GraphicsMagick

- Home
- Project
- Download
- Install
- Source
- News
- Utilities
- Programming
- Reference

# pixel_iterator

## Pixel iterator pattern support functions

Contents

- InitializePixelIteratorOptions
- PixelIterateMonoRead
- PixelIterateMonoSet
- PixelIterateMonoModify
- PixelIterateDualRead
- PixelIterateDualModify
- PixelIterateDualNew
- PixelIterateTripleModify
- PixelIterateTripleNew

# InitializePixelIteratorOptions

## Synopsis

    void InitializePixelIteratorOptions( PixelIteratorOptions *options,
                                         ExceptionInfo *exception );

## Description

InitializePixelIteratorOptions() assigns default options to a user-provided PixelIteratorOptions structure. This function should always be used to initialize the PixelIteratorOptions structure prior to making any changes to it.

The format of the InitializePixelIteratorOptions method is:

    void InitializePixelIteratorOptions( PixelIteratorOptions *options,
                                         ExceptionInfo *exception );

options:
  pointer to PixelIteratorOptions structure to initialize.
exception:
  Return any errors or warnings in this structure.

# PixelIterateMonoRead

## Synopsis

    MagickPassFail PixelIterateMonoRead( PixelIteratorMonoReadCallback call_back,
                                         const PixelIteratorOptions *options,
                                         const char *description, void *mutable_data,
                                         const void *immutable_data, const long x, const long y,
                                         const unsigned long columns, const unsigned long rows,
                                         const Image *image, ExceptionInfo *exception );

## Description

PixelIterateMonoRead() iterates through a region of an image and invokes a user-provided callback function (of type PixelRowIteratorMonoReadCallback) for a row of pixels. This is useful to support simple operations such as statistics computation.

The format of the PixelIterateMonoRead method is:

    MagickPassFail PixelIterateMonoRead( PixelIteratorMonoReadCallback call_back,
                                         const PixelIteratorOptions *options,
                                         const char *description, void *mutable_data,
                                         const void *immutable_data, const long x, const long y,
                                         const unsigned long columns, const unsigned long rows,
                                         const Image *image, ExceptionInfo *exception );

call_back:
  A user-provided C callback function which is passed the address of pixels from the image.
options:
  Pixel iterator execution options (may be NULL).
description:
  textual description of operation being performed.
mutable_data:
  User-provided mutable context data.
immutable_data:
  User-provided immutable context data.
x:
  The horizontal ordinate of the top left corner of the region.
y:
  The vertical ordinate of the top left corner of the region.
columns:
  Width of pixel region
rows:
  Height of pixel region
image:
  The address of the Image.
exception:
  If an error is reported, this argument is updated with the reason.

# PixelIterateMonoSet

## Synopsis

    MagickPassFail PixelIterateMonoSet( PixelIteratorMonoModifyback call_back,
                                        const PixelIteratorOptions *options,
                                        const char *description, void *mutable_data,
                                        const void *immutable_data, const long x, const long y,
                                        const unsigned long columns, const unsigned long rows,
                                        Image *image, ExceptionInfo *exception );

## Description

PixelIterateMonoSet() iterates through a region of an image and invokes a user-provided callback function (of type PixelIteratorMonoModifyCallback) to initialize a region of pixels from scratch. The difference from PixelIterateMonoModify() is that the output pixels are not initialized from the underlying store so it is more efficient when outputting a new image or when the existing pixels are intentionally discarded. This is useful for operations such as setting the pixel color.

The format of the PixelIterateMonoSet method is:

    MagickPassFail PixelIterateMonoSet( PixelIteratorMonoModifyback call_back,
                                        const PixelIteratorOptions *options,
                                        const char *description, void *mutable_data,
                                        const void *immutable_data, const long x, const long y,
                                        const unsigned long columns, const unsigned long rows,
                                        Image *image, ExceptionInfo *exception );

call_back:
  A user-provided C callback function which is passed the address of pixels to be initialized in the image.
options:
  Pixel iterator execution options (may be NULL).
description:
  textual description of operation being performed.
mutable_data:
  User-provided mutable context data.
