root / ImageMagick / branches / ImageMagick-6.3.6 / magick / cache.c

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%                      CCCC   AAA    CCCC  H   H  EEEEE                       %
%                     C      A   A  C      H   H  E                           %
%                     C      AAAAA  C      HHHHH  EEE                         %
%                     C      A   A  C      H   H  E                           %
%                      CCCC  A   A   CCCC  H   H  EEEEE                       %
%                                                                             %
%                                                                             %
%                      ImageMagick Pixel Cache Methods                        %
%                                                                             %
%                              Software Design                                %
%                                John Cristy                                  %
%                                 July 1999                                   %
%                                                                             %
%                                                                             %
%  Copyright 1999-2007 ImageMagick Studio LLC, a non-profit organization      %
%  dedicated to making software imaging solutions freely available.           %
%                                                                             %
%  You may not use this file except in compliance with the License.  You may  %
%  obtain a copy of the License at                                            %
%                                                                             %
%    http://www.imagemagick.org/script/license.php                            %
%                                                                             %
%  Unless required by applicable law or agreed to in writing, software        %
%  distributed under the License is distributed on an "AS IS" BASIS,          %
%  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   %
%  See the License for the specific language governing permissions and        %
%  limitations under the License.                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%
%
*/

/*
  Include declarations.
*/
#include "magick/studio.h"
#include "magick/blob.h"
#include "magick/blob-private.h"
#include "magick/cache.h"
#include "magick/cache-private.h"
#include "magick/color-private.h"
#include "magick/composite-private.h"
#include "magick/exception.h"
#include "magick/exception-private.h"
#include "magick/list.h"
#include "magick/log.h"
#include "magick/magick.h"
#include "magick/memory_.h"
#include "magick/pixel-private.h"
#include "magick/quantum.h"
#include "magick/random_.h"
#include "magick/resource_.h"
#include "magick/semaphore.h"
#include "magick/splay-tree.h"
#include "magick/string_.h"
#include "magick/utility.h"
#if defined(HasZLIB)
#include "zlib.h"
#endif
#if defined(HAVE_PTHREAD)
#include <pthread.h>
#endif
#if defined(__WINDOWS__)
#include <windows.h>
#endif

/*
  Define declarations.
*/
#define DefaultNumberCacheViews  8UL

/*
  Typedef declarations.
*/
struct _NexusInfo
{
  MagickBooleanType
    available,
    mapped;

  unsigned long
    columns,
    rows;

  long
    x,
    y;

  MagickSizeType
    length;

  PixelPacket
    *cache,
    *pixels;

  IndexPacket
    *indexes;
};

/*
  Forward declarations.
*/
#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif

static const PixelPacket
  *AcquirePixelCache(const Image *,const VirtualPixelMethod,const long,
    const long,const unsigned long,const unsigned long,ExceptionInfo *);

static IndexPacket
  *GetIndexesFromCache(const Image *);

static MagickBooleanType
  OpenCache(Image *,const MapMode,ExceptionInfo *),
  SyncCache(Image *),
  SyncPixelCache(Image *);

static PixelPacket
  AcquireOnePixelFromCache(const Image *,const VirtualPixelMethod,const long,
    const long,ExceptionInfo *),
  GetOnePixelFromCache(Image *,const long,const long),
  *GetPixelCache(Image *,const long,const long,const unsigned long,
    const unsigned long),
  *GetPixelsFromCache(const Image *),
  *SetPixelCache(Image *,const long,const long,const unsigned long,
    const unsigned long);

static void
  DestroyPixelCache(Image *);

#if defined(__cplusplus) || defined(c_plusplus)
}
#endif

/*
  Forward declarations.
*/
static PixelPacket
  *SetNexus(const Image *,const RectangleInfo *,const unsigned long);

static MagickBooleanType
  ReadCacheIndexes(CacheInfo *,const unsigned long,ExceptionInfo *),
  ReadCachePixels(CacheInfo *,const unsigned long,ExceptionInfo *),
  WriteCacheIndexes(CacheInfo *,const unsigned long,ExceptionInfo *),
  WriteCachePixels(CacheInfo *,const unsigned long,ExceptionInfo *);

