pygame2.base

The pygame2.base C API contains fundamental core objects and functions used throughout nearly all pygame2 modules. As such, it should be considered to be imported in the first place in all C extensions for pygame2.

Import

Include headers:

pygame2/pgbase.h
int import_pygame2_base(void)
Imports the pygame2.base module. This returns 0 on success and -1 on failure.

Basic Types

For platform and system environment compatibility, pygame2.base defines a small set of own types to be used for most of its functions.

pgbyte
An unsigned 8-bit integer type. It is guaranteed to have at least 8 bits.
pguint16
pgint16
Signed and unsigned 16-bit integer types. They are guaranteed to have at least 16 bits.
pguint32
pgint32
Signed and unsigned 32-bit integer types. They are guaranteed to have at least 32 bits.
CRect

A simple structure defining a rectangular area. It carries the following members:

pgint16 CRect.x
The topleft x coordinate of the CRect.
pgint16 CRect.y
The topleft y coordinate of the CRect.
pguint16 CRect.w
The width of the CRect.
pguint16 CRect.h
The height of the CRect.

Macros

In addition to the types, a set of helpful macros was established, which are used heavily and should be relied on wherever possible.

MIN(x, y)
Gets the smaller of two values. The own implementation will only be used, if no system-specific one was found.
MAX(x, y)
Gets the larger of two values. The own implementation will only be used, if no system-specific one was found.
ABS(x)
Gets the absolute value. The own implementation will be only used, if no system-specific one was found.
trunc(x)
Truncates a floating point value. The own implementation will only be used, if no system-specific one was found.
round(x)
Rounds a floating point value to the nearest integer. The own implementation will only be used, if no system-specific one was found.
CLAMP(x, low, high)
Checks, whether x is within the boundaries of low and high and returns it. If x is not within the boundaries, either low or high will be returned, depending on which of them is larger. The own implementation will only be used, if no system-specific one was found.
M_PI
The pi constant with 31 digits. The own definition will only be used, if no system-specific one was found.
DEG2RAD(x)
Converts degrees to radians. The own implementation will only be used, if no system-specific one was found.
RAD2DEG(x)
Converts radians to degrees. The own implementation will only be used, if no system-specific one was found.
ADD_LIMIT(x, y, lower, upper)
SUB_LIMIT(x, y, lower, upper)
Adds and subtracts two values, but guarantees that the result will not be smaller or larger than the lower and upper limits.
INT_ADD_LIMIT(x, y)
INT_SUB_LIMIT(x, y)
INT16_ADD_LIMIT(x, y)
INT16_SUB_LIMIT(x, y)
Adds and subtracts two integer values, but guarantees that the result will not be smaller or larger than the INT_MIN and INT_MAX limits.
UINT_ADD_LIMIT(x, y)
UINT_SUB_LIMIT(x, y)
UINT16_ADD_LIMIT(x, y)
UINT16_SUB_LIMIT(x, y)
Adds and subtracts two unsigned integer values, but guarantees that the result will not be smaller or larger than zero and UINT_MAX.
LONG_ADD_LIMIT(x, y)
LONG_SUB_LIMIT(x, y)
INT32_ADD_LIMIT(x, y)
INT32_SUB_LIMIT(x, y)
Adds and subtracts two long integer values, but guarantees that the result will not be smaller or larger than the LONG_MIN and LONG_MAX limits.
ULONG_ADD_LIMIT(x, y)
ULONG_SUB_LIMIT(x, y)
UINT32_ADD_LIMIT(x, y)
UINT32_SUB_LIMIT(x, y)
Adds and subtracts two unsigned long integer values, but guarantees that the result will not be smaller or larger than zero and ULONG_MAX.
DBL_ADD_LIMIT(x, y)
DBL_SUB_LIMIT(x, y)
Adds and subtracts two floating point values, but guarantees that the result will not be smaller or larger than the DBL_MIN and DBL_MAX limits.
INT_ADD_UINT_LIMIT(x, y, z)
INT_SUB_UINT_LIMIT(x, y, z)
INT16_ADD_UINT16_LIMIT(x, y, z)
INT16_SUB_UINT16_LIMIT(x, y, z)
Adds and subtracts an unsigned integer y to an integer x and stores the result in the integer z. If the operation will exceed the INT_MIN and INT_MAX limits, z will be set to INT_MIN or *INT_MAX.

Errors

PyObject* PyExc_PyGameError
The internally used pygame2.base.Error exception class.

Functions