immutable_data:
  User-provided immutable context data.
x:
  The horizontal ordinate of the top left corner of the region.
y:
  The vertical ordinate of the top left corner of the region.
columns:
  Width of pixel region
rows:
  Height of pixel region
image:
  The address of the Image.
exception:
  If an error is reported, this argument is updated with the reason.

# PixelIterateMonoModify

## Synopsis

    MagickPassFail PixelIterateMonoModify( PixelIteratorMonoModifyCallback call_back,
                                           const PixelIteratorOptions *options,
                                           const char *description, void *mutable_data,
                                           const void *immutable_data, const long x,
                                           const long y, const unsigned long columns,
                                           const unsigned long rows, Image *image,
                                           ExceptionInfo *exception );

## Description

PixelIterateMonoModify() iterates through a region of an image and invokes a user-provided callback function (of type PixelIteratorMonoModifyCallback) to modify a region of pixels. This is useful to support simple operations such as level shifting, colorspace translation, or thresholding.

The format of the PixelIterateMonoModify method is:

    MagickPassFail PixelIterateMonoModify( PixelIteratorMonoModifyCallback call_back,
                                           const PixelIteratorOptions *options,
                                           const char *description, void *mutable_data,
                                           const void *immutable_data, const long x,
                                           const long y, const unsigned long columns,
                                           const unsigned long rows, Image *image,
                                           ExceptionInfo *exception );

call_back:
  A user-provided C callback function which is passed the address of pixels from the image.
options:
  Pixel iterator execution options (may be NULL).
description:
  textual description of operation being performed.
mutable_data:
  User-provided mutable context data.
immutable_data:
  User-provided immutable context data.
x:
  The horizontal ordinate of the top left corner of the region.
y:
  The vertical ordinate of the top left corner of the region.
columns:
  Width of pixel region
rows:
  Height of pixel region
image:
  The address of the Image.
exception:
  If an error is reported, this argument is updated with the reason.

# PixelIterateDualRead

## Synopsis

    MagickPassFail PixelIterateDualRead( PixelIteratorDualReadCallback call_back,
                                         const PixelIteratorOptions *options,
                                         const char *description, void *mutable_data,
                                         const void *immutable_data, const unsigned long columns,
                                         const unsigned long rows, const Image *first_image,
                                         const long first_x, const long first_y,
                                         const Image *second_image, const long second_x,
                                         const long second_y, ExceptionInfo *exception ); ;

## Description

PixelIterateDualRead() iterates through pixel regions of two images and invokes a user-provided callback function (of type PixelIteratorDualReadCallback) for each row of pixels. This is useful to support operations such as image comparison.

The format of the PixelIterateDualRead method is:

    MagickPassFail PixelIterateDualRead( PixelIteratorDualReadCallback call_back,
                                         const PixelIteratorOptions *options,
                                         const char *description, void *mutable_data,
                                         const void *immutable_data, const unsigned long columns,
                                         const unsigned long rows, const Image *first_image,
                                         const long first_x, const long first_y,
                                         const Image *second_image, const long second_x,
                                         const long second_y, ExceptionInfo *exception ); ;

call_back:
  A user-provided C callback function which is passed the address of pixels from each image.
options:
  Pixel iterator execution options (may be NULL).
description:
  textual description of operation being performed.
mutable_data:
  User-provided mutable context data.
immutable_data:
  User-provided immutable context data.
columns:
  Width of pixel region
rows:
  Height of pixel region
first_image:
  The address of the first Image.
first_x:
  The horizontal ordinate of the top left corner of the first region.
first_y:
  The vertical ordinate of the top left corner of the first region.
second_image:
  The address of the second Image.
second_x:
  The horizontal ordinate of the top left corner of the second region.
second_y:
  The vertical ordinate of the top left corner of the second region.
exception:
  If an error is reported, this argument is updated with the reason.

# PixelIterateDualModify

## Synopsis

    MagickPassFail PixelIterateDualModify( PixelIteratorDualModifyCallback call_back,
                                           const PixelIteratorOptions *options,
                                           const char *description, void *mutable_data,
                                           const void *immutable_data,
                                           const unsigned long columns, const unsigned long rows,
                                           const Image *source_image, const long source_x,
                                           const long source_y, Image *update_image,
                                           const long update_x, const long update_y,
                                           ExceptionInfo *exception );

