cache - Get or Set Image Pixels

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: 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: 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: status: `SyncImagePixels()` returns MagickTrue if the image pixels are transferred to the in-memory or disk cache otherwise MagickFalse. image: The image. "Image manipulation software that works like magick"