Source

pygame / doc / MODULE_FAQ.txt

marcus 13d1988 


marcus 5388d03 
marcus 5e789c3 

marcus a2d9a07 






marcus 5e789c3 
marcus 57a302e 



marcus 13d1988 
marcus 0b36150 
marcus 13d1988 


marcus a2d9a07 
marcus 0b36150 
marcus 13d1988 


marcus 57a302e 
marcus 3b4ffe4 
marcus 5e789c3 
marcus 13d1988 
















marcus 8625d94 
marcus 13d1988 
marcus 3b4ffe4 




marcus 5e789c3 
marcus 6fdef59 
marcus 5e789c3 
marcus 5388d03 




























marcus 13d1988 

marcus 57a302e 





marcus 13d1988 

marcus 57a302e 





marcus 13d1988 

marcus 5e789c3 




marcus 13d1988 

marcus 5e789c3 



marcus 13d1988 

marcus 3b4ffe4 
marcus 5e789c3 



marcus 13d1988 

marcus 5e789c3 
============
C Module FAQ
============

The C API contains numerous macros and functions that ease the
developer's life. In order to have a similar behaviour without
implementing the same things again and again, the most important ones will be
listed here.

.. note::

   For a full list of macros, utility functiona and C API interfaces, it is 
   *strongly* recommended to read the :ref:`capi`.

If it is necessary to rely on certain features specific to a particular
environment, you can check for the build system flags, which are automatically
added at compile time. Currently, the following flags and macros are available:

  +-----------+----------------------------------------+
  | IS_WIN32  | Win32 build with Visual C++            |
  +-----------+----------------------------------------+
  | IS_MSYS   | (Win32) Msys build with GCC            |
  +-----------+----------------------------------------+
  | IS_DARWIN | MacOS X and Darwin-based platforms     |
  +-----------+----------------------------------------+
  | IS_UNIX   | Any other build platform that          |
  |           | successfully passes the preparations   |
  +-----------+----------------------------------------+

base/pgdefines.h contains some useful numeric macros:

  +----------------+--------------------------------------------+
  | MIN(x,y)       | Returns the minimum of two values          |
  +----------------+--------------------------------------------+
  | MAX(x,y)       | Returns the maximum of two values          |
  +----------------+--------------------------------------------+
  | ABS(x)         | Returns the absolute value                 |
  +----------------+--------------------------------------------+
  | trunc(x)       | Truncates a number                         |
  +----------------+--------------------------------------------+
  | round(x)       | Rounds a number                            |
  +----------------+--------------------------------------------+
  | DEG2RAD(x)     | Converts degrees to radians                |
  +----------------+--------------------------------------------+
  | DEG2RAD(x)     | Converts radians to degrees                |    
  +----------------+--------------------------------------------+
  | ADD_LIMIT(x,y) | Variable addition using overflow limits    |
  +----------------+--------------------------------------------+
  | SUB_LIMIT(x,y) | variable subtraction using overflow limits |
  +----------------+--------------------------------------------+

Besides that it contains various ready-to-use macros for signed/unsigned
integer and double additions and subtractions with overflow checking.

Additionally base/pgbase.h contains several functions to get an integer
or floating point value from a PyObject. Those however require other
modules to import the base module.

.. note::
  
   **Never** do an ``#include <Python.h>`` in your code directly. We are
   using ``PY_SSIZE_T_CLEAN`` along with a set of compatibility
   macros. To have correct includes, use ``#include "pgcompat.h``
   instead.

Buffer Sizes and Offset Access
------------------------------
Since Python 2.5, the **Py_ssize_t** type is available, which can (and
should) be used for numerical sizing arguments. Python 2.4 does not know
this type however and also cannot handle the ``n`` argument in
``PyArg_ParseTuple``.

To come around this issue, do something like the following in the code: ::

  Py_ssize_t offset;
  Py_ssize_t length;
  char *buf;

  #ifdef IS_PYTHON_24
    if (!PyArg_ParseTuple (args, "s#i", &buf, &length, &offset))
        return NULL;
  #else
    if (!PyArg_ParseTuple (args, "s#n", &buf, &length, &offset))
        return NULL;
  #endif


Text Handling
-------------
For text guaranteed to be UTF-8 or ASCII, use the related Text_***() macros
instead of the specific PyUnicode/PyString APIs. The Text_***() macros assure
that for each Python version the current API is used.
For other objects that contain text (but not necessarily UTF-8 or ASCII), use 
the UTF8FromObject() and ASCIIFromObject() conversion functions.

Sizes And Points
----------------
Whereever typical two-value tuples for denoting points or sizes are necessary
or used, use the [F]PointFromObject() and [F]SizeFromObject() functions from 
base/pgbase.h. Those guarantee interoperability with rectangular arguments,
tuples, lists and any other sequence and take care of the most basic value
checks.

SDL Rectangles
--------------
sdl/pgsdl.h defines some handy routines to quickly get a SDL_Rect from
the base.Rect and base.FRect classes, SDLRect_FromRect(). Use it
wherever methods require a rectangular object. IsValidRect() checks only,
whether the passed argument is a base.Rect or base.FRect.

SDL Surface Pixel Manipulation
------------------------------
sdl/surface.h contains tons of macros to manipulate surface pixels. It
should be your first address to look for a matching operation whenever
you need it.

SDL Color Handling
------------------
The Color class uses an ARGB layout for PyColor_AsNumber(). In order to
prepare this value for color operations within the SDL functions or
pixel manipulations, use the RGB2FORMAT() and ARGB2FORMAT() macros,
defined in sdl/surface.h.

SDL Subsystems
--------------
Whenever you require a certain subsystem to be available, use the
corresponding ASSERT_***_INIT() macro from sdl/pgsdl.h.