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.
-
PRAGMA(q)
#pragma handler for usage within C macros.
PRAGMA(some simple pragma)
will be expanded depending on the compiler to something like
__pragma(some simple pragma) /* Visual C++ */
_Pragma("some simple pragma") /* GCC */
which in turn will be expanded to the default #pragma directive for
the compiler.
-
MIN(q, v)
- Gets the smaller of two values. The own implementation will only be used,
if no system-specific one was found.
-
MAX(q, v)
- Gets the larger of two values. The own implementation will only be used,
if no system-specific one was found.
-
ABS(q)
- Gets the absolute value. The own implementation will be only used,
if no system-specific one was found.
-
trunc(q)
- Truncates a floating point value. The own implementation will only be used,
if no system-specific one was found.
-
round(q)
- Rounds a floating point value to the nearest integer. The own implementation
will only be used, if no system-specific one was found.
-
CLAMP(q, low, high)
- Checks, whether q is within the boundaries of low and high and returns
it. If q 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(q)
- Converts degrees to radians. The own implementation will only be used, if no
system-specific one was found.
-
RAD2DEG(q)
- Converts radians to degrees. The own implementation will only be used, if no
system-specific one was found.
-
ARGB_2_RGBA(q)
- Converts a 32-bit unsigned integer value from an 0xAARRGGBB layout to
a 32-bit unsigned integer value using an 0xRRGGBBAA layout.
-
RGBA_2_ARGB(q)
- Converts a 32-bit unsigned integer value from an 0xRRGGBBAA layout to
a 32-bit unsigned integer value using an 0xAARRGGBB layout.
-
ADD_LIMIT(q, v, lower, upper)
-
SUB_LIMIT(q, v, 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(q, v)
-
INT_SUB_LIMIT(q, v)
-
INT16_ADD_LIMIT(q, v)
-
INT16_SUB_LIMIT(q, v)
- 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(q, v)
-
UINT_SUB_LIMIT(q, v)
-
UINT16_ADD_LIMIT(q, v)
-
UINT16_SUB_LIMIT(q, v)
- 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(q, v)
-
LONG_SUB_LIMIT(q, v)
-
INT32_ADD_LIMIT(q, v)
-
INT32_SUB_LIMIT(q, v)
- 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(q, v)
-
ULONG_SUB_LIMIT(q, v)
-
UINT32_ADD_LIMIT(q, v)
-
UINT32_SUB_LIMIT(q, v)
- 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(q, v)
-
DBL_SUB_LIMIT(q, v)
- 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(q, v, t)
-
INT_SUB_UINT_LIMIT(q, v, t)
-
INT16_ADD_UINT16_LIMIT(q, v, t)
-
INT16_SUB_UINT16_LIMIT(q, v, t)
- Adds and subtracts an unsigned integer v to an integer q and stores the
result in the integer t. If the operation will exceed the INT_MIN and
INT_MAX limits, t will be set to INT_MIN or *INT_MAX.
Errors
-
PyObject* PyExc_PyGameError
- The internally used pygame2.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 LongFromObj(PyObject* obj, long *val)
- Tries to convert the PyObject to a long and stores the result in val, if
successful. This returns 1 on success and 0 on failure.
-
int UlongFromObj(PyObject* obj, unsigned long *val)
- Tries to convert the PyObject to an unsigned long 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 PointFromObj(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 SizeFromObj(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 FPointFromObj(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 FSizeFromObj(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 ASCIIFromObj(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 UTF8FromObj(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.
-
int ColorFromObj(PyObject *obj, pguint32 *val)
- Converts the passed object to a 32-bit unsigned integer color value
using a RGBA layout and stores the result in val. This returns 1 on
success and 0 on failure.
-
int IsReadableStreamObj(PyObject *obj)
- Checks, whether the passed object supports the most important stream
operation for reading data, such as read, seek and tell.
This returns 1 on success and 0 on failure.
-
int IsWriteableStreamObj(PyObject *obj)
- Checks, whether the passed object supports the most important stream
operation for writing data, such as write, seek and tell.
This returns 1 on success and 0 on failure.
-
int IsReadWriteableStreamObj(PyObject *obj)
- Checks, whether the passed object supports the most important stream
operation for reading and writing data, such as read, write,
seek and tell. 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 is 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.
CPyStreamWrapper
-
CPyStreamWrapper
CPyStreamWrapper is a C API only class type for reading and writing
Python stream objects in a threaded or non-threaded manner. It
encapsules the important underlying stream methods.
Note
The C functions provided below do not perform any argument
checks. It is up to the caller to ensure that the passed
CPyStreamWrapper argument is correct.
Members
-
PyObject* CPyStreamWrapper.read
- The method pointer to the underlying Python object’s read method.
This will be NULL, if the Python object does not support read access.
-
PyObject* CPyStreamWrapper.write
- The method pointer to the underlying Python object’s write method.
This will be NULL, if the Python object does not support write access.
-
PyObject* CPyStreamWrapper.seek
- The method pointer to the underlying Python object’s seek method.
This will be NULL, if the Python object does not support seeking the
stream.
-
PyObject* CPyStreamWrapper.tell
- The method pointer to the underlying Python object’s tell method.
This will be NULL, if the Python object does not support seeking the
stream.
-
PyObject* CPyStreamWrapper.close
- The method pointer to the underlying Python object’s close method.
This will be NULL, if the Python object does not support closing the
stream.
-
PyThreadState* CPyStreamWrapper.thread
- If Python was built with thread support, this will contain the
preserved Python thread state to allow concurrent external threads
to access the interpreter state and perform stream operations on the
underlying Python object.
Functions
-
CPyStreamWrapper* CPyStreamWrapper_New(PyObject *obj)
Creates a new CPyStreamWrapper object encapsuling the passed
obj. This will not perform any checks, whether the obj actually is
a stream-like object and supports all required methods. If it is not a
stream-like object or does not implement the methods, the according
CPyStreamWrapper members will be NULL.
Use IsReadableStreamObj(), IsWriteableStreamObj() or
IsReadWritebbleStreamObj() beforehand, to check whether obj
implements all wanted methods.
On failure, this returns NULL.
-
CPyStreamWrapper_Free(CPyStreamWrapper *wrapper)
- Releases all resources hold by the passed CPyStreamWrapper
instance.
-
CPyStreamWrapper_Clone(CPyStreamWrapper *wrapper)
- Creates a copy of the passed CPyStreamWrapper instance, which
uses the same bound methods for reading and writing.
-
int CPyStreamWrapper_Read_Threaded(CPyStreamWrapper *wrapper, void *buf, pguint32 offset, pguint32 count, pguint32 *read_)
Reads a maximum of count bytes from the passed
CPyStreamWrapper, starting at offset. The read data will be
stored in buf, which must be large enough to hold the data. The
amount of bytes actually written to buf will be stored in read_.
If offset is 0, the stream will not be repositioned. Otherwise,
offset denotes a position relative to the start of the stream.
Returns 1 on succes and 0 on failure.
This will swap the Python interpreter thread state to gain access to
the underlying Python stream object. It should not be called from
within the same interpreter thread, as it locks the interpreter stat
(and thus itself).
-
int CPyStreamWrapper_Read(CPyStreamWrapper *wrapper, void *buf, pguint32 offset, pguint32 count, pguint32 *read_)
- Same as CPyStreamWrapper_Read_Threaded(), but this will not
swap the thread state of the Python interpreter and thus is safe
to be called from within the interpreter thread.
-
int CPyStreamWrapper_Write_Threaded(CPyStreamWrapper *wrapper, const void *buf, pguint32 num, pguint32 size, pguint32 *written)
Writes at least num elements of size size from the passed buf to
the stream of the passed CPyStreamWrapper. The actual amount
of written elements will be stored in written.
This will swap the Python interpreter thread state to gain access to
the underlying Python stream object. It should not be called from
within the same interpreter thread, as it locks the interpreter stat
(and thus itself).
-
int CPyStreamWrapper_Write(CPyStreamWrapper *wrapper, const void *buf, pguint32 num, pguint32 size, pguint32 *written)
- Same as CPyStreamWrapper_Write_Threaded(), but this will not
swap the thread state of the Python interpreter and thus is safe
to be called from within the interpreter thread.
-
int CPyStreamWrapper_Seek_Threaded(CPyStreamWrapper *wrapper, pgint32 offset, int whence)
Moves to a new stream position. offset is the position in
bytes. whence indicates, how the movement should be performed and
can be a valid value of
- SEEK_SET - offset is relative to the start of the stream
- SEEK_CUR - offset is relative to the current stream position
- SEEK_END - offset is relative to the end of the stream.
Note
Seeking beyond the end of the stream boundaries might result in an
undefined behaviour.
Returns 1 on succes and 0 on failure.
This will swap the Python interpreter thread state to gain access to
the underlying Python stream object. It should not be called from
within the same interpreter thread, as it locks the interpreter stat
(and thus itself).
-
int CPyStreamWrapper_Seek(CPyStreamWrapper *wrapper, pgint32 offset, int whence)
- Same as CPyStreamWrapper_Seek_Threaded(), but this will not
swap the thread state of the Python interpreter and thus is safe
to be called from within the interpreter thread.
-
pgint32 CPyStreamWrapper_Tell_Threaded(CPyStreamWrapper *wrapper)
Returns the current stream position or -1 if an error occured.
This will swap the Python interpreter thread state to gain access to
the underlying Python stream object. It should not be called from
within the same interpreter thread, as it locks the interpreter stat
(and thus itself).
-
pgint32 CPyStreamWrapper_Tell(CPyStreamWrapper *wrapper)
- Same as CPyStreamWrapper_Tell_Threaded(), but this will not
swap the thread state of the Python interpreter and thus is safe
to be called from within the interpreter thread.
-
int CPyStreamWrapper_Close_Threaded(CPyStreamWrapper *wrapper)
Closes the underlying stream. This leaves the wrapper itself intact.
Returns 1 on success and 0 on failure.
This will swap the Python interpreter thread state to gain access to
the underlying Python stream object. It should not be called from
within the same interpreter thread, as it locks the interpreter stat
(and thus itself).
-
int CPyStreamWrapper_Close(CPyStreamWrapper *wrapper)
- Same as CPyStreamWrapper_Close_Threaded(), but this will not
swap the thread state of the Python interpreter and thus is safe
to be called from within the interpreter thread.