cache.c

Go to the documentation of this file.

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%                      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                       %
%                                                                             %
%                                                                             %
%                       MagickCore Pixel Cache Methods                        %
%                                                                             %
%                              Software Design                                %
%                                John Cristy                                  %
%                                 July 1999                                   %
%                                                                             %
%                                                                             %
%  Copyright 1999-2008 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(MAGICKCORE_ZLIB_DELEGATE)
#include "zlib.h"
#endif
#if defined(MAGICKCORE_HAVE_PTHREAD)
#include <pthread.h>
#endif
#if defined(__WINDOWS__)
#include <windows.h>
#endif

/*
  Typedef declarations.
*/
struct _NexusInfo
{
  MagickBooleanType
    reserve,
    mapped;

  RectangleInfo
    region;

  MagickSizeType
    length;

  PixelPacket
    *cache,
    *pixels;

  IndexPacket
    *indexes;

  unsigned long
    signature;
};

/*
  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
  GetOneVirtualPixelFromCache(const Image *,const VirtualPixelMethod,
    const long,const long,PixelPacket *,ExceptionInfo *),
  GetOneAuthenticPixelFromCache(Image *,const long,const long,PixelPacket *,
    ExceptionInfo *),
  OpenCache(Image *,const MapMode,ExceptionInfo *),
  SyncCache(Image *,ExceptionInfo *),
  SyncPixelCache(Image *,ExceptionInfo *),
  SyncImagePixelCache(Image *,ExceptionInfo *);

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

static void
  DestroyPixelCache(Image *);

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

static MagickBooleanType
  ReadCacheIndexes(CacheInfo *,NexusInfo *,ExceptionInfo *),
  ReadCachePixels(CacheInfo *,NexusInfo *,ExceptionInfo *),
  WriteCacheIndexes(CacheInfo *,NexusInfo *,ExceptionInfo *),
  WriteCachePixels(CacheInfo *,NexusInfo *,ExceptionInfo *);

/*
  Global declarations.
*/
static volatile MagickBooleanType
  instantiate_cache = MagickFalse;

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,
%        NexusInfo *nexus_info,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_info: the 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*GetPseudoRandomValue()+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*GetPseudoRandomValue()+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,
  NexusInfo *nexus_info)
{
  MagickOffsetType
    offset;

  offset=(MagickOffsetType) nexus_info->region.y*cache_info->columns+
    nexus_info->region.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,NexusInfo *nexus_info,
  ExceptionInfo *exception)
{
  CacheInfo
    *cache_info;

  IndexPacket
    *indexes;

  MagickOffsetType
    offset;

  MagickSizeType
    length,
    number_pixels;

  NexusInfo
    *virtual_nexus;

  PixelPacket
    *pixels;

  RectangleInfo
    region;

  register const IndexPacket
    *nexus_indexes;

  register const PixelPacket
    *p;

  register long
    u,
    v;

  register PixelPacket
    *q;

  /*
    Acquire pixels.
  */
  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  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_info);
  if (pixels == (PixelPacket *) NULL)
    return((const PixelPacket *) NULL);
  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))
      {
        /*
          Pixel request is inside cache extents.
        */
        if (IsNexusInCore(cache_info,nexus_info) != MagickFalse)
          return(pixels);
        if (ReadCachePixels(cache_info,nexus_info,exception) == MagickFalse)
          return((const PixelPacket *) NULL);
        if ((cache_info->storage_class == PseudoClass) ||
            (cache_info->colorspace == CMYKColorspace))
          if (ReadCacheIndexes(cache_info,nexus_info,exception) == MagickFalse)
            return((const PixelPacket *) NULL);
        return(pixels);
      }
  /*
    Pixel request is outside cache extents.
  */
  q=pixels;
  indexes=GetNexusIndexes(cache_info,nexus_info);
  virtual_nexus=AcquireNexusInfo();
  if (virtual_nexus == (NexusInfo *) NULL)
    {
      (void) ThrowMagickException(exception,GetMagickModule(),CacheError,
        "UnableToGetCacheNexus","`%s'",image->filename);
      return((const PixelPacket *) NULL);
    }
  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,virtual_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,virtual_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,virtual_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,virtual_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,virtual_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 HorizontalTileVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                TileX(cache_info->columns,x+u),TileY(cache_info->rows,y+v),
                1UL,1UL,virtual_nexus,exception);
              if (((y+v) < 0) || ((y+v) >= (long) cache_info->rows))
                {
                  cache_info->virtual_pixel=image->background_color;
                  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,virtual_nexus,exception);
              break;
            }
            case RandomVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                RandomX(cache_info->columns),RandomY(cache_info->rows),
                1UL,1UL,virtual_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,virtual_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,virtual_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 VerticalTileVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                TileX(cache_info->columns,x+u),TileY(cache_info->rows,y+v),
                1UL,1UL,virtual_nexus,exception);
              if (((x+u) < 0) || ((x+u) >= (long) cache_info->columns))
                {
                  cache_info->virtual_pixel=image->background_color;
                  p=(&cache_info->virtual_pixel);
                }
              break;
            }
            case MaskVirtualPixelMethod:
            case WhiteVirtualPixelMethod:
            {
              p=AcquireCacheNexus(image,virtual_pixel_method,
                EdgeX(cache_info->columns,x+u),EdgeY(cache_info->rows,y+v),
                1UL,1UL,virtual_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)
            {
              nexus_indexes=AcquireNexusIndexes(cache_info,virtual_nexus);
              if (nexus_indexes != (const IndexPacket *) NULL)
                *indexes++=(*nexus_indexes);
            }
          continue;
        }
      /*
        Transfer a run of pixels.
      */
      p=AcquireCacheNexus(image,virtual_pixel_method,x+u,y+v,(unsigned long)
        length,1UL,virtual_nexus,exception);
      if (p == (const PixelPacket *) NULL)
        break;
      (void) CopyMagickMemory(q,p,(size_t) length*sizeof(*p));
      q+=length;
      if (indexes != (IndexPacket *) NULL)
        {
          nexus_indexes=AcquireNexusIndexes(cache_info,virtual_nexus);
          if (nexus_indexes != (const IndexPacket *) NULL)
            {
              (void) CopyMagickMemory(indexes,nexus_indexes,(size_t) length*
                sizeof(*nexus_indexes));
              indexes+=length;
            }
        }
    }
  }
  virtual_nexus=DestroyNexusInfo(virtual_nexus);
  return(pixels);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+   A c q u i r e I n d e x e s F r o m C a c h e                             %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquireIndexesFromCache() returns the indexes associated with the last call
