PgReadScreen()

Read an image from the screen

Synopsis:

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

Description:

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

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:

There must be a graphics driver present that completely encompasses the rectangle being captured.
The graphics driver must be running on the same node as the calling process, since shared memory is used to pass data.
All data associated with the image (structure, palette, data) is stored in one contiguous shared memory object. Release this memory by calling PgShmemDestroy(); don't call PhReleaseImage() for an image acquired using PgReadScreen(). If you plan to use the acquired image in an environment where this restriction proves inconvenient, then you should make a copy of the image using PiDuplicateImage(), after which you may free the original as outlined above.

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

PgReadScreen