[Home] [Mission Statement] [Development Process] [Download] [Installation] [CVS] [Mailing Lists] [FAQ] [Formats] [News ] [ChangeLog] [Report Bugs] [Utilities] [Programming] [Books] [Links] |
Search GraphicsMagick site

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

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

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.