libgpcogl - API reference

Arrays

typedef struct gpcogl_array_id_s gpcogl_array_id_t;

extern const gpcogl_array_id_t gpcogl_no_array;

typedef enum gpcogl_cell_type_e {   /* each cell of the array is holding ... */
	GPCOGL_CT_1_FLOAT32,              /* ... a single float32 */
	GPCOGL_CT_2_FLOAT32,              /* ... a pair of float32s */
	GPCOGL_CT_3_FLOAT32,              /* ... three of float32s */
	GPCOGL_CT_4_FLOAT32,              /* ... four of float32s */
	GPCOGL_CT_1_INT32,                /* ... a single int32 */
	GPCOGL_CT_2_INT32,                /* ... a pair of int32s */
	GPCOGL_CT_3_INT32,                /* ... three of int32s */
	GPCOGL_CT_4_INT32,                /* ... four of int32s */
	GPCOGL_CT_1_UINT32,               /* ... a single uint32 */
	GPCOGL_CT_2_UINT32,               /* ... a pair of uint32s */
	GPCOGL_CT_3_UINT32,               /* ... three of uint32s */
	GPCOGL_CT_4_UINT32,               /* ... four of uint32s */

	GPCOGL_CT_max
} gpcogl_cell_type_t;

gpcogl_array_id_t gpcogl_array_create(gpcogl_t *ctx, gpcogl_cell_type_t ct, int sx, int sy);

int gpcogl_array_clear(gpcogl_t *ctx, gpcogl_array_id_t dst);

gpcogl_array_id_t gpcogl_array_init(gpcogl_t *ctx, gpcogl_cell_type_t ct, const void *inp, int sx, int sy);

int gpcogl_array_get(gpcogl_t *ctx, void *dst, gpcogl_array_id_t src);

int gpcogl_array_get_box(gpcogl_t *ctx, void *dst, gpcogl_array_id_t src, GLint x0, GLint y0, GLsizei w, GLsizei h);

int gpcogl_array_get_size(gpcogl_t *ctx, GLint *sx, GLint *sy, gpcogl_array_id_t src);

int gpcogl_array_free(gpcogl_t *ctx, gpcogl_array_id_t aid);

Array type

A GPU array is identified by its gpcogl_array_id_t, which is an opaque struct that contains enough information for the lib to address the array in GPU memory. A special value gpcogl_no_array is provided to act as the invalid array ID.

An array is built of uniform cells. The type of the cell is referenced by an GPCOGL_CT_* enum value. Enum value GPCOGL_CT_max is provided to count the number of cell types available.

Limitation: using 3 long cells (GPCOGL_CT_3_*) for the output array is not portable and will fail on some common GPUs. For output always use 1, 2 or 4 long cells. This is a limitation of the OpenGL specification.

Creating/uploading arrays

An array is created with uninitialized (random) content in GPU memory in using gpcogl_array_create(). Returns gpcogl_no_array on error. When the array is used as input or is written by shader programs only partially, it's necessary to clear the array after it's been created. This is done using gpcogl_array_clear(), which sets all bits of the array to 0. This call returns 0 on success.

An alternative approach is to create an array and upload its whole content from the CPU. This is done using gpcogl_array_init(), which both creates and initializes the array from the CPU memory buffer inp.

Downloading arrays

Arrays can be downloaded from GPU memory to CPU memory using gpcogl_array_get() and gpcogl_array_get_box(). The former donwloads the whole array, the latter downloads only a rectangular box of width w and height h cells from offset x0,y0 (indexed from 0). All downloads are containing cells macthing the cell type specified when the array was created. All downloads are in in row-major format. These calls assume the caller has enough room for all data in dst and happoly overrun the buffer if not.

These calls return 0 on success.

Query

Function gpcogl_array_get_size() can be used to query array size from the GPU. Size is returned in sx and sy.

This call returns 0 on success.

Free