NAME

cache - Methods to Get or Set Image Pixels

SYNOPSIS

const PixelPacket * AcquireImagePixels( const Image *image, const long x, const long y, const unsigned long columns, const unsigned long rows, ExceptionInfo *exception );

PixelPacket AcquireOnePixel( const Image image, const long x, const long y, ExceptionInfo exception );

void DestroyCacheInfo( Cache cache );

void DestroyImagePixels( Image *image );

PixelPacket * GetImagePixels( Image *image, const long x, const long y, const unsigned long columns, const unsigned long rows );

IndexPacket * GetIndexes( const Image *image );

PixelPacket * GetOnePixel( const Image image, const long x, const long y );

PixelPacket * GetPixels( const Image image );

unsigned int ModifyCache( Image *image );

Cache ReferenceCache( Cache cache_info );

PixelPacket * SetImagePixels( Image *image, const long x, const long y, const unsigned long columns, const unsigned long rows );

SetImageVirtualPixelType( Image *image, const VirtualPixelType type, const PixelPacket *pixel );

unsigned int SyncImagePixels( Image *image );

FUNCTION DESCRIPTIONS

AcquireImagePixels

Method AcquireImagePixels() acquires pixels from the in-memory or disk pixel cache as defined by the geometry parameters. A pointer to the pixels is returned if the pixels are transferred, otherwise a NULL is returned. If you plan to change the pixels, use GetImagePixels ( ) instead.
The format of the AcquireImagePixels() method is:
const PixelPacket *AcquireImagePixels ( const Image *image, const long x, const long y, const unsigned long columns, const unsigned long rows, ExceptionInfo *exception );

A description of each parameter follows:

status:
Method AcquireImagePixels() returns a pointer to the pixels if they are transferred, otherwise a NULL is returned.

image:
The image.

x,y,columns,rows:
These values define the perimeter of a region of pixels.

exception:
Return any errors or warnings in this structure.

AcquireOnePixel

Method AcquireOnePixel() returns a single pixel at the specified ( x, y ) location. The image background color is returned if an error occurs. If you plan to change the pixel, use GetOnePixel ( ) instead.
The format of the AcquireOnePixel() method is:
PixelPacket AcquireOnePixel ( const Image image, const long x, const long y, ExceptionInfo exception );

A description of each parameter follows:

pixels:
Method AcquireOnePixel() returns a pixel at the specified (x,y) location.

image:
The image.

x,y:
These values define the location of the pixel to return.

exception:
Return any errors or warnings in this structure.

DestroyCacheInfo

Method DestroyCacheInfo() deallocates memory associated with the pixel cache.
The format of the DestroyCacheInfo() method is:
void DestroyCacheInfo ( Cache cache );

A description of each parameter follows:

cache:
Specifies a pointer to a Cache structure.

DestroyImagePixels

Method DestroyImagePixels() deallocates memory associated with the pixel cache.
The format of the DestroyImagePixels() method is:
void DestroyImagePixels ( Image *image );

A description of each parameter follows:

image:
The image.

GetImagePixels

Method GetImagePixels() gets pixels from the in-memory or disk pixel cache as defined by the geometry parameters. A pointer to the pixels is returned if the pixels are transferred, otherwise a NULL is returned.
The format of the GetImagePixels() method is:
PixelPacket *GetImagePixels ( Image *image, const long x, const long y, const unsigned long columns, const unsigned long rows );

A description of each parameter follows:

status:
Method GetImagePixels() returns a pointer to the pixels if they are transferred, otherwise a NULL is returned.

image:
The image.

x,y,columns,rows:
These values define the perimeter of a region of pixels.

GetIndexes

Method GetIndexes() returns the indexes associated with the last call to SetImagePixels ( ) or GetImagePixels ( ) .
The format of the GetIndexes() method is:
IndexPacket *GetIndexes ( const Image *image );

A description of each parameter follows:

indexes:
Method GetIndexes() returns the indexes associated with the last call to SetImagePixels() or GetImagePixels().

image:
The image.

GetOnePixel

GetOnePixel() returns a single pixel at the specified ( x, y ) location. The image background color is returned if an error occurs.
The format of the GetOnePixel() method is:
PixelPacket *GetOnePixel ( const Image image, const long x, const long y );

A description of each parameter follows:

image:
The image.

x,y:
These values define the location of the pixel to return.

GetPixels

Method GetPixels() returns the pixels associated with the last call to SetImagePixels ( ) or GetImagePixels ( ) .
The format of the GetPixels() method is:
PixelPacket *GetPixels ( const Image image );

A description of each parameter follows:

pixels:
Method GetPixels() returns the pixels associated with the last call to SetImagePixels() or GetImagePixels().

image:
The image.

ModifyCache

ModifyCache() ensures that there is only a single reference to the pixel cache to be modified, updating the provided cache pointer to point to a clone of the original pixel cache if necessary.

The format of the ModifyCache method is:

unsigned int ModifyCache ( Image *image );

A description of each parameter follows:

image:
The image.

ReferenceCache

ReferenceCache() increments the reference count associated with the pixel cache returning a pointer to the cache.

The format of the ReferenceCache method is:

Cache ReferenceCache ( Cache cache_info );

A description of each parameter follows:

cache_info:
The cache_info.

SetImagePixels

Method SetImagePixels() allocates an area to store image pixels as defined by the region rectangle and returns a pointer to the area. This area is subsequently transferred from the pixel cache with SyncImagePixels ( ) . A pointer to the pixels is returned if the pixels are transferred, otherwise a NULL is returned.
The format of the SetImagePixels() method is:
PixelPacket *SetImagePixels ( Image *image, const long x, const long y, const unsigned long columns, const unsigned long rows );

A description of each parameter follows:

pixels:
Method SetImagePixels returns a pointer to the pixels if they are transferred, otherwise a NULL is returned.

image:
The image.

x,y,columns,rows:
These values define the perimeter of a region of pixels.

SetImageVirtualPixelType

SetImageVirtualPixelType() sets the type of "virtual" pixels for the image. A virtual pixel is any pixel access that is outside the boundaries of the image cache.
The format of the SetImageVirtualPixelType() method is:
SetImageVirtualPixelType ( Image *image, const VirtualPixelType type, const PixelPacket *pixel );

A description of each parameter follows:

image:
The image.

type:
choose from these access types: 

      ConstantVPType:  every value outside the image is a constant as
      defines by the pixel parameter.
      EdgeVPType:  the edge pixels of the image extend infinitely.
      Any pixel outside the image is assigned the same value as the
      pixel at the edge closest to it.
      TileVPType:  the image extends periodically or tiled.  The pixels
      wrap around the edges of the image.
      MirrorVPType:  mirror the image at the boundaries.
=over 4

pixel:
the constant pixel value for the ConstantVPType method. This value is ignored for other access methods.

SyncImagePixels

Method SyncImagePixels() saves the image pixels to the in-memory or disk cache. The method returns True if the pixel region is synced, otherwise False.
The format of the SyncImagePixels() method is:
unsigned int SyncImagePixels ( Image *image );

A description of each parameter follows:

status:
Method SyncImagePixels() returns True if the image pixels are transferred to the in-memory or disk cache otherwise False.

image:
The image.