• NAME
• SYNOPSIS
• FUNCTION DESCRIPTIONS
• AcquireImagePixels
• AcquireOnePixel
• DestroyCacheInfo
• DestroyImagePixels
• GetImagePixels
• GetImageVirtualPixelMethod
• GetIndexes
• GetOnePixel
• GetPixels
• ModifyCache
• ReferenceCache
• SetImagePixels
• SetImageVirtualPixelMethod

NAME

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

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

MagickBooleanType ModifyCache( Image *image, const unsigned long nexus );

Cache ReferenceCache( Cache cache_info );

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

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

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

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:

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:

MagickBooleanType ModifyCache ( Image *image, const unsigned long nexus );

A description of each parameter follows:

image:

The image.

nexus:

specifies which cache nexus to acquire.

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:

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

A description of each parameter follows:

image:

The image.

method:

choose from these access types:

      EdgeVirtualPixelMethod:  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.
      TileVirtualPixelMethod:  the image extends periodically or tiled.  The
      pixels wrap around the edges of the image.
      MirrorVirtualPixelMethod:  mirror the image at the boundaries.
      ConstantVirtualPixelMethod:  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 MagickTrue if the pixel region is synced, otherwise MagickFalse.

The format of the SyncImagePixels() method is:

MagickBooleanType SyncImagePixels ( Image *image );

A description of each parameter follows:

image:

The image.