PiInitImage()

Initialize a Photon image

Synopsis:

PhImage_t *PiInitImage( PhImage_t *oldImage,
                        PhRect_t const *oldRect,
                        PhRect_t *newRect,
                        int newType,
                        int flags,
                        int colors )

Arguments:

oldImage

A pointer to a PhImage_t structure that defines the image parameters to use to initialize the new image.

oldRect

A rectangle that defines an area within oldImage to use to initialize the new image. If passed as NULL, the entire rectangle representing oldImage is used.

newRect

A location where the function can fill in a rectangle that describes the area of the new image.

newType

The type of the new image. This must be one of the Pg_IMAGE_* types defined for PhImage_t. See Image types for a list of defined types. If this argument is 0, the type from oldImage is used.

flags

Dictates special behavior of the initialization process and can take the following values:

Pi_CHECK_BOUNDS)

Checks that the coordinates in oldRect make sense. If you set this flag bit, the function uses (0,0) for the upper-left corner if the coordinates in oldRect are negative. It also uses the image's lower-left corner coordinates, if the lower-left corner coordinates in oldRect are too large.

Pi_SHMEM

Store the newly created image data in shared memory. This is useful if you require fast rendering of the image.

Pi_USE_COLORS

Copy the palette of the old image. If not specified, the new image palette is NULL.

colors

Library:

ph

Description:

This function initializes a new, empty Photon image based on the parameters of an existing image, copying all the PhImage_t structure members, and allocating a new image data buffer the same size as the old image's data buffer. If you specify the Pi_USE_COLORS flag bit, this function also copies the old image palette. You can optionally initialize a smaller image by passing in oldRect.

To duplicate an existing image, use PiDuplicateImage().

Returns:

A pointer to the new, empty image on success, or NULL if an error occurred.

Classification:

Photon

See also:

PhCreateImage(), PhImage_t, PhRect_t, PiConvertImage() PiDuplicateImage(), PiFlipImage(), PiResizeImage()

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