## Description

PixelIterateDualModify() iterates through pixel regions of two images and invokes a user-provided callback function (of type PixelIteratorDualModifyCallback) for each row of pixels. This is useful to support operations such as composition.

The format of the PixelIterateDualModify method is:

    MagickPassFail PixelIterateDualModify( PixelIteratorDualModifyCallback call_back,
                                           const PixelIteratorOptions *options,
                                           const char *description, void *mutable_data,
                                           const void *immutable_data,
                                           const unsigned long columns, const unsigned long rows,
                                           const Image *source_image, const long source_x,
                                           const long source_y, Image *update_image,
                                           const long update_x, const long update_y,
                                           ExceptionInfo *exception );

call_back:
  A user-provided C callback function which reads from a region of source pixels and updates a region of destination pixels.
options:
  Pixel iterator execution options (may be NULL).
description:
  textual description of operation being performed.
mutable_data:
  User-provided mutable context data.
immutable_data:
  User-provided immutable context data.
columns:
  Width of pixel region
rows:
  Height of pixel region
source_image:
  The address of the constant source Image.
source_x:
  The horizontal ordinate of the top left corner of the source region.
source_y:
  The vertical ordinate of the top left corner of the source region.
update_image:
  The address of the update Image.
update_x:
  The horizontal ordinate of the top left corner of the update region.
update_y:
  The vertical ordinate of the top left corner of the update region.
exception:
  If an error is reported, this argument is updated with the reason.

# PixelIterateDualNew

## Synopsis

    MagickPassFail PixelIterateDualNew( PixelIteratorDualNewCallback call_back,
                                        const PixelIteratorOptions *options,
                                        const char *description, void *mutable_data,
                                        const void *immutable_data, const unsigned long columns,
                                        const unsigned long rows, const Image *source_image,
                                        const long source_x, const long source_y,
                                        Image *new_image, const long new_x,
                                        const long new_y, ExceptionInfo *exception );

## Description

PixelIterateDualNew() iterates through pixel regions of two images and invokes a user-provided callback function (of type PixelIteratorDualNewCallback) for each row of pixels. This is used if a new output image is created based on an input image. The difference from PixelIterateDualModify() is that the output pixels are not initialized so it is more efficient when outputting a new image.

The format of the PixelIterateDualNew method is:

    MagickPassFail PixelIterateDualNew( PixelIteratorDualNewCallback call_back,
                                        const PixelIteratorOptions *options,
                                        const char *description, void *mutable_data,
                                        const void *immutable_data, const unsigned long columns,
                                        const unsigned long rows, const Image *source_image,
                                        const long source_x, const long source_y,
                                        Image *new_image, const long new_x,
                                        const long new_y, ExceptionInfo *exception );

call_back:
  A user-provided C callback function which reads from a region of source pixels and initializes a region of destination pixels.
options:
  Pixel iterator execution options (may be NULL).
description:
  textual description of operation being performed.
mutable_data:
  User-provided mutable context data.
immutable_data:
  User-provided immutable context data.
columns:
  Width of pixel region
rows:
  Height of pixel region
source_image:
  The address of the constant source Image.
source_x:
  The horizontal ordinate of the top left corner of the source region.
source_y:
  The vertical ordinate of the top left corner of the source region.
new_image:
  The address of the new Image.
new_x:
  The horizontal ordinate of the top left corner of the new region.
new_y:
  The vertical ordinate of the top left corner of the new region.
exception:
  If an error is reported, this argument is updated with the reason.

# PixelIterateTripleModify

## Synopsis

    MagickPassFail PixelIterateTripleModify( PixelIteratorTripleModifyCallback call_back,
                                             const PixelIteratorOptions *options,
                                             const char *description, void *mutable_data,
                                             const void *immutable_data,
                                             const unsigned long columns, const unsigned long rows,
                                             const Image *source1_image,
                                             const Image *source2_image, const long source_x,
                                             const long source_y, Image *update_image,
                                             const long update_x, const long update_y,
                                             ExceptionInfo *exception );

