PgSetLayerSurface()

Tell a layer to fetch image data from a specified surface

Synopsis:

int PgSetLayerSurface( int layer, 
                       int surface_index,
                       PdOffscreenContext_t *surface );

Arguments:

layer

The layer index, which must be 0 or greater.

surface_index

The surface index, which must be 0 or greater.

surface

A pointer to the PdOffscreenContext_t structure for the offscreen context, created by a call to PgCreateLayerSurface(), that you want to display. This argument must not be NULL.

Library:

ph

Description:

PgSetLayerSurface() tells a layer to fetch image data from the specified surface. If another surface was previously assigned to the layer for the same surface_index, it's replaced but not destroyed.

---

You must target this function at a device by calling PdSetTargetDevice().

---

You must configure the layer's format before calling PgSetLayerSurface(). If a layer reads data from more than one surface, every surface read must have the same width and height.

You must use this function after a call to PgSetLayerArg() with an argument of Pg_LAYER_ARG_LIST_BEGIN, and before another call with an argument of Pg_LAYER_ARG_LIST_END. For example:

int fmt_idx = 5;
PgSetLayerArg( layer, Pg_LAYER_ARG_LIST_BEGIN, NULL, 0 );
PgSetLayerArg( layer, Pg_LAYER_ARG_FORMAT_INDEX,
               &fmt_idx, sizeof(int) );
PgSetLayerSurface( layer, 0, osc0 );
PgSetLayerSurface( layer, 1, osc1 );
PgSetLayerSurface( layer, 2, osc2 );
PgSetLayerArg( layer, Pg_LAYER_ARG_BRIGHTNESS, ... );
PgSetLayerArg( layer, ... );
...
PgSetLayerArg( layer, Pg_LAYER_ARG_LIST_END, NULL, 0 );

Returns:

0

Success.

-1

An error occurred (errno is set).

Errors:

EBUSY

The layer is locked by another application.

EINVAL

The specified layer or surface doesn't exist, the osc argument is NULL, or the specified offscreen context is incompatible with the layer and/or surface.

EOPNOTSUPP

The operation isn't supported.

EFAULT

The function couldn't access the specified offscreen context.

Classification:

Photon

See also:

PdOffscreenContext_t, PdSetTargetDevice(), PgCreateLayerSurface(), PgSetLayerArg()

"Layers" in the Raw Drawing and Animation chapter of the Photon Programmer's Guide