git.cworth.org Git - apitrace/blob - specs/scripts/README.markdown

   1 This directory contains several helper scripts that facilitate the generation
   2 of the API descriptions from specs and/or header files.
   3
   4 The specs/headers are not expressive enough, which is why we can't just code
   5 generate everything from them directly.  However the scripts in this directory
   6 usually get 90% of the work done automatically.
   7
   8
   9 OpenGL
  10 ======
  11
  12 For OpenGL the typical procedure is to run
  13
  14     make -B
  15
  16 which will generate several python scripts with prototypes and defines from the
  17 Khronos `.spec` files:
  18
  19 * glapi.py
  20
  21 * glparams.py
  22
  23 * glxapi.py
  24
  25 * wglapi.py
  26
  27 * wglenum.py
  28
  29 and then manually crossport new functions / enums to the identically named
  30 files in the parent dir via a side-by-side diff tool, such as gvimdiff.
  31
  32
  33 OpenGL ES
  34 =========
  35
  36 Khronos doesn't provide `.spec` files for OpenGL ES.  But the `gltxt.py` script
  37 can extract and convert prototypes for the `.txt` extension specifications:
  38
  39     $ ./gltxt.py http://www.khronos.org/registry/gles/extensions/OES/OES_mapbuffer.txt
  40         # GL_OES_mapbuffer
  41         GlFunction(Void, "glGetBufferPointervOES", [(GLenum, "target"), (GLenum, "pname"), (OpaquePointer(OpaquePointer(Void)), "params")], sideeffects=False),
  42         GlFunction(OpaquePointer(Void), "glMapBufferOES", [(GLenum, "target"), (GLenum, "access")]),
  43         GlFunction(GLboolean, "glUnmapBufferOES", [(GLenum, "target")]),
  44
  45
  46 Generic
  47 =======
  48
  49 When the domain specific scripts don't work the fallback solution is `cdecl.py`, which can parse most C declarations:
  50
  51     $ echo 'void *memcpy(void *dest, const void *src, size_t n);' | ./cdecl.py
  52         Function(OpaquePointer(Void), "memcpy", [(OpaquePointer(Void), "dest"), (OpaquePointer(Const(Void)), "src"), (size_t, "n")]),
  53
  54