Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

PgReadScreen()

Read an image from the screen

Synopsis:

PhImage_t *PgReadScreen( PhRect_t *rect,
                         void *buffer );

Library:

ph

Description:

This function retrieves an image from the screen by querying the local graphics driver(s), using the highest bit depth possible.


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

The PhRect_t structure pointed to by rect specifies the area to capture and is in absolute Photon coordinates.

The buffer argument points to a buffer in which to store the image structure and its associated data, palette, and so on. This must be shared memory, since the graphics driver needs to be able to access it. Use PgReadScreenSize() to determine an adequate size for the buffer. If buffer is NULL, a shared memory object is created for you.

Note the following restrictions:

Returns:

A pointer to the PhImage_t structure that defines the image, or NULL if the operation failed (errno is set).

Errors:

ENOMEM
Insufficient memory to perform the operation.
ENXIO
There was no graphics driver present to capture the specified rectangle.

See the description of shm_open() in the QNX Neutrino Library Reference for further errors that may occur.

Examples:

PhImage_t *image;
PhRect_t rect = { { 0,0 }, {100,100 } };

if(image = PgReadScreen(&rect,buffer))
{
    /* Manipulate the image */
    ...
    
    /* Free the memory */
    PgShmemDestroy(image);
}

This example uses PgReadScreenSize() to determine the amount of shared memory to allocate for the buffer:

PhImage_t *image;
PhRect_t rect = { { 0,0 } }, { 31,31 } };

if((image = PgShmemCreate(PgReadScreenSize(&rect),NULL)) &&
   PgReadScreen(&rect,image))
{
   /* Manipulate the image */
   ...

   /* Free the memory */
   PgShmemDestroy(image);
}

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

PdSetTargetDevice(), PgReadScreenSize(), PgShmemDestroy(), PhImage_t, PhRect_t, PiDuplicateImage()

shm_open() in the QNX Neutrino Library Reference