/*
  Global declarations.
*/
static MagickSizeType
  serial_number = 0;

static SemaphoreInfo
  *cache_semaphore = (SemaphoreInfo *) NULL;

static SplayTreeInfo
  *cache_resources = (SplayTreeInfo *) NULL;

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+   A c q u i r e C a c h e N e x u s                                         %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquireCacheNexus() acquires 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 AcquireCacheNexus() method is:
%
%      PixelPacket *AcquireCacheNexus(const Image *image,
%        const VirtualPixelMethod method,const long x,const long y,
%        const unsigned long columns,const unsigned long rows,
%        const unsigned long nexus,ExceptionInfo *exception)
%
%  A description of each parameter follows:
%
%    o image: The image.
%
%    o virtual_pixel_method: The virtual pixel method.
%
%    o x,y,columns,rows:  These values define the perimeter of a region of
%      pixels.
%
%    o nexus: specifies which cache nexus to acquire.
%
%    o exception: Return any errors or warnings in this structure.
%
*/

static long
  DitherMatrix[64] =
  {
     0,  48,  12,  60,   3,  51,  15,  63,
    32,  16,  44,  28,  35,  19,  47,  31,
     8,  56,   4,  52,  11,  59,   7,  55,
    40,  24,  36,  20,  43,  27,  39,  23,
     2,  50,  14,  62,   1,  49,  13,  61,
    34,  18,  46,  30,  33,  17,  45,  29,
    10,  58,   6,  54,   9,  57,   5,  53,
    42,  26,  38,  22,  41,  25,  37,  21
  };

static inline long DitherX(const unsigned long columns,const long x)
{
  long
    index;

  index=x+DitherMatrix[x & 0x07]-32L;
  if (index < 0L)
    return(0L);
  if (index >= (long) columns)
    return((long) columns-1L);
  return(index);
}

static inline long DitherY(const unsigned long rows,const long y)
{
  long
    index;

  index=y+DitherMatrix[y & 0x07]-32L;
  if (index < 0L)
    return(0L);
  if (index >= (long) rows)
    return((long) rows-1L);
  return(index);
}

static inline long EdgeX(const unsigned long columns,const long x)
{
  if (x < 0L)
    return(0L);
  if (x >= (long) columns)
    return((long) columns-1L);
  return(x);
}

static inline long EdgeY(const unsigned long rows,const long y)
{
  if (y < 0L)
    return(0L);
  if (y >= (long) rows)
    return((long) rows-1L);
  return(y);
}

static inline MagickSizeType MagickMax(const MagickSizeType x,
  const MagickSizeType y)
{
  if (x > y)
    return(x);
  return(y);
}

static inline MagickSizeType MagickMin(const MagickSizeType x,
  const MagickSizeType y)
{
  if (x < y)
    return(x);
  return(y);
}


static inline long RandomX(const unsigned long columns)
{
  long
    x;

  x=(long) (columns*GetRandomValue()+0.5);
  if (x >= (long) columns)
    return((long) columns-1L);
  return(x);
}

static inline long RandomY(const unsigned long rows)
{
  long
    y;

  y=(long) (rows*GetRandomValue()+0.5);
  if (y >= (long) rows)
    return((long) rows-1L);
  return(y);
}

static inline long TileX(const unsigned long columns,const long x)
{
  if (x < 0L)
    return((long) columns+((x+1) % (long) columns)-1);
  if (x >= (long) columns)
    return(x % (long) columns);
  return(x);
}

static inline long TileY(const unsigned long rows,const long y)
{
  if (y < 0L)
    return((long) rows+((y+1) % (long) rows)-1L);
  if (y >= (long) rows)
    return(y % (long) rows);
  return(y);
}

static inline long MirrorX(const unsigned long columns,const long x)
{
  if ((x < 0) || (x >= (long) columns))
    return((long) columns-TileX(columns,x)-1L);
  return(x);
}

static inline long MirrorY(const unsigned long rows,const long y)
{
  if ((y < 0) || (y >= (long) rows))
    return((long) rows-TileX(rows,y)-1L);
  return(y);
}

