PdGetOffscreenContextPtr()

Create a shared memory object reference to an offscreen context

Synopsis:

void *PdGetOffscreenContextPtr( 
         PdOffscreenContext_t *osc );

Arguments:

osc: A pointer to a PdOffscreenContext_t, structure that describes an offscreen context. You must have created the context with the Pg_OSC_MEM_PAGE_ALIGN flag in order for this function to work.

Description:

This function creates a shared memory reference to an offscreen context and return a pointer to the object.

PdGetOffscreenContextPtr() can fail on certain hardware. You can use this function on closed systems where you know that the graphics frame buffer is linear; don't use it in applications that target generic hardware configurations.

If osc is NULL, this function returns a pointer to the currently displayed screen:

If you're in direct mode, the pointer to the screen is read/write.
If you aren't in direct mode, the pointer is read only.

If osc isn't the visible screen, the pointer is read/write.

This call blocks until the operation is complete.

Returns:

A pointer to the shared memory object, or NULL on failure.

Examples:

Draw a white vertical line in an offscreen context using software (not PgDrawRect()):

// For the purposes of this example, we'll accept only
// 565, 555, or 8888 as possible targets.

typedef union vidptr {
    uint8_t  * volatile ptr8;
    uint16_t * volatile ptr16;
    uint32_t * volatile ptr32;
} VidPtr_t;

PdOffscreenContext_t *buff;
VidPtr_t main_ptr,work_ptr;
uint32_t color,bytespp;
PhRect_t rect;
int i;

// Create the offscreen context
buff=PdCreateOffscreenContext(0,100,100,
                              Pg_OSC_MEM_PAGE_ALIGN);
if (buff==NULL)
{
    // Error code
    return;
}

// figure out which value color should be
switch (buff->format)
{
    case Pg_IMAGE_DIRECT_565 :
        color = 0x0000FFFF; 
        bytespp=2;
    break;
    case Pg_IMAGE_DIRECT_8888 :
        color = 0x00FFFFFF;
        bytespp=4;
    break;
    default:
        //Error code
        return;
}

rect.ul.x=rect.ul.y=0;
rect.lr.x=rect.lr.y=99;

main_ptr.ptr8=(unsigned char *) 
                 PdGetOffscreenContextPtr(buff);
if (main_ptr.ptr8 == NULL)
{
    // Error code
}

// Clear the context to black
PhDCSetCurrent(buff);
PgSetFillColor(Pg_BLACK);
PgDrawRect(&rect,Pg_DRAW_FILL);
PgFlush();

// Ensure that all drawing operations are done before
// writing using software to this context:
PgWaitHWIdle();

// draw the line in the middle:
work_ptr.ptr8=main_ptr.ptr8 + (49 * bytespp);

for (i=0; i<100; i++, work_ptr.ptr8+=buff->pitch)
{
    switch (bytespp)
    {
        case 2 :
            *work_ptr.ptr16 = color;
        break;
        case 4 :
            *work_ptr.ptr32 = color;
        break;
    }
}

PgContextBlit(buff,&rect,NULL,&rect); 
PgFlush();

// You should see a black rectangle with a vertical
// white line in the middle

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No