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
• Pg_LAYER_FORMAT_YUV_AYUV
• Pg_LAYER_FORMAT_YUV_NV12

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

See also:

PdGetOffscreenContextPtr(), PdOffscreenContext_t, PdSetTargetDevice(), PgGetLayerCaps(), PgSetLayerSurface()

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