static inline MagickBooleanType IsNexusInCore(const CacheInfo *cache_info,
  const unsigned long nexus)
{
  MagickOffsetType
    offset;

  register NexusInfo
    *nexus_info;

  nexus_info=cache_info->nexus_info+nexus;
  offset=(MagickOffsetType) nexus_info->y*cache_info->columns+nexus_info->x;
  if (nexus_info->pixels != (cache_info->pixels+offset))
    return(MagickFalse);
  return(MagickTrue);
}

MagickExport const PixelPacket *AcquireCacheNexus(const Image *image,
  const VirtualPixelMethod virtual_pixel_method,const long x,const long y,
  const unsigned long columns,const unsigned long rows,
  const unsigned long nexus,ExceptionInfo *exception)
{
  CacheInfo
    *cache_info;

  IndexPacket
    *indexes,
    *nexus_indexes;

  MagickOffsetType
    offset;

  MagickSizeType
    length,
    number_pixels;

  PixelPacket
    *pixels;

  RectangleInfo
    region;

  register const PixelPacket
    *p;

  register long
    u,
    v;

  register PixelPacket
    *q;

  unsigned long
    image_nexus;

  /*
    Acquire pixels.
  */
  assert(image != (const Image *) NULL);
  assert(image->signature == MagickSignature);
  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  assert(image->cache != (Cache) NULL);
  cache_info=(CacheInfo *) image->cache;
  if (cache_info->type == UndefinedCache)
    return((const PixelPacket *) NULL);
  region.x=x;
  region.y=y;
  region.width=columns;
  region.height=rows;
  pixels=SetNexus(image,&region,nexus);
  offset=(MagickOffsetType) region.y*cache_info->columns+region.x;
  length=(MagickSizeType) (region.height-1)*cache_info->columns+region.width-1;
  number_pixels=(MagickSizeType) cache_info->columns*cache_info->rows;
  if ((offset >= 0) && (((MagickSizeType) offset+length) < number_pixels))
    if ((x >= 0) && ((long) (x+columns) <= (long) cache_info->columns) &&
        (y >= 0) && ((long) (y+rows) <= (long) cache_info->rows))
      {
        MagickBooleanType
          status;

        /*
          Pixel request is inside cache extents.
        */
        if (IsNexusInCore(cache_info,nexus) != MagickFalse)
          return(pixels);
        status=ReadCachePixels(cache_info,nexus,exception);
        if ((cache_info->storage_class == PseudoClass) ||
            (cache_info->colorspace == CMYKColorspace))
          if (ReadCacheIndexes(cache_info,nexus,exception) == MagickFalse)
            status=MagickFalse;
        if (status == MagickFalse)
          return((const PixelPacket *) NULL);
        return(pixels);
      }
  /*
    Pixel request is outside cache extents.
  */
  indexes=GetNexusIndexes(cache_info,nexus);
  image_nexus=GetNexus(cache_info);
  if (image_nexus == 0)
    {
      (void) ThrowMagickException(exception,GetMagickModule(),CacheError,
        "UnableToGetCacheNexus","`%s'",image->filename);
      return((const PixelPacket *) NULL);
    }
  q=pixels;
  for (v=0; v < (long) rows; v++)
  {
    for (u=0; u < (long) columns; u+=length)
    {
      length=(MagickSizeType) MagickMin(cache_info->columns-(x+u),columns-u);
      if ((((x+u) < 0) || ((x+u) >= (long) cache_info->columns)) ||
          (((y+v) < 0) || ((y+v) >= (long) cache_info->rows)) || (length == 0))
        {
          /*
            Transfer a single pixel.
          */
          length=(MagickSizeType) 1;
          switch (virtual_pixel_method)
          {
            case BackgroundVirtualPixelMethod:
            case ConstantVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                EdgeX(cache_info->columns,x+u),EdgeY(cache_info->rows,y+v),
                1UL,1UL,image_nexus,exception);
              cache_info->virtual_pixel=image->background_color;
              p=(&cache_info->virtual_pixel);
              break;
            }
            case BlackVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                EdgeX(cache_info->columns,x+u),EdgeY(cache_info->rows,y+v),
                1UL,1UL,image_nexus,exception);
              cache_info->virtual_pixel.red=0;
              cache_info->virtual_pixel.green=0;
              cache_info->virtual_pixel.blue=0;
              cache_info->virtual_pixel.opacity=OpaqueOpacity;
              p=(&cache_info->virtual_pixel);
              break;
            }
            case DitherVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                DitherX(cache_info->columns,x+u),DitherY(cache_info->rows,y+v),
                1UL,1UL,image_nexus,exception);
              break;
            }
            case EdgeVirtualPixelMethod:
            default:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                EdgeX(cache_info->columns,x+u),EdgeY(cache_info->rows,y+v),
                1UL,1UL,image_nexus,exception);
              break;
            }
            case GrayVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                EdgeX(cache_info->columns,x+u),EdgeY(cache_info->rows,y+v),
                1UL,1UL,image_nexus,exception);
              cache_info->virtual_pixel.red=(Quantum) QuantumRange/2;
              cache_info->virtual_pixel.green=(Quantum) QuantumRange/2;
              cache_info->virtual_pixel.blue=(Quantum) QuantumRange/2;
              cache_info->virtual_pixel.opacity=(Quantum) OpaqueOpacity;
              p=(&cache_info->virtual_pixel);
              break;
            }
            case MaskVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                EdgeX(cache_info->columns,x+u),EdgeY(cache_info->rows,y+v),
                1UL,1UL,image_nexus,exception);
              cache_info->virtual_pixel.red=(Quantum) QuantumRange;
              cache_info->virtual_pixel.green=(Quantum) QuantumRange;
              cache_info->virtual_pixel.blue=(Quantum) QuantumRange;
              cache_info->virtual_pixel.opacity=(Quantum) OpaqueOpacity;
              p=(&cache_info->virtual_pixel);
              break;
            }
            case MirrorVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                MirrorX(cache_info->columns,x+u),MirrorY(cache_info->rows,y+v),
                1UL,1UL,image_nexus,exception);
              break;
            }
            case RandomVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                RandomX(cache_info->columns),RandomY(cache_info->rows),
                1UL,1UL,image_nexus,exception);
              break;
            }
            case TileVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                TileX(cache_info->columns,x+u),TileY(cache_info->rows,y+v),
                1UL,1UL,image_nexus,exception);
              break;
            }
            case TransparentVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                EdgeX(cache_info->columns,x+u),EdgeY(cache_info->rows,y+v),
                1UL,1UL,image_nexus,exception);
              cache_info->virtual_pixel.red=(Quantum) 0;
              cache_info->virtual_pixel.green=(Quantum) 0;
              cache_info->virtual_pixel.blue=(Quantum) 0;
              cache_info->virtual_pixel.opacity=(Quantum) TransparentOpacity;
              p=(&cache_info->virtual_pixel);
              break;
            }
            case WhiteVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                EdgeX(cache_info->columns,x+u),EdgeY(cache_info->rows,y+v),
                1UL,1UL,image_nexus,exception);
              cache_info->virtual_pixel.red=(Quantum) QuantumRange;
              cache_info->virtual_pixel.green=(Quantum) QuantumRange;
              cache_info->virtual_pixel.blue=(Quantum) QuantumRange;
              cache_info->virtual_pixel.opacity=OpaqueOpacity;
              p=(&cache_info->virtual_pixel);
              break;
            }
          }
          if (p == (const PixelPacket *) NULL)
            break;
          *q++=(*p);
          if (indexes == (IndexPacket *) NULL)
            continue;
          nexus_indexes=GetNexusIndexes(cache_info,image_nexus);
          if (nexus_indexes == (IndexPacket *) NULL)
            continue;
          *indexes++=(*nexus_indexes);
          continue;
        }
      /*
        Transfer a run of pixels.
      */
      p=AcquireCacheNexus(image,virtual_pixel_method,x+u,y+v,(unsigned long)
        length,1UL,image_nexus,exception);
      if (p == (const PixelPacket *) NULL)
        break;
      (void) CopyMagickMemory(q,p,(size_t) length*sizeof(*q));
      q+=length;
      if (indexes == (IndexPacket *) NULL)
        continue;
      nexus_indexes=GetNexusIndexes(cache_info,image_nexus);
      if (nexus_indexes == (IndexPacket *) NULL)
        continue;
      (void) CopyMagickMemory(indexes,nexus_indexes,(size_t) length*
        sizeof(*indexes));
      indexes+=length;
    }
  }
  DestroyCacheNexus(cache_info,image_nexus);
  return(pixels);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%   A c q u i r e I m a g e P i x e l s                                       %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquireImagePixels() obtains a pixel region for read-only access. If the
