.. include:: ../common.txt

.. highlight:: c

******************************************
  High level API exported by pygame.base
******************************************

src_c/base.c
============

This extension module defines general purpose routines for starting and stopping
SDL as well as various conversion routines uses elsewhere in pygame.

C header: src_c/include/pygame.h

.. c:var:: PyObject* pgExc_SDLError

   This is :py:exc:`pygame.error`, the exception type used to raise SDL errors.

.. c:function:: int pg_mod_autoinit(const char* modname)

   Inits a pygame module, which has the name ``modname``
   Return ``1`` on success, ``0`` on error, with python
   error set.

.. c:function:: void pg_mod_autoquit(const char* modname)

   Quits a pygame module, which has the name ``modname``

.. c:function:: void pg_RegisterQuit(void (*f)(void))

   Register function *f* as a callback on Pygame termination.
   Multiple functions can be registered.
   Functions are called in the reverse order they were registered.

.. c:function:: int pg_IntFromObj(PyObject *obj, int *val)

   Convert number like object *obj* to C int and place in argument *val*.
   Return ``1`` on success, else ``0``.
   No Python exceptions are raised.

.. c:function:: int pg_IntFromObjIndex(PyObject *obj, int index, int *val)

   Convert number like object at position *i* in sequence *obj*
   to C int and place in argument *val*.
   Return ``1`` on success, else raise a Python exception and return ``0``.

.. c:function:: int pg_TwoIntsFromObj(PyObject *obj, int *val1, int *v2)

   Convert the two number like objects in length 2 sequence *obj*
   to C int and place in arguments *val1* and *val2* respectively.
   Return ``1`` on success, else raise a Python exception and return ``0``.

.. c:function:: int pg_FloatFromObj(PyObject *obj, float *val)

   Convert number like object *obj* to C float and place in argument *val*.
   Returns ``1`` on success, ``0`` on failure.
   No Python exceptions are raised.


.. c:function:: int pg_FloatFromObjIndex(PyObject *obj, int index, float *val)

   Convert number like object at position *i* in sequence *obj*
   to C float and place in argument *val*.
   Return ``1`` on success, else raise a Python exception and return ``0``.

.. c:function:: int pg_TwoFloatsFromObj(PyObject *obj, float *val1, float *val2)

   Convert the two number like objects in length 2 sequence *obj*
   to C float and place in arguments *val1* and *val2* respectively.
   Return ``1`` on success, else raise a Python exception and return ``0``.

.. c:function:: int pg_UintFromObj(PyObject *obj, Uint32 *val)

   Convert number like object *obj* to unsigned 32 bit integer and place
   in argument *val*.
   Return ``1`` on success, else ``0``.
   No Python exceptions are raised.

.. c:function:: int pg_UintFromObjIndex(PyObject *obj, int _index, Uint32 *val)

   Convert number like object at position *i* in sequence *obj*
   to unsigned 32 bit integer and place in argument *val*.
   Return ``1`` on success, else raise a Python exception and return ``0``.

.. c:function:: int pg_RGBAFromObj(PyObject *obj, Uint8 *RGBA)

   Convert the color represented by object *obj* into a red, green, blue, alpha
   length 4 C array *RGBA*.
   The object must be a length 3 or 4 sequence of numbers having values
   between 0 and 255 inclusive.
   For a length 3 sequence an alpha value of 255 is assumed.
   Return ``1`` on success, ``0`` otherwise.
   No Python exceptions are raised.

.. c:type:: pg_buffer

   .. c:member:: Py_buffer view

      A standard buffer description

   .. c:member:: PyObject* consumer

      The object holding the buffer

   .. c:member:: pybuffer_releaseproc release_buffer

      A buffer release callback.

.. c:var:: PyObject *pgExc_BufferError

   Python exception type raised for any pg_buffer related errors.

.. c:function:: PyObject* pgBuffer_AsArrayInterface(Py_buffer *view_p)

   Return a Python array interface object representation of buffer *view_p*.
   On failure raise a Python exception and return *NULL*.

.. c:function:: PyObject* pgBuffer_AsArrayStruct(Py_buffer *view_p)

   Return a Python array struct object representation of buffer *view_p*.
   On failure raise a Python exception and return *NULL*.

.. c:function:: int pgObject_GetBuffer(PyObject *obj, pg_buffer *pg_view_p, int flags)

   Request a buffer for object *obj*.
   Argument *flags* are PyBUF options.
   Return the buffer description in *pg_view_p*.
   An object may support the Python buffer interface, the NumPy array interface,
   or the NumPy array struct interface.
   Return ``0`` on success, raise a Python exception and return ``-1`` on failure.

.. c:function:: void pgBuffer_Release(Pg_buffer *pg_view_p)

   Release the Pygame *pg_view_p* buffer.

.. c:function:: int pgDict_AsBuffer(Pg_buffer *pg_view_p, PyObject *dict, int flags)

   Write the array interface dictionary buffer description *dict* into a Pygame
   buffer description struct *pg_view_p*.
   The *flags* PyBUF options describe the view type requested.
   Return ``0`` on success, or raise a Python exception and return ``-1`` on failure.

.. c:function:: void import_pygame_base()

   Import the pygame.base module C API into an extension module.
   On failure raise a Python exception.

.. c:function:: SDL_Window* pg_GetDefaultWindow(void)

   Return the Pygame default SDL window created by a
   pygame.display.set_mode() call, or *NULL*.

   Availability: SDL 2.

.. c:function:: void pg_SetDefaultWindow(SDL_Window *win)

   Replace the Pygame default window with *win*.
   The previous window, if any, is destroyed.
   Argument *win* may be *NULL*.
   This function is called by pygame.display.set_mode().

   Availability: SDL 2.

.. c:function:: pgSurfaceObject* pg_GetDefaultWindowSurface(void)

   Return a borrowed reference to the Pygame default window display surface,
   or *NULL* if no default window is open.

   Availability: SDL 2.

.. c:function:: void pg_SetDefaultWindowSurface(pgSurfaceObject *screen)

   Replace the Pygame default display surface with object *screen*.
   The previous surface object, if any, is invalidated.
   Argument *screen* may be *NULL*.
   This functions is called by pygame.display.set_mode().

   Availability: SDL 2.
