Powered by NetworkEleven ImageMagick logo

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.
Top of page
"Image manipulation software that works like magick"