%  region is successfully accessed, a pointer to it is returned, otherwise
%  NULL is returned. The returned pointer may point to a temporary working
%  copy of the pixels or it may point to the original pixels in memory.
%  Performance is maximized if the selected area is part of one row, or one
%  or more full rows, since there is opportunity to access the pixels in-place
%  (without a copy) if the image is in RAM, or in a memory-mapped file.  The
%  returned pointer should *never* be deallocated by the user.
%
%  Pixels accessed via the returned pointer represent a simple array of type
%  PixelPacket.  If the image type is CMYK or the storage class is PseudoClass,
%  call GetIndexes() after invoking GetImagePixels() to access the black
%  color component or to obtain the colormap indexes (of type IndexPacket)
%  corresponding to the region.
%
%  If you plan to modify the pixels, use GetImagePixels() instead.
%
%  Note, the AcquireImagePixels() and GetImagePixels() methods are not thread-
%  safe.  In a threaded environment, use AcquireCacheViewPixels() or
%  GetCacheViewPixels() 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:
%
%    o image: The image.
%
%    o x,y,columns,rows:  These values define the perimeter of a region of
%      pixels.
%
%    o exception: Return any errors or warnings in this structure.
%
*/
MagickExport const PixelPacket *AcquireImagePixels(const Image *image,
  const long x,const long y,const unsigned long columns,
  const unsigned long rows,ExceptionInfo *exception)
{
  CacheInfo
    *cache_info;

  const PixelPacket
    *pixels;

  assert(image != (const Image *) NULL);
  assert(image->signature == MagickSignature);
  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  assert(image->cache != (Cache) NULL);
  cache_info=(CacheInfo *) image->cache;
  assert(cache_info->signature == MagickSignature);
  if (cache_info->methods.acquire_pixel_handler == (AcquirePixelHandler) NULL)
    return((const PixelPacket *) NULL);
  pixels=cache_info->methods.acquire_pixel_handler(image,
    GetCacheVirtualPixelMethod(image),x,y,columns,rows,exception);
  return(pixels);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%   A c q u i r e I n d e x e s                                               %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquireIndexes() returns the black channel or the colormap indexes
%  associated with the last call to SetImagePixels() or AcquireImagePixels().
%  NULL is returned if the black channel or colormap indexes are not available.
%
%  The format of the AcquireIndexes() method is:
%
%      const IndexPacket *AcquireIndexes(const Image *image)
%
%  A description of each parameter follows:
%
%    o indexes: AcquireIndexes() returns the indexes associated with the last
%      call to SetImagePixels() or AcquireImagePixels().
%
%    o image: The image.
%
*/
MagickExport const IndexPacket *AcquireIndexes(const Image *image)
{
  CacheInfo
    *cache_info;

  assert(image != (const Image *) NULL);
  assert(image->signature == MagickSignature);
  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  assert(image->cache != (Cache) NULL);
  cache_info=(CacheInfo *) image->cache;
  assert(cache_info->signature == MagickSignature);
  if (cache_info->methods.acquire_indexes_from_handler ==
       (AcquireIndexesFromHandler) NULL)
    return((IndexPacket *) NULL);
  return(cache_info->methods.acquire_indexes_from_handler(image));
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+   G e t I n d e x e s F r o m C a c h e                                     %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquireIndexesFromCache() returns the indexes associated with the last callV
%  to SetPixelCache() or AcquirePixelCache().
%
%  The format of the AcquireIndexesFromCache() method is:
%
%      IndexPacket *AcquireIndexesFromCache(const Image *image)
%
%  A description of each parameter follows:
%
%    o indexes: AcquireIndexesFromCache() returns the indexes associated with the
%      last call to SetPixelCache() or AcquirePixelCache().
%
%    o image: The image.
%
*/
static const IndexPacket *AcquireIndexesFromCache(const Image *image)
{
  assert(image != (Image *) NULL);
  assert(image->signature == MagickSignature);
  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  assert(image->cache != (Cache) NULL);
  return(AcquireNexusIndexes(image->cache,0));
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+   A c q u i r e N e x u s I n d e x e s                                     %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquireNexusIndexes() returns the indexes associated with the specified
%  cache nexus.
%
%  The format of the AcquireNexusIndexes() method is:
%
%      const IndexPacket *AcquireNexusIndexes(const Cache cache,
%        const unsigned long nexus)
%
%  A description of each parameter follows:
%
%    o indexes: AcquireNexusIndexes returns the indexes associated with the
%      specified cache nexus.
%
%    o cache: The pixel cache.
%
%    o nexus: specifies which cache nexus to return the colormap indexes.
%
*/
MagickExport const IndexPacket *AcquireNexusIndexes(const Cache cache,
  const unsigned long nexus)
{
  CacheInfo
    *cache_info;

  register NexusInfo
    *nexus_info;

  if (cache == (Cache) NULL)
    return((IndexPacket *) NULL);
  cache_info=(CacheInfo *) cache;
  assert(cache_info->signature == MagickSignature);
  if (cache_info->storage_class == UndefinedClass)
    return((IndexPacket *) NULL);
  nexus_info=cache_info->nexus_info+nexus;
  return(nexus_info->indexes);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+   A c q u i r e P i x e l C a c h e                                         %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquirePixelCache() acquires 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 AcquirePixelCache() method is:
%
%      const PixelPacket *AcquirePixelCache(const Image *image,
%        const VirtualPixelMethod virtual_pixel_method,const long x,
%        const long y,const unsigned long columns,const unsigned long rows,
%        ExceptionInfo *exception)
%
%  A description of each parameter follows:
%
%    o image: The image.
%
%    o virtual_pixel_method: The virtual pixel method.
%
%    o x,y,columns,rows:  These values define the perimeter of a region of
%      pixels.
%
%    o exception: Return any errors or warnings in this structure.
%
*/
static const PixelPacket *AcquirePixelCache(const Image *image,
  const VirtualPixelMethod virtual_pixel_method,const long x,const long y,
  const unsigned long columns,const unsigned long rows,ExceptionInfo *exception)
{
  const PixelPacket
    *pixels;

  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  pixels=AcquireCacheNexus(image,virtual_pixel_method,x,y,columns,
    rows,0,exception);
  return(pixels);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%   A c q u i r e O n e M a g i c k P i x e l                                 %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquireOneMagickPixel() 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 AcquireOneMagickPixel() method is:
%
%      MagickPixelPacket AcquireOneMagickPixel(const Image image,const long x,
%        const long y,ExceptionInfo exception)
%
%  A description of each parameter follows:
%
%    o pixels: AcquireOneMagickPixel() returns a pixel at the specified (x,y)
%      location.
%
%    o image: The image.
%
%    o x,y:  These values define the location of the pixel to return.
%
%    o exception: Return any errors or warnings in this structure.
%
*/
MagickExport MagickPixelPacket AcquireOneMagickPixel(const Image *image,
  const long x,const long y,ExceptionInfo *exception)
{
  CacheInfo
    *cache_info;

  MagickPixelPacket
    pixel;

  register const PixelPacket
    *p;

  register IndexPacket
    *indexes;

  assert(image != (const Image *) NULL);
  assert(image->signature == MagickSignature);
  assert(image->cache != (Cache) NULL);
  cache_info=(CacheInfo *) image->cache;
  assert(cache_info->signature == MagickSignature);
  GetMagickPixelPacket(image,&pixel);
  p=AcquirePixelCache(image,GetCacheVirtualPixelMethod(image),x,y,1,1,
    exception);
  indexes=GetIndexes(image);
  SetMagickPixelPacket(image,p,indexes,&pixel);
  return(pixel);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%   A c q u i r e O n e P i x e l                                             %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  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)