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:
-
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).
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.
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.