]> git.cworth.org Git - apitrace/blob - specs/scripts/README.markdown
trim: Fix short command-line option -a for "apitrace trim"
[apitrace] / 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