cache - Low-level access to image pixels

- NAME
- SYNOPSIS
- FUNCTION DESCRIPTIONS

- AcquireImagePixels
- AcquireOnePixel
- DestroyCacheInfo
- DestroyImagePixels
- GetImagePixels
- GetImageVirtualPixelMethod
- GetIndexes
- GetOnePixel
- GetPixels
- ModifyCache
- ReferenceCache
- SetImagePixels
- SetImageVirtualPixelMethod

# NAME

cache - Low-level access to 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 );

VirtualPixelMethod GetImageVirtualPixelMethod( const Image *image );

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

SetImageVirtualPixelMethod( const Image *image, const VirtualPixelMethod method );

unsigned int SyncImagePixels( Image *image );

# FUNCTION DESCRIPTIONS

## AcquireImagePixels

> AcquireImagePixels() acquires pixels from the in-memory or disk pixel cache as defined by the geometry parameters. A pointer to the pixel is returned if the pixels are transferred, otherwise a NULL is returned. If you plan to modify 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:
  `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

> 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 modify 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:
  `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

> 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

> 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

> 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:
  `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.

## GetImageVirtualPixelMethod

> GetImageVirtualPixelMethod() gets the "virtual pixels" method for the image. A virtual pixel is any pixel access that is outside the boundaries of the image cache.

> The format of the GetImageVirtualPixelMethod() method is:

> VirtualPixelMethod GetImageVirtualPixelMethod ( const Image *image );

A description of each parameter follows:

image:
  The image.

## GetIndexes

> 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:
  `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

> 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:
  `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

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

## SetImageVirtualPixelMethod

> SetImageVirtualPixelMethod() sets the "virtual pixels" method for the image. A virtual pixel is any pixel access that is outside the boundaries of the image cache.

> The format of the SetImageVirtualPixelMethod() method is:

> SetImageVirtualPixelMethod ( const Image *image, const VirtualPixelMethod method );

A description of each parameter follows:

image:
  The image.

type:
  choose from these access types:

          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.
          ConstantVPType:  every value outside the image is a constant as
          defines by the pixel parameter.
    =head2 SyncImagePixels

> 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:
  `SyncImagePixels()` returns True if the image pixels are transferred to the in-memory or disk cache otherwise False.

image:
  The image.