X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=docs%2Freference%2Fglk-api-conventions.sgml;fp=docs%2Freference%2Fglk-api-conventions.sgml;h=b6f68719046f58730f30d81eabf3351069e24d5c;hb=f19a194bd066ea4320c1c6b6b8c5a375f7787af5;hp=e796e5217f54c612e633d027c223f295e34a6f19;hpb=2da183ac47f1157560dcd2c417f7f6a24ae72352;p=projects%2Fchimara%2Fchimara.git diff --git a/docs/reference/glk-api-conventions.sgml b/docs/reference/glk-api-conventions.sgml index e796e52..b6f6871 100644 --- a/docs/reference/glk-api-conventions.sgml +++ b/docs/reference/glk-api-conventions.sgml @@ -18,19 +18,16 @@ The glk.h header file is the same on all platforms, with the sole exception of the typedef of #glui32 and #glsi32. These will always be defined as 32-bit unsigned and signed integer types, which may be long or int or some other C definition. -Note that all constants are #defines, and all functions are actual function declarations (as opposed to macros.) +Note that all constants are #defines. All functions are currently actual function declarations (as opposed to macros), but this may change in future Glk revisions. As in the standard C library, if Glk function is defined by a macro, an actual function of the same name will also be available. - -There are a few places where macros would be more efficient — glk_gestalt() and glk_gestalt_ext(), for example — but they are not likely to be CPU bottlenecks, and clarity seems more important. - -%FALSE is 0; %TRUE is 1. %NULL is also 0. +Functions that return or generate boolean values will produce only 0 (%FALSE) or 1 (%TRUE). Functions that accept boolean arguments will accept any value, with zero indicating %FALSE and nonzero indicating %TRUE. -As stated above, it is illegal to pass %NULL to a function which is expecting a valid object reference, unless the function definition says otherwise. +%NULL (when used in this document) refers to the C null pointer. As stated above, it is illegal to pass %NULL to a function which is expecting a valid object reference, unless the function definition says otherwise. -Some functions have pointer arguments, acting as variable or reference arguments; the function's intent is to return some value in the space pointed to by the argument. Unless the function says otherwise, it is legal to pass a %NULL pointer to indicate that you do not care about that value. +Some functions have pointer arguments, acting as variable or reference arguments; the function's intent is to return some value in the space pointed to by the argument. Unless the function says otherwise, it is legal to pass %NULL to indicate that you do not care about that value.