PgCreateLayerSurface()

Create an offscreen context that a layer can display

Synopsis:

PdOffscreenContext_t *PgCreateLayerSurface(
                         int layer,
                         int surface_index,
                         int format_index,
                         unsigned short width,
                         unsigned short height,
                         unsigned long flags);

Arguments:

layer

The layer index, which must be 0 or greater.

surface_index

The surface index, which must be 0 or greater.

format_index

The image format index, which corresponds to the index used in PgGetLayerCaps().

width, height

The dimensions of the context, in pixels.

flags

Defined flags are:

Pg_OSC_MEM_PAGE_ALIGN — ensure that the offscreen context that's created is aligned to __PAGESIZE (4K on an x86). You should set this flag if you're using PdGetOffscreenContextPtr().
Pg_OSC_MEM_2D_READABLE — create an offscreen context that is readable by a 2D engine.
Pg_OSC_MEM_2D_WRITABLE — create an offscreen context that is targetable by a 2D engine.
Pg_OSC_MEM_HINT_CPU_READ — create an offscreen context that is optimized by the driver for fast reading by the CPU. This flag has a lower priority than other flags.
Pg_OSC_MEM_HINT_CPU_WRITE — create an offscreen context that is optimized by the driver for fast writing by the CPU. This flag has a lower priority than other flags.

Library:

ph

Description:

PgCreateLayerSurface() creates an offscreen context that can be nearby the given layer in the given format.

For layer formats that require data from more than one surface, surface_index is used to distinguish each surface.

For these layer formats:

Pg_LAYER_FORMAT_YVU9
Pg_LAYER_FORMAT_YV12
Pg_LAYER_FORMAT_YUV420

Use these surface indices:

0: Y plane
1: U plane
2: V plane

For all other layer formats, use 0 for surface_index.

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

If a layer is reconfigured (e.g. its format is changed), previously allocated offscreen contexts might no longer be compatible with the layer.

To tell a layer to read data from a surface, call PgSetLayerSurface().

You can't use Photon drawing functions on a surface with a format that doesn't match the current video mode.

Returns:

A pointer to a PdOffscreenContext_t structure, or NULL if an error occurred.

Errors:

EINVAL: The format, dimensions, or flags are incompatible with the given layer capabilities, or the layer or layer surface doesn't exist.
EOPNOTSUPP: The operation isn't supported.
ENOMEM: Memory allocation failed.

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No