int DoubleFromObj(PyObject* obj, double *val)
Tries to convert the PyObject to a double and stores the result in val, if successful. This returns 1 on success and 0 on failure.
int IntFromObj(PyObject* obj, int *val)
Tries to convert the PyObject to an int and stores the result in val, if successful. This returns 1 on success and 0 on failure.
int UintFromObj(PyObject* obj, unsigned int *val)
Tries to convert the PyObject to an unsigned int and stores the result in val, if successful. This returns 1 on success and 0 on failure.
int DoubleFromSeqIndex(PyObject *seq, Py_ssize_t index, double *val)
Tries to get the item at the desired index from the passed sequence object and converts it to a double, which will be stored in val. This returns 1 on success and 0 on failure.
int IntFromSeqIndex(PyObject *seq, Py_ssize_t index, int *val)
Tries to get the item at the desired index from the passed sequence object and converts it to an int, which will be stored in val. This returns 1 on success and 0 on failure.
int UintFromSeqIndex(PyObject *seq, Py_ssize_t index, unsigned int *val)
Tries to get the item at the desired index from the passed sequence object and converts it to an unsigned int, which will be stored in val. This returns 1 on success and 0 on failure.
int PointFromObject(PyObject *obj, int *x, int *y)
Tries to get two int values from the passed object. If the object is a PyRect or PyFRect, the topleft x and y values are taken, if the object is a sequence type, the first two items are used. This returns 1 on success and 0 on failure.
int SizeFromObject(PyObject *obj, pgint32 *x, pgint32 *y)
Tries to get two pgint32 values from the passed object. If the object is a PyRect or PyFRect, the width and height values are taken, if the object is a sequence type, the first two items are used. This returns 1 on success and 0 on failure.
int FPointFromObject(PyObject *obj, double *x, double *y)
Tries to get two double values from the passed object. If the object is a PyRect or PyFRect, the topleft x and y values are taken, if the object is a sequence type, the first two items are used. This returns 1 on success and 0 on failure.
int FSizeFromObject(PyObject *obj, double *x, double *y)
Tries to get two double values from the passed object. If the object is a PyRect or PyFRect, the width and height values are taken, if the object is a sequence type, the first two items are used. This returns 1 on success and 0 on failure.
int ASCIIFromObject(PyObject *obj, char** text, PyObject **convobj)
Tries to get ASCII text from the passed object and stores the result in text. If the object has to be converted, the conversion result will be stored in convobj and needs to be freed by the caller, once text is not required anymore. This returns 1 on success and 0 on failure.
int UTF8FromObject(PyObject *obj, char** text, PyObject **convobj)
Tries to get UTF-8 encoded text from the passed object and stores the result in text. If the object has to be converted, the conversion result will be stored in convobj and needs to be freed by the caller, once text is not required anymore. This returns 1 on success and 0 on failure.

PyColor

PyColor
PyColor_Type

The PyColor object is suitable for storing RGBA color values that feature a 8-bit resolution range for each channel (allowing it to represent a 24/32-bit color depth).

Members

pgbyte PyColor.r
The red color part value.
pgbyte PyColor.g
The green color part value.
pgbyte PyColor.b
The blue color part value.
pgbyte PyColor.a
The alpha transparency value.

Functions

int PyColor_Check(PyObject *obj)
Returns true, if the argument is a PyColor or a subclass of PyColor.
PyObject* PyColor_New(pgbyte rgba[])
Creates a new PyColor object from the passed 4-value RGBA array. On failure, this returns NULL.
PyObject* PyColor_NewFromNumber(pguint32 rgba)
Creates a new PyColor object from the passed pguint32. On failure, this returns NULL.
PyObject* PyColor_NewFromRGBA(pgbyte r, pgbyte g, pgbyte b, pgbyte a)
Creates a new PyColor object from the passed four RGBA values. On failure, this returns NULL.
pguint32 PyColor_AsNumber(PyObject *color)
Returns the 32-bit ARGB integer representation of the PyColor object. On failure, this returns 0. As 0 might be a valid color, you should check for an error explicitly using PyErr_Occured().

PyRect

PyRect
PyRect_Type

The PyRect object defines a rectangular area for arbitrary usage. It features the most typical operations, but is - due to its integer resolution - limited in some usage scenarios.

Members

pgint16 PyRect.x
The topleft x coordinate of the PyRect.
pgint16 PyRect.y
The topleft y coordinate of the PyRect.
pguint16 PyRect.w
The width of the PyRect.
pguint16 PyRect.h
The height of the PyRect.

Functions

int PyRect_Check(PyObject *obj)
Returns true, if the argument is a PyRect or a subclass of PyRect.
PyObject* PyRect_New(pgint16 x, pgint16 y, pguint16 w, pguint16 h)
Creates a new PyRect object from the passed four values. On failure, this returns NULL.

PyFRect

PyFRect
PyFRect_Type

The PyFRect object defines a rectangular area for arbitrary usage and a high floating point resolution. It features the most typical operations required by most applications.

Members

double PyFRect.x
The topleft x coordinate of the PyFRect.
double PyFRect.y
The topleft y coordinate of the PyFRect.
double PyFRect.w
The width of the PyFRect.
double PyFRect.h
The height of the PyFRect.

Functions

int PyFRect_Check(PyObject *obj)
Returns true, if the argument is a PyFRect or a subclass of PyFRect.
PyObject* PyFRect_New(double x, double y, double w, double h)
Creates a new PyFRect object from the passed four values. On failure, this returns NULL.

