PdCreateOffscreenContext()

Create an offscreen context

Synopsis:

PdOffscreenContext_t *PdCreateOffscreenContext(
                         unsigned long ImageType,
                         unsigned short width,
                         unsigned short height,
                         unsigned long flags );

Arguments:

ImageType

The type of image. Can be one of:

• Pg_IMAGE_DIRECT_1555
• Pg_IMAGE_DIRECT_565
• Pg_IMAGE_DIRECT_888
• Pg_IMAGE_DIRECT_8888
• Pg_IMAGE_PALETTE_BYTE
• 0 (the image type is defined by the current video mode)

For more information about these image types, see PhImage_t.

width, height

The dimensions of the context, in pixels.

flags

Flags that indicate how you want to create the offscreen context. Set to 0 if there are no restrictions on where the context can be allocated. Can be a combination of:

• Pg_OSC_CRTC_SAFE — tell the driver that you want to be able to point the CRT at this context at a later date (using PgSwapDisplay()).

  The driver may change the dimensions and/or image type of the context in order to comply with this flag.

• Pg_OSC_MAIN_DISPLAY — create an offscreen context from the currently displayed screen. It doesn't make a new offscreen context in video ram, but just wraps the displayed screen with a PdOffscreenContext_t structure.
• Pg_OSC_MEM_LINEAR_ACCESSIBLE — Request surface memory that is linearly accessible.

  ---

  Requests made to hardware without linear accessible memory may fail.

  ---

• Pg_OSC_MEM_PAGE_ALIGN — ensure that the offscreen context that's created is aligned to __PAGESIZE (4K on an x86). You need to specify this flag in order to use PdGetOffscreenContextPtr() with this context.
• Pg_OSC_MEM_SYS_ONLY — create an offscreen context in system RAM only. If there is not enough system RAM to create the context, the function fails.
• Pg_OSC_MEM_2D_WRITABLE — create an offscreen context that the graphic card's 2D engine can write to. The offscreen context is created in video RAM only to support hardware acceleration. If there is not enough video RAM to create the context, the function fails.
• Pg_OSC_MEM_2D_READABLE — create an offscreen context that is readable by the graphic card's 2D engine. The offscreen context is created in video RAM only to support hardware acceleration. If there is not enough video RAM to create the context, the function fails.
• Pg_OSC_MEM_HINT_CPU_READ — create an offscreen context that is optimized by the driver for fast reading by the CPU. Use this flag if you are doing unaccelerated rendering or using PdGetOffscreenContextPtr(). This flag has a lower priority than other flags. For example, if conditions conflict for satisfying the requirements of this flag and Pg_OSC_MEM_2D_READABLE, this flag is ignored.
• Pg_OSC_MEM_HINT_CPU_WRITE — create an offscreen context that is optimized by the driver for fast writing by the CPU. Use this flag if you are doing unaccelerated rendering or using PdGetOffscreenContextPtr(). This flag has a lower priority than other flags. For example, if conditions conflict for satisfying the requirements of this flag and Pg_OSC_MEM_2D_WRITABLE, this flag is ignored.
• Pg_OSC_GF_SID — create an offscreen context given an AGTDK surface sid identifier. When you pass this flag, you must set the middle two parameters to 0 (ignored) and specify the AGTDK surface sid identifier as the first parameter. Call gf_surface_get_info() to specify the AGTDK surface sid identifier.

Library:

ph

Description:

This function creates an offscreen context.

---

You must target this function at a specific card by calling PdSetTargetDevice(). PdCreateOffscreenContext() blocks until the operation is complete.

---

If there isn't enough space in video RAM to create the offscreen context, the behavior of this function depends on the driver; most drivers allocate space in system memory instead (if none of SYS_ONLY, 2D_WRITABLE, or 2D_READABLE are set in flags).

Returns:

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

Classification:

Photon

See also:

PdDupOffscreenContext(), PdGetOffscreenContextPtr(), PdOffscreenContext_t, PdSetOffscreenTranslation(), PdSetTargetDevice(), PgContextBlit(), PgSwapDisplay(), PhDCCreate(), PhDCRelease()

“Video memory offscreen” in the Raw Drawing and Animation chapter of the Photon Programmer's Guide