## Description

PixelIterateTripleModify() iterates through pixel regions of three images and invokes a user-provided callback function (of type PixelIteratorTripleModifyCallback) for each row of pixels. The first two images are read-only, while the third image is read-write for update. Access of the first two images is done lock-step using the same coordinates. This is useful to support operations such as image differencing.

The format of the PixelIterateTripleModify method is:

    MagickPassFail PixelIterateTripleModify( PixelIteratorTripleModifyCallback call_back,
                                             const PixelIteratorOptions *options,
                                             const char *description, void *mutable_data,
                                             const void *immutable_data,
                                             const unsigned long columns, const unsigned long rows,
                                             const Image *source1_image,
                                             const Image *source2_image, const long source_x,
                                             const long source_y, Image *update_image,
                                             const long update_x, const long update_y,
                                             ExceptionInfo *exception );

call_back:
  A user-provided C callback function which reads from a region of source pixels and updates a region of destination pixels.
options:
  Pixel iterator execution options (may be NULL).
description:
  textual description of operation being performed.
mutable_data:
  User-provided mutable context data.
immutable_data:
  User-provided immutable context data.
columns:
  Width of pixel region
rows:
  Height of pixel region
source1_image:
  The address of the constant source 1 Image.
source2_image:
  The address of the constant source 2 Image.
source_x:
  The horizontal ordinate of the top left corner of the source regions.
source_y:
  The vertical ordinate of the top left corner of the source regions.
update_image:
  The address of the update Image.
update_x:
  The horizontal ordinate of the top left corner of the update region.
update_y:
  The vertical ordinate of the top left corner of the update region.
exception:
  If an error is reported, this argument is updated with the reason.

# PixelIterateTripleNew

## Synopsis

    MagickPassFail PixelIterateTripleNew( PixelIteratorTripleNewCallback call_back,
                                          const PixelIteratorOptions *options,
                                          const char *description, void *mutable_data,
                                          const void *immutable_data,
                                          const unsigned long columns, const unsigned long rows,
                                          const Image *source1_image,
                                          const Image *source2_image, const long source_x,
                                          const long source_y, Image *new_image,
                                          const long new_x, const long new_y,
                                          ExceptionInfo *exception );

## Description

PixelIterateTripleNew() iterates through pixel regions of three images and invokes a user-provided callback function (of type PixelIteratorTripleNewCallback) for each row of pixels. The first two images are read-only, while the third image is read-write for update. Access of the first two images is done lock-step using the same coordinates. This is used if a new output image is created based on two input images. The difference from PixelIterateTripleModify() is that the output pixels are not initialized so it is more efficient when outputting a new image.

The format of the PixelIterateTripleNew method is:

    MagickPassFail PixelIterateTripleNew( PixelIteratorTripleNewCallback call_back,
                                          const PixelIteratorOptions *options,
                                          const char *description, void *mutable_data,
                                          const void *immutable_data,
                                          const unsigned long columns, const unsigned long rows,
                                          const Image *source1_image,
                                          const Image *source2_image, const long source_x,
                                          const long source_y, Image *new_image,
                                          const long new_x, const long new_y,
                                          ExceptionInfo *exception );

call_back:
  A user-provided C callback function which reads from a region of source pixels and initializes a region of destination pixels.
options:
  Pixel iterator execution options (may be NULL).
description:
  textual description of operation being performed.
mutable_data:
  User-provided mutable context data.
immutable_data:
  User-provided immutable context data.
columns:
  Width of pixel region
rows:
  Height of pixel region
source1_image:
  The address of the constant source 1 Image.
source2_image:
  The address of the constant source 2 Image.
source_x:
  The horizontal ordinate of the top left corner of the source regions.
source_y:
  The vertical ordinate of the top left corner of the source regions.
new_image:
  The address of the new Image.
new_x:
  The horizontal ordinate of the top left corner of the new region.
new_y:
  The vertical ordinate of the top left corner of the new region.
exception:
  If an error is reported, this argument is updated with the reason.