The image pixels are represented by the structure PixelPacket and are cached in-memory, or on disk, depending on the cache threshold setting. This cache is known as the "pixel cache". Pixels in the cache may not be edited directly. They must first be made visible from the cache. After an image has been read (and is therefore in the cache), the pixels are made visible and accessable by using the GetPixelCache() method which allows importing a specified region of the image. The pixels may then be accessed via the pointer returned from GetPixelCache() or the pixels member (identical values). After the pixels have been updated, they may be saved back to the cache in their original positions via SyncPixelCache().
In order to create an image with new contents, or to blindly overwrite existing contents, the method SetPixelCache() is used to reserve a pixel memory region corresponding to the pixel cache. Once the memory region has been updated, it may be written to the cache via SyncPixelCache().
When writing encoders and decoders for new image formats, it is convenient to have a high-level interface available which supports converting between external pixel representations and ImageMagick's own representation. Pixel components (red, green, blue, opacity, RGB, or RGBA) may be transferred from a user-supplied buffer into the image pixel buffer by using ReadPixelCache(). Pixel components may be transferred from the image pixel buffer into a user-supplied buffer by using WritePixelCache(). Use of this high-level interface helps protect image coders from changes to ImageMagick's pixel representation and simplifies the implementation.
The members of the Image structure are shown in the following table:
Member | Type | Description |
background_color | PixelPacket | Image background color |
blur | double | Blur factor to apply to the image when zooming. Default is 1.0 (no blur). |
border_color | PixelPacket | Image border color |
chromaticity | ChromaticityInfo | Red, green, blue, and white-point chromaticity values. |
class | ClassType | Image storage class. If DirectClass then the image packets contain valid RGB or CMYK colors. If PseudoClass then the image has a colormap referenced by pixel's index member. For C++ this member is known as "c_class" |
color_profile | ProfileInfo | ICC color profile. Specifications are available from the International Color Consortium for the format of ICC color profiles. |
colormap | PixelPacket * | PseudoColor palette array. |
colors | unsigned int | The desired number of colors. Used by QuantizeImage(). |
colorspace | ColorspaceType | Image pixel interpretation.If the colorspace is RGB the pixels are red, green, blue. If matte is true, then red, green, blue, and index. If it is CMYK, the pixels are cyan, yellow, magenta, black. Otherwise the colorspace is ignored. |
columns | unsigned int | Image width |
comments | char * | Image comments |
compression | CompressionType | Image compresion type. The default is the compression type of the specified image file. |
delay | unsigned int | Time in 1/100ths of a second (0 to 65535) which must expire before displaying the next image in an animated sequence. This option is useful for regulating the animation of a sequence of GIF images within Netscape. |
depth | unsigned int | Image depth (8 or 16). QuantumLeap must be defined before a depth of 16 is valid. |
directory | char * | Tile names from within an image montage. Only valid after calling MontageImages() or reading a MIFF file which contains a directory. |
dispose | unsigned int | GIF disposal method. This option is used to control how successive frames are rendered (how the preceding frame is disposed of) when creating a GIF animation. |
file | FILE * | Stdio stream to read image from or write image to. If set, ImageMagick will read from or write to the stream rather than opening a file. Used by ReadImage() and WriteImage(). The stream is closed when the operation completes. |
filename | char[MaxTextExtent] | Image file name to read or write. |
filesize | long int | Number of bytes of the encoded file. |
filter | FilterType | Filter to use when resizing image. The reduction filter employed has a sipngicant effect on the time required to resize an image and the resulting quality. The default filter is Lanczos which has been shown to produce high quality results when reducing most images. |
fuzz | int | Colors within this distance are considered equal. A number of algorithms search for a target color. By default the color must be exact. Use this option to match colors that are close to the target color in RGB space. |
gamma | double | Gamma level of the image. The same color image displayed on two different workstations may look different due to differences in the display monitor. Use gamma correction to adjust for this color difference. |
geometry | char * | Preferred size of the image when encoding. |
interlace | InterlaceType | The type of interlacing scheme (default NoInterlace). This option is used to specify the type of interlacing scheme for raw image formats such as RGB or YUV. NoInterlace means do not interlace, LineInterlace uses scanline interlacing, and PlaneInterlace uses plane interlacing. PartitionInterlace is like PlaneInterlace except the different planes are saved to individual files (e.g. image.R, image.G, and image.B). Use LineInterlace or PlaneInterlace to create an interlaced GIF or progressive JPEG image. |
iptc_profile | ProfileInfo | IPTC profile. Specifications are available from the International Press Telecommunications Council for IPTC profiles. |
iterations | unsigned int | Number of iterations to loop an animation (e.g. Netscape loop extension) for. |
label | char * | Image label |
list | struct _Image * | Undo image list (used only by 'display') |
magick | char[MaxTextExtent] | Image encoding format (e.g. "GIF"). |
magick_columns | unsigned int | Base image width (before transformations) |
magick_filename | char[MaxTextExtent] | Base image filename (before transformations) |
magick_rows | unsigned int | Base image height (before transformations) |
magick_time | long int | Time (as reported by POSIX time()) that image was allocated by AllocateImage(). Used by DescribeImage() to display the time spent reading the image. |
matte | unsigned int | If non-zero, then the index member of pixels represents the alpha channel. |
matte_color | PixelPacket | Image matte (transparent) color |
mean_error_per_pixel | unsigned int | The mean error per pixel computed when an image is color reduced. This parameter is only valid if verbose is set to true and the image has just been quantized. |
montage | char * | Tile size and offset within an image montage. Only valid for montage images. |
next | struct _Image * | Next image frame in sequence |
normalized_maximum_error | double | The normalized max error per pixel computed when an image is color reduced. This parameter is only valid if verbose is set to true and the image has just been quantized. |
normalized_mean_error | double | The normalized mean error per pixel computed when an image is color reduced. This parameter is only valid if verbose is set to true and the image has just been quantized. |
offset | int | Number of initial bytes to skip over when reading raw image. |
orphan | unsigned int | When set, CloneImage() clones only the current frame, creating an "orphan" frame. |
page | char * | Equivalent size of Postscript page. |
pipe | int | Set to True if image is read/written from/to a POSIX pipe. To read from (or write to) an open pipe, set this member to True, set the file member to a stdio stream representing the pipe (obtained from popen()), and invoke ReadImage()/WriteImage(). The pipe is automatically closed via pclose() when the operation completes. |
pixels | PixelPacket * | Image pixels retrieved via GetPixelCache() or initialized via SetPixelCache(). |
previous | struct _Image * | Previous image frame in sequence. |
rendering_intent | RenderingIntent | The type of rendering intent. |
rows | unsigned int | Image height |
scene | unsigned int | Image frame scene number. |
signature | char * | Image MD5 signature. Valid after SignatureImage() has been called. |
tainted | int | Set to non-zero (True) if the image pixels have been modified. |
tile_info | RectangleInfo | Describes a tile within an image. For example, if your images is 640x480 you may only want 320x256 with an offset of +128+64. It is used for raw formats such as RGB and CMYK as well as for TIFF. |
total_colors | unsigned long | The number of colors in the image after QuantizeImage(), or QuantizeImages() if the verbose flag was set before the call. Calculated by GetNumberColors(). |
units | ResolutionType | Units of image resolution |
x_resolution | double | Horizontal resolution of the image |
y_resolution | double | Vertical resolution of the image |