PyBufferProxy

PyBufferProxy
PyBufferProxy_Type

The PyBufferProxy object is a transparent proxy class for buffer-like access. It supports the Python 2.x and 3.x buffer APIs, automatic unlock hooks for the buffer object and read/write access to the buffer contents.

Members

void* PyBufferProxy.buffer
A pointer to the underlying C buffer contents.
Py_ssize_t PyBufferProxy.length
The length of the buffer in bytes
bufferunlock_func PyBufferProxy.unlock_func

The unlock function callback hook. bufferunlock_func is defined as:

int (*bufferunlock_func)(PyObject* object, PyObject* buffer)

Functions

int PyBufferProxy_Check(PyObject *obj)
Returns true, if the argument is a PyBufferProxy or a subclass of PyBufferProxy.
void* PyBufferProxy_AsBuffer(PyObject *obj)

Macro for accessing the buffer member of the PyBufferProxy.

This does not perform any type or argument checks.

PyObject* PyBufferProxy_New(PyObject *object, void *buffer, Py_ssize_t length, bufferunlock_func func)
Creates a new PyBufferProxy object from the passed PyObject. buffer must be the buffer to refer to for read and write operations, length the maximum length in bytes that is safe to write to the buffer. func is the unlock func to release any pending locks and references on the buffered object. On failure, this returns NULL.

PyFont

PyFont
PyFont_Type

The PyFont object an abstract base class, to be used by inheriting classes and other interfaces, so it is guaranteed that font-like objects contain a set of same attributes and methods.

Members

PyFont only defines a set of function pointer bindings to access and set by inheriting classes and interfaces. Those are

PyObject* (*get_height)(PyObject *self, void *closure)
Gets the height of the PyFont instance. self is the PyFont itself, the closure argument is the same as for the Python C API getter definition.
PyObject* (*get_name)(PyObject *self, void *closure)
Gets the name of the PyFont instance. self is the PyFont itself, the closure argument is the same as for the Python C API getter definition.
PyObject* (*get_style)(PyObject *self, void *closure)
Gets the currently applied style of the PyFont instance. self is the PyFont itself, the closure argument is the same as for the Python C API getter definition.
int (*set_style)(PyObject *self, PyObject *attr, void *closure)
Applies a style to the PyFont instance. self is the PyFont itself, attr the style to apply, the closure argument is the same as for the Python C API getter definition.
PyObject* (*get_size)(PyObject *self, PyObject *args, PyObject *kwds)
Gets the size of the PyFont instance. self is the PyFont itself, the closure argument is the same as for the Python C API getter definition.
PyObject* (*render)(PyObject *self, PyObject *args, PyObject *kwds)
Renders the PyFont onto some PySurface or whatever is appropriate for the concrete implementation. self is the PyFont itself, the args and kwds arguments are the same as for the Python C API method definition.
PyObject* (*copy) (PyObject *self);
Creates an exact copy of the PyFont. self is the PyFont itself.

Functions

int PyFont_Check(PyObject *obj)
Returns true, if the argument is a PyFont or a subclass of PyFont.
PyObject* PyFont_New(void)
Creates a new, empty PyFont object, which’s members are set to NULL. On failure, this returns NULL.

PySurface

PySurface
PySurface_Type

The PySurface object an abstract base class, to be used by inheriting classes and other interfaces, so it is guaranteed that surface-like objects contain a set of same attributes and methods.

Members

PySurface only defines a set of function pointer bindings to access and set by inheriting classes and interfaces. Those are

PyObject* (*get_width)(PyObject *self, void *closure)
Gets the width of the PySurface instance. self is the PySurface itself, the closure argument is the same as for the Python C API getter definition.
PyObject* (*get_height)(PyObject *self, void *closure)
Gets the height of the PySurface instance. self is the PySurface itself, the closure argument is the same as for the Python C API getter definition.
PyObject* (*get_size)(PyObject *self, void *closure)
Gets the size of the PySurface instance. self is the PySurface itself, the closure argument is the same as for the Python C API getter definition.
PyObject* (*get_pixels)(PyObject *self, void *closure)
Gets the raw pixels of the PySurface instance. self is the PySurface itself, the closure argument is the same as for the Python C API getter definition.
PyObject* (*blit)(PyObject *self, PyObject *args, PyObject *kwds)
Blits the PySurface onto some other PySurface or whatever is appropriate for the concrete implementation. self is the PySurface itself, the args and kwds arguments are the same as for the Python C API method definition.
PyObject* (*copy)(PyObject *self)
Creates an exact copy of the PySurface. self is the PySurface itself.

Functions

int PySurface_Check(PyObject *obj)
Returns true, if the argument is a PySurface or a subclass of PySurface.
PyObject* PySurface_New(void)
Creates a new, empty PySurface object, which’s members are set to NULL. On failure, this returns NULL.