- NAME
- SYNOPSIS
- FUNCTION DESCRIPTIONS
  - AcquireImagePixels
  - AcquireOnePixel
  - DestroyImagePixels
  - GetImagePixels
  - GetIndexes
  - GetOnePixel
  - GetPixels
  - ModifyCache
  - ReferenceCache
  - SetImagePixels
  - SyncImagePixels

# 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 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 );

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.

## 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.

## 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.