docs/reference/glk-api-conventions.sgml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 ]>
   5 <refentry id="chimara-Other-API-Conventions">
   6 <refmeta>
   7 <refentrytitle>Other API Conventions</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>CHIMARA Library</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>Other API Conventions</refname>
  13 <refpurpose>General information about the Glk API</refpurpose>
  14 </refnamediv>
  15 <refsect1>
  16 <title>Description</title>
  17 <para>
  18 The <filename class="headerfile">glk.h</filename> 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 <quote><type>long</type></quote> or <quote><type>int</type></quote> or some other C definition.
  19 </para>
  20 <para>
  21 Note that all constants are &num;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.
  22 </para>
  23 <para>
  24 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.
  25 </para>
  26 <para>
  27 %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.
  28 </para>
  29 <para>
  30 Some functions have pointer arguments, acting as <quote>variable</quote> or <quote>reference</quote> 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.
  31 </para>
  32 </refsect1>
  33 </refentry>