PhCreateImage()

Create a new PhImage_t structure

Synopsis:

PhImage_t *PhCreateImage( PhImage_t *buffer,
                          short width,
                          short height,
                          int type,
                          PgColor_t const *palette,
                          int ncolors,
                          int shmem );

Library:

ph

Description:

This function creates a new Photon image and allocates space for the image data and palette (if present).

The buffer argument lets you pass in a pointer to a PhImage_t structure to fill in. If this value is NULL, the function allocates a structure for you.

The width and height specify the size of the new image, in pixels. The type specifies the type of the image. Supported types are outlined in the documentation for PhImage_t.

The palette and ncolors arguments let you have this function automatically allocate and fill in space to store the image's palette, if needed. The ncolors argument specifies the size of the palette in terms of the number of colors, while palette points to the list of colors specifying the palette itself:

• If ncolors is 0, no palette is allocated or copied.
• If ncolors is nonzero, but palette is NULL, space is allocated for the palette, but nothing is copied.
• If ncolors is nonzero and palette is non-NULL, then space is allocated and the palette is copied automatically.

The shmem argument specifies whether or not shared memory should be allocated for the image's data. For large images, shared memory facilitates faster data transfer to local graphics drivers, and hence quicker rendering of the image. If you wish to use shared memory to store the image data, set this value to 1. Otherwise, set it to 0.

Returns:

A pointer to the new image on success, or NULL if an error occurred due to lack of memory, or if the specified type isn't a recognized Photon image type.

Classification:

Photon

See also:

ApGetImageRes(), PgColor_t, PgDrawPhImage*(), PgDrawPhImageRect*(), PgDrawRepPhImage*(), PhImage_t, PhMakeGhostBitmap(), PhMakeTransBitmap(), PhMakeTransparent(), PhReleaseImage(), PmMemCreateMC(), PmMemFlush(), PxRotateImage(), PxLoadImage()

“Images” in the Raw Drawing and Animation chapter of the Photon Programmer's Guide