%  to SetPixelCache() or AcquirePixelCache().
%
%  The format of the AcquireIndexesFromCache() method is:
%
%      IndexPacket *AcquireIndexesFromCache(const Image *image)
%
%  A description of each parameter follows:
%
%    o image: the image.
%
*/

static inline long GetNexusInfoThreadId(void)
{
#if defined(MAGICKCORE_OPENMP_SUPPORT)
  return(omp_get_thread_num());
#else
  return(0);
#endif
}

static const IndexPacket *AcquireIndexesFromCache(const Image *image)
{
  CacheInfo
    *cache_info;

  const IndexPacket
    *indexes;

  long
    id;

  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  cache_info=(CacheInfo *) image->cache;
  id=GetNexusInfoThreadId();
  indexes=AcquireNexusIndexes(image->cache,cache_info->nexus_info[id]);
  return(indexes);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+   A c q u i r e P i x e l s F r o m C a c h e                               %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquirePixelsFromCache() returns the pixels associated with the last call
%  to SetPixelCache() or AcquirePixelCache().
%
%  The format of the AcquirePixelsFromCache() method is:
%
%      IndexPacket *AcquirePixelsFromCache(const Image *image)
%
%  A description of each parameter follows:
%
%    o pixels: AcquirePixelsFromCache() returns the pixels associated with the
%      last call to SetPixelCache() or AcquirePixelCache().
%
%    o image: the image.
%
*/
static const PixelPacket *AcquirePixelsFromCache(const Image *image)
{
  CacheInfo
    *cache_info;

  const PixelPacket
    *pixels;

  long
    id;

  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  cache_info=(CacheInfo *) image->cache;
  id=GetNexusInfoThreadId();
  pixels=AcquireNexusPixels(image->cache,cache_info->nexus_info[id]);
  return(pixels);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+   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,
%        NexusInfo *nexus_info)
%
%  A description of each parameter follows:
%
%    o cache: the pixel cache.
%
%    o nexus_info: the cache nexus to return the colormap indexes.
%
*/
MagickExport const IndexPacket *AcquireNexusIndexes(const Cache cache,
  NexusInfo *nexus_info)
{
  CacheInfo
    *cache_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);
  return(nexus_info->indexes);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%   A c q u i r e N e x u s I n f o                                           %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquireNexusInfo() allocates the NexusInfo structure.
%
%  The format of the AcquireNexusInfo method is:
%
%      NexusInfo *AcquireNexusInfo(void)
%
*/
MagickExport NexusInfo *AcquireNexusInfo(void)
{
  NexusInfo
    *nexus_info;

  nexus_info=(NexusInfo *) AcquireMagickMemory(sizeof(*nexus_info));
        if (nexus_info == (NexusInfo *) NULL)
    ThrowFatalException(ResourceLimitFatalError,"MemoryAllocationFailed");
        (void) ResetMagickMemory(nexus_info,0,sizeof(*nexus_info));
  nexus_info->signature=MagickSignature;
  return(nexus_info);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%   A c q u i r e N e x u s I n f o T h r e a d S e t                         %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquireNexusInfoThreadSet() acquires a set of views, one for each possible
%  thread.
%
%  The format of the AcquireNexusInfoThreadSet method is:
%
%      NexusInfo **AcquireNexusInfoThreadSet(const unsigned long nexuses)
%
%  A description of each parameter follows:
%
%    o nexuses: the number of nexus to acquire.
%
*/
MagickExport NexusInfo **AcquireNexusInfoThreadSet(const unsigned long nexuses)
{
  register long
    i;

  NexusInfo
    **nexus_info;

  nexus_info=(NexusInfo **) AcquireQuantumMemory(nexuses,sizeof(**nexus_info));
  if (nexus_info == (NexusInfo **) NULL)
    ThrowFatalException(ResourceLimitFatalError,"MemoryAllocationFailed");
  for (i=0; i < (long) nexuses; i++)
    nexus_info[i]=AcquireNexusInfo();
  return(nexus_info);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+   A c q u i r e N e x u s P i x e l s                                       %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AcquireNexusPixels() returns the pixels associated with the specified
%  cache nexus.
%
%  The format of the AcquireNexusPixels() method is:
%
%      const IndexPacket *AcquireNexusPixels(const Cache cache,
%        NexusInfo *nexus_info)
%
%  A description of each parameter follows:
%
%    o cache: the pixel cache.
%
%    o nexus_info: the cache nexus to return the colormap pixels.
%
*/
MagickExport const PixelPacket *AcquireNexusPixels(const Cache cache,
  NexusInfo *nexus_info)
{
  CacheInfo
    *cache_info;

  if (cache == (Cache) NULL)
    return((PixelPacket *) NULL);
  cache_info=(CacheInfo *) cache;
  assert(cache_info->signature == MagickSignature);
  if (cache_info->storage_class == UndefinedClass)
    return((PixelPacket *) NULL);
  return((const PixelPacket *) nexus_info->pixels);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+   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)
{
  CacheInfo
   *cache_info;

  const PixelPacket
    *pixels;

  long
    id;

  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  cache_info=(CacheInfo *) image->cache;
  id=GetNexusInfoThreadId();
  pixels=AcquireCacheNexus(image,virtual_pixel_method,x,y,columns,rows,
    cache_info->nexus_info[id],exception);
  return(pixels);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+   C l i p C a c h e N e x u s                                               %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  ClipCacheNexus() clips the cache nexus as defined by the image clip mask.
%  The method returns MagickTrue if the pixel region is clipped, otherwise
%  MagickFalse.
%
%  The format of the ClipCacheNexus() method is:
%
%      MagickBooleanType ClipCacheNexus(Image *image,NexusInfo *nexus_info)
%
%  A description of each parameter follows:
%
%    o image: the image.
%
%    o nexus_info: the cache nexus to clip.
%
*/
static MagickBooleanType ClipCacheNexus(Image *image,
  NexusInfo *nexus_info)
{
  CacheInfo
    *cache_info;

  MagickSizeType
    number_pixels;

  NexusInfo
    *clip_nexus,
    *image_nexus;

  register const PixelPacket
    *r;

  register IndexPacket
    *nexus_indexes,
    *indexes;

  register long
    i;

  register PixelPacket
    *p,
    *q;

  /*
    Apply clip mask.
  */
  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  if (image->clip_mask == (Image *) NULL)
    return(MagickFalse);
  cache_info=(CacheInfo *) image->cache;
  image_nexus=AcquireNexusInfo();
  clip_nexus=AcquireNexusInfo();
  if ((image_nexus == (NexusInfo *) NULL) || (clip_nexus == (NexusInfo *) NULL))
    ThrowBinaryException(CacheError,"UnableToGetCacheNexus",image->filename);
  p=GetCacheNexus(image,nexus_info->region.x,nexus_info->region.y,
    nexus_info->region.width,nexus_info->region.height,image_nexus,
    &image->exception);
  indexes=GetNexusIndexes(image->cache,image_nexus);
  q=nexus_info->pixels;
  nexus_indexes=nexus_info->indexes;
  r=AcquireCacheNexus(image->clip_mask,MaskVirtualPixelMethod,
    nexus_info->region.x,nexus_info->region.y,nexus_info->region.width,
    nexus_info->region.height,clip_nexus,&image->exception);
  number_pixels=(MagickSizeType) nexus_info->region.width*
    nexus_info->region.height;
  for (i=0; i < (long) number_pixels; i++)
  {
    if ((p == (PixelPacket *) NULL) || (r == (const PixelPacket *) NULL))
      break;
    if (PixelIntensityToQuantum(r) > ((Quantum) QuantumRange/2))
      {
        q->red=p->red;
        q->green=p->green;
        q->blue=p->blue;
        q->opacity=p->opacity;
        if ((cache_info->storage_class == PseudoClass) ||
            (cache_info->colorspace == CMYKColorspace))
          nexus_indexes[i]=indexes[i];
      }
    p++;
    q++;
    r++;