Create an offscreen context that a layer can display
PdOffscreenContext_t *PgCreateLayerSurface( int layer, int surface_index, int format_index, unsigned short width, unsigned short height, unsigned long flags);
- The layer index, which must be 0 or greater.
- The surface index, which must be 0 or greater.
- The image format index, which corresponds to the index used in PgGetLayerCaps().
- width, height
- The dimensions of the context, in pixels.
- 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.
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:
Use these surface indices:
- Y plane
- U plane
- 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.|
A pointer to a PdOffscreenContext_t structure, or NULL if an error occurred.
- The format, dimensions, or flags are incompatible with the given layer capabilities, or the layer or layer surface doesn't exist.
- The operation isn't supported.
- Memory allocation failed.
“Layers” in the Raw Drawing and Animation chapter of the Photon Programmer's Guide