PdDupOffscreenContext()

Duplicate an offscreen context

Synopsis:

PdOffscreenContext_t *
    PdDupOffscreenContext(
        PdOffscreenContext_t *context,
        unsigned long flags );

Arguments:

context

A pointer to the context that you want to duplicate, as returned by PdCreateOffscreenContext(), or NULL if you want to duplicate the screen buffer.

flags

Flags that indicate how you want to create the offscreen context:

• 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_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.

Library:

ph

Description:

PdDupOffscreenContext() makes a copy of the given context. This not only creates a context that has the same dimensions and image type, but also copies the image data.

---

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

---

Returns:

A pointer to a PdOffscreenContext_t structure, or NULL on failure.

Classification:

Photon

See also:

PdCreateOffscreenContext(), PdGetOffscreenContextPtr(), PdOffscreenContext_t, PdSetOffscreenTranslation(), PdSetTargetDevice(), PgContextBlit(), PgSwapDisplay()

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