AccuSoft ImageGear v16
Windows 32-Bit Platforms
For DLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


Copyright Information

Information in this document is subject to change without notice. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of AccuSoft® Corporation.

© 1996-2008 AccuSoft® Corporation. All rights reserved.

AccuSoft and ImageGear are registered trademarks of AccuSoft Corporation. High Performance Imaging and the "half gear" logo are trademarks of AccuSoft Corporation. All rights reserved. All other company and brand names are trademarks or registered trademarks of their respective owners.

This manual and the software described in it are both products of the USA.

Document revision number: 4-14-08

AccuSoft Corporation, 71 Lyman Street, Northborough, MA 01532

(508) 351-9092,

(508) 351-9086 (Fax)

Internet address: www.accusoft.com


Volume 1: User Guide

The first Volume of the ImageGear User's Manual provides you with the following information:

  • The Introduction Chapter provides information about ImageGear features, improvements, component structure, plus information about AccuSoft's Product Support Services and descriptions of AccuSoft's other products.
  • The Installation Chapter provides system requirements information as well as installation instructions. It also describes the structure of installed ImageGear files and the ImageGear Licensing process.
  • The Getting Started Chapter describes how to incorporate ImageGear's imaging capabilities into your own applications by using the sample source imaging programs provided with your toolkit.
  • The Understanding Bitmap Images Chapter explains Device-Independent Bitmaps (DIBs), the memory structures that are at the heart of ImageGear's architecture. The majority of ImageGear functions operate either directly or indirectly upon DIBs. Device-Dependent Bitmaps (DDBs) are also discussed, as is the meaning of Pixels (the building blocks of bitmaps), and all color and grayscale representations supported by ImageGear.
  • The Using ImageGear Chapter provides information about how to call an ImageGear function, including setting up the variables and structures passed as arguments, and details which functions to use to perform the variety of imaging tasks. It also explains how to work with some ImageGear components API.
  • The File Format Reference Chapter provides detailed information on each of the file formats supported by ImageGear (see the section ImageGear Supported File Formats), its control parameters, supported features and compressions, plus "at-a-glance" tables that describe the features supported by each format and provide guidelines on which formats may be most suitable when speed, storage space, or similar considerations are important.
  • The AccuSoft Image Guarantee provides information about how to identify an imaging problem, if it occurs.

Besides this there is some supplemental information:

  • See Appendix: Function Error Return Codes for lists of error codes returned by ImageGear functions. These error codes are classified into different groups and numbered in alphabetical and numerical orders.
  • See Appendix: Non-Image Data Storage for detailed info about TIFF, JPEG, EXIF-TIFF, EXIF-JPEG, IPTC, PNG and GIF formats non-image data storage.
  • Appendix: Recognition Component Specifications provides you with detailed specifications of ImageGear Recognition component characters, codepages, languages lists, modules, etc.
  • Appendix: TWAIN Scanning Capabilities represents the descriptions of the most oftenly used TWAIN scanning capabilities.
  • Appendix: DIB Pointer Transition Guide for ImageGear tells you how to use the DIB Pointer public API.
  • SOFTWARE LICENSE AGREEMENT provides the AccuSoft SOFTWARE LICENSE AGREEMENT and Software Support and Maintenance Policy documents.

This Volume also provides a Glossary and Bibliography.


Introduction

ImageGear is the most advanced way to create, control, and deliver more secure, high-quality imaging applications. Using ImageGear, you can easily add powerful imaging capability to your applications. ImageGear supports all of the most commonly used graphics file formats (and many more), providing complete compatibility when developing applications across multiple platforms, or when developing for users who have a variety of target systems.

ImageGear features include analysis, correction, and manipulation of both computer-generated and scanned images, "special effects", file format conversion, image enhancement through color reduction/promotion/dithering, and GUI (Graphical User Interface) functions. The toolkit supports the following bit depths internally: 1, 4, 8-bit gray level, 8i, 9-16-bit gray level, 24, and 32. The toolkit can also read all the additional bit depths possible for the supported file formats.

With ImageGear , you are assured of the high quality and performance you expect from AccuSoft, the industry leader in image processing toolkits. In addition, ImageGear's integrity is backed by the AccuSoft Image Guarantee: ImageGear is guaranteed to read all valid raster images in the supported formats. See the Chapter AccuSoft Image Guarantee for more information.


In This Guide

This manual consists of two Volumes, organized as follows:

Volume 1: User Guide provides the following information about ImageGear:

  • The Introduction chapter includes information about ImageGear features, improvements, ImageGear components structure, plus information about AccuSoft's Product Support Services and descriptions of AccuSoft's other products.
  • The Installation chapter explains how to install ImageGear. It also describes the structure of installed ImageGear files and the ImageGear Licensing process.
  • The Getting Started chapter demonstrates how to incorporate ImageGear's imaging capabilities into your own applications by using the sample source imaging programs provided with your toolkit.
  • The Understanding Bitmap Images chapter helps application developers to thoroughly understand Device-Independent Bitmaps (DIBs), the memory structures that are at the heart of ImageGear's architecture. The majority of ImageGear functions operate either directly or indirectly upon DIBs. Device-Dependent Bitmaps (DDBs), the meaning of pixels (the building blocks of bitmaps), and all color and grayscale representations supported by ImageGear are also discussed.
  • The Using ImageGear chapter explains how to call an ImageGear function, including setting up the variables and structures passed as arguments, and details which functions to use to perform the variety of imaging tasks mentioned in the Overview above.
  • The File Format Reference chapter provides detailed information on each of the file formats supported by ImageGear, its control parameters, supported features and compressions, plus "at-a-glance" tables that describe the features supported by each format and provide guidelines on which formats may be most suitable when speed, storage space, or similar considerations are important.
  • The AccuSoft Image Guarantee chapter explains the ImageGear Image Guarantee and how to identify the imaging problem if it occurs.

This volume also includes the following appendices:

  • Appendix: Function Error Return Codes lists the error codes returned by ImageGear functions. These error codes are classified in different groups and numbered in alphabetical and numerical orders.
  • Appendix: Non-Image Data Storage provides detailed info about TIFF, JPEG, EXIF-TIFF, EXIF-JPEG, IPTC, PNG and GIF formats non-image data storage.
  • Appendix: Recognition Component Specifications provides detailed specifications of ImageGear Recognition component characters, codepages, languages lists, modules, etc.
  • Appendix: TWAIN Scanning Capabilities describes the most frequently used TWAIN scanning capabilities.
  • Appendix: DIB Pointer Transition Guide for ImageGear tells you how to use the DIB Pointer public API.
  • SOFTWARE LICENSE AGREEMENT provides the AccuSoft's SOFTWARE LICENSE AGREEMENT and Software Support and Maintenance Policy documents.
  • Glossary
  • Bibliography

Volume 2: API Reference provides detailed information about each function or control parameter of the following ImageGear Components:

  • Core Component API Function Reference
  • ARTX Component API Function Reference
  • ART Component API Function Reference
  • FreqIP Component API Function Reference
  • GUI Component API Function Reference
  • ImageClean Component API Function Reference
  • ISIS Component API Function Reference
  • JPEG2000 Component API Function Reference
  • MD Component API Function Reference
  • PDF Component API Function Reference
  • Recognition Component API Function Reference
  • TWAIN Component API Function Reference
  • Vector Component API Function Reference

This manual also provides an an Index..

NOTE: The contents of this manual are also included in their entirety in the ImageGear Help (HTML Help *.chm format). The HTML Help documentation files for ImageGear DLL and its components are installed in the ...\Accusoft\ImageGear v16\...\Documentation directory when installing the product.

Refer to the sections Directory Structure and Description of Installed Files for more information on where files are installed.


What's New in ImageGear

ImageGear version 16 introduces many new features and enhancements, including the following:

  • PDF Enhancements
  • Vector Enhancements
  • Digital Camera Raw Format Enhancements
  • File Format Enhancements
  • Image Processing Enhancements
  • Miscellaneous New Features


PDF Enhancements

  • Support for 3D PDF Content
  • PDF/X and PDF/A Verifiers
  • PDF Display Performance Optimization

Support for 3D PDF Content

ImageGear v16 introduces support for 3D PDF content. Starting with version 1.6, PDF introduces the capability for collections of 3D objects, such as those used by CAD formats, to be embedded in PDF files. Such collections are called 3D models, and PDF refers to them as 3D Artwork. In PDF documents, 3D Artwork is represented by 3D annotations stored in Universal 3D (U3D) format (see Support for Universal 3D (U3D)).

See Also:

Working with 3D Artwork

Image Mark

PDF Marks

PDF/X and PDF/A Verifiers

There is new ImageGear API that verifies compliance with PDF/X and PDF/A standards, which are defined by the International Organization for Standardization (ISO).

  • PDF/X standards apply to graphic content exchange

The most widely used standards for a print publishing workflow are several PDF/X formats: PDF/X-1a, PDF/X-3, and PDF/X-4.

  • PDF/A standards apply to long-term archiving of electronic documents

The most widely used standards for PDF archiving are PDF/A-1a and PDF/A-1b (for less stringent requirements).

For more information on PDF/X and PDF/A, see the ISO website.

See Also:

PDF Standards

HIG_PDF_PREFLIGHT

HIG_PDF_PREFLIGHT_REPORT

PDF Display Performance Optimization

ImageGear 16.0 introduces optimized PDF display rendering and scrolling capabilities. IG_PDF_page_reset_display_cache causes IG display API to re-render PDF page content for display.


Vector Enhancements

The following vector enhancements are introduced in ImageGear v16:

  • Support for Universal 3D (U3D)
  • Support for Design Web Format (DWF)
  • Support for Gradient Fill Type

Support for Universal 3D (U3D)

U3D file format, short for "Universal 3D", is a universal vector standard for storing three-dimensional data of all kinds to facilitate data exchange. The U3D format is natively supported by PDF, and 3D objects in U3D format can be inserted into PDF document files and interactively visualized by PDF viewers (also see Support for 3D PDF Content).

The ImageGear U3D Vector Component supports reading, writing and rasterizing the U3D vector files.

Support for Design Web Format (DWF)

DWF is an open file format developed by AutoDesk for storing DWG files on the Internet. DWF contains a vector based description of drawings and illustrations.

Support for Gradient Fill Type

Support for linear and radial gradient filling of vector objects has been added. Linear gradient filling specifies a transition of color from a start to an end point of the filling. Radial gradient specifies a transition from a start point to the outer circle of the filling. Gradient filling uses an array of "stops" to define the transition function.

See Also:

Gradient concept

IG_vect_drwng_create_gradientfilltype

IG_vect_gradient_add_stop


Digital Camera Raw Format Enhancements

ImageGear version 16 introduces the following Digital Camera Raw format enhancements:

  • Support for more than 80 new digital camera Raw file formats. See ImageGear Supported Digital Camera RAW Formats for a complete list of supported Raw Formats. Also see Working with ImageGear Digital Camera RAW Filter .
  • Interactive GUI for Digital Camera RAW color reconstruction. See Reconstructing Camera Raw Images with ImageGear Processing API and Control Parameters for the Camera Raw Filter and Headerless Camera Raw filters for more information.


File Format Enhancements

ImageGear v16 introduces the following new file format enhancements:

  • Support for the new file format: XPS. The XPS Document format represents a set of related pages with a fixed layout, which are organized as one or more documents, in the traditional meaning of the word.
  • ImageGear provides support for the Adobe PSB (Photoshop Big) or Large Document format, which is a newer version of Adobe PSD designed for files over 2 gigabytes, supporting up to 300,000 pixels in any dimension. The PSB format is identical to the Photoshop native format (PSD) in many ways.
  • ImageGear now allows users to load layered Photoshop image files (Adobe PSD and Adobe PSB) and retain image layers for editing. Users can also create new image layers, delete existing ones, as well as flatten and display the selected composition of image layers. See Working with ImageGear Layers for more information.
  • Support for the Spot Color Scheme (Pantone and others). See Working with Spot Colors.
  • Support for XMP metadata. For more information, see Working with XMP Metadata and XMP Non-Image Data Structure.


Image Processing Enhancements

ImageGear v16 introduces new Image Processing enhancements in the following categories:

  • ImageClean Enhancements
  • Mathematical Morphology
  • Special Effects

ImageClean Enhancements

There are the following new ImageClean features:

  • Punch holes removal

IG_IC_remove_punch_holes automatically detects and removes the punch holes on a 1-bit scanned image. It works for most common hole puncher standards including 2, 3, 4 and 5 hole puncher marks. The method takes a 1-bit image page and the set of advanced parameters specifying the location and diameter of punch holes.

  • Line removal

IG_IC_remove_lines automatically detects and removes horizontal and vertical solid and broken lines on the 1-bit scanned image. The method takes a 1-bit image page and the set of advanced parameters specifying the line's attributes.

  • Dot Line removal

IG_IC_remove_dot_lines automatically detects and removes horizontal and vertical dotted lines on the 1-bit scanned image. The method takes a 1-bit image page and the set of advanced parameters specifying the attributes to be used for the processing.

Mathematical Morphology

The field of mathematical morphology contributes a wide range of operators to image processing, all based around a few simple mathematical concepts from set theory. The operators are particularly useful for the analysis of binary images and common usages include edge detection, noise removal, image enhancement and image segmentation.

The following morphology ImageProcessing functions have been added: IG_IP_erode and IG_IP_NR_ROI_mask_erode, IG_IP_dilate and IG_IP_NR_ROI_mask_dilate , IG_IP_open, IG_IP_close.

See Also:

Mathematical Morphology

Special Effects

ImageGear version 16 introduces the following new ImageProcessing effects:

  • Area Detection - The IG_IP_detect_redeye_area detects an area around specified point where the colors correspond to the point color with the specified threshold.
  • Red Eye Removal - Red-eye removal removes the "red eye" effect in color images by converting the red color in the eye to the new specified color. The IG_IP_remove_redeye removes red eye for every point in the ROI of a hIGear image. See Red-Eye Removal for more information.
  • Solarize - IG_FX_solarize mimics the accidental exposure of photographic film to light.
  • Radial Wave (Ripple) This IG_FX_radial_wave effect warps the image in concentric rings.
  • Pinch - IG_FX_pinch transforms the image by making it appear as if it were pinched in the center.
  • Perspective - The IG_FX_perspective effect provides a perspective-like effect by placing image corners to the specified points, and stretching the image linearly between them.
  • Mosaic -
    • IG_FX_pixelate function gives groups of pixels identical values, and optionally adds borders between these groups. The groups can have the shape of rectangle, rounded rectangle or ellipse. This transform effectively reduces the resolution of the image, and can make it appear that you have zoomed in on a smaller image.
    • IG_FX_mosaic_tiles creates a mosaic effect by dividing a bitmap into tiles of a specified shape and size, changing the color of all pixels in each tile to the average color of pixels within the tile, and adding 3D borders between the tiles.
  • Directional Wave - The IG_FX_directional_wave function warps the image in a specific direction.
  • Warping (Cylinder, Parabolic and Sphere) - The IG_FX_cylinder, IG_FX_parabola, and IG_FX_sphere functions perform a point-to-point stretch of the image to give a warping effect.
  • Shear - The IG_FX_shear function applies a shearing effect to an image, moving the image rasters or columns according to the specified offsets.
  • Aging - The IG_FX_aging function applies an aging effect to make an image look older.
  • Spatter - The IG_FX_spatter function applies a spatter effect to an image, making it look to have been painted in the impressionist style of painting.
  • Shadow - The IG_IP_drop_shadow function adds a drop shadow to an image.
  • Oilify - The IG_FX_oilify function makes the image appear similar to an oil painting.
  • Functional Light -
    • The IG_FX_directional_light function adds bars of light according to a sine wave pattern.
    • The IG_FX_radial_light function adds circles of light according to a sine wave pattern.
    • The IG_FX_free_directional_light function adds bars of light according to a custom pattern.
    • The IG_FX_free_radial_light function adds circles of light according to a custom pattern.
  • Fragmentation - The IG_FX_fragment function fragments an image into four blended images which move diagonally outward from the original image.
  • Lens Flare - The IG_FX_lens_flare function applies a lens flare effect to the image.
  • Pointillist - The IG_FX_pointillist function makes the image appear to have been painted in the pointillism style of painting.
See Also:

Special Effects

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


Miscellaneous New Features

  • Bilinear and bicubic interpolation support for down size resize. See IG_IP_resize, IG_IP_resize_bkgrnd, IG_IP_resize_bkgrnd_ex, and IG_IP_resize_ex.
  • Added capability to save a multi-page image into memory. Saving an Image to Memory and Saving Images to Memory.
  • Implemented the floodfill functionality to fill an image area with a specified color. See IG_DIB_flood_fill.
  • Implemented the new function to transform the image pixel values, using a LUT (IG_IP_transform_with_LUT_ex).
  • The Multimedia component now supports DirectShow. DirectShow is a Microsoft framework and API for working with multimedia data. It supports a variety of formats. You can use the IG_mult_...() functions to access still images, animations, movies with video and audio, and audio-only files loaded and exported on the fly from DirectShow. See Multimedia Format: DirectShow for more information.
  • New VS 2008 samples are available.
  • Added Top-Left corner padding mode to the IP resize functionality.
  • Implemented support for noncompliant TGA RGBA images.


ImageGear Overview

ImageGear and its Components provide the most comprehensive set of imaging features available in the industry. It provides a complete set of over 700 functions focused on the following features:

  • High Speed Display
  • Image Loading and Saving
  • Printing
  • Advanced TWAIN Scanning
  • Image Processing
  • Special Effects
  • Pixel Access
  • ROI Processing
  • Graphical User Interface (GUI)
  • Format Conversion
  • Compression
  • Animation
  • Transitions
  • Native CMYK Support
  • ImageClean™ Auto-Image Correction
  • Database
  • Annotations
  • Built-in Internet Support (URL, FTP, Gopher)


High Speed Display

ImageGear gives you complete control over how your application displays each of its images. Among the attributes you can set on an image-by-image basis are:

  • Auto-color reduction for low color modes
  • High-quality display for all video modes
  • Contrast/Brightness control
  • Display effects (wipes, blocks, etc.)
  • Color reduction (several types)
  • Transparency
  • Gamma correction
  • Dithering
  • Rotation
  • The portion of the image to display (this array of pixels within the DIB bitmap is called the Image Rectangle)
  • How to fit the Image Rectangle to the Device Rectangle
  • The background fill pattern and color to use (for any area of the Device Rectangle left vacant by the image)
  • Region within the display area the image is to be displayed (this area is called the Device Rectangle)
  • Center image in window
  • Fit to width, height, window
  • Precision scrolling
  • Sub-region display
  • Auto-aspect ratio
  • Preserve black and preserve white display for 1-bit images
  • Sub-second display rotation supported
  • Faster image display
  • Anti-alias display
  • Huge image display capability
  • Merge 2 Images during display
  • 4x faster scale-to-gray
  • Also, by using the image's LUTs (Look Up Tables), you can cause the colors in the image's color palette to be translated to other colors you select (and therefore you can, for example, display an 8-bit grayscale image in any 256 colors you choose).
  • All of the above display attributes affect the display only. They do not alter either the image bitmap or the color palette in the DIB.
  • In addition, any time your image is being displayed, you can center, zoom, or scroll it from within your application.
See Also:

Loading Images

Saving Images

Displaying Images

Thread Safety

Understanding Display Options

Color Reduction

Color Promotion

Contrast Alteration

Working with Format Filters

Working with ImageGear Color Profile Manager

Working with Global Control Parameters

Working with Color Space Conversion Engine

Working with Grayscale Look Up Tables

Working with Multi-page Images

Working with Stripped Images

Working with Tiled Images

Working with Run Ends Format

Working with ImageGear Digital Camera RAW Filter


Image Loading and Saving

ImageGear now supports over 200 raster file formats. This far exceeds all other image toolkit vendors. AccuSoft also is the only company willing to guarantee that all images in the listed formats will be displayed correctly!

See Also:

Loading Images

Saving Images

Displaying Images


Printing

  • Print to any Windows printer with complete control.
  • Auto-color reduction for high-quality printing.
  • Single- or multi-page printing.
  • ImageGear automatically overcomes several inherent limitations of printer drivers to ensure your images print at the highest quality possible.
  • ImageGear's printing functionality includes automatic sizing to full page, half, quarter, eighth, and sixteenth, with auto page centering, or specific placement.
  • Printing many images to a single page is as simple as specifying the location of each image.
  • Images can be printed to any location and at any size desired.
  • ImageGear includes a sample to illustrate printing a single image onto multiple pages for creating posters of any size.
See Also:

Printing Images


Advanced TWAIN Scanning

ImageGear supports TWAIN 1.6, 1.7, 1.8, and 1.9; it works with a wider variety of scanner devices, digital cameras, and video capture boards. No TWAIN toolkit is easier or more comprehensive.

ImageGear includes a wide array of functions, providing the developer precise control of the scanning process, including:

  • Control of the TWAIN transfer mode
  • Control of the available TWAIN device listing
  • Control of the scanning area
  • Control of the brightness and contrast
  • Control of the DPI (dots-per-inch resolution)
  • Control of the display of the TWAIN UI
  • Setting of a callback function to gain control during scanning
  • Control of the ADF (Automatic Document Feeder) for multi-page scanning
  • Control of scanner capabilities
See Also:

ImageGear TWAIN Component

Using ImageGear Twain Component

TWAIN Component API Function Reference

Appendix: TWAIN Scanning Capabilities


Image Processing

  • Region of interest (ROI) support for basic rectangles as well as ellipses, polygons, and other shapes.
  • The most complete color space support, including color space conversions, color separation and combination, support for any color space found in any of the 200 supported formats, and support for color spaces such as CMYK without conversion to RGB for perfect fidelity.
  • Powerful color reduction for maximum quality and minimum size.
  • Encryption and decryption for entire image or any part of image.
  • Matrix convolutions of any size with pre-defined or user-supplied matrix values.
  • Special effects, automatic image correction, intelligent re-sizing, and much more.
See Also:

Image Processing

Core Component API Function Reference


Special Effects

ImageGear provides the following special effects:

  • Blur
  • Spotlight
  • Emboss
  • Stitch
  • Chroma Key
  • Watermark
  • Add Noise
  • Pixelate
  • Texture Tile
  • Posterize
  • Diffuse
  • Twist
  • Motion

See Also:

Special Effects

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


Pixel Access

ImageGear is equipped with several functions that will allow you to get and set the values of individual pixels, rows or columns of pixels, and rectangular groups of pixels. This family of functions is referred to as the "pixel access" functions. For each kind of pixel access, you can obtain the value(s) of a pixel or group of pixels, or set the value(s) of a pixel or group of pixels.

See Also:

Pixel Access Operations


ROI Processing

  • Specify rectangular ROI for nearly all image processing functions.
  • Specify arbitrary ROI for most image processing functions. Functions included to create certain shape types such as ellipse, polygon, and freehand.
  • Create 1 bit mask image for identifying which pixels to include/disclude from image processing algorithms.
See Also:

Image Processing

Core Component API Function Reference


Graphical User Interface (GUI)

Though the entire ImageGear toolkit is geared toward providing a graphical interface as well as image handling and image processing support, the set of GUI functions included in ImageGear goes a step further in the areas of GUI pan, magnify, thumbnail, and GUI palette editing. Although the functions provided do much of the work for you, you are still in control when you need to be, due to the flexible argument lists and the availability of callback functions, which you write to control. For example, you have control when a palette might actually be changed, or when a directory search filter is to be provided. In addition, you can control the GUI window dimensions and positions.

See Also:

GUI Component API Function Reference

Working with ImageGear GUI Functions

Working with ImageGear GUI Dialogs


Format Conversion

ImageGear now supports over 200 raster file formats, by far exceeding all other image toolkit vendors.

You may want to convert a file from one format to another. You can do this by saving the original file to its desired format by setting the nFormatType parameter to the appropriate value in the saving function. For more information on converting issues, see the section Saving Images.

AccuSoft is also the only company willing to guarantee that all images in the listed formats will be displayed correctly.

See Also:

File Format Reference

ImageGear Supported File Formats Reference

ImageGear Supported Bit Depths


Compression

ImageGear supports most of the industry-standard compression algorithms.

See Also:

ImageGear Supported Compressions Reference

ImageGear Supported File Formats Reference


Animation

ImageGear includes the most complete GIF format support available, providing total programmer control of all aspects of reading and writing GIF images. With ImageGear you can:

  • Read still and animated GIFs with a single function call.
  • Access all data contained within a GIF, including comments, local palettes and animation sequencing information.
  • Read ALL types of GIFs.
  • Create any type of GIF, including non-interlaced, interlaced, single image, multi image, animated, etc.
  • Write fully customized GIFs with comments, animation sequencing, custom palettes and more.
See Also:

ImageGear Multimedia Component

ImageGear QuickTime Component


Transitions

ImageGear has the most advanced and flexible image-display technology available. It is also the fastest, with much of the functionality coded in assembler for optimal speed. One component of this is the ability to transition from one image to another in a more interesting fashion than simple replacement. Sometimes referred to as "transitions" or "wipes", these features are useful for slide shows, or any type of product where the image itself is the focus. For this type of product, ImageGear provides a set of functions for migrating from one image to another in an interesting way.

The transition support in ImageGear includes 29 types of transitions with control over the "granularity" and speed. Granularity refers to the size of the object used or the smoothness of the transition. The speed is the total time used to make the transition from one image to another. Of course, all other display parameters are also available for controlling the transitions.

See Also:

Image Transformation

Image Analysis

Special Effects

Blending and Combining Images

Image Correction

Image Maintenance


Native CMYK Support

  • Images stored in CMYK format can be loaded into ImageGear without being converted to RGB. This ensures the original color information is maintained with perfect fidelity.
  • Images can be saved to formats that support CMYK color space.
  • Images stored in CMYK can be optionally converted to RGB when loaded (default for STD), or converted to RGB at any time after loading.
  • Basic image processing, image access, display, and other functions work with native CMYK image data.
  • CMYK images can be color separated or converted to several other color spaces.
See Also:

Working with Color Space Conversion Engine


ImageClean™ Auto-Image Correction

  • Automatic detection and correction of white text blocks
  • Automatic detection and removal of unnecessary borders
  • Automatic detection and correction of inverted image
  • Automatic detection and correction of rotated image
See Also:

ImageGear ImageClean Component

ImageClean Component API Function Reference


Database

  • Load images from memory in 200 plus formats.
  • Load images from file with any offset for images embedded in a database.
  • Decode images using various compression algorithms without specific format headers.
  • Import/export images from/to various types of memory formats.
  • Save images to files at specified offsets.


Annotations

The ImageGear ART component integrates with ImageGear and supports the Wang annotation specification for storing annotations in TIFF. However, this is not a requirement; annotation data may be stored anywhere. The simple API makes adding and managing annotations easier than ever. ART works as an overlay to loaded images. ART annotation marks can include vector graphics, text, bitmaps, user-defined marks and others. There are many built-in features such as automatic handling of object creation, a toolbar that you can customize, attribute dialog boxes for each type of mark, built-in internationalization and more. To use ImageGear ART functionality you should attach ImageGear ART component. Please see ImageGear ARTX Component.


Built-in Internet Support (URL, FTP, Gopher)

AccuSoft's ImageGear product has Internet Support for Web pages. You can take advantage of AccuSoft's new Internet support to enable your product on the Web.


ImageGear Supported File Formats

ImageGear supports a great number of the most popular graphics file formats with different compressions, preventing compatibility problems before they arise. These ImageGear-supported file formats are described in detail in the File Format Reference Chapter. See also the section ImageGear Supported File Formats Reference.

The complete list of supported formats (as of this writing) is below:

Format
Read/write?
Description
Adobe DNG
Read
Adobe Digital Negative format
Adobe PDF
Read-write
Adobe Portable Document Format, with ImageGear PDF Component only.
Adobe PS
Read-write
Adobe PostScript language files level III. Requires ImageGear PDF Component.
Adobe PSB
Read-write
Adobe Photoshop Big
Adobe PSD
Read-write
Adobe Photoshop
AFX
Read
AutoFX format
AVI
Read
Audio/Visual Interleaved data (animation), requires multi-media component
BMP
Read-write
Standard Windows format including OS/2 bitmap format.
BTR
Read-write
Brooktrout FAX format, Group III or Group III 2D or 301
CAL
Read-write
CALS raster, Type I
CGM
Read-write
The Computer Graphics Metafile (CGM) file format for capturing and retrieving two-dimensional pictures. Requires ImageGear CAD/Vector CGM Component.
CLP
Read-write
Windows Clipboard format for raster images
CUR
Read
For reading Windows 3.x and Windows95 mouse cursor display.
CUT
Read
Dr. Halo CUT format
DCRAW
Read
Raw images created by many digital cameras. See the sections Working with ImageGear Digital Camera RAW Filter and ImageGear Supported Digital Camera RAW Formats.
DCX
Read-write
Intel multi-page FAX format
DGN
Read-write
DGN is a file format that is used by Intergraph MicroStation and Interactive Graphics System CAD applications. Requires ImageGear CAD/Vector DGN Component .
DIB
Read-write
DIB is a synonym for the BMP format.
DICOM
Read-write
DICOM is a public standard created to provide a flexible and expandable means for storing, sharing, and transporting digital medical images.(Supported with ImageGear Medical Component attached only)
DWF
Read-write
A file format designed by AutoDesk for storing DWG files on the Internet. DWF is a 2D or 3D vector based description of drawings and illustrations. Requires ImageGear CAD/Vector DWF Component.
DWG
Read-write
An AutoCAD, AutoCAD2004, and AutoDesk graphics format (DraWinG). Requires ImageGear CAD/Vector DWG, DXF Component.
DXF
Read-write
An AudoDesk graphics format (Drawing eXchange Format). Most CAD programs (PC-based) support this format. Requires ImageGear CAD/Vector DWG, DXF Component.
EPS
Read-write
IG without a PDF component allows for the reading of the preview portion of EPS files and writes EPS files. ImageGear PDF component allows for the reading of any EPS files.
EXIF-JPEG
Read-write
Exchangeable image file format for Digital Still cameras. ImageGear also allows you to process non-image data that is usually encoded in this file format. See the section Non-Image Data Processing.
EXIF-TIFF
Read-write
Uncompressed EXIF is recorded in TIFF Rev. 6.0 formats with two pages - the first is the main image, the second is a thumbnail (if it present).
FlashPix
Read-write
FlashPix (requires ImageGear FlashPix Component)
GEM
Read
GEM Paint Raster format
GIF
Read-write
ImageGear supports every aspect of GIF including animated and transparent. Requires ImageGear GIF/TIFF-LZW Component.
Group 3
Read-write
Proprietary formats with custom headers followed by Group III data.
Group 3 2D
Read-write
Proprietary formats with custom headers followed by Group III 2D data.
Group 4
Read-write
Proprietary formats with custom headers followed by Group IV data.
HPGL
Read-write
The HPGL and HPGL2 file formats are vector format developed by Hewlett Packard for driving plotters. The file extensions used include .plt, .hpg, .hp2, .pl2. Requires ImageGear CAD/Vector HPGL, HPGL/2 Component .
IBM AFP
read
Meta file format that may include raster and/or text data. This type format belongs to IBM's format family, which also includes IBM IOCA, IBM MO:DCA, PTOCA and IBM MMR compression.
IBM IOCA
Read-write
Image Object Content Architecture, CCITT Group 3, CCITT Group 3 2D, CCITT Group 4, IBM MMR, uncompressed, ABIC (with ImageGear ABIC Component only).
IBM MO:DCA
Read-write
Mixed Object Document Content Architecture format, CCITT Group 3, CCITT Group 3 2D, CCITT Group 4, IBM MMR, uncompressed, ABIC (with ImageGear ABIC Component only).
ICO
Read-write
Windows ICON format
IFF
Read-write
Electronic Arts format
IMG
Read
Xerox raster format, Group IV
IMR
Read
IMRS-Raster image
IMT
Read-write
IMNET format, Groups III and IV.
JBIG2
Read/Write
Multipage bitonal images. With ImageGear JBIG2 Component only.
JPEG
Read-write
ANSI-standard, full-color image format. IG supports all aspects of this format including lossless and progressive. JFIF - industry standard header for JPEG compressed images.
JPEG2000
Read-write
New JPEG2000 standard, based on the EBCOT (Embedded Block Coding with Optimized Truncation of the embedded bitstreams) algorithm. With ImageGear JPEG2000 Component only.
JPX
Read-write
JPX file format is an extension to JPEG 2000 file format. It normally uses JPEG 2000 compression, but allows other compressions as well, such as JBIG, CCITT Group3, CCITT Group4, etc.
KFX
Read
Kofax format, Group IV
LV
Read
LaserView, LaserData, Group IV
MAC
Read
Macintosh Paint format.
MAC PICT
Read-write
Macintosh metafile format. IG supports raster data only.
Motion JPEG2000
Read
Motion JPEG2000 file format is designed to contain one or more motion sequences of JPEG2000 images, with their timing, and also optional audio annotations, all composed into an overall presentation.
MSP
Read
Microsoft Paint format
MULTIMEDIA
Read
Motion Pictures Experts Group, an ISO specification for the compression of (digital) broadcast quality full-motion video and sound, requires ImageGear Multimedia Component.
NCR
Read-write
NCR Format
PBM
Read-write
Portable BitMap (Unix graphic file format)
PCD
Read-write
Kodak format for high resolution photographs
PCX
Read-write
PC Paintbrush format
PGM
Read-write
Portable BitMap (Unix graphic file format)
PNG
Read-write
Portable Network Graphics, intended as successor to GIF
PNM
Read-write
Portable BitMap (Unix graphic file format)
PPM
Read-write
Portable BitMap (Unix graphic file format)
PTOCA
Read
Presentation Text Object Content Architecture support for IBM's AFP printer architecture.
QuickTime
Read
Apple's multimedia development, storage, and playback technology. QuickTime files combine sound, text, animation, and video in a single file, requires ImageGear Multimedia Component. and ImageGear QuickTime Component
RAS
Read-write
SUN raster format
RAW
Read
Raw pixel data storage image formats, proprietary image formats
Scitex CT
Read-write
For electronic pre-press and visual communications systems, part of the HandShake Foreign File Transfer Protocol, a standard for defining storage formats and data interchange protocols.
SGI
Read-write
Silicon Graphics raster format
SVG
Read-write
Scalable Vector Graphics format. This is a modularized language for describing two-dimensional vector and mixed vector/raster graphics in XML. Requires ImageGear CAD/Vector SVG Component.
TGA
Read-write
Targa file format. ImageGear supports many aspects of this format including alpha channel.
TIFF
Read-write
Tagged Image File Format. IG supports every aspect of this format.
TXT (ASCII Text)
Read
Converted to raster image. Control font, point size, page break, margins, attributes etc.
U3D
Read-write
Universal 3D format. Requires ImageGear U3D Vector Component.
WBMP
Read-write
Optimized to support mobile computing devices that use the Wireless Application Protocol (WAP).
WMF
Read-write
Windows standard metafile format. IG converts non-raster data to raster during load.
WPG
Read
Wordperfect Graphic Format. IG reads bitmaps stored in this format
XBM
Read-write
X Windows Bitmap format
XPM
Read-write
X Windows Pixmap format
XPS
Read-write
XPS (XML Paper Specification)
XWD
Read-write
X Windows Dump format

NOTE: AccuSoft is always willing to consider supporting a new format. If you are interested in discussing support for your own format, please call the AccuSoft Sales Department at (508) 351-9092.


ImageGear Support for DCRAW Formats

ImageGear supports 100+ Digital Camera RAW formats.

ImageGear supports reading raw images created by many digital cameras. Support for raw images includes reading of image pixel data, color reconstruction of raw images, and reading of metadata stored with the images.

Since there are many flavors of raw formats, the list is continuously growing as new vendors/models enter the market, and the formats share many similarities, ImageGear treats all DCRAW formats as one format: IG_FORMAT_DCRAW. Details regarding manufacturer, model, etc, are available as metadata.

Please see the section Working with ImageGear Digital Camera RAW Filter to know how to work with DCRAW formats using ImageGear functionality.

For the list of supported DCRAW formats and the level of support please see the section ImageGear Supported Digital Camera RAW Formats.


ImageGear Components

ImageGear functionality is broken into components. This provides extra flexibility in packaging and licensing ImageGear technology. Each component encapsulates particular functionality of the product. All components are enabled when you evaluate or purchase the product (there is an expiration date for evaluation version), but different licensing fees may be associated with different components for deployment of your application. Please contact AccuSoft's Sales for more information about deployment licensing fees.

You need to attach a component (other than the core component) before using it. See the Samples for a demonstration of attaching the components. The sample code has been provided so that you may simply cut and paste the attaching component code into your own application.

Please, see ImageGear Licensing for full information about ImageGear and its component licensing process. See also the SOFTWARE LICENSE AGREEMENT.

The API used to attach components, IG_comm_comp_attach () and IG_comm_comp_check (), are described in Core Component API Function Reference and in the section Using ImageGear Component Manager.

NOTE: In your ImageGear application code, you will need to use the short component names. Please see the section ImageGear Component Names for the full list.


ImageGear Component Descriptions

The following sections summarize the ImageGear components that are currently available. For more information on these components, see the documentation provided with each one.

The following ImageGear components are currently available:

  • ImageGear ABIC Component
  • ImageGear ARTX Component
  • ImageGear ART Component
  • ImageGear CAD/Vector CGM Component
  • ImageGear CAD/Vector DGN Component
  • ImageGear CAD/Vector DWF Component
  • ImageGear CAD/Vector DWG, DXF Component
  • ImageGear CAD/Vector HPGL, HPGL/2 Component
  • ImageGear CAD/Vector SVG Component
  • ImageGear FlashPix Component
  • ImageGear FreqIP Component
  • ImageGear GIF/TIFF-LZW Component
  • ImageGear HD Photo Component
  • ImageGear ImageClean Component
  • ImageGear ISIS Component
  • ImageGear JBIG2 Component
  • ImageGear JPEG2000 Component
  • ImageGear Medical Component
  • ImageGear Multimedia Component
  • ImageGear QuickTime Component
  • ImageGear PDF Component
  • ImageGear Recognition Component
  • ImageGear TWAIN Component
  • ImageGear U3D Vector Component
  • ImageGear Vector Component
  • ImageGear XPS Component

ImageGear ABIC Component

ImageGear offers the ABIC Component to support bank check imaging with the proprietary ABIC compression owned by IBM.

See Also:

ABIC , ABIC_BW , ABIC_Gray

ImageGear ARTX Component

The ImageGear ARTX component provides access to the new ImageGear ARTX API that contains objects used for creating, loading, saving and processing ART annotations and their groups. Using this component, you can annotate any image that your application loads into ImageGear. Marks objects are created by using their objects. The ImageGear ARTX component allows you to work with 2 types of ART marks:

  • ART 3.0 Marks
  • ART 2.0 (Legacy) Marks

The ART 3.0 set consists of the enhanced list of more flexible marks. These marks are recommended for new applications. The ART 2.0 (Legacy) set consists of the marks that are backward compatible with previous ART versions. Only ART 2.0 marks can be loaded from the .ART files created with previous ART versions, and only ART 2.0 marks can be saved into the legacy ART storage format.

The ImageGear ARTX API allows you to create, load, edit and save an image with the marks into a separate file in legacy .ART file format or .XML file format.

NOTE: You can only attach one ART component. ARTX cannot be attached when ART is already attached.

For detailed information about attaching and using the ARTX Component, see the section entitled Using ImageGear ARTX Component. For detailed information about the ARTX DLL functions, see the ARTX Component API Function Reference.

ImageGear ART Component

The ImageGear ART component includes low-level functions for the fine-tune image annotating and high-level functions for the most typical operations. ART creates annotations on a "layer" that sits "above" the image or document that is to be annotated. The original image and the annotations can be stored separately or merged together permanently.

NOTE: You can only attach one ART component. ART cannot be attached when ARTX is already attached.

For detailed information about using the ART component, see the section Using ImageGear ART Component and the chapter entitled ART Component API Function Reference.

NOTE: ImageGear ART Component is provided in ImageGear v15 for backward compatibility with previous vesrsions of ImageGear. We recommend that you use the new ImageGear ARTX Component API for new development.

ImageGear CAD/Vector CGM Component

The ImageGear CGM Component supports the rasterization of CGM vector file format.

For detailed information about using the CAD/Vector components, see the section entitled Using ImageGear CAD/Vector Components .

ImageGear CAD/Vector DGN Component

The ImageGear DGN Component provides read-only support for the DGN vector file format.

For detailed information about using the CAD/Vector components, see the section entitled Using ImageGear CAD/Vector Components

ImageGear CAD/Vector DWF Component

The ImageGear CAD/VectorView component supports the rasterization of the DWF vector format.

For detailed information about using the CAD/Vector components, see the section entitled Using ImageGear CAD/Vector Components

ImageGear CAD/Vector DWG, DXF Component

The ImageGear CAD/VectorView component supports the rasterization of the DWG and DXF vector formats.

For detailed information about using the CAD/Vector components, see the section entitled Using ImageGear CAD/Vector Components

ImageGear CAD/Vector HPGL, HPGL/2 Component

The ImageGear HPGL Component supports the rasterization of HPGL and HPGL/2 vector file formats. It also allows you to work with PCL files containing HPGL/2 instructions.

For detailed information about using the CAD/Vector components, see the section entitled Using ImageGear CAD/Vector Components .

ImageGear CAD/Vector SVG Component

The ImageGear SVG Component supports the rasterization of SVG vector file format.

For detailed information about using the CAD/Vector components, see the chapter entitled Using ImageGear CAD/Vector Components .

ImageGear FlashPix Component

The FlashPix File Format provides easy desktop handling of digital color photographic images. It was developed and published by Eastman Kodak Company in collaboration with Hewlett-Packard, Live Picture, Inc. and Microsoft.

The FlashPix component provides the following features:

  • A full hierarchy of resolutions for each image
  • A "Source Plus Transform" storage scheme for easy "undos" and no loss of image quality, no matter how many transformations are applied
  • A choice of JPEG or Single Color compression
  • A detail-oriented stash of non-image data (title, subject, people in the picture, creation date, etc.)
  • Thumbnail support
  • Tiled storage
  • The use of all ImageGear functions to load, save, and transform FlashPix images
  • A special FlashPix-specific API, including functions that make reading and writing of non-image information easy
  • The ability to perform all FlashPix transformations on any ImageGear image
  • The ability to perform ImageGear transformations without losing FlashPix transformations

ImageGear FreqIP Component

FreqIP (Frequency Domain Image Processing) component is responsible for image processing functionalities in frequency domain.

See Also:

FreqIP Component API Function Reference

ImageGear GIF/TIFF-LZW Component

This component allows you to work with GIF/TIFF-LZW compression images.

See Also:

GIF Non-image Data Structure

ImageGear HD Photo Component

This component allows you to load and save HD Photo images.

See Also:

HD Photo

ImageGear ImageClean Component

The ImageGear ImageClean component provides several API functions that allow you to enhance bi-level image support. It includes the ability to clean borders, invert white text, auto-orient image, auto invert black text on the white background, and auto-crop.

See Also:

ImageClean Component API Function Reference

ImageGear ISIS Component

The ImageGear ISIS component is a high-speed scanning module based on the AIIM MS61 standard with a complete API that provides full control of the scanning process.

See Also:

Using ImageGear ISIS Component

ISIS Component API Function Reference

NOTE: The name of the ISIS standard is ANSI/AIIM MS61-1996. ISIS is a trademark of Pixel Translations.

ImageGear JBIG2 Component

The ImageGear JBIG2 component enables you to load and save bi-tonal images using a new method based on the JBIG2 compression algorithm. The JBIG2 format supports multipage images and is the most effective compression method for b/w images to date.

See Also:

Using ImageGear JBIG2 Component

ImageGear JPEG2000 Component

The JPEG2000 standard provides a set of features that take advantage of new technologies, making them important to many high-end and emerging applications. It addresses areas where current standards fail to produce the best quality or performance and provides capabilities to markets that currently do not use compression. The markets and applications better served by the JPEG2000 standard are Internet, color facsimile, printing, scanning (consumer and pre-press), digital photography, remote sensing, mobile, medical imaging, digital libraries / archives and E-commerce. Each application area imposes some requirements that the standard should fulfill.

The ImageGear JPEG2000 component is based on the Kakadu SDK, which allows you to use the diverse functionality of the JPEG2000 wavelet-based compression technique. It provides such advantages:

  • Excellent image quality at high compression ratios
  • Fast compression and decompression
  • Both lossless (guaranteed pixel identity) and lossy image compression options
  • User-controlled compression ratio
  • Quicklook generation and scaled image reconstruction based on embedded coding techniques
  • Elimination of JPEG-like blocking artifacts

All these features outperform all other image compression techniques. JPEG2000 image compression is best suited for compression either of sensitive images because of the lossless feature, or for its excellent image quality at high compression ratios for uses such as transmission in low bandwidth applications.

The ImageGear JPEG2000 component also provides partial support for JPEG2000 Part II (JPX) and Motion JPEG2000 file format (MJ2).ImageGear JPIP client API and ImageGear JPIP server API can be used to implement a JPIP server capable of efficiently and dynamically streaming portions of a JPEG2000-compressed image over a network. A JPIP client can establish a session over which multiple regions of interest within an image may be streamed from the JPIP server.

See Also:

Using ImageGear JPEG2000 Component

JPEG2000 Component API Function Reference

ImageGear Medical Component

The ImageGear Medical (MD) component is a full-featured ImageGear component. It supports the DICOM format, contains a custom API, and includes expanded image processing capabilities beyond those of the baseline ImageGear library.

The format support of the MD component includes loading and saving monochrome, palletized, and true color medical images using the following file formats:

  • DICOM 3.0 Part 10-compliant images
  • DICOM 3.0 Raw Format (non-Part 10-compliant)

In addition, your application will continue to support all ImageGear-supported file formats, allowingt you to convert an image of a different format to a medical image format, and vice- versa.

The ImageGear MD component is backed by the AccuSoft Image Guarantee. The component is guaranteed to read all valid raster images in the supported formats.

See Also:

Using ImageGear MD Component

MD Component API Function Reference

ImageGear Multimedia Component

The ImageGear Multimedia component supports more multimedia formats and compressions than ever before because it's based on the DirectX Media SDK. Any format your Windows Media Player will read (like AVI, MPEG, and QuickTime) can now be read by the ImageGear Multimedia component. For detailed information about using the Multimedia component, see the section entitled Using ImageGear Multimedia Component.

ImageGear QuickTime Component

The ImageGear QuickTime component provides streaming access to video and audio data in QuickTime movie files through the multimedia API in ImageGear.

For detailed information about using the multimedia API, see the IG_mult_...() functions reference in the Core Component API Function Reference Chapter. For detailed information about using the QuickTime component, see the section entitled Using ImageGear Multimedia Component.

ImageGear PDF Component

The ImageGear PDF Component allows you to load, save and process PDF (Portable Document Format) file format images using core ImageGear and other IG Components functionality.

This Component also allows you to read vector data from PS (PostScript) and EPS (Encapsulated PostScript) file formats (core ImageGear Component allows you to read only raster data from these two formats).

In addition, this PDF Component provides the ability to extract text from loaded PDF and PS image files.

See Also:

Using ImageGear PDF Component

PDF Component API Function Reference

ImageGear Recognition Component

The ImageGear Recognition component is a set of functions that provide access to ScanSoft's document recognition technology.

This core software module provides unsurpassed recognition accuracy for almost any document, including those produced on typewriters, dot-matrix printers, ink-jet printers, laser printers, and phototypesetters, as well as photocopied and faxed versions of any documents. It also allows for recognition of handwritten text, check marks and a veriety of bar codes.

Using the ImageGear Recognition component, you can recognize a document image and export text in any format defined by the ScanSoft SDK. These formats include 8-bit text, HTML, XML and Word processor formats such as MS Word or WordPerfect. You also can learn, save, and (later) load character recognition data for similar documents. The software learns as a result of normal recognition, and acquires additional information by using the API's text verification system.

The ImageGear recognition component also allow the user to:

  • Manage delineated zones of a document page and then specify treatment for those zones. This includes the ability to correct the OCR engine's automatic segmentation between the segmentation phase and the recognition phase.
  • Process both text and graphics. The recognition software's ability to distinguish graphics from text can provide the basis of a compound document processing system.
  • Automatically detect fax, dot matrix, and other degraded documents and compensate accordingly.
  • Recognize handwritten text using a numbers only module or alphanumeric module.
  • Process questionnaries, educational tests and other form-like documents using the Optical Mark Recognition feature.
  • Recognize both 1D and 2D bar codes (provided that both BAR and BAR2D modules are licensed).

For detailed information about using the Recognition component, see the section entitled Recognition Component API Function Reference. See also Using ImageGear Recognition Component section.

ImageGear TWAIN Component

The TWAIN standard is widely supported by scanner manufacturers, with most users of TWAIN version 1.9. The ImageGear TWAIN component allows you to support all three TWAIN Transfer Modes: Native Data Transfer Mode (which is the TWAIN default), Disk File Transfer, and Buffered Memory.

For detailed information about using the TWAIN component, see the section entitled TWAIN Component API Function Reference. See also Using ImageGear Twain Component section.

ImageGear U3D Vector Component

The ImageGear U3D Vector component supports reading, writing and rasterizing the U3D vector files. It provides read and write support for the following features of the Universal 3D format: CLOD Progressive Mesh, Normals, Colors (diffuse and specular), Views, Lights, Textures, Transparency, Linesets and Pointsets.

For detailed information about using the CAD/Vector components, see the section entitled Using ImageGear CAD/Vector Components. Also see U3D.

ImageGear Vector Component

The ImageGear Vector component provides base operations for reading such vector formats as CAD (DXF/DWG), DWF, DGN, CGM and HPGL and drawing vector data during display operations.

This component allows you to switch between OpenGL and WinAPI rendering engines dynamically. OpenGL is an advanced rendering engine that provides faster execution speed via hardware acceleration and offers higher level graphics commands. Since not all hardware supports the OpenGL interface, the Windows API engine can be used as an alternative. ImageGear provides 3 rendering modes: OpenGL, Windows API, and Automatic (the default), which means that ImageGear tries to use OpenGL, and falls back to Windows API if OpenGL is not available. This provides for an universal automated solution across different hardware and software configurations.

For detailed information about using the Vector component, see the section entitled Vector Component API Function Reference.

ImageGear XPS Component

This component allows you to load and save XML Paper Specification (XPS) documents. For information about using XML Paper Specification (XPS), see XPS.

The ImageGear XPS component requires the Microsoft XPS Essentials Pack and available for Windows Vista, Windows XP, and Windows Server 2003. This is also available in both 32-bit and 64-bit versions.


ImageGear Samples

Your ImageGear toolkit also contains a directory with sample imaging application programs and images. You may copy and modify them as you wish. You can also use them as templates for developing your own applications. The sample images may also be used for any purpose, such as testing your applications as you develop them.


Answering Your ImageGear Questions

After reading the manual, one of the best ways to begin to answer your questions is by reading the release notes, which can be accessed through the ImageGear application menu.

See Also:

AccuSoft Customer Support

Before Contacting Customer Support


AccuSoft Customer Support

AccuSoft includes one year of the support and subscription program with the ImageGear product at no additional cost. If you desire a higher level of support, we offer additional Support programs designed to meet the diverse requirements of AccuSoft customers. Please visit AccuSoft's Web site at

http://www.accusoft.com/support/s_about.asp

or call our Sales Department at (508) 351-9092.

You can also e-mail questions to sales@accusoft.com .

See also the section Software Support and Maintenance Policy in SOFTWARE LICENSE AGREEMENT to get information about AccuSoft's customer support policy.


Before Contacting Customer Support

  • Double check the Manuals provided with this product or check the on-line documentation.
  • Read the release notes, which can be accessed through the ImageGear application menu.
  • Refer to the following chapters: Chapter 3Getting Started, Chapter 5 Using ImageGear, and Chapter AccuSoft Image Guarantee. These chapters contain a great deal of information on both programming your application and identifying image problems.
  • Take a look at the sample programs included with your product.
  • If you still need technical support assistance, please follow the instructions provided in the AccuSoft Customer Support section.


Internet Services

Visit the AccuSoft website ( www.accusoft.com) for useful information, including the following areas:

  • Product Information
  • Product Downloads
  • Customer Support
  • Demos and Evals
  • On-line Documentation


Installation

This Chapter provides information about how to install/uninstall ImageGear in the following sections:

  • Minimum Requirements
  • Installing ImageGear from CD
  • Installing ImageGear from the Web Site
  • Directory Structure
  • Description of Installed Files
  • Uninstalling ImageGear
  • ImageGear Licensing


Minimum Requirements

In order to install and use ImageGear for Windows , you must ensure that your computer system meets the following minimum requirements.

  • Processor:
    • For Windows 32-bit Operating System - Pentium
  • 64 MB RAM
Operating System:
    • Windows for 32-bit Operating System - Windows 2000, Windows XP, Windows 2003, Windows Vista, and Windows 2008 Server
NOTE: The Installation program will tell you how much disk space you need in order to load ImageGear. The disk space used will vary, depending upon the options you select during installation.


Vista and Visual Studio 2005/2008

Microsoft recommends running Visual Studio 2005/2008 with administrator privileges under Vista. To properly use the ImageGear Samples please run Visual Studio 2005/2008 with elevated permissions.

To run Visual Studio 2005/2008 with elevated administrator permissions first confirm you are a member of the "Administrators" group on the local machine.

Then right-click the Visual Studio 2005/2008 shortcut and select the "Run as administrator" option from the context menu. Click `Continue' to the UAC prompt.

To ensure you have the latest updates, after running Visual Studio 2005/2008 choose `Check for Updates' from the Help Menu.


Installing ImageGear from CD

To install the ImageGear library from CD:

  1. Insert the ImageGear CD into the CD-ROM drive.
    1. CD should auto-start installation process. Follow on-screen prompts.
    2. If installation does not "autostart", double-click igsetup.exe in CD root directory.
  2. Choose the product to install, either "Professional", "Enterprise" or "MD" and click the "Next" button to continue or "Cancel" to terminate the installation. If you click "Next", the installation will bring up the "License Agreement" form.
  3. Carefully read the information contained in the "License Agreement" form before making a decision to accept the terms of the agreement. Choose "I accept the license agreement" to accept the conditions outlined in the License Agreement and then click the "Next" button to continue the installation, or click "Cancel" to exit the installation process.
  4. If you accepted the License Agreement and continued the installation process, the "User Information" form appears next. Enter your name and the name of your company in the "Full Name" and "Organization" text boxes, respectively. Then click "Next".
  5. Choose the destination directory where the ImageGear product should be installed with the browse button, or leave the default installation destination directory. Then click "Next".
  6. Once you click the "Next" button, the product "Select Features" form is displayed. In this form you can:
    1. Choose the features and components of the selected product to install on your PC.
    2. Get information about how much of your hard disk memory is required to install the product features that you have chosen in 6a.

When all these options are chosen, click the "Next" button to continue the installation process and then click "Finish".

NOTE: During the ImageGear installation you need to obtain License Key using AccuSoft License Manager, which is run automatically at the end of the installation. Please see the section ImageGear Licensing for the information how to obtain ImageGear license.
NOTE: The ImageGear Medical component is not installed during the ImageGear Professional installation process. The Medical component is installed using the ImageGear MD. ImageGear MD will install both ImageGear Professional or Enterprise and the Medical components.


Installing ImageGear from the Web Site

Please visit our Web site, www.accusoft.com or call our Sales department for instructions at (508) 351-9092.

Here is an example Linux .bash_profile with all the necessary variables defined:

# User specific environment and startup programs
PATH=$PATH:$HOME/bin:.
BASH_ENV=$HOME/.bashrc
USERNAME=""
LD_LIBRARY_PATH=$HOME/AccuSoft/ImageGear16/Pro/Unix/Bin/
Linux
IMAGE_GEAR_LIBRARY_PATH=$HOME/AccuSoft/ImageGear16/Pro/Unix/
Bin/Linux
IMAGE_GEAR_LICENSE_DIR=$HOME/AccuSoft/ImageGear16/Pro/Unix
export USERNAME BASH_ENV PATH LD_LIBRARY_PATH
IMAGE_GEAR_LIBRARY_PATH
IMAGE_GEAR_LICENSE_DIR

Linux users must use the GNU zip version of zcat.


Directory Structure

If you accept the suggested default, the installation program creates the following directory structure:

NOTE: For 64-bit platforms, the directory stucture is
$HOME/AccuSoft/ImageGear16/Pro/Utils/lib/


Description of Installed Files

The following files are installed on your PC to the root of your installation directories:

  • ...Shared\BIN Folder:
    File Name
    Description
    /BIN/Resource/
    ImageGear PDF component resource files and fonts.
    /BIN/*.dll
    ImageGear DLL components.
    /BIN/*.exe
    ImageGear DLL Samples executables.
    Other ImageGear files...
  • ...\DOCUMENTATION Folder consists of HTMLHelp (*.chm files) documentation subfolder and Release Notes (*.html files) subfolder.
  • ...\DLL\INCLUDE Folder:
    File Name
    Description
    accucb.h
    C/C++ include file for ImageGear callback functions type
    accucnst.h
    C/C++ include file for ImageGear constants declarations
    accufunc.h
    C/C++ include file for ImageGear function prototypes
    accuimg.h
    C/C++ include file for ImageGear data types and macros
    accuold.h
    C/C++ include file for ImageGear backward compatibility declarations
    accuosd.h
    C/C++ include file for ImageGear operating system declarations
    accustd.h
    C/C++ include file for ImageGear data types and pointers
    accuvers.h
    C/C++ include file for ImageGear version declaration
    artgui.h
    C/C++ include file for the ImageGear ART component (ART GUI API)
    datadict.h
    C/C++ include file for ImageGear ImageGear Medical Component
    dcm.h
    C/C++ include file for ImageGear Medical Component
    gear.h
    C/C++ include file for ImageGear core component
    gearerrs.h
    C/C++ include file for ImageGear error codes
    gearestr.h
    C/C++ include file for ImageGear error strings
    geartags.h
    C/C++ include file for ImageGear field tags used with tag callbacks
    gif.h
    C/C++ include file for ImageGear LZW component
    i_ART.h
    Public header file for the ImageGear ART Component
    i_ARTX.h
    Public header file for the ImageGear ARTX Component
    i_ARTXGUI.h
    Public header file for the ARTX GUI DLL
    i_ARTXtp.h
    C/C++ include file for ImageGear ARTX Component
    i_CGM.h
    Public header file for the ImageGear CAD/Vector CGM Component
    i_CLN.h
    Public header file for the ImageGear ImageClean Component
    i_CLNtp.h
    Public header file for ImageGear ImageClean Component
    i_FPX.h
    Public header file for the ImageGear FlashPix Component
    i_FreqIP
    Public header file for Frequency Domain\Image Processing
    i_FreqIPtp
    Public header file for Frequency Domain\Image Processing related constants
    i_ISIS.h
    Public header file for the ImageGear ISIS Component
    i_JPEG2K
    Public header file for the ImageGear JPEG2000 Component
    i_MED.h
    Public header file for the ImageGear Medical Component
    i_PDF.h
    Public header file for the ImageGear PDF Component
    i_PDFtp.h
    C/C++ include file for ImageGear PDF Component
    i_REC.h
    Public header file for the ImageGear Recognition Component
    i_TWAIN.h
    Public header file for the ImageGear TWAIN Component
    i_VECT.h
    Public header file for the ImageGear Vector Component
    metadata.h
    C/C++ include file for ImageGear metadata callback constants
    vectapi.h
    C/C++ include file for ImageGear Vector Component
    /Include/Scansoft/...
    C/C++ include files for the ImageGear Recognition Component
    /Include/Vector/...
    C/C++ include files for the ImageGear Vector Component
  • ...\DLL\LIB Folder:
    File Name
    Description
    igartgui16d.lib
    ART GUI Standard Library
    igArtX16d.lib
    ARTX Component Standard library
    igArtXGUI16d.lib
    ARTX Component GUI Standard Library
    igcore16d.lib
    ImageGear DLL Import Library
    iggui16d.lib
    ImageGear GUI Import Library


Sample Applications

In addition, a SAMPLES directory will be installed, if you have selected it during installation. Under this directory is a separate subdirectory for each sample. Each sample is a complete, executable mini application. In their totality, these applications offer you more breadth than most tutorials. See the section ImageGear DLL Samples in Getting Started chapter for more details about ImageGear's sample applications.


Uninstalling ImageGear

Run Add/Remove Programs from the Control Panel. Choose "AccuSoft ImageGear v16". Click "Change" button, select "Uninstall AccuSoft ImageGear v16 from this computer" and click Next.


ImageGear Licensing

During the ImageGear installation, you need to obtain a license key using the AccuSoft License Manager that is run automatically at the end of the installation. If you need to run it manually in the future you can do it using

Start Menu\Programs\AccuSoft\ImageGear\License Manager

shortcut.

If you are evaluating the product, please select the ImageGear evaluation license option from the initial screen of the License Manager utility. You will be prompted to login using the same e-mail and password you have registered with on AccuSoft Web site. After you supply login credentials your license key will be automatically obtained and stored on your computer. An Evaluation license enables you to use any features of the product on your machine for a limited period of time.

To extend the Evaluation license:

  1. Run the License Manager utility.
  2. Select ImageGear evaluation license and click Continue.
  3. Click the Submit extension request to request an extension of the ImageGear evaluation.

Your request will be considered, and you will receive e-mail notification when your license is extended. Then you need to run the License Manager utility again to generate a new license key.

If you bought the Development copy of ImageGear please select the ImageGear Development license option from the initial screen of the License Manager utility. You will be prompted to login using e-mail and password you have registered with on AccuSoft Web site. Upon login you will be presented with the combo-box containing different access keys for the AccuSoft products you have bought:

  1. Please select ImageGear [Edition] and click Get key.
  2. Your license key will be automatically obtained and stored on your computer.

In case if you had the Evaluation license previously, it will be overwritten with the new Development license. Development license enables you to use any of the ImageGear features on the limited number of computers. You need to run the License Manager utility for each machine where you need to use the product.

In case if hardware parameters of the machine changes, next time you're using ImageGear you will receive an error with the following text "The hardware ID of this machine doesn't match license information. Please run AccuSoft License Manager on this machine to add its hardware ID to your license." Please run the License Manager utility to associate the license with your new hardware ID.

NOTE: There is a limit on the maximum number of hardware IDs associated with the license. If you hit the limit then the License Manager utility will guide you though the process of removing unused hardware IDs from the license.

The License Manager utility stores license key in the registry and product samples are configured to read it from the registry. Please refer to the section ImageGear Licensing API for details on adding licensing calls to your application.

The License Manager utility requires an Internet connection in order to manage the license keys. If you don't have Internet connection, please call AccuSoft Customer Service at 1-508-351-9092.

NOTE: The Development license enables one developer to develop any applications but in order to deploy your ImageGear-based application you need to obtain the AccuSoft Licensing Deployment Kit (LDK). Please contact AccuSoft when you're ready to deploy your solution. See also the section ImageGear Licensing API.


Getting Started

This chapter helps you to get started with ImageGear. You can use:

  • MS Visual Studio .NET 2003 C++ Application - for step-by-step creating the simplest ImageGear application.
  • MS Visual Studio .NET 2003 C# Application - will help you to use ImageGear DLL in the MS VS .NET C# application.
  • ImageGear DLL Samples - for the programming code you can use to create your own ImageGear application.

Please see also Using ART Component (A Quick Start Tutorial) section, which shows how you can use the ImageGear ART Component functions and structures to greatly enhance your imaging application.


MS Visual Studio .NET 2003 C++ Application

In this section, you will create a Visual C++ application using the ImageGear DLL library. This tutorial assumes you are using Microsoft Visual Studio 2003 on Microsoft Windows 2000 or XP.

The application in this tutorial loads, displays, and zooms images. The instructions in this tutorial are specific to Visual Studio 2003 C++ Projects.


Creating the Project

To create the interface, start Visual Studio 2003. The Visual Studio 2003 environment will appear.

  1. Create a new MFC Application project. For this tutorial, the Project name will be called "IGSample". Click OK after entering this Project name.

  2. Next choose the Single document option to create a Single Document Interface (SDI) application. Click Finish to create the project.

  3. Once the project is created, you should set up the compiler to use ImageGear. To do this select Project, then IGSample Properties to display IGSample Property Pages dialog box. Once the dialog pops up, select the C/C++ option in the left panel, and choose General option in the dropdown list. In right panel choose the Additional Include Directories filed and add the path to where you installed ImageGear (C:\Program Files\AccuSoft\ImageGear v16\[IG version]\DLL\Include by default). For debug configuration select "Debug Info" other than "Program Database for Edit and Continue".

  4. Next select the Linker/General option in the left panel, and add a link to the ImageGear library folder (C:\Program Files\AccuSoft\ImageGear v16\[IG version]\DLL\Lib by default) in the Additional Library Directories field. For AMD 64: Add "/machine:AMD64" to the end of Project Options.

  5. Then select the Linker/Input option in the left panel, and add the name of ImageGear library file (igcore16d.lib) to the Additional Dependencies field in the right panel. Once you have done this, click OK.


Developing the Application

Before completing the steps in this section, complete the following setup:

  • Enter the project settings properties.
  • Select the "Debugging" option from the lefthand side.
  • Set the "Working Directory" property to "C:\Program Files\AccuSoft\ImageGear v16\<>\Shared\Bin"

1. First we need to add ImageGear license initialization code: CIGSample::InitInstance() in the IGSample application.

BOOL CIGSample::InitInstance()
{
AfxEnableControlContainer();
// Standard initialization
// If you are not using these features and wish to reduce the
size
// of your final executable, you should remove from the
following
// the specific initialization routines you do not need.
// If you are evaluating/developing ImageGear:
IG_lic_solution_name_set( "AccuSoft 1-100-16" );
. . .
}

2. We will now add "Zoom In" and "Zoom Out" options under the application's View menu. To do this, select the Resources Tab, then expand the Menu folder. Open IDR_MAINFRAME. Drop down the View option and add two items: Zoom In and Zoom Out. For this tutorial, the ID's of these two items are ID_ZIN and ID_ZOUT respectively. So right click each item, select Properties, then change their ID fields to ID_ZIN and ID_ZOUT respectively.

3. Next select the FileView tab, then expand the Header Files folder. Open the IGSampleDoc.h file, and add the following statement:

#include "gear.h"

This provides access to the ImageGear functions for use in our application.

4. Also in the IGSampleDoc.h file, add the following declaration to the public attributes section of the code:

HIGEAR hIGear;

This creates an ImageGear handle that will be used to hold the loaded image, which will be passed to the different ImageGear functions that are called.

5. Next we will add code to the IGSampleDoc.cpp constructor and destructor functions. Expand the Source Files and open the IGSampleDoc.cpp file. Add the following code to the IGSampleDoc::IGSampleDoc() function:

hIGear = (HIGEAR)NULL;

Then add the following code to the IGSampleDoc::~IGSampleDoc() function:

if( IG_image_is_valid( hIGear ) )
IG_image_delete( hIGear );

The code above utilizes:

IG_image_is_valid ()
This function is called to determine if the HIGEAR variable hIGear contains a handle of a valid ImageGear image.
IG_image_delete ()
This function removes the HIGEAR handle of hIGear, and frees the memory of the associated HIGEAR structure. This function also frees the memory associated with the image's DIB, if ImageGear allocated the DIB memory. If ImageGear did not allocate the DIB memory, the DIB continues to exist, and it is the responsibility of your application to free this memory when done with it.

6. Also in IGSampleDoc.cpp, we will use the Class View to add the virtual function OnOpenDocument. Right click the CIGSampleDoc item in the tree and choose Properties. In the Properties tab, select the button for overrides (second from the right). Scroll down and select OnOpenDocument. Click the town error for the combo box and choose '<Add> OnOpenDocument'. Add the following code into the function in place of the TODO comment:

if( IG_load_file( (char*)lpszPathName, &hIGear )==0 )
return TRUE;
else
{
//ErrorReport
return FALSE;
}

The code above utilizes:

IG_load_file ()
Loads the specified file into the HIGEAR.

7. Using the same Class View, right click CIGSampleDoc and choose Add->Add Function. In the Add Member Function Wizard, set the return type to AT_ERRCOUNT and function name to and add the following parameters:

Type
Name
CView *
v
AT_MODE
nZoomMode
DOUBLE
dHZoom
DOUBLE
dVZoom

The Function signature should now look like this:

AT_ERRCOUNT dsplZoomSet(CView * v, AT_MODE nZoomMode, double
dHZoom, double dVZoom)

Click Finish to add the function.

Next insert code under the member function in IGSampleDoc.cpp so that the final code looks like the following:

AT_ERRCOUNT CIGSampleDoc::dsplZoomSet(CView * v, AT_MODE
nZoomMode, double dHZoom, double dVZoom)
{
    DWORD dwGrpID=0;
    AT_ERRCOUNT nErrCount;
    nErrCount = IG_dspl_zoom_set( hIGear, dwGrpID, nZoomMode,
        dHZoom, dVZoom );
    if( nErrCount!=NULL )
    {
        //ErrorReport
    }
    return nErrCount;
}

8. Now add two other member functions (dsplZoomGet, DrawImage) using the same process as in the previous step and matching their function declarations:

AT_ERRCOUNT CIGSampleDoc::dsplZoomGet(CView *v, LPAT_MODE
lpnZoomMode, LPDOUBLE lpdHZoom, LPDOUBLE lpdVZoom)
{
DWORD dwGrpID=0;
AT_ERRCOUNT nErrCount;
nErrCount = IG_dspl_zoom_get( hIGear, dwGrpID, v-
>GetSafeHwnd(), lpnZoomMode, lpdHZoom, lpdVZoom );
if( nErrCount!=NULL )
{
//ErrorReport
}
return nErrCount;
}
void CIGSampleDoc::DrawImage( CView *v, CDC *dc, CPrintInfo
*pInfo )
{
if( IG_image_is_valid( hIGear ) )
{
DWORD dwGrpID=0;
POINT p;
SIZE s;
DWORD nMapMode;
AT_RECTANGLE Viewport;
AT_RECTANGLE Window;
/* get current mapping parameters */
nMapMode = ::GetMapMode( dc->m_hDC );
::GetViewportOrgEx( dc->m_hDC, &p );
Viewport.x = p.x;
Viewport.y = p.y;
::GetViewportExtEx( dc->m_hDC, &s );
Viewport.width = s.cx;
Viewport.height = s.cy;
::GetWindowOrgEx( dc->m_hDC, &p );
Window.x = p.x;
Window.y = p.y;
::GetWindowExtEx( dc->m_hDC, &s );
Window.width = s.cx;
Window.height = s.cy;
IG_dspl_mapmode_set( hIGear, dwGrpID, nMapMode, &Viewport,
&Window );
IG_dspl_image_draw( hIGear, dwGrpID, v->GetSafeHwnd(), dc-
>GetSafeHdc(), NULL );
}
}

The code for these member functions include:

IG_dspl_mapmode_set ()
Sets the current map mode and logical coordinate system.
IG_dspl_image_draw ()
This function draws an image onto a destination device context.
IG_dspl_zoom_set ()
Sets the zoom value.
IG_dspl_zoom_get ()
Gets the current zoom value.

9. Now we need to add code to IGSampleView.cpp for handling the menu events. Start off by finding the OnDraw functions. Remove the comments around pDC in the function declaration line so the function starts like this:

void CIGSampleView::OnDraw(CDC* pDC)

Then add the following code to the OnDraw function:

pDoc->DrawImage( this, pDC, NULL );

This calls the DrawImage function defined in IGSampleDoc.cpp and ensures that the image will be properly drawn when the window is redrawn.

10. Next we need to add handles for ID_ZIN and ID_ZOUT. Using the ClassView, select CIGSampleView class and bring up the properties for it. In the properties view select the lightning bolt icon for Events. Scroll down and expand both the ID_ZIN and ID_ZOUT events. Click the down arrow for the combo box of the COMMAND field for each and choose to "<Add> OnZin" and "<Add> OnZout". Then insert the following code into the OnZin() function:

DOUBLE dHZoom, dVZoom;
CIGSampleDoc* pDoc = GetDocument();
ASSERT_VALID(pDoc);
pDoc->dsplZoomGet( this, NULL, &dHZoom, &dVZoom );
dHZoom *= 1.25;
dVZoom *= 1.25;
pDoc->dsplZoomSet( this,
IG_DSPL_ZOOM_H_FIXED|IG_DSPL_ZOOM_V_FIXED, dHZoom, dVZoom );
InvalidateRect( NULL, FALSE ); //force redraw
UpdateWindow();

The above code zooms the image to 125 percent, or 5/4ths, of its size (zoom in by 25 percent).

Finally, insert the following code into the OnZout() function:

DOUBLE dHZoom, dVZoom;
CIGSampleDoc* pDoc = GetDocument();
ASSERT_VALID(pDoc);
pDoc->dsplZoomGet( this, NULL, &dHZoom, &dVZoom );
dHZoom /= 1.25;
dVZoom /= 1.25;
pDoc->dsplZoomSet( this,
IG_DSPL_ZOOM_H_FIXED|IG_DSPL_ZOOM_V_FIXED, dHZoom, dVZoom );
InvalidateRect( NULL, FALSE ); //force redraw
UpdateWindow();

The above code zooms "out", decreasing the image to 4/5ths of its size, thereby canceling the effect of the zoom in above.


Running the Application

That's it! Simply compile and run your project and you will now have an image viewer that supports 100 file formats. Add the components to enable support for 100+ image formats.

See Also:

MS Visual Studio .NET 2003 C# Application

ImageGear DLL Samples

Using ART Component (A Quick Start Tutorial)


MS Visual Studio .NET 2003 C# Application

MS Visual Studio .Net 2003 Platform allows you to use unmanaged DLL code through Platform invoke.

You need to create a managed declaration for ImageGear DLL functionality and structures:

  • Add using of System.Runtime.InteropServices to your code to get access to the interoperability services of Platform invoke.
  • Create a class and add a managed declaration for ImageGear functions importing igcore16d.dll.
  • Use the DllImportAttribute fields (EntryPoint, CharSet, etc.), if you wish to simplify ImageGear functions you are using.
  • Create formatted ImageGear types for use in managed code, preserving its original layout and alignment.

For example:

C#
using System.Runtime.InteropServices;
[StructLayout(LayoutKind.Sequential)]
public struct AT_DIB
{
public uint biSize;
public int biWidth;
public int biHeight;
public ushort biPlanes;
public ushort biBitCount;
public uint biCompression;
public uint biSizeImage;
public int biXPelsPerMeter;
public int biYPelsPerMeter;
public uint biClrUsed;
public uint biClrImportant;
};
public class ImageGearDecl
{
//...
[DllImport("igcore16d.dll")]
public static extern int IG_load_file( byte *pFileName, uint
*hIGear );
[DllImport("igcore16d.dll", EntryPoint="IG_dspl_image_draw")]
public static extern int IG_image_display( uint hIGear, uint
nGrpID,
IntPtr hWnd, IntPtr hDC, uint *pRect );
[DllImport(ImageGearLibName)]
public static extern int IG_image_DIB_pntr_get( uint hIGear, ref
AT_DIB lpDIB );
//...
}

Then you will be able to use the ImageGear functionality in managed code. For example:

C#
public int LoadFromFile( string sFileName )
{
uint phImage = 0;
ASCIIEncoding encoding = new ASCIIEncoding();
byte[] szFileName = new byte[256];
int nErrCount = 0;
szFileName = encoding.GetBytes(sFileName);
fixed (byte* pszFileName = szFileName)
{
nErrCount = IG_load_file( pszFileName, &phImage );
}
return nErrCount;
}


Using ImageGear callbacks

  1. Create a delegate object type for callback.
  2. Declare the callback-registering function.
  3. Create the managed callback function.
  4. Create a delegate object for callback and pass it as an argument to the callback-registering function.

For example:

C#
// Delegate type for callback
public delegate bool LPFNART_GUI_CALLBACKFUNC( void* lpPrivate,
uint dwButtonID,
uint nReason );
// Declare callback-registering function.
[DllImport("ARTGUI32.DLL")]
public static extern int ART_GUI_toolbar_CB_register(
IntPtr hwndToolBar,
uint nCallback,
LPFNART_GUI_CALLBACKFUNC lpfnCallback,
void* lpPrivate );
//...
private LPFNART_GUI_CALLBACKFUNC m_CBFunc;
// Create the managed callback function.
private bool ARTToolBarNotifyFunc( void* lpPrivate, uint
dwButtonID, uint nReason )
{
//...
return true;
}
//...
private int CallbackInit()
{
// Create a delegate object for callback and pass it as an
argument to the
// callback-registering function.
m_CBFunc = new LPFNART_GUI_CALLBACKFUNC( ARTToolBarNotifyFunc
);
ART_GUI_toolbar_CB_register(m_hToolBarWnd,
(uint)enumART_GUI_CB.ART_GUI_CB_TOOLBAR,
m_CBFunc, null );
return 0;
}

See also the ...DLL/Samples/C#.NET/ImageGearDemo Sample for details on using ImageGear DLL in the MS VS .NET environment.

See Also:

ImageGear DLL Samples.


ImageGear DLL Samples

Your ImageGear toolkit contains a comprehensive set of sample application programs, which you can load when you install ImageGear's DLL and related files. Each sample is provided in both executable and source form. You can execute each application to see the actual effects of the ImageGear function calls within it, or examine the source file for the interrelated C language and Windows calls. In addition, AccuSoft permits you to use the source code. You can use the sample code as is, or cut and paste from it as you wish, to create, then expand, your own applications. The only restriction is that you may not distribute the original ImageGear sample applications with your applications.

Many ImageGear functions are demonstrated in at least one of the most all-around useful samples DISPLAY. This program lets you load, display, and print images, and also demonstrates the implementation of a status bar, GUI windows and dialogs. By running this application then examining its source code, you can see how the calls to ImageGear functions such as IG_load_...(), IG_dspl_...(), IG_fltr_...(), IG_GUI_...() and IG_gui_...() interact with the requirements and procedures of Windows programming. You can later use this program as a template for developing an application of your own.

Each sample's files are located in a single directory that bears the name of the sample. Sample DISPLAY's files are located in directory:

****\Samples\C\DISPLAY

The source file for this sample is "display.c", so its path\filename is:

****\Samples\C\DISPLAY\display.c

NOTE: Four asterisks represent characters that will vary depending on the ImageGear version in use. See Chapter "Installation" for the DLL **** name applicable to your version.

You can begin developing an application easily by choosing an appropriate sample to start with as a template, making a backup copy to preserve it, and editing it - cutting and pasting whole sections from other samples if you wish. In this way, you will begin with a working program that displays images on your screen from the start, so you can test and debug each new feature as you add it to your code.


Description of Installed Samples

Below is a list of the subdirectories installed within your Samples subdirectory. There is a subdirectory for each sample. Right column also provides short descriptions for every of the sample applications:

Subdirectory
This sample:
ArtXGUI
Demonstrates the use of ImageGear ARTX Component
\C\Alpha
Demonstrate the use of alpha channels.
\C\Artext
Demonstrates the use of ImageGear ART Component features.
\C\ASCII
Demonstrates the loading/displaying of ASCII images.
\C\CLPBRD
Demonstrates the ImageGear copy/cut/paste features.
\C\COLOR
Demonstrates the ImageGear reduce/promote image bit depth features.
\C\DISPLAY
Demonstrates the ImageGear display API including Layout, Orientation, MapMode, Zoom/Scroll and much more.
\C\FILTER
Demonstrates the features of various file formats, primarily TIFF, PDF and JPEG2000 - with the appropriate ImageGear PDF Component and ImageGear JPEG2000 Component attached. Also demonstrates the EXIF file format processing and new ImageGear metadata mechanism, as well as the association of an image with multiple alpha images.
\C\FPX
Demonstrates the loading, displaying, and transforming FlashPix images with the ImageGear FlashPix Component attached.
C\FreqIp
Demonstrates the Frequency Domain Image Processing features.
\C\GUISCAN
Demonstrates how to use the ImageGear's GUI scan window.
\C\GUIWIN
Demonstrates how to use different the ImageGear GUI Windows.
\C\IC
Demonstrates the use of the ImageGear ImageClean Component. Includes such features as "auto-crop", "invert white text" and "clean borders".
\C\IMGPROC
Demonstrates the comprehensive usage of the ImageGear Image Processing API, including the non-rectangular region of interest feature. Also demonstrates the process of blending with alpha images.
\C\IMGUTIL
Demonstrates different ImageGear methods of creating, importing, and exporting images.
\C\IOSET
Demonstrates how to override ImageGear's reading and writing of images by using your own callback functions.
\C\ISIS
Demonstrates the use of the ImageGear ISIS Component.
\C\JPEG
Demonstrates the handling of three JPEG types: Lossless, Progressive, and Lossy. Also demonstrates the ImageGear thumbnail features.
\C\JPIPC
Demonstrates how to use JPIP Client API of ImageGear JPEG2000 Component.
\C\JPIPS
Demonstrates how to use JPIP Server API of ImageGear JPEG2000 Component.
\C\Legacy_Alpha
Demonstrates how to use legacy ImageGear API.
\C\Legacy_Color
Demonstrates how to use legacy ImageGear API.
\C\Legacy_LoadCB
Demonstrates how to use legacy ImageGear API.
\C\Legacy_pix_acc
Demonstrates how to use legacy ImageGear API.
\C\LOADCB
Demonstrates how to use ImageGear load callback functions.
\C\MAGNIFY
Demonstrates how to use the GUI Magnify window.
\C\MED
Demonstrates the imaging features of ImageGear Medical Component.
\C\MediaPlayer
Demonstrates how to use ImageGear multimedia functions (IG_mult_...()).
\C\MEMIO
Demonstrates the image loading from and saving to memory.
\C\MULT
Demonstrates the ImageGear Multimedia Component features.
\C\PAGE
Demonstrates the use of the GUI Page Sorter.
\C\PALEDT
Demonstrates the use of the GUI Palette Editor.
\C\PAN
Demonstrates the use of ImageGear's Pan window.
\C\PIXACC
Demonstrates the reading and writing of individual pixels and rows and columns of pixels using ImageGear's Pixel Access functions.
\C\PJPEG
Demonstrates the scanning of Progressive JPEG format.
\C\POSTER
Demontrates the ImageGear printing features. Prints a poster from a given image.
\C\PRINT
Demontrates the ImageGear printing features. Prints to printer, or directly to driver. Prints a single image on a single page, or many images on a single page.
\C\Recognition
Demonstrates the ImageGear Recognition Component features.
\C\THUMB
Demonstrates the use of ImageGear's GUI Thumbnail Sorter window. This makes thumbnail representations of "normal-size" images.
\C\TIMING
Demonstrates the benchmark of ImageGear API.
\C\TWAIN
Demonstrates all aspects of ImageGear's TWAIN support, including scan callbacks.
\C\VECTOR
Demonstrates the use of ImageGear CAD/Vector DGN Component, ImageGear CAD/Vector DWF Component, ImageGear CAD/Vector DWG, DXF Component, ImageGear CAD/Vector HPGL, HPGL/2 Component , ImageGear CAD/Vector CGM Component , ImageGear U3D Vector Component features.
\C\WIPES
Demonstrates ImageGear's wide choice of wipe display effects.
\C#.NET\ImageGearDemo
Demonstrates the use of ImageGear with C#.NET programming environment.
\Delphi\IGDemo
Demonstrates the use of ImageGear with Delphi programming environment.
\GUI
Demonstrates the use of ImageGear GUI dialogs.
\JNI
Demonstrates the use of ImageGear with Java programming environment..
\MFC\MFC
Demonstates the use of ImageGear with MFC programming environment.
\MFC\MULTPAGE
Demontrates the use of the ImageGear enhanced multi-page API.
\MFC\PDFDemo
Demontrates the use of the ImageGear ImageGear PDF Component API.
\MFC\THREADS
Demontrates the ImageGear thread safety features.


Using ART Component (A Quick Start Tutorial)

The following tutorial explains how to display the ART toolbar and how to respond to the selection of a button. Two buttons are discussed - the Typed Text button, and the Select button.

To save time, this tutorial hard-codes one image for display and loads with the click of a menu item. The focus of this tutorial is how to add ART component functionality to your ImageGear application. When complete, it displays the ART toolbar and responds to the selection of two buttons: the Typed Text button and the Select button.

At the top of your main program module, you need to place the main ART public header file. It is required for the ART prototypes and macros:

i_ART.h

In addition, if you plan on using ART's GUI tools, including the toolbar and property sheets (which this Tutorial does), you need to include:

artgui.h

Before you can load an image that can be marked up using ART functions, you need to attach the ART component using the ImageGear DLL function IG_comm_comp_attach ():

IG_lic_solution_name_set( "AccuSoft 1-104-16" );
...
IG_comm_comp_attach("ART");

The following code must be added to the application's main window procedure to allow ART to process mouse messages:

AT_POINT		pt;
LPARAM		lparam;
HIGEAR 		hIGear;
HWND		hWnd;
MSG		msg;
AT_MODE		nUserMode;
        .	.	.
case WM_LBUTTONDOWN:
case WM_LBUTTONDBLCLK:
case WM_LBUTTONUP:
    if (IG_image_is_valid(hIGear))
    {
        pt.x = LOWORD(lParam);
        pt.y = HIWORD(lParam);
ART_GUI_interaction_process(hIGear,
       IG_GRP_DEFAULT,
hWnd,msg, nUserMode, &pt);
    }
    break;

The following code is necessary to process the cursor messages:

    /* In addition to variables intitialized above: */
    HCURSOR		hCursor;
    POINT		ptPos;
    HWND	hwndToolbar
        .	.	.
    case WM_SETCURSOR:
        if (IG_image_is_valid(hIGear) &&
          LOWORD(lParam) == HTCLIENT)
        {
            GetCursorPos(&ptPos);
            ScreenToClient(hWnd, &ptPos);
            pt.x = ptPos.x, pt.y = ptPos.y;
          /* Ask ART to provide the cursor */
        ART_GUI_cursor_query	(hIGear, IG_GRP_DEFAULT, hWnd,
nUserMode, &pt, &hCursor, NULL);
          SetCursor(hCursor);
          return TRUE;
}
return DefWindowProc(hWnd, msg, wParam, lParam);

Create a menu item that displays the ART toolbar and registers a callback function of type LPFNART_GUI_TOOLBARNOTIFYFUNC to let you know when the user presses a toolbar button. For example, under a View Menu, you might have a menu item that says "Show Toolbar". Add the following code for "Show Toolbar":

LPFNART_GUI_TOOLBARNOTIFYFUNC ARTToolBarNotifyFunc;
    .	.	.
ART_GUI_toolbar_create	(hWnd, 13, 54, &hwndToolbar);
ART_GUI_toolbar_CB_register	(hwndToolbar, ART_GUI_CB_TOOLBAR,
ARTToolBarNotifyFunc, NULL);

Now write your code for the toolbar callback function that you just registered above:

BOOL FAR PASCAL ARTToolBarNotifyFunc(
    LPVOID	lpPrivate,		/* private callback data				*/
    DWORD	dwButtonID,	/* ID of button (mark type) 	*/
    UINT	nReason	/* Reason for callback		*/
)
{
    ART_MARK_ATTRIBUTES ma;	/*annotation mark attribs	*/
    DWORD	dwBlockSize;		/* Size of a named block	*/
    LPART_TEXTPRIVDATA lpTextPriv; /*for text marks 	*/
    if (nReason == ART_GUI_TOOLBAR_BUTTON_SELECTED	)
    {
        memset(&ma, 0, sizeof(ART_MARK_ATTRIBUTES));
        switch (dwButtonID)
        {
           case ART_BUTTON_SELECT_TOOL:
            ART_GUI_tool_set(hIGear, NULL);
            break;
           case ART_BUTTON_TYPED_TEXT	:
            ma.dwType = ART_MARK_TYPED_TEXT;
            ma.rgbColor1.rgbRed   = 0xFF;
            ma.bVisible = TRUE;
            ma.lfFont.lfHeight = -15;
            ma.lfFont.lfWeight = FW_NORMAL;
            ma.lfFont.lfCharSet = DEFAULT_CHARSET;
            ma.lfFont.lfOutPrecision = OUT_TT_ONLY_PRECIS;
            ma.lfFont.lfClipPrecision =
               CLIP_DEFAULT_PRECIS;
            ma.lfFont.lfQuality = DEFAULT_QUALITY;
            ma.lfFont.lfPitchAndFamily = FF_SWISS;
            lstrcpyn(ma.lfFont.lfFaceName, "Arial",
            sizeof(ma.lfFont.lfFaceName));
            /* clear out the previous text priv data */
            dwBlockSize = sizeof(ART_TEXTPRIVDATA);
            lpTextPriv = (LPART_TEXTPRIVDATA)
            LocalAlloc(LPTR, (UINT)dwBlockSize);
            #ifdef WIN32
        memset(lpTextPriv, 0, (UINT)dwBlockSize);
            #else
    _fmemset(lpTextPriv, 0, (UINT)dwBlockSize);
            #endif
            /* create a blank text data block */

            ART_global_block_create(hIGear,
            ART_BLOCK_ANTEXT lpTextPriv, dwBlockSize);

            LocalFree((HLOCAL)(UINT)(DWORD)lpTextPriv);
            ART_GUI_tool_set(hIGear, &ma);
            break;
            }
      }
}

Note that this code checks to see when a button is selected, and if it is one of the two above-mentioned buttons. We then set any appropriate attributes or blocks, and then call the function ART_GUI_tool_set (), which sets the fields in the Mark Attributes structure (defined in artapi.h) and in doing so also sets the type of mark that is created. The dwType field of the Mark Attributes structure holds the type of mark to create.

NOTE: When the Select button is chosen, no mark attributes structure is needed, so ART_GUI_tool_set() is called with its second argument set to NULL. The Select button is the only button on the toolbar that does not use a mark attributes structure.

In addition to having a Mark Attributes structure initialized for it, the Typed Text mark object needs to have a global block of type ART_BLOCK_ANTEXT created. See the section "Mark Objects: Descriptions, Types and Attributes" on page -311 to know what kinds of global blocks are needed for each type of mark.

Create a menu item called Open under the File menu that loads a file. Add the following line of code:

nErrCount = IG_load_file("C:\anyPicture.jpg", &hIGear);

(You'll need to supply the image.)

ART supplies "property sheets" for each kind of mark. These give the user an interactive way to change the attributes of a mark. Next we add code that makes a property sheet appear any time the end user clicks the right mouse button over a mark (while in edit mode).

Add the following lines to the WM_RBUTTONDOWN case of your main window:

case WM_RBUTTONDOWN:
if (IG_image_is_valid(hIGear))
{
    rcHit.left = rcHit.right = LOWORD(lParam);
    rcHit.top = rcHit.bottom = HIWORD(lParam);
    ART_GUI_mark_hit_test(hIGear, hWnd, IG_GRP_DEFAULT, &rcHit,
&hMarkIndex, 1, &dwMarkCount,NULL, NULL);
    /* draw the property page */
    ART_mark_query(hIGear, hMarkIndex, &ma);
    IG_image_DIB_pntr_get(hIGear, &lpDIB);
    ART_GUI_property_sheet_create(hWnd, lpDIB, &hPropertySheet);
    ART_GUI_property_sheet_init	(hPropertySheet,
ART_GUI_INIT_ATTRIBUTES, &ma, NULL, NULL, 0L);
    ART_mark_block_first	(hIGear, hMarkIndex, &byBlockName);
    while (*byBlockName)
    {
    ART_mark_block_query(hIGear, hMarkIndex, &byBlockName, NULL,
&dwBlockSize);
        if (dwBlockSize)
        {
        hGlobal = GlobalAlloc(GMEM_MOVEABLE, (UINT)dwBlockSize);
              lpBlockData = GlobalLock(hGlobal);
            if (lpBlockData)
            { 		ART_mark_block_query(hIGear, hMarkIndex,
&byBlockName,lpBlockData, &dwBlockSize);
    ART_GUI_property_sheet_init(hPropertySheet,
ART_GUI_INIT_NAMED_BLOCK, NULL, &byBlockName, lpBlockData,
dwBlockSize);
            }
            GlobalUnlock(hGlobal);
            GlobalFree(hGlobal);
        }
      ART_mark_block_next	(hIGear, hMarkIndex, &byBlockName);
    }
    if (ART_GUI_property_sheet_show	(hPropertySheet))
    {
      ART_GUI_property_sheet_query(hPropertySheet,
ART_GUI_QUERY_ATTRIBUTES	,&ma, NULL, NULL, NULL);
      ART_mark_modify	(hIGear, hMarkIndex, &ma);
      ART_mark_block_first	(hIGear, hMarkIndex, &byBlockName);
      ART_GUI_property_sheet_query(hPropertySheet,
ART_GUI_QUERY_ATTRIBUTES	,&ma, NULL, NULL, NULL);
      ART_mark_modify	(hIGear, hMarkIndex, &ma);
      ART_mark_block_first	(hIGear, hMarkIndex, &byBlockName);
       {
           hGlobal=GlobalAlloc(GMEM_MOVEAB(UINT)dwBlockSize);
      lpBlockData = GlobalLock(hGlobal);
      if (lpBlockData)
      {
             ART_GUI_property_sheet_query(hPropertySheet,
ART_GUI_QUERY_NAMED_BLOCK, NULL, &byBlockName, lpBlockData,
&dwBlockSize);
          ART_mark_block_create(hIGear, hMarkIndex,
    &byBlockName, lpBlockData, dwBlockSize);
           }
           GlobalUnlock(hGlobal);
           GlobalFree(hGlobal);
       }
      ART_mark_block_next(hIGear, hMarkIndex, &byBlockName);
   }
   ART_GUI_mark_paint	(hIGear,
          IG_GRP_DEFAULT, hMarkIndex, hWnd, TRUE);
    }
    ART_GUI_property_sheet_destroy	(hPropertySheet);
    break;
  }
  break;

Now you can compile and run your mini-application.

For a more elegant example of what you can do using the ART component with core ImageGear, please see the ART sample application.


Using ImageGear

This chapter describes how to use ImageGear's functions to fulfill your applications' imaging needs. The function groups are outlined in ImageGear Overview. There are also many examples that show you how to use ImageGear functionality. Additional examples and recommendations for using ImageGear functions can be found in the API Function Reference chapter for respective component as well as in Getting Started Chapter.

To recognize ImageGear functions naming convention, ImageGear data types and data structure please see the sections:

  • Core Component Function Naming Conventions
  • How to Call an ImageGear Function
  • ImageGear Data Types and Structures

Please read the section ImageGear Licensing API, which describes how to use the ImageGear licensing functions to provide an evaluation, development or deployment license to your ImageGear application.

This chapter includes the following basic sections that describe ImageGear structure and its public functionality:

  • Loading Images
  • Saving Images
  • Displaying Images
  • Image Processing
  • Pixel Access Operations
  • Clipboard Operations
  • Printing Images
  • Thread Safety

The concept of the functions including loading, displaying, saving images, image processing, special effects, thread safety, pixel accessing, etc. are described in these sections.

The following sections describe how to work with special function groups and special groups of images:

  • Working with Format Filters
  • Working with ImageGear Color Profile Manager
  • Working with Global Control Parameters
  • Working with Color Space Conversion Engine
  • Working with Grayscale Look Up Tables
  • Working with ImageGear Layers
  • Working with Multi-page Images
  • Working with ImageGear GUI Functions
  • Working with ImageGear GUI Dialogs
  • Working with Image Utility Functions
  • Working with Library Utility Functions
  • Working with ImageGear Callback Functions
  • Working with Stripped Images
  • Working with Tiled Images
  • Working with Vector Data
  • Working with Run Ends Format
  • Working with ImageGear Digital Camera RAW Filter

Please see the section Using Format Filters API for Filter Control for the image control parameters setting.

Also take a look at the Non-Image Data Processing section, which describes ImageGear features, providing you with the possibility to read/write metadata information from/in such formats as JPEG, TIFF, EXIF, EXIF-TIFF, EXIF-JPEG, PNG, IPTC, GIF, CIFF, DC RAW, JPEG2000, and XMP.

You can find the detailed information about how to use the functionality of ImageGear components in the following sections:

  • Using ImageGear Component Manager
  • Using ImageGear ARTX Component
  • Using ImageGear ART Component
  • Using ImageGear CAD/Vector Components
  • Using ImageGear ISIS Component
  • Using ImageGear JBIG2 Component
  • Using ImageGear JPEG2000 Component
  • Using ImageGear MD Component
  • Using ImageGear Multimedia Component
  • Using ImageGear PDF Component
  • Using ImageGear Recognition Component
  • Using ImageGear Twain Component


Core Component Function Naming Conventions

We have carefully named ImageGear Core Component functions with the goal of making them self-documenting and easy to find within Core Component API Function Reference, which is the reference section of this manual.

With the exception of callback functions which always begin with the prefix "LPFNIG", the function names adhere to the following conventions:

  • All function names begin with the prefix "IG_" (always in uppercase). This is to identify it as an ImageGear function, and to avoid conflicts with your application's functions.
  • Following "IG_" is the name of the group to which the function belongs. Table below displays ImageGear function groups and describes their functions
    Function name
    Function purpose
    IG_clipboard_ ...()
    Clipboard
    IG_ ... _CB_ ...() or LPFNIG_ ...()_CB_
    Callback
    IG_colorspace_conversion_ ...()
    Color space conversion
    IG_comm_ ...()
    Component manager
    IG_cpm_ ...()
    Color profile manager
    IG_DIB_ ...()
    DIB Info Services
    IG_display_ ...()
    Display
    IG_dspl_ ...()
    Displaying and printing
    IG_error_ ...(), IG_version_ ...(), IG_err_...()
    Library utility
    IG_fltr_ ...()
    Format Filter processing
    IG_FX_ ...()
    Special Effects
    IG_image_ ...() or IG_palette_ ...()
    Image utility
    IG_IP_ ...()
    Image processing
    IG_gctrl_ ...()
    Global control parameters processing
    IG_GUI_ ...()
    Graphical user interface
    IG_load_ ...()
    Loading
    IG_mult_ ...()
    Multimedia
    IG_pixel_ ...()
    Pixel access
    IG_save_ ...()
    Saving
    IG_thread_ ...()
    Thread safety
    IG_util_colorspace_ ...()
    Color space utility
    IG_vector_...()
    Vector utility


How to Call an ImageGear Function

To call an ImageGear function, use a normal C statement, such as:

   nErrcount = IG_load_file("picture.bmp", &hIGear);

The above calls a function named IG_load_file (), which loads an image file into memory and provides a handle by which you can refer to the image in subsequent ImageGear function calls.

As described in the "Core Component API Function Reference" , this function requires two arguments: a pointer to a character string specifying the name of the file to load, and a pointer to avariable of type HIGEAR. This second argument will hold the HIGEAR image handle returned by the function. Also, the function returns the number of ImageGear errors, if any, that occurred during execution of the function to the merchant.

Additional statements are needed to support the above function call. These are shown in the more complete example below:

#include "gear.h"
   ...
   HIGEAR       hIGear;        /* handle of image in mem 				*/
   AT_ERRCOUNT  nErrcount;     /* holds # of errs on stack */
   ...
   nErrcount = IG_load_file ("picture.bmp", &hIGear);
   if (nErrcount != 0) {...}  /* if errs have been reported */

The statement #include "gear.h" is required in all modules containing ImageGear function calls. It tells the C compiler how each ImageGear function must be called, and also defines ImageGear's special data types, data structures, and constants. The two statements:

 HIGEAR     hIGear;    /* HIGEAR handle of image  */
 AT_ERRCOUNT  nErrcount; /* to check for errs during func */

are necessary to define variables used in the function call. The handle of an ImageGear image is always of type HIGEAR. The value that is returned by function IG_load_file () and most ImageGear functions is of type AT_ERRCOUNT. This return value contains the number of ImageGear errors generated.

It may be mentioned here that once you have the HIGEAR handle of an image, you have the key to the full power of ImageGear. Supplying this handle to an ImageGear function provides all the access it needs to the image's DIB, color Look Up Tables (LUTs), display attributes, and other information that defines the state of the image in memory. The HIGEAR image handle is usually provided to you upon the load, import, or create operation in which the image's DIB first comes into existence.

The two statements of the example below invoke the ImageGear function IG_load_file (), and test for any error condition upon its return:

   nErrcount = IG_load_file ("picture.bmp", &hIGear);
   if (nErrcount != 0) {...} /* if any errs during call... */

Most ImageGear functions, including IG_load_file(), return a value of type AT_ERRCOUNT. This is a count of ImageGear errors reported by the ImageGear function you called and any functions it has called. Whenever this returned count is non-zero, you should examine the contents of the error stack to determine whether some special action is required by your application. How to obtain the contents of the stack, learn specifically which errors have occurred, and clear the stack, is covered in Detecting and Handling Errors.


ImageGear Data Types and Structures

This section provides you with the list of the Data Types and Data Structures that you will encounter in ImageGear IG_ ...() function call. Each of them has a short description.


Data Types

  • ACCUAPI: A string directing your C/C++ compiler as to how the given ImageGear function should be called. Remember to include this in your callback function declarations, as shown in the examples of coding callback functions.
  • AT_ERRCOUNT: Type of the value returned by most ImageGear functions. It is an integer equal to the number of errors placed on the ImageGear error stack during execution of the function and any lower level functions called.
  • AT_LMODE: Type of a 32-bit constant (such as IG_SAVE_BMP_RLE), or of a variable containing such a value, used to declare what mode of operation a function should use. Most variables have constants defined for them in accucnst.h. Occasionally a variable of this type will be a Windows constant.
  • AT_MODE: Type normally used for a constant that is used to specify an option in a call to an ImageGear function. Examples are IG_CONTRAST_PIXEL or IG_ASPECT_DEFAULT. This type is used when the constant's value can never require more than 16 bits.
  • AT_BOOL: An integer that is interpreted as FALSE if 0 and TRUE if non-0.
  • AT_DIMENSION: Type usually used for the width in pixels or height in rows, of an image in memory or of a display area on a display device.
  • HDC: Windows handle of a Windows Device Context.
  • HBITMAP: Windows handle of a Device-Dependent Bitmap (DDB) or of a Windows Resource.
  • HIGEAR: Handle of a comprehensive ImageGear data structure that defines an image along with its display attributes, Look Up Tables, DIB, and other data necessary for maintaining the image and providing access to its pertinent data for your application program.
  • HPALETTE: Windows handle of a palette.
  • HWND: Windows handle of a window on a display device.
  • LP ...: Far (long) pointer to an object of type "..." For example, LPDIMENSION means a FAR pointer to a variable of type
  • DIMENSION, LPAT_RECT means FAR pointer to a structure of type
  • AT_RECT.
  • AT_PIXEL: A BYTE, usually a byte in an image bitmap.
  • AT_PIXPOS: A 32-bit integer value specifying a pixel x or y coordinate.


Data Structures

AT_DIB

Type of the ImageGear DIB header struct (equivalent to Windows struct BITMAPINFOHEADER):

WORD       biSize;
LONG        biWidth;
LONG        biHeight;
WORD        biPlanes;
WORD        biBitCount;
DWORD       biCompression;
DWORD       biSizeImage;
LONG        biXPelsPerMeter;
LONG        biYPelsPerMeter;
DWORD       biClrUsed;
DWORD       biClrImportant;

biSize

Total length of this struct in bytes

biWidth

Number of pixels in each raster (row) of the bitmap

biHeight

Number of rasters (rows) in the bitmap

biPlanes

Number of bit planes. Always = 1

biBitCount

Number of bits per pixel (bit depth): 1, 4, 8, 9-16-bit gray level, or 24, 32

biCompression

Type of compression, or 0 (IG_BI_RGB) if bitmap not compressed. IG_BI_RGB, IG_BI_RLE, IG_BI_CMYK or IG_BI_ABIC

biSizeImage

Total number of bytes in bitmap (necessary if bitmap is compressed; may be 0 if bitmap is IG_BI_RGB)

biXPelsPerMeter

Pixels per meter horizontally if known (else 0)

biYPelsPerMeter

Rows per meter vertically if known (else 0)

biClrUsed

Number of entries in the color palette that are actually used. (The number of unique pixel values that occur.) If 0, it is assumed all palette entries are used.

biClrImportant

Number of palette entries considered important. If 0, all are important.

AT_POINT

This struct is simply the X and Y coordinates of a point.

AT_PIXPOS x;
AT_PIXPOS y;

x

X coordinate of the point

y

Y coordinate of the point

AT_RECT

This is the type of all rectangles used in calls to ImageGear IG_...() functions (do not confuse with Windows struct type RECT, in which the type of the coordinates is different)

AT_PIXPOS left;
AT_PIXPOS top;
AT_PIXPOS right;
AT_PIXPOS bottom;

left

X coordinate of the upper left corner of rectangle

top

Y coordinate of the upper left corner of rectangle

right

X coordinate of the lower right corner of rectangle

bottom

Y coordinate of the lower right corner of rectangle

AT_RESOLUTION

This struct describes an image's resolution. This information is used to map between a number of pixels and a physical length measurement. For example, if you have an image which is 600 pixels wide, and the horizontal resolution is specified as 300 DPI (dots per inch, IG_RESOLUTION_INCHES), then the image should be 2 inches wide when printed.

LONG	 xResNumerator,
LONG	 xResDenominator,
LONG	 yResNumerator,
LONG	 yResDenominator
AT_LMODE	 nUnits;
See Also:

IG_image_resolution_get ()

IG_image_resolution_set ()

AT_RGB

This struct contains three color bytes ordered as in the image bitmap of a standard DIB. Note the order carefully.

AT_PIXEL b;
AT_PIXEL g;
AT_PIXEL r;

b

Byte containing blue component of color, 0 to 255

g

Green component of color

r

Red component of color

AT_RGBQUAD

Type of a DIB palette entry. This struct contains four bytes; note the order carefully.

AT_PIXEL rgbBlue;
AT_PIXEL rgbGreen;
AT_PIXEL rgbRed;
AT_BYTE rgbReserved;

rgbBlue

Byte containing blue component of color, 0 to 255

rgbGreen

Green component of color

rgbRed

Red component of color

rgbReserved

Reserved, should be 0

BITMAPINFOHEADER

See structure type AT_DIB.


ImageGear Licensing API

Before you can use any ImageGear functionality you need to call the ImageGear licensing API. When you evaluate the product or develop your application using ImageGear you have to call the following function:

IG_lic_solution_name_set (LPCHAR lpSolutionName)

and pass 'AccuSoft 1-100-16' as lpSolutionName argument.

The ImageGear samples installed with the product already have this call included, so you can simply copy/paste this call from the source code of the samples.

NOTE: ImageGear reads the license information from registry. You have to obtain the product license (evaluation or development) using AccuSoft License Manager (see the section ImageGear Licensing) in order for the product to work.

When you're ready to deploy your application please contact AccuSoft about obtaining License Deployment Kit. It will explain additional steps (including the API calls) that you need to take in order to deploy your application.


Loading Images

The IG_load_...() functions provide you with a convenient way to bring images from image files into ImageGear's sphere of influence. The image files may be on a mass storage device such as a disk, or they may already be in memory.

When you load an image using an IG_load_...() function, ImageGear provides you with a handle of ImageGear type HIGEAR. Having HIGEAR handles for your images, your application has access to ImageGear's full power, and can perform the entire range of ImageGear's imaging operations.

The IG_load_ ...() functions aren't the only way to get images under ImageGear's control. You can import images that exist as plain bitmaps, DIBs, or DDBs in your application. You can scan images from the outside world, directly into ImageGear. You can locate and extract ASCII or graphics images from multi-page (multi-image) files, using ImageGear's GUI browse and other capabilities. See also Using ImageGear Twain Component and Working with Image Utility Functions .

An IG_load_ ...() functions create a DIB in memory, and transfer the bitmap and other pertinent information (such as the image's color palette, if one is associated with it, and header information such as width, height, and bits per pixel) into this DIB. These functions do not display the image unless the word "display" is included in the name, such as in IG_load_file_display ().

Here are a few examples showing how to call the functions in this group. Refer to "Core Component API Function Reference" for more information on the IG_load_ ...() functions.

Example 1:

#include "gear.h"
HIGEAR        hIGear;        /* HIGEAR handle returned   */
AT_ERRCOUNT   nErrcount;     /* Count of errors reported */
nErrcount = IG_load_file ("picture.bmp", &hIGear);

The above loads file picture.bmp from the current directory, creating a DIB in memory, and creates a unique ImageGear handle for it, returning this handle to you in hIGear.

Example 2:

HIGEAR        hIGear;        /* handle returned by ImageGear  */
char *        lpWhereFile;    /* ptr to image file in mem     */
DWORD         dwWholeSize;  /* size of image file in mem     */
UINT          nPageNum;               /* will be 0 for this call
*/
AT_ERRCOUNT   nErrcount;  /* to test for errors            */
nPageNum     = 0;        /* not a multi-page file        */
lpWhereFile  = ...;     /* where mem image file begins   */
dwWholeSize  = ...;      /* size of whole mem image       */
nErrcount = IG_load_mem (lpWhereFile, dwWholeSize,nPageNum, 0,
&hIGear);

IG_load_mem () is used to load an image from memory. The image in memory must be in the same format as if the image were in a disk file. For example it must contain an appropriate header, the bitmap data, and if necessary, a palette. This in-memory file must be of a format recognized by ImageGear (See , "File Format Reference").

In the above call, dwWholeSize must be the size of the entire memory image, not just of the bitmap. lpWhereFile must point to the first byte of this whole image. And nPageNum, if not zero, would specify the page number to load if loading from a multi-page (multiple image) file. Please note that the first page of a multi-page file is page number 1, not page number 0. The function IG_load_mem() creates a DIB and loads into it the image you've specified, and returns in hIGear the new HIGEAR image handle by which you will refer to this image in subsequent calls to ImageGear functions.

Names of some IG_load_ ...() functions contain the letters "FD", for example IG_load_FD_CB (). These functions access the file by its File Descriptor handle, which is an integer value returned to you when you open the file using certain Windows functions. You may use these IG_load_FD...() functions to load an image from a file, if the file is already open and your application has its File Descriptor handle. Following is an example showing an ImageGear IG_load_FD...() loading from the file that has been already opened by means of Windows function _lopen() or other file I/O function that returns a File Descriptor handle:

Example 3:

HIGEAR        hIGear;      /* handle ret'd by IG_load_FD   */
INT           fd;        /* File Descriptor handle       */
LONG          lOffset;     /* offset to image in file    */
UINT          nPageNum;  /* will be 0 for this call      */
AT_ERRCOUNT nErrcount;    /* to test for errors          */
fd = _lopen ( "picture.bmp", OF_READ );    /* open file     */
nPagenum   = 0;         /* not a multi-page file      */
lOffset    = 0;         /* access file from start     */
/* Load image, and obtain its ImageGear handle: */
nErrcount = IG_load_FD (fd, lOffset, nPageNum, 0, &hIGear);

If nErrcount is zero, a DIB is created, the image is loaded, and your HIGEAR object, &hIGear, contains its HIGEAR handle.

TIP: For information about loading CMYK images, see Working With Color Space Options.
See Also:

Using the Format Filters API for Image Loading and Getting Information.


Working With Color Space Options

ImageGear offers different levels of support for the supported color spaces. For CMYK, there are two such levels:

  1. your application can read and write CMYK and leave it in its native format
  2. your application can read CMYK but converts it to RGB.

ImageGear has two API for working with color space options:

IG_color_space_level_get ()
Returns the support level currently set for the color space that you specify.
IG_color_space_level_set ()
Sets the support level for the color space you specify.

Each of these functions takes two constants for arguments-one to identify the color space, the second to get/set the desired support level for that color space. The constants are of type AT_MODE and can be found in accucnst.h.

To select CMYK color space, use the constant IG_COLOR_SPACE_CMYK. The constants for CMYK support are IG_CMYK_CONVERT_TO_RGB, and IG_CMYK_FULL_SUPPORT.

The following call would set CMYK support to "full", meaning that ImageGear will read in CMYK and allow you to save the image as CMYK:

IG_color_space_level_set(IG_COLOR_SPACE_CMYK,
IG_CMYK_FULL_SUPPORT);


Saving Images

The IG_save_...() family of functions is complementary to the IG_load_...() functions. The IG_save_...() functions allow you to save images to disk files or to memory, convert files from one file format to another, and to append or insert images as pages to a multi-page file. All IG_save_...() functions have the lFormatType parameter in common. This allows you to choose which ImageGear-supported file format and compression type (where applicable) to save to. Whereas some functions, such as IG_info_get_ex (), have separate parameters for the format and compression types, the saving functions have one parameter that covers both.


The Image Rectangle

In ImageGear, an "image rectangle" defines the coordinates for the area of the bitmap that will be saved or displayed. The image rectangle represents a rectangular array of pixels from the bitmap that can include the whole image or any rectangular portion of the image.

You can leave the image rectangle set to its default, which includes the whole image, or you can specify a portion of the image by setting the image rectangle with IG_dspl_layout_set (). A call to this function is included in the example code in Saving an Image to Memory. You can also find a detailed description and example of this function's use in "Core Component API Function Reference".

TIP: For a more detailed description of the Image Rectangle and other ImageGear display rectangles, see Geometric Layout.


Saving Images to a Disk File

IG_save_file(HIGEAR hIGear, lpszFileName, lFormatType)

is the function normally used to save a HIGEAR image to disk. The name of the file to save to is specified through the second argument, and the format type and compression type (if applicable) in which to save it is specified in the third. If the file format being used supports more than one compression type, more than one constant will be available. The BMP format, for example, is provided with two values for lformatType: IG_SAVE_BMP_UNCOMP and IG_SAVE_BMP_RLE.

The file accucnst.h defines the constants to which lFormatType may be set. These constants are also listed at the end of "File Format Reference".

If the file already exists and the format supports multiple pages, IG_save_file() will append the new image(s) to the file. If the file already exists and it is a single image format type, the file will be overwritten.

Here is an example of code that calls IG_save_file():

HIGEAR hIGear;             /* handle ret'd by IG_load_...     */
AT_ERRCOUNT nErrcount;     /* # of errors on stack          */
AT_LMODE lFormatType;      /* format type to save to        */
/*set format and compression to an AT_LMODE constant       */
lFormatType = IG_SAVE_TIF_UNCOMP;
nErrcount = IG_save_file(hIGear, "picture.tif", lFormatType);

If you do not know what format your file is in, you may set lFormatType to IG_SAVE_UNKNOWN. ImageGear will check the file's extension and save the image accordingly. If you set lFormatType to other than IG_SAVE_UNKNOWN, ImageGear assumes that you are giving it the correct type and saves the image accordingly.

TIP: Before selecting a file format to save to, you can reference the section entitled ImageGear Supported Bit Depths to ensure that you save to a format that supports the same bit depth as the original image.


Saving to a Disk File Using a File Descriptor Handle

You can use IG_save_FD () function to save a HIGEAR image to a file that has already been opened and for which you have a File Descriptor handle (for example, your application may have opened the file using the Windows function _lopen()). IG_save_FD() will permit you to insert an image into a multi-page file (instead of merely appending it as IG_save_file () would do.)

IG_save_FD() is called with five arguments, of which the HIGEAR image handle and lFormatType have the same meaning as in a call to IG_save_file(). The other parameters are the File Descriptor handle, fd obtained by the Windows function call that opened the file, a reserved argument nReserved, which should always be set = 0, and nPageNum, which allows you to specify what page to insert the image in. If you want to append image(s) to a file, you can set nPageNum to IG_APPEND_PAGE. The following example shows IG_save_FD () being used to insert an image as page 3 into an existing a multi-page file:

HIGEAR		hIGear;		/* ImageGear handle         	*/
INT		d;		/* File Descriptor handle	*/
UINT		nPageNum,		/* page # to insert image as	*/
        nReserved;		/* for future expansion	*/
AT_ERRCOUNT nErrcount;				/* # of errors on stack	*/
AT_LMODE		lFormatType;		/* type of format to save to			*/
/ *Windows call to open file with write privileges 					*/
fd = _lopen("picture.tif", WRITE);
nPageNum = 3;			/* save this image as page #		*/
nReserved = 0;			* always set to 0 for now		*/
lFormatType = IG_SAVE_TIF_JPG; /* format is TIFF-JPEG					*/
/* save the HIGEAR image as page 3 of file whose descriptor is
fd:*/
nErrcount = IG_save_FD(hIGear, fd, nPageNum,
nReserved,lFormatType,);

If the file "picture.tif" has five pages, the new image will be inserted into position of the third page, and what was formerly page three will now be page four, and so on. Remember that ImageGear treats the first page of a multi-page file as page 1, not 0. Setting the nPageNum parameter to 0 will append your image(s) to the file. If you set nFormatType to a type that doesn't support multiple pages, then the file will be overwritten with a single image.

NOTE: Inserting pages to a multi-page file does not physically rearrange the image in the file. Rather, the offset table is adjusted to hold the new address(es) of the inserted page(s), and the new order of the image within the file.

lFormatType should be set to one of the IG_SAVE_ constants, which also include the compression type. Note that TIFF has more than one compression type, and that there are different constants to represent TIFF with each type of compression. If you call IG_save_FD () for a multiple-page file, you must supply the format type (from accucnst.h) for the image to be appended to the file. If you do not know the format of the destination file, first call IG_info_get_FD_ex () and use the format information returned to decide which format to use.

The following pseudo-code example demonstrates how to write a multi-page image using IG_save_FD():

lFormat = IG_SAVE_TIF_UNCOMP;
fd = _lopen (szFile,OF_READWRITE);
for (i = 1; i<=nPages; i++)
{
/*Seek to the beginning of the file before writing each page
ImageGear will automatically find the correct file position of
the new page */
    seek(fd, 0, SEEK_SET );
    /*Write each next page 				*/
    nErrcount = IG_save_FD(hIGear, fd, i, 0, lFormat);
}
close(fd);
NOTE: When you call OS SEEK or an equivalent function to set the file pointer, the stream needs to be positioned at the FIRST byte of a multi-page image. This is the only way in which a filter can recognize that the image is multi-page.

A file should be opened with both READ and WRITE access.


Saving an Image to Memory

ImageGear allows you to save images to memory, in the same way as you save images to a disk file. See Using Format Filters API for Image Saving / Saving Images to Memory section for details.

See Also:

Using Format Filters API for Image Saving


Converting Images from One File Format to Another

Converting a file from one file format to another is simply a matter of loading a file from disk using IG_load_file () or other load function, and then saving it with a new format type. Be sure, however, that the bit depth of the original file can be supported by the new format type. To help you with this, we have provided you with a Format Bit Depths table in the section entitled ImageGear Supported Bit Depths. Here is an example in which a Windows Bitmap file (BMP) is converted to a TIFF file (.TIF):

HIGEAR      hIGear;        /* HIGEAR handle returned        */
AT_ERRCOUNT nErrcount;     /* # of errors on stack          */
AT_LMODE    lFormatType;   /* format to save to             */
/* Set name of BMP file to load and format to save to       */
lFormatType = IG_SAVE_TIF_UNCOMP;
/* Load picture.bmp, obtaining ImageGear handle of image     */
nErrcount = IG_load_file("picture.bmp", &hIGear);
if (nErrcount == 0 )          /* If successful:              */
{
    /* save image as a TIFF file:                            */
    nErrcount = IG_save_file(hIGear, "picture.tif", lFormatType
);
}
NOTE: If the file named "picture.tif" already exists, the image will be appended to `picture.tif' because TIFF supports multiple images in a single file.

For more detail on the ImageGear IG_save_...() functions, see Core Component API Function Reference.

TIP: In order to save an image using ImageGear, it must have a HIGEAR handle. If your image is in DIB format, use: IG_image_DIB_import() or IG_image_create_DIB_ex() to assign it a HIGEAR handle. If the image is a DDB, use IG_dspl_DDB_import().


Displaying Images

ImageGear's family of over 40 display-related functions gives you complete control over where and with what attributes your application displays each of its images. Among the attributes you can set on an image-by-image basis are:

  • contrast adjustment
  • brightness adjustment
  • gamma correction
  • dithering
  • anti-aliasing enhancement
  • rotation
  • region within the display area the image is to be displayed (this area is called the Device rectangle)
  • the portion of the image to display (this array of pixels within the DIB bitmap is called the Image Rectangle)
  • how to fit the Image Rectangle to the Device Rectangle
  • the background fill pattern and color to use (for any area of the Device Rectangle left vacant by the image)

Also, by using the image's LUTs (Look Up Tables), you can cause the colors in the image's color palette to be translated to other colors you select (and therefore you can, for example, display an 8-bit grayscale image in any 256 colors you choose).

All of the above display attributes have their effects during display only. They do not alter either the image bitmap or the color palette in the DIB.

In addition, any time your image is currently being displayed, you can center, zoom, or scroll it from within your application.

How to do all of the above, and how to use additional special purpose IG_dspl_image_draw...() functions, is explained in the sections below which discuss basic concepts of displaying images.


Concepts

The key concepts of the new display functionality are display options, display option groups and display operations. A display option is a variable that is assigned a value (or a setting) from a predefined list. Every option has a default value associated with it, and therefore, is always defined.

The complete set of all options' values is an option group. An operation is an action such as displaying or printing an image. Every operation requires an option group whose identifier is passed as a parameter to the function that performs the operation. This group affects the result of the operation and the way in which it is achieved.


Understanding Storage Options

Every handle of an ImageGear image (HIGEAR) contains a set of option groups. ImageGear does not impose any restrictions on the size of this set, i.e. on the number of option groups that are stored with any given HIGEAR. Do not worry about allocating or de-allocating the storage space for the groups. You can, however, reset all group options to their default values.

Each option group has its own ID. This ID is a DWORD integer and is unique in the scope of a given HIGEAR, i.e. every pair {HIGEAR, DWORD} uniquely identifies an option group. The reason for introducing option groups and associating multiple groups with a single image handle is to provide a convenient means of drawing the same image on multiple devices. In this case, a separate option group may be allocated for each of the devices, and later used whenever the image is output to the corresponding device without a need for reassigning options values.


Understanding Display Options

In this section all the options are divided into several categories according to the type of the functionality they affect:

  • Geometric Layout
  • Dithering, Anti-aliasing, and Palette Handling
  • Transparency and Background
  • Lookup Tables and Gamma Correction
  • Grayscale Look Up Tables

Geometric Layout

The first category includes options that determine the image layout on the destination device:

ImageRect (AT_RECTANGLE)
A rectangle that defines the part of the image that is output to the device. It is expressed in image coordinates. By default, this option is set to the entire image.
ClipRect (AT_RECTANGLE)
A rectangle that identifies the destination device area that is affected by display operations. Display operations never affect parts of the destination device outside of the ClipRect. It is expressed by device coordinates and is initially assigned the entire client area of the destination device.
DeviceRect (AT_RECTANGLE)
A rectangle that identifies the area on the destination device upon which the image is projected. Only the portion of the projection falling within the clip rectangle will be seen. The rest of the clip rectangle may be painted with the background color depending on BkMode.
The image does not necessarily fit exactly into the device rectangle. The position of the image inside the device rectangle is determined by other options such as AspectMode, FitMode, and AlignMode (see their description below).
DisplayedImageRect (AT_RECTANGLE)
This is not a display option that you can set, however this is a very important concept discussed below. This is the rectangular area that represents the image's size and location on the device (and therefore, it is expressed in the device coordinates). It is important to understand that it is not related to the ClipRect, which represents the visible part of the image. The DisplayedImageRect's value can be calculated and used but cannot be directly set.
AspectMode (AT_MODE) and AspectValue (DOUBLE)
These options determine an image's aspect ratio (its width-to-height ratio). AspectMode can be assigned one of two possible values:
IG_DSPL_ASPECT_FIXED -- this aspect ratio is the one contained in AspectValue.
IG_DSPL_ASPECT_NOT_FIXED -- this aspect ratio is the one of the device rectangle.
AspectValue may be any positive number with the following meaning: AspectValue = (DisplayedImageRect.Width / DisplayedImageRect.Height) / (ImageRect.Width / ImageRect.Height). The default values for these options are IG_DISPL_ASPECT_FIXED and 1.0 respectively.
PPMCorrect (BOOL)
This option allows you to take into account the image's resolution when calculating the aspect ratio such that physical width and height are actually used for calculation. If this value is TRUE then ImageRect.Width and ImageRect.Height will be altered based on the horizontal and vertical resolution respectively. Default value is FALSE.
FitMode (AT_MODE)
This value defines how an image fits to the device rectangle while preserving its aspect ratio according to the AspectMode and AspectValue options. The possible values are:
IG_DSPL_FIT_TO_DEVICE - in this mode, the image is scaled to fit both the width and height of the device rectangle.
IG_DSPL_FIT_TO_WIDTH - in this mode, the image is scaled to fit the width of the device rectangle.
IG_DSPL_FIT_TO_HEIGHT - in this mode, the image is scaled to fit the height of the device rectangle.
IG_DSPL_ACTUAL_SIZE - in this mode, the device rectangle is ignored and the image is scaled 1:1.
The default value is IG_DSPL_FIT_TO_DEVICE.
AlignMode (AT_MODE)
This value defines how the displayed image is aligned relative to the device rectangle. Possible values are bitwise ORs of any two values such that one of them represents the horizontal alignment and the other represents the vertical alignment. The values representing the horizontal alignment are:
IG_DSPL_ALIGN_X_LEFT - the image is aligned to the left border of the device rectangle,
IG_DSPL_ALIGN_X_CENTER - the image is centered horizontally,
IG_DSPL_ALIGN_X_RIGHT - the image is aligned to the right border of the device rectangle.
The values representing the vertical alignment are:
IG_DSPL_ALIGN_Y_TOP - the image is aligned to the top border of the device rectangle,
IG_DSPL_ALIGN_Y_CENTER - the image is centered vertically,
IG_DSPL_ALIGN_Y_BOTTOM - the image is aligned to the bottom border of the device rectangle.
The default value is IG_DSPL_ALIGN_X_CENTER | IG_DSPL_ALIGN_Y_CENTER.
ZoomMode (AT_MODE)
The value that specifies how the image is zoomed in the horizontal and vertical directions. Possible values for this option are bitwise ORs of any two flags such that one of them represents a horizontal zoom value and the other represents a vertical zoom value. Flags representing the horizontal zoom values are:
IG_DSPL_ZOOM_H_NOT_FIXED - this mode allows any horizontal zoom value.
IG_DSPL_ZOOM_H_FIXED - in this mode the horizontal zoom factor is taken from ZoomValueH (see below for details).
IG_DSPL_ZOOM_V_NOT_FIXED - this mode allows any vertical zoom value.
IG_DSPL_ZOOM_V_FIXED - in this mode the horizontal zoom factor is taken from ZoomValueH (see below for details).
The default value for this option is IG_DSPL_ZOOM_H_NOT_FIXED | IG_DSPL_ZOOM_V_NOT_FIXED.
Please note that AspectMode takes precedence over ZoomMode. In other words, the vertical zoom values are ignored if AspectMode is set to IG_DSPL_ASPECT_FIXED.
ZoomValueH, ZoomValueV (DOUBLE)
These options specify actual horizontal and vertical zoom values according to ZoomMode. Their meaning may be expressed as follows:
ZoomValueH = DisplayedImageRect.width / ImageRect.width,
ZoomValueV = DisplayedImageRect.height / ImageRect.height.
Please note that ZoomValueV is not used if AspectMode is set to IG_DSPL_ASPECT_FIXED.
OrientMode (AT_MODE)
This parameter identifies how the image is oriented before it is drawn on the output device. Possible values are determined by the constants that have the form of IG_DSPL_ORIENT_X_Y, where each of X and Y can be LEFT, TOP, RIGHT or BOTTOM. X stands for the position where the topmost row of the bitmap will be located after applying the transformation and Y stands for the position where the leftmost column of the bitmap will be located after applying the transformation.
For example, IG_DSPL_ORIENT_RIGHT_TOP means that the left-most column will become the image's new topmost row and the topmost row will become the image's new rightmost column. The image will be rotated 90 degrees. The following constants are defined:
IG_DSPL_ORIENT_TOP_LEFT - the image is displayed unchanged
IG_DSPL_ORIENT_LEFT_TOP - the image is rotated 270 degrees and then flipped vertically
IG_DSPL_ORIENT_RIGHT_TOP - the image is rotated 90 degrees
IG_DSPL_ORIENT_TOP_RIGHT - the image is flipped horizontally
IG_DSPL_ORIENT_BOTTOM_RIGHT - the image is rotated 180 degrees
IG_DSPL_ORIENT_RIGHT_BOTTOM - the image is rotated 90 degrees and then flipped vertically
IG_DSPL_ORIENT_LEFT_BOTTOM - the image is rotated 270 degrees
IG_DSPL_ORIENT_BOTTOM_LEFT - the image is flipped vertically
The default value is IG_DSPL_ORIENT_TOP_LEFT.
Note that when changing an image's orientation, the image rectangle's orientation is also changed. The other rectangles and options remain unchanged.
ScrollbarMode (AT_MODE)
Scrolling is automatically supported in both horizontal and vertical directions. Scroll parameters are automatically calculated by ImageGear. All scroll parameters are stored apart from scrollbars, and therefore, the image can be scrolled in any possible way.
If you want to manage the scrollbars yourself, you may do so by using this option. Possible values for this option include any combination of two flags, such that one of them is a "horizontal" flag and the other is a "vertical" flag.
Horizontal flags are:
IG_DSPL_HSCROLLBAR_AUTO - allows ImageGear to show and hide the horizontal scrollbar depending on the scroll range.
IG_DSPL_HSCROLLBAR_ENABLE - in this mode, ImageGear always shows the horizontal scrollbar even if the scroll range is 0.
IG_DSPL_HSCROLLBAR_DISABLE - in this mode, ImageGear ignores the horizontal scrollbar and does not set any of its properties.
IG_DSPL_VSCROLLBAR_AUTO - allows ImageGear to show and hide the vertical scrollbar depending on the scroll range.
IG_DSPL_VSCROLLBAR_ENABLE - in this mode, ImageGear always shows the vertical scrollbar even if the scroll range is 0.
IG_DSPL_VSCROLLBAR_DISABLE - in this mode, ImageGear ignores the vertical scrollbar and does not set any of its properties.
ScrollPosH, ScrollPosV
(LONG)
These options determine how DisplayedImageRect is moved in the horizontal and vertical directions. These values should fall within the corresponding scroll range. Both are set to 0 by default.
MapMode (DWORD),
Viewport (AT_RECTANGLE),
Window (AT_RECTANGLE)
These options are device dependent and allow you to set logical coordinates. It is assumed by ImageGear that all coordinates except ImageRect are logical. These options are necessary to properly convert logical to device coordinates.
For the Windows platform the value of MapMode can be any value accepted by the GDI's functions GetMapMode/SetMapMode. The Viewport and Window contain values that are the same as GDI's SetViewportOrgEx/SetViewportExtEx and SetWindowOrgEx/SetWindowExtEx.
The default value is the same as current desktop map mode.

This figure demonstrates the meaning of the rectangles listed above:

Some of the options listed above conflict unless priorities are defined. Consider the general algorithm of display rendering. It consists of several steps, and on each step ImageGear processes some options to introduce modifications to the resulting image.

  • ImageRect is oriented according to OrientMode. ClipRect and DeviceRect are calculated according to their definitions above.
  • If FitMode is set to IG_DSPL_ACTUAL_SIZE then DisplayedImageRect.width and DisplayImageRect.height are set to ImageRect.width and ImageRect.height respectively. Otherwise, DisplayedImageRect is computed using DeviceRect.
  • According to ZoomMode, ZoomValueH and ZoomValueV, DisplayedImageRect.width and DisplayedImageRect.height are modified as follows:
if( (ZoomMode&IG_DSPL_ZOOM_H_FIXED) != 0 )
    DisplayedImageRect.width =
DisplayedImageRect.width*ZoomValueH,

and

if( (ZoomMode&IG_DSPL_ZOOM_V_FIXED) != 0 )
    DisplayedImageRect.height =
DisplayedImageRect.height*ZoomValueV.

If AspectMode is set to IG_DSPL_ASPECT_FIXED, then ZoomValueV is not used and the above procedure is changed in the following way:

If( (ZoomMode&IG_DSPL_ZOOM_H_FIXED) != 0 )
{
DisplayedImageRect.width = DisplayedImageRect.width*ZoomValueH,
DisplayedImageRect.height =
DisplayedImageRect.height*ZoomValueH.
}
  • DisplayedImageRect.x and DisplayedImageRect.y are computed so that DisplayedImageRect is aligned as specified by AlignMode.
  • The scrolling range is calculated so that DisplayedImageRect can be viewed inside of ClipRect. Then DisplayedImageRect.x and DisplayedImageRect.y are shifted according to the current scroll position.

Dithering, Anti-aliasing, and Palette Handling

ImageGear supports automatic dithering of source images. This functionality is affected by the following options:

DitherMode (AT_MODE)
Can be assigned the following values:
IG_DSPL_DITHER_AUTO
Specifies that the destination device color resolution should be used for dithering. In this mode IG automatically applies dithering only when it is necessary.
IG_DSPL_DITHER_TO_8BPP
This mode forces ImageGear to assume that the output device is 8 bits per pixel and perform the necessary dithering.
IG_DSPL_DITHER_TO_4BPP
This mode forces ImageGear to assume that the output device is 4 bits per pixel and perform the necessary dithering.
IG_DSPL_DITHER_TO_1BPP
This mode forces ImageGear to assume that the output device is 1 bit per pixel and perform the necessary dithering.
IG_DSPL_DITHER_NONE
Disables ImageGear's dithering. In this mode dithering is performed by the operating system or the device driver.

The following flags can be used with any of the above modes:

IG_DSPL_DITHER_FIXED_
PALETTE
If this flag is set, ImageGear will try to use the standard palette when performing dithering. This may be useful if the output device contains more than one image and by using this flag it is possible to draw images with the same palette.
PALETTE
This flag is applicable only if the output device is 8 bits per pixel. It tells ImageGear to use the 216 entries Netscape palette.
The default value for DitherMode is IG_DSPL_DITHER_AUTO. Currently only ordered dithering is implemented.
IG_DSPL_ANTIALIAS_MODE (AT_MODE)
A bitmask used to isolate black and white antialiasing modes:
  • IG_DSPL_ANTIALIAS_NONE - anti-aliasing is not used.
  • IG_DSPL_ANTIALIAS_SCALE_TO_GRAY - the scale to gray algorithm is used and the output image becomes 4 bits per pixel
  • IG_DSPL_ANTIALIAS_PRESERVE_BLACK - this mode means ImageGear will try to preserve black pixels while scaling.
  • IG_DSPL_ANTIALIAS_PRESERVE_WHITE - This mode means ImageGear will try to preserve white pixels while scaling.
Together with these modes the following flag can be used:
  • IG_DSPL_ANTIALIAS_SUBSAMPLE - specifies ImageGear to use sub-sampling during anti-alias scaling. The output is as good but the speed is greater.
IG_DSPL_ANTIALIAS_RESAMPLE_MODE
A bitmask used to isolate resampling modes:
  • IG_DSPL_ANTIALIAS_RESAMPLE_BILINE - resample with bilinear interpolation
IG_DSPL_ANTIALIAS_COLOR_MASK
A bitmask used to isolate color antialiasing modes:
  • IG_DSPL_ANTIALIAS_COLOR - color antialiasing
AliasThreshold (UINT)
Threshold integer value from 0 to 100. Its meaning depends on the AliasMode value
If AliasMode is set to IG_DSPL_ANTIALIAS_SCALE_TO_GRAY then AliasThreshold determines how many black and white pixels are involved in the destination gray pixel value. Value 100 causes ImageGear to take 100% white pixels, value 0 causes ImageGear to take 100% of black pixels, and the default value is 50 which means 50% of white and 50% of black pixels.
If AliasMode is set to IG_DSPL_ANTIALIAS_PRESERVE_BLACK, then AliasThreshold determines how many black pixels should be preserved. Value 100 means that 100% of black pixels are preserved. The default value is 50.
If AliasMode is set to IG_DSPL_ANTIALIAS_PRESERVE_WHITE, then AliasThreshold determines how many white pixels should be preserved. Value 100 means that 100% of white pixels are preserved. The default value is 50.
DevicePalette (HPALETTE)
This option is a palette in OS-dependent format. This palette is implemented before drawing pixels onto the output device. By default, this option is NULL, which means that it is created every time; either from the logical palette of the image, or from the logical palette used in dithering.
If this option is not NULL then it should be a valid palette handle. ImageGear does not perform logical processing of the specified palette; it only implements it before drawing. Incorrect usage of this option may distort the image on the destination device.
PaletteMode (AT_MODE)
This option specifies how to use the DevicePalette option when the destination device does support palette operations. Possible values are:
IG_DSPL_PALETTE_HIGH - tells ImageGear to use the palette in the high priority mode. This means that the operating system palette manager will try to best map colors of DevicePalette to the system palette.
IG_DSPL_PALETTE_LOW - tells ImageGear to use the palette in the low priority mode. In this mode the palette manager will try to best preserve current view of the destination while drawing the new image on it.
IG_DSPL_PALETTE_DISABLE - tells ImageGear not to implement DevicePalette in the destination device while drawing the image.

Transparency and Background

ImageGear display functionality supports transparency by color and by mask. The former means that it is possible to draw images with the specified color being transparent. The latter allows providing a one bit per pixel image and using it as the transparent mask. There are a few options related to transparency and background support:

TranspMode (AT_MODE)
Option that contains transparency flags. If its value is IG_DSPL_TRANSPARENCY_NONE then transparency is disabled.
Each of the next flags enables some transparency-related features:
IG_DSPL_TRANSPARENCY_COLOR
If this flag is set then the transparent color is enabled and the color's value that is assigned to the TranspColor option is used as transparent while drawing the image.
IG_DSPL_TRANSPARENCY_MASK
If this flag is set then the transparency mask is enabled and the TranspMask option is used as the transparent bitmap.
IG_DSPL_TRANSPMASK_
STRETCH_TO_IMAGE
This flag is used when the transparency mask is enabled. If this flag is set then the TranspMask image is resized and oriented along with the image being displayed. In other words, if during display operation the image is scaled by factors DX and DY in the horizontal and vertical directions respectively, then the TranspMask image is scaled by the same factors. If this flag is not set then the transparency mask is not scaled. This flag is ignored unless the IG_DSPL_TRANSPMASK_LOCATE_TO_IMAGE flag is set.
The next three flags are exclusive so that only one of them can be set at a time:
IG_DSPL_TRANSPMASK_
LOCATE_TO_IMAGE
This flag is applicable if the transparency mask is enabled. If this flag is set then the mask is calculated in the image-dependent coordinate system. This means that the mask is oriented as the image is and the MaskLocation option is calculated from the original image's ImageRect. If this flag is not set then the IG_DSPL_TRANSPMASK_STRETCH_TO_IMAGE flag is ignored.
IG_DSPL_TRANSPMASK_
LOCATE_TO_CLIPRECT
This flag locates the transparent mask relative to the ClipRect, so that the MaskLocation is calculated from this rectangle's left top point.
IG_DSPL_TRANSPMASK_
LOCATE_ABSOLUTE
This flag locates the transparent mask on the output device so that the mask's left top point of has the coordinates specified in the MaskLocation option.
The default value for TranspMode option is IG_DSPL_TRANSPARENCY_NONE which means that transparency is disabled.
TranspColor (AT_RGB)
This (RGB) triple specifies the transparent color and it is used if the IG_DSPL_TRANSPARENCY_COLOR flag is set in TranspMode (see its description above). If the transparent color is enabled, then all the pixels in the image that have values equal to TranspColor are drawn as transparent.
TranspMask (HIGEAR)
This option specifies the transparency mask and it is used if the IG_DSPL_TRANSPARENCY_MASK flag is set (see the TranspMode's description above). This is a normal HIGEAR image, and its location on the screen depends on other flags described above and the MaskLocation option. The application code is responsible for creating and deleting this mask.
MaskRect (AT_RECTANGLE)
This rectangle specifies which part of the TranspMask image should be used as the transparency mask. It is an analog of the original image's ImageRect but it applies to the TranspMask image. By default, it is initialized with the empty rectangle, which means the complete TranspMask image will be used.
MaskLocation (AT_POINT)
This option specifies how the transparency mask is located relative to either the image or the device d epending on the flags set in TranspMode.
BkMode (AT_MODE)
This option specifies how ImageGear should fill the area of ClientRect that is not covered by the image's pixels. If its value is IG_DSPL_BACKGROUND_NONE then the background is disabled and IG does not fill this area. Other possible values are as follows:
IG_DSPL_BACKGROUND_UNDER_IMAGE - if this flag is set, then the image's transparent pixels are drawn with current BkColor and BkBrush (see their description below). The area outside of DisplayedImageRect is not affected.
IG_DSPL_BACKGROUND_BEYOND_IMAGE - if this flag is set, then the transparent pixels that are outside of DisplayedImageRect are drawn with current BkColor and BkBrush (see their description below).
The default value for this option is IG_DSPL_BACKGROUND_UNDER_IMAGE| IG_DSPL_BACKGROUND_BEYOND_IMAGE.
BkColor (AT_RGB)
This option is a (RGB) triple that specifies the background color. This color is used to fill the area of ClipRect that is not covered by the image's pixels.
BkBrush (HBITMAP)
This option is the handle of the bitmap that stores the brush to be used. The application code is responsible for creating and deleting this brush.

Lookup Tables and Gamma Correction

ImageGear supports gamma correction preprocessing before the image is drawn onto the destination device. This operation does not affect the image itself but only changes its appearance.

There are three options that allow the controlling of the gamma correction

  • RedLut (LPBYTE) - this is a 256-entry array of bytes that contains a new value for each of the possible 256 intensities of the red color.
  • GreenLut (LPBYTE) - this is a 256-entry array of bytes that contains a new value for each of the possible 256 intensities of the green color.
  • BlueLut (LPBYTE) - this is a 256-entry array of bytes that contains a new values for each of the possible 256 intensities of the blue color.

Each of the three option's default value is the identity array.

NOTE: If the source image is not in the RGB color space then it is first converted to the RGB color space and then all the lookup tables are applied.

There are high level options, which automatically create all necessary lookup tables.

  • Contrast, Brightness, Gamma (DOUBLE) - these three options are actually parameters which specify how to calculate the lookup tables to get the necessary color effects.
  • Parameter Contrast specifies the contrast level to produce. Values greater then 1.0 increase contrast, values less than 1.0 decrease contrast. Values less than 0.0 will invert contrast (exchange dark and light).
  • Parameter Brightness specifies the brightness adjustment. Possible values range from -255.0 to +255.0.
  • Parameter Gamma controls the non-linear contrast adjustment. Values greater then 1.0 increase contrast, values less than 1.0 decrease it. Usual range is from 1.8 to 2.2

The default values are:

    • Contrast = 0.0,
    • Brightness = 1.0,
    • Gamma = 1.0

Grayscale Look Up Tables

The ImageGear display API allows storing a grayscale (single-channel) look up table with an image's display settings. The grayscale look-up table can be set for any image, but ImageGear only uses it with 8...16-bit grayscale images, and ignores it with the other images. This look up table specifies a transform from 16-bit image to 8-bit image, which allows to display a particular part of 8...16-bit image's contrast range, or enhance image's contrast.

A grayscale LUT can be stored with a 16g image as well. However, if both the image and its display contain LUTs, the display LUT overrides the image's LUT. A LUT can be removed from an image and attached to a display, or vice versa.

Storing a grayscale LUT with display settings allows you to display the same image with different LUTs simultaneously, in different windows.

A grayscale LUT can be used in combination with a RGB LUT. The grayscale LUT is applied first, and then the RGB LUT is applied.

Use IG_dspl_grayscale_LUT_update_from () to create or update a grayscale LUT with the specified LUT. LUT data will be copied to the display settings. Set the lut parameter to NULL to remove grayscale LUT from display settings.

Use IG_dspl_grayscale_LUT_exists () to check whether display settings contain a grayscale LUT.

Use IG_dspl_grayscale_LUT_copy_get () to obtain a copy of the display grayscale LUT.

The ImageGear Medical component provides a set of API functions that allow building grayscale LUTs according to various DICOM display settings.

The only allowed LUT configuration for display is: InputDepth = 16, OutputDepth = 8, Output is unsigned. Such LUTs can be used with grayscale images which depth is 8... 16 bits per pixel.

See Also:

Working with Grayscale Look Up Tables

Medical Component Grayscale Look Up Tables


Image Processing

ImageGear's comprehensive family of image processing functions permits you to perform both simple and complex image-modifying operations using a single function call. Image alterations such as contrast enhancement, sharpness adjustment, color reduction/promotion, image merging ("blending"), and "special effects" are performed using the functions in this group.

NOTE: Image processing functions are always named beginning with IG_IP_ ...() or IG_FX_ ...(). Be careful not to confuse these functions with IG_dspl_image_draw ...()functions designed to perform similar operations during displaying images. The IG_dspl_image_draw ...() functions affect only how the image will be displayed. The image processing functions actually alter the pixel data in the DIB image bitmap, or the DIB palette, or both.

Many image processing functions permit you to specify a rectangular region within your image, limiting the function's operation to that region. In such cases, the address of an AT_RECT structure is supplied as an argument. (Specify this argument as NULL to operate on the whole image.)

NOTE: The "image rectangle" setting made by calls to function IG_dspl_layout_set() is not used by the image processing functions.

In this section, ImageGear's image processing functions are grouped as shown below. You may want to refer to the individual discussions of the groups as they become pertinent to your application's development needs.

  • Area Detection and Processing
  • Color Reduction
  • Color Promotion
  • Contrast Alteration
  • Image Transformation
  • Image Analysis
  • Red-Eye Removal
  • Region of Interest Processing
  • Special Effects
  • Blending and Combining Images
  • Image Correction
  • Image Maintenance
  • Mathematical Morphology

If you encounter an occasional image processing term that you are not familiar with, be sure to refer to the comprehensive "Glossary" . Also, refer to the functions entries in "Core Component API Function Reference" for the detailed calling sequences and additional information and examples. In a function's entry, be sure to check the "Bits Per Pixel" line. It tells which of bit depths may be processed using that function. The descriptions of the different bit depths (1, 4, 8i, 8-bit gray level, 9-16-bit gray level, 24, and 32) and how they are stored internally in the DIB image bitmap in memory, can be found in "Understanding Bitmap Images".

NOTE: A number of image processing functions can process 8-bit gray level and 24-bit images, but cannot process 8i (8-bit indexed color) images. This is because in 8i images the pixel value does not itself describe the pixel (its color or its intensity), but is merely an index into the palette. If you want to call such a function for an 8i image, first promote the image to 24-bit using function IG_IP_color_promote().
NOTE: The following types of image processing can be performed on an image that is loaded with its CMYK data intact (not translated to RGB): IG_IP_crop(), IG_IP_flip(), IG_IP_resize(), IG_IP_rotate_multiple_90(), IG_IP_rotate_any_angle(), IG_IP_contrast_invert(), IG_IP_contrast_stretch(), and IG_IP_contrast_equalize(). The rest of image processing API can be used after conversion of CMYK image to RGB format.


Area Detection and Processing

Area detection functions allow you to detect an area in the image, using a predefined or custom pixel checking method.

See also Red-Eye Removal group.

IG_IP_detect_area ()
Detects an area of pixels using a user-defined pixel checker.
IG_IP_detect_area_with_threshold ()
Detects an area of pixels using a specified threshold.
IG_IP_process_area
Processes all pixels in the ROI area using a specified pixel processor.


Color Reduction

Color reduction in general results in an image with fewer colors than the original, even if the bit depth is not changed. There are a number of color reduction methods and ImageGear provides you with several different functions from which you can choose the one that is most suitable in a given case. Below you can see the color reduction methods that are available, and the functions that perform them:

IG_IP_color_reduce_bayer ()
Reduces a 4, 8, or 24-bit image to a 4-bit image using a Bayer dithering algorithm.
IG_IP_color_reduce_to_bitonal ()
Reduces a 4, 8, or 24-bit image to a 1-bit or "bitonal" image.
IG_IP_color_reduce_median_cut ()
Reduces a 24-bit image to 8 bits using the median cut algorithm.
IG_IP_color_reduce_diffuse ()
Reduces a 4, 8, or 24-bit image to a 1-bit or 4-bit image using a diffusion algorithm.
IG_IP_color_reduce_popularity ()
Reduces a 24-bit image to an 8-bit image, while preserving its most prevalent or popular colors.
IG_IP_color_reduce_octree ()
Reduces a 24-bit or 8-bit image to an 8-bit or 4-bit image. Uses an efficient algorithm that gives a result as near the original as possible, using the number of colors you specify.
IG_IP_color_reduce_halftone ()
Reduces a 4, 8, or 24-bit image to a 1-bit image using a halftone pattern.

Refer to the function descriptions in Core Component API Function Reference for the calling sequences and further information on the above.

The additional function IG_IP_convert_to_gray () is also considered a color reduction function. It is called as follows:

IG_IP_convert_to_gray ( hIGear );

It always converts the image to 8-bit gray level. The resulting DIB has a 256-entry palette, and each 8-bit pixel value in the resulting image bitmap is a weighted average of the three color intensities of the pixel in the original image.


Color Promotion

Color promotion is the process of increasing the bit depth, or number of bits per pixel, of an image. The color of each pixel is retained. ImageGear provides one function that handles promotion to any bit depth. It is called as follows:

IG_IP_color_promote ( hIGear, IG_PROMOTE_TO_24 );

The constant shown in the example above may instead be IG_PROMOTE_TO_4 or IG_PROMOTE_TO_8. Your image must of course originally have fewer bits per pixel than the bit depth to which you are promoting it.

When promoting to 4 or 8 bits, the promotion is accomplished by simply increasing the number of bits per pixel for each pixel (but without changing the pixel's value), and increasing the size of the DIB palette (the added palette entries are set to all zeroes).

Function name
Bpp
In
Use or create palette for output image
BppOut
IG_IP_color_reduce_bayer ()
24
use standard B/W palette
1
8
use standard B/W palette
1
4
use standard B/W palette
1
24
use given palette
4
8
use given palette
4
24
use standard palette
4
8
use standard palette
4
IG_IP_color_reduce_diffuse ()
24
use standard B/W palette
1
8
use standard B/W palette
1
4
use standard B/W palette
1
24
use given palette
4
8
use given palette
4
24
use standard palette
4
8
use standard palette
4
IG_IP_color_reduce_halftone ()
24
use standard B/W palette
1
8
use standard B/W palette
1
4
use standard B/W palette
1
IG_IP_color_reduce_median_cut ()
24
create optimal palette
8
IG_IP_color_reduce_octree ()
24
use given palette (maxcolors > 16)
8
8
use given palette (maxcolors > 16)
8
24
create optimal palette (maxcolors > 16)
8
8
create optimal palette (maxcolors > 16)
8
24
use given palette (maxcolors <= 16)
4
8
use given palette (maxcolors <= 16)
4
24
create optimal palette (maxcolors <= 16)
4
8
create optimal palette (maxcolors <= 16)
4
IG_IP_color_reduce_popularity ()
24
create optimal palette
8
IG_IP_color_reduce_to_bitonal ()
24
use standard B/W palette
1
8
use standard B/W palette
1
4
use standard B/W palette
1

When promoting to 24 bits, the 24-bit color of the pixel (obtained from the image's original palette) becomes the 24-bit pixel in the resulting promoted image. The DIB palette is deleted, since a 24-bit image does not have a DIB palette.

NOTE: The function IG_IP_convert_to_gray(), though it could increase the number of bits per pixel in an image, is considered a color reduction function, because it reduces the colors to shades of gray.


Contrast Alteration

ImageGear's contrast alteration functions operate by altering the range of pixel intensities that occur in your image, or by redistributing the occurrence frequency of the pixel intensities. There are five IG_IP_contrast_...() functions, which operate as follows:

IG_IP_contrast_adjust ()
Adjusts the contrast of the image by stretching or compressing the range of intensities that occur. Also adjusts brightness, by adding or subtracting a constant you specify, to each intensity value.
IG_IP_contrast_stretch ()
Adjusts the contrast of the image by stretching the range of intensities that occur, such that the least intense pixel becomes full black and the most intense becomes full white.
IG_IP_contrast_equalize ()
Adjusts the contrast of the image by stretching or compressing sub-ranges of intensities that occur, so that there are an approximately equal number of pixels in each sub-range. This can bring out subtle changes in contrast when contrast is poor in the original, such as in x-ray images.
IG_IP_contrast_gamma ()
Adjusts the contrast of the image non-linearly, using an algorithm that tends to correct for the non-linear response of display monitor phosphors, video camera photoreceptors, and photographic emulsions.
IG_IP_contrast_invert ()
Inverts each pixel intensity or color, resulting in an image that is a "negative" of the original.

Each of the above functions can operate on any specified rectangular portion of your image. However, when operating on a whole image, each function above can achieve its effect by altering the image's palette instead of by altering its pixel values. An example of a call to an IG_IP_contrast_ ...() function is:

HIGEAR hIGear; /* HIGEAR handle of image */
AT_RECT rcRect; /* rectangle to operate on */
IG_IP_contrast_equalize ( hIGear, &rcRect, IG_CONTRAST_PIXEL);

If you specify IG_CONTRAST_PALETTE instead of IG_CONTRAST_PIXEL, note that your rectangle argument will be ignored, and the operation will be performed on the whole image.

Several additional functions help you to highlight contrast boundaries:

IG_IP_edge_map ()
Produces a resultant image that shows where there are contrast changes in the original image. An area in which there are no contrast changes is black in the resultant image; the stronger the contrast change, the brighter the result. The result tends to have bright lines where there are sharp contrast changes.
IG_IP_pseudocolor_small_grads ()
Colors an 8-bit gray level image according to the local rate of p ixel value change. This can be set to expose even very small gradients in brightness.
IG_IP_pseudocolor_limits ()
Allows you to block out, to a single color, all pixels below (or above) a given pixel value. This can be used to highlight the portion of an image that is relevant (then IG_IP_contrast_stretch () might be called to enhance its contrast), or may be used to see what portions of the image are saturated or unsaturated.

Refer to the descriptions of all of the above in "Core Component API Function Reference".


Image Transformation

An image transformation function is one in which a mathematical algorithm is applied to transform each pixel to a new location or value. Rotation is a good example of a simple image transformation. Image transformation differs from contrast adjustment (which might also be carried out by applying an algorithm) in that the contrast adjustment is trying to achieve some visual improvement or enhancement of the image. A transformation's object is simply to achieve the transformation (e.g., rotate the image).

ImageGear provides the following image transformation functions. Refer to the description of each in "Core Component API Function Reference" for detailed calling sequences as well as other related information:

IG_IP_transform_with_LUT ()
Transforms an image by mapping each pixel value through a Look Up Table that you supply to obtain the pixel's new value.
IG_IP_convolve_matrix ()
Convolves the 8-bit gray level or 24-bit image using a user-defined convolution kernel.
IG_IP_rotate_multiple_90 ()
Rotates your image 90, 180, or 270 degrees around its center.
IG_IP_rotate_any_angle ()
Rotates your image through any angle you specify around its center.
IG_IP_sharpen ()
Causes the dark side of a contrast boundary to become darker and the bright side to become brighter. This makes the image appear sharper. You can control the degree of sharpening applied.
IG_IP_smooth ()
Removes graininess in an image, tending to soften or smooth its appearance. You control the degree of smoothing.
IG_IP_flip ()
Flips your image right-for-left or top-for-bottom. This is equivalent to rotating the image about a vertical or horizontal axis (respectively) drawn through its center.
IG_IP_resize ()
Re-scales the image, changing the size of the image bitmap.


Image Analysis

This section describes the following:

  • Histogram
  • Color counting

Histogram

ImageGear provides a histogram-generating function (and a related function to clear histogram bins) to assist you in image analysis. For an 8-bit image, whether 8i or 8-bit gray level, these functions can be called as follows:

HIGEAR hIGear; /* HIGEAR handle of image */
DWORD dwHistoBins[256]; /* Array of bins for counting */
IG_IP_histo_clear ( &dwHistoBins, 256 ); /* Clear the bins */
IG_IP_histo_tabulate (hIGear, &dwHistoBins, 256, NULL, 1, 0 );
/* Tabulate: */

In the above call, 256 DWORD bins are provided (one for each possible pixel value that can occur). The function will examine each pixel in the image bitmap, and will increment the bin corresponding to that value. (That is, the bin dwHistoBins[pixel value] will be incremented.) Upon return, you will have a count of the number of occurrences of each pixel value.

The fourth argument in the above call lets you specify the address of a rectangular region, if you want to restrict the tabulating to include only a portion of the image. When NULL, the whole image is included in the tabulation.

The fifth argument above can be set larger than 1, if you want to increase the speed of the tabulation for a large image. 1 means that every raster line of pixels will be included in the tabulation. A larger value would result in raster lines being skipped.

The final argument in a call to IG_IP_histo_tabulate () is relevant for 24-bit images only. Its use is shown in the following example:

HIGEAR hIGear; /* Handle of a 24-bit image */
DWORD dwHistoBins[256]; /* Array of bins for counting */
IG_IP_histo_clear ( &dwHistoBins, 256 );/* Clear the bins */
IG_IP_histo_tabulate (hIGear, &dwHistoBins, 256, NULL, 1,
IG_COLOR_COMP_R ); /* Tabulate:   */

For 24-bit images, only 1 color channel is tabulated by a given call. That is, only 1 byte of each 3-byte pixel is examined. The final argument tells which byte (Blue, Green, or Red) should be tabulated.

You can also call IG_IP_histo_tabulate () for 1-bit and 4-bit images. In these cases, the number of DWORD histogram bins you need would be 2 and 16 respectively. In any event, always remember to call IG_IP_histo_clear () before calling IG_IP_histo_tabulate(), unless it is your intention to accumulate the count into the existing contents of your bins.

Color counting

The IG_IP_color_count_get () function counts the number of different colors in the specified rectangle of an image.


Red-Eye Removal

Red-eye removal removes the "red eye" effect in color images by converting the red color in the eye to the new specified color. ImageGear's Red-Eye Removal works by detecting an area around a specified point where the colors correspond to the point color with the specified threshold. This detected area is saved as a Region of Interest (ROI) of the hIGear. Red eye is then removed for every point in the ROI of a hIGear. It is designed only for red eye removal, not other colors (as may occur with animal eyes).

The IG_IP_detect_redeye_area detects an area around specified point where the colors correspond to the point color with the specified threshold. The detected area is returned as a ROI.

For example, the color of the specified point is:

Red == 212;

Green == 96;

Blue == 128;

And threshold is 10.

The method detects a closed polygon around the specified point in which the color components belong to the range.

Red - 202.. 222;

Green - 86..106

Blue - 118.. 138

The IG_IP_remove_redeye removes red eye for every point in the ROI of a hIGear image. It is designed only for red eye removal, not other colors (as occurs with animal eyes). First, the red component must be reduced to be around the same level of the green and blue components. Then, all three components must be reduced. The following are some examples of corrected color values:

210,39,71 -> 25,23,26

186,77,82 -> 64,54,53

236,95,101 -> 80,80,78


Region of Interest Processing

This group of functions allows you to apply image processing and special effects functions on an arbitrary region of interest (ROI). You can specify a shape, such as ellipse, polygon or freehand, or a 1 bit mask for identifying which pixels to include/disclude from image processing algorithms.

To apply an image processing function on a non-rectangular ROI, create the ROI using IG_IP_NR_ROI_to_HIGEAR_mask (), or use a 1-bit image, and associate it with the HIGEAR handle on which you are going to apply the processing function, using IG_IP_NR_ROI_mask_associate (). Consequent calls to image processing functions on this image will only affect the area specified by the ROI.

IG_IP_NR_ROI_control_get ()
Returns the current ROI control settings.
IG_IP_NR_ROI_control_set ()
Detects an area of pixels using a specified threshold.
IG_IP_NR_ROI_mask_associate()
Associates a mask HIGEAR, as specified by the AT_NR_ROI_MASK structure, with the image referenced by hIGear.
IG_IP_NR_ROI_mask_delete()
Deletes the mask HIGEAR created by IG_IP_NR_ROI_to_HIGEAR_mask().
IG_IP_NR_ROI_mask_dilate()
Dilates ROI mask by the specified number of pixels.
IG_IP_NR_ROI_mask_erode()
Erodes ROI mask by the specified number of pixels.
IG_IP_NR_ROI_mask_unassociate()
Removes the non-rectangular ROI information from a HIGEAR image, but does not delete the mask HIGEAR.
IG_IP_NR_ROI_to_HIGEAR_mask()
Builds a non-rectangular ROI mask from a set of segment descriptors that you pass in.


Special Effects

Special effects are a group of image processing functions that distort the image in some way, but still allows the image to be viewed, but with reduced clarity. ImageGear's special effects image processing functions (note that their names begin with IG_FX_ ...) include:

IG_FX_aging()
Applies an aging effect to make an image look older. See Aging for more information.
IG_FX_blur()
Makes your image appear blurred. See also IG_FX_motion ().
IG_FX_chroma_key()
Blends two images. See the section entitled Blending and Combining Images later in this document.
IG_FX_cylinder()
Provides the effect of warping around a cylinder. See Warp Effects for more information.
IG_FX_diffuse()
Diffuses your image by locally shuffling the positions of pixels.
IG_FX_directional_light()
Changes the colors of an image according to the pattern of a sine wave. See Functional Lights for more information.
IG_FX_directional_wave()
Applies a directional wave effect. See Ripple Effects for more information.
IG_IP_drop_shadow()
Adds a drop shadow to an image. See Borders and Shadows for more information.
IG_FX_emboss()
Gives a 3-D chiseled-in-stone-like look to an image, similar to the appearance of the face on an engraved coin.
IG_FX_fragment()
Fragments an image into four blended images which move diagonally outward from the original image. See Fragmentation for more information.
IG_FX_free_directional_light()
Changes the colors of an image according to the pattern of a sine wave. See Functional Lights for more information.
IG_FX_free_radial_light()
Changes the colors of an image according to the pattern of a sine wave. See Functional Lights for more information.
IG_FX_lens_flare()
Applies a lens flare effect to the image. See Lens Flare for more information.
IG_FX_mosaic_tiles
Provides a 3D mosaic effect on the hIGear image. See Mosaic Effects for more information.
IG_FX_motion()
Makes your image appear as if it was moving when the image was captured. You can specify the direction of the apparent motion.
IG_FX_noise()
Adds noise to an image (by altering some pixel values). This tends to make the image look old or worn.
IG_FX_oilify()
Applies an effect to an image that makes it appear similar to an oil painting. See Artistic Effects for more information.
IG_FX_parabola()
Provides the effect of warping around a paraboloid. See Warp Effects for more information.
IG_FX_perspective
Provides a perspective-like effect by placing image corners to the specified points, and stretching the image linearly between them. See Perspective Effect for more information.
IG_FX_pinch
Pinches an image toward or away from the pinch center. See Pinch Effect for more information.
IG_FX_pixelate()
Gives groups of pixels identical values, effectively reducing the resolution of the image. Can make it appear that you have zoomed in on a smaller image. See Mosaic Effects for more information.
IG_FX_pointillist()
Applies an effect to an image that makes it appear to have been painted in the pointillism style of painting. See Artistic Effects for more information.
IG_FX_posterize()
Reduces the number of colors in the image by making groups of adjacent palette colors identical in the palette.
IG_FX_radial_light
Changes the colors of an image according to the pattern of a sine wave. See Functional Lights for more information.
IG_FX_radial_wave
Warps the image in concentric rings. See Ripple Effects for more information.
IG_FX_shear()
Applies a shearing effect to an image, moving the image rasters or columns according to the specified offsets. See Shear for more information.
IG_FX_solarize
The effect mimics the accidental exposure of photographic film to light. See Solarize Effect for more information.
IG_FX_spatter()
Applies a spatter effect to an image, making it look as if it was painted in the impressionist style of painting. See Artistic Effects for more information.
IG_FX_sphere()
Provides the effect of warping around a sphere. See Warp Effects for more information.
IG_FX_spotlight()
Creates a "spotlight" effect by darkening pixels outside the circular area you specify.
IG_FX_stitch()
Provides an effect similar to IG_FX_emboss () above, except the output more closely resembles a quilted stitch pattern.
IG_FX_texture()
Gives your image a textured look by applying changes to neighborhoods of pixels according to the pixel values in a small texturing image that you provide.
IG_FX_twist()
Makes your image appear as if it is being viewed through a shower curtain by rotating neighborhoods of pixels.
IG_FX_watermark()
Superimposes a watermark that you provide onto your image.

Each of the above functions is called similarly: with the HIGEAR handle of the image, a specification of where to apply the effect, and an additional argument or arguments as needed for you to specify the degree of the effect, direction, or other control.

Refer to Core Component API Function Reference for additional details on each of these special effect functions. Some of the functions are also discussed in the following sections.

Aging

The IG_FX_aging function applies an aging effect to make an image look older. The effect can adjust image saturation and contrast, and add noise and random vertical lines to the image.

Original

Aging Effect

Artistic Effects

ImageGear artistic effects make the image appear to have been hand-painted.

The IG_FX_oilify function makes the image appear similar to an oil painting.

The IG_FX_pointillist function makes the image appear to have been painted in the pointillism style of painting. This effect is also known as Dot Mosaic.

The IG_FX_spatter function applies a spatter effect to an image, making it look to have been painted in the impressionist style of painting.

Original

Oilify Effect

Spatter Effect

Pointillist Effect

Borders and Shadows

The IG_IP_drop_shadow function adds a drop shadow to an image. The image is enlarged to contain a background and shadowed area.

Original

Drop Shadow Effect

Fragmentation

The IG_FX_fragment function fragments an image into four blended images which move diagonally outward from the original image.

Original

Fragmentation effect

Functional Lights

Functional Lights functions change the colors of an image according to the pattern of a sine wave, or an application defined pattern. The image will appear to have circles or bars of light and/or shadow overlaid on top of it.

The IG_FX_directional_light function adds bars of light according to a sine wave pattern.

The IG_FX_radial_light function adds circles of light according to a sine wave pattern.

The IG_FX_free_directional_light function adds bars of light according to a custom pattern.

The IG_FX_free_radial_light function adds circles of light according to a custom pattern.

Original

Directional Light

Radial Light

Free Directional Light

Lens Flare

The IG_FX_lens_flare function applies a lens flare effect to the image. The effect simulates a bright light, such as the sun, and some reflections within the lens. It is typically used to add a sense of drama or realism to a photographic image.

Original

Lens Flare Effect

Mosaic Effects

ImageGear provides the following mosaic effects:

  • IG_FX_pixelate function gives groups of pixels identical values, and optionally adds borders between these groups. The groups can have the shape of rectangle, rounded rectangle or ellipse. This transform effectively reduces the resolution of the image. Can make it appear that you have zoomed in on a smaller image.
  • IG_FX_mosaic_tiles creates a mosaic effect by dividing a bitmap into tiles of a specified shape and size, changing the color of all pixels in each tile to the average color of pixels within the tile, and adding 3D borders between the tiles.

See also IG_FX_pointillist in the Artistic Effects section.

Original

Pixelate effect

Tile Mosaic - square

Tile Mosaic - spider's web

Perspective Effect

The IG_FX_perspective effect provides a perspective-like effect by placing image corners to the specified points, and stretching the image linearly between them.

Pinch Effect

IG_FX_pinch transforms the image by making it appear as if it were pinched in the center.

A region of interest (ROI) can be used as a pinch base.

Ripple Effects

This IG_FX_radial_wave effect warps the image in concentric rings. This effect is also known as Ripple Warp, Radial Wave, or Ring Wave.

The IG_FX_directional_wave function warps the image in a specific direction.

Shear

The IG_FX_shear function applies a shearing effect to an image, moving the image rasters or columns according to the specified offsets.

Original

Shear effect

Solarize Effect

IG_FX_solarize mimics the accidental exposure of photographic film to light.

Solarize inverts the colors of pixels whose lightness exceeds a given threshold. If lightness is considered on a 0 to 1.0 scale, the default threshold used by various paint programs is 0.5.

In the following set of images, Solarize was performed with a threshold that caused the color of the sky to be inverted while the rest of the image remained unaffected.

Warp Effects

The IG_FX_cylinder, IG_FX_parabola, and IG_FX_sphere functions perform a point-to-point stretch of the image to give a warping effect.


Blending and Combining Images

A number of ImageGear's image processing functions combine data from two or more HIGEAR images, altering one with the result that it is a "blend" or other combination of the original images. These functions invariably take at least two HIGEAR handles as arguments. The functions in this group include:

IG_IP_blend_with_LUT ()
Performs weighted blend of image 2 into image 1, with the weighting factor determined by looking up the pixel/color value in your LUT.
IG_FX_chroma_key ()
This Special Effects function replaces image 1 by image 2 only where the image 1 pixels are within a specified hue range.
IG_IP_color_combine_ex ()
Combines the pixel values from separate 8 bit images to form a single 24-bit color image.
IG_IP_color_separate ()
The opposite of IG_IP_color_combine_ex (). Separates a 24-bit image's Red, Green, and Blue color values, producing separate 8-bit grayscale images (each with their own higher handle).
IG_IP_blend_percent ()
Blends together the pixel values (if grayscale) or color values (if 24-bit) of the two images, according to a percent parameter that you specify. You can specify, for example, to combine 80 percent of image 1's value, with 20 percent of image 2's value. For a 24-bit image, you can specify that only one color channel (Red, Green, or Blue), or that all three color channels, are to be blended.

When you use IG_IP_blend_with_LUT (), you provide the address of a 256-byte Look Up Table (LUT). ImageGear looks up image 1's pixel value or color value in your LUT to determine the percentages to blend for that pixel.

A different kind of blend is provided by Special Effects function IG_FX_chroma_key (). This function searches for pixels in image 1 that are within a color hue range that you specify. Only pixels within that color hue range are replaced from image 2. Arguments are provided for you to control the smoothness of the transition where replacement occurs, and a threshold pixel darkness below which replacement will not occur. You might use this to remove a person's picture from a plain background and to replace the original background with a new one. TV stations often use this technique to overlay the weather reporter onto a background of a weather map.

IG_IP_color_combine_ex () and IG_IP_color_separate () let you, respectively, assemble a 24-bit image from separate 8-bit gray level images, or disassemble a 24-bit image into separate 8-bit gray level images. In both cases, you can specify whether the 24-bit combination is standard RGB, or whether or not the 24-bit value is to be interpreted in terms of a different color space scheme. You may specify IG_COLOR_SPACE_RGB, or IG_COLOR_SPACE_IHS, or others. The complete list of supported color space schemes is provided in the file accucnst.h.


Image Correction

ImageGear provides several functions whose specific purpose is to correct an image's appearance. The functions in this group include:

IG_IP_despeckle ()
Removes noise from a 1-bit image, using a 3x3 median filter on the image.
IG_IP_median ()
Uses a median filter to reduce noise in 8-bit gray level and 24-bit images.
IG_IP_deskew_auto ()
De-skews a 1-bit image that was created by reading a text file. You can specify a threshold angle below which de-skewing should not be performed.
IG_IP_deskew_angle_find ()
Will analyze a 1-bit image and report to you the angle at which it is skewed.

In general, you would use the image correction functions with images that have been obtained by scanning text documents or graphical images.


Image Maintenance

ImageGear provides a group of image processing functions that perform image maintenance operations. All of these functions change the image bitmap, in some way changing either its size or format of the pixel data stored within it. The functions in this group include:

IG_IP_crop ()
Crops an image to a rectangle that you specify, discarding pixels that fall outside the rectangularly area.
IG_IP_resize ()
This also changes the dimensions of the image bitmap, but scales the image to fit the new dimensions.
IG_IP_resize_canvas()
Resizes image canvas, without scaling the image.
IG_IP_thumbnail_create ()
This creates a new HIGEAR image for you, of the dimensions you specify, scaling your original image to fit the new dimensions. The original image is not altered or deleted.
IG_IP_swap_red_blue ()
Exchanges the first and third bytes of each pixel in a 24-bit image's bitmap, changing the order from BGR to RGB, or vice versa.
IG_IP_encrypt ()
Encrypts your image bitmap, using a password string that you specify. To successfully decrypt the image bitmap that password will be needed.
IG_IP_decrypt ()
Decrypts an image bitmap, according to a password string that you specify. If the password is the same as used with IG_IP_encrypt () then the decrypting will be successful and the original image bitmap will be restored.


Mathematical Morphology

The field of mathematical morphology contributes a wide range of operators to image processing, all based around a few simple mathematical concepts from set theory. The operators are particularly useful for the analysis of binary images and common usages include edge detection, noise removal, image enhancement and image segmentation.

The two fundamental operations in mathematical morphology are Erosion and Dilation. Both of these operators take two pieces of data as input: an image to be eroded or dilated, and a structuring element (also known as a kernel). The two pieces of input data are each treated as representing sets of coordinates in a way that is slightly different for binary and grayscale images.

For a binary image, white pixels are normally taken to represent foreground regions, while black pixels denote background. (Note that in some implementations this convention is reversed, and so it is very important to set up input images with the correct polarity for the implementation being used). Then the set of coordinates corresponding to that image is simply the set of two-dimensional Euclidean coordinates of all the foreground pixels in the image, with an origin normally taken in one of the corners so that all coordinates have positive elements.

For a grayscale image, the intensity value is taken to represent height above a base plane, so that the grayscale image represents a surface in three-dimensional Euclidean space. Then the set of coordinates associated with this image surface is simply the set of three-dimensional Euclidean coordinates of all the points within this surface and also all points below the surface, down to the base plane. Note that even when we are only considering points with integer coordinates, this is a lot of points, so usually algorithms are employed that do not need to consider all the points.

The structuring element is already just a set of point coordinates (although it is often represented as a binary image). It differs from the input image coordinate set in that it is normally much smaller, and its coordinate origin is often not in a corner, so that some coordinate elements will have negative values. Note that in many implementations of morphological operators, the structuring element is assumed to be a particular shape (e.g. a 3×3 square) and so is hardwired into the algorithm.

Binary morphology can be seen as a special case of grayscale morphology in which the input image has only two gray levels at values 0 and 1.

Erosion and dilation work (at least conceptually) by translating the structuring element to various points in the input image, and examining the intersection between the translated kernel coordinates and the input image coordinates. For instance, in the case of erosion, the output coordinate set consists of just those points to which the origin of the structuring element can be translated, while the element still remains entirely `within' the input image.

Virtually all other mathematical morphology operators can be defined in terms of combinations of erosion and dilation along with set operators such as intersection and union. Some of the more important are Opening and Closing.

Erosion

Erosion is one of the fundamental operations in the mathematical morphology. It is usually applied to black and white images, but can also be applicable to grayscale ones. The basic effect of the operation is to erode away the boundaries of regions of foreground pixels (white pixels). Thus areas of foreground pixels shrink in size, and holes within those areas become larger. Applying this to the grayscale image will make bright objects smaller, that is, the image will be darker..

Both erosion and dilation work by translating the structuring element to various points in the input image, and examining the intersection between the translated kernel coordinates and the input image coordinates. For instance, in the case of erosion, the output coordinate set consists of just those points to which the origin of the structuring element can be translated, while the element still remains entirely "within" the input image. In the case of dilation the effect is the opposite.

For more information, see IG_IP_erode and IG_IP_NR_ROI_mask_erode functions.

Dilation

Dilation is one of the fundamental operators in the mathematical morphology. It is usually applied to black and white images, but can also be applicable to grayscale ones. The basic effect of the operation is to gradually enlarge the boundaries of regions of foreground pixels (white pixels). Thus areas of foreground pixels grow in size while holes within those regions become smaller. Applying this to the grayscale image will make bright objects larger, that is, the image will be lighter.

Both erosion and dilation work by translating the structuring element to various points in the input image, and examining the intersection between the translated kernel coordinates and the input image coordinates. For instance, in the case of erosion, the output coordinate set consists of just those points to which the origin of the structuring element can be translated, while the element still remains entirely "within" the input image. In the case of dilation, the effect is the opposite.

For more information, see IG_IP_dilate and IG_IP_NR_ROI_mask_dilate functions.

Opening

Opening is another operation from mathematical morphology that is derived from the fundamental operations of erosion and dilation. Like those operators it is usually applied to black and white images, but can be applicable to grayscale images as well. The basic effect of an opening is somewhat like erosion in that it tends to remove some of the foreground (bright) pixels from the edges of regions of foreground pixels. However it is less destructive than erosion in general. As with other morphological operators, the exact operation is determined by a structuring element. The effect of the operator is to preserve foreground regions that have a similar shape to this structuring element, or that can completely contain the structuring element, while eliminating all other regions of foreground pixels.

For more information, see IG_IP_open function.

Closing

Closing is another operation from mathematical morphology that is derived from the fundamental operations of erosion and dilation. Like those operators it is usually applied to black and white images, but can be applicable to grayscale images as well. Closing is similar in some ways to dilation in that it tends to enlarge the boundaries of foreground (bright) regions in an image (and shrink background color holes in such regions), but it is less destructive of the original boundary shape. As with other morphological operators, the exact operation is determined by a structuring element. The effect of the operator is to preserve background regions that have a similar shape to this structuring element, or that can completely contain the structuring element, while eliminating all other regions of background pixels.

For more information, see IG_IP_close function.


Pixel Access Operations

ImageGear is equipped with several functions that let you get and set the values of individual pixels, rows or columns of pixels, and rectangular groups of pixels. This family of functions is referred to as the "pixel access" functions.

All functions include the acronym "DIB" in their names. Every pixel access function is part of a "_get()/_set()" pair of functions. In other words, for each pixel access type, you can obtain the value(s) of a pixel or group of pixels, and set the value(s) of a pixel or group of pixels.

To obtain descriptions of each pixel access function and view additional sample code, refer to Core Component API Function Reference. It is important to note that although DIBs are stored upside-down so that (0,0) refers to the lower left-hand corner, ImageGear's pixel access functions consider (0,0) to be the upper left-hand corner of the bitmap data.

NOTE: Be sure to read the section entitled Using Pixel Access Functions with ImageGear.

The pixel access functions have two modes of operation: legacy (prior to 14.5) and new (14.5 and beyond). The default mode is legacy, in which these functions behave the same way they did before 14.5. So if you have existing code using pixel access functions, you shouldn't need to update it for 14.5. If you're considering using the pixel access functions for new code and you don't need to work directly with higher bit depths, uncommon color spaces, or alpha/extra channel data included with the main channel data, we recommend using the legacy mode. This mode shields you from the added complexity of these new formats.

If you want to use the new formats, or achieve maximum efficiency, you can use the new mode of pixel access to get more direct access to the new storage system. If you use the new mode, you must be aware of the following differences as compared to legacy mode:

  • For RGB images, color channel order is RGB (in legacy mode, it's BGR)
  • You can access higher bit depths (i.e. 36-bit, 48-bit RGB)
  • You can access other color spaces (i.e. LAB, YUV)
  • Alpha and extra channel data is included on a per-pixel basis. For example, if you have a 24-bit RGB image with an 8-bit alpha channel, the pixel data will look like RGBA, RGBA, RGBA and so on, where R, G, B, and A are each one byte.
  • Pixel packing and raster padding are as follows:
    Packing Mode
    Legacy
    New
    IG_PIXEL_PACKED
    1, 4bpp packed, DWORD padding
    1bpp packed, DWORD padding
    IG_PIXEL_UNPACKED
    No packing, BYTE padding
    No packing, DWORD padding

Note that 1-bit channels are the only channels that are packed in the new mode - 8 pixels stored in each byte. All other channel depths are stored as 1, 2, or 4 byte values. A channel value with depth of 2-8 bits will be stored in one byte, 9-16 bits in two bytes, and 17-32 bits in four bytes. Channel values with depths of 33-64 bits are possible on 64-bit platforms and are stored in eight bytes.

To use the new mode, you need to set the DIB.PIX_ACCESS_USE_LEGACY_MODE global control parameter to IG_PIX_ACCESS_MODE_NEW. For example:

AT_MODE pixAccessMode = IG_PIX_ACCESS_MODE_NEW;
IG_gctrl_item_set("DIB.PIX_ACCESS_USE_LEGACY_MODE",
AM_TID_AT_MODE,
    &pixAccessMode, sizeof(pixAccessMode), NULL);


Allocating Space for ImageGear Pixel Access Functions

A common thread for all _get() functions is that you must provide an array with enough space to accommodate the data that you will receive. For 1, 4, and 8-bit images, one byte per pixel must be allocated. For a 24-bit image, you must allocate 3 bytes for each pixel. One exception to this rule is when getting a rectangular area of pixels. These ImageGear functions permit you to store the data packed, so that for a 1-bit image, you could store 8 pixels per byte, and so on.

Remember that the RGB data in a DIB is stored backwards so that the pixel values that you will receive will be in the order of Blue-Green-Red (unless you have changed the order of the image bitmap bytes using IG_IP_swap_red_blue (), or one of your own image processing functions).

NOTE: It is very important that you always allocate 3 bytes for each pixel when dealing with 24-bit images.


Area Filling

The IG_DIB_flood_fill () function fills an area surrounded by a border of the specified color. You provide the fill color and coordinates of a point withing the area to be filled.


Getting and Setting Individual Pixels

There is one ImageGear function for getting and one ImageGear function for setting the value of an individual pixel: IG_DIB_pixel_get () and IG_DIB_pixel_set (), respectively. You must supply each of these functions with the HIGEAR handle of the image you are processing, and with an x and y position from which to get and then set the pixel's value. As with all pixel access functions, you should also provide an array to store the pixel value. For a 1, 4, or 8-bit image, one byte needs to be allocated, for a 24-bit image, allocate 3 bytes, for a 32-bit image, allocate 4 bytes, for a 9-16-bit gray level image, allocate 2 bytes. As noted in the previous section, the pixel access functions consider the coordinates 0,0 as the upper left-hand corner of the bitmap data.


Getting and Setting Linear Groups of Pixels

ImageGear lets you get and set the values of linear groups of pixels that run in a horizontal, vertical, or diagonal direction.

IG_DIB_column_get ()
Gets the values of a variable-length (vertical) column of pixels
IG_DIB_column_set ()
Sets the values of a column of pixels
IG_DIB_line_get ()
Gets the values of a variable-length line of pixels
IG_DIB_line_set ()
Set the values of a line of pixels
IG_DIB_raster_get ()
Gets the values of a full raster line of pixels
IG_DIB_raster_set ()
Sets the values of a full raster line of pixels
IG_DIB_row_get ()
Gets the values of a variable-length (horizontal) row of pixels
IG_DIB_row_set ()
Sets the values of a row of pixels

Raster and row access API allow packing more than one pixel per byte, you may set the nFormat argument to IG_PIXEL_PACKED. For more details, see Core Component API Function Reference.

If you are using a 24-bit image, you must allocate three bytes per pixel, whether the data is packed or unpacked. The data from a 24-bit image will be stored in BGR (blue-green-red) order. See the section entitled Allocating Space for ImageGear Pixel Access Functions for more details.

The IG_DIB_column_get () function requires that you set the nX parameter to the horizontal position of the column that you would like to get, and also the first and last row from which you would like to get the pixel values. For this you set the values of nY1 and nY2. You also give it a pointer to and nLenBytes (size in bytes) of the buffer to which you will store the pixel values. This function will return to you the actual number of pixel values acquired: lpNumPixels. If the buffer size of nLenBytes is not large enough to accommodate the number of pixels specified by nY1 and nY2, the line of pixels will be truncated, and you will not receive all of the pixels that you had specified.

IG_DIB_column_set () does just the opposite as its _get() counterpart. It takes the pixel values in the buffer and transfers a specified number of them to a HIGEAR image at row nX, and columns nY1 through nY2. You also supply this function with the number of pixel values that you will be setting, where:

max # of pixels to set = (nY2 - nY1) + 1

IG_DIB_row_get () and IG_DIB_row_set () work exactly like the above-mentioned pair of functions, except that they get and set the values of a horizontal row of pixels.

IG_DIB_raster_get () and IG_DIB_raster_set () work similarly to the functions described above, except that they will get and set the values of a full (horizontal) raster line of pixels. These functions are quite a bit easier to use than the above functions, however, because you do not need to supply the beginning and ending position of the line. Also, while you must allocate sufficient memory for the data, you do not need to tell ImageGear what number of bytes your buffer contains.

IG_DIB_line_get () and IG_DIB_line_set () give you access to the line of pixel values between any two sets of points in the image, i.e. a diagonal line, a horizontal line or a vertical line. For this reason, each requires that you set two x coordinates and two y coordinates. If you were to give equal values to either the x pair of coordinates or the y pair of coordinates, you would specify a line that was strictly horizontal or vertical, respectively. These two functions require that you give the size in bytes of the buffer and its address.


Getting and Setting a Rectangular Area of Pixels

The ImageGear functions for getting and setting the values of a rectangular area of an image are IG_DIB_area_get () and IG_DIB_area_set (), respectively. They are the same as the other pixel access functions insofar as they take a HIGEAR and a pointer to the address of the array allocated for storing the pixel values. Rather than directly taking 2 or more x and y coordinates, however, each of these functions takes an AT_RECT structure (defined in Gear.h), whose members specify the top, left, bottom and right of a rectangle within the image. Each function also takes an AT_MODE constant for the nPixelFormat parameter. This parameter may be set to one of the following values:

IG_DIB_AREA_DIB
Stores or transfers the pixel values; 8 pixels per byte for 1-bit images, 2 pixels per byte for 4-bit images, 1 pixel per byte for 8-bit images, and one pixel per 3 bytes for 24-bit images. Please also note that each row of the data will be padded to DWORD edge.
IG_DIB_AREA_UNPACKED
Stores/transfers unpacked pixel values at 1 pixel per byte for 1-, 4-, and 8-bit images, and one pixel per 3 bytes for 24-bit images.

The constant IG_DIB_AREA_DIB stores data the way that it is stored in an uncompressed DIB format, with the pixels packed so that each row is padded to a multiple of 4 bytes in length. The pixels will be stored left justified - most significant bit first. IG_DIB_AREA_UNPACKED will store the pixels right justified - least significant byte first.

NOTE: ImageGear's pixel access functions consider the coordinates 0,0 to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers 0,0 to refer to the lower left-hand corner of the bitmap.


Using Pixel Access Functions with ImageGear

If you are using any of the pixel access functions to get pixel values, you may get pixel data from an image of any bit depth (1, 4, 8, 9-16-bit gray level, 24, or 32). However, if you wish to set pixel values of a 1-bit image using, there are two peculiarities to consider:

The following pixel access functions work with the standard DIB format only:

IG_DIB_area_set ()

IG_DIB_column_set ()

IG_DIB_line_set ()

IG_DIB_pixel_set ()

IG_DIB_row_set ()

If you did not first convert the runs-compressed image to a standard DIB you will receive this error: IGE_OPERATION_IS_NOT_ALLOWED.

TIP: To be thorough, you should make a check of the 1-bit image to make sure that it is actually compressed. To do so call IG_image_compression_type_get() before converting the image from compressed DIB to a standard DIB. A return value of IG_BI_RLE means that the image is compressed.

The IG_DIB_raster_set () function needs special attention when used with ImageGear. If you call IG_DIB_raster_set() for all of the rasters in the image, you do not have to convert the image to a standard DIB first.


Clipboard Operations

The "clipboard" family of functions consists of a handful of straightforward functions that help you to meet all of your clipboard cut and paste needs very easily. With this function group, you can cut or copy all or a portion of an image to the system clipboard, paste the contents of the clipboard into a new HIGEAR image, or even "paste-merge" the contents of the system clipboard into a pre-existing image. You can also check for the existence of data in the clipboard, and check the size of an image in the clipboard. For separate descriptions of each clipboard function and additional sample code, please refer to Core Component API Function Reference.


Copying/Cutting to the Clipboard

You may cut or copy the entire HIGEAR image, or just a specified rectangular portion of the image, to the clipboard. To copy to the clipboard simply call the function IG_clipboard_copy ()with the image's HIGEAR handle, and the coordinates of the AT_RECT rectangle that you would like to save to the clipboard. Pass NULL as the rectangle's value to if you want to copy the entire image to the clipboard.

To cut to the clipboard, call IG_clipboard_cut (). The only difference in the prototype of these functions is that IG_clipboard_cut() contains an extra argument for specifying what color pixel to use to replace the pixels that are "cut away". This pixel color argument is usually set to black or white.


Checking the Contents of the Clipboard

ImageGear provides two functions for examining the contents of the clipboard: IG_clipboard_paste_available_ex () and IG_clipboard_dimensions (). The first of these functions will let you know whether there is an image in the system clipboard. It is recommended that you always call this function before pasting from the clipboard, and also before calling IG_clipboard_dimensions().

IG_clipboard_paste_available_ex () returns a AT_BOOL value, where TRUE means that there is a paste-able image in the clipboard.

IG_clipboard_dimensions() returns three values to you: the width and height of the image (in pixels), and the number of bits per pixel of the image on the clipboard. Using these values, you can determine whether or not the image dimensions are appropriate for your purposes.


Pasting an Image from the Clipboard

There are two ImageGear functions for pasting the image from the clipboard: IG_clipboard_paste () and IG_clipboard_paste_merge_ex (). The first of these two functions will create a new HIGEAR image and paste in the contents of the clipboard. IG_clipboard_paste_merge_ex () will paste the clipboard image into an existing HIGEAR image at the position that you specify. If the clipboard image's width is greater than the image being pasted to, it will automatically be cropped to fit; the size of the original HIGEAR image will not change.

Before you call IG_clipboard_paste_merge_ex (), you can call the function IG_clipboard_paste_op_set () to set the kind of arithmetic operation to apply to the pixels of the two bitmaps that intersect during the paste-merge. IG_clipboard_paste_op_set() takes an AT_MODE constant (defined in accucnst.h) that has a prefix of IG_ARITH_. The full group of arithmetic constants is listed under the function description for IG_clipboard_paste_op_set() in Core Component API Function Reference. ImageGear also supplies a companion reading function IG_clipboard_paste_op_get () to read the current setting for the paste-merge arithmetic operation. See Example code below:

AT_DIMENSION nWi, nHi;
UINT nBpp;
BOOL bPasteAvail;
AT_ERRCOUNT nErrcount;
HIGEAR hIGear, hIGear2;
AT_RECT rcClipRect;
nErrcount = IG_load_file("picture.bmp", &hIGear);
if (nErrcount == 0)
{
    nErrcount = IG_image_dimensions_get ( hIGear, &nWid, &nHi,
&nBpp );*/
    if ( nErrcount == 0 ) /* If valid image dimensions */
    {/* send the bottom half of the image*/
        rcClipRect.top = nHi/2; /* to the clipboard */
        rcClipRect.left = 0;
        rcClipRect.right = nWi - 1;
        rcClipRect.bottom = nHi - 1;
        nErrcount = IG_clipboard_copy (hIGear, &rcClipRect);
    }
if (nErrcount == 0)
{
/*load a second image into which to merge the clipboard
contents*/
        nErrcount = IG_load_file("picture2.bmp", &hIGear2);
}
if (nErrcount == 0)
{
    nErrcount = IG_clipboard_paste_available_ex(&bPasteAvail);
    if (bPasteAvail == TRUE)
    {
    /* set the paste-merge arithmetic operation to Img1^Img2 */
    nErrcount = IG_clipboard_paste_op_set(hIGear,
                IG_ARITH_XOR);
    /* merge clipboard's rectangular contents with upper left
     corner at position 0,0 		*/
        nErrcount = IG_clipboard_paste_merge_ex(hIGear2, 0 , 0);
        }
}


Printing Images

ImageGear provides a simple all-purpose printing function that will print any image to a graphics-capable printer. This function is:

IG_dspl_image_print ( HIGEAR hIGear, DWORD dwGrpID, HDC hDC,
BOOL bDirectToDriver );

This function prints a HIGEAR image to the current default printer according to the display parameter specified by dwGrpID group. There is special group IG_GRP_DEFAULT_PRINT that can be used to print image with default print options. The argument, bDirectToDriver, when TRUE, instructs ImageGear to send the image's DIB directly to the printer's device driver. In this case, the entire procedure is controlled by the printer's driver. If your printer has special capabilities such as color, and if the driver supports these, then your image can be printed with these features.

When bDirectToDriver is FALSE, ImageGear handles the printing procedure. ImageGear first reduce the image to 1-bit if necessary (such as by using a Bayer dithering algorithm). It then sends each raster line to the printer driver individually. If you've called IG_status_bar_CB_register () to declare a status bar callback function, ImageGear calls your callback function after each raster line is sent. This type of callback permits you to display a status bar showing the completed percentage, or a message box displaying the page number being sent. You can also detect a keystroke or mouse selection indicating that the user wants to cancel the printing process. The sample application program "print.c" demonstrates how to implement these and other features, including an initial Print Dialog Box.

In general, bDirectToDriver = FALSE gives you greater control of the printing process, while bDirectToDriver = TRUE gives you faster printing.

Note also that the functions IG_dspl_page_print (), IG_dspl_document_print (), and IG_dspl_document_print_custom () allow you to specify how to print a single image on a page, and how to print a list of images on a page, specifying how to place the images relative to the page's borders.

See Chapter "Core Component API Function Reference", for more information on function IG_dspl_image_print (), IG_dspl_page_print (), IG_dspl_document_print (), and IG_dspl_document_print_custom ().


Thread Safety

ImageGear and its associated components are 100 percent thread-safe. The implementation of thread safety in ImageGear maximizes the performance of threaded applications on multi-CPU computers, providing the benefit of performance scalability at a huge cost savings over other implementations. Every ImageGear API function can be executed within a thread.

Five thread safety APIs are explained in detail in "Core Component API Function Reference".

  • IG_thread_data_ID_associate ()
  • IG_thread_data_ID_get ()
  • IG_thread_local_data_cleanup ()
  • IG_thread_image_lock ()
  • IG_thread_image_unlock ()

In most cases no additional API calls are required to achieve thread safety.

IG_thread_data_ID_associate(), IG_thread_data_ID_get(), and IG_thread_local_data_cleanup() functions only provide additional flexibility allowing thread customized ImageGear settings.

IG_thread_image_lock()/IG_thread_image_unlock() are only required in the situation where several threads are accessing the same HIGEAR concurrently AND at least one of these threads performs an operation that modifies/deletes HIGEAR.

NOTE: The global group of ART settings cannot be used in multi-threaded application. You have to use this function to associate a new local group of settings for each new thread. For more detailed information please see the example code for IG_thread_data_ID_associate() function.
NOTE: The access to the same PDF document from multiple threads is not permitted because the multiple threads cannot share Adobe PDF Library datatypes. PDF doc created/opened in the main thread can be only used from the main thread.


Working with Format Filters

ImageGear introduces significant improvements in the area of working with images stored on disk and in memory. This includes new additional API, improved scheme of setting image control parameters and more GUI controls to simplify and illustrate the process of working with file formats.

Every image format supported by ImageGear has its own filter, including the set of internal functions organized into the special structure that completely defines the filter's functionality. Every filter has its own banch of control parameters that can determine the manner in which it loads, saves and operates with images. Besides this, the control parameters used for the filters API are not constants (IG_CONTROL_TIF_BUFFER_SIZE ) as they were in previous versions of ImageGear, but a string ("BUFFER_SIZE"). Please see detailed information about the control parameters for each format filter in the ImageGear Supported File Formats Reference section.

Every format filter has its own list of supported features determined by IG_FLTR_ flags. The table below describes the meaning of each of these flags:

IG_FLTR_DETECTSUPPORT
Means that filter supports autodetection.
IG_FLTR_PAGEREADSUPPORT
Means that filter supports single page file reading.
IG_FLTR_MPAGEREADPSUPPORT
Means that filter supports multi-page file reading.
IG_FLTR_PAGEINSERTSUPPORT
Means that filter supports single-page file writing.
IG_FLTR_MPAGEWRITEPSUPPORT
Means that filter supports multipage file writing.
IG_FLTR_PAGEDELETESUPPORT
Means that filter supports page deleting from multi-page file.
IG_FLTR_PAGESWAPSUPPORT
Means that filter supports page swaping in multi-page files.
IG_FLTR_MPDATASUPPORT
Means that filter supports faster multi-page access by storing private format data (used only with IG_mpi_... and IG_mpf_... API).

Please see information about the supported features for each format filter in the ImageGear Supported File Formats Reference section.

ImageGear supports different types of image compression. Currently every ImageGear format filter has its own list of supported compressions, determined by IG_COMPRESSION_ constants for different types of images. For information about the supported compressions for every format filter, see the ImageGear Supported File Formats Reference and ImageGear Supported Compressions Reference section.


Using the Format Filters API for Image Loading and Getting Information.

The ImageGear Format Filters API allows you to load an image into memory, detect the format of an image file, get info about the features supported by ImageGear for this format, provide image control parameters, work with pages in multi-page files and save an image in a single- or multi-page file.

In the case of loading and saving image files, you can choose which functionality group (IG_fltr_ ...() or IG_load/save_ ...()) is more useful for your application.

To import an image from a file format to an internal memory representation, you can use the function:

IG_fltr_load_file(const LPSTR lpszFileName, UINT nPageNumber,
LPHIGEAR lphIGear);

If the image file is on a mass storage device, such as a disk, then the first parameter specifies its file name. The second parameter determines the page number (starting from 1) if the image file contains more than 1 page. The last parameter is a handle of internal memory representation. This received handle can be used then to perform different operations on the image, such as image processing or export operation. The file specified by lpszFileName should be in one of the ImageGear supported image file formats; ImageGear detects this format automatically. If the format is invalid or unsupported, this function puts an error into the error stack. This function is similar to IG_load_file (), but the last one always imports the first page.

TIP: Actually you can use other ImageGear functions for loading images from disk and from memory, such as IG_load_...() functions. They are very convenient when you don't need to work with a large amount of images and you do not need to optimize the speed of loading multiple pages from file. But if you need to work with a large range of image files, especially multi-page files, and need your application to work faster, choosing images with determined parameters such as the type of file format, compression, page number, size, supported features, control parameters, we recommend that you use the IG_fltr_...() functions.

Detecting the File Format

You can detect the format of image file before and after loading it in HIGEAR handle using functions IG_fltr_detect_...():

IG_fltr_detect_FD(INT fd, LONG  lOffset, LPATE_MODE lFileType)
IG_fltr_detect_file(const LPSTR lpszFileName, LPATE_MODE
lFileType)
IG_fltr_detect_mem(void FAR lpImage, DWORD dwSize, LPATE_MODE
lFileType)

The first function detects the format by scanning its File Descriptor fd starting from the lOffset position in the file. The second IG_fltr_detect_file() function determines the format of image located in the file by given filename. Function IG_fltr_detect_mem() determines the format of image located in memory buffer. All three functions return the type of image format as IG_FORMAT_ constant, determined in accucnst.h file. The code fragment below allows you to sort image files by their formats and then choose how to use them:

AT_ERRCOUNT nErrCount = IGE_SUCCESS;/* will hold returned error
count */
AT_MODE nFormatID;
...
nErrCount = IG_fltr_detect_file( "image.tiff", &nFormatID );
if( nFormatID==IG_FORMAT_TIF )
{
...
}

For better performance or for some other purposes, use the special functions IG_fltr_load_file_format ()and IG_fltr_pagecount_file_format ()if the image format is known. Those functions accept the first parameter as the format ID and do not perform usual detect operations like IG_fltr_load_file ()does, but immediately start to operate with the data, assuming it from the specified format. If the data is invalid or the image format is different, then an error is placed in the error stack.

Getting Information and Sorting Images

To get information about every ImageGear format filter use IG_fltr_info_get () function. It returns information about the features supported by ImageGear for this file format (as IG_FLTR_ flags), the short and full names of the filter's file format and the names of the default file's extension:

nErrCount = [lpfn]IG_fltr_info_get( nFormat, &dwFlags,
szShortName, sizeof(szShortName), szFullName,
sizeof(szFullName), szDefExt, sizeof(szDefExt) );

Together with this function, you can use the IG_fltr_formatlist_sort ()function to sort file formats in alphabetic order based on the short name returned by the IG_fltr_info_get() function through its third lpShortName parameter.

If you want to determine the list of filters that support the IG_FLTR_ features you can use the function:

IG_fltr_formatlist_get(DWORD dwFlags, LPAT_MODE lpFormatList,
UINT nFListSize, LPUINT lpnFListCount)

Through the dwFlags argument, you can specify any combination of features (for instance, IG_FLTR_DETECTSUPPORT | IG_FLTR_PAGEREADSUPPORT | IG_FLTR_MPAGEREADPSUPPORT), and a list of filters that support those features will be returned through the second parameter (lpFormatList). See the description of this function in the Core Component API Function Reference for detailed information about the parameters. If you want to determine the value of the nFListSize argument, first set lpFormatList to NULL. You can also use this function together with IG_fltr_formatlist_sort ()to get the list of filters that support necessary features and sort them by filter name:

UINT              nFilterSize;
UINT              nFListSize;
LPAT_MODE         FList = NULL;
LPCHAR            lpFilter = NULL;
LPSTR			str;
IG_fltr_formatlist_get( IG_FLTR_PAGEREADSUPPORT, NULL, 0,
&nFListSize );
FList = malloc( nFListSize*sizeof(AT_MODE) );
if( FList!=NULL )
{
IG_fltr_formatlist_get( IG_FLTR_PAGEREADSUPPORT, FList,
nFListSize, NULL );
IG_fltr_formatlist_sort( FList, nFListSize );
...
}

You can get information about any page of a multi-page file without loading it into memory if you use the function IG_fltr_pageinfo_get (). Return information consists of the name of the file format (as IG_FORMAT_ constant), the type of image compression (as IG_COMPRESSION_ constant), and such info as bpp, width and height of the page-image.

Another two IG_fltr_...() functions allow you to work with pages in a multi-page file without loading it in memory:

IG_fltr_pageswap_file (const LPSTR   lpszFileName, AT_MODE
nFormatType,  UINT  Page1, UINT  Page2)
IG_fltr_pagedelete_file (const LPSTR   lpszFileName, AT_MODE
nFormatType,  UINT  nStartPage, UINT  nRange)

Both functions accept the filename of the multi-page image, format filter ID and two integer parameters as page numbers (assuming numeration from 1). The first function swaps pages in a multi-page image specified by page numbers, but the second function deletes pages from it.

Before using these functions you have to determine whether or not ImageGear supports the corresponding features for the necessary file format. This can be done using the function IG_fltr_info_get () and inspecting flags returned through the second parameter for the specified file formats. If this value contains the flag IG_FLTR_PAGESWAPSUPPORT, then the format filter does support the IG_fltr_pageswap_file() operation. If it has also the flag IG_FLTR_PAGEDELETESUPPORT, then it supports the IG_fltr_pagedelete_file() operation.

NOTE: SWAP and DELETE operations may or may not physically reorder multi-page files. For example, the page delete operation may not really reduce the size of the file - just update the file format structures and remove the specified pages from it.


Using Format Filters API for Image Saving

The ImageGear filters API provides three saving functions that make your application much faster and more flexible when working with image saving:

IG_fltr_save_file (HIGEAR hIGear, const LPSTR lpszFileName,
AT_LMODE lFormatType, UINT nPageNumber, AT_BOOL bOverwrite)
IG_fltr_compressionlist_get (LPAT_DIB lpDIB, AT_MODE nFormatID,
LPAT_MODE lpComprList, UINT nCListSize, LPUINT lpnCListCount)
IG_fltr_savelist_get (LPAT_DIB lpDIB, LPAT_MODE lpnFilterList,
UINT nFListSize, LPAT_LMODE lpSaveList, UINT nSListSize, LPUINT
lpnSListCount)

The function IG_fltr_compressionlist_get() allows you to get information about all compressions (as IG_COMPRESSION_ constants returned in lpComprList list) that are available when saving the image to the file format specified by the nFormatID (as IG_FORMAT_ constant) parameters. The first parameter allows you to specify information about the image to be saved. If this parameter is NULL then the function returns all available compressions, otherwise it returns compressions that are applicable to a given image. For example, G3/4 compressions are only applicable for bi-tonal images, but JPEG compression is only applicable for color images with 8 bits or more per pixel.

Function IG_fltr_savelist_get () is more advanced and allows you to prepare the list of applicable compressions not for the single format but for the list of formats. It provides the ability to quickly build the list of applicable parameters that can be used, for instance, for the third (lFormatType) parameter of IG_fltr_save_file (). The main returned value lpSaveList contains a list of combined values (nFormat | (nCompression<<16)) = (IG_FORMAT_ | IG_COMPRESSION_<<16) available for a given image to save. You can get values of nFormat from lpnFilterList provided through the second parameter. For instance, if you specified lpnFilterList as IG_FORMAT_TIF, then the returned lpSaveList will be looked at as a list of (IG_FORMAT_TIF | IG_COMPRESSION_ ) values where IG_COMPRESSION_ is a list of all the compressions available for the TIFF image with the current lpDIB.

If lpnFilterList is NULL then this function uses all available formats registered in ImageGear and returns the list with all currently available formats and compressions.

The basic saving function of the ImageGear Filters API IG_fltr_save_file () works similarly to the IG_save_file () function, but has additional arguments that enhance your work when saving the image in a multi-page file. The nPageNumber argument allows you to specify the number of the page in an already existing multi-page file where you want the saved page to be placed. The last argument bOverwrite allows you to determine the mode of how to work with multi-page image files. The TRUE value completely overwrites the file and places a single page there, but a FALSE value means that the existing file will be expanded with one additional page specified by the nPageNumber parameter.

You can process the IG_fltr_compressionlist_get () and/or IG_fltr_savelist_get ()functions before using IG_fltr_save_file ()to determine the file format and compression type you specified in the lFormatType argument (as IG_SAVE_ constant, see accucnst.h file).

Saving Images to Memory

The function IG_fltr_save_mem() allows you to save a HIGEAR image to memory. The result will be a file image in memory that is identical to the file that would have resulted if you had used any other save function (such as IG_fltr_save_file ()). However, instead of using a filename to call IG_save_mem() with, you specify the address and size of the memory area to save to. The allocation of memory is discussed further below.

If there already is a valid image file at the address you specify in an IG_fltr_save_mem() call, the effect is the same as when using IG_fltr_save_file() to save to an existing file. Specifically, it allows appending or inserting pages into existing file stored in memory.

Before you call IG_fltr_save_mem() you need to allocate a memory buffer, and you must supply the size of the allocated buffer to the function. You can determine the appropriate buffer size by making a call to IG_fltr_save_mem_size_calc(). The size returned by this function will include the size of the bitmap data, which can be a portion of the image (the image rectangle) or the whole image, plus any other structures, such as the header or palette. If you are going to add a page to an already existing image in the memory buffer, pass address of the buffer to IG_fltr_save_mem_size_calc(). The function will calculate and return the size necessary for storing the image after addition of the page.

You can use these steps to save a multipage file in a memory buffer:

  1. Call IG_fltr_save_mem_size_calc () specifying the HIGEAR for the first page, and passing NULL to lpImage parameter. This will return the size of the first page, saved to the buffer.
  2. Allocate a memory buffer using the calculated size.
  3. Save first page to the memory buffer, using IG_fltr_save_mem ()
  4. Call IG_fltr_save_mem_size_calc () specifying the HIGEAR for the second page, and passing the pointer to the memory buffer you've allocated, to lpImage parameter. This will return the size of the first and second pages page, saved to the buffer.
  5. Reallocate memory buffer using the new size.
  6. Save second page.
  7. Continue for the rest of pages.

This process can be optimized. For example, you can allocate (size of first saved page) * (number of pages) bytes in the first place, to reduce the number of reallocations.

IG_fltr_save_mem() will return the actual size that the file required when it was saved to memory.


Using Format Filters API for Filter Control

Almost every format filter in ImageGear has some attributes that it depends on while processing its operations such as READ, WRITE and etc. Those attributes may be attributes declared by the format filter specification or it may be specific to its implementation by ImageGear. Anyway, ImageGear has a general public interface implemented and named as format filter control parameters. Every such control parameter is identified by the format filter and string name and has an associated type of acceptable value, the value itself and the default value. The sense of each control parameter is filter specific. The ImageGear Supported File Formats Reference section in Chapter File Format Reference, where descriptions of filters are located, also contains a description of each control parameter for each format filter.

The ImageGear Filters API has three new powerful functions that allow you to get/set and retrieve info about every supported filter control parameter:

IG_fltr_ctrl_list(DWORD  dwFormatID, LPUINT lpnCount, LPDWORD
lpArray, DWORD dwArraySizeInBytes)
IG_fltr_ctrl_get(DWORD dwFormatID, const LPCHAR lpcsCtrlName,
AT_BOOL    bGetDefault, LPAT_MODE lpnValueType, LPDWORD
lpdwValueSize, LPVOID       lpBuffer, DWORD dwBufferSize)
IG_fltr_ctrl_set(DWORD dwFormatID, const LPCHAR lpcsCtrlName,
LPVOID lpValue, DWORD dwValueSize)

The first function IG_fltr_ctrl_list() allows the application to get the list of names of all control parameters supported by the format filter identified by dwFormatID. The Application is responsible for allocating the buffer lpArray, but ImageGear sets the elements of this array as pointers to strings with control parameter names.

You can use these control parameter names as input values for the second argument for the next two functions - IG_fltr_ctrl_get() and IG_fltr_ctrl_set(). The first function is used to get the value of a given control parameter of a given format filter, and it may return either its current value or its default value - that is controlled by the bGetDefault argument. The TRUE value returns default value, but FALSE returns the current value. The value itself is copied into a buffer that the application provides through the dwBufferSize argument.

The third function IG_fltr_ctrl_set()allows you to set a new value for the control parameter. The last two arguments of this function specify the data to be set, and ImageGear always treats this data as a type that can be gotten by the _get() function.

NOTE: If the actual size of the new value is less than 4 bytes, then lpValue is treated as the value itself, otherwise it is treated as a pointer to the value.

The following code fragments demonstrate how to use these functions:

This example demonstrates how to get the names of all supported control parameters for the TIFF format filter:

/* getting the total number of parameters */
nErrCount = IG_fltr_ctrl_list(IG_FORMAT_TIF, &nCount, NULL, 0);
if(!nErrCount && nCount > 0)
{
/* allocate required buffer to keep all names */
lpOptList = malloc(nCount * sizeof(DWORD));
    if(lpArray)
    {
    nErrCount = IG_fltr_ctrl_list(IG_FORMAT_TIF, NULL,
lpOptList, nCount * sizeof(DWORD));
NOTE: Please remember that filter control parameters you work with using IG_fltr_ctrl_...() functions are now strings. You can see them in the "Filter Control Parameters" Tables for every file format in the ImageGear Supported File Formats Reference section.

This example demonstrates how to get and set the value of the TIFF control parameter named "BIG_ENDIAN" :

char DocumentName[_MAX_PATH];
AT_BOOL bDefBigEndian, bOldBigEndian;
...
/* get current value of BIG_ENDIAN control parameter */
IG_fltr_ctrl_get(IG_FORMAT_TIF, "BIG_ENDIAN", FALSE, NULL,
NULL, (LPVOID)&bOldBigEndian, sizeof(hOldBigEndian));
/* get default value of BIG_ENDIAN control parameter */
IG_fltr_ctrl_get(IG_FORMAT_TIF, "BIG_ENDIAN", TRUE, NULL, NULL,
(LPVOID)&bDefBigEndian, sizeof(hDefBigEndian));
/* get current value of DOCUMENT_NAME control parameter */
IG_fltr_ctrl_get(IG_FORMAT_TIF, "DOCUMENT_NAME", FALSE, NULL,
NULL, DocumentName, sizeof(DocumentName));
/* set new value to BIG_ENDIAN control parameter */
IG_fltr_ctrl_set(IG_FORMAT_TIF, "BIG_ENDIAN", (LPVOID)TRUE,
sizeof(AT_BOOL));
/* set new value to DOCUMENT_NAME control parameter */
strcpy( DocumentName, "This is a test string for DocumentName"
);
IG_fltr_ctrl_set(IG_FORMAT_TIF, "DOCUMENT_NAME",
(LPVOID)DocumentName, sizeof(DocumentName));
NOTE: In the case of TXT Filter to set the LINES_PER_PAGE and CHAR_PER_LINE control parameters, do not set the POINT_SIZE control parameter because setting the PAGE_WIDTH, PAGE_HEIGHT and POINT_SIZE parameters provides sufficient page description, and LINES_PER_PAGE, CHAR_PER_LINE options are ignored. To set these parameters you should set POINT_SIZE option to zero.


Non-Image Data Processing

Such complex format filters as EXIF-JPEG, EXIF-TIFF, TIFF, JPEG, PNG and some others contain a lot of non-image data generally refered to as meta-data. ImageGear provides a machanism for reading the meta-data during image loading and modifying it during image saving. Non-image data itself can be of any possible complex type and completely depends on the nature of the file format. ImageGear processes this complex data through a single interface and allows uniform processing that does not depend on the actual data format and starts from information fields of such simple formats as BMP and PCX, up to the complex metadata support in the EXIF filter and the IPTC non-image data format in such filters as TIFF and JPEG.

NOTE: While EXIF-JPEG, EXIF-TIFF is a separate image file formats using JPEG or TIFF image data compressions, IPTC is a format used only for non-image data storage in such imaging format filters as JPEG, TIFF. For more detailed information about these formats, see the EXIF-TIFF Non-Image Data Structure, EXIF-JPEG Non-image Data Structure and the IPTC Non-Image Data Structure sections in Appendix Appendix: Non-Image Data Storage as well as the EXIF-JPEG and EXIF-TIFF sections in the File Format Reference Chapter.

ImageGear is responsible for translating this format-dependent data into a standard uniform format. There are at least two operations that include such data processing:

  • image loading - during image loading some additional data needs to be loaded and uncompressed into the set of values of standard types for further processing.
  • image saving - during image saving there should be a way to change already defined values and add new values.

The next section defines the uniform data format that is used for such data exchange.

Non-Image data format

The key thing of non-image data processing in ImageGear is a uniform data format that is used to convert to and from the format filter. As soon as the format filter decodes the data fields one after another during the loading operation, and encodes it in the reverse direction during the saving operation, all data consists of the set of items where each item is a minimal atom of information. The order of items is fixed, and the format filter processes item after item in the given order. The same order is used when data is passed through the stream.

Let's look at the low-level format of the data. It consists of the list of items where each item represents a minimal unit of information. Each item also should have some unique name that allows you to connect it with the physical value inside of the file format. The definition of the data item can be described by the following fields:

typedef struct tagAT_DATALIST_ITEM{
    AT_MODE		FormatID
    LPCHAR 		Name;
    DWORD 		Id;
    AT_MODE 		Type;
    LPVOID 		Value;
    AT_MODE 		ValueType;
    DWORD 		Length;
    AT_MODE 		ValueAccessMode;
    }AT_DATALIST_ITEM;

Please see the descriptions of these fields in the Table below:

FormatID
The ID of the filter that reads or writes a file (IG_FORMAT_... constant value)
Name
The name of the item. Can be any string value.
Id
Numerical ID of item. Can be any value of DWORD size.
Type
Specifies the type of item and reflects the status of the given record. Possible values are:
  • IG_METAD_VALUE_ITEM - this value specifies that the current item is a value of the simplest type and the field Value contains the actual value of the item, and ValueType contains the identifier of the type of this item. ReadOnly can be either TRUE (read-only) or FALSE (read/ write). Name and/or Id contains textual and numerical identification of the item.
  • IG_METAD_LEVEL_START - this value specifies that the current item opens the sublevel of items and all the next items up to the corresponding item with the LEVEL_END value belonging to this sublevel.
  • IG_METAD_LEVEL_END - this value closes the current sublevel and tells that next item belongs to a higher level.
Value
Contains the value of the item in the case of Type = IG_METAD_VALUE_ITEM.
NOTE: Possible values of this field are fixed and define exact list of allowed data types. It also depends on ImageGear platform and FLTR.METADATA_FORMAT global control parameter. This global parameter has two allowed values: "text" and "binary".
See the section Metadata Structure "ValueType" and "Value" for the possible values.
ValueType
Contains the type identifier of the item in the case of Type = IG_METAD_VALUE_ITEM.
Possible values of this field are fixed and define the exact list of allowed data types.
See the section Metadata Structure "ValueType" and "Value" for possible values.
Length
Identifies the number of values to be written.
For AM_TID_TXT_STRING it should indicate the number of characters in the string excluding last null character (basically the length of the string). For AM_TID_RAW_DATA it should indicate the number of bytes that the raw data occupies. For the rest of the types it should indicate the number of values of the type, which textual representation is encoded into "Value".
ValueAccessMode
Identifies wether data can be changed or not. "Read only" value means that its value is information only and cannot be changed after setting the initial value. It also means that its value will be ignored during a WRITE operation.

So, this data structure allows to "linearize" hierarchical and complex data into the array of simplest data types.

You can transfer different non-image data using the general data structure described in this section. Please see Appendix Appendix: Non-Image Data Storage .

Processing of non-image data through filter callback functions

There are two working scenarios of how ImageGear processes non-image data.

The first one is the LOAD operation:

1. Application registers special callback function of type LPAFT_IG_METAD_ITEM_GET_CB .
2. The application calls some of the filter loading functions (like IG_fltr_load_file ()), and during the LOAD operation, the format filter calls the registered callback function to pass data for each item decoded from the image.

The reverse WRITE operation is more complex:

1. Application registers callback functions of types LPAFT_IG_METAD_ITEM_SET_CB and LPAFT_IG_METAD_ITEM_ADD_CB.
2. Application calls some filter writing functions (like IG_fltr_save_file ()).
3. While performing WRITE operation ImageGear uses callback functions to modify existing items or add additional items to required dataset.
NOTE: ImageGear provides new special LPAFT_ callback functions for the non-image data processing described in this section. It also preserves the "old" callback functionality (LPFNIG_ callback functions) required for the image processing control and perfection. Please see Working with ImageGear Callback Functions for detailed information about the structure of the ImageGear callback functionality.

You can see from the declaration below that LPAFT_IG_METAD_ITEM_GET_CB accepts parameters that provide all necessary information about one data item. All parameters except the first one are fields of the data structure AT_DATALIST_ITEM described in previous Non-Image data format section:

LPAFT_IG_METAD_ITEM_GET_CB(LPVOID lpPrivate, LPCHAR ItemName,
DWORD ItemID, AT_MODE ItemType, LPVOID ItemValue, AT_MODE
ValueType, DWORD ValueLength, AT_BOOL ReadOnlyValue )

By implementing and providing a callback function of this type, the application can receive every decoded item and process it as needed.

Some items from the dataset are informational only and cannot be changed during the WRITE operation. So, if ReadOnlyValue field is set to TRUE then item is not be changed during the WRITE operation. Actually, during this operation the format filter prepares all necessary items and puts required values to them to make sure that the file format itself is not violated. For instance, there can be the item that keeps the number of strips in the image, and if the value of this item is changed, the image cannot be loaded.

The format filter prepares a minimal set of items and default values for them, and before writing its values to the output stream it calls the callback function of type LPAFT_IG_METAD_ITEM_SET_CB so that the application can change its values. In addition, the format filter may call the function of type LPAFT_IG_METAD_ITEM_ADD_CB to get additional items to append the dataset. The application should provide its implementation in such a way that it returns TRUE until it is necessary to insert more items. If this function returns FALSE, all custom items have been added, and the filter can proceed

NOTE: It may happen that the application provides the item with the name or ID of a different type than the format filter is expecting. For example, the format filter may expect the item named SOFTWARE with text as a String, but the application provides its value as an Integer. In this case the filter may ignore this item and put the warning that this type of item is not expected. Also, the application may provide an item that the format filter is not able to handle because it does not fit the format defined by the corresponding image file format. In this case it may simply ignore the item and give a warning.

The exact specification of the callback function types can be found in the "Core Component API Function Reference" Chapter, but the following is a quick reference for better understanding:

LPAFT_IG_METAD_ITEM_SET_CB)(LPVOID lpPrivate, LPCHAR ItemName,
DWORD ItemID, AT_MODE ItemType, LPVOID ItemValue, AT_MODE
ValueType, DWORD ValueLength, AT_BOOL ReadOnlyValue, LPVOID
*NewItemValue, LPAT_MODE *NewValueType, LPDWORD *NewValueLength
)

*NewItemValue, *NewValueType, *NewValueLength are parameters of new value for given item. If ReadOnlyValue is TRUE, the value of this item is unchangable.

You can add a new non-image item during the filter WRITE operation using the callback function prototype:

LPAFT_IG_METAD_ITEM_ADD_CB(LPVOID lpPrivate, LPCHAR ItemName,
DWORD ItemID, AT_MODE ItemType, LPVOID ItemValue, AT_MODE
ValueType, DWORD ValueLength, AT_BOOL ReadOnlyValue )

All arguments in this function are parameters for the new item and its value.

To exchange the non-image tag information, provided by these three callback functions, between the application and the internal ImageGear structure levels you should use two functions:

IG_fltr_metad_callback_get(LPVOID *lpPrivate,
LPAFT_IG_METAD_ITEM_SET_CB    *lplpfnSetCB,
LPAFT_IG_METAD_ITEM_ADD_CB  *lplpfnAddCB,
LPAFT_IG_METAD_ITEM_GET_CB *lplpfnGetCB )
IG_fltr_metad_callback_set(LPVOID *lpPrivate,
LPAFT_IG_METAD_ITEM_SET_CB    *lplpfnSetCB,
LPAFT_IG_METAD_ITEM_ADD_CB  *lplpfnAddCB,
LPAFT_IG_METAD_ITEM_GET_CB *lplpfnGetCB )

The first function allows you to provide the current callback non-image tag data from the internal ImageGear structure to an application level during load/save processes. If some callback information is not necessary, you can set the respective argument of this function to NULL. For instance, if you do not need information about newly added non-image items, set lplpfnAddCB = NULL.

The second _set() function provides the new non-image callback data from the application level to the internal ImageGear level during the load/save processes. Again, if some callback information is not necessary you can set the respective argument of this function to NULL.

An example, how to use this callback functions is too complex to include into this manual. The GUI implementation that is provided in the source form demonstrates all aspects of working with these callback functions.

Updating non-image data in a file without loading and saving the image

Callback functions can be used to get and set non-image data during normal load and save operations. It is also possible to use callback functions with the IG_fltr_metad_update_file () function to operate on only the non-image data in a file. This function creates a new file with an exact copy of the source file's pixel data and with new non-image data. Pixel data is not decoded but copied directly from source to destination file. This function is currently supported with the following file formats only:

  • TIFF (except for TIFF-JPEG)
  • JPEG

IG_fltr_metad_update_file () obtains new non-image data from the following callback functions:

LPAFT_IG_METAD_ITEM_SET_CB, LPAFT_IG_METAD_ITEM_ADD_CB.

Using metadata update function

IG_fltr_metad_update_file () function can be used as follows:

  • Load necessary page to get metadata;
  • Change metadata (add / delete / change metadata tags or metadata values);
  • Call IG_fltr_metad_update_file() function. nPageNumber and lFormatType parameter values should correspond to the loaded page and source file format.

The destination file will be a copy of the source file with the new non-image data for the specified page.

The application may then delete the source file and rename the destination file with the name of the source file.

Example of using IG_fltr_metad_update_file function

Usage of metadata update function is demonstrated in the Filter sample. Use the following steps to test this feature:

  1. Open a TIF image using File/Open menu item;
  2. Add or modify tag(s) using Image/Metadata/Data Structure dialog
  3. Create a file with updated metadata using File/Update metadata menu item. Source file name and page number correspond to the last loaded page in the filter sample.
NOTE: All changes made in the Metadata dialog will be lost if any function that returns metadata is called before calling IG_fltr_metad_update_file() (loading a new file, getting file info or preview).

Working with XMP Metadata

Extensible Metadata Platform (XMP) is an XML-based standard for storage and interchange of metadata, developed by Adobe Systems Inc. The standard defines the rules for storage and processing of the metadata, and provides a number of schemas for storage of information that is typically asociated with images and documents, such as Title, Author, Creation date/time, Rating, etc. Applications can add their own schemas to store arbitrary information.

XMP metadata can be attached to files of various formats, such as TIFF, JPEG, PSD and PDF, or stored as a standalone file.

ImageGear provides the following ways for working with XMP metadata.

  1. Accessing XMP properties via the ImageGear Metadata API. In this mode, ImageGear decodes XMP properties and sends them to the application via metadata callbacks.
  2. Working with unprocessed XMP metadata. In this mode, ImageGear passes XMP to the application as a byte array, treating it as a single tag of the containing metadata format.

By default, ImageGear parses XMP stream into its metadata structure, and does not provide the Raw XMP stream. If you don't want ImageGear to parse the XMP stream, and prefer to instead access the unprocessed XMP stream, set global control parameter XMP.Parse to false.

During saving, if XMP.Parse is TRUE, ImageGear expects a tree under the XMP tag, and serializes this tree into the output file. If XMP.Parse is FALSE, ImageGear expects a byte array in the XMP tag, and saves it verbatim to the file.

Since XMP standard identifies schema properties using string names, rather than numbers, ImageGear also uses names to identify XMP properties. However, it uses numeric identifiers to differentiate between the kinds of entities, such as Description (schema), Array, Property, Qualifier, etc. All properties have ID = ImGearXMPTagIDs.Property, but differ by their names.

See XMP Non-Image Data Structure section for description of XMP metadata structure in ImageGear.

Example:

Representation of XMP metadata tree.

  • XMP
    • http://ns.adobe.com/xap/1.0/
      • About = ""
      • Namespace
      • Prefix = "xmp"
      • URI = "http://ns.adobe.com/xap/1.0/"
      • Properties
      • xap:Rating
      • Value = 4
      • xap:Identifier
      • Value = "1234.0345.34532.234231"
    • http://purl.org/dc/elements/1.1/
      • Namespace
      • Prefix = "dc"
      • URI = http://purl.org/dc/elements/1.1/
      • Properties
      • dc:subject
      • Bag
      • Item
      • Value = "Test subject 1"
      • Item
    • Value = "Test subject 2"
      • dc:title
      • Alt
      • Item
      • Lang = "x-default"
      • Value = "XMP Support Specification"


Working with ImageGear Color Profile Manager

ImageGear supports color profiles while performs color conversion operations. Detailed information about color processing based on profiles can be found at www.color.org. The following sections "Color Profile Basic Concepts", "ImageGear Color Profile Groups" and "Color Profile Manager API" describe how color profiles can be used with ImageGear.


Color Profile Basic Concepts

The first step in the color profile process is loading raster data from an external location (file, memory, or other) and converting it from some graphical file format to an internal uniform format that is incorporated into the HIGEAR object. After the image is loaded into memory, it is possible to perform different manipulations with it such as image processing transforms, color conversions, displaying, printing, and, finally, an export operation that converts raster data from internal representation into an external graphics file format.

All these steps may requre color conversions. As the color profile is always associated with the appropriate device, there are several virtual devices defined in ImageGear. These "virtual devices" are not real devices, but just abstract things that have associated color spaces and are used to convert color data from one color space to another. There are three virtual devices defined in ImageGear:

  • import devices - used for all import operations. Such import operations as loading a raster image using the format filter assume that imported color data is dependent on the import device. In other words, any format filter that loads color data in a device-dependent format from an external file format assumes that this data is dependent on this specific device.
  • export devices - the same as the import device, but used for export operations.
  • working devices - associated with color data stored in a HIGEAR object.

So we can assume every color conversion is a transition from one device to another. For example, loading an image from an external file using the file format filter (import device) to the internal HIGEAR representation (working device) assumes that the color data has to be "copied" from the import to the working device, i.e. color data has to be converted using color profiles associated with import and working devices.

ImageGear supports different color spaces such as RGB, CMYK and grayscale. So each virtual device may be used with different color spaces. For example, the format filter may load pixels from an external file format in CMYK color space, and it will be necessary to convert color data from the CMYK color space associated with the import device to CMYK or another color space associated with the working device. Each device may have associated color profiles for different color spaces, and they are organized into groups - one group for each device.

You can find the exact definition of the term "color profile" in public specification ICC.1:1998-09 or newer. In general a color profile consists of a set of objects and transforms the specified parameters of color conversion from a standard device-independent color space (PCS) to a necessary device-dependent one. The ImageGear color management system accepts a color profile in the format specified in the ICC.1:1998-09 specification and converts it into internal representation for faster processing.


ImageGear Color Profile Groups

ImageGear allocates 3 color profile groups:

  • ICP (Import Color Profile)
  • ECP (Export Color Profile)
  • WCP (Working Color Profile)

ImageGear allows you to set and get the actual value of a color profile in every group. In spite of the fact that operations with color profiles from different groups are very similar, at a low level there are some differences in how profiles from different groups are processed.

ICP (Import Color Profile)

This group of profiles is used during a filter load operation. In some cases a raster image file contains device-dependent color data such as RGB or CMYK but does not have a color profile associated with it. So this color data can be interpreted in a different manner depending on the color profile used. The ICP profile of appropriate color space should be used in this case. However, if a raster image contains a color profile, this one is used instead of the standard ICP profile.

ECP (Export Color Profile)

This group of profiles is very similar to ICP but is used in the filter export operation. If the raster image file to be exported does not allow you to store the color profile or if it needs to be stored in a specific color space, ECP allows you to provide the profile, and the output image will be converted to that color space.

WCP (Working Color Profile)

This group of color profiles provides information about the default color global parameters used to represent the color data for HIGEAR objects. Those global parameters are used if the image does not have a local color profile associated with it.

When color processing is performed on an image, either a local or global color profile is used. When an image is exported or imported, its pixel data, converted from one color space to another, is described by the WCP associated with the image and corresponding profile from the ECP or ICP group.


Color Profile Manager API

There are public functions implemented in ImageGear that allow you to set and get actual values for each group of color profiles.

To start working with the color profile manager, it is necessary to activate it. By default, the color profile manager is disabled in ImageGear, and all color-related operations are exactly the same as in previous versions (prior to ImageGear ). There is a Boolean global parameter named CPM.ENABLE_PROFILES used to control color profile management.

To activate color profile management, call the ImageGear global control function (see also the section Working with Global Control Parameters:

AT_BOOL     bEnable = TRUE;
IG_gctrl_item_set( "CPM.ENABLE_PROFILES", AM_TID_AT_BOOL,
&bEnable, sizeof(AT_BOOL), NULL );

Another thing related to color management is that additional files are necessary - color profile files to be used as default profiles. By default those files should be located in the same folder as ImageGear and its components are located, and those files should be named as "ig_rgb_profile.icm" and "ig_cmyk_profile.icm" respectively for RGB and CMYK color spaces. Correspondent global parameters CPM.RGB_PROFILE_PATH and CPM.CMYK_PROFILE_PATH exist to specify the full path to default profiles. Their values can be changed using the function IG_gctrl_item_set (), like below in the example:

CHAR     profile[256];
strcpy( profile, "d:\\profile\\rgb_profile.icm" );
IG_gctrl_item_set( "CPM.RGB_PROFILE_PATH",
AM_TID_MAKELP(AM_TID_CHAR), profile, strlen(profile)+1, NULL );

After color profile management is activated, it is possible to use the next functions to set color profiles in global parameters or to a specific image and to get information about currently used profiles.

The function:

IG_cpm_profile_set(AT_MODE nColorSpace, DWORD nProfileGroup,
LPBYTE lpRawData, DWORD dwRawSize, AT_BOOL  bConvert);

allows you to set a new color profile value (lpRawData) to a group specified by the second parameter and associate it with the color space given by the first parameter. lpRawData is a pointer to the memory buffer that contains the color profiles in valid ICC format, and if it is NULL then the default color profile will be set. The last parameter specifies how to process the color data of the images associated with it. If it is TRUE then all images associated with the color profile will be converted to a new color format.

The function:

IG_cpm_image_profile_set(HIGEAR hIGear, LPBYTE lpRawData,
DWORD dwRawSize, AT_BOOL  bConvert)

is a special case of a working profile set operation that associates a given color profile with a single image. In this case the image becomes associated not with a global working profile but with a locally given profile.

The function:

IG_cpm_profile_get(AT_MODE nColorSpace, DWORD nProfileGroup,
LPCHAR	 pStatusStr, UINT nStatusSize, LPUINT lpnStatusLen,
LPDWORD lpnProfileSize, LPBYTE lpProfileData, DWORD
dwProfileDataSize)

can be used to get the current value of a color profile associated with the color space given by the first parameter in the profile group specified by the second parameter. Other parameters return information about the profile along with the profile itself.

To get the color profile information associated with a given image, the function

IG_cpm_image_profile_get(HIGEAR hIGear, LPAT_BOOL lpbIsLocal,
LPAT_MODE lpnColorSpace, LPCHAR  lpStatusStr,UINT  nStatusSize,
LPUINT lpnStatusLen, LPDWORD lpnProfileSize, LPBYTE
lpProfileData,
DWORD  dwProfileDataSize)

can be used. It returns information about the local profile if it is associated with an image, or a global profile otherwise. The second parameter returns TRUE if the local profile is associated or FALSE if it is not.

The function:

IG_cpm_profiles_reset(AT_BOOL bConvert)

is introduced to reset all global profiles to their default values. If bConvert is TRUE, then all images associated with the old previous profiles will be converted to the new ones.

For a detailed description of the color profile functions, please see the "Core Component API Function Reference" chapter.


Working with Global Control Parameters

ImageGear provides you with a set of API functions that allow you to add new global control parameters to your ImageGear application, set new values for already existing global control parameters, and retrieve information about these parameters.

To add a new global parameter as well as to set new values for existing parameters use the function:

IG_gctrl_item_set(LPCHAR ControlID, AT_MODE nValueType, LPVOID
lpValue, DWORD dwValueSize, LPCHAR lpTextInfo)

This function will search for the global parameter specified by the ControlID name (syntax: "<GRPNAME>.<Param name>"), and if it is found will set a new value for it. If it is not found the function will add this new parameter to the global control parameters list. Through the lpTextInfo argument you can also set the text description of the specified global parameter.

To retrieve information about the global control parameter use the functions:

IG_gctrl_item_get(LPCHAR CtrlID, LPAT_MODE lpnValType, LPVOID
lpValue, DWORD dwValSize, LPDWORD lpdwValSize, LPCHAR
lpTextInfo, DWORD dwTextBufSize, LPDWORD lpdwTextInfoSize)
IG_gctrl_item_by_index_get(UINT nIndex, LPCHAR CtrlID, DWORD
dwIDSize, LPAT_MODE lpnValType, LPVOID lpValue, DWORD dwValSize,
LPDWORD lpdwValSize, LPCHAR lpTextInfo, DWORD dwTextBufSize,
LPDWORD lpdwTextInfoSize );

The first function returns the value and the text description of the global control parameter specified by name. The second function returns information about the control parameter specified by its index in the global parameters list. Both functions return FALSE if the specified global parameter is not found.

If you want to know the general amount of global control parameters currently existing in the global parameters list, call the function:

IG_gctrl_item_count_get();

If you need to know an index of the global control parameter in the parameters array, use this function:

IG_gctrl_item_id_get (UINT nIndex, LPCHAR lpCtrlID, UINT
nBufSize);


Working with Color Space Conversion Engine

Color space conversion available for separate raster as well as for entire image. The simplest version may be used to convert entire image. For these purposes IG_image_colorspace_convert () routine must be used. It takes image, new color space identifier and conversion options (optionally) as incoming parameters. It is necessary to note that channels structure of converted image may differ from initial one. The most common changes are quantity of channels and depth for channels. Quantity of channels may be changed because of differences in color space and because of changes in extra channels (controlled by conversion options). Changes in depth usually occur if source channels have different depths. E.g. If source image has 5-6-5 bits per pixel, converted image will have 6-6-6 channel depths.

To provide advanced control for color space conversion, AT_COLORSPACE_CONVERSION_OPTIONS structure has been added. Below is the explanation of each attribute:

  • IsRaw (BOOL) specifies should image content be converted or just changed value of color space id. That is if IsRaw is false, conversion flows in regular way with modification of pixels using color space conversion rules. If parameter is TRUE, in this case only value of attribute that stores color space id is changed without applying conversion to image data. It's necessary to note that raw conversion is not available for all cases. E.g. conversion from IG_COLOR_SPACE_ID_Gy to IG_COLOR_SPACE_ID_RGB with IsRaw = TRUE is not available because of absence of sufficient channels quantity.
  • AlphaBlending is designed to control conversion in case of alpha channel presence. If neither alpha nor premultiplied alpha channel is available in incoming image, this attribute is not used. But if source image has any alpha and new color space has no alpha bit (neither IG_COLOR_SPACE_ID_A nor IG_COLOR_SPACE_ID_P), AlphaBlending.Apply specifies whether or not the image should be blended with AlphaBlending.Background color. That is, if Apply attribute is equal to FALSE, alpha channel will simply be cut. Otherwise image will be blended with background according to alpha channel values.
  • ExtraChannels provides additional control of how extra channels should be transferred. If its Range attribute is equal to FALSE, then all extra channels are transferred from source to converted image (if new color space have IG_COLOR_SPACE_ID_Ex bit. otherwise all extra channels will be cut). Otherwise StartChannel and ChannelCount attributes specify the range of extra channels to be transferred from source to result.
  • ColorConverter represents a custom converter for pixel color part. For now, this is a reserved attribute and must be NULL.

Advanced color space conversion routines allow operating on not only images but particular rasters. It's also possible to supply a custom channels structure to produce conversion data with necessary channel depths.

To start operating conversion, HIGCSCONVERTER instance must be created. Any of IG_colorspace_conversion_create (), IG_colorspace_conversion_create_from_image () or IG_colorspace_conversion_create_from_dib_info () may be used for this purpose. First variation has eight incoming parameters and one output:

  • sourceSpace (enumIGColorSpaceIDs) - identifier of color space from which conversion will occur.
  • sourceSpaceAttribs (const AT_RGBQUAD*) - represents palette entries. Must be specified if source color space is indexed. Otherwise may be NULL.
  • sourceChannelDepths(const AT_INT*) - array of channel depths in source image or raster.
  • sourceChannelCount (AT_INT) - quantity of channels in source image or raster.
  • resultSpace (enumIGColorSpaceIDs) - identifier of color space to which image or raster will be converted.
  • resultChannelDepths (const AT_INT*) - channel depths for result image (raster). May be NULL - in this case, resultChannelDepths will have same values as output of IG_colorspace_conversion_result_channels_build () routine.
  • resultChannelCount (AT_INT) - quantity of channels in result image or raster. Ignored if resultChannelDepths is NULL.
  • options (LPCAT_COLORSPACE_CONVERSION_OPTIONS) - conversion control parameters.

IG_colorspace_conversion_create_from_image () and IG_colorspace_conversion_create_from_dib_info () are designed for convenience and retrieve source attributes (space, palette, channels) from supplied image or DIB information.

Once color space converter was allocated it may be used in any of IG_colorspace_conversion_apply_to_image () and IG_colorspace_conversion_apply_to_raster () routines.

To release conversion, IG_colorspace_conversion_destroy () routine must be used.

It's necessary to note that advanced conversion routines may be used not only for color space conversion, but for channel depth change too (even if IsRaw attribute of conversion options turned on). It's possible to provide desired channels structure and the converter will produce output according to specified structure.

Auxiliary routines of advanced colorspace conversion are IG_colorspace_conversion_result_palette_get () and IG_colorspace_conversion_result_channels_build ().

IG_colorspace_conversion_result_palette_get () is designed to produce palette if new color space is indexed. But note that conversion to IG_COLOR_SPACE_ID_I color space is possible only from IG_COLOR_SPACE_ID_I and IG_COLOR_SPACE_ID_Gy with depth not greater than eight.

IG_colorspace_conversion_result_channels_build () may be used to get default channels structure for converted data. The result of this routine is used by conversion routines if resultChannelDepths parameter has NULL value.


Working with Grayscale Look Up Tables

ImageGear provides a set of functions for working with grayscale LUTs. A grayscale LUT object is represented as an opaque handle: HIGLUT. Use the IG_LUT_... group of functions to create, destroy and access features of grayscale LUTs.

An HIGLUT object can have various input and output depths. Both input and output can be signed or unsigned.

The ImageGear Medical component provides a set of API functions that allows you to build grayscale LUTs according to various DICOM display settings.

Example:

HIGLUT GrayLUT;
AT_INT index;
// Create a LUT
IG_LUT_create(12, TRUE, 8, FALSE, &GrayLUT);
// Fill the LUT with a linear table, transforming 12-bit signed
image to 8-bit unsigned
for (index = -2048; index<2048; index++)
{
    value = (index + 2048) / 16;
    IG_LUT_item_set(GrayLUT, index, value);
}
IG_image_grayscale_LUT_update_from(hIGear, GrayLUT);

ImageGear allows attaching grayscale LUTs to images and to image display settings.

See Also:

Grayscale Look Up Tables

Medical Component Grayscale Look Up Tables


Working with ImageGear Layers

ImageGear allows users to load layered image files and retain image layers for editing. Users can also create new layers, delete existing ones as well as flatten and display the selected layers.

ImageGear currently supports layers for PSD and large PSD (PSB) file formats.

ImageGear provides a set of API for working with layers.

  • HIGLAYER is a handle-based object representing the general attributes of the layer. ImageGear can currently read and write PSD layers. Users can manipulate with generic layer attributes using the IG_layer_... API.
  • HIGIMAGELAYER is a handle-based object representing the image layer and its attrbibutes. Any PSD image can consist of multiple layers. Currently ImageGear can only read, write and edit image layers, t.e. layers represented by a raster image. User can manipulate with image layer attributes using the IG_image_layer_... API.
  • HIGLAYERARRAY is a handle-based object representing the composition of layers. The composition of layers from PSD image is stored in the array of layers attached to the HIGEAR. User can manipulate with composition by creating new layers, editing and deleting the existing ones using the IG_layer_array_... API.
  • HIGEAR also has new IG_image_layers_... API, and there are new IG_gui_layers_... functions in the GUI Component.


About Layers

Layers are used to specify different elements of an image. There are different types of layers. They represent a part of an image either as image pixels or as adjustment instructions. They are stacked on top of each other producing the resulting appearance of the image. ImageGear supports the image layers described in the next section.

Image Layer

An Image Layer is a type of layer containing image pixels that can be applied/blended with another layer. An image from the Image Layer can cover the same area as the resulting image or just a part specifyied by its rectangle. Image Layers have an opacity and other properties associated with it.

Layered Page

An ImageGear layered page is a raster image page containing the composition of layers. Layers associated with an image page can be blended in the order they appear providing the resulting page. The result of such blending represents the final image view and is stored in the page's DIB.


Working with Multi-page Images

Along with a single-page image handle (HIGEAR), ImageGear provides support for multi-page images. The new handle, HMIGEAR, represents an array of single-page images. You can now use ImageGear to:

  • Create and delete an internal representation of a multi-page image (HMIGEAR handle),
  • Open and associate a multi-page image file with an external file,
  • Access and manipulate pages within the multi-page image,
  • Manipulate pages in the external image file, such as loading, saving, swapping and deleting pages,
  • Retrieve information about multi-page images and about associated external files.

The list of functions are divided into two categories:

    • Those that work with external associated multi-page files. These functions appear as IG_mpf_... .
    • Those that deal with multi-page image arrays. These functions begin with IG_mpi_.

For example, the function IG_mpf_page_swap () swaps pages in the external file.


Creating and Deleting a Multi-page Image

An internal representation of a multi-page image is an object of the data type HMIGEAR. This data type encapsulates an array of pages, which are objects of type HIGEAR. All IG_mpi_*** functions are introduced to access and manage this array.

The first step when working with a multi-page image is to allocate and initialize an object of type HMIGEAR. To do this, call the function IG_mpi_create (). This function creates a new multi-page image and sets the page array size to the given number of pages. Pages are numbered from 0 to nPageCount-1, where nPageCount is the current size of the page array and the default page value is NULL.

A multi-page image is an array of pages. It is not necessary that all elements of this array contain valid HIGEAR objects. Some pages may have a NULL value and the function IG_mpi_page_is_valid () can be used to quickly identify whether a page with a given number contains a valid HIGEAR image. The function IG_mpi_page_get () retrieves the value, and the IG_mpi_page_set () function replaces a page value with a given index in the page array of a multi-page image.

The function IG_mpi_page_count_get () returns the current size of a page array and the function IG_mpi_page_count_set () changes then size of the page array.

When a multi-page image is no longer needed, you should delete it using the IG_mpi_page_delete () function. This function deletes all valid pages in the array and frees all memory allocated in the HMIGEAR handle.

See Also:

Getting Information and Sorting Images


Opening and Closing an External Image File

After a multi-page image is created it can be associated with external image. This allows you to set a relationship between a page array of a given multi-page image and pages of a multi-page file. After making that association, but before closing the file, ImageGear stores format-related information in memory. This allows you to perform page manipulation operations, such as page loads, saves, swaps, or deletes - quickly, without scanning all of the format structure of the associated file image. This may be useful if the number of pages in the file is large. It also improves the performance of these operations.

Use the function IG_mpi_file_open () to open or create an external multi-page file and associate it with the multi-page image given by the HMIGEAR object. Use the fourth parameter of this function to specify two open modes. If IG_MP_OPENMODE_READONLY is specified, then the file opened has read-only access. only these operations are allowed. They need not change the file (for example, page loading).

If IG_MP_OPENMODE_READWRITE is used, then the file is opened with read-write access and all supported operations are allowed. Not all format filters support such operations, such as page insert, delete, and swap. The function IG_fltr_info_get () can be used to get information about all implemented features of some particular format.

The third parameter of this function provides the format identifier (one from defined IG_FORMAT_... constants in accucnst.h) and is used only when the file image opens in IG_MP_OPENMODE_READWRITE mode. The file does not exist and it is ignored in other cases. This parameter is used to specify the format of the image to be created.

Example 1:

#include "accucnst.h"
 ...
HMIGEAR hMIGear;        /* HMIGEAR handle returned   */
AT_ERRCOUNT nErrCount;     /* number of errors reported */
 ...
nErrCount = IG_mpi_create(&hMIGear, 0);
if (!nErrCount)
{
nErrCount = IG_mpi_file_open("picture.tif", hMIGear,
IG_FORMAT_UNKNOWN,
IG_MP_OPENMODE_READONLY);
         ...
    nErrCount = IG_mpi_close( hMIGear );
}else
         /* error handling */
 ...

If this function is opened for read-only access, then page array of multi-page images is set to the number of pages that is equal to number of pages in the external file. If the file is opened for read-write access, then the multi-page image is not changed.

Use the function IG_mpi_close () to disassociate a multi-page image from an external file and close the file and free all correspondent resources.


Loading and Saving Pages

After the multi-page image is associated with an external file, it is possible to perform operations such as page loads, saves, swaps, and deletes. If open mode is read-only, then only the page load is allowed. All others will be set to an error.

Use the function IG_mpf_page_load () to load pages from an external file into a multi-page image. The second argument of the function is a zero-based index of the first page for loading. The third argument specifies the number of pages to load starting from this index. The order and location of the loaded pages in the page array is the same as in the external file. Therefore, if the file pages start from nFirstIndex, then it loads into the page array starting with nFirstIndex. If necessary, the page arrays are expanded to fit all of the requested number of pages. If, while loading, some elements of the page array contains a valid HIGEAR image, then it is not deleted. It is then assigned a new value of the image loaded from the file.

Use the function IG_mpf_page_save () to save pages from a multi-page image into an external file. The second and third arguments are the same and have the same meaning as the second and third arguments for the load function. The fourth argument specifies the compression method (for example, IG_COMPRESSION_JPEG or IG_COMPRESSION_LZW for TIFF image) and applies to all pages from the given range. The last parameter of this function specifies how to save the pages into a file. There are two modes are possible

  • IG_MPF_SAVE_INSERT
  • IG_MPF_SAVE_REPLACE

The first mode insert pages into the file at the location specified by second parameter, which is demonstrated in the following picture:

IG_MPF_SAVE_INSERT:

The second mode replaces pages starting from the index specified by the second parameter:

IG_MPF_SAVE_REPLACE case:

Example 2:

To load pages 2 through 5 from the file "image1.tif" and insert them into file "image2.tif," the program is:

/*...*/
HMIGEAR 		hMIGear;
AT_ERRCOUNT		nErrCount;
UINT		nStartPage;
UINT		nCount;
nErrCount = IG_mpi_create(&hMIGear, 0);
if (!nErrCount)
{
nErrCount = IG_mpi_file_open( "picture1.tif", hMIGear,
IG_FORMAT_UNKNOWN,
IG_MP_OPEN_READ );
        nStartPage = 2;
        nCount = 4;
        nErrCount = IG_mpf_page_load( hMIGear, nStartPage, nCount
);
}
if (!nErrCount)
{
        nErrCount = IG_mpi_close( hMIGear );
        if (!nErrCount)
            nErrCount = IG_mpi_file_open( "picture2.tif",
hMIGear, IG_FORMAT_UNKNOWN, IG_MP_OPEN_READWRITE );
    if (!nErrCount)
    nErrCount = IG_mpf_page_save( hMIGear, nStartPage, nCount,
IG_COMPRESSION_JPEG, IG_MPF_SAVE_INSERT );
}
if (nErrCount)
{
        /* error handling */
#include "accucnst.h"
}
NOTE: If a page from the pages to save is not a valid HIGEAR image, then this page is ignored during the save operation.
NOTE: IG_MPF_SAVE_REPLACE mode is acceptable for filters that support the page deletion operation. This information can be obtained using the function IG_fltr_info_get() and it should return the IG_FLTR_PAGEDELETESUPPORT flag, which set in the dwInfoFlags parameters.


Using Other Functions that Work with Pages

When an external file is opened in read-write mode, an operation such as page delete and page swap is possible. Not all filters support it. It is necessary to check with the function IG_fltr_info_get () for flags IG_FLTR_PAGEDELETESUPPORT and IG_FLTR_PAGESWAPSUPPORT in the lpdwInfoFlags parameter.

IG_mpf_page_swap () is used to reorder pages in the external file. The second and third arguments of this function are zero-based indexes of the pages to be swapped.

The IG_mpf_page_delete () function deletes the specified pages from the external file. The index of the first deleted page is passed through the second argument and number of pages to be deleted is passed through the third argument.

The example below shows how to reorder pages in the multi-page file.

Example 3:

AT_ERRCODE mpfPageReorder(
    HMIGEAR hMIGear
)
{
    UINT nPageCount;
    AT_MODE nFormatID;
    AT_ERRCOUNT nErrCnt;
    DWORD dwInfoFlags;
    UINT i;
IG_mpf_info_get( hMIGear, &nFormatID );
    if( nFormatID==IG_FORMAT_UNKNOWN )
    return	-1; /* file is not associated */
    IG_fltr_info_get( nFormatID, &dwInfoFlags, NULL, 0, NULL, 0,
NULL, 0 );
    if( (dwInfoFlags&IG_FLTR_PAGESWAPSUPPORT)==0 )
    return	-1;/* format filter does not support the page swap
operation */

    nErrCnt = IG_mpf_page_count_get( hMIGear, &nPageCount );
    for( i = 0; (i < nPageCount/2) && (nErrCnt==0); i++ )
nErrCnt = IG_mpf_page_swap( hMIGear, i, nPageCount - i - 1 );
    return -nErrCnt;
}

The example below demonstrates how to perform this operation on a multi-page image located in memory:

Example 4:

AT_ERRCODE mpiPageReorder(
HMIGEAR hMIGear

{
HIGEAR hPage1, hPage2;
UINT i, nPageCount;
AT_ERRCOUNT  nErrCnt = 0;
nErrCnt = IG_mpi_page_count_get( hMIGear, &nPageCount );

for( i = 0; (i<nPageCount/2) && (nErrCnt==0); i++ )
    {
    nErrCnt = IG_mpi_page_get( hMIGear, i, &hPage1 );
    nErrCnt += IG_mpi_page_get( hMIGear, nPageCount - i - 1,
&hPage2 );
    nErrCnt += IG_mpi_page_set( hMIGear, i, hPage2 );
    nErrCnt += IG_mpi_page_set( hMIGear, nPageCount - i - 1,
hPage1 );
}
return -nErrCnt;}
See Also:

IG_fltr_pageswap_file ()

IG_fltr_pagedelete_file ()

Getting Information and Sorting Images


Using the Multi-page Image Callback Function

Multi-page image operations, implemented by the above functions, support a notification mechanism that allows you to track information about when and how the multi-page image or associated file was changed. This can be done using the functions IG_mpi_CB_set (), IG_mpi_CB_get (), IG_mpi_CB_reset (), and IG_mpi_CB_reset_all ().

Use the function IG_mpi_CB_set(hMIGear, lpPrivate, lpfnUpdate, lpdwCBID) to associate new callback data with the given hMIGear handle. The second parameter, lpPrivate, is any LPVOID pointer that the callback function lpfnUpdate receives through the second parameter. lpfnUpdate is a pointer to the function that implements the following interface:

typedef  VOID (LPACCUAPI LPFNIG_MPCB_UPDATE)(
   DWORD dwCBID,
   LPVOID lpPrivate,
   AT_MODE nMode,
   UINT nPage,
   UINT nCount
   );

The last parameter, lpdwCBID, is a pointer to that application which receives a unique DWORD identifier for the associated callback data. This ID is used to delete callback data using the function IG_mpi_CB_reset() and retrieves callback data using the function IG_mpi_CB_get(). After the IG_mpi_CB_set() function is executed, ImageGear calls the lpfnUpdate function every time a multi-page image is changed. This allows the application to react accordingly, and updates the related objects such as GUI windows. As soon as this callback function is called from the context of the thread that performed the operation, its execution is blocked until the callback function is complete. From one side, this can be used for synchronization; but from another side, it should be used carefully so that it does not affect performance.

By calling the callback function, ImageGear passes the type of changes through the nMode parameter. The sense of nPage and nCount parameters depend upon nMode. The following table list all possible cases:

nMode
nPage
nCount
Description
IG_MPCBMODE_MPI_DELETE
Not used
Not used
Notifies the application that a multi-page image is going to be deleted.
IG_MPCBMODE_MPI_
ASSOCIATED
Not used
Not used
Notifies the application that a multi-page image is just associated with external file.
IG_MPCBMODE_MPI_CLOSE
No used
Not used
Notifies the application that a multi-page image is going to close associated external file
IG_MPCBMODE_MPI_CB_SET
Not used
Not used
Notifies the application that this callback data is just set. This notification receives only the callback function that just has been set.
IG_MPCBMODE_MPI_CB_
RESET
Not used
Not used
Notifies the application that this callback data is to be reset.
IG_MPCBMODE_MPI_
PAGEINSERTED
index of where new pages starts
number of new pages inserted
Notifies the application that new pages are inserted into the multi-page image.
IG_MPCBMODE_MPI_
PAGEUPDATED
index of the first updated page
number of updated pages starting from nPage
The application updated pages in the multi-page image
IG_MPCBMODE_MPI_
PAGEDELETED
first deleted page index was have
number of deleted pages
The application deleted pages in the multi-page image.
IG_MPCBMODE_MPF_
PAGEINSERTED
index of where new pages starts
number of new pages inserted
The application inserted new pages into external file image.
IG_MPCBMODE_MPF_
PAGEUPDATED
index of the first updated page
number of updated pages starting from nPage
The application updated pages in the associated external multi-page image file.
IG_MPCBMODE_MPF_
PAGEDELETED
Index of the first deleted page
number of deleted pages
The application deleted pages in the associated external multi-page image file

When the application does not need to receive any more information from the callback data, it should call the function IG_mpi_CB_reset (hMIGear, dwCBID), where dwCBID is a unique identifier of the association returned by IG_mpi_CB_set ().

The function IG_mpi_CB_reset_all () removes all callback data associated with all previously allocated identifiers.

See Also:

Processing of non-image data through filter callback functions

Working with ImageGear Callback Functions


Working with ImageGear GUI Functions

ImageGear's Graphical User Interface functions provide you with the means for readily implementing a number of sophisticated graphical user interface features in your applications, which normally would require tedious and time consuming development effort. Though the entire ImageGear toolkit is geared toward providing a graphical interface as well as image handling and image processing support, the set of IG_GUI_ ...() functions, described in this section, go a step further in the areas of GUI pan, magnify, thumbnail, and GUI palette editing.

Although these functions do most of the work for you, the flexible argument lists and the availability of callback functions give you control when you need it. You can, for example, control when a palette might actually be changed, or when a directory search filter is to be provided. You can also control the GUI window dimensions and positions.

This discussion includes these sections:

  • The GUI Pan Window
  • The GUI Magnify Window
  • GUI Select Track Mouse
  • The GUI Palette Window
  • The GUI Thumbnail Window

You may want to refer to them as they become relevant to your application. Descriptions of the IG_GUI_ ...() functions and the LPFNIG_GUI ... callback function types are provided in Chapter "Core Component API Function Reference". You can run the GUI sample to view these features. You can also refer to and use the source code from the samples' source modules.


The GUI Pan Window

To create a GUI pan window invoke IG_GUI_pan_window_create_ex (). This function creates a new window on your screen in which the HIGEAR image you name in the call will be displayed in its entirety. In this call you also name a second window, called the parent window.

As the user of your application moves the mouse around in the pan window, you can have ImageGear pan (slide) the image in the parent window, such that you see (in the parent window) the portion of the image selected by the mouse's position in the pan window. Here is how to do it:

  • First, make the window that is designated to be the parent window a GUI image window. You do this by calling IG_GUI_window_associate () if this window already exists, or by calling IG_GUI_pan_window_create_ex () to create the parent window.
  • Next, call IG_GUI_pan_window_create_ex () to create the pan window and designate its parent. You should name the same HIGEAR image when creating the pan window that is in its parent window. In the pan window, you automatically get the whole image. However, the parent window is under your control. You can, for example, define its device rectangle (e.g., zoom it) to obtain the desired scaling. Generally, for large images the parent window's device rectangle should be significantly larger than the client rectangle so that only a portion of the image appears in the client window at any given moment.
  • To handle the mouse movement, you would include a call to function IG_GUI_pan_track_mouse () in your Windows window-message-handling routine when handling a WM_LBUTTONDOWN message.
NOTE: ImageGear does not support tracking of the right mouse button, only the left.

Your IG_GUI_pan_track_mouse () call causes ImageGear to automatically reposition the image in the parent window.

NOTE: If your parent window is not a GUI image window (that is, if you did not call IG_GUI_window_associate() or IG_GUI_window_create() for this window), then your IG_GUI_pan_track_mouse() call generates Windows WM_PAINT and WM_... scroll messages that can be used to slide the image in the parent window. However, ImageGear does not intercept these messages and handle them automatically. Your application must detect the messages and execute calls to cause the scrolling or other effects you want.

When your application uses a pan window, you can use the Windows call DestroyWindow() to remove it. You can dissociate the parent window from GUI by calling IG_GUI_window_associate () with BOOL argument bAssociate = FALSE. If you call function IG_GUI_window_CB_register (), whenever a GUI image window is destroyed, your LPFNIG_GUIWINDESTROY callback function is called.

An additional GUI pan function, IG_GUI_pan_update (), is provided so that you can tell ImageGear to update (refresh) the pan window if the HIGEAR image that is being displayed in it has changed in memory.


The GUI Magnify Window

The GUI Magnify interface is similar to the GUI pan. A similarly named set of functions is provided, namely: IG_GUI_magnify_window_create (), IG_GUI_magnify_update (), and IG_GUI_magnify_track_mouse (). You use these functions in the same way that you use the GUI pan functions. The difference is in what the user sees.

The magnify window is first created using IG_GUI_magnify_window_create (). Thereafter, whenever the user clicks or drags the mouse pointer in the image window, your application can issue a call to IG_GUI_magnify_track_mouse () to cause that portion of the image to be shown magnified in the magnify window. A scroll bar is provided in the magnify window. When the user drags this magnify window scroll bar, ImageGear automatically changes the magnification factor. Your application can refresh the magnify window, if needed, by calling IG_GUI_magnify_update ().


GUI Select Track Mouse

ImageGear provides the function IG_GUI_select_track_mouse () to assist you when you want to let your user select a rectangular portion of an image, or for some other purpose draw or delineate a rectangle in an image window. As with the other IG_GUI_ ..._track_mouse() functions, the call to this function is placed in a Windows message handling segment for message WM_LBUTTONDOWN.

NOTE: You cannot use IG_GUI_..._track_mouse() with a WM_RBUTTONDOWN message. ImageGear only responds to left mouse button clicks.

Issue the call, giving the (x, y) coordinates at which the mouse button was depressed, and ImageGear will track the mouse as it is moved with the button held down. When the mouse button is released, the opposite corner of a rectangle is thus specified, and ImageGear invokes your LPFNIG_GUISELECT callback function, passing it the coordinates of the rectangle which the user delineated. Your callback function (declared in the call to IG_GUI_select_track_mouse ()) may draw the specified rectangle, or zoom the image to it, or do anything else with this information that you want your application to do. This function is independent of the other GUI groups such as Pan, Magnify, etc., and can be used in any window.

If the HIGEAR image's aspect ratio setting is IG_DSPL_ASPECT_FIXED (that is, if aspect ratio preservation is in effect for the image), then the rectangle which the user draws out will automatically be aspect-ratio corrected.


The GUI Palette Window

GUI Palette support provides a convenient way to permit a user to edit a palette by making mouse selections without requiring your application to make calls to the IG_palette_ ...() functions in order to update the palette. You create a GUI palette window by making a call to IG_GUI_palette_window_create (), and ImageGear creates the window, displays your named HIGEAR image's palette in it, and tracks the mouse as the user makes selections to modify the palette.

Any time the user makes an edit, your LPFNIG_GUIPALETTE callback function is called, if you've declared one by calling IG_GUI_palette_CB_register (). Your callback function is passed arguments telling which palette entry the user tried to change, and what the new RGB color is. Your function will return TRUE or FALSE to tell ImageGear to go ahead with the change, or deny the attempt. If TRUE, ImageGear modifies the image's DIB palette and reflects the color change in the palette window display as well.

Your application can call IG_GUI_palette_update () to update (refresh) the palette window, if your application has changed the image's palette while the palette window is on the screen.

When you are done using a palette window, your application can issue a Windows DestroyWindow() call to remove the palette window.


The GUI Thumbnail Window

A GUI thumbnail window is a window in which thumbnails (miniature images) are displayed. ImageGear's thumbnail window support functions include:

  • Functions to create a thumbnail window,
  • Add thumbnails of individual image files or groups of image files that you name
  • Sort the thumbnails in the window according to any scheme that you specify.
  • A function that lets you set many attributes for displaying the thumbnails, and
  • A function to tell you when the user has clicked the mouse on a thumbnail.

Creating a thumbnail window is just like creating any other GUI window. You call IG_GUI_thumbnail_window_create_ex () and specify the dimensions and position for the new thumbnail window.

Having done this, you can have ImageGear add thumbnails to the window by calling either IG_GUI_thumbnail_file_append (), to add a thumbnail image of a single file, or IG_GUI_thumbnail_dir_append (), to add from a directory a group of thumbnails matching a "filter" or "wildcard" string such as "*.BMP;*.JPG."

You can also drag files from Windows Explorer, into the GUI thumbnail window.

NOTE: When you add a thumbnail of a multi-page file, only a thumbnail of the first page of the file is displayed, unless you use IG_GUI_thumbnail_attribute_set() to show all of the pages. If only the first page is displayed, the filename that appears under the thumbnail is accompanied by an asterisk.

There are a number of attributes that affect the way the thumbnails themselves are displayed. These are all modifiable using the function IG_GUI_thumbnail_attribute_set ().

To learn when a user has clicked the mouse on a thumbnail, and which thumbnail it was, use IG_GUI_thumbnail_CB_register () to register a callback function of type LPFNIG_GUITHUMBSELECT. Your callback function is called with a far pointer to the filename string that corresponds to the thumbnail image, and a pointer to the thumbnail image's DIB header.

You can have ImageGear sort thumbnails that are currently being displayed in the thumbnail window. Call IG_GUI_thumbnail_sort (), providing the address of a callback function of type LPFNIG_GUITHUMBCOMP. This callback function will then be called successively for each pair of thumbnails, with pointers to both filenames and both DIB headers. Your LPFNIG_GUITHUMBCOMP function can compare the two according to any scheme you choose, returning -1, 0, or +1 to tell ImageGear that the first of the pair should be placed before, equal, or after the second, respectively. ImageGear will keep calling this function with pairs until all the thumbnails are sorted (ImageGear automatically adjusts their positions in the thumbnail window.).

Call function IG_GUI_thumbnail_update () if something being displayed in the thumbnail window has changed in memory and you want ImageGear to refresh the thumbnail window display.

Refer to Chapter "Core Component API Function Reference" , for descriptions of the IG_GUI_ ...() functions and the LPFNIG_GUI ... callback types as well as for the calling sequences of ImageGear's Graphical User Interface support functions.


Working with ImageGear GUI Dialogs

The ImageGear GUI windows described above allow you to perform many imaging specific operations. However, you often need to modify standard Windows dialogs to be imaging specific or create custom dialogs to perform imaging specific operation. To address such needs, ImageGear provides an additional set of GUI windows, dialogs, and utility functions that are available in the separate DLL - IGGui_PD.dll. It is based solely on the ImageGear public API and best of all source code for IGGui_PD.dll is freely distributed with the product, you can either use IGGui_PD.dll `as is', customize it for your own needs, or use some code fragments of it in your own applications. Dialogs are provided for file opening and saving, color resolution, image processing or filtering, and effects. These dialogs allow you to quickly and easily enable your application to gather input from end users for the parameters required by the various ImageGear functions. These dialogs can also be used to automatically process the image based on end user input (reducing the amount of code you have to write).

For example, this line of code displays the loaded file info dialog:

case ID_FILE_FILEINFO:
/* pop up the file info dialog box */
    lpFile = (LPSTR)GetProp(hWnd, szPropFileName);
        if(lpFile)
        {
        IG_gui_file_info_dlg (hWnd, lpFile, 0);
        }
    break;

Below you can see this file info GUI window itself:

If you use the GUI Component in your ImageGear application, then it is necessary to include this file with your distribution when you deploy your application. For more detailed information about every ImageGear GUI see the Chapter "GUI Component API Function Reference".


Working with Image Utility Functions

ImageGear's image utility family of functions provides you with the capabilities to create, import, and export images in either DIB or DDB format, and to obtain information about any image for which you have a HIGEAR handle. You can also obtain information about image files stored on mass storage devices, such as the file format type, compression, width, height, bits per pixel, or number of pages if a multi-page file.

A few special purpose image utility functions tell you whether a HIGEAR variable contains a valid image handle, and whether an image is grayscale. And there are six functions to help you read and write palettes, either whole or one entry at a time, and save them to disk. There's also a function that lets you set special control options that alter the operation of ImageGear's file format read-write filters during file operations.

One additional important image utility function sets an image's "image rectangle", which determines the portion of the image to be displayed, printed, or saved during display, print, and save operations. Refer to "Core Component API Function Reference" Chapter for detailed calling sequences and further notes on these functions.


Creating DIBs and DDBs

  • To create a new HIGEAR with an empty DIB, use the following code:
IG_image_create_DIB_ex ( nWidth, nHeight, nBpp, lCompression,
lpDIB = NULL, &hIGear );

Later, you could use the IG_DIB_...() for direct pixel access functions, or an IG_IP_blend_ ...() function to create an image bitmap. You can use the IG_palette_ ...() functions (described later in this section) to add a palette to the DIB.

  • To create a new HIGEAR with a DIB filled by copying an existing DIB, use the same function as demonstrated above, but call it like this:
IG_image_create_DIB_ex ( 0, 0, 0, 0, lpDIB, &hIGear );

In this example, lpDIB is a pointer to the existing DIB to copy, and the first four arguments are ignored. Width, height, bits per pixel, and "compression" will be copied from the existing DIB, along with its image bitmap and palette.

  • To give a HIGEAR handle to an existing DIB, use the import function:
IG_image_DIB_import ( lpDIB, &hIGear );

This call returns you to the HIGEAR handle assigned to your DIB.

  • To create a HIGEAR whose image is a copy of the image in an existing DDB:
IG_dspl_DDB_import ( hBitmap, hPalette, &hIGear);

In this call, you provide the DDB's HBITMAP handle, and optionally the handle of a palette. ImageGear creates a DIB for you and returns the new DIB's HIGEAR handle.

  • To create a DDB whose image is a copy of the image in an existing HIGEAR:
IG_dspl_DDB_create( hIGear, IG_GRP_DEFAULT, hDC, nWidth,
nHeight, TRUE, &hBitmap, &hPalette )

Provide the HIGEAR handle and the width and height for your DDB as well as the addresses of an HBITMAP and an HPALETTE variable to receive the DDB and palette handles. Because this function belongs to the display group, there should be a group identifier, nGripID, to specify where to get the options needed to complete this operation. hDC is necessary to specify the color format output to which the DDB should be compatible.


Deleting DIBs and DDBs

  • To delete the HIGEAR, but keep the DIB in existence (and obtain its address):
IG_image_DIB_export( hIGear, lpDIB, DIBSize, &Options);

The DIB's address is returned in your LPAT_DIB variable lpDIB.

  • To delete the HIGEAR and the DIB, but produce a copy of the image in DDB format:
IG_dspl_DDB_create( hIGear, IG_GRP_DEFAULT, hDC, nWidth,
nHeight, TRUE, &hBitmap, &hPalette )

Provide the HIGEAR handle of the image to delete, and provide the addresses of the HBITMAP and HPALETTE variables to receive the handles for the created DDB and palette.

  • To delete a HIGEAR, including the DIB, when you are entirely done using use the following call:
IG_image_delete ( hIGear );

Note that in all the above cases, ImageGear will not release memory that it did not allocate. For example, assume your application has allocated memory, created a DIB, and subsequently used an IG_image_DIB_import () call to give this DIB a HIGEAR handle. In this case, a later call to IG_image_delete() will delete the HIGEAR structure but will not free the DIB's memory. The owner of the DIB's memory (in this case, your application) would issue a Windows DeleteObject() call to free this memory.


Reading and Writing Palettes

There are six image utility functions that read and write palettes in memory, or load and save them between memory and disk. To transfer a palette between your own memory area and a HIGEAR image's DIB (that is, to get or set the DIB palette), use:

AT_RGBQUAD palette[256];
IG_palette_get ( hIGear, palette );
IG_palette_set ( hIGear, palette );

In the above calls, lpPalette should point to the first of an array of AT_RGBQUAD structures, one structure per palette entry.

If instead you want to move just one entry to or from the DIB palette:

AT_RGB    rgbPaletteColor;
IG_palette_entry_get ( hIGear, &rgbPaletteColor, nIndex );
IG_palette_entry_set ( hIGear, &rgbPaletteColor, nIndex );

In the single entry calls, you supply a pointer to a single structure of type AT_RGB. The third argument has a value between 0 and 255, specifying which palette entry to get or set (Remember that an AT_RGBQUAD structure consists of 4 bytes ordered Blue-Green-Red-Unused(0), while an AT_RGB struct consists of 3 bytes ordered Blue-Green-Red.).

To load and save palettes between memory and disk, use the functions:

IG_palette_load ("filename", palette, nEntries, bOrder,
lpFileType);
IG_palette_save ("filename", palette, nEntries, lpFileType);

See the descriptions of the above functions in "Core Component API Function Reference", for details on specifying the arguments.


Getting Information about a HIGEAR Image

To find out if a HIGEAR variable currently holds a valid handle:

if ( IG_image_is_valid(hIGear) )  { ... }

Similarly, to find out if it is a grayscale image:

if ( IG_image_is_gray(hIGear, &bItsGray) )  { ... }

To obtain the width, height, and bits per pixel of an image, or the DIB compression type, use (respectively):

AT_DIMENSION nWidth, nHeight;
UINT nBpp;
IG_image_dimensions_get ( hIGear, &nWidth, &nHeight, &nBpp );
DWORD nCompression;
IG_image_compression_type_get ( hIGear, &nCompression );
NOTE: Be careful to declare the types as AT_DIMENSION and DWORD where shown above (rather than INT or UINT). On some development platforms, AT_DIMENSION and DWORD are not the same size as INT.

And to learn the position and size of an image's image rectangle, use IG_dspl_layout_get () API.

NOTE: Here also be careful to use the correct type: AT_RECT, not Windows structure type RECT, whose fields may be a different length.

To set the image rectangle, use the function IG_dspl_layout_set (). Examples are provided in the sections Displaying Images and Saving Images .

If you need to access a DIB directly, refer to the descriptions of function IG_image_DIB_palette_pntr_get ()in "Core Component API Function Reference".


Obtaining Information about Files

Three sets of image utility functions obtain information about files. The IG_info_get ...() functions (namely: IG_info_get_ex (), IG_info_get_FD_ex (), and IG_info_get_mem_ex ()) return to you the file format type and file compression type, and the DIB header that would be created if you loaded the file (giving you width, height, and bits per pixel, for example).

The similarly named IG_page_count_get ...() and IG_tile_count_get ...() functions tell you how many pages a file has if it is a multi-page file, and how a given page is tiled if the file format supports tiled pages. See the descriptions of these functions in Core Component API Function Reference. For more discussion about tiles, see also the section entitled Working with Tiled Images.

For all three sets of functions use:

  • IG_ ...get() form (such as IG_page_count_get()) if you are referencing the file by its filename.
  • IG_ ...get_FD() form if the file is already open and you are referencing it by its File Descriptor handle.
  • IG_ ...get_mem() form if the file image is in memory and you are referencing it by its memory address.
See Also:

Getting Information and Sorting Images


Working with Library Utility Functions

ImageGear's small group of functions, called "library utility" functions, are provided so that you can conveniently obtain the ImageGear version and function status. The functions in this group have names beginning with IG_version_ ...() , IG_error_ ...(), IG_err_ ...() and IG_errmngr_ ...().

For instructions on how to use these functions, see the section entitled Detecting and Handling Errors . Detailed information on these functions is provided in Core Component API Function Reference.


Detecting and Handling Errors

Handling error conditions detected inside ImageGear functions is easy, because ImageGear functions handle all errors in a single, uniform way. Even low-level ImageGear functions that you can not call directly, handle errors in this same way.

When an error condition is detected by an ImageGear function, the function places an error code indicating specifically what happened, along with information telling where the error occurred, in an internal memory area called the ImageGear error stack. This error stack remains available to your application as it executes, so you can inspect and treat the errors where (in your program code) you wish, and as you wish. After placing the error or errors on the error stack, the ImageGear function returns to its caller (returning the count of errors now on the stack, if the function's return-type is AT_ERRCOUNT).

More than one error may be placed on the error stack as a result of a single ImageGear function call. This is because an ImageGear function that you call will often call lower level ImageGear functions (not directly callable by your application). Each such lower level function may itself place an error onto the error stack before returning to its caller. Upon return to your application, there may be several errors on the stack. Note that in such a case, the lowest level function's error was placed on the stack first, and the highest level function (the one that your application called directly) placed its error on the stack last, just before returning to your application because it could not proceed (due to the error).

ImageGear provides four basic functions for accessing the error stack. They are:

IG_error_clear ()
Clear the error stack
IG_error_check ()
Obtain the number of errors on the error stack
IG_error_get ()
Get a specified error from the error stack
IG_error_set ()
Place an error on the error stack. This function can be useful for the forced termination of loading or saving procedures if you have defined your own callback routines.

The example below shows how you may use some of the above functions to display in a Message Window on your screen every error that is on the ImageGear error stack. Refer to descriptions of these functions in Chapter "Core Component API Function Reference" for thorough explanations of their arguments.

HIGEAR hImage; /* Will hold handle of image loaded below */
INT i; /* Will hold Loop Index and Error Index */
INT iLineNumber; /* Will hold returned Line Number */
BYTEszFileName[30]; /* Will hold ret'd module name, <= 29 chars
*/
INT cbFileNameSize; /* Will hold size of szFileName array */
AT_ERRCODE  iCode; /* Will hold returned ImageGear Error Code */
AT_ERRCOUNT  nErrcount; /* Will hold count of errors on error
stack  */
BYTE szBuf[60]; /* Will hold zero-terminated string returned by
wsprintf() below */
cbFileNameSize = 30; /* Size of module-name array */
IG_load_file ("picture.bmp", &hImage ); /* Try to load image */
nErrcount = IG_error_check(); /* Get number of errors on stack
*/
for ( i = 0;  i < nErrcount;  i++ )  /* For each error on stack:
*/
    {
    /* Get Module Name, Line Number, and Error Code:
*
    IG_error_get ( i, (LPSTR) &szFileName, cbFileNameSize,
            &iLineNumber, (LPAT_ERRCODE) &iCode, NULL, NULL );
/* Format error message in szBuf: */
    wsprintf ( szBuf, "Error %d in Module %s at Line %d", iCode,
              szFileName, iLineNumber );
/* Display error message in a Message Box, with heading
"Error":*/
    MessageBox ( NULL, szBuf, "Error", MB_OK );
    }
IG_error_clear();/* Done getting errors, clear the error stack
*/

This example displays the error number (iCode) in the Message Box. Text describing the nature of the error, and the ImageGear Error Name (such as IGE_OUT_OF_MEMORY) can be found in file GEARERRS.H.

It should be noted that each ImageGear function, excluding all IG_dspl_...() functions, clears the error stack upon entry. Therefore, after an ImageGear function call you should check the stack prior to your next ImageGear function call. Also, many ImageGear functions return as their value the value of IG_error_check (). So it is usually not necessary to call IG_error_check(). For example, the load-file and error-check statements in the above example could have been combined into one:

nErrcount = IG_load_file ( "picture.bmp", &hImage );
/* nErrcount now = number of errors place on stack during load
attempt */
for ( i = 0;  i < nErrcount;  i++ )
     ...

Also there is a bunch of ImageGear functions that may help you with the error stack processing:

IG_err_callback_get

IG_err_callback_set ()

IG_err_count_get ()

IG_err_error_check ()

IG_err_error_set ()

IG_err_error_get ()

IG_errmngr_callback_get ()

IG_errmngr_callback_set ()

IG_err_record_get ()

IG_err_stack_clear ()


Checking the ImageGear Version

ImageGear provides two IG_version_ ...() functions.

The first of these functions gives you update information:

INT	 nVersionMajor;
INT	 nVersionMinor;
INT	 nVersionUpdate;
IG_version_numbers ( &nVersionMajor, &nVersionMinor,
&nVersionUpdate);

The second IG_version_ ...() function allows you to obtain the compilation date of the ImageGear that you are using:

LPSTR		lpszCompileDate;
lpszCompileDate  =  IG_version_compile_date ( void );

Upon return from the above, lpszCompileDate will contain a pointer to a string of the form "Mmm dd yyyy," such as "May 09 2001."


Working with ImageGear Callback Functions

ImageGear's strategy of providing callback function support for load, save, print, and other operations is to permit your application to help control these processes. Callback functions are functions that you write the code for, and whose names you provide to ImageGear. ImageGear will call them at appropriate breakpoints in an operation (such as after each raster line has been processed), at which time your function may modify image data, display status information, or perform other auxiliary operations you wish before returning control to ImageGear.

This section discusses how to declare, code, and invoke an ImageGear callback function; how to register an ImageGear callback function; and how to work with the status bar and tag callback functions.

Callbacks are actually function types (or templates) where you can include your own code to carry out extra operations during normal ImageGear file processing. Callbacks can be passed data, return data, or both. All callback type names begin with the prefix "LPFNIG" which stands for "Long Pointer to a FuNction of ImageGear". Due to this unusual prefix, their descriptions can easily be found in the section Core Component Callback Functions Reference in Chapter "Core Component API Function Reference".

Some callback functions return a Boolean value to ImageGear, indicating whether you want ImageGear to continue the operation, disregard the instructions in the callback, or abort an operation. Most callbacks are VOID, exchanging their information through their arguments.

How a callback function is coded, declared to ImageGear, and invoked by ImageGear, is illustrated by the simple examples below in which an application calls function IG_load_file_display () to load and then display an image. IG_load_file_display() will automatically call your callback of type LPFNIG_LOAD_DISP.

The following example shows a call to register a display callback and the callback itself:

VOID ACCUAPI  my_set_attributes_func
  (
      LPVOID  lpPrivateData, /* Ptr to private data area      */
      HIGEAR  hIGear         /* Handle of loaded image         */
   )
{
/* This callback function disables centering of the image: */
IG_dspl_layout_set( hIGear, IG_GRP_DEFAULT, IG_DSPL_ALIGN_MODE,
NULL, NULL, >NULL, 0,
IG_DSPL_ALIGN_X_LEFT|IG_DSPL_ALIGN_Y_TOP, 0, 0.0 );
return;
}

In response to the above call ImageGear loads the image, creates a DIB and a HIGEAR data structure, and then calls your callback function. When your callback function returns, ImageGear will display the image, and then return to the statement following IG_load_file_display ().

Note that your module containing the IG_load_file_display() should contain in its initial definitions a function prototype or declaration for the callback function. There are two ways that the callback can be declared:

  1. By prototype:
VOID ACCUAPI  my_set_attributes_func ( LPVOID lpPrivate, HIGEAR
hIGear );
  1. By declaration:
LPFNIG_LOAD_DISP my_set_attributes_func;
NOTE: If you do not write code for a callback function type that is part of a normal API call, such as IG_load_file_display(), you can just pass in a NULL for the callback parameter.


Private Data Use in Callback Functions

If you look at the argument lists of the ImageGear callback function types you will notice that many of them have an argument for holding private data. This can be used for anything you like. In some cases, the function which calls or registers the callback will also contain a parameter for private data which will be directly passed to your callback. IG_load_file_display () fits this description. In the following example, you will see how the fourth argument of this function can be used to pass private data to the callback for additional flexibility:

LPFNIG_LOAD_DISP   my_set_attributes_func;
HIGEAR         hIGear;
HDC            hDC;
DWORD          dwGroupID
HWND           hWnd
AT_ERRCOUNT    nErrcount;
AT_MODE        nAlignMode;     /* align mode  */
/* Instead of NULL, give the address where private data
(&bCenter) begins:*/
nErrcount = IG_load_file_display ( "picture.bmp", hDC,
dwGroupID, hWnd,
               my_set_attributes_func, &nAlignMode, &hIGear );
/* And the corresponding callback function:  */
VOID ACCUAPI  my_set_attributes_func (LPVOID lpPrivateData,
HIGEAR hIGear)
{
/* Instead of FALSE, give the BOOL value located at the start of
the private data area: */
IG_dspl_layout_set( hIGear, IG_GRP_DEFAULT, IG_DSPL_ALIGN_MODE,
NULL, NULL, NULL, 0, (AT_MODE) *lpPrivateData, 0, 0, 0 );
>return;
}
TIP: You can pass any amount of private data that you would like. You can define a structure to hold your private data, and can provide the address of the structure (instead of the address of a single variable as in the above example).


Registering a Callback Function

You inform ImageGear of each callback function that you want it to call by specifying a pointer to that function as an argument in a call to an IG_...() function. The ImageGear functions that include at least one callback are:

  • IG_load_file_display ()
  • IG_file_IO_register ()
  • IG_load_tag_CB_register ()
  • IG_mem_CB_register ()
  • IG_save_tag_CB_register ()
  • IG_status_bar_CB_register ()

Some callbacks are registered with special registration calls while others are passed in as arguments to normal API calls. The reason for this is that some callbacks need to be called during more than one ImageGear process. Callbacks of this nature will generally be registered with a special registering function (which includes the word "register") and called by ImageGear behind the scenes.

Other callbacks whose function is limited to just one API call will be passed in as an argument, such as LPFNIG_GUITHUMBCOMP, which is called by IG_GUI_thumbnail_sort ().

These callbacks are often essential to the completion of their host function. For example, LPFNIG_GUITHUMBCOMP makes the decision on how thumbnails are sorted. Without it no sorting will take place.

NOTE: If you've registered a callback function using an IG_ ..._CB_register() function, you can un-register it by calling the function again, and supplying a NULL in place of the pointer to the callback function.

In each case, the IG_...() function's description in "Core Component API Function Reference" chapter describes what type the callback function must be. This refers to the argument sequence with which ImageGear is going to call that particular callback function.


Status Bar Callback

ImageGear function IG_status_bar_CB_register () registers a callback function that will thereafter automatically be called by many ImageGear functions at the end of processing each raster line. The arguments let your callback function compute the completed percentage, so you can maintain and update a status bar or a message box showing this information.

Most of the following ImageGear functions will automatically call (not "register") a status bar callback function if you've registered it:

  • IG_load_ ...()
  • IG_save_ ...()
  • IG_dspl_ ...()
  • IG_IP_ ...()
  • IG_FX_ ...()

To register your own status bar callback function (and the area you use if you want to pass your own data to it) make the following call:

IG_status_bar_CB_register ( my_status_bar_CB_func,
&myPrivateData );

Your status bar callback function must be of type LPFNIG_STATUS_BAR. Whenever called by ImageGear, your status bar callback function will be called with the following argument list:

BOOL ACCUAPI my_status_bar_CB_func ( LPVOID lpPrivate, PIXPOS
cYPos,
DIMENSION dwHeight );

Note the following:

  • The function returns an AT_BOOL value, TRUE or FALSE. Return TRUE to have ImageGear proceed normally, return FALSE to tell ImageGear to put an IGE_INTERRUPTED_BY_USER error in the error stack and return from the IG_...() call it is processing (that is, to abort the operation returning the above-named error).
  • The second argument indicates the raster line number just processed.
  • The third argument indicates the total number of raster lines in the image. However, since some functions do not process the lines in order, the quantity (cYPos/dwHeight) in general will not tell you the fraction completed. Instead, your callback function should count the number of times it has been called since the operation began, and divide this count by dwHeight to obtain the fraction completed.


Tag (Non-Image) Data Callback

NOTE: Through ImageGear preserves non-image callback functionality described in this section for the compatibility with applications based on previous versions of ImageGear, it also provides you with new callback functionality for non-image data processing. This new callbacks are connected with ImageGear Format Filters API. So if it is not imperative for you to use old callbacks, please refer to the new ones in the section "Non-Image Data Processing" on page -209 above in this chapter.

Firstly, for those of you who may not have been close-up with a TIFF file before, we offer an explanation of the word "tag". While tags are not exclusive to the TIFF format, the word "tag" was borrowed from TIFF, which is an acronym that stands for "Tagged Image File Format". Each TIFF image can have a set of "tags" totaling into the thousands. In other formats, the equivalents for a tag are normally referred to as a "fields", "header information", or "non-image data". Essentially, tags constitute information that is stored in an image file in addition to the actual bitmap (image) data. Examples of such information range from the bare essentials, such as image width and height, to more auxiliary types of information, such as name of the artist or the date the image was created.

Throughout this section you will see the word tag used in a few different ways. To avoid confusion, here are the five types of tags we will be referring to:

  • Registered TIFF tags: Those tags that are defined by the TIFF specification.
  • Reg istered tags: This generic term refers to those tags that are defined by any format's specification. This will allow you to differentiate from "user-defined" tags.
  • User-defined tags: Tags that you wish to define and add to a file when saving it with ImageGear. These tags are for your own use. If you are adding user-defined tags to a TIFF image, you must use a tag number of 32768 or higher so that you are not accidentally trying to overwrite "registered TIFF tags." As of this writing, TIFF is the only supported format that allows the storage of user-defined tags.
  • Volatile tags: ImageGear refers to tags as "volatile" when the changing of their information could result in the corruption of the bitmap. ImageGear will not allow you to change the information in a volatile tag. Only ImageGear can change the data in these fields. For example, if you resize the image while it is loaded, when you save it, ImageGear will update the height and width tags.
  • Non-volatile tags: ImageGear refers to tags as "non-volatile" when the changing of their information cannot corrupt the image. Examples of such tags are the "Artist" tag (who created the image), and the "Date" tag (when the image was created). ImageGear allows you writing to non-volatile tags when you are saving the image.

ImageGear offers three callback function types for handling tag data. The two callback types LPFNIG_TAG_GET and LPFNIG_TAG_SET are used for setting and getting (respectively) the tag data of any of ImageGear's supported formats. The third, LPFNIG_TAG_USER_GET is used for setting private tag data. This means that you can create your own tags (or fields) and add them to the current set of tags.

NOTE: ImageGear's callbacks for getting and setting information are named from the toolkit's point of view. Since ImageGear is calling your callback functions, when the word "GET" is part of the callback name, it means that ImageGear is Getting information from you. When "SET" is part of a callback name, it means that ImageGear is Setting or sending information to you. If you can remember to use the toolkit's point of view when using callbacks, the names will be easier to remember.

Reading Tags During Loading

When you load a file using ImageGear, you have the opportunity to read its tags. Before ImageGear loads any file it checks for the registration of a callback of type LPFNIG_TAG_SET . If such a callback has been registered, it will be called once for each tag that is being parsed. This includes both registered tags and user-defined tags. However, ImageGear will not let you write data to any tag while loading. When loading, tags are read-only. In your callback, you may wish to make copies of important data. Be sure to make a copy of the data, not the pointer to the data.

NOTE: For all non-volatile fields, ImageGear will store "default values". To keep original data in such fields, you should make a copy of them while loading the image using a callback of type LPFNIG_TAG_SET function. Later, when saving the file, you can pass this data to a callback of type LPFNIG_TAG_GET. Your callback can be designed to look for certain types of tags and to make decisions based on the information in those tags, including whether you would want to modify the data in any of them during saving.

To register LPFNIG_TAG_SET call IG_load_tag_CB_register ().

The example below shows a function of type LPFNIG_TAG_SET that will make a copy of the Artist tag of the image (TIFF) being loaded.

LPFNIG_TAG_SET send_me_tag_info; /* Declare my callback function
*/
HIGEAR hIGear; /* Will hold handle of image */
AT_ERRCOUNT  nErrcount; /* Returned count of errors */
static DWORD dwTags; /* Returned tag values */
nErrcount=IG_load_tag_CB_register ( send_me_tag_info, (LPVOID)
&dwTags );
nErrcount=IG_load_file("TaggedImage.TIF", &hIGear);

In response to the above call ImageGear loads the image, creating its DIB and HIGEAR data structure and handle, then calls your callback function once for each tag being parsed. Here is a simple example of what your callback function might look like:

BOOL ACCUAPI  send_me_tag_info
(
const LPVOID lpPrivate, /* Ptr to private data area */
AT_MODE nIGTag, /* Handle of loaded image */
AT_MODE nDataType, /* Data type of tag data */
const LPVOID lpTagData, /* a copy of the tag data */
DWORD dwSize /* size of the data */
)
{
/* This callback function makes a copy of the Artist tag */
LPBYTE lpDataPtr;
CHAR szArtistName [60];
switch (nIGTag){
...
case IGTAG_TIF_ARTIST:
    memcpy(&szArtistName, lpDataPtr, sizeof(szArtistName));
    return (TRUE);
    break;
return TRUE;
}

Modifying Tags During Saving

When you save any file using ImageGear, you have the opportunity to write to either non-volatile registered tags, or in the case of TIFF, to add user-defined tags. Before ImageGear begins saving your file it will look to see if either of the two tag save callbacks are registered: LPFNIG_TAG_GET or LPFNIG_TAG_USER_GET. If you have registered a callback of type LPFNIG_TAG_GET, ImageGear will check your callback each time it processes a non-volatile tag to see if you would like to overwrite the data in the tag. If you set the callback to TRUE, ImageGear will use your data to overwrite the value in this Tag; if you set the callback to FALSE, ImageGear will ignore your data for this particular tag. In your callback you might include a switch statement that checks the value of AT_MODE nIGTag.

To find out which TIFF tags are considered non-volatile, see the TIFF tag constants section of Geartags.h. The TIFF tag constants are accompanied by a key that tells you which tags will be written by ImageGear to the file when it is saved, which tags are sent to the user via callback, which tags are writable, and which ones can be modified by the user. Basically, if you find a "Y" (for yes) in columns 4 and 5, ImageGear will let you write to this tag. See Geartags.h and also see the note under the description for TIFF in File Format Reference Chapter.

In the example below both callbacks are registered by calling IG_save_tag_CB_register ():

LPFNIG_TAG_GET store_my_tag_info; /* Declare tag-modifying
callback*/
LPFNIG_TAG_USER_GET add_my_own_tags;/* Declare user-defined tag
adding*/
HIGEAR hIGear; /* Will hold handle of image */
AT_ERRCOUNT nErrcount; /* Returned count of errors */
static DWORD dwTags; /* Returned tag values */
nErrcount = IG_save_tag_cb_register ( store_my_tag_info,
add_my_own_tags, (LPVOID) &dwTags );
nErrcount = IG_save_file(hIGear, "TaggedImage.TIF",
IG_SAVE_TIF_JPG);

In response to the above call ImageGear begins to save the image pointed to by hIGear as a JPEG-compressed TIFF. As it reaches each non-volatile writable tag it will call your function store_my_tag_info(). Note, that it also registers add_my_own_tags() which will be called after store_my_tag_info() to add any desired user-defined tags. The example below writes to the Artist tag when the file is being saved.

BOOL ACCUAPI store_my_tag_info;
(
LPVOID lpPrivate,/* Private data passed in */
AT_MODE nIGTAG,/* Tag ID value */
LPAT_MODE lpDataType, /* type of data being set */
LPVOID lpData, /* pointer to the data */
DWORD dwDataLen /* size of data in bytes */
)
{
/* This callback function modifies the Artist tag */
LPPRIVDATASTRUCT lpStructPtr;
lpStructPtr =((LPPRIVDATASTRUCT) lpPrivate);
    if (lpStructPtr->PublSetUsd){
        switch (nIGTag){

        case IGTAG_TIF_ARTIST:
        *lpDataType = IG_TAG_TYPE_ASCII;
            memset( (LPBYTE)(lpData), '\0', dwDataLen );
            memcpy((LPBYTE)(lpData),"JOE PROGRAMMER",14);
            return (TRUE);
            break;
        default:
            return (FALSE);
            break;
        }
    }
return (FALSE);
};
NOTE: When you set a tag you have to tell ImageGear the type and size of your data. When your callback is called, ImageGear will pass you the allowable data size for the tag. You must be sure not to exceed this length.

ImageGear Default Tag Values

For those TIFF tags that can be written ImageGear uses default values unless you tell it otherwise. In other words, if you do not register a callback function of type LPFNIG_TAG_USER_GET, ImageGear will set all writable TIFF tags to ImageGear default values. An example of one such tag is the Artist tag. Let's say it originally contains an artist name of "Giuseppe Artisano". If you do not provide data for this tag and return TRUE from your callback, ImageGear will modify it with its own default value of "1996-2001 AccuSoft Co., All rights reserved". To keep the name of Giuseppe Artisano in the Artist Tag you need to make a copy of this string via your LPFNIG_TAG_SET function, and when saving the image, use a callback of type LPFNIG_TAG_USER_GET to set the tag data back to its original value.

User-Defined Tags

As mentioned earlier, the other type of tag that you can write is a user-defined tag. These are tags that you register for your own use. To add user-defined tags to an image that is being saved, register a callback of type LPFNIG_TAG_USER_GET.

Until you return a FALSE from your callback it will continue to call it and add your list of tags to the image being saved. To register a callback of type LPFNIG_TAG_USER_GET call IG_save_tag_CB_register (). Remember that if you are saving to a TIFF file, your private tags must have values greater than 32768.

For more information about tag callbacks please see the individual descriptions for the tag callbacks prototypes in Core Component API Function Reference.

NOTE: Remember, that as of this writing, TIFF is the only file format which supports the appending of user-defined tags.


Working with Spot Colors

  • Color Channels
  • ImageGear Support


Color Channels

The following types of color channels are currently supported by ImageGear for reading, writing and display:

  • Alpha Channel
  • Extra Channel
  • Mask Channel
  • Spot Channel
  • Unknown Channel

Alpha Channel

Alpha channel defines opacity/transparency of an image. Only one Alpha channel per image can exist. Color space with Alpha channel can be pre-multiplied or non-pre-multiplied. This is the common definition of an Alpha channel, used by most file formats, such as TIFF, PNG, SGI, TGA, etc.

Extra Channel

Extra channel is any channel besides regular color channels or Alpha. There can be any number of Extra channels per image. Extra channels may have some defined semantics, such as Mask or Spot channels, or can be "Unknown", meaning that ImageGear does not know how to display or process them.

Mask Channel

Mask channel specifies a mask or selection in the image. There can be any number of mask channels per image. Images are never pre-multiplied by mask channels. In ImageGear, Mask channel is a subtype of Extra channel.

Spot Channel

Spot channel uses a specific color. The color can be specified using a standard color space, such as RGB or CMYK, or using a custom color, such as Pantone, TRUMATCH, etc. The cusom spot color is defined by its Vendor ID and Color ID.

Existing Vendor IDs:

  • 3000 (ANPA)
  • 3001 (Focoltone)
  • 3002 (PantoneCoated)
  • 3003 (PantoneProcess)
  • 3004 (PantoneProSlim)
  • 3005 (PantoneUncoated)
  • 3006 (Toyo)
  • 3007 (Trumatch)
  • 3008 (HKSE)
  • 3009 (HKSK)
  • 3010 (HKSN)
  • 3011 (HKSZ)
  • 3012 (DIC)
  • 3013 (PantoneMatte)
  • 3020 (PantonePastelCoated)
  • 3021 (PantonePastelUncoated)
  • 3022 (PantoneMetallic)
  • 3024 (HKSEProcess)
  • 3025 (HKSKProcess)
  • 3026 (HKSNProcess)
  • 3027 (HKSZProcess)
  • 3028 (PantoneProSlimEuro)
  • 3029 (PantoneProcessUncoated)

In ImageGear, Spot channel is a subtype of Extra channel.

Unknown Channel

Unknown channel is an additional channel which purpose is unknown to ImageGear. In ImageGear, Unknown channel is a subtype of Extra channel.


ImageGear Support

  • Extra Color Space
  • Reader, Writer and Format Converter
  • Color Books

Extra Color Space

An image may contain multiple Extra channels. An Extra channel can belong to one of the following subtypes: Mask, Spot or Unknown. These channels can be mixed in arbitrary order. ImageGear does not use separate bitmasks from enumIGColorSpaceIDs for Mask and Spot channels. Instead, it uses IG_COLOR_SPACE_ID_Ex bitmask to specify presence of any of these channels in an image.

ImageGear stores an array of extra channel info objects in the DIB. Length of this array must always be equal to the number of extra channels in the DIB. DIB constructors, color space and channel manipulation functions must insure this.

If an entry of the info array has type IG_EXTRA_CHANNEL_TYPE_Spot then corresponding Extra channel is a Spot channel. Spot channel info contains information that is necessary for displaying the spot channel. ImageGear uses spot color channels for display and color space conversions, and saves them to output files when supported by format. If output format does not allow storing additional channels, ImageGear converts Spot channels, together with regular color channels, to the destination color space.

If an entry of the info array has type IG_EXTRA_CHANNEL_TYPE_Mask then corresponding Extra channel is a Mask channel. ImageGear uses Mask channels for display and saves them to output files when supported by format. However, it does not use them in color space conversions. If output format does not allow storing additional channels, ImageGear ignores Mask channels in conversion to the destination color space.

If an entry has type IG_EXTRA_CHANNEL_TYPE_Unknown then corresponding Extra channel is unknown. It is not used in display and color conversions, but preserved and saved to output files when possible.

Spot color, Mask and Extra channels can be appended after any regular color channels, in any order, including color spaces that contain Alpha or Pre-multiplied Alpha channel.

Reader, Writer and Format Converter

ImageGear can load extra channels from TIFF and PSD file formats. The extra channels are internally stored as specified above and saved back as extra channels when the output format is either TIFF or PSD. Spot color support is added to the raster color conversion mechanism, so when saving an image to a format that doesn't support extra channels the image spot channels are get blended to the base channels. The alpha channels are skipped in this case.

Color Books

ImageGear can load Adobe Color Books and apply the loaded colors for displaying spot channels. Color books API allows you to specify a path to the color books, enumerates loaded books and colors within a book, and retrieves info on the specific spot color (see IG_colorbook_create). Display and processing code use color books to convert spot colors to regular colors such as CMYK, RGB etc.


Working with Stripped Images

Large images often test the patience of computer users when they are loaded or displayed. To help speed up loading and display times ImageGear provides alternate storage schemes that allow a large image to be loaded in segments. Such segments could be loaded and pieced together in sequential order.

One of the storage schemes developed was stripped storage. A stripped image contains offsets to numerous groups of pixel rows. Each strip is the full width of the image. The diagrams below show an image stored in strips (shown separated), and the same image pieced together in memory:

In the actual DIB there are no spaces between strips. The header simply contains the address of the leftmost pixel of the first row of each strip. The spaces between the strips in the image on the left are just for illustrative purposes. On the right, the image has been loaded and pieced together in memory.

The TIFF format, in which the use of stripped storage was once commonplace, rarely uses this scheme today. However, there are still many old images still in use that were created with this storage scheme, and ImageGear fully supports these images.

The loading and saving of stripped images using ImageGear is no different than loading or saving a non-stripped image. You can use IG_load_file () or any other ImageGear loading API, without making any special settings. When loading, ImageGear will automatically detect the stripped storage and piece all of the strips together in the proper order.

Once in memory, a stripped image will be like any other image loaded into memory. It will be a DIB with a HIGEAR handle. You can now save it to any ImageGear-supported format. If you would like to save it to again using stripped storage, you may do so using ImageGear Format Filter IG_fltr_ctrl_set ()/ IG_fltr_ctrl_get () functions. Of course, you must choose a file format that supports stripped storage. You can save a TIFF image with stripped storage by setting the number of strips to use. Here is the call you would make:

/* get current value of NUMBER_OF_STRIPS control parameter */
IG_fltr_ctrl_get(IG_FORMAT_TIF, "NUMBER_OF_STRIPS", FALSE,
NULL, NULL, (LPVOID)nNumberOfStrips, sizeof(nNumberOfStrips));
/* set new value to NUMBER_OF_STRIPS control parameter */
IG_fltr_ctrl_set(IG_FORMAT_TIF, "NUMBER_OF_STRIPS", (LPVOID)3,
sizeof(nNumberOfStrips));

In fact, there are a number of ways that a TIFF may be stored using IG_fltr_ctrl_set () with WRITE_CONFIG parameter. See this control parameter and its range of settings in TIFF Control Parameters Table located in the section ImageGear Supported File Formats Reference.

TIFF filter control parameters that pertain to stripped storage include those shown in the following list:

  • NUMBER_OF_STRIPS
  • BUFFER_SIZE
  • WRITE_CONFIG

Please see the section TIFF in File Format Reference Chapter for more detailed information about every of these parameters.


Working with Tiled Images

In a tiled image, pixel data is stored in blocks called "tiles", whose height and width are less than that of the height and width of the full image. All tiles are the same size. However, it is rare that the tiles evenly cover the image. Therefore, in most cases, the following statements will be TRUE:

(# of tiles per row) ¥ (width of a tile)  ¼  the width of the
image
(# of tiles per column) ¥ (height of a tile)  ¼  the height of
the image


Padding

Those areas of tiles that are on the border of an image, but are not completely filled with image data, are filled with padding. The image below illustrates a tiled image and shows padding to the right side and bottom of the image. Padding to the right and bottom of the image is the most frequent tiled storage situation that you will encounter:

When ImageGear loads a tiled image (or any image) it reads the header or tag data to find out the width and height of the actual image. This data will not include the padding. As ImageGear loads the file, it will discard the padding. The following ImageGear-supported file formats allow the use of tiled storage: TIFF, IBM IOCA, and IBM MO:DCA. As of this writing, the highest level of control given to you for working with tiled images is for the popular TIFF format, which will be mentioned frequently throughout this section.

If you were to call IG_load_file () to load a tiled image, it would load the first tile of the first page. If you want to load more than one tile and stitch them together, you should call one of the IG_load_tiles_stitch ...() functions. In addition to loading and stitching any number of tiles, ImageGear also allows you to query the tiles of an image before loading it, tell ImageGear which tiles to "stitch together" when loading, and how to tile the image when you save it to disk.

If you wish to specify which tiles of a TIFF image to load and stitch, your first task will be to find out whether the image actually has tiles or not. The function IG_tile_count_get () can be called to get this information. This function returns the number of tiles per row, and the number of tiles per column. If this function returns zeros for the number of tiles across the image (lpTileCols) and the number of tiles down the length of the image (lpTileRows), you will know that the image is not tiled. There are two other versions of this function: if you have already opened a TIFF file and have a File Descriptor handle for it, use the function IG_tile_count_get_FD (); if the file has already been loaded into memory (using IG_load_mem ()), use the function IG_tile_count_get_mem ().

The following ImageGear functions can be used to load and stitch TIFF tiles:

AT_ERRCOUNT ACCUAPI IG_load_tiles_stitch(const LPSTR
lpszFileName, UINT nPage, LPAT_STITCH lpStitch, LPHIGEAR
lphIGear);
AT_ERRCOUNT ACCUAPI IG_load_tiles_stitch_FD(INT fd, LONG
lOffset, UINT nPage, LPAT_STITCH lpStitch, LPHIGEAR lphIGear);
AT_ERRCOUNT ACCUAPI IG_load_tiles_stitch_mem(LPVOID lpImage,
DWORD dwImageSize, UINT nPage, LPAT_STITCH lpStitch, LPHIGEAR
lphIGear);

Each function takes a page number specifying which page of a multi-page file to load. Set this to 1 if it is not a multi-page file. Each also takes a structure of type AT_STITCH that will tell ImageGear which tiles to stitch together and load. Here is the definition of AT_STITCH:

typedef struct tagAT_STITCH
{
LONG uRefTile; /* Upper left-hand corner tile # */
LONG uTileRows; /* Number of tiles to stitch across*/
LONG uTileCols; /* Number of tiles to stitch down */
}AT_STITCH, FAR *LPAT_STITCH;

Set the structure member uRefTile to the number of the tile that you would like to be used as the upper left-most tile in the image that will be loaded and stitched. Set uTileRows to the number of tiles across that you would like your stitched image to use. Set uTileCols to the number of columns of tiles that you would like your stitched image to use. If you wish to stitch all tiles together, simply pass in a NULL for this structure.

Below are some examples of how a tiled image can be stitched together. Figure 1 shows a tiled TIFF image that contains a total of 9 tiles. Note that for simplicity, the tiles are shown to evenly cover the exact height and width of the image. This rarely happens.

The numbering scheme in Figure 1 reflects the way that ImageGear keeps track of the tiles. When you refer to specific tiles, the upper-left-most tile will be 1. The tiles are then numbered sequentially from left to right, top to bottom.

Figure 1. TIFF image with 9 tiles. The numbering scheme shown is the same one you should use when interfacing with tiles using ImageGear.

Figure 2 shows all of the tiles stitched together, which would be the result if you set the AT_STITCH structure to NULL.

Figure 2. All of the tiles loaded and stitched together.

The following call achieves the results shown in Figure 2:

IG_load_tiles_stitch("KidsKatz.tif", 1, NULL, &hIGear)
Figure 3. Tiles 5, 6, 8, and 9 loaded and stitched together.

To achieve the results shown in Figure 3, make the following calls:

AT_STITCH stitchStruct;
HIGEAR hIGear;
stitchStruct.uRefTile = 5;
stitchStruct.uTileRows = 2;
stitchStruct.uTileCols = 2;
IG_load_tiles_stitch("KidsKatz.tif", 1, &stitchStruct, &hIGear)

You may want to find out the width and height of the tiles in the image so that you can make an informed decision about which tiles to load. First use the function IG_info_get_ex () which will return you the width and height of the image. Then divide the width of the image by the number of tiles per row, and the height of the image by the number of tiles per column. To get the height and width of an image which is already opened and for which you have a File Descriptor handle, call IG_info_get_FD_ex (); to get the height and width of an image which has been loaded into memory and for which you have a HIGEAR handle call IG_info_get_mem_ex ().


Automatic Tile Stitching

ImageGear allows you to automatically stitch all image tiles during loading. Set "STITCH_TILES" filter control parameter to TRUE to enable automatic tile stitching. In this mode:

  • Image loading functions load the whole image as if it was not tiled;
  • Tile counting functions report that the image is not tiled (has a single tile);
  • Header reading functions report full image dimensions rather than dimensions of a single tile.

Set "STITCH_TILES" filter control parameter to FALSE to disable automatic tile stitching. In this mode:

  • Image loading functions load a single tile (by default - first image tile);
  • Tile counting functions report actual number of tiles;
  • Header reading functions report dimensions of a single tile.

Currently, the following ImageGear format filters support automatic tile stitching:

  • IBM AFP
  • IBM IOCA
  • IBM MO:DCA
  • JPEG 2000
  • JPX
  • MJ2
  • TIFF


Saving a TIFF File Using Tiles

When you save a TIFF image to disk, you can tell ImageGear to save the bitmap data as tiles, regardless of what storage scheme was originally used. To choose tiled storage and to make modifications to the way ImageGear will implement these storage schemes, use the IG_fltr_ctrl_set () and IG_fltr_ctrl_get ()functions. For more information on getting/setting filter control parameters see the section "Using Format Filters API for Filter Control" on page -207.

There the list of TIFF filter control parameters that are related to tiles:

  • WRITE_CONFIG
  • TILE_H_COUNT
  • TILE_V_COUNT
  • TILE_WIDTH
  • TILE_HEIGHT
  • BUFFER_SIZE

Please see the section TIFF in File Format Reference Chapter for more detailed information about every of these parameters.

The following example call shows an example image loaded into memory with just tiles 5, 6, 8, and 9 and then being saved as a tiled image with 20 tiles:

/* Declare a structure of type AT_STITCH */
AT_STITCH stitchStruct;
UINT nPage;
HIGEAR hIGear;
LONG lHorizTileCount, lVertTileCount;
/* Set uRefTile to the number of the tile that you would like to
use as the upper-left most tile in the stitched image */
stitchStruct.uRefTile = 5;
/* Set uTileRows to the number of tiles that you would like per
row */
stitchStruct.uTileRows = 2;
/* Set uTileCols to the number of tiles that you would like per
column */
stitchStruct.uTileCols = 2;
/* Set lHorizontalTileCount to the number of tiles per row that
ImageGear should make when an image is saved to disk as a tiled
TIFF. */
lHorizTileCount = 5;
/* Set lVertTileCount to the number of rows that ImageGear
should make when an image is saved to disk as a tiled TIFF. */
lVertTileCount = 4;
/* Set nPage to the page number of a multipage TIFF that you
would like to load. If the TIFF isn't multipage, set to 1. */
nPage = 1;
/* This function loads the tiles specified by &stitchStruct,
stitches them together in a DIB and returns you a HIGEAR to the
image in &lphIGear.*/
IG_load_tiles_stitch("KidsKatz.tif", nPage, &stitchStruct,
&hIGear);
/* Use the Filter Control function to tell ImageGear how to
configure TIFF files when it saves them to disk. This call
specifies that they should be saved as tiled images and that you
will be providing ImageGear will a fixed number of tiles to
create when saving the file. */
IG_fltr_ctrl_set(IG_FORMAT_TIF, "WRITE_CONFIG",
(LPVOID)IG_TIF_TILED_FIXED_COUNT, sizeof(lpWriteConfig));
/* Use the Filter Control function to tell ImageGear how many
tiles per row you would like to make in images saved to disk as
TIFFs. */
IG_fltr_ctrl_set(IG_FORMAT_TIF, "TILE_H_COUNT",
(LPVOID)lHorizTileCount, sizeof(lHorizTileCount));
/* Use the Filter Control function to tell ImageGear how many
rows of tiles you would like to make in images saved to disk as
TIFFs. */
IG_fltr_ctrl_set(IG_FORMAT_TIF, "TILE_V_COUNT",
(LPVOID)lVertTileCount, sizeof(lVertTileCount));
/* Call IG_fltr_save_file() to save the current HIGEAR image as
an uncompressed TIFF. */
IG_fltr_save_file(hIGear, "KidsKatz.tif", IG_SAVE_TIF_UNCOMP,
1, TRUE);
TIP: If you do not specify the configuration to use for saving a TIFF to disk, ImageGear will use the default setting of IG_TIF_STRIP_FIXED_COUNT. If you do not specify a number of strips, the default of 1 is used.

TIFF Storage

TIFF format filter supports four modes of storage for writing out a TIFF file. All settings are made by supplying "WRITE_CONFIG" control parameter for function IG_fltr_ctrl_set (). Here are the possible settings:

IG_TIF_STRIP_FIXED_COUNT
Write the image using a fixed number of strips. The number of strips to use can be set via the NUMBER_OF_STRIPS control parameter.
IG_TIF_STRIP_FIXED_BUFFER
Write the image using strips so that each strip is not greater than the specified size in bytes. The size of the strip buffer can be set via the BUFFER_SIZE control parameter. Please note that at least one raster will be included in the strip.
IG_TIF_TILED_FIXED_SIZE
Save the image using tiles of fixed size. The size of the tiles can be set via the TILE_WIDTH and TILE_HEIGHT control parameters.
IG_TIF_TILED_FIXED_COUNT
Save the image using a fixed number of tiles. The number of tiles in both the horizontal and vertical direction can be set via the control parameters TILE_H_COUNT and TILE_V_COUNT.


Working with Vector Data

ImageGear provides you with 3D vector support.

In previous versions of ImageGear, any vector format filter provided a rasterization, drawing 2D projection of the vector data to the DIB during the vector format reading. In result, the file content was available after loading only as a raster data and all the vector information was lost.

Now the 3D vector support allows you to keep all the vector information together with HIGEAR image handle and show it when an image is displayed. You can show the vector data on the different viewpoints and change such its characteristics as scale factors, position and rotate angles.

When you attach the ImageGear CAD/Vector DWF Component, ImageGear CAD/Vector DWG, DXF Component, ImageGear CAD/Vector DGN Component, ImageGear CAD/Vector HPGL, HPGL/2 Component , ImageGear U3D Vector Component to the core ImageGear module, you can process the vector data for the DWF, DWG, DXF, DGN, HPGL, HPGL/2, U3D vector formats, using the core ImageGear Vector Data Structure (VDS) and API.


Vector Data Structure (VDS) and API

An interface of the vector data structure (VDS) is defined in the vectapi.h file and has two implementations - for C and C++ users:

// Interface definition
#ifndef interface
#define interface struct
#endif
// Enum defining rotation direction
typedef enum tag_direction
{
IG_DIR_XY,
IG_DIR_YZ,
IG_DIR_XZ
} IG_DIRECTION;
//C++ user interface
#ifdef __cplusplus
interface IIGVectorData
{
// Relative camera moving.
virtual void ACCUAPI CameraMove(double dx, double dy, double dz)
= 0;
// Relative changing camera scale factors.
virtual void ACCUAPI CameraScale(double xscale, double yscale,
double zscale) = 0;
// Relative Camera Rotation
virtual void ACCUAPI CameraRotate(double angle, IG_DIRECTION
dir) = 0;
// return camera lens focus
virtual double ACCUAPI get_CameraFocus()= 0;
// set camera lens focus
virtual void ACCUAPI put_CameraFocus(double focus) = 0;
// copy 4x4 vector data state matrix to the state[4][4]
virtual double* ACCUAPI get_DrawingState(double state[][4]) = 0;
//copy state[4][4] matrix to the vector data state matrix
virtual void ACCUAPI put_DrawingState(double state[][4]) = 0;
// Vector data min and max absolute coordinates - read only
virtual double ACCUAPI get_DrawingXMax() = 0;
virtual double ACCUAPI get_DrawingXMin() = 0;
virtual double ACCUAPI get_DrawingYMax() = 0;
virtual double ACCUAPI get_DrawingYMin() = 0;
virtual double ACCUAPI get_DrawingZMax() = 0;
virtual double ACCUAPI get_DrawingZMin() = 0;
};
#else
/* C interface */
typedef struct IIGVectorData IIGVectorData;
typedef struct IIGVectorDataVtbl
{
/* Relative camera moving. */
void (ACCUAPI *CameraMove)(IIGVectorData* This, double dx,
double dy, double dz);
/* Relative changing camera scale factors. */
void (ACCUAPI *CameraScale)(IIGVectorData* This, double xscale,
double yscale, double zscale);
/* Relative rotation of the camera*/
void (ACCUAPI *CameraRotate)(IIGVectorData* This, double angle,
long dir);
/* return camera lens focus */
double (ACCUAPI *get_CameraFocus)(IIGVectorData* This);
/* set camera lens focus */
void (ACCUAPI *put_CameraFocus)(IIGVectorData* This, double
focus);
/* copy 4x4 vector data state matrix to the state[4][4] */
void (ACCUAPI* get_DrawingState)(double state[][4]);
/* copy state[4][4] matrix to the vector data state matrix */
void (ACCUAPI* put_DrawingState)(double state[][4]);
/* Drawing min and max */
double (ACCUAPI *get_DrawingXMax)(IIGVectorData* This);
double (ACCUAPI *get_DrawingXMin)(IIGVectorData* This);
double (ACCUAPI *get_DrawingYMax)(IIGVectorData* This);
double (ACCUAPI *get_DrawingYMin)(IIGVectorData* This);
double (ACCUAPI *get_DrawingZMax)(IIGVectorData* This);
double (ACCUAPI *get_DrawingZMin)(IIGVectorData* This);
};
interface IIGVectorData
{
struct IIGVectorDataVtbl* lpVtbl;
};
#endif /* __cplusplus */

To get an access to the VDS interface use the following ImageGear public function:

IG_vector_data_get(HIGEAR hIGear, LPVOID* lplpVectorData);

This function returns the vector data interface in the lplpVectorData parameter for the given HIGEAR handle.

You can also use the function:

IG_vector_data_to_dib(HIGEAR hIGearSource, LPHIGEAR
lphIGearDest);

that allows you to flush the vector data of the image to DIB.

See the "Core Component API Function Reference" chapter for the more detailed info about these two public functions and for the code examples. See also the VECTOR Sample for the code examples.


Working with Run Ends Format

As of ImageGear v14.5, the Windows DIB format is no longer used for internal storage of images. So 1-bit images are now always stored internally in run ends format. Previous versions of ImageGear had IG_IP_convert_runs_to_DIB() and IG_IP_convert_DIB_to_runs() functions which converted the internally stored image between run ends and DIB (uncompressed packed) format. These functions are no longer necessary because conversion is performed automatically as needed.

When you read an image's pixel data using a pixel access function such as IG_DIB_raster_get (), ImageGear will decompress the pixel data for that raster and store it in your buffer. You can specify packed (8 pixels per byte) or unpacked (1 pixel per byte) format. When you write pixel data using a pixel access function such as IG_DIB_raster_set (), ImageGear will compress and store the pixel data in run ends format. It's important to realize that this decompression and compression is the same work that was previously performed in IG_IP_convert_runs_to_DIB() and IG_IP_convert_DIB_to_runs(). But instead of being performed on the entire image before and after processing, this work is performed on parts of the image during processing.

Decompressing and Compressing the Entire Image

If you want to work with an image directly and to avoid using pixel access functions on a per-raster basis, you can decompress the image to your own buffer using IG_DIB_area_get (). Here's an example scenario:

  1. Call IG_DIB_area_size_get to get the size of the buffer.
  2. Allocate the buffer (i.e. with new or malloc).
  3. Call IG_DIB_area_get. ImageGear decompresses the image into your buffer.
  4. Read/write uncompressed pixel data directly in your buffer.
  5. Call IG_DIB_area_set if updating ImageGear's internal copy of the image is desired. ImageGear compresses the image from your buffer.

Run Ends Format Description

The run ends format is a specialized variant of run length encoding. Run length encoding relies on the fact that certain types of images frequently contain parts where many adjacent pixels share the same color. A description of such an occurrence is known as a run. Typically a run is described as 1) a color and 2) the number of following pixels that are that color. An image raster (or entire image) can be stored as a collection of runs. For example, an image of this page could be described as "2000 white pixels, 5 black pixels, 15 white pixels, 5 black pixels, 15 white pixels, 5 black pixels, 30 white pixels" and so on.

Since the run ends format only works on 1-bit images, it can take advantage of the fact that there are only two possible colors present in the raster: 0 and 1. Since there are only two possible colors, the color does not need to be stored for each run. It is inferred from the previous run. Also, having only two colors makes it especially likely that long runs of identically colored pixels will occur, as compared to images with more colors present.

The following points characterize the run ends format:

  • An image is stored as a collection of rasters encoded in run ends format. Each raster is independent - there is no information shared between rasters. Therefore, consider only a single raster when thinking about the run ends format.
  • A run ends raster is stored as an array of run ends. A run end is a value of type AT_RUN which marks the end of a run by storing the horizontal position (X-coordinate) of where the next run begins.
  • Run ends are stored in order from left to right.
  • It is always assumed that the first run in a raster is white. If it is not, there will be a "null run" at the beginning of the raster which ends at column 0. This is a means of getting the first real (non-zero-length) run to be black.
  • The last run end in the raster is always equal to the image width. This value is stored three times to mark the end of the raster.

Here are some examples of rasters that are 8 pixels in width. Each raster is shown first in uncompressed format, then in run ends format as it would be stored in memory on a 32-bit x86 platform. That is, the number 5 is stored in memory as "05 00 00 00".

Example 1
Example 2
11001000
02 00 00 00 // white run until column 2
04 00 00 00 // black run until column 4
05 00 00 00 // white run until column 5
08 00 00 00 // done (remainder is black)
08 00 00 00
08 00 00 00
00000101
00 00 00 00 // *get first run to be black*
05 00 00 00 // black run until column 5
06 00 00 00 // white run until column 6
07 00 00 00 // black run until column 7
08 00 00 00 // done (remainder is white)
08 00 00 00
08 00 00 00

Accessing Run Ends Data with IG_runs_row_get/set

You can read and write rows of run ends data by using the IG_runs_row_get/set functions. IG_runs_row_get () retrieves a pointer to the run ends data. IG_runs_row_set () updates a row with compressed data from a buffer you supply. These functions are the recommended way of accessing run ends data. The format of the data is exactly as described in the previous section.

Accessing Run Ends Data with IG_image_DIB_raster_pntr_get

IG_image_DIB_raster_pntr_get () is a general purpose function for getting a pointer to pixel data for a given raster. If you use it on a 1bpp image, it will return a pointer to a run ends raster. You can access this raster directly, but be aware of the following:

  • There is an additional AT_RUN value at the beginning of the raster. This value is equal to the total number of AT_RUN values used to store the raster, including this value. For example, for the raster "11001000", this value would be 7.
  • You cannot write data which exceeds the original length of a raster, because ImageGear allocates only enough space to hold the runs for that raster. For this reason, it is safer to use IG_runs_row_set () which can reallocate if necessary.
  • Run ends rasters are not stored contiguously in memory. You must call IG_image_DIB_raster_pntr_get () for each raster you want to process.

Sample Run Ends Code

Here's a sample function which decompresses a run ends raster into uncompressed unpacked (1 byte per pixel) format. It's designed to work with the data you would get from IG_runs_row_get ().

// runsToUnpacked: Decompresses a run ends raster to unpacked
format.
//   nWidth - width of image in pixels
//   lpRuns - pointer to input buffer containing run ends data
//   lpPixels - pointer to output buffer to receive unpacked
pixel data
void runsToUnpacked(AT_DIMENSION nWidth, LPAT_RUN lpRuns,
LPAT_PIXEL lpPixels)
{
    // Starting color is white
    AT_PIXEL outputPixColor = 1;
    // Loop through runs
    AT_INT outputPixPos = 0;
    while (1)
    {
        // Find out when the current run ends
        AT_RUN runEnd = *lpRuns++;
        // Fill in pixels for this run
        while (outputPixPos < runEnd)
            lpPixels[outputPixPos++] = outputPixColor;
        // Have we reached the end?
        if (outputPixPos >= nWidth)
            break;
        // Switch colors for next run
        outputPixColor = !outputPixColor;
    }
}

Here's a more minimalist view of the same function:

void runsToUnpacked(AT_DIMENSION w, LPAT_RUN lpRuns, LPAT_PIXEL
lpPixels)
{
    AT_PIXEL c = 1;
    AT_INT x = 0;
    while (1)
    {
        AT_RUN r = *lpRuns++;
        while (x < r)
            lpPixels[x++] = c;
        if (x >= w)
            break;
        c = !c;
    }
}

Here's a more complex function that creates a 90-degree rotated copy of an image. It operates entirely on run ends data without ever decompressing the data. Note that this is only sample code. This does not represent how ImageGear works internally. Also, error handling is omitted.

// Returns a 90-degree rotated copy of the source image
HIGEAR rotate90(HIGEAR hImageSrc)
{
    HIGEAR hImageDst = NULL;
    HIGDIBINFO hDIB;
    AT_INT d[1] = { 1 };
    AT_DIMENSION srcWidth, srcHeight, dstWidth, dstHeight;
    AT_PIXPOS x, y;
    // Get info about source image
    IG_image_dimensions_get(hImageSrc, &srcWidth, &srcHeight,
NULL);
    // Create destination image
    dstWidth = srcHeight;
    dstHeight = srcWidth;
    IG_DIB_info_create(&hDIB, dstWidth, dstHeight,
IG_COLOR_SPACE_ID_I, 1, d);
    IG_DIB_palette_alloc(hDIB);
    IG_image_create(hDIB, &hImageDst);
IG_DIB_info_delete(hDIB);
    AT_RGB rgb = { 255, 255, 255 };
    IG_palette_entry_set(hImageDst, &rgb, 1);
    // Make a list of source raster pointers
    LPAT_RUN *lpSrcRasters = NULL;
    lpSrcRasters = (LPAT_RUN *) malloc(sizeof(LPAT_RUN) *
srcHeight);
    // Make a list of current colors for source runs
    LPAT_BYTE lpSrcRunColors = NULL;
    lpSrcRunColors = (LPAT_BYTE) malloc(sizeof(AT_BYTE) *
srcHeight);
    // Populate the lists
    for (y = 0; y < srcHeight; y++)
    {
        AT_RUN runCount;
        IG_runs_row_get(hImageSrc, y, &runCount,
&lpSrcRasters[y]);
        if (*lpSrcRasters[y])
            lpSrcRunColors[y] = 1;
        else
        {
            lpSrcRunColors[y] = 0;
            lpSrcRasters[y]++;
        }
    }
    // Allocate a raster large enough to store worst-case input
data
    LPAT_RUN lpDstRaster = (LPAT_RUN) malloc(sizeof(AT_RUN) *
(dstWidth + 4));
    // Loop through output rasters
    for (y = 0; y < dstHeight; y++)
    {
        AT_INT nDstRuns = 0;
        AT_BYTE dstRunColor = 1;
        AT_INT srcRasterIndex = srcHeight - 1;
        // If the first source pixel is black,
// set us up to start with black in the output raster
        if (!lpSrcRunColors[srcRasterIndex])
        {
            dstRunColor = 0;
            lpDstRaster[nDstRuns++] = 0;
        }
        // Loop through columns in destination image
        for (x = 0; x < dstWidth; x++)
        {
            // Check the color of the run in the source raster
that
            // corresponds to the current column in the
destination raster.
            // Is it the same color as the run we're currently
constructing?
            if (lpSrcRunColors[srcRasterIndex] != dstRunColor)
            {
                // If not, then we need to store the run we've been
making
// in the destination raster.
                lpDstRaster[nDstRuns++] = x;
                // Alternate the current destination run color
                dstRunColor = !dstRunColor;
            }
            // See if it's time to move on to the next source run
for
// this source raster
            if (*lpSrcRasters[srcRasterIndex] == y)
            {
                lpSrcRasters[srcRasterIndex]++;
                lpSrcRunColors[srcRasterIndex] =
!lpSrcRunColors[srcRasterIndex];
            }
            // Move on to the next source raster (go *up* through
the source image)
            srcRasterIndex--;
        }
        // Add the three ending runs to the destination raster
        lpDstRaster[nDstRuns++] = dstWidth;
        lpDstRaster[nDstRuns++] = dstWidth;
        lpDstRaster[nDstRuns++] = dstWidth;
        // Store the destination raster!
        IG_runs_row_set(hImageDst, y, nDstRuns, lpDstRaster);
    }
    // Clean up
    free(lpSrcRasters);
    free(lpSrcRunColors);
    free(lpDstRaster);
    return hImageDst;
}


Working with ImageGear Digital Camera RAW Filter

ImageGear supports reading raw images created by many digital cameras. Support for raw images includes reading of image pixel data, color reconstruction of raw images, and reading of metadata stored with the images.


File Format

Since there are many flavors of raw formats, the list is continuously growing as new vendors/models enter the market, and the formats share many similarities, ImageGear treats most of raw formats as one format: IG_FORMAT_DCRAW. Details regarding manufacturer, model, etc, are available as metadata.

A special group of camera raw formats is Headerless Camera Raw formats. Headerless Digital Camera RAW file filter provides support for Digital Camera Raw images that only contain pixel data and no header. Because of absence of a header, such files can't be detected reliably. ImageGear uses low detection priority for these images, and by default, detection of this filter is disabled. Also, since these files do not contain any metadata describing color reconstruction, ImageGear support level for them is limited to "S2" - pixel decoding only.


Loading Raw Images

Load camera raw images in the same way as you load images of all other formats, using one of the image loading methods. Use control parameters of the IG_FORMAT_DCRAW or IG_FORMAT_HLDCRAW filter to control loading of raw images.

By default, ImageGear attempts to reconstruct the full color image from raw data. You can also load unprocessed or partially processed image and apply some custom processing to it.


Loading of Pixel Data from Raw and DNG Images

Digital cameras store raw images in exactly the same format as obtained from the camera sensor. A number of image processing operations must be performed to reconstruct full color image from the raw data. DCRaw and DNG filters have the same set of loading options that allows loading unprocessed or partially processed image. Partially processed image can then be processed with the help of ImageGear image processing methods.

Note that camera manufacturers do not publish specifications on their raw formats. ImageGear attempts to reconstruct color images correctly where it is possible. For some cameras not all of the color balance data is available. The application may need to apply additional processing to such images.

The section ImageGear Supported Digital Camera RAW Formats lists the level of support that ImageGear provides for particular cameras.


Reconstructing Camera Raw Images with ImageGear Processing API

By default, ImageGear reconstructs Camera Raw images automatically, using the settings found in image metadata. However, one of the main benefits of Raw formats is that they can be custom adjusted during conversion to the working RGB colorspace.

ImageGear provides API that allows to specify white balance and tone settings for Raw image reconstruction.

Colorspace Conversion

In order to use custom white balance for the image, set "APPLY_COLORSPACE_CONVERSION" control parameter of DCRAW format filter to FALSE. Use IG_IP_DCRaw_camera_to_sRGB_matrix_calculate function to calculate a conversion matrix, based on selected white balance and on known conversion matrices obtained from metadata. Use IG_colorspace_conversion_create_from_matrix and IG_colorspace_conversion_apply_to_image to convert the image to the linear sRGB colorspace.

Use IG_color_temperature_initialize_from_preset function to create white balance settings from preset values; IG_color_temperature_initialize_from_XY and IG_color_temperature_convert_to_XY for converting between color temperature and white point XY values.

The APPLY_COLORSPACE_CONVERSION parameter only has effect if the RECONSTRUCT_COLORS parameter is True.

Tone Correction

In order to adjust image tone (contrast/brightness curve), set "APPLY_TONE_CORRECTION" filter option to FALSE. This will tell ImageGear to skip the tone correction step. The application can create a Tone correction LUT using IG_IP_DCRaw_tone_LUT_build function, or build its own Tone LUT. In order to convert the image to the standard sRGB colorspace, an additional sRGB Gamma LUT must be applied. Use IG_IP_DCRaw_RGB_gamma_LUT_build function to build sRGB Gamma LUT.

Use IG_IP_transform_with_LUTs function to apply a LUT to the image.

The APPLY_TONE_CORRECTION parameter only has effect if both APPLY_COLORSPACE_CONVERSION and RECONSTRUCT_COLORS options are True.


Control Parameters for the Camera Raw Filter and Headerless Camera Raw filters

Filter Control Parameter
Type
Default Value
Available Values
Description
APPLY_COLORSPACE_CONVERSION
AT_BOOL
TRUE
FALSE,
TRUE
Set to TRUE to convert raw image to linear sRGB colorspace during loading. Has effect only if RECONSTRUCT_COLORS is TRUE.
APPLY_TONE_CORRECTION
AT_BOOL
TRUE
FALSE,
TRUE
Set to TRUE to automatically adjust image tone and apply sRGB gamma correction during loading. Has effect only if both
RECONSTRUCT_COLORS and APPLY_COLORSPACE_CONVERSION are TRUE.
RECONSTRUCT_COLORS
AT_BOOL
TRUE
TRUE,
FALSE
If TRUE, ImageGear attempts to reconstruct full color image from the camera raw image. Otherwise, ImageGear loads raw pixel data without any processing. See also APPLY_COLORSPACE_CONVERSION and APPLY_TONE_CORRECTION parameters.

Loading options are discussed in more detail below.

RECONSTRUCT_COLORS

When TRUE, ImageGear performs the following operations during image loading:

  • Linearization. Some cameras store images in a non-linear colorspace, to increase compression efficiency.
  • Calculation of image Black Level, trimming of the black frame, subtraction of black level. Black level, or Thermal Black is the level of signal produced by heating of the camera rather than by light. Many camera sensors measure the black encoding level using fully masked pixels at the edges of the sensor. ImageGear trims these pixels from the image during loading. Intensities of these pixels are averaged to produce the Black Level value. Black Level should be subtracted from image pixels for correct reconstruction of the image.
  • Intensity stretching according to White Level. White level specifies the maximum intensity that can be recorded by camera sensor, or an intensity at which the sensor's output becomes highly nonlinear. Image intensities between the BlackLevel and WhiteLevel range should be stretched to the full contrast range supported by the image bit depth.
  • Demosaicing. Most of digital cameras store pixels in "mosaic" format. At a given pixel location either a Red, Green, Blue, Cyan, or some other color sample value is recorded. Such images are referred to as "Color Filter Array" type. A two-dimensional matrix called "Color Filter Array pattern" describes positions of pixels of particular color in the mosaic image. In order to recreate the full color values in each pixel, it is necessary to interpolate neighbouring pixels.
  • Image rotation. Some camera sensors are rotated by 45 degrees. Such images need to be rotated back.

These operations normally don't require user interaction. After applying these operations, all Camera raw images are converted to linear CMYG or RGB colorspace and promoted to 16 bits per channel.

APPLY_COLORSPACE_CONVERSION and APPLY_TONE_CORRECTION parameters control the rest of color reconstruction operations.

When RECONSTRUCT_COLORS is FALSE, ImageGear does not perform any color reconstruction operations during image loading.

APPLY_COLORSPACE_CONVERSION

When TRUE, ImageGear converts image from camera color space to linear sRGB colorspace, using white balance settings from the image metadata. This option is enabled only if RECONSTRUCT_COLORS is True. In order to load the image with custom white balance settings, set APPLY_COLORSPACE_CONVERSION to FALSE and use Camera Raw Colorspace Conversion API functions after image loading.

APPLY_TONE_CORRECTION

When TRUE, ImageGear adjusts image exposure using image's default settings (baseline exposure) and default setting of 5 for Shadows. This option is enabled only if both RECONSTRUCT_COLORS and APPLY_COLORSPACE_CONVERSION are True. In order to load the image with custom exposure/shadows settings, set APPLY_TONE_CORRECTION parameter to FALSE and use Camera Raw Tone Correction API functions after image loading.


Using ImageGear Component Manager

The general structure of ImageGear is a component structure that consists of the core (main) ImageGear module and some additional components.

The component is code that can be connected with the main ImageGear functionality using a platform-independent API. A component can be a separate module or linked statically with the main IG module. To initialize component functionality, attach (load) the component to the main ImageGear module through the special ImageGear component manager API. When the component is attached, it gets access to all core ImageGear functions, and the core ImageGear functionality can use the component's structures, functions, and control parameters.

Usually, ImageGear components contain such additional functionality as additional format filters (for example, LZW, PDF) and additional image processing functionality (such as ImageClean, ISIS/MS61 Scanning, ART).

Once you have loaded the component it cannot be unloaded up to the moment of cleanup of the main ImageGear module, i.e. exit of ImageGear based application.

ImageGear identifies every component by its name, and during the attaching process it calculates the physical name of the file where the component is located. By default ImageGear assumes that all components are located in the same directory where the main IG module is located, however there is a way to set up a full path to the module for every component.

See also the ImageGear Component Names section.


Component Manager API

ImageGear provides the component manager API that can be used for attaching, checking, function requesting, and retrieving information of every ImageGear component.

To attach (load) the component to the core ImageGear you can use the function:

IG_comm_comp_attach(LPCHAR lpCompName)

This function attaches the component, determined by lpCompName (for instance, "CAD"), to the core IG module. If a component with the given name is already attached, this function does nothing. See also the ImageGear Component Names section.

To check if a component with a given name is currently attached, use the function:

IG_comm_comp_check(LPCHAR lpCompName)

If the component is attached, then this function returns TRUE; it returns FALSE otherwise.

It is the usual situation that some component provides functionality that should be accessible from the application, and there are two ways that the application can call some function implemented by the component. The First method is using the component manager function:

IG_comm_function_call(LPCHAR lpEntryName, ... );

where lpEntryName is a name of the requested function in the form "<COMP_NAME>.<FUNC_NAME>", where <COMP_NAME> is a name of the component that provides the function and <FUNC_NAME> is a name of the function.

However, the application is not supposed to call this function directly, but use a special macro that is provided for each public function by the component. That macro is located in the special header file i_<COMP_NAME>.h named component public header. For instance, i_CLN.h (ImageClean component):

#define IG_IC_clean_borders_ex( hIGear, nLeftBorderSize,
nRightBorderSize, nTopBorderSize, nBottomBorderSize,
nMinLinesNum, nMinLineWidth)
    ((AT_ERRCOUNT (CACCUAPI *)(LPCHAR, HIGEAR, UINT, UINT, UINT,
UINT, UINT, UINT))
IG_comm_function_call)("CLN.IG_IC_clean_borders_ex",  hIGear,
nLeftBorderSize,  nRightBorderSize,  nTopBorderSize,
nBottomBorderSize,  nMinLinesNum,  nMinLineWidth)

Another way is to use the function

IG_comm_entry_request( LPCHAR lpEntryName, LPAFT_ANY
*lpFuncPtr, LPCHAR lpReason );

The first parameter is the name of the function in the format described above. The second parameter is a pointer to the necessary function. The last parameter is a text description reason to get access for this function (it is optional and can be NULL). The component public header usually contains a type declaration for any public function. The correct way to call such a function would be to declare the variable of the necessary function type defined in a public header; use IG_comm_entry_request() to initialize this variable with the correct value and then call it.

NOTE: To distribute your application using any ImageGear component API, you should include in your application's *.c file the component public header i_<COMP_NAME>.h.

Also, there is a function to retrieve information about all attached components:

IG_comm_comp_list(LPUINT *lpnCount, UINT nIndex, LPCHAR lpComp,
DWORD dwCompSize, LPUINT lpnRevMajor, LPUINT lpnRevMinor, LPUINT
lpnRevUpdate,
LPCHAR lpBuildDate, UINT nBDSize, LPCHAR lpInfoStr, UINT
nISSize)

This function provides you with the full list of info about the component determined by nIndex index from the list of currently attached components whose numbers are returned trough the lpnCount argument.


ImageGear Component Names

Below is the list of ImageGear components and their short names that you should provide for IG_comm_comp_attach () through the lpCompName argument:

  • Core ImageGear Component - "CORE"
  • ImageGear ABIC Component - "ABIC"
  • ImageGear ARTX Component - "ArtX"
  • ImageGear ART Component - "ART"
  • ImageGear CAD/Vector DGN Component - "DGN"
  • ImageGear CAD/Vector DWF Component - "DWF"
  • ImageGear CAD/Vector DWG, DXF Component - "DWG"
  • ImageGear CAD/Vector HPGL, HPGL/2 Component - "HPGL"
  • ImageGear CAD/Vector CGM Component - "CGM"
  • ImageGear CAD/Vector SVG Component - "SVG"
  • ImageGear FlashPix Component - "FPX"
  • ImageGear FreqIP Component - "FREQIP"
  • ImageGear GIF/TIFF-LZW Component - "LZW"
  • ImageGear HD Photo Component - "HDP"
  • ImageGear ImageClean Component - "CLN"
  • ImageGear ISIS Component - "SCAN"
  • ImageGear JBIG2 Component - "JBIG2"
  • ImageGear JPEG2000 Component - "JPEG2K"
  • ImageGear Medical Component - "MED"
  • ImageGear Multimedia Component - "MULT"
  • ImageGear QuickTime Component - "QT"
  • ImageGear PDF Component - "PDF"
  • ImageGear Recognition Component - "REC"
  • ImageGear TWAIN Component - "TWAIN"
  • ImageGear U3D Vector Component - "U3D"
  • ImageGear Vector Component - "VECT"


Using ImageGear ARTX Component

NOTE: You can only attach one ART component. ARTX cannot be attached when ART is already attached.

Using the ArtX component, you can annotate any image that your application loads into ImageGear. The annotations are called "ArtX marks", or "marks" for short. Every ArtX mark is represented by its own object, but the actual life of marks starts when they are added into the HIG_ARTX_PAGE object.

Art internally tracks the marks that are associated with the image and insures that marks are always displayed on the correct part of the image (even as the image is scrolled, rotated, flipped and zoomed). Your application can save an image with the marks into a separate file in legacy .ART file format or .XML file format. Anytime the image is reloaded, the ArtX marks can be reloaded with a simple function-call.

ImageGear ArtX component consists of the marks objects as well as of the objects for handling marks.


Annotation and Redlining

The ImageGear ArtX helps developers to add redlining and annotation capabilities to any application built with ImageGear. If you have an application that can read, display, and print images, with ImageGear ArtXcomponent associated you can add marking capabilities, such as lines, arrows, highlighting, and sticky notes to documents images, and use them as though you were working on printed sheets of paper.

The fundamental "unit" of annotation is called an "ART Mark", or "mark" for short (the original name of ImageGear ArtX was the "Annotation and Redlining Toolkit"). When the end-user uses your application to annotate an image, (s)he is creating marks. Each mark is defined by some geometry ((x,y) position on the image, height and width, etc.), and (for some marks) textual information (a text string, a date, etc.). While the rest of ImageGear typically works with raster (pixel-based) images, ImageGear ArtX marks are vector objects - they can be moved, resized and deleted.

While the marks are vector objects, they typically are intended to be related to some part of the raster image. For example, one of the marks is a digital version of a "PostIt" note (called an "Attach A Note" mark):

If the user scrolls or zooms the image, it's critical that the mark scrolls or zooms with the image - so that it always appears over the same part of the image. ImageGear ART works in conjunction with page display functions to make sure that this happens.

ImageGear ART provides ART GUI tool that the end-user works with to create and edit the marks. Enabling the ART Forms tool makes adding annotation/redlining capabilities to your application basically trivial.

Once the end-user has created marks for a given image, they need to be saved. ART marks can be saved in any of 4 ways:

  • Save the annotations in a separate .ART or .XML file.
  • "Burn in" the annotations permanently (making them part of the image file).
  • Save the annotations in the image format that supports storing annotations (for example TIFF files).
  • You may also combine these methods. You can, for example, leave classified information in an ART file and "burn in" non-classified information into the image.

The various marks that can be created with ImageGear ART are described in the following table. Please refer to the ARTX Component API Function Reference for complete descriptions of the ImageGear ART component objects and functions.

ART 3.0/ART 2.0 Mark
Example
Text

Line

Freehand Polyline

Rectangle

Ellipse

Polygon

Polyline

Audio (a WAV file on disk is read, and the sound played when the user clicks in the mark)

Image (your application provides the image used - the one shown here is the one used in the sample program)

Ruler (automatically labels the line according to the units defined in the image-file header).

Protractor

Encryption (visually looks like a filled rectangle). When user clicks on the rectangle, an event is raised allowing to request a password. If password matches the one in the mark, then application can make the mark transparent, which displays the image)

Button (when user clicks on the button, an event is raised allowing to take action)

Hotspot (when end-user clicks in shaded area, an event is raised to which your application can respond)

Rich Text

ART 2.0 Mark
Example
Arrow

Filled Rectangle

Hollow Rectangle

Filled Ellipse

Hollow Ellipse

Filled Polygon

Hollow Polygon

Redaction (looks just like a filled rectangle, but cannot be moved after the marks are written to a file)

Hightlighter Rectangle

Typed Text

Text Stamp (automatically set to date and/or time the mark was created)

Attach A Note

Text From File (a text file on disk is read, and the text displayed in the mark)

Pin-up Text (when user clicks on the pushpin, an event is raised allowing the application to display additional text).

Embedded Image (your application provides the image used - the one shown here is the one used in the sample program)

Image Reference (an image file on disk is read, and the image in the file is displayed for the mark - the one shown here is just a sample)


Working with ART Marks

Creating a Mark via the ToolBar

End users can create a mark using the ART toolbar, or your application can create them directly by calling ART functions. This section describes how to create marks with user interaction through the ART toolbar.

When a button is selected from the toolbar, ART goes into "edit mode", where the mouse is used to place and size the mark. The sequence of events depends on whether the mark is one of the types that contains text or not:

Mark does not contain text:

  • User drags a rectangle on the image
  • Mark is placed and sized on the image, and is selected.
  • Control returns to the application.

Mark contains text:

  • User drags a rectangle on the image
  • Mark is placed and sized on the image, and is placed in text-edit mode.
  • Blinking "I-Beam" insertion point is placed in the mark.
  • User types text into the mark, as desired.
  • User clicks the mouse-button. Mark goes from text-edit mode to selected.
  • Control returns to the application

Note that ART ToolBar event handlers are implemented in the ART GUI open source code and can be modified at any time and any way, but in order for them to work your application need to interact with the following events:

UINT IG_ARTX_GUI_mouse_down(LPAT_ARTX_ACTION_PARAMS lpParams,
UINT nMessage, LPAT_POINT lpPoint);
UINT IG_ARTX_GUI_mouse_move(LPAT_ARTX_ACTION_PARAMS lpParams,
UINT nMessage, LPAT_POINT lpPoint);
UINT IG_ARTX_GUI_mouse_up(LPAT_ARTX_ACTION_PARAMS lpParams,
UINT nMessage, LPAT_POINT lpPoint);

Creating a Mark via Function Calls

Some applications won't use the ART ToolBar, or will provide the ToolBar and other options, for creating marks. In that case, some function in your application will need to create the marks directly. ART marks are created by using their objects. For example rectangle can be created as follows:

IG_ARTX_rectangle_create(pRectangle, pFillColor, pBorder,
nOpacity, &hRectMark);

Once it is created it should be added to the ART page:

IG_ARTX_page_mark_add(hArtPage, hRectMark, nCoordType,
&hRectMark);

Mark properties can be edited at any time:

IG_ARTX_rectangle_opacity_set(_hRectMark, 128);

Saving ART Marks

Once the end-users of your application have created some marks, they're probably going to save them somewhere. Your application has 5 choices of where to save them:

  • Save them to a separate .ART file. This is a legacy ART storage format supported in the previous versions of ImageGear ART. Using this method, your application will have to keep track of which .ART file goes with which image file, and load them together. Use IG_ARTX_page_save_file () function with LEGACY parameter of enumIGArtXSaveFormat.
  • Save them to a separate .XML file. This is a more flexible and extendable storage format highly recommended for using. Using this method, your application will have to keep track of which .XML file goes with which image file, and load them together. Use IG_ARTX_page_save_file () method with XML parameter of enumIGArtXSaveFormat.
  • Save the art marks as tags or objects inside the image file. This option is only available for the raster file formats that support storing annotations, like TIFF files. Use IG_ARTX_page_save ().
  • Save the art marks as annotations inside the PDF file. This option is only available for PDF format. Use IG_ARTX_page_save_file () that takes IGPage to do this.
  • "Burn In" the ART marks. This converts the ART marks from their native representation to the format of the raster image file, which usually destroys a lot of their functionality (for instance, once a mark is burned in to a JPEG image, it cannot be moved, resized or hidden). Use IG_ARTX_page_burn_in () method to do this.
NOTE: .ART files can be read by any other application developed with ImageGear. In addition, the .ART file format is supported by the Imaging for Windows application (from Kodak) supplied with Windows.

Loading ART Marks

Once ART marks have been saved, they can be reloaded (by the same user or a different user, using the same program or using any other ImageGear-enabled application). The way that the marks were saved will determine how they must be reloaded:

  • .ART / .XML / image file / PDF file: Your application loads the image using any of the IG_load_xxx functions and then loads ART page using the appropriate IG_ARTX_page_load_file ().
  • Burned In: Your application loads the image using any of the IG_load_xxx functions. The burned-in remains of the marks are loaded as part of the image.

Edit Mode, Run Mode and View Mode

ART GUI can interract in one of three modes:

  • Edit mode lets users create or edit marks.
  • Run mode lets users operate on Hot Spot, Encryption, Image, Audio, and Button activities.
  • View-only mode allows users to view marks but not add or modify them.

Your application can switch the mode from one to another by simply setting ART GUI Mode property.

ART GUI code implementes abstract ArtX...Processor objects for each mode:

  • View mode processor is implemented via ArtXViewProcessor object.
  • Run mode processor is implemented via ArtXRunProcessor object.
  • Edit mode processor is implemented via ArtXEditProcessor object.

Those classes are distributed with ImageGear ART GUI component and can be modified to fit in your application.

While you are in the View mode, your application will not have to deal with any ART-related events via ArtXViewProcessor: it simply loads the image and ART marks and displays them.

If your application switches to Run mode, then it will have to start dealing with specific ART-related events via ArtXRunProcessor. For example, for an Encryption mark, when the image and ART marks are first loaded and displayed, the Encryption mark will obscure some or all of the image. When the user moves the cursor over the mark, the cursor will change to pointing hand cursor. ART Forms event handler will display a dialog box asking for the password to enable viewing of that portion of the image, and then (if the user gets the password right), unobscure the image.

If your application switches to Edit mode, then it will have to start dealing with specific ART-related events via ArtXEditProcessor.

Modifying Marks

As long as you are in Edit mode, marks can be modified.

As with creating marks, there are two ways to modify marks:

  • The first is to use ART GUI property dialogs.
  • The second is to use mark objects' properties and methods.

Geometric changes (like moving and resizing) are done automatically, as a result of ART GUI implementation, as shown in Creating a Mark via the ToolBar. To make other changes to a mark, your application makes a simple call to the mark's properties and methods.

The technique for modifying marks via function call is used in the ART GUI dialogs code. The marks attributes can be modified by changing their properties and using their methods.

Deleting Marks

Marks are deleted by using IG_ARTX_page_mark_remove ()/ IG_ARTX_page_marks_remove () functions.

Clipboard Operations

ART marks can be cut from and copied to the clipboard as well as and pasted into an image individually or in groups. There are the following functions in HIG_ARTX_PAGE object providing the methods to perform clipboard operations:

Iterating Through Marks

Sometimes, your application will need to iterate through the marks in an HIG_ARTX_PAGE object. This can be done by using "foreach" mechanism:

For example, to delete all the selected marks, your application would do the following:

HIG_ARTX_PAGE hMark = NULL;
IG_ARTX_page_mark_first(hArtPage, &hMark);
while (hMark != NULL)
{
AT_BOOL bSelected = FALSE;
IG_ARTX_page_mark_is_selected(hArtPage, hMark, &bSelected);
if (bSelected)
{
...
}
}

Mark Groups

HIG_ARTX_PAGE provides a facility called "mark groups" (or just "groups", for short) that provides a powerful mechanism for implementing application features. Every mark belongs to one and only one group; by default all marks belong to a group with index 0 and named "[Untitled]".

Your application can create as many groups as needed, each group is simply given a unique index. HIG_ARTX_PAGE provides a set of methods that manipulate all of the marks in a group (hide them all, make them all visible, etc.). Your application could use groups to provide annotation layers (each "layer" would simply be a group), so that the user could choose which layer, and thus which set of annotations, to view. Alternatively, your application could use groups to provide private annotations (each person would only be able to see "their" annotations).

The various methods that operate on groups are provided by HIG_ARTX_GROUP object.

Event Handling

Event handlers are implemented in the ART GUI open source code and can be modified at any time and any way. To enable ART GUI event handlers your application need to interract with the HIG_ARTX_ACTION functions:

  • IG_ARTX_action_mouse_down
  • IG_ARTX_action_mouse_move
  • IG_ARTX_action_mouse_up


ART 2.0 and ART 3.0 Marks

This section describes two sets of marks available in ImageGear ART namespace:

  • ART 3.0/ART 2.0 Marks
  • ART 2.0 Legacy Marks

ART 3.0 set consists of the enhanced list of more flexible marks. These marks are recommended for using by new applications. ART 2.0 (Legacy) set consists of the marks backward compatible with the previus ART versions.

Only ART 2.0 marks can be loaded from the .ART files created with previus ART versions and only ART 2.0 marks can be saved into the legacy ART storage format.

Both ART 2.0 and 3.0 marks can be saved into the XML storage format, please note however that ART 2.0 marks will be converted to the appropriate ART 3.0 super class marks. Only ART 3.0 marks are loaded from the XML storage format.

NOTE: Some ART marks, such as Attach-a-Note, Text Stamp may require Wang compatibility mode enabled to be saved properly in legacy storage format. On the contrary the Highlighter mark should be saved in legacy format without Wang compatibility mode on.

ART 3.0/ART 2.0 Marks

Text

The Text mark enables the end user to add descriptive text to their annotated image or document. The text can be created in various fonts, sizes, colors and opacity. It can be with or without border, filled color and pin icon. The text appears over the original image or document.

Edit mode: End users create this mark by clicking the Text button with the left mouse button and then dragging the resulting rectangle over the area to be annotated. This rectangle helps to position the Text annotations. Text annotations are easily modified when the application is in the Edit mode. To modify it, the end user double-clicks the left mouse button when the cursor is over the text mark. The cursor appears at the beginning of the text, and transforms to allow editing.

Line

The Line mark enables the end user to create straight lines on an image or document.

Edit Mode: To create this mark, end users:

  1. Click on the Line button with the left mouse button.
  2. Click on the left mouse button at the point where the line shoud begin.
  3. While holding the left mouse button down, drag the line to the point at which the line should end.
  4. Release the left mouse button to complete the line.
  5. Press the right mouse button after the mark is created to activate the popup Edit menu.

Freehand Polyline

The Freehand Polyline mark enables the end user to use freehand drawing for annotation. With this mark, end users create drawings as though they are using a pen and paper.

Edit Mode: In Edit mode, end users create this mark by clicking the Freehand Polyline button with the left mouse button, dragging the image, and then releasing the left mouse button. Pressing the right mouse button after the mark is created activates the popup edit menu.

Rectangle

The Rectangle mark enables end users to cover areas of an image or document with a rectangle. The Rectangle can be with or without border and filled color. It can have a different opacity level.

Edit Mode: In Edit mode, end users create this mark by clicking the Rectangle button with the left mouse button and then dragging the resulting rectangle over the items to be covered. Pressing the right mouse button after the mark is created activates the popup edit menu.

Ellipse

The Ellipse mark enables end users to cover areas of an image or document with an ellipse. The Ellipse can be with or without border and filled color. It can have a different opacity level.

Edit Mode: In Edit mode, end users create this mark by clicking the Ellipse button with the left mouse button and then dragging the resulting ellipse over the items to be covered. Pressing the right mouse button after the mark is created activates the popup edit menu.

Polygon

The Polygon mark enables the end user to cover areas of an image or document with a polygon.

Edit Mode: To create a Polygon mark, end users:

  1. Click the left mouse button at the point where the polygon starts.
  2. Drag the mouse to the location of a vertice and click the left mouse button.
  3. Repeat step 2 to add the desired number of vertices to the polygon, clicking the left mouse button to add a vertice.
  4. Double-click the left mouse button to complete the polygon.
  5. Press the right mouse button after the mark is created to activate the popup Edit menu.

Polyline

The Polyline mark enables the end user to create several connected straight lines by dragging and clicking the mouse.

Edit Mode: To create a Polyline mark in an application, end users:

  1. Click the left mouse button at the point where the polyline starts.
  2. Drag the left mouse button to the location of a vertice.
  3. Drag and click the left mouse button to create each additional vertice.
  4. Move the cursor to the location where the polyline ends.
  5. Double-click the left mouse button.

Pressing the right mouse button after the mark is created activates the popup Edit menu.

Audio

The Audio mark enables end users to hear sounds when annotating an image or document. It is useful for drawing attention to a particular area of a text or image file. This mark plays a waveform audio file (.WAV).

Edit Mode: In Edit mode, end users create this mark by clicking on the Audio button with the left mouse button and then dragging the mark (a loud-speaker-shaped bitmap) to its destination. To display the dialog box, the user double-clicks the left mouse button on the loud-speaker. This allows the user to specify the name of the .WAV file that plays during Run mode.

When the application is in the Run mode, the cursor changes to a pointing hand when it passes over the loud-speaker bitmap. As the mark is activated (makes a sound), lines representing sound waves appear and disappear from the end of the loud-speaker.

Image

The Image mark enables the end user to embed or file reference a bitmap or vector image in a document or image.

Edit Mode: In Edit mode, end users creates a mark by clicking the Image button with the left mouse button, dragging the image, and then releasing the left mouse button. When the left mouse button is released, the image becomes embedded. Once the bitmap or the vector image is in place on the annotation window, it can be re-sized by using the left mouse button. Right-click the mark to activate the popup edit menu.

Run Mode: In Run mode, end users interact with a vector Image mark by clicking over the mark and using the popup 3D toolbar. End users can rotate, scale and move 3D data, as well as change lights and views settings.

Ruler

The Ruler mark enables the end user to create a line that displays its measurement.

Edit Mode: To create a measured line, the end users:

  1. Click on the Ruler button.
  2. Click the left mouse button where the end of the line begins and drag it to the end of the line.
  3. Release the left mouse button to complete the line.
  4. Press the right mouse button to activate the popup Edit menu.

Protractor

The Protractor mark enables the end user to create an angle that displays the arc and the angle measurement.

Edit Mode: To create a measured angle, end users:

  1. Click the protractor button.
  2. Drag the mouse to create the first line of the angle.
  3. Click the left mouse button to end the first line. This click creates the vertex and begins the second line.
  4. Click the left mouse button where you want your second line to end. The measured angle is complete.
  5. Press the right mouse button after the mark is created to activate the popup Edit menu.

Encryption

The Encryption mark enables your users to scramble all or part of the image.

Edit mode: End users create this mark by clicking the Encryption button with the left mouse button and then dragging the resulting rectangle over the area to be scrambled.

NOTE: Encrypted marks cannot overlap.

Button

The Button mark places a programmable button on an image. For example, a button can be programmed to zoom into part of an image.

Edit Mode: In the Edit mode, end users create this mark by clicking on the Button button with the left mouse button and then dragging the resulting mark to its destination. The button can be resized by dragging the resize handles. You can set your application to respond to a right-mouse click by displaying the properties box and selecting the appropriate property. Your user can set several attributes for a button, including font, foreground color, background color and text.

When the application is in Run mode, the cursor changes to a pointing hand when it passes over the Button bitmap.

Hot Spot

The Hot Spot mark enables the end user to define an invisible region in a document or image that can be used to hold hidden messages.

Edit Mode: In Edit mode, end users create this mark by clicking the Hot Spot button with the left mouse button, dragging the image, and then releasing the left mouse button. When the left mouse button is released, the resulting rectangle becomes the hot spot region. It remains visible while the application is in edit mode. Pressing the right mouse button after the mark is created activates the popup edit menu.

Run Mode: When a user passes the cursor over this region, the cursor changes, indicating that there is something special about the contents within the invisible region. If the user clicks the left mouse button while the cursor is in the region, your application sends a message detailing the information about the contents of the region.

NOTE: The Hot Spot region is visible only when the application is in Edit mode.

Rich Text

The Rich Text mark enables end users to edit, load, and display RTF text.

Edit mode: In Edit mode, end users create this mark by clicking the Rich Text button with the left mouse button and then dragging the resulting rectangle over the area to be annotated. The RTF Editor Tool allows users to load RTF files and edit the RTF text using the menu and toolbar buttons.

ART 2.0 Legacy Marks

Arrow

The Arrow mark enables the end user to create an arrow over an image or document. It allows users to point to areas of a document that may be of interest to its reader.

Edit Mode: Users of the completed application can create this mark by clicking the Arrow button with the left mouse button, dragging the image, and then releasing. The head of the arrow is drawn at the point where the left mouse button is first pushed, and the tail (end) of the arrow is set at the location where the left mouse button is released. Pressing the right mouse button after the mark is created activates the popup edit menu.

Filled Rectangle

The Filled Rectangle mark enables end users to cover areas of an image or document with a rectangle.

Edit Mode: In Edit mode, end users create this mark by clicking the Filled Rectangle button with the left mouse button and then dragging the resulting rectangle over the items to be covered. Pressing the right mouse button after the mark is created activates the popup edit menu.

Hollow Rectangle

The Hollow Rectangle mark enables users to surround areas of an image or document with a hollow rectangle.

Edit Mode: In Edit mode, end users of your application create this mark by clicking the Hollow Rectangle button with the left mouse button and then dragging the resulting rectangle over the items to be surrounded. Pressing the right mouse button after the mark is created activates the popup edit menu.

Filled Ellipse

The Filled Ellipse mark enables end users to cover areas of an image or document with an ellipse.

Edit Mode: In the edit mode, end users create this mark by clicking the Filled Ellipse button with the left mouse button, dragging the image, and then releasing the left mouse button. Pressing the right mouse button after the mark is created activates the popup edit menu.

Hollow Ellipse

The Hollow Ellipse mark enables the end user to create a hollow ellipse to surround important areas.

Edit Mode: In Edit mode, end users of the completed application create this mark by clicking the Hollow Ellipse button with the left mouse button, dragging the image, and then releasing the left mouse button. Pressing the right mouse button after the mark is created activates the popup edit menu.

Filled Polygon

The Filled Polygon mark enables the end user to cover areas of an image or document with a polygon.

Edit Mode: To create a Filled Polygon mark, end users:

  1. Click the left mouse button at the point where the polygon starts.
  2. Drag the mouse to the location of a vertice and click the left mouse button.
  3. Repeat step 2 to add the desired number of vertices to the polygon, clicking the left mouse button to add a vertice.
  4. Double-click the left mouse button to complete the polygon.
  5. Press the right mouse button after the mark is created to activate the popup Edit menu.

Hollow Polygon

The Hollow Polygon mark enables the end user to surround areas of an image or document with a polygon.

Edit Mode: To create a Hollow Polygon mark, end users:

  1. Click the left mouse button at the point where the polygon starts.
  2. Drag and click the left mouse button to create each vertice you want to add.
  3. Double-click the left mouse button to complete the polygon.
  4. Press the right mouse button after the mark is created to activate the popup edit menu.

Redaction

The Redaction mark enables end users to hide or black out areas of their annotated image or document.

Edit Mode: In Edit mode, end users create this mark by clicking the Redaction button with the left mouse button and then dragging the resulting rectangle over the items they wish to cover. The rectangle covers whatever is underneath it. Pressing the right mouse button after the mark is created activates the popup Edit menu.

Highlighter

The Highlighter mark enables end users to highlight areas of their annotated image or document.

Edit Mode: In Edit mode, end users:

  1. Create this mark by clicking the Highlighter button with the left mouse button and then dragging the resulting rectangle over the items they wish to cover.
  2. The resulting rectangle highlights whatever is underneath it.
  3. Pressing the right mouse button after the mark is created user activates the popup Edit menu.

Typed Text

The Typed Text mark enables the end user to add descriptive text to their annotated image or document. The text can be created in various fonts, sizes, colors. The text appears over the original image or document.

Edit mode: End users create this mark by clicking the Typed Text button with the left mouse button and then dragging the resulting rectangle over the area to be annotated. This rectangle helps to position the Text annotations. Text annotations are easily modified when the application is in the Edit mode. To modify it, the end user double-clicks the left mouse button when the cursor is over the text mark. The cursor appears at the beginning of the text, and transforms to allow editing.

NOTE: If end users create a text mark without any text with a Transparent background, the resulting mark will exist but will not be visible.

Text Stamp

The Text Stamp mark allows the end user to annotate documents and images with text.

Edit Mode: In Edit mode, end users create this mark by clicking on the Text Stamp button with the left mouse button. Pressing the right mouse button after the mark is created activates the popup Edit menu, which allows you to enter the text of the stamp.

Attach-a-Note

The Attach-A-Note mark enables your end users to add notes to their annotated image or document.

Edit Mode: In the edit mode, end users create this mark by clicking the Attach-A-Note button with the left mouse button and then dragging the resulting rectangle over the area to be annotated.

Pressing the right mouse button activates the popup menu that enables users to change the font or the background colors of the note.

The Choose Font option displays a dialog box that allows users to change text properties. If the application is in Edit mode, and an end user wants to modify the text, they simply double-click the left mouse button when the cursor is over the note. The cursor appears at the beginning of the text to allow editing.

The Set Background Color option enables end users to change the color of the note. When this option is selected, a dialog box appears with a range of options.

Text from File

The Text From File mark enables the end user to add descriptive text to an annotated image or document. The text can be created in various fonts, sizes, colors, and even angles of presentation. The text appears to lay over the original image or document.

Edit mode: End users create this mark by clicking the Text From File button with the left mouse button and then dragging the rectangle over the area to be annotated. This rectangle helps to position the Text annotations. Text annotations are modified when the application is in Edit mode. To modify the text, the end user double-clicks the left mouse button when the cursor is over the text mark. The cursor appears at the beginning of the text, and transforms to allow editing.

While creating this mark and entering text, end users use the right mouse button to access a popup menu that enables them to change several attributes of the mark.

  • Choose Fontoption allows users to select the color of the text fonts.
  • Adjust Angle option enables end users to rotate the text mark with a dialog box. The square at the lower left corner of the Adjust Angle dialog box shows the appearance of the text mark with the selected text display angle.
  • Set Background Color option is identical to the one available while creating the Attach-a-Note mark.
  • Set Background Mode option enables end users to change the visibility level of the region within the Text mark. When this option is selected, a dialog box appears.
      • If Transparent is selected, the interior of the text mark is not visible; only the text is visible.
      • If Opaque is selected, end users are not able to see through the interior of the text mark.
      • If Tinted is selected, the text mark resembles a tinted glass. End users are able to see through the mark.
NOTE: If end users create a text mark without any text with a Transparent background, the resulting mark will exist but will not be visible.

Pin Up Text

The Pin Up Text mark enables the user to create a mark that appears to be tacked onto the image with a push pin.

Edit Mode: This mark can have an optional label. The label indicates which data can be obtained by clicking on the pin in while in Run mode. You can add code to the MouseNotify event to display additional data when the push pin is pressed

Image Embedded

The Image Embedded mark enables the end user to embed a bitmap image in a document or image.

Edit Mode: In Edit mode, end users embed an image by clicking the Image Embedded button with the left mouse button, dragging the image, and then releasing the left mouse button. When the left mouse button is released, the image becomes imbedded. Once the bitmap is in place on the annotation window, it can be re-sized by using the left mouse button. Pressing the right mouse button over the mark to activate the popup edit menu.

Image Embedded marks are intended for use with bitmaps that use no more than the standard 20 Windows colors. Therefore, 1-bit and 4-bit bitmaps are allowed. If you try to display an 8-bit bitmap in the mark, it is displayed using only the standard 20 colors.

Image Reference

The Image Reference mark enables the end user to include an image by reference in a document or image.

Edit Mode: In Edit mode, end users reference an image by clicking the Image Reference button with the left mouse button, dragging the image, and then releasing the left mouse button. When the left mouse button is released, an image is displayed. To insert an image, press the right mouse button over the mark to activate the popup Edit menu and choose Properties. Select the image you wish to reference.


PDF Marks

ImageGear ART can convert ART marks to PDF annotations and PDF annotations to ART marks giving the user an ability to edit PDF annotations using the same ImageGear ART GUI.

The following table lists all the ART marks that can be converted to PDF annotations and describes how the marks are being converted:

ART Marks
PDF Annotations
Ellipse
Circle
Hot Spot
Link
Image (vector)
3D
Legacy Arrow
Line
Legacy Attach-A-Note
FreeText
Legacy Filled Ellipse
Circle
Legacy Filled Polygon
Polygon
Legacy Filled Rectangle
Square
Legacy Highlighter
Square
Legacy Hollow Ellipse
Circle
Legacy Hollow Polygon
Polygon
Legacy Hollow Rectangle
Square
Legacy Redaction
Square
Legacy Text From File
FreeText
Legacy Text Stamp
FreeText
Legacy Typed Text
FreeText
Line
Line
Polygon
Polygon
Polyline and Freehand Polyline
PolyLine
Rectangle
Square
Rich Text (RTF)
FreeText
Text
FreeText

The following PDF annotations can be converted to ART marks:

PDF Annotations
ART Marks
3D
Image (vector)
Circle
Ellipse
FreeText (RTF style text)
Rich Text
FreeText (simple style text)
Text
Line
Line
Link
Hot Spot
Polygon
Polygon
PolyLine
Polyline
Square
Rectangle


Using ImageGear ART Component

NOTE: You can only attach one ART component. ART cannot be attached when ARTX is already attached.

ImageGear ART Component helps developers to add redlining and annotation capabilities to any application built with ImageGear. If you have an application that can read, display, and print images, with ART component attached you can add marking capabilities, such as arrows, highlighting, and sticky notes to documents images, and use them as though you were working on printed sheets of paper. You can design applications that allow end users to easily access mark objects from the ART toolbar. You can also add your own mark objects to the toolbar. Some of marks, such as the Ruler and Protractor, are especially useful when combined with DICOM images.

To save marks created for an image either:

  • Save the annotations in a separate .ART file,
  • "Burn in" the annotations permanently, or
  • Save the annotations in the header of a TIFF image.

You may also combine these methods. You can, for example, leave classified information in an ART file and "burn in" non-classified information into the image. ART and ImageGear support the .ART file extension. You can print the resulting image with or without the marks.


Loading the ART Component

If you are going to use ART component functionality in your application you should attach ART component ("ART") using ImageGear Component Manager API. Please, see the section Component Manager API for more detailes for this process as well as for the information how to make a call for ART component functions. Remember that you should make #include for ART public header i_ART.h in your application.


Working with ART Marks

Once you attach ART component you can annotate any image that you load into ImageGear. ART internally tracks the marks that are associated with an image. The end-user can save the image with the marks in a separate file with the .ART filename extension. Anytime the image is reloaded, a simple import call is used to "re-apply" the annotations.

You can also "burn in" the marks so they become part of the image and are not stored separately.

If the image is saved as a TIFF file, the annotations are automatically embedded in the TIFF file.

NOTE: This option can be disabled - See Saving Marks to File.

If a TIFF file with embedded annotations is loaded, the annotations are automatically "re-applied."

ART annotations saved to a separate file (.ART) can be read only by software that supports .ART files, such as ImageGear and the Imaging for Windows 95 and Imaging for Windows NT Wang products.

Components of a Mark

All mark objects contain the following components:

  • A Mark Attributes structure
  • An index block
  • A group block

The Mark Attributes structure is a set of attributes associated with a mark object. Attributes that do not apply are ignored.

The index block contains an unique number that is used for the mark object identification. When new mark object is created its index is generated (by incrementing 1 to the number just assigned) and stored in the global index block.

This unique number (32-bit unsigned integer) is used to refer to the mark in many of ART's operations. It cannot be modified.

The group block contains a NULL-terminated string that acts as the name of the block. It is initialized to the value contained in the global group block. If you have not set the global group block, a default value of "(Untitled)" is used. See the section ART Component Important Structures and Types or i_ART.h for more information about these structures.

ART refers to all data blocks associated with marks as "named blocks." Each data block has a unique 8-byte name for identification. All names that are less than 8 bytes are padded with NULLs. The ART component uses two kinds of named blocks:

  • mark blocks
  • global blocks

Mark blocks contain data for individual marks. Global blocks contain data that is used to define the next mark created, as well as to store data that is not associated with an individual mark.

This diagram above shows the components of a mark. Central to any mark is the Mark Attributes structure. In addition, each mark contains a pointer to a list that includes the index and group blocks and other mandatory blocks, that vary depending on the type of mark, and an unlimited number of user-defined blocks. User-defined blocks contain data that might be useful to the developer.

You can define as many user-defined blocks as you want. Information that might be stored in a user-defined block includes:

  • who last edited the file or mark
  • user preferences, such as preferred line thickness

Note that the block shown in the list can occur in any order.

When a mark is created by the end user from the ART toolbar, a mark attributes structure is created and filled automatically with global settings, that can be modified using ART_GUI_tool_set (). If there are other mandatory blocks pertaining to the type of mark created, these are created automatically by ART and filled with values from global blocks. The global blocks are previously initialized.

When a mark is created using ART_mark_create (), which is a lower-level method of creation, the group and index blocks are created automatically; any other mandatory blocks pertaining to the type of mark created need to be added one at a time using the ART_mark_block_create () function.

The following named blocks are defined by ART in the i_ART.h file. Each of these ones have a corresponding global block to hold default values for toolbar created marks:

ART_BLOCK_ANODAT
Used by many mark types to hold points and rotation information
ART_BLOCK_FILNAM
Name of file used for Image Reference, Text from File, and Audio
ART_BLOCK_DIB
Embedded DIB image
ART_BLOCK_GROUP
Name of group the mark belongs to
ART_BLOCK_INDEX
Unique index number for mark
ART_BLOCK_ANTEXT
For text mark types. Orientation and length of text, in bytes.

Creating a Mark with End-User Interaction

End users can create a mark using the ART toolbar, or developers can created them "manually" by using lower-level calls. This section describes how to create marks with user interaction through the ART toolbar.

NOTE: You may create your own marks and have them appear automatically on any image loaded while ART is also loaded, by registering the LPFNIG_ART_DRAWNOTIFYFUNC callback function.

When a button is selected from the toolbar, ART updates the mark's attributes as the user modifies it. Once the end user creates the mark, control returns to the application.

The following constants define the mark types:

ART_MARK_IMAGE_EMBEDDED
ART_MARK_FILLED_POLYGON
ART_MARK_IMAGE_REFERENCE
ART_MARK_HOLLOW_POLYGON
ART_MARK_STRAIGHT_LINE
ART_MARK_POLYLINE
ART_MARK_FREEHAND_LINE
ART_MARK_AUDIO
ART_MARK_HOLLOW_RECTANGLE
ART_MARK_HOLLOW_ELLIPSE
ART_MARK_FILLED_RECTANGLE
ART_MARK_FILLED_ELLIPSE
ART_MARK_TYPED_TEXT
ART_MARK_ARROW
ART_MARK_TEXT_FROM_FILE
ART_MARK_HOT_SPOT
ART_MARK_TEXT_STAMP
ART_MARK_REDACTION
ART_MARK_ATTACH_A_NOTE
ART_MARK_ENCRYPTION
ART_MARK_FORM
ART_MARK_RULER
ART_MARK_PROTRACTOR
ART_MARK_BUTTON
ART_MARK_PIN_UP_TEXT
ART_MARK_HIGHLIGHTER
ART_MARK_RTF_EDIT

Call the function ART_GUI_toolbar_create () to display the toolbar. You then set the case statements in the LPFNART_GUI_TOOLBARNOTIFYFUNC callback function for each button. The function ART_GUI_toolbar_button_get () tells the status of any button on the toolbar. ART automatically initializes whatever blocks are needed by the mark with global settings. The global settings are set prior to the mark being created; the best place to do that is the case statement for each type of mark in the LPFNART_GUI_TOOLBARNOTIFYFUNC callback function.

ART makes internal calls to create the mark object. Modifications to the attributes structure are made interactively by ART as the end user drags, drops and re-sizes a mark. Here is a short example case statement that is used for a HOT SPOT mark that is created from the toolbar:

ART_MARK_ATTRIBUTES ma; /* Mark Attributes Structure */
. . .
switch (dwButtonID)
{
case ART_BUTTON_HOT_SPOT:
ma.dwType = ART_MARK_HOT_SPOT;
ma.rgbColor1.rgbRed   = 0xFF;
ma.bVisible = TRUE;
ART_GUI_tool_set(hIGear, &ma);
ART_GUI_interaction_process(hIGear, IG_GRP_DEFAULT, hWnd, msg,
nUserMode, &pt);
break;

Call ART_GUI_interaction_process () when a button is pressed down over the image is. When the user mode parameter is set to ART_MODE_EDIT and the left mouse button is pressed over the image, ART takes control of all Windows messages received during creation. When the mark is finished, control returns to your application the line after ART_GUI_interaction_process().

NOTE: You should set the ART user mode to ART_MODE_VIEW to give ImageGear back control of the mouse functions.

Creating a Mark Using Low-Level Calls

If you need to create a mark without the end user, call ART_mark_create (). You supply this function a structure of type ART_MARK_ATTRIBUTES, and it returns a unique index to the mark.

ART_mark_create() automatically creates the index and group blocks for your object. You have to add other required named blocks (their types depend on the mark object) one at a time using ART_mark_block_create_ex (). To see what blocks are required by each mark type look at the section Mark Objects: Descriptions, Types and Attributes .To display the mark call ART_GUI_mark_paint ().

Modifying Marks

Most often, marks are modified interactively by the end user. Whether a mark can be modified depends on its access setting. A mark has write-access or is read-only. Access can be applied to a group of marks. See Working With Mark Groups section for a discussion about group operations.

To check the access of a mark, call ART_mark_is_access_granted (). To set the access of a mark, call ART_mark_access (). To set the access for a group of marks, call ART_group_access ().

There are differences in the way you handle modifying marks, depending on who modifies the mark - you or the end user. See below Modifying Marks By the End User and .

Modifying Marks By the End User

The end user modifies a mark by clicking the mouse over it. When you receive the Windows message WM_LBUTTONDOWN, call ART_GUI_interaction_process (). ART automatically updates the mark's attributes structure and appropriate blocks when the user is modifying the mark.

Another way to allow the end user to modify a mark is to set up "property sheets" for each mark object. Use ART_GUI_property_sheet_create () to obtain a handle to a property sheet. ART automatically creates a property sheet that is appropriate for the type of mark modified. The property sheet for each mark is different. Control is passed back to the application once the end user clicks OK. ART_GUI_property_sheet_create() simply returns a handle to a property sheet - it does not display it or get the user's input. The following sequence of calls processes property sheets:

ART_GUI_property_sheet_create ()
Get the handle to a property sheet
ART_GUI_property_sheet_init ()
Initialize values to mark attributes structure's values and one or more named blocks.
ART_GUI_property_sheet_show ()
Displays the property sheet. When this function returns, the property sheet will disappear from the screen.
ART_GUI_property_sheet_query ()
Query the mark attributes and one or more named blocks.
ART_GUI_property_sheet_destroy ()
Free the property sheet resource.

If ART_GUI_property_sheet_show () returns TRUE, it means the user pressed OK and the user might have caused the mark attributes or named blocks to be changed. Call ART_mark_modify () to make the changes permanently to the mark attributes structure. Call ART_mark_block_create () to overwrite the old data with the new. To redraw the mark with the new attributes, call ART_GUI_mark_paint ().

Modifying Marks Programmatically

To modify marks programmatically, you set the attributes for block data, and call ART_mark_modify () or ART_mark_block_create_ex () to update that information. Call ART_GUI_mark_paint () to see the changes.

Deleting Marks

To delete a mark, call ART_mark_delete () with the index number you supply. To delete a group of marks, call ART_group_delete (). When a mark is deleted, the unique index identifiers of the remaining marks are not changed.

The callback function LPFNIG_ART_DELETENOTIFYFUNC is used to create a function that is called each time the user tries to delete a mark. If you return TRUE from a callback of this type, the mark is deleted.

Clipboard Operations

ART marks can be cut from and copied to the clipboard as well as pasted into an image individually or in groups.

The names of all functions that handle clipboard operations begin with ART_edit_. This group includes functions that undo changes made to marks. See the next section for a discussion about performing undos.

ART_edit_copy ()
Copies an array of marks to the clipboard
ART_edit_cut ()
Cuts an array of marks to the clipboard
ART_edit_paste ()
Pastes any available marks from the clipboard into the current HIGEAR image
ART_edit_paste_count ()
Queries the clipboard for the number marks available for pasting

To see the results of cutting or pasting the marks associated with an image, call ART_GUI_mark_paint () function.

Undoing Edits

As with Clipboard operations, undo begins with ART_edit_. The scope is determined by what is recorded. ART component supplies the following functions for "undoing edits":

ART_edit_undo_enable ()
Enable or disable undo operations.
ART_edit_undo ()
Reverses any changes made to any mark
ART_edit_undo_clear ()
Clears all pending undos from memory
ART_edit_undo_count ()
Returns (in lpUndoCount) the number of times that ART_edit_undo()can be called (you can limit your undo loop)
ART_edit_undo_record ()
Enables or disables the recording of every action

The example below shows ART_edit_undo_record() being set "on" before each mark in the image is deleted. Once the deletion loop has been completed, recording is shut "off" by calling ART_edit_undo_record () a second time with the last argument set to FALSE

/* Record all the deletes so that when an ART_edit_undo()  */
/* is called, the deleted marks will be restored at once,  */
/* instead of being restored individually. */
ART_edit_undo_record(hIGear, TRUE);
ART_mark_selected_first(hIGear, &hMarkIndex);
while (hMarkIndex != ART_INVALID_ID)
{
hMarkDelete = hMarkIndex;
ART_mark_selected_next(hIGear, &hMarkIndex);
ART_mark_delete(hIGear, hMarkDelete);
}
/* Turn off undo recording */
ART_edit_undo_record(hIGear, FALSE);
ART_GUI_mark_paint(hIGear,
IG_GRP_DEFAULT, ART_INVALID_ID, hWnd, TRUE);

A call to ART_edit_undo () restores all marks that were modified while recording was on. This means that all deleted marks are restored at once. If ART_edit_undo_record () was not used, then ART_edit_undo() would have to be called many times to restore all of the deleted marks.

Iterating Through Marks

ART component provides two functions that iterate through all of the marks associated with the current HIGEAR image. ART_mark_first () returns the index of the first mark. ART_mark_next () returns the index of the next mark. To iterate through all marks, call ART_mark_first(), then call ART_mark_next() within a loop, with a line such as:

ART_mark_first(hIGear, &hMarkIndex);
while (hMarkIndex != ART_INVALID_ID)
{
...
   ART_mark_next(hIGear, &hMarkIndex);
}

ART returns ART_INVALID_ID when there are no more marks to iterate through.

As you iterate through the marks, you can pass the returned index of each mark to any of the mark modification functions.

Iterating Through Blocks

ART supplies functions that let you iterate through both global blocks and mark blocks. To iterate through global blocks, use ART_global_block_first () and ART_global_block_next (). To iterate through the blocks that belong to an individual mark, use ART_mark_block_first () and ART_mark_block_next ().

All of these block iteration functions set the block name to NULL when there are no more blocks to iterate through.

ART Textflow Functionality

The ART textflow functionality allows to process several separated text marks as single text document. It includes the possibilities of checking of the text overflowing, calculating of the preferable mark bounds to draw the mark text in and automatical moving of the overflowed text from one text mark to another one.

The textflow functionality consists of two following functions:

  • ART_GUI_text_flow () - This function links texts of given annotation marks and distributes it between these marks according to their bounds so that all of them do not have overflowed text excluding may be the last one.
  • ART_GUI_text_overflow_check () - This function checks the mark with text overflowed.

And of one callback function:

  • LPFNIG_ART_TEXTOVERFLOWNOTIFYFUNC - This callback function provides you with the possibility to change the mark bounds or apply ART_GUI_text_flow()function after resizing of the text mark bounds.

Currently ART textflow functionality can be applied only for Typed Text, Attach-a-Note and TEXT From FILE mark types.

Working With Mark Groups

Each mark received a group name when it is created. If you do not assign it a name, ART assigns it the default group name "(Untitled)". Group names provide a convenient way to associate groups of marks so that you can modify, delete, send to the front or back of the stacking order, change access, perform clipboard operation, and select attributes.

The group name for the next mark created comes from the Global Group Block. To set it to a new name, you need to overwrite the block in the following manner:

LPSTR lpszGroup = "New Group";
ART_global_block_create(hIGear, ART_BLOCK_GROUP, lpszGroup,
lstrlen(lpszGroup) + 1);

All named block names that are less than 8 bytes must be padded with NULLs. See ART Component Important Structures and Types for the composition of a Global Group Block structure.

All names of functions that operate on groups begin with ART_group_. Here are the names of the functions that operate on groups:

ART_group_access ()
Sets access of a group to allow for edit or read only access.
ART_group_bring_to_front ()
Moves group to the front of the stacking order.
ART_group_delete ()
Deletes a group.
ART_group_edit_copy ()
Copies a group to the clipboard.
ART_group_edit_cut ()
Cuts a group to the clipboard.
ART_group_select ()
Selects all marks in a group.
ART_group_send_to_back ()
Sends a group to the back of the stacking order.
ART_group_visible ()
Makes marks visible or invisible.

Use ART_edit_paste () and ART_edit_paste_count () to perform paste operations on groups of marks.

Saving Marks to File

When the set of marks belonging to a HIGEAR image are saved, they can be saved separately into a file with filename extension ".ART", burned permanently into the image, or embedded into an image file. You can embed marks into TIFF files only.

  • To save the marks to an .ART file, call the ART_file_export (), method, supplying the name of the .ART file to export. If an .ART file exists you can set a flag to indicate whether the new file replaces or overwrites the existing file. You can also append new mark objects to the existing ART file. If the existing file has multiple pages you can specify which page the new file overwrites, or where it should be inserted.
  • To burn the marks into the image, call the ART_image_burn_in () function. Marks can be burned in by group, list, selection, etc., depending on what setting you choose. See Chapter "ART Component API Function Reference" for more detailed information.

If you are saving a TIFF file, the annotations are automatically saved as an embedded file. Use ART_control_option_set ()with the appropriate setting if you do not want the annotations to be embedded into the file:

nErrcount=ART_control_option_set(hIGear,
ART_CONTROL_SAVE_ENABLE, FALSE)"

Importing Marks to an Image

An .ART file can be imported into any loaded HIGEAR image as long as the ART component is attached. If the .ART file to import has multiple pages, you can specify the number of the page to load. To import an .ART file for association with the current HIGEAR file call ART_file_import ().

To import/export .ART files using Internet please use the functions ART_internet_import () and ART_internet_export ().

Edit Mode vs. Run Mode

ART component applications can operate in three different modes:

  • Edit mode lets users create or edit marks.
  • Run mode lets users operate on hot spot, audio, and button activities.
  • View-only mode allows users to view marks--not add or modify them.

It is recommended that you set your application to be in Edit mode any time a toolbar button is selected, and that you set it to Run mode when none of the buttons on the toolbar are selected.

To set your application mode, use the ART_GUI_interaction_process () function using one of these constants:

  • ART_MODE_EDIT
  • ART_MODE_RUN
  • ART_MODE_VIEW
  • LPFNIG_ART_MODIFYNOTIFYFUNC
  • LPFNIG_ART_OVERRIDEDRAWNOTIFYFUNC
  • LPFNIG_ART_PREMODIFYNOTIFYFUNC
  • LPFNIG_ART_SELECTNOTIFYFUNC


ART Component Important Structures and Types

Some arguments in ART component function calls are pointers to the internal ART component structures and data types such as ART_MARK_ATTRIBUTES structure that determines general attributes used by every ART mark. There are such important data types as ART component named blocks (ART_NAMED_BLOCK) that determine, for instance, mark's coordinates and orientation (ART_BLOCK_ANODAT) or the name of file for image marks (ART_BLOCK_FILNAM). For the full list of structures and data types currently provided by ART component please see i_ART.h file.

  • You can see ART_MARK_ATTRIBUTES structure reference below:

Declaration:

typedef struct tagART_MARK_ATTRIBUTES {
DWORD dwType;
AT_RECT rcBounds;
AT_RGBQUAD rgbColor1;
AT_RGBQUAD rgbColor2;
DWORD bHighlighting;
DWORD bTransparent;
DWORD dwLineSize;
LONG lReserved1[2];
AT_LOGFONT lfFont;
LONG dwReserved2;
DWORD dwTime;
DWORD bVisible;
LONG lReserved3[11];
}
ART_MARK_ATTRIBUTES, FAR *LPART_MARK_ATTRIBUTES;

Structure Members:

dwType
The type of the mark:
1 = Image Embedded
2 = Image Reference
3 = STRAIGHT LINE
4 = FREEHAND LINE
5 = HOLLOW RECTANGLE
6 = FILLED RECTANGLE
7 = Typed Text
8 = TEXT From FILE
9 = Text Stamp
10 = Attach-a-Note
12 = Form
500= FILLED POLYGON
501= HOLLOW POLYGON
502= POLYLINE
503= Audio
504= FILLED ELLIPSE
505= HOLLOW ELLIPSE
506= Arrow
507= HOT SPOT
508= REDACTION
509= Encryption
510= Ruler
511= Protractor
512= BUTTON
513= Pin Up Text
514= Highlighter
515= RTF
rcBounds
Rectangle in image units. Can be a rectangle or two points.
rgbColor1
The main color; for example, the color of all lines, all rectangles, and standalone text.
rgbColor2
The secondary color; for example, the color of the text of an Attach-a-Note.
bHighlighting
If TRUE the mark is drawn highlighted. Highlighting performs the same function as a highlighting marker on a piece of paper. Valid only for lines, rectangles and freehand.
bTransparent
If TRUE the mark is drawn transparent. A transparent mark does not draw white pixels: transparent replaces white pixels with whatever is behind those pixels. Available only for images.
dwLineSize
The width of the line in pixels.
NOTE: It is ignored when setting dwPenStyle for a straight line mark.
lReserved1[2]
Reserved; must be set to 0.
lfFont
The font information for the text, consisting of standard font attributes of font size, name, style, effects, and background color.
dwReserved2
Reserved; must be set to 0x0FF83F.
dwTime
The time that the mark was first saved, in seconds, from 00:00:00 1-1-1970 GMT. Every annotation mark has time as one of its attributes. If you don't set the time before the file is saved, the time is set to date and time that the save was initiated. This time is in the form returned by the "time" C call, which is the number of seconds since midnight 00:00:00 on 1-1-1970 GMT. If necessary, refer to your C manual for a more detailed description.
bVisible
If TRUE the mark is currently set to be visible. Annotation marks can be visible or hidden.
Reserved3[11]
First 9 elements and Reserved[10] are reserved and must be set to 0.
Value Reserved[9] is used by ImageGear to store DISABLE_PPM_FOR_FONTS mark attribute. Its interpretation is identical with global control parameter ART_CONTROL_DISABLE_PPM_FOR_FONTS but affects only one annotation.
2 helper macro-functions has been introduced to get and set this attribute.
  • AT_BOOL ART_DISABLE_PPM_FOR_FONTS_GET(LPART_MARK_ATTRIBUTES pMa);
  • AT_BOOL ART_DISABLE_PPM_FOR_FONTS_SET(LPART_MARK_ATTRIBUTES pMa, AT_BOOL bNewValue);

  • Below there are definitions for ART component named blocks:
/* Coordinates and orientation      */
#define ART_BLOCK_ANODAT					((const LPART_BLOCK_NAME)"OiAnoDat")
/* Hold a file name for image marks */
#define ART_BLOCK_FILNAM					((const LPART_BLOCK_NAME)"OiFilNam")
/* Stores DIB data                  */
#define ART_BLOCK_DIB				((const
LPART_BLOCK_NAME)"OiDib\000\000\000")
/* Create sets of marks             */
#define ART_BLOCK_GROUP					((const LPART_BLOCK_NAME)"OiGroup\000")
/* Unique ID for each mark          */
#define ART_BLOCK_INDEX					((const LPART_BLOCK_NAME)"OiIndex\000")
/* Text for annotation marks        */
#define ART_BLOCK_ANTEXT					((const LPART_BLOCK_NAME)"OiAnText")


Mark Objects: Descriptions, Types and Attributes

This section describes each mark available in ImageGear ART component, and its associated attributes.

NOTE: Some ART marks, such as Attach-a-Note, Text Stamp, Typed Text, may require Wang compatibility mode enabled to be saved properly. On the contrary Highlighter mark should be saved without Wang compatibility mode on.
TIP: Wang/Kodak viewer included with Windows would only understand Wang- compatible annotations.
NOTE: These constants define a range of user marks reserved for customer use. ImageGear will never use this range of the mark IDs for its purposes.
#define ART_MARK_USER_FIRST 1000
#define ART_MARK_USER_LAST 1999

Arrow

The Arrow mark enables the end user to create an arrow over an image or document. It allows users to pointing to areas of a document that may be of interest to its reader.

Edit Mode: Users of the completed application can create this mark by clicking the Arrow button with the left mouse button, dragging the image, and then releasing. The head of the arrow is drawn at the point where the left mouse button is first pushed, and the tail (end) of the arrow is set at the location where the left mouse button is released. Pressing the right mouse button after the mark is created activates the popup edit menu.

Description
A line with a defined starting and ending point. An arrow head appears at the starting point.
Attributes
rgbColor1, bHighlighting, dwLineSize
OiGroup
String
OiIndex
String
OiAnoDat
ART_ARROW. This structure includes the following members:
  • lArrowType - Type of arrow head; valid values are 0 (ART_ARROW_POINTER), 1(ART_ARROW_SOLID), 2 (ART_ARROW_OPEN) and 3 (ART_ARROW_POINTER_SOLID)
  • lArrowAngle - The angle from the line to the outside edge of the arrow head. 15 is the default
  • lArrowLength - Length in image units of the arrow head. 25 is the default
  • lArrowEnd - Which end of the line the arrow head is to appear. Set to 0 for first point, set to 1 for second point
  • lReserved - Set to 0
  • apPoints - End points of the arrow

Attach-a-Note

The Attach-A-Note mark enables your end users to add notes to their annotated image or document.

Edit Mode: In the edit mode, end users create this mark by clicking the Attach-A-Note button with the left mouse button and then dragging the resulting rectangle over the area to be annotated.

Pressing the right mouse button activates the popup menu that enables users to change the font or the background colors of the note.

The Choose Font option displays a dialog box that allows users to change text properties. If the application is in Edit mode, and an end user wants to modify the text, they simply double-click the left mouse button when the cursor is over the note. The cursor appears at the beginning of the text to allow editing.

The Set Background Color option enables end users to change the color of the note. When this option is selected, a dialog box appears with a range of options.

Description
A colored rectangle that contains text.
Attributes
rgbColor1, rgbColor2, lfFont
OiGroup
String
OiIndex
String
OiAnText
ART_TEXTPRIVDATA. This structure includes the following members:
  • lOrientation - Angle of text baseline to image in tenths of a degree; valid values are 0, 900, 1800, 2700.
  • lAlign - See ART_TEXT_xxx bitflags
  • lReserved - Not in use
  • lAnoTextLength - 64K byte limit (32K for multi-byte data) for Attach-a-Note, typed text, text from file; 255 byte limit for text stamp
  • szAnoText - Text string for text mark types

Audio

The Audio mark enables end users to hear sounds when annotating an image or document. It is useful for drawing attention to a particular area of a text or image file. This mark plays a waveform audio file (.WAV).

Edit Mode: In Edit mode, end users create this mark by clicking on the Sound button with the left mouse button and then dragging the resulting mark (a loud-speaker-shaped bitmap) to its destination. To display the dialog box, the user double-clicks the left mouse button on the loud-speaker. This allows the user to specify the name of the .WAV file that plays during Run mode.

When the application is in the Run mode, the cursor changes to a pointing hand when it passes over the loud-speaker bitmap. As the mark is activated (makes a sound), lines representing sound waves appear and disappear from the end of the loud-speaker.

Description
A sound file (.wav) included by reference. If the file is not found when it is activated, an error returns.
Attributes
None
OiGroup
String
OiIndex
String
OiFilNam*
ART_NAME_STRUCT
OiAnoDat*
.WAV file

*Use either OiFilNam or OiAnoDat, not both.

BUTTON

The Button mark places a programmable button on an image. For example, a button can be programmed to zoom into part of an image. Actions are programmed by adding code to the LPFNIG_ART_MOUSENOTIFY_FUNC callback function.

Edit Mode: In the Edit mode, end users create this mark by clicking on the Button button with the left mouse button and then dragging the resulting mark to its destination. The button can be resized by dragging the resize handles. You can set your application to respond to a right-mouse click by displaying the properties box and selecting the appropriate property. Your user can set several attributes for a button including font, foreground color, background color and text.

When the application is in Run mode, the cursor changes to a pointing hand when it passes over the Button bitmap.

Description
A rectangular or oval button assigned to perform certain actions.
Attributes
rgbColor1, rgbColor2, lfFont
OiGroup
String
OiIndex
String
OiAnText
ART_TEXTPRIVDATA. This structure includes the following members:
  • lOrientation - Angle of text baseline to image in tenths of a degree; valid values are 0, 900, 1800, 2700.
  • lAlign - See ART_TEXT_xxx bitflags
  • lReserved - Not in use
  • lAnoTextLength - 64K byte limit (32K for multi-byte data) for Attach-a-Note, typed text, text from file; 255 byte limit for text stamp
  • szAnoText - Text string for text mark types

Encryption

The Encryption mark enables your users to scramble all or part of the image.

Edit mode: End users create this mark by clicking the Encryption button with the left mouse button and then dragging the resulting rectangle over the area to be scrambled. Pressing the right mouse button activates the popup menu that enables users to enter a password to unscramble the encrypted image section.

NOTE: Encrypted marks cannot overlap.

Description
A scrambled rectangle in the image. The operation is reversible if the correct cypher is applied.
Attributes
None
OiGroup
String
OiIndex
String
OiAnoDat
ART_ENCRYPTION. This structure includes the following members:
  • lMethod - Encryption method, set to 0
  • lReserved - Set to 0
  • szPassword - Encryption password, NULL terminated

FILLED ELLIPSE

The Filled Ellipse mark enables end users to cover areas of an image or document with a rectangle.

Edit Mode: In the edit mode, end users create this mark by clicking the Filled Ellipse button with the left mouse button, dragging the image, and then releasing the left mouse button. Pressing the right mouse button after the mark is created activates the popup edit menu.

Description
A filled ellipse whose boundaries are defined by a rectangle. Two points define the rectangle; an upper left point and a bottom right point.
Attributes
rgbColor1, bHighlighting, dwLineSize
OiGroup
String
OiIndex
String

FILLED POLYGON

The Filled Polygon mark enables the end user to cover areas of an image or document with a polygon.

Edit Mode: To create a Filled Polygon mark, end users:

  1. Click the left mouse button at the point where the polygon starts.
  2. Drag the mouse to the location of a vertice and click the left mouse button.
  3. Repeat step 2 to add the desired number of vertices to the polygon, clicking the left mouse button for each vertice.
  4. Double-click the left mouse button to complete the polygon.
  5. Press the right mouse button after the mark is created to activate the popup Edit menu.

    6. Description
    A series of lines where the starting point of line 1 is the same as the ending point of line n. The resulting polygon is filled with a solid color.
    Attributes
    rgbColor1, bHighlighting, dwLineSize
    OiGroup
    String
    OiIndex
    String
    OiAnoDat
    ART_POINTS. This structure includes the following members:
    • lMaxPoints - The maximum number of points; must be equal to the value of nPoints.
    • lPoints - The current number of points
    • ptPoint - Points marking the beginning and ending of the line segment(s); in image (not scaled) coordinates relative to the upper left corner of rcBounds in ART_MARK_ATTRIBUTES.

FILLED RECTANGLE

The Filled Rectangle mark enables end users to cover areas of an image or document with a rectangle.

Edit Mode: In Edit mode, end users create this mark by clicking the Filled Rectangle button with the left mouse button and then dragging the resulting rectangle over the items to be covered. Pressing the right mouse button after the mark is created activates the popup edit menu.

Description
A rectangle with a filled center.
Attributes
rgbColor1, bHighlighting
OiGroup
String
OiIndex
String

Form

The Form mark enables the developer to insert a bitmap image in a document or image. The inserted image must be the same size as the image or document it covers and must be one bit per pixel.

The Form mark is not on the toolbar. To use this mark the developer must call the ART_mark_create() function. This mark cannot be accessed by the end user.

Description
A black and white image included by an indirect reference. Only one Form mark is allowed per image. It is placed on top of the base image before all other marks. If the image is not found at display time, an error is returned.
Attributes
bTransparent (must be set)
OiGroup
String
OiIndex
String
OiFilNam
ART_NAME_STRUCT
OiAnoDat
ART_NEW_ROTATE. This structure includes the following members:
  • lRotation - 1 = Original, 2 = Rotate right (90 degrees clockwise), 3 = Flip (180 degrees clockwise), 4 = Rotate left (270 degrees clockwise), 5 = Vertical mirror (reflected around a vertical line), 6 = Vertical mirror + Rotate right, 7 = Vertical mirror + Flip, 8 = Vertical mirror + Rotate left
  • lScale - Set to 1000
  • lHRes - Set to value of nOrigHRes
  • lVRes - Set to value of nOrigVRes
  • lOrigHRes - Horizontal resolution of image mark in DPI
  • lOrigVRes - Vertical resolution of image mark in DPI
  • lReserved - Set to 0

FREEHAND LINE

The Freehand Line mark enables the end user to use freehand drawing for annotation. With this mark, end users create drawings as though they are using a pen and paper.

Edit Mode: In Edit mode, end users create this mark by clicking the Freehand Line button with the left mouse button, dragging the image, and then releasing the left mouse button. Pressing the right mouse button after the mark is created activates the popup edit menu.

Description
A series of lines where the starting point of line n+1 is the same as the ending point of line n.
Attributes
rgbColor1, bHighlighting, dwLineSize
OiGroup
String
OiIndex
String
OiAnoDat
ART_POINTS. This structure includes the following members:
  • lMaxPoints - The maximum number of points; must be equal to the value of nPoints.
  • lPoints - The current number of points
  • ptPoint - Points marking the beginning and ending of the line segment(s); in image (not scaled) coordinates relative to the upper left corner of rcBounds in ART_MARK_ATTRIBUTES.

Highlighter

The Highlighter mark enables end users to highlight areas of their annotated image or document.

Edit Mode: In Edit mode, end user:

  1. Create this mark by clicking the Highlighter button with the left mouse button and then dragging the resulting rectangle over the items they wish to cover.
  2. The resulting rectangle highlights whatever is underneath it.
  3. Pressing the right mouse button after the mark is created user activates the popup Edit menu.

    4. Description
    A colored rectangle that highlights part of the image.
    Attributes
    rgbColor1
    OiGroup
    String
    OiIndex
    String

HOLLOW ELLIPSE

The Hollow Ellipse mark enables the end user to create a hollow ellipse to surround important areas.

Edit Mode: In Edit mode, end users create this mark by clicking the Hollow Ellipse button with the left mouse button, dragging the mark to the appropriate size, and then releasing the left mouse button. Pressing the right mouse button after the mark is created activates the popup edit menu.

Description
A hollow ellipse whose boundaries are defined by a rectangle. Two points define the rectangle, an upper left point and a bottom right point.
Attributes
rgbColor1, bHighlighting, dwLineSize
OiGroup
String
OiIndex
String

HOLLOW POLYGON

The Hollow Polygon mark enables the end user to surround areas of an image or document with a polygon.

Edit Mode: In Edit mode, to create a hollow polygon, end users:

  1. Click the left mouse button at the point where the polygon starts.
  2. Drag and click the left mouse button to create each vertice.
  3. Double-click the left mouse button to complete the polygon.
  4. Press the right mouse button after the mark is created to activate the popup edit menu.

    5. Description
    A series of lines where the starting point of line 1 is the same as the ending point of line n.
    Attributes
    rgbColor1, bHighlighting, dwLineSize
    OiGroup
    String
    OiIndex
    String
    OiAnoDat
    ART_POINTS. This structure includes the following members:
    • lMaxPoints - The maximum number of points; must be equal to the value of nPoints.
    • lPoints - The current number of points
    • ptPoint - Points marking the beginning and ending of the line segment(s); in image (not scaled) coordinates relative to the upper left corner of rcBounds in ART_MARK_ATTRIBUTES.

HOLLOW RECTANGLE

The Hollow Rectangle mark enables users to surround areas of an image or document with a rectangle.

Edit Mode: In Edit mode, end users create this mark by clicking the Hollow Rectangle button with the left mouse button and then dragging the resulting rectangle over the items to be surrounded. Pressing the right mouse button after the mark is created activates the popup edit menu.

Description
A rectangle with a center that is not filled.
Attributes
rgbColor1, bHighlighting, dwLineSize
OiGroup
String
OiIndex
String

HOT SPOT

The Hot Spot mark enables the end user to define an invisible hyperlink region in a document or image that can be used to hold hidden messages.

Edit Mode: In Edit mode, end users create this mark by clicking the Hot Spot button with the left mouse button, dragging the image to the appropriate size, and then releasing the left mouse button. When the left mouse button is released, the resulting rectangle becomes the hot spot region. It remains visible while the application is in edit mode. Pressing the right mouse button over the mark created activates the popup edit menu.

Run Mode: When a user passes the cursor over this region, the cursor changes, indicating that there is something special about the contents within the invisible region. If the user clicks the left mouse button while the cursor is in the region, your application sends a message detailing the information about the contents of the region.

NOTE: The Hot Spot region is visible only when the application is in Edit mode.

Description
An invisible rectangle over part of an image. When the cursor passes over the area, it changes, indicating that the area has a special meaning.
Attributes
rgbColor1
OiGroup
String
OiIndex
String

Image Embedded

The Image Embedded mark enables the end user to embed a bitmap image in a document or image.

Edit Mode: In Edit mode, end users embed an image by clicking the Image Embedded button with the left mouse button, dragging the image, and then releasing the left mouse button. When the left mouse button is released, the image becomes embedded. Once the bitmap is in place on the annotation window, it can be resized using the left mouse button. Pressing the right mouse button after the mark is created activates the popup edit menu.

Image Embedded marks are intended for use with bitmaps that use no more than the standard 20 Windows colors. Therefore, 1-bit and 4-bit bitmaps are allowed. If you try to display an 8-bit bitmap in the mark, it is displayed using only the standard 20 colors.

Description
An embedded image.
Attributes
bTransparent
OiGroup
String
OiIndex
String
OiDib
AT_BITMAPINFO
OiAnoDat
ART_NEW_ROTATE. This structure includes the following members:
  • lRotation - 1 = Original, 2 = Rotate right (90 degrees clockwise), 3 = Flip (180 degrees clockwise), 4 = Rotate left (270 degrees clockwise), 5 = Vertical mirror (reflected around a vertical line), 6 = Vertical mirror + Rotate right, 7 = Vertical mirror + Flip, 8 = Vertical mirror + Rotate left
  • lScale - Set to 1000
  • lHRes - Set to value of nOrigHRes
  • lVRes - Set to value of nOrigVRes
  • lOrigHRes - Horizontal resolution of image mark in DPI
  • lOrigVRes - Vertical resolution of image mark in DPI
  • lReserved - Set to 0

Image Reference

The Image Reference mark enables the end user to include an image by reference in a document or image.

Edit Mode: In Edit mode, end users reference an image by clicking the Image Reference button with the left mouse button, dragging the image, and then releasing the left mouse button. When the left mouse button is released, an image is displayed. To insert an image, press the right mouse button over the mark to activate the popup Edit menu and choose Properties. Choose the image you wish to reference.

Description
An image included by reference. If the image is not found at display time, an error is returned.
Attributes
bTransparent
OiGroup
String
OiIndex
String
OiFilNam
ART_NAME_STRUCT
OiAnoDat
ART_NEW_ROTATE. This structure includes the following members:
  • lRotation - 1 = Original, 2 = Rotate right (90 degrees clockwise), 3 = Flip (180 degrees clockwise), 4 = Rotate left (270 degrees clockwise), 5 = Vertical mirror (reflected around a vertical line), 6 = Vertical mirror + Rotate right, 7 = Vertical mirror + Flip, 8 = Vertical mirror + Rotate left
  • lScale - Set to 1000
  • lHRes - Set to value of nOrigHRes
  • lVRes - Set to value of nOrigVRes
  • lOrigHRes - Horizontal resolution of image mark in DPI
  • lOrigVRes - Vertical resolution of image mark in DPI
  • lReserved - Set to 0

Pin Up Text

The Pin Up Text mark enables the user to create a mark that appears to be tacked onto the image with a push pin.

Edit Mode: This mark can have an optional label. The label indicates which data can be obtained by clicking on the pin in Run mode. You can add code to the LPFNIG_ART_MOUSENOTIFY_FUNC callback function to display additional data when the push pin is pressed.

Description
A push pin that has an optional description label indicating what data can be retrieved when the mark is activated.
Attributes
rgbColor1, rgbColor2, lfFont
OiGroup
String
OiIndex
String
OiAnoDat
ART_TEXTPRIVDATA. This structure includes the following members:
  • lOrientation - Angle of text baseline to image in tenths of a degree; valid values are 0, 900, 1800, 2700.
  • lAlign - See ART_TEXT_xxx bitflags
  • lReserved - Not in use
  • lAnoTextLength - 64K byte limit (32K for multi-byte data) for Attach-a-Note, typed text, text from file; 255 byte limit for text stamp
  • szAnoText - Text string for text mark types

POLYLINE

The Polyline mark enables the end user to create several connected straight lines by dragging and clicking the mouse.

Edit Mode: To create a polyline mark in an application, end users:

  1. Click the left mouse button at the point where the polyline starts.
  2. Drag the left mouse button to the location of a vertice.
  3. Drag and click the left mouse button to create each vertice you want to add.
  4. Move the cursor to the location where the polyline ends.
  5. Double-click the left mouse button.
  6. The polyline is complete.

Pressing the right mouse button after the mark is created activates the popup Edit menu.

Description
A series of lines such that the starting point of line n+1 is the same as the ending point of line n.
Attributes
rgbColor1, bHighlighting, dwLineSize
OiGroup
String
OiIndex
String
OiAnoDat
ART_POINTS. This structure includes the following members:
  • lMaxPoints - The maximum number of points; must be equal to the value of nPoints.
  • lPoints - The current number of points
  • ptPoint - Points marking the beginning and ending of the line segment(s); in image (not scaled) coordinates relative to the upper left corner of rcBounds in ART_MARK_ATTRIBUTES.

Protractor

The Protractor mark enables the end user to create an angle that displays the arc and the angle measurement.

Edit Mode: To create a measured angle, end uses:

  1. Click the protractor button.
  2. Drag the mouse to create the first line of the angle.
  3. Click the left mouse button to end the first line. This click creates the vertex and begins the second line.
  4. Click the left mouse button where you want your second line to end. The measured angle is complete.
  5. Press the right mouse button after the mark is created to activate the popup Edit menu.

    6. Description
    Two lines that define an arc. The angle of the arc is displayed at the vertex of the lines.
    Attributes
    rgbColor1, dwLineSize, bHighlighting
    OiGroup
    String
    OiIndex
    String
    OiAnoDat
    ART_PROTRACTOR. This structure includes the following members:
    • lAspectNumeratorX - Aspect ratio numerator X
    • lAspectDenominatorX - Aspect ratio denominator X
    • lAspectNumeratorY - Aspect ratio numerator Y
    • lAspectDenominatorY - Aspect ratio denominator Y
    • lArcRadius - Radius of the arc
    • lPrecision - Number of places after decimal point
    • lOrientation - Angle of text baseline to image in tenths of a degree; valid values are 0, 900, 1800, 2700.
    • lReserved - Set to 0
    • ptPoint - Points of the arc

REDACTION

The Redaction mark enables end users to hide or black out areas of their annotated image or document.

Edit Mode: In Edit mode, end users create this mark by clicking the Redaction button with the left mouse button and then dragging the resulting rectangle over the items they wish to cover. The resulting rectangle covers whatever is underneath it. Pressing the right mouse button after the mark is created activates the popup Edit menu.

Description
A colored rectangle that permanently blocks out part of the image.
Attributes
rgbColor1
OiGroup
String
OiIndex
String

RTF

The RTF Edit mark enables end users to edit, load, and display RTF text.

Edit mode: In Edit mode, end users create this mark by clicking the RTF edit button with the left mouse button and then dragging the resulting rectangle over the area to be annotated. The RTF Edit window allows users to load RTF files and edit the RTF text using the menu and toolbar buttons.

Description
An object that allows editing and displaying RTF text
Attributes
None
OiGroup
String
OiIndex
String
OiAnText
ART_TEXTPRIVDATA. This structure includes the following members:
  • lOrientation - Angle of text baseline to image in tenths of a degree; valid values are 0, 900, 1800, 2700.
  • lAlign - See ART_TEXT_xxx bitflags
  • lReserved - Not in use
  • lAnoTextLength - 64K byte limit (32K for multi-byte data) for Attach-a-Note, typed text, text from file; 255 byte limit for text stamp
  • szAnoText - Text string for text mark types

Ruler

The Ruler mark enables the end user to create a line that displays its measurement.

Edit Mode: To create a measured line, end users:

  1. Click on the Ruler button.
  2. Click the left mouse button at the beginning of the line and drag it to the end.
  3. Release the left mouse button to complete the line.
  4. Press the right mouse button after the mark is created to activate the popup Edit menu.

    5. Description
    A line used to measure the distance with a predefined list of measurement units. The distance between points is displayed at the second point.
    Attributes
    rgbColor1, dwLineSize, bHighlighting
    OiGroup
    String
    OiIndex
    String
    OiAnoDat
    ART_POINTS. This structure includes the following members:
    • lMaxPoints - The maximum number of points; must be equal to the value of nPoints.
    • lPoints - The current number of points
    • ptPoint - Points marking the beginning and ending of the line segment(s); in image (not scaled) coordinates relative to the upper left corner of rcBounds in ART_MARK_ATTRIBUTES.
    OiAnText
    ART_TEXTPRIVDATA. This structure includes the following members:
    • lOrientation - Angle of text baseline to image in tenths of a degree; valid values are 0, 900, 1800, 2700.
    • lAlign - See ART_TEXT_xxx bitflags
    • lReserved - Not in use
    • lAnoTextLength - 64K byte limit (32K for multi-byte data) for Attach-a-Note, typed text, text from file; 255 byte limit for text stamp
    • szAnoText - Text string for text mark types

STRAIGHT LINE

The Straight Line mark enables the end user to create straight lines on a document or image.

Edit Mode: To create this mark, end users:

  1. Click on the Straight Line button with the left mouse button.
  2. Click the left mouse button at the point where the line shoud begin.
  3. While holding the left mouse button down, drag the line to the point at which the line shoud end.
  4. Release the left mouse button to complete the line.
  5. Press the right mouse button after the mark is created to activate the popup Edit menu.

    6. Description
    A line with a defined starting and ending point.
    Attributes
    rgbColor1, bHighlighting, dwLineSize
    OiGroup
    String
    OiIndex
    String
    OiAnoDat
    ART_POINTS. This structure includes the following members:
    • lMaxPoints - The maximum number of points; must be equal to the value of nPoints.
    • lPoints - The current number of points
    • ptPoint - Points marking the beginning and ending of the line segment(s); in image (not scaled) coordinates relative to the upper left corner of rcBounds in ART_MARK_ATTRIBUTES.

TEXT From FILE

The Text From File mark enables the end user to add descriptive text to an annotated image or document. The text can be created in various fonts, sizes, colors, and even angles of presentation. The text appears to lay over the original image or document.

NOTE: If you wish to rotate the mark, you must use a Windows True Type font (due to a Windows limitation).

Edit mode: End users create this mark by clicking the Text From File button with the left mouse button and then dragging the resulting rectangle over the area to be annotated. This rectangle helps to position the Text annotations. Text annotations are modified when the application is in the Edit mode. To modify the text, the end user double-clicks the left mouse button when the cursor is over the text mark. The cursor appears at the beginning of the text, and transforms to allow editing.

While creating this mark and entering text, end users use the right mouse button to access a popup menu that enables them to change several attributes of the mark:

  • The Choose Font option is identical to the one available for creating the Attach-a-Note mark.
  • The Adjust Angle option enables end users to rotate the text mark with a dialog box. The square at the lower left corner of the Adjust Angle dialog box shows the appearance of the text mark with the selected text display angle.
  • The Set Background Color option is identical to the one available while creating the Attach-a-Note mark.
  • The Set Background Mode option enables your end users to change the visibility level of the region within the Text mark. When this option is selected, a dialog box appears.

If Transparent is selected, the interior of the text mark is not visible; only the text is visible.

If Opaque is selected, users cannot see through the interior of the text mark.

If Tinted is selected, the text mark resembles a tinted glass. End users are ble to see through the mark.

NOTE: If your end users create a text mark without any text, and with a Transparent background, the resulting mark will exist but will not be visible.

Description
Text supplied from a file.
Attributes
rgbColor1, lfFont
OiGroup
String
OiIndex
String
OiAnText
ART_TEXTPRIVDATA. This structure includes the following members:
  • lOrientation - Angle of text baseline to image in tenths of a degree; valid values are 0, 900, 1800, 2700.
  • lAlign - See ART_TEXT_xxx bitflags
  • lReserved - Not in use
  • lAnoTextLength - 64K byte limit (32K for multi-byte data) for Attach-a-Note, typed text, text from file; 255 byte limit for text stamp
  • szAnoText - Text string for text mark types
OiFilNam
char[]

Text Stamp

The Text Stamp mark allows the end user to annotate documents and images with text.

Edit Mode: In Edit mode, end users create this mark by clicking on the Text Stamp button with the left mouse button. Pressing the right mouse button after the mark is created activates the popup Edit menu, which allows you to enter the text of the stamp.

Description
Text that contains a pre-defined string. The string may include, for example, the date and/or time that the mark was applied.
Attributes
rgbColor1, lfFont
OiGroup
String
OiIndex
String
OiAnText
ART_TEXTPRIVDATA. This structure includes the following members:
  • lOrientation - Angle of text baseline to image in tenths of a degree; valid values are 0, 900, 1800, 2700.
  • lAlign - See ART_TEXT_xxx bitflags
  • lReserved - Not in use
  • lAnoTextLength - 64K byte limit (32K for multi-byte data) for Attach-a-Note, typed text, text from file; 255 byte limit for text stamp
  • szAnoText - Text string for text mark types

There are several codes that can be embedded into the string stored into the szAnotText field of the ART_TEXTPRIVDATA structure of the ART_BLOCK_ANTEXT named block. For 32-bit products:

%a:
Abbreviated weekday name
%:
A Full weekday name
%b:
Abbreviated month name
%B:
Full month name
%c:
Date and time representation appropriate for locale
%d:
Day of the month in decimal number (01 - 31) format
%H:
Hour in 24-hour format (00 - 23)
%I:
Hour in 12-hour format (01 - 12)
%j:
Day of the year as decimal number (001 - 366) format
%m:
Month in decimal number (01 - 12) format
%M:
Minute in decimal number (00 - 59) format
%p:
Current locale's A.M./P.M. indicator for 12-hour clock
%S:
Second in decimal number (00 - 59) format
%U:
Week of the year in decimal number format, with Sunday as first day of week (00 - 51)
%w:
Weekday in decimal number (0 - 6; Sunday is 0) format
%W
Week of the year in decimal number format, with Monday as first day of week (00 - 51)
%x
Date representation for the current locale
%X
Time representation for the current locale
%y
Year without the century, in decimal number (00 - 99) format
%Y
Year with the century, in decimal number format
%z,%Z
Time-zone name or abbreviation; no characters if the time zone is unknown
%%
Percent sign

Typed Text

The Typed Text mark enables the end user to add descriptive text to their annotated image or document. The text can be created in various fonts, sizes, colors. The text appears over the original image or document.

NOTE: If you wish to rotate the mark, you must use a Windows True Type font (this is a Windows limitation).

Edit mode: End users create this mark by clicking the Typed Text button with the left mouse button and then dragging the resulting rectangle over the area to be annotated. This rectangle helps to position of the Text annotations. Text annotations are easily modified when the application is in the Edit mode. To modify it, the end user double-clicks the left mouse button when the cursor is over the text mark. The cursor appears at the beginning of the text allows editing.

NOTE: If end users create a text mark without any text, with a Transparent background, the resulting mark will exist but will not be visible.

Description
A series of characters entered from the keyboard.
Attributes
rgbColor1, lfFont
OiGroup
String
OiIndex
String
OiAnText
ART_TEXTPRIVDATA. This structure includes the following members:
  • lOrientation - Angle of text baseline to image in tenths of a degree; valid values are 0, 900, 1800, 2700.
  • lAlign - See ART_TEXT_xxx bitflags
  • lReserved - Not in use
  • lAnoTextLength - 64K byte limit (32K for multi-byte data) for Attach-a-Note, typed text, text from file; 255 byte limit for text stamp
  • szAnoText - Text string for text mark types


Using ImageGear CAD/Vector Components

ImageGear CAD/Vector Format Components provide support for the following vector format filters:

    • CAD/Vector (CGM) Component Format Filter
    • CAD/Vector (DGN) Component Format Filter
    • CAD/Vector (DWF) Component Format Filter
    • CAD/Vector (DWG, DXF) Component Format Filter
    • CAD/Vector (HPGL, HPGL/2) Component Format Filter
    • CAD/Vector (SVG) Component Format Filter
    • Vector (U3D) Component Format Filter


CAD/Vector (CGM) Component Format Filter

If you attach CAD/Vector (CGM) Component to core ImageGear it allows you to initialize CGM Format Filter functionality, that can be accessed through core ImageGear Format Filter API.

ImageGear CGM Format Filter supports the following features of CGM files processing:

    • IG_FLTR_DETECTSUPPORT - autodetection.
    • IG_FLTR_PAGEREADSUPPORT - single page file reading.
    • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading.
    • IG_FLTR_PAGEINSERTSUPPORT - saving page in the file.

You can detect, read, and work with pages in multi-page CGM files using methods from ImageGear Format Filters API.

Currently ImageGear CAD/Vector (CGM) Component provides 1 control parameter:

    • WIDTH
See Also:

CAD/Vector Filter Control Parameters


CAD/Vector (DGN) Component Format Filter

If you attach CAD/Vector (DGN) Component to core ImageGear it allows you to initialize DGN Format Filter functionality, that can be accessed through core ImageGear Format Filter API.

ImageGear DGN Format Filter supports the following features of DGN files processing:

    • IG_FLTR_DETECTSUPPORT - autodetection.
    • IG_FLTR_PAGEREADSUPPORT - single page file reading.

You can detect and read single-page DGN files.

Currently ImageGear CAD/Vector (DGN) Component provides 2 control parameters:

    • BACKCOLOR
    • WIDTH
See Also:

CAD/Vector Filter Control Parameters


CAD/Vector (DWF) Component Format Filter

The ImageGear CAD/Vector (DWF) component adds support of DWF format to ImageGear. This allows your application to DWF images like any other vector format supported by ImageGear.

If you attach this Component to core ImageGear it allows you to initialize CAD/DWF Format Filter functionality, that can be accessed through core ImageGear Format Filter API.

ImageGear DWF Format Filter supports the following features of CAD files processing:

    • IG_FLTR_DETECTSUPPORT - autodetection.
    • IG_FLTR_PAGEREADSUPPORT - single page file reading.
    • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading.
    • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing.

You can detect, read/write and work with pages in multi-page DWF files.

Currently ImageGear CAD/Vector (DWF) Component provides 2 control parameters:

    • IMAGE_FORMAT
    • WIDTH
See Also:

CAD/Vector Filter Control Parameters


CAD/Vector (DWG, DXF) Component Format Filter

The ImageGear CAD/Vector (DWG, DXF) component provides the ability to import AutoCAD formats into ImageGear. This allows your application to use them like any other format supported by ImageGear. The following formats are supported:

Format
Description
DXF
An AudoDesk graphics format (Drawing eXchange Format). Most CAD programs (PC-based) support this format.
DWG
An AutoCAD, AutoCAD2004, and AutoDesk graphics format (DraWinG).

If you attach this Component to core ImageGear it allows you to initialize CAD Format Filter functionality, that can be accessed through core ImageGear Format Filter API.

ImageGear DXF, DWG Format Filter supports the following features of CAD files processing:

    • IG_FLTR_DETECTSUPPORT - autodetection.
    • IG_FLTR_PAGEREADSUPPORT - single page file reading.
    • IG_FLTR_PAGEINSERTSUPPORT - single page file writing.

You can detect, read/write and work with single-page DXF/DWG files.

Currently ImageGear CAD/Vector (DWG, DXF) Component provides the following control parameters:

    • BACKCOLOR
    • FONTPATH
    • LINEWIDTHDEF
    • PASSWORD
    • SHOWHIDDEN
    • TRUETYPE
    • TTFWIDTH
    • VERSION
    • WIDTH
See Also:

CAD/Vector Filter Control Parameters


CAD/Vector (HPGL, HPGL/2) Component Format Filter

If you attach CAD/Vector (HPGL, HPGL/2) Component to core ImageGear it allows you to initialize HPGL Format Filter functionality, that can be accessed through core ImageGear Format Filter API.

ImageGear HPGL, HPGL/2 Format Filter supports the following features of HPGL, HPGL/2 files processing:

    • IG_FLTR_DETECTSUPPORT - autodetection.
    • IG_FLTR_PAGEREADSUPPORT - single page file reading.
    • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading.

You can detect and read pages in multi-page HPGL, HPGL/2 files.

Currently ImageGear CAD/Vector (HPGL, HPGL/2) Component provides 2 control parameters:

    • BACKCOLOR
    • WIDTH
See Also:

CAD/Vector Filter Control Parameters


CAD/Vector (SVG) Component Format Filter

The ImageGear CAD/Vector (SVG) component provides the ability to import Scalable Vector Graphics format into ImageGear. This allows your application to use them like any other format supported by ImageGear. The following formats are supported:

Format
Description
SVG
Scalable Vector Graphics format. This is a modularized language for describing two-dimensional vector and mixed vector/raster graphics in XML.

If you attach this Component to core ImageGear it allows you to initialize SVG Format Filter functionality, that can be accessed through core ImageGear Format Filter API.

ImageGear SVG Format Filter supports the following features of SVG files processing:

    • IG_FLTR_DETECTSUPPORT - autodetection.
    • IG_FLTR_PAGEREADSUPPORT - single page file reading.
    • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing.

You can detect, read, write and work with single-page SVG files.

Currently ImageGear CAD/Vector (SVG) Component provides 1 control parameter:

    • EXTERN_FILE_PATH
    • WIDTH
See Also:

CAD/Vector Filter Control Parameters


Vector (U3D) Component Format Filter

The ImageGear U3D component provides the ability to import Universal 3D formats into ImageGear. This allows your application to use them like any other format supported by ImageGear. The following formats are supported:

Format
Description
U3D
Universal 3D format is a universal vector standard for storing three-dimensional data of all kinds, to facilitate data exchange.

If you attach this Component to core ImageGear it allows you to initialize U3D Format Filter functionality, that can be accessed through core ImageGear Format Filter API.

ImageGear U3D Format Filter supports the following features of U3D files processing:

  • IG_FLTR_DETECTSUPPORT - auto-detection.
  • IG_FLTR_PAGEREADSUPPORT - single page file reading.
  • IG_FLTR_PAGEINSERTSUPPORT - saving vector data in the file.

Currently ImageGear U3D Component provides 2 control parameters:

  • BACKCOLOR
  • WIDTH


CAD/Vector Filter Control Parameters

All ImageGear CAD/Vector Components import DWF, DWG, DXF, HPGL, HPGL/2, DGN, CGM and SVG files into internal storage format, preserving all the vector information. This process depends on the control parameters, which the programmer controls. An empty reference bitmap is also attached to HIGEAR, providing compatibility with ImageGear raster image support API. The application can set the width in pixels of the reference bitmap. Height is calculated using file's scale factors. ImageGear keeps one dimension and alters the other one to preserve the aspect ratio of the drawing.

ImageGear provides filter control parameters that are applicable for DWG, DXF, HPGL, HPGL/2, DGN, CGM and SVG vector formats. For the information about which parameter is applicable for which filter please see the sections:

  • CAD/Vector (CGM) Component Format Filter
  • CAD/Vector (DGN) Component Format Filter
  • CAD/Vector (DWF) Component Format Filter
  • CAD/Vector (DWG, DXF) Component Format Filter
  • CAD/Vector (HPGL, HPGL/2) Component Format Filter
  • CAD/Vector (SVG) Component Format Filter
  • Vector (U3D) Component Format Filter

You can get/set and retrieve information about these control parameters via ImageGear format filters API calls using methods and properties.

NOTE: DWF, DWG, DXF, HPGL, HPGL/2, DGN and SVG parameters are stored in the same way as all other ImageGear filters.

All ImageGear CAD/Vector filter control parameters are described below:

    • BACKCOLOR
    • EXTERN_FILE_PATH
    • FONTPATH
    • IMAGE_FORMAT
    • PASSWORD
    • VERSION
    • WIDTH


BACKCOLOR

Group: Control Parameter

Description:

This parameter is used to set background color. If nBackGroundColor=0, then a black background color is set, otherwise a white background color is set.

Type:

UINT


EXTERN_FILE_PATH

Group: Control Parameter

Description:

Defines a path where the external files (like raster images) should be looked for.

Type:

String

Default Value:

" " (This means that the external files should be looked for in the directory of the current SVG file.)


FONTPATH

Group: Control Parameter

Description:

Defines a path to the vector font files. Format - <Path1>;< Path2>;... . The total length is currently 262.

Type:

LP | CHAR

Default Value:

" "


IMAGE_FORMAT

Group: Control Parameter

Description:

Defines the internal format that will be used for saving raster data inside the DWF file. This only affects saving of raster images to DWF.

Allowed values correspond to enumIGSaveFormats constants:

IG_FORMAT_BMP

IG_FORMAT_CAL

IG_FORMAT_GIF

IG_FORMAT_G4

IG_FORMAT_JPG

IG_FORMAT_PCX

IG_FORMAT_PCT

IG_FORMAT_PNG

IG_FORMAT_TGA

IG_FORMAT_TIF

Type:

INT

Default Value:

IG_FORMAT_PNG


LINEWIDTHDEF

Group: Control Parameter

Description:

This parameter is used to set default line width.

Type:

Double

Default Value:

0


PASSWORD

Group: Control Parameter

Description:

This parameter is used to set password for encrypted files before reading. Currently this parameter is by DWG/DXF filter to read encrypted CAD .

Type:

LP|CHAR

Default Value:

" "


SHOWHIDDEN

Group: Control Parameter

Description:

If true, hidden layers are shown by default.

Type:

Boolean

Default Value:

False


TRUETYPE

Group: Control Parameter

Description:

If true, TrueType font (Arial) are used for text drawing, otherwise vector fonts are used.

Type:

Boolean

Default Value:

False


TTFWIDTH

Group: Control Parameter

Description:

Relative default TrueType font width.

Type:

Double

Default Value:

0


VERSION

Group: Control Parameter

Description:

This parameter is used to set a version for the file when vector image is saved.

Type:

LP|CHAR

Default Value:

" "


WIDTH

Group: Control Parameter

Description:

Defines the DIB width of the loaded image. The DIB height is calculated using the file's scale factors.

Type:

INT

Default Value:

512


Using ImageGear ISIS Component

ISIS (the Image and Scanner Interface Specification) is an open standard for scanner control and a complete image-processing framework. Now supported by a large number of application and scanner vendors, and rapidly becoming a de facto industry standard, ISIS allows application developers to build very complex image capture systems quickly and reliably using any ISIS certified driver.

  • ISIS is modular: it allows applications to control a scanner directly, or to use built-in routines to handle most situations automatically.
  • ISIS is flexible: using a message-based interface with tags, it can grow in a straightforward and compatible way. This means that features, operations, and formats not yet in existence can be added as desired without waiting for a new version of the specification.
  • Finally, ISIS is a complete specification: it addresses all of the issues that an application using a scanner must address. This includes such tasks as selecting, installing, and configuring a new scanner, setting scanner-specific parameters, scanning, reading, and writing files, and (through PixTools/View) fast image scaling, rotating, displaying, and printing. ISIS drivers have also been written to preprocess data by doing operations such as converting grayscale to binary image data dynamically.

ISIS excels at running scanners at or above their rated speed. It does so by linking drivers together in a pipe so that data flows from scanner driver to compression driver, to packaging driver, to a file, viewer, or printer in a continuous stream, usually without a need to buffer more than a small portion of the entire image. Because ISIS drivers are arranged in a pipe when they are used, each driver is specialized to perform only one function. Drivers are typically small and modular, which means that ISIS allows new functionality to be introduced into an existing application with very little modification.

Since virtually every ISIS driver has been created either by Pixel Translations, or with access to PixTools toolkiks and sample source code, there is a high degree of API consistency between ISIS drivers-even drivers for scanning devices as different as a hand scanner and a digital copier.

ISIS versus TWAIN

As mentioned, ISIS is aimed at application-critical scanning and image manipulation such as is found in the document imaging market; TWAIN is targeted at occasional scanning like the desktop publishing market.

When the TWAIN specification was released, there were issues both with the specification and with field implementations which caused substantial problems of compatibility and performance. To a lesser extent, these problems continue to inhibit TWAIN's acceptance beyond it's historical base.

The philosophy of TWAIN is that the scanner vendor (and hence the TWAIN drivers) should determine the proper graphical user interface to control the scanner. Programmatic control of the scanner has, therefore, rarely been included by the TWAIN driver implementors. The philosophy of ISIS is that programmatic control of the scanner is paramount, and a consistent, optional GUI is available to the developer as well.

Since virtually every ISIS driver has been created either by Pixel Translations, or with access to Pixel's toolkits and sample source code, there is a high degree of API consistency between ISIS drivers -- even drivers for scanning devices as different as a hand scanner and a digital copier. Due to the complexity of the TWAIN specification, the shortage of good example code, the lack of sophisticated testing tools, and the large number of different implementors, TWAIN has had difficulty meeting its goal of true "plug and play" compatibility. Often, applications don't work with TWAIN drivers that are new and weren't tested by the application developer.

The TWAIN specification is not designed for efficiently moving data from the image source (typically a scanner) to its destination (typically a viewer, printer, file, or combination of these). Therefore, it is not optimized for writing drivers that keep up with high-speed scanners. On the other hand, ISIS excels at running scanners at or above their rated speed. It does so by linking drivers together in a pipe so that data flows from scanner driver, to compression driver, to packaging driver, to a file, viewer, or printer in a continuous stream, usually without a need to buffer more than a small portion of the entire image.

Because ISIS drivers are arranged in a pipe when they are used, each driver is specialized to perform only one function. Drivers are typically small and modular. TWAIN drivers, on the other hand, must encompass all of the necessary functionality in a single driver, and are therefore generally much larger. Because of the modularity of ISIS drivers, it is much easier and faster to improve functionality without recompiling, retesting, and re-releasing a large program. Furthermore, ISIS allows new functionality to be introduced into an existing application with very little modification.


Using ISIS Drivers

PixTools/View, PixTools/Scan, and other Pixel Translations' products use the ISIS specification as a framework to access and connect different imaging functions. Some PixTools products, like the Scan toolkit, are based directly on the ISIS specification, while others, like the View toolkit, connect to ISIS through glue code called metadrivers.

The concept behind ISIS is to be able to create many small, reusable code pieces (drivers) which can be connected together to perform complex functions. These drivers use tags and messages to automatically communicate system parameters between themselves.

ISIS drivers are designed to be linked together into an ISIS pipe to perform a specific function. At the beginning or head of the ISIS pipe is a driver that generates data. This is generally either a scanner driver or a file reading driver. Next, various compression, decompression, packaging, and formatting drivers can be linked to the head driver to change the format of the image data as desired. At the end of the ISIS pipe is usually either a file writing driver or a driver that sends data to an image viewer.

One characteristic of an ISIS pipe is that most drivers only need access to a small portion of an image at one time. Therefore, data can "flow" through an ISIS pipe from the head driver to the end without ever requiring buffering of a full page. In most cases, each ISIS driver works with the same 8 Kbyte buffer at all times. This characteristic makes an ISIS pipe a very efficient system for scanning images and moving image data to its destination.

The drivers that are needed to construct an ISIS pipe must be loaded and initialized by the application. Then, the drivers can be linked into a pipe that will produce the desired results. Once the pipe is ready, parameters can be set as desired by sending tags to the head driver. The head driver passes these tags to every other driver in the pipe, and each driver either responds to or ignores each tag, as appropriate. When the pipe is ready, the application invokes it, causing the head driver to perform its function (scan, read, or whatever) and send its data through the pipe.

Scanner Drivers

Most scanner drivers offered by Pixel Translations are 32-bit drivers that work on
Windows 98/Me/NT/2000/XP. These drivers have the filename driver.PXN. Some older drivers exist in 16-bit form and are used within the 16-bit sub-system on Windows 95/98/Me.

Minidrivers

A minidriver is an ISIS driver that is implemented within an application, rather than as a stand-alone module. Although not a requirement, a minidriver generally has limited functionality and can be written by an application developer, whereas a regular ISIS driver must be written by a driver developer who has access to the Driver Developer's Toolkit.

Minidrivers typically are written to solve a particular problem, such as determining the actual size of an image that has been scanned by a scanner that does automatic edge detection, and therefore often returns an image that has a smaller length and width than you are expecting.

Pixel customers have written minidrivers that modify data, do special compression, implement progress monitors, and so forth.


An Overview of Making ISIS Pipes

There are a number of steps you must perform before an ISIS driver will do any work for you. All of these steps must be performed in order, and each must succeed. If you do not do any particular step, or do not check that a step has succeeded, your application will almost certainly fail at some point.

To use an ISIS pipe, you must call at least the following functions:

  • IG_ISIS_drv_load-activates permissions and loads a driver.
  • IG_ISIS_drv_init-initializes a driver and may pass it parameters.
  • IG_ISIS_drv_unload-unloads a driver from memory when the application is done with it.

In addition to these functions, you use IG_ISIS_drv_link to link drivers into ISIS pipes, IG_ISIS_tag_set... to send tags to the pipe to set parameters, and IG_ISIS_run_zone to invoke the pipe and make all drivers perform their intended functions.

IG_ISIS_drv_load

IG_ISIS_drv_load determines the driver to load and whether or not necessary permissions are present. If proper permissions are found, IG_ISIS_drv_load will try to load the driver from the <WINDIR>\PIXTRAN directory.

See Also:

IG_ISIS_drv_load ().

IG_ISIS_drv_init

After a driver is loaded, it must be initialized. If you attempt to do work with a driver that has not been initialized (even a IG_ISIS_drv_link), the application may crash. IG_ISIS_drv_init initializes a driver and optionally can pass parameters to it. For example, it is possible to initialize a file writing driver with the name of the file to write (but there are better ways of doing this by using tags).

See Also:

IG_ISIS_drv_init ().

IG_ISIS_drv_link

Once you have the desired drivers loaded and initialized, you use IG_ISIS_drv_link to link them into a pipe. Each IG_ISIS_drv_link call can link one driver to one other driver. Each subsequent driver to be linked requires a separate call to IG_ISIS_drv_link. You cannot directly link a driver to more than one other driver. (However, you will learn how to split a pipe in a later section.) The first driver in the pipe is also called the head driver.

See Also:

IG_ISIS_drv_link ().

IG_ISIS_tag_set...

To send tags to a pipe, the toolkit provides a set of IG_ISIS_tag_set... functions. The most often used function is IG_ISIS_tag_set_long, which sets tags of type long, short, and byte. IG_ISIS_tag_set_ascii is used to set ASCII tags such as IG_ISIS_TAG_OUTPUTNAME (the name of the output file for a file writing driver).

NOTE: Tags are not saved values-they are sent when the application calls the IG_ISIS_tag_set... function. The driver(s) to which the tags are sent must already be linked. For example, you cannot call IG_ISIS_tag_set_ascii to set the filename on a pipe before the file writing driver is linked in.
See Also:

IG_ISIS_tag_set_ascii (), IG_ISIS_tag_set_default (), IG_ISIS_tag_set_length (), IG_ISIS_tag_set_long (), IG_ISIS_tag_set_rational ().

IG_ISIS_run_zone

IG_ISIS_run_zone invokes a pipe and must be called only after you have loaded, initialized, linked, and set tags on a pipe. It takes as its parameter the head driver of the pipe, and makes that driver perform the function for which it was designed. For example, IG_ISIS_run_zone will make a scanner driver scan a page, or a file reading driver read a page from a file.

See Also:

IG_ISIS_run_zone ()

IG_ISIS_drv_unload

After loading and initializing a driver, you generally do some amount of work with it. When you are finished with the driver, before exiting from your application, you must unlink and unload it from memory. The toolkit does not do this for you. To unlink a driver, you use zero as the parameter to IG_ISIS_drv_link because there is no IG_ISIS_drv_unlink function. To unload a driver, call IG_ISIS_drv_unload and pass in the driver handle. You must unlink a driver completely from a pipe before unloading it.

See Also:

IG_ISIS_drv_link (), IG_ISIS_drv_unload ()


Writing a Simple Scanning Application

There are several different ways to accomplish the task of scanning a page and saving it in a file. This section shows one of those ways, not necessarily the easiest, but a good illustration of all of the required steps. The following steps will scan a page using your scanner's default settings (usually binary, 300dpi, no dither, letter paper size) and put the resulting data into a TIFF file. (Note that if your scanner outputs compressed data, the TIFF file will contain data with the same compression. No attempt is made to compress or decompress the image.)

NOTE: The sample code utilizes the SPEW or Image Spewer driver which is a test scanner driver included in PixTools/Scan. The SPEW driver can be configured to output sample image data and to simulate both basic and advanced scanning functions for application testing.
  1. Load and initialize the scanner driver. The first parameter of the IG_ISIS_drv_load function is reserved and must be zero.
IG_ISIS_drv_load(0, "SPEW", &hScan, 0);
IG_ISIS_drv_init(hScan, 0, 0);

The above IG_ISIS_drv_load function loads the Image Spewer driver. If you prefer, substitute the filename (without extension) of your scanner driver within the quotes. The handle to the driver (hScan) is a HISISDRV.

  1. Load and initialize the file writing driver:
IG_ISIS_drv_load(0, "PIXFPACK", &hFileWriter, 0);
IG_ISIS_drv_init(hFileWriter, 0, 0);

PIXFPACK is Pixel's universal file writing driver-it can write any supported file format.

  1. Link the drivers into an ISIS pipe:
IG_ISIS_drv_link(hScan, hFileWriter);
  1. Set tags on the pipe to specify the filename, file type, and how to write the file:
IG_ISIS_tag_set_ascii(hFileWriter, IG_ISIS_TAG_OUTPUTNAME,
(char FAR *)"TEST.TIF");
IG_ISIS_tag_set_long(hFileWriter, IG_ISIS_TAG_FILETYPE, 0,
IG_ISIS_TAG_FILETYPE_TIFF);

Each IG_ISIS_tag_set... call sets the value of one tag. IG_ISIS_TAG_OUTPUTNAME is set to the ASCII string "TEST.TIF." The remaining tags are type long values with defined constant names. IG_ISIS_TAG_FILETYPE is set to IG_ISIS_TAG_FILETYPE_TIFF.

NOTES: Once the ISIS drivers are linked into a pipe, the tags can be set on any driver, provided that their meanings are not ambiguous. In this example, each of these tags could have been set on hScan rather than on hFileWriter. This characteristic will become more important when you only have a handle to a pipe, rather than individual drivers.

Many application developers mistakenly try to use IG_ISIS_tag_set_long to set the filename. It is important to use the correct tag set function for the various data types. In this case, be sure to use IG_ISIS_tag_set_ascii to set the filename.
  1. Invoke the pipe:
IG_ISIS_run_zone(hScan, Buffer, BUFSIZE);

This call tells the head driver to run a zone, which means to scan a page and send the resulting data down the pipe. The other drivers in the pipe respond automatically, performing whatever function they are designed to perform. In this case, PIXFPACK writes the image data into a TIFF file named TEST.TIF.

  1. Unlink and unload the drivers when you are done with them:
IG_ISIS_drv_link(hScan, 0);
IG_ISIS_drv_unload(hFileWriter);
IG_ISIS_drv_unload(hScan);

To unlink the scanner driver, link it with nothing (zero). Note that the drivers are unlinked and unloaded in reverse order of loading.

Example:

Here is the complete code to scan a page to a file:

#define BUFSIZE 8192
{
    char Buffer[BUFSIZE];
    HISISDRV hScan, hFileWriter;
    /* Load and initialize the scanner driver				*/
    IG_ISIS_drv_load(0, "SPEW", &hScan, 0);
    IG_ISIS_drv_init(hScan, 0, 0);
    /* Load and initialize the file writing driver					*/
    IG_ISIS_drv_load(0, "PIXFPACK", &hFileWriter, 0);
    IG_ISIS_drv_init(hFileWriter, 0, 0);
    /* Link the scanner driver to the file writing driver					*/
    IG_ISIS_drv_link(hScan, hFileWriter);
    /* Set tags to correctly write the file					*/
    IG_ISIS_tag_set_ascii(hFileWriter, IG_ISIS_TAG_OUTPUTNAME,
                   (char FAR *)"TEST.TIF");
    IG_ISIS_tag_set_long(hFileWriter, IG_ISIS_TAG_FILETYPE, 0,
IG_ISIS_FILETYPE_TIFF);
    /* Invoke the pipe and scan the page					*/
    IG_ISIS_run_zone(hScan, Buffer, BUFSIZE);
    /* Unlink and unload the drivers					*/
    IG_ISIS_drv_link(hScan, 0);
    IG_ISIS_drv_unload(hFileWriter);
    IG_ISIS_drv_unload(hScan);
}


Simplifying the Scanning Application

Now that you have seen how to individually load, initialize, and link drivers, there is a simpler way that can often be used to make the toolkit do much of this work for you-IG_ISIS_drv_load_init_pipe(). Here are the steps involved in writing the same scanning application using IG_ISIS_drv_load_init_pipe():

  1. Load, initialize, and link the scanner driver and the file writing driver:
IG_ISIS_drv_load_init_pipe(0, "SPEW|PIXFPACK", &hScan, 0);
  1. Set tags on the pipe to specify the filename, file type, and how to write the file:
IG_ISIS_tag_set_ascii(hScan, IG_ISIS_TAG_OUTPUTNAME, (char FAR
*)"TEST.TIF");
IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_FILETYPE, 0,
IG_ISIS_FILETYPE_TIFF);

This step is the same as before, except the tags are set on the scanner driver because there is no handle to the file writing driver. (ISIS propagates all tags to every driver in the pipe, so this is not a problem). If you need access to a particular driver's handle, that driver must be loaded, initialized, and linked separately.

  1. Invoke the pipe:
IG_ISIS_run_zone(hScan, Buffer, BUFSIZE);

This step is the same as before.

  1. Unlink and unload the drivers when you are done with them:
IG_ISIS_drv_unload_pipe(hScan);

This single function unloads the entire pipe. If you loaded and linked any drivers using separate functions, they also will be unlinked and unloaded by the call to IG_ISIS_drv_unload_pipe().

Example:

Here is the complete simplified code to scan a page to a file:

#define BUFSIZE 8192
{
    char Buffer[BUFSIZE];
    HISISDRV hScan;
    /* Load and initialize the pipe					*/
    IG_ISIS_drv_load_init_pipe(0, "SPEW|PIXFPACK", &hScan, 0);
    /* Set tags to correctly write the file					*/
    IG_ISIS_tag_set_ascii(hScan, IG_ISIS_TAG_OUTPUTNAME, (char
FAR *)"TEST.TIF");
    IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_FILETYPE, 0,
IG_ISIS_FILETYPE_TIFF);
    /* Invoke the pipe and scan the page					*/
    IG_ISIS_run_zone(hScan, Buffer, BUFSIZE);
    /* Unlink and unload the drivers					*/
    IG_ISIS_drv_unload_pipe(hScan);
}


Splitting a Pipe

In addition to linking drivers into a single pipe, you can split a pipe so that the image data is sent to two destinations at the same time. This allows many possibilities; for example, an application that saves a 24-bit color image and a binary thumbnail image at the same time.

The function that splits a pipe is IG_ISIS_drv_split (). It is important to remember that IG_ISIS_drv_split() splits the input of one driver into the input of another driver.

ISIS drivers keep track of two handles: a child handle and a sibling handle. The child handle is the handle that gets linked from the output of the driver to the input of another driver in a linear ISIS pipe. The sibling handle is another handle that links the input of the driver to the input of another driver in a split pipe. Note in the diagram above that the split driver uses the other driver's sibling handle, not its child handle. You cannot split the output of a driver to the input of two drivers. The IG_ISIS_drv_link and IG_ISIS_drv_split functions that connect each driver are also shown in the diagram.

PIXDFLT makes each driver send its data to its siblings before the data is modified; therefore, the data goes to the siblings first. When all sibling splits have been satisfied, PIXDFLT then instructs the driver to send the processed data to its child (next driver). However, since data from scanners always arrives in chunks that are less than a page, the order that the data passes through a pipe with splits is almost never important to an application developer. Each chunk of data from its source (usually about 8K bytes) is processed through the entire pipe before the next chunk is received.


Loading the Currently-Selected Scanner Driver

The toolkit has facilities for letting the user select and configure a scanner from among all installed scanner drivers. Selecting a driver does not load it for the application to use. So, how does the application load the currently-selected scanner driver?

The function IG_ISIS_drv_get_scan_name() provides an easy solution.

IG_ISIS_drv_get_scan_name () retrieves and fills in the currently-selected scanner by reading the [Scanner] section of the SETSCAN.INI file. If no scanner is currently selected, IG_ISIS_drv_get_scan_name will return IG_ISIS_ERR_NOCURSCANNER.

If no name is set and the hWnd parameter is not zero, the toolkit attempts to establish a current scanner by calling IG_ISIS_drv_set_scan_name () and displaying the Select Scanner dialog box.

The following program fragment shows how to load and unload the currently-selected driver.

HISISDRV hDriver;
char lpcDriverName[255];
IG_ISIS_drv_get_scan_name(hWnd or 0, lpcDriverName);
IG_ISIS_drv_load((char FAR *)0, lpcDriverName, &hDriver, 0);
IG_ISIS_drv_init(hDriver, lpcDriverName, 0);
.
.
.
/* The driver may now be used by referencing &hDriver						*/
.
.
.
IG_ISIS_drv_unload(hDriver);


More ISIS Characteristics

This section contains useful information about using ISIS pipes.

Buffering of Image Data

Because of the way ISIS is designed, data is not copied from buffer to buffer as it moves from one driver to the next. Most ISIS drivers share a common buffer and each driver gets a FAR pointer to it. ISIS drivers that do compression and decompression are carefully designed not to modify this common buffer.

Loading and Unloading Drivers

Loading drivers takes time-it is expensive in terms of application performance. For this reason, ISIS is designed to allow you to keep drivers loaded yet use them in different pipes. You can load all of the drivers you are likely to need when you start your application, and then link and unlink them as they are needed in different pipes. Don't forget to initialize each driver before linking it. And, if the driver requires initialization parameters, it must be initialized whenever you want to change these parameters. You do not have to reinitialize the driver if it was unlinked from one pipe and linked to another pipe using the same parameters. Unload the drivers only when exiting from the application.

You can use IG_ISIS_drv_load_init_pipe () to load and initialize individual drivers, and then use IG_ISIS_drv_link () to link them later.

Yielding

When writing applications for windowing environments, it is usually important to let the operating system and other applications have time to perform some work while the application is busy. When scanning pages, your application will often use up a lot of CPU time. It should implement a yield function during these times so that other processes can do some work.

Some ISIS drivers, if they are waiting for data, look for IG_ISIS_TAG_YIELDPROC which defines a yield function. If the application assigns a value to that tag, then the driver itself will call the application's yield function to tell the application it is waiting. For drivers that do not support the yield tag, it is a good idea for the application to implement a yield mechanism itself.

Note that you cannot expect a Windows yield function to occur with any particular regularity.

Special IG_ISIS_drv_load cases

The PIXMISIS and FROMPIXM drivers will not work with the default parameters passed to them during the initialization routine used by IG_ISIS_drv_load_init_pipe(), and so they cannot be loaded, initialized, and linked by using this function. You must use separate
IG_ISIS_drv_load(), IG_ISIS_drv_init(), and IG_ISIS_drv_link() calls.

IG_ISIS_drv_unload_pipe

IG_ISIS_drv_unload_pipe() can unload any pipe (whether or not it was created with IG_ISIS_drv_load_init_pipe()), provided the pipe does not contain any splits. Often, however, you may want to unlink and unload drivers separately, because typically the scanner driver should remain loaded during the entire time the application is active.

Unloading Drivers without Unlinking

It is not safe to unload drivers without first unlinking them, and it is bad programming practice to do so. If a linked driver remains in memory and is used after its child or sibling is gone, the pipe is in an unstable state. The driver will forward its data to an undetermined location, causing unpredictable results. Don't unload your drivers without first unlinking them!

Tag Characteristics

When a driver is initialized, its tags are set to default values that are determined by the driver. Tag values can be changed by the application at any time, and the application can save tag values so that they can later be restored. In this way, an application can save and restore current settings, a set of named settings, and/or its own start-up settings. Note however that a driver's default settings cannot be changed by an application with one exception: user-settable defaults.

User-Settable Defaults

The one exception to default settings being made by the application is a mechanism for setting driver defaults that are critical or at least important to the operation of a driver. For example, many scanner drivers let the user configure and save the default paper size, default SCSI address, or default interface I/O address. The actual values vary depending on the selected scanner, and many scanners have no user-settable defaults. Any tags other than those presented by the driver when it is selected are hard-coded to factory default settings.

The toolkit has functions for setting tags back to their default values, for finding a tag's default values, and for finding the current value of a tag.

More information on tags can be found in Working with Tags section.

Checking a Scanner for Feeder Capabilities

Pixel Translations supports a large number of image scanners, each with different capabilities. One of the more important capabilities that users want to work with is sheet feeding mechanisms. The toolkit has a tag for checking whether the scanner has a flatbed, feeder, or both, and whether the scanner can report whether there is a page loaded on the flatbed or in the feeder. Once the application has determined the capabilities of the scanning mechanism, the toolkit has a function just for checking the status of the feeder: IG_ISIS_drv_is_loaded.

Checking the Feeder and Incrementing Filenames

The following example uses IG_ISIS_drv_is_loaded to continue scanning as long as there are pages in the feeder. For each page scanned, a TIFF file is created called FILEnn.TIF, where nn is a number that increments with each page scanned.

#define BUFSIZE 8192
AT_ERRCOUNT ScanBatch(HISISDRV hDriver)
{
    AT_ERRCOUNT nErrCount;
    LONG lValue, dwBits;
    char Buffer[BUFSIZE];
    HISISDRV hFile;
    int iPage;
    char lpcFileName[80];
/* Load and initialize the file writing driver		*/
    nErrCount = IG_ISIS_drv_load_init_pipe(0, "PIXFPACK",
&hFile, 0);
    if (nErrCount != IGE_SUCCESS)
        return nErrCount;
/* Link already-loaded scanner driver with file writing driver.
*/
    IG_ISIS_drv_link(hDriver, hFile);
/* Set the file type and open attributes		*/
    IG_ISIS_tag_set_long(hFile, IG_ISIS_TAG_FILETYPE, 0,
IG_ISIS_FILETYPE_TIFF);
    IG_ISIS_tag_set_long(hFile, IG_ISIS_TAG_OPENATTRIBUTE, 0,
                   IG_ISIS_OPENATTRIBUTE_CREATE |
IG_ISIS_FILE_BOTH);
/* Check whether there is a page loaded */
    IG_ISIS_tag_get_long(hDriver, IG_ISIS_TAG_FEEDER, 0,
&dwBits);
    if (dwBits & IG_ISIS_FEEDER_TELLFEED) {
        IG_ISIS_drv_is_page_loaded(hDriver,
IG_ISIS_TAG_FEEDER_FEED, &dwBits);
        if (dwBits & IG_ISIS_DRV_STACKPAGE)
            printf("There is a page ready in the feeder.");
        else
            printf("The feeder is empty.");
    } else
        printf("Can't tell if page is loaded.");
    nErrCount = IG_ISIS_drv_is_page_loaded(hDriver,
IG_ISIS_FEEDER_FEED, &lValue);
/* Clean up if an error occurs	*/
    if (nErrCount != IGE_SUCCESS)
        IG_ISIS_drv_link(hDriver, 0);
        IG_ISIS_drv_unload(hFile) ;
        return nErrCount;
    }
/*  While there is a page in the feeder, get ready to scan by
 *  incrementing a numeric portion of the filename for each page
 *  scanned. */
    while (lValue == IG_ISIS_DRV_STACKPAGE) {
        wsprintf(lpcFileName, "FILE%04d", iPage++);
        IG_ISIS_tag_set_ascii(hDriver, IG_ISIS_TAG_OUTPUTNAME,
lpcFileName);
/* Run the zone			 */
        nErrCount = IG_ISIS_run_zone(hDriver, Buffer, BUFSIZE);
/* Clean up if an error occurs						 */
        if (nErrCount != IGE_SUCCESS) {
            IG_ISIS_drv_link(hDriver, 0);
            IG_ISIS_drv_unload(hFile);
            return nErrCount;
        }
/* Check for page in feeder again, and stay in the loop if
present						*/
        nErrCount = IG_ISIS_drv_is_page_loaded(hDriver,
IG_ISIS_TAG_FEEDER_FEED, &lValue);
/* Clean up if an error occurs						 */
        if (nErrCount != IGE_SUCCESS) {
            IG_ISIS_drv_link(hDriver, 0);
            IG_ISIS_drv_unload(hFile);
            return nErrCount;
        }
    }
/* Clean up if successful	 					*/
    IG_ISIS_drv_link(hDriver, 0);
    IG_ISIS_drv_unload(hFile);
    return IGE_SUCCESS;
}

In the above example, the scanner driver was already loaded by some previous code in the application. This code fragment does not attempt to unload the scanner driver because it didn't load it. When using IG_ISIS_drv_is_loaded (), remember that the information about whether or not a page is loaded is in the function's third parameter (&lValue), not in the return value. A negative return value from IG_ISIS_drv_is_loaded() means there was an error completing the function.

Error Handling

There are several functions in the toolkit that are critical to proper and well-behaved scanning and image handling. In writing your application, you should not assume that any of these critical functions complete without error. You should check for errors at each step.

Here is an example of how an error could cause a system crash if undetected:

  1. Your application needs to load a scanner driver, initialize it, and link it with a pipe.
  2. You set up a IG_ISIS_drv_load() function to load the scanner driver, and do not check whether or not the driver actually loaded.
  3. A user of your application does not have the proper permissions to use the scanner driver, but selects it anyway.
  4. Your application thinks the driver is loaded and tries to initialize it.
  5. Since the driver is not loaded, some other, perhaps critical system data in memory is "initialized" with tags that were intended to be sent to the driver.

In addition to standard programming practices of checking return values from functions, the toolkit has built-in error reporting features that can produce textual error messages for the user.

Scanning from any Scanner

Many applications need to work with a variety of scanners, and each scanner may have either slightly or vastly different capabilities. For example, the scanner may have only a flatbed, only a document feeder, or both flatbed and feeder. It may be a binary-only scanner, a grayscale scanner, or a color scanner. In addition to these basic features, various scanners have different levels of extra features, such as automatic brightness and contrast control, bar code readers, endorsers, downloadable dither and gamma settings, and so forth.

Invoking a Pipe with Individual Functions

All of the examples in this chapter have used the IG_ISIS_run_zone function, which is suitable for most scanning and file reading applications. It takes care of all the steps necessary to get the image from the head driver and move its data through the pipe you have defined. IG_ISIS_run_zone is implemented by several separate functions that can be called separately by an application when more control over the process is desired. The separate functions for invoking an ISIS pipe are:

  • IG_ISIS_drv_start_stack ()
  • IG_ISIS_drv_start_page ()
  • IG_ISIS_drv_start_zone ()
  • IG_ISIS_drv_forward ()
  • IG_ISIS_drv_start_data ()
  • IG_ISIS_drv_put_data ()
  • IG_ISIS_drv_end_zone ()
  • IG_ISIS_drv_end_page ()
  • IG_ISIS_drv_end_stack ()

Stack

A stack is a way of referring to a group of related pages. These pages may or may not fit into the scanner's document feeder at one time.

Page

A page is a way of referring to an individual page of a stack.

Zone

A zone is a way of referring to an individual area upon a page.


Working with Tags

All parameters that drivers use are set and retrieved by using tags. A tag is a data storage area that has a specific, predefined purpose or definition. Tags are used within ISIS both to describe data and to control the behavior of drivers. Each ISIS tag that a driver implements has a current value, a default value, a set of legal values, and perhaps one or more saved values.

As you work with tags, keep in mind that some tags are critical and required by all drivers; other tags are optional and may or may not be available in some drivers. When a tag is not available in a driver, the driver returns the error IG_ISIS_ERR_BADTAG indicating that the tag is not available, and ignores the settings that were carried by that tag. The string constant defined for IG_ISIS_ERR_BADTAG is "Tag not found." It is up to the application to determine whether or not this error message is actually an error or just a driver responding that it does not contain that tag. In many cases, it is safe, and probably desirable, for the application to continue.

Another important point about setting tags: tag values are set for all drivers in a pipe instantaneously. The parameters carried by tags are not stored for later implementation by a driver. A tag must take effect when it is received by a driver (assuming the driver contains that tag), and the driver (in most cases) then forwards the tag to other drivers in the ISIS pipe. If the driver is not ready to accept the parameter that the tag is carrying, the parameter will not be set. For example, if you set IG_ISIS_TAG_OUTPUTNAME on the head driver of a pipe before the pipe is linked with a file writing driver, the filename to be used when saving the file will not be set when the driver is eventually linked into the pipe.

Functions for Working with ISIS Tags

Following is a list of tag functions and their use. The "..." in many of the function names is replaced by Ascii, Long, or Rational, according to the type of tag to which the function is being directed.

Tag Function
Purpose
IG_ISIS_tag_get...
Get the current value of a tag.
IG_ISIS_tag_get...default
Get the default value of a tag.
IG_ISIS_tag_get_length ()
Get the number of elements in the current value of a numeric tag, or the number of characters in the current value of an ASCII tag including the NULL terminating character.
IG_ISIS_tag_get_length_default ()
Get the number of elements in the default value of a numeric tag, or the number of characters in the default value of an ASCII tag including the NULL terminating character.
IG_ISIS_tag_get_type ()
Get the type of a tag.
IG_ISIS_tag_save_file ()
Save current scanner tag values to a file.
IG_ISIS_tag_restore_file ()
Restore saved scanner tag values from a file.
IG_ISIS_tag_save_value ()
Save current tag value(s) to a memory buffer.
IG_ISIS_tag_restore_value ()
Restore tag value(s) saved in a memory buffer.
IG_ISIS_tag_set...
Set the value of a tag.
IG_ISIS_tag_set...default
Set a tag to its default value.
NOTE: This function only sets a tag to its predefined default value. Default values are determined by the driver. Default values for tags cannot be set by an application developer or user.
IG_ISIS_tag_set_length ()
Set the number of elements in a multi-element tag.

Tag Function
Purpose
PixTagCreate
Create a tag in a driver.
PixTagSetAffect
Establish a tag setting relationship in a driver.
PixTagSetAffectCount
Allocate space for a PixTagSetAffect array.
PixTagGet...
Get the current value of a tag.
PixTagGet...Default
Get the default value of a tag.
PixTagGetLength
Get the number of elements in the current value of a numeric tag, or the number of characters in the current value of an ASCII tag.
PixTagGetLengthDefault
Get the number of elements in the default value of a numeric tag, or the number of characters in the default value of an ASCII tag.
PixTagGetType
Get the type of a tag.
PixTagSaveFile
Save current tag values in a file.
PixTagRestoreFile
Restore saved tag values from a file.
PixTagSaveValue
Save current tag value(s) in a memory buffer.
PixTagRestoreValue
Restore tag value(s) saved in a memory buffer.
PixTagSet...
Set the value of a tag.
PixTagSetDefault
Set a tag to its default value.1
PixTagSetLength
Set the number of elements in a multi-element tag.
1Important: This function only sets a tag to its predefined default value. Default values are determined in the driver by the first value to which a tag is set. Default values for tags cannot be set by an application developer or user.

ISIS Tag Types

Before setting a tag, it is important to know the type of the tag. There are five distinct type of tags and three sets of functions for getting and setting their values, as shown in the following table. Byte, short, and long tag types are all manipulated by using IG_ISIS_tag...long functions.

Tag Type
Typical Tag Functions
IG_ISIS_TAG_TYPE_BYTE
IG_ISIS_TAG_TYPE_SHORT
IG_ISIS_TAG_TYPE_LONG
IG_ISIS_tag_get_long (hDriver, wTag, wIndex, &dwValue);
IG_ISIS_tag_set_long(hDriver, wTag, wIndex, &dwValue);
IG_ISIS_tag_get_long_default(hDriver, wTag, wIndex, &dwValue);
IG_ISIS_TAG_TYPE_RATIONAL
IG_ISIS_tag_get_rational(hDriver, wTag, wIndex, &ratValue);
IG_ISIS_tag_set_rational(hDriver, wTag, wIndex, &ratValue);
IG_ISIS_tag_get_rational_default(hDriver, wTag, wIndex, &ratValue);
IG_ISIS_TAG_TYPE_STRING
IG_ISIS_tag_get_ascii(hDriver, wTag, wLength, lpcBuffer);
IG_ISIS_tag_set_ascii(hDriver, wTag, lpcBuffer);
IG_ISIS_tag_get_ascii_default(hDriver, wTag, wLength, lpcBuffer);

There are very few IG_ISIS_TAG_TYPE_BYTE type tags in drivers. Most application developers can remain completely unaware of whether they are working with a byte, short, or long type tag.

Some tags store their values in arrays. The wIndex parameter of each of the tag functions then specifies which element of the array you want to access. This is important for tags that control dither patterns, gamma tables, and other data that is stored in a table. Rather than have, for example, 64 different tags (one for each value in a dither pattern), drivers will use an array of 64 elements for a single tag. You can iterate on the value of wIndex from 0-63 to get or set all of the elements of the tag.

An ASCII tag is a special case. You cannot have multiple strings within an ASCII tag. The ASCII tag functions, therefore, do not have a wIndex parameter because the toolkit assumes that you always will want to get or set the entire string. (A string is stored as an array of bytes, and an index would simply take you to a particular character in the string.

Tag Initialization

When a driver is initialized, its tags are set to default values as determined by the person who wrote the driver. Once a driver has been initialized, tag values can be changed repeatedly by an application. To return a tag to its default value, use the IG_ISIS_tag_set_default function. The application can also save current tag values in a file, and then load them later (perhaps right after initialization). This gives the application the capability to implement settings that appear to the user to be defaults.

User-Settable Tag Defaults

Despite what was just explained about tags not having default values that can be set by the user, each scanner driver has from zero to four special tags that actually can be set by the user to default values during scanner selection. Most scanners that employ user-settable defaults use only one or two of the four available tags. The tags are named IG_ISIS_TAG_CONFIG_1 through IG_ISIS_TAG_CONFIG_4 and are assigned to particular driver tags by the driver developer. Typical uses for these tags are default SCSI address, default page size, default color dropout, default I/O address, and so forth.

Under Windows, a dialog box appears if the user chooses a scanner by using the built-in Select Scanner dialog and the scanner has user-settable default tags, and the user clicks the Setup button after choosing a scanner. It also appears if the user chooses a scanner for which default values have not yet been set and tries to close the dialog.

The actual settings available in this dialog box will vary according to the implementation of the driver. The driver that displays the above dialog box has default tags for default paper size and default SCSI address. These values will be set each time the scanner driver is initialized. The values for IG_ISIS_TAG_CONFIG_1 through IG_ISIS_TAG_CONFIG_4 are saved in a scanner-specific section of the SETSCAN.INI file. In the dialog box shown above, the values would be saved in a section named [FUJIGINX].

Determining Tag Default Values

The IG_ISIS_tag...default function gets the default value of a tag without resetting it to its default value. To set a tag to its default value, you could use the value returned by IG_ISIS_tag...default to set the tag, but it is easier to simply use IG_ISIS_tag_set_default.

Tag Values and Interdependencies

Some tags are independent of other tags, and some tags are dependent on other tags' values. A dependent tag's value can be reset or changed when the value of a tag upon which it is dependent changes. Tag dependencies are described in the Tag Reference later in this document. By always setting tags in order of their dependence, you can always ensure the desired results.

An an example, for a particular scanner, IG_ISIS_TAG_DITHER may have legal values other than "None" when IG_ISIS_TAG_BITSPERSAMPLE and IG_ISIS_TAG_SAMPLESPERPIXEL are both one (indicating binary scanning mode). But when these tags are set to values that set a grayscale or color scanning mode, IG_ISIS_TAG_DITHER may have a legal value of "None" only.

Because of interdependencies, it is possible, and in fact common, for an application to set a tag to an intermediate illegal value. Note that the toolkit does not query to determine the legal choices for a tag when the tag is set. There are two reasons for this:

  1. Previous versions of the toolkit did not check tags as they were set because it is a very slow process. Changing it now would break many existing applications.
  2. It is possible that while an application is en route to setting a legal group of tag values, it sets tags to values that are temporarily illegal until all other interdependent tags in the group are set.

Because the toolkit does not check each tag as it is set, the order in which many tags are set does not matter to the toolkit. It may, however, matter to the application. If you set TAG2 to a legal value, and then set TAG1 on whose value TAG2 depends, TAG2 may be changed to a different value and produce results different from what you expect or require. Furthermore, if you call IG_ISIS_run_zone on a pipe that has tags set to illegal values, you might get an error such as "Bad parameter."

NOTE: It is possible for a tag's default value to become illegal due to the application changing the values of tags that have a higher precedence. In this case, the toolkit performs some calculations to attempt to reset the default tag value to a legal value.

Tags and Choices

The way in which ISIS drivers decide and communicate the legal values for a particular tag is with choices. Each ISIS driver must establish legal choices for a tag based on other interdependent tag values. The application can then query choices to find out the current legal values for a tag.

Choices are a separate entity from tags. Tags generally only hold one value each at a given time (unless the tag is an array that has several elements such as gamma tables). Choices for a given tag change based on the value of other interdependent tags.

For example, if your application is scanning in binary mode, specific dither options are available. If the user changes the scanner mode to grayscale, in which mode most scanners do not allow dither, the choices for the dither tag change to reflect the new available settings (probably "None"). Therefore, if you set IG_ISIS_TAG_BITSPERSAMPLE and IG_ISIS_TAG_SAMPLESPERPIXEL to 1 (indicating binary), you can query choices for IG_ISIS_TAG_DITHER and obtain a list of legal dither patterns. If you then set IG_ISIS_TAG_BITSPERSAMPLE to 8 (indicating grayscale), the choices for IG_ISIS_TAG_DITHER may contain only one value (None).

NOTE: As you can see from the example above, it is generally not safe to query the choices for a particular tag and assume that they will remain the same for as long as you are working with the scanner. You should query a tag's value right before its use in your application.

Choices and relationships between tags are established by the person who wrote the ISIS driver. The application developer has no control over what choices are available and what their relationships are. Application developers can only get a tag's value, set a tag to one of its legal values, or find out how many choices a tag has and what they are.

Tag Choice Data Types

As previously mentioned, it is important to know the data type of a tag before setting it. The choices for a tag have the same data type as the tag itself. Issuing a IG_ISIS_tag_get_type () function will return the data type of the tag and its choices. There is no separate function for getting the type of a choice.

Querying Choices

Choices can only be queried by an application; there are no PixTools/Scan API functions for setting choices. The functions for querying choices are shown in the following table:

Tag Choice Function
Purpose
IG_ISIS_choice_get_flags ()
Gets the type of choice for the tag: list (IG_ISIS_CONT_LIST) or range (IG_ISIS_CONT_RANGE). A list has multiple values; a range has a low value, a high value, and a step value.
IG_ISIS_choice_get_count ()
Gets the number of legal values for a choice. Although valid for both list and range choices, it usually is not used for ranges, because you do not need to know how many valid values there are in the range.
IG_ISIS_choice_get_long ()
 IG_ISIS_choice_get_rational ()
 IG_ISIS_choice_get_ascii_len ()
 IG_ISIS_choice_get_ascii ()
Gets the values of choices for a particular tag. Generally, the application must iterate through the index of the array of choices that is determined by IG_ISIS_choice_get_count.

Choice Lists Versus Choice Ranges

Choices can be set up in the driver as lists or ranges. A list makes sense when there are multiple, non-sequential choices. IG_ISIS_choice_get_count() is useful for lists, where the application must determine how many choices there are so that they can be listed for the user. A range is more useful for tags such as IG_ISIS_TAG_IMAGEWIDTH which may contain hundreds or even thousands of individual choices (3300 pixels wide with 8 bits between values, for example). Using a range eliminates the need to specify hundreds or thousands of choices in a list within a driver, and makes dealing with the choice much easier for the application. Using IG_ISIS_choice_get_count () with a range generally is not useful.

The special indexes of IG_ISIS_CHOICE_LOW, IG_ISIS_CHOICE_HIGH, and IG_ISIS_CHOICE_STEP may be used to access the range of a choice. IG_ISIS_CHOICE_LOW always returns the lowest value and IG_ISIS_CHOICE_HIGH always returns the highest value of the range (or list). Only if the choice is a range, IG_ISIS_CHOICE_STEP returns the difference between any two consecutive values. If the choice is not a range, IG_ISIS_CHOICE_STEP's value is undefined. Note also that individual indexes always return valid values, even if the choice is a range. Thus, you can always access the nth possible value of a tag, whether the choices are represented as a list or a range.

Tags with No Choices

An ISIS driver is not required to specify choices for every tag. If you query the choices for tags that do not have choices, IG_ISIS_choice_get_flags() will indicate that the choices are a list, and IG_ISIS_choice_get_count() will indicate that there is only one valid value. There is no way for an application developer to know that a tag has no choices, nor should the developer care. If a tag has only one valid choice, it will always be set to that choice.

Checking Choices before Setting Tags

It is important to check the choices for a tag before setting the tag. If you ignore the fact that a tag has choices, and you pick a value and set the tag to it, and then you ask for the legal values for the tag, the driver may return the (possibly illegal) value to which you just set the tag. Then, when you invoke the pipe, you will likely receive a Bad Parameter error. If you set tags without checking their choices, you will eventually set illegal values and either get a Bad Parameter error or a system crash.

Choice Function Examples

The following are typical function calls for the functions used with choices:

IG_ISIS_choice_get_long(hScan, wTag, iIndex, &dwValue);
IG_ISIS_choice_get_count(hScan, wTag, &wCount);

IG_ISIS_CONT_RANGE:

IG_ISIS_choice_get_long(hScan, wTag, IG_ISIS_CHOICE_LOW,
&ValueLow);
IG_ISIS_choice_get_long(hScan, wTag, IG_ISIS_CHOICE_HIGH,
&ValueHigh);
IG_ISIS_choice_get_long(hScan, wTag, IG_ISIS_CHOICE_STEP,
&ValueStep);

IG_ISIS_CONT_LIST:

for (index=0; index<wCount; index++)
    IG_ISIS_choice_get_long(hScan, wTag, index, &lValue);

Examples

This section shows examples of working with tags and choices.

Scanning a Page and Saving Group 4 Data

This example shows how to scan a page and make sure that the file is saved with CCITT Group 4 compression, whether the scanner outputs Group 4 compressed data or uncompressed data. If the scanner is capable of outputting Group 4 compressed data, this example constructs an ISIS pipe that does not do compression, and it turns on Group 4 compression in the scanner driver. If the scanner cannot output Group 4 compressed data, this example constructs a pipe that includes the necessary compression drivers and does not attempt to turn on compression in the scanner driver. This sample assumes that a scanner has already been loaded and its handle is hScan.

LONG lComp;
WORD wCount, iIndex;
BOOL bGroup4 = FALSE;
HISISDRV hWrite;
/* We can assume that IG_ISIS_TAG_COMPRESSION will always be a
list, */
/* so we didn't do a IG_ISIS_choice_get_flags. */
/* If the following call fails, then there is no compression */
/* available from the scanner: */
if (!IG_ISIS_choice_get_count(hScan, IG_ISIS_TAG_COMPRESSION,
&wCount)) {
    for (iIndex = 0; iIndex < wCount; iIndex++) {
/*	Loop thru all choices and put into lComp: */
        IG_ISIS_choice_get_long(hScan, IG_ISIS_TAG_COMPRESSION,
iIndex, &lComp);
/*	If any value of lComp is G4, set bGroup4 to TRUE: */
        if (lComp == IG_ISIS_COMPRESSION_G4)
            bGroup4 = TRUE ;
            break;
    }
}
/* If bGroup4 is True, make a pipe that writes the file without
*/
/* compression. Set the scanner driver to Group 4. */
if (bGroup4) {
    IG_ISIS_drv_load_init_pipe(0, "PIXFPACK", &hWrite, 0);
    IG_ISIS_drv_link(hScan, hWrite);
    IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_COMPRESSION, 0,
IG_ISIS_COMPRESSION_G4);
}
/* Otherwise, make a pipe that includes G4 compression. Don't
try */
/* to turn on compression in the scanner. */
else {
    IG_ISIS_drv_load_init_pipe(0, "RAS2RUN|RUN2G4|PIXFPACK",
&hWrite, 0);
    IG_ISIS_drv_link(hScan, hWrite);
    IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_COMPRESSION, 0,
IG_ISIS_COMPRESSION_NONE);
}
/* Set the output filename and type */
IG_ISIS_tag_set_ascii(hFileWriter, IG_ISIS_TAG_OUTNAME, 0,
(char FAR *)"TST.TIF");
IG_ISIS_tag_set_long(hFileWriter, IG_ISIS_TAG_FILETYPE, 0,
IG_ISIS_TAG_FILETYPE_TIFF);
/* Invoke the pipe */
IG_ISIS_run_zone(hScan, buffer, sizeof buffer);
/* Clean up when done */
IG_ISIS_drv_link(hScan, 0);
IG_ISIS_drv_unload_pipe(hWrite);

Setting a Scanning Area

One way to allow a user to set the scanning area is to call the toolkit's built-in Set Scanning Area dialog box by using the IG_ISIS_drv_area_dialog () function. If you would rather use your own interface to set the scanning area, this example will show you how. (The source code sample SCANTEST.C defines a function for setting scanning area and is a good source of additional information.)

The following example shows how to pick a 3" wide by 5" high rectangle as close to the center of a page as possible.

Note that the first step in this example is to set the X position to zero. This is done in case some other code has already defined a scanning area. To reflect the currently-available legal IMAGEWIDTH settings, the legal values of IMAGEWIDTH change if XPOSITION changes. (This is another tag dependency that must be remembered.) The sample does not test whether IG_ISIS_TAG_IMAGEWIDTH is a list or a range, because in ISIS drivers, it is always a range.

Finally, note that all ISIS measurements are in pixels and dots per inch, regardless of how the scanner wants the measurements specified. ISIS drivers make this conversion, if necessary.

LONG lHigh, lLow, lStep, lLeft, lWidth, lTop, lLength;
AT_ISIS_RAT rat;
/* Reset X position to 0 in case some other region was defined.
*/
IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_XPOSITION, 0, 0L);
/* Query the width values. */
IG_ISIS_choice_get_long(hScan, IG_ISIS_TAG_IMAGEWIDTH,
IG_ISIS_CHOICE_HIGH, &lHigh);
IG_ISIS_choice_get_long(hScan, IG_ISIS_TAG_IMAGEWIDTH,
IG_ISIS_CHOICE_LOW, &lLow);
IG_ISIS_choice_get_long(hScan, IG_ISIS_TAG_IMAGEWIDTH,
IG_ISIS_CHOICE_STEP, &lStep);
/* Get the current X position. */
IG_ISIS_tag_get_rational(hScan, IG_ISIS_TAG_XRESOLUTION, 0,
&rat);
/* Multiply 3" by resolution (after converting to an integer).
*/
lWidth  = 3*(rat.Num+rat.Denom-1)/rat.Denom ;
if (lWidth > lHigh-lLow)
/* scanner cannot scan an area 3" large */
    return -1;
/* Compute the left edge of the page to the nearest step. */
lLeft = (lHigh - lLow - lWidth) / 2 ; /* Find middle */
lLeft = lLeft - (lLeft % lStep) ;  /* Adjust to closest legal
step */
/* Set the left edge (X position). */
IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_XPOSITION, 0, lLeft);
/* Get the new high value for image width */
IG_ISIS_choice_get_long(hScan, IG_ISIS_TAG_IMAGEWIDTH,
IG_ISIS_CHOICE_HIGH, &lHigh);
/* Set image width to actual width or to the new high value, */
/* whichever is less. */
lWidth = lWidth - (lWidth % lStep) ; /* adjust width to closest
*/
if (lWidth > lHigh)						              /* legal step value. */
    lWidth = lHigh ;
IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_IMAGEWIDTH, 0, lWidth);
/* Repeat everything to set the height. */
IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_YPOSITION, 0, 0L);
IG_ISIS_choice_get_long(hScan, IG_ISIS_TAG_IMAGELENGTH,
IG_ISIS_CHOICE_HIGH, &lHigh);
IG_ISIS_choice_get_long(hScan, IG_ISIS_TAG_IMAGELENGTH,
IG_ISIS_CHOICE_LOW, &lLow);
IG_ISIS_choice_get_long(hScan, IG_ISIS_TAG_IMAGELENGTH,
IG_ISIS_CHOICE_STEP, &lStep);
IG_ISIS_tag_get_rational(hScan, IG_ISIS_TAG_YRESOLUTION, 0,
&rat);
lLength  = 5*(rat.Num+rat.Denom-1)/rat.Denom ;
if (lLength > lHigh-lLow)
    return -1;
lTop = (lHigh - lLow - lWidth) / 2;  /* Find middle */
lTop = lTop - (lTop % lStep);  /* Adjust to closest legal step
*/
IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_YPOSITION, 0, lTop);
IG_ISIS_choice_get_long(hScan, IG_ISIS_TAG_IMAGELENGTH,
IG_ISIS_CHOICE_HIGH, &lHigh);
lLength = lLength - (lLength % lStep) ; /* adjust length to
closest */
if (lLength > lHigh)						                 /* legal step value */
    lLength = lHigh ;
IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_IMAGELENGTH, 0,
lLength);

In the above example, note that the step value for these tags depends on the mode of the scanner. PIXDFLT does not work with fractional bytes of image data; therefore, binary scanning will typically have step values of eight pixels (one byte). The above example truncates to the step to the left, so if the region to be scanned does not fall on a step value, it will be shifted to the nearest step to the left (a maximum of seven pixels).

ISIS scanner drivers default to 300 dots per inch (dpi) if this resolution is available. If 300 dpi is not available, the default resolution is the nearest value that is less 300 dpi. Scanner driver use RATIONAL image resolution values that generally have a denominator of 1, so it is generally safe to work only with the numerator. (Keep in mind that ISIS drivers will accept a RATIONAL value with a denominator of any integer value.) Even though the PixTools/Scan toolkit normally uses RATIONAL values with a denominator of 1, it is quite common for the PixTools/View toolkit to work with TIFF files that have resolutions of, for example, 7,200,000/10,000. This is a valid image resolution according to the TIFF specification.

Some scanners allow X and Y resolutions to be different from one another. To determine if this is the case for the current scanner, you can query the choices for X resolution and Y resolution. On scanners that do not support independent X and Y resolutions, there will only be one choice for the Y resolution, and its value will be the last value set for X resolution. (Note that Standard mode faxes are 200 x 100 dpi.)

Making a List of Available Color Formats

The following example makes a list of available color formats from the current scanner. Note that for this code to work it is necessary to set the value of IG_ISIS_TAG_SAMPLESPERPIXEL in order to find out the choices for IG_ISIS_TAG_BITSPERSAMPLE. (Each value of IG_ISIS_TAG_SAMPLESPERPIXEL could cause the choice for IG_ISIS_TAG_BITSPERSAMPLE to return a different set of choices.)

main()
{
    LONG lBits, lSamps, lValue, lFlags;
    WORD wCount, iIndex;
    HISISDRV hScan;
/* Load and init, for example, Nikon scanner driver */
    IG_ISIS_drv_load_init_pipe(0, "NIKON", &hScan, 0);
/* Find out how many choices there are for SAMPLESPERPIXEL */
    IG_ISIS_choice_get_count(hScan, IG_ISIS_TAG_SAMPLESPERPIXEL,
&wCount);
/* Get and set values for SAMPLESPERPIXEL one at a time */
    for (iIndex = 0; iIndex < wCount; iIndex++) {
        IG_ISIS_choice_get_long(hScan,
IG_ISIS_TAG_SAMPLESPERPIXEL, iIndex,
                         &lSamps);
        IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_SAMPLESPERPIXEL,
0, lSamps);
/* If SAMPLESPERPIXEL is 1, then must be binary, grayscale */
/* or palette color. */
        if (lSamps==1) {
            LONG lValue;
            /* binary, grayscale, or palette color */
/* IG_ISIS_TAG_BITSPERSAMPLE is normally a list, and the
following list
 * logic will also handle the case where it is a range. However
 * it is presented here with specific list and range code to
 * demonstrate how to process both types. IG_ISIS_TAG_RESOLUTION
is, for
 * example, a more common tag that you would want to be able to
 * process as both a list and a range.
 */
/* Determine whether BITSPERSAMPLE is a list or a range */
            IG_ISIS_choice_get_flags(hScan,
IG_ISIS_TAG_BITSPERSAMPLE, &lFlags);
/* Handle case where BITSPERSAMPLE is a list */
            if (lFlags & IG_ISIS_CONT_LIST) {
                WORD iIndex, wCount;
                LONG lBits;
                IG_ISIS_choice_get_count(hScan,
IG_ISIS_TAG_BITSPERSAMPLE, &wCount);
                for (iIndex = 0; iIndex < wCount; iIndex++) {
                    IG_ISIS_choice_get_long(hScan,
IG_ISIS_TAG_BITSPERSAMPLE,
                                    iIndex, &lBits);
                    if (lBits==1)
                        printf("Binary is supported\n");
                    else
                        printf("%d-bit grayscale is supported\n",
                              (int)lBits);
                }
            }
/* Handle case where BITSPERSAMPLE is a range */
            else
            if (lFlags & IG_ISIS_CONT_RANGE) {
                LONG lLow, lHigh, lStep, lBits;
                IG_ISIS_choice_get_long(hScan,
IG_ISIS_TAG_BITSPERSAMPLE,
                                 IG_ISIS_CHOICE_LOW, &lLow);
                IG_ISIS_choice_get_long(hScan,
IG_ISIS_TAG_BITSPERSAMPLE,
                                IG_ISIS_CHOICE_HIGH, &lHigh);
                IG_ISIS_choice_get_long(hScan,
IG_ISIS_TAG_BITSPERSAMPLE,
                                IG_ISIS_CHOICE_STEP, &lStep);
                for (lBits = lLow; lBits <= lHigh; lBits += lStep)
                    if (lBits==1)
                        printf("Binary is supported\n");
                    else
                        printf("%d-bit grayscale is supported\n",
                              (int)lBits);
                }
            }
/* If SAMPLESPERPIXEL is 3, then must be color */
        else
        if (lSamps=3) {
            LONG lValue;
            /* color */
/* Determine whether BITSPERSAMPLE is a list or a range */
            IG_ISIS_choice_get_flags(hScan,
IG_ISIS_TAG_BITSPERSAMPLE, &lFlags);
/* Handle case where BITSPERSAMPLE is a list */
            if (lFlags & IG_ISIS_CONT_LIST) {
                WORD iIndex, wCount;
                LONG lBits;
                IG_ISIS_choice_get_count(hScan,
IG_ISIS_TAG_BITSPERSAMPLE, &wCount);
                for (iIndex = 0; iIndex < wCount; iIndex++) {
                    IG_ISIS_choice_get_long(hScan,
IG_ISIS_TAG_BITSPERSAMPLE,
                                    iIndex, &lBits);
/* The number of bits in color is 3 times the BITSPERSAMPLE */
                    printf("%d-bit color is supported\n",
                          (int)lBits*3);
                }
            }
/* Handle case where BITSPERSAMPLE is a range */
            else
            if (lFlags & IG_ISIS_CONT_RANGE) {
                LONG lLow, lHigh, lStep, lBits;
                IG_ISIS_choice_get_long(hScan,
IG_ISIS_TAG_BITSPERSAMPLE,
                                IG_ISIS_CHOICE_LOW, &lLow);
                IG_ISIS_choice_get_long(hScan,
IG_ISIS_TAG_BITSPERSAMPLE,
                                IG_ISIS_CHOICE_HIGH, &lHigh);
                IG_ISIS_choice_get_long(hScan,
IG_ISIS_TAG_BITSPERSAMPLE,
                                IG_ISIS_CHOICE_STEP, &lStep);
                for (lBits = lLow; lBits <= lHigh; lBits += lStep)
/* The number of bits in color is 3 times the BITSPERSAMPLE */
                    printf("%d-bit color is supported\n",
                          (int)lBits*3);
            }
        }
/* Probably will never see this case: If scanner returns other
than */
/* 1 or 3 SAMPLESPERPIXEL, print number of samples scanner
supports */
        else {
            printf("Scanner supports %d-sample color\n",
                  (int)lSamps);
        }
    }
    IG_ISIS_drv_unload_pipe(hScan);
}

Listing a Scanner's Tags

PixTools/Scan has functions that read and write the values of all tags in a scanner driver. The following sample shows how to get a list of all tags that a scanner supports.

ISIS allows your application to query a scanner and tell it to give you a list of all tags which exist in a driver. The tag that contains this list is tag number zero (0). The following example shows how to use this special tag to get a list of all tags supported in a driver:

LONG lNumTags, dwIndex;
LONG lTagNum;
WORD wType;
char FAR *ucTagType;
/* ask for tag zero's length; that's the number of tags that */
/* the scanner supports */
IG_ISIS_tag_get_length(hScan, 0, &lNumTags);
/* Get the tag number and the tag type for each of lNumTags */
for (dwIndex = 0; dwIndex < lNumTags; dwIndex++) {
    IG_ISIS_tag_get_long(hScan, 0, dwIndex, &lTagNum);
    IG_ISIS_tag_get_type(hScan, (AT_MODE) lTagNum, &wType);
    switch (wType) {
        case IG_ISIS_TAG_TYPE_BYTE:		ucTagType="Byte"; break;
        case IG_ISIS_TAG_TYPE_SHORT:		ucTagType="Word"; break;
        case IG_ISIS_TAG_TYPE_LONG:		ucTagType="Long"; break;
        case IG_ISIS_TAG_TYPE_RATIONAL:	ucTagType="Rational";
break;
        case IG_ISIS_TAG_TYPE_STRING:		ucTagType="Ascii"; break;
        default:				ucTagType="Unknown"; break;
    }
/* Print the tag number and type, one tag per line */
    printf("Tag number %ld is supported, and is of type %s\n",
        lTagNum, ucTagType);
}

The above example prints the number and type of each tag. The string representation for the tag name is not in the toolkit. The # defines that associate strings with tag numbers can be found in PIXTAGS.H

Once you have found the type of a tag, you could extend this example to find out its choices. You can also use this method to find all tag values. Another way to do this is to use the library function IG_ISIS_tag_save_file (). This function saves the current value of all scanner state tags for the referenced driver to a file (usually SETSCAN.INI), in a section of the specified name. A corresponding function is IG_ISIS_tag_restore_file () which can be used after a IG_ISIS_tag_save_file() to restore the values of all tags to their previous saved values. These two functions used together can save and restore the state of an application's settings for a driver.

Checking a Scanner Driver for 8-Bit Grayscale

The following example shows how to determine whether or not eight-bit grayscale is available from a scanner:

/* 1-sample-per-pixel is always allowed (it's needed for binary)
*/
/* Set SAMPLESPERPIXEL to 1 */
IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_SAMPLESPERPIXEL, 0,
1L);
/* how many options exist for BITSPERSAMPLE? */
IG_ISIS_choice_get_count(hScan, IG_ISIS_TAG_BITSPERSAMPLE,
&wCount);
for (i=0;i<wCount;i++) {
/* Get each value of IG_ISIS_TAG_BITSPERSAMPLE */
    IG_ISIS_choice_get_long(hScan, IG_ISIS_TAG_BITSPERSAMPLE, i,
&lValue);
/* If a value of 8 is found, stop looking--8-bit gray is
supported */
    if (lValue==8)
        break;
}
if (i<wCount) {
    /* 8-bit gray is available */
}
else {
    /* 8-bit gray is not available */
}

Displaying a List of Dither Patterns

The following example displays a list of dither patterns that a driver supports:

WORD i,j;
char lpcBuffer[128];
/* ASCII tags are always represented as lists 							*/
IG_ISIS_choice_get_count(hDriver,IG_ISIS_TAG_DITHER,&i);
for (j=0; j<i; j++) {

IG_ISIS_choice_get_ascii(hDriver,IG_ISIS_TAG_DITHER,j,lpcBuffer
);
  printf("%d. %s\n",j,lpcBuffer);
}

Displaying a List of X Resolutions

The following example displays all of the X resolution values that a driver supports:

DWORD dwFlags;
WORD wCount;
int i;
AT_ISIS_RAT ratValue1,ratValue2,ratValue3;
/* RATIONAL tags can be represented as a range or list 							*/
IG_ISIS_choice_get_flags(hDriver,IG_ISIS_TAG_XRESOLUTION,&dwFla
gs);
if (dwFlags & IG_ISIS_CONT_RANGE) {
/*   Choices are represented as a range.  when a driver supports
a
     large number of choices (such as resolution or zoning
     information), and when the choices are represented as a
list,
     then accessing the choice values through the special
indexes
     (LOW, HIGH, STEP) will be much more efficient. 						*/
    IG_ISIS_choice_get_rational(hDriver,
IG_ISIS_TAG_XRESOLUTION, IG_ISIS_CHOICE_LOW,
                         &ratValue1);
    IG_ISIS_choice_get_rational(hDriver,
IG_ISIS_TAG_XRESOLUTION, IG_ISIS_CHOICE_HIGH,
                         &ratValue2);
    IG_ISIS_choice_get_rational(hDriver,
IG_ISIS_TAG_XRESOLUTION, IG_ISIS_CHOICE_STEP,
                         &ratValue3);
/* give ratValue1 and ratValue3 a common denominator 							*/
    if (ratValue3.Denom != ratValue1.Denom) {
        ratValue1.Num *= ratValue3.Denom;
        ratValue1.Denom *= ratValue3.Denom;
        ratValue3.Num *= ratValue1.Denom;
        ratValue3.Denom *= ratValue1.Denom;
    }
    while (ratValue1.Num * ratValue2.Denom <= ratValue2.Num *
          ratValue1.Denom) {
        printf("%ld / %ld\n", ratValue1.Num , ratValue1.Denom);
        ratValue1.Num += ratValue3.Num;
    }
} else /* if (dwFlags & IG_ISIS_CHOICE_LIST) */ {
/*	 Choices are represented as a list.  Note that 	this code
     would work even if the choices are 	represented as a range.
*/

IG_ISIS_choice_get_count(hDriver,IG_ISIS_TAG_XRESOLUTION,&wCoun
t);
    for (i=0; i<wCount; i++) {

IG_ISIS_choice_get_rational(hDriver,IG_ISIS_TAG_XRESOLUTION,i,&
ratValue1);
        printf("%ld / %ld\n", ratValue1.Num, ratValue1.Denom);
    }
}

ScanAhead™

ScanAhead is a PixTools feature that allows a scanner to achieve a higher throughput by scanning pages that the application hasn't yet requested. Most document imaging scanners today support ScanAhead, including those from Fujitsu, Ricoh, Bell & Howell, Canon, Panasonic, and numerous others. Kodak scanners operate in ScanAhead mode only. IG_ISIS_TAG_SCANAHEAD is a tag that controls whether or not a scanner operates in ScanAhead mode. If your application is written so that it supports IG_ISIS_TAG_SCANAHEAD, it will also work correctly for non-ScanAhead scanners.

ScanAhead Off

If ScanAhead is off, invoking IG_ISIS_run_zone () tells the scanner driver to scan one page. An ordinary scanner will scan one page, output the data for that page, and wait for another IG_ISIS_run_zone() before scanning the next page. There are two cases when the scanner will actually scan one page ahead of the application, even though ScanAhead is not turned on:

  1. If the scanner is a duplex model (capable of scanning both sides of the page at one time) and duplex mode is enabled, both sides of the page are scanned simultaneously, but another IG_ISIS_run_zone() must be issued to obtain the data from the back side. This makes duplex scanning almost transparent to the application. Even though ScanAhead is not on, the application gets both sides of the page with one physical scan, even though the application only requested one side.
  2. When working with a scanner whose IG_ISIS_TAG_FEEDER tag contains IG_ISIS_FEEDER_TELLSCAN. This type of scanner must scan a page when requested to sense whether or not there is a page in the feeder. Once a page is sensed, that page has already been scanned and the data is waiting for the application to request it. When the application issues a IG_ISIS_run_zone(), the data from the page that was already scanned is transferred to the application.

ScanAhead On

If ScanAhead is on when the application issues a IG_ISIS_run_zone() call, the toolkit begins a batch scanning process. The scanner continues to scan pages even though the application may not have requested them. The result is that when the application is running zones, it is probably getting image data that was scanned some time ago while the driver continues to scan more pages. The application can configure the maximum number of pages to scan ahead, if desired, as explained below.

If ScanAhead had no settings or controls, the behavior described above would be the only behavior-the application would continue scanning until the feeder was empty. However, the following tags and functions allow your application to have more control over how ScanAhead works:

IG_ISIS_TAG_SCANAHEAD_PAGES
Returns how many pages have been scanned ahead.
IG_ISIS_TAG_SCANAHEAD_MAXPAGES
Tells the scanner driver how many pages it is allowed to scan ahead. A value of zero means scan until the feeder is empty.
IG_ISIS_drv_send(hScan, IG_ISIS_DRV_SCANAHEADCLEAR, 0, 0);
Causes the driver to throw out all pages that have been scanned ahead but not read by the application. The IG_ISIS_DRV_SCANAHEADCLEAR message discards back pages from duplex scans as well, regardless of whether ScanAhead is on or off.

Duplex Scanning

When scanning in duplex mode, the application should not rely on IG_ISIS_TAG_SCANAHEAD_PAGES to find out whether or not there is a back side waiting to be read, even though some scanners (such as Ricohs) will put this information into this tag. The application should keep track of pages scanned in pairs, and is often required to do so anyway because of file naming requirements for front and back sides.

Pixsl

Pixsl is a DLL and an API that is supplied with PixTools/Scan. It is a batch scanning utility that handles scanning from both feeder and flatbed, takes care of ScanAhead issues, provides automatic file naming of multiple files, including front/back sides and job separators, and performs other important functions related to high-throughput scanning. If you do not want to use Pixsl in your application, you should take a look at how it works so that you can cover all important cases in your batch scanning code. The Pixsl user interface can be seen in PixUtil Demo after choosing Scan Batch to File and naming the file(s) to store the image(s). A dialog box appears.

Note some of the features of this dialog. It gives the user the opportunity to continue scanning the front sides of pages or to turn a stack over and scan the back sides in reverse order. It allows the user to specify the number of pages to scan, and it lets the user specify a paper source (flatbed or feeder and, if connected to a duplex scanner, whether or not duplex mode is enabled). If the scanner supports hardware batch detection, this dialog allows the user to specify how to separate batches (whether to keep or discard the batch separation sheet), and it lets the user enable or disable ScanAhead.

Behind the scenes, Pixsl makes sure that if the user cancels scanning with ScanAhead on, scanning resumes at the correct page number. Pixsl also can save and restore its state so that its settings are maintained when the application next uses it.

IG_ISIS_DRV_SCANAHEADCLEAR

The IG_ISIS_DRV_SCANAHEADCLEAR message that can be sent by calling IG_ISIS_drv_send () discards all pages that have been scanned but not yet transferred to the application by IG_ISIS_run_zone () or equivalent calls. The return value of IG_ISIS_drv_send indicates how many pages were discarded, allowing your application to prompt the user to reload the last n pages for rescanning. It is usually better to have your application process all the pages in a ScanAhead buffer instead of using IG_ISIS_DRV_SCANAHEAD_CLEAR. This can be done by setting IG_ISIS_TAG_SCANAHEAD to zero (stopping ScanAhead) and doing IG_ISIS_run_zone until all pages are retrieved.

Canceling Scanning

Many ISIS scanner drivers are designed to occasionally yield to other operating system tasks so that, among other things, scanning can be canceled. There are some cases, however, where even though the driver is doing the right thing, the scan cannot be canceled. This may happen when there is too much competition for processor time, such as when the computer is allocating memory and disk space for a large scan, when there are other processor-intensive processes running, or when an application is poorly designed.

When a scan is successfully canceled, any image data that has been scanned ahead is discarded. These scanned ahead pages are not left somewhere in memory for the application to access later.

NOTE: Your application will receive a IG_ISIS_DRV_STACKNO-PAGE message in response to a IG_ISIS_drv_is_loaded function call at the time when the last image that has been scanned (ahead) is actually received by the application, and not when the feeder is actually empty. (This behavior helps to make ScanAhead transparent to the application.)

Some scanners do not actually support ScanAhead (notably the Ricoh 410 and Fujitsu 309x series). In such scanners, ScanAhead is implemented in the ISIS driver. Other scanners have ScanAhead built into the scanner hardware, and the ISIS driver just turns the feature on. In scanners that implement ScanAhead themselves, your application has no way of knowing for certain how far ahead pages have been scanned. (The scanned-ahead data is held in the scanner until requested by the application.) In scanners that implement ScanAhead in the ISIS driver, the application can always be certain of the number of pages scanned ahead. Your application will therefore see some differences in the data returned by the IG_ISIS_TAG_SCANAHEAD_PAGES tag. Therefore, you can use IG_ISIS_TAG_SCANAHEAD_PAGES as a general indicator that there are some pages that have been scanned ahead remaining to be retrieved, but not as an absolute indicator of how many pages are remaining.


Letting the User Install and Select Drivers

Many applications will need to give users the ability to select their scanner from among the scanner drivers that are installed, and the ability to add new scanner drivers to their installed set after the application has been installed. The PixTools/Scan toolkit has some built-in features which make this a relatively easy problem to solve.

Selecting and installing drivers is different depending on which platform you are working with; therefore, this chapter is divided into sections for each platform.

Selecting a Scanner

Under Microsoft Windows, scanner drivers may be located in the application directory, a directory of the application's choosing, or in the PIXTRAN subdirectory of the user's WINDOWS directory. Since early 1994, Pixel Translations has been strongly recommending that application developers design their applications to load scanner drivers from the <WINDIR>\PIXTRAN directory. Following this recommendation will reduce problems associated with multiple applications loading multiple instances of the same driver, ensuring that each instance gets the correct version or a warning stating that the version currently loaded may not work properly with the newly-launched application.

Drivers have an extension of .PXN (some older drivers have an extension of .PXW. These will still work in Windows 95/98/Me.) The currently-selected driver, if any, is saved in the SETSCAN.INI file located in the user's WINDOWS directory under the section [Scanner]. Following is a portion of a typical SETSCAN.INI file:

[Scanner]
Driver=AGFAASPI

This shows that the currently-selected scanner is one that uses the AGFAASPI.PXW driver (for the Agfa StudioScan color scanner).

To allow the user to select from among the scanners whose drivers are installed, your application can call the following function from, for example, a Select Scanner command on the File menu:

IG_ISIS_drv_set_scan_name(HWND hParent);

with a parameter of the handle to the parent window. This results in a dialog box being displayed:

The list of scanners that appears in this dialog box differs according to the actual drivers on the user's disk. The user now picks the desired scanner from the list, then clicks OK. The following actions then occur:

  1. The library checks the SETSCAN.INI file to determine whether setup configuration information has ever been saved for the selected scanner. Every scanner ever selected has its own section in this file. If the driver has been selected in the past, then the scanner is selected using the previously-saved configuration information. If not, and if the scanner is one that has user-settable configuration information, the library displays the Scanner Configuration dialog box that would have been displayed if the user had clicked Setup instead of OK.
  2. To obtain this information, the library temporarily loads the scanner driver. When it does so, it checks permissions. If the user does not have sufficient permissions to use this driver, then an error message is displayed instead.
  3. Note that the Scanner Configuration dialog box can also be displayed independently by calling IG_ISIS_drv_configure. Many application developers choose to implement their own scanner selection dialog to conform to their application's look and style. If this is done, the scanner selection dialog should implement a Configure button which calls IG_ISIS_drv_configure () to allow the scanner to be configured. Once scanner configuration information has been established and written to the SETSCAN.INI file, the scanner is selected, and its driver is unloaded. The driver can now be used loaded and used by the application. (The driver does not remain loaded because, since your application did not load it, it does not have a handle to the driver and cannot reference it.)

Determining the Selected Scanner

So far, the application has displayed a dialog box asking the user to select a scanner, the user has selected a scanner, and configuration information for that scanner, if any, has been established. In order for the application to determine which scanner has been selected, it can call IG_ISIS_drv_get_scan_name (), which will return the name of the driver for the selected scanner. With this information, the application can load, initialize, and link the scanner driver into an ISIS pipe.

Adding a Scanner Driver

To add a scanner driver, the application can display the Scanner Selection dialog box by calling IG_ISIS_drv_set_scan_name (). The user can then click the Add button to display the Add Scanner dialog

This dialog prompts the user to insert a diskette containing the scanner driver, and then prompts the user through the installation process.

Keep in mind that the user can install any ISIS scanner driver, but may not have the necessary level of permissions to use it. In this case, the user will get an error message when the application loads the driver (probably when configuration is performed right after selecting the driver for the first time).

NOTE: By using this dialog box, all drivers are installed in the <WINDIR>\PIXTRAN directory. If your application does not follow Pixel's guidelines for driver location, this may cause problems in your application's ability to load drivers.

Installing a Scanner Driver

Scanner drivers can be installed using the IG_ISIS_install_driver () function.If you want more control over the scanner driver installation process, use the IG_ISIS_install_driver_init () function (to return a IG_ISIS_install_driver handle) along with the IG_ISIS_install_driver_step () function (to perform each step in the installation) and IG_ISIS_install_driver_done () function (to clean up the installation). You can also call IG_ISIS_install_driver_set_long () and IG_ISIS_install_driver_set_ascii () to set up parameters of the installation.

See the online help for more information about these functions and specific tags.


Using ImageGear JBIG2 Component

The ImageGear JBIG2 component enables you to load and save images using a method based on the JBIG2 compression algorithm. The JBIG2 format supports multi-page images and is the most effective compression method for bitonal (B\W) images.


JBIG2 Format Filter

If you attach JBIG2 Component to core ImageGear it allows you to initialize JBIG2 Format Filter functionality, that can be accessed through core ImageGear Format Filter API. JBIG2 Format Filter supports some features of bitonal file processing. These features are determined by IG_FLTR_ flags. This Format Filter also allows you to save JBIG2 images with different compressions depending of image bit depth.

Supported Features

ImageGear JBIG2 Format Filter supports such features of JBIG2 file processing:

    • IG_FLTR_DETECTSUPPORT - autodetection.
    • IG_FLTR_PAGEREADSUPPORT - single page file reading.
    • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading.
    • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing.
    • IG_FLTR_MPAGEWRITEPSUPPORT - multi-page file writing.

You can detect, read, write and work with pages in multi-page JBIG2 files using ImageGear API.

Supported Compressions for Images

ImageGear JBIG2 Format Filter allows you to save JBIG2 image file using such compressions:

    • IG_COMPRESSION_JBIG2 - 1 bpp


JBIG2 Filter Control Parameters

ImageGear JBIG2 Format Filter provides you with a bunch of control parameters that are optional but can be used for JBIG2 file processing perfection and/or according your own reasons. Currently there are 5 control parameters:

    • JBIG2_DISABLE_CSM ,
    • JBIG2_FILE_ORG ,
    • JBIG2_GENERIC_IMAGE_MMR ,
    • JBIG2_GENERIC_IMAGE_TEMPLATE ,
    • JBIG2_REMOVE_FLY_SPECK

See the reference of these parameters below.


JBIG2_DISABLE_CSM

Group: Control Parameter

Description:

This parameter, when TRUE, specifies that Combined Symbol Matching will not be used. When this option is TRUE, the compression algorithm uses lossy compression. Using lossy compression is likely to result in an image that is smaller (lossless compression can result in encoded images up to 2-3x larger) and a compression speed that is slower than when using lossless compression.

Data Type:

BOOL

Valid Values:

TRUE, FALSE

Default Value:

FALSE


JBIG2_FILE_ORG

Group: Control Parameter

Description:

This function specifies the file format generated by the encoder.

    • IG_JB2_FILEORGDISTRIBUTED creates a sequential document suitable for transmission.
    • IG_JB2_FILEORGCENTRAL creates a document that allows random access to the pages in the document.

JBIG2 files may be organized in two ways; by sequential access or by random access.

    • In sequential organization (IG_JB2_FILEORGDISTRIBUTED), each page's header immediately precedes the page's data.
    • In random access organization (IG_JB2_FILEORGCENTRAL), all page headers are collected together at the beginning of the file, followed by the data for all of the segments in the same order.

The second organization permits a decoder to determine all the segment dependencies without reading the entire file. Sequential organization is suitable for transmitting images through a network - page by page. Random access organization is used for quick access to each page in an image.

Data type:

INT

Valid Values:

  • IG_JB2_FILEORGDISTRIBUTED = 0
  • IG_JB2_FILEORGCENTRAL = 1

Default Value:

IG_JB2_FILEORGDISTRIBUTED = 0


JBIG2_GENERIC_IMAGE_MMR

Group: Control Parameter

Description:

This parameter specifies that MMR (G4) encoding should be used for generic image segments.

A typical JBIG2 page contains text data, i.e., small characters arranged in horizontal or vertical rows. The characters in a page's text section are called symbols in JBIG2. A page may also contain halftone data, i.e., grayscale or color photographic images that have been dithered to produce bi-level images. A page may also contain non-text data, such as large characters, line art, and noise. Such non-text data is called generic data in JBIG2.

There are two methods for coding the generic image segment: arithmetic coding and MMR (G4) coding (MMR - Modified Modified READ). MMR provides less compression (up to 4-5 times) than image bitmap compression based on arithmetic coding. Image bitmap decoding using MMR is faster than image bitmap decoding based on arithmetic coding.

Data type:

BOOL

Valid Values:

TRUE, FALSE

Default Value:

FALSE


JBIG2_GENERIC_IMAGE_TEMPLATE

Group: Control Parameter

Description:

This parameter specifies one of four templates for the arithmetic coder. The JBIG2 working draft describes these templates in detail. Typically, IG_JB2_GENERICIMAGETEMPLATE16 is used for halftone photographic images and IG_JB2_GENERICIMAGETEMPLATE10B or IG_JB2_GENERICIMAGETEMPLATE10A is used for images that contain primarily text. IG_JB2_GENERICIMAGETEMPLATE13 falls somewhere between halftone images and text.

Data type:

INT

Valid Values:

  • IG_JB2_GENERICIMAGETEMPLATE16 = 2
  • IG_JB2_GENERICIMAGETEMPLATE13 = 3
  • IG_JB2_GENERICIMAGETEMPLATE10A = 4
  • IG_JB2_GENERICIMAGETEMPLATE10B = 5

Default Value:

IG_JB2_GENERICIMAGETEMPLATE16 = 2


JBIG2_REMOVE_FLY_SPECK

Group: Control Parameter

Description:

This parameter specifies whether or not isolated single pixels, also known as "fly specks", should be removed.

Data type:

BOOL

Valid Values:

TRUE, FALSE

Default Value:

FALSE


Using ImageGear JPEG2000 Component

The ImageGear JPEG2K Component allows you to create an imaging application, supporting JPEG2000 standard (Part I), JPEG2000 extensions (Part II) and Motion JPEG2000 (Part III) formats.

The JPEG2000 standard (JP2, J2K, JPC) provides set of features that are of importance to many high-end and emerging applications by taking advantage of new technologies. It addresses areas where current standards fail to produce the best quality or performance and provides capabilities to markets that currently do not use compression. The markets and applications better served by the JPEG2000 standard are Internet, color facsimile, printing, scanning (consumer and pre-press), digital photography, remote sensing, mobile, medical imagery, digital libraries / archives and E-commerce. Each application area imposes some requirements that the standard should fulfill.

Many applications require extensions to the JPEG2000 file format that would prevent the file from being treated improperly. To avoid such confusions JPEG2000 Standard Part II defines extended format called JPX. Using this extension allows applications to operate images with different colorspaces (like CMYK), better handle for transparent channels and define more metadata elements.

The Motion JPEG2000 file format (MJ2) is designed to contain one or more motion sequences of JPEG2000 images, with their timing, and also optional audio annotations, all composed into an overall presentation. It's expected to be used in a variety of applications, particularly where the codec is already available for other reasons, or where the high-quality frame-based approach, with no inter-frame coding, is appropriate.

For more information about JP2, JPX and MJ2 please go to the site:

http://www.jpeg.org/JPEG2000.html

See Also:

JPEG2000 Format Support

JPX Format Support

MJ2 Format Support


JPEG2000 Format Support

The ImageGear JPEG2K component is based on Kakadu SDK and allows for utilizing the wide functionality of the JPEG2000 Standard (JP2, J2K, JPC) (ISO/IEC 15444-1). It provides following advantages:

  • The ability to read/write JPEG2000 codestream and JP2 format. See also FILE_FORMAT.
  • Excellent image quality at high compression rates. A major difference between JPEG2000 and the well known JPEG (Joint Photographic Experts Group) technique is the use of the analyzing method. While JPEG uses the Discrete Cosine Transform, JPEG2000 uses a special Discrete Wavelet Transform, which results in improved image quality. The Discrete Wavelet Analysis is performed over the whole image without partitioning it into many different tiles. The reconstructed image does not contain blocking artifacts corresponding to these initial tiles even at high compression rates. See also Discrete Wavelet Transform (DWT) and WAVELET_FILTER, WAVELET_LEVELS.
  • Choice of lossless and loss image compression. The analyzing wavelet filter operation allows a lossless compression at low compression rates and a loss compression at higher rates. The lossless compression is the lowest possible compression rate. The JPEG2000 compression is so efficient it outperforms comparable lossless image compression techniques like LZW and TIFF.
  • User controlled output loss compression rate. The image to be stored may be compressed to either a predetermined rate or to achieve a desired quality. If set for a predetermined compression rate the size of the resulting JPEG2000 file will meet the rate exactly. While using other compression techniques, the size of a compressed file depends on the image contents and differs over a wide range. The different progression orders available in a JPEG2000 compressed file allows for size-dependent compression control. In addition to compression rate this component allows to set a different number of quality layers. See also RATE_BYTES.
  • Support of different image types. JPEG2K Component supports following image types and bit depths: palette-based (1,4,8 bit depths), grayscale (8, 16 bit depths), and truecolor (24 bit depth). Restricted ICC profiles are supported as well.
  • User controlled opacity and transparency information (alpha channel transparency). The ImageGear JPEG2K component allows to store and load alpha channel transparency for all color channels. Loading and saving of additional alpha channels can be performed using core ImageGear functionality. See also "AlphaMapping".
  • User controlled reading/writing of JPEG2000 format metadata (XML and IPR). Non-image information (XML and IPR) does not affect the decoding or visual appearance of the image itself. See also JPEG2000 Part I (JPEG2K) Metadata Tags and Non-image Dataset Structure for JPEG2K as well as "XML" and "IPR".
  • Quicklook generation and scaled image reconstruction based on embedded coding techniques: The resolution progression feature of the compressed JPEG2000 data is best suited to perform a scaled reconstruction. The reconstruction process can be interrupted at any time and the partly processed data contains information of the full-size image. The reconstructed image appears in the appropriate quality corresponding to the processed amount of image data. If the image is reconstructed only for quicklook purposes, the best quality is not necessary because it is displayed at a fraction of the original image size. Using ImageGear JPEG2K component the quality and size of the reconstructed image can be scaled. This reconstructed image may be shown clearly because critical image information is located at the beginning of the compressed file, and remaining data follows in the order of detail. See also DISCARD_LEVELS, MODE.

These features outperform all other image compression techniques. JPEG2K image compression is suited well for sensitive image compressions because of the lossless feature, or for its excellent image quality at high compression ratios for uses such as transmission in low bandwidth applications.

If you attach JPEG2000 Component to core ImageGear it allows you to initialize JPEG2K Format Filter functionality, that can be accessed through core ImageGear Format Filter API. JPEG2K Format Filter supports some features of JPEG2000 Part I format file processing.

Supported Features

ImageGear JPEG2K Format Filter supports such features of JPEG2000 Part I file processing:

    • IG_FLTR_DETECTSUPPORT - autodetection.
    • IG_FLTR_PAGEREADSUPPORT - single page file reading.
    • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing.

You can detect, read and write JPEG2K files.

Supported Compressions for Images

ImageGear JPEG2K Format Filter allows you to save JPEG2000 Part I image file using such compression:

    • IG_COMPRESSION_JPEG2K - for 1, 4, 8, 16, 24, 32 bpp

JPEG2000 Format Filter Control Parameters

ImageGear provides the following control parameters for JPEG2000 Format filter:

  • CODE_BLOCK_SIZE
  • CODE_BLOCK_STYLE
  • DISCARD_LEVELS
  • DISPLAY_OPTIMIZED
  • FILE_FORMAT
  • MODE
  • PROGRESSION_ORDER
  • QUALITY_LAYERS
  • QUANT_STEP
  • RATE_BYTES
  • STITCH_TILES
  • TILE_HEIGHT
  • TILE_WIDTH
  • VIEW_HEIGHT
  • VIEW_WIDTH
  • WAVELET_FILTER
  • WAVELET_LEVELS
See Also:

JP2, JPX and MJ2 Format Filters Control Parameters Reference


JPX Format Support

JPEG2000 Standard Part II defines JPX file architecture rather than a specific, fixed set of data structures that will be found in a file. The ImageGear JPEG2K component provides you with the support of the following important JPX features:

  • In addition to the JP2 color spaces, JPX offers much richer set of color descriptions. These include a much larger set of colour spaces, arbitrary ICC profiles, and vendor-specific colour spaces. ImageGear JPEG2K Component understands more than fifteen color spaces.
  • ImageGear JPEG2K Component allows you to manipulate JPX files with many compositing layers. LOAD_COMPOSITION control parameter allows switching between loading of single layer and loading result composition of all available layers according to composition rules, resided within the file.
  • JPX file format extends JP2 with ability to separate transparency channels into different codestreams. In many image editing applications, the color data and the opacity data are edited separately, and thus it is useful to allow those channels to be stored in separate codestreams.
  • JPX file format (and ImageGear JPEG2K Component) allows for specification of fully transparent samples through a chroma-key. File format specifies an array of sample values, one from each color channel. Image locations that contain that combination of sample values shall be considered fully transparent. Desired value of the transparent pixels can be manages thought "Croma" value of assigned metadata.
  • User controlled reading/writing of JPEG2000 format metadata (XML and IPR). Non-image information (XML and IPR) does not affect the decoding or visual appearance of the image itself. See also JPEG2000 Part II (JPX) Metadata Tags and Non-image Dataset Structure for JPX as well as "XML" and "IPR".

If you attach JPEG2K Component to core ImageGear it allows you to initialize JPX Format Filter functionality, that can be accessed through core ImageGear Format Filter API.

Supported Features

ImageGear JPX Format Filter supports the following features of JPEG2000 Part II (JPX) file processing:

    • IG_FLTR_DETECTSUPPORT - autodetection.
    • IG_FLTR_PAGEREADSUPPORT - single-page file reading.
    • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing.
    • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading.
    • IG_FLTR_MPAGEWRITEPSUPPORT - multi-page file writing.

You can detect, read and write JPX files.

Supported Compressions for Images

ImageGear JPX Format Filter allows you to save JPEG2000 Part II (JPX) image file using such compression:

    • IG_COMPRESSION_JPEG2K - for 1, 4, 8, 16, 24, 32 bpp

JPX Format Filter Control Parameters

ImageGear provides the following control parameters for JPX Format filter:

  • CODE_BLOCK_SIZE
  • CODE_BLOCK_STYLE
  • DISCARD_LEVELS
  • DISPLAY_OPTIMIZED
  • FILE_FORMAT
  • LOAD_COMPOSITION
  • MODE
  • PROGRESSION_ORDER
  • QUALITY_LAYERS
  • QUANT_STEP
  • RATE_BYTES
  • STITCH_TILES
  • TILE_HEIGHT
  • TILE_WIDTH
  • VIEW_HEIGHT
  • VIEW_WIDTH
  • WAVELET_FILTER
  • WAVELET_LEVELS
See Also:

JP2, JPX and MJ2 Format Filters Control Parameters Reference


MJ2 Format Support

Support of Motion JPEG2000 file format (MJ2) is based on support of JP2 file formats, since MJ2 is designed to contain one or more motion sequences of JPEG2000 images. Thus ImageGear JPEG2K component is able to handle all features of single image which can be extracted from any track, available in MJ2 file. To select particular video track VIDEO_TRACK control parameter should be used.

If you attach JPEG2K Component to core ImageGear it allows you to initialize Motion JPEG2000 (MJ2) Format Filter functionality, that can be accessed through core ImageGear Format Filter API.

Supported Features

ImageGear MJ2 Format Filter supports the following features of JPEG2000 Part III (MJ2) file processing:

  • IG_FLTR_DETECTSUPPORT - autodetection.
  • IG_FLTR_PAGEREADSUPPORT - single page file reading.
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading.

You can detect and read MJ2 files using IG_fltr_...() functions.

Supported Compressions for Images

ImageGear MJ2 Format Filter allows you to save JPEG2000 Part III (MJ2) image file using such compression:

    • IG_COMPRESSION_JPEG2K - for 1, 4, 8, 16, 24, 32 bpp

MJ2 Format Filter Control Parameters

ImageGear provides the following control parameters for MJ2 Format filter:

  • CODE_BLOCK_SIZE
  • CODE_BLOCK_STYLE
  • DISCARD_LEVELS
  • DISPLAY_OPTIMIZED
  • FILE_FORMAT
  • MODE
  • PROGRESSION_ORDER
  • QUALITY_LAYERS
  • QUANT_STEP
  • RATE_BYTES
  • STITCH_TILES
  • TILE_HEIGHT
  • TILE_WIDTH
  • VIDEO_TRACK
  • VIEW_HEIGHT
  • VIEW_WIDTH
  • WAVELET_FILTER
  • WAVELET_LEVELS
See Also:

JP2, JPX and MJ2 Format Filters Control Parameters Reference


JP2, JPX and MJ2 Format Filters Control Parameters Reference

This section contains detailed information about ImageGear JP2, JPX and MJ2 format filters control parameters. ImageGear provides you with Format Filter API for getting/setting these control parameters and for retrieving information about them.

    • IG_fltr_ctrl_get ()
    • IG_fltr_ctrl_set ()
    • IG_fltr_ctrl_list ()

For the detailed information about these functions/methods calls, please, see the section Using Format Filters API for Filter Control.

Currently ImageGear JPEG2K component provides the following control parameters:

  • CODE_BLOCK_SIZE
  • CODE_BLOCK_STYLE
  • DISCARD_LEVELS
  • DISPLAY_OPTIMIZED
  • FILE_FORMAT
  • ICC_PROFILE_MODE
  • LOAD_COMPOSITION
  • MODE
  • PROGRESSION_ORDER
  • QUALITY_LAYERS
  • QUANT_STEP
  • RATE_BYTES
  • STITCH_TILES
  • TILE_HEIGHT
  • TILE_WIDTH
  • VIDEO_TRACK
  • VIEW_HEIGHT
  • VIEW_WIDTH
  • WAVELET_FILTER
  • WAVELET_LEVELS


CODE_BLOCK_SIZE

Group: Control Parameter

Data type: AT_INT

Purpose:

Nominal code-block dimension. Actual dimension is the subject to precinct, tile and image dimensions.

Valid Values:

Must be powers of 2 and no less than 4.

Default Value: 64

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


CODE_BLOCK_STYLE

Group: Control Parameter

Data type: enumJPEG2KCodeBlockStyles

Purpose:

Block coder mode switches. Any combination of values from enumJPEG2KCodeBlockStyles is legal.

Valid Values:

IG_JPEG2K_CODE_BLOCK_STYLE_ALL_OFF = 0,

IG_JPEG2K_CODE_BLOCK_STYLE_BYPASS = 1,

IG_JPEG2K_CODE_BLOCK_STYLE_RESET = 2,

IG_JPEG2K_CODE_BLOCK_STYLE_RESTART = 4,

IG_JPEG2K_CODE_BLOCK_STYLE_CAUSAL = 8,

IG_JPEG2K_CODE_BLOCK_STYLE_ERTERM = 16,

IG_JPEG2K_CODE_BLOCK_STYLE_SEGMARK = 32

Default Value:

IG_JPEG2K_CODE_BLOCK_STYLE_ALL_OFF


DISCARD_LEVELS

Group: Control Parameter

Data type: INT

Purpose:

This parameter affects the decompression process. It allows to load reduced version of image, which takes less time then loading of the whole image.

It This parameter indicates the number of highest resolution DWT levels which will not appear at the output image. Image dimensions are essentially divided by 2 to the power of this number. If specified number exceeds the number of DWT levels then it will be set to the maximal possible value.

To allow using DISCARD_LEVELS parameter on images saved by ImageGear you must save images with WAVELET_LEVELS parameter set to more then one level.

Valid Values:

From 0 to maximal value depends on DWT levels in compressed JPEG2000 image.

Default Value: 0

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


DISPLAY_OPTIMIZED

Group: Control Parameter

Data type: Boolean

Purpose:

This parameter forces filter to produce RGB24 images regardless of original colorspace, alpha channels and bit depth. It's necessary to note, that this parameter doesn't suppose faster load. Although current implementation uses Kakadu's workhorse clases, some slowdown is available due to differencies in Kakadu and ImageGear RGB24 representation. Kakadu uses 32 bits per pixels whetheras ImageGear - 24. Thus additional loop is performed to convert result raster from 32-bit RGB to 24-bit.

Here are some results of performance for different types of viewing area:

  • 300K image:

Testing image: {3072x2048}.

Viewing Area: {640x480}.

'As Is Load' time: 0.543000 (sec.).

'Screen Bounded Load' time: 0.066250 (sec.).

  • 1.8Mb image:

Testing image: {3072x2048}.

Viewing Area: {800x600}.

'As Is Load' time: 1.160000 (sec.).

'Screen Bounded Load' time: 0.332000 (sec.).

NOTE: This parameter was designed for those customers, who need only to display images. This parameter forces JP2 filter to use Kakadu native high-level classes that do all data processing in its own way avoiding temporary transformations from Kakadu to ImageGear structures.

Valid Values:

True, False

Default Value: False

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


FILE_FORMAT

Group: Control Parameter

Data type: INT

Purpose:

Specifies whether the result file will be a JP2-compatible file or a raw JPEG2000 code-stream. Fully JP2/JPX compatible file contains various metadata such as resolution, colorspace, palette, XML, etc. Raw code-stream does not store any metadata.

Valid Values:

  • IG_JPEG2K_FORMAT_CODESTREAM = 0
  • IG_JPEG2K_FORMAT_JP2 = 1

Default Value:

IG_JPEG2K_FORMAT_JP2 = 1


ICC_PROFILE_MODE

Group: Control Parameter

Data type:

INT

Purpose:

Specifies the usage mode for ICC profiles embedded into JPEG2K and JPX images.

There are two possible values of this control:

  • JPEG2K_ICC_PROFILE_LOAD: ImageGear loads the embedded profile and attaches it to the image. It does not apply the profile to image pixels during loading. If ImageGear ICC support is enabled, ImageGear uses this profile for image display and for colorspace conversion.
  • JPEG2K_ICC_PROFILE_APPLY: ImageGear converts the image to sRGB colorspace using the embedded profile, during loading. Use this mode for compatibility with ImageGear version 15.1 and earlier.

Valid Values:

  • JPEG2K_ICC_PROFILE_LOAD = 0
  • JPEG2K_ICC_PROFILE_APPLY = 1

Default Value:

JPEG2K_ICC_PROFILE_LOAD


LOAD_COMPOSITION

Group: Control Parameter

Data type: Boolean

Purpose:

This parameters affects JPX filter only and allows switching between loading of single layer and loading result composition of all available layers according to composition rules, resided within JPX file.

Valid Values:

FALSE, TRUE

Default Value:

FALSE


MODE

Group: Control Parameter

Data type: INT

Purpose:

Specifies the mode of the reading process. There are three possible values of this control:

    • IG_JPEG2K_MODE_FAST - The fast mode is used by default. In this case, compliance is assumed and checking is minimized; there is no attempt to recover from any errors.
    • IG_JPEG2K_MODE_FUSSY - In the fussy mode, the code-stream management machinery makes a serious attempt to identify compliance violations and generates an appropriate terminal error message if it finds one.
    • IG_JPEG2K_MODE_RESILIENT - In the resilient mode, the code-stream management machinery makes a serious attempt to both detect and recover from errors in the code-stream. We attempt to guarantee that decompression will not fail, so long as the main header is uncorrupted and there is only one tile with one tile-part.

Valid Values:

  • IG_JPEG2K_MODE_FAST = 0
  • IG_JPEG2K_MODE_FUSSY = 1
  • IG_JPEG2K_MODE_RESILIENT = 2

Default Value: IG_JPEG2K_MODE_FAST = 0

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


PROGRESSION_ORDER

Group: Control Parameter

Data type: enumJPEG2KProgressionOrders

Purpose:

This parameter specifies progression order. Any constant from enumJPEG2KProgressionOrders enumeration is valid.

Valid Values:

IG_JPEG2K_PROGRESSION_ORDER_LRCP = 0,

IG_JPEG2K_PROGRESSION_ORDER_RLCP = 1,

IG_JPEG2K_PROGRESSION_ORDER_RPCL = 2,

IG_JPEG2K_PROGRESSION_ORDER_PCRL = 3,

IG_JPEG2K_PROGRESSION_ORDER_CPRL = 4

Default Value:

IG_JPEG2K_PROGRESSION_ORDER_LRCP


QUALITY_LAYERS

Group: Control Parameter

Data type: AT_DOUBLE | AT_LP

Purpose:

This parameter represents more powerful variant of RATE_BYTES control parameter. Its value is an array of one or more bit-rates, expressed in terms of the ratio between the total number of compressed bits (including headers) and the largest horizontal and vertical image component dimensions. The number of elements in array represents the number of quality layers. If parameter is NULL, then RATE_BYTES parameter is used to limit the output codestream.

Valid Values:

Default Value:

NULL


QUANT_STEP

Group: Control Parameter

Data type: DOUBLE

Purpose:

This control parameter is the base step size to be used in deriving irreversible quantization step sizes for every subband.

NOTE: This control parameter is mostly used for 16g images.

Valid Values: the range from 0 to 2

Default Value: 1/256

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


RATE_BYTES

Group: Control Parameter

Data type: INT

Purpose:

This control parameter specifies maximal size of the compressed data in bytes. Supplying non-zero value causes filter to produce codestream with the size not greater than specified value. Zero (default) value instructs filter to use lossless compression.

NOTE: Using the same value for different images causes filter to write files with different compression quality. This happens because RATE_BYTES specifies size of final codestream and thus filter is obligated to use more loss compression for bigger images.

Dividing size of unpacked image (DIB) to some number and specifying result as value of RATE_BYTES parameter simulates quality lost coefficient.

For example, uncompressed truecolor image with 800x600 dimensions has 1,440,000 bytes size. Setting 480,000 as RATE_BYTES value instructs filter to compress image in three times.

Valid Values: 0 - (2^32 - 1)

Default Value: 0

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


STITCH_TILES

Group: Control Parameter

Data type: AT_BOOL

Purpose:

This parameter specifies the way tiled images should de loaded. If TRUE then all tiles are stitched into image. If FALSE, then the single tile can be loaded.

Valid Values:

TRUE, FALSE

Default Value:

TRUE


TILE_HEIGHT

Group: Control Parameter

Data type: INT

Purpose:

Specifies the height of one tile in the reference grid. A zero value indicates the image's height.

Valid Values: 0 - (2^32 - 1)

Default Value: 0

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


TILE_WIDTH

Group: Control Parameter

Data type: INT

Purpose:

Specifies the width of one tile in reference grid. A zero value indicates the image's width.

Valid Values: 0 - (2^32 - 1)

Default Value: 0

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


VIDEO_TRACK

Group: Control Parameter

Purpose:

This parameter available for Motions JPEG2000 filter and specifies video tracks from which frame should be loaded.

Valid Values:

Any non-zero value.

Default Value:

1


VIEW_HEIGHT

Group: Control Parameter

Data type:

Int32

Default Value:

0

Valid Values:

0 - (2^32 - 1)

Description:

This parameter is used for loading reduced copies of big images. If the value is nonzero, ImageGear only loads DWT levels which width is not greater than parameter value. Dimensions of each decomposition level are twice greater than that of previous level. A zero value indicates the initial image's height. This parameter is similar to DISCARD_LEVELS in that it allows to select the highest resolution level for image loading.


VIEW_WIDTH

Group: Control Parameter

Data type:

Int32

Default Value:

0

Valid Values:

0 - (2^32 - 1)

Description:

This parameter is used for loading reduced copies of big images. If the value is nonzero, ImageGear only loads DWT levels which width is not greater than parameter value. Dimensions of each decomposition level are twice greater than that of previous level. A zero value indicates the initial image's width. This parameter is similar to DISCARD_LEVELS in that it allows to select the highest resolution level for image loading.


WAVELET_FILTER

Group: Control Parameter

Data type: INT

Purpose:

Specifies the type of Wavelet filter to be used for Wavelet Discrete Transform:

  • IG_JPEG2K_FILTER_AUTO automatically selects the best transform depending on image type. It selects irreversible transform for true color and grayscale images, and reversible transform for paletted images.
  • IG_JPEG2K_FILTER_REVERSIBLE is a reversible transform based on 5\3 filter. This mode allows saving JP2 filter as lossless.
  • IG_JPEG2K_FILTER_IRREVERSIBLE is an irreversible transform based on Daubechies 9\7 filter. It allows JP2 filter to apply lossy compression. The amount of loss and compression ratio are defined by other parameters, such as RATE_BYTES and QUALITY_LAYERS.
NOTE: Selecting the IG_JPEG2K_FILTER_REVERSIBLE filter does not guarantee that image will be saved without loss of quality. To save the image in lossless mode, set RATE_BYTES to 0.
NOTE: Applying irreversible transform to paletted images may result in significant degradation of image quality, because small changes in pixel values may result in significant visual difference after application of palette. Consider using reversible transform for paletted images, or promote images to true color and then use reversible transform.

Valid Values:

  • IG_JPEG2K_FILTER_AUTO = -1
  • IG_JPEG2K_FILTER_REVERSIBLE = 0
  • IG_JPEG2K_FILTER_IRREVERSIBLE = 1

Default Value: IG_JPEG2K_FILTER_AUTO = -1

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


WAVELET_LEVELS

Group: Control Parameter

Data type: INT

Purpose:

Specifies quantity of decomposition levels (stages) for image being saved. Main purpose of each level is to provide ability to faster decompress reduced in size version of original image. Level number defines size of reduced image: level[0] allows to get whole image, level[1] lets get original image reduced in two times by each dimension, level[2] - allows get into four times and etc.

The default value for this parameter is '-1', which tells ImageGear to select the value automatically depending on image type. In this mode, ImageGear uses 0 for paletted images and 5 for other cases.

Valid Values: -1 - 16

Default Value: -1

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


JPIP Client Support

NOTE: AccuSoft JPIP client API currently supports JPEG2000 Part I (JP2, JPC, J2K, J2C) format only.

The AccuSoft JPIP client API can be used by an application to efficiently and dynamically stream portions of a JPEG2000-compressed image over a network. The application based on this API can:

  1. establish a session over which multiple regions of interest within an image may be streamed from a JPIP server
  2. efficiently extract these regions of interest from the cached compressed data on the client side

This makes it possible to vary the region of interest over time to meet the changing needs of an interactive application, and to interactively explore images that are so large that they could not be held in memory in uncompressed form.

The application can use this API to perform the following main tasks:

  • Connect to a JPIP server
  • Request access to a JPEG2000-compressed image
  • Retrieve information about the image, such as dimensions and component configuration
  • Retrieve compressed image data for regions of interest within the image
  • Retrieve image metadata
  • Decompress regions of the image into memory (HIGEAR object)

Region of interest/window

This is a combination of several parameters which define a region of interest in an image for the purpose of interactively requesting image data transfer from a JPIP server. The parameters are as follows:

  • Spatial region of interest - defines a rectangular spatial area of the image.
  • Resolution - typically set according to user's zoom level.
  • Max quality layers - can be varied by the client for progressive display.
  • Image component(s) - typically channels (i.e. RGBA), but can also be used to access slices in a medical image.

An application varies these parameters and sends new windows to the JPIP server as the user takes actions such as panning and zooming, or to facilitate progressive display.

How to use JPIP client API

  • Create JPIP client object with IG_JPIPC_create ().
  • Register a notification callback with IG_JPIPC_CB_register ().
  • Connect to JPIP server with IG_JPIPC_connect ().
  • Wait until information about the image has been received. (Use callback to wait for a network event, call IG_JPIPC_status_get () to get status, and see if isValidImage is TRUE.)
  • Get information about the image with IG_JPIPC_image_info_get (). Use this to inform the user, set up user interface, possibly allocate a HIGEAR to use as a frame buffer.
  • Set a region of interest with IG_JPIPC_window_set ().
  • Respond to network events:
    • Get current session status with IG_JPIPC_status_get ().
    • If IsModifiedWindow is TRUE, the server has modified the window. Call IG_JPIPC_window_get () to get the new window. The user may need to be notified, or the user interface may need to be updated.
    • Update user interface to indicate status, progress.
    • If enough new data has been transferred, get updated image data using IG_JPIPC_image_export () and repaint the display.
  • Respond to user events:
    • If user's ROI has changed, set new window with IG_JPIPC_window_set ().
    • If display area or parameters have changed, get updated image data using IG_JPIPC_image_export () and repaint the display.

Accessing Metadata

The JPIP client API provides access to JPEG2000 metadata (also known as "boxes"). This metadata is the part of the image data transferred during a JPIP session. There are two sets of functions related to metadata:

  • The IG_JPIPC_metareq_* functions allow you to request metadata from the server. If you don't request any metadata, the server may only send the essential metadata which is necessary to decode the image. It may be necessary to explicitly request metadata in order to retrieve metadata beyond what the server sends by default.
  • The IG_JPIPC_metadata_* functions provide access to metadata which has been received from the server.


JPIP Server Support

NOTE: AccuSoft JPIP server API currently supports JPEG2000 Part I (JP2, JPC, J2K, J2C) format only.

ImageGear JPIP server API can be used to implement a JPIP server capable of efficiently and dynamically streaming portions of a JPEG2000-compressed image over a network. A JPIP client can establish a session over which multiple regions of interest within an image may be streamed from the JPIP server. This makes it possible to vary the region of interest over time to meet the changing needs of an interactive application.

An application can use this JPIP server API to perform the following main tasks:

  • Set server settings
  • Start and stop the server
  • Monitor server log and error messages
  • Monitor incoming requests and grant or deny them
  • Supply a JPEG2000 image on the fly (from a file or memory buffer) to use as a request response

How to use JPIP server API

  • Create JPIP server object with IG_JPIPS_create ().
  • Set server parameters with IG_JPIPS_config_set/IG_JPIPS_config_load.
  • (Optional) Register callbacks with IG_JPIPS_CB_register ().
  • Start the server with IG_JPIPS_start ().
  • (Optional) Process callbacks to supply image data for requests and get status information.
  • Delete the server object with IG_JPIPS_delete ().


Using ImageGear MD Component

The MD (Medical) component is a full-featured ImageGear component. It supports the DICOM format, contains a custom API, and includes expanded image processing capabilities beyond those of the baseline ImageGear library.


Loading and Saving DICOM Images

With the MD component loaded, your application is ready to load and save DICOM image files in addition to the file formats normally supported by ImageGear.

Supported features:

  • IG_FLTR_DETECTSUPPORT - autodetection.
  • IG_FLTR_PAGEREADSUPPORT - single page file reading.
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing.
  • IG_FLTR_PAGEDELETESUPPORT - page deleting from multi-page files
  • IG_FLTR_MPAGEWRITEPSUPPORT - multi-page file writing.

Supported Compressions for Images:

  • IG_COMPRESSION_NONE - 8, 9-16, 24 bpp
  • IG_COMPRESSION_JPEG - 8, 9-16, 24 bpp
  • IG_COMPRESSION_JPEG2K - 8, 9-16, 24 bpp
  • IG_COMPRESSION_RLE - 8, 9-16, 24 bpp

Loading DICOM images

Load DICOM images in the same way as you load images of all other formats, using one of the Formats Component loading methods. You can use Page or Document loading modes, and all Image Sources that are supported by the Formats Component. Use DICOM Filter Control Parameters to control loading of the DICOM images.

Saving DICOM images

There are several ways to save DICOM images using ImageGear Medical. The functions included as part of the MD component API have a number of DICOM specific parameters. The others are included in the baseline API. You may need to pass the DICOM parameters to these functions via the Image Control settings. You can also use the ImageGear's Multipage Image API to load and save multipage (cine) DICOM images. The saving functions are listed below.

Description
DLL
DICOM-specific saving
function
MED_DCM_save_DICOM()
DICOM-specific saving
function for a file that has
already been opened and
for which you have a File
Descriptor handle
MED_DCM_save_DICOM_FD()
One of the baseline
ImageGear saving
functions (properties)
IG_save_file()
IG_save_FD()
IG_save_mem()
IG_fltr_save_file()

The important consideration in writing a DICOM image is whether the image being saved out was originally a DICOM image. If the image was originally a DICOM image (and assuming that you have not altered its Data Set to contain illegal values), the saving of such an image is quite a simple process. This chapter describes how to save an image that has a valid Data Set, how to use the DICOM-specific saving functions, and what Image Control options can be used to save the image when using the baseline functions.

Using the DICOM specific saving function

MED_DCM_save_DICOM ()saves the DICOM file using the name specified by the first argument. Here is a sample call:

MED_DCM_save_DICOM("OmyBack.dcm", hIGear,
   MED_DCM_TS_JPEG_LOSSY_8, TRUE, TRUE,
   MED_DCM_PLANAR_PIXEL_BY_PIXEL, TRUE, 100, 0);

Notice that the setting for Transfer Syntax in the sample call indicates that JPEG compression should be used on the file. For this reason the second-to-last argument nJPEGQuality is used. This is the quality setting for lossy JPEG compression. The setting shown (100) results in the highest quality that is possible using this compression scheme. If another Transfer Syntax had been specified, the setting of nJPEGQuality would have been meaningless.

Note that DICOM is a multipage format. When you save an image into existing DICOM file, ImageGear tries to append this image at the end of the file. If for some reason appending of the image is not possible, ImageGear returns an error. If you do not want to append a page, delete the existing file before saving to that filename, or (in DLL version) use IG_fltr_save_file() with bOverwrite parameter set to TRUE.

Saving a DICOM Image Using a File Descriptor

If you are saving a DICOM image to a file for which you have a File Descriptor handle, call MED_DCM_save_DICOM_FD (). Here is a sample call:

MED_DCM_save_DICOM_FD(fd, hIGear, MED_DCM_TS_EXPLICIT_VR_LE,
FALSE, TRUE, MED_DCM_PLANAR_PIXEL_BY_PIXEL, TRUE, 0, 0);

Saving a DICOM Image Using Baseline ImageGear API Calls

ImageGear baseline API functions can also be used to save a DICOM image. However as these functions do not contain any of the custom parameters for saving a DICOM image, you may need to make some Filter Control calls first. You will find the list of available DICOM filter control parameters for saving in the section DICOM Filter Control Parameters.

Here is an example of setting DICOM filter control parameters for saving and then calling the baseline saving function. All of the parameters values used below are different from the component's default values:

/* get current value of SAVE_SYNTAX control parameter */
IG_fltr_ctrl_get(IG_FORMAT_DCM, "SAVE_SYNTAX", FALSE, NULL,
NULL, (LPVOID)nSaveSyntax, sizeof(nSaveSyntax));
/* set new value to SAVE_SYNTAX control parameter */
IG_fltr_ctrl_set(IG_FORMAT_DCM, "SAVE_SYNTAX",
(LPVOID)MED_DCM_TS_EXPLICIT_VR_LE, sizeof(nSaveSyntax));
/* get current value of SAVE_SMALLEST control parameter */
IG_fltr_ctrl_get(IG_FORMAT_DCM, "SAVE_SMALLEST", FALSE, NULL,
NULL, (LPVOID)bSaveSmallest, sizeof(bSaveSmallest));
/* set new value to SAVE_SMALLEST control parameter */
IG_fltr_ctrl_set(IG_FORMAT_DCM, "SAVE_SMALLEST", (LPVOID)TRUE,
sizeof(bSaveSmallest));
nErrcount = IG_save_file(hIGear, "knee.dcm", IG_SAVE_DCM);

Saving DICOM Images with JPEG Compression

ImageGear supports the following modes for saving JPEG compressed DICOM images:

JPEG Lossy Baseline or Extended

This is the default mode for saving DICOM images with JPEG compression in ImageGear. In this mode, depending on the channel depth of the source image, ImageGear saves it as either 8 bits per channel, using "JPEG Baseline (Process 1)" transfer syntax, or as 9..12 bits per channel, using "JPEG Extended (Process 2 & 4)" transfer syntax.

Use one of these ways to save an image as DICOM JPEG Baseline or Extended:

  • Save the image using a general ImageGear saving function, such as IG_fltr_save_file, and passing IG_FORMAT_DCM | IG_COMPRESSION_JPEG << 16 to the lFormatType parameter. JPEG control parameter SAVE_TYPE should be set to IG_JPG_LOSSY. DICOM control parameter SAVE_SYNTAX is ignored.
  • Save the image as IG_FORMAT_DCM, using a general ImageGear saving function. Set DICOM control parameter SAVE_SYNTAX to either MED_DCM_TS_JPEG_LOSSY or MED_DCM_TS_JPEG_EXTENDED_PR_2_4. JPEG control parameter SAVE_TYPE is ignored.
  • Save the image using a DICOM-specific saving function. Set nSyntax parameter to either MED_DCM_TS_JPEG_LOSSY or MED_DCM_TS_JPEG_EXTENDED_PR_2_4. JPEG control parameter SAVE_TYPE is ignored.
JPEG Lossy Baseline Only

This mode provides compatibility with viewers that do not support JPEG Extended coding process (12-bit images). In this mode ImageGear saves images as 8 bits per channel, using "JPEG Baseline (Process 1)" transfer syntax. If the image has greater bit depth, ImageGear reduces it to 8 bits per channel for saving.

Use one of these ways to save an image as DICOM JPEG Baseline:

  • Save the image as IG_FORMAT_DCM, using a general ImageGear saving function. Set DICOM control parameter SAVE_SYNTAX to MED_DCM_TS_JPEG_BASELINE_PR_1_ONLY. JPEG control parameter SAVE_TYPE is ignored.
  • Save the image using a DICOM-specific saving function. Set nSyntax parameter to MED_DCM_TS_JPEG_BASELINE_PR_1_ONLY. JPEG control parameter SAVE_TYPE is ignored.
NOTE: For compatibility with earlier versions of ImageGear, MED_DCM_TS_JPEG_BASELINE_PR_1 constant has the same meaning as MED_DCM_TS_JPEG_LOSSY: the image is saved using either Baseline or Extended process. To save with the Baseline process, make sure to use MED_DCM_TS_JPEG_BASELINE_PR_1_ONLY constant.
JPEG Lossless

In this mode, depending on the channel depth of the source image, ImageGear saves it as 8...16 bits per channel, using "JPEG Lossless, Non-Hierarchical (Process 14)" transfer syntax.

Use one of these ways to save an image as DICOM JPEG Lossless:

  • Save the image using a general ImageGear saving function, such as IG_fltr_save_file, and passing IG_FORMAT_DCM | IG_COMPRESSION_JPEG << 16 to the lFormatType parameter (DICOM control parameter SAVE_SYNTAX is ignored). JPEG control parameter SAVE_TYPE should be set to IG_JPG_LOSSLESS.
  • Save the image as IG_FORMAT_DCM, using a general ImageGear saving function. Set DICOM control parameter SAVE_SYNTAX to either MED_DCM_TS_JPEG_LOSSLESS, or MED_DCM_TS_JPEG_LOSSLESS_FIRSTORDER. JPEG control parameter SAVE_TYPE is ignored.
  • Save the image using a DICOM-specific saving function. Set nSyntax control parameter to either MED_DCM_TS_JPEG_LOSSLESS or MED_DCM_TS_JPEG_LOSSLESS_FIRSTORDER. JPEG control parameter SAVE_TYPE is ignored.

Saving out a DICOM Image from a Non-DICOM Image

If you have created a Data Set for a loaded non-DICOM image and wish to save it, please remember that it is up to you to add all the Mandatory Data Elements to make it a valid Part 3 DICOM file. When you create the Data Set, a handful of basic Data Elements are added to it. These values were taken from the image. Note that they are not sufficient to satisfy the requirements of Part 3 of the Standard.

Saving a Multiframe DICOM Image

ImageGear MD component allows to save single-frame as well as multiframe (multipage) images. Saving a multiframe DICOM image is pretty straightforward. Use any standard image saving function from ImageGear baseline API. Image saving functions from Medical API do not support saving of multiframe images.

Use the following steps to create a multiframe image:

  • Create or load first frame into HIGEAR.
  • Create the DataSet if it is not present.
  • Add the DCM_TAG_NumberOfFrames tag to the DataSet, if it is not present. Value of this tag is irrelevant but its presence is necessary.
  • Save the image using any ImageGear baseline saving function.
  • * Create or load second frame into HIGEAR.
  • Create Data Set if it is not present.
  • Add the DCM_TAG_NumberOfFrames tag to the Data Set, if it is not present.
  • Save the image, specifying the same file name that you used for the first frame.
* Repeat for all consequent frames.

Several limitations that are imposed by the DICOM standard are listed below.

All frames of the image should have same dimensions, bit depth and photometric interpretation. All frames should use the same Transfer Syntax (compression). ImageGear returns an error if these conditions are not met.

NOTE: It is important to note that only a few DICOM modalities allow the presence of multiple frames in the image, while the others do not. When you try to add a frame to an existing DICOM file, ImageGear checks the file for presence of the NumberOfFrames (0028, 0008) Data Element. If it is present ImageGear tries to append the frame, otherwise ImageGear considers the file as belonging to a single-frame modality and returns an error.

Another important fact about DICOM format is that it has a continious structure which means all the Data Elements as well as image frames go one after another. This results in the following limitations:

  • Inserting a frame in a file that contains multiple frames, would lead to rewriting all the consequent frames. The same thing would happen when overwriting a frame in a file that uses some compression. Changed size of the compressed frame would lead to rewriting the whole file. To prevent such unpredictable time-consuming operations, ImageGear Medical only supports appending a frame at the end of the DICOM image, but not insertion or overwriting of frames.
  • ImageGear Medical writes the DICOM DataSet only when writing the first frame, and does not modify it when adding frames. The only exclusion is the "Number Of Frames" Data Element, which is always kept consistent with the actual number of frames.
  • The "Number of Frames" Data Element has a Value Representation of "Integer String", i.e., it is stored in the file as a character string rather than an integer. This string can occupy up to 14 characters. Now imagine that you are appending frame to a file that has 99 frames. The number 99 occupies two bytes in the file (because it is composed of two digits). After a frame is added, the Number Of Frames DE becomes 100, needing 4 positions for its storage (three digits plus padding). This results in the need of shifting the whole file by two bytes. To prevent this, ImageGear Medical always leaves the maximum of 14 positions for storing the Number Of Frames DE. Moreover, it does not append a frame to a file where Value Length of the Number of Frames Data Element is less than 14 (for example, if the file has been created by some other vendor1).

If you need to insert or delete a frame, or modify DataSet in the DICOM image, create a new image with the modified DataSet, copy necessary frames to it, and then delete the original image.

Saving DICOM Images Using ImageGear's Multipage Image API (DLL only)

You can use ImageGear's Multipage Image API calls (IG_mpi_... and IG_mpf_...) for loading and saving multiframe DICOM images. Just note that ImageGear Medical only supports the appending of frames but not insertion, deletion or overwriting of frames.


DICOM Filter Control Parameters

The Medical Component provides the following filter control parameters for loading DICOM images:

    • DETECT_CONTINUOUS_RLE
    • LOAD_CONCAT_REPEATED_DE
    • LOAD_CONVERTTO8G
    • LOAD_DETECTSKIPDIMSE
    • LOAD_MASKALPHACHANNEL
    • LOAD_PAGENUMBER
    • LOAD_SAVE_PIXDATA_TAG
    • LOAD_SYNTAX
    • LOAD_USE_8x8_LUT
    • LOAD_USE_AUTO_WL_FOR_8G

and the following filter control parameters for saving DICOM images:

    • SAVE_ASPART10
    • SAVE_GROUPLENGTHS
    • SAVE_JPEGQUALITY
    • SAVE_LARGEST
    • SAVE_PLANARCONFIG
    • SAVE_SMALLEST
    • SAVE_SYNTAX

The Medical Component uses JPEG and JPEG 2000 format filters for loading and saving compressed DICOM images. Control parameters of JPEG and JPEG 2000 filters are taken into account when loading or saving such images (see JPEG section and JPEG2000 Component API Function Reference Chapter).


DETECT_CONTINUOUS_RLE

Group: Control Parameter

Description:

This parameter specifies what to do with RLE compressed images where RLE runs across row boundaries. If it is set to TRUE, ImageGear tries to detect and load images where RLE runs across row boundaries. Otherwise, ImageGear truncates any row overruns and decodes each row separately. This parameter does not affect the loading of properly encoded images, where each row is encoded separately.

Type:

Boolean

Default:

TRUE

Settings:

TRUE, FALSE


LOAD_CONCAT_REPEATED_DE

Group: Control Parameter

Description:

If this parameter is TRUE then concatenate duplicated tags data, FALSE otherwise.

Type:

Boolean

Default Value:

FALSE

Settings:

TRUE, FALSE


LOAD_CONVERTTO8G

Group: Control Parameter
NOTE: This parameter is not supported now. Use IG_image_channel_depths_change after image loading to change its channel depths.

Description:

If this parameter is TRUE, ImageGear converts 9-16-bit grayscale images to 8 bits during loading. If FALSE, ImageGear loads these images in their native bit depth.

Type:

Boolean

Default Value:

FALSE

Settings:

TRUE, FALSE


LOAD_DETECTSKIPDIMSE

Group: Control Parameter

Description:

This option controls loading process if a DICOM image contains DIMSE commands. DIMSE commands are a type of Data Element, with a group number of "0000" that are almost always removed by the DICOM network protocol before a transmitted image is saved to a disk file. However, sometimes they are found in the file and in such case ImageGear doesn't automatically recognize the file as a DICOM image. This is done because the DIMSE Tags are very hard to differentiate from other file formats that ImageGear supports. However, if DCM_CONTROL_LOAD_DETECT_SKIP_DIMSE is set to TRUE then the auto format detection skips over the DIMSE Tags when it attempts to decide if the file is DICOM or not.

Type: Boolean

Default Value: False

Settings:

  • False- ImageGear will not detect DICOM image files that contain DIMSE commands.
  • True - Allow DIMSE commands and attempt to parse the file as a valid DICOM file.


LOAD_MASKALPHACHANNEL

Group: Control Parameter

Description:

This option controls what would have done if an Alpha Channel image has been stuffed into the upper unused bits of a 16-bit image (Bits Stored < 16). These extra bits can be masked off or loaded along with the actual pixel value. If they are not masked off, you may need to alter the 16x8 LUT in order to display the image appropriately.

Type: Boolean

Default Value: True

Settings:

  • True - The extra bits (the Alpha Channel) are masked off.
  • False - The extra bits will be loaded into the DIB with the rest of the pixel.


LOAD_PAGENUMBER

Group: Control Parameter
NOTE: This parameter is not supported now. Use IG_fltr_load_file to load aspecific page of an image.

Description:

This parameter specifies page number of the DICOM image to load.

Type:

UINT

Default Value:

1

Settings:

Any positive Integer value


LOAD_SAVE_PIXDATA_TAG

Group: Control Parameter

Description:

When LOAD_SAVE_PIXDATA_TAG is TRUE, ImageGear does not read pixel data into a DIB, but rather creates an empty DIB, so the image cannot be displayed. When reading compressed image, IG Medical treats PixelData tag as a Sequence, and places actual binary data into Item tags. This corresponds to the structure of compressed PixelData in DICOM files. When using this parameter for writing, make sure that Transfer Syntax matches actual Transfer Syntax of the PixelData element.

Type:

Boolean

Default:

TRUE

Settings:

TRUE, FALSE


LOAD_SYNTAX

Group: Control Parameter

Description:

This parameter controls the types of DICOM files ImageGear attempts to detect. If the file that is being loaded does not fall into the category specified by this control parameter it will be ignored and a IGE_CANT_DETECT_FORMAT error will be returned.

Type: enumIGMedTS

Default Value: MED_DCM_TS_AUTODETECT

Settings:

  • MED_DCM_TS_AUTODETECT = 9998 - ImageGear makes its best to determine the format of the DICOM file.
  • MED_DCM_TS_PART_10 = 9997 - only files with Part 10 Header will be detected. The Transfer Syntax of the file will be determined from the header and used to load the remainder of the image file.

If you specify any standard DICOM Transfer Syntax, such as MED_DCM_TS_IMPLICIT_VR_LE or MED_DCM_TS_JPEG_LOSSY, the Medical Component will only load files having this Transfer Syntax.


LOAD_USE_8x8_LUT

Group: Control Parameter

Description:

If this parameter is TRUE then use 8x8 LUT for 8-bit images, otherwise use Palette.

Type:

Boolean

Default Value:

TRUE

Settings:

TRUE, False


LOAD_USE_AUTO_WL_FOR_8G

Group: Control Parameter

Description:

If this parameter is TRUE use auto window/level for 8g images, if VOI LUT is not present. If it is FALSE, use default 0...255 window/level.

Type:

Boolean

Default Value:

TRUE

Settings:

TRUE, False


SAVE_ASPART10

Group: Control Parameter

Description:

This parameter controls whether Meta Information Header is saved with the file, or not.

Type: Boolean

Default Value: True

Settings:

  • False - The image is saved as a raw DICOM file
  • True - The image is saved with a Part 10 header, making the file "Part 10-compliant".


SAVE_GROUPLENGTHS

Group: Control Parameter

Description:

This parameter controls the usage of Group Length values in a DICOM file. ImageGear treats these Data Elements as either on or off. That is they either are all included in each Group of Data Elements through the saving process or they are all absent. The internal Data Set that is attached to the HIGEAR does not contain Group Length Data Elements. When a DICOM file is to be written to disk they are computed and inserted if this parameter is set to TRUE.

Type: Boolean

Default Value: True

Settings:

  • True - Group Lengths are saved
  • False - Group Lengths are not saved


SAVE_JPEGQUALITY

Group: Control Parameter
NOTE: This parameter is not supported now. Please use QUALITY control parameter of JPEG filter instead. Please see JPEG section in File Format Reference Chapter.

Description:

This parameter specifies quality for saving DICOM images using JPEG Lossy compression.

Type:

UINT

Default Value:

70

Settings:

1-100


SAVE_LARGEST

Group: Control Parameter

Description:

Controls whether Largest Image Pixel Value (0028,0107) is updated by ImageGear.

If the original image Data Set did not contain a Data Element for Largest Image Pixel Value (0028,0107) and you set SAVE_LARGEST = True, ImageGear scans the image and determines a value for this DE. Largest Image Pixel Value is included in the Data Set of the DICOM image being saved and contains the ImageGear-determined value. The value of the DE from the original Data Set (if any) is ignored.

If you set SAVE_LARGEST = False, ImageGear does not determine this value for you, and the Data Set of the image being saved does not include the Largest Image Pixel Value Data Element. However, if the original Data Set did contain this DE, ImageGear preserves and includes it in the Data Set being saved

Type: Boolean

Default Value: False

Settings:

  • True - The Largest Image Pixel value DE (0028,0107) are set to the minimum pixel value found in the image when it is saved.
  • False - ImageGear does not update the Largest Image Pixel value DE when it saves a DICOM image.


SAVE_PLANARCONFIG

Description:

This parameter controls how the pixels are saved:

  • in normal RGB order ("pixel by pixel" configuration)
  • in a planar configuration meaning that all Red, Blue, and Green pixels are saved in separate planes

Type: AT_MODE

Default Value: MED_DCM_PLANAR_PIXEL_BY_PIXEL

Settings:

  • MED_DCM_PLANAR_PIXEL_BY_PIXEL - Pixels are saved in normal RGB order
  • MED_DCM_PLANAR_PLANE_BY_PLANE - Red, Blue, and Green are stored in separate planes.


SAVE_SMALLEST

Group: Control Parameter

Description:

This parameter controls whether ImageGear updates the Smallest Image Pixel Value (0028,0106).

If the original image Data Set did not contain a Data Element for Smallest Image Pixel Value (0028,0106) and you set SAVE_SMALLEST = True ImageGear scans the image and determines a value for this DE. Smallest Image Pixel Value are included in the Data Set of the DICOM image being saved, and contains the ImageGear-determined value. The value of the DE from the original Data Set (if any) are ignored.

If you set SAVE_SMALLEST = False ImageGear does not determine this value for you, and the Data Set of the image being saved does not include the Smallest Image Pixel Value Data Element. However, if the original Data Set did contain this DE, ImageGear preserves and includes it in the Data Set being saved.

Type: Boolean

Default Value: False

Settings:

  • True - The Smallest Image Pixel Value DE (0028,0106) is set to the minimum pixel value found in the image.
  • False - ImageGear does not update the Smallest Image Pixel Value (0028,0106) when saving a DICOM image.


SAVE_SYNTAX

Description:

This parameter controls how a DICOM file is to be formatted when it is written to disk. It does not control the file being Part 10 or Raw (see bSaveAsPart10), but controls how the non-Group 2 Data Elements are formatted. It also specifies the compression that will be used for Pixel Data.

Type: enumIGMedTS

Default Value: MED_DCM_TS_DEFAULT

Settings:

  • MED_DCM_TS_IMPLICIT_VR_LE = 2 - Implicit VR Little Endian: Default Transfer Syntax
  • MED_DCM_TS_EXPLICIT_VR_LE = 3 - Explicit VR Little Endian
  • MED_DCM_TS_EXPLICIT_VR_BE = 4 - Explicit VR Big Endian
  • MED_DCM_TS_JPEG_LOSSY = 5 - JPEG baseline Transfer Syntax (process 01)
  • MED_DCM_TS_JPEG_LOSSLESS = 12 - JPEG lossless non-hierachical Huffman transfer Syntax (process 14)
  • MED_DCM_TS_JPEG_LOSSLESS_FIRSTORDER = 22 - JPEG Lossless, Hierarchical, First-Order Prediction
  • MED_DCM_TS_JPEG_2K_LOSSLESS_ONLY = 157 - JPEG 2000 Lossless Only
  • MED_DCM_TS_JPEG_2K = 158 - JPEG 2000
  • MED_DCM_TS_RLE = 522 - RLE
  • MED_DCM_TS_DEFAULT = 2 - Default transfer syntax: same as MED_DCM_TS_EXPLICIT_VR_LE
  • MED_DCM_TS_UNKNOWN = 0 - Unknown Transfer Syntax
  • MED_DCM_TS_PART_10 = 9997 - This constant can be passed to the LOAD_SYNTAX image control parameter to load only those DICOM files that have a File Meta Information (Part 10) Header.
  • MED_DCM_TS_AUTODETECT = 9998 - This constant can be passed to the LOAD_SYNTAX image control parameter to load any detectible DICOM files.


Associating DICOM Data with an ImageGear Image

As a DICOM file is being loaded, the ImageGear Medical associates some additional structures with it. DICOM Data Elements are stored into two separate chunks: a table of Data Elements, which holds those Data Elements that make up the core of the image file, and a Part 10 Template, which holds the Data Elements from the Part 10 Header. The Part 10 Header is kept separate due to some of its special characteristics.

The table of Data Elements is internal and is only accessible via the API functions provided by this component. You can remove it (and free its memory), or create a new table if it does not exist. The names of the API functions that allow you to access the data in the internal Data Set table all start with MED_DCM_DS_ .

We refer to the Part 10 Header area as a "template" because it should be created for every loaded DICOM image, even if the image's Data Set is empty. This template always contains the same set of storage fields for Data Elements-even if the Part 10 Header of the loaded image has no value for them. Further on in this section you will find information on how to get and set Part 10 Header values.

The Part 10 Template cannot be removed. However, as you are saving the image you can choose not to save it as "Part 10-compliant" and the image will be saved without this header.


Reading Data From Data Elements

The functions that return you the data for a DE's Data Field include:

MED_DCM_DS_curr_data_get()
Returns the data and size of the data
MED_DCM_DS_curr_data_get_string()
Returns the data as a string and returns the size of the string.

Both of these functions return you the contents of the Data Field of the Current Data Element.

To interpret the returned data call MED_DCM_DS_curr_info_get (). This function returns, among other things, the VR, the VL, and the Item Count.

If the data is binary, i.e. defined as an INT, WORD, etc., you can use the VL and Item Count to determine the length of each item in the Data Field. Binary items aren't delimited; they are stored end-to-end. Since all binary items must be of the same length, you can calculate the length of each item this way:

lengthOfEachItem = VL/Item_count

Using Item_count as a loop delimiter, you can now parse through the data by jumping lengthOfEachItem bytes for as many items as it's returned by Item_count:

for (item = 0; item < Item_count; item++)
    {
    int_array[item] = ((int *)value_field)[item];
    }

Character data items can be of either fixed length or variable length. In either case, you can forgo the calculation shown above for binary data because character data must be delimited by backslashes.


Writing Data to Data Elements

The following API functions allow you to write or overwrite the data of a Data field, respectively:

MED_DCM_DS_DE_insert()
Inserts a new DE to the Data Set. Its placement are determined automatically according to its Tag value. Your only power of placement is in specifying what level in the hierarchy of the Data Set to place the new DE.
MED_DCM_DS_curr_data_set()
Overwrites the Data Field of an existing Data Element.

Whether you are inserting a new DE or overwriting the Data Field of an existing DE, you may need to query the VR and VM by calling MED_DCM_util_tag_info_get (). With the VR in hand, you can call MED_DCM_util_VR_info_mode ()which tells you the length that each item can have, and whether the items are of fixed or variable length. See the previous section "Reading Data From Data Elements" for how to interpret the value returned to you in VM.

The Components of the Data Set

A Data Set is composed entirely of Data Elements. In DICOM, all stored data, including the images themselves, is stored in fundamental DICOM building blocks called Data Elements.

Access to the Data Set is achieved by moving an internal Data Element index called the "Current Data Element" from Data Element to Data Element. There is a set of API functions, which just move the Current Data Element about the Data Set. Another group of API functions will allow you to retrieve or set the Value Field of the Current Data Element.

The Internal Data Set vs. the Original Data Set

The internal Data Set is similar to but not exactly like the Data Set found in the DICOM file. The DICOM standard has many options and various methods of storing its data. As the internal Data Set is being filled, the vital information is stored in an abstract form. The new form of this information makes it easier for you to work with. Most of this internal storage is completely transparent for you and your application, but there are a few items you should be aware of.

First of all, as you move to see the internal Data Set and inspect its contents you may notice that some items that were in the original Data Set are missing. One example of this are the "Group Lengths" (all of which have Element Numbers of 0000). Group Lengths which are optional in the DICOM specification, are placed in the Data Set to aid to quickly find certain Data Elements by allowing the parser to skip over large blocks of Data Elements that do not contain the Data Element being searched for. They serve no other purpose and are therefore removed. If you are going to save the Data Set back out to disk you may request that Group Lengths should be included in the new disk file. If you do so, ImageGear recalculates the Group Lengths in case any Data Elements have been added, removed or altered.

Also missing from the data is the Data Field for Pixel Data (7FE0,0010). It is the Data Element that holds the image. This Data Element is actually present but his Data Field is empty. This is because the image has been read and loaded into an ImageGear DIB.

Another difference from the internal Data Set and the original file version is that regardless of what the original encoding scheme was, the internal Data Set always are "Explicit VR." That is, the Value Representations (VRs) of each Tag are looked up in the Data Dictionary and recorded along with the other information. If you later write the Data Set to disk you may choose whether the Data Set should be Explicit or Implicit VR.

Critical Data Elements

"Critical Data Elements" are those DEs whose values are taken from the image not regarding to whether the Data Set has values for these DEs or not. Two examples of such DEs are the height (Rows) and width (Columns) of the image. Note that the Critical Data Elements in the internal Data Set are always kept consistent with the HIGEAR. For example, if you have resized the image, the DCM_TAG_Columns and DCM_TAG_Rows Data Elements are set to the new Width and Height of the image. When an image processing function, such as Resize or Rotate, is applied to the DICOM image, the values for Rows and Columns will be updated from the HIGEAR.

The Hierarchy of the Data Set

A certain type of Data Element can be hierarchical meaning that it can have other groups of Data Elements "under" it similarly to the way files are stored under the directory structure. This special type of Data Element has a Value Representation of Sequence Delimiter (SQ). This Data Element l marks a set of Data Elements called "Items." This set can contain 0 or more embedded Data Elements. The hierarchical structure can make it difficult to keep track of where you are as you move through the Data Set. This is the reason of using the Current Data Element - to keep track of index you are positioned at in the array of Data Elements.

Data Set Levels

You may notice that many of the Data Set Navigation API contain a parameter of level_op. This argument tells whether the Data Set index should remain in the current level or can be moved to another level. The possible values for this argument are:

  • MED_DCM_MOVE_LEVEL_FIXED
  • MED_DCM_MOVE_LEVEL_FLOAT

Part 10 Header Access

When a DICOM image file is loaded it may or may not begin with a Part 10 Header. The Part 10 Header consists of 2 parts: a free-form block of 128 bytes called a Preamble, and a fixed list of 9 Data Elements, all of which have a Group Number of 0002. Both of these parts are stored in the Part 10 Template mentioned earlier. The use of the Preamble is up to the application and can be used to store anything you like, as long as it is 128 bytes or less. A blank or empty Preamble is indicated by 128 bytes of 0x00.

If the original image has a Part 10 header, the data from it is extracted and placed in the internal template mentioned earlier. If there is no header, the template is empty except for 2 fields: the File Meta Information Version (0002,0001) and the Transfer Syntax UID (0002,0010). Default values are assigned to these fields - File Meta Information Version is set to 0x0001, and Transfer Syntax UID is set to the Transfer Syntax detected by ImageGear when the image was loaded. The Version number is called for the DICOM specification and it value never need to be altered.

Access to the values in the Part 10 Template is done using a small set of methods or functions, which include either "Part10" or "preamble" in their names.

MED_DCM_DS_preamble_get()
get Part 10 Header Preamble
MED_DCM_DS_preamble_set()
set Part 10 Header Preamble
MED_DCM_DS_part10_get()
get Part 10 Header Data Elements, except Preamble
MED_DCM_DS_part10_set()
set Part 10 Header Data Elements, except Preamble


Displaying Medical Grayscale Images

Many of the medical images use more than 8 bits per grayscale pixel. The main concern in displaying such images is that commonly used monitors can display only 256 shades of gray, which corresponds to 8 bits per pixel. The 16-bit pixels need to be mapped in some way to 8-bit pixels. ImageGear uses two approaches for this mapping.

If a 9..16 bit grayscale image has been loaded from a non-DICOM file, its pixels are mapped to 8g by left shifting the pixels by (n-8), where n is the bit depth of the image. For example, if the image has 12 bits per pixel, its pixels will be left shifted by 4 bits, so the 8 most significant bits of the 12-bit pixel will be used. This mapping is done only for image display, and does not affect the image stored in memory.

When ImageGear loads a DICOM image, it creates a 16-bit to 8-bit, or 8-bit to 8-bit display Look Up Table (16x8 LUT or 8x8 LUT), and attaches it to the image. This LUT gives more flexibility in displaying medical images, allowing to display a certain range of pixel intensities with best contrast.

DICOM image files may contain several Look Up Tables that describe how the image shall be displayed. "Modality" LUT specifies transform of image pixels into modality meaningful values, such as optical density or Hounsfield Units. "Value of Interest" LUT (VOI LUT) specifies what range of pixel intensities should be shown on the screen. Most often, both these LUTs are linear, and thus are presented by a pair of values that are similar to brightness and contrast. For Modality LUT, these are Rescale Intercept (0028, 1053) and Rescale Slope (0028, 1053). For VOI LUT, these are Window Center (0028, 1050) and Window Width (0028, 1051). The standard also allows the usage of non-linear LUTs. These LUTs are represented as an array of values that map source image intensities to the output range.

If all of these values are found in the file, they are all used to build the 16x8 LUT. If Rescale values are not found, default values (Intercept = 0.0, Slope=1.0) are substituted. If VOI LUT values are not found, the image is scanned for min and max pixel intensities, and the LUT is built to display the min intensity as black and max intensity as white. The values between min and max are linearly scaled between black and white.

You can adjust the values in the 16x8 LUT using MED_display_...() functions.

Grayscale LUTs can be attached to a HIGEAR or to a Display Group. In the latter case, if you are using multiple Display Groups corresponding to the same HIGEAR, they can have different LUTs, allowing to display the same image with different contrast settings simultaneously, in different windows. See Medical Component Grayscale Look Up Tables section below for more details.

NOTE: Grayscale LUTs (16x8, 8x8) only work with grayscale images. They do not work with bitonal, indexed (paletted) or color images.

Pixel Padding Value

DICOM images sometimes contain a Data Element called "Pixel Padding Value" (PPV). The PPV is used mostly to fill in the corners of round images. DICOM provides a Tag for PPV which is (0028,0120). This Data Element stores a 16-bit grayscale value that is to be treated as the Pixel Padding Value. Any pixels in the image that have this value are not to be treated as meaningful objects - but as background color.

When the ImageGear Medical loads a DICOM image that contains a PPV the value is captured and stored in the HDS, which is attached to the new image. In fact, 3 values are stored to the HDS: the PPV from the PPV Data Element, a flag indicating that a PPV was found in the file when it was loaded, and an 8-bit grayscale value used to display pixels with this value.

Use MED_DCM_DS_PixPadVal_get () and MED_DCM_DS_PixPadVal_set () functions to get/set the Pixel Padding Value that is to be used while displaying a 16-bit grayscale image.

Pseudocoloring Medical images

Medical Display API contains methods for creating color LUTs that can be used to pseudocolor grayscale images.

MED_display_color_create ()
Chooses a pre-defined ImageGear pseudo color scheme and creates 3 LUTs for the RGB components that are ready for use with display. You can call MED_display_color_set () to associate these RGB LUTs with an image.
MED_display_color_limits ()
Displays over and under-saturated areas with pseudo color of your choice.
MED_display_color_set ()
Associates 3 LUTs with an image. Can be used to apply pseudo color to an image. You can set to your own LUTs, to the LUTs created by MED_display_color_create (), or set to NULL to use linear 0-255 grayscale LUTs.

Medical Component Grayscale Look Up Tables

The ImageGear Medical component provides a set of functions that allow you to create grayscale look up tables according to DICOM display attributes, such as VOI LUT, Modality LUT, Presentation LUT, etc.

Use the MED_display_grayscale_LUT_build () function to build a grayscale LUT from DICOM display settings. This function supports both linear and non-linear Modality and VOI LUTs, as well as presentation state related LUTs.

Once you have built the LUT, you can copy it to either the image, or to the image display settings, by using IG_image_grayscale_LUT_update_from () or IG_dspl_grayscale_LUT_update_from ().

IG_image_grayscale_LUT_... API internally uses the same LUT as the one that can be set by IG_display_option_get/set functions.

When ImageGear loads a grayscale DICOM image, it builds a grayscale LUT and attaches it to the image. This LUT can be obtained with the IG_image_grayscale_LUT_copy_get () function.

Example:

AT_MED_DCM_DISPLAY_SETTINGS DICOMDisplaySettings;
HIGLUT GrayLUT = (HIGLUT)NULL;
memset(&DICOMDisplaySettings, 0, sizeof(DICOMDisplaySettings));
if (MED_DCM_DS_LUT_exists(g_hIGear, g_hIGearPresState,
DCM_TAG_ModalityLUTSequence))
{
    MED_DCM_DS_LUT_copy_get(g_hIGear, g_hIGearPresState,
DCM_TAG_ModalityLUTSequence,
&DICOMDisplaySettings.ModalityLUT);
}
else
{
    DICOMDisplaySettings.ModalityRescale.Slope = 1.0;
    DICOMDisplaySettings.ModalityRescale.Intercept = 0.0;
}
DICOMDisplaySettings.VOIWindow.Center = 1024;
DICOMDisplaySettings.VOIWindow.Width = 2048;
DICOMDisplaySettings.Gamma = 1.0;
IG_LUT_create(12,		/* Input depth of images to use this LUT for.
*/
    FALSE,		/* Apply to unsigned images. */
    8,		/* Display bit depth to use this LUT for. 8-bits is
common for most PC monitors. */
    FALSE,		/* Apply to unsigned displays. */
    &GrayLUT);
/* Build a grayscale LUT based on display settings */
MED_display_grayscale_LUT_build(&DICOMDisplaySettings,
GrayLUT);
/* Copy LUT to the image. */
IG_image_grayscale_LUT_update_from(g_hIGear, GrayLUT);
IG_LUT_destroy(GrayLUT);
See Also:

Working with Grayscale Look Up Tables

Grayscale Look Up Tables


Image Processing of 16-bit Images

Most of the baseline ImageGear processing functions support 9..16 bit images.

Medical Component presents a set of methods that were designed specifically for 9..16 bit and Medical images.

The Medical Image Processing API is described below

MED_IP_high_bit_transform()
Gives the high bit data element a new value and transforms the image accordingly.
MED_IP_histo_clear(),
Clears the histogram created by MED_IP_histo_tabulate()
MED_IP_histo_tabulate(),
Tabulates a histogram for a specified region of an image (or the whole image), and allows you to set the width of and number of bins that are used. This method also indicates whether the image is signed or not.
MED_IP_min_max(),
Gets the minimum and maximum pixel values from a specified region of an image (or the whole image), and also indicates whether the image is signed or not.
MED_IP_normalize(),
Converts a signed image to an unsigned image. Takes an argument for a minimum pixel value, converts the lowest pixel value in the image to the new minimum, and maps all the rest of the pixels in the image such that the original contrast is maintained.
MED_IP_promote_to_16_gray()
Promotes an 8g or 8i image to a 16-bit grayscale image and gives you the possibility to select the position of the high bit.
MED_IP_reduce_depth_with_downshift(),
Reduces a 9-16-bit image to an 8-bit image using downshifting, that allows you to choose which 8 bits to use for the new image.
MED_IP_reduce_depth_with_LUT(),
Reduces a 9-16-bit image to an 8-bit image using your own LUT or the current display16x8 LUT.
MED_IP_swap_bytes(),
Corrects a poorly constructed image in which the bytes of each 16-bit pixel are in the wrong order.
MED_IP_contrast(),
Reduces a 9-16-bit image to an 8-bit image using Rescale Slope, Intercept, Window Center, Width and Gamma. You would normally use Rescale and Window settings from the Data Set, and your own setting for Gamma.
MED_IP_contrast_auto(),
Same as MED_IP_contrast() except that it automatically derives Window Level and Window Center values for you by scanning the image for the min/max pixel values.

Critical Data Elements

In this manual, we use the term "Critical Data Elements" for those DEs that are used to help load a DICOM image correctly. It's important to note that when certain IP methods are called, the toolkit alters the Data Set. See Critical Data Elements topic in the Working With DICOM Data Structures section for more detail.


Working With DICOM Data Structures

When a DICOM image is loaded into ImageGear, it is loaded into a DIB just like any other supported image. In addition to the actual image, the following DICOM-specific data structures are also loaded: File Meta Information Header (if present) and the Data Set. This section explains how to read and/or manipulate the data in the Data Set or File Meta Information Header, or how to create your own Data Set or File Meta Information Header.

Getting and Setting Data Set and Part10 Header Data

With the exception of the first function listed below, these functions can be used for getting or setting various parts of the Part 10 Header data. These functions are useful when you are creating a new DICOM file.

The first function listed below simply returns some information about the Data Set attached to the HIGEAR. This returns the number of Data Elements in the Data Set.

The second function warrants a bit of explanation. When a DICOM image is loaded into ImageGear, the original Transfer Syntax is stored in the HIGEAR. This value is called the Original Transfer Syntax and cannot be changed. You can to read this information using MED_DCM_DS_orig_TS_get (). Even though you can alter the Transfer Syntax Data Element in the Part 10 Header template, the Transfer Syntax of the original image file is kept in case you ever need to know what it was. It does not affect the saving of a DICOM file. To set the Transfer Syntax for an image that you are saving use either the Image Control setting or fill in the TS parameter of MED_DCM_save_DICOM ().

MED_DCM_DS_info_get ()
Returns the number of DEs in the Data Set
MED_DCM_DS_orig_TS_get ()
Returns the Transfer Syntax used to create the image. It is returned as a MED_DCM_TS_ constant.
MED_DCM_DS_part10_get ()
Returns the data from a Part 10 item. You specify the item you would like to read. You must supply the item as DCM_PART10_ITEM_ constant.
MED_DCM_DS_part10_set ()
Sets the data of an item from the Part 10 meta-info header. You specify which item and supply it with new data to be stored to that item. You must supply a DCM_PART10_ITEM_ constant.
MED_DCM_DS_preamble_get ()
Gets the Preamble from the Part 10 header. Your receiving buffer must be at least 128 bytes. You could also use MED_DCM_DS_part10_set()with the appropriate constant to get this value.
MED_DCM_DS_preamble_set ()
Sets the Preamble of the Part 10 header. You must supply it with the address of the Preamble and the length of the data you are saving to it. You could also use MED_DCM_DS_part10_get()with the appropriate constant to get this value.

Inserting a New Data Element

ImageGear Medical allows you to insert any number of Data Elements to an existing Data Set, or to a new Data Set that you have created by calling MED_DCM_DS_create(). (See the section "Creating a Data Set".)

DICOM Data Sets are sorted numerically by Tag number. Therefore, the Current Data Element does not affect the index position where your new Data Element is inserted. ImageGear takes your Tag number and automatically sorts the new DE into the correct position in the array. The Current Data Element does, however, determine the level at which the new DE is stored. For example, if the Current Data Element is in level 0 and has a Tag value of (0028, 0010) and your new DE has a Tag value of (0028, 0015), the new DE will be inserted into level 0 and positioned somewhere below the Current DE so that its unique Element Number fits numerically in ascending order.

NOTE: If a DE with specified Tag number already exists in the Data Set, it will be overwritten.
NOTE: If there are no DEs in the Data Set, the level for the new DE will be 0 or the "top level"

You have complete flexibility in what kind of DEs you can add to the Data Set. For each new DE, you have to supply ImageGear with a Tag structure, a VR, and the data. You can add it to any Group, to any position, with any VR, and with any data that you desire.

An example of using MED_DCM_DS_DE_insert ():

HIGEAR hIGear;
AT_DCM_TAG tag = 0x00111111;
AT_DCM_VR vr = MED_DCM_VR_CS;
char data[256] = "Data for test element";
DWORD dwSizeOfData = strlen(data);
MED_DCM_DS_DE_insert(hIGear, tag, vr, data, dwSizeOfData);

This function requires you to supply the following values: a Tag, a VR, a Data Field, and the size of the data for the Data Field. Below are brief descriptions of what you would need to know in order to set these arguments.

Setting the Tag Value

All standard Tag values for a DICOM file are assigned constants in DataDict.h. You can also add your own user-defined Tag using MED_DCM_util_tag_info_add ().

Setting the VR

The DICOM specification assigns specific VRs for each defined public Tag. In other words, for a particular Tag, you must always use the specified VR. There are a few rare exceptions to this rule, and it is for this reason that you should tell MED_DCM_DS_DE_insert () what VR the data has.

If you don't know the VR for a particular Tag that you are adding, you can find out easily by calling the function MED_DCM_util_tag_info_get (), which returns you its VR as a constant.

Setting the Data for a VR of CS

There are no constants in ImageGear defined for those Data Elements which have a VR of CS. Refer to Part 3 of the DICOM specification for the valid Code Strings which you can enter for data of type CS.

Here is a sample call to insert a Data Element with a Tag of DCM_TAG_PhotometricInterpretation, which has a VR of CS (Code String). You must use one of the defined values from Part 3 of the DICOM specification. The allowed values are: "MONOCHROME1", "MONOCHROME2", "PALETTE COLOR", "RGB", "HSV", "ARGB", "CMYK", "YBR_FULL", "YBR_FULL_422", and "YBR_PARTIAL_422".

MED_DCM_DS_DE_insert(hIGear, DCM_TAG_PhotometricInterpretation,
MED_DCM_VR_CS,  "MONOCHROME2", 11);

Setting the Data Field

What kind of data can be stored to the Data Field depends on the Tag type, the VR, the restriction flags and the Value Multiplicity (VM) defined for the Tag. It is very helpful to call MED_DCM_util_VR_info_mode () or MED_DCM_util_VR_info_string () so that you can find out what kind of restrictions are placed on the kind of data that you would like to enter. Some types of Data Fields are tricky to work with. VRs of Person Name and Code String place a number of restrictions on what can go into the Data Field, and how it is to be formatted. For these VR types, you must consult Part 5 of the DICOM specification.

The lpData parameter is a binary buffer, which can contain a character string, a BYTE or WORD array, or one or several of numbers, such as Integers or Floats. Below there is an example how to set a value of VR=FD (double):

DOUBLE dblRefPixelValueX = 1.234;
MED_DCM_DS_DE_insert(hIGear,
DCM_TAG_ReferencePixelPhysicalValueX, MED_DCM_VR_FD,
&dblRefPixelValueX, sizeof(DOUBLE));

Setting the Length of a Data Field

Because some VRs allow a range of values, the length of all Data Fields cannot be assumed. For this reason, you must supply ImageGear with the length of your data.

Inserting a Sequence of Data Elements

Use the following steps to create and fill a sequence (SQ) of Data Elements:

  1. Insert the Data Element of VR = SQ. This positions you one level lower in the DataSet hierarchy. At this level you can only add items to the sequence, not the Data Elements.
  2. Insert the DCM_TAG_ItemItem Data Element to denote the beginning of a new item in the sequence. This positions you one level lower in the DataSet hierarchy. Now you can add Data Elements to the embedded Data Set.
  3. Insert the data elements you would like to insert to this item.
  4. Insert the DCM_TAG_ItemDeliminationItem Data Element to denote end of the item. This positions you one level higher. Repeat steps 2-4 for every item you would like to add.
  5. Insert the DCM_TAG_SequenceDeliminationItem Data Element to denote the end of the sequence. This moves you one level higher - to the same level where you added the SQ Data Element.

Examples on creating a Data Element Sequence are below. Note that it is completely valid to add same Data Elements to different Items within a Sequence.

AT_DCM_TAG  tag;
char        data_str[64];
tag = DCM_TAG_ReferencedStudySequence;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_SQ, NULL, 0);
tag = DCM_TAG_ItemItem;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_xx, NULL, 0);
tag = DCM_TAG_ReferencedSOPClassUID;
strcpy( data_str, "1.23.456.7.8.90.1234567890.2");
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_UI, data_str,
strlen(data_str));
tag = DCM_TAG_ReferencedSOPInstanceUID;
strcpy( data_str, "1.23.456.7.8.90.1234567890.2.1");
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_UI, data_str,
strlen(data_str));
tag = DCM_TAG_ItemDelimitationItem;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_xx, NULL, 0);
tag = DCM_TAG_ItemItem;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_xx, NULL, 0);
tag = DCM_TAG_ReferencedSOPClassUID;
strcpy( data_str, "1.23.456.7.8.90.1234567890.3");
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_UI, data_str,
strlen(data_str));
tag = DCM_TAG_ReferencedSOPInstanceUID;
strcpy( data_str, "1.23.456.7.8.90.1234567890.3.1");
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_UI, data_str,
strlen(data_str));
tag = DCM_TAG_ItemDelimitationItem;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_xx, NULL, 0);
tag = DCM_TAG_SequenceDelimitationItem;
MED_DCM_DS_DE_insert( hIGear, tag, MED_DCM_VR_xx, NULL, 0);

Deleting a Data Element

Data Elements can be deleted by calling MED_DCM_DS_curr_remove (). This function removes the DE designated by the Current Data Element. Therefore, you can use one of the MED_DCM_DS_move_...() functions to position the Current Data Element to the DE you want to remove.

TIP: If you've used MED_DCM_DS_move_find() or MED_DCM_DS_move_find_first() to position the Current Data Element, be sure to check the value of the Boolean argument to see whether you successfully found the Tag or Group Number that you were looking for. Otherwise, you might unintentionally delete the wrong DE.

Some calls to MED_DCM_DS_curr_remove ()result in deletion of more than one Data Element:

  • If you are going to delete a DE with a VR of SQ, all the items and consequently DEs below it will be deleted also.
  • If you are going to delete a DE of type Item (FFFE, EOOO), all DEs below it will also be deleted.

The following types of DEs may not be deleted:

  • Sequence Delimitation Item (SQD) - (FFFE, EODD)
  • Item Delimitation Item (ID) - (FFFE, EOOD)

Trying to delete DEs of these types will have no affect on the Data Set. These type of DEs will be automatically deleted by ImageGear when their accompanying set of DEs are deleted.

Getting and Setting Data of the Current Data Element

Notice that all functions in this group include "curr" as part of their names. Below is a description of these functions..

MED_DCM_DS_curr_data_get ()
Returns the data and size of data from the CDE. The data is returned in its native format. Use MED_DCM_DS_curr_info_get () to get the VR in order to know how to handle the data.
MED_DCM_DS_curr_data_get_string ()
Same as MED_DCM_DS_curr_data_get() except that the data is always returned as a string.
MED_DCM_DS_curr_data_set ()
Sets/overwrites the Value Field (data) of the CDE. Check the VR required. You cannot change the VR of an existing DE.
MED_DCM_DS_curr_index_get ()
Returns the index of the CDE. Lets you know where you are in the Data Set.
MED_DCM_DS_curr_info_get ()
Returns the following pieces of information about the CDE: Tag, VR, VL, Item Count. This is a very important method. Use it as a precautionary call before modifying info in the CDE or inserting/deleting.

Creating a Data Set

If you have a HIGEAR image to which you would like to attach a Data Set, call MED_DCM_DS_create (). This file might have been loaded from a non-DICOM format or may be a DICOM file in which you've destroyed the Data Set (see the section above).

This function creates an empty Data Set and attaches it to the ImageGear's image. The function creates a Data Set structure (outlined above) and fills it with a few Data Elements whose values can be derived from the image. This function also requires you to supply a Transfer Syntax that is saved in the Part 10 Header template as the original Transfer Syntax (as if it was loaded from a DICOM file). If you then save the image and specify a different Transfer Syntax, you overwrite the TS value specified at the time of Data Set creation.

Deleting a Data Set

If you have loaded a DICOM image file and do not need to keep the Data Set around you can free up the memory used to store all the Data Elements by calling MED_DCM_DS_destroy (). Once this function is called the remaining image is no different than any other ImageGear image that was created from any other non-DICOM format. The removed Data Set is discarded and cannot be recovered.

Creating a Part 10 Header

When a DICOM image is loaded with the ImageGear Medical, a Part 10 Header Template is initialized automatically. If you save the image as a Part 10-compliant image (which is the default option), the values from this template are used to fill the header saved with the file.

For those wishing to modify or read the values stored in the Part 10 Header Template, the component supplies 11 constants. All except the last one correlate directly to the fields found in a Part 10 Header. The last constant can be used by ImageGear to store the length of the Private Info field, and is for informational purposes.

Below is the list of Part 10 constants defined in DCM.h. Each one is followed by its size in bytes. A check appears next to each field that is considered "Mandatory" by the specification. ("Mandatory" is one of three possible "Types" for a DICOM DE. The other Types are "Optional", and "Mandatory Depending on some Condition".)

Mandatory
MD Component Constant
Size of Data Field
Yes
DCM_PART10_ITEM_PREAMBLE
128 bytes
Yes
DCM_PART10_ITEM_VERSION
2 bytes
Yes
DCM_PART10_ITEM_MSSOPCLASSUID
Max 64 bytes
Yes
DCM_PART10_ITEM_MSSOPINSTUID
Max 64 bytes
Yes
DCM_PART10_ITEM_TRANSSYNTAXUID
Max 64 bytes
Yes
DCM_PART10_ITEM_IMPLCLASSUID
Max 64 bytes
DCM_PART10_ITEM_IMPLVERNAME
Max 16 bytes
DCM_PART10_ITEM_SRCAETILE
Max 16 bytes
DCM_PART10_ITEM_PRIVINFOCRUID
Max 64 bytes
DCM_PART10_ITEM_PRIVINFO
any length
DCM_PART10_ITEM_PRIVINFO_SIZE
DWORD - length of Priv Info - read only

Please note the following about the above constants:

  • You can set DCM_PART10_ITEM_PREAMBLE to anything you want as long as it doesn't exceed 128 bytes
  • DCM_PART10_ITEM_VERSION is set by the toolkit to a default value of 1. You should not change this.
  • DCM_PART10_ITEM_TRANSSYNTAXUID - we set the value of this DE when the image is loaded. You can read this value; you can even set this value. But when the image is saved your setting are ignored.

If you enter data in DCM_PART10_ITEM_PRIVINFO, it is stored with the new Part 10 Header. Also, ImageGear calculates its size and saves this information internally. This read-only size information is not made part of the template but is kept in case you need to know how much memory to allocate when getting the information from DCM_PART10_ITEM_PRIVINFO. DCM_PART10_ITEM_PRIVINFO_SIZE isn't stored to the new Part 10 header.

Here is an example of a Part 10 field being populated:

char szPreamble[] = "This DICOM File is MINE!";
DWORD size_of_data;
size_of_data = sizeof(&szPreamble[0]);
MED_DCM_DS_part10_set(hIGear, DCM_PART10_ITEM_PREAMBLE,
&szPreamble[0], &size_of_data);

Updating DICOM DataSet without updating Pixel Data

There are cases when an application needs to update DataSet of a DICOM file, while leaving PixelData unchanged. For example, if the image is compressed using a Lossy compression scheme, this will avoid degradation of image quality.

Use MED_DCM_DS_update_file() function to update DataSet in a DICOM file, without changing its pixel data.

Critical Data Elements

In this manual, we use the term "Critical Data Elements" for those DEs that are used to help load a DICOM image correctly. It's important to note that when certain IP methods are called, the toolkit alters the Data Set. For example, when an aspect of the image has been altered (for instance, by image processing) so, that the Critical DEs no longer correctly describe the image, the Data Set have to be altered. When the image is actually saved, ImageGear also analyzes the DIB and set its own values for the Critical Data Elements of the file being saved. The original values are ignored.

The Critical Data Elements are:

(0028,0010)
Rows
(0028,0011)
Columns
(0028,0100)
Bits Allocated
(0028,0101)
Bits Stored
(0028,0102)
High Bit
(0028,0004)
Photometric Interpretation
(0028,0103)
Pixel Representation
(0028,0002)
Samples per pixel
(0028,0006)
Planar Configuration
(7FE0,0010)
Pixel Data

NOTE: PixelData DE does not contain any actual data, it is always empty. The actual pixel data is stored in ImageGear's DIB, to which the DataSet is attached. Value Representation and Value Length of the Pixel Data tag correspond to VR and VL of PixelData tag, if the DIB is saved to an uncompressed image.


Working with DICOM Data Dictionary

The MD component encapsulates the DICOM Data Dictionary (Part 6) in a static and internal table, which the component uses to look up Tags as they are being decoded. This table is generated from the component header file DataDict.h. It can be used also by your application to provide the DICOM given name or other information about a given Tag. To retrieve this information use the MED_DCM_util_tag_info_get () function.

The Data Dictionary is also used to check the VR of Data Elements as they are being decoded. If a file is Explicit VR then as each Data Element is read, the VR found in the file is matched against the VR in the Data Dictionary. If it is determined that the VR is not appropriate for the Tag type, an error condition may occur.

You can add your own user-defined Tags to the Data Dictionary, or add new Tags that have been added to the DICOM specification so that you keep your application current. The Tags that you add, whether they are user-defined, or new to the DICOM specification, will be stored in a separate table in memory, rather than added to DataDict.h file. DataDict.h is reserved for public DICOM Tags. However, when your application is running, ImageGear Medical will treat the two tables as one, and will be able to process any valid Tag number that you reference. To add a Tag use MED_DCM_util_tag_info_get ().

Since the internal Data Dictionary tables are statically defined, any Tags you wish to add should be added to your initialization code since the table need to be updated each time the toolkit is started up.

The internal Data Dictionary holds several pieces of information for each Tag: it holds the VR, the VM, the version in which the Tag is last used, and the character string name of the Tag as it appears in the DICOM Standard.

The version information is stored because there are many Tags in the DICOM 3 Standard Data Dictionary that are now obsolete or "Retired" as DICOM calls them. If a Tag has been Retired in DICOM 3, then the version is stored as 2. If the Tag has not been retired then it is stored as 3 (for DICOM version 3). Retired Tags also include the string "(RET)" at the end of their name string.


Working with Overlays

Use MED_overlay_apply() function to load graphic overlays from DICOM DataSet to ART annotations. Use MED_overlay_extract() function to save ART annotations into DICOM DataSet as overlay data.


Working with Presentation State Objects

Presentation State (PS) objects serve for the following purposes: consistent display of images on various devices and media, storage of specific settings for display (contrast transformations, geometric transformations), and storage of annotations. They also allow for special display of multiframe images.

Presentation State object files do not include actual images, but reference one or more images.

Presentation State object files, in addition to LUTs, display parameters and annotations, contain other tags, such as Patient/Study/Series info, Referenced Image UIDs, etc. ImageGear provides read/write access to these tags.

Consistent display of images

DICOM standard introduces the Standardized Display System. A Standardized Display System may be a printer, a monitor or some other display device which has been calibrated according to the Grayscale Standard Display Function (GSDF). The main feature of such display system is that throughout its display range, equal differences in digital input values correspond to visually equal differences in luminosity. Two Standardized Display Systems will always show the same detail in an image, even if their physical characteristics are different.

The values that can be used as input to a Standardized Display System are called "Presentation Values" ("P-Values"). To map image pixel intensities into P-Values, Presentation Look Up Table ("P-LUT") is used. It is applied after Modality and VOI LUTs.

Presentation LUT is stored in a Presentation State DataSet.

If a display device is not physically calibrated to comply with GSDF, but its characteristic curve (a table that lists luminosities for each digital input value) is known, it can be calibrated at the software level. In that case, P-Values shall be used as input to a GSDF LUT, which will map them to the device's input values according to GSDF. Thus, a non-standardized device together with its GSDF LUT can be considered as Standardized Display System.

ImageGear Medical component allows to build a GSDF LUT from a device's Characteristic Curve.

ImageGear uses all available LUTs (Modality LUT, VOI LUT, Presentation LUT and GSDF LUT), to build the general 16x8 or 8x8 LUT that maps image pixel values into display input values.

Grayscale contrast transformations

Presentation State DataSet may include VOI and Modality LUTs. Their usage is the same as in normal DICOM images. If either of these LUTs is present, it overrides the LUT found in the image.

Geometric transformations

Presentation State DataSet may include Rectangle of Interest, scale mode (True size, Scale to Fit, Magnify), and orientation (Rotate, Flip).

Annotations

Annotation objects include: Text box, Point, Polyline, Spline, Circle, Ellipse. Graphical objects can be filled or not filled. Annotations can be grouped into layers.

ImageGear Medical component uses ART marks to represent DICOM annotation objects. When a Presentation State DataSet is applied to an image, ImageGear creates ART marks for each of the annotation objects. These marks can then be edited with the ART API methods.

Working with Presentation State Objects

You can load Presentation State files in the same way as you load normal DICOM images. However, since PS files do not contain an image, HIGEAR will be set to an empty image (DIB.biCompression |= IG_BI_EMPTY). Data Set of such image is accessible through Medical API. Such images can also be saved in the same way as normal DICOM images.

A HIGEAR containing a Presentation State DataSet can be "applied" to another HIGEAR that contains an image. This operation applies display and annotation settings from Presentation state onto the target image. In the opposite way, display settings and annotations can be exported from an image into another HIGEAR.

When you apply Presentation State to an image, ImageGear updates its 16x8 or 8x8 LUT using the Presentation LUT. However, it does not store Presentation LUT with that image. If you would like to work with Presentation LUT, you should allocate memory for it in your application. Pass Presentation LUT as a parameter to medical display functions. You can also save Presentation LUT to a Presentation State data set.

If a Characteristic Curve is available for a display, you can build a GSDF LUT from it, and use it in calls to medical Presentation State and Display functions. Otherwise, pass a NULL to GSDF LUT parameter.


Waveform Image Support

ImageGear supports both DICOM raster and vector (waveform) images. ImageGear loads waveform images in vector form. You can use Vector component API to modify waveform images that have been loaded to ImageGear. Use any image loading functions to load DICOM waveform images.

ImageGear reads and displays waveform data (graphs), as well as axes and some annotations.

As of this writing, ImageGear creates the following annotations for waveform images:

  • X axis with second marks, according to SamplingFrequency tag value.
  • X axis for every image, if it is visible and does not intersect with other images
  • Y axis for all images.
  • Minimum and maximum Y values for each graph


Using ImageGear Multimedia Component

The IG_mult_...() functions provide high level support for accessing the contents of multimedia files. These functions support two types of data: video (images associated with video or animation frames) and audio.

The IG_mult_open_...() functions are used to open a multimedia file and obtain a handle of ImageGear type HIGMULT. The file remains open and the handle remains valid until IG_mult_close () is used to close it. You must call IG_mult_close() when you're finished work.

You can determine the number of video frames in the file and the file's duration in milliseconds by calling IG_mult_duration_get (). If you're interested in whether or not the file contains video and/or audio data, you can call the functions IG_mult_has_video () and IG_mult_has_audio () to find out.

Video data is accessed on frame-by-frame basis. It is recommended to use the IG_mult_current_frame_...() functions, which keep track of the current frame you're accessing within the file. You can go back to the beginning of the file with IG_mult_current_frame_reset () and advance to the next frame with IG_mult_current_frame_advance (). You can seek to a specific time using IG_mult_current_frame_seek_time (), and seek to a specific frame number with IG_mult_current_frame_seek (). To determine if you've run off the end of the movie, use IG_mult_current_frame_is_valid ().

There is a duration and an image associated with each frame. The duration specifies how long the frame should be displayed at a normal playback speed. To retrieve a frame's duration, use IG_mult_current_frame_duration_get (), or IG_mult_frame_duration_get () if you want to specify the frame number explicitly. A frame's duration is given in 100ns units. You can convert to milliseconds by dividing by 10000, but be aware that some common frame rates such as 29.97 frames per second (used in NTSC television) require the higher precision for correct playback speed. Also, depending on your application, you should not assume that all frames in a file have the same duration. To support a variable frame rate, as is common in animations but also possible in video clips, you must retrieve the duration of each individual frame.

To retrieve a frame's image, use IG_mult_current_frame_image_get (), or IG_mult_frame_image_get () if you want to specify the frame number explicitly. This will give you a HIGEAR image handle that can be used to access the image with all of ImageGear's functions that work on a HIGEAR. However, you should not attempt to modify the image or free it with IG_image_delete (). If you need to modify the image, use IG_image_duplicate () and work with the duplicate image. Remember to free the duplicate image when you're finished with it.

Audio data is accessed as blocks of uncompressed PCM audio samples. An audio sample represents the amplitude of an audio waveform at a particular point in time. Before you can retrieve audio data, you should find out what its format is by calling IG_mult_audio_format_get (). This will tell you the sample rate (number of samples per second), bits per sample, and number of channels. If the audio has multiple channels (i.e. stereo), the samples for each channel are stored in alternating order beginning with the left channel.

There is also a function to set the audio format: IG_mult_audio_format_set (). You can use this to request that ImageGear convert the file's audio format to your specified format as you retrieve audio data. Conversion may not be possible, so be sure to check the result when calling this function.

To retrieve audio data, use IG_mult_audio_get (). Provide a pointer to a buffer where it will copy the audio data to, as well as a pointer to a value containing the number of bytes of audio data to retrieve. If the call is successful, your buffer will contain audio data and the value you passed will contain the number of bytes of audio data that were copied. This number will be less than the number you requested if you requested more data than was available.

You can calculate the number of bytes of audio data to retrieve by using the audio format. Divide the number of bits per sample by 8 to get the number of bytes per sample. Then multiply by the number of channels. This gives the number of bytes needed to represent the audio at a single point in time. The number of bytes you request must be a multiple of this number. You can then multiply by the sample rate to expand out into time. For example, to calculate the number of bytes per second of audio:

BytesPerSec = ((nBitsPerSample / 8) * nChannels) *
nSamplesPerSec

Finally, there are some generalized functions for getting and setting parameters. These are the functions with "info" in the name. They can offer access to parameters which may be relevant to a whole file or an individual frame. These parameters may also be relevant to a particular file format or all file formats. These parameters are defined in accucnst.h. For more information about format-specific parameters, see the documentation for the formats supported by the IG_mult_...() functions.


Multimedia Format: Animated GIF

An animated GIF file contains a series of input images and instructions on how to combine the images to form a series of output images. The IG_mult_...() functions provide access to the final output frames from this process. Each frame will have the same dimensions and bit depth. The bit depth can be 1, 4, or 8bpp. Palettes and durations of frames may vary. Animated GIF files do not contain audio data.

To access animated GIF files, you must have the LZW component attached.

There are currently two parameters specific to animated GIF that can be set using IG_mult_info_set ():

  • IG_MULT_INFO_GIF_MIN_DELAY - default = 100ms
  • IG_MULT_INFO_GIF_MIN_DELAY_THRESHOLD - default = 10ms

These parameters exist because some animated GIF files have frames whose delays are specified as 0. Also, some frames have delays specified as 10ms or more when they are meant to be displayed for much longer. The default behavior of ImageGear is to enforce a minimum delay of 100ms for frames having delays specified as 10ms or less. This only affects the frame durations retrieved from IG_mult_current_frame_duration_get () and IG_mult_frame_duration_get ().


Multimedia Format: DirectShow

DirectShow is a Microsoft framework and API for working with multimedia data. It supports a variety of formats. You can use the IG_mult_...() functions to access still images, animations, movies with video and audio, and audio-only files loaded and exported on the fly from DirectShow. Each video frame will have the same dimensions and bit depth. The bit depth will be 24bpp.

To open files using DirectShow, you must have the MULT component attached. Also, you must have DirectX 8.0 or later installed. DirectX 8.0 or later comes standard as part of modern versions of Windows such as Windows 2000 SP4, Windows XP and Windows Vista.

Support for DirectShow in ImageGear is primarily intended for AVI and MPEG files, but other formats may also be accessible depending on the codecs installed on the system. If a file is compressed with a codec not installed on the system, ImageGear will not be able to open it.


Multimedia Format: QuickTime

QuickTime is Apple's multimedia platform and supports a variety of formats. You can use the IG_mult_...() functions to access still images, animations, movies with video and audio, and audio-only files loaded and exported on the fly from QuickTime. Each video frame will have the same dimensions and bit depth. The bit depth will be 24bpp. Although QuickTime movies almost always use a fixed frame rate, it is possible that the frame rate could be variable, so durations of frames may vary.

To open files using QuickTime, you must have the QT component attached.

To retrieve image data, the QuickTime Player (version 6 or higher) must be installed. To retrieve audio data, the QuickTime Player and QuickTime Authoring component must be installed. This software can be downloaded for free from Apple's web site by end users, or you can license it for distribution from Apple.

Support for QuickTime in ImageGear is primarily intended for QuickTime movies (MOV files) but other formats have been read successfully, such as AVI (uncompressed), MP3, WAV, and JPG.

ADDITIONAL NOTES:

  • Reading MPEG files (.mpg, .mpeg) using QuickTime and ImageGear is not supported.
  • QuickTime movies may contain multiple video tracks. Only the first video track is made available through ImageGear. The same applies to audio tracks.
  • QuickTime may prompt the user to install necessary software when opening some types of files. In such cases, the file may be opened successfully but images retrieved may appear as solid white. For example, opening a CMYK JPEG image requires the "QuickTime Image" component. If the user permits QuickTime to download and install the necessary software, the image can be retrieved successfully after the file has been closed and re-opened.
  • If a QuickTime movie uses the QDesign 2 audio codec, retrieving its audio in blocks may result in noticeable discontinuities between blocks.
  • The final 0.5 seconds or less of audio data from QuickTime may be faded or not available for some files.


ImageGear DirectShow Source Filter

DirectShow is Microsoft's multimedia platform. It provides a means of building and running directed graphs of filters. There are several types of filters, such as source, transform, and renderer, and they connect through output and input pins. The purpose of a filter graph in DirectShow is to facilitate the flow of media samples from source to sink.

The purpose of the ImageGear DirectShow source filter is to provide source data for other filters in a DirectShow filter graph. It can load still image formats that ImageGear supports, as well as animated GIF files and QuickTime movies.

The source filter has output pins for video and audio. Video samples can be provided as RGB24 or RGB32. Audio samples are provided as uncompressed PCM audio in the original format of the audio. If a file is loaded by the filter but does not contain audio, the audio pin cannot be connected. The same applies to video.

The filter must be licensed just like an application using ImageGear. A custom COM interface called IIGSourceControl provides wrapper methods to let you perform the necessary licensing API calls, as well as allowing for component attachment. If you do not perform licensing (for example, when loading the filter in GraphEdit), the filter assumes development licensing and attempts to load the LZW and QT components. If you do perform licensing, it's up to you to specify the components to attach.

Testing with GraphEdit

GraphEdit is a tool that Microsoft provides as part of the DirectShow SDK. It lets you visually build and run a filter graph, inserting and connecting filters as you wish. You can use GraphEdit to experiment with the source filter before writing any code. If you need to obtain the DirectShow SDK, visit:

http://msdn.microsoft.com/directx/

To use the ImageGear DirectShow Source Filter with GraphEdit, follow these steps:

  1. Go to the Graph menu and choose Insert Filters.
  2. Expand the DirectShow Filters category.
  3. Select "AccuSoft ImageGear Source Filter" and click Insert Filter.
  4. Select a file to use as input for the filter. It can be a still image, or animated GIF, or a file type supported by QuickTime (such as .MOV).
  5. Click Close to close the filter insertion window.
  6. You should see two boxes that say "Out". These are the video and audio output pins of the source filter. Right-click on a pin and choose Render Pin. This will automatically insert and connect the filters needed to view or hear the video/audio. You can only connect pins for which the source file has data. So, for example, you cannot connect the audio pin when loading an animated GIF file.
  7. Click the Play button in the toolbar to run the graph. You should see and/or hear the file you specified.

Other things to try:

  • You can insert filters and form connections manually by dragging from an output pin to an input pin.
  • Right-click on a pin or connection arrow and choose Properties to see its media type(s).
  • Right-click on the source filter and choose Properties. From here, you can click "..." to switch input files, as long as the graph is stopped and no pins are connected.

Using the Source Filter in a DirectShow Application

The source filter is a COM object. You can write applications using it in languages and development environments that support COM and DirectShow. This section describes how to use the source filter from C++, but the steps are similar in other languages. If you're not familiar with DirectShow programming, you had better read the DirectShow SDK documentation in addition to this section. The code here is taken from the ImageGear DSCon sample application, so please refer to it as well.

Creating an Instance of the Source Filter

Before you can do anything with the source filter, you will need to create an instance of it. Be sure to initialize COM with CoInitialize in the same thread before doing this.

HRESULT hr = CoInitialize(NULL);
IBaseFilter *pIGSource = NULL;
hr = CoCreateInstance(CLSID_IGSource, NULL,
CLSCTX_INPROC_SERVER, IID_IBaseFilter, (void **)&pIGSource);

IBaseFilter and IID_IBaseFilter are defined in strmif.h, which comes with the DirectX SDK. CLSID_IGSource is the source filter's CLSID, defined in IGSourceGUID.h. You must include this file in your project. Also, in at least one source file in your project, you must include initguid.h and then IGSourceGUID.h.

Licensing and Component Attachment with the IIGSourceControl Interface

The IIGSourceControl interface is a custom COM interface implemented by the source filter that lets you perform tasks that are not covered by standard filter interfaces, such as licensing and component attachment. Here is sample code that retrieves the interface and uses it to perform licensing and component attachment:

IIGSourceControl *pIGSourceControl = NULL;
hr = pIGSource->QueryInterface(__uuidof(IIGSourceControl),
(void **) &pIGSourceControl);
hr = pIGSourceControl->SC_setSolutionName("Test License");
hr = pIGSourceControl->SC_setSolutionKey(0x473F47EC,
0xDEDCEDC4, 0xAFFBB23E, 0xFBFBDE4A);
hr = pIGSourceControl-
>SC_setOEMLicenseKey("1.0.EtSEqHSHxCPHUVSKAEq3NjYcUK...");
hr = pIGSourceControl->SC_attachComponent("LZW");
hr = pIGSourceControl->SC_attachComponent("QT");

IIGSourceControl is defined in IIGSourceControl.h. Note that if you do not perform licensing, the filter will assume development licensing and attempt to attach the LZW and QT components. If you do perform licensing, it's up to you to attach the components you want the filter to use.

Adding the Source Filter to a Graph

The purpose of the source filter is to provide data to other filters in a graph. Before it can do this, you must add it to a graph. The following code demonstrates how to create a graph (using the Filter Graph Manager object via its IGraphBuilder interface) and add the filter to it:

IGraphBuilder *pGraph = NULL;
hr = CoCreateInstance(CLSID_FilterGraph, NULL,
CLSCTX_INPROC_SERVER, IID_IGraphBuilder, (void **)&pGraph);
hr = pGraph->AddFilter(pIGSource, L"IGSource Filter");

Loading a File into the Source Filter

Before you can connect any of the source filter's output pins to other filters, you need to instruct the filter to load a file. The filter implements the standard DirectShow interface IFileSourceFilter to allow this. The following code demonstrates retrieving this interface and using it to load a file:

IFileSourceFilter *pFileSource = NULL;
hr = pIGSource->QueryInterface(IID_IFileSourceFilter, (void **)
&pFileSource);
hr = pFileSource->Load(wszFilename, NULL);

Note that the Load method of the IFileSourceFilter requires the filename to be a wide character string (Unicode). The second parameter of the Load method should always be NULL.

Querying the Filter's State

The IIGSourceControl interface provides a method called SC_getFilterState to let you retrieve some information about the filter's current state. You can use this as an easy way to find out if the filter can provide video and/or audio data after you've loaded a file:

DWORD dwFilterState = 0;
hr = pIGSourceControl->SC_getFilterState(&dwFilterState);
if (dwFilterState & IGSOURCE_HAS_VIDEO)
{
    // Video data is available
}
if (dwFilterState & IGSOURCE_HAS_AUDIO)
{
    // Audio data is available
}

For optimal performance, you should use this mechanism to avoid attempting to connect an output pin when no data is available for the pin. See the DSCon sample for a complete example.

Rendering Output Pins

The Filter Graph Manager provides a method called Render which attempts to automatically "render" a given output pin. First it will look at filters already added to the graph to see if it can use them to render the pin. It will add additional filters to the graph as needed to connect filters together, and it will add a renderer filter if necessary. You can observe this behavior in GraphEdit by right-clicking on an output pin and choosing Render. Here is sample code to render the video and audio output pins:

IPin *pIGSourcePinVideo = NULL;
hr = GetPin(pIGSource, PINDIR_OUTPUT, &pIGSourcePinVideo, 0);
hr = pGraph->Render(pIGSourcePinVideo);
IPin *pIGSourcePinAudio = NULL;
hr = GetPin(pIGSource, PINDIR_OUTPUT, &pIGSourcePinAudio, 1);
hr = pGraph->Render(pIGSourcePinAudio);

Note that GetPin is a utility function that enumerates pins of a filter and retrieves the requested pin's IPin interface. It's implemented in the file DSUtils.cpp in the DSCon sample. Also, using IGraphBuilder's Render method is the easiest way to connect filters, but there are other ways to do it. For example, IGraphBuilder offers a Connect method that lets you specify output and input pins to connect together. For more information, see the DirectShow SDK documentation.

Running the Graph

Once you've set up a graph and connected its filters together, you can get data flowing by running the graph. The Filter Graph Manager's IMediaControl interface offers a Run method to do this:

IMediaControl *pControl = NULL;
hr = pGraph->QueryInterface(IID_IMediaControl, (void
**)&pControl);
hr = pControl->Run();

For more information about controlling a graph, see the DirectShow SDK documentation.


Using ImageGear PDF Component

This section tells how to use ImageGear PDF component.

  • About the PDF Component
  • How to Attach the PDF Component to Core ImageGear
  • PDF Standards
  • Working with PDF Layers
  • Working with 3D Artwork
  • Distributing PDF and PS Fonts with Your Application
  • PDF Format Filter
  • PDF Format Filter Control Parameters
  • PostScript Filter Control Parameters


About the PDF Component

PostScript Language (PS)

The PostScript Language (PS) is a simple interpretive programming language with powerful graphics capabilities. Its primary application is to describe the appearance of text, graphical shapes, and sampled images on printed or displayed pages, according to the Adobe® imaging model. A program in this language can communicate a description of a document from a composition system to a printing system or control the appearance of text and graphics on a display. The description is high-level and device-independent.

Adobe® Portable Document Format (PDF)

The Adobe® Portable Document Format (PDF) is the native file format of the Adobe® Acrobat® family of products. PDF relies on the same imaging model as the PostScript page description language to describe text and graphics in a device-independent and resolution-independent manner. A document can be converted between PDF and the PostScript language; the two representations produce the same output when printed. To improve performance for interactive viewing, PDF defines a more structured format than that used by most PostScript language programs. PDF also includes objects, such as annotations and hypertext links that are not part of the page itself but are useful for interactive viewing and document interchange. However, PDF lacks the general-purpose programming language framework of the PostScript language.

Using the ImageGear PDF API allows you to load, save, edit and process native PDF and PostScript documents. The ImageGear PDF Component can also perform rasterization of PDF and PostScript documents, converting them to bitmaps. The component also provides you with the ability to extract text from loaded PDF and PostScript documents

ImageGear PDF component provides full multi-page reading and writing support for the entire document as well as specified set of pages. You can detect, read, write, append, insert, replace, swap and delete a specified page in the PDF document.

Content Editing

Content editing provides an API for creating, accessing and editing PDF page content objects. With this API you can work with a page's content as with a list of such objects like images, texts, forms. Retain, modify and save their data and properties.

Document Fonts

Document font support includes:

  • Listing the fonts available in the host system and finding a system font that matches a PDF font
  • Creating a font from the system font and encoding as well as from the specified attributes
  • Changing font's information
  • Editing and embedding a font in the document
  • Both single and multiple bytes fonts are supported

Word Extraction

Text words extraction includes:

  • Extracting words from a PDF document or specified page
  • Enumerating and sorting the words
  • Getting word layouts, styles and characters

PDF Multi-thread Safety

For a multi-threaded application, you must call IG_PDF_initialize () and IG_PDF_terminate () in the thread - not in the calling module.

Note that the access to the same PDF document from different multiple threads is not permitted because the multiple threads cannot share Adobe PDF Library datatypes. PDF document created/opened in the main thread can be only used from the main thread.

Document Metadata

You can get and set PDF document metadata corresponding to a document's Info dictionary.

Native Printing

Native PDF document printing now renders the document content directly to the printer, so it is fast and requires less memory.

NOTE: PDF support is compatible with Adobe® PDF version 1.7 as defined in the Portable Document Format Reference Manual Version 1.7, distributed by Adobe Systems Incorporated. It provides reading capability up to the PDF version 1.7 and writing of the PDF 1.7 documents.
NOTE: PostScript support is compatible with Adobe® PostScript® 3.0 language as defined in the PostScript Format Reference Manual, distributed by Adobe Systems Incorporated. It provides reading capability up to the PostScript 3.0 Language Level 3 and writing of the PostScript 3.0 files with the Language Level 1, 2 and 3. This includes writing of the Enhanced PostScript (EPS) files with standard and extended preview as well as w/o preview at all.


How to Attach the PDF Component to Core ImageGear

To use the ImageGear PDF Component, you have attach this component to core ImageGear using the following function:

IG_comm_comp_attach("PDF")

To check if the Component is attached successfully, use the following function:

IG_comm_comp_check("PDF")

This function (method) returns TRUE if the Component is attached.

Initializing the Component

To initialize the ImageGear PDF component, the "PDF" component needs to be attached to the ImageGear component manager.

The following resource content is required by the ImageGear PDF component initialization routine.

Resource\PDF\CIDFont\
PDF CID fonts directory
Resource\PDF\CMap\
PDF font CMaps directory
Resource\PDF\Font\
PDF fonts directory
Resource\PDF\Unicode\
PDF unicode mappings directory
Resource\PS\ColorRendering\
Color rendering PostScript
Resource\PS\ICCProfiles\
Directory containing the ICC profiles that allow using the Adobe Color Engine (ACE)
Resource\PS\Fonts\
PS fonts directory
Resource\PS\ProcSet\
PostScript procedures
Resource\PS\ps.vm
A file for initialization the PostScript Interpreter's virtual memory
Resource\PS\startupNORM.ps
Startup PostScript program used to initialize the PostScript Interpreter
Resource\PS\superatm.db
Adobe® Type Manager® (ATM®) database used to substitute missing fonts

The ImageGear PDF component uses the following PDF global control parameters to locate the resource content:

PDF.PDF_RESOURCE_PATH
path to the Resource\PDF directory
PDF.PS_RESOURCE_PATH
path to the Resource\PS directory
PDF.HOST_FONT_PATH
path to the system font directory
PDF.TMP_PATH
path to the TEMP directory

If the PDF global parameters are not defined, the ImageGear PDF does the following:

  • Resource content gets from the directory defined by IMAGE_GEAR_PDF_RESOURCE_PATH and IMAGE_GEAR_PS_RESOURCE_PATH environment variables, "\AccuSoft\ImageGearv16\Shared\Bin\Resource\PDF\" and "\AccuSoft\ImageGear v16\Shared\Bin\Resource\PS\" if those are not defined
  • Host fonts get from the directory defined by IMAGE_GEAR_HOST_FONT_PATH, "/usr/local/hfonts/" if that is not defined
  • Temporary directory gets from the directory defined by IMAGE_GEAR_TEMP_PATH, "/tmp/"if that is not defined

PDF Global Control Parameters

PDF.ENABLE_POSTSCRIPT

Used to enable/disable PostScript support in PDF component.

By default the ImageGear PDF Component enables PDF and PostScript file format support. But it is possbile to disable PostScript file format support in case if it is not required. There is a boolean global parameter named PDF.ENABLE_POSTSCRIPT used to control this.

To disable PostScript use:

AT_BOOL     bEnable = FALSE;
IG_gctrl_item_set( "PDF.ENABLE_POSTSCRIPT", AM_TID_AT_BOOL,
&bEnable,
sizeof(AT_BOOL), NULL );

Retrieving Info About the Component

To retrieve information about the attached Component, call the following function:

IG_comm_comp_list(LPUINT *lpnCount, UINT nIndex, LPCHAR lpComp,
DWORD dwCompSize, LPUINT lpnRevMajor, LPUINT lpnRevMinor, LPUINT
lpnRevUpdate,
LPCHAR lpBuildDate, UINT nBDSize, LPCHAR lpInfoStr, UINT
nISSize)

This function (methods) provides you with the full list of info about the component determined by nIndex index from the list of currently attached components whose number are returned trough lpnCount argument.

For more detailed information about these functions usage see Using ImageGear Component Manager section


PDF Standards

PDF/X and PDF/A standards are defined by the International Organization for Standardization (ISO).

  • PDF/X standards apply to graphic content exchange

The most widely used standards for a print publishing workflow are several PDF/X formats: PDF/X-1a, PDF/X-3, and PDF/X-4.

  • PDF/A standards apply to long-term archiving of electronic documents

The most widely used standards for PDF archiving are PDF/A-1a and PDF/A-1b (for less stringent requirements).

For more information on PDF/X and PDF/A, see the ISO website.

PDF/A

PDF/A is a file format based on PDF. It provides a mechanism for representing electronic documents in a manner that preserves their visual appearance over time, independent of the tools and systems used for creating, storing or rendering the files.

PDF/A-1a

Level A conforming files shall adhere to all of the requirements of the ISO 19005-1:2005 specification.

A file meeting this conformance level is said to be a "conforming PDF/A -1a file."

PDF/A-1b

In recognition of the varying preservation needs of the diverse user communities making use of PDF files, the ISO 19005-1:2005 specification defines a Level B conformance level. Level B conforming files shall adhere to all of the requirements of the spec except those applicable to Level A only.

A file meeting this conformance level is said to be a "conforming PDF/A-1b file."

NOTE: The Level B conformance requirements are intended to be those minimally necessary to ensure that the rendered visual appearance of a conforming file is preservable over the long term. However, Level B conforming files might not have sufficiently rich internal information to allow for the preservation of the document's logical structure and content text stream in natural reading order, which is provided by Level A conformance. The requirements for Level A conformance place greater responsibilities on writers of conforming files and those preparing such files, but these requirements allow for a higher level of document preservation service and confidence

PDF/X

PDF/X is a PDF based format for the exchange of object-based data where individual objects may be in either vector or raster data structures. PDF/X defines a data format and its usage to permit the predictable dissemination of a compound entity to one or more locations, as colour-managed, CMYK, gray, RGB, and/or spot colour data, in a form ready for final print reproduction, by transfer of a single file. This file contains all the content information necessary to process and render the document, as intended by the sender, coded inside a single PDF file. No other parts, neither external files nor internally embedded files, are required or permitted. This exchange requires no prior knowledge of the sending and receiving environments and is sometimes referred to as "blind" exchange. It is platform- and transport-independent.

PDF/X-3:2003

PDF/X-3:2003 conforming files shall adhere to all of the requirements of the ISO 15930-6:2003 specification defining "Prepress digital data exchange using PDF -- Part 6: Complete exchange of printing data suitable for colour-managed workflows using PDF 1.4 (PDF/X-3)".

A file meeting this conformance level is said to be a "conforming PDF/X-3 file."


Working with PDF Layers

This section explains how to work with PDF Layers, as follows:

  • Layer Objects and Visibility
  • Layers Diagram
  • Visibility Policy
  • Working with Containers, Dictionaries and Layers using ImageGear PDF sample

For more information, see Using ImageGear PDF Component and HIG_PDF_DICTIONARY and HIG_PDF_LAYER.

Layer Objects and Visibility

The following objects are related to PDF Layers and responsible for the visibility.

Layers

Each layer has a name and a visibility state for the containers connected to the layer through a Dictionary. The visibility state can have one of two values - ON or OFF.

Dictionaries

Each dictionary contains the array of layers and a Boolean function, which takes all the layers' states as input and applies the visibility policy function to the layers' state values producing the Boolean result whether or not to display all the objects from the dictionary's container. The output can have one of two values - ON or OFF.

Containers

Each container is an arbitrary set of PDF elements or other containers. Each container is associated with a dictionary. The container and all its elements (including the other containers) are displayed when its dictionary's visibility policy Boolean function results with ON.

The following diagram shows the relationship between containers and the other PDF document objects:

Layers Diagram

The following diagram shows interconnection between PDF objects and layers:

Visibility Policy

Dictionary Boolean functions define the visibility policy. It can be one of the following:

  • AllOn - equivalent to "AND" function for all input parameters,
  • AnyOn - equivalent to "OR" function for all input parameters,
  • AnyOff - equivalent to "NOT-OR" function for all input parameters,
  • AllOff - equivalent to "NOT-AND" function for all input parameters,

In other words:

AllOn
All the containers from the dictionary will be displayed when all the input layers' states are `ON'
AnyOn
All the containers from the dictionary will be displayed when at least one of the input layers state is `ON'
AnyOff
All the containers from the dictionary will be displayed when at least one of the input layers state is `OFF'
AllOff
All the containers from the dictionary will be displayed when all the input layers' states are `OFF'

Working with Containers, Dictionaries and Layers using ImageGear PDF sample

Before creating a container you need to create one or more layers using the View -> Layers menu. Make sure to create some simple elements like text, paths or images as well.

In order to create container right click on the PDF page and select Create -> Container. You will be prompted to select all the layers you want to associate with the containers dictionary, which will affect the container's visibility. You also need to select the visibility policy and check all the elements you want to include into the new container. When container is created a new dictionary is automatically created as well.

To show or hide the container's elements use View -> Layers menu to change the layer's state to ON or OFF.

In order to rearrange the container's elements you can right click to delete the existing container, which will free its elements and create the new one.


Working with 3D Artwork

Starting with version 1.6, PDF introduces the capability for collections of 3D objects, such as those used by CAD formats, to be embedded in PDF files. Such collections are called 3D models and PDF refers to them as 3D Artwork. In PDF documents 3D Artwork is represented by 3D annotations stored in Universal 3D (U3D) format.

ImageGear PDF component allows the following 3D features:

  • 3D content can be rendered within a page
  • Multiple instances of 3D data can appear within a page or document
  • Specific views of 3D artwork can be available, including a default view that is displayed initially and other views that can be selected.
  • Users can rotate and move 3D data, enabling them to examine complex objects from any angle or orientation.

Working Process

ImageGear 3D Artwork processing integrates the following components:

  • ImageGear PDF - PDF content reader and writer.
  • ImageGear U3D - U3D format decoder and encoder.
  • ImageGear ARTX - Image annotation mark used to represent 3D Artwork.
  • ImageGear ARTXGUI - Interactive GUI forms and toolbar.
  • ImageGear VECT - Vector data storage and API for interaction.

3D PDF Artwork is converted into the ART Image mark referencing a vector HIGEAR page, so it could be edited, interacted with and/or saved back to PDF.

3D Interaction is possible in the ART RUN Mode, by clicking over the mark and using the popup 3D toolbar. Users can rotate, scale and move 3D data, as well as change lights and views settings.

XML Import and Export

The vector Image mark representing 3D data can be exported to XML in the U3D format. While saving to XML, vector HIGEAR page associated with the Image mark will be converted to U3D stream and saved to XML Data tag. While loading from XML, U3D stream will be loaded as a vector HIGEAR page and will be attached to the Image mark.


Distributing PDF and PS Fonts with Your Application

ImageGear toolkit comes with multiple PDF and PS fonts that can be used for developing an application based on ImageGear. However only four fonts are pre-licensed for distribution:

  • The two MultiMaster PDF fonts, AdobeSansMM (zx______.mmm) and AdobeSerifMM (zy______.mmm).
  • The two PostScript fonts, Courier and NotDefFont.

These fonts are the property of Adobe® Systems and are fully licensed for distribution with your application.

If you need to distribute additional fonts, you need to get a license for the redistribution of those fonts. However, you are not limited to the fonts supplied with ImageGear; it's possible to add other fonts to be used with ImageGear PDF/PS support. To do this, place your fonts to the PDF "Resource" directory as follows:

  • CID fonts (if any) to ...\Resource\PDF\CIDFont
  • CMaps fonts to ...\Resource\PDF\CMap
  • PDF fonts to ...\Resource\PDF\Font
  • PostScript fonts to ...\Resource\PS\Fonts

Please also note that the fonts that are pre-licensed for distribution (i.e., AdobeSansMM, AdobeSerifMM, "Courier" and "NotDefFont") provide the substitution capabilities for the other fonts, so they are likely to be enough for many cases. The below paragraph provides more technical details regarding font substitution.

The multiple master font format is an extension of the Type 1 font format that allows the generation of a wide variety of typeface styles from a single font program. This is accomplished through the presence of various design dimensions in the font. Examples of design dimensions are weight (light to extra-bold) and width (condensed to expanded). Coordinates along these design dimensions (such as the degree of boldness) are specified by numbers. A particular choice of numbers selects an instance of the multiple master font. Adobe® Technical Note #5015, Type 1 Font Format Supplement, describes multiple master fonts in detail.


PDF Format Filter

If you attach the PDF Component to core ImageGear, you can initialize the PDF Format Filter functionality, which can be accessed through the core ImageGear Format Filter API. The PDF Format Filter supports some features of PDF file processing. These features are determined by IG_FLTR_ flags. This Format Filter also allows you to save PDF raster images with different compressions, depending on image bit depth.

Supported Features

The ImageGear PDF Format Filter supports the following features of PDF file processing:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_MPAGEWRITEPSUPPORT - multi-page file writing
  • IG_FLTR_PAGEDELETESUPPORT - page deleting from multi-page files
  • IG_FLTR_PAGESWAPSUPPORT - page swaping in multi-page files

You can detect, read, write, and work with pages in multi-page PDF files using IG_fltr_...() functions from ImageGear Format Filters API. Please see Working with Format Filters section in this .

Supported Compressions for Images

The following raster image compressions are supported by ImageGear PDF component for read and write:

  • IG_COMPRESSION_NONE - for 1, 2, 4, 8, 24, 32 bits per pixel (bpp)
  • IG_COMPRESSION_CCITT_G3 - for 1 bpp
  • IG_COMPRESSION_CCITT_G4 - for 1 bpp
  • IG_COMPRESSION_CCITT_G32D - for 1 bpp
  • IG_COMPRESSION_JBIG2* - for 1 bit per pixel
  • IG_COMPRESSION_RLE - for 1, 2, 4, 8, 24, 32 bits per pixel
  • IG_COMPRESSION_DEFLATE - for 1, 2, 4, 8, 24, 32 bits per pixel
  • IG_COMPRESSION_JPEG - for 8, 24, 32 bits per pixel
  • IG_COMPRESSION_LZW* - for 1, 2, 4, 8 bits per pixel
  • IG_COMPRESSION_JPEG2K* - for 1, 2, 4, 8, 24, 32 bits per pixel

* - Supported when the appropriate ImageGear component is loaded.

NOTE: Once the image is compressed, an optional text encoding scheme can be applied to convert binary data to text format. See the description of the TEXT_ENCODING control parameter for details.


PDF Format Filter Control Parameters

ImageGear PDF Format Filter provides you with many control parameters that are optional, but can be used for PDF file processing refinement.

  • DEPTH
  • INC_REND
  • INDEPENDENT_PAGESIZE
  • PAGE_HEIGHT
  • PAGE_WIDTH
  • PASSWORD
  • PRINT_DEPTH
  • PRINT_RESOLUTION_X
  • PRINT_RESOLUTION_Y
  • RESOLUTION_3D
  • RESOLUTION_X
  • RESOLUTION_Y
  • SAVE_FLAGS
  • SAVE_MAJOR
  • SAVE_MINOR
  • SMOOTH_FLAGS
  • TEXT_ENCODING
  • USE_CROP_BOX


DEPTH

This parameter specifies bit depth in bits per pixels during the PDF document convertion into the raster image. The more is this value, the more quality of the raster image you get and the more memory is required for rasterization. The DIB of the output raster image has this value as a bit count.

Data type:

UINT

Default Value:

24

Valid Values:

1, 8, 24

Example:

// Get current value of DEPTH control parameter
IG_fltr_ctrl_get( IG_FORMAT_PDF, "DEPTH", FALSE, NULL, NULL,
(LPVOID)nDepth, sizeof(nDepth) );
// Set new value to the DEPTH control parameter
IG_fltr_ctrl_set( IG_FORMAT_PDF, "DEPTH", (LPVOID)1,
sizeof(UINT));


INC_REND

This parameter specifaies whether incremental rendering or rendering at once should be performed.

Data type:

Boolean

Default Value:

False

Valid Values:

True, False

Example:

// Get current value of INC_REND control parameter
IG_fltr_ctrl_get( IG_FORMAT_PDF, "INC_REND", FALSE, NULL, NULL,
(LPVOID)nDepth, sizeof(nDepth) );
// Set new value to the INC_REND control parameter
IG_fltr_ctrl_set( IG_FORMAT_PDF, "INC_REND", TRUE,
sizeof(UINT));


INDEPENDENT_PAGESIZE

(Used with PDF write only.) If this parameter is FALSE, when saving a raster image into the PDF document, the width and height of the newly created page is set to the width and height of the previous page in the PDF document. If the previous page does not exist, the width and height are calculated from the image resolution and size as follows:

Width = <width of the raster image> * 72 / <X DPI of the raster
image>
Height = < height of the raster image> * 72 / <Y DPI of the
raster image>

If the image resolution is not defined, the width and height are set to the width and height of the A4 page, which is 612x792.

Use the following parameters to set the page size when this option is TRUE:

  • PAGE_HEIGHT
  • PAGE_WIDTH

Data type:

AT_BOOL

Valid Values:

TRUE, FALSE

Default Value:

FALSE

Example:

// Get current value of INDEPENDENT_PAGESIZE control parameter
IG_fltr_ctrl_get(IG_FORMAT_PDF, "INDEPENDENT_PAGESIZE", FALSE,
NULL, NULL, (LPVOID)bIndependentPagesize,
sizeof(bIndependentPagesize));
// Set new value to INDEPENDENT_PAGESIZE control parameter
IG_fltr_ctrl_set(IG_FORMAT_PDF, "INDEPENDENT_PAGESIZE",
(LPVOID)TRUE, sizeof(AT_BOOL));


PAGE_HEIGHT

(Used with PDF write only.) This parameter sets the height of the page (in 1/72 inches). If this option is 0, the height is calculated from the image resolution and size as follows:

Height = < height of the raster image> * 72 / <Y DPI of the
raster image>

If the image resolution is not defined, the height is set to the height of an A4 page, which is 792.

This option is not used if RESOLUTION_X is FALSE.

Data type:

UINT

Valid Values:

Any non-negative value.

Default Value:

0

Example:

// Get current value of PAGE_HEIGHT control parameter
IG_fltr_ctrl_get(IG_FORMAT_PDF, "PAGE_HEIGHT", FALSE, NULL,
NULL, (LPVOID)nPageHeight, sizeof(nPageHeight));
// Set new value to PAGE_HEIGHT control parameter
IG_fltr_ctrl_set(IG_FORMAT_PDF, "PAGE_HEIGHT", (LPVOID)792,
sizeof(UINT));


PAGE_WIDTH

(Used with PDF write only.) This parameter sets the width of the page (in 1/72 inches). If this option is 0, the width is calculated from the image resolution and size as follows:

Width = <width of the raster image> * 72 / <X DPI of the raster
image>

If the image resolution is not defined, the width is set to the width of the A4 page, which is 612.

This option is not used if RESOLUTION_X is FALSE.

Data type:

UINT

Valid Values:

Any non-negative value.

Default Value:

0

Example:

// Get current value of PAGE_WIDTH control parameter
IG_fltr_ctrl_get(IG_FORMAT_PDF, "PAGE_WIDTH", FALSE, NULL,
NULL, (LPVOID)nPageWidth, sizeof(nPageWidth));
// Set new value to PAGE_WIDTH control parameter
IG_fltr_ctrl_set(IG_FORMAT_PDF, "PAGE_WIDTH", (LPVOID)612,
sizeof(UINT));


PASSWORD

This parameter specifies the password string for the password of the protected PDF documents.

Data type:

LPCHAR

Default Value:

""

Valid Values:

Any

Example:
// Get current value of PASSWORD control parameter
IG_fltr_ctrl_get( IG_FORMAT_PDF, "PASSWORD", FALSE, NULL, NULL,
(LPVOID)&szPassword, sizeof(szPassword) );
// Set new value to the PASSWORD control parameter
IG_fltr_ctrl_set( IG_FORMAT_PDF, "PASSWORD",
(LPVOID)szPassword, sizeof(szPassword));


PRINT_DEPTH

This parameter specifies bit depth in bits per pixels during the PDF document printing. The more is this value, the more quality of the raster image you get and the more memory is required for printing.

Data type:

UINT

Default Value:

8

Valid Values:

1, 8, 24

Example:

// Get current value of PRINT_DEPTH control parameter
IG_fltr_ctrl_get( IG_FORMAT_PDF, "PRINT_DEPTH", FALSE, NULL,
NULL, (LPVOID)nPrintDepth, sizeof(nPrintDepth) );
// Set new value to the PRINT_DEPTH control parameter
IG_fltr_ctrl_set( IG_FORMAT_PDF, "PRINT_DEPTH", (LPVOID)1,
sizeof(UINT));


PRINT_RESOLUTION_X

This parameter specifies the horizontal resolution in dots per inch during the PDF document printing. The more is this value, the more is the quality of the image to be printed.

Data type:

UINT

Default Value:

300

Valid Values:

Any

Example:

// Get current value of PRINT_RESOLUTION_X control parameter
IG_fltr_ctrl_get( IG_FORMAT_PDF, "PRINT_RESOLUTION_X", FALSE,
NULL, NULL, (LPVOID)nPrintResolutionX,
sizeof(nPrintResolutionX) );
// Set new value to the PRINT_RESOLUTION_X control parameter
IG_fltr_ctrl_set( IG_FORMAT_PDF, "PRINT_RESOLUTION_X",
(LPVOID)300, sizeof(UINT));


PRINT_RESOLUTION_Y

This parameter specifies the vertical resolution in dots per inch during the PDF document printing. The more is this value, the more is the quality of the image to be printed.

Data type:

UINT

Default Value:

300

Valid Values:

Any

Example:

// Get current value of PRINT_RESOLUTION_Y control parameter
IG_fltr_ctrl_get( IG_FORMAT_PDF, "PRINT_RESOLUTION_Y", FALSE,
NULL, NULL, (LPVOID)nPrintResolutionY,
sizeof(nPrintResolutionY) );
// Set new value to the PRINT_RESOLUTION_Y control parameter
IG_fltr_ctrl_set( IG_FORMAT_PDF, "PRINT_RESOLUTION_Y",
(LPVOID)300, sizeof(UINT));


RESOLUTION_3D

This parameter specifies the resolution in dots per inch used for generating a pre-rendered bitmap of the default view of the 3D artwork. Producers should provide bitmaps of appropriate resolution for all intended uses of the document, i.e. a high-resolution bitmap for high-quality printing and a default screen-resolution bitmap for on-screen viewing.

Data type:

UINT

Valid Values:

Any, except zero

Default Value:

72


RESOLUTION_X

This parameter specifies the horizontal resolution in dots per inch during the PDF/PS document conversion into the raster image. The higher this value, the higher-quality raster image you get after rasterization. The DIB of the output raster image has this value as an X resolution.

Data type:

UINT

Valid Values:

Any

Default Value:

72

Example:

// Get current value of RESOLUTION_X control parameter
IG_fltr_ctrl_get(IG_FORMAT_PDF, "RESOLUTION_X", FALSE, NULL,
NULL, (LPVOID)nResolutionX, sizeof(nResolutionX));
// Set new value to the RESOLUTION_X control parameter
IG_fltr_ctrl_set(IG_FORMAT_PDF, "RESOLUTION_X", (LPVOID)300,
sizeof(UINT));


RESOLUTION_Y

This parameter specifies the vertical resolution in dots per inch during the PDF/PS document conversion into the raster image. The higher this value, the higher-quality raster image you get after rasterization. The DIB of the output raster image has this value as an Y resolution.

Data type:

UINT

Valid Values:

Any

Default Value:

72

Example:

// Get current value of RESOLUTION_Y control parameter
IG_fltr_ctrl_get(IG_FORMAT_PDF, "RESOLUTION_Y", FALSE, NULL,
NULL, (LPVOID)nResolutionY, sizeof(nResolutionY));
// Set new value to the RESOLUTION_Y control parameter
IG_fltr_ctrl_set(IG_FORMAT_PDF, "RESOLUTION_Y", (LPVOID)300,
sizeof(UINT));


SAVE_FLAGS

(Used with PDF write only.) This parameter specifes an option for saving a PDF file, which allows you to remove unreferenced objects, often reducing file size as well as to write a linearized file for page-served remote (network) access.

Data type:

UINT

Default Value:

IG_PDF_OPTIMIZED

Valid Values:

A bit composition of an OR of the following values:

  • IG_PDF_OPTIMIZED = 32 - perform garbage collection on unreferenced objects
  • IG_PDF_LINEARIZED = 4 - writes the file linearized for page serving over the remote connections

Example:

// Get current value of SAVE_FLAGS control parameter
IG_fltr_ctrl_get( IG_FORMAT_PDF, "SAVE_FLAGS", FALSE, NULL,
NULL, (LPVOID)nSaveFlags, sizeof(nSaveFlags) );

// Set new value to SAVE_FLAGS control parameter
IG_fltr_ctrl_set( IG_FORMAT_PDF, "SAVE_FLAGS", (LPVOID)
IG_PDF_OPTIMIZED|IG_PDF_LINEARIZED, sizeof(UINT) );


SAVE_MAJOR

Specifies major PDF version number of the document for saving. If major equals 0, both major and minor are ignored and the document is saved to the library's default version.

Make sure that the document conforms to the version number you are setting.

Data type:

UINT

Default Value:

0

Valid Values:

1


SAVE_MINOR

Specifies minor PDF version number of the document for saving. Make sure that the document conforms to the version number you are setting.

Data type:

UINT

Default Value:

0

Valid Values:

6, 5, 4 etc.


SMOOTH_FLAGS

This parameter specifes smooth settings for PDF rasterization.

Data type:

UINT

Default Value:

0

Valid Values:

A bit composition of an OR of the following values:

  • 1 - Draw smooth text
  • 2 - Draw smooth line art
  • 4 - Draw smooth image

Example:

// Get current value of SMOOTH_FLAGS control parameter
IG_fltr_ctrl_get( IG_FORMAT_PDF, "SMOOTH_FLAGS", FALSE, NULL,
NULL, (LPVOID)nSmoothFlags, sizeof(nSmoothFlags) );
// Set new value to SMOOTH_FLAGS control parameter
IG_fltr_ctrl_set( IG_FORMAT_PDF, "SMOOTH_FLAGS", (LPVOID) 1|4,
sizeof(UINT) );


TEXT_ENCODING

(Used with PDF write only.) This parameter specifies which encoding scheme should be used to convert binary image data to the text format when saving raster image into the PDF document.

Data type:

UINT

Valid Values:

  • IG_PDF_TEXTENC_NONE = 1 - no encoding used
  • IG_PDF_TEXTENC_ASCII_85 = 2 - ASCII 85 encoding used
  • IG_PDF_TEXTENC_ASCII_HEX = 3- ASCII HEX encoding used

Default Value:

IG_PDF_TEXTENC_ASCII_85

Example:

// Get current value of TEXT_ENCODING control parameter
IG_fltr_ctrl_get(IG_FORMAT_PDF, "TEXT_ENCODING", FALSE, NULL,
NULL, (LPVOID)nTextEncoding, sizeof(nTextEncoding));
// Set new value to TEXT_ENCODING control parameter
IG_fltr_ctrl_set(IG_FORMAT_PDF, "TEXT_ENCODING",
(LPVOID)IG_PDF_TEXTENC_NONE, sizeof(UINT));


USE_CROP_BOX

TRUE - use PDF crop box rectangle for page layout, FALSE - use PDF media rectangle for page layout.

Data type:

AT_BOOL

Valid Values:

True, False

Default Value:

True

Example:

// Get current value of USE_CROP_BOX control parameter
IG_fltr_ctrl_get(IG_FORMAT_PDF, "USE_CROP_BOX", FALSE, NULL,
NULL, (LPVOID)bUseCropBox, sizeof(bUseCropBox));
// Set new value to USE_CROP_BOX control parameter
IG_fltr_ctrl_set(IG_FORMAT_PDF, "USE_CROP_BOX", (LPVOID)FALSE,
sizeof(UINT));


PostScript Filter Control Parameters

ImageGear PostScript Filter provides you with many control parameters that are optional but can be used for PostScript file processing refinement.

  • AUTO_POSITION
  • DEPTH
  • HEIGHT
  • INDEPENDENT_PAGESIZE
  • JOB_OPTIONS_FILE
  • LEVEL
  • PAGE_HEIGHT
  • PAGE_WIDTH
  • READ_PREVIEW
  • RESOLUTION_X
  • RESOLUTION_Y
  • SMOOTH_FLAGS
  • TEXT_ENCODING
  • TYPE
  • USE_CROP_BOX
  • WIDTH


AUTO_POSITION

This parameter enables/disables AutoPositionEPSFiles option for reading PS/EPS file format.

Data type:

Boolean

Default Value:

TRUE

Valid Values:

TRUE, FALSE

Example:

// Get current value of AUTO_POSITION control parameter
IG_fltr_ctrl_get( IG_FORMAT_POSTSCRIPT, "AUTO_POSITION", FALSE,
NULL, NULL, (LPVOID)nDepth, sizeof(nDepth) );
// Set new value to the AUTO_POSITION control parameter
IG_fltr_ctrl_set( IG_FORMAT_POSTSCRIPT, "AUTO_POSITION",
(LPVOID)FALSE, sizeof(UINT));


DEPTH

This parameter specifies bit depth in bits per pixels during the PostScript document convertion into the raster image. The more is this value, the more quality of the raster image you get and the more memory is required for the rasterization. The DIB of the output raster image has this value as a bit count.

Data type:

UINT

Default Value:

24

Valid Values:

1, 8, 24

Example:

// Get current value of DEPTH control parameter
IG_fltr_ctrl_get( IG_FORMAT_POSTSCRIPT, "DEPTH", FALSE, NULL,
NULL, (LPVOID)nDepth, sizeof(nDepth) );
// Set new value to the DEPTH control parameter
IG_fltr_ctrl_set( IG_FORMAT_POSTSCRIPT, "DEPTH", (LPVOID)1,
sizeof(UINT));


HEIGHT

This parameter determines the height of PS page to load.

Data type:

UINT

Default Value:

0

Valid Values:

Any positive value

Example:

// Get current value of HEIGHT control parameter
IG_fltr_ctrl_get( IG_FORMAT_POSTSCRIPT, "HEIGHT", FALSE, NULL,
NULL, (LPVOID)nDepth, sizeof(nDepth) );
// Set new value to the HEIGHT control parameter
IG_fltr_ctrl_set( IG_FORMAT_POSTSCRIPT, "HEIGHT", (LPVOID)1,
sizeof(UINT));


INDEPENDENT_PAGESIZE

(Used with PostScript write only.) When this parameter is FALSE, when saving a raster image into the PostScript document, the width and height of the newly created page is set to the width and height of the previous page in the PostScript document. If the previous page does not exist, the width and height are calculated from the image resolution and size as follows:

Width = <width of the raster image> * 72 / <X DPI of the raster image>

Height = < height of the raster image> * 72 / <Y DPI of the raster image>

If the image resolution is not defined, the width and height are set to the width and height of the A4 page, which is 612x792.

Use the following parameters to set the page size when this option is TRUE:

  • PAGE_HEIGHT
  • PAGE_WIDTH

Data type:

AT_BOOL

Valid Values:

TRUE, FALSE

Default Value:

FALSE

Example:

// Get current value of INDEPENDENT_PAGESIZE control parameter
IG_fltr_ctrl_get(IG_FORMAT_POSTSCRIPT, "INDEPENDENT_PAGESIZE",
FALSE, NULL, NULL, (LPVOID)bIndependentPagesize,
sizeof(bIndependentPagesize));
// Set new value to INDEPENDENT_PAGESIZE control parameter
IG_fltr_ctrl_set(IG_FORMAT_POSTSCRIPT, "INDEPENDENT_PAGESIZE",
(LPVOID)TRUE, sizeof(AT_BOOL));


JOB_OPTIONS_FILE

This parameter determines JobOptions file name.

Data type:

LPSTR

Default Value:

N/A

Valid Values:

Any string

Example:

// Get current value of JOB_OPTIONS_FILE control parameter
IG_fltr_ctrl_get( IG_FORMAT_POSTSCRIPT, "JOB_OPTIONS_FILE",
FALSE, NULL, NULL, (LPVOID)nDepth, sizeof(nDepth) );
// Set new value to the JOB_OPTIONS_FILE control parameter
IG_fltr_ctrl_set( IG_FORMAT_POSTSCRIPT, "JOB_OPTIONS_FILE",
(LPVOID)JOBOPT_1, sizeof(UINT));


LEVEL

(Used with PostScript write only.) This parameter specifies a language level of the output PostScript 3.0 document when saving to PostScript.

Data type:

UINT

Valid Values:

  • IG_PS_LEVEL_1 = 1 - language level 1
  • IG_PS_LEVEL_2 = 2 - language level 2
  • IG_PS_LEVEL_3 = 3 - language level 3

Default Value:

IG_PS_LEVEL_3

Example:

// Get current value of LEVEL control parameter
IG_fltr_ctrl_get( IG_FORMAT_POSTSCRIPT, " LEVEL ", FALSE, NULL,
NULL, (LPVOID)nLevel, sizeof(nLevel) );

// Set new value to LEVEL control parameter
IG_fltr_ctrl_set( IG_FORMAT_POSTSCRIPT, "LEVEL", (LPVOID)
IG_PS_LEVEL_2, sizeof(UINT) );


PAGE_HEIGHT

(Used with PostScript write only.) This parameter sets the height of the page (in 1/72 inches). If this option is 0, the height is calculated from the image resolution and size as follows:

Height = < height of the raster image> * 72 / <Y DPI of the raster image>

If the image resolution is not defined, the height is set to the height of an A4 page, which is 792.

This option is not used if RESOLUTION_X is FALSE.

Data type:

UINT

Valid Values:

Any non-negative value.

Default Value:

0

Example:

// Get current value of PAGE_HEIGHT control parameter
IG_fltr_ctrl_get(IG_FORMAT_POSTSCRIPT, "PAGE_HEIGHT", FALSE,
NULL, NULL, (LPVOID)nPageHeight, sizeof(nPageHeight));
// Set new value to PAGE_HEIGHT control parameter
IG_fltr_ctrl_set(IG_FORMAT_POSTSCRIPT, "PAGE_HEIGHT",
(LPVOID)792, sizeof(UINT));


PAGE_WIDTH

(Used with PostScript write only.) This parameter sets the width of the page (in 1/72 inches). If this option is 0, the width is calculated from the image resolution and size as follows:

Width = <width of the raster image> * 72 / <X DPI of the raster image>

If the image resolution is not defined, the width is set to the width of the A4 page, which is 612.

This option is not used if RESOLUTION_X is FALSE.

Data type:

UINT

Valid Values:

Any non-negative value.

Default Value:

0

Example:

// Get current value of PAGE_WIDTH control parameter
IG_fltr_ctrl_get(IG_FORMAT_POSTSCRIPT, "PAGE_WIDTH", FALSE,
NULL, NULL, (LPVOID)nPageWidth, sizeof(nPageWidth));
// Set new value to PAGE_WIDTH control parameter
IG_fltr_ctrl_set(IG_FORMAT_POSTSCRIPT, "PAGE_WIDTH",
(LPVOID)612, sizeof(UINT));


READ_PREVIEW

This parameter determines whether to read TIFF preview only or not.Data type:

Boolean

Default Value:

FALSE

Valid Values:

TRUE, FALSE

Example:

// Get current value of READ_PREVIEW control parameter
IG_fltr_ctrl_get( IG_FORMAT_POSTSCRIPT, "READ_PREVIEW", FALSE,
NULL, NULL, (LPVOID)nDepth, sizeof(nDepth) );
// Set new value to the READ_PREVIEW control parameter
IG_fltr_ctrl_set( IG_FORMAT_POSTSCRIPT, "READ_PREVIEW",
(LPVOID)TRUE, sizeof(UINT));


RESOLUTION_X

This parameter specifies the horizontal resolution in dots per inch during the PostScript/PDF document conversion into the raster image. The higher this value, the higher-quality raster image you get after rasterization. The DIB of the output raster image has this value as an X resolution.

Data type:

UINT

Valid Values:

Any

Default Value:

72

Example:

// Get current value of RESOLUTION_X control parameter
IG_fltr_ctrl_get(IG_FORMAT_POSTSCRIPT, "RESOLUTION_X", FALSE,
NULL, NULL, (LPVOID)nResolutionX, sizeof(nResolutionX));
// Set new value to the RESOLUTION_X control parameter
IG_fltr_ctrl_set(IG_FORMAT_POSTSCRIPT, "RESOLUTION_X",
(LPVOID)300, sizeof(UINT));


RESOLUTION_Y

This parameter specifies the vertical resolution in dots per inch during the PostScript/PDF document conversion into the raster image. The higher this value, the higher-quality raster image you get after rasterization. The DIB of the output raster image has this value as an Y resolution.

Data type:

UINT

Valid Values:

Any

Default Value:

72

Example:

// Get current value of RESOLUTION_Y control parameter
IG_fltr_ctrl_get(IG_FORMAT_POSTSCRIPT, "RESOLUTION_Y", FALSE,
NULL, NULL, (LPVOID)nResolutionY, sizeof(nResolutionY));
// Set new value to the RESOLUTION_Y control parameter
IG_fltr_ctrl_set(IG_FORMAT_POSTSCRIPT, "RESOLUTION_Y",
(LPVOID)300, sizeof(UINT));


SMOOTH_FLAGS

This parameter specifes smooth settings for PostScript rasterization.

Data type:

UINT

Default Value:

0

Valid Values:

A bit composition of an OR of the following values:

  • 1 - Draw smooth text
  • 2 - Draw smooth line art
  • 4 - Draw smooth image

Example:

// Get current value of SMOOTH_FLAGS control parameter
IG_fltr_ctrl_get( IG_FORMAT_POSTSCRIPT, "SMOOTH_FLAGS", FALSE,
NULL, NULL, (LPVOID)nSmoothFlags, sizeof(nSmoothFlags) );
// Set new value to SMOOTH_FLAGS control parameter
IG_fltr_ctrl_set( IG_FORMAT_POSTSCRIPT, "SMOOTH_FLAGS",
(LPVOID) 1|4, sizeof(UINT) );


TEXT_ENCODING

(Used with PostScript write only.) This parameter specifies which encoding scheme should be used to convert binary image data to the text format when saving raster image into the PostScript document.

Data type:

UINT

Valid Values:

  • IG_PDF_TEXTENC_NONE = 1 - no encoding used
  • IG_PDF_TEXTENC_ASCII_85 = 2 - ASCII 85 encoding used
  • IG_PDF_TEXTENC_ASCII_HEX = 3 - ASCII HEX encoding used

Default Value:

IG_PDF_TEXTENC_ASCII_85

Example:

// Get current value of TEXT_ENCODING control parameter
IG_fltr_ctrl_get(IG_FORMAT_POSTSCRIPT, "TEXT_ENCODING", FALSE,
NULL, NULL, (LPVOID)nTextEncoding, sizeof(nTextEncoding));
// Set new value to TEXT_ENCODING control parameter
IG_fltr_ctrl_set(IG_FORMAT_POSTSCRIPT, "TEXT_ENCODING",
(LPVOID)IG_PDF_TEXTENC_NONE, sizeof(UINT));


TYPE

(Used with PostScript write only.) This parameter specifies a type of the output PostScript document when saving to PostScript.

Data type:

UINT

Valid Values:

  • IG_POSTSCRIPT = 0 - PS file
  • IG_EPS_NO_PREVIEW = 1 - EPS file with no preview
  • IG_EPS_STANDARD_PREVIEW = 2 - EPS file with standard preview
  • IG_EPS_EXTENDED_PREVIEW = 3 - EPS file with extended preview

Default Value:

IG_POSTSCRIPT

Example:

// Get current value of TYPE control parameter
IG_fltr_ctrl_get( IG_FORMAT_POSTSCRIPT, "TYPE", FALSE, NULL,
NULL, (LPVOID)nType, sizeof(nType) );

// Set new value to TYPE control parameter
IG_fltr_ctrl_set( IG_FORMAT_POSTSCRIPT, "TYPE", (LPVOID)
IG_EPS_STANDARD_PREVIEW, sizeof(UINT) );


USE_CROP_BOX

TRUE - use PDF crop box rectangle for page layout, FALSE - use PDF media rectangle for page layout.

Data type:

AT_BOOL

Valid Values:

True, False

Default Value:

True

Example:

// Get current value of USE_CROP_BOX control parameter
IG_fltr_ctrl_get(IG_FORMAT_POSTSCRIPT, "USE_CROP_BOX", FALSE,
NULL, NULL, (LPVOID)bUseCropBox, sizeof(bUseCropBox));
// Set new value to USE_CROP_BOX control parameter
IG_fltr_ctrl_set(IG_FORMAT_POSTSCRIPT, "USE_CROP_BOX",
(LPVOID)FALSE, sizeof(UINT));


WIDTH

This parameter determines the width of PS page to load.

Data type:

UINT

Default Value:

0

Valid Values:

Any positive value

Example:

// Get current value of WIDTH control parameter
IG_fltr_ctrl_get( IG_FORMAT_POSTSCRIPT, "WIDTH", FALSE, NULL,
NULL, (LPVOID)nDepth, sizeof(nDepth) );
// Set new value to the WIDTH control parameter
IG_fltr_ctrl_set( IG_FORMAT_POSTSCRIPT, "WIDTH", (LPVOID)1,
sizeof(UINT));


Using ImageGear Recognition Component

Using ImageGear Recognition Component1

The ImageGear Recognition component is a set of functions that provide access to ScanSoft's document recognition technology.

This core software module provides unsurpassed recognition accuracy for almost any document, including those produced on typewriters, dot-matrix printers, ink-jet printers, laser printers, and phototypesetters, as well as photocopied and faxed versions of any documents. It also allows for recognition of handwritten text, check marks and a veriety of bar codes.

Figure 1 below illustrates a simple application that takes a page image as input and produces recognized text in a variety of output formats.

Figure 1. Sample Application
1Portions of this document are excerpted from ScanSoft's OmniPage Capture SDK 12.5 reference materials. Copyright (c) 2004 ScanSoft, Inc. All rights reserved. ScanSoft is a trademark or registered trademark of ScanSoft, Inc. in the United States and other countries.


What the ImageGear Recognition component can do?

ImageGear's Recognition component enables you to build OCR applications for the Windows development environment. An application using the Recognition API can:

  • Accept as input any image file format supported by ImageGear.This image data can be binary, gray, or color.
  • Recognize a document image and export text in any format defined by ScanSoft SDK. These formats include 8-bit text, HTML, XML and Word processor formats such as MS Word or WordPerfect.
  • Select the language or languages of documents to be recognized. The list includes English, Eastern and Western European languages, Cyrillic based languages (Russian), the Baltic languages, Turkish and Greek. Documents with multiple languages can be recognized with accuracy because the API allows the application to specify the set of languages for recognition.
  • Learn, save, and (later) load character recognition data for similar documents. The software learns as a result of normal recognition, and acquires additional information by using the API's text verification system.
  • Enable end users to verify text during the recognition process.
  • Increase recognition accuracy with built-in and user-defined dictionaries.
  • Output confidence values for post-recognition processing.
  • Automatically segment the page to correctly recognize text on pages with complex or irregular layouts, including tables, reverse video, and line art as well.
  • Allow the user to manage delineate zones of a document page and then specify treatment for those zones. This includes the ability to correct the OCR engine's automatic segmentation between the segmentation phase and the recognition phase.
  • Process both text and graphics. The recognition software's ability to distinguish graphics from text can provide the basis of a compound document processing system.
  • Automatically detect fax, dot matrix, and other degraded documents and compensate accordingly.
  • Use the new scalable voting architecture that provides developers with 2 pre-made voting interfaces (OmniPage and PLUS) and direct access to 3 leading OCR engines (MOR, MTX and FireWorX).
  • Recognize handwritten text using a numbers only module or alphanumeric module.
  • Process questionnaries, educational tests and other form-like documents using the Optical Mark Recognition feature.
  • Recognize both 1D and 2D bar codes (provided that both BAR and BAR2D modules are licensed).


The ImageGear Recognition component and multi-threading

ImageGear OCR component is thread safe. Note however, that the underlying objects are process-global. It is application's responsibility to ensure that the objects are maintained correctly within all threads.

No reentrance is allowed withing the same thread. This can occur when the API is making an application defined callback. When the focus of control is in the application-defined callback, no API functions of the Recognition component can be called.


Working with the ImageGear Recognition component

The very first working code

Loading and recognizing the TEST1.TIF image file. The image contains English, machine-printed text. The result will be saved in the TEST1.TXT text file.

#include "i_Rec.h"
AT_ERRCOUNT nErrCount;
HIGEAR 	hIGear;
HIG_REC_IMAGE	hImg;
nErrCount = IG_comm_comp_attach("REC");
nErrCount = IG_REC_initialize();
nErrCount = IG_fltr_load_file("TEST1.TIF", 0, &hIGear );
nErrCount = IG_REC_image_import(hIGear, &hImg);
nErrCount = IG_REC_output_codepage_set("Windows ANSI");
nErrCount = IG_REC_output_level_set(DROPFORMAT);
nErrCount = IG_REC_output_format_set("Rec ASCII (StandardEx)");
nErrCount = IG_REC_image_recognize(hImg, NULL, FALSE);
nErrCount = IG_REC_output_convert_to_doc(NULL, "TEST1.TXT");
nErrCount = IG_REC_close();

Error handling

ImageGear Recognition component reports errors in the same way as other ImageGear components do. When an error occurs in the underlying ScanSoft's modules, ImageGear reports an error with error code IGE_REC_SCANSOFT_ERROR or IGW_REC_SCANSOFT_WARNING. You can use IG_err_record_get () function to obtain the original error code from ScanSoft's library.

Importing images into Recognition component

Recognition engine uses its own interal image storage. To supply recognition engine with input data, you should first load an image to ImageGear storage (HIGEAR). You can load images from any ImageGear supported image location, such as file, URL, or memory, or retrieve images from scanner. Then you can import the image into Recognition image storage (HIG_REC_IMAGE). Use the IG_REC_image_import () function for this.

If the source IGPage contains a grayscale image, the import method can convert the imported image to a bitonal one. If the source IGPage contains a color image, the import method can convert the imported image to grayscale or bitonal. The way this function will handle the different image types (such as bitonal, grayscale or color images) is called the primary color reduction mode. The reduction mode applied during the execution of this method is specified by the IG_REC_primary_reduction_mode_set () function.

Use the IG_REC_image_export () function to export the pixel data from HIG_REC_IMAGE to HIGEAR.

Note that pixel data are copied into HIG_REC_IMAGE object rather than shared between HIGEAR and HIG_REC_IMAGE. If you perform some preprocessing operation on the recognition page, and would like to access the modified image, for example, in order to display it, you'll need to export the image to a HIGEAR.


Preparing the image for recognition

This section consists of the following subsections:

  • Pre-processing the image
  • Pre-processing operations
  • Zones and images
  • Adding zones

Pre-processing the image

Before recognizing an image, SDK functions can be used to apply some image pre-processing procedures to enhance the quality of an image resulting in more accurate auto-zoning and recognition. This is typically done with the function IG_REC_image_preprocess (), which can include any or all of the following steps:

  • Inversion: automatic, programmed or none
  • Rotation: automatic, programmed or none
  • Deskewing: automatic, programmed or none

The following functions let you define the behavior of these image enhancement steps:

  • IG_REC_inversion_mode_set,
  • IG_REC_orientation_mode_set (),
  • IG_REC_deskew_mode_set () and IG_REC_slope_set ().

In addition to these three, sometimes, image despeckling and resolution enhancement are also performed internally to improve the success of the above transformations.

Example

Pre-processing an image to deskew it by a set value with the IG_REC_image_preprocess () function:

AT_ERRCOUNT rc;
HIG_REC_IMAGE hImg;
HIGEAR hIGear;
. . .
nErrCnt = IG_REC_image_import(hIGear, &hImg);
. . .
nErrCnt = IG_REC_deskew_mode_set(DSK_SET);
nErrCnt = IG_REC_slope_set(82);
nErrCnt = IG_REC_image_preprocess(hImg);
. . .
nErrCnt = IG_REC_image_delete(hImg);
. . .

The image pre-processing functions can also be called one by one. In your code you can use the inverting function (IG_REC_image_area_invert), the rotating function (IG_REC_image_orient ()) and the deskewing function (IG_REC_image_deskew ()). When the application calls any of these functions, the appropriate image enhancement step is immediately performed on the image and the result is available to both the recognition engine and the application. These functions do not have progress monitoring facilities. These separate functions must be used to invert only part of an image or to mirror an image.

Pre-processing operations

Here we summarize information on each image modification step:

  • INVERSION
  • DESKEWING
  • ROTATION and MIRRORING
  • DESPECKLING
  • RESOLUTION ENHANCEMENT

INVERSION

Image inversion can be done on any image (bitonal, grayscale or color) within the recognition engine's memory space. Recognition needs black or dark characters on a white or pale background.

The function RecInvertImgArea immediately inverts a whole single image - or a specified rectangle inside it. This function ignores the image inversion mode setting. The inverted image replaces the original one and is available to the recognition engine and the application.

An image inversion mode setting is made with IG_REC_image_invert (), taking values from IMG_INVERT. These are:

  • INV_AUTO: recognition engine examines image and inverts it if necessary (default).
  • INV_NO: No images are inverted.
  • INV_YES: All images are inverted.

This mode-induced inversion is performed when IG_REC_image_preprocess () is called and always acts on the whole image. The inverted image replaces the original one, it keeps its original type (bitonal, grayscale or color) and format and is available to the recognition engine and the application.

If auto-inversion is set (INV_AUTO), grayscale or color images undergo an implicit secondary conversion to create a clean bitonal image. If INV_AUTO and despeckle mode is ON for a bitonal image with over 280 dpi, a despeckled bitonal image is created. Detecting whether inversion is needed or not is done on the bitonal image - the despeckled one if available. These bitonal images are not available to the application. If the recognition engine decides inversion is needed, the whole original image is inverted.

DESKEWING

Image deskewing can be done on any image type (bitonal, grayscale or color), either automatically or with a programmed value. A deskewed image should increase auto-zoning and recognition accuracy.

The function IG_REC_image_deskew () immediately deskews a whole single image in the recognition engine's memory space by an amount defined in the function itself - up to 30 degrees. IG_REC_image_skew_detect () can be used to detect the amount of skew in an image.

IG_REC_image_deskew () ignores the deskewing mode setting IG_REC_deskew_mode_set () and the value given by IG_REC_slope_set (). The deskewed image replaces the original one, retaining its type and format, and is available to the recognition engine and the application.

A deskewing mode setting is made with IG_REC_deskew_mode_set (), taking values from IMG_DESKEW. These are:

  • DSK_SET: All images are deskewed by a given value, up to 30º.
  • DSK_NO: No images are deskewed.
  • DSK_AUTO: Skew up to 15º is auto-detected and removed (default).

The skew value to be applied for DSK_SET is defined with IG_REC_slope_set (). The value needed here can be obtained by IG_REC_image_skew_detect ().

This mode-induced deskewing is performed when IG_REC_image_preprocess() is called. The deskewed image replaces the original one; it keeps its original type and format and is available to the recognition engine and the application.

When DSK_AUTO is set, grayscale or color images undergo an implicit secondary conversion to create a clean but hidden bitonal image. If DSK_AUTO is set and despeckle mode is ON for a bitonal image with over 280 dpi, a hidden, despeckled bitonal image is created. Skew detection is done on the bitonal image - the despeckled one if available. These hidden bitonal images are not available to the application. The detected deskew value is applied to the original image.

ROTATION and MIRRORING

Image rotation in multiples of 90º can be done on any image type (bitonal, grayscale or color).

The function IG_REC_image_orient () immediately rotates and/or mirrors a whole single image in the recognition engine's memory space. Seven combinations of rotation and mirroring are available. This function ignores the image rotation mode setting of the recognition engine. The transformed image replaces the original one, keeping its type and format. It remains in the recognition engine's memory space, but is available to the application.

A rotation mode setting is made with IG_REC_orientation_mode_set (), taking values from IMG_ROTATE. These are:

  • ROT_LEFT: All images are rotated left by 90º.
  • ROT_RIGHT: All images are rotated right by 90º.
  • ROT_DOWN: All images are rotated by 180º.
  • ROT_AUTO: Images are examined and if necessary rotated (default).
  • ROT_NO: Rotation is not performed.

This mode-induced rotation is performed whenever IG_REC_image_preprocess() is called. When a fixed value is given (e.g. ROT_LEFT), the original image is rotated.

When ROT_AUTO is set, grayscale or color images undergo an implicit secondary conversion to create a clean bitonal image. If ROT_AUTO is set and despeckle mode is ON for a bitonal image with over 280 dpi, a despeckled bitonal image is created. Orientation detection is done on the bitonal image - the despeckled one if available. This bitonal image is not available to the application. The required rotation is performed on the original image. In both cases, the original rotated image remains in the recognition engine's memory space and is available to the application.

DESPECKLING

Image despeckling relates to bitonal images. These may be imported as bitonal or may be generated, explicitly or implicitly, from grayscale or color images. Image despeckling can improve the quality of auto-zoning, recognition and the automatic pre-processing transformations: the detection of inverted characters, skew and orientation is more reliable when run on a despeckled bitonal image.

The function IG_REC_image_despeckle () immediately despeckles a single bitonal image in the recognition engine's memory space. This functions independently of the despeckle mode setting and the resolution of the original image. The transformed image replaces the original one, keeping its format, and is available to the application.

An image despeckling mode setting is given by IG_REC_despeckle_mode_set (), with Boolean values TRUE and FALSE (default: TRUE). This mode setting influences bitonal images with a resolution of 280 dpi or greater. This mode setting is applied whenever any of the following functions are called:

  • IG_REC_zones_locate ()
  • IG_REC_image_recognize ()
  • IG_REC_image_preprocess () with DSK_AUTO, ROT_AUTO or INV_AUTO.

When a grayscale or color image is converted to bitonal, it usually results in a cleaned image. This can be influenced by the values in IG_REC_secondary_reduction_mode_set () and IG_REC_reduction_threshold_set ().

With these mode-induced transformations, the cleaned or despeckled bitonal image exists in parallel with the original one and is not available to the application.

RESOLUTION ENHANCEMENT

Resolution enhancement may be performed internally during image conversions. It involves a doubling of the resolution of a bitonal image resulting from an implicit secondary image conversion from grayscale or color. The doubling is performed on the basis of information available from the greater pixel depth in grayscale and color images. The resulting bitonal image exists in parallel with the original one, and is not available to the application.

The application has no control over when resolution doubling is done, only on whether and how it is done. The function IG_REC_res_enhancement_mode_set () accepts one of three settings from IMG_RESENH:

  • RE_YES: Forces resolution doubling in all cases,
  • RE_NO: Prohibits enhancement,
  • RE_AUTO: Enhances all images with 150 dpi or less (default).

Zones and images

A zone is a rectangular area in the image, up to full size, containing a feature of interest to the user. The image data covered by each zone is handled and processed (typically recognized) separately, according to zone-specific parameters. The zones of a HIG_REC_IMAGE image form a list, the zone list, which is attached to the image. The number of zones in the zone list can be examined at any time with the IG_REC_zones_count_get () function.

The characterizing attributes of a zone are the following:

  • size and position,
  • identifier of the zone (identifies the zone in the zone list),
  • type (determines the role of the zone in the image layout, i.e. Flowed text, Table or Graphic),
  • filling method (specifies the nature of the zone content, i.e. how the zone's area was supposed to be filled originally),
  • recognition method (the recognition module to be applied for the zone),
  • a Character Set filter,
  • what kind of checkings are enabled for the zone content,
  • User dictionary section assigned to the zone (for UD-checking),
  • user-written checking callback assigned to the zone.

The zone's filling method (fm) can take one of the following FILLINGMETHOD values:

  • FM_OMNIFONT: denotes machine printed text with any typeface, which is not too stylized.
  • FM_DRAFTDOT9: denotes a 9-pin draft dot-matrix printout.
  • FM_BARCODE: denotes a one-dimensional bar code within the zone.
  • FM_OMR: denotes a possible check-marking within the zone.
  • FM_HANDPRINT: denotes handprinting within the zone.
  • FM_DRAFTDOT24: denotes a 24-pin draft dot-matrix printout.
  • FM_OCRA: denotes OCR-A zone filling.
  • FM_OCRB: denotes OCR-B zone filling.
  • FM_MICR: denotes magnetic ink character filling.
  • FM_BARCODE2D: denotes 2D bar code zone filling.
  • FM_DOTDIGIT: denotes dot-digit zone filling.
  • FM_DASHDIGIT: denotes dash-digit zone filling.

There are two special filling methods worth mentioning separately:

  • FM_NO_OCR: denotes that no recognition should be attempted.
  • FM_DEFAULT, which allows a number of zones on the image to be handled together. For zones having this filling method the recognition engine will apply a common value according to the setting previously given with a separate call to the IG_REC_default_filling_method_set () function.

Adding zones

Zones can be added to a given image (to the zone list of the image, to be precise) in three different ways:

  • automatically (auto-zoning),
  • manually (by specifying the zone coordinates and zone attributes), or
  • from a storage file, called a zone file.
Auto-zoning

The automatic page-layout decomposition process (auto-zoning) can be activated directly by calling the IG_REC_zones_locate () function for finding text blocks on the image. It creates an entire zone list for the given image.

The IG_REC_zones_locate () function has a parameter that points to a structure containing the active area. This rectangle serves to limit the area inside which zones will be searched and defined.

The Capture SDK offers three different algorithms to be applied during auto-zoning: use the IG_REC_decomp_method_set () function to specify which Page parser algorithm setting should be applied during auto-zoning. This allows choosing between

  • the page parser algorithm introduced in the previous version of the toolkit (DCM_STANDARD),
  • the one incorporated in the earlier versions of the toolkit (DCM_LEGACY)
  • a third one called DCM_FAST, which is the quickest but not able to handle complex cases (including tables).

In addition the integrating application can set the zoning method to DCM_AUTO. With this setting, recognition engine determines the method to use. See IMG_DECOMP for details.

Applying the new DCM_STANDARD algorithm results in the best throughput in overall accuracy, though in some cases it might require significantly more time to complete.

When auto-zoning is used, each resulting zone is initialized with

  • a unique auto-assigned zone identifier,
  • the zone's detected coordinates,
  • the zone type determined (WT_FLOW, WT_TABLE or WT_GRAPHIC).

All zones created by this function will have

  • the default filling method FM_DEFAULT,
  • the automatic recognition module selection RM_AUTO setting,
  • the FILTER_DEFAULT Character Set filter, to specify the use of global filtering, if any.
  • none of the checking prohibit flags (e.g. CHK_LANGDICT_PROHIBIT) are set.

Any zone can be locally overridden with the IG_REC_zone_info_set () function, which allows you to change the attributes of a zone in the zone list.

Adding zones manually

In addition to, or instead of the automatic zone search, you can program your own zones. For adding zones to the zone list manually, the application calls the IG_REC_zone_insert () function. Related functions are: IG_REC_zone_delete (), IG_REC_zones_delete_all () and IG_REC_zone_info_set ().

Adding zones from a zone file

The third way of creating zones is by reading zones from a file (called a zone file) that contains the attributes of previously saved zones. An application can save the current zone definitions to a zone file any time with the IG_REC_zones_save () function. The application can load them from a zone file with the IG_REC_zones_load () function.

NOTE: When a zone file is loaded, any previous zones on the image are removed.

If the application calls the IG_REC_image_recognize () recognizing function on an image with an empty zone list, the page-layout decomposition function is called automatically.

Detecting tables without visible cell separators

Tables with visible gridlines (gridded tables) in an original page can usually be detected successfully by the auto-zoning function. In contrast, tables without visible cell separators in the original are harder to identify as tables, because they could equally well be word lists or data arranged in columns. The Capture SDK offers an algorithm for detecting such non-gridded tables more confidently. This feature can only be used in conjunction with an auto-zoning step. The non-gridded table detect algorithm is based on the result of the character recognition. This algorithm will run only if all the following conditions are met:

  • the zone list was created through auto-zoning,
  • there were no changes in the zone list (no zones were inserted or deleted)
  • none of the zones in zone list were updated by modifying the zone coordinates,
  • the feature is enabled through the IG_REC_decomp_nongridded_table_detect_set () function.

Defining a zone manually.

It contains uppercase letters only for multi-lingual omnifont recognition.

HIG_REC_IMAGE hImg;
HIGEAR hIGear;
ZONE zone;
. . .
nErrCnt = IG_REC_image_import(hIGear, &hImg);
memset(zone, 0, sizeof(ZONE));
zone.rect.left = 10;
zone.rect.top = 20;
zone.rect.right = 330;
zone.rect.bottom = 50;
// textual zone: it contains flowed text
zone.type = WT_FLOW;
 // Omnifont filling method was used to fill the zone's area
zone.fm = FM_OMNIFONT;
 // MOR recognition module will be applied for the zone's area
zone.rm = RM_OMNIFONT_MOR;
 // Character Set: only uppercase letters.
zone.filter = FILTER_UPPERCASE;
 // Insert the zone to the zone list
nErrCnt = IG_REC_zone_insert(hImg, &zone, 0);
. . .

To get information about any particular zone of the zone list of the image, the application can invoke the IG_REC_zone_info_get () function. This can be useful to find out more about the zones created by the auto-zoning function.

Zone manipulation: updating a zone.

HIGEAR hIGear;
HIG_REC_IMAGE hImg;
int nZone;
ZONE zone;
. . .
nErrCnt = IG_REC_image_import(hIGear, &hImg);
nErrCnt = RecLoadZones(hImg, "SAMPLE.ZON");
nErrCnt = IG_REC_zones_count_get(hImg, &nZone);
 // Get the first zone in the zone list
nErrCnt = IG_REC_zone_info_get(hImg, &zone, 0);
. . .
 // Adjust the left border of the zone by 10 pixels
zone.rect.left -= 10;
 // Zone content will be handled as a flow text
zone.type = WT_FLOW;
nErrCnt = IG_REC_zone_info_set(hImg, &zone, 0);
nErrCnt = IG_REC_zones_save("SAMPLE.ZON");.
. . .
IG_REC_image_recognize(hImg, "SAMPLE.RDF", FALSE);
 // result stored in the recognition data file
nErrCnt = IG_REC_output_codepage_set("Windows ANSI");
nErrCnt = IG_REC_output_level_set(DROPFORMAT);
nErrCnt = IG_REC_output_format_set("Text - Comma Delimited");
nErrCnt = IG_REC_output_convert_to_doc("SAMPLE.RDF",
"SAMPLE.csv");
NOTE: When updating a table-type zone with the IG_REC_zone_info_set() function, the "cell-detection" algorithm won't be activated, which will result in improper table detection within the zone.

The program can detect cells within a table-zone if you set the zone type to WT_FLOW first (followed by a IG_REC_zone_info_set () call) and then change the zone type to WT_TABLE (followed by a second IG_REC_zone_info_set () call).

Updating table zones.

HIGEAR hIGear;
HIG_REC_IMAGE hImg;
ZONE zone;
. . .
memset(&zone, 0, sizeof(ZONE));
zone.rect.bottom = 50;
zone.type = WT_TABLE;
zone.fm = FM_OMNIFONT;
zone.rm = RM_PLUS3W;
zone.filter = FILTER_ALL;
nErrCnt = IG_REC_zone_insert(hImg, &zone, 0);
// . . .
zone.rect.bottom = 40;
zone.type = WT_FLOW;
nErrCnt = IG_REC_zone_info_set(hImg, &zone, 0);
zone.type = WT_TABLE;
nErrCnt = IG_REC_zone_info_set(hImg, &zone, 0);


Recognition

This section consists of the following subsections:

  • Recognition modules
  • Recognition
  • Structured data output
  • OCR performance issues
  • Defining the Character Set
  • Recognized data kept in memory

Recognition modules

The ImageGear Recognition component can load a number of recognition modules: which ones are present depends on its configuration. You can program which one should run in a given zone, with the ZONE's attribute. This allows your application to perform "multi-module" recognition on any image.

The enum RECOGNITIONMODULE lists the possible recognition modules:

  • PLUS3W omnifont module for machine-printed text (default),
  • PLUS2W omnifont module for machine-printed text,
  • MTX omnifont module for machine-printed text,
  • MOR multi-lingual omnifont module for machine-printed text,
  • FRX multi-lingual omnifont module for machine-printed text,
  • HNR module for handprinted digits,
  • RER module for handprinted alphanumerical characters,
  • DOT module for 9-pin draft dot-matrix printouts,
  • OMR module for optical marks (checkmarks),
  • MAT matrix matching module,
  • BAR module for 1D bar codes.
  • BAR2D module for 2D bar codes.
NOTE: Two of these modules, the RER and BAR2D recognition modules are third-party components.

Corresponding to the above list, the rm field of any zone should contain one of the following recognition module IDs: RM_OMNIFONT_PLUS3W, RM_OMNIFONT_PLUS2W, RM_OMNIFONT_MTX, RM_OMNIFONT_MOR, RM_OMNIFONT_FRX, RM_HNR, RM_RER, RM_DOT, RM_OMR, RM_MAT, RM_BAR, RM_BAR2D or one of the two special ones: RM_NO_OCR and RM_AUTO. The RM_NO_OCR value means that no recognition will be done in the zone concerned.

RM_AUTO means that the recognition engine will choose the module most likely to be appropriate. It does this first of all by consulting the filling method set for the zone.

The filling method describes the type of data expected in the zone, e.g. a bar code, a handprinted or a machine generated text. A degree of auto-detection is available for filling method, with the IG_REC_image_filling_method_detect () function, useful when the precise filling method used on incoming documents may not be known in advance. It is the programmer's responsibility to specify a valid recognition module-filling method pair. Any incorrectly set zone will have no recognition result. Some filling methods can be linked successfully with one and only one recognition module (e.g. FM_OMR and RM_OMR). However, some recognition modules support more than one filling method, and some filling methods are accepted by more than one recognition module. For example, with mid-quality 9-pin dot-matrix text, either RM_DOT or one of the omnifont modules could give better results. With mid-quality 24-pin dot-matrix text, try RM_OMNIFONT_MOR with FM_DOTMATRIX24 and FM_OMNIFONT.

You can find detailed information on this and the different recognition modules in the Recognition module specifications.

RM_AUTO reads the filling method; if only one recognition module is suitable, it is used. When there is a choice, RM_AUTO uses various checks (character set, image size, etc.) to select the best one. Thus, it protects against an invalid FM-RM pair.

If the recognition module is not present when it is needed, the recognition function (IG_REC_image_recognize ()) returns with IGE_REC_SCANSOFT_ERROR / API_MODULEMISSING_ERR, and there will be no recognized data for the zone concerned. To avoid risk of this, we recommend checking the presence and correct installation of the necessary recognition modules by calling IG_REC_modules_info_get () just after the recognition component's initialization.

Recognition

The recognition process is initiated by the IG_REC_image_recognize () function.

The IG_REC_image_recognize () function processes the single image identified by its first hImg parameter. The function takes the zone list of the image or if it is empty, automatically calls the page-layout decomposition process (auto-zoning).

Internally this function operates on a bitonal image. If the hImg image is not a bitonal one or the Image despeckle mode setting is enabled, an implicit secondary image conversion step is performed automatically to create a secondary image. This implicit image conversion can be influenced with previous calls to the IG_REC_secondary_reduction_mode_set () and IG_REC_despeckle_mode_set () functions.

The IG_REC_image_recognize () function enumerates the zones in the zone list and activates the appropriate recognition modules for them. The recognition modules are given the calculated Character Set information zone by zone.

The second parameter of this call identifies where the recognition result should be placed. This can be either a file, called the recognition data file (recommended extension is RDF), or if a period or full-stop string (".") has been specified, the recognition result will be kept in memory (recognition data).

The RDF recognition data file is a binary one, containing all the recognized data including the recognized character codes, the position of the character on the image and different character formatting attributes (character size, bold, italic, underline, serif, sans serif, monospaced). The format of this file is not documented for the public. A separate IG_REC_output_convert_to_doc () call is necessary to make the recognized text available.

Calling IG_REC_image_recognize () repeatedly for different images with the same recognition data file argument appends the recognition data to that file. To recognize and output a multi-page document call IG_REC_output_convert_to_doc () only after all pages in the document have been recognized.

Recognizing a multi-page document.

int i;
int nPageCount;
HIGEAR hIGear;
HIG_REC_IMAGE hImg;
. . .
nErrCnt = IG_page_count_get(szFile, &nPageCount);
DeleteFile("MULTIPAG.RDF");
for (i = 0; i < nPageCount; i++) {
    nErrCnt = IG_REC_image_import(hIGear, &hImg);
    nErrCnt = IG_REC_image_preprocess(hImg);
    nErrCnt = IG_REC_image_recognize(hImg, "MULTIPAG.RDF",
FALSE);
}
// Specifies the file format for the final output document
nErrCnt = IG_REC_output_codepage_set("Windows ANSI");
nErrCnt = IG_REC_output_level_set(FULLFORMAT);
nErrCnt = IG_REC_output_format_set("Word 97, 2000, XP");
nErrCnt = IG_REC_output_convert_to_doc("MULTIPAG.RDF",
"MULTIPAG.DOC");
. . .

In this example the application specifies the output format (Word 97, 2000, XP) for the final output document (MULTIPAG.DOC) with the IG_REC_output_format_set() call. Then the multi-page result of the recognition stored in the recognition data file is converted into the requested format with the IG_REC_output_convert_to_doc() function call.

Then the IG_REC_image_recognize () function is called with the parameter NULL, the application doesn't have to care about the recognition data file: the recognition engine handles it internally (i.e. the default recognition data file is used automatically). However, this can be used only for single-page documents, since the default recognition data file is always deleted before a new recognition.

Recognizing a single-page document.

HIGEAR hIGear;
HIG_REC_IMAGE hImg;
. . .
. . .
nErrCnt = IG_REC_image_import(hIGear, &hImg);
nErrCnt = IG_REC_image_preprocess(hImg);
nErrCnt = IG_REC_image_recognize(hImg, NULL, FALSE);
nErrCnt = IG_REC_output_codepage_set("Windows ANSI");
nErrCnt = IG_REC_output_level_set(FULLFORMAT);
nErrCnt = IG_REC_output_format_set("Word 97, 2000, XP");
nErrCnt = IG_REC_output_convert_to_doc(NULL, "ONEPAGE.DOC");
. . .

Note the NULL value in the second parameter of the IG_REC_image_recognize () and the first parameter in the IG_REC_output_convert_to_doc () calls.

Structured data output

After recognition, the application can also access the recognition data as a structured data output with a call to the IG_REC_letters_get () function, which provides a LETTER structure memory output. (See the Recognized data kept in memory topic.)

Alternatively, the recognition data can be converted through the "2G Type 2" or "2G Type 3" converters into a final output document (Special Output Text Formats).

Any of these above also provides confidence information for the recognition as follows:

  • Confidence of the character recognition, and
  • Confidence of the space estimation (of the decision whether there is a space in front of the recognized character).

For more information, see also the Confidence reporting section.

OCR performance issues

There are different issues to be taken into account when you want to improve accuracy. Typically they also have consequences for the processing speed.

1. Image quality

This is one of the most important factors that influences accuracy. A resolution of 300 dpi or 400 dpi is best for recognition.

Use image preprocessing to enhance the quality of the given image to get more accurate auto-zoning and recognition.

Load grayscale or color images into the recognition engine without any conversion (CNV_NO) and combine this with image preprocessing in order to get more accurate output.

2. Auto-zoning algorithm to be applied

If auto-zoning is needed, use DCM_STANDARD, the most accurate page parser available in the recognition engine. Applying the DCM_STANDARD algorithm results in better throughput in overall accuracy, though in some complex cases it might require significantly more time to complete.

If processing speed is also important, consider using the algorithm DCM_LEGACY.

Finally, use DCM_FAST, when the processing speed has a higher priority than accuracy and the image content of the originals is simple enough (e.g. good quality letters without graphics or tables). In this case, it is recommended that the Non-gridded table detection algorithm be disabled (see: IG_REC_decomp_nongridded_table_detect_set ()).

3. Correct RM-FM choice

The most suitable filling method and recognition module should be specified, as described in the previous topic.

If more than one recognition module supports a given filling method, consider whether for your application it is better to specify the recognition module in your program rather than accept the setting selected by the recognition engine through the RM_AUTO option.

By choosing different combinations of the auto-zoning algorithm and specific recognition modules, 2-3 times faster recognition speed at the cost of increased error rate (1,5-2 times more errors) can be achieved.

For example, when speed is an issue, consider using RM_OMNIFONT_MTX, RM_OMNIFONT_FRX, RM_OMNIFONT_MOR, or RM_OMNIFONT_PLUS2W instead of the default omnifont module RM_OMNIFONT_PLUS3W.

4. Trade-off settings

These are set at page level, and determine how thorough the recognition should be, i.e. should more time be taken to try for higher accuracy. There are three possible values: TO_ACCURATE, TO_BALANCED, TO_FAST and these are passed to the IG_REC_tradeoff_set () function. For more details see Specifications for the recognition modules.

5. Module specific settings

The behavior, and hence accuracy, of some recognition modules can be influenced by separate module-specific settings.

  • bar code recognition: IG_REC_BAR_types_set (),
  • HNR module: IG_REC_HNR_params_set (), IG_REC_HNR_style_set (),
  • MOR, PLUS2W and PLUS3W modules: IG_REC_MOR_is_faxed_set (),
  • OMR module: IG_REC_OMR_params_set ().

BAR:

The bar code module auto-detects the bar code type. The IG_REC_BAR_types_set() function can be used to limit the acceptable choices. If it is certain that only one type will be used, it is possible to validate only that type. By default, five main types are enabled.

HNR:

Accuracy can be improved if the application can tell the module the precise location of characters (e.g. they occur in a structured form with comb or cell boxes). If this can't be done, the module will auto-detect their positions. It is also possible to specify European or American handprint styling. To recognize zones with hand printed numbers and no letters, consider choosing RM_HNR rather than RM_RER.

MOR, PLUS2W and PLUS3W:

For poor-quality fax output, the fax compensation switch IG_REC_MOR_is_faxed_set () can be used.

OMR:

This module has a setting to indicate whether checkbox borders will be visible or invisible in the loaded image. A value for mark sensitivity can also be given.

BAR, MAT and RER:

These modules can be influenced through an optional RM-specific parameter file. This allows settings not supported by the API to be communicated to these modules. (see the function IG_REC_module_spec_params_set ().)

In the Recognition module specifications each module has its own section Accuracy Issues.

6. Character Set

This determines at zone level which set of characters should be considered as valid. By eliminating characters that are known not to appear in the zone, accuracy can be improved. If non-validated character shapes are encountered in a zone, they are either replaced by the rejection symbol or forced to a similar-shaped validated character. A major component of the Character Set is the language choice. Setting the wrong language(s) and/or language dictionary (or leaving unneeded ones enabled) is likely to slow down recognition and reduce accuracy considerably. The steps for defining the Character Set are given (with examples) in a following section.

7. Training

The machine print recognition modules accept training files through the IG_REC_training_file_name_set () call. It's worth using a training file if there are some repeatedly misformed characters in a series of uniformly degraded documents, or the module repeatedly misreads a certain character.

8. The Checking subsystem

This consists of any combination of the following checking tools:

  • Spell checking (language-based checking),
  • User dictionary based checking (with words, strings or character patterns) or
  • User-written checking routines.

The Checking subsystem will find characters, words or zone contents that do not match program specified rules for that zone. It can be instructed either to only mark these occurrences, or be given permission to change them when it finds a sufficiently similar acceptable solution. See the forthcoming section (Improving recognition with the checking subsystem) for precise examples.

Character Set limitation and the Checking subsystem (CSS) both influence accuracy, but in different ways. Both, either or none of them can be used; the integrator should decide which balance is best. Their effects, when used separately, can be summarized as follows:

  • Limiting the Character Set: Recognition results outside the Character Set will not be used.
  • CSS with changes: Recognition results outside the CSS rules are less likely; both non-CSS solutions and changed items will be flagged.
  • CSS used without changing: Text appears as recognized, but non-CSS solutions will be flagged.

Limiting the Character Set gives the program greatest decision power, using the checking subsystem to only flag errors is safest, but requires more post-processing outside the recognition engine to check all non-conforming cases.

A typical balance would be to impose broad restrictions by limiting the Character Set, e.g. specifying the permissible languages, but using the checking subsystem for detailed control over parts of the recognized text where it's important that the original data be recognized and passed for checking precisely as it was written (e.g. for an ID Code incorporating a check-digit function). This later checking should make it possible to determine whether any error is due to optical recognition errors or was originally invalid.

Defining the Character Set

You can improve text recognition accuracy by narrowing the range of characters valid for recognition. This way the recognition engine doesn't always have to choose its solutions from all 500 characters in the recognition engine's Total Character Set. (The multi-lingual omnifont MOR recognition module supports all of these characters; other recognition modules recognize fewer of them.) The Character Set concept is documented in detail in the Character Set topic. Broadly, the Set is compiled as follows:

  • Language environment

This involves selecting one or more of the 114 available languages with the IG_REC_languages_set () function and optionally additional characters validated individually with the IG_REC_languagesplus_set function. Selecting only needed language(s) has a major impact. For example, selecting German only immediately INVALIDATES the Cyrillic and Greek alphabets and over 150 other unneeded accented letters. For a list of languages with their validated accented letters, see Languages and characters. For a list of accented letters and the languages which use them, see Characters, languages, modules. For an overview of the topic, see Introduction to language-related topics.

NOTE: If IG_REC_languages_set() is not called, the default is to enable the English alphabet.
  • Recognition module capabilities

Defining a recognition module for processing a zone may also restrict the available languages or characters within the Language environment. For example, RER cannot read Russian, and the HNR recognition module cannot process letters at all.

  • Filtering

The SDK provides filters (CHR_FILTER) to further narrow down the Character Set, by enabling only certain character classes, e.g. digits, uppercase letters etc. The value FILTER_ALL means no filtering.

  • Re-Expanding

An application may require exceptions to the filter rule. The most flexible way to re-expand the Character Set with individual characters after filtering is to specify them with a call to IG_REC_filterplus_set () and validate them with the FILTER_PLUS flag in the required zones.

  • Zone-level modification

In addition to the global, page-level definition of the Character Set, the choice of Recognition module, filling method, filtering and use of the expansion string can be fine-tuned on a local, zone level. Auto-located zones will be set to take the global filter settings. Manually created or modified zones may contain zone-level settings. Local filtering and expansion (with FILTER_PLUS) can be set in the zone's filter field. The possible local filter values are the same as the global ones, with an extra one: FILTER_DEFAULT. If this is the only one set, the zone inherits the global filter setting.

The following four examples illustrate various techniques for limiting the Character Set.

Recognition of a bi-lingual document (German and Spanish).

AT_ERRCOUNT rc;
int i;
. . .
LANG_ENA langs[LANG_SIZE];
for (i=0; i< LANG_SIZE; i++) langs[i] = LANG_DISABLED;
langs[LANG_GER] = LANG_ENABLED;
langs[LANG_SPA] = LANG_ENABLED;
nErrCnt = IG_REC_languages_set(langs);
nErrCnt = IG_REC_output_codepage_set("Windows ANSI");
nErrCnt = IG_REC_output_level_set(DROPFORMAT);
nErrCnt = IG_REC_output_format_set("Rec ASCII (StandardEx)");
nErrCnt = IG_REC_image_import(hIGear, &hImg);
nErrCnt = IG_REC_image_recognize(hImg, NULL, FALSE);
. . .

In the above example, the default recognition module (omnifont, unless specifically changed) will be assigned to all zones, as will the filter value FILTER_DEFAULT, i.e. there is no local modification of the Character Set.

The second example illustrates a rare case, such as you have a page containing zones with a very restricted number of characters to be recognized, e.g. in recognizing forms or multiple-choice test papers. In this case the application doesn't enable any language, but instead defines the few characters necessary as LanguagesPlus characters. This means there is no language selection and the Language environment consists solely of the individually defined LanguagesPlus characters. Also note that there is no filtering and no locally (zone) validated FilterPlus characters, in this case, the Language environment fully defines the Character Set and it will be valid for the defined zone, and for others inserted with an identical zone structure.

Character Set with no language selection: "a, A, b, B, c, C, d, D, e, E" as the only validated characters.

HIGEAR hIGear;
HIG_REC_IMAGE hImg;
int  i;
int  nZone;
ZONE zone;
LANG_ENA langs[LANG_SIZE];
. . .
for (i=0; i< LANG_SIZE; i++) langs[i] = LANG_DISABLED;
nErrCnt = IG_REC_languages_set(langs);
 // Specify the LanguagesPlus characters
nErrCnt = IG_REC_languagesplus_set(L"aAbBcCdDeE");
. . .
nErrCnt = IG_REC_image_import(hIGear, &hImg);
memset(&zone, 0, sizeof(ZONE));
zone.rect.left = 10;
zone.rect.top = 20;
zone.rect.right = 330;
zone.rect.bottom = 50;
zone.fm = FM_OMNIFONT;
zone.rm = RM_AUTO;
zone.filter = FILTER_ALL;
zone.type = WT_FLOW;
nErrCnt = IG_REC_zone_insert(hImg, &zone, 0);
. . .
nErrCnt = IG_REC_image_recognize(hImg, "PAGE1.RDF", FALSE);
. . .

In the above case the zone list is not empty, so the function IG_REC_image_recognize () will not perform auto-decomposition (auto-zoning), but will act on the inserted zone(s).

The third example will read a printed page in Hungarian, in which a Croatian town name appears repeatedly, containing the character "z-hacek" in lower and uppercase. The Windows Eastern Europe Code Page (1250), is needed as the current Code Page (and for export). The page includes a table containing numbers, which should be zoned separately for digits-only recognition.

In this example the Language environment is formed from the language selection (Hungarian) plus the two additional LanguagesPlus characters "z-hacek" and "Z-hacek". There is no global filter, but there is a local one, FILTER_DIGIT, defined for one zone.

Using language selection, LanguagesPlus characters and local filter.

HIGEAR hIGear;
HIG_REC_IMAGE hImg;
int  i, nZone;
char c;
auto WCHAR uni[256];
ZONE zone;
LANG_ENA langs[LANG_SIZE];
. . .
IG_REC_output_codepage_set("Windows Eastern"); // Code Page
1250
. . .
for (i=0; i< LANG_SIZE; i++) langs[i] = LANG_DISABLED;
langs[LANG_HUN] = LANG_ENABLED;
nErrCnt = IG_REC_languages_set(langs);
. . .
memset(uni, 0, sizeof(uni)); //only one wide character
terminating NULL is necessary
i=0;
c=0x9E; // Code of z-hacek in Code Page 1250
nErrCnt = IG_REC_util_convert_codepage_to_unicode(&c,
&uni[i++]);
c=0x8E; // Code of Z-hacek in Code Page 1250
nErrCnt = IG_REC_util_convert_codepage_to_unicode(&c,
&uni[i++]);
nErrCnt = IG_REC_languagesplus_set(uni);
. . .
nErrCnt = IG_REC_image_import(hIGear, &hImg);
nErrCnt = IG_REC_image_preprocess(hImg);
. . .
 // 1st zone contains a table with digits
memset(&zone, 0, sizeof(ZONE));
zone.rect.left = 10;      zone.rect.top = 20;
zone.rect.right = 330;    zone.rect.bottom = 50;
zone.fm = FM_OMNIFONT;    zone.rm = RM_OMNIFONT_MOR;
zone.filter = FILTER_DIGIT;
zone.type = WT_TABLE;
nErrCnt = IG_REC_zone_insert(hImg, &zone, 0);
 // 2nd zone contains flowed text without filtering
memset(&zone, 0, sizeof(ZONE));
zone.rect.left = 10;      zone.rect.top = 80;
zone.rect.right = 330;    zone.rect.bottom = 120;
zone.fm = FM_OMNIFONT;    zone.rm = RM_OMNIFONT_MOR;
zone.type = WT_FLOW;
zone.filter = FILTER_ALL;
nErrCnt = IG_REC_zone_insert(hImg, &zone, 1);
 // 3rd zone contains flowed text without filtering
 // etc.
. . .
nErrCnt = IG_REC_image_recognize(hImg, "PAGE1.TMP", FALSE);
nErrCnt = IG_REC_image_delete(hImg);
. . .

Multiple languages, global and local filters, FilterPlus characters

To read a page from a Luxembourgian newspaper, in which articles on a single page appear in French, German and Luxembourgian. The page contains six zones. The text contains no miscellaneous characters (mathematical symbols, etc.). Zone 5 contains uppercase letters only, with no digits, and only three punctuation characters: the comma, the period (full-stop) and a question mark. Zone 6 presents a currency conversion table containing the digits, the comma and the currency codes of Luxembourg and its neighbours: LUF, FRF, DEM, BEF and EUR.

The language selection is set to French, German and Luxembourgian. IG_REC_default_filter_set () is used to specify the global filter, to filter out only the 30 miscellaneous characters:

FILTER_ALPHA | FILTER_PUNCTUATION | FILTER_DIGIT.

A local filter is defined for zone 5:

FILTER_UPPERCASE | FILTER_PLUS.

A different local filter is defined for zone 6:

FILTER_DIGIT | FILTER_PLUS, or simply FILTER_NUMBERS.

These have the same effect.

The IG_REC_filterplus_set () is called to validate the FilterPlus characters needed in zone 5 and zone 6:

the comma, the period and the question mark and the currency letters, B D E F L M R U.

HIGEAR hIGear;
HIG_REC_IMAGE hImg;
int  i, nZone;
char c;
auto WCHAR uni[256];
ZONE zone;
LANG_ENA langs[LANG_SIZE];
. . .
IG_REC_output_codepage_set("Windows ANSI"); // Code Page 1252
for (i=0; i< LANG_SIZE; i++)
    langs[i] = LANG_DISABLED;
langs[LANG_FRE] = LANG_ENABLED;
langs[LANG_GER] = LANG_ENABLED;
langs[LANG_LUX] = LANG_ENABLED;
nErrCnt = IG_REC_languages_set(langs);
nErrCnt = IG_REC_default_filter_set((CHR_FILTER)(FILTER_ALPHA |
FILTER_PUNCTUATION | FILTER_DIGIT));
. . .
nErrCnt = IG_REC_image_import(hIGear, &hImg);
nErrCnt = IG_REC_image_preprocess(hImg);
. . .
 // 1-4 zones
. . .
 // 5th zone
memset(&zone, 0, sizeof(ZONE));
zone.rect.left = 10;      zone.rect.top = 420;
zone.rect.right = 330;    zone.rect.bottom = 450;
zone.fm = FM_OMNIFONT;    zone.rm = RM_OMNIFONT_MOR;
zone.filter = (CHR_FILTER)(FILTER_UPPERCASE | FILTER_PLUS);
zone.type = WT_FLOW;
nErrCnt = IG_REC_zone_insert(hImg, &zone, 4);
 // 6th zone
memset(&zone, 0, sizeof(ZONE));
zone.rect.left = 10;      zone.rect.top = 80;
zone.rect.right = 330;    zone.rect.bottom = 120;
zone.fm = FM_OMNIFONT;    zone.rm = RM_OMNIFONT_MOR;
zone.type = WT_FLOW;
zone.filter = (CHR_FILTER)(FILTER_DIGIT | FILTER_PLUS);
nErrCnt = IG_REC_zone_insert(hImg, &zone, 5);
. . .
 // Function call to specify the FilterPlus characters
nErrCnt = IG_REC_filterplus_set(L"BDEFLMRU.,?");
. . .
nErrCnt = IG_REC_image_recognize(hImg, "LUXEMB.RDF", FALSE);
nErrCnt = IG_REC_image_delete(hImg);
. . .

To summarize, the Character Set for each zone was:

  • Zones 1-4: Globally defined: All unaccented letters plus all accented letters needed for the three specified languages, plus all digits and punctuation.
  • Zone 5: Locally defined: All uppercase unaccented letters plus three accented ones, plus the period, comma, and question mark. (The letters BDEFLMRU were doubly validated; that doesn't matter).
  • Zone 6: Locally defined: The digits, the letters BDEFLMRU, the comma and (superfluously) the period and question mark.

The IG_REC_is_char_enabled () function can be used to inquire whether a given character is validated for the current page by its Language environment and FilterPlus.

Recognized data kept in memory

Either the recognized data or the converted recognized output can be kept in memory. The recognized data of an image can be stored in memory if the IG_REC_image_recognize () function has been called with a period or full-stop (".") parameter. In this case the application can access the recognized data with a IG_REC_letters_get ()functions call. The recognized data will be available as an array of LETTER structures providing significantly more information than the character code itself. This occupies 36 bytes for each recognized character, and this type of output offers the most detailed information on the recognition.

Since this function creates a new memory object containing the recognized data, after having evaluated (processed) the result, the application should call the IG_REC_letters_free() function to free this memory area.

The application can slightly change the recognized data before converting it to a recognition data file. The IG_REC_letters_set () function can be used to update the recognized data belonging to the hImg image. Be careful, modify only those fields whose change is necessary!

Before the application uses the converting service of IG_REC_output_convert_to_doc(), a call to IG_REC_RDFile_write () must be made to convert the recognized data to a recognition data file.

Note that you can keep not only the recognized data in memory, i.e. the result of the IG_REC_image_recognize () call, but also the final output document, which is the converted recognized output of the IG_REC_output_convert_to_doc call. For doing so the conversion function should be called with a a period or full-stop (".") parameter.


Checking

This section consists of the following subsections:

  • Improving accuracy with the checking subsystem
  • Applying checking
  • Preparing / maintaining the User dictionary

Improving accuracy with the checking subsystem

The checking subsystem is mainly used to achieve better accuracy in the recognized output text and/or to make proofing more effective. Its services are closely integrated into the recognition process, they are activated internally either during the recognition (by some recognition modules) or immediately after the recognition process. That is why all the checking related settings have to be set BEFORE calling the IG_REC_image_recognize () function.

The checking subsystem consists of the following three independent parts:

  • Spell checking: using language-specific dictionary elements,
  • UD-checking: checking against the User dictionary (with words, strings or patterns),
  • User-written checking: using user-written callback functions.

Any combination of these parts is possible during the recognition process as steps in determining the acceptability of words. Note that the use of these checkings can still be enabled or disabled separately at zone level.

Spell checking

Spell checking uses third-party language-specific spell checkers. There are two kinds of the spell checkers:

  • Language dictionaries ("language checking"), and
  • Vertical dictionaries ("vertical language checking").

The Capture SDK is delivered with seventeen different Language dictionaries (English, German, Dutch, Polish, Russian etc.). These are generic language dictionaries; they contain between 100,000 and 200,000 entries.

Vertical dictionaries apply to special professions and in the toolkit they can be treated as extensions to the Language dictionaries, though they can even be used when no Language dictionary is specified.

The Capture SDK is delivered with 8 different Vertical dictionaries for two professions (medical and legal) in four languages (English, German, French and Dutch).

Specifying the Spelling language (Language dictionary) and/or a Vertical dictionary is page-level setting. Once a Language dictionary has been specified, the language checking will be applied to all zones on the page, unless their CHK_LANGDICT_PROHIBIT flag is set.

Similarly, once a Vertical dictionary has been specified, the vertical language checking will be applied to all zones on the page, unless their CHK_VERTDICT_PROHIBIT flag is set.

Recognizing Dutch legal texts.

char legaldut[] = "LEGAL_DUT.dmd"
nErrCnt = IG_REC_spelling_language_set(LANG_DUT);
nErrCnt = IG_REC_vertical_dict_set(legaldut);
. . .

UD-checking

The checking subsystem also makes use of a User dictionary. A User dictionary is a collection of user-specific elements, the so-called UDitems. UDitems can be of two types: literal strings, usually words (as in the case of any wordprocessor's user dictionary) or regular expressions. A string being checked will be accepted if it conforms to at least one item in the specified section of the User dictionary. A regular expression defines a pattern, range or class of characters, either singly or as a group. When an item is a regular expression, it means that during the UD-checking, strings passed for checking by a recognition module will be checked to see whether they conform to the pattern defined by the regular expression.

In the following example regular expressions will be applied to check whether the recognized strings comply with post or zip code formats used mostly in Europe or in the US.

Adding literal and regular expression UDitems to the User dictionary.

LPCSTR sect1[] = "ZIP_Section";
LPCWSTR item_literal[] = L"AccuSoft";
// US postal zip code: 12345 or 12345-67890
LPCWSTR US_postal_zip[]  = L"\d{5}(-\d{5})?";
// European postal code: D-12345 or H-1234
LPCWSTR European_postal_zip[]  = L"[A-Z]-\d{4,5}";
// This assumes the UD is already open for maintenance
nErrCnt = RecAddItem(sect1, item_literal, 0);
nErrCnt = RecAddItem(sect1, US_postal_zip, UI_REGEXP);
nErrCnt = RecAddItem(sect1, European_postal_zip, UI_REGEXP);
. . .

Within the User dictionary the UDitems can be organized under different sections. Zones are always associated with a section of the User dictionary when they are created.

There can be different situations when it is worth doing an UD-checking.

If the application uses spell checking and it consistently encounters words marked as uncertain that are spelled correctly, or it is known that the document contains many proper nouns, the application can reduce unwanted marking and improve recognition accuracy by performing UD-checking, to supplement the spell checking (assuming that the User dictionary has been prepared previously by adding the required words to it). In this case the UD-checking is complementary to the spell checking.

UD-checking without spell checking enabled is typically used in form-like applications (e.g. questionnaires), i.e. where the data to be recognized is highly structured and follows predictable patterns.

Specifying the User dictionary file itself is a page-level setting. Once it is specified, it will be applied to all zones on the page. However, since the User dictionary may have several sections, each to be assigned to the different zones, different sets of dictionary items can be used for the different zones. For particular zones the UD-checking can be disabled with the CHK_USERDICT_PROHIBIT flag.

User-written checking

User-written checking is performed through CHECKWORD_CB user-written callback function by the integrating application. When creating or updating a zone, the chk_fn field of the zone may contain the address of such a function. During recognition, when it is called, the user-written function is passed the string to be checked and the index of the zone (which the string to be checked derives from). The user-written function should evaluate the string, knowing the pattern of permissible zone content. Its opinion on the recognized string's acceptability should be expressed with one of the five values from the CHECKWORDRETURNCODE enum.

Applying checking

The most important API function in controlling the checking subsystem is the IG_REC_spelling_is_enabled_set function. This function is used to enable or disable the running of the checking subsystem.

If it is enabled (default=enabled), the correction of non-compliant words can be enabled or disabled. For this, the IG_REC_correction_is_enabled_set ()/ IG_REC_spelling_language_set () function is used. If correction is disabled, non-compliant and suspicious words are flagged, but no auto-correction is done. When enabled, all these unchanged words are flagged, while some characters may be changed and are marked as changed. Correction is the default so the application needs to call this function only when it wants to explicitly disable the word correction feature.

The remaining checking-related API functions are specific to the particular checking system.

Spell checking

The Spelling languages available in the current recognition engine configuration can be enumerated with the IG_REC_spelling_language_first_get (), IG_REC_spelling_language_next_get () and the IG_REC_spelling_language_next_get ()/IG_REC_vertical_dict_set () function-pair. The application can specify a language setting as the Spelling language, valid for the next page or pages with the IG_REC_spelling_language_set () subroutine.

Additionally, vertical language checking can also be activated when one of the Vertical dictionaries (e.g. LEGAL_GER.DMD) has been set through the IG_REC_vertical_dict_set() call.

Configuring the checking subsystem to use English spell checking.

AT_ERRCOUNT rc;
. . .
nErrCnt = IG_REC_spelling_is_enabled_set(TRUE);
nErrCnt = IG_REC_correction_is_enabled_set(TRUE);
nErrCnt = IG_REC_spelling_language_set(LANG_ENG);
. . .
nErrCnt = IG_REC_image_recognize(hImg, "ENGTEXT.RDF", FALSE);

When the Spelling language is set to LANG_NO, or when it specifies a language, for which there is no Language dictionary, the language checking will not be activated for the zones of the page.

Spell checking with automatic spell language selection

In the special (default) case, when the specified Spelling language is set to LANG_AUTO, the language checking will be performed based on the recognition language selection (IG_REC_languages_set ()) as follows:

  • If the recognition language selection is empty, there won't be language checking.
  • If one recognition language has been set, that language will be automatically selected for language checking assuming that the appropriate Language dictionary is available.
  • If two or more languages are selected for recognition, language checking will be done for all selected languages, for which a Language dictionary is available.

UD-checking

The prerequisites for checking with a User dictionary are

  • a properly prepared User dictionary file,
  • a call to IG_REC_UD_set () and
  • zones referring to sections in the User dictionary (if not the default section of the User dictionary is required).

The checking subsystem can handle two kinds of User dictionaries: native dictionary files (created or updated by a previous IG_REC_UD_save () call), and word-list file. The way of preparing a native User dictionary file is given in the next topic. A word-list file is a text file; it contains words, one in each line.

Before recognition, the IG_REC_UD_set() function must be called with the name of the User dictionary file and also with a section name. This section name defines the default section in the User dictionary. The items under this section will be "used" by any ZONE in the zone list, whose chk_sect field contains an empty string. (Note that the auto-zoning function always creates zones with an empty string in this field.) Other sections in the User dictionary can be referred to by name. In this case, for those zones where it is needed, the chk_sect field must contain the section name. This way different zones on a page can be UD-checked with different sections. A zone will be subject to UD-checking only if the CHK_USERDICT_PROHIBIT flag of its chk_control field is off.

Configuring the checking subsystem to enable UD-checking.

AT_ERRCOUNT rc;
. . .
nErrCnt = IG_REC_spelling_is_enabled_set(TRUE);
nErrCnt = IG_REC_correction_is_enabled_set(TRUE);
nErrCnt = IG_REC_UD_set("MYWORDS.DCT", "DEFSECT");
. . .
nErrCnt = IG_REC_image_recognize(hImg, "FOD.RDF", FALSE);

After recognition, the chk_control field of the zones might be updated by one of the flags CHK_LANGDICT_USED, CHK_USERDICT_USED, CHK_CHECKCBF_USED or CHK_VERTDICT_USED.

Preparing / maintaining the User dictionary

Compiling and changing a User dictionary requires that the application specify a User dictionary file with the IG_REC_UD_set() function followed by a call to the IG_REC_UD_edit_open () function. At this point the content of the User dictionary can be listed, and items can be added or removed on request until IG_REC_UD_edit_close () is called.

The IG_REC_UD_state_get () function can be used to learn whether there has been any change since the User dictionary was last opened for maintenance.

Changes can be made permanent by calling the IG_REC_UD_save() function.

A new User dictionary can be created by calling the IG_REC_UD_set() function with a NULL parameter, followed by a IG_REC_UD_save() call as follows.

Creating a new User dictionary. Adding UDitems to it.

AT_ERRCOUNT rc;
char userdict[] = "NEW_USER.DICT";
char sectA[] = "Section_A";
LPCWSTR item1[] = L"Peabody";
LPCWSTR item2[] = L"Budapest";
nErrCnt = IG_REC_UD_set(NULL, NULL);
nErrCnt = IG_REC_UD_edit_open();
nErrCnt = IG_REC_UD_item_add(sectA, item1, 0);
nErrCnt = IG_REC_UD_item_add(sectA, item2, 0);
nErrCnt = IG_REC_UD_save(userdict);
nErrCnt = IG_REC_UD_edit_close();
. . .

Sections in the currently opened User dictionary can be enumerated with the IG_REC_UD_section_first_get (), IG_REC_UD_section_next_get () function-pair.

Ditems (the elements or entries) of the currently opened User dictionary can be enumerated with the IG_REC_UD_item_first_get (), IG_REC_UD_item_next_get () function-pair. These functions list the UDitems belonging to the specified section of the User dictionary with their attribute(s). The UI_REGEXP attribute denotes that the item is a regular expression.

Elements can be added to the User dictionary with the IG_REC_UD_item_add () function. When adding a new UDitem with a non-existing section specified, the section will be automatically created. Existing UDitems can be deleted from the User dictionary with the IG_REC_UD_item_delete () function. Sections are automatically removed as soon as their last UD item is deleted.

Maintaining an existing User dictionary.

AT_ERRCOUNT rc;
BOOL bChanged;
char userdict[] = "USER1.DICT";
char sectA[] = "Section_A";
char sectB[] = "Section_B";
LPCWSTR item1[] = L"Peabody";
LPCWSTR item2[] = L"Peabody";
LPCWSTR item3[] = L"Budapest";
nErrCnt = IG_REC_UD_set(userdict, sectB);
nErrCnt = IG_REC_UD_edit_open();
nErrCnt = IG_REC_UD_item_add(sectB, item1, 0);
nErrCnt = IG_REC_UD_item_add(sectB, item3, 0);
nErrCnt = IG_REC_UD_item_delete(sectA, item2, 0);
. . .
nErrCnt = IG_REC_UD_state_get(bChanged);
if (bChanged == TRUE)
    nErrCnt = IG_REC_UD_save();
nErrCnt = IG_REC_UD_edit_close();
. . .
NOTE: A User Dictionary that has been opened with IG_REC_UD_edit_open() must be closed with IG_REC_UD_edit_close() before any function that performs recognition (e.g. IG_REC_image_recognize()).


The Output

This section consists of the following subsections:

  • Code pages
  • Exporting to the final output document
  • Format retention in final output documents
  • Embedded images in final output documents
  • Confidence reporting
  • Progress indication
  • Processing statistics

Code pages

One of the recognition engine's settings is its Code Page setting, which can be set and/or inquired with the functions IG_REC_output_codepage_set () and IG_REC_output_codepage_get (), respectively.

Recognized characters are stored internally in the recognition engine in their UNICODE representation. The current Code Page is taken into account either when converting a character to/from this UNICODE representation, or when converting the recognition data to the final output document. The first needs to be done with the IG_REC_util_convert_codepage_to_unicode () or IG_REC_util_convert_unicode_to_codepage () calls.

The IG_REC_util_convert_codepage_to_unicode () function is useful when a RECapi API function requires a UNICODE character or character string parameter, and you know only the character code in your target Code Page.

When the IG_REC_output_convert_to_doc () function is called, it performs character code conversions from UNICODE into the current Code Page setting of the recognition engine while producing the final output document.

In most cases, the Code Page setting of the recognition engine must be specified together with the Output Text Format for the final output document. While some output converters ignore the Code Page setting, others, typically the text converters, apply it during their running.

The current Code Page setting should be able to express all characters validated for recognition (i.e. the Character Set). You can use the IG_REC_output_codepage_check () function to decide whether the current Code Page fulfills this requirement.

The IG_REC_output_codepage_first_get () and the IG_REC_output_codepage_next_get () function-pair can be used to enumerate the list of available Code Pages.

Enumerating the list of available Code Pages.

char aCodepage[32];
AT_ERRCOUNT rc;
. . .
nErrCnt = IG_REC_output_codepage_first_get(aCodepage,
sizeof(aCodepage));
do {
    printf("Codepage: %s"\n, aCodepage);
    nErrCnt = IG_REC_output_codepage_next_get(aCodepage,
sizeof(aCodepage);
} while (rc == REC_OK);
. . .

There can be conflicts between the set of characters validated for recognition (i.e. the Character Set) and the Code Page selection; a selected Code Page may not support some characters. For example, if you select the Hungarian language and the current Code Page is Windows ANSI (Code Page 1252), the final output document will not contain some accented characters for that language. Use the IG_REC_output_codepage_check function to check whether the current Code Page setting contains all the characters of the current Language environment (language selection, the LanguagesPlus characters), and any characters listed as FilterPlus characters. The output of IG_REC_output_codepage_check () is a string of characters not supported by the current Code Page (non-supported characters).

If the language and Code Page settings are such that there are non-supported characters when output conversion is performed, the recognition engine tries to replace non-supported characters with somewhat similar shaped ones in the final output document. This substitution does not work in all cases; mainly it is good for replacing non-supported accented characters with un-accented ones. The final output document will contain a missing symbol in the place of characters, which were recognized correctly but could not be either exported or substituted.

The application can call IG_REC_output_missing_symbol_set () to define, which character from the current Code Page should be used to indicate a missing symbol.

Exporting to the final output document

After having successfully recognized the image (or a series of images), a IG_REC_output_convert_to_doc () call converts the recognition data file into the final output document. The Code Page, format of the final output document and the level of format retention should be specified by prior calls to the functions IG_REC_output_codepage_set (), IG_REC_output_format_set () and IG_REC_output_level_set (), respectively. The full list of supported output formats is given in the topic Output Text Format Lists.

To check whether a requested output format is available in the current Recognition component's configuration, enumerate the list of output formats with the IG_REC_output_format_first_get () and the IG_REC_output_format_next_get () function-pair. You can get more information about any of the installed output text format converters with IG_REC_output_format_info_get (), which provides this information in the OUTPUTCONVERTERINFO structure.

Enumerating the available output text file formats.

char aFormat[32];
AT_ERRCOUNT rc;
OUTPUTCONVERTERINFO cnv_info;
. . .
nErrCnt = IG_REC_output_format_first_get(aFormat,
sizeof(aFormat));
do {
    nErrCnt = IG_REC_output_format_info_get(aFormat, &cnv_info);
    printf("Text Format: %s", aFormat);
    printf("Default file extension: %s", cnv_info.Ext);
    nErrCnt = IG_REC_output_format_next_get(aFormat,
sizeof(aFormat);
} while ((rc != REC_OK) && (rc != TMP_NOMORE_WARN));
. . .

It is also possible to transfer the recognized text stored in the final output document into a memory location instead of storing it into a file. To do this, the application has to invoke the IG_REC_output_convert_to_doc () with a period or full-stop string ("."), instead of a real output filename. The application gets access to the recognized output by calling the IG_REC_output_text_get () function. Later, the IG_REC_output_text_delete () function needs to be called by the application to free the memory object containing the recognized output.

Transferring the recognized text to a memory location.

HIGEAR hIGear;
HIG_REC_IMAGE hImg;
BYTE *pText;
long  sText;
. . .
nErrCnt = IG_REC_image_import(hIGear, &hImg);
nErrCnt = IG_REC_image_preprocess(hImg);
nErrCnt = IG_REC_zones_locate(hImg, NULL);
nErrCnt = IG_REC_image_recognize(hImg, NULL, FALSE);
nErrCnt = IG_REC_output_codepage_set("Windows ANSI");
nErrCnt = IG_REC_output_format_set("Rec ASCII (StandardEx)");
nErrCnt = IG_REC_output_convert_to_doc(NULL, ".");
nErrCnt = IG_REC_output_text_get(&pText, &sText);
. . .
nErrCnt = IG_REC_output_text_delete();
. . .

In some cases the application may need to access the recognized information on a per-character basis. For this structured data output, you can either use the LETTER structure, which is the direct memory output of the IG_REC_image_recognize () function, or you can use either the "2G Type 2" or the "2G Type 3" output format. These latter file formats are created by a IG_REC_output_convert_to_doc () call. They are documented in the section Special Output Text Formats.

The LETTER structure can only be accessed immediately after recognition so IG_REC_image_recognize () must be used with one page being processed at a time.

Format retention in final output documents

If you select an advanced word processor as the output text format for the final output document (i.e. Microsoft Word, etc.), you may want the recognition engine to pass as much formatting information as it can collect from a document to make the layout result similar to the original one. The application can control the amount of formatting details passed to the word processor by the IG_REC_output_param_get () function. Since it has to be called with four rather complicated structures (OUTDOCUMENT, OUTPARAGRAPH and OUTCHARACTER, OUTMARK) filled in by the application, a shortcut is available with the function IG_REC_output_level_set (). This provides for selection from four pre-defined format detail levels:

  • FULLFORMAT,
  • PARTFORMAT,
  • DROPFORMAT,

These settings express the degree of the format retention in the final output document. With DROPFORMAT, only the character code information is passed to the output. If PARTFORMAT has been specified, character and paragraph formatting information are also added to the output. The FULLFORMAT setting results in all formatting being retained, including the text zoning, which is converted to frames in the output document. You can find the default output property settings for these pre-defined values in the comment part of the function IG_REC_output_level_set ().

The recommended way of specifying formatting properties is as follows:

  • specify the OUTPUTLEVEL closest to your formatting requirements, using IG_REC_output_level_set (),
  • call IG_REC_output_param_get () to fill four structures with the formatting properties defined by the Format level specified in the previous call,
  • change any fields in these structure variables, as required,
  • call this IG_REC_output_param_get () function to validate your changes.

In the final output document not all possible formatting features can be used, since either they are not applicable or they were not implemented for that particular converter. For example, specifying the page margins in conjunction with a text output converter won't have any effect. The converters implement the various output formatting features as described in the Output converter formatting properties topic.

In the example below, FULLFORMAT is specified, so the PaperSize setting is AUTO, that is, the output page size will be equal to the input size. The example forces a given page size setting, by changing AUTO to PREDFEFINED and specifying OUT_A4 in the nPaperSize.

Validating formatting properties for the final output document.

OUTDOCUMENT  outdocu;
OUTPARAGRAPH outpara;
OUTCHARACTER outchar;
OUTMARK      outmark;
. . .
nErrCnt = IG_REC_output_level_set(FULLFORMAT);
nErrCnt = IG_REC_output_param_get(&outdocu, &outpara, &outchar,
&outmark);
 // Force A4 output papersize
outdocu.PaperSize = OUT_PREDEFINED;
outdocu.nPaperSize = OUT_A4;
outdocu.nOrientation = OUT_PORTRAIT;
nErrCnt = IG_REC_output_param_get(&outdocu, &outpara, &outchar,
&outmark);
nErrCnt = IG_REC_output_codepage_set("Windows ANSI");
nErrCnt = IG_REC_output_format_set("Word 97, 2000, XP");
nErrCnt = IG_REC_output_convert_to_doc("TEMPINTR.RDF",
"FINALOUT.DOC");
. . .

It is also possible to place marking characters in the final output document. These can mark suspect characters or words or transmit character position information from the original document. These marking characters can be placed regardless of the format level setting. They can be controlled through the OUTMARK structure.

Suspect characters and/or words can be denoted by color, if the final output document supports that. They can also be marked by a user-defined character placed just before each suspect character or word.

Character position information is given by inserted user-defined characters. This marking can signal line, table-row, paragraph, zone, and page boundaries.

Embedded images in final output documents

The Recognition component is able to export images to the final output document for the graphics zones. This is called the Retain Graphics feature.

Recognized document output with embedded image requires the following steps:

  • Import the image to the HIG_REC_IMAGE.
  • Perform the image pre-processing step on the image, if necessary.
  • Call the IG_REC_image_recognize () function to perform recognition and save the recognition data file, passing TRUE to the bKeepGraphics parameter.
  • Set either FULLFORMAT or PARTFORMAT, or specify the Retain Graphics feature directly through the IG_REC_output_param_set () call.
  • Call IG_REC_output_codepage_set () to specify the Code Page for the output
  • Call IG_REC_output_format_set () to specify an appropriate output text format for the final output document. (i.e. one that supports text and graphics).
  • Call the IG_REC_output_convert_to_doc () function.

To set the Retain Graphics feature directly, the RetainGraphics field of the OUTDOCUMENT variable should be set to any OUTPUTGRAPHICS value, except OUT_NONEGR.

If the HIG_REC_IMAGE image is a color or a grayscale one, the embedded image type depends on what kind of OUTPUTGRAPHICS value has been validated for the RetainGraphics field.

If OUT_ORIGINAL is specified, which is the default for FULLFORMAT or PARTFORMAT, the image parts (graphical zones) will be embedded into the final output document from the original image, without any conversion. If the RetainGraphics field is set to OUT_BW, the final output document will contain bitonal images, independently from the type of the hImg image. Further possible values are: OUT_GRAY, OUT_COLOR.

Confidence reporting

For some applications, it may be important to know the reliability of the recognized text. These applications may require having additional confidence information for the recognized characters and/or words.

The Recognition component can provide confidence information for the correctness of the recognized text in two different ways:

  • The output-marking feature (see: OUTMARK structure) enables the IG_REC_output_convert_to_doc () function to place a user-defined character sequence into the final output document before suspiciously recognized characters and/or words. Alternatively, the suspicious characters and/or words can be set to a particular color in the output document to indicate recognition results with low confidence.
  • In another approach, the recognition engine can generate output, which consists of structured data for each recognized character. In this output there is one structure or record for each character. The character code of the recognized entity is the primary field. Other fields include the coordinates of the character on the image, the zone to which the character belongs to, the font information for the character, and the confidence information.

The output-marking feature is supported by most of the output converters. Marking low confidence recognition with color requires the selection of an output format (e.g. MS Word) that supports colored text.

For more information on these converters, see the Output converter formatting properties topic.

A possible output for the marking feature might be as follows:

"We would like to ask you some questions, ta*king around 15 minutes"

The text extract above was generated using the output-marking feature, in which the asterisk ('*') character was set to mark the suspiciously recognized characters in the output.

Structured recognized output can be produced though one of the two special output converters (e.g. "2G Type 3"). Even more information can be retrieved directly into application memory by a call to the IG_REC_letters_get () function, just after issuing the IG_REC_image_recognize () call. The IG_REC_letters_get() call provides the most detailed information about the recognized data: it results in a 36-byte long LETTER structure for each recognized character. Whereas the 2G Type output formats provide 2nd guesses for each character the LETTER structure provides three.

There are two fields in the LETTER structure, which provide character recognition confidence information: the err and the spaceErr fields.

  • The err field is a combined value. Its most significant bit is used to express the certainty/uncertainty of the word. (The word is uncertain, if this bit set to 1). The remaining bits express the certainty of the recognition of the character, which ranges between 0 and 100. A value of zero (0) means that the recognition engine recognized the character with high confidence. In some cases a word may have some or all characters that are individually suspicious but the characters are not be marked suspicious in the word bit. This is usually a result of language or user dictionary checking. It means the word was validated by the checking subsystem.
  • The spaceErr field ranges between 0 and 100, and it expresses the confidence of the value in the space field of the structure, i.e. whether the recognition engine is certain regarding the space estimation in front of the recognized character.

Applications that examine the character confidence information can use a threshold value, above which the character value is treated as a suspicious result. A value of 64 is recommended for this purpose. A value less than 64 will indicate that the character was recognized with high confidence. A value of 64 or greater marks that code is suspicious.NOTE!

This value (64) is also used internally in the same manner when the output-marking feature for suspicious characters in the output text is enabled.

NOTE: The confidence reporting system works best when all three recognition modules are used in the voting scheme (RM_OMNIFONT_PLUS3W). If other machine print recognition modules are used (RM_OMNIFONT_PLUS2W, RM_OMNIFONT_MTX, etc) then confidence information is still available, but the ability of the system to properly report confidence will be reduced. This will result in a higher level of false negative and false positive reporting of suspicious recognition results.

Progress indication

Typically the most time-consuming processes invoked by the Recognition component are the recognition processes (PID_RECOGNITION1, PID_RECOGNITION2, and PID_RECOGNITION3) and the final output document generation (PID_WRITEFOUTDOC). In some particular cases, other processes like image loading (PID_IMGINPUT) or image preprocessing (PID_IMGPREPROCESS) might also take considerable time.

Sometimes it is advisable to provide the application user with feedback about these processes. The application can register a callback procedure for progress monitoring with the IG_REC_progress_CB_register () function. The Recognition component will invoke the registered callback procedure during processing with a pointer to a PROGRESSMONITOR structure containing information about the current process. The application can provide progress indication with this procedure. If the callback function returns a value other than REC_OK, it signals an interruption of the current process. This can be used to provide the application user with a cancel button.

The ProcessId field of the PROGRESSMONITOR structure identifies the current process. (e.g. PID_DECOMPOSITION, PID_WRITEFOUTDOC etc.) The Percent member provides the progress information for the ProcessId process.

If the current session includes one of the two recognition processes, the iChrNumber and iChrRejected fields provide the number of recognized and rejected characters up to that point on the page being processed. This feature can be used to alert the user, or even some automatic monitoring code, that recognition accuracy has fallen below some predefined level.

The ObjectContent field contains a sample from the recognized characters (approx. 30-80).

Sample callback function for progress monitoring.

AT_ERRCOUNT RECAPI ProgressMon(LPPROGRESSMONITOR mon)
{
  int id = (int)mon->ProcessId;
  char *strProcNames[NUMOFPROCESSES] =
  {"IMAGEINPUT","IMAGESAVE", etc...};
  wsprintf(aTmp, "Process: %s %d%%", strProcNames[id], mon-
>Percent);
  if (mon->ObjectSize >0) {
    wchar_t *s = (wchar_t *)mon->ObjectContent;
    // as points to UNICODE text, conversion might be
necessary...
  }
  if (keypressed() == TRUE) {
    return API_PROCESS_ABORTED_ERR;
  }
  return REC_OK;
}
. . .
 // register callback function
. . .
nErrCnt = IG_REC_progress_CB_register(ProgressMon);
nErrCnt = IG_REC_image_import(hIGear, &hImg);
 // calls to process and recognize the image etc.
. . .

Processing statistics

The integrating application can retrieve timing and other statistical information about the last accessed image. This includes

  • time used to load the image in the recognition engine's memory space,
  • time used for pre-processing the image, if any,
  • time used for auto-zoning of the image, if any,
  • time that the image spent in the different recognition modules during recognition, if any,
  • recognition time measured till producing the recognition result,
  • number of recognized characters on the image,
  • number of recognized words on the image,
  • number of rejected characters on the image,
  • number of recognized words on the image corrected by the checking subsystem (CSS).

The application calls IG_REC_statistics_get () for this purpose. The fields of the STATISTIC structure will be filled with the relevant information on return.

The function can be called during any phase of the processing. The time for any processes (from PROCESSID) that has not run contain zero (0). Similarly, if no recognition has been performed when the statistic function is called, each relevant field of the STATISTIC structure contains zero (0).

All timing data is measured in milliseconds.

Processing statistics of an image.

AT_ERRCOUNT rc;
int nChar, nWord, nRej;
int nSTime, nPTime, nLTime, nRTime;
HIGEAR hIGear;
HIG_REC_IMAGE hImg;
STATISTIC stat;
. . .
nErrCnt = IG_REC_image_import(hIGear, &hImg);             // ->
iScanTime
nErrCnt = IG_REC_image_preprocess(hImg);        // ->
iPreprocTime
nErrCnt = IG_REC_zones_locate(hImg, NULL);    // -> iDecompTime
nErrCnt = IG_REC_image_recognize(hImg, "TMP.RDF", FALSE); // ->
iReadingTime, iRecognitionTime
nErrCnt = IG_REC_output_convert_to_doc("TMP.RDF", "FOD.DOC"); /
/ -> no stat. info
nErrCnt = IG_REC_image_delete(hImg);
nErrCnt = IG_REC_statistics_get(&stat);
nChar = stat.iChrNumber;   // Number of recognized characters
nWord = stat.iWordNumber;  // Number of recognized words
nRej = stat.iChrRejected;  // Number of rejected characters
nSTime = stat.iScanTime;   // Image loading time
nPTime = stat.iPreprocTime;// Image pre-processing time
nLTime = stat.iDecompTime; // Time necessary for auto-zoning of
the image.
nRTime = stat.iReadingTime;// Recognition time
. . .


Using ImageGear Twain Component

TWAIN was developed by a consortium of software and hardware manufacturers to standardize the communication between software applications and image acquisition devices. The interface is optimized for acquisition of graphic images. The TWAIN standard is widely supported by scanner manufacturers, with the widely used version of TWAIN being 1.9 (as of this writing). In addition to scanners, TWAIN is being used with digital cameras and video capture boards. ImageGear supports all three TWAIN Transfer Modes: Native Data Transfer Mode (which is the TWAIN default), Disk File Transfer, and Buffered Memory.

A TWAIN-compliant image acquisition device is one whose device driver complies with TWAIN specification. The device driver understands the TWAIN protocol, thus allowing interaction with the Data Source Manager, the main interface module of the TWAIN software. The Data Source Manager "manages the session" between the application program and the raster-generating data source. Three software elements work together in TWAIN: the application, the Data Source (DS), and the Data Source Manager (DSM) as shown below:

This section uses the following terminology when discussing ImageGear scanning functionality:

  • Data Source: This is a shortened reference to the device driver of an Image Acquisition Device and will be used frequently.
  • Data Source Manager: The TWAIN manager for the device drivers.
  • Image Acquisition Device: This term covers all devices that acquire images using the TWAIN protocol, including scanners.
  • Scanner: This word is sometimes used as an alternative for "Data Source" when the discussion is specific to scanners but is not relevant to all Image Acquisition Devices, or "Data Sources".
  • Scanning: This term refers in a general sense to all methods of TWAIN image acquisition. See the "TWAIN Scanning Capabilities" for details.


TWAIN Scanning Functions Overview

The following are brief descriptions some of ImageGear's TWAIN scanning functions.

There are also scan callbacks, DS enumeration, scan capability queries, and scan GUI functions that are not currently discussed at any length in this chapter. For information on these functions, refer to TWAIN Component API Function Reference Chapter.

IG_TWAIN_CB_register ()
This function registers one of the seven available scan callback functions.
IG_TWAIN_driver_info_get ()
This function returns the major and minor release version numbers of the TWAIN-compliant image acquisition device.
IG_TWAIN_source_get_default ()
This function returns the name of the current or "default" Data Source.
IG_TWAIN_source_get_first ()
This function returns the name of the first Data Source detected.
IG_TWAIN_source_get_next ()
This function returns the name of the next Data Source detected.
IG_TWAIN_source_open ()
This function loads the specified Data Source into main memory and causes its initialization.
IG_TWAIN_source_close ()
This function closes the currently opened Data Source.
IG_TWAIN_cap_get ()
This function gets information about a capability from a Data Source.
IG_TWAIN_cap_set ()
This function sets or resets the current value of a capability.
IG_TWAIN_cap_create ()
This function creates a new capability container.
IG_TWAIN_cap_delete ()
This function deletes a capability container and frees all resources associated with it.
IG_TWAIN_cap_is_valid ()
This function checks whether the handle to a capability container is valid.
IG_TWAIN_cap_id_get ()
This function gets the numeric designator of a capability from its container.
IG_TWAIN_cap_container_type_get ()
This function gets the type of a capability container.
IG_TWAIN_cap_item_type_get ()
This function gets the data type of a capability from its container.
IG_TWAIN_cap_reset ()
This function changes the id and item type of a capability and reallocates the container's memory according to the new item type.
IG_TWAIN_cap_value_get ()
This function gets the value of a capability from its container. Applicable to TW_ON_ONEVALUE container.
IG_TWAIN_cap_value_set ()
This function sets the value of a capability in its container. Applicable to TW_ON_ONEVALUE container.
IG_TWAIN_cap_array_size_get ()
This function gets the size of the array of a capability. Applicable to TW_ON_ARRAY and TW_ON_ENUMERATION containers.
IG_TWAIN_cap_array_value_get ()
This function gets an element of the array of a capability. Applicable to TW_ON_ARRAY and TW_ON_ENUMERATION containers.
IG_TWAIN_cap_array_value_set ()
This function sets an element of the array of a capability. Applicable to TW_ON_ARRAY and TW_ON_ENUMERATION containers.
IG_TWAIN_cap_array_value_add ()
This function adds an element to the end of the array of a capability. Applicable to TW_ON_ARRAY and TW_ON_ENUMERATION containers.
IG_TWAIN_cap_current_value_get ()
This function gets the current value of a capability from its container. Applicable to TW_ON_ENUMERATION and TW_ON_RANGE containers.
IG_TWAIN_cap_current_value_set ()
This function sets the current value of a capability in its container. Applicable to TW_ON_ENUMERATION and TW_ON_RANGE containers.
IG_TWAIN_cap_default_value_get ()
This function gets the default value of a capability from its container. Applicable to TW_ON_ENUMERATION and TW_ON_RANGE containers.
IG_TWAIN_cap_default_value_set ()
This function sets the default value of a capability in its container. Applicable to TW_ON_ENUMERATION and TW_ON_RANGE containers.
IG_TWAIN_cap_min_value_get ()
This function gets the minimum value of a capability from its container. Applicable to TW_ON_RANGE container.
IG_TWAIN_cap_min_value_set ()
This function sets the minimum value of a capability in its container. Applicable to TW_ON_RANGE container.
IG_TWAIN_cap_max_value_get ()
This function gets the maximum value of a capability from its container. Applicable to TW_ON_RANGE container.
IG_TWAIN_cap_max_value_set ()
This function sets the maximum value of a capability in its container. Applicable to TW_ON_RANGE container.
IG_TWAIN_cap_step_value_get ()
This function gets the step value of a capability from its container. Applicable to TW_ON_RANGE container.
IG_TWAIN_cap_step_value_set ()
This function sets the step value of a capability in its container. Applicable to TW_ON_RANGE container.
IG_TWAIN_acquire ()
This function acquires a single image from the selected TWAIN device.
IG_TWAIN_scan_pages_to_file ()
This function scans multiple pages from a scanner equipped with an Automatic Document Feeder (ADF).
IG_TWAIN_scan_pages ()
This function scans multiple pages from a scanner equipped with an Automatic Document Feeder (ADF).
IG_TWAIN_preview ()
This function acquires preview images from the selected TWAIN device.
IG_TWAIN_auto_capture ()
This function automatically captures images from the selected TWAIN device.
IG_TWAIN_file_change_dir ()
This function selects the current device within the Data Source (camera, storage, etc).
IG_TWAIN_file_copy ()
This function copies the specified file from one directory to another.
IG_TWAIN_file_create_dir ()
This function creates a new directory within the current directory.
IG_TWAIN_file_delete ()
This function deletes a file or directory on the device.
IG_TWAIN_file_format_media ()
This function formats the specified storage.
IG_TWAIN_file_rename ()
This function renames (and optionally moves) a file or directory.
IG_TWAIN_file_info_get ()
This function gets information about the requested file.
IG_TWAIN_file_get_first ()
This function gets the first filename in a directory and returns information about that file.
IG_TWAIN_file_get_next ()
This function gets the next filename in a directory, and returns information about that file.
IG_TWAIN_file_close ()
This function closes the previously open file system context.
IG_TWAIN_file_get_image ()
This function retrieves the image that the device's file system context currently points to.
IG_TWAIN_ctrl_get ()
This function gets the value of a TWAIN control parameter.
IG_TWAIN_ctrl_set ()
This function sets the value of a TWAIN control parameter.
LPFNIG_TWAIN_...
ImageGear's scan callbacks begin with this prefix. See "API Function Reference" for descriptions.


Scanning Using ImageGear

The flexibility that ImageGear gives you in working with TWAIN warrants a small introduction. This introduction provides an overview of all of the ways in which you may shape your sessions with TWAIN. The steps involved are listed below, with the details for each step provided later in the section:

  • Opening the Source
  • Setting the TWAIN Image Acquisition Mode
  • Setting the Filename and Format Type for Disk File Transfer
  • Verifying the TWAIN Version
  • Controlling the Scanning Capabilities and Other Options
  • Scanning and Acquiring Pages

Opening the Source

Before the application performs any scanning operation, the user is offered a list of available scanning devices from which to choose, in the event that there is more than one. IG_TWAIN_source_open() will display the TWAIN Select Source dialog box with a list of available scanning devices, as shown below:

The call to this function is straightforward:

// Select TWAIN device from which to acquire an image
nErrCount = IG_TWAIN_source_open(hMainWnd, NULL, TRUE);
if (nErrCount == IGE_SUCCESS)
bIsSourceOpen = TRUE;
NOTE: Call this function before calling any other TWAIN functions.

You can create your own dialog box for Data Source selection by using the DS enumeration API, all of which include "source" in their names. Call IG_TWAIN_source_get_first (), then IG_TWAIN_source_get_next () with a loop to detect all available devices. Use IG_TWAIN_source_open () to open the source selected by the end user. See TWAIN Component API Function Reference for detailed descriptions on the API. See also TWAIN.c file, included in your Sample directory, for an implementation of a dialog box using these functions.

Setting the TWAIN Image Acquisition Mode

There are three acquisition modes in TWAIN:

  • Native: ImageGear will load the entire image into memory as one continuous data stream.
  • Disk File Transfer: The Data Source will save the acquired image directly to a file. ImageGear gives you control over setting the filename and file format to be used in Setting the Filename and Format Type for Disk File Transfer.
  • Buffered Memory Transfer: The data will be loaded into memory (as for Native Transfer) except that it will be buffered and optionally compressed. This allows you to mimimize memory requirements which is especially useful when scanning high-resolution images.
NOTE: Remember that not all of the TWAIN-supported transfer syntax modes are supported by all Data Sources. If you try to use an acquisition mode that your device does not support, you will receive an error message.

Tell ImageGear the transfer mode to use with the function IG_TWAIN_cap_set ()

  • To set the transfer syntax to Disk File Transfer:
HTWAINCAP hTWAINCap = (HTWAINCAP)NULL;
DWORD dwXferMode = IG_TW_SX_FILE;
nErrCount = IG_TWAIN_cap_create(IG_TW_ICAP_XFERMECH,
IG_TW_ON_ONEVALUE,
AM_TID_META_UINT16, &hTWAINCap);
nErrCount = IG_TWAIN_cap_value_set(hTWAINCap,
(LPCVOID)dwXferMode,
sizeof(dwXferMode));
nErrCount = IG_TWAIN_cap_set(hTWAINCap, IG_TW_MSG_SET);
IG_TWAIN_cap_delete(hTWAINCap);
  • To set the transfer syntax to Buffered Memory:
HTWAINCAP hTWAINCap = (HTWAINCAP)NULL;
DWORD dwXferMode = IG_TW_SX_MEMORY;
nErrCount = IG_TWAIN_cap_create(IG_TW_ICAP_XFERMECH,
IG_TW_ON_ONEVALUE,
AM_TID_META_UINT16, &hTWAINCap);
nErrCount = IG_TWAIN_cap_value_set(hTWAINCap,
(LPCVOID)dwXferMode,
sizeof(dwXferMode));
nErrCount = IG_TWAIN_cap_set(hTWAINCap, IG_TW_MSG_SET);
IG_TWAIN_cap_delete(hTWAINCap);
  • To set the transfer syntax to Native:
HTWAINCAP hTWAINCap = (HTWAINCAP)NULL;
DWORD dwXferMode = IG_TW_SX_NATIVE;
nErrCount = IG_TWAIN_cap_create(IG_TW_ICAP_XFERMECH,
IG_TW_ON_ONEVALUE,
AM_TID_META_UINT16, &hTWAINCap);
nErrCount = IG_TWAIN_cap_value_set(hTWAINCap,
(LPCVOID)dwXferMode,
sizeof(dwXferMode));
nErrCount = IG_TWAIN_cap_set(hTWAINCap, IG_TW_MSG_SET);
IG_TWAIN_cap_delete(hTWAINCap);

By default, if no call is made to set transfer mode, ImageGear will use the mode set in Data Source.

Setting the Filename and Format Type for Disk File Transfer

When the Disk File Transfer mode is used, the Data Source will save an image directly to a file. You must use the TWAIN capabilities to set all parameters involved in using Disk File Transfer. To do this, use the IG_TWAIN_cap_set () and IG_TWAIN_ctrl_set () functions. Below are two sample calls. The first sets the filename to "myfile.tif"; the second sets the file format to TIFF.

IG_TWAIN_ctrl_set(IG_TW_CTRL_IMAGE_FILE_NAME, "myfile.tif",
strlen("myfile.tif"));
HTWAINCAP hTWAINCap = (HTWAINCAP)NULL;
AT_LMODE nFileFormat = IG_FORMAT_TIF;
nErrCount = IG_TWAIN_cap_create(IG_TW_ICAP_IMAGEFILEFORMAT,
IG_TW_ON_ONEVALUE,
AM_TID_META_UINT16, &hTWAINCap);
nErrCount = IG_TWAIN_cap_value_set(hTWAINCap,
(LPCVOID)nFileFormat,
sizeof(nFileFormat));
nErrCount = IG_TWAIN_cap_set(hTWAINCap, IG_TW_MSG_SET);
IG_TWAIN_cap_delete(hTWAINCap);
NOTE: Your choice of which file format to use for an image that is acquired and stored directly to a file is limited by two factors: (1) The file formats supported by your Scanner's Device Driver, (2) The file formats supported by TWAIN.

The following formats are supported by TWAIN for image acquisition devices: TIFF, PICT, BMP, XBM, JPEG, FPX, PNG. Therefore, if you are using the Disk File Transfer, you are restricted to using a format that is both supported by TWAIN and supported by your Data Source.

If you do not specify a filename, the path to the temporary Windows directory will be used.

NOTE: Remember that not all TWAIN-supported file formats are supported by all TWAIN- compliant Data Sources. If your Data Source does not support the file format that you specify, ImageGear will return an error.

For additional information about using the Disk File Transfer syntax see the section entitled Using Disk File Transfer and IG_TWAIN_acquire().

Verifying the TWAIN Version

The TWAIN version may be verified by using the function IG_TWAIN_driver_info_get (). This function returns two integer values: one for the major release number, and the other for the minor release number. The example code provided with your product includes a call to this function.

Controlling the Scanning Capabilities and Other Options

The function used to set scanning capabilities is IG_TWAIN_cap_set (), which was briefly described at the beginning of this scanning discussion.

You have already seen that used in prior sections to set the filename and format for an image acquired using Disk File Transfer mode. However, there are many other capabilities that can be set using that function, including bit depth and layout. There are restrictions on which capabilities can be used based on the hardware that you are using, the transfer mode setting, and the ImageGear function that you call.

See Also:

Appendix: TWAIN Scanning Capabilities

Scanning and Acquiring Pages

In general, IG_TWAIN_acquire () is used to scan a single image from the flatbed area of the scanner, while IG_TWAIN_scan_pages () and IG_TWAIN_scan_pages_to_file () are used to scan any number of pages from an automatic document feeder (ADF), which is an optional scanner accessory.

The key difference between these functions is that IG_TWAIN_acquire () scans a single image to a DIB in memory (unless the Disk File Transfer mode is used), while IG_TWAIN_scan_pages () can scan one or more pages and IG_TWAIN_scan_pages_to_file () saves your images to disk.

See Also:

Using the User Interface (UI)

Using Disk File Transfer and IG_TWAIN_acquire()

Using the User Interface (UI)

You should decide when using IG_TWAIN_acquire (), IG_TWAIN_scan_pages () or IG_TWAIN_scan_pages_to_file () whether or not to display the Data Source User-Interface dialog box (UI). The UI, which is supplied by the scanner manufacturer, allows the user to preview the image, select the portion of the image to be acquired, and to set those controls that specify image characteristics particular to the device in use. Setting the parameter bShowUI to TRUE allows the UI displaying, while setting it to FALSE disables the display. The UI specific to the Hewlett-Packard ScanJet 4c scanner is shown on the picture below:

If you set bShowUI to FALSE, you can still set the device capabilities by including a call to IG_TWAIN_cap_set (). This may actually be preferable to using the UI, because it can offer you more control in some cases.

The following example code demonstrates using IG_TWAIN_acquire () with the UI displayed, and also shows a call to IG_TWAIN_driver_info_get ().

INT nTwainVerMajor, nTwainVerMinor;      /*rlease versions */
HIGEAR        hImage;                     /* returned ImageGear
handle */
HWND          hWnd;                      /* App's active window
handle */
AT_ERRCOUNT   nErrCount;                  /* # of errors on the
stack */
BOOL          bShowUI;                   /* whether to show UI
box */
char          cBuf[140];
bShowUI = TRUE;
/* get version information */
nErrCount = IG_TWAIN_driver_info_get(&nTwainVerMajor,
&nTwainVerMinor);
if (nErrCount == IGE_SUCCESS)
{
wsprintf(szBuf, " TWAIN Working Group\n\n"
"Aldus, Caere, Eastman Kodak,\n"
"Hewlett-Packard, and Logitech\n\n"
" Version %d.%d",
nTwainVerMajor, nTwainVerMinor);
MessageBox(hWnd, szBuf, "TWAIN Protocol", MB_ICONINFORMATION);
}
nErrCount = IG_TWAIN_acquire(&hIGear, bShowUI);

If you are scanning with IG_TWAIN_scan_pages () or IG_TWAIN_scan_pages_to_file () and have set bShowUI to TRUE, be aware that the UI box will only appear once (before the first page is scanned). But the settings you make with the UI box will be applied to all pages scanned during this session.

NOTE: IG_TWAIN_scan_pages_to_file() can save to any of the file formats supported by ImageGear (unless you are using the Disk File Transfer Syntax mode). TIFF is the most commonly used file format for storing multi-page documents when using the ADF. However, any of the supported formats that store one image per file, such as Windows Bitmap (BMP), can also be used for scanning multiple pages. A separate file will be created for each image. For example, if you name a 3-page file PICTURE.BMP, three files will be created (one for each image), and their names will be: PICTURE1.BMP, PICTURE2.BMP, PICTURE3.BMP. If you are using the Disk File Transfer mode (which directly saves acquired images to disk files), your choice of formats is restricted to those supported by both TWAIN and your device. As of this writing, TWAIN supports TIFF, PICT, BMP, XBM, JPEG, FPX, PNG.

Using Disk File Transfer and IG_TWAIN_acquire()

IG_TWAIN_acquire () can be used with any of the TWAIN transfer modes. If you use Buffered Memory or Native, the file is scanned into memory and assigned a HIGEAR handle; if you use Disk File Transfer mode, the image is stored directly to disk. As described in the section Setting the Filename and Format Type for Disk File Transfer, when acquiring an image using the Disk File Transfer syntax, the image acquired is stored to the specified file with the specified file format type. To set the filename when using the Disk File Transfer mode, use the function IG_TWAIN_ctrl_set ().

Formatting Scanned Image

Calling IG_TWAIN_acquire () results in the creation of a DIB to hold your acquired image, and it returns an ImageGear HIGEAR handle. Use IG_save_file () or IG_fltr_save_file () to save the image to a disk file using any of the writable format types supported by ImageGear. See Saving Images and Using Format Filters API for Image Saving for more information.

If you scan multiple pages using IG_TWAIN_scan_pages_to_file (), in combination with the Native or Buffered Memory transfer modes, the images are saved directly to a disk file with the format specified by the nFileFormat parameter. If the chosen format supports storage of multiple images, one file will be created; if the chosen format supports storage of one image per file, a separate file will be created for each image scanned from the ADF.

You can force ImageGear to save pages separately even for multi-page formats using the setting IG_TW_CTRL_SAVE_PAGES_SEPARATELY with IG_TWAIN_ctrl_set (). For instructions on saving a file to a different file formats, see the sections entitled Saving Images and Using Format Filters API for Image Saving.

You can also refer to TWAIN Component API Function Reference for descriptions of scanning functions.

NOTE: 24-bit color images can be large. If, for example, you have an image that is 5" x 7", with a resolution of 300 dpi at 24 bits per pixel, your uncompressed image will be about 9 megabytes in size.

12-bit Gray Level Scanning

You can use ImageGear to scan 12-bit gray level images from Vidar and Lumisys X-ray digitizers using TWAIN interface.


Understanding Bitmap Images

This chapter provides an introduction to the workings of the bitmap. It includes descriptions of:

  • Pixels
  • Channels
  • Color Spaces
  • 24-bit RGB Images
  • 1-bit Images
  • 4-bit and 8-bit Images
  • Grayscale Images
  • Color Values Used During Display
  • Device-Independent Bitmaps (DIB)
  • Device-Dependent Bitmaps (DDBs)
  • Vector Images


Pixels

The pixel (or "picture element") is the basic building block of all images displayed by ImageGear. On a display screen, each pixel is a dot. In memory, the pixel is stored as a sequence of bits that determine what color the displayed pixel is. There can also be other data associated with the pixel.


Channels

An image is made up of one or more channels. For each pixel in the image, there are channel values for all of the image's channels. ImageGear supports the following channel types:

  • Color channel - channel value describes a pixel's color. The number of color channels in an image is determined by the image's color space. For example, an RGB image has three color channels, one for each color component: red, green, and blue. CMYK has four color channels, and grayscale has only one.
  • Alpha channel - channel value describes how much a pixel should be blended with another pixel during an alpha blending operation. In ImageGear, an image can have only one alpha channel, which can contain either non-premultiplied (as in PNG) or premultiplied (as in TIFF) alpha values. Also, only images with RGB or grayscale color channels can have alpha channels.
  • Extra channel - extra data associated with the image on a per-pixel basis. For example, if an image being loaded contains multiple alpha channels, the first alpha channel will be loaded as the image's alpha channel, and the others will be loaded as extra channels. Extra channels are maintained in the image but do not contribute to display or alpha blending operations.

Each channel has a bit depth associated with it. This is the number of bits used to represent a value for the channel. This bit depth can be up to 32 bits on 32-bit platforms and up to 64 bits on 64-bit platforms. It is possible to have an image with multiple channels that differ in bit depth. For example, you could have an RGB image with 8 bits per color channel and a 1-bit alpha channel. Or you could have a 5-6-5 RGB image with 5 bits for red and blue channels and 6 bits for the green channel.

NOTE: Previous versions of ImageGear stored alpha channels as separate, associated images. ImageGear now stores all channel values together for each pixel in an image.


Color Spaces

A color space in ImageGear describes the channels present in an image. The most important part of this description is the color channel configuration. This includes how many color channels there are and how these channels are used to describe colors, which is the usual informal concept of a color space. For example, in the RGB color space there are three channels (red, green, blue) whose values are combined to form colors. In the indexed color space there is one channel which consists of index values into an associated color palette.

In ImageGear, the concept of a color space is extended to also include information about other types of channels besides color, such as alpha and extra channels. An ImageGear color space ID is a bit field which can combine values from the enumIGColorSpaceIDs enumeration defined in accucnst.h.

For example,

  • A simple RGB image would be:

IG_COLOR_SPACE_ID_RGB

  • A grayscale image with an alpha channel and no extra channels would be:

IG_COLOR_SPACE_ID_Gy | IG_COLOR_SPACE_A

  • An RGB image with a premultiplied alpha channel and three extra channels would be:

IG_COLOR_SPACE_ID_RGB | IG_COLOR_SPACE_ID_P | IG_COLOR_SPACE_ID_Ex


24-bit RGB Images

24-bit RGB images are images in which each pixel is represented by three 8-bit quantities (thus, 24 bits total) specifying the intensities of red, green, and blue that form the color for the pixel. For example, a pixel that is to be displayed as brightest magenta-magenta being a color formed of equal intensities of red and blue, and no green-would be represented by three bytes having the respective values of 255, 0, 255 for the red, green, and blue intensities. In RGB representation the brightest white would be (255, 255, 255) and black would be (0, 0, 0).


1-bit Images

Images that contain only one bit per pixel can contain only two colors, since only two pixel values are possible: 0 and 1. The two colors for a 1-bit image are usually black and white, but if the image is to be displayed on an RGB device, the colors are determined by a table called a color palette. A color palette defines the color to be displayed for each possible pixel value. The following table demonstrates the color palette for a 1-bit image, which specifies black for pixel value 0 and white for pixel value 1:

BLUE
GREEN
RED
Not Used
color 0
0
0
0
0
color 1
255
255
255
255

Each entry in a color palette is a 4-byte structure of type AT_RGBQUAD, in which the first three bytes are used to specify the intensities of blue, green, and red respectively, forming the color. The 4th byte is not used. (Note that the ordering in this structure is blue, green, red-not red, green, blue.) AT_RGBQUAD and all other structure types mentioned in this chapter are described in detail in the section ImageGear Data Types and Structures, found in .

If instead you wanted to have pixel value 0 displayed as a medium yellow, and pixel value 1 as brightest red, you might use the following color palette (yellow is constructed of equal intensities of red and green, with no blue):

BLUE
GREEN
RED
Not Used
color 0
0
128
128
0
color 1
0
0
255
0


4-bit and 8-bit Images

A 4-bit image is simply one in which each pixel is represented by 4 bits. Therefore, a 4-bit image can contain 16 (24) colors, each pixel having a numerical value between 0 and 15. The color palette for a 4-bit image will therefore normally have 16 entries (0 - 15.) As a 1-bit image might be called a 2-color image, a 4-bit image is also called a 16-color image.

In an 8-bit image each pixel occupies exactly one byte. This means each pixel has 256 (28) possible numerical values, from 0 to 255. Therefore, the color palette for an 8-bit image normally contains 256 entries, defining color 0 through color 255. 8-bit or 256-color images are very common because the availability of 256 unique colors provides adequate or even excellent color resolution for most purposes. Also, when operating upon an image in memory, such as when performing image analysis, transformations, or other image processing, operating on an 8-bit image is much faster than performing the same operations on a 24-bit image. And, of course, an 8-bit image uses only about one-third the memory or file storage space as a 24-bit image.

Because each pixel value of a 1, 4, or 8-bit color image is used as an index into a color palette, these images are sometimes called "indexed color" images. In this manual, 8-bit color images are sometimes referred to as "8i" images, to distinguish them from 8-bit gray level images, which are described below.


Grayscale Images

In RGB color representation, (255, 255, 255) results in the brightest white, and (0, 0, 0) results in black. Any time the three intensities are equal, no color is emphasized and the result is a shade of gray. For example (128, 128, 128) would be a medium gray, (240, 240, 240) would be a bright gray approaching white, and (16, 16, 16) would be a dark gray not far from black.

A grayscale image is one in which the color palette contains only grays, evenly graduated from black (0, 0, 0) for pixel value 0, to white (255,255,255) for the highest possible pixel value. This means that in an 8-bit gray level image, the blue, green, and red intensities for each palette entry are equal to the pixel value. The color palette for an 8-bit gray level image is illustrated below:

BLUE
GREEN
RED
Not Used
color 0
0
0
0
0
color 1
1
1
1
0
color 2
2
2
2
0
color 3
3
3
3
0
...
...
...
...
...
color 254
254
254
254
0
color 255
255
255
255
0

Some ImageGear image processing operations cannot be performed on 8i (8-bit color) images, because some colors that occur as a result of the processing may not be present in the image's color palette. For such operations, if the image is 8-bit, it must be 8-bit gray level.


Color Values Used During Display

Although an image's color palette (or in the case of a 24-bit image, each pixel's 24-bit RGB value) normally determines the color to display at each pixel location, there are cases when this is not so. ImageGear maintains a set of Red, Green, and Blue "Look Up Tables" (LUTs), which are used to determine whether the colors to actually display are different from those in the image's palette. The LUTs are modified, for example, if you instruct ImageGear to alter the brightness or contrast of an image. The LUTs can also be set directly by your application (meaning you can display an 8-bit grayscale image in any 256 colors of your choosing). See the section Displaying Images of , for further explanation of ImageGear's LUTs, including examples showing how to modify and use them.

The colors displayed for an image may also be modified due to constraints imposed by the display monitor being used. Some display monitors use a single 256-color hardware palette. ImageGear can reload this hardware palette each time an image is to be displayed, but since all images on the screen are being displayed using this one hardware palette, all other images on the screen at the same time will change to reflect the colors of this new palette. For such cases, you can instruct ImageGear as to which image or images are to have precedence in establishing the device's hardware palette. In addition, ImageGear can also inform you when the colors of an image may have changed due to the loading of another image's palette. This is discussed in more detail in the section Displaying Images in Chapter 5.


Device-Independent/Device-Dependent Bitmaps

A bitmap image, also called a raster image, is an image held in the form of successive rows (called rasters) of pixel data. As already stated, ImageGear's bitmap images use 1, 4, 8, or 24 bits to represent each pixel. But besides these pixel bits, additional information is necessary to describe an image. For example, the width (number of pixels per row) and height (number of rows in the image), are required. For some images, a color palette may be required. Depending upon how the bitmap is to be used, additional information may be required or useful.

To hold bitmap images in memory, ImageGear uses two types of bitmaps, both widely used by many other software products and supported by development platforms such as Microsoft Windows. These are the Device-Independent Bitmap (DIB) and the Device-Dependent Bitmap (DDB). The DIB is by far the more widely used for in-memory operations. It has become the common denominator format because it is so simple: it describes just the image, without reference to characteristics of the device(s) upon which it may later be displayed. While ImageGear provides convenient ways to convert between DIBs and DDBs and to display DDBs, nearly all ImageGear operations are performed on DIBs exclusively.


Device-Independent Bitmaps (DIB)

A DIB consists of a header structure called a BITMAPINFOHEADER followed by the color palette, if one is present, followed by the bitmap (pixel) data:

BITMAPINFOHEADER
COLOR PALETTE (if any)
BITMAP DATA

The BITMAPINFOHEADER structure contains such information as the number of bits per pixel, number of pixels per row, and total number of rows in the image, as well as whether the bitmap data has been compressed for more efficient storage. Its form is shown below. Its fields are described in detail in the section ImageGear Data Types and Structures of Chapter 5.

BITMAPINFOHEADER:
DWORD
biSize
LONG
biWidth
LONG
biHeight
WORD
biPlanes
WORD
biBitCount
DWORD
biCompression
DWORD
biSizeImage
LONG
biXPelsPerMeter
LONG
biYPelsPerMeter
DWORD
biClrUsed
DWORD
biClrImportant

A color palette is present in the DIB if the image is 1-bit, 4-bit, or 8-bit. The format of the color palette was described at the beginning of this chapter.

The format of the bitmap data is:

  • For 1-bit images, the first (leftmost) pixel of a row is held in the Most Significant Bit (MSB) of the first byte of the row. Subsequent bits hold subsequent pixels, at a rate of 8 pixels per byte. The row is padded with zeroes as necessary to assure a multiple of 4 bytes length for each row.
  • For 4-bit images, the first pixel of each row is in the 4 Most Significant Bits of the first byte of the row, and each succeeding 4 bits hold each succeeding pixel. As above, the row is zero-padded to a multiple of 4 bytes length.
  • For 8-bit and 24-bit images, each pixel of a row occupies exactly 1 or 3 bytes respectively, and again each row is padded with zeroes to a multiple of 4 bytes length. Note that the colors in a 24-bit pixel in a standard DIB are ordered Blue-Green-Red (not Red-Green-Blue).

It should be noted that in a DIB, the first row of the bitmap data is the row to be displayed at the bottom of the image. For historical reasons, many file formats store their bitmap data top row first (this is because most devices to which bitmap data is sent display the rows top-to-bottom. Such devices, which include most CRT display monitors, are often called raster-scan devices.).

Whenever ImageGear loads a file of a format having top-to-bottom row ordering, it automatically reverses the order of the rows, assuring bottom-to-top row ordering for all DIBs, regardless of where the image originated. Keep in mind the ordering of a DIB is therefore "upside down" relative to the convention used in much display software that the top row of a display is row 0 and row numbers increase downward. However, it is important to note, ImageGear's pixel access functions (such as IG_DIB_pixel_set()) consider the coordinates 0,0 to refer to the upper left-hand corner of the bitmap data. As with an image shown on the screen, the x values will increase toward the right, and the y values will increase toward the bottom.

See Also:

ImageGear Architecture Diagram.


Device-Dependent Bitmaps (DDBs)

Device-Dependent Bitmaps are bitmaps whose pixel data is organized for convenient dispatch to a particular device or group of devices, such as to a particular type of display monitor or printer. Normally you will not need to concern yourself with DDBs. ImageGear is designed to hold in-memory images in DIBs by default, and to process the image data of DIBs efficiently. But when the speed with which images are displayed is an important factor in your application, keeping large or often-displayed images in memory in DDB format may improve performance. For such cases, ImageGear provides several ways to create or import DDBs, and to display DDBs. Please refer to Using ImageGearChapter.

If your application is intensive in the use of in-memory DDB's, we suggest you refer to Microsoft Windows documentation of Device-Dependent Bitmaps and Device Contexts.


Vector Images

Bitmap images, sometimes also called raster images, have their data organized in horizontal rows of pixels for convenient dispatch to raster-scan devices. Devices and display software also exist that can directly display any line, if given an exact specification of the line. An example is a straight line defined by its two endpoints. Such a line is sometimes called a vector, and an image file whose data is specified exclusively in terms of vectors is called a vector image file.

ImageGear reads most popular formats that contains vector data. While doing so it performs so called "rasterization", i.e. conversion of vector data into raster representation. For some vector formats such conversion can only be possible for the certain platforms (WMF/EMF vector data can only be rasterized in Windows version of the product, and PICT vector data can only be rasterized in Mac version of the product). For some vector formats (DWF, DWG, DXF, HPGL,HPGL/2, DGN) ImageGear also allows to control the projection of 3D vector data into 2D raster bitmap.


ImageGear Architecture Diagram

The diagram in figure 1 gives a conceptual view of the important role played by DIBs in ImageGear. The center image represents a DIB that results when an image is obtained from disk, memory, or a scanned file. Image processing and clipboard functions can be used to alter or merge the actual DIB bitmap data. To the right of the DIB are various routes an image may take after being manipulated by ImageGear: it may be saved to disk or to memory, it may be displayed, or it may be printed.


File Format Reference

This chapter provides information about the image formats that ImageGear supports. Before you begin, please refer to the Encoding vs. Compressing section below to familiarize yourself with the terms used in this Chapter.

Then you can read the Format Suitability at a Glance section, which briefly delineates which formats best support various types of images. This section provides you with a starting point for deciding which file formats to use in your application.

The section ImageGear Support for Graphics File Formats describes the types of imaging file formats supported by ImageGear and provides useful information about support for some specific formats:

  • Support for Adobe PDF/PS Formats
  • Support for CAD/Vector Formats
  • Support for DICOM File Format
  • Support for JBIG2 File Format
  • Support for JPEG2000 File Formats
  • Support for Metafile Formats
  • Support for Multimedia File Formats
  • Support for Multi-page File Formats

ImageGear Supported Bit Depths section describes the bit depths, and the read/write capabilities of the supported formats. Using this table you can easily find out whether an image can be converted to a particular format.

Detailed information about every ImageGear supported imaging file format or compression can be found in the following sections:

  • ImageGear Supported Compressions Reference - here you will find information for every ImageGear supported imaging compression.
  • ImageGear Supported File Formats Reference - provides you with the detailed information about every ImageGear supported format, its ID, versions, encoding type, multi-page and alpha channel support, supported compressions, color spaces and bit depths for read and write, as well as information about ImageGear supported features and filter control parameters.

The section ImageGear Supported Digital Camera RAW Formats provides you with information about the level of ImageGear support for DC RAW formats.

If you are going to use the ImageGear alpha channels or transparency support, please review the section ImageGear Alpha Channel Support or ImageGear Transparency Support.

Encoding vs. Compressing

These two words are often used interchangeably in discussions of graphics file formats. Encoding is actually a broad term under which compression falls. For the sake of clarity, use these terms separately with the following intended meanings:

  • Encoding - The manner that data is stored when uncompressed (binary, ASCII, etc.), how it is packed (e.g., 4-bit pixels may be packed at a rate of two pixels per byte), and the unique set of symbols used to represent the range of data items.
  • Compressing - A "physical" rewriting of the graphics data so that it is represented by a smaller set of data.


Format Suitability at a Glance

The following table contains the formats that AccuSoft considers most practical for the listed type of data, and can be used as a starting point. You can use a format with the appropriate character depth and one that provides either the most efficient use of space, or the fastest loading and saving capabilities.

Bear in mind that the following table represents recommendations only. To make an informed choice, read about each format in more detail in the section ImageGear Supported File Formats Reference.

Image type
Recommended
Colors
JPEG, JPEG2000, TIFF, PNG, FlashPix
Grayscale/many shades
TGA, TIFF, JPEG, DICOM
Monochrome / high resolution
TIFF (CCITT Group 3 compression), TIFF (CCITT Group 4 compression)
Banking data
IBM IOCA, IBM MO:DCA (ABIC compression)
Noisy
Color: PNG, TIFF, JPEG;
Bi-tonal: Group 3, Group 4
Lossless
GIF, TIFF, PNG, Group 3, Group 4, JPEG (Lossless JPEG compression)
Lossy
TIFF (JPEG compression), JPEG
Extra data to store
TIFF, EXIF-JPEG, EXIF-TIFF
Iconic images
ICO
Facsimiles
Group 3, Group 4
Multimedia
PNG, GIF, JPEG, AVI, MULTIMEDIA, QuickTime
Photographic images
Adobe PSD, Adobe PSB, PCD, JPEG, FlashPix
Internet images
GIF, JPEG, PNG, JPEG2000, WBMP
Macintosh paint programs
MAC, MAC PICT
PC paint programs and/or graphics arts
PCX, GEM, WMF, TIFF, EPS, MAC PICT, BMP
X Windows
XBM, XPM, XWD
Medical data
DICOM
CAD/Vector
EPS, WMF, DWF, DWG, DXF , CGM , DGN , HPGL , SVG , U3D
Document processing
TIFF, Adobe PDF, Adobe PS, EPS, PTOCA, TXT (ASCII Text)


ImageGear Support for Graphics File Formats

Every application that deals with images has specific kinds of data to store and interchange, from icons to photographs. The various hardware devices used to record and store the graphics data, and the hardware intended to display or print the data also affect the design of the format. This leads to a diversity of file formats. To add to this diversity, different groups of people have different ideas about how to structure and access an image, and what kind of additional information should be stored with an image. Even formats designed to store the same kind of data can differ. Other factors that affect the outcome of the design include memory considerations, storage size, accuracy, and portability.

National and international standardization organizations, such as the American National Standards Institute (ANSI) and the International Standards Organization (ISO), seek to create standards of storage for graphics data. One example is the Joint Photographic Experts Group's (JPEG) creation of the JPEG file format. Some of its intended goals were good image quality, user-chosen compression ratio, and cross-platform flexibility. When an image is called a JPEG, it is assumed to precisely follow the standardized JPEG format.

Formats known as "de facto standards" are those that begin as proprietary formats, but by the forces of the market and sometimes by good quality, become widely supported. Some examples of de facto standards are BMP, GIF, and PCD.

A third group of file formats falls somewhere between officially recognized standards and the strictly proprietary formats. These formats are created by groups of individuals with a common interest who come together to form a more unofficial standards organization. These formats are usually intended to provide an end-all industry standard so that data with the same or similar origins can be shared across different applications or platforms. One example is the TIFF format. TIFF was designed by eight computer technology companies (headed by Aldus Corporation) with the common goal of providing a standard format for storing scanned images.

ImageGear supports graphics file formats from all of these genres, providing you with a complete range of imaging capabilities, including the capture and processing of scanned images.

In addition, ImageGear functionality enable you to exchange data easily from one format to another, and to make improvements in images using powerful image-processing API.

ImageGear list of supported formats includes all of the popular formats, including recognized standards that best utilize the latest imaging technologies.

See Also:

ImageGear Supported Compressions Reference

ImageGear Supported File Formats Reference


Support for Adobe PDF/PS Formats

ImageGear provides comprehensive support for Adobe PDF and Adobe PS formats using its ImageGear PDF Component.

To use support for PDF and PostScript formats as well as manipulate and transform PDF/PS images ImageGear PDF Component should be attached to Core ImageGear.

See Also:

Using ImageGear PDF Component

PDF Component API Function Reference


Support for CAD/Vector Formats

ImageGear provides support for the following CAD/Vector formats:

  • CGM
  • DGN
  • DWF
  • DWG
  • DXF
  • HPGL (HPGL/2)
  • SVG
  • U3D

To work with these formats the following ImageGear components should be attached to Core ImageGear respectively:

  • ImageGear CAD/Vector CGM Component
  • ImageGear CAD/Vector DGN Component
  • ImageGear CAD/Vector DWF Component
  • ImageGear CAD/Vector DWG, DXF Component
  • ImageGear CAD/Vector HPGL, HPGL/2 Component
  • ImageGear CAD/Vector SVG Component
  • ImageGear U3D Vector Component

To manipulate and process CAD/Vector images ImageGear Vector Component should be attached to Core ImageGear.

NOTE: ImageGear supports CAD/Vector formats for Win32 and Win64 platforms only.
See Also:

Using ImageGear CAD/Vector Components

Vector Component API Function Reference


Support for DICOM File Format

ImageGear provides comprehensive support for DICOM formats using its ImageGear Medical Component.

To use the support for DICOM format as well as manipulate, transform and process DICOM images ImageGear Medical Component should be attached to Core ImageGear.

See Also:

Using ImageGear MD Component

MD Component API Function Reference


Support for JBIG2 File Format

ImageGear provides comprehensive support for JBIG2 format using its ImageGear JBIG2 Component.

To use the support for JBIG2 format ImageGear JBIG2 Component should be attached to Core ImageGear.

See Also:

Using ImageGear JBIG2 Component


Support for JPEG2000 File Formats

ImageGear provides support for the following JPEG2000 formats:

  • JPEG2000
  • JPX
  • Motion JPEG2000

To use the support for JPEG2000 formats as well as efficiently and dynamically stream portions of a JPEG2000-compressed image over a network ImageGear JPEG2000 Component should be attached to Core ImageGear.

See Also:

Using ImageGear JPEG2000 Component

JPEG2000 Component API Function Reference


Support for Metafile Formats

Metafiles contain vector (or geometric) specifications and bitmap pixel data. Vectors, in the realm of computer graphics, define shapes and location of shapes in terms of their relative location within the page.

ImageGear supports the following formats that contain vector data:

  • WMF
  • WPG
  • EPS
  • MAC PICT

For all formats, except WMF, the vector data is ignored; only the bitmap data is read and/or written.

NOTE: When ImageGear loads a Windows Metafile (WMF), it automatically converts each vector specification to bitmap data. The shapes and lines declared by the vector specifications appear in the image, but the original vector instructions are not saved.


Support for Multimedia File Formats

ImageGear provides support for the following multimedia formats:

  • AVI
  • MULTIMEDIA
  • QuickTime

To use the support for multimedia formats as well as ImageGear Multimedia Component should be attached to Core ImageGear.

ImageGear Multimedia Component uses DirectShow internally to read and decode files and the types of AVI and MPEG files you can read with it depend on what files DirectShow can read, i.e. it depends on what video codecs are installed on the computer. For example, if you want to read a DivX-compressed AVI file, you can do it with the ImageGear Multimedia Component, but only if you have installed the DivX codec on your PC.

On the other way if you can view the file in Windows Media Player, you should be able to read it with the ImageGear Multimedia Component.


Support for Multi-page File Formats

ImageGear provides multi-page support for the following file formats:

  • Adobe PDF
  • Adobe PS
  • Adobe PSB
  • Adobe PSD
  • AVI
  • BMP (OS/2 BMP only)
  • CGM
  • CUR
  • DCX
  • DICOM
  • DWF
  • GIF
  • HPGL
  • IBM AFP
  • IBM IOCA
  • IBM MO:DCA
  • ICO
  • IFF
  • JBIG2
  • MULTIMEDIA
  • PCD
  • PTOCA
  • TIFF
  • TXT (ASCII Text)
  • XPS

Please see the section Working with Multi-page Images to learn how to use ImageGear multi-page functionality.

To create multi-page files, simply save to an existing Adobe PDF , Adobe PS , DCX , DICOM , GIF , IBM AFP , JBIG2 or TIFF file. If the file exists, the new page is appended to the file.

NOTE: It is important to note that ImageGear treats the first page of a multi-page file as page number 1 (not 0).


ImageGear Supported Bit Depths

You may want to convert a file from one format to another. You can do this by saving the original file to its desired format by setting the nFormatType parameter to the appropriate value in the saving function. For more information on converting issues, see the sections Loading Images and Saving Images.

When saving a file to another format, remember to ensure that the desired file format is supported for that image. For example, you cannot convert an 8-bit DCX file to an 8-bit CAL file, because the CAL format does not support 8-bit files.

In the tables on the following pages, the columns underneath the numbers indicated size in bits that can actually be saved (written). The columns underneath the letters "R" and "W" indicate that the ImageGear reads and writes, respectively, the corresponding file format.

Format
R
W
1
4
8
9-16G
24
32
36
48
64
Adobe DNG
+
+
+
Adobe PDF
+
+
+
+
+
+
+
Adobe PS
+
+
+
+
+
+
+
Adobe PSB 1
+
+
+
+
+
+
+
+
+
+
Adobe PSD 2
+
+
+
+
+
+
+
+
+
+
AFX
+
+
AVI
+
+
+
+
+
BMP
+
+
+
+
+
+
+
+3
BTR
+
+
+
CAL
+
+
+
CGM
+
+
CLP
+
+
+
+
+
+
CUR 4
+
+
+
+
+
+
CUT
+
+
+
DCRAW
+
+
+
DCX
+
+
+
+
+
+
DGN
+
DIB
+
+
+
+
+
+5
+
+6
DICOM
+
+
+
+
+
+
+
+
DWF
+
+
DWG
+
+
DXF
+
+
EPS 7
+
+
+
+
+
+
EXIF-JPEG
+
+
+
+
+
+
+
EXIF-TIFF
+
+
+
+
+
+
+
+
+
+
+
FlashPix
+
+
+
+
+
GEM
+
+
+
+
GIF
+
+
+
+
+
Group 3
+
+
+
Group 3 2D
+
+
+
Group 4
+
+
+
HD Photo
+
+
+
+
+
+
+
+
+
Headerless Digital Camera RAW
+
+
+
HPGL
+
IBM AFP
+
+
+
+
+
IBM IOCA
+
+8
+
+
+
+
IBM MO:DCA
+
+9
+
+
+
+
ICO
+
+
+
+
+
+
IFF
+
+
+
+
+
+
IMG
+
+
+
IMR
+
+
IMT
+
+
+
JBIG2
+
+
+
JPEG
+
+
+10
+
+
+
+
+
JPEG2000
+
+
+
+
+
+
+
+
+
JPX
+
+
+
+
+
+
+
+
+
KFX
+
+
LV
+
+
MAC
+
+
MAC PICT
+
+
+
+
+
+
Motion JPEG2000
+
+
+
+
+
+
+
MSP
+
+
MULTIMEDIA
+
+
NCR
+
+
+
+11
PBM
+
+
+
+
+
+
+
PCD
+
+
PCX
+
+
+
+
+
+
PGM 12
+
+
+
+
PNG 13
+
+
+
+
+
+
+
+
+
+
PNM 14
+
+
+
+
+
+
+
PPM
+
+
+
+
PTOCA
+
+
QuickTime
+
+
RAS
+
+
+
+15
+
+
RAW
+
+
+
+
+
+
+
Scitex CT 16
+
+
+
SGI
+
+
+
+
+
+
SVG
+
+
TGA
+
+
+
+
+
+
+
TIFF 17
+
+
+
+
+
+
+
+
+
+
+
TXT (ASCII Text) 18
+
U3D
+
+
WBMP
+
+
+
WMF
+
+
+
+
+
+
WPG
+
+
+
+
XBM
+
+
+
XPM
+
+
+
+
+
+19
XPS
+
+
+
+
+
+
+
+
+
XWD
+
+
+
+
+
+

148- and 64-bit images support is Read only.

248- and 64-bit images support is Read only.

3Read only support.

4Supports Extra ((1, 3, 4, 8)*2)-bit images also.

5Read only support.

6Read only support.

7Screen Preview image only, when reading.

8Write support for 1-bit images only.

9Write support for 1-bit images only.

108-bit grayscale.

11Read only.

12Supports 16-bit grayscale images also.

13Supports 48(RGB)- and 64(RGB+alpha)-bit images.

14Supports 16-bit grayscale and 48-bit color images also.

15Read only support.

16The native format is CMYK. With full CMYK support enabled, you can use 32-bit images.

17Read only supports also 3- and 6 bpp for RGB and LAB color spaces for Deflate, LZW (Lempel-Ziv-Welch), Packbits compressions and uncompressed.

18Converts to raster image when loaded.

1924-bit has Read only support


ImageGear Supported Compressions Reference

All imaging files compressions can be divided on three basic types:

  • One-dimensional compression - the raster data is treated as one continuous data stream. Each byte read is compared to the previous byte. This compression method is not concerned with delineating lines of data.
  • 2D compression can be thought of as "Differencing Compression", where the data stored is a representation of the differences in data values from previous data values. In 2-D compression, the encoding of one line is determined by the contents of the previous line. This method of compression is best used for black-and-white images where the black pixels tend to fall into groups.
  • 3D compression is a new branch of data compression aimed at the 3D models and other geometric datasets used in computer graphics, virtual reality, video games, CAD/CAM, and many scientific, engineering, and medical applications.

Existing 3D compression algorithms use both techniques adapted from the 1D and 2D cases (like wavelets, entropy coding, and predictive coding), and completely different approaches that take advantage of the properties of 3D surfaces (like Edgebreaker, Subdivision Surfaces, and triangle strips).

ImageGear supports the following compressions:

  • ABIC
  • ABIC_BW
  • ABIC_Gray
  • ASCII
  • CCITT Group 3
  • CCITT Group 3 2D
  • CCITT Group 4
  • Deflate
  • FPX NOCHANGE
  • FPX SINCOLOR
  • Huffman
  • IBM MMR
  • JBIG2
  • JPEG
  • JPEG2000
  • Lossless JPEG
  • LZW (Lempel-Ziv-Welch)
  • Packbits
  • Progressive JPEG
  • RAW
  • RLE


ABIC

Full Name
IBM ABIC compression
Compression ID
IG_COMPRESSION_ABIC =16
IG Component
ABIC
Bit Depth
1
File Formats
IBM AFP , IBM IOCA, IBM MO:DCA , RAW , TIFF
IG Platforms Support
WIN32

Comments:

This is a proprietary compression scheme (owned by IBM) used on IOCA/MO:DCA. It requires the ImageGear ABIC Component to be attached.


ABIC_BW

Full Name
IBM ABIC compression
Compression ID
IG_COMPRESSION_ABIC_BW = 9
IG Component
ABIC
Bit Depth
1
File Formats
IBM AFP , IBM IOCA, IBM MO:DCA , RAW , TIFF
IG Platforms Support
WIN32

Comments:

This is a proprietary compression scheme (owned by IBM) used on IOCA/MO:DCA. Used for ABIC black and white (B/W) images. It requires ImageGear ABIC Component to be attached.


ABIC_Gray

Full Name
IBM ABIC compression
Compression ID
IG_COMPRESSION_ABIC_GRAY = 10
IG Component
ABIC
Bit Depth
1
File Formats
IBM AFP , IBM IOCA, IBM MO:DCA
IG Platforms Support
WIN32

Comments:

This is a proprietary compression scheme (owned by IBM) used on IOCA/MO:DCA. Used for ABIC grayscale images. It requires ImageGear ABIC Component to be attached.


ASCII

Full Name
American Standard Code for Information Interchange (ASCII)
Compression ID
IG_COMPRESSION_ASCII = 23
IG Component
Core
Bit Depth
Gray level: 1, 8, 16 bpp; RGB 24, 48 bpp
File Formats
PBM, PGM, PNM, PPM
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

Acronym for the American Standard Code for Information Interchange. ASCII is a code for representing English characters as numbers, with each letter assigned a number from 0 to 127. For example, the ASCII code for uppercase M is 77. Most computers use ASCII codes to represent text, which makes it possible to transfer data from one computer to another.

Text files stored in ASCII format are sometimes called ASCII files. Text editors and word processors are usually capable of storing data in ASCII format, although ASCII format is not always the default storage format. Most data files, particularly if they contain numeric data, are not stored in ASCII format. Executable programs are never stored in ASCII format.


CCITT Group 3

Full Name
CCITT Group 3
Compression ID
IG_COMPRESSION_CCITT_G3 = 3
IG Component
Core
Bit Depth
1
File Formats
BTR, EPS, Group 3, IBM IOCA, IBM MO:DCA, IMT,
LV, NCR, Adobe PDF, Adobe PS, TIFF , RAW
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

This is a 1-D version of the CCITT Group 3 compression scheme. It uses a static table of values to assign codes to run lengths. Frequently occurring run lengths are given smaller codes. (The most frequent are usually black runs of 2 or 4 pixels).


CCITT Group 3 2D

Full Name
CCITT Group 3 2D
Compression ID
IG_COMPRESSION_CCITT_G32D = 5
IG Component
Core
Bit Depth
1
File Formats
BTR, EPS, Group 3 2D, IBM IOCA, IBM MO:DCA,
Adobe PDF, Adobe PS, TIFF , RAW
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

This is a 2-D version of the CCITT Group 3 compression scheme. It includes an error recovery algorithm for error transmissions; an error in one line does not translate to garbage output for the rest of the file. All modern fax machines support this format.


CCITT Group 4

Full Name
CCITT Group 4
Compression ID
IG_COMPRESSION_CCITT_G4 = 4
IG Component
Core
Bit Depth
1
File Formats
CAL, EPS, Group 4, IBM IOCA, IBM MO:DCA, IMR,
IMT, KFX, LV, NCR, Adobe PDF, Adobe PS, TIFF , RAW
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

The G4 compression is two-dimensional by default. It is very similar to the G3 2D compression, but it can produce compressed images that are half the size of a G3-compressed file.

It is slower, however, and does not have the same error recovery built in that the G3 format has. The decrease in speed occurs because G4 was designed specifically for encoding disk data. For this reason, it may be advisable to use the G3-Fax compression scheme if final compression size is not crucial, but speed is.


Deflate

Full Name
Deflate compression
Compression ID
IG_COMPRESSION_DEFLATE = 14
IG Component
Core
Bit Depth
1, 2, 4, 8, 16 bpc
File Formats
Adobe PDF, PNG, Adobe PS, TIFF
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

"Zip-in-TIFF" compression. Deflate compression, sometime known as "zip" compression, uses another variant of the LZW compression method and so gives similar results, but is not restricted by any licenses.


FPX NOCHANGE

Full Name
Unchanged compression
Compression ID
IG_COMPRESSION_FPX_NOCHANGE = 13
IG Component
FlashPix
Bit Depth
Gray level: 8 bpp; RGB: 24 bpp
File Formats
FlashPix
IG Platforms Support
WIN32

Comments:

This is not a compression scheme but rather a saving mode, allowing to save FlashPix images with the same compression as they were loaded. Use this mode to change FlashPix image metadata without changing its pixels.

This compression requires the ImageGear FlashPix Component to be attached.


FPX SINCOLOR

Full Name
Single color compression
Compression ID
IG_COMPRESSION_FPX_SINCOLOR = 12
IG Component
FlashPix
Bit Depth
Gray level: 8 bpp, RGB: 24 bpp
File Formats
FlashPix
IG Platforms Support
WIN32

Comments:

This is compression is used with FlashPix images. FlashPix images are divided into tiles; when all pixels of a tile have the same color, only this single color value is saved. If a tile has pixels of different colors, the tile is saved uncompressed.

This compression requires the ImageGear FlashPix Component to be attached.


Huffman

Full Name
Huffman encoding
Compression ID
IG_COMPRESSION_HUFFMAN = 2
IG Component
Core
Bit Depth
1, 24
File Formats
NCR, PCD, TIFF
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

Developed in 1952 by David Huffman, this is one of the older compression methods. The encoding and decoding processes are complex relative to today's standards, but the compression ratio can be high if the image contains many repeat data values. It is best used for images with little or no pixel noise, e.g. cartoons or drawings with large areas of the same color and intensity (like a monotone sky). This compression scheme is often used by other compression algorithms for extra compression.

The Huffman method uses a conversion table to assign codes for each value, based on frequency of occurrence. The file is scanned for all of its values, with the values and their frequency of occurrence tallied. Using a binary tree, values are paired off by frequency of occurrence, beginning with the least frequent values. As the tree progresses upward, the least occurring values at the bottom of the tree continue to be incremented a bit at a time, with one bit added for each new branch added to the tree. In the end, the values that occur the most (at the top of the tree) have the shortest codes.

A potential problem with this compression method is decoding; the file's variable-length codes can cause the dropping or adding of a bit to the end of a line, thereby throwing off subsequent lines of data.


IBM MMR

Full Name
IBM Modified Modified Read
Compression ID
IG_COMPRESSION_IBM_MMR = 15
IG Component
Core
Bit Depth
1
File Formats
IBM IOCA, IBM MO:DCA
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

Compression for black and white documents, similar to CCITT Group 4.


JBIG2

Full Name
JBIG2 compression
Compression ID
IG_COMPRESSION_JBIG2 = 19
IG Component
JBIG2
Bit Depth
1
File Formats
JBIG2, Adobe PDF
IG Platforms Support
WIN32

Comments:

The JBIG2 is the most effective compression method for bitonal (B\W) images. It requires ImageGear JBIG2 Component to be attached.


JPEG

Full Name
JPEG compression
Compression ID
IG_COMPRESSION_JPEG = 6
IG Component
Core
Bit Depth
Gray level: 8, 16 bpp; RGB: 24, 36 bpp; CMYK: 32 bpp; RGB+Alpha: 32 bpp
File Formats
AFX, AVI, JPEG, DICOM, Adobe DNG, EPS, EXIF-JPEG,
FlashPix, MAC PICT, Adobe PDF, Adobe PS, TIFF
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

This file compression method obtains a high compression ratio when used with detailed photographic images (its intended use). It is not a good compression choice for images with a small number of colors and high contrast edges, or for color-mapped data. Part of JPEGs success in high compression is due to the fact that it is a "lossy" compression method, meaning that the compression results in the loss of some data that is determined to be unimportant or unnecessary. This does not necessarily result in a visible reduction of image quality.

JPEG is highly flexible - it allows you to make a "quality" setting that determines the amount of loss that occurs and affects the size of the resulting compressed file.

The JPEG algorithm takes into account that the human eye is more sensitive to changes in brightness than to number of colors. Rather than saving the color data from each pixel in an image, it saves information on the rate of change of color, or "frequency information." More loss is allowed in the color data than in the brightness data. Some of the compression of the color is achieved by converting the RGB values to YCbCr color scheme. ImageGear supports two other JPEG compression modes--Lossless JPEG and Progressive JPEG.

See Also:

Lossless JPEG, Progressive JPEG


JPEG2000

Full Name
JPEG 2000 wavelet compression
Compression ID
IG_COMPRESSION_JPEG2K = 25
IG Component
JPEG2K
Bit Depth
1..16 bpc, various colorspaces (depends on file format)
File Formats
JPEG2000, JPX, Motion JPEG2000, DICOM,
Adobe PDF, Adobe PS
IG Platforms Support
WIN32, WIN64, .NET, .NET64

Comments:

This compression requires the ImageGear JPEG2000 component to be attached. See Using ImageGear JPEG2000 Component.

The JPEG2000 compression technique is based on two main processes: Tiling and Discrete Wavelet Transform (DWT).

Tiling

The term `tiling' refers to the partition of the original (source) image into rectangular non-overlapping blocks (tiles), which are compressed independently as though they were entirely distinct images. All operations, including component mixing, wavelet transform, quantization and entropy coding are performed independently on the image tiles. Tiling reduces memory requirements, and since they are also reconstructed independently, they can be used for decoding specific parts of the image rather than the entire image.

All tiles have exactly the same dimensions, except for those at the right and lower boundary of the image. Arbitrary tile sizes are allowed, up to and including the entire image (i.e., the whole image is regarded as one tile). Components with different sub-sampling factors are tiled with respect to a high-resolution grid, which ensures spatial consistency on the resulting tile components. Smaller tiles create more tiling artifacts compared to larger tiles.

Discrete Wavelet Transform (DWT)

The Discrete Wavelet Transform (DWT) is very similar to the Discrete Fourier Transform (DFT), but does not use the sine and cosine functions for analyzing the image data. The basic functions are called scaling functions and wavelets. These functions combine the fundamental feature of orthogonality (allowing the transformation and the identical reconstruction) and compact representation. This allows the analysis of image data without the windowing effects, which result from the need to handle the infinite sine function on finite image data using the DFT.

Images can be seen as two dimensional signals. They can be transformed using a two dimensional transformation. Two dimensional transformations can be achieved by separately applying one dimensional transformations to the lines and columns of an image. The DWT method splits the image into four new images in the wavelet domain; one image contains the low-pass information and the others contain high-pass information of horizontal, vertical and diagonal orientation. The transformation then applies itself recursively to the low-pass image. This can be continued until the last low-pass image contains only a single pixel.

The tile components of JPEG2000 images are decomposed into different decomposition levels using Discrete Wavelet Transform. These decomposition levels contain a number of subbands, which consist of coefficients that describe the horizontal and vertical spatial frequency characteristics of the original tile component. Power of two decompositions are allowed in the form of dyadic decomposition (in Part I).

To perform the forward DWT, the standard uses a one dimensional subband decomposition of a one dimensional set of samples into low-pass samples and high-pass samples. Low-pass samples represent a downsampled low-resolution version of the original set. High-pass samples represent a downsampled residual version of the original set, needed for the perfect reconstruction of the original set from the low-pass set.

The DWT can be irreversible or reversible. The default irreversible transform is implemented by means of the Daubechies 9-tap/7-tap filter. The default reversible transformation is implemented by means of the 5-tap/3-tap filter.

The standard supports two filtering modes: a convolution-based mode and a lifting-based mode. For both modes to be implemented, the signal should first be extended periodically. This periodic symmetric extension is used to ensure that for the filtering operations that take place at both boundaries of the signal, one signal sample exists and spatially corresponds to each coefficient of the filter mask. The number of additional samples required at the boundaries of the signal is, therefore, filter-length dependent.

Convolution-based filtering performs a series of dot products between the two filter masks and the extended one dimensional signal. Lifting-based filtering consists of a sequence of very simple filtering operations for which alternately odd sample values of the signal are updated with a weighted sum of even sample values. Even sample values are updated with a weighted sum of odd sample values. For the reverse (lossless) case, the results are rounded to integer values.

The 5/3 filter allows repetitive encoding and decoding of an image without any additional loss. This is true when the decompressed image values are not clipped when they fall outside the full dynamic range (i.e. 0-255 for an 8-bpp image).


Lossless JPEG

Full Name
Lossless JPEG compression
Compression ID
IG_COMPRESSION_JPEG = 6
IG Component
Core
Bit Depth
Gray level: 8, 16 bpp; RGB: 24, 48 bpp
File Formats
DICOM, JPEG, TIFF
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

Lossless JPEG is an extension to the normal JPEG standard. One of the main algorithmic differences between the two is that the lossless JPEG does not apply a Discrete Cosine Transform. Rather, it uses a Predictive scheme. For each pixel, the values of one or several neighboring pixels are added to the value of the original pixel and then subtracted from the value of the original pixel. This method yields smaller values that require fewer bits per pixel to store.

ImageGear allows you to set the number of neighboring pixels to use in calculating the "predictor value".


LZW (Lempel-Ziv-Welch)

Full Name
Lempel-Zif-Welch (LZW) compression
Compression ID
IG_COMPRESSION_LZW = 8
IG Component
GIF/TIFF-LZW
Bit Depth
1, 4, 8, 16 bpc
File Formats
GIF, Adobe PDF, Adobe PS, TIFF
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

LZW compression works by finding patterns of data and assigning codes. It works best on highly-patterned images. Images with irregular patterning, or "noise," are not good candidates for this type of compression.

This compression scheme is "dictionary-based". This refers to the array of codes that identify each data pattern found in the image. The "dictionary" begins with a table that contains a code for each possible value in the image. If LZW compression is used on 8-bit images, a LZW "dictionary" is initialized with codes for 256 (28) values. As the file data is read, new values are added to the table for each unique pattern of data found. In the interest of saving space, the dictionary is not saved with the compressed file. The same dictionary is actually rebuilt when the data is decoded.


Packbits

Full Name
Packed bits compression
Compression ID
IG_COMPRESSION_PACKED_BITS = 1
IG Component
Core
Bit Depth
1, 4, 8, 16 bpc
File Formats
Adobe PSD, TIFF
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

Packbits compression seeks repeated data values. Packbits is considered an RLE (run-length encoding) compression scheme because it looks for "runs" or repeated values, and tallies their number, or "length". While its name implies that runs of bits are "packed" together, it is actually runs of bytes. It is very similar to the Macintosh Packbits compression used by Macpaint, except that the Packbits compression used for a TIFF allows the dimensions of the image to vary.

Packbits works by reducing repeated strings of the same characters into two components: the "run count" and the "run value". The count and value are stored in one byte each. Each two-byte grouping is referred to as an RLE packet. It is not a good compression scheme for images with large color ranges, as these do not tend to have many runs of the same color.

The terms "RLE" and "Packbits" are often used synonymously.


Progressive JPEG

Full Name
Progressive JPEG compression
Compression ID
IG_COMPRESSION_PROGRESSIVE = 17
IG Component
Core
Bit Depth
Gray level: 8, 16 bpp; RGB: 24, 36 bpp; CMYK: 32 bpp; RGB+Alpha: 32 bpp
File Formats
JPEG
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

Progressive JPEG is considered an extension to the JPEG standard. It produces the same kind of lossy compression as normal JPEG compression (see above), except that it saves multiple copies of the same image using different levels of quality. There is no hard limit on the number of "scans" that may be stored.

When a Progressive JPEG-compressed image is decompressed, the filter decompresses the lowest quality image first. This can be helpful for quickly displaying a version of the image that you are loading. The benefit of this compression is the fast display of an image that is recognizable. The downside is that a JPEG decompression is performed more than once.


RAW

Full Name
RAW compression (Uncompressed binary compression)
Compression ID
IG_COMPRESSION_RAW = 24
IG Component
Core
Bit Depth
Gray level: 1, 8, 16 bpp; RGB 24, 48 bpp
File Formats
PBM, PGM, PNM, PPM
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

Uncompressed binary compression. PBM/PGM/PNM/PPM formats use the term "RAW" for uncompressed binary compression, as opposed to ASCII compression.


RLE

Full Name
Run length encoding compression
Compression ID
IG_COMPRESSION_RLE = 7
IG Component
Core
Bit Depth
1, 4, 8, 16 bpc
File Formats
BMP, CLP, CUT, DCX, DICOM, GEM, IFF, MAC, MSP,
PCX, Adobe PDF, Adobe PS, RAS, SGI, TGA, WMF, WPG
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

Comments:

RLE (Run Length Encoding) is normally a 1-dimensional compression scheme. Working sequentially from left to right and top to bottom, it compares the value of each byte with the value of the previous byte. Each data value is recorded into a "packet" of two bytes where the first byte contains the number of times the value is repeated, and the second packet contains the actual value. The bytes in the pocket are called the "run count" and the "run value". When an image contains many repeat values, the compression ratio is very high (for example, if every byte in a 100 byte image were the same, its size could be reduced to 2 bytes giving a 50:1 ratio). A very noisy image, or a plain ASCII text file typically does not compress well, and in fact could become larger for example, if all bytes in image are different from the ones next to them, the image doubles, because 2 bytes are used to store each byte in the image.

The terms "RLE" and "Packbits" are often used synonymously.


ImageGear Supported File Formats Reference

This section represents the reference for every imaging file format supported by ImageGear.

The following are the characteristic features for file format description:

  • Full Name - Full name of the File Format
  • Format ID - ImageGear constant that determines the File Format ID used for loading this file in ImageGear-based application. See the section Working with Format Filters .
  • File Extensoin(s) - The used extensions of the File Format
  • Data Type - The type of the File Format (raster, vector, metafile)
  • Data Encoding - The type of data encoding. Please see the section Encoding vs. Compressing.
  • IG Multipage Support - Shows if ImageGear supports the File Format as multipage or singlepage. Please see also the section Support for Multi-page File Formats.
  • IG Alpha Channel Support - Shows if ImageGear supports the alpha channel for the File Format or not. Please see also the section ImageGear Alpha Channel Support.
  • IG Platforms Support - Shows ImageGear platform versions that support the File Format.
  • ImageGear Supported versions - Shows the versions of the File Format supported by ImageGear.
  • ImageGear Supported Features - Shows the ImageGear Format Filter features supported by ImageGear for this format. Please see the section Working with Format Filters.
  • ImageGear Read Support - Provides all compressions, color spaces, channels and bit depths supported by ImageGear for the file format reading.
  • ImageGear Write Support - Provides all compressions, color spaces, channels and bit depths supported by ImageGear for the file format writing.
  • ImageGear Filter Control Parameters - Provides all filter control parameters supported by ImageGear for this format filter. Please see also Working with Format Filters.
  • Comments - Some general information about format encoding and compression structure.
  • References Used - References to the information sources for the File Format.

Currently ImageGear supports the following File Formats:

  • Adobe DNG
  • Adobe PDF
  • Adobe PS
  • Adobe PSB
  • Adobe PSD
  • AFX
  • AVI
  • BMP
  • BTR
  • CAL
  • CGM
  • CLP
  • CUR
  • CUT
  • DCRAW
  • DCX
  • DGN
  • DIB
  • DICOM
  • DWF
  • DWG
  • DXF
  • EPS
  • EXIF-JPEG
  • EXIF-TIFF
  • FlashPix
  • GEM
  • GIF
  • Group 3
  • Group 3 2D
  • Group 4
  • HD Photo
  • Headerless Digital Camera RAW
  • HPGL
  • IBM AFP
  • IBM IOCA
  • IBM MO:DCA
  • ICO
  • IFF
  • IMG
  • IMR
  • IMT
  • JBIG2
  • JPEG
  • JPEG2000
  • JPX
  • KFX
  • LV
  • MAC
  • MAC PICT
  • Motion JPEG2000
  • MSP
  • MULTIMEDIA
  • NCR
  • PBM
  • PCD
  • PCX
  • PGM
  • PNG
  • PNM
  • PPM
  • PTOCA
  • QuickTime
  • RAS
  • RAW
  • Scitex CT
  • SGI
  • SVG
  • TGA
  • TIFF
  • TXT (ASCII Text)
  • U3D
  • WBMP
  • WMF
  • WPG
  • XBM
  • XPM
  • XPS
  • XWD


Adobe DNG

Full Name
Digital Negative file format
Format ID
IG_FORMAT_DNG = 108
File Extension(s)
*.dng
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC

ImageGear Supported versions:

  • Version 1.0.0.0
  • Version 1.1.0.0 - fixed incompatibility in JPEG Lossless compression, added new tags

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Grayscale: 9..16 bpp
    • RGB: 24, 48 bpp *
  • IG_COMPRESSION_JPEG:
    • Grayscale: 16 bpp
    • RGB: 24, 48 bpp *

* 8bpc DNG loading has been enabled via promoting the image to 16bpc before loading.

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
APPLY_COLORSPACE_CONVERSION
AT_BOOL
TRUE
TRUE,
FALSE
Set to TRUE to convert raw image to linear sRGB colorspace during loading. Has effect only if RECONSTRUCT_COLORS is TRUE.
APPLY_TONE_CORRECTION
AT_BOOL
TRUE
TRUE,
FALSE
Set to TRUE to automatically adjust image tone and apply sRGB gamma correction during loading. Has effect only if bothRECONSTRUCT_COLORS and APPLY_COLORSPACE_CONVERSION are TRUE.
RECONSTRUCT_COLORS
AT_BOOL
TRUE
TRUE,
FALSE
ImageGear attempts to reconstruct full color image from the camera raw image. Otherwise, ImageGear loads raw pixel data without any processing.

Comments

This file format was developed by Adobe as a non-proprietory format for unified storage of "raw" images from digital cameras. DNG image stores unprocessed pixel data obtained from camera's sensor, and keeps information about color, contrast and brightness adjustments, sharpening, as well as many other parameters, in its tags. This provides greater possibilities for image correction and enhancement, compared to commonly used formats such as JPEG, EXIF or TIFF.

The fact that the format is non-proprietary allows software vendors to provide support for DNG in their applications, with complete control over the image reconstruction process.

DNG extends TIFF/EP format. It adds a set of new tags for parameters that control reconstruction of full color image from the raw data.

References used

ADOBE SYSTEMS INCORPORATED. Digital Negative (DNG) specification.


Adobe PDF

Full Name
Adobe PDF (Adobe Portable Document Format)
Format ID
IG_FORMAT_PDF = 56
File Extension(s)
*.pdf
Data Type
Vector Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC, .NET

NOTE: To support PDF format ImageGear PDF Component should be attached to Core ImageGear.

ImageGear Supported versions:

  • Adobe® PDF version 1.7
  • Adobe® PDF version 1.6
  • Adobe® PDF version 1.5

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_MPAGEWRITEPSUPPORT - multipage file writing
  • IG_FLTR_PAGEDELETESUPPORT - page deleting from multi-page file
  • IG_FLTR_PAGESWAPSUPPORT - page swaping in multi-page files

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32 bpp
  • IG_COMPRESSION_DEFLATE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32 bpp
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G32D:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_JPEG:
    • Indexed RGB: 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32 bpp
  • IG_COMPRESSION_JPEG2K:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32 bpp
  • IG_COMPRESSION_JBIG2:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_LZW:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32 bpp
  • IG_COMPRESSION_DEFLATE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32 bpp
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G32D:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_JPEG:
    • Indexed RGB: 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32 bpp
  • IG_COMPRESSION_JPEG2K:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32 bpp
  • IG_COMPRESSION_JBIG2:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_LZW:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp

ImageGear Filter Control Parameters:

Please see the section PDF Format Filter Control Parameters.

Comments:

Please see the section Using ImageGear PDF Component.


Adobe PS

Full Name
Adobe PS (Adobe PostScript)
Format ID
IG_FORMAT_PS = 102
File Extension(s)
*.ps, *.eps
Data Type
Vector Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC, .NET

NOTE: To support PS format ImageGear PDF Component should be attached to Core ImageGear.

ImageGear Supported versions:

  • Adobe® PS v3

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_MPAGEWRITEPSUPPORT - multipage file writing
  • IG_FLTR_PAGEDELETESUPPORT - page deleting from multi-page file
  • IG_FLTR_PAGESWAPSUPPORT - page swaping in multi-page files

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1,4,8 bpp;
    • Grayscale - 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32bpp
  • IG_COMPRESSION_DEFLATE:
    • Indexed RGB: 1,4,8 bpp;
    • Grayscale - 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1,4,8 bpp;
    • Grayscale - 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32bpp
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G32D:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_JPEG:
    • Indexed RGB: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32bpp
  • IG_COMPRESSION_JPEG2K:
    • Indexed RGB: 1,4,8 bpp;
    • Grayscale - 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32bpp
  • IG_COMPRESSION_JBIG2:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_LZW:
    • Indexed RGB: 1,4,8 bpp;
    • Grayscale - 8 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1,4,8 bpp;
    • Grayscale - 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32bpp
  • IG_COMPRESSION_DEFLATE:
    • Indexed RGB: 1,4,8 bpp;
    • Grayscale - 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1,4,8 bpp;
    • Grayscale - 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32bpp
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G32D:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_JPEG:
    • Indexed RGB: 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32bpp
  • IG_COMPRESSION_JPEG2K:
    • Indexed RGB: 1,4,8 bpp;
    • Grayscale - 8 bpp;
    • RGB: 24 bpp;
    • CMYK: 32bpp
  • IG_COMPRESSION_JBIG2:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_LZW:
    • Indexed RGB: 1,4,8 bpp;
    • Grayscale - 8 bpp

ImageGear Filter Control Parameters:

Please see the section PostScript Filter Control Parameters.

Comments:

Please see the section Using ImageGear PDF Component.


Adobe PSB

Full Name
PSB (Adobe Photoshop Big)
Format ID
IG_FORMAT_PSB = 112
File Extension(s)
*.psb
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
Supports single Alpha channel for Read only. Supports aditional Alpha channels as ImageGear Extra channels for Read only.
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 2.0
  • Version 2.5
  • Version 3.0
  • Version 8.0

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_DEFLATE:
    • Indexed RGB: 1, 8 bpp;
    • Grayscale: 8, 16 bpp;
    • Grayscale + Alpha: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • RGB + Alpha: 32, 64 bpp;
    • RGB + Alpha + Extra 8, 16 bpc;
    • CMYK: 32, 64 bpp;
    • CMYK + Alpha: 40, 80 bpp;
    • CMYK + Alpha + Extra: 8, 16 bpc;
    • LAB + Alpha: 32, 64 bpp;
    • Lab + Alpha + Extra: 8, 16 bpc;
    • HSL + Alpha: 32, 64 bpp;
    • HSL + Alpha + Extra: 8, 16 bpc;
  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 8 bpp;
    • Grayscale: 8, 16 bpp;
    • Grayscale + Alpha: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • RGB + Alpha: 32, 64 bpp;
    • RGB + Alpha + Extra 8, 16 bpc;
    • CMYK: 32, 64 bpp;
    • CMYK + Alpha: 40, 80 bpp;
    • CMYK + Alpha + Extra: 8, 16 bpc;
    • LAB + Alpha: 32, 64 bpp;
    • Lab + Alpha + Extra: 8, 16 bpc;
    • HSL + Alpha: 32, 64 bpp;
    • HSL + Alpha + Extra: 8, 16 bpc;
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 8 bpp;
    • Grayscale: 8, 16 bpp;
    • Grayscale + Alpha: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • RGB + Alpha: 32, 64 bpp;
    • RGB + Alpha + Extra 8, 16 bpc;
    • CMYK: 32, 64 bpp;
    • CMYK + Alpha: 40, 80 bpp;
    • CMYK + Alpha + Extra: 8, 16 bpc;
    • LAB + Alpha: 32, 64 bpp;
    • Lab + Alpha + Extra: 8, 16 bpc;
    • HSL + Alpha: 32, 64 bpp;
    • HSL + Alpha + Extra: 8, 16 bpc;

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 8 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • CMYK: 32, 64 bpp;
    • Lab: 24, 48 bpp
  • IG_COMPRESSION_PACKED_BITS:
    • Indexed RGB: 1, 8 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • CMYK: 32, 64 bpp;
    • Lab: 24, 48 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
LOAD_FIRST_EXTRA_CHANNEL_AS_ALPHA
BOOL
FALSE
TRUE,
FALSE
This parameter specifies how ImageGear should load the first extra channel of a PSB image. If FALSE, ImageGear loads all extra channels according to their descriptors in the file header. If the channel contains transparency information, ImageGear loads it as Alpha channel. Otherwise IG loads it as Extra channel.
If TRUE, IG loads first extra channel as Alpha channel. This mode provides backward compatibility with previous versions of ImageGear.
READ_LAYER_INDEX
INT
-1
Any integer, but no more than number of layers
When > -1 specifies a zero based index of layer mask image to load, otherwise reads the composition image.
READ_LAYER_MASK
BOOL
FALSE
FALSE,
TRUE
When TRUE PSB layer mask images are loaded as usual pages of multipage file, otherwise layer masks are ignored.
SAVE_THUMBNAIL
BOOL
FALSE
FALSE,
TRUE
Gets/Sets thumbnail flag. If TRUE then thumbnail will be added to image.
THUMBNAIL_ENABLE
BOOL
FALSE
FALSE,
TRUE
When TRUE thumbnail reading function loads thumbnail image provided by PSB format.
THUMBNAIL_HEIGHT
UINT
64
Any positive value
Gets/Sets thumbnail height.
THUMBNAIL_WIDTH
UINT
64
Any positive value
Gets/Sets thumbnail width.

Comments:

PSB is a newer version of PSD designed for files over 2 gigabytes, supporting up to 300,000 pixels in any dimension. The PSB format is identical to the Photoshop native format (PSD) in many ways.

The PSD file is considered by many in the computer graphics arts community as an industry standard.

The PSD/PSB is organized into 5 major segments of data: the header, 3 informational blocks, and the bitmap data. The short header always contains a "signature" of 8PPS, as well as these fields: width, height, and bit depth of the bitmap.

The first block of informational data is called the "Color Mode Data Block". It begins with a value for the length of the block. If the image has a palette, it is located here.

The next block is called the "Image Resources Block". Like the previous block, it first gives the length of the block. An ID field is filled with one of many possible values that indicate the structure where the data is stored. It may contain such parameters as resolution.

The last informational block is called the "Layer and Mask Instruction Block". After a value for the length of the block, it tells how many "layer records" follow. There is a record for each layer in the image. Each record begins with a channel ID and the length of the data in the record. After the records, a "Layer Mask" section may be stored, if applicable.

The bitmap data represents the last segment of a PSD/PSB file.

NOTE: For historic reasons, ImageGear uses the IG_COMPRESSION_PACKED_BITS constant for saving Packed Bits compressed PSD/PSB images, and uses the IG_COMPRESSION_RLE constant to report Packed Bits compression when reading PSD/PSB images. For the PSD/PSB format, the terms "Packed Bits" and "RLE" are used synonymously.

References used

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats, 2d ed. Sebastopol, CA: O'Reilly & Associates, Inc., 1996.


Adobe PSD

Full Name
PSD (Adobe Photoshop)
Format ID
IG_FORMAT_PSD = 36
File Extension(s)
*.psd
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
Supports single Alpha channel for Read only. Supports aditional Alpha channels as ImageGear Extra channels for Read only.
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 2.0
  • Version 2.5
  • Version 3.0
  • Version 8.0

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_DEFLATE:
    • Indexed RGB: 1, 8 bpp;
    • Grayscale: 8, 16 bpp;
    • Grayscale + Alpha: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • RGB + Alpha: 32, 64 bpp;
    • RGB + Alpha + Extra 8, 16 bpc;
    • CMYK: 32, 64 bpp;
    • CMYK + Alpha: 40, 80 bpp;
    • CMYK + Alpha + Extra: 8, 16 bpc;
    • LAB + Alpha: 32, 64 bpp;
    • Lab + Alpha + Extra: 8, 16 bpc;
    • HSL + Alpha: 32, 64 bpp;
    • HSL + Alpha + Extra: 8, 16 bpc;
  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 8 bpp;
    • Grayscale: 8, 16 bpp;
    • Grayscale + Alpha: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • RGB + Alpha: 32, 64 bpp;
    • RGB + Alpha + Extra 8, 16 bpc;
    • CMYK: 32, 64 bpp;
    • CMYK + Alpha: 40, 80 bpp;
    • CMYK + Alpha + Extra: 8, 16 bpc;
    • LAB + Alpha: 32, 64 bpp;
    • Lab + Alpha + Extra: 8, 16 bpc;
    • HSL + Alpha: 32, 64 bpp;
    • HSL + Alpha + Extra: 8, 16 bpc;
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 8 bpp;
    • Grayscale: 8, 16 bpp;
    • Grayscale + Alpha: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • RGB + Alpha: 32, 64 bpp;
    • RGB + Alpha + Extra 8, 16 bpc;
    • CMYK: 32, 64 bpp;
    • CMYK + Alpha: 40, 80 bpp;
    • CMYK + Alpha + Extra: 8, 16 bpc;
    • LAB + Alpha: 32, 64 bpp;
    • Lab + Alpha + Extra: 8, 16 bpc;
    • HSL + Alpha: 32, 64 bpp;
    • HSL + Alpha + Extra: 8, 16 bpc;

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 8 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • CMYK: 32, 64 bpp;
    • Lab: 24, 48 bpp
  • IG_COMPRESSION_PACKED_BITS:
    • Indexed RGB: 1, 8 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • CMYK: 32, 64 bpp;
    • Lab: 24, 48 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
LOAD_FIRST_EXTRA_CHANNEL_AS_ALPHA
BOOL
FALSE
TRUE,
FALSE
This parameter specifies how ImageGear should load the first extra channel of a PSD image. If FALSE, ImageGear loads all extra channels according to their descriptors in the file header. If the channel contains transparency information, ImageGear loads it as Alpha channel. Otherwise IG loads it as Extra channel.
If TRUE, IG loads first extra channel as Alpha channel. This mode provides backward compatibility with previous versions of ImageGear.
READ_LAYER_INDEX
INT
-1
Any integer, but no more than number of layers
When > -1 specifies a zero based index of layer mask image to load, otherwise reads the composition image.
READ_LAYER_MASK
BOOL
FALSE
FALSE,
TRUE
When TRUE PSD layer mask images are loaded as usual pages of multipage file, otherwise layer masks are ignored.
SAVE_THUMBNAIL
BOOL
FALSE
FALSE,
TRUE
Gets/Sets thumbnail flag. If TRUE then thumbnail will be added to image.
THUMBNAIL_ENABLE
BOOL
FALSE
FALSE,
TRUE
When TRUE thumbnail reading function loads thumbnail image provided by PSD format.
THUMBNAIL_HEIGHT
UINT
64
Any positive value
Gets/Sets thumbnail height.
THUMBNAIL_WIDTH
UINT
64
Any positive value
Gets/Sets thumbnail width.

Comments:

The PSD file is considered by many in the computer graphics arts community as an industry standard.

The PSD is organized into 5 major segments of data: the header, 3 informational blocks, and the bitmap data. The short header always contains a "signature" of 8PPS, as well as these fields: width, height, and bit depth of the bitmap.

The first block of informational data is called the "Color Mode Data Block". It begins with a value for the length of the block. If the image has a palette, it is located here.

The next block is called the "Image Resources Block". Like the previous block, it first gives the length of the block. An ID field is filled with one of many possible values that indicate the structure where the data is stored. It may contain such parameters as resolution.

The last informational block is called the "Layer and Mask Instruction Block". After a value for the length of the block, it tells how many "layer records" follow. There is a record for each layer in the image. Each record begins with a channel ID and the length of the data in the record. After the records, a "Layer Mask" section may be stored, if applicable.

The bitmap data represents the last segment of a PSD file.

NOTE: For historic reasons, ImageGear uses the IG_COMPRESSION_PACKED_BITS constant for saving Packed Bits compressed PSD images, and uses the IG_COMPRESSION_RLE constant to report Packed Bits compression when reading PSD images. For the PSD format, the terms "Packed Bits" and "RLE" are used synonymously.

References used

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats, 2d ed. Sebastopol, CA: O'Reilly & Associates, Inc., 1996.


AFX

Full Name
Auto FX Photographic Edges
Format ID
IG_FORMAT_AFX = 49
File Extension(s)
*.afx
Data Type
Raster Image
Data Encoding
JPEG Lossy
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC, .NET

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

IG_COMPRESSION_JPEG - RGB: 24 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

No

Comments:

The Auto-FX file contains a small header followed by a JPEG datastream.


AVI

Full Name
MS Video for Windows video clip
Format ID
IG_FORMAT_AVI = 52
File Extension(s)
*.avi
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC

NOTE: To support AVI format ImageGear Multimedia Component should be attached to Core ImageGear.

ImageGear Supported versions:

N/A

ImageGear Supported Features:

    • IG_FLTR_DETECTSUPPORT - autodetection
    • IG_FLTR_PAGEREADSUPPORT - single page file reading
    • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 4, 8 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
FILE_NAME
String
""
any string
Obsolete. Not currently used.
IMAGE_IS_KEY_FRAME
Boolean
True
True, False
The filter will set this to True or False when reading an image depending on whether or not the image is marked as a key frame in the AVI file.

Comments:

AVI files are a special case of RIFF files. RIFF is the Resource Interchange File Format. This is a general purpose format for exchanging multimedia data types that was defined by Microsoft and IBM. An AVI file ("audio/video interleave") typically contains video and optionally audio which is synchronized to the video.

ImageGear can read video frame images from uncompressed and RLE compressed AVI files using this AVI format filter. To read AVI files which use other forms of compression, it's necessary to use the MULTIMEDIA format filter instead.


BMP

Full Name
Microsoft Windows Bitmap
Format ID
IG_FORMAT_BMP = 2
File Extension(s)
*.bmp, *dib
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Only for OS/2 BMP
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC, .NET, .NET64, Java

ImageGear Supported versions:

  • Windows Bitmap version 5 (created for Windows 98, Windows 2000)
  • Windows Bitmap version 4 (created for Windows 95, Windows NT 4.0)
  • Windows Bitmap version 3 (created for Windows 3.x)
  • Windows Bitmap version 2 (created for Windows 2.x)
  • OS/2 Bitmap version 2
  • OS/2 Bitmap version 1

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 15, 16, 24 bpp;
    • RGB + Alpha: 32 bpp.
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 4, 8 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 15, 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 4, 8 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
UPSIDE_DOWN
BOOL
FALSE
FALSE,
TRUE
If TRUE then the images will be saved upside-down
TYPE
UINT
BMP_TYPE_BMI
BMP_TYPE_BMC,
BMP_TYPE_BMI,
BMP_TYPE_BMI2
Type of BMP, see BMP_TYPE_... constants
COMPRESSION
DWORD
BMP_COMP_RGB
BMP_COMP_RLE4,
BMP_COMP_RLE8,
BMP_COMP_RGB
BMP compression, see BMP_COMP_... constants
B16_GRAY_SCANNER
BOOL
FALSE
FALSE,
TRUE
Vidar 12-bit scanner options
B16_GRAY_SCANTYPE
UINT
0
Vidar 12-bit scanner options

Comments:

The BMP format for versions 2.x - 4.x contains two headers. All Windows bitmap files begin with the same first header. They proceed with a data structure containing image information (the Bitmap Information Header), and end with the actual image data. If there is a palette (1, 4, 8-bit images), it is located between the bitmap information and the bitmap image data.

The first header identifies the format as BMP, and stores the file size and the address of the image. Two additional fields, Reserved1 and Reserved2, are not used and are set to 0.

The second header, known as the "bitmap information header", varies across the versions of Windows bitmaps. The second header for all bitmaps from version 2.x to 5.x have in common the following basic set of information: size of the secondary header in bytes, height and width of the image in pixels, the number of bit planes, the number of bits per pixel, compression scheme (0 = uncompressed, 1 = 4-bit RLE compression, 2 = 8-bit RLE compression, 3 = bitfields encoding was used), size of image in bytes, horizontal and vertical resolution in pixels per meter, the number of colors in the image, and the minimum number of important colors.

If the image is 16 or 32-bits per pixel in resolution, the compression field equals 3, and following the header are values for RedMask, GreenMask and BlueMask, rather than a palette. If the file is 4.x, there are values for an alpha component, color space type, x and y coordinates of red, green or blue endpoints, and gamma values for red, green, and blue coordinate scale values. The "ColorsImportant" field accommodates hardware that supports fewer colors than are contained by the image palette. The most significant colors are determined by counting their frequency of appearance. A value of zero means that all the colors in the image are significant.

The palette, or color table, varies in size depending on the number of colors in the image. This value is stored in the "ColorsUsed" field of the Bitmap Information Header. In the BMP format v. 3, the palette's structure is in "RGBQUAD" format. See the section entitled "Palettes" in for more information. 24-bit images do not use a palette, but rather store the color information directly in the image data.

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1996.


BTR

Full Name
Brooktrout
Format ID
IG_FORMAT_BRK = 3
File Extension(s)
*.brk, *.301,
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC, .NET, .NET64

ImageGear Supported versions:

Version 1

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetect
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_CCITT_G3 - Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G32D - Indexed RGB: 1 bpp

ImageGear Write Support:

  • IG_COMPRESSION_CCITT_G3 - Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G32D - Indexed RGB: 1 bpp
NOTE: When saving an image, the image must have horizontal resolution of 200 DPI and vertical resolution of 100 or 200 DPI.

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
COMPRESSION
WORD
BTR_COMP_G3
BTR_COMP_G3
BTR_COMP_G3_2D
Compression for saving.

Comments:

A Brooktrout file consists of a CCITT Group 3 (G3) compressed file with a 128-byte header designed by Brooktrout Technology. The header fields include a constant that identifies the file as Brooktrout, a version number, the horizontal and vertical resolutions of the image in dots/mm, the number of bits per pixel, and the number of pixels per line.


CAL

Full Name
CALS Raster
Format ID
IG_FORMAT_CAL = 4
File Extension(s)
*.cal, *.ras, *.cals
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC, .NET, .NET64, Java

ImageGear Supported versions:

  • Type II (Tiles made possible)
  • Type I

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

IG_COMPRESSION_CCITT_G4 - Indexed RGB : 1 bpp

ImageGear Write Support:

IG_COMPRESSION_CCITT_G4 - Indexed RGB : 1 bpp

ImageGear Filter Control Parameters:

No

Comments:

The CALS file format was created as a graphics format specification by The Department of Defense to standardize the data exchange of logistics support operations across the military branches and military contractors. It is mandatory for most military document-handling applications. It is no longer used solely by the military and its contractors; other government agencies and commercial businesses have also adopted this format, including the aerospace, commercial computer, and medical industries.

There are two types of CALS files: Type I, and a newer, significantly more complicated Type II. Type II supports the use of tiles. Sometimes it acts a repository for a group of Type I files. Whether or not a Type II contains Type I images determines what kind of compression scheme is used. Type I is supported by ImageGear.

Type I and Type II files begin with a header that has the same format and size. It includes information about the source and destination documents, as well as image characteristics data. The data storage units under the header are each 128 bytes in length, and are referred to as records. These are written with 7-bit ASCII characters, making it more "human-readable" than most file format headers.

The image data follows the header. In a Type II file, if the data is a series of Type I images, the images are encoded with CCITT Group 4 compression. If they are Type II files, the data may either be uncompressed or encoded with CCITT Group 4. In addition, Type II data may be stored in tiles, wherein some, all, or none of the tiles may be compressed.

The Type II file contains several more substructures than Type I. Between the header and the image data are three groups of document formatting data. Other data preceding each image (or images), are "layout information" and a "Tile Index", that contains the address of each tile stored for the image.

References used

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


CGM

Full Name
Computer Graphics Metafile
Format ID
IG_FORMAT_CGM = 75
File Extension(s)
*.cgm
Data Type
Metafile Vector Image
Data Encoding
Character-based, Binary, Clear-text encoded
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
Win32, Win64, .NET, .NET64

NOTE: To support CGM format ImageGear CAD/Vector CGM Component should be attached to Core ImageGear.

ImageGear Supported versions:

  • Version 1 (1987 standard)
  • Version 2
  • Version 3 (1992 standard)

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_MPAGEREADSUPPORT - multi-page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE - Vector/CAD data

ImageGear Write Support:

  • IG_COMPRESSION_NONE - Vector/CAD data

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
WIDTH
Long
512
Any positive value
Defines the DIB width of the loaded image. The DIB height is calculated using the file's scale factors.

Comments:

This is standardized platform-independent format used for the interchange of bitmap and vector data.

CGM is a very feature-rich format which attempts to support the graphic needs of many general fields (graphic arts, technical illustration, cartography, visualization, electronic publishing, and so on). While the CGM format is rich in features (many graphical primitives and attributes), it is less complex than PostScript, produces much smaller (more compact) files, and allows the interchange of very sophisticated and artistic images.

Computer Graphics Metafile was developed by experts working on committees under the auspices of the International Standards Organization (ISO) and the American Standards National Institute (ANSI). It was specifically designed as a common format for the platform-independent interchange of bitmap and vector data, and for use in conjunction with a variety of input and output devices. Although CGM incorporates extensions designed to support bitmap (called raster in the CGM specification) data storage, files in CGM format are used primarily to store vector information. CGM files typically contain either bitmap or vector data, but rarely both.


CLP

Full Name
Windows Clipboard
Format ID
IG_FORMAT_CLP = 5
File Extension(s)
*.clp
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC, .NET, .NET64

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 4, 8 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 4, 8 bpp

ImageGear Filter Control Parameters:

No

Comments:

The CLP file format represents a subset of a file format called Pictor PC Paint. The use for PC Paint format is to display images created by the PC Paint application to IBM display hardware (CGA, EGA, VGA, etc.).

The header of a CLP file is fairly short and simple, containing the file size (in bytes), and the height, width, and address of the image. The image data may be compressed or uncompressed. If it is compressed, the header contains two additional fields to give the number of bits per pixel of the packed data, and the address of the beginning of the packed run.

References used

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


CUR

Full Name
Windows cursor
Format ID
IG_FORMAT_CUR = 96
File Extension(s)
*.cur
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
Single alpha channel for read/write (see Comments).
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

Windows 3.x

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed + Extra: 1+1, 4+1, 8+1 bpp;
    • RGB + Alpha: 32 bpp
  • IG_COMPRESSION_RLE:
    • Indexed + Extra: 4+1, 8+1 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed + Extra: 1+1, 4+1, 8+1 bpp;
    • RGB + Alpha: 32 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
READ_AS_RGBA
Boolean
False
True,
False
If True, ImageGear reads CUR format as RGBA (RGB with alpha channel). See Comments for more detail.

Comments:

Cursor files consist of a file header (that is repeated several times), info headers, and cursor data. Cursor data contains an XOR mask bitmap and a monochrome AND mask bitmap. Whenever Windows draws a cursor, the AND bitmap is applied to whatever is on the screen. After that, the XOR bitmap is applied.

READ_AS_RGBA control parameter determines how ImageGear reads the 1-bit AND masks. If READ_AS_RGBA is False, ImageGear reads AND mask into "Extra" channel. This mode preserves unchanged pixel values from the file. However, in this mode ImageGear displays only the XOR mask and ignores AND mask (Extra channel) during display, i.e. display is not transparent. If READ_AS_RGBA is TRUE, ImageGear reads CUR files as 32 bpp RGB + Alpha. This allows transparent display.

Files must be 255x255 pixels or less.

References used:

© Jörn Daub EDV-Beratung - Glashütter Weg 105 - D-22889 Tangstedt

fileformats@daubnet.com


CUT

Full Name
Dr. Halo
Format ID
IG_FORMAT_CUT = 7
File Extension(s)
*.cut, *.pal (for the separately stored palette)
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, .NET, .NET64, Unix, Unix64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

IG_COMPRESSION_RLE - Indexed RGB: 8 bpp

ImageGear Write Support:

IG_COMPRESSION_RLE - Indexed RGB: 8 bpp

ImageGear Filter Control Parameters:

No

Comments:

The Dr. Halo file format is associated with the HALO Image File Format Library, the Dr. Halo III paint program, and other applications created by Media Cybernetics.

This format consists of two separate files, one with an extension of .CUT and the other with an extension of .PAL. The .CUT file contains the image data and the .PAL file contains the color palette.

The .CUT file begins with a simple header of just three data fields: width and height of the image data (pixels by scan lines), and a reserved field intended for use with any future expansions of the header. The image data is always RLE-encoded and follows the header.

The palette file (.PAL) contains a header, with information about the type of palette used, and the size and maximum values of the Red, Green, and Blue components. The palette can be hardware-specific, in which case it contains additional data.

When a CUT image is loaded into ImageGear, the palette is initialized to a grayscale ramp. In order to achieve the original colors of the palette (PAL file), it must be loaded separately into the HIGEAR image.

When saving an image into the Dr. Halo format, ImageGear creates a .CUT file. In order to save the palette (PAL file), it must be saved separately.

See the section RLE for more information.

References used

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


DCRAW

Full Name
Digital camera RAW file
Format ID
IG_FORMAT_DCRAW = 104
File Extension(s)
*.*
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC

ImageGear Supported versions:

Please see the section ImageGear Supported Digital Camera RAW Formats.

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Gray level: 10..16 bpp;
    • RGB: 48 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
APPLY_COLORSPACE_CONVERSION
AT_BOOL
TRUE
TRUE,
FALSE
Set to TRUE to convert raw image to linear sRGB colorspace during loading. Has effect only if RECONSTRUCT_COLORS is TRUE.
APPLY_TONE_CORRECTION
AT_BOOL
TRUE
TRUE,
FALSE
Set to TRUE to automatically adjust image tone and apply sRGB gamma correction during loading. Has effect only if both RECONSTRUCT_COLORS and APPLY_COLORSPACE_CONVERSION are TRUE.
RECONSTRUCT_COLORS
AT_BOOL
TRUE
TRUE,
FALSE
If TRUE, ImageGear attempts to reconstruct full color image from the camera raw image. Otherwise, ImageGear loads raw pixel data without any processing.

Comments:

Please see the section Working with ImageGear Digital Camera RAW Filter in Using ImageGear chapter.


DCX

Full Name
Paintbrush (Intel multi-page FAX format)
Format ID
IG_FORMAT_DCX = 8
File Extension(s)
*.dcx
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_MPAGEWRITEPSUPPORT - multipage file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
SAVE_COMPRESSED
BOOL
TRUE
FALSE,
TRUE
This parameters specify either compress output image or not. TRUE value cause to RLE compress image. FALSE cause to write image uncompressed.
ADD_IMAGE
BOOL
TRUE
FALSE,
TRUE
If this parameter is TRUE then image is added as additional page of multipage image. If FALSE then the new image with single page is written

Comments:

This file format was designed to allow multiple PCX files to be stored in one file. This is especially desirable for multi-page faxes (for which the PCX format is often used). Up to 1024 PCX images can be stored in one DCX file.

The DCX construct begins with a simple header, then the PCX files are simply stored end-to-end, complete with their individual headers and palettes. An array in the header called "Pagetable" contains offsets to each PCX. The one piece of vital information not stored with the PCX files under a DCX is their original filenames. See the PCX section of this manual for more about PCX files.

References used

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


DGN

Full Name
MicroStation Drawing (Drawing format used by MicroStation construction design software)
Format ID
IG_FORMAT_DGN = 73
File Extension(s)
*.dgn
Data Type
Vector image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
Win32, Win64, .NET, .NET64

NOTE: To support DGN format ImageGear CAD/Vector DGN Component should be attached to Core ImageGear.

ImageGear Supported versions:

  • DGN_VERSION_UNKNOWN
  • DGN_VERSION_DGN2
  • DGN_VERSION_DGN1_2D
  • DGN_VERSION_DGN1_3D
  • DGN_VERSION_CEL1_2D
  • DGN_VERSION_CEL1_3D

ImageGear Supported Features:

IG_FLTR_DETECTSUPPORT - autodetection

IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

IG_COMPRESSION_NONE - Vector/CAD data

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
BACKCOLOR
Long
0
Any positive value
This parameter is used to set background color. If nBackGroundColor=0, then a black background color is set, otherwise a white background color is set.
WIDTH
Long
512
Any positive value
Defines the DIB width of the loaded image. The DIB height is calculated using the file's scale factors.
FILENAME
String
""
N/A
Obsolete. Not currently used.

Comments:

DGN is a CAD file format used by Intergraph IGDS CAD software. It is not as commonly used as some other CAD file formats, but it has an open specification.


DIB

Full Name
DIB (Microsoft Windows Device Independent Bitmap)
Format ID
IG_FORMAT_DIB = 9
File Extension(s)
*.dib
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, .NET, .NET64

ImageGear Supported versions:

See BMP format description.

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 15, 16, 24 bpp;
    • RGB + Alpha: 32 bpp.
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 4, 8 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 15, 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 4, 8 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
UPSIDE_DOWN
BOOL
FALSE
FALSE,
TRUE
If TRUE then the images will be saved upside-down
TYPE
UINT
BMP_TYPE_BMI
BMP_TYPE_BMC,
BMP_TYPE_BMI,
BMP_TYPE_BMI2
Type of BMP, see BMP_TYPE_... constants
COMPRESSION
DWORD
BMP_COMP_RGB
BMP_COMP_RLE4,
BMP_COMP_RLE8,
BMP_COMP_RGB
BMP compression, see BMP_COMP_... constants
B16_GRAY_SCANNER
BOOL
FALSE
FALSE,
TRUE
Vidar 12-bit scanner options
B16_GRAY_SCANTYPE
UINT
0
Vidar 12-bit scanner options

Comments:

DIB is a synonym for the BMP format.


DICOM

Full Name
DICOM (Digital Imaging & Communication in Medicine)
Format ID
IG_FORMAT_DCM = 48
File Extension(s)
*.dicm, *.dcm
Data Type
Raster or vector image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix (Linux), .NET, .NET64

NOTE: To support DICOM format ImageGear Medical Component should be attached to Core ImageGear.

ImageGear Supported versions:

  • DICOM 3.0, 1991 - 2006

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_PAGEDELETESUPPORT - page deleting from multi-page file (only deletion of last page is supported)
  • IG_FLTR_MPAGEWRITEPSUPPORT - multipage file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Grayscale: 1, 8, 9-16, 32 bpp;
    • Indexed RGB: 8 bpp, 16 bpp (converted to 24-bit RGB during loading);
    • RGB: 24 bpp
    • Vector/waveform data
  • IG_COMPRESSION_JPEG (lossy):
    • Grayscale: 8, 9-12 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_JPEG (lossless):
    • Grayscale: 8, 9-16 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_JPEG2K:
    • Grayscale: 8, 9-16 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Grayscale: 8, 9-16 bpp;
    • Indexed RGB: 8 bpp, 16 bpp (converted to 24-bit RGB during loading);
    • RGB: 24 bpp

ImageGear also supports reading of Adobe PDF documents, encapsulated in DICOM files. See Adobe PDF format description for information on supported Adobe PDF features.

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Grayscale: 8, 9-16, 32 bpp;
    • Indexed RGB: 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_JPEG (lossy - baseline / process 1):
    • Grayscale: 8 bpp
    • RGB: 24 bpp
  • IG_COMPRESSION_JPEG (lossy - extended / process 2&4):
    • Grayscale: 8, 9-12 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_JPEG (lossless):
    • Grayscale: 8, 9-16 bpp;
    • Indexed RGB: 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_JPEG2K:
    • Grayscale: 8, 9-16 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Grayscale: 8, 9-16 bpp;
    • Indexed RGB: 8 bpp;
    • RGB: 24 bpp
NOTES: To use JPEG2000 compression scheme you should attach ImageGear JPEG2000 Component.

To be able to load encapsulated Adobe PDF documents you should attach ImageGear PDF Component.

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
DETECT_CONTINUOUS_RLE
BOOL
TRUE
TRUE,
FALSE
Set to TRUE for ImageGear to detect and load images where RLE runs across row boundaries.*)
LOAD_CONCAT_REPEATED_DE
BOOL
FALSE
TRUE, FALSE
TRUE to concatenate repeated data elements into one data element during loading. ****)
LOAD_CONVERTTO8G
BOOL
FALSE
TRUE,
FALSE
DEPRECATED
Use IG_image_channel_depths_change after image loading to change its channel depths.
Convert 9-16 bit gray to 8 on load.
LOAD_DETECTSKIPDIMSE
BOOL
FALSE
TRUE,
FALSE
Set to TRUE if files may contain DIMSE commands - that could throw off the format detection
LOAD_MASKALPHACHANNEL
BOOL
TRUE
TRUE,
FALSE
Rasters are masked off
LOAD_PAGENUMBER
UINT
1
Any positive integer value
DEPRECATED
Use IG_fltr_load_file to load specific page of an image.
Page number to load.
LOAD_SAVE_PIXDATA_TAG
BOOL
FALSE
TRUE,
FALSE
Set to TRUE to allow loading/saving pixel data to/from DataSet rather than to/from ImageGear DIB. **)
LOAD_SYNTAX
INT
MED_DCM_TS_AUTODETECT
MED_DCM_TS_ constants.
See file DataDict.h
Transfer Syntax to load DCM image with.
LOAD_USE_8x8_LUT
BOOL
TRUE
TRUE, FALSE
Set to TRUE to use 8x8 display LUT. Otherwise, use image's palette (the mechanism that was used in IG v15.0 and earlier). ***)
LOAD_USE_AUTO_WL_FOR_8G
BOOL
TRUE
TRUE, FALSE
Set to TRUE to use auto window/level for 8g images, if VOI LUT is not present. *****)
SAVE_ASPART10
BOOL
TRUE
TRUE,
FALSE
TRUE will cause the Header to be saved
SAVE_GROUPLENGTHS
BOOL
TRUE
TRUE,
FALSE
TRUE=include FALSE=exclude
SAVE_JPGQUALITY
UINT
70
1 - 100
DEPRECATED
Please use QUALITY control parameter of JPEG filter instead.
JPEG Quality setting 1-100
SAVE_LARGEST
BOOL
FALSE
TRUE,
FALSE
Include/exclude Largest Pixel Value when saving image.
SAVE_PLANARCONFIG
INT
MED_DCM_PLANAR_PIXEL_BY_PIXEL
MED_DCM_PLANAR_... constants
Planar configuration for saving image: MED_DCM_PLANAR_...
SAVE_SMALLEST
BOOL
FALSE
TRUE,
FALSE
Include/exclude Smallest Pixel Value when saving image.
SAVE_SYNTAX
INT
MED_DCM_TS_DEFAULT
MED_DCM_TS_ constants.
See file DataDict.h
Transfer Syntax to save DCM image with.

*) This parameter specifies what to do with RLE compressed images where RLE runs across row boundaries. If it is set to TRUE, ImageGear tries to detect and load images where RLE runs across row boundaries. Otherwise, ImageGear truncates any row overruns and decodes each row separately. This parameter does not affect the loading of properly encoded images, where each row is encoded separately.

**) When LOAD_SAVE_PIXDATA_TAG is TRUE, ImageGear does not read pixel data into a DIB, but rather creates an empty DIB, so the image cannot be displayed. When reading compressed image, IG Medical treats PixelData tag as a Sequence, and places actual binary data into Item tags. This corresponds to the structure of compressed PixelData in DICOM files. When using this parameter for writing, make sure that Transfer Syntax matches actual Transfer Syntax of the PixelData element.

***) Parameter LOAD_USE_8x8_LUT specifies the mechanism for display contrast adjustments of 8-bit grayscale images. Set to TRUE (default) to use 8x8 display LUT. Otherwise, use image's palette (the mechanism that was used in IG v15.0 and earlier).

****) Parameter LOAD_CONCAT_REPEATED_DE allows to load incompliant DICOM images where some data elements are cut into several repeated data elements. Instead of one data element containing an array of values, the data set contains several data elements, with the same group/element numbers pair, containing portions of the array. Specifically, there are images with look up tables and palettes stored in this way. Set LOAD_CONCAT_REPEATED_DE parameter to TRUE to concatenate repeated data elements into one data element during loading. Otherwise (default), ImageGear loads all of the repeated elements in the same way as they are located in the file. Note that ImageGear does not allow saving of repeated data elements. If a data set contains repeated data elements, ImageGear will only write first repeated element to the file.

*****) Parameter LOAD_USE_AUTO_WL_FOR_8G affects loading of 8-bit grayscale images that do not have a VOI LUT (either a LUT sequence or window center/width values). Set to TRUE to use auto window/level for these images. Set to FALSE to apply no window/levelling (set contrast range to 0...255).

Comments:

DICOM is a public standard created to provide a flexible and expandable means for storing, sharing, and transporting digital medical images. Today DICOM is the standard for medical imaging throughout the world.

DICOM image (alternately called Data Set) contains an ordered collection of attributes referred to as "Data Elements" that are related to one or more images. Each Data Element (DE) describes a single attribute of the image, patient, or study. The images themselves are also stored in DEs.

Each DICOM Data Set is transported through the Network, and consequently, stored in a file, using one of the defined Transfer Syntaxes. The Transfer Syntax of the DICOM file indicates whether the file uses Big Endian or Little Endian byte order, whether the image data is compressed or uncompressed, and if the DICOM Data Set uses Explicit or Implicit Value Representation (VR).

The Data Element (DE) is made up of the following parts:

  • Tag
  • Value Representation (optional)
  • Value Lenth
  • Value

Tag field identifies the type of information that is contained in the Value field (where the actual data is stored). The DICOM Data Dictionary (Part 6 of the specification) defines all possible public Data Element Tags that may be used. DICOM also allows applications to define and use private Tags and thus define their own Data Elements. Value Representation (VR) specifies the format of the Data Element Value, such as UL (unsigned long), ST (Short Text) or PN (Person Name). If Implicit Transfer Syntax is used, the VR field is omitted. It can be obtained from the standard or private Data Dictionary. Value Lenth is the lenth (in bytes) of the Data field.

DICOM also allows embedding (nesting) Data Sets within Data Sets. Nested Data Sets are implemented using a "Sequence of Items" (SQ), which is a special type of Data Element.

A special group of tags at the beginning of the file allows application to recognize the file as a DICOM image file, and includes information needed to decode the file (Transfer Syntax), and serial numbers to help locate and keep track of each field. This header is referred to as "File Meta Information Header", or "Part 10 Header" (since it is defined in Part 10 of the DICOM standard). While the standard clearly states that all DICOM image files must include a Part 10 Header, in reality one finds that many do not. Instead, the average DICOM image file is a simple data stream capture of the data into a file. This is called a "Raw Data" DICOM image file. In order to read a Raw DICOM the Transfer Syntax must be guessed at using a Transfer Syntax detection algorithm.

The actual pixel data for a DICOM image is stored in a Data Element, just like any other DICOM information. Image parameters, such as dimensions, bit depth, photometric interpretation etc., are also stored in Data Elements. The Tag for Pixel Data is called "Pixel Data" and has the Tag Number 7FE0, 0010. The Data Field in this Data Element contains all pixels for the image. Depending on the image's Transfer Syntax, the Pixel Data can be compressed or uncompressed.

References Used

Digital Imaging and Communication in Medicine (DICOM). Published by: National Electrical Manufacturers Association: http://medical.nema.org/dicom.html.


DWF

Full Name
DWF (Design Web Format)
Format ID
IG_FORMAT_DWF = 78
File Extension(s)
*.dwf, *.w2d, *.w3d
Data Type
Vector/CAD image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
Win32, Win64, .NET, .NET64

NOTE: To support DWF format ImageGear CAD/Vector DWF Component should be attached to Core ImageGear.

ImageGear Supported Versions:

  • Read:
    • DWF packages version 6.0...6.21
    • DWF streams up to version 0.55
    • W2D streams up to version 6.0.1
    • W3D streams up to version 13.0.5
  • Write:
    • DWF package version 6.21, with W2D stream version 6.01.

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE - Vector/CAD data

ImageGear Write Support:

  • IG_COMPRESSION_NONE - Vector/CAD data

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
WIDTH
Long
512
Any positive value
Defines the DIB width of the loaded image. The DIB height is calculated using the file's scale factors.
IMAGE_FORMAT
Long
IG_FORMAT_PNG
IG_FORMAT_BMP
IG_FORMAT_CAL
IG_FORMAT_GIF
IG_FORMAT_G4
IG_FORMAT_JPG
IG_FORMAT_PCX
IG_FORMAT_PCT
IG_FORMAT_PNG
IG_FORMAT_TGA
IG_FORMAT_TIF
Defines the internal format that will be used for saving raster data inside the DWF file. This only affects saving of raster images to DWF.

Comments

DWF is an open file format developed by AutoDesk for storing DWG files on the Internet. DWF contains a vector based description of drawings and illustrations. The format supports 2D and 3D drawings. Unlike DWG and DXF, DWF is focused on viewing only. It is intended to be used for publishing 2D and 3D CAD drawings so they can be easily viewed without requiring the use of CAD software.

The format also may contain an encapsulated raster image, in one of the following formats: BMP, CAL, GIF, CCITT Group4, JPEG, PCX, PCT, PNG, TGA, TIFF.


DWG

Full Name
DWG (AutoDesk AutoCAD)
Format ID
IG_FORMAT_DWG = 69
File Extension(s)
*.dwg
Data Type
Vector/CAD image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
Win32, Win64, .NET, .NET64

NOTE: To support DWG format ImageGear CAD/Vector DWG, DXF Component should be attached to Core ImageGear.

ImageGear Supported versions:

  • Read: Versions 2.5 through 2007
  • Write: Versions 12 through 2007

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

IG_COMPRESSION_NONE - Vector/CAD data

ImageGear Write Support:

IG_COMPRESSION_NONE - Vector/CAD data

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
BACKCOLOR
Long
0
Any positive value
This parameter is used to set background color. If nBackGroundColor=0, then a black background color is set, otherwise a white background color is set.
FILENAME
String
""
N/A
Obsolete. Not currently used.
FONTPATH
String
""
Any string up to 262 characters
Defines a path to the vector font files. Format - <Path1>;< Path2>;... .
LINEWIDTHDEF
Double
0
Any positive value
Default line width.
PASSWORD
String
""
Any string up to 262 characters
Used to set password for encrypted files before reading.
SHOWHIDDEN
Boolean
False
True, False
If true, hidden layers are shown by default.
TRUETYPE
Boolean
False
True, False
If true, TrueType font (Arial) are used for text drawing, otherwise vector fonts are used.
TTFWIDTH
Double
0
Any positive value
Relative default TrueType font width.
VERSION
String
ACAD2004
ACAD12 ACAD13 ACAD14 ACAD2000 ACAD2004 ACAD2007
Used to specify version to save the file as.
WIDTH
Long
512
Any positive value
Defines the DIB width of the loaded image. The DIB height is calculated using the file's scale factors.

Comments

DWG, short for "DraWinG", is a CAD file format which serves as the native file format for drawings created in AutoCAD.


DXF

Full Name
DXF (AutoDesk AutoCAD)
Format ID
IG_FORMAT_DXF = 70
File Extension(s)
*.dxf
Data Type
Vector/CAD image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
Win32, Win64, .NET, .NET64

NOTE: To support DXF format ImageGear CAD/Vector DWG, DXF Component should be attached to Core ImageGear.

ImageGear Supported versions:

  • Read: Versions 2.5 through 2007
  • Write: Versions 12 through 2007

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE - Vector/CAD data

ImageGear Write Support:

  • IG_COMPRESSION_NONE - Vector/CAD data

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
BACKCOLOR
Long
0
Any positive value
This parameter is used to set background color. If nBackGroundColor=0, then a black background color is set, otherwise a white background color is set.
FILENAME
String
""
N/A
Obsolete. Not currently used.
FONTPATH
String
""
Any string up to 262 characters
Defines a path to the vector font files. Format - <Path1>;< Path2>;... .
LINEWIDTHDEF
Double
0
Any positive value
Default line width.
PASSWORD
String
""
Any string up to 262 characters
Used to set password for encrypted files before reading.
SHOWHIDDEN
Boolean
False
True, False
If true, hidden layers are shown by default.
TRUETYPE
Boolean
False
True, False
If true, TrueType font (Arial) are used for text drawing, otherwise vector fonts are used.
TTFWIDTH
Double
0
Any positive value
Relative default TrueType font width.
VERSION
String
ACAD2004
ACAD12 ACAD13 ACAD14 ACAD2000 ACAD2004 ACAD2007
Used to specify version to save the file as.
WIDTH
Long
512
Any positive value
Defines the DIB width of the loaded image. The DIB height is calculated using the file's scale factors.

Comments

DXF is an AutoDesk graphics format (Drawing eXchange Format). Most CAD programs (PC-based) support this format. Compared to DWG, it is simpler and more broadly supported among different software.


EPS

Full Name
Encapsulated PostScript File
Format ID
IG_FORMAT_EPS = 10
File Extension(s)
*.eps (may or may not contain preview image), *.epi (contains preview image), *epsf
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix (full support with ImageGear PDF component only), Unix64, MAC, .NET

ImageGear Supported versions:

  • Version 3.0
  • Version 2.0
  • Version 1.0

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_JPEG:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_JPEG:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
SAVE_PREVIEW
BOOL
FALSE
TRUE,
FALSE
If TRUE then EPS preview will be saved
START
DWORD
0
Position of start.
FITTING_METHOD
UINT
IG_EPS_FIT_ACTUAL
IG_EPS_FIT_PAGE,
IG_EPS_FIT_ACTUAL,
IG_EPS_FIT_SET
Fitting method, see IG_EPS_FIT_... constants
PIXEL_TO_PIXEL
BOOL
FALSE
TRUE,
FALSE
PAGE_WIDTH
AT_DIMENSION
8500
Page width (100ths of an inch)
PAGE_HEIGHT
AT_DIMENSION
11000
Page height (100ths of an inch)
MARGINS
AT_RECT
{250, 250, 250, 250}
Margins (100ths of an inch)
X_DPI
UINT
300
X resolution
Y_DPI
UINT
300
Y resolution
TEXT_ENCODING
UINT
IG_PDF_TEXTENC_ASCII_HEX
IG_PDF_TEXTENC_NONE,
IG_PDF_TEXTENC_ASCII_85,
IG_PDF_TEXTENC_ASCII_HEX
Text encoding methos, see IG_PDF_TEXTENC_ constants

Comments

"PostScript" refers to a widely-supported general-purpose computer language that encodes text and graphics files for sharing with the many different hardware devices that support it. The full name for this language is "PostScript Page Description Language" (PDL).

An Encapsulated PostScript file stores (encapsulates) graphical or photographic images from a larger PostScript file. ImageGear currently supports the reading of EPS image of any bit depth as long as the preview image is TIF, uncompressed. ImageGear currently supports the writing of monochrome (1-bit) and grayscale (8-bit gray level) EPS images only.

The EPS file format begins with a PostScript language header. The data herein identifies the format as EPS, and gives the image title, creator, creation date, size and position of the image. Each line begins with a percent sign (%), which is normally interpreted in the PostScript language as the beginning of a comment line. Within the context of the EPS header, it takes on a different meaning.

Following the header is a block of PostScript code, which accomplishes the actual creation of the image.

The format proceeds with the bitmap data, or "graphics screen representation".

The EPI version of the EPS format, the version supported by ImageGear, contains an abridged interpretation of the image that is appended to the end of the file. It is usually smaller, and contains a lower resolution. One of the benefits of a preview image is that an application does not need to be able to interpret PostScript in order to display the image. Preview images are created with one of four file format types: TIFF, WMF, MAC PICT, and EPS in this chapter.

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


EXIF-JPEG

Full Name
Exchangeable image file format (EXIF-JPEG)
Format ID
IG_FORMAT_EXIF_JPEG = 71
File Extension(s)
*.jpg, *.xif
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Read/write
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC, .NET, .NET64

ImageGear Supported versions:

  • Version 1.0 (1996)
  • Version 1.1 (1997)
  • Version 2.0 (1998)
  • Version 2.1 (1998)
  • Version 2.2 (2002)

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_JPEG (lossy, progressive):
    • Grayscale: 8, 12 bpp;
    • RGB: 24, 36 bpp;
    • RGB + Alpha: 32 bpp;
    • CMYK: 32 bpp
  • IG_COMPRESSION_JPEG (lossless):
    • Grayscale: 8, 16 bpp;
    • RGB: 24 bpp;
    • RGB + Alpha: 32 bpp;
    • CMYK: 32 bpp

ImageGear Write Support:

  • IG_COMPRESSION_JPEG (lossy):
    • Grayscale: 8, 12 bpp;
    • RGB: 24, 36 bpp;
    • RGB + Alpha: 32 bpp1
    • CMYK: 32 bpp2
  • IG_COMPRESSION_JPEG (lossless):
    • Grayscale: 8, 16 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_JPEG (progressive):
    • Grayscale: 8, 12 bpp;
    • RGB: 24 bpp;

1) RGBA saving is disabled by default. Set JPEG-JFIF control parameter SAVE_ALLOW_RGBA to TRUE to enable it.

2) CMYK saving is enabled by default. You can disable it by setting JPEG-JFIF control parameter SAVE_ALLOW_CMYK to FALSE.

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
FLASHPIX_READY
BOOL
FALSE
TRUE,
FALSE
If TRUE the image will be saved with 64 interoperability, alowing lossless conversion to FlashPix format.
SAVE_JFIF_SEGMENT
BOOL
FALSE
TRUE,
FALSE
If TRUE the JFIF segment will be saved with image
SAVE_
THUMBNAIL
BOOL
TRUE
TRUE,
FALSE
If TRUE the thumbnail will be saved with image
THUMBNAIL_
WIDTH
UINT
160
Any positive value
The width of thumbnail
THUMBNAIL_
HEIGHT
UINT
120
Any positive value
The height of thumbnail
THUMBNAIL_
COMPRESSED
BOOL
TRUE
TRUE,
FALSE
For JPEG compressed EXIF. If TRUE the thumbnail will be JPEG compressed
LOAD_SCALE_DENOM
UINT
1
1, 2, 4, 8
If this parameter is set to any other than default value, ImageGear loads reduced version of the image, width and height of which are scaled by 1/load_scale_denom. This mode can be used for image preview, especially for those images that do not have embedded thumbnails, or where embedded thumbnails are smaller than desired. This mode allows you to make loading process 2-4 times faster.*

* LOAD_SCALE_DENOM parameter affects the following formats: JFIF-JPEG, EXIF-JPEG. It does not affect TIFF-JPEG and other formats containing JPEG stream. Only Lossy and Progressive compressed images are supported. It affects all image loading functions and all image info functions.

The following control parameters of JFIF-JPEG format filter also affect EXIF-JPEG:

  • SAVE_ALLOW_CMYK
  • SAVE_ALLOW_RGBA

Comments

The EXIF file format is based on existing formats. There are two kinds of EXIF format: compressed and uncompressed. Compressed EXIF is recorded in JPEG format with EXIF header saved in APP1 and APP2 marker segments. The APP2 segment is used when recording FlashPix extensions.

Uncompressed EXIF is recorded in TIFF Rev. 6.0 formats with two pages - the first is the main image, the second is a thumbnail (if it present). The EXIF header data is stored in TIFF 6.0 format for both compressed and uncompressed EXIF and include EXIF information (that is necessary) and GPS information (that is optional). Information specific to the camera system and not defined in TIFF is stored in private tags registered for EXIF. ImageGear EXIF support allows you to retrieve this information and send it to an application level and vice versa.

The EXIF image file specification also specifies the method for recording thumbnails. The reason for using the TIFF Rev. 6.0 tag format in the compressed file APP1 segment is to facilitate exchange of attribute data between EXIF compressed and uncompressed files.

Although the standard only allows uncompressed and JPEG-compressed EXIF images, and RGB colorspace, there are EXIF images that use other compressions and colorspaces. In a sence, these images can be considered as JPEGs or TIFFs with additional EXIF metadata. ImageGear supports reading of such non-standard images, as well as writing of Exif images with some non-standard compressions and colorspaces.

References used

Digital Still Camera Image File Format Standard (Exif) Version 2.0, Nov 1997, Japan Electronic Industry Development Association.

Digital Still Camera Image File Format Standard (Exif) Version 2.1, June 1998, Japan Electronic Industry Development Association.


EXIF-TIFF

Full Name
Exchangeable image file format (EXIF-TIFF)
Format ID
IG_FORMAT_EXIF_TIFF = 74
File Extension(s)
*.tif, *.xif
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Read only
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC, .NET, .NET64

ImageGear Supported versions:

  • Version 1.0 (1996)
  • Version 1.1 (1997)
  • Version 2.0 (1998)
  • Version 2.1 (1998)
  • Version 2.2 (2002)

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 1, 4, 8, 12, 16, 32 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 32, 48, 64 bpp;
    • RGB + Alpha: 8, 12, 16 bpc;
    • RGB + Alpha + Extra: 8, 12, 16 bpc;
    • Lab + Extra: 8, 12, 16 bpc;
    • CMYK + Extra: 8, 12, 16 bpc.
  • IG_COMPRESSION_PACKED_BITS:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 1, 4, 8, 12, 16, 32 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 32, 48, 64 bpp;
    • RGB + Alpha: 8, 12, 16 bpc;
    • RGB + Alpha + Extra: 8, 12, 16 bpc;
    • Lab + Extra: 8, 12, 16 bpc;
    • CMYK + Extra: 8, 12, 16 bpc.
  • IG_COMPRESSION_LZW:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 1, 4, 8, 12, 16, 32 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 32, 48, 64 bpp;
    • RGB + Alpha: 8, 12, 16 bpc;
    • RGB + Alpha + Extra: 8, 12, 16 bpc;
    • Lab + Extra: 8, 12, 16 bpc;
    • CMYK + Extra: 8, 12, 16 bpc.
  • IG_COMPRESSION_DEFLATE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 1, 4, 8, 12, 16, 32 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 32, 48, 64 bpp;
    • RGB + Alpha: 8, 12, 16 bpc;
    • RGB + Alpha + Extra: 8, 12, 16 bpc;
    • Lab + Extra: 8, 12, 16 bpc;
    • CMYK + Extra: 8, 12, 16 bpc.
  • IG_COMPRESSION_HUFFMAN:
    • Indexed RGB: 1 bpp;
    • Grayscale: 1 bpp;
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp;
    • Grayscale: 1 bpp;
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp;
    • Grayscale: 1 bpp;
  • IG_COMPRESSION_CCITT_G32D:
    • Indexed RGB: 1 bpp;
    • Grayscale: 1 bpp;
  • IG_COMPRESSION_JPEG (Lossy):
    • Grayscale: 8, 12 bpp;
    • RGB: 24, 36 bpp;
  • IG_COMPRESSION_JPEG (Lossless):
    • Grayscale: 8, 16 bpp;
    • RGB: 24 bpp;

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Grayscale: 8, 12, 16 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 32, 48, 64 bpp.
  • IG_COMPRESSION_PACKED_BITS:
    • Grayscale: 8, 12, 16 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 32, 48, 64 bpp.
  • IG_COMPRESSION_LZW:
    • Grayscale: 8, 12, 16 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 32, 48, 64 bpp.
  • IG_COMPRESSION_DEFLATE:
    • Grayscale: 8, 12, 16 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 32, 48, 64 bpp.
  • IG_COMPRESSION_JPEG (Lossy):
    • Grayscale: 8, 12 bpp;
    • RGB: 24, 36 bpp;
  • IG_COMPRESSION_JPEG (Lossless):
    • Grayscale: 8, 16 bpp;
    • RGB: 24 bpp;

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
SAVE_
THUMBNAIL
BOOL
TRUE
TRUE,
FALSE
If TRUE the thumbnail will be saved with image
THUMBNAIL_
WIDTH
UINT
160
Any positive value
The width of thumbnail
THUMBNAIL_
HEIGHT
UINT
120
Any positive value
The height of thumbnail

Comments

The EXIF file format is based on existing formats. There are two kind of EXIF format: compressed and uncompressed. Compressed EXIF is recorded in JPEG format with EXIF header saved in APP1 and APP2 marker segments. The APP2 segment is used when recording FlashPix extensions.

Uncompressed EXIF is recorded in TIFF Rev. 6.0 formats with two pages - the first is the main image, the second is a thumbnail (if it present). The EXIF header data is stored in TIFF 6.0 format for both compressed and uncompressed EXIF and include EXIF information (that is necessary) and GPS information (that is optional). Information specific to the camera system and not defined in TIFF is stored in private tags registered for EXIF. ImageGear EXIF support allows you to retrieve this information and send it to an application level and vice versa.

The EXIF image file specification also specifies the method for recording thumbnails. The reason for using the TIFF Rev. 6.0 tag format in the compressed file APP1 segment is to facilitate exchange of attribute data between EXIF compressed and uncompressed files.

Although the standard only allows uncompressed and JPEG-compressed EXIF images, and RGB colorspace, there are EXIF images that use other compressions and colorspaces. In a sence, these images can be considered as JPEGs or TIFFs with additional EXIF metadata. ImageGear supports reading of such non-standard images, as well as writing of Exif images with some non-standard compressions and colorspaces.

References used

Digital Still Camera Image File Format Standard (Exif) Version 2.0, Nov 1997, Japan Electronic Industry Development Association.

Digital Still Camera Image File Format Standard (Exif) Version 2.1, June 1998, Japan Electronic Industry Development Association.


FlashPix

Full Name
FlashPix
Format ID
IG_FORMAT_FPX = 50
File Extension(s)
*.fpx
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Read only, converted to RGB during loading.
IG Platforms Support
WIN32

NOTE: To support FlashPix format ImageGear FlashPix Component should be attached to Core ImageGear.

ImageGear Supported versions:

Version 1.0.0

Version 1.0.1

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • Grayscale + Alpha: 16 bpp (converted to RGB during loading);
    • RGB + Alpha: 16 bpp (converted to RGB during loading);
  • IG_COMPRESSION_FPX_SINCOLOR:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • Grayscale + Alpha: 16 bpp (converted to RGB during loading);
    • RGB + Alpha: 16 bpp (converted to RGB during loading);
  • IG_COMPRESSION_JPEG:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
  • IG_COMPRESSION_FPX_NOCHANGE:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
  • IG_COMPRESSION_FPX_SINCOLOR:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
  • IG_COMPRESSION_JPEG:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
DISABLETRANSFORMS
BOOL
FALSE
TRUE,
FALSE
Set to TRUE to load the image without applying geometric and color transforms that are specified in the metadata
LOADOPTION
MODE
IG_FPX_LOAD_DEFAULT
IG_FPX_LOAD_DEFAULT = 0, IG_FPX_LOAD_NOLESS = 1, IG_FPX_LOAD_NOGREATER = 2
Allows to select a resolution according to specified page width and height. *)
PAGEBACKGROUND
RGBQUAD
{0, 0, 0, 0};
RGBQUAD
Background to use for images that have Alpha channel.
PAGEHEIGHT
AT_DIMENSION
0
AT_DIMENSION
See LOADOPTION
PAGEWIDTH
AT_DIMENSION
0
AT_DIMENSION
See LOADOPTION
QUALITY
UINT
70
1...100
Quality to use for saving JPEG compressed FPX images
SAVEFROMDIB
BOOL
TRUE
TRUE,
FALSE
TRUE to save pixel data from HIGEAR. FALSE to save pixel data that were loaded from FlashPix image and stored internally. This allows changing FlashPix metadata, including geometric and color transforms, and saving the image without changing its original pixel data.
SETSCANNEDIMGSIZE
BOOL
FALSE
TRUE,
FALSE
Use HIGEAR resolution to set ScannedImageSize tag when saving the image

*) Set to IG_FPX_LOAD_DEFAULT to load the highest (or the only) resolution in the resolution hierarchy. Set to IG_FPX_LOAD_NOLESS to load the lowest resolution which dimensions are not less than PAGEWIDTH and PAGEHEIGHT parameters. Set to IG_FPX_LOAD_NOGREATER to load the highest resolution which dimensions are not greater than PAGEWIDTH and PAGEHEIGHT parameters.

Comments

The FlashPix File Format was created to make the desktop handling of digital color photographic images easy, enjoyable, affordable, and commonplace. It was developed and published by Eastman Kodak Company in collaboration with Hewlett-Packard, Live Picture Inc. and Microsoft.

Kodak is marketing the Kodak Image Magic system, which includes such components as a FlashPix CD, digital cameras, scanners, and print services - that can be accessed through the internet, or through your local film developer. You do not, however, have to use digital equipment to put your photographs onto CD. You can still take your "old-fashioned" camera film to a film developer and request that it be sent to Kodak for transfer to a CD. You can also bring in existing negatives and have them transferred to CD. Ultimately, Kodak envisions a world where amateur PC users can put their latest photographs into digital storage, improve them and enhance them, drop them into card or calendar templates, and E-mail them off to Grandma and Grandpa's home computer.

When you think FlashPix file format, three major structural features should come to mind: Source Plus Transform storage scheme, hierarchy of resolutions, and tiled storage. These three key features best illustrate the purpose of the format and also set it apart from most others.

  • The Source Plus Transform storage scheme refers to Kodak's use of "transformation parameters". This set of non-image data tags (fields) stores the last set of FlashPix-specific transformations that were made to the image. In this unique storage scheme the bitmap data and the transformations for it are stored separately. This keeps the bitmap data in its original state. The bitmap data, or "source image" of a FlashPix image is never directly altered by a FlashPix transformation. One of the reasons for this structure is that it allows the end-user of a FlashPix application always to be able to return to the source image if their transformations have gotten out-of-hand. Transformation parameters can be applied (enabled) to the source image when the image is being displayed, or they can be "turned off" (disabled) so that the unaltered source image is displayed. The API functions IG_FPX_enable() and IG_FPX_disable() are used for this purpose, respectively. Additionally, you can "burn in" the transformations directly to the DIB, if so desired.
  • The "hierarchy of resolutions" refers to the multiple pages with which FlashPix stores several versions of the same image - each with a different resolution. The highest resolution image represents the first image or "page" of a FlashPix file. Each subsequent image is at a lower resolution. The resolution hierarchy was developed in the interest of optimizing speed during image loading. The lower resolution images can be used for display, depending on the capability of the monitor, and the highest resolution image will always be used for printing. Kodak likes to refer to this storage as being like a pyramid.

The FlashPix is available as an ImageGear component, which brings you the core of the FlashPix features:

  • a full hierarchy of resolutions for each image,
  • a "Source Plus Transform" storage scheme for easy "undos" and no loss of image quality, no matter how many transformations are applied,
  • a choice of JPEG or Single Color compression,
  • a details-oriented stash of non-image data (title, subject, people in the picture, creation date, etc.),
  • thumbnail support,
  • tiled storage,
  • and the use of all ImageGear functions to load, save, and transform FlashPix images.
  • a special FlashPix-specific API, including functions that make reading and writing of non-image information easy,
  • the ability to perform all FlashPix transformations on any ImageGear image,
  • the ability to perform ImageGear transformations without losing FlashPix transformations.


GEM

Full Name
GEM Raster
Format ID
IG_FORMAT_GEM = 13
File Extension(s)
*.gem
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

IG_COMPRESSION_RLE - 1, 4, 8 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

No

Comments

A deal with the creators of Ventura Publisher made this a significant format in the desktop publishing arena. It was also distributed by PC systems manufacturers and was the native bitmap format of the Atari ST system.

The structure of a GEM Raster image file begins with a fixed-length header and is followed by the bitmap data.

The data fields of the header include the version number (always 1), image width (in pixels), and image height (in scan lines). A field named "Headerlength" contains a value of either 8 or 9, where 9 indicates that an optional field appears at the end, called "BitImageFlag". This field is directly tied with a "NumberOfPlanes" field. If "NumberOfPlanes" is greater than 1, the BitImageFlag indicates whether the image is color or grayscale. (BitImageFlag = 0 = color, BitImageFlag = 1 = grayscale).

Two fields in the header that are a little unusual among bitmap formats are the width and height of the pixels (in microns), and a field called "PatternLength". PatternLength is the length of any pattern that will be decoded. It is used by the RLE compression scheme, which assigns one of four different kind of codes to store each of the four different types of repeat data in the image. The "pattern code" indicates that a pattern is available. The pattern and repeat count are decoded while reading the file.

For more on RLE compression, see the ImageGear Supported Compressions Reference section in this chapter.

References used

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


GIF

Full Name
CompuServe Graphics Interchange Format (GIF)
Format ID
IG_FORMAT_GIF = 14
File Extension(s)
*.gif
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

NOTE: To support GIF format ImageGear GIF/TIFF-LZW Component should be attached to Core ImageGear.

ImageGear Supported versions:

  • Version 89a, 1989: added ability to store both text and graphics in same file.
  • Version 87a, 1987: first version; still read by major applications supporting GIF.

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_MPAGEWRITEPSUPPORT - multipage file writing

ImageGear Read Support:

IG_COMPRESSION_LZW - Indexed RGB: 1, 4, 8 bpp

ImageGear Write Support:

IG_COMPRESSION_LZW - Indexed RGB: 1, 4, 8 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
VERSION
INT
89
87; 89
Sets version of GIF file to be saved.
INTERLACE
BOOL
FALSE
TRUE,
FALSE
Sets GIF interlace mode to be used on saving.

Comments

This is a very popular format for storing graphics images on Web pages. It is also supported by most applications that handle graphical image data.

Unisys, the owner of the LZW compression used on all GIF files, declared at the end of 1995 that it will charge a royalty fee to all developers wishing to use this compression scheme. (This drove many developers to search for a replacement file format. A new file format called PNG ("Ping") was created. The PNG format is supported by ImageGear; see the PNG section of this chapter for more information.) However, worldwide GIF-related patents expired in 2004 and the format is once again free to use without the need to pay royalties to Unisys.

While the GIF format is designed to store multiple images, few GIF format viewers support this. For this reason, it is not advisable to store more than one image in a GIF file.

The GIF layout is fairly complex; it can include several categories of "blocks" under which subcategories of blocks may occur.

For both the 89a and 87a versions, the first three blocks are the header, the Logical Source Descriptor, and the Global Color Table. The header simply identifies the file as a GIF and gives the version number. The Logical Source Descriptor is very similar to a header, and is sometimes stored within the header. It contains information about the display screen and color table.

GIFs contain two kinds of color tables: a "Global Color Table" and "Local Color Table." The Global Color Table is used as a table for the pixel values of all images contained within the GIF file. Optionally, the Local Color Table block that is provided for each image can contain data specific to an individual image.

In addition to a local color table, each image is associated with another block of data, the Local Image Descriptor, provides the size and location of the image, and data about its color table.

GIF89a is equipped with four new types of blocks called "Control Extensions". The most significant group of these are the "Graphics Control Extension Blocks" that enable the simultaneous storing and displaying of textual and graphical data, including multiple images, resulting in a "multimedia presentation". The functions provided by these blocks include setting the transparency or opacity of the images, restoring or deleting images, and overlaying captions (that are not part of the actual bitmap) on images.

GIF image data is always stored in LZW-compressed form. The data may also be interlaced. Interlacing helps the appearance of an image as it displays while being decompressed, so that it "fades in". In a non-interlaced file, the presentation of the image data begins with row 1 and works downward to the last row of data. This method of display does not allow a quick preview of the whole image. When the data is interlaced, the lines are saved and displayed out of sequence. Every fourth row is displayed first and then filled in with every remaining fourth row, until all of the lines are displayed. This allows the eye to perceive the basic subject of the whole image before it is completely displayed.

See also:

GIF Non-image Data Structure

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


Group 3

Full Name
Group 3 (G3)
Format ID
IG_FORMAT_G3 = 11
File Extension(s)
*.raw
Data Type
Raw image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
Win32, Win64, Unix, Java, Unix64

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

IG_COMPRESSION_CCITT_G3 - Indexed RGB: 1 bpp

ImageGear Write Support:

IG_COMPRESSION_CCITT_G3 - Indexed RGB: 1 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
WIDTH
DIMENSION
0
Any positive
value
Image width
HEIGHT
DIMENSION
0
Any positive
value
Image height
FILL_ORDER
UINT
1
FillOrder = 2, for inverse bit order in byte
PACKED
BOOL
FALSE
TRUE,
FALSE
Currently not in use. Reserved for the future.
K_FACTOR
UINT
2
K - factor for 2D coding

Comments

ImageGear does not try to automatically detect raw Group3 data. Use one of the raw file loading functions, or specify format explicitly. Please see the sections Loading Images and Saving Images.


Group 3 2D

Full Name
Group 3 2D
Format ID
IG_FORMAT_G32D = 53
File Extension(s)
*.raw
Data Type
Raw image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
Win32, Win64, Unix, Java, Unix64

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

IG_COMPRESSION_CCITT_G32D - Indexed RGB: 1 bpp

ImageGear Write Support:

IG_COMPRESSION_CCITT_G32D - Indexed RGB: 1 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
WIDTH
DIMENSION
0
Any positive
value
Image width
HEIGHT
DIMENSION
0
Any positive
value
Image height
FILL_ORDER
UINT
1
FillOrder = 2, for inverse bit order in byte
PACKED
BOOL
FALSE
TRUE,
FALSE
Currently not in use. Reserved for the future.
K_FACTOR
UINT
2
K - factor for 2D coding

Comments

ImageGear does not try to automatically detect raw Group3 data. Use one of the raw file loading functions, or specify format explicitly. Please see the sections Loading Images and Saving Images.


Group 4

Full Name
Group 4
Format ID
IG_FORMAT_G4 = 12
File Extension(s)
*.raw
Data Type
Raw image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
Win32, Win64, Unix, Java, Unix64

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

IG_COMPRESSION_CCITT_G4 - Indexed RGB: 1 bpp

ImageGear Write Support:

IG_COMPRESSION_CCITT_G4 - Indexed RGB: 1 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
WIDTH
DIMENSION
0
Any positive
value
Image width
HEIGHT
DIMENSION
0
Any positive
value
Image height
FILL_ORDER
UINT
1
FillOrder = 2, for inverse bit order in byte
PACKED
BOOL
FALSE
TRUE,
FALSE
Currently not in use. Reserved for the future.
K_FACTOR
UINT
2
K - factor for 2D coding

Comments

ImageGear does not try to automatically detect raw Group3 data. Use one of the raw file loading functions, or specify format explicitly. Please see the sections Loading Images and Saving Images.


HD Photo

Full Name
HD Photo (formerly Windows Media Photo)
Format ID
IG_FORMAT_HDP = 110
File Extension(s)
*.hdp, *.wdp
Data Type
Raster image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Yes
IG Platforms Support
WIN32 (DLL only), WIN64, .NET, .NET64

NOTE: To support HD Photo format ImageGear HD Photo Component should be attached to Core ImageGear.

ImageGear Supported versions:

  • 1.0

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_HDP:
    • Grayscale: 1, 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • RGBA: 32, 64 bpp;
    • RGBPA: 32, 64 bpp;
    • CMYK: 32, 64 bpp;
    • CMYKEx: 40, 80 bpp;
    • Extra: 3...9 channels x 8, 16 bpp;

ImageGear Write Support:

  • IG_COMPRESSION_HDP:
    • Grayscale: 1, 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • RGBA: 32, 64 bpp;
    • RGBPA: 32, 64 bpp;
    • CMYK: 32, 64 bpp;
    • CMYKEx: 40, 80 bpp;
    • Extra: 3...9 channels x 8, 16 bpp;

ImageGear Filter Control Parameters:

Name
Type
Default value
Available values
Description
Lossless
AM_TID_AT_BOOL
FALSE
TRUE, FALSE
Setting this parameter to TRUE enables lossless compression mode.
ImageQuality
AM_TID_DOUBLE
0.9
Any Double value in range 0.0...1.0
Specifies image quality. 0.0 specifies lowest quality, 1.0 specifies highest quality (lossless mode). 1)
BitmapTransform
AM_TID_AT_MODE
0
One or combination of the following values:
0x00000000 (Rotate 0),
0x00000001 (Rotate 90),
0x00000002 (Rotate 180),
0x00000003 (Rotate 270),
0x00000008 (Flip Horizontal), 0x00000010 (Flip Vertical)
This parameter is stored as the BitMapTransform value in the compressed bit stream header, controlling how the image will be transformed during decode.
UseAdvancedParameters
AM_TID_AT_BOOL
FALSE
TRUE, FALSE
Specifies whether standard or advanced parameters should be used.
Advanced.Quality
AM_TID_BYTE
1
1...255
Controls quantization of the main image. A value of 1 sets lossless mode (no quantization). Increasing values result in greater quantization and thus greater compression ratios and lower image quality. This parameter is tightly related with Advanced.Subsampling and Advanced.Overlap parameters, and its behavior may differ depending on source image content. If the application needs a single parameter to control image quailty, the use of the basic ImageQuality parameter is recommended.
Advanced.Overlap
AM_TID_BYTE
0
0, 1, 2
This parameter selects the optional overlap processing level. 2)
Advanced.Subsampling
AM_TID_BYTE
3
0, 1, 2, 3
Enables additional compression in the chroma space, preserving luminance detail at the expense of color detail. Only applies to RGB images 3)
Advanced.HorizontalTileSlices
AM_TID_WORD
0
0...4096
Specifies horizontal tiling of the image. 0 means no horizontal subdividions (1 tile), 1 means 2 horizontal tiles, etc.
Advanced.VerticalTileSlices
AM_TID_WORD
0
0...4096
Specifies vertical tiling of the image. 0 means no vertical subdividions (1 tile), 1 means 2 vertical tiles, etc.
Advanced.FrequencyOrder
AM_TID_AT_BOOL
TRUE
TRUE, FALSE
Specifies that the image must be encoded in frequency order, with the lowest frequency data appearing first in the file, and image content grouped by its frequency rather than its spatial orientation. Organizing a file by frequency order provides the highest performance results for any frequency-based decoding, and is the preferred option.
Advanced.InterleavedAlpha
AM_TID_AT_BOOL
FALSE
TRUE, FALSE
Specifies whether to encode Alpha channel as an additional interleaved channel, or as a planar alpha channel, encoded as a separate image with its own optional Quality value. Interleaved alpha channels are only supported for certain RGB pixel formats. A Planar alpha channel can be associated with any image format that defines an alpha channel.
Advanced.AlphaQuality
AM_TID_BYTE
1
1...255
Specifies quantization for the planar alpha channel image. A value of 1 sets lossless mode (no quantization). Increasing values result in greater quantization and thus greater compression ratios and lower alpha quality.
Advanced.CompressedDomainTranscode
AM_TID_AT_BOOL
TRUE
TRUE, FALSE
Not used
Advanced.ImageDataDiscard
AM_TID_BYTE
0
0...3
Not used
Advanced.AlphaDataDiscard
AM_TID_BYTE
0
0...4
Not used
Advanced.IgnoreOverlap
AM_TID_AT_BOOL
FALSE
TRUE, FALSE
Not used

1) Quality value maps to specific WMPhoto encoder parameters based on the following table:

ImageQuality
Advanced.Quality (BD<=8)
Advanced.Quality (BD<=16)
Advanced.Quality (BD>16)
Advanced.
Subsampling
Advanced .Overlap
>0.0 <0.4
105-IQ*100
185-IQ*180
245-IQ*240
4:4:4
2
>0.4 <1.0
105-IQ*100
185-IQ*180
245-IQ*240
4:4:4
1
1.0
1
1
1
4:4:4
0

2) Selects the optional overlap processing level

0
No overlap processing is enabled.
1
One level of overlap processing is enabled, modifying 4x4 block encoded values based on values of neighboring blocks.
2
Two levels of overlap processing are enabled; in addition to the first level processing, encoded values of 16x16 macro blocks are modified based on the values of neighboring macro blocks.

3) Allowed values for Advanced.Subsampling parameter are:

3
4:4:4 encoding preserves full chroma resolution.
2
4:2:2 encoding reduces chroma resolution to ½ of luminance resolution.
1
4:2:0 encoding reduces chroma resolution to ¼ of luminance resolution.
0
4:0:0 encoding discards all chroma content, preserving luminance only. Because the codec uses a slightly modified definition of luminance to improve performance, it is preferred to convert an RGB image to monochrome before encoding rather than use this chroma subsampling mode.

Comments:

HD Photo is a new file format for continuous-tone still images that surpasses the limitations of existing image formats. HD Photo supports a wide range of features including:

  • Multiple color formats for display or print
  • Fixed or floating point high-dynamic-range image encoding
  • Lossless or high-quality lossy compression
  • Efficient decoding for multiple resolutions and subregions
  • Minimal overhead for format conversion or transformations during decode

HD Photo delivers a lightweight, high performance algorithm with a small memory footprint that enables practical, in-device encoding and decoding. It delivers compression quality comparable with JPEG-2000 and more than twice the quality of JPEG.

HD Photo is the new name for Windows Media Photo. Both names refer to the exact same file format. The Windows Media Photo name is still used to describe the implementation of HD Photo in existing Windows products.

See Also

HD Photo Non-Image Data Structure

References Used

HD Photo v.1.0 Feature Specification.

http://www.microsoft.com/windows/windowsmedia/forpros/wmphoto/default.aspx


Headerless Digital Camera RAW

Full Name
Headerless Digital Camera file
Format ID
IG_FORMAT_HLDCRAW = 114
File Extension(s)
*.*
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC, Net, Net64

ImageGear Supported versions:

Please see the section ImageGear Supported Digital Camera RAW Formats.

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Gray level: 10..16 bpp;
    • RGB: 48 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
RECONSTRUCT_COLORS
AT_BOOL
TRUE
TRUE,
FALSE
If TRUE, ImageGear attempts to reconstruct full color image from the camera raw image. Otherwise, ImageGear loads raw pixel data without any processing. See also APPLY_COLORSPACE_CONVERSION and APPLY_TONE_CORRECTION parameters.
APPLY_COLORSPACE_CONVERSION
AT_BOOL
TRUE
TRUE,
FALSE
Set to TRUE to convert raw image to linear sRGB colorspace during loading. Has effect only if RECONSTRUCT_COLORS is TRUE.
APPLY_TONE_CORRECTION
AT_BOOL
TRUE
TRUE,
FALSE
Set to TRUE to automatically adjust image tone and apply sRGB gamma correction during loading. Has effect only if bothRECONSTRUCT_COLORS and APPLY_COLORSPACE_CONVERSION are TRUE.

Comments:

Headerless Digital Camera file filter provides support for Digital Camera Raw images that only contain pixel data and no header.

Because of absence of a header, such files can't be detected reliably. ImageGear uses low detection priority for these images, and by default, detection of this filter is disabled. Also, since these files do not contain any metadata describing color reconstruction, ImageGear support level for them is limited to "S2" - pixel decoding only.

Please also see the section Working with ImageGear Digital Camera RAW Filter in Using ImageGear chapter.


HPGL

Full Name
HPGL
Format ID
IG_FORMAT_HPGL = 72
File Extension(s)
*.hpgl, *.plt
Data Type
Vector image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
Win32, Win64, .NET, .NET64

NOTE: To support HPGL format ImageGear CAD/Vector HPGL, HPGL/2 Component should be attached to Core ImageGear.

ImageGear Supported versions:

HPGL, HPGL/2

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading

ImageGear Read Support:

IG_COMPRESSION_NONE - Vector/CAD data

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
BACKCOLOR
Long
0
Any positive value
This parameter is used to set background color. If nBackGroundColor=0, then a black background color is set, otherwise a white background color is set.
WIDTH
Long
512
Any positive value
Defines the DIB width of the loaded image. The DIB height is calculated using the file's scale factors.
FILENAME
String
""
N/A
Obsolete. Not currently used.

Comments

HPGL ("Hewlett Packard Graphics Language") is a vector graphics language used to output vector/CAD drawings to plotters. Due to widespread support among CAD software, it is sometimes used as a vector/CAD interchange format.


IBM AFP

Full Name
IBM AFP
Format ID
IG_FORMAT_AFP = 106
File Extension(s)
*.afp
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_IBM_MMR:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_ABIC_BW:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_ABIC_GRAY:
    • Indexed RGB: 4 bpp
  • IG_COMPRESSION_JPEG:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
STITCH_TILES
BOOL
FALSE
TRUE,
FALSE
Set to TRUE to enable automatic tile stitching during image loading.

Comments:

The AFP Document File is the file, coded in IBM's MO:DCA format (Mixed Object Document Content Architecture). All MO:DCA objects contained in the AFP Document File include the following:

  • Document Structure Objects
  • Resource Objects
    • Font Objects
    • Overlay Objects
    • Page Segment Objects
  • Graphics Objects
    • IM Image Objects
    • Image Objects (IOCA)
    • Graphics Objects (GOCA)
  • Text Objects
  • Bar Code Objects
  • Object Containers


IBM IOCA

Full Name
IBM IOCA (Image Object Content Architecture)
Format ID
IG_FORMAT_ICA =16
File Extension(s)
*.ica, *.mod
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_IBM_MMR:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_ABIC_BW:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_ABIC_GRAY:
    • Indexed RGB: 4bpp
  • IG_COMPRESSION_JPEG:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp

ImageGear Write Support:

  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_IBM_MMR:
    • Indexed RGB: 1 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
STITCH_TILES
BOOL
FALSE
TRUE,
FALSE
Set to TRUE to enable automatic tile stitching during image loading.

Comments:

IOCA files are most often used for document storage. They are not so unusual from most file formats, except for their naming conventions, which tend to be IBM-specific.

The general structure of an IOCA image file includes a "beginning segment", an "end segment", a header component called "Image Data Parameters", a palette, and the actual image data. Most IOCA images (less than 24-bit) contain a palette. The elements of the bitmap image are referred to as Image Data Elements (IDEs), that are called pixels by most other formats. The "Object Content" refers to the combination of the header and the image data.

IBM uses fields in the header called "self-defining fields". They each contain a type code, the length of the parameter, and then the actual parameter data. They include information as resolution, size, encoding scheme, and bit depth.

There are many optional parameters. Subsets of IOCA parameters are referred to as "function sets" and define different flavors of the IOCA, one being the MO:DCA, also supported by ImageGear. Examples of optional parameters include a tiling parameter, if the image is tiled, and a Band Image parameter, which signifies that the image is saved in "bands" ("bit planes" in other formats).

References used

Image Object Content Architecture Reference, 2d ed., copyright International Business Machines Corporation, August 1991.


IBM MO:DCA

Full Name
IBM MO:DCA (Mixed Object Document Content Architecture)
Format ID
IG_FORMAT_MOD = 26
File Extension(s)
*.mod, *.ica
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC, .NET, .NET64

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_MPAGEWRITEPSUPPORT - multipage file writing
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_IBM_MMR:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_ABIC_BW:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_ABIC_GRAY:
    • Indexed RGB: 4bpp
  • IG_COMPRESSION_JPEG:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp

ImageGear Write Support:

  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_IBM_MMR:
    • Indexed RGB: 1 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
STITCH_TILES
BOOL
FALSE
TRUE,
FALSE
Set to TRUE to enable automatic tile stitching during image loading.

Comments:

The MO:DCA header allows the storage of multiple IOCA images in one file. The MO:DCA format is an IOCA "wrapper". It is considered by IBM to be a "data stream controlling environment" for a group of IOCA images.

There are many optional parameters. Subsets of IOCA parameters are referred to as "function sets" and define different flavors of the IOCA, for example, the MO:DCA. The MO:DCA incorporates function sets "10" and "11".

Please see the description of IBM IOCA in this chapter for further description.

References used

Image Object Content Architecture Reference, 2d ed., copyright International Business Machines Corporation, August 1991.


ICO

Full Name
ICO (Windows icon)
Format ID
IG_FORMAT_ICO = 17
File Extension(s)
*.ico
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
Single alpha channel for read/write (see Comments).
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Windows 3.1
  • Windows NT/95

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed + Extra: 1+1, 4+1, 8+1 bpp;
    • RGB + Alpha: 32 bpp
  • IG_COMPRESSION_RLE:
    • Indexed + Extra: 4+1, 8+1 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed + Extra: 1+1, 4+1, 8+1 bpp;
    • RGB + Alpha: 32 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
READ_AS_RGBA
Boolean
False
True,
False
If True, ImageGear reads CUR format as RGBA (RGB with alpha channel).

Comments:

More than one representation of the icon bitmap is stored in order to offer a choice of icons; the version most compatible to the output device is used. Support for read-write transparency masks has been added to the ICO filter. Transparency masks are placed into an alpha channel when the image is created. These masks can subsequently be set and applied to the main image.

The structure of an ICO file consists of four data sections: the header, the Resource Descriptor, and two representations of the image data per each icon (the color bitmap and the 1-bit masking bitmap).

The header identifies the file as an ICO and stores the number of icon images that are stored in the file.

The Resource Descriptor stores the image width and height, the number of colors used, and the offset from the beginning of the file to the image data.

The 1-bit masking bitmap defines the transparent portion of the bitmap.

READ_AS_RGBA control parameter determines how ImageGear reads the 1-bit AND masks. If READ_AS_RGBA is False, ImageGear reads AND mask into "Extra" channel. This mode preserves unchanged pixel values from the file. However, in this mode ImageGear displays only the XOR mask and ignores AND mask (Extra channel) during display, i.e. display is not transparent. If READ_AS_RGBA is TRUE, ImageGear reads CUR files as 32 bpp RGB + Alpha. This allows transparent display.

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.


IFF

Full Name
Interchange File Format
Format ID
IG_FORMAT_IFF = 18
File Extension(s)
*.iff
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 1, 1985

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp

ImageGear Filter Control Parameters:

None

Comments

This type of file format is referred to as a "wrapper" because it can include any type of data that is encoded in any manner.

The basic organization of the IFF file format utilizes storage structures known as "chunks". A chunk is a block of data that contains its own header (that identifies the chunk size and type). This makes it easy for an IFF viewer to identify chunks and to skip over the ones that are not necessary.

The Header Chunk contains 17 fields, including the size of the header chunk, the identification of the chunk as a header, the size and origin of the image, data encoding (yes or no), and aspect ratio.

A "CMG Chunk" may follow, containing data specific to Amiga display hardware.

A "CMAP Chunk" contains the RGB palette for the image.

The "Body Chunk" (also called the ILBM or "interleaved bitmap"), is the image data itself. It is stored in an "interleaved" format, by bit plane. Interleaving allows for data with different resolutions to be neatly stored together. The data may be uncompressed or compressed using an RLE scheme. See RLE section at the beginning of this chapter for more information.

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


IMG

Full Name
Xerox 9700 graphic image (IMG)
Format ID
IG_FORMAT_XRX = 46
File Extension(s)
*.img
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

Version 1.0

Version 2.0

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE - Indexed RGB: 1, 8 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

None

Comments

The IMG header contains the width, height and resolution of the image. Following the header is compressed data. The sample values of a binary image are compressed and then encoded into a sequence of bits. Compression is achieved by predicting a pixel value based on pixel values that have already been computed. For example, the predicted value of a pixel may be that of the corresponding pixel on the previous scan line. Up to fifteen different compression techniques are used, each designed to remove redundancy from a certain kind of image - text characters, line art, and halftones of various screen frequencies. The algorithm adapts to the properties of the image by selecting the technique that will perform the best.

References Used

Xerox System Integration Standard. Raster Encoding Standard. Xerox, XNSS 178506, June 1990.


IMR

Full Name
IMRS-Raster image
Format ID
IG_FORMAT_IMR = 59
File Extension(s)
*.ima
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

IG_COMPRESSION_CCITT_G4 - Indexed RGB: 1 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

None

Comments

The IMG header contains the width, height and resolution of the image. Following the header is compressed data. The sample values of a binary image are compressed and then encoded into a sequence of bits. Compression is achieved by predicting a pixel value based on pixel values that have already been computed. For example, the predicted value of a pixel may be that of the corresponding pixel on the previous scan line. Up to fifteen different compression techniques are used, each designed to remove redundancy from a certain kind of image - text characters, line art, and halftones of various screen frequencies. The algorithm adapts to the properties of the image by selecting the technique that will perform the best.

References Used

Xerox System Integration Standard. Raster Encoding Standard. Xerox, XNSS 178506, June 1990.


IMT

Full Name
IMNET (Medical Image Format)
Format ID
IG_FORMAT_IMT = 20
File Extension(s)
*.imt
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_CCITT_G3 - Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4 - Indexed RGB: 1 bpp

ImageGear Write Support:

  • IG_COMPRESSION_CCITT_G4 - Indexed RGB: 1 bpp
NOTE: The width of an image being saved must be a multiple of 8.

ImageGear Filter Control Parameters:

None


JBIG2

Full Name
JBIG2 (bilevel image compression)
Format ID
IG_FORMAT_JB2 = 62
File Extension(s)
*.jb2
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32

NOTE: To support JBIG 2 format ImageGear JBIG2 Component should be attached to Core ImageGear.

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_MPAGEWRITEPSUPPORT - multipage file writing

ImageGear Read Support:

IG_COMPRESSION_JBIG2 - Indexed RGB: 1 bpp

ImageGear Write Support:

IG_COMPRESSION_JBIG2 - Indexed RGB: 1 bpp

ImageGear Filter Control Parameters:

Please see the section JBIG2 Filter Control Parameters.

Comments

JBIG2 is a highly-compressed black and white image format that uses symbol recognition and substitution for very good compression results. Any black and white image can be compressed using JBIG2 including images stored as Group 4, Group 3, MO:DCA, TIFF, PDF and others.

The JBIG2 compression algorithm searches for groups of pixels arranged in similar shapes and use them to define a symbol. Rather than retaining information on the placement of each pixel, a table is created for common symbols. This allows users to see incredible reductions in file sizes. Compression rate matches 100:1 compared to uncompressed black and white TIFFs.


JPEG

Full Name
JPEG File Interchange Format
Format ID
IG_FORMAT_JPG = 21
File Extension(s)
*.ipg, *jpeg
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Read/write
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC, Java

ImageGear Supported versions:

  • Version 1.01 - 1991
  • Version 1.02 - Added ability for thumbnails to be color-mapped and JPEG compressed.

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_JPEG (Lossy):
    • Grayscale: 8, 12 bpp;
    • RGB: 24, 36 bpp;
    • CMYK: 32 bpp;
    • RGB + Alpha: 32 bpp
  • IG_COMPRESSION_JPEG (Lossless):
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • CMYK: 32 bpp;
    • RGB + Alpha: 32 bpp
  • IG_COMPRESSION_JPEG (Progressive JPEG):
    • Grayscale: 8, 12 bpp;
    • RGB: 24 bpp;
    • CMYK: 32 bpp;
    • RGB + Alpha: 32 bpp

ImageGear Write Support:

  • IG_COMPRESSION_JPEG (Lossy):
    • Grayscale: 8, 12 bpp;
    • RGB: 24, 36 bpp;
    • RGB + Alpha: 32 bpp1
    • CMYK: 32 bpp2
  • IG_COMPRESSION_JPEG (Lossless):
    • Grayscale: 8, 16 bpp;
    • RGB: 24 bpp;
  • IG_COMPRESSION_JPEG (Progressive JPEG):
    • Grayscale: 8, 12 bpp;
    • RGB: 24, 36 bpp

1) RGBA saving is disabled by default. Set SAVE_ALLOW_RGBA control parameter to TRUE to enable it.

2) CMYK saving is enabled by default. You can disable it by setting SAVE_ALLOW_CMYK control parameter to FALSE.

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
CALLER_ID
Long
21
For internal use.
DECIMATION_TYPE
WORD
IG_JPG_DCM_2x2_1x1_1x1
See JPEG Decimation Section.
Get/Set decimation value. For all available values see JPEG Decimation Section.
ENTROPY_OPTIMIZE
BOOL
FALSE
FALSE
TRUE
Get/Set entropy optimization flag. See JPEG Entropy Optimization Section.
KEEP_ALPHA
BOOL
FALSE
FALSE
TRUE
This parameter gets/sets alpha channel flag. If TRUE then alpha channel will be saved with original image (if it is present).
LOAD_SAVE_DCT
BOOL
FALSE
FALSE
TRUE
For internal use. Load/save DCT matrix instead of decompressing/compressing the image
LOAD_SCALE_DENOM
UINT
1
1, 2, 4, 8
If this parameter is set to any other than default value, ImageGear loads reduced version of the image, width and height of which are scaled by 1/load_scale_denom. This mode can be used for image preview, especially for those images that do not have embedded thumbnails, or where embedded thumbnails are smaller than desired. This mode allows you to make loading process 2-4 times faster.*
LOAD_SCANS
UINT
0
Gets/Sets number of scans to load from Progressive JPEG image. See Progressive JPEG Scans Section for details.
OLD_LOSSLESS_READ
BOOL
FALSE
FALSE
TRUE
PREDICTOR
AT_MODE
1
Gets/Sets predictor for lossless JPEG. See Lossless JPEG Predictor Settings Section for details.
QUALITY
INT
70
Possible value in range [1,100]
Gets/Sets quality value for Lossy and Progressive JPEG compression. See JPEG Quality Section for details.
SAVE_ALLOW_CMYK
BOOL
TRUE
TRUE, FALSE
Set to TRUE (default) to allow saving JPEG CMYK images. Set to FALSE to save CMYK images to JPEG as RGB.
SAVE_ALLOW_LOSSY12BPCSAVING
BOOL
TRUE
FALSE
TRUE
Controls the saving to Lossy JPEG format. If TRUE, saving of 12 bits per channel Lossy JPEG is allowed. This is the maximum channel depth supported by Lossy JPEG format. If source image's depth is more than 8 bits per channel, it will be saved to a 12 bpc JPEG. For example, 48-bit RGB image will be saved to 36-bit JPEG. Note that many viewers do not support 12 bpc JPEG. If FALSE, all images are saved to 8 bpc JPEG, regardless of their channel depth.
SAVE_ALLOW_RGBA
BOOL
FALSE
TRUE, FALSE
Set this parameter to TRUE to enable RGBA JPEG saving. Note, that there is no official standard for RGBA JPEG. This format is recognized as CMYK rather than RGBA by most third-party software.
SAVE_THUMBNAIL
BOOL
FALSE
FALSE
TRUE
Gets/Sets thumbnail flag. If TRUE then thumbnail will be added to image. See JPEG Decimation Section for details.
SAVE_TYPE
AT_MODE
IG_JPG_LOSSY
IG_JPG_LOSSY
,
IG_JPG_LOSSLESS,
IG_JPG_PROGRESSIVE
Get/Set type for output JPEG format. See Loading and Saving JPEG-Compressed Images Section for details.
SCAN_INFO
VOID|LP
{
{ 0, 0, 7, 1, 0 },
{ 1, 5, 7, 1, 1 },
{ 1, 5, 7, 1, 2 },
{ 1, 5, 7, 1, 3 },
{ 0, 0, 0, 0, 0 },
{ 6, 63,7, 1, 1 },
{ 6, 63,7, 1, 2 },
{ 6, 63,7, 1, 3 },
{ 1, 63,0, 0, 1 },
{ 1, 63,0, 0, 2 },
{ 1, 63,0, 0, 3 },
};
Gets/Sets scan configuration for Progressive JPEG format. See Progressive JPEG Scans Section for details.
SCAN_INFO_COUNT
UINT
sizeof(scan_info)/sizeof(scan_info[0]);
Gets/Sets length of array for previous parameter. See Progressive JPEG Scans Section for details.
THUMBNAIL_COMPRESSED
BOOL
FALSE
FALSE, TRUE
If TRUE then thumbnail will be compressed.
THUMBNAIL_HEIGHT
UINT
16
Gets/Sets thumbnail height.
THUMBNAIL_WIDTH
UINT
16
Gets/Sets thumbnail width.

Comments:

JPEG is normally associated with the JPEG compression scheme, but it is also implemented into the JFIF file format. This format was developed to store JPEG-encoded data, and to exchange it between applications or operating systems that are normally incompatible.

NOTE: The JPEG compression scheme was developed by the Joint Photographic Experts Group (created by the joining of a subgroup of the International Standards Organizations, called PEG (Photographic Experts Group) and a subgroup of the CCITT). Their common goal was to produce a standard for the transmission of graphics image data over networks and through color facsimile systems.

The header of the JFIF contains the version number, the image dots per inch (DPI), or dots per centimeter, and an optional thumbnail (miniature) RGB representation of the main image. Version 1.02 handles thumbnails differently by storing them separately, rather than in the identification marker of the header.

The raw JPEG data is surrounded by two markers, an "SOI" (start of image) marker, and an "EOI" (end of image) marker. See the section entitled Compression Schemes in this chapter for more about JPEG compression.

JFIF is considered a non-proprietary file format. Many proprietary file formats contain JPEG data, incorporating their own application-specific data structures. Other non-proprietary formats that use JPEG-encoded data are Macintosh MAC PICT and the TIFF file format, version 6.0.

Loading and Saving JPEG-Compressed Images

ImageGear supports the reading and writing of three types of JPEG compression: baseline JPEG (Lossy), Progressive JPEG, and Lossless JPEG. When you load a JPEG-compressed file, ImageGear detects the type of JPEG compression and decompress the image automatically. But if you want to save an image with a JPEG compression scheme other than baseline JPEG, you must use the "SAVE_TYPE" parameter to specify the type of JPEG compression.

Use these constants for "SAVE_TYPE" control parameter:

  • IG_JPG_LOSSY - Lossy JPEG compression.
  • IG_JPG_LOSSLESS - Lossless JPEG compression
  • IG_JPG_PROGRESSIVE - Progressive JPEG compression.

JPEG Decimation

This table lists all possible decimation values:

IG_JPG_DCM_1x1_1x1_1x1
IG_JPG_DCM_2x1_1x1_1x1
IG_JPG_DCM_1x2_1x1_1x1
IG_JPG_DCM_2x2_1x1_1x1
IG_JPG_DCM_2x2_2x1_2x1
IG_JPG_DCM_4x2_1x1_1x1
IG_JPG_DCM_2x4_1x1_1x1
IG_JPG_DCM_4x1_1x1_1x1
IG_JPG_DCM_1x4_1x1_1x1
IG_JPG_DCM_4x1_2x1_2x1
IG_JPG_DCM_1x4_1x2_1x2
IG_JPG_DCM_4x4_2x2_2x2

The format of these ImageGear decimation constants is:

IG_JPG_DCM_<H1>x<V1>_<H2>x<V2>_<H3>x<V3>,

where Hi, Vi = horizontal and vertical decimation values for the i-channel.

The following is a simple example of decimation. For a more detailed definition, please see the JPEG Specification.

A decimation setting of IG_JPG_DCM_4x2_1x1_1x1 would yield the following results:

As shown, 8 Y components in the source image have yielded one Cb and one Cr component. In general, this setting will reduce the quality of the compression, unless the image has many continuous tone areas.

  • Maximum quality can be reached using a value of IG_JPG_DCM_1x1_1x1_1x1.
  • Maximum compression ratio can be reached with a value of IG_JPG_DCM_4x4_2x2_2x2.
  • The ImageGear default decimation value is: IG_JPG_DCM_2x2_1x1_1x1.

JPEG Thumbnails

The JPEG format can store thumbnails, which are small representations of the original image. These images are stored in uncompressed form and can significantly decrease your overall compression ratio. (Uncompressed thumbnails sometimes occupy more space than the original JPEG image when compressed). Use this option carefully.

NOTE: The JPEG format does not allow the storage of "large" thumbnails. This is due to the marker segment length, which cannot be greater than 65,536 bytes. The maximum size of a color thumbnail is about 100x200 or 200x100 pixels, and the maximum size of a grayscale thumbnail is about 300x200 or 200x300 pixels.

Lossless JPEG Predictor Settings

The Lossless JPEG scheme is "predictive" in nature-it uses the values of surrounding pixels in addition to the value of the original pixel to calculate a predictor value, which it then subtracts from the value of the original pixel. The resulting pixel value will be reduced such that it can be compressed more than the original value. The higher the number of neighboring pixels used, the higher the compression will be.

Regardless of the predictor value setting, the quality of the image will remain the same. The difference is that if you choose to optimize for space by setting a high predictor value, you will have to give up some speed, as the decompression will take longer to perform.

ImageGear lets you set the predictor value using "PREDICTOR" control parameter. The ImageGear default for this setting is 1. The allowed range is 1-7. The graphic below shows a predictor (x) and three reconstructed samples (a,b,c) immediately to the left, immediately above, and diagonally to the left of the current sample

Lossless JPEG does not apply DCT for an image as per the Lossy JPEG compression. Instead, it uses a DPCM difference coding, which can be carried out with any one of seven different prediction modes. Correspondingly, the IG_CONTROL_JPG_PREDICTOR control parameter can be set to a value between 0 and 7. In Table 4, you will see what algorithm your setting of 1-7 will use, where Pr Px is the predictor, and Ra, Rb, and Rc are the reconstructed samples:

Value
JPEG DIS Prediction
0
no prediction
1
Px = Ra
2
Px = Rb
3
Px = Rc
4
Px = Ra + Rb - Rc
5
Px = Ra + ((Rb-Rc)/2)
6
Px = Rb + ((Ra-Rc)/2)
7
Px = (Ra + Rb)/2

JPEG Quality

The baseline JPEG specification calls for a quality setting. The lower the setting, the greater the number of original pixels lost, and therefore the smaller the resulting compressed file will be. ImageGear lets you set the quality of compression with values of type INT between 1-100, where 100 provides the highest retention of original pixel values. A setting of 100 does not mean that the image includes 100% of all original pixel values. With Lossy JPEG, there is no such thing as "no loss". Control parameter for setting Lossy JPEG quality is "QUALITY".

JPEG Entropy Optimization

Entropy optimization is relevant only to standard Lossy JPEG compression. If you set the parameter to TRUE, the default Huffman tables are not used. Instead, optimal Huffman tables are created for each component. This can bring a higher compression ratio but it takes more time for the compression.

Progressive JPEG Scans

A Progressive JPEG file stores more than just a copy of an image but rather several scans, each of which progressively adds a higher level of quality. Each scan contains a portion of the original image data. The purpose of this is to allow a very quick display of an image, beginning with a low-quality rendering and then increasing in quality as the remaining scans are added to it.

A Progressive JPEG image is stored as sequence of Huffman compressed blocks or "scans". Each scan contains the sequence of DCT coefficients in the given range. However, the coefficients are not complete. Only some of their bits will be stored in each scan.

ImageGear defines the following structure for holding the necessary configuration to write a JPEG image:

typedef struct tag AT_PJPEG_SCANINFO{
        LONG		Ss;
        LONG		Se;
        LONG		HBit;
        LONG		LBit;
        LONG		ChannelID;
}		AT_PJPEG_SCANINFO;
typedef AT_PJPEG_SCANINFO FAR* LPAT_PJPEG_SCANINFO;

The Ss and Se members of the AT_PJPEG_SCANINFO structure are used for spectral selection control coefficients:

LONG			Ss;
LONG			Se; - after applying DCT of 8x8 pixels we get 64

In Progressive coding, these coefficients are separated into different scans. Values Ss and Se specify the first and last number of the DCT coefficients that must be included in a given scan. The possible values are Ss = Se = 0 or 1<= Ss<=Se<=63. Please note following restrictions:

  • The first coefficient (DC) cannot be encoded with the other coefficient (AC) in the single scan. In other words, the DC and AC coefficients cannot be in the same scan.
  • Only scans that code DC coefficients may include interleaved blocks from more than one component. All other scans shall have only one component. For each component, a first DC scan shall precede any AC scans.

The HBit and LBit members of the AT_PJPEG_SCANINFO structure are used for successive approximation control:

    LONG HBit;
    LONG LBit;

If successive approximation is used, the DCT coefficients are reduced in precision by the point transform defined in the scan header. This is equivalent to taking some binary digits from each coefficient. HBit and LBit specify the high and low range of bits to take. For example, if HBit = 7 and LBit = 2, the scan will have the following original bits of the original DCT coefficient: 7,6,5,4,3,2.

The ChannelID member of the AT_PJPEG_SCANINFO structure is used to specify the number of components that will be encoded:

LONG ChannelID;

It can be set to one of the following values:

  • interleaved scan which will only have DC coefficients of all components. This setting can only be used if Ss=Se=0.
  • takes coefficients of first component.
  • takes coefficients of second component.
  • takes coefficients of third component.

There are two control parameters that operate with the AT_PJPEG_SCANINFO structure:

SCAN_INFO
Points to array of AT_PJPEG_SCANINFO elements.
SCAN_INFO_COUNT
Specifies the number of elements in this array. The nth entry of the SCAN_INFO array defines the configuration for the nth scan of the Progressive image.

The LOAD_SCANS control parameter specifies how many scans should be loaded. For example, if it is set to 1, the JPEG filter will load only the first scan of the image.

The following text blocks represent the different AT_PJPEG_SCANINFO structures that would be generated when loading a JPEG file using the ImageGear default settings for Progressive scans:

scan_config[0].Ss = 0;
scan_config[1].Ss = 1;
scan_config[0].Se = 0;
scan_config[1].Se = 5;
scan_config[0].HBit = 7;
scan_config[1].HBit = 7;
scan_config[0].LBit = 2;
scan_config[1].LBit = 2;
scan_config[0].ChannelID = 0;
scan_config[1].ChannelID = 1;
scan_config[2].Ss = 1;
scan_config[3].Ss = 1;
scan_config[2].Se = 5;
scan_config[3].Se = 5;
scan_config[2].HBit = 7;
scan_config[3].HBit = 7;
scan_config[2].LBit = 2;
scan_config[3].LBit = 2;
scan_config[2].ChannelID = 2;
scan_config[3].ChannelID = 3;
scan_config[4].Ss = 0;
scan_config[5].Ss = 1;
scan_config[4].Se = 0;
scan_config[5].Se = 5;
scan_config[4].HBit = 1;
scan_config[5].HBit = 1;
scan_config[4].LBit = 1;
scan_config[5].LBit = 1;
scan_config[4].ChannelID = 0;
scan_config[5].ChannelID = 1;
scan_config[6].Ss = 1;
scan_config[7].Ss = 1;
scan_config[6].Se = 5;
scan_config[7].Se = 5;
scan_config[6].HBit = 1;
scan_config[7].HBit = 1;
scan_config[6].LBit = 1;
scan_config[7].LBit = 1;
scan_config[6].ChannelID = 2;
scan_config[7].ChannelID = 3;
scan_config[8].Ss = 6;
scan_config[9].Ss = 6;
scan_config[8].Se = 63;
scan_config[9].Se = 63;
scan_config[8].HBit = 7;
scan_config[9].HBit = 7;
scan_config[8].LBit = 1;
scan_config[9].LBit = 1;
scan_config[8].ChannelID = 1;
scan_config[9].ChannelID = 2;
scan_config[10].Ss = 6;
scan_config[11].Ss = 0;
scan_config[10].Se = 63;
scan_config[11].Se = 0;
scan_config[10].HBit = 7;
scan_config[11].HBit = 0;
scan_config[10].LBit = 1;
scan_config[11].LBit = 0;
scan_config[10].ChannelID = 3;
scan_config[11].ChannelID = 0;
scan_config[12].Ss = 1;
scan_config[13].Ss = 1;
scan_config[12].Se = 63;
scan_config[13].Se = 63;
scan_config[12].HBit = 0;
scan_config[13].HBit = 0;
scan_config[12].LBit = 0;
scan_config[13].LBit = 0;
scan_config[12].ChannelID = 1;
scan_config[13].ChannelID = 2;
scan_config[14].Ss = 1;
scan_config[14].Se = 63;
scan_config[14].HBit = 0;
scan_config[14].LBit = 0;
scan_config[14].ChannelID = 3;

References used:

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


JPEG2000

Full Name
JPEG2000
Format ID
IG_FORMAT_JPEG2K = 100
File Extension(s)
*.jp2, *.jpc, *.j2k, *.j2c
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Read/write
IG Platforms Support
WIN32, WIN64, .NET, .NET64

NOTE: To support JPEG2000 format ImageGear JPEG2000 Component should be attached to Core ImageGear.

ImageGear Supported versions:

ISO/IEC 15444-1:2000

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_JPEG2K:
    • Indexed RGB: 1..8 bpp;
    • Grayscale: 1..16 bpc
    • RGB: 1..16 bpc
    • Grayscale + Alpha: 1..16 bpc
    • RGB + Alpha: 1..16 bpc

ImageGear Write Support:

  • IG_COMPRESSION_JPEG2K:
    • Indexed RGB: 1..8 bpp;
    • Grayscale: 1..16 bpc
    • RGB: 1..16 bpc
    • Grayscale + Alpha: 1..16 bpc
    • RGB + Alpha: 1..16 bpc

ImageGear Filter Control Parameters:

Please see the section JPEG2000 Format Support and JP2, JPX and MJ2 Format Filters Control Parameters Reference.

Comments:

JPEG 2000 standard defines a compression scheme and a file format for interchange of JPEG2000 compressed data.

The compression scheme is based on a discrete wavelet transform, and supports both lossy and lossless modes. JPEG 2000 compression is similar to JPEG in that it supports lossy compression. However, JPEG2000 allows achieving much higher compression ratios while preserving good image quality.

JPEG2000 file format defines a basic set of features that allow interchange of JPEG2000 compressed images.


JPX

Full Name
JPEG2000 Extensions
Format ID
IG_FORMAT_JPX = 101
File Extension(s)
*.jpx
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Yes
IG Platforms Support
WIN32, WIN64, .NET, .NET64

NOTE: To support JPX format ImageGear JPEG2000 Component should be attached to Core ImageGear.

ImageGear Supported versions:

ISO/IEC 15444-2:2000

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_JPEG2K:
    • Indexed RGB: 1..8 bpp;
    • Grayscale: 1..16 bpc
    • RGB: 1..16 bpc
    • YCbCr: 1..16 bpc
    • Lab: 1..16 bpc
    • CMY: 1..16 bpc
    • CMYK: 1..16 bpc
    • Grayscale + Alpha: 1..16 bpc
    • RGB + Alpha: 1..16 bpc

ImageGear Write Support:

  • IG_COMPRESSION_JPEG2K:
    • Indexed RGB: 1..8 bpp;
    • Grayscale: 1..16 bpc
    • RGB: 1..16 bpc
    • YCbCr: 1..16 bpc
    • Lab: 1..16 bpc
    • CMY: 1..16 bpc
    • CMYK: 1..16 bpc
    • Grayscale + Alpha: 1..16 bpc
    • RGB + Alpha: 1..16 bpc

ImageGear Filter Control Parameters:

Please see the section JPX Format Support and JP2, JPX and MJ2 Format Filters Control Parameters Reference.

Comments:

JPX file format is an extension to JPEG 2000 file format. It normally uses JPEG 2000 compression, but allows other compressions as well, such as JBIG, CCITT Group3, CCITT Group4, etc. The format provides advanced features such as multiple layers for an image, various colorspaces, opacity (alpha channel) and fragmented codestreams.


KFX

Full Name
KFX (Kofax Group4 image)
Format ID
IG_FORMAT_KFX = 22
File Extension(s)
*.kfx
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 3

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_CCITT_G4 - 1bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

None


LV

Full Name
LV (Lazer View format)
Format ID
IG_FORMAT_LV = 23
File Extension(s)
*.lv
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_CCITT_G3 - 1bpp
  • IG_COMPRESSION_CCITT_G4 - 1bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

None

Comments:

N/A


MAC

Full Name
MAC (Macintosh Paint)
Format ID
IG_FORMAT_MAC = 24
File Extension(s)
*.mac
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, MAC

ImageGear Supported versions:

Version 2.0 1989

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_RLE - 1 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

None

Comments:

Originally developed to store MacPaint graphics files, this format is now supported by many Macintosh applications. It is also exportable to the PC platform. It is always monochrome, and always has a fixed size of 576 pixels by 720 lines. The data, when uncompressed, is always 51,840 bytes in size.

Because this is a Macintosh format, it is organized as "forked" data. Each file consists of two forks, a "resource fork" and a "data fork". There is no code associated with this graphics format. The resource fork is always empty, and is easily merged together with the data fork when the file is exported to a PC platform.

The MacPaint data begins with a version number. If set to a value of 2, it indicates that paint patterns appear as the next structure. There are 38 possible patterns. These are generally not used, unless the file is being exported from one paint program to another.

The bitmap data begins at an offset of 512 bytes from the beginning of the file. The data is always compressed using the "PackBits" RLE compression scheme. The compressed data is stored in variable-length strips. See the description of RLE compression in the ImageGear Supported Compressions Reference sectionof this chapter.

It the MacPaint file has been exported to a PC platform it contains a structure called the MacBinary header. This helps in reconstructing the resource fork if the file is returned to the Macintosh environment. A field in the MacBinary header holds the size of the fork. Other information includes the position of the file in the window, the version of the MacBinary header (I or II), the time and data of creation, and a SecondHeadLength field intended for future expansion of the MacPaint format should it require a secondary header.

References used

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


MAC PICT

Full Name
Mac PICT
Format ID
IG_FORMAT_PCT = 30
File Extension(s)
*.pct, *.pict
Data Type
Metafile (2D raster, 2D geometry)
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Supports single alpha channel for read only. Alpha channel have to be 8-bit image.
IG Platforms Support
WIN32, WIN64, MAC

ImageGear Supported versions:

  • PICT 2 (for Color QuickDraw version 2). Added color and support for additional QuickDraw functions.
  • PICT 1 (for Color QuickDraw version 1). Monochrome only.

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp and 24+8 bit alpha
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp and 24+8 bit alpha
  • IG_COMPRESSION_JPEG:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp and 24+8 bit alpha

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp (for 1, 4, 8 bpp, the files are ONLY saved as uncompressed if the image is 64x64 pixels or smaller. Otherwise, the image is saved as RLE compressed).
    • RGB: 24 bpp (Always saved as uncompressed)

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
FORCE_VERSION
BOOL
FALSE
TRUE,
FALSE
TRUE means saving of PCT in version 1.

Comments:

The PICT is one of the most widely-supported graphics file formats for the Macintosh.

PICT files begin with a fixed length header containing application-specific data, followed by fields that store the image size and location. If it is a PICT2 file, an additional header follows that contains the original resolution data of the image.

The bitmap data in the PICT2 format is referred as a Pixmap, from older terminology where Pixmap meant a bitmap with color.

The PICT file uses "opcodes". These are similar to the fields found in most file formats, and are associated with data that describes different shapes, lines, fill patterns, etc.

The lengthy list of opcodes is followed by the bitmap or "pixmap" data that describes the image data's address and resolution. The color table follows the opcodes. Next, source and destination rectangles are defined by their top left and lower right coordinates.

The pixel data, stored in the "PixData" field, is the last data to appear in the file. Each value is an index to the color table. This data is represented by 1, 2, or 4 bits.

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


Motion JPEG2000

Full Name
Motion JPEG2000
Format ID
IG_FORMAT_MJ2 = 103
File Extension(s)
*.mj2
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Read only
IG Platforms Support
WIN32, WIN64, .NET, .NET64

NOTE: To support Motion JPEG2000 format ImageGear JPEG2000 Component should be attached to Core ImageGear.

ImageGear Supported versions:

ISO/IEC 15444-3:2002

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_JPEG2K:
    • Indexed RGB: 1..8 bpp;
    • Grayscale: 1..16 bpc
    • RGB: 1..16 bpc
    • Grayscale + Alpha: 1..16 bpc
    • RGB + Alpha: 1..16 bpc

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Please see the section MJ2 Format Support and JP2, JPX and MJ2 Format Filters Control Parameters Reference.

Comments:

Motion JPEG2000 file format is designed to contain one or more motion sequences of JPEG2000 images, with their timing, and also optional audio annotations, all composed into an overall presentation.

Please see the section MJ2 Format Support for more details.


MSP

Full Name
MSP (MS Paint)
Format ID
IG_FORMAT_MSP = 25
File Extension(s)
*.msp
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 2.0
  • Version 1.0

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE: Indexed RGB: 1 bpp
  • IG_COMPRESSION_RLE: Indexed RGB: 1 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

None

Comments:

This was a popular format for storing line drawing and clip art images created with Windows applications, but has recently begun to be replaced by the Windows bitmap format (also supported by ImageGear see BMP).

For versions earlier than 2.0, the format begins with a 32-byte header and immediately proceeds with the bitmap data. The header information includes: the version of the file, the size and aspect ratio of the bitmap, and the width and height and aspect ratio (in pixels) of the output device used to render the bitmapped image. The bitmap data is uncompressed.

Files made with Version 2.0 and later always use RLE compression. In these files a "scan-line map" follows the header and precedes the data. It gives offsets to each scan line for instances when a particular scan line needs to be examined. All previous lines can remain compressed, while the needed line is located.

See RLE Compression under the ImageGear Supported Compressions Reference section of this chapter for more information.

References used

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


MULTIMEDIA

Full Name
Multimedia, Motion Picture Expert Group (MPEG)
Format ID
IG_FORMAT_MUL = 67
File Extension(s)
*.avi, *.mpeg, *.mpg
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64

NOTE: To support MULTIMEDIA format ImageGear Multimedia Component should be attached to Core ImageGear.

ImageGear Supported versions:

  • AVI
  • MPEG-1 (Standard)
  • MPEG-2
  • MPEG-3
  • MPEG-4

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE - RGB: 24 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
FILENAME
LPSTR
""
Any string
Name of the input MPEG or AVI file.

Comments:

The first version of the MPEG format is optimized for CD-ROM. It uses discrete cosine transform (DCT) and Huffman compression to remove spatially redundant data within a frame and block-based motion compensated prediction (MCP) to remove data which is temporally redundant between frames. Audio is compressed using subband compression.

MPEG-2 is a variant of the MPEG video and audio compression algorithm and file format, optimized for broadcast quality video for digital storage media up to 4.0Mbits/second. The file extension is .MP2. MPEG-2 has been approved as International Standard IS-13818.

MPEG-3 is a variant of the MPEG video and audio compression algorithm and file format. The file extension is .MP3. This variant no longer exists and has been merged into MPEG-2.

MPEG-4 is a variant of the MPEG video and audio compression algorithm and file format used for low bandwidth video telephony. The file extension is .MP4. The International Standards Organization (ISO) has adopted the QuickTime 3 file format to form the starting point for a unified digital media storage format for the MPEG-4 specification

No actual structured MPEG file format has been defined. Everything required to play back MPEG data is compressed directly in the data stream. Therefore, no header or other type of wrapper is necessary. It is likely that when needed, a multimedia standards committee - perhaps MHEG or the DSM (Digital Storage Medium) MPEG subgroup - will one day define an MPEG file format.

MPEG starts with a relatively low resolution video sequence (possibly decimated from the original) of about 352 by 240 frames by 30 frames in the US (the numbers are different in Europe), but original high (CD) quality audio. The images are in color, but converted to YUV space, and the two chrominance channels (U and V) are decimated further to 176 by 120 pixels. You can get us much less resolution in those channels and not notice it, at least in natural (not computer generated) images.

The basic scheme is to predict motion from frame to frame in the temporal direction, and then to use DCTs (Discrete Cosine Transforms) to organize the redundancy in the spatial directions. The DCTs are performed on 8x8 blocks. The motion prediction is performed in the luminance (Y) channel on 16x16 blocks. In other words, given the 16x16 block in the current frame that you are trying to compress, you look for a close match to that block in a previous or future frame (there are backward prediction modes where later frames are sent first to allow interpolating between frames). The DCT coefficient (of either the actual data, or the difference between this block and the close match) are quantized, which means that you divide them by some value to drop bits off the bottom end. Hopefully, many of the coefficients will then end up being zero. The quantization can change for every macroblock (a macroblock is 16x16 of Y and the corresponding 8x8's in both U and V). The results of all of this, which include the DCT coefficients, the motion vectors, and the quantization parameters (and other stuff) is Huffman compressed using fixed tables. The DCT coefficients have a special Huffman table that is two-dimensional in that one code specifies a run-length of zeros and the non-zero value that ends the run. Also, the motion vectors and the DCT components are DPCM (subtracted from the last one) compressed.

There are three types of compressed frames.

  • I or intra frames are simply a frame compressed as a still image, not using any past history.
  • P or predicted frames are predicted from the most recently reconstructed I or P frame. (Described from the decompressor view point) Each macroblock in a P frame can either come with a vector and difference DCT coefficients for a close match in the last I or P, or it can just be intra compressed (like in the I frames) if there is no good match.
  • B or bidirectional frames are predicted from the closest two I or P frames, one in the past and one in the future. You search for matching blocks in those frames, and try three different things to see which works best. (Described from the compressor view point.) You first use the forward vector and the backward vector, then average the two blocks from future and past frames, and then subtract that from the block being compressed. If none of these methods work well, you can intra-compress the block.

The sequence of decompressed frames is as follows:

 IBBPBBPBBPBBIBBPBBPB...

Where there are 12 frames from I to I (for US and Japan). This is based on a random access requirement that you need a starting point; at least once every 0.4 seconds or so. The ratio of P's to B's is based on experience. Of course, for the decompressor to work, you have to send that first P before the first two B's, so that the compressed data stream appears as follows:

 0xx312645...

where those are frame numbers. "xx" may be nothing (if this is the true starting point), or it may be the B's of frames -2 and -1 if it is the middle of the stream.

Decompress the I, then the P. Keep both in memory, and then decompress the two B's. You can display the I while you're decompressing the P, and display the B's as you're decompressing them. Display the P as you are decompressing the next P, and so on.

See also AVI file format reference.


NCR

Full Name
NCR
Format ID
IG_FORMAT_NCR = 27
File Extension(s)
*.ncr
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_CCITT_G4 - Indexed RGB: 1 bpp
  • IG_COMPRESSION_NONE - Indexed RGB: 1, 4 bpp

ImageGear Write Support:

  • IG_COMPRESSION_CCITT_G4 - Indexed RGB: 1 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
COMRESSION
WORD
0
0,
NCR_CCITT_G4
This parameter has been retired.

Comments:

NCR is the black and white image compression format.


PBM

Full Name
PBM (Portable Bitmap File Format)
Format ID
IG_FORMAT_PBM = 28
File Extension(s)
*.pbm
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

October 1991 - last release

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_RAW:
    • Indexed RGB: 1 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp
  • IG_COMPRESSION_ASCII:
    • Indexed RGB: 1 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp

ImageGear Write Support:

  • IG_COMPRESSION_RAW:
    • Indexed RGB: 1 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp
  • IG_COMPRESSION_ASCII:
    • Indexed RGB: 1 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp

ImageGear Filter Control Parameters:

None

Comments:

This is useful for quick and easy transfer of monochrome bitmap images, although the encoding scheme is not efficient in terms of storage space. This format, as well as the PGM, PNM, and PPM formats, are at the core of a set of utility programs also written by Jef Poskanzer. Among other things, these formats serve as intermediary storage methods for the conversion of other file formats.

The Portable Bitmap File Format structure is very simple. It begins with a short ASCII header that contains the file type identifier (magic number), the width and height of the image, and perhaps a comment line identifying the filename. Following white space (usually a carriage return) is the bitmap data. The number of bits is equal to the width * height. A pixel value of 0 indicates white, and a value of 1 indicates black.

The magic number of the header can have one of two values: either P1 or P4. P1 indicates that the bitmap data are to be read as ASCII decimal values. P4 indicates that the bitmap data are stored as plain bytes. Because 8 pixel values (1 bit each) are stored in one byte, the file is 8 times smaller than in the ASCII decimal format. White spaces are permitted in the P1 format but not permitted in the P4 format.

NOTE: Note: ImageGear uses IG_FORMAT_PBM filter to handle the whole family of formats: PBM (1-bit), PGM (grayscale), PPM (truecolor) and PNM (collective name for all of above). When saving image as IG_FORMAT_PBM format, ImageGear chooses particular format (PBM, PGM, PNM or PPM) depending on image bit depth.
See Also:

PGM, PPM, PNM

References used

Kay, David C. and John R. Levine. Graphics File Formats, 2nd ed. Windcrest /McGraw-Hill, 1995.

PBM Specification by Jef Poskanzer, copyright © 1989, 1991.


PCD

Full Name
PCD (Kodak Photo CD)
Format ID
IG_FORMAT_PCD = 29
File Extension(s)
*.pcd
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

All valid PCD files in 5 different resolutions:

  • Page 1: 768x512
  • Page 2: 384x256
  • Page 3: 192x128
  • Page 4: 1536x1024
  • Page 5: 3072x2048

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE - RGB: 24 bpp
  • IG_COMPRESSION_HUFFMAN - RGB: 24 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

None

Comments:

"Photo CD" is the informally adopted name for files created using the Photo CD-ROM-based storage and retrieval system created by Kodak. The images are digitized versions of photographic images. Using a Photo CD player, images can be viewed on television. Although intended for photographic images, the data source does not necessarily have to be film. Due to the large storage capacity of the CD medium, this format supports very large and/or intricate images.

Images and their associated information are stored in groups called "sessions". Originally, they were stored at the rate of one session per CD, but later versions allowed multiple sessions per disc.

For each stored image, there are up to 5 bitmaps, each representing the image at a different resolution. The bitmaps at the lowest resolution are intended for such purposes as displaying thumbnails and previewing an image.

References used

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


PCX

Full Name
PCX (PC Paintbrush File Format)
Format ID
IG_FORMAT_PCX = 31
File Extension(s)
*.pcx
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 5.0 1991, Supports 24-bit RGB
  • Version 3.0
  • Version 2.8 Included color palette
  • Version 2.5

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp

ImageGear Write Support:

  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
SAVE_COMPRESSED
BOOL
TRUE
FALSE,
TRUE
If TRUE - image is saved with RLE Compression

Comments:

PCX is one of the oldest PC-based bitmap formats. It became well-known when Microsoft used it for their Paintbrush for Windows application and distributed it with every copy of Windows. This format is popular for fax documents because it allows them to be viewed within many popular paint and image display programs. If multiple images are desired in a PCX format, the format known as DCX, designed for this purpose, (and supported by ImageGear), may be used. Please see DCX file format for more information.

The main components of the PCX file format are the fixed length header, the image data, and if it is written for VGA display technology, the palette for the image (this appears as the last structure in the file). The header includes fields including the PCX version, the image size, resolution and position, and an encoding field that always has a value of 1; PCX data is always RLE. (For complex images, this may actually cause the bitmap data to increase in size).

The size and location of the palette associated with the image depends on the version of the PCX. When it was first developed, the limitations of the EGA card led to a palette that contained just 16 colors. PCX also supported CGA, so that the palette contained only 4 colors. Both of these palettes were stored in the palette array structure of the header. When the PCX was modified to display VGA, there was not enough room to store the palette in the header; subsequently, it was located at the end of the file.

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


PGM

Full Name
PGM (Portable Graymap File Format)
Format ID
IG_FORMAT_PBM = 28 (see the Note below)
File Extension(s)
*.pgm
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

NOTE: ImageGear supports PGM file format via its IG_FORMAT_PBM format filter. Use IG_FORMAT_PBM to save grayscale images to PGM format.

ImageGear Supported versions:

October 1991 - last release

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_RAW - Grayscale: 8, 16 bpp
  • IG_COMPRESSION_ASCII - Grayscale: 8, 16 bpp

ImageGear Write Support:

  • IG_COMPRESSION_RAW - Grayscale: 8, 16 bpp
  • IG_COMPRESSION_ASCII - Grayscale: 8, 16 bpp

ImageGear Filter Control Parameters:

None

Comments:

This format quickly and easily transfers grayscale bitmap images. This format, as well as PBM, PNM, and PPM, are at the core of a set of utility programs also written by Jef Poskanzer. These formats serve as an intermediary storage methods for the conversion of other file formats.

The Portable Graymap File Format structure is very simple. It begins with a short ASCII header that contains the file type identifier (magic number), the width and height of the image, a "maximum gray value", and perhaps a comment line identifying the filename. The bitmap data follows white space (usually a carriage return). The number of pixels is equal to width * height. A pixel value of 0 indicates black, and a "maximum gray value" is equivalent to white.

The magic number of the header can have one of two values: either P2 or P5. P2 indicates that the bitmap data is read as ASCII decimal values. P5 indicates that the bitmap data is stored as plain bytes. This makes for a smaller and faster-to-read file.

If the maximum gray value does not exceed 255 (28 = 256 gray values from 0 to 255), each pixel is represented by a 8-bit sample. ImageGear loads such images as 8-bit grayscale. Otherwise, each pixel is represented by a 16-bit sample. ImageGear loads these images as 16-bit grayscale.

See Also:

PPM, PBM, PNM

References used

Kay, David C. and John R. Levine. Graphics File Formats, 2nd ed. Windcrest /McGraw-Hill, 1995.

PGM Specification by Jef Poskanzer, copyright © 1989, 1991.


PNG

Full Name
PNG (Portable Network Graphics)
Format ID
IG_FORMAT_PNG = 33
File Extension(s)
*.png
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Supports single alpha channel for read/write.
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • 10th draft (future drafts will be backward-compatible)
  • PNG v2

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_DEFLATE:
    • Indexed RGB: 1, 2, 4, 8 bpp;
    • Grayscale: 1, 2, 4, 8, 16 bpp;
    • Grayscale + Alpha: 8, 16 bpp;
    • RGB: 24, 48 bpp;
    • RGB + Alpha: 32, 64 bpp

ImageGear Write Support:

  • IG_COMPRESSION_DEFLATE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8, 16 bpp;
    • Grayscale + Alpha: 16, 32 bpp;
    • RGB: 24, 48 bpp;
    • RGB + Alpha: 32, 64 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
BUFFER_SIZE
DWORD
0
Size of the buffer for strip if STRIP_CONFIG is IG_PNG_STRIP_FIXED_BUFFER
COMP_LEVEL
UINT
IG_PNG_DEFAULT_COMPRESSION
IG_PNG_DEFAULT_COMPRESSION,
IG_PNG_MIN_COMPRESSION,
IG_PNG_MAX_COMPRESSION
Compression level. It must be between IG_PNG_MIN_COMPRESSION and IG_PNG_MAX_COMPRESSION. Better compression takes more time for compression.
KEEP_ALPHA
BOOL
TRUE
TRUE,
FALSE
When loading: if this parameter is True, then alpha channel is loaded into Alpha DIB. Otherwise, the image is transformed into RGB, by compositing over the background supplied in the bKGD chunk, if it is present, or over the default background.
When saving:
if this parameter is True, and alpha DIB is present, it will be written to the file.
SAVE_INDEXED_GRAY_AS_GRAY
BOOL
FALSE
FALSE,
TRUE
Affects saving of images that have grayscale palette. If TRUE then IG saves the image as Grayscale (type 0). Otherwise, IG saves the image as Paletted (type 3).
STRIP_CONFIG
INT
IG_PNG_STRIP_FIXED_COUNT = 0
IG_PNG_STRIP_FIXED_COUNT,
IG_PNG_STRIP_FIXED_BUFFER
Format of PNG strip, see IG_PNG_STRIP_... constants
STRIP_COUNT
INT
0
Number of lines in one strip if STRIP_CONFIG is IG_PNG_STRIP_FIXED_COUNT

Comments:

The PNG (pronounced "Ping") format was created out of reaction to Unisys's announcement that it would begin requiring royalty fees for use of its LZW compression scheme. This was the compression scheme for the widely-used GIF format (found in Web pages and online library images).

Thomas Boutell and a host of other programmers began working to devise a new file format to eliminate the need for payment of royalty fees. The result was a file format that offers better compression than GIF, and adds features GIF doesn't offer, including truecolor, and full alpha channel and gamma correction.

The basic organization of the PNG file format utilizes storage structures known as "chunks". A chunk is a block of data that contains its own header (identifying the chunk size and type). This makes it easy for a PNG viewer to identify chunks and to skip over the ones that are not necessary.

The first entry in a PNG file is the "PNG signature" that identifies the format as PNG. The file then proceeds with a series of chunks.

The IHDR Image Header, or IHDR Chunk, contains a number of fields including the height, width, depth, color type, and compression type of the image. The only valid compression value is 0, which indicates the PNG's custom compression scheme, a deflate/inflate compression with a 32k sliding window. This is a derivative of ZZ77, the precursor to LZW. ZZ77 is the compression scheme used by pkzip software.

The "PLTE Palette Chunk" contains 1 to 256 palette entries. This is present if the type field of the header chunk is set to 3. The number of colors cannot exceed the range provided by the bit depth.

The image data is stored in "IDAT Image Data Chunks". These are subdivided into chunks whose size is usually determined by the size of the encoder's buffer. The data may be stored in "interlaced order" allowing the image to be "faded in". The data may also be interlaced. Interlacing helps the appearance of an image as it displays while being decompressed, so that it "fades in". In a non-interlaced file, the presentation of the image data begins with row 1 and works downward to the last row of data. This method of display does not allow a quick preview of the whole image. When the data is interlaced, the lines are saved and displayed out of sequence. Every fourth row is displayed first and then filled in with every remaining fourth row, until all of the lines are displayed. This allows the eye to perceive the basic subject of the whole image before it is completely displayed.

"Ancillary Chunks" are optional. They must appear before the first IDAT and after the PLTE. One chunk is the "bKGD chunk" that sets the default background color for the image. Two of the other ancillary chunks are the "hHist Chunk" or histogram chunk, and the "tEXt" chunk. The histogram chunk appears if there is a palette. It stores the frequency of each color of the palette as it occurs in the image data. If the application doesn't support all of the colors in the palette, the histogram can be used to choose a subset of colors. There may be any number of text chunks. They can vary in length from 0 to the maximum chunk size. They include the image author, copyright information, and any desired comments.

Questions about PNG can be e-mailed to: png-info@uunet.uu.net

References used:

Murray, James D. "Graphic Image Format FAQ 3-4". James D. Murray, 1994-1996.

PNG (Portable Network Graphics), tenth draft. Page 5, copyright Thomas Boutell, May 1995.

Wegner, Tim. "Coding for PNG Graphics", "PC Techniques", Feb/Mar 1996, pp 32-38.


PNM

Full Name
PNM (Portable Any-Map File Format)
Format ID
IG_FORMAT_PBM = 28 (See the Note below)
File Extension(s)
*.pnm
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

NOTE: ImageGear supports PNM file format via its IG_FORMAT_PBM format filter. Use IG_FORMAT_PBM to save images to PNM format.

ImageGear Supported versions:

October 1991 - last release

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_RAW:
    • Indexed RGB: 1 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp
  • IG_COMPRESSION_ASCII:
    • Indexed RGB: 1 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp

ImageGear Write Support:

  • IG_COMPRESSION_RAW:
    • Indexed RGB: 1 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp
  • IG_COMPRESSION_ASCII:
    • Indexed RGB: 1 bpp;
    • Grayscale: 8, 16 bpp;
    • RGB: 24, 48 bpp

ImageGear Filter Control Parameters:

None

Comments:

The PNM format is useful for quick and easy transfer of uncomplicated monochrome, grayscale, or color bitmap images. This format, as well as the PBM, PGM, and PPM formats, are at the core of a set of utility programs also written by Jef Poskanzer. These formats serve as intermediary storage methods for the conversion of other file formats. For example, a function called gifftoppm translates a GIF file to a PPM, from where it can be then translated to a TIFF using the pnmtotiff.

The Portable Anymap File Format structure is very simple. The "Anymap" portion of its name refers to the fact that it can be one of three types of UNIX bitmap file formats: the Portable Bitmap File Format (PBM), the Portable Graymap File Format (PGM), or the Portable Pixelmap File Format (PPM). A PNM begins with a short ASCII header that contains the file type identifier (magic number), the width and height of the image, a "maximum color-component value" if it is a PPM, a "maximum gray value" if it is a PGM, and perhaps a comment line identifying the filename. Following white space (usually a carriage return) is the bitmap data. For PGM and PPM files, the number of pixels is equal to width * height (whereas, in a PBM file, this calculation gives you the number of bits).

The magic number of the header can have one of six values depending on whether the bitmap is in PBM, PGM, or PPM format. Each format can have one of two magic numbers depending on whether the pixel data is stored in ASCII decimal or plain bytes. See the descriptions for the individual formats (these are all supported by ImageGear) for more details.

References used

Kay, David C. and John R. Levine. Graphics File Formats, 2nd ed. Windcrest /McGraw-Hill, 1995.

PBM, PGM, PPM, PNM Specifications by Jef Poskanzer, copyright © 1989, 1991.


PPM

Full Name
PPM (Portable Pixmap File Format)
Format ID
IG_FORMAT_PBM = 28 (See the Note below)
File Extension(s)
*.ppm
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

NOTE: ImageGear supports PPM file format via its IG_FORMAT_PBM format filter. Use IG_FORMAT_PBM to save truecolor images to PPM format.

ImageGear Supported versions:

October 1991 - last release

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_RAW - RGB: 24, 48 bpp
  • IG_COMPRESSION_ASCII - RGB: 24, 48 bpp

ImageGear Write Support:

  • IG_COMPRESSION_RAW - RGB: 24, 48 bpp
  • IG_COMPRESSION_ASCII - RGB: 24, 48 bpp

ImageGear Filter Control Parameters:

None

Comments:

The PPM format is useful for quick and easy transfer of color bitmap images. This format, as well as the PBM, PGM, and PNM formats, are at the core of a set of utility programs also written by Jef Poskanzer. These formats serve as intermediary storage methods for the conversion of other file formats. For example, a function called gifftoppm translates a GIF file to a PPM, where it can translate to a TIFF using the pnmtotiff.

The Portable Pixmap File Format structure is very simple. It begins with a short ASCII header that contains the file type identifier (magic number), the width and height of the image, a "maximum color-component value", and perhaps a comment line identifying the filename. Following white space (usually a carriage return) is the bitmap data. The number of pixels is equal to width * height, with each pixel being represented by three bytes: one each for Red, Green, and Blue color components, respectively.

The magic number of the header can have one of two values: either P3 or P6. P3 indicates that the bitmap data is read as ASCII decimal values. P6 indicates that the bitmap data is stored as plain bytes. This makes for a smaller and faster-to-read file.

If the maximum gray value exceeds 255 (28 = 256 gray values from 0 to 255), each pixel is represented by three 16-bit RGB samples, making a total of 48 bits per pixel. ImageGear loads such images to 24-bit RGB.

See Also:

PGM, PBM, PNM

References used:

Kay, David C. and John R. Levine. Graphics File Formats, 2nd ed. Windcrest /McGraw-Hill, 1995.

PPM Specification by Jef Poskanzer, copyright © 1989, 1991.


PTOCA

Full Name
PTOCA (Presentation Text Object Content Architecture)
Format ID
IG_FORMAT_PTOCA = 65
File Extension(s)
*.pto, *.mod
Data Type
Metafile
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, .NET, .NET64

ImageGear Supported versions:

  • Format 2

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE - Indexed RGB: 8 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
FACTOR
DOUBLE
1.0
Linear DIB size Factor.

Comments:

ImageGear can read PTOCA files as content of multi- and single-page MOD:CA files, ensuring better compatibility with IBM's AFP (Advanced Function Presentation) printer architecture.

The PT object structure starts with the "Begin Presentation Text" structure field and finishes with the "End Presentation Text" structure field. Text data is placed between these fields and consists of graphic characters and control sequences that describe how the text will be shown on the presentation surface. The PT object can include some other optional structured fields that define initial presentation text values. If PTOCA is included in the MOD:CA content, some presentation text parameters (like code page, font, an initial values) can be defined on the MOD:CA level.

References used:

IBM BookManager BookServer, Copyright 1989, 1999, IBM Corporation.


QuickTime

Full Name
QT (Quick Time movie)
Format ID
IG_FORMAT_QUICKTIMEJPEG = 76
File Extension(s)
*.jpg, *.mov, *.qt
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC

NOTE: To support QuickTime format ImageGear Multimedia Component should be attached to Core ImageGear.

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

IG_COMPRESSION_JPEG - RGB: 24 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

None

Comments:

QuickTime format has been developed by Apple, inc. as a container for various media such as video and audio clips and still images.

ImageGear Core component supports loading of the first frame from JPEG- and Motion JPEG compressed QuickTime files.


RAS

Full Name
RAS (Sun Raster Data Format)
Format ID
IG_FORMAT_RAS = 37
File Extension(s)
*.ras
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 1, 8 bpp;
    • RGB: 24 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
SAVE_COMPRESSED
INT
0 (FALSE)
TRUE,
FALSE
Compression flag. If TRUE the saving image will be RLE compressed.

Comments:

Bitmap images used under the SunOS system and UNIX imaging applications are usually stored in Sun Raster form.

The Sun Raster header contains image data (size and type), and the type and size of the colormap, if present. It also contains a Sun Raster identifying tag called "MagicNumber," which always contains the same value. A type field identifies the version of Sun Raster, the most common are called "Old" and "Standard". These are actually the same format and indicate that the image is not compressed. Other possible versions of Sun Raster files include TIFF and IFF, meaning that the image data was converted from one of these formats.

Following the header is a colormap, if applicable. Most 24 or 32-bit raster images do not use a colormap, but rather store the color values directly with the image data. This is known as "truecolor".

The last element of the Sun Raster file is the image data itself. It is usually in 2D raster format.

References used:

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


RAW

Full Name
RAW (Raw image)
Format ID
IG_FORMAT_RAW = 58
File Extension(s)
*.raw
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Yes
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 9-16 bpp;
    • RGB: 24 bpp;
    • RGB + Alpha: 32 bpp
  • IG_COMPRESSION_LZW:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 9-16 bbp;
    • RGB: 24 bpp;
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_CCITT_G32D:
    • Indexed RGB: 1 bpp
  • IG_COMPRESSION_ABIC:
    • Indexed RGB: 1 bpp
NOTE: To use ABIC compression scheme ImageGear ABIC Component should be attached.

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
ALIGNMENT
UINT
0
0, 1, 2, 4
Row alignment.
0: DWORD alignment
1: BYTE alignment
2: WORD alignment
4: DWORD alignment
BITS_PER_PIXEL
UINT
0
Used internally
COMPRESSION
AT_MODE
0
Used internally
FILL_ORDER
INT
0
Used internally
HEIGHT
AT_DIMENSION
0
Used internally
UNCOMPRESSED_PACKED
BOOL
FALSE
FALSE, TRUE
Set to TRUE to read uncompressed packed RAW format, where pixels are not padded to a byte boundary. Set to FALSE to read unpacked format. For example, two 12-bit pixels occupy 3 bytes in the packed format, and 4 bytes in the unpacked format.
WIDTH
AT_DIMENSION
0
Used internally

Comments:

A raw image file contains no header or identifying information. Also, ImageGear can load images of proprietary or unsupported formats as Raw data. Since ImageGear cannot obtain parameters, such as width, height or bits per pixel from the file, the application should specify them. For uncompressed images, ImageGear assumes BMP row order (bottom line goes first). If the RAW image uses the other row order, use IG_IP_flip function to flip it vertically after loading.


Scitex CT

Full Name
SciTex (Scitex CT)
Format ID
IG_FORMAT_SCI_CT = 91
File Extension(s)
*.sct
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE - CMYK: 32 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE - CMYK: 32 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
HEIGHT_IN_UNITS
DOUBLE
Height of the picture, in measurement units.
WIDTH_IN_UNITS
DOUBLE
Width of the picture, in measurement units.
FILE_TYPE
WORD
"CT"
"CT"
Scitex file type. The only "CT" - Continuous Tone Picture is currently supported.
UNITS_MEASUREMENT
BYTE
0
1
Units of measurement
(0 mm, 1 inches)
SCAN_DIRECTION
BYTE
ScanDirection is a bitmap indicating the position of the image source on the scanner. The bitfields are defined as follows:
Bit 0
0 = Top to bottom, 1 = Bottom to top
Bit 1
0 = Left to right,
1 = Right to left
Bit 2
0 = No rotation,
1 = 90 degree counter-clockwise rotation
Bits 3:7
Undefined (always 0)

Comments:

ImageGear has read and write support for Scitex HandShake Continuous Tone Picture files. This is the native format used by Scitex scanners and printers for high-end image processing and color separation.

Scitex CT files store uncompressed, CMYK true-color raster data. They contain a Control Block, a Parameters Block, and the image data. Scitex CT images are typically four-color separation, CMYK, line-interleaved raster data. The separations are always stored by scan line and in the order C-M-Y-K (cyan-magenta-yellow-black). A color pixel value have up to 16 separations (128 bits) in size. Separations 1 through 4 are defined in order (C-M-Y-K). Separations 5 through 16 are reserved for future expansion of the format, as shown below.

Each row or Scitex CT image data is stored in separated color. The first separation's row data is followed by the second, and so forth, up to the number of separations specified by NumColorSeparations. Only the data for the separations defined by the SeparationsBitMask field is actually stored in the CT file. Each pixel can contain up to 16 separation components and each component is one byte in size. A CMYK pixel contains four components and is of a 32-bit size. Remember that the data is not stored by pixel, but by separation. If rows contain odd numbers of bytes, the zero padding byte will be added to the end of each separation to preserve word alignment.

Note: You can set ImageGear CMYK Support level to IG_CONVERT_TO_RGB to convert CMYK images to 24-bit RGB during loading. However, use of this mode is deprecated. We recommend to load the image in its native format, and then convert to desired colorspace if needed.

References used

Copyright© 1994, 1996, O'Reilly & Associates, Inc.


SGI

Full Name
SGI (Silicon Graphics Image)
Format ID
IG_FORMAT_SGI = 38
File Extension(s)
*.sgi, *.bw, *.rgb, *.rgba
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Supports single alpha channel for read and write.
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • Grayscale + Alpha: 16 bpp;
    • RGB + Alpha: 32 bpp
  • IG_COMPRESSION_RLE:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • Grayscale + Alpha: 16 bpp;
    • RGB + Alpha: 32 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp;
    • Grayscale + Alpha: 16 bpp;
    • RGB + Alpha: 32 bpp
  • IG_COMPRESSION_RLE:
    • Grayscale: 8 bbp;
    • RGB: 24 bpp;
    • Grayscale + Alpha: 16 bpp;
    • RGB + Alpha: 32 bpp;

ImageGear Filter Control Parameters:

None

Comments:

This format was developed for use with the SGI image library included on most Silicon Graphics computers. Most SGI images are black and white.

The major components of an SGI file are the 512-byte header, a "scan-line offset table", and the bitmap header. SGI is one of the few formats to use a scan-line offset table.

The fields of the header structure include a compression flag (1 = compressed), the height and width (in pixels) of the image, the number of bit planes, the highest pixel value and the lowest pixel value, the name of the image, and pixel format. Pixel format can indicate the number of color channels, whether the image is dithered to a single channel, and whether the bitmap image is actually a color map for other images.

The bitmap data is stored up-side-down-the first scan line is at the bottom of the bitmap. If the data is RLE, a scan-line offset table is present, following the header and preceding the bitmap. This increases compression further by allowing repeated offsets to the same scan line, if several scan lines have the same value. A grayscale image may even refer to the same scan line from three different bit fields. For this reason, and because SGI data that is compressed can be stored in any scan-line order, the offset table must not be ignored.

References used

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats, 2d ed. Sebastopol, CA: O'Reilly & Associates, Inc., 1996.


SVG

Full Name
SVG (Scalable Vector Graphics format)
Format ID
IG_FORMAT_SVG = 77
File Extension(s)
*.svg
Data Type
Vector Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64

NOTE: To support SVG format ImageGear CAD/Vector SVG Component should be attached to Core ImageGear.

ImageGear Supported versions:

  • SVG 1.1 (partial)

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE - Vector data

ImageGear Write Support:

  • IG_COMPRESSION_NONE - Vector data

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
EXTERN_FILE_PATH
String
""
Any string up to 262 characters
Defines a path where external files (like raster images) should be looked for. A value of "" looks in the same directory as the file being loaded.
WIDTH
Long
512
Any positive value
Defines the DIB width of the loaded image. The DIB height is calculated using the file's scale factors.

Comments:

SVG (Scalable Vector Graphics) is a platform for two-dimensional graphics. It has two parts: an XML-based file format and a programming API for graphical applications. SVG allows for three types of graphic objects: vector graphic shapes (e.g., paths consisting of straight lines and curves), raster images, and text. Graphical objects can be grouped, styled, transformed and composited into previously rendered objects. Text can be in any XML namespace suitable to the application, which enhances searchability and accessibility of the SVG graphics. The feature set includes nested transformations, clipping paths, alpha masks, filter effects, template objects and extensibility.

SVG drawings can be dynamic and interactive. The Document Object Model (DOM) for SVG, which includes the full XML DOM, allows for straightforward and efficient vector graphics animation via scripting. A rich set of event handlers such as onmouseover and onclick can be assigned to any SVG graphical object. Because of its compatibility and leveraging of other Web standards, features like scripting can be done on SVG elements and other XML elements from different namespaces simultaneously within the same Web page.

References used

About SVG - 2d Graphics in XML.- http://www.w3.org/Graphics/SVG/About.html


TGA

Full Name
TGA (Truevision Targa)
Format ID
IG_FORMAT_TGA = 39
File Extension(s)
*.tga, *.tpic
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
Single alpha channel for read/write
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 2.0, 1991
  • Version 1.0, 1984

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Grayscale: 1 bpp;
    • Indexed RGB: 8 bpp;
    • RGB: 15, 24 bpp;
    • RGB 15 bpp + Alpha 1 bpp;
    • RGB 24 bpp + Alpha 8 bpp;
    • RGB 15 bpp + Premultiplied Alpha 1 bpp;
    • RGB 24 bpp + Premultiplied Alpha 8 bpp;
    • RGB 15 bpp + Extra 1 bpp;
    • RGB 24 bpp + Extra 8 bpp;
  • IG_COMPRESSION_RLE:
    • Grayscale: 1 bpp;
    • Indexed RGB: 8 bpp;
    • RGB: 15, 24 bpp;
    • RGB 15 bpp + Alpha 1 bpp;
    • RGB 24 bpp + Alpha 8 bpp;
    • RGB 15 bpp + Premultiplied Alpha 1 bpp;
    • RGB 24 bpp + Premultiplied Alpha 8 bpp;
    • RGB 15 bpp + Extra 1 bpp;
    • RGB 24 bpp + Extra 8 bpp;

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 8 bpp;
    • RGB: 15, 24 bpp;
    • RGB 15 bpp + Alpha 1 bpp;
    • RGB 24 bpp + Alpha 8 bpp;
    • RGB 15 bpp + Extra 1 bpp;
    • RGB 24 bpp + Extra 8 bpp;
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 8 bpp;
    • RGB: 15, 24 bpp;
    • RGB 15 bpp + Alpha 1 bpp;
    • RGB 24 bpp + Alpha 8 bpp;
    • RGB 15 bpp + Extra 1 bpp;
    • RGB 24 bpp + Extra 8 bpp;

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
AUTHOR_COMMENT
STRING
" "
Author's comments.
AUTHOR_NAME
STRING
" "
Name of author.
IMAGE_ID
STRING
" "
Image ID
SOFTWARE_ID
STRING
" "
Software ID
STAMP_DAY
WORD
0
Day stamp
STAMP_HOUR
WORD
0
Hour stamp
STAMP_MINUTE
WORD
0
Minute stamp
STAMP_MONTH
WORD
0
Month stamp
STAMP_SECOND
WORD
0
Second stamp
STAMP_YEAR
WORD
0
Year stamp
KEEP_ALPHA
BOOL
FALSE
TRUE, FALSE
FALSE means to ignore Alpha bits. Non-zero (TRUE) means to pass alpha bits back through callback.
PROMOTE16
BOOL
FALSE
TRUE, FALSE
FALSE means to create 16 bit DIB without promoting to 24 bits. Non-zero (TRUE) means promoting.
HEADER_TYPE
INT
0
1 or 2
1 or 2 for revision level of header
STORES_TAMP
BOOL
FALSE
TRUE, FALSE
FALSE for no stamp, TRUE to save a stamp with image. HEADER_TYPE must be 2.
STAMP_WIDTH
BOOL
0
TRUE, FALSE
Stamps width must not be larger than 64 pixels
STAMP_HEIGHT
BOOL
0
TRUE, FALSE
Stamps height must not be larger than 64 pixels
PALETTE
BOOL
FALSE
TRUE, FALSE
TRUE indicates that color map should be created.
CONV_TO_16
BOOL
FALSE
TRUE, FALSE
If TRUE, convert to 16 bpp when saving.
THUMB_FLAG
UINT
0
TRUE,
FALSE
TRUE if save should include a thumbnail.
THUMB_WIDTH
UINT
0
Width of thumbnail.
THUMB_HEIGHT
UINT
0
Height of thumbnail - Thumbnails are 24 bit.

Comments:

This file format was originally developed by AT&T for use with its image capture boards. The format was taken over by Truevision when it acquired the product line from AT&T. It is now commonly used for digitized images and also for high-quality images produced by ray tracers and other graphics applications.

It became a popular file format mainly because it was the first 24-bit truecolor format to come to the PC market. There are several varieties of Targa files; the most commonly used are the Targa 16, Targa 24, and Targa 32. The names are derived from the type of hardware used to create them.

The fixed-sized header information of the Targa format includes: the existence (or not) and colormap, location, size, pixel depth, image location, colormap (if it exists), and finally the image data itself.

Version 2.0 introduced a file footer that identifies it as the newest version and contains pointers to additional fields in two main structures: the "extension area" and the "developer directory". The extension area contains the addresses of many optional fields, one of the most popular being the "postage stamp image" (miniature of the main image).

The developer directory can be used to store proprietary information. Developers can register their own private fields with Truevision. A null-terminated ASCII string containing "TRUEVISION-XFILE.", and positioned at the end of the file, indicates that the footer is valid.

Targa defines 3 color methods: pseudo color, direct color, and truecolor. Pseudo color uses an index to a color palette. Direct color is like pseudo color except that the RGB components are looked up separately. In truecolor files, the color information is stored directly in the image data. The palettes used by Targa files are variable in size; they do not necessarily correlate to the bit depth of the image. The presence of a palette does not always mean that it is used to display the image.

Alpha channel handling

KEEP_ALPHA control parameter must be set to TRUE to enable loading and saving of Alpha/Extra channels from TGA images.

If bits 0..3 of Image Descriptor field are set to non-zero (additional channel is present), ImageGear treats additional bits as follows, depending on the Attributes Type field:

Attributes Type value
Attributes type value meaning
Additional bits are loaded as:
0
No Alpha Data included
Non-premultiplied Alpha (for incompliant images where Image Descriptor tells there is an additional channel but Attributes Type field is not set.)
1
Undefined data, can be ignored
Extra channel
2
Undefined data, should be retained
Extra channel
3
Non-premultiplied Alpha
Non-premultiplied Alpha
4
Premultiplied Alpha
Premultiplied Alpha
Other
Reserved or unassigned
Non-premultiplied Alpha

If bits 0..3 of Image Descriptor field are set to zero (no additional channel is present), ImageGear treats additional bits as Extra channel. This allows reading additional channel from images that have incorrect Image Descriptor field, but does not spoil image display if there is no meaningful data in the additional channel.

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


TIFF

Full Name
TIFF (Tagged Image File Format)
Format ID
IG_FORMAT_TIF = 40
File Extension(s)
*.tif, *.tiff
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
Yes
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 6.0 - Added support for CMYK and YCbCr color images, and JPEG compression. Ability to store pixels in "tiles"
  • Version 5.0 - Added ability to store palette color images and support for LZW compression. This version featured TIFF "classes."
  • Version 4.0 - Added support for uncompressed RGB color images.
  • Version 3.0 - First public release.

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_MPAGEWRITEPSUPPORT - multipage file writing
  • IG_FLTR_PAGEDELETESUPPORT - page deleting from multi-page file
  • IG_FLTR_PAGESWAPSUPPORT - page swaping in multi-page files
  • IG_FLTR_MPDATASUPPORT - faster multi-page access by storing private format data (used only with IG_mpi_... and IG_mpf_... API)

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB - 1, 2, 4, 8 bpp;
    • Grayscale - 1, 2, 4, 8, 12, 16, 32 bpp;
    • RGB: 3, 6, 12, 24, 36, 48 bpp;
    • Lab: 3, 6, 12, 24, 36, 48 bpp;
    • CMYK: 4, 8, 16, 32, 48, 64 bpp;
    • Grayscale + Premultiplied Alpha: 2, 4, 8, 12, 16, 32 bpp;
    • RGB + Premultiplied Alpha: 4, 8, 16, 32, 48, 64 bpp;
    • Indexed RGB + Extra: 1, 2, 4, 8 bpc;
    • Lab + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • CMYK + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • Grayscale + Premultiplied Alpha + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • RGB + Premultiplied Alpha + Extra: 1, 2, 4, 8, 12, 16 bpc.
  • IG_COMPRESSION_PACKED_BITS:
    • Indexed RGB - 1, 2, 4, 8 bpp;
    • Grayscale - 1, 2, 4, 8, 12, 16, 32 bpp;
    • RGB: 3, 6, 12, 24, 36, 48 bpp;
    • Lab: 3, 6, 12, 24, 36, 48 bpp;
    • CMYK: 4, 8, 16, 32, 48, 64 bpp;
    • Grayscale + Premultiplied Alpha: 2, 4, 8, 12, 16, 32 bpp;
    • RGB + Premultiplied Alpha: 4, 8, 16, 32, 48, 64 bpp;
    • Indexed RGB + Extra: 1, 2, 4, 8 bpc;
    • Lab + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • CMYK + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • Grayscale + Premultiplied Alpha + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • RGB + Premultiplied Alpha + Extra: 1, 2, 4, 8, 12, 16 bpc.
  • IG_COMPRESSION_HUFFMAN:
    • Indexed RGB: 1 bpp;
    • Grayscale: 1 bpp;
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp;
    • Grayscale: 1 bpp;
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp;
    • Grayscale: 1 bpp;
  • IG_COMPRESSION_CCITT_G32D:
    • Indexed RGB: 1 bpp;
    • Grayscale: 1 bpp;
  • IG_COMPRESSION_JPEG:
    • Grayscale: 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_DEFLATE:
    • Indexed RGB - 1, 2, 4, 8 bpp;
    • Grayscale - 1, 2, 4, 8, 12, 16, 32 bpp;
    • RGB: 3, 6, 12, 24, 36, 48 bpp;
    • Lab: 3, 6, 12, 24, 36, 48 bpp;
    • CMYK: 4, 8, 16, 32, 48, 64 bpp;
    • Grayscale + Premultiplied Alpha: 2, 4, 8, 12, 16, 32 bpp;
    • RGB + Premultiplied Alpha: 4, 8, 16, 32, 48, 64 bpp;
    • Indexed RGB + Extra: 1, 2, 4, 8 bpc;
    • Lab + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • CMYK + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • Grayscale + Premultiplied Alpha + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • RGB + Premultiplied Alpha + Extra: 1, 2, 4, 8, 12, 16 bpc.
  • IG_COMPRESSION_LZW:
    • Indexed RGB - 1, 2, 4, 8 bpp;
    • Grayscale - 1, 2, 4, 8, 12, 16, 32 bpp;
    • RGB: 3, 6, 12, 24, 36, 48 bpp;
    • Lab: 3, 6, 12, 24, 36, 48 bpp;
    • CMYK: 4, 8, 16, 32, 48, 64 bpp;
    • Grayscale + Premultiplied Alpha: 2, 4, 8, 12, 16, 32 bpp;
    • RGB + Premultiplied Alpha: 4, 8, 16, 32, 48, 64 bpp;
    • Indexed RGB + Extra: 1, 2, 4, 8 bpc;
    • Lab + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • CMYK + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • Grayscale + Premultiplied Alpha + Extra: 1, 2, 4, 8, 12, 16 bpc;
    • RGB + Premultiplied Alpha + Extra: 1, 2, 4, 8, 12, 16 bpc.
NOTE: To use LZW (Lempel-Ziv-Welch) compression scheme ImageGear GIF/ TIFF-LZW Component should be attached.

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8, 12, 16, 32 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 4, 32, 48, 64 bpp;
    • Grayscale + Premultiplied Alpha: 16, 24, 32, 64 bpp;
    • RGB + Premultiplied Alpha: 32, 48, 64 bpp;
    • Lab + Extra: 8, 12, 16 bpc;
    • CMYK + Extra: 8, 12, 16 bpc;
    • Grayscale + Premultiplied Alpha + Extra: 8, 12, 16 bpc;
    • RGB + Premultiplied Alpha + Extra: 8, 12, 16 bpc;
  • IG_COMPRESSION_PACKED_BITS:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8, 12, 16, 32 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 4, 32, 48, 64 bpp;
    • Grayscale + Premultiplied Alpha: 16, 24, 32, 64 bpp;
    • RGB + Premultiplied Alpha: 32, 48, 64 bpp;
    • Lab + Extra: 8, 12, 16 bpc;
    • CMYK + Extra: 8, 12, 16 bpc;
    • Grayscale + Premultiplied Alpha + Extra: 8, 12, 16 bpc;
    • RGB + Premultiplied Alpha + Extra: 8, 12, 16 bpc;
  • IG_COMPRESSION_HUFFMAN:
    • Indexed RGB: 1 bpp;
  • IG_COMPRESSION_CCITT_G3:
    • Indexed RGB: 1 bpp;
  • IG_COMPRESSION_CCITT_G4:
    • Indexed RGB: 1 bpp;
  • IG_COMPRESSION_CCITT_G32D:
    • Indexed RGB: 1 bpp;
  • IG_COMPRESSION_JPEG (Lossy, Progressive):
    • Grayscale: 8, 12 bpp;
    • RGB: 24, 36 bpp;
  • IG_COMPRESSION_JPEG (Lossless):
    • Grayscale: 8, 16 bpp;
    • RGB: 24 bpp;
  • IG_COMPRESSION_DEFLATE:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8, 12, 16, 32 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 4, 32, 48, 64 bpp;
    • Grayscale + Premultiplied Alpha: 16, 24, 32, 64 bpp;
    • RGB + Premultiplied Alpha: 32, 48, 64 bpp;
    • Lab + Extra: 8, 12, 16 bpc;
    • CMYK + Extra: 8, 12, 16 bpc;
    • Grayscale + Premultiplied Alpha + Extra: 8, 12, 16 bpc;
    • RGB + Premultiplied Alpha + Extra: 8, 12, 16 bpc;
  • IG_COMPRESSION_LZW:
    • Indexed RGB: 1, 4, 8 bpp;
    • Grayscale: 8, 12, 16, 32 bpp;
    • RGB: 24, 36, 48 bpp;
    • Lab: 24, 36, 48 bpp;
    • CMYK: 4, 32, 48, 64 bpp;
    • Grayscale + Premultiplied Alpha: 16, 24, 32, 64 bpp;
    • RGB + Premultiplied Alpha: 32, 48, 64 bpp;
    • Lab + Extra: 8, 12, 16 bpc;
    • CMYK + Extra: 8, 12, 16 bpc;
    • Grayscale + Premultiplied Alpha + Extra: 8, 12, 16 bpc;
    • RGB + Premultiplied Alpha + Extra: 8, 12, 16 bpc;
NOTE: To use LZW (Lempel-Ziv-Welch) compression scheme ImageGear GIF/ TIFF-LZW Component should be attached.

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
BIG_ENDIAN
BOOL
FALSE
FALSE,
TRUE
If TRUE, big endian order is used for write operation ("MM"), in other case little endian is used("II").
BUFFER_SIZE
DWORD
32768
any DWORD>0
This parameter specifies the buffer size for each strip for write operation if WRITE_CONFIG= =IG_TIF_STRIP_FIXED_BUFFER
DATETIME
LPCHAR
""
Specifies value for DateTime (tag 306) to write into image.
DO_NOT_WRITE_PALETTE
BOOL
FALSE
FALSE,
TRUE
Set to TRUE to skip the palette when writing a TIFF.
DOCUMENT_NAME
LPCHAR
""
any string
Specifies value for DocumentName (tag 269) to write into image.
FAST_PAGE_COUNT
BOOL
FALSE
FALSE,
TRUE
Affects page counting. When FALSE, ImageGear counts only those IFDs that contain images. When TRUE, ImageGear counts all IFDs, without checking for presence of images in them. The latter mode requires significantly less reading operations and thus works faster, especially if the image is accessed through a network.
FILL_ORDER
MODE
IG_FILL_MSB
IG_FILL_MSB
IG_FILL_LSB
Specifies fill order (tag 266) for tiff file to be written
IMAGE_BEFORE_IFD
BOOL
FALSE
FALSE,
TRUE
This flag specifies physical location of raster data inside TIFF file relatively to IFD record. If this value is TRUE then image data is to be written before IFD record.
IMAGE_HEIGHT
DWORD
0
Any positive value
Was used internally in previous versions of IG.
IMAGE_WIDTH
DWORD
0
Any positive value
Was used internally in previous versions of IG.
INCLUDE_PAGE_NUMBER
BOOL
TRUE
FALSE,
TRUE
If this parameter is TRUE then include tag 297 into TIFF image with real value of page number.
LOAD_FIRST_UNKNOWN_CHANNEL_AS_PALPHA
BOOL
TRUE
TRUE,
FALSE
This parameter specifies how to load first extra channel if ExtraSamples tag is missing. If TRUE, IG loads first extra channel as Premultiplied Alpha channel. This mode provides support for RGBPA TIFF images written by earlier versions of ImageGear. If LoadFirstUnknownChannelAsPAlpha is FALSE, IG loads all extra channels as extra channels.
MISSING_COMPRESSION
Long
0
Missing compression
NEW_SUBFILE_TYPE
UINT
0xFF
This parameter specifies value for tag 254. If value of this control parameter 0xFF then default value is used according to TIFF 6.0 format specification.
NUMBER_OF_STRIPS
UINT
1
any value >0
If WRITE_CONFIG= =IG_TIF_STRIP_FIXED_COUNT then this value is used as the number of strips to be written
PHOTOMETRIC
UINT
IG_TIF_PHOTO_WHITEZERO
IG_TIF_PHOTO_WHITEZERO,
IG_TIF_PHOTO_BLACKZERO,
IG_TIF_PHOTO_RGB,
IG_TIF_PHOTO_CMYK,
IG_TIF_PHOTO_PALETTE,
IG_TIF_PHOTO_TRANSPARENCY,
IG_TIF_PHOTO_YCBCR,
IG_TIF_PHOTO_CIELAB
Specifies photometric interpretation (tag 262) for write operation.
PLANAR
BOOL
FALSE
FALSE,
TRUE
Specifies tag value 284 for output image.
READ_JPEG_AS_YCBCR
BOOL
FALSE
TRUE,
FALSE
For internal use.
SAVE_DIFF_
PREDICTOR
BOOL
FALSE
FALSE,
TRUE
If this parameter is TRUE,
then output TIFF-LZW image
will be produced using the horizontal differencing predictor.
SAVE_INDEXED_GRAY_AS_GRAY
BOOL
TRUE
FALSE,
TRUE
Affects saving of images that have grayscale or interted grayscale palette. If TRUE then IG saves the image with BlackZero or WhiteZero photometric interpretation. Otherwise, IG saves the image as Paletted.
STITCH_TILES
BOOL
FALSE
TRUE,
FALSE
Set to TRUE to enable automatic tile stitching during image loading.
SUBIFD_PATH
LPCHAR
Empty string
Number of the SubIFD to load the image from. If set to empty string (default), load image from root IFD. See "Camera Raw Image support" section for more detail.
TILE_H_COUNT
DWORD
10
If WRITE_CONFIG==IG_TIF_TILED_FIXED_COUNT
then this value is used as number of tiles in horizontal dimension.
TILE_HEIGHT
DWORD
If WRITE_CONFIG==IG_TIF_TILED_FIXED_SIZE
then this value is used to specify vertical dimension of each tile.
TILE_V_COUNT
DWORD
10
If WRITE_CONFIG==IG_TIF_TILED_FIXED_COUNT
then this value is used as number of tiles in vertical dimension.
TILE_WIDTH
DWORD
64
If WRITE_CONFIG==IG_TIF_TILED_FIXED_SIZE
then this value is used to specify horizontal dimension of each tile.
UPDATE_LUT16
BOOL
TRUE
TRUE,
FALSE
UPDATE_PAGE_NUMBERS
BOOL
TRUE
TRUE,
FALSE
WRITE_CLASS_F
BOOL
FALSE
FALSE,
TRUE
If this value is TRUE then image to be written in TIFF format compatible with class F requirements.
WRITE_CONFIG
MODE
IG_TIF_STRIP_FIXED_COUNT
IG_TIF_STRIP_FIXED_COUNT,
IG_TIF_STRIP_FIXED_BUFFER,
IG_TIF_TILED_FIXED_SIZE,
IG_TIF_TILED_FIXED_COUNT
Specifies configuration of TIFF file to be written:
IG_TIF_STRIP_FIXED_COUNT - writes fixed number of strips.
IG_TIF_STRIP_FIXED_BUFFER - writes strips of size no more then given size
IG_TIF_TILED_FIXED_SIZE - writes image in tiles of specified size
IG_TIF_TILED_FIXED_COUNT - devides image into specified number of tiles vertically and horizontally.
WRITE70
BOOL
TRUE
FALSE,
TRUE
If this value is TRUE then output TIFF-JPEG image will be produced in TIFF 7.0 compatible format but in other case it will be compatible with TIFF 6.0.

Comments:

TIFF was developed for use in storing black-and-white images from scanners and desktop publishing applications. Now, in its fourth release (version 6.0), it is one of the most detailed and versatile bitmap formats in use. It is supported by most art, imaging, and word-processing applications. It supports several compression schemes. Aside from saving image data in bitmap form, it can also contain vector or text-based images.

Containing just three fields, the TIFF header is simple and one of the shortest of all the graphics file format headers. But, the structure of a TIFF is complicated, with variable length fields, variable number of fields, and the ability to store information (other than the header) in any order desired.

The other two major components of the TIFF format are "Image File Directories" (IFDs) and the image or images themselves. There is one IFD per image stored. The combination of an IFD and an image is referred to as a "subfile". The header contains an offset pointer to the first IFD. If there are multiple IFDs, each contains an offset to the next. The last IFD contains a value that signifies the end of the file.

IFDs closely resemble a header structure, and the information stored in them is often referred to as "TIFF Header Information". Unlike a header, however, they contain a variable number of "tags" (pointers or fields). In addition, each tag can point to data with a variable length. TIFFs are notorious for the number of tags that they can contain, up to a maximum of 65,535 tags of nearly 100 different types (version 6.0). Tags are listed in order by code number so that a TIFF reader can easily determine what fields are present. While ImageGear reads and stores all TIFF tags, it utilizes a subset of all of the possible tags. See note on previous page.

In version 5.0, the presence of certain subgroups of tags determined what "class" the TIFF belonged to. The classes are: TIFF-B-monochrome, TIFF-F-fascimile, TIFF-G-grayscale, TIFF-P-palette based, TIFF-R-RGB color, TIFF-X-any class, TIFF-Y-can use JPEG compression. Version 6.0 uses tags to divide the TIFF type into different file configurations, leaving behind the class concept. Version 6.0 configurations are: Bilevel, palette color, RGB, grayscale, YCbCr, and Class F (fascimile).

TIFF bitmap data can be stored in one of two configurations: strips or tiles. Strips are groups of adjoining rows of bitmap data, and can be found in version 5.0 and 6.0 files. Tiles were new to TIFF version 6.0. They are rectangular or square sections of bitmap data. The method of storage is determined in part by what kind of compression (if any) is used. JPEG compression can handle tiled images. Due to the need for padding with tile storage, tiling is not usually efficient for small images.

ImageGear supports the following compression schemes for TIFF:

    • Uncompressed
    • CCITT Group 3
    • CCITT Group 3 2D
    • CCITT Group 4
    • Huffman
    • JPEG
    • Lossless JPEG
    • LZW (Lempel-Ziv-Welch)
    • Packbits
    • Progressive JPEG
    • Deflate

See the ImageGear Supported Compressions Reference for descriptions of these compression types. The compression tag of the IFD tells whether the image is compressed, and by what method. (Not all TIFF files can use JPEG compression. It is supported by version 6.0, but in version 5.0, only a "Y" class TIFF can use JPEG).

TIFF/EP

TIFF/EP format was designed to provide a means for storing "raw" (unprocessed) image from digital camera's sensor.

TIFF/EP allows to store several versions of the same image in one file. Typically, TIFF/EP image includes a small preview and a raw image. It can also include a larger or full-size preview, or some other variations of the image.

TIFF/EP uses IFD trees for storing different versions of image. This is different from IFD chains that are used in baseline TIFF to store multiple pages.

ImageGear does not detect TIFF/EP as a separate file format. If Raw detection is enabled, and ImageGear can recognize TIFF/EP file as a known Raw format, it detects and loads the file as DCRAW. Otherwise it detects TIFF/EP as TIFF. One of well known extensions to TIFF/EP is Adobe DNG format. ImageGear detects it as a separate file format.

Most of digital cameras store pixels in "mosaic" format. At a given pixel location either a Red, Green, Blue, Cyan, or some other color sample value is recorded. Such images are referred to as "Color Filter Array" type. TIFF/EP format uses a two-dimensional matrix called "Color Filter Array pattern" to describe positions of pixels of particular color in the mosaic image. In order to recreate the full color values in each pixel, it is necessary to interpolate intensities of neighbouring pixels.

To enable loading images from TIFF SubIFDs, a new control parameter is added to TIFF filter: "SUBIFD_PATH". This parameter has the type of String, and its default value is "" (empty string). By default, ImageGear loads the image in the root IFD (thumbnail). If "SUBIFD_PATH" string begins with a number, then ImageGear loads the image from the corresponding SubIFD of the root IFD. For example, if SUBIFD_PATH is set to "3", ImageGear will load the image from the 3rd SubIFD.

SUBIFD_PATH parameter also affects metadata reading. Metadata is loaded starting from the IFD specified by SUBIFD_PATH.

NOTE: ImageGear does not support color reconstruction of TIFF/EP images, unless they are detected to be a Adobe DNG or a DCRAW image supported by ImageGear.

References used:

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Murray, James D. "Graphic Image Format FAQ 3-4". James D. Murray, 1994-1996.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


TXT (ASCII Text)

Full Name
TXT (ASCII Text)
Format ID
IG_FORMAT_TXT = 41
File Extension(s)
*.txt
Data Type
Raster Image
Data Encoding
ASCII
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, MAC

ImageGear Supported versions:

N/A

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading

ImageGear Read Support:

  • IG_COMPRESSION_ASCII - Indexed RGB: 1 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
XDPI
UINT
200
Horizontal resolution of image.
YDPI
UINT
200
Vertical resolution of image
MARGINS_LEFT
LONG
1000
Left text margin on page, expressed as thousandths of an inch.
MARGINS_TOP
LONG
1000 (750 - for Unix)
Top text margin on page, expressed as thousandths of an inch.
MARGINS_RIGHT
LONG
1000
Right text margin on page, expressed as thousandths of an inch.
MARGINS_BOTTOM
LONG
1000 (750 - for Unix)
Bottom text margin on page, expressed as thousandths of an inch.
PAGE_WIDTH
DIMENSION
8500
Width of resulting page, expressed as thousandths of an inch.
PAGE_HEIGHT
DIMENSION
11000
Height of resulting page, expressed as thousandths of an inch
POINT_SIZE
INT
10 (-1 - for Unix)
Font metric: If 0 then lines per page and character per line is used, else - specify font size.
WEIGHT
UINT
FALSE (0)
TRUE,
FALSE
Font metric: if TRUE use bold font.
ITALIC
BOOL
FALSE
TRUE,
FALSE
Font metric: if TRUE use italic font.
TAB_STOP
UINT
3 (4 - for Unix)
The number of characters per tab.
TYPE_FACE
LP | CHAR
"\x00" ("courier" - for Unix)
Font metric:typeface name of the font, If empty string then default font used "Courier new".
LINES_PER_PAGE
UINT
0 (60 - for Unix)
Number of line per page.
CHAR_PER_LINE
UINT
0 (80 - for Unix)
Number of characters per line.
COMPATIBILITY_MODE
BOOL
FALSE (TRUE - for Unix)
TRUE,
FALSE
If TRUE use old algorithm, otherwise use ImageGear Algorithm

Comments:

This is a widely used format for storing plain text files. ASCII data can also be used to give vector data instructions, but this is not supported by ImageGear.

The current, commonly used version of ASCII uses a 7-bit format and is known as "Full" or "Extended ASCII". The 128 (27) different data values include printable and non-printable values. The non-printable values are represented by the first 32 (0-31) values of ASCII, and are called "control values". They are used to communicate with screens or printers for placement of the characters. These control values represent tabs, line feeds, spaces, etc. Combinations of these values create "escape sequences" whose values are device-dependent upon implementation. To keep an ASCII file completely device-independent, a file usually does not contain any control values other than tab, line feed, and carriage return.

What makes a TXT file different from many bitmap formats is the byte order. A file is written in the natural order that it appears when output. There is no division into bit planes, or reverse order of bits and bytes. The eighth bit of each byte is normally set to zero. In older versions of TXT files, this was often used as a parity bit.

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats, 2nd ed. Windcrest /McGraw-Hill, 1995.


U3D

Full Name
U3D (Universal 3D)
Format ID
IG_FORMAT_U3D = 79
File Extension(s)
*.u3d
Data Type
Vector image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, .NET, .NET64

NOTE: To support U3D format, ImageGear U3D Component should be attached to Core ImageGear.

ImageGear Supported Versions:

  • U3D v. 1.0

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - auto-detection
  • IG_FLTR_PAGEREADSUPPORT - single-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE - Universal 3D vector data

ImageGear Write Support:

  • IG_COMPRESSION_NONE - Universal 3D vector data

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
BACKCOLOR
Long
0
Any positive value
This parameter is used to set background color. If BACKCOLOR=0, then the black background color is set, otherwise the white background color is set.
WIDTH
Long
512
Any positive value
Defines the DIB width of the loaded image. The DIB height is calculated using the file's scale factors.

Comments

U3D file format, short for "Universal 3D", is a universal vector standard for storing three-dimensional data of all kinds to facilitate data exchange. The specification for this format is the document ECMA-363: Universal 3D File Format. The latest edition of this specification is available at the ECMA web site:

http://www.ecma-international.org/

The U3D format is natively supported by PDF, and 3D objects in U3D format can be inserted into PDF document files and interactively visualized by PDF viewers.


WBMP

Full Name
WBMP (Wireless Bit-Map)
Format ID
IG_FORMAT_WBMP = 66
File Extension(s)
*.wbmp,
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 1.1

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE - Indexed RGB: 1 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE - Indexed RGB: 1 bpp

ImageGear Filter Control Parameters:

No

Comments

The WBMP (Wireless Bit-Map) read/write format is optimized to support mobile computing devices that use the Wireless Application Protocol (WAP).

File contains small header with image parameters and array or pixels in uncompressed form.

References used:

WAP WAE Specification Version, 24 May 1999.


WMF

Full Name
WMF (Windows Metafile Format)
Format ID
IG_FORMAT_WMF = 44
File Extension(s)
*.wmf,
Data Type
Metafile Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix (read raster portion only). MAC (read raster portion only)

ImageGear Supported versions:

  • Version 1 Metafiles prior to Windows 3.0
  • Version 2 Metafiles for Windows 3.0 and later

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 4, 8 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp
  • IG_COMPRESSION_RLE:
    • Indexed RGB: 4, 8 bpp

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
UPSIDE_DOWN
BOOL
TRUE,
FALSE
If TRUE then images will be saved upside-down
TYPE
UINT
BMP_TYPE_BMC,
BMP_TYPE_BMI,
BMP_TYPE_BMI2
Type of the BMP file to be saved as part of WMF.
COMPRESSION
DWORD
BMP_COMP_RLE4,
BMP_COMP_RLE8,
BMP_COMP_RGB
Type of compression of BMP file.
TRUE_METAFILE
BOOL
TRUE (for Windows)
FALSE(otherwise)
TRUE,
FALSE
TRUE means executing of metafile commands (playing of metafile). Can be TRUE only for Windows.
RESOLUTION_X
DWORD
NULL
X resolution. 0 for actual resolution
RESOLUTION_Y
DWORD
NULL
Y resolution. 0 for actual resolution
DEPTH
DWORD
NULL
Bit Depth. 0 for actual depth

NOTE: If the TRUE_METAFILE parameter tis set to TRUE, the image will be opened as an RGB DIB for use with the GDI functions, which produce the image output. This causes the image to look like it is 24-bit per pixel, and 1024x1024 in dimensions. If the TRUE_METAFILE parameter is set to FALSE, then ImageGear will open the image according to its correct bit depth and dimensions.

Comments

A Microsoft Windows Metafile holds vector and bitmap graphics data in memory or on disk. Although it was developed for use with Windows applications, it is now used by many non-Windows-based applications, allowing data to be transferred to and from Windows applications. Due to the great success of the Microsoft Windows interface, the Windows Metafile format is found in nearly all graphical applications. Metafiles use much less space and are more device-independent than bitmaps.

See also the section Support for Metafile Formats.

The Windows metafile begins with a short header and is followed by one or more records of data. The header describes the record data. A "placement" header can also be added before the file header; it contains information needed to move the metafile between applications. Each record corresponds to a binary-encoded Windows graphics device interface (GDI) call, and contains the size of the record, the unique function number for the GDI and an array of parameters. The GDI is used by Windows to perform all image output. When the metafile is "played", (this Microsoft term is a companion term to the Windows function named "PlayMetaFile"), each record makes a call to the appropriate function call for displaying each object in the image. The last record in the file contains a function number of zero to indicate that the end of the record data has been reached.

References used:

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.

Petzold, Charles. Programming Windows: The Microsoft Guide to writing applications for Windows 3. Redmond, WA: Microsoft Press, 1990.


WPG

Full Name
WPG (WordPerfect Graphics Metafile)
Format ID
IG_FORMAT_WPG = 42
File Extension(s)
*.wpg
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • WPG for WP 5.1 and up can store bitmap and vector graphics in the same file.
  • WPG for WP 5.0 and prior can store only bitmap or vector graphic, but not both in same file.

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading

ImageGear Read Support:

  • IG_COMPRESSION_RLE - Indexed RGB: 1, 4, 8 bpp

ImageGear Write Support:

No

ImageGear Filter Control Parameters:

No

Comments

This format was created specifically for use with WordPerfect software products. WPG files for WordPerfect versions 5.1 and up can store both bitmap and vector image data in the same file.

The WordPerfect Graphics Metafile contains a short header or "prefix" (as WordPerfect Corporation referred to it). The header is followed by a record area, that is a sequence of objects and their attributes. The first record is called the "Start WPG Data" record and contains information on the size of the images and the version number of the .WPG file. The next record is usually a color map, unless the image is black and white. The next record is a bitmap record. If there are multiple images, there is a bitmap record for each image. The last record in a .WPG file contains a NULL body to signify the end of the file. These files may also contain Encapsulated PostScript (EPS) data.

References used

Murray, James D. "Graphic Image Format FAQ 3-4". James D. Murray, 1994-1996.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


XBM

Full Name
XBM (X BitMap)
Format ID
IG_FORMAT_XBM = 43
File Extension(s)
*.xbm
Data Type
Raster Image
Data Encoding
ASCII
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 11, data stored as 1-byte character, 1986
  • Version 10, data stored as 2-byte "short" integers

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_ASCII - Indexed RGB: 1 bpp

ImageGear Write Support:

  • IG_COMPRESSION_ASCII - Indexed RGB: 1 bpp

ImageGear Filter Control Parameters:

No

Comments

The XBM format is intended as a convenient storage method for small monochrome images, for example, cursor and icon bitmaps. It can, however, support images of any size, but since it supports no native compression scheme, an exterior compression program is used when compacting is desired. The bitmap data is stored as ASCII data with C language syntax, making the file easy to insert into C program code. XBM data can be stored as a standalone graphics file, or within a C program header file. See also XPM, XWD.

XBM files begin with two to four #define statements in substitution of a header. These identify the image width and height, and optionally, the coordinates of a Hotspot, if one exists.

The image data follows and is more free-form than the other bitmap data formats described in this chapter. It consists of one variable-length static array of pixel values. Each value (in version 11) consists of one byte of data, and therefore represents 8 1-bit pixels. The first pixel (0,0) is represented by the high bit of the first byte in the array. Due to this one-array format, there is nothing in the data that explicitly marks the rows of the bitmap.

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


XPM

Full Name
XPM (X PixMap)
Format ID
IG_FORMAT_XPM = 45
File Extension(s)
*.xpm
Data Type
Raster Image
Data Encoding
ASCII (in C language syntax)
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 3.2g, April 1993

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp

ImageGear Filter Control Parameters:

No

Comments

The XPM format was created as an extended version of the XBM file format. It is the informal standard for storing X Window pixmap data, including Hotspot information for cursor bitmaps. The image data is stored in ASCII text characters that are formatted as a standard C array of character strings. It is intended to be human-readable, is readily inserted into C/C++ program code, and can contain any number of comment lines. It therefore does not support a native compression scheme. If compacting is desired, an external compression program may be used. See also XBM, XWD.

All XPM files begin with a C language comment line containing "XPM". Following this are three sections of data: values, colors, and pixels, and an optional fourth section: extensions. The "values" section is the equivalent of the header structure typically found in a graphics file. It gives the size of the pixmap, as well as its number of colors, characters per pixel, the location of the Hotspot (if any), and an indicator of whether the file contains an extension section. Each section is set off with a comment-line title.

The colors section contains codes for the pixmap data characters. All pixels that make up the pixmap are assigned to one or more ASCII characters and one or more colors. (e.g. the character "X" may be assigned to the color red). There are several different conventions for identifying a color. If the string "None" appears as the color to be applied to a specific character, the character(s) symbolizes a transparent pixel.

The "pixels" section contains the bitmap data that appear as an array of character strings, where one row of bitmap data is represented by one array element. Each row is a group of characters set off by quotation marks. Each character is defined in the previous "colors" section.

If indicated by the values section, an extension section appears. It can contain one or more subsections that conform to one of two syntactical formats. An "XPMENDEXT" marker is always used to mark the end of the extension section.

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


XPS

Full Name
XPS (XML Paper Specification)
Format ID
IG_FORMAT_XPS = 80
File Extension(s)
*.xps
Data Type
Vector image
Data Encoding
Binary
IG Multipage Support
Yes
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, .NET, .NET64

NOTE: To support XPS format, ImageGear XPS Component should be attached to Core ImageGear.

ImageGear Supported Versions:

  • Version 1.0

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_MPAGEREADPSUPPORT - multi-page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing
  • IG_FLTR_MPAGEWRITEPSUPPORT - multipage file writing
  • IG_FLTR_MPDATASUPPORT - faster multi-page access by storing private format data (used only with IG_mpi_... and IG_mpf_... API)

ImageGear Read Support:

  • IG_COMPRESSION_NONE - XPS data

ImageGear Write Support:

  • Vector
    • IG_COMPRESSION_NONE - XPS data
  • Raster
    • IG_COMPRESSION_NONE
      • Grayscale: 1, 8, 16 bpp;
      • RGB: 24, 48 bpp;
      • RGBA: 32, 64 bpp;
      • RGBPA: 32, 64 bpp;
      • CMYK: 32 bpp;

ImageGear Filter Control Parameters:

Filter Control Parameter
Type
Default Value
Available Values
Description
RESOLUTION_X
AM_TID_UINT
96
Any positive integer
This parameter specifies the horizontal resolution in dots-per-inch during the XPS document conversion into a raster image. The greater this value, the higher the quality of the raster image you get after rasterization. The DIB of the output raster image has this value as an X resolution.
RESOLUTION_Y
AM_TID_UINT
96
Any positive integer
This parameter specifies the vertical resolution in dots-per-inch during the XPS document conversion into a raster image. The greater this value, the higher the quality of the raster image you get after rasterization. The DIB of the output raster image has this value as an Y resolution.

Non-Image Data Structure:

XML Paper Specification file format has different non-image data that can be stored in a package as XML or resources. The XML Paper Specification metadata design allows reading and writing the following non-image data:

Tag Name
Tag ID
Description
Category
IGMDTAG_ID_XPS_CATEGORY
The category of the content that is contained in the file.
ContentStatus
IGMDTAG_ID_XPS_CONTENTSTATUS
Example ContentStatus values include "Draft", "Reviewed", and "Final".
ContentType
IGMDTAG_ID_XPS_CONTENTTYPE
Example ContentType values include "Whitepaper", "Security Bulletin", and "Exam".
Created
IGMDTAG_ID_XPS_CREATED
The date and time the file was initially created.
Creator
IGMDTAG_ID_XPS_CREATOR
The individual or entity that created the file and its content.
Description
IGMDTAG_ID_XPS_DESCRIPTION
The Description may include but is not limited to: an abstract, table of contents, reference to a graphical representation of content, or a free-text account of the content.
Identifier
IGMDTAG_ID_XPS_IDENTIFIER
A value that unambiguously identifies the file and its content.
Keywords
IGMDTAG_ID_XPS_KEYWORDS
A delimited set of keywords to support searching and indexing the Package and content.The Keywords property typically contains a list of terms that are not available elsewhere in file metadata.
Language
IGMDTAG_ID_XPS_LANGUAGE
A value that identifies the file content language.
LastModifiedBy
IGMDTAG_ID_XPS_LASTMODIFIEDBY
The user who last modified the file content.
LastPrinted
IGMDTAG_ID_XPS_LASTPRINTED
The date and time the file content was last printed.
Modified
IGMDTAG_ID_XPS_MODIFIED
The date and time the file was last changed.
Revision
IGMDTAG_ID_XPS_REVISION
The revision number of the file. The Revision property indicates the number of changed saves or revisions. The application is responsible for updating the Revision property value after each revision.
Subject
IGMDTAG_ID_XPS_SUBJECT
The topic of the file content.
Title
IGMDTAG_ID_XPS_TITLE
The name given to the file and its content.
Version
IGMDTAG_ID_XPS_VERSION
The version number of the file.

Comments

The XPS Document format represents a set of related pages with a fixed layout, which are organized as one or more documents, in the traditional meaning of the word. A file that implements this format includes everything necessary to fully render those documents on a display device or physical medium (for example, paper). This includes all resources such as fonts and images that might be required to render individual page markings.

In addition, the format includes optional components that build on the minimal set of components required to render a set of pages. This includes the ability to specify print job control instructions, to organize the minimal page markings into larger semantic blocks such as paragraphs, and to physically rearrange the contents of the format for easy consumption in a streaming manner, among others.

The XPS format supports HD Photo images natively for raster images.

The XPS format conception is similar to the Adobe PDF. It is a fixed-layout document format designed to preserve document fidelity, so that documents look the same and as they are intended on any device. While Adobe PDF is based on PostScript the XPS format is based on XML. Adobe PDF however includes some dynamic capabilities not supported by the XPS format, and cannot be fully replaced by XPS.

Finally, the XPS Document format implements the common package features specified by the Open Packaging Conventions specification that support digital signatures and core properties. An XPS file is a ZIP archive conforming to the Open Packaging Convention.

The XPS format intended as the replacement for the EMF print spooler format. The format serves as the page description language for printers. For printers supporting XPS, this eliminates an intermediate conversion to a printer-specific language, increasing the reliability and fidelity of the printed output.

References Used

  • XML Paper Specification v. 1.0:

http://www.microsoft.com/whdc/xps/xpsspec.mspx


XWD

Full Name
XWD (X Window Dump)
Format ID
IG_FORMAT_XWD = 47
File Extension(s)
*.xwd, *.wd (for Unix)
Data Type
Raster Image
Data Encoding
Binary
IG Multipage Support
No
IG Alpha Channel Support
No
IG Platforms Support
WIN32, WIN64, Unix, Unix64, .NET, .NET64, MAC

ImageGear Supported versions:

  • Version 7 for X11, June 1987 (X10 grayscale and palette only)

ImageGear Supported Features:

  • IG_FLTR_DETECTSUPPORT - autodetection
  • IG_FLTR_PAGEREADSUPPORT - single page file reading
  • IG_FLTR_PAGEINSERTSUPPORT - single-page file writing

ImageGear Read Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp

ImageGear Write Support:

  • IG_COMPRESSION_NONE:
    • Indexed RGB: 1, 4, 8 bpp;
    • RGB: 24 bpp

ImageGear Filter Control Parameters:

No

Comments

An XWD file can contain a representation of the window, the background, or the entire screen display. It has been designed to be a very versatile, device-independent format. See also XBM, XPM.

The general structure of the XWD graphics format begins with a long header, that is sometimes followed by a palette and contains the bitmap data. The header contains integer data and stores the header size, the XWD version, the size and location of the bitmap, the window size, location, and border width. A ByteOrder field indicates whether the bytes are stored in big-endian or little-endian order.

In the interest of making this format device-independent, the XWD supports six "visual classes" and three image formats. The visual class code is stored in the visual_class field of the header, and represents the following categories:

    • Static Gray, for most monochrome screens and using a fixed device-dependent color map;
    • GrayScale, for monochrome screens and using a software-supplied palette;
    • StaticColor, which uses a fixed device-dependent palette;
    • Pseudocolor, which uses a software-supplied palette and is intended for VGA screens;
    • TrueColor, with fixed device-dependent mapping of RGB values to screen colors;
    • DirectColor, with software-supplied mapping of RGB values to screen values.

The image-format categories, whose codes are stored in the pixmap_format field of the header, are called XYBitmap (1-bit), XYPixmap (single plane), and ZPixmap (two or more planes).

Where the value of pixmap_format indicates GrayScale, PseudoColor or DirectColor, a palette follows the header.

The image data is the last structure in the file. The bytes are stored in rows with groupings called "units", whose lengths are determined by the bitmap_unit field of the header.

If the pixmap_format field is 1, indicating an XYPixmap, there are multiple representations of the bitmap data, one for each color plane, where the first bitmap represents the highest bit of the data; the second bitmap represents the second-highest bit, and so on. An image with a bit depth of 4 yields a file with four bitmaps.

References used

Brown, C. Wayne, and Barry J. Shepherd. Graphics File Formats: Reference and Guide. Greenwich, CT.: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats. Sebastopol, CA: O'Reilly & Associates, Inc., 1994.


ImageGear Alpha Channel Support

Alpha channel is an additional image channel that specifies transparency (or opacity) of each pixel in the image. ImageGear provides alpha channel support for the following file format filters:

Format
Support
Adobe PSB
Supports single Alpha channel for Read only. Supports aditional Alpha channels as ImageGear Extra channels for Read only.
Adobe PSD
Supports single Alpha channel for Read only. Supports aditional Alpha channels as ImageGear Extra channels for Read only.
CUR
Supports single 8-bit alpha channel for read/write. Supports single 1-bit alpha channel for read only.
EXIF-JPEG
Supports single Alpha channel for Read/write.
EXIF-TIFF
Supports single Alpha channel for read only. Supports additional Alpha channels as ImageGear Extra channels for read only.The following compressions are supported with alpha channel:
  • Uncompressed
  • Packed Bits
  • LZW
  • Deflate
FlashPix
Supports single Alpha channel for read only. Converts RGB + Alpha to RGB during loading.
ICO
Supports single 8-bit alpha channel for read/write. Supports single 1-bit alpha channel for read only.
JPEG
Supports single Alpha channel for Read/write.
JPEG2000
Supports single Alpha channel for read/write, for Grayscale and RGB images.
JPX
Supports single Alpha channel for read/write, for Grayscale and RGB images. Supports additional Alpha channels as ImageGear Extra channels for read/write.
MAC PICT
Supports single alpha channel for read only. Alpha channel have to be 8-bit image.
Motion JPEG2000
Supports single Alpha channel for read only, for Grayscale and RGB images.
PNG
Suports single Alpha channel for read/write.
RAW
Supports single Alpha channel in uncompressed images for read only.
SGI
Supports single alpha channel for read and write.
TGA
Supports single alpha channel for read and write.
TIFF
Supports single Alpha channel for read and write. Supports additional Alpha channels as ImageGear Extra channels for read and write.The following compressions are supported with alpha channel:
  • Uncompressed
  • Packed Bits
  • LZW
  • Deflate


ImageGear Transparency Support

Transparency allows you to specify a palette index or a color to be transparent. When the image is displayed, all pixels having this index (color) show background rather than the pixel's color.

Transparency requires very little storage space in the file - only a few bytes. However, the pixels can't be semi-transparent; also, transparent color occupies a palette entry or a color, which reduces the possible range of colors for the image. Alpha channel requires significantly more storage space in the file, but it does not have the limitations listed above.

ImageGear provides transparency support for the following file format filters:

Format
Support
GIF
Supports transparency for Read and Write.
PNG
Supports transparency for Read only.
XPM
Supports transparency for Read and Write.


ImageGear Supported Digital Camera RAW Formats

Camera manufacturers do not publish specifications on their raw formats. ImageGear attempts to reconstruct color images correctly where it is possible. For some cameras, however, not all of the color balance data is available. The application may need to apply additional processing to such images. This table lists the level of support that ImageGear provides for particular cameras.

The table uses the following notation:

  • S1 - Not supported in this version
  • S2 - ImageGear loads non-demosaiced image, basic metadata, and exif metadata if available. Reconstructed image can have incorrect colors.
  • S3 - Same as S2 plus correct white balance, black level tags. Display can be slightly different from native viewer, due to lack of info on camera colorspace.
  • S4 - Displays with colors very close to native viewer
  • S5 - Displays with colors and contrast very close to native viewer

    • Manufacturer
    Model
    Level of Support
    Canon
    EOS 10D
    S5
    Canon
    EOS 1D
    S2
    Canon
    EOS 1D Mark II
    S5
    Canon
    EOS 1D Mark II N
    S5
    Canon
    EOS 1D Mark III
    S5
    Canon
    EOS 1Ds
    S2
    Canon
    EOS 1Ds Mark II
    S5
    Canon
    EOS 1Ds Mark III
    S5
    Canon
    EOS 20D
    S3
    Canon
    EOS 20Da
    S3
    Canon
    EOS 300D
    S5
    Canon
    EOS 30D
    S4
    Canon
    EOS 350D
    S5
    Canon
    EOS 400D
    S4
    Canon
    EOS 40D
    S5
    Canon
    EOS 5D
    S5
    Canon
    EOS D30
    S2
    Canon
    EOS D60
    S5
    Canon
    EOS Digital Rebel
    S5
    Canon
    EOS Digital Rebel XT
    S5
    Canon
    EOS Digital Rebel Xti
    S4
    Canon
    EOS Kiss Digital
    S5
    Canon
    EOS Kiss N Digital
    S5
    Canon
    EOS Kiss X Digital
    S4
    Canon
    PowerShot 600
    S2
    Canon
    PowerShot A4601
    S2
    Canon
    PowerShot A5
    S2
    Canon
    PowerShot A5 Zoom
    S5
    Canon
    PowerShot A50
    S2
    Canon
    PowerShot A6101
    S2
    Canon
    PowerShot A6201
    S2
    Canon
    PowerShot A6301
    S2
    Canon
    PowerShot A6401
    S2
    Canon
    PowerShot A7101
    S2
    Canon
    PowerShot A7201
    S2
    Canon
    PowerShot G1
    S5
    Canon
    PowerShot G2
    S5
    Canon
    PowerShot G3
    S3
    Canon
    PowerShot G5
    S2
    Canon
    PowerShot G6
    S2
    Canon
    PowerShot G71
    S2
    Canon
    PowerShot G9
    S5
    Canon
    PowerShot Pro1
    S5
    Canon
    PowerShot Pro70
    S2
    Canon
    PowerShot Pro90 IS
    S2
    Canon
    PowerShot S2 IS1
    S2
    Canon
    PowerShot S3 IS1
    S2
    Canon
    PowerShot S30
    S2
    Canon
    PowerShot S40
    S5
    Canon
    PowerShot S45
    S2
    Canon
    PowerShot S5 IS1
    S2
    Canon
    PowerShot S50
    S4
    Canon
    PowerShot S60
    S2
    Canon
    PowerShot S70
    S2
    Casio
    Exlim Pro 5051
    S2
    Casio
    Exlim Pro 6001
    S2
    Casio
    Exlim Pro 7001
    S2
    Casio
    EX-S1001
    S2
    Casio
    EX-Z501
    S2
    Casio
    EX-Z551
    S2
    Casio
    QV-R511
    S2
    Fujifilm
    FinePix E550
    S5
    Fujifilm
    FinePix E900
    S5
    Fujifilm
    FinePix F700
    S2
    Fujifilm
    FinePix F710
    S2
    Fujifilm
    FinePix S2 Pro
    S2
    Fujifilm
    FinePix S20 Pro
    S2
    Fujifilm
    FinePix S3 Pro
    S5
    Fujifilm
    FinePix S5 Pro
    S5
    Fujifilm
    FinePix S5000 Z
    S2
    Fujifilm
    FinePix S5100
    S5
    Fujifilm
    FinePix S5200
    S5
    Fujifilm
    FinePix S5500
    S5
    Fujifilm
    FinePix S5600
    S5
    Fujifilm
    FinePix S6000fd
    S5
    Fujifilm
    FinePix S6500fd
    S5
    Fujifilm
    FinePix S7000 Z
    S2
    Fujifilm
    FinePix S9000
    S5
    Fujifilm
    FinePix S9100
    S5
    Fujifilm
    FinePix S9500
    S5
    Fujifilm
    FinePix S9600
    S5
    Kodak
    DCS 720x
    S2
    Kodak
    DCS 760C
    S4
    Kodak
    DCS 760M (monochrome)
    S2
    Kodak
    DCS PRO 14n (13.5 MegaPixel)
    S2
    Kodak
    DCS PRO 14n (3.2 MegaPixel)
    S2
    Kodak
    DCS PRO 14n (6 MegaPixel)
    S2
    Kodak
    DCS PRO 14n (YUV)
    S2
    Kodak
    DCS PRO 14nx
    S2
    Kodak
    DCS Pro SLR/c
    S2
    Kodak
    DCS Pro SLR/c (YUV)
    S2
    Kodak
    DCS Pro SLR/n (13.5 MegaPixel)
    S2
    Kodak
    DCS Pro SLR/n (3.2 MegaPixel)
    S2
    Kodak
    DCS Pro SLR/n (6 MegaPixel)
    S2
    Kodak
    DCS Pro SLR/n (YUV)
    S2
    Kodak
    EasyShare P850
    S2
    Kodak
    EasyShare P880
    S2
    Konica Minolta
    Alpha Sweet
    S5
    Konica Minolta
    DiMAGE 5
    S5
    Konica Minolta
    DiMAGE 7
    S5
    Konica Minolta
    DiMAGE 7Hi
    S5
    Konica Minolta
    DiMAGE 7i
    S4
    Konica Minolta
    DiMAGE A1
    S5
    Konica Minolta
    DiMAGE A2
    S5
    Konica Minolta
    DYNAX/MAXXUM 5D
    S5
    Konica Minolta
    DYNAX/MAXXUM/ALPHA 7D
    S5
    Leaf
    Aptus 22
    S5
    Leaf
    Aptus 54S
    S5
    Leaf
    Aptus 65
    S5
    Leaf
    Aptus 75
    S5
    Leaf
    Aptus 75S
    S5
    Leaf
    CMost
    S5
    Leaf
    Valeo 11
    S5
    Leaf
    Valeo 17
    S5
    Leaf
    Valeo 22
    S5
    Leaf
    Valeo 6
    S5
    Leica
    Digilux 2
    S5
    Leica
    Digilux 3
    S5
    Leica
    D-LUX2
    S5
    Leica
    D-LUX3
    S5
    Leica
    V-LUX1
    S5
    Mamiya
    ZD
    S2
    Nikon
    Coolpix 5000
    S2
    Nikon
    Coolpix 5400
    S5
    Nikon
    Coolpix 5700
    S5
    Nikon
    Coolpix 8400
    S5
    Nikon
    Coolpix 8700
    S5
    Nikon
    Coolpix 8800
    S5
    Nikon
    D1
    S5
    Nikon
    D100
    S5
    Nikon
    D1H
    S5
    Nikon
    D1X
    S5
    Nikon
    D200
    S5
    Nikon
    D2H
    S5
    Nikon
    D2Hs
    S5
    Nikon
    D2X
    S5
    Nikon
    D2Xs
    S5
    Nikon
    D3
    S5
    Nikon
    D300
    S5
    Nikon
    D40
    S5
    Nikon
    D40s
    S5
    Nikon
    D40x
    S5
    Nikon
    D50
    S5
    Nikon
    D50s
    S5
    Nikon
    D60
    S5
    Nikon
    D70
    S5
    Nikon
    D70s
    S5
    Nikon
    D80
    S5
    Olympus
    C-5050 Zoom
    S5
    Olympus
    C-5060 Zoom
    S5
    Olympus
    C-7000 Zoom
    S5
    Olympus
    C-7070 Zoom
    S5
    Olympus
    C-70Z
    S5
    Olympus
    C-8080
    S5
    Olympus
    E-1
    S5
    Olympus
    E-10
    S5
    Olympus
    E-20
    S5
    Olympus
    E-3
    S5
    Olympus
    E-300
    S5
    Olympus
    E-330
    S5
    Olympus
    E-400
    S5
    Olympus
    E-410
    S4
    Olympus
    E-500
    S5
    Olympus
    E-510
    S4
    Olympus
    SP350
    S5
    Olympus
    SP500UZ
    S5
    Olympus
    SP510UZ
    S5
    Olympus
    SP550UZ
    S5
    Olympus
    SP560UZ
    S5
    Panasonic
    DMC-FZ18
    S5
    Panasonic
    DMC-FZ30
    S5
    Panasonic
    DMC-FZ50
    S5
    Panasonic
    DMC-FZ8
    S5
    Panasonic
    DMC-L1
    S5
    Panasonic
    DMC-L10
    S5
    Panasonic
    DMC-LC1
    S5
    Panasonic
    DMC-LX1
    S5
    Panasonic
    DMC-LX2
    S5
    Pentax
    *ist D
    S5
    Pentax
    *ist DL
    S5
    Pentax
    *ist DL2
    S4
    Pentax
    *ist DS
    S5
    Pentax
    *ist DS2
    S5
    Pentax
    K100D
    S4
    Pentax
    K100D Super
    S5
    Pentax
    K10D
    S5
    Pentax
    K110D
    S4
    Samsung
    GX-10
    S5
    Samsung
    GX-1S
    S5
    Sony
    DSC-F828
    S2
    Sony
    DSC-R1
    S3
    Sony
    DSC-V3
    S2
    Sony
    DSLR-A100
    S5
    Sony
    DSLR-A700
    S2

1) Headerless Digital Camera RAW file. Detection is disabled by default.


AccuSoft Image Guarantee

ImageGear is guaranteed to read all valid raster images for supported formats. If for some reason, you cannot read an image with our library, three things may have occurred:

  1. The image is corrupted.
  2. The image is improperly coded.
  3. ImageGear is not reading this image properly.
See Also:

Identifying the Problem.


Identifying the Problem

In the rare instance that ImageGear cannot read an image, please try the following:

  1. Try to read the image with another software package. Be sure to use a different package from the one that created the image. Some products that claim to produce a particular graphics file format do not adhere completely to the format specifications. If you can successfully read the image with a different product, you can feel confident that it is a valid image.
  2. If you can read the file with a package other than the one that created the image, please refer to the section Sending the Image to Accusoft for the instructions how to send us your image.

Check the error count that is returned by the ImageGear function (AT_ERRCOUNT). If it is greater than 0, use the IG_error_get () function to get the ImageGear error codes. (AT_ERRCODE). For more information on doing this, you can consult either Core Component API Function Reference Chapter or Detecting and Handling Errors.

NOTE: ImageGear contains filters that are designed to decompress an image even if it is corrupted. Some images may be too badly corrupted for the filters to use. If this is the case, you will receive the error message IGE_CORRUPTED_FILE defined in GEARERRS.H.


Sending the Image to Accusoft

To send your image to AccuSoft, please log a support ticket via our web-ticketing system, and attach the file once the ticket is created, so that our Customer Support Team can address your problem as soon as possible.

See Also:

AccuSoft Customer Support

Software Support and Maintenance Policy


Appendix: Function Error Return Codes

This Appendix represents ImageGear error codes including their numerical numbers and short descriptions. All error codes are listed in numerical order and divided on the groups that are specific for ImageGear components functionality. Please refere to gearerrs.h and gearestr.h files for additional information about ImageGear error and warning codes.

JPEG2000 Component Error Codes

IGE_JPEG2000_KAKADU_ERROR
-9700
Error has been reported from Kakadu JPEG2000 library

Recognition Component Error Codes

IGE_REC_SCANSOFT_ERROR
-9600
Error has been reported from ScanSoft recognition library

ART Component Error Codes

IGE_ART_WANG_INCOMPATIBLE_FILE
-9500
Internal format of loaded annotation file is not compatible with Wang.

NRA Error Codes

IGE_INVALID_PARAMETER_FOR_PROCESSING_WITH_REGION
-9001
Operation can not be done using region.
IGE_INVALID_REGION_DATA
-9000
Invalid region

OS2 Error Codes

IGE_UNREGISTERED_HAB
-8000
HAB is not registered

VBX/OCX Level Error Codes

IGE_GUIWINDOW_TYPE_INVALID
-7020
GUIWindow type invalid
IGE_ROTATE_ENUMERATED_VALUES_NOT_USED
-7010
The enumerated values for rotate were not used
IGE_VBX_INVALID_FUNCTION_NUM
-7000
Invalid VBX function number

GUI Function Error Codes

IGE_GUI_GET_DEVICE_RECT_FAILED
-6522
Failed to retrieve device rectangle from SourceView's page display.
IGE_GUI_DESTINATION_VIEW_UNAVAILABLE
-6521
DestinationView property must be setup in stationary mode before starting mouse tracking.
IGE_GUI_SOURCE_VIEW_UNAVAILABLE
-6520
SourceView property must be setup before starting mouse tracking.
IGE_GUI_WINDOWING_FAILED
-6519
Failed to attach to the source view control window.
IGE_GUI_SLIDER_SETUP_FAILED
-6518
Failed to setup magnifier's on-source sliding area.
IGE_GUI_INTERNAL_ERROR
-6517
Internal GUI error.
IGE_GUI_UNKNOWN_FILE_FORMAT
-6516
Unknown file format
IGE_GUI_GET_HWND
-6515
Could not retrieve the underlying HWND for this object.
IGE_GUI_GET_DLG_CTL_FAILED
-6514
Could not retrieve the dialog control object.
IGE_GUI_PAGE_VIEW_UPDATE_FAILED
-6513
Could not update the PageView Control.
IGE_GUI_PAGE_VIEW_ENABLE_FAILED
-6512
Could not enable the PageView Control.
IGE_GUI_DISPLAY_ZOOM_CHANGE_FAILED
-6511
Could not modify the properties of the Display Zoom object for this image display.
IGE_GUI_DISPLAY_ZOOM_SET_OBJ_FAILED
-6510
Could not set the Display Zoom object for this image display.
IGE_GUI_DISPLAY_ZOOM_GET_OBJ_FAILED
-6509
Could not retrieve the Display Zoom object for this image display.
IGE_GUI_LAYOUT_CHANGE_FAILED
-6508
Could not modify the properties of the Display Layout object for this image display.
IGE_GUI_LAYOUT_GET_OBJ_FAILED
-6507
Could not retrieve the DIsplay Layout object for this image display.
IGE_GUI_PAGE_DISPLAY_SET_OBJ_FAILED
-6506
Could not set the PageDisplay object for this image's PageView Control.
IGE_GUI_PAGE_DISPLAY_CREATE_OBJ_FAILED
-6505
The CreatePageDIsplay() call failed.
IGE_GUI_NO_PAGE
-6504
Invalid IGPage object.
IGE_GUI_NO_PAGE_DISPLAY
-6503
Invalid IGPageDisplay object.
IGE_GUI_NO_PROCESSING_CTL
-6502
The control is not associated with a valid IGProcessingCtl control.
IGE_GUI_NO_DISPLAY_CTL
-6501
The control is not associated with a valid IGDisplayCtl control.
IGE_GUI_NO_FORMATS_CTL
-6500
The control is not associated with a valid IGFormatsCtl control.
IGE_UNREGISTER_CLASS_FAILED
-6040
Microsoft Windows function: UnregisterClass() failed.
IGE_INVALID_WINDOW
-6030
An invalid window handle was passed as one of the parameters to the function.
IGE_WINDOW_NOT_ASSOCATED
-6020
An attempt was made to disassociate a window that was never associated.
IGE_CREATE_WINDOW_FAILED
-6010
Microsoft Windows function: CreateWindow() failed.
IGE_REGISTER_CLASS_FAILED
-6000
Microsoft Windows function: RegisterClass() failed.

PDF/PostScript Component Error Codes

PDF Objects

IGE_PDF_STREAM_INVALID
-5807
Invalid stream object
IGE_PDE_OBJECT_INVALID
-5806
Invalid PDE object
IGE_PDF_COLORSPACE_INVALID
-5805
Invalid color space object
IGE_PDF_ELEMENT_INVALID
-5804
Invalid element
IGE_PDF_CONTENT_CANT_SET
-5803
Cannot set content
IGE_PDF_CONTENT_INVALID
-5802
Invalid content object
IGE_PDF_OBJECT_INVALID
-5801
Invalid PDF object

PDF Page

IGE_PDF_PAGE_CANT_DELETE
-5706
Cannot delete page.
IGE_PDF_PAGE_CANT_INSERT
-5705
Cannot insert page.
IGE_PDF_PAGE_CANT_SAVE
-5704
Cannot save page.
IGE_PDF_PAGE_CANT_OPEN
-5703
Cannot open page.
IGE_PDF_PAGE_CANT_CREATE
-5702
Cannot create page.
IGE_PDF_PAGE_INVALID
-5701
Invalid page object

PDF Document

IGE_PDF_DOC_NOT_AUTHORIZED
-5605
This operation is not permitted
IGE_PDF_DOC_CANT_SAVE
-5604
Cannot save document
IGE_PDF_DOC_CANT_OPEN
-5603
Cannot open document
IGE_PDF_DOC_CANT_CREATE
-5602
Cannot create document
IGE_PDF_DOC_INVALID
-5601
Invalid document object

PDF General

IGE_PDF_PRINTING_FAILED
-5541
Printing failed
IGE_PDF_CANT_CREATE_OBJECT
-5540
Cannot create object
IGE_PDF_CANT_EXTRACT_TEXT
-5539
Cannot extract text
IGE_PDF_INVALID_BITCOUNT
-5538
Invalid bit count
IGE_PDF_INVALID_COMPRESSION
-5537
Invalid compression
IGE_PDF_INVALID_PARAMETER
-5536
Invalid parameter
IGE_PDF_CANT_CONVERT_DATA
-5535
Rasterization failed
IGE_PDF_CANT_WRITE_DATA
-5534
Cannot write PDF stream
IGE_PDF_CANT_READ_DATA
-5533
Cannot read PDF stream
IGE_PDF_NOT_INITIALIZED
-5532
PDF engine is not initialized
IGE_PDF_FAILURE
-5531
General PDF error

PostScript General

IGE_PS_POSTSCRIPT_ERROR
-5504
The file contains a PostScript error
IGE_PS_EMPTY_JOB
-5503
Empty PostScript job
IGE_PS_NOT_INITIALIZED
-5502
PostScript engine is not initialized
IGE_PS_FAILURE
-5501
General PostScript job error

Multipage Error Codes

IGE_MP_IMAGE_NOT_ASSOCIATED
-5404
Multipage image is not opened
IGE_MP_ASSOCIATE_FAILURE
-5403
Multipage image open failure
IGE_MP_CANT_OPEN_MUTEX
-5402
Synchronization error
IGE_MP_IMVALID_PAGE_NUMBER
-5401
Invalid page number
IGE_MP_INVALID_HANDLE
-5400
Invalid multipage image handle

PS2 TEXT Function Error Codes

IGE_PS2TEXT_ERROR
-5350
GhostScript PS2TEXT error

PDF Read Function Error Codes

IGE_PDFREAD_GENERAL
-5301
GhostScript general error
IGE_PDFREAD_PSERROR
-5300
GhostScript PostScript error

Bar Function Error Codes

IGE_BAR_EFFORT_OUT_OF_RANGE
-5220
Effort out of range
IGE_BAR_SEARCH_ORDER_FAILURE
-5219
Set bar code search order failure.
IGE_BAR_BASE_API_FAILURE
-5218
Base api failure (error code in 2 parameter)
IGE_BAR_SETUP_FAILURE
-5217
Setup failure of bar code characteristics for recognition
IGE_BAR_SYMBOLOGY_SELECT_FAILURE
-5216
Symbology select failure
IGE_BAR_SYMBOLOGY_UNLICENSED
-5215
BAR symbology unlicensed
IGE_BAR_NOT_LICENSED
-5214
Bar not licensed
IGE_BAR_REGION_NOT_REMOVED
-5213
Bar region not removed
IGE_BAR_TEXT_NOT_READ
-5212
Bar text not read
IGE_BARCODES_NOT_READ
-5211
Barcodes not read
IGE_REGION_SPECIFIED_FAILURE
-5210
Region specified failure
IGE_LOADDIB_FAILURE
-5209
Load dib failure
IGE_IMAGE_DIB_PNTR_NOT_GOT
-5208
Not got image dib pntr
IGE_NOT_CONVERTED_RUNS_TO_DIB
-5207
Not converted runs to dib
IGE_WORKIMAGE_NOT_CREATED
-5206
Work image not created
IGE_BAR_API_FUNCTION_EXCEPTION
-5205
Exception of AutoPilot API function
IGE_BAR_CANT_GET_API_FUNCTION
-5204
Cannot get API function address from AutoPilot DLL
IGE_BAR_CANT_CLOSE
-5203
Cannot close AutoPilot API DLL
IGE_BAR_CANT_OPEN
-5202
Cannot open AutoPilot API DLL
IGE_BAR_CANT_UNLOAD
-5201
Cannot unload AutoPilot API DLL
IGE_BAR_CANT_LOAD
-5200
Cannot load AutoPilot API DLL

XRX Format Conversion Error codes

IGE_XRX_CV_NODATA
-5119
when @fa file is 0 byte
IGE_XRX_CV_XDOCFLAVOR
-5118
not XDOC_PLUS flavor
IGE_XRX_CV_DISKSPACE
-5116
lack of disk space
IGE_XRX_CV_PREOPENFAIL
-5113
The PRE can't be opened to write
IGE_XRX_CV_FILECANCEL
-5112
cancel by the call back from app.
IGE_XRX_CV_FILEDELETE
-5111
delete file fail
IGE_XRX_CV_VERSION
-5110
not the current version of fatext
IGE_XRX_CV_SET
-5108
A setting error.
IGE_XRX_CV_FILE
-5107
A file error.
IGE_XRX_CV_MEM
-5106
Out of memory.
IGE_XRX_CV_FA
-5105
Bad @fa file.
IGE_XRX_CV_DC
-5104
Bad xdc file.
IGE_XRX_CV_BADINPUT
-5103
Bad input data.
IGE_XRX_CV_NIL
-5102
Unexpected NIL value.
IGE_XRX_CV_EOD
-5101
End of data.
IGE_XRX_CV_UNKNOWN
-5100
Unknown conversion error

XRX Function Error Codes

IGE_XRX_NOT_SUPPORTED_FORMAT
-5048
not supported output file format
IGE_XRX_BAD_BITCOUNT
-5047
bits per pixel = 1
IGE_XRX_BAD_RESOLUTION
-5046
DPI can't be zero
IGE_XRX_WRITE_FAILED
-5045
I/O write failed (no space)
IGE_XRX_PROCESSING_CANCEL
-5044
Server cancelled processing on its initiative = - page may be too complex for selected mode
IGE_XRX_BAD_VERSION
-5043
Server is for wrong version
IGE_XRX_TIMEOUT
-5042
Timeout error on IPC to server
IGE_XRX_IMAGE_BUFFER_OVERFLOW
-5041
Image buffer full/overflow
IGE_XRX_NO_INPUT_INFO
-5040
No input format available for use with user defined input et. al.
IGE_XRX_NO_OUTPUT_INFO
-5039
No output format available for use with regions et. al.
IGE_XRX_NO_LICENSE_SERVER
-5038
Licensed version of API could not find license server
IGE_XRX_NO_LICENSE_API
-5037
Licensed version of API could not acquire a license from server
IGE_XRX_PP_FAILED
-5036
Bitmap preprocessing failed
IGE_XRX_LEX_OVERFLOW
-5035
Too many lexicons, remove one
IGE_XRX_BAD_REGION
-5034
Region index error
IGE_XRX_NO_IMAGE
-5033
Preprocessing, Recognition with no image
IGE_XRX_BAD_INTERNAL_DDB
-5032
HBITMAP is NULL (internal error)
IGE_XRX_BAD_COMBINATION
-5031
Param combination not supported or file format legal but not supported
IGE_XRX_BAD_HIGEAR
-5030
Invalid HIGEAR handle
IGE_XRX_BAD_PAGE_NUMBER
-5029
Nothing (more) to read
IGE_XRX_TOO_MANY_RESMODE
-5028
Image resolution change within a document too many times
IGE_XRX_NOT_WAIT
-5027
ICR must be waiting to make this call
IGE_XRX_NOT_IDLE
-5026
ICR must be idle to make this call
IGE_XRX_BAD_FILE
-5025
Bad file or file content associated
IGE_XRX_BAD_IMAGE_FORMAT
-5024
Invalid input format
IGE_XRX_FATAL
-5023
Fatal condition detected
IGE_XRX_REGION_OCCLUDED
-5021
Region is totally occluded
IGE_XRX_BAD_ORIENTATION
-5020
Could not orient text
IGE_XRX_ACCESS_DENIED
-5019
Access denied to this feature see your sales rep.
IGE_XRX_BAD_POLYGON
-5018
Invalid UOR or polygon passed to the server
IGE_XRX_UNKNOWN
-5017
Unknown or internal error
IGE_XRX_BAD_HEAP
-5016
Heap was corrupted
IGE_XRX_NO_MEMORY
-5015
ICR process memory error
IGE_XRX_NO_VERIFICATION
-5014
ICR not blocked on verification
IGE_XRX_BAD_PARAMETER
-5013
Bad function parameter
IGE_XRX_NO_LANG
-5012
Language not loaded/installed
IGE_XRX_BAD_LANGID
-5011
Invalid index for language/lexicon
IGE_XRX_LANG_OVERFLOW
-5010
Too many language packs, remove one
IGE_XRX_BAD_MODE
-5008
Bad recognition or verification mode
IGE_XRX_BAD_TIME
-5006
Parameter cannot be set at this time
IGE_XRX_BAD_PARAM_VALUE
-5005
Value bad or out of range
IGE_XRX_BAD_PARAM_ID
-5004
Bad tag in tag value set
IGE_XRX_NOT_INITIALIZED
-5003
Server not found or down
IGE_XRX_BAD_HANDLE
-5002
Handle is NULL
IGE_XRX_BAD_POINTER
-5001
Pointer is NULL
IGE_XRX_CANNOT_INIT_XRX_SESSION
-5000
Cannot init XRX session

Display Error Codes

IGE_FAIL_TO_DRAW_IMAGE
-4910
cannot draw image
IGE_INVALID_PRM_OPERATION
-4890
invalid operation
IGE_INVALID_PARAMETER
-4880
invalid parameter
IGE_INVALID_IMAGE_HANDLE
-4870
invalid image handle
IGE_INVALID_DEVICE_CONTEXT
-4860
invalid device context
IGE_INVALID_DISPLAY_PARAMETER
-4850
invalid display parameter
IGE_FORMAT_OPERATION_IS_NOT_SUPPORTED
-4840
format operation is not supported
IGE_INVALID_FORMAT_BIT_COUNT
-4835
invalid format bit count
IGE_INVALID_FORMAT_HEADER
-4830
invalid format header
IGE_INVALID_FORMAT_METHOD_ID
-4825
invalid format method ID
IGE_FAIL_TO_ALLOC_MUTEX
-4820
cannot allocate critical session data
IGE_GROUP_IS_NOT_EXIST
-4815
group does not exist
IGE_INVALID_OBJECT
-4811
invalid object
IGE_THREAD_ALREADY_ASSOCIATED
-4810
thread is already associated
IGE_FAIL_TO_ALLOC_PAMETER_GROUP
-4805
cannot allocate parameter group
IGE_CANT_OPEN_FORMAT_STORAGE_MUTEX
-4801
cannot start critical session
IGE_CANT_OPEN_PARAMETER_MUTEX
-4800
cannot start critical session

MS61 Function Error codes

IGE_MS61_UNSUPPORTED_CAPABILITY
-4718
Unsupported capability
IGE_MS61_CANT_GET_DRIVER_NAME
-4717
Cannot get driver name
IGE_MS61_CANT_SELECT_DRIVER_IN_MANUAL_MODE
-4716
Cannot select driver in manual mode
IGE_MS61_WRONG_CB_TYPE
-4715
Wrong CallBack type
IGE_MS61_CANT_TRANSFERIMAGE
-4714
Cannot transfer image to application
IGE_MS61_KERNEL_FUNCTION_EXCEPTION
-4713
Kernel function exception
IGE_MS61_SCAN_RASTER_TOO_LONG
-4712
Scan raster too long
IGE_MS61_NOT_SUPPORTED_COMPRESSION
-4711
Not supported compression
IGE_IMAGE_BUFFER_FILE_FAILURE
-4710
Failure to create file for image buffer
IGE_MS61_SCANNING_FAILED
-4709
Image scanning failed
IGE_MS61_SCANNER_UNACCESSIBLE
-4708
Kernel function error
IGE_MS61_KERNEL_FUNCTION_ERROR
-4707
Kernel function error
IGE_MS61_CANT_GET_SETTINGS
-4706
Cant get settings
IGE_MS61_IMAGE_TRANSFER_IS_CANCELED
-4705
image transfer canceled
IGE_MS61_TRANSFER_CB_CANCELED
-4704
Call back canceled
IGE_MS61_CANT_GET_IMAGE_LAYOUT
-4703
Cannot get image layout
IGE_MS61_CANT_GET_IMAGE_INFO
-4702
Cannot get image info
IGE_MS61_CANT_SELECT_DRIVER
-4701
Cannot select driver, next parameter contains MS61 error code
IGE_MS61_DLL_ACCESS
-4700
IG can not access ISIS DLL
IGE_MS61_CANT_CLOSE
-4646
Cannot close driver
IGE_MS61_CANT_ENABLE_DRIVER
-4613
Cannot enable driver
IGE_MS61_CANT_OPEN_DRIVER
-4612
Cannot load data Source
IGE_MS61_CANT_OPEN
-4611
Cannot load ISIS DLL

ISIS Function Error codes

IGE_ISIS_SCANNING_CANCELED
-4408
ISIS scanning was canceled
IGE_ISIS_DRIVER_NOT_LOADED
-4407
ISIS driver is not loaded
IGE_ISIS_SCANNING_FAILED
-4406
ISIS scanning failed
IGE_ISIS_RASTER_TOO_LONG
-4405
ISIS scan raster is too long
IGE_ISIS_COMPRESSION_NOT_SUPPORTED
-4404
ISIS compression is not supported
IGE_ISIS_INVALID_CB_TYPE
-4403
ISIS callback function type is invalid
IGE_ISIS_INVALID_INDEX
-4402
ISIS array index is invalid
IGE_ISIS_INVALID_HANDLE
-4401
ISIS handle is invalid
IGE_ISIS_INTERNAL_ERROR
-4400
ISIS internal error

TWAIN Scanning Function Error codes

IGE_TW_SOURCE_NOT_OPEN
-4083
No data source is currently open
IGE_TW_PALETTE_SIZE_MISMATCH
-4082
Palette size mismatch
IGE_TW_PIX_TYPE_MISMATCH
-4081
Pixel type mismatch
IGE_TW_SCANNING_CANCELED
-4080
Scanning was canceled
IGE_TW_AUDIO_TRANSFER_FAILED
-4079
Audio transfer operation failed
IGE_TW_AUDIO_TRANSFER_CANCELED
-4078
Audio transfer operation was canceled
IGE_TW_IMAGE_TRANSFER_FAILED
-4077
Image transfer operation failed
IGE_TW_IMAGE_TRANSFER_CANCELED
-4076
Image transfer operation was canceled
IGE_TW_TRANSFER_CB_CANCELED
-4075
Callback canceled transfer operation
IGE_TW_SELECT_DS_CANCELED
-4074
User canceled data source selection operation
IGE_TW_PIX_TYPE_NOT_SUPPORTED
-4073
Pixel type not supported
IGE_PALETTE_TYPE_NOT_SUPPORTED
-4072
Palette type not supported
IGE_TW_DATA_TYPE_NOT_SUPPORTED
-4071
TWAIN data type not supported
IGE_TW_COMPRESSION_NOT_SUPPORTED
-4070
Compression type not supported
IGE_TW_FILE_FORMAT_NOT_SUPPORTED
-4069
File format not supported
IGE_TW_TRANSFER_MODE_NOT_SUPPORTED
-4068
Transfer mode not supported
IGE_TW_CONTAINER_TYPE_NOT_SUPPORTED
-4067
Capability container type not supported
IGE_TW_PREVIEW_CAMERA_NOT_FOUND
-4066
Unable to find preview camera
IGE_TW_DLL_NOT_FOUND
-4065
TWAIN data source manager DLL not found
IGE_TW_VALUE_TOO_SHORT
-4064
Value buffer is too short to hold value
IGE_TW_CANT_GET_PALETTE
-4063
Can't get image palette
IGE_TW_CANT_SET_DATA_GROUP
-4062
Can't set data group
IGE_TW_CANT_GET_AUDIO_INFO
-4061
Can't get audio info
IGE_TW_CANT_PROCESS_MSG
-4060
Can't process TWAIN message
IGE_TW_CANT_SET_TRANSFER_PARAMS
-4059
Can't set image transfer parameters
IGE_TW_CANT_GET_TRANSFER_PARAMS
-4058
Can't get image transfer parameters
IGE_TW_CANT_GET_IMAGE_LAYOUT
-4057
Can't get image layout struct
IGE_TW_CANT_GET_IMAGE_INFO
-4056
Can't get image info struct
IGE_TW_CANT_SET_CAP
-4055
Can't set capability value
IGE_TW_CANT_GET_CAP
-4054
Can't get capability value
IGE_TW_CANT_FIND_DS
-4053
Can't find data source
IGE_TW_CANT_DISABLE_DS
-4052
Can't disable data source
IGE_TW_CANT_ENABLE_DS
-4051
Can't enable data source
IGE_TW_CANT_CLOSE_DS
-4050
Can't close data source
IGE_TW_CANT_OPEN_DS
-4049
Can't open data source
IGE_TW_CANT_CLOSE_DSM
-4048
Can't close data source manager
IGE_TW_CANT_OPEN_DSM
-4047
Can't open data source manager
IGE_TW_CANT_CLOSE_FILE
-4046
Can't close file on TWAIN device
IGE_TW_CANT_GET_NEXT_FILE
-4045
Can't get next file on TWAIN device
IGE_TW_CANT_GET_FIRST_FILE
-4044
Can't get first file on TWAIN device
IGE_TW_CANT_GET_FILE_INFO
-4043
Can't get file info on TWAIN device
IGE_TW_CANT_FORMAT_MEDIA
-4042
Can't format media on TWAIN device
IGE_TW_CANT_DELETE_FILE
-4041
Can't delete file on TWAIN device
IGE_TW_CANT_RENAME_FILE
-4040
Can't rename file on TWAIN device
IGE_TW_CANT_COPY_FILE
-4039
Can't copy file on TWAIN device
IGE_TW_CANT_CREATE_DIR
-4038
Can't create directory on TWAIN device
IGE_TW_CANT_CHANGE_DIR
-4037
Can't change directory on TWAIN device
IGE_TW_CANT_SET_AUTO_CAPTURE_DIR
-4036
Can't set destination directory for auto captured images
IGE_TW_CANT_GET_NEXT_DS
-4035
Can't get next data source
IGE_TW_CANT_GET_FIRST_DS
-4034
Can't get first data source
IGE_TW_CANT_GET_DEFAULT_DS
-4033
Can't get default data source
IGE_TW_CANT_GET_FILE_VERSION
-4032
Can't get file version
IGE_TW_CANT_LOCK_CONTAINER
-4031
Can't lock capability container memory
IGE_TW_INVALID_IMAGE_PARAMS
-4030
Image has invalid parameters
IGE_TW_INVALID_DIB_HANDLE
-4029
Invalid DIB handle
IGE_TW_INVALID_CONTROL_PARAM
-4028
Invalid control parameter identifier
IGE_TW_INVALID_CB_TYPE
-4027
Invalid callback type
IGE_TW_INVALID_VALUE
-4026
Invalid value, does not exist in array
IGE_TW_INVALID_INDEX
-4025
Invalid array index
IGE_TW_INVALID_CAP_HANDLE
-4024
Invalid capability handle
IGE_TW_INVALID_CAP_TYPE
-4023
Invalid capability type
IGE_TW_INVALID_CONTAINER_TYPE
-4022
nvalid capability container type
IGE_TW_SM_CHECKDEVICEONLINE
-4021
The device went offline prior to or during this operation
IGE_TW_SM_FILEWRITEERROR
-4020
Error writing the file (meant for things like disk full conditions)
IGE_TW_SM_PAPERDOUBLEFEED
-4019
The feeder detected multiple pages
IGE_TW_SM_PAPERJAM
-4018
The feeder is jammed
IGE_TW_SM_NOTEMPTY
-4017
Operation failed because directory is not empty
IGE_TW_SM_FILENOTFOUND
-4016
File not found
IGE_TW_SM_FILEEXISTS
-4015
Operation failed because file already exists
IGE_TW_SM_DENIED
-4014
File System operation is denied (file is protected)
IGE_TW_SM_CAPSEQERROR
-4013
Capability has dependency on other capability
IGE_TW_SM_CAPBADOPERATION
-4012
Operation not supported by capability
IGE_TW_SM_CAPUNSUPPORTED
-4011
Capability not supported by source
IGE_TW_SM_BADDEST
-4010
Unknown destination in DSM_ENTRY
IGE_TW_SM_SEQERROR
-4009
Illegal operation for current Source Manager or Source state
IGE_TW_SM_BADVALUE
-4008
Data parameter out of supported range
IGE_TW_SM_BADPROTOCOL
-4007
Unrecognized operation triplet
IGE_TW_SM_BADCAP
-4006
Capability not supported by Source or operation not supported by capability
IGE_TW_SM_OPERATIONERROR
-4005
Source or Source Manager reported an error to the user
IGE_TW_SM_MAXCONNECTIONS
-4004
Source is connected to maximum number of applications
IGE_TW_SM_NODS
-4003
Source Manager unable to find the specified Source
IGE_TW_SM_LOWMEMORY
-4002
Not enough memory to complete operation
IGE_TW_SM_BUMMER
-4001
General failure due to unknown causes
IGE_TW_SM_SUCCESS
-4000
Operation worked

Component related error codes

IGE_FUNCTION_DOESNT_EXIST
-3702
The function doesn't exist in the specified component
IGE_COMPONENT_NOT_ATTACHED
-3701
The component isn't attached
IGE_CANT_ATTACH_COMP
-3700
The specified component can't be attached

Auto Detect Error codes

IGE_FILE_IS_UNSUPPORTED_FILE
-3605
File format is not supported
IGE_FILE_IS_HLP
-3604
File is a Microsoft sytem Help file
IGE_FILE_IS_DOC
-3603
File is a Microsoft DOC file
IGE_FILE_IS_ZIP
-3602
File is a PKZIP file
IGE_FILE_IS_EXE
-3601
File is a EXE, DLL, DRV, FNT, OCX, or 386
IGE_FILE_IS_SYSTEM_FILE
-3600
The image file passed in is really one of the following system files and not an image

Batch conversion CB Error codes

IGE_BATCH_WRONG_CB_TYPE
-3500
Wrong CB type passed to IG_batch_CB_register

Disk File Access Error codes

IGE_FILE_INVALID_PATH
-3450
Invalid path
IGE_FILE_INVALID_FILENAME
-3443
Invalid file name
IGE_FILE_CANT_DELETE
-3442
Cannot delete file
IGE_FILE_CANT_SAVE
-3441
Cannot save file
IGE_FILE_CANT_OPEN
-3440
Cannot open file

Image Processing Error codes

IGE_INVALID_RANK_TYPE
-3424
Specified type of rank in the rank filter is invalid.
IGE_INVALID_RESOLUTION_VALUE
-3423
Resolution value is not supported by a file format.
IGE_INVALID_ALPHA_CHANNEL
-3422
It is possible that width or height not equal to original image.
IGE_INVALID_CLIPING_RECT
-3421
Invalid clipping rect
IGE_RASTER_LINE_INVALID
-3420
The given raster line is invalid, it should be between 0 and the height of the image -1
IGE_PROC_INVAL_FOR_8BIT_INDEXED
-3410
Proc does not work on the 8i images
IGE_DIB_DIMENSIONS_ARE_INVALID
-3400
Either height or width of the DIB is wrong.
IGE_INVALID_BIT_MASK
-3390
The red, green and blue components of the bit mask overlap.
IGE_POINTER_IS_NULL
-3380
Pointer passed to an IP function is NULL, but it would point at object
IGE_INVALID_RESOLUTION_UNIT
-3370
The units of the image resolution are not supported
IGE_PROC_REQUIRE_8BIT_GRAYSCALE
-3360
This function can be used on 8-bit grayscale images only
IGE_PASSWORD_LENGTH_INVALID
-3350
Password must be at least 1-byte long (should be at least 5 bytes)
IGE_INVALID_ENCRYPT_MODE
-3340
The selected Encryption Method is invalid
IGE_INVALID_POINTER
-3330
A pointer was detected to be NULL
IGE_PARAMETER_OUT_OF_LIMITS
-3320
A parameter is out of its legal range
IGE_PROC_INVAL_FOR_PALETTE_IMG
-3310
This function can not be used on 8-bit color images - try to promote to 24-bit
IGE_PROC_INVAL_FOR_BIT_COUNT
-3300
This function can not be used on images with this one's bit count
IGE_DIB_POINTER_IS_NULL
-3220
The DIB pointer about to be used is NULL (invalid)
IGE_COLOR_SPACE_INVALID
-3210
Invalid type of color space
IGE_TILE_IS_LARGER_THAN_IMAGE
-3200
The tile image must be the same size or smaller in both dimensions than the original source
IGE_INVALID_SKEW_POINTS
-3190
A valid line could not be drawn through the two point provided. Y1==Y2
IGE_INVALID_SIGMA
-3180
Invalid sigma
IGE_INVALID_KERN_NORMALIZER
-3170
Invalid kernel normalizer
IGE_INVALID_NOISE_TYPE
-3160
Invalid noise type
IGE_INVALID_KERN_MOTION_EXTENT
-3150
Invalid kernel motion extent
IGE_INVALID_LUT_ARITH_FUNC
-3140
The LUT_ARITH_FUNC is not a valid function number, check the constant
IGE_INVALID_RAMP_DIRECTION
-3130
The contrast ramps direction is not supported
IGE_REQUIRES_CONVEX_ROI
-3120
This function requires a convex ROI. The one passed in must be convex
IGE_ROI_WRONG_TYPE
-3110
Region of interest is wrong type
IGE_DIB_HAS_NO_PALETTE
-3101
The image passed in does not have a palette and this routine requires one
IGE_DIB_BIT_COUNTS_NOT_EQUAL
-3100
The images must have the same bit count
IGE_DIB_DIMENSIONS_NOT_EQUAL
-3090
The images must be the same dimensions
IGE_INVALID_SIGMA
-3080
Invalid sigma
IGE_DIBS_ARE_INCOMPATIBLE
-3070
The images are not compatible for this function, either dimension, bit count, or both
IGE_AI_HANDLE_INVALID
-3060
This routine requires an AccuSoft handle. The handle passed in was not allocated by AccuSoft
IGE_AI_HANDLES_USED_UP
-3050
The maximum number of AccuSoft handles has been used - no more left. Free up some and try again
IGE_BAD_KERN_TYPE
-3040
Bad kernel type
IGE_FREE_FAILED
-3030
An internal memory free has failed, usually a bad handle, or corrupted system
IGE_ALLOC_FAILED
-3020
Memory required for this routine could not be allocated, free up some resources and try again
IGE_LOCK_FAILED
-3010
Memory required for this routine could not be locked, most likely running out of memory resources
IGE_WRONG_DIB_BIT_COUNT
-3000
The DIB has bit with the wrong bit count for this routine

Sync Error Codes

IGE_CANT_UNLOCK_DATA
-2904
Can't unlock data
IGE_CANT_LOCK_DATA
-2903
Can't lock data.
IGE_CANT_UNLOCK_IMAGE
-2902
Can't unlock image
IGE_CANT_LOCK_IMAGE
-2901
Can't lock image.
IGE_IMAGE_IS_LOCKED
-2900
Image is locked

TIFF Filter Specific Errors

IGE_END_OF_IMAGE
-2610
IGE_CANNT_OPEN_INTERNET_SESSION
-2600
Can't open internet session
IGE_CANNT_OPEN_INTERNET_CONNECTION
-2590
Can't open internet connection
IGE_CANNT_OPEN_TEMPORARY_FILE
-2580
Can't open temporary file
IGE_CANNT_OPEN_GOPHER_FILE
-2570
Can't open Gopher file
IGE_CANNT_OPEN_HTTP_FILE
-2560
Can't open HTTP file
IGE_CANNT_OPEN_FTP_FILE
-2550
Can't open FTP file
IGE_JBIG_STREAM_OPEN_FAILURE
-2540
JBIG support library returned an error in return code
IGE_TIF_INVALID_CLASS_F_IMAGE
-2530
Error writing TIF class F format
IGE_ICA_IBM_MMR_COMP_ERROR
-2520
Error in IBM MMR IOCAMO:DCA compression
IGE_ICA_COMP_NOT_SUPPORTED
-2510
MO:DCAIOCA Compression is not supported at this time
IGE_CLP_INVALID_FORMAT_ID
-2500
Windows clipboard file contains an unsupport Format ID at this page
IGE_JBG_IMG_CNTRL_NOT_FOUND
-2486
JBIG Extension Image Control not found for save
IGE_JBIG_EXTENSION_NOT_LOADED
-2485
JBIG Extension has not been loaded
IGE_ABIC_EXTENSION_NOT_LOADED
-2484
ABIC Extension has not been loaded
IGE_IMBEDDED_IMAGE_FAILURE
-2483
Failure occurred while reading a file format imbedded in another
IGE_RASTER_WRITE_FAILURE
-2482
Unable to write Raster to Output Device (Full Device)
IGE_TILE_NOT_PRESENT
-2481
Tile is not present
IGE_LZW_EXTENSION_NOT_LOADED
-2480
LZW Extension has not been loaded
IGE_PRIV_TAG_TYPE_INVALID
-2479
private user tag had an invalid type
IGE_REPAGE_FAILED
-2478
unable to write new page numbers while repaging file
IGE_INVALID_COMP_BIT_DEPTH
-2477
bit depth is invalid for this compression scheme
IGE_INVALID_STRIP_BYTE_CNT
-2476
strip byte count was zero and could not be estimated
IGE_CORRUPTED_FILE
-2475
data in file was not what was expected and could not be interpreted
IGE_PAGE_COUNT_FAILURE
-2474
count not count the number of pages in the file
IGE_BAD_DATA_TYPE
-2473
Data type detected is not valid
IGE_INVALID_IMG_DEM
-2472
Image Dimension was invalid
IGE_LZW_ERROR
-2471
Error occured in LZW decode
IGE_RASTER_TO_LONG
-2470
One raster lines exceeds the max num of bytes
IGE_PLANAR_CONFIG_ERROR
-2469
Planar Config detected is unsupported
IGE_IMAGE_DATA_WRITE_ERROR
-2468
Was not able to write IMAGE data to the IOS
IGE_TAG_WRITE_ERROR
-2467
Was not able to write TAG info to the IOS
IGE_IFD_WRITE_ERROR
-2466
Was not able to write IFD info to the IOS
IGE_CANT_REALLOC_MEM
-2465
Was not able to reallocate memory
IGE_DIB_GET_FAILURE
-2464
Was unable to retreive the DIB information
IGE_HEADER_WRITE_FAILED
-2463
Header write failed
IGE_IMAGE_DATA_READ_ERROR
-2462
Was unable to read all image data requested
IGE_RASTER_FEED_ERROR
-2461
Error feeding raster data to the DIB
IGE_COMP_NOT_SUPPORTED
-2460
Compression is not supported at this time
IGE_INVALID_REQ_INFO
-2459
Required information was not supplied
IGE_INVALID_PHOTOMETRIC
-2458
Photometric tag value was found to be invalid
IGE_INVALID_COLOR_MAP
-2457
Color Map was found to be invalid
IGE_INVALID_BITS_PER_SAMPLE
-2456
Bits per sample tag was invalid
IGE_CANT_READ_TAG_DATA
-2455
Was unable to read all TAG information
IGE_INVALID_BYTE_ORDER
-2454
Byte order flag was not Intel or Motorola
IGE_SEEK_FAILURE
-2453
IOS position seek failed
IGE_IFD_PROC_FAILURE
-2452
Invalid IFD information was detected
IGE_INVALID_IFD
-2451
IFD Read did not contain correct number of bytes
IGE_INVALID_TAG
-2450
Tag Read did not contain correct number of bytes

Miscellaneous Error Codes

IGE_X_NULL_DISPLAY
-2448
X display specified is NULL. ASCII filter is unable to draw text.
IGE_FILTER_UNKNOWN_FORMAT
-2447
Unknown file format
IGE_FILTER_CANT_GET_INFOFUNC
-2446
Fail to get filter's info function
IGE_DIB_RES_UNITS_NOT_SUPPORTED
-2445
DIB resolution units is not supported
IGE_UNDEFNIED_COLOR_SPACE_ID
-2444
color space ID is not defined
IGE_NOT_SUPPORTED_COMP
-2443
Compression is not supported at this time
IGE_PNG_NO_IDAT_CHUNK
-2442
failed to READ a manditory IDAT Chunk
IGE_PNG_READ_FAILED
-2441
failed to READ png data
IGE_PNG_CHUNK_READ_FAILED
-2440
failed to READ the correct number of bytes for png chunk
IGE_PNG_WRITE_FAILED
-2439
failed to write png data
IGE_PNG_CHUNK_WRITE_FAILED
-2438
failed to write the correct number of bytes for png chunk
IGE_STANDARD_FEATURE
-2437
This feature is not available in Lite version
IGE_LOAD_FUNCTION_GET_FAILED
-2436
Was not able to intialize the filer load function
IGE_ALLOC_SELECTOR_FAILED
-2435
AllocSelector() failed, couldn't get an entry into the Global Descriptor able
IGE_CAN_NOT_OPEN_TEMP_FILE
-2434
The temporary file need for this function could not be openedcreated
IGE_PROC_INVAL_FOR_RUNS_DIB
-2433
This function can not be used on DIBs in the Runs format - convert first IG_IP_convert_runs_to_DIB
IGE_OPERATION_IS_NOT_ALLOWED
-2432
IGE_PJPEG_NOT_SUPPORTED
-2427
Progressive JPEG feature is not supported
IGE_JPG_INVALID_HUFFMAN_TABLE
-2426
Invalid huffman table
IGE_JPG_INVALID_HUFFMAN_ID
-2425
Invalid huffman table descriptor
IGE_JPG_INVALID_QTABLE_PRECISION
-2424
Invalid quantization table precision
IGE_JPG_INVALID_QTABLE_ID
-2423
Invalid quantization table descriptor
IGE_JPG_UNRECOGNIZE
-2422
Unrecognized JPEG marker encountered
IGE_PJPEG_INVALID_SCAN_COUNT
-2421
Invalid number of scans for progresive JPEG write
IGE_PJPEG_INVALID_SCAN_
CONFIGURATION
-2420
Invalid configuration of scans for progressive JPEG write
IGE_IMNET_INVALID_WIDTH
-2418
Invalid width for IMNET
IGE_NAME_CONV_NOT_SUPPORTED
-2416
Batch Naming configuration not supported
IGE_LOG_FILE_CREATE_ERROR
-2415
Unable to create Batch Log File
IGE_DIRECTORY_CREATE_ERROR
-2414
Unable to create Destination Directory
IGE_BITDEPTH_NOTSUPPORTED
-2413
This Bit-Depth is not supported for this write format
IGE_G3_PREMATURE_EOL_AT_SCAN_LINE
-2412
Group 3 premature EOL
IGE_G3_BAD_1D_CODE_AT_SCAN_LINE
-2411
Group 3 bad 1D code
IGE_G3_PREMATURE_EOF_AT_SCAN_LINE
-2410
Group 3 premature EOF
IGE_G4_BAD_DECODING_STATE_AT_
SCAN_LINE
-2403
Group 4 bad decoding state
IGE_G4_BAD_2D_CODE_AT_SCAN_LINE
-2402
Group 4 invalid 2D code
IGE_G4_PREMATURE_EOL_AT_SCAN_LINE
-2401
Group 4 premature EOL
IGE_G4_PREMATURE_EOF_AT_SCAN_LINE
-2400
Group 4 premature EOF
IGE_PALETTE_FILE_INVALID_HALO_PAL
-2399
Detected Dr. Halo Palette file is invalid
IGE_PALETTE_FILE_NOT_DETECTED
-2398
The file is not a valid palette file
IGE_PALETTE_FILE_READ_ERROR
-2397
Error reading from a palette file
IGE_PALETTE_FILE_WRITE_ERROR
-2396
Error writing to a palette file
IGE_PALETTE_FILE_TYPE_INVALID
-2395
IG_PALETTE_ value is not known
IGE_NO_BITMAP_FOUND
-2394
WPG, WMF etc. No raster image exists in file
IGE_CANT_WRITE_FILE
-2393
File can't be saved in the specified format.
IGE_EPS_NO_PREVIEW
-2392
EPS file has no screen preview image to load
IGE_BAD_FILE_FORMAT
-2391
Format is not correct.
IGE_NO_BITMAP_REGION
-2390
No bitmap region
IGE_INTERRUPTED_BY_USER
-2113
Status bar callback returned FALSE
IGE_INVALID_BITCOUNT_FOR_FORMAT
-2112
The bitcount found is not supported by this format
IGE_FILE_FORMAT_IS_READONLY
-2111
The image file is read only and can not be written to
IGE_INVALID_IMAGE_FORMAT
-2110
The image file is invalid as the expected format
IGE_CANT_READ_FILE
-2100
Can't read file
IGE_CANT_SETUP_DIB_HEADER
-2095
Can't setup DIB header
IGE_INSTANCE_CLEANUP_ERROR
-2091
Instance cleanup error
IGE_INSTANCE_FAILURE
-2090
Instance failure
IGE_INVALID_COMPRESSION
-2080
Invalid compression
IGE_FORMAT_NOT_DETECTABLE
-2073
Save format can not be detected from file extension used
IGE_CANT_WRITE_HEADER
-2072
Can't write header
IGE_CANT_WRITE_PIXELS
-2071
Can't write pixel data
IGE_CANT_WRITE_PALETTE
-2070
Can't write palette
IGE_INVALID_HEADER
-2061
Invalild file header
IGE_INVALID_FILE_TYPE
-2060
Invalid file type
IGE_CANT_READ_HEADER
-2052
Can't read header
IGE_CANT_READ_PIXELS
-2051
Can't read pixel data
IGE_CANT_READ_PALETTE
-2050
Can't read palette
IGE_FILE_SIZE_WRITE_ERROR
-2041
Could not write file size field to BMP
IGE_BMP_IS_COMPRESSED
-2040
The BMP file is in compressed (RLE) format
IGE_FILE_TO_SMALL_TO_BE_BMIH
-2035
The file is too small to be a valid BMIH
IGE_FILE_IS_NOT_BMP
-2034
The BMFH Magic number is invalid
IGE_FILE_TO_SMALL_TO_BE_BMFH
-2033
The file is too small to be a valid BMFH
IGE_FILE_CANT_BE_CLOSED
-2032
An attempt to close a file failed
IGE_FILE_CANT_BE_CREATED
-2031
An attempt to create a file failed, it may already exist in the provided path
IGE_FILE_CANT_BE_OPENED
-2030
An attempt to open a file failed, it may not exist in the provided path
IGE_CANT_DETECT_FORMAT
-2010
The format of the file can not be determined
IGE_PAGE_COULD_NOT_BE_READ
-2007
The page number could not be determined
IGE_PAGE_INVALID
-2006
The page number provided is outside of the range of valid pages for this file
IGE_PAGE_NOT_PRESENT
-2005
The requested image page does not exist in the file
IGE_THUMBNAIL_NOT_SUPPORTED
-2002
Thumbnails are not supported by this format
IGE_THUMBNAIL_READ_ERROR
-2001
A read error occured while reading a thumbnail
IGE_THUMBNAIL_NOT_PRESENT
-2000
Thumnails are supported but none can be found in this image file
IGE_PASSWORD_INVALID
-1016
The Password is not recognized
IGE_INVALID_PATTERN_BITMAP
-1015
The DDB was > 1 bit per pixel or the width was > 8 or the height was > 8
IGE_COULD_DISPLAY_DDB
-1014
BitBlt() failed. Couldn't display the DDB
IGE_CREATE_BITMAP_FAILED
-1013
CreateBitmap() failed. Couldn't create a DDB.
IGE_COULD_NOT_GET_DDB_BITS
-1012
GetDIBits() failed. Couldn't get the DDB's image data
IGE_COULD_NOT_GET_DDB_DIMENSIONS
-1011
GetObject() failed. Couldn't get the DDB's dimensions
IGE_SETCLIPBOARDDATA_FAILED
-1010
Could not put data into the clipboard
IGE_CLIPBOARD_OPEN_FAILED
-1009
Could not open the clipboard
IGE_NO_CLIPBOARD_IMAGE_AVAILABLE
-1008
No image is available for a clipboard paste
IGE_INVALID_RECTANGLE
-1007
Occurs when a rectangle's left >= right or top >= bottom
IGE_INTERNAL_ERROR
-1005
An internal error has occured, contact ACCUSOFT techical support
IGE_INVALID_STANDARD_KERNEL
-1004
The kernel expected one of the predefined ones, yours could not be found
IGE_EVAL_DLL_TIMEOUT_HAS_EXPIRED
-1003
The DLL is an Evaluation copy and as timed out - contact ACCUSOFT to purchase a release copy
IGE_OUT_OF_MEMORY
-1000
No more global memory is available for allocation, reduced used resources
IGE_FUNCTIONALITY_NOT_SUPPORTED
-900
The ImageGear functionality is not supported under this platform.
IGE_EXTENSION_INITIALIZATION_FAILED
-800
The specified ImageGear extension was unable to initialize.
IGE_INVALID_EXTENSION_MODULE
-700
The specified ImageGear extension file was not a valid extension file
IGE_INVALID_CONTROL_OPTION
-600
Invalid image control option ID
IGE_COMPONENT_ATTACH_FAILURE
-553
Failure to attach component.
IGE_INVALID_COMPONENT_MODULE
-552
The module is not component or has wrong interface
IGE_INVALID_FUNCTION_POINTER
-551
Invalid pointer to the component's function
IGE_INVALID_FUNCTION_NAME
-550
The name of the component's function is invalid
IGE_FILTER_CTRL_INVALID_NAME
-512
The name of control parameter is invalid or not supported
IGE_INVALID_FILTER_OPERATION
-511
Requested operation is not supported by format filter
IGE_FILTER_NOT_LOADED
-510
Requested format filter is not present
IGE_EXTENSION_NOT_LOADED
-500
The ImageGear extension was not present or couldn't be loaded
IGE_BUFFER_HAS_INSUFFICIENT_SIZE
-404
Incoming buffer has insufficient size
IGE_PARAMETER_HAS_INVALID_VALUE
-401
Incoming parameter is invalid
IGE_ERROR_COMPRESSION
-400
IGE_NOT_SUPPORTED_BY_PLATFORM
-350
The last function used is not supported by this platform.
IGE_NOT_LITE_FEATURE
-301
An attempt was made to use a Non IG-Lite feature in the IG-Lite product.
IGE_NOT_IMPLEMENTED
-200
For internal reference of areas to return to
IGE_NOT_DONE_YET
-100
For internal reference of areas to return to
IGE_FAILURE
-1
General error - Failure
IGE_SUCCESS
0
No errors -- Success


Appendix: Non-Image Data Storage

This Appendix provides you with detailed information about ImageGear:

  • Metadata Structure "ValueType" and "Value" .
  • TIFF Non-Image Data Structure
  • JPEG Non-Image Data Structure
  • EXIF-TIFF Non-Image Data Structure
  • EXIF-JPEG Non-image Data Structure
  • CIFF Non-Image Data Structure
  • IPTC Non-Image Data Structure
  • PNG Non-Image Data Structure
  • GIF Non-image Data Structure
  • DCRAW Non-Image Data Structure
  • HD Photo Non-Image Data Structure
  • XMP Non-Image Data Structure
  • JPEG2000 Component Metadata


Metadata Structure "ValueType" and "Value"

Here are possible combinations of ValueType and Value elements of AT_DATALIST_ITEM ImageGear metadata structure:

ValueType
Value
AM_TID_META_INT8
  • The "FLTR.METADATA_FORMAT" global parameter value is "text" :
Value is pointer to NUL-terminated ASCII string - textual representation of "Length" 8-bit signed integers separated by comma.
Example: "-128;0;+45;56"
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" :
Value is pointer to array of 8-bit signed integers of size "Length"
AM_TID_META_UINT8
  • The "FLTR.METADATA_FORMAT" global parameter value is "text" :
Value is pointer to NUL-terminated ASCII string - textual representation of "Length" 8-bit unsigned integers separated by comma. The hexadecimal values are allowed.
Example: "0;+18;255;0xFA"
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 8-bit signed integers of size "Length"
AM_TID_META_INT16
  • The "FLTR.METADATA_FORMAT" global parameter value is "text":
Value is pointer to NUL-terminated ASCII string - textual representation of "Length" 16-bit signed integers separated by comma.
Example: "0;+1800;-255;32355"
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 16-bit signed integers of size "Length"
AM_TID_META_UINT16
  • The "FLTR.METADATA_FORMAT" global parameter value is "text":
Value is pointer to NUL-terminated ASCII string - textual representation of "Length" 16-bit unsigned integers separated by comma. The hexadecimal values are allowed.
Example: "0;+543;2550;0x12FF"
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 16-bit signed integers of size "Length"
AM_TID_META_INT32
  • The "FLTR.METADATA_FORMAT" global parameter value is "text":
Value is pointer to NUL-terminated ASCII string - textual representation of "Length" 32-bit signed integers separated by comma.
Example: "0;+67;-235987;32355"
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 32-bit signed integers of size "Length"
AM_TID_META_UINT32
  • The "FLTR.METADATA_FORMAT" global parameter value is "text":
Value is pointer to NUL-terminated ASCII string - textual representation of "Length" 32-bit unsigned integers separated by comma. The hexadecimal values are allowed.
Example: "0;+543;12362550;0x56FDE345"
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 32-bit signed integers of size "Length"
AM_TID_META_INT64
  • The "FLTR.METADATA_FORMAT" global parameter value is "text":
Value is pointer to NUL-terminated string - textual representation of "Length" 64-bit signed integers separated by comma.
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 32-bit signed integers of size "Length"
AM_TID_META_UINT64
  • The "FLTR.METADATA_FORMAT" global parameter value is "text":
Value is pointer to NUL-terminated ASCII string - textual representation of "Length" 64-bit unsigned integers separated by comma. The hexadecimal values are allowed.
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 32-bit signed integers of size "Length"
AM_TID_META_BOOL
  • The "FLTR.METADATA_FORMAT" global parameter value is "text":
Value is pointer to NULL-terminated string - textual representation of "Length" Boolean values separated by comma.
Example: "TRUE;FALSE;false;true"
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 32-bit unsigned integers of size "Length"
The value 1 represents boolean TRUE and the value 0 represents boolean FALSE.
AM_TID_META_RATIONAL_INT32
  • The "FLTR.METADATA_FORMAT" global parameter value is "text":
Value is pointer to NUL-terminated ASCII string - textual representation of "Length" rational values separated by comma. Each rational value is fraction where both numerator and denominator are 32-bit signed integers separated by slash. Zero is allowed.
Example: "+324/-567;0/0;-68/45668"
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 32-bit signed integers of size 2 * "Length"
Each two elements represent pair (numerator, denominator) that represents rational number numerator/denominator.
AM_TID_META_RATIONAL_UNT32
  • The "FLTR.METADATA_FORMAT" global parameter value is "text":
Value is pointer to NUL-terminated ASCII string - textual representation of "Length" rational values separated by comma. Each rational value is fraction where both numerator and denominator are 32-bit unsigned integers separated by slash. Zero is allowed.
Example: "+324/567;0/0"
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 32-bit unsigned integers of size 2 * "Length"
Each two elements represent pair (numerator, denominator) that represents rational number numerator/denominator.
AM_TID_META_FLOAT
  • The "FLTR.METADATA_FORMAT" global parameter value is "text":
Value is pointer to NUL-terminated ASCII string - textual representation of "Length" 4-byte float-point values separated by comma.
Example: "-298.98676;3568732;6.9876E-10;0"
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 4-byte float-point values of size "Length"
AM_TID_META_DOUBLE
  • The "FLTR.METADATA_FORMAT" global parameter value is "text":
Value is pointer to NUL-terminated ASCII string - textual representation of "Length" 8-byte (double precision) float-point values separated by comma.
Example:
"-29842.9867698098;356873245345;6.98766575489E+50;0"
  • The "FLTR.METADATA_FORMAT" global parameter value is "binary" (DLL only):
Value is pointer to array of 8-byte (double precision) float-point values of size "Length"
AM_TID_META_STRING
  • It does not depend on "FLTR.METADATA_FORMAT" global parameter value
Value is pointer to NUL-terminated ASCII string, "Length" - length of the string (NULL is not counted).
Example: "Simple string"
AM_TID_RAW_DATA
  • It does not depend on "FLTR.METADATA_FORMAT" global parameter value
Value is pointer to byte array that represent binary data, "Length" - size of the array in bytes.


Non-Image Data Structure

In this section the metadata items (and sequence of metadata items) is written in table form where metadata type constants are in the shorted form. For example the LEVEL_START should be treated as IG_METAD_LEVEL_START, UINT32 - as AM_TID_META_UINT32, RAW_DAT - as AM_TID_RAW_DATA etc.

See Also:
  • TIFF Non-Image Data Structure
  • JPEG Non-Image Data Structure
  • EXIF-TIFF Non-Image Data Structure
  • EXIF-JPEG Non-image Data Structure
  • IPTC Non-Image Data Structure
  • PNG Non-Image Data Structure


TIFF Non-Image Data Structure

TIFF metadata structure is framed in several levels:

  • TIFF level containing all TIFF metadata
  • IFD level,
  • Tags

TIFF level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"TIFF"
IG_FORMAT_TIF
LEVEL_START
0
NULL
0
TRUE
"TIF_
HEADER"
59936
VALUE_ITEM
UINT16
0x4949 or
0x4D4D
1
TRUE
Main IFD level
"TIFF"
IG_FORMAT_TIF
LEVEL_END
0
NULL
0
TRUE

All items between items with Name "TIFF" and Id IG_FORMAT_TIF (Type LEVEL_START and LEVEL_END) are interpreted as TIFF data. If during sending data from application level to filter level the first item is omitted the data will not be parsed and saved.

NOTE: The subIFDs is not parsed and passed.

IFD level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"IFD"
0
LEVEL_START
0
NULL
0
TRUE
One or more tag items
"IFD"
0
LEVEL_END
0
NULL
0
TRUE

Tags

Most of TIFF tags are passed through metadata callback as

Name
Id
Type
Value Type
Value
Value Length
Read Only
<TagName>
<TagId>
VALUE_ITEM
<ValueType>
<TagValue>
<TagCount>
<R.o.>

The valid values of <TagName>, <TagId> and "Read Only" attributes are available in Description of TIFF tags Table.

See also: TIFF Complex Data Tags

NOTE: It is possible to use tag identifier and value of nonstandard tag (user defined tag).

The <TagCount> is real tag count value that is read/written in file.

The < ValueType > value is the metadata type constant that matches TIFF tag type as described in the table below:

TIFF tag type
Metadata type
BYTE
AM_TID_META_UINT8
SBYTE
AM_TID_META_INT8
SHORT
AM_TID_META_UINT16
SSHORT
AM_TID_META_INT16
LONG
AM_TID_META_UINT32
SLONG
AM_TID_META_INT32
RATIONAL
AM_TID_META_RATIONAL_UINT32
SRATIONAL
AM_TID_META_RATIONAL_INT32
FLOAT
AM_TID_META_FLOAT
DOUBLE
AM_TID_META_DOUBLE
ASCII
AM_TID_META_STRING
UNDEFINED
AM_TID_RAW_DATA

Description of TIFF tags

Item Name
Item Id
Read only
"NewSubfileType"
254
TRUE
"SubfileType"
255
TRUE
"ImageWidth"
256
TRUE
"ImageLength"
257
TRUE
"BitsPerSample"
258
TRUE
"Compression"
259
TRUE
"PhotometricInterpretation"
262
TRUE
"Threshholding"
263
FALSE
"CellWidth"
264
TRUE
"CellLength"
265
TRUE
"FillOrder"
266
FALSE
"DocumentName"
269
FALSE
"ImageDescription"
270
FALSE
"Make"
271
FALSE
"Model"
272
FALSE
"StripOffsets"
273
TRUE
"Orientation"
274
FALSE
"SamplesPerPixel"
277
TRUE
"RowsPerStrip"
278
TRUE
"StripByteCounts"
279
TRUE
"MinSampleValue"
280
FALSE
"MaxSampleValue"
281
FALSE
"XResolution"
282
FALSE
"YResolution"
283
FALSE
"PlanarConfiguration"
284
TRUE
"PageName"
285
FALSE
"XPosition"
286
FALSE
"YPosition"
287
FALSE
"FreeOffsets"
288
TRUE
"FreeByteCounts"
289
TRUE
"GrayResponseUnit"
290
FALSE
"GrayResponseCurve"
291
FALSE
"T4Options"
292
TRUE
"T6Options"
293
TRUE
"ResolutionUnit"
296
FALSE
"PageNumber"
297
TRUE
"TransferFunction"
301
FALSE
"Software"
305
FALSE
"DateTime"
306
FALSE
"Artist"
315
FALSE
"HostComputer"
316
FALSE
"Predictor"
317
TRUE
"WhitePoint"
318
FALSE
"PrimaryChromaticities"
319
FALSE
"ColorMap"
320
TRUE
"HalftoneHints"
321
FALSE
"TileWidth"
322
TRUE
"TileLength"
323
TRUE
"TileOffsets"
324
TRUE
"TileByteCounts"
325
TRUE
"InkSet"
332
FALSE
"InkNames"
333
FALSE
"NumberOfInks"
334
FALSE
"DotRange"
336
FALSE
"TargetPrinter"
337
FALSE
"ExtraSamples"
338
TRUE
"SampleFormat"
339
FALSE
"SMinSampleValue"
340
FALSE
"SMaxSampleValue"
341
FALSE
"TransferRange"
342
FALSE
"JPEGTables"
347
TRUE
"JPEGProc"
512
TRUE
"JPEGInterchangeFormat"
513
TRUE
"JPEGInterchangeFormatLngth"
514
TRUE
"JPEGRestartInterval"
515
TRUE
"JPEGLosslessPredictors"
517
TRUE
"JPEGPointTransforms"
518
TRUE
"JPEGQTables"
519
TRUE
"JPEGDCTables"
520
TRUE
"JPEGACTables"
521
TRUE
"YCbCrCoefficients"
529
FALSE
"YCbCrSubSampling"
530
TRUE
"YCbCrPositioning"
531
FALSE
"ReferenceBlackWhite"
532
FALSE
"Copyright"
33432
FALSE
"PhotoshopResources"
34377
FALSE
"ExifIFDPointer"
34665
TRUE
"GPSInfoIFDPointer"
34675
TRUE

NOTE: Please see file metadata.h for the full list of TIFF Metadata Item Name and Item Id constants.

TIFF Complex Data Tags

Some tags, which value is a complex data, can be passed in parsed form as following:

Name
Id
Type
Value Type
Value
Value Length
Read Only
<TagName>
<TagId>
LEVEL_START
0
NULL
0
TRUE
"TagType"
<TagId>
VALUE_ITEM
UINT16
<TagType>
1
FALSE
"TagCount"
<TagId>
VALUE_ITEM
UINT32
<TagCount>
1
FALSE
<Tag Value Block>: one or more metadata items that identify the tag value
<TagName>
<TagId>
LEVEL_END
0
NULL
0
TRUE

The <TagName> and <TagId> values are the tag name and identifier (available values see in the Table Photoshop Image Resource metadata structure). It is possible to use the tag identifier and value of nonstandard tag (user defined tag).

The <TagType> value is the standard TIFF tag type constant described in TIFF 6.0 specification.

Currently only TIFF tag with ID 34377, where Adobe Photoshop and some other TIFF writers save image recourses (IPTC data, resolution, some LUT etc.), is passed in this form. The <Tag Value Block> of these TIFF tag has structure described in the Table Photoshop Image Resource metadata structure below.

Photoshop Image Resource metadata structure

Name
Id
Type
Value Type
Value
Value Length
Read Only
"PhotoshopImageResource"
<Res. Id>
LEVEL_START
0
NULL
0
TRUE
"PhotoshopImageResourceSize"
<Res. Id>
VALUE_ITEM
UINT16
1
TRUE
Resource data
"DATA"
<Res. Id>
VALUE_ITEM
RAW_DATA
Variable
FALSE
Or in case the data are parsed (currently it is happen only if the resource is IPTC data)
"IPTC"
0x1C00
LEVEL_START
0
NULL
0
TRUE
...
"IPTC"
0x1C00
LEVEL_END
0
NULL
0
TRUE
"PhotoshopImageResource"
<Res. Id>
LEVEL_END
0
NULL
0
TRUE

Where the <Res. Id> is the Adobe Photoshop image resource identifier (see Adobe Photoshop SDK).

IPTC PhotoshopImageResource identifier is 0x0404.

Callback required for writing TIFF metadata items

Value of TIFF metadata tags that are in the table below can be changed using LPAFT_IG_METAD_ITEM_SET_CB callback only:

Item Name
Item Id
"XResolution"
282
"YResolution"
283
"ResolutionUnit"
296
"PageNumber"
297
"Software"
305
"DateTime"
306
"Artist"
315
"FillOrder"
266
"DocumentName"
269

All the rest TIFF metadata tags values can be written using LPAFT_IG_METAD_ITEM_ADD_CB callback only.

TIFF Metadata Item Name and ID constants

NOTE: Please see file metadata.h for the full list of TIFF Metadata Item Name and Item Id constants.


JPEG Non-Image Data Structure

JPEG metadata structure is framed in several levels:

  • JPEG level containing all JPEG metadata,
  • JPEG marker segment levels containing metadata of each separated JPEG marker segment.

JPEG level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"JPEG-JFIF"
IG_FORMAT_JPG
LEVEL_START
0
NULL
0
TRUE
JPEG marker segment levels
"JPEG-JFIF"
IG_FORMAT_JPG
LEVEL_END
0
NULL
0
TRUE

All items between items with Name "JPEG-JFIF" and Id IG_FORMAT_JPG (Type LEVEL_START and LEVEL_END) are interpreted as JPEG metadata. If during sending data from application level to filter level the first item is omitted the data will not be parsed and saved.

JPEG marker segment levels

The following JPEG marker segments metadata are supported:

  • Frame marker segment level - SOF0, SOF1, SOF2 and SOF3 (read only),
  • Scan marker segment level - SOS (read only),
  • Define-quantization-table marker segment level - DQT (read only),
  • Define-Huffman-tables marker segment level - DHT (read only),
  • Comment marker segment level - COM (read/write),
  • Application marker segment level - APP0-APP15 (read/write).

Frame marker segment level

Name
Id
Type
Value Type
Value
Value Length
Read Only
<Frame marker name>
<Frame marker Id>
LEVEL_START
0
NULL
0
TRUE
<Frame marker size tag name>
<Frame marker size tag Id>
VALUE_ITEM
UINT16
1
TRUE
"Precision"
212
VALUE_ITEM
UINT8
1
TRUE
"Lines"
213
VALUE_ITEM
UINT16
1
TRUE
"SamplesPerLine"
214
VALUE_ITEM
UINT16
1
TRUE
"ComponentNumber"
215
VALUE_ITEM
UINT8
<n>
1
TRUE
Frame component level 1
Frame component level <n>
<Frame marker name>
<Frame marker Id>
LEVEL_END
0
NULL
0
TRUE

<Frame marker Id>, <Frame marker name>, <Frame marker size tag name> and <Frame marker size tag Id> are described in the table below:

Frame
Marker
<Frame
marker
name>
<Frame
marker Id>
<Frame marker
size tag name>
<Frame marker
size tag Id>
SOF0
"SOF0"
0xFFC0
"SOF0_DATASIZE"
60192
SOF1
"SOF1"
0xFFC1
"SOF1_DATASIZE"
60193
SOF2
"SOF2"
0xFFC2
"SOF2_DATASIZE"
60194
SOF3
"SOF3"
0xFFC3
"SOF3_DATASIZE"
60195

Frame component level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"Component"
<Component No.>
LEVEL_START
0
NULL
0
TRUE
"Id"
<Component No.>
VALUE_ITEM
UINT
1
TRUE
"MCU_HV"
<Component No.>
VALUE_ITEM
UINT
1
TRUE
"QuantizationNumber"
<Component No.>
VALUE_ITEM
UINT
1
TRUE
"Component"
<Component No.>
LEVEL_END
0
NULL
0
TRUE

NOTE: <Component No.> is frame component identifier of appropriate component.

Scan marker segment level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"SOS"
0xFFDA
LEVEL_START
0
NULL
0
TRUE
"SOS_DATASIZE"
60218
VALUE_ITEM
UINT16
1
TRUE
"ComponentNumber"
228
VALUE_ITEM
UINT8
<n>
1
TRUE
Scan component level 1
Scan component level <n>
"SpectralStart"
235
VALUE_ITEM
UINT8
1
TRUE
"SpectralEnd"
236
VALUE_ITEM
UINT8
TRUE
"AH_AL"
237
VALUE_ITEM
UINT8
TRUE
"SOS"
0xFFDA
LEVEL_START
0
NULL
0
TRUE

Scan component level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"Component"
<Component No.>
LEVEL_START
0
NULL
0
TRUE
"Selector"
<Component No.>
VALUE_ITEM
UINT8
1
TRUE
"DC_AC"
<Component No.>
VALUE_ITEM
UINT8
1
TRUE
"Component"
<Component No.>
LEVEL_END
0
NULL
0
TRUE

NOTE: <Component No.> is scan component selector of appropriate component.

Define-quantization-table marker segment level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"DQT"
0xFFDB
LEVEL_START
0
NULL
0
TRUE
"DQT_DATASIZE"
60219
VALUE_ITEM
UINT16
1
TRUE
"QuantizationTable"
<table 1 Id >
VALUE_ITEM
UINT8 or
UINT16
64
TRUE
"QuantizationTable"
<table 1 Id >
VALUE_ITEM
UINT8 or
UINT16
64
TRUE
"DQT"
0xFFDB
LEVEL_END
0
NULL
0
TRUE

NOTE: <table Id > is the appropriate quantization table identifier.
Define-Huffman-tables marker segment level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"DHT"
0xFFC4
LEVEL_START
0
NULL
0
TRUE
"DHT_DATASIZE"
60196
VALUE_ITEM
UINT16
1
TRUE
"DATA"
0xFFC4
VALUE_ITEM
RAW_DATA
<ValueSize>
TRUE
"DHT"
0xFFC4
LEVEL_END
0
NULL
0
TRUE

Comment marker segment level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"COM"
0xFFFE
LEVEL_START
0
NULL
0
TRUE
"COM_DATASIZE"
60254
VALUE_ITEM
UINT16
1
TRUE
"Comment"
0xFFFE
VALUE_ITEM
STRING
<ValueSize>
TRUE
"COM"
0xFFFE
LEVEL_END
0
NULL
0
TRUE

Application marker segment level

There are several application marker segments, which data structure is well known. These segments are parsed and their data are passed in special format.

These marker segments are:

  • JFIF APP0 segment
  • JFIF extension (JFXX) APP0 segment (read only)
  • EXIF APP1 segment
  • Photoshop Image Resource APP13 marker segment(it includes some IPTC data and another Photoshop Image Resource metadata structure)
  • Other application marker segment levels

JFIF APP0 segment

Name
Id
Type
Value Type
Value
Value Length
Read Only
"APP0"
0xFFE0
LEVEL_START
0
NULL
0
TRUE
"APP0_DATASIZE"
60224
VALUE_ITEM
UINT16
1
FALSE
"JFIF_HEADER"
200
VALUE_ITEM
STRING
JFIF
5
TRUE
"Version"
201
VALUE_ITEM
UINT16
1
FALSE
"ResolutionUnits"
202
VALUE_ITEM
UINT8
1
FALSE
"ResolutionX"
203
VALUE_ITEM
UINT16
1
FALSE
"ResolutionY"
204
VALUE_ITEM
UINT16
1
FALSE
"ThumbnailWidth"1
205
VALUE_ITEM
UINT8
1
TRUE
"ThumbnailHeight"2
206
VALUE_ITEM
UINT8
1
TRUE
"APP0"
0xFFE0
LEVEL_END
0
NULL
0
TRUE

1The thumbnail width tags are present only if the thumbnail is stored to JFIF segment.

2The thumbnail height tags are present only if the thumbnail is stored to JFIF segment.

JFIF extension (JFXX) APP0 segment

Name
Id
Type
Value Type
Value
Value Length
Read Only
"APP0"
0xFFE0
LEVEL_START
0
NULL
0
TRUE
"APP0_DATASIZE"
60224
VALUE_ITEM
UINT16
1
TRUE
"JFIF_EX_HEADER"
209
VALUE_ITEM
STRING
"JFXX"
5
TRUE
"ExtensionCode"
210
VALUE_ITEM
UINT8
1
TRUE
"APP0"
0xFFE0
LEVEL_END
0
NULL
0
TRUE

Photoshop Image Resource APP13 marker segment

Name
Id
Type
Value Type
Value
Value Length
Read Only
"APP13"
0xFFED
LEVEL_START
0
NULL
0
TRUE
"APP13_DATASIZE"
60237
VALUE_ITEM
UINT16
1
FALSE
"PHOTOSHOP_HEADER"
59915
VALUE_ITEM
STRING
"Photoshop 3.0"
14
FALSE
Photoshop Image Resource level 1
...
Photoshop Image Resource level n
"APP13"
0xFFED
LEVEL_END
0
NULL
0
TRUE

NOTE: For "Photoshop Image Resource" metadata structure see in TIFF non-image data Photoshop Image Resource metadata structure Table.

Other application marker segment levels

Name
Id
Type
Value Type
Value
Value Length
Read Only
<Marker name>
<Marker Id>
LEVEL_START
0
NULL
0
TRUE
<Marker size tag name>
<Marker size tag Id>
VALUE_ITEM
UINT16
1
FALSE
"DATA"
<Marker Id>
VALUE_ITEM
RAW_DATA
<ValueSize>
FALSE
<Marker name>
<Marker Id>
LEVEL_END
0
NULL
0
TRUE

<Marker Id>, <Marker name>, <Marker size tag name> and <Marker size tag Id> are in table below:

Marker
<Marker
name>
<Marker
Id>
<Marker size tag
name>
<Marker size tag
Id>
APP0
"APP0"
0xFFE0
"APP0_DATASIZE"
60224
APP1
"APP1"
0xFFE1
"APP1_DATASIZE"
60225
APP2
"APP2"
0xFFE2
"APP2_DATASIZE"
60226
APP3
"APP3"
0xFFE3
"APP3_DATASIZE"
60227
APP4
"APP4"
0xFFE4
"APP4_DATASIZE"
60228
APP5
"APP5"
0xFFE5
"APP5_DATASIZE"
60229
APP6
"APP6"
0xFFE6
"APP6_DATASIZE"
60230
APP7
"APP7"
0xFFE7
"APP7_DATASIZE"
60231
APP8
"APP8"
0xFFE8
"APP8_DATASIZE"
60232
APP9
"APP9"
0xFFE9
"APP9_DATASIZE"
60233
APP10
"APP10"
0xFFEA
"APP10_DATASIZE"
60234
APP11
"APP11"
0xFFEB
"APP11_DATASIZE"
60235
APP12
"APP12"
0xFFEC
"APP12_DATASIZE"
60236
APP13
"APP13"
0xFFED
"APP13_DATASIZE"
60237
APP14
"APP14"
0xFFEE
"APP14_DATASIZE"
60238
APP15
"APP15"
0xFFEF
"APP15_DATASIZE"
60239

Callback required for writing JPEG metadata items

All JPEG metadata items can be written using LPAFT_IG_METAD_ITEM_ADD_CB callback only.

JPEG Metadata Item Name and ID constants

NOTE: Please see file metadata.h for the full list of JPEG Metadata Item Name and Item Id constants.


EXIF-TIFF Non-Image Data Structure

EXIF-TIFF metadata structure is framed in several levels -

  • EXIF-TIFF level containing all EXIF-TIFF data
  • IFD0 level
  • Tag levels

EXIF-TIFF level

The EXIF-TIFF metadata structure is similar to TIFF's one. But EXIF-TIFF allows Exif subIFD tags, GPS subIFD tags and thumbnail IFD tags to be parsed and passed together with main IFD.

Name
Id
Type
Value Type
Value
Value Length
Read Only
"EXIF"
IG_FORMAT_EXIF_TIFF
LEVEL_START
0
NULL
0
TRUE
"TIF_HEADER"
59936
VALUE_ITEM
UINT16
0x4949 or
0x4D4D
1
TRUE
IFD 0 level ( if present)
Thumbnail IFD level ( if present)
"EXIF"
IG_FORMAT_EXIF_TIFF
LEVEL_END
0
NULL
0
TRUE

All items between items with Name "EXIF" and Id IG_FORMAT_EXIF_TIFF (Type LEVEL_START and LEVEL_END) are interpreted as EXIF data. If during sending data from application level to filter level the first item is omitted the data will not be interpreted and saved.

See also Exif subIFD tags for the list of Exif subIFD tag names and Ids.

IFD0 level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"IFD"
0
LEVEL_START
0
NULL
0
TRUE
Exif subIFD, GPS info subIFD and tags levels mixed in any way
"IFD"
0
LEVEL_END
0
NULL
0
TRUE

Exif subIFD level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"IFD"
34665
LEVEL_START
0
NULL
0
TRUE
Interoperability info subIFD and tags levels mixed in any way
"IFD"
34665
LEVEL_END
0
NULL
0
TRUE

The number 34665 is the Exif subIFD pointer tag (see below)

IFD1 (Thumbnail IFD), GPS info subIFD and Interoperability info subIFD levels

Name
Id
Type
Value Type
Value
Value Length
Read Only
"IFD"
<IFDId>
LEVEL_START
0
NULL
0
TRUE
Tag 1
...
Tag n
"IFD"
<IFDId>
LEVEL_END
0
NULL
0
TRUE

The value of <IFDId> is 1 for IFD1 or the subIFD pointer tag identifier for GPS (34853)(see GPS subIFD tags) or Interoperability (40965) subIFD (see Interoperability subIFD tags).

Tag levels

For tag metadata structure see TIFF Non-Image Data Structure.

Description of tags used in EXIF

There are such types of EXIF tags described:

  • Exif subIFD tags
  • GPS subIFD tags
  • Interoperability subIFD tags

For IFD0 and Thumbnail IFD tags see TIFF Non-Image Data Structure.

Exif subIFD tags

Item Name
Item Id
Read Only
"ExposureTime"
33434
FALSE
"Fnumber"
33437
FALSE
"ExposureProgram"
34850
FALSE
"SpectralSensitivity"
34852
FALSE
"ISOSpeedRatings"
34855
FALSE
"OECF"
34856
FALSE
"ExifVersion"
36864
FALSE
"DateTimeOriginal"
36867
FALSE
"DateTimeDigitized"
36868
FALSE
"ComponentsConfiguration"
37121
FALSE
"CompressedBitsPerPixel"
37122
FALSE
"ShutterSpeedValue"
37377
FALSE
"ApertureValue"
37378
FALSE
"BrightnessValue"
37379
FALSE
"ExposureBiasValue"
37380
FALSE
"MaxApertureValue"
37381
FALSE
"SubjectDistance"
37382
FALSE
"MeteringMode"
37383
FALSE
"LightSource"
37384
FALSE
"Flash"
37385
FALSE
"FocalLength"
37386
FALSE
"SubjectArea"
37396
FALSE
"MakerNote"
37500
FALSE
"UserComment"
37510
FALSE
"SubSecTime"
37520
FALSE
"SubSecTimeOriginal"
37521
FALSE
"SubSecTimeDigitized"
37522
FALSE
"FlashPixVersion"
40960
FALSE
"ColorSpace"
40961
FALSE
"PixelXDimension"
40962
TRUE
"PixelYDimension"
40963
TRUE
"RelatedSoundFile"
40964
FALSE
"InteroperabilityIFDPointer"
40965
TRUE
"FlashEnergy"
41483
FALSE
"SpatialFrequencyResponse"
41484
FALSE
"FocalPlaneXResolution"
41486
FALSE
"FocalPlaneYResolution"
41487
FALSE
"FocalPlaneResolutionUnit"
41488
FALSE
"SubjectLocation"
41492
FALSE
"ExposureIndex"
41493
FALSE
"SensingMethod"
41495
FALSE
"FileSource"
41728
FALSE
"SceneType"
41729
FALSE
"CFAPattern"
41730
FALSE
"CustomRendered"
41985
FALSE
"ExposureMode"
41986
FALSE
"WhiteBalance"
41987
FALSE
"DigitalZoomRatio"
41988
FALSE
"FocalLengthIn35mmFilm"
41989
FALSE
"SceneCaptureType"
41990
FALSE
"GainControl"
41991
FALSE
"Contrast"
41992
FALSE
"Saturation"
41993
FALSE
"Sharpness"
41994
FALSE
"DeviceSettingDescription"
41995
FALSE
"SubjectDistanceRange"
41996
FALSE
"ImageUniqueID"
42016
FALSE

GPS subIFD tags

Item Name
Item Id
Read Only
"GPSVersionID"
0
FALSE
"GPSLatitudeRef"
1
FALSE
"GPSLatitude"
2
FALSE
"GPSLongitudeRef"
3
FALSE
"GPSLongitude"
4
FALSE
"GPSAltitudeRef"
5
FALSE
"GPSAltitude"
6
FALSE
"GPSTimeStamp"
7
FALSE
"GPSSatellites"
8
FALSE
"GPSStatus"
9
FALSE
"GPSMeasureMode"
10
FALSE
"GPSDOP"
11
FALSE
"GPSSpeedRef"
12
FALSE
"GPSSpeed"
13
FALSE
"GPSTrackRef"
14
FALSE
"GPSTrack"
15
FALSE
"GPSImgDirectionRef"
16
FALSE
"GPSImgDirection"
17
FALSE
"GPSMapDatum"
18
FALSE
"GPSDestLatitudeRef"
19
FALSE
"GPSDestLatitude"
20
FALSE
"GPSDestLongitudeRef"
21
FALSE
"GPSDestLongitude"
22
FALSE
"GPSDestBearingRef"
23
FALSE
"GPSDestBearing"
24
FALSE
"GPSDestDistanceRef"
25
FALSE
"GPSDestDistance"
26
FALSE
"GPSProcessingMethod"
27
FALSE
"GPSAreaInformation"
28
FALSE
"GPSDateStamp"
29
FALSE
"GPSDifferential"
30
FALSE

Interoperability subIFD tags

Item Name
Item Id
Read Only
"InteroperabilityIndex "
1
FALSE
"InteroperabilityVersion "
2
FALSE
"RelatedImageFileFormat"
4096
FALSE
"RelatedImageWidth "
4097
FALSE
"RelatedImageLength"
4098
FALSE

Callback required for writing EXIF metadata items.

Value of these tags can be changed using LPAFT_IG_METAD_ITEM_SET_CB callback only.

Item Name
Item Id
"TIF_HEADER"
59936
IFD0 tags
"PlanarConfiguration"
284
"YCbCrSubSampling"
530
"RowsPerStrip"
278
"YCbCrPositioning"
531
"XResolution"
282
"YResolution"
283
"ResolutionUnit"
296
Exif subIFD
"ExifVersion"
36864
"FlashPixVersion"
40960
"ColorSpace"
40961
Thumbnail IFD
"ImageWidth"
256
"ImageLength"
257
"PlanarConfiguration"
284
"YCbCrSubSampling"
530
"RowsPerStrip"
278
"YCbCrPositioning"
531
"XResolution"
282
"YResolution"
283
"ResolutionUnit"
296

The rest of metadata item values can be written using LPAFT_IG_METAD_ITEM_ADD_CB callback only.

EXIF-TIFF Metadata Item Name and ID constants

NOTE: Please see file metadata.h for the full list of EXIF Metadata Item Name and Item Id constants.


EXIF-JPEG Non-image Data Structure

The EXIF-JPEG metadata structure is similar to JPEG one. But EXIF-JPEG sends the Exif APP1 marker segment data in parsed form and Jfif APP0 marker segment data is not parsed and sent as raw data.

EXIF-JPEG level

All items between items with Name "EXIF" and Id IG_FORMAT_EXIF_JPEG (Type LEVEL_START and LEVEL_END) are interpreted as EXIF data. If during sending data from application level to filter level the first item is omitted the data will not be interpreted and saved.

For JPEG marker segment levels see JPEG Non-Image Data Structure.

Name
Id
Type
Value Type
Value
Value Length
Read Only
"EXIF-JPEG"
IG_FORMAT_EXIF_JPEG
LEVEL_START
0
NULL
0
TRUE
Exif APP1 marker segment level
JPEG marker segment levels mixed in any way (if present)
"EXIF-JPEG"
IG_FORMAT_EXIF_JPEG
LEVEL_END
0
NULL
0
TRUE

Exif APP1 marker segment level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"APP1"
65505
LEVEL_START
0
NULL
0
TRUE
"APP1_DATASIZE"
60225
VALUE_ITEM
UINT16
<Data>
1
TRUE
"EXIF_HEADER"
59935
VALUE_ITEM
STRING
"EXIF"
5
TRUE
"TIF_HEADER"
59936
VALUE_ITEM
UINT16
0x4949 or
0x4D4D
1
TRUE
IFD 0 level ( if present )
Thumbnail IFD level ( if present )
"APP1"
0xFFE1
LEVEL_END
0
NULL
0
TRUE

NOTE: The "APP1_DATASIZE" item can be omitted during saving.

For more detailed Exif information see EXIF-TIFF Non-Image Data Structure.

EXIF Makernote

Makernote is a standard EXIF tag of UNDEFINED (byte) type. This tag usually is used as a "hidden" IFD. Makernote can not be read in and written out as a BLOB, because IFD offsets become invalid. Therefore, to preserve this tag while writing an image it's necessary to decode it during reading and re-encode it during writing, despite the fact that formally makernote is just a binary tag.

There are several types of makernotes, all of them have corresponding constants in Metadata.h file:

IG_MAKERNOTE_TYPE_UNKNOWN
This is the default type. This type means that we can't decect Makernote as any other type. Preserving such makernote and saving it with the file, most likely, does not make any sence, because IFD offsets will be corrupted.
IG_MAKERNOTE_TYPE_IFD
Makernote is a valid TIF IFD, except that it is not referenced from anywhere in the file, and does not reference other IFDs. Such makernote is preserved entirely when writing to a file.
IG_MAKERNOTE_TYPE_IFD_PREFIXED
Same as IG_MAKERNOTE_TYPE_IFD, but with a short prefix before the IFD. The prefix is also preserved, so the whole Makernote*s* is preserved when writing to a file.
IG_MAKERNOTE_TYPE_TIF_HEADER_PREFIXED
Makernote starts with a prefix, then goes TIF image header, which points to an IFD.
IG_MAKERNOTE_TYPE_IFD_PREFIXED_OFFSET_II
Makernote starts with a prefix, then goes offset to the IFD, then IFD itself. Makernote IFD uses Intel byte ordering (II), even though the whole file uses Motorola ordering.

To present Makernote info in a convenient way ImageGear introduces a special structure as an addition to the standard EXIF Metadata: "Makernote*s* Wrapper IFD". Instead of a single binary Makernote*s* tag (37500), we are adding a virtual IFD, containing all the information about Makernote*s*.

'Makernote Wrapper IFD' has the following format depending on the 'type' tag:

    1. Type IG_MAKERNOTE_TYPE_UNKNOWN:
'MakerNote wrapper IFD'
-------->'type' = IG_MAKERNOTE_TYPE_UNKNOWN
-------->'binary MakerNote'

  1. Type IG_MAKERNOTE_TYPE_IFD:
    2.

'MakerNote wrapper IFD'
-------->'type' = IG_MAKERNOTE_TYPE_IFD
-------->'MakerNote IFD'
----------------> 'individual MakerNote tag 1'
----------------> 'individual MakerNote tag 2'
...
----------------> 'individual MakerNote tag N'
-------->'binary MakerNote'

  1. Type IG_MAKERNOTE_TYPE_IFD_PREFIXED:
    2.

'MakerNote wrapper IFD'
-------->'type' = IG_MAKERNOTE_TYPE_IFD_PREFIXED
-------->'MakerNote IFD prefix'
-------->'MakerNote IFD'
----------------> 'individual MakerNote tag 1'
----------------> 'individual MakerNote tag 2'
...
----------------> 'individual MakerNote tag N'
-------->'binary MakerNote'

  1. Type IG_MAKERNOTE_TYPE_TIF_HEADER_PREFIXED:
    2.

'MakerNote wrapper IFD'
-------->'type' = IG_MAKERNOTE_TYPE_TIF_HEADER_PREFIXED
<The rest of the structure is identical to
IG_MAKERNOTE_TYPE_IFD_PREFIXED>

  1. Type IG_MAKERNOTE_TYPE_IFD_PREFIXED_OFFSET_II:
    2.

'MakerNote wrapper IFD'
-------->'type' = IG_MAKERNOTE_TYPE_IFD_PREFIXED_OFFSET_II
<The rest of the structure is identical to
IG_MAKERNOTE_TYPE_IFD_PREFIXED>

If 'Makernote' EXIF tag is present in the file then ImageGear will always provide it in its original binary form via meta-data callback ('binary Makernote' tag) on the read side, and will also optionally provide it as a decoded sub-IFD (w/ or w/o prefix depending on how it is stored in the original file) if it can be decoded.

ImageGear will ignore 'binary Makernote' tag on the write side for the 'Makernote wrapper IFDs' that have 'type' other than IG_MAKERNOTE_TYPE_UNKNOWN - and construct 'Makernote' EXIF tag based on the 'Makernote IFD'.

ImageGear will store 'binary Makernote' to file 'as is' for the 'Makernote wrapper IFDs' that have 'type' set to IG_MAKERNOTE_TYPE_UNKNOWN.

If 'Makernote wrapper IFD' is not provided to ImageGear during saving operation then 'Makernote' EXIF tag will not be saved into the output file.

Makernote IFD tags are listed below:

Name
Id
Type
Value Type
Value
Value Length
Read Only
"IFD"
***)
LEVEL_START
0
NULL
FALSE
"MakerNoteType"
VALUE_ITEM
UINT16
*)
1
FALSE
"MakerNotePrefix"
VALUE_ITEM
RAW_DATA
FALSE
"MakerNoteBinary"
VALUE_ITEM
RAW_DATA
FALSE
"IFD"
LEVEL_START
0
NULL
0
FALSE
"UNDEFINED"**)
VALUE_ITEM
RAW_DATA
FALSE
...
"IFD"
LEVEL_END
0
NULL
0
FALSE
"IFD"
LEVEL_END
0
NULL
FALSE

*) One of the following enumIGEXIFMakerNoteType constants:

IG_MAKERNOTE_TYPE_UNKNOWN = 0
IG_MAKERNOTE_TYPE_IFD = 1
IG_MAKERNOTE_TYPE_IFD_PREFIXED = 2
IG_MAKERNOTE_TYPE_TIF_HEADER_PREFIXED = 3
IG_MAKERNOTE_TYPE_IFD_PREFIXED_OFFSET_II = 4

**) Manufacturer specific tags, not covered by EXIF standard.

***) See respective IGMDTAG_ID_EXIF_MAKERNOTE_ Id constants in the section Custom Makernote Tags and IFDs

Custom Makernote Tags and IFDs

The following custom tags and IFDs are introduced for Makernote support:

Makernote Wrapper IFD: tag = 37500 (same as standard Makernote tag). This IFD is located in the "Exif IFD" (34665).

New tags, which belong to the Makernote Wrapper IFD:

enum enumIGEXIFMakerNoteTagIDs
{
IGMDTAG_ID_EXIF_MAKERNOTE_TYPE = 1,
IGMDTAG_ID_EXIF_MAKERNOTE_PREFIX = 2,
IGMDTAG_ID_EXIF_MAKERNOTE_BINARY = 1000,
IGMDTAG_ID_EXIF_MAKERNOTE_DATA_IFD = 1001
};

Vendors and models currently supported

Make
Model
Canon
Canon DIGITAL IXUS
Canon
Canon EOS D30
Canon
Canon PowerShot G2
Canon
Canon PowerShot S50
FUJIFILM
FinePix4900Z
LEICA
digilux 4.3
Minolta Co., Ltd.
DiMAGE 7i
Nikon
E5000 (TIF)
NIKON
E5700
NIKON
E950
OLYMPUS OPTICAL CO.,LTD
C2040Z
OLYMPUS OPTICAL CO.,LTD
C960Z,D460Z
Panasonic
DMC-LC5
RICOH
Caplio RR1
SANYO Electric Co.,Ltd.
SR6
SANYO Electric Co.,Ltd.
SX113
SANYO Electric Co.,Ltd.
SX212
SEIKO EPSON CORP.
PhotoPC 850Z

Exif APP2 marker segment (Flashpix extensions) levels

EXIF file format allows to store Flashpix extensions in APP2 marker segments. There are several types of FPXR APP2 marker segments described below:

  • FPXR Contents List APP2 marker segment
  • Interoperability Entity level
  • FPXR Data Stream APP2 marker segment
  • The other FPXR APP2 marker segment

FPXR Contents List APP2 marker segment

Name
Id
Type
Value Type
Value
Value Length
Read Only
"APP2"
0xFFE2
LEVEL_START
0
NULL
0
TRUE
"APP2_DATASIZE"
60226
VALUE_ITEM
UINT16
1
TRUE
"FPXR_HEADER"
61221
VALUE_ITEM
STRING
"FPXR"
4
FALSE
"FPXRVersion"
61222
VALUE_ITEM
UINT8
1
FALSE
"FPXRExtensionID"
61223
VALUE_ITEM
UINT8
"1"
1
FALSE
"FPXRInteroperabilityCount"
61224
VALUE_ITEM
UINT16
<n>
1
FALSE
Interoperability Entity level 0
...
Interoperability Entity level <n> - 1
"APP2"
0xFFE2
LEVEL_END
0
NULL
0
TRUE

Interoperability Entity level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"InteroperabilityEntity"
<Ind.>
LEVEL_START
0
NULL
0
TRUE
"EntitySize"
<Ind.>
VALUE_ITEM
UINT32
0xFFFFFFFF for Storage or
<Variable> for Stream
1
FALSE
"DefaultValue"
<Ind.>
VALUE_ITEM
UINT8
"FPXR"
4
FALSE
"Storage/StreamName"
<Ind.>
VALUE_ITEM
RAW_DATA
<Unicode name>
<Variable>
FALSE
The next item is present only if "EntitySize" item value is equal 0xFFFFFFFF (Storage)
"EntityClassID"
<Ind.>
VALUE_ITEM
RAW_DATA
16
FALSE
"InteroperabilityEntity"
<Ind.>
LEVEL_END
0
NULL
0
TRUE

FPXR Data Stream APP2 marker segment

Name
Id
Type
Value Type
Value
Value Length
Read Only
"APP2"
0xFFE2
LEVEL_START
0
NULL
0
TRUE
"APP2_DATASIZE"
60226
VALUE_ITEM
UINT16
1
TRUE
"FPXR_HEADER"
61221
VALUE_ITEM
STRING
"FPXR"
4
FALSE
"FPXRVersion"
61222
VALUE_ITEM
UINT8
1
FALSE
"FPXRExtensionID"
61223
VALUE_ITEM
UINT8
"2"
1
FALSE
"FPXRIndexToContentsList"
61225
VALUE_ITEM
UINT16
<Ind.>
1
FALSE
"FPXROffsetToStream"
61226
VALUE_ITEM
UINT32
1
FALSE
"FPXRStreamData"
61227
VALUE_ITEM
RAW_DATA
<Variable>
FALSE
"APP2"
0xFFE2
LEVEL_END
0
NULL
0
TRUE

<Ind.> is pointer to appropriate "InteroperabilityEntity" of FPXR Contents List APP2 marker segment. <Ind.> value is between 0 and <n> - 1(<n> is the "FPXRInteroperabilityCount" item value of FPXR Contents List APP2 marker segment).

The other FPXR APP2 marker segment

Name
Id
Type
Value Type
Value
Value Length
Read Only
"APP2"
0xFFE2
LEVEL_START
0
NULL
0
TRUE
"APP2_DATASIZE"
60226
VALUE_ITEM
UINT16
1
TRUE
"FPXR_HEADER"
61221
VALUE_ITEM
STRING
"FPXR"
4
FALSE
"FPXRVersion"
61222
VALUE_ITEM
UINT8
1
FALSE
"FPXRExtensionID"
61223
VALUE_ITEM
UINT8
More than "2"
1
FALSE
"FPXRData"
61228
VALUE_ITEM
RAW_DATA
<Variable>
FALSE
"APP2"
0xFFE2
LEVEL_END
0
NULL
0
TRUE

EXIF-JPEG and EXIF-FPX Metadata Item Name and ID constants

NOTE: Please see file metadata.h for the full list of EXIF-JPEG and EXIF APP2 Marker segment Metadata Item Name and Item Id constants.


CIFF Non-Image Data Structure

CIFF metadata is similar to EXIF-TIFF, but it uses multiple nested IFDs, structured as a tree.

Brief information on CIFF metadata levels is provided in the set of tables below.

NOTE: Please see file metadata.h for the full list of CIFF Metadata Item Name and Item Id constants.

CIFF level

Name
Id
Type
"CIFF"
IG_FORMAT_CIFF
LEVEL_START
ImageProps level
CIFF root tags
"CIFF"
IG_FORMAT_CIFF
LEVEL_END

ImageProps level

Name
Id
Type
"ImageProps"
IGMDTAG_ID_CIFF_IMAGE_PROPS
LEVEL_START
ImageInfo level
ImageDescription level
CameraObject level
ShootingRecord level
MeasuredInfo level
ExifInformation level
ImageProps tags
"ImageProps"
IGMDTAG_ID_CIFF_IMAGE_PROPS
LEVEL_END

ImageInfo level

Name
Id
Type
"ImageInfo"
IGMDTAG_ID_CIFF_IMAGE_INFO
LEVEL_START
ImageInfo tags
"ImageInfo"
IGMDTAG_ID_CIFF_IMAGE_INFO
LEVEL_END

ImageDescription level

Name
Id
Type
"ImageDescription"
IGMDTAG_ID_CIFF_IMAGE_DESCRIPTION
LEVEL_START
ImageDescription tags
"ImageDescription"
IGMDTAG_ID_CIFF_IMAGE_DESCRIPTION
LEVEL_END

CameraObject level

Name
Id
Type
"CameraObject"
IGMDTAG_ID_CIFF_CAMERA_OBJECT
LEVEL_START
CameraSpecification level
CameraObject tags
"CameraObject"
IGMDTAG_ID_CIFF_CAMERA_OBJECT
LEVEL_END

ShootingRecord level

Name
Id
Type
"ShootingRecord"
IGMDTAG_ID_CIFF_SHOOTING_RECORD
LEVEL_START
ShootingRecord tags
"ShootingRecord"
IGMDTAG_ID_CIFF_SHOOTING_RECORD
LEVEL_END

MeasuredInfo level

Name
Id
Type
"MeasuredInfo"
IGMDTAG_ID_CIFF_MEASURED_INFO
LEVEL_START
MeasuredInfo tags
"MeasuredInfo"
IGMDTAG_ID_CIFF_MEASURED_INFO
LEVEL_END

ExifInformation level

Name
Id
Type
"ExifInformation"
IGMDTAG_ID_CIFF_EXIF_INFORMATION
LEVEL_START
FocalLength level
CanonShotInfo level
CanonCameraSettings level
SensorInfo level
CanonCustomFunctions level
CanonPictureInfo level
ExifInformation tags
"ExifInformation"
IGMDTAG_ID_CIFF_EXIF_INFORMATION
LEVEL_END

CameraSpecification level

Name
Id
Type
"CameraSpecification"
IGMDTAG_ID_CIFF_CAMERA_SPECIFICATION
LEVEL_START
CameraSpecification tags
"CameraSpecification"
IGMDTAG_ID_CIFF_CAMERA_SPECIFICATION
LEVEL_END

FocalLength level

Name
Id
Type
"FocalLength"
IGMDTAG_NAME_CIFF_FOCAL_LENGTH
LEVEL_START
FocalLength tags
"FocalLength"
IGMDTAG_NAME_CIFF_FOCAL_LENGTH
LEVEL_END

CanonShotInfo level

Name
Id
Type
"CanonShotInfo"
IGMDTAG_NAME_CIFF_CANON_SHOT_INFO
LEVEL_START
CanonShotInfo tags
"CanonShotInfo"
IGMDTAG_NAME_CIFF_CANON_SHOT_INFO
LEVEL_END

CanonCameraSettings level

Name
Id
Type
"CanonCameraSettings"
IGMDTAG_NAME_CIFF_CANON_CAMERA_SETTINGS
LEVEL_START
CanonCameraSettings tags
"CanonCameraSettings"
IGMDTAG_NAME_CIFF_CANON_CAMERA_SETTINGS
LEVEL_END

SensorInfo level

Name
Id
Type
"SensorInfo"
IGMDTAG_NAME_CIFF_SENSOR_INFO
LEVEL_START
SensorInfo tags
"SensorInfo"
IGMDTAG_NAME_CIFF_SENSOR_INFO
LEVEL_END

CanonCustomFunctions level

Name
Id
Type
"CanonCustomFunctions"
IGMDTAG_NAME_CIFF_CANON_CUSTOM_FUNCTIONS
LEVEL_START
CanonCustomFunctions tags
"CanonCustomFunctions"
IGMDTAG_NAME_CIFF_CANON_CUSTOM_FUNCTIONS
LEVEL_END

CanonPictureInfo level

Name
Id
Type
"CanonPictureInfo"
IGMDTAG_NAME_CIFF_CANON_PICTURE_INFO
LEVEL_START
CanonPictureInfo tags
"CanonPictureInfo"
IGMDTAG_NAME_CIFF_CANON_PICTURE_INFO
LEVEL_END


IPTC Non-Image Data Structure

IPTC, International Press and Telecommunications Council Standards have been created for different type information exchanging.

IPTC is not file format. It can be stored within the JPEG, TIFF, EXIF-JPEG and EXIF-TIFF image file as Adobe Photoshop Image Resource (see Photoshop Image Resource metadata structure). In TIFF and EXIF-TIFF files the IPTC data is stored in TIFF tag with Id = 34377 (see TIFF Non-Image Data Structure for metadata structure of the tag). In JPEG and EXIF-JPEG files the IPTC data is stored in Photoshop APP13 marker segment (see JPEG Non-Image Data Structure).

The ImageGear IPTC metadata structure is framed in two levels:

  • IPTC level containing all IPTC data
  • Record level containing value items of a record.

IPTC level

Name
Id
Type
ValueType
Value
Value Length
Read Only
"IPTC"
0x1C00
LEVEL_START
UNDEFINED
NULL
0
TRUE
Record level 1
...
Record level n
"IPTC"
0x1C00
LEVEL_END
UNDEFINED
NULL
0
TRUE

All items between items with Name "IPTC" and Id 0x1C00 (Type LEVEL_START and LEVEL_END) are interpreted as IPTC data. If during sending data from application level to filter level the first item is omitted the data will not be interpreted and saved.

Record level

Name
Id
Type
ValueType
Value
Value Length
Read Only
"IPTC_RECORD"
<Record#>
LEVEL_START
UNDEFINED
NULL
0
TRUE
Dataset value item
...
Dataset value item
"IPTC_RECORD"
<Record#>
LEVEL_END
UNDEFINED
NULL
0
TRUE

The <Record#> is identifier of IPTC record. Its value is the number of appropriate IPTC record described in IPTC - NAA IIM4 specification. Record levels must follow in numerical order within IPTC level.

Dataset value item

Name
Id
Type
ValueType
Value
Value Length
Read Only
<Dataset name>
<Dataset Id>
VALUE_ITEM
<Value Type>
<Data>
<Value Length>
FALSE

The available <Dataset name>, <Dataset Id>, <Value Length> and <Value Type> values are described below for each IPTC record according to IPTC-NAA IIM4 specification. Dataset value item can follow in any order within appropriate record level.

Dataset value items description for IPTC Envelope Record (Record #1)

Item Identifier
Item Name
Value Type
Max. Value Length
(for String last NULL is not counted)
0
"ModelVersion"
AT_TID_WORD
1
5
"Destination"
AT_TID_STRING
1024
20
"FileFormat"
AT_TID_WORD
1
22
"FileFormatVersion"
AT_TID_WORD
1
30
"ServiceIdentifier"
AT_TID_STRING
10
40
"EnvelopeNumber"
AT_TID_STRING
8
50
"ProductID"
AT_TID_STRING
32
60
"EnvelopePriority"
AT_TID_STRING
1
70
"DateSent"
AT_TID_STRING
8
80
"TimeSent"
AT_TID_STRING
11
90
"CodedCharacterSet"
AT_TID_STRING
32
100
"UNO"
AT_TID_STRING
80
120
"ARMIdentifier"
AT_TID_WORD
1
122
"ARMVersion"
AT_TID_WORD
1

Dataset value items description for IPTC Application Record (Record #2)

Item Identifier
Item Name
Value Type
Max. Value Length
(for String last NULL is not counted)
0
"RecordVersion"
AT_TID_WORD
1
3
"ObjectTypeReference"
AT_TID_STRING
67
4
"ObjectAttributeReference"
AT_TID_STRING
68
5
"ObjectName"
AT_TID_STRING
64
7
"EditStatus"
AT_TID_STRING
64
8
"EditorialUpdate"
AT_TID_STRING
2
10
"Urgency"
AT_TID_STRING
1
12
"SubjectReference"
AT_TID_STRING
236
15
"Category"
AT_TID_STRING
3
20
"SupplementalCategory"
AT_TID_STRING
32
22
"FixtureIdentifier"
AT_TID_STRING
32
25
"Keywords"
AT_TID_STRING
64
26
"ContentLocationCode"
AT_TID_STRING
3
27
"ContentLocationName"
AT_TID_STRING
64
30
"ReleaseDate"
AT_TID_STRING
8
35
"ReleaseTime"
AT_TID_STRING
11
37
"ExpirationDate"
AT_TID_STRING
8
38
"ExpirationTime"
AT_TID_STRING
11
40
"SpecialInstructions"
AT_TID_STRING
256
42
"ActionAdvised"
AT_TID_STRING
2
45
"ReferenceService"
AT_TID_STRING
10
47
"ReferenceDate"
AT_TID_STRING
8
50
"ReferenceNumber"
AT_TID_STRING
8
55
"DateCreated"
AT_TID_STRING
8
60
"TimeCreated"
AT_TID_STRING
11
62
"DigitalCreationDate"
AT_TID_STRING
8
63
"DigitalCreationTime"
AT_TID_STRING
11
65
"OriginatingProgram"
AT_TID_STRING
32
70
"ProgramVersion"
AT_TID_STRING
10
75
"ObjectCycle"
AT_TID_STRING
1
80
"By-line"
AT_TID_STRING
32
85
"By-lineTitle"
AT_TID_STRING
32
90
"City"
AT_TID_STRING
32
92
"Sublocation"
AT_TID_STRING
32
95
"Province/State"
AT_TID_STRING
32
100
"Country/
PrimaryLocationCode"
AT_TID_STRING
3
101
"Country/
PrimaryLocationName"
AT_TID_STRING
64
103
"OriginalTransmission
Reference"
AT_TID_STRING
32
105
"Headline"
AT_TID_STRING
256
110
"Credit"
AT_TID_STRING
32
115
"Source"
AT_TID_STRING
32
116
"CopyrightNotice"
AT_TID_STRING
128
118
"Contact"
AT_TID_STRING
128
120
"Caption/Abstract"
AT_TID_STRING
2000
122
"Writer/Editor"
AT_TID_STRING
32
125
"RasterizedCaption"
AT_TID_BYTE
7360
130
"ImageType"
AT_TID_STRING
2
131
"ImageOrientation"
AT_TID_STRING
1
135
"LanguageIdentifier"
AT_TID_STRING
3
150
"AudioType"
AT_TID_STRING
2
151
"AudioSamplingRate"
AT_TID_STRING
6
152
"AudioSamplingResolution"
AT_TID_STRING
2
153
"AudioDuration"
AT_TID_STRING
6
154
"AudioOutcue"
AT_TID_STRING
64
200
"ObjectDataPreview
FileFormat"
AT_TID_WORD
1
201
"ObjectDataPreview
FileFormatVersion"
AT_TID_WORD
1
202
"ObjectDataPreviewData"
AT_TID_BYTE
Undefined

Dataset value items description for IPTC Digital News Photo Parameter Record (Record #3)

Item Identifier
Item Name
Value Type
Max. Value Length (for String last NULL is not counted)
0
"RecordVersion"
AM_TID_TXT_UINT16
1
10
"PictureNumber"
AM_TID_RAW_DATA
16
20
"PixelsPerLine"
AM_TID_TXT_UINT16
1
30
"NumberOfLine"
AM_TID_TXT_UINT16
1
40
"PixelSizeInScanningDirection"
AM_TID_TXT_UINT16
1
50
"PixelSizePerpendicularTo
ScanningDirection"
AM_TID_TXT_UINT16
1
55
"SupplementType"
AM_TID_TXT_UINT8
1
60
"ColourRepresentation"
AM_TID_TXT_UINT8
2
64
"InterchangeColourSpace"
AM_TID_TXT_UINT8
1
65
"ColourSequence"
AM_TID_TXT_UINT8
4
66
"ICCInputColourProfile"
AM_TID_RAW_DATA
Undefined
70
"ColourCalibrationMatrixTable"
AM_TID_RAW_DATA
Undefined
80
"LookupTable"
AM_TID_RAW_DATA
131072
84
"NumberOfIndexEntries"
AM_TID_TXT_UINT16
1
85
"ColourPalette"
AM_TID_RAW_DATA
Undefined
86
"NumberOfBitsPerSample"
AM_TID_TXT_UINT8
1
90
"SamplingStructure"
AM_TID_TXT_UINT8
1
100
"ScanningDirection"
AM_TID_TXT_UINT8
1
102
"ImageRotation"
AM_TID_TXT_UINT8
1
110
"DataCompressionMethod"
AM_TID_RAW_DATA
4
120
"QuantisationMethod"
AM_TID_TXT_UINT8
1
125
"EndPoints"
AM_TID_TXT_UINT8
Undefined
130
"ExcursionTolerance"
AM_TID_TXT_UINT8
1
135
"BitsPerComponent"
AM_TID_TXT_UINT8
Undefined
140
"MaximumDensityRange"
AM_TID_TXT_UINT16
1
145
"GammaCompensatedValue"
AM_TID_TXT_UINT16
1

Dataset value items description for IPTC Pre-Object Descriptor Record (Record #7

Item Identifier
Item Name
Value Type
Max. Value Length (for String last NULL is not counted)
10
"SizeMode"
AM_TID_TXT_UINT8
1
20
"MaxSubfileSize"
AM_TID_TXT_UINT8 or
AM_TID_TXT_UINT16 or
AM_TID_TXT_UINT32
1
90
"ObjectDataSizeAnnounced"
AM_TID_TXT_UINT8 or
AM_TID_TXT_UINT16 or
AM_TID_TXT_UINT32
1
95
"MaximumObjectDataSize"
AM_TID_TXT_UINT8 or
AM_TID_TXT_UINT16 or
AM_TID_TXT_UINT32
1

Dataset value items description for IPTC Object Record (Record #8)

Item Identifier
Item Name
Value Type
Max. Value Length (for String last NULL is not counted)
10
"Subfile"
AM_TID_RAW_DATA
Undefined

Dataset value items description for IPTC Post-Object Descriptor Record (Record #9)

Item Identifier
Item Name
Value Type
Max. Value Length (for String last NULL is not counted)
10
"ConfirmedObjectDataSize"
AM_TID_TXT_UINT8 or
AM_TID_TXT_UINT16 or
AM_TID_TXT_UINT32
1

Callback required for writing IPTC metadata items

All IPTC metadata items can be written using LPAFT_IG_METAD_ITEM_ADD_CB callback only.

IPTC Metadata Item Name and ID constants

NOTE: Please see file metadata.h for the full list of IPTC Metadata Item Name and Item Id constants.


PNG Non-Image Data Structure

There are 2 main PNG metadata levels:

  • PNG metadata level
  • PNG chunks levels

PNG metadata level

All items between items with Name "PNG" and Id IG_FORMAT_PNG (Type LEVEL_START and LEVEL_END) are interpreted as PNG data. If during sending data from application level to filter level the first item is omitted the data will not be interpreted and saved.

Name
Id
Type
Value Type
Value
Value Length
Read Only
"PNG"
IG_FORMAT_PNG
LEVEL_START
0
NULL
0
TRUE
PNG chunks levels
"PNG"
IG_FORMAT_PNG
LEVEL_END
0
NULL
0
TRUE

PNG chunks levels

There are such PNG non-image chunk levels supported by ImageGear:

  • PNG header chunk metadata
  • Physical dimension chunk metadata
  • Transparency chunk metadata
  • Gamma chunk metadata
  • Primary chromaticities chunk metadata
  • sRGB chunk metadata
  • ICC profile chunk metadata
  • Background chunk metadata
  • Significant bits chunk metadata
  • Suggested palette chunk metadata
  • Palette histogram chunk metadata
  • Modified time chunk metadata
  • Text chunk metadata
  • Compressed textual data chunk metadata
  • International textual data chunk metadata
  • Calibration of pixel values chunk metadata
  • Physical scale chunk metadata
  • GIF application extension chunk metadata
  • GIF Graphic Control Extension chunk metadata
  • Image offset chunk metadata
  • The rest chunk metadata

PNG header chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"IHDR"
0x49484452
LEVEL_START
0
NULL
0
TRUE
"Width"
0x49484452
VALUE_ITEM
UINT32
1
TRUE
"Height"
0x49484452
VALUE_ITEM
UINT32
1
TRUE
"BitDepth"
0x49484452
VALUE_ITEM
UINT8
1
TRUE
"ColorType"
0x49484452
VALUE_ITEM
UINT8
1
TRUE
"CompressionType"
0x49484452
VALUE_ITEM
UINT8
1
TRUE
"FilterType"
0x49484452
VALUE_ITEM
UINT8
1
TRUE
"InterlaceType"
0x49484452
VALUE_ITEM
UINT8
1
TRUE
"IHDR"
0x49484452
LEVEL_END
0
NULL
0
TRUE

Physical dimension chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"pHYs"
0x70485973
LEVEL_START
0
NULL
0
TRUE
"XAxis"
0x70485973
VALUE_ITEM
UINT32
1
FALSE
"YAxis"
0x70485973
VALUE_ITEM
UINT32
1
FALSE
"UnitSpecifier"
0x70485973
VALUE_ITEM
UINT8
1
FALSE
"pHYs"
0x70485973
LEVEL_END
0
NULL
0
TRUE

Transparency chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"tRNS"
0x74524e53
VALUE_ITEM
UINT8 or
UINT16
Variable
FALSE

Gamma chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"gAMA"
0x67414d41
VALUE_ITEM
UINT32
1
FALSE

Primary chromaticities chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"cHRM"
0x6348524d
LEVEL_START
0
NULL
0
TRUE
"WhitePoint"
0x6348524d
LEVEL_START
0
NULL
0
TRUE
"x"
0x6348524d
VALUE_ITEM
UINT32
1
FALSE
"y"
0x6348524d
VALUE_ITEM
UINT32
1
FALSE
"WhitePoint"
0x6348524d
LEVEL_END
0
NULL
0
TRUE
"Red"
0x6348524d
LEVEL_START
0
NULL
0
TRUE
"x"
0x6348524d
VALUE_ITEM
UINT32
1
FALSE
"y"
0x6348524d
VALUE_ITEM
UINT32
1
FALSE
"Red"
0x6348524d
LEVEL_END
0
NULL
0
TRUE
"Green"
0x6348524d
LEVEL_START
0
NULL
0
TRUE
"x"
0x6348524d
VALUE_ITEM
UINT32
1
FALSE
"y"
0x6348524d
VALUE_ITEM
UINT32
1
FALSE
"Green"
0x6348524d
LEVEL_END
0
NULL
0
TRUE
"Blue"
0x6348524d
LEVEL_START
0
NULL
0
TRUE
"x"
0x6348524d
VALUE_ITEM
UINT32
1
FALSE
"y"
0x6348524d
VALUE_ITEM
UINT32
1
FALSE
"Blue"
0x6348524d
LEVEL_END
0
NULL
0
TRUE
"cHRM"
0x6348524d
LEVEL_END
0
NULL
0
TRUE

sRGB chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"sRGB"
0x73524742
VALUE_ITEM
UINT32
1
FALSE

ICC profile chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"iCCP"
0x70485973
LEVEL_START
0
NULL
0
TRUE
"ProfileName"
0x70485973
VALUE_ITEM
STRING
Variable
FALSE
"ProfileData"
0x70485973
VALUE_ITEM
RAW_DATA
Variable
FALSE
"iCCP"
0x70485973
LEVEL_END
0
NULL
0
TRUE

Background chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"bKGD"
0x624b4744
VALUE_ITEM
UINT8 or UINT16
Variable
FALSE

Significant bits chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"sBIT"
0x73424954
VALUE_ITEM
UINT8
Variable
FALSE

Suggested palette chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"sPLT"
0x73504c54
LEVEL_START
0
NULL
0
TRUE
"PaletteName"
0x73504c54
VALUE_ITEM
STRING
Variable
TRUE
"SampleDepth"
0x73504c54
VALUE_ITEM
UINT8
1
FALSE
"PaletteEntryCount"
0x73504c54
VALUE_ITEM
UINT16
<N>
1
FALSE
Palette entry level 0
...
Palette entry level n
"sPLT"
0x70485973
LEVEL_END
0
NULL
1
FALSE

Palette entry level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"PaletteEntry"
<Entry No.>
LEVEL_START
0
NULL
0
TRUE
"Red"
<Entry No.>
VALUE_ITEM
UINT8 or UINT16
1
FALSE
"Green"
<Entry No.>
VALUE_ITEM
UINT8 or UINT16
1
FALSE
"Blue"
<Entry No.>
VALUE_ITEM
UINT8 or UINT16
1
FALSE
"Alpha"
<Entry No.>
VALUE_ITEM
UINT8 or UINT16
1
FALSE
"Frequency"
<Entry No.>
VALUE_ITEM
UINT16
1
FALSE
"PaletteEntry"
<Entry No.>
LEVEL_END
0
NULL
0
TRUE

Palette histogram chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"hIST"
0x68495354
VALUE_ITEM
UINT16
Variable
FALSE

Modified time chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"tIME"
0x74494d45
LEVEL_START
0
NULL
0
TRUE
"Year"
0x74494d45
VALUE_ITEM
UINT16
1
FALSE
"Month"
0x74494d45
VALUE_ITEM
UINT8
1
FALSE
"Day"
0x74494d45
VALUE_ITEM
UINT8
1
FALSE
"Hour"
0x74494d45
VALUE_ITEM
UINT8
1
FALSE
"Minute"
0x74494d45
VALUE_ITEM
UINT8
1
FALSE
"Second"
0x74494d45
VALUE_ITEM
UINT8
1
FALSE
"tIME"
0x74494d45
LEVEL_END
0
NULL
0
TRUE

Text chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"tEXt"
0x74455874
LEVEL_START
0
NULL
0
TRUE
"Keyword"
0x74455874
VALUE_ITEM
STRING
Variable
FALSE
"Text"
0x74455874
VALUE_ITEM
STRING
Variable
FALSE
"tEXt"
0x74455874
LEVEL_END
0
NULL
0
TRUE

Compressed textual data chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"zTXt"
0x7a545874
LEVEL_START
0
NULL
0
TRUE
"Keyword"
0x7a545874
VALUE_ITEM
STRING
Variable
FALSE
"CompressionMethod"
0x7a545874
VALUE_ITEM
UINT8
1
FALSE
"Text"
0x7a545874
VALUE_ITEM
STRING
Variable
FALSE
"zTXt"
0x7a545874
LEVEL_END
0
NULL
0
TRUE

International textual data chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"zTXt"
0x69545874
LEVEL_START
0
NULL
0
TRUE
"Keyword"
0x69545874
VALUE_ITEM
STRING
Variable
FALSE
"CompressionFlag"
0x69545874
VALUE_ITEM
BOOL
"CompressionMethod"
0x69545874
VALUE_ITEM
UINT8
1
FALSE
"LanguageTag"
0x69545874
VALUE_ITEM
STRING
"TranslatedKeyword"
0x69545874
VALUE_ITEM
RAW_DATA
"Text"
0x69545874
VALUE_ITEM
RAW_DATA
Variable
FALSE
"zTXt"
0x69545874
LEVEL_END
0
NULL
0
TRUE

Calibration of pixel values chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"pCAL"
0x7043414c
LEVEL_START
0
NULL
0
TRUE
"CalibrationName"
0x7043414c
VALUE_ITEM
STRING
Variable
FALSE
"OriginalZero(x0)"
0x7043414c
VALUE_ITEM
INT32
1
FALSE
"OriginalMax(x1)"
0x7043414c
VALUE_ITEM
INT32
1
FALSE
"EquationType"
0x7043414c
VALUE_ITEM
UINT8
1
FALSE
"NumberOfParameters"
0x7043414c
VALUE_ITEM
UINT8
<N>
Variable
FALSE
"UnitName"
0x7043414c
VALUE_ITEM
STRING
Variable
FALSE
"CalibrationParameter"
0
VALUE_ITEM
STRING
Variable
FALSE
...
"CalibrationParameter"
<N> - 1
VALUE_ITEM
STRING
Variable
FALSE
"pCAL"
0x7043414c
LEVEL_END
0
NULL
0
TRUE

Physical scale chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"sCAL"
0x7343414c
LEVEL_START
0
NULL
0
TRUE
"UnitSpecifier"
0x7343414c
VALUE_ITEM
UINT8
1
FALSE
"PixelWidth"
0x7343414c
VALUE_ITEM
STRING
Variable
FALSE
"PixelHeigt"
0x7343414c
VALUE_ITEM
STRING
Variable
FALSE
"sCAL"
0x7343414c
LEVEL_END
0
NULL
0
TRUE

GIF application extension chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"gIFx"
0x67494678
LEVEL_START
0
NULL
0
TRUE
"ApplicationIdentifier"
0x67494678
VALUE_ITEM
STRING
Variable
FALSE
"AuthenticationCode"
0x67494678
VALUE_ITEM
UINT8
1
FALSE
"ApplicationData"
0x67494678
VALUE_ITEM
RAW_DATA
Variable
FALSE
"gIFx"
0x67494678
LEVEL_END
0
NULL
0
TRUE

GIF Graphic Control Extension chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"gIFg"
0x67494674
LEVEL_START
0
NULL
0
TRUE
"DisposalMethod"
0x67494674
VALUE_ITEM
UINT8
1
FALSE
"UserInputFlag"
0x67494674
VALUE_ITEM
UINT8
1
FALSE
"DelayTime"
0x67494674
VALUE_ITEM
UINT16
1
FALSE
"gIFg"
0x67494674
LEVEL_END
0
NULL
0
TRUE

Image offset chunk metadata

Name
Id
Type
Value Type
Value
Value Length
Read Only
"oFFs"
0x6f464673
LEVEL_START
0
NULL
0
TRUE
"XPosition"
0x6f464673
VALUE_ITEM
UINT32
1
FALSE
"YPosition"
0x6f464673
VALUE_ITEM
UINT32
1
FALSE
"UnitSpecifier"
0x6f464673
VALUE_ITEM
UINT8
1
FALSE
"oFFs"
0x6f464673
LEVEL_END
0
NULL
0
TRUE

The rest chunk metadata

The rest chunk data are passed as raw data

Name
Id
Type
Value Type
Value
Value Length
Read Only
<Chunk Name>
<Chunk ID>
VALUE_ITEM
RAW_DATA
Variable
FALSE

<Chunk Name> is a string representation of the chunk type value.

<Chunk ID> is a binary representation of the chunk type value.

Callback required for writing PNG metadata items

Value of these metadata items can be changed using LPAFT_IG_METAD_ITEM_SET_CB callback only:

Item Name
Item Id
Physical dimension chunk metadata
"XAxis"
0x70485973
"YAxis"
0x70485973
"UnitSpecifier"
0x70485973

The rest PNG metadata items can be written using LPAFT_IG_METAD_ITEM_ADD_CB callback only.

PNG Metadata Item Name and ID constants

NOTE: Please see file metadata.h for the full list of PNG Metadata Item Name and Item Id constants.


GIF Non-image Data Structure

GIF file format is complex and has different non-image data that can be stored before and after an image data. The GIF metadata design allows to read/write any GIF non-image data and prevents from misunderstanding with GIF extensions storing order.

The following metadata are always saved before an image data:

  • GIF Logical Screen Descriptor level
  • GIF Image Descriptor level
  • GIF Global Color Table level
  • GIF Local Color Table level

The metadata of GIF extensions that are inside GIF Extensions After Image level (between items with Name "AfterImageExtensions" and Id 0xFFF (Type LEVEL_START and LEVEL_END)) are saved after an image data.

All other GIF Extensions Metadata are saved before an image data.

NOTE: You can work with GIF metadata only when the ImageGear GIF/TIFF-LZW Component is attached to the core ImageGear module.

GIF metadata level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"GIF"
IG_FORMAT_GIF
LEVEL_START
0
NULL
0
TRUE
GIF header level
GIF Logical Screen Descriptor level
GIF Image Descriptor level
optional Global and/or Local Color Tables and
optional GIF Extensions levels (extensions before image)
"GIF"
IG_FORMAT_GIF
LEVEL_END
0
NULL
0
TRUE

All items between items with Name "GIF" and Id IG_FORMAT_GIF (Type LEVEL_START and LEVEL_END) are interpreted as GIF data. If during sending data from application level to filter level the first item is omitted the data will not be interpreted and saved.

GIF header level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"GIFHeader"
0x10
LEVEL_START
0
NULL
0
TRUE
"Signature"
0x101
VALUE_ITEM
STRING
"GIF"
3
TRUE
"Version"
0x102
VALUE_ITEM
STRING
3
TRUE
"GIFHeader"
0x10
LEVEL_END
0
NULL
0
TRUE

GIF Logical Screen Descriptor level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"LogicalScreenDescriptor"
0x20
LEVEL_START
0
NULL
0
TRUE
"LogicalScreenWidth"
0x201
VALUE_ITEM
UINT16
1
FALSE
"LogicalScreenHeight"
0x202
VALUE_ITEM
UINT16
1
FALSE
"Fields"
0x205
LEVEL_START
0
NULL
0
TRUE
"GlobalColorTableFlag"
0x206
VALUE_ITEM
BOOL
1
FALSE
"ColorResolution"
0x207
VALUE_ITEM
UINT8
1
FALSE
"SortFlag"
0x208
VALUE_ITEM
BOOL
1
FALSE
"GlobalColorTableSize"
0x209
VALUE_ITEM
UINT8
1
FALSE
"Fields"
0x205
LEVEL_END
0
NULL
0
TRUE
"BackgroundColorIndex"
0x203
VALUE_ITEM
UINT8
FALSE
"PixelAspectRatio"
0x204
VALUE_ITEM
UINT8
FALSE
"LogicalScreenDescriptor"
0x20
LEVEL_END
0
NULL
0
TRUE

GIF Global Color Table level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"GlobalColorTable"
0x30
VALUE_ITEM
RAW_DATA
Variable
TRUE

GIF Image Descriptor level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"ImageDescriptor"
0x2C
LEVEL_START
0
NULL
0
TRUE
"ImageLeftPosi tion"
0x2C1
VALUE_ITEM
UINT16
1
FALSE
"ImageTopPosition"
0x2C2
VALUE_ITEM
UINT16
1
FALSE
"ImageWidth"
0x2C3
VALUE_ITEM
1
FALSE
"ImageHeight"
0x2C4
VALUE_ITEM
1
FALSE
"Fields"
0x2C5
LEVEL_START
0
NULL
0
TRUE
"LocalColorTableFlag"
0x2C6
VALUE_ITEM
BOOL
1
FALSE
"InterlaceFlag"
0x2C7
VALUE_ITEM
BOOL
1
FALSE
"SortFlag"
0x2C8
VALUE_ITEM
BOOL
1
FALSE
"LocalColorTableSize"
0x2C9
VALUE_ITEM
UINT8
1
FALSE
"Fields"
0x2C5
LEVEL_END
0
NULL
0
TRUE
"ImageDescriptor"
0x2C
LEVEL_END
0
NULL
0
TRUE

GIF Local Color Table level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"LocalColorTable"
0x40
VALUE_ITEM
RAW_DATA
Variable
TRUE

GIF Extensions Metadata

GIF Graphic Control Extension level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"GraphicControlExtension"
0xF9
LEVEL_START
0
NULL
0
TRUE
"Fields"
0xF91
LEVEL_START
0
NULL
0
TRUE
"DisposalMethod"
0xF92
VALUE_ITEM
UINT8
1
FALSE
"UserInputFlag"
0xF93
VALUE_ITEM
BOOL
1
FALSE
"TransparentColorFlag"
0xF94
VALUE_ITEM
BOOL
1
FALSE
"Fields"
0xF91
LEVEL_END
0
NULL
0
TRUE
"DelayTime"
0xF95
VALUE_ITEM
UINT16
1
FALSE
"TransparentColorIndex"
0xF96
VALUE_ITEM
UINT8
1
FALSE
"GraphicControlExtension"
0xF9
LEVEL_END
0
NULL
0
TRUE

GIF Comment Extension level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"CommentExtension"
0xFE
VALUE_ITEM
STRING
Variable
TRUE

GIF Application Extension level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"ApplicationExtension"
0xFF
LEVEL_START
0
NULL
0
TRUE
"ApplicationIdentifier"
0xFF1
VALUE_ITEM
STRING
8
FALSE
"Appl.AuthenticationCode"
0xFF2
VALUE_ITEM
UINT8
4
FALSE
"ApplicationData"
0xFF3
VALUE_ITEM
RAW_DATA
Variable
FALSE
"ApplicationExtension"
0xFF
LEVEL_END
0
NULL
0
TRUE

GIF Plain Text Extension level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"PlainTextExtension"
0x01
LEVEL_START
0
NULL
0
TRUE
"TextGridLeftPosition"
0x11
VALUE_ITEM
UINT16
1
FALSE
"TextGridTopPosition"
0x12
VALUE_ITEM
UINT16
1
FALSE
"TextGridWidth"
0x13
VALUE_ITEM
UINT16
1
FALSE
"TextGridHeight"
0x14
VALUE_ITEM
UINT16
1
FALSE
"CharacterCellWidth"
0x15
VALUE_ITEM
UINT8
1
FALSE
"CharacterCellHeight"
0x16
VALUE_ITEM
UINT8
1
FALSE
"TextForegroundColorIndex"
0x17
VALUE_ITEM
UINT8
1
FALSE
"TextBackgroundColorIndex"
0x18
VALUE_ITEM
UINT8
1
FALSE
"PlainTextData"
0x19
VALUE_ITEM
STRING
Variable
FALSE

GIF Extensions After Image level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"AfterImageExtensions"
0xFFF
LEVEL_START
0
NULL
0
TRUE
One or more GIF extension levels
"AfterImageExtensions"
0xFFF
LEVEL_END
0
NULL
0
TRUE

Callback required for writing GIF metadata items

The GIF Logical Screen Descriptor level and GIF Image Descriptor level metadata items can be written using LPAFT_IG_METAD_ITEM_SET_CB callback function.

Other GIF metadata can be written using LPAFT_IG_METAD_ITEM_ADD_CB callback function.

GIF Metadata Item Name and ID constants

NOTE: Please see file metadata.h for the full list of GIF Metadata Item Name and Item Id constants.


DCRAW Non-Image Data Structure

  • Common level
  • Format-specific level
  • Statistics

DCRAW level

Name
Id
Type
Value Type
Value
Value Length
Read Only
"Common"
IGMDTAG_ID_DCRAW_COMMON
LEVEL_START
0
NULL
0
TRUE
"EXIF"
IG_FORMAT_EXIF_TIFF
LEVEL_START
0
NULL
0
TRUE
"TIFF"
IG_FORMAT_TIF
LEVEL_START
0
NULL
0
TRUE
"CIFF"
IG_FORMAT_CIFF
LEVEL_START
0
NULL
0
TRUE
"Statistics"
IGMDTAG_ID_DCRAW_STATISTICS
LEVEL_START
0
NULL
0
TRUE

Common level

The Common sub-tree contains values that are common or useful for all raw files.

All values in the Common sub-tree have Type = VALUE_ITEM and are Read Only.

Name
Id
Description
AsShotNeutral
IGMDTAG_ID_DCRAW_ASSHOTNEUTRAL
Specifies the selected white balance at time of capture, encoded as the coordinates of a perfectly neutral color in linear reference space values.
BaselineExposure
IGMDTAG_ID_DCRAW_BASELINEEXPOSURE
Specifies baseline exposure of the camera, in EV units. Application may use this value to adjust exposure compensation for particular camera model.
BitsPerSample
IGMDTAG_ID_DCRAW_BITSPERSAMPLE
Bits per sample in the original raw image (before reconstruction)
BlackLevelRepeatDim
IGMDTAG_ID_DCRAW_BLACKLEVELREPEATDIM
This tag specifies repeat pattern size for the "BlackLevel" tag.
CalibrationIlluminant1
IGMDTAG_ID_DCRAW_CALIBRATIONILLUMINANT1
The illuminant used for ColorMatrix1 color conversion matrix. Allowed values are the same as allowed values for LightSource EXIF tag (see Exif specification).
CalibrationIlluminant2
IGMDTAG_ID_DCRAW_CALIBRATIONILLUMINANT1
The illuminant used for ColorMatrix2 color conversion matrix. Allowed values are the same as allowed values for LightSource EXIF tag (see Exif specification).
CFAPattern
IGMDTAG_ID_DCRAW_CFAPATTERN
This tag encodes the actual color filter array geometric pattern of the image sensor used to capture the single sensor color image.
CFARepeatPatternDim
IGMDTAG_ID_DCRAW_CFAREPEATPATTERNDIM
This tag encodes the number of pixels horizontally and vertically that are needed to uniquely define the repeat pattern of the color filter array.
ColorMatrix1
IGMDTAG_ID_DCRAW_COLORMATRIX1
Conversion matrix from XYZ to camera colorspace, for illuminant specified by CalibrationIlluminant1 tag. Matrix is stored in row scan order.
ColorMatrix2
IGMDTAG_ID_DCRAW_COLORMATRIX2
Conversion matrix from XYZ to camera colorspace, for illuminant specified by CalibrationIlluminant2 tag. Matrix is stored in row scan order.
ColorPlanes
IGMDTAG_ID_DCRAW_COLORPLANES
Number of colors in the CFA pattern
ImageHeight
IGMDTAG_ID_DCRAW_IMAGEHEIGHT
Image height after that masked pixels were trimmed out
ImageWidth
IGMDTAG_ID_DCRAW_IMAGEWIDTH
Image width after that masked pixels were trimmed out
Make
IGMDTAG_ID_DCRAW_MAKE
Name of the camera manufacturer
Model
IGMDTAG_ID_DCRAW_MODEL
Name of the camera model
PhotometricInterpretation
IGMDTAG_ID_DCRAW_PHOTOMETRICINTERPRETATION
TIF_PHOTO_CFA, TIF_PHOTO_RGB
RawHeight
IGMDTAG_ID_DCRAW_RAWHEIGHT
Raw Image Height, including masked pixels
RawLeft
IGMDTAG_ID_DCRAW_RAWLEFT
X coordinate of first column of non-masked pixels
RawTop
IGMDTAG_ID_DCRAW_RAWTOP
Y coordinate of first row of non-masked pixels
RawWidth
IGMDTAG_ID_DCRAW_RAWWIDTH
Raw Image Width, including masked pixels
SamplesPerPixel
IGMDTAG_ID_DCRAW_SAMPLESPERPIXEL
Number of samples per pixel in the original image, before reconstruction
TimeStamp
IGMDTAG_ID_DCRAW_TIMESTAMP
Time stamp
UniqueCameraModel
IGMDTAG_ID_DCRAW_UNIQUECAMERAMODEL
Unique, non-localized name for the camera model that created the image in the raw file.
WhiteLevel
IGMDTAG_ID_DCRAW_WHITELEVEL
Image pixel value that corresponds to fully saturated encoding level.

Format-specific level

This level includes format-specific metadata that is found in the image (EXIF, TIFF or CIFF). See corresponding sections for structure of metadata for these formats.

Statistics

This section contains data which is collected during image loading, rather than obtained from image's header or metadata. Only image loading functions, such as IG_fltr_load_file generate this section. Header reading functions, such as IG_info_get, do not generate it.

For some cameras ImageGear uses predefined values for BlackLevel, so they are not calculated from pixel data. In this case, ImageGear also places BlackLevel tag to Statistics section, rather than in Common section, for uniformity reasons.

The following tags can be present in the Statistics section:

Name
ID
Description
BlackLevelRepeatDim
IGMDTAG_ID_DCRAW_BLACKLEVELREPEATDIM
This tag specifies repeat pattern size for the "BlackLevel" tag.
BlackLevel
IGMDTAG_ID_DCRAW_BLACKLEVEL
This tag specifies the zero light (a.k.a. thermal black or black current) encoding level. It is calculated during image loading by averaging pixel values in the masked areas of the image.


HD Photo Non-Image Data Structure

HD Photo format uses the same non-image data storage format as is used by TIFF. However, HD Photo uses its own set of tags for image-related parameters, such as image width, height and pixel format. It also uses a few descriptive TIFF tags such as Copyright and Artist. HD Photo non-image data may include EXIF, EXIF GPS and IPTC subtrees.


XMP Non-Image Data Structure

ImageGear support XMP metadata in the following image file formats:

  • TIFF: Read, Write
  • EXIF-TIFF: Read, Write
  • JFIF-JPEG: Read, Write
  • EXIF-JPEG: Read, Write
  • PSD: Read

In TIFF and EXIF-TIFF formats, XMP metadata is located in the main IFD.

In JFIF-JPEG and EXIF-JPEG formats, XMP metadata is located in one of the App1 segments. Note that EXIF metadata is also located in an App1 segment.

In PSD format, XMP metadata is located in the Photoshop Resources tree.

XMP metadata tree structure:

  • XMP Root level
  • XMP Schema level
  • XMP Namespace level
  • XMP Property Collection level
  • XMP Simple Property level
  • XMP Array level
  • XMP Array Items level
  • XMP Language Alternative Property level
  • XMP Structure level
  • XMP Structure Items level
  • XMP Qualifiers level
  • XMP Qualifier level

XMP Root level

Name
Id
Type
Level Type
Value Type
<Schema namespace URI 1>
ImGearXMPTagIDs.Description
Tree
XMP Schema
N/A
<Schema namespace URI 1>
ImGearXMPTagIDs.Description
Tree
XMP Schema
N/A
...

XMP Schema level

Name
Id
Type
Level Type
Value Type
About
ImGearXMPTagIDs.About
Leaf
N/A
String
Namespace
ImGearXMPCommonTagIDs. Namespace
Tree
XMP Namespace
N/A
Properties
ImGearXMPCommonTagIDs.
Tree
XMP Property Collection
N/A

XMP Namespace level

Name
Id
Type
Level Type
Value Type
Prefix
ImGearXMPTagIDs.Prefix
Leaf
N/A
String
URI
ImGearXMPTagIDs.URI
Leaf
N/A
String

XMP Property Collection level

Name
Id
Type
Level Type
Value Type
<Property 1 name>
ImGearXMPTagIDs.Property
Tree
XMP Simple Property / XMP Array / XMP Structure
N/A
<Property 2 name>
ImGearXMPTagIDs.Property
Tree
XMP Simple Property, XMP Array/Structure property
N/A
...

XMP Simple Property level

Name
Id
Type
Level Type
Value Type
Value
ImGearXMPropertyTagIDs.Value
Leaf
N/A
<Value type>
Qualifiers
ImGearXMPropertyTagIDs.Qualifiers
Tree
XMP Qualifiers collection
N/A

XMP Array level

Name
Id
Type
Level Type
Value Type
Bag / Seq / Alt
ImGearXMPropertyTagIDs.Bag / ImGearXMPropertyTagIDs.Seq / ImGearXMPropertyTagIDs.Alt
Tree
XMP Array items level
N/A

XMP Array Items level

Name
Id
Type
Level Type
Value Type
Item
ImGearXMPropertyTagIDs.Item
Tree
XMP Simple Property / XMP Language Alternative Property / XMP Structure
<N/A>
Item
ImGearXMPropertyTagIDs.Item
Tree
XMP Simple Property / XMP Language Alternative Property / XMP Structure
<N/A>
...

XMP Language Alternative Property level

Name
Id
Type
Level Type
Value Type
Value
ImGearXMPropertyTagIDs.Value
Leaf
N/A
<Value type>
Lang
ImGearXMPropertyTagIDs.Lang
Leaf
N/A
String

XMP Structure level

Name
Id
Type
Level Type
Value Type
Struct
ImGearXMPropertyTagIDs.Struct
Tree
XMP Structure items level
N/A

XMP Structure Items level

Name
Id
Type
Level Type
Value Type
<Field 1 name 1>
ImGearXMPropertyTagIDs.Property
Tree
XMP Simple Property
<N/A>
<Field 2 name>
ImGearXMPropertyTagIDs. Property
Tree
XMP Simple Property
<N/A>
...

XMP Qualifiers level

Name
Id
Type
Level Type
Value Type
<Qualifier 1 name>
ImGearXMPropertyTagIDs. Qualifier
Tree
XMP Qualifier
<N/A>
<Qualifier 2 name>
ImGearXMPropertyTagIDs. Qualifier
Tree
XMP Qualifier
<N/A>
...

XMP Qualifier level

Name
Id
Type
Level Type
Value Type
Value
ImGearXMPCommonTagIDs.
Value
Leaf
N/A
<Value type>


JPEG2000 Component Metadata

ImageGear JPEG2K Component allows you to work with non-image data stored in supported file formats. It provides metadata tags that make possible manipulating with such kinds of non-image information:

  • XML & IPR information,
  • alpha channels mapping,
  • chroma keys,
  • composition layers,
  • format type information,
  • Type of compression (loss, lossless).

JP2 Metadata Tags

There are the following metadata tags you can use to work with JP2 files:

    • "XML"
    • "IPR"
    • "Format"
    • "CompressionType"
    • "AlphaMapping",
    • "Alpha1", "Alpha2", "Alpha3", "Alpha4",

JPX Metadata Tags

There are the following metadata tags you can use to work with JPX files:

    • "XML"
    • "IPR"
    • "ComposedLayersQty",
    • "Chroma",
    • "AlphaMapping",
    • "Alpha1", "Alpha2", "Alpha3", "Alpha4",

MJ2 Metadata Tags

There are the following metadata tags you can use to work with MJ2 files:

    • "AlphaMapping",
    • Alpha1,
    • Alpha2,
    • Alpha3

See "Alpha1", "Alpha2", "Alpha3", "Alpha4"

JPEG2000 Metadata Tags Reference

NOTE: Value of these tags below can be changed using LPAFT_IG_METAD_ITEM_SET_CB callback only.

"AlphaMapping"

This tag establishes the relationship, if any, between color channels and alpha (and/or pre-multiplied) alpha channels. Each element of array specifies number of alpha channel associated with regular (color) channel. Zero or negative value means absence of alpha mapping for particular color channel. For example:

"AlphaMapping" with {1, 1, 1, -1} as value means that all red, green and blue channels of image are mapped to single (first) alpha channel, which available under 0-index for current image through ImageGear API. {-1, 2, 1, -1} value means availability of two different alpha channels for green and blue channels and absence of alpha channel for red channel. Second alpha (located in "Alpha2") is mapped to green color channel and first is mapped to

Addinional information about available alpha channels can be accessed through "Alpha1", "Alpha2", "Alpha3" and "Alpha4" tags.

"Alpha1", "Alpha2", "Alpha3", "Alpha4"

Each of these tags represents information about alpha channels. Valid value for each tag is array with three integer elements. First element represents index of codestream (-1 or non-negative value), in which alpha channel is (or "should be" in case of write) resided. Second - index of component in which alpha is stored (-1 or non-negative value). Last element specifies whether alpha is regular (0) or pre-multiplied (1). For example:

"Alpha1" with {0, 3, 0} as value means that first alpha channel is regular and located in fourth component of the first codestream. {1, 0, 1} value represents pre-multiplied alpha in first component of second codestream in JPX layer.

NOTE: For JP2 and MJ2 file formats value of the first element (codestream index) is restricted to {-1, 0} set. Only for JPX files it's allowed to store alpha channels in separate codestream.

"Chroma"

This tag contains array of values each of which is treated as fully-transparent for particular channel. Negative value of any element means absence of chroma-key.

"ComposedLayersQty"

This tag specifies number of composed layers involved into loaded composition. It appears only for images loaded by JPX filter with value of LOAD_COMPOSITION control parameter set to TRUE.

"XML"

This tag serves for getting and setting some specific information written in XML language. Please note that only JPEG2000 format is able to store XML data. It must be set as a text string ended with "\0".

"IPR"

This tag serves for getting and setting IPR (Intellectual Property Rights) information. The IPR metadata defines metadata to either protect the rights of the owner of the image or provide further information to request permission to use it. It is important for developers and users to properly protect the rights of the owner of the image data.

Please note that only JPEG2000 format is able to store IPR data. It must be set as a text string ended with "\0".

"Format"

This tag serves for getting format of JPEG2K file. Its possible values are:

    • IG_JPEG2K_FORMAT_CODESTREAM =0,
    • IG_JPEG2K_FORMAT_JP2 =1

"CompressionType"

This tag serves for getting a compression type of JPEG2K image. Its possible values are:

    • IG_JPEG2K_TYPE_LOSSY = 0,
    • IG_JPEG2K_TYPE_LOSSLESS = 1

JPEG2K sets one of these values depending on the type of the image. This tag is not used in JPEG2K writing.


Appendix: TWAIN Scanning Capabilities

This Appendix represents TWAIN scanning capabilities that are most oftenly used for the TWAIN scanning processes:

  • CAP_DUPLEXENABLED
  • CAP_PAPERDETECTABLE
  • CAP_FEEDERENABLED
  • CAP_FEEDERLOADED
  • CAP_XFERCOUNT
  • ICAP_BITDEPTH
  • ICAP_BITORDER
  • ICAP_BRIGHTNESS
  • ICAP_COMPRESSION
  • ICAP_CONTRAST
  • ICAP_HIGHLIGHT
  • ICAP_IMAGEFILEFORMAT
  • ICAP_MINIMUMHEIGHT
  • ICAP_MINIMUMWIDTH
  • ICAP_PIXELFLAVOR
  • ICAP_PIXELTYPE
  • ICAP_SHADOW
  • ICAP_UNITS
  • ICAP_XFERMECH
  • ICAP_XRESOLUTION
  • ICAP_XSCALING
  • ICAP_YRESOLUTION
  • ICAP_YSCALING


CAP_DUPLEXENABLED

Group: TWAIN Capabilities

Data type: TW_BOOL

Purpose:

The user can set the duplex option to be TRUE or FALSE. If TRUE, the scanner scans both sides of a paper; otherwise, the scanner will scan only one side of the image.

Valid Values: TRUE, FALSE

Default Value: FALSE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


CAP_PAPERDETECTABLE

Group: TWAIN Capabilities

Data type: TW_BOOL

Purpose:

This capability determines whether the device has a paper sensor that can detect documents on the ADF or Flatbed.

If the source returns FALSE, the application should not rely on values such as CAP_FEEDERLOADED, and continue as if the paper is loaded.

Valid Values: TRUE, FALSE

Default Value: TRUE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


CAP_FEEDERENABLED

Group: TWAIN Capabilities

Data type: TW_BOOL

Purpose:

The application should set this capability to TRUE before using other capabilities relating to an ADF, such as CAP_FEEDERLOADED.

ImageGear will set this capability to TRUE prior to initiating a multi-page-capable image acquisition. Therefore, the application does not need to set this capability unless it needs to work with other ADF-related capabilities prior to acquisition.

Valid Values: TRUE, FALSE

Default Value: TRUE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


CAP_FEEDERLOADED

Group: TWAIN Capabilities

Data type: TW_BOOL

Purpose:

This capability indicates whether or not documents are loaded in an ADF. CAP_FEEDERENABLED must equal TRUE to use this capability. CAP_PAPERDETECTABLE can be checked to see if the device is capable of returning feeder status.

Valid Values: TRUE, FALSE

Default Value: No default

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


CAP_XFERCOUNT

Group: TWAIN Capabilities

Data type: TW_INT16

Purpose:

The application is willing to accept this number of images.

Set this capability to the number of images you are willing to transfer per session. Common values are:

  • 1 - Application wishes to transfer only one image this session
  • -1 - Application is willing to transfer multiple images

ImageGear sets this capability prior to acquiring images based on the API call used to initiate image acquisition. You should not set this capability. If you do, it will not affect the number of pages scanned by ImageGear.

Valid Values:

-1 to 2^15

Default Value:

-1


ICAP_BITDEPTH

Group: TWAIN Capabilities

Data type: TW_UINT16

Purpose:

Specifies the pixel bit depths for the Current value of ICAP_PIXELTYPE. For example, when using ICAP_PIXELTYPE = TWPT_GRAY, this capability specifies whether this is 8-bit gray or 4-bit gray.

This depth applies to all the data channels (for instance, the R, G, and B channels will all have this same bit depth for RGB data). A bit depth of 8 for RGB indicates 8 bits per channel, resulting in 24-bit RGB. Therefore, for 24-bit RGB, this capability should be set to 8, not 24.

Valid Values: >=1

Default Value: N/A

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ICAP_BITORDER

Group: TWAIN Capabilities

Data type: TW_UINT16

Purpose:

Specifies how the bytes in an image are filled by the Source. TWBO_MSBFIRST indicates that the leftmost bit in the byte (usually bit 7) is the byte's Most Significant Bit.

Valid Values:

  • TWBO_LSBFIRST = 0
  • TWBO_MSBFIRST = 1

Default Value:

TWBO_MSBFIRST


ICAP_BRIGHTNESS

Group: TWAIN Capabilities

Data type: TW_FIX32

Purpose:

The brightness values available within the Source.

The application can use this capability to inquire, set, or restrict the values for BRIGHTNESS used in the Source.

Valid Values:

-1000 to +1000

Default Value:

0


ICAP_COMPRESSION

Group: TWAIN Capabilities

Data type: TW_UINT16

Purpose:

Allows the application and Source to identify which compression schemes they have in common for Buffered Memory and File transfers.

Since only certain file formats support compression, this capability must be negotiated after setting the desired file format with ICAP_IMAGEFILEFORMAT.

  • TWCP_NONE - All Sources must support this
  • TWCP_PACKBITS - Macintosh PackBits format (can be used with TIFF or PICT)
  • TWCP_GROUP31D
  • TWCP_GROUP31DEOL
  • TWCP_GROUP32D
  • TWCP_GROUP4 - Are all from the CCITT specification (now ITU), intended for document images (can be used with TIFF)
  • TWCP_JPEG - Intended for the compression of color photographs (can be used with TIFF, JFIF or SPIFF)
  • TWCP_LZW - A compression licensed by UNISYS (can be used with TIFF)
  • TWCP_JBIG - Intended for bitonal and grayscale document images (can be used with TIFF or SPIFF)
  • TWCP_PNG - This compression can only be used if ICAP_IMAGEFILEFORMAT is set to TWFF_PNG
  • TWCP_RLE4
  • TWCP_RLE8
  • TWCP_BITFIELDS - These compressions can only be used if ICAP_IMAGEFILEFORMAT is set to TWFF_BMP

Applications must not assume that a Source can provide compressed Buffered Memory or File transfers, because many cannot. The application should use MSG_SET on a TW_ONEVALUE container to specify the compression type for future transfers.

Valid Values:

  • TWCP_NONE = 0
  • TWCP_PACKBITS = 1
  • TWCP_GROUP31D = 2
  • TWCP_GROUP31DEOL = 3
  • TWCP_GROUP32D = 4
  • TWCP_GROUP4 = 5
  • TWCP_JPEG = 6
  • TWCP_LZW = 7
  • TWCP_JBIG = 8
  • TWCP_PNG = 9
  • TWCP_RLE4 = 10
  • TWCP_RLE8 = 11
  • TWCP_BITFIELDS = 12

Default Value:

TWCP_NONE


ICAP_CONTRAST

Group: TWAIN Capabilities

Data type: TW_FIX32

Purpose:

The contrast values available within the Source.

The application can use this capability to inquire, set or restrict the values for CONTRAST used in the Source.

Valid Values:

-1000 to +1000

Default Value: 0

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ICAP_HIGHLIGHT

Group: TWAIN Capabilities

Data type: TW_FIX32

Purpose:

Specifies which value in an image should be interpreted as the lightest "highlight." All values "lighter" than this value will be clipped to this value. Whether lighter values are smaller or larger can be determined by examining the Current value of ICAP_PIXELFLAVOR.

Valid Values:

0 to 255

Default Value:

255


ICAP_IMAGEFILEFORMAT

Group: TWAIN Capabilities

Data type: TW_UINT16

Purpose:

Informs the application which file formats the Source can generate (MSG_GET). Tells the Source which file formats the application can handle (MSG_SET).

  • TWFF_TIFF - Used for document imaging
  • TWFF_PICT - Native Macintosh format
  • TWFF_BMP - Native Microsoft format
  • TWFF_XBM - Used for document imaging
  • TWFF_JFIF - Wrapper for JPEG images
  • TWFF_FPX - FlashPix, used with digital cameras
  • TWFF_TIFFMULTI - Multi-page TIFF files
  • TWFF_PNG - An image format standard intended for use on the web, replaces GIF
  • TWFF_SPIFF - A standard from JPEG, intended to replace JFIF, also supports JBIG
  • TWFF_EXIF - File format for use with digital cameras.

Use this ICAP to determine which formats are available for file transfers, and set the context for other capability negotiations such as ICAP_COMPRESSION. Be sure to use the DG_CONTROL / DAT_SETUPFILEXFER / MSG_SET or the DG_CONTROL / DAT_SETUPFILEXFER2 / MSG_SET operation to specify the format to be used for a particular acquisition.

Valid Values:

  • TWFF_TIFF = 0
  • TWFF_PICT = 1
  • TWFF_BMP = 2
  • TWFF_XBM = 3
  • TWFF_JFIF = 4
  • TWFF_FPX = 5
  • TWFF_TIFFMULTI = 6
  • TWFF_PNG = 7
  • TWFF_SPIFF = 8
  • TWFF_EXIF = 9

Default Value:

TWFF_BMP


ICAP_MINIMUMHEIGHT

Group: TWAIN Capabilities

Data type: TW_FIX32

Purpose:

Allows the source to define the minimum height (Y-axis) that the source can acquire.

Valid Values:

0 to 32767 (in ICAP_UNITS)

Default Value:

N/A


ICAP_MINIMUMWIDTH

Group: TWAIN Capabilities

Data type: TW_FIX32

Purpose:

Allows the source to define the minimum width (X-axis) that the source can acquire.

Valid Values:

0 to 32767 (in ICAP_UNITS)

Default Value:

N/A


ICAP_PIXELFLAVOR

Group: TWAIN Capabilities

Data type: TW_UINT16

Purpose:

Sense of the pixel whose numeric value is zero (minimum data value). For example, consider a black and white image:

If ICAP_PIXELTYPE is TWPT_BW then
If ICAP_PIXELFLAVOR is TWPF_CHOCOLATE
then Black = 0
Else if ICAP_PIXELFLAVOR is TWPF_VANILLA
then White = 0

Sources may prefer a different value depending on ICAP_PIXELTYPE. Set ICAP_PIXELTYPE and do a MSG_GETDEFAULT to determine the Source's preferences.

Valid Values:

  • TWPF_CHOCOLATE = 0
  • TWPF_VANILLA = 1

Default Value:

TWPF_CHOCOLATE


ICAP_PIXELTYPE

Group: TWAIN Capabilities

Data type: TW_UINT16

Purpose:

Specifies the type of pixel data that a Source is capable of acquiring (for example, black and white, gray, RGB, etc.).

  • MSG_GET - returns a list of all pixel types available from the Source.
  • MSG_SET on a TW_ENUMERATION structure - requests that the Source restrict the available pixel types to the enumerated list.
  • MSG_SET on a TW_ONEVALUE container - specifies the only pixel type the application can accept.

If the application plans to transfer data through any mechanism other than Native and cannot handle all possible ICAP_PIXELTYPE, it must support negotiation of this ICAP.

Valid Values:

  • TWPT_BW = 0
  • TWPT_GRAY = 1
  • TWPT_RGB = 2
  • TWPT_PALETTE = 3
  • TWPT_CMY = 4
  • TWPT_CMYK = 5
  • TWPT_YUV = 6
  • TWPT_YUVK = 7
  • TWPT_CIEXYZ = 8

Default Value:

N/A


ICAP_SHADOW

Group: TWAIN Capabilities

Data type: TW_FIX32

Purpose:

Specifies which value in an image should be interpreted as the darkest "shadow." All values "darker" than this value will be clipped to this value.

Whether darker values are smaller or larger can be determined by examining the Current value of ICAP_PIXELFLAVOR.

Valid Values:

0 to 255

Default Value:

0


ICAP_UNITS

Group: TWAIN Capabilities

Data type: TW_UINT16

Purpose:

Unless a quantity is dimensionless or uses a specified unit of measure, ICAP_UNITS determines the unit of measure for all quantities.

Applications should be able to handle TWUN_PIXELS, if they want to support data transfers from "dimensionless" devices such as digital cameras.

Valid Values:

  • TWUN_INCHES = 0
  • TWUN_CENTIMETERS = 1
  • TWUN_PICAS = 2
  • TWUN_POINTS = 3
  • TWUN_TWIPS = 4
  • TWUN_PIXELS = 5

Default Value:

TWUN_INCHES


ICAP_XFERMECH

Group: TWAIN Capabilities

Data type: TW_UINT16

Purpose:

Allows the application and Source to identify which transfer mechanisms they have in common.

The current setting of ICAP_XFERMECH must match the constant used by the application to specify the transfer mechanism when starting the transfer using the triplet: DG_IMAGE /DAT_IMAGExxxxXFER / MSG_GET.

ImageGear will transfer images according to the transfer mechanism an application selects via this capability.

Valid Values:

  • TWSX_NATIVE = 0
  • TWSX_FILE = 1
  • TWSX_MEMORY = 2
  • TWSX_FILE2 = 3

Default Value:

TWSX_NATIVE


ICAP_XRESOLUTION

Group: TWAIN Capabilities

Data type: TW_FIX32

Purpose:

All the X-axis resolutions the Source can provide.

Measured in units of pixels per unit as defined by ICAP_UNITS (pixels per TWUN_PIXELS yields dimensionless data). That is, when the units are TWUN_PIXELS, both ICAP_XRESOLUTION and ICAP_YRESOLUTION shall report 1 pixel/pixel. Some data sources like to report the actual number of pixels that the device reports, but that response is more appropriate in ICAP_PHYSICALHEIGHT and ICAP_PHYSICALWIDTH.

Setting this value will restrict the various resolutions that will be available to the user during acquisition. Applications will want to ensure that the values set for this ICAP match those set for ICAP_YRESOLUTION.

Valid Values:

>0

Default Value:

N/A


ICAP_XSCALING

Group: TWAIN Capabilities

Data type: TW_FIX32

Purpose:

All the X-axis scaling values available. A value of `1.0' is equivalent to 100% scaling.

NOTE: Do not use values less than or equal to zero.

Applications will want to ensure that the values set for this ICAP match those set for ICAP_YSCALING. There are no units inherent with this data as it is normalized to 1.0 being "unscaled."

Valid Values:

> 0

Default Value:

1.0


ICAP_YRESOLUTION

Group: TWAIN Capabilities

Data type: TW_FIX32

Purpose:

All the Y-axis resolutions the Source can provide.

Measured in units of pixels per unit as defined by ICAP_UNITS (pixels per TWUN_PIXELS yields dimensionless data). That is, when the units are TWUN_PIXELS, both ICAP_XRESOLUTION and ICAP_YRESOLUTION shall report 1 pixel/pixel. Some data sources like to report the actual number of pixels that the device reports, but that response is more appropriate in ICAP_PHYSICALHEIGHT and ICAP_PHYSICALWIDTH.

Setting this value will restrict the various resolutions that will be available to the user during acquisition.

Applications will want to ensure that the values set for this ICAP match those set for ICAP_XRESOLUTION.

Valid Values:

> 0

Default Value:

N/A


ICAP_YSCALING

Group: TWAIN Capabilities

Data type: TW_FIX32

Purpose:

All the Y-axis scaling values available. A value of `1.0' is equivalent to 100% scaling.

NOTE: Do not use values less than or equal to zero.

There are no units inherent with this data as it is normalized to 1.0 being "unscaled."

Applications will want to ensure that the values set for this ICAP match those set for ICAP_XSCALING.

Valid Values:

> 0

Default Value:

1.0


Appendix: Recognition Component Specifications

This Appendix provides you with detailed specifications of ImageGear Recognition component characters, codepages, languages lists, modules, etc1.

1Portions of this document are excerpted from ScanSoft's OmniPage Capture SDK 12.5 reference materials. Copyright (c) 2004 ScanSoft, Inc. All rights reserved. ScanSoft is a trademark or registered trademark of ScanSoft, Inc. in the United States and other countries.


Characters and Code Pages

The following tables list all the characters handled by the recognition engine, arranged in filter categories. The letters are in alphabetical order. You cannot extend the recognition engine's capability beyond these characters (approx. 500 in total).

The first columns present the character names and their UNICODE value. The next columns show the character in ASCII (437), Roman-8, ANSI (1252), Greek-Elot, Greek-Memotek and WordPerfect code pages.

Some API functions need character strings stated in UNICODE values.

"MIS" in the tables means that the character is missing from the Code Page.

NUMBERS (Digits)

Name of the Character
UNICODE
ASCII
Roman
ANSI
Elot
Memotek
WP
Digit Zero
0x0030
0
0
0
0
0
0x0030
Digit One
0x0031
1
1
1
1
1
0x0031
Digit Two
0x0032
2
2
2
2
2
0x0032
Digit Three
0x0033
3
3
3
3
3
0x0033
Digit Four
0x0034
4
4
4
4
4
0x0034
Digit Five
0x0035
5
5
5
5
5
0x0035
Digit Six
0x0036
6
6
6
6
6
0x0036
Digit Seven
0x0037
7
7
7
7
7
0x0037
Digit Eight
0x0038
8
8
8
8
8
0x0038
Digit Nine
0x0039
9
9
9
9
9
0x0039

LATIN CHARACTERS (Upper case)

Name of the Character
UNICODE
ASCII
Roman
ANSI
Elot
Memotek
WP
Cap. A Diaeresis
0x00c4
142
216
196
MIS
MIS
0x011e
Cap. A Acute
0x00c1
MIS
224
193
MIS
MIS
0x011a
Cap. A Ring
0x00c5
143
208
197
MIS
MIS
0x0122
Cap. A Circumflex
0x00c2
MIS
162
194
MIS
MIS
0x011c
Cap. A Grave
0x00c0
MIS
161
192
MIS
MIS
0x0120
Cap. A Tilde (Portuguese)
0x00c3
MIS
225
195
MIS
MIS
0x014c
Cap. A Breve (Romanian)
0x0102
MIS
MIS
MIS
MIS
MIS
MIS
Cap. A Ogonok (Polish, Lith...)
0x0104
MIS
MIS
MIS
MIS
MIS
0x015e
Cap. A Macron (Latvian)
0x0100
MIS
MIS
MIS
MIS
MIS
0x015c
Cap. AE
0x00c6
146
211
198
MIS
MIS
0x0124
Cap. A
0x0041
A
A
A
A
A
0x0041
Cap. B
0x0042
B
B
B
B
B
0x0042
Cap. C Acute
0x0106
MIS
MIS
MIS
MIS
MIS
0x0160
Cap. C Circumflex (Esperanto)
0x0108
MIS
MIS
MIS
MIS
MIS
0x0164
Cap. C Hacek
0x010c
MIS
MIS
MIS
MIS
MIS
0x0162
Cap. C Dot (Maltese)
0x010a
MIS
MIS
MIS
MIS
MIS
0x0166
Cap. C Cedilla
0x00c7
128
180
199
MIS
MIS
0x0126
Cap. C
0x0043
C
C
C
C
C
0x0043
Cap. D Hacek (Czech, Slovak)
0x010e
MIS
MIS
MIS
MIS
MIS
0x0168
Cap. D Stroke (Croatian)
0x0110
MIS
MIS
MIS
MIS
MIS
0X014e
Cap. D
0x0044
D
D
D
D
D
0x0044
Cap. ETH (Icelandic, Faroese)
0x00d0
MIS
227
208
MIS
MIS
0x0156
Cap. E Acute
0x00c9
144
220
201
MIS
MIS
0x0128
Cap. E Diaeresis
0x00cb
MIS
165
203
MIS
MIS
0x012c
Cap. E Circumflex
0x00ca
MIS
164
202
MIS
MIS
0x012a
Cap. E Grave
0x00c8
MIS
163
200
MIS
MIS
0x012e
Cap. E Hacek
0x011a
MIS
MIS
MIS
MIS
MIS
0x016a
Cap. E Dot (Lithuanian)
0x0116
MIS
MIS
MIS
MIS
MIS
0x016c
Cap. E Ogonok (Polish, Lith...)
0x0118
MIS
MIS
MIS
MIS
MIS
0x0170
Cap. E Macron (Latvian)
0x0112
MIS
MIS
MIS
MIS
MIS
0x016e
Cap. E
0x0045
E
E
E
E
E
0x0045
Cap. F
0x0046
F
F
F
F
F
0x0046
Cap. G Circumflex (Esperanto)
0x011c
MIS
MIS
MIS
MIS
MIS
0x017a
Cap. G Breve (Turkish)
0x011e
MIS
MIS
MIS
MIS
MIS
0x0176
Cap. G Dot (Maltese)
0x0120
MIS
MIS
MIS
MIS
MIS
0x017c
Cap. G Cedilla (Latv. + Lapp)
0x0122
MIS
MIS
MIS
MIS
MIS
0x0178
Cap. G
0x0047
G
G
G
G
G
0x0047
Cap. H Circumflex (Esperanto)
0x0124
MIS
MIS
MIS
MIS
MIS
0x017e
Cap. H Bar (Maltese)
0x0126
MIS
MIS
MIS
MIS
MIS
0x0180
Cap. H
0x0048
H
H
H
H
H
0x0048
Cap. I Diaeresis
0x00cf
MIS
167
207
MIS
MIS
0x0134
Cap. I Grave
0x00cc
MIS
230
204
MIS
MIS
0x0136
Cap. I Circumflex
0x00ce
MIS
166
206
MIS
MIS
0x0132
Cap. I Acute
0x00cd
MIS
229
205
MIS
MIS
0x0130
Cap. I Tilde (Eskimo, Kikuyu)
0x0128
MIS
MIS
MIS
MIS
MIS
0x0188
Cap. I Dot (Turkish)
0x0130
MIS
MIS
MIS
MIS
MIS
0x0182
Cap. I Ogonok (Lithuanian)
0x012e
MIS
MIS
MIS
MIS
MIS
0x0186
Cap. I Macron (Latvian...)
0x012a
MIS
MIS
MIS
MIS
MIS
0x0184
Cap. I Hacek
0x012c
MIS
MIS
MIS
MIS
MIS
MIS
Cap. I
0x0049
I
I
I
I
I
0x0049
Cap. J Circumflex (Esperanto)
0x0134
MIS
MIS
MIS
MIS
MIS
0x018c
Cap. J
0x004a
J
J
J
J
J
0x004a
Cap. K Cedilla (Latvian)
0x0136
MIS
MIS
MIS
MIS
MIS
0x018e
Cap. K
0x004b
K
K
K
K
K
0x004b
Cap. L Acute (Slovak)
0x0139
MIS
MIS
MIS
MIS
MIS
0x0190
Cap. L Hacek (Slovak)
0x013d
MIS
MIS
MIS
MIS
MIS
0x0192
Cap. L Slash (Polish...)
0x0141
MIS
MIS
MIS
MIS
MIS
0x0198
Cap. L Cedilla (Latvian)
0x013b
MIS
MIS
MIS
MIS
MIS
0x0194
Cap. L
0x004c
L
L
L
L
L
0x004c
Cap. M
0x004d
M
M
M
M
M
0x004d
Cap. N Tilde
0x00d1
165
182
209
MIS
MIS
0x0138
Cap. N Acute (Polish...)
0x0143
MIS
MIS
MIS
MIS
MIS
0x019a
Cap. N Hacek (Czech, Slovak)
0x0147
MIS
MIS
MIS
MIS
MIS
0x019e
Cap. N Cedilla (Latvian)
0x0145
MIS
MIS
MIS
MIS
MIS
0x01a0
Cap. ENG (Lappish)
0x014a
MIS
MIS
MIS
MIS
MIS
0x01d2
Cap. N
0x004e
N
N
N
N
N
0x004e
Cap. O Diaeresis
0x00d6
153
218
214
MIS
MIS
0x013e
Cap. O Acute
0x00d3
MIS
231
211
MIS
MIS
0x013a
Cap. O Circumflex
0x00d4
MIS
223
212
MIS
MIS
0x013c
Cap. O Grave
0x00d2
MIS
232
210
MIS
MIS
0x0140
Cap. O Tilde (Estonian, Port.)
0x00d5
MIS
233
213
MIS
MIS
0x0152
Cap. O Double Acute(Hungarian)
0x0150
MIS
MIS
MIS
MIS
MIS
0x01a2
Cap. O Macron (Latvian)
0x014c
MIS
MIS
MIS
MIS
MIS
0x01a4
Cap. O Breve (Latin)
0x014e
MIS
MIS
MIS
MIS
MIS
MIS
Cap. O Slash (Danish, Nor. ...)
0x00d8
MIS
210
216
MIS
MIS
0x0150
Cap. O E (French)
0x0152
MIS
MIS
140
MIS
MIS
0x01a6
Cap. O
0x004f
O
O
O
O
O
0x004f
Cap. P
0x0050
P
P
P
P
P
0x0050
Cap. Q
0x0051
Q
Q
Q
Q
Q
0x0051
Cap. R Acute (Slovak, Basque...)
0x0154
MIS
MIS
MIS
MIS
MIS
0x01a8
Cap. R Hacek (Czech...)
0x0158
MIS
MIS
MIS
MIS
MIS
0x01aa
Cap. R Cedilla (Latvian)
0x0156
MIS
MIS
MIS
MIS
MIS
0x01ac
Cap. R
0x0052
R
R
R
R
R
0x0052
Cap. S Hacek
0x0160
MIS
235
138
MIS
MIS
0x01b0
Cap. S Acute (Polish...)
0x015a
MIS
MIS
MIS
MIS
MIS
0x01ae
Cap. S Circumflex (Esperanto)
0x015c
MIS
MIS
MIS
MIS
MIS
0x01b4
Cap. S Cedilla (Turkish, Rom. ...)
0x015e
MIS
MIS
MIS
MIS
MIS
0x01b2
Cap. S
0x0053
S
S
S
S
S
0x0053
Cap. T Hacek (Czech, Slovak)
0x0164
MIS
MIS
MIS
MIS
MIS
0x01b6
Cap. T Cedilla (Romanian)
0x0162
MIS
MIS
MIS
MIS
MIS
0x01b8
Cap. T THORN (Icelandic)
0x00de
MIS
240
222
MIS
MIS
MIS
Cap. T Bar (Lappish)
0x0166
MIS
MIS
MIS
MIS
MIS
0x01ba
Cap. T
0x0054
T
T
T
T
T
0x0054
Cap. U Diaeresis
0x00dc
154
219
220
MIS
MIS
0x0146
Cap. U Acute
0x00da
MIS
237
218
MIS
MIS
0x0142
Cap. U Circumflex
0x00db
MIS
174
219
MIS
MIS
0x0144
Cap. U Grave
0x00d9
MIS
173
217
MIS
MIS
0x0148
Cap. U Tilde
0x0168
MIS
MIS
MIS
MIS
MIS
0x01c6
Cap. U Double Acute(Hungarian)
0x0170
MIS
MIS
MIS
MIS
MIS
0x01be
Cap. U Breve (Latin, Esperanto)
0x016c
MIS
MIS
MIS
MIS
MIS
0x01bc
Cap. U Ring (Czech)
0x016e
MIS
MIS
MIS
MIS
MIS
0x01c4
Cap. U Macron (Lith.+Latv. ...)
0x016a
MIS
MIS
MIS
MIS
MIS
0x01c0
Cap. U Ogonok (Lithuanian)
0x0172
MIS
MIS
MIS
MIS
MIS
0x01c2
Cap. U
0x0055
U
U
U
U
U
0x0055
Cap. V
0x0056
V
V
V
V
V
0x0056
Cap. W Circumflex (Welsh)
0x0174
MIS
MIS
MIS
MIS
MIS
0x01c8
Cap. W
0x0057
W
W
W
W
W
0x0057
Cap. X
0x0058
X
X
X
X
X
0x0058
Cap. Y Acute
0x00dd
MIS
177
221
MIS
MIS
0x0154
Cap. Y Diaeresis (French)
0x0178
MIS
238
159
MIS
MIS
0x014a
Cap. Y Circumflex (Welsh)
0x0176
MIS
MIS
MIS
MIS
MIS
0x01ca
Cap. Y
0x0059
Y
Y
Y
Y
Y
0x0059
Cap. Z Acute (Sorbian)
0x0179
MIS
MIS
MIS
MIS
MIS
0x01cc
Cap. Z Hacek
0x017d
MIS
MIS
MIS
MIS
MIS
0x01ce
Cap. Z Dot (Polish, Maltese)
0x017b
MIS
MIS
MIS
MIS
MIS
0x01d0
Cap. Z
0x005a
Z
Z
Z
Z
Z
0x005a

LATIN CHARACTERS (Lower case)

Name of the Character
UNICODE
ASCII
Roman
ANSI
Elot
Memotek
WP
Sml. A Diaeresis
0x00e4
132
204
228
MIS
MIS
0x011f
Sml. A Acute
0x00e1
160
196
225
MIS
MIS
0x011b
Sml. A Ring
0x00e5
134
212
229
MIS
MIS
0x0123
Sml. A Circumflex
0x00e2
131
192
226
MIS
MIS
0x011d
Sml. A Grave
0x00e0
133
200
224
MIS
MIS
0x0121
Sml. A Tilde
0x00e3
MIS
226
227
MIS
MIS
0x014d
Sml. A Feminine Ord. Ind. (Sp...)
0x00aa
166
249
170
MIS
MIS
0x040f
Sml. A Breve
0x0103
MIS
MIS
MIS
MIS
MIS
0x015b
Sml. A Ogonok
0x0105
MIS
MIS
MIS
MIS
MIS
0x015f
Sml. A Macron
0x0101
MIS
MIS
MIS
MIS
MIS
0x015d
Sml. AE
0x00e6
145
215
230
MIS
MIS
0x0125
Sml. A
0x0061
a
a
a
a
a
0x0061
Sml. B
0x0062
b
b
b
b
b
0x0062
Sml. C Acute
0x0107
MIS
MIS
MIS
MIS
MIS
0x0161
Sml. C Circumflex
0x0109
MIS
MIS
MIS
MIS
MIS
0x0165
Sml. C Hacek
0x010d
MIS
MIS
MIS
MIS
MIS
0x0163
Sml. C Dot
0x010b
MIS
MIS
MIS
MIS
MIS
0x0167
Sml. C Cedilla
0x00e7
135
181
231
MIS
MIS
0x0127
Sml. C
0x0063
c
c
c
c
c
0x0063
Sml. D Hacek
0x010f
MIS
MIS
MIS
MIS
MIS
0x0169
Sml. D Stroke
0x0111
MIS
MIS
MIS
MIS
MIS
0X0145
Sml. D
0x0064
d
d
d
d
d
0x0064
Sml. ETH
0x00f0
MIS
228
240
MIS
MIS
0x0157
Sml. E Acute
0x00e9
130
197
233
MIS
MIS
0x0129
Sml. E Diaeresis
0x00eb
137
205
235
MIS
MIS
0x012d
Sml. E Circumflex
0x00ea
136
193
234
MIS
MIS
0x012b
Sml. E Grave
0x00e8
138
201
232
MIS
MIS
0x012f
Sml. E Hacek
0x011b
MIS
MIS
MIS
MIS
MIS
0x016b
Sml. E Dot
0x0117
MIS
MIS
MIS
MIS
MIS
0x016d
Sml. E Ogonok
0x0119
MIS
MIS
MIS
MIS
MIS
0x0171
Sml. E Macron
0x0113
MIS
MIS
MIS
MIS
MIS
0x016f
Sml. E
0x0065
e
e
e
e
e
0x0065
Sml. F
0x0066
f
f
f
f
f
0x0066
Sml. G Circumflex
0x011d
MIS
MIS
MIS
MIS
MIS
0x017b
Sml. G Breve
0x011f
MIS
MIS
MIS
MIS
MIS
0x0177
Sml. G Dot
0x0121
MIS
MIS
MIS
MIS
MIS
0x017d
Sml. G Cedilla
0x0123
MIS
MIS
MIS
MIS
MIS
0x0179
Sml. G
0x0067
g
g
g
g
g
0x0067
Sml. H Circumflex
0x0125
MIS
MIS
MIS
MIS
MIS
0x017f
Sml. H Bar
0x0127
MIS
MIS
MIS
MIS
MIS
0x0181
Sml. H
0x0068
h
h
h
h
h
0x0068
Sml. I Diaeresis
0x00ef
139
221
239
MIS
MIS
0x0135
Sml. I Grave
0x00ec
141
217
236
MIS
MIS
0x0137
Sml. I Circumflex
0x00ee
140
209
238
MIS
MIS
0x0133
Sml. I Acute
0x00ed
161
213
237
MIS
MIS
0x0131
Sml. I Tilde
0x0129
MIS
MIS
MIS
MIS
MIS
0x0189
Sml. I Ogonok
0x012f
MIS
MIS
MIS
MIS
MIS
0x0187
Sml. I Macron
0x012b
MIS
MIS
MIS
MIS
MIS
0x0185
Sml. I Hacek
0x012d
MIS
MIS
MIS
MIS
MIS
MIS
Sml. Dotless I
0x0131
MIS
MIS
MIS
MIS
MIS
0x0118
Sml. I
0x0069
i
i
i
i
i
0x0069
Sml. J
0x006a
j
j
j
j
j
0x006a
Sml. J Circumflex
0x0135
MIS
MIS
MIS
MIS
MIS
0x018d
Sml. K Cedilla
0x0137
MIS
MIS
MIS
MIS
MIS
0x018f
Sml. K
0x006b
k
k
k
k
k
0x006b
Sml. L Acute
0x013a
MIS
MIS
MIS
MIS
MIS
0x0191
Sml. L Hacek
0x013e
MIS
MIS
MIS
MIS
MIS
0x0193
Sml. L Slash
0x0142
MIS
MIS
MIS
MIS
MIS
0x0199
Sml. L Cedilla
0x013c
MIS
MIS
MIS
MIS
MIS
0x0195
Sml. L
0x006c
l
l
l
l
l
0x006c
Sml. M
0x006d
m
m
m
m
m
0x006d
Sml. N Tilde
0x00f1
164
183
241
MIS
MIS
0x0139
Sml. N Acute
0x0144
MIS
MIS
MIS
MIS
MIS
0x019b
Sml. N Hacek
0x0148
MIS
MIS
MIS
MIS
MIS
0x019f
Sml. N Cedilla
0x0146
MIS
MIS
MIS
MIS
MIS
0x019d
Sml. ENG
0x014b
MIS
MIS
MIS
MIS
MIS
0x01d3
Sml. N
0x006e
n
n
n
n
n
0x006e
Sml. O Diaeresis
0x00f6
148
206
246
MIS
MIS
0x013f
Sml. O Acute
0x00f3
162
198
243
MIS
MIS
0x013b
Sml. O Circumflex
0x00f4
147
194
244
MIS
MIS
0x013d
Sml. O Grave
0x00f2
149
202
242
MIS
MIS
0x0141
Sml. O Tilde
0x00f5
MIS
234
245
MIS
MIS
0x0153
Sml. O Masculine Ord. Ind.(Sp...)
0x00ba
167
250
186
MIS
MIS
0x0410
Sml. O Double Acute
0x0151
MIS
MIS
MIS
MIS
MIS
0x01a3
Sml. O Macron
0x014d
MIS
MIS
MIS
MIS
MIS
0x01a5
Sml. O Breve
0x014f
MIS
MIS
MIS
MIS
MIS
MIS
Sml. O Slash
0x00f8
MIS
214
248
MIS
MIS
0x0151
Sml. O E
0x0153
MIS
MIS
156
MIS
MIS
0x01a7
Sml. O
0x006f
o
o
o
o
o
0x006f
Sml. P
0x0070
p
p
p
p
p
0x0070
Sml. Q
0x0071
q
q
q
q
q
0x0071
Sml. R Acute
0x0155
MIS
MIS
MIS
MIS
MIS
0x01a9
Sml. R Hacek
0x0159
MIS
MIS
MIS
MIS
MIS
0x01ab
Sml. R Cedilla
0x0157
MIS
MIS
MIS
MIS
MIS
0x01ad
Sml. R
0x0072
r
r
r
r
r
0x0072
Sml. S Hacek
0x0161
MIS
236
154
MIS
MIS
0x01b1
Sml. S Acute
0x015b
MIS
MIS
MIS
MIS
MIS
0x01af
Sml. S Circumflex
0x015d
MIS
MIS
MIS
MIS
MIS
0x01b5
Sml. S Cedilla
0x015f
MIS
MIS
MIS
MIS
MIS
0x01b3
Sharp SS (German)
0x00df
225
222
223
169
153
0x0117
Sml. S
0x0073
s
s
s
s
s
0x0073
Sml. T Hacek
0x0165
MIS
MIS
MIS
MIS
MIS
0x01b7
Sml. T Cedilla
0x0163
MIS
MIS
MIS
MIS
MIS
0x01b9
Sml. T THORN
0x00fe
MIS
241
254
MIS
MIS
MIS
Sml. T Bar
0x0167
MIS
MIS
MIS
MIS
MIS
0x01bb
Sml. T
0x0074
t
t
t
t
t
0x0074
Sml. U Diaeresis
0x00fc
129
207
252
MIS
MIS
0x0147
Sml. U Acute
0x00fa
163
199
250
MIS
MIS
0x0143
Sml. U Circumflex
0x00fb
150
195
251
MIS
MIS
0x0145
Sml. U Grave
0x00f9
151
203
249
MIS
MIS
0x014b
Sml. U Tilde
0x0169
MIS
MIS
MIS
MIS
MIS
0x01c7
Sml. U Double Acute
0x0171
MIS
MIS
MIS
MIS
MIS
0x01bf
Sml. U Breve
0x016d
MIS
MIS
MIS
MIS
MIS
0x01bd
Sml. U Ring
0x016f
MIS
MIS
MIS
MIS
MIS
0x01bb
Sml. U Macron
0x016b
MIS
MIS
MIS
MIS
MIS
0x01c1
Sml. U Ogonok
0x0173
MIS
MIS
MIS
MIS
MIS
0x01c3
Sml. U
0x0075
u
u
u
u
u
0x0075
Sml. V
0x0076
v
v
v
v
v
0x0076
Sml. W Circumflex
0x0175
MIS
MIS
MIS
MIS
MIS
0x01c9
Sml. W
0x0077
w
w
w
w
w
0x0077
Sml. X
0x0078
x
x
x
x
x
0x0078
Sml. Y Acute
0x00fd
MIS
178
253
MIS
MIS
0x0155
Sml. Y Diaeresis
0x00ff
152
239
255
MIS
MIS
0x014b
Sml. Y Circumflex
0x0177
MIS
MIS
MIS
MIS
MIS
0x01cb
Sml. Y
0x0079
y
y
y
y
y
0x0079
Sml. Z Acute
0x017a
MIS
MIS
MIS
MIS
MIS
0x01cd
Sml. Z Hacek
0x017e
MIS
MIS
MIS
MIS
MIS
0x01cf
Sml. Z Dot
0x017c
MIS
MIS
MIS
MIS
MIS
0x01d1
Sml. Z
0x007a
z
z
z
z
z
0x007a

CYRILLIC CHARACTERS (Lower case)

Name of the Character
UNICODE
ASCII
Roman
ANSI
Elot
Memotek
WP
Cyr. Sml. A
0x0430
MIS
MIS
MIS
MIS
MIS
0x0a01
Cyr. Sml. YA
0x044f
MIS
MIS
MIS
MIS
MIS
0x0a41
Cyr. Sml. BE
0x0431
MIS
MIS
MIS
MIS
MIS
0x0a03
Cyr. Sml. VE
0x0432
MIS
MIS
MIS
MIS
MIS
0x0a05
Cyr. Sml. GHE
0x0433
MIS
MIS
MIS
MIS
MIS
0x0a07
Cyr. Sml.GHEWITHUPTURN
0x0491
MIS
MIS
MIS
MIS
MIS
0x0a43
Cyr. Sml. GJE
0x0453
MIS
MIS
MIS
MIS
MIS
0x0a47
Cyr. Sml. DE
0x0434
MIS
MIS
MIS
MIS
MIS
0x0a09
Cyr. Sml. DJE
0x0452
MIS
MIS
MIS
MIS
MIS
0x0a45
Cyr. Sml. IE
0x0435
MIS
MIS
MIS
MIS
MIS
0x0a0b
Cyr. Sml. IO
0x0451
MIS
MIS
MIS
MIS
MIS
0x0a0d
Cyr. Sml. UKRAINIANIE
0x0454
MIS
MIS
MIS
MIS
MIS
0x0a49
Cyr. Sml. ZHE
0x0436
MIS
MIS
MIS
MIS
MIS
0x0a0f
Cyr. Sml. ZE
0x0437
MIS
MIS
MIS
MIS
MIS
0x0a11
Cyr. Sml. I
0x0438
MIS
MIS
MIS
MIS
MIS
0x0a13
Cyr. Sml. SHORTI
0x0439
MIS
MIS
MIS
MIS
MIS
0x0a15
Cyr. Sml. YI
0x0457
MIS
MIS
MIS
MIS
MIS
0x0a4f
Cyr. Sml.BYELORUSSIANUKRI
0x0456
MIS
MIS
MIS
MIS
MIS
0x0a4d
Cyr. Sml. YERU
0x044b
MIS
MIS
MIS
MIS
MIS
0x0a39
Cyr. Sml. KA
0x043a
MIS
MIS
MIS
MIS
MIS
0x0a17
Cyr. Sml. KJE
0x045c
MIS
MIS
MIS
MIS
MIS
0x0a59
Cyr. Sml. EL
0x043b
MIS
MIS
MIS
MIS
MIS
0x0a19
Cyr. Sml. LJE
0x0459
MIS
MIS
MIS
MIS
MIS
0x0a53
Cyr. Sml. EM
0x043c
MIS
MIS
MIS
MIS
MIS
0x0a1b
Cyr. Sml. EN
0x043d
MIS
MIS
MIS
MIS
MIS
0x0a1d
Cyr. Sml. NJE
0x045a
MIS
MIS
MIS
MIS
MIS
0x0a55
Cyr. Sml. O
0x043e
MIS
MIS
MIS
MIS
MIS
0x0a1f
Cyr. Sml. PE
0x043f
MIS
MIS
MIS
MIS
MIS
0x0a21
Cyr. Sml. ER
0x0440
MIS
MIS
MIS
MIS
MIS
0x0a23
Cyr. Sml. ES
0x0441
MIS
MIS
MIS
MIS
MIS
0x0a25
Cyr. Sml. TE
0x0442
MIS
MIS
MIS
MIS
MIS
0x0a27
Cyr. Sml. TSHE
0x045b
MIS
MIS
MIS
MIS
MIS
0x0a57
Cyr. Sml. U
0x0443
MIS
MIS
MIS
MIS
MIS
0x0a29
Cyr. Sml. SHORTU
0x045e
MIS
MIS
MIS
MIS
MIS
0x0a5b
Cyr. Sml. YU
0x044e
MIS
MIS
MIS
MIS
MIS
0x0a3f
Cyr. Sml. EF
0x0444
MIS
MIS
MIS
MIS
MIS
0x0a2b
Cyr. Sml. HA
0x0445
MIS
MIS
MIS
MIS
MIS
0x0a2d
Cyr. Sml. TSE
0x0446
MIS
MIS
MIS
MIS
MIS
0x0a2f
Cyr. Sml. DZHE
0x045f
MIS
MIS
MIS
MIS
MIS
0x0a5d
Cyr. Sml. CHE
0x0447
MIS
MIS
MIS
MIS
MIS
0x0a31
Cyr. Sml. SHA
0x0448
MIS
MIS
MIS
MIS
MIS
0x0a33
Cyr. Sml. SHCHA
0x0449
MIS
MIS
MIS
MIS
MIS
0x0a35
Cyr. Sml. DZE
0x0455
MIS
MIS
MIS
MIS
MIS
0x0a4b
Cyr. Sml. HARDSIGN
0x044a
MIS
MIS
MIS
MIS
MIS
0x0a37
Cyr. Sml. JE
0x0458
MIS
MIS
MIS
MIS
MIS
0x0a51
Cyr. Sml. SOFTSIGN
0x044c
MIS
MIS
MIS
MIS
MIS
0x0a3b
Cyr. Sml. E
0x044d
MIS
MIS
MIS
MIS
MIS
0x0a3d

GREEK CHARACTERS (Upper case)

Name of the Character
UNICODE
ASCII
Roman
ANSI
Elot
Memotek
WP
Cap. ALPHA TONOS (A)
0x0386
MIS
224
193
MIS
234
0x08c8
Cap. ALPHA
0x0391
A
A
A
144
128
0x0800
Cap. BETA
0x0392
B
B
B
145
129
0x0802
Cap. GAMMA
0x0393
226
MIS
MIS
146
130
0x0806
Cap. DELTA
0x0394
MIS
MIS
MIS
147
131
0x0808
Cap. EPSILON TONOS (E)
0x0388
144
220
201
MIS
235
0x08c9
Cap. EPSILON
0x0395
E
E
E
148
132
0x080a
Cap. ZETA
0x0396
Z
Z
Z
149
133
0x080c
Cap. ETA TONOS(H)
0x0389
MIS
MIS
MIS
MIS
236
0x08ca
Cap. ETA
0x0397
H
H
H
150
134
0x080e
Cap. THETA
0x0398
233
MIS
MIS
151
135
0x0810
Cap. IOTA TONOS (I)
0x038a
MIS
229
205
MIS
237
0x08cb
Cap. IOTA DIAERESIS
0x03AA
MIS
MIS
MIS
MIS
MIS
MIS
Cap. IOTA
0x0399
I
I
I
152
136
0x0812
Cap. KAPPA
0x039a
K
K
K
153
137
0x0814
Cap. LAMBDA
0x039b
MIS
MIS
MIS
154
138
0x0816
Cap. MU
0x039c
M
M
M
155
139
0x0818
Cap. NU
0x039d
N
N
N
156
140
0x081a
Cap. XI
0x039e
MIS
MIS
MIS
157
141
0x081c
Cap. OMICRON TONOS (O)
0x038c
MIS
231
211
MIS
238
0x08cc
Cap. OMICRON
0x039f
O
O
O
158
142
0x081e
Cap. PI
0x03a0
MIS
MIS
182
159
143
0x0820
Cap. RHO
0x03a1
P
P
P
160
144
0x0822
Cap. SIGMA
0x03a3
228
MIS
MIS
161
145
0x0824
Cap. TAU
0x03a4
T
T
T
162
146
0x0828
Cap. UPSILON TONOS (Y)
0x038e
MIS
177
221
MIS
239
0x08cd
Cap. UPSILON DIAERESIS
0x03ab
MIS
MIS
MIS
MIS
MIS
MIS
Cap. UPSILON
0x03a5
Y
Y
Y
163
147
0x082a
Cap. PHI
0x03a6
232
MIS
MIS
164
148
0x082c
Cap. CHI
0x03a7
X
X
X
165
149
0x082e
Cap. PSI
0x03a8
MIS
MIS
MIS
166
150
0x0830
Cap. OMEGA TONOS (e)
0x038f
MIS
MIS
MIS
MIS
240
0x01ce
Cap. OMEGA
0x03a9
234
MIS
MIS
167
151
0x0832

GREEK CHARACTERS (Lower case)

Name of the Character
UNICODE
ASCII
Roman
ANSI
Elot
Memotek
WP
Sml. ALPHA TONOS
0x03ac
MIS
MIS
MIS
193
225
0x0866
Sml. ALPHA
0x03b1
224
MIS
MIS
168
152
0x0801
Sml. BETA
0x03b2
MIS
MIS
MIS
169
153
0x0803
Sml. GAMMA
0x03b3
MIS
MIS
MIS
170
154
0x0807
Sml. DELTA
0x03b4
235
MIS
MIS
171
155
0x0809
Sml. EPSILON TONOS
0x03ad
MIS
MIS
MIS
194
226
0x0878
Sml. EPSILON
0x03b5
MIS
MIS
MIS
172
156
0x080b
Sml. ZETA
0x03b6
MIS
MIS
MIS
173
157
0x080d
Sml. ETA TONOS
0x03ae
MIS
MIS
MIS
196
227
0x0881
Sml. ETA
0x03b7
MIS
MIS
MIS
174
158
0x080f
Sml. THETA
0x03b8
MIS
MIS
MIS
175
159
0x0811
Sml. IOTA TONOS
0x03af
MIS
MIS
MIS
195
229
0x0893
Sml. IOTA Diaeresis
0x03ca
MIS
MIS
MIS
209
228
0x0899
Sml. IOTA Diaeresis TONOS
0x0390
MIS
MIS
MIS
MIS
MIS
0x0891
Sml. IOTA
0x03b9
MIS
MIS
MIS
176
160
0x0813
Sml. KAPPA
0x03ba
MIS
MIS
MIS
177
161
0x0815
Sml. LAMBDA
0x03bb
MIS
MIS
MIS
178
162
0x0817
Sml. MU
0x03bc
230
243
181
179
163
0x0819
Sml. NU
0x03bd
MIS
MIS
MIS
180
164
0x081b
Sml. XI
0x03be
MIS
MIS
MIS
181
165
0x081d
Sml. OMIK TONOS
0x03cc
162
198
243
197
230
0x089f
Sml. OMICRON
0x03bf
o
o
o
182
166
0x081f
Sml. PI
0x03c0
227
MIS
MIS
183
167
0x0821
Sml. RHO
0x03c1
MIS
MIS
MIS
184
168
0x0823
Sml. SIGMA
0x03c3
229
MIS
MIS
185
169
0x0825
Sml. TAU
0x03c4
231
MIS
MIS
186
171
0x0829
Sml. UPSILON TONOS
0x03cd
163
199
250
198
231
0x08a0
Sml. UPSILON Diaeresis
0x03cb
129
207
252
212
232
0x08a8
Sml. UPSILON Diar.TONOS
0x03b0
MIS
MIS
MIS
MIS
MIS
0x08a4
Sml. UPSILON
0x03c5
u
u
u
187
172
0x082b
Sml. PHI
0x03c6
MIS
MIS
MIS
188
173
0x082d
Sml. CHI
0x03c7
MIS
MIS
MIS
189
174
0x082f
Sml. PSI
0x03c8
MIS
MIS
MIS
190
175
0x0831
Sml. OMEGA TONOS
0x03ce
MIS
MIS
MIS
199
233
0x08b4
Sml. OMEGA
0x03c9
MIS
MIS
MIS
191
224
0x0833
Sml. EVANGEL
0x03c2
MIS
MIS
MIS
192
170
0x0827

PUNCTUATION CHARACTERS

Name of the Character
UNICODE
ASCII
Roman
ANSI
Elot
Memotek
WP
Apostrophe-Quote
0x0027
'
'
'
`
`
0x0027
Closing Curly Bracket
0x007d
}
}
}
}
}
0x007d
Closing Parenthesis
0x0029
)
)
)
)
)
0x0029
Closing Square Bracket
0x005d
]
]
]
]
]
0x005d
Colon
0x003a
:
:
:
:
:
0x003a
Comma
0x002c
,
,
,
,
,
0x002c
Double Quotation Mark Left
0x201c
MIS
MIS
"
MIS
MIS
0x043e
Double Quotation Mark Right
0x201d
MIS
MIS
"
MIS
MIS
0x043d
Em Dash
0x2014
-
-
-
-
-
0x0422
En Dash
0x2013
-
-
-
MIS
MIS
0x0421
Exclamation Mark
0x0021
!
!
!
!
!
0x0021
Hyphen-Minus
0x002d
-
-
-
-
-
0x002d
Inverted Exclamation Mark (Sp.)
0x00a1
?
?
?
MIS
MIS
0x0407
Inverted Question Mark (Sp.)
0x00bf
?
?
?
MIS
MIS
0x0408
Left Single Quotation Mark
0x2018
`
`
`
MIS
MIS
0x041b
Right Single Quotation Mark
0x2019
'
'
'
MIS
MIS
0x041c
Low Dbl. Comma Quot. Mark
0x201e
"
"
"
"
"
0x043f
Low Single Comma Quot. Mark
0x201a
‚
‚
‚
MIS
MIS
0x010c
Opening Curly Bracket
0x007b
{
{
{
{
{
0x007b
Opening Parenthesis
0x0028
(
(
(
(
(
0x0028
Opening Square Bracket
0x005b
[
[
[
[
[
0x005b
Period (full stop)
0x002e
.
.
.
.
.
0x002e
Question Mark
0x003f
?
?
?
?
?
0x003f
Quotation Mark
0x0022
"
"
"
"
"
0x0022
Semicolon
0x003b
;
;
;
;
;
0x003b
Left Pointing Single Guillemet
0x2039
<
<
<
<
<
0x0441
Right Pointing Single Guillemet
0x203a
>
>
>
>
>
0x0441
Soft Hyphen
0x20ad
-
-
-
-
-
0x002d
Spacing Grave
0x0060
`
`
`
`
`
0x0060

MISCELLANEOUS CHARACTERS

Name of the Character
UNICODE
ASCII
Roman
ANSI
Elot
Memotek
WP
Acute
0x00b4
MIS
?
?
MIS
MIS
0x0106
Ampersand
0x0026
&
&
&
&
&
0x0026
Asterisk
0x002a
*
*
*
*
*
0x002a
Backslash
0x005c
\
\
\
\
\
0x005c
Bullet
0x2022
·
·
·
MIS
·
0x0400
Broken Bar
0x00a6
¦
¦
¦
MIS
MIS
0x007c
Cedilla
0x00b8
MIS
MIS
?
MIS
MIS
0x0111
Cent Sign
0x00a2
?
?
?
MIS
MIS
0x0413
Circumflex
0x02c6
MIS
?
?
MIS
MIs
0x0103
Commercial At
0x0040
@
@
@
@
@
0x0040
Copyright Sign
0x00a9
MIS
MIS
©
MIS
MIS
0x0417
Currency Sign
0x00a4
MIS
¤
¤
MIS
MIS
0x0418
Dagger
0x2020
MIS
MIS
†
MIS
MIS
0x0431
Degree Sign
0x00b0
°
°
°
MIS
MIS
0x0410
Diaresis
0x00a8
MIS
?
?
MIS
MIS
0x0107
Dollar Sign
0x0024
$
$
$
$
$
0x0024
Double Dagger
0x2021
MIS
MIS
‡
MIS
MIS
0x0432
Equals Sign
0x003d
=
=
=
=
=
0x003d
Euro Sign
0x20ac
MIS
MIS
ˆ
MIS
MIS
0x209c
Greater-Than Sign
0x003e
>
>
>
>
>
0x003e
Horizontal Ellipsis
0x2026
MIS
MIS
...
MIS
MIS
0x0438
Left Pointing Guillemet
0x00ab
«
«
«
MIS
MIS
0x0409
Less-Than Sign
0x003c
<
<
<
<
<
0x003c
Macron
0x00af
MIS
?
?
MIS
MIS
0x0108
Math Division Sign
0x00f7
?
MIS
?
MIS
MIS
0x0608
Math Multipication Sign
0x00d7
MIS
MIS
?
MIS
MIS
0x0627
Micron
0x00b5
µ
µ
µ
MIS
MIS
0x0625
Midddle Dot
0x00b7
·
·
·
MIS
MIS
0x010e
Not Sign
0x00ac
¬
MIS
¬
MIS
MIs
0x0614
Number Sign
0x0023
#
#
#
#
#
0x0023
Per Mille Sign
0x2030
MIS
MIS
‰
MIS
MIS
0x044b
Percent Sign
0x0025
%
%
%
%
%
0x0025
Pilcrow Sign
0x00b6
¶
¶
¶
MIS
MIS
0x0405
Plus Sign
0x002b
+
+
+
+
+
0x002b
Plus-OR-Minus Sign
0x00b1
±
±
±
±
±
0x0601
Pound Sign
0x00a3
?
?
?
MIS
MIS
0x040b
Registered Trade Mark Sign
0x00ae
MIS
MIS
®
MIS
MIS
0x0416
Right Pointing Guillemet
0x00bb
»
»
»
MIS
MIS
0x040a
Section Sign
0x00a7
§
§
§
MIS
MIS
0x0406
Slash
0x002f
/
/
/
/
/
0x002f
Sml. Script F
0x0192
?
?
?
MIS
MIS
0x040e
Sml. Tilde
0x02dc
MIS
~
~
MIS
MIS
0x0102
Space
0x0020
0x0020
Spacing Circumflex
0x005e
^
^
^
^
^
0x005e
Spacing Underscore
0x005f
_
_
_
_
_
0x005f
Superscript One
0x00b9
MIS
MIS
?
MIS
MIS
0x044e
Superscript Three
0x00b3
MIS
MIS
?
MIS
MIS
0x041a
Superscript Two
0x00b2
?
MIS
?
MIS
MIS
0x0414
Tilde
0x007e
~
~
~
~
~
0x007e
Trade Mark Sign
0x2122
MIS
MIS
™
MIS
MIS
0x0429
Vertical Bar
0x007c
|
|
|
|
|
0x007c
Vulgar Fraction Three Quarter
0x00be
MIS
3/4
3/4
MIS
MIS
0x0419
Vulgar Fraction One Half
0x00bd
1/2
1/2
1/2
MIS
MIS
0x0411
Vulgar Fraction One Quarter
0x00bc
1/4
1/4
1/4
MIS
MIS
0x0412
Yen Sign
0x00a5
?
?
?
MIS
MIS
0x040c

OCR SPECIAL CHARACTERS*

Name of the Character
UNICODE
ASCII
Roman
ANSI
Elot
Memotek
WP
OCR Amount Of Check
0x2447
MIS
MIS
MIS
MIS
MIS
MIS
OCR Belt Buckle
0x2444
MIS
MIS
MIS
MIS
MIS
MIS
OCR Bow Tie
0x2445
MIS
MIS
MIS
MIS
MIS
MIS
OCR Branch Bank
0x2446
MIS
MIS
MIS
MIS
MIS
MIS
OCR Chair
0x2441
MIS
MIS
MIS
MIS
MIS
MIS
OCR Customer Account Number
0x2449
MIS
MIS
MIS
MIS
MIS
MIS
OCR Dash
0x2448
MIS
MIS
MIS
MIS
MIS
MIS
OCR Double Backslash
0x244a
MIS
MIS
MIS
MIS
MIS
MIS
OCR Fork
0x2442
MIS
MIS
MIS
MIS
MIS
MIS
OCR Hook
0x2440
MIS
MIS
MIS
MIS
MIS
MIS
OCR Inverted Fork
0x2443
MIS
MIS
MIS
MIS
MIS
MIS


Code Page List

The following table summarizes all the Code Pages supported by the Recognition component. One of these must be specified as the Code Page of the final output document.

CODE PAGE NAME
WIDTH
SUPPL. INFORMATION
Windows ANSI
8-bit
Code Page 1252
Windows Greek
8-bit
Code Page 1253
Windows Eastern
8-bit
Code Page 1250
Windows Turkish
8-bit
Code Page 1254
Windows Baltic
8-bit
Code Page 1257
Windows Cyrillic
8-bit
Code Page 1251
Windows Esperant
8-bit
Non Standard Win
Windows OCR/MICR
8-bit
Non Standard Win
Windows E13B
8-bit
Non Standard Win
Code Page 437
8-bit
DOS Latin US
Greek-ELOT
8-bit
DOS Greek
Greek-MEMOTEK
8-bit
DOS Greek
Code Page 850
8-bit
DOS Latin 1
Code Page 852
8-bit
DOS Latin 2
Code Page 860
8-bit
DOS Portuguese
Code Page 863
8-bit
DOS French-Canadian
Code Page 865
8-bit
DOS Nordic
Code Page 866
8-bit
DOS Cyrillic CIS
CWI Magyar
8-bit
DOS Hungarian
Magyar Ventura
8-bit
DOS Hungarian
IVKAM C-S
8-bit
Czech & Slovak
Mazowia Polish
8-bit
DOS Polish
Sloven & Croat
8-bit
7 bits used
Turkish
8-bit
DOS Turkish
Icelandic
8-bit
DOS Icelandic
Macintosh
8-bit
Mac Western
Mac INSO Latin 2
8-bit
MAC CE
Mac Central EU
8-bit
PT 202
Mac Primus CE u
8-bit
MAC CE
Maltese
8-bit
Malta; 7 bits used
Unicode
16-bit
multilingual
WordPerfect
16-bit
multilingual
Roman 8
8-bit
For HP printers


Output Text Format List

The following table summarizes the output text formats available in the Recognition component. One of these can be specified as the format for the final output document.

NAME OF THE OUTPUT FORMAT
DESCRIPTION
"Text - Standard"
Text output with line break after each line. If table is present, its cells are positioned by TABs
"Text - Smart"
Text output with line break after each line. Left margin is taken into account (with SPACEs) If a table is present; its cells are positioned by SPACEs.
"Text - Stripped"
Text output with line break after each paragraph. If table is present, its cells are separated by TABs.
"Text - Plain"
Text output with line break after each line. Left and Upper margins are is taken into account (with SPACEs and NEWLINEs) If table is present, its cells are positioned by TABs.
"Text - Comma Delimited"
Comma delimited text output. Line/cell contents are surrounded by quotes (""). The default delimiter (comma) can be overwritten (see the REC_OUT.ini file)
"Text - Tab Delimited"
TAB separated text output. Line/cell contents are surrounded by quotes ("")
"Rec ASCII (Formatted)"
Text output, layout retention with mimicked SPACEs. Line/cell contents are surrounded by quotes ("")
"Rec ASCII (Standard)"
Text output allowing quick text conversion. Kept for compatibility reasons.
"Rec ASCII (StandardEx)"
Text output allowing quick text conversion. Line break after each line and after each zone. Kept for compatibility reasons.
"General Word Processor"
Text output allowing quick text conversion. Line break after each paragraph. Kept for compatibility reasons.
"HTML 3.2"
HTML output.HTML 3.2 is useful to export with PARTFORMAT. The output files support both IE and Netscape.
"HTML 4.0"
HTML output.HTML 4.0 can set the exact position/size of objects, use this output format with the FULLFORMAT option.
"Word 97, 2000, XP"
Microsoft Word 97, Word 2000 and Word XP output format.
"Excel 97, 2000"
Microsoft Excel 97 and Excel 2000 output format.
"WordPerfect 8"
WordPerfect 8 format.
"Rich Text Format"
Quick conversion to Rich Text Format.
"PowerPoint 97 (RTF)"
Rich Text Format for PowerPoint 97
"Publisher 98 (RTF)"
Rich Text Format for Publisher 98
"WordPad (RTF)"
Rich Text Format for WordPad
"RTF Word 2000"
Rich Text Format for Word 2000
"RTF Word 97"
Rich Text Format for Word 97
"RTF Word 6.0/95"
Rich Text Format for Word 6.0/95
"Open eBook 1.0"
Open eBook 1.0 format
"XML"
XML output format conforming with ScanSoft's schema file
SSDOC-SCHEMA2.xmlhttp:\\www.scansoft.com/omnipage/xml/SSDOC-SCHEMA2.xml
"2G Type 2"
Binary output of the recognition with a 16-byte long structure for each recognized character.2G Type 2 structure output
"2G Type 3"
Binary output of the recognition with a 16-byte long structure for each recognized character.2G Type 3 structure output


Language Dictionary List

The following table lists the languages available in the Recognition component's checking subsystem for spell checking. One of these can be specified as the spelling language, if desired.

SPELLING LANGUAGE
LANGUAGE DICTIONARY FILE
Catalan
R_CAT.DAT
Czech
R_CZH.DAT
Danish
R_DAN.DAT
Dutch
R_DUT.DAT
English
R_ENG.DAT
Finnish
R_FIN.DAT
French
R_FRE.DAT
German
R_GER.DAT
Greek
R_GRE.DAT
Hungarian
R_HUN.DAT*
Italian
R_ITA.DAT
Norwegian
R_NOR.DAT
Polish
R_POL.DAT*
Portuguese
R_POR.DAT
Russian
R_RUS.DAT
Slovenian
R_SLN.DMD
Spanish
R_SPA.DAT
Swedish
R_SWE.DAT


Vertical Dictionary List

The following table lists all the Vertical dictionaries available with the Recognition component.

PROFESSION
LANGUAGE
VERTICAL DICTIONARY FILE
Medical
Dutch
MEDICAL_DUT.DMD
Medical
English
MEDICAL_ENG.DMD
Medical
French
MEDICAL_FRE.DMD
Medical
German
MEDICAL_GER.DMD
Legal
Dutch
LEGAL_DUT.DMD
Legal
English
LEGAL_ENG.DMD
Legal
French
LEGAL_FRE.DMD
Legal
German
LEGAL_GER.DMD


Specifications for the recognition modules

Introduction

ImageGear Recognition component has multiple recognition modules, which can be applied on a per-zone basis. This allows a wide range of different types of textual and non-textual data to be recognized, even if they all appear on the same page. For each zone, the application can assign any module available in the configuration, or the choice of module can be left to the recognition engine.

NOTE: There is a general limitation of 22.75 inches in width and height for all OCR modules in ImageGear recognition engine.


Filling method - Recognition module combinations

When the value RM_AUTO is used, either by default or explicitly, the recognition engine takes care of recognition module selection for any filling method.

When setting specific values for filling methods and recognition modules, it is the programmer's responsibility to specify a valid recognition module-filling method pair. Any incorrectly set zone will have no recognition result.

The following table shows which modules are considered by the automatic recognition module selection, called up by the RM_AUTO value. The order of the recognition modules in the second column shows the priority order for the automatic recognition module selection.

Filling method
Permissible Recognition modules
FM_OMNIFONT
RM_OMNIFONT_PLUS3W, RM_OMNIFONT_PLUS2W, RM_OMNIFONT_MOR, RM_OMNIFONT_FRX, RM_OMNIFONT_MTX
FM_DRAFTDOT9
RM_DOT, RM_OMNIFONT_MTX
FM_BARCODE
RM_BAR
FM_OMR
RM_OMR
FM_HANDPRINT
RM_HNR, RM_RER
FM_DRAFTDOT24
RM_OMNIFONT_MOR, RM_OMNIFONT_MTX
FM_OCRA
RM_OMNIFONT_MOR, RM_OMNIFONT_MTX, RM_MAT
FM_OCRB
RM_OMNIFONT_MOR, RM_OMNIFONT_MTX, RM_MAT
FM_MICR
RM_MAT
FM_BARCODE2D
RM_BAR2D
FM_DOTDIGIT
RM_MAT
FM_DASHDIGIT
RM_MAT
FM_NO_OCR
-


Recognition modules and the widest available character set

The correct assignment of a recognition module and a filling method to a zone should mean that the recognition module is able to satisfactorily process the contents of that zone. But it does not guarantee that the recognition module will be able to process every possible character. The characters supported by the Recognition component are listed in Characters and Code Pages. Most recognition modules recognize only a subset of these. Even if we restrict the Character Set to a limited Language Environment e.g. selecting the German language, the recognition module may not be able to process all the enabled characters. E.g. HNR module is able to process hand printed numerals but does not recognize letters. Automatic recognition module selection takes Character Set support of modules into consideration. Selecting a recognition module directly, it is the programmer's responsibility to select a recognition module capable of supporting the widest character set enabled in the zone. Otherwise this zone may have an incomplete recognition result. The precise character and language support for each module is given in the appropriate recognition module specifications.


Recognition modules and filters

Narrowing the Character Set has two effects:

  • it influences the automatic recognition module selection
  • it may increase accuracy.

Narrowing the Character Set has two effects:

  • it influences the automatic recognition module selection
  • it may increase accuracy.

The filtering system allows the Language environment to be narrowed, by enabling only certain character classes, and also by enabling individual characters. A filter is built up from filter elements, as detailed under CHR_FILTER.

Each filter element name tells which character class is enabled, e.g. FILTER_ALL means no filtering. Not all recognition modules interpret all filter elements. Precise information appears in the sub-heading for each module.

Applying a filter may not always enable the same number of characters.

E.g. FILTER_MISCELLANEOUS can enable only those miscellaneous characters supported by the recognition module assigned to the zone.


Recognition modules and the trade-off settings

Three accuracy/speed trade-off settings can be specified on page or document level: TO_ACCURATE, TO_BALANCED and TO_FAST. Five recognition modules can interpret these. Precise information appears in the sub-heading for each module.


Recognition modules and the checking subsystem

The checking subsystem has two basic services. It can flag unacceptable recognition results without changing them or it can be permitted to modify recognition results using checking subsystem feedback. The available acceptance rules can come from the following:

  • Language and/or Vertical dictionaries,
  • User dictionaries containing precise entries and/or required patterns,
  • User-written checking functions.

These three sources may be combined freely. The checking subsystem and each of its three parts can be enabled or disabled on a per-zone basis.

The integrator should try to match the particular parts of the checking subsystem to the contents and recognition modules of individual zones, e.g. allowing checking changes with a language dictionary enabled will be either pointless or even harmful for the modules BAR, OMR and HNR, since it could change their numerical solutions to letters.


BAR bar code recognition module

  • Module name:BAR
  • Module identifier:RM_BAR
  • Filling methods supported:FM_BARCODE
  • Filters supported:ignores all filter settings
  • Trade-off supported:none
  • Knowledge base file:none
  • CSS-based correction:none
  • RM-spec file support:none
  • Training supported:none

Application areas

Recognition of one-dimensional bar codes.

Supported basic bar code types

  • Codabar (on by default),
  • Code 128 (on by default),
  • Code 39 (on by default),
  • EAN 8/13 (on by default),
  • ITF (2 of 5 interleaved) (on by default),
  • Postnet (off by default),
  • UPC (off by default)
  • UCC Code 128 (off by default).

Conditions

One zone can include only one bar code.

Postnet and any other type are mutually exclusive.

Similarly, the EAN and UPC types are mutually exclusive.

The thickness of bar code lines and the distance between them should be at least 3 pixels (that is a minimum line thickness of 0.25 mm (0.01 inch) in the case of 300 dpi resolution).

No parallel non-bar code lines of similar dimensions should be located less than 6 mm (0.25 inch) from the bar code.

The position of the bar code can be in any direction (except the Postnet code, where the maximum allowable skew of the bar code is 10°)

One zone can include only one bar code.

Though the zone can contain other pixel elements beside the bar code itself (the program is able to detect the bar code inside the zone), the preferred method of zoning is to define a zone, which entirely covers the bar code but does not include any other elements.

Output

The output is a string of digits giving the bar code value, plus optionally other checksum or start/stop digits. The precise input/output choices are:

  • Codabar,
  • Codabar with start-stop char transmit,
  • Code 128,
  • Code 39,
  • Code 39 with check digit control,
  • Code 39 with start-stop char transmit,
  • Code 39 full ASCII mode,
  • EAN 8/13,
  • EAN/UPC with 2 & 5 digit supplement,
  • ITF (2 of 5 interleaved),
  • ITF with check digit control,
  • Postnet,
  • UPC-A,
  • UPC-E 6 digit
  • UCC Code 128.

The maximum length of the coded information is 64 characters, except for ITF which supports up to 128 characters.

In LETTER structure output, the character size (width, height) and confidence data (err) information for each recognized character present bar code-level information, i.e. these values will be identical for all characters deriving from the bar code.


BAR2D bar code recognition module

  • Module name: BAR2D
  • Module identifier: RM_BAR2D
  • Filling methods supported: FM_BARCODE, FM_BARCODE2D
  • Filters supported: ignores all filter settings
  • Trade-off supported: TO_FAST, TO_BALANCED, TO_ACCURATE
  • Knowledge base file: none
  • CSS-based correction: none
  • RM-spec file support: yes (default: RM_BAR2D.ini)
  • Training supported: no

Application areas

This recognition module recognizes one-dimensional and two-dimensional bar codes, provided that BAR and BAR2D modules are properly licensed.

Supported one-dimensional bar code types

  • Codabar (on by default),
  • Code 128 (on by default),
  • Code 93 (on by default),
  • EAN 8/13 (on by default),
  • ITF (2 of 5 interleaved) (on by default),
  • Postnet (off by default),
  • UPC (off by default)
  • UCC Code 128 (off by default).
  • Code 2 of 5
  • Code 39

Supported two-dimensional bar code types

PDF-417 2D code

Conditions

By default, one zone can include up to ten bar codes.

The zone can contain other elements besides the bar code. The program is able to detect the bar code(s) inside a zone. If, however, there are many other objects (text, figures, etc.) in the zone, recognition will be slower and these other elements in the zone won't be recognized.

One-dimensional bar codes cannot be enabled together with 2-dimensional ones inside a single zone.

The two-dimensional PDF 417 bar code type is capable of storing 200 characters per square inch, up to 2000 characters in one code. It is used for document level indexing, form layout definition and encoding form data content.

Output

If there is no recognition result in the zone, then no valid or fragmented bar code was found in the zone.

If the recognition result for the zone is one or more rejected characters, then every rejection symbol represents a bar code fragment or one recognized with an incorrect checksum.

In structured data output (either Page.CharacterArray or Page.Characters properties), the character size (width, height) and confidence data (err) information for each recognized character present bar code-level information, i.e. these values will be identical for all characters deriving from the bar code.

The output for 1D barcodes is a string of digits giving the bar code value, plus optionally other checksum or start/stop digits. The precise input/output choices for 1D bar codes are:

  • Codabar,
  • Codabar with start-stop char transmit,
  • Code 128,
  • Code 39,
  • Code 39 with check digit control,
  • Code 39 with start-stop char transmit,
  • Code 39 full ASCII mode,
  • EAN 8/13,
  • EAN/UPC with 2 & 5 digit supplement,
  • ITF (2 of 5 interleaved),
  • ITF with check digit control,
  • Postnet,
  • UPC-A,
  • UPC-E 6 digit
  • UCC Code 128.
  • Code 2 of 5
  • Code 93


DOT 9-pin draft dot-matrix recognition module

  • Module name:DOT
  • Module identifier:RM_DOT
  • Filling methods supported:FM_DRAFTDOT9
  • Filters supported:all filter elements
  • Trade-off supported:none
  • Knowledge base file:TUDAS.FA
  • CSS-based correction:none
  • RM-spec file support:none
  • Training supported:yes

Application areas

This module is designed for ONLY draft-quality 9-pin dot-matrix texts. For NLQ or LQ texts, the RM_OMNIFONT_PLUS2W, RM_OMNIFONT_PLUS3W, RM_OMNIFONT_MTX or RM_OMNIFONT_MOR modules are likely to give better results.

Range of characters

This module supports 76 languages, of which 14 has dictionary support: Catalan, Danish, Dutch, English, Finnish, French, German, Greek, Hungarian, Italian, Norwegian, Portuguese, Spanish and Swedish. It can read multiple languages.

It can read 18 of the 29 punctuation characters. (The Low Double Comma Quotation Mark is missing). It supports 24 of the 55 miscellaneous characters. (Some missing ones are: the Euro Sign, the Small Script F, the Copyright Sign, Registered Trade Mark Sign and the Degree Sign.)

The following table lists all accented letters this module can recognize. The range of uppercase ones supported by this module is limited, since in 9-pin dot-matrix text, there is difficulty in printing these letters. Those with lowercase support only are listed separately:

Upper & Lowercase
Lowercase only
Cap.&Small A Acute (A')
Small A Circumflex (a^)
Cap.&Small AE (Ae)
Small A Macron (a-)
Cap.&Small A Ring (Ao)
Small A Grave (a`)
Cap.&Small A Umlaut (A:)
Small E Umlaut (e:)
Cap.&Small A Tilde (A~)
Small E Circumflex (e^)
Cap.&Small C Cedilla (C,)
Small E Grave (e`)
Cap.&Small E Acute (E')
Small I Umlaut (I:)
Cap.&Small I Acute (I')
Small I Circumflex (I^)
Cap.&Small N Tilde (N~)
Small I Grave (I`)
Cap.&Small O Double Acute (O")
Small O Circumflex (O^)
Cap.&Small O Acute (O'
Small O Macron (O-)
Cap.&Small O Umlaut (O:)
Small O Grave (O`)
Cap.&Small O Tilde (O~)
Small S Hacek (Sv)
Cap.&Small O Slash (O/)
Small U Circumflex (U^)
Cap.&Small AE(OE)
Small U Grave (U`)
Cap.&Small U Double Acute (U")
Cap.&Small U Acute (U')
Cap.&Small U Umlaut (U:)

Accuracy issues

This module does not interpret the recognition trade-off setting and cannot be trained.

Character attributes

Since this module recognizes draft dot-matrix texts, character attributes are not applicable. Expanded characters are not recognized, condensed printout can be, but the accuracy is liable to be low.

Conditions

This module is used if it is directly specified in a zone structure.

If FM_DRAFTDOT9 filling method is set together with RM_AUTO, RM_OMNIFONT_MTX is used, provided that all characters (or languages or filters) validated for the zone are supported by it. If any are not supported, this module is used.

It can generate confidence data on recognized characters and can interpret all filter values.


FRX multi-lingual omnifont recognition module

  • Module name: FRX
  • Module identifier: RM_OMNIFONT_FRX
  • Filling methods supported: FM_OMNIFONT
  • Filters supported: ignores all filter settings
  • Trade-off supported: none
  • Knowledge base files: none
  • CSS-based correction: none
  • RM-spec file support: none
  • Training supported: yes

Application areas

This module recognizes machine printed text; i.e. from printed publications, laser or ink-jet printers and electric typewriters. Output from mechanical typewriters in good condition may also be acceptable. It should also be used for letter or near letter quality (NLQ, LQ) output from dot-matrix printers.

Range of characters

This module supports the recognition of Latin, Greek and Cyrillic alphabets with enough accented letters to recognize the 54 languages (Languages and modules)

The characters are listed in category and alphanumeric order, together with their Code Page values, in Characters and Code Pages.

Multi-lingual language support

The language support of this module is based on the module's internal code pages, which contain characters from a related group of languages. The internal code pages of this module are American/European, Baltic, Central-European, Cyrillic, Greek and Turkish.

The module supports multi-language selection for recognition, though it may not recognize languages from different language groups properly.

Character attributes

The omnifont recognition module can detect and transmit character attributes: bold, italic or underlined text (or any combination of them). It can also detect and transmit character size, and can classify font types into three broad categories: serif, sans serif and monospaced.


HNR handprinted numeral recognition module

  • Module name: HNR
  • Module identifier: RM_HNR
  • Filling methods supported: FM_HANDPRINT
  • Filters supported: FILTER_ALL, FILTER_DIGIT, FILTER_PUNCTUATION and FILTER_MISCELLANEOUS
  • Trade-off supported: TO_FAST, TO_ACCURATE (includes TO_BALANCED)
  • Knowledge base file: KEZIRSTR.TBS
  • CSS-based correction: supported
  • RM-spec file support: none
  • Training supported: no

Application areas

This recognition module can be used for recognition of handprinted numerals and four additional signs. If further handprinted characters are to be recognized, the use of the RM_RER recognition module is recommended.

Range of characters

This recognition module can recognize the following handprinted characters:

  • the digits (0-9),
  • the Plus Sign (+)
  • the Minus Sign (-)
  • the Period or Full-stop (.)
  • the Comma (,).

The filter FILTER_DIGIT can be used to exclude the last four characters. The filters FILTER_PUNCTUATION and FILTER_MISCELLANEOUS function, other filters have no effect.

Accuracy issues

The functioning of the module can be influenced with the following parameters:

Recognition trade-off settings:

The page-level trade-off value TO_FAST is respected, while TO_ACCURATE and TO_BALANCED are merged to a single value.

Writing style:

STYLE_EURO
lets you specify European styled numbers,
STYLE_US
lets you specify North-American styled numbers.

Character box flag:

  • This lets you pass information to the recognition module on the positions of characters to be recognized, which is likely to improve accuracy. If a zero value is given, the recognition module will determine the positions automatically.

Space inclusion flag:

  • This lets you set whether spaces detected between the recognized characters should be transmitted or not.

Conditions

For successful recognition, the characters should not touch each other. Each character can be zoned individually or a zone may contain several lines of characters. Each character must have a height of 30-180 pixels. Well-formed numbers written in pen are best recognized. Pencil and felt-tip pens give poorer results. When reading from pre-printed forms, dropout colored boxes can be useful to encourage respondents to write numbers of even size and spacing. But then, they mustn't use a pen with the dropout color!

Optimum box size for such cases is 5 x 6 mm separated by 3 mm.

Maximum number of characters in a zone: 3000.

Maximum number of lines in a zone: 40.

Maximum number of characters in a line: 600.

Output

This can consist of the digits, the four additional characters, rejection symbols and, if requested, spaces.

The HNR module can benefit from the checking subsystem to improve recognition accuracy, by encouraging output to conform to the systems' pre-defined requirements. But note that spell checking from a language dictionary should be disabled. For zones whose contents are known to be limited in some way, a set of permitted numerical strings or patterns pre-defined in a User dictionary, or some other user-written checking could be very useful.


MAT matrix matching recognition module

  • Module name: MAT
  • Module identifier: RM_MAT
  • Filling methods supported: FM_OCRA, FM_OCRB, FM_MICR, FM_DOTDIGIT, FM_DASHDIGIT
  • Filters supported: all elements except FILTER_LOWERCASE
  • Trade-off supported: none
  • Knowledge base file: SFOCR.TUD
  • CSS-based correction: supported
  • RM-spec file support: yes (default: RM_MAT.ini)
  • Training supported: no

Application areas

This module is designed to read certain groups of fixed-font characters specially designed for OCR or imaging applications, in which no two characters have similar shapes. Each character group has its own filling method. Application areas are in banking, check or waybill handling, product distribution and document validation, where high accuracy can be vital. It also handles some non-fixed print styles.

Range of characters

  • FM_OCRA

OCR-A. Uppercase English letters (26), digits, some punctuation (see Characters (punctuation / miscellaneous) and modules) and 3 special OCR-A symbols:

    • OCR Chair,
    • OCR Hook,
    • OCR Fork.
  • FM_OCRB

OCR-B. Uppercase English letters (26), digits and some punctuation.

  • FM_MICR

MICR (E-13B). Digits plus some punctuation and 4 special MICR symbols:

    • OCR Branch Bank,
    • OCR Amount of Check,
    • OCR Dash,
    • OCR Customer Account Number.
  • FM_DOTDIGIT

Ten digits only and the period. Commas are also read, but converted to periods. Though this is in theory a fixed-font, many variants of it are used.

  • FM_DASHDIGIT

Ten digits only and the period. Commas are also read, but converted to periods. Though this is in theory a fixed-font, many variants of it are used.

Accuracy issues

When this module is handling fixed fonts, well printed on a firm surface, with a limited number of possible characters, it should provide high accuracy recognition. This can be further enhanced by use of regular expressions (UD-checking) or user-written checking available through the checking subsystem. This module doesn't interpret the page-level recognition trade-off settings. This recognition is fairly tolerant of differing resolution settings. The dot- and dash-digit symbols are typically printed onto product containers, which may be curved or molded; furthermore many different standards are used. For high accuracy here, the texts to be read should be found on flat surfaces (on packing documents rather than product containers).

Conditions

This module supports the checking subsystem fully, and also all filter elements (however, FILTER_LOWERCASE will have no effect). Characters should be at least 4 x 8 pixels large and should not be touching. FM_OCRA and FM_OCRB support both single and multi-line zones, the other filling methods (FM_MICR, FM_DOTDIGIT and FM_DASHDIGIT) do not: each line must be zoned separately.

MICR strings found on checks are usually single-line only.

Zones with FM_OCRA or FM_OCRB filling method can have either single or multi-line content. By default, for these types of zones, the MAT recognition modules assume multi-line content.


MOR multi-lingual omnifont recognition module

  • Module name: MOR
  • Module identifier: RM_OMNIFONT_MOR
  • Filling methods supported: FM_OMNIFONT, FM_DRAFTDOT24, FM_OCRA, FM_OCRB
  • Filters supported: all filter elements
  • Trade-off supported: TO_FAST, TO_BALANCED, TO_ACCURATE
  • Knowledge base files: RECOGN.BCT and RECOGN24.BCT
  • CSS-based correction: supported
  • RM-spec file support: none
  • Training supported: yes
NOTE: This module can safely handle A3 size (11.69" x 16.54") both portrait and landscape images with 300 dpi resolution.

Application areas

This module recognizes machine printed text; i.e. from printed publications, laser or ink-jet printers and electric typewriters. Output from mechanical typewriters in good condition may also be acceptable. It should also be used for letter or near letter quality (NLQ, LQ) output from dot-matrix printers. There are two ways of modifying incoming images to make them more suitable for this omnifont recognition module:

Standard mode Fax output. (200 x 100 dpi). This switch doubles the pixels in the image's vertical direction. Faxes sent in Fine Mode (200 x 200 dpi) are preferable; then this switch shouldn't be used.

Draft 24-pin dot-matrix output. Use the FM_DRAFTDOT24 filling method to have the character contours smoothed. Again, NLQ or LQ quality output can usually be better recognized without using FM_DRAFTDOT24.

This module can safely handle A3 size (11.69" x 16.54") both portrait and landscape images with 300 dpi resolution.

The max. number of zones defined on an image that this module can handle is 500.

Range of characters

This module can recognize about 500 characters, termed Recognition component's Total Character Set. It includes the letters of the Latin, Greek and Cyrillic alphabets with enough accented letters to recognize the 114 Languages supported by the Recognition component.

The set is classified as follows:

Non-accented
Accented
Latin alphabet upper case letters
26
89
Latin alphabet lower case letters
26
91
Digits
10
Punctuation
29
Miscellaneous (maths symbols etc.)
55
Cyrillic upper case letters
33
14
Cyrillic lower case letters
33
14
Greek upper case letters
24
9
Greek lower case letters
25
11
OCR (OCR-A / MICR) characters
3

The characters are listed in category and alphanumeric order, together with their Code Page values, in Characters and Code Pages. These are the character categories used by the filter elements. The pre-trained OCR characters are: OCR Chair, OCR Hook, OCR Fork.

Character attributes

The omnifont recognition module can detect and transmit character attributes: bold, italic or underlined text (or any combination of them). It can also detect and transmit character size, and can classify font types into three broad categories: serif, sans serif and monospaced.

Speed/Accuracy choices

The multi-lingual omnifont recognition module basically uses contour analysis, but can supplement this with an innovative form of pattern matching not requiring enormous pre-stored shape libraries.

This module interprets all three page-level recognition trade-off settings: TO_ACCURATE, TO_BALANCED and TO_FAST.

The module is tightly integrated with the checking subsystem, giving a total of five speed/accuracy choices.

  • Level 1: TO_FAST without checking.

Fastest. The module reads text once and uses feature extraction only. Even this setting can give excellent accuracy on high-quality documents. Recommended also when accuracy is not a big issue (e.g. when OCR is only to allow fuzzy keyword searching in a document retrieval system) or for high-volume work when processing speed is most important.

  • Level 2: TO_FAST with checking.

The recognition module reads text only once, with feature extraction, but sends words containing suspect or reject characters to a checker, together with its first and second guesses for unsure characters. The checker tries to find solutions based only on those characters. It also tries to repair other typical OCR faults (e.g. di9its embedded in words) and will flag all non-dictionary words it was unable to solve. Recommended e.g. when a Language dictionary is available and the texts are mono-lingual and liable to contain normal language (if not, a User dictionary could be employed).

  • Level 3: TO_BALANCED without checking.

Two-pass recognition. During the first pass with feature extraction, the program builds up a library of sample characters and ligatured character pairs from the page, whose recognition was very sure. During the second reading pass it stops on all reject and unsure characters, consults its library and uses pattern matching to try and find solutions. That's why the second pass is not very useful for pages with very little text - the library is too small. Recommended for multi-lingual documents or when a checker is not available. (-14% errors + 15% time compared to TO_FAST without checking)

  • Level 4: TO_BALANCED with checking.

Two-pass recognition. Reading is a combination of the two processes used in levels 2 and 3. More accurate but processing will take more time. (-24.5% errors + 28% time compared to TO_FAST without checking)

  • Level 5: TO_ACCURATE with checking compulsory.

Most accurate but slowest. Designed for use on very degraded mono-lingual documents or when maximum accuracy is very important. It involves two-pass recognition with Adaptive Cell Analysis. This is used to get a bigger library for the pattern matching: uniformly highly degraded documents typically can't yield enough surely recognized characters to form a useful library. With ACA recognition, characters with somewhat lower certainty are accepted, provided they fall within words accepted by the checking subsystem. This allows the pattern matching to work more successfully. (-27.5% errors + 62% time compared to TO_FAST without checking)

NOTE: Accuracy and time data was measured on an English magazine sample collection, 986 pages, 3.6 million characters.


MTX omnifont recognition module

  • Module name: MTX
  • Module identifier: RM_OMNIFONT_MTX
  • Filling methods supported: FM_OMNIFONT, FM_DRAFTDOT9, FM_DRAFTDOT24, FM_OCRA, FM_OCRB
  • Filters supported: FILTER_ALL, FILTER_DIGIT and FILTER_ALPHA
  • Trade-off supported: TO_FAST, TO_ACCURATE (includes TO_BALANCED)
  • Knowledge base file: N / A
  • CSS-based correction: language dictionary only
  • RM-spec file support: none
  • Training supported: yes
NOTE: Only images with the following resolution ranges are supported: 90-110, 160-240, 280-320, 400, 600. This module does not process images larger than 6600 pixels in either width or height, that is it can safely handle A3 size (11.69" x 16.54") both portrait and landscape images with 300 dpi resolution. At larger resolution the supported image size is smaller.

Application areas

This recognition module recognizes machine printed text; i.e. from printed publications, laser or ink-jet printers and electric typewriters. Output from mechanical typewriters in good condition may also be acceptable. It should also be used for Letter or Near Letter Quality output from dot-matrix printers, and can also be used for Draft Quality.

Only images with the following resolution ranges are supported: 90-110, 160-240, 280-320, 400, 600.

This module does not process images larger than 6600 pixels in either width or height, that is it can safely handle A3 size (11.69" x 16.54") both portrait and landscape images with 300 dpi resolution. At larger resolution the supported image size is smaller.

The max. number of zones defined on an image that this module can handle is 64.

Range of characters

This module supports the characters of the following languages

Language
Language identifier
English
LANG_ENG
French
LANG_FRE
Spanish
LANG_SPA
Italian
LANG_ITA
German
LANG_GER
Norwegian
LANG_NOR
Portuguese
LANG_POR
Danish
LANG_DAN
Dutch
LANG_DUT
Finnish
LANG_FIN
Swedish
LANG_SWE
Brazilian
LANG_BRA

Any of these languages can be combined.

Accuracy issues

This module is influenced by the page-level trade-off setting, but reduces the three settings to two: TO_FAST is respected, while TO_BALANCED and TO_ACCURATE merge to one value.

Character attributes

The omnifont recognition module can detect and transmit character attributes: bold, italic or underlined text (or any combination of them). It can also detect and transmit character size, and can classify font types into three broad categories: serif, sans serif and monospaced.


OMR optical mark recognition module

  • Module name: OMR
  • Module identifier: RM_OMR
  • Filling methods supportedFM_OMR
  • Filters supported: ignores all filter settings
  • Trade-off supported: none
  • Knowledge base file: none
  • CSS-based correction: none
  • RM-spec file support: none
  • Training supported: no

Application areas

This recognition module is used for recognizing optical marks (checkmarks). Typical application areas are in questionnaires, ballot papers, educational tests and reporting or ordering sheets, where the documents to be processed are form-like and filled by respondents, usually by hand.

Accuracy issues

Checkmark zones are bounded by printed frames, which are visible on the input document, but may be visible or invisible in the image passed to the recognition module, due to the use of dropout colors during scanning. The accuracy of this module can be improved by

  • specifying in advance how the module will handle frame detection (frames visible, frames invisible, auto-detect)
  • specifying the "marking sensitivity" of the module, i.e. how strongly an OMR zone must be marked to count as filled. There are four choices.

The values "frames visible" and "frames invisible" give higher accuracy than "auto-detect". This recognition module is not influenced by the recognition trade-off setting.

See also the topic "Instructions to respondents" below.

Conditions

The frame can be a rectangle, a circle, an ellipse, etc.; it can be shaded. It may be visible or invisible in the image sent for recognition. The dimension of the frame should be at least 45-50 pixels in each direction, that is 3.5 to 4 mm (0.2 inch) in the case of 300 dpi resolution.

  • If there is a frame visible in the image: it can be filled in by any shape such as an X, a tick, non-solid hatching, horizontal or vertical lines, etc.). The recommended filling shape is an X or a tick. A small number of contiguous black pixels falling within the checkmark area will lead to a value "filled". The recommended scanner brightness setting is slightly darker than 50%.
  • If there is no frame visible in the image: it should be filled so that the checkmark shape could not be mixed with a frame or half-frame, i.e. no lines parallel to the invisible zone borders. The filling shape should be a clear X or a tick.

This module has been tested on an image with more than 1300 OMR zones.

Output

An OMR (optical mark) zone is unique in that its output always consists of precisely one digit. The output generated for checkmark zones is always zero (0) for unchecked and one (1) for checked ones.

The safest way to link the output values with the checkboxes, which generated them, is through the structured data output ((either Page.CharacterArray or Page.Characters properties)), which contains the zone number and the coordinates (zone, left, top, width, height). This can also help prevent checkmark data being confused with bar code values or other non-checkmark data coming from the same page.

If a page contains mainly or only checkmark data, the output converters "Text - Tab Delimited", "Text - Comma Delimited" or the "Excel 97, 2000" can be used to load the data into a spreadsheet program for further analysis and presentation.

Instructions to respondents

OMR processing requires a high degree of accuracy. The two-value detection is inherently accurate; three-value detection is more difficult. Good document design and clear instructions to respondents are very important in getting high accuracy. Printing model samples of ideally filled and filled-in-error checkboxes in the instructions is recommended. Respondents should be urged to fill in the document with a dark blue or black pen. Pencils are to be avoided, as are pens with an ink color close to a dropout color on the scanner to be used.


PLUS2W and PLUS3W omnifont recognition modules

  • Module name: PLUS2W and PLUS3W
  • Module identifier: RM_OMNIFONT_PLUS2W and RM_OMNIFONT_PLUS3W
  • Filling methods supported:FM_OMNIFONT
  • Filters supported: FILTER_ALL, FILTER_DIGIT and FILTER_ALPHA
  • Trade-off supported: TO_FAST, TO_BALANCED, TO_ACCURATE
  • Knowledge base file: RECOGN.BCT, RECOGN24.BCT and OURDICT.DAT
  • CSS-based correction: supported
  • RM-spec file support: none
  • Training supported: yes

Application areas

This recognition module recognizes machine printed text; i.e. from printed publications, laser or ink-jet printers and electric typewriters. Output from mechanical typewriters in good condition may also be acceptable.

Range of characters

This module supports the same set of characters as the OMNIFONT_MOR module.

Accuracy issues

The PLUS2W and PLUS3W modules use voting technology to provide improved recognition result.

The PLUS2W module combines the results from the MOR and MTX modules.

The PLUS3W module combines the results from the MOR, MTX and FRX modules.

With any of these two voting modules, the accuracy is considerably better, but the recognition may need significantly more time than any single module.

Suspicious marking

With these modules, the suspicious character and word marking feature is different from that used in MOR, MTX or FRX.

These modules do not mark characters as suspicious if all the voting modules provided the same recognition result, even if in any of them they were suspiciously recognized. Consequently, the number of words marked as non-dictionary, may be less.

Character attributes

The omnifont recognition module can detect and transmit character attributes: bold, italic or underlined text (or any combination of them). It can also detect and transmit character size, and can classify font types into three broad categories: serif, sans serif and monospaced.


RER handprinted recognition module

  • Module name: RER
  • Module identifier: RM_RER
  • Filling methods supported:FM_HANDPRINT
  • Filters supported: all filter elements
  • Trade-off supported: TO_ACCURATE, TO_FAST (includes TO_BALANCED)
  • Knowledge base file: HAND.REC
  • CSS-based correction: none
  • RM-spec file support: yes (default: RM_RER.ini)
  • Training supported: no

Application areas

This recognition module can be used for recognition of handprinted alphanumerical characters, i.e. upper and lower case letters, the digits and some others. Although it can be used to read flowing text, its main application area is in form-like situations, where the form designer has great control over the content and maybe length of handprinted information given in each zone.

Range of characters

This module can differentiate 159 characters. These are the digits, 28 punctuation and miscellaneous characters (listed below), letters of the English alphabet plus all accented characters necessary for 98 languages. Fifteen languages have dictionary support: Catalan, Czech, Danish, Dutch, English, Finnish, French, German, Hungarian, Italian, Norwegian, Polish, Portuguese, Spanish and Swedish. Other supported languages include Croatian (with one limitation), Estonian, Gaelic, Indonesian, Latvian, Lithuanian, Slovak, Slovenian, Swahili, Tagalog, Turkish and Welsh (the last two with minor limitations). Cyrillic languages and Greek are not supported. In Hungarian the lower case characters "Small I Acute", "Small O Acute" and the "Small U Acute" are not supported, in effect limiting recognition to upper case characters. These languages can be freely combined, but then dictionary support is not available.

The following punctuation characters can be recognized:

  • ! Exclamation Mark
  • ? Question Mark
  • ` Apostrophe-Quote
  • "Quotation Mark
  • : Semicolon
  • , Comma
  • : Colon
  • . Period (Full-stop)
  • - Hyphen-Minus
  • ( Opening Parenthesis
  • ) Closing Parenthesis
  • [ Opening Square Bracket
  • ] Closing Square Bracket
  • { Opening Curly Bracket
  • } Closing Curly Bracket

The following miscellaneous characters can be recognized:

  • # Number Sign
  • % Percent Sign
  • @ Commercial At
  • & Ampersand
  • | Vertical Bar
  • $ Dollar Sign
  • * Asterisk
  • + Plus Sign
  • = Equals Sign
  • _ Spacing Underscore
  • / Slash
  • \ Backslash
  • < Less-Than Sign
  • > Greater-Than Sign

Note that language-specific knowledge base files are also distributed as listed in the table below. These files have names in form HAND??.REC, whereas the double question mark within the filename is to be replaced by a country code as follows:

Code
Language(s) / Territory
AL
Albanian
AT
Austrian, German
BE
Belgian, Dutch, French, German
CH
Swiss, French, German, Italian
CS
Czech, Slovakian
CZ
Czech
DE
German
DK
Danish
EE
Estonian
ES
Spanish
EU
West-European
FI
Finnish
FR
French
HU
Hungarian
IE
Irish, English, Gaelic Irish
IT
Italian
LT
Lithuanian
NL
Dutch
PL
Polish
SE
Swedish
SF
Suomi Finnish
SL
Slovenian
SK
Slovakian
TR
Turkish
US
USA

Using language-specific knowledge base file(s) may improve accuracy.

Accuracy issues

Handprint is much harder to recognize accurately than machine generated text, and success depends very heavily on character quality.

The use of structured forms to limit the possible range of characters, together with zone-level filters and individual character validation can significantly improve accuracy. This recognition module can apply all the Recognition component's possible filter elements to the 159-member character set it supports.

Handprinted forms are usually filled by different respondents and this is liable to lower accuracy. If respondents can be given clear filling instructions (e.g. a print model to follow) and be motivated to print clearly, success will be higher.

If the handprint contains numbers only, using the HNR module is likely to give better results than the RER module filtered for numbers only.

The functioning of the module can be influenced by the page-level trade-off settings: TO_ACCURATE is respected, while TO_FAST and TO_BALANCED are merged.

Conditions

For successful recognition, the characters should not touch each other. Each character can be zoned individually or a zone may contain one or more lines of characters. Each character must have a height of 30-180 pixels. Well formed characters written in pen are best recognized. Pencil and felt-tip pens give poorer results. When reading from pre-printed forms, dropout colored boxes can be useful to encourage respondents to write characters of even size and spacing. But then, they mustn't use a pen with the dropout color.

Maximum number of characters in a line: 200.

Number of lines in a zone: No restriction.


Appendix: DIB Pointer Transition Guide for ImageGear

The functions which provided pointers to an image's DIB - IG_image_DIB_ptr_get and IG_image_DIB_bitmap_pntr_get - have been removed from ImageGear as of version 14.5. This guide explains why these functions were removed, what they did, and how to work without them.


Reasons for API Changes

ImageGear 14.5 introduced support for native storage and processing of images with high bit depths, a variety of color spaces, and flexible channel configuration (flexible channel depths, flexible number of channels). To provide this support, it was necessary to abandon the relatively limited Windows DIB format for internal storage of images. Its header could not describe all of the necessary properties of an image and was not extensible enough. Since the Windows DIB format is no longer used for internal storage, the function IG_image_DIB_ptr_get had been removed. Instead, a new DIB storage system is used and the API has been revised to accommodate it.

The function IG_image_DIB_bitmap_pntr_get was removed to intentionally break code that relied on the old storage system. It has been replaced by IG_image_DIB_raster_pntr_get, which can be used in the same way as IG_image_DIB_bitmap_pntr_get by asking for the first raster in the image.


Summary of Changes

Here are some changes and implications resulting from adoption of the new storage system:

  • There is no BITMAPINFOHEADER / AT_DIB struct maintained in a HIGEAR.
  • Functions which formerly took a DIB header struct as a parameter have been modified to take a HIGDIBINFO handle (more info in the next section).
  • DIB import and export support has been improved and expanded.
  • Alpha and extra channels are stored together with color channels on a per-pixel basis.
  • A new type is used for color space IDs (enumIGColorSpaceIDs) which contains information about color, alpha, and extra channels.
  • New color spaces can be stored natively, such as LAB and YUV.
  • CMYK is no longer a special case and is stored like any other color space.
  • Channel depths can range from 1 to 32 bits, and there is no requirement that channels have equal depths - for example, 5-6-5 16-bit RGB can be stored.
  • Rasters are stored internally from top to bottom. (DIB was bottom-up)
  • RGB pixel data is stored internally in RGB order. (DIB used BGR order)
  • 1-bit images are always stored internally in compressed format. They are compressed and decompressed as needed, for example during DIB import/export and pixel access.


Getting a Pointer to the DIB (the old way)

ImageGear versions prior to 14.5 used the standard Windows DIB format for internal storage of images. This format is made up of three components which are stored sequentially:

  1. Header. This is a BITMAPINFOHEADER / AT_DIB struct containing the following information about a DIB:
struct tagAT_DIB
{
    AT_DWORD    biSize;
    AT_INT32    biWidth;
    AT_INT32    biHeight;
    AT_WORD     biPlanes;
    AT_WORD     biBitCount;
    AT_DWORD    biCompression;
    AT_DWORD    biSizeImage;
    AT_INT32    biXPelsPerMeter;
    AT_INT32    biYPelsPerMeter;
    AT_DWORD    biClrUsed;
    AT_DWORD    biClrImportant;
};
typedef struct tagAT_DIB AT_DIB;
typedef struct tagAT_DIB FAR *LPAT_DIB;

The removed function IG_image_DIB_ptr_get retrieved a pointer to this struct.

  1. Palette. This is an array of RGBQUAD entries containing the colors that correspond to pixel values in an indexed image. The number of entries in this array is determined by the bit depth of the image (biBitCount). A palette is only stored for indexed images.

The function IG_image_DIB_palette_pntr_get retrieves a pointer to this array. This function still exists in ImageGear 14.5, but the DIB header and pixel data no longer surround the palette in memory.

  1. Pixel data. This is the pixel data that actually makes up the image. The image rows are stored bottom-up and each row is DWORD-aligned. In the case of a 24-bit RGB image, the pixels are stored in BGR channel order.
NOTE: The removed function IG_image_DIB_bitmap_pntr_get retrieved a pointer to this data. However, you can use IG_image_DIB_raster_pntr_get to get a pointer to pixel data for a given raster. And, since rasters are stored sequentially in memory, you can get a pointer to the first raster (raster 0) and use it to access the entire image.


The DIB Info Object - HIGDIBINFO

Formerly, you could get a pointer to an image's DIB using IG_image_DIB_ptr_get and read information about it from the DIB header. This is no longer possible. A new "DIB info" object is now used instead of a DIB header struct. This object contains most of the information that was in the DIB header, plus new information introduced in ImageGear 14.5. A DIB info object is handle-based and its handle type is HIGDIBINFO. This is similar to a HIGEAR, file handle, GDI/kernel object handle, etc. Typical DIB info object workflow is as follows:

  1. Call a function to create the DIB info object (from a HIGEAR or from scratch). You will get a handle of type HIGDIBINFO. You will always have ownership of the object, so you will be responsible for deleting it.
  2. Pass the HIGDIBINFO handle to functions in the DIB Info Services group, such as IG_DIB_width_get, IG_DIB_colorspace_get, etc. to retrieve information. Or, pass the HIGDIBINFO handle to other functions that formerly took AT_DIB as a parameter, such as IG_image_create.
  3. Call IG_DIB_info_delete to delete the DIB info object when you've finished using it.
NOTE: A DIB info object can also, optionally, contain palette data. So the DIB info object replaces not only the DIB header, but also the palette. But this palette is separate from the palette in a HIGEAR. See the IG_DIB_palette_* functions for more information.
NOTE: A DIB info object DOES NOT contain pixel data. Pixel data is associated with a HIGEAR, not a HIGDIBINFO.


Retrieving DIB Information

If you formerly retrieved information about an image by getting a pointer to the DIB and reading from the DIB header, refer to this table to see how to get the same information in other ways:

DIB header field
From a HIGEAR...
From a HIGDIBINFO...
biSize
N/A
N/A
biWidth
IG_image_dimensions_get
IG_DIB_width_get
biHeight
IG_image_dimensions_get
IG_DIB_height_get
biPlanes
N/A
N/A
biBitCount* (see following sections)
IG_image_dimensions_get, IG_DIB_legacy_bit_depth_get
IG_DIB_bit_depth_get, IG_DIB_channel_count_get + IG_DIB_channel_depths_get
biCompression* (see following sections)
IG_image_colorspace_get,
IG_image_compression_type_get
IG_DIB_colorspace_get
biSizeImage
N/A
N/A
biXPelsPerMeter
IG_image_resolution_get
IG_DIB_resolution_get
biYPelsPerMeter
IG_image_resolution_get
IG_DIB_resolution_get
biClrUsed
N/A
N/A
biClrImportant
N/A
N/A

Note that you need a HIGDIBINFO handle for all functions in the right column of this table. Here's an example of how to get one from a HIGEAR, get some information, and clean up:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIBInfo;    /* DIB info handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_DIMENSION width;     /* Returned width of image */
nErrcount = IG_image_DIB_info_get(hImage, &hDIBInfo);
width = IG_DIB_width_get(hDIBInfo);
IG_image_DIB_info_delete(hDIBInfo);


biBitCount - Retrieving Bit Depths

Be careful when considering the bit depth of an image. IG_image_dimensions_get will always return the true bit depth (number of bits per pixel) of the image as stored internally by ImageGear. Since ImageGear can now store images with higher bit depths, and it stores alpha channels and extra channels in-line with the color channels, this number may be higher than you expect.

For example, consider the case where you call IG_image_dimensions_get and get a value of 32 for the bit depth. This means that 32 bits are used to represent each pixel in the image. In the past, this meant that the image was CMYK. But now it could also mean that the image is 24-bit RGB with an 8-bit alpha channel. It's also possible to see new bit depths like 36 or 48 for images with higher bit depths.

If you need to know the bit depth as reported by IG_image_dimensions_get in versions of ImageGear prior to 14.5, call IG_DIB_legacy_bit_depth_get. This is the bit depth you'll be using if you're using pixel access functions in the legacy mode, which is the default mode in 14.5.

If you need to know the bit depths of specific channels in the image, and/or what types of channels are present, use the following functions:

  • IG_image_colorspace_get
  • IG_DIB_channel_count_get
  • IG_DIB_channel_depth_get / IG_DIB_channel_depths_get


biCompression - Retrieving Compression Type / Color Space

Prior to 14.5, biCompression was used as a means of extending the Windows DIB header to include information about other compression types and color spaces. Possible values are listed in the enumIGBiCompression enumeration in accucnst.h. Some examples are things like IG_BI_RGB, IG_BI_CMYK, IG_BI_GRAYSCALE, IG_BI_RLE, and so on.

In 14.5, the BITMAPINFOHEADER / AT_DIB struct is no longer used, so there's no biCompression. However, this value can still be retrieved by using the function IG_image_compression_type_get. It retrieves the same kind of value that biCompression held (from enumIGBiCompression). Note, however, that a new value was added to this enumeration: IG_BI_EXT. IG_image_compression_type_get will return this value if the image cannot be sufficiently described by any of the old enumeration values. Some examples of images for which IG_BI_EXT is returned are 1) an image with an alpha channel and 2) a 36-bit RGB image.

Instead of retrieving an image's "compression type", which has really been used more like "image type", you should consider retrieving the image's color space instead. In 14.5, you can get an image's color space by calling IG_image_colorspace_get. What you get back is a color space ID. This ID is made up of one or more values from the enumIGColorSpaceIDs enumeration defined in accucnst.h. A color space ID is a bitfield, so it can contain one or more of the following pieces of information:

  • The image's color space (indexed, RGB, CMYK, LAB, etc)
  • Whether or not an alpha channel is present
  • Whether or not at least one extra channel is present

To isolate the piece of information you're interested in, you must use a bitmask such as IG_COLOR_SPACE_ID_ColorMask.

Consider the following sample function which determines whether or not an image is bitonal:

// Is the given image bitonal? (1 bit per pixel for color
channel)
BOOL isBitonal(HIGEAR hImage)
{
    // The color space must be indexed
    enumIGColorSpaceIDs cs;
    IG_image_colorspace_get(hImage, &cs);
    if ((cs & IG_COLOR_SPACE_ID_ColorMask) !=
IG_COLOR_SPACE_ID_I)
        return FALSE;
    // The color channel must have a depth of 1
    HIGDIBINFO hDIB;
    IG_image_DIB_info_get(hImage, &hDIB);
    AT_INT depth = IG_DIB_channel_depth_get(hDIB, 0);
    IG_DIB_info_delete(hDIB);
    if (depth != 1)
        return FALSE;
    return TRUE;
}


Method 1: Exporting and Importing DIBs

If you were previously getting a pointer to an image's DIB and accessing it directly, one alternative available to you is to export the image from a HIGEAR to a DIB, work with the DIB the same way you did before, and import it when you're finished. ImageGear 14.5 provides the following new functions to export/import images between a HIGEAR and a DIB in memory:

  • IG_image_DIB_export_size_calc
  • IG_image_DIB_export
  • IG_image_DIB_import

    • Old Workflow
    New Workflow
    1) Get pointer to DIB with IG_image_DIB_ptr_get
    2) Read/write data in DIB
    1) Calculate total size of DIB with IG_image_DIB_export_size_calc
    2) Allocate memory to hold exported DIB
    3) Export DIB with IG_image_DIB_export
    4) Read/write data in DIB
    5) Import DIB with IG_image_DIB_import

See the API reference documentation for these new functions for instructions and examples of their use. One thing in particular to note is that you will probably want to use IG_DIB_EXPORT_FORMAT_IG_LEGACY in the DIB export options. This will give you a DIB in the same format that previous versions of ImageGear used for internal storage.

Depending on what your application code is doing and the images it works with, DIB export/import may not be practical due to the memory and time overhead involved. If this is the case for you, you will need to update your code to use one of the methods described in the following sections.


Method 2: Pixel Access Functions

As with previous versions of ImageGear, there are pixel access functions that can be used to access pixel data associated with a HIGEAR image. These functions have names like IG_DIB_area_get/set, IG_DIB_raster_get/set, IG_DIB_pixel_get/set, and so on. The pixel access functions have two modes of operation: legacy (prior to 14.5) and new (14.5 and beyond). The default mode is legacy, in which these functions behave the same way they did before 14.5. So if you have existing code using pixel access functions, you shouldn't need to update it for 14.5. If you're considering using the pixel access functions for new code and you don't need to work directly with higher bit depths, uncommon color spaces, or alpha/extra channel data included with the main channel data, we recommend using the legacy mode. This mode shields you from the added complexity of these new formats.

If you want to use the new formats, or achieve maximum efficiency, you can use the new mode of pixel access to get more direct access to the new storage system. If you use the new mode, you must be aware of the following differences as compared to legacy mode:

  • For RGB images, color channel order is RGB (in legacy mode, it's BGR)
  • You can access higher bit depths (i.e. 36-bit, 48-bit RGB)
  • You can access other color spaces (i.e. LAB, YUV)
  • Alpha and extra channel data is included on a per-pixel basis. For example, if you have a 24-bit RGB image with an 8-bit alpha channel, the pixel data will look like RGBA, RGBA, RGBA and so on, where R, G, B, and A are each one byte.
  • Pixel packing and raster padding are as follows:
    Packing Mode
    Legacy
    New
    IG_PIXEL_PACKED
    1, 4bpp packed, DWORD padding
    1bpp packed, DWORD padding
    IG_PIXEL_UNPACKED
    No packing, BYTE padding
    No packing, DWORD padding

Note that 1-bit channels are the only channels that are packed in the new mode - 8 pixels stored in each byte. All other channel depths are stored as 1, 2, or 4 byte values. A channel value with depth of 2-8 bits will be stored in one byte, 9-16 bits in two bytes, and 17-32 bits in four bytes. Channel values with depths of 33-64 bits are possible on 64-bit platforms and are stored in eight bytes.

To use the new mode, you need to set the DIB.PIX_ACCESS_USE_LEGACY_MODE global control parameter to IG_PIX_ACCESS_MODE_NEW. For example:

AT_MODE pixAccessMode = IG_PIX_ACCESS_MODE_NEW;
IG_gctrl_item_set("DIB.PIX_ACCESS_USE_LEGACY_MODE",
AM_TID_AT_MODE,
    &pixAccessMode, sizeof(pixAccessMode), NULL);


Method 3: Accessing Pixel Data Directly

The function IG_image_DIB_raster_pntr_get provides a direct pointer to the pixel data for a raster as it is stored internally by ImageGear. The first raster, raster 0, is the top-most raster in the image. The easiest way to access pixel data directly is to loop over the rasters in the image and call IG_image_DIB_raster_pntr_get for each raster. However, since rasters are stored sequentially in memory, it is possible to retrieve a pointer to the first raster and use it to address the entire image. If you do this, you must be aware of the following details:

  • Rasters are stored in memory from top to bottom. (This is the opposite of the previous DIB-based storage system which stored images vertically flipped.)
  • Rasters are stored with DWORD padding. That is, if the size of a raster is not a multiple of 4, the end of a raster will be padded with unused bytes until the size is a multiple of 4.

When accessing pixel data directly, the format of the data is the same as when the pixel access functions are used in "new" mode as described in the previous section. However, there is one exception: 1bpp images are always stored internally in a compressed format. If you need to access 1bpp images, you should use DIB import/export or pixel access functions instead of IG_image_DIB_raster_pntr_get. Alternatively, you can work with the compressed data directly as described in the Working with Run Ends Format section.


Working with Alpha/Extra Channels

When you access pixel data by using the pixel access functions in new mode, or directly via IG_image_DIB_raster_pntr_get, remember that alpha/extra channels may be present. These channels are stored along with the color channels on a per-pixel basis. You can easily detect their presence by calling the following functions:

  • IG_image_colorspace_get / IG_DIB_colorspace_get
  • IG_util_colorspace_contains_alpha
  • IG_util_colorspace_contains_extra

Here are some options for dealing with these channels:


Option 1: Make your pixel access code aware of alpha/extra channels.

If you want to work with alpha/extra channels in your pixel access code, this is the obvious choice. If you don't want to work with them but you want to be able to process images that may contain them, then you can calculate a per-pixel "stride" - the number of bytes between pixels - by using the channel depths, so that you can skip over alpha and extra channels, or you can use the next option.


Option 2: Remove alpha/extra channels before doing pixel access.

If you don't care about alpha/extra channels, you can remove them from the image before doing pixel access. Of course, keep in mind that if you then save the image, the saved image will not contain these channels. It's easy to remove alpha/extra channels by using the color space converter. For example:

// Removes any alpha/extra channels from the image
void removeAlphaExtra(HIGEAR hImage)
{
    // Make sure there's at least one alpha or extra channel
    // (this isn't strictly necessary, it's here for demo
purposes)
    enumIGColorSpaceIDs cs;
    IG_image_colorspace_get(hImage, &cs);
    if (!IG_util_colorspace_contains_alpha(cs) &&
        !IG_util_colorspace_contains_extra(cs))
        return;
    // Alter the color space ID to only include color channels
    cs = (enumIGColorSpaceIDs) (cs &
IG_COLOR_SPACE_ID_ColorMask);
// Use the color space converter to convert to this new ID
    IG_image_colorspace_convert(hImage, cs, NULL);
}


Working with Variable Channel Depths

When you access pixel data by using the pixel access functions in new mode, or directly via IG_image_DIB_raster_pntr_get, you may need to pay special attention to channel depths. Let's consider the example of an image in ImageGear 14.5 whose color space is reported as IG_COLOR_SPACE_ID_RGB. It has no alpha or extra channels. In the past, it was safe to assume that an RGB image had 24 bits per pixel, using 8 bits for each channel: red, green, and blue. In ImageGear 14.5, this may not be true. It's possible to have an RGB image with 36 bits per pixel, using 12 bits for each channel. Or the image could be "24-bit RGB" but the red and blue channels are 6 bits and the green channel is 12 bits. (This is an odd channel configuration, but it's easy to create such an image using the function IG_image_channel_depths_change.)

Fortunately, ImageGear gives you functions to query the relevant properties of an image and easily perform color space and channel depth conversions. This lets you prepare an image ahead of time to simplify your pixel access code. You can choose the level of flexibility and complexity you want to target by looking at the following properties of an image and taking action based on them:

Image property
IG function(s) to get it
Notes
Color space
IG_image_colorspace_get / IG_DIB_colorspace_get
Specifies configuration and number of color channels
Number of channels
IG_DIB_channel_count_get
Includes color, alpha, and extra
Channel depths
IG_DIB_channel_depth_get,
IG_DIB_channel_depths_get
Specifies number of bits used for each channel

Consider an example in which you want to access any kind of input image as a typical 24-bit RGB image (having 8-bit R, G, and B channels) with no alpha or extra channels. With one call to IG_image_colorspace_convert, you can make sure the image is RGB and get rid of any alpha or extra channels at the same time. Then you can use IG_image_channel_depths_change to make sure that the channel depths are each 8 bits. Here's an example function to prepare an image in this way:

// Convert any (raster) image to 24-bit RGB with no alpha/extra
channels
void convertToRGB24(HIGEAR hImage)
{
    IG_image_colorspace_convert(hImage, IG_COLOR_SPACE_ID_RGB,
NULL);
    AT_INT d[3] = { 8, 8, 8 };  // 8 bits for each channel - R,
G, and B
    IG_image_channel_depths_change(hImage, d,
IG_DEPTH_CHANGE_SCALE);
}


Pixel Access Examples

The following functions demonstrate pixel access by creating a 24-bit RGB image and filling it with a specified color. The overall strategy is:

  • Create a new 24-bit RGB image with IG_image_create
  • Fill a single temporary raster with the desired fill color for the image
  • Loop through the image rasters, copying the temporary raster to each image raster


Image Creation Helper Function (used by the functions that follow)

// Create a 24-bit RGB image (initially filled with black
pixels)
HIGEAR createRGB24(AT_DIMENSION w, AT_DIMENSION h)
{
    HIGEAR hImage;
    HIGDIBINFO hDIB;
    AT_INT d[3] = { 8, 8, 8 };   // 8 bits per channel for R, G,
B
    IG_DIB_info_create(&hDIB, w, h, IG_COLOR_SPACE_ID_RGB, 3,
d);
    IG_image_create(hDIB, &hImage);
    return hImage;
}


Using Pixel Access Functions in Legacy Mode

// Create a filled RGB24 image using pixel access functions
(legacy mode)
HIGEAR createFilledRGB24(AT_DIMENSION w, AT_DIMENSION h,
AT_RGBQUAD c)
{
    // Create image (initially filled with black pixels)
    HIGEAR hImage = createRGB24(w, h);
    // Set pixel access mode to legacy (even though it's the
default)
    AT_MODE pixAccessMode = IG_PIX_ACCESS_MODE_LEGACY;
    IG_gctrl_item_set("DIB.PIX_ACCESS_USE_LEGACY_MODE",
AM_TID_AT_MODE,
&pixAccessMode, sizeof(pixAccessMode), NULL);
    // Create a raster with the desired color (BGR channel
order!)
    LPAT_PIXEL lpRaster = (LPAT_PIXEL) malloc(w * 3);
    for (AT_PIXPOS x = 0; x < w; x++)
    {
        lpRaster[x * 3 + 0] = c.rgbBlue;
        lpRaster[x * 3 + 1] = c.rgbGreen;
        lpRaster[x * 3 + 2] = c.rgbRed;
    }
    // Loop over the image and set each raster
    for (AT_PIXPOS y = 0; y < h; y++)
        IG_DIB_raster_set(hImage, y, lpRaster,
IG_PIXEL_UNPACKED);

    free(lpRaster);
    return hImage;
}


Using Pixel Access Functions in New Mode

// Create a filled RGB24 image using pixel access functions (new
mode)
HIGEAR createFilledRGB24(AT_DIMENSION w, AT_DIMENSION h,
AT_RGBQUAD c)
{
    // Create image (initially filled with black pixels)
    HIGEAR hImage = createRGB24(w, h);
    // Set pixel access mode to new
    AT_MODE pixAccessMode = IG_PIX_ACCESS_MODE_NEW;
    IG_gctrl_item_set("DIB.PIX_ACCESS_USE_LEGACY_MODE",
AM_TID_AT_MODE,
        &pixAccessMode, sizeof(pixAccessMode), NULL);
    // Create a raster with the desired color (RGB channel
order!)
    LPAT_PIXEL lpRaster = (LPAT_PIXEL) malloc(w * 3);
    for (AT_PIXPOS x = 0; x < w; x++)
    {
        lpRaster[x * 3 + 0] = c.rgbRed;
        lpRaster[x * 3 + 1] = c.rgbGreen;
        lpRaster[x * 3 + 2] = c.rgbBlue;
    }
    // Loop over the image and set each raster
    for (AT_PIXPOS y = 0; y < h; y++)
        IG_DIB_raster_set(hImage, y, lpRaster,
IG_PIXEL_UNPACKED);
    free(lpRaster);
    return hImage;
}


Using Direct Access via IG_image_DIB_raster_pntr_get (called for each raster)

// Create a filled RGB24 image using direct pixel access
HIGEAR createFilledRGB24(AT_DIMENSION w, AT_DIMENSION h,
AT_RGBQUAD c)
{
    // Create image (initially filled with black pixels)
    HIGEAR hImage = createRGB24(w, h);
    // Note: Pixel access mode does not matter here, since the
pixel
    // data is being accessed directly by getting a pointer to it
    // Create a raster with the desired color (RGB channel
order!)
    LPAT_PIXEL lpSrcRaster = (LPAT_PIXEL) malloc(w * 3);
    for (AT_PIXPOS x = 0; x < w; x++)
    {
        lpSrcRaster[x * 3 + 0] = c.rgbRed;
        lpSrcRaster[x * 3 + 1] = c.rgbGreen;
        lpSrcRaster[x * 3 + 2] = c.rgbBlue;
    }
    // Loop over the image and set each raster
    for (AT_PIXPOS y = 0; y < h; y++)
    {
        // Get a pointer to the image raster
        LPAT_VOID lpDstRaster;
        IG_image_DIB_raster_pntr_get(hImage, y, &lpDstRaster);
        // Copy the source raster to image raster
        memcpy(lpDstRaster, lpSrcRaster, w * 3);
    }
    free(lpSrcRaster);
    return hImage;
}


Using Direct Access via IG_image_DIB_raster_pntr_get (called only once)

// Create a filled RGB24 image using direct pixel access
// The algorithm has been changed slightly to simplify this
example
HIGEAR createFilledRGB24(AT_DIMENSION w, AT_DIMENSION h,
AT_RGBQUAD c)
{
    // Create image (initially filled with black pixels)
    HIGEAR hImage = createRGB24(w, h);
    // Note: Pixel access mode does not matter here, since the
pixel
    // data is being accessed directly by getting a pointer to it
    // Get a pointer to the pixel data
    LPAT_VOID lpPixelVoid;
    IG_image_DIB_raster_pntr_get(hImage, 0, &lpPixelVoid);
    LPAT_PIXEL lpPixel = (LPAT_PIXEL) lpPixelVoid;
    // Loop through rasters in the image
    for (AT_PIXPOS y = 0; y < h; y++)
    {
        // Set each pixel to the fill color
        for (AT_PIXPOS x = 0; x < w; x++)
        {
            *lpPixel++ = c.rgbRed;
            *lpPixel++ = c.rgbGreen;
            *lpPixel++ = c.rgbBlue;
        }
        // Rasters are DWORD-padded (raster size is multiple of
4)
        // so advance to the beginning of the next raster
        lpPixel += w % 4;
    }
    return hImage;
}


Glossary

This glossary contains a mixture of terminology used by AccuSoft in both its software products and its documentation. Since these terms come from many different disciplines and because many of the terms have different meanings in each discipline, each glossary entry is followed by the name of the field from which the definition is taken.

For a detailed description, refer to the references listed in the Bibliography.

To find terms which start with a numeral (0-9), look under its spelling, for example, the term "8-bit gray level" can be found as - "eight bit gray level."

absolute coordinates (imaging)

Absolute coordinates refer to a common origin, for example, the upper left corner of a display screen. This is the opposite of relative coordinates.

ACCUAPI (AccuSoft)

AccuSoft Application Program Interface. See API (software) .

additive primary colors (imaging)

Red, Green, Blue - the 3 colors used to create all other colors when direct, or transmitted light is used (as in a video monitor). They are called additive primaries, because when these three colors are superimposed they produce white.

anti-aliasing (imaging)

A method of filling in data that is missing due to under-sampling. In imaging, this usually involves the process of removing jagged edges by interpolating values in-between pixels of contrast. These methods are most often used to remove or reduce the stair-stepping artifact found in digital high contrast images.

AOI (Image Processing)

Area Of Interest. An area of interest is a rectangle within an image defined as two points within the image. An AOI can be written as (x1,y1)-(x2,y2). All AOIs are parallel with the image's axes. See ROI (AccuSoft image processing) .

API (software)

Application Programmer's Interface. The set of routines that make up a library or toolkit. Some times called a binding.

aspect ratio (imaging)

The proportion of an image's size given in terms of the horizontal length verses the vertical height. An aspect ratio of 4:3 indicates that the image is 4/3 times as wide as it is high.

Bezier curve (graphics)

A curve created from endpoints and two or more control points that serve as positions for the shape of the curve. Originated by P. Bezier (~1962) for the use in car body descriptions.

bit block transfer

A raster operation that moves a block of bits representing a portion of an image or scene from one location in the frame buffer to another. Usually written as "bit blt".

bin (image processing)

See histogram (imaging) .

Bit Block Transfer (Windows)

An optimized movement of a large block of computer memory from one location to another. Used for moving images or sub-images to and from areas of computer memory.

bit blt

bit_block_transfer.

bitmap (imaging)

An image is a bitmap if it contains a value for each of its pixels. This is the opposite of vector images where a small set of values generate an object.

bit plane (imaging)

A hypothetical 2-D plane containing a single bit of memory for each pixel in a image. If each 8-bit pixel is thought of as a stack of 8 coins, and an image as many rows and columns of these stacked coins then the 3rd bit plane would be the plane consisting of the 3rd coin from each stack.

bounding rectangle (geometry)

The smallest rectangle that fits around a given object. In imaging, the rectangle is usually rotationally restricted to be parallel to both image axes.

.BMP (file format extension)

Format originator: Microsoft Corporation

16011 NE 36th Way, Box 97917

Redmond, WA 98073

Call-back function (software)

A function that is passed to another function as a parameter. The function receiving the call-back function can call this function. This is used to change the behavior of a given routine without knowing beforehand what it is expected to do.

Cartesian coordinates (imaging)

A 2-dimensional equally spaced grid iron that uniquely assigns every point in the plane, (one and only one), co-ordinate pair; (x, y). In imaging, each point is usually referred to as a pixel and the x and y values take on integer values. Most images use the top-left as the (0,0), or origin. See coordinates .

Chroma-key (image processing)

An image blending function that replaces pixels of a specified hue range with pixels from a second image. This is often referred to the weatherman effect because most weather forecasters use a solid blue or green background to make it look as if they are standing in front of a huge weather map. It is important to remember that it is the hue that is used in the blending function and not the intensity or saturation.

C.I.E (color imaging)

Commission Internationale de l'Eclairage. (International Commission of Illumination). A standards organization which provides specifications for the description of device independent color.

clipboard (Windows)

The clipboard is a windows data structure used to exchanged data between applications. It is a common area where applications place data and others can access it. These operations are usually referred to as Cut (place data in) and Paste (take data out).

closing (image processing)

See MPEG (image compression) .

CMY & CMYK

Cyan, Magenta, Yellow, (K) black. Computer monitors are additive, but color printers are subtractive. Instead of combining light from monitor phosphors, printers coat paper with colored pigment that removes specific colors from the illumination light.

CMY is the subtractive color model that corresponds to the additive RGB model. Cyan, magenta, and yellow are the color complements of red, green, and blue. Due to the difficulties of manufacturing pigments that produce black when mixed together, a separate black ink is often used and is referred to as K (`B' is already used for blue).

color map (imaging)

See Look-Up-Table (computer hardware)

color model (imaging)

See color space (imaging) .

color space (imaging)

A mathematical coordinate system (space) for assigning numerical values to colors. There are many ways to define such spaces, each with its own benefits and problems.

See Also:
  • CMY & CMYK
  • HIS (color imaging)
  • HLS (color imaging)
  • HSV (color imaging)
  • RGB (imaging)
  • YIQ (color imaging)

compression (imaging)

An image processing method for saving valuable disk and memory space by reducing the amount of space required to save a digital image. The graphics data is rewritten allowing it to be represented by a smaller set of data. Do not confuse this with encoding. See lossless (image compression) andlossy (image compression) .

compression ratio (imaging)

The ratio of a file's uncompressed size over its compressed size.

concave (geometry)

A 2-dimensional blob, for example, a region of interest (ROI), where at least one tangent is drawn that touches the blob at two different locations, and there is a point on the tangent between the two contacts that does not touch the blob.

In simpler words, if a rubber band could be snugly wrapped around a concave blob there would be places where the rubber band lifts off and does not touch the blob. Concave is the opposite of convex.

convex (geometry)

A 2-dimensional blob, for example, a region of interest (ROI), where every tangent that can be drawn touches the blob at a continuous stretch of the blob's surface with no gaps.

In simpler words, if a rubber band could be snugly wrapped around a convex blob there would be no places where the rubber band lifts off and is not touching the blob. Convex is the opposite of concave.

convolution (image processing)

An image processing operation that is used to spatially filter an image. A convolution is defined by a kernel that is a small matrix of fixed numbers. The size of the kernel, the numbers within it, and a single normalizer value define the operation that is applied to the image. The kernel is applied to the image by placing the kernel over the image to be convolved and sliding it around to center it over every pixel in the original image.

At each placement the numbers (pixel values) from the original image are multiplied by the kernel number that is currently aligned above it. The sum of all these products is tabulated and divided by the kernel's normalizer. This result is placed into the new image at the position of the kernel's center. The kernel is translated to the next pixel position and the process repeats until all image pixels have been processed.

As an example, a 3x3 kernel holding all `1's with a normalizer of 1/9 performs a neighborhood averaging operation. Each pixel in the new image is the average of its 9 neighbors from the original.

coordinates

A pair of numbers that represent a specific location in a two-dimensional plane, for example, an image or on a map.

See Also:
  • absolute coordinates (imaging)
  • device coordinates (imaging)
  • Cartesian coordinates (imaging)
  • polar coordinates (imaging)
  • relative coordinates
  • screen coordinates (imaging)
  • world coordinates

crop (Imaging)

An image processing method for removing the region near the edge of the image, but keeping the central area.

.DCX (file format extension)

Format originator: Intel

DDB (Windows)

Device-Dependent Bitmap. A Window image specification that depends on the capabilities of a specific graphics display controller. Since a DDB is matched to the current graphics controller, it is fast and easy to display since large blocks of memory need only be copied to the controller.

See Also:

DIB (Windows) .

decompression (imaging)

When an image or other digital data set is compressed and stored, it is not usable until it is decompressed into it original form.

device coordinates (imaging)

The co-ordinates of the coordinate system that describe the physical units that defines the computer screen.

device dependent (software)

Software written to work on a specific set of hardware platforms. Since these routines make use of physical device attributes, they may behave differently on other devices, although they will most often not work on other devices.

See Also:
  • device independent (software)
  • DIB (Windows) .

device driver (software)

A set of low-level software routines that work with and control a specific hardware device. The names and functions are often standardized across many similar devices. This allows higher level software to use the hardware as a generic device. This frees the higher-level software from dealing with the particulars of specific devices and allows devices to be interchanged.

device independent (software)

Software or data structures that are designed to work with or on a wide set of hardware platforms.

See Also:
  • device independent (software)
  • DIB (Windows) .

DIB (Windows)

Device-Independent Bitmap is a Windows-defined image format specification. It is called device-independent because of its straightforward, common-denominator, format. It has all the information that a basic digital image needs and is laid out in a simple specification. Its simplicity makes it an ideal format for holding images that need to be shared by several programs.

See Also:
  • DDB (Windows)
  • the book Programming Windows by Charles Petzold.

dilation (image processing)

See MPEG (image compression) .

dithering (imaging)

The method of using neighborhoods of display pixels to represent one image intensity or color. This method allows low-intensity resolution display devices to simulate higher resolution images. For example, a binary laser printer can use block patterns to display grayscale images.

See Also:

halftone (imaging) .

DLL (Microsoft Windows)

Dynamic Linked Library. A compiled and linked collection of computer functions that are not directly bound to an executable. These libraries are linked at run-time by Windows. Since Windows is in charge of managing (loading, linking, and removing) the DLLs, they are available to all executables currently running. Each executable links to a shared DLL saving memory by avoiding redundant functions from co-existing. DLLs allow a new level of modularity by providing a means to modify and update executables without re-linking. Just copy a new version of the DLL to the correct disk directory.

DPI (printing)

Dots Per Inch. The number of printer dots that can be printed in one inch. The printer's resolution is defined by the number of dots per inch: lower resolution = less dots per inch, higher resolution = more dots per inch.

edge (image processing)

In an image, an edge is a region of contrast or color change. Edges are useful in machine vision since optical edges often mark the boundary of physical objects.

edge detection (image processing)

A method that isolates and locates an optical edge in a digital image.

edge map (image processing)

An edge map is the output of an image-processing filter that transforms an image into an image where intensity represents a change in the contrast (optical edge) of the original image.

(eight) 8-bit image (digital imaging)

An image where each pixel has 8-bits of information. An 8-bit pixel contains one of 256 possible values. There are two common types of 8-bit images: grayscale and indexed color.

In a grayscale image, each pixel takes one of 256 shades of gray and the shades are linearly distributed from 0 (black) to 256 (white). An 8-bit grayscale image does not require a palette but may have one.

An indexed color image is always a palette image. Each pixel is used as an index to the palette. These images can have up to 256 different colors. This includes hues as well as shades. Indexed 8-bit images are good for low color resolution images that do not need processing. They are 3 times smaller than full-color RGB images, but because the pixel values are not linear, many image-processing algorithms cannot work with them. They must be promoted to 24-bit for image processing.

8-bit gray level (AccuSoft term)

This indicates 8-bit grayscale. 8-bit gray level is used to distinguish between 8-bit indexed color (8i) and 8 bit grayscale. An 8-bit gray level DIB image is one where each pixel in the bitmap is unchanged by its palette when displayed. Each palette entry is the same as its index.

8i (AccuSoft term)

This indicates 8-bit indexed color. 8i is used throughout this manual to distinguish between 8-bit grayscale (8-bit gray level) and 8-bit indexed color. An 8-bit indexed color DIB is one where each 8-bit pixel value in the bitmap is used as an index to the palette.

The palette dictates which RGB color the pixel displays. These images are compact ways of storing color images. However they are difficult to process because the bytes that make up the pixel can no longer be ordered with any certainty.

Encoding

The format for storing uncompressed data (binary, ASCII, etc.), how it is packed (e.g. 4-bit pixels may be packed at a rate of two pixels per byte), and the unique set of symbols used to represent the range of data items.

.EPS (file format extension)

Format originator: Adobe Systems, Inc.

1585 Charleston Road

Mountain View, CA 94039

equalize (image processing)

An image-processing algorithm that redistributes the frequency of image pixel values allowing equal representation for any given continuous range of values. In an ideal world, an equalized image has the same number of pixels in the range from 10-20 as it does from 200-210. However, since digital images have quantized intensity values, the range totals are rarely identical but usually close.

erosion (image processing)

See MPEG (image compression)

file format (software)

A specification for holding computer data in a disk file. The format dictates what information is present in the file and how it is organized.

filter (image processing)

An image-processing filter is a transform that removes a specified quantity from an image. For instance a spatial filter removes high, medium or low spatial frequencies from an image.

(four) 4 bit image (digital imaging)

An image file format that allows 4-bits per pixel. This image can contain up to 16 (24) different colors or levels of gray.

frame (imaging)

A single picture, usually taken from a collection of images for example, a movie or video stream.

frame buffer (imaging hardware)

A computer peripheral that stores and sometimes manipulates digital images.

frame processes (image processing)

Image-processing algorithms that operate on a single image.

fx (imaging)

See special effects (image processing) .

gain & level (imaging)

Gain and level are image-processing terms that correspond to the brightness and contrast control on a television. The gain is the "contrast", and the level is the "brightness." By changing the level, the entire range of pixel values are linearly shifted brighter or darker. Gain on the other hand linearly stretches or shrinks the intensity range, altering the contrast.

gamma correction (imaging)

A non-linear function that is used to correct the inherent non-linearities of cameras and monitors. The intensity of the luminescent phosphor on the raster display is non-linear. Gamma correction is an adjustment to the pixel intensity values that make up for this inherent non-linearity.

geometric transform (image processing)

A class of image processing transforms that alter the location of pixels. This class includes rotates and warps.

.GIF (file format extension)

Name: Graphics Interchange File Format

Format originator: CompuServe Inc.

500 Arlington Center Blvd.

Columbus, OH 43220

This format uses the LZW compression created by Unisys. It is the same as the LZW compression used in the TIFF file format, except that the bytes are reversed and the string table is upside-down.

All GIF files have a palette. Some GIF files can be interlaced - the raster lines can appear as every 4 lines, then every 8 lines, then every other line. This is due to GIF files usually being received from a modem.

GUI

Graphical User Interface. A computer-user interface that uses graphical objects and a mouse for user interaction, for example Microsoft Windows.

graphics library (software)

A collection of software routines that work on digital images. These collections usually contain routines for drawing various graphical objects, for example, lines, circles, and rectangles.

gray level (imaging)

A shade of gray assigned to a pixel. The shades are usually positive integer values taken from the grayscale. In an 8-bit image a gray level can have a value from 0 to 255.

grayscale (imaging)

A range of gray levels. Zero is usually black and higher numbers indicate brighter pixels.

group III Fax (Imaging compression)

A CCITT standard for transmission of facsimile data. It compresses black and white images using a combination of differential, run length and Huffman coding.

halftone (imaging)

The reproduction of a continuous-tone image on a device that does not directly support continuous output. This is done by displaying or printing a pattern of small dots that simulate the desired output color or intensity. These methods are used extensively in magazines and newspapers.

handle (software)

A handle references a data object. A handle is a type of pointer but it usually contains, internally, more information about the referenced object.

histogram (imaging)

A tabulation of pixel value populations displayed as a bar chart where the x-axis represents all the possible pixel values and the y-axis is the total image count of each given pixel value. A histogram counts how many pixels in the image have a given intensity value or range of values.

Each histogram intensity value or range of values is called a bin. Each bin contains a positive number that represents the number of pixels in the image that fall within the bin's range. A typical 8-bit grayscale histogram contains 256 bins. Each bin has a range of a single intensity value. Bin 0 contains the number of pixels in the image that have a grayscale value of 0 or black; bin 255 contains the number of white (255) pixels. When the collection of bins are sorted (0-255) and charted, the graph displays the intensity distributions of all the images pixels.

HLS (color imaging)

Hue Saturation, and Lightness. A method that describes any color as a triplet of real values. The hue represents the color or wavelength of the color. It is sometimes called tone and is commonly known as color. The hue is taken from the standard color wheel and is calibrated in degrees.

Saturation is the depth of the color. It states how gray the color is. It is a real valued parameter from 0.0 to 1.0 with 0.0 indicating full gray and 1.0 representing pure hue.

Lightness determines how black or white a color is. It ranges from 0.0 to 1.0 but with 0.0 representing black and 1.0 white. A lightness of 0.5 is a pure hue.

HSV (color imaging)

Hue, Saturation, and Value.

Huffman coding (image compression)

A method of encoding symbols that varies the length of the code in proportion to its information content. Groups of pixels that appear frequently in a image are coded with fewer bits than those of lower occurrence.

HIS (color imaging)

Intensity, Hue, and Saturation.

image format (image storage)

There are many digital image formats. Some of these are: TIFF, DIB, GIF, and JPEG. The image format specification dictates which image information is present and how it is organized in memory. Many formats support various sub-formats or `flavors'.

image processing

The general term "image processing" refers to a computer discipline wherein digital images are the main data object. This type of processing can be broken down into several sub-categories: compression, image enhancement, image filtering, image distortion, image display and coloring, and image editing.

See Also:

machine vision .

indexed color image (imaging)

An image where each pixel value is used as an index to a palette for interpretation before the pixel is displayed. These images contain a palette that is initialized specifically for a given image. The pixel values are usually 8-bit and the palette 24-bit (8-red, 8-green, and 8-blue).

See Also:

(eight) 8-bit image (digital imaging) .

invert intensity (image processing)

An image processing operation where each pixel is subtracted from the maximum pixel value allowed. This produces a photographic negative of the original. For an 8-bit image the inverse function is:

invert(pix) = 255-pix;

For an 8-bit RGB image the function is:

invert(Rpix) = 255-Rpix;

invert(Gpix) = 255-Gpix;

invert(Bpix) = 255-Bpix;

"jaggies" (imaging)

A term used to describe the visual appearance of lines and shapes in raster pictures that results from a grid of insufficient spatial resolution.

JPEG JFIF (image compression)

Joint Photographic Experts Group. A collaborative specification of the CCITT and the ISO for image compression. The standard JPEG compression algorithm, which is used by ImageGear, is a lossy compression scheme - it loses data.

.JPG (file format extension)

Format originator: Joint Photographics Experts Group

kernel (image processing)

A small matrix of pixels, usually no bigger that 9x9, that is used as an operator during image convolution. The kernel is set prior to the convolution in a fashion that emphasizes a particular feature of the image. Kernels are often used as spatial filters, each one tuned to a specific spatial frequency that the convolution is intended to highlight.

See Also:

convolution (image processing).

Lempel Ziff Welch (data compression)

A dictionary-based image compression method with lossless performance that results in fair compression ratios. Most files are compressed at 2:1.

level (imaging)

See gain & level (imaging).

library (software)

A collection of software functions that can be called upon by a higher level program. Most libraries are collections of similar routines, for example, those used for graphical or image processing.

See Also:

DLL (Microsoft Windows) .

Look-Up-Table (computer hardware)

A look-up-table or LUT is a continuous block of computer memory that computes the values of a function for one variable. The LUT is set up for the function's variable to be used as an address or offset into the memory block. The value that resides at this memory location becomes the function's output. Because the LUT values need only be initialized once, LUTs are very useful for image processing due to their inherent high speed.

LUT[pixel_value] = f(pixel_value)

LUTs come in various widths, usually in units of bits. An nxm bit LUT has 2n addresses or 256 stored values. Each value is 2m bits wide.

If the second dimension is left off it can be assumed to be equal to the first. In grayscale image processing, LUTs are commonly 8x8, and the bit widths are usually assumed.

A linear LUT, sometimes called a NOP LUT or pass through, is a LUT that is initialized to output the same values as the input. NOP_LUT[pixel_value] = pixel_value.

See palette (digital imaging) .

lossless (image compression)

A method of image compression where there is no loss in quality when the image is uncompressed. The uncompressed image is mathematically identical to its original. Lossless compression is usually lower in compression ratio than lossy compression.

lossy (image compression)

A method of image compression where some image quality is sacrificed in exchange for higher compression ratios. The amount of quality degradation depends on the compression algorithm used and by a user-selected quality variable.

LUT (computer)

Look-Up-Table. See Look-Up-Table (computer hardware) .

LUT transform (image processing)

A LUT transform is an image processing method that takes an image and passes each pixel, one at a time, through a pre-set LUT. Each new pixel is a function of one and only one pixel from the original image and is arranged in the same location.

Any image-processing algorithm that transforms a single pixel into another single pixel, both from the same location, can be performed quickly using a LUT.

Square_root_LUT[pixel_value] = sqrt(pixel_value)

See Also:

Look-Up-Table (computer hardware) .

LZW (data compression)

Lempel Ziff Welch. See Lempel Ziff Welch (data compression) .

machine vision

A sub-discipline of artificial intelligence that uses video cameras or scanners to obtain information about a given environment. Machine vision processes extract information from digital images about objects in the image. This is the opposite of computer graphics that takes various data describing objects in and produces an output image. Machine vision takes an image in and outputs some level of description about the objects in it, (i.e. color, size, brightness).

See Also:

image processing .

matrix operation (image processing)

See neighborhood process (image processing) .

median filter (image processing)

An image spatial filtering operation based on an input pixel and its 8 neighbors. The resulting value is the median (5th from the sorted values). A median filter is often used to reduce spike or speckling noise from a grayscale image. It has the advantage over convolution smoothing - it better preserves edges.

morphing (image processing)

An imaging process where one image is gradually transformed into a second image, where both images previously existed. The result is a sequence of in-between images when played sequentially, as in a film loop show, give the appearance of the starting image being transformed to the second image.

Morphing is made up of a collection of image processing algorithms. The two major groups are: warps and blends. Do not confuse this with morphology.

MPEG (image compression)

Motion Pictures Experts Group. An ISO specification for the compression of digital-broadcast quality full-motion video and sound.

neighborhood process (image processing)

A class of image-processing routines that works on neighborhoods of pixels. Each pixel in the new image is computed as a function of the neighborhood of the pixel from the original pixel. The neighborhood ID is defined by a kernel that is set once for each image to be processed.

See Also:

point process (image processing) .

(one) 1-bit image (digital imaging)

An image comprised of pixels that contain only a single bit of information. Each pixel is either on or off. Normally, "on" is white and "off" is black.

opening (image processing)

See MPEG (image compression) .

overlay (imaging)

An image or sub-image that can be placed over a given image. The pixels from the original image are not altered but the overlay can be viewed as if they had been. Usually used to place temporary text and annotation marks, for example, arrows on a image.

packed bits (imaging)

A binary image is usually stored in computer memory (8 pixels per byte). In this case each byte is referred to as being filled with packed bits. This saves space but makes reading and writing any individual pixel harder since most computers cannot directly access memory in chunks smaller than a byte.

palette (digital imaging)

A digital image palette is a collection of 3 look-up-tables, or LUTs, that are used to define a given pixel's display color. One LUT is for red, one for green and one for blue. The number of entries in the LUTs depend on the width (in bits) of the image's pixels.

A palette image requires its palette in order to be displayed in a fashion that makes sense to the viewer. This is often the case for color 8-bit images. Without a palette describing what color each pixel needs for display, this type of image would most likely be displayed as randomly selected noise.

A grayscale palette is one where each of the 3 LUTs are linear. The output is whatever is input to them. Since each color component (R, G, B) is an equal value, any pixels input to them are displayed in a varying shade of gray.

See Also:

Look-Up-Table (computer hardware) .

pattern recognition (imaging)

A sub-discipline of machine vision where images are searched for specific patterns. Optical character recognition or "OCR" is one type of pattern recognition, where images are searched for the letters of the alphabet.

.PCX (file format extension)

Format originator: ZSoft Corp.

450 Franklin Road Suite 100

Marietta, GA 30067

pixel (imaging)

An abbreviated version of the term PIcture (X) ELement. This is the most fundamental element of a digital image. A digital image is made up of rows and columns of points of light. Each indivisible point of light is a pixel. Each pixel in an image is addressed by its column (x) and its row (y) usually written as the coordinate pair (x, y). An 8-bit pixel can take on one of 256 values. A 24-bit pixel has 3, 8-bit components for each of the primary colors, red, green, and blue.

point process (image processing)

A class of image processing transforms where every pixel is taken, one at a time from an image, and mathematically transformed into a new value with no input from any other pixel in the image. A point process is a degenerative neighborhood process where the kernel is a matrix of pixels that is 1x1 or in other words a single pixel.

polar coordinates (imaging)

An alternative to the usual Cartesian method of addressing image pixels. Polar coordinates use the coordinate pair, angle and radius from an origin instead of column and row.

posterize (imaging)

A special effect that decreases the number of colors or grayscales in an image. The default image pixel contains 256 levels of gray or 256 levels of red, green, and blue. Using this effect reduces these numbers.

pseudocolor (image processing)

A method of assigning color to ranges of a grayscale image's pixel values. Most often used to highlight subtle contrast gradients or for visually quantifying pixel values. The applied color usually has no correspondence to the original scene. The colors are used only as a guide or highlight.

raster (imaging)

A term that describes a single row of a digital image. A raster image is made up of rows of pixels. This is opposed to vector images, where an image is made up of a list of polygon nodes. A raster is sometimes called a scan-line.

relative coordinates

Relative coordinates refer to position, as identified as the distance from a local origin.

render (imaging)

The process of displaying an image. The final and actual displayed image is said to be rendered.

resolution (imaging)

There are two types of resolution in digital images; spatial and intensity. Spatial resolution is the number of pixels per unit of length along the x and y axis. Intensity resolution is the number of quantized levels that a pixel can have.

RGB (imaging)

Red, Green, Blue. A triplet of numeric values that describe a color.

RGBQUAD

Red, Green, Blue, Quad. A set of four numbers used to describe a color. The forth number is always set to zero. This creates an efficient color LUT or palette. It is more efficient because most computers find multiplying by 4 easier then by 3, as is the case in an RGB triplet.

ROI (AccuSoft image processing)

Region Of Interest. A region of interest or ROI is a specification and date structure that allows for the definition of arbitrarily shaped regions within a given image, often called sub-images. A ROI can be thought of as a place holder which remembers a location within an image. ROIs are of several types, each defined in a manor that makes sense for its type.

ROIs are either a rectangle (also called an AOI), square, circle, or a segment list. A rectangle is defined by any two points in the image. From these two points one and only one rectangle can be drawn. A square is defined by a single point and a single length. A circle is defined by its center and radius. A segment list is an arbitrary list of triplets (x, y, xlen); a single point and a length to the right.

Every point in an image is either inside or outside of a given ROI.

Most image processing functions in this package work only within a given ROI. The ROI can encompass the entire image.

See Also:

AOI (Image Processing) .

scan line (imaging)

See raster (imaging) .

screen coordinates (imaging)

Screen coordinates are those of the actual graphics display controller. The origin is almost always at the upper left-hand corner of the display.

See Also:

coordinates .

segment (imaging)

A contiguous section of a raster line. It is defined in physical coordinates by the triplet of its left most point and length (x, y, length).

shear (image processing)

A skew is image distortion that often occurs when a scanner is sampling an image and the image slides to either side before the scan is complete. This has the effect of transforming squares into rhombuses.

special effects (image processing)

Any image processing transform that is applied mostly for its artistic value. Special effects include, wipes, transitions, barn doors, etc.

stretch intensity (image processing)

An image processing method that takes a given image and assures that the intensity distribution fills the entire range of possible values. An 8-bit image that is stretched always has at least one pixel with a value of zero and one of 255. The term comes from the before and after histogram of the given image. A stretch operation linearly stretches a histogram so that is ranges from the minimum pixel value to the maximum pixel value.

.TGA (file format extension)

Format originator: Truevision, Inc.

7340 Shadeland Station

Indianapolis, IN 46255

TIFF (file format)

Tagged Image File Format.

.TIF (file format extension)

Format originator: Aldus Corp

411 First Ave South

Seattle, WA 98104, and

Microsoft Corp

16011 NE 36th Way

Redmond, WA 98073

thumbnail (imaging)

A small copy of an image. Thumbnails are used to display many images on the screen at once.

transform (image processing)

An algorithm that takes an image, alters it, and outputs a new image. Sometimes written as `xform'.

See Also:
  • geometric transform (image processing)
  • neighborhood process (image processing)
  • point process (image processing)

triplet (digital imaging)

Three numbers used together to represent a single quantity or location, for example, RGB or (x, y, z).

(twenty-four) 24 bit image (digital imaging)

A 24-bit image contains pixels made from RGB triplets.

video stream (video)

A sequence of still images that are transmitted and displayed in synchronous order that give the appearance of live motion.

warp (image processing)

A geometric image processing routine that distorts an image by spatially compressing and stretching regions.

.WMF (file format extension)

Format originator: Microsoft Corp

16011 NE 36th Way

Redmond, WA 98073

world coordinates

The real valued coordinates that make sense for the object, treating it as if it really exists. The world coordinates of a house on a map would be in miles or longitude and latitude. This is the opposite of screen, device or model coordinates.

.WPG (file format extension)

Format originator: WordPerfect Corp

(x, y)

A mathematical method for referring to a pixel from a digital image. Since most digital images are maintained as a Cartesian matrix of pixels, each pixel has a unique address that can be described as an x or horizontal displacement from the origin and a y or vertical displacement from the origin.

See Also:

coordinates .

xform

Shorthand for transform.

YIQ (color imaging)

(Y) luminance, (I), (Q). YIQ is the color model used for U.S. commercial television. It was designed to be backwards compatible with the old black and white television sets. "Y" or luminance is a weighted average of the red, green, and blue that gives more weight to red and green than to blue. The I and Q contain the color components. Together they are called chromoticity.

(Z)

A mathematical method that refers to a pixel's intensity from a digital image. An image can be written as: I(x,y)=z


Bibliography

Books

Brown, Wayne C., and Barry J. Shepherd. Graphics File Formats Reference and Guide. Greenwich, CT: Manning Publications, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. Windcrest Books, 1992.

Kay, David C. and John R. Levine. Graphics File Formats. 2d ed. Windcrest/McGraw-Hill, 1995.

Murray, James D., and William vanRyper. Encyclopedia of Graphics File Formats. Sebastapol, CA: O'Reilly & Associates, Inc., 1994.

Murray, James D. and William vanRyper. Encyclopedia of Graphics File Formats, 2d ed. Sebastopol, CA: O'Reilly & Associates, Inc., 1996.

Petzold, Charles. Programming Windows: The Microsoft Guide to Writing Applications for Windows 3. Redmond, WA: Microsoft Press, 1990.

Articles

Wegner, Tim. "Coding for PNG Graphics", PC Techniques (Feb/Mar 1996): 32-38.

Other

"Graphic Image Format FAQ 3-4." James D. Murray, 1994-1996.

PBM, PGM, PPM, PNM Specifications by Jef Poskanzer, copyright " 1989, 1991.

PNG (Portable Network Graphics), tenth draft. Page 5, copyright Thomas Boutell, May 1995.


SOFTWARE LICENSE AGREEMENT

YOUR INSTALLATION, USE AND DISTRIBUTION OF THIS SOFTWARE PRODUCT ("THE PRODUCT") SIGNIFIES YOUR ACCEPTANCE OF THE TERMS OF THIS LICENSING AGREEMENT BETWEEN YOU ("LICENSEE") AND ACCUSOFT CORPORATION, A DELAWARE CORPORATION WITH ITS PRINCIPAL PLACE OF BUSINESS AT 71 LYMAN STREET, NORTHBOROUGH, MASSACHUSETTS 01532 ("ACCUSOFT")

Article 1: Definitions.

Section 1.0. Defined Terms. Terms defined in this Article 1 shall have the meanings given below. Defined terms may be used in the singular or plural.

Section 1.1. "Agreement" means this Software License Agreement, which includes this Agreement's terms and conditions, Order Forms, Schedules, Exhibits, Addenda, and Amendments, if any, which are incorporated in, and form an integral part of, this Agreement.

Section 1.2. "Application" means only the software application program or programs developed by Licensee (and all versions and releases thereof) that contain a copy of, and is linked to, the Product's Distributable Files.

Section 1.3. "Business Day" means a day or part of a day when AccuSoft is open for business, excluding Saturdays, Sundays, official United States federal holidays, Commonwealth of Massachusetts state holidays, and AccuSoft holidays.

Section 1.4. "Confidential information" means any data or information, oral or written, that relates to either party's (or, if either party is bound to protect the confidentiality of any other person's information, such other person's) past, present, or future research, development or business activities, including any unannounced product(s) and service(s), and including any information relating to services, developments, inventions, processes, plans, financial information, customer lists, forecasts, and projections, including the terms of this Agreement.

Section 1.5. "Develop" or "Development" means the development of one or more Applications by Licensee that contain a copy of the Product's Distributable Files.

Section 1.6. "Distributable File" means those files contained in the Product that may be distributed with Licensee's Application, as defined in Section 1.2. The list of Distributable Files for each Product is identified in the documentation that accompanies each Product.

Section 1.7. "Distribute" or "Distribution" means the distributing, deploying, selling, reselling, leasing, renting, licensing, lending or any other act whereby Licensee distributes the Application to an End User, whether such End User is internal or external to Licensee.

(a) "External Distribution" means that the Application containing the product is distributed for any reason other than internal distribution.

(b) "Internal Distribution" means that the Application containing the Product is not distributed for either commercial use or for sale (or resale), and is for use by End Users who are employees, interns, or contract employees of Licensee.

Section 1.8. "Distribution Method" means the method by which Licensee's End User accesses the Distributable Files. A Distribution Method may include one or more of the following:

(a) "Client/Server" means the End User is permitted to install the Distributable File on a Server specifically designated to host the Application from which a fixed number of Named or Concurrent Users can access the Application at any one time.

(b) "Concurrent User" means the End User is permitted to have (i) a fixed number of simultaneous individual users who are authorized to use the Application, or (ii) a multiple number of individual users who can sequentially use the Application on one single computer or workstation (i.e. a "kiosk model").

(c) "Named User" means the End User is permitted to have only one single, named individual user who is authorized to use one copy of the Application on a single personal computer.

(d) "Server" means the End User is permitted to install the Distributable File on a networked processor specifically designated to process one or more instances of the Application by (i) individual users via a single computer or workstation, (ii) non-user computers for automated tasks (a "Process Machine") (for example, batch imaging conversion processing, printer server processing, etc.), or (iii) a client applet server accessible via a web browser (a "Web Server").

Section 1.9. "End User" means the person or entity to which Licensee distributes the Application for use in the ordinary course of its business, and not for re-distribution or resale by such person or entity.

Section 1.10. "Installation" means the act of installing the Product on any system.

Section 1.11. "Licensing Fees" mean the fees identified in the Order Form that are mutually agreed to by AccuSoft and Licensee.

Section 1.12. "Order Form" means the order form, or other such document prescribed by AccuSoft, that details the Product(s), quantities, fees, and term of this Agreement and is executed by both parties.

Section 1.13. "Product" means the software product or products, including any accompanying documentation, identified in the Order Form and licensed by AccuSoft under this Agreement.

Section 1.14. "Supplier" means any software product or products, including any accompanying documentation, licensed by AccuSoft for use and distribution in the Product.

Section 1.15. "Term" means the period of time of this Agreement, as identified in the Order Form.

Article 2: Scope of License.

Section 2.1. Evaluation License. If the Product installed by Licensee is for evaluation purposes only, AccuSoft grants Licensee a license solely for the purpose of sampling and evaluating such Product for the timeframe specified in the evaluation period. No other rights, including but not limited to the rights stated in Sections 2.2 and 2.3, are applicable to evaluation copies of the product.

Section 2.2. Development License. Subject to the terms and conditions set forth in this Agreement, AccuSoft grants Licensee a non-exclusive, non-transferable, worldwide license to use the Product on a single machine, and incorporate all or portions of the Distributable Files into one or more Applications for Distribution by Licensee. Unless otherwise agreed to in writing by the parties, no more than one developer is authorized to use one single Product, and the Product is not to be used concurrently or on a site-wide basis, via a server or other networked connection. Licensee may make one copy of the Product for backup or archive purposes. If Licensee desires to have more than one developer use the Product, Licensee must purchase additional development licenses from AccuSoft.

Section 2.3. Distribution License. Subject to the terms and conditions set forth in this Agreement, AccuSoft grants Licensee a non-exclusive, non-transferable, worldwide license to distribute to End Users (either directly or indirectly) a copy of one or more distributable files in any applications developed pursuant to Section 2.2 by the Distribution Method identified on the Order Form during the Term of the Agreement. The Licensing Fee for a Distribution License will vary depending on the type or subtype of Distribution Method and the quantities licensed. If Licensee distributes more licenses than it has pre-purchased, as identified on the Order Form, Licensee's purchase of such additional licenses shall be subject to the terms and conditions set forth in Article 3 of this Agreement.

Section 2.4. Licensee shall distribute the Distributable Files in object code form only. No license or other right is granted to Licensee with respect to any of the Product's source code. Licensee shall not alter, modify, disassemble, decompile or reverse engineer the Product in any way or manner.

Section 2.5. Licensee shall distribute the Application to its resellers, OEMs, or other distribution channels only pursuant to a written agreement that binds the resellers, OEMs, or other distribution channels to comply with the terms and conditions of Articles 2 and 5 of this Agreement.

Section 2.6. Licensee shall distribute the Application to its End Users only pursuant to a written agreement that prohibits the End User from Distributing, creating, copying, duplicating, re-distributing, disassembling, decompiling, reverse engineering, or sublicensing the Product, and shall use its best efforts to ensure the same.

Section 2.7. Licensee may distribute the Application only if the Application:

(a) operates solely on the hardware and operating system(s) for which the Product is intended to be used;

(b) does not extend access to the Product's application programming interface (API);

(c) includes within the executable object files of all copies of the Product, including all Distributable Files, AccuSoft's patent, copyright, trademark and proprietary notices; and

(d) recognizes AccuSoft's copyright ownership in the Application initialization screen or "About Box", and/or in the documentation for the Application as follows: Imaging Technology provided under License by AccuSoft Corporation. ImageGear © 1996-2008. All Rights Reserved." Italics are not required. This requirement is not applicable if Licensee's internal application has neither an initialization screen nor an "About Box."

Section 2.8. If Licensee's Application is intended for external distribution, Licensee's Application shall also:

(a) not compete to any degree with the Product. Such competitive products are defined as imaging software development toolkit intended for use by application programmers and/or system integrators;

(b) be substantially greater in scope with greater functionality and features than those of the Product;

(c) not be a software development toolkit or provide a software development environment to the End User, and

(d) recognize AccuSoft's copyright ownership in the Application initialization screen (or "About Box") and/or in the documentation for the Application as follows: Imaging Technology provided under License by AccuSoft Corporation. ImageGear © 1996-2008. All Rights Reserved." Italics are not required.

Section 2.9. As required by United States export regulations, Licensee shall not permit export of the Product, or any direct products thereof, to any country to which export is then controlled by the United States Bureau of Export Administration, unless Licensee has that agency's prior written approval. Licensee shall require its End Users to comply with the provisions of this Section.

Section 2.10. If Licensee (or Licensee's End User) is an office, branch or agency of the U.S. Government, then its use, duplication and disclosure of the Product or any part thereof, shall be subject to the following additional requirements: The Product is a "commercial item," as such term is defined in 48 C.F.R. 12.101 (Oct. 1995), consisting of "commercial computer software" and "commercial computer software documentation," as such terms are used in 48 C.F. 12.212 (September 1995). Consistent with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4, the U.S. Government End Users acquire the Product and/or Application with only those rights set forth in this section.

Section 2.11. AccuSoft reserves the right to include in the Product one or more software devices to ensure that Licensee's use of the Application is consistent with the use identified in the Order Form, and does not exceed the maximum number of fixed licenses granted by AccuSoft, if any.

Article 3: Fees and Reporting.

Section 3.1. Licensee shall pay to AccuSoft all Licensing Fees due for all copies of the Application containing the Distributable Files licensed and Distributed by Licensee. All Licensing Fees are payable in U.S. dollars and are non-refundable.

Section 3.2. Timely payment of the Licensing Fee permits Licensee to use the Product, and Distribute its Application (either directly or indirectly) to End Users. For U.S. based Licensees, payment is due 30 days from the date of the invoice. For all other Licensees, payment is due in full prior to or contemporaneously with the licensing of the Product. Late payment charges shall be imposed on all outstanding balances for each month or portion thereof that the outstanding balance remains unpaid, at the rate of 1.5% per month or the maximum rate permitted by law for such charge.

Section 3.3. Where required by law, AccuSoft will collect from Licensee, and Licensee is responsible to pay for, sales and all other taxes associated with the order, unless AccuSoft is provided a valid and correct tax exemption certificate prior to order acceptance. The payment of such tax is the sole responsibility of Licensee.

Section 3.4. Licensee understands and acknowledges that in order to receive bulk discount pricing for distribution Licensing Fees, it must pre-pay for such licenses. In the event that Licensee Distributes more licenses than it has purchased, or distributes by a Distribution Method not stated on the Order Form, Licensee shall pay AccuSoft's then-current quantity-one pricing for each copy distributed over the number licenses purchased. Quantity-one pricing is defined as the fee associated with purchasing one (1) distribution license.

Section 3.5. Licensee shall inform AccuSoft in writing within thirty (30) days after the date of the first shipment of copies of the Application. Thereafter, Licensee shall complete a License Distribution Report (or other such Distribution Fee statements provided by AccuSoft) each calendar quarter stating the number of Distribution Licenses distributed during each Disclosure Period and estimating the number of Distribution License that may be used during the next Disclosure Period. An authorized officer of Licensee shall sign all such License Distribution Reports.

Section 3.6. Upon AccuSoft's request, at mutually agreeable times no more frequently than once annually, an auditor chosen by AccuSoft shall be provided reasonable access during normal business hours to the relevant records of Licensee for the purpose of an audit of Distribution Fees due. Such records shall include, without limitation, information concerning copies of the Application made and distributed and other information necessary to verify the payments and amounts due AccuSoft hereunder. AccuSoft shall maintain in confidence any proprietary information of Licensee obtained during the course of such audit. The results of any such audit shall be final and dispositive. If the auditor's report indicates an underpayment of more than 10% for any auditing period, Licensee shall pay the full cost of the audit, and pay AccuSoft the balance due within thirty (30) days from presentation of the report.

Article 4: Support.

Section 4.1. For one year after Licensee's purchase or installation of the Product (pursuant to Section 2.2 of this Agreement), whichever is earlier, AccuSoft shall provide Licensee with the level of product support and maintenance identified on the Order Form. A copy of each of AccuSoft's various product support and maintenance levels may be found in the on-line help section included with the Product. If no such product support and maintenance is identified, the Product does not come with support.

Section 4.2. Licensee agrees that, within thirty days of its release of any Application built with the Product, it will provide AccuSoft with two (2) copies of such Application for support purposes. AccuSoft's use of such Application will be limited to providing support to Licensee, and shall be governed by the provisions of Article 7 of this Agreement.

Article 5: Intellectual Property.

Section 5.1. Licensee recognizes and acknowledges the exclusive right of AccuSoft (and its Suppliers) in and to all patents, trademarks, service marks, trade names, copyrights, and other intellectual property and proprietary rights in and to the Product, and that such patents, trademarks, service marks, trade names, copyrights, and other intellectual property and proprietary rights are the sole and exclusive property of AccuSoft and its Suppliers.

Section 5.2. Licensee waives its right to contest any of AccuSoft's or its Supplier's patents, trademarks, service marks, trade names, copyrights, and other intellectual property and proprietary rights in and to the Product.

Section 5.3. Licensee shall not use such trademarks, service marks, and trade names except where permitted under this Agreement without receiving AccuSoft's prior written approval of such use. If such approval is granted, Licensee's right to use such trademarks, service marks, and trade names shall end upon the termination of this Agreement.

Article 6: Confidentiality.

Section 6.1. Licensee shall remain in exclusive control of the Product, including but not limited to, the physical media, downloads, sample code, and documentation. The parties agree that neither party shall disclose or otherwise make available any confidential information provided to it by the other party. Unless otherwise agreed to by the parties, the scope of this Section shall be given the broadest interpretation possible and shall include, but not be limited to, the terms and conditions of this Agreement, the Order Form, and pricing.

Section 6.2. The obligations of non-disclosure in Section 6.1 shall not apply to information that (i) is publicly available or in the public domain at the time disclosed; (ii) is, or becomes, publicly available or enters the public domain through no fault of the party receiving such information; (iii) is rightfully communicated to the recipient by persons not bound by confidentiality obligations with respect thereto; (iv) is already in the recipient's possession free of any confidentiality obligations with respect thereto at the time of disclosure; (v) is independently developed by the recipient; (vi) is approved for release or disclosure by the disclosing party without restriction, (vii) is required by a court of competent jurisdiction.

Article 7: Term and Termination.

Section 7.1. Unless otherwise agreed to by the parties, this Agreement shall become effective upon its execution by both parties, and shall continue in full force and effect until terminated in accordance with the terms set forth in the Order Form or this Agreement.

Section 7.2. In the event that Licensee materially breaches this Agreement, or ceases business or is adjudged bankrupt or insolvent, then AccuSoft may, at its option, terminate this Agreement, by giving ten (10) Business Days written notice of such termination, which notice shall identify and describe the basis for such termination. If, prior to expiration of such period, Licensee cures such default, termination shall not take place.

Section 7.3. In the event of any termination of this Agreement, Licensee shall stop manufacturing and Distributing the Application containing a copy of the Distributable Files, and require its resellers, OEMs, and other distribution channels (if any) to likewise stop manufacturing and Distributing the Application containing a copy of the Distributable Files. Within ten (10) Business Days thereafter, Licensee shall return or, at AccuSoft's option, destroy the Product and all copies in whole or in part thereof, whether or not incorporated in or with the Application, and within Licensee's possession, custody and control, and shall certify to AccuSoft in writing within ten (10) Business Days thereafter that it has complied with the foregoing obligation.

Section 7.4. For external distributions, the termination of this Agreement shall not affect any rights of End Users to use the Application if such copies were shipped prior to the termination of this Agreement. So long as Licensee's external distributions to End Users and the End Users' use of the Application conforms to the terms and conditions set forth in this Agreement, the End User's rights to use the Product as incorporated into the Application shall be perpetual.

Section 7.5. Articles 1, 5, 6, 7, 8 and 9 shall continue in full force and effect, notwithstanding any such termination of this Agreement.

Article 8: Limited Warranty.

Section 8.1. AccuSoft represents and warrants that it has full power and authority to enter into this Agreement, and has sufficient right, title, and interest in the Product to enter into this Agreement.

Section 8.2. Licensee understands and acknowledges that the Product, although functionally complete, has not been extensively tested by AccuSoft or its Suppliers as to the correctness or speed of operation in Licensee's Application. Although AccuSoft will make reasonable efforts to correct any material nonconformity between the Product and its then-current documentation that is brought to AccuSoft's attention with written, documented reports from Licensee, ACCUSOFT AND ITS SUPPLIERS DO NOT AND CANNOT WARRANT THE RESULTS OBTAINED BY USING THE PRODUCT. AccuSoft's entire liability and Licensee's exclusive remedy under this Agreement shall be to provide reasonable support services.

Section 8.3. THE PRODUCT IS PROVIDED "AS IS." ACCUSOFT AND ITS SUPPLIERS SPECIFICALLY DISCLAIM ANY AND ALL WARRANTY TO LICENSEE OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, PERFORMANCE RESULTS AND NON INFRINGEMENT. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PRODUCT IS WITH LICENSEE.

Section 8.4. IN NO EVENT WILL ACCUSOFT OR ITS SUPPLIERS BE LIABLE TO LICENSEE FOR ANY DAMAGES, INCLUDING LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING FROM THE USE OR INABILITY TO USE THE PRODUCT EVEN IF IT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. Some states or jurisdictions do not allow the exclusion or limitation of incidental, consequential or special damages, or the exclusion of implied warranties, or limitations on how long an implied warranty may last, so the above limitations may not apply to Licensee. To the extent permissible, any implied warranties are limited to thirty (30) days. This warranty gives Licensee specific legal rights. Licensee may have other rights which vary from state to state or jurisdiction to jurisdiction.

Section 8.5. The warranty extended in this Article extends only to Licensee, and shall not apply to any other person or entity including, but not limited to, Licensee's End Users.

Article 9: General Provisions.

Section 9.1. AccuSoft and Licensee warrant that they have the requisite authority to enter into this Agreement.

Section 9.2. This Agreement constitutes the entire understanding and agreement between AccuSoft and Licensee regarding its subject matter, and supercedes all previous oral and written communications, agreements, memoranda, representations, or understandings between AccuSoft and Licensee regarding this Agreement. No other rights or licenses are granted to Licensee, except as expressly provided herein.

Section 9.3. This Agreement shall not be amended, altered, changed or modified in any way, unless agreed to in writing by both AccuSoft and Licensee. Such writing must be executed by a duly authorized representative of AccuSoft and a duly authorized representative of Licensee.

Section 9.4. This Agreement is not transferable or assignable by Licensee under any circumstances, without the prior written consent of AccuSoft. AccuSoft will not unreasonably withhold such consent. This agreement shall be binding upon, and is made for the benefit of, each party, its successors, and permitted assignees (if any). For the purposes of this Agreement, any change in control of Licensee shall constitute an assignment or transfer of this Agreement. As used in this section, a change in control is defined as (i) any change in ownership of more than fifty percent (50%) of the voting interest in Licensee, whether by merger, purchase, foreclosure of a security interest or other transaction, or (ii) a sale of all or substantially all of the assets of Licensee.

Section 9.5. The relationship established by this Agreement between Licensee and AccuSoft shall be that of licensee and licensor. Nothing contained in this Agreement shall be construed as creating a relationship of agency, joint venture or partnership between Licensee and AccuSoft. Neither party shall have any right whatsoever to incur any liabilities or obligations on behalf of the other party.

Section 9.6. The laws of the Commonwealth of Massachusetts shall govern this Agreement, excluding that body of law known as conflict of laws and the United Nations Convention on Contracts for the Sale of Goods. Any action or proceeding brought by either party against the other arising out of, or related to, this Agreement shall be brought only in a state or federal court of competent jurisdiction located in the Commonwealth of Massachusetts and the parties hereby consent to the personal jurisdiction of said courts.

Section 9.7. In the event that any provision of this Agreement is found invalid or unenforceable pursuant to a judicial decree or decision, the remainder of this Agreement shall remain valid and enforceable according to its terms.

Section 9.8. AccuSoft's failure to perform any term or condition of this Agreement as a result of conditions beyond its control such as, but not limited to, war, strikes, fires, floods, acts of God, governmental restrictions, power failures, or damage or destruction of any network facilities or servers, shall not be deemed a breach of this Agreement.

Section 9.9. In the event of suit or any legal action due to any breach of this Agreement is commenced to enforce this Agreement or otherwise relating to this Agreement, the prevailing party shall be entitled to all attorneys' fees and costs incurred in connection therewith.

Section 9.10. The headings provided in this Agreement are for convenience and reference purposes only. In the event of a conflict between the terms and conditions listed in Articles 1 through 10, and the attached Schedules, the terms and conditions shall govern.

Section 9.11. A waiver of a breach, violation, or default under this Agreement shall not be a waiver of any subsequent breach, violation or default. Failure of either party to enforce compliance with any term or condition of this Agreement shall not constitute a waiver of such term or condition.

Section 9.12. All notices and communications shall be in writing and shall be deemed to have been duly given when delivered or three (3) Business Days after mailing by certified mail, return receipt requested, postage prepaid, addressed to the parties at their respective addresses set forth on the Order Form or at such other addresses as the parties may designate by written notice in accordance with this section.

Section 9.13. The Order Form, and any amendments or addenda to this Agreement, may be executed in counterparts, each of which will be considered an original, but all counterparts together will constitute one agreement. A facsimile of a signed copy of this Agreement, or an electronic or other digital signature imprinted on this Agreement, may be relied upon as an original.


Schedule A: Additional Terms and Conditions Applicable to Adobe® Technology

1. Adobe Technology

If Licensee's use and distribution of the Product includes Adobe Technology and related documentation, the term "Product" as defined in Section 1.13 of the Agreement includes Adobe Technology and related documentation, and any upgrades, modified versions, updates, additions, and copies thereof.

2. Font License.

If the Product includes font software, Licensee may embed the font software, or outlines of the font software, into its Application to the extent that the font vendor copyright owner allows for such embedding. The fonts contained in this package may contain both Adobe and non-Adobe owned fonts. Licensee may fully embed any font owned by Adobe.

3. Limited Warranty

ARTICLE 8 OF THE AGREEMENT STATES THE SOLE AND EXCLUSIVE REMEDIES FOR ACCUSOFT'S BREACH OF WARRANTY. EXCEPT FOR THE FOREGOING LIMITED WARRANTY, ADOBE AND ITS SUPPLIERS MAKE NO WARRANTY, EXPRESS OR IMPLIED, AS TO MERCHANTABILITY, FITNESS FOR ANY PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT WILL ADOBE OR ITS SUPPLIERS BE LIABLE TO LICENSEE FOR ANY CONSEQUENTIAL, INCIDENTAL OR SPECIAL DAMAGES, INCLUDING ANY LOST PROFITS OR LOST SAVINGS, EVEN IF AN ADOBE REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY THIRD PARTY. Some states or jurisdictions do not allow the exclusion or limitation of incidental, consequential or special damages, or the exclusion of implied warranties, or limitations on how long an implied warranty may last, so the above limitations may not apply to Licensee. To the extent permissible, any implied warranties are limited to thirty (30) days. This warranty gives Licensee specific legal rights. Licensee may have other rights which vary from state to state or jurisdiction to jurisdiction.

4. Trademarks.

Adobe and Adobe PDF Library are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.


Schedule B: Additional Terms and Conditions Applicable to MIT's FFTW Technology

1. FFTW Technology

If Licensee's use and distribution of the Product includes FFTW Technology, please note that the FFTW technology is provided to AccuSoft under a copyright license from the Massachusetts Institute of Technology (MIT).

2. Disclosure of Customer's Information

If Licensee informs AccuSoft that is desires to license the FFTW technology, AccuSoft is required to notify MIT of Licensee's name and contact information. Additionally, upon request from MIT, AccuSoft may be required to provide MIT with a copy of this specific licensing agreement. MIT shall treat all this information as confidential information of the AccuSoft.

3. Termination.

In the event MIT terminates its FFTW copyright license with AccuSoft, Licensee's rights to use the FFTW technology may be affected as follows:

a. If Licensee is the End User of the Product (e.g. the Application is for Licensee's internal use only), and has no rights to sublicense or distribute the Product, Licensee's right to continued use of the FFTW technology within the Product shall not be affected by such termination.

b. If Licensee is a Sublicensee of the Product, and has the rights to sublicense or distribute Product containing the FFTW technology, Licensee shall be required to contact MIT directly to procure the appropriate level of licensing. By Agreement, AccuSoft is required to provide MIT with a list of all customers who have sublicensing or distribution rights. All such information is deemed confidential in the AccuSoft-MIT Agreement.

c. However, Licenses of derivative works created by Licensee shall survive the termination of this Agreement, so long as Licensee understands that MIT specifically disclaims any and all warranties in relation to the derivative works, and that Licensee, in its License Agreement, specifically disclaim any and all warranties by MIT. in relation to the derivatives to the full extent permitted by law and limit MIT's liability for damages related to the derivatives to the full extent permitted by law.

4. Limited Warranty

ARTICLE 8 OF THE AGREEMENT STATES THE SOLE AND EXCLUSIVE REMEDIES FOR ACCUSOFT'S BREACH OF WARRANTY. THIS ARTICLE SHALL BE SUPERSEDED BY THE FOLLOWING: MIT MAKES NO WARRANTY, EXPRESS OR IMPLIED, AS TO MERCHANTABILITY, FITNESS FOR ANY PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT WILL MIT OR ITS SUPPLIERS BE LIABLE TO LICENSEE FOR ANY CONSEQUENTIAL, INCIDENTAL OR SPECIAL DAMAGES, INCLUDING ANY LOST PROFITS OR LOST SAVINGS, EVEN IF AN MIT REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY THIRD PARTY. Some states or jurisdictions do not allow the exclusion or limitation of incidental, consequential or special damages, or the exclusion of implied warranties, or limitations on how long an implied warranty may last, so the above limitations may not apply to Licensee. To the extent permissible, any implied warranties are limited to thirty (30) days. This warranty gives Licensee specific legal rights. Licensee may have other rights which vary from state to state or jurisdiction to jurisdiction.


Schedule C: Additional Terms and Conditions Applicable to Microsoft's XPS Functionality

1. Microsoft's Technology

If Licensee's use and distribution of the Product includes Microsoft's XPS Functionality (as defined below), please note that the XPS Functionality technology is provided to AccuSoft under a royalty free copyright license from Microsoft. XPS Functionality includes the following:

a. Microsoft's XPS Essentials Pack;

b. Microsoft's MSXML 6.0; and

c. Microsoft's Windows Desktop 4.0 Search Preview.

2. XPS Technology License

Under the terms of Microsoft's various licensing agreements, AccuSoft has a perpetual, royalty-free license to redistribute the XPS functionality to the Licensee. However, if Licensee desires to Externally Distribute such XPS Functionality to its End Users, Licensee is required to download directly the XPS Functionality prior to any such External Distribution.

3. Limited Warranty

ARTICLE 8 OF THE AGREEMENT STATES THE SOLE AND EXCLUSIVE REMEDIES FOR ACCUSOFT'S BREACH OF WARRANTY. EXCEPT FOR THE FOREGOING LIMITED WARRANTY, MICROSOFT AND ITS SUPPLIERS MAKE NO WARRANTY, EXPRESS OR IMPLIED, AS TO MERCHANTABILITY, FITNESS FOR ANY PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT WILL ADOBE OR ITS SUPPLIERS BE LIABLE TO LICENSEE FOR ANY CONSEQUENTIAL, INCIDENTAL OR SPECIAL DAMAGES, INCLUDING ANY LOST PROFITS OR LOST SAVINGS, EVEN IF AN ADOBE REPRESENTATIVE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY THIRD PARTY. Some states or jurisdictions do not allow the exclusion or limitation of incidental, consequential or special damages, or the exclusion of implied warranties, or limitations on how long an implied warranty may last, so the above limitations may not apply to Licensee. To the extent permissible, any implied warranties are limited to thirty (30) days. This warranty gives Licensee specific legal rights. Licensee may have other rights which vary from state to state or jurisdiction to jurisdiction.

4. Trademarks.

Microsoft and the components of the XPS Functionality are either registered trademarks or trademarks of Microsoft in the United States and/or other countries.


Software Support and Maintenance Policy

AccuSoft provides product support and maintenance services for all of its products. These services provide the subscriber with a certain level of ongoing technical assistance (i.e., support) and access to software updates (i.e., maintenance). The subscriber is the individual or company who has licensed one or more products from AccuSoft, and who is entitled to product support and maintenance services under the terms and conditions of its Software License Agreement with AccuSoft. Additionally, unless otherwise stated in this policy, the terms used in this policy shall have the same meanings as the terms defined in Article I of the Software License Agreement.

See Also:
  • Preferred Level
  • Premier Level

Preferred Level

At the Preferred Level, product support and maintenance services entitle a subscriber to the following:

1. Maintenance.

AccuSoft makes periodic updates to its products to correct errors, make enhancements, or improve performance. An update is defined as a minor release to the current version that results in a patch, bug fix, updated documentation, or improved performance of the Product. At the Preferred Level, subscribers are entitled to any and all updates to the version of the product licensed by the subscriber during the support term.

At the Preferred Level, subscribers are also entitled to any and all upgrades to the version of the product licensed by the subscriber during the support term. An upgrade is defined as a change to the product that substantially enhances the functionality of the product and/or results in change in the version number of the product to the left of the decimal point.

2. Technical Assistance.

Technical assistance is provided to subscribers to enable AccuSoft to determine and resolve product problems and questions. Technical assistance does not include software application consulting, or custom coding of a subscriber's solution.

Technical assistance is only provided via electronic methods from the AccuSoft support web site to the individual identified by the subscriber as the designated support contact for the product.

Preferred support is entirely web-based for both problem ticketing and resolution. During the support term, Preferred Level subscribers receive automated e-mail notification of any updates to ticket that have been posted to AccuSoft's support web site. The designated support contact will have unlimited access to the AccuSoft web site for ticket creation, status monitoring, information access, etc.

Preferred Support services include:

  • Electronic submission of product problems and questions, and online access to update and track the progress of your case
  • Electronic access to up-to-date knowledge databases for our products that provide answers and fixes to commonly asked questions and problems
  • Electronic access to product documentation including the updated guides and manuals, technical bulletins, flashes, and release notes
  • Electronic access to all patches, product fixes, release and maintenance information for the version licensed

Plus,

  • Electronic access to all updates, enhancements and upgrades (including new versions/releases) that may be issued to the licensed product during your support term (one-year by default)
  • Electronic notification that a resolution or status update is available to view through AccuSoft's electronic web interface

3. Support Services Availability and Coverage.

Electronic access is available 24 hours a day, 7 days a week.

AccuSoft's Customer Support department is open Monday through Friday, 8:30 a.m. to 5:30 p.m. EST, except on designated AccuSoft holidays. Requests for assistance received after the daily coverage period shall be deemed to have been received the next business day.

4. Support Services - Response Objectives.

AccuSoft shall use reasonable efforts to meet the following objectives with regard to remedial support for each AccuSoft productsoftware.

  • Initial Response. Upon receipt, AccuSoft will respond to the subscriber's report of a problem with the product based upon the initial response time and problem severity priority listed below:
    Problem
    Resolution
    Stages
    for Preferred
    Level
    Problem Severity
    Priority I
    Priority II
    Priority III
    Initial Response
    3 Business Hours
    8 Business Hours
    24 Business Hours
    Response Update
    Every 2 Business Days
    Every 2 Weeks
    Every 4 Weeks
    Relief
    Priority work
    ASAP
    Reasonable efforts
  • Problem Severity. Problem Severity is prioritized as follows:

Priority I - Subscriber is unable to do production work or production is jeopardized and a work-around is not available or is generally unacceptable;

Priority II - A major product function is inoperable, but production can continue;

Priority III - A loss of a function that does not seriously impact operation or schedules.

  • Problem Resolution Stages. After the initial response, AccuSoft will provide a response update to the subscriber according to the schedule specified above. AccuSoft will use the following objectives for problem resolution: Response - A technically qualified engineer is working on the problem; Relief - subscriber's operation is no longer at risk due to the original problem, or the subscriber understands and accepts all risk. A permanent problem resolution may be available in a subsequent revision.

5. Additional Support Options.

During the first ninety (90) days after the purchase of the product, a subscriber is eligible to upgrade to an enhanced level of support services that includes but is not limited to, access to AccuSoft's Customer Support Department.

Additionally, AccuSoft may also provide on-site technical assistance to augment any such remote technical assistance. On-site technical assistance shall be chargeable to the subscriber based on AccuSoft's then current on-site support services fees and policies. On-site technical assistance is not included in the services provided in the maintenance and support subscription described above.

6. Subscriber Responsibilities.

  • Information. Subscriber problem reports to AccuSoft must contain all pertinent information regarding the issue, including but not limited to, the following: the AccuSoft software/revision number, Operating system/version, Development Platform, Problem Description, Log files/Test Case and Problem Severity. Subscribers must execute diagnostic routines if provided by AccuSoft, and inform AccuSoft of the results. Subscribers must also verify the existence of a product problem and provide the conditions under which it may be duplicated by AccuSoft at an AccuSoft location. All problem reports must be in English.
  • Technical Contact. During the period of time in which AccuSoft is working on the subscriber issue, the subscriber shall provide a technical contact who is familiar with the product problem and the subscriber environment.
  • Remote Access. By purchasing software support and maintenance services, the subscriber agrees to permit AccuSoft to remotely access the subscribers computer system for the sole purpose of diagnosing any reported problem with the product including, but not limited to, granting AccuSoft permission to install remote access software on subscriber's computer system(s) that contain the product. All standard confidentiality provisions identified in the Software License Agreement will apply. The subscriber shall provide remote access via dial-in or internet when required by AccuSoft to analyze a problem.

7. Service Limitations.

  • AccuSoft will support only the most current version of the Product. The current version is defined as the version of the product that is commercially available for sale by AccuSoft. Upon the release of such current version of a product, AccuSoft will continue to support and maintain the version of the product released immediately prior to the release of the current version in accordance with the then prevailing End-of-Life policy.
  • All associated computer hardware and operating system software and product must be maintained at the latest version deemed necessary by AccuSoft. AccuSoft shall not be obligated to provide support services under this policy if the service is regarding hardware, software or product that does not conform to the above statement. Any and each such service may result in additional charges for labor and materials as determined by AccuSoft, and shall be provided at the sole discretion of AccuSoft.
  • On-site services will be provided by quotation, are not covered by this policy, and shall be provided at the sole discretion of AccuSoft. Additional AccuSoft consulting and/or coding services may also be available to the subscriber under a separate agreement. AccuSoft may provide assistance to help optimize or enhance subscriber's use of the product. When AccuSoft determines that any such assistance has exceeded a reasonable level, AccuSoft will supply a quotation for additional Consulting Services.
See Also:
  • Premier Level

Premier Level

At the Premier Level, product support and maintenance services entitle a subscriber to the following:

1. Maintenance.

AccuSoft makes periodic updates to its products to correct errors, make enhancements, or improve performance. An update is defined as a minor release to the current version that results in a patch, bug fix, updated documentation, or improved performance of the Product. At the Premier Level, subscribers are entitled to any and all updates to the version of the product licensed by the subscriber during the support term.

At the Premier Level, subscribers are also entitled to any and all upgrades to the version of the product licensed by the subscriber during the support term. An upgrade is defined as a change to the product that substantially enhances the functionality of the product and/or results in change in the version number of the product to the left of the decimal point.

2. Technical Assistance.

Technical assistance is provided to subscribers to enable AccuSoft to determine and resolve product problems and questions. Technical assistance does not include software application consulting, or custom coding of a subscriber's solution.

Premier support is pro-active, with personalized contact both to and from the subscriber via any and all contact methods - e-mail, telephone, facsimile - as well as AccuSoft's electronic web interface. The designated support contact may make unlimited requests for assistance to AccuSoft's Customer Service department.

Premier Support services include:

  • Electronic and/or personalized submission of product problems and questions, and online access to update and track the progress of your case
  • Electronic access to up-to-date knowledge databases for our products that provide answers and fixes to commonly asked questions and problems
  • Electronic access to product documentation including the updated guides and manuals, technical bulletins, flashes, and release notes
  • Electronic access to all patches, product fixes, release and maintenance information for the version licensed

Plus,

  • Electronic access to all updates, enhancements and upgrades (including new versions/releases) that may be issued to the licensed product during your support term (one-year by default)
  • Electronic notification that a resolution or status update is available to view through AccuSoft's electronic web interface

Additionally, should AccuSoft's Customer Support analysts need to investigate an issue within your own computer environment, the Customer Support analysts may recommend the use of our e-support solution. This system allows AccuSoft to assist the subscriber by allowing the analyst to:

  • Access your system to view, diagnose and solve your problems online
  • Run applications to ensure proper installation and configuration
  • Download and install patches or updates to your system
  • Upload your files for analysis
  • Include other analysts for consultation
  • Interact with you via text chat
  • Record the entire support session for archival

3. Support Services Availability and Coverage.

Electronic access is available 24 hours a day, 7 days a week.

AccuSoft's Customer Support department is open Monday through Friday, 8:30 a.m. to 5:30 p.m. EST, except on designated AccuSoft holidays. Requests for assistance received after the daily coverage period shall be deemed to have been received the next business day.

4. Support Services - Response Objectives.

AccuSoft shall use reasonable efforts to meet the following objectives with regard to remedial support for each AccuSoft productsoftware.

  • Initial Response. Upon receipt, AccuSoft will respond to the subscriber's report of a problem with the product based upon the initial response time and problem severity priority listed below:
    Problem
    Resolution
    Stages for
    Premier
    Level
    Problem Severity
    Priority I
    Priority II
    Priority III
    Initial Response
    1 Business Hour
    4 Business Hours
    12 Business Hours
    Response Update
    Each Business Day
    Every Week
    Every 2 Weeks
    Relief
    Work Continuously
    ASAP
    Reasonable efforts
  • Problem Severity. Problem Severity is prioritized as follows:

Priority I - Subscriber is unable to do production work or production is jeopardized and a work-around is not available or is generally unacceptable;

Priority II - A major product function is inoperable, but production can continue;

Priority III - A loss of a function that does not seriously impact operation or schedules.

  • Problem Resolution Stages. After the initial response, AccuSoft will provide a response update to the subscriber according to the schedule specified above. AccuSoft will use the following objectives for problem resolution: Response - A technically qualified engineer is working on the problem; Relief - subscriber's operation is no longer at risk due to the original problem, or the subscriber understands and accepts all risk. A permanent problem resolution may be available in a subsequent revision.

5. Additional Support Options.

AccuSoft may also provide on-site technical assistance to augment any such remote technical assistance. On-site technical assistance shall be chargeable to the subscriber based on AccuSoft's then current on-site support services fees and policies. On-site technical assistance is not included in the services provided in the maintenance and support subscription described above.

6. Subscriber Responsibilities.

  • Information. Subscriber problem reports to AccuSoft must contain all pertinent information regarding the issue, including but not limited to, the following: the AccuSoft software/revision number, Operating system/version, Development Platform, Problem Description, Log files/Test Case and Problem Severity. Subscribers must execute diagnostic routines if provided by AccuSoft, and inform AccuSoft of the results. Subscribers must also verify the existence of a product problem and provide the conditions under which it may be duplicated by AccuSoft at an AccuSoft location. All problem reports must be in English.
  • Technical Contact. During the period of time in which AccuSoft is working on the subscriber issue, the subscriber shall provide a technical contact who is familiar with the product problem and the subscriber environment.
  • Remote Access. By purchasing software support and maintenance services, the subscriber agrees to permit AccuSoft to remotely access the subscriber's computer system for the sole purpose of diagnosing any reported problem with the product including, but not limited to, granting AccuSoft permission to install remote access software on subscriber's computer system(s) upon which the product has been installed. All standard confidentiality provisions identified in the Software License Agreement will apply. The subscriber shall provide remote access via dial-in or internet when required by AccuSoft to analyze a problem.

7. Service Limitations.

  • AccuSoft will support only the most current version of the Product. The current version is defined as the version of the product that is commercially available for sale by AccuSoft. Upon the release of such current version of a product, AccuSoft will continue to support and maintain the version of the product released immediately prior to the release of the current version in accordance with the then prevailing End-of-Life policy.
  • All associated computer hardware and operating system software and product must be maintained at the latest version deemed necessary by AccuSoft. AccuSoft shall not be obligated to provide support services under this policy if the service is regarding hardware, software or product that does not conform to the above statement. Any and each such service may result in additional charges for labor and materials as determined by AccuSoft, and shall be provided at the sole discretion of AccuSoft.
  • On-site services will be provided by quotation, are not covered by this policy, and shall be provided at the sole discretion of AccuSoft. Additional AccuSoft consulting and/or coding services may also be available to the subscriber under a separate agreement. AccuSoft may provide assistance to help optimize or enhance subscriber's use of the product. When AccuSoft determines that any such assistance has exceeded a reasonable level, AccuSoft will supply a quotation for additional Consulting Services.
See Also:
  • Preferred Level


Volume 2: API Reference

This part of ImageGear User's Manual provides detailed information about each function or control parameter of the ImageGear Components. This information includes function's calling sequence, arguments, use, possible return values, and supported bit depths as well as other useful information.

Currently there are the following components API reference:

  • ARTX Component API Function Reference
  • ART Component API Function Reference (LEGACY)
  • Core Component API Function Reference
  • FreqIP Component API Function Reference
  • GUI Component API Function Reference
  • ImageClean Component API Function Reference
  • ISIS Component API Function Reference
  • JPEG2000 Component API Function Reference
  • MD Component API Function Reference
  • PDF Component API Function Reference
  • Recognition Component API Function Reference
  • TWAIN Component API Function Reference
  • Vector Component API Function Reference


ARTX Component API Function Reference

NOTE: You can only attach one ART component. ARTX cannot be attached when ART is already attached.

ImageGear ARTX component provides access to IG ArtX API and contains objects used for creating, loading, saving and processing ART annotations and their groups. ImageGear ARTX component exposes the following objects:

HIG_ARTX_ACTION
ArtX class for processing ArtX GUI actions such as marks creation, selection, move and resize.
HIG_ARTX_ARROW
Legacy ART Arrow mark
HIG_ARTX_AUDIO
ART Audio mark.
HIG_ARTX_BUTTON
ART Button mark
HIG_ARTX_ELLIPSE
ART Ellipse mark.
HIG_ARTX_ENCRYPTION
ART Encryption mark
HIG_ARTX_FILLED_ELLIPSE
Legacy ART Filled Ellipse mark
HIG_ARTX_FILLED_POLYGON
Legacy ART Filled Polygon mark
HIG_ARTX_FILLEDRECTANGLE
Legacy ART Filled Rectangle mark
HIG_ARTX_FREELINE
Legacy ART Freehand line mark
HIG_ARTX_GROUP
Collection of ART marks united into a group.
HIG_ARTX_HIGHLIGHTER
Legacy ART Highlighter mark
HIG_ARTX_HOLLOW_ELLIPSE
Legacy ART Hollow Ellipse mark
HIG_ARTX_HOLLOW_POLYGON
Legacy ART Hollow Polygon mark
HIG_ARTX_HOLLOW_RECTANGLE
Legacy ART Hollow Rectangle mark
HIG_ARTX_HOTSPOT
ART Hot Spot mark.
HIG_ARTX_IMAGE
ART Image mark
HIG_ARTX_IMAGE_EMBEDDED
Legacy ART Embedded Image mark
HIG_ARTX_IMAGEREF
Legacy ART Image Reference mark
HIG_ARTX_LINE
ART Line mark.
HIG_ARTX_LINK
ArtX link objects associated with the HotSpot mark.
HIG_ARTX_MARK
Provides general properties and methods for all mark types.
HIG_ARTX_NOTE
Legacy ART Attach-A-Note mark
HIG_ARTX_PAGE
Collection of ART groups. This class provides methods and properties for accessing to individual marks on the page, as well as to the group of marks.
HIG_ARTX_PINUPTEXT
Legacy ART Pin-Up-Text mark
HIG_ARTX_POLYGON
ART Polygon mark.
HIG_ARTX_POLYLINE
ART Polyline mark.
HIG_ARTX_PROTRACTOR
ART Protractor mark.
HIG_ARTX_RECTANGLE
ART Rectangle mark.
HIG_ARTX_REDACTION
Legacy ART Redaction mark.
HIG_ARTX_RICHTEXT
ART Rich Text mark.
HIG_ARTX_RULER
ART Ruler mark.
HIG_ARTX_TEXT
ART Text mark.
HIG_ARTX_TEXTFROMFILE
Legacy ART "Text From File" mark
HIG_ARTX_TEXTSTAMP
Legacy ART "Text Stamp" mark
HIG_ARTX_TYPEDTEXT
Legacy ART "Typed Text" mark

Most of this API is represented in C ArtX sample program.

See Also:

ArtX GUI Reference

ArtX Structures Reference

ArtX Enumerations Reference


HIG_ARTX_ACTION

Type: Basic Object

Description:

ArtX class for processing ArtX GUI actions such as marks creation, selection, move and resize.

Class Members:

IG_ARTX_action_begin_creation
Creates GUI action object of type Mark Creation.
IG_ARTX_action_begin_edit
Creates GUI action object of type Mark Edit.
IG_ARTX_action_begin_move
Creates GUI action object of type Mark Move.
IG_ARTX_action_begin_resize
Creates GUI action object of type Mark Resize.
IG_ARTX_action_begin_selection
Creates GUI action object of type Selection.
IG_ARTX_action_draw
Performs drawing of GUI action.
IG_ARTX_action_end
Ends specified GUI action.
IG_ARTX_action_mouse_down
Passes mouse events to GUI action. It should be called when user presses mouse button.
IG_ARTX_action_mouse_move
Passes mouse events to GUI action. It should be called when user moves mouse pointer.
IG_ARTX_action_mouse_up
Passes mouse events to GUI action. It should be called when user releases mouse button.
IG_ARTX_action_type_get
Returns action's type.


IG_ARTX_action_begin_creation

Group: Action

Declaration:

AT_ERRCOUNT IG_ARTX_action_begin_creation(
    HIG_ARTX_PAGE hArtPage,
    LPAT_ARTX_DRAW_PARAMS pParams,
    LPAT_POINT lpStartPoint,
    HIG_ARTX_MARK hMarkSample,
    enumIGArtXMarkType nMarkType,
    enumIGArtXCoordType nCoordType,
    LPHIG_ARTX_ACTION lphAction
);

Arguments:

hArtPage
ArtX page handle.
pParams
Parameters required for action drawing.
lpStartPoint
Action starting point.
hMarkSample
Handle of annotation that will be used as template for the new mark to create. If NULL then newly created mark will be initialized with default values.
nMarkType
Type of annotation to create. If hMarkSample is not NULL then nMarkType value is ignored and mark of hMarkSample type will be created.
nCoordType
Coordinate type of mark to create. See enumIGArtXCoordType decription.
lphAction
Pointer to storage for the function result.

Description:

This function creates GUI action object of type Mark Creation. This action object helps to create new annotation and place it on the page.

Return Value:

Error count.


IG_ARTX_action_begin_edit

Group: Action

Declaration:

AT_ERRCOUNT IG_ARTX_action_begin_edit(
    HIG_ARTX_PAGE hArtPage,
    LPAT_ARTX_DRAW_PARAMS pDrawParams,
    HIG_ARTX_MARK hMark,
    LPAT_ARTX_EDIT_PARAMS pEditParams,
    LPHIG_ARTX_ACTION lphAction
);

Arguments:

hArtPage
ArtX page handle.
pDrawParams
Parameters required for action drawing.
hMark
Handle of annotation to edit.
pEditParams
Editing parameters returned by the method.
lphAction
Pointer to storage for function result.

Description:

This function creates GUI action object of type Mark Edit. This action object can be used to editing TEXT and RTF annotations.

Return Value:

Error count.


IG_ARTX_action_begin_move

Group: Action

Declaration:

AT_ERRCOUNT IG_ARTX_action_begin_move(
    HIG_ARTX_PAGE hArtPage,
    LPAT_ARTX_DRAW_PARAMS pParams,
    LPAT_POINT lpStartPoint,
    HIG_ARTX_MARK* phMark,
    AT_DWORD dwMarkCount,
    LPHIG_ARTX_ACTION lphAction
);

Arguments:

hArtPage
ArtX page handle.
pParams
Parameters required for action drawing.
lpStartPoint
Action starting point.
phMark
Pointer to list of annotation handles to move.
dwMarkCount
Number of elements in phMark
lphAction
Pointer to storage for function result.

Description:

This function creates GUI action object of type Mark Move. This action object helps to change position of specified annotation with mouse.

Return Value:

Error count.


IG_ARTX_action_begin_resize

Group: Action

Declaration:

AT_ERRCOUNT IG_ARTX_action_begin_resize(
    HIG_ARTX_PAGE hArtPage,
    LPAT_ARTX_DRAW_PARAMS pParams,
    LPAT_POINT lpStartPoint,
    HIG_ARTX_MARK hMark,
    LPHIG_ARTX_ACTION lphAction);

Arguments:

hArtPage
ArtX page handle.
pParams
Parameters required for action drawing.
lpStartPoint
Action starting point.
hMark
Handle of annotation that geometrical dimensions are to modify.
lphAction
Pointer to storage for function result.

Description:

This function creates GUI action object of type Mark Resize. This action object helps to change size of specified annotation with mouse.

Return Value:

Error count.


IG_ARTX_action_begin_selection

Group: Action

Declaration:

AT_ERRCOUNT IG_ARTX_action_begin_selection(
    HIG_ARTX_PAGE hArtPage,
    LPAT_ARTX_DRAW_PARAMS pParams,
    LPAT_POINT lpStartPoint,
    LPHIG_ARTX_ACTION lphAction);

Arguments:

hArtPage
ArtX page handle.
pParams
Parameters required for action drawing.
lpStartPoint
Action starting point.
lphAction
Pointer to storage for function result.

Description:

This function creates GUI action object of type Selection. This action object helps to select objects on the page with mouse.

Return Value:

Error count.


IG_ARTX_action_draw

Group: Action

Declaration:

AT_ERRCOUNT IG_ARTX_action_draw(
    HIG_ARTX_ACTION hAction,
    HWND hWnd);

Arguments:

hAction
Handle of GUI action.
hWnd
Windows handle to draw on.

Description:

This function performs drawing of GUI action.

Return Value:

Error count.


IG_ARTX_action_end

Group: Action

Declaration:

AT_ERRCOUNT IG_ARTX_action_end(
    HIG_ARTX_ACTION hAction,
    LPAT_VOID* lpResultData);

Arguments:

hAction
Handle of GUI action.
lpResultData
Pointer to buffer for action result data.
  • Select Action - returns NULL
  • Create Action - returns pointer to the created mark
  • Move Action - returns NULL
  • Resize Action - returns pointer to the resized mark

Description:

This function ends specified GUI action. It commits all data modification stored in action object (creates new annotation or change selection state) and destroys an action object.

Return Value:

Error count.


IG_ARTX_action_mouse_down

Group: Action

Declaration:

AT_ERRCOUNT IG_ARTX_action_mouse_down(
    HIG_ARTX_ACTION hAction,
    UINT nMessage,
    LPAT_POINT lpPoint,
    LPUINT lpnStatus);

Arguments:

hAction
Handle of GUI action.
nMessage
Mouse event parameters.
lpPoint
Screen position of mouse event.
lpnStatus
Pointer to storage for action state.

Description:

This function is to pass mouse events to GUI action. It should be called when user presses mouse button.

Return Value:

Error count.


IG_ARTX_action_mouse_move

Group: Action

Declaration:

AT_ERRCOUNT IG_ARTX_action_mouse_move(
    HIG_ARTX_ACTION hAction,
    UINT nMessage,
    LPAT_POINT lpPoint,
    LPUINT lpnStatus);

Arguments:

hAction
Handle of GUI action.
nMessage
Mouse event parameters.
lpPoint
Screen position of mouse event.
lpnStatus
Pointer to storage for action state.

Description:

This function is to pass mouse events to GUI action. It should be called when user moves mouse pointer.

Return Value:

Error count.


IG_ARTX_action_mouse_up

Group: Action

Declaration:

AT_ERRCOUNT IG_ARTX_action_mouse_up(
    HIG_ARTX_ACTION hAction,
    UINT nMessage,
    LPAT_POINT lpPoint,
    LPUINT lpnStatus);

Arguments:

hAction
Handle of GUI action.
nMessage
Mouse event parameters.
lpPoint
Screen position of mouse event.
lpnStatus
Pointer to storage for action state.

Description:

This function is to pass mouse events to GUI action. It should be called when user releases mouse button.

Return Value:

Error count.


IG_ARTX_action_type_get

Group: Action

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_action_type_get(
    HIG_ARTX_ACTION hAction,
    enumIGArtXGUIActionType* pType
    );

Arguments:

hAction
An action object.
pType
Returned type.

Description:

This function returns action's type.

Return Value:

Error count.


HIG_ARTX_ARROW

Type: Basic Object

Description:

ART Arrow mark.

Class Members:

IG_ARTX_arrow_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_arrow_create
Creates a new instance of Arrow annotation (IG_ARTX_MARK_ARROW).
IG_ARTX_arrow_endpoint_get
Queries arrow end point.
IG_ARTX_arrow_endpoint_set
Updates arrow end point position.
IG_ARTX_arrow_head_get
Queries attributes of annotation arrow head
IG_ARTX_arrow_head_set
Sets attributes of annotation arrow head.
IG_ARTX_arrow_highlight_get
Queries the highlight state of annotation.
IG_ARTX_arrow_highlight_set
Sets highlight state of annotation.
IG_ARTX_arrow_line_get
Queries attributes of line used to draw the annotation.
IG_ARTX_arrow_line_set
Sets attributes of line used to draw the annotation.
IG_ARTX_arrow_startpoint_get
Queries arrow start point.
IG_ARTX_arrow_startpoint_set
Updates arrow start point position.


IG_ARTX_arrow_bounds_get

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_bounds_get(
    HIG_ARTX_ARROW hMark,
    LPAT_RECTANGLE lpRect
    );

Arguments:

hMark
Annotation handle
lpRect
Pointer to storage for bounding rectangle

Description:

This function queries the bounding rectangle of annotation. This is read-only property and calculated as biggest rectange that covers all points of annotation.

Return Value:

Error count.


IG_ARTX_arrow_create

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_create(
    LPAT_POINT lpStartPoint,
    LPAT_POINT lpEndPoint,
    LPAT_ARTX_BORDER pLine,
    LPAT_ARTX_ARROW_HEAD lpHead,
    AT_BOOL bHighlight,
    LPHIG_ARTX_ARROW lphMark);

Arguments:

lpStartPoint
Coordinates of start arrow point
lpEndPoint
Coordinates of end arrow point
pLine
Attributes of line used to draw arrow
lpHead
Attributes of arrow head
bHighlight
Indicates whether the annotation is highlighted
lphMark
Pointer to storage for new annotation handle

Description:

This function creates a new instance of Arrow annotation (IG_ARTX_MARK_ARROW).

Return Value:

Error count.


IG_ARTX_arrow_endpoint_get

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_endpoint_get(
    HIG_ARTX_ARROW hMark,
    LPAT_POINT lpPoint
    );

Arguments:

hMark
Annotation handle
lpPoint
Pointer to storage for function result

Description:

This function queries arrow end point.

Return Value:

Error count.


IG_ARTX_arrow_endpoint_set

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_endpoint_set(
    HIG_ARTX_ARROW hMark,
    LPAT_POINT lpPoint
    );

Arguments:

hMark
Annotation handle
lpPoint
Pointer to new value of arrow end point

Description:

This function updates arrow end point position.

Return Value:

Error count.


IG_ARTX_arrow_head_get

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_head_get(
    HIG_ARTX_ARROW hMark,
    LPAT_ARTX_ARROW_HEAD lpHead,
    LPAT_UINT pnDataSize
    );

Arguments:

hMark
Annotation handle
lpHead
Pointer to storage for the arrow head atributes
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpHead parameter. On output it contains number of bytes copied to lpHead buffer.
If arrow annotation has an arrow head then its attributes are copied into output buffer lpHead and number of bytes copied is placed into pnDataSize.
If lpHead is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_ARTX_ARROW_HEAD structure.
If lpHead is not NULL and pnDataSize is not NULL and there is no arrow head then on output pnDataSize contains zero.

Description:

This function queries attributes of annotation arrow head. See AT_ARTX_ARROW_HEAD structure for additional info.

Return Value:

Error count.


IG_ARTX_arrow_head_set

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_head_set(
    HIG_ARTX_ARROW hMark,
    LPAT_ARTX_ARROW_HEAD lpHead
    );

Arguments:

hMark
Annotation handle
lpHead
Pointer to arrow head attributes structure. NULL value removes arrow head from hMark annotaiton

Description:

This function sets attributes of annotation arrow head. See AT_ARTX_ARROW_HEAD structure for additional info.

Return Value:

Error count.


IG_ARTX_arrow_highlight_get

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_highlight_get(
    HIG_ARTX_ARROW hMark,
    LPAT_BOOL lpbHighlight
    );

Arguments:

hMark
Arrow annotation handle
lpbHighlight
Pointer to storage annotation highlight state

Description:

This function queries the highlight state of annotation. This is boolean property of legacy annotation types. When set to TRUE annotaion is transparent (equal to set transparency to 128). When FALSE annotation is opaque.

Return Value:

Error count.


IG_ARTX_arrow_highlight_set

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_highlight_set(
    HIG_ARTX_ARROW hMark,
    AT_BOOL bHighlight
    );

Arguments:

hMark
Arrow annotation handle
bHighlight
Pointer to storage annotation highlight state

Description:

This function set highlight state of annotation. This is boolean property of legacy annotation types and means that annotaion is transparent.

Return Value:

Error count.


IG_ARTX_arrow_line_get

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_line_get(
    HIG_ARTX_ARROW hMark,
    LPAT_ARTX_BORDER lpLine
    );

Arguments:

hMark
Annotation handle
lpLine
Pointer to storage for line atributes

Description:

This function queries attributes of line used to draw the annotation. See AT_ARTX_BORDER structure for additional info.

Return Value:

Error count.


IG_ARTX_arrow_line_set

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_line_set(
    HIG_ARTX_ARROW hMark,
    LPAT_ARTX_BORDER lpData
    );

Arguments:

hMark
Annotation handle
lpData
Pointer to line attributes structure

Description:

This function sets attributes of line used to draw the annotation.

Return Value:

Error count.


IG_ARTX_arrow_startpoint_get

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_startpoint_get(
    HIG_ARTX_ARROW hMark,
    LPAT_POINT lpPoint
    );

Arguments:

hMark
Annotation handle
lpPoint
Pointer to storage for function result

Description:

This function queries arrow start point.

Return Value:

Error count.


IG_ARTX_arrow_startpoint_set

Group: Arrow

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_arrow_startpoint_set(
    HIG_ARTX_ARROW hMark,
    LPAT_POINT lpPoint
    );

Arguments:

hMark
Annotation handle
lpPoint
Pointer to new value of arrow start point

Description:

This function updates arrow start point position.

Return Value:

Error count.


HIG_ARTX_AUDIO

Type: Basic Object

Description:

ART Audio mark.

Class Members:

IG_ARTX_audio_bounds_get
Queries the bounding rectangle.
IG_ARTX_audio_bounds_set
Updates the bounding rectangle.
IG_ARTX_audio_create
Creates an instance of the mark.
IG_ARTX_audio_filename_get
Queries the file name of the annotation.
IG_ARTX_audio_filename_set
Updates the file name of the annotation.
IG_ARTX_audio_play
Plays audio sound.


IG_ARTX_audio_bounds_get

Group: Audio

Declaration:

AT_ERRCOUNT IG_ARTX_audio_bounds_get(
    HIG_ARTX_AUDIO hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Audion mark handle.
lpRect
Pointer to storage for function result.

Description:

This function queries the bounding rectangle.

Return Value:

Error count.


IG_ARTX_audio_bounds_set

Group: Audio

Declaration:

AT_ERRCOUNT IG_ARTX_audio_bounds_set(
    HIG_ARTX_AUDIO hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
New bounding rectangle to set.

Description:

This function sets the new bounding rectangle.

Return Value:

Error count.


IG_ARTX_audio_create

Group: Audio

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_audio_create(
    LPAT_RECTANGLE pRectangle,
    LPSTR lpszFileName,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

pRectangle
Bounding rectangle.
lpszFileName
Path to the audio file.
lphMark
Created mark audio object.

Description:

This function creates an instance of the Audio mark.

Return Value:

Error count.


IG_ARTX_audio_filename_get

Group: Audio

Declaration:

AT_ERRCOUNT IG_ARTX_audio_filename_get(
    HIG_ARTX_AUDIO hMark,
    LPSTR lpszFileName,
    AT_UINT nLen
);

Arguments:

hMark
Annotation handle.
lpszFileName
Pointer to storage the function results.
nLen
The buffer length.

Description:

This function queries the file name of the annotation.

Return Value:

Error count.


IG_ARTX_audio_filename_set

Group: Audio

Declaration:

AT_ERRCOUNT IG_ARTX_audio_filename_set(
    HIG_ARTX_AUDIO hMark,
    LPSTR lpszFileName
);

Arguments:

hMark
Annotation handle.
lpszFileName
Zero terminated string with file name.

Description:

This function updates the file name of the annotation.

Return Value:

Error count.


IG_ARTX_audio_play

Group: Audio

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_audio_play(
    HIG_ARTX_AUDIO hMark,
    AT_BOOL bPlay
);

Arguments:

hMark
Annotation handle.
bPlay
TRUE - starts playing, FALSE - stops playing.

Description:

This function plays audio sound.

Return Value:

Error count.


HIG_ARTX_BUTTON

Type: Object

Description:

ART Button mark.

Class Members:

IG_ARTX_button_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_button_bounds_set
Updates the bounding rectangle of annotation.
IG_ARTX_button_create
Creates a new instance of Button annotation (IG_ARTX_MARK_BUTTON).
IG_ARTX_button_fillcolor_get
Queries button fill color.
IG_ARTX_button_fillcolor_set
Updates button fill color with new value.
IG_ARTX_button_font_get
Queries button text font.
IG_ARTX_button_font_set
Updates button text font.
IG_ARTX_button_logfont_get
Queries button text font.
IG_ARTX_button_logfont_set
Updates button text font.
IG_ARTX_button_opacity_get
Queries the opacity value of annotation.
IG_ARTX_button_opacity_set
Sets the opacity value of annotation.
IG_ARTX_button_orientation_get
Queries value of button text orientation.
IG_ARTX_button_orientation_set
Queries value of button text orientation.
IG_ARTX_button_state_get
Sets the state of button. Button has 2 states pressed and not pressed.
IG_ARTX_button_state_set
Sets the state of button.
IG_ARTX_button_text_get
Queries button text string.
IG_ARTX_button_text_set
Updates button text string.
IG_ARTX_button_textcolor_get
Queries button text color.
IG_ARTX_button_textcolor_set
Updates button text color with new value.


IG_ARTX_button_bounds_get

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_bounds_get(
    HIG_ARTX_BUTTON hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_button_bounds_set

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_bounds_set(
    HIG_ARTX_BUTTON hMark,
    LPAT_RECTANGLE lpRect
    );

Arguments:

hMark
Annotation handle.
lpRect
Pointer to new bounding rectangle.

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_button_create

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_create(
    LPAT_RECTANGLE pRectangle,
    LPSTR lpszText,
    LPAT_ARTX_FONT lpFont,
    LPAT_RGBQUAD pFillColor,
    LPAT_RGBQUAD pTextColor,
    AT_INT nOpacity,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
lpszText
Text string drawn on button.
lpFont
Attributes of font to be used for text drawing.
pFillColor
Button fill color.
pTextColor
Text color.
nOpacity
Annotation opacity value.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates a new instance of Button annotation (IG_ARTX_MARK_BUTTON).

Return Value:

Error count.


IG_ARTX_button_fillcolor_get

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_fillcolor_get(
    HIG_ARTX_BUTTON hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for the fill color value.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.
If fill color is specified for the button then it is copied into output buffer lpColor and number of bytes copied is placed into pnDataSize.
If lpColor is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_RGBQUAD structure.
If lpColor is not NULL and pnDataSize is not NULL and there is no fill color in the button then on output pnDataSize contains zero.

Description:

This function queries button fill color.

Return Value:

Error count.


IG_ARTX_button_fillcolor_set

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_fillcolor_set(
    HIG_ARTX_BUTTON hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to new fill color value. If lpColor is NULL then button internal area will not be filled.

Description:

This function updates button fill color with new value.

Return Value:

Error count.


IG_ARTX_button_font_get

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_font_get(
    HIG_ARTX_BUTTON hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to storage for the text font value.

Description:

This function queries button text font.

Return Value:

Error count.


IG_ARTX_button_font_set

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_font_set(
    HIG_ARTX_BUTTON hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to structure with new font atributes.

Description:

This function updates button text font.

Return Value:

Error count.


IG_ARTX_button_logfont_get

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_logfont_get(
    HIG_ARTX_BUTTON hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to storage for the text font value.

Description:

This function queries button text font.

Return Value:

Error count.


IG_ARTX_button_logfont_set

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_logfont_set(
    HIG_ARTX_BUTTON hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to structure with new font atributes.

Description:

This function updates button text font.

Return Value:

Error count.


IG_ARTX_button_opacity_get

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_opacity_get(
    HIG_ARTX_BUTTON hMark,
    LPAT_INT lpnOpacity
);

Arguments:

hMark
Annotation handle.
lpnOpacity
Pointer to storage for function result.

Description:

This function queries the opacity value of annotation.

Return Value:

Error count.


IG_ARTX_button_opacity_set

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_opacity_set(
    HIG_ARTX_BUTTON hMark,
    AT_INT nOpacity
);

Arguments:

hMark
Annotation handle.
nOpacity
New opacity value to set.

Description:

This function sets the opacity value of annotation.

Return Value:

Error count.


IG_ARTX_button_orientation_get

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_orientation_get(
    HIG_ARTX_BUTTON hMark,
    enumOrientModes* lpnOrientation
);

Arguments:

hMark
Annotation handle.
lpnOrientation
Pointer to buffer for function result.

Description:

This function queries value of button text orientation. See enumOrientModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_button_orientation_set

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_orientation_set(
    HIG_ARTX_BUTTON hMark,
    enumOrientModes nOrientation
);

Arguments:

hMark
Annotation handle.
nOrientation
New button text orientation value.

Description:

This function updates value of button text orientation.

Return Value:

Error count.


IG_ARTX_button_state_get

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_state_get(
    HIG_ARTX_BUTTON hMark,
    LPAT_BOOL lpbState
);

Arguments:

hMark
annotation handle.
lpbState
pointer to buffer for function result.

Description:

This function gets the state of button. Button has 2 states pressed and not pressed. TRUE value indicates pressed state and FALSE not pressed.

Return Value:

Error count.


IG_ARTX_button_state_set

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_state_set(
    HIG_ARTX_BUTTON hMark,
    AT_BOOL bState
);

Arguments:

hMark
annotation handle.
bState
new button state to set

Description:

This function sets the state of button. See IG_ARTX_button_state_get () function for more info.

Return Value:

Error count.


IG_ARTX_button_text_get

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_text_get(
    HIG_ARTX_BUTTON hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer for output string.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If text attribute is not empty in the button then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store annotation text.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no text in the button then on output pnDataSize contains zero.

Description:

This function queries button text string.

Return Value:

Error count.


IG_ARTX_button_text_set

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_text_set(
    HIG_ARTX_BUTTON hMark,
    LPSTR lpszTextBuffer
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer with new button text. If lpszTextBuffer is NULL then button text attribute will be empty.

Description:

This function updates button text string.

Return Value:

Error count.


IG_ARTX_button_textcolor_get

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_textcolor_get(
    HIG_ARTX_BUTTON hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for the text color value.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.
If text color is specified for the button then it is copied into output buffer lpColor and number of bytes copied is placed into pnDataSize.
If lpColor is NULL and pnDataSize is not NULL then on output pnDataSize contains the size of AT_RGBQUAD structure.
If lpColor is not NULL and pnDataSize is not NULL and there is no text color in the button then on output pnDataSize contains zero.

Description:

This function queries button text color.

Return Value:

Error count.


IG_ARTX_button_textcolor_set

Group: Button

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_button_textcolor_set(
    HIG_ARTX_BUTTON hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to new text color value. If lpColor is NULL then no text will be drawn on button

Description:

This function updates button text color with new value.

Return Value:

Error count.


HIG_ARTX_ELLIPSE

Type: Object

Description:

ART Ellipse mark.

Class Members:

IG_ARTX_ellipse_border_get
Queries ellipse annotation border.
IG_ARTX_ellipse_border_set
Updates ellipse annotation border.
IG_ARTX_ellipse_create
Creates an instance of ellipse mark
IG_ARTX_ellipse_bounds_get
Queries ellipse bounding rectangle.
IG_ARTX_ellipse_bounds_set
Updates ellipse bounding rectangle.
IG_ARTX_ellipse_fillcolor_get
Queries filling color of ellipse annotation.
IG_ARTX_ellipse_fillcolor_set
Updates ellipse annotation filling color.
IG_ARTX_ellipse_opacity_get
Queries value of ellipse annotation opacity.
IG_ARTX_ellipse_opacity_set
Updates value of ellipse annotation opacity attribute.


IG_ARTX_ellipse_border_get

Group: Ellipse

Declaration:

AT_ERRCOUNT IG_ARTX_ellipse_border_get(
    HIG_ARTX_ELLIPSE hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Ellipse annotation handle.
lpBorder
Pointer to storage for function result.

Description:

This function queries ellipse annotation border.

Return Value:

Error count.


IG_ARTX_ellipse_border_set

Group: Ellipse

Declaration:

AT_ERRCOUNT IG_ARTX_ellipse_border_set(
    HIG_ARTX_ELLIPSE hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Ellipse annotation handle
lpBorder
New border to set

Description:

This function updates ellipse annotation border.

Return Value:

Error count.


IG_ARTX_ellipse_create

Group: Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ellipse_create(
    LPAT_RECTANGLE pRectangle,
    LPAT_RGBQUAD pFillColor,
    LPAT_ARTX_BORDER pBorder,
    AT_INT Opacity,
    LPHIG_ARTX_ELLIPSE lphMark
);

Arguments:

pRectangle
bounding rectangle
pFillColor
fill color
pBorder
border
Opacity
opacity
lphMark
created object

Description:

This function creates an instance of ellipse mark (IG_ARTX_MARK_ELLIPSE).

Return Value:

Error count.


IG_ARTX_ellipse_bounds_get

Group: Ellipse

Declaration:

AT_ERRCOUNT IG_ARTX_ellipse_bounds_get(
    HIG_ARTX_ELLIPSE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Ellipse annotation handle.
lpRect
Pointer to storage for function result.

Description:

This function queries ellipse bounding rectangle.

Return Value:

Error count.


IG_ARTX_ellipse_bounds_set

Group: Ellipse

Declaration:

AT_ERRCOUNT IG_ARTX_ellipse_bounds_set(
    HIG_ARTX_ELLIPSE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Ellipse annotation handle.
lpRect
New bounding rectangle to set.

Description:

This function updates ellipse bounding rectangle.

Return Value:

Error count.


IG_ARTX_ellipse_fillcolor_get

Group: Ellipse

Declaration:

AT_ERRCOUNT IG_ARTX_ellipse_fillcolor_get(
    HIG_ARTX_ELLIPSE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Ellipse annotation handle.
lpColor
Pointer to storage for function result

Description:

This function queries filling color of ellipse annotation.

Return Value:

Error count.


IG_ARTX_ellipse_fillcolor_set

Group: Ellipse

Declaration:

AT_ERRCOUNT IG_ARTX_ellipse_fillcolor_set(
    HIG_ARTX_ELLIPSE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Ellipse annotation handle.
lpColor
New color value border to set

Description:

This function updates ellipse annotation filling color.

Return Value:

Error count.


IG_ARTX_ellipse_opacity_get

Group: Ellipse

Declaration:

AT_ERRCOUNT IG_ARTX_ellipse_opacity_get(
    HIG_ARTX_ELLIPSE hMark,
    LPAT_INT lpnOpacity
);

Arguments:

hMark
Ellipse annotation handle.
lpnOpacity
Pointer to storage for function result.

Description:

This function queries value of ellipse annotation opacity.

Return Value:

Error count.


IG_ARTX_ellipse_opacity_set

Group: Ellipse

Declaration:

AT_ERRCOUNT IG_ARTX_ellipse_opacity_set(
    HIG_ARTX_ELLIPSE hMark,
    AT_INT nOpacity
);

Arguments:

hMark
Ellipse annotation handle
nOpacity
New opacity value to set

Description:

This function updates value of ellipse annotation opacity attribute.

Return Value:

Error count.


HIG_ARTX_ENCRYPTION

Type: Object

Description:

This class provides methods and properties for ART Encryption mark.

Class Members:

IG_ARTX_encryption_applied_get
Checks whether the encryption mark is applied or not to the image page.
IG_ARTX_encryption_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_encryption_bounds_set
Updates the bounding rectangle of annotation.
IG_ARTX_encryption_create
Creates a new instance of encryption annotation (IG_ARTX_MARK_ENCRYPTION).
IG_ARTX_encryption_decrypt
Decrypts the area previously encrypted with IG_ARTX_encryption_encrypt.
IG_ARTX_encryption_encrypt
Encrypts the area of hIGear covered by the encryption mark.
IG_ARTX_encryption_password_get
Queries password string.
IG_ARTX_encryption_password_set
Updates annotation password.


IG_ARTX_encryption_applied_get

Group: Encription

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_encryption_applied_get(
    HIG_ARTX_ENCRYPTION hMark,
    AT_BOOL lpbApplied
);

Arguments:

hMark
Annotation handle.
lpbApplied
Return value. True - applied to the image page, False - otherwise.

Description:

This function checks whether the encryption mark is applied or not to the image page.

Return Value:

Error count.


IG_ARTX_encryption_bounds_get

Group: Encription

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_encryption_bounds_get(
    HIG_ARTX_ENCRYPTION hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_encryption_bounds_set

Group: Encription

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_encryption_bounds_set(
    HIG_ARTX_ENCRYPTION hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to new bounding rectangle.

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_encryption_create

Group: Encription

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_encryption_create(
    LPAT_RECTANGLE	pRectangle,
    LPSTR				lpszPassword,
    enumEncryptModes	nMethod,
    LPHIG_ARTX_ENCRYPTION lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
lpszPassword
Password string.
nMethod
Specifies encryption algorytm to be used.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates a new instance of encryption annotation (IG_ARTX_MARK_ENCRYPTION).

Return Value:

Error count.


IG_ARTX_encryption_decrypt

Group: Encription

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_encryption_decrypt(
    HIG_ARTX_ENCRYPTION hMark
);

Arguments:

hMark
Annotation handle.

Description:

This function decrypts the area previously encrypted with IG_ARTX_encryption_encrypt ().

Sets applied property to FALSE, if decryption was successful.

Return Value:

Error count.


IG_ARTX_encryption_encrypt

Group: Encription

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_encryption_encrypt(
    HIG_ARTX_ENCRYPTION hMark,
    HIGEAR hIGear
);

Arguments:

hMark
Annotation handle.
hIGear
Image page to encrypt.

Description:

This function encrypts the area of hIGear covered by the encryption mark. If the area (or portion of that area) is covered by another encryption mark, then does nothing.

Sets applied property to true if encryption was successful.

Return Value:

Error count.


IG_ARTX_encryption_password_get

Group: Encription

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_encryption_password_get(
    HIG_ARTX_ENCRYPTION hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer for output string.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If password attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store annotation password.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no password in the annotation then on output pnDataSize contains zero.

Description:

This function queries password string.

Return Value:

Error count.


IG_ARTX_encryption_password_set

Group: Encription

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_encryption_password_set(
    HIG_ARTX_ENCRYPTION hMark,
    LPSTR lpszTextBuffer
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer with new password. If lpszTextBuffer is NULL then annotation password will be empty.

Description:

This function updates annotation password. If there is an image associated with annotation it will be decrypted using old password and encrypted with new one.

Return Value:

Error count.


HIG_ARTX_FILLED_ELLIPSE

Type: Object

Description:

This class provides methods and properties for Legacy ART Filled Ellipse mark.

Class Members:

IG_ARTX_filled_ellipse_bounds_get
Queries ellipse bounding rectangle.
IG_ARTX_filled_ellipse_bounds_set
Updates ellipse bounding rectangle.
IG_ARTX_filled_ellipse_create
Creates an instance of ellipse mark (IG_ARTX_MARK_FILLED_ELLIPSE)
IG_ARTX_filled_ellipse_fillcolor_get
Queries filling color of ellipse annotation.
IG_ARTX_filled_ellipse_fillcolor_set
Updates ellipse annotation filling color.
IG_ARTX_filled_ellipse_highlight_get
Queries the highlight state of annotation.
IG_ARTX_filled_ellipse_highlight_set
Sets highlight state of annotation.


IG_ARTX_filled_ellipse_bounds_get

Group: Filled Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_ellipse_bounds_get(
    HIG_ARTX_FILLED_ELLIPSE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for function result.

Description:

This function queries ellipse bounding rectangle.

Return Value:

Error count.


IG_ARTX_filled_ellipse_bounds_set

Group: Filled Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_ellipse_bounds_set(
    HIG_ARTX_FILLED_ELLIPSE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
New bounding rectangle to set.

Description:

This function updates ellipse bounding rectangle.

Return Value:

Error count.


IG_ARTX_filled_ellipse_create

Group: Filled Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_ellipse_create(
    LPAT_RECTANGLE pRectangle,
    LPAT_RGBQUAD pFillColor,
    AT_BOOL bHighlight,
    LPHIG_ARTX_ELLIPSE lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
pFillColor
Annotation fill color.
bHighlight
Indicates whether the annotation is highlighted.
lphMark
Pointer to storage for new annotation handle.

Description:

This function Creates an instance of ellipse mark (IG_ARTX_MARK_FILLED_ELLIPSE).

Return Value:

Error count.


IG_ARTX_filled_ellipse_fillcolor_get

Group: Filled Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_ellipse_fillcolor_get(
    HIG_ARTX_FILLED_ELLIPSE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for the fill color value.

Description:

This function queries filling color of ellipse annotation.

Return Value:

Error count.


IG_ARTX_filled_ellipse_fillcolor_set

Group: Filled Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_ellipse_fillcolor_set(
    HIG_ARTX_ELLIPSE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
New color value to set. If lpColor is NULL black color (0,0,0) is assumed.

Description:

This function updates ellipse annotation filling color.

Return Value:

Error count.


IG_ARTX_filled_ellipse_highlight_get

Group: Filled Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_ellipse_highlight_get(
    HIG_ARTX_ELLIPSE hMark,
    LPAT_BOOL lpbHighlight
);

Arguments:

hMark
Annotation handle.
lpbHighlight
Pointer to storage annotation highlight state.

Description:

This function queries the highlight state of annotation. This is boolean property of legacy annotation types. When set to TRUE annotaion is transparent (equal to set transparency to 128). When FALSE annotation is opaque.

Return Value:

Error count.


IG_ARTX_filled_ellipse_highlight_set

Group: Filled Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_ellipse_highlight_set(
    HIG_ARTX_FILLED_ELLIPSE hMark,
    AT_BOOL	bHighlight
);

Arguments:

hMark
Annotation handle.
bHighlight
Pointer to storage annotation highlight state.

Description:

This function set highlight state of annotation. This is boolean property of legacy annotation types and means that annotaion is transparent.

Return Value:

Error count.


HIG_ARTX_FILLED_POLYGON

Type: Object

Description:

This class provides methods and properties for Legacy ART Filled Polygon mark.

Class Members:

IG_ARTX_filled_polygon_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_filled_polygon_create
Creates an instance of filled polygon mark (IG_ARTX_MARK_FILLED_POLYGON)
IG_ARTX_filled_polygon_fillcolor_get
Queries filling color of annotation.
IG_ARTX_filled_polygon_fillcolor_set
Updates annotation filling color.
IG_ARTX_filled_polygon_highlight_get
Queries the highlight state of annotation.
IG_ARTX_filled_polygon_highlight_set
Sets highlight state of annotation.
IG_ARTX_filled_polygon_points_get
Queries annotation points data.
IG_ARTX_filled_polygon_point_count_get
Obtains the number of polygon points.
IG_ARTX_filled_polygon_points_set
Updates annotation points data.


IG_ARTX_filled_polygon_bounds_get

Group: Filled Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_polygon_bounds_get(
    HIG_ARTX_FILLED_POLYGON hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation. This is read-only property and calculated as biggest rectange that covers all points of annotation.

Return Value:

Error count.


IG_ARTX_filled_polygon_create

Group: Filled Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_polygon_create(
    LPAT_POINT lpPoints,
    AT_DWORD nCount,
    LPAT_RGBQUAD pFillColor,
    AT_BOOL bHighlight,
    LPHIG_ARTX_FILLED_POLYGON lphMark
);

Arguments:

lpPoints
Array of polygon points.
nCount
Number of elements in lpPoints array.
pFillColor
Annotation fill color.
bHighlight
Indicates whether the annotation is highlighted.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates an instance of filled polygon mark (IG_ARTX_MARK_FILLED_POLYGON).

Return Value:

Error count.


IG_ARTX_filled_polygon_fillcolor_get

Group: Filled Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_polygon_fillcolor_get(
    HIG_ARTX_FILLED_POLYGON hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for the fill color value.

Description:

This function queries filling color of annotation.

Return Value:

Error count.


IG_ARTX_filled_polygon_fillcolor_set

Group: Filled Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_polygon_fillcolor_set(
    HIG_ARTX_FILLED_POLYGON hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
New color value to set. If lpColor is NULL then black color (0,0,0) is assumed.

Description:

This function updates annotation filling color.

Return Value:

Error count.


IG_ARTX_filled_polygon_highlight_get

Group: Filled Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_polygon_highlight_get(
    HIG_ARTX_FILLED_POLYGON hMark,
    LPAT_BOOL lpbHighlight
);

Arguments:

hMark
Annotation handle.
lpbHighlight
Pointer to storage for annotation highlight state.

Description:

This function queries the highlight state of annotation. This is boolean property of legacy annotation types. When set to TRUE annotaion is transparent (equal to set transparency to 128). When FALSE annotation is opaque.

Return Value:

Error count.


IG_ARTX_filled_polygon_highlight_set

Group: Filled Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_polygon_highlight_set(
    HIG_ARTX_FILLED_POLYGON hMark,
    AT_BOOL	bHighlight
);

Arguments:

hMark
Annotation handle.
bHighlight
Specifies new value of annotation highlight state.

Description:

This function sets highlight state of annotation.

Return Value:

Error count.


IG_ARTX_filled_polygon_points_get

Group: Filled Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_polygon_points_get(
    HIG_ARTX_FILLED_POLYGON hMark,
    LPAT_POINT lpPoints,
    AT_DWORD nStart,
    AT_DWORD nCount
);

Arguments:

hMark
Specifies annotation handle.
lpPoints
Specifies pointer to storage for points.
nStart
Specifies index of first point to get.
nCount
Specifies number of points to get.

Description:

This function queries annotation points data.

Return Value:

Error count.


IG_ARTX_filled_polygon_point_count_get

Group: Filled Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_polygon_point_count_get(
    HIG_ARTX_FILLED_POLYGON hMark,
    LPAT_INT lpnCount
);

Arguments:

hMark
Annotation handle.
lpnCount
Pointer to buffer for point count.

Description:

This function obtains the number of polygon points.

Return Value:

Error count.


IG_ARTX_filled_polygon_points_set

Group: Filled Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_polygon_points_set(
    HIG_ARTX_FILLED_POLYGON hMark,
    LPAT_POINT lpPoints,
    AT_DWORD nStart,
    AT_DWORD nCount
);

Arguments:

hMark
Specifies annotation handle.
lpPoints
Specifies buffer with new annotation points.
nStart
Specifies index of first point to set.
nCount
Specifies number of points to set.

Description:

This function updates annotation points data.

Return Value:

Error count.


HIG_ARTX_FILLEDRECTANGLE

Type: Object

Description:

This class provides methods and properties for Legacy ART Filled Rectangle mark.

Class Members:

IG_ARTX_filled_rectangle_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_filled_rectangle_bounds_set
Updates the bounding rectangle of annotation.
IG_ARTX_filled_rectangle_create
Creates an instance of filled rectangle mark (IG_ARTX_MARK_FILLED_RECTANGLE).
IG_ARTX_filled_rectangle_fillcolor_get
Queries filling color of annotation.
IG_ARTX_filled_rectangle_fillcolor_set
Updates annotation filling color.
IG_ARTX_filled_rectangle_highlight_get
Queries the highlight state of annotation.
IG_ARTX_filled_rectangle_highlight_set
Sets highlight state of annotation.


IG_ARTX_filled_rectangle_bounds_get

Group: Filled Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_rectangle_bounds_get(
    HIG_ARTX_FILLED_RECTANGLE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_filled_rectangle_bounds_set

Group: Filled Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_rectangle_bounds_set(
    HIG_ARTX_FILLED_RECTANGLE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to new bounding rectangle.

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_filled_rectangle_create

Group: Filled Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_rectangle_create(
    LPAT_RECTANGLE pRectangle,
    LPAT_RGBQUAD pFillColor,
    AT_BOOL bHighlight,
    LPHIG_ARTX_FILLED_RECTANGLE lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
pFillColor
Annotation fill color.
bHighlight
Indicates whether the annotation is highlighted.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates an instance of filled rectangle mark (IG_ARTX_MARK_FILLED_RECTANGLE).

Return Value:

Error count.


IG_ARTX_filled_rectangle_fillcolor_get

Group: Filled Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_rectangle_fillcolor_get(
    HIG_ARTX_FILLED_RECTANGLE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for the annotation fill color.

Description:

This function queries filling color of annotation.

Return Value:

Error count.


IG_ARTX_filled_rectangle_fillcolor_set

Group: Filled Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_rectangle_fillcolor_set(
    HIG_ARTX_FILLED_RECTANGLE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
New color value to set. If lpColor is NULL then black color (0,0,0) is assumed.

Description:

This function updates annotation filling color.

Return Value:

Error count.


IG_ARTX_filled_rectangle_highlight_get

Group: Filled Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_rectangle_highlight_get(
    HIG_ARTX_FILLED_RECTANGLE hMark,
    LPAT_BOOL lpbHighlight
);

Arguments:

hMark
Annotation handle.
lpbHighlight
Pointer to storage for annotation highlight state.

Description:

This function queries the highlight state of annotation. This is boolean property of legacy annotation types. When set to TRUE annotaion is transparent (equal to set transparency to 128). When FALSE annotation is opaque.

Return Value:

Error count.


IG_ARTX_filled_rectangle_highlight_set

Group: Filled Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_filled_rectangle_highlight_set(
    HIG_ARTX_FILLED_RECTANGLE hMark,
    AT_BOOL bHighlight
);

Arguments:

hMark
Annotation handle.
bHighlight
Specifies new value of annotation highlight state.

Description:

This function sets highlight state of annotation.

Return Value:

Error count.


HIG_ARTX_FREELINE

Type: Object

Description:

This class provides methods and properties for Legacy ART Freehand line mark.

Class Members:

IG_ARTX_freeline_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_freeline_closed_get
Queries the close state of annotation.
IG_ARTX_freeline_closed_set
Updates the close state of annotation.
IG_ARTX_freeline_create
Creates an instance of free line mark (IG_ARTX_MARK_FREEHAND_LINE).
IG_ARTX_freeline_highlight_get
Queries the highlight state of annotation.
IG_ARTX_freeline_highlight_set
Sets highlight state of annotation.
IG_ARTX_freeline_line_get
Queries attributes of line used to draw the annotation.
IG_ARTX_freeline_line_set
Sets attributes of line used to draw the annotation.
IG_ARTX_freeline_point_count_get
Obtains the number of freeline points.
IG_ARTX_freeline_points_get
Queries annotation points data.
IG_ARTX_freeline_points_set
Updates annotation points data.


IG_ARTX_freeline_bounds_get

Group: Freehand Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_freeline_bounds_get(
    HIG_ARTX_FREELINE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation. This is read-only property and calculated as biggest rectange that covers all points of annotation.

Return Value:

Error count.


IG_ARTX_freeline_closed_get

Group: Freehand Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_freeline_closed_get(
    HIG_ARTX_FREELINE hMark,
    LPAT_BOOL lpbIsClosed
);

Arguments:

hMark
Annotation handle.
lpbIsClosed
Pointer to storage for annotation close state.

Description:

This function queries the close state of annotation. When set to TRUE freeline considered as closed i.e. the edge from start point to end point is drawn.

Return Value:

Error count.


IG_ARTX_freeline_closed_set

Group: Freehand Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_freeline_closed_set(
    HIG_ARTX_FREELINE hMark,
    AT_BOOL bIsClosed
);

Arguments:

hMark
Annotation handle.
bIsClosed
Specifies new value of annotation close state.

Description:

This function updates the close state of the annotation.

Return Value:

Error count.


IG_ARTX_freeline_create

Group: Freehand Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_freeline_create(
    LPAT_POINT lpPoints,
    AT_DWORD nPointCount,
    LPAT_ARTX_BORDER pLine,
    AT_BOOL bClosed,
    AT_BOOL bHighlight,
    LPHIG_ARTX_FREELINE lphMark
);

Arguments:

lpPoints
Array of annotation points.
nPointCount
Number of elements in lpPoints array.
pLine
Attributes of line used to draw annotation.
bClosed
Indicates whether the freeline is closed.
bHighlight
Indicates whether the annotation is highlighted.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates an instance of free line mark (IG_ARTX_MARK_FREEHAND_LINE).

Return Value:

Error count.


IG_ARTX_freeline_highlight_get

Group: Freehand Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_freeline_highlight_get(
    HIG_ARTX_FREELINE hMark,
    LPAT_BOOL lpbHighlight
);

Arguments:

hMark
Annotation handle.
lpbHighlight
Pointer to storage for annotation highlight state.

Description:

This function queries the highlight state of annotation. This is boolean property of legacy annotation types. When set to TRUE annotaion is transparent (equal to set transparency to 128). When FALSE annotation is opaque.

Return Value:

Error count.


IG_ARTX_freeline_highlight_set

Group: Freehand Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_freeline_highlight_set(
    HIG_ARTX_FREELINE hMark,
    AT_BOOL	bHighlight
);

Arguments:

hMark
Annotation handle.
bHighlight
Specifies new value of annotation highlight state.

Description:

This function sets highlight state of annotation.

Return Value:

Error count.


IG_ARTX_freeline_line_get

Group: Freehand Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_freeline_line_get(
    HIG_ARTX_FREELINE hMark,
    LPAT_ARTX_BORDER lpLine
);

Arguments:

hMark
Annotation handle.
lpLine
Pointer to storage for line atributes.

Description:

This function queries attributes of line used to draw the annotation. See AT_ARTX_BORDER structure for additional info.

Return Value:

Error count.


IG_ARTX_freeline_line_set

Group: Freehand Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_freeline_line_set(
    HIG_ARTX_FREELINE hMark,
    LPAT_ARTX_BORDER lpData
);

Arguments:

hMark
Annotation handle.
lpData
Pointer to line attributes structure.

Description:

This function sets attributes of line used to draw the annotation.

Return Value:

Error count.


IG_ARTX_freeline_point_count_get

Group: Freehand Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_freeline_point_count_get(
    HIG_ARTX_FREELINE hMark,
    LPAT_INT lpnCount
);

Arguments:

hMark
Annotation handle.
lpnCount
Pointer to buffer for point count.

Description:

This function obtains the number of freeline points.

Return Value:

Error count.


IG_ARTX_freeline_points_get

Group: Freehand Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_freeline_points_get(
    HIG_ARTX_FREELINE hMark,
    LPAT_POINT lpPoints,
    AT_DWORD nStart,
    AT_DWORD nCount
);

Arguments:

hMark
Annotation handle.
lpPoints
Specifies pointer to storage for points.
nStart
Specifies index of first point to get.
nCount
Specifies number of points to get.

Description:

This function queries annotation points data.

Return Value:

Error count.


IG_ARTX_freeline_points_set

Group: Freehand Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_freeline_points_set(
    HIG_ARTX_FREELINE hMark,
    LPAT_POINT lpPoints,
    AT_DWORD nStart,
    AT_DWORD nCount
);

Arguments:

hMark
Annotation handle.
lpPoints
Specifies buffer with new annotation points.
nStart
Specifies index of first point to set.
nCount
Specifies number of points to set.

Description:

This function updates annotation points data.

Return Value:

Error count.


HIG_ARTX_GROUP

Type: Basic Object

Description:

Collection of ART marks united into a group. This class provides methods and properties general for the entire group.

Class Members:

IG_ARTX_group_bring_to_front
Moves a group of marks to the top of the Z-Order.
IG_ARTX_group_clipboard_copy
Copies a group of marks to the clipboard.
IG_ARTX_group_clipboard_cut
Cuts a group of marks to the clipboard.
IG_ARTX_group_mark_add
Adds specified mark to the group.
IG_ARTX_group_mark_at
Gives the index to the specified mark within the group.
IG_ARTX_group_mark_count
Provides the count of the marks in the group.
IG_ARTX_group_mark_remove
Removes specified mark from the group.
IG_ARTX_group_mark_remove_at
Removes the mark specified by index from the group.
IG_ARTX_group_marks_remove
Removes the group of marks.
IG_ARTX_group_marks_select
Selects the group of marks.
IG_ARTX_group_send_to_back
Moves the group of marks to the bottom of the Z-Order


IG_ARTX_group_bring_to_front

Group: Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_group_bring_to_front(
    HIG_ARTX_GROUP hGroup
);

Arguments:

hGroup
Group handle.

Description:

This function moves a group of marks to the top of the Z-Order.

Return Value:

Error count.


IG_ARTX_group_clipboard_copy

Group: Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_group_clipboard_copy(
    HIG_ARTX_GROUP hGroup
);

Arguments:

hGroup
Group handle.

Description:

This function copies a group of marks to the clipboard.

Return Value:

Error count.


IG_ARTX_group_clipboard_cut

Group: Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_group_clipboard_cut(
    HIG_ARTX_GROUP hGroup
);

Arguments:

hGroup
Group handle

Description:

This function cuts a group of marks to the clipboard.

Return Value:

Error count.


IG_ARTX_group_mark_add

Group: Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_group_mark_add(
    HIG_ARTX_GROUP hGroup,
    HIG_ARTX_MARK hMark,
    enumIGArtXCoordType nCoordType,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

hGroup
Group handle
hMark
The mark to add to the group.
nCoordType
The type of the coordinates. See enumIGArtXCoordType values.
lphMark
Pointer to the mark.

Description:

This function adds specified mark to the group.

Return Value:

Error count.


IG_ARTX_group_mark_at

Group: Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_group_mark_at(
    HIG_ARTX_GROUP hGroup,
    AT_INT nMarkIndex,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

hGroup
Group handle
nMarkIndex
Index of the mark.
lphMark
Specified mark.

Description:

This function gives the index to the specified mark within the group.

Return Value:

Error count.


IG_ARTX_group_mark_count

Group: Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_group_mark_count(
    HIG_ARTX_GROUP hGroup,
    LPAT_INT lpnCount
);

Arguments:

hGroup
Group handle.
lpnCount
Mark count

Description:

This function provides the count of the marks in the group.

Return Value:

Error count.


IG_ARTX_group_mark_remove

Group: Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_group_mark_remove(
    HIG_ARTX_GROUP hGroup,
    HIG_ARTX_MARK hMark
);

Arguments:

hGroup
Group handle.
hMark
Specified mark.

Description:

This function removes specified mark from the group.

Return Value:

Error count.


IG_ARTX_group_mark_remove_at

Group: Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_group_mark_remove_at(
    HIG_ARTX_GROUP hGroup,
    AT_INT nIndex
);

Arguments:

hGroup
Group handle.
nIndex
Index of the mark.

Description:

This function removes the mark specified by index from the group.

Return Value:

Error count.


IG_ARTX_group_marks_remove

Group: Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_group_marks_remove(
    HIG_ARTX_GROUP hGroup
);

Arguments:

hGroup
Group handle.

Description:

This function removes the group of marks.

Return Value:

Error count.


IG_ARTX_group_marks_select

Group: Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_group_marks_select(
    HIG_ARTX_GROUP hGroup,
    AT_BOOL bState
);

Arguments:

hGroup
Group handle.
bState
The state of the group: selected/deselected.

Description:

This function selects the group of marks.

Return Value:

Error count.


IG_ARTX_group_send_to_back

Group: Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_group_send_to_back(
    HIG_ARTX_GROUP hGroup
);

Arguments:

hGroup
Group handle.

Description:

This function moves the group of marks to the bottom of the Z-Order.

Return Value:

Error count.


HIG_ARTX_HIGHLIGHTER

Type: Object

Description:

Legacy ART Highlighter mark.

Class Members:

IG_ARTX_highlighter_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_highlighter_bounds_set
Updates the bounding rectangle of annotation.
IG_ARTX_highlighter_create
Creates an instance of highlighter mark (IG_ARTX_MARK_HIGHLIGHTER).
IG_ARTX_highlighter_fillcolor_get
Queries filling color of annotation.
IG_ARTX_highlighter_fillcolor_set
Updates annotation filling color.


IG_ARTX_highlighter_bounds_get

Group: Highlighter

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_highlighter_bounds_get(
    HIG_ARTX_HIGHLIGHTER hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_highlighter_bounds_set

Group: Highlighter

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_highlighter_bounds_set(
    HIG_ARTX_HIGHLIGHTER hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to new bounding rectangle.

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_highlighter_create

Group: Highlighter

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_highlighter_create(
    LPAT_RECTANGLE pRectangle,
    LPAT_RGBQUAD pFillColor,
    LPHIG_ARTX_HIGHLIGHTER lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
pFillColor
Annotation fill color.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates an instance of highlighter mark (IG_ARTX_MARK_HIGHLIGHTER).

Return Value:

Error count.


IG_ARTX_highlighter_fillcolor_get

Group: Highlighter

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_highlighter_fillcolor_get(
    HIG_ARTX_HIGHLIGHTER hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for the fill color value.

Description:

This function queries filling color of annotation.

Return Value:

Error count.


IG_ARTX_highlighter_fillcolor_set

Group: Highlighter

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_highlighter_fillcolor_set(
    HIG_ARTX_HIGHLIGHTER hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
New color value to set. If lpColor is NULL then black color (0,0,0) is assumed.

Description:

This function updates annotation filling color.

Return Value:

Error count.


HIG_ARTX_HOLLOW_ELLIPSE

Type: Object

Description:

Legacy ART Hollow Ellipse mark.

Class Members:

IG_ARTX_hollow_ellipse_border_get
Queries filling color of ellipse annotation.
IG_ARTX_hollow_ellipse_border_set
Updates ellipse annotation filling color.
IG_ARTX_hollow_ellipse_bounds_get
Queries ellipse bounding rectangle.
IG_ARTX_hollow_ellipse_bounds_set
Updates ellipse bounding rectangle.
IG_ARTX_hollow_ellipse_create
Creates an instance of ellipse mark (IG_ARTX_MARK_HOLLOW_ELLIPSE).
IG_ARTX_hollow_ellipse_highlight_get
Queries the highlight state of annotation.
IG_ARTX_hollow_ellipse_highlight_set
Sets highlight state of annotation.


IG_ARTX_hollow_ellipse_border_get

Group: Hollow Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_ellipse_border_get(
    HIG_ARTX_FILLED_ELLIPSE hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
Pointer to storage for annotation border attributes.

Description:

This function queries filling color of ellipse annotation.

Return Value:

Error count.


IG_ARTX_hollow_ellipse_border_set

Group: Hollow Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_ellipse_border_set(
    HIG_ARTX_ELLIPSE hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
New value of border attributes to set. If lpBorder is NULL original annotaion border is not modified.

Description:

This function updates ellipse annotation filling color.

Return Value:

Error count.


IG_ARTX_hollow_ellipse_bounds_get

Group: Hollow Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_ellipse_bounds_get(
    HIG_ARTX_FILLED_ELLIPSE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for function result.

Description:

This function queries ellipse bounding rectangle.

Return Value:

Error count.


IG_ARTX_hollow_ellipse_bounds_set

Group: Hollow Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_ellipse_bounds_set(
    HIG_ARTX_FILLED_ELLIPSE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
New bounding rectangle to set.

Description:

This function updates ellipse bounding rectangle.

Return Value:

Error count.


IG_ARTX_hollow_ellipse_create

Group: Hollow Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_ellipse_create(
    LPAT_RECTANGLE pRectangle,
    LPAT_ARTX_BORDER pBorder,
    AT_BOOL bHighlight,
    LPHIG_ARTX_ELLIPSE lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
pBorder
Annotation border attributes.
bHighlight
Indicates whether the annotation is highlighted.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates an instance of ellipse mark (IG_ARTX_MARK_HOLLOW_ELLIPSE).

Return Value:

Error count.


IG_ARTX_hollow_ellipse_highlight_get

Group: Hollow Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_ellipse_highlight_get(
    HIG_ARTX_ELLIPSE hMark,
    LPAT_BOOL lpbHighlight
);

Arguments:

hMark
Annotation handle.
lpbHighlight
Pointer to storage annotation highlight state.

Description:

This function queries the highlight state of annotation. This is boolean property of legacy annotation types. When set to TRUE annotaion is transparent (equal to set transparency to 128). When FALSE annotation is opaque.

Return Value:

Error count.


IG_ARTX_hollow_ellipse_highlight_set

Group: Hollow Ellipse

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_ellipse_highlight_set(
    HIG_ARTX_FILLED_ELLIPSE hMark,
    AT_BOOL bHighlight
);

Arguments:

hMark
Annotation handle.
bHighlight
Pointer to storage annotation highlight state.

Description:

This function sets highlight state of annotation. This is boolean property of legacy annotation types and means that annotaion is transparent.

Return Value:

Error count.


HIG_ARTX_HOLLOW_POLYGON

Type: Object

Description:

Legacy ART Hollow Polygon mark.

Class Members:

IG_ARTX_hollow_polygon_border_get
Queries attributes of annotation line.
IG_ARTX_hollow_polygon_border_set
Updates attributes of annotation border.
IG_ARTX_hollow_polygon_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_hollow_polygon_create
Creates an instance of hollow polygon mark (IG_ARTX_MARK_HOLLOW_POLYGON).
IG_ARTX_hollow_polygon_highlight_get
Queries the highlight state of annotation.
IG_ARTX_hollow_polygon_highlight_set
Sets highlight state of annotation.
IG_ARTX_hollow_polygon_point_count_get
Obtains the number of polygon points.
IG_ARTX_hollow_polygon_points_get
Queries annotation points data.
IG_ARTX_hollow_polygon_points_set
Updates annotation points data.


IG_ARTX_hollow_polygon_border_get

Group: Hollow Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_polygon_border_get(
    HIG_ARTX_HOLLOW_POLYGON hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
Pointer to storage for annotation border attributes.

Description:

This function queries attributes of annotation line.

Return Value:

Error count.


IG_ARTX_hollow_polygon_border_set

Group: Hollow Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_polygon_border_set(
    HIG_ARTX_HOLLOW_POLYGON hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
New value of border attributes to set. If lpBorder is NULL original annotaion border is not modified.

Description:

This function updates attributes of annotation border.

Return Value:

Error count.


IG_ARTX_hollow_polygon_bounds_get

Group: Hollow Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_polygon_bounds_get(
    HIG_ARTX_HOLLOW_POLYGON hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation. This is read-only property and calculated as the biggest rectange that covers all points of the annotation.

Return Value:

Error count.


IG_ARTX_hollow_polygon_create

Group: Hollow Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_polygon_create(
    LPAT_POINT lpPoints,
    AT_DWORD nCount,
    LPAT_ARTX_BORDER pLine,
    AT_BOOL bHighlight,
    LPHIG_ARTX_HOLLOW_POLYGON lphMark
);

Arguments:

lpPoints
An array of polygon points.
nCount
The number of elements in lpPoints array.
pLine
Attributes of line used to draw annotation.
bHighlight
Indicates whether the annotation is highlighted.
lphMark
Pointer to storage for the new annotation handle.

Description:

This function creates an instance of hollow polygon mark (IG_ARTX_MARK_HOLLOW_POLYGON).

Return Value:

Error count.


IG_ARTX_hollow_polygon_highlight_get

Group: Hollow Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_polygon_highlight_get(
    HIG_ARTX_HOLLOW_POLYGON hMark,
    LPAT_BOOL lpbHighlight
);

Arguments:

hMark
Annotation handle.
lpbHighlight
Pointer to storage for annotation highlight state.

Description:

This function queries the highlight state of annotation. This is the boolean property of legacy annotation types. When set to TRUE, annotaion is transparent (equal to set transparency to 128). When FALSE - annotation is opaque.

Return Value:

Error count.


IG_ARTX_hollow_polygon_highlight_set

Group: Hollow Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_polygon_highlight_set(
    HIG_ARTX_HOLLOW_POLYGON hMark,
    AT_BOOL	bHighlight
);

Arguments:

hMark
Annotation handle.
bHighlight
Specifies new value of annotation highlight state.

Description:

This function sets the highlight state of the annotation.

Return Value:

Error count.


IG_ARTX_hollow_polygon_point_count_get

Group: Hollow Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_polygon_point_count_get(
    HIG_ARTX_HOLLOW_POLYGON hMark,
    LPAT_INT lpnCount
);

Arguments:

hMark
Annotation handle.
lpnCount
Pointer to buffer for point count.

Description:

This function obtains the number of polygon points.

Return Value:

Error count.


IG_ARTX_hollow_polygon_points_get

Group: Hollow Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_polygon_points_get(
    HIG_ARTX_HOLLOW_POLYGON hMark,
    LPAT_POINT lpPoints,
    AT_DWORD nStart,
    AT_DWORD nCount
);

Arguments:

hMark
Annotation handle.
lpPoints
Specifies pointer to storage for points.
nStart
Specifies index of first point to get.
nCount
Specifies number of points to get.

Description:

This function queries annotation points data.

Return Value:

Error count.


IG_ARTX_hollow_polygon_points_set

Group: Hollow Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_polygon_points_set(
    HIG_ARTX_HOLLOW_POLYGON hMark,
    LPAT_POINT lpPoints,
    AT_DWORD nStart,
    AT_DWORD nCount
);

Arguments:

hMark
Annotation handle.
lpPoints
Specifies buffer with new annotation points.
nStart
Specifies index of first point to set.
nCount
Specifies number of points to set.

Description:

This function updates the annotation points data.

Return Value:

Error count.


HIG_ARTX_HOLLOW_RECTANGLE

Type: Object

Description:

Legacy ART Hollow Rectangle mark object.

Class Members:

IG_ARTX_hollow_rectangle_border_get
Queries attributes of annotation border line.
IG_ARTX_hollow_rectangle_border_set
Updates attributes of annotation border.
IG_ARTX_hollow_rectangle_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_hollow_rectangle_bounds_set
Updates the bounding rectangle of annotation.
IG_ARTX_hollow_rectangle_create
Creates an instance of hollow rectangle mark (IG_ARTX_MARK_HOLLOW_RECTANGLE).
IG_ARTX_hollow_rectangle_highlight_get
Queries the highlight state of annotation.
IG_ARTX_hollow_rectangle_highlight_set
Sets highlight state of annotation.


IG_ARTX_hollow_rectangle_border_get

Group: Hollow Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_rectangle_border_get(
    HIG_ARTX_HOLLOW_RECTANGLE hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
Pointer to storage for annotation border attributes.

Description:

This function queries attributes of annotation border line.

Return Value:

Error count.


IG_ARTX_hollow_rectangle_border_set

Group: Hollow Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_rectangle_border_set(
    HIG_ARTX_HOLLOW_RECTANGLE hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
New value of border attributes to set. If lpBorder is NULL original annotaion border is not modified.

Description:

This function updates attributes of annotation border.

Return Value:

Error count.


IG_ARTX_hollow_rectangle_bounds_get

Group: Hollow Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_rectangle_bounds_get(
    HIG_ARTX_HOLLOW_RECTANGLE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to storage for bounding rectangle

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_hollow_rectangle_bounds_set

Group: Hollow Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_rectangle_bounds_set(
    HIG_ARTX_HOLLOW_RECTANGLE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to new bounding rectangle.

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_hollow_rectangle_create

Group: Hollow Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_rectangle_create(
    LPAT_RECTANGLE pRectangle,
    LPAT_ARTX_BORDER pBorder,
    AT_BOOL bHighlight,
    LPHIG_ARTX_HOLLOW_RECTANGLE lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
pBorder
Annotation border attributes.
bHighlight
Indicates whether the annotation is highlighted.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates an instance of hollow rectangle mark (IG_ARTX_MARK_HOLLOW_RECTANGLE).

Return Value:

Error count.


IG_ARTX_hollow_rectangle_highlight_get

Group: Hollow Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_rectangle_highlight_get(
    HIG_ARTX_HOLLOW_RECTANGLE hMark,
    LPAT_BOOL lpbHighlight
);

Arguments:

hMark
Annotation handle.
lpbHighlight
Pointer to storage for annotation highlight state.

Description:

This function queries the highlight state of annotation.

Return Value:

Error count.


IG_ARTX_hollow_rectangle_highlight_set

Group: Hollow Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hollow_rectangle_highlight_set(
    HIG_ARTX_HOLLOW_RECTANGLE hMark,
    AT_BOOL	bHighlight
);

Arguments:

hMark
Annotation handle.
bHighlight
Specifies new value of annotation highlight state.

Description:

This function sets highlight state of annotation.

Return Value:

Error count.


HIG_ARTX_HOTSPOT

Type: Object

Description:

ART Hot Spot mark object.

Class Members:

IG_ARTX_hotspot_border_get
Queries the annotation border.
IG_ARTX_hotspot_border_set
Updates the annotation border.
IG_ARTX_hotspot_bounds_get
Queries the bounding rectangle.
IG_ARTX_hotspot_bounds_set
Updates the bounding rectangle.
IG_ARTX_hotspot_create
Creates an instance of hotspot mark.
IG_ARTX_hotspot_fillcolor_get
Queries fill color of the annotation.
IG_ARTX_hotspot_fillcolor_set
Updates the annotation fill color.
IG_ARTX_hotspot_link_get
Queries link object associated with the annotation.
IG_ARTX_hotspot_link_set
Updates the link object associated with the annotation.
IG_ARTX_hotspot_opacity_get
Queries the value of annotation opacity.
IG_ARTX_hotspot_opacity_set
Updates the value of annotation opacity.


IG_ARTX_hotspot_border_get

Group: Hot Spot

Declaration:

AT_ERRCOUNT IG_ARTX_hotspot_border_get(
    HIG_ARTX_HOTSPOT hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
Pointer to storage for function result.

Description:

This function queries the annotation border.

Return Value:

Error count.


IG_ARTX_hotspot_border_set

Group: Hot Spot

Declaration:

AT_ERRCOUNT IG_ARTX_hotspot_border_set(
    HIG_ARTX_HOTSPOT hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
New border to set

Description:

This function

Return Value:

Error count.


IG_ARTX_hotspot_bounds_get

Group: Hot Spot

Declaration:

AT_ERRCOUNT IG_ARTX_hotspot_bounds_get(
    HIG_ARTX_HOTSPOT hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for function result.

Description:

This function queries the bounding rectangle.

Return Value:

Error count.


IG_ARTX_hotspot_bounds_set

Group: Hot Spot

Declaration:

AT_ERRCOUNT IG_ARTX_hotspot_bounds_set(
    HIG_ARTX_HOTSPOT hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
New bounding rectangle to set.

Description:

This function updates the bounding rectangle.

Return Value:

Error count.


IG_ARTX_hotspot_create

Group: Hot Spot

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_hotspot_create(
    LPAT_RECTANGLE pRectangle,
    LPAT_RGBQUAD pFillColor,
    LPAT_ARTX_BORDER pBorder,
    AT_INT Opacity,
    HIG_ARTX_LINK hLink,
    LPHIG_ARTX_HOTSPOT lphMark
);

Arguments:

pRectangle
Bounding rectangle.
pFillColor
Mark's fill color.
pBorder
Mark's border
Opacity
Mark's opacity.
hLink
Link object associated with the mark.
lphMark
Created object.

Description:

This function creates an instance of hotspot mark.

Return Value:

Error count.


IG_ARTX_hotspot_fillcolor_get

Group: Hot Spot

Declaration:

AT_ERRCOUNT IG_ARTX_hotspot_fillcolor_get(
    HIG_ARTX_HOTSPOT hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Mark's fill color.

Description:

This function queries fill color of the annotation.

Return Value:

Error count.


IG_ARTX_hotspot_fillcolor_set

Group: Hot Spot

Declaration:

AT_ERRCOUNT IG_ARTX_hotspot_fillcolor_set(
    HIG_ARTX_HOTSPOT hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
The new annotation fill color.

Description:

This function updates the annotation fill color.

Return Value:

Error count.


IG_ARTX_hotspot_link_get

Group: Hot Spot

Declaration:

AT_ERRCOUNT IG_ARTX_hotspot_link_get(
    HIG_ARTX_HOTSPOT hMark,
    LPHIG_ARTX_LINK lphLink
);

Arguments:

hMark
Annotation handle.
lphLink
Pointer to storage for function result

Description:

This function queries link object associated with the annotation.

Return Value:

Error count.


IG_ARTX_hotspot_link_set

Group: Hot Spot

Declaration:

AT_ERRCOUNT IG_ARTX_hotspot_link_set(
    HIG_ARTX_HOTSPOT hMark,
    HIG_ARTX_LINK lphLink
);

Arguments:

hMark
Annotation handle.
lphLink
New link object to set.

Description:

This function updates the link object associated with the annotation.

Return Value:

Error count.


IG_ARTX_hotspot_opacity_get

Group: Hot Spot

Declaration:

AT_ERRCOUNT IG_ARTX_hotspot_opacity_get(
    HIG_ARTX_HOTSPOT hMark,
    LPAT_INT lpnOpacity
);

Arguments:

hMark
Annotation handle.
lpnOpacity
Pointer to storage for function result.

Description:

This function queries the value of annotation opacity.

Return Value:

Error count.


IG_ARTX_hotspot_opacity_set

Group: Hot Spot

Declaration:

AT_ERRCOUNT IG_ARTX_hotspot_opacity_set(
    HIG_ARTX_HOTSPOT hMark,
    AT_INT nOpacity
);

Arguments:

hMark
Annotation handle.
nOpacity
New opacity value to set.

Description:

This function updates the value of annotation opacity.

Return Value:

Error count.


HIG_ARTX_IMAGE

Type: Object

Description:

ART Image mark object.

Class Members:

IG_ARTX_image_alignment_h_get
Queries value of annotation image horizontal alignment.
IG_ARTX_image_alignment_h_set
Updates value of annotation image horizontal alignment.
IG_ARTX_image_alignment_v_get
Queries value of annotation image vertical alignment.
IG_ARTX_image_alignment_v_set
Updates value of annotation image vertical alignment.
IG_ARTX_image_aspectratio_get
Queries value of annotation image aspect ratio.
IG_ARTX_image_aspectratio_set
Updates value of annotation image aspect ratio.
IG_ARTX_image_bounds_get
Queries the bounding rectangle of annotation
IG_ARTX_image_bounds_set
Updates the bounding rectangle of annotation.
IG_ARTX_image_create
Creates a new instance of image annotation (IG_ARTX_MARK_IMAGE).
IG_ARTX_image_filename_get
Queries the name of image file associated with hMark annotation.
IG_ARTX_image_filename_set
Assigns image file to annotation.
IG_ARTX_image_fitmode_get
Queries value of annotation image fitmode.
IG_ARTX_image_fitmode_set
Updates value of annotation image fitmode.
IG_ARTX_image_orientation_get
Queries value of annotation image orientation.
IG_ARTX_image_orientation_set
Updates value of annotation image orientation.
IG_ARTX_image_page_get
Queries the handle of image associated with hMark annotation.
IG_ARTX_image_page_set
Updates the image associated with hMark annotation.
IG_ARTX_image_transparent_color_get
Queries annotation transparent color.
IG_ARTX_image_transparent_color_set
Updates annotation transparent color with new value.


IG_ARTX_image_alignment_h_get

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_alignment_h_get(
    HIG_ARTX_IMAGE hMark,
    enumAlignModes* lpnAlignModes
);

Arguments:

hMark
Annotation handle.
lpnAlignModes
Pointer to buffer for function result.

Description:

This function queries value of annotation image horizontal alignment. See enumAlignModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_alignment_h_set

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_alignment_h_set(
    HIG_ARTX_IMAGE hMark,
    enumAlignModes nAlignModes
);

Arguments:

hMark
Annotation handle.
nAlignModes
Specifies new image horizontal alignment value.

Description:

This function updates value of annotation image horizontal alignment.

Return Value:

Error count.


IG_ARTX_image_alignment_v_get

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_alignment_v_get(
    HIG_ARTX_IMAGE hMark,
    enumAlignModes* lpnAlignModes
);

Arguments:

hMark
Annotation handle.
lpnAlignModes
Pointer to buffer for function result.

Description:

This function queries value of annotation image vertical alignment. See enumAlignModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_alignment_v_set

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_alignment_v_set(
    HIG_ARTX_IMAGE hMark,
    enumAlignModes nAlignModes
);

Arguments:

hMark
Annotation handle.
nAlignModes
Specifies new image vertical alignment value.

Description:

This function updates value of annotation image vertical alignment.

Return Value:

Error count.


IG_ARTX_image_aspectratio_get

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_aspectratio_get(
    HIG_ARTX_IMAGE hMark,
    AT_DOUBLE* lpdAspectratio
);

Arguments:

hMark
Annotation handle.
lpdAspectratio
Pointer to buffer for function result.

Description:

This function queries value of annotation image aspect ratio.

Return Value:

Error count.


IG_ARTX_image_aspectratio_set

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_aspectratio_set(
    HIG_ARTX_IMAGE hMark,
    AT_DOUBLE dAspectratio
);

Arguments:

hMark
Annotation handle.
dAspectratio
Specifies new image annotation image aspect ratio.

Description:

This function updates the value of annotation image aspect ratio.

Return Value:

Error count.


IG_ARTX_image_bounds_get

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_bounds_get(
    HIG_ARTX_IMAGE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_image_bounds_set

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_bounds_set(
    HIG_ARTX_IMAGE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to new bounding rectangle.

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_image_create

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_create(
    LPAT_RECTANGLE pRectangle,
    HIGEAR hGear,
    enumOrientModes	nOrientation,
    enumFitModes	nFitMode,
    enumAlignModes	nAlignmentH,
    enumAlignModes	nAlignmentV,
    AT_FLOAT		dAspectRatio,
    LPSTR  lpszFileName,
    LPAT_RGBQUAD pTransparentColor,
    LPHIG_ARTX_IMAGE lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
hGear
Handle of image to associate with new annotation. Copy of image is created and stored. This parameter can be NULL.
nOrientation
Specifies orientation of image within annotation bounding rectangle.
nFitMode
Specifies fit mode of image.
nAlignmentH
Specifies horizontal alignment of image.
nAlignmentV
Specifies vertical alignment of image.
dAspectRatio
Specifies image aspect ratio.
lpszFileName
Specifies name of file with image to associate with annotation. If hGear is not NULL then lpszFileName is ignored. Otherwise image from lpszFileName FILE is used.
pTransparentColor
Specifies transparent color.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates a new instance of image annotation (IG_ARTX_MARK_IMAGE).

Return Value:

Error count.


IG_ARTX_image_filename_get

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_filename_get(
    HIG_ARTX_IMAGE hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer for output string.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If file name attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store image file name.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no image file in the annotation then on output pnDataSize contains zero.

Description:

This function queries the name of image file associated with hMark annotation.

Return Value:

Error count.


IG_ARTX_image_filename_set

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_filename_set(
    HIG_ARTX_IMAGE hMark,
    LPSTR lpszFileName
);

Arguments:

hMark
Annotation handle.
lpszFileName
Specifies pointer to buffer with image file to set. If this parameter is NULL existing image is removed from annotation.

Description:

This function assigns image file to the annotation.

Return Value:

Error count.


IG_ARTX_image_fitmode_get

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_fitmode_get(
    HIG_ARTX_IMAGE hMark,
    enumFitModes* lpnFitmode
);

Arguments:

hMark
Annotation handle.
lpnFitmode
Pointer to buffer for function result.

Description:

This function queries value of annotation image fitmode. See enumFitModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_fitmode_set

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_fitmode_set(
    HIG_ARTX_IMAGE hMark,
    enumFitModes nFitmode
);

Arguments:

hMark
Annotation handle.
nFitmode
Specifies new image fitmode value.

Description:

This function updates value of annotation image fitmode.

Return Value:

Error count.


IG_ARTX_image_orientation_get

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_orientation_get(
    HIG_ARTX_IMAGE hMark,
    enumOrientModes* lpnOrientation
);

Arguments:

hMark
Annotation handle.
lpnOrientation
Pointer to buffer for function result.

Description:

This function queries value of annotation image orientation. See enumOrientModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_orientation_set

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_orientation_set(
    HIG_ARTX_IMAGE hMark,
    enumOrientModes nOrientation
);

Arguments:

hMark
Annotation handle.
nOrientation
New image orientation value

Description:

This function updates value of annotation image orientation.

Return Value:

Error count.


IG_ARTX_image_page_get

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_page_get(
    HIG_ARTX_IMAGE hMark,
    LPHIGEAR lphIGear
);

Arguments:

hMark
Annotation handle.
lphIGear
pointer to storage for image handle

Description:

This function queries the handle of image associated with hMark annotation.

Return Value:

Error count.


IG_ARTX_image_page_set

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_page_set(
    HIG_ARTX_IMAGE hMark,
    HIGEAR hIGear
);

Arguments:

hMark
Annotation handle.
hIGear
handle of image to associate with annotation. Copy of image is created and stored. If this parameter is NULL existing image is removed from annotation

Description:

This function updates the image associated with hMark annotation.

Return Value:

Error count.


IG_ARTX_image_transparent_color_get

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_transparent_color_get(
    HIG_ARTX_IMAGE hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for the transparent color value.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.

Description:

This function queries annotation transparent color.

If the transparent color is specified for the annotation then it is copied into the output buffer lpColor and number of bytes copied is placed into pnDataSize.

If lpColor is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_RGBQUAD structure.

If lpColor is not NULL and pnDataSize is not NULL and there is no transparent color in the annotation then on output pnDataSize contains zero.

Return Value:

Error count.


IG_ARTX_image_transparent_color_set

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_transparent_color_set(
    HIG_ARTX_IMAGE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to the new transparent color value. If lpColor is NULL then no transparent color will be set.

Description:

This function updates annotation transparent color with new value.

Return Value:

Error count.


HIG_ARTX_IMAGE_EMBEDDED

Type: Object

Description:

ART Image Embedded mark object.

Class Members:

IG_ARTX_image_embedded_alignment_h_get
queries value of annotation image horizontal alignment.
IG_ARTX_image_embedded_alignment_h_set
updates value of annotation image horizontal alignment.
IG_ARTX_image_embedded_alignment_v_get
queries value of annotation image vertical alignment.
IG_ARTX_image_embedded_alignment_v_set
updates value of annotation image vertical alignment.
IG_ARTX_image_embedded_aspectratio_get
queries value of annotation image aspect ratio.
IG_ARTX_image_embedded_aspectratio_set
updates value of annotation image aspect ratio.
IG_ARTX_image_embedded_bounds_get
queries the bounding rectangle of annotation
IG_ARTX_image_embedded_bounds_set
updates the bounding rectangle of annotation
IG_ARTX_image_embedded_create
creates a new instance of image annotation (IG_ARTX_IMAGE_EMBEDDED).
IG_ARTX_image_embedded_fitmode_get
queries value of annotation image fitmode.
IG_ARTX_image_embedded_fitmode_set
updates value of annotation image fitmode.
IG_ARTX_image_embedded_orientation_get
queries value of annotation image orientation.
IG_ARTX_image_embedded_orientation_set
updates value of annotation image orientation.
IG_ARTX_image_embedded_page_get
queries the handle of image associated with hMark annotation
IG_ARTX_image_embedded_page_set
updates the image associated with hMark annotation
IG_ARTX_image_embedded_transparent_color_get
Queries annotation transparent color.
IG_ARTX_image_embedded_transparent_color_set
Updates annotation transparent color with new value.


IG_ARTX_image_embedded_alignment_h_get

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_alignment_h_get(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    enumAlignModes* lpnAlignModes
);

Arguments:

hMark
Annotation handle.
lpnAlignModes
Pointer to buffer for function result.

Description:

This function queries value of annotation image horizontal alignment. See enumAlignModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_embedded_alignment_h_set

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_alignment_h_set(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    enumAlignModes nAlignModes
);

Arguments:

hMark
Annotation handle.
nAlignModes
Specifies new image horizontal alignment value.

Description:

This function updates the value of annotation image horizontal alignment.

Return Value:

Error count.


IG_ARTX_image_embedded_alignment_v_get

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_alignment_v_get(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    enumAlignModes* lpnAlignModes
);

Arguments:

hMark
Annotation handle.
lpnAlignModes
Pointer to buffer for function result.

Description:

This function queries value of annotation image vertical alignment. See enumAlignModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_embedded_alignment_v_set

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_alignment_v_set(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    enumAlignModes nAlignModes
);

Arguments:

hMark
Annotation handle.
nAlignModes
Specifies new image vertical alignment value.

Description:

This function updates the value of annotation image vertical alignment.

Return Value:

Error count.


IG_ARTX_image_embedded_aspectratio_get

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_aspectratio_get(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    AT_DOUBLE* lpdAspectratio
);

Arguments:

hMark
Annotation handle.
lpdAspectratio
Pointer to buffer for function result.

Description:

This function queries the value of annotation image aspect ratio.

Return Value:

Error count.


IG_ARTX_image_embedded_aspectratio_set

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_aspectratio_set(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    AT_DOUBLE dAspectratio
);

Arguments:

hMark
Annotation handle.
dAspectratio
Specifies new image annotation image aspect ratio.

Description:

This function updates the value of annotation image aspect ratio.

Return Value:

Error count.


IG_ARTX_image_embedded_bounds_get

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_bounds_get(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to storage for bounding rectangle

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_image_embedded_bounds_set

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_bounds_set(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to new bounding rectangle.

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_image_embedded_create

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_create(
    LPAT_RECTANGLE pRectangle,
    HIGEAR hGear,
    enumOrientModes	nOrientation,
    enumFitModes	nFitMode,
    enumAlignModes	nAlignmentH,
    enumAlignModes	nAlignmentV,
    AT_FLOAT		dAspectRatio,
    LPAT_RGBQUAD	pTransparentColor,
    LPHIG_ARTX_IMAGE_EMBEDDED lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
hGear
Handle of image to associate with new annotation. Copy of image is created and stored. This parameter can be NULL.
nOrientation
Specifies orientation of image within annotation bounding rectangle.
nFitMode
Specifies fit mode of image.
nAlignmentH
Specifies horizontal alignment of image.
nAlignmentV
Specifies vertical alignment of image.
dAspectRatio
Specifies image aspect ratio.
pTransparentColor
Specifies transparent color.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates a new instance of image annotation (IG_ARTX_IMAGE_EMBEDDED).

Return Value:

Error count.


IG_ARTX_image_embedded_fitmode_get

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_fitmode_get(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    enumFitModes* lpnFitmode
);

Arguments:

hMark
Annotation handle.
lpnFitmode
pointer to buffer for function result

Description:

This function queries value of annotation image fitmode. See enumFitModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_embedded_fitmode_set

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_fitmode_set(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    enumFitModes nFitmode
);

Arguments:

hMark
Annotation handle.
nFitmode
specifies new image fitmode value

Description:

This function updates value of annotation image fitmode.

Return Value:

Error count.


IG_ARTX_image_embedded_orientation_get

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_orientation_get(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    enumOrientModes* lpnOrientation
);

Arguments:

hMark
Annotation handle.
lpnOrientation
pointer to buffer for function result

Description:

This function queries value of annotation image orientation. See enumOrientModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_embedded_orientation_set

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_orientation_set(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    enumOrientModes nOrientation
);

Arguments:

hMark
Annotation handle.
nOrientation
New image orientation value.

Description:

This function updates value of annotation image orientation.

Return Value:

Error count.


IG_ARTX_image_embedded_page_get

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_page_get(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    LPHIGEAR lphIGear
);

Arguments:

hMark
Annotation handle.
lphIGear
Pointer to the storage for image handle.

Description:

This function queries the handle of image associated with hMark annotation.

Return Value:

Error count.


IG_ARTX_image_embedded_page_set

Group: Image Embedded

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_embedded_page_set(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    HIGEAR hIGear
);

Arguments:

hMark
Annotation handle.
hIGear
Handle of image to associate with annotation. Copy of image is created and stored. If this parameter is NULL existing image is removed from annotation.

Description:

This function updates the image associated with hMark annotation.

Return Value:

Error count.


IG_ARTX_image_embedded_transparent_color_get

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI
IG_ARTX_image_embedded_transparent_color_get(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for the transparent color value.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.

Description:

This function queries annotation transparent color.

If the transparent color is specified for the annotation then it is copied into the output buffer lpColor and number of bytes copied is placed into pnDataSize.

If lpColor is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_RGBQUAD structure.

If lpColor is not NULL and pnDataSize is not NULL and there is no transparent color in the annotation then on output pnDataSize contains zero.

Return Value:

Error count.


IG_ARTX_image_embedded_transparent_color_set

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI
IG_ARTX_image_embedded_transparent_color_set(
    HIG_ARTX_IMAGE_EMBEDDED hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to the new transparent color value. If lpColor is NULL then no transparent color will be set.

Description:

This function updates annotation transparent color with new value.

Return Value:

Error count.


HIG_ARTX_IMAGEREF

Type: Object

Description:

ART Image mark object.

Class Members:

IG_ARTX_image_reference_alignment_h_get
queries value of annotation image horizontal alignment.
IG_ARTX_image_reference_alignment_h_set
updates value of annotation image horizontal alignment.
IG_ARTX_image_reference_alignment_v_get
queries value of annotation image vertical alignment.
IG_ARTX_image_reference_alignment_v_set
updates value of annotation image vertical alignment.
IG_ARTX_image_reference_aspectratio_get
queries value of annotation image aspect ratio.
IG_ARTX_image_reference_aspectratio_set
updates value of annotation image aspect ratio.
IG_ARTX_image_reference_bounds_get
queries the bounding rectangle of annotation
IG_ARTX_image_reference_bounds_set
updates the bounding rectangle of annotation
IG_ARTX_image_reference_create
creates a new instance of image annotation (IG_ARTX_IMAGE_REFERENCE).
IG_ARTX_image_reference_filename_get
queries the name of image file associated with hMark annotation
IG_ARTX_image_reference_filename_set
assigns image file to annotation
IG_ARTX_image_reference_fitmode_get
queries value of annotation image fitmode.
IG_ARTX_image_reference_fitmode_set
updates value of annotation image fitmode.
IG_ARTX_image_reference_orientation_get
queries value of annotation image orientation.
IG_ARTX_image_reference_orientation_set
updates value of annotation image orientation.
IG_ARTX_image_reference_transparent_color_get
Queries annotation transparent color.
IG_ARTX_image_reference_transparent_color_set
Updates annotation transparent color with new value.


IG_ARTX_image_reference_alignment_h_get

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_alignment_h_get(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    enumAlignModes* lpnAlignModes
);

Arguments:

hMark
Annotation handle.
lpnAlignModes
Pointer to buffer for function result.

Description:

This function queries value of annotation image horizontal alignment. See enumAlignModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_reference_alignment_h_set

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_alignment_h_set(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    enumAlignModes nAlignModes
);

Arguments:

hMark
Annotation handle.
nAlignModes
Specifies new image horizontal alignment value.

Description:

This function updates value of annotation image horizontal alignment.

Return Value:

Error count.


IG_ARTX_image_reference_alignment_v_get

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_alignment_v_get(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    enumAlignModes* lpnAlignModes
);

Arguments:

hMark
Annotation handle.
lpnAlignModes
Pointer to buffer for function result.

Description:

This function queries value of annotation image vertical alignment. See enumAlignModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_reference_alignment_v_set

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_alignment_v_set(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    enumAlignModes nAlignModes
);

Arguments:

hMark
Annotation handle.
nAlignModes
Specifies new image vertical alignment value.

Description:

This function updates value of annotation image vertical alignment.

Return Value:

Error count.


IG_ARTX_image_reference_aspectratio_get

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_aspectratio_get(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    AT_DOUBLE* lpdAspectratio
);

Arguments:

hMark
Annotation handle.
lpdAspectratio
Pointer to buffer for function result.

Description:

This function queries value of annotation image aspect ratio.

Return Value:

Error count.


IG_ARTX_image_reference_aspectratio_set

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_aspectratio_set(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    AT_DOUBLE dAspectratio
);

Arguments:

hMark
Annotation handle.
dAspectratio
Specifies new image annotation image aspect ratio.

Description:

This function updates the value of annotation image aspect ratio.

Return Value:

Error count.


IG_ARTX_image_reference_bounds_get

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_bounds_get(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_image_reference_bounds_set

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_bounds_set(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to new bounding rectangle.

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_image_reference_create

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_create(
    LPAT_RECTANGLE pRectangle,
    HIGEAR hGear,
    enumOrientModes nOrientation,
    enumFitModes nFitMode,
    enumAlignModes nAlignmentH,
    enumAlignModes nAlignmentV,
    AT_FLOAT dAspectRatio,
    LPSTR  lpszFileName,
    LPAT_RGBQUAD pTransparentColor,
    HIG_ARTX_IMAGE_REFERENCE lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
hGear
Handle of image to associate with new annotation. Copy of image is created and stored. This parameter can be NULL.
nOrientation
Specifies orientation of image within annotation bounding rectangle.
nFitMode
Specifies fit mode of image.
nAlignmentH
Specifies horizontal alignment of image.
nAlignmentV
Specifies vertical alignment of image.
dAspectRatio
Specifies image aspect ratio.
lpszFileName
Specifies name of file with image to associate with annotation. If hGear is not NULL then lpszFileName is ignored. Otherwise image from lpszFileName FILE is used.
pTransparentColor
Specifies transparent color.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates a new instance of image annotation (IG_ARTX_IMAGE_REFERENCE).

Return Value:

Error count.


IG_ARTX_image_reference_filename_get

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_filename_get(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer for output string.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If file name attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store image file name.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no image file in the annotation then on output pnDataSize contains zero.

Description:

This function queries the name of image file associated with hMark annotation.

Return Value:

Error count.


IG_ARTX_image_reference_filename_set

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_filename_set(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    LPSTR lpszFileName
);

Arguments:

hMark
Annotation handle.
lpszFileName
Specifies pointer to buffer with image file to set. If this parameter is NULL existing image is removed from annotation.

Description:

This function assigns image file to annotation.

Return Value:

Error count.


IG_ARTX_image_reference_fitmode_get

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_fitmode_get(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    enumFitModes* lpnFitmode
);

Arguments:

hMark
Annotation handle.
lpnFitmode
Pointer to buffer for function result.

Description:

This function queries value of annotation image fitmode. See enumFitModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_reference_fitmode_set

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_fitmode_set(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    enumFitModes nFitmode
);

Arguments:

hMark
Annotation handle.
nFitmode
Specifies new image fitmode value.

Description:

This function updates value of annotation image fitmode.

Return Value:

Error count.


IG_ARTX_image_reference_orientation_get

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_orientation_get(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    enumOrientModes* lpnOrientation
);

Arguments:

hMark
Annotation handle.
lpnOrientation
Pointer to buffer for function result.

Description:

This function queries value of annotation image orientation. See enumOrientModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_image_reference_orientation_set

Group: Image Reference

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_image_reference_orientation_set(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    enumOrientModes nOrientation
);

Arguments:

hMark
Annotation handle.
nOrientation
New image orientation value.

Description:

This function updates value of annotation image orientation.

Return Value:

Error count.


IG_ARTX_image_reference_transparent_color_get

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI
IG_ARTX_image_reference_transparent_color_get(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for the transparent color value.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.

Description:

This function queries annotation transparent color.

If the transparent color is specified for the annotation then it is copied into the output buffer lpColor and number of bytes copied is placed into pnDataSize.

If lpColor is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_RGBQUAD structure.

If lpColor is not NULL and pnDataSize is not NULL and there is no transparent color in the annotation then on output pnDataSize contains zero.

Return Value:

Error count.


IG_ARTX_image_reference_transparent_color_set

Group: Image

Declaration:

AT_ERRCOUNT ACCUAPI
IG_ARTX_image_reference_transparent_color_set(
    HIG_ARTX_IMAGE_REFERENCE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to the new transparent color value. If lpColor is NULL then no transparent color will be set.

Description:

This function updates annotation transparent color with new value.

Return Value:

Error count.


HIG_ARTX_LINE

Type: Object

Description:

ART Line mark object.

Class Members:

IG_ARTX_line_bounds_get
Queries the bounding rectangle.
IG_ARTX_line_create
Creates line mark.
IG_ARTX_line_endhead_get
Queries the end head of the annotation.
IG_ARTX_line_endhead_set
Updates the end head of the annotation.
IG_ARTX_line_endpoint_get
Gets the line end point.
IG_ARTX_line_endpoint_set
Sets the line end point.
IG_ARTX_line_headfillcolor_get
Queries head fill color of the annotation.
IG_ARTX_line_headfillcolor_set
Updates the annotation head fill color.
IG_ARTX_line_line_get
Queries the annotation line attributes.
IG_ARTX_line_line_set
Updates the annotation line attributes.
IG_ARTX_line_opacity_get
Queries the value of annotation opacity.
IG_ARTX_line_opacity_set
Updates the value of annotation opacity.
IG_ARTX_line_starthead_get
Queries the start head of the annotation.
IG_ARTX_line_starthead_set
Updates the start head of the annotation.
IG_ARTX_line_startpoint_get
Gets the line start point.
IG_ARTX_line_startpoint_set
Sets the line start point.


IG_ARTX_line_bounds_get

Group: Line

Declaration:

AT_ERRCOUNT IG_ARTX_line_bounds_get(
    HIG_ARTX_LINE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for function result.

Description:

This function queries the bounding rectangle.

Return Value:

Error count.


IG_ARTX_line_create

Group: Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_line_create(
    LPAT_POINT lpStartPoint,
    LPAT_POINT lpEndPoint,
    LPAT_ARTX_BORDER pLine,
    LPAT_ARTX_ARROW_HEAD lpStartHead,
    LPAT_ARTX_ARROW_HEAD lpEndHead,
    LPAT_RGBQUAD pHeadFillColor,
    AT_INT nOpacity,
    LPHIG_ARTX_POLYLINE lphMark
);

Arguments:

lpStartPoint
Start point of the line.
lpEndPoint
End point of the line.
pLine
Line attributes.
lpStartHead
Start head of the line.
lpEndHead
End head of the line.
pHeadFillColor
Arrow head fill color.
nOpacity
Opacity of the line.
lphMark
Pointer to the created mark.

Description:

This function creates the Line mark.

Return Value:

Error count.


IG_ARTX_line_endhead_get

Group: Line

Declaration:

AT_ERRCOUNT IG_ARTX_line_endhead_get(
    HIG_ARTX_LINE hMark,
    LPAT_ARTX_ARROW_HEAD lpHead
);

Arguments:

hMark
Annotation handle.
lpHead
Pointer to storage for function result.

Description:

This function queries the end head of the annotation.

Return Value:

Error count.


IG_ARTX_line_endhead_set

Group: Line

Declaration:

AT_ERRCOUNT IG_ARTX_line_endhead_set(
    HIG_ARTX_LINE hMark,
    LPAT_ARTX_ARROW_HEAD lpHead
);

Arguments:

hMark
Annotation handle.
lpHead
Pointer to the head to set.

Description:

This function updates the end head of the annotation.

Return Value:

Error count.


IG_ARTX_line_endpoint_get

Group: Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_line_endpoint_get(
    HIG_ARTX_POLYLINE hMark,
    LPAT_POINT lpEndPoint
);

Arguments:

hMark
Annotation handle.
lpEndPoint
Pointer to the end point.

Description:

This function gets the Line end point.

Return Value:

Error count.


IG_ARTX_line_endpoint_set

Group: Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_line_endpoint_set(
    HIG_ARTX_POLYLINE hMark,
    LPAT_POINT lpEndPoint
);

Arguments:

hMark
Annotation handle.
lpEndPoint
Pointer to the end point.

Description:

This function sets the Line end point.

Return Value:

Error count.


IG_ARTX_line_headfillcolor_get

Group: Line

Declaration:

AT_ERRCOUNT IG_ARTX_line_headfillcolor_get(
    HIG_ARTX_LINE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for function result.

Description:

This function queries head fill color of the annotation.

Return Value:

Error count.


IG_ARTX_line_headfillcolor_set

Group: Line

Declaration:

AT_ERRCOUNT IG_ARTX_line_headfillcolor_set(
    HIG_ARTX_LINE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
New color value to set.

Description:

This function updates the annotation head fill color.

Return Value:

Error count.


IG_ARTX_line_line_get

Group: Line

Declaration:

AT_ERRCOUNT IG_ARTX_line_line_get(
    HIG_ARTX_LINE hMark,
    LPAT_ARTX_BORDER lpLine
);

Arguments:

hMark
Annotation handle.
lpLine
Pointer to storage for function result.

Description:

This function queries the annotation Line attributes.

Return Value:

Error count.


IG_ARTX_line_line_set

Group: Line

Declaration:

AT_ERRCOUNT IG_ARTX_line_line_set(
    HIG_ARTX_LINE hMark,
    LPAT_ARTX_BORDER lpLine
);

Arguments:

hMark
Annotation handle.
lpLine
New line attributes to set.

Description:

This function updates the annotation Line attributes.

Return Value:

Error count.


IG_ARTX_line_opacity_get

Group: Line

Declaration:

AT_ERRCOUNT IG_ARTX_line_opacity_get(
    HIG_ARTX_LINE hMark,
    LPAT_INT lpnOpacity
);

Arguments:

hMark
Annotation handle.
lpnOpacity
Pointer to storage for function result.

Description:

This function queries the value of annotation opacity.

Return Value:

Error count.


IG_ARTX_line_opacity_set

Group: Line

Declaration:

AT_ERRCOUNT IG_ARTX_line_opacity_set(
    HIG_ARTX_LINE hMark,
    AT_INT nOpacity
);

Arguments:

hMark
Annotation handle.
nOpacity
New opacity value to set.

Description:

This function updates the value of annotation opacity.

Return Value:

Error count.


IG_ARTX_line_starthead_get

Group: Line

Declaration:

AT_ERRCOUNT IG_ARTX_line_starthead_get(
    HIG_ARTX_LINE hMark,
    LPAT_ARTX_ARROW_HEAD lpHead
);

Arguments:

hMark
Annotation handle.
lpHead
Pointer to storage for function result.

Description:

This function queries the start head of the annotation.

Return Value:

Error count.


IG_ARTX_line_starthead_set

Group: Line

Declaration:

AT_ERRCOUNT IG_ARTX_line_starthead_set(
    HIG_ARTX_LINE hMark,
    LPAT_ARTX_ARROW_HEAD lpHead
);

Arguments:

hMark
Annotation handle.
lpHead
Pointer to the head to set.

Description:

This function updates the start head of the annotation.

Return Value:

Error count.


IG_ARTX_line_startpoint_get

Group: Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_line_startpoint_get(
    HIG_ARTX_POLYLINE hMark,
    LPAT_POINT lpStartPoint
);

Arguments:

hMark
Annotation handle.
lpStartPoint
Pointer to the start point.

Description:

This function gets the Line start point.

Return Value:

Error count.


IG_ARTX_line_startpoint_set

Group: Line

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_line_startpoint_set(
    HIG_ARTX_POLYLINE hMark,
    LPAT_POINT lpStartPoint
);

Arguments:

hMark
Annotation handle.
lpStartPoint
Pointer to the start point.

Description:

This function sets the Line start point.

Return Value:

Error count.


HIG_ARTX_LINK

Type: Object

Description:

ArtX link objects associated with the HotSpot mark.

See Also:

HIG_ARTX_HOTSPOT

Class Members:

IG_ARTX_link_create
Creates new Link object.
IG_ARTX_link_data_get
Returns Link data.
IG_ARTX_link_data_set
Sets the Link data
IG_ARTX_link_highlight_get
Returns Link highlight mode.
IG_ARTX_link_highlight_set
Sets Link highlight mode.


IG_ARTX_link_create

Group: Link

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_link_create(
    LPVOID lpData,
    enumIGArtXHighlightModes nHighlightMode,
    LPHIG_ARTX_LINK lphLink
);

Arguments:

lpData
Link data.
nHighlightMode
Link highlight mode that can be used by GUI to highlight the hotspot area.
lphLink
Created Link object.

Description:

This function creates new Link object.

Return Value:

Error count.


IG_ARTX_link_data_get

Group: Link

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_link_data_get(
    HIG_ARTX_LINK hLink,
    LPVOID* lpData
);

Arguments:

hLink
Link object.
lpData
Pointer to the returned value.

Description:

This function returns the Link data.

Return Value:

Error count.


IG_ARTX_link_data_set

Group: Link

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_link_data_set(
    HIG_ARTX_LINK hLink,
    LPVOID lpData
);

Arguments:

hLink
Link object.
lpData
pointer to the new data. Use HIG_PDF_ACTION object to associate a PDF action with the link.

Description:

This function sets the Link data.

Return Value:

Error count.


IG_ARTX_link_highlight_get

Group: Link

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_link_highlight_get(
    HIG_ARTX_LINK hLink,
    enumIGArtXHighlightModes* lpnHighlight
);

Arguments:

hLink
Link object.
lpnHighlight
Pointer to the returned value.

Description:

This function returns the Link highlight mode.

Return Value:

Error count.


IG_ARTX_link_highlight_set

Group: Link

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_link_highlight_set(
    HIG_ARTX_LINK hLink,
    enumIGArtXHighlightModes nHighlight
);

Arguments:

hLink
Link object.
nHighlight
New highlight mode to set.

Description:

This function sets the Link highlight mode.

Return Value:

Error count.


HIG_ARTX_MARK

Type: Object

Description:

Abstract ART mark class that provides general properties and methods for all mark types.

Class Members:

IG_ARTX_mark_bounds_get
Queries annotation bounding rectangle.
IG_ARTX_mark_clone
Creates a copy of mark.
IG_ARTX_mark_clone_from_legacy
Creates a non-legacy object that corresponds to the source mark.
IG_ARTX_mark_create
Creates specified mark object with default attributes.
IG_ARTX_mark_delete
Deletes the mark object.
IG_ARTX_mark_hittest_bounds_get
Returns a minimal bounding rectangle containing all the graphic elements of annotation.
IG_ARTX_mark_move
Moves mark to the specified offset.
IG_ARTX_mark_tooltip_get
Queries annotation tooltip string.
IG_ARTX_mark_tooltip_set
Updates annotation tooltip string.
IG_ARTX_mark_type_get
Queries type of annotation.
IG_ARTX_mark_user_data_get
Queries user data associated with mark.
IG_ARTX_mark_user_data_set
Sets the user data associated with mark.
IG_ARTX_mark_visible_get
Queries visibility state of mark.
IG_ARTX_mark_visible_set
Sets the mark visibility state.


IG_ARTX_mark_bounds_get

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_bounds_get(
    HIG_ARTX_MARK hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Mark handle.
lpRect
Pointer to storage for function result.

Description:

This function queries annotation bounding rectangle.

Return Value:

Error count.


IG_ARTX_mark_clone

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_clone(
    HIG_ARTX_MARK hMarkSrc,
    LPHIG_ARTX_MARK phMarkNew
);

Arguments:

hMarkSrc
Handle of source mark.
phMarkNew
Pointer to storage for new mark handle.

Description:

This function creates a copy of mark.

Return Value:

Error count.


IG_ARTX_mark_clone_from_legacy

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_clone_from_legacy(
    HIG_ARTX_MARK hMarkSrc,
    LPHIG_ARTX_MARK phMarkNew
);

Arguments:

hMarkSrc
Handle of source mark.
phMarkNew
Pointer to storage for new mark handle.

Description:

This function works with legacy mark. It creates a non-legacy object that corresponds to the source mark.

Return Value:

Error count.


IG_ARTX_mark_create

Group: Mark

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_mark_create(
    enumIGArtXMarkType nMarkType,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

nMarkType
The type of mark. Please see enumIGArtXMarkType values.
lphMark
Mrk handle.

Description:

This function creates specified mark object with default attributes.

Return Value:

Error count.


IG_ARTX_mark_delete

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_delete(
    HIG_ARTX_MARK hMark
);

Arguments:

hMark
Mark handle to delete.

Description:

This function creates specified mark object with default attributes.

Return Value:

Error count.


IG_ARTX_mark_hittest_bounds_get

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_hittest_bounds_get(
    HIG_ARTX_MARK hMark,
    LPAT_ARTX_DRAW_PARAMS lpDrawParams,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpDrawParams
Drawing parameters required to calculate device coordinates of the mark.
lpRect
Pointer to storage for function result.

Description:

This function returns a minimal bounding rectangle containing all the graphic elements of annotation (in device coordinates).

Return Value:

Error count.


IG_ARTX_mark_move

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_move(
    HIG_ARTX_MARK hMarkSrc,
    AT_INT nXoffset,
    AT_INT nYoffset
);

Arguments:

hMarkSrc
Handle of source mark.
nXoffset
Horizontal move offset.
nYoffset
Vertical move offset.

Description:

This function moves mark to the specified offset.

Return Value:

Error count.


IG_ARTX_mark_tooltip_get

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_tooltip_get(
    HIG_ARTX_MARK hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnBufLength
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer for output string.
pnBufLength
Pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If tooltip attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnBufLength is not NULL then on output pnBufLength contains the size required to store annotation text.
If lpszTextBuffer is not NULL and pnBufLength is not NULL and there is no tooltip text in the annotation then on output pnBufLength contains zero.

Description:

This function queries annotation tooltip string.

Return Value:

Error count.


IG_ARTX_mark_tooltip_set

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_tooltip_set(
    HIG_ARTX_MARK hMark,
    LPSTR lpszTextBuffer
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer containing a new annotation tooltip text. If lpszTextBuffer is NULL then annotation tooltip text attribute will be empty.

Description:

This function updates annotation tooltip string.

Return Value:

Error count.


IG_ARTX_mark_type_get

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_type_get(
    HIG_ARTX_MARK hMark,
    enumIGArtXMarkType* lpMarkType
);

Arguments:

hMark
Mark handle.
lpMarkType
Pointer to storage for function result

Description:

This function queries type of annotation.

Return Value:

Error count.


IG_ARTX_mark_user_data_get

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_user_data_get(
    HIG_ARTX_MARK hMark,
    LPAT_VOID* lpData
);

Arguments:

hMark
Annotation handle.
lpData
Pointer to storage for function result.

Description:

This function queries user data associated with mark.

Return Value:

Error count.


IG_ARTX_mark_user_data_set

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_user_data_set(
    HIG_ARTX_MARK hMark,
    LPAT_VOID lpData
);

Arguments:

hMark
Annotation handle.
lpData
User data pointer.

Description:

This function sets the user data associated with mark.

Return Value:

Error count.


IG_ARTX_mark_visible_get

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_visible_get(
    HIG_ARTX_MARK hMark,
    LPAT_BOOL lpbVisible
);

Arguments:

hMark
Annotation handle.
lpbVisible
Pointer to storage for function result.

Description:

This function queries visibility state of mark. If lpbVisible is TRUE the mark is visible.

Return Value:

Error count.


IG_ARTX_mark_visible_set

Group: Mark

Declaration:

AT_ERRCOUNT IG_ARTX_mark_visible_set(
    HIG_ARTX_MARK hMark,
    AT_BOOL bVisible
);

Arguments:

hMark
Annotation handle
bVisible
Visibility value to set.

Description:

This function sets the mark visibility state.

Return Value:

Error count.


HIG_ARTX_NOTE

Type: Object

Description:

Legacy ART Text Note mark.

Class Members:

IG_ARTX_text_note_bounds_get
queries the bounding rectangle of annotation
IG_ARTX_text_note_bounds_set
updates the bounding rectangle of annotation
IG_ARTX_text_note_boundswrap_get
queries the boundswrap of annotation
IG_ARTX_text_note_boundswrap_set
updates the boundswrap of annotation
IG_ARTX_text_note_create
creates a new instance of Text-note annotation (IG_ARTX_MARK_ATTACH_A_NOTE).
IG_ARTX_text_note_fillcolor_get
queries annotation fill color
IG_ARTX_text_note_fillcolor_set
updates annotation fill color with new value
IG_ARTX_text_note_font_get
queries annotation text font
IG_ARTX_text_note_font_set
updates annotation text font
IG_ARTX_text_note_logfont_get
queries annotation text font
IG_ARTX_text_note_logfont_set
updates annotation text font
IG_ARTX_text_note_orientation_get
queries value of annotation text orientation.
IG_ARTX_text_note_orientation_set
sets value of annotation text orientation.
IG_ARTX_text_note_text_get
queries annotation text string
IG_ARTX_text_note_text_set
updates annotation text string
IG_ARTX_text_note_textcolor_get
queries annotation text color
IG_ARTX_text_note_textcolor_set
updates annotation text color with new value


IG_ARTX_text_note_bounds_get

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_bounds_get(
    HIG_ARTX_TEXT_NOTE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle
lpRect
pointer to storage for bounding rectangle

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_note_bounds_set

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_bounds_set(
    HIG_ARTX_TEXT_NOTE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle
lpRect
pointer to new bounding rectangle

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_note_boundswrap_get

Group: Text Note

Declaration:

AT_ERRCOUNT IG_ARTX_text_note_boundswrap_get(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap* lpWrapMode
);

Arguments:

hMark
Annotation handle.
lpWrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Gets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_note_boundswrap_set

Group: Text Note

Declaration:

AT_ERRCOUNT IG_ARTX_text_note_boundswrap_set(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap WrapMode
);

Arguments:

hMark
Annotation handle.
WrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Sets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_note_create

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_create(
    LPAT_RECTANGLE pRectangle,
    LPSTR lpszText,
    LPAT_ARTX_FONT lpFont,
    LPAT_RGBQUAD pFillColor,
    LPAT_RGBQUAD pTextColor,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

pRectangle
annotation bounding rectangle
lpszText
text string drawn on annotation
lpFont
attributes of font to be used for text drawing
pFillColor
annotation fill color
pTextColor
text color
lphMark
pointer to storage for new annotation handle

Description:

This function creates a new instance of Text-note annotation (IG_ARTX_MARK_ATTACH_A_NOTE).

Return Value:

Error count.


IG_ARTX_text_note_fillcolor_get

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_fillcolor_get(
    HIG_ARTX_TEXT_NOTE hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle
lpColor
pointer to storage for the fill color value
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.
If fill color is specified for the annotation then it is copied into output buffer lpColor and number of bytes copied is placed into pnDataSize.
If lpColor is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_RGBQUAD structure.
If lpColor is not NULL and pnDataSize is not NULL and there is no fill color in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation fill color.

Return Value:

Error count.


IG_ARTX_text_note_fillcolor_set

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_fillcolor_set(
    HIG_ARTX_TEXT_NOTE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle
lpColor
pointer to new fill color value. If lpColor is NULL then annotation internal area will not be filled

Description:

This function updates annotation fill color with new value.

Return Value:

Error count.


IG_ARTX_text_note_font_get

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_font_get(
    HIG_ARTX_TEXT_NOTE hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_note_font_set

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_font_set(
    HIG_ARTX_TEXT_NOTE hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_note_logfont_get

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_logfont_get(
    HIG_ARTX_TEXT_NOTE hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_note_logfont_set

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_logfont_set(
    HIG_ARTX_TEXT_NOTE hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_note_orientation_get

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_orientation_get(
    HIG_ARTX_TEXT_NOTE hMark,
    enumOrientModes* lpnOrientation
);

Arguments:

hMark
Annotation handle
lpnOrientation
pointer to buffer for function result

Description:

This function queries value of annotation text orientation. See enumOrientModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_text_note_orientation_set

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_orientation_set(
    HIG_ARTX_TEXT_NOTE hMark,
    enumOrientModes nOrientation
);

Arguments:

hMark
Annotation handle
nOrientation

Description:

This function sets value of annotation text orientation.

Return Value:

Error count.


IG_ARTX_text_note_text_get

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_text_get(
    HIG_ARTX_TEXT_NOTE hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle
lpszTextBuffer
pointer to buffer for output string
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If text attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store annotation text.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no text in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text string.

Return Value:

Error count.


IG_ARTX_text_note_text_set

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_text_set(
    HIG_ARTX_TEXT_NOTE hMark,
    LPSTR lpszTextBuffer
);

Arguments:

hMark
Annotation handle
lpszTextBuffer
pointer to buffer with new annotation text. If lpszTextBuffer is NULL then annotation text attribute will be empty

Description:

This function sets annotation text string.

Return Value:

Error count.


IG_ARTX_text_note_textcolor_get

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_textcolor_get(
    HIG_ARTX_TEXT_NOTE hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle
lpColor
pointer to storage for the text color value
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.
If text color is specified for the annotation then it is copied into output buffer lpColor and number of bytes copied is placed into pnDataSize.
If lpColor is NULL and pnDataSize is not NULL then on output pnDataSize contains the size of AT_RGBQUAD structure.
If lpColor is not NULL and pnDataSize is not NULL and there is no text color in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text color.

Return Value:

Error count.


IG_ARTX_text_note_textcolor_set

Group: Text Note

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_note_textcolor_set(
    HIG_ARTX_TEXT_NOTE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle
lpColor
pointer to new text color value. If lpColor is NULL then no text will be drawn on annotation

Description:

This function sets annotation text color with new value.

Return Value:

Error count.


HIG_ARTX_PAGE

Type: Object

Description:

Collection of ART groups. This class provides methods and properties for accessing to individual marks on the page, as well as to the group of marks.

ART page is completely independent from the image page and can be associated with one or more raster or vector pages.

Class Members:

IG_ARTX_page_apply_to_image
Applies all the image related marks from hArtPage to the specified hIGear.
IG_ARTX_page_attr_get
Returns attributes of ArtX page.
IG_ARTX_page_attr_set
Modifies attributes of ArtX page.
IG_ARTX_page_burn_in
Merges marks permanently into hArtPage.
IG_ARTX_page_create
Creates new blank ArtX page object
IG_ARTX_page_delete
Destroys specified ArtX page including all objects associated with this page.
IG_ARTX_page_display_flip
Flips page's orientation.
IG_ARTX_page_display_orientation_get
Gets page's orientation.
IG_ARTX_page_display_orientation_set
Sets page's orientation.
IG_ARTX_page_display_rotate
Rotates page's orientation.
IG_ARTX_page_group_add
Adds new group to ArtX page.
IG_ARTX_page_group_at
Returns handle of group with index specified.
IG_ARTX_page_group_count
Returns number of group on ArtX page specified.
IG_ARTX_page_group_delete
Deletes specified group from page and destroys all related group content.
IG_ARTX_page_group_get
Returns handle of group with name specified
IG_ARTX_page_hit_test
Checks if mouse poiner is on any mark on the page.
IG_ARTX_page_load
Loads annotations from HIGEAR to the ArtX page.
IG_ARTX_page_load_file
Loads annotations from file to the ArtX page specified.
IG_ARTX_page_mark_add
Adds new mark to ArtX page.
IG_ARTX_page_mark_add_to_group_index
Adds new mark to ArtX page. Mark will be added to group with the index specified.
IG_ARTX_page_mark_add_to_group_name
Adds new mark to ArtX page. Mark will be added to group with the name specified.
IG_ARTX_page_mark_bring_to_front
Changes Z-order of marks on the page. It sends the mark specified to the top of stack.
IG_ARTX_page_mark_coord_type_set
Changes coordinate type of the specified mark on page.
IG_ARTX_page_mark_first
Returns handle of the first annotation.
IG_ARTX_page_mark_is_selected
Returns selection state of annotation specified.
IG_ARTX_page_mark_is_valid
Validates that mark handle is valid on this page.
IG_ARTX_page_mark_next
Returns handle of the next annotation.
IG_ARTX_page_mark_remove
Removes mark from ArtX page and destroys it.
IG_ARTX_page_marks_coord_type_set
Changes coordinate type of the specified mark on the page.
IG_ARTX_page_mark_select
Sets selection status of the annotation specified.
IG_ARTX_page_mark_selected_first
Returns handle of first selected annotation.
IG_ARTX_page_mark_selected_next
Returns handle of next selected annotation.
IG_ARTX_page_mark_send_to_back
Changes Z-order of marks on page. It sends the mark specified to the bottom of stack.
IG_ARTX_page_marks_flip
Flips all marks on the page according with value of nFlipValue parameter.
IG_ARTX_page_marks_remove
Removes all marks from the page.
IG_ARTX_page_marks_remove_array
Removes several marks from page.
IG_ARTX_page_marks_rotate
Rotates all marks on the page according with value of nRotateValue parameter.
IG_ARTX_page_marks_select
Sets selection status for all annotations on the page.
IG_ARTX_page_save
Saves ArtX page content to HIGEAR.
IG_ARTX_page_save_file
Saves ArtX page content to file.
IG_ARTX_page_undo_action_enable
Enables or disables recording of particular undo actions.
IG_ARTX_page_undo_action_is_enabled
Returns the state of undo actions recording of specified type.
IG_ARTX_page_undo_clear
Clears all records from undo action.
IG_ARTX_page_undo_count
Returns number of records in undo action list.
IG_ARTX_page_undo_enable
Enables or disables recording of undo actions.
IG_ARTX_page_undo_is_enabled
Returns current undo recording status.


IG_ARTX_page_apply_to_image

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_apply_to_image (
    HIG_ARTX_PAGE hArtPage,
    HIGEAR hIGear
);

Arguments:

hArtPage
ArtX page handle.
hIGear
Handle to the image to apply marks to.

Description:

This method applies all the image related marks from hArtPage to the specified hIGear.

NOTE: Currently only the Encryption mark is directly related to an image. This method encrypts areas of hIGear covered by all encryption marks from hArtPage.

Return Value:

Error count.


IG_ARTX_page_attr_get

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_attr_get(
    HIG_ARTX_PAGE hPage,
    enumIGArtXAttrPage nParam,
    LPVOID lpData,
    UINT nDataSize
);

Arguments:

hPage
ArtX page handle
nParam
Attribute to obtain. See enumIGArtXAttrPage description for more info.
lpData
Pointer to memory buffer to receive data requested.
nDataSize
Size of lpData memory buffer.

Description:

This function returns attributes of ArtX page.

Return Value:

Error count.


IG_ARTX_page_attr_set

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_attr_set(
    HIG_ARTX_PAGE hPage,
    enumIGArtXAttrPage nParam,
    LPVOID lpData,
    UINT nDataSize
);

Arguments:

hPage
ArtX page handle.
nParam
Attribute to change. See enumIGArtXAttrPage description for more info.
lpData
Pointer to memory buffer with new attribute value.
nDataSize
Size of lpData memory buffer.

Description:

This function modifies attributes of ArtX page.

Return Value:

Error count.


IG_ARTX_page_burn_in

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_page_burn_in(
    HIG_ARTX_PAGE hArtPage,
    LPAT_ARTX_DRAW_PARAMS lpDrawParams,
    LPAT_ARTX_BURNIN_PARAMS lpBurnParams
);

Arguments:

hArtPage
Page to burn in.
lpDrawParams
Draw parameters for burn in.
lpBurnParams
Burn in parameters.

Description:

This function merges marks permanently into hArtPage. They are converted from vector-format constructs into raster-format. The image may be temporarily promoted to a higher bit-depth for the purpose of the merge (see AT_ARTX_BURNIN_PARAMS). When doing burn-in, the image is converted to 24-bit.

Return Value:

Error count.


IG_ARTX_page_create

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_create(
    LPHIG_ARTX_PAGE lphArtPage
);

Arguments:

lphArtPage
ArtX page handle.

Description:

This function creates new blank ArtX page object.

Return Value:

Error count.


IG_ARTX_page_delete

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_delete(
    HIG_ARTX_PAGE hArtPage
);

Arguments:

hArtPage
ArtX page handle.

Description:

This function destroys specified ArtX page including all objects associated with this page.

Return Value:

Error count.


IG_ARTX_page_display_flip

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_page_display_flip(
    HIG_ARTX_PAGE hPage,
    enumIGFlipModes nMode
);

Arguments:

hPage
Page to flip.
nMode
Flip mode.

Description:

This function flips page's orientation.

Return Value:

Error count.


IG_ARTX_page_display_orientation_get

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_page_display_orientation_get(
    HIG_ARTX_PAGE hPage,
    enumIGOrientationModes *pMode
);

Arguments:

hPage
Page handle.
pMode
Page's orientation mode.

Description:

This function gets page's orientation.

Return Value:

Error count.


IG_ARTX_page_display_orientation_set

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_page_display_orientation_set(
    HIG_ARTX_PAGE hPage,
    enumIGOrientationModes nMode
);

Arguments:

hPage
ArtX page handle.
nMode
Page's orientation mode.

Description:

This function sets page's orientation.

Return Value:

Error count.


IG_ARTX_page_display_rotate

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_page_display_rotate(
    HIG_ARTX_PAGE hPage,
    enumIGRotationModes nMode
);

Arguments:

hPage
Page to rotate.
nMode
Rotation mode.

Description:

This function rotates page's orientation.

Return Value:

Error count.


IG_ARTX_page_group_add

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_group_add(
    HIG_ARTX_PAGE hPage,
    LPSTR lpszName,
    LPHIG_ARTX_GROUP lphGroup
);

Arguments:

hPage
ArtX page handle.
lpszName
Name of group to add.
lphGroup
Pointer to storage for function result. Output contains handle on created group. If group with the name specified already exists this function returns handle of existing group.

Description:

This function adds new group to ArtX page.

Return Value:

Error count.


IG_ARTX_page_group_at

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_group_at(
    HIG_ARTX_PAGE hPage,
    AT_INT nIdx,
    LPHIG_ARTX_GROUP lphGroup
);

Arguments:

hPage
ArtX page handle.
nIdx
Group index to get.
lphGroup
Pointer to storage for function result. An output contains handle of group requested or NULL if there is no group with this index number.

Description:

This function returns handle of group with index specified.

Return Value:

Error count.


IG_ARTX_page_group_count

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_group_count(
    HIG_ARTX_PAGE hPage,
    LPAT_INT lpnCount
);

Arguments:

hPage
ArtX page handle.
lpnCount
Pointer to storage for function result.

Description:

This function returns number of group on ArtX page specified.

Return Value:

Error count.


IG_ARTX_page_group_delete

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_group_delete(
    HIG_ARTX_PAGE hPage,
    HIG_ARTX_GROUP hGroup
);

Arguments:

hPage
ArtX page handle.
hGroup
Handle of the group to destroy.

Description:

This function deletes specified group from page and destroys all related group content.

Return Value:

Error count.


IG_ARTX_page_group_get

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_group_get(
    HIG_ARTX_PAGE hPage,
    LPSTR lpszGroupName,
    LPHIG_ARTX_GROUP lphGroup
);

Arguments:

hPage
ArtX page handle.
lpszGroupName
Name of the group to get.
lphGroup
Pointer to storage for function result. An output contains handle of group requested or NULL if there is no group with this index number.

Description:

This function returns handle of group with name specified.

Return Value:

Error count.


IG_ARTX_page_hit_test

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_page_hit_test(
    HIG_ARTX_PAGE hArtPage,
    LPAT_ARTX_DRAW_PARAMS lpDrawParams,
    LPAT_ARTX_HITTEST_PARAMS lpBurnParams
);

Arguments:

hArtPage
ArtX page handle
lpDrawParams
Draw parameters for hit test.
lpBurnParams
Hit test parameters.

Description:

This function checks if mouse poiner is on any mark on the page.

Return Value:

Error count.


IG_ARTX_page_load

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_load(
    HIG_ARTX_PAGE hArtPage,
    HIGEAR hIGear
    AT_BOOL bAppend
);

Arguments:

hArtPage
ArtX page handle
hIGear
Handle to the image page with annotations. It can be TIF or PDF page.
bAppend
When set to FALSE specifies that the current content of ArtX page is destroyed before annotation loading. Otherwise file content is to append ArtX page.

Description:

This function loads annotations from HIGEAR to the ArtX page.

Return Value:

Error count.


IG_ARTX_page_load_file

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_load_file(
    HIG_ARTX_PAGE hArtPage,
    LPSTR lpszFileName,
    AT_DWORD dwPageNumber,
    AT_BOOL bAppend
);

Arguments:

hArtPage
ArtX page handle.
lpszFileName
Name of file with annotations. It can be legacy Art2 data file of ArtX XML annotation storage.
dwPageNumber
Specifies annotation page number to load from multipage file.
bAppend
When set to FALSE specifies that current content of ArtX page is destroyed before annotation loading. Otherwise file content is to append ArtX page

Description:

This function loads annotations from file to the ArtX page specified.

Return Value:

Error count.


IG_ARTX_page_mark_add

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_add(
    HIG_ARTX_PAGE hArtPage,
    HIG_ARTX_MARK hMark,
    enumIGArtXCoordType nCoordType,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

hArtPage
ArtX page handle.
hMark
Handle of the mark to add.
nCoordType
Coordinate type of the mark on page. Please see enumIGArtXCoordType values.
lphMark
Pointer of mark object.

Description:

This function adds new mark to ArtX page. Mark will be added to default group (with zero index). Mark's coordinate system will be set to nCoordType value.

Return Value:

Error count.


IG_ARTX_page_mark_add_to_group_index

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_add_to_group_index(
    HIG_ARTX_PAGE hArtPage,
    HIG_ARTX_MARK hMark,
    enumIGArtXCoordType nCoordType,
    AT_INT nIndex,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

hArtPage
ArtX page handle.
hMark
Handle of the mark to add.
nCoordType
Coordinate type of the mark on page. Please see enumIGArtXCoordType values.
nIndex
Index of the group to add mark to.
lphMark
Pointer of mark object.

Description:

This function adds new mark to ArtX page. Mark will be added to group with the index specified. Mark's coordinate system will be set to nCoordType value.

Return Value:

Error count.


IG_ARTX_page_mark_add_to_group_name

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_add_to_group_name(
    HIG_ARTX_PAGE hArtPage,
    HIG_ARTX_MARK hMark,
    enumIGArtXCoordType nCoordType,
    LPSTR lpszName,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

hArtPage
ArtX page handle.
hMark
Handle of the mark to add.
nCoordType
Coordinate type of the mark on page. Please see enumIGArtXCoordType values.
lpszName
Name of the group to add mark to.
lphMark
Pointer of mark object.

Description:

This function adds new mark to ArtX page. Mark will be added to group with the name specified. If there is no such group on page it will be created firstly. Mark's coordinate system will be set to nCoordType value.

Return Value:

Error count.


IG_ARTX_page_mark_bring_to_front

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_bring_to_front(
    HIG_ARTX_PAGE hArtPage,
    HIG_ARTX_MARK hMark
);

Arguments:

hArtPage
ArtX page handle.
hMark
Handle of mark to change Z-order.

Description:

This function changes Z-order of marks on the page. It sends the mark specified to the top of stack.

Return Value:

Error count.


IG_ARTX_page_mark_coord_type_set

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_coord_type_set(
    HIG_ARTX_PAGE hArtPage,
    HIG_ARTX_MARK hMark,
    enumIGArtXCoordType nCoordType
);

Arguments:

hArtPage
ArtX page handle.
hMark
Handle of mark to modify.
nCoordType
Coordinate type value to set.

Description:

This function changes coordinate type of the specified mark on page.

Return Value:

Error count.


IG_ARTX_page_mark_first

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_first(
    HIG_ARTX_PAGE hPage,
    LPHIG_ARTX_MARK phMark
);

Arguments:

hPage
ArtX page handle.
phMark
Input/output parameter. If phMark represents valid annotation handle then this function call returns handle of the first annotation on the page.

Description:

This function is used to enumerate all annotations on the page. It returns handle of the first annotation.

Return Value:

Error count.


IG_ARTX_page_mark_is_selected

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_is_selected(
    HIG_ARTX_PAGE hPage,
    HIG_ARTX_MARK hMark,
    LPAT_BOOL lpbSelected
);

Arguments:

hPage
ArtX page handle.
hMark
Handle of annotation to check selection.
lpbSelected
Specifies where to place output result.

Description:

This function returns selection state of annotation specified.

Return Value:

Error count.


IG_ARTX_page_mark_is_valid

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_is_valid(
    HIG_ARTX_PAGE hArtPage,
    HIG_ARTX_MARK hMark,
    LPAT_BOOL pbValid
);

Arguments:

hArtPage
ArtX page handle.
hMark
Mark handle.
pbValid
Pointer to storage for function result.

Description:

This function validates that mark handle is valid on this page.

Return Value:

Error count.


IG_ARTX_page_mark_next

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_next(
    HIG_ARTX_PAGE hPage,
    LPHIG_ARTX_MARK phMark
);

Arguments:

hPage
ArtX page handle.
phMark
Input/output parameter. If *phMark represents valid annotation handle then this function call returns handle of next annotation on page

Description:

This function is used to enumerate all annotations on the page. It returns handle of the next annotation.

Return Value:

Error count.


IG_ARTX_page_mark_remove

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_remove(
    HIG_ARTX_PAGE hArtPage,
    HIG_ARTX_MARK hMark
);

Arguments:

hArtPage
ArtX page handle.
hMark
Handle of mark to remove.

Description:

This function removes mark from ArtX page and destroys it.

Return Value:

Error count.


IG_ARTX_page_marks_coord_type_set

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_coord_type_set(
    HIG_ARTX_PAGE hArtPage,
    HIG_ARTX_MARK hMark,
    enumIGArtXCoordType nCoordType
);

Arguments:

hArtPage
ArtX page handle.
hMark
Handle of the mark to be modified.
nCoordType
Coordinate type value to set.

Description:

This function changes coordinate type of the specified mark on the page.

Return Value:

Error count.


IG_ARTX_page_mark_select

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_select(
    HIG_ARTX_PAGE hPage,
    HIG_ARTX_MARK hMark,
    AT_BOOL bSelected
);

Arguments:

hPage
ArtX page handle.
hMark
handle of the annotation to select.
bSelected
Specifies annotation selection state to set.

Description:

This function sets selection status of the annotation specified.

Return Value:

Error count.


IG_ARTX_page_mark_selected_first

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_selected_first(
    HIG_ARTX_PAGE hPage,
    LPHIG_ARTX_MARK phMark
);

Arguments:

hPage
ArtX page handle.
phMark
Input/output parameter. If *phMark represents valid annotation handle then this function call returns handle of first selected annotation on the page.

Description:

This function is used to enumerate all selected annotations on page. It returns handle of first selected annotation.

Return Value:

Error count.


IG_ARTX_page_mark_selected_next

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_selected_next(
    HIG_ARTX_PAGE hPage,
    LPHIG_ARTX_MARK phMark
);

Arguments:

hPage
ArtX page handle.
phMark
Input/output parameter. If *phMark represents valid annotation handle then this function call returns handle of next selected annotation on the page.

Description:

This function is used to enumerate all selected annotations on page. It returns handle of next selected annotation.

Return Value:

Error count.


IG_ARTX_page_mark_send_to_back

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_mark_send_to_back(
    HIG_ARTX_PAGE hArtPage,
    HIG_ARTX_MARK hMark
);

Arguments:

hArtPage
ArtX page handle.
hMark
Handle of mark to change Z-order.

Description:

This function changes Z-order of marks on page. It sends the mark specified to the bottom of stack.

Return Value:

Error count.


IG_ARTX_page_marks_flip

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_marks_flip(
    HIG_ARTX_PAGE hArtPage,
    enumFlipValue nFlipValue,
    LPAT_RECTANGLE lprcImageRect,
    LPAT_RECTANGLE lprcDeviceRect
);

Arguments:

hArtPage
ArtX page handle.
nFlipValue
Specifies flip direction.
lprcImageRect
Specifies bounding rectangle to flip annotations specified in image coordinate system. Typically it can be image rectangle.
lprcDeviceRect
Specifies bounding rectangle to flip annotations specified in device coordinate system. Typically it can be windows client rectangle.

Description:

This function flips all marks on the page according with value of nFlipValue parameter. In contrast with IG_ARTX_page_display_flip () method it updates annotation coordinates. For text annotations (IG_ARTX_MARK_TEXT and similar), button and image (IG_ARTX_MARK_IMAGE and similar) it also updates mark orientation property.

Return Value:

Error count.


IG_ARTX_page_marks_remove

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_marks_remove(
    HIG_ARTX_PAGE hArtPage
);

Arguments:

hArtPage
ArtX page handle.

Description:

This function removes all marks from the page.

Return Value:

Error count.


IG_ARTX_page_marks_remove_array

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_marks_remove_array(
    HIG_ARTX_PAGE hArtPage,
    LPHIG_ARTX_MARK phMarkAray,
    AT_INT nCount
);

Arguments:

hArtPage
ArtX page handle.
phMarkAray
Array with handles of marks to remove.
nCount
Number of elements in phMarkAray array.

Description:

This function removes several marks from page.

Return Value:

Error count.


IG_ARTX_page_marks_rotate

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_marks_rotate(
    HIG_ARTX_PAGE hArtPage,
    enumRotateValue nRotateValue,
    LPAT_RECTANGLE lprcImageRect,
    LPAT_RECTANGLE lprcDeviceRect
);

Arguments:

hArtPage
ArtX page handle.
nRotateValue
Specifies rotation angle.
lprcImageRect
Specifies bounding rectangle to rotate annotations specified in image coordinate system. Typically it can be image rectangle.
lprcDeviceRect
Specifies bounding rectangle to rotate annotations specified in device coordinate system. Typically it can be windows client rectangle.

Description:

This function rotates all marks on the page according with value of nRotateValue parameter. In contrast with IG_ARTX_page_display_rotate () method it updates annotation coordinates. For text annotations (IG_ARTX_MARK_TEXT and similar), button and image (IG_ARTX_MARK_IMAGE and similar) it also updates mark orientation property.

Return Value:

Error count.


IG_ARTX_page_marks_select

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_marks_select(
    HIG_ARTX_PAGE hPage,
    AT_BOOL bSelected
);

Arguments:

hPage
ArtX page handle.
bSelected
Selection state to set.

Description:

This function sets selection status for all annotations on the page.

Return Value:

Error count.


IG_ARTX_page_save

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_save (
    HIG_ARTX_PAGE hArtPage,
    HIGEAR hIGear
);

Arguments:

hArtPage
ArtX page handle.
hIGear
Handle to the image page to save annotations to. It can be TIF or PDF page.

Description:

This function saves ArtX page content to HIGEAR.

Return Value:

Error count.


IG_ARTX_page_save_file

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_save_file(
    HIG_ARTX_PAGE hArtPage,
    LPSTR lpszFileName,
    AT_DWORD dwPageNumber,
    AT_BOOL nWriteMode,
    enumIGArtXSaveFormat nFormat
);

Arguments:

hArtPage
ArtX page handle.
lpszFileName
Output file name.
dwPageNumber
Number of pages in the multipage annotation file.
nWriteMode
Saving mode.
nFormat
Annotation format. See enumIGArtXSaveFormat description for more info.

Description:

This function saves ArtX page content to file.

Return Value:

Error count.


IG_ARTX_page_undo_action_enable

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_undo_action_enable(
    HIG_ARTX_PAGE hPage,
    enumIGArtXUndoAction nAction,
    AT_BOOL bState
);

Arguments:

hPage
ArtX page handle.
nAction
Action type to enable. See enumIGArtXUndoAction description for more info.
bState
When set to TRUE the action specified is enabled.

Description:

This function enables or disables recording of particular undo actions.

Return Value:

Error count.


IG_ARTX_page_undo_action_is_enabled

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_undo_action_is_enabled(
    HIG_ARTX_PAGE hPage,
    enumIGArtXUndoAction nAction,
    LPAT_BOOL pbState
);

Arguments:

hPage
ArtX page handle.
nAction
Action type to check. See enumIGArtXUndoAction description for more info.
pbState
Pointer to storage for function result.

Description:

This function returns the state of undo actions recording of specified type.

Return Value:

Error count.


IG_ARTX_page_undo_clear

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_undo_clear(
    HIG_ARTX_PAGE hPage
);

Arguments:

hPage
ArtX page handle.

Description:

This function clears all records from undo action.

Return Value:

Error count.


IG_ARTX_page_undo_count

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_undo_count(
    HIG_ARTX_PAGE hPage,
    LPUINT pnUndoCount
);

Arguments:

hPage
ArtX page handle.
pnUndoCount
Pointer to storage for the function result.

Description:

This function returns number of records in the undo action list.

Return Value:

Error count.


IG_ARTX_page_undo_enable

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_undo_enable(
    HIG_ARTX_PAGE hPage,
    AT_BOOL bState
);

Arguments:

hPage
ArtX page handle.
bState
When TRUE, enable undo recording and disable it otherwise.

Description:

This function enables or disables recording of undo actions.

Return Value:

Error count.


IG_ARTX_page_undo_is_enabled

Group: Page

Declaration:

AT_ERRCOUNT IG_ARTX_page_undo_is_enabled(
    HIG_ARTX_PAGE hPage,
    LPAT_BOOL pbState
);

Arguments:

hPage
ArtX page handle.
pbState
Pointer to storage for the function result.

Description:

This function returns current undo recording status.

Return Value:

Error count.


HIG_ARTX_PINUPTEXT

Type: Object

Description:

Legacy ART Pin-Up-Text mark.

Class Members:

IG_ARTX_text_pinup_bounds_get
Queries the bounding rectangle of annotation
IG_ARTX_text_pinup_bounds_set
Updates the bounding rectangle of annotation
IG_ARTX_text_pinup_boundswrap_get
Gets one or combination of enumIGArtXWrap values that specify text wrapping mode.
IG_ARTX_text_pinup_boundswrap_set
Sets one or combination of enumIGArtXWrap values that specify text wrapping mode.
IG_ARTX_text_pinup_create
Creates a new instance of Text annotation (IG_ARTX_MARK_PIN_UP_TEXT).
IG_ARTX_text_pinup_font_get
Queries annotation text font
IG_ARTX_text_pinup_font_set
Updates annotation text font
IG_ARTX_text_pinup_logfont_get
Queries annotation text font
IG_ARTX_text_pinup_logfont_set
Updates annotation text font
IG_ARTX_text_pinup_orientation_get
Queries value of annotation text orientation.
IG_ARTX_text_pinup_orientation_set
Sets the new value of annotation text orientation.
IG_ARTX_text_pinup_pin_get
Queries attributes of annotation pin.
IG_ARTX_text_pinup_pin_set
Sets annotation pin attributes.
IG_ARTX_text_pinup_text_get
Queries annotation text string
IG_ARTX_text_pinup_text_set
Updates annotation text string
IG_ARTX_text_pinup_textcolor_get
Queries annotation text color
IG_ARTX_text_pinup_textcolor_set
Updates annotation text color with new value


IG_ARTX_text_pinup_bounds_get

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_bounds_get(
    HIG_ARTX_TEXT_PINUP hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to storage for bounding rectangle

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_pinup_bounds_set

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_bounds_set(
    HIG_ARTX_TEXT_PINUP hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to new bounding rectangle

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_pinup_boundswrap_get

Group: Text Pinup

Declaration:

AT_ERRCOUNT IG_ARTX_text_pinup_boundswrap_get(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap* lpWrapMode
);

Arguments:

hMark
Annotation handle.
lpWrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Gets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_pinup_boundswrap_set

Group: Text Pinup

Declaration:

AT_ERRCOUNT IG_ARTX_text_pinup_boundswrap_set(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap WrapMode
);

Arguments:

hMark
Annotation handle.
WrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Sets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_pinup_create

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_create(
    LPAT_RECTANGLE pRectangle,
    LPSTR lpszText,
    LPAT_ARTX_FONT lpFont,
    LPAT_RGBQUAD pTextColor,
    LPAT_ARTX_PIN pTextPin,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

pRectangle
annotation bounding rectangle.
lpszText
text string drawn on annotation
lpFont
attributes of font to be used for text drawing
pTextColor
text color
pTextPin
attributes of pin icon to drawn over text annotation. NULL if no pin should be set
lphMark
pointer to storage for new annotation handle

Description:

This function creates a new instance of Text annotation (IG_ARTX_MARK_PIN_UP_TEXT).

Return Value:

Error count.


IG_ARTX_text_pinup_font_get

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_font_get(
    HIG_ARTX_TEXT_PINUP hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_pinup_font_set

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_font_set(
    HIG_ARTX_TEXT_PINUP hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_pinup_logfont_get

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_logfont_get(
    HIG_ARTX_TEXT_PINUP hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_pinup_logfont_set

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_logfont_set(
    HIG_ARTX_TEXT_PINUP hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_pinup_orientation_get

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_orientation_get(
    HIG_ARTX_TEXT_PINUP hMark,
    enumOrientModes* lpnOrientation
);

Arguments:

hMark
Annotation handle.
lpnOrientation
pointer to buffer for function result

Description:

This function queries value of annotation text orientation. See enumOrientModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_text_pinup_orientation_set

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_orientation_set(
    HIG_ARTX_TEXT_PINUP hMark,
    enumOrientModes nOrientation
);

Arguments:

hMark
Annotation handle.
nOrientation
new annotation text orientation value

Description:

This function sets value of annotation text orientation.

Return Value:

Error count.


IG_ARTX_text_pinup_pin_get

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_pin_get(
    HIG_ARTX_TEXT hMark,
    LPAT_ARTX_PIN lpPin,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpPin
pointer to storage for the annotation pin
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpPin parameter. On output it contains number of bytes copied to lpPin buffer.
If annotation has a pin then its attributes are copied into output buffer lpPin and number of bytes copied is placed into pnDataSize.
If lpPin is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_ARTX_PIN structure.
If lpPin is not NULL and pnDataSize is not NULL and there is no pin then on output pnDataSize contains zero.

Description:

This function queries attributes of annotation pin. See AT_ARTX_PIN structure for additional info.

Return Value:

Error count.


IG_ARTX_text_pinup_pin_set

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_pin_set(
    HIG_ARTX_TEXT hMark,
    LPAT_ARTX_PIN lpPin
);

Arguments:

hMark
Annotation handle.
lpPin
pointer to pin attributes structure. NULL value specifies that hMark annotation has no pin

Description:

This function sets annotation pin attributes.

Return Value:

Error count.


IG_ARTX_text_pinup_text_get

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_text_get(
    HIG_ARTX_TEXT_PINUP hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
pointer to buffer for output string
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If text attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store annotation text.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no text in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text string.

Return Value:

Error count.


IG_ARTX_text_pinup_text_set

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_text_set(
    HIG_ARTX_TEXT_PINUP hMark,
    LPSTR lpszTextBuffer
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
pointer to buffer with new annotation text. If lpszTextBuffer is NULL then annotation text attribute will be empty

Description:

This function updates annotation text string.

Return Value:

Error count.


IG_ARTX_text_pinup_textcolor_get

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_textcolor_get(
    HIG_ARTX_TEXT_PINUP hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to storage for the text color value
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.
If text color is specified for the annotation then it is copied into output buffer lpColor and number of bytes copied is placed into pnDataSize.
If lpColor is NULL and pnDataSize is not NULL then on output pnDataSize contains the size of AT_RGBQUAD structure.
If lpColor is not NULL and pnDataSize is not NULL and there is no text color in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text color.

Return Value:

Error count.


IG_ARTX_text_pinup_textcolor_set

Group: Pin Up Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pinup_textcolor_set(
    HIG_ARTX_TEXT_PINUP hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to new text color value. If lpColor is NULL then no text will be drawn on annotation

Description:

This function updates annotation text color with new value.

Return Value:

Error count.


HIG_ARTX_POLYGON

Type: Object

Description:

ART Polygon mark object.

Class Members:

IG_ARTX_polygon_border_get
Queries the annotation border.
IG_ARTX_polygon_border_set
Sets the annotation border.
IG_ARTX_polygon_bounds_get
Queries the bounding rectangle.
IG_ARTX_polygon_create
Creates Polygon mark.
IG_ARTX_polygon_fillcolor_get
Queries fill color of the annotation.
IG_ARTX_polygon_fillcolor_set
Sets the annotation fill color.
IG_ARTX_polygon_opacity_get
Queries the value of annotation opacity.
IG_ARTX_polygon_opacity_set
Sets the value of annotation opacity.
IG_ARTX_polygon_point_count_get
Gets the number of the Polygon points.
IG_ARTX_polygon_points_get
Gets the Polygon points.
IG_ARTX_polygon_points_set
Sets the Polygon points.


IG_ARTX_polygon_border_get

Group: Polygon

Declaration:

AT_ERRCOUNT IG_ARTX_polygon_border_get(
    HIG_ARTX_POLYGON hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
Pointer to storage for function result.

Description:

This function queries the annotation border.

Return Value:

Error count.


IG_ARTX_polygon_border_set

Group: Polygon

Declaration:

AT_ERRCOUNT IG_ARTX_polygon_border_set(
    HIG_ARTX_POLYGON hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
New border to be set.

Description:

This function sets the annotation border.

Return Value:

Error count.


IG_ARTX_polygon_bounds_get

Group: Polygon

Declaration:

AT_ERRCOUNT IG_ARTX_polygon_bounds_get(
    HIG_ARTX_POLYGON hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for function result.

Description:

This function queries the bounding rectangle.

Return Value:

Error count.


IG_ARTX_polygon_create

Group: Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_polygon_create(
    LPAT_POINT lpPoints,
    AT_DWORD nCount,
    LPAT_RGBQUAD prgbFillColor,
    LPAT_ARTX_BORDER pBorder,
    AT_INT nOpacity,
    LPHIG_ARTX_POLYGON lphMark
);

Arguments:

lpPoints
Points array.
nCount
Number of points.
prgbFillColor
Fill color of the mark.
pBorder
Border of the mark.
nOpacity
Opacity of the mark.
lphMark
Pointer to the created mark.

Description:

This function creates the Polygon mark.

Return Value:

Error count.


IG_ARTX_polygon_fillcolor_get

Group: Polygon

Declaration:

AT_ERRCOUNT IG_ARTX_polygon_fillcolor_get(
    HIG_ARTX_POLYGON hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to the storage of function result.

Description:

This function queries fill color of the annotation.

Return Value:

Error count.


IG_ARTX_polygon_fillcolor_set

Group: Polygon

Declaration:

AT_ERRCOUNT IG_ARTX_polygon_fillcolor_set(
    HIG_ARTX_POLYGON hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
New color of annotation to set.

Description:

This function sets the annotation fill color.

Return Value:

Error count.


IG_ARTX_polygon_opacity_get

Group: Polygon

Declaration:

AT_ERRCOUNT IG_ARTX_polygon_opacity_get(
    HIG_ARTX_POLYGON hMark,
    LPAT_INT lpnOpacity
);

Arguments:

hMark
Annotation handle.
lpnOpacity
Annotation's opacity.

Description:

This function queries the annotation opacity.

Return Value:

Error count.


IG_ARTX_polygon_opacity_set

Group: Polygon

Declaration:

AT_ERRCOUNT IG_ARTX_polygon_opacity_set(
    HIG_ARTX_POLYGON hMark,
    AT_INT nOpacity
);

Arguments:

hMark
Annotation handle.
nOpacity
New opacity value to set.

Description:

This function sets the new opacity of the mark.

Return Value:

Error count.


IG_ARTX_polygon_point_count_get

Group: Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_polygon_point_count_get(
    HIG_ARTX_POLYGON hMark,
    LPAT_INT lpnCount
);

Arguments:

hMark
Annotation handle.
lpnCount
The number of the mark's points.

Description:

This function gets the number of Polygon points.

Return Value:

Error count.


IG_ARTX_polygon_points_get

Group: Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_polygon_points_get(
    HIG_ARTX_POLYGON hMark,
    LPAT_POINT lpPoints,
    AT_DWORD nStart,
    AT_DWORD nCount
);

Arguments:

hMark
Annotation handle.
lpPoints
Pointer to the mark's points.
nStart
The start point.
nCount
The number of points.

Description:

This function gets the Polygon points.

Return Value:

Error count.


IG_ARTX_polygon_points_set

Group: Polygon

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_polygon_points_set(
    HIG_ARTX_POLYGON hMark,
    LPAT_POINT lpPoints,
    AT_DWORD nStart,
    AT_DWORD nCount
);

Arguments:

hMark
Annotation handle.
lpPoints
Pointer to the mark's points.
nStart
The start point of the mark.
nCount
The number of mark's points.

Description:

This function sets the Polygon points.

Return Value:

Error count.


HIG_ARTX_POLYLINE

Type: Object

Description:

ART Polyline mark.

Class Members:

IG_ARTX_polyline_bounds_get
Queries the bounding rectangle.
IG_ARTX_polyline_closed_get
Checks whether the polyline is closed.
IG_ARTX_polyline_closed_set
Updates the polyline closed attribute.
IG_ARTX_polyline_create
Creates polyline mark.
IG_ARTX_polyline_endhead_get
Queries the end head of the annotation.
IG_ARTX_polyline_endhead_set
Updates the end head of the annotation.
IG_ARTX_polyline_headfillcolor_get
Queries head fill color of the annotation.
IG_ARTX_polyline_headfillcolor_set
Updates the annotation head fill color.
IG_ARTX_polyline_line_get
Queries the annotation line attributes.
IG_ARTX_polyline_line_set
Updates the annotation line attributes.
IG_ARTX_polyline_opacity_get
Queries the value of annotation opacity.
IG_ARTX_polyline_opacity_set
Updates the value of annotation opacity.
IG_ARTX_polyline_point_count_get
Gets the number of polyline points.
IG_ARTX_polyline_points_get
Gets the polyline points.
IG_ARTX_polyline_points_set
Sets the polyline points.
IG_ARTX_polyline_starthead_get
Queries the start head of the annotation.
IG_ARTX_polyline_starthead_set
Updates the start head of the annotation.


IG_ARTX_polyline_bounds_get

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_bounds_get(
    HIG_ARTX_POLYLINE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to the storage for function result.

Description:

This function queries the bounding rectangle.

Return Value:

Error count.


IG_ARTX_polyline_closed_get

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_closed_get(
    HIG_ARTX_POLYLINE hMark,
    LPAT_BOOL lpbClosed
);

Arguments:

hMark
Annotation handle.
lpbClosed
TRUE - polyline is closed, FALSE - otherwise.

Description:

This function checks whether the polyline is closed.

Return Value:

Error count.


IG_ARTX_polyline_closed_set

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_closed_set(
    HIG_ARTX_POLYLINE hMark,
    AT_BOOL bClosed
);

Arguments:

hMark
Annotation handle.
bClosed
TRUE - polyline is closed, FALSE - otherwise.

Description:

This function updates the polyline closed attribute.

Return Value:

Error count.


IG_ARTX_polyline_create

Group: Polyline

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_polyline_create(
    LPAT_POINT lpPoints,
    AT_INT nNumOfPoints,
    LPAT_ARTX_BORDER pLine,
    LPAT_ARTX_ARROW_HEAD lpStartHead,
    LPAT_ARTX_ARROW_HEAD lpEndHead,
    LPAT_RGBQUAD pHeadFillColor,
    AT_BOOL bClosed,
    AT_INT nOpacity,
    LPHIG_ARTX_POLYLINE lphMark
);

Arguments:

lpPoints
Array of the mark's points.
nNumOfPoints
Number of the mark's points.
pLine
Line attributes.
lpStartHead
Start head of the mark.
lpEndHead
End head of the mark.
pHeadFillColor
Arrow head fill color.
bClosed
Closed attribute.
nOpacity
Opacity of the mark.
lphMark
Pointer to the created mark.

Description:

This function creates Polyline mark.

Return Value:

Error count.


IG_ARTX_polyline_endhead_get

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_endhead_get(
    HIG_ARTX_POLYLINE hMark,
    LPAT_ARTX_ARROW_HEAD lpHead
);

Arguments:

hMark
Annotation handle.
lpHead
Pointer to the storage for function result.

Description:

This function queries the end head of the annotation.

Return Value:

Error count.


IG_ARTX_polyline_endhead_set

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_endhead_set(
    HIG_ARTX_POLYLINE hMark,
    LPAT_ARTX_ARROW_HEAD lpHead
);

Arguments:

hMark
Annotation handle.
lpHead
Pointer to the end head to set.

Description:

This function updates the end head of the annotation.

Return Value:

Error count.


IG_ARTX_polyline_headfillcolor_get

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_headfillcolor_get(
    HIG_ARTX_POLYLINE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to the storage for function result.

Description:

This function queries head fill color of the annotation.

Return Value:

Error count.


IG_ARTX_polyline_headfillcolor_set

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_headfillcolor_set(
    HIG_ARTX_POLYLINE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
New color value to set.

Description:

This function updates the annotation head fill color.

Return Value:

Error count.


IG_ARTX_polyline_line_get

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_line_get(
    HIG_ARTX_POLYLINE hMark,
    LPAT_ARTX_BORDER lpLine
);

Arguments:

hMark
Annotation handle.
lpLine
Pointer to the storage for function result

Description:

This function queries the annotation line attributes.

Return Value:

Error count.


IG_ARTX_polyline_line_set

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_line_set(
    HIG_ARTX_POLYLINE hMark,
    LPAT_ARTX_BORDER lpLine
);

Arguments:

hMark
Annotation handle.
lpLine
New line attributes to set.

Description:

This function updates the annotation line attributes.

Return Value:

Error count.


IG_ARTX_polyline_opacity_get

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_opacity_get(
    HIG_ARTX_POLYLINE hMark,
    LPAT_INT lpnOpacity
);

Arguments:

hMark
Annotation handle.
lpnOpacity
Pointer to the storage for function result.

Description:

This function queries the value of annotation opacity.

Return Value:

Error count.


IG_ARTX_polyline_opacity_set

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_opacity_set(
    HIG_ARTX_POLYLINE hMark,
    AT_INT nOpacity
);

Arguments:

hMark
Annotation handle.
nOpacity
New opacity value to set.

Description:

This function updates the value of annotation opacity.

Return Value:

Error count.


IG_ARTX_polyline_point_count_get

Group: Polyline

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_polyline_point_count_get(
    HIG_ARTX_POLYLINE hMark,
    LPAT_INT lpnCount
);

Arguments:

hMark
Annotation handle.
lpnCount
The number of the mark's points.

Description:

This function gets the number of Polyline points.

Return Value:

Error count.


IG_ARTX_polyline_points_get

Group: Polyline

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_polyline_points_get(
    HIG_ARTX_POLYLINE hMark,
    LPAT_POINT lpPoints,
    AT_DWORD nStart,
    AT_DWORD nCount
);

Arguments:

hMark
Annotation handle.
lpPoints
Pointer to the annotation points.
nStart
The start point.
nCount
The number of annotation point.

Description:

This function gets the Polyline points.

Return Value:

Error count.


IG_ARTX_polyline_points_set

Group: Polyline

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_polyline_points_set(
    HIG_ARTX_POLYLINE hMark,
    LPAT_POINT lpPoints,
    AT_DWORD nStart,
    AT_DWORD nCount
);

Arguments:

hMark
Annotation handle.
lpPoints
Pointer to the annotation points.
nStart
The start point.
nCount
The number of annotation point.

Description:

This function sets the Polyline points.

Return Value:

Error count.


IG_ARTX_polyline_starthead_get

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_starthead_get(
    HIG_ARTX_POLYLINE hMark,
    LPAT_ARTX_ARROW_HEAD lpHead
);

Arguments:

hMark
Annotation handle.
lpHead
Pointer to the storage for function result.

Description:

This function queries the start head of the annotation.

Return Value:

Error count.


IG_ARTX_polyline_starthead_set

Group: Polyline

Declaration:

AT_ERRCOUNT IG_ARTX_polyline_starthead_set(
    HIG_ARTX_POLYLINE hMark,
    LPAT_ARTX_ARROW_HEAD lpHead
);

Arguments:

hMark
Annotation handle.
lpHead
Pointer to the head to set.

Description:

This function updates the start head of the annotation.

Return Value:

Error count.


HIG_ARTX_PROTRACTOR

Type: Object

Description:

ART Rectangle mark object.

Class Members:

IG_ARTX_protractor_arcradius_get
Queries the radius of arc displayed in protractor.
IG_ARTX_protractor_arcradius_set
Updates the radius of arc displayed in protractor.
IG_ARTX_protractor_aspectratio_get
Queries attributes protractor aspect ratio.
IG_ARTX_protractor_aspectratio_set
Updates attributes of protractor aspect ratio.
IG_ARTX_protractor_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_protractor_create
Creates a new instance of protractor annotation (IG_ARTX_MARK_PROTRACTOR).
IG_ARTX_protractor_endpoint_get
Queries annotation end point.
IG_ARTX_protractor_endpoint_set
Updates annotation end point position.
IG_ARTX_protractor_font_get
Queries annotation text font.
IG_ARTX_protractor_font_set
Updates annotation font.
IG_ARTX_protractor_headpoint_get
Queries arrow start point.
IG_ARTX_protractor_headpoint_set
Updates annotation start point position.
IG_ARTX_protractor_line_get
Queries attributes of line used to draw the annotation.
IG_ARTX_protractor_line_set
Sets attributes of line used to draw the annotation.
IG_ARTX_protractor_logfont_get
Queries annotation text font.
IG_ARTX_protractor_logfont_set
Updates button text font.
IG_ARTX_protractor_opacity_get
Queries the opacity value of annotation.
IG_ARTX_protractor_opacity_set
Sets the opacity value of annotation.
IG_ARTX_protractor_precision_get
Queries the precision of ruler length displayed.
IG_ARTX_protractor_precision_set
Updates the precision of protractor measurement displayed.
IG_ARTX_protractor_startpoint_get
Queries arrow start point.
IG_ARTX_protractor_startpoint_set
Updates arrow start point position.


IG_ARTX_protractor_arcradius_get

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_arcradius_get(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_INT lpnArcRadius
);

Arguments:

hMark
Annotation handle.
lpnArcRadius
Pointer to storage for function result.

Description:

This function queries the radius of arc displayed in protractor.

Return Value:

Error count.


IG_ARTX_protractor_arcradius_set

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_arcradius_set(
    HIG_ARTX_PROTRACTOR hMark,
    AT_INT nArcRadius
);

Arguments:

hMark
Annotation handle.
nArcRadius
Specifies new value of arc radius.

Description:

This function updates the radius of arc displayed in protractor.

Return Value:

Error count.


IG_ARTX_protractor_aspectratio_get

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_aspectratio_get(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_ARTX_ASPECTRATIO lpAspectRatio
);

Arguments:

hMark
Annotation handle.
lpAspectRatio
Pointer to storage for aspect ratio atributes structure.

Description:

This function queries attributes protractor aspect ratio. See AT_ARTX_ASPECTRATIO structure for additional info.

Return Value:

Error count.


IG_ARTX_protractor_aspectratio_set

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_aspectratio_set(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_ARTX_ASPECTRATIO lpAspectRatio
);

Arguments:

hMark
Annotation handle.
lpAspectRatio
Pointer to structure with new aspect ratio atributes.

Description:

This function updates attributes of protractor aspect ratio.

Return Value:

Error count.


IG_ARTX_protractor_bounds_get

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_bounds_get(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation. This is read-only property and calculated as biggest rectange that covers all points of annotation.

Return Value:

Error count.


IG_ARTX_protractor_create

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_create(
    LPAT_POINT lpPoints,
    LPAT_ARTX_BORDER pLine,
    LPAT_ARTX_ASPECTRATIO lpAspectRatio,
    AT_INT nArcRadius,
    AT_INT nPrecision,
    LPAT_ARTX_FONT lpFont,
    AT_INT nOpacity,
    LPHIG_ARTX_PROTRACTOR lphMark
);

Arguments:

lpPoints
Array of annotation points. Protractor consists of 3 points and lpPoints should contain 3 AT_POINT elements.
pLine
Attributes of line used to draw annotation.
lpAspectRatio
Structure with protractor aspectratio attributes.
nArcRadius
Specifies radius of protractor arc.
nPrecision
Specifies precision of protractor measurement output.
lpFont
Attributes of font to be used for protractor label drawing.
nOpacity
Annotation opacity value.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates a new instance of protractor annotation (IG_ARTX_MARK_PROTRACTOR).

Return Value:

Error count.


IG_ARTX_protractor_endpoint_get

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_endpoint_get(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_POINT lpPoint
);

Arguments:

hMark
Annotation handle.
lpPoint
Pointer to storage for function result.

Description:

This function queries annotation end point.

Return Value:

Error count.


IG_ARTX_protractor_endpoint_set

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_endpoint_set(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_POINT lpPoint
);

Arguments:

hMark
Annotation handle.
lpPoint
Pointer to new value of annotation end point.

Description:

This function updates annotation end point position.

Return Value:

Error count.


IG_ARTX_protractor_font_get

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_font_get(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_protractor_font_set

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_font_set(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to structure with new font atributes.

Description:

This function updates annotation font.

Return Value:

Error count.


IG_ARTX_protractor_headpoint_get

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_headpoint_get(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_POINT lpPoint
);

Arguments:

hMark
Annotation handle.
lpPoint
Pointer to storage for function result.

Description:

This function queries arrow start point.

Return Value:

Error count.


IG_ARTX_protractor_headpoint_set

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_headpoint_set(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_POINT lpPoint
);

Arguments:

hMark
Annotation handle.
lpPoint
Pointer to new value of annotation start point.

Description:

This function updates annotation start point position.

Return Value:

Error count.


IG_ARTX_protractor_line_get

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_line_get(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_ARTX_BORDER lpLine
);

Arguments:

hMark
Annotation handle.
lpLine
Pointer to storage for line atributes.

Description:

This function queries attributes of line used to draw the annotation. See AT_ARTX_BORDER structure for additional info.

Return Value:

Error count.


IG_ARTX_protractor_line_set

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_line_set(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_ARTX_BORDER lpData
);

Arguments:

hMark
Annotation handle.
lpData
Pointer to line attributes structure.

Description:

This function sets attributes of line used to draw the annotation.

Return Value:

Error count.


IG_ARTX_protractor_logfont_get

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_logfont_get(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_protractor_logfont_set

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_logfont_set(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to structure with new font atributes.

Description:

This function updates button text font.

Return Value:

Error count.


IG_ARTX_protractor_opacity_get

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_opacity_get(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_INT lpnOpacity
);

Arguments:

hMark
Annotation handle.
lpnOpacity
Pointer to storage for function result.

Description:

This function queries the opacity value of annotation.

Return Value:

Error count.


IG_ARTX_protractor_opacity_set

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_opacity_set(
    HIG_ARTX_PROTRACTOR hMark,
    AT_INT nOpacity
);

Arguments:

hMark
Annotation handle.
nOpacity
New opacity value to set.

Description:

This function sets the opacity value of annotation.

Return Value:

Error count.


IG_ARTX_protractor_precision_get

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_precision_get(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_INT lpnPrecision
);

Arguments:

hMark
Annotation handle.
lpnPrecision
Pointer to storage for function result.

Description:

This function queries the precision of ruler length displayed.

Return Value:

Error count.


IG_ARTX_protractor_precision_set

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_precision_set(
    HIG_ARTX_PROTRACTOR hMark,
    AT_INT nPrecision
);

Arguments:

hMark
Annotation handle.
nPrecision
Specifies new value of protractor precision.

Description:

This function updates the precision of protractor measurement displayed.

Return Value:

Error count.


IG_ARTX_protractor_startpoint_get

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_startpoint_get(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_POINT lpPoint
);

Arguments:

hMark
Annotation handle.
lpPoint
Pointer to storage for function result.

Description:

This function queries arrow start point.

Return Value:

Error count.


IG_ARTX_protractor_startpoint_set

Group: Protractor

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_protractor_startpoint_set(
    HIG_ARTX_PROTRACTOR hMark,
    LPAT_POINT lpPoint
);

Arguments:

hMark
Annotation handle.
lpPoint
Pointer to new value of arrow start point.

Description:

This function updates arrow start point position.

Return Value:

Error count.


HIG_ARTX_RECTANGLE

Type: Object

Description:

ART Rectangle mark object.

Class Members:

IG_ARTX_rectangle_border_get
Queries the annotation border.
IG_ARTX_rectangle_border_set
Updates the annotation border.
IG_ARTX_rectangle_bounds_get
Queries the bounding rectangle.
IG_ARTX_rectangle_bounds_set
Updates the bounding rectangle.
IG_ARTX_rectangle_create
Creates an instance of the Rectangle mark.
IG_ARTX_rectangle_fillcolor_get
Queries fill color of the annotation.
IG_ARTX_rectangle_fillcolor_set
Updates the annotation fill color.
IG_ARTX_rectangle_opacity_get
Queries the value of annotation opacity.
IG_ARTX_rectangle_opacity_set
Updates the value of annotation opacity.


IG_ARTX_rectangle_border_get

Group: Rectangle

Declaration:

AT_ERRCOUNT IG_ARTX_rectangle_border_get(
    HIG_ARTX_RECTANGLE hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
Pointer to the storage for function result.

Description:

This function queries the annotation border.

Return Value:

Error count.


IG_ARTX_rectangle_border_set

Group: Rectangle

Declaration:

AT_ERRCOUNT IG_ARTX_rectangle_border_set(
    HIG_ARTX_RECTANGLE hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
The new border to be set.

Description:

This function updates the annotation border.

Return Value:

Error count.


IG_ARTX_rectangle_bounds_get

Group: Rectangle

Declaration:

AT_ERRCOUNT IG_ARTX_rectangle_bounds_get(
    HIG_ARTX_RECTANGLE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to the storage for function result.

Description:

This function queries the bounding rectangle.

Return Value:

Error count.


IG_ARTX_rectangle_bounds_set

Group: Rectangle

Declaration:

AT_ERRCOUNT IG_ARTX_rectangle_bounds_set(
    HIG_ARTX_RECTANGLE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
New bounding rectangle to be set.

Description:

This function updates the bounding rectangle.

Return Value:

Error count.


IG_ARTX_rectangle_create

Group: Rectangle

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_rectangle_create(
    LPAT_RECTANGLE pRectangle,
    LPAT_RGBQUAD pFillColor,
    LPAT_ARTX_BORDER pBorder,
    AT_INT Opacity,
    LPHIG_ARTX_RECTANGLE lphMark
);

Arguments:

pRectangle
Bounding rectangle.
pFillColor
Fill color.
pBorder
Border of the Rectangle.
Opacity
Opacity of the mark.
lphMark
Pointer to the created mark.

Description:

This function creates an instance of mark Rectangle.

Return Value:

Error count.


IG_ARTX_rectangle_fillcolor_get

Group: Rectangle

Declaration:

AT_ERRCOUNT IG_ARTX_rectangle_fillcolor_get(
    HIG_ARTX_RECTANGLE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to the storage for function result.

Description:

This function queries fill color of the annotation.

Return Value:

Error count.


IG_ARTX_rectangle_fillcolor_set

Group: Rectangle

Declaration:

AT_ERRCOUNT IG_ARTX_rectangle_fillcolor_set(
    HIG_ARTX_RECTANGLE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
New color value to be set.

Description:

This function updates the annotation fill color.

Return Value:

Error count.


IG_ARTX_rectangle_opacity_get

Group: Rectangle

Declaration:

AT_ERRCOUNT IG_ARTX_rectangle_opacity_get(
    HIG_ARTX_RECTANGLE hMark,
    LPAT_INT lpnOpacity
);

Arguments:

hMark
Annotation handle.
lpnOpacity
Pointer to the storage for function result.

Description:

This function queries the value of the annotation opacity.

Return Value:

Error count.


IG_ARTX_rectangle_opacity_set

Group: Rectangle

Declaration:

AT_ERRCOUNT IG_ARTX_rectangle_opacity_set(
    HIG_ARTX_RECTANGLE hMark,
    AT_INT nOpacity
);

Arguments:

hMark
Annotation handle.
nOpacity
New opacity value to be set.

Description:

This function updates the value of annotation opacity.

Return Value:

Error count.


HIG_ARTX_REDACTION

Type: Object

Description:

Legacy ART Redaction mark.

Class Members:

IG_ARTX_redaction_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_redaction_bounds_set
Updates the bounding rectangle of annotation.
IG_ARTX_redaction_create
Creates an instance of redaction mark (IG_ARTX_MARK_REDACTION).
IG_ARTX_redaction_fillcolor_get
Queries filling color of annotation.
IG_ARTX_redaction_fillcolor_set
Updates annotation filling color.


IG_ARTX_redaction_bounds_get

Group: Redaction

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_redaction_bounds_get(
    HIG_ARTX_REDACTION hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_redaction_bounds_set

Group: Redaction

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_redaction_bounds_set(
    HIG_ARTX_REDACTION hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to new bounding rectangle.

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_redaction_create

Group: Redaction

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_redaction_create(
    LPAT_RECTANGLE pRectangle,
    LPAT_RGBQUAD pFillColor,
    LPHIG_ARTX_REDACTION lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
pFillColor
Annotation fill color.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates an instance of redaction mark (IG_ARTX_MARK_REDACTION).

Return Value:

Error count.


IG_ARTX_redaction_fillcolor_get

Group: Redaction

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_redaction_fillcolor_get(
    HIG_ARTX_REDACTION hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for the fill color value.

Description:

This function queries filling color of annotation.

Return Value:

Error count.


IG_ARTX_redaction_fillcolor_set

Group: Redaction

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_redaction_fillcolor_set(
    HIG_ARTX_REDACTION hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
New color value to set. If lpColor is NULL then black color (0,0,0) is assumed.

Description:

This function updates annotation filling color.

Return Value:

Error count.


HIG_ARTX_RICHTEXT

Type: Object

Description:

ART Rich Text mark.

Class Members:

IG_ARTX_richtext_border_get
Queries attributes of annotation border.
IG_ARTX_richtext_border_set
Sets annotation border attributes.
IG_ARTX_richtext_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_richtext_bounds_set
Updates the bounding rectangle of annotation.
IG_ARTX_richtext_create
Creates a new instance of rich text annotation (IG_ARTX_MARK_RICH_TEXT).
IG_ARTX_richtext_fillcolor_get
Queries annotation fill color.
IG_ARTX_richtext_fillcolor_set
Updates annotation fill color with new value.
IG_ARTX_richtext_opacity_get
Queries the opacity value of annotation.
IG_ARTX_richtext_opacity_set
Sets the opacity value of annotation.
IG_ARTX_richtext_text_get
Queries annotation text string. Note this is RTF text.
IG_ARTX_richtext_text_set
Updates annotation text.


IG_ARTX_richtext_border_get

Group: Rich Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_richtext_border_get(
    HIG_ARTX_RICHTEXT hMark,
    LPAT_ARTX_BORDER lpBorder,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpBorder
Pointer to storage for the annotation border.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpBorder parameter. On output it contains number of bytes copied to lpBorder buffer.
If arrow annotation has an arrow head then its attributes are copied into output buffer lpBorder and number of bytes copied is placed into pnDataSize.
If lpBorder is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_ARTX_BORDER structure.
If lpBorder is not NULL and pnDataSize is not NULL and there is no border then on output pnDataSize contains zero.

Description:

This function queries attributes of annotation border. See AT_ARTX_BORDER structure for additional info.

Return Value:

Error count.


IG_ARTX_richtext_border_set

Group: Rich Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_richtext_border_set(
    HIG_ARTX_RICHTEXT hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
Pointer to border attributes attributes structure. NULL value specifies that hMark annotation has no border.

Description:

This function sets annotation border attributes.

Return Value:

Error count.


IG_ARTX_richtext_bounds_get

Group: Rich Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_richtext_bounds_get(
    HIG_ARTX_RICHTEXT hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_richtext_bounds_set

Group: Rich Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_richtext_bounds_set(
    HIG_ARTX_RICHTEXT hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to new bounding rectangle.

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_richtext_create

Group: Rich Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_richtext_create(
    LPAT_RECTANGLE pRectangle,
    LPSTR lpszText,
    LPAT_ARTX_BORDER pBorder,
    LPAT_RGBQUAD pFillColor,
    AT_INT nOpacity,
    LPHIG_ARTX_RICHTEXT lphMark
);

Arguments:

pRectangle
Annotation bounding rectangle.
lpszText
Pointer to bufer with anottaion text (in RTF format).
pBorder
Attributes of annotation border or NULL if no border should be used.
pFillColor
Annotation fill color.
nOpacity
Annotation opacity value.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates a new instance of rich text annotation (IG_ARTX_MARK_RICH_TEXT).

Return Value:

Error count.


IG_ARTX_richtext_fillcolor_get

Group: Rich Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_richtext_fillcolor_get(
    HIG_ARTX_RICHTEXT hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to storage for the fill color value.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.
If fill color is specified for the annotation then it is copied into output buffer lpColor and number of bytes copied is placed into pnDataSize.
If lpColor is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_RGBQUAD structure.
If lpColor is not NULL and pnDataSize is not NULL and there is no fill color in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation fill color.

Return Value:

Error count.


IG_ARTX_richtext_fillcolor_set

Group: Rich Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_richtext_fillcolor_set(
    HIG_ARTX_RICHTEXT hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
Pointer to new fill color value. If lpColor is NULL then annotation internal area will not be filled.

Description:

This function updates annotation fill color with new value.

Return Value:

Error count.


IG_ARTX_richtext_opacity_get

Group: Rich Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_richtext_opacity_get(
    HIG_ARTX_RICHTEXT hMark,
    LPAT_INT lpnOpacity
);

Arguments:

hMark
Annotation handle.
lpnOpacity
Pointer to storage for function result.

Description:

This function queries the opacity value of annotation.

Return Value:

Error count.


IG_ARTX_richtext_opacity_set

Group: Rich Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_richtext_opacity_set(
    HIG_ARTX_RICHTEXT hMark,
    AT_INT nOpacity
);

Arguments:

hMark
Annotation handle.
nOpacity
New opacity value to set.

Description:

This function sets the opacity value of annotation.

Return Value:

Error count.


IG_ARTX_richtext_text_get

Group: Rich Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_richtext_text_get(
    HIG_ARTX_RICHTEXT hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer for output string.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If text attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store annotation text.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no text in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text string. Note this is RTF text.

Return Value:

Error count.


IG_ARTX_richtext_text_set

Group: Rich Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_richtext_text_set(
    HIG_ARTX_RICHTEXT hMark,
    LPSTR lpszTextBuffer
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer with new annotation text. If lpszTextBuffer is NULL then annotation text will be empty.

Description:

This function updates annotation text. lpszTextBuffer should be RTF text.

Return Value:

Error count.


HIG_ARTX_RULER

Type: Object

Description:

ART Ruler mark.

Class Members:

IG_ARTX_ruler_aspectratio_get
Queries attributes ruler aspect ratio.
IG_ARTX_ruler_aspectratio_set
Updates attributes of ruler aspect ratio.
IG_ARTX_ruler_bounds_get
Queries the bounding rectangle of annotation.
IG_ARTX_ruler_create
Creates a new instance of ruler annotation (IG_ARTX_MARK_RULER).
IG_ARTX_ruler_endline_length_get
Queries the length of ruler end point touch.
IG_ARTX_ruler_endline_length_set
Updates the length of ruler end point touch.
IG_ARTX_ruler_endpoint_get
Queries ruler end point.
IG_ARTX_ruler_endpoint_set
Updates ruler end point position.
IG_ARTX_ruler_font_get
Queries button text font.
IG_ARTX_ruler_font_set
Updates annotation font.
IG_ARTX_ruler_label_get
Queries annotation label string.
IG_ARTX_ruler_label_set
Updates annotation label.
IG_ARTX_ruler_line_get
Queries attributes of line used to draw the annotation.
IG_ARTX_ruler_line_set
Sets attributes of line used to draw the annotation.
IG_ARTX_ruler_logfont_get
Queries annotation text font.
IG_ARTX_ruler_logfont_set
Updates button text font.
IG_ARTX_ruler_opacity_get
Queries the opacity value of annotation.
IG_ARTX_ruler_opacity_set
Sets the opacity value of annotation.
IG_ARTX_ruler_precision_get
Queries the precision of ruler length displayed.
IG_ARTX_ruler_precision_set
Updates the precision of ruler length displayed.
IG_ARTX_ruler_startline_length_get
Queries the length of ruler start point touch.
IG_ARTX_ruler_startline_length_set
Updates the length of ruler start point touch.
IG_ARTX_ruler_startpoint_get
Queries ruler start point.
IG_ARTX_ruler_startpoint_set
Updates ruler start point position.


IG_ARTX_ruler_aspectratio_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_aspectratio_get(
    HIG_ARTX_RULER hMark,
    LPAT_ARTX_ASPECTRATIO lpAspectRatio
);

Arguments:

hMark
Annotation handle.
lpAspectRatio
Pointer to storage for aspect ratio atributes structure.

Description:

This function queries attributes ruler aspect ratio. See AT_ARTX_ASPECTRATIO structure for additional info.

Return Value:

Error count.


IG_ARTX_ruler_aspectratio_set

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_aspectratio_set(
    HIG_ARTX_RULER hMark,
    LPAT_ARTX_ASPECTRATIO lpAspectRatio
);

Arguments:

hMark
Annotation handle.
lpAspectRatio
Pointer to structure with new aspect ratio atributes.

Description:

This function updates attributes of ruler aspect ratio.

Return Value:

Error count.


IG_ARTX_ruler_bounds_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_bounds_get(
    HIG_ARTX_RULER hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
Pointer to storage for bounding rectangle.

Description:

This function queries the bounding rectangle of annotation. This is read-only property and calculated as biggest rectange that covers all points of annotation.

Return Value:

Error count.


IG_ARTX_ruler_create

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_create(
    LPAT_POINT lpPoints,
    LPAT_ARTX_BORDER pLine,
    LPAT_ARTX_ASPECTRATIO lpAspectRatio,
    AT_INT nStartLineLength,
    AT_INT nEndLineLength,
    AT_INT nPrecision,
    LPSTR lpszLabel,
    LPAT_ARTX_FONT logFont,
    AT_INT nOpacity,
    LPHIG_ARTX_RULER lphMark
);

Arguments:

lpPoints
Array of annotation points. Ruler consists of 2 points and so lpPoints should contains 2 AT_POINT elements.
pLine
Attributes of line used to draw annotation.
lpAspectRatio
Structure with ruler aspectratio attributes.
nStartLineLength
Specifies length of touch at start point of ruler.
nEndLineLength
Specifies length of touch at end point of ruler.
nPrecision
Specifies precision of ruler measurement.
lpszLabel
String used to create annotation label.
logFont
Attributes of font to be used for ruler label drawing.
nOpacity
Annotation opacity value.
lphMark
Pointer to storage for new annotation handle.

Description:

This function creates a new instance of ruler annotation (IG_ARTX_MARK_RULER).

Return Value:

Error count.


IG_ARTX_ruler_endline_length_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_endline_length_get(
    HIG_ARTX_RULER hMark,
    LPAT_INT lpnLength
);

Arguments:

hMark
Annotation handle.
lpnLength
Pointer to storage for function result.

Description:

This function queries the length of ruler end point touch.

Return Value:

Error count.


IG_ARTX_ruler_endline_length_set

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_endline_length_set(
    HIG_ARTX_RULER hMark,
    AT_INT nLength
);

Arguments:

hMark
Annotation handle.
nLength
Specifies new length of ruler end point touch.

Description:

This function updates the length of ruler end point touch.

Return Value:

Error count.


IG_ARTX_ruler_endpoint_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_endpoint_get(
    HIG_ARTX_RULER hMark,
    LPAT_POINT lpPoint
);

Arguments:

hMark
Annotation handle.
lpPoint
Pointer to storage for function result.

Description:

This function queries ruler end point.

Return Value:

Error count.


IG_ARTX_ruler_endpoint_set

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_endpoint_set(
    HIG_ARTX_RULER hMark,
    LPAT_POINT lpPoint
);

Arguments:

hMark
Annotation handle.
lpPoint
Pointer to new value of arrow start point.

Description:

This function updates ruler end point position.

Return Value:

Error count.


IG_ARTX_ruler_font_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_font_get(
    HIG_ARTX_RULER hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to storage for the text font value.

Description:

This function queries button text font.

Return Value:

Error count.


IG_ARTX_ruler_font_set

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_font_set(
    HIG_ARTX_RULER hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to structure with new font atributes.

Description:

This function updates annotation font.

Return Value:

Error count.


IG_ARTX_ruler_label_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_label_get(
    HIG_ARTX_RULER hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer for output string.
pnDataSize
Pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If text attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store annotation label.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no label in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation label string.

Return Value:

Error count.


IG_ARTX_ruler_label_set

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_label_set(
    HIG_ARTX_RULER hMark,
    LPSTR lpszTextBuffer
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
Pointer to buffer with new annotation label text. If lpszTextBuffer is NULL then label will be empty.

Description:

This function updates annotation label.

Return Value:

Error count.


IG_ARTX_ruler_line_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_line_get(
    HIG_ARTX_RULER hMark,
    LPAT_ARTX_BORDER lpLine
);

Arguments:

hMark
Annotation handle.
lpLine
Pointer to storage for line atributes.

Description:

This function queries attributes of line used to draw the annotation. See AT_ARTX_BORDER structure for additional info.

Return Value:

Error count.


IG_ARTX_ruler_line_set

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_line_set(
    HIG_ARTX_RULER hMark,
    LPAT_ARTX_BORDER lpData
);

Arguments:

hMark
Annotation handle.
lpData
Pointer to line attributes structure.

Description:

This function sets attributes of line used to draw the annotation.

Return Value:

Error count.


IG_ARTX_ruler_logfont_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_logfont_get(
    HIG_ARTX_RULER hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_ruler_logfont_set

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_logfont_set(
    HIG_ARTX_RULER hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
Pointer to structure with new font atributes.

Description:

This function updates button text font.

Return Value:

Error count.


IG_ARTX_ruler_opacity_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_opacity_get(
    HIG_ARTX_RULER hMark,
    LPAT_INT lpnOpacity
);

Arguments:

hMark
Annotation handle.
lpnOpacity
Pointer to storage for function result.

Description:

This function queries the opacity value of annotation.

Return Value:

Error count.


IG_ARTX_ruler_opacity_set

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_opacity_set(
    HIG_ARTX_RULER hMark,
    AT_INT nOpacity
);

Arguments:

hMark
Annotation handle.
nOpacity
New opacity value to set.

Description:

This function sets the opacity value of annotation.

Return Value:

Error count.


IG_ARTX_ruler_precision_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_precision_get(
    HIG_ARTX_RULER hMark,
    LPAT_INT lpnPrecision
);

Arguments:

hMark
Annotation handle.
lpnPrecision
Pointer to storage for function result.

Description:

This function queries the precision of ruler length displayed.

Return Value:

Error count.


IG_ARTX_ruler_precision_set

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_precision_set(
    HIG_ARTX_RULER hMark,
    AT_INT nPrecision
);

Arguments:

hMark
Annotation handle.
nPrecision
Specifies new value of ruler precision.

Description:

This function updates the precision of ruler length displayed.

Return Value:

Error count.


IG_ARTX_ruler_startline_length_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_startline_length_get(
    HIG_ARTX_RULER hMark,
    LPAT_INT lpnLength
);

Arguments:

hMark
Annotation handle.
lpnLength
Pointer to storage for function result.

Description:

This function queries the length of ruler start point touch.

Return Value:

Error count.


IG_ARTX_ruler_startline_length_set

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_startline_length_set(
    HIG_ARTX_RULER hMark,
    AT_INT nLength
);

Arguments:

hMark
Annotation handle.
nLength
Specifies new length of ruler start point touch.

Description:

This function updates the length of ruler start point touch.

Return Value:

Error count.


IG_ARTX_ruler_startpoint_get

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_startpoint_get(
    HIG_ARTX_RULER hMark,
    LPAT_POINT lpPoint
);

Arguments:

hMark
Annotation handle.
lpPoint
Pointer to storage for function result.

Description:

This function queries ruler start point.

Return Value:

Error count.


IG_ARTX_ruler_startpoint_set

Group: Ruler

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_ruler_startpoint_set(
    HIG_ARTX_RULER hMark,
    LPAT_POINT lpPoint
);

Arguments:

hMark
Annotation handle.
lpPoint
pointer to new value of arrow start point

Description:

This function updates ruler start point position.

Return Value:

Error count.


HIG_ARTX_TEXT

Type: Object

Description:

ART Text mark.

Class Members:

IG_ARTX_text_textalignment_get
queries value of annotation text alignment.
IG_ARTX_text_textalignment_set
sets value of annotation text alignment.
IG_ARTX_text_border_get
queries attributes of annotation border.
IG_ARTX_text_border_set
sets annotation border attributes.
IG_ARTX_text_bordershading_get
queries value of annotation border shading.
IG_ARTX_text_bordershading_set
sets value of annotation border shading.
IG_ARTX_text_bounds_get
queries the bounding rectangle of annotation
IG_ARTX_text_bounds_set
updates the bounding rectangle of annotation
IG_ARTX_text_boundswrap_get
queries the value of the boundswrap
IG_ARTX_text_boundswrap_set
sets the value of the boundswrap
IG_ARTX_text_callout_get
queries attributes of annotation callout.
IG_ARTX_text_callout_set
sets annotation callout attributes.
IG_ARTX_text_create
creates a new instance of Text annotation (IG_ARTX_MARK_TEXT).
IG_ARTX_text_fillcolor_get
queries annotation fill color
IG_ARTX_text_fillcolor_set
updates annotation fill color with new value
IG_ARTX_text_font_get
queries annotation text font
IG_ARTX_text_font_set
updates annotation text font
IG_ARTX_text_logfont_get
queries annotation text font
IG_ARTX_text_logfont_set
updates annotation text font
IG_ARTX_text_opacity_get
queries the opacity value of annotation
IG_ARTX_text_opacity_set
sets the opacity value of annotation
IG_ARTX_text_orientation_get
queries value of annotation text orientation.
IG_ARTX_text_orientation_set
sets the new value of annotation text orientation.
IG_ARTX_text_pin_get
queries attributes of annotation pin.
IG_ARTX_text_pin_set
sets annotation pin attributes.
IG_ARTX_text_text_get
queries annotation text string
IG_ARTX_text_text_set
updates annotation text string
IG_ARTX_text_textcolor_get
queries annotation text color
IG_ARTX_text_textcolor_set
updates annotation text color with new value
IG_ARTX_text_texttype_get
queries value of text type attribute.
IG_ARTX_text_texttype_set
sets the new value of annotation text orientation.


IG_ARTX_text_textalignment_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_textalignment_get(
    HIG_ARTX_TEXT hMark,
enumAlignModes* lpnAlign);

Arguments:

hMark
Annotation handle.
lpAlign
Pointer to buffer for function result

Description:

This function queries the value of annotation text alignment. See enumAlignModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_text_textalignment_set

Group: Text

Declaration

AT_ERRCOUNT ACCUAPI IG_ARTX_text_textalignment_set(
    HIG_ARTX_TEXT hMark,
    enumAlignModes nAlign
);

Arguments:

hMark
Annotation handle.
nOrientation
New annotation text alignment value

Description:

This function sets the value of annotation text alignment.

Return Value:

Error count.


IG_ARTX_text_border_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_border_get(
    HIG_ARTX_TEXT hMark,
    LPAT_ARTX_BORDER lpBorder,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpBorder
pointer to storage for the annotation border
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpBorder parameter. On output it contains number of bytes copied to lpBorder buffer.
If arrow annotation has an arrow head then its attributes are copied into output buffer lpBorder and number of bytes copied is placed into pnDataSize.
If lpBorder is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_ARTX_BORDER structure.
If lpBorder is not NULL and pnDataSize is not NULL and there is no border then on output pnDataSize contains zero.

Description:

This function queries attributes of annotation border. See AT_ARTX_BORDER structure for additional info.

Return Value:

Error count.


IG_ARTX_text_border_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_border_set(
    HIG_ARTX_TEXT hMark,
    LPAT_ARTX_BORDER lpBorder
);

Arguments:

hMark
Annotation handle.
lpBorder
pointer to border attributes attributes structure. NULL value specifies that hMark annotation has no border

Description:

This function sets annotation border attributes.

Return Value:

Error count.


IG_ARTX_text_bordershading_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_bordershading_get(
    HIG_ARTX_TEXT hMark,
    LPAT_BOOL lpbBorderShading
);

Arguments:

hMark
Annotation handle.
lpbBorderShading
pointer to buffer for function result

Description:

This function queries value of annotation border shading.

Return Value:

Error count.


IG_ARTX_text_bordershading_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_bordershading_set(
    HIG_ARTX_TEXT hMark,
    AT_BOOL bBorderShading
);

Arguments:

hMark
Annotation handle.
bBorderShading
new text border shading value

Description:

This function sets new value of annotation border shading.

Return Value:

Error count.


IG_ARTX_text_bounds_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_bounds_get(
    HIG_ARTX_TEXT hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to storage for bounding rectangle

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_bounds_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_bounds_set(
    HIG_ARTX_TEXT hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to new bounding rectangle

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_boundswrap_get

Group: Text

Declaration:

AT_ERRCOUNT IG_ARTX_text_boundswrap_get(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap* lpWrapMode
);

Arguments:

hMark
Annotation handle.
lpWrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Gets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_boundswrap_set

Group: Text

Declaration:

AT_ERRCOUNT IG_ARTX_text_boundswrap_set(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap WrapMode
);

Arguments:

hMark
Annotation handle.
WrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Sets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_callout_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_callout_get(
    HIG_ARTX_TEXT hMark,
    LPAT_ARTX_CALLOUT lpCallout,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpCallout
pointer to storage for the annotation callout
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpCallout parameter. On output it contains number of bytes copied to lpCallout buffer.
If annotation has an callout then its attributes are copied into output buffer lpCallout and number of bytes copied is placed into pnDataSize.
If lpCallout is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_ARTX_CALLOUT structure.
If lpCallout is not NULL and pnDataSize is not NULL and there is no callout then on output pnDataSize contains zero.

Description:

This function queries attributes of annotation callout. See AT_ARTX_CALLOUT structure for additional info.

Return Value:

Error count.


IG_ARTX_text_callout_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_callout_set(
    HIG_ARTX_TEXT hMark,
    LPAT_ARTX_CALLOUT lpCallout
);

Arguments:

hMark
Annotation handle.
lpCallout
pointer to callout attributes structure. NULL value specifies that hMark annotation has no callout

Description:

This function sets annotation callout attributes.

Return Value:

Error count.


IG_ARTX_text_create

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_create(
    LPAT_RECTANGLE pRectangle,
    LPSTR lpszText,
    enumIGArtXTextType nTextType,
    LPAT_ARTX_FONT lpFont,
    LPAT_ARTX_BORDER pBorder,
    AT_INT32 nBorderShading,
    LPAT_RGBQUAD pFillColor,
    LPAT_RGBQUAD pTextColor,
    AT_INT nOpacity,
    LPAT_ARTX_PIN pTextPin,
    LPAT_ARTX_CALLOUT pCallout,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

pRectangle
annotation bounding rectangle.
lpszText
text string to draw in annotation
nTextType
specifies the type of text
lpFont
attributes of font to be used for text drawing
pBorder
attributes of annotation border or NULL if no border should be used
nBorderShading
specifies the width of shadow border around annotation
pFillColor
annotation fill color
pTextColor
text color
nOpacity
annotation opacity value
pTextPin
attributes of pin icon to drawn over text annotation. NULL if no pin should be used
pCallout
attributes of callout to drawn with text annotation. NULL if no callout should be used
lphMark
pointer to storage for new annotation handle

Description:

This function creates a new instance of Text annotation (IG_ARTX_MARK_TEXT).

Return Value:

Error count.


IG_ARTX_text_fillcolor_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_fillcolor_get(
    HIG_ARTX_TEXT hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to storage for the fill color value
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.
If fill color is specified for the annotation then it is copied into output buffer lpColor and number of bytes copied is placed into pnDataSize.
If lpColor is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_RGBQUAD structure.
If lpColor is not NULL and pnDataSize is not NULL and there is no fill color in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation fill color.

Return Value:

Error count.


IG_ARTX_text_fillcolor_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_fillcolor_set(
    HIG_ARTX_TEXT hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to new fill color value. If lpColor is NULL then annotation internal area will not be filled

Description:

This function updates annotation fill color with new value.

Return Value:

Error count.


IG_ARTX_text_font_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_font_get(
    HIG_ARTX_TEXT hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_font_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_font_set(
    HIG_ARTX_TEXT hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_logfont_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_logfont_get(
    HIG_ARTX_TEXT hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_logfont_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_logfont_set(
    HIG_ARTX_TEXT hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_opacity_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_opacity_get(
    HIG_ARTX_TEXT hMark,
    LPAT_INT lpnOpacity
);

Arguments:

hMark
Annotation handle.
lpnOpacity
pointer to storage for function result

Description:

This function queries the opacity value of annotation.

Return Value:

Error count.


IG_ARTX_text_opacity_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_opacity_set(
    HIG_ARTX_TEXT hMark,
    AT_INT nOpacity
);

Arguments:

hMark
Annotation handle.
nOpacity
new Opacity value to set

Description:

This function sets the opacity value of annotation.

Return Value:

Error count.


IG_ARTX_text_orientation_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_orientation_get(
    HIG_ARTX_TEXT hMark,
    enumOrientModes* lpnOrientation
);

Arguments:

hMark
Annotation handle.
lpnOrientation
pointer to buffer for function result

Description:

This function queries value of annotation text orientation. See enumOrientModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_text_orientation_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_orientation_set(
    HIG_ARTX_TEXT hMark,
    enumOrientModes nOrientation
);

Arguments:

hMark
Annotation handle.
nOrientation
new annotation text orientation value

Description:

This function sets the new value of annotation text orientation.

Return Value:

Error count.


IG_ARTX_text_pin_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pin_get(
    HIG_ARTX_TEXT hMark,
    LPAT_ARTX_PIN lpPin,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpPin
pointer to storage for the annotation pin
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpPin parameter. On output it contains number of bytes copied to lpPin buffer.
If annotation has a pin then its attributes are copied into output buffer lpPin and number of bytes copied is placed into pnDataSize.
If lpPin is NULL and pnDataSize is not NULL than on output pnDataSize contains the size of AT_ARTX_PIN structure.
If lpPin is not NULL and pnDataSize is not NULL and there is no pin then on output pnDataSize contains zero.

Description:

This function queries attributes of annotation pin. See AT_ARTX_PIN structure for additional info.

Return Value:

Error count.


IG_ARTX_text_pin_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_pin_set(
    HIG_ARTX_TEXT hMark,
    LPAT_ARTX_PIN lpPin
);

Arguments:

hMark
Annotation handle.
lpPin
pointer to pin attributes structure. NULL value specifies that hMark annotation has no pin

Description:

This function sets annotation pin attributes.

Return Value:

Error count.


IG_ARTX_text_text_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_text_get(
    HIG_ARTX_TEXT hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
pointer to buffer for output string
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If text attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store annotation text.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no text in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text string.

Return Value:

Error count.


IG_ARTX_text_text_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_text_set(
    HIG_ARTX_TEXT hMark,
    LPSTR lpszTextBuffer
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
pointer to buffer with new annotation text. If lpszTextBuffer is NULL then annotation text attribute will be empty

Description:

This function updates annotation text string.

Return Value:

Error count.


IG_ARTX_text_textcolor_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_textcolor_get(
    HIG_ARTX_TEXT hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to storage for the text color value
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.
If text color is specified for the annotation then it is copied into output buffer lpColor and number of bytes copied is placed into pnDataSize.
If lpColor is NULL and pnDataSize is not NULL then on output pnDataSize contains the size of AT_RGBQUAD structure.
If lpColor is not NULL and pnDataSize is not NULL and there is no text color in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text color.

Return Value:

Error count.


IG_ARTX_text_textcolor_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_textcolor_set(
    HIG_ARTX_TEXT hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to new text color value. If lpColor is NULL then no text will be drawn

Description:

This function updates annotation text color with new value.

Return Value:

Error count.


IG_ARTX_text_texttype_get

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_texttype_get(
    HIG_ARTX_TEXT hMark,
    enumIGArtXTextType* lpnTextType
);

Arguments:

hMark
Annotation handle.
lpnTextType
pointer to buffer for function result

Description:

This function queries value of text type attribute. See enumIGArtXTextType enum description for additional info.

Return Value:

Error count.


IG_ARTX_text_texttype_set

Group: Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_texttype_set(
    HIG_ARTX_TEXT hMark,
    enumIGArtXTextType nTextType
);

Arguments:

hMark
Annotation handle.
nTextType
new text type value

Description:

This function sets the new value of text type attribute. See enumIGArtXTextType enum description for additional info

Return Value:

Error count.


HIG_ARTX_TEXTFROMFILE

Type: Object

Description:

Legacy ART "Text From File" mark.

Class Members:

IG_ARTX_text_from_file_bounds_get
queries the bounding rectangle of annotation
IG_ARTX_text_from_file_bounds_set
updates the bounding rectangle of annotation
IG_ARTX_text_from_file_boundswrap_get
queries the boundswrap setting
IG_ARTX_text_from_file_boundswrap_set
sets the boundswrap setting
IG_ARTX_text_from_file_create
creates a new instance of Text-from_file annotation (IG_ARTX_MARK_TEXT_FROM_FILE).
IG_ARTX_text_from_file_font_get
queries annotation text font
IG_ARTX_text_from_file_font_set
updates annotation text font
IG_ARTX_text_from_file_logfont_get
queries annotation text font
IG_ARTX_text_from_file_logfont_set
updates annotation text font
IG_ARTX_text_from_file_orientation_get
queries value of annotation text orientation.
IG_ARTX_text_from_file_orientation_set
sets new value of annotation text orientation.
IG_ARTX_text_from_file_text_get
queries annotation text string
IG_ARTX_text_from_file_text_set
updates annotation text string
IG_ARTX_text_from_file_textcolor_get
queries annotation text color
IG_ARTX_text_from_file_textcolor_set
updates annotation text color with new value


IG_ARTX_text_from_file_bounds_get

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_bounds_get(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to storage for bounding rectangle

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_from_file_bounds_set

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_bounds_set(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to new bounding rectangle

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_from_file_boundswrap_get

Group: Text from file

Declaration:

AT_ERRCOUNT IG_ARTX_text_from_file_boundswrap_get(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap* lpWrapMode
);

Arguments:

hMark
Annotation handle.
lpWrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Gets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_from_file_boundswrap_set

Group: Text from file

Declaration:

AT_ERRCOUNT IG_ARTX_text_from_file_boundswrap_set(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap WrapMode
);

Arguments:

hMark
Annotation handle.
WrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Sets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_from_file_create

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_create(
    LPAT_RECTANGLE	pRectangle,
    LPSTR				lpszText,
    LPAT_ARTX_FONT		lpFont,
    LPAT_RGBQUAD		pTextColor,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

pRectangle
annotation bounding rectangle.
lpszText
text string specifying FileName with text to draw
lpFont
attributes of font to be used for text drawing
pTextColor
text color
lphMark
pointer to storage for new annotation handle

Description:

This function creates a new instance of Text-from_file annotation (IG_ARTX_MARK_TEXT_FROM_FILE).

Return Value:

Error count.


IG_ARTX_text_from_file_font_get

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_font_get(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_from_file_font_set

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_font_set(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_from_file_logfont_get

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_logfont_get(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_from_file_logfont_set

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_logfont_set(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_from_file_orientation_get

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_orientation_get(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    enumOrientModes* lpnOrientation
);

Arguments:

hMark
Annotation handle.
lpnOrientation
pointer to buffer for function result

Description:

This function queries value of annotation text orientation. See enumOrientModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_text_from_file_orientation_set

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_orientation_set(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    enumOrientModes nOrientation
);

Arguments:

hMark
Annotation handle.
nOrientation
new annotation text orientation value

Description:

This function sets the new value of annotation text orientation.

Return Value:

Error count.


IG_ARTX_text_from_file_text_get

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_text_get(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
pointer to buffer for output string
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If text attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store annotation text.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no text in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text string.

Return Value:

Error count.


IG_ARTX_text_from_file_text_set

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_text_set(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    LPSTR lpszTextBuffer
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
pointer to buffer with new annotation text. If lpszTextBuffer is NULL then annotation text attribute will be empty

Description:

This function updates annotation text string.

Return Value:

Error count.


IG_ARTX_text_from_file_textcolor_get

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_textcolor_get(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to storage for the text color value
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.
If text color is specified for the annotation then it is copied into output buffer lpColor and number of bytes copied is placed into pnDataSize.
If lpColor is NULL and pnDataSize is not NULL then on output pnDataSize contains the size of AT_RGBQUAD structure.
If lpColor is not NULL and pnDataSize is not NULL and there is no text color in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text color.

Return Value:

Error count.


IG_ARTX_text_from_file_textcolor_set

Group: Text From File

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_from_file_textcolor_set(
    HIG_ARTX_TEXT_FROM_FILE hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to new text color value. If lpColor is NULL then no text will be drawn on annotation

Description:

This function updates annotation text color with new value.

Return Value:

Error count.


HIG_ARTX_TEXTSTAMP

Type: Object

Description:

Legacy ART "Text Stamp" mark.

Class Members:

IG_ARTX_text_stamp_bounds_get
queries the bounding rectangle of annotation
IG_ARTX_text_stamp_bounds_set
updates the bounding rectangle of annotation
IG_ARTX_text_stamp_boundswrap_get
queries the boundswrap of annotation
IG_ARTX_text_stamp_boundswrap_set
updates the boundswrap of annotation
IG_ARTX_text_stamp_create
creates a new instance of Text-from_file annotation (IG_ARTX_MARK_TEXT_FROM_FILE).
IG_ARTX_text_stamp_font_get
queries annotation text font
IG_ARTX_text_stamp_font_set
updates annotation text font
IG_ARTX_text_stamp_logfont_get
queries annotation text font
IG_ARTX_text_stamp_logfont_set
updates annotation text font
IG_ARTX_text_stamp_orientation_get
queries value of annotation text orientation.
IG_ARTX_text_stamp_orientation_set
sets new value of annotation text orientation.
IG_ARTX_text_stamp_text_get
queries annotation text string
IG_ARTX_text_stamp_text_set
updates annotation text string
IG_ARTX_text_stamp_textcolor_get
queries annotation text color
IG_ARTX_text_stamp_textcolor_set
updates annotation text color with new value


IG_ARTX_text_stamp_bounds_get

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_bounds_get(
    HIG_ARTX_TEXT_STAMP hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to storage for bounding rectangle

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_stamp_bounds_set

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_bounds_set(
    HIG_ARTX_TEXT_STAMP hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to new bounding rectangle

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_stamp_boundswrap_get

Group: Text Stamp

Declaration:

AT_ERRCOUNT IG_ARTX_text_stamp_boundswrap_get(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap* lpWrapMode
);

Arguments:

hMark
Annotation handle.
lpWrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Gets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_stamp_boundswrap_set

Group: Text Stamp

Declaration:

AT_ERRCOUNT IG_ARTX_text_stamp_boundswrap_set(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap WrapMode
);

Arguments:

hMark
Annotation handle.
WrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Sets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_stamp_create

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_create(
    LPAT_RECTANGLE pRectangle,
    LPSTR lpszText,
    LPAT_ARTX_FONT lpFont,
    LPAT_RGBQUAD pTextColor,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

pRectangle
annotation bounding rectangle.
lpszText
text string specifying FileName with text to draw
lpFont
attributes of font to be used for text drawing
pTextColor
text color
lphMark
pointer to storage for new annotation handle

Description:

This function creates a new instance of Text-from_file annotation (IG_ARTX_TEXT_STAMP).

Return Value:

Error count.


IG_ARTX_text_stamp_font_get

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_font_get(
    HIG_ARTX_TEXT_STAMP hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_stamp_font_set

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_font_set(
    HIG_ARTX_TEXT_STAMP hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_stamp_logfont_get

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_logfont_get(
    HIG_ARTX_TEXT_STAMP hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_stamp_logfont_set

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_logfont_set(
    HIG_ARTX_TEXT_STAMP hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_stamp_orientation_get

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_orientation_get(
    HIG_ARTX_TEXT_STAMP hMark,
    enumOrientModes* lpnOrientation
);

Arguments:

hMark
Annotation handle.
lpnOrientation
pointer to buffer for function result

Description:

This function queries value of annotation text orientation. See enumOrientModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_text_stamp_orientation_set

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_orientation_set(
    HIG_ARTX_TEXT_STAMP hMark,
    enumOrientModes nOrientation
);

Arguments:

hMark
Annotation handle.
nOrientation
new annotation text orientation value

Description:

This function sets the new value of annotation text orientation.

Return Value:

Error count.


IG_ARTX_text_stamp_text_get

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_text_get(
    HIG_ARTX_TEXT_STAMP hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
pointer to buffer for output string
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If text attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store annotation text.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no text in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text string.

Return Value:

Error count.


IG_ARTX_text_stamp_text_set

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_text_set(
    HIG_ARTX_TEXT_STAMP hMark,
    LPSTR lpszTextBuffer
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
pointer to buffer with new annotation text. If lpszTextBuffer is NULL then annotation text attribute will be empty

Description:

This function updates annotation text string.

Return Value:

Error count.


IG_ARTX_text_stamp_textcolor_get

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_textcolor_get(
    HIG_ARTX_TEXT_STAMP hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to storage for the text color value
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.
If text color is specified for the annotation then it is copied into output buffer lpColor and number of bytes copied is placed into pnDataSize.
If lpColor is NULL and pnDataSize is not NULL then on output pnDataSize contains the size of AT_RGBQUAD structure.
If lpColor is not NULL and pnDataSize is not NULL and there is no text color in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text color.

Return Value:

Error count.


IG_ARTX_text_stamp_textcolor_set

Group: Text Stamp

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_stamp_textcolor_set(
    HIG_ARTX_TEXT_STAMP hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to new text color value. If lpColor is NULL then no text will be drawn on annotation

Description:

This function updates annotation text color with new value.

Return Value:

Error count.


HIG_ARTX_TYPEDTEXT

Type: Object

Description:

Legacy ART "Typed Text" mark.

Class Members:

IG_ARTX_text_typed_bounds_get
queries the bounding rectangle of annotation
IG_ARTX_text_typed_bounds_set
updates the bounding rectangle of annotation
IG_ARTX_text_typed_boundswrap_get
queries the boundswrap of annotation
IG_ARTX_text_typed_boundswrap_set
updates the boundswrap of annotation
IG_ARTX_text_typed_create
creates a new instance of Text-from_file annotation (IG_ARTX_MARK_TEXT_FROM_FILE).
IG_ARTX_text_typed_font_get
queries annotation text font
IG_ARTX_text_typed_font_set
updates annotation text font
IG_ARTX_text_typed_logfont_get
queries annotation text font
IG_ARTX_text_typed_logfont_set
updates annotation text font
IG_ARTX_text_typed_orientation_get
queries value of annotation text orientation.
IG_ARTX_text_typed_orientation_set
sets new value of annotation text orientation.
IG_ARTX_text_typed_text_get
queries annotation text string
IG_ARTX_text_typed_text_set
updates annotation text string
IG_ARTX_text_typed_textcolor_get
queries annotation text color
IG_ARTX_text_typed_textcolor_set
updates annotation text color with new value


IG_ARTX_text_typed_bounds_get

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_bounds_get(
    HIG_ARTX_TEXT_TYPED hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to storage for bounding rectangle

Description:

This function queries the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_typed_bounds_set

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_bounds_set(
    HIG_ARTX_TEXT_TYPED hMark,
    LPAT_RECTANGLE lpRect
);

Arguments:

hMark
Annotation handle.
lpRect
pointer to new bounding rectangle

Description:

This function updates the bounding rectangle of annotation.

Return Value:

Error count.


IG_ARTX_text_typed_boundswrap_get

Group: Typed Text

Declaration:

AT_ERRCOUNT IG_ARTX_text_typed_boundswrap_get(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap* lpWrapMode
);

Arguments:

hMark
Annotation handle.
lpWrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Gets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_typed_boundswrap_set

Group: Typed Text

Declaration:

AT_ERRCOUNT IG_ARTX_text_typed_boundswrap_set(
    HIG_ARTX_TEXT hMark,
    enumIGArtXWrap WrapMode
);

Arguments:

hMark
Annotation handle.
WrapMode
Wrap mode - of type enumIGArtXWrap.

Description:

Sets one or combination of enumIGArtXWrap values that specify text wrapping mode.

Return Value:

Error count.


IG_ARTX_text_typed_create

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_create(
    LPAT_RECTANGLE pRectangle,
    LPSTR lpszText,
    LPAT_ARTX_FONT lpFont,
    LPAT_RGBQUAD pTextColor,
    LPHIG_ARTX_MARK lphMark
);

Arguments:

pRectangle
annotation bounding rectangle.
lpszText
text string specifying FileName with text to draw
lpFont
attributes of font to be used for text drawing
pTextColor
text color
lphMark
pointer to storage for new annotation handle

Description:

This function creates a new instance of Text-from_file annotation (IG_ARTX_TEXT_TYPED).

Return Value:

Error count.


IG_ARTX_text_typed_font_get

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_font_get(
    HIG_ARTX_TEXT_TYPED hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_typed_font_set

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_font_set(
    HIG_ARTX_TEXT_TYPED hMark,
    LPAT_ARTX_FONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_typed_logfont_get

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_logfont_get(
    HIG_ARTX_TEXT_TYPED hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to storage for the text font value.

Description:

This function queries annotation text font.

Return Value:

Error count.


IG_ARTX_text_typed_logfont_set

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_logfont_set(
    HIG_ARTX_TEXT_TYPED hMark,
    LPAT_LOGFONT lpFont
);

Arguments:

hMark
Annotation handle.
lpFont
pointer to structure with new font atributes

Description:

This function updates annotation text font.

Return Value:

Error count.


IG_ARTX_text_typed_orientation_get

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_orientation_get(
    HIG_ARTX_TEXT_TYPED hMark,
    enumOrientModes* lpnOrientation
);

Arguments:

hMark
Annotation handle.
lpnOrientation
pointer to buffer for function result

Description:

This function queries value of annotation text orientation. See enumOrientModes enum description for additional info.

Return Value:

Error count.


IG_ARTX_text_typed_orientation_set

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_orientation_set(
    HIG_ARTX_TEXT_TYPED hMark,
    enumOrientModes nOrientation
);

Arguments:

hMark
Annotation handle.
nOrientation
new annotation text orientation value

Description:

This function sets the new value of annotation text orientation.

Return Value:

Error count.


IG_ARTX_text_typed_text_get

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_text_get(
    HIG_ARTX_TEXT_TYPED hMark,
    LPSTR lpszTextBuffer,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
pointer to buffer for output string
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpszTextBuffer parameter. On output it contains number of bytes copied to lpszTextBuffer buffer.
If text attribute is not empty in the annotation then it is copied into output buffer lpszTextBuffer and number of bytes copied is placed into pnDataSize.
If lpszTextBuffer is NULL and pnDataSize is not NULL then on output pnDataSize contains the size required to store annotation text.
If lpszTextBuffer is not NULL and pnDataSize is not NULL and there is no text in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text string.

Return Value:

Error count.


IG_ARTX_text_typed_text_set

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_text_set(
    HIG_ARTX_TEXT_TYPED hMark,
    LPSTR lpszTextBuffer
);

Arguments:

hMark
Annotation handle.
lpszTextBuffer
pointer to buffer with new annotation text. If lpszTextBuffer is NULL then annotation text attribute will be empty

Description:

This function updates annotation text string.

Return Value:

Error count.


IG_ARTX_text_typed_textcolor_get

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_textcolor_get(
    HIG_ARTX_TEXT_TYPED hMark,
    LPAT_RGBQUAD lpColor,
    LPAT_UINT pnDataSize
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to storage for the text color value
pnDataSize
pointer to the variable that on input contains size of buffer specified by lpColor parameter. On output it contains number of bytes copied to lpColor buffer.
If text color is specified for the annotation then it is copied into output buffer lpColor and number of bytes copied is placed into pnDataSize.
If lpColor is NULL and pnDataSize is not NULL then on output pnDataSize contains the size of AT_RGBQUAD structure.
If lpColor is not NULL and pnDataSize is not NULL and there is no text color in the annotation then on output pnDataSize contains zero.

Description:

This function queries annotation text color.

Return Value:

Error count.


IG_ARTX_text_typed_textcolor_set

Group: Typed Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_ARTX_text_typed_textcolor_set(
    HIG_ARTX_TEXT_TYPED hMark,
    LPAT_RGBQUAD lpColor
);

Arguments:

hMark
Annotation handle.
lpColor
pointer to new text color value. If lpColor is NULL then no text will be drawn on annotation

Description:

This function updates annotation text color with new value.

Return Value:

Error count.


ArtX GUI Reference

Type: Object

Description:

ARTX GUI handle.

Class Members:

IG_ARTX_GUI_cursor_get
Gets handle to current mouse cursor.
IG_ARTX_GUI_mode_get
Gets the current display mode of the ArtX GUI.
IG_ARTX_GUI_mode_set
Changes the display mode of the ArtX GUI.
IG_ARTX_GUI_mouse_down
Handles the MouseDown event.
IG_ARTX_GUI_mouse_move
Handles the MouseMove event.
IG_ARTX_GUI_mouse_up
Handles the MouseUp event.
IG_ARTX_GUI_page_set
Sets the ArX Page that ArtX GUI is to be connected to.
IG_ARTX_GUI_register_hotspot_action
Registers a callback function that will be called from the ArtX GUI when a user clicks on a hotspot mark.
IG_ARTX_GUI_show_attributes
Shows a property sheet for a given mark.
IG_ARTX_GUI_toolbar_version_get
Gets the version of the GUI toolbar.
IG_ARTX_GUI_toolbar_version_set
Changes the version of the GUI toolbar.
IG_ARTX_GUI_toolbar_visible_get
Gets the visible state of the GUI toolbar.
IG_ARTX_GUI_toolbar_visible_set
Changes the visible state of the GUI toolbar.
IG_ARTX_GUI_tooltips_visible_get
Gets the state of visibility of the GUI tooltips.
IG_ARTX_GUI_tooltips_visible_set
Changes the state of visibility of the tooltip.
LPFNIG_ARTX_GUI_HOTSPOT_ACTION
Registers a callback method called from the ArtX GUI when a user clicks on a hotspot mark.
LPFNIG_ARTX_GUI_TOOLBARNOTIFY
Registers a callback method called whenever the user changes the button selection in the ToolBar.


IG_ARTX_GUI_cursor_get

Group: GUI

Declaration:

HCURSOR IG_ARTX_GUI_cursor_get();

Description:

This function gets the handle to the current mouse cursor.

Return Value:

HCURSOR object handle.


IG_ARTX_GUI_mode_get

Group: GUI

Declaration:

enumIGArtXGUIMode IG_ARTX_GUI_mode_get();

Description:

This function gets the current display mode of the ArtX GUI.

Return Value:

Can be one of the following:

  • IG_ARTX_GUI_MODE_EDIT - edit mode
  • IG_ARTX_GUI_MODE_RUN - run mode
  • IG_ARTX_GUI_MODE_VIEW - view mode


IG_ARTX_GUI_mode_set

Group: GUI

Declaration:

UINT IG_ARTX_GUI_mode_set(
    enumIGArtXGUIMode nNewMode
);

Arguments:

nNewMode
Display mode to be set. Can be one of the following:
  • IG_ARTX_GUI_MODE_EDIT - edit mode
  • IG_ARTX_GUI_MODE_RUN - run mode
  • IG_ARTX_GUI_MODE_VIEW - view mode

Description:

This function changes the display mode of the ArtX GUI.

Return Value:

0 - if the function is successful, -1 - otherwise.


IG_ARTX_GUI_mouse_down

Group: GUI

Declaration:

UINT IG_ARTX_GUI_mouse_down(
    LPAT_ARTX_ACTION_PARAMS lpParams,
    UINT nMessage,
    LPAT_POINT lpPoint
);

Arguments:

lpParams
Action params such as HIGEAR handle, device context, window handle.
nMessage
Window message (WM_LBUTTONDOWN).
lpPoint
Pointer to AT_POINT that contains mouse position.

Description:

This function is for handling the MouseDown event.

Return Value:

0 - if the function is successful, -1 - otherwise.


IG_ARTX_GUI_mouse_move

Group: GUI

Declaration:

UINT IG_ARTX_GUI_mouse_move(
    LPAT_ARTX_ACTION_PARAMS lpParams,
    UINT nMessage,
    LPAT_POINT lpPoint
);

Arguments:

lpParams
Action params such as HIGEAR handle, device context, window handle.
nMessage
Window message (WM_MOUSEMOVE).
lpPoint
Pointer to AT_POINT that contains mouse position.

Description:

This function is for handling the MouseMove event.

Return Value:

0 - if the function is successful, -1 - otherwise.


IG_ARTX_GUI_mouse_up

Group: GUI

Declaration:

UINT IG_ARTX_GUI_mouse_up(
    LPAT_ARTX_ACTION_PARAMS lpParams,
    UINT nMessage,
    LPAT_POINT lpPoint
);

Arguments:

lpParams
Action params such as HIGEAR handle, device context, window handle.
nMessage
Window message (WM_LBUTTONUP).
lpPoint
Pointer to AT_POINT that contains mouse position.

Description:

This function is for handling the MouseUp event.

Return Value:

0 - if the function is successful, -1 - otherwise.


IG_ARTX_GUI_page_set

Group: GUI

Declaration:

void IG_ARTX_GUI_page_set(
    HIG_ARTX_PAGE hArtXPage
);

Arguments:

hArtXPage
ArtX page to connect to ArtX GUI.

Description:

This function sets the ArtX Page that ArtX GUI is to be connected to.

Return Value:

None.


IG_ARTX_GUI_register_hotspot_action

Group: GUI

Declaration:

void IG_ARTX_GUI_register_hotspot_action(
    LPFNIG_ARTX_GUI_HOTSPOT_ACTION lpfnHotSpotAction,
    LPVOID lpClientData
);

Arguments:

lpfnHotSpotAction
A callback to register.
lpClientData
Client data passed to the callback.

Description:

This function is used to register a callback function that will be called from the ArtX GUI when a user clicks on a hotspot mark.

You can use this function in PDF application to register a callback that would perform a PDF action associated with the hotspot mark's link.

Return Value:

None.


IG_ARTX_GUI_register_toolbar_notify

Group: GUI

Declaration:

void IG_ARTX_GUI_register_toolbar_notify(
    LPFNIG_ARTX_GUI_TOOLBARNOTIFY lpfnToolbarNotify,
    LPVOID lpClientData
);

Arguments:

lpfnToolbarNotify
A callback to register.
lpClientData
Client data passed to the callback.

Description:

This function is used to register a callback function that will be called from the ArtX GUI when the user changes the button selection in the ToolBar.

Return Value:

None.


IG_ARTX_GUI_show_attributes

Group: GUI

Declaration:

UINT IG_ARTX_GUI_show_attributes(
    HIG_ARTX_MARK hArtXMark,
    LPAT_ARTX_DRAW_PARAMS lpParams
);

Arguments:

hArtXMark
Mark which attributes are to be shown.
lpParams
Action params such as HIGEAR handle, device context, window handle.

Description:

This function shows a property sheet for a given mark.

Return Value:

0 - if the function is successful, -1 - otherwise.


IG_ARTX_GUI_toolbar_version_get

Group: GUI

Declaration:

UINT IG_ARTX_GUI_toolbar_version_get(
    BOOL * pbIsLegacy
);

Arguments:

pbIsLegacy
2.0 toolbar if TRUE, 3.0 toolbar if FALSE.

Description:

This function is for getting the version of the GUI toolbar.

Return Value:

0 - if the function is successful, -1 - otherwise.


IG_ARTX_GUI_toolbar_version_set

Group: GUI

Declaration:

UINT IG_ARTX_GUI_toolbar_version_set(
    BOOL bIsLegacy
);

Arguments:

bIsLegacy
2.0 toolbar if TRUE, 3.0 toolbar if FALSE.

Description:

This function is for changing the version of the GUI toolbar.

Return Value:

0 - if the function is successful, -1 - otherwise.


IG_ARTX_GUI_toolbar_visible_get

Group: GUI

Declaration:

UINT IG_ARTX_GUI_toolbar_visible_get(
    BOOL * pbVisibleState
);

Arguments:

pbVisibleState
TRUE - GUI toolbar is visible, FALSE - otherwise.

Description:

This function is for getting the visible state of the GUI toolbar.

Return Value:

0 - if the function is successful, -1 - otherwise.


IG_ARTX_GUI_toolbar_visible_set

Group: GUI

Declaration:

UINT IG_ARTX_GUI_toolbar_visible_set(
    BOOL bVisibleState
);

Arguments:

bVisibleState
TRUE - GUI toolbar is visible, FALSE - otherwise.

Description:

This function is for setting the visible state of the GUI toolbar.

Return Value:

0 - if the function is successful, -1 - otherwise.


IG_ARTX_GUI_tooltips_visible_get

Group: GUI

Declaration:

UINT IG_ARTX_GUI_tooltips_visible_get(
    BOOL * pbVisibleState
);

Arguments:

bVisibleState
TRUE - GUI tooltips is visible, FALSE - otherwise.

Description:

This function is for getting the visible state of the GUI tooltips.

Return Value:

0 - if the function is successful, -1 - otherwise.


IG_ARTX_GUI_tooltips_visible_set

Group: GUI

Declaration:

UINT IG_ARTX_GUI_tooltips_visible_set(
    BOOL bVisibleState
);

Arguments:

bVisibleState
TRUE - GUI tooltips is visible, FALSE - otherwise.

Description:

This function is for changing the visible state of the tooltip.

Return Value:

0 - if the function is successful, -1 - otherwise.


LPFNIG_ARTX_GUI_HOTSPOT_ACTION

Group: GUI

Declaration:

typedef AT_BOOL (LPACCUAPI LPFNIG_ARTX_GUI_HOTSPOT_ACTION)(
    HIG_ARTX_HOTSPOT hHotSpot,
    LPVOID clientData
);

Arguments:

hHotSpot
Handle to the hotspot mark that was clicked.
clientData
Client data passed to IG_ARTX_GUI_register_hotspot_action.

Description:

The callback function declaration used to register a callback method called from the ArtX GUI when the user clicks on a hotspot mark.


LPFNIG_ARTX_GUI_TOOLBARNOTIFY

Group: GUI

Declaration:

 typedef AT_BOOL (LPACCUAPI LPFNIG_ARTX_GUI_TOOLBARNOTIFY)(
     LPVOID lpPrivate,
     enumIGArtXMarkType MarkType,
     enumIGArtXGUIToolbarEventType nReason
);

Arguments:

lpPrivate
Private callback data
MarkType
The annotation mark button that was selected. enumIGArtXMarkType value.
nReason
The reason that ToolBarNotify has been raised. enumIGArtXGUIToolbarEventType value.

Description:

The callback function declaration used to register a callback method called whenever the user changes the button selection in the ToolBar.


ArtX Structures Reference

ImageGear ArtX component represents the following public structures:

AT_ARTX_ARROW_HEAD
Contains members that specify attributes of arrow drawn on and of line annotations.
AT_ARTX_ASPECTRATIO
Contains members that specify aspect ratio parameters used in some annotations.
AT_ARTX_BORDER
Contains members that specify line drawing attributes.
AT_ARTX_BURNIN_PARAMS
Contains members that specify burn in parameters.
AT_ARTX_CALLOUT
Contains members that specify attributes of callout drawn with text annotations.
AT_ARTX_DRAW_PARAMS
Contains members that specify drawing parameters.
AT_ARTX_EDIT_PARAMS
Contains members that specify action edit parameters.
AT_ARTX_FONT
Contains members that specify font in format close to MS GDI+ native font.
AT_ARTX_HITTEST_PARAMS
Contains members that specify hit test parameters.
AT_ARTX_PIN
Contains members that specify attributes of Pin drawn with text annotations.


AT_ARTX_ARROW_HEAD

Group: Structure

Declaration:

typedef struct tagAT_ARTX_ARROW_HEAD
{
    enumIGArtXArrowStyle nStyle;
    AT_INT32 nAngle;
    AT_INT32 nLength;
} AT_ARTX_ARROW_HEAD, * LPAT_ARTX_ARROW_HEAD;

Structure Members:

nStyle
Arrow style
nStyle
Arrow angle
nLength
Arrow length

Description:

This structure contains members that specify attributes of arrow drawn on and of line annotations.


AT_ARTX_ASPECTRATIO

Group: Structure

Declaration:

typedef struct tagAT_ARTX_ASPECTRATIO
{
    AT_INT nAspectNumeratorX;
    AT_INT nAspectDenominatorX;
    AT_INT nAspectNumeratorY;
    AT_INT nAspectDenominatorY;
} AT_ARTX_ASPECTRATIO, *LPAT_ARTX_ASPECTRATIO;

Structure Members:

nAspectNumeratorX
Horizontal aspect numerator.
nAspectDenominatorX
Horizontal aspect denominator.
nAspectNumeratorY
Vertical aspect numerator.
nAspectDenominatorY
Vertical aspect denominator.

Description:

This structure contains members that specify aspect ratio parameters used in some annotations.


AT_ARTX_BORDER

Group: Structure

Declaration:

typedef struct tagAT_ARTX_BORDER
{
    enumIGArtXPenStyle nPenStyle;
    AT_INT32 nWidth;
    AT_RGBQUAD rgbColor;
} AT_ARTX_BORDER, * LPAT_ARTX_BORDER;

Structure Members:

nPenStyle
Pen style
nWidth
Line width
rgbColor
Line color

Description:

This structure contains members that specify line drawing attributes.


AT_ARTX_BURNIN_PARAMS

Group: Structure

Declaration:

typedef struct tagAT_ARTX_BURNIN_PARAMS
{
    AT_MODE nFlags;
    LPAT_VOID lpData;
    AT_DWORD dwDataElements;
} AT_ARTX_BURNIN_PARAMS, *LPAT_ARTX_BURNIN_PARAMS;

Structure Members:

nFlags
A combination of enumIGArtXBurnInOptions flags.
lpData
Pointer to group name or array of elements.
dwDataElements
Numbers of elements in array.

Description:

This structure contains members that specify burn in parameters.


AT_ARTX_CALLOUT

Group: Structure

Declaration:

typedef struct tagAT_ARTX_CALLOUT
{
    enumIGArtXCalloutType nType;
    AT_INT32 nX;
    AT_INT32 nY;
    AT_ARTX_BORDER borderLine;
    AT_BOOL bBorderPresent;
} AT_ARTX_CALLOUT, *LPAT_ARTX_CALLOUT;

Structure Members:

nType
Callout type.
nX
Horizontal coordinate of callout reference point.
nY
Vertical coordinate of callout reference point.
borderLine
Attributes of callout border line.
bBorderPresent
Specifies whether the borderline field is valid and contains any data. Callout may not have any border. In this case bBorderPresent is FALSE and value of borderline is not defined.

Description:

This structure contains members that specify attributes of callout drawn with text annotations.


AT_ARTX_DRAW_PARAMS

Group: Structure

Declaration:

typedef struct tagAT_ARTX_DRAW_PARAMS
{
    HIGEAR hiGear;
    AT_DWORD dwGrpID;
    HDC hDC;
    HWND hWnd;
    AT_INT nOffLeft;
    AT_INT nOffTop;
} AT_ARTX_DRAW_PARAMS, *LPAT_ARTX_DRAW_PARAMS;

Structure Members:

hiGear
image handle
dwGrpID
display group ID
hDC
device context
hWnd
window handle
nOffLeft
offset from left
nOffTop
offset from top

Description:

This structure contains members that specify drawing parameters.


AT_ARTX_EDIT_PARAMS

Group: Structure

Declaration:

typedef struct tagAT_ARTX_EDIT_PARAMS
{
    HWND hEditCtrl;
} AT_ARTX_EDIT_PARAMS, *LPAT_ARTX_EDIT_PARAMS;

Structure Members:

hEditCtrl
Handle to the edit control. Usually a control created for editing TEXT or RTF annotations. See IG_ARTX_action_begin_edit ().

Description:

This structure contains members that specify action edit parameters.


AT_ARTX_FONT

Group: Structure

Declaration:

typedef struct tagAT_ARTX_FONT
{
    AT_FLOAT fSize;
    enumIGArtXFontStyle nStyle;
    AT_INT32 bDisablePPM;
    AT_CHAR lfFaceName[IG_ARTX_FONT_FACESIZE];
} AT_ARTX_FONT, *LPAT_ARTX_FONT;

Structure Members:

fSize
Logical font size.
nStyle
Font style.
bDisablePPM
This parameter affects calculation of physical font size used for drawing from logical size specified in fSize field.
lfFaceName
Font face name.

Description:

This structure contains members that specify font in format close to MS GDI+ native font.


AT_ARTX_HITTEST_PARAMS

Group: Structure

Declaration:

typedef struct tagAT_ARTX_HITTEST_PARAMS
{
    AT_POINT ptDevicePoint;
    AT_INT nClickPrecision;
    HIG_ARTX_MARK hMark;
    enumIGArtXHitTest nResult;
    AT_INT nResultData;
} AT_ARTX_HITTEST_PARAMS, *LPAT_ARTX_HITTEST_PARAMS;

Structure Members:

ptDevicePoint
Point in device coordinates to test.
nClickPrecision
Click precision in pixels.
hMark
Hanle to the result mark.
nResult
Hit test result (enumIGArtXHitTest value).
nResultData
enumIGArtXBounds value in case if nResult = IG_ARTX_HITTEST_ONBOUND, index of the mark point in case if nResult = IG_ARTX_HITTEST_ONPOINT, 0 otherwise.

Description:

This structure contains members that specify hit test parameters.


AT_ARTX_PIN

Group: Structure

Declaration:

typedef struct tagAT_ARTX_PIN
{
    enumIGArtXPinAlignment nAlignment;
    AT_RGBQUAD rgbColor;
    AT_BOOL bColorPresent;
} AT_ARTX_PIN, *LPAT_ARTX_PIN;

Structure Members:

nAlignment
Pin alignment.
rgbColor
Color used to fill area not covered by pin image.
bColorPresent
Specifies whether the rgbColor field is valid and contains any data. Pin can be transparent. In this case bColorPresent is FALSE and value of rgbColor is not defined.

Description:

This structure contains members that specify attributes of Pin drawn with text annotations.


ArtX Enumerations Reference

ImageGear ArtX component represents the following enumerations:

enumIGArtXAccess
Specifies mark accesability state.
enumIGArtXArrowStyle
Specifies available arrow head styles.
enumIGArtXAttrAudio
Identifies attributes of audio annotation.
enumIGArtXAttrButton
Identifies attributes of button annotation.
enumIGArtXAttrEllipse
Identifies attributes of ellipse annotation.
enumIGArtXAttrEncryption
Identifies attributes of encryption annotation.
enumIGArtXAttrGroup
Identifies attributes of group of annotations.
enumIGArtXAttrHotSpot
Identifies attributes of hot spot annotation.
enumIGArtXAttrImage
Identifies attributes of image annotation.
enumIGArtXAttrLine
Identifies attributes of line annotation.
enumIGArtXAttrLink
Identifies attributes of link annotation.
enumIGArtXAttrMark
Identifies attributes of mark.
enumIGArtXAttrPage
Identifies attributes of page.
enumIGArtXAttrPolygon
Identifies attributes of polygon annotation.
enumIGArtXAttrPolyline
Identifies attributes of polyline annotation.
enumIGArtXAttrProtractor
Identifies attributes of protractor annotation.
enumIGArtXAttrRectangle
Identifies attributes of rectangle annotation.
enumIGArtXAttrRichText
Identifies attributes of rich text annotation.
enumIGArtXAttrRuler
Identifies attributes of ruler annotation.
enumIGArtXAttrText
Identifies attributes of text annotation.
enumIGArtXBounds
Used to indicate position of point (mouse cursor in most cases) relative annotation selection border.
enumIGArtXBurnInOptions
Specifies options for burn in.
enumIGArtXButtonState
Determines the state of button annotation.
enumIGArtXCalloutType
Specifies the type of callout drawn with text annotation.
enumIGArtXCoordType
Determines the type of coordinate system used to specify mark position.
enumIGArtXFontStyle
Specifies the style of the typeface of a font. Styles can be combined.
enumIGArtXGUIAction
Specifies the result of ArtX GUI action operations.
enumIGArtXGUIActionType
Specifies ArtX GUI action types and is used with function IG_ARTX_action_type_get ().
enumIGArtXGUIToolbarEventType
Enumerates the various reasons for raising the ToolBarNotify event.
enumIGArtXHighlightModes
Specifies link highlight modes that can be used by GUI to highlight the hotspot area.
enumIGArtXHitTest
Specifies results of point hittest for selected mark.
enumIGArtXMarkType
Specifies available annotation types.
enumIGArtXPenStyle
Specifies the line styles of lines used to draw annotation or it's border.
enumIGArtXPinAlignment
Specifies alignment of Pin, assigned to text annotation.
enumIGArtXSaveFormat
Specifies alignment of Pin, assigned to text annotation.
enumIGArtXSelectionType
Specifies a type of selection that is drawn arounf mark to indicate it is selected.
enumIGArtXTextType
Specifies available types of text annotation and what TEXT attribute of annotation means - text itself or name of file with text.
enumIGArtXUndoAction
Used to control Undo functionality of ArtX.
enumIGArtXWrap
Affects text mark's drawing method.


enumIGArtXAccess

Group: Enumeration

Description:

This enumeration specifies mark accesability state.

Values:

IG_ARTX_ACCESS_LOCKED
Specifies that annotation is locked and can't be moved/edited with GUI.
IG_ARTX_ACCESS_UNLOCKED
Specifies that annotation is not locked and can be moved/edsited with GUI.


enumIGArtXArrowStyle

Group: Enumeration

Description:

This enumeration specifies available arrow head styles.

Values:

IG_ARTX_ARROW_POINTER
Specifies simple arrow pointer.
IG_ARTX_ARROW_SOLID
Specifies solid arrow pointer.
IG_ARTX_ARROW_OPEN
Specifies open arrow pointer.
IG_ARTX_ARROW_POINTER_SOLID
Specifies closed solid arrow pointer.
IG_ARTX_ARROW_NONE
Specifies empty pointer (no arrow).


enumIGArtXAttrAudio

Group: Enumeration

Description:

This enumeration identifies attributes of audio annotation.

Values:

IG_ARTX_ATTR_AUDIO_BOUNDS
Identifies annotation bounding rectangle
IG_ARTX_ATTR_AUDIO_FILENAME
Identifies name of audio file associated with annotation


enumIGArtXAttrButton

Group: Enumeration

Description:

This enumeration identifies attributes of button annotation.

Values:

IG_ARTX_ATTR_BUTTON_BOUNDS
Identifies annotation bounding rectangle
IG_ARTX_ATTR_BUTTON_FILLCOLOR
Identifies attributes of annotation fill color
IG_ARTX_ATTR_BUTTON_TEXTCOLOR
Identifies attributes of annotation text color
IG_ARTX_ATTR_BUTTON_TEXT
Identifies annotation text
IG_ARTX_ATTR_BUTTON_FONT
Identifies attributes of annotation text font. Font is specified as AT_ARTX_FONT structure
IG_ARTX_ATTR_BUTTON_LOGFONT
Identifies attributes of annotation text font. Font is specified as AT_LOGFONT structure
IG_ARTX_ATTR_BUTTON_FONT_DISABLEPPM
Identifies whether the resolution of underlying image is used to render annotation text
IG_ARTX_ATTR_BUTTON_OPACITY
Identifies annotation opacity
IG_ARTX_ATTR_BUTTON_ORIENTATION
Identifies orientation of annotation text


enumIGArtXAttrEllipse

Group: Enumeration

Description:

This enumeration identifies attributes of ellipse annotation.

Values:

IG_ARTX_ATTR_ELLIPSE_BOUNDS
Identifies annotation bounding rectangle
IG_ARTX_ATTR_ELLIPSE_OPACITY
Identifies annotation opacity
IG_ARTX_ATTR_ELLIPSE_BORDER
Identifies attributes of annotation border
IG_ARTX_ATTR_ELLIPSE_FILLCOLOR
Identifies attributes of annotation fill color


enumIGArtXAttrEncryption

Group: Enumeration

Description:

This enumeration identifies attributes of encryption annotation.

Values:

IG_ARTX_ATTR_ENCRYPTION_BOUNDS
Identifies annotation bounding rectangle
IG_ARTX_ATTR_ENCRYPTION_PASSWORD
Identifies encryption password


enumIGArtXAttrGroup

Group: Enumeration

Description:

This enumeration identifies attributes of ArtX annotation group.

Values:

IG_ARTX_ATTR_GROUP_NAME
Indetifies group name.
IG_ARTX_ATTR_GROUP_DESCR
Indetifies group description.


enumIGArtXAttrHotSpot

Group: Enumeration

Description:

This enumeration identifies attributes of hotspot annotation.

Values:

IG_ARTX_ATTR_HOTSPOT_BOUNDS
Identifies annotation bounding rectangle
IG_ARTX_ATTR_HOTSPOT_OPACITY
Identifies annotation opacity
IG_ARTX_ATTR_HOTSPOT_BORDER
Identifies attributes of annotation border
IG_ARTX_ATTR_HOTSPOT_FILLCOLOR
Identifies attributes of annotation fill color
IG_ARTX_ATTR_HOTSPOT_LINK
Identifies attributes of hotspot link


enumIGArtXAttrImage

Group: Enumeration

Description:

This enumeration identifies attributes of image annotation.

Values:

IG_ARTX_ATTR_IMAGE_BOUNDS
Identifies annotation bounding rectangle
IG_ARTX_ATTR_IMAGE_PAGE
Identifies handle of annotation image
IG_ARTX_ATTR_IMAGE_FILENAME
Identifies name of file with image to use for annotation drawing
IG_ARTX_ATTR_IMAGE_ORIENTATION
Identifies orientation of annotation image
IG_ARTX_ATTR_IMAGE_FITMODE
Identifies fit mode of annotation image
IG_ARTX_ATTR_IMAGE_ALIGNMENT_H
Identifies horizontal alignment of annotation image
IG_ARTX_ATTR_IMAGE_ALIGNMENT_V
Identifies vertical alignment of annotation image
IG_ARTX_ATTR_IMAGE_ASPECT_VALUE
Identifies aspectratio of annotation image


enumIGArtXAttrLine

Group: Enumeration

Description:

This enumeration identifies attributes of polyline annotation.

Values:

IG_ARTX_ATTR_LINE_BOUNDS
Identifies annotation bounding rectangle. Read-only attribute
IG_ARTX_ATTR_LINE_OPACITY
Identifies annotation opacity
IG_ARTX_ATTR_LINE_LINE
Identifies attributes of line used to draw this annotation
IG_ARTX_ATTR_LINE_HEADFILLCOLOR
Identifies fill color of arrows drawn on ends of line
IG_ARTX_ATTR_LINE_STARTHEAD
Identifies attributes of line start head
IG_ARTX_ATTR_LINE_ENDHEAD
Identifies attributes of line end head
IG_ARTX_ATTR_LINE_STARTPOINT
Identifies start point of line
IG_ARTX_ATTR_LINE_ENDPOINT
Identifies end point of line


enumIGArtXAttrLink

Group: Enumeration

Description:

This enumeration identifies attributes of link annotation.

Values:

IG_ARTX_ATTR_LINK_DATA
Identifies data associated with link
IG_ARTX_ATTR_LINK_HIGHLIGHT
Identifies link highlighter data


enumIGArtXAttrMark

Group: Enumeration

Description:

This enumeration identifis attributes common for all annotations.

Values:

IG_ARTX_ATTR_MARK_TYPE
Identifies annotation type ID
IG_ARTX_ATTR_MARK_BOUNDS
Identifies annotation bounding rectangle
IG_ARTX_ATTR_MARK_VISIBLE
Identifies annotation visibility state
IG_ARTX_ATTR_MARK_USER_DATA
Identifies user data associated with annotation
IG_ARTX_ATTR_MARK_TOOLTIP
Identifies tooltip text string associated with annotation


enumIGArtXAttrPage

Group: Enumeration

Description:

This enumeration identifies attributes of ArtX page.

Values:

IG_ARTX_ATTR_PAGE_SHOW_LOCKS
Identifies visibility of lock icon for locked annotations on page.
Type AT_BOOL, default is FALSE.
IG_ARTX_ATTR_PAGE_DISABLE_PPM_FOR_FONTS
Identifies whether the resolution of underlying image is affecting drawing of text and RTF annotations on page. Set to FALSE (default value) to enable using image resolution for scaling font size of text and RTF marks, TRUE otherwise.
Type AT_BOOL, default is FALSE.
IG_ARTX_ATTR_PAGE_SHADOW_FONTS
Identifies shadow font attribute of page. It specifies how to draw text annotation (text, button, and so on)
Type AT_BOOL, default is FALSE.
IG_ARTX_ATTR_PAGE_WANG_LOAD_COMPATIBILITY
Identifies Wang load compatibility attribute of page. When set to TRUE only Wang-compatible annotation will be loaded into page.
IG_ARTX_ATTR_PAGE_FULL_TEXTMARKS_SELECT
Identify attribute that responds for text mark hit test functionality. When set to TRUE all area within text bounding rectangle is considered as annotation area. When set to FALSE only area occupied by text (by each character) is considered as internal for mark.
Type AT_BOOL, default is FALSE.
IG_ARTX_ATTR_PAGE_BURN_IN_THRESHOLD
This attribute is used in IG_ARTX_page_burn_in function. It specifies how to reduce full color annotations to b/w colorspace.
Type AT_INT, default is 128, valid values are 0-255.


enumIGArtXAttrPolygon

Group: Enumeration

Description:

This enumeration identifies attributes of polygon annotation.

Values:

IG_ARTX_ATTR_POLYGON_BOUNDS
Identifies annotation bounding rectangle. Read-only attribute
IG_ARTX_ATTR_POLYGON_OPACITY
Identifies annotation opacity
IG_ARTX_ATTR_POLYGON_BORDER
Identifies attributes of annotation border
IG_ARTX_ATTR_POLYGON_FILLCOLOR
Identifies attributes of annotation fill color


enumIGArtXAttrPolyline

Group: Enumeration

Description:

This enumeration identifies attributes of polyline annotation.

Values:

IG_ARTX_ATTR_POLYLINE_BOUNDS
Identifies annotation bounding rectangle. Read-only attribute
IG_ARTX_ATTR_POLYLINE_OPACITY
Identifies annotation opacity
IG_ARTX_ATTR_POLYLINE_LINE
Identifies attributes of line used to draw this annotation
IG_ARTX_ATTR_POLYLINE_HEADFILLCOLOR
Identifies fill color of arrows drawn on ends of polyline
IG_ARTX_ATTR_POLYLINE_STARTHEAD
Identifies attributes of polyline start head
IG_ARTX_ATTR_POLYLINE_ENDHEAD
Identifies attributes of polyline end head
IG_ARTX_ATTR_POLYLINE_CLOSED
Identifies whether polyline is closed or not


enumIGArtXAttrProtractor

Group: Enumeration

Description:

This enumeration identifies attributes of protractor annotation.

Values:

IG_ARTX_ATTR_PROTRACTOR_BOUNDS
Identifies annotation bounding rectangle. This is read-only property
IG_ARTX_ATTR_PROTRACTOR_OPACITY
Identifies annotation opacity
IG_ARTX_ATTR_PROTRACTOR_LINE
Identifies attributes of line used to draw annotation
IG_ARTX_ATTR_PROTRACTOR_ASPECTRATIO
Identifies attributes of annotation aspectratio
IG_ARTX_ATTR_PROTRACTOR_STARTPOINT
Identifies start point of protractor
IG_ARTX_ATTR_PROTRACTOR_ENDPOINT
Identifies end point of protractor
IG_ARTX_ATTR_PROTRACTOR_HEADPOINT
Identifies head point of protractor
IG_ARTX_ATTR_PROTRACTOR_ARCRADIUS
Identifies radius of arc drawn within protractor
IG_ARTX_ATTR_PROTRACTOR_PRECISION
Identifies precision of protcractor length displayed
IG_ARTX_ATTR_PROTRACTOR_FONT
Identifies attributes of annotation font. Font is specified as AT_ARTX_FONT structure
IG_ARTX_ATTR_PROTRACTOR_LOGFONT
Identifies attributes of annotation font. Font is specified as AT_LOGFONT structure


enumIGArtXAttrRectangle

Group: Enumeration

Description:

This enumeration identifies attributes of rectangle annotation.

Values:

IG_ARTX_ATTR_RECTANGLE_BOUNDS
Identifies annotation bounding rectangle
IG_ARTX_ATTR_RECTANGLE_OPACITY
Identifies annotation opacity
IG_ARTX_ATTR_RECTANGLE_BORDER
Identifies attributes of annotation border
IG_ARTX_ATTR_RECTANGLE_FILLCOLOR
Identifies attributes of annotation fill color


enumIGArtXAttrRichText

Group: Enumeration

Description:

This enumeration identifies attributes of rich text annotation.

Values:

IG_ARTX_ATTR_RICHTEXT_BOUNDS
Identifies annotation bounding rectangle
IG_ARTX_ATTR_RICHTEXT_OPACITY
Identifies annotation opacity
IG_ARTX_ATTR_RICHTEXT_BORDER
Identifies attributes of annotation border
IG_ARTX_ATTR_RICHTEXT_FILLCOLOR
Identifies attributes of annotation fill color
IG_ARTX_ATTR_RICHTEXT_TEXT
Identifies annotation text. Note this is text in RTF format
IG_ARTX_ATTR_RICHTEXT_ORIENTATION
Identifies orientation of annotation text


enumIGArtXAttrRuler

Group: Enumeration

Description:

This enumeration identifies attributes of ruler annotation.

Values:

IG_ARTX_ATTR_RULER_BOUNDS
Identifies annotation bounding rectangle. This is read-only property
IG_ARTX_ATTR_RULER_OPACITY
Identifies annotation opacity
IG_ARTX_ATTR_RULER_LINE
Identifies attributes of line used to draw annotation
IG_ARTX_ATTR_RULER_ASPECTRATIO
Identifies attributes of annotation aspectratio
IG_ARTX_ATTR_RULER_STARTPOINT
Identifies start point of ruler
IG_ARTX_ATTR_RULER_ENDPOINT
Identifies end point of ruler
IG_ARTX_ATTR_RULER_STARTLINE_LENGTH
Identifies length of touch at start point of ruler
IG_ARTX_ATTR_RULER_ENDLINE_LENGTH
Identifies length of touch at end point of ruler
IG_ARTX_ATTR_RULER_PRECISION
Identifies precision of ruler length displayed
IG_ARTX_ATTR_RULER_LABEL
Identifies text used for ruler label
IG_ARTX_ATTR_RULER_FONT
Identifies attributes of annotation font. Font is specified as AT_ARTX_FONT structure
IG_ARTX_ATTR_RULER_LOGFONT
Identifies attributes of annotation font. Font is specified as AT_LOGFONT structure


enumIGArtXAttrText

Group: Enumeration

Description:

This enumeration identifies attributes of text annotation.

Values:

IG_ARTX_ATTR_TEXT_BOUNDS
Identifies annotation bounding rectangle
IG_ARTX_ATTR_TEXT_OPACITY
Identifies annotation opacity
IG_ARTX_ATTR_TEXT_BORDER
Identifies attributes of annotation border
IG_ARTX_ATTR_TEXT_FILLCOLOR
Identifies attributes of annotation fill color
IG_ARTX_ATTR_TEXTTYPE
Identifies annotation text type
IG_ARTX_ATTR_TEXT_TEXTCOLOR
Identifies attributes of annotation text color
IG_ARTX_ATTR_TEXT_BORDERSHADING
Identifies annotation text border shadoing
IG_ARTX_ATTR_TEXT_TEXT
Identifies annotation text
IG_ARTX_ATTR_TEXT_FONT
Identifies attributes of annotation text font. Font is specified as AT_ARTX_FONT structure
IG_ARTX_ATTR_TEXT_LOGFONT
Identifies attributes of annotation text font. Font is specified as AT_LOGFONT structure
IG_ARTX_ATTR_TEXT_FONT_DISABLEPPM
Identifies whether the resolution of underlying image is used to render annotation text
IG_ARTX_ATTR_TEXT_PIN
Identifies attributes of pin object assotiated with text annotation
IG_ARTX_ATTR_TEXT_CALLOUT
Identifies attributes of callout object assotiated with text annotation
IG_ARTX_ATTR_TEXT_ORIENTATION
Identifies orientation of annotation text


enumIGArtXBounds

Group: Enumeration

Description:

This enumeration is used to indicate position of point (mouse cursor in most cases) relative annotation selection border.

Values:

IG_ARTX_BOUND_NONE
Specifies that point is not on border.
IG_ARTX_BOUND_LEFT_TOP
Specifies that point is on left-top corner of selection rectangle.
IG_ARTX_BOUND_RIGHT_TOP
Specifies that point is on right-top corner of selection rectangle.
IG_ARTX_BOUND_LEFT_BOTTOM
Specifies that point is on left-bottom corner of selection rectangle.
IG_ARTX_BOUND_RIGHT_BOTTOM
Specifies that point is on right-bottom corner of selection rectangle.
IG_ARTX_BOUND_LEFT
Specifies that point is on left side of selection rectangle.
IG_ARTX_BOUND_RIGHT
Specifies that point is on right side of selection rectangle.
IG_ARTX_BOUND_TOP
Specifies that point is on top side of selection rectangle.
IG_ARTX_BOUND_BOTTOM
Specifies that point is on bottom side of selection rectangle.


enumIGArtXBurnInOptions

Group: Enumeration

Description:

This enumeration specifies options for burn in.

Values:

IG_ARTX_BURN_IN_ALL
Burns in all annotation marks.
IG_ARTX_BURN_IN_DELETE_MARKS
Deletes affected marks after burning them in.
IG_ARTX_BURN_IN_GROUP
Burns in a group of marks.
IG_ARTX_BURN_IN_MARK_LIST
Burns in a list of marks.
IG_ARTX_BURN_IN_VISIBLE
Burns in all visible marks.
IG_ARTX_BURN_IN_SELECTED
Burns in all selected marks.
IG_ARTX_BURN_IN_AUTO_PROMOTE
Automatically promotes image.
IG_ARTX_BURN_IN_NO_PROMOTE
No promotion before burn-in.
IG_ARTX_BURN_IN_THRESHOLD_METHOD
Threshold reduce method for b/w images.
IG_ARTX_BURN_IN_GROUP_LIST
Burns in several groups of marks.


enumIGArtXButtonState

Group: Enumeration

Description:

This enumeration determines the state of button annotation.

Values:

IG_ARTX_BUTTON_NORMAL
Specifies normal button state.
IG_ARTX_BUTTON_PRESSED
Specifies pressed button state.


enumIGArtXCalloutType

Group: Enumeration

Description:

This enumeration specifies the type of callout drawn with text annotation.

Values:

IG_ARTX_CALLOUT_LINE
Specifies line callout.
IG_ARTX_CALLOUT_TRIANGLE
Specifies triangle callout.


enumIGArtXCoordType

Group: Enumeration

Description:

This enumeration determines the type of coordinate system used to specify mark position.

Values:

IG_ARTX_COORD_IMAGE
Image-based coordinate system. Point (0,0) represents left top corner of image.
IG_ARTX_COORD_DEVICE
Device (window) based coordinate system. Point (0,0) represents left top corner of window.


enumIGArtXFontStyle

Group: Enumeration

Description:

This enumeration specifies the style of the typeface of a font. Styles can be combined.

Values:

IG_ARTX_FONT_REGULAR
Specifies normal weight or thickness of the typeface.
IG_ARTX_FONT_BOLD
Specifies bold typeface. Bold is a heavier weight or thickness.
IG_ARTX_FONT_ITALIC
Specifies italic typeface, which produces a noticeable slant to the vertical stems of the characters.
IG_ARTX_FONT_UNDERLINE
Specifies underline, which displays a line underneath the baseline of the characters.
IG_ARTX_FONT_STRIKEOUT
Specifies strikeout, which displays a horizontal line drawn through the middle of the characters.


enumIGArtXGUIAction

Group: Enumeration

Description:

This enumeration specifies the result of ArtX GUI action operations. It is used as output parameter of IG_ARTX_action_mouse_XXX functions.

Values:

IG_ARTX_GUI_ACTION_FAILURE
Specifies that operation is failed.
IG_ARTX_GUI_ACTION_SUCCESS
Specifies that operation is successful.
IG_ARTX_GUI_ACTION_READY
Specifies that operation is successful and that selected action has enough data to be finished. Additional operations with this action are also possible.
IG_ARTX_GUI_ACTION_CONTINUE
Specifies that operation is successful but selected action can't be finished and requires more data/more events. For instance protractor annotation requires 3 points to be specified but only 2 where acquired for the moment.


enumIGArtXGUIActionType

Group: Enumeration

Description:

This enumeration specifies ArtX GUI action types and is used with function IG_ARTX_action_type_get ().

Values:

IG_ARTX_GUI_ACTION_NONE
Specifies empty action. Should not be used and may indicate error state.
IG_ARTX_GUI_ACTION_SELECT
GUI action is mark selection.
IG_ARTX_GUI_ACTION_CREATE
GUI action is mark creation.
IG_ARTX_GUI_ACTION_MOVE
GUI action is mark movement.
IG_ARTX_GUI_ACTION_RESIZE
GUI action is mark resize.
IG_ARTX_GUI_ACTION_EDIT
GUI action is mark edit.


enumIGArtXGUIToolbarEventType

Group: Enumeration

Description:

Enumerates the various reasons for raising the ToolBarNotify event.

Values:

IG_ARTX_GUI_TOOLBAR_BUTTON_SELECTED
A button has been selected.
IG_ARTX_GUI_TOOLBAR_NONE_SELECTED
No button is selected.
IG_ARTX_GUI_TOOLBAR_HIDDEN
A button on toolbar caption is clicked.
IG_ARTX_GUI_TOOLBAR_DESTROYED
The toolbar is about to be destroyed.


enumIGArtXHighlightModes

Group: Enumeration

Description:

This enumeration specifies link highlight modes that can be used by GUI to highlight the hotspot area.

Values:

IG_ARTX_HIGHLIGHT_NONE
Specifies empty highlighter.
IG_ARTX_HIGHLIGHT_INVERT
Specifies that highlighter is inverting colors within its area.
IG_ARTX_HIGHLIGHT_OUTLINE
Specifies that highlighter is outlining it's area.
IG_ARTX_HIGHLIGHT_PUSH
Specifies that highlighter is drawing XXXXX.


enumIGArtXHitTest

Group: Enumeration

Description:

This enumeration specifies results of point hittest for selected mark.

Values:

IG_ARTX_HITTEST_NONE
Specifies that point is outside of any mark.
IG_ARTX_HITTEST_ONMARK
Specifies that point is exactly on mark pixels.
IG_ARTX_HITTEST_ONBOUND
Specifies that point is exactly on mark bounding rectangle.
IG_ARTX_HITTEST_ONPOINT
Specifies that point is exactly on mark corner-point.
IG_ARTX_HITTEST_INBOUND
Specifies that point is within mark bounds, but not on mark pixels.
IG_ARTX_HITTEST_ON
Specifies combination of flags above and means that point is on mark.


enumIGArtXMarkType

Group: Enumeration

Description:

This enumeration specifies available annotation types.

Values:

IG_ARTX_MARK_SELECT
IG_ARTX_MARK_IMAGE_EMBEDDED
IG_ARTX_MARK_IMAGE_REFERENCE
IG_ARTX_MARK_LINE
IG_ARTX_MARK_FREEHAND_LINE
IG_ARTX_MARK_HOLLOW_RECTANGLE
IG_ARTX_MARK_FILLED_RECTANGLE
IG_ARTX_MARK_TYPED_TEXT
IG_ARTX_MARK_TEXT_FROM_FILE
IG_ARTX_MARK_TEXT_STAMP
IG_ARTX_MARK_ATTACH_A_NOTE
IG_ARTX_MARK_FILLED_POLYGON
IG_ARTX_MARK_HOLLOW_POLYGON
IG_ARTX_MARK_POLYLINE
IG_ARTX_MARK_AUDIO
IG_ARTX_MARK_FILLED_ELLIPSE
IG_ARTX_MARK_HOLLOW_ELLIPSE
IG_ARTX_MARK_ARROW
IG_ARTX_MARK_HOTSPOT
IG_ARTX_MARK_REDACTION
IG_ARTX_MARK_ENCRYPTION
IG_ARTX_MARK_RULER
IG_ARTX_MARK_PROTRACTOR
IG_ARTX_MARK_BUTTON
IG_ARTX_MARK_PIN_UP_TEXT
IG_ARTX_MARK_HIGHLIGHTER
IG_ARTX_MARK_RICH_TEXT
IG_ARTX_MARK_CALLOUT
IG_ARTX_MARK_RECTANGLE
IG_ARTX_MARK_ELLIPSE
IG_ARTX_MARK_POLYGON
IG_ARTX_MARK_TEXT
IG_ARTX_MARK_IMAGE


enumIGArtXPenStyle

Group: Enumeration

Description:

This enumeration specifies the line styles of lines used to draw annotation or it's border.

Values:

IG_ARTX_PEN_SOLID
Specifies a solid line.
IG_ARTX_PEN_DASH
Specifies a dashed line.
IG_ARTX_PEN_DOT
Specifies a dotted line.
IG_ARTX_PEN_DASHDOT
Specifies an alternating dash-dot line.
IG_ARTX_PEN_DASHDOTDOT
Specifies an alternating dash-dot-dot line
IG_ARTX_PEN_PDFDASH1
Specifies a PDF dash line 1.
IG_ARTX_PEN_PDFDASH2
Specifies a PDF dash line 2.
IG_ARTX_PEN_PDFDASH3
Specifies a PDF dash line 3.
IG_ARTX_PEN_PDFDASH4
Specifies a PDF dash line 4.
IG_ARTX_PEN_PDFDASH5
Specifies a PDF dash line 5.
IG_ARTX_PEN_PDFDASH6
Specifies a PDF dash line 6.
IG_ARTX_PEN_UNDERLINE
Specifies a single line along the bottom of the annotation rectangle. Applicable for IG_ARTX_MARK_LINK only.


enumIGArtXPinAlignment

Group: Enumeration

Description:

This enumeration specifies alignment of Pin, assigned to text annotation.

Values:

IG_ARTX_PINALIGNMENT_LEFT_TOP
Specifies Pin attached to left top corner of text annotation.
IG_ARTX_PINALIGNMENT_LEFT_BOTTOM
Specifies Pin attached to left top bottom of text annotation.
IG_ARTX_PINALIGNMENT_RIGHT_TOP
Specifies Pin attached to right top corner of text annotation.
IG_ARTX_PINALIGNMENT_RIGHT_BOTTOM
Specifies Pin attached to right bottom corner of text annotation.


enumIGArtXSaveFormat

Group: Enumeration

Description:

This enumeration specifies format used to save annotations.

Values:

IG_ARTX_SAVE_XML
Specifies that annotations should be saved in XML format. This is ArtX native data format.
IG_ARTX_SAVE_LEGACY
Specifies that annotations should be saved in Art 2.0 legacy format. It is applicable for legacy annotations only. All ArtX native types are ignored.
IG_ARTX_SAVE_LEGACY_WANG
Specifies that annotations should be saved in Art 2.0 WANG legacy format. It is applicable for WANG compatible legacy annotations only. All other annotation types are ignored.


enumIGArtXSelectionType

Group: Enumeration

Description:

This enumeration specifies a type of selection that is drawn arounf mark to indicate it is selected.

Values:

IG_ARTX_SELECTION_RECTANGLE
Rectangle selection is used for simple shape annotation such as rectangle, ellipse, text, etc.
IG_ARTX_SELECTION_POINTS
Mark considered as sequence of points. Each point is selected separately and can be moved independently.


enumIGArtXTextType

Group: Enumeration

Description:

This enumeration specifies available types of text annotation and what TEXT attribute of annotation means - text itself or name of file with text.

Values:

IG_ARTX_TEXT_DIRECT_TEXT
Specifies that text stored in annotation is what is for drawing directly.
IG_ARTX_TEXT_FILE_NAME
Specifies that text stored in annotation is a name of file. File content is used to draw text annotation.


enumIGArtXUndoAction

Group: Enumeration

Description:

This enumeration is used to control Undo functionality of ArtX. These constants are specifying what undo operation is enabled or disabled (see IG_ARTX_page_undo_action_enable ()/IG_ARTX_page_undo_action_is_enabled () API)

Values:

IG_ARTX_UNDO_NONE
Corresponds to empty operation. Should not be used.
IG_ARTX_UNDO_MARK_ATTRIBUTES
Specifies whether to record annotation attribute modification to undo base.
IG_ARTX_UNDO_MARK_SELECT
Specifies whether to record annotation selecting operations to undo base.
IG_ARTX_UNDO_MARK_DELETE
Specifies whether to record annotation delete operation to undo base.
IG_ARTX_UNDO_MARK_CREATE
Specifies whether to record annotation creation operation to undo base.
IG_ARTX_UNDO_GROUP_ATTRIBUTES
Specifies whether to record group attribute modification to undo base.
IG_ARTX_UNDO_GROUP_ZORDER
Specifies whether to record group z-order modification to undo base.
IG_ARTX_UNDO_GROUP_DELETE
Specifies whether to record group creation operation to undo base.
IG_ARTX_UNDO_GROUP_CREATE
Specifies whether to record group delete operation to undo base.


enumIGArtXWrap

Group: Enumeration

Description:

Affects text mark's drawing method as follows:

IG_ARTX_WRAP_HORIZONTAL - mark's text is wrapped horizontally

IG_ARTX_WRAP_VERTICAL - mark's text is wrapped vertically

Values:

IG_ARTX_WRAP_NONE
Indicates no wrapping method for text border (default)
IG_ARTX_WRAP_HORIZONTAL
Indicates horizontal wrapping for text border
IG_ARTX_WRAP_VERTICAL
Indicates vertical wrapping for text border


ART Component API Function Reference

In this Chapter you can get the detailed information about all ImageGear ART component functions, macros and callbacks:

  • ART Component Functions Reference
  • ART Component Callback Functions Reference
NOTE: You can only attach one ART component. ART cannot be attached when ARTX is already attached.
NOTE: ART component functions are accessible only when ART component is attached to Core ImageGear. Please see the section Using ImageGear Component Manager.

ART component functions are designated with the prefix ART_....

ART component callback functions are designated with LPFNIG_ART_... and LPFNART_... prefixes. Please see the section ART Component Callback Functions Reference.


ART Component Functions Reference

ART Component API Classifications

There are several classifications for ART component functions. All these functions are divided on groups. The following table lists the different groups. Discussions explaining each group appears after the table.

Function Names beginning with
Group
ART_callback_register_
Callback Register
ART_control_option_
Control
ART_edit_
Clipboard
ART_edit_undo_
Undo
ART_file_
File
ART_global_block_
Global Named Block Management
ART_group_
Mark Grouping
ART_GUI_
Graphical User Interface
ART_image_
Image Utility
ART_mark_
Mark Management
ART_mark_block_
Named Block Management
ART_version_
Library Utility

Block Operations

ART component has two types of blocks:

  • Global Named Blocks
  • Named Blocks.

Global Named Blocks hold values that act as defaults for the next mark created. Named Blocks can be used to set specific attributes for the current mark.

Global Named Blocks work with "Global Named Block Management" functions; these function names begin with ART_global_block_. Named Blocks work with "Named Block Management" functions; these function names begin with ART_mark_block_.

See also the section ART Component Important Structures and Types.

Callback & Callback Register

Callbacks are low-level functions that provide control over the way that ART works. Each callback function must be "registered" in order to be automatically called by ART. Function with the name ART_callback_register () registers ART callback.

Functions labelled as "Callback", when registered, are called by ART during certain events:

  • when the user is about to create a new mark,
  • when they are going to delete a mark,
  • when the mouse is clicked over a mark.

ART returns important data to you and you can send data back to ART. This exchange of information determines whether or not to proceed with an operation. See the section entitled ART Component Callback Functions Reference.

Clipboard

Clipboard function names begin with ART_edit_ and allow you to copy and cut marks to the clipboard, and to paste marks into an image.

Control

Currently there are two functions in this category: ART_control_option_set () and ART_control_option_get (). The former function modifies default library settings. The latter function gets a value of the control option.

File

This set of functions begin with ART_file_. They control import and export of .ART files.

Graphical User Interface

The functions begin with ART_GUI_. These functions deal with interactive modification of marks:

  • through property sheets,
  • the ART toolbar
  • by mouse interaction.

ART_GUI_mark_hit_test () is an indespensible function that determines what kind of mouse actions have occurred within a specified region of the image.

Image Utility

There is one function in this group, ART_image_burn_in (). This function causes marks to be "burned in" to an image when it is saved. There are many options for this function, including the abilitiy to burn in only a specified list of the available marks.

Mark Grouping

These functions begin with ART_group_. They perform operations on groups of marks. You can form any number of groups you wish and assign them names. You may choose to group all shapes together, and then send them "to the back" using the ART_group_send_to_back () function.

Mark Management

These functions begin with ART_mark_. They modify and query marks. The ART_mark_modify () updates the values in the mark attributes structure. This structure is defined in ARTAPI.H and is illustrated in the section ART Component Important Structures and Types inChapter 5.

The ART_mark_query () function returns the values in the attributes structure.

Undo

Undo function names begin with ART_edit_undo_. These functions record edits to marks, and undo a specified number of edits.


ART_callback_register

Group: Callback Register

Declaration:

AT_ERRCOUNT ART_callback_register(HIGEAR hIGear,
    AT_MODE			nCallbackID,
    LPFNIG_ART_CALLBACKFUNC	 lpfnCallback,
    LPVOID			lpPrivate
    );

Arguments:

hIGear
HIGEAR handle to the image
nCallbackID
An ART-defined constant of type AT_MODE that tells which type of callback is being registered
lpfnCallback
A far pointer to your callback function to register
lpPrivate
A far pointer to private data (passed to callback function)

Description:

This function registers an ART callback function. (see the callback functions at the end of this reference in the section ART Component Callback Functions Reference.) To unregister a function, pass NULL to the lpfnCallback parameter.

nCallbackID is a predefined value that identies the type of callback to register. The predefined constants for this variable reside in ARTAPI.H and begin with the prefix ART_CALLBACK_. Only one callback of each type may be registered at the same time.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • nCallbackID is not one of the predefined callback types.
  • lpfnCallback is not NULL or a valid address.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
AT_ERRCOUNT nErrcount; /* Tally of IG errors on  */
             /* the stack    */
VOID privateData; /* Any private data that you */
/* would like to pass to the */
/* callback   */
nErrcount = ART_callback_register(hIGear,
ART_CALLBACK_CREATE_MODIFY ,myCallbackFunc, (LPVOID)
&privateData);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_control_option_get

Group: Control

Declaration:

AT_ERRCOUNT ART_control_option_get(HIGEAR hIGear,
    AT_MODE nOption,
    const LPVOID lpValue
    );

Arguments:

hIGear
HIGEAR handle of an image.
nOption
An ART-defined control option constant .
lpValue
A far pointer to the return value.

Description:

This function returns a value of the control option specified by nOption parameters. See the function ART_control_option_set () for a list of the control option constants.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_control_option_set

Group: Control

Declaration:

AT_ERRCOUNT ART_control_option_set(HIGEAR hIGear,
    AT_MODE nOption,
    const LPVOID lpValue
    );

Arguments:

hIGear
HIGEAR handle of an image.
nOption
An ART-defined constant for the Library option to change.
lpValue
A far pointer to a new value for the option.

Description:

This function modifies default library settings that changes the default behavior of the library. nOption specifies the option to set. The following list describes the available options and their default values:

Option
Type
Default
Description
ART_CONTROL_CLIP_TEXT
BOOL
TRUE
Text marks are clipped if they do not fit within the bounds of the annotation.
ART_CONTROL_CREATE_SCROLL
BOOL
FALSE
Does auto scrolling for the zoomed image when annotation is created. Applicable for Filled Rectangle Hollow Rectangle, Highlighter, Typed text, Attach-a-Note, RTF text, Text file, Text Stamp, Hot Spot, Redaction, Button, Encryption, Filled Ellipse and Hollow Ellipse marks.
ART_CONTROL_DISABLE_CLIPPING
BOOL
FALSE
Disables clipping
ART_CONTROL_DISABLE_PPM_FOR_FONTS
BOOL
FALSE
Disables PPM in font size calculations. If TRUE tells ImageGear to ignore the image resolution when displaying text annotations.
See also description of ART_MARK_ATTRIBUTES structure and ART_DISABLE_PPM_FOR_FONTS_GET/ART_DISABLE_PPM_FOR_FONTS_SET macros
ART_CONTROL_DO_NOT_MODIFY_CURSOR
BOOL
FASLE
Disables cursor modifications
ART_CONTROL_ENABLE_SELECTION_UNDO
BOOL
TRUE
If this option is set to FALSE, the selections are not placed to undo stack.
ART_CONTROL_FULL_TEXTMARKS_SELECT
BOOL
FALSE
If TRUE enables selecting a text mark using a mouse click when the text is not visible.
ART_CONTROL_LARGEFONTS_ENABLE
BOOL
FALSE
If TRUE then the use of very large fonts are enabled for text marks.
ART_CONTROL_LOAD_ORIENTATION
BOOL
TRUE
Enables loading an annotation with or without orientation
ART_CONTROL_PRINT_ENABLE
BOOL
TRUE
Enables printing of marks with the image
ART_CONTROL_RECT_SELECTION
BOOL
TRUE
Indicates the selection width of the rectangle around the mark
ART_CONTROL_RESIZE_ENABLE
BOOL
TRUE
This enables marks resizing while in the Edit Mode.
ART_CONTROL_SAVE_ENABLE
BOOL
TRUE
Enables saving of marks as an embeded file with a TIFF image
ART_CONTROL_SAVE_ORIENTATION
BOOL
TRUE
Enables saving an annotation with or without orientation
ART_CONTROL_SELECT_NO_CLIP
BOOL
FALSE
Ignores clipping during selection
ART_CONTROL_SELECT_SCROLL
BOOL
FALSE
Scroll and select at the same time
ART_CONTROL_SHADOW_FONTS
BOOL
FALSE
Enables shadow fonts
ART_CONTROL_SHOW_LOCKS
BOOL
FALSE
Whether to show padlocks on marks that have access locked
ART_CONTROL_SHOW_TEXT_WARNING
BOOL
FALSE
Whether to show warning text or not
ART_CONTROL_USE_ONE_AS_FALSE
BOOL
FALSE
Enables using 1 as FALSE value
ART_CONTROL_WANG_LOAD_COMPATIBILITY
BOOL
FALSE
Disables Wang compatibility for load
ART_CONTROL_WANG_SAVE_COMPATIBILITY
BOOL
FALSE
Disables Wang compatibility for save

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
nErrcount = ART_control_option_set(hIGear,
ART_CONTROL_SHOW_LOCKS, TRUE);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_edit_copy

Group: Clipboard

Declaration:

AT_ERRCOUNT ART_edit_copy(HIGEAR hIGear,
    LPART_MARK_INDEX lpMarkIndex,
    DWORD dwMarkCount
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMarkIndex
A far pointer to an array list of mark identifiers
dwMarkCount
A variable of type DWORD which tells ART the number of marks to copy to the clipboard. This number indicates the number of mark indexes in the lpMarkIndex array.

Description:

This function copies an array of marks and places them on the clipboard.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • The memory pointed to by lpMarkIndex is invalid.
  • One or more of the indexes in lpMarkIndex is not valid.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
ERRCOUNT nErrcount; /* tally of IG errors on the */
/* stack   */
ART_MARK_INDEX lpMarkIndex; /* number of mark(s) */
/* to copy toclipboard */
DWORD dwMarkCount; /* # of marks that have been */
/* selected  */
HGLOBAL hGlobal; /* Windows handle to memory */
/* area   */
. . .
case ID_EDIT_COPY:
nErrcount = ART_mark_select_count(hIGear,
   &dwMarkCount);
hGlobal = GlobalAlloc(GMEM_MOVEABLE, dwMarkCount *
sizeof(ART_MARK_INDEX));
lpMarkIndex=(LPART_MARK_INDEX)GlobalLock(hGlobal);
nErrcount =
ART_mark_selected_first(hIGear,lpMarkIndex);
for (i = 1; i < (INT)dwMarkCount; i++)
{
lpMarkIndex[i] = lpMarkIndex[i - 1];
nErrcount = ART_mark_selected_next(hIGear,
lpMarkIndex + i);
}
nErrcount = ART_edit_copy(hIGear, lpMarkIndex,
dwMarkCount);
GlobalUnlock(hGlobal);
GlobalFree(hGlobal);
break;

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_edit_cut

Group: Clipboard

Declaration:

AT_ERRCOUNT ART_edit_cut(HIGEAR hIGear,
    LPART_MARK_INDEX lpMarkIndex,
    UINT nMarkCount
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMarkIndex
A far pointer to an array list of mark identifiers
nMarkCount
A variable of type UNIT which tells ART the number of marks in the list.

Description:

This function cuts an array list of marks and places it on the clipboard.

NOTE: The cut marks are visible until the screen is repainted. Use ART_GUI_mark_paint()function.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • The memory pointed to by lpMarkIndex is invalid.
  • One or more of the indexes in lpMarkIndex is not valid.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
AT_ERRCOUNT nErrcount; /* tally of IG errors on stack */
DWORD dwMarkCount; /* number of marks selected */
HGLOBAL hGlobal; /* Windows handle to  */
/* memory area  */
AT_MARK_INDEX lpMarkIndex; /* index to mark(s) */
HWND hWnd;  /* Windows handle to  */
/* image window  */
case ID_EDIT_CUT:
nErrcount = ART_mark_select_count(hIGear,
   &dwMarkCount);
hGlobal = GlobalAlloc(GMEM_MOVEABLE, dwMarkCount *
sizeof(ART_MARK_INDEX));
lpMarkIndex = (LPART_MARK_INDEX)GlobalLock(hGlobal);
nErrcount =
ART_mark_selected_first(hIGear,lpMarkIndex);
for (i = 1; i < (INT)dwMarkCount; i++)
{
lpMarkIndex[i] = lpMarkIndex[i - 1];
nErrcount = ART_mark_selected_next(hIGear,
lpMarkIndex + i);
}
nErrcount = ART_edit_cut(hIGear, lpMarkIndex,
dwMarkCount);
nErrcount = ART_GUI_mark_paint(hIGear, IG_GRP_DEFAULT,
ART_INVALID_ID, hWnd, TRUE);
GlobalUnlock(hGlobal);
GlobalFree(hGlobal);
break;

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_edit_paste

Group: Clipboard

Declaration:

AT_ERRCOUNT ART_edit_paste(HIGEAR hIGear,
    HWND hWnd,
    DWORD dwGrpID
    );

Arguments:

hIGear
HIGEAR handle to the image
hWnd
HWND handle to the window
dwGrpID
Identifier of group

Description:

This function pastes one or more marks from the clipboard to the current HIGEAR image. The marks are pasted on top of the image.

NOTE: The pasted marks are not visible until the screen is repainted. Use ART_GUI_mark_paint() function.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
AT_ERRCOUNT nErrcount; /* tally of IG errors on stack */
DWORD dwMarkCount; /* # of marks available  */
/* for paste  */
HWND hWnd; /* Windows handle to  */
/* image window  */
DWORD dwGrpID;
nErrcount = ART_edit_paste_count(hIGear, &dwMarkCount);
if (dwMarkCount > 1)
{
dwGrpID = IG_GRP_DEFAULT;
nErrcount = ART_edit_paste(hIGear, hWnd, dwGrpID);
nErrcount = ART_GUI_mark_paint(hIGear, dwGrpID,
ART_INVALID_ID, hWnd, TRUE);
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_edit_paste_count

Group: Clipboard

Declaration:

AT_ERRCOUNT ART_edit_paste_count(HIGEAR hIGear,
    LPDWORD lpMarkCount
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMarkCount
A far pointer which returns the number of mark items currently stored in the clipboard.

Description:

This function queries the clipboard for the number of marks available for pasting. The number of marks available for pasting from the clipboard is returned by lpMarkCount.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • The memory pointed to by lpMarkCount is invalid.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
AT_ERRCOUNT nErrcount; /* tally of IG errors on stack */
DWORD dwMarkCount; /* # of marks available  */
/* for paste  */
nErrcount = ART_edit_paste_count(hIGear, &dwMarkCount);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_edit_undo

Group: Undo

Declaration:

AT_ERRCOUNT ART_edit_undo(HIGEAR hIGear);

Arguments:

hIGear
HIGEAR handle to the image

Description:

This function reverses any changes made to any mark. Reversible operations include: creation, modification, selection, and deletions of marks. To clear the list of undos stored in memory, call ART_edit_undo_clear () function.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
AT_ERRCOUNT nErrcount; /* tally of IG errors on */
/* stack  */
HWND hWnd; /* Windows handle to */
/* image window  */
nErrcount = ART_edit_undo(hIGear);
nErrcount = ART_GUI_mark_paint(hIGear, IG_GRP_DEFAULT,
ART_INVALID_ID, hWnd, TRUE);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_edit_undo_clear

Group: Undo

Declaration:

AT_ERRCOUNT ART_edit_undo_clear(HIGEAR hIGear);

Arguments:

hIGear
HIGEAR handle to the image

Description:

This function clears all pending undos from memory. A subsequent call to ART_edit_undo () has no affect on the marks associated with the specified HIGEAR image.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

AT_ERRCOUNT nErrcount;
HIGEAR hIGear;
nErrcount = ART_edit_undo_clear(hIGear);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_edit_undo_count

Group: Undo

Declaration:

AT_ERRCOUNT ART_edit_undo_count(HIGEAR hIGear,
    LPDWORD lpUndoCount
    );

Arguments:

hIGear
HIGEAR handle to the image
lpUndoCount
A far pointer which returns the number of "undos" that can be performed

Description:

This function returns (in lpUndoCount) the number of times that ART_edit_undo () can be called.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • The memory pointed to by lpUndoCount is invalid.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear;      /* HIGEAR handle of image  */
AT_ERRCOUNT   nErrcount;    /* tally of IG errors on stack */
DWORD        dwMarkCount;  /* count of potential undos */
nErrcount = ART_edit_undo_count(hIGear, &dwMarkCount);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_edit_undo_enable

Group: Undo

Declaration:

AT_ERRCOUNT ART_edit_undo_enable(HIGEAR hIGear,
    BOOL bEnable
    );

Arguments:

hIGear
HIGEAR handle to the image
bEnable
A flag of type BOOL which allows you to enable or disable undo operations.

Description:

This function alllows you to enable or disable undo operations.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_edit_undo_record

Group: Undo

Declaration:

AT_ERRCOUNT ART_edit_undo_record(HIGEAR hIGear,
    BOOL fRecord
    );

Arguments:

hIGear
HIGEAR handle to the image
fRecord
A flag of type BOOL which enables or disables the recording of every action, so that the actions can later be undone. If TRUE, every action is recorded. Set to FALSE when you want recording to stop.

Description:

This function enables or disables the recording of every action. If you call ART_edit_undo_record(), with fRecord set to TRUE, every action is recorded until this function is called again with fRecord set to FALSE. The next time ART_edit_undo () is called, all previously recorded actions become undone.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
case ID_EDIT_SELECTALL:
ART_mark_select_count(hIGear, &dwSelectCount);
ART_mark_count(hIGear, &dwMarkCount);
/* if the number of marks equals the number of  */
/* selected marks, then we don't need to do this */
if (dwMarkCount != dwSelectCount)
{
ART_edit_undo_record(hIGear, TRUE);
ART_mark_first(hIGear, &hMarkIndex, NULL);
while (hMarkIndex != ART_INVALID_ID)
{
/* check to see if the mark is already */
/* selected */
ART_mark_is_selected(hIGear, hMarkIndex
&fSelected);
/* if not, then select it  */
if (!fSelected)
{
  ART_mark_select(hIGear, hMarkIndex, TRUE);
  ART_mark_next(hIGear, &hMarkIndex, NULL);
}
}
ART_edit_undo_record(hIGear, FALSE);
ART_GUI_mark_paint(hIGear, IG_GRP_DEFAULT,
ART_INVALID_ID, hWnd, TRUE);
}
break;

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_enable_rotation_get

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_enable_rotation_get (HIGEAR hIGear,
    LPBOOL lpbEnable
    );

Arguments:

hIGear
HIGEAR handle to the image
lpbEnable
A pointer to BOOL value

Description:

This function determines whether rotation is possible for an annotation. A value of TRUE allows rotation, a FALSE value does not allow rotation. The default is TRUE.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the f unction call.

Example:

HIGEAR hIGear;  /* HIGEAR handle of Image */
AT_ERRCOUNT nErrCount; /* Tally of IG errors on stack */
BOOL bEnable;
nErrCount = ART_enable_rotation_get (hIGear,&bEnable);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_enable_rotation_set

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_enable_rotation_set (HIGEAR hIGear,
            BOOL bEnable);

Arguments:

hIGear
HIGEAR handle to the image
bEnable
TRUE/FALSE

Description:

This function determines whether rotation is possible or not for an annotation. A value of TRUE allows rotation, a FALSE value does not allow rotation. The default value is TRUE.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear;  /* HIGEAR handle of Image */
AT_ERRCOUNT nErrCount; /* Tally of IG errors on stack */
nErrCount = ART_enable_rotation_set (hIGear,FALSE);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_file_append

Group: File

Declaration:

AT_ERRCOUNT ART_file_append(HIGEAR hIGear,
    HWND hWnd,
    DWORD dwGrpID,
    const LPSTR lpszFileName,
    DWORD dwPageNumber
    );

Arguments:

HIGear
HIGEAR handle to the image
HWnd
HWND handle of the image window
dwGrpID
Display group
lpszFileName
A far pointer to the name of the .ART file to append
dwPageNumber
Set this parameter to the page number to load if the .ART file has multiple pages. If the .ART file has one page, set this to 1.

Description:

This function appends the marks from a separate .ART file into the HIGEAR image.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR            hIGear;         /* HIGEAR handle of image */
char FAR          *szARTFile;      /* Name of the ART file  */
/* to import  */
char FAR          *szARTAppend;     /* Name of the ART file  */
/* to append  */
AT_ERRCOUNT        nErrcount;      /* Tally of IG errors on stack
*/
HWND               hWnd;
nErrcount = IG_load_file("JoeFax.BMP", &hIGear);
nErrcount = ART_file_import(hIGear, szARTFile, 1);
nErrcount = ART_file_append(hIGear, hWnd, IG_GRP_DEFAULT,
szARTAppend, 1);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_file_export

Group: File

Declaration:

AT_ERRCOUNT ART_file_export(HIGEAR hIGear,
    const LPSTR     lpszFileName,
    DWORD           dwPageNumber,
    BOOL            fReplace
    );

Arguments:

hIGear
HIGEAR handle to the image
lpszFileName
A far pointer to a NULL-terminated string containing the name of the .ART file to export.
dwPageNumber
Use this parameter to save one page of an exisitng file to a new file. Set this parameter to the page number of the .ART file that you want to save to the new file.
fReplace
This parameter is relevant if the target .ART file already exists and has multiple pages. Set to TRUE to replace the page; set to FALSE to insert the page.

Description:

This function saves the marks associated with the HIGEAR image to a separate .ART file.

Other ways to save marks:

  • Marks may be saved as an embedded file, but only if the format of the image file is TIFF - see ART_control_option_set ()
  • Marks may also be "burned in" permanently to an image using ART_image_burn_in ().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
char FAR *szARTFile; /* Name of the ART file  */
/* to export  */
AT_ERRCOUNT nErrcount; /* Tally of IG errors on stack */
szARTFile = "ARTsnack.ART";
nErrcount = IG_save_file(hIGear, "Snack.png",
IG_SAVE_PNG);
nErrcount = ART_file_export(hIGear, szARTFile, 2,
FALSE);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_file_import

Group: File

Declaration:

AT_ERRCOUNT ART_file_import(HIGEAR hIGear,
    HWND            hWnd,
    DWORD           dwGrpID,
    const LPSTR     lpszFileName,
    DWORD           dwPageNumber
    );

Arguments:

hIGear
HIGEAR handle to the image
hWnd
HWND handle to the window
dwGrpID
Identifier of group
lpszFileName
A far pointer to the name of the .ART file to import
dwPageNumber
Set this parameter to the page number to load if the .ART file has multiple pages. If the .ART file has one page, set this to 1.

Description:

This function loads the marks from a separate .ART file into the HIGEAR image. This is typically used for combining a newly loaded image with marks that were previously made and saved separately to an .ART file.

See also ART_file_import_ex () function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
char FAR *szARTFile; /* Name of the ART file  */
/* to import  */
AT_ERRCOUNT nErrcount; /* Tally of IG errors on stack */
HWND hWnd;
DWORD dwGrpID;
nErrcount = IG_load_file("JoeFax.BMP", &hIGear);
dwGrpID = IG_GRP_DEFAULT;
nErrcount = ART_file_import(hIGear, hWnd, dwGrpID,
szARTFile, 1);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_file_import_ex

Group: File

Declaration:

AT_ERRCOUNT ART_file_import_ex(HIGEAR hIGear,
    HWND            hWnd,
    DWORD           dwGrpID,
    const LPSTR     lpszFileName,
    DWORD           dwPageNumber,
    BOOL            bAppend
    );

Arguments:

hIGear
HIGEAR handle to the image
hWnd
HWND handle to the window
dwGrpID
Identifier of group
lpszFileName
A far pointer to the name of the .ART file to import
dwPageNumber
Set this parameter to the page number to load if the .ART file has multiple pages. If the .ART file has one page, set this to 1.
bAppend
If this parameter is TRUE then current ART annotation will be simply added to the specified .ART file. Otherwise previous annotation in the file will be replaced by the current one.

Description:

This function loads the marks from a separate .ART file into the HIGEAR image. This is typically used for combining a newly loaded image with marks that were previously made and saved separately to an .ART file.

This function is the same as ART_file_import () but has supplementary parameter bAppend that allows you to determine if current ART annotation should be simply added to the specified .ART file (TRUE), or replace the existed one (FALSE).

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_global_block_create

Group: Global Named Block Management

Declaration:

AT_ERRCOUNT ART_global_block_create(HIGEAR hIGear,
    const LPART_BLOCK_NAME lpBlockName,
    const LPVOID lpBlockData,
    DWORD dwBlockSize
    );

Arguments:

hIGear
HIGEAR handle to the image
lpBlockName
A far pointer to an 8 byte array of memory into which you set the type of block to create. The block type will be either an ART-defined constant beginning with ART_BLOCK_ or a user defined block. See ARTAPI.H for the full list of ART-defined constants.
lpBlockData
A far pointer of type VOID which points to the block data.
dwBlockSize
The size of lpBlockData, in bytes

Description:

This function creates a new global named block, or replaces an existing one. If a block of type lpBlockName exists, it is replaced by the new one. The block data pointed to by lpBlockData is copied into the new named block.

Unlike mark named blocks, which are associated with an individual mark, global named blocks are not associated with any mark - they act as default settings for the next created mark. When a new mark is created, some of its named blocks are created from the global named blocks.

NOTE: You may create your own global named blocks to store user-defined data.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • lpBlockName does not point to a valid address.
  • lpBlockData does not point to a valid address.
  • there is not enough memory to allocate dwBlockSize bytes of memory.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example

/* set the block size   */
dwBlockSize = sizeof(ART_ARROW) + sizeof(AT_POINT);
/* allocate memory for the arrow structure */
lpArrow = (LPART_ARROW)alloca((UINT)dwBlockSize);
/* initialize to zero   */
memset(lpArrow, 0, (UINT)dwBlockSize);
lpArrow->lArrowType  = ART_ARROW_POINTER;
lpArrow->lArrowEnd  = 0;
lpArrow->lArrowAngle = 15;
lpArrow->lArrowLength = 25;
/* create the named block and associate  */
/* it with this mark   */
ART_global_block_create(hIGear, ART_BLOCK_ANODAT,
lpArrow, dwBlockSize);
ART_GUI_tool_set (hIGear, &ma);
break;

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_global_block_delete

Group: Global Named Block Management

Declaration:

AT_ERRCOUNT ART_global_block_delete(HIGEAR hIGear,
    const LPART_BLOCK_NAME lpBlockName
    );

Arguments:

hIGear
HIGEAR handle to the image
lpBlockName
A far pointer to an 8-byte memory array contains the type of block to delete. The block type is either an ART-defined constant beginning with ART_BLOCK or a user-defined block. See ARTAPI.H for the full list of ART-defined constants.

Description:

This function deletes an existing global named block, lpBlockName, from the set of global named blocks. Reserved named blocks cannot be deleted. However, they may be modified by calling ART_global_block_create ()function.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • lpBlockName does not point to a valid address.
  • lpBlockName points to a reserved named block.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
nErrcount =
ART_global_block_delete(hIGear,"NOTES\000\000\000");

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_global_block_first

Group: Global Named Block Management

Declaration:

AT_ERRCOUNT ART_global_block_first(HIGEAR hIGear,
    LPART_BLOCK_NAME lpBlockName
    );

Arguments:

hIGear
HIGEAR handle to the image
lpBlockName
A far pointer to an 8 byte array of memory that returns the type of block to query. The block type is either an ART-defined constant beginning with ART_BLOCK or a user defined block. See ARTAPI.H for the full list of ART-defined constants.

Description:

This function gets the name of the first global block. The block data for the named block can be retrieved by calling ART_global_block_query ()function.

Call ART_global_block_next () function to get the block name of the named block that follows the one that was passed into lpBlockName. This function sets lpBlockName to zeroes if there are no global blocks. Block names are returned in no particular order.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • lpBlockName does not point to a valid address.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example

HIGEAR  hIGear; /* HIGEAR handle of image */
ART_BLOCK_NAME lpBlockName; /* returned type of first */
/* global block  */
AT_ERRCOUNT nErrcount; /* tally of IG errors on */
/* stack  */
nErrcount = ART_global_block_first(hIGear,&lpBlockName);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_global_block_next

Group: Global Named Block Management

Declaration:

AT_ERRCOUNT ART_global_block_next(HIGEAR hIGear,
    LPART_BLOCK_NAME lpBlockName
    );

Arguments:

hIGear
HIGEAR handle to the image
lpBlockName
A far pointer to an 8-byte array of memory that returns the type of block to query. The block type is either an ART-defined constant beginning with ART_BLOCK or a user-defined block. See ARTAPI.H file for the full list of ART-defined constants.

Description:

This function gets the name of the next global block associated with the HIGEAR image, and iterates through all global named blocks. .ART_global_block_first () gets the first block name. The block data for the named block is retrieved by calling ART_global_block_query ()function. This function sets lpBlockName to zero when there are no more blocks, providing you with an easy check for ending your loop. Block names are returned in no particular order.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • lpBlockName does not point to a valid address.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
ART_BLOCK_NAME lpBlockName; /* returned type of first */
/* global block  */
AT_ERRCOUNT nErrcount; /* tally of IG errors */
/* on stack  */
nErrcount = ART_global_block_first(hIGear,&lpBlockName);
while (*lpBlockName)
{
  if (!memcmp(&lpBlockName, "EYEBALL\0", 8))
break;
nErrcount = ART_global_block_next(hIGear,
&lpBlockName);
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_global_block_query

Group: Global Named Block Management

Declaration:

AT_ERRCOUNT ART_global_block_query(HIGEAR hIGear,
    const LPART_BLOCK_NAME lpBlockName,
    LPVOID lpBlockData,
    LPDWORD lpBlockSize
    );

Arguments:

hIGear
HIGEAR handle to the image
lpBlockName
A far pointer to an 8 byte array of memory that specifies the type of block to query. The block type is either an ART-defined constant beginning with ART_BLOCK or a user-defined block. See ARTAPI.H file for the full list of ART-defined constants.
lpBlockData
A far VOID pointer which returns block data.
lpBlockSize
The size of lpBlockData (in bytes).

Description:

This function queries a global named block for its data returning it in lpBlockData. The buffer pointed to by lpBlockData must be large enough to fit the named block data. The size of the block is returned by lpBlockSize.

To find the size of a buffer necessary to hold the block data, call ART_global_block_query() with lpBlockData set to NULL. lpBlockSize returns the size of the block.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • lpBlockName does not point to a valid address.
  • lpBlockData does not point to a valid address or is not NULL.
  • lpBlockData points to a buffer smaller than the block data.
  • lpBlockSize points to an invalid address.
  • lpBlockSize points to a value smaller than the size of the block data.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
LPVOID blockData; /* data in global block  */
DWORD blockSize; /* size of block, in bytes */
AT_ERRCOUNT nErrCount; /* number of errors on the */
/* error stack  */
/* get the block size */
nErrCount = ART_global_block_query(hIGear,
ART_BLOCK_GROUP, NULL, &blockSize);
blockData = (LPVOID)alloca(blockSize);
/* but the data into blockData */
nErrCount = ART_global_block_query(hIGear,
ART_BLOCK_GROUP, blockData, &blockSize);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_group_access

Group: Mark Grouping

Declaration:

AT_ERRCOUNT ART_group_access(HIGEAR hIGear,
    const LPSTR szGroupName,
    BOOL fEnable
    );

Arguments:

hIGear
HIGEAR handle to the image
szGroupName
A far pointer to a null-terminated string that tells ART which group of marks' access to change.
fEnable
A flag of type BOOL that tells ART whether to allow editing for all the marks in the group specified by szGroupName.

Description:

This function sets the access control (editable or view only) for all of the marks in the group specified by szGroupName. When fEnable is set to TRUE, the end user can edit or modify marks in the group; when set to FALSE the end user cannot edit or modify marks in the group.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • szGroupName does not point to a valid address.
  • No group matches szGroupName.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
char FAR *szGroupName; /* type of group to make  */
/* accessible  */
/* Deny access to the MIS Group */
szGroupName = "MIS Group";
nErrcount = ART_group_access(hIGear,szGroupName,FALSE);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_group_bring_to_front

Group: Mark Grouping

Declaration:

AT_ERRCOUNT ART_group_bring_to_front(HIGEAR hIGear,
    const LPSTR szGroupName
    );

Arguments:

hIGear
HIGEAR handle to the image
szGroupName
Far pointer to a NULL-terminated string containing the mark group name

Description:

This function moves a group of marks to the front of the stacking order.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • No group matches szGroupName.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
char FAR *szGroupName; /* Name of group to */
/* bring to front  */
nErrcount = ART_group_bring_to_front(hIGear,szGroupName);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_group_delete

Group: Mark Grouping

Declaration:

AT_ERRCOUNT ART_group_delete(HIGEAR hIGear,
    const LPSTR szGroupName
    );

Arguments:

hIGear
HIGEAR handle to the image
szGroupName
A far pointer to a NULL-terminated string that contains the name of the group that contains the marks for deletion.

Description:

This function deletes any marks that belong to the mark group.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • szGroupName does not point to a valid address.
  • No group matches szGroupName.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
char FAR *szGroupName; /* name of group to delete */
szGroupName = "Sticky Notes Group";
nErrcount = ART_group_delete(hIGear, szGroupName);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_group_edit_copy

Group: Mark Grouping

Declaration:

AT_ERRCOUNT ART_group_edit_copy(HIGEAR hIGear,
    const LPSTR szGroupName
    );

Arguments:

hIGear
HIGEAR handle to the image
szGroupName
A far pointer to a NULL-terminated string that contains the group of marks to copy to the clipboard

Description:

This function copies a group of marks to the clipboard. Use szGroupName to tell ART which group of marks to copy.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • No group matches szGroupName.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
char FAR *szGroupName; /* name of group from */
/* which to copy mark */
AT_ERRCOUNT nErrcount; /* tally of IG errors */
/* on stack  */
/* Copy the Sticky Notes Group to the clipboard */
szGroupName = "Sticky Notes Group";
nErrcount = ART_group_edit_copy(hIGear, szGroupName);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_group_edit_cut

Group: Mark Grouping

Declaration:

AT_ERRCOUNT ART_group_edit_cut(HIGEAR hIGear,
    const LPSTR szGroupName
    );

Arguments:

hIGear
HIGEAR handle to the image
szGroupName
A far pointer to a null-terminated string that tells ART which group of marks to cut from the HIGEAR image and copy to the clipboard

Description:

This function cuts a group of marks from the HIGEAR image and copies them to the clipboard.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • No group matches szGroupName.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
char FAR *szGroupName; /* name of group from  */
/* which to cut marks */
AT_ERRCOUNT nErrcount; /* tally of IG errors */
/* on stack  */
szGroupName = "Time Group";
nErrcount = ART_group_edit_cut(hIGear, szGroupName);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_group_select

Group: Mark Grouping

Declaration:

AT_ERRCOUNT ART_group_select(HIGEAR hIGear,
    const LPART_GROUP_NAME szGroupName,
    BOOL fSelect
    );

Arguments:

hIGear
HIGEAR handle to the image
lpGroupName
A far pointer to a NULL-terminated string that identifies the name of the mark group for selection.
fSelect
A flag of type BOOL that tells ART whether to select or deselect the marks in the specified group. If set to TRUE, the marks in the group are selected.

Description:

This function selects or deselects all marks that belong to the specified mark group. When fSelect is set to TRUE, all marks in the group are selected. When fSelect is set to FALSE, all marks in the group are deselected.

An error is set set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • szGroupName does not point to a valid address.
  • No group matches szGroupName.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
char FAR *szGroupName; /* Type of Group to */
/* select all marks from */
szGroupName = "Former Employee Group";
nErrcount = ART_group_select(hIGear, szGroupName, TRUE);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_group_send_to_back

Group: Mark Grouping

Declaration:

AT_ERRCOUNT ART_group_send_to_back (HIGEAR hIGear,
    const LPSTR szGroupName
    );

Arguments:

hIGear
HIGEAR handle to the image
szGroupName
A far pointer to a NULL-terminated string that contains the name of the mark group.

Description:

This function moves a group of marks to the back of the stacking order. An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • No group matches szGroupName.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
char FAR *szGroupName; /* Name of group to bring */
/* to front  */
nErrcount = ART_group_send_to_back(hIGear, szGroupName);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_group_visible

Group: Mark Grouping

Declaration:

AT_ERRCOUNT ART_group_visible(HIGEAR hIGear,
    const LPSTR szGroupName,
    BOOL fVisible
    );

Arguments:

hIGear
HIGEAR handle to the image
szGroupName
A far pointer to a NULL-terminated string that identifies the name of the mark group to make visible
fVisible
A flag of type BOOL that tells ART whether to make all of the marks in the group visible. If set to TRUE, all marks become visible.

Description:

This function sets the visibility (hide or show) of all of the marks in the group identified by szGroupName. The fVisible field of each of the mark's attribute structures will be set to TRUE or FALSE, depending on the fVisible parameter.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • szGroupName does not point to a valid address.
  • No group matches szGroupName.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
char FAR *szGroupName; /* type of group of marks */
/* to make visible  */
HIGEAR hIGear; /* HIGEAR handle of image */
LPSTR szGroupName; /* data in global block  */
DWORD dwBlockSize; /* size of block, in bytes */
AT_ERRCOUNT nErrCount; /* number of errors on the */
/* error stack  */
nErrCount = ART_global_block_query(hIGear,
ART_BLOCK_GROUP, NULL, &dwBlockSize);
szGroupName = (LPSTR)alloca(dwBlockSize);
nErrCount = ART_global_block_query(hIGear, ART_BLOCK_GROUP,
(LPVOID)szGroupName, &dwBlockSize);
nErrcount = ART_group_visible(hIGear,szGroupName,TRUE);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_cursor_query

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ART_GUI_cursor_query(HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWnd,
    AT_MODE nMode,
    const LPAT_POINT lpPoint,
    HCURSOR FAR *lpCursor,
    LPAT_MODE lpCursorType
    );

Arguments:

hIGear
HIGEAR handle to the image
dwGrpID
Identifier of group
hWnd
Windows handle to the image window
nMode
An ART-defined constant of type AT_MODE that indicates the current user mode: run mode or edit mode.
lpPoint
An ART-defined constant of type AT_POINT that gives the screen coordinates of the mouse position
lpCursor
A far pointer to a Window's cursor. ART will fill the memory that the HCURSOR pointer points to with a cursor of type HCURSOR.
lpCursorType
A far pointer to an ART-defined constant of type AT_MODE that gives the suggested type of cursor to use.

Description:

This function returns the type of cursor that is used when the mouse passes over marks or resize handles. You can set nMode to a constant beginning with ART_MODE_ to find out what cursor is used in a particular mode (run or edit). The cursor type is chosen by ART. You then call the Windows function SetCursor() and use ART's cursor or a cursor of your own.

This function is called in response to a Windows WM_SETCURSOR message with nMode set to either the run or edit mode constant. lpPoint is the current position of the mouse cursor. lpCursor returns the cursor the library determined for use. If lpCursorType is not NULL, it is set with a constant identifier that indicates which one of the standard cursors is set in lpCursor. The application can choose to use its own cursor for the given lpCursorType. Do not delete the cursor returned in lpCursor with DeleteObject().

In the lpCursorType parameter, one of these values is returned:

ART_CURSOR_NESW
ART_CURSOR_ANY
ART_CURSOR_NS
ART_CURSOR_NOT_OVER_MARK
ART_CURSOR_NWSE
ART_CURSOR_SELECT
ART_CURSOR_EW
ART_CURSOR_MOVE
ART_CURSOR_WE
ART_CURSOR_OVER_MARK
ART_CURSOR_SENW
ART_CURSOR_CREATE_MARK
ART_CURSOR_SN
ART_CURSOR_WAIT
ART_CURSOR_SWNE

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • hWnd is not a valid window.
  • nMode is not a valid user mode constant.
  • lpPoint is not a valid address.
  • lpCursor is not a valid address (or NULL.)
  • lpCursorType is not a valid address (or NULL.)

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
AT_POINT pt; /* Cursor position  */
HWND hwnd;  /* Windows handle to the   */
/* window    */
AT_MODE nUserMode; /* Run mode or edit mode */
DWORD dwGrpID;
nUserMode = ART_MODE_EDIT;
. . .
case WM_SETCURSOR:
if (IG_image_is_valid(hIGear))
{
GetCursorPos(&ptPos);
ScreenToClient(hWnd, &ptPos);
pt.x = ptPos.x, pt.y = ptPos.y;
/* Ask ART to provide the cursor */
dwGrpID = IG_GRP_DEFAULT;
ART_GUI_cursor_query(hIGear, dwGrpID,
hWnd, nUserMode,
&pt, &hCursor, NULL);
SetCursor(hCursor);
return TRUE;
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_interaction_process

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ART_GUI_interaction_process(HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWnd,
    UINT nMessage,
    AT_MODE nMode,
    LPAT_POINT lpPoint
    );

Arguments:

hIGear
HIGEAR handle to the image
dwGrpID
Identifier of group
hWnd
Windows handle to the image window
nMessage
Windows message
nMode
An ART-defined constant of type AT_MODE that sets the image to run mode or edit mode.
lpPoint
A far pointer to an ART-defined constant of type AT_POINT that gives the cursor position's screen coordinates.

Description:

This function handles user interaction with marks. This function is called in response to a Windows WM_LBUTTONDOWN, WM_LBUTTONUP, and WM_LBUTTONDBLCLK message. The nMode parameter is set to either the user-run mode or user-edit mode constants. lpPoint is the current position where the mouse button was pressed. The library handles creating, moving, re-sizing, selecting and user run-mode interaction with marks.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • hWnd is not a valid window.
  • nMode is not a valid user mode constant.
  • lpPoint is not a valid address.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example

HIGEAR hIGear; /* HIGEAR handle of image  */
AT_POINT pt; /* Cursor position  */
HWND hwnd; /* Windows handle to the window */
AT_MODE nUserMode; /* Run mode or edit mode */
UINT msg; /* Windows message  */
DWORD dwGrpID;
nUserMode = ART_MODE_RUN;
case WM_LBUTTONDOWN:
case WM_LBUTTONDBLCLK:
case WM_LBUTTONUP:
if (IG_image_is_valid(hIGear))
{
pt.x = LOWORD(lParam);
pt.y = HIWORD(lParam);
dwGrpID = IG_GRP_DEFAULT;
ART_GUI_interaction_process(hIGear, dwGrpID, hWnd,
msg, nUserMode, &pt);
}
break;

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_mark_hit_test

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ART_GUI_mark_hit_test(HIGEAR hIGear,
    HWND hWnd,
    DWORD dwGrpID,
    const LPAT_RECT lpRect,
    LPART_MARK_INDEX lpMarkIndex,
    DWORD dwMarkCount,
    LPDWORD lpMarkCount,
    LPAT_MODE lpResizeBox,
    LPDWORD lpBoxIndex
    );

Arguments:

hIGear
HIGEAR handle to the image
hWnd
HWND handle to the window
dwGrpID
Identifier of group
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of image to search for marks.
lpMarkIndex
A far pointer returning the indexes
dwMarkCount
The amount of memory available for returned marks
lpMarkCount
The number of marks actually returned
lpResizeBox
A far pointer to a defined constant of type AT_MODE, only used if the rectangle lpRect is an individual point and is over a resize handle.
lpBoxIndex
A far pointer to the index of the resize handle, or NULL if the return value is not needed.

Description:

This function returns all mark indexes that are within the rectangle specified by lpRect. The rectangle represents screen coordinates.

There is some variation in what is returned:

  • If the coordinates passed to lpRect define a point - in other words, the left and top are equal to the right and bottom:
  • and the point is over a mark: the mark will be returned.
  • and the point is over a resize box: an identifier indicating whichresize box the point is over is returned. If the resize box is part of a line, free-hand line, polyline, polygon or arrow, the index of the resize box is also returned.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of */
/* image  */
AT_ERRCOUNT nErrcount; /* Tally of IG errors on */
/* stack  */
AT_RECT  MarkRect; /* Region of image to */
/* query  */
ART_MARK_INDEX MarkIndexes; /* Array of mark indexes */
DWORD MarkCount; /* Space available for */
/* marks or # of marks */
AT_MODE  lpResizeBox; /* Handle to resize box, */
/* if there is one  */
AT_DIMENSION nWidth, /* Original width and */
/* height  */
nHeight;
UINT nBpp; /* Bits per pixel  */
/* (not used)  */
AT_DIMENSION nHalfWidth, /* Will hold half the */
/* width  */
nHalfHeight; /* and half the height */
HWND HWnd;
DWORD dwGrpID;
/* Set rectangle to half the size of the image, centered */
if ( IG_image_is_valid (hIGear) )
{
IG_image_dimensions_get ( &hIGear, &nWidth, &nHeight,
&nBpp );
nHalfWidth = nWidth / 2;
nHalfHeight = nHeight / 2;
MarkRect.left  = nHalfWidth / 2;
MarkRect.right = MarkRect.left + nHalfWidth - 1;
MarkRect.top  = nHalfHeight / 2;
MarkRect.bottom = MarkRect.top + nHalfHeight - 1;
dwGrpID = IG_GRP_DEFAULT;
nErrcount = ART_GUI_mark_hit_test(hIGear, hWnd,
dwGroupID, &MarkRect,
&MarkIndexes, MarkCount, &MarkCount, &lpResizeBox,
&lpBoxIndex);
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_mark_paint

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ART_GUI_mark_paint(HIGEAR hIGear,
    DWORD dwGrpID,
    ART_MARK_INDEX hMarkIndex,
    HWND hWnd,
    BOOL fDraw
    );

Arguments:

hIGear
HIGEAR handle to the image
dwGrpID
Identifier of group
hMarkIndex
Index of the mark
hWnd
Windows handle to the image window
fDraw
Flag of type BOOL that tells ART whether or not to paint the mark. If set to TRUE, ART paints the mark; if set to FALSE, ART temporarily erases the mark.

Description:

This function draws or redraws the mark referenced by hMarkIndex, in the window hWnd. The flag fDraw tells whether to paint or erase the mark.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • hMarkIndex does not reference a valid mark.
  • hWnd is not a valid window handle.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example

HIGEAR  hIGear; /* HIGEAR handle of
  image */
ART_MARK_ATTRIBUTES ma; /* Structure to hold
mark's attributes */
AT_MARK_INDEX  hMarkIndex; /* Index to the */
/* mark  */
AT_ERRCOUNT  nErrcount; /* Tally of IG */
/* errors on the */
/* stack  */
HWND  hWnd; /* Windows handle */
/* to the image */
/* window  */
DWORD  dwGrpID;
nErrcount = ART_mark_create(hIGear, &ma, &hMarkIndex);
if (nErrcount != 0)
{
  ErrorReport(hWnd);
}
else
{
dwGrpID = IG_GRP_DEFAULT;
ART_GUI_mark_paint(hIGear, dwGrpID, hMarkIndex,
hWnd, TRUE);
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_property_sheet_create

Group: Graphical Use Interface

Declaration:

BOOL FAR PASCAL ART_GUI_property_sheet_create(HWND hWndParent,
    const LPAT_DIB lpDIB,
    HARTPROPSHEET FAR *lpPropertySheet
    );

Arguments:

hWndParent
A Windows handle to the Window of the toolbar
lpDIB
A far pointer to the DIB header of underlying image
lpPropertySheet
A far pointer that returns an ART handle to the new Property sheet

Description:

This function creates a "property sheet" - a dialog box that allows you to modify the attributes of a mark object. The screen capture shown below is a property sheet for an Attach-a-Note object. Each type of mark has a different property sheet.

NOTE: Please call ART_GUI_property_sheet_init() to initialize the settings and ART_GUI_property_sheet_show() to display it.

Bits Per Pixel: All

Return Value:

Returns TRUE if a "property sheet" is created successfully, otherwise returns FALSE.

Example

HIGEAR  hIGear; /* HIGEAR handle of
  image  */
HARTPROPSHEET hPropertySheet; /* handle to the */
/* property sheet */
AT_ERRCOUNT nErrcount;  /* tally of  */
/* ImageGear errors*/
AT_DIB lpDIB;  /* pointer to the */
/* DIB header */
nErrcount = IG_image_DIB_pntr_get(hIGear, &lpDIB);
nErrcount = ART_GUI_property_sheet_create(hWnd, lpDIB,
&hPropertySheet);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_property_sheet_destroy

Group: Graphical User Interface

Declaration:

BOOL FAR PASCAL ART_GUI_property_sheet_destroy (
    HARTPROPSHEET hPropertySheet
    );

Arguments:

hPropertySheet
ART Handle to the Property Sheet

Description:

This function destroys the property sheet referenced by hPropertySheet.

Bits Per Pixel: All

Return Value:

Returns TRUE if successful, FALSE if there was an error. An error occurs if hPropertySheet is not a valid handle.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
HARTPROPSHEET hPropertySheet; /* handle to the */
/* property sheet */
nErrcount =
ART_GUI_property_sheet_destroy(hPropertySheet);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_property_sheet_init

Group: Graphical User Interface

Declaration:

BOOL FAR PASCAL ART_GUI_property_sheet_init(
    HARTPROPSHEET hPropertySheet,
    AT_MODE const fInitFlags,
    LPART_MARK_ATTRIBUTES lpMarkAttr,
    const LPART_BLOCK_NAME lpBlockName,
    const LPVOID lpBlockData,
    DWORD dwBlockSize
    );

Arguments:

hPropertySheet
ART handle to the Property Sheet
fInitFlags
A bit flag that takes one or more AT_MODE variables. The possible settings are ART_INIT_ATTRIBUTES, ART_INIT_NAMED_BLOCK, or ART_INIT_GLOBAL_BLOCK.
lpMarkAttr
Set Mark Attributes to initialize the property sheet, or NULL.
lpBlockName
Set to the name of the Named Block to initialize the property sheet, or NULL.
lpBlockData
Set to the Global Block Data to initialize the property sheet, or NULL.
dwBlockSize
Set to the size of the named block or 0L if you are not initializing a named block data.

Description:

This function initializes the values in the property sheet with the values from the ART_MARK_ATTRIBUTES structure and one or more named blocks. Set fInitFlags to one or more of the constants shown above to tell ART what you are initializing in the property sheet.

Call this function after ART_GUI_property_sheet_create (), and before ART_GUI_property_sheet_show ().

Bits Per Pixel: All

Return Value:

Returns TRUE if successful, FALSE if there was an error. An error occurs if hPropertySheet is not a valid handle.

Example:

HIGEAR  hIGear; /* HIGEAR handle of image */
HARTPROPSHEET hPropertySheet;/* handle to the property */
/* sheet  */
ART_BLOCK_NAME lpBlockName; /* name of the named block*/
VOID  lpBlockData; /* data from the block */
DWORD  dwBlockSize; /* size of the block */
HWND  hGlobal; /* Window handle to global*/
/* mem  */
/* Go to first named block for the mark object and get
block name */
nErrcount = ART_mark_block_first(hIGear, hMarkIndex,
&byBlockName);
while (*byBlockName)
{
/* while there are still named blocks, get their size */
nErrcount = ART_mark_block_query(hIGear, hMarkIndex,
&byBlockName, NULL, &dwBlockSize);
if (dwBlockSize)
{
hGlobal = GlobalAlloc(GMEM_MOVEABLE,
(UINT)dwBlockSize);
lpBlockData = GlobalLock(hGlobal);
if (lpBlockData)  /* if there is any block */
/* data, read it  */
{
  nErrcount = ART_mark_block_query(hIGear,
hMarkIndex, &byBlockName, lpBlockData,
&dwBlockSize);
  /* initialize the property sheet with the */
  /* current named block data  */
  nErrcount =
    ART_GUI_property_sheet_init(hPropertySheet,
    ART_GUI_INIT_NAMED_BLOCK, NULL,
    &byBlockName, lpBlockData, dwBlockSize);
}
GlobalUnlock(hGlobal);
GlobalFree(hGlobal);
}
/* move to next named block */
ART_mark_block_next(hIGear, hMarkIndex,&byBlockName);
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_property_sheet_show

Group: Graphical User Interface

Declaration:

BOOL FAR PASCAL ART_GUI_property_sheet_show(
    HARTPROPSHEET hPropertySheet
    );

Arguments:

hPropertySheet
ART handle to the Property Sheet

Description:

This function displays the property sheet. It returns TRUE if the user clicked OK to exit; it returns FALSE if the user clicked Cancel to exit.

Bits Per Pixel: All

Return Value:

Returns TRUE is the user clicked OK; FALSE if the user pressed Cancel.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
AT_ERRCOUNT nErrcount; /* tally of ImageGear */
/* errors  */
HARTPROPSHEET hPropertySheet; /* handle to the */
/* property sheet  */
ART_MARK_ATTRIBUTES ma; /* Structure for mark */
/* attributes  */
/* If the user clicked OK, query the property sheet */
if (ART_GUI_property_sheet_show(hPropertySheet))
{
/* first query the attributes settings */
nErrcount =
ART_GUI_property_sheet_query(hPropertySheet,
ART_GUI_QUERY_ATTRIBUTES,&ma,NULL,NULL,NULL);
}
. . .

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_property_sheet_query

Group: Graphical User Interface

Declaration:

BOOL FAR PASCAL ART_GUI_property_sheet_query(HARTPROPSHEET
hPropertySheet,
    AT_MODE fQueryFlags,
    LPART_MARK_ATTRIBUTES lpMarkAttr,
    const LPART_BLOCK_NAME lpBlockName,
    LPVOID lpBlockData,
    LPDWORD lpBlockSize
    );

Arguments:

hPropertySheet
ART handle to the Property Sheet
fQueryFlags
Query flags
lpMarkAttr
Attributes return
lpBlockName
Named block name
lpBlockData
Block Data return, or NULL
lpBlockSize
Block size return

Description:

This function reads the settings of the property sheet referenced by hPropertySheet, and is called when the user clicks OK. fQueryFlags is a bit flag that queries ART_MARK_ATTRIBUTES structure and one or more named blocks. When changes are made to the property sheet that reflect properties stored in the ART_MARK_ATTRIBUTES structure, call ART_mark_modify () to update the structure. If changes were made to a named block, call ART_mark_block_create () to overwrite the old data with the new data.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_resize_handle_size_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ART_GUI_resize_handle_size_get(HIGEAR hIGear,
    LPDWORD lpdwSize
    );

Arguments:

hIGear
HIGEAR handle to the image
lpdwSize
A pointer to a size of the sizing handle

Description:

This function gets the region defined as the sizing handle.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR       hIGear;          /* HIGEAR handle of image */
AT_ERRCOUNT  nErrcount;       /* tally of IG errors on stack */
DWORD        dwSize
nErrcount = ART_GUI_resize_handle_size_get (hIGear, &dwSize);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_resize_handle_size_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ART_GUI_resize_handle_size_set(HIGEAR hIGear,
    DWORD dwSize
    );

Arguments:

hIGear
HIGEAR handle to the image
dwSize
Size of the sizing handle

Description:

This function sets the region defined as the sizing handle. Allows the handle size to be increased, to a size that allows it to be grabbed by a finger (for example, for use with a touch screen). This is a global property; it affects All HIGEAR handles.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR        hIGear;      /* HIGEAR handle of image */
AT_ERRCOUNT   nErrcount;   /* tally of IG errors on stack */
nErrcount = ART_GUI_resize_handle_size_set (hIGear, 20);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_text_flow

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ART_GUI_text_flow ( HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWnd,
    const LPART_MARK_INDEX lpMarkIndexes,
    DWORD dwMarkCount );

Arguments:

hIGear
HIGEAR handle to the image.
dwGrpID
Identifier of group.
hWnd
Windows handle to the image window to draw marks.
lpMarkIndexes
Array of text mark identifiers.
dwMarkCount
Number of mark in lpMarkIndexes array.

Description:

This function links text of annotation marks given by lpMarkIndexes parameter and distributes it between these marks according to their bounds so that all of the marks do not have overflowed text excluding may be the last one if the linked text needs more space to be drawn than the marks allow. If the text needs less space then the total mark bounds some of the marks may be empty. The function does not change the mark bounds and does not repaint them.

The function can be applied only for Typed Text(ART_MARK_TYPED_TEXT) and Attach-a-Note(ART_MARK_ATTACH_A_NOTE) marks. If the lpMarkIndexes array contains indexes of marks diferent from ART_MARK_TYPED_TEXT or ART_MARK_ATTACH_A_NOTE an error will be occurred and the function will do nothing.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

See example for LPFNIG_ART_TEXTOVERFLOWNOTIFYFUNC callback function.

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_text_overflow_check

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ART_GUI_text_overflow_check( HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWnd,
    ART_MARK_INDEX hMarkIndex,
    LPAT_RECT lprcPreferableBounds,
    LPDWORD lpdwOverflowedTextLength);

Arguments:

hIGear
HIGEAR handle to the image
dwGrpID
Identifier of group
hWnd
Windows handle to the image window to draw marks
hMarkIndex
Identifier of the mark
lprcPreferableBounds
Returns preferable mark bounds to draw whole mark text (cut to clip bounds)
lpdwOverflowed
TextLength
Returns the length of overflowed text (the last NULL is not included) or 0

Description:

This function checks the mark with text overflowed. It can be applied for ART_MARK_TYPED_TEXT, ART_MARK_ATTACH_A_NOTE and ART_MARK_TEXT_FROM_FILE marks only. If the mark has overflowed text the lpdwOverflowedTextLength returns the number of overflowed text characters. Otherwise it returns 0.

The lprcPreferableBounds returns rectangle of mark bounds enough to draw the whole text. It is made by expanding the mark bounds in direction the drawn text (from top to bottom direction) is cut to the image window clip bounds.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

See example for LPFNIG_ART_TEXTOVERFLOWNOTIFYFUNC callback function.

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_toolbar_button_get

Group: Graphical User Interface

Declaration:

BOOL FAR PASCAL ART_GUI_toolbar_button_get(HWND hwndToolBar,
    DWORD dwButtonID,
    LPDWORD lpFlags
    );

Arguments:

hWndToolBar
Set to the Windows handle to the toolbar
dwButtonID
Set to an ART-defined constant beginning with ART_BUTTON_.
lpFlags
A far pointer that returns the current settings for the state flags. One or more of the following flags is returned: ART_BUTTON_CHECKED, ART_BUTTON_ENABLED, ART_BUTTON_VISIBLE

Description:

This function gets the current state of the button specified by dwButtonID. Possible states include: ART_BUTTON_CHECKED - the button is pressed, ART_BUTTON_ENABLED - the button is not grayed out, and ART_BUTTON_VISIBLE - the button is not hidden. Pass it the handle to the toolbar, and pass it ART-defined constants beginning with ART_BUTTON_ to specify which button to query. lpFlags returns the current status of the button.

Bits Per Pixel: N/A

Return Value:

Returns TRUE if the button exists and is successfully queried; returns FALSE if the button of the specified ID does not exist.

Example:

HIGEAR  hIGear; /* HIGEAR handle of image */
BOOL bButton; /* Whether button exists */
/* on toolbar  */
DWORD lpFlags; /* State flags returned */
bButton = ART_GUI_toolbar_button_get(hWndToolBar,
ART_BUTTON_ARROW, &lpFlags);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_toolbar_button_set

Group: Graphical User Interface

Declaration:

BOOL FAR PASCAL ART_GUI_toolbar_button_set(HWND hwndToolBar,
    DWORD dwButtonID,
    DWORD dwFlags
    );

Arguments:

hWndToolBar
Set to the Windows handle to the toolbar
dwButtonID
Set to an ART-defined constant beginning with ART_BUTTON_.
dwFlags
One or more of the bitwise state flags: ART_BUTTON_CHECKED, ART_BUTTON_ENABLED, ART_BUTTON_VISIBLE

Description:

This function sets the state of the button specified by dwButtonID. Possible states include: ART_BUTTON_CHECKED - the button is pressed, ART_BUTTON_ENABLED - the button is not grayed out, and ART_BUTTON_VISIBLE - the button is not hidden. Supply it with the handle to the toolbar, and an ART-defined constant beginning with ART_BUTTON_ to specify which button to set, and the flags for setting the button. One of the uses for this function is to keep the toolbar in sync with items that are checked on menus. This function updates the button.

To have a button un-checked, disabled, or invisible, leave the appropriate constant off of your setting for dwFlags.

To make a button checked and disabled set state flags to:

  • ART_BUTTON_CHECKED|ART_BUTTON_VISIBLE.

To make a button invisible:

dwPriorFlags|~ART_BUTTON_VISIBLE, where dwPriorFlags is the value retrieved from ART_GUI_toolbar_button_set().

Bits Per Pixel: N/A

Return Value:

Returns TRUE if the button exists and is successfully queried; returns FALSE if the button of the specified ID does not exist.

Example:

HIGEAR  hIGear; /* HIGEAR handle of image */
BOOL bButton; /* Whether button exists  */
/* on toolbar  */
DWORD lpFlags; /* State flags returned  */
bButton = ART_GUI_toolbar_button_set(hWndToolBar,
ART_BUTTON_ARROW,ART_BUTTON_ENABLED|
ART_BUTTON_VISIBLE);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_toolbar_CB_register

Group: Graphical User Interface

Declaration:

BOOL FAR PASCAL ART_GUI_toolbar_CB_register(HWND hwndToolBar,
    UINT nCallback,
    LPFNART_GUI_CALLBACKFUNC lpfnCallback,
    LPVOID lpPrivate
    );

Arguments:

hWndToolBar
Windows handle to the toolbar. This is given to you by the ART_GUI_toolbar_create () function.
nCallback
Set to the Type of callback to register, either ART_GUI_CB_TOOLBAR or ART_GUI_CB_TEXT_REPLACE
lpfnCallback
Set to the type of callback to register. The types that can be registered are defined in ARTGUI.H and begin with LPFNART_GUI_
lpPrivate
A far pointer to any private data that you want to pass to the callback.

Description:

This function registers a callback function of type LPFNART_GUI_CALLBACK_FUNC. See the descriptions for these callbacks in the section ART Component Callback Functions Reference towards the end of this chapter.

Bits Per Pixel: N/A

Return Value:

Returns TRUE if the callback is successfully registered; FALSE if it is not successfully registered.

Example:

HIGEAR  hIGear; /* HIGEAR handle of image */
BOOL bRegistered; /* Whether successfully */
/* registered or not */
UINT nCallback; /* Type of callback to */
/* register  */
ART_GUI_CALLBACK MyCallback; /* Callback type to */
/* register  */
DWORD dwPrivateFlags; /* private data to */
/* pass to callback*/
bRegistered = ART_GUI_toolbar_CB_register(hwndToolBar,
nCallback, MyCallback, (LPVOID)&dwPrivateFlags);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_toolbar_create

Group: Graphical User Interface

Declaration:

BOOL FAR PASCAL ART_GUI_toolbar_create(HWND hwndParent,
    int x,
    int y,
    HWND FAR *phwndToolBar
    );

Arguments:

hwndParent
Set to the Windows handle of the toolbar's parent window
x
An integer variable that sets the x coordinate of the upper-left corner of the toolbar
y
An integer variable that sets the y coordinate of the upper-left corner of the toolbar
lphWndToolbar
A far pointer that returns a Windows handle to the toolbar

Description:

This function creates an ART toolbar and displays it with its upper-left corner positioned at your defined coordinates of x and y. You must supply ART with the handle to the parent window to display the toolbar. It returns a Windows handle to the toolbar that you need to pass to the functions starting with ART_GUI_toolbar_...().

Bits Per Pixel: All

Return Value:

Returns TRUE if toolbar is successfully created; returns FALSE if toolbar not successfully created.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
BOOL bCreated; /* Whether toolbar created*/
int  x, y; /* coordinates of toolbar */
/* corner  */
HWND lphWndToolBar; /* handle returned for */
 /* toolbar  */
bCreated = ART_GUI_toolbar_create( hwndParent, x, y,
&lphWndToolBar);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_toolbar_create_ex

Group: Graphical User Interface
NOTE: This function is extended version of ART_GUI_toolbar_create() function.

Declaration:

BOOL FAR PASCAL ART_GUI_toolbar_create_ex(HWND hwndParent,
    int x,
    int y,
    HWND FAR *phwndToolBar,
    DWORD dwStyle
    );

Arguments:

hwndParent
Set to the Windows handle of the toolbar's parent window.
x
An integer variable that sets the x coordinate of the upper-left corner of the toolbar.
y
An integer variable that sets the y coordinate of the upper-left corner of the toolbar.
lphWndToolbar
A far pointer that returns a Windows handle to the toolbar.
dwStyle
Standard Windows style flags: WS_VISIBLE, etc.

Description:

This function creates an ART toolbar and displays it with its upper-left corner positioned at your defined coordinates of x and y. You must supply ART with the handle to the parent window to display the toolbar. It returns a Windows handle to the toolbar that you need to pass to the functions starting with ART_GUI_toolbar_. Fifth parameter sets style flags of the toolbar window to be created. For example, toolbar window may be created with such style:

MFS_4THICKFRAME | MFS_SYNCACTIVE | WS_POPUP | WS_CAPTION | WS_SYSMENU | MFS_MOVEFRAME | FWS_SNAPTOBARS | dwStyle

Bits Per Pixel: All

Return Value:

Returns TRUE if toolbar is successfully created; returns FALSE if toolbar not successfully created.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
BOOL bCreated; /* Whether toolbar created*/
int  x, y; /* coordinates of toolbar's upper-left corner */
HWND lphWndToolBar; /* handle returned for toolbar*/

bCreated = ART_GUI_toolbar_create_ex( hwndParent, x, y,
&lphWndToolBar,  WS_VISIBLE);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_tool_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ART_GUI_tool_get(HIGEAR hGear,
    LPART_MARK_ATTRIBUTES lpMarkAttr
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMarkAttr
A far pointer that returns the type of mark to create. The return value of the dwType field is a constant beginning with the prefix ART_MARK_ , such as ART_MARK_FREEHAND_LINE

Description:

This function gets the type of mark that is created by the end user.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR  hIGear; /* HIGEAR handle of */
/* image  */
ART_MARK_ATTRIBUTES ma; /* Structure for */
/* mark attributes */
memset(&ma, 0, sizeof(ART_MARK_ATTRIBUTES));
ART_GUI_tool_get(hIGear, &ma);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_GUI_tool_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ART_GUI_tool_set(HIGEAR hIGear,
    LPAT_MARK_ATTRIBUTES lpMarkAttr
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMarkAttr
These attributes are used when the next mark is created. Set the dwType field to the type of mark to create. These constants begin with the prefix: ART_MARK_ such as ART_MARK_FREEHAND_LINE

Description:

This function sets the next type of mark that is created by the end user. If lpMarkAttr is set to NULL, no mark is created, instead, the selection pointer is enabled. This function is called when a toolbar button is pressed.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • nMarkType is not a valid mark type.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example

HIGEAR hIGear; /* HIGEAR handle of */
/* image   */
ART_MARK_ATTRIBUTES ma; /* Structure for   */
/* mark attributes   */
memset(&ma, 0, sizeof(ART_MARK_ATTRIBUTES));
ma.dwType = ART_MARK_ATTACH_A_NOTE;
/* set the type of   */
/* mark    */
ma.rgbColor1.rgbRed   = 0xFF;/* set the red component  */
/* of the note's color  */
ma.bVisible = TRUE;  /* ensure that the mark  */
/* will be visible (shown)*/
ART_GUI_tool_set(hIGear, &ma);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_image_burn_in

Group: Image Utility

Declaration:

AT_ERRCOUNT ART_image_burn_in(HIGEAR hIGear,
    HWND hWnd,
    DWORD dwGrpID,
    AT_MODE fOptions,
    const LPSTR szGroup,
    PART_MARK_INDEX lpMarkIndex,
    UINT nMarkCount
    );

Arguments:

hIGear
HIGEAR handle to the image
hWnd
HWND handle to the window
dwGrpID
Identifier of group
fOptions
An ART-defined constant ( a bit flag) that tells what type of marks to burn in to the HIGEAR image. These are defined in ARTAPI.H, and are shown below.
szGroup
A far pointer to a null-terminated string that tells ART what group of marks to merge, when the ART_BURN_IN_GROUP bit is set.
lpMarkIndex
A far pointer to the mark identifier, used when the ART_BURN_IN_LIST bit is set.
hMarkCount
The count of marks or groups, ignored unless the ART_BURN_IN_LIST bit is set.

Description:

This function merges annotation marks permanently into an image. The fOptions parameter specifies which marks are merged.

fOptions may be a bitwise combination of any of the following values:

ART_BURN_IN_ALL
Burns in all annotation marks
ART_BURN_IN_DELETE_MARKS
Deletes affected marks after burning them in.
ART_BURN_IN_GROUP
Burns in a group of marks
ART_BURN_IN_LIST
Burns in a list of marks
ART_BURN_IN_VISIBLE
Burns in visible marks
ART_BURN_IN_SELECTED
Burns in selected marks
ART_BURN_IN_AUTO_PROMOTE
Automatically promotes image
ART_BURN_IN_NO_PROMOTE
No promotion before burn-in

The szGroup parameter is ignored, unless fOptions includes ART_BURN_IN_GROUP. The lpMarkIndex parameter is ignored, unless fOptions includes ART_BURN_IN_LIST. nMarkCount is the count of items in the list pointed to by lpMarkIndex.

To restrict the number of marks that are burned into the image, set more options. For example, if ART_BURN_IN_GROUP, ART_BURN_IN_SELECTED and ART_BURN_IN_VISIBLE are set, only those marks that are in the group szGroup, that are selected and visible, are burned into the image.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • fOptions includes ART_BURN_IN_LIST and the memory pointed to by lpMarkIndex is invalid.

The settings ART_BURN_IN_AUTO_PROMOTE and ART_BURN_IN_NO_PROMOTE affect whether the IGPage image undergoes a bit depth promotion before the marks are burned in.

There are three variants of this method behavior for the bit depth promotion:

  • Default behavior (neither ART_BURN_IN_AUTO_PROMOTE nor ART_BURN_IN_NO_PROMOTE is used):
    • For 1-bit images: promote to 8, burn-in, then reduce back to 1.
    • For 4 and 8: promote to 24, burn-in, then reduce to original bit depth.
    • For 24: no promote, burn-in, and no reducing.
  • When ART_BURN_IN_NO_PROMOTE is used:

All promotion is suppressed.

  • When ART_BURN_IN_AUTO_PROMOTE is used:
    • For 1 and 4-bit images: promote to 24, burn-in, then reduce to 4 bits per pixel.
    • For 8-bit images: promote to 24, burn-in, then reduce to 8 bits per pixel.
    • For 24: no promote, burn-in, and no reducing.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
HWND hWnd;
DWORD dwGrpID;
/* Burn in all visible marks in the group  */
/* "Unclassified"     */
dwGrpID = IG_GRP_DEFAULT;
ART_image_burn_in(hIGear, hWnd, dwGrpID,
ART_BURN_IN_VISIBLE|ART_BURN_IN_GROUP,
"Unclassified", NULL, 0L);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_internet_export

Group: File

Declaration:

AT_ERRCOUNT ART_internet_export (
    const LPCHAR    HostName,
    const LPCHAR    URLPath,
    const LPCHAR    UserName,
    const LPCHAR    Password,
    LONG            nServerPort,
    DWORD           dwService,
    AT_BOOL         bHttpSecure,
    DWORD           dwHttpVerb,

    DWORD           dwAccessType,
    const LPSTR  lpszProxyName,
    const LPSTR  lpszProxyBypass,
    DWORD           dwFlags,
    HIGEAR          hIGear,
    DWORD           dwPageNumber,
    AT_BOOL         fReplace
    );

Arguments:

HostName
Set to the name of Internet host, for example "www.accusoft.com."
URLPath
The URL path to the annotation file, such as "/annotations/1.art". In general, this is a path to necessary file on the given host.
UserName
Set to the proper user name to logon.
Password
Give the proper password to logon.
nServerPort
Set to the number of the Internet port. Use one of the settings from parameter 3 of the Win32 function InternetConnect.
dwService
Set to one of the following values:
INTERNET_SERVICE_FTP - for FTP service,
INTERNET_SERVICE_HTTP - for HTTP service.
bHttpSecure
This is a boolean parameter that is used for HTTP service only:
Set this parameter to TRUE to use secure transaction semantics for HTTPS requests.
Set this parameter to FALSE to use unsecure transaction semantics for HTTP requests.
NOTE: bHttpSecure parameter should be set to TRUE in case of HTTPS connection.
dwHttpVerb
One of the following values:
IG_HTTP_VERB_PUT - for saving the annotation page to the file strURLPath
IG_HTTP_VERB_POST - for transferring the annotation page data to the web script strURLPath
NOTE: This parameter is used only for INTERNET_SERVICE_HTTP
dwAccessType
The type of access that will be passed to InternetOpen function. as second parameter. For details see description of function InternetOpen from Miscrosoft Win32 Internet Function Reference.
lpszProxyName
Proxy name for the third parameter of InternetOpen function. See the description of the InternetOpen function from Miscrosoft's Win32 Internet Function Reference.
lpszProxyBypass
Bypass name for fourth parameter of InternetOpen function. See the description of the InternetOpen function from Miscrosoft's Win32 Internet Function Reference
dwFlags
Flags for fifth parameter of InternetOpen function. See the description of the InternetOpen function from Miscrosoft's Win32 Internet Function Reference.
hIGear
ImageGear returns you a HIGEAR handle to the newly loaded image.
dwPageNumber
The number of page you are going to save.
fReplace
Boolean flag that says whether or not to replace the old annotation page (if exists) with the new one.

Description:

This function can be used to transfer ART annotation page to FTP/ HTTP(S).

NOTE: This function doesn't work for GOPHER service.

See also:

ART_file_import ()

IG_load_internet_ex ()

ART_internet_import ()

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_internet_import

Group: File

Declaration:

AT_ERRCOUNT ART_internet_import (
    const LPCHAR    HostName,
    const LPCHAR    URLPath,
    const LPCHAR    UserName,
    const LPCHAR    Password,
    LONG            nServerPort,
    DWORD           dwService,
    AT_BOOL         bHttpSecure,
    DWORD           dwAccessType,
    const   LPSTR   lpszProxyName,
    const   LPSTR   lpszProxyBypass,
    DWORD           dwFlags,

    HIGEAR          hIGear,
    HWND            hWnd,
    DWORD           dwGrpID,
    DWORD           dwPageNumber,
    AT_BOOL         bAppend
    )

Arguments:

HostName
Set to the name of Internet host, for example "www.accusoft.com."
URLPath
The URL path to the annotation file, such as "/annotations/1.art". In general, this is a path to necessary file on the given host.
UserName
Set to the proper user name to logon.
Password
Give the proper password to logon.
nServerPort
Set to the number of the Internet port. Use one of the settings from parameter 3 of the Win32 function InternetConnect.
dwService
Set to one of the following values:
INTERNET_SERVICE_FTP - for FTP service,
INTERNET_SERVICE_GOPHER - for Gopher service,
INTERNET_SERVICE_HTTP - for HTTP service.
bHttpSecure
This is a boolean parameter that is used for HTTP service only:
Set this parameter to TRUE to use secure transaction semantics for HTTPS requests.
Set this parameter to FALSE to use unsecure transaction semantics for HTTP requests.
NOTE: bHttpSecure parameter should be set to TRUE in case of HTTPS connection.
dwAccessType
The type of access that will be passed to InternetOpen function. as second parameter. For details see description of function InternetOpen from Miscrosoft Win32 Internet Function Reference.
lpszProxyName
Proxy name for the third parameter of InternetOpen function. See the description of the InternetOpen function from Miscrosoft's Win32 Internet Function Reference.
lpszProxyBypass
Bypass name for fourth parameter of InternetOpen function. See the description of the InternetOpen function from Miscrosoft's Win32 Internet Function Reference
dwFlags
Flags for fifth parameter of InternetOpen function. See the description of the InternetOpen function from Miscrosoft's Win32 Internet Function Reference.
lphIGear
ImageGear returns you a HIGEAR handle to the newly loaded image.
hWnd
HWND handle to the window.
dwGrpID
Identifier of the group.
dwPageNumber
The number of page to load from the annotation file.
bAppend
Boolean flag that says whether or not to append annotations from the loaded file.

Description:

This function can be used to load ART annotation files from FTP/GOTHER/HTTP(S).

See also:

ART_file_import ()

IG_load_internet_ex ()

ART_internet_export ()

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_access

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_access (HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    BOOL fAccess
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
fAccess
If set to TRUE, the mark can be edited; if FALSE, editing is disabled.

Description:

This function allows or restricts access to a mark. Access to a mark includes the ability to edit it. When fEnable is set to TRUE, the mark can be edited. When fAccess is set to FALSE, the mark editing is disabled.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR  hIGear; /* HIGEAR handle of image */
AT_ERRCOUNT  nErrcount; /* tally of IG errors on  */
/* stack    */
ART_MARK_INDEX  hMarkIndex; /* index to current mark  */
ART_MARK_ATTRIBUTES ma; /* structures for   */
/* attributes of current  */
/* mark    */
BOOL  fEnable; /* whether access for  */
/* editing    */
/* is granted to the mark */
nErrcount = ART_mark_query(hIGear, hMarkIndex, &ma);
if (ma.dwType == 10)
{  /* if mark is an attach-a-note */
nErrcount = ART_mark_access_is_granted(hIGear,
hMarkIndex, fEnable);
if (fEnable == TRUE)
{
/*if access is granted, deny the access */
nErrcount = ART_mark_access (hIGear,
hMarkIndex, FALSE);
/*deny access to this mark */
}
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_block_create

Group: Named Block Management

Declaration:

AT_ERRCOUNT ART_mark_block_create(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    const LPART_BLOCK_NAME lpBlockName,
    LPVOID lpBlockData,
    DWORD dwBlockSize
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
lpBlockName
Tells ART what type of block to create. Use an ART-defined constant beginning with ART_BLOCK. See ARTAPI.H for the full list. This parameter is also a user-defined block type.
lpBlockData
A far pointer to the Block to copy into a new named block
dwBlockSize
Size of lpBlockdata (in bytes)

Description:

This function creates or replaces a named block and associates a new block with the annotation mark pointed to by hMarkIndex. If a block of type lpBlockName exists, the new one replaces the previous one. The block data pointed to by lpBlockData is copied into the new named block.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.
  • lpBlockName does not point to a valid address.
  • lpBlockData does not point to a valid address.
  • There is not enough memory to allocate dwBlockSize bytes of memory.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image  */
AT_MARK_ATTRIBUTES ma; /* mark attributes structure */
ART_POINTS lpPoints; /* screen coordinates   */
ART_MARK_INDEX hMarkIndex; /* index to mark getting  */
/* new block   */
DWORD  dwBlockSize; /* size in bytes of block */
/* set the block size */
dwBlockSize = sizeof(ART_POINTS) + sizeof(AT_POINT);
/* allocate memory for the points structure */
lpPoints = (LPART_POINTS)LocalAlloc(LPTR,
(UINT)dwBlockSize);
/* initialize to zero */
memset(lpPoints, 0, (UINT)dwBlockSize);
/* fill the structure */
lpPoints->lMaxPoints    = 2;
lpPoints->lPoints       = 2;
lpPoints->ptPoint[0].x  = (ma.rcBounds.right -
ma.rcBounds.left) - 1;
lpPoints->ptPoint[0].y  = 0;
lpPoints->ptPoint[1].x  = 0;
lpPoints->ptPoint[1].y  = (ma.rcBounds.bottom -
ma.rcBounds.top) - 1;
/* create the named block and associate it with this  */
/* mark         */
nErrcount = ART_mark_block_create(hIGear, hMarkIndex,
ART_BLOCK_ANODAT, lpPoints, dwBlockSize);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_block_create_ex

Group: Named Block Management

Declaration:

AT_ERRCOUNT ART_mark_block_create_ex(HIGEAR hIGear,
    HWND hWnd,
    DWORD dwGrpID,
    ART_MARK_INDEX hMarkIndex,
    const LPART_BLOCK_NAME lpBlockName,
    LPVOID lpBlockData,
    DWORD dwBlockSize
    );

Arguments:

hIGear
HIGEAR handle to the image
hWnd
HWND handle to the window
dwGrpID
Identifier of group
hMarkIndex
Mark identifier
lpBlockName
Tells ART what type of block to create. Use an ART-defined constant beginning with ART_BLOCK. See ARTAPI.H for the full list. This parameter is also a user-defined block type.
lpBlockData
A far pointer to the Block to copy into a new named block
dwBlockSize
Size of lpBlockdata, in bytes

Description:

This function creates or replaces a named block and associates a new block with the annotation mark pointed to by hMarkIndex. If a block of type lpBlockName exists, the new one replaces the previous one. The block data pointed to by lpBlockData is copied into the new named block.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.
  • lpBlockName does not point to a valid address.
  • lpBlockData does not point to a valid address.
  • There is not enough memory to allocate dwBlockSize bytes of memory.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image  */
AT_MARK_ATTRIBUTES ma; /* mark attributes structure */
ART_POINTS lpPoints; /* screen coordinates   */
ART_MARK_INDEX hMarkIndex; /* index to mark getting  */
/* new block   */
DWORD  dwBlockSize; /* size in bytes of block */
HWND   hWnd;
DWORD  dwGrpID;
/* set the block size */
dwBlockSize = sizeof(ART_POINTS) + sizeof(AT_POINT);
/* allocate memory for the points structure */
lpPoints = (LPART_POINTS)LocalAlloc(LPTR,
(UINT)dwBlockSize);
/* initialize to zero */
memset(lpPoints, 0, (UINT)dwBlockSize);
/* fill the structure */
lpPoints->lMaxPoints    = 2;
lpPoints->lPoints       = 2;
lpPoints->ptPoint[0].x  = (ma.rcBounds.right -
ma.rcBounds.left) - 1;
lpPoints->ptPoint[0].y  = 0;
lpPoints->ptPoint[1].x  = 0;
lpPoints->ptPoint[1].y  = (ma.rcBounds.bottom -
ma.rcBounds.top) - 1;
/* create the named block and associate it with this  */
/* mark         */
dwGrpID = IG_GRP_DEFAULT;
nErrcount = ART_mark_block_create_ex(hIGear, hWnd, dwGrpID,
hMarkIndex, ART_BLOCK_ANODAT, lpPoints, dwBlockSize);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_block_delete

Group: Named Block Management

Declaration:

AT_ERRCOUNT ART_mark_block_delete(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    const LPART_BLOCK_NAME lpBlockName
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
lpBlockName
Tells ART what type of block to delete. Use an ART-defined constant beginning with ART_BLOCK. See ARTAPI.H for the full list. This parameter is also a user-defined block type.

Description:

This function deletes an existing named block. It deletes the named block lpBlockName from the mark referenced by hMarkIndex.

  • An error will be set if any of the following conditions are met:
  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.
  • lpBlockName does not point to a valid address.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR  hIGear; /* HIGEAR handle of image */
ART_MARK_INDEX hMarkIndex; /* index to the mark the  */
/* block belongs to  */
nErrcount = ART_mark_block_delete(hIGear, hMarkIndex,
ART_BLOCK_ANODAT);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_block_first

Group: Named Block Management

Declaration:

AT_ERRCOUNT ART_mark_block_first(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    LPART_BLOCK_NAME lpBlockName
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
lpBlockName
A far pointer to an 8-byte array of memory that returns the type of block of the mark referenced by hMarkIndex. The block type is either an ART-defined constant beginning with ART_BLOCK or a user-defined block. See ARTAPI.H for the full list of ART-defined constants.

Description:

This function gets the first block name. The block data for the named block retrieved by calling ART_mark_block_query (). ART_mark_block_next () is called to get the name of the next named block. If there are no blocks, ART_mark_block_first() sets lpBlockName to zero.

TIP: Many of ART's callback functions include the index number as a parameter. As part of your callback function, you can call ART_mark_block_first() and ART_mark_block_next() using the mark index that was passed in.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle. There are no marks with a matching index block.
  • lpBlockName does not point to a valid address.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR  hIGear; /* HIGEAR handle of image */
ART_MARK_INDEX hMarkIndex; /* index to mark   */
ART_BLOCK_NAME lpBlockname; /* type of block   */
/* to return   */
CHAR szFileName[_MAX_PATH]; /* file name buffer  */
DWORD dwBlockSize;  /* size of a named  Block  */
nErrcount = ART_mark_block_first(hIGear, hMarkIndex,
&lpBlockName);
while (*lpBlockName)
{
if (!memcmp(lpBlockName, ART_BLOCK_FILENAM,
sizeof(ART_BLOCK_NAME))
{
nErrcount = ART_mark_block_query(hIGear,
hMarkIndex, &lpBlockName,
(LPVOID)szFileName, &dwBlockSize);
if (!strcmp(szFileName, "Clown.tif"))
{
nErrcount = RT_mark_send_to_back(hIGear,
hMarkIndex);
}
}
nErrcount = ART_mark_block_next(hIGear, hMarkIndex,
&lpBlockName);
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_block_next

Group: Named Block Management

Declaration:

AT_ERRCOUNT ART_mark_block_next(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    LPART_BLOCK_NAME lpBlockName
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
lpBlockName
A far pointer to an 8-byte array of memory that returns the type of block of the mark referenced by hMarkIndex. The block type is either an ART-defined constant beginning with ART_BLOCK or a user-defined block. See ARTAPI.H for the full list of ART-defined constants.

Description:

This function gets the block name of the named block that follows the one that was last passed into lpBlockName. ART_mark_block_first () is called to get the first block name. The block data for the named block is retrieved by calling ART_mark_block_query (). Both ART_mark_block_next() and ART_mark_block_first () set lpBlockName to zero when there are no more blocks (providing you an easy way to know when to end your loop). Block names are returned in no particular order.

NOTE: To get the mark index needed for this function, you can call any of ART's functions that return a mark index, for example: ART_mark_first().
TIP: Many of ART's callback functions include the index number as a parameter. As part of your callback function, you can call ART_mark_block_first() and ART_mark_block_next() using the passed mark index.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.
  • lpBlockName does not point to a valid address.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

See example under ART_mark_block_first ()function.

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_block_query

Group: Named Block Management

Declaration:

AT_ERRCOUNT ART_mark_block_query(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    const LPART_BLOCK_NAME lpBlockName,
    LPVOID lpBlockData,
    LPDWORD lpBlockSize
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
lpBlockName
Tells ART what type of block to query. Use an ART-defined constant beginning with ART_BLOCK. See ARTAPI.H for the full list. This parameter is also a user-defined block type.
lpBlockData
The block data returned
lpBlockSize
The size of BlockData (in bytes)

Description:

This function queries a mark for the data from one of its named blocks. The block data for the named block associated with lpBlockName is copied into lpBlockData. The buffer pointed to by lpBlockData is large enough to fit the named block data. The size of the block is returned to lpBlockSize.

To find the size needed for a buffer to hold the block data, set lpBlockData to NULL and the size of the block is returned in lpBlockSize.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.
  • lpBlockName does not point to a valid address.
  • lpBlockData does not point to a valid address or is not NULL.
  • lpBlockData points to a buffer smaller than the block data.
  • lpBlockSize points to an invalid address.
  • lpBlockSize points to a value smaller than the size of the block data.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR  hIGear; /* HIGEAR handle of image */
ART_MARK_INDEX hMarkIndex; /* index to mark   */
/* associated   */
/* with block being  */
/* queried    */
LPVOID   BlockData; /* memory to hold data  */
/* from block  */
DWORD  BlockSize; /* size of blocks,   */
/* in byte    */
nErrcount = ART_mark_block_query(hIGear, hMarkIndex,
ART_BLOCK_ANODAT, NULL, &BlockSize);
BlockData = (LPVOID)alloca(BlockSize);
nErrcount = ART_mark_block_query(hIGear, hMarkIndex,
ART_BLOCK_ANODAT, &BlockData, &BlockSize);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_bring_to_front

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_bring_to_front(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier

Description:

This function moves a mark to the front of the stacking order. To move a group of marks to the front, use ART_group_bring_to_front().

NOTE: The mark must be repainted in order to see a change in the stacking order. Use ART_GUI_mark_paint()function.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR  hIGear; /* HIGEAR handle of image */
AT_ERRCOUNT  nErrcount; /* tally of IG errors  */
/* on stack    */
ART_MARK_INDEX hMarkIndex /* index for mark to  */
/* bring to front   */
nErrcount = ART_mark_selected_first(hIGear,
&hMarkIndex);
if (hMarkIndex != ART_MARK_INVALID)
{
nErrcount = ART_mark_bring_to_front(hIGear,
hMarkIndex);
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_count

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_count(HIGEAR hIGear,
    LPDWORD lpMarkCount
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMarkCount
A far pointer that returns the total number of marks associated with the HIGEAR image.

Description:

This function returns the total number of marks associated with the current HIGEAR image.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

AT_ERRCOUNT nErrcount;
HIGEAR   hIGear;
DWORD   dwMarkCount;
nErrcount = ART_mark_count(hIGear, &dwMarkCount);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_create

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_create(HIGEAR hIGear,
    const LPART_MARK_ATTRIBUTES lpMarkAttr,
    LPART_MARK_INDEX lpMarkIndex
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMarkAttr
Mark Description
lpMarkIndex
Mark Identifier

Description:

This function creates a new mark. Marks are initially created with two reserved named blocks: index and group. The index block is assigned a unique number, starting at 0. The index is taken from the global index block, then the global index block is incremented by one. The group is taken from the global group block. The following marks require additional named blocks to be created: lines, images, arrows, buttons, audio and text.

Returned in lpMarkIndex is the value stored in the index named block. The fields in the lpMarkAttr parameter set the attributes of the new mark, andare filled with default values. Call ART_mark_modify () to modify the attributes of the mark.

If the dwTime field is set to 0, the library is set to the current time. Not all fields are used for each mark type. An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • lpMarkAttr is an invalid address or has one or more invalid fields.
  • The memory pointed to by lpMarkIndex is read-only, invalid or not large enough.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear;  /* HIGEAR handle of image */
AT_MARK_ATTRIBUTES ma;  /* attributes structure */
AT_MARK_INDEX hMarkIndex; /* index to the mark just */
/* created   */
/* set the mark type */
ma.dwType = ART_MARK_TEXT_STAMP;
/* set the mark color */
ma.rgbColor1.rgbRed = 0xFF;
/* set the mark to be visible */
ma.bVisible = TRUE;
/* create the mark */
nErrcount = ART_mark_create(hIGear, &ma, &hMarkIndex);
if (nErrcount != 0)
{
   ErrorReport(hWnd);
}
else
{
    ART_GUI_mark_paint(hIGear, IG_GRP_DEFAULT, hMarkIndex,
hWnd, TRUE);
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_delete

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_delete(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark Identifier

Description:

This function deletes the mark whose index block value is the same as hMarkIndex.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear;  /* HIGEAR handle of image */
ART_MARK_INDEX hMarkDelete, hMarkIndex; /* Mark index  */
   /* numbers */
ART_mark_selected_first(hIGear, &hMarkIndex);
if (hMarkIndex != ART_MARK_INVALID)
{
hMarkDelete = hMarkIndex;
/* Set mark to be deleted to  */
   /* current index number   */
ART_mark_delete(hIGear, hMarkDelete);
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_first

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_first(HIGEAR hIGear,
    LPART_MARK_INDEX lpMarkIndex,
    LPART_MARK_ATTRIBUTES lpMarkAttr
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMarkIndex
Mark identifier returned
lpMarkAttr
Mark description returned or NULL

Description:

This function returns the mark index of the first mark associated with the HIGEAR image. The attributes for the mark are copied into lpMarkAttr. The lpMarkAttr parameter is set to NULL if the mark attributes are not needed. ART_mark_next () gets the mark index and attributes of the mark that follows the one that was passed into lpMarkIndex. These functions set lpMarkIndex to ART_INVALID_ID when there are no more marks to iterate through. Mark indexes are returned in the same order as the stacking order.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • The memory pointed to by lpMarkAttr is read-only (or not NULL), invalid or not large enough.
  • The memory pointed to by lpMarkIndex is read-only, invalid or not large enough.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
BOOL fSelected; /* flag for whether mark has been
selected */
AT_MARK_INDEX  hMarkIndex; /* index number for marks */
/* Get index of first mark created */
ART_mark_first(hIGear, &hMarkIndex, NULL);
/* While there are valid index number, iterate through them and
select all of those marks which have not yet been selected */
while (hMarkIndex != ART_INVALID_ID)
{
/* check to see if the mark is already selected */
ART_mark_is_selected(hIGear, hMarkIndex, &fSelected);
/* if not, then select it */
if (!fSelected)
{
ART_mark_select(hIGear, hMarkIndex, TRUE);
ART_mark_next(hIGear, &hMarkIndex, NULL);
}
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_is_access_granted

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_is_access_granted(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    LPBOOL lpEnabled
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
lpEnabled
A far pointer that returns the current setting of the mark's edit ability. The value is Boolean.

Description:

This function returns the current access state of a mark. If the mark is editable, this function sets lpEnabled to TRUE. If the mark is not editable, lpEnabled is set to FALSE.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.
  • lpEnabled points to an invalid address.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

See example under ART_mark_access () function.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_is_selected

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_is_selected(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    LPBOOL lpSelected
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
lpSelected
A far pointer that returns the current setting of the selection field in the mark's attribute structure. The value of this field is Boolean.

Description:

This function returns the current selection state of a mark. If the mark is selected, lpSelected returns a value of TRUE. If the mark is not selected, lpSelected returns a value of FALSE.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block. lpSelected points to an invalid address.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

See example under ART_mark_first ()

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_is_visible

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_is_visible(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    BOOL lpVisible
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
lpVisible
A far pointer that returns the current setting of the visibility field in the mark's attribute structure. The value of this field is Boolean.

Description:

This function returns the current visibility state of a mark. The value returned in lpVisible is the value of the bVisible field of the mark's attribute structure.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle. There are no marks with a matching index block.
  • lpVisible points to an invalid address.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

See example under ART_mark_visible ()function.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_modify

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_modify(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    LPART_MARK_ATTRIBUTES lpMarkAttr
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
lpMarkAttr
A far pointer to a structure of type ART_MARK_ATTRIBUTES that holds all settings for the mark's attributes

Description:

This function changes the attributes of a mark. The attributes are stored in a structure of type ART_MARK_ATTRIBUTES, that is defined in ARTAPI.H. You can set any number of the attributes of this structure and then pass it to this function.

NOTE: The mark is repainted in order to see the change in it's attributes. Use ART_GUI_mark_paint()function.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.
  • lpMarkAttr is an invalid address or has one or more invalid fields.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR  hIGear;  /* HIGEAR handle of image */
AT_MARK_ATTRIBUTES ma;  /* mark attributes */
/* structure */
AT_MARK_INDEX markIndex /* index to the mark */
ART_mark_selected_first(hIGear, &hMarkIndex);
if (hMarkIndex != ART_MARK_INVALID)
{
ART_mark_query(hIGear, markIndex, &ma);
ma.dwType = 506;  /* arrow    */
ma.dwLineSize = 5;  /* line thickness =  */
/* 5 pixels    */
nErrcount = ART_mark_modify(hIGear, markIndex, &ma);
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_next

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_next(HIGEAR hIGear,
    LPART_MARK_INDEX lpMarkIndex,
    LPART_MARK_ATTRIBUTES lpMarkAttr
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMarkIndex
Mark identifier
lpMarkAttr
Mark description

Description:

This function is called after ART_mark_first () to get the mark index and attributes of the next mark. The attributes for the mark are copied into lpMarkAttr. The lpMarkAttr parameteris set to NULL if the mark attributes are not needed. Both this function and ART_mark_first () set lpMarkIndex to ART_INVALID_MARK when there are no more marks to iterate through. Mark indexes are returned in the same order as the stacking order.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • The memory pointed to by lpMarkAttr is read-only (or not NULL), invalid or not large enough.
  • The memory pointed to by lpMarkIndex is read-only, invalid or not large enough.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

See example under ART_mark_first ()function.

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_query

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_query(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    LPART_MARK_ATTRIBUTES lpMarkAttr
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
lpMarkAttr
Mark description

Description:

This function queries a mark for its attributes that are stored in the structure AT_MARK_ATTRIBUTES. The attributes for the mark associated with hMarkIndex are copied into lpMarkAttr, and can then be examined. To bring a particular mark to the front of the stacking order, use ART_mark_bring_to_front ().

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.
  • The memory pointed to by lpMarkAttr is read-only, invalid or not large enough.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR  hIGear; /* HIGEAR handle of image */
AT_ERRCOUNT  nErrcount; /* tally of IG errors on  */
/* the stack   */
ART_MARK_INDEX hMarkIndex; /* index to the mark  */
/* being queried  */
ART_MARK_ATTRIBUTES ma ; /* structure holding the  */
/* mark's attributes  */
UINT arrowCount;  /* number of arrow marks  */
/* assoc. with image  */
/* Get index of first mark created */
ART_mark_first(hIGear, &hMarkIndex, NULL);
/* While there are valid index number, iterate through them and
keep count of any arrow marks associated with the image */
while (hMarkIndex != ART_INVALID_ID)
{
nErrcount = ART_mark_query(hIGear, hMarkIndex, &ma);
if (ma.dwType = 506)
{
arrowCount++
}
   nErrcount = ART_mark_next(hIGear,&HMarkIndex,NULL);
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_rotate

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_rotate (HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    DOUBLE dblRotate
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
dblRotate
Rotation angle

Description:

This function allows individual mark rotation. Currently only image marks (embedded and image reference) can be rotated.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR               hIGear;       /* HIGEAR handle of image  */
AT_ERRCOUNT          nErrcount;     /* tally of IG errors on  */
/* stack    */
ART_MARK_INDEX       hMarkIndex;    /* index to current mark  */
ART_MARK_ATTRIBUTES ma;    /* structures for  */
/* attributes of current  */
/* mark  */
nErrcount = ART_mark_query(hIGear, hMarkIndex, &ma);
if ((ma.dwType == ART_MARK_IMAGE_EMBEDDED) ||
   (ma.dwType == ART_MARK_IMAGE_REFERENCE))
{ 		/* if mark is an embedded image or image reference*/
        nErrcount = ART_mark_rotate(hIGear, hMarkIndex, 45.0);
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_select

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_select(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    BOOL fSelect
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
fSelect
If set to FALSE, the mark is deselected; if TRUE, the mark is selected.

Description:

This function selects or deselects a mark. When fSelect is set to TRUE, the mark is selected. When fSelect is set to FALSE, the mark is deselected.

NOTE: The mark must be repainted in order to see a change in the selection state. Use ART_GUI_mark_paint()function.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

See example under ART_mark_first ()function.

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_select_count

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_select_count(HIGEAR hGear,
    LPWORD lpSelected
    );

Arguments:

hIGear
HIGEAR handle to the image
lpSelected
A far DWORD pointer that returns the number of selected marks.

Description:

This function counts the number of marks selected by the user or selected by calling ART_mark_select ()function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image  */
AT_ERRCOUNT nErrcount; /* tally of IG errors on   */
/* stack     */
char szBuf[100]; /* Temporary string buffer */
nErrcount = ART_mark_select_count(hIGear, &dwMarkCount);
wsprintf(szBuf, _TEXT("There are %ld marks selected."),
dwMarkCount);
MessageBox(HWND_DESKTOP,szBuf,NULL,MB_ICONINFORMATION);

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_selected_first

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_selected_first(HIGEAR hGear,
    LPART_MARK_INDEX lpMarkIndex
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMarkIndex
A far pointer that returns the index of the first mark selected.

Description:

This function returns the index of the mark that is first in the list of selected marks. ART_mark_selected_next () returns the index of the next mark.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
. . .
case ID_EDIT_DELETE:  /*delete all marks   */
ART_mark_selected_first(hIGear, &hMarkIndex);
/* iterate through all marks that were selected by user
and delete them */
while (hMarkIndex != ART_INVALID_ID)
{
hMarkDelete = hMarkIndex;
ART_mark_selected_next(hIGear, &hMarkIndex);
ART_mark_delete(hIGear, hMarkDelete);
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_selected_next

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_selected_next(HIGEAR  hIGear,
    LPART_MARK_INDEX lpMarkIndex
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMarkIndex
A far pointer that returns the index of the first mark selected.

Description:

This function returns the index of the next mark in the list of selected marks. (Or the selected mark following the mark index number currently pointed to). In conjunction with ART_mark_selected_first () you can iterate through all of the selected marks.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

See example for ART_mark_selected_first ()function.

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_send_to_back

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_send_to_back(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier

Description:

This function moves a mark to the back of the stacking order.

NOTE: The mark must be repainted in order to see a change in the stacking order. Use ART_GUI_mark_paint()function.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR    hIGear;  /* HIGEAR handle of image */
AT_ERRCOUNT nErrcount;  /* tally of IG errors on  */
      /* stack    */
ART_MARK_INDEX hMarkIndex;  /* index for mark to  */
/* bring to front   */
nErrcount = ART_mark_selected_first(hIGear,&hMarkIndex);
if (hMarkIndex != ART_MARK_INVALID)
{
nErrcount = ART_mark_send_to_back(hIGear,hMarkIndex);
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_mark_visible

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_mark_visible(HIGEAR hIGear,
    ART_MARK_INDEX hMarkIndex,
    BOOL fVisible
    );

Arguments:

hIGear
HIGEAR handle to the image
hMarkIndex
Mark identifier
fVisible
If set to TRUE, the mark is made visible; FALSE, invisible.

Description:

This function sets the visibility of a mark. When fVisible is set to TRUE, the function show marks; when fVisible is set to FALSE, it hides marks. The bVisible field of the mark's attribute structure is set to the latest value for fVisible.

NOTE: The mark must be repainted in order to see a change in the visibility state. Use ART_GUI_mark_paint()function.

An error is set if any of the following conditions are met:

  • hIGear does not reference a valid ImageGear handle.
  • There are no marks with a matching index block.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR   hIGear; /* HIGEAR handle of image */
AT_ERRCOUNT  nErrcount; /* tally of IG errors on  */
/* stack    */
ART_MARK_INDEX  hMarkIndex; /* index to current mark */
ART_MARK_ATTRIBUTES ma; /* structures for   */
/* attributes of current  */
/* mark    */
nErrcount = ART_mark_query(hIGear, hMarkIndex, &ma);
nErrcount = ART_mark_is_visible(hIGear, hMarkIndex,
fVisible);
if (fVisible == TRUE && ma.dwType == 10){
/* if an attach-a-note mark is visible  */
nErrcount = ART_mark_visible(hIGear, hMarkIndex,
FALSE);
/* make it invisible    */
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_memory_append

Group: File

Declaration:

AT_ERRCOUNT ART_memory_append (HIGEAR hIGear,
    HWND hWnd,
    DWORD dwGrpID,
    LPVOID lpMem
    );

Arguments:

hIGear
HIGEAR handle to the image
hWnd
HWND handle of the image window
dwGrpID
Display group
lpMem
A 32-bit pointer to memory

Description:

This function appends the marks from memory into the HIGEAR image.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR      hIGear; /* HIGEAR handle of Image  */
LPBYTE      pMem; /* Pointer to memory  */
LPBYTE      pMemAppend; /* Pointer to memory  */
AT_ERRCOUNT nErrCount; /* Tally of IG errors on stack */
HWND        hWnd;
nErrCount = ART_memory_import (hIGear,pMem);
nErrCount = ART_memory_append (hIGear,pMemAppend);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_memory_export

Group: File

Declaration:

AT_ERRCOUNT ART_memory_export (HIGEAR hIGear,
    LPVOID lpMem,
    DWORD dwSize
    );

Arguments:

hIGear
HIGEAR handle to the image
lpMem
A 32-bit pointer to memory
dwSize
The size of memory block

Description:

This function saves the marks associated with the HIGEAR image to a separate previously allocated memory block.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example

HIGEAR hIGear;   /* HIGEAR handle of Image */
LPBYTE pMem;   /* Pointer to memory  */
DWORD dwSize;   /* Size of memory block  */
AT_ERRCOUNT nErrCount; /* Tally of IG errors on stack */
nErrCount = ART_memory_export_size_calc (hIGear,&dwSize);
pMem = (LPBYTE)HeapAlloc(GetProcessHeap(),HEAP_ZERO_MEMORY,
dwSize);
nErrCount = ART_memory_export (hIGear,pMem,dwSize);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_memory_export_size_calc

Group: File

Declaration:

AT_ERRCOUNT ART_memory_export_size_calc (HIGEAR hIGear,
    LPDWORD lpdwSize
    );

Arguments:

hIGear
HIGEAR handle to the image
lpdwSize
Returns the size of memory block

Description:

This function calculates the size of memory needed to allocate and save marks using the ART_memory_export () function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear;   /* HIGEAR handle of Image  */
DWORD dwSize;   /* Size of memory block   */
AT_ERRCOUNT nErrCount; /* Tally of IG errors on stack  */
nErrCount = ART_memory_export_size_calc(hIGear,&dwSize);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_memory_import

Group: File

Declaration:

AT_ERRCOUNT ART_memory_import (HIGEAR hIGear,
    HWND hWnd,
    DWORD dwGrpID,
    LPVOID lpMem
    );

Arguments:

hIGear
HIGEAR handle to the image
hWnd
HWND handle to the window
lpMem
A 32-bit pointer to memory
dwGrpID
Identifier of group

Description:

This function loads the marks from memory into the HIGEAR image. Use this for loading marks that were previously made and temporarily saved in memory.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear;   /* HIGEAR handle of Image  */
LPBYTE pMem;   /* Pointer to memory   */
AT_ERRCOUNT nErrCount; /* Tally of IG errors on stack  */
HWND hWnd;
DWORD dwGrpID;
dwGrpID = IG_GRP_DEFAULT;
nErrCount = ART_memory_import (hIGear, hWnd,
dwGrpID, pMem);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_memory_import_ex

Group: File

Declaration:

AT_ERRCOUNT ART_memory_import_ex (HIGEAR hIGear,
    HWND hWnd,
    DWORD dwGrpID,
    LPVOID lpMem
    BOOL bAppend
    );

Arguments:

hIGear
HIGEAR handle to the image
hWnd
HWND handle to the window
lpMem
A 32-bit pointer to memory
dwGrpID
Identifier of group
bAppend
If this parameter is TRUE then current ART annotation will be simply added to the memory. Otherwise previous annotation in the file will be replaced by the current one.

Description:

This function loads the marks from memory into the HIGEAR image. Use this for loading marks that were previously made and temporarily saved in memory.

This function is the same as ART_memory_import () but has supplementary parameter bAppend that allows you to determine if current ART annotation should be simply added to the memory (TRUE), or replace the existed one (FALSE).

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_rotation_angle_get

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_rotation_angle_get (HIGEAR IGear,
    LPDWORD lpdwAngle
    );

Arguments:

hIGear
HIGEAR handle to the image
lpdwAngle
A pointer to the angle value

Description:

This function determines the angle (in degrees) that an annotation rotates. Values are 0, 90, 180, 270.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear;   /* HIGEAR handle of Image  */
DWORD dwAngle;   /* Rotation angle    */
AT_ERRCOUNT nErrCount; /* Tally of IG errors on stack  */
nErrCount = ART_rotation_angle_get (hIGear,&dwAngle);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_rotation_angle_set

Group: Mark Management

Declaration:

AT_ERRCOUNT ART_rotation_angle_set (HIGEAR hIGear,
    DWORD dwAngle
    );

Arguments:

hIGear
HIGEAR handle to the image
dwAngle
The angle to rotate

Description:

This function determines the angle (in degrees) that an annotation rotates. Values are 0,90,180,270. The default is 0. Any other value (not 0,90,180,270) is interpreted as 0.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear;   /* HIGEAR handle of Image  */
AT_ERRCOUNT nErrCount; /* Tally of IG errors on stack  */
nErrCount = ART_rotation_angle_set (hIGear,90);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART_version_numbers

Declaration:

AT_ERRCOUNT ACCUAPI ART_version_numbers(
    DWORD lpdwMajor,
    DWORD lpdwMinor,
    DWORD lpdwUpdate,
    BOOL lpbNewAPI
    );

Arguments:

lpdwMajor
Far pointer to an INT variable in which will be stored the Major version number of the version of ART component that you are using
lpdwMinor
Far pointer to an INT variable in which will be stored the Minor version number of the version of ART component that you are using
lpdwUpdate
Far pointer to an INT variable in which will be stored the Update (bug fix) number, reflecting any updates you have received and installed in this version of ART component.
lpbNewAPI
This argument returns TRUE if current version of ART component uses new ImageGear display API.

Description:

This function provides you with information about currently used version of ART component.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


ART Component Callback Functions Reference

ImageGear ART Component provides the following callback functions:

  • LPFNART_GUI_TEXTREPLACEFUNC
  • LPFNART_GUI_TOOLBARNOTIFYFUNC
  • LPFNIG_ART_CREATENOTIFYFUNC
  • LPFNIG_ART_DELETENOTIFYFUNC
  • LPFNIG_ART_DRAWNOTIFYFUNC
  • LPFNIG_ART_MODIFYNOTIFYFUNC
  • LPFNIG_ART_MOUSENOTIFYFUNC
  • LPFNIG_ART_OVERRIDEDRAWNOTIFYFUNC
  • LPFNIG_ART_POSTCREATENOTIFYFUNC
  • LPFNIG_ART_PRECREATENOTIFYFUNC
  • LPFNIG_ART_PREMODIFYNOTIFYFUNC
  • LPFNIG_ART_SELECTNOTIFYFUNC
  • LPFNIG_ART_TEXTOVERFLOWNOTIFYFUNC


LPFNART_GUI_TEXTREPLACEFUNC

Group: Callback

Declaration:

typedef BOOL (FAR PASCAL *LPFNART_GUI_TEXTREPLACEFUNC)(
    LPVOID		lpPrivate,
    DWORD		dwTextID,
    const LPSTR		lpszText,
    LPSTR FAR		*lpszNewText
    );

Arguments:

lpPrivate
A far pointer to private data being passed to the callback
dwTextID
The button ID
lpszText
The current text string for the tool tip
lpszNewText
The replacement string for the tool tip

Description:

This callback function gets called whenever a "tool tip" is about to be displayed over a button. It gives you a chance to replace the default text for the button's tool tip. Tool tips are the little text boxes that appear when you let the mouse pointer rest over an ART button. For example, if you are over the Filled Rectangle button, a small rectangle appears next to it saying "Filled Rectangle".

NOTE: In order to use this callback, it must be registered with ART using the function ART_callback_register().

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNART_GUI_TOOLBARNOTIFYFUNC

Group: Callback

Declaration:

typedef BOOL (FAR PASCAL *LPFNART_GUI_TOOLBARNOTIFYFUNC)(
    LPVOID	lpPrivate,
    DWORD	dwButtonID,
    UINT	nReason
    );

Arguments:

lpPrivate
A far pointer to private data being passed to the callback
dwButtonID
The ID for the button that was pressed. These are defined in ARTGUI.H and begin with ART_BUTTON_.
nReason
The reason that the callback is being called. These are defined in ARTGUI.H and include:
ART_GUI_TOOLBAR_BUTTON_SELECTED,
ART_GUI_TOOLBAR_NONE_SELECTED,
ART_GUI_TOOLBAR_HIDDEN,
ART_GUI_TOOLBAR_DESTROYED,

Description:

This callback, if registered, gets called when a user presses a button on the toolbar, or when the toolbar is closed via the close menu or Win95's 'x' on it's mini-menu bar.

This callback passes dwButtonID and nReason to let you know what triggered the callback. dwButtonID is the button that was pressed. Each button has a unique ID:

ART_GUI_TOOLBAR_BUTTON_SELECTED
The button dwButtonID was pressed.
ART_GUI_TOOLBAR_NONE_SELECTED
The user presses a button; no other buttons are pressed.
ART_GUI_TOOLBAR_HIDDEN
The user pressed 'x' or closed the toolbar.
ART_GUI_TOOLBAR_DESTROYED
The developer called the Windows API function DestroyWindow() and passed the handle of the toolbar window.

NOTE: In order to use this callback, it must be registered with ART using the ART_callback_register() function.

Bits Per Pixel: N/A

Return Value:

The return value is ignored at this time.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ART_CREATENOTIFYFUNC

Group: Callback

Declaration:

typedef BOOL (ACCUAPI *LPFNART_CREATENOTIFYFUNC)(
    HIGEAR			hIGear,
    LPVOID			lpPrivate,
    ART_MARK_INDEX 			hMarkIndex,
    LPART_MARK_ATTRIBUTES	 		lpMarkAttr
    );

Arguments:

hIGear
HIGEAR handle to the image
lpPrivate
A far pointer to the private callback data
hMarkIndex
The index identifier for the mark just created
lpMarkAttr
A far pointer to an ART-defined attribute structure of type AT_MARK_ATTRIBUTES

Description:

This function is called by the library after a mark is created.

If the callback function returns TRUE, the mark is created; if it returns FALSE, the mark is not created. This callback gives you the opportunity to determine whether a mark is created or not.

NOTE: The callback for "Pre-create" happens before the end user draws the mark For example, if the user is drawing a line, LPFNIG_ART_PRECREATENOTIFYFUNC is called when the mouse is pressed. If this callback returns TRUE, then the point where the mouse was pressed becomes the first end-point of the line. The point where the user releases the mouse button becomes the second end-point. At this time LPFNIG_ART_CREATENOTIFYFUNC is called.
NOTE: In order to use this callback, it must fbe registered with ART using the function ART_callback_register().

Bits Per Pixel: All

Return Value:

Returns TRUE - mark is created; FALSE - mark isn't created.

Example:

BOOL ACCUAPI ARTCreateNotify(HIGEAR hIGear,
LPVOID lpPrivate, ART_MARK_INDEX hMarkIndex,
const LPART_MARK_ATTRIBUTES lpMarkAttr)
{
/* add a named block to each mark that gets created */
ART_mark_block_create(hIGear, hMarkIndex,
myBlockName, myBlockData, myBlockSize);
return TRUE;
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ART_DELETENOTIFYFUNC

Group: Callback

Declaration:

typedef BOOL (ACCUAPI *LPFNIG_ART_DELETENOTIFYFUNC)(
    HIGEAR		hIGear,
    LPVOID		lpPrivate,
    ART_MARK_INDEX		 hMarkIndex
    );

Arguments:

hIGear
HIGEAR handle to the image
lpPrivate
A far pointer to the private callback data
hMarkIndex
The index of the to-be-deleted mark

Description:

This function is called whenever a mark is deleted. If the callback function returns FALSE, the mark is not deleted. It should return TRUE to allow the mark to be deleted.

NOTE: In order to use this callback, it must first be registered with ART using the function ART_callback_register().

Bits Per Pixel: All

Return Value:

If the callback function returns FALSE, the mark is not deleted. It should return TRUE to allow the mark to be deleted.

Example:

BOOL ACCUAPI MyDeleteMarkFunc(HIGEAR hIGear, LPVOID
lpPrivate, ART_MARK_INDEX hMarkIndex)
{
/* before deleting the mark, copy it to the clipboard */
ART_edit_copy(hIGear, &hMarkIndex, 1);
return TRUE;
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ART_DRAWNOTIFYFUNC

Group: Callback

Declaration:

typedef VOID (ACCUAPI *LPFNIG_ART_DRAWNOTIFYFUNC)(
    HIGEAR hIGear,
    DWORD dwGrpID,
    LPVOID lpPrivate,
    HDC hDC,
    AT_MODE nWhen,
    ART_MARK_INDEX hMarkIndex,
    const LPART_MARK_ATTRIBUTES lpMarkAttr,
    const LPAT_RECT lprcClip,
    const LPAT_RECT lprcBounds,
    AT_MODE nOrientation
    );

Arguments:

hIGear
HIGEAR handle to the image
dwGrpID
Identifier of group
lpPrivate
A far pointer that takes private callback data
hDC
Windows handle to the device context to draw to
nWhen
Before or after image
hMarkIndex
Index for the mark
lpMarkAttr
Set to the ART_MARK_ATTRIBUTES structure of the mark to draw
lprcClip
Set to the AT_RECT coordinates of the clipping rectangle
lprcBounds
The scaled bounds of the mark
nOrientation
The orientation of the mark. Set to an AT_MODE constant (defined in Gear.h) that begins with IG_ORIENT_TOP_ .

Description:

When registered, this callback gets called when ART encounters a mark that it does not know how to draw. The main purpose of this callback is for painting user-defined marks that the developer has created. This callback gets called twice each time the mark needs to be painted. On the first call, the nWhen parameter is set to ART_DISPLAY_PREPAINT. This indicates that the underlying image has not repainted itself yet. On the second call, nWhen is set to ART_DISPLAY_POSTPAINT. Any drawing that is done during the pre-paint phase isclobbered by the underlying image when it paints itself. The pre-paint phase is used to create clipping regions for optimized painting. The mark is drawn during the post-paint phase. The hMarkIndex parameter indicates that the mark needs to be painted and its attributes are passed in the lpMarkAttr parameter. If the mark has extra data in named blocks that is necessary during painting, the named blocks are queried by this function.

The lprcClip parameter is the current clipping rectangle. Any drawing that occurs outside this rectangle is clipped by the operating system. This parameter is passed to give the callback an opportunity to optimize it's painting within the rectangle. The lprcBounds parameter is the rectangle of the current boundaries of the mark. This parameter differs from the rcBounds field in the ART_MARK_ATTRIBUTES structure. The rectangle in this parameter is scaled for the display and if the underlying image is rotated, then lprcBounds is rotated. The nOrientation parameter tells the callback how to orient the mark when drawn. Possible values include: IG_ROTATE_0, IG_ROTATE_90, IG_ROTATE_180 and IG_ROTATE_270.

NOTE: In order to use this callback, it must be registered with ART using the function ART_callback_register().

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

VOID ACCUAPI DRAWNOTIFYFUNC(
    HIGEAR hIGear,
    DWORD dwGrpID,
    LPVOID lpPrivate,
    HDC hDC,
    AT_MODE nWhen,
    ART_MARK_INDEX hMarkIndex,
    const LPART_MARK_ATTRIBUTES lpMarkAttr,
    const LPAT_RECT lprcClip,
    const LPAT_RECT lprcBounds,
    AT_MODE nOrientation
    )
{
    HBRUSH hBrush;
    HBRUSH hOldBrush;
    AT_RGBQUAD color = lpMarkAttr->rgbColor1;
    AT_POINT ptPoints[2];
    ptPoints[0].x = lpMarkAttr->rcBounds.left;
    ptPoints[0].y = lpMarkAttr->rcBounds.top;
    ptPoints[1].x = lpMarkAttr->rcBounds.right;
    ptPoints[1].y = lpMarkAttr->rcBounds.bottom;
    IG_dspl_image_to_device(hIGear, dwGrpID, hWnd, hDC,
ptPoints, 2);
    hBrush = CreateSolidBrush(RGB(color.rgbRed, color.rgbGreen ,
color.rgbBlue));
    hOldBrush = SelectObject(hDC, hBrush);
    Ellipse(hDC, ptPoints[0].x, ptPoints[0].y, ptPoints[1].x,
ptPoints[1].y);
    SelectObject(hDC, hOldBrush);
    DeleteObject(hBrush);
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ART_MODIFYNOTIFYFUNC

Group: Callback

Declaration:

typedef VOID (ACCUAPI *LPFNIG_ART_MODIFYNOTIFYFUNC)(
    HIGEAR				hIGear,
    LPVOID				lpPrivate,
    ART_MARK_INDEX				hMarkIndex,
    const LPART_MARK_ATTRIBUTES				lpMarkAttr,
    AT_MODE				nReason
    );

Arguments:

hIGear
HIGEAR handle to the image
lpPrivate
A far pointer to the private callback data
hMarkIndex
The index of the mark just modified
lpMarkAttr
A far pointer to an ART-defined structure of type ART_MARK_ATTRIBUTES
nReason
An integer constant of type AT_MODE, defined in ARTAPI.H. This tells what caused the callback to be called.

Description:

This function is called after a mark has been modified. A mark is modified if it is moved, resized or edited.

Upon entry, nReason is set to a constant indicating what triggered the modification. Your application displays one of the library's standard editing dialog boxes. Here is the list of "reasons" why this callback will be called:

ART_MODIFY_ATTRIBUTES
One or more attributes have been modified (from the ART_MARK_ATTRIBUTES structure)
ART_MODIFY_ANODAT
A named block specific to this type of mark was modified
ART_MODIFY_FILNAM
The filename block was modified
ART_MODIFY_DIB
The embedded DIB was changed
ART_MODIFY_GROUP
The mark's group block was modified
ART_MODIFY_INDEX
The mark's index block was changed
ART_MODIFY_ANTEXT
The orientation or length of text mark have been modified
ART_MODIFY_NAMED_BLOCK
A user-defined named block was modified

NOTE: In order to use this callback, it must be registered with ART using the function ART_callback_register().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

VOID ACCUAPI ARTModifyNotify( HIGEAR hIGear, LPVOID
lpPrivate, ART_MARK_INDEX hMarkIndex,
const LPART_MARK_ATTRIBUTES lpMarkAttr,
AT_MODE nReason)
{
switch (nReason)
{
case ART_MODIFY_ATTRIBUTES:
/* indicate to the user that the highlight */
/* attribute was changed */
    if (lpMarkAttr->bHighlighting)
MessageBox(HWND_DESKTOP, "The mark is "
"highlighted", NULL, MB_OK);
}
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ART_MOUSENOTIFYFUNC

Group: Callback

Declaration:

typedef VOID (ACCUAPI *LPFNIG_ART_MOUSENOTIFYFUNC)(
    HIGEAR		hIGear,
    LPVOID		lpPrivate,
    ART_MARK_INDEX		hMarkIndex,
    AT_MODE		nReason,
    const LPAT_POINT			lpPoint
    );

Arguments:

hIGear
HIGEAR handle to the image
lpPrivate
A far pointer to the private callback data
hMarkIndex
The index number (identifier) for the new mark
nReason
An ART-defined constant of type AT_MODE that determines why this callback has been called. See below.
lpPoint
A far pointer structure of type AT_POINT that gives the screen coordinates of the position of the mouse at the time of the callback.

Description:

This callback is used during run-mode. It is called when the end user interacts with marks using the mouse, including clicking on a mark or passing over one. Here are the settings for nReason:

ART_MOUSE_LBUTTON_DOWN
Left button held down
ART_MOUSE_LBUTTON_DBL_CLICK
Left button double-clicked
ART_MOUSE_LBUTTON_UP
Left button up
ART_MOUSE_RBUTTON_DOWN
Right button down
ART_MOUSE_RBUTTON_DBL_CLICK
Right button double-clicked
ART_MOUSE_RBUTTON_UP
Right button up
ART_MOUSE_ENTER
The mouse cursor is entering a mark
ART_MOUSE_LEAVE
The mouse cursor is leaving a mark

This callback is called for each reason. You can put a switch statement into the callback function to respond or ignore each reason.

NOTE: In order to use this callback, it must be registered with ART using the function ART_callback_register().
NOTE: Here are the definitions for ART_MOUSE_ENTER and ART_MOUSE_LEAVE:
_ENTER: The mouse moves over any visible portion of a mark.
_LEAVE: The mouse was over a mark; the mouse moved; and the mouse is off the mark.

Bits Per Pixel: All

Return Value:

This callback function does not return a value.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ART_OVERRIDEDRAWNOTIFYFUNC

Group: Callback

Declaration:

typedef BOOL (ACCUAPI *LPFNIG_ART_OVERRIDEDRAWNOTIFYFUNC)(
    HIGEAR				hIGear,
    DWORD				dwGrpID,
    LPVOID				lpPrivate,
    HDC				hDC,
    AT_MODE				nWhen,
    ART_MARK_INDEX				hMarkIndex,
    const LPART_MARK_ATTRIBUTES				lpMarkAttr,
    const LPAT_RECT				lprcClip,
    const LPAT_RECT				lprcBounds,
    AT_MODE				nOrientation
    );

Arguments:

hIGear
HIGEAR handle to the image
dwGrpID
Identifier of group
lpPrivate
A far pointer that takes private callback data
hDC
Windows handle to the drawing device
nWhen
Before or after image
hMarkIndex
Index for the mark
lpMarkAttr
Set to the ART_MARK_ATTRIBUTES structure of the mark to draw
lprcClip
Set to the AT_RECT coordinates of the clipping rectangle
lprcBounds
The scaled bounds of the mark
nOrientation
The orientation of the mark. Set to an AT_MODE constant (defined in Gear.h) that begins with IG_ROTATE_ .

Description:

This callback operates similar to the LPFNIG_ART_DRAWNOTIFYFUNC callback. However, this callback is called for known marks, instead of user-defined marks. The purpose of this callback is to let the developer draw the standard marks, instead of letting the library do it.

All of the parameters are the same as LPFNIG_ART_DRAWNOTIFYFUNC. The return value is different. When this callback returns TRUE, it means that the library does not draw the mark. When it returns FALSE, the callback did not handle the drawing of the mark and the library draws the mark. This callback can be used to draw all mark types or just a few marks. The developer can check the dwType field of the lpMarkAttr parameter to determine if they want to draw this type of mark, or let the library handle it.

Finally the nOrientation parameter tells the callback how to orient the mark when drawn. Possible values include IG_ROTATE_0, IG_ROTATE_90, IG_ROTATE_180 and IG_ROTATE_270.

NOTE: In order to use this callback, it must be registered with ART using the function ART_callback_register().

Bits Per Pixel: All

Return Value:

Returns FALSE if the callback did not handle the drawing of the mark and the library did.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ART_POSTCREATENOTIFYFUNC

Group: Callback

Declaration:

typedef BOOL (ACCUAPI *LPFNIG_ART_POSTREATENOTIFYFUNC)(
    HIGEAR			hIGear,
    LPVOID			lpPrivate,
    ART_MARK_INDEX			hMarkIndex,
    LPART_MARK_ATTRIBUTES			lpMarkAttr
    );

Arguments:

hIGear
HIGEAR handle of an image.
lpPrivate
A far pointer to the private callback data.
hMarkIndex
The index number (identifier) for the new mark.
lpMarkAttr
A far pointer to an ART-defined attribute structure of type AT_MARK_ATTRIBUTES. This can be used to override the default mark attributes before the new created mark is displayed.

Description:

This callback function is called just before a mark is displayed. The MarkIndex passed into the callback is the MarkIndex of the created mark. This callback function gives the developer an opportunity to change any default named blocks or the mark attributes of the mark that is just created.

NOTE: The callback for "Post create" occurs just after the end user draws the mark. For example, if the user draws a line, LPFNIG_ART_POSTCREATENOTIFYFUNC is called when the right mouse button is released and when the mark and all mark named blocks are created.
NOTE: In order to use this callback, it must be registered with ART using the function ART_callback_register().

Bits Per Pixel: All

Return Value:

Returns TRUE - the mark attributes are changed; FALSE - no change.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ART_PRECREATENOTIFYFUNC

Group: Callback

Declaration:

typedef BOOL (ACCUAPI *LPFNIG_ART_PRECREATENOTIFYFUNC)(HIGEAR
hIGear,
    LPVOID			lpPrivate,
    ART_MARK_INDEX			hMarkIndex,
    LPART_MARK_ATTRIBUTES			lpMarkAttr
    );

Arguments:

hIGear
HIGEAR handle of an image.
lpPrivate
A far pointer to the private callback data.
hMarkIndex
The index number (identifier) for the new mark.
lpMarkAttr
A far pointer to an ART-defined attribute structure of type AT_MARK_ATTRIBUTES. This can be used to override the default mark attributes before the new mark is created.

Description:

This callback function is called just before a mark is created. The MarkIndex passed into the callback is the MarkIndex that is used when the mark is created. This callback function gives the developer an opportunity to change any default named blocks or the mark attributes for the mark that is about to be created.

NOTE: The callback for "Pre create" occurs before the end user draws the mark. For example, if the user draws a line, LPFNIG_ART_PRECREATENOTIFYFUNC is called when the mouse is pressed. If this callback returns TRUE, then the point where the mouse was pressed becomes the first end-point of the line. The point where the user releases the mouse button becomes the second end-point. At this time LPFNIG_ART_CREATENOTIFYFUNC is called.

The return value is either TRUE or FALSE. When set to FALSE, the mark is not created. When set to TRUE, the mark is created.

NOTE: In order to use this callback, it must be registered with ART using the function ART_callback_register().

Bits Per Pixel: All

Return Value:

Returns TRUE - the mark is created; FALSE - the mark is not created.

Example:

BOOL ACCUAPI MyChangeAttributes (HIGEAR hIGear,
LPVOID lpPrivate, ART_MARK_INDEX hMarkIndex,
LPART_MARK_ATTRIBUTES lpMarkAttr)
{
if (lpMarkAttr.dwType == 6) /* if mark is a filled */
   /* rectangle  */
{
lpMarkAttr.bHighlighting = TRUE;
/* apply highlighting to the mark */
}
return TRUE;
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ART_PREMODIFYNOTIFYFUNC

Group: Callback

Declaration:

typedef BOOL (ACCUAPI *LPFNIG_ART_PREMODIFYNOTIFYFUNC)(HIGEAR
hIGear,
    LPVOID				lpPrivate,
    ART_MARK_INDEX				hMarkIndex,
    const PART_MARK_ATTRIBUTES				lpMarkAttr,
    AT_MODE				nReason
    );

Arguments:

hIGear
HIGEAR handle of an image.
lpPrivate
A far pointer to private callback data.
hMarkIndex
The index number to the mark to be modified.
lpMarkAttr
Set to type ART_MARK_ATTRIBUTES that is associated with the mark.
nReason
An integer constant of type AT_MODE, defined in ARTAPI.H. This indicates what caused the callback.

Description:

This function is called whenever a mark attribute is about to be modified. A mark is modified if it is moved, resized or edited.

If this callback function returns FALSE, the mark does not change. Set it to TRUE to allow the mark to be modified. Upon entry, nReason is set to a constant indicating what triggered the modification. At this point your application can display one of the library's standard editing dialog boxes. "Reasons" this callback is called may be:

ART_MODIFY_ATTRIBUTES
One or more attributes have been modified (from the ART_MARK_ATTRIBUTES structure).
ART_MODIFY_ANODAT
A named block specific to this type of mark was modified.
ART_MODIFY_FILNAM
The filename block was modified.
ART_MODIFY_DIB
The embedded DIB was changed.
ART_MODIFY_GROUP
The mark's group block was modified.
ART_MODIFY_INDEX
The mark's index block was changed.
ART_MODIFY_ANTEXT
The orientation or length of text mark was modified.
ART_MODIFY_NAMED_BLOCK
A user-defined named block was modified.

NOTE: In order to use this callback, it must be registered with ART using the function ART_callback_register().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

BOOL ACCUAPI ARTPreModifyNotify( HIGEAR hIGear,
LPVOID lpPrivate, ART_MARK_INDEX hMarkIndex,
const LPART_MARK_ATTRIBUTES lpMarkAttr,
AT_MODE nReason)
{
switch (nReason)
{
case ART_MODIFY_ATTRIBUTES:
    /* prevent the highlighting attribute from being */
 /* enabled */
 if (lpMarkAttr->bHighlighting)
    return FALSE;
}
return TRUE;
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ART_SELECTNOTIFYFUNC

Group: Callback

Declaration:

typedef BOOL (ACCUAPI *LPFNIG_ART_SELECTNOTIFYFUNC)(HIGEAR
hIGear,
    LPVOID		lpPrivate,
    ART_MARK_INDEX		hMarkIndex,
    BOOL		fSelect
    );

Arguments:

hIGear
HIGEAR handle of an image.
lpPrivate
A far pointer to the private callback data.
hMarkIndex
The index for the selected mark.
fSelect
A flag of type BOOL indicating the new selection state (selected/unselected).

Description:

This function is called by the library when the selection state of a mark is changed. If the callback function returns FALSE, the mark's selection state is not changed. It returns TRUE to allow the selection state to be changed.

NOTE: In order to use this callback, it must be registered with ART using the function ART_callback_register().

Bits Per Pixel: All

Return Value:

Returns FALSE for the mark's selection state to remain unchanged; returns TRUE to allow the mark's selection state to change.

Example:

BOOL ACCUAPI ARTSelectNotify(HIGEAR hIGear, LPVOID
lpPrivate, ART_MARK_INDEX hMarkIndex, BOOL fSelect)
{
ART_MARK_ATTRIBUTES  ma;
ART_mark_query(hIGear, hMarkIndex, &ma);
if (ma.dwType == ART_MARK_BUTTON && fSelect == TRUE)
{
    /* prevent button marks from being selected */
    return FALSE;
}
return TRUE;
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ART_TEXTOVERFLOWNOTIFYFUNC

Group: Callback

Declaration:

typedef AT_BOOL (ACCUAPI
*LPFNIG_ART_TEXTOVERFLOWNOTIFYFUNC)(HIGEAR  hIGear,
    LPVOID		lpPrivate,
    ART_MARK_INDEX		hMarkIndex,
    DWORD		dwMarkType,
    const LPAT_RECT		lprcPreferableBounds,
    DWORD		dwTextLength,
    DWORD		dwReserved
    );

Arguments:

hIGear
HIGEAR handle of an image.
lpPrivate
A pointer to the private callback data.
hMarkIndex
The index for the selected mark.
dwMarkType
The type of selected mark. Currently it can be
ART_MARK_TYPED_TEXT, ART_MARK_ATTACH_A_NOTE, ART_MARK_TEXT_FROM_FILE
lprcPreferableBounds
Preferable mark bounds to draw whole mark text (cut to clip bounds)
dwTextLength
The length of overflowed text (the last NULL is not included). If the text is not overflowed must be set to 0
dwReserved
Reserved for future use. Currently should be set to 0

Description:

This callback function is called after the text mark is resized by mouse dragging and before the mark is repainted. It is called independently on whether the text overflows the mark bounds or not. It is applied for ART_MARK_TYPED_TEXT, ART_MARK_ATTACH_A_NOTE and ART_MARK_TEXT_FROM_FILE marks.

The return value is ignored at this time. Using this callback function customer has possibility to change the mark bounds or apply ART_GUI_text_flow () after resizing of the text mark bounds.

To use this callback, it should be registered using the function:

ART_callback_register (hIGear,
ART_CALLBACK_TEXT_OVERFLOW_NOTIFY, TextOverflowNotify, NULL);

Bits Per Pixel: All

Return Value:

Returns FALSE for the mark's selection state to remain unchanged; returns TRUE to allow the mark's selection state to change.

Example:

HIGEAR hIGear;
HWND hWnd;
ART_MARK_INDEX markIndexes[3]; /* array of processed mark
indexes*/
/* ... */
/* Initialize the markIndexes array anywhere*/
/* and call */
/* ART_callback_register(hIGear,
ART_CALLBACK_TEXT_OVERFLOW_NOTIFY, TextOverflowNotify,
lpPrivate);*/
/* to register TextOverflowNotify callback function*/
/* ... */
AT_BOOL ACCUAPI TextOverflowNotify(
HIGEAR hIGear,
LPVOID lpPrivate,
ART_MARK_INDEX hMarkIndex,
DWORD dwMarkType,
const LPAT_RECT lprcPreferedBounds,
DWORD dwOverflowedTextLength,
DWORD dwReserved
)
{
AT_ERRCOUNT nErrCount;
ART_MARK_ATTRIBUTES ma;
AT_RECT rcBounds;
DWORD dwTextLength;
/* The ART_GUI_text_flow is applied only for ART_MARK_TYPED_TEXT
and ART_MARK_ATTACH_A_NOTE */
if ( dwMarkType != ART_MARK_TYPED_TEXT && dwMarkType !=
ART_MARK_ATTACH_A_NOTE )
return TRUE;
if ( hMarkIndex == markIndexes[0] )
{
nErrCount = ART_GUI_text_flow(hIGear, IG_GRP_DEFAULT, hWnd,
(LPART_MARK_INDEX)markIndexes, 3 );
if ( nErrCount == 0 )
nErrCount = ART_GUI_mark_paint( hIGear, IG_GRP_DEFAULT,
markIndexes[1], hWnd, TRUE );
}
else if ( hMarkIndex == markIndexes[1] )
{
nErrCount = ART_GUI_text_flow( hIGear, 0, hWnd,
(LPART_MARK_INDEX)(markIndexes + 1), 2 );
}
/* Set preferable bounds to the third mark */
/* If you do not want to change the mark size remove the
following code */
if ( hMarkIndex != markIndexes[2] && nErrCount == 0 )
{
ART_GUI_mark_paint( hIGear, IG_GRP_DEFAULT, markIndexes[2],
hWnd,FALSE );
nErrCount = ART_mark_query( hIGear, markIndexes[2], &ma );
/* Get the preferable bounds for third mark*/
if ( nErrCount == 0 )
nErrCount = ART_GUI_text_overflow_check( hIGear,
IG_GRP_DEFAULT,
hWnd, markIndexes[2], &rcBounds, &dwTextLength);
if ( nErrCount == 0 )
{
/*Change the bounds*/
ma.rcBounds = rcBounds;
ART_mark_modify( hIGear, markIndexes[2], &ma );
/*Repaint the mark*/
ART_GUI_mark_paint( hIGear, IG_GRP_DEFAULT, markIndexes[2],
hWnd, TRUE );
}
}
return TRUE;
}

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


Core Component API Function Reference

This Chapter provides detailed information about all ImageGear Core component functions and callbacks:

  • Core Component Functions Reference
  • Core Component Callback Functions Reference
  • Core Component Enumerations


Core Component Functions Reference

This section describes each function supported by ImageGear Core component, in alphabetical order.


IG_ascii_import

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_ascii_import (
    const LPSTR lpszFileName,
    UINT nPageNumber,
    LPHIGEAR lphIGear
);

Arguments:

lpszFileName
Set to the path/filename of the text file to load.
nPageNumber
Set to the number of the page to load; if not a multipage file, set to 1.
lphIGear
A far pointer that returns a HIGEAR handle for your newly loaded image.

Description:

This function loads an ASCII (.TXT) file into ImageGear. Specify the path/filename of the file and which page of the file (if it is a multi-page file) you would like to load. ImageGear then returns a HIGEAR handle to the newly loaded image.

To set the control parameters of the loaded file, use IG_fltr_ctrl_set (). The TXT filter control parameters are listed in the section TXT (ASCII Text) .

You may also use IG_load_file () to load an ASCII file.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_ascii_page_width_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_ascii_page_width_get (
    const LPSTR lpszFileName,
    LPUINT lpPageWidth
);

Arguments:

lpszFileName
Set to the name of the ASCII file from which to get the width.
lpPageWidth
A far pointer that returns a value of type UINT indicating the width of the file in thousands of an inch.

Description:

This function returns the width of an ASCII file that has not been loaded yet. Simply supply it with the path/filename of an ASCII file and it will return the width in thousands of an inch. For example, if the file has a width of 8.5 inches, this function returns the value 8500.

The width of the page (as well as many other attributes) can be set before the page is loaded. See the description for IG_ascii_import () for the full list of attributes that can be determined prior to loading.

As an alternative to this function, you can use IG_fltr_ctrl_get () with the control parameter argument "PAGE_WIDTH".

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;        /* HIGEAR handle of image   */
AT_ERRCOUNT nErrcount;     /* total # of ImageGear errors on the
stack*/
UINT pageWidth;     /* returns the width of the ASCII file */
UINT pointSize;     /* to get and possibly set the point size of
the font */
AT_REAL reduction;    /* percentage of reduction possibly needed
on the point size before the image is loaded with a width of 8.5
inches   */
nErrcount = IG_ascii_page_width_get("Hamlet.txt", &pageWidth);
if (pageWidth > 8500)
/* if the width of the unloaded page is greater than 8.5 inches,
we will resize it to 8.5 inches before loading it. However, to
avoid cropping any words, we will first reduce the point size by
the percentage needed to make each line fit on an 8.5 inch page
*/
{
    reduction = 8500/pageWidth;
    pointSize = (UINT)(pointSize * reduction + 0.5);
    nErrcount =
        IG_fltr_ctrl_set(IG_FORMAT_TXT, "POINT_SIZE",
        (LPVOID)pointSize, sizeof(pointSize));
    nErrcount =
        IG_fltr_ctrl_set(IG_FORMAT_TXT, "PAGE_WIDTH",
        (LPVOID)8500, sizeof(nPageWidth));
}
nErrcount = IG_ascii_import("Hamlet.txt", 1, &hIGear);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_batch_CB_register

Group: Callback

Declaration:

AT_ERRCOUNT ACCUAPI IG_batch_CB_register(
    LPVOID lpfnBatchCB,
    AT_MODE nCBType,
    LPVOID lpPrivate
);

Arguments:

lpfnBatchCB
A far pointer to the scan callback function you would like to register.
nCBType
Set to the type of callback being registered. Use one of the following ImageGear- defined constants:
  • IG_BATCHCB_BEFORE_OPEN
  • IG_BATCHCB_BEFORE_SAVE
lpPrivate
Optional pointer to from which to pass and receive data. Set this to NULL if this is not required.

Description:

This function registers one of two available batch callback functions.

  • LPFNIG_BATCH_BEFORE_OPEN is called before a file is opened, allowing you to get the file name and correct some settings. For example, some multimedia formats and PDF files require you to get the file name before converting a page.
  • LPFNIG_BATCH_BEFORE_SAVE is called before an image file is saved, allowing you to correct an image before saving it. For example, you might want to rotate an image before saving it.

Bits per pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See example the code for the LPFNIG_BATCH_BEFORE_SAVE and LPFNIG_BATCH_BEFORE_OPEN functions.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_clipboard_copy

Group: Clipboard

Declaration:

AT_ERRCOUNT ACCUAPI IG_clipboard_copy (
    HIGEAR hIGear,
    const LPAT_RECT lprcRectToCopy
);

Arguments:

hIGear
HIGEAR handle of the current image.
rcRectToCopy
Far pointer to an AT_RECT struct specifying the rectangular portion of the image that is to be copied to the clipboard.

Description:

This function copies the specified portion of the image to the system clipboard. If rcRectToCopy = NULL, the entire image will be copied.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask ().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR       hIGear;        /* HIGEAR handle of image  */
AT_RECT      rcRectToCopy;  /* Rectangle of image to copy to
clipboard */
AT_DIMENSION nImageWidth;    /* Width of image  */
AT_DIMENSION nImageHeight;  /* Height of image  */
/* Copy bottom half of image to system clipboard:  */
rcRectToCopy.left   = 0;
rcRectToCopy.top    = nImageHeight / 2;
rcRectToCopy.right  = nImageWidth - 1;
rcRectToCopy.bottom = nImageHeight - 1;
IG_clipboard_copy ( hIGear, &rcRectToCopy );

Sample: CLPBRD, IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_clipboard_cut

Group: Clipboard

Declaration:

AT_ERRCOUNT ACCUAPI IG_clipboard_cut (
    HIGEAR hIGear,
    const LPAT_RECT lprcRegion,
    const LPAT_PIXEL lpPixel
);

Arguments:

hIGear
HIGEAR handle of current image
lprcRegion
A long pointer to a rectangular region of the image, which should be copied to the clipboard and removed from the image.
lpPixel
A long pointer to a pixel value you would like to be used to fill in the area out of which the region has been cut.

Description:

This function "cuts away" a portion of an image. The cut portion is copied to the clipboard with its original pixel values, while in the displayed image, that rectangle is replaced by a pixel value as specified by lpPixel. The color used is usually black or white. You can restore the image to its original composition by calling IG_clipboard_paste_merge_ex (). You then set the x and y positions of the upper left-hand corner arguments to PIXPOS left and PIXPOS right of the image rectangle defined by lprcRegion. If you save the image after a call to this function, it will be saved with the cut.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE (i.e. an NRA mask is active), and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROIdefined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

For 24-bit images, lpPixel must point to 3 bytes where the first byte is red, the second - green and the third - blue. For all other bit depths, lpPixel must point to a single byte.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR        hIGear;     /* HIGEAR handle of image  */
AT_ERRCOUNT   nErrcount;  /* # of IG errors on the stack  */
AT_RECT       rcRegion;   /* Rectangular region to cut from image
*/
AT_PIXEL      pixel       /* Pixel value used when filling cut
regions */
pixel = 0;
/* For a currently loaded 1-bit image where black = 0, set the
cut area to black*/
nErrcount = IG_clipboard_cut ( hIGear, &rcRegion, &pixel );

Sample: CLPBRD, IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_clipboard_dimensions

Group: Clipboard

Declaration:

AT_ERRCOUNT ACCUAPI IG_clipboard_dimensions (
    LPAT_DIMENSION lpWidth,
    LPAT_DIMENSION lpHeight,
    LPUINT lpBitsPerPixel
);

Arguments:

lpWidth
Far pointer to a variable of type AT_DIMENSION to receive the width in pixels of the image currently in the system clipboard.
lpHeight
Far pointer to a variable of type AT_DIMENSION to receive the height in rows of the image currently on the system clipboard.
lpBitsPerPixel
Far pointer to a variable of type UINT to receive the bit depth, in bits per pixel, of the image currently on the system clipboard.

Description:

This function obtains the dimensions of the image currently in the system clipboard. Prior to calling this function you should call IG_clipboard_paste_available_ex (), to verify that there is a pasteable image in the system clipboard.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_DIMENSION   nWidth, nHeight;   /* holds the images's width
and height   */
UINT           nBpp;              /* holds the bits per pixel   */
AT_ERRCOUNT    nErrcount; /* holds athe returned error count */
BOOL           bPasteAvail;     /* TRUE if a pasteable image is
on the clipboard */
 /* If a pasteable image is on the clipboard, get its
dimensions: */
IG_clipboard_paste_available ( &bPasteAvail);
if ( bPasteAvail )
  {
nErrcount = IG_clipboard_dimensions ( &nWidth, &nHeight, &nBpp
);
  }

Sample: CLPBRD

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_clipboard_paste

Group: Clipboard

Declaration:

AT_ERRCOUNT ACCUAPI IG_clipboard_paste (
    LPHIGEAR lphIGear
);

Arguments:

lphIGear
Far pointer to a variable of type HIGEAR, to receive the HIGEAR handle of the image created by this operation

Description:

This function creates a HIGEAR image by pasting the image on the system clipboard. Prior to calling this function, call IG_clipboard_paste_available_ex () to verify that there is a paste-able image in the clipboard.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear; /* Receives the HIGEAR handle the image created
*/
BOOL bPasteAvail;  /* TRUE if a pasteable image is present  */
AT_ERRCOUNT   nErrcount;    /* Holds the returned error count*/
IG_clipboard_paste_available ( &bPasteAvail);
if ( bPasteAvail )
/* Create HIGEAR image from contents of system clipboard:*/
    { nErrcount = IG_clipboard_paste ( &hIGear );
    if ( nErrcount )  { ... } /* Process any errors ...*/ }

Sample: CLPBRD, IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_clipboard_paste_available_ex

Group: Clipboard

Declaration:

AT_ERRCOUNT ACCUAPI IG_clipboard_paste_available_ex (
    LPBOOL lpPasteStatus,
    LPAT_MODE lpRegionType
);

Arguments:

lpPasteStatus
A far pointer that returns TRUE if the clipboard contains a region of interest that can be pasted into an image.
lpRegionType
A far pointer that returns the type of region stored in the clipboard. Currently the valid values are IG_REGION_IS_RECT, IG_REGION_IS_NON_RECT, IG_REGION_IS_NOT_AVAIL.

Description:

This function tells you whether the clipboard contains a valid image or region of interest (ROI) that can be pasted into an image. It also returns the type of region contained in the clipboard: rectangular, non-rectangular, or not available. If the clipboard does contain a a valid ROI, lpPasteStatus returns TRUE; if lpPasteStatus returns FALSE, the region type returned is IG_REGION_IS_NOT_AVAIL.

A return value of FALSE does not necessarily mean that the clipboard is empty. It could mean that the clipboard contains non-valued ROI data or text, or that it contains multimedia data.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: To paste a rectangular or non-rectangular ROI into the current image, call IG_clipboard_paste_merge_ex().

Example:

AT_ERRCOUNT nErrcount;
HIGEAR hIGear;
BOOL bNRpasteAvail; /* TRUE if a pasteable image is on clipboard
*/
AT_MODE nRegionType; /* type of region on the clipboard */
nErrcount = IG_clipboard_paste_available_ex(&bNRpasteAvail,
&nRegionType);
if (bNRpasteAvail)
    (...)

Sample: IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_clipboard_paste_merge_ex

Group: Clipboard

Declaration:

AT_ERRCOUNT ACCUAPI IG_clipboard_paste_merge_ex(
    HIGEAR  hIGear,
    AT_PIXPOS nLeftPos,
    AT_PIXPOS nTopPos
);

Arguments:

hIGear
Set to the HIGEAR handle of the image in which to merge the clipboard contents.
nLeftPos
X position in HIGEAR image at which to place the upper left corner of the clipboard image when merging.
nTopPos
Y position in HIGEAR image at which to place the upper left corner of the clipboard image when merging.

Description:

This function pastes a rectangular or non-rectangular clipboard image into the HIGEAR image that you specify. To check if there is a pasteable image on the clipboard, call IG_clipboard_paste_available_ex ().

nLeftPos and nTopPos set the (x,y) coordinates of the upper-left corner of the bounding rectangle of the original image. See image below. The image has an (x,y) location within it at which the upper left-corner of the bounding rectangle will be placed. The white circle enclosed within a gray rectangle represents the non-rectangular ROI image stored in the clipboard, where the shaded area represents the transparent area between the bounding rectangle and the non-rectangular ROI. When the clipboard image is merged, only the circle will appear on the image.

NOTE: Use IG_clipboard_paste_op_set() to tell ImageGear what kind of merge operation to perform.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: This function will automatically call IG_clipboard_paste_available_ex() to confirm that there is data available. Therefore, it is not mandatory to call IG_clipboard_paste_available_ex() before making this call, unless you are interested in knowing the type of region contained in the clipboard.

Example:

AT_ERRCOUNT nErrcount;
HIGEAR 	hIGear;
BOOL 	bNRpasteAvail;
AT_PIXPOS 	xpos, ypos;
AT_MODE 	nRegionType;
nErrcount = IG_clipboard_paste_available_ex(&bNRpasteAvail,
&nRegionType);
nErrcount = IG_clipboard_paste_merge_ex(hIGear, xpos, ypos);

Sample: IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_clipboard_paste_op_get

Group: Clipboard

Declaration:

AT_ERRCOUNT ACCUAPI IG_clipboard_paste_op_get (
    HIGEAR hIGear,
    LPAT_MODE lpOperation
);

Arguments:

hIGear
HIGEAR handle of image
lpOperation
A long pointer to an integer constant of type AT_MODE. This will return the current setting for the kind of paste merge operation that will be performed.

Description:

This function returns the current paste-merge operation that will be used when an image from the clipboard is merged into the currently loaded image using IG_clipboard_paste_merge_ex (). See the description of IG_clipboard_paste_op_set () for the list of possible settings.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;      /* HIGEAR handle of image    */
AT_MODE nOperation;  /* current setting for paste-merge
operation */
AT_ERRCOUNT nErrcount    /* # of IG errors currently on the
stack  */
nErrcount = IG_clipboard_paste_op_get (hIGear, &nOperation);

Sample: CLPBRD, IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_clipboard_paste_op_set

Group: Clipboard

Declaration:

AT_ERRCOUNT ACCUAPI IG_clipboard_paste_op_set (
    HIGEAR hIGear,
    AT_MODE nOperation
);

Arguments:

hIGear
HIGEAR handle of the image that is in the system.
nOperation
An integer constant of type AT_MODE which will be used in future calls to IG_clipboard_paste_merge_ex ().

Description:

This function sets the kind of operation to use for future calls to IG_clipboard_paste_merge_ex (). nOperation is an integer constant of type AT_MODE that is defined in accucnst.h. Here are the possible settings and what kind of operation each one will perform on the values of the merging pixels:

IG_ARITH_ADD
Img1 = Img1 + Img2
IG_ARITH_SUB
Img1 = Img1 - Img2
IG_ARITH_MULTI
Img1 = Img1 * Img2
IG_ARITH_DIVIDE
Img1 = Img1 / Img2
IG_ARITH_AND
Img1 = Img1 & Img2
IG_ARITH_OR
Img1 = Img1 | Img2
IG_ARITH_XOR
Img1 = Img1 ^ Img2
IG_ARITH_ADD_SIGN_CENTERED
Img1 = Img1 + SC_Img2
IG_ARITH_NOT
Img1 = ~Img1
IG_ARITH_OVER
Img1 = Img2

You can also set nOperation to 0, which is the default. This will cause the image in the clipboard to just be copied over the currently loaded image - no merging of intersecting pixel values will occur.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR       hIGear;         /* HIGEAR handle of image      */
AT_ERRCOUNT  nErrcount       /* # of IG errors on the stack */
nErrcount = IG_clipboard_paste_op_set( hIGear, IG_ARITH_AND );

Sample: CLPBRD, IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_colorbook_add_color

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_add_color(
    HIGCOLORBOOK hColorBook,
    HIGCOLORBOOKCOLOR hColorBookColor
);

Parameters:

hColorBook
Color book object.
hColorBookColor
ColorBook Color to add.

Description:

This method adds a new Color to the color book.


IG_colorbook_color_by_index_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_color_by_index_get(
    HIGCOLORBOOK hColorBook,
    AT_UINT nIndex,
    HIGCOLORBOOKCOLOR *lphColorBookColor
);

Parameters:

hColorBook
Color book object.
nIndex
Index of the requested color in the color book.
hColorBookColor
Obtained ColorBook Color.

Description:

This method gets a color with the specified index from the color book.


IG_colorbook_color_count_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_color_count_get(
    HIGCOLORBOOK hColorBook,
    AT_UINT *lpnCount
);

Parameters:

hColorBook
Color book object.
lpnCount
Number of colors in the ColorBook.

Description:

This method gets the number of colors in the ColorBook.


IG_colorbook_color_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_color_get(
    HIGCOLORBOOK hColorBook,
    AT_QWORD nColorID,
    HIGCOLORBOOKCOLOR *lphColorBookColor
);

Parameters:

hColorBook
Color book object.
nColorID
Color ID of the requested color in the color book.
hColorBookColor
Obtained ColorBook Color.

Description:

This method gets a color with the specified ID from the color book.


IG_colorbook_color_type_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_color_type_get(
    HIGCOLORBOOK hColorBook,
    enumIGColorSpaceIDs *lpColorType
);

Parameters:

hColorBook
Color book object.
lpColorType
ColorBook color type.

Description:

This method gets ColorBook color type.


IG_colorbook_colors_per_page_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_colors_per_page_get(
    HIGCOLORBOOK hColorBook,
    AT_UINT *lpnColorsPerPage
);

Parameters:

hColorBook
Color book object.
lpnColorsPerPage
Number of colors per page in the ColorBook.

Description:

This method gets the number of colors per page in the ColorBook (should be not greater than 9).


IG_colorbook_create

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_create(
    enumIGSpotColorVendorIDs VendorID,
    LPCHAR lpTitle,
    enumIGColorSpaceIDs ColorType,
    HIGCOLORBOOK *lphColorBook
);

Parameters:

VendorID
Vendor ID of the new ColorBook
lpTitle
Title of the new ColorBook
ColorType
Color space of new ColorBook
lphColorBook
Created ColorBook.

Description:

This method creates a new ColorBook from the specified parameters.


IG_colorbook_create_from_file

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_create_from_file(
    LPCHAR lpFileName,
    HIGCOLORBOOK *lphColorBook
);

Parameters:

lpFileName
Color book filename.
lphColorBook
Created ColorBook.

Description:

This method creates a new ColorBook from file.


IG_colorbook_description_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_description_get(
    HIGCOLORBOOK hColorBook,
    LPCHAR *lpDescription
);

Parameters:

hColorBook
Color book object.
lpDescription
ColorBook's description.

Description:

This method gets description of the ColorBook.


IG_colorbook_filename_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_filename_get(
    HIGCOLORBOOK hColorBook,
    LPCHAR *lpFileName
);

Parameters:

hColorBook
Color book object.
lpFileName
Filename of the ColorBook.

Description:

This method gets filename of the ColorBook if it was read from the file.


IG_colorbook_key_color_page_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_key_color_page_get(
    HIGCOLORBOOK hColorBook,
    AT_UINT *lpnKeyColorPage
);

Parameters:

hColorBook
Color book object.
lpnKeyColorPage
KeyColorPage attribute of the ColorBook.

Description:

This method gets KeyColorPage attribute of the ColorBook (should not be greater than colors per page count).


IG_colorbook_postfix_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_postfix_get(
    HIGCOLORBOOK hColorBook,
    LPCHAR *lpPostfix
);

Parameters:

hColorBook
Color book object.
lpPostfix
ColorBook's postfix.

Description:

This method gets postfix of the ColorBook.


IG_colorbook_prefix_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_prefix_get(
    HIGCOLORBOOK hColorBook,
    LPCHAR *lpPrefix
);

Parameters:

hColorBook
Color book object.
lpPrefix
ColorBook's prefix.

Description:

This method gets prefix of the ColorBook.


IG_colorbook_title_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_title_get(
    HIGCOLORBOOK hColorBook,
    LPCHAR *lpTitle
);

Parameters:

hColorBook
Color book object.
lpTitle
ColorBook's title.

Description:

This method gets title of the ColorBook.


IG_colorbook_vendor_id_get

Group: ColorBook

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbook_vendor_id_get(
    HIGCOLORBOOK hColorBook,
    enumIGSpotColorVendorIDs *lpVendorId
);

Parameters:

hColorBook
Color book object.
lpVendorID
Obtained Vendor ID.

Description:

This method gets Vendor ID of the ColorBook.


IG_colorbooks_add_colorbook

Group: ColorBooks

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbooks_add_colorbook(
    HIGCOLORBOOK hColorBook
);

Parameters:

hColorBook
Color book to add.

Description:

This method adds the specified color book to the color books collection.


IG_colorbooks_add_colorbook_from_file

Group: ColorBooks

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbooks_add_colorbook_from_file(
    LPCHAR lpFileName
);

Parameters:

lpFileName
Color book filename (an *.acb file),

Description:

This method adds a color book from file to the ColorBooks collection.


IG_colorbooks_colorbook_by_index_get

Group: ColorBooks

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbooks_colorbook_by_index_get(
    AT_UINT nIndex,
    HIGCOLORBOOK *lphColorBook
);

Parameters:

nIndex
Index of the requested ColorBook.
lphColorBook
Obtained ColorBook object.

Description:

This method gets a ColorBook object with the specified index from the ColorBooks collection.


IG_colorbooks_colorbook_get

Group: ColorBooks

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbooks_colorbook_get(
    enumIGSpotColorVendorIDs vendorID,
    HIGCOLORBOOK *lphColorBook
);

Parameters:

vendorID
Vendor ID of the requested ColorBook.
lphColorBook
Obtained ColorBook object or NULL if no ColorBook found.

Description:

This method gets a ColorBook object with specified Vendor ID from the ColorBooks collection.


IG_colorbooks_count_get

Group: ColorBooks

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbooks_count_get(
    AT_UINT *lpnCount
);

Parameters:

lpnCount
Number of ColorBooks in the ColorBooks collection.

Description:

This method gets the number of ColorBooks in the ColorBooks collection.


IG_colorbooks_remove_colorbook

Group: ColorBooks

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbooks_remove_colorbook(
    enumIGSpotColorVendorIDs vendorID
);

Parameters:

vendorID
Vendor ID of ColorBook to remove.

Description:

This method removes ColorBook object with the specified Vendor ID from the ColorBooks collection.


IG_colorbooks_remove_colorbook_by_index

Group: ColorBooks

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbooks_remove_colorbook_by_index(
    AT_UINT nIndex
);

Parameters:

nIndex
Index of ColorBook to remove.

Description:

This method removes ColorBook object with the specified index from the ColorBooks collection.


IG_colorbooks_synonym_count_get

Group: ColorBooks

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbooks_synonym_count_get(
    enumIGSpotColorVendorIDs VendorID,
    AT_UINT *lpnCount
);

Parameters:

VendorID
Vendor ID to get the number of synonyms for
lpnCount
The number of synonyms for the specified Vendor ID.

Description:

This method gets the number of synonyms for the specified Vendor ID.


IG_colorbooks_ synonym_get

Group: ColorBooks

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbooks_synonym_get(
    enumIGSpotColorVendorIDs VendorID,
    AT_UINT nIndex,
    enumIGSpotColorVendorIDs *lpSynonymID
);

Parameters:

VendorID
Vendor ID to get a synonym for.
nIndex
Index of the synonym to get.
lpSynonymID
VendorID's synonym.

Description:

This method gets a synonym Vendor ID with the specified index for the specified Vendor ID.


IG_colorbookcolor_colorspace_get

Group: ColorBook Color
Declaration:
AT_ERRCOUNT ACCUAPI IG_colorbookcolor_colorspace_get(
    HIGCOLORBOOKCOLOR hColorBookColor,
    enumIGColorSpaceIDs *lpColorSpace
);

Parameters:

hColorBookColor
ColorBook Color.
lpColorSpace
Color space of the specified ColorBook Color.

Description:

This method gets color space of the specified ColorBook Color.


IG_colorbookcolor_colorvalue_copy_get

Group: ColorBook Color

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbookcolor_colorvalue_copy_get(
    HIGCOLORBOOKCOLOR hColorBookColor,
    HIGPIXEL *lphPixel
);

Parameters:

hColorBookColor
ColorBook Color.
lphPixel
Color value of the specified ColorBook Color.

Description:

This method gets a copy of color value of the specified ColorBook Color.


IG_colorbookcolor_create

Group: ColorBook Color

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbookcolor_create(
    LPCHAR lpName,
    AT_QWORD nColorID,
    HIGPIXEL lphPixel,
    enumIGColorSpaceIDs colorSpace,
    HIGCOLORBOOKCOLOR *lphColorBookColor
);

Parameters:

lpName
Name of new ColorBook Color,
nColorID
Color ID of new ColorBook Color,
lphPixel
Color value of new ColorBook Color,
colorSpace
Color space of new ColorBook Color,
lphColorBookColor
Created ColorBook Color.

Description:

This method creates new ColorBook Color object.


IG_colorbookcolor_id_get

Group: ColorBook Color

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbookcolor_id_get(
    HIGCOLORBOOKCOLOR hColorBookColor,
    AT_QWORD *lpID
);

Parameters:

hColorBookColor
ColorBook Color.
lpID
Color ID of the specified ColorBook Color.

Description:

This method gets Color ID of the specified ColorBook Color.


IG_colorbookcolor_name_get

Group: ColorBook Color

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorbookcolor_name_get(
    HIGCOLORBOOKCOLOR hColorBookColor,
    LPCHAR *lpName
);

Parameters:

hColorBookColor
ColorBook Color.
lpName
Name of the specified ColorBook Color.

Description:

This method gets name of the specified ColorBook Color.


IG_colorspace_conversion_apply_to_image

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorspace_conversion_apply_to_image(
    HIGCSCONVERTER hCSConverter,
    HIGEAR hIGear
);

Arguments:

hCSConverter
Handle of color space converter
hIGear
HIGEAR handle of image to apply conversion to

Description:

This function applies conversion to the entire image. Using this routine is similar to using IG_image_colorspace_convert ()function, but using the color space conversion engine allows you to manage the bit depths of the result channels.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Use the color space converter to convert an image
   to 24-bit RGB, no alpha or extra channels */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGCSCONVERTER hCSConv; /* Color space converter handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT depths[] = { 8, 8, 8 }; /* Result channel depths */
nErrcount = IG_colorspace_conversion_create_from_image(
    hImage, IG_COLOR_SPACE_ID_RGB, depths, 3, NULL, &hCSConv);
nErrcount = IG_colorspace_conversion_apply_to_image(
    hCSConv, hImage);
nErrcount = IG_colorspace_conversion_destroy(hCSConv);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_colorspace_conversion_apply_to_raster

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorspace_conversion_apply_to_raster(
    HIGCSCONVERTER hCSConverter,
    const void* sourceRaster,
    void* resultRaster,
    AT_INT rasterLength
);

Arguments:

hCSConverter
Handle of color space converter
sourceRaster
Raster to be converted
resultRaster
Raster to store conversion result
rasterLength
Number of PIXELS (not bytes!) in raster to convert

Description:

This function applies conversion to a single raster. resultRaster argument should be sufficient to store the converted pixels. If the result raster is run-ends, the store must be suitable to contain the most capacious case. rasterLength argument specifies the quantity of pixels (not bytes!) in the raster.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Use the color space converter to convert a CMYK raster
to 24-bit RGB.  Then fill a test image with it and save file. */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGCSCONVERTER hCSConv; /* Color space converter handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT depthsCMYK[] = { 8, 8, 8, 8 }; /* CMYK channel depths */
AT_INT depthsRGB[] = { 8, 8, 8 }; /* RGB channel depths */
HIGDIBINFO hDIBCMYK;    /* CMYK DIB info handle */
HIGDIBINFO hDIBRGB;     /* RGB DIB info handle */
AT_DIMENSION x, y, w = 64, h = 64; /* Test image dimensions */
AT_DIMENSION rasterSizeCMYK; /* CMYK raster size */
AT_DIMENSION rasterSizeRGB;  /* RGB raster size */
LPAT_PIXEL lpRasterCMYK;     /* CMYK raster data */
LPAT_PIXEL lpRasterRGB;      /* RGB raster data */
/* Create CMYK test raster (solid yellow) */
nErrcount = IG_DIB_info_create(&hDIBCMYK, w, h,
    IG_COLOR_SPACE_ID_CMYK, 4, depthsCMYK);
rasterSizeCMYK = IG_DIB_info_raster_size_get(hDIBCMYK);
lpRasterCMYK = (LPAT_PIXEL) calloc(rasterSizeCMYK, 1);
for (x = 0; x <= rasterSizeCMYK - 4; x += 4)
    lpRasterCMYK[x] = 255; /* Yellow */
/* Create RGB test image */
nErrcount = IG_DIB_info_create(&hDIBRGB, w, h,
    IG_COLOR_SPACE_ID_RGB, 3, depthsRGB);
rasterSizeRGB = IG_DIB_info_raster_size_get(hDIBRGB);
lpRasterRGB = (LPAT_PIXEL) malloc(rasterSizeRGB);
nErrcount = IG_image_create(hDIBRGB, &hImage);
/* Convert CMYK test raster to RGB raster */
nErrcount = IG_colorspace_conversion_create_from_dib_info(
    hDIBCMYK, IG_COLOR_SPACE_ID_RGB, depthsRGB, 3,
    NULL, &hCSConv);
nErrcount = IG_colorspace_conversion_apply_to_raster(
    hCSConv, lpRasterCMYK, lpRasterRGB, w);
nErrcount = IG_colorspace_conversion_destroy(hCSConv);
/* Fill test image with converted raster */
for (y = 0; y < h; y++)
    nErrcount = IG_DIB_raster_set(hImage, y, lpRasterRGB,
        IG_PIXEL_UNPACKED);
/* Save test image to a file and clean up */
nErrcount = IG_save_file(hImage, "test.bmp",
IG_SAVE_BMP_UNCOMP);
nErrcount = IG_DIB_info_delete(hDIBRGB);
nErrcount = IG_DIB_info_delete(hDIBCMYK);
nErrcount = IG_image_delete(hImage);
free(lpRasterCMYK);
free(lpRasterRGB);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_colorspace_conversion_create

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorspace_conversion_create(
    enumIGColorSpaceIDs sourceSpace,
    const AT_RGBQUAD* sourceSpaceAttribs,
    const AT_INT* sourceChannelDepths,
    AT_INT sourceChannelCount,
    enumIGColorSpaceIDs resultSpace,
    const AT_INT* resultChannelDepths,
    AT_INT resultChannelCount,
    LPCAT_COLORSPACE_CONVERSION_OPTIONS options,
    HIGCSCONVERTER* hCSConverter
);

Arguments:

sourceSpace
Color space to convert from
sourceSpaceAttribs
Source color space attributes
sourceChannelDepths
Array of channel depths for source color space
sourceChannelCount
Number of channels in source color space
resultSpace
Color space to convert to
resultChannelDepths
Array of channel depths in resulting color space
resultChannelCount
Number of channels in resulting color space
options
Conversion options
hCSConverter
Handle of color space converter

Description:

This function creates conversion engine based on the source and the result color space attributes. NULL is an acceptable value for resultChannelDepths. In this case the result channels will be constructed using IG_colorspace_conversion_result_channels_build () routine. Options controls the conversion flow. You may pass NULL for Options if you don't want to specify any options.

For the detailed information about AT_COLORSPACE_CONVERSION_OPTIONS structure and the whole color conversion process please refer to the section Working with Color Space Conversion Engine.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Use the color space converter to convert an image
   from CMYK to 24-bit RGB, no alpha or extra channels */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGCSCONVERTER hCSConv; /* Color space converter handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT depthsCMYK[] = { 8, 8, 8, 8 }; /* CMYK channel depths */
AT_INT depthsRGB[] = { 8, 8, 8 };     /* RGB channel depths */
nErrcount = IG_colorspace_conversion_create(
    IG_COLOR_SPACE_ID_CMYK, NULL, depthsCMYK, 4,
    IG_COLOR_SPACE_ID_RGB, depthsRGB, 3,
    NULL, &hCSConv);
nErrcount = IG_colorspace_conversion_apply_to_image(
    hCSConv, hImage);
nErrcount = IG_colorspace_conversion_destroy(hCSConv);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_colorspace_conversion_create_from_dib_info

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI
IG_colorspace_conversion_create_from_dib_info(
    HIGDIBINFO hDIB,
    enumIGColorSpaceIDs resultSpace,
    const AT_INT* resultChannelDepths,
    AT_INT resultChannelCount,
    LPCAT_COLORSPACE_CONVERSION_OPTIONS options,
    HIGCSCONVERTER* hCSConverter
);

Arguments:

hDIB
DIB info handle, describes source color space
resultSpace
Color space to convert to
resultChannelDepths
Array of channel depths in resulting color space
resultChannelCount
Number of channels in resulting color space
options
Conversion options
hCSConverter
Handle of color space converter

Description:

This function creates conversion engine based on source and result color space attributes. NULL is an acceptable value for resultChannelDepths. In this case the result channels will be constructed using IG_colorspace_conversion_result_channels_build () routine. The source color space attributes are taken from the specified DIB information handle. Options controls the conversion flow. You may pass NULL for Options if you don't want to specify any options.

For the detailed information about AT_COLORSPACE_CONVERSION_OPTIONS structure and the whole color conversion process please refer to the section Working with Color Space Conversion Engine.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Use the color space converter to convert an image
from CMYK to 24-bit RGB, no alpha or extra channels */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGCSCONVERTER hCSConv; /* Color space converter handle */
HIGEAR hImage;          /* HIGEAR handle of image */
HIGDIBINFO hDIB;        /* Source DIB info handle */
AT_INT depths[] = { 8, 8, 8 }; /* Result channel depths */
nErrcount = IG_image_DIB_info_get(hImage, &hDIB);
nErrcount = IG_colorspace_conversion_create_from_dib_info(
    hDIB, IG_COLOR_SPACE_ID_RGB, depths, 3, NULL, &hCSConv);
nErrcount = IG_colorspace_conversion_apply_to_image(
    hCSConv, hImage);
nErrcount = IG_colorspace_conversion_destroy(hCSConv);
nErrcount = IG_DIB_info_delete(hDIB);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_colorspace_conversion_create_from_image

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorspace_conversion_create_from_image(
    HIGEAR hIGear,
    enumIGColorSpaceIDs resultSpace,
    const AT_INT* resultChannelDepths,
    AT_INT resultChannelCount,
    LPCAT_COLORSPACE_CONVERSION_OPTIONS options,
    HIGCSCONVERTER* hCSConverter
);

Arguments:

hIGear
HIGEAR handle of image
resultSpace
Color space to convert to
resultChannelDepths
Array of channel depths in resulting color space
resultChannelCount
Number of channels in resulting color space
options
Conversion options
hCSConverter
Handle of color space converter

Description:

This function creates conversion engine based on source and result color space attributes. NULL is an acceptable value for resultChannelDepths. In this case the result channels will be constructed using IG_colorspace_conversion_result_channels_build () routine. The color space attributes are taken from specified hIGear instance. Options controls the conversion flow. You may pass NULL for Options if you don't want to specify any options.

For the detailed information about AT_COLORSPACE_CONVERSION_OPTIONS structure and the whole color conversion process please refer to the section Working with Color Space Conversion Engine.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Use the color space converter to convert an image
   to 24-bit RGB, no alpha or extra channels */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGCSCONVERTER hCSConv; /* Color space converter handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT depths[] = { 8, 8, 8 }; /* Result channel depths */
nErrcount = IG_colorspace_conversion_create_from_image(
    hImage, IG_COLOR_SPACE_ID_RGB, depths, 3, NULL, &hCSConv);
nErrcount = IG_colorspace_conversion_apply_to_image(
    hCSConv, hImage);
nErrcount = IG_colorspace_conversion_destroy(hCSConv);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_colorspace_conversion_create_from_matrix

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI
IG_colorspace_conversion_create_from_matrix(
    enumIGColorSpaceIDs sourceSpace,
    const AT_INT* sourceChannelDepths,
    AT_INT sourceChannelCount,
    enumIGColorSpaceIDs resultSpace,
    const AT_INT* resultChannelDepths,
    AT_INT resultChannelCount,
    HIGDoubleMatrix conversionMatrix,
    LPCAT_COLORSPACE_CONVERSION_OPTIONS options,
    HIGCSCONVERTER* hCSConverter
);

Parameters:

sourceChannelDepths
Array of channel depths for source color space
sourceChannelCount
Number of channels in source color space
resultSpace
Color space to convert to
resultChannelDepths
Array of channel depths in resulting color space
conversionMatrix
Conversion matrix
options
Reserved for future use
hCSConverter
Returns the handle of color space converter

Description:

Converts image to new colorspace using a conversion matrix. Destination pixels are calculated as Dst = M * Src, where M is conversion matrix. Number of channels after conversion will be equal to first dimension of the conversionMatrix. Second dimension of conversionMatrix should be equal to number of channels in the source image.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_colorspace_conversion_destroy

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorspace_conversion_destroy(
    HIGCSCONVERTER hCSConverter
);

Arguments:

hCSConverter
Handle of color space converter

Description:

This function destroys an instance of the color space conversion engine.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Use the color space converter to convert an image
   to 24-bit RGB, no alpha or extra channels */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGCSCONVERTER hCSConv; /* Color space converter handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT depths[] = { 8, 8, 8 }; /* Result channel depths */
nErrcount = IG_colorspace_conversion_create_from_image(
    hImage, IG_COLOR_SPACE_ID_RGB, depths, 3, NULL, &hCSConv);
nErrcount = IG_colorspace_conversion_apply_to_image(
    hCSConv, hImage);
nErrcount = IG_colorspace_conversion_destroy(hCSConv);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_colorspace_conversion_is_applicable

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_colorspace_conversion_is_applicable(
    enumIGColorSpaceIDs sourceSpace,
    const AT_INT* sourceChannelDepths,
    AT_INT sourceChannelCount,
    enumIGColorSpaceIDs resultSpace,
    LPCAT_COLORSPACE_CONVERSION_OPTIONS options,
    AT_BOOL* applicable
);

Arguments:

sourceSpace
Color space to convert from
sourceChannelDepths
Array of channel depths for source color space
sourceChannelCount
Number of channels in source color space
resultSpace
Color space to convert to
options
Conversion options
applicable
This gets set to TRUE if conversion is possible, otherwise FALSE

Description:

This function checks whether conversion is possible for the given combination of source and result color spaces. In general, conversion cannot be constructed only if: 1) the result color space is indexed and 2) the source color space is something other than indexed or grayscale (8bpp or less). Options controls the conversion flow. You may pass NULL for Options if you don't want to specify any options.

For the detailed information about AT_COLORSPACE_CONVERSION_OPTIONS structure and the whole color conversion process please refer to the section Working with Color Space Conversion Engine.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Can we convert from 48-bit RGB to CMYK? */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
AT_INT depths[] = { 16, 16, 16 }; /* Channel depths */
AT_BOOL bApplicable;    /* Is conversion applicable? */
nErrcount = IG_colorspace_conversion_is_applicable(
    IG_COLOR_SPACE_ID_RGB, depths, 3,
    IG_COLOR_SPACE_ID_CMYK, NULL, &bApplicable);
/* bApplicable is TRUE */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_colorspace_conversion_result_channels_build

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI
IG_colorspace_conversion_result_channels_build(
    enumIGColorSpaceIDs sourceSpace,
    const AT_INT* sourceChannelDepths,
    AT_INT sourceChannelCount,
    enumIGColorSpaceIDs resultSpace,
    AT_INT* resultChannelDepths,
    AT_INT* resultChannelCount,
    LPCAT_COLORSPACE_CONVERSION_OPTIONS options
);

Arguments:

sourceSpace
Color space to convert from
sourceChannelDepths
Array of channel depths for source color space
sourceChannelCount
Number of channels in source color space
resultSpace
Color space to convert to
resultChannelDepths
Array of channel depths in resulting color space
resultChannelCount
Number of channels in resulting color space
options
Conversion options

Description:

This function builds the channels structure for the specified conversion. It fills resultChannelDepths with the calculated depths. resultChannelCount contains the quantity of channels in the result raster. Options controls the conversion flow. You may pass NULL for Options if you don't want to specify any options.

For the detailed information about AT_COLORSPACE_CONVERSION_OPTIONS structure and the whole color conversion process please refer to the section Working with Color Space Conversion Engine.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Calculate output channel depths for RGB to CMYK */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
AT_INT depthsIn[] = { 8, 8, 8 }; /* Channel depths */
AT_INT depthsOut[4]; /* Output channel depths */
AT_INT nDepthsOut = 4; /* Number of output channel depths */
nErrcount = IG_colorspace_conversion_result_channels_build(
    IG_COLOR_SPACE_ID_RGB, depthsIn, 3,
    IG_COLOR_SPACE_ID_CMYK, depthsOut, &nDepthsOut, NULL);
/* depthsOut[] is { 8, 8, 8, 8 } */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_colorspace_conversion_result_palette_get

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI
IG_colorspace_conversion_result_palette_get(
    HIGCSCONVERTER hCSConverter,
    AT_RGBQUAD* palette,
    AT_INT* paletteLength
);

Arguments:

hCSConverter
Handle of color space converter
palette
Array of palette entries
paletteLength
Number of palette entries

Description:

This function builds the result palette. if the result colorspace is indexed, paletteLength will be filled with the quantity of palette entries.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Use the color space converter to convert an image
to 8-bit indexed, no alpha or extra channels */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGCSCONVERTER hCSConv; /* Color space converter handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT depths[] = {8};  /* Result channel depths */
AT_RGBQUAD pal[256];    /* Result palette */
AT_INT nEntries;        /* # of palette entries */
nErrcount = IG_colorspace_conversion_create_from_image(
    hImage, IG_COLOR_SPACE_ID_I, depths, 1, NULL, &hCSConv);
nErrcount = IG_colorspace_conversion_apply_to_image(
    hCSConv, hImage);
nErrcount = IG_colorspace_conversion_result_palette_get(
    hCSConv, pal, &nEntries);
nErrcount = IG_colorspace_conversion_destroy(hCSConv);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_color_space_level_get

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_color_space_level_get(
    AT_MODE nColorSpaceID,
    LPAT_MODE lpnSupportLevel
);

Arguments:

nColorSpaceID
Set this to an AT_MODE constant for the type of color space you would like to get the support level setting of. The names of the appropriate constants begin with IG_COLOR_SPACE_ prefix.
lpnSupportLevel
A far pointer that returns the current setting level for the color space specified in the first argument. See IG_color_space_level_set ().

Description:

This function queries the current option level setting for the color space that you specify. You must supply nColorSpaceID with a constant of type AT_MODE from accucnst.h that specifies the color space you wish to query. The second argument will return an ImageGear constant that tells you the current option level setting for the color space.

NOTE: ImageGear fully supports the loading and saving of TIFF-CMYK images. A CMYK image will only be converted to RGB for the purpose of display. CMYK is a color scheme designed for printing and cannot be used for screen display.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: For more details see the description for IG_color_space_level_set() and the section Working With Color Space Options.

Example:

AT_ERRCOUNT 			nErrcount;
HIGEAR			hIGear;
AT_MODE			nSupportLevel;
nErrcount = IG_color_space_level_get(IG_COLOR_SPACE_CMYK,
&nSupporLevel);

Sample: COLOR

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_color_space_level_set

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_color_space_level_set(
    AT_MODE nColorSpaceID,
    AT_MODE nSupportLevel
);

Arguments:

nColorSpaceID
Set this to an AT_MODE constant for the type of color space you would like to set the support level setting for. For example: IG_COLOR_SPACE_CMYK.
nSupportLevel
Set this to an AT_MODE constant for level of support for the color space specified in the first argument. For CMYK support, the possible settings are IG_CONVERT_TO_RGB or IG_FULL_SUPPORT.

Description:

This function allows you to set the option level setting for the color space that you specify. You must supply nColorSpaceID with a constant of type AT_MODE from accucnst.h that specifies the color space you wish to query, and nSupportLevel with a constant of type AT_MODE that specifies the level of support you would like your application to provide.

The CMYK color space is supported using the following settings:

IG_CONVERT_TO_RGB
Loads a CMYK image and converts it to RGB.
IG_FULL_SUPPORT
Full support for loading and saving CMYK images.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: ImageGear fully supports the loading and saving of CMYK images. A CMYK image will only be converted to RGB for the purpose of display. CMYK is a color scheme designed for printing and cannot be used for screen display.
NOTE: For more details see the section Working With Color Space Options Using ImageGear.

Example:

AT_ERRCOUNT  	nErrcount;
HIGEAR 	hIGear;
nErrcount= IG_color_space_level_set(IG_COLOR_SPACE_CMYK,
IG_COLOR_FULL_SUPPORT);

Sample: COLOR

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_color_temperature_convert_to_XY

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_color_temperature_convert_to_xy(
    const AT_COLOR_TEMPERATURE *lpColorTemperature
    AT_DPOINT *lpWhiteXY,
);

Parameters:

lpColorTemperature
Color temperature structure
lpWhiteXY
Coordinates of a white point to be calculated

Description:

Converts color temperature structure to XY coordinates of the corresponding white point.

Setting a greater temperature for an image results in more yellow color, lower temperature results in more blue color. Useful range for Temperature is between 2000 and 10000.

Setting a greater tint value for an image results in a more magenta color, lower tint values result in greener color. Useful range for Tint is between -50 and 50.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_color_temperature_initialize_from_preset

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI
IG_color_temperature_initialize_from_preset(
    enumIGWhiteBalancePreset PresetValue,
    AT_COLOR_TEMPERATURE *lpColorTemperature
);

Parameters:

PresetValue
Preset white balance identifier
ColorTemperature
Color temperature structure to be initialized

Description:

Initializes color temperature structure from a preset value, such as Daylight, Tungsten, etc.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_color_temperature_initialize_from_XY

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_color_temperature_initialize_from_XY(
    const AT_DPOINT *lpWhiteXY,
    AT_COLOR_TEMPERATURE *lpColorTemperature
);

Parameters:

lpWhiteXY
Coordinates of a white point
lpColorTemperature
Color temperature structure to be initialized

Description:

Initializes color temperature structure from XY coordinates of white point.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_comm_comp_attach

Group: Component Manager

Declaration:

AT_ERRCODE  LACCUAPI IG_comm_comp_attach (
    LPCHAR lpCompName
);

Arguments:

lpCompName
The Name of IG Component to be linked with main IG module.

Description:

This function allows you to attach ImageGear component defined by lpCompName to the main ImageGear module. By default, ImageGear searches for components in the same directory where main ImageGear module is located but it is possible to specify exact path and filename to given module name of component using global parameters api function IG_gctrl_item_set () and setting parameter "COMM.<COMP_NAME>" to full path of component.

See also the section Using ImageGear Component Manager.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

...
#include "i_ART.h"
...
/*  Initialize ART component   */
IG_comm_comp_attach( "ART" );
...

Sample: ART, BAR, Vector, Filter, FPX, IC, Medical, MFC, MULTIMED,

Recognition, Scan, IGDemo (Delphi)

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_comm_comp_check

Group: Component Manager

Declaration:

AT_BOOL    ACCUAPI IG_comm_comp_check(
    LPCHAR lpCompName
);

Arguments:

lpCompName
The Name of IG Component attached to the main IG module.

Description:

This function allows you to check if ImageGear component defined by lpCompName argument is currently attached or not. If component is attached it returns TRUE, if not - FALSE.

See also the section Using ImageGear Component Manager

Bits Per Pixel: N/A

Return Value:

TRUE - if component is attached successfully. FALSE - if not.

Example:

bFoundLZW = IG_comm_comp_check("LZW");
if( bFoundLZW )
{
EnableMenuItem( GetMenu( hWnd ), ID_FILE_SAVE_INTERLIVED,
MF_ENABLED|MF_BYCOMMAND );
EnableMenuItem( GetMenu( hWnd ), ID_FILE_SAVE_NONINTERLIVED,
MF_ENABLED|MF_BYCOMMAND );
IG_fltr_ctrl_get(IG_FORMAT_GIF, "INTERLACE", FALSE, NULL, NULL,
(LPVOID)&bInterlaced, sizeof(&bInterlaced));
CheckMenuItem(GetMenu(hWnd), ID_FILE_SAVE_INTERLIVED,
MF_BYCOMMAND | bInterlaced?MF_CHECKED:MF_UNCHECKED);
CheckMenuItem(GetMenu(hWnd), ID_FILE_SAVE_NONINTERLIVED,
MF_BYCOMMAND | bInterlaced?MF_UNCHECKED:MF_CHECKED);
}else
{
EnableMenuItem( GetMenu( hWnd ), ID_FILE_SAVE_INTERLIVED,
MF_GRAYED|MF_BYCOMMAND );
EnableMenuItem( GetMenu( hWnd ), ID_FILE_SAVE_NONINTERLIVED,
MF_GRAYED|MF_BYCOMMAND );
}

Sample: FILTER, MULTIMED, GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_comm_comp_list

Group: Component Manager

Declaration:

AT_ERRCODE  ACCUAPI  IG_comm_comp_list(
    LPUINT *lpnCount,
    UINT nIndex,
    LPCHAR lpComp,
    DWORD dwCompSize,
    LPUINT lpnRevMajor,
    LPUINT lpnRevMinor,
    LPUINT lpnRevUpdate,
    LPCHAR lpBuildDate,
    UINT nBDSize,
    LPCHAR lpInfoStr,
    UINT nISSize
);

Arguments:

lpnCount
OUT: The number of attached components
nIndex
IN: The index of component from the list
lpComp
OUT: The buffer where to return the name of component specified by nIndex index
dwCompSize
IN: The size of lpBuffer in bytes
lpnRevMajor
Far pointer to an INT variable in which will be stored the Major version number of the version of the Component specified by nIndex.
lpnRevMinor
Far pointer to an INT variable in which will be stored the Minor version number of the version of the Component specified by nIndex.
lpnRevUpdate
Far pointer to an INT variable in which will be stored the Update (bug fix) number, reflecting any updates you have received and installed in this version of the Component specified by nIndex.
lpBuildDate
The buffer where to return the build date of the current version of the Component specified by nIndex. The return value is a string in the format "Mmm dd yyyy", such as "Jul 04 2002."
nBDSize
The size of buffer where lpBuildDate is returned.
lpInfoStr
The buffer where to return the info string about the Component specified by nIndex.
nISSize
The size of buffer where lpInfoStr is returned.

Description:

This function allows to obtain information about currently loaded components. First argument returns actual number of attached components. nIndex specifies the index of the component in the components list which name is copied into lpBuffer. The rest of parameters return information about component specified by nIndex.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_comm_entry_request

Group: Component Manager

Declaration:

AT_ERRCODE  ACCUAPI  IG_comm_entry_request(
    LPCHAR lpEntryName,
    LPAFT_ANY *lpFuncPtr,
    LPCHAR lpReason
);

Arguments:

lpEntryName
The full name of entry "<Comp_name>.<Func_name>", where <Comp_name> is a component name where function is exported and <Func_name> is a name of function.
lpFuncPtr
Pointer where to return pointer to requested function.
lpReason
Optional parameter to specify string description of the reason for this request.

Description:

This function is used to get pointer to the function from component with given name. Usually it is used with component public header i_<COMP_NAME>.h where actual type of function is declared.

See also the section Using ImageGear Component Manager

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_comm_function_call

Group: Component Manager

Declaration:

LONG  CACCUAPI   IG_comm_function_call(
    LPCHAR lpEntryName,
    ...
);

Arguments:

lpEntryName
The name of entry in GFT to call
...
additonal parameters

Description:

This function is used to call function from component. Usually it is not used directly but it is used in macro declarations defined in component public headers i_<COMP_NAME>.h.

See also the section Using ImageGear Component Manager

Bits Per Pixel: N/A

Return Value:

Returns a LONG indicating the requested component function.

Example:

See example in "Component Manager API" sectionUsing ImageGear.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_convert_DPI_to_PPM

Group: Image Utility

Declaration:

LONG ACCUAPI IG_convert_DPI_to_PPM(
    LONG lDotsPerInch
);

Arguments:

lDotsPerInch
A variable of type LONG, holding the dpi value that can be converted to pels per meter.

Description:

Converts Dots Per Inch (DPI) to Pels Per Meter (PPM). "Pels" is an abbreviated term for pixels. This function can be useful when you are converting a file that supports dots per inch to a DIB format, which supports pels per meter. The header structure of a DIB (the BIMAPINFOHEADER) contains two fields whose values are defined in "pels per meter": LONG biXPelsPerMeter and LONG biYPelsPerMeter.

Bits Per Pixel: Not applicable

Return Value:

Returns a LONG indicating the pels per meter of an image.

Example:

LONG	 IPpm, IDpi;
...
IPpm=IG_convert_DPI_to_PPM(IPpi);
...

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_convert_PPM_to_DPI

Group: Image Utility

Declaration:

LONG ACCUAPI IG_convert_PPM_to_DPI(
    LONG lPelsPerMeter
);

Arguments:

lPelsPerMeter
A variable of type LONG, holding the pels per meter value that can be converted to dots per inch.

Description:

Converts Pels Per Meter (PPM) to Dots Per Inch (DPI). "Pels" is an abbreviated term for pixels. This function can be useful when you are converting a DIB to a format that supports dots per inch. The header structure of a DIB (the BIMAPINFOHEADER) contains two fields whose values are defined in "pels per meter": LONG biXPelsPerMeter and LONG biYPelsPerMeter.

Bits Per Pixel: Not applicable

Return Value:

Returns a LONG indicating the DPI of an image.

Example:

LONG	 IPpm, IDpi;
...
IPpm=IG_convert_PPM_to_DPI(IPpm);
...

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_cpm_image_embedded_profile_check

Group: Color Profile

Declaration:

AT_ERRCODE ACCUAPI IG_cpm_image_embedded_profile_check(
    HIGEAR hIGear,
    LPAT_BOOL lpbEmbedded
);

Arguments:

hIGear
(in) A handle of the image to check.
lpbEmbedded
(out) Return TRUE if profile embedded, otherwise, FALSE.

Description:

This function checks to see whether the image has embedded color profile.

Bits Per Pixel:

All

Return Value:

Return value is a code of last error or NULL if success.

Example:

HIGEAR hIGear;  /* Handle of the image to check*/
AT_BOOL bEmbeddedProfile = FALSE;	/* Flag to return whether
profile embedded or not */
/* Load an image into hIGear */
......
/* Check whether the image has embedded profile. */
if (IGE_SUCCESS == IG_cpm_image_embedded_profile_check(hIGear,
&bEmbeddedProfile))
{
......
}

Sample:

GUI


IG_cpm_image_profile_get

Group: Color Profile

Declaration:

AT_ERRCODE LACCUAPI IG_cpm_image_profile_get(
    HIGEAR hIGear,
    LPAT_BOOL lpbIsLocal,
    LPAT_MODE lpnColorSpace,
    LPCHAR lpStatusStr,
    UINT nStatusSize
    LPUINT lpnStatusLen,
    LPDWORD lpnProfileSize
    LPBYTE lpProfileData,
    DWORD dwProfileDataSize
);

Arguments:

hIGear
IN: handle of image where to set profile.
lpbIsLocal
OUT: return TRUE if local profile associated with given image and FALSE in other case. If NULL then argument ignored.
lpnColorSpace
OUT: color space id of returned profile. Possible returned values:
IG_COLOR_SPACE_RGB
IG_COLOR_SPACE_CMYK
If NULL then parameter ignored.
lpStatusStr
OUT: pointer where to copy textual information about local profile.
If NULL then parameter ignored.
nStatusSize
IN: size of lpStatusStr buffer.
lpnStatusLen
OUT: Return length of actual status message. If NULL then parameter ignored.
lpnProfileSize
OUT: If not NULL then returns actual profile size in ICC format.
lpProfileData
OUT: Pointer where to put profile data. Profile will be written according to ICC.1:1998-09 specification.
dwProfileDataSize
IN: the size of lpProfileData buffer.

Description:

This function returns information about color profile associated with given image. Second parameter is used to get information either this image has embedded local profile or use global profile.

The rest of parameters are used to provide text description of profile and profile data iteslf. The profile returned through lpProfileData will be written according to ICC specification.

Depending from parameters it either return information about profile or profile data itself. For example, if lpnProfileSize is not NULL then the size of profile is calculated and returned. If lpProfileData is not NULL then profile is encoded into standard ICC format and returned through this parameter.

Please note that color profile management is disabled by default. See section Working with ImageGear Color Profile Manager for descirption how to activate it.

Bits Per Pixel: ALL

Return Value:

Return value is a code of last error or NULL if success.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_cpm_image_profile_set

Group: Color Profile

Declaration:

AT_ERRCODE LACCUAPI IG_cpm_image_profile_set(
    HIGEAR hIGear,
    LPAT_BYTE lpRawData,
    DWORD dwRawSize,
    AT_BOOL bConvert
);

Arguments:

hIGear
IN: handle of image where to set profile.
lpRawData
IN: raw data of new profile. Can be either NULL or pointer to memory buffer that contains valid color profile in format specified by ICC.1:1998-09.
dwRawSize
IN: lenth of data stored in lpRawData.
bConvert
IN: if TRUE then convert all images associated with old profile to new profile, but if FALSE then simple replace profile without any conversion.

Description:

This function provides color profile management for given particular image. There can be two ways how an image is associated with color profile:

  • First way: image itself does not store color profile data but use profile from global parameters (WCP).
  • Second way: image stores color profile locally and does not depend on global settings.

If lpRawData is NULL during this function call, then previous local profile (if it existed) is deleted and image become dependent on global profile correspondent to color space used by its pixel data. If lpRawData is valid ICC profile then previous local profile (if it existed) is deleted and image becomes associated with new local profile.

The last parameter specifies how pixel data should be changed during profile change operation. If bConvert is TRUE, then pixel is converted from one format to another but in other case pixel data is unchanged.

Please note, that color profile management is disabled by default. See section Working with ImageGear Color Profile Manager for descirption how to activate it.

If some error happens such as invalid or unsupported profile or color space mismatch in image and color profile, then function returns appropriate error code.

Bits Per Pixel: ALL

Return Value:

Return value is a code of last error or NULL if success.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_cpm_profile_get

Group: Color Profile

Declaration:

AT_ERRCODE LACCUAPI IG_cpm_profile_get(
    AT_MODE nColorSpace,
    DWORD nProfileGroup,
    LPCHAR lpStatusStr,
    UINT nStatusSize
    LPUINT lpnStatusLen,
    LPDWORD lpnProfileSize,
    LPBYTE lpProfileData,
    DWORD dwProfileDataSize
);

Arguments:

nColorSpace
IN: color space ID which profile status to get. Possible value:
IG_COLOR_SPACE_RGB
IG_COLOR_SPACE_CMYK
nProfileGroup
IN: color profile group where profiles to get. Possible value:
IG_CP_GRP_DISPLAY
IG_CP_GRP_WORKING
IG_CP_GRP_EXPORT
IG_CP_GRP_IMPORT
lpStatusStr
OUT: pointer where to copy textual information about local profile. If NULL then parameter is ignored.
nStatusSize
IN: size of lpStatusStr buffer.
lpnStatusLen
OUT: return length of actual status message. If NULL then parameter ignored.
lpnProfileSize
OUT: If this parameter is not NULL then actual size of color profile in ICC format is returned.
lpProfileData
OUT: Pointer where to put profile data or ignored if parameter is NULL. Profile will be written according to ICC.1:1998-09 specification.
dwProfileDataSize
IN: the size of lpProfileData

Description:

This function returns information about global profile for given color space of given group. Depending from parameters it either returns information about profile or profile data itself. For example, if lpnProfileSize is not NULL, then size of profile is calculated and returned. If lpProfileData is not NULL, then profile is encoded into standard ICC format and returned through this parameter.

Please note that color profile management is disabled by default. See section Working with ImageGear Color Profile Manager for descirption how to activate it.

Bits Per Pixel: ALL

Return Value:

Return value is a code of last error or 0 if success.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_cpm_profile_set

Group: Color Profile

Declaration:

AT_ERRCODE LACCUAPI IG_cpm_profile_set(
    AT_MODE nColorSpace,
    DWORD nProfileGroup
    LPAT_BYTE lpRawData,
    DWORD dwRawSize,
    AT_BOOL bConvert
);

Arguments:

nColorSpace
IN: color space ID which profile to replace. Current supported values:
IG_COLOR_SPACE_RGB
IG_COLOR_SPACE_CMYK
nProfileGroup
IN: color profile group where to set profile. Possible values:
IG_CP_GRP_WORKING
IG_CP_GRP_IMPORT
IG_CP_GRP_EXPORT
IG_CP_GRP_DISPLAY
lpRawData
IN: raw data of new profile. Can be either NULL or pointer to memory buffer that contains valid color profile in format specified by ICC.1:1998-09.
dwRawSize
IN: lenth of data stored in lpRawData.
bConvert
IN: if TRUE then this function converts all images associated with old profile to new profile, but if FALSE it simply replaces profile without any conversion

Description:

This function sets new value of color profile associated with color space given by nColorSpace parameter to profile group given by nProfileGroup parameter. If last parameter is set to TRUE then all associated images with previous format are converted to new color profile. In the case if nColorSpace does not match the same color space that is used in color profile or color profile is in invalid or unsupported format, then error is returned.

Please note that color profile management is disabled by default. See section Working with ImageGear Color Profile Manager for descirption how to activate it.

Bits Per Pixel: All

Return Value:

Return value is a code of last error or 0 if success.

Sample: Color

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_cpm_profiles_reset

Group: Color Profile

Declaration:

AT_ERRCODE LACCUAPI IG_cpm_profiles_reset(
    AT_BOOL bConvert
);

Arguments:

bConvert
IN: specify how this operation should affect associated image.

Description:

This function resets all default color profiles to default values taken from global parameters. If value of parameter is TRUE then it converts all images associated with all global profiles to default profiles, but if FALSE then all global profiles are reset to default values but images are not changed.

Please note that color profile management is disabled by default. See section Working with ImageGear Color Profile Manager for descirption how to activate it.

Bits Per Pixel: ALL

Return Value:

Return value is a code of last error or 0 if success.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_area_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_area_get (HIGEAR hIGear,
    const LPAT_RECT lpRect,
    LPAT_PIXEL lpPixel,
    AT_MODE nPixelFormat
);

Arguments:

hIGear
hIGear handle of an image.
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image bitmap to get
lpPixel
Far pointer to first in an array of bytes large enough to receive all pixels in the area
nPixelFormat
A constant such as IG_DIB_AREA_UNPACKED, specifying in what form you want the pixels stored in your array. The list of IG_DIB_AREA_ constants available is in file accucnst.h.

Description:

This function obtains all the pixels contained within the rectangular portion of image hIGear specified by lpRect. Use argument lpPixel to tell ImageGear where to store the pixels.

NOTE: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.

Use nPixelFormat = IG_DIB_AREA_DIB if you want the data in standard uncompressed DIB format, and with each row returned to you padded to a multiple of 4 bytes length. 1-bit pixels are returned 8 to the byte, most significant bit first. 4-bit pixels are returned 2 to the byte, similarly left justified. 24-bit pixels are returned 3 bytes per pixel, ordered Blue-Green-Red.

Use nPixelFormat = IG_DIB_AREA_UNPACKED if you want the pixels returned 1 per byte (but still 3 bytes for a 24-bit pixel, ordered Blue-Green-Red). Each 1-bit or 4-bit pixel will be returned right justified in a single byte, padded with zeroes in the most significant bits of the byte.

In either case, be sure your area pointed to by lpPixel is large enough to receive all the pixel data including padding.

NOTE: See also function IG_DIB_area_set().

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR         hIGear;       /* HIGEAR handle of image  */
AT_RECT        rcBlock;      /* The rectangular block to get  */
AT_PIXEL       cPixArray[400];/* Will receive returned pixels
*/
AT_DIMENSION   nWid, nHi;     /* Will receive width, height of
image     */
UINT           nBpp;          /* Bits per pixel  */
AT_ERRCOUNT   nErrcount;   /* Will receive returned error counts
*/
/* Will fetch upper left 20 x 20 pixels, to cPixArray[]:   */
rcBlock.top = rcBlock.left = 0;
rcBlock.bottom = rcBlock.right = 20;  /* 20x20 area, 400 pixels
*/
nErrcount = IG_image_dimensions_get ( hIGear, &nWid, &nHi, &nBpp
);  */
if ( nErrcount == 0 )      /* If valid image, dimensions
obtained'    */
    {
    if ( (nBpp <= 8) && (nWid >= 20) && (nHi >= 20) )
        {/* (Array is too small for 24-bit)					*/
        nErrcount = IG_DIB_area_get ( hIGear, &rcBlock,
            &cPixelArray[0], IG_DIB_AREA_UNPACKED );
        }
    }

Sample: PIXACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_area_set

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_area_set (HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const LPAT_PIXEL lpPixel,
    AT_MODE nPixelFormat
);

Arguments:

hIGear
ImageGear HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image bitmap to set
lpPixel
Far pointer to first byte of your pixel data
nPixelFormat
A constant such as IG_DIB_AREA_UNPACKED specifying in what form you are providing the pixels. The IG_DIB_AREA_... constants are listed in file accucnst.h.

Description:

This function transfers pixels from the location pointed to by lpPixel into the rectangular portion of the image specified by rectangle lpRect.

NOTE: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.
  • Use nPixelFormat = IG_DIB_AREA_DIB if you are providing the pixels in standard uncompressed DIB format. This means 1-bit or 4-bit pixels will be packed 8 to the byte or 2 to the byte respectively, left justified (first pixel uses most significant bit). 24-bit pixels are in 3 bytes, ordered Blue-Green-Red.
  • Use nPixelFormat = IG_DIB_AREA_UNPACKED if you are providing the pixels 1 pixel per byte (however, 3 bytes for a 24-bit pixel, ordered Blue-Green-Red). In this case, you provide 1-bit and 4-bit pixels one to a byte, right justified in the byte.
NOTE: See also function IG_DIB_area_get().

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR          hIGear;        /* HIGEAR handle of image */
AT_RECT         rcBlock;       /* The rectangular block to set
*/
AT_PIXEL        cPixelArray[400];    /* The pixels to set */
AT_DIMENSION    nWid, nHi;     /* Receives the width & height of
an image */
UINT            nBpp;          /* Bits per pixel   */
AT_ERRCOUNT     nErrcount;      /* Receives the returned error
counts  */
/* Sets the upper left 20 x 20 pixels, to cPixArray[]:
*/
rcBlock.top = rcBlock.left = 0;
rcBlock.bottom = rcBlock.right = 20;  /* 20x20 area, 400 pixels
*/
nErrcount = IG_image_dimensions_get ( hIGear, &nWid, &nHi, &nBpp
);  */
if ( nErrcount == 0 )      /* If valid image, dimensions
obtained:  */
    {
    if ( (nBpp <= 8) && (nWid >= 20) && (nHi >= 20) )
{
/*Array is too small for 24-bit)     */
    INT           row, col; pix;     /* For the loops below  */
    AT_PIXEL      nPixval;          /* pixel value to set  */
    if (nBpp == 8) nPixval = 128;   /* Value to set if 8-bit   */
    if (nBpp == 4) nPixval = 8;     /* Value to set if 4-bit   */
    if (nBpp == 1) nPixval = 1;     /* Pixel ON if 1-bit    */
        for ( pix=0,row=0; row<20; row++ ) /* For all pixels in
*/
            for ( col=0; col<20; col++ )/* the 20 x 20 array:  */
                cPixelArray[pix++] = nPixval;
                /* Set unpacked in byte    */
        nErrcount = IG_DIB_area_set ( hIGear, &rcBlock,
&cPixelArray[0], IG_DIB_AREA_UNPACKED );
}
    }

Sample: PIXACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_area_size_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_area_size_get(HIGEAR hIGear,
    LPAT_RECT lpRect,
    AT_MODE nFormat,
    LPAT_DIMENSION lpSize
);

Arguments:

hIGear
HIGEAR handle of image.
lpRect
A far pointer to a rectangular array of pixels from the image. Setting this to NULL selects the whole image.
nFormat
A variable of type AT_MODE, such as IG_DIB_AREA_DIB, that defines how the data should be stored: packed or unpacked. (They are defined in accucnst.h)
lpSize
A far pointer to a variable that returns the size in bytes of the array of pixels.

Description:

This function calculates and returns the number of bytes required to hold a rectangular region selected from an image. You can use this function to determine the size of the block of memory to allocate to hold the pixel values from the rectangular region. This will help you to avoid data overflow. The value returned by lpSize includes the allocation of space for raster buffering at the end of each raster line. (See the section Device-Independent Bitmaps (DIB) Understanding Bitmap Images.)

Use the format parameter to indicate the form in which you want to store the pixels:

Use:
To:
IG_DIB_AREA_DIB
pad rows to long boundaries (the way they are stored in a DIB).
IG_DIB_AREA_UNPACKED
store pixels 1 per byte for 1, 4, 8-bit images, 1 per 3 bytes for a 24-bit image

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.

Sample: PIXACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_bit_depth_get

Group: DIB Info Services

Declaration:

AT_INT ACCUAPI IG_DIB_bit_depth_get(
    HIGDIBINFO hDIB
);

Arguments:

hDIB
DIB info handle

Description:

This function returns the bit depth of an image. This number is the sum of the channel bit depths.

For example, if the image is a simple 24-bit RGB image, this function will return 24. If it's a 24-bit RGB image with an 8-bit alpha channel, this function will return 32.

Bits Per Pixel: All

Return Value:

Returns image bit depth.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIBInfo;    /* DIB info handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT imageDepth;      /* Returned bit depth of image */
nErrcount = IG_image_DIB_info_get(hImage, &hDIBInfo);
imageDepth = IG_DIB_bit_depth_get(hDIBInfo);

Sample: ARTEXT, LOADCB, THUMB, PDFDemo

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_channel_count_get

Group: DIB Info Services

Declaration:

AT_INT ACCUAPI IG_DIB_channel_count_get(
    HIGDIBINFO hDIB
);

Arguments:

hDIB
DIB info handle

Description:

This function returns the number of channels in the image.

For example, a typical 24-bit RGB image has three 8-bit channels (red, green, blue) so this function will return 3. For a 24-bit RGB image with a single alpha channel, this function would return 4.

Bits Per Pixel: All

Return Value:

Returns the number of channels in the image.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIBInfo;    /* DIB info handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT nChannels;       /* Returned number of channels */
nErrcount = IG_image_DIB_info_get(hImage, &hDIBInfo);
nChannels = IG_DIB_channel_count_get(hDIBInfo);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_channel_depth_get

Group: DIB Info Services

Declaration:

AT_INT ACCUAPI IG_DIB_channel_depth_get(
    HIGDIBINFO hDIB,
    AT_INT Index
);

Arguments:

hDIB
DIB info handle
Index
Index of channel to return bit depth of

Description:

This function returns the bit depth of the channel specified by the Index parameter.

For example, if you had a typical 24-bit RGB image with three 8-bit channels, you could specify 0, 1, or 2 for the index and the return value would be 8.

Bits Per Pixel: All

Return Value:

Returns specified channel's bit depth.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIBInfo;    /* DIB info handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT depth;           /* Returned depth of first channel */
nErrcount = IG_image_DIB_info_get(hImage, &hDIBInfo);
depth = IG_DIB_channel_depth_get(hDIBInfo, 0);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_channel_depths_get

Group: DIB Info Services

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_channel_depths_get(
    HIGDIBINFO hDIB,
    AT_INT ChannelCount,
    AT_INT *lpChannelDepths
);

Arguments:

hDIB
DIB info handle
ChannelCount
Number of channels to return depths for
lpChannelDepths
Array to copy channel depths to

Description:

This function copies channel bit depths to an array. You can use it to find out the bit depths of each individual channel.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIBInfo;    /* DIB info handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT nChannels;       /* Number of channels in image */
LPAT_INT depths;        /* Array of channel depths */
nErrcount = IG_image_DIB_info_get(hImage, &hDIBInfo);
nChannels = IG_DIB_channel_count_get(hDIBInfo);
depths = (LPAT_INT) malloc(nChannels * sizeof(AT_INT));
nErrcount = IG_DIB_channel_depths_get(hDIBInfo, nChannels,
depths);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_colorspace_get

Group: DIB Info Services

Declaration:

enumIGColorSpaceIDs ACCUAPI IG_DIB_colorspace_get(
    HIGDIBINFO hDIB
);

Arguments:

hDIB
DIB info handle

Description:

This function returns the image's color space. This is a bitmask that indicates the color space as well as the presence of alpha, premultiplied alpha, and extra channels.

See the IG_util_colorspace_...() functions for more functions that retrieve information about color spaces, alpha, and extra channels.

NOTE: Use caution when extracting information from this bitmask. For example, if you want to look at only the color space, you must use the mask IG_COLOR_SPACE_ID_ColorMask as in the example below.

Bits Per Pixel: All

Return Value:

Returns a combination of values from enumIGColorSpaceIDs.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIBInfo;    /* DIB info handle */
HIGEAR hImage;          /* HIGEAR handle of image */
enumIGColorSpaceIDs colorspace; /* Color space of image */
AT_BOOL bIndexed;       /* Is color space of image indexed? */
AT_BOOL bHasAlpha;      /* Does image have an alpha channel? */
/* Find out if an image is indexed, and if it has alpha */
nErrcount = IG_image_DIB_info_get(hImage, &hDIBInfo);
colorspace = IG_DIB_colorspace_get(hDIBInfo);
bIndexed = (colorspace & IG_COLOR_SPACE_ID_ColorMask) ==
IG_COLOR_SPACE_ID_I;
bHasAlpha = colorspace & IG_COLOR_SPACE_ID_A;

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_column_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_column_get ( HIGEAR hIGear,
    AT_PIXPOS nX,
    AT_PIXPOS nY1,
    AT_PIXPOS nY2,
    LPAT_PIXEL lpPixel,
    AT_DIMENSION nLenBytes,
    LPAT_DIMENSION lpNumPixels
);

Arguments:

hIGear
HIGEAR handle of image
nX
X offset (X coord) of the vertical pixel column to get
nY1
Raster line number at which the vertical column starts
nY2
Raster line number at which the vertical column ends
lpPixel
Far pointer to your data area to which the pixels should be returned
nLenBytes
Size of the data area, in bytes
lpNumPixels
Far pointer to a AT_DIMENSION variable in which will be returned the number of pixels (not bytes) transferred

Description:

This function obtains a column of pixels from the DIB image bitmap of image hIGear, and stores the pixels in your data area pointed to by lpPixel. The offset of the column to retrieve is indicated by nX. The beginning and ending raster lines of the column are nY1 and nY2, respectively (top to bottom).

NOTE: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.

If the pixels will not fit in nLenBytes, only nLenBytes of data will be transferred. The actual number of pixels transferred is returned in the variable pointed to by lpNumPixels.

If the image is 1-bit or 4-bit, the pixels will be returned one to a byte, right justified in the byte. If the image is 24-bit, each pixel will occupy 3 bytes, in Blue-Green-Red order.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;	   	/* HIGEAR handle of image					*/
AT_PIXEL cPixArray[400];  /* Receives the returned pixels  	*/
AT_PIXPOS nCol, nYtop, nYbot; /* Column and which rows to get
*/
AT_DIMENSION nFetched;  /* Holds count of pixels retrieved  	*/
AT_ERRCOUNT nErrcount;  /* Receives returned error counts  	*/
nCol  = 0;   /* Fetch left boundary of image  	*/
nYtop = 10;  nYbot = 59;   /* 50 pixels, from lines 10 thru 59
*/
nErrcount = IG_DIB_column_get ( hIGear, nCol, nYtop, nYbot,
&cPixArray[0], 400, &nFetched );

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_column_set

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_column_set ( HIGEAR hIGear,
    AT_PIXPOS nX,
    AT_PIXPOS nY1,
    AT_PIXPOS nY2,
    const LPAT_PIXEL lpPixel,
    AT_DIMENSION nNumPixels
);

Arguments:

hIGear
HIGEAR handle of image
nX
X offset (X coord) of the vertical pixel column to be set
nY1
Raster line number at which the vertical column starts
nY2
Raster line number at which the column ends
lpPixel
Far pointer to first byte of your pixel data
nNumPixels
Number of pixels (not bytes) to transfer

Description:

This function sets the pixel data you supply into the DIB image bitmap column specified by nX. The pixel at nX is set in pixel rows nY1 through nY2 inclusive. nNumPixels is the number of pixels to set, and should equal (nY2-nY1+1).

NOTE: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.

If the image is 1-bit or 4-bit, your pixels should be one to a byte and right justified, beginning at lpPixel. If the image is 24-bit, each pixel should occupy 3 bytes, in Blue-Green-Red order.

NOTE: If the image you are modifying is 1-bit, you will probably need to convert the image from run-end encoded to a standard DIB before you can set pixel values. Please see the section Using Pixel Access Functions with ImageGear Using ImageGear for details.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;  /* HIGEAR handle of image            */
AT_PIXEL cPixArray[400];  /* Receives the returned pixels
*/
AT_PIXPOS nCol,  nYtop,  nYbot; /* Column and rows to get
*/
AT_DIMENSION nFetched;  /* Holds the count of pixels retrieved*/
AT_ERRCOUNT nErrcount;  /* Receives the returned error counts */
/* Restore the pixels saved by the call in example
IG_DIB_column_get:   */
nCol  = 0;   /* Restores to image's left boundary */
nYtop = 10;  nYbot = 59;   /* 50 pixels, from lines 10 thru 59*/
nFetched = nYbot - Top + 1;
nErrcount = IG_DIB_column_set ( hIGear, nCol, nYtop, nYbot,
&cPixArray[0],nFetched );

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_flood_fill

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_flood_fill(
    HIGEAR hIGear,
    AT_INT xPos,
    AT_INT yPos,
    LPAT_PIXEL lpFillPixel,
    LPAT_PIXEL lpBorderPixel
);

Arguments:

hIGear
Image to process.
xPos
X coordinate of a point inside the area to be filled.
yPos
X coordinate of a point inside the area to be filled.
lpFillPixel
Fill color.
lpBorderPixel
Color of the border surrounding the area.

Description:

This function fills an area with a color, starting at the specified point. There are two ways to specify the area:

  • If BorderColor is NULL, the area is defined by the color of the specified point.
  • Otherwise, the area is defined by the border color.

Applicability:

All except bitonal.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

PIX_ACC


IG_DIB_height_get

Group: DIB Info Services

Declaration:

AT_DIMENSION ACCUAPI IG_DIB_height_get(
    HIGDIBINFO hDIB
);

Arguments:

hDIB
DIB info handle

Description:

This function returns the height of the image.

Bits Per Pixel: All

Return Value:

Returns image height.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIBInfo;    /* DIB info handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_DIMENSION height;    /* Returned height of image */
nErrcount = IG_image_DIB_info_get(hImage, &hDIBInfo);
height = IG_DIB_height_get(hDIBInfo);

Sample: ARTEXT, FILTER, LOADCB, PDFDemo

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_info_copy

Group: DIB Info Services

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_info_copy(
    HIGDIBINFO hDIBSrc,
    HIGDIBINFO *lphDIBDst
);

Arguments:

hDIBSrc
DIB info handle to copy from
lphDIBDst
Pointer to where copied DIB info handle will be stored

Description:

This function makes a copy of a DIB info object.

NOTE: It does not copy pixel data.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;   /* Number of errors on stack */
HIGDIBINFO hDIBInfo;     /* Handle of DIB info to be copied */
HIGDIBINFO hDIBInfoCopy; /* Handle of DIB info copy */
HIGEAR hImage;           /* HIGEAR handle of image */
nErrcount = IG_image_DIB_info_get(hImage, &hDIBInfo);
nErrcount = IG_DIB_info_copy(hDIBInfo, &hDIBInfoCopy);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_info_create

Group: DIB Info Services

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_info_create(
    HIGDIBINFO *lphDIB,
    AT_DIMENSION width,
    AT_DIMENSION height,
    enumIGColorSpaceIDs colorspace,
    AT_INT channelCount,
    AT_INT *channelDepths
);

Arguments:

lphDIB
Pointer to where created DIB info's handle will be stored
width
Width of image in pixels
height
Height of image in pixels
colorspace
Colorspace of image
channelCount
Number of channels in image
channelDepths
Array of channel depths

Description:

This function creates a new DIB info object and initializes it to the given values. The DIB info object must be deleted with IG_DIB_info_delete when it is finished being used.

NOTE: It does not allocate pixel data storage.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Create a DIB info object describing a 48-bit RGB image */
AT_ERRCOUNT nErrcount;   /* Number of errors on stack */
HIGDIBINFO hDIBInfo;             /* DIB info handle */
AT_INT depths[3] = {16, 16, 16}; /* Array of channel depths */
nErrcount = IG_DIB_info_create(&hDIBInfo, 320, 240,
IG_COLOR_SPACE_ID_RGB, 3, depths);
/* ... */
nErrcount = IG_DIB_info_delete(hDIBInfo);

Sample: MED

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_info_delete

Group: DIB Info Services

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_info_delete(
    HIGDIBINFO hDIB
);

Arguments:

hDIB
DIB info handle

Description:

This function deletes a DIB info object.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Create a DIB info object describing a 24-bit RGB image */
AT_ERRCOUNT nErrcount;   /* Number of errors on stack */
HIGDIBINFO hDIBInfo;             /* DIB info handle */
AT_INT depths[3] = {8, 8, 8};    /* Array of channel depths */
nErrcount = IG_DIB_info_create(&hDIBInfo, 320, 240,
IG_COLOR_SPACE_ID_RGB, 3, depths);
/* ... */
nErrcount = IG_DIB_info_delete(hDIBInfo);

Sample: ARTEXT, DISPLAY, FILTER, IC, IMG_PROC, ISIS, JPEG, LOADCB, MED, MULTIMEDIA, PALEDT, PJPEG, PRINT, RECOGNITION, TWAIN, PDFDemo

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_info_raster_size_get

Group: DIB Info Services

Declaration:

AT_INT ACCUAPI IG_DIB_info_raster_size_get(
    HIGDIBINFO hDIB
);

Arguments:

hDIB
DIB info handle

Description:

This function returns the number of bytes per raster in the DIB.

For all images except 1-bit images, the returned number is precise.

For 1-bit images, the function returns the raster size assuming that 8 pixels are packed per byte. In reality, ImageGear internally stores 1-bit images using run ends scheme. The size of the raster stored in memory depends on the content of the raster, but usually the raster occupies much less space than the number returned by IG_DIB_info_raster_size_get.

Bits Per Pixel: All

Return Value:

Returns DIB raster size.

Example:

HIGDIBINFO hDIBInfo;    /* DIB info handle */
AT_INT rasterSize;      /* Returned raster size */
rasterSize = IG_DIB_info_raster_size_get(hDIBInfo);

Sample: PDFDemo

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_legacy_bit_depth_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_legacy_bit_depth_get(
    HIGEAR hIGear,
    LPAT_INT lpBitsPerPixel
);

Arguments:

hIGear
HIGEAR handle of image
lpBitsPerPixel
Returned legacy bit depth of the image

Description:

This function returns the bit depth that earlier ImageGear versions used to store this image. This can be used for working with pixel access functions in the legacy mode.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
AT_INT bpp;             /* Image bit depth */
nErrcount = IG_DIB_legacy_bit_depth_get(hImage, &bpp);
/* bpp could be 1, 4, 8, 9-16, 24, or 32 */

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_line_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_line_get ( HIGEAR hIGear,
    PIXPOS nX1,
    AT_PIXPOS nY1,
    AT_PIXPOS nX2,
    AT_PIXPOS nY2,
    LPAT_PIXEL lpPixel,
    const AT_DIMENSION nlenOfArray,
    LPAT_DIMENSION lpNumPixels
);

Arguments:

hIGear
HIGEAR handle of image
nX1
X coordinate of the first endpoint of line to get
nY1
Y coordinate of the first endpoint
nX2
X coordinate of the second endpoint of line
nY2
Y coordinate of the second endpoint
lpPixel
Far pointer to your data area to which the pixels should be returned
nLenOfArray
Length, in bytes, of lpPixel block
lpNumPixels
Far pointer to an AT_DIMENSION variable in which the number of pixels (not bytes) transferred is returned.

Description:

This function obtains an arbitrary line of pixels from the DIB image bitmap of the image referenced by hIGear. The line does not have to be horizontal or vertical. nX1,nY1 are the coordinates of one endpoint of the line and nX2,nY2 are of the other.

If the pixel data would overflow your area (nLenOfArray), the transfer will be truncated; your data area will not be overflowed. The actual number of pixels returned will be stored in your variable pointed to by lpNumPixels.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during the function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.
NOTE: To determine the number of pixels that your line will be comprised of, use the following formula:
max((1+abs(x2-x1)), (1+abs(y2-y1)))

1-bit and 4-bit pixels are returned one to a byte, right justified. 24-bit pixels are returned 3 bytes per pixel, in Blue-Green-Red order.

Example:

See the example for function IG_DIB_line_set ().

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_line_set

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_line_set ( HIGEAR hIGear,
    PIXPOS nX1,
    AT_PIXPOS nY1,
    AT_PIXPOS nX2,
    AT_PIXPOS nY2,
    const LPAT_PIXEL lpPixel,
    AT_DIMENSION nNumPixels
);

Arguments:

hIGear
HIGEAR handle of image to transfer pixels to
nX1
X coordinate of the first endpoint of line to store
nY1
Y coordinate of the first endpoint
nX2
X coordinate of the second endpoint of line to store
nY2
Y coordinate of the second endpoint
lpPixel
Far pointer to your data area containing the pixels to be stored
nNumPixels
Number of pixels (not bytes) to be transferred

Description:

This function stores an arbitrary line of pixels in the DIB image bitmap of the image referenced by HIGEAR. The line does not have to be horizontal or vertical. (nX1,nY1) are the coordinates of one endpoint of the line and (nX2,nY2) are of the other.

NOTE: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.

If the image you are modifying is 1-bit, you must convert the image from run-end encoded to a standard DIB before you can set pixel values. Please see the section Using Pixel Access Functions with ImageGear for details.

1-bit and 4-bit pixels should be provided one to a byte, right justified (that is, in the least significant bits of the byte). 24 bit pixels should be 3 bytes per pixel, in Blue-Green-Red order.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

TIP: To calculate the number of pixels that your line will consist of, use the following formula:
max((1+abs(x2-x1)), (1+abs(y2-y1)))

Example:

HIGEAR hIGear;	    /* HIGEAR handle of image              */
AT_PIXEL cPixArray[400]; /* Receives the returned pixels
*/
AT_PIXPOS nXleft, nYtop,  /* Coordinates of upper-left end of
line*/
  nXright, nYbot; /* Coordinates of the lower-right end   */
AT_DIMENSION nFetched; 	   /* Holds the count of pixels retrieved
*/
AT_ERRCOUNT  nErrcount; 	   /* Receives the returned error counts
*/
/* Fetch a diagonal line, from Coordinates (0,0) to (100,100):
*/
nXleft  = 0;    nYtop = 0;					/* Diagonal line from upper left
corner	     */
nXright = 100;  nYbot = 100;
nErrcount = IG_DIB_line_get ( hIGear, nXleft, nYtop, nXright,
nYbot, &cPixArray[0], 400, &nFetched );
 ...
/* Now restore the line: */
nErrcount = IG_DIB_line_set ( hIGear, nXleft, nYtop, nXright,
nYbot, &cPixArray[0], nFetched );

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_palette_alloc

Group: DIB Info Services

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_palette_alloc(
    HIGDIBINFO hDIB
);

Arguments:

hDIB
DIB info handle

Description:

This function allocates a palette for the given DIB.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIB;        /* DIB info handle */
AT_INT nEntries;        /* Number of palette entries */
LPAT_RGBQUAD lpPalette; /* Pointer to palette data */
AT_INT i;               /* Index for palette loop */
/* Make a palette in which every color is GREEN */
nErrcount = IG_DIB_palette_alloc(hDIB);
nEntries = IG_DIB_palette_length_get(hDIB);
lpPalette = IG_DIB_palette_pointer_get(hDIB);
for (i = 0; i < nEntries; i++)
{
    lpPalette[i].rgbRed = lpPalette[i].rgbBlue = 0;
    lpPalette[i].rgbGreen = 255;
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_palette_length_get

Group: DIB Info Services

Declaration:

AT_INT ACCUAPI IG_DIB_palette_length_get(
    HIGDIBINFO hDIB
);

Arguments:

hDIB
DIB info handle

Description:

This function returns the number of entries in the DIB's palette.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level

Return Value:

Returns the number of palette entries.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIB;        /* DIB info handle */
AT_INT nEntries;        /* Number of palette entries */
LPAT_RGBQUAD lpPalette; /* Pointer to palette data */
AT_INT i;               /* Index for palette loop */
/* Make a palette in which every color is GREEN */
nErrcount = IG_DIB_palette_alloc(hDIB);
nEntries = IG_DIB_palette_length_get(hDIB);
lpPalette = IG_DIB_palette_pointer_get(hDIB);
for (i = 0; i < nEntries; i++)
{
    lpPalette[i].rgbRed = lpPalette[i].rgbBlue = 0;
    lpPalette[i].rgbGreen = 255;
}

Sample: MED, PDFDemo

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_palette_pointer_get

Group: DIB Info Services

Declaration:

LPAT_RGBQUAD ACCUAPI IG_DIB_palette_pointer_get(
    HIGDIBINFO hDIB
);

Arguments:

hDIB
DIB info handle

Description:

This function returns a pointer to the DIB's palette, if it is present. Otherwise it returns NULL. You can use this to get and set palette entries or the palette as a whole.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level

Return Value:

Pointer to the DIB palette, if it is present. NULL - otherwise.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIB;        /* DIB info handle */
AT_INT nEntries;        /* Number of palette entries */
LPAT_RGBQUAD lpPalette; /* Pointer to palette data */
AT_INT i;               /* Index for palette loop */
/* Make a palette in which every color is GREEN */
nErrcount = IG_DIB_palette_alloc(hDIB);
nEntries = IG_DIB_palette_length_get(hDIB);
lpPalette = IG_DIB_palette_pointer_get(hDIB);
for (i = 0; i < nEntries; i++)
{
    lpPalette[i].rgbRed = lpPalette[i].rgbBlue = 0;
    lpPalette[i].rgbGreen = 255;
}

Sample: LOADCB, MED, PDFDemo

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_palette_size_get

Group: DIB Info Services

Declaration:

AT_INT ACCUAPI IG_DIB_palette_size_get(
    HIGDIBINFO hDIB
);

Arguments:

hDIB
DIB info handle

Description:

This function returns the size of the DIB's palette, in bytes.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level

Return Value:

DIB palette size, in bytes.

Example:

HIGDIBINFO hDIB;        /* DIB info handle */
AT_INT paletteSize;     /* Returned size of palette */
paletteSize = IG_DIB_palette_size_get(hDIB);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_pixel_array_size_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_pixel_array_size_get(
    HIGEAR hIGear,
    AT_DIMENSION length,
    AT_MODE format,
    LPAT_DIMENSION lpSize
);

Arguments:

hIGear
HIGEAR handle of image containing pixel data
length
Number of pixels to calculate array size for
format
IG_PIXEL_UNPACKED - all bit depths are unpacked (at least one byte per pixel)
IG_PIXEL_PACKED - In legacy mode: 1 and 4 bit images are packed (8 or 2 pixels per byte). In new mode: Only 1 bit images are packed (8 pixels per byte)
lpSize
Returned array size in bytes

Description:

This function returns the number of bytes needed to store an array of pixels. This can be used to allocate storage for use with pixel access functions. This function is similar to IG_DIB_raster_size_get(), but it lets you specify the number of pixels instead of using the number of pixels in an entire raster.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Get # of bytes needed to store half a row */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
AT_DIMENSION w, h;      /* Width and height of image */
AT_DIMENSION nBytes;    /* Size of pixel array in bytes */
nErrcount = IG_image_dimensions_get(hImage, &w, &h, NULL);
nErrcount = IG_DIB_pixel_array_size_get(hImage, w / 2,
    IG_PIXEL_UNPACKED, &nBytes);

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_pixel_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_pixel_get (
    HIGEAR hIGear,
    AT_PIXPOS nXpos,
    AT_PIXPOS nYpos,
    LPAT_PIXEL lpPixel
);

Arguments:

hIGear
HIGEAR handle of image.
nXpos
X offset (in pixels) from beginning of raster line. First pixel on line is pixel number 0.
nYpos
Raster line number. 0 is top line.
lpPixel
Far pointer to byte at which to store pixel (or to a 3-byte area if a 24-bit pixel)

Description:

This function obtains the pixel at coordinates (nXpos, nYpos), storing it right justified (that is, in the least significant bits) at the location pointed to by lpPixel. If the pixel is 1-bit or 4-bit, the remaining bits of the byte will be set to zeroes.

If the pixel is 24-bit, 3 bytes are returned. These will be in the order Blue-Green-Red (unless you have changed the order of the image bitmap bytes such as by calling function IG_IP_swap_red_blue ()).

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

TIP: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.

Example:

HIGEAR hIGear; /* HIGEAR handle of image						*/
AT_PIXEL		cPixelValue[3];/* 3 bytes in case 24-bit image								*/
        /* Get value of the upper-leftmost pixel in image: 								*/
IG_DIB_pixel_get ( hIGear, 0, 0, &cPixelValue[0] );

Sample: PIX_ACC, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_pixel_set

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_pixel_set (
    HIGEAR hIGear,
    AT_PIXPOS nXpos,
    AT_PIXPOS nYpos,
    const LPAT_PIXEL lpPixel
);

Arguments:

hIGear
HIGEAR handle of an image.
nXpos
X offset (in pixels) from beginning of raster line. First pixel on line is pixel number 0.
nYpos
Raster line number. 0 is top line.
pPixel
Far pointer to byte containing pixel, or to a 3-byte area if a 24-bit pixel

Description:

This function sets the pixel, at the location pointed to by lpPixel, into the image bitmap of image hIGear at coordinates (nXpos, nYpos). The pixel is assumed to have the same number of Bits Per Pixel as the image, and if it is 1 or 4 bits, it is assumed to be right justified (that is, in the least significant bits) at location lpPixel. If the image is 24-bit, 3 bytes are transferred. Normally, these bytes will be in the order of Blue-Green-Red (unless the order of the image bitmap bytes has been changed by a call such as IG_IP_swap_red_blue ()).

TIP: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.
NOTE: If the image you are modifying is 1-bit, you must convert the image from run-end encoded to a standard DIB, before you can set pixel values. Please see the section Using Pixel Access Functions with ImageGear for details.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;/* HIGEAR handle of image						*/
AT_PIXEL cPixelValue[3];/* 3 bytes in case 24-bit image								*/
/* Set upper-leftmost pixel in image, to max pixel value:										*/
cPixelValue[0] = cPixelValue[1] = cPixelValue[2] = 255;
IG_DIB_pixel_set ( hIGear, 0, 0, &cPixelValue[0] );

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_pix_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_pix_get(
    HIGEAR hIGear,
    AT_PIXPOS xpos,
    AT_PIXPOS ypos,
    HIGPIXEL *lphPixel
);

Arguments:

hIGear
HIGEAR handle of image to get pixel from
xpos
X coordinate (0 to width-1)
ypos
Y coordinate (0 to height-1)
lphPixel
Returns object containing pixel data

Description:

This function gets a pixel from the specified location in the image. The pixel data is contained by a pixel object with handle of type HIGPIXEL. This pixel object stores values for each channel in the image.

Bits Per Pixel:

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGPIXEL hPix;          /* Handle of pixel */
AT_DIMENSION w, h;      /* Width and height of image */
AT_INT nChannels;       /* Number of channels in image */
AT_DIMENSION x, y;      /* Used to loop over image */
AT_INT c;               /* Used to loop over channels */
AT_INT nDepth;          /* Channel depth */
AT_UINT inverted;       /* Inverted channel value */
/* Invert colors in upper-left quadrant of image */
nErrcount = IG_load_file("test.jpg", &hImage);
nErrcount = IG_image_channel_count_get(hImage, &nChannels);
nErrcount = IG_image_dimensions_get(hImage, &w, &h, NULL);
for (y = 0; y < h / 2; y++)
    for (x = 0; x < w / 2; x++)
    {
        nErrcount = IG_DIB_pix_get(hImage, x, y, &hPix);
        for (c = 0; c < nChannels; c++)
        {
            IG_image_channel_depth_get(hImage, c, &nDepth);
            nDepth = (1 << nDepth) - 1;
            inverted = nDepth - IG_pixel_value_get(hPix, c);
            IG_pixel_value_set(hPix, c, inverted);
        }
        nErrcount = IG_DIB_pix_set(hImage, x, y, hPix);
        IG_pixel_delete(hPix);
    }
nErrcount = IG_save_file(hImage, "test.bmp",
    IG_SAVE_BMP_UNCOMP);
IG_image_delete(hImage);

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_pix_set

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_pix_set(
    HIGEAR hIGear,
    AT_PIXPOS xpos,
    AT_PIXPOS ypos,
    const HIGPIXEL hPixel
);

Arguments:

hIGear
HIGEAR handle of image to set pixel into
xpos
X coordinate (0 to width-1)
ypos
Y coordinate (0 to height-1)
hPixel
Pixel data to write

Description:

This function sets a pixel at the specified location in the image. The pixel data is contained by a pixel object with handle of type HIGPIXEL. This pixel object stores values for each channel in the image.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGPIXEL hPix;          /* Handle of pixel */
AT_DIMENSION w, h;      /* Width and height of image */
AT_INT nChannels;       /* Number of channels in image */
AT_DIMENSION x, y;      /* Used to loop over image */
AT_INT c;               /* Used to loop over channels */
AT_INT nDepth;          /* Channel depth */
AT_UINT inverted;       /* Inverted channel value */
/* Invert colors in upper-left quadrant of image */
nErrcount = IG_load_file("test.jpg", &hImage);
nErrcount = IG_image_channel_count_get(hImage, &nChannels);
nErrcount = IG_image_dimensions_get(hImage, &w, &h, NULL);
for (y = 0; y < h / 2; y++)
    for (x = 0; x < w / 2; x++)
    {
        nErrcount = IG_DIB_pix_get(hImage, x, y, &hPix);
        for (c = 0; c < nChannels; c++)
        {
            IG_image_channel_depth_get(hImage, c, &nDepth);
            nDepth = (1 << nDepth) - 1;
            inverted = nDepth - IG_pixel_value_get(hPix, c);
            IG_pixel_value_set(hPix, c, inverted);
        }
        nErrcount = IG_DIB_pix_set(hImage, x, y, hPix);
        IG_pixel_delete(hPix);
    }
nErrcount = IG_save_file(hImage, "test.bmp",
    IG_SAVE_BMP_UNCOMP);
IG_image_delete(hImage);

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_raster_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_raster_get (
    HIGEAR hIGear,
    AT_PIXPOS nYpos,
    LPAT_PIXEL lpPixel,
    AT_MODE nFormat
);

Arguments:

hIGear
HIGEAR handle of image
nYpos
Raster line number (0 is top line)
lpPixel
Far pointer to first byte of area to receive the raster row of pixel values.
nFormat
A variable of type AT_MODE (see accucnst.h) that tells whether the data being read in packed, unpacked, or RLE-compressed.

Description:

This function obtains an entire horizontal raster line of pixels from the DIB image bitmap. You may first make a call to IG_DIB_raster_size_get () in order to determine the size of buffer that you will need to hold the raster data. The format in which the data is returned, nFormat, tells ImageGear whether the data is packed, unpacked, or RLE-compressed. The values that nFormat may be set to are: IG_PIXEL_PACKED, IG_PIXEL_UNPACKED, and IG_PIXEL_RLE. IG_PIXEL_PACKED gives the storage format of a standard uncompressed DIB, which includes padding to a multiple of 4 bytes length. (If 1-bit or 4-bit, the pixels are packed 8 or 2 to a byte respectively, stored most-significant-bit-first.) 24-bit pixels are returned 3 bytes each, ordered Blue-Green-Red, with the row padded to a multiple of 4 bytes length.

TIP: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR		 hIGear;			/* HIGEAR handle of image 					*/
AT_PIXEL		 cPixelValue[64];			/* Needed to hold 500 1-bit pixels					*/
AT_PIXPOS		 nRaster;			/* Index for the loop below 					*/
AT_ERRCOUNT		 nErrcount;			/* Hold the returned error count					*/
AT_MODE	 	nFormat;
/* Obtain the top raster of a 1-bit image that's 500 pixels
wide:		*/
/* The pixels occupy 500/8 = 62.5 bytes.						*/
nErrcount = IG_DIB_raster_get ( hIGear, 0, &cPixelValue[0],
IG_PIXEL_PACKED);
/* Make the next 9 rows identical to the top row: */
for ( nRaster = 1; nRaster < 10; nRaster++ )
    nErrcount = IG_DIB_raster_set ( hIGear, nRaster,
&cPixelValue[0], IG_PIXEL_PACKED );

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_raster_set

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_raster_set (
    HIGEAR hIGear,
    AT_PIXPOS nYpos,
    Const LPAT_PIXEL lpPixel,
    AT_MODE nFormat
);

Arguments:

hIGear
HIGEAR handle of an image
nYpos
Raster line number (0 is top line)
lpPixel
Far pointer to first byte of the pixel data to set
nFormat
A variable of type AT_MODE which indicates in which manner the raster data should be stored: IG_PIXEL_PACKED, IG_PIXEL_UNPACKED, or IG_PIXEL_RLE.

Description:

This function sets a horizontal raster line of pixels into the DIB image bitmap. nFormat should be set to the same format in which the rest of the data in the DIB is stored. If you choose IG_PIXEL_PACKED, your array of bytes should be padded with zeroes on the right, just as it is in the standard DIB format, such that its length is a multiple of 4.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

TIP: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.
NOTE: If the image you are modifying is 1-bit, you must convert the image from run-end encoded to a standard DIB, before you can set pixel values. Please see the section Using Pixel Access Functions with ImageGear for details.

Example:

See the example for function IG_DIB_raster_get ().

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_raster_size_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_raster_size_get(
    HIGEAR hIGear,
    AT_MODE nFormat,
    LPAT_DIMENSION lpSize
);

Arguments:

hIGear
HIGEAR handle of the image.
nFormat
Format in which the raster data is stored: IG_PIXEL_PACKED, IG_PIXEL_UNPACKED, IG_PIXEL_RLE.
lpSize
A far pointer to a variable in which the size of the raster line (in bytes) is returned.

Description:

This function calculates and returns the number of bytes required to hold a line (raster) from the image. You can use this function to determine the size of a block of memory to allocate before using IG_DIB_raster_get (), to avoid data overflow. The returned size will include allocation for buffering at the end of the rasters. (See the section Device-Independent Bitmaps (DIB) for more information on buffering in DIBs.) The nFormat variable determines in what form you would like to store the pixels in. The size will vary according to the storage method.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Also Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_resolution_get

Group: DIB Info Services

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_resolution_get(
    HIGDIBINFO hDIB,
    AT_RESOLUTION *lpResolution
);

Arguments:

hDIB
DIB info handle
lpResolution
Pointer to struct to copy DIB resolution to

Description:

This function copies resolution from DIB to lpResolution.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIB;        /* DIB info handle */
AT_RESOLUTION res;      /* Returned image resolution */
nErrcount = IG_DIB_resolution_get(hDIB, &res);

Sample: PDFDemo

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_resolution_set

Group: DIB Info Services

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_resolution_set(
    HIGDIBINFO hDIB,
    const AT_RESOLUTION *lpResolution
);

Arguments:

hDIB
DIB info handle
lpResolution
Pointer to struct to copy to DIB

Description:

This function copies resolution from lpResolution to DIB.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIB;        /* DIB info handle */
AT_RESOLUTION res;      /* Image resolution to be set */
/* Set resolution to 300 DPI */
res.units = IG_RESOLUTION_INCHES;
res.xResNumerator = res.yResNumerator = 300;
res.xResDenominator = res.yResDenominator = 1;
nErrcount = IG_DIB_resolution_set(hDIB, &res);

Sample: PDFDemo

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_resolution_units_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_resolution_units_get(
    LPAT_MODE lpnResUnits
);

Arguments:

lpnResUnits
Pointer to AT_MODE where to return current identifier of resolution units.

Description:

ImageGear allows you to store the DIB resolution - biXPelsPerMeter and biYPelsPerMeter fields of AT_DIB structure - in different units depending on a global parameter. This function allows you to get the current value of this parameter. Valid values are IG_RESOLUTION_INCHES and IG_RESOLUTION_METERS. The default value is IG_RESOLUTION_METERS.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;		/* HIGEAR handle of image */
AT_MODE nResUnits;
. . .IG_DIB_resolution_units_get( &nResUnits );. . .

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_resolution_units_set

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_resolution_units_set(
    AT_MODE nDIBResUnits
);

Arguments:

nDIBResUnits
Value of type AT_MODE. Can be either IG_RESOLUTION_INCHES or IG_RESOLUTION_METERS.

Description:

ImageGear allows you to store the DIB resolution (biXPelsPerMeter and biYPelsPerMeter fields of AT_DIB structure) in different units depending on a global parameter. This function allows you to set the current value of this parameter. Valid values are IG_RESOLUTION_INCHES and IG_RESOLUTION_METERS. The default value is IG_RESOLUTION_METERS.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
AT_MODE nDIBResUnits
nDIBResUnits = IG_RESOLUTION_INCHES
...IG_DIB_resolution_units_set( nDIBResUnits );. . .

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_row_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_row_get (
    HIGEAR hIGear,
    AT_PIXPOS nXpos,
    AT_PIXPOS nYpos,
    AT_DIMENSION nLength,
    LPVOID lpPixel,
    AT_MODE nFormat
);

Arguments:

hIGear
HIGEAR handle of image
nXpos
X offset (in pixels) from beginning of the raster line. First pixel on line is pixel number 0. Specify as -1 to obtain the entire raster line of pixels.
nYpos
Raster line number (0 is top line)
nLength
Number of consecutive pixels to obtain (enitre raster line if nXpos = -1)
lpPixel
Far pointer to first byte of your area, at which the pixels obtained are to be stored
nFormat
Format in which the raster data is read: IG_PIXEL_PACKED, IG_PIXEL_UNPACKED, IG_PIXEL_RLE.

Description:

This function obtains a consecutive row of nLength pixels beginning at coordinates (nXpos, xYpos) in the image bitmap. If nFormat is set to IG_PIXEL_UNPACKED, and the image is 1 or 4-bit, the pixels obtained are stored right justified, one to a byte, beginning at your byte pointed to by lpPixel. The unused bits of the bytes are set to zero. If the pixels are 24-bit, 3 bytes per pixel are returned, ordered Blue-Green-Red. A total of nLength pixels is transferred. (See the section Device-Independent Bitmaps (DIB) Understanding Bitmap Images for more details on pixel storage in DIBs.)

TIP: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24. 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR		 hIGear;		/* HIGEAR handle of image						  	*/
AT_PIXEL		 cPixelValue[300];			/* To hold 100 pixels, in case 24-
bit*/
AT_PIXPOS		 nRow;		/* Index for the loop below						  	*/
AT_DIMENSION		 nRowLen;		/* How much of row to copy 						  	*/
AT_ERRCOUNT		 nErrcount;		/* Holds the returned error count						 	*/
/* Obtain leftmost 100 pixels of top raster of image:									  		*/
nRowLen = 100;
nErrcount = IG_DIB_row_get ( hIGear, 0, 0, nRowLen,
&cPixelValue[0], IG_PIXEL_UNPACKED );
/* Make leftmost 100 pixels of next 9 rows identical:
*/
for ( nRow = 1; nRow < 10; nRow++ )
    nErrcount = IG_DIB_row_set (hIGear, 0, nRow,
        nRowLen, cPixelValue, IG_PIXEL_UNPACKED);

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_row_set

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_row_set (
    HIGEAR hIGear,
    AT_PIXPOS nXpos,
    AT_PIXPOS nYpos,
    AT_DIMENSION nLength,
    const LPVOID lpPixel,
    AT_MODE nFormat
);

Arguments:

hIGear
HIGEAR handle of image
nXpos
X offset (in pixels) from beginning of raster line. First pixel on line is pixel number 0
nYpos
Raster line number. 0 is top line
nLength
Number of consecutive pixels to transfe
lpPixel
Far pointer to byte at which the pixels to transfer begin
nFormat
Format in which the raster data is stored: IG_PIXEL_PACKED, IG_PIXEL_UNPACKED, IG_PIXEL_RLE.

Description:

This function writes a consecutive row of nLength pixels that begin at lpPixel, into image hIGear`s DIB image bitmap. The row is written into raster line nYpos, beginning at pixel offset nXpos. If nFormat is set to IG_PIXEL_UNPACKED, and the image is 1-bit or 4-bit, your pixels to be transferred should be one to a byte, right justified (that is, in the least significant bits). If a 24-bit image, each pixel should occupy 3 bytes, ordered Blue-Green-Red. (See the section Device-Independent Bitmaps (DIB) for more details on pixel storage in DIBs.)

(If (nXpos + nLength) is greater than the width of the image as indicated in the DIB header, an error will result.

TIP: ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.
NOTE: If the image you are modifying is 1-bit, you will probably need to convert the image from run-end encoded to a standard DIB, before you can set pixel values. Please see the section Using Pixel Access Functions with ImageGear Using ImageGearfor details.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

See the example for function IG_DIB_row_get ().

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_DIB_width_get

Group: DIB Info Services

Declaration:

AT_DIMENSION ACCUAPI IG_DIB_width_get(
    HIGDIBINFO hDIB
);

Arguments:

hDIB
DIB info handle

Description:

This function returns the width of the image.

Bits Per Pixel: All

Return Value:

Width of the image.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIBInfo;    /* DIB info handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_DIMENSION width;     /* Returned height of image */
nErrcount = IG_image_DIB_info_get(hImage, &hDIBInfo);
width = IG_DIB_width_get(hDIBInfo);

Sample: ARTEXT, FILTER, LOADCB, PDFDemo

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_display_animation_delay_get

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_display_animation_delay_get (
    HIGEAR hIGear,
    LPUINT lpDelay
);

Arguments:

hIGear
HIGEAR handle of image
lpDelay
Far pointer to a UINT variable to receive current animation delay setting for this image

Description:

This function obtains the animation delay setting for image hIGear, as set by IG_display_animation_delay_set (). ImageGear does not provide functions for creating animation. This function is for getting this value from the HIGEAR. You will need to write your own code to display the images in succession (animate).

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		 hIGear;		/* HIGEAR handle of image 						   */
UINT		 nDelay;		/* Will hold returned Delay setting					     */
IG_display_animation_delay_get ( hIGear, &nDelay );

Sample: MULTIMED

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_display_animation_delay_set

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_display_animation_delay_set (
    HIGEAR hIGear,
    UINT nDelay
);

Arguments:

hIGear
HIGEAR handle of image
nDelay
Animation delay, in milliseconds. A setting of 100 would mean 10 frames per second.

Description:

This function sets the animation delay for image hIGear. (At present, this quantity is meaningful only with GIF format files.) ImageGear does not provide functions for creating animation. This function is for setting this value in the HIGEAR. You will need to write your own code to display the images in succession (animate).

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		 hIGear;			/* HIGEAR handle of image				*/
/* Set for 5 frames per second: */
IG_display_animation_delay_set ( hIGear, 200 );

Sample: MULTIMED

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_display_option_get

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_display_option_get (
    HIGEAR hIGear,
    AT_MODE nOption,
    LPVOID lpOption,
    LPVOID lpReserved
);

Arguments:

hIGear
HIGEAR handle of image, or NULL
nOption
A integer of type AT_MODE that tells ImageGear what type of display option to return a value for. The options are defined in accucnst.h and their names begin with IG_DISPLAY_OPTION_.
lpOption
A long pointer to VOID data returned as display option data
lpReserved
This argument is reserved for future use. Please set to NULL for now.

Description:

This function allows you to get the current display option settings for either a specific HIGEAR image or to get the settings that will be inherited by each new HIGEAR image.

The value that you set for hIGear determines whether the option settings will be retrieved from a specific image or a global setting for all new HIGEAR images. If you set hIGear to a specific image, the settings for that image will be returned. If you set hIGear to NULL, global settings for all new HIGEAR images will be returned.

NOTE: See the description under IG_display_option_set() for more details about the display settings.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_display_option_set

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_display_option_set (
    HIGEAR  hIGear,
    AT_MODE nOption,
    const LPVOID lpOption,
    LPVOID lpReserved
);

Arguments:

hIGear
HIGEAR handle of image or NULL
nOption
A integer of type AT_MODE that tells ImageGear what which display option to set. The options are defined in accucnst.h and their names begin with IG_DISPLAY_OPTION_.
lpOption
A long pointer to VOID display option data. See details below
lpReserved
This argument is reserved for future use. Please set to NULL for now.

Description:

This function allows you to set the current display option settings for either a specific HIGEAR image or to set the settings that will be inherited by each new HIGEAR image.

You may set these options for a specific HIGEAR or for all newly created HIGEAR images. To set the options for a particular HIGEAR image, set hIGear to the appropriate handle. To set the options for all newly created HIGEAR images, set hIGear to NULL.

nOption must be set to one of the IG_DISPLAY_OPTION_ constants defined in accucnst.h. lpOption should be set to the value of the option. This will vary depending on what option you are setting. See the list below.

NOTE: As of this writing, this function is useful for 16-bit grayscale images only. However, constants will be added to support all bit depths. See accucnst.h for new constants beginning with IG_DISPLAY_OPTION_.

Currently available options include:

  • IG_DISPLAY_OPTION_DOWNSHIFT: This option is for 16-bit grayscale DIBs only. It has no effect on any other image bit depth. The value passed in to nOption must be in the range of 0 to 16 (the value is cast to a LPVOID - the address of this value is not passed in). This value specifies how far each 16-bit pixel should be downshifted before the least significant word is taken for display. All remaining bits in the high word are discarded. Setting this option turns off the IG_DISPLAY_OPTION_LUT option.
  • IG_DISPLAY_OPTION_LUT: This option is for 16-bit grayscale DIBs only. It has no effect on any other image bit depth. The value passed in to nOption must be a pointer to a 16x8 LUT (64K of memory). This table should be filled with values that allow ImageGear to display 16-bit grayscale pixels on a 8-bit display. Setting this option turns off the IG_DISPLAY_OPTION_DOWNSHIFT option.

Additional options include:

  • IG_DISPLAY_OPTION_OFFSCREEN_DRAW: If this parameter is TRUE then the display code optimizes the drawing when the ART component is used to prevent flashing. This a bit slower, but the visual quality is better. Otherwise, each redraw operation is directly displayed, with flashing possible.
  • IG_DISPLAY_OPTION_DDB_OPTIMIZE: If this parameter is TRUE then monochrome DDB is created from 1bpp HIGEAR image. Otherwise, a compatible bitmap to the current display is created.
  • IG_DISPLAY_OPTION_OFFSCREEN_WIDTH/IG_DISPLAY_OPTION_OFFSCREEN_HEIGHT: Default values (0, 0) means that GetDeviceCaps(hDC,HORZRES) / GetDeviceCaps(hDC,VERTRES) will be used, respectively. These options specify the size of offscreen drawing surface. Set it to the size of a single monitor. In case of a dual monitor system you need to set IG_DISPLAY_OPTION_OFFSCREEN_WIDTH / IG_DISPLAY_OPTION_OFFSCREEN_HEIGHT to the total size of your dual monitor screen.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR		 hIGear;			/* HIGEAR handle of image */
IG_display_option_set( hIGear, IG_DISPLAY_OPTION_DOWNSHIFT,
(LPVOID)0, NULL);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_display_transparent_get

Group: Display

Declaration:

AT_ERRCOUNT EXPORT ACCUAPI IG_display_transparent_get(
    HIGEAR hIGear,
    LPAT_RGB lpRGB,
    LPAT_BOOL lpEnabled
);

Arguments:

hIGear
HIGEAR handle of image.
lpRGB
Returns the RGB color values through which transparency is currently set.
lpEnabled
Returns current condition of transparency: TRUE - transparency enabled, FALSE - transparency disabled.

Description:

Use this function to get image transparent color.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_display_transparent_set

Group: Display

Declaration:

AT_ERRCOUNT EXPORT ACCUAPI IG_display_transparent_set(
    HIGEAR hIGear,
    LPAT_RGB lpRGB,
    LPAT_BOOL lpEnabled
);

Arguments:

hIGear
HIGEAR handle of image.
lpRGB
Provide the RGB color values through which transparency have to be set.
lpEnabled
Enables or disablesd image transparency: TRUE - transparency enabled, FALSE - transparency disabled.

Description:

Use this function to set image transparent color. You have to use this API to write out a file with a transparency color set. For example when save image transparency information to a GIF file format.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_double_matrix_column_count_get

Group: Image Processing

Declaration:

AT_INT ACCUAPI IG_double_matrix_column_count_get(
    HIGDoubleMatrix DoubleMatrix
);

Parameters:

DoubleMatrix
HIGDoubleMatrix object

Description:

Returns number of columns in the matrix.

Return value:

Number of columns in the matrix.


IG_double_matrix_create

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_double_matrix_create(
    AT_INT RowCount,
    AT_INT ColCount,
    HIGDoubleMatrix *lpDoubleMatrix
);

Parameters:

RowCount
Number of rows
ColCount
Number of columns
lpDoubleMatrix
Returns new HIGDoubleMatrix object

Description:

Creates an HIGDoubleMatrix object with specified dimensions.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_double_matrix_create_values

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_double_matrix_create_values(
    AT_INT RowCount,
    AT_INT ColCount,
    AT_DOUBLE *lpValues,
    HIGDoubleMatrix *lpDoubleMatrix
);

Parameters:

RowCount
Number of rows
ColCount
Number of columns
lpValues
Array of RowCount*ColCount double values to initialize the matrix with.
lpDoubleMatrix
Returns new HIGDoubleMatrix object

Description:

Creates an HIGDoubleMatrix object with specified dimensions and values.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_double_matrix_delete

Group: Image Processing

Declaration:

AT_VOID ACCUAPI IG_double_matrix_delete(
    HIGDoubleMatrix DoubleMatrix
);

Parameters:

DoubleMatrix
HIGDoubleMatrix object to delete.

Description:

Deletes an HIGDoubleMatrix object.


IG_double_matrix_item_get

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_double_matrix_item_get(
    HIGDoubleMatrix DoubleMatrix,
    AT_INT Row,
    AT_INT Column,
    AT_DOUBLE *lpValue
);

Parameters:

DoubleMatrix
HIGDoubleMatrix object
RowCount
Row index
ColCount
Column index
lpValue
Returns element value

Description:

Returns element of the double matrix at the specified row and column indices.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_double_matrix_item_set

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_double_matrix_item_set(
    HIGDoubleMatrix DoubleMatrix,
    AT_INT Row,
    AT_INT Column,
    AT_DOUBLE Value
);

Parameters:

DoubleMatrix
HIGDoubleMatrix object
RowCount
Row index
ColCount
Column index
Value
New value of the matrix element

Description:

Sets element of the double matrix at the specified row and column indices.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_double_matrix_row_count_get

Group: Image Processing

Declaration:

AT_INT ACCUAPI IG_double_matrix_row_count_get(
    HIGDoubleMatrix DoubleMatrix
);

Parameters:

DoubleMatrix
HIGDoubleMatrix object

Description:

Returns number of rows in the matrix.

Return value:

Number of rows in the matrix.


IG_dspl_antialias_get

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_antialias_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPAT_MODE lpnAliasFlags,
    [OUT] LPUINT lpnThreshold
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group from which to get option.
lpnAliasFlags
Pointer to where AliasMode is to be received. If NULL, then this parameter is ignored.
lpnThreshold
Pointer to where ThresholdValue is to be received. If NULL, then this parameter is ignored.

Description:

This function returns the current anti-alias settings. Possible values are listed in the description of the IG_dspl_antialias_set () function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;     /* HIGEAR handle of image  */
DWORD		nGrpID;     /* display group identifier */
AT_MODE nAliasFlags; /* alias flags  */
UINT		nThreshold;  /* alias threshold */
 ...
IG_dspl_antialias_get( hIGear, nGrpID, &nAliasFlags,
&nThreshold );
 ...

Sample: MFC, TIMING, FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_antialias_get_ex

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_antialias_get_ex(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPAT_MODE lpnAliasFlags,
    [OUT] LPUINT lpnThreshold
    [OUT] LPUINT lpnQuality
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group from which to get option.
lpnAliasFlags
Pointer to where AliasMode is to be received. If NULL, then this parameter is ignored.
lpnThreshold
Pointer to where ThresholdValue is to be received. If NULL, then this parameter is ignored.
lpnQuality
Pointer to where color antialiasing quality value is to be received. If NULL, then this parameter is ignored.

Description:

This function returns the current anti-alias settings. Possible values are listed in the description of the IG_dspl_antialias_set_ex () function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;     /* HIGEAR handle of image  */
DWORD		nGrpID;     /* display group identifier */
AT_MODE nAliasFlags; /* alias flags  */
UINT		nThreshold;  /* alias threshold */
UINT nQuality /*alias quality */
 ...
IG_dspl_antialias_get_ex( hIGear, nGrpID, &nAliasFlags,
&nThreshold, &nQuality);
 ...

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_antialias_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_antialias_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] AT_MODE nAliasFlags,
    [IN] INT nThreshold
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group in which to set option.
nAliasFlags
New value of AliasMode to set. Possible value is one from this list:
IG_DSPL_ANTIALIAS_NONE
IG_DSPL_ANTIALIAS_SCALE_TO_GRAY
IG_DSPL_ANTIALIAS_PRESERVE_BLACK
IG_DSPL_ANTIALIAS_PRESERVE_WHITE
with OR combination of one additional flag
IG_DSPL_ANTIALIAS_SUBSAMPLE
nThreshold
Specifies display aliasing threshold level (AliasThreshold). Please see Dithering, Anti-aliasing, and Palette Handling.

Description:

This function sets new anti-alias settings.

Bits Per Pixel: 1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;     /* HIGEAR handle of image  */
DWORD		nGrpID;     /* display group identifier */
 ...
/* sets scale to gray algorithm with subsampling  */
IG_dspl_antialias_set( hIGear, nGrpID,
IG_DSPL_ANTIALIAS_SCALE_TO_GRAY| IG_DSPL_ANTIALIAS_SUBSAMPLE,
50 );
 ...

Sample: MFC, TIMING, FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_antialias_set_ex

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_antialias_set_ex(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] AT_MODE nAliasFlags,
    [IN] INT Threshold,
    [IN] INT nColorQuality
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group in which to set option.
nAliasFlags
New value of AliasMode to set. It is an OR combination of following elements:
  • Scale-Up interpolation (resampling)
  • Scale-Down interpolation (antialiasing)
For 1 bit images antialiasing element is a one of constants:
  • IG_DSPL_ANTIALIAS_NONE
  • IG_DSPL_ANTIALIAS_SCALE_TO_GRAY
  • IG_DSPL_ANTIALIAS_PRESERVE_BLACK
  • IG_DSPL_ANTIALIAS_PRESERVE_WHITE
with OR combination of one additional flag
IG_DSPL_ANTIALIAS_SUBSAMPLE
Antialising for all non-1bit color spaces is activated with the IG_DSPL_ANTIALIAS_COLOR flag.
Scale-Up interpolation for all non-1bit color spaces is specified by the IG_DSPL_ANTIALIAS_RESAMPLE_BILINE flag.
nThreshold
It indicates the threshold value of the amount of selected color to include for IG_DSPL_ANTIALIAS_PRESERVE_XXXX scale-down interpolations. Please see Dithering, Anti-aliasing, and Palette Handling.
nColorQuality
Specifies quality of color scale-down interpolation (antialiasing). Valid values are from 0 to 100 and specify the percent of image pixels taken into account to produce one display pixel. Zero value means automatic quality choice according with image resolution and display settings.

Description:

This function sets new anti-alias settings.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;     /* HIGEAR handle of image  */
DWORD		nGrpID;     /* display group identifier */
 ...
/* sets scale to gray algorithm with subsampling  */
IG_dspl_antialias_set_ex( hIGear, nGrpID,
IG_DSPL_ANTIALIAS_SCALE_TO_GRAY| IG_DSPL_ANTIALIAS_SUBSAMPLE,
50, 80);
 ...

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_artx_DDB_create

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_artx_DDB_create(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HIG_ART_PAGE hArtXPage,
    [IN] HDC hDC,
    [IN] AT_DIMENSION nWidth,
    [IN] AT_DIMENSION nHeight,
    [IN] BOOL bExport,
    [OUT] HBITMAP FAR* lphBitmap,
    [OUT] HPALETTE FAR* lphPalette
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group in which the options are stored
hArtXPage
ImageGear handle to the ArtX annotation page.
hDC
Handle of device context that the DDB should be compatible with. If NULL then the DDB will be compatible with the desktop's device context.
nWidth
Width of DDB that is to be created.
nHeight
Height of DDB that is to be created.
bExport
Boolean parameter which specifies whether to delete the source image or not. If TRUE then the hIGear image will be deleted after the DDB is created, but if FALSE then the image is left unchanged.
lphBitmap
Pointer to where to return the DDB object.
lphPalette
Pointer to where to return the palette handle for this DDB.

Description:

This function creates a DDB of the image and ArtX annotations. It always uses all the display options specified by dwGrpID group and assumes that the output device has a color format compatible with the hDC, but the client area of the output device is a rectangle of nWidth x nHeight size. For 1 bit per pixel images, bit depth of the resulting DDB depends on anti-aliasing settings. If anti-aliasing is turned off, the resulting DDB has 1 bit per pixel, otherwise its bit depth is equal to the hDC bit depth.

Example:

HIGEAR		hIGear;    /* HIGEAR handle of image  */
DWORD		nGrpID;     /* display group identifier */
HIG_ARTX_PAGE  hArtXPage;    /* Handle of ArtX page  */
HBITMAP hBitmap;    /* handle of bitmap  */
HPALETTE hPalette;   /* handle of palette */
 ...
case ID_IMAGE_EXPORT:
     ...
IG_dspl_artx_DDB_create( hIGear, nGrpID, hArtXPage, NULL, 640,
480, TRUE,
&hBitmap, &hPalette );
     ...
    break;
 ...


IG_dspl_artx_image_draw

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_artx_image_draw(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] LPVOID hArtXPage,
    [IN] HWND hWnd,
    [IN] HDC hDC,
    [OUT] LPAT_RECTANGLE lpActualDeviceRect
);

Arguments:

hIGear
ImageGear handle from which to get options and pixel data
dwGrpID
Identifier of group from which to get display options
hArtXPage
ArtX page to display.
hWnd
Handle of window where the image is to be displayed. Can be NULL, but in this case some display options may be calculated incorrectly if they are not set explicitly.
hDC
Handle of the device context on which to draw the image. Can be NULL, and in this case no actual drawing is performed but all parameters are calculated and updated. This may be useful in calculating DisplayedImageRect in the next parameter of this function.
lpActualDeviceRect
Pointer to the rectangle in which to copy DisplayedImageRect. This rectangle is calculated no matter whether hDC=NULL or not. If the value is NULL, then this parameter is ignored.

Description:

This function acts like IG_dspl_image_draw () but takes one extra parameter hArtXPage.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: ARTX

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_artx_image_print

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_artx_image_print(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] LPVOID hArtXPage,
    [IN] HDC hDC,
    [IN] BOOL bDirectToDriver
);

Arguments:

HIGear
ImageGear handle of image.
DwGrpID
Identifier of group from which to get image options
hArtXPage
ArtX page to print.
hDC
Handle of device context on which to draw the image.
bDirectToDriver
If TRUE then IG does not perform image scaling but use the operating system's and driver's capabilities for this. If FALSE then ImageGear performs the scaling.

Description:

This function acts like IG_dspl_image_print () function but takes one extra parameter hArtXPage.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Samples: ARTX

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_artx_page_print

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI IG_dspl_artx_page_print(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] LPVOID hArtXPage,
    [IN] HDC hDC,
    [IN] const LPAT_DRECTANGLE lpLayout,
    [IN] BOOL bDirectToDriver
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group from which to get printing options.
hArtXPage
ArtX page to print.
hDC
Handle of printer device context on which to draw the image.
lpLayout
Rectangle which specifies how the image is located on the page. This rectangle is calculated in page-relative units, and as actual page resolutions are obtained it translates the rectangle into real coordinates and assigns ClipRect according to the following rules:
ClipRect.x = lpLayout->x*nPageWidth
ClipRect.y = lpLayout->y*nPageHeight
ClipRect.width = lpLayout->width*nPageWidth
ClipRect.height = lpLayout->height*nPageHeight
bDirectToDriver
If TRUE then ImageGear does not perform image scaling but uses the operating system's and driver's capabilities for this. If FALSE then ImageGear performs the scaling.

Description:

This function acts like IG_dspl_page_print () but takes one extra parameter hArtXPage.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: ARTX

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_background_get

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_background_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPAT_MODE lpnBkMode,
    [OUT] LPAT_RGB lpBkColor,
    [OUT] HBITMAP FAR* lphBrush
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of the group to use.
lpnBkMode
Pointer to where BkMode options are returned. If NULL, then this parameter is ignored.
lpBkColor
Pointer to where BkColor option is returned. If NULL, then this parameter is ignored.
lphBrush
Pointer to where BkBrush option is returned. If NULL, then this parameter is ignored.

Description:

This function returns the background settings' current values. Possible values are listed in the description of function IG_dspl_background_set ().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;      /* HIGEAR handle of image  */
DWORD		nGrpID;      /* display group identifier */
AT_MODE nBkMode;    /* backgound mode  */
AT_RGB BkColor;    /* background color  */
HBITMAP hBrush;     /* background mask  */
 ...
IG_dspl_background_get( hIGear, nGrpID, &nBkMode, &BkColor,
&hBrush );
 ...

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_background_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_background_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] AT_MODE nBkMode,
    [IN] const LPAT_RGB lpBkColor,
    [IN] HBITMAP hBrush
);

Arguments:

hIGear
ImageGear handle of image
dwGrpID
Identifier of the group in which to set options.
nBkMode
IG_DSPL_BACKGROUND_NONE or a combination of the following flags:
IG_DSPL_BACKGROUND_UNDER_IMAGE
IG_DSPL_BACKGROUND_BEYOND_IMAGE
lpBkColor
New value of BkColor to set. If NULL, then this parameter is ignored.
hBrush
New value of BkBrush option to set. Please note that the old bitmap is not deleted and the application code is responsible for removing the old value of this option.

Description:

This function sets the background settings.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;    /* HIGEAR handle of image  */
DWORD		nGrpID;  /* display group identifier  */
 ...
/* disable background under image and beyond image  */
IG_dspl_background_set( hIGear, nGrpID,
IG_DSPL_BACKGROUND_NONE, NULL, NULL );
 ...

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_channel_visibility_get

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_channel_visibility_get(
    HIGEAR hIGear,
    DWORD dwGrpID,
    AT_INT nIndex,
    LPAT_BOOL lpbVisible
);

Parameters:

hIGear
Image handle.
dwGrpID
Display group ID.
nIndex
Index of the requested channel (up to 64).
lpbVisible
Visibility state.

Description:

This method gets the visibility state of the specified channel in the image. TRUE - image channel is visible, FALSE - otherwise.


IG_dspl_channel_visibility_set

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_channel_visibility_set(
    HIGEAR hIGear,
    DWORD dwGrpID,
    AT_INT nIndex,
    AT_BOOL bVisible
);

Parameters:

hIGear
Image handle.
dwGrpID
Display group ID.
nIndex
Index of the channel to set new visibility state (up to 64).
bVisible
New visibility state.

Description:

This method sets the new visibility state for the specified channel in the image. TRUE - image channel is visible, FALSE - otherwise.


IG_dspl_DDB_create

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_DDB_create(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HDC hDC,
    [IN] AT_DIMENSION nWidth,
    [IN] AT_DIMENSION nHeight,
    [IN] BOOL bExport,
    [OUT] HBITMAP FAR* lphBitmap,
    [OUT] HPALETTE FAR* lphPalette
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group in which the options are stored
hDC
Handle of device context that the DDB should be compatible with. If NULL then the DDB will be compatible with the desktop's device context.
nWidth
Width of DDB that is to be created.
nHeight
Height of DDB that is to be created.
bExport
Boolean parameter which specifies whether to delete the source image or not. If TRUE then the hIGear image will be deleted after the DDB is created, but if FALSE then the image is left unchanged.
lphBitmap
Pointer to where to return the DDB object.
lphPalette
Pointer to where to return the palette handle for this DDB.

Description:

This function creates a DDB of the image. It always uses all the display options specified by dwGrpID group and assumes that the output device has a color format compatible with the hDC, but the client area of the output device is a rectangle of nWidth x nHeight size. For 1 bit per pixel images, bit depth of the resulting DDB depends on anti-aliasing settings. If anti-aliasing is turned off, the resulting DDB has 1 bit per pixel, otherwise its bit depth is equal to the hDC bit depth.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;    /* HIGEAR handle of image  */
DWORD		nGrpID;     /* display group identifier */
HBITMAP hBitmap;    /* handle of bitmap  */
HPALETTE hPalette;   /* handle of palette */
 ...
case ID_IMAGE_EXPORT:
     ...
IG_dspl_DDB_create( hIGear, nGrpID, NULL, 640, 480, TRUE,
&hBitmap, &hPalette );
     ...
    break;
 ...

Sample: DISPLAY, IMGUTIL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_DDB_draw

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI IG_dspl_DDB_draw(
    [IN] HWND hWnd,
    [IN] HDC hDC,
    [IN] HBITMAP hBitmap,
    [IN] HPALETTE hPalette,
    [IN] AT_PIXPOS x,
    [IN] AT_PIXPOS y
);

Arguments:

hWnd
Handle of window to be used. Can be NULL if not available.
hDC
Handle of device context in which to draw.
hBitmap
Device dependent bitmap in OS-dependent format in which to draw.
hPalette
Handle of palette which should be realized before drawing.
x
Horizontal position of left top corner of bitmap on the destination device.
y
Vertical position of left top corner of bitmap on the destination device.

Description:

This function draws a DDB image on the device. If hPalette!=NULL then the palette is selected and realized first.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HBITMAP hBitmap;     /* bitmap to draw  */
HPALETTE hPalette;    /* associated palette handle  */
 ...
case WM_PAINT:
    BeginPaint(hWnd, &ps);
    IG_dspl_DDB_draw( hWnd, ps.hdc, hBitmap, hPalette, 0, 0 );
    EndPaint(hWnd, &ps);
    break;
 ...

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_DDB_import

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_DDB_import(
    [IN] HDC hDC,
    [IN] HBITMAP hBitmap,
    [IN] HPALETTE hPalette,
    [OUT] LPHIGEAR lphIGear
);

Arguments:

hDC
Handle of device context that the DDB is compatible with. If NULL then it is assumed that the DDB is compatible with the desktop's device context.
hBitmap
Handle of DDB object that image should be created from.
hPalette
Handle of palette that should be realized before drawing the DDB.
lphIGear
Pointer to where to return the newly allocated image handle.

Description:

This function creates an image from the DDB object. If the color format of the DDB is not supported directly by ImageGear then it is converted to the nearest supported format with a minimal possible loss of color quality.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HBITMAP hBitmap;      /* handle of bitmap  */
HPALETTE hPalette;     /* handle of palette  */
HIGEAR hIGear;       /* HIGEAR handle of image  */
 ...
case ID_IMAGE_IMPORT:
     ...
IG_dspl_DDB_import( NULL, hBitmap, hPalette, &hIGear );
     ...
    break;
 ...

Sample: DISPLAY, IMGUTIL, Recognition

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_device_to_image

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_device_to_image(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] HDC hDC,
    [IN/OUT] LPAT_POINT lpPoint,
    [IN] UINT nCount
);

Arguments:

hIGear
ImageGear handle of image.
DwGrpID
Identifier of the group from which to get the display options.
HWnd
Handle of the window where the image is drawn.
HDC
Handle of the device context used for drawing. This can be NULL, but if a calculation is necessary for a printer device context, then you should provide the real value.
LpPoint
Pointer to an array of points that should be translated.
NCount
Number of elements in the lpPoint array.

Description:

This function translates an array of points from device coordinates to image coordinates. It takes into account all display parameters including orientation and current scrolling position.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* HIGEAR handle of image  */
DWORD		nGrpID;     /* display group identifier  */
AT_POINT p[2];       /* array of point to translate  */
RECT		rc;
 ...
/* calculate coordinates in image coordinate space of current
client rectangle of the window */
GetClientRect( hWnd, &rc );
p[0].x = rc.left;
p[0].y = rc.top;
p[1].x = rc.right;
p[1].y = rc.bottom;
IG_dspl_device_to_image( hIGear, nGrpID, hWnd, NULL, p, 2 );
 ...

Sample: IMG_PROC, CLPBRD, Recognition

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_device_to_image_d

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_device_to_image_d(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] HDC hDC,
    [IN/OUT] LPAT_DPOINT lpPoint,
    [IN] UINT nCount
);

Arguments:

hIGear
ImageGear handle of image.
DwGrpID
Identifier of the group from which to get display options.
HWnd
Handle of the window from which the image is drawn.
HDC
Handle of the device context used for drawing. This can be NULL, but if a calculation is necessary for printer device contex,t then you should provide the real value.
LpPoint
Pointer to an array of points in DOUBLE float-point format that should be translated.
NCount
Number of elements in the lpPoint array.

Description:

This function translates an array of points in DOUBLE float-points format from the device coordinates to the image coordinates. It takes into account all display parameters, including the orientation and current scrolling position.

NOTE: See also the function IG_dspl_image_to_device_d().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_dithering_get

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_dithering_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPAT_MODE lpnDitherFlags
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group from which to get option.
lpnDitherFlags
Pointer where DitherMode is to be received.

Description:

This function returns the current dithering flags. All possible values are listed in the description of function IG_dspl_dithering_set ().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;    /* HIGEAR handle of image  */
DWORD		nGrpID;    /* display group identifier */
AT_MODE nDitherFlags; /* dither flags */
 ...
IG_dspl_dithering_get( hIGear, nGrpID, &nDitherFlags );
 ...

Sample: MFC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_dithering_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI   IG_dspl_dithering_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] AT_MODE nDitherFlags
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group from which to set dithering.
nDitherFlags
New value of DitherMode to set. Possible values include:
IG_DSPL_DITHER_AUTO
IG_DSPL_DITHER_TO_8BPP
IG_DSPL_DITHER_TO_4BPP
IG_DSPL_DITHER_TO_1BPP
IG_DSPL_DITHER_NONE
with OR combination from two flags
IG_DSPL_DITHER_FIXED_PALETTE
IG_DSPL_DITHER_NETSCAPE_PALETTE

Description:

This function sets new dithering options.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	hIGear;    /* HIGEAR handle of image */
DWORD	nGrpID;    /* display group identifier  */
 ...
/* if device is palette based then dither to fixed palette */
IG_dspl_dithering_set( hIGear, nGrpID, IG_DSPL_DITHER_AUTO|
IG_DSPL_DITHER_FIXED_PALETTE );
 ...

Sample: MFC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_document_print

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_document_print(
    [IN] const LPHIGEAR lphIGear,
    [IN] UINT nImageCount,
    [IN] DWORD dwGrpID,
    [IN] HDC hDC,
    [IN] UINT nImagesPerWidth,
    [IN] UINT nImagesPerHeight,
    [IN] DOUBLE dblXSpace,
    [IN] DOUBLE dblYSpace,
    [IN] BOOL bDirectToDriver,
    [IN] LPFNIG_IMAGESPOOLED lpfnImageSpooled,
    [IN] LPVOID lpPrivateData
);

Arguments:

lphIGear
Array of ImageGear image handles to print.
nImageCount
Number of elements in lphIGear array.
dwGrpID
Identifier of group from which to get options for printing for each image.
hDC
Handle of printer device context on which to draw images.
nImagesPerWidth
Number of images that should be placed in row.
nImagesPerHeight
Number of images that should be placed in column.
dblXSpace
Horizontal destination between images in row in page's width relative coordinates. This means the actual destination in device coordinates is calculated as:
xSpace = PageWidth*dblXSpace.
dblYSpace
Vertical destination between images in column in page's height relative coordinates. This means the actual destination in device coordinates is calculated as:
ySpace = PageHeight*dblYSpace.
bDirectToDriver
If TRUE then IG does not perform image scaling but uses the operating system's and driver's capabilities for this. If FALSE then ImageGear performs the scaling.
lpfnImageSpooled
Callback function that will be called after each image is printed.
lpPrivateData
Private data that will be passed to lpfnImageSpooled callback function in first parameter.

Description:

This function allows you to print an array of images and specify the number of images per width (row) and per height (column) of the page. lpfnImageSpooled function will be called after each image is printed and can use the lpPrivateData parameter as private data storage. bDirectToDriver parameter allows you to perform image scaling inside of ImageGear or leave this task to the printer driver and operating system. Usually, direct to driver printing (bDirectToDriver=TRUE) results in smaller output size and it works faster but not using it produces better quality and allows you to use such IG capabilities as anti-aliasing during printing.

NOTE: Special predefined option group IG_GRP_DEFAULT_PRINT can be used to print an image with the most common parameters.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR lphIGear[10]; /* array of HIGEAR handles of images  */
DWORD nGrpID;       /* display group identifier  */
BOOL bDirect;  /* direct to driver flag  */
PRINTDLG pd;      /* print dialog structure  */
INT nPrivateInfo;
 ...
case ID_FILE_PRINT:
     ...
    if( PrintDlg(&pd) )
    {
 ...
IG_dspl_document_print( lphIGear, 10, nGrpID, pd.hDC, 2, 3,
0.05, 0.05, bDirect, ImageSpooled, &nPrivateInfo );
 ...
    }
     ...
    break;
 ...
BOOL ACCUAPI  ImageSpooled(
    LPVOID   lpPrivate,  /* Private data passed in */
    UINT      nImageNumber, /* Current image being spooled (1
based) */
    UINT     nPageNumber   /* Current page number being spooled
*/
    )
{
     ...
    return TRUE;   /* return false to cancel printing */
}
 ...

Sample: DISPLAY, PRINT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_document_print_custom

Group: Display

Declaration:

AT_ERRCOUNT    ACCUAPI    IG_dspl_document_print_custom(
    [IN] const LPHIGEAR lphIGear,
    [IN] UINT nImageCount,
    [IN] DWORD dwGrpID,
    [IN] HDC hDC,
    [IN] UINT nImagesPerPage,
    [IN] const LPAT_DRECTANGLE lpImagesLayout,
    [IN] BOOL bDirectToDriver,
    [IN] LPFNIG_IMAGESPOOLED lpfnImageSpooled,
    [IN] LPVOID lpPrivateData
);

Arguments:

lphIGear
Array of ImageGear image handles to print.
nImageCount
Number of elements in lphIGear array.
dwGrpID
Identifier of group from which to get the options for printing for each image.
hDC
Handle of printer device context on which to draw the images.
nImagesPerPage
Number of images that should be placed in a single page.
lpImagesLayout
Array of length nImagesPerPage of rectangles where an i-th rectangle specifies how the i-th image of this page is located on that page. Each rectangle is calculated in page-relative units, and as the actual page resolutions are obtained, it translates the rectangles into real coordinates and assigns values to ClipRect according to the following rules:
ClipRect.x = lpLayout[i].x*nPageWidth
ClipRect.y = lpLayout[i].y*nPageHeight
ClipRect.width = lpLayout[i].width*nPageWidth
ClipRect.height = lpLayout[i].height*nPageHeight
bDirectToDriver
If TRUE then IG does not perform image scaling but uses the operating system's and driver's capabilities for this. If FALSE then ImageGear performs the scaling.
lpfnImageSpooled
Callback function that will be called after each image is printed.
lpPrivateData
Private data that will be passed to the lpfnImageSpooled callback function in the first parameter.

Description:

This function allows you to print an array of images and customize each image's layout on the page. lpfnImageSpooled function will be called after each image is printed and you can use the lpPrivateData parameter as private data storage. bDirectToDriver parameter allows you to perform image scaling inside of ImageGear or leave this task to the printer driver and operating system. Usually, direct to driver printing (bDirectToDriver=TRUE) results in smaller output size and it works faster, but not using it produces better quality and allows you to use such IG capabilities as anti-aliasing during printing.

NOTE: Special predefined option group IG_GRP_DEFAULT_PRINT can be used to print an image with the most common parameters.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		lphIGear[10];  /* array of HIGEAR handles of images */
DWORD		nGrpID;        /* display group identifier  */
BOOL		bDirect;        /* direct to driver flag  */
AT_DRECTANGLE
        Layout[2];   /* array describes image layout on single
page */
PRINTDLG		pd;         /* print dialog structure   */
INT		nPrivateInfo;
 ...
case ID_FILE_PRINT:
     ...
    if( PrintDlg(&pd) )
    {
 ...
/* place one page at the left top of the page              */
Layout[0].x = 0.01; Layout[0].y = 0.01;
Layout[0].width = 0.48; Layout[0].height = 0.48;
/* and second page at the right bottom                     */
Layout[1].x = 0.51; Layout[1].y = 0.51;
Layout[1].width = 0.48; Layout[1].height = 0.48;
IG_dspl_document_print_custom( lphIGear, 10, nGrpID, pd.hDC, 2,
Layout, bDirect, ImageSpooled, &nPrivateInfo );
    }	 ...
    break; ...
BOOL	ACCUAPI  ImageSpooled(
    LPVOID   lpPrivate,      /* Private data passed in   */
    UINT     nImageNumber, /* Current image being spooled (1
based) */
    UINT     nPageNumber  /* Current page number being spooled
*/
    )
{	 ...
    return  TRUE;   /* return false to cancel printing  */
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_foreground_get

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI   IG_dspl_foreground_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPAT_RGB lpFrColor
);

Arguments:

hIGear
The ImageGear handle of an image.
dwGrpID
Identifier of the group to use.
lpFrColor
Pointer to where the FrColor option is returned. If NULL, then this parameter is ignored.

Description:

This function returns the foreground color.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;        /* HIGEAR handle of image   */
DWORD nGrpID;        /* display group identifier  */
AT_RGB FrColor;       /* foreground color  */
 ...
IG_dspl_foreground_get( hIGear, nGrpID, &FrColor );
 ...

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_foreground_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_foreground_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] const LPAT_RGB lpFrColor
);

Arguments:

hIGear
ImageGear handle of an image
dwGrpID
Identifier of the group in which to set options.
lpFrColor
The new value of FrColor to set. If NULL, then this parameter is ignored.

Description:

This function sets the foreground color.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;     /* HIGEAR handle of image   */
DWORD		nGrpID;      /* display group identifier  */
AT_RGB		FrColor;
 ...
FrColor.r = FrColor.g = FrColor.b;
IG_dspl_foreground_set( hIGear, nGrpID, &FrColor );
...

Samples: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_free_grp_id_get

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_free_grp_id_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwMin,
    [OUT] LPDWORD lpdwFreeGrpId
);

Arguments:

hIGear
ImageGear handle of image.
dwMin
Minimum value that IG should start to search from.
lpdwFreeGrpId
Pointer to where to return free group identifier.

Description:

This function searches and returns the first free unused group identifier. It also sets a flag so the returned group is marked as used and the next call to this function with the same parameters returns another group id. To mark a group as unused and reset it to the default values call function IG_dspl_grp_reset ().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;   /* HIGEAR handle of image   */
DWORD nGrpID;   /* display group identifier  */
 ...
IG_dspl_free_grp_id_get( hIGear, 0, &nGrpID );
 ...

Samples: DISPLAY, MFC, PRINT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_gamma_correction_LUT_build

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_gamma_correction_LUT_build(
    [IN] DOUBLE dblContrast,
    [IN] DOUBLE dblBrightness,
    [IN] DOUBLE dblGamma,
    [OUT] LPBYTE lpLUT
);

Arguments:

dblContrast
Contrast value to use in calculations. You can use any value.
dblBrightness
Brightness value to use in calculations. Must be within the -255.0 to +255.0 range.
dblGamma
Gamma value to use in calculations. Must be greater than 0.0, however the most useful values are in the range from 1.8 to 2.2.
lpLUT
Pointer to 256 byte array in which to calculate the lookup table.

Description:

This function builds lookup tables from given contrast, brightness and gamma values.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

BYTE lut[256];    /* lookup array  */
 ...
IG_dspl_gamma_correction_LUT_build( 2.0, 120.0, 2.0, lut );

Sample: MFC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_gamma_correction_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_gamma_correction_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] AT_MODE nFlags,
    [IN] DOUBLE dblContrast,
    [IN] DOUBLE dblBrightness,
    [IN] DOUBLE dblGamma
);

Arguments:

hIGear
ImageGear handle of image
dwGrpID
Identifier of group in which to set lookup tables.
nFlags
Specify which lookup tables to set. Possible values are 0 or a combination of these flags:
IG_DSPL_R_CHANNEL - if this flag is set then the RedLut option is to be set.
IG_DSPL_G_CHANNEL - if this flag is set then the GreenLut option is to be set.
IG_DSPL_B_CHANNEL - if this flag is set then the BlueLut option is to be set.
The constant IG_DSPL_ALL_CHANNELS is defined for convenience and can be used to set all three options.
#define IG_DSPL_ALL_CHANNELS
(IG_DSPL_R_CHANNEL|IG_DSPL_G_CHANNEL|I
G_DSPL_B_CHANNEL)
dblContrast
Contrast value to use in calculations. You can use any value.
dblBrightness
Brightness value to use in calculations. Must be in the range from -255.0 to +255.0.
dblGamma
Gamma value to use in calculations. Must be greater than 0.0; however the most useful values are in the range from 1.8 to 2.2.

Description:

This function takes contrast (dblContrast), brightness (dblBrightness) and gamma (dblGamma) parameters and calculates lookup tables accordingly and sets them into the corresponding options.

All lookup tables specified in the nFlags parameter are initialized with the same value based on the dblContrast, dblBrightness, and dblGamma values.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;    /* HIGEAR handle of image  */
DWORD		nGrpID;    /* display group identifier */
 ...
IG_dspl_gamma_correction_set( hIGear, nGrpID,
IG_DSPL_ALL_CHANNELS, 2.0, 120.0, 2.0 );
 ...

Sample: MFC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_grayscale_LUT_copy_get

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_grayscale_LUT_copy_get(
    HIGEAR hIGear,
    DWORD dwGrpID,
    HIGLUT *lpLUT
);

Arguments:

hIGear
ImageGear handle.
dwGrpID
Display group ID.
lpLUT
New LUT handle.

Description:

This function returns a copy of display grayscale LUT, if it exists in the specified display settings group.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

None


IG_dspl_grayscale_LUT_exists

Group: Display

Declaration:

AT_BOOL ACCUAPI IG_dspl_grayscale_LUT_exists(
    HIGEAR hIGear,
    DWORD dwGrpID
);

Arguments:

hIGear
HIGEAR handle.
dwGrpID
Display group ID.

Description:

This function checks whether the display settings group has a grayscale LUT attached.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

None


IG_dspl_grayscale_LUT_update_from

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_grayscale_LUT_update_from(
    HIGEAR hIGear,
    DWORD dwGrpID,
    HIGLUT lut
);

Arguments:

hIGear
HIGEAR handle.
dwGrpID
Display group ID.
lut
LUT handle.

Description:

This function updates (creates if not present) a grayscale LUT for the image display.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: Medical

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_grp_reset

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_grp_reset(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group to reset.

Description:

This function resets all the options of the specified group to its default values. Please note the application code is responsible for freeing memory allocated for options such as TranspMask and BkBrush. This function does not free it.

This function also removes the flag that marks this group as "used." It may be set again by any display function that specifies using this group identifier.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
DWORD nGrpID; /* display group identifier */
...
IG_dspl_grp_reset( hIGear, nGrpID );
...

Sample: DISPLAY, PRINT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_image_calc

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_image_calc(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] HDC hDC,
    [OUT] LPAT_RECTANGLE lpActualDeviceRect
);

Arguments:

hIGear
ImageGear handle from which to get options and pixel data
dwGrpID
Identifier of group from which to get display options
hWnd
Handle of window where image is to be displayed. Can be NULL, but in this case some display options may be calculated incorrectly if they are not set explicitly.
hDC
Handle of the device context where image is to be drawn.
lpActualDeviceRect
Pointer to the rectangle in which to copy DisplayedImageRect. This rectangle is calculated no matter whether hDC=NULL or not. If NULL, then this parameter is ignored.

Description:

This function calculates DisplayedImageRect, which is the exact rectangle in which the image is to be scaled. All options for drawing the image are taken from the dwGrpID group. This function does not perform any drawing, whether hDC is NULL or not.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR			hIGear;		/* HIGEAR handle of image 					*/
DWORD			nGrpID;		/* Display group identifier					*/
AT_RECTANGLE			 DisplayedRect;
...
case WM_PAINT:
    BeginPaint(hWnd, &ps);
    if (IG_image_is_valid(hIGear))
        IG_dspl_image_calc( hIGear, nGrpID, hWnd, ps.hdc,
&DisplayedRect );
    EndPaint(hWnd, &ps);
    break;

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_image_draw

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_image_draw(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] HDC hDC,
    [OUT] LPAT_RECTANGLE lpActualDeviceRect
);

Arguments:

hIGear
ImageGear handle from which to get options and pixel data
dwGrpID
Identifier of group from which to get display options
hWnd
Handle of window where the image is to be displayed. Can be NULL, but in this case some display options may be calculated incorrectly if they are not set explicitly.
hDC
Handle of the device context on which to draw the image. Can be NULL, and in this case no actual drawing is performed but all parameters are calculated and updated. This may be useful in calculating DisplayedImageRect in the next parameter of this function.
lpActualDeviceRect
Pointer to the rectangle in which to copy DisplayedImageRect. This rectangle is calculated no matter whether hDC=NULL or not. If the value is NULL, then this parameter is ignored.

Description:

This function draws an image onto a destination device context. All options regarding how to draw the image are taken from the dwGrpID group. This function can also be used for the actual device rectangle calculation. If hDC=NULL then all parameters are calculated and updated but no actual drawing is performed.

NOTE: If you are using ImageGear ARTX component in your application please use IG_dspl_artx_image_draw() function.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;		/* HIGEAR handle of image 					*/
DWORD		nGrpID;		/* Display group identifier					*/
...
case WM_PAINT:
    BeginPaint(hWnd, &ps);
    if (IG_image_is_valid(hIGear))
        IG_dspl_image_draw( hIGear, nGrpID, hWnd, ps.hdc, NULL );
    EndPaint(hWnd, &ps);
    break;

Sample: ALL (besides GUIWIN, LoadCB & Shared)

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_image_print

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_image_print(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HDC hDC,
    [IN] BOOL bDirectToDriver
);

Arguments:

HIGear
ImageGear handle of image.
DwGrpID
Identifier of group from which to get image options
hDC
Handle of device context on which to draw the image.
bDirectToDriver
If TRUE then IG does not perform image scaling but use the operating system's and driver's capabilities for this. If FALSE then ImageGear performs the scaling.

Description:

This function draws an image onto the printer device context. Print resolution depends on the current printer setting. bDirectToDriver parameter allows you to either perform image scaling inside of ImageGear or leave this task to the printer driver and operating system. Usually, direct to driver printing (bDirectToDriver=TRUE) results in smaller output size and works faster, but not using it produces better quality and allows you to use IG capabilities such as anti-aliasing during printing.

NOTE: Special predefined option group IG_GRP_DEFAULT_PRINT can be used to print an image with the most common parameters.
NOTE: If you are using ImageGear ARTX component in your application please use IG_dspl_artx_image_print() function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;		/* HIGEAR handle of image 					*/
DWORD		nGrpID;		/* display group identifier					*/
BOOL		bDirect;		/* direct to driver flag					*/
PRINTDLG		 pd;		/* print dialog structure					*/
 ...
case ID_FILE_PRINT:
     ...
    if( PrintDlg(&pd) )
    {
 ...
IG_dspl_image_print( hIGear, nGrpID, pd.hDC, bDirect );
 ...
    }
     ...
    break;
 ...

Samples: PRINT, DISPLAY, MFC, POSTER, THREADS, ARTEXT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_image_to_device

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_image_to_device(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] HDC hDC,
    [IN/OUT] LPAT_POINT lpPoint,
    [IN] UINT nCount
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group from which to get display options.
hWnd
Handle of a window where the image is drawn.
hDC
Handle of the device context used for drawing. Can be NULL, but if it is necessary to perform a calculation for the printer device context, then a real value should be provided.
lpPoint
Pointer to an array of points that should be translated.
nCount
Number of elements in lpPoint array.

Description:

This function translates an array of pointers from image coordinates into device coordinates. It takes into account all display parameters including orientation and current scrolling position.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;		/* HIGEAR handle of image 					*/
DWORD		nGrpID;		/* display group identifier					*/
AT_POINT		 p[2];		/* array of point to translate 					*/
AT_RECTANGLE	 	ImageRect;		/* image rectangle					*/
 ...
/* calculates device coordinates of current image rectangle */
IG_dspl_layout_get( hIGear, nGrpID, &ImageRect, NULL, NULL,
NULL, NULL, NULL, NULL );
p[0].x = ImageRect.x;
p[0].y = ImageRect.y;
p[1].x = ImageRect.x + ImageRect.width - 1;
p[1].y = ImageRect.y + ImageRect.height - 1;
IG_dspl_image_to_device( hIGear, nGrpID, hWnd, NULL, p, 2 );
 ...

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_image_to_device_d

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_image_to_device_d(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] HDC hDC,
    [IN/OUT] LPAT_DPOINT lpPoint,
    [IN] UINT nCount
);

Arguments:

hIGear
ImageGear handle of an image.
dwGrpID
Identifier of the group from which to get display options.
hWnd
Handle of the window where the image is drawn.
hDC
Handle of the device context used for drawing. Can be NULL, but if it is necessary to perform a calculation for the printer device context, then a real value should be provided.
lpPoint
Pointer to an array of points in DOUBLE float-point format that should be translated.
nCount
Number of elements in the lpPoint array.

Description:

This function translates an array of points in DOUBLE float-point format from the image coordinates into device coordinates. It takes into account all display parameters, including orientation and current scrolling position.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

NOTE: See also IG_dspl_device_to_image_d() function.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_image_wipe

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_image_wipe(
    [IN] HIGEAR hIGearBefore,
    [IN] DWORD dwGrpBefore,
    [IN] HIGEAR hIGearAfter,
    [IN] DWORD dwGrpAfter,
    [IN] HWND hWnd,
    [IN] AT_MODE nWipeStyle,
    [IN] LONG nGranularity,
    [IN] LONG lTime
);

Arguments:

hIGearBefore
HIGEAR handle of an image in the window before the wipe.
dwGrpBefore
Display group identifier used for hIGearBefore.
hIGearAfter
HIGEAR handle of an image to be in window after the wipe.
dwGrpAfter
Display group identifier used for hIGearAfter.
hWnd
Window handle.
nWipeStyle
Transition style, such as IG_WIPE_LEFTTORIGHT. See below. (Check updates to accucnst.h for new wipe styles.)
nGranularity
Size of each square region, in pixels. A typical value is 5.
lTime
The time, in milliseconds, between wipes

Description:

This function changes the image in window hWnd from the hIGearBefore image to the hIGearAfter image. The transition is accomplished according to the nWipeStyle style. Before you call this function, the first image should already be in the window. This function will set the wipe style, and then generate a WM_PAINT message. The IG_dspl_image_draw () call while processing this WM_PAINT message will perform the transition to the new image. nWipeStyle Constants include:

IG_WIPE_LEFTTORIGHT
Left-to-Right Wipe.
IG_WIPE_RIGHTTOLEFT
Right-To-Left Wipe.
IG_WIPE_UP_TO_DOWN
Up-to-Down Wipe.
IG_WIPE_DOWN_TO_UP
Down-to-Up Wipe.
IG_WIPE_SPARKLE
Sparkle Transition.
IG_WIPE_ULTOLRDIAG
Upper Left to Lower Right wipe.
IG_WIPE_LRTOULDIAG
Lower Right to Upper Left wipe.
IG_WIPE_URTOLLDIAG
Upper Right to Lower Left wipe.
IG_WIPE_LLTOURDIAG
Lower Left to Upper Right wipe.
IG_WIPE_CLOCK
Clockwise wipe.
IG_WIPE_SPARKLE_CLOCK
Clockwise wipe with sparkles.
IG_WIPE_DOUBLE_CLOCK
Two simultaneous clockwise wipes, 180× apart.
IG_WIPE_SLIDE_RIGHT
New image slides in from the left.
IG_WIPE_SLIDE_LEFT
New image slides in from the right.
IG_WIPE_SLIDE_UP
New image slides in from the down.
IG_WIPE_SLIDE_DOWN
New image slides in from the up.
IG_WIPE_RANDOM_BARS_DOWN
Vertical bars of old image fall to reveal new image.
IG_WIPE_RAIN
Vertical lines of new image cover over old, like paint running down the side of a bucket.
IG_WIPE_BOOK
Bookwisw wipe.
IG_WIPE_ROLL
Old image rolls in from right to left.
IG_WIPE_UNROLL
New image rolls out from left to right.
IG_WIPE_EXPAND_PROPORTIONAL
New image expands from the center of old image in diagonal directions.
IG_WIPE_EXPAND_HORIZONTAL
New image expands from the center of old image in horizontal directions.
IG_WIPE_EXPAND_VERTICAL
New image expands from the center of old image in vertical directions.
IG_WIPE_STRIPS_HORIZONTAL
New image appeares as expanding horizontal strips.
IG_WIPE_STRIPS_VERTICAL
New image appeares as expanding vertical strips.
IG_WIPE_CELLS
New image appeares as expanding square cells.
IG_WIPE_BALL
New image appeares as tracks of spirally moving balls.
IG_WIPE_GEARS
New image appeares as tracks of moving ImageGear's icons.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		 hIGearBefore;   /* Handle of image already being
displayed */
HIGEAR		 hIGearAfter;    /* Handle of image to replace it  */
HWND		 hWnd;            /* Handle of the window  */
AT_ERRCOUNT		 nErrcount;     /* Returned count of errors  */
/* Perform a "sparkle" wipe, changing 16 x 16 pixel areas in
each step:*/
nErrcount = IG_dspl_image_wipe ( hIGearBefore, IG_GRP_DEFAULT,
hIGearAfter, IG_GRP_DEFAULT, hWnd, IG_WIPE_SPARKLE, 16, 5 );
/* See sample application WIPES for a complete example */

Sample: WIPES

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_layout_get

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_layout_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPAT_RECTANGLE lpImageRect,
    [OUT] LPAT_RECTANGLE lpDeviceRect,
    [OUT] LPAT_RECTANGLE lpClipRect,
    [OUT] LPAT_MODE lpnFitMode,
    [OUT] LPAT_MODE lpnAlignMode,
    [OUT] LPAT_MODE lpnAspectMode,
    [OUT] LPDOUBLE lpdAspectValue
);

Arguments:

hIGear
Image handle from which to search the option group.
dwGrpID
Identifier of group which to get layout options.
lpImageRect
Pointer to the rectangle in which to copy the value of ImageRect option. If NULL then it is ignored. If ImageRect is not set then an empty rectangle is returned.
lpDeviceRect
Pointer to the rectangle in which to copy DeviceRect. If NULL, then the parameter is ignored. If an empty rectangle is returned then it is not set and it will be calculated every time from the destination device.
lpClipRect
Pointer to the rectangle in which to copy ClipRect. If NULL, then the parameter is ignored. If an empty rectangle returned then it is not set and it will be calculated every time from the destination device.
lpnFitMode
Assigns the current FitMode. If NULL then the parameter is ignored.
lpnAlignMode
Assigns the current AlignMode. If NULL then the parameter is ignored.
lpnAspectMode
Assigns the current AspectMode. If NULL then the parameter is ignored.
lpdAspectValue
Assigns the current AspectValue. If NULL then the parameter is ignored.

Description:

This function returns the current values of layout parameters. If a parameter is a rectangle then all empty rectangle is returned if it is not set. For a list of possible values see function IG_dspl_layout_set ().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;     /* HIGEAR handle of image  */
DWORD		nGrpID;      /* display group identifier */
AT_RECTANGLE		 ImageRect;    /* Image rectangle  */
AT_RECTANGLE	 	DeviceRect;    /* Device rectangle  */
AT_RECTANGLE		 ClipRect;      /* Clip rectangle  */
AT_MODE     nFitMode;               /* Fit mode  */
AT_MODE     nAlignMode;            /* Align mode  */
AT_MODE     nAspectMode;           /* Aspect mode  */
DOUBLE      dAspectValue;    /* Aspect value  */
 ...
/* get all layout parameters */
IG_dspl_layout_get( hIGear, nGrpID, &ImageRect, &DeviceRect,
&ClipRect, &nFitMode, &nAlignMode, &nAspectMode, &dAspectValue
);
 ...
/* get only device rectangle and fit mode */
IG_dspl_layout_get( hIGear, nGrpID, NULL, &DeviceRect, NULL,
&nFitMode, NULL, NULL, NULL );
 ...

Sample: ASCII, DISPLAY, GUIWIN, IMG_PROC, MFC, PRINT, THREADS,

Vector, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_layout_set

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_layout_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] DWORD nFlags,
    [IN] const LPAT_RECTANGLE lpImageRect,
    [IN] const LPAT_RECTANGLE lpDeviceRect,
    [IN] const LPAT_RECTANGLE lpClipRect,
    [IN] AT_MODE nFitMode,
    [IN] AT_MODE nAlignMode,
    [IN] AT_MODE nAspectMode,
    [IN] DOUBLE dblAspectValue
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group in which to set layout options.
nFlags
Combination of flags where each one specifies if the appropriate parameter is to be used or ignored:
IG_DSPL_IMAGE_RECT - if (nFlags&IG_DSPL_IMAGE_RECT)!=0 then the lpImageRect parameter of this function is not ignored
IG_DSPL_DEVICE_RECT - if (nFlags&IG_DSPL_DEVICE_RECT)!=0 then the lpDeviceRect parameter of this function is not ignored
IG_DSPL_CLIP_RECT - if (nFlags&IG_DSPL_CLIP_RECT)!=0 then the lpClipRect parameter of this function is not ignored
IG_DSPL_FIT_MODE - if (nFlags&IG_DSPL_FIT_MODE)!=0 then the nFitMode parameter of this function is not ignored
IG_DSPL_ALIGN_MODE - if (nFlags&IG_DSPL_ALIGN_MODE)!=0 then the nAlignMode parameter of this function is not ignored
IG_DSPL_ASPECT_MODE - if (nFlags&IG_DSPL_ASPECT_MODE)!=0 then the nAspectMode parameter of this function is not ignored
IG_DSPL_ASPECT_VALUE - if (nFlags&IG_DSPL_ASPECT_VALUE)!=0 then the dblAspectValue parameter of this function is not ignored
lpImageRect
A new value of ImageRect option to set. If NULL then it is reset with the default value which means the whole image will be used.
lpDeviceRect
A new value of DeviceRect option to set. If NULL, then it is reset with the default value (an empty rectangle). This means it is calculated every time from the destination output device.
lpClipRect
A new value of ClipRect option to set. If NULL, then it is reset with the default value (an empty rectangle). This means it is calculated every time and assigned to the whole client area of the destination output device.
nFitMode
New value of FitMode option to set. Possible values are:
  • IG_DSPL_FIT_TO_DEVICE
  • IG_DSPL_FIT_TO_WIDTH
  • IG_DSPL_FIT_TO_HEIGHT
  • IG_DSPL_ACTUAL_SIZE
nAlignMode
New value of AlignMode option to set. Possible value is OR combination of one constant that sets the horizontal alignment:
  • IG_DSPL_ALIGN_X_LEFT
  • IG_DSPL_ALIGN_X_CENTER
  • IG_DSPL_ALIGN_X_RIGHT
and one that sets the vertical alignment:
  • IG_DSPL_ALIGN_Y_TOP
  • IG_DSPL_ALIGN_Y_CENTER
  • IG_DSPL_ALIGN_Y_BOTTOM
nAspectMode
New value of AspectMode option to set. Possible values are:
  • IG_DSPL_ASPECT_FIXED
  • IG_DSPL_ASPECT_NOT_FIXED
dblAspectValue
Sets new value to AspectValue option. Possible value may be any positive double.

Description:

This function sets layout parameters. If some of the values are out of range then it does not change and an error is returned.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;    /* HIGEAR handle of image  */
DWORD		nGrpID;     /* display group identifier */
AT_RECTANGLE		 ImageRect;  /* Image rectangle   */
AT_RECTANGLE		 DeviceRect;  /* Device rectangle   */
AT_RECTANGLE		 ClipRect;     /* Clip rectangle  */
AT_MODE		 nFitMode;     /* Fit mode     */
AT_MODE		 nAlignMode;    /* Align mode     */
AT_MODE		 nAspectMode;   /* Aspect mode     */
DOUBLE		dAspectValue;      /* Aspect value  */
AT_MODE		 nFlags;        /* flags which specify what to set */
/* set all layout parameters */
nFlags =
IG_DSPL_IMAGE_RECT|IG_DSPL_DEVICE_RECT|IG_DSPL_CLIP_RECT|IG_DSP
L_FIT_MODE|IG_DSPL_ALIGN_MODE|IG_DSPL_ASPECT_MODE|IG_DSPL_ASPEC
T_VALUE;
IG_dspl_layout_get( hIGear, nGrpID, &ImageRect, &DeviceRect,
&ClipRect, nFitMode, nAlignMode, nAspectMode, dAspectValue );
 ... ...
/* reset image, device and clip rectangles to its default values
*/
nFlags =
IG_DSPL_IMAGE_RECT|IG_DSPL_DEVICE_RECT|IG_DSPL_CLIP_RECT;
IG_dspl_layout_set( hIGear, nGrpID, nFlags, NULL, NULL, NULL, 0,
0, 0, 0.0 );
 ...
/* set new fit mode */
IG_dspl_layout_set( hIGear, nGrpID, IG_DSPL_FIT_MODE, NULL,
NULL, NULL, IG_DSPL_FIT_TO_WIDTH, 0, 0, 0.0 );
 ...
/* set align mode so that the image located at right bottom of
device rectangle */
IG_dspl_layout_set( hIGear, nGrpID, IG_DSPL_ALIGN_MODE, NULL,
NULL, NULL, 0, IG_DSPL_ALIGN_X_RIGHT| IG_DSPL_ALIGN_Y_BOTTOM,
0, 0.0 );
 ...

Sample: ASCII, DISPLAY, GUIWIN, IMG_PROC, IMGUTIL, MDI, MFC,

POSTER, PRINT, TIMING, THREADS, ARTEXT, Vector, Bar, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_LUT_get

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_LUT_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPBYTE lpRLUT,
    [OUT] LPBYTE lpGLUT,
    [OUT] LPBYTE lpBLUT
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group from which to get options.
lpRLUT
Pointer to where the current red lookup table (RedLut value) is to be copied. If NULL, then this parameter is ignored.
lpGLUT
Pointer where the current green lookup table (GreenLut value) is to be copied. If NULL, then this parameter is ignored.
lpBLUT
Pointer where the current blue lookup table (BlueLut value) is to be copied. If NULL, then this parameter is ignored.

Description:

This function returns the current red, green and blue lookup tables lpRLUT, lpGLUT or lpBLUT should be either NULL or valid pointers to a 256 byte array.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear;         /* HIGEAR handle of image  */
DWORD	 nGrpID;         /* display group identifier  */
BYTE	 r_lut[256];       /* red lookup array     */
BYTE	 g_lut[256];     /* green lookup array     */
 ...
IG_dspl_LUT_get( hIGear, nGrpID, r_lut, g_lut, NULL );
 . .

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_LUT_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_LUT_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] AT_MODE nFlags,
    [IN] const LPBYTE lpRLUT,
    [IN] const LPBYTE lpGLUT,
    [IN] const LPBYTE lpBLUT
);

Arguments:

hIGear
ImageGear handle of image
dwGrpID
Identifier of group in which to set LUT options.
nFlags
Specify which lookup tables to set. Possible value is 0 or a combination of flags
IG_DSPL_R_CHANNEL - if this flag is set then the lpRLUT parameter of this function is not ignored
IG_DSPL_G_CHANNEL - if this flag is set then the lpGLUT parameter of this function is not ignored
IG_DSPL_B_CHANNEL - if this flag is set then the lpBLUT parameter of this function is not ignored
The constant IG_DSPL_ALL_CHANNELS is defined for convenience and can be used to set all three channels.
#define IG_DSPL_ALL_CHANNELS
(IG_DSPL_R_CHANNEL|IG_DSPL_G_CHANNEL|IG_
DSPL_B_CHANNEL)
lpRLUT
Pointer to a 256 element array of a red lookup table to set. If NULL, then identity the array is assigned to RedLut option.
lpGLUT
Pointer to a 256 element array of a green lookup table to set. If NULL, then identity the array is assigned to GreenLut option.
lpBLUT
Pointer to a 256 element array of a blue lookup table to set. If NULL, then identity the array is assigned to BlueLut option.

Description:

This function assigns new values to red, green and blue lookup tables.

TIP: IG always makes a copy of lpRLUT, lpGLUT and lpBLUT in case they are needed, but does not assign pointers directly so that the application should cleanup the memory allocated for them.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear;         /* HIGEAR handle of image  */
DWORD	 nGrpID;        /* display group identifier  */
BYTE	 lut[256];      /* lookup array  */
INT	 i;
 ...
/* set inverted lookup table */
for( i = 0; i<256; i++ )
    lut[i] = 255 - i;
IG_dspl_LUT_set( hIGear, nGrpID, IG_DSPL_ALL_CHANNELS, lut,
lut, lut );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_mapmode_get

Group: Display

Declaration:

AT_ERRCOUNT    ACCUAPI   IG_dspl_mapmode_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPDWORD lpdwMapMode,
    [OUT] LPAT_RECTANGLE lpViewport,
    [OUT] LPAT_RECTANGLE lpWindow
);

Arguments:

hIGear
ImageGear handle of Image.
dwGrpID
Identifier of group from which to get map mode options.
lpdwMapMode
Pointer to the current value of option MapMode.
lpViewport
Pointer to the current value of rectangle Viewport.
lpWindow
Pointer to the current value of rectangle Window.

Description:

This function returns the current map mode and logical coordinate system where parameters such as ClipRect, DeviceRect and most others (except ImageRect) are stored.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;     /* HIGEAR handle of image  */
DWORD		nGrpID;     /* display group identifier */
DWORD		dwMapMode;    /* map mode   */
AT_RECTANGLE	 	Viewport;     /* view port values    */
AT_RECTANGLE		 Window;       /* window values  */
 ...
IG_dspl_mapmode_get( hIGear, nGrpID, &dwMapMode, &Viewport,
&Window );
SetMapMode( dwMapMode );
SetWindowOrgEx( hDC, Window.x, Window.y, NULL );
SetWindowExtEx( hDC, Window.width, Window.height, NULL );
SetViewportOrgEx( hDC, Viewport.x, Viewport.y, NULL );
SetViewportExtEx( hDC, Viewport.width, Viewport.height, NULL );
 ...

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_mapmode_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_mapmode_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] DWORD dwMapMode,
    [IN] const LPAT_RECTANGLE lpViewport,
    [IN] const LPAT_RECTANGLE lpWindow
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group in which to set map mode options.
dwMapMode
New value of option MapMode to assign.
LpViewport
New value of Viewport option to assign.
LpWindow
New value of Window option to assign.

Description:

This function sets the current map mode and logical coordinate system. IG will perform all calculations with the assumption that the specified logical system is used for the device coordinates.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;     /* HIGEAR handle of image  */
DWORD		nGrpID;      /* display group identifier  */
DWORD		dwMapMode;       /* map mode   */
AT_RECTANGLE 		Viewport;         /* view port values  */
AT_RECTANGLE		 Window;          /* window values  */
POINT		p;
SIZE		s;
 ...
/* get current mapping parameters */
dwMapMode = GetMapMode( hDC );
GetViewportOrgEx( hDC, &p );
Viewport.x = p.x;
Viewport.y = p.y;
GetViewportExtEx( hDC, &s );
Viewport.width = s.cx;
Viewport.height = s.cy;
GetWindowOrgEx( hDC, &p );
Window.x = p.x;
Window.y = p.y;
GetWindowExtEx( hDC, &s );
Window.width = s.cx;
Window.height = s.cy;
IG_dspl_mapmode_set( hIGear, nGrpID, dwMapMode, &Viewport,
&Window );
 ...

Sample: DISPLAY, MFC, THREADS

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_orientation_get

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_orientation_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPAT_MODE lpnOrientMode
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group from which to retrieve the orientation mode.
lpnOrientMode
Where to copy OrientMode value. If NULL then this parameter ignored.

Description:

This function returns the current orientation mode. Possible values are listed in the IG_dspl_orientation_set () function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;       /* HIGEAR handle of image  */
DWORD		nGrpID;        /* display group identifier  */
AT_MODE		 nOrientMode;      /* Orientation mode  */
 ...
IG_dspl_orientation_get( hIGear, nGrpID, &nOrientMode );
 ...

Sample: DISPLAY, MFC, Vector, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_orientation_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_orientation_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] AT_MODE nOrientMode
);

Arguments:

hIGear
Image handle where to set orientation mode.
dwGrpID
Identifier of the group in which to set the orientation.
nOrientMode
New OrientMode value to set. Possible values are:
IG_DSPL_ORIENT_TOP_LEFT
IG_DSPL_ORIENT_LEFT_TOP
IG_DSPL_ORIENT_RIGHT_TOP
IG_DSPL_ORIENT_TOP_RIGHT
IG_DSPL_ORIENT_BOTTOM_RIGHT
IG_DSPL_ORIENT_RIGHT_BOTTOM
IG_DSPL_ORIENT_LEFT_BOTTOM
IG_DSPL_ORIENT_BOTTOM_LEFT

Description:

This function sets the new orientation mode.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR       hIGear;      /* HIGEAR handle of image  */
DWORD        nGrpID;      /* display group identifier  */
 ...
/* rotate image orientation by 90 degree   */
IG_dspl_orientation_set( hIGear, nGrpID,
IG_DSPL_ORIENT_TOP_RIGHT );
 ...

Sample: ASCII, DISPLAY, MFC, ARTEXT, Vector, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_page_print

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_page_print(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HDC hDC,
    [IN] const LPAT_DRECTANGLE lpLayout,
    [IN] BOOL bDirectToDriver
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group from which to get printing options.
hDC
Handle of printer device context on which to draw the image.
lpLayout
Rectangle which specifies how the image is located on the page. This rectangle is calculated in page-relative units, and as actual page resolutions are obtained it translates the rectangle into real coordinates and assigns ClipRect according to the following rules:
ClipRect.x = lpLayout->x*nPageWidth
ClipRect.y = lpLayout->y*nPageHeight
ClipRect.width = lpLayout->width*nPageWidth
ClipRect.height = lpLayout->height*nPageHeight
bDirectToDriver
If TRUE then ImageGear does not perform image scaling but uses the operating system's and driver's capabilities for this. If FALSE then ImageGear performs the scaling.

Description:

This function draws an image onto the printer device context within the specified rectangle. Printing resolution depends on the current printer setting. The bDirectToDriver parameter allows you to perform image scaling inside of ImageGear or leave this task to the printer driver and operating system. Usually, direct to driver printing (bDirectToDriver=TRUE) results in smaller output size and it works faster, but not using it produces better quality and allows you to use IG capabilities such as anti-aliasing during printing.

NOTE: Special predefined option group IG_GRP_DEFAULT_PRINT can be used to print an image with the most common parameters.
NOTE: If you are using ImageGear ARTX component in your application please use IG_dspl_artx_page_print() function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;        /* HIGEAR handle of image  */
DWORD		nGrpID;        /* display group identifier   */
BOOL		bDirect;       /* direct to driver flag  */
AT_DRECTANGLE
        Layout;
PRINTDLG		 pd;          /* print dialog structure  */
 ...
case ID_FILE_PRINT:
     ...
    if( PrintDlg(&pd) )
    {
 ...
/* print image in the middle of the page and at 0.5 of width and
height of the page */
Layout.x = 0.25;			Layout.y = 0.25;
Layout.width = 0.5; Layout.height = 0.5;
IG_dspl_page_print( hIGear, nGrpID, pd.hDC, &Layout, bDirect );
 ...
    }
     ...
    break;
 ...

Sample: PRINT, DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_palette_create

Group: Display

Declaration:

AT_ERRCOUNT     ACCUAPI   IG_dspl_palette_create(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] HDC hDC,
    [OUT] HPALETTE FAR* lphPalette
);

Arguments:

hIGear
ImageGear handle of image.
DwGrpID
Identifier of group containing the palette options to use.
HWnd
Handle of window where the image is drawn.
HDC
Handle of device context on which to draw.
LphPalette
Pointer to where the palette handle should be returned.

Description:

This function calculates all the display parameters, the way IG_dspl_image_draw () does, and produces the same palette that IG_dspl_image_draw realizes before drawing onto hDC. It returns DevicePalette if it is not set with a custom value.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;      /* HIGEAR handle of image  */
DWORD		nGrpID;      /* display group identifier */
HPALETTE	 	hPalette;     /* handle of palette  */
 ...
IG_dspl_palette_create( hIGear, nGrpID, hWnd, hDC, &hPalette );
 ...

Sample: MDI, MFC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_palette_handle

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_palette_handle(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] HDC hDC,
    [IN] AT_MODE nPalMode,
    [OUT] LPBOOL lpbRealized
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group that should be used.
hWnd
Valid handle of window where image is drawn and from which palette message is to be handled.
hDC
Handle of device context where image is to be drawn. If NULL, then it will automatically be retrieved from hWnd.
nPalMode
New value of PaletteMode to set. Possible value is either
IG_DSPL_PALETTE_HIGH or IG_DSPL_PALETTE_LOW.
Please note that this new value is assigned only if the current value of PaletteMode is not IG_DSPL_PALETTE_DISABLE.
If the current value is IG_DSPL_PALETTE_DISABLE then the function does not perform any action (to change this, use IG_dspl_palette_set ()function).
lpbRealized
Pointer to the BOOL parameter where TRUE will be assigned if new palette has been realized and FALSE if otherwise. If NULL, then this parameter is ignored.

Description:

This function is designed to be used to handle palette messages from the operating system. For the Windows platform, this function should be called when WM_QUERYNEWPALETTE and WM_PALETTECHANGED messages are processed (see the sample below). Handling of those messages is extremely important for palette based devices.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;      /* HIGEAR handle of image   */
DWORD		nGrpID;      /* display group identifier */
 ...
case WM_QUERYNEWPALETTE:
    /* let Image Gear handle palette management */
IG_dspl_palette_handle(hIGear, nGrpID, hWnd, NULL,
IG_DSPL_PALETTE_HIGH, &bRealized );
    return bRealized;
case WM_PALETTECHANGED:
    /* let Image Gear handle palette management */
IG_dspl_palette_handle(hIGear, nGrpID, hWnd, NULL,
IG_DSPL_PALETTE_LOW, NULL );
    break;
 ...

Sample: ASCII, COLOR, DISPLAY, GUIWIN, GUISCAN, loadext, MDI, MFC,

PAGE, THUMB, FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_palette_get

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_palette_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPAT_MODE lpnPalMode,
    [OUT] HPALETTE FAR* lphPalette
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group from which to get palette options.
lpnPalMode
Pointer to where PaletteMode is to be received. If NULL, then this parameter is ignored.
lphPalette
Pointer to where DevicePalette is to be received. If NULL, then this parameter is ignored.

Description:

This function returns the current palette settings.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;      /* HIGEAR handle of image   */
DWORD		nGrpID;      /* display group identifier  */
AT_MODE	 	nPalMode;    /* palette mode  */
HPALETTE		 hPalette;    /* palette handle */
 ...
IG_dspl_palette_get( hIGear, nGrpID, &nPalMode, &hPalette );
 ...

Samples: MDI, MFC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_palette_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_palette_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] AT_MODE nPalMode,
    [IN] HPALETTE hPalette
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group in which to set palette options.
nPalMode
New value of PaletteMode to set. Possible values are:
  • IG_DSPL_PALETTE_HIGH
  • IG_DSPL_PALETTE_LOW
  • IG_DSPL_PALETTE_DISABLE
hPalette
New value of DevicePalette option. Possible value is NULL or valid OS-dependent palette handle. Please note that the application code is responsible for removing all the resources allocated for DevicePalette if it is not NULL.

Description:

This function sets the new palette options.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;    /* HIGEAR handle of image  */
DWORD		nGrpID;    /* display group identifier  */
 ...
/* disable palette realization */
IG_dspl_palette_set( hIGear, nGrpID, IG_DSPL_PALETTE_DISABLE,
NULL );
 ...

Sample: MDI, MFC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_PPM_correct_get

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_PPM_correct_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPBOOL lpbEnable
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group in from which to get options.
LpbEnable
Pointer to where to get the current value of option PPMCorrect.

Description:

This function returns the current value of options which specify either to use the image resolution or the image dimension to calculate the aspect ratio.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;       /* HIGEAR handle of image  */
DWORD		nGrpID;      /* display group identifier    */
BOOL		bPPMEnable;    /* PPM corect flag value  */
 ...
IG_dspl_PPM_correct_get ( hIGear, nGrpID, &bPPMEnable );
 ...

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_PPM_correct_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_PPM_correct_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] BOOL bEnable
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group for which to set options.
bEnable
New value for PPMCorrect option. If TRUE then the resolution will be used to calculate the aspect ratio, but if FALSE then the image dimension will be used.

Description:

This function sets the new value of the PPMCorrect option.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;     /* HIGEAR handle of image   */
DWORD		nGrpID;     /* display group identifier */
 ...
IG_dspl_PPM_correct_set ( hIGear, nGrpID, TRUE );
 ...

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_resize_handle

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_resize_handle(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group which is used to display the image on the hWnd.
hWnd
Handle of window where the image is displayed.

Description:

This function is to be called during WM_SIZE message handling and it recalculates all the parameters according to the new window width and height.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;       /* HIGEAR handle of image  */
DWORD		nGrpID;        /* display group identifier */
 ...
case WM_SIZE:
    /* handle window resizing */
    IG_dspl_resize_handle( hIGear, nGrpID, hWnd );
    break;
 ...

Sample: MAGNIFY, MDI, IMGUTIL, PAN, Vector, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_ROP_get

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_ROP_get(
    HIGEAR hIGear,
    DWORD dwGrpID,
    LPDWORD lpdwROP
);

Arguments:

hIGear
HIGEAR handle of image
dwGrpID
Identifier of display group to get ROP code from
lpdwROP
Returned ROP code

Description:

This function gets the ROP (raster-operation) code used to display images on Windows platforms. This code determines how the source image pixels are combined with the destination area pixels. The default ROP is SRCCOPY, which overwrites the destination area with the source image. Other codes are described in the documentation for the Windows GDI function BitBlt.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR       hIGear;      /* HIGEAR handle of image */
DWORD        nGrpID;      /* display group identifier */
DWORD        dwROP;       /* retrieved ROP code */
 ...
/* get ROP code */
IG_dspl_ROP_get( hIGear, nGrpID, &dwROP );
 ...

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_ROP_set

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI IG_dspl_ROP_set(
    HIGEAR hIGear,
    DWORD dwGrpID,
    DWORD dwROP
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group in which to set ROP code.
dwROP
ROP code to set.

Description:

This function sets the ROP (raster-operation) code to use when displaying images on Windows platforms. This code determines how the source image pixels are combined with the destination area pixels. The default ROP is SRCCOPY, which overwrites the destination area with the source image. Other codes are described in the documentation for the Windows GDI function BitBlt.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR       hIGear;      /* HIGEAR handle of image  */
DWORD        nGrpID;      /* display group identifier  */
 ...
/* image will be XOR'd with destination contents */
IG_dspl_ROP_set( hIGear, nGrpID, SRCINVERT );
 ...

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_scroll_get

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_scroll_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [OUT] LPAT_MODE lpnScrollMode,
    [OUT] LPAT_SCROLL_INFO lpScrollInfo
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group from which to retrieve scroll parameters.
hWnd
Handle of window where image is drawn.
lpnScrollMode
Where ScrollbarMode is to be received. If NULL, then this parameter is ignored.
lpScrollInfo
Where to copy the current scroll parameters. If NULL, then this parameter is ignored.

Description:

This function calculates and returns the current scroll parameters.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;        /* HIGEAR handle of image   */
DWORD		nGrpID;        /* display group identifier  */
AT_MODE		 nScrollMode;      /* scroll mode   */
AT_SCROLL_INFO  ScrollInfo;   /* scroll info  */
 ...
IG_dspl_scroll_get( hIGear, nGrpID, hWnd, &nScrollMode,
&ScrollInfo );
 ...

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_scroll_handle

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_scroll_handle(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] AT_MODE nScrlType,
    [IN] AT_MODE nScrlMode,
    [IN] LONG lScrlValue,
    [OUT] LPAT_SCROLL_INFO lpScrollInfo
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group which will be used to perform operation.
hWnd
Handle of window where image is displayed and where scrolling is performed.
nScrlType
Scroll command. Its value is platform dependent. For Win32 platforms there should be LOWORD(wParam) and for Win16, wParam. Valid values are:
  • IG_DSPL_SCROLL_HORIZONTAL
  • IG_DSPL_SCROLL_VERTICAL
nScrlMode
Scroll command. Its value is platform dependent. For Win32 platforms there should be LOWORD(wParam) and for Win16, wParam. Valid values are:
  • IG_DSPL_HSCROLLBAR
  • IG_DSPL_HSCROLLBAR_AUTO
  • IG_DSPL_HSCROLLBAR_ENABLE
  • IG_DSPL_HSCROLLBAR_DISABLE
  • IG_DSPL_VSCROLLBAR
  • IG_DSPL_VSCROLLBAR_AUTO
  • IG_DSPL_VSCROLLBAR_ENABLE
  • IG_DSPL_VSCROLLBAR_DISABLE
nScrlValue
Scroll value. It is also platform dependent and its value may have a different meaning from nScrlType. Under the Windows platform, it is not used because the scroll position is obtained directly from the scrollbars.
lpScrollInfo
Receive updated scroll parameters (not scrollbar). If NULL then it is ignored.

Description:

This function is designed to handle scrollbar messages from an hWnd window. It should not be used to set the absolute scroll position; function IG_dspl_scroll_to () should be used instead.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;       /* HIGEAR handle of image      */
DWORD		nGrpID;       /* display group identifier     */
 ...
case WM_HSCROLL:           /* horizontal scrolling   */
IG_dspl_scroll_handle( hIGear, nGrpID, hWnd,
IG_DSPL_SCROLL_HORIZONTAL, LOWORD(wParam), HIWORD(wParam), NULL
);
    break;
case WM_VSCROLL: /* vertical scrolling */
IG_dspl_scroll_handle( hIGear, nGrpID, hWnd,
IG_DSPL_SCROLL_VERTICAL, LOWORD(wParam), HIWORD(wParam), NULL
);
    break;
 ...

Sample: ASCII, DISPLAY, IMGUTIL, MAGNIFY, MDI, MFC, PAN, ARTEXT,

Vector, FILTER, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_scroll_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_scroll_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] AT_MODE nScrollMode,
    [IN] INT nXPage,
    [IN] INT nYPage,
    [OUT] LPAT_SCROLL_INFO lpScrollInfo
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group in which to set scroll options.
hWnd
Handle of window where image is drawn.
nScrollMode
New value of ScrollbarMode to set. Possible value is a combination of the horizontal scrollbar flag:
  • IG_DSPL_HSCROLLBAR_AUTO
  • IG_DSPL_HSCROLLBAR_ENABLE
  • IG_DSPL_HSCROLLBAR_DISABLE
and the vertical:
  • IG_DSPL_VSCROLLBAR_AUTO
  • IG_DSPL_VSCROLLBAR_ENABLE
  • IG_DSPL_VSCROLLBAR_DISABLE
nXPage
New value of scrolling page width. If 0 then it will be calculated from ClipRect.
nYPage
New value of scrolling page height. If 0 then it will be calculated from ClipRect.
lpScrollInfo
Where to copy new scroll parameters. If NULL then the parameter is ignored.

Description:

This function sets the scroll parameters (not scroll position) and allows you to enable and disable the vertical and horizontal scrollbars associated with a given window.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;      /* HIGEAR handle of image  */
DWORD		nGrpID;        /* display group identifier   */
AT_SCROLL_INFO  ScrollInfo;      /* scroll info  */
 ...
/* always hide both scrollbars */
IG_dspl_scroll_set( hIGear, nGrpID, hWnd,
IG_DSPL_HSCROLLBAR_DISABLE|IG_DSPL_VSCROLLBAR_DISABLE, 0, 0,
&ScrollInfo );
 ...

Sample: JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_scroll_to

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_scroll_to(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] INT nXPos,
    [IN] INT nYPos,
    [OUT] LPAT_SCROLL_INFO lpScrollInfo
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group where to work.
hWnd
Handle of window where image is drawn and scrolled.
nXPos
New horizontal scroll position. Should be in a valid range that can be retrieved using the IG_dspl_scroll_get () function.
nYPos
New vertical scroll position. Should be in a valid range that can be retrieved using the IG_dspl_scroll_get ()function.
lpScrollInfo
Where to copy the new scroll parameters. If NULL then the parameter is ignored.

Description:

This function scrolls the image to a specified position and updates the window's scroll bars accordingly. It can be used even if a window's scroll bars are disabled. Both scroll positions should be in valid scroll range but if not, then the nearest valid value will be assigned.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;         /* HIGEAR handle of image   */
DWORD		nGrpID;          /* display group identifier  */
AT_SCROLL_INFO  ScrollInfo;    /* scroll info  */
 ...
/* scroll down and right from current position */
IG_dspl_scroll_get( hIGear, nGrpID, hWnd, NULL, &ScrollInfo );
If( (ScrollInfo.h_cur_pos<ScrollInfo.h_max) &&
(ScrollInfo.v_cur_pos<ScrollInfo.v_max) )
    IG_dspl_scroll_to( hIGear, nGrpID, hWnd,
ScrollInfo.h_cur_pos+1, ScrollInfo.v_cur_pos+1, NULL );

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_scroll_to_ex

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_scroll_to_ex(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] INT nXPos,
    [IN] INT nYPos,
    [OUT] LPAT_SCROLL_INFO lpScrollInfo
    [IN] BOOL bRepaint
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group where to work.
hWnd
Handle of window where image is drawn and scrolled.
nXPos
New horizontal scroll position. Should be in a valid range that can be retrieved using the IG_dspl_scroll_get () function.
nYPos
New vertical scroll position. Should be in a valid range that can be retrieved using the IG_dspl_scroll_get ()function.
lpScrollInfo
Where to copy the new scroll parameters. If NULL then the parameter is ignored.
bRepaint
This parameter determines if the function repaints scrolling content (TRUE) or not (FALSE).

Description:

This function scrolls the image to a specified position and updates the window's scroll bars accordingly. It can be used even if a window's scroll bars are disabled. Both scroll positions should be in valid scroll range but if not, then the nearest valid value will be assigned.

This function is the same as IG_dspl_scroll_to () function, but has bRepaint parameter that when FALSE allows do not repaint the scrolling content.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_transparency_get

Group: Display

Declaration:

AT_ERRCOUNT    ACCUAPI  IG_dspl_transparency_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [OUT] LPAT_MODE lpnTranspMode,
    [OUT] LPAT_RGB lpTranspColor,
    [OUT] LPHIGEAR lphIMask,
    [OUT] LPAT_RECTANGLE lpMaskRect,
    [OUT] LPAT_POINT lpMaskLocation
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group to use.
lpnTranspMode
Pointer where TranspMode options are returned. If NULL, then this parameter is ignored.
lpTranspColor
Pointer where TranspColor option is returned. If NULL, then this parameter is ignored.
hphIMask
Pointer where TranspMask option is returned. If NULL, then this parameter is ignored. Please note that this function does not change or delete the value of TranspMask, but only makes its copy.
lpMaskRect
Pointer to where to return the value of the MaskRect option. If NULL, then this parameter is ignored. If an empty rectangle is returned then it is initialized with a rectangle equal to the entire mask image.
lpMaskLocation
Pointer to where to return the value of MaskLocation option. If NULL, then this parameter is ignored.

Description:

This function returns the transparency parameters.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;        /* HIGEAR handle of image    */
DWORD		nGrpID;         /* display group identifier */
AT_MODE 		nTranspMode;     /* transparency mode  */
AT_RGB		TranspColor;    /* transparency color  */
HIGEAR		hIMask;         /* transparent mask    */
AT_RECTANGLE	 	MaskRect;       /* mask rectangle      */
AT_POINT	 	MaskLocation;    /* mask location   */
 ...
IG_dspl_transparency_get( hIGear, nGrpID, &nTranspMode,
&TranspColor, &hIMask, &MaskRect, &MaskLocation );
if( IG_image_is_valid( hIMask ) )
    IG_image_delete( hIMask );
 ...

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_transparency_set

Group: Display

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_dspl_transparency_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] AT_MODE nTranspMode,
    [IN] const LPAT_RGB lpTranspColor,
    [IN] HIGEAR hIMask,
    [IN] const LPAT_RECTANGLE lpMaskRect,
    [IN] const LPAT_POINT lpMaskLocation
);

Arguments:

hIGear
ImageGear handle of image
dwGrpID
Identifier of the group in which to set transparency options.
nTranspMode
New value of TranspMode to set. Possible value maybe:
  • IG_DSPL_TRANSPARENCY_NONE,
or a combination of one of the following flags:
  • IG_DSPL_TRANSPARENCY_COLOR
  • IG_DSPL_TRANSPARENCY_MASK
  • IG_DSPL_TRANSPMASK_STRETCH_TO_IMAGE
and one of these flags:
  • IG_DSPL_TRANSPMASK_LOCATE_TO_IMAGE
  • IG_DSPL_TRANSPMASK_LOCATE_TO_CLIPRECT
  • IG_DSPL_TRANSPMASK_LOCATE_ABSOLUTE
lpTranspColor
New value of TranspColor to set. If NULL, then this parameter is ignored.
hIMask
New value of TranspMask option to set. Please note that the image is not deleted and the application code is responsible for removing the old value of this option.
lpMaskRect
New value of MaskRect option to set. If NULL, then this parameter is ignored. An empty rectangle is possible.
lpMaskLocation
New value of MaskLocation option to set. If NULL, then this parameter is ignored.

Description:

This function sets the transparency options.

NOTE: This function set the transparency only for image displaying. For saving image with transparency mask use function IG_display_transparent_set().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;        /* HIGEAR handle of image  */
DWORD		nGrpID;        /* display group identifier  */
AT_MODE		 nTranspMode;    /* transparency mode  */
AT_RGB		TranspColor;    /* transparency color */
HIGEAR		hIMask;         /* transparent mask   */
 ...
/* enable transparent color and mask with default mask rectangle
and location oriented and scaled with main image */
nTranspMode =
IG_DSPL_TRANSPARENCY_COLOR|IG_DSPL_TRANSPARENCY_MASK|IG_DSPL_TR
ANSPMASK_STRETCH_TO_IMAGE|IG_DSPL_TRANSPMASK_LOCATE_TO_IMAGE;
/* set transparent color to white */
TranspColor.r = TranspColor.g = TranspColor.b = 255;
IG_dspl_transparency_set( hIGear, nGrpID, nTranspMode,
&TranspColor, hIMask, NULL, NULL );
 ...

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_zoom_get

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_zoom_get(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [OUT] LPAT_MODE lpnZoomMode,
    [OUT] LPDOUBLE lpdblHZoom,
    [OUT] LPDOUBLE lpdblVZoom
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of the group from which to obtain zoom parameters.
hWnd
Handle of window where the image is drawn.
lpnZoomMode
Pointer to where ZoomMode is to be received. If NULL, then this parameter is ignored.
lpdblHZoom
Where to return the calculated horizontal zoom value. This value is always calculated whether or not the horizontal zoom is fixed.
lpdblVZoom
Where to return the calculated vertical zoom value. This value is always calculated whether or not the vertical zoom is fixed.

Description:

This function returns the current zoom values.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;        /* HIGEAR handle of image  */
DWORD		nGrpID;        /* display group identifier  */
AT_MODE		 nZoomMode;     /* zoom mode     */
DOUBLE		dHZoom;        /* horizontal zoom value   */
DOUBLE		dVZoom;        /* vertical zoom value    */
 ...
IG_dspl_zoom_get( hIGear, nGrpID, hWnd, &nZoomMode, &dHZoom,
&dVZoom );
 ...

Sample: DISPLAY, MFC, FILTERS, ASCII, PAN, ARTEXT, Vector

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_zoom_set

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_dspl_zoom_set(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] AT_MODE nZoomMode,
    [IN] DOUBLE dHZoom,
    [IN] DOUBLE dVZoom
);

Arguments:

hIGear
Image handle to where set zoom options.
dwGrpID
Identifier of group in which to set zoom options.
nZoomlMode
New value of ZoomMode to set. Possible value is combination from one of the horizontal zoom flags:
  • IG_DSPL_ZOOM_H_NOT_FIXED
  • IG_DSPL_ZOOM_H_FIXED
and one of the vertical flags:
  • IG_DSPL_ZOOM_V_NOT_FIXED
  • IG_DSPL_ZOOM_V_FIXED
dHZoom
New value of ZoomValueH to set. Any positive number is accepted. Value 1.0 means that the image is zoomed by 100% or displayed in its actual size.
dVZoom
New value of ZoomValueV to set. Any positive number is accepted. Value 1.0 means that the image is zoomed by 100% or displayed in its actual size.

Description:

This function sets the new zoom values.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;        /* HIGEAR handle of image    */
DWORD		nGrpID;        /* display group identifier  */
 ...
/* set aspect ratio as not fixed and zoom image by 150% and 200%
for horizontal and vertical directions respectively  */
IG_dspl_layout_set( hIGear, nGrpID, IG_ASPECT_MODE, NULL, NULL,
NULL, 0, 0, IG_DSPL_ASPECT_NOT_FIXED, 0.0 );
IG_dspl_zoom_set( hIGear, nGrpID, IG_DSPL_ZOOM_H_FIXED|
IG_DSPL_ZOOM_V_FIXED, 1.5, 2.0 );
 ...
/* the same as before but only for horizontal direction;
vertical direction is zoomed according to current fit method and
device rectangle */
IG_dspl_zoom_set( hIGear, nGrpID, IG_DSPL_ZOOM_H_FIXED|
IG_DSPL_ZOOM_V_NOT_FIXED, 1.5, 2.0 );
 ...

Sample: DISPLAY, MFC, FILTERS, ASCII, PAN, ART, Vector

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_dspl_zoom_to_rect

Group: Display

Declaration:

AT_ERRCOUNT   ACCUAPI   IG_dspl_zoom_to_rect(
    [IN] HIGEAR hIGear,
    [IN] DWORD dwGrpID,
    [IN] HWND hWnd,
    [IN] const LPAT_RECTANGLE lpZoomRect,
    [OUT] LPDOUBLE lpdblHZoom,
    [OUT] LPDOUBLE lpdblVZoom
);

Arguments:

hIGear
ImageGear handle of image.
dwGrpID
Identifier of group in which to set zoom_to_rect options.
hWnd
Handle of window where image is drawn.
lpZoomRect
Pointer to the rectangle in device coordinates that should be fitted into ClipRect.
lpdblHZoom
Pointer to where to return the newly calculated ZoomValueH value. If NULL, then this parameter is ignored.
lpdblVZoom
Pointer to where to return the newly calculated ZoomValueV value. If NULL, then this parameter is ignored.

Description:

This function calculates the zoom and scroll values, so that the specified rectangle is fitted to ClipRect. It assigns ZoomMode=IG_DSPL_ZOOM_H_FIXED| IG_DSPL_ZOOM_V_FIXED, calculates and modifies ZoomValueH, ZoomValueV, and the horizontal and vertical scroll positions. It does not change the value of rectangles DeviceRect, ImageRect and ClipRect.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR		hIGear;       /* HIGEAR handle of image  */
DWORD		nGrpID;        /* display group identifier */
AT_RECTANGLE 		ZoomRect;     /* rectangle where to zoom  */
RECT		rc;
 ...
GetClientRect( hWnd, &rc );
ZoomRect.x = rc.left;
ZoomRect.y = rc.top;
ZoomRect.width = (rc.right - rc.left + 1)/2;
ZoomRect.height = (rc.bottom - rc.top + 1)/2;
IG_dspl_zoom_to_rect( hIGear, nGrpID, hWnd,  &ZoomRect, NULL,
NULL );
 ...

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_err_callback_get

Group: Library Utility

Declaration:

AT_ERRCODE ACCUAPI IG_err_callback_get(
    [IN] LPVOID FAR*  lplpPrivate,
    [IN] LPFNIG_ERRSTACK_ADD FAR*  lplpfnAddCB,
    [IN] LPFNIG_ERRSTACK_CLEAR FAR*  lplpfnClearCB
);

Arguments:

lplpPrivate
Pointer indicating where to receive private data.
lplpfnAddCB
Pointer indicating where to receive the pointer to the callback function that is called after the record is added to the error stack.
lplpfnClearCB
Pointer indicating where to receive the pointer to the callback function that is called after the error stack is cleared.

Description:

This function is currently associated with the error stack callback data and functions that are called to flag error stack changes.

NOTE: See also IG_err_callback_set() function.

Bits Per Pixel: Not applicable

Return Value:

Returns the error code that executes this function. A value of zero means that no errors have occurred.

Example:

LPVOID                lpPrivate;
LPFNIG_ERRSTACK_ADD   lpfnAdd;
LPFNIG_ERRSTACK_CLEAR lpfnClear;

...

Sample: FILTERS, MULTIMED, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_err_callback_set

Group: Library Utility

Declaration:

AT_ERRCODE ACCUAPI IG_err_callback_set(
    [IN] LPVOID lpPrivate,
    [IN] LPFNIG_ERRSTACK_ADD lpfnAddCB,
    [IN] LPFNIG_ERRSTACK_CLEAR lpfnClearCB
);

Arguments:

lpPrivate
Any private data. NULL is acceptable.
lpfnAddCB
Pointer to the callback function that will be called after the record is added to the error stack. NULL is acceptable.
lpfnClearCB
Pointer to the callback function that will be called after the error stack is cleared. NULL is acceptable.

Description:

This is the associated callback data, which functions with the error stack that flags error stack changes. Declare the following types for this function:

typedef VOID (LPACCUAPI LPFNIG_ERRSTACK_ADD)(
LPVOID lpPrivate, - pointer to private data
UINT nRecord, - index of error record in the stack
INT iLineNumber, - the number of line where error occured
AT_ERRCODE  iCode, - error code
UINT nLevel, - level of error, 0 - critical error (stop
execution), >0 - warning of different levels
LONG lValue1, - associated long value
LONG lValue2, - associated long value
LPCHAR lpFileName, - string of source file name where error
occured
LPCHAR lpExtratext - additional error description
);
typedef VOID (LPACCUAPI LPFNIG_ERRSTACK_CLEAR)(
LPVOID lpPrivate, -  pointer to private data.
UINT nRecords - number of records cleared from the stack
starting from 0 index.
);
NOTE: See also IG_err_callback_get() function.

Bits Per Pixel: Not applicable

Return Value:

Returns the error code that executes this function. A value of zero means no errors have occurred.

Example:

 ...
/* set callback function to output error records to the window
with handle hWnd */
IG_err_callback_set( (LPVOID)hWnd, ErrAdd, ErrClear );
 ...
}
VOID ACCUAPI ErrAdd(
LPVOID lpPrivate,
UINT nRecord,
INT iLineNumber,
AT_ERRCODE  iCode,
UINT nLevel,
LONG lValue1,
LONG lValue2,
LPCHAR lpFileName,
LPCHAR lpExtratext
)
{
   HWND   hWnd = (HWND)lpPrivate;
  ...
   /* update error window with new records */
}
VOID ACCUAPI ErrClear(
LPVOID lpPrivate,
UINT nRecords
)
{
   HWND   hWnd = (HWND)lpPrivate;
  ...
   /* remove records from error window */
}

Sample: FILTERS, THREADS, MULTIMED, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_err_count_get

Group: Library Utility

Declaration:

AT_ERRCODE ACCUAPI IG_err_count_get( VOID );

Arguments:

(none)

Description:

This function returns the total number of records (errors + warnings) in the error stack.

NOTE: See also IG_err_callback_get() function.

Bits Per Pixel: Not applicable

Return Value:

Returns the total count of records in the error stack.

Example:

AT_ERRCOUNT iErrCount;
IErrCount = IG_err_count_get( );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_err_error_check

Group: Library Utility

Declaration:

AT_ERRCODE ACCUAPI IG_err_error_check(
    [IN] UINT  nLevel
);

Arguments:

nLevel
Level of errors to count.

Description:

This function counts number of records of the specified level in the error stack.

NOTE: See also IG_err_callback_get() function.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of records in the stack of the given level.

Example:

AT_ERRCOUNT iErrCount;
/* get number of records of level 0 "
iErrCount = IG_err_error_check( 0  );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_err_error_get

Group: Library Utility

Declaration:

AT_ERRCODE ACCUAPI IG_err_error_get(
    [IN] UINT nLevel,
    [IN] UINT nIndex,
    [IN] LPCHAR lpsFileName,
    [IN] UINT nFNameSize,
    [IN] LPINT pnLineNumber,
    [IN] LPAT_ERRCODE lpnCode,
    [IN] LPAT_INT  lplValue1,
    [IN] LPAT_INT  lplValue2,
    [IN] LPCHAR lpExtraText,
    [IN] UINT nETextSize
);

Arguments:

nLevel
Level of errors to to index.
Nindex
Zero-based record index of the given level
lpsFileName
Pointer indicating where to return the source's file name where the error occurred.
nFNameSize
Size of the memory buffer lpsFileName.
lpnLineNumber
Pointer indicating where to return the line number where the error occurred.
LpnCode
Pointer indicating where to return the error code.
lplValue1
Pointer indicating where to return the first associated long value.
lplValue2
Pointer indicating where to return the second associated long value.
lpExtraText
Pointer indicating where to return the additional text description.
nETextSize
The size of the memory lpExtraText.

Description:

This function returns information about the record from error stack with the given index. The difference between this function and IG_err_record_get () is that this index exists for records with the specified level, nLevel; not for all records of in the stack.

NOTE: See also IG_err_callback_get() function.

Bits Per Pixel: Not applicable

Return Value:

Returns the error code when this function is executed. A value of zero means no errors have occurred.

Example:

AT_ERRCOUNT iErrCount, i;
CHAR         FileName[_MAX_PATH];
INT          nLineNumber;
AT_ERRCODE   nCode;
/* get all errors of level 0 */
iErrCount = IG_err_error_check( 0 );
for( i = 0; i<iErrCount; i++ )
{
   IG_err_error_get( 0, i, FileName, sizeof(FileName),
&nLineNumber, &nCode, NULL, NULL, NULL, 0 );
  ...
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_err_error_set

Group: Library Utility

Declaration:

AT_ERRCODE ACCUAPI IG_err_error_set(
    [IN] const LPCHAR lpFileName,
    [IN] INT iLineNumber,
    [IN] AT_ERRCODE nCode,
    [IN] UINT nLevel,
    [IN] AT_INT lplValue1,
    [IN] AT_INT lplValue2,
    [IN] constLPCHAR lpExtraText,
);

Arguments:

lpFileName
A long pointer to a string that supplies the name of the module from which the error was generated. It is recommended that you use the FILE constant in this field.
iLineNumber
An integer number indicating the line from which the error was set. It is recommended that you use the _LINE_ constant in this field.
nCode
An integer value of type AT_ERRCODE. Set this to the code number of the error that you wish to place on the error stack. If you will be placing an error on the stack that you have defined yourself, be sure to set it to a number that is less than the current value of IG_LAST_ERROR_NUMBER.
nLevel
The level of error. 0 means most critical error (stop execution). 1,2,... means records of type "warning."
lplValue1
lplValue2
These LONG arguments are available so that you may supply any supporting information about the error. Your application might use these values to decide what to do after setting a particular kind of error.
lpExtraText
Additional text description of the error. It can be NULL if it is not available.

Description:

This function is called to place an ImageGear error on the error stack.

Bits Per Pixel: Not applicable

Return Value:

Returns the error code when this function is executed. A value of zero means no errors have occurred.

Example:

/* set application specific waining */
IG_err_error_set( FILE, LINE, -1, 2, 0, 0, "Some explanation"
);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_errmngr_callback_get

Group: Library Utility

Declaration:

AT_ERRCODE  ACCUAPI IG_errmngr_callback_get(
    LPVOID FAR* lplpPrivate,
    LPFNIG_ERRMNGR_ADD FAR* lplpfnAddCB,
    LPFNIG_ERRMNGR_CLEAR FAR* lplpfnClearCB
);

Arguments:

lpPrivate
Pointer to a variable to retrieve private information passed in when you register callbacks.
lpfnAddCB
Pointer to a variable to retrieve a pointer to the callback function that is called each time a new error record is added.
lpfnClearCB
Pointer to a variable to retrieve a pointer to the callback function that is called each time a error stack is cleared.

Description:

ImageGear allows you to register callback functions that will be called each time new record is added or an error stack is cleared. An error stack is thread-dependent, so each thread has its own independent error stack. There are two types of callbacks - local to thread and global. This API allows you to get global (thread independent) callbacks.

Bits Per Pixel: N/A

Return Value:

Returns error code indicating success or failure: 0 - success, otherwise failure.

NOTE: See also the IG_errmngr_callback_set() function.

Example:

iErrCode	 = IG_errmngr_callback_get( &Private, &lpfnAdd,
&lpfnClear );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_errmngr_callback_set

Group: Library Utility

Declaration:

AT_ERRCODE  ACCUAPI IG_errmngr_callback_set(
    LPVOID lpPrivate,
    LPFNIG_ERRMNGR_ADD lpfnAddCB,
    LPFNIG_ERRMNGR_CLEAR lpfnClearCB
);

Arguments:

lpPrivate
Private information to be passed to a callback function each time it is called.
lpfnAddCB
Pointer to the a callback function that is called each time a new error record is added.
lpfnClearCB
Pointer to the callback function that is called each time a error stack is cleared.

Description:

This API allows to set global (thread independent) callbacks. See IG_errmngr_callback_get () function for more detailed description.

Bits Per Pixel: N/A

Return Value:

Returns error code indicating success or failure: 0 - success, otherwise failure.

Example:

iErrCode = IG_errmngr_callback_set( NULL, ErrGlAddCB,
ErrGlClearCB );

Sample: Threads

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_err_record_get

Group: Library Utility

Declaration:

AT_ERRCODE ACCUAPI IG_err_record_get(
    [IN] UINT nIndex,
    [IN] LPCHAR lpsFileName,
    [IN] UINT nFNameSize,
    [IN] LPINT lpnLineNumber,
    [IN] LPAT_ERRCODE lpnCode,
    [IN] LPUINT lpnLevel,
    [IN] LPAT_INT lplValue1,
    [IN] LPAT_INT lplValue2,
    [IN] LPCHAR lpExtraText,
    [IN] UINT nETextSize
);

Arguments:

nIndex
Zero based index of the record.
lpsFileName
Pointer indicating where to return the source's file name where the error occurred.
nFNameSize
The buffer memory size of lpsFileName.
lpnLineNumber
Pointer indicating where to return the line number where the error occurred.
lpnCode
Pointer indicating where to return the error code.
lpnLevel
Pointer indicating where to return the error level.
lplValue1
Pointer error where to return the first associated long value.
lplValue2
Pointer where to return the second associated long value.
lpExtraText
Pointer indicating where to return additional text description.
nETextSize
The size of memory lpExtraText.

Description:

This function returns information about the record from the error stack with the given index. This index is the general index of all records in the stack. The difference between this function and IG_err_error_get () is that this function enumerates all records rather than only records of a given level.

NOTE: See also IG_err_callback_get()function.

Bits Per Pixel: Not applicable

Return Value:

Returns the error code of executing of this function. A value of zero means no errors have occurred.

Example:

AT_ERRCOUNT iErrCount, i;
CHAR         FileName[_MAX_PATH];
INT          nLineNumber;
AT_ERRCODE   nCode;
UINT         nLevel;
/* get all records from error stack. */
iErrCount = IG_err_count_get( );
for( i = 0; i<iErrCount; i++ )
{
   IG_err_record_get( i, FileName, sizeof(FileName),
&nLineNumber, &nCode, &nLevel, NULL, NULL, NULL, 0 );
  ...
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_err_stack_clear

Group: Library Utility

Declaration:

AT_ERRCODE ACCUAPI IG_err_stack_clear( VOID );

Arguments:

None.

Description:

This function remove all records from the error stack.

NOTE: See also IG_err_callback_get() function.

Bits Per Pixel: Not applicable

Return Value:

Returns the error code of executing this function. A value of zero means no errors have occurred.

Example:

/* clear error stack */
IG_err_error_clear();

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_error_check

Group: Library Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_error_check( VOID );

Arguments:

None.

Description:

Returns to you the number of errors currently on the ImageGear error stack. A value of zero means no ImageGear errors have occurred during your last IG_ function call.

NOTE: See also IG_error_get(), IG_error_set(), and IG_error_clear()functions.

Bits Per Pixel: Not applicable

Return Value:

This function returns the number of errors currently on the ImageGear error stack. Since each IG_ function, excluding all IG_dspl_...() functions, cleares the error stack automatically upon entry, this will equal the number of errors that occurred during your last IG_ function call.

Example:

See the example for function IG_error_clear ().

Sample: THREADS, IMG_PROC, MFC, TWAIN, SCAN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_error_clear

Group: Library Utility

Declaration:

void ACCUAPI IG_error_clear( VOID );

Arguments: None

Description:

Clears all errors from the error stack. After calling this function, IG_error_check () will return zero.

Bits Per Pixel: Not applicable

Example:

BYTE szModuleName[30]; /* Will hold ret'd module name, up to 29
chars */
INT  iNameArraySize; /* Will hold size of that BYTE array */
INT  iLineNumber;      /* Will hold returned line number */
AT_ERRCODE  iCode;   /* Will hold returned error code */
AT_ERRCOUNT nErrcount; /* Will hold count of errors on stack */
INT n; 	   /* Will be Loop Index and Error Index Number */
iNameSize = 30; /* Size of module-name array */
nErrcount = IG_error_check();/* Obtain number of errors on stack
         */
for ( n = 0; n < nErrcount; n++ )/* For each error on stack */
   {
/* Get Error Code, Module Name, Line Number:  */
   IG_error_get( n, &szModuleName, iNameSize,
&iLineNumber, &iCode, NULL, NULL );
   /* ... Process or Display Error, etc. */
   }
IG_error_clear ();/* Done getting errs, clear error stack */

Sample: Barcode

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_error_get

Group: Library Utility

Declaration:

void ACCUAPI IG_error_get (INT iErrorIndex,
    LPSTR szFileName,
    INT cbFileNameSize,
    LPINT lpiLineNumber,
    LPAT_ERRCODE lpiCode,
    LPAT_INT  lplValue1,
    LPAT_INT  lplValue2
);

Arguments:

iErrorIndex
A value of 0 means fetch the first error placed on the stack. Tells which error to fetch from stack.
szFileName
Far pointer to where to return the module name in which this error occurred. If this pointer is NULL, the module name is not returned
cbFileNameSize
Number of bytes available in byte array pointed to by szFileName
lpiLineNumber
Far pointer to where to return the line number at which the error occurred. If NULL, the line number is not returned
lpiCode
Far pointer to where to return the Error Code. If NULL, the Error Code is not returned
lplValue1
Far pointer to where to return a value stored as lValue1 when the error occurred. If NULL, this value is not returned. See below for explanation of lValue1 and lValue2
lplValue2
Far pointer to where to return a value stored as lValue2 when the error occurred. If NULL, this value is not returned

Description:

This function is called to fetch an ImageGear Error Code and associated information from the error stack.

Set iErrorIndex to indicate which error you wish to fetch. iErrorIndex = 0 means the error added to the stack first. The other arguments (except cbFileNameSize) are FAR pointers telling this function where to return the retrieved information to you. This information consists of the Error Code, the module name and line number at which the error occurred, and two additional values (lValue1 and lValue2) which may provide additional information about the error. See the "Appendix: Function Error Return Codes" for a list of all ImageGear Error Codes and the significance of lValue1, lValue2 where applicable.

NOTE: To determine the number of errors currently on the error stack use IG_error_check(). After fetching all error information you need using IG_error_get(), use IG_error_clear() to clear the stack. See the example below.

Bits Per Pixel: Not applicable

Example:

INT	 i; /* Will hold Loop Index and Error Index */
INT	 iLineNumber;/* Will hold returned Line Number */
BYTE	 szFileName[30]; /* Will hold ret'd module name, up to 29
chars */
INT	 cbFileNameSize; /* Will hold size of szFileName array */
LONG	 lValue1, lValue2;/* Will hold returned lValue1, lValue2 */
AT_ERRCODE  iCode; /* Will hold returned ImageGear Error Code */
AT_ERRCOUNT  nErrcount;/* Will hold count of errors on error
stack    */
BYTE	 szBuf[60];/* Will hold zero-terminated string returned by
wsprintf() below */
cbFileNameSize = 30;/* Size of module-name array */
nErrcount = IG_error_check(); /* Get number of errors on stack
*/
for ( i = 0;  i < nErrcount;  i++ )
    {
    /* Get Module Name, Line Number, Error Code, and lValue1,
lValue2: */
    IG_error_get ( i, (LPSTR) &szFileName,
        cbFileNameSize, &iLineNumber, (LPAT_ERRCODE)
        &iCode, (LPLONG) &lValue1, (LPLONG) &lValue2 );
    /* Format error message in szBuf: */
    wsprintf ( szBuf, "Error %d in Module %s at Line
%d", iCode, szFileName, iLineNumber );
/* Display error message in a Message Box, with heading "Error"
: */
    MessageBox ( NULL, szBuf, "Error", MB_OK );
    }
IG_error_clear(); /* Done getting errors, clear the error stack
*/

Sample: THREADS, MFC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_error_set

Group: Library Utility

Declaration:

void ACCUAPI IG_error_set (
    const LPSTR szFileName,
    INT iLineNumber,
    AT_ERRCODE iCode,
    AT_INT  lValue1,
    AT_INT  lValue2
);

Arguments:

szFileName
A long pointer to a string that supplies the name of the module from which the error was generated. It is recommended that you use the _FILE_ constant in this field.
iLineNumber
An integer telling ImageGear from which line the error was set. It is recommended that you use the _LINE_ constant in this field.
iCode
An integer value of type AT_ERRCODE. Set this to the code number of the error that you wish to place on the error stack. If you will be placing an error on the stack that you have defined yourself, be sure to set it to a number that is less than the current value of IG_LAST_ERROR_NUMBER.
lValue1
lValue2
These LONG arguments are available so that you may supply any supporting information about the error. Your application might use these values to decide what to do after setting a particular kind of error.

Description:

This function is called to place an ImageGear error onto the error stack.

One use for this function is with the callback functions. It allows you to write the loading and saving of DIBs and individual raster lines (IG_load_FD_CB (), IG_save_FD_CB_ex ()) to the handle. Each of these functions call your callback functions in order to supply data, such as width, height, and Bits Per Pixel, to ImageGear. Your callback functions (which must be of type LPFNIG_DIB_GET, LPFNIG_RASTER_GET, LPFNIG_DIB_CREATE, and LPFNIG_RASTER_SET), must return an error count to IG_load_FD_CB () and IG_save_FD_CB(). You would do this by calling IG_error_check () after each raster is loaded or saved. If you wanted to terminate the load or save, you could use IG_error_set() to place the ImageGear error of your choosing, upon the stack.

TIP: If you are setting an error code that you have defined yourself, you must make sure that it has a value less than ImageGear's IG_LAST_ERROR_NUMBER. As the defined value of IG_LAST_ERROR_NUMBER may change in the future, you should always use the constant name during your check, not the integer value. For example: #define MYERROR1 (IG_LAST_ERROR_NUMBER - 1) #define MYERROR2 (IG_LAST_ERROR_NUMBER - 2)

Bits Per Pixel: Not applicable

Example:

#define MYERR_BAD_RASTER (IG_LAST_ERROR_NUMBER - 1)
 ...
AT_ERRCODE  iCode;  /* Initialize an integer of type AT_ERRCODE
*/
AT_ERRCOUNT nErrcount; /* Count of returned errors on stack */
LPFNIG_DIB_GET MyDIBGet;  	/* Will provide DIB header     */
LPFNIG_RASTER_GET MyRasterGet;  /* Will provide each raster */
INT	 fd; 	/* File Descriptor handle     	  */
DWORD	 dwPrivate[10]; 	/* Some private data  	  	 	  */
BYTE	 szFileName[30];		/* Will set name of guilty module 						 		  */
nErrcount = IG_save_FD_CB ( fd, 1, 0, IG_SAVE_BMP_UNCOMP,
MyRasterGet, MyDIBGet, (LPVOID) &dwPrivate );
 ...
AT_ERRCOUNT  ACCUAPI MyRasterGet (LPVOID lpPrivate, LPAT_PIXEL
lpRast, AT_PIXPOS lYpos, DWORD dwPrivate)
{
 ...
    /* if error found in raster line just read */
    If (bytes_read!=bytes_expected){
        nErrcount = IG_error_set(FILE,LINE,
        MYERR_BAD_RASTER,bytes_read, bytes_expected);
    }
 ...
return IG_error_check();
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_extra_channel_info_color_ID_get

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_color_ID_get(
    HIGEXTRACHANNELINFO hInfo,
    AT_QWORD *lpColorID
);

Parameters:

hInfo
Extra channel object.
lpColorID
Returns Color ID of this extra channel.

Description:

This method gets Color ID of the extra channel.

NOTE: This method is only applicable to the extra channel object with IG_EXTRA_CHANNEL_COLOR_TYPE_Vendor color type.


IG_extra_channel_info_colorspace_get

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_colorspace_get(
    HIGEXTRACHANNELINFO hInfo,
    enumIGColorSpaceIDs * colorSpace
);

Parameters:

hInfo
Extra channel object.
colorSpace
Returns color space of this extra channel.

Description:

This method gets color space of the extra channel.

NOTE: This method is only applicable to the extra channel object with IG_EXTRA_CHANNEL_COLOR_TYPE_Colorspace color type.


IG_extra_channel_info_color_type_get

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_color_type_get(
    HIGEXTRACHANNELINFO hInfo,
    enumIGExtraChannelColorType * lpColorType
);

Parameters:

hInfo
Extra channel object.
lpInternalType
Extra channel color type.

Description:

This method gets extra channel color type (Color space or Vendor).

NOTE: This method is only applicable to the extra channel object with IG_EXTRA_CHANNEL_COLOR_TYPE_Colorspace color type.


IG_extra_channel_info_color_value_copy_get

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_color_value_copy_get(
    HIGEXTRACHANNELINFO hInfo,
    HIGPIXEL * hPixel
);

Parameters:

hInfo
Extra channel object.
hPixel
Returns color value of this extra channel.

Description:

This method gets color value of the extra channel.

NOTE: This method is only applicable to the extra channel object with IG_EXTRA_CHANNEL_COLOR_TYPE_Colorspace color type.


IG_extra_channel_info_color_value_copy16_get

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI
IG_extra_channel_info_color_value_copy16_get(
    HIGEXTRACHANNELINFO hInfo,
    HIGPIXEL * hPixel
);

Parameters:

hInfo
Extra channel object.
hPixel
Returns color value of this extra channel (forced to 16 bits).

Description:

This method gets color value of the extra channel.

NOTE: This method is only applicable to the extra channel object with IG_EXTRA_CHANNEL_COLOR_TYPE_Colorspace color type.


IG_extra_channel_info_color_value_copy8_get

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI
IG_extra_channel_info_color_value_copy8_get(
    HIGEXTRACHANNELINFO hInfo,
    HIGPIXEL * hPixel
);

Parameters:

hInfo
Extra channel object.
hPixel
Returns color value of this extra channel (forced to 8 bits).

Description:

This method gets color value of the extra channel.

NOTE: This method is only applicable to the extra channel object with IG_EXTRA_CHANNEL_COLOR_TYPE_Colorspace color type.


IG_extra_channel_info_create_color_channel

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_create_color_channel
(
    enumIGColorSpaceIDs colorSpace,
    HIGPIXEL colorValue,
    HIGEXTRACHANNELINFO *hInfo
);

Parameters:

colorSpace
Color space for the new spot channel
colorValue
Color value for the new spot channel
hInfo
Returns HIGEXTRACHANNELINFO object.

Description:

This method creates a new spot channel that uses regular color space like RGB, CMYK etc and color value.


IG_extra_channel_info_create_maskcolor_channel

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI
IG_extra_channel_info_create_maskcolor_channel (
    enumIGMaskChannelModes mode,
    enumIGColorSpaceIDs colorSpace,
    HIGPIXEL colorValue,
    HIGEXTRACHANNELINFO *hInfo
);

Parameters:

mode
Mask mode for the new mask channel
colorSpace
Color space for the new mask channel
colorValue
Color value for the new mask channel
hInfo
Returns HIGEXTRACHANNELINFO object.

Description:

This method creates a new alpha mask channel that uses regular color space like RGB, CMYK etc and color value.


IG_extra_channel_info_create_maskspot_channel

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI
IG_extra_channel_info_create_maskspot_channel (
    enumIGMaskChannelModes mode,
    enumIGSpotColorVendorIDs vendorID,
    AT_QWORD colorID,
    HIGEXTRACHANNELINFO *hInfo
);

Parameters:

mode
Mask mode for the new mask channel
vendorID
Vendor ID for the new mask channel
colorID
Color ID for the new mask channel
hInfo
Returns HIGEXTRACHANNELINFO object.

Description:

This method creates a new alpha mask channel that uses a special (like Pantone) color. This channel does not store a color name, but looks it up from the loaded color books.


IG_extra_channel_info_create_spot_channel

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_create_spot_channel (
    enumIGSpotColorVendorIDs vendorID,
    AT_QWORD colorID,
    HIGEXTRACHANNELINFO *hInfo
);

Parameters:

vendorID
Vendor ID for the new spot channel
colorID
Color ID for the new spot channel
hInfo
Returns HIGEXTRACHANNELINFO object.

Description:

This method creates a new spot channel that uses a special (like Pantone) color. This channel does not store a color name, but looks it up from the loaded color books.


IG_extra_channel_info_create_unknown_channel

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI
IG_extra_channel_info_create_unknown_channel (
    HIGEXTRACHANNELINFO *hInfo
);

Parameters:

hInfo
Returns HIGEXTRACHANNELINFO object.

Description:

This method creates new extra channel info, with unknown channel type.


IG_extra_channel_info_delete

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_delete(
    HIGEXTRACHANNELINFO hInfo
);

Parameters:

hInfo
HIGEXTRACHANNELINFO object to release.

Description:

This method releases memory used by this extra channel info object.


IG_extra_channel_info_mode_get

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_mode_get(
    HIGEXTRACHANNELINFO hInfo,
    enumIGMaskChannelModes *mode
);

Parameters:

hInfo
Extra channel object.
mode
Returns Mask mode of this extra channel.

Description:

This method gets mode of Mask extra channel.

NOTE: This method is only applicable for IG_EXTRA_CHANNEL_TYPE_Mask channel type.


IG_extra_channel_info_name_get

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_name_get(
    HIGEXTRACHANNELINFO hInfo,
    LPCHAR *lpName
);

Parameters:

hInfo
Extra channel object.
lpName
Name of this extra channel.

Description:

This method gets name of the extra channel.


IG_extra_channel_info_name_set

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_name_set(
    HIGEXTRACHANNELINFO hInfo,
    LPCHAR lpName
);

Parameters:

hInfo
Extra channel object.
lpName
New name for this extra channel.

Description:

This method sets new name for the specified extra channel.


IG_extra_channel_info_opacity_get

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_opacity_get(
    HIGEXTRACHANNELINFO hInfo,
    LPAT_WORD lpOpacity
);

Parameters:

hInfo
Extra channel object.
lpOpacity
Returns opacity value of this extra channel.

Description:

This method gets opacity of the extra channel.

NOTE: This method is applicable to any type of extra channels except IG_EXTRA_CHANNEL_TYPE_Unknown.


IG_extra_channel_info_opacity_set

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_opacity_set(
    HIGEXTRACHANNELINFO hInfo,
    AT_WORD Opacity
);

Parameters:

hInfo
Extra channel object.
Opacity
New opacity value for this extra channel (should be in range 0-100).

Description:

This method sets new opacity for the extra channel.

NOTE: This method is applicable to any type of extra channels except IG_EXTRA_CHANNEL_TYPE_Unknown.


IG_extra_channel_info_type_get

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_type_get(
    HIGEXTRACHANNELINFO hInfo,
    enumIGExtraChannelType * lpType
);

Parameters:

hInfo
Extra channel object.
lpType
Extra channel type.

Description:

This method gets extra channel type (Unknown, Mask or Spot).


IG_extra_channel_info_vendor_ID_get

Group: Extra Channel

Declaration:

AT_ERRCOUNT ACCUAPI IG_extra_channel_info_vendor_ID_get(
    HIGEXTRACHANNELINFO hInfo,
    enumIGSpotColorVendorIDs * lpVendorID
);

Parameters:

hInfo
Extra channel object.
lpVendorID
Returns Vendor ID of this extra channel.

Description:

This method gets Vendor ID of the extra channel.

NOTE: This method is only applicable to the extra channel object with IG_EXTRA_CHANNEL_COLOR_TYPE_Vendor color type.


IG_file_IO_register

Group: Callback

Declaration:

AT_ERRCOUNT ACCUAPI IG_file_IO_register (
    LPFNIG_READ lpfnReadFunc,
    LPFNIG_WRITE lpfnWriteFunc,
    LPFNIG_SEEK lpfnSeekFunc
);

Arguments:

lpfnReadFunc
Far pointer to your function to be called for READs
lpfnWriteFunc
Far pointer to your function to be called for WRITEs
lpfnSeekFunc
Far pointer to your function to be called for SEEKs

Description:

This function registers your own functions to be called to do Reads, Writes, and Seeks during image file transfers. An argument should be NULL if you want ImageGear to perform that operation. See also the descriptions for typedefs LPFNIG_READ, LPFNIG_WRITE, and LPFNIG_SEEK.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

LPFNIG_READ		 MyReadFunc;      /* To be called for file READs */
{
HIGEAR		 hIGear;     /* Will hold HIGEAR handle of image  */
 ...
IG_file_IO_register ( MyReadFunc, NULL, NULL );/* Register it */
 ...
IG_load_file ( "picture.bmp", &hIGear );
 ...
}
/* This will be called for each read during the above Load:   */
LONG  ACCUAPI MyReadFunc ( LONG fd, LPBYTE lpBuffer,
    LONG lNumToRead )
{
LONG	 nNumActuallyRead;
 ...   /* May transfer bytes to buffer in any way     */
return  nNumActuallyRead; /* Return count, or -1 for error  */
}

Sample: IOSET

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_compressionlist_get

Group: Format filters

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_fltr_compressionlist_get (
    [IN] LPAT_DIB lpDIB,
    [IN] AT_MODE nFormatID,
    [OUT] LPAT_MODE lpComprList,
    [IN] UINT nCListSize,
    [OUT] LPUINT lpnCListCount
);

Arguments:

lpDIB
Pointer to the AT_DIB structure that contains image parameters. If NULL, then this function retursn all possible compressions.
nFormatID
File format identifier of the IG_FORMAT_... constant.
lpComprList
Pointer to the array indicating where to return list of IG_COMPRESSION_...compression constants
nCListSize
The size of array lpCompList
lpnCListCount
Pointer indicating where to receive the actual number of compression constants.

Description:

This function allows you to get information about which compressions are applicable when saving an image with parameters given in the lpDIB header into the file format specified by identifier nFormatID. If lpDIB is NULL, this function returns all supported compressions by this format filter. When lpComprList is NULL, this function returns number of compressions through the lpnCListCount parameter. If lpCompList is not NULL, then this function copies the correspondent compression constants (IG_COMPRESSION_...) into this array. nCListSize specifies the size of lpComprList if it is not NULL.

See also the section Using Format Filters API for Image Saving.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear; /* Will hold handle returned by IG_load_file*/
AT_ERRCOUNT  nErrCount;  /* Count of errs on stack upon ret from
func*/
UINT nCount;
LPAT_DIB  lpDIB;
LPAT_MODE  lpCompList;
/* Figure out compressions that given HIGEAR is possible to save
into TIFF format */
nErrCount = IG_image_DIB_pntr_get( hIGear, &lpDIB );
if( nErrCount==0 )
{
    /* get number of compressions */
    IG_fltr_compressionlist_get( lpDIB, IG_FORMAT_TIF, NULL, 0,
&nCount );
    lpCompList = (LPAT_MODE)malloc( nCount*sizeof(AT_MODE) );
    if( lpCompList!=NULL )
    {
    IG_fltr_compressionlist_get( lpDIB, IG_FORMAT_TIF,
lpCompList, nCount, &nActual );
  ...
 free( lpCompList );
    }
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_compressionlist_get_ex

Group: Format Filters

Declaration:

AT_ERRCOUNT ACCUAPI IG_fltr_compressionlist_get_ex(
    const HIGDIBINFO hDIB,
    AT_MODE nFormatID,
    LPAT_MODE lpComprList,
    UINT nCListSize,
    LPUINT lpnCListCount
);

Arguments:

hDIB
Handle of DIB info object that contains image parameters. If NULL, then this function returns all possible compressions.
nFormatID
File format identifier of the IG_FORMAT_... constant.
lpComprList
Pointer to the array indicating where to return list of IG_COMPRESSION_...compression constants
nCListSize
The size of array lpCompList
lpnCListCount
Pointer indicating where to receive the actual number of compression constants.

Description:

This function allows you to get information about which compressions are applicable when saving an image with parameters given in the hDIB info object into the file format specified by identifier nFormatID.

If hDIB is NULL, this function returns all supported compressions by this format filter.

When lpComprList is NULL, this function returns number of compressions through the lpnCListCount parameter. If lpCompList is not NULL, then this function copies the correspondent compression constants (IG_COMPRESSION_...) into this array.

nCListSize specifies the size of lpComprList if it is not NULL.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGDIBINFO hDIB;        /* DIB info handle of image */
UINT nCount, nActual;   /* Number of compressions */
LPAT_MODE lpCompList;   /* List of compressions */
/* Get list of compressions that can be used when
   saving the given image into TIFF format */
nErrcount = IG_image_DIB_info_get(hImage, &hDIB);
nErrcount = IG_fltr_compressionlist_get_ex(hDIB,
    IG_FORMAT_TIF, NULL, 0, &nCount);
lpCompList = (LPAT_MODE) malloc(nCount * sizeof(AT_MODE));
nErrcount = IG_fltr_compressionlist_get_ex(hDIB,
    IG_FORMAT_TIF, lpCompList, nCount, &nActual);
/* lpCompList now contains list of compressions */
IG_DIB_info_delete(hDIB);
free(lpCompList);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_ctrl_get

Group: Format filters

Declaration:

AT_ERRCODE  EXPORT   ACCUAPI IG_fltr_ctrl_get(
    DWORD dwFormatID,
    const LPCHAR lpcsCtrlName,
    AT_BOOL bGetDefault,
    LPAT_MODE lpnValueType,
    LPDWORD lpdwValueSize,
    LPVOID lpBuffer,
    DWORD dwBufferSize
);

Arguments:

FormatID
Specifies ImageGear filter you want to get the info about. Set it using IG_FORMAT_ constants.
lpcsCtrlName
Specifies the name of control parameter you want to get the info about. The list of names of supported control parameters can be get using IG_fltr_ctrl_list().
bGetDefault
Each control parameter has default value and this parameter can be used to select what to return through lpBuffer parameter. If TRUE then default value of control parameter is returned through lpBuffer, but in other case current value is returned.
lpnValueType
Returns the value type of control parameter.
lpdwValueSize
Return the size of memory buffer that should be allocated for lpBuffer to completely fit returned value. If NULL then this parameter is ignored.
lpBuffer
Buffer where to return control parameter value.
dwBufferSize
The size of memory allocated for lpBuffer pointer. Please note that if it is less than value returned through lpdwValueSize then lpBuffer contains not all bytes of control parameter value.

Description:

This function allows you to get full information about every control parameter supported by ImageGear filter. It returns current value of lpcsCtrlName control parameter for dwFormatID filter (set it as IG_FORMAT_ constant) through lpBuffer. Also it returns the type of this control parameter value (lpnValueType). If you want to get default control parameter value set bGetDefault argument to TRUE. Note that your application is responsible for allocating free necessary memory for lpBuffer through dwBufferSize argument.

To change the current value of control parameter use function IG_fltr_ctrl_set ().

See also the section Using Format Filters API for Filter Control.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

...
/* setup JPEG decimation control parameter */
so.nDecimationIndex = GetPrivateProfileInt( lpszSaveSection,
lpszDecimationIndex,
100, lpszIniFileName);
   if( (so.nDecimationIndex<0) ||
(so.nDecimationIndex>=(sizeof(_JPG_decimate_array)/
sizeof(WORD))) )
   {
      WORD       decim;
      INT         i;
      so.nDecimationIndex = 0;
IG_fltr_ctrl_get( IG_FORMAT_JPG, "DECIMATION_TYPE", FALSE,
NULL, NULL, &decim, sizeof(decim) );
      for( i = 0; i<sizeof(_JPG_decimate_array)/sizeof(WORD);
i++ )
         if( decim==_JPG_decimate_array[i] )
         {
            so.nDecimationIndex = i;
            break;
         }
   }
...

Sample: ASCII, Vector, FlashPix, GUI, JPEG, PJPEG

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_ctrl_list

Group: Format filters

Declaration:

AT_ERRCODE  EXPORT   ACCUAPI  IG_fltr_ctrl_list (
    DWORD dwFormatID,
    LPUINT lpnCount,
    LPVOID lpArray,
    DWORD dwArraySizeInBytes
);

Arguments:

FormatID
Specifies ImageGear filter you want to get the info about. Set it using IG_FORMAT_ constants (See accucnst.h file).
lpnCount
Returns the number of supported control parameters for requested filter.
Array
Returns the array of control parameters for requested filter. Application is responsible to allocate memory for lpArray buffer but IG fills each element of this array with pointer to static string. Application is not allowed to change memory referenced by any of those string pointers.
ArraySizeInBytes
Provides the size (in bytes) of memory allocated for lpArray pointer.

Description:

This function allows you to get the list of control parameters for each ImageGear filter you specify using FormatID argument.

See also the section Using Format Filters API for Filter Control.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_ctrl_set

Group: Format filters

Declaration:

AT_ERRCODE  EXPORT   ACCUAPI  IG_fltr_ctrl_set(
    DWORD dwFormatID,
    const LPCHAR lpcsCtrlName,
    LPVOID lpValue,
    DWORD dwValueSize
);

Arguments:

FormatID
Specifies ImageGear filter wich control parameter you want to set. Set it using IG_FORMAT_ constants.
lpcsCtrlName
Specifies the name of control parameter you want to set. The list of names of supported control parameters can be get using IG_fltr_ctrl_list ().
lpValue
Specifies new value to set for control parameter with name lpcsCtrlName. General rule for format is following. If size of value is <= sizeof(DWORD) then lpValue should contain actual value but in other case it should contain pointer to value.
dwValueSize
Specifies the size (in bytes) of control parameter value.

Description:

This function allows you to set the control parameter value specified by lpcsCtrlName for the format filter specified by FormatID.

See also the section Using Format Filters API for Filter Control.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

...
    {
    case	 IDCANCEL:
        EndDialog( hWnd, FALSE );
        break;
    case IDOK:
/* close the dialog box when the OK button is pressed */
    nIndex = SendDlgItemMessage( hWnd, IDC_LIST, CB_GETCURSEL,
0, 0 );
    IG_fltr_ctrl_set( IG_FORMAT_JPG, "LOAD_SCANS",
(LPVOID)(LONG)(nIndex), sizeof(nIndex) );
    EndDialog(hWnd, TRUE);
    break;
    }
    break;
...

Sample: ASCII, Vector, Filter, FlashPix, GUI, JPEG, P-JPEG

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_detect_FD

Group: Format filters

Declaration:

AT_ERRCOUNT IG_fltr_detect_FD(
    [IN] AT_INT fd,
    [IN] LONG lOffset,
    [OUT] LPAT_MODE lpFileType
);

Arguments:

fd
The file descriptor handle of the file in which to load the data. This is a handle (always an integer) obtained when using certain Windows functions, such as _lopen(), to open a file.
lOffset
The offset, in bytes, to the file in which the image begins. This is the offset to the beginning of the header, not to the beginning of the bitmap. lOffset is usually 0.
lpFileType
The pointer indicating where to return file format identifier.

Description:

This function detects the file format, specified by given file descriptor starting from the lOffset position in the file. It can be either IG_FORMAT_UNKNOWN if the format is unknown, or another IG_FORMAT_... value defined in accucnst.h.

See also the section Detecting the File Format.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrCount = IGE_SUCCESS;/* will hold returned error
count */
AT_MODE nFormatID;
INT fd;
fd = _lopen ( "image.tiff", OF_READ );
 ...
nErrCount = IG_fltr_detect_FD( fd, 0, &nFormatID );
if( nFormatID==IG_FORMAT_TIF )
{
     ...
}
_lclose( fd );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_detect_file

Group: Format filters

Declaration:

AT_ERRCOUNT   IG_fltr_detect_file(
    [IN] const LPSTR lpszFileName,
    [OUT] LPAT_MODE lpFileType
);

Arguments:

lpszFileName
The file name of image format you wish to detect.
lpFileType
A pointer indicating where to return the file format identifier.

Description:

This function detects the file format specified by a given filename. It can be either IG_FORMAT_UNKNOWN if the format is unknown, or another IG_FORMAT_... value defined in accucnst.h.

See also the section Detecting the File Format.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrCount = IGE_SUCCESS;/* will hold returned error
count */
AT_MODE nFormatID;
 ...
nErrCount = IG_fltr_detect_file( "image.tiff", &nFormatID );
if( nFormatID==IG_FORMAT_TIF )
{
     ...
}

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_detect_mem

Group: Format filters

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_fltr_detect_mem(
    [IN] VOID FAR* lpImage,
    [IN] AT_UINT nSize,
    [OUT] LPAT_MODE lpFileType
);

Arguments:

lpImage
A far pointer to the memory location of an image file that is currently in memory.
nSize
Size of image in memory.
lpFileType
A pointer indicating where to return the file format identifier.

Description:

This function detects the format of an image located in the memory specified by the pointer lpImage. It can be either IG_FORMAT_UNKNOWN if the format is unknown, or another IG_FORMAT_... value defined in accucnst.h.

See also the section Detecting the File Format.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrCount = IGE_SUCCESS; /* will hold returned error
count */
AT_MODE nFormatID;
INT fd;
LPBYTE lpPtr;
AT_UINT 	nSize;
fd = _lopen ( "image.tiff", OF_READ );
 ...
/* load file into memory */
 ...
_lclose( fd );
nErrCount = IG_fltr_detect_mem( lpPtr, nSize, &nFormatID );
if( nFormatID==IG_FORMAT_TIF )
{
     ...
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_formatlist_get

Group: Format filters

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_fltr_formatlist_get(
    [IN] DWORD dwFlags,
    [OUT] LPAT_MODE lpFormatList,
    [IN] UINT nFListSize,
    [OUT] LPUINT lpnFListCount
);

Arguments:

dwFlags
Any combination of IG_FLTR_... flags described in the IG_fltr_info_get () function, which specifies the format filter properties.
lpFormatList
An array in which to return the list of IG_FORMAT_... constants. If this value is NULL, the total number of formats is returned through the lpnFListCount parameter.
nFListSize
The size of lpFormatList array if it is not NULL.
lpnFListCount
If lpFormatList is not NULL, then the number of copied format identifiers are returned. Otherwise, the total number of formats is returned.

Description:

This function searches and returns the list of supported format filters with features specified by the dwFlags parameter. Possible values include any combination of IG_FLTR_... constants defined in the IG_fltr_info_get function. This function searches for filters that support ALL requested features (not just some of them).

The result is a list of IG_FILTER_... values returned through the second parameter, lpFormatList. The third parameter specifies its size if its value not NULL. The lpnFListCount parameter returns number of copied values if lpFormatList is not NULL and the total number of formats if it is NULL.

In general, to obtain a complete list of formats, you can call this function twice; the first time to get the number of values to allocate the lpFormatList array of the necessary size, and the second time to receive the actual values.

See also the section Getting Information and Sorting Images in Chapter Using ImageGear.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

AT_ERRCOUNT nErrCount; /* Count of errs on stack upon ret from
func*/
UINT nCount;
LPAT_MODE lpFormatList;
/* Get list filters that support detect and saving */
/* get total count */
nErrCount =
IG_fltr_formatlist_get(IG_FLTR_DETECTSUPPORT|IG_FLTR_PAGEINSERT
SUPPORT, NULL, 0, &nCount );
if( nErrCount==0 )
{
    /* allocate memory */
    lpFormatList = (LPAT_MODE)malloc( nCount*sizeof(AT_MODE) );
    if( lpFormatList!=NULL )
    {

IG_fltr_formatlist_get(IG_FLTR_DETECTSUPPORT|IG_FLTR_PAGEINSERT
SUPPORT, lpFormatList, nCount, NULL );
 ...
        free( lpFormatList );
    }
}

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_formatlist_sort

Group: Format filters

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_fltr_formatlist_sort(
    [IN/OUT] LPAT_MODE lpFormatList,
    [IN] UINT nFListSize
);

Arguments:

lpFormatList
An array of IG_FORMAT_... constants..
nFListSize
The size of lpFormatList array.

Description:

This auxiliary function sorts formats in alphabetic order based on the short format name returned through the third parameter of function IG_fltr_info_get ().

See also the section Getting Information and Sorting Images.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

AT_ERRCOUNT	 	nErrCount; /* Count of errs on stack upon ret from
func */
UINT nCount;
LPAT_MODE lpFormatList;
/* Get list filters that support detect and saving */
/* get total count */
nErrCount =
IG_fltr_formatlist_get(IG_FLTR_DETECTSUPPORT|IG_FLTR_PAGEINSERT
SUPPORT, NULL, 0, &nCount );
if( nErrCount==0 )
{
    /* allocate memory */
    lpFormatList = (LPAT_MODE)malloc( nCount*sizeof(AT_MODE) );
    if( lpFormatList!=NULL )
    {

IG_fltr_formatlist_get(IG_FLTR_DETECTSUPPORT|IG_FLTR_PAGEINSERT
SUPPORT,
     lpFormatList, nCount, NULL );
        /* sort formats in alphabetic order */
        IG_fltr_formatlist_sort( lpFormatList, nCount );
 ...
        free( lpFormatList );
    }
}

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_ICC_callback_get

Group: Format filters

Declaration:

AT_ERRCODE  ACCUAPI  IG_fltr_ICC_callback_get(
    LPVOID *lplpPrivate,
    LPAFT_IG_ICC_GET_CB *lplpfnGetCB,
    LPAFT_ANY *lplpfnReserved1,
    LPAFT_ANY *lplpfnReserved2
);

Arguments:

lplpPrivate
Private callback data.
lplpfnGetCB
GET callback function.
lplpfnReserved1
Reserved.
lplpfnReserved2
Reserved.

Description:

This function returns the current settings for callbacks that are used for reading and writing ICC profiles. It allows you to retrieve the settings of LPAFT_IG_ICC_GET_CB callback function.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: LoadCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_ICC_callback_set

Group: Format filters

Declaration:

AT_ERRCODE  ACCUAPI  IG_fltr_ICC_callback_set(
    LPVOID lpPrivate,
    LPAFT_IG_ICC_GET_CB lpfnGetCB,
    LPAFT_ANY lpfnReserved1,
    LPAFT_ANY lpfnReserved2
);

Arguments:

lpPrivate
Private callback data.
lpfnGetCB
GET callback function.
lpfnReserved1
Reserved.
lpfnReserved2
Reserved.

Description:

This function allows you to register your ICC callback LPAFT_IG_ICC_GET_CB function. It registers callbacks for reading and writing ICC profiles during loading and saving of image files.

  • ICC profile reading. Use any image loading function to load an image. As soon as the format filter encounters an ICC profile, it calls the callback function. The ICC profile is provided in the standard ICC format, as a byte array. The toolkit owns the buffer, so the application shall not delete it. If the application needs to use the ICC profile after exiting the callback, it shall copy it to its own buffer.
  • ICC profile writing. Use any image saving function to save an image. If the format filter supports ICC profile writing, it calls the callback function before writing the profile. If the HIGEAR being saved has an ICC profile attached to it, format filter ignores this profile and writes the profile obtained from the callback. The ICC profile shall be provided in the standard ICC format, as a byte array. The application owns the buffer, and is responsible for deleting it.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: LoadCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_info_get

Group: Format filters

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_fltr_info_get(
    [IN] AT_MODE nFormatID,
    [OUT] LPDWORD lpdwInfoFlags,
    [OUT] LPCHAR lpShortName,
    [IN] DWORD dwSNameSize,
    [OUT] LPCHAR lpFullName,
    [IN] DWORD dwFNameSize,
    [OUT] LPCHAR lpDefExt,
    [IN] DWORD dwDefExtSize
);

Arguments:

nFormatID
File format identifier of the IG_FORMAT_... constant.
lpdwInfoFlags
Pointer indicating where to receive the format flags, which can be a combination of the following flags:
IG_FLTR_DETECTSUPPORT
IG_FLTR_PAGEREADSUPPORT
IG_FLTR_MPAGEREADPSUPPORT
IG_FLTR_MPAGEWRITEPSUPPORT
IG_FLTR_PAGEINSERTSUPPORT
IG_FLTR_PAGEDELETESUPPORT
IG_FLTR_PAGESWAPSUPPORT
IG_FLTR_MPDATASUPPORT
If the value is NULL, this flag is ignored.
lpShortName
A pointer indicating where to copy the zero-terminated string with the short file format name. If the value is NULL, this flag is ignored.
dwSNameSize
The size of the lpShortName array in bytes.
lpFullName
A pointer indicating where to copy the zero-terminated string with the full file format name. If the value is NULL, this flag is ignored.
dwFNameSize
The size of array lpFullName in bytes.
lpDefExt
A pointer indicating where to copy the zero-terminated string with file masks separated by a semicolon (;). If the value is NULL, this flag is ignored.
dwDefExtSize
The size of lpDefExt array in bytes.

Description:

This function returns information about the format filter and its supported features. If lpdwInfoFlags in not NULL then the DWORD value is returned with combination of the following flags:

IG_FLTR_DETECTSUPPORT
Detect is supported
IG_FLTR_PAGEREADSUPPORT
Page read is supported
IG_FLTR_MPAGEREADPSUPPORT
In combination with IG_FLTR_PAGEREADSUPPORT, this flag means any page loading from a multi-page form
IG_FLTR_PAGEINSERTSUPPORT
Page write is supported
IG_FLTR_MPAGEWRITEPSUPPORT
In combination with IG_FLTR_PAGEINSERTSUPPORT, this flag means the page is inserted into a multi-page form support
IG_FLTR_PAGEDELETESUPPORT
Page delete support from multi-page formats
IG_FLTR_PAGESWAPSUPPORT
Page swap support for multi-page formats
IG_FLTR_MPDATASUPPORT
Supports faster multi-page access by storing private format data (used only with IG_mpi_... and IG_mpf_... API).

This function also returns short format name - usually 3-4 chars ("TIFF"), full format name ("Tagged Image File Format"), and default file extensions separated by ";" ("*.tif;*.tiff").

See also the section Getting Information and Sorting Images.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

AT_ERRCOUNT SaveImage(
    LPCHAR lpFileName,
    HIGEAR hIGear,
    AT_MODE nFormat,
    AT_MODE nCompression
)
{
    AT_ERRCOUNT nErrCount;
    DWORD dwFlags;
    CHAR FName[20];
    nErrCount = IG_fltr_info_get( nFormat, &dwFlags, FName,
sizeof(FName),
 NULL, 0, NULL, 0 );
    if( nErrCount==0 )
    if( (dwFlags&IG_FLTR_PAGEINSERTSUPPORT)!=0 )
    {
        nErrCount = IG_save_file( hIGear, lpFileName,
        nFormat|(nCompression<<16) );
    }else
        printf( "File format %s does not support image saving",
FName );
    return	 nErrCount;
}

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_load_FD_format

Group: Format Filters

Declaration:

AT_ERRCOUNT ACCUAPI IG_fltr_load_FD_format(
    AT_MODE nFormat,
    AT_INT fd,
    LONG lOffset,
    UINT nPageNumber,
    UINT nTileNumber,
    LPHIGEAR lphIGear
);

Arguments:

nFormat
File format id to load. If IG_FORMAT_UNKNOWN then usual detect works
fd
File descriptor
lOffset
Offset to image
nPageNumber
Page number to load
nTileNumber
Tile number to load, set to 1 for non-tiled image
lphIGear
Image Gear handle

Description:

This function is similar to IG_load_FD() function, but has an additional nFormat parameter that specifies the format of the file from which the image should be loaded. If nFormat = IG_FORMAT_UNKNOWN, then the usual loading procedure is performed. Otherwise, ImageGear loads the file with specified format filter.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_fltr_load_file

Group: Format filters

Declaration:

AT_ERRCOUNT    ACCUAPI    IG_fltr_load_file(
    const LPSTR lpszFileName,
    UINT nPageNumber,
    LPHIGEAR lphIGear
);

Arguments:

szFileName
Far pointer to FileName (you may include path with filename) of the multipage file from which an image should be loaded into memory.
nPageNumber
The PageNumber of the page-image to load into memory from the szFileName file.
hIGear
Far pointer to the HIGEAR object in which to return the ImageGear handle of the image.

Description:

This function loads an image from nPageNumber of szFileName file into memory and creates a DIB for that image. The handle that ImageGear assigns for this image is returned in the hIGear argument. The file named by szFileName may be in any format recognized by ImageGear. IG_fltr_load_file() will determine the format by inspecting the file's header section. See Chapter File Format Reference.

NOTE: Note that simply loading the file does not cause it to be displayed. Refer to IG_dspl_image_draw() and related routines, for how to display an image once it is in memory. See also IG_load_file_display().

See also the section Using the Format Filters API for Image Loading and Getting Information..

NOTE: Some file formats, such as TXT (ASCII Text), JPEG, and others, may be loaded with additional control, using IG_fltr_ctrl_get()and IG_fltr_ctrl_set(). See the description of these functions also in Using Format Filters API for Filter Control section.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

NOTE: This function can also be used to load Internet files. See the example code below. The function IG_load_internet() is a more versatile function for loading Internet files.

Example:

HIGEAR    hIGear     /* Will hold handle returned by
IG_fltr_load_file */
UINT      nPage
AT_ERRCOUNT nErrcount;   /* Count of errs on stack upon ret from
func*/
/* load the selected image */
nErrCount = IG_fltr_load_file(szFile, nPage, &hIGear );

Sample: ART, ASCII, CLPBRD, COLOR, DISPLAY, IMG_PROC,

JPEG, MEMIO, PAN, PIX_ACC, PJPEG, POSTER, PRINT,

IC, MULTIMED, Recognition, Scan, TEMPLATE, TWAIN, WIPES, GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_load_file_format

Group: Format filters

Declaration:

AT_ERRCOUNT EXPORT  ACCUAPI IG_fltr_load_file_format(
    AT_MODE nFormat,
    const LPSTR lpszFileName,
    UINT nPageNumber,
    LPHIGEAR lphIGear
);

Arguments:

nFormat
File format ID to load the file. It is specified by such constants as IG_FORMAT_. For the full list of these constants, see the accucnst.h file.
szFileName
Far pointer to the filename (you may include the path with the filename) of the multipage file from which an image should be loaded into memory.
nPageNumber
The PageNumber of the page-image to load into memory from the szFileName file.
hIGear
Far pointer to the HIGEAR object in which to return the ImageGear handle of the image.

Description:

This function is almost the same as the IG_fltr_load_file () function, but has an additional nFormat parameter that specifies the format of the file from which the image should be loaded. If nFormat = IG_FORMAT_UNKNOWN then an usual loading procedure is performed. In other case this procedure isn't performed, but ImageGear loads file with specified format filter.

See also the section Using the Format Filters API for Image Loading and Getting Information.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

...
/* Load the image specified on the command line (if any) */
if (lpCmdLine[0])
{
   strcpy( FileName, lpCmdLine );
   /* determine the number of pages */
  IG_fltr_pagecount_file_format( IG_FORMAT_TXT, FileName,
&g_nPageCount );
   /* load the selected image */
  IG_fltr_load_file_format( IG_FORMAT_TXT, FileName,
g_nCurrentPage, &hIGear);
    }
...

Sample: ASCII

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_metad_callback_get

Group: Format filters

Declaration:

AT_ERRCODE  ACCUAPI  IG_fltr_metad_callback_get(
    LPVOID *lpPrivate,
    LPAFT_IG_METAD_ITEM_SET_CB *lplpfnSetCB,
    LPAFT_IG_METAD_ITEM_ADD_CB *lplpfnAddCB,
    LPAFT_IG_METAD_ITEM_GET_CB *lplpfnGetCB
);

Arguments:

Private
Returns private data associated with metadata callback functions.
SetCB
Returns pointer to callback function of type LPAFT_IG_METAD_ITEM_SET_CB that is used for Set metadata operation.
AddCB
Returns pointer to callback function of type LPAFT_IG_METAD_ITEM_ADD_CB that is used for Add metadata operation.
GetCB
Returns pointer to callback function of type LPAFT_IG_METAD_ITEM_GET_CB that is used for Get metadata operation.

Description:

This function returns current value of callback information that ImageGear uses to pass/receive application data during save/load filter's operations. NULL value is possible for any parameter - means that some information is not necessary.

See also IG_fltr_metad_callback_set (), LPAFT_IG_METAD_ITEM_ADD_CB, LPAFT_IG_METAD_ITEM_GET_CB, LPAFT_IG_METAD_ITEM_SET_CB functions and the section Processing of non-image data through filter callback functions.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_metad_callback_set

Group: Format filters

Declaration:

AT_ERRCODE  ACCUAPI  IG_fltr_metad_callback_set(
    LPVOID *lpPrivate,
    LPAFT_IG_METAD_ITEM_SET_CB *lplpfnSetCB,
    LPAFT_IG_METAD_ITEM_ADD_CB *lplpfnAddCB,
    LPAFT_IG_METAD_ITEM_GET_CB *lplpfnGetCB
);

Arguments:

Private
New value for private data to be associated with callback functions.
SetCB
New value of callback function of type LPAFT_IG_METAD_ITEM_SET_CB that is to be used for Set metadata operation.
AddCB
New value of callback function of type LPAFT_IG_METAD_ITEM_ADD_CB that is to be used for Add metadata operation.
GetCB
New value of callback function of type LPAFT_IG_METAD_ITEM_GET_CB that is to be used for Get metadata operation.

Description:

This function set new value of callback information that ImageGear uses to pass/receive application data during save/load filter's operations. NULL value is possible for any parameter - means that some information is not necessary.

See also IG_fltr_metad_callback_get (), LPAFT_IG_METAD_ITEM_ADD_CB, LPAFT_IG_METAD_ITEM_GET_CB, LPAFT_IG_METAD_ITEM_SET_CB functions and the section Processing of non-image data through filter callback functions.

NOTE: To avoid an application lock up lpfnAddCB metadata callback should always return FALSE if there are no data to send.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

VOID ACCUAPI MetaDataGet(
    LPVOID	 lpPrivate,     /* Private callback data. */
    LPCHAR	 ItemName,      /* Name of data item  */
    DWORD	 ItemID,        /* ID of data item   */
    AT_MODE	 ItemType,      /* Type of item */
    LPVOID	 ItemValue,       /* value of item */
    AT_MODE	 ValueType,       /* type of value */
    DWORD	 ValueLength,       /* length of value */
    AT_BOOL	 ReadOnlyValue  /* inform about is value is
changeable or not */
)
{
}
BOOL ACCUAPI MetaDataSet(
    LPVOID         lpPrivate,     /* Private callback data. */
   LPCHAR         ItemName,       /* Name of data item */
   DWORD          ItemID,         /* ID of data item    */
   AT_MODE        ItemType,       /* Type of item */
   LPVOID         ItemValue,      /* value of item */
   AT_MODE        ValueType,      /* type of value */
   DWORD          ValueLength,    /* length of value */
   AT_BOOL        ReadOnlyValue, /* inform about is value is
changeable or not	*/
   LPVOID         *NewItemValue,
   LPAT_MODE      NewValueType,
   LPDWORD        NewValueLength
)
...
BOOL ACCUAPI MetaDataAdd(
    LPVOID	lpPrivate,        /* Private callback data. */
    LPCHAR	*ItemName,         /* Name of data item */
    DWORD	*ItemID,          /* ID of data item     */
    AT_MODE	*ItemType,         /* Type of item */
    LPVOID	*ItemValue,        /* value of item */
    AT_MODE	*ValueType,        /* type of value */
    DWORD	*ValueLength,      /* length of value */
    AT_BOOL	*ReadOnlyValue  /* inform about is value is
changeable or not */
)
...
FillAddMetaDList();
    IG_fltr_metad_callback_set( &PrivMetaD, MetaDataSet,
MetaDataAdd, MetaDataGet );
...

Sample: JPEG, GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_metad_update_file

Group: Format filters

Declaration:

AT_ERRCOUNT ACCUAPI IG_fltr_metad_update_file(
    const LPSTR lpszFileNameSrc,
    const LPSTR lpszFileNameDest,
    AT_LMODE lFormatType,
    UINT nPageNumber
);

Arguments:

lpszFileNameSrc
Source file name.
lpszFileNameDest
Destination file name.
lFormatType
Source file format.
nPageNumber
Page number for metadata updating.

Description:

This metadata updating function creates a new file with exact copy of source file's pixel data and with new metadata. Pixel data is not decoded but copied directly from source to destination file. At the moment, the following file formats supports this feature:

  • IG_FORMAT_TIF
NOTE: TIFF-JPEG format is not supported by this function.

The function creates a new file that contains copy of source file data with the new metadata for required page. lFormatType parameter value should be the same as the source file format type. In a multipage file, the rest of pages are copied verbatim from source to destination file.

The function obtains new metadata from metadata callback functions (LPAFT_IG_METAD_ITEM_SET_CB, LPAFT_IG_METAD_ITEM_ADD_CB).

IG_fltr_metad_update_file() function can be used as follows:

  1. Load necessary page to get metadata;
  2. Change metadata (add / delete / change metadata tags or metadata values);
  3. Call IG_fltr_metad_update_file() function. nPageNumber and lFormatType parameter values should correspond to the loaded page and source file format.

Destination file will have source file copy with new metadata for required page.

Bits Per Pixel: ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

Example of metadata update function usage is in the Filter sample. Use the following steps to test this feature:

  1. Open TIF image using File/Open menu item;
  2. Add or modify tag(s) using Image/Metadata/Data Structure dialog
  3. Create a file with updated metadata using File/Update metadata menu item. Source file name and page number correspond to the last loaded page in the filter sample.
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
nErrcount = IG_fltr_metad_callback_set(
    dwPrivate, lpfnSetCB, lpfnAddCB, NULL);
nErrcount = IG_fltr_metad_update_file(
    "test.jpg", "updated.jpg", IG_FORMAT_JPG, 1);
NOTE: All changes made in the Metadata dialog will be lost, if any function that returns metadata is called before calling IG_fltr_metad_update_file() (loading a new file, getting file info or preview).

Sample: Filter

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_pagecount_FD_format

Group: Format Filters

Declaration:

AT_ERRCOUNT ACCUAPI  IG_fltr_pagecount_FD_format(
    AT_MODE nFormat,
    AT_INT fd,
    LONG lOffset,
    LPUINT lpPageCount
);

Arguments:

nFormat
File format id to load. If IG_FORMAT_UNKNOWN then usual detect works
fd
File descriptor
lOffset
Offset to image
lpPageCount
return: Number of pages in an image

Description:

This function is similar to the IG_page_count_get_FD() function, but has an additional parameter, nFormat, which specifies the file format of the input file. If nFormat = IG_FORMAT_UNKNOWN, then the usual autodetection procedure is performed before retrieving the page count. Otherwise, this procedure is not performed, and ImageGear retrieves page count using the specified format filter.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_fltr_pagecount_file_format

Group: Format filters

Declaration:

AT_ERRCOUNT ACCUAPI  IG_fltr_pagecount_file_format(
    AT_MODE nFormat,
    const LPSTR lpszFileName,
    LPUINT lpPageCount
);

Arguments:

nFormat
The File format ID to load the file. It is specified using constants such as IG_FORMAT_. For a complete list of these constants, see the accucnst.h file.
szFileName
The File Name of image file from which pages should be counted.
PageCount
The number of pages returned by this function.

Description:

This function is similar to the IG_page_count_get () function, but has an additional parameter, nFormat, which specifies the file format of the input file. If nFormat = IG_FORMAT_UNKNOWN, then the usual autodetection procedure is performed before retrieving the page count. Otherwise, this procedure is not performed, and ImageGear retrieves page count using the specified format filter.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See example for IG_fltr_load_file_format ().

Sample: ASCII

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_pagedelete_file

Group: Format filters

Declaration:

AT_ERRCOUNT ACCUAPI IG_fltr_pagedelete_file(
    const LPSTR lpszFileName,
    AT_MODE nFormatType,
    UINT nStartPage,
    UINT nRange
);

Arguments:

szFileName
Far pointer to FileName (you may include path with filename) of the multipage file from which (nRange) pages should be deleted.
nFormatType
Specifies the filter ID of the szFileName file format. If IG_FORMAT_UNKNOWN is passed then the normal detection procedure is performed.
nStartPage
Determines the first page to delete from the szFileName file.
nRange
Determines the number of pages to delete, starting from nStartPage.

Description:

This function deletes nRange pages from the multipage file format, starting with the nStartPage page. Not all filters support this procedure. To determine whether the format filter is supported, use the IG_fltr_info_get () function. If the IG_fltr_info_get() function returns the flags ((*lpdwInfoFlags)&IG_FLTR_PAGEDELETESUPPORT)!=, then the format filter supports the deleting procedure.

See also the section Getting Information and Sorting Images.

NOTE: Currently only TIFF filter supports this procedure.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_pageinfo_get

Group: Format filters

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_fltr_pageinfo_get(
    const LPSTR lpszFileName,
    UINT nPageNumber,
    LPAT_MODE lpFileType,
    LPAT_MODE lpCompression,
    LPAT_DIB lpDIB
);

Arguments:

lpszFileName
Name of the file for which to get information.
nPageNumber
Page Number of the page in a multi-page file for which to get information.
lpFileType
Far pointer to an AT_MODE variable for which the file type, such as IG_FORMAT_BMP, will be returned.
lpCompression
Far pointer to an AT_MODE variable for which a compression type, such as IG_COMPRESSION_RLE, will be returned
lpDIB
Far pointer to an AT_DIB structure to which other file information, such as width, height, and Bits Per Pixel will be returned.

Description:

This function obtains information about the page specified by the nPageNumber parameter from a named multipage file without actually loading it. The file is opened and the header is inspected. The file must exist.

See also the section Getting Information and Sorting Images.

NOTE: This function is almost the same as the IG_info_get_ex() function, but returns information about any multipage file page specified by nPageNumber, not just the first page.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_pageswap_file

Group: Format filters

Declaration:

AT_ERRCOUNT   ACCUAPI  IG_fltr_pageswap_file(
    const LPSTR lpszFileName,
    AT_MODE nFormatType,
    UINT nPage1,
    UINT nPage2
);

Arguments:

szFileName
Far pointer to filename (you may include path with filename) of the multipage file in which two pages should be swapped.
nFormatType
Specifies the filter ID of the szFileName file format. If IG_FORMAT_UNKNOWN is passed, then the normall detection procedure is performed.
nPage1
Number of page 1 to swap with page 2.
nPage2
Number of page 2 to swap with page 1.

Description:

This function swaps two pages (specified by nPage1 and nPage2 accordingly) in the szFileName multipage file. This operation is supported by the filters for which the IG_fltr_info_get () function returns the ((*lpdwInfoFlags)&IG_FLTR_PAGESWAPSUPPORT)!=0 flags.

NOTE: Currently only TIFF filter supports this procedure.

See also the section Getting Information and Sorting Images.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_raster_plane_callback_get

Group: Format Filters

Declaration:

AT_ERRCOUNT LACCUAPI IG_fltr_raster_plane_callback_get(
    LPFNIG_RASTER_PLANE_SET *lplpfnRasterPlaneSetCB,
    AT_VOID **lpReserved
);

Arguments:

lplpfnRasterPlaneSetCB
SET callback function
lpReserved
reserved for Get function

Description:

This function allows you to retrieve the settings of raster plane callback LPFNIG_RASTER_PLANE_SET function.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
nErrcount = IG_fltr_raster_plane_callback_get(
    &lpfnRasterPlaneSetCB, NULL);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_raster_plane_callback_set

Group: Format Filters

Declaration:

AT_ERRCOUNT LACCUAPI IG_fltr_raster_plane_callback_set(
    LPFNIG_RASTER_PLANE_SET lpfnRasterPlaneSetCB,
    AT_VOID *Reserved
);

Arguments:

lpfnRasterPlaneSetCB
SET callback function
Reserved
reserved for Get function

Description:

This function allows you to register your raster plane callback LPFNIG_RASTER_PLANE_SET function.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
nErrcount = IG_fltr_raster_plane_callback_set(
    lpfnRasterPlaneSetCB, NULL);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_save_FD_size_calc

Group: Format filters

Declaration:

AT_ERRCOUNT ACCUAPI  IG_fltr_save_file_size_calc(
    HIGEAR hIGear,
    AT_INT fd,
    AT_LMODE lFormatType,
    AT_UINT nPageNumber,
    AT_BOOL bOverwrite,
    LPAT_UINT lpFileSize
);

Arguments:

hIGear
HIGEAR handle of the image on which to calculate the size.
fd
If you are going to add a page to an existing image file, this parameter specifies the file descriptor handle of this (already opened) file.
lFormatType
A constant such as IG_SAVE_TIF_UNCOMP or IG_SAVE_BMP_RLE, indicating the format in which to save the image. It also specifies the compression scheme if applicable. See the accucnst.h file for a list of all IG_SAVE_... constants.
nPageNumber
Specifies the page number of the page inserted into a multi-page file.
bOverwrite
If TRUE - the file is overwritten during the save procedure, if FALSE - the file isn't overwritten during inserting page procedure.
lpFileSize
Returns the maximum possible size of the file.

Description:

This function is used to determine the maximum size of the file that would result if the call IG_save_FD were executed on this HIGEAR image and the same parameters. This call may be used prior to calling IG_save_FD() to determine the size of result file.

This function can be used to calculate the size of a multipage image file after addition of a page.

See also the section Using Format Filters API for Image Saving.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_fltr_save_file

Group: Format filters

Declaration:

AT_ERRCOUNT ACCUAPI  IG_fltr_save_file(
    HIGEAR hIGear,
    const LPSTR lpszFileName,
    AT_LMODE lFormatType,
    UINT nPageNumber,
    AT_BOOL bOverwrite
);

Arguments:

hIGear
HIGEAR handle of the image to save
lpszFilename
Far pointer to the filename (you may include path with filename) to save.
lFormatType
A constant such as IG_SAVE_TIF_UNCOMP or IG_SAVE_BMP_RLE, indicating the format in which to save the image. It also specifies the compression scheme if applicable. See the accucnst.h file for a list of all IG_SAVE_... constants.
nPageNumber
Specifies the page number of the page inserted into a multi-page file.
bOverwrite
AT_BOOL parameter. If TRUE - the file is overwritten during the save procedure, if FALSE - the file isn't overwritten during inserting page procedure.

Description:

This function stores the image rectangle of the image referenced by hIGear to disk using the name lpszFilename. lFormatType is used to set the format and compression (if applicable) of the output file. If you want to have ImageGear use the file extension provided in your filename string (lpszFilename) to determine the file format in which to save the file, set lFormatType = IG_SAVE_UNKNOWN.

NOTE: This function is similar to the IG_save_file() function, but it allows you to insert a new page in multi-page file as either the end page or the page with a given nPageNumber number. The second bOverwrite parameter determines whether or not the lpszFilename file should be overwritten during the save procedure. (yes=TRUE) (no=FALSE).

See also the section Using Format Filters API for Image Saving.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* The code example for using "File|Save As" menu option:  */
case ID_FILE_SAVEAS:
    memset( &SFInfo, 0, sizeof(SFInfo) );
    IG_image_DIB_pntr_get( hIGear, &lpDIB );
/* get a file name from the save common dialog box */
    if( IG_gui_save_page_dlg( hWnd, NULL, lpDIB, NULL, 0,
&SFInfo ) )
    {
        SetCursor(LoadCursor(NULL, IDC_WAIT));
/* save the image in the selected image file format    */
/* of.nFilterIndex - 1 is a zero based offset into the */
/* save filter list, defined in common.c 	 */
err_count = IG_fltr_save_file(hIGear, SFInfo.FileName,
SFInfo.nFormat|(SFInfo.PageInfo.nCompression<<16),
SFInfo.PageInfo.nPage, SFInfo.bOverwrite );
    repaint_image_and_error_check(hWnd);
    SetCursor(LoadCursor(NULL, IDC_ARROW));
        }
break;

Sample: ART, COLOR, DISPLAY, IC, IMG_PROC, JPEG,

Medical, PALEDT, PIX_ACC, PJPEG, PRINT, Scan, TEMPLATE,

TWAIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_save_file_size_calc

Group: Format filters

Declaration:

AT_ERRCOUNT ACCUAPI  IG_fltr_save_file_size_calc(
    HIGEAR hIGear,
    const LPSTR lpszFileName,
    AT_LMODE lFormatType,
    AT_UINT nPageNumber,
    AT_BOOL bOverwrite,
    LPAT_UINT lpFileSize
);

Arguments:

hIGear
HIGEAR handle of the image on which to calculate the size.
lpszFilename
If you are going to add a page to an existing image file, this parameter specifies its name.
lFormatType
A constant such as IG_SAVE_TIF_UNCOMP or IG_SAVE_BMP_RLE, indicating the format in which to save the image. It also specifies the compression scheme if applicable. See the accucnst.h file for a list of all IG_SAVE_... constants.
nPageNumber
Specifies the page number of the page inserted into a multi-page file.
bOverwrite
If TRUE - the file is overwritten during the save procedure, if FALSE - the file isn't overwritten during inserting page procedure.
lpFileSize
Returns the maximum possible size of the file.

Description:

This function is used to determine the maximum size of the file that would result if the call IG_fltr_save_file were executed on this HIGEAR image and the same parameters. This call may be used prior to calling IG_fltr_save_file() to determine the size of result file.

This function can be used to calculate the size of a multipage image file after addition of a page.

See also the section Using Format Filters API for Image Saving.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_fltr_save_mem

Group: Format filters

Declaration:

AT_ERRCOUNT ACCUAPI  IG_fltr_save_mem(
    HIGEAR hIGear,
    LPVOID lpImage,
    AT_UINT   nImageSize,
    AT_UINT   nBufferSize,
    AT_LMODE lFormatType,
    AT_UINT nPageNumber,
    AT_BOOL bOverwrite,
    LPAT_UINT lpActualSize
);

Arguments:

hIGear
HIGEAR handle of the image to save
lpImage
Far pointer to first byte of memory area in which to save
nImageSize
Size of image (if exists).
nBufferSize
Size of memory block.
lFormatType
A constant such as IG_SAVE_TIF_UNCOMP or IG_SAVE_BMP_RLE, indicating the format in which to save the image. It also specifies the compression scheme if applicable. See the accucnst.h file for a list of all IG_SAVE_... constants.
nPageNumber
Specifies the page number of the page inserted into a multi-page file.
bOverwrite
If TRUE - the file is overwritten during the save procedure, if FALSE - the file isn't overwritten during inserting page procedure.
lpActualSize
Size of new or updated file in memory

Description:

This function stores the image referenced by hIGear to the specified memory buffer. lFormatType is used to set the format and compression (if applicable) of the output file. If you want to have ImageGear use the file extension provided in your filename string (lpszFilename) to determine the file format in which to save the file, set lFormatType = IG_SAVE_UNKNOWN.

Before using this function, the application must allocate a memory buffer, sufficient for storing the saved image. Use IG_fltr_save_mem_size_calc() to determine the necessary buffer size.

NOTE: This function is similar to the IG_save_mem() function, but it allows you to insert a new page in multi-page file as either the end page or the page with a given nPageNumber number.

See also the section Using Format Filters API for Image Saving.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: MEMIO

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_save_mem_size_calc

Group: Format filters

Declaration:

AT_ERRCOUNT ACCUAPI  IG_fltr_save_mem_size_calc(
    HIGEAR hIGear,
    LPVOID lpImage,
    AT_UINT   nImageSize,
    AT_LMODE lFormatType,
    AT_UINT nPageNumber,
    AT_BOOL bOverwrite,
    LPAT_UINT lpFileSize
);

Arguments:

hIGear
HIGEAR handle of the image on which to calculate the size.
lpImage
If the buffer exists and already contains an image file to which a page will be appended, this parameter specifies a pointer to first byte of the existing file in the memory buffer.
nImageSize
If the buffer exists and already contains an image file to which a page will be appended, this parameter specifies the size of existing image.
lFormatType
A constant such as IG_SAVE_TIF_UNCOMP or IG_SAVE_BMP_RLE, indicating the format in which to save the image. It also specifies the compression scheme if applicable. See the accucnst.h file for a list of all IG_SAVE_... constants.
nPageNumber
Specifies the page number of the page inserted into a multi-page file.
bOverwrite
If TRUE - the file is overwritten during the save procedure, if FALSE - the file isn't overwritten during inserting page procedure.
lpFileSize
Returns the maximum possible size of the file.

Description:

This function is used to determine the maximum size of the file that would result if the call IG_fltr_save_mem were executed on this HIGEAR image and the same parameters. This call may be used prior to calling IG_fltr_save_mem() to determine the amount of memory that needs to be allocated.

This function can be used to calculate the size of a multipage image file after addition of a page.

See also the section Using Format Filters API for Image Saving.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: MEMIO

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_savelist_get

Group: Format filters

Declaration:

AT_ERRCOUNT ACCUAPI IG_fltr_savelist_get (
    [IN] LPAT_DIB lpDIB,
    [IN] LPAT_MODE lpnFilterList,
    [IN] UINT nFListSize,
    [OUT] LPAT_LMODE lpSaveList,
    [IN] UINT nSListSize,
    [OUT] LPUINT lpnSListCount
);

Arguments:

lpDIB
A pointer to the AT_DIB structure that contains the image parameters. If the value is not NULL, this function contains a list of the IG_FORMAT_... constants that defines the formats you can use. If the value is NULL, then all currently supported file formats can be used.
lpnFilterList
This parameter is a pointer to the list of format identifiers (like IG_FORMAT_JPG), which will be used in the save list. If this parameter is NULL, then all currenhtly existing formats will be used.
nFListSize
An array containing the number of elements if lpnFilterList is not NULL.
lpSaveList
An array containing the returned save constants created by combining the format identifier from the lpnFilterList list and the compression format that applies to the image with the parameters stored in lpDIB. If this value is NULL, the total number of records is returned through the lpnSListCount parameter.
nSListSize
The size of the lpSaveList array.
lpnSListCount
If the lpSaveList array is not NULL, this parameter returns the number of copied values. If lpSaveList is NULL, this parameter returns the total number of records.

Description:

This function prepares a list of values (nFormat|(nCompression<<16)), where nFormat is the format identifier IG_FORMAT_... and nCompression is the compression constant IG_COMPRESSION_... defined in the accucnst.h header file.

If the value is not NULL, nFormat values are taken from either lpnFilterList or from the list of all available format filters. In any case, all records are sorted alphabetically by short name, returned from the IG_fltr_info_get ()function, through the third parameter.

Compression constants are obtained using function IG_fltr_compressionlist_get () and its corresponding combination is put into lpSaveList for each format identifier in this list. Each value from this list can be passed directly to the function IG_save_file () as the third parameter.

If lpSaveList is NULL, this function counts the size of the required lpSaveList array and returns that count in through the last lpnSListCount parameter.

See also the section Using Format Filters API for Image Saving.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;
AT_ERRCOUNT nErrCount;
UINT nCount;
LPAT_DIB lpDIB;
LPAT_LMODE lpSaveList;
LPCHAR lpFileName;	/* file name where to save image */
/* Prepare the list of save constants that can be used to save
given image */
nErrCount = IG_image_DIB_pntr_get( hIGear, &lpDIB );
if( nErrCount==0 )
{
    /* get number of compressions */
    IG_fltr_savelist_get( lpDIB, NULL, 0, NULL, 0, &nCount );
    lpSaveList = (LPAT_LMODE)malloc( nCount*sizeof(AT_LMODE) );
    if( lpSaveList!=NULL )
    {
    IG_fltr_savelist_get( lpDIB, NULL, 0, lpSaveList, nCount,
NULL );
    // some gui that allows to select one save index
     ...
    IG_save_file( hIGear, lpFileName, lpSaveList[
nSelectedFormat ] );
        free( lpSaveListList );
    }
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_fltr_savelist_get_ex

Group: Format Filters

Declaration:

AT_ERRCOUNT ACCUAPI IG_fltr_savelist_get_ex(
    const HIGDIBINFO hDIB,
    LPAT_MODE lpnFilterList,
    UINT nFListSize,
    LPAT_LMODE lpSaveList,
    UINT nSListSize,
    LPUINT lpnSListCount
);

Arguments:

hDIB
Handle of DIB info object that contains image parameters. If NULL, then this function returns all possible file formats.
lpnFilterList
This parameter is a pointer to the list of format identifiers (like IG_FORMAT_JPG), which will be used in the save list. If this parameter is NULL, then all currently existing formats will be used.
nFListSize
An array containing the number of elements if lpnFilterList is not NULL.
lpSaveList
An array containing the returned save constants created by combining the format identifier from the lpnFilterList list and the compression format that applies to the image with the parameters stored in hDIB. If this value is NULL, the total number of records is returned through the lpnSListCount parameter.
nSListSize
The size of the lpSaveList array.
lpnSListCount
If the lpSaveList array is not NULL, this parameter returns the number of copied values. If lpSaveList is NULL, this parameter returns the total number of records.

Description:

This function prepares a list of values (nFormat|(nCompression<<16)), where nFormat is the format identifier IG_FORMAT_... and nCompression is the compression constant IG_COMPRESSION_... defined in the accucnst.h header file.

If the value is not NULL, nFormat values are taken from either lpnFilterList or from the list of all available format filters. In any case, all records are sorted alphabetically by short name, returned from the IG_fltr_info_get () function, through the third parameter.

Compression constants are obtained using function IG_fltr_compressionlist_get () and its corresponding combination is put into lpSaveList for each format identifier in this list. Each value from this list can be passed directly to the function IG_save_file () as the third parameter.

If lpSaveList is NULL, this function counts the size of the required lpSaveList array and returns that count in through the last lpnSListCount parameter.

See also the section Using Format Filters API for Image Saving.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Get list of formats that can be used when
   saving the given image */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGDIBINFO hDIB;        /* DIB info handle of image */
UINT nCount, nActual;   /* Number of formats */
LPAT_LMODE lpSaveList;  /* List of formats */
nErrcount = IG_image_DIB_info_get(hImage, &hDIB);
nErrcount = IG_fltr_savelist_get_ex(hDIB, NULL, 0,
    NULL, 0, &nCount);
lpSaveList = (LPAT_MODE) malloc(nCount * sizeof(AT_MODE));
nErrcount = IG_fltr_savelist_get_ex(hDIB, NULL, 0,
    lpSaveList, nCount, &nActual);
/* [some GUI to allow selecting a format] */
nErrcount = IG_save_file(hImage, lpFileName,
    lpSaveList[nSelectedFormat]);
IG_DIB_info_delete(hDIB);
free(lpSaveList);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_FX_aging

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_aging(
    HIGEAR hIGear,
    AT_FLOAT saturation,
    AT_FLOAT deviation,
    AT_FLOAT imageContrast,
    AT_FLOAT lineContrast,
    AT_INT lineDensity,
    AT_FLOAT agingColor[],
    AT_INT agingColorCount
);

Arguments:

hIGear
Image to apply aging effect to
saturation
Adjusts color saturation of the original image. The value should range from 0 to 1, where 0 removes all color from the image and 1 does not adjust color saturation.
deviation
Amount of noise to add to the image. The value should range from 0 to 50.
imageContrast
Adjusts image contrast. The value should range from 0 to 1, where 0 is minimum contrast and 1 does not adjust contrast. Values less than 0 produce inverted contrast.
lineContrast
Adjusts contrast of random vertical lines added to the image. The value should range from -1 to 1, where -1 is completely black lines, 0 is invisible lines, and 1 is completely white lines. Values between 0 and 1, for example, blend line color between original image pixel colors and white.
lineDensity
Adjusts density (quantity) of random vertical lines added to the image. The value should range from 0 to the width of the image in pixels, where 0 would add no lines, and the width of the image in pixels would fill the image with lines.
agingColor [ ]
Adjusts color tint of the image. The color of the image will be tinted according to the values of the array. The array consists of three elements which represent color adjustment factors, corresponding to image colorspace. Each element ranges from -1 to 1, where a value of 0 represents no change to the image's color component, -1 represents completely change to the color component's minimum value, and 1 represents complete change to the color component's maximum value.
agingColorCount
Number of entries in the agingColor array. Must be equal to number of channels in the image.

Description:

This method applies an aging effect to make an image look older. The effect can adjust image saturation and contrast, and add noise and random vertical lines to the image.

Applicability:

RGB, non bitonal Gray and indexed with grayscale palette. Does not support Grayscale with LUT.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_blur

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_blur (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const AT_MODE nBlurMode
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to be processed. Set = NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nBlurMode
A constant such as IG_BLUR_3 specifying the kernel size to use to perform the blurring. See file accucnst.h for the IG_BLUR_ constants available.

Description:

This function blurs an image. nBlurMode controls the degree of blurring.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear;        /* HIGEAR handle of image    */
AT_RECT	 rcImageRect;    /* Image's current image rectangle */
/* Blur only the image rect portion, using a 5 x 5 kernel:     */
IG_FX_blur ( hIGear, &rcImageRect, IG_BLUR_5 );

Sample:

None


IG_FX_chroma_key

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_chroma_key (
    HIGEAR hIGearFrGrnd,
    LPAT_RECT lpRect,
    HIGEAR hIGearBkGrnd,
    const DOUBLE dblHueCenter,
    const DOUBLE dblHueRange,
    const UINT nSmooth,
    const UINT nThreshold
);

Arguments:

hIGearFrGrnd
HIGEAR handle of image to modify where the specified hue is found
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image to be processed. Use NULL for the whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
hIGearBkGrnd
HIGEAR handle of an image to insert from on hue match.
dblHueCenter
The angle in degrees (in the standard Color Wheel) of the hue to match. 0.0 - 360.0 (360 == 0).
dblHueRange
The range on which to allow (in degrees) either side. 0.0 - 360.0
nSmooth
An integer from 0 to 25 specifying how much to smooth the transition. 0 gives the sharpest edge.
nThreshold
Intensity below which to ignore the hue, and fail the match (0 - 255)

Description:

This function blends two images, inserting the pixel values from hIGearBkGrnd wherever the pixel in hIGearFrGrnd is in the specified hue range. You can control the smoothness of the transitions using argument nSmooth, and you can prevent the hue of dark pixels from being considered, using nThreshold. To determine the proper hue center and hue range, you may want to use the IG_DIB_pixel_get () and IG_IP_RGB_to_hue () functions.

NOTE: See also IG_IP_blend_with_LUT(), IG_DIB_pixel_get() and IG_IP_RGB_to_hue()functions.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: See the descriptions of "IG_IP_NR_ROI_mask_associate" described on page -2032 and "IG_IP_NR_ROI_to_HIGEAR_mask" described on page -2037 for more details.
TIP: The "background image" must have the same height, width, and bit depth as the "foreground image."

The hue is not an 8-bit HSI. HSI is the name of the color space.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hiGear, /* HIGEAR handle of image to blend into  */
hIGear Bkgrnd; /* HIGEAR handle of image to blend in  */
AT_PIXEL pixelvalue[3];	/* 3 bytes for return of an RGB pixel
value */
DOUBLE Hue;	/* Hue angle that will be returned */
/* Retrieve the RGB value of the pixel at (10,20) in the HIGEAR
image */
nErrcount = IG_DIB_pixel_get (hIGear, 10, 20, &pixelvalue[0]);
/* Pass the RGB pixel value to IG_IP_RGB_to_hue to convert to
hue angle  */
nErrcount = IG_IP_RGB_to_hue (&pixelvalue[0], &Hue);
/* Pass newly calculated hue angle to chroma_key to combine
images   */
IG_FX_chroma_key ( hIGear, NULL, hIGearBkgrnd, Hue, 10.0, 0, 20
);

Sample:

FlashPix


IG_FX_cylinder

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_cylinder(
    HIGEAR hIGear,
    AT_INT nDistance,
    AT_INT nRadius,
    AT_INT nHeight,
    AT_BOOL bHorizontal,
    AT_BOOL bInterpolate,
    HIGPIXEL hbkColor,
    LPAT_RECT lpRect
);

Arguments:

hIGear
Image to apply the effect to.
nDistance
Distance to the cylinder axes, in pixels.
nRadius
Cylinder radius, in pixels.
nHeight
Height of the cylinder segment, in pixels. Height can be changed from
(-radius) to (radius).
bHorizontal
If TRUE, cylinder is horizontal.
bInterpolate
If TRUE, interpolation is used during processing.
hbkColor
Background color. It should have the same colorspace and channel depths as the image to which the effect is applied.
lpRect
Rectangle area to apply the effect to, or NULL for whole image.

Description:

Provides the effect of warping around a cylinder on the hIGear image.

Applicability:

All except bitonal if interpolation is off; All except bitonal, non-gray Indexed and Grayscale with LUT if interpolation is on.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FX_diffuse

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_diffuse (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const UINT nStrength
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to be processed. Set = NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nStrength
An integer from 1 to 16 specifying the amount of diffusion.

Description:

This function diffuses an image by shuffling the positions of pixels. The greater the value of nStrength, the greater the diffusion.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear;   	/* HIGEAR handle of image */
/* Diffuse the image slightly: */
IG_FX_diffuse ( hIGear, NULL, 3 );

Sample:

FlashPix


IG_FX_directional_light

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_directional_light(
    HIGEAR hIGear,
    AT_FLOAT angle,
    AT_INT channelCount,
    AT_FLOAT amplitude[],
    AT_FLOAT frequency,
    AT_FLOAT phase,
    AT_FLOAT attenuation
);

Arguments:

hIGear
Image to apply direct light effect to.
angle
Direction to apply the effect across the image. The value is specified as an angle in degrees and ranges from 0 to 360.
channelCount
Specifies the number of channels that should be affected by the transform.
amplitude [ ]
Controls the magnitude of color adjustment for each channel of the image. The number of elements of the array is typically set to the number of channels in the image. Each value should range from 0 to 2, although higher values are possible. 0 represents no change in the image color. Higher values represent more intense change. Color changes are clipped, so higher values result in a harder edge to the waveform. Array length must be equal to channelCount.
frequency
Frequency of sine wave. The value should be from 0 to 0.5. The higher the frequency, the more bars will be visible.
phase
Phase of sine wave. The value should be from 0 to 2*PI (approximately 6.28). As the phase is changed, the alignment of the bars is changed. This can be used to line up the bars with image content or boundaries.
attenuation
Attenuation of sine wave. The value should be from -0.01 to 0.01. Attenuation adjusts how much the amplitude of the sine wave is decreased or increased as the sine wave proceeds. It can be used to cause the lighting to fade or intensify.

Description:

This method changes the colors of an image according to the pattern of a sine wave. The image will appear to have regularly spaced bars of light and shadow overlaid on top of it.

Applicability:

All except bitonal, non-gray Indexed and Grayscale with LUT.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_directional_wave

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_directional_wave(
    HIGEAR hIGear,
    AT_FLOAT fAngle,
    AT_FLOAT fAmplitude,
    AT_FLOAT fFrequency,
    AT_FLOAT fPhase,
    AT_FLOAT fAttenuation,
    AT_BOOL bInterpolate,
    HIGPIXEL hbkColor,
    LPAT_RECT lpRect
);

Arguments:

hIGear
Image to apply the effect to.
fAngle
Wave direction, in radians.
fAmplitude
Wave amplitude. Measurement units - pixel / 100.
fFrequency
Wave frequency. The frequency is defined as 1 / T, where T is a wave period, in pixels.
fPhase
Wave phase, in radians.
fAttenuation
Wave attenuation. The attenuation factor of the wave is calculated as exp(-attenuation * r), where r is a distance from the wave center to the current wave point.
bInterpolate
If TRUE, interpolation is used during processing.
hbkColor
Background color. It should have the same colorspace and channel depths as the image to which the effect is applied.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.

Description:

Applies a directional wave effect on the current hIGear image.

Applicability:

All except bitonal if interpolation is off; All except bitonal, non-gray Indexed and Grayscale with LUT if interpolation is on.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FX_emboss

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_emboss (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const DOUBLE dblStrength,
    const AT_MODE nCompassDir
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to be processed. Set = NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
dblStrength
the embossing strength. The valid range is from 1.0 to 5.0
ncompassDir
An AT_MODE Compass derection constants (see accucnst.h file):
IG_COMPASS_N - North direction
IG_COMPASS_NE - North-East direction
IG_COMPASS_E - East direction
IG_COMPASS_SE - South-East direction
IG_COMPASS_S - South direction
IG_COMPASS_SW - South-West direction
IG_COMPASS_W - West direction direction
IG_COMPASS_NW - North-West direction

Description:

This function produces an embossed or 3-D like chiseled-in-stone look to the image. The result looks similar to the engraved face of a coin. The greater the value of dblStrength, the greater the effect will be (higher ridges and lower depressions). The direction in which the image will appear elevated is selected by nCompassDir.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    	/* HIGEAR handle of image  */
AT_RECT rcImageRect;	/* Image's current image rectangle  */
/* Emboss only the image rect portion: */
IG_FX_emboss ( hIGear, &rcImageRect, 3.0, IG_COMPASS_NE );

Sample:

FlashPix


IG_FX_fragment

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_fragment(
    HIGEAR  hIGear,
    AT_INT  displacement
);

Arguments:

hIGear
Image to apply fragment effect to.
displacement
Distance in pixels to move each blended image away from the original image.

Description:

This method fragments an image into four blended images which move diagonally outward from the original image.

Applicability:

All except bitonal, non-gray Indexed and Grayscale with LUT.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_free_directional_light

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_free_directional_light(
    HIGEAR  hIGear,
    AT_FLOAT angle,
    AT_INT  pointCount,
    AT_FLOAT points[],
    AT_INT channelCount,
    AT_FLOAT amplitude[],
    AT_FLOAT frequency,
    AT_FLOAT phase,
    AT_FLOAT attenuation
);

Arguments:

hIGear
Image to apply free directional light effect to.
angle
Direction to apply the effect across the image. The value is specified as an angle in degrees and ranges from 0 to 360.
pointCount
Length of the points array
points[ ]
Array of points containing relative light deviations along the period of the sine wave. Each value typically ranges from -1 to 1. The number of points is flexible and should be chosen based on the period length relative to the image size and desired resolution of the effect.
channelCount
Number of image channels to apply the effect to.
amplitude[ ]
Controls the magnitude of color adjustment for each channel of the image. The number of elements of the array is typically set to the number of channels in the image. Each value should range from 0 to 2, although higher values are possible. 0 represents no change in the image color. Higher values represent more intense change. Color changes are clipped, so higher values result in a harder edge to the waveform. Array length must be equal to channelCount.
frequency
Frequency of sine wave. The value should be from 0 to 0.5. The higher the frequency, the more bars will be visible.
phase
Phase of sine wave. The value should be from 0 to 2*PI (approximately 6.28). As the phase is changed, the alignment of the bars is changed. This can be used to line up the bars with image content or boundaries.
attenuation
Attenuation of sine wave. The value should be from -0.01 to 0.01. Attenuation adjusts how much the amplitude of the sine wave is decreased or increased as the sine wave proceeds. It can be used to cause the lighting to fade or intensify.

Description:

This method changes the colors of an image according to the pattern of a sine wave. The image will appear to have regularly spaced bars of light and/or shadow overlaid on top of it.

Applicability:

All except bitonal, non-gray Indexed and Grayscale with LUT.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_free_radial_light

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_free_radial_light(
    HIGEAR  hIGear,
    AT_POINT center,
    AT_INT pointCount,
    AT_FLOAT points[],
    AT_INT channelCount,
    AT_FLOAT amplitude[],
    AT_FLOAT frequency,
    AT_FLOAT phase,
    AT_FLOAT attenuation
);

Arguments:

hIGear
Image to apply free radial light effect to.
center
Center point in the image (in pixels) about which the effect is applied.
pointCount
Length of the points array.
points[ ]
Array of points containing relative light deviations along the period of the sine wave. Each value typically ranges from -1 to 1. The number of points is flexible and should be chosen based on the period length relative to the image size and desired resolution of the effect.
channelCount
Number of image channels to apply the effect to.
amplitude[ ]
Controls the magnitude of color adjustment for each channel of the image. The number of elements of the array is typically set to the number of channels in the image. Each value should range from 0 to 2, although higher values are possible. 0 represents no change in the image color. Higher values represent more intense change. Color changes are clipped, so higher values result in a harder edge to the waveform. Array length must be equal to channelCount.
frequency
Frequency of sine wave. The value should be from 0 to 0.5. The higher the frequency, the more bars will be visible.
phase
Phase of sine wave. The value should be from 0 to 2*PI (approximately 6.28). As the phase is changed, the alignment of the bars is changed. This can be used to line up the bars with image content or boundaries.
attenuation
Attenuation of sine wave. The value should be from -0.01 to 0.01. Attenuation adjusts how much the amplitude of the sine wave is decreased or increased as the sine wave proceeds. It can be used to cause the lighting to fade or intensify.

Description:

This method changes the colors of an image according to the pattern of a sine wave. The image will appear to have regularly spaced bars of light and/or shadow overlaid on top of it in a radial pattern.

Applicability:

All except bitonal, non-gray Indexed and Grayscale with LUT.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_lens_flare

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_lens_flare(
    HIGEAR  hIGear,
    AT_INT  xPos,
    AT_INT  yPos,
    AT_DOUBLE primaryBrightness,
    AT_DOUBLE secondaryBrightness,
    AT_MODE  flareType
);

Arguments:

hIGear
Image to apply lens flare effect to.
xPos
X coordinate of the primary flare.
yPos
Y coordinate of the primary flare.
primaryBrightness
Brightness of the primary flare. This value should range from 0 to 1.
secondaryBrightness
Brightness of the secondary flare. This value should range from 0 to 1.
flareType
Predefined flare type to use. Determines the shape and appearance of the lens flare elements.

Description:

This method applies a lens flare effect to the image. The effect simulates a bright light, such as the sun, and some reflections within the lens. It is typically used to add a sense of drama or realism to a photographic image.

Applicability:

RGB-based colorspaces only.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_mosaic_tiles

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_mosaic_tiles(
    HIGEAR hIGear,
    AT_MOSAIC_FILL_PARAMS* fillParams,
    AT_MOSAIC_CELL_PARAMS* cellParams,
    AT_MOSAIC_BORDER_PARAMS* borderParams,
    AT_MOSAIC_SHADOW_PARAMS* shadowParams,
    LPAT_RECT lpRect
);

Arguments:

hIGear
Image to apply the effect to.
fillParams
Mosaic fill parameters.
cellParams
Mosaic cell parameters.
borderParams
Mosaic border parameters.
shadowParams
Mosaic shadow parameters.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.

Description:

Provides a 3D mosaic effect on the hIGear image.

AT_MOSAIC_BORDER_PARAMS is a structure that contains the Mosaic border parameters. Border color should have the same colorspace and channel depths as the image to which the effect is applied.

struct tagAT_MOSAIC_BORDER_PARAMS
{
    AT_INT Width;
    AT_INT Height;
    AT_INT Irregularity;
    AT_FLOAT Opacity;
    HIGPIXEL hColor;
};
typedef struct tagAT_MOSAIC_BORDER_PARAMS
AT_MOSAIC_BORDER_PARAMS;

AT_MOSAIC_FILL_PARAMS is a structure that contains the Mosaic fill parameters. Fill color should have the same colorspace and channel depths as the image to which the effect is applied.

struct tagAT_MOSAIC_FILL_PARAMS
{
    AT_FLOAT Opacity;
    HIGPIXEL hColor;
};
typedef struct tagAT_MOSAIC_FILL_PARAMS AT_MOSAIC_FILL_PARAMS;

AT_MOSAIC_SHADOW_PARAMS is a structure that contains the Mosaic shadow parameters.

struct tagAT_MOSAIC_SHADOW_PARAMS
{
    AT_BOOL Enabled;
    enumCompass Direction;
    AT_FLOAT Threshold;
    AT_BOOL HighResolution;
    AT_FLOAT Intensity;
};
typedef struct tagAT_MOSAIC_SHADOW_PARAMS
AT_MOSAIC_SHADOW_PARAMS;

AT_MOSAIC_CELL_PARAMS is a structure that contains the Mosaic cell parameters.

struct tagAT_MOSAIC_CELL_PARAMS
{
    enumIGMosaicType Type;
    AT_INT Width;
    AT_INT Height;
    AT_INT PolarCenterX;
    AT_INT PolarCenterY;
};
typedef struct tagAT_MOSAIC_CELL_PARAMS AT_MOSAIC_CELL_PARAMS;

Applicability:

All except bitonal, non-gray Indexed and Grayscale with LUT.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FX_motion

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_motion (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const UINT nExtent,
    const AT_MODE nDirection
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to be processed. Set = NULL for the whole image to be processed. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nExtent
Set to a UINT for the amount of motion you would like applied. If nDirection will be set to "S, W, E, N", the correct range for this variable is 2 - 15. If nDirection will be set to "SE, NE, NW, SW", the correct range for this variable is 3 - 22. This variable determines the extent to which the pixels will be "moved" or "smeared", or literally how many pixel lengths each pixel will "move over."
nDirection
An AT_MODE Compass direction constant. Please see accucnst.h file or the descriptin of IG_FX_emboss () function for full list of these constants.

Description:

This function makes the image look as though it was moving when the image was captured. The amount of motion depends on the nAmount parameter. A larger nAmount makes the motion appear faster. Use nDirection to select which direction the image appears to be moving toward. lpRect specifies what portion of the image is to be affected.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;  /* HIGEAR handle of image */
/* Blur whole image to imply fast motion to the south-east:  */
IG_FX_motion ( hIGear, NULL, 6, IG_COMPASS_SE );

Sample:

FlashPix


IG_FX_noise

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_noise (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const WORD nType,
    const DOUBLE dblStrength,
    const INT nHitRate,
    const DOUBLE dblSigma,
    const AT_MODE nColorChannel
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to be processed. NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nType
An IG_NOISE constant such as IG_NOISE_LINEAR, IG_NOISE_GAUSSIAN
dblStrength
From 0.0 to 127.0, specifying the degree of noise alteration to introduce into affected pixels
nHitRate
Set = 1 to add noise to all pixels, > 1 to skip pixels, only adding noise to some. Larger values cause fewer pixels to be affected. Valid range: 1 to 500
dblSigma
Used with IG_NOISE_GAUSSIAN, range: 0.1-25.0
nColorChannel
An IG_COLOR_COMP_ constant. See file accucnst.h for the full list of these constants.

Description:

This function is used to create noise in an image. This can make an image look older. nHitRate selects how many pixels may have noise introduced into them. dblStrength determines how strongly a pixel's value is to be altered when it is selected to be altered. nType determines the algorithm used to determine the noise alteration.

nHitRate = 1 indicates that almost every pixel should be affected. A value of 100 would indicate that every 100th pixel should be affected. dblStrength = 1.0 indicates that a value of about +1 to -1 should be added to those pixels selected while dblStrength = 50.0 would increase the noise result by adding values in the range of -50 to +50.

Which pixels are altered and the amount of noise to apply are selected randomly.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask ().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear;  /* HIGEAR handle of image   */
/* Add moderate noise to about 5 percent of the pixels: */
IG_FX_noise ( hIGear, NULL, IG_NOISE_LINEAR, 30.0, 20, 1.0,
IG_COLOR_COMP_RGB );

Sample:

FlashPix


IG_FX_oilify

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_oilify(
    HIGEAR hIGear,
    AT_INT brushSize
);

Arguments:

hIGear
Image to apply oilify effect to.
brushSize
Brush size in pixels. As the brush size is increased, less detail is visible in the image and the effect becomes more dramatic.

Description:

This method applies an effect to an image that makes it appear similar to an oil painting.

Applicability:

All except bitonal, non-gray Indexed and Grayscale with LUT, bits per channel.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_parabola

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_parabola(
    HIGEAR hIGear,
    AT_POINT Center,
    AT_FLOAT fHeight,
    AT_INT nRadiusX,
    AT_INT nRadiusY,
    AT_BOOL bInterpolate,
    HIGPIXEL hbkColor,
    LPAT_RECT lpRect
);

Arguments:

hIGear
Image to apply the effect to.
Center
Parabola center, in pixels.
fHeight
Extrusion strength.
nRadiusX
Radius of the modified area in X direction, in pixels.
nRadiusY
Radius of the modified area in Y direction, in pixels.
bInterpolate
If TRUE, interpolation is used during processing.
hbkColor
Background color. It should have the same colorspace and channel depths as the image to which the effect is applied.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.

Description:

Provides the effect of warping around a paraboloid on the hIGear image.

Applicability:

All except bitonal if interpolation is off; All except bitonal, non-gray Indexed and Grayscale with LUT if interpolation is on.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FX_perspective

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_perspective(
    HIGEAR hIGear,
    AT_POINT LeftTop,
    AT_POINT RightTop,
    AT_POINT LeftBottom,
    AT_POINT RightBottom,
    HIGPIXEL hbkColor,
    LPAT_RECT lpRect
);

Arguments:

hIGear
Image to apply the effect to.
LeftTop
Position to move the left top image corner to.
RightTop
Position to move the right top image corner to.
LeftBottom
Position to move the left bottom image corner to.
RightBottom
Position to move the right bottom image corner to.
hbkColor
Background color. It should have the same colorspace and channel depths as the image to which the effect is applied.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.

Description:

This method provides a perspective-like effect by placing image corners to the specified points, and stretching the image linearly between them.

Applicability:

All except bitonal.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FX_pinch

Group: Image Processing

Declaration:

AT_ERRCOUNT EXPORT ACCUAPI IG_FX_pinch(
    HIGEAR hIGear,
    AT_POINT nCenter,
    AT_INT nRadius,
    AT_FLOAT fStrength,
    AT_BOOL bInterpolate,
    HIGPIXEL hbkColor,
    LPAT_RECT lpRect
);

Arguments:

hIGear
Image to apply the effect to.
nCenter
Pinch center, in pixels.
nRadius
Pinch radius, in pixels.
fStrength
Pinch strength. Positive value means that the page is pinched away from the center.
bInterpolate
If TRUE, interpolation is used during processing.
hbkColor
Background color. It should have the same colorspace and channel depths as the image to which the effect is applied.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.

Description:

This method pinches an image toward or away from the pinch center.

Applicability:

All except bitonal if interpolation is off; All except bitonal, non-gray Indexed and Grayscale with LUT if interpolation is on.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FX_pixelate

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_pixelate (HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const AT_DIMENSION nXRes,
    const AT_DIMENSION nYRes,
    const AT_MODE nResampleIn,
    const AT_MODE nResampleOut,
    const WORD radius,
    const LPAT_RGB lprgbBkColor
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to be processed. NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nXRes
The distance between the new pixels in the horizontal direction.
nYRes
The distance between the new pixels in the vertical direction.
nResampleIn
An IG_RESAMPLE_IN_ constant. These are listed in accucnst.h
nResampleOut
IG_RESAMPLE_OUT_SQUARE or _CIRCLE, the type of result to produce
nRadius
Radius of new "pixels", in pixels. Only applicable nResampleOut = IG_RESAMPLE_OUT_CIRCLE
LprgbBkColor
If circle, a far pointer to an AT_RGB struct specifying the background color surrounding the output circles.

Description:

This function redraws an image using what appear to be very large pixels. Use nXRes and nYRes to specify how many "apparent pixels" you want in the result.

nResampleIn tells ImageGear what to do with the block of pixels it reads in. It lets you have each output "apparent pixel" computed on the basis of the average, minimum, maximum, or central pixel in the block. Setting this to IG_RESAMPLE_IN_AV will set the value of all pixels in the block to the average all of the pixel values in the block.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    /* HIGEAR handle of image */
AT_ERRCOUNT nErrcount;
nErrcount = IG_FX_pixelate ( hIGear, NULL, 10, 10,
IG_RESAMPLE_IN_AVE,IG_RESAMPLE_OUT_SQUARE, 0, NULL );

Sample:

FlashPix


IG_FX_pointillist

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_pointillist(
    HIGEAR  hIGear,
    AT_INT pointSize,
    AT_INT pointType,
    AT_INT smoothness,
    HIGPIXEL hColor
);

Arguments:

hIGear
Image to apply pointillist effect to.
pointSize
Average size of each point (in pixels).
pointType
Type of brush to use for each point. Determines the shape of the point.
smoothness
Smoothness factor for each point. This value typically ranges from 0 to 100.
hColor
Specifies a background color to use. If this parameter is null, all points fit together smoothly with no gaps. If this parameter specifies a background a color, there are some occasional gaps which are set to the specified background color. The color should have the same colorspace and channel depths as the image to which the effect is applied.

Description:

This method applies an effect to an image that makes it appear to have been painted in the pointillism style of painting. The painted points are randomly generated, hence creating a slightly different look to the image each time the method is applied with the exact same settings.

Applicability:

All except bitonal; if non-gray Indexed, smoothness parameter is ignored.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_posterize

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_posterize (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const WORD nLevels,
    const AT_MODE nColorChannel
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying a rectangular portion of the image to be processed. NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nLevels
Number of unique colors or levels wanted in the resulting image. Valid range: 1-255
nColorChannel
IG_COLOR_COMP_RGB, or use IG_COLOR_COMP_R, _B, or _G to affect only one color channel.

Description:

Posterize reduces the number of actual colors in the image by creating a "stair case" in the palette. The number of steps wanted is specified by nLevels, in the range 1 to 255. nLevels = 255 would cause no effect while nLevels = 20 would cause 20 equally spaced steps to be created.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;	    /* HIGEAR handle of image  */
/* Use only 50 colors, regardless of how many unique pixel
values:  */
IG_FX_posterize ( hIGear, NULL, 50, IG_COLOR_COMP_RGB );

Sample:

FlashPix


IG_FX_radial_light

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_radial_light(
    HIGEAR  hIGear,
    AT_POINT center,
    AT_INT  channelCount,
    AT_FLOAT amplitude[],
    AT_FLOAT frequency,
    AT_FLOAT phase,
    AT_FLOAT attenuation
);

Arguments:

hIGear
Image to apply radial light effect to.
center
Center point in the image (in pixels) about which the effect is applied.
channelCount
Number of image channels to apply the effect to.
amplitude[ ]
Controls the magnitude of color adjustment for each channel of the image. The number of elements of the array is typically set to the number of channels in the image. Each value should range from 0 to 2, although higher values are possible. 0 represents no change in the image color. Higher values represent more intense change. Color changes are clipped, so higher values result in a harder edge to the waveform.
frequency
Frequency of sine wave. The value should be from 0 to 0.5. The higher the frequency, the more bars will be visible.
phase
Phase of sine wave. The value should be from 0 to 2*PI (approximately 6.28). As the phase is changed, the alignment of the bars is changed. This can be used to line up the bars with image content or boundaries.
attenuation
Attenuation of sine wave. The value should be from -0.01 to 0.01. Attenuation adjusts how much the amplitude of the sine wave is decreased or increased as the sine wave proceeds. It can be used to cause the lighting to fade or intensify.

Description:

This method changes the colors of an image according to the pattern of a sine wave. The image will appear to have regularly spaced bars of light and shadow overlaid on top of it in a radial pattern.

Applicability:

All except bitonal, non-gray Indexed and Grayscale with LUT.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_radial_wave

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_radial_wave(
    HIGEAR hIGear,
    AT_POINT nCenter,
    AT_FLOAT fAmplitude,
    AT_FLOAT fFrequency,
    AT_FLOAT fPhase,
    AT_FLOAT fAttenuation,
    AT_BOOL bInterpolate,
    HIGPIXEL hbkColor,
    LPAT_RECT lpRect
);

Arguments:

hIGear
Image to apply the effect to.
nCenter
Center of the wave effect, in pixels.
fAmplitude
Wave amplitude. Measurement units - pixel / 100.
fFrequency
The frequency is defined as 1 / T, where T is a wave period, in pixels.
fPhase
Wave phase, in radians.
fAttenuation
Wave attenuation. The attenuation factor of the wave is calculated as exp(-attenuation * r), where r is a distance from the wave center to the current wave point.
bInterpolate
If TRUE, interpolation is used during processing.
hbkColor
Background color. It should have the same colorspace and channel depths as the image to which the effect is applied.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.

Description:

This method provides a radial wave effect on the hIGear image.

Applicability:

All except bitonal if interpolation is off; All except bitonal, non-gray Indexed and Grayscale with LUT if interpolation is on.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FX_ripple

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_ripple(
    HIGEAR hIGear,
    AT_FLOAT depth,
    AT_INT xPeriod,
    AT_INT yPeriod,
    enumIGFXRipplePattern type,
    AT_FLOAT smoothness,
    AT_BOOL bInvert
);

Arguments:

hIGear
Image to apply the effect to.
depth
Strength of the ripple effect.
xPeriod
X period of the ripple pattern, in pixels.
yPeriod
Y period of the ripple pattern, in pixels.
type
Identifies a predefined ripple pattern. An enumIGFXRipplePattern value.
smoothness
Specifies how much the ripple pattern should be smoothed before applying.
bInvert
Inverts the ripple pattern, effectively swapping "convex" and "concave" areas.

Description:

This function provides the ripple effect on the image, as if it is looked at through a relief glass. The function uses one of the predefined ripple patterns.

Applicability:

All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_ripple_freehand

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_ripple_freehand(
    HIGEAR hIGear,
    AT_FLOAT depth,
    AT_FLOAT xDistribution[],
    AT_INT xPointCount,
    AT_FLOAT yDistribution[],
    AT_INT yPointCount,
    AT_INT xPeriod,
    AT_INT xPhase,
    AT_INT yPeriod,
    AT_INT yPhase,
    AT_FLOAT smoothness,
    AT_FLOAT angle
);

Arguments:

hIGear
Image to apply the effect to.
depth
Strength of the ripple effect.
xDistribution[ ]
Array of points containing relative light deviations along the X axis in each cell. Each value typically ranges from -1 to 1. The number of points is flexible and should be chosen based on the period length relative to the image size and desired resolution of the effect.
xPointCount
Length of the xDistribution array.
yDistribution[ ]
Array of points containing relative light deviations along the Y axis in each cell. Each value typically ranges from -1 to 1. The number of points is flexible and should be chosen based on the period length relative to the image size and desired resolution of the effect.
yPointCount
Length of the xDistribution array.
xPeriod
Horizontal period of the repeating pattern. It corresponds to number of points from the xDistribution array that should be used in the transform, and does not have to be equal to the length of the array.
xPhase
Index of the first point in the xDistribution array to be used in the transform.
yPeriod
Vertical period of the repeating pattern. It corresponds to number of points from the yDistribution array, that should be used in the transform, and does not have to be equal to the length of the array.
yPhase
Index of the first point in the yDistribution array to be used in the transform.
smoothness
Specifies how much the ripple pattern should be smoothed before applying.
angle
Specifies the angle for the ripple pattern, in degrees. Valid range is from 0 to 360.

Description:

This function provides the ripple effect on the image, as if it is looked at through a relief glass. The function uses a custom ripple pattern, defined as two one-dimensional arrays containing light deviations in X and Y directions.

Applicability:

All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_ripple_texture

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_ripple_texture(
    HIGEAR hIGear,
    HIGEAR hTexture,
    AT_FLOAT depth,
    AT_FLOAT scale,
    AT_INT xOffset,
    AT_INT yOffset,
    AT_FLOAT smoothness,
    AT_BOOL bInvert
);

Arguments:

hIGear
Image to apply the effect to.
hTexture
Image to use as a ripple pattern.
depth
Strength of the ripple effect.
scale
Specifies the scaling factor for pattern image.
xOffset
Horizontal offset at which the upper left corner of the ripple texture shall be placed.
yOffset
Horizontal offset at which the upper left corner of the ripple texture shall be placed.
smoothness
Specifies how much the ripple pattern should be smoothed before applying.
bInvert
Inverts the ripple pattern, effectively swapping "convex" and "concave" areas.

Description:

This function provides the ripple effect on the image, as if it is looked at through a relief glass. The function uses an image as a ripple pattern. If the scaled ripple pattern image is smaller than the source image, or if offsets are greater than 0, pattern is repeated over the image.

Applicability:

All colorspaces for image, DibStd for texture. The first channel of the texture is used as ripple mask.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_shear

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_shear(
    HIGEAR  hIGear,
    AT_DOUBLE* curvePoints,
    AT_INT   pointCount,
    enumIGIPShearFillStyle fillStyle,
    AT_BOOL interpolate,
    AT_BOOL vertical,
    HIGPIXEL hbkColor
);

Arguments:

hIGear
Image to apply shear effect to.
curvePoints
The array of offsets to move the image by. Every offset is in the range -1 to 1. Negative values shift the raster/column to the left, while positive values shift it to the right. The number of offsets is equal to the image width or height depending on the direction of movement (horizontal or vertical).
pointCount
Specifies curvePoints array length.
fillStyle
Specifies how the empty image area is filled.
interpolate
If true, interpolation is used to smooth shifted pixel values.
vertical
If true, the direction of motion is vertical. Otherwise, the direction is horizontal.
hbkColor
Background color to use for filling empty image area. Only used if the specified fill style uses a fill color. It should have the same colorspace and channel depths as the image to which the effect is applied.

Description:

This method applies a shearing effect to an image, moving the image rasters or columns according to the specified offsets.

The fillStyle parameter can be set to one of the following values:

Name
Description
IG_IP_SHEAR_FILLCOLOR
Empty area is filled with the specified color.
IG_IP_SHEAR_NOCHANGE
Empty area remains unchanged.
IG_IP_SHEAR_REPEATEDGE
Empty area is filled with the first or last raster color.
IG_IP_SHEAR_REPEATRASTER
The raster is repeated periodically across the empty area.

Applicability:

All if interpolation is off; All except non-gray Indexed and Grayscale with LUT if interpolation is on.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_solarize

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_solarize(
    HIGEAR hIGear,
    AT_INT nThreshold
);

Arguments:

hIGear
Image to apply the effect to.
nThreshold
Specifies minimum intensity at which the pixels should be inverted.

Description:

The Solarize effect mimics the accidental exposure of photographic film to light, by inverting the colors of pixels whose lightness exceeds a given threshold. To calculate the threshold, use the following formula:

2^bpc (i.e., 24bit RGB is 8bpc, 2^8 = 256, hence the range is 0
to 256)

Applicability:

All except bitonal, non-gray Indexed and Grayscale with LUT.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_spatter

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_spatter(
    HIGEAR hIGear,
    AT_INT diffusionHor,
    AT_INT diffusionVert,
    AT_INT smoothness
);

Arguments:

hIGear
Image to apply spatter effect to.
diffusionHor
Factor of horizontal diffusion. The greater this value, the deeper the horizontal diffusion. Typical values range from 1 to 20.
diffusionVert
Factor of vertical diffusion. The greater this value, the deeper the vertical diffusion. Typical values range from 1 to 20.
smoothness
Smoothness factor of diffusion. Typical values range from 0 to 100.

Description:

This method applies a spatter effect to an image, making it look as if it was painted in the impressionist style of painting. The painted points are randomly generated, hence creating a slightly different look to the image each time the method is applied with the exact same settings.

Applicability:

All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_FX_sphere

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_sphere(
    HIGEAR hIGear,
    AT_POINT Center,
    AT_INT nRadius,
    AT_INT nHeight,
    AT_BOOL bInterpolate,
    HIGPIXEL hbkColor,
    LPAT_RECT lpRect
);

Arguments:

hIGear
Image to apply the effect to
Center
Sphere center, in pixels.
nRadius
Sphere radius, in pixels.
nHeight
Height of the sphere segment, in pixels. Height can be changed from (-radius) to (radius).
bInterpolate
If TRUE, interpolation is used during processing.
hbkColor
Background color. It should have the same colorspace and channel depths as the image to which the effect is applied.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.

Description:

This method provides the effect of warping around a sphere on the hIGear image.

Applicability:

All except bitonal if interpolation is off; All except bitonal, non-gray Indexed and Grayscale with LUT if interpolation is on.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FX_spotlight

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_spotlight (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const AT_PIXPOS nCenterX,
    const AT_PIXPOS nCenterY,
    const AT_DIMENSION nRadius,
    const UINT nDarkenBy,
    const AT_PIXEL nSmoothing
);

Arguments:

hIGear
HIGEAR handle of an image to place the spotlight effect into
lpRect
Far pointer to an AT_RECT struct specifying a rectangular portion of the image to be processed. NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nCenterX
X coordinate of the center of the circle to receive a spotlight effect; 0 to Width - 1
nCenterY
Y coordinate of the center of the circle; 0 to Height - 1
nRadius
Radius of the circle, in pixels; 2 to Height - 2
nDarkenBy
How much to darken the remainder of the image
nSmoothing
0 to 255, specifying how much smoothing to apply at the edges; 0 = sharp edges, > 0 = smoother edges.

Description:

This function produces a "spotlight" effect within the circle specified by nRadius and (nCenterX, nCenterY). It leaves the pixels within the circle unchanged while darkening the surrounding pixels by reducing their intensity. Use nDarkenBy to specify the reduction in intensity of the surrounding pixels.

Use nSmoothing to specify the amount of smoothing at the perimeter of the circle. nSmoothing = 0 will leave the sharpest edge.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. (See above.) However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;  /* HIGEAR handle of image   */
AT_PIXPOS nXc, nYc;  /* Coords of center of spotlight area */
AT_DIMENSION nWid, nHi; /* Will receive width and height of
image */
UINT nBpp;     /* Bits per pixel, not used */
AT_DIMENSION nRadius;  /* Radius of spotlight  */
IG_image_dimensions_get ( hIGear, &nWid, &nHi, &nBpp ); /* Get
Wid,Hi */
nXc = nWid / 2;   nYc = nHi / 2;   /* Coords of center */
/* Diameter will be half of smallest dimension:   */
nRadius =  (nWid < nHi) ?  nWid / 4  :  nHi / 4;
/* Darken outside the circle by 40, with some smoothing of
transition:  */
IG_FX_spotlight ( hIGear, NULL, nXc, nYc, nRadius, 40, 10 );

Sample:

FlashPix


IG_FX_stitch

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_stitch (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    AT_MODE nCompassDir,
    const DOUBLE dblStrength,
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying a rectangular portion of the image to be processed. NULL for the whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nCompassDir
An AT_MODE Compass direction constant. Please see accucnst.h file or the descriptin of IG_FX_emboss () function for full list of these constants.
dblStrength
0.0 to 5.0 (A very low value will produce a gray screen with no detail.)

Description:

This function produces an effect similar to IG_FX_emboss (), except that the output more closely resembles a quilted stitch pattern.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. (See above.) However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;        /* HIGEAR handle of image */
AT_RECT rcImageRect;  /* Image's current image rectangle */
/* Emboss only the image rect portion: */
IG_FX_stitch ( hIGear, &rcImageRect, IG_COMPASS_NE, 3.0 );

Sample:

FlashPix


IG_FX_texture

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_texture (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const HIGEAR hTextureImage
);

Arguments:

hIGear
HIGEAR handle of image to apply texture to.
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to be processed. Set = NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non rectangular ROI defined by the mask.
hTextureImage
HIGEAR handle of the 8 bit image to be applied to image hIGear to produce textured effect

Description:

This function applies a texture to an image. The texturing image is a small 8-bit grayscale image that is treated as a sign centered image. Pixels in the texture image that are 127 have no effect on the original image, and the farther a texture image pixel is from 127, the greater its effect. The texture image is tiled over the entire original image starting in the top left corner. Any left over is clipped.

NOTE: Sign centered images can be created using the emboss function.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: See the descriptions of "IG_IP_NR_ROI_mask_associate" described on page -2032 and "IG_IP_NR_ROI_to_HIGEAR_mask" described on page -2037 for more details.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    /* Handle of image to be textured */
HIGEAR hTextureImage; /* Handle of 8 x 8 pixel 8-bit gray level
texturing image */
/* Apply texture to the whole image: */
IG_FX_texture ( hIGear, NULL, hTextureImage );

Sample:

FlashPix


IG_FX_twist

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_twist (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const AT_MODE nTwistType,
    const UINT nSquareSize
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image to be processed. Use NULL for whole image. Before ImageGear performs this operation, it determines if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear overrides the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nTwistType
One of the IG_TWIST_ constants:
IG_TWIST_90
IG_TWIST_180
IG_TWIST_270
IG_TWIST_RANDOM
nSquareSize
Size in pixels of the regions to which to apply twisting (valid range: 2 to 50).

Description:

This function applies a special effect that makes the image look as if it is being viewed through a shower curtain. The image can still be seen but it is chopped up so that detail is lost.

Each square of pixels of size nSquareSize in the image is rotated according to nTwistType. If IG_TWIST_RANDOM is chosen then each block is rotated one of the directions selected randomly.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: See IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability:

All except 1bpp indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* Handle of image to apply twisting to  */
/* Apply random twisting to 16 x 16 pixel squares of image:  */
IG_FX_twist ( hIGear, NULL, IG_TWIST_RANDOM, 16 );

Sample:

FlashPix


IG_FX_watermark

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FX_watermark (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const HIGEAR hWatermark
);

Arguments:

hIGear
HIGEAR handle of image to watermark
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to be processed. Set = NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
hWatermark
8-bit sign centered image to use for watermarking

Description:

This function is used to produce a watermark like effect. 8-bit sign centered image hWatermark is scaled to match image hIGear and is added to it.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability:

All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    /* Handle of image to apply watermark to  */
HIGEAR hWMarkImage; /* Handle of watermark image  */
IG_FX_watermark ( hIGear, NULL, hWMarkImage );

Sample:

FlashPix


IG_gctrl_item_by_index_get

Group: Global Parameters

Declaration:

AT_BOOL  ACCUAPI  IG_gctrl_item_by_index_get(
    UINT nIndex,
    LPCHAR CtrlID,
    DWORD dwIDSize,
    LPAT_MODE lpnValType,
    LPVOID lpValue,
    DWORD dwValSize,
    LPDWORD lpdwValSize,
    LPCHAR lpTextInfo,
    DWORD dwTextBufSize,
    LPDWORD lpdwTextInfoSize
);

Arguments:

nIndex
IN: Index of global control parameter in the array.
CtrlID
OUT: The name of global control parameter.
dwIDSize
IN: Size of CtrlID in bytes.
lpnValType
OUT: The type of global control parameter value.
lpValue
OUT: Buffer where to copy control parameter value.
dwValSize
IN: Size of lpValue buffer in bytes.
lpdwValSize
OUT: Actual size of parameter value in bytes.
lpTextInfo
OUT: Buffer where to copy text description of global control parameter.
dwTextBufSize
IN: Size of lpTextInfo buffer in bytes.
lpdwTextInfoSize
OUT: Actual size of the text description of parameter.

Description:

This function is like IG_gctrl_item_get () but returns information about parameter determined by given index in array.

See also the section Working with Global Control Parameters.

Bits Per Pixel:

N/A

Return Value:

TRUE if global parameter with given name is found, FALSE if it is not exist.

Sample:

None


IG_gctrl_item_count_get

Group: Global Parameters

Declaration:

UINT  ACCUAPI  IG_gctrl_item_count_get();

Arguments:

None

Description:

This function returns total amount of global parameters in the list.

See also the section Working with Global Control Parameters.

Bits Per Pixel:

N/A

Return Value:

Integer value - amount of global parameters in the list.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gctrl_item_get

Group: Global Parameters

Declaration:

AT_BOOL  ACCUAPI  IG_gctrl_item_get(
    LPCHAR CtrlID,
    LPAT_MODE lpnValType,
    LPVOID lpValue,
    DWORD dwValSize,
    LPDWORD lpdwValSize,
    LPCHAR lpTextInfo,
    DWORD dwTextBufSize,
    LPDWORD lpdwTextInfoSize
);

Arguments:

CtrlID
IN: The name of global control parameter.
lpnValType
OUT: The type of global control parameter value.
lpValue
OUT: Buffer where to copy control parameter value.
dwValSize
IN: Size of lpValue buffer in bytes.
lpdwValSize
OUT: Actual size of parameter value in bytes.
lpTextInfo
OUT: Buffer where to copy text description of global control parameter.
dwTextBufSize
IN: Size of lpTextInfo buffer in bytes.
lpdwTextInfoSize
OUT: Actual size of the text description of parameter.

Description:

This function return all information about global control parameter identified by name CtrlID. Return TRUE if parameter with given name is found and FALSE if parameter with given name is not exist.

See also the section Working with Global Control Parameters.

Bits Per Pixel:

N/A

Return Value:

TRUE if global parameter with given name is found, FALSE if it is not exist.

Sample:

None


IG_gctrl_item_id_get

Group: Global Parameters

Declaration:

AT_BOOL  ACCUAPI  IG_gctrl_item_id_get(
    UINT nIndex
    LPCHAR lpCtrlID,
    UINT nBufSize
);

Arguments:

nIndex
OUT: An index of lpCtrlID global control parameter in the parameters array.
lpCtrlID
IN: The name of global control parameter.
nBufSize
IN: Size of lpCtrlID buffer in bytes

Description:

This function returns index of the global control parameter with given name in array.

See also the section "Working with Global Control Parameters".

Bits Per Pixel:

N/A

Return Value:

TRUE if global parameter with given name is found, FALSE if it is not exist.

Sample:

None


IG_gctrl_item_set

Group: Global Parameters

Declaration:

AT_ERRCODE  ACCUAPI IG_gctrl_item_set(
    LPCHAR CtrlID,
    AT_MODE nValueType,
    LPVOID lpValue,
    DWORD dwValueSize,
    LPCHAR lpTextInfo
);

Arguments:

CtrlID
IN: The name of global control parameter in form "<GRPNAME>.<Param name>".
nValueType
IN: The type of global control parameter value. Constant of kind AM_TID_...
lpValue
IN: Pointer to global control parameter value data.
dwValueSize
IN: Size of global control parameter value data (size of buffer lpValue)
lpTextInfo
IN: Text description of global control parameter value.

Description:

This function sets the value to global control parameter. If parameter with given name ControlID is not exist then it is added. If control parameter with given value is exist and callback function for it is not NULL then callback is called exactly after value is changed by this function. If lpTextInfo is not NULL then previous value of this field is changed to new value but if NULL then it is not changed.

See also the section Working with Global Control Parameters.

Bits Per Pixel:

N/A

Return Value:

Return value is a code of last error or NULL if success.

Sample:

None


IG_GUI_color_profile_attribute_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_color_profile_attribute_get(
    HWND hWnd,
    AT_MODE nAttributeID,
    LPVOID lpData
);

Arguments:

hWnd
Handle of window in which the image is displayed
nAttributeID
A variable of type AT_MODE, such as IG_GUI_WINDOW_PAINT
lpData
A VOID pointer to a variable of the type required by the nAttributeID parameter. This gets the value for the attribute defined by nAttributeID

Description:

This function gets the current attribute settings of the GUI window. As of this writing, there are only two attributes, but this may be expanded in the future.

  • IG_GUI_DATA_COLOR_COMPONENT: Retrieves information about color components to display.
  • IG_GUI_DATA_COLORPROFILE_STYLE: Retrieves the chart style.
NOTE: See IG_GUI_color_profile_attribute_set() for the values that lpData may have when either of the above-listed attributes are is used.

Bits Per Pixel:

1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

GUIWIN


IG_GUI_color_profile_attribute_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_color_profile_attribute_set(
    HWND hWnd,
    AT_MODE nAttributeID,
    LPVOID lpData
);

Arguments:

hWnd
Handle of the window in which an image is displayed
nAttributeID
A variable of type AT_MODE, such as IG_GUI_WINDOW_PAINT
lpData
A VOID pointer to a variable of the type required by the nAttributeID parameter. This sets the value for the attribute defined by nAttributeID.

Description:

This function sets the attribute settings of the GUI Color Profile window. Here are the settings available for nAttributeID as defined in accucnst.h, and what they mean:

NOTE: lpData is not the address of the data but a value to which the address should be passed.

1) If nAttributeID is set to a IG_GUI_DATA_COLOR_COMPONENT constant, then lpData should contain combinations of following flags:

  • IG_GUI_COLOR_COMPONENT_R: show chart for Red component
  • IG_GUI_COLOR_COMPONENT_G: show chart for Green component
  • IG_GUI_COLOR_COMPONENT_B: show chart for Blue component
  • IG_GUI_COLOR_COMPONENT_I: show chart for Intensity

The ImageGear default value for IG_GUI_DATA_COLOR_COMPONENT is:

IG_GUI_COLOR_COMPONENT_R | IG_GUI_COLOR_COMPONENT_G | IG_GUI_COLOR_COMPONENT_B

2) If nAttributeID is set to a constant then lpData should contain a combination of the following flags:

  • IG_GUI_COLORPROFILE_STYLE_STACK - Draw stacked chart. Each chart bottom is the top of the previous chart.
  • IG_GUI_COLORPROFILE_STYLE_SEPARATE - Draw each chart in separate area. Each chart has its own base line
  • IG_GUI_COLORPROFILE_STYLE_OVERLAID - Draw one chart over previous. Only one of the styles listed above may be specified.
  • IG_GUI_COLORPROFILE_STYLE_TRACK -- Draw line following the mouse
  • IG_GUI_COLORPROFILE_STYLE_XY -- Show mouse cursor coordinates in the GUI window.

The default ImageGear setting for IG_GUI_DATA_COLORPROFILE_STYLE is:

IG_GUI_COLORPROFILE_STYLE_TRACK | IG_GUI_COLORPROFILE_STYLE_SEPARATE

Bits Per Pixel:

1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

GUIWIN


IG_GUI_color_profile_track_mouse

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_color_profile_track_mouse(
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndProfile,
    INT nX,
    INT nY
);

Arguments:

hIGear
HIGEAR handle of image
DwGrpID
Display group identifier used for image drawing the options to be used in GUI calculations.
hWndProfile
Handle of GUI Profile window
nX
X position of left mouse button click
nY
Y position of left mouse button click

Description:

This function can be called while processing the Windows mouse-button-down message WM_LBUTTONDOWN, for a Color Profile window's parent window.

NOTE: See the IG_GUI_color_profile_window_create() function.

You can obtain (nX, nY), the coordinates of the mouse click, from the parameters passed by Windows with the WM_... message. See the sample application GUIWIN for a description of how to use this and related IG_GUI_color_profile_...() functions.

NOTE: You cannot use IG_GUI_..._track_mouse() functions with a WM_RBUTTONDOWN message. ImageGear only responds to left mouse button clicks.

Bits Per Pixel:

24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

DISPLAY, GUIWIN


IG_GUI_color_profile_update

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_color_profile_update (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWNDProfile
);

Arguments:

hIGear
HIGEAR handle of image
dwGrpID
Display group identifier used for image drawing which options to be used in GUI calculations.
HWNDProfile
Handle of GUI Profile window

Description:

This function should be called when a new image is loaded into the Color Profile window. It updates the client area of the Color Profile GUI window specified by hwndProfile. If the image handle associated with the GUI window is not the same as the image pointed to by the hIGear parameter, this function will update hWNDProfile to point to the new HIGEAR image.

Bits Per Pixel:

1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

DISPLAY


IG_GUI_color_profile_window_create

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_color_profile_window_create(
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndParent,
    HWND hwndImage,
    DWORD dwStyle,
    const LPSTR lpszTitle,
    INT nX,
    INT nY,
    INT nWidth,
    INT nHeight,
    HWND FAR* lphwndProfile
);

Arguments:

hIGear
HIGEAR handle of image
dwGrpID
Display group identifier used for image drawing which options to be used in GUI calculations.
hWndParent
Handle of Parent window
dwStyle
Window style bits
HWND hwndImage
The handle of the window where the image is drawn.
lpszTitle
Title of color_profile Window
nX
X position of upper left corner of color_profile window
nY
Y position of upper left corner of color_profile window
nWidth
Width of color_profile window
nHeight
Height of color_profile window
lphwndProfile
Far pointer to HWND object to hold color_profile window handle

Description:

This function creates a Color Profile GUI window. This window is designed to display image data along the line that is specified by dragging the mouse. When the mouse is moved about in hwndParent window with the left button held down, a line is painted over the image from the point where mouse was clicked to the current mouse position. As the line is moved, the GUI window displays image data from the selected area in chart format.

By default, this function will create a GUI window using the style WS_OVERLAPPEDWINDOW. To modify the attributes of the window, use IG_GUI_color_profile_attribute_set ().

Bits Per Pixel:

1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

DISPLAY, GUIWIN


IG_gui_colorbook_properties_dlg

Group: GUI

Declaration:

BOOL  ACCUAPI IG_gui_colorbook_properties_dlg(
    HWND hWnd,
    HIGCOLORBOOK hColorBook
);

Parameters:

hWnd
Handle of the parent window.
hColorBrook
Handle of the color book object.

Description:

This function displays Color Book properties dialog allowing the user to work with color book colors.

Return Value:

Returns TRUE if OK button is clicked, FALSE - otherwise.


IG_gui_colorbooks_dlg

Group: GUI

Declaration:

BOOL  ACCUAPI	IG_gui_colorbooks_dlg(
    HWND hWnd
    );

Parameters:

hWnd
Handle of the parent window.

Description:

This function displays Color Books dialog allowing the user to manipulate with the loaded books as well as to add new and remove existing.

Return Value:

Returns TRUE if OK button is clicked, FALSE - otherwise.


IG_gui_extrachannel_colorchoice_dlg

Group: GUI

Declaration:

BOOL  ACCUAPI IG_gui_extrachannel_colorchoice_dlg(
    HWND hWnd,
    HIGEAR hIGear,
    AT_UINT nIndex
);

Parameters:

hWnd
Handle of the parent window.
hIGear
Handle to the image.
nIndex
Index of the extra channel.

Description:

This function displays a color specification of the specified extra channel. This dialog can be used for editing extra channel's color.

Return Value:

Returns TRUE if OK button is clicked, FALSE - otherwise.


IG_gui_extrachannels_dlg

Group: GUI

Declaration:

BOOL  ACCUAPI IG_gui_extrachannels_dlg(
    HWND hWnd,
    HIGEAR hIGear
);

Parameters:

hWnd
Handle of the parent window.
hIGear
Handle to the image.

Description:

This function displays a list of extra channels available in the image. This dialog can be used turn on and off extra channels for display.

Return Value:

Returns TRUE if OK button is clicked, FALSE - otherwise.


IG_GUI_histogram_update

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT IG_GUI_histogram_update(HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hwndHistogram
);

Arguments:

hIGear
HIGEAR handle to the image
dwGrpID
Identifier of group where to get display options for creating palette.
hwndHistogram
Windows handle to the GUI Histogram window

Description:

This function updates the client area of the Histogram GUI window specified by hwndHistogram.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: DISPLAY, GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_histogram_window_create

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_histogram_window_create(
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hwndParent,
    const LPSTR lpcszTitle,
    INT x,
    INT y,
    INT nWidth,
    INT nHeight,
    HWND FAR *lphwndHisto
);

Arguments:

hIGear
HIGEAR handle to the image to create a histogram for
DwGrpID
Identifier of display group of where to get options for creating palette.
hwndParent
Identifies the parent or owner window of the window being created.
LpcszTitle
Points to a null-terminated string that specifies the window name
x
Specifies the initial horizontal position of the window.
y
Specifies the initial vertical position of the window
nWidth
Specifies the width, in device units, of the window
nHeight
Specifies the height, in device units, of the window
lphwndHisto
Address of HWND variable to obtain the handle of the created window

Description:

This function creates a GUI Histogram window. This window is designed to display an image histogram. The Histogram GUI window also contains menus. From the View menu you can choose "R" to show the red channel population of the pixels; or "I", which shows the arithmetic mean of all channel values for the pixels. For 1, 4, or 8-bit images, you may only select "I".

The GUI Histogram window menus also allow you to save your histogram to a file or to the Clipboard.

By default, the GUI Histogram window will be created with the style WS_OVERLAPPEDWINDOW.

Bits Per Pixel: 1,4,8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: DISPLAY, GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_magnify_attribute_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_magnify_attribute_get(
    HWND hwndMag,
    AT_MODE nAttributeID,
    LPVOID lpData
);

Arguments:

hwndMag
Handle to the Magnifier Window created by the IG_GUI_magnify_window_create (). If a popup magnifier is being used, then specify NULL for this parameter.
nAttributeID
One of the GUI Magnify control options defined in accucnst.h
LpData
The value currently assigned to the attribute will be returned here. The value depends on the nAttributeID value:
IG_GUI_MAGNIFY_POPUP_WIDTH - Width, in pixels of the window
IG_GUI_MAGNIFY_POPUP_HEIGHT - Height, in pixels, of the window
IG_GUI_MAGNIFY_POPUP_ZOOM - Zoom factor (2 = 2x, 10=10x, etc.)
IG_GUI_MAGNIFY_POPUP_CIRCLE - Only used for Popup window TRUE (circle) or FALSE (square) - Win32 only

Description:

This function is used to get the various attributes of the Magnifier window.

NOTE: See the function "IG_GUI_magnify_window_create" described on page -1809.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: MAGNIFY, GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_magnify_attribute_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_magnify_attribute_set(
    HWND hwndMag,
    AT_MODE nAttributeID,
    const LPVOID lpData
);

Arguments:

hwndMag
Handle to the Magnifier Window created by the IG_GUI_magnify_window_create (). If a popup magnifier is being used, then specify NULL for this parameter.
nAttributeID
One of the GUI Magnify control options defined in accucnst.h
lpData
The value to assign to the attribute. The value depends on the nAttributeID value:
IG_GUI_MAGNIFY_POPUP_WIDTH - Width, in pixels of the window
IG_GUI_MAGNIFY_POPUP_HEIGHT - Height, in pixels, of the window
IG_GUI_MAGNIFY_POPUP_ZOOM - Zoom factor (2 = 2x, 10=10x, etc.)
IG_GUI_MAGNIFY_POPUP_CIRCLE - Only used for Popup window TRUE (circle) or FALSE (square) - Win32 only.

Description:

This function is used to set the various attributes of the Magnifier window.

NOTE: See the function IG_GUI_magnify_window_create().

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: MAGNIFY, GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_magnify_GrpID_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_magnify_GrpID_get(
    HWND hwndMag,
    DWORD* pdwGrpID
);

Arguments:

HwndMag
Handle to magnify the window.
PdwGrpID
Pointer to where the magnify window group ID is to be received.

Description:

This function returns the group ID of the specified magnify window. This value can be used for magnify window display attribute corrections.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

/* Updating magnify window with new gamma correction: */
      DWORD dwGrpID;
    IG_GUI_magnify_GrpID_get(hwndMag, &dwGrpID);
IG_dspl_gamma_correction_set(hIGear, dwGrpID,
IG_DSPL_ALL_CHANNELS, 1.0, 1.0, 1.0);
InvalidateRect(hwndMag, NULL, FALSE);
UpdateWindow(m_hwndMag);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_magnify_track_mouse

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_magnify_track_mouse (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndMagnify,
    INT nX,
    INT nY
);

Arguments:

hIGear
HIGEAR handle of image
DwGrpID
Identifier of group which is used for drawing the image in the parent window.
HwndMagnify
Handle of GUI Magnify window
nX
X position of left mouse button click
nY
Y position of left mouse button click

Description:

This function can be called while processing the Windows mouse-button-down message WM_LBUTTONDOWN, for a magnify window's parent window. This function will show, magnified in the magnify window, the portion of the image that is at the location of the mouse click in the parent window.

NOTE: See the function IG_GUI_magnify_window_create() .

You can obtain the coordinates (nX, nY) of the mouse click, from the parameters passed by Windows with the WM_... message. See the sample application MAGNIFY for a description of how to use this and related IG_GUI_magnify_...() functions.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

NOTE: You cannot use IG_GUI_..._track_mouse() with a WM_RBUTTONDOWN message. ImageGear only responds to left mouse button clicks.

Example:

HIGEAR	hIGear;     /* Global handle of image in parent window  */
HWND	hWndParent;  /* Global Windows handle of that window  */
HWND	hWndMagnify;  /* Global HIGEAR handle of Magnify window */
AT_ERRCOUNT nErrcount; /* Returned count of errors  */
 ...
/* Create a Magnify window for the image in window hWndParent:
*/
nErrcount = IG_GUI_magnify_window_create ( hIGear,
IG_GRP_DEFAULT, hWndParent, "I.G. Mag Window", 50, 50, 200, 200,
&hWndMagnify );
 ...
/* Message-Handling routine: */
LPARAM CALLBACK  MsgHandler (HWND hWnd, UINT msg, WPARAM wParam,
LPARAM lParam );
{
 ...
switch (msg)
    {
    case WM_LBUTTONDOWN:
 /* if occurred in the Magnify window: */
        IG_GUI_magnify_track_mouse ( hIGear, IG_GRP_DEFAULT,
hWndMagnify, LOWORD(lParam), HIWORD(lParam) );
        /* The above will display magnified, the location where
the mouse was just clicked in the parent image window. */
 ...
    }
 ...
}
/* See also sample application MAGNIFY. */

Sample: MAGNIFY, DISPLAY, GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_magnify_update

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_magnify_update (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWNDMagnify
);

Arguments:

hIGear
HIGEAR handle of image
dwGrpID
Identifier of group which is used for drawing image in the parent window.
hWndMagnify
Handle of GUI Magnify window

Description:

This function may be called to update (repaint) the magnify window. For example, if the image being displayed in its parent window has changed.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	hIGear;    /* Global HIGEAR handle of image in parent
window */
HWND	hWndMagnify;/* Global HIGEAR handle of Magnify window     */
IG_GUI_magnify_update ( hIGear, IG_GRP_DEFAULT, hWndMagnify );

Sample: DISPLAY, GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_magnify_window_create

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_magnify_window_create (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndParent,
    const LPSTR lpszTitle,
    INT nX,
    INT nY,
    INT nWidth,
    INT nHeight,
    HWND FAR* lphWndMagnify
);

Arguments:

hIGear
HIGEAR handle of image
DwGrpID
Identifier of the group used for drawing image in the hWndParent window. A new group will be allocated internally for drawing image in the magnify window.
hWndParent
Handle of Parent window
lpszTitle
Title of Magnify Window
nX
X position of upper left corner of Magnify window
nY
Y position of upper left corner of Magnify window
nWidth
Width of Magnify window
nHeight
Height of Magnify window
lphWndMagnify
Far pointer to HWND object to hold Magnify window handle

Description:

This function is called to create a GUI magnify window. When the mouse is moved about in such a window with the left button held down, a small rectangle is dragged and the portion of the image inside the rectangle can be displayed (magnified) in the parent image window.

NOTE: See the IG_GUI_magnify_track_mouse() function.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See the example for function IG_GUI_magnify_track_mouse ().

Sample: MAGNIFY, DISPLAY, GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_active_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_active_get(
    HWND hwndPage,
    LPUINT lpPageNumber
);

Arguments:

hwndPage
Windows handle to the GUI Page Sorter window
lpPageNumber
A far pointer that returns the page number of the "active page"

Description:

This function returns the page number of the currently "active" image in the GUI Page Sorter window. The active image has a selection border around it. This function is a companion to IG_GUI_page_focus_set ()and IG_GUI_page_active_set () in that it returns the page number of the image on which the "focus" is set.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* This excerpt from the Page.c sample checks to see if there
are any pages in the GUI Window Sorter. If not, the file being
opened is made the "current page" (nCurrentPage) and page #1 is
set to the active page. If there are already pages, nCurrentPage
is set to the active page */
HIGEAR hIGear;    /* HIGEAR handle of image  */
UINT nCurrentPage;/* page number of the active page */
HWND hwndPage;  /* Windows handle to the Page Sorter*/
/* set the initial page */
if (!nCurrentPage)
{
    nCurrentPage = 1;
    /* set the active page */
    IG_GUI_page_active_set(hwndPage, nCurrentPage);
}
else
{
    /* get the new page */
    IG_GUI_page_active_get(hwndPage, &nCurrentPage);
    IG_GUI_page_handle_get(hwndPage, nCurrentPage,
        &hIGear);
}

Sample: PAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_active_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_active_set(
    HWND hwndPage,
    UINT nPage
);

Arguments:

hwndPage
HIGEAR Windows handle to the GUI Page Sorter window
nPage
Set to the page number of the image in the GUI Page Sorter window that you would like to make "active"

Description:

This function calls your selected callback function (of type LPFNIG_GUIPAGESELECTPROC) for the GUI Page Sorter window, as if the user had clicked on the page. IG_GUI_page_active_set() is similar to IG_GUI_page_focus_set (), but goes one step further by calling the select callback function.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

Please see the example code under IG_GUI_page_active_get ().

Sample: PAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_attribute_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_attribute_get(
    HWND hwndPage,
    AT_MODE nAttributeID,
    LPVOID lpData
);

Arguments:

hwndPage
Windows handle to the GUI Page Sorter window.
nAttributeID
An integer variable of type AT_MODE that indicates the attrtibute for which to get the current setting. These constants have the prefix IG_GUI_PAGE_ and are defined in accucnst.h.
lpData
The current setting of the page attribute referred to by nAttributeID.

Description:

This function returns the current setting for the GUI Page attribute indicated by nAttributeID. See IG_GUI_page_attribute_set () for a complete description of the attributes that can be changed.

NOTE: Currently it is possible to change the font title for Page windows that is created by IG_GUI_page_window_create(). To set the font, use IG_GUI_page_attribute_set() and to get the font use IG_GUI_page_attribute_get() with the IG_GUI_PAGE_FONT_TITLE option. As in the case of a thumbnail window, the user is responsible for creating and deleting the font.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

UINT nThreshold;
/*Get the current antialiasing threshold */
IG_GUI_page_attribute_get(hWndPag, IG_GUI_PAGE_ALIAS_THRESHOLD,
(LPVOID)& nThreshold);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_attribute_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_attribute_set(
    HWND   hwndPage,
    AT_MODE nAttributeID,
    const LPVOID lpData
);

Arguments:

hwndPage
Windows handle of the GUI Page Sorter window.
nAttributeID
An integer variable of type AT_MODE that indicates the attrtibute for which to get the current setting. These constants have the prefix IG_GUI_PAGE_ and are defined in accucnst.h.
lpData
The new setting for the page attribute is referred to by nAttributeID.

Description:

This function allows you to change the settings for the GUI Page window. Set nAttributeID to the appropriate defined IG_GUI_PAGE_ constant and lpData to the appropriate value.

The table below lists the GUI Page Settings and indicates the various attributes that you should refer to: .

IMAGE CONTROL CONSTANTS
TYPE
VALUES RANGE
IG_GUI_PAGE_REALIZEPALETTETO
HWND
A window that contains the palette to use for the page thumbnails.
IG_GUI_PAGE_DRAGDROP
AT_BOOL
TRUE - moving page thumbnails is allowed within the page window if the SHIFT key is pressed.
IG_GUI_PAGE_ALIAS_THRESHOLD
UINT
Antialiasing threshold for 1-bit page thumbnails.

NOTE: Currently it is possible to change font title for Page windows that is created by IG_GUI_page_window_create(). To set the font use IG_GUI_page_attribute_set() and to get the font, use IG_GUI_page_attribute_get() with the IG_GUI_PAGE_FONT_TITLE option. As in the case of thumbnail window, the user is responsible for creating and deleting the font. See the example below.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/*Create the new page window with the new font */
HFONT hOldFont, hFont;
IG_GUI_page_window_create(hWnd, IG_GRP_DEFAULT+1, "Page
Window",
                        CW_USEDEFAULT, CW_USEDEFAULT, 320, 200,
&hwndPage);
hFont = CreateFontA(
       24, /*  height  */
       0, /*nWidth*/
       0, /*nEscapement*/
       0, /*nOrientation*/
       FW_NORMAL, /*fnWeight*/
       FALSE, /*fdwItalic*/
       FALSE, /*fdwUnderline*/
       FALSE, /*fdwStrikeOut*/
       ANSI_CHARSET, /*fdwCharSet*/
       OUT_DEFAULT_PRECIS, /*fdwOutputPrecision*/
       CLIP_DEFAULT_PRECIS, /*fdwClipPrecision*/
       DEFAULT_QUALITY, /*fdwQuality*/
       DEFAULT_PITCH,
       "Ariel" /*lpszFace*/
       );
if(hFont)
{
    IG_GUI_page_attribute_get(hwndPage, IG_GUI_PAGE_FONT_TITLE,
(LPVOID)&hOldFont);
    if(hOldFont)
    {
        DeleteObject(hOldFont);
    }
    IG_GUI_page_attribute_set(hwndPage, IG_GUI_PAGE_FONT_TITLE,
(LPVOID)hFont);
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_count_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_count_get(
    HWND hwndPage,
    LPUINT lpPageCount
);

Arguments:

hwndPage
Windows handle to the GUI Page Sorter window.
lpPageCount
A far pointer that returns the total number of pages (images) currently associated with the GUI Page Sorter.

Description:

This function returns the total number of pages (images) currently associated with the GUI Page Sorter window referenced by hwndPage. Be sure not to confuse this function with the IG_page_count_get_...() functions.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

Please see the example code under IG_GUI_page_window_create_ex ().

Sample: PAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_delete_CB_register

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_delete_CB_register(
    HWND hwndPage,
    LPFNIG_GUIPAGEDELETEPROC lpfnPageDeleteProc,
    LPVOID lpPrivate
);

Arguments:

hwndPage
Windows handle to the page sorter window
LpfnPageDeletProc
A far pointer to the callback function that you wish to register
LpPrivate
A far pointer to and private data that you would like to pass to the callback function.

Description:

This function registers a callback function of type LPFNIG_GUIPAGEDELETEPROC, in which you can write a function to receive notification of when a thumbnail is deleted.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

See the example code under LPFNIG_GUIPAGEDELETEPROC .

Sample: PAGE, GUISCAN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_document_refresh

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_document_refresh(
    HWND hwndPage,
    UINT nPage
);

Arguments:

hwndPage
HIGEAR Windows handle to the GUI Page Sorter
nPage
Set to the UINT page number you would like to refresh/update

Description:

This function updates/refreshes the image in the GUI Page Sorter referenced by nPage. To refresh all of the images in the Page Sorter, call IG_GUI_page_document_update ().

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;   /* HIGEAR handle of image   */
AT_ERRCOUNT  nErrcount; /* Tally of IG errors on the stack */
HWND  hwndPage; /* Windows handle of the Page Sorter*/
UINT  nPage;    /* Page number of image to refresh  */
nPage = 5;
nErrcount = IG_GUI_page_document_refresh(hwndPage, nPage);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_document_update

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_document_update (
    HWND hwndPage,
    DWORD dwGrpID
);

Arguments:

hwndPage
Windows handle to the page sorter window to update
dwGrpID
Identifier of display group should be used for drawing thumbnail in the GUI page.

Description:

This function should be called when one or more of the images in the page sorter window has been modified (i.e. rotated, cropped, flipped.) Any modified image will be repainted in the page sorter window. To update just one particular image, use IG_GUI_page_document_refresh ().

NOTE: Also see IG_GUI_page_update() and IG_GUI_page_window_create()functions.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_file_append

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_file_append(
    HWND hwndPage,
    const LPSTR lpcszFileName
);

Arguments:

hwndPage
Windows handle to the GUI Page Sorter
lpcszFileName
Set to the path/filename of the image that you want to add to the GUI Page Sorter

Description:

This function appends a new image to the GUI Page Sorter window created with IG_GUI_page_window_create (). The image will be last in order of the images already displayed and will be assigned a page number equal to the last page number plus one, e.g. if the GUI Page Sorter contains five images, the image added with this function will be treated as page 6.

NOTE: To delete a page, use IG_GUI_page_remove()function.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;    /* HIGEAR handle of image */
HWND hWnd, hWndPage;    /* Windows handles */
AT_ERRCOUNT  nErrCount; /* tally of IG errors on the stack */
UINT nCurrentPage; /* number of page currently active */
case ID_FILE_OPENDOCUMENT:
    if (GetOpenImageFileName(hWnd, szFile, sizeof(szFile)))
    {
    SetCursor(LoadCursor(NULL, IDC_WAIT));
    /* create the page sorter window, if it does not already
exist*/
        if (!IsWindow(hwndPage))
        {
        nErrCount = IG_GUI_page_window_create(hWnd,
IG_GRP_DEFAULT,
        "Page Window", CW_USEDEFAULT,
        CW_USEDEFAULT, 320, 200, &hwndPage);
        /* attach select, delete and order callbacks */
        IG_GUI_page_order_CB_register(hwndPage,
        PageOrderProc, NULL);
        IG_GUI_page_select_CB_register(hwndPage,
        PageSelectProc, NULL);
        IG_GUI_page_delete_CB_register(hwndPage,
        PageDeleteProc, NULL);
        nCurrentPage = 0;
        }
        /* now add the full document to the page window */
        nErrCount = IG_GUI_page_file_append(hwndPage, szFile);
        /* set the initial page */
        if (!nCurrentPage)
        {
        nCurrentPage = 1;
        /* set the active page */
        IG_GUI_page_active_set(hwndPage, nCurrentPage);
        }
        else
        {
        /* get the new page */
        IG_GUI_page_active_get(hwndPage, &nCurrentPage);
        IG_GUI_page_handle_get(hwndPage, nCurrentPage, &hIGear);
        }
        /* change the title of the main window to reflect a
filename
            change */
        wsprintf(szBuf, "%s Page:  %d", (LPVOID)szFile,
nCurrentPage);
        SetWindowText(hWndMain, szBuf);
        /* tell windows to tell us to paint the new image */
        InvalidateRect(hWnd, NULL, FALSE);
        UpdateWindow(hWnd);
        SetCursor(LoadCursor(NULL, IDC_ARROW));
    }
break;

Sample: PAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_focus_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_focus_set(
    HWND hwndPage,
    UINT nPage,
    BOOL fScrollToThumbnail
);

Arguments:

hwndPage
HIGEAR Windows handle to the GUI Page Sorter
nPage
Set to the page number of the image in the Page Sorter that you would like to update.
fScrollToThumbnail
Set to TRUE, if you would like the Page Sorter to scroll the window so that nPage is shown. Set to FALSE, if you don't care need the image specified by nPage is shown in the window.

Description:

This function tells ImageGear which page should be highlighted and whether the scrollbars should be adjusted to make the page visible, if it is hidden.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;   /* HIGEAR handle of image */
AT_ERRCOUNT nErrcount; /* Tally of ImageGear errors on the stack
*/
HWND hwndPage; /* Windows handle to the Page Sorter window*/
nErrcount = IG_GUI_page_focus_set(hwndPage, 5, TRUE);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_handle_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_handle_get(
    HWND hwndPage,
    UINT nPage,
    LPHIGEAR lphIGear
);

Arguments:

hwndPage
Windows handle to the GUI Page Sorter window
nPage
Set to the number of the page (thumbnail) in the GUI Page Sorter window for which you would like the HIGEAR handle
lphIGear
A far pointer that returns the HIGEAR handle for the image in the GUI Page Sorter referenced by nPage

Description:

This function returns the HIGEAR handle for the image (thumbnail) in the GUI Page Sorter that you specify in nPage.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

Please see examples for IG_GUI_page_window_create () or IG_GUI_page_file_append () functions.

Sample: PAGE, GUISCAN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_insert

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_insert(
    HWND hwndPage,
    HIGEAR hIGear,
    UINT nPage
);

Arguments:

HwndPage
Windows handle to the Page Sorter window
hIGear
The HIGEAR handle of the image you would like to insert into the GUI Page Sorter window
nPage
Set this to the page number you would like to assign to the new HIGEAR image that you are adding to the GUI Page Sorter Window.

Description:

This function inserts a new image into the GUI Page Sorter window referenced by hwndPage. Set nPage to the page number that you would like ImageGear to assign to your newly inserted image. For example, if there are several images already in the GUI Page Sorter window, and you ask to insert the new image as page 3 (nPage = 3), the old page 3 becomes page 4, and the old page 4 becomes page 5, etc. The HIGEAR handles of the loaded images never change despite any changes in page numbers; all images retain their original HIGEAR handle values.

If you set nPage to a page number greater than the number of images in the GUI Page Sorter, the image will be appended. In other words, ImageGear will set its page number to the total number of pages + 1.

NOTE: To delete an image (thumbnail) from the GUI Page Sorter window, use IG_GUI_page_remove().

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;    /* HIGEAR handle of image */
AT_ERRCOUNT  nErrcount;  /* Tally of IG errors on the stack */
HWND  hwndPage;  /* Windows handle to GUI Page Sorter */
UINT nPage;    /* Page number to assign to new image */
nErrcount = IG_load_file("kittens.bmp", &hIGear);
/* Insert "kittens.bmp" as first image in GUI Page Sorter  */
AT_ERRCOUNT ACCUAPI IG_GUI_page_insert(hwndPage, hIGear, 1);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_order_CB_register

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_order_CB_register(
    HWND hwndPage,
    LPFNIG_GUIPAGEORDERPROC lpfnPageOrderProc,
    LPVOID lpPrivate
);

Arguments:

hIGear
HIGEAR handle to the image
hwndPage
Windows handle to the GUI page sorter window
lpfnPageOrderProc
A far pointer to the callback function that you would like to register
lpPrivate
A far pointer to any private data that you would like to pass to the callback function.

Description:

This function registers a callback of type LPFNIG_GUIPAGEDELETEPROC in which you can write a procedure that will receive notification if the image icons in the GUI page sorter window are moved around by the user. The user can mover them around by holding down the Shift key and dragging with the left mouse button.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

See the example code under LPFNIG_GUIPAGEORDERPROC.

Sample: PAGE, GUISCAN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_remove

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_remove(
    HWND hwndPage,
    UINT nPage
);

Arguments

hwndPage
HIGEAR Windows handle to the GUI Page Sorter window
nPage
Set to an UINT indicating the number of the page (thumbnail) in the GUI Page Sorter that you would like to delete.

Description:

This function removes (deletes) the image referred to by nPage from the GUI Page Sorter. The image file will be closed, and the pages will be re-numbered if necessary. For example, if you delete nPage = 2 from a GUI Page Sorter that contains 3 images, the image formerly referred to as Page 3 will be made Page 2. (All images will retain their original HIGEAR handles).

NOTE: This function does not clear the image's handle from memory. You should call IG_image_delete() when the image is no longer needed.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;  /* HIGEAR handle of image  */
HWND hwndPage; /* Windows handle to the Page Sorter window */
UINT nPage;   /* Page number of image to remove */
AT_ERRCOUNT nErrcount; /* Tally of ImageGear errors on the stack
*/
nErrcount = IG_GUI_page_remove(hwndPage, nPage);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_select_CB_register

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_select_CB_register(
    HWND hwndPage,
    LPFNIG_GUIPAGESELECTPROC lpfnPageSelectProc,
    LPVOID lpPrivate
);

Arguments:

hwndPage
Windows handle to the GUI page sorter window
lpfnPageSelectProc
A far pointer to the callback function that you would like to register
lpPrivate
A far pointer to any private data that you wish to pass to the callback

Description:

This function registers a callback of type LPFNIG_GUIPAGESELECTPROC in which you can write a procedure to react to the user's mouse selection of a page icon on the GUI page sorter window.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

Please see the example code under LPFNIG_GUIPAGESELECTPROC .

Sample: PAGE, GUISCAN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_thumbnail_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_thumbnail_get(
    HWND hwndPage,
    UINT nPage,
    BITMAP FAR *lpBitmap,
    HPALETTE FAR *lpPalette
);

Arguments:

hwndPage
Windows handle to the GUI page sorter window
nPage
Set to the number of the page (thumbnail) in the GUI Page Sorter window for which you would like to receive the bitmap and palette.
lpBitmap
Returns the bitmap of the currently selected thumbnail.
lpPalette
Returns the palette of the currently selected thumbnail. If there is no palette, this returns a NULL.

Description:

This function returns the bitmap representation of a page in the page browser window and also the palette, if it has one. The purpose of this function is to allow you to manipulate the screen representation of the page. For example, if a page contains annotations, you could indicate this by making the page's screen bitmap have a red tint.

The bitmap and palette returned should never be deleted using the Window's DeleteObject() function. When the page is deleted via the Page Sorter Window, the bitmap will be automatically destroyed for you. To destroy and regenerate all screen bitmaps (pages) call IG_GUI_page_document_update (); to destroy and regenerate a single screen bitmap, call IG_GUI_page_document_refresh ().

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: See also other IG_GUI_page_...() functions.

Example:

/* This example demonstrates retrieving the screen bitmap of
page 1 and drawing a rectangle around it */
AT_ERRCOUNT  nErrcount;
HIGEAR hIGear;
HBITMAP hBitmap, hPriorBitmap;
HPALETTE	 	hPalette, hPriorPalette;
HWND hwndPage;
HDC hmemDC;
INT nWidth, nHeight;
IG_GUI_page_thumbnail_get(hwndPage, 1, &hBitmap, &hPalette);
IG_GUI_page_thumbnail_size_get(hwndPage, &nWidth, &nHeight);
hmemDC = CreateCompatibleDC(NULL);
hPriorBitmap = SelectBitmap(hmemDC, hBitmap);
hPriorPalette = SelectPalette(hmemDC, hPalette, FALSE);
RealizePalette(hmemDC);
Rectangle(hmemDC, 0, 0, nWidth, nHeight);
SelectPalette(hmemDC, hPriorPalette, FALSE);
SelectBitmap(hmemDC, hPriorBitmap);
DeleteDC(hmemDC);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_thumbnail_size_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_thumbnail_size_get(
    HWND hwndPage,
    LPINT lpThumbWidth,
    LPINT lpThumbHeight
);

Arguments:

hwndPage
Windows handle to the GUI Page Sorter window
lpThumbWidth
Returns the width setting for the thumbnails in the GUI Page Sorter window
lpThumbHeight
Returns the height setting for the thumbnails in the GUI Page Sorter window

Description:

This function returns the current width and height settings for the thumbnail images in the GUI Page Sorter window. To set the dimensions of the thumbnails, use IG_GUI_page_thumbnail_size_set ().

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;  /* HIGEAR handle of image   */
AT_ERRCOUNT nErrcount; /* tally of ImageGear errors on the stack
*/
INT nHeight, nWidth; /* Height and width of thumbnails in Sorter
*/
HWND hwndPage;       /* Windows handle for Page Sorter    */
nErrcount = IG_GUI_page_thumbnail_size_get(hwndPage, &nWidth,
&nHeight);
if (nHeight > 60){
    nErrcount =
IG_GUI_page_thumbnail_size_set(hwndPage,nWidth*nHeight/60, 60);
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_thumbnail_size_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_thumbnail_size_set(
    HWND hwndPage,
    INT nThumbWidth,
    INT nThumbHeight
);

Arguments:

IGear
HIGEAR handle to the image
nThumbWidth
Sets the width of the thumbnails in the GUI Page Sorter window. Set to an INT value.
nThumbHeight
Sets the height of the thumbnails in the GUI Page Sorter window. Set to an INT value.

Description:

This function sets the height and width for the thumbnail images displayed in the GUI Page Sorter window. Such a window can be created using IG_GUI_page_window_create ().

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

Please see the example code for IG_GUI_page_thumbnail_size_get ()function.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_update

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_update(HWND hwndPage);

Arguments:

hwndPage
Windows handle to the GUI page sorter

Description:

This function updates the display of the GUI page sorter window. Call this function if the page sorter window is a "child" of another window, and the "parent" window has been resized.

NOTE: See also IG_GUI_page_window_create() and IG_GUI_page_document_update()functions.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_GUI_page_window_create

Group: Graphical User Interface
NOTE: Please use the new upgraded function IG_GUI_page_window_create_ex().

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_window_create (
    HWND hwndParent,
    DWORD dwGrpID,
    const LPSTR lpcszTitle,
    INT x,
    INT y,
    INT nPageWidth,
    INT nPageHeight,
    HWND FAR *lphwndPage
);

Arguments:

hWndParent
Windows handle to the parent window
dwGrpID
Identifier of the display group that should be used for drawing thumbnail in the GUI page.
lpcszTitle
A long pointer to a string that sets the title for the window.
x
A variable of type INT that sets the x position of the window
y
A variable of type INT that sets the y position of the window
nPageWidth
A variable of type INT that sets the width of the window
nPageHeight
A variable of type INT that sets the height of the window
lphwndPage
A long pointer that returns the window handle of the page sorter

Description:

This function creates a page sorter window. The purpose of the page sorter window is for creating a new multi-page file or to edit an existing one. When you're done editing pages, you have the option to save out a single image file with multiple pages.

NOTE: For a screen capture of a GUI page sorter, see IG_GUI_page_window_create().

This function takes as parameters settings for the size and position of the page sorter, and returns the handle of the new page sorter window. If there is no parent window, set hWndParent to NULL. The page sorter window will show small versions (thumbnails) of any file that is added to the page sorter window by the function IG_GUI_page_file_append ().

To move pages around (which effectively changes the numbering of the pages) hold down the Shift key while dragging with the left mouse button.

NOTE: The functionality of this API call has been upgraded and supported by the new function IG_GUI_page_window_create_ex(). The reason that this new function has been created is that the old function does not allow you to set the Windows Style bits. In the interest of backward compatibility, we have left the old function in its original form and have retained support for it. If you have already used the old function in your code, it is not mandatory that you modify your code, but it is recommended.

To delete a page, select it with the mouse, and press the Delete key.

To modify the size of the page "thumbnails" or to read their current size, use IG_GUI_page_thumbnail_size_set () and IG_GUI_page_thumbnail_size_get ()functions respectively.

To save the pages into one multi-page file, set up a loop that will "page" through each HIGEAR image and append it to a multi-page file with a call to IG_save_file (). This is demonstrated in the example code below.

NOTE: See also IG_GUI_page_update(), IG_GUI_page_document_update(), and IG_GUI_page_window_create_ex()functions.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear, hIGearSave; /* HIGEAR handles of images */
AT_ERRCOUNT  nErrcount;      /* Tally of ImageGear errors */
INT xpos, ypos,    /* Position of parent window  */
        nPageCount;     /* # of pages in page sorter */
HWND hwndPage;    /* Windows handle to a page  */
nErrCount = IG_GUI_page_window_create(hWnd, IG_GRP_DEFAULT,
"Page Window", xpos, ypos, 320, 200, &hwndPage);
 ...
/* save the pages in the sorter window to a multipage file */
IG_GUI_page_count_get(hwndPage, &nPageCount);
for (i = 1; i <= nPageCount; i++)
{
   IG_GUI_page_handle_get(hwndPage, i, &hIGearSave);
   nErrCount = IG_save_file(hIGearSave,
"NewPages.tif",IG_SAVE_FORMAT_TIF_RLE);
   if (nErrCount != 0)
   {
   /* report the error */
   ErrorReport(hWnd);
   break;
   }
}

Sample: PAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_page_window_create_ex

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_page_window_create_ex (
    HWND hwndParent,
    DWORD dwGrpID,
    DWORD dwStyle,
    const LPSTR lpcszTitle,
    INT x,
    INT y,
    INT nPageWidth,
    INT nPageHeight,
    HWND FAR *lphwndPage
);

Arguments:

hWndParent
Windows handle to the parent window
dwGrpID
Identifier of display group should be used for drawing thumbnail in the GUI page.
dwStyle
Set to any Windows style bits that you would like the Pan window to have. This parameter can be a combination of window styles ORed together.
lpcszTitle
A long pointer to a string that sets the title for the window.
x
A variable of type INT that sets the x position of the window.
y
A variable of type INT that sets the y position of the window.
nPageWidth
A variable of type INT that sets the width of the window.
nPageHeight
A variable of type INT that sets the height of the window.
lphwndPage
A long pointer that returns the window handle of the page sorter.

Description:

This function creates a page sorter window. The purpose of the page sorter window is to create a new multi-page file or to edit an existing one. When you're done editing the pages, you have the option to save out a single image file with multiple pages.

This function takes, as parameters, settings for the size and position of the page sorter, and returns you the handle of the new page sorter window. If there is no parent window, set hWndParent to NULL. The page sorter window will show small versions (thumbnails) of any file that is added to the page sorter window by the function IG_GUI_page_file_append (), or IG_GUI_page_insert ().

To move pages around (which effectively changes the numbering of the pages) hold down the Shift key while dragging with the left mouse button.

To delete a page, select it with the mouse and press the Delete key.

To modify the size of the page "thumbnails" or to read their current size, use IG_GUI_page_thumbnail_size_set () and IG_GUI_page_thumbnail_size_get () functions respectively.

To save the pages into one multi-page file, set up a loop that will "page" through each HIGEAR image and append it to a multi-page file with a call to IG_save_file (). This is demonstrated in the example code below.

NOTE: See also IG_GUI_page_update() and IG_GUI_page_document_update() functions.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear, hIGearSave /* HIGEAR handle of image */
AT_ERRCOUNT  nErrcount;  /* Tally of ImageGear errors */
INT xpos, ypos, /* Position of parent window */
INT nPageCount; /* # of pages in page sorter */
HWND hwndPage;   /* Windows handle to a page  */
nErrCount = IG_GUI_page_window_create_ex(hWnd, IG_GRP_DEFAULT,
WS_CHILD|WS_VISIBLE, "Page Window", xpos, ypos, 320, 200,
&hwndPage);
/* save the pages in the sorter window to a multipage file */
IG_GUI_page_count_get(hwndPage, &nPageCount);
for (i = 1; i <= nPageCount; i++)
{
   IG_GUI_page_handle_get(hwndPage, i, &hIGearSave);
   nErrCount = IG_save_file(hIGearSave, "NewPages.tif",
    IG_SAVE_FORMAT_TIF_RLE);
   if (nErrCount != 0)
   {
   /* report the error */
   ErrorReport(hWnd);
   break;
   }
}

The Page Sorter Window as it is implemented in the sample application: Page.c. The parent window displays the currently selected image - 3.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_palette_CB_register

Group: raphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_palette_CB_register (
    HWND hWndPalette,
    LPFNIG_GUIPALETTE lpfnPalette,
    LPVOID lpPrivate
);

Arguments:

hWndPalette
Handle of Palette window
lpfnPalette
Far pointer to Palette callback function, called when palette changes
lpPrivate
Far pointer to private data area (passed to callback function)

Description:

This function registers a callback function to be called whenever the user has changed a palette entry in the palette window.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

LPFNIG_GUIPALETTE 	MyPaletteCBFunc;  /* Declare type of callback
func */
HWND 	hWndPalette;     /* Global Palette window handle   */
{
static char cPrivate[200];    /* Private data area   */
 ...
IG_GUI_palette_CB_register(hWndPalette, MyPaletteCBFunc,
(LPVOID) &cPrivate);
/* See also the example under LPFNIG_GUIPALETTE */
 ...
}

Sample: PALEDT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_palette_update

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_palette_update (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndPalette
);

Arguments:

hIGear
HIGEAR handle of image
dwGrpID
Identifier of group where to get display options for creating palette.
hWndPalette
Handle of palette window

Description:

This function may be called to update (repaint) the palette window, if for example the image's DIB palette has been changed in memory by your application.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;   /* HIGEAR handle of image  */
HWND hWndPalette;  /* Handle of Palette window */
IG_GUI_palette_update ( hIGear, hWndPalette );

Sample: PALEDT, DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_palette_window_create

Group: raphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_palette_window_create (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndParent,
    const LPSTR lpcszTitle,
    INT nX,
    INT nY,
    INT nWidth,
    INT nHeight,
    HWND FAR lphWndPalette
);

Arguments:

hIGear
HIGEAR handle of image
dwGrpID
Identifier of group where to get display options for creating palette.
hWndParent
Handle of Parent window
lpszTitle
Title of Palette window
nX
X position of upper left corner of window
nY
Y position of upper left corner of window
nWidth
Width of window
nHeight
Height of window
lphWndPalette
Far pointer to HWND object to hold Palette window handle

Description:

This function creates a GUI palette window. ImageGear automatically displays the image's palette in the palette window, and the user may edit the palette. Also call function IG_GUI_palette_CB_register () if you want to be informed any time the user is actually trying to modify the palette.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;  /* Global HIGEAR handle of image in parent
window  */
HWND hWndParent; /* Global Windows window handle of that window
*/
HWND hWndPalette;/* Global HIGEAR handle of Palette window
*/
AT_ERRCOUNT nErrcount; /* Returned count of errors         */
 ...
/* Create a Palette window for image hIGear's palette:
*/
nErrcount = IG_GUI_palette_window_create ( hIGear,
IG_GRP_DEFAULT, hWndParent, "I.G. Pal Window", 50, 50, 200, 200,
&hWndPalette );

Sample: PALEDT, DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_pan_attribute_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pan_attribute_get(
    HWND hwndPan,
    AT_MODE nAttributeID,
    LPVOID lpData
);

Arguments:

hWndPan
Handle to the Pan Window created by the IG_GUI_pan_window_create (). If no pan window is being used, then specify NULL for this parameter.
nAttributeID
One of the GUI Pan control options defined in accucnst.h.
LpData
The value currently assigned to the attribute will be returned here. The value depends on the nAttributeID value:
IG_GUI_PAN_MODIFY_DEVICE_RECT - TRUE boolean value specifies that modification of image device rectangle with IG_GUI_pan_track_mouse () call is allowed. This is global control parameter and does not require windows handle of Pan window.

Description:

This function is used to get the various attributes of the Pan window.

NOTE: See the function IG_GUI_pan_window_create().

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

Pan


IG_GUI_pan_attribute_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pan_attribute_set(
    HWND hwndPan,
    AT_MODE nAttributeID,
    const LPVOID lpData
);

Arguments:

hWndPan
Handle to the Pan Window created by the IG_GUI_pan_window_create (). If no pan window is being used, then specify NULL for this parameter.
nAttributeID
One of the GUI Pan control options defined in accucnst.h.
LpData
The value currently assigned to the attribute will be returned here. The value depends on the nAttributeID value:
IG_GUI_PAN_MODIFY_DEVICE_RECT - Boolean value enabling or disabling device rectangle modification.

Description:

This function is used to set the various attributes of the Pan window.

NOTE: See the function IG_GUI_pan_window_create().

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

Pan


IG_GUI_pan_CB_register

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pan_CB_register (
    HWND hWndPan,
    LPFNIG_GUIPANUPDATE lpfnPanUpdate,
    LPVOID lpPrivate
);

Arguments:

hWndPan
A windows handle to the Pan window.
lpfnPanUpdate
A pointer to the callback function called whenever a pan window is updated.
lpPrivateData
A far pointer to any private data that you want to pass to the callback.

Description:

Call this function to register a callback function that is to be called after a Pan window is updated.

NOTE: See also the description for the callback type LPFNIG_GUIPANUPDATE.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See the example for the LPFNIG_GUIPANUPDATE callback function.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_pan_GrpID_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pan_GrpID_get(
    HWND hwndPan,
    DWORD* pdwGrpID
);

Arguments:

HwndPan
Handle to the Pan Window.
PdwGrpID
Pointer to where the Pan window group ID is to be received.

Description:

This function returns the group ID of the specified pan window. This value can then be used for pan window display attribute corrections.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

/* Updating Pan window with new gamma correction: */
      DWORD dwGrpID;
     IG_GUI_pan_GrpID_get(hwndPan, &dwGrpID);
IG_dspl_gamma_correction_set(hIGear, dwGrpID,
IG_DSPL_ALL_CHANNELS, 1.0, 1.0, 1.0);
InvalidateRect(hwndPan, NULL, FALSE);
UpdateWindow(m_hwndPan);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_pan_track_mouse

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pan_track_mouse (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndPan,
    INT nX,
    INT nY
);

Arguments:

hIGear
HIGEAR handle of image
dwGrpID
Identifier of group which is used for drawing image in the parent window.
hWndPan
Handle of GUI Image or Pan window
nX
X position of left mouse button click
nY
Y position of left mouse button click

Description:

This function can be called while processing the Windows left-mouse-button-down message WM_LBUTTONDOWN. If the pan window's parent window is a GUI image window (see functions IG_GUI_window_create (), and IG_GUI_window_associate ()), then calling IG_GUI_pan_track_mouse() will show, in the parent window, the portion of the image indicated by the mouse location in the pan window. This can be used to let the user slide (pan) the image around in the parent window, by moving the mouse in the pan window.

NOTE: See also IG_GUI_pan_window_create()function.

You can obtain (nX, nY), the coordinates of the left mouse button click, from the parameters passed by Windows with the WM_... message.

NOTE: You cannot use IG_GUI_..._track_mouse() with a WM_RBUTTONDOWN message. ImageGear only responds to left mouse button clicks.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear;     /* HIGEAR handle of image in parent window */
HWND	 hWndParent;  /* Windows window handle of that window */
HWND	 hWndImage;  /* Windows handle of Image window    */
AT_ERRCOUNT nErrcount;   /* Returned count of errors   */
 ...
/* Create a Pan window for the image in window hWndParent: */
nErrcount = IG_GUI_pan_window_create_ex ( hIGear,
IG_GRP_DEFAULT, hWndParent, hWndImage, WS_CHILD|WS_VISIBLE,
"I.G. Pan Window", 50, 50, 200, 200, &hWndPan );
/* Message-Handling routine: */
LPARAM CALLBACK  MsgHandler (HWND hWnd, UINT msg, WPARAM wParam,
LPARAM lParam );
{
 ...
switch (msg)
    {
    case WM_LBUTTONDOWN:
    /* if occurred in the Pan window: */
    IG_GUI_pan_track_mouse ( hIGear, IG_GRP_DEFAULT, hWndPan,
LOWORD(lParam),HIWORD(lParam) );
/* The above will display in the Pan window, the location where
the mouse is being clicked in the parent image window. */
     ...
    }
 ...
}
/* See also sample application, PAN */

Sample: PAN, DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_pan_update

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pan_update (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndPan,
    BOOL bFullRepaint
);

Arguments:

hIGear
HIGEAR handle of image
dwGrpID
Identifier of group which is used for drawing image in the parent window.
hWndPan
Handle of Pan window
bFullRepaint
TRUE = redraw image

Description:

This function may be called to update (repaint) the pan window, such as if the image has changed in memory.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;  /* HIGEAR handle of image */
HWND hWndPalette; /* Handle of Pan window */
IG_GUI_pan_update ( hIGear, IG_GRP_DEFAULT, hWndPan, TRUE );

Sample: PAN, DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_pan_window_create

Group: Graphical User Interface
NOTE: Please use new upgraded function IG_GUI_pan_window_create_ex(). See the NOTE below.

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pan_window_create (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndParent,
    const LPSTR lpszTitle,
    INT nX,
    INT nY,
    INT nWidth,
    INT nHeight,
    HWND FAR * lphWndPan
);

Arguments:

hIGear
HIGEAR handle of image
dwGrpID
Identifier of group which is used for drawing image in the hWndParent window. New group will be allocated internally for drawing image in the pan window.
hWndParent
Handle of Parent window. This function assumes that the Parent window is the image window. If you would like to supply a separate handle for an image window, please use IG_GUI_pan_window_create_ex ().
lpszTitle
Title of Pan Window
nX
X position of upper left corner of window
nY
Y position of upper left corner of window
nWidth
Width of window
nHeight
Height of window
lphWndPan
Far pointer to HWND object to hold Pan window handle

Description:

This function is called to create a GUI pan window. When the user moves the mouse around in the pan window, your application can pan the specified portion of the image, in the parent image window. See IG_GUI_pan_track_mouse ().

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See the example for function IG_GUI_pan_track_mouse ().

NOTE: The functionality of this API call has been upgraded and supported by the new function IG_GUI_pan_window_create_ex(). The reason that this new function has been created is that the old function does not allow you to set the Windows style of the pan window, or to specify the handle of the image window. In the interest of backward compatibility, we have left the old function in its original form and have retained support for it. If you have already used the old function in your code, it is not mandatory for you to modify your code, but it is recommended.

Sample: PAN, DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_pan_window_create_ex

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pan_window_create_ex (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndParent,
    HWND hwndImage,
    DWORD dwStyle,
    const LPSTR lpszTitle,
    INT nX,
    INT nY,
    INT nWidth,
    INT nHeight,
    HWND FAR * lphWndPan
);

Arguments:

hIGear
HIGEAR handle of image
dwGrpID
Identifier of group which is used for drawing image in the hWndParent window. New group will be allocated internally for drawing image in the pan window.
hWndParent
Handle of Parent window
hWndImage
Handle to the image window
dwStyle
Set to any Windows style bits that you would like the Pan window to have. This parameter can be a combination of window styles ORed together.
lpszTitle
Title of Pan Window
nX
X position of upper left corner of window
nY
Y position of upper left corner of window
nWidth
Width of window
nHeight
Height of window
lphWndPan
Far pointer to HWND object to hold Pan window handle

Description:

This function is called to create a GUI pan window. When the user moves the mouse around in the pan window, your application can pan the specified portion of the image, in the parent image window. See IG_GUI_pan_track_mouse ().

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See the example for function IG_GUI_pan_track_mouse ().

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_pixdump_attribute_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pixdump_attribute_get(
    HWND hWnd,
    AT_MODE nAttributeID,
    LPVOID lpData
);

Arguments:

hWnd
Handle of window in which image is displayed
nAttributeID
A variable of type AT_MODE, such as IG_GUI_WINDOW_PAINT
lpData
A VOID pointer a variable of the type required by the nAttributeID parameter. This sets the value for the attribute defined by nAttributeID

Description:

This function gets the current attribute settings of the GUI window. As of this writing, there are only two attributes, but this may be expanded in the future.

Values:

  • IG_GUI_PIXDUMP_FONT - Retrieves font used for text output.
  • IG_GUI_PIXDUMP_MODE - Retrieves the display style.
NOTE: See IG_GUI_pixdump_attribute_set() for a full description of available styles.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_pixdump_attribute_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pixdump_attribute_set(
    HWND hWnd,
    AT_MODE nAttributeID,
    LPVOID lpData
);

Arguments:

hWnd
Handle of window in which image is displayed
nAttributeID
A variable of type AT_MODE, such as IG_GUI_WINDOW_PAINT
lpData
A VOID pointer to a variable of the type required by the nAttributeID parameter. This sets the value for the attribute defined by nAttributeID.

Description:

This function sets the attribute settings of the GUI Pixel Dump window. Here are the settings available for nAttributeID and what they mean:

Values:

  • IG_GUI_PIXDUMP_FONT Set font to use for text output
  • IG_GUI_PIXDUMP_MODE Set output mode
  • IG_GUI_DATA_COLOR_COMPONENT Set information about color components to
    display

lpData specifies the value of attribute to set. This is not address but value itself (32 bit). If nAttributeID is set to IG_GUI_PIXDUMP_FONT then lpData should contain handle HFONT of the font. For old font DeleteObject will be called.

If nAttributeID is set to IG_GUI_PIXDUMP_MODE then lpData should contain one of following values:

  • IG_GUI_COLOR_COMPONENT_R - shows value of Red component
  • IG_GUI_COLOR_COMPONENT_G - shows value of Green component
  • IG_GUI_COLOR_COMPONENT_B - shows value of Blue component
  • IG_GUI_COLOR_COMPONENT_I - shows value of Intensity
  • IG_GUI_COLOR_COMPONENT_RGB - shows all 3 (RGB) components

The default value for IG_GUI_DATA_COLOR_COMPONENT is: IG_GUI_PIXDUMP_COMPONENT_RGB.

If nAttributeID is IG_GUI_PIXDUMP_MODE then lpData should contain a combination of the following flags:

  • IG_GUI_PIXDUMP_DIGITS_HEX Display hexadecimal numbers
  • IG_GUI_PIXDUMP_DATA_COLOR If the image contains a palette, then this flag specifies whether to display entries of the actual RGB vaues or to display the index.

The default value for IG_GUI_PIXDUMP_MODE is: NULL

NOTE: For 16-bit grayscale images, the intensity value will be displayed with any of the IG_GUI_DATA_COLOR_COMPONENT values.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_pixdump_track_mouse

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pixdump_track_mouse(
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndPixDump,
    INT nX,
    INT nY
);

Arguments:

hIGear
HIGEAR handle of an image.
dwGrpID
Identifier of a group that is used for drawing an image in the parent window.
hWndPixDump
Handle of a GUI pixdump window.
nX
X position of the left mouse button click.
nY
Y position of the left mouse button click.

Description:

This function can be called while processing the Windows mouse-button-down message WM_LBUTTONDOWN for a pixdump window's parent window. See also the IG_GUI_pixdump_window_create () function.

You can obtain the nX, nY coordinates of the mouse click from the parameters passed by Windows with the WM_... message. See the sample application GUI for a demonstration of how to use this and related (IG_GUI_COLOR_PIXDUMP_....()).

NOTE: You cannot use IG_GUI_..._track_mouse() with a WM_RBUTTONDOWN message. ImageGear only responds to left mouse button clicks.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: GUIWIN, DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_pixdump_window_create

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pixdump_window_create(
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndParent,
    HWND hWndImage,
    DWORD dwStyle,
    const LPSTR lpszTitle,
    INT nX,
    INT nY,
    INT nWidth,
    INT nHeight,
    HWND FAR* lphwndPixDump
);

Arguments:

hIGear
HIGEAR handle of an image.
dwGrpID
Identifier of the group that is used for drawing an image in the hWndParent window.
hWndParent
Handle of the Parent window.
dwStyle
Window style in bits.
lpszTitle
Title of the pixdump Window.
nX
X position of the upper left corner of the pixdump window.
nY
Y position of the upper left corner of the pixdump window.
nWidth
Width of the pixdump window.
nHeight
Height of the pixdump window.
lphwndPixDump
Far pointer to the HWND object to hold the pixdump window handle.

Description:

This function creates a GUI Pixel Dump window. This window is designed to display the image data in numeric form from the area selected by the mouse. To select an area in the image, hold the left button down and drag. A small rectangle is painted on the image and the GUI window displays data from this area in the image. The data is displayed as decimal or hexadecimal numbers.

This function creates a GUI window using the style WS_OVERLAPPEDWINDOW. For attribute settings, see IG_GUI_pixdump_attribute_set ().

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: GUIWIN, DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_pixdump_update

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_pixdump_update (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWNDPixDump
);

Arguments:

hIGear
HIGEAR handle of an image
dwGrpID
Identifier of a group that is used for drawing image in the parent window.
hWNDProfile
Handle of a GUI pixdump window

Description:

Call this function when loading a new image into the Pixel Dump window. It updates the client area of the Color Profile GUI window specified by hwndPixDump. If the image handle associated with the GUI window is not the same as the image to which hIGear parameter points, this function updates hWNDPixDump to point to the new HIGEAR image.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: GUIWIN, DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_select_attribute_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT  ACCUAPI IG_GUI_select_attribute_set(
    HWND hwndSelect,
    AT_MODE nAttributeID,
    const LPVOID lpData
);

Arguments:

hwndSelect
Handle to select a window.
NAttributeID
ID of the attribute to set. The only possible value is IG_GUI_SELECT_ASPECT
lpData
Data value to be set. Possible values are TRUE or FALSE.

Description:

This function is used to define the behavior of a rubber rectangle during selection. If lpData = FALSE, then the rectangle corresponds exactly to the mouse pointer. Otherwise, the current aspect is taken into account.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

IG_GUI_select_track_mouse(hIGear, dwGroupID, hWnd, x, y,
MySelectRect, NULL);
IG_GUI_select_attribute_set(hWnd, IG_GUI_SELECT_ASPECT,
(LPVOID)(FALSE));

Sample: Recognition

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_select_track_mouse

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_select_track_mouse (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndImage,
    INT nX,
    INT nY,
    LPFNIG_GUISELECT lpfnSelect,
    LPVOID lpPrivate
);

Arguments:

hIGear
HIGEAR handle of image
dwGrpID
Display group identifier, used for drawing image in the image window.
hWndImage
Handle of the Image window
nX
The X position of the left mouse button click
nY
The Y position of the left mouse button click
lpfnSelect
Far pointer to the GUI Select callback function. This is called when a rectangle is created.
lpPrivate
Far pointer to private data (passed to the callback function).

Description:

This function is called when you want to use the mouse to delineate a rectangle within an image window.

Call this function in response to the windows message WM_LBUTTONDOWN. The mouse position is followed while the left mouse button is down. When the left mouse button is released, your lpfnSelect callback function is called with the coordinates of the rectangle that was described. The callback function may use the rectangle data in any way.

NOTE: If aspect ratio preservation is in effect for the image (that is, if the aspect ratio setting is anything other than IG_DSPL_NOT_FIXED), then the dragged rectangle will automatically be aspect ratio corrected.

You can obtain the starting mouse coordinates (nX, nY) from the parameters passed by Windows with the WM_... message.

NOTE: You cannot use IG_GUI_..._track_mouse()functions with a WM_RBUTTONDOWN message. ImageGear responds only to left mouse button clicks.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

PFNIG_GUISELECT	 MyGUISelectCB;/* Called when rect delineated  */
HIGEAR 	hIGear;/* HIGEAR handle of image     */
struct  tagMyPriv  {
   BOOL     bRectWasSelected; /* TRUE=User delineated a rect  */
   AT_RECT  rcUserRect:      /* This is the rectangle      */
   }	     PrivateStruct;  /* Name of private data area    */
/* Window-message handling routine:    */
LPARAM CALLBACK  MsgHandler
    ( HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam )
{
 ...
switch ( msg )
  {
  CASE WM__LBUTTONDOWN:
     ...
    IG_GUI_select_track_mouse ( hIGear, IG_GRP_DEFAULT, hWnd,
    LOWORD(lParam), HIWORD(lParam), MyGUISelectCB,
    (LPVOID) &PrivateStruct );
     ...
  }
 ...
}
VOID ACCUAPI  MyGUISelectCB ( LPVOID lpPrivate,
    LPAT_RECT lprcRectSelected )
/* This function will record the rectangle selected, in
PrivateStruct, pointed to by lpPrivate. */
{
struct tagMyPriv *   structPtr; /* Will point to PrivateStruct
*/
structPtr =  lpPrivate;      /* Copy the pointer */
structPtr -> bRectWasSelected  =  TRUE; /* Indicate a rect here
*/
structPtr -> rcUserRect        =  *lprcRectSelected;  /* Copy
rect */
return;      /* Done */
}

Sample: DISPLAY, CLPBRD, Recognition

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_spotcolormismatch_warning

Group: GUI

Declaration:

VOID ACCUAPI IG_gui_spotcolormismatch_warning(
    HWND hWnd,
    HIGEAR hIGear
);

Parameters:

hWnd
Handle of the parent window.
hIGear
Handle to the image to check whether it has spot colors.

Description:

This function performs checks to determine whether to show a spot color mismatch warning dialog. The dialog will be displayed in case if image contains spot colors not defined in the available color books. The dialog can be used to add new color books.


IG_GUI_thumbnail_attribute_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_attribute_get (
    HWND hwndThumbnail,
    AT_MODE nAttributeID,
    LPVOID lpData
);

Arguments:

hwndThumbnail
Windows handle to the Thumbnail Window
nAttributeID
An integer variable of type AT_MODE that indicates attrtibute for which to get the current setting. These constants have the prefix IG_GUI_THUMBNAIL_ and are defined in accucnst.h.
lpData
The current setting of the thumbnail attribute referred to by nAttributeID.

Description:

This function returns the current setting for the GUI Thumbnail attribute indicated by nAttributeID.

NOTE: See IG_GUI_thumbnail_attribute_set() for a complete description of the attributes that can be changed.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

UINT nThumbWidth;
HWND hWndThumb;
/*Get the current setting for thumbnail width */
IG_GUI_thumbnail_attribute_get(hWndThumb,
IG_GUI_THUMBNAIL_WIDTH, (LPVOID)&nThumbWidth);

Sample: THUMB, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_attribute_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_attribute_set (
    HWND hwndThumbnail,
    AT_MODE nAttributeID,
    const LPVOID lpData
);

Arguments:

hwndThumbnail
Windows handle to the Thumbnail Window
nAttributeID
An integer variable of type AT_MODE that tells which attrtibute to get the current setting for. These constants all have the prefix IG_GUI_THUMBNAIL_ and are defined in accucnst.h.
lpData
The new setting for the thumbnail attribute referred to by nAttributeID.

Description:

This function allows you to change various settings for the GUI Thumbnail Browser. Set nAttributeID to the appropriate defined IG_GUI_THUMBNAIL_ constant and lpData to the appropriate value. The table below lists the GUI Thumbnail Settings and indicates what the various attributes refer to.

If the type of lpData is less than 32 bits, the value is passed. If the type is greater than 32 bits, the address is passed.

IMAGE CONTROL CONSTANTS
TYPE
VALUES RANGE
IG_GUI_THUMBNAIL_WIDTH
INT
Width of thumbnail
IG_GUI_THUMBNAIL_HEIGHT
INT
Height of thumnail
IG_GUI_THUMBNAIL_SHOW_TITLE
BOOL
TRUE - title will be shown
FALSE - title will not be shown
IG_GUI_THUMBNAIL_X_SPACING
INT
X offset of upper left corner of thumbnail
IG_GUI_THUMBNAIL_Y_SPACING
INT
Y offset of upper left corner of thumbnail from the edge or the previous thumbnail
IG_GUI_THUMBNAIL_SHOW_FLAT
BOOL
TRUE - no 3-D display
FALSE - 3-D display
IG_GUI_THUMBNAIL_BORDER_WIDTH
INT
Width of the border surrounding the thumbnail in pixels
IG_GUI_THUMBNAIL_SHADOW_WIDTH
INT
Width of the shadow surrounding the thumbnail in pixels
IG_GUI_THUMBNAIL_ZOOM_FACTOR
INT
Zoom factor is applied to the thumbnail when shift and the left mouse button are selected
IG_GUI_THUMBNAIL_INTERIOR
INT
Thumbnail interior border spacing in pixels
IG_GUI_THUMBNAIL_MAGNIFY_FLAG
BOOL
TRUE - if thumbnail is selected image will magnify
FALSE - no magnification occurs
IG_GUI_THUMBNAIL_TITLE_HEIGHT
INT
Height of the thumbnail title
IG_GUI_THUMBNAIL_USE_EMBEDDED
BOOL
TRUE - all embedded thumbnails will be used to display thumbnail
FALSE - create a thumbnail from the image
IG_GUI_THUMBNAIL_ACTIVE_ID
INT
An index of the currently selected icon in the thumbnail window
IG_GUI_THUMBNAIL_ MULTISELECT
BOOL
TRUE allows you to select multiple thumbnails
IG_GUI_THUMBNAIL_HIGHLIGHT_
COLOR
AT_RGBQUAD
The color for highlighted icons that have the same filename
IG_GUI_THUMBNAIL_ALL_PAGES
BOOL
TRUE - if image is a multipage a thumbnail will be for each page.
FALSE - only first page will be displayed as a thumbnail
Table - GUI Thumbnail Settings

In this diagram, IG_GUI_THUMBNAIL_SHOW_FLAT is set to FALSE.

If you set IG_GUI_THUMBNAIL_ZOOM_FACTOR to > 1, the image is zoomed when you press the shift key and click over the thumbnail. Here is an example:

The center thumbnail has been mouse-clicked and zoomed.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

UINT	 nThumbWidth = 64;      /* thumbnail width */
UINT 	nThumbHeight = 64;     /* thumbnail height  */
/*Set the width and height for the thumbnails in the browse  */
IG_GUI_thumbnail_attribute_set(hwndThumb,
IG_GUI_THUMBNAIL_WIDTH,(LPVOID)(DWORD)nThumbWidth);
IG_GUI_thumbnail_attribute_set(hwndThumb,
IG_GUI_THUMBNAIL_HEIGHT, (LPVOID)(DWORD)nThumbHeight);
NOTE: The thumbnail sample contains a comprehensive dialog box for changing GUI Thumbnail browser display attributes.

Sample: THUMB, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_CB_register

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_CB_register (
    HWND hWndThumbnail,
    LPFNIG_GUITHUMBSELECT lpfnThumbSelect,
    LPVOID lpPrivate
);

Arguments:

hWndThumbnail
Windows handle to the Thumbnail window
lpfnThumbSelect
A pointer to the callback function that you are registering, to be called whenever a thumbnail is selected.
lpPrivateData
A far pointer to any private data to which you want to pass to the callback

Description:

Call this function to register a callback function that is to be called whenever a thumbnail is selected in thumbnail window hWndThumbnail. See also the description for callback type LPFNIG_GUITHUMBSELECT.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

For an example showing the use of this and other IG_GUI_Thumbnail functions and callbacks, see sample application THUMB.

Sample: THUMB, DISPLAY, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_create_CB_register

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_create_CB_register (
    HWND hWndThumbnail,
    LPFNIG_GUITHUMBCREATE lpfnThumbCreate,
    LPVOID lpPrivate
);

Arguments:

hWndThumbnail
Windows handle to the Thumbnail window
lpfnThumbCreate
A pointer to the callback function that you are registering, to be called whenever a thumbnail is created
lpPrivateData
A far pointer to any private data to which you want to pass the callback

Description:

Call this function to register a callback function that is to be called whenever a thumbnail is created in the thumbnail window hWndThumbnail. See also the description for callback type LPFNIG_GUITHUMBCREATE.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_delete_CB_register

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_delete_CB_register (
    HWND hWndThumbnail,
    LPFNIG_GUITHUMBDELETE lpfnThumbDelete,
    LPVOID lpPrivate
);

Arguments:

hWndThumbnail
Windows handle to the Thumbnail window
lpfnThumbDelete
A pointer to the callback function that you are registering to be called whenever a thumbnail is deleted
lpPrivateData
A far pointer to any private data to which you want to pass to the callback

Description:

Call this function to register a callback function that is to be called whenever a thumbnail is deleted in the thumbnail window hWndThumbnail. See also the description for callback type LPFNIG_GUITHUMBCREATE.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_data_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_data_get (
    HWND hwndThumbnail,
    UINT nIndex,
    AT_MODE nAttributeID,
    LPVOID lpData
);

Arguments:

hwndThumbnail
Windows handle to the Thumbnail Window
nIndex
Index of an icon
nAttributeID
An integer variable of type AT_MODE that indicates the attrtibute from which to get the current setting. These constants all have the prefix IG_GUI_THUMBNAIL_ICON_ and are defined in accucnst.h.
lpData
The current setting of the icon attribute referred to by nAttributeID.

Description:

This function returns the current setting for the thumbnail icon data indicated by nAttributeID.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

BOOL bIsMultipage;
HWND hWndThumb;
UINT nIndex;
IG_GUI_thumbnail_data_get(hWndThumb, nIndex,
IG_GUI_THUMBNAIL_ICON_ISMULTIPAGE, (LPVOID)&bIsMultipage);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_data_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_data_set (
    HWND hwndThumbnail,
    UINT nIndex,
    AT_MODE nAttributeID,
    LPVOID lpData
);

Arguments:

hwndThumbnail
Windows handle to the Thumbnail Window
nIndex
Index of an icon
nAttributeID
Only the icon title (IG_GUI_THUMBNAIL_ICON_TITLE) can be changed
lpData
The current setting of the icon attribute referred to by nAttributeID.

Description:

This function changes the current setting for the thumbnail icon data indicated by nAttributeID.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

CHAR szTitle[128];
HWND hWndThumb;
UINT nIndex;
IG_GUI_thumbnail_data_set(hWndThumb, nIndex,
IG_GUI_THUMBNAIL_ICON_TITLE, (LPVOID)szTitle);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_dir_append

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_dir_append (
    HWND hWndThumbnail,
    const LPSTR lpszDirectory,
    const LPSTR lpszFilter
);

Arguments:

hWndThumbnail
Handle of Thumbnail window
lpszDirectory
Far pointer to zero-terminated string name of Thumbnail directory
lpszFilter
Far pointer to zero-terminated string name of Thumbnail file filter

Description:

This function adds thumbnails to the thumbnail window hWndThumbnail. ImageGear examines the directory indicated by the path string pointed to by lpszDirectory. Thumbnails will be created in the thumbnail window for all files matching the filter (or "wildcard") string pointed to by lpszFilter.

lpszFilter is a string in the format *.BMP;*.JPG, or *.* ( to match all files in the named directory).

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

For an example showing the use of this and other IG_GUI_Thumbnail functions and callbacks, see the THUMB sample application.

Sample: THUMB, DISPLAY, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_file_append

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_file_append (
    HWND hWndThumbnail,
    const LPSTR lpszFileName
);

Arguments:

hWndThumbnail
Handle of Thumbnail window
lpszFileName
Far pointer to string containing name of image file to append

Description:

Call this function to append the thumbnail window to a thumbnail of the named file.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_highlight_icons

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_highlight_icons (
    HWND hWndThumbnail,
    UINT nIndex
);

Arguments:

hWndThumbnail
Handle of Thumbnail window
nIndex
Index of an icon

Description:

This function changes the background color of a title for all icons having the same file name as nIndex icon. You can change the highlighting color using the IG_GUI_THUMBNAIL_HIGHLIGHT_COLOR attribute. The Highlight function is not the same as the select function. Selecting icons using the keyboard or mouse can belong to different filenames.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_hit_test

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_hit_test (
    HWND hwndThumbnail,
    INT x,
    INT y,
    LPINT lpIndex
);

Arguments:

hwndThumbnail
Windows handle to the Thumbnail Window
x, y
Pointer for the test
lpIndex
Index of an icon in the specified position; -1 if there is no icon

Description:

This function tests the existence of an icon in the specified position and returns its index.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HWND hWndThumb;
INT nIndex;
INT x,y;
IG_GUI_thumbnail_hit_test(hWndThumb, x, y, &nIndex);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_load_CB_register

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_load_CB_register(
    HWND hwndThumbnail,
    LPFNIG_GUITHUMBLOAD lpfnThumbLoad,
    LPVOID lpPrivateData
);

Arguments:

hwndThumbnail
Windows handle to the Thumbnail window.
lpfnThumbLoad
A pointer to the callback function that you are registering, to be called whenever a thumbnail is loaded.
lpPrivateData
A far pointer to any private data to which you want to pass the callback.

Description:

Call this function to register a callback function to be called whenever a thumbnail is loaded in the thumbnail window hwndThumbnail.

NOTE: See also the description for callback type LPFNIG_GUITHUMBLOAD.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See example under LPFNIG_GUITHUMBLOAD function.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_mouse_CB_register

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_mouse_CB_register (
    HWND hWndThumbnail,
    LPFNIG_GUITHUMBMOUSE lpfnThumbMouse,
    LPVOID lpPrivate
);

Arguments:

hWndThumbnail
Windows handle to the Thumbnail window
lpfnThumbMouse
A pointer to the callback function that you are registering to be called whenever a thumbnail is selected using a mouse click
lpPrivateData
A far pointer to any private data to which you want to pass the callback

Description:

Call this function to register a callback function that is to be called whenever a thumbnail is selected in thumbnail window hWndThumbnail. See the description for the callback type LPFNIG_GUITHUMBMOUSE for more information.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_memory_append

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_memory_append (
    HWND hWndThumbnail,
    LPVOID lpImage,
    AT_UINT nImageSize,
    DWORD dwPage
);

Arguments:

hWndThumbnail
Handle of Thumbnail window
lpImage
Address of an image in memory
nImageSize
Size of an image in memory
dwPage
Page number to load

Description:

This function appends a thumbnail of an image to the thumbnail window. If dwPage equals 0, then all pages are appended.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_remove

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_remove (
    HWND hWndThumbnail,
    UINT nIndex,
    UINT nCount
);

Arguments:

hWndThumbnail
Handle of Thumbnail window
nIndex
Starting index of an icon to remove
nCount
Number of icons to remove

Description:

This function removes icons from the thumbnail window.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

.


IG_GUI_thumbnail_sort

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_sort (
    HWND hWndThumbnail,
    LPFNIG_GUITHUMBCOMP lpfnThumbCompare,
    LPVOID lpPrivate
);

Arguments:

hWndThumbnail
Handle of Thumbnail window
lpfnThumbCompare
Far pointer to callback function to be called to compare thumbnails for a sort
lpPrivate
Far pointer to private data to be passed to the callback function

Description:

Call this function to register a callback function that is to be called to sort the thumbnails in the window hWndThumbnail. See also the description for the callback type LPFNIG_GUITHUMBCOMP. It is your callback function that performs the actual sorting.

NOTE: See also IG_GUI_thumbnail_attribute_set()function.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

For an example showing the use of this and other IG_GUI_Thumbnail functions and callbacks, see sample application THUMB

Sample: THUMB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_state_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_state_get (
    HWND hWndThumbnail,
    UINT nIndex,
    UINT nMask,
    LPUINT lpnState
);

Arguments:

hWndThumbnail
Handle of the Thumbnail window
nIndex
Index of an thumbnail
nMask
Mask of state
lpnState
State of an thumbnail

Description:

This function changes the thumbnail's state to highlighted and/or selected. nMask and lpnState can be a combination of the following values: IG_GUI_THUMBNAIL_STATE_HIGHLIGHT and IG_GUI_THUMBNAIL_STATE_SELECT.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

For an example of this and other IG_GUI_thumbnail_ functions and callbacks, see sample application THUMB.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_state_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_state_set (
    HWND hWndThumbnail,
    UINT nIndex,
    UINT nMask,
    UINT nState
);

Arguments:

hWndThumbnail
Handle of the Thumbnail window
nIndex
Index of a thumbnail
nMask
Mask of state
nState
State of a thumbnail

Description:

Calling this function will change a thumbnail's state to highlighted and/or selected. nMask and nState can be a combination of the following values: IG_GUI_THUMBNAIL_STATE_HIGHLIGHT and IG_GUI_THUMBNAIL_STATE_SELECT.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_title_CB_register

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_title_CB_register (
    HWND hwndThumbnail,
    LPFNIG_GUITHUMBTITLE lpfnThumbTitle,
    LPVOID lpPrivateData
);

Arguments:

hWndThumbnail
Windows handle to the Thumbnail window
lpfnThumbTitle
The name of the callback function you are registering, to be called to modify the thumbnail title
lpPrivateData
A far pointer to any private data that you want to pass to the callback.

Description:

This function registers a callback of type LPFNIG_GUITHUMBTITLE, which gives you the flexibility to modify the contents of the thumbnail title for the next thumbnail loaded.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

See the LPFNIG_GUITHUMBTITLE example.

Sample: THUMB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_update

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_update (
    HWND hWndThumbnail
);

Arguments:

hWndThumbnail
Windows handle of a Thumbnail window

Description:

This function may be called to update (repaint) the GUI thumbnail window; if an image that is being displayed in the window has changed in memory, for example.

Bits Per Pixel: Not applicable

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HWND	 hWndThumb; 	/* Handle of Thumbnail window */
IG_GUI_thumbnail_update ( hWndThumb );

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_window_create

Group: Graphical User Interface
NOTE: Please use new upgraded function IG_GUI_thumbnail_window_create_ex(): See Note Below.

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_window_create (
    HWND hWndParent,
    LPSTR lpszTitle,
    INT nX,
    INT nY,
    INT nWidth,
    INT nHeight,
    HWND FAR * lphWndThumbnail
);

Arguments:

hWndParent
Handle of the Parent window
lpszTitle
Title of the Thumbnail Window
nX
X position of the window's upper left corner
nY
Y position of the window's upper left corner
nWidth
Width of the window
nHeight
Height of the window
lphWndThumbnail
Far pointer to the HWND object to hold the Thumbnail window handle

Description:

This function is called to create a GUI thumbnail window. A GUI thumbnail window allows your application to display thumbnails of images stored in image files. It also allows you to easily select and sort them.

NOTE:	See also the IG_GUI_thumbnail_attribute_get(),
IG_GUI_thumbnail_attribute_set(),
IG_GUI_thumbnail_file_append(),
IG_GUI_thumbnail_dir_append(), and the other
IG_GUI_thumbnail_...() functions.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

NOTE: The functionality of this API call has been upgraded and supported by the new function IG_GUI_thumbnail_window_create_ex(). The reason that this new function has been created is that the old function does not allow you to set the Windows style of the thumbnail window. In the interest of backward compatibility, we have left the old function in its original form and have retained support for it. If you have already used the old function in your code, it is not mandatory that you modify your code, but it is recommended.

Example:

For an example of this and other IG_GUI_thumbnail_ functions and callbacks, see sample application THUMB.

Sample: THUMB, DISPLAY, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_thumbnail_window_create_ex

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_thumbnail_window_create_ex (
    HWND hWndParent,
    DWORD dwStyle,
    LPSTR lpszTitle,
    INT nX,
    INT nY,
    INT nWidth,
    INT nHeight,
    HWND FAR * lphWndThumbnail
);

Arguments:

hWndParent
Handle of the Parent window
dwStyle
Set to any Windows style bits that you would like the Pan window to have. This parameter can be a combination of window styles ORed together.
lpszTitle
Title of the Thumbnail Window
nX
X position of the window's upper left corner
nY
Y position of the window's upper left corner
nWidth
Width of the window
nHeight
Height of the window
lphWndMagnify
Far pointer to the HWND object to hold Thumbnail window's handle

Description:

This function is called to create a GUI thumbnail window. A GUI thumbnail window allows your application to display thumbnails of images stored in image files. It also allows you to easily select and sort them.

NOTE:	See also functions IG_GUI_thumbnail_attribute_get(),
IG_GUI_thumbnail_attribute_set(),
IG_GUI_thumbnail_file_append(),
IG_GUI_thumbnail_dir_append(), and the other
IG_GUI_thumbnail_...() functions.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_window_associate

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_window_associate (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndImage,
    BOOL bAssociate
);

Arguments:

hIGear
The HIGEAR handle of an image
dwGrpID
The display group identifier indicating where to obtain the display options for drawing an image in the GUI window.
hWndImage
The HWND handle of the image window
bAssociate
TRUE = associate
FALSE = disassociate

Description:

You may call this function to convert an image window owned by your application into a GUI window (bAssociate = TRUE), or to render a GUI window that is no longer a GUI window (bAssociate = FALSE).

In general, the parent window of a magnify or pan window should be made a GUI window so that ImageGear will automatically handle the magnifying or panning function.

In any case, if a window had not been made a GUI window by calling IG_GUI_window_associate() or IG_GUI_window_create (), then your application will have to handle the Windows message such as WM_PAINT, and the WM_... scroll messages generated in response to user mouse clicks.

NOTE: See also function IG_GUI_window_create(), which creates a GUI window, rather than associating an already existing window.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* HIGEAR handle of image  */
HWND hWnd;      /* Window it is being displayed in  */
/* Turn existing window into a GUI window: */
IG_GUI_window_associate ( hIGear, hWnd, TRUE );

Sample: DISPLAY, GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_window_attribute_get

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_window_attribute_get(
    HWND hWnd,
    AT_MODE nAttributeID,
    LPVOID lpData
);

Arguments:

hWnd
Handle of the window in which the image is displayed
nAttributeID
A variable of type AT_MODE, such as IG_GUI_WINDOW_PAINT
lpData
A VOID pointer to a variable of the type required by the nAttributeID parameter. This sets the value for the attribute defined by nAttributeID

Description:

This function gets the current attribute settings of the GUI window. If the argument nAttributeID is set to IG_GUI_WINDOW_PAINT and lpData is set to TRUE, the GUI window is painted.

NOTE: There is currently just one attribute, IG_GUI_WINDOW_PAINT, but this may be expanded in the future.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HWND hWndImage;
AT_ERRCOUNT nErrcount;
AT_MODE	 	nAttribute;
BOOL bPaintFlag;
bPaintFlag = TRUE;      /* enable painting */
/* Get the current attribute settings of the GUI window */
nErrcount = IG_GUI_window_attribute_get(hWndImage,
IG_GUI_WINDOW_PAINT, &bPaintFlag);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_window_attribute_set

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_window_attribute_set (
    HWND hWnd,
    AT_MODE nAttributeID,
    DWORD dwData,
    LPVOID lpData
);

Arguments:

hWnd
Handle of the window in which the image is displayed
nAttributeID
A variable of type AT_MODE, such as IG_GUI_WINDOW_PAINT
dwData
The DWORD value. This used if nAttributeID = IG_GUI_WINDOW_IMAGE_ADD. In this case dwData contains the display group identifier, which should be used for a new image drawing.
lpData
A VOID pointer to a variable of the type required by the nAttributeID parameter. This sets the value for the attribute defined by nAttributeID.

Description:

This function sets the attribute settings of the GUI window. The settings available for nAttributeID include:

IG_GUI_WINDOW_PAINT
If lpData is set to TRUE, the GUI window is painted.
IG_GUI_WINDOW_IMAGE_ADD
Adds a HIGEAR image to a GUI window. See the GUIWin example. Currently, there is one main image and other sub-images can be added to this. If an image is added and there already exists one or more images in the same place, the images will be animated.
IG_GUI_WINDOW_IMAGE_REMOVE
Removes a sub-image previously added with IG_GUI_WINDOW_IMAGE_ADD.
IG_WINDOW_HANDLE_RESIZE
The default value is TRUE. When it is set to FALSE, it prevents the GUI window from responding to WM_RESIZE messages.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HWND hWndImage;
AT_ERRCOUNT nErrcount;
AT_MODE nAttribute;
BOOL bPaintFlag;
bPaintFlag = FALSE;          /* Disable painting */
/* Set the current attribute settings of the GUI window  */
nErrcount = IG_GUI_window_attribute_set(hWndImage,
IG_GUI_WINDOW_PAINT, 0, bPaintFlag);
     /* no ampersand */
nErrcount = IG_GUI_window_attribute_set(hIGear,
IG_GUI_WINDOW_IMAGE_ADD, IG_GRP_DEFAULT,
(LPVOID)hIGearSubImage);
nErrcount = IG_GUI_window_attribute_set(hIGear,
IG_GUI_WINDOW_IMAGE_REMOVE, 0, (LPVOID)hIGearSubImage);
nErrcount = IG_GUI_window_attribute_set(hIGear,
IG_GUI_WINDOW_HANDLE_RESIZE, 0, FALSE);

Sample: GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_window_CB_register

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_window_CB_register (
    HWND hWndImage,
    LPFNIG_GUIWINDESTROY lpfnDestroy,
    LPVOID lpPrivate
);

Arguments:

hWndImage
Image window handle
lpfnDestroy
Far pointer to the callback function to be called when the window is destroyed
lpPrivate
Far pointer to the private data (passed to the callback function)

Description:

This function registers a callback function to be called when a GUI image window is destroyed. These are windows created by IG_GUI_window_create() or by currently GUI-associated by calls to IG_GUI_window_associate ().

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See the example for function IG_GUI_window_create ().

Sample: GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_GUI_window_create

Group: Graphical User Interface

Declaration:

AT_ERRCOUNT ACCUAPI IG_GUI_window_create (
    HIGEAR hIGear,
    DWORD dwGrpID,
    HWND hWndParent,
    const LPSTR lpszTitle,
    INT nX,
    INT nY,
    INT nWidth,
    INT nHeight,
    HWND FAR* lphWndImage
);

Arguments:

hIGear
HIGEAR handle of an image
dwGrpId
Display group identifier, which is used to display an image in the GUI window.
hWndParent
Handle of the Parent window
lpszTitle
Title of an Image Window
nX
X position of the Image window's upper left corner
nY
Y position of the Image window's upper left corner
nWidth
Width of the Image window
nHeight
Height of the Image window
lphWndImage
Far pointer to the HWND object to hold the Image window handle

Description:

This function is called to create a GUI window. See the description of the IG_GUI_window_associate () function.

NOTE: Currently it is possible to change font title for Page windows that is created by IG_GUI_page_window_create(). To set the font use IG_GUI_page_attribute_set() and to get the font use IG_GUI_page_attribute_get() with IG_GUI_PAGE_FONT_TITLE option. As in the case of thumbnail window, the user is responcible for creating and deleting font.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

LPFNIG_GUIWINDESTROY  MyGUIwinCleanup; /* Called when GUI window
closed */
HWND 	hWnd;          /* Handle of existing parent window     */
HWND	 hWndImage;    /* Will hold handle of GUI window        */
BOOL	 bDelete;     /* TRUE= delete HIGEAR image when close window
*/
AT_ERRCOUNT nErrcount;    /* Returned count of errors      */
/* Create a GUI image window: */
nErrcount = IG_GUI_window_create ( hIGear, IG_GRP_DEFAULT, hWnd,
"My GUI Image Window", 100, 50, 400, 200, &hWndImage );
If ( nErrcount == 0)
    {
/* Register a function to be called if user closes this GUI
window:  */
    bDelete = FALSE;    /* (Don't delete HIGEAR if window is
closed)*/
    IG_GUI_window_CB_register ( hWndImage, MyGUIwinCleanup,
(LPVOID) &bDelete );
     ...
    }
/* Callback function, called when window is destroyed: */
VOID ACCUAPI  MyGUIwinCleanup
( LPVOID lpPrivate, HIGEAR hIGear, HWND hWndClosing )
{
/* Delete the image if bDelete not FALSE: */
if ( *((LPBOOL) lpPrivate) )
    {
    if ( IG_image_is_valid (hIGear) )
 { IG_image_delete ( hIGear ); }
    }
return;
}

Sample: GUIWIN, DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_batch_convert

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_batch_convert(
    LPAT_SRCINFO lpSrcInfo,
    LPAT_DSTINFO lpDstInfo,
    const LPSTR lpcszLogFileName
);

Arguments:

lpSrcInfo
A long pointer to a structure of type AT_SRCINFO through which you supply ImageGear with the source directory and format type of the files to be converted. See details below.
lpDstInfo
A long pointer to a structure of type AT_DSTINFO in which you supply ImageGear with the destination directory, format type, and naming convention for the newly converted files. See details below.
lpcszLogFileName
Set this string to a filename for a log file to be generated. The log file will contain a list of files successfully converted, and any images that caused errors. If you do not need a log file, set this to NULL.

Description:

This function is designed to convert a specified set of files from one ImageGear-supported image format type to another. The function takes three parameters: the source information (a structure of type AT_SRCINFO), the destination information (a structure of type AT_DSTINFO), and a const LPSTR to which you specify the path\filename of the log file to create.

AT_SRCINFO is a structure that contains the source file information:

typedef struct tag AT_SRCINFO
{
   LPSTR lpcszSrcDir; /* source dir from which files will be
gathered */
   LPSTR lpcszSrcFilter;/* source filter for files contained on
the
                                                             source
dir*/
}AT_SRCINFO, FAR *LPAT_SRCINFO;

The source information structure must be completed entirely; no fields may be left out. The lpcszSrcDir should be a NULL-terminated string of characters representing the source directory, or where the images that are to be converted will be read from (ex. "c:\public\source\images"). The lpcszSrcFilter should be a NULL-terminated string of characters that represents what type of images should be converted. You may specify more than one type of image to be converted, e.g."*.bmp;*.tif". Each individual filter should be separated by a semicolon.

The LPAT_DSTINFO is a structure that contains the file destination information.

typedef struct tag AT_DSTINFO
{
LPSTR lpcszDstDir;      /*destination directory */
AT_LMODE DstOptions;       /*destination naming convention*/
AT_LMODE DstSaveType;      /*destination save type */
} AT_DSTINFO, FAR *LPAT_DSTINFO;

The destination information structure must be completed entirely; no fields may be left out. The lpcszDstDir argument should be a NULL-terminated string of characters that represents where the images that are to be converted will be stored after they are converted. This directory may or may not exist at the time this function is called. If the directory does not exist this function will create it (ex. "c:\public\destination\images"). If the source image is a multi-page image and the destination format type supports multiple pages, a new multi-page file will be created. If the source image is a multi-page image and the destination save type does not support multiple pages, the resulting destination image file or files will be determined by the naming convention that you supply to the AT_DSTINFO structure. If the naming convention IG_BATCH_USE_SRC_NAME is used, there will be one destination file which is continually overwritten by each subsequent page, and will ultimately contain only the last page of the original source file.

The DstNamingConv should contain one of the predefined constants from accucnst.h, in the section under "*Batch Naming Conventions*". As of this writing, the following naming conventions are available:

IG_BATCH_USE_SRC_NAME: This naming convention will use the source file name, remove the extension and replace it with the new save type default extension for naming each of the converted images. The DstSaveType should be one of the save types defined in the accucnst.h file (ex. IG_SAVE_TIF_UNCOMP).

You must enter a valid path and filename when you set lpczLogFileName.where the path that you specify already exists. If lpcszLogFileName is set to a valid filename, any pre-existing file will be overwritten with the new conversion information. If there is no such file, it will be created. The format of the log file, lpcszLogFileName, if the user has chosen to generate one, will be as follows for image files that are successfully converted:

Image:<Src file name> <src format, src comp>  Converted: <Dst
file name> <dst format, dst comp>
Image:<Src file name> <src format, src comp>  Converted: <Dst
file name> <dst format, dst comp>
Image:<Src file name> <src format, src comp>  Converted: <Dst
file name> <dst format, dst comp>
Image:<Src file name> <src format, src comp>  Converted: <Dst
file name> <dst format, dst comp>
...

If any image files cause errors during the convert, the format of the log file will be as follows:

Image:<Src file name> <src format, src comp> <error type> <error
code number> >
Image:<Src file name> <src format, src comp> <error type> <error
code number> >
Image:<Src file name> <src format, src comp> <error type> <error
code number> >

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT   nErrcount;
LPAT_DSTINFO  DstInfo;
LPAT_SRCINFO  SrcInfo;
SrcInfo.lpcszSrcDir = "c:\public\source\images";
SrcInfo.lpcszSrcFilter = "*.bmp;*.tif";
DstInfo.lpcszDstDir = "c:\public\richard\joe\rich";
DstInfo.DstNamingConv = IG_BATCH_USE_SRC_NAME;
DstInfo.DstSaveType = IG_SAVE_TIF_UNCOMP;
/* convert all .bmp and .tif files from c:\public\source\images
to TIFF uncompressed images and store the coverted images to the
destination directory c:\public\richard\joe\rich, using the
TIFF uncompressed file format*/
nErrcount = IG_image_batch_convert(&SrcInfo, &DstInfo,"
c:\\public\\log.txt");

Sample: THUMB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_bits_per_channel_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_bits_per_channel_get(
    HIGEAR hIGear,
    AT_INT *lpBitsPerChannel
);

Arguments:

hIGear
HIGEAR handle of image
lpBitsPerChannel
Returned number of allocated bits for each pixel channel

Description:

This function gets the number of bits allocated for each pixel channel in an image: 8, 16 or 32.

NOTE: This is not the same as the bit depth of a channel. The number of bits used for a pixel channel may be less than the number of bits allocated.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
AT_INT nBits;           /* Number of bits per channel */
nErrcount = IG_image_bits_per_channel_get(hImage, &nBits);

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_blend_with_alpha

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_blend_with_alpha(
    HIGEAR hSource,
    HIGEAR hAlpha,
    LPAT_RECT blendingArea
);

Arguments:

hSource
HIGEAR handle of source image
hAlpha
HIGEAR handle of image to blend into source image
blendingArea
Rectangle of area to perform blending on

Description:

This function blends the color channels of two images according to the alpha channel of the image identified by hAlpha. This image must contain an alpha channel. Also, the two images must have the same color space. However, the number of alpha and extra channels may differ.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* HIGEAR handle of source image */
HIGEAR hAlpha;          /* HIGEAR handle of alpha image */
AT_RECT r;              /* Rectangle of area to blend */
r.left = r.top = 0;
r.right = r.bottom = 200;
nErrcount = IG_image_blend_with_alpha(hImage, hAlpha, &r);

Sample: ALPHA

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_channel_add

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_channel_add(
    HIGEAR hIGear,
    AT_UINT position,
    LPCAT_CHANNEL_REF channel
);

Arguments:

hIGear
HIGEAR handle of image to add channel to
position
Index of where channel should be added
channel
Location of channel to add

Description:

This function adds a new channel to an image at the specified position, populating the channel's image data from another channel. position is an index into the number of channels starting at 0. channel specifies the location of the channel to add, which consists of the HIGEAR handle of the image containing the channel and the index of the channel within that image.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Add an "extra" channel to an image */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of destination image */
HIGEAR hExtra;          /* Handle of image to use as extra */
AT_CHANNEL_REF channel; /* Channel to add */
AT_INT nChannels;       /* Number of channels in dest. image */
channel.hImage = hExtra;
channel.uNumber = 0;
nErrcount = IG_image_channel_count_get(hImage, &nChannels);
nErrcount = IG_image_channel_add(hImage, nChannels, &channel);
nErrcount = IG_image_colorspace_get(hImage, &cs);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_channel_copy_create

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_channel_copy_create(
    LPCAT_CHANNEL_REF source,
    LPAT_CHANNEL_REF copy
);

Arguments:

source
Location of source channel to copy
copy
Location of new image with copied channel

Description:

This function creates a new image by copying a single channel from an existing image. Specify in source the image and channel index to copy. If the copy is successful, copy will contain the HIGEAR handle of a newly allocated image containing the copied channel. The channel index in copy will always be set to 0. You are responsible for freeing the new image with IG_image_delete.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Extract the first alpha channel if one exists */
/* Otherwise, extract the first color channel */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of source image */
AT_CHANNEL_REF srcChan; /* Channel to copy */
AT_CHANNEL_REF dstChan; /* New image with copied channel */
enumIGColorSpaceIDs cs; /* Source image's color space */
AT_INT nColorChannels;  /* Number of color channels */
nErrcount = IG_load_file("alpha.tif", &hImage);
nErrcount = IG_image_colorspace_get(hImage, &cs);
nColorChannels = IG_util_colorspace_color_count_get(cs);
srcChan.hImage = hImage;
if (IG_util_colorspace_contains_alpha(cs))
    srcChan.uNumber = nColorChannels; /* First alpha channel */
else
    srcChan.uNumber = 0; /* First color channel */
nErrcount = IG_image_channel_copy_create(&srcChan, &dstChan);
hCopy = dstChan.hImage;
nErrcount = IG_save_file(dstChan.hImage, "alpha.bmp",
    IG_SAVE_BMP_UNCOMP);
nErrcount = IG_image_delete(hImage);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_channel_count_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_channel_count_get(
    HIGEAR hIGear,
    AT_INT *lpChannelCount
);

Arguments:

hIGear
HIGEAR handle of image
lpChannelCount
Channel count of the image

Description:

This function counts the image channels.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_channel_depth_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_channel_depth_get(
    HIGEAR hIGear,
    AT_INT Index,
    AT_INT *lpChannelDepth
);

Arguments:

hIGear
HIGEAR handle of image
Index
Channel index to get info on
lpChannelDepth
Bit depth of the chanel

Description:

This function returns the channel bit depth.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_channel_depths_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_channel_depths_get(
    HIGEAR hIGear,
    AT_INT ChannelCount,
    AT_INT *lpChannelDepths
);

Arguments:

hIGear
HIGEAR handle of image
ChannelCount
Length of the channel depths array to be filled
lpChannelDepths
Array of the channel depths to be filled

Description:

This function returns an array of the channel bit depths.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_channel_depths_change

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_channel_depths_change(
    HIGEAR hIGear,
    const AT_INT* newDepths,
    AT_MODE scaleMode
);

Arguments:

hIGear
HIGEAR handle of image
newDepths
New channel depths to set
scaleMode
Mode to use for scaling channel depths - must be one of the following:
IG_DEPTH_CHANGE_SCALE
IG_DEPTH_CHANGE_NO_SCALE

Description:

This function changes the bit depths of the image channels to the specified depths. If scaling is used, pixel data is scaled to match the new bit depths. Otherwise, pixel data will remain unchanged and will be interpreted as conforming to the new depths.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Alter a 24-bit RGB image to have full 8-bit precision
   for green, but only 1-bit precision for red and blue */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT depths[] = { 1, 8, 1 }; /* New channel depths */
nErrcount = IG_load_file("test.jpg", &hImage);
nErrcount = IG_image_channel_depths_change(hImage, depths,
    IG_DEPTH_CHANGE_SCALE);
nErrcount = IG_save_file(hImage, "test.bmp",
    IG_SAVE_BMP_UNCOMP);
nErrcount = IG_image_delete(hImage);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_channel_remove

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_channel_remove(
    HIGEAR hIGear,
    AT_UINT position
);

Arguments:

hIGear
HIGEAR handle of image
position
Index of channel to remove

Description:

This function removes the specified channel from the source image and shifts the remaining channels without transforming pixel data.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Alter a 24-bit RGB image to use the red channel data
   for both red and blue channels */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of source image */
AT_CHANNEL_REF channel; /* Channel to add */
nErrcount = IG_load_file("test.jpg", &hImage);
channel.hImage = hImage;
channel.uNumber = 0;
nErrcount = IG_image_channel_add(hImage, 3, &channel);
nErrcount = IG_image_channel_remove(hImage, 2);
nErrcount = IG_save_file(hImage, "test.bmp",
    IG_SAVE_BMP_UNCOMP);
IG_image_delete(hImage);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_channel_update

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_channel_update(
    LPCAT_CHANNEL_REF channelToUpdateWith,
    LPCAT_CHANNEL_REF channelToBeUpdated
);

Arguments:

channelToUpdateWith
Channel to use as source channel
channelToBeUpdated
Channel to be replaced by source channel

Description:

This function copies pixel data from one channel to another channel. Each channel is specified by a HIGEAR image handle and the channel's index within that image. The source and destination channels can reside in different images or the same image.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Alter a 24-bit RGB image to use the red channel data
for both red and blue channels */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of source image */
AT_CHANNEL_REF chanSrc; /* Channel to update from */
AT_CHANNEL_REF chanDst; /* Channel to update */
nErrcount = IG_load_file("test.jpg", &hImage);
chanSrc.hImage = hImage;
chanSrc.uNumber = 0;
chanDst.hImage = hImage;
chanDst.uNumber = 2;
nErrcount = IG_image_channel_update(&chanSrc, &chanDst);
nErrcount = IG_save_file(hImage, "test.bmp",
    IG_SAVE_BMP_UNCOMP);
IG_image_delete(hImage);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_channels_combine

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_channels_combine(
    LPCAT_CHANNEL_REF channels,
    AT_UINT channelsQty,
    enumIGColorSpaceIDs colorSpace,
    LPHIGEAR hIGear
);

Arguments:

channels
Array of channel descriptors for channels to combine
channelsQty
Number of channels to combine
colorSpace
Color space of new image
hIGear
Pointer to HIGEAR handle where new image is returned

Description:

This function creates a new image with the color space specified by colorSpace. The channels in the new image are copied from the channels specified by channels.

NOTE: This function does not do any color space or pixel conversions, it merely merges the pixel data from different channels together.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Make a copy of a 24-bit RGB image in which the
   red and blue channels are swapped */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of source image */
HIGEAR hImageCombined;  /* Handle of combined image */
AT_CHANNEL_REF chan[3]; /* Channels to combine */
nErrcount = IG_load_file("test.jpg", &hImage);
chan[0].hImage = hImage;
chan[0].uNumber = 2;
chan[1].hImage = hImage;
chan[1].uNumber = 1;
chan[2].hImage = hImage;
chan[2].uNumber = 0;
nErrcount = IG_image_channels_combine(chan, 3,
    IG_COLOR_SPACE_ID_RGB, &hImageCombined);
nErrcount = IG_save_file(hImageCombined, "test.bmp",
    IG_SAVE_BMP_UNCOMP);
IG_image_delete(hImage);
IG_image_delete(hImageCombined);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_channels_separate

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_channels_separate(
    HIGEAR hIGear,
    LPAT_CHANNEL_REF channels,
    AT_UINT channelsQty
);

Arguments:

hIGear
HIGEAR handle of image to store separated channels in
channels
Array of channel descriptors for channels to separate
channelsQty
Number of channels to separate

Description:

This function separates channels in an image by creating a new image for each channel. Each new image contains one channel with creates a new image for each channeln array of pages, where each page contains one channel with color space set to grayscale. This method does not do any color space or pixel conversions.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Load an image and save all of its channels as
   separate pages in a multi-page TIFF file */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of source image */
AT_CHANNEL_REF *chan;   /* Channels to combine */
AT_INT nChannels;       /* Number of channels in image */
AT_INT i;
nErrcount = IG_load_file("test.jpg", &hImage);
nErrcount = IG_image_channel_count_get(hImage, &nChannels);
chan = (AT_CHANNEL_REF *) malloc(nChannels *
sizeof(AT_CHANNEL_REF));
for (i = 0; i < nChannels; i++)
{
    chan[i].hImage = hImage;
    chan[i].uNumber = i;
}
nErrcount = IG_image_channels_separate(hImage, chan,
nChannels);
for (i = 0; i < nChannels; i++)
{
    nErrcount = IG_fltr_save_file(chan[i].hImage, "test.tif",
        IG_SAVE_TIF_UNCOMP, i, !i);
    IG_image_delete(chan[i].hImage);
}
IG_image_delete(hImage);
free(chan);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_colorspace_convert

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_colorspace_convert(
    HIGEAR hIGear,
    enumIGColorSpaceIDs newColorSpace,
    LPCAT_COLORSPACE_CONVERSION_OPTIONS options
);

Arguments:

hIGear
HIGEAR handle of image
newColorSpace
Color space to convert to
options
Conversion options (or NULL)

Description:

This function converts an image to the specified color space. Specify the new color space using a value from enumIGColorSpaceIDs. Argument options controls the conversion flow. You may pass NULL for options if you don't want to specify any options.

For the detailed information about AT_COLORSPACE_CONVERSION_OPTIONS structure and the whole color conversion process please refer to the section Working with Color Space Conversion Engine.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* HIGEAR handle of image */
IG_image_colorspace_convert(hImage, IG_COLOR_SPACE_ID_RGB,
NULL);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_colorspace_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_colorspace_get(
    HIGEAR hIGear,
    enumIGColorSpaceIDs  *lpColorspace
);

Arguments:

hIGear
HIGEAR handle of image
lpColorspace
Returned color space of the image

Description:

This function gets an image's color space ID.

NOTE: An ImageGear color space ID is actually a combination of values. It contains information about 1) color channels, 2) an alpha channel, and 3) extra channels. Examine the definition of enumIGColorSpaceIDs carefully (in accucnst.h) and use bitmasks such as IG_COLOR_SPACE_ID_ColorMask to isolate the information you want.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
enumIGColorSpaceIDs cs; /* Color space ID */
AT_BOOL bIndexed;       /* Is the image indexed? */
nErrcount = IG_image_colorspace_get(hImage, &cs);
if ((cs & IG_COLOR_SPACE_ID_ColorMask) == IG_COLOR_SPACE_ID_I)
    bIndexed = TRUE;
else
    bIndexed = FALSE;

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_compression_type_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_compression_type_get (
    HIGEAR hIGear,
    LPDWORD lpCompression
);

Arguments:

hIGear
HIGEAR handle of image
lpCompression
Far pointer to a DWORD in which will be returned the compression type, such as IG_BI_RLE. The compression types are listed in file ACCUSTD.H.

Description:

This function returns the compression type of the image indicated by hIGear. The value will be returned right justified in the 32-bit DWORD pointed to by argument lpCompression.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;         /* HIGEAR handle of image        */
DWORD dwCompression;  /* Will receive compression type */
IG_image_compression_type_get ( hIGear, &dwCompression );

Sample: IMG_PROC, MULTPAGE, PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_convert

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_convert(
    char *lpszSrcFileName,
    char *lpszDstFileName,
    AT_LMODE lFormatType,
    AT_LMODE lCommand,
    AT_LMODE lOptions
);

Arguments:

lpszSrcFileName
The filename of the source file
lpszDstFileName
The filename of the destination file
lFormatType
The format type of output image to save
lCommand
The type of operation to perform (IG_CONVERT_ type constant)
lOptions
Conversion options (bit mask)

Description:

This function allows you to transform image file without decoding it completely and avoiding the need to load it into a memory. The following types of transformations are supported as of this writing:

  • Lossless conversion of JPEG compressed image files
  • Conversion between PDF and PostScript formats

This method does not process image's metadata. This is responsibility of the user. See filter sample for an example of working with metadata.

Lossless conversion of JPEG compressed image files

This function allows you to apply certain operations on JPEG compressed image files, such as rotation, flipping, etc, without degradation of image quality. It can be used also for lossless conversion between JFIF JPEG and EXIF JPEG file formats, and for adding a thumnbail to a JFIF or EXIF file.

Transformation is done on the DCT coefficients rather than on decompressed pixels, so the lossy decompression/compression stages are not involved.

In contrast, the usual way (to load, rotate and save image) results in significant image degradation, especially when a high compression rate is used.

This function can be useful for converting photographic images between portrait and landscape layouts.

The following lossless operations (lCommand argument) are supported:

IG_CONVERT_NONE
No conversion
IG_CONVERT_ROTATE_90
Rotate 90
IG_CONVERT_ROTATE_180
Rotate 180
IG_CONVERT_ROTATE_270
Rotate 270
IG_CONVERT_FLIP_HORIZONTAL
Flip horizontal
IG_CONVERT_FLIP_VERTICAL
Flip vertical
IG_CONVERT_TRANSPOSE
Flip about upper left - lower right diagonal
IG_CONVERT_TRANSVERSE
Flip about upper right - lower left diagonal

IG_CONVERT_NONE mode can be used for converting between JFIF JPEG and EXIF JPEG format, or for adding a thumbnail to the image.

lOption parameter is a bit mask. Only one bit flag is supported:

IG_CONVERT_OPTION_TRIM = 1

An inherent limitation of such conversions is that the source image dimensions must be multiples of the DCT matrix size (typically 8 or 16) to preserve the entire image. If they are not, the remaining pixels at the right and/or bottom are undefined after transform. The function fills them with a mirror projection of the preceeding pixels. This may work well enough for many photographic pictures. If you prefer not to keep the mirrored edge, set lOption parameter to IG_CONVERT_OPTION_TRIM. With this option set, the function will trim result image dimensions to a multiple of DCT size. In particular:

IG_CONVERT_NONE
Resulting image dimensions will not be modified
IG_CONVERT_ROTATE_90
Resulting image width can be trimmed
IG_CONVERT_ROTATE_180
Resulting image width and height can be trimmed
IG_CONVERT_ROTATE_270
Resulting image height can be trimmed
IG_CONVERT_FLIP_HORIZONTAL
Resulting image width can be trimmed
IG_CONVERT_FLIP_VERTICAL
Resulting image height can be trimmed
IG_CONVERT_TRANSPOSE
Resulting image dimensions will not be modified
IG_CONVERT_TRANSVERSE
Resulting image width and height can be trimmed

The following formats are supported as both source and destination: JFIF-JPEG, EXIF-JPEG. Only Lossy and Progressive compressions are supported. If any other format is used for either source or destination, the function will return an error.

If lFormatType == IG_FORMAT_UNKNOWN, the function will recognize source file format and use it for the destination file to save.

This function also converts the image's thumnbail, if it is present. If the thumnbail is JPEG compressed, it will be converted without degradation of quality. If the source image does not contain a thumnbail, and destination filter's "SAVE_THUMBNAIL" control parameter is set to TRUE, the function will create a thumbnail from the source image.

Conversion between PDF and PostScript formats

This method can also be used for conversion of the entire document from PDF to PostScript or back. The method's parameters should be set as follows to achieve that:

lpszSrcFileName
Name of the input PDF or PS document to convert
lpszDstFileName
Name of the output PDF or PS document
lFormatType
Save format, either IG_FORMAT_PDF, or IG_FORMAT_POSTSCRIPT
lCommand
IG_CONVERT_NONE
lOptions
Not used, set to 0

Bits Per Pixel: All

Return Value:

Number of errors occurred during the function call.

Sample: Filter

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_create

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_create(
    HIGDIBINFO hDIB,
    HIGEAR *lphIGear
);

Arguments:

hDIB
DIB info object with parameters used to create image
lphIGear
Returned HIGEAR handle of created image

Description:

This function creates a new image according to DIB information stored in a DIB info object. Pixel data is allocated and initialized to black.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Create a new image with the same parameters as
   an existing image */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGDIBINFO hDIB;        /* DIB info handle of image */
HIGEAR hImageCreated;   /* Handle of created image */
nErrcount = IG_image_DIB_info_get(hImage, &hDIB);
nErrcount = IG_image_create(hDIB, &hImageCreated);
/* ... */
IG_DIB_info_delete(hDIB);
IG_image_delete(hImageCreated);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_create_alpha

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_create_alpha (
    HIGEAR hIGear,
    HIGEAR hIBackgrnd,
    AT_MODE nCreateMode
);

Arguments:

hIGear
HIGEAR handle of image
hIBackgrnd
HIGEAR handle to a background image
nCreateMode
An integer value of type AT_MODE that tells ImageGear what bit depth the alpha channel should have. The possible settings for this variable, which are defined in accucnst.h are:
IG_ALPHA_CREATE_1 and IG_ALPHA_CREATE_8.

Description:

This function creates an alpha channel in the image hIGear, based on the data found in hIBackgrnd. The height and width of hIBackgrnd must not be less than the height and width of hIGear. If there is already an alpha channel in the image, it will be replaced. Here is the formula by which the alpha channel data is calculated (where I2 stands for second image):

A = (I2 - Back) / (abs(I2 - back) - back);

If hIBackgrnd is a 1-bit image, you should set nCreateMode to IG_ALPHA_CREATE_1. When hIGear is displayed, this data will act as overlay data, where the 2 possible values for each bit of overlay data will determine whether the pixel is displayed or is made transparent, so that whatever is in the background will show through.

If hIBackgrnd is an 8-bit image, you should set nCreateMode to IG_ALPHA_CREATE_8. This will add 8 bits (with 256 possible values) of alpha data for each pixel of hIGear.

NOTE: The image must support the storage of alpha data. Targa (*.tga) is an example of one that does. In a 24-bit Targa image, each pixel is stored to 32 bits, where the extra 8 bits may be used for alpha data.
NOTE: See also IG_IP_blend_with_alpha()function.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear,  /* HIGEAR handles of images */
HIGEAR hIBackgrnd;
AT_ERRCOUNT    nErrcount;  /* Tally of ImageGear errors on the
stack*/
nErrcount = IG_load_file ("Picture1.tga", &hIGear);
nErrcount = IG_load_file( "Picture2".bmp", &hIBackgrnd);
nErrcount = IG_image_create_alpha( hIGear, hIBackgrnd,
IG_ALPHA_CREATE_8);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_create_DIB

Group: Image Utility
NOTE: Please, use the new upgraded function IG_image_create_DIB_ex().

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_create_DIB(
    AT_DIMENSION nWidth,
    AT_DIMENSION nHeight,
    UINT nBitsPerPixel,
    LPAT_DIB lpDIB,
    LPHIGEAR lphIGear
);

Arguments:

nWidth
Set to the width that the image will be, in pixels. If the DIB already exists (lpDIB <> NULL), this value will be ignored.
nHeight
Set to the height that the image will be (number of rows). If the DIB already exists (lpDIB <> NULL), this value will be ignored
nBitsPerPixel
Set to the bit depth of the new DIB. If the DIB already exists (lpDIB <> NULL), this value will be ignored .
lpDIB
Far pointer to a DIB to copy, or NULL if creating an empty DIB. See the tip below. If this parameter is not NULL, it must be a valid pointer to the uncompressed bitmap. For example, the biCompression field of lpDIB can be either:
IG_BI_RGB = 0 or
IG_BI_GRAYSCALE = 503
LphIGear
A far pointer that returns a HIGEAR handle for the DIB just created

Description:

NOTE: The functionality of this API call has been upgraded and supported by the new function IG_image_create_DIB_ex(). The reason that this new function has been created is that the old function cannot support 16-bit DIBs. In the interest of backward compatibility, we have left the old function in its original form and have retained support for it. If you have already used the old function in your code, it is not mandatory that you modify your code, but it is recommended.

This function creates a new DIB and returns you its HIGEAR handle. If the FAR pointer lpDIB = NULL, an empty DIB is created using arguments nWidth, nHeight, and nBitsPerPixel. If lpDIB is not NULL, it should be a FAR pointer to an existing DIB which is to be copied. The DIB to be copied need not have a HIGEAR handle associated with it. The width, height, and Bits Per Pixel will be copied from the existing DIB; arguments nWidth, nHeight, and nBitsPerPixel will be ignored.

If you have an existing DIB which you simply want to give a HIGEAR handle to, use function IG_image_DIB_import(), which does not make a copy of the DIB.

If the lpDIB parameter is not NULL, then it must be a valid pointer to the uncompressed bitmap, that is the biCompression field of the lpDIB structure can be either IG_BI_RGB = 0 or IG_BI_GRAYSCALE = 503.

NOTE: If you set lpDIB to NULL in order to create an empty DIB, the DIB palette will not be initialized. You will have to initialize it yourself. If you do not, the image will be displayed as all black.
Each raster in the DIB data must be padded to 32 bits. ImageGear does not support a top-down DIB (where biHeight is negative).

Bits Per Pixel:

1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

(See also the example for function IG_dspl_DDB_import).
HIGEAR  hIGearNew;      /* Will be handle of new empty DIB */
AT_DIMENSION  nWid, nHi;      /* Dimensions for empty DIB  */
UINT 	Bpp;             /* Bits per pixel for empty DIB */
AT_ERRCOUNT   nErrCount;      /* Count of errors put on stack */
HIGEAR  hIGearCopy;     /* Will be handle of new copied DIB */
char FAR  *lpExistingDIB; /* Holds address of an existing DIB */
/* Create an empty 500 x 300 x 16 bits per pixel DIB:   */
nWid  =  500;  nHi = 300;   /* Create a 500 pixel x 300 row DIB
*/
nBpp  =  16;                /* 16 bits per pixel:  */
nErrCount =  IG_image_create_DIB (nWid, nHi, nBpp, NULL,
&hIGearNew);
if ( nErrs ) { ...}        /* Process any errors */
 ...
/* Copy DIB at *lpExistingDIB, creating HIGEAR image hIGearCopy:
*/
nErrCount =  IG_image_create_DIB (0, 0, 0,  (LPAT_DIB)
lpExistingDIB, &hIGearCopy);
if ( nErrs ) { ...}        /* Process any errors */

Sample: IMGUTIL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_create_DIB_ex

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_create_DIB_ex(
    AT_DIMENSION nWidth,
    AT_DIMENSION nHeight,
    UINT nBitsPerPixel,
    AT_LMODE lCompression,
    LPAT_DIB lpDIB,
    LPHIGEAR lphIGear
);

Arguments:

nWidth
Set to the width that the image will be, in pixels. If the DIB already exists (lpDIB <> NULL), this value will be ignored.
nHeight
Set to the height that the image will be (number of rows). If the DIB already exists (lpDIB <> NULL), this value will be ignored
nBitsPerPixel
Set to the bit depth of the new DIB. If the DIB already exists (lpDIB <> NULL), this value will be ignored .
lCompression
Set to the type of pixel storage format you would like used in the new DIB. Currently, there are three options:
IG_BI_RGB - for standard Windows DIB pixel storage.
IG_BI_GRAYSCALE - for 16-bitgrayscale DIB pixel storage.
IG_BI_CMYK - for 32-bit CMYK DIB pixel storage.
**This variable is named lCompression because it is used to set up the biCompression field of the DIB header.
lpDIB
Far pointer to a DIB to copy, or NULL if creating an empty DIB. See the tip below. If this parameter is not NULL, it must be a valid pointer to the uncompressed bitmap. For example, the biCompression field of lpDIB can be either:
IG_BI_RGB = 0 or
IG_BI_GRAYSCALE = 503
LphIGear
A far pointer that returns a HIGEAR handle for the DIB just created.

Description:

This function creates a new DIB and returns you its HIGEAR handle. If the FAR pointer lpDIB = NULL, an empty DIB is created using arguments nWidth, nHeight, and nBitsPerPixel. If lpDIB is not NULL, it should be a FAR pointer to an existing DIB which is to be copied. The DIB to be copied need not have a HIGEAR handle associated with it. The width, height, and Bits Per Pixel will be copied from the existing DIB; arguments nWidth, nHeight, and nBitsPerPixel will be ignored.

If the lpDIB parameter is not NULL, then it must be a valid pointer to the uncompressed bitmap, that is the biCompression field of the lpDIB structure can be either IG_BI_RGB = 0 or IG_BI_GRAYSCALE = 503.

NOTE: If you set lpDIB to NULL in order to create an empty DIB, the DIB palette will not be initialized. You will have to initialize it yourself. If you do not, the image will be displayed as all black.

Each raster in the DIB data must be padded to 32 bits. ImageGear does not support a top-down DIB (where biHeight is negative).

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32 (CMYK)

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGearNew = NULL; // Will be handle of new empty DIB
AT_DIMENSION nWidth=0, nHight=0; // Dimensions for empty DIB
UINT nBpp = 0; // Bits per pixel for empty DIB
AT_LMODE nCompression = IG_COMPRESSION_NONE;
AT_ERRCOUNT nErrCount = 0; // Count of errors put on stack
HIGEAR hIGearCopy = NULL; // Will be handle of new copied DIB
char FAR *lpExistingDIB = NULL; // Holds address of an existing
DIB
// Create an empty 500 x 300 x 16 bits per pixel DIB
nWidth = 500; nHight = 300; nBpp = 16;
nErrCount = IG_image_create_DIB_ex (nWidth, nHight, nBpp,
nCompression, NULL, &hIGearNew);
if( nErrCount ) //Process any errors
// Copy DIB at *lpExistingDIB, creating HIGEAR image hIGearCopy
nErrCount = IG_image_create_DIB_ex (0, 0, 0, 0, (LPAT_DIB)
lpExistingDIB, &hIGearCopy);
if( nErrCount ) //Process any errors

Sample: IMGUTIL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_create_empty

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_create_empty(
    HIGDIBINFO hDIB,
    HIGEAR *lphIGear
);

Arguments:

hDIB
DIB info object with parameters used to create image
lphIGear
Returned HIGEAR handle of created image

Description:

This function creates a new empty image. The resulting image does not have pixel data allocated.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Create a new image with the same parameters as
   an existing image, but with no pixel data allocated */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGDIBINFO hDIB;        /* DIB info handle of image */
HIGEAR hImageCreated;   /* Handle of created image */
nErrcount = IG_image_DIB_info_get(hImage, &hDIB);
nErrcount = IG_image_create_empty(hDIB, &hImageCreated);
/* ... */
IG_DIB_info_delete(hDIB);
IG_image_delete(hImageCreated);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_delete

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_delete (HIGEAR hIGear );

Arguments:

hIGear
HIGEAR handle of image to delete

Description:

This function removes the HIGEAR handle of hIGear, and frees the memory of the associated HIGEAR structure. This function also frees the memory associated with the image's DIB, if ImageGear allocated the DIB memory. If ImageGear did not allocate the DIB memory, the DIB continues to exist and it is the responsibility of your application to free this memory when done with it

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;        /*ImageGear handle of an existing image
*/
AT_ERRCOUNT nErrcount;   /*Count of errs on stack upon return
from func */
/* Invalidate handle, free HIGEAR mem (and DIB mem if alloc'd by
ImageGear)*/
nErrcount = IG_image_delete ( hIGear );
 ...
/* hIGear is now not associated with any image  */
/* hIGear can now be used to hold handle associated with new
image loaded here: */
nErrcount = IG_load_file ( "picture.bmp" , &hIGear );

Sample: ASCII, CLPBRD, COLOR, DISPLAY, GUIWIN,

IMG_PROC, IMGUTIL, IOSET, MAGNIFY, MDI, MEMIO,

MFC, PAGE, PALEDT, PAN, PIX_ACC, PRINT, SCAN,

THUMB, TWAIN, WIPES, THREADS, ART, Vector,

FILTER, FlashPix, IC, JPEG, MULTIMED,

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_DIB_export

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_DIB_export(
    const HIGEAR hIGear,
    AT_VOID *lpBuffer,
    AT_INT BufferSize,
    const AT_DIB_EXPORT_OPTIONS *lpOptions
);

Arguments:

hIGear
HIGEAR handle of image to export DIB from
lpBuffer
Memory buffer where DIB will be exported
BufferSize
Size of memory buffer - use IG_image_DIB_export_size_calc to determine what to use for this
lpOptions
Export options:
Format:
IG_DIB_EXPORT_FORMAT_WINDOWS - Export DIB in standard Windows DIB format. 9-16bpp grayscale images cannot be exported in this format. CMYK images will be exported as24bpp RGB.
IG_DIB_EXPORT_FORMAT_IG_LEGACY - Export DIB in ImageGear legacy format. In this format, DIB compression can be IG_BI_GRAYSCALE for 9-16bpp grayscale, in which case the DIB bit depth will be the actual bit depth from 9 to 16. Also, DIB compression can be IG_BI_CMYK for CMYK images, in which case the DIB bit depth will be 32.
UseAlpha:
If the image contains an alpha channel, and this is set to TRUE, the alpha channel will be blended into the color channel(s) during export.
imgRect:
A rectangle that specifies an area of the image to be exported. If 0 is specified for the width or height, the image dimensions will be used instead.

Description:

This function exports the contents of hIGear into a buffer, provided by the application, using Windows DIB or ImageGear AT_DIB format. hIGear remains valid after calling this function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of source image */
HIGEAR hImported;       /* Handle of image with imported DIB */
LPAT_DIB lpDIBBuffer;   /* Buffer to store exported DIB */
AT_INT DIBSize;         /* Size of exported DIB in bytes */
AT_DIB_EXPORT_OPTIONS Options; /* DIB export options */
LPAT_BYTE lpBits;       /* Pointer to image bits */
AT_DWORD i = 0;
/* Load a 24-bit RGB image and export it as a DIB */
nErrcount = IG_load_file("test.jpg", &hImage);
Options.Format = IG_DIB_EXPORT_FORMAT_IG_LEGACY;
Options.UseAlpha = FALSE;
memset(&Options.imgRect, 0, sizeof(AT_RECTANGLE));
nErrcount = IG_image_DIB_export_size_calc(hImage,
    &DIBSize, &Options);
lpDIBBuffer = (LPAT_DIB) malloc(DIBSize);
nErrcount = IG_image_DIB_export(hImage, lpDIBBuffer,
    DIBSize, &Options);
/* Add some random noise to the DIB */
lpBits = (LPAT_BYTE) lpDIBBuffer + sizeof(AT_DIB);
while (i < lpDIBBuffer->biSizeImage - 3)
{
    lpBits[i] = 0;
    lpBits[i + 1] = 0;
    lpBits[i + 2] = 0;
    i += (rand() % 7) + 3;
}
/* Import the DIB and save it as a BMP file */
nErrcount = IG_image_DIB_import(lpDIBBuffer, &hImported);
nErrcount = IG_save_file(hImported, "test.bmp",
    IG_SAVE_BMP_UNCOMP);
IG_image_delete(hImported);
IG_image_delete(hImage);
free(lpDIBBuffer);

Sample: FILTER, IMGUTIL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_DIB_export_size_calc

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_DIB_export_size_calc(
    const HIGEAR hIGear,
    AT_INT *lpDIBSize,
    const AT_DIB_EXPORT_OPTIONS *lpOptions
);

Arguments:

hIGear
HIGEAR handle of image to calculate exported DIB size for
lpDIBSize
Pointer to where exported DIB size will be stored
lpOptions
Export options

Description:

This function calculates the size of the exported DIB for an image. In order to export an image's DIB, you will need to pass a memory buffer with at least this many bytes allocated to IG_image_DIB_export.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of source image */
HIGEAR hImported;       /* Handle of image with imported DIB */
LPAT_DIB lpDIBBuffer;   /* Buffer to store exported DIB */
AT_INT DIBSize;         /* Size of exported DIB in bytes */
AT_DIB_EXPORT_OPTIONS Options; /* DIB export options */
LPAT_BYTE lpBits;       /* Pointer to image bits */
AT_DWORD i = 0;
/* Load a 24-bit RGB image and export it as a DIB */
nErrcount = IG_load_file("test.jpg", &hImage);
Options.Format = IG_DIB_EXPORT_FORMAT_IG_LEGACY;
Options.UseAlpha = FALSE;
memset(&Options.imgRect, 0, sizeof(AT_RECTANGLE));
nErrcount = IG_image_DIB_export_size_calc(hImage,
    &DIBSize, &Options);
lpDIBBuffer = (LPAT_DIB) malloc(DIBSize);
nErrcount = IG_image_DIB_export(hImage, lpDIBBuffer,
    DIBSize, &Options);
/* Add some random noise to the DIB */
lpBits = (LPAT_BYTE) lpDIBBuffer + sizeof(AT_DIB);
while (i < lpDIBBuffer->biSizeImage - 3)
{
    lpBits[i] = 0;
    lpBits[i + 1] = 0;
    lpBits[i + 2] = 0;
    i += (rand() % 7) + 3;
}
/* Import the DIB and save it as a BMP file */
nErrcount = IG_image_DIB_import(lpDIBBuffer, &hImported);
nErrcount = IG_save_file(hImported, "test.bmp",
    IG_SAVE_BMP_UNCOMP);
IG_image_delete(hImported);
IG_image_delete(hImage);
free(lpDIBBuffer);

Sample: FILTER, IMGUTIL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_DIB_import

Group: Format Filters

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_DIB_import(
    const AT_DIB* lpDIB,
    LPHIGEAR lphIGear
);

Arguments:

lpDIB
DIB to be imported
lphIGear
HIGEAR handle of image created from imported DIB

Description:

This function creates a new HIGEAR image from a Windows DIB stored in memory. This function copies pixels to the new HIGEAR. Application continues to own lpDIB after calling this function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of source image */
HIGEAR hImported;       /* Handle of image with imported DIB */
LPAT_DIB lpDIBBuffer;   /* Buffer to store exported DIB */
AT_INT DIBSize;         /* Size of exported DIB in bytes */
AT_DIB_EXPORT_OPTIONS Options; /* DIB export options */
LPAT_BYTE lpBits;       /* Pointer to image bits */
AT_DWORD i = 0;
/* Load a 24-bit RGB image and export it as a DIB */
nErrcount = IG_load_file("test.jpg", &hImage);
Options.Format = IG_DIB_EXPORT_FORMAT_IG_LEGACY;
Options.UseAlpha = FALSE;
memset(&Options.imgRect, 0, sizeof(AT_RECTANGLE));
nErrcount = IG_image_DIB_export_size_calc(hImage,
    &DIBSize, &Options);
lpDIBBuffer = (LPAT_DIB) malloc(DIBSize);
nErrcount = IG_image_DIB_export(hImage, lpDIBBuffer,
    DIBSize, &Options);
/* Add some random noise to the DIB */
lpBits = (LPAT_BYTE) lpDIBBuffer + sizeof(AT_DIB);
while (i < lpDIBBuffer->biSizeImage - 3)
{
    lpBits[i] = 0;
    lpBits[i + 1] = 0;
    lpBits[i + 2] = 0;
    i += (rand() % 7) + 3;
}
/* Import the DIB and save it as a BMP file */
nErrcount = IG_image_DIB_import(lpDIBBuffer, &hImported);
nErrcount = IG_save_file(hImported, "test.bmp",
    IG_SAVE_BMP_UNCOMP);
IG_image_delete(hImported);
IG_image_delete(hImage);
free(lpDIBBuffer);

Sample: FILTER, IMGUTIL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_DIB_info_get

Group: DIB Info Services

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_DIB_info_get(
    HIGEAR hIGear,
    HIGDIBINFO *lphDIB
);

Arguments:

hIGear
HIGEAR handle of image to create DIB info object from
lphDIB
Returned DIB info object handle

Description:

This function returns the handle of a new DIB info object containing information about the given image. The application must delete it after it is done using it by calling IG_DIB_info_delete().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGDIBINFO hDIBInfo;    /* DIB info handle */
HIGEAR hImage;          /* HIGEAR handle of image */
AT_INT nChannels;       /* Returned number of channels */
nErrcount = IG_image_DIB_info_get(hImage, &hDIBInfo);
nChannels = IG_DIB_channel_count_get(hDIBInfo);
IG_DIB_info_delete(hDIBInfo);

Sample: ALPHA, ARTEXT, DISPLAY, FILTER, IC, IMG_PROC, ISIS, JPEG, LEGACY_COLOR, MED, MULT, PALEDT, PJPEG, PRINT, RECOGNITION, TWAIN, PDFDemo

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_DIB_palette_pntr_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_DIB_palette_pntr_get (
    HIGEAR hIGear,
    LPAT_RGBQUAD FAR *lpRGBQ,
    LPUINT lpEntries
);

Arguments:

hIGear
HIGEAR handle of image
lpRGBQ
Far pointer to a variable of type LPAT_RGBQUAD, in which this function will store the address of the start of the image's DIB palette
lpEntries
Far pointer to a variable in which will be returned the number of entries in the palette

Description:

This function is called to obtain the address of a HIGEAR image's DIB palette. Since a DIB palette consists of a list of AT_RGBQUAD structs, this function returns the address of the palette's first AT_RGBQUAD struct.

NOTE: See the section ImageGear Data Types and Structures, for a description of the AT_RGBQUAD struct.

When referencing a DIB palette, remember that each DIB palette entry contains 4 bytes, not 3, and that the order of the bytes is: Blue, Green, Red, Unused (not Red, Green, Blue).

NOTE: Directly altering a DIB's header, or its palette size or bitmap size, without using the HIGEAR can cause problems. ImageGear's internal HIGEAR structure keeps track of the DIB and other internal items. These fields can not be updated correctly if you alter the DIB without using the HIGEAR.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See the example for function IG_palette_save ().

Sample: PALEDT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_DIB_raster_pntr_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_DIB_raster_pntr_get(
    HIGEAR hIGear,
    AT_PIXPOS row,
    AT_VOID **lplpRaster
);

Arguments:

hIGear
HIGEAR handle of image
row
Row in image to retrieve raster pointer for
lplpRaster
Returned pointer to the 1st pixel in the raster

Description:

This function gets a pointer to the beginning of pixel data for a raster in the given image.

As long as the image is not 1bpp B/W, you can use this pointer to access other rasters in the image. So you could get a pointer to the first raster and use that pointer to access the entire image.

Rasters are stored from top to bottom, are DWORD-padded, use 8, 16, or 32 bits to store channel values, and have alpha/extra channels included in-line with the color channels. For example, an RGB image with an alpha channel would be stored as: RGBA RGBA RGBA ...

If the image is 1bpp b/w, it is stored in a compressed run ends format. See IG_runs_row_get ()/IG_runs_row_set () for a description of this format. It is recommended to use these functions to access run ends data, but you can use IG_image_DIB_raster_pntr_get() with the following restrictions:

  1. You can only read data. It is not safe to write data.
  2. You can only access the raster you've retrieved a pointer to.

So you have to call IG_image_DIB_raster_pntr_get() for each raster you want to access.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
LPAT_VOID lpRst;        /* Pointer to a raster */
nErrcount = IG_image_DIB_raster_pntr_get(hImage, 0, &lpRst);
/* lpRst now points to first pixel in topmost raster */

Sample: FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_dimensions_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_dimensions_get (
    HIGEAR hIGear,
    LPAT_DIMENSION lpWidth,
    LPAT_DIMENSION lpHeight,
    LPUINT lpBitsPerPixel
);

Arguments:

hIGear
ImageGear handle of image
lpWidth
Far pointer to where to return width of image (number of pixels per row)
lpHeight
Far pointer to where to return height (number of rows in image)
lpBitsPerPixel
Far pointer to where to return depth of image (number of Bits Per Pixel)

Description:

This function will return to you the width, height, and number of Bits Per Pixel, from the DIB of the image indicated by handle hIGear.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;           /* Handle of image */
AT_DIMENSION nWidth, nHeight;  /* Will hold returned width and
height  */
UINT nBpp             /* Will hold returned bits per pixel    */
AT_ERRCOUNT nErrcount      /* Will hold returned error count
*/
nErrcount = IG_image_dimensions_get ( hIGear, &nWidth, &nHeight,
&nBpp );

Sample: COLOR, DISPLAY, GUIWIN, IMG_PROC, MULTPAGE,

PALEDT, PIX_ACC, TIMING, THREADS, ART, FlashPix,

MULTIMED

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_duplicate

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_duplicate (
    HIGEAR hIGear,
    LPHIGEAR lphIGear
);

Arguments:

hIGear
HIGEAR handle to the current image to be duplicated
lphIGear
A far pointer in which the handle of the new, duplicate image is returned.

Description:

This function creates an exact duplicate of the current HIGEAR image, and returns the handle to the new image to you in lphIGear.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;/* HIGEAR handle of image  */
HIGEAR lphIGear;  /* HIGEAR handle to new duplicate image   */
IG_image_duplicate(hIGear, &lphIGear);

Sample: COLOR, IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_extra_channel_info_count_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_extra_channel_info _count_get(
    HIGEAR hIGear,
    AT_INT *lpnCount
);

Description:

This method gets the number of entries in the image DIB's extra channel info array.

Parameters:

hIGear
Image handle
lpnCount
The number of entries in the image DIB's extra channel info array

Returns:

Error count.


IG_image_extra_channel_info_entry_copy_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_DIB_extra_channel_info_entry_copy_get(
    HIGEAR hIGear,
    AT_UINT nIndex,
    HIGEXTRACHANNELINFO* lphInfo
);

Description:

This method obtains a copy of the image DIB's extra channel info array entry at nIndex position.

Parameters:

hIGear
Image handle
nIndex
Index to the entry to obtain
lphInfo
Obtained extra channel info entry

Returns:

Error count.


IG_image_extra_channel_info_entry_update_from

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI
IG_image_extra_channel_info_entry_update_from(
    HIGEAR hIGear,
    AT_UINT nIndex,
    HIGEXTRACHANNELINFO hInfo
);

Description:

This method creates a copy of the extra channel info specified by hInfo and replaces the existing HIGEAR's extra channel info entry at nIndex position with the new one.

Parameters:

hIGear
Image handle
nIndex
Index to the entry to update
hInfo
New extra channel info entry

Returns:

Error count.


IG_image_extra_channel_info_pointer_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_extra_channel_info_pointer_get(
    HIGEAR hIGear,
    HIGEXTRACHANNELINFO* *lphInfo
);

Description:

This method gets a pointer to the image DIB's extra channel info array.

Parameters:

hIGear
Image handle
lphInfo
Pointer to image DIB's extra channel info array

Returns:

Error count.


IG_image_extra_channel_info_update_from

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_extra_channel_info_update_from(
    HIGEAR hIGear,
    HIGEXTRACHANNELINFO *lphInfo,
    AT_INT nCount
);

Description:

This method creates a copy of the info array specified by lphInfo and attaches it to HIGEAR's extra channel info array, replacing the old value.

Parameters:

hIGear
Image handle
lphInfo
Extra channel info array
nCount
The number of entries in the extra channel info array

Returns:

Error count.


IG_image_grayscale_LUT_copy_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_grayscale_LUT_copy_get(
    HIGEAR hIGear,
    HIGLUT *lpLUT
);

Arguments:

hIGear
ImageGear handle.
lpLUT
New LUT handle.

Description:

This function returns a copy of image grayscale LUT, if it exists.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

None


IG_image_grayscale_LUT_exists

Group: Image Utility

Declaration:

AT_BOOL ACCUAPI IG_image_grayscale_LUT_exists(
    HIGEAR hIGear
);

Arguments:

hIGear
HIGEAR handle.

Description:

This function checks whether HIGEAR has a grayscale LUT attached.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

None


IG_image_grayscale_LUT_update_from

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_grayscale_LUT_update_from(
    HIGEAR hIGear,
    HIGLUT lut
);

Arguments:

hIGear
HIGEAR handle.
lut
LUT handle.

Description:

This function updates (creates if not present) a grayscale LUT for the image.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: Medical

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_is_CAD

Group: Image Utility

Declaration:

AT_BOOL ACCUAPI IG_image_is_CAD( HIGEAR hIGear)

Arguments:

hIGear
HIGEAR handle of image

Description:

This function returns TRUE if the image is CAD.

Bits Per Pixel: All

Return Value:

Returns TRUE if the image is CAD, FALSE - otherwise.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_is_gray

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_is_gray (
    HIGEAR hIGear,
    LPBOOL lpIsImageGray
);

Arguments:

hIGear
HIGEAR handle of image
lpIsImageGray
Far pointer to a BOOL variable in which will be returned TRUE if the image is a grayscale image

Description:

This function is called to determine if an image is a grayscale image. To be considered grayscale by this function, the image must be indexed (has a palette), grayscale (has no palette), or 24 bit RGB.

An indexed image is grayscale if each palette entry is equal to the palette index offset for red, green, and blue. The shades of gray in the palette must be sorted from black to white or white to black. If the palette contains only shades of gray but is not sorted, this function will return FALSE.

For a 24-bit image all pixels in the image must have pixels where red, green, and blue are all equal to one another. If this condition is failed for any pixel in the image, this function will return FALSE.

NOTE: FALSE is returned for all 1-bit images, even thought the palette may contain only 2 shades of gray.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* HIGEAR handle of image   */
BOOL bItsGray;   /* Will be set = TRUE if grayscale */
IG_image_is_gray ( hIGear, &bItsGray );

Sample: IMG_PROC, TIMING, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_is_PDF

Group: Image Utility

Declaration:

AT_BOOL ACCUAPI IG_image_is_PDF( HIGEAR hIGear)

Arguments:

hIGear
HIGEAR handle of image

Description:

This function returns TRUE if the image is PDF.

Bits Per Pixel: All

Return Value:

Returns TRUE if the image is PDF, FALSE - otherwise.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_is_raster

Group: Image Utility

Declaration:

AT_BOOL ACCUAPI IG_image_is_raster( HIGEAR hIGear)

Arguments:

hIGear
HIGEAR handle of image

Description:

This function returns TRUE if the image is raster.

Bits Per Pixel: All

Return Value:

Returns TRUE if the image is raster, FALSE - otherwise.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_is_signed_get

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_is_signed_get (
    HIGEAR hIGear,
    LPBOOL lpbSigned
);

Arguments:

hIGear
HIGEAR handle of an image
lpbSigned
Indicates whether or not a grayscale image should be treated as signed.

Description:

This function is available for all versions of ImageGear. It is used on grayscale images (8-bit gray level and 9-16-bit gray level). When ImageGear loaded the image, it attempted to determine if the pixel representations were signed or unsigned. If it could not determine, then it assumed unsigned.

Bits Per Pixel: 8-bit gray level, 16-bit gray level

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_is_signed_set

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_is_signed_set (
    HIGEAR hIGear,
    BOOL bSigned
);

Arguments:

hIGear
HIGEAR handle of image
bSigned
Indicates whether or not grayscale image should be treated as signed.

Description:

This function is available for all versions of ImageGear. It is used on grayscale images (8-bit gray level and 9-16-bit gray level). When ImageGear loaded the image, it attempted to determine if the pixel representations were signed or unsigned. If it could not determine, then it assumed unsigned. Use this function to force the image-attribute to either TRUE or FALSE.

NOTE: Note that this function DOES NOT modify the pixel-values themselves - it only changes the way in which ImageGear will display them. Call IG_dspl_image_draw() after IG_image_is_signed_set() to repaint the image.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_is_valid

Group: Image Utility

Declaration:

BOOL ACCUAPI IG_image_is_valid ( HIGEAR hIGear );

Arguments:

hIGear
HIGEAR handle of image

Description:

This function is called to determine if the HIGEAR variable hIGear contains a handle of a valid ImageGear image. Note that the return-type of the function is BOOL, not AT_ERRCOUNT. TRUE is returned if the handle is valid and may be used as the HIGEAR argument in calls to other ImageGear functions.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

This function returns TRUE if a hIGear contains a valid handle, FALSE otherwise

Example:

HIGEAR hIGear;     /* Contains HIGEAR handle of image   */
if ( IG_image_is_valid ( hIGear ) )
    { IG_save_file ( hIGear, "picture.bmp", IG_SAVE_BMP_UNCOMP
); }

Sample: ASCII, CLPBRD, COLOR, DISPLAY, GUIWIN,

IMG_PROC, IMGUTIL, IOSET, JPEG, MAGNIFY, MDI,

MEMIO, MFC, PAGE, PALEDT, PAN, PIX_ACC,

THUMB, TWAIN, WIPES, THREADS, JNIDLL, ART,

Scan, Vector, FILTER, FlashPix, IC, MULTIMED

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_is_vector

Group: Image Utility

Declaration:

AT_BOOL ACCUAPI IG_image_is_vector( HIGEAR hIGear)

Arguments:

hIGear
HIGEAR handle of image

Description:

This function returns TRUE if the image is vector.

Bits Per Pixel: All

Return Value:

Returns TRUE if the image is vector, FALSE - otherwise.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_layer_create

Group: Image Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_layer_create(
    HIGEAR hIGear,
    LPHIGIMAGELAYER lphLayer
    );

Description:

This function creates the image layer from the raster image.

Arguments:

hIGear
Raster image to create layer from.
lphLayer
Handle to the created image layer object.

Return Value:

Error count.


IG_image_layer_image_get

Group: Image Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_layer_image_get(
    HIGIMAGELAYER hLayer,
    LPHIGEAR lphIGear
);

Description:

This function obtains the raster image representing image layer.

Arguments:

hLayer
Handle to the image layer object.
lphIGear
Image representing the layer.

Return Value:

Error count.


IG_image_layer_location_get

Group: Image Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_layer_location_get(
    HIGIMAGELAYER hLayer,
    LPAT_POINT lpLocation
);

Description:

This function obtains the X and Y coordinates of the image layer's left/top point.

Arguments:

hLayer
Handle to the image layer object.
lpLocation
X and Y coordinates of the image layer's left/top point.

Return Value:

Error count.


IG_image_layer_location_set

Group: Image Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_layer_location_set(
    HIGIMAGELAYER hLayer,
    LPAT_POINT lpLocation
);

Description:

This function sets the X and Y coordinates of the image layer's left/top point.

Arguments:

hLayer
Handle to the image layer object.
lpLocation
the X and Y coordinates of the image layer's left/top point.

Return Value:

Error count.


IG_image_layer_opacity_get

Group: Image Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_layer_opacity_get(
    HIGIMAGELAYER hLayer,
    AT_INT* lpnOpacity
);

Description:

This function obtains the opacity of the image layer.

Arguments:

hLayer
Handle to the image layer object.
lpnOpacity
Opacity of the image layer.

Return Value:

Error count.


IG_image_layer_opacity_set

Group: Image Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_layer_opacity_set(
    HIGIMAGELAYER hLayer,
    AT_INT nOpacity
);

Description:

This function sets the opacity of the image layer.

Arguments:

hLayer
Handle to the image layer object.
nOpacity
Opacity of the image layer.

Return Value:

Error count.


IG_image_layers_flatten

Group: Image Layers

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_layers_flatten(
    HIGEAR hIGear
);

Description:

This function renders all the visible layers into the raster composition DIB.

This function can be used to flatten the layered page into the raster page. As a result of this function the raster image specified by HIGEAR is regenerated from the layer array composition attached to the same image.

Arguments:

hIGear
Handle to the image whose layers are flattened.

Return Value:

Error count.


IG_image_layers_get

Group: Image Layers

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_layers_get(
    HIGEAR hIGear,
    LPHIGLAYERARRAY lphLayers
);

Description:

This function obtains the layers associated with the specified HIGEAR.

Arguments:

hIGear
Handle to the image whose layers are obtained.
lphLayers
Obtained layer array representing the layers of the specified image.

Return Value:

Error count.


IG_image_layers_remove

Group: Image Layers

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_layers_remove(
    HIGEAR hIGear
);

Description:

This function removes the layers from the specified HIGEAR.

Arguments:

hIGear
Handle to the image whose layers are removed.

Return Value:

Error count.


IG_image_layers_set

Group: Image Layers

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_layers_set(
    HIGEAR hIGear,
    HIGLAYERARRAY hLayers
);

Description:

This function sets the new layers to the specified HIGEAR. It does destroy the exisitng layers if there are any.

Arguments:

hIGear
Handle to the image whose layers are set.
hLayers
Layer array to set.

Return Value:

Error count.


IG_image_orientation_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_orientation_get(
    HIGEAR hIGear,
    LPAT_MODE lpOrientation
);

Arguments:

hIGear
HIGEAR handle of image
lpOrientation
A constant of type AT_MODE that will return the current orientation of the HIGEAR image

Description:

This function tells you what orientation the HIGEAR image was saved with. The two most-often-used orientations are "Portrait" and "Landscape." However, in order to provide complete support for the TIFF file format, which defines eight image orientations, ImageGear interprets eight orientations. lpOrientation will return the orientation mode used, as an IG_ORIENT_... constant. For an image with a "Portrait" orientation, this value would normally be IG_ORIENT_TOP_LEFT. For an image with "Landscape" orientation, this value would be either IG_ORIENT_RIGHT_TOP or IG_ORIENT_LEFT_BOTTOM. The full list of constants is defined in accucnst.h.

Notice that the IG_ORIENT constants contain indicators of two directions. For IG_ORIENT_TOP_LEFT, the first direction is "TOP." This specifies the placement of row 0 of the image. The second direction is "LEFT", and this specifies the placement of column 0. Thus, IG_ORIENT_TOP_LEFT specifies that row 0 of the image stored in the file should be displayed at the top and column 0 should be displayed at the left. This is the normal orientation of most images. On the other hand, IG_ORIENT_LEFT_BOTTOM specifies that row 0 should be displayed at the left and column 0 at the bottom. For this to be true the image would have to be rotated 90× counter clockwise.

NOTE: The orientation setting of an image is for informational purposes only. This information is stored in the header structure of those file formats that support the storage of orientation information. The orientation setting tells how the image was intended to be displayed. In the last example above, the bitmap image is not necessarily stored "sideways." When you find that it is intended to be displayed sideways, you could call IG_dspl_orientation_get () to display it in its intended orientation, or call IG_IP_rotate_multiple_90() to rearrange the actual bitmap data so that the image is actually stored sideways. See example code below.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

AT_ERRCOUNT  nErrcount;    /* Tally of any ImageGear errors that
occur */
HIGEAR  hIGear;   /* Contains HIGEAR handle of image  */
 ...
nErrcount = IG_image_orientation_get(hIGear,
    &nOrientation);
if (nOrientation == IG_ORIENT_LEFT_BOTTOM)
{
/* if the image is meant to be displayed with row 0 at left and
col 0 at bottom, set the display angle to rotate 90×
counterclockwise */
    nErrcount = IG_dspl_orientation_set(hIGear, IG_GRP_DEFAULT,
IG_DSPL_ORIENT_LEFT_BOTTOM);
    }

Sample: FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_orientation_set

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_orientation_set(
    HIGEAR hIGear,
    AT_MODE nOrientation
);

Arguments:

hIGear
HIGEAR handle of image
nOrientation
A constant of type AT_MODE that sets the orientation of the HIGEAR image

Description:

This function sets the orientation of the currently loaded HIGEAR image. The two most-often-used orientations are "Portrait" and "Landscape." However, in order to provide complete support for the TIFF file format, ImageGear interprets eight orientations. nOrientation is set to an IG_ORIENT_... constant. To set the orientation to "Portrait" you would normally use IG_ORIENT_TOP_LEFT. To set the orientation to "Landscape", use either IG_ORIENT_RIGHT_TOP or IG_ORIENT_LEFT_BOTTOM. The full list of constants is defined in accucnst.h.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See example under IG_image_orientation_get () function.

Sample: FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_resolution_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_resolution_get(
    HIGEAR hIGear,
    LPLONG lpXResNumerator,
    LPLONG lpXResDenominator,
    LPLONG lpYResNumerator,
    LPLONG lpYResDenominator,
    LPAT_MODE lpnUnits
);

Arguments:

hIGear
HIGEAR handle to the image
lpXResNumerator
A far pointer in which is returned the setting the numerator of the x resolution of an image
lpXResDenominator
A far pointer in which is returned the setting for the denominator of the y resolution of an image
lpYResNumerator
A far pointer in which is returned the setting for the numerator of the y resolution of an image
lpYResDenominator
A far pointer in which is returned the setting for the denominator of the y resolution of an image
lpnUnits
A far pointer to an AT_MODE variable, in which is returned the units of resolution for the image. See description for IG_image_resolution_set ().

Description:

This function is used to retrieve the current resolution settings of the HIGEAR image. It returns the values and units of resolution stored in the HIGEAR. To set these values, use IG_image_resolution_set (). See that function's description for more details about DIB and HIGEAR resolution settings.

The image resolution in the HIGEAR is stored as a pair of 2 ratio: one for horizontal, or "x" resolution, and one for vertical, or "y" resolution. Each ratio is a pair of LONGs. This is the method used by several file formats which store rational values but need to avoid IEEE types of float and double. If the X resolution numerator is 600 and the denominator is 2, then the x resolution is 300 (600/2).

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;
LONG  XResNumerator;
LONG  XResDenominator;
LONG  YResNumerator;
LONG  YResDenominator;
AT_MODE  Units;
AT_ERRCOUNT  nErrcount;
/* Change the current resolution setting to INCHES */
nErrcount = IG_image_resolution_get(hIGear, &XResNumerator,
&XResDenominator, &YResNumerator, &YResDenominator, &nUnits);
if (nUnits != IG_RESOLUTION_NO_ABS)
    {
    if (nUnits == IG_RESOLUTION_METERS)
        {
        /*convert from meters to inches*/
        xResNumerator = XResNumerator * 39.37;
        xResDenominator = XResDenominator * 39.37;
        yResNumerator = YResNumerator * 39.37;
        yResDenominator = YResDenominator * 39.37;
        }
    else if
        (nUnits == IG_RESOLUTION_CENTIMETERS)
        {
            /*convert from centimeters to inches*/
            xResNumerator = XResNumerator * 0.3937;
            xResDenominator = XResDenominator * 0.3937;
            yResNumerator = YResNumerator * 0.3937;
            yResDenominator = YResDenominator * 0.3937;
        }
    }
nUnits = IG_RESOLUTION_INCHES;
nErrcount = IG_image_resolution_set(hIGear, xResNumerator,
xResDenominator, yResNumerator, yResDenominator, nUnits);

Sample: COLOR, MULTPAGE, PRINT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_image_resolution_set

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_image_resolution_set(
    HIGEAR hIGear,
    LONG xResNumerator,
    LONG xResDenominator,
    LONG yResNumerator,
    LONG yResDenominator,
    AT_MODE nUnits
);

Arguments:

hIGear
HIGEAR handle to the image
XResNumerator
A variable of type LONG for setting the numerator of the x resolution of an image
XResDenominator
A variable of type LONG for setting the denominator of the y resolution of an image
YResNumerator
A variable of type LONG for setting the numerator of the y resolution of an image
YResDenominator
A variable of type LONG for setting the denominator of the y resolution of an image
nUnits
A constant of type AT_MODE, that sets the units of resolution for the image. Choices include:
  • IG_RESOLUTION_NO_ABS = No Absolute Units
  • IG_RESOLUTION_METERS = Pels Per Meter
  • IG_RESOLUTION_INCHES = Dots Per Inch
  • IG_RESOLUTION_CENTIMETERS = Pixels Per cm
  • IG_RESOLUTION_10_INCHES = Pixels Per 10 inches *
  • IG_RESOLUTION_10_CENTIMETERS = Pixels Per 10 cm*

* used by MO:DCA and IOCA.

Description:

This function is used to set and store the resolution of the image referenced by hIGear. The resolution settings will be made to both the HIGEAR and the DIB. For the HIGEAR, the values are saved as numerators and denominators for better precision (details below). In addition, ImageGear will also store the units of resolution to the HIGEAR, in nUnits. This allows the flexibility of storing any one of the different methods of resolution measurement listed above. Because the DIB specification requires that resolution be stored as pels-per-meter, the values will be converted to pels-per-meter and stored directly to the DIB's XPelsPerMeter and YPelsPerMeter fields.

To make a conversion, you can use the appropriate conversion formula:

  • pels per meter = 0.0254 * dots per inch
  • dots per inch = 39.37 * pels per meter

To convert from DPI to PPM or PPM to DPI, you may call IG_convert_DPI_to_PPM () and IG_convert_PPM_to_DPI ().

When an image is saved to a file the resolution values in the HIGEAR are used, not the values in the DIB. They will be converted when necessary to match the units specified by the file format.

To maintain the original precision of the resolution obtained from the image file the resolutions are stored as numerator and denominator. This is the method used by several image file formats as a method of avoiding the IEEE specifications for double and float. To set the X resolution of the image to 300 DPI the numerator can be 300 and the denominator 1 (900 and 3 would also work).

The ratio of the image resolutions (X and Y) is used by ImageGear when printing the image. Changing these values does not alter the number of pixels or colors in the actual image in any way. The resolution values are for informational and printing purposes only.

NOTE: To resize or crop an image see IG_IP_resize() and IG_IP_crop().
NOTE: The settings of the resolution directly affect the output of any of the IG_dspl_..._print... functions.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See the example under IG_image_resolution_get ()function.

Sample: COLOR, PRINT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_info_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_info_get (
    LPSTR lpszFileName,
    LPAT_MODE lpFileType,
    LPAT_MODE lpCompression,
    LPAT_DIB lpDIB
);

Arguments:

lpszFileName
Name of file about which to get information
lpFileType
Far pointer to an AT_MODE variable in which file type, such as IG_FORMAT_BMP, will be returned
lpCompression
Far pointer to an AT_MODE variable in which compression type, such as IG_COMPRESSION_RLE, will be returned
lpDIB
Far pointer to an AT_DIB struct to which will be returned other file information such as width, height, and Bits Per Pixel

Description:

This function obtains information about the named file without actually loading the file. The file is opened and the header is inspected. The file must exist.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

AT_MODE nFileType; /* Will receive an IG_FORMAT_ constant */
AT_MODE nCompression;/* Will receive an IG_COMPRESSION_
constant*/
AT_DIB dibInfoDIB;/* Will receive copy of the
BITMAPINFOHEADER*/
AT_ERRCOUNT nErrcount; /* Returned count of errors */
nErrcount = IG_info_get ( "picture.bmp", &nFileType,
&nCompression, &dibInfoDIB );

Sample: MEMIO, MFC, SHARED, Vector, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_info_get_ex

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_info_get_ex (
    const LPSTR lpszFileName,
    UINT nPageNumber,
    LPAT_MODE lpFileType,
    LPAT_MODE lpCompression,
    HIGDIBINFO *lphDIB
);

Arguments:

lpszFileName
Name of file about which to get information
nPageNumber
Page number to get info about if this is a multi-page (multi-image) file. Note that page numbers begin at 1, not 0. Set nPageNumber to 1, if this is not a multi-page file.
lpFileType
Far pointer to an AT_MODE variable in which file type, such as IG_FORMAT_BMP, will be returned
lpCompression
Far pointer to an AT_MODE variable in which compression type, such as IG_COMPRESSION_RLE, will be returned
lphDIB
Far pointer to an HIGDIBINFO struct to which will be returned other file information such as width, height, and Bits Per Pixel

Description:

This function obtains information about the page specified by nPageNumber argument without actually loading the named file. The file is opened and the header is inspected. The file must exist.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

INT nPageNumber
AT_MODE nFileType;  /* Will receive an IG_FORMAT_ constant    */
AT_MODE nCompression;/* Will receive an IG_COMPRESSION_
constant*/
HIGDIBINFO dibhInfoDIB;
AT_ERRCOUNT nErrcount;     /* Returned count of errors */
nErrcount = IG_info_get_ex ( "picture.bmp", 2, &nFileType,
&nCompression, &dibhInfoDIB );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_info_get_FD_ex

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_info_get_FD_ex (
    AT_INT fd,
    LONG lOffset,
    UINT nPage,
    LPAT_MODE lpFileType,
    LPAT_MODE lpCompression,
    HIGDIBINFO *lphDIB
);

Arguments:

fd
File Descriptor handle
lOffset
Offset within file at which the file image begins
nPage
Page number about which to get information, if a multi-page file set to 1 or greater; for a non-multi-page file set to 1.
lpFileType
Far pointer to an AT_MODE variable in which file type, such as IG_FORMAT_BMP, will be returned
lpCompression
Far pointer to an AT_MODE variable in which compression type, such as IG_COMPRESSION_RLE, will be returned
lphDIB
Far pointer to an HIGDIBINFO struct to which will be returned other file information such as width, height, and Bits Per Pixel

Description:

This function obtains information about a file that is already open and whose File Descriptor handle (fd) you have.

NOTE: See also IG_info_get_ex().

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

INT fd      /* File Descriptor handle */
AT_MODE nFileType;  /* Will receive an IG_FORMAT_ constant */
AT_MODE nCompression; /* Will receive an IG_COMPRESSION_
constant */
HIGDIBINFO dibhInfoDIB;
AT_ERRCOUNT nErrcount;  /* Returned count of errors  */
nErrcount = IG_info_get_FD ( fd, 0, 0, &nFileType,
&nCompression, &dibhInfoDIB );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_info_get_mem_ex

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_info_get_mem_ex (
    VOID FAR32 lpImage32,
    AT_UINT dwSize,
    UINT nPage,
    LPAT_MODE lpFileType,
    LPAT_MODE lpCompression,
    HIGDIBINFO *lphDIB
);

Arguments:

lpImage32
Far pointer to start of file image in memory
dwSize
Size of image in memory.
nPage
Page number about which to get information, if a multi page file set to 1 or greater; for a non multi page file set to 1.
lpFileType
Far pointer to an AT_MODE variable in which file type, such as IG_FORMAT_BMP, will be returned.
lpCompression
Far pointer to an AT_MODE variable in which compression type, such as IG_COMPRESSION_RLE, will be returned
lphDIB
Far pointer to an HIGDIBINFO struct to which will be returned other file information such as width, height, and Bits Per Pixel

Description:

This function obtains information about a file whose image is in memory beginning at location *lpImage.

NOTE: See also IG_info_get_FD_ex() and IG_info_get_ex()functions.

Bits Per Pixel: 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

VOID FAR * lpMemImage32;  /* Pointer to in-memory image of file
*/
AT_UINT dwImageSize;   /* Size of image in memory */
AT_MODE nFileType; /* Will receive an IG_FORMAT_ constant  */
AT_MODE lpCompression;  /* Will receive an IG_COMPRESSION_
constant */
HIGDIBINFO dibhInfoDIB;
AT_ERRCOUNT nErrcount; /* Returned count of errors  */
nErrcount = IG_info_get_mem ( lpMemImage32, dwImageSize, 0,
&nFileType, &nCompression, dibhInfoDIB );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_add_tilt

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_add_tilt(
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    AT_DOUBLE dSlopeX,
    AT_DOUBLE dSlopeY
);

Arguments:

hIGear
HIGEAR handle of image to be processed
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image. Before ImageGear performs this operation it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
dSlopeX
Specify the slope of the plane in X direction, and must be given in units per pixel.
dSlopeY
Specify the slope of the plane in X direction, and must be given in units per pixel.

Description:

This function adds a specified plane to the input image to correct for a tilt in the image luminance. The plane has X and Y zero crossing at the center of the input image with dSlopeX and dSlopeY as specified in the arguments.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Bits Per Pixel:

8, 16, or 32bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	hIGear; 	/* HIGEAR handle of image */
AT_RECT lpRect; 	/* rectangle to process */
AT_DOUBLE dSlopeX, dSlopeY;
...
IG_IP_add_tilt( hIGear, lpRect, dSlopeX, dSlopeY);
...

Sample:

IMG_PROC


IG_IP_alpha_create

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_alpha_create(
    HIGEAR hIGear,
    HIGEAR hIBackgrnd,
    AT_MODE nCreateMode,
    LPHIGEAR lphAlpha
);

Arguments:

hIGear
HIGEAR handle of image
hIBackgrnd
HIGEAR handle to a background image
nCreateMode
An integer value of type AT_MODE that tells ImageGear what bit depth the alpha channel should have. The possible settings for this variable, which are defined in accucnst.h are:
IG_ALPHA_CREATE_1 and IG_ALPHA_CREATE_8.
lphAlpha
Far pointer to the newly created alpha channel.

Description:

This new function creates alpha channel. The difference from function IG_image_create_alpha () is that newly created alpha channel is not associated with any HIGEAR - it's only created and returned via last parameter lphAlpha. Other parameters have the same meaning as those of IG_image_create_alpha().

See also the section ImageGear Alpha Channel Support.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_area_info_get

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_area_info_get(
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    HIGPIXEL lpPixel,
    AT_MODE channel,
    AT_MODE	info
);

Arguments:

hIGear
Image to get pixel block from
lpRect
Rectangle to get info from (NULL for the whole image)
lpPixel
Block of memory to receive pixels
channel
IG_COLOR_COMP_
info
IG_DIB_AREA_INFO_

Description:

This function provides the info about the rectangle area of the image.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_arithmetic

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_arithmetic (
    HIGEAR hIGearDest,
    HIGEAR hIGearOp2,
    AT_MODE nOperation
);

Arguments:

hIGearDest
HIGEAR handle of Operand 1, also the destination of the operation
hIGearOp2
HIGEAR handle of Operand 2
nOperation
An integer constant of type AT_MODE which tells which kind of arithmetic operation to perform on the intersecting pixels of the two images. See accucnst.h or the description of IG_clipboard_paste_op_set () for the full list of constants available.

Description:

This function performs the arithmetic or logical operation specified by nOperation, on each corresponding pair of pixels in hIGearDest and hIGearOp2. The result is stored in hIGearDest. The two images must be the same width and height. If you would like to set an image rectangle within which to perform your operations, see IG_IP_arithmetic_rect ().

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;  /* Handle of image that will change */
HIGEAR hIGearOther;  /* Handle of image 2 */
AT_ERRCOUNT nErrcount;   /* Returned count of errors */
/* Image 1 Pixel =  Image 1 Pixel  |  Image 2 Pixel */
nErrcount = IG_IP_arithmetic ( hIGear, hIGearOther, IG_ARITH_OR
);

Sample: IMG_PROC, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_arithmetic_rect

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_arithmetic_rect (
    HIGEAR hIGear1,
    HIGEAR hIGear2,
    LPAT_RECT lpImageRect2,
    AT_MODE nOperation
);

Arguments:

hIGear1
HIGEAR handle of image 1, which is the destination image.
hIGear2
HIGEAR handle of image 2, the images must have be of the same height and width.
lpImageRect2
A long pointer to a set of rectangle coordinates of type AT_RECT, which will define the region of image 1 to apply the arithmetic operation to. Set to NULL for the whole image.
nOperation
An integer constant of type AT_MODE which tells which kind of arithmetic operation to perform on the intersecting pixels of the two images. See accucnst.h or the description of IG_clipboard_paste_op_set () function for the full list of constants available.

Description:

This function performs in the same way that IG_IP_arithmetic () does, except that you can specify a rectangular region of hIGear1 to perform the pixel operation on.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR	 	hIGear1;     /* HIGEAR Handle of image 1     */
HIGEAR hIGear2;     /* HIGEAR Handle of image 2     */
AT_ERRCOUNT nErrcount;   /* Returned count of IG errors on the
stack */
AT_DIMENSION  nWidth, nHeight;  /* Height and width of image */
AT_RECT rcRectOf1;   /* selected rectangle from image 1  */
UINT  nBpp;       /* bits per pixel of image        */
/* Get dimensions of hIGear1, so can use width and height values
below  */
nErrcount = IG_image_dimensions_get( hIGear1, &nWidth,
&nHeight, &nBpp );
/*Use the bottom ½ of hIGear1 for arithmetic operations
*/
rcRectOf1.left = 0;
rcRectOf1.top = nHeight/2;
rcRectOf1.right = nWidth - 1;
rcRectOf1.bottom = nHeight - 1;
nErrcount = IG_IP_arithmetic_rect( hIGear1, hIGear2,
&rcRectOf1, IG_ARITH_ADD);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_blend_percent

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_blend_percent (
    HIGEAR hIGearDest,
    const HIGEAR hIGear2,
    const DOUBLE dblPctOfImage2,
    const AT_MODE nColorChannel,
    const LPAT_RECT lpRect
);

Arguments:

hIGearDest
HIGEAR handle of the image to be blended into
hIGear2
HIGEAR handle of image to blend in, must be same size and bit depth
dblPctOfImage2
Percent of image 2 to be in the blend (the percent of image 1 will be 100.0 minus this). 0 means all of image 1; 50 means half and half, and 100 means all of image 2. The range of values is 0.0 to 100.0
nColorChannel
A constant such as IG_COLOR_COMP_R, _G, _B, or _RGB, specifying which color(s) to blend
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to operate on. lpRect = NULL means the entire image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non- rectangular ROI defined by the mask.

Description:

This function will blend the second image into the first. Use lprect to set a rectangular portion of the first image to be processed. dblPctOfImage2 specifies the percent of each image to be used in the result. The image in hIGearDest is destroyed and is replaced with the resulting blend. The percentage ranges from 0 to 100. A zero results in 0% hIGearDest and 100% hIGear2. A value of 50% results in an image which is created ½ of each image. A value of 100% creates an image that is 100% hIGear2 and 0% hIGearDest. The images must be the same width, height, and bit depth. nColorChannel lets you specify that only one color of a 24-bit image is to be blended in.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear1;      /* Handle of image1 that will change  */
HIGEAR hIGear2;     /* Handle of image2      */
AT_ERRCOUNT nErrcount;  /* Returned count of errors  */
AT_DIMENSION nWidth, nHeight;  /* Width & Height of Image1
*/
UINT nBpp;     /* Bits per pixel    */
AT_RECT rcRectOf1;   /* selected rectangle from image1  */
/* Get dimensions of hIGear1, so can use width and height values
below */
nErrcount = IG_image_dimensions_get( hIGear1, &nWidth,
&nHeight, &nBpp );
/*Use the bottom ½ of Image1 */
rcRectOf1.left = 0;
rcRectOf1.top = nHeight/2;
rcRectOf1.right = nWidth - 1;
rcRectOf1.bottom = nHeight - 1;
/* If 24-bit image, blend all color channels (else blend pixels)
*/
nErrcount = IG_IP_blend_percent ( hIGear1, hIGear2,
20.0,IG_COLOR_COMP_RGB, &rcRectOf1 );

Sample: IMG_PROC, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_blend_with_alpha

Group: Image Processing
NOTE: This function is no longer supported. Please use IG_image_blend_with_alpha instead.

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_blend_with_alpha (
    HIGEAR hIGear1,
    UINT nFAIndex
    HIGEAR hIGear2,
    UINT nSAIndex
    HIGEAR hIBackgrnd,
    LPAT_RECT lpRect,
    AT_MODE nBlendMode
);

Arguments:

hIGear1
HIGEAR handle of first image
nFAIndex
Not used.
hIGear2
HIGEAR handle of second image
nSAIndex
Not used.
hIBackgrnd
HIGEAR handle of background image
lpRect
A long pointer to a structure of type AT_RECT which tells which rectangular subregion of hIGear1 will have blending applied to it. Set to NULL for whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non- rectangular ROI defined by the mask.
nBlendMode
An integer of type AT_MODE which is used to set which type of blending should be used. These are defined in accucnst.h and are shown below with their formulas.

Description:

This function is no longer supported. Please use IG_image_blend_with_alpha instead. It has much simpler API, but still provides the necessary functionality for blending images containing Alpha channels.

IG_IP_blend_with_alpha function blends two images, hIGear1 and hIGear2, using both their pixel data, their alpha channel data (if they have any), and a background image. The changes are made to the pixel data of hIGear1. All three images: hIGear1, hIGear2, and hIBackgrnd must have the same width and height. hIGear2 and hIBackgrnd may be NULL. hIGear1 should not be NULL.

The images hIGear1 and hIGear2 will be blended equally, and any areas that are not covered by either image will show through to the background image. If hIGear1 has a lower bit depth than hIGear2, it will automatically be promoted to the bit depth so that the resultant image has the higher bit depth.

Below are the possible settings for nBlendMode. With each setting, there is a brief description of what this blend mode will do, and also the formula that is used for calculating the new pixel values of hIGear1, where. Please use the following key for the formulas:

  • I1 = hIGear1
  • I2 = hIGear2
  • Back = hIBackgrnd
  • A1 = alpha channel of the first image
  • A2 = alpha channel of the second image
  • IG_BLEND_OVER: Blend first image over the second image:
I1 = (Back*(1-A1)*(1-A2)) + (I1*A1) + (I2*(1-A1)*A2)
  • IG_BLEND_IN: Blend the first image into the second image
I1 = (Back*(1-A1)*(1-A2)) + (I1*A1*A2) + (I2*(1-A1)*A2)
  • IG_HELD_OUT: The first image is held out by the second image.
I1 = (Back*(1-A1)*(1-A2)) + (I1*A1*(1-A2)) + (I2*A2)
  • IG_BLEND_LINEAR: The first and second images are combined in a linear fashion.
I1 = ((Back*(1-A1)*(1-A2)) + (I1*A1) + (I2*A2)/(1+A2*A1)

Exceptions:

  • if I2 ==NULL is it replaced with 0
  • if A1==NULL it is replaced with 1
  • if A2==NULL it is replaced with 0
  • if Back==NULL it is replaced with 0.
NOTE: The values contained in the alpha channel will be mapped to a float value between 0 and 1, where 1 is equivalent to 100%. 100% means that the pixel will be fully transparent, and 0% means that the pixel will be fully opaque. All values in between (0.1 - 0.99) will represent varying degrees of transparency. If it is an 8-bit alpha channel, the value 255 will be mapped to 1, or 100%.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument so that you can blend a rectangular subregion of hIGear1. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.
NOTE: See also IG_image_create_alpha().

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear1, hIGear2,      /* HIGEAR handle of image */
        hIBackgrnd;
AT_ERRCOUNT  nErrcount;      /* tally of IG errors on the stack
*/
AT_RECT rcRectOf1;      /* selected rectangle from image 1 */
nErrcount = IG_IP_blend_with_alpha (hIGear1, hIGear2,
hIBackgrnd, &rcRectOf1, IG_BLEND_OVER);

Sample: IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_blend_with_LUT

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_blend_with_LUT (
    HIGEAR hIGearDest,
    HIGEAR hIGear2,
    const LPAT_LUT lpLUT_red,
    const LPAT_LUT lpLUT_green,
    LPAT_LUT lpLUT_blue,
    const LPAT_RECT lpRect
);

Arguments:

hIGearDest
HIGEAR handle of the image to be blended into
hIGear2
HIGEAR handle of image to blend in, must be same size and bit depth
lpLUT_red
Far pointer to Red channel of LUT for 24-bit image; also used as single pointer to LUT of a grayscale image with a bit depth of 8.
lpLUT_green
Far pointer to Green channel of LUT for 24-bit image; not used for 8-bit images
lpLUT_blue
Far pointer to Blue channel of LUT of 24-bit image; not user for 8-bit images
lpRect
Rectangular portion of the image to process. Set to NULL for the whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.

Description:

This function blends two images using Look-Up Tables (LUTs) to determine the strength of each pixel's contribution. The pixel values from hIGearDest are used as the indexes into the LUTs. Both hIGear2 and hIGearDest must be the same bit depth and dimensions. The image in hIGearDest is destroyed and is replaced with the resulting blend.

For 24-bit images, each channel (R, G, or B) of the hIGearDest image are processed through their own LUT. For 8-bit images, the lpLUT_red is used and the other two are ignored (you can pass in NULL for these). Each LUT that is to be used must point to an 8-bit LUT that has at least enough entries to process the images being passed in. A 24-bit blend requires 3 LUTs, each having 256 entries. (All three pointers can point to the same LUT.) An 8-bit gray level blend requires a single LUT (lpLUT_red) of 256 entries.

Each entry into the LUT determines the percentage of the blend on a pixel-by-pixel basis. Pixel values of the hIGearDest image are used as indexes into the array. The LUTs should be initialized with values from 0 to 100, where:

  • 0 = 0 % hIGearDest, 100% hIGear2
  • 50 = 50% of hIGearDest and 50% of hIGear2
  • 100 = 100% hIGearDest and 0 % hIGear2

For 8-bit images, the value of each pixel in hIGearDest is used as the index into the LUT. For 24-bit images, it is the intensity (R+G+B)/3 that is used.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. (See above.) However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGearDest    /* HIGEAR handle of image 1, destination */
         hIGear2;   /* HIGEAR handle of image 2    */
AT_LUT LUT_blend[256];   /* The LUT for blend values */
INT pix;            /* Loop index, = pixel value  */
AT_ERRCOUNT nErrcount;     /* Returned count of errors   */
for ( pix = 0;  pix < 256;  pix++ )
    { LUTblend[pix] =  25; }    /* set Look Up Table   */
for (pix = 10; pix < 100; pix++)
    { LUTblend[pix] = 75; }
nErrcount =  IG_IP_blend_with_LUT ( hIGearDest, hIGear2,
(LPAT_LUT)&LUT_blend,
    (LPAT_LUT)&LUT_blend, (LPAT_LUT)&LUT_blend, NULL );

Sample: IMG_PROC, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_close

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_close(
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    LPAT_INT lpMatrix,
    AT_INT nMatrixSize
);

Parameters:

hIGear
Image to apply effect to.
lpRect
Image rectangle to process.
lpMatrix
Matrix specifying a structuring element for the operation
nMatrixSize
Matrix edge size.

Description:

This method applies closing effect to provided raster page using the specified structure element. This method is applicable to any grayscale image (image with [Gy] color space).

Applicability:

1-bit and 8-bit grayscale

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_color_combine_ex

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_combine_ex (
    LPHIGEAR lphIGear_result,
    HIGEAR hIGear1,
    HIGEAR hIGear2,
    HIGEAR hIGear3,
    HIGEAR hIGear4,
    AT_MODE color_space,
    AT_MODE dst_color_space
);

Arguments:

lphIGear_result
Far pointer to an object of type HIGEAR, to receive the HIGEAR handle of the created 24- bit image
hIGear1
HIGEAR handle of input image to be treated as channel 1
hIGear2
HIGEAR handle of input image to be treated as channel 2
hIGear3
HIGEAR handle of input image to be treated as channel 3
hIGear4
HIGEAR handle of input image to be treated as channel 4
nColorSpace
A constant such as IG_COLOR_SPACE_RGB describing how the channels are to be merged
dst_color_space
tells what color space output HIGEAR should have. There are 2 possible values now: RGB and CMYK.

Description:

This function is an upgrade to IG_IP_color_combine(). While support for IG_IP_color_combine() will always be maintained, it is recommended that you use this newer function. The additional benefit of this function is that it allows you to choose a color space for the destination image. For example, you can choose to store your destination image using the CMYK color scheme. As of this writing, the dst_color_space parameter can take one of the following constants as its setting: IG_COLOR_SPACE_RGB and IG_COLOR_SPACE_CMYK. In order to set it to CMYK, you must be sure that you first call IG_color_space_level_set () function with settings of IG_COLOR_SPACE_CMYK and IG_FULL_SUPPORT.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: COLOR

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_color_convert

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_convert(
    [IN] HIGEAR hIGear,
    [IN] AT_MODE nColorSpace
);

Arguments:

hIGear
The ImageGear handle of an image.
nColorSpace
The identifier of destination color space where to convert.

Description:

This function converts an image from one internal format to another depending on the parameter, nColorSpace. This parameter must be a color space listed in enumIGColorSpaces, which is defined in accucnst.h.

Commonly used values for nColorSpace are:

  • IG_COLOR_SPACE_CMYK
  • IG_COLOR_SPACE_RGB

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    /* HIGEAR handle of image  */
. . .
IG_IP_color_convert( hIGear, IG_COLOR_SPACE_CMYK );
. . .

Sample: COLOR

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_color_count_get

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_count_get(
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    LPAT_INT lpCount
);

Arguments:

hIGear
Image whose count colors are to be counted
lpRect
Rectangle in which to count colors (NULL for the whole image)
lpCount
Pointer to AT_INT to receive number of colors

Description:

This function counts the number of unique colors in the specified rectangular area of the image.

Applicability:

ALL

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

PIX_ACC


IG_IP_color_promote

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_promote (
    HIGEAR hIGear,
    AT_MODE nPromoteTo
);

Arguments:

hIGear
HIGEAR handle of image
nPromoteTo
One of these options:
IG_PROMOTE_TO_4
IG_PROMOTE_TO_8
IG_PROMOTE_TO_24
IG_PROMOTE_TO_32

Description:

This function will promote an image to the common bit depths of 4, 8, 24, or 32 bits per pixel. Promotion to 4 or 8bpp produces an image in the indexed color space, 24bpp in RGB color space, and 32 in CMYK color space. The color space of the source image will be converted if necessary.

The width and height of the image are not changed. Only the number of Bits Per Pixel are increased. Colors are not changed. The same color is used for each new pixel as was used in the original.

When promoting to 24-bit, levels of gray and white may appear to be slightly colored when displayed. This is due to using a common 8-bit palette to display a 24-bit color image. The actual 24-bit pixel values are correct.

Applicability: All (with input bit depth less than output bit depth)

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    /* HIGEAR handle of 1,4, or 8 bit image */
/* Make it a 24 bit image: */
IG_IP_color_promote ( hIGear, IG_PROMOTE_TO_24 );

Sample: TIMING, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_color_reduce_bayer

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_reduce_bayer (
    HIGEAR hIGear,
    UINT nToBits,
    LPAT_RGBQUAD lpPalette
);

Arguments:

hIGear
HIGEAR handle of image to reduce bit depth of
nToBits
Number of bits per pixel after reduction (4 or 1)
lpPalette
This argument is currently not used

Description:

This function reduces the image to a fewer number of Bits Per Pixel, using a Bayer dithering algorithm. The target bit depth is specified by argument nToBits. In general, a color image will be reduced to a fewer number of colors, and a grayscale image will be reduced to a fewer number of shades of gray. Note that setting nToBits = 1 will reduce the image to monochrome or black-and-white.

The input number of Bits Per Pixel must be greater than nToBits, or an error will result.

NOTE: See also the section in entitled Color Reduction.

Applicability: 4bpp indexed, 8bpp indexed, 8bpp grayscale, 24bpp RGB

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* HIGEAR handle of 4, 8, or 24 bit image */
/* Reduce image to 1-bit black-and-white: */
IG_IP_color_reduce_bayer ( hIGear, 1, NULL );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_color_reduce_diffuse

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_reduce_diffuse (
    HIGEAR hIGear,
    UINT nToBits,
    INT level,
    LPAT_RGBQUAD lpPalette
);

Arguments:

hIGear
HIGEAR handle of image to reduce bit depth of
nToBits
Number of bits per pixel after reduction, 1 or 4
nLevel
Threshold value for dithering, 0 to 255
lpPalette
This argument is currently not used

Description:

This function reduces the image to a fewer number of Bits Per Pixel. The target bit depth is specified by argument nToBits. In general, a color image will be reduced to a fewer number of colors, and a grayscale image will be reduced to a fewer number of shades of gray. Note that setting nToBits = 1 will reduce the image to monochrome or black-and-white.

nLevel sets a threshold value for the target image. nLevel = 128 means that black and white in the target image will be in equal proportion. nLevel greater than 128 would mean more bright than dark, nLevel less than 128 would mean more dark than bright.

The input number of Bits Per Pixel must be greater than nToBits, or an error will result.

NOTE: See also section in entitled Color Reduction.

Applicability: 4bpp indexed, 8bpp indexed, 24bpp RGB

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;   /* HIGEAR handle of 4, 8, or 24 bit image */
/* Reduce image to 1-bit black-and-white: */
IG_IP_color_reduce_diffuse ( hIGear, 1, 128, NULL );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_color_reduce_halftone

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_reduce_halftone (
    HIGEAR hIGear,
    AT_MODE nOption
);

Arguments:

hIGear
HIGEAR handle of image
nOption
halftoning pattern - 0 for now (squares)

Description:

This function reduces a color or grayscale image to a 1 bit per pixel image suitable for use in half-toning. The resulting image will consist of small squares of varying sizes that will give the appearance of varying shades of gray.

NOTE: See also the section in entitled Color Reduction.

Applicability: 4bpp indexed, 8bpp indexed, 24bpp RGB

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    /* HIGEAR handle of 4, 8, or 24 bit image */
/* Reduce to a 1-bit halftone image: */
IG_IP_color_reduce_halftone ( hIGear, 0 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_color_reduce_median_cut

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_reduce_median_cut (
    HIGEAR hIGear,
    BOOL bFastRemap,
    UINT nMaxColors
);

Arguments:

hIGear
HIGEAR handle of image
bFastRemap
Set = TRUE for reduction algorithm optimized for speed. Set = FALSE for algorithm optimized for quality
nMaxColors
The maximum number of colors (that is, maximum number of unique pixel values) you want in the resulting image. Must be 16 to 256.

Description:

This function reduces an image by dividing it into nMaxColors equal-sized squares. The colors of the pixels in each square will be averaged to produce a resulting color. The resulting image will contain only these colors.

NOTE: See also section in entitled Color Reduction.

Applicability: 24bpp RGB

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* HIGEAR handle of image */
/* Reduce to 64 colors using median cut algorithm */
IG_IP_color_reduce_median_cut ( hIGear, FALSE, 64 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_color_reduce_octree

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_reduce_octree (
    HIGEAR hIGear,
    BOOL bFastRemap,
    UINT nMaxColors,
    const UINT nPaletteSize,
    const LPAT_RGB lpPalette
);

Arguments:

hIGear
HIGEAR handle of image
bFastRemap
Set = TRUE for reduction algorithm optimized for speed. Set = FALSE for algorithm optimized for quality
nMaxColors
The maximum number of colors (that is, maximum number of unique pixel values) you want in the resulting image. If you set this to > 16, the resulting image will be an 8-bit. Valid values are 8 - 256. If you pass in a value out of this range, ImageGear will set the value to either 8 or 256. See description below for details.
nPaletteSize
Number of entries in palette lpPalette that will be used by ImageGear during reduction. This should be >= nMaxColors. Setting this to 0, and setting lpPalette to NULL will have ImageGear make an optimized palette for you.
lpPalette
LONG pointer to an array of palette entries, where the number of entries = nPaletteSize. Set to NULL if you want ImageGear to make an optimized palette for you.

Description:

This function reduces a 24-bit or 8-bit image to an 8-bit or 4-bit image, having the number of colors specified by nMaxColors. If you set nPaletteSize > 0 and supply an address to lpPalette, ImageGear will use your palette. If you set either nPaletteSize = 0 or lpPalette to NULL, ImageGear will build an optimized palette for you. If you set nMaxColors > 16, then an 8-bit image will always result. Setting nMaxColors <=16 will result in a 4-bit image. You may not specify less than 8 colors.

nPaletteSize should be set to >= nMaxColors. If nPaletteSize is set to 0, ImageGear will build an optimal palette and lpPalette will be unused. The table below demonstrates some sample cases of 8 and 24-bit images being reduced, using the setting of nMaxColors (middle column). The right-most column shows the number of Bits Per Pixel that the resulting image will have.

Table 3. Octree Bit Depths In and Out

Bpp of orig.
HIGEAR
# of resulting colors
Bpp reduced image
24
17-256
8
24
8-16
4
24
16
4
8
17-256
8
8
8-16
4
8
6
*

.

*Not possible, nMaxColors will be changed to 8

NOTE: See also the section in entitled Color Reduction.

Applicability: 8bpp indexed, 24bpp RGB

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;   /* HIGEAR handle of image   */
AT_RGB rgbPalette[64];  /* Pointer to image's palette */
AT_ERRCOUNT   nErrcount;    /* Tally of ImageGear errors on
stack*/
/* Reduce image to 64 colors using given palette */
nErrcount = IG_IP_color_reduce_octree (hIGear, FALSE, 64, 64,
rgbPalette);
/* Reduce image to 64 colors, having ImageGear build optimal
palette  */
nErrcount = IG_IP_color_reduce_octree (hIGear, FALSE, 64, 0,
NULL);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_color_reduce_popularity

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_reduce_popularity (
    HIGEAR hIGear,
    BOOL bFastRemap,
    UINT nMaxColors
);

Arguments:

hIGear
HIGEAR handle of image
bFastRemap
Set = TRUE for reduction algorithm optimized for speed. Set = FALSE for algorithm optimized for quality
nMaxColors
Number of colors to reduce to

Description:

This function reduces a 24-bit image to an 8-bit image while retaining its most popular, or prevalent, colors. Use nMaxColors to specify the maximum number of colors wanted in the result.

NOTE: See also the section in entitled Color Reduction.

Applicability: 24bpp RGB

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* HIGEAR handle of image */
/* Reduce to 64 colors using octree algorithm   */
IG_IP_color_reduce_popularity ( hIGear, FALSE, 64 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_color_reduce_to_bitonal

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_reduce_to_bitonal(
    HIGEAR hIGear,
    const AT_MODE nOption,
    const UINT nThreshold,
    UINT nWeight1,
    UINT nWeight2,
    UINT nWeight3
);

Arguments:

hIGear
HIGEAR handle of image
nOption
A constant of type AT_MODE, such as IG_REDUCE_BITONAL_AVE, that specifies what type of reduction to perform. See accucnst.h for the complete list.
nThreshold
An integer value that specifies which pixel values will be changed to black, and which pixel values will be changed to white. Pixels with values greater than nThreshold will be changed to white, and pixels that have values less than nThreshold will be changed to black.
nWeight1
These values are only used if nOption is set to IG_REDUCE_BITONAL_WEIGHTED. The range of values is 0 - 255. The default values are 255.
nWeight2
The range of values is 0 - 255. The default values are 255.
nWeight3
The range of values is 0 - 255. The default values are 255.

Description:

This function reduces the hIGear image from 24, 8, or 4 bpp to 1 bpp. Set nOption to specify how to get the threshold value. If you set nOption to IG_REDUCE_BITONAL_WEIGHTED, you may also set the values of nWeight1, nWeight2, and nWeight3. These "weights" are used to determine how much influence the values of the red, green, or blue pixels will have on the reduction. For example, if nWeight1 (red) = 255, nWeight2 (green) = 0, nWeight3 (blue) = 0, the whole reduction will depend on the value of the red pixels. The green and blue pixel values will have "no weight."

IG_REDUCE_BITONAL_GRAYSCALE gives the most weight to the value of green. This optimizes for the perception of the human eye, in which blue is the hardest color to see, and therefore requires the least weight.

IG_REDUCE_BITONAL_AVE gives equal weight to all three pixel values.

Here are the formulas used by the three different reduction methods:

  • IG_REDUCE_BITONAL_GRAYSCALE: value = (red*77 + green*151 + blue*28)/256;
  • IG_REDUCE_BITONAL_AVE: value = (red + green + blue)/3;
  • IG_REDUCE_BITONAL_WEIGHTED: value = (red*w1 + green*w2 + blue*w3)/(w1 + w2 + w3);

Use the nThreshold argument to set the threshold value for converting pixels to black or white. If the value, as calculated by one of the above reduction methods, is less than nThreshold, the pixels will be set to black; if it is greater or equal to nThreshold, the pixels will be set to white.

NOTE: See also the section in entitled Color Reduction.

Applicability: 4bpp indexed, 8bpp indexed, 8bpp grayscale, 24bpp RGB

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear,      /* HIGEAR handle of input image   */
AT_ERRCOUNT nErrcount;   /* Returned count of errors  */
nErrcount = IG_IP_color_reduce_to_bitonal ( hIGear,
IG_REDUCE_BITONAL_AVE, 100, 0, 0, 0 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_color_separate

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_color_separate (
    HIGEAR hIGearOrig,
    LPHIGEAR lphIGear1,
    LPHIGEAR lphIGear2,
    LPHIGEAR lphIGear3,
    LPHIGEAR lphIGear4,
    AT_MODE nColorSpace
);

Arguments:

hIGearOrig
HIGEAR handle of the original image to be separated.
lphIGear1
Far pointer to an object of type HIGEAR to receive the handle of the separated channel 1 image.
lphIGear2
Far pointer to receive handle of channel 2 image.
lphIGear3
Far pointer to receive handle of channel 3 image.
lphIGear4
Far pointer to receive handle of channel 4 image.
nColorSpace
A constant such as IG_COLOR_SPACE_RGB or IG_COLOR_SPACE_CMYK describing how the individual channels are to be separated or extracted.

Description:

This function is the reverse of IG_IP_color_combine_ex (). See the description of that function. Each of the output images created by this function (lphIGear1, etc.) will be grayscale. That is, each will have a grayscale palette. The pixel values will be those obtained from the input image.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear,    /* HIGEAR handle of input image  */
 hIGearRed, /* Handle of Red output image,   */
 hIGearGreen, hIGearBlue,   /* Green, Blue output images */
 hIGearNULL;    /* (Not used when IG_COLOR_SPACE_RGB)   */
AT_ERRCOUNT nErrcount;  /* Returned count of errors */
nErrcount = IG_IP_color_separate ( hIGear, &hIGearRed,
&hIGearGreen, &hIGearBlue, &hIGearNull, IG_COLOR_SPACE_RGB );

Sample: COLOR

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_contrast_adjust

Group: Image Processing
NOTE: See also IG_IP_contrast_adjust_ex.

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_contrast_adjust (
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    AT_MODE nMethodMode,
    DOUBLE dblContrast,
    DOUBLE dblBrightness
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to operate on. lpRect = NULL means the entire image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nMethodMode
IG_CONTRAST_PIXEL or IG_CONTRAST_PALETTE, telling whether to adjust by altering the pixels themselves, or the palette
dblContrast
The range should be from -(2^bpc) to (2^bpc) to adjust the contrast, bpc being equal to the bits per channel. Here are two examples of how this works:
  • A normal RGB image, 8bpc, would be -(2^8) to (2^8), or -256 to 256.
  • A 4 bit indexed image, 4bpc, would be -(2^4) to (2^4), or -16 to 16.
dblBrightness
The range should be from -(2^bpc)+1 to (2^bpc)-1 to adjust the brightness, bpc being equal to the bits per channel. Here are two examples of how this works:
  • A normal RGB image, 8bpc, would be -(2^8)+1 to (2^8)-1, or -255 to 255.
  • A 4 bit indexed image, 4bpc, would be -(2^4)+1 to (2^4)-1, or -15 to 15.

Description:

This function allows the brightness and contrast of the image to be adjusted. Brightness and contrast are linear controls that affect the intensity of the image pixels. These controls are similar to the Brightness and Contrast controls on a typical television set.

Contrast is a multiplier and Brightness is an additive value. A Contrast of 2.0 will cause each pixel to take on twice the intensity that it originally had while 0.5 will divide each by 2. A Brightness value of 20.0 will cause each pixel's intensity to be increased by 20 and a -20 will decrease or darken each by 20. Pixel values are clipped to the 0 to 255 range. Once clipped the data is lost and can not be regenerated. A Brightness of 0.0 and a Contrast of 1.0 will cause no change to the image. A -1.0 Contrast with a Brightness of 0.0 can be used to invert the intensity range.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: See the functions IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

When IG_CONTRAST_PALETE is used the lpRect rectangle is ignored, since the whole image is affected when the palette is changed.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* HIGEAR handle of image */
IG_IP_contrast_adjust ( hIGear, NULL, IG_CONTRAST_PIXEL, 2.0, -
10.0 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_contrast_adjust_ex

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_contrast_adjust_ex(
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    AT_MODE method_mode,
    DOUBLE contrast,
    DOUBLE brightness,
    AT_MODE color_channel
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to operate on. lpRect = NULL means the entire image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
method_mode
IG_CONTRAST_PIXEL or IG_CONTRAST_PALETTE, telling whether to adjust by altering the pixels themselves, or the palette
contrast
The range should be from -(2^bpc) to (2^bpc) to adjust the contrast, bpc being equal to the bits per channel. Here are two examples of how this works:
  • A normal RGB image, 8bpc, would be -(2^8) to (2^8), or -256 to 256.
  • A 4 bit indexed image, 4bpc, would be -(2^4) to (2^4), or -16 to 16.
brightness
The range should be from -(2^bpc)+1 to (2^bpc)-1 to adjust the brightness, bpc being equal to the bits per channel. Here are two examples of how this works:
  • A normal RGB image, 8bpc, would be -(2^8)+1 to (2^8)-1, or -255 to 255.
  • A 4 bit indexed image, 4bpc, would be -(2^4)+1 to (2^4)-1, or -15 to 15.
color_channel
Specifies the color channel to adjust.

Description:

This function allows the brightness and contrast of the image to be adjusted. brightness and contrast are linear controls that affect the intensity of the image pixels. These controls are similar to the brightness and contrast controls on a typical television set.

contrast is a multiplier and brightness is an additive value. A contrast of 2.0 will cause each pixel to take on twice the intensity that it originally had while 0.5 will divide each by 2. A brightness value of 20.0 will cause each pixel's intensity to be increased by 20 and a -20 will decrease or darken each by 20. Pixel values are clipped to the 0 to 255 range. Once clipped the data is lost and can not be regenerated. A brightness of 0.0 and a contrast of 1.0 will cause no change to the image. A -1.0 contrast with a brightness of 0.0 can be used to invert the intensity range.

color_channel must be a value from enumIGColorChannels. It specifies the color channel to adjust. This channel does not need to be in the same color space as the image. For example, you can adjust the saturation of an RGB image by specifying IG_COLOR_COMP_IHS_S.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: See the functions IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() for more details.

When IG_CONTRAST_PALETE is used the lpRect rectangle is ignored, since the whole image is affected when the palette is changed.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

// Decrease the saturation of an image:
IG_IP_contrast_adjust_ex(hIGear, NULL, IG_CONTRAST_PIXEL, 1, -
128, IG_COLOR_COMP_IHS_S);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_contrast_equalize

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_contrast_equalize(
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    AT_MODE nMethodMode
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct defining the rectangle within the image that this function is to operate on. If NULL, the entire image will be operated on. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nMethodMode
IG_CONTRAST_PIXEL or IG_CONTRAST_PALETTE, telling whether to alter the pixels themselves (the image bitmap) or the palette

Description:

This function automatically adjusts the contrast of the image so that each range of possible intensities has about the same number of pixels in it. Just like IG_IP_contrast_stretch (), this will expand the intensity range of the image to fill the entire 0 to 255 range. However, unlike that function this one is non-linear.

This function is often used in x-ray images and in others where the contrast can be very small in the original. IG_IP_contrast_equalize () will bring out subtle changes in the contrast.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;      /* HIGEAR handle of image */
IG_IP_contrast_equalize ( hIGear, NULL, IG_CONTRAST_PIXEL );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_contrast_gamma

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_contrast_gamma (
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    AT_MODE nMethodMode,
    DOUBLE dblGamma
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to operate on. lpRect = NULL means the entire image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nMethodMode
IG_CONTRAST_PIXEL or IG_CONTRAST_PALETTE, telling whether to adjust by altering the pixels themselves, or the palette
dblGamma
Greater than 0.0. Usual range: 0.75 to 3.0

Description:

Gamma is a non-linear method to adjust the contrast of a image. In this method, the amount a pixel's intensity changes depends on its original intensity. This can be used to make dark regions brighter without over saturating (clipping) the bright regions. Or, conversely, to make light regions darker without under saturating the dark regions.

Gamma was originally introduced to compensate for the non-linear nature of the phosphors used in monitors and in the original tube cameras that created images. However, it can be used as an image processing function to create better looking images that may not be mathematically color corrected.

While the gamma can be any non-zero positive value the usual range is 0.75 to 3.0. A gamma value of 1.0 does not alter the image. For typical monitors a range of 1.8 to 2.2 is usual. Values less than 1.0 cause dark pixel to become brighter. Values greater than 1.0 cause bright regions to become darker.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* HIGEAR handle of image */
IG_IP_contrast_gamma ( hIGear, NULL, IG_CONTRAST_PALETTE, 2.0 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_contrast_invert

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_contrast_invert (
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    AT_MODE nMethodMode
);

Arguments:

hIGear
HIGEAR handle of image to invert contrast of
lpRect
Far pointer to an AT_RECT struct defining the rectangle within the image that this function is to operate on. If NULL, the entire image will have its contrast inverted. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nMethodMode
IG_CONTRAST_PIXEL or IG_CONTRAST_PALETTE, telling whether to alter the pixels themselves (the image bitmap) or the palette

Description:

This function will invert every color to its complement, in the rectangular portion of the image selected by lpRect. For black-and-white images, black will become white and white will become black. For grayscale and color images, every red, green, and blue color intensity value will be complemented: 0 will become 255 (and vice versa), 1 will become 254, and so on. Therefore, in a grayscale image, the darkest grays will become the lightest grays, and vice versa; and in a color image, colors near green will complement to colors near magenta (the complement of green), and so on.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

If nMethodMode = IG_CONTRAST_PIXEL, the inversion is accomplished by inverting all bits of all pixels within lpRect: bits that are 1 become 0, and bits that are 0 become 1. If nMethodMode = IG_CONTRAST_PALETTE, the inversion is accomplished by inverting the bits in the image's palette. (The image bitmap is left unchanged.) Note that specifying IG_CONTRAST_PALETTE inverts the entire image, ignoring any rectangle specified. Note also that for 8-bit indexed color (8i) images, inverting the pixel will produce an error; only IG_CONTRAST_PALETTE makes sense.

If the image is 24-bit, only the pixel bits can be complemented (since there is no palette), so in this case nMethodMode is ignored.

In photographic terms, this function produces the "negative" of the image.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;      /* Handle of image to have contrast
inverted*/
AT_RECT rcInvertRect;/* Portion of image to be inverted   */
AT_ERRCOUNT nErrcount    /* Returned number of errors        */
AT_DIMENSION nWid        /* Will hold returned width of image */
AT_DIMENSION nHi        /* Returned height of image, number of
rows */
UINT nBpp      /* Returned number of bits per pixel */
/* The following will invert contrast on only the upper right
quadrant of the image, unless the image is 8i, in which case
whole image will be inverted. */
/* First, get dimensions of image: */
nErrcount = IG_image_dimensions_get ( hIGear, &nWid, &nHi, &nBpp
);
if ( nErrcount == 0 )    /* If that succeeded: */
{
    if ( (nBpp == 8) && (IG_image_is_gray(hIGear) == FALSE) ) /*
If 8i:*/
        {
        /* Invert contrast of whole image: */
        nErrcount = IG_IP_contrast_invert(hIGear,NULL,
IG_CONTRAST_PALETTE);
        }
    else	                /* Otherwise: */
        {
        /* Create rectangle of upper right quadrant: */
        rcInvertRect.top    = 0;
        rcInvertRect.left   = nWid / 2;
        rcInvertRect.right  = nWid - 1;
        rcInvertRect.bottom = nHi  / 2;
        /* Invert contrast of upper-right quadrant only: */
nErrcount = IG_IP_contrast_invert ( hIGear, &rcInvertRect,
                                               IG_CONTRAST_PIXEL );
        }
    }
if ( nErrcount ) { ... }    /* If any errors, process them  */

Sample: TIMING

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_contrast_stretch

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_contrast_stretch (
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    AT_MODE nMethodMode
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct defining the rectangle within the image that this function is to operate on. If NULL, the entire image will be operated on. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nMethodMode
IG_CONTRAST_PIXEL or IG_CONTRAST_PALETTE, telling whether to alter the pixels themselves (the image bitmap) or the palette

Description:

This function automatically adjusts the contrast of the image so that at least one pixel is completely black and one pixel is completely white. This fills the entire range of the pixel intensities. The original pixel intensities are adjusted linearly between the 2 extremes. (If the image already fills the entire range then the image is not altered.)

Images that use the entire range often appear richer and the colors display more vivid.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. (See above.) However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
IG_IP_contrast_stretch ( hIGear, NULL,IG_CONTRAST_PIXEL );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_convert_to_gray

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_convert_to_gray (HIGEAR hIGear );

Arguments:

hIGear
HIGEAR handle of image

Description:

This function converts the image referenced by hIGear to a grayscale image.

Applicability: All except grayscale

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;      /* HIGEAR handle of image */
IG_IP_convert_to_gray ( hIGear );

Sample: COLOR, IMG_PROC, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_convolve_matrix

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_convolve_matrix(
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    LPINT lpMatrix,
    UINT nMatrixWidth,
    UINT nMatrixHeight,
    DOUBLE dblNormalizer,
    AT_MODE ColorChannel,
    AT_MODE nResultForm,
    BOOL bAddToOrigin
);

Arguments:

hIGear
HIGEAR handle of image to be processed
lpRect
Rectangle of image to process; setting to NULL will process the whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non - rectangular ROI defined by the mask.
lpMatrix
Far pointer to first INT object in array of kernel elements
nMatrixWidth
A variable of type UINT that holds the width of the array; the maximum value is 16
nMatrixHeight
A variable of type UINT that holds the height of the array; the maximum value is 16
dblNormalizer
A variable of type DOUBLE that contains the value of the normalizer of the kernel
nColorChannel
An AT_MODE constant such as IG_COLOR_COMP_R, _G, _B, or _RGB
nResultForm
An AT_MODE constant, such as IG_CONV_RESULT_8BIT_SIGNED
bAddToOrigin
A variable of type BOOL that tells whether to add the result of the convolution to the pixel values.

Description:

This function convolves the image using a user-defined convolution kernel. The bAddToOrigin argument determines whether the result of the convolution is added to the pixel values, or if it replaces the pixel values:

    if bAddToOrigin = TRUE
        pixel = pixel + result_of_convolution
    if bAddToOrigin = FALSE
        pixel = result_of_convolution

The result of each convolution is multiplied by the normalizer, dblNormalizer. For kernels that sum to zero, the normalizer is usually set to 1.0. When the sum is not zero, the normalizer's value will depend on the goal of convolution. In a non-weighted averaging convolution the kernel elements are often all ones. In this case the normalizer would be equal to 1/(sum of kernel). Remember that the normalizer is multiplied by the sum of the convolution and not divided into it.

The result of the convolution is an 8-bit image. nResultForm determines the type of the format of this new image:

  • IG_CONV_RESULT_RAW - the result is stored as is.
  • IG_CONV_RESULT_ABS - the absolute value of the signed result is stored.
  • IG_CONV_RESULT_8BIT_SIGNED - the result is stored as 8-bit signed values. The MSB is used for the sign.
  • IG_CONV_RESULT_SIGN_CENTERED - the result is stored as 8-bit signed, but 0 is equal to 0x7F. Positive numbers are from 0x7E to 0x00. Negative numbers are from 0x80 to 0xFF. This is used for images that are to be used as background tiles or watermarks. The IG_FX_emboss () function uses this format.
NOTE: See the Glossary for another explanation of "Convolution." Note that this particular convolution method multiples the results of the convolution by the normalizer, rather than dividing by the convolution, as described in the Glossary.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. (See above.) However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Applicability: All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR       hIGear;     /* HIGEAR handle of image */
UINT         mxConv[5,3];  /* Convolution kernel  */
DOUBLE       dblNormalizer; /* Normalizer of the kernel  */
AT_MODE      nResultForm;    /* Storage format of results */
BOOL         bAddToOrigin;  /* TRUE = add to original pix vals */
AT_RECT      lpRect;        /* rectangle to process  */
mxConv = { 1, 1, 1, 1, 1,
    -2,-2,-2,-2,-2
    1, 1, 1, 1, 1 };
IG_IP_convolve_matrix ( hIGear, NULL, &mxConv, 5, 3, 1.0,
     IG_COLOR_COMP_RGB, IG_CONV_RESULT_RAW, FALSE );

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_crop

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_crop (
    HIGEAR hIGear,
    LPAT_RECT lpCropRect
);

Arguments:

hIGear
HIGEAR handle of image
lpCropRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to keep. The remainder of the image is removed and discarded.

Description:

This function crops the image to the image rectangle. Only pixels that fall on or inside the lpCropRect rectangle will be kept in the resulting image. The dimensions of the resulting image are then same as that of the lpCropRect. The removed parts of the image are discarded.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* HIGEAR handle of image */
AT_RECT rcCropRect;    /* Rectangular part remaining  */
AT_DIMENSION nWidth,      /* Original width and height  */
        nHeight;
UINT nBpp;      /* Bits per pixel (not used) */
AT_DIMENSION nHalfWidth,    /* Will hold half the width */
        nHalfHeight;   /* and half the height    */
/* Set crop rectangle to half the size of the image, centered:
*/
if ( IG_image_is_valid (hIGear) )
    {
    IG_image_dimensions_get ( &hIGear, &nWidth, &nHeight, &nBpp
);
    nHalfWidth  =  nWidth / 2;   nHalfHeight  =  nHeight / 2;
    rcCropRect.left   =  nHalfWidth / 2;
    rcCropRect.right  =  rcCropRect.left + nHalfWidth - 1;
    rcCropRect.top    =  nHalfHeight / 2;
    rcCropRect.bottom =  rcCropRect.top  + nHalfHeight - 1;
        /* Crop the image: */
    nErrCount	 =  IG_IP_crop ( hIGear, &rcCropRect );
    }

Sample: ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_DCRaw_camera_to_sRGB_matrix_calculate

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI
IG_IP_DCRaw_camera_to_sRGB_matrix_calculate(
    AT_INT SrcChannelCount,
    HIGDoubleMatrix XYZToCam1,
    enumIGIlluminant Illuminant1,
    HIGDoubleMatrix XYZToCam2,
    enumIGIlluminant Illuminant2,
    AT_DPOINT WhiteXY,
    HIGDoubleMatrix *lpCamToRGB
);

Parameters:

SrcChannelCount
Number of channels in the camera color space
XYZToCam1
XYZ to camera matrix under Illuminant 1
Illuminant1
Illuminant 1
XYZToCam
XYZ to camera matrix under Illuminant 2
Illuminant2
Illuminant 2
WhiteXY
XY coordinates of camera white point
lpCamToRGB
Returns conversion matrix

Description:

Calculates matrix for convesion from camera colorspace to linear sRGB colorspace, based on two known color matrices corresponding to different light conditions, and a white point. By "linear sRGB colorspace" we assume a linear (Gamma = 1.0) RGB colorspace that uses sRGB primaries and reference white. This colorspace can be converted to sRGB by applying sRGB gamma correction function.

If only one color matrix is known, pass null to XYZToCam2.

Dimensions of XYZToCam1 and XYZToCam2 must be equal to (n, 3), where n is channel count of native camera colorspace (3 or 4). Result matrix dimensions are (3, n).

Return value:

Returns the number of ImageGear errors that occurred during this function call.

See also:

IG_IP_DCRaw_RGB_gamma_LUT_build


IG_IP_DCRaw_RGB_gamma_LUT_build

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_DCRaw_RGB_gamma_LUT_build (
    AT_INT ChannelDepth,
    HIGLUT *SRGBLUT
);

Parameters:

ChannelDepth
Bit depth of the LUT
SRGBLUT
Returns new LUT

Description:

Builds sRGB Gamma LUT, for conversion from "linear sRGB" to the standard sRGB colorspace.

By "linear sRGB colorspace" we assume a linear (Gamma = 1.0) RGB colorspace that uses sRGB primaries and reference white.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_DCRaw_tone_LUT_build

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_DCRaw_tone_LUT_build (
    AT_INT ChannelDepth,
    AT_DOUBLE Exposure,
    AT_DOUBLE Shadows,
    HIGLUT *ToneLUT
);

Parameters:

ChannelDepth
Bit depth of the LUT
Shadows
Amount by which to move the black point
Exposure
Exposure compensation, in f/stops
ToneLUT
Returns new LUT

Description:

Builds tone correction LUT.

The LUT moves image's black point by 2^16 / 1000 * Shadows, and adjusts white point according to Exposure parameter. Exposure parameter is measured in f/stops and works similar to modifying the camera exposure.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_DCRaw_white_point_calculate

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_DCRaw_white_point_calculate (
    AT_INT SrcChannelCount,
    HIGDoubleMatrix XYZToCam1,
    enumIGIlluminant Illuminant1,
    HIGDoubleMatrix XYZToCam2,
    enumIGIlluminant Illuminant2,
    const AT_DOUBLE *lpNeutralColor,
    AT_DPOINT *lpWhiteXY,
);

Parameters:

SrcChannelCount
Number of channels in the camera color space
XYZToCam1
XYZ to camera matrix under Illuminant 1
Illuminant1
Illuminant 1
XYZToCam2
XYZ to camera matrix under Illuminant 2
Illuminant2
Illuminant 2
lpNeutralColor
Normalized coordinates of a neutral color
lpWhiteXY
Returns the calculated white point coordinates

Description:

Calculates white point corresponding to neutral color in camera colorspace based on two known color matrices corresponding to different light conditions.

If only one color matrix is known, pass null to XYZToCam2.

Dimensions of XYZToCam1 and XYZToCam2 must be equal to (n, 3), where n is channel count of native camera colorspace (3 or 4). Number of entries in the lpNeutralColor array must be equal to channel count of native camera colorspace.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_decrypt

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_decrypt (
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    AT_MODE nEncryptType,
    LPSTR lpszPassword
);

Arguments:

hIGear
HIGEAR handle of image to be decoded
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to decode. Set = NULL for the whole image
nEncrptyType
An IG_ENCRYPT_METHOD_ constant specifying how the image was encoded
lpszPassword
Far pointer to your zero- terminated password string

Description:

This function works on a DIB, not on a file. It decodes an image or a rectangular portion thereof, that was encrypted using IG_IP_encrypt (). You must supply both the encryption method and the password that were used in the call to IG_IP_encrypt ().

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;
/* Decrypt the whole hIGear image by method A & with "Top
Secret" password   */
IG_IP_decrypt (hIGear, NULL, IG_ENCRYPT_METHOD_A, "Top
Secret");

Sample: FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_deskew_angle_find

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_deskew_angle_find (
    HIGEAR hIGear,
    LPDOUBLE lpAngle
);

Arguments:

hIGear
HIGEAR handle of image
lpAngle
Far pointer to a DOUBLE variable that will receive the skew angle

Description:

This function determines the skew angle of a 1-bit document image. The angle is returned via the pointer lpAngle. You may then use the value of lpAngle with IG_IP_rotate_any_angle () function in order to straighten the image.

Applicability: 1bpp indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;  /* HIGEAR handle of image    */
DOUBLE dblDeskewAngle;  /* Amount of skew in lpRect returned  */
AT_ERRCOUNT  nErrcount;  /* will tally any IG errors  */
nErrcount = IG_IP_deskew_angle_find ( hIGear, &dblDeskewAngle );

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_deskew_auto

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_deskew_auto (
    HIGEAR hIGear,
    DOUBLE dblAngleThresh,
    AT_MODE nExpand_clip_option
);

Arguments:

hIGear
HIGEAR handle of image to be decoded
dblAngleThresh
Do not de-skew if the skew angle is less than this parameter.
nExpand_clip_option
An AT_MODE type variable, either: IG_ROTATE_CLIP or IG_ROTATE_EXPAND

Description:

This function automatically detects the angle of the 1-bit document referenced by hIGear, and rotates it so that it is straight. (de-skews it.) However, if the skew angle is less than dblAngleThresh, then the image is not de-skewed. If nExpand_clip_option is set to IG_ROTATE_EXPAND, the size of image width or height will be enlarged as necessary to accommodate the document when it has been rotated. Otherwise, any areas of the document that now fall outside the borders of the original width and height of the image, will be cropped.

NOTE: If you want to first detect the angle and then decide whether to rotate it, you can make separate calls to IG_IP_deskew_angle_find() and IG_IP_rotate_any_angle()functions.

Applicability: 1bpp indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear;      /* HIGEAR handle of image  */
DOUBLE	 angle_thresh;/* max angle above which should not perform
skew  */
AT_MODE nExpand_clip_option;/* expand image or clip doc  */
AT_ERRCOUNT nErrcount;    /* will tally returned IG errors */
nErrcount = IG_IP_deskew_auto ( hIGear, 3.0, IG_ROTATE_CLIP);

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_despeckle

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_despeckle (
    HIGEAR hIGear,
    const LPAT_RECT lpRect
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to operate on. If NULL, the operation will be performed on the entire image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.

Description:

Despeckle is used to help reduce the amount of noise in the image. Single pixels and pixel spurs on letters and graphics are removed while leaving the solid areas alone. It is typically used on 1-bit document images.

The despeckle operation performs a 3x3 median filter on the image. For each 3x3 neighborhood of pixels in the original image, a single pixel is produced in the output image. In this case the output is the median of the 9 values in the 3x3 neighborhood.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Applicability: All except indexed with >1bpp

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;  /* HIGEAR handle of image */
nErrCount	 = IG_IP_despeckle ( hIGear, NULL );

Sample: TIMING

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_detect_area

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_detect_area(
    HIGEAR hIGear,
    AT_INT xPos,
    AT_INT yPos,
    LPAT_VOID detectStruct,
    LPFNIG_CHECK_PIXEL detectFunc,
    LPAT_RECT lpRect,
    AT_NR_ROI_MASK* lpMask
);

Arguments:

hIGear
Image to analyze.
xPos
X coordinate of a point inside the area to be detected.
yPos
X coordinate of a point inside the area to be detected.
detectStruct
A pointer to a user-defined structure that will be passed to the callback function.
detectFunc
Callback function that checks whether specified pixel belongs to the area or not.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.
lpMask
Returns the ROI mask.

Description:

Detects an area of pixels using a user-defined pixel checker. The area being detected is returned as a ROI structure.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_detect_area_with_threshold

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_detect_area_with_threshold(
    HIGEAR  hIGear,
    AT_INT  xPos,
    AT_INT  yPos,
    AT_DOUBLE nThreshold,
    LPAT_RECT lpRect,
    AT_NR_ROI_MASK* lpMask
);

Arguments:

hIGear
Image to analyze.
xPos
X coordinate of a point inside the area to be detected.
yPos
Y coordinate of a point inside the area to be detected.
nThreshold
Area threshold.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.
lpMask
Returns the ROI mask.

Description:

Detects an area of pixels using a specified threshold. The pixel is supposed to be in the area if the following condition is true for all pixel channels:

(pixel[i] >= initialPixel[i] - threshold) && (pixel[i] <= initialPixel[i] + threshold)

The area being detected is saved as the ROI of the page.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_detect_redeye_area

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_detect_redeye_area(
    HIGEAR  hIGear,
    AT_INT  xPos,
    AT_INT  yPos,
    AT_DOUBLE dblThreshold,
    LPAT_RECT lpRect,
    AT_NR_ROI_MASK* lpMask
);

Arguments:

hIGear
Image to analyze.
xPos
X coordinate of a point inside the area to be detected.
yPos
Y coordinate of a point inside the area to be detected.
dblThreshold
Area threshold. Value in the range 0.5..2 that specifies a part of the red component in the pixel color.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.
lpMask
Returns the ROI mask.

Description:

Detects red eye area in the image.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_dilate

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_dilate(
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    LPAT_INT lpMatrix,
    AT_INT nMatrixSize
);

Parameters:

hIGear
Image to apply effect to.
lpRect
Image rectangle to process.
lpMatrix
Matrix specifying a structuring element for the operation
nMatrixSize
Matrix edge size.

Description:

This method applies dilation effect to provided raster page using the specified structure element. This method is applicable to any grayscale image (image with [Gy] color space).

Applicability:

1-bit and 8-bit grayscale

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_draw_frame

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_draw_frame (
    HIGEAR hIGear,
    AT_DIMENSION width,
    AT_MODE nMethod,
    LPAT_PIXEL lpColor
);

Arguments:

hIGear
HIGEAR handle of image
width
A variable that holds the width of the frame, in pixels
nMethod
A variable of type AT_MODE that tells ImageGear which IG_DRAW_FRAME_ setting to use. See below.
lpColor
A far pointer to the RGB value that specifies the frame's color

Description:

This function adds a frame (block of solid color on all four sides) to the image referenced by hIGear.

If nMethod is set to IG_DRAW_FRAME_EXPAND, the width and the height of the image will be expanded by 2 times the width of the frame. If nMethod is set to IG_DRAW_FRAME_OVERWRITE, all four sides of the image will be overwritten by the frame, so that the resulting image has the same width and height as the original image, but the edges of the image are "covered" by the frame.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
AT_ERRCOUNT nErrcount;  /* holds tally of IG errors */
AT_DIMENSION width;  /* width, in pixels, of frame  */
AT_MODE	 	 nMethod;  /* expand or overwrite image  */
AT_PIXEL lpColor[256];  /* color of frame; RGB value  */
nErrcount = IG_IP_draw_frame ( hIGear, 5, IG_DRAW_FRAME_EXPAND,
&lpColor[9]);

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_drop_shadow

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_drop_shadow(
    HIGEAR  hIGear,
    AT_INT  width,
    AT_INT  distance,
    AT_INT  angle,
    HIGPIXEL hInsideColor,
    HIGPIXEL hOutsideColor
);

Arguments:

hIGear
Image to apply drop shadow effect to.
width
Width of background and shadow area to add to the image.
distance
Distance to move image from shadow area.
angle
Angle (direction) of movement of image from shadow area.
hInsideColor
Color of shadow area. It should have the same colorspace and channel depths as the image to which the effect is applied.
hOutsideColor
Color of background. It should have the same colorspace and channel depths as the image to which the effect is applied.

Description:

This method adds a drop shadow to an image. The image is enlarged to contain a background and shadowed area.

Applicability:

All except bitonal, non-gray Indexed and Grayscale with LUT.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_IP_edge_detection

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_edge_detection(
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const AT_MODE edge_detection_type
);

Arguments:

hIGear
Handle of the input image
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image. Before ImageGear performs this operation it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
edge_detection_type
Type of edge detection method to perform. Constants IG_EDGE_DETECTION_* are listed in file accucnst.h.

Description:

This function performs the edge detection operation specified by the edge_detection_type argument.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Bits Per Pixel:

8bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Example:

HIGEAR hIGear; 	/* Handle of the image */
AT_RECT lpRect; 	/* Rectangle to process */
...
IG_IP_edge_detection(hIGear, lpRect,
IG_EDGE_DETECTION_MAXGRADIENT);
...

Sample:

IMG_PROC


IG_IP_edge_map

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_edge_map (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const AT_MODE nEdgeMapType
);

Arguments:

hIGear
HIGEAR handle of an image.
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image. Before ImageGear performs this operation it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangualr ROI defined by the mask.
nEdgeMapType
Type of edge map operation to perform, such as IG_EDGE_OP_LAPLACIAN, IG_EDGE_OP_ROBERTS, etc. The list of available types is in the accucnst.h.

Description:

This function performs the image processing operation specified by the nEdgeMapType argument. The operation is performed upon the rectangular portion of the image specified by lpRect.

An edge map is an image that shows where there are changes in contrast in the original image. Where there are no changes, the resulting image is black. The stronger the contract change, the brighter the resultant image. The different types of edge maps are slight variations of the algorithm used, and produce slightly different results.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image.If the flag is set to TRUE, and a validpointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mak HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask ().

NOTE: See the descriptions of IG_IP_NR_ROI_mask_associate() and IP_IP_NR_ROI_to_HIGEAR_mask () functions for more details.

Applicability: All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR 	hIGear;   /* HIGEAR handle of an image *?
IG_IP_edge_map ( hIGear, NULL, IG_EDGE_OF_ALPLACIAN ):

Sample: FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_encrypt

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_encrypt (
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    AT_MODE nEncryptType,
    const LPSTR lpszPassword
);

Arguments:

hIGear
HIGEAR handle of image to be encoded
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to encode. Set = NULL for the whole image.
nEncrptyType
An IG_ENCRYPT_METHOD_ constant specifying the method to be used. See file accucnst.h for IG_ENCRYPT_METHOD_ constants available
lpszPassword
Far pointer to your zero-terminated password string

Description:

This function scrambles an image bitmap, or a rectangular portion thereof. Your password is also stored. To later decode the image using IG_IP_decrypt (), you will need to know both the encryption method and the password used in this call.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

NOTE: This function cannot take a non-rectangular ROI for its AT_RECT parameter.

Example:

HIGEAR hIGear;
/* Encrypt the whole hIGear image by method A & with "Top
Secret" password   */
IG_IP_encrypt ( hIGear, NULL, IG_ENCRYPT_METHOD_A, "Top Secret"
);

Sample: FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_enhance_local

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_enhance_local(
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const AT_DIMENSION nWinWidth,
    const AT_DIMENSION nWinHeight,
    const AT_DOUBLE dScaleFactor,
    const AT_DOUBLE dMinStdDev
);

Arguments:

hIGear
IGEAR handle of image to be processed
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image. Before ImageGear performs this operation it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nWinWidth
Width of the local window
nWinHeight
Height of the local window
dScaleFactor
Scaling factor
dMinStdDev
Minimum allowed standard deviation

Description:

This function enhances an image using the local standard deviation and mean.

It transforms the input image f(x, y) to a new image g(x, y) based on the following formula,

g(x, y) = A(x, y) * [f(x, y) - m(x, y)] + m(x, y)

where,

A(x, y) = k * M / sigma(x, y), with k being a scaling factor within the range [0, 1], m(x, y) and sigma(x, y) being the local mean and local standard deviation, and M being the global mean of the input image.

To avoid the problem of spikes caused by too small local standard deviation, a check against the minimum allowed standard deviation is performed. If the local standard deviation is too small, the minimum allowed will instead be used in the calculation.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Bits Per Pixel:

8-bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear; 	/* HIGEAR handle of image */
AT_RECT lpRect; 	/* rectangle to process */
AT_DIMENSION nWinWidth;	/* Window width */
AT_DIMENSION	nWinHeight;	/* Window height */
AT_DOUBLE dScaleFactor;	/* Tuning factor */
AT_DOUBLE dMinStdDev; /* Minimum allowed standard deviation */
...
IG_IP_enhance_local(hIGear, lpRect, nWinWidth, nWinHeight,
dScaleFactor, dMinStdDev);
...

Sample:

IMG_PROC


IG_IP_erode

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_erode(
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    LPAT_INT lpMatrix,
    AT_INT nMatrixSize
);

Parameters:

hIGear
Image to apply effect to.
lpRect
Image rectangle to process.
lpMatrix
Matrix specifying a structuring element for the operation
nMatrixSize
Matrix edge size.

Description:

This method applies erosion effect to provided raster page using the specified structure element. This method is applicable to any grayscale image (image with [Gy] color space).

Applicability:

1-bit and 8-bit grayscale

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_find_tilt

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_find_tilt(
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    LPAT_DOUBLE lpSlopeX,
    LPAT_DOUBLE lpSlopeY,
    LPAT_DOUBLE lpPiston
);

Arguments:

hIGear
HIGEAR handle of image to be processed
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image. Before ImageGear performs this operation it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
lpSlopeX
Returns the slope in the X direction of the tilt plane.
lpSlopeY
Returns the slope in the Y direction of the tilt plane.
lpPiston
Returns the piston of the tilt plane.

Description:

This function computes the least-squares best fit plane for an image. The plane will be given by formula f(x, y) = SlopeX * x + SlopeY * y + Piston.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Bits Per Pixel:

8, 16, or 32bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	hIGear;  	/* HIGEAR handle of image */
AT_RECT lpRect;  	/* rectangle to process */
LPAT_DOUBLE lpSlopeX, lpSlopeY, lpPiston;
...
IG_IP_find_tilt(hIGear, lpRect, lpSlopeX, lpSlopeY, lpPiston);
...

Sample:

IMG_PROC


IG_IP_flip

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_flip (
    HIGEAR hIGear,
    AT_MODE nDirection
);

Arguments:

hIGear
HIGEAR handle of image to flip
nDirection
IG_FLIP_HORIZONTAL or IG_FLIP_VERTICAL, telling whether to flip horizontally or vertically

Description:

Flips the image referenced by hIGear either horizontally or vertically. Flipping horizontally exchanges the right-most pixel column of the image bitmap with the left-most. Flipping vertically exchanges the topmost pixel row (raster) of the image bitmap with the bottom-most. The dimensions of the image do not change.

NOTE: If you want to turn the image upside-down (not the same as a vertical flip), use function IG_IP_rotate_multiple_90(), with rotation mode set to IG_ROTATE_180.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    /* Handle of image to flip    */
AT_ERRCOUNT nErrcount;    /* Will hold ret'd count of errors  */
    /* Flip such that top row becomes bottom row, etc.:  */
nErrcount = IG_IP_flip ( hIGear, IG_FLIP_VERTICAL );

Sample: IMG_PROC, ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_gaussian_blur

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_gaussian_blur (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const double dblRadius
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to AT_RECT struct specifying a portion of the image to be affected. NULL means entire image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
dblRadius
Defines the neighborhood to be considered for each pixel.

Description:

This function smoothes the images using Gaussian transform. It makes images look softer and slightly out of focus. A specific feature of Gaussian Blur is that it removes the high-frequency component from the image, which is not the case for the IG_IP_smooth ().

Parameter dblRadius corresponds to the Standard Deviation (Sigma) in Gaussian transform. It can range from 0.1 to 500. Typical values for high-resolution images range from 1.0 to 2.0. Larger values will cause greater softening. On the other hand, smaller values are faster. The width of the area considered for each pixel is approximately 6 * dblRadius.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask ().

Applicability: All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;
/* Blur whole image, radius = 2.0 */
nErrCount =IG_IP_gaussian_blur ( hIGear, NULL, 2.0 );

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_geom_despeckle

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_geom_despeckle(
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const AT_INT nIterations
);

Arguments:

hIGear
HIGEAR handle of image to be processed
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image. Before ImageGear performs this operation it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nIterations
Number of iterations to apply the despeckle filter.

Description:

This function is used to reduce speckle noise from an image by using the Crimmins algorithm. It reduces the speckle index of an image by sending the image through a geometric filter, which uses the complementary hulling technique. The method has the effect of reducing the undesired speckle noise while preserving the edges of the original image.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Bits Per Pixel:

8-bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	hIGear; /* HIGEAR handle of image */
AT_RECT lpRect; /* rectangle to process */
AT_INT nIterations;	/* Number of iterations */
...
IG_IP_geom_despeckle(hIGear, lpRect, nIterations);
...

Sample:

IMG_PROC


IG_IP_histo_clear

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_histo_clear (
    LPDWORD lpHisto,
    UINT nNumberOfBins
);

Arguments:

lpHisto
Far pointer to an array of bins (each a DWORD) to be cleared
nNumberOfBins
Number of bins to clear

Description:

This function will clear an array of histogram bins. Call this function prior to calling IG_IP_histo_tabulate (), unless you mean to accumulate onto existing contents of the bins.

Applicability: N/A (this function does not operate on an image)

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See the example under the IG_IP_histo_tabulate ()function.

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_histo_tabulate

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_histo_tabulate (
    HIGEAR hIGear,
    LPDWORD lpHisto,
    UINT nNumberOfBins,
    LPAT_RECT lpRect,
    UINT nYIncr,
    const AT_MODE nColorChannel
);

Arguments:

hIGear
HIGEAR handle of image
lpHisto
Far pointer to an array of bins (each a DWORD) in which to tabulate
nNumberOfBins
Number of bins
lpRect
Far pointer to an AT_RECT struct specifying rectangular portion of the image to tabulate for, or NULL for whole image. an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nYIncr
Set = 1 to sample every pixel. Values larger than 1 will skip rasters of the image bitmap
nColorChannel
For 24 bit images selects which channel: IG_COLOR_COMP_R, _G, or _B (IG_COLOR_COMP_RGB not allowed).

Description:

This function produces a histogram of the pixel values occurring in image hIGear, or in the rectangular portion specified if lpRect is not NULL.

If nYIncr = 1, each pixel in the image is examined. The bin corresponding to that pixel value increments. The number of bins must be large enough to hold the entire histogram. If an 8 or 24-bit image, the number of bins must be 256. If a 4-bit or 1-bit image, the number of bins must be 16 or 2 respectively. Note that for a 24-bit image, only a single color channel can be a histogram at one time. Use argument nColorChannel to select the channel.

If nYIncr is greater than 1, then rasters of the image are skipped. This can be used to speed up the tabulation when the image is large.

You should call IG_IP_histo_clear () before calling this function, unless you intentionally mean to accumulate the count onto the existing contents of the bins.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    /* HIGEAR handle of image */
DWORD dwHistoBins[256];   /* Array of bins for counting */
IG_IP_histo_clear ( &dwHistoBins, 256 ); /* Clear the bins */
/* Tabulate. If a 24-bit image, only the red will be tabulated:
*/
IG_IP_histo_tabulate (hIGear, &dwHistoBins, 256, NULL, 1,
IG_COLOR_COMP_R);

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_maximum

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_maximum (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    AT_DIMENSION nNeighborWidth,
    AT_DIMENSION nNeighborHeight
);

Arguments:

hIGear
HIGEAR handle of image.
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to operate upon. If NULL, the entire image will be operated upon. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nNeighborWidth
Width of the neighborhood to include in computing each new pixel's value.
nNeighborHeight
Height of the neighborhood to include in computing each new pixel's value.

Description:

This function performs a maximum filter on an image. A maximum filter makes the lighter pixels larger and shrinks the darker ones. The width and height determine the size of each original pixel's neighborhood to use to compute the maximum output pixels. Most applications will find that 3x3 or 5x5 works best.

Only the lpRect of the image is processed. Set lpRect = NULL to process the entire image.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask ().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Applicability: All except indexed with >1bpp

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    /* HIGEAR handle of image */
nErrCount = IG_IP_maximum ( hIGear, NULL, 5, 5 );

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_median

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_median (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    AT_DIMENSION nNeighborWidth,
    AT_DIMENSION nNeighborHeight
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the rectangular portion of the image to operate upon. If NULL, the entire image will be operated upon. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nNeighborWidth
Width of the neighborhood to include in computing each new pixel's value
nNeighborHeight
Height of the neighborhood

Description:

This function performs a median filter on an image. A median filter is useful for reducing spike or snow-like noise from an image. The width and height determine the size of each original pixel's neighborhood to use to compute the median output pixels. Most applications will find that 3x3 or 5x5 works best.

Only the lpRect of the image is processed. Set lpRect = NULL to process the entire image.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Applicability: All except indexed with >1bpp

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    /* HIGEAR handle of image */
nErrCount	 = IG_IP_median ( hIGear, NULL, 5, 5 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_merge

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_merge (
    HIGEAR hImage1,
    HIGEAR hImage2,
    LPAT_RECT lpImageRect2,
    AT_PIXPOS nDstX,
    AT_PIXPOS nDstY,
    AT_MODE nPix_op
);

Arguments:

hIGear1
HIGEAR handle of image
hIGear2
HIGEAR image to be merged into hIGear1; must have same bit depth as hIGear1.
lpImageRect2
Far pointer to an AT_RECT structure specifying the rectangular portion of hIGear2 to merge into hIGear1. upon. Set to NULL if you want to merge the entire image of hIGear2. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non - rectangular ROI defined by the mask.
nDstX
The x coordinate within hIGear1 at which to place the upper - left corner of hIGear2.
nDstY
The y coordinate within hIGear1 at which to place the upper-left corner of hIGear2.
nPix_op
A variable of constant type AT_MODE that specifies what type of arithmetic operation (merge method) to perform on all pixels of hIGear1 that have been intersected with pixels from hIGear2. Examples are IG_ARITH_ADD, which adds the pixel values of both images, and IG_ARITH_SUB, which subtracts the pixel values of hIGear2 from the corresponding pixel values of hIGear1. For the full list of available constants, see accucnst.h or see the description for IG_clipboard_paste_op_set () which also uses these constants for full list.

Description:

This function is used to "place" or merge one image into another. The images do not have to be the same size but do have to be the same bit depth. hImage2 is drawn into hImage1. The top left corner of hImage1 will be placed at nDstX, nDstY of hImage1. Any over-hanging pixels of hImage2 will be clipped, automatically. The nPix_op, which is defined in accucnst.h, determines how the pixels are combined.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can merge a rectangular subregion of HIGEAR2 into HIGEAR1. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask()functions, for more details.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear1,  /* HIGEAR handle of destination image   */
        hIGear2;  /* HIGEAR handle of image to be merged in */
AT_ERRCOUNT nErrcount; /* # of ImageGear errors on stack */
nErrcount = IG_IP_merge ( hIGear1, hIGear2, NULL, 0, 0,
IG_ARITH_OVER );

Sample: IMG_PROC, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_minimum

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_minimum (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    AT_DIMENSION nNeighborWidth,
    AT_DIMENSION nNeighborHeight
);

Arguments:

hIGear
HIGEAR handle of image.
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image to operate upon. If NULL, the entire image will be operated upon. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nNeighborWidth
Width of the neighborhood to include in computing each new pixel's value.
nNeighborHeight
Height of the neighborhood to include in computing each new pixel's value.

Description:

This function performs a minimum filter on an image. A minimum filter makes the lighter pixels smaller and the darker ones larger. The width and height determine the size of each original pixel's neighborhood to use to compute the minimum output pixels. Most applications will find that 3x3 or 5x5 works best.

Only the lpRect of the image is processed. Set lpRect = NULL to process the entire image.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear overrides the settings passed to the AT_RECT structure and uses the non-rectangular ROI defined by the HIGEAR mask. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask ().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Applicability: All except indexed with >1bpp

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR  hIGear;    /* HIGEAR handle of image */
nErrCount = IG_IP_minimum ( hIGear, NULL, 5, 5 );

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_NR_ROI_control_get

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_NR_ROI_control_get(
    HIGEAR hIGear,
    AT_MODE  nAttributeID,
    VOID FAR32 *lpData
);

Arguments:

hIGear
HIGEAR handle of image for which you would like to query ROI settings.
nAttributeID
Set to an AT_MODE constant for the type of attribute you wish to query. See below.
lpData
This returns the current setting of nAttributeID.

Description:

This function will return to you the current setting of any of the non-rectangular ROI control settings. Supply ImageGear with the HIGEAR handle of the image you are querying and the attribute (nAttributeID) whose setting you would like to query. The ROI settings available at the time of this writing are:

  • IG_CONTROL_NR_ROI_DIB: Returns the DIB which is currently set to be used as the mask HIGEAR.
  • IG_CONTROL_NR_ROI_REFERENCE_POINT: Returns the reference point of the mask.
  • IG_CONTROL_NR_ROI_REFERENCE_POINT_LEFT: Returns left point of the mask.
  • IG_CONTROL_NR_ROI_REFERENCE_POINT_TOP: Returns top point of the mask.
  • IG_CONTROL_NR_ROI_CONDITION: Queries the "condition" of the mask HIGEAR: whether it is set to be active or not active for the next IP or Clipboard operation.
  • IG_CONTROL_NR_ROI_VALIDATE: Returns TRUE if the current ROI mask is valid.

To change these settings and for details on how these controls can be used, see the description for IG_IP_NR_ROI_control_set ().

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT  	nErrcount;
HIGEAR 	hIGear;
BOOL 	bUseNonRect;
AT_POINT 	ptReferencePoint;
/* Find out whether the image rectangle for hIGear is set to be
overridden by a non-rectangular ROI    */
nErrcount = IG_IP_NR_ROI_control_get (hIGear,
IG_CONTROL_NR_ROI_STATE, &bUseNonRect);
/* Find out what the reference point for a mask HIGEAR is in the
hIGear */
nErrcount = IG_IP_NR_ROI_control_get (hIGear,
IG_CONTROL_NR_ROI_REFERENCE_POINT, &ptReferencePoint);

Sample: IMG_PROC, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_NR_ROI_control_set

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_NR_ROI_control_set(
    HIGEAR hIGear,
    AT_MODE nAttributeID,
    const LPVOID lpData
);

Arguments:

hIGear
HIGEAR handle of the image to which you wish make the non-rectangular ROI setting changes.
nAttributeID
Set to an AT_MODE constant for the non-rectangular ROI attribute you would like to set.
lpData
Set to the desired attribute setting.

Description:

This function allows you to set the non-rectangular ROI attributes associated with any HIGEAR that has an associated non-rectangular ROI mask. These attributes are only applicable for non-rectangular ROIs. Use IG_IP_NR_ROI_to_HIGEAR_mask () to create the mask image.

All ROI control settings have defined constants in accucnst.h which have a prefix of IG_CONTROL_NR_ROI_. The following is a list of each setting available at the time of this writing, and a description of what each does.

  • IG_CONTROL_NR_ROI_DIB: Sets the DIB to be used as the mask HIGEAR for the currently loaded HIGEAR image.
  • IG_CONTROL_NR_ROI_REFERENCE_POINT: Sets the position within the HIGEAR image at which the upper-left corner of the masking HIGEAR should be placed.
  • IG_CONTROL_NR_ROI_REFERENCE_POINT_LEFT: Sets the left point of the mask.
  • IG_CONTROL_NR_ROI_REFERENCE_POINT_TOP: Sets the top point of the mask.
  • IG_CONTROL_NR_ROI_CONDITION: Sets whether or not ImageGear should override the AT_RECT argument passed to its API. Set to TRUE if you would like ImageGear to use the non-rectangular ROI defined by the mask HIGEAR. Set to FALSE for ImageGear to use the rectangular ROI defined by the current image rectangle.
NOTE: IG_CONTROL_NR_ROI_CONDITION can also be set using IG_IP_NR_ROI_mask_associate() function.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT  	nErrcount;
HIGEAR 	hIGear;
BOOL 	bCondition;
HIGEAR 	hIGearMask;]
/* Find out whether the image rectangle for hIGear is set to be
overridden by a non-rectangular ROI   */
nErrcount = IG_IP_NR_ROI_control_set (hIGear,
IG_CONTROL_NR_ROI_DIB, (LPVOID) hIGearMask);
/* Find out what the reference point for a mask HIGEAR is in the
hIGear */
nErrcount = IG_IP_NR_ROI_control_set (hIGear,
IG_CONTROL_NR_ROI_CONDITION, (LPVOID) bCondition);

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_NR_ROI_mask_associate

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_NR_ROI_mask_associate(
    HIGEAR hIGear,
    LPAT_NR_ROI_MASK lpMask,
    BOOL bState
);

Arguments:

hIGear
HIGEAR handle of the image to associate with a non-rectangular ROI mask.
lpMask
Pass ImageGear a long pointer to a structure of type AT_NR_ROI_MASK that gives the HIGEAR handle of the mask HIGEAR.
bState
Set to TRUE if you want to make the mask "active", meaning that affected IP or clipboard operations will operate on the non-rectangular region only; set to FALSE if you want affected IP or clipboard operations to apply the image rectangle specified by the AT_RECT argument.

Description:

This function will associate a mask HIGEAR, as specified by the AT_NR_ROI_MASK structure, with the image referenced by hIGear. The bState argument determines whether or not the ROI defined by AT_NR_ROI_MASK should be made active. If you set bState to TRUE, ImageGear will override the AT_RECT argument passed to certain Image Processing and Clipboard API functions in favor of using the non-rectangular ROI. For example, the function IG_IP_contrast_adjust () takes an AT_RECT as an argument, so that you can adjust the contrast in a rectangular sub-region of an image, or adjust the contrast of the whole image (if you set the AT_RECT parameter to NULL). If you set bState to TRUE, when you next call IG_IP_contrast_adjust(), its AT_RECT argument will be ignored, or "overridden", and ImageGear will instead use the ROI described by the mask HIGEAR.

NOTE: If you provide an invalid mask HIGEAR, you will receive the error IGE_INVALID_MASK_ASSOCIATED.

No change will take place in the image until you perform an Image Processing or Clipboard operation. When using image processing functions the changes made are permanent if you save the image. For this reason, you may want to keep a copy of the original image so that the user can "undo" an operation.

  • The setting for bState, which ImageGear stores with the image can also be set using IG_IP_NR_ROI_control_set () with the constant IG_CONTROL_NR_ROI_CONDITION.
  • To reset the reference point in HIGEAR, call IG_IP_NR_ROI_control_set() with the constant IG_CONTROL_NR_ROI_REFERENCE_POINT.
  • Call IG_IP_NR_ROI_mask_unassociate () to clear the mask HIGEAR from its association with HIGEAR.

Applicability: All

NOTE: To create a non-rectangular region of interest call IG_IP_NR_ROI_to_HIGEAR_mask()function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT  	nErrcount;
HIGEAR 	hIGear;
AT_NR_ROI_MASK	 lpMask;
BOOL 	bState;
nErrcount = IG_IP_NR_ROI_mask_associate(hIGear, &lpMask, TRUE);

Sample: IMG_PROC, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_NR_ROI_mask_delete

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_NR_ROI_mask_delete (
    LPAT_NR_ROI_MASK lpMask
);

Arguments:

lpMask
A far pointer to the mask structure to delete.

Description:

This function deletes the mask HIGEAR created by IG_IP_NR_ROI_to_HIGEAR_mask (). When you are done using this mask, and have called the function IG_IP_NR_ROI_mask_unassociate (), you should call IG_IP_NR_ROI_mask_delete() to delete the mask and free up the memory allocated to it.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE:	See also: IG_IP_NR_ROI_to_HIGEAR_mask(),
IG_IP_NR_ROI_mask_associate(), and
IG_IP_NR_ROI_mask_unassociate()functions.

Example:

AT_ERRCOUNT  nErrcount;
HIGEAR hIGear;
AT_NR_ROI_MASK Mask
nErrcount = IG_IP_NR_ROI_mask_delete(&Mask);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_NR_ROI_mask_dilate

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_NR_ROI_mask_dilate(
    LPAT_NR_ROI_MASK lpMask,
    AT_INT pixCount
);

Arguments:

lpMask
ROI mask to dilate.
pixCount
Number of pixels to dilate the area by.

Description:

Dilates ROI mask by the specified number of pixels.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_NR_ROI_mask_erode

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_NR_ROI_mask_erode(
    LPAT_NR_ROI_MASK lpMask,
    AT_INT pixCount
);

Arguments:

lpMask
ROI mask to dilate.
pixCount
Number of pixels to erode the area by.

Description:

Erodes ROI mask by the specified number of pixels.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_NR_ROI_mask_unassociate

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_NR_ROI_mask_unassociate(HIGEAR
hIGear);

Arguments:

hIGear
HIGEAR handle to the image for which you would like to unassociate a mask HIGEAR.

Description:

This function clears the non-rectangular ROI information from a HIGEAR image. This function does not delete the mask HIGEAR, it only removes the reference to it from this HIGEAR. To delete the mask HIGEAR, call IG_IP_NR_ROI_mask_delete ().

NOTE: See the description for IG_IP_NR_ROI_mask_associate() function for more information.

Applicability: All

NOTE: To delete the mask HIGEAR, use IG_image_delete()function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT  nErrcount;
HIGEAR hIGear;
nErrcount = IG_IP_NR_ROI_mask_unassociate(hIGear);

Sample: IMG_PROC, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_NR_ROI_to_HIGEAR_mask

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_NR_ROI_to_HIGEAR_mask(
    AT_MODE nSimpleAreaTypeID,
    LPVOID lpAreaSegmentDesc,
    LPAT_NR_ROI_MASK lpNR_ROI
);

Arguments:

nSimpleAreaTypeID
Set to an AT_MODE constant that describes what kind of non-rectangular region of interest (ROI) you will be passing in. See supported AT_MODE constants below.
lpAreaSegmentDesc
Pass in an array of segment descriptors which will be used to reproduce/render the non-rectangular ROI as a mask. These segment descriptors can be points in the case of polygons, points and angles in the case of ellipses and so on. The segment descriptors use image coordinates to describe the mask.
lpNR_ROI
ImageGear returns you a structure of type AT_NR_ROI_MASK which contains the HIGEAR handle of the new mask HIGEAR and the "reference point" for its placement within HIGEAR.

Description:

This function is a non-rectangular ROI (region on interest) support function whose purpose is to build a non-rectangular ROI mask from a set of segment descriptors that you pass in, and to return a pointer to a non-rect ROI mask data structure. This non-rect ROI mask data structure (of type AT_NR_ROI_MASK) is then used in conjunction with other API functions to create, associate, modify, and apply the non-rect ROI to the source image.

The AT_NR_ROI_MASK structure, shown below, contains two important pieces of information. ptMaskOffset describes the coordinates for reference point for the mask HIGEAR. ptMaskOffset is the (x,y) position in the original HIGEAR at which the upper left corner of the mask HIGEAR should be placed. The mask HIGEAR is actually a rectangle which is calculated by determining the smallest rectangular area that can encompass the entire non-rectangular ROI. We refer to this area as the "bounding rectangle". Within the mask, which represents the bounding rectangle, a pixel value of 1 indicates that the pixel is within the non-rect ROI; a pixel value of 0 indicates that the pixel is outside the non-rect ROI.

typedef struct tag	  AT_NR_ROI_MASK
{
    AT_POINT ptMaskOffet;
    HIGEAR hMask;

}   AT_NR_ROI_MASK, FAR* LPAT_NR_ROI_MASK;

The second member of the mask structure is a HIGEAR handle to the actual mask image. The mask HIGEAR is a run length-encoded binary image.

You must also pass this function an argument that specifies whether the region of interest is elliptical, polygonal, or rectangular (the default), using one of the following constants:

  • IG_ROI_IS_RECTANGLE
  • IG_ROI_IS_ELLIPSE
  • IG_ROI_IS_POLYGON

The default ROI type, which is IG_ROI_IS_RECTANGLE means that when this mask is associated with and activated for an image, all affected API should use the AT_RECT argument that is part of their argument list. If nSimpleAreaTypeID is set to IG_ROI_IS_ELLIPSE or IG_ROI_IS_POLYGON, all affected API will override their AT_RECT arguments and instead look for an associated AT_NR_ROI_MASK.

Applicability: N/A (this function does not operate on an image)

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS. The lpNR_ROI parameter will store the mask HIGEAR information structure when the function return value is IGE_SUCCESS.

NOTE: Use IG_IP_NR_ROI_mask_associate() function to associate the mask HIGEAR with a HIGEAR image.

Example:

AT_ERRCOUNT  	nErrcount;
HIGEAR 	hIGear;
AT_NR_ROI_MASK	 region;
AT_POINT 	ROI[];
nErrcount =
    IG_IP_NR_ROI_to_HIGEAR_mask(IG_ROI_IS_POLYGON, &ROI[0],
&region);

Sample: IMG_PROC, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_open

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_open(
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    LPAT_INT lpMatrix,
    AT_INT nMatrixSize
);

Parameters:

hIGear
Image to apply effect to.
lpRect
Image rectangle to process.
lpMatrix
Matrix specifying a structuring element for the operation
nMatrixSize
Matrix edge size.

Description:

This method applies opening effect to provided raster page using the specified structure element. This method is applicable to any grayscale image (image with [Gy] color space).

Applicability:

1-bit and 8-bit grayscale

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_pixel_format_convert

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_pixel_format_convert(
    HIGPIXEL hPixel,
    enumIGColorSpaceIDs SrcColorSpace,
    const AT_INT *SrcChannelDepths,
    AT_RGBQUAD *SrcPalette,
    enumIGColorSpaceIDs DstColorSpace,
    AT_INT DstChannelCount,
    const AT_INT *DstChannelDepths,
    AT_RGBQUAD *DstPalette
);

Arguments:

hPixel
Pixel to convert to the new format.
SrcColorSpace
Source color space of the pixel.
SrcChannelDepths
Source channel depths of the pixel. Length of the array should be equal to number of channels used by the hPixel.
SrcPalette
Source palette used by the pixel, if its color space is Indexed, or null otherwise.
DstColorSpace
Color space to convert the pixel to.
DstChannelCount
Number of channels for the pixel after conversion.
DstChannelDepths
New channel depths for the pixel. Length of the array should correspond to the dstColorSpace parameter.
DstPalette
Destination palette for the pixel, if destination color space is Indexed, or null otherwise.

Description:

This method converts a single pixel to new color space and channel depths.

Please note, using this function in a cycle for large array of pixels could be inefficient. Consider creating a temporary HIGEAR and converting its color space and channel depths in this case.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_pixel_format_convert_to_image_format

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_pixel_format_convert_to_image_format(
    HIGPIXEL hPixel,
    enumIGColorSpaceIDs SrcColorSpace,
    const AT_INT *SrcChannelDepths,
    AT_RGBQUAD *SrcPalette,
    HIGEAR hIGear
);

Arguments:

hPixel
Pixel to convert to the new format.
SrcColorSpace
Source color space of the pixel.
SrcChannelDepths
Source channel depths of the pixel. Length of the array should be equal to number of channels used by the hPixel.
SrcPalette
Source palette used by the pixel, if its color space is Indexed, or null otherwise.
hIGear
Image which color space, chanel depths and palette will be used for destination format when converting the pixel.

Description:

This method converts a single pixel to color space and channel depths of the specified HIGEAR image.

Please note, using this function in a cycle for large array of pixels could be inefficient. Consider creating a temporary HIGEAR and converting its color space and channel depths in this case.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_process_area

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_process_area(
    HIGEAR hIGear,
    LPAT_VOID processStruct,
    LPFNIG_PROCESS_PIXEL processFun,
    LPAT_RECT lpRect
);

Arguments:

hIGear
Image to be processed.
processStruct
A pointer to a user-defined structure that will be passed to the callback function.
processFun
User-defined callback function that processes pixels.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.

Description:

Processes all pixels in the ROI area using a specified pixel processor.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_pseudocolor_limits

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_pseudocolor_limits (
    HIGEAR hIGear,
    LPAT_RGB lpRGB_Low,
    LPAT_RGB lpRGB_High,
    AT_PIXEL nLow,
    AT_PIXEL nHigh
);

Arguments:

hIGeaR
HIGEAR handle of 8-bit grayscale image to be colored
lpRGB_Low
Far pointer to an AT_RGB struct (note: B-G-R) specifying the color to apply to all pixels below the nLow value
lpRGB_High
Far pointer to an AT_RGB struct (note: B-G-R) specifying the color to apply to all pixels above the nHigh value
nLow
All pixels below this value are colored
nHigh
All pixels above this value are colored

Description:

This function colors all pixels in an 8-bit gray level image whose values are outside the range nLow to nHigh. Those above the range receive the color pointed to by lpRGB_High, and those below the range receive the color pointed to by lpRGB_Low. This function can be used to see how much of the image is saturated or unsaturated.

NOTE: Remember that the order in the RGB structure is B-G-R. See the section Device- Independent Bitmaps (DIB) for more information.

Applicability: 8bpp grayscale

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image  */
AT_RGB cLowColor, cHighColor; /* The colors to apply */
AT_PIXEL nLow, nHigh;  /* Where to apply them  */
cLowColor.b  = cLowColor.g  = 0;  cLowColor.r  = 255; /* bright
red  */
cHighColor.b = cHighColor.r = 0;  cHighColor.g = 255; /* bright
green*/
    /* Retain image colors for pixel values 25 through 225:
*/
nLow = 25;  nHigh = 225;
IG_IP_pseudocolor_limits ( hIGear, &cLowColor, &cHighColor,
nLow, nHigh );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_pseudocolor_small_grads

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_pseudocolor_small_grads (
    HIGEAR hIGear,
    UINT nSlope
);

Arguments:

hIGear
HIGEAR handle of 8-bit grayscale image to be colored
nSlope
An integer from 1 to 255. Higher values increase colors faster.

Description:

This function colors an 8-bit gray level image such that small gradients are exposed. The greater the value of nSlope, the faster the color will change for a given rate of change of the pixel value.

Applicability: 8bpp grayscale

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;
if ( IG_image_is_valid(hIGear) )
    if ( IG_image_is_gray(hIGear) )
    IG_IP_pseudocolor_small_grads ( hIGear, 10 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_remove_redeye

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_remove_redeye(
    HIGEAR hIGear,
    AT_DOUBLE dblThreshold,
    AT_DOUBLE dblBrightness,
    LPAT_RECT lpRect
);

Arguments:

hIGear
Image to process.
dblThreshold
A value in the range 0.5..2 that specifies a part of the red component in the pixel color.
dblBrightness
Scaling factor for brightness of the pixel after processing. The range is -1...1.
lpRect
Rectangular area to apply the effect to, or NULL for whole image.

Description:

This function processes the given image using a redeye removal algorithm. The algorithm can be applied to the entire image, to a rectangular ROI defined by the lpRect parameter, or to a non-rectangular ROI set using the IG_IP_NR_ROI_mask_associate function. The function IG_IP_detect_redeye_area can assist in defining a non-rectanular ROI suitable for use with this function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IP_remove_tilt

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_remove_tilt(
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    AT_BOOL bRemoveMean
);

Arguments:

hIGear
HIGEAR handle of image to be processed
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image. Before ImageGear performs this operation it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
bRemoveMean
Remove the mean from the detilted image, giving it zero-mean statistics.

Description:

This function computes the best-fit plane for an image, and then subtracts that plane from the image to produce the output. This is very handy for correcting illumination gradients in a poorly digitized image.

If bRemoveMean argument is set to TRUE, then remove mean from image.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Bits Per Pixel:

8, 16, or 32bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear; /* HIGEAR handle of image */
AT_BOOL 	bRemoveMean;	/* TRUE = remove mean */
AT_RECT 	lpRect; /* rectangle to process */
...
IG_IP_remove_tilt( hIGear, lpRect, bRemoveMean);
...

Sample:

IMG_PROC


IG_IP_resize

Group: Image Processing
NOTE: Please, use new upgraded function IG_IP_resize_bkgrnd(). See note below.

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_resize (
    HIGEAR hIGear,
    AT_DIMENSION nNewWidth,
    AT_DIMENSION nNewHeight,
    AT_MODE nInterpMethod
);

Arguments:

hIGear
HIGEAR handle of image to resize
nNewWidth
Width that the image is to be after resize
nNewHeight
Height that the image is to be after resize
nInterpMethod
IG_INTERPOLATION_NONE, or the interpolation method to use to compute the new pixel values for the resized image. The IG_INTERPOLATION_... constants are listed in file accucnst.h:
IG_INTERPOLATION_NONE
IG_INTERPOLATION_AVERAGE
IG_INTERPOLATION_BILINEAR
IG_INTERPOLATION_NEAREST_NEIGHBOR
IG_INTERPOLATION_PADDING
IG_INTERPOLATION_GRAYSCALE
IG_INTERPOLATION_PRESERVE_WHITE
IG_INTERPOLATION_PRESERVE_BLACK
IG_INTERPOLATION_BICUBIC

Description:

This function will change the dimensions of the image referenced by hIGear, by changing the dimensions of the DIB image bitmap. The image data in the bitmap will be stretched or compressed as necessary, to fit the new dimensions. Use nNewWidth and nNewHeight to specify the new dimensions.

During re-sizing, new pixel values which previously did not exist in the image, may be introduced due to interpolation. If you want to prevent this, such as to preserve the original number of palette entries used, then specify IG_INTERPOLATION_NONE. In this case, only pixel values that occur in the original image will result in the resized image.

If you try to apply some interpolation methods to a 4-bit image, you will receive the error IGE_PROC_INVAL_FOR_BIT_COUNT. If you try to apply some interpolation methods to an 8-bit indexed image you will receive this same error and also IGE_PROC_INVAL_FOR_8BIT_INDEXED.

NOTE: IG_IP_resize_bkgrnd() works for 16-bit gray level images using the following resize modes:
IG_INTERPOLATION_NONE
IG_INTERPOLATION_AVERAGE IG_INTERPOLATION_BILINEAR

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call if there were no errors.

Example:

HIGEAR hIGear;    /* Handle of image to be resized  */
AT_DIMENSION nNewWid,    /* New width the image is to be  */
        nNewHi;    /* New height  */
AT_DIMENSION nOldWid,  /* Old width of image  */
        nOldHi,    /* Old height  */
        nBpp;      /* Bits per pixel (not used below) */
AT_ERRCOUNT nErrcount;/* Returned count of errors  */
/* Resize image to 1.5 times its present width, but same height:
*/
/* First, obtain current dimensions:  */
nErrcount = IG_image_dimensions_get ( hIGear1, &nOldWid,
&nOldHi, &nBpp );
if ( nErrcount == 0 )     /* If no errors doing that:  */
{
/* Multiply no. of pixels per row by 1.5:   */
    nNewWid = (nOldWid * 3) / 2;
    nNewHi  =  nOldHi;    /* Keep image the same height  */
    /* Resize, with no interpolation:     */
    nErrcount = IG_IP_resize ( hIGear, nNewWid, nNewHi,
                                             IG_INTERPOLATION_NONE
);
}
if ( nErrcount } { ... }   /* If errors anywhere above, process
here  */
NOTE: The functionality of this API call has been upgraded and supported by the new function IG_IP_resize_bkgrnd(). The reason that this new function has been created is that the old function does not allow you to change the background color around the image being resized. In the interest of backward compatibility, we have left the old function in its original form and have retained support for it. If you have already used the old function in your code, it is not mandatory that you modify your code, but it is recommended.

Sample: IMG_PROC, TIMING, ART, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_resize_bkgrnd

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_resize_bkgrnd (
    HIGEAR hIGear,
    AT_DIMENSION nNewWidth,
    AT_DIMENSION nNewHeight,
    AT_MODE nInterpMethod,
    LPAT_PIXEL lpBkgColor
);

Arguments:

hIGear
HIGEAR handle of image to resize
nNewWidth
Width that the image is to be after resize
nNewHeight
Height that the image is to be after resize
nInterpMethod
IG_INTERPOLATION_NONE, or the interpolation method to use to compute the new pixel values for the resized image. The IG_INTERPOLATION_... constants are listed in file accucnst.h.
0 - Standard algorithm
1 - Standard (average) interpolation
2 - Bilinear
3 - Nearest Neighbor interpolation
4 - Resize by adding padding to the image or by cropping the image (this is not an interpolaiton method.)
5 - Scale to Gray
6 - Peserve White
7 - Preserve Black
8 - Bicubic interpolations
lpBkgColor
A far pointer to the RGB or pixel value that specifies the background color to be used in the displaced areas after the image has been resized when use resize with padding method.

Description:

This function will change the dimensions of the image referenced by hIGear, by changing the dimensions of the DIB image bitmap. The image data in the bitmap will be stretched or compressed as necessary, to fit the new dimensions. Use nNewWidth and nNewHeight to specify the new dimensions. Set lpBkgColor to the color you would like ImageGear to paint the pixels in the image window which are exposed after the image has been resized. This background color is only applicable when you are resizing the image to a smaller size.

During re-sizing, new pixel values which previously did not exist in the image, may be introduced due to interpolation. If you want to prevent this, such as to preserve the original number of palette entries used, then specify IG_INTERPOLATION_NONE. In this case only pixel values that occur in the original image will result in the resized image.

NOTE: IG_IP_resize_bkgrnd() works for 16-bit gray level images using the following resize modes:
IG_INTERPOLATION_NONE
IG_INTERPOLATION_AVERAGE IG_INTERPOLATION_BILINEAR

Applicability: All

Return Value:

The following table illustrates what happens when you try to apply interpolation (or none) to images of different bit depths.

Bit
Depth
None,
Padding,
Nearest
Neighbor
Average and
Bilinear
Interpolation
Preserve Black,
Preserve White,
Scale-to-gray
Bicubic
Interpolation
1
+
+
+
IG error
4
+
IG error
IG error
IG error
8i
+
IG error
IG error
IG error
8-bit gray
level
+
+
IG error
+
9-16-bit
gray level
+ (see note below)
+
IG error
+
24 and others
+
+
IG error
+

NOTE: Setting the _PADDING means that if you increase the size of the image, it is padded to the new boundaries. If you display the image, you see white space to the right and bottom of the original image. If you decrease the size of the image with _PADDING, the image is cropped.

Example:

HIGEAR hIGear;    /* Handle of image to be resized  */
AT_DIMENSION	 	nNewWid,   /* New width the image is to be   */
        nNewHi;    /* New height   */
AT_DIMENSION	 	nOldWid,   /* Old width of image  */
        nOldHi,    /* Old height    */
        nBpp;      /* Bits per pixel (not used below) */
AT_ERRCOUNT	 	nErrcount; /* Returned count of errors  */
AT_RGB		rgb;       /* color of background; RGB value  */
/* Enlarge image to 1.5 times its present width, but same
height, padding with the green color up to right: */
/* First, obtain current dimensions:     */
nErrcount = IG_image_dimensions_get ( hIGear1, &nOldWid,
&nOldHi, &nBpp );
if ( nErrcount == 0 )    /* If no errors doing that:  */
{
/* Multiply no. of pixels per row by 1.5:  */
    nNewWid = (nOldWid * 3) / 2;
    nNewHi  =  nOldHi;     /* Keep image the same height  */
    /* Resize, with padding:     */
    rgb.r = 0;
    rgb.g = 255;
    rgb.b = 0;
    nErrcount = IG_IP_resize_bkgrnd ( hIGear, nNewWid,
    nNewHi,IG_INTERPOLATION_PADDING, (LPAT_PIXEL)&rgb);
}
if ( nErrcount } { ... }     /* If errors anywhere above, process
here  */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_resize_bkgrnd_ex

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_resize_bkgrnd_ex(
    [IN/OUT] HIGEAR hIGear,
    [IN] AT_DIMENSION nNewWidth,
    [IN] AT_DIMENSION nNewHeight,
    [IN] AT_MODE InterpMethid,
    [IN] AT_MODE lpBkgColor,
    [IN] DWORD dwFlags,
    [IN] INT nValue
);

Arguments:

hIGear
HIGEAR handle of the image to resize
newWidth
The width of the resized image
nNewHeight
The height of the resized image
nInterpMethod
IG_INTERPOLATION_NONE, or the interpolation method to use to compute the new pixel values for the resized image. The IG_INTERPOLATION_... constants are listed in accucnst.h file.
0 - Standard algorithm
1 - Standard (average) interpolation
2 - Bilinear
3 - Nearest Neighbor interpolation
4 - Resize by adding padding to the image or by cropping the image (this is not an interpolaiton method.)
5 - Scale to Gray
6 - Peserve White
7 - Preserve Black
8 - Bicubic interpolations
lpBkgColor
A far pointer to the RGB or pixel value that specifies the background color to be used in the displaced areas after the image is resized using padding method.
dwFlags
The contents of this parameter depends upon the value of nInterpMethod. This is currently not used.
nValue
The contents of this parameter depends upon the value of nInterpMethod. This is currently used only if nInterpMethod is one of the following:
  • IG_INTERPOLATION_GRAYSCALE - nValue can be from 0 to 100. It takes the proportion of pixels from entry 1 to entry 0 (white/black)
  • IG_INTERPOLATION_PRESERVE_WHITE - nValue can be from 0 to 100. It indicates the threshold value of the amount of white color to include.
  • IG_INTERPOLATION_PRESERVE_BLACK - nValue can be from 0 to 100. It indicates the threshold value of the amount of black color to include.

Description:

This function changes the dimensions of the image referenced by hIGear by changing the dimensions of the DIB image bitmap. The image data in the bitmap is stretched or compressed as necessary, to fit the new dimensions. Use nNewWidth and nNewHeight to specify the new dimensions. Set lpBkgColor to the color you would like ImageGear to paint the pixels in the image window that are exposed after the image has been resized. This background color is only applicable when you are resizing the image to a smaller size.

During re-sizing, new pixel values that previously did not exist in the image, may be introduced due to interpolation. If you want to prevent this, (to preserve the original number of palette entries used, for example) specify IG_INTERPOLATION_NONE. In this case, only the pixel values that occur in the original image will result in the resized image.

NOTE: IG_IP_resize_bkgrnd_ex() works for 16-bit gray level images using the following resize modes:
IG_INTERPOLATION_NONE
IG_INTERPOLATION_AVERAGE
IG_INTERPOLATION_BILINEAR

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Interpolation Specs:

Bit Depth
None,
Padding,
Nearest
Neighbor
Average and
Bi-linear
Interpolation
Preserve Black,
Preserve White,
Scale-to-gray
Bicubic
Interpolation
1
+
+
+
IG error
4
+
IG error
IG error
IG error
8i
+
IG error
IG error
IG error
8-bit gray level
+
+
IG error
+
9-16-bit gray
level
+(see note below)
+
IG error
+
24 and others
+
+
IG error
+

NOTE: Setting the _PADDING means that if you increase the size of the image, it is padded to the new boundaries. If you display the image, you see white space to the right and bottom of the original image. If you decrease the size of the image with _PADDING, the image is cropped.

Example:

HIGEAR hIGear;      /* Handle of image to be resized */
AT_DIMENSION nNewWid,     /* New width the image is to be */
        nNewHi;      /* New height  */
AT_DIMENSION nOldWid,     /* Old width of image  */
        nOldHi,      /* Old height  */
        nBpp;        /* Bits per pixel (not used below)  */
AT_ERRCOUNT nErrcount;   /* Returned count of errors  */
AT_RGB rgb;  /* color of background; RGB value */
/* Enlarge image to 1.5 times its present width, but same
height, padding with the green color up to right:  */
/* First, obtain current dimensions:    */
nErrcount = IG_image_dimensions_get ( hIGear1, &nOldWid,
&nOldHi, &nBpp );
if ( nErrcount == 0 )     /* If no errors doing that: */
{
/* Multiply no. of pixels per row by 1.5:    */
    nNewWid = (nOldWid * 3) / 2;
    nNewHi  =  nOldHi;      /* Keep image the same height  */
    /* Resize, with padding:       */
    rgb.r = 0;
    rgb.g = 255;
    rgb.b = 0;
    nErrcount = IG_IP_resize_bkgrnd_ex ( hIGear, nNewWid,
    nNewHi, IG_INTERPOLATION_PADDING, (LPAT_PIXEL)&rgb, 0, 0 );
}
if ( nErrcount } { ... }      /* If errors anywhere above, process
here  */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_resize_canvas

Group: Image Processing

Declaration:

AT_ERRCOUNT LACCUAPI IG_IP_resize_canvas(
    HIGEAR hIGear,
    AT_DIMENSION new_width,
    AT_DIMENSION new_height,
    AT_PIXPOS nXPos,
    AT_PIXPOS nYPos,
    LPAT_PIXEL lpBkgColor
);

Arguments:

hIGear
Image to process.
new_width
Width of the image after resize.
new_height
Height of the image after resize.
nXPos
X offset at which to put left top corner of the image after resize.
nYPos
Y offset at which to put left top corner of the image after resize.
lpBkgColor
Color to fill the empty area.

Description:

This function changes the dimensions of the image referenced by hIGear. The image data in the bitmap is not stretched or compressed, but copied to the specified offset in the new image.

Applicability:

All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IMG_PROC


IG_IP_resize_ex

Group: Image Processing
NOTE: Please, use new upgraded function IG_IP_resize_bkgrnd_ex(). See note below.

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_resize_ex(
    [IN/OUT] HIGEAR hIGear,
    [IN] AT_DIMENSION nNewWidth,
    [IN] AT_DIMENSION nNewHeight,
    [IN] AT_MODE nInterpMethod,
    [IN] DWORD dwFlags,
    [IN] INT nValue
);

Arguments:

hIGear
HIGEAR handle of the image to resize
nNewWidth
Width to which the image is to be resized.
nNewHeight
Height to which the image is to be resized.
nInterpMethod
IG_INTERPOLATION_NONE, or the interpolation method to use to compute the new pixel values for the resized image. The IG_INTERPOLATION_... constants are listed in file accucnst.h.
0 - Standard algorithm
1 - Standard (average) interpolation
2 - Bilinear
3 - Nearest Neighbor interpolation
4 - Resize by adding padding to the image or by cropping the image (this is not an interpolaiton method.)
5 - Scale to Gray
6 - Peserve White
7 - Preserve Black
8 - Bicubic interpolations
dwFlags
The contents of this parameter depends upon the value of nInterpMethod. It is currently not used.
nValue
The contents of this parameter depends upon the value of nInterpMethod. It is currently used only if nInterpMethod is used.
  • IG_INTERPOLATION_GRAYSCALE - nValue can be from 0 to 100. It takes the proportion of pixels from entry 1 to entry 0 (white/black)
  • IG_INTERPOLATION_PRESERVE_WHITE - nValue can be from 0 to 100. It indicates the threshold value of the amount of white color to include.
  • IG_INTERPOLATION_PRESERVE_BLACK - nValue can be from 0 to 100. It indicates the threshold value of the amount of black color to include.

Description:

This function changes the dimensions of the image referenced by hIGear by changing the dimensions of the DIB image bitmap. The image data in the bitmap will be stretched or compressed as necessary, to fit the new dimensions. Use nNewWidth and nNewHeight to specify the new dimensions.

During re-sizing, new pixel values that previously did not exist in the image may be introduced due to interpolation. If you want to prevent this, such as to preserve the original number of palette entries used, then specify IG_INTERPOLATION_NONE. In this case, the only pixel values that occur in the original image will result in the resized image.

If you try to add interpolation to a 4-bit image, you will receive the error IGE_PROC_INVAL_FOR_BIT_COUNT. If you try to use interpolation for an 8-bit indexed image you will receive this same error and also IGE_PROC_INVAL_FOR_8BIT_INDEXED.

NOTE: IG_IP_resize_bkgrnd_ex() works for 16-bit gray level images using the following resize modes:
IG_INTERPOLATION_NONE
IG_INTERPOLATION_AVERAGE
IG_INTERPOLATION_BILINEAR

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* Handle of image to be resized */
AT_DIMENSION  nNewWid,    /* New width the image is to be  */
        nNewHi;     /* New height   */
AT_DIMENSION nOldWid,   /* Old width of image  */
        nOldHi,     /* Old height   */
        nBpp;       /* Bits per pixel (not used below)  */
AT_ERRCOUNT nErrcount; /* Returned count of errors  */
/* Resize image to 1.5 times its present width, but same height:
*/
/* First, obtain current dimensions:     */
nErrcount = IG_image_dimensions_get ( hIGear1, &nOldWid,
&nOldHi, &nBpp );
if ( nErrcount == 0 )     /* If no errors doing that:  */
{
/* Multiply no. of pixels per row by 1.5:    */
    nNewWid = (nOldWid * 3) / 2;
    nNewHi  =  nOldHi;       /* Keep image the same height */
    /* Resize, with no interpolation:      */
    nErrcount = IG_IP_resize_ex ( hIGear, nNewWid,
nNewHi,IG_INTERPOLATION_NONE, 0, 0 );
}
if ( nErrcount } { ... }     /* If errors anywhere above, process
here  */
NOTE: The functionality of this API call has been upgraded and supported by the new function IG_IP_resize_bkgrnd_ex(). The reason that this new function has been created is that the old function does not allow you to change the background color around the image being resized. In the interest of backward compatibility, we have left the old function in its original form and have retained support for it. If you have already used the old function in your code, it is not mandatory that you modify your code, but it is recommended.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_RGB_to_hue

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_RGB_to_hue (
    const LPAT_RGB lpRGB,
    LPDOUBLE lpHue
);

Arguments:

lpRGB
A long pointer to a structure of type AT_RGB containing three bytes of color information.
lpHue
A long pointer to a double containing the hue value that corresponds to the color specified by lpRGB

Description:

This function will convert a 24-bit RGB value to a hue value. You pass it a pointer to the AT_RGB structure of your choice, and it returns the hue angle (0.0 to 360) to you. This is useful before calling IG_FX_chroma_key () which requires a hue angle as one of its arguments. (ImageGear's pixel access functions only read and write RGB values.) You can use them to read the RGB value of a "background" pixel in the image which you wish to make transparent.

Applicability: N/A (this function does not operate on an image)

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

See the example for IG_FX_chroma_key ()function.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_rotate_any_angle

Group: Image Processing
NOTE: Please, use new upgraded function IG_IP_rotate_any_angle_bkgrnd(). See note below.

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_rotate_any_angle (
    HIGEAR hIGear,
    DOUBLE angle,
    AT_MODE rotate_mode
);

Arguments:

hIGear
HIGEAR handle of image
angle
Angle to rotate, in degrees; this may be set to a positive or negative value.
rotate_mode
An integer variable of type AT_MODE defined in accucnst.h. The value can be either:
  • IG_ROTATE_CLIP - clip the rotated image to keep the image bitmap the same size or
  • IG_ROTATE_EXPAND - expand the size of the bitmap if necessary to retain the entire rotated image.

Description:

This function rotates the image about its center through the angle indicated by angle. (angle must be expressed in degrees, such as 45.0 to rotate 45 degrees.) rotate_mode is examined to determined whether to clip the image or resize the bitmap.

If you have called this function with the IG_ROTATE_EXPAND setting, you can use IG_IP_rotate_compute_size () to calculate the new dimensions of the bitmap.

Applicability: All

NOTE: The functionality of this API call has been upgraded and supported by the new function IG_IP_rotate_any_angle_bkgrnd(). The reason that this new function has been created is that the old function does not allow you to change the background color around the image being rotated. In the interest of backward compatibility, we have left the old function in its original form and have retained support for it. If you have already used the old function in your code, it is not mandatory that you modify your code, but it is recommended.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;      /* HIGEAR handle of image to rotate  */
DOUBLE angle;    /* Angle to rotate counterclockwise  */
AT_ERRCOUNT nErrcount;   /* Returned number of errors       */
 ...
angle  = 45.0           /* Set angle to rotate  */
nErrcount = IG_IP_rotate_any_angle ( hIGear, angle,
IG_ROTATE_CLIP );

Sample: TIMING

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_rotate_any_angle_bkgrnd

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_rotate_any_angle_bkgrnd (
    HIGEAR hIGear,
    DOUBLE angle,
    AT_MODE rotate_mode,
    LPAT_PIXEL lpBkgrndColor
);

Arguments:

hIGear
HIGEAR handle of image
angle
Set to a positive or negative value for angle of rotation.
rotate_mode
An integer variable of type AT_MODE defined in accucnst.h. The value can be either:
  • IG_ROTATE_CLIP - clip the rotated image to keep the image bitmap the same size or
  • IG_ROTATE_EXPAND - expand the size of the bitmap if necessary to retain the entire rotated image.
lpBkgrndColor
A far pointer to the RGB or pixel value that specifies the background color to be used in the displaced areas after the image has been rotated.

Description:

This function rotates the image about its center through the angle indicated by angle. (angle must be expressed in degrees, such as 45.0 to rotate 45 degrees.) rotate_mode is examined to determined whether to clip the image or resize the bitmap. Set lpBkgrndColor to the color that you would like to display in the background that was previously covered by the image before it was rotated.

If you have called this function with the IG_ROTATE_EXPAND setting, you can use IG_IP_rotate_compute_size () to calculate the new dimensions of the bitmap.

NOTE: You can only rotate PDF/PS images in 90 degree increments.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;      /* HIGEAR handle of image to rotate  */
DOUBLE angle;    /* Angle to rotate counterclockwise  */
AT_ERRCOUNT nErrcount;   /* Returned number of errors  */
AT_RGB rgb;         /* color of background; RGB value */
 ...
rgb.r = 0;
rgb.g = 255;
rgb.b = 0;
angle  = 45.0     /* Set angle to rotate  */
nErrcount = IG_IP_rotate_any_angle_bkgrnd ( hIGear, angle,
IG_ROTATE_CLIP, (LPAT_PIXEL)&rgb);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_rotate_any_angle_ex

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_rotate_any_angle_ex (
    HIGEAR hIGear,
    DOUBLE angle,
    AT_MODE rotate_mode,
    LPAT_PIXEL lpBkgrndColor,
    AT_MODE interpolation
);

Arguments:

hIGear
HIGEAR handle of image
angle
Set to a positive or negative value for angle of rotation.
rotate_mode
An integer variable of type AT_MODE defined in accucnst.h. The value can be either:
  • IG_ROTATE_CLIP - clip the rotated image to keep the image bitmap the same size or
  • IG_ROTATE_EXPAND - expand the size of the bitmap if necessary to retain the entire rotated image.
lpBkgrndColor
A far pointer to the RGB or pixel value that specifies the background color to be used in the displaced areas after the image has been rotated.
interpolation
Interpolation to use for rotation (IG_INTERPOLATION_NONE, IG_INTERPOLATION_BILINEAR, or IG_INTERPOLATION_BICUBIC)

Description:

This function rotates the image about its center through the angle indicated by angle. (angle must be expressed in degrees, such as 45.0 to rotate 45 degrees.) rotate_mode is examined to determined whether to clip the image or resize the bitmap. Set lpBkgrndColor to the color that you would like to display in the background that was previously covered by the image before it was rotated. The interpolation parameter controls what type of interpolation, if any, is used for rotation.

If you have called this function with the IG_ROTATE_EXPAND setting, you can use IG_IP_rotate_compute_size () to calculate the new dimensions of the bitmap.

For highest quality, bilinear interpolation is recommended, especially if the rotation angle is small (less than 5 degrees) and/or the image will be rotated multiple times (not recommended). Bicubic interpolation can be used to achieve a slightly sharper appearance.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;      /* HIGEAR handle of image to rotate  */
DOUBLE angle;    /* Angle to rotate counterclockwise  */
AT_ERRCOUNT nErrcount;   /* Returned number of errors  */
AT_RGB rgb;         /* color of background; RGB value */
 ...
rgb.r = 0;
rgb.g = 255;
rgb.b = 0;
angle  = 45.0     /* Set angle to rotate  */
nErrcount = IG_IP_rotate_any_angle_bkgrnd ( hIGear, angle,
IG_ROTATE_CLIP, (LPAT_PIXEL)&rgb);
IG_INTERPOLATION_BILINEAR

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_rotate_compute_size

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_rotate_compute_size (
    HIGEAR hIGear,
    DOUBLE dblAngle,
    AT_MODE nRotateMode,
    LPAT_DIMENSION lpWidth,
    LPAT_DIMENSION lpHeight
);

Arguments:

hIGear
HIGEAR handle of image to compute size of
dblAngle
The angle (in degrees) that you want to rotate the image
nRotateMode
An integer variable of type AT_MODE defined in accucnst.h. The value can be either:
  • IG_ROTATE_CLIP - clip the rotated image to keep the image bitmap the same size or
  • IG_ROTATE_EXPAND - expand the size of the bitmap if necessary to retain the entire rotated image.
lpWidth
A long pointer in which is returned the new width of the bitmap after rotation
lpHeight
A long pointer in which is returned the new height of the bitmap after rotation.

Description:

This function can be used to compute the new height and width of hIGear after it has been rotated using IG_IP_rotate_any_angle ()or IG_IP_rotate_any_angle_bkgrnd ()functions. You may use it before rotation, to determine the dimensions of the new rotated image. This way, you can estimate the amount of memory that will be needed to hold the new image.

This function is actually only relevant if the mode of rotation is set to IG_ROTATE_EXPAND. Otherwise, the height and width would remain the same after rotation. (with clipping.)

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;       /* HIGEAR handle of image  */
DOUBLE dblAngle;             /* Angle of rotation  */
AT_DIMENSION Width, Height;  /* New height and width of image
*/
AT_ERRCOUNT nErrcount;       /* Totally of ImageGear errors    */
AT_DIMENSION szAngleWidth[46];   /* Hold widths at diff angles
*/
INT  i;
/* loop will store the resulting widths of hIGear when it is set
to angles between 0 and 45 degrees. Results stored to array
*/
for (i = 0; i < 46; i++)
{
nErrcount = IG_IP_rotate_compute_size (hIGear, (DOUBLE)i,
IG_ROTATE_EXPAND, &Width, &Height);
szAngleWidth[i] = Width;
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_rotate_multiple_90

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_rotate_multiple_90 (
    HIGEAR hIGear,
    AT_MODE nMult_90_Mode
);

Arguments:

hIGear
HIGEAR handle of image to rotate
nMult_90_Mode
One of IG_ROTATE_0, IG_ROTATE_90, IG_ROTATE_180, or IG_ROTATE_270

Description:

This function will rotate the image referenced by hIGear clockwise about its center. The rotation must be a multiple of 90 degrees. If the rotation is either 90 or 270 degrees, the previous width of the image becomes the new height, and the previous height of the image becomes the new width. IG_ROTATE_0 does nothing and is included for completeness only.

To rotate by an arbitrary angle that may not be a multiple of 90 degrees, use functions IG_IP_rotate_any_angle ()or IG_IP_rotate_any_angle_bkgrnd ().

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

/* HIGEAR     handle of image to rotate   */
AT_MODE	       nRotateMode; /* Will be set to an IG_ROTATE_...
constant */
BOOL	       bClockwiseFlag;/* Flag indicating direction to rotate
*/
AT_ERRCOUNT nErrcount;    /* Returned number of errors */
 ...
/* If flag is TRUE, rotate 90 clockwise, else 90
counterclockwise:  */
if ( bClockwiseFlag )
    { nRotateMode = IG_ROTATE_270; } /* Go clockwise 90 degrees
*/
else
    { nRotateMode = IG_ROTATE_90;  } /* clockwise 90   */
nErrcount = IG_IP_rotate_multiple_90 ( hIGear, nRotateMode );

Sample: IMG_PROC, TIMING, THREADS, ART, Scan, TWAIN, JNI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_sharpen

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_sharpen (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const INT nSharpFactor
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying a portion of the image to be affected. NULL means entire image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nSharpFactor
Factor indicating the degree for increasing image sharpness. Valid range is 1 to 5.

Description:

This function causes the dark side of a contrast edge to become darker and the light side lighter. Areas without contrast are not altered. nSharpFactor should be in the range 1 to 5. The higher the value, the more sharpening will be applied.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.
NOTE: See also function IG_IP_smooth().

Applicability: All except indexed

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;     /* Handle of image to sharpen  */
nErrCount	 = IG_IP_sharpen ( hIGear, NULL, 2 );/* Sharpen whole
image, factor = 2*/

Sample: TIMING

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_smooth

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_smooth(
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const INT nSmoothFactor
);

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to an AT_RECT struct specifying the portion of image to be affected. NULL means whole image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
nSmoothFactor
Factor indicating degree of decrease to sharpness or increase to smoothness wanted. Valid range is 1 to 4.

Description:

This function makes images look softer and slightly out of focus. This can be used to reduce the graininess of an image. nSmoothFactor can range from 1 to 4. Larger values will cause greater softening.

The pixel neighborhood considered by this function is 3x3, 5x5, 7x7, or 9x9 for nSmoothFactor = 1, 2, 3, or 4 respectively. Therefore a smaller value is faster. nSmoothFactor = 1 or 2 is recommended.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.
NOTE: See the function IG_IP_sharpen().

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;    /* Handle of image to smooth   */
nErrCount	=IG_IP_smooth ( hIGear, NULL, 2 ); /* Smooth whole
image, factor = 2*/

Sample: TIMING

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_swap_red_blue

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_swap_red_blue ( HIGEAR hIGear );

Arguments:

hIGear
HIGEAR handle of image

Description:

This function reverses the color sequence in the pixels of image hIGear's image bitmap. If the sequence is Blue-Green-Red (the standard sequence for a DIB), it is reversed to Red-Green-Blue. If Red-Green-Blue, each pixel is reversed to Blue-Green-Red. This function is typically used on 24-bit RGB images, but it can operate on other image types as well.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;      /* HIGEAR handle of 24-bit image */
IG_IP_swap_red_blue ( hIGear );

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_thumbnail_create

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_thumbnail_create (
    HIGEAR hOrignalImage,
    LPHIGEAR lphNewThumbnail,
    AT_DIMENSION nNewWidth,
    AT_DIMENSION nNewHeight,
    AT_MODE nInterpMethod
);

Arguments:

hOriginalImage
HIGEAR handle of image to create thumbnail image of
lphNewThumbnail
Far pointer to a variable of type HIGEAR to receive the HIGEAR handle of the created thumbnail image
nNewWidth
Specifies width wanted for the new image
nNewHeight
Specifies height wanted for the new image
nInterpMethod
Specifies interpolation method to use for computing values of the pixels in the new image

Description:

This function creates a new image and provides you its new HIGEAR handle. The new image is a resize of the original image. This new image will be nNewWidth by nNewHeight.

The interpolation parameter is used to determine how the new pixels are to be computed from the original one. nInterpMethod = IG_INTERPOLATION_NONE specifies that no interpolation is to be used. In this case, only pixel values that occur in the original image will occur in the new image. See file accucnst.h to learn of any other interpolation methods available.

NOTE: Please see description of IG_IP_resize() and other IG_IP_resize_... functions for interpolation modes description as well as for information on how this function works with different bits per pixels.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear,    /* HIGEAR handle of image to create thumbnail
of */
hIGearThumb;      /* Will be handle of the 64 x 64 thumbnail
image */
ErrCount = IG_IP_thumbnail_create ( hIGear, &hIGearThumb, 64,
64,IG_INTERPOLATION_NONE );

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_thumbnail_create_ex

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_thumbnail_create_ex
    [IN] HIGEAR hOriginalImage,
    [OUT] LPHIGEAR lphNewThumbnail,
    [IN] AT_DIMENSION nNewWidth,
    [IN] AT_DIMENSION nNewHeight,
    [IN] AT_MODE nInterpMethod,
    [IN] DWORD dwFlags,
    [IN] INT nValue
);

Arguments:

hOriginalImage
HIGEAR handle of the image for which to create the thumbnail image
lphNewThumbnail
Far pointer to a variable of type HIGEAR to receive the HIGEAR handle of the created thumbnail image
nNewWidth
Specifies the width specified for the new image
nNewHeight
Specifies the height specified for the new image
nInterpMethod
Specifies interpolation method to use for computing values of the pixels in the new image
dwFlags
The contents of this parameter depends upon the value of nInterpMethod. This is currently not used.
nValue
The contents of this parameter depends upon the value of nInterpMethod. This is used only if nInterpMethod is:
  • IG_INTERPOLATION_GRAYSCALE - nValue can be from 0 to 100. It takes the proportion of pixels from entry 1 to entry 0 (white/black)
  • IG_INTERPOLATION_PRESERVE_WHITE - nValue can be from 0 to 100. It indicates the threshold value of the amount of white color to include.
  • IG_INTERPOLATION_PRESERVE_BLACK - nValue can be from 0 to 100. It indicates the threshold value of the amount of black color to include

Description:

This function creates a new image and provides its new HIGEAR handle. The new image is a resize of the original image. This new image will be nNewWidth by nNewHeight.

The interpolation parameter is used to determine how the new pixels are to be computed from the original one. nInterpMethod = IG_INTERPOLATION_NONE specifies that no interpolation is to be used. In this case, only pixel values that occur in the original image will occur in the new image. See the accucnst.h file for other interpolation methods that are currently available.

NOTE: See the description of IG_IP_resize() and other IG_IP_resize_... functions for interpolation modes as well as for information on how this function works with different bits per pixels.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear,    /* HIGEAR handle of image to create thumbnail
of */
hIGearThumb;      /* Will be handle of the 64 x 64 thumbnail
image */
IG_IP_thumbnail_create_ex( hIGear, &hIGearThumb, 64, 64,
IG_INTERPOLATION_NONE, 0, 0 );
;

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_transform_with_LUT

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_transform_with_LUT (
    HIGEAR hIGear,
    LPAT_RECT lpRect,
    LPAT_PIXEL lpLUTr,
    LPAT_PIXEL lpLUTg,
    LPAT_PIXEL lpLUTb,
    AT_MODE nColorMode
);

Arguments:

hIGear
HIGEAR handle of image to transform
lpRect
Rectangular portion of the image to process; set to NULL for entire image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
lpLUTr
Far pointer to a user-supplied Look Up Table for transforming the red component, or for transforming the pixel value if the image is less than 24-bit.
lpLUTg
Far pointer to a user-supplied Look Up Table for transforming the green component, or for transforming the pixel value if the image is 24-bit.
lpLUTb
Far pointer to a user-supplied Look Up Table for transforming the blue component, or for transforming the pixel value if the image is 24-bit.
nColorMode
A variable of type AT_MODE (IG_COLOR_COMP_) that tells which color channel to use, or to use all three.

Description:

This function transforms the pixel values of the image referenced by hIGear, using a LUT. The pixels from hIGear are used as indices into the LUT. The entry in the LUT at this position is placed into the new image. For 24-bit images, the three channels each have their own LUT. You can point all three LUT parameters to the same LUT. This will process all three channels the same. For 8-bit gray level images, only the lpLUTr LUT parameter is used and the pixel value replaced from the LUT is as follows and the other two are ignored.

new pixel value  = RedLUT[ old pixel value ].

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. (See above.) However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;         /* HIGEAR handle of image    */
AT_PIXEL LUTred[256];  /* Look up pixels, or red if 24-bit, here
*/
AT_PIXEL LUTgreen[256];/* Look up green if 24-bit, here   */
AT_PIXEL LUTblue[256]; /* Look up blue if 24-bit, here    */
IG_IP_transform_with_LUT ( hIGear,
(LPAT_PIXEL)&LUTred,(LPAT_PIXEL)&LUTgreen,
(LPAT_PIXEL)&LUTblue, IG_COLOR_COMP_RGB );

Sample: IMG_PROC, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_transform_with_LUT_ex

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_transform_with_LUT_ex(
    HIGEAR hImage,
    LPAT_RECT lpRect,
    LPAT_VOID* lpLUTs,
    AT_INT nLUTNumber,
    LPAT_INT lpLUTSize,
    AT_MODE nChannels
);

Arguments:

hImage
Image to transform
lpRect
Rectangular portion of the image to process; set to NULL for entire image. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
lpLUTs
Far pointer to a user-supplied Look Up Table.
nLUTNumber
Number of LUTs in lpLUTs.
lpLUTSize
Size of every LUT.
nChannels
A variable of type AT_MODE (IG_COLOR_COMP_) that tells which color channel to use.

Description:

This function transforms the pixel values of the image referenced by hIGear, using a LUT. The pixels from hIGear are used as indices into the LUT. The entry in the LUT at this position is placed into the new image. The function supports images having any number of channels and arbitrary channel depths.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask ().

Applicability:

All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IP_transform_with_LUTs

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_transform_with_LUTs(
    HIGEAR hImage,
    const LPAT_RECT lpRect,
    AT_INT LUT Count,
    const HIGLUT *lpLUTs
);

Parameters:

hImage
Number of channels for the Multichannel LUT
lpRect
New Multichannel LUT object
LUTCount
Number of LUTs in the array
lpLUTs
Array of LUTs

Description:

Transforms the pixel values of the image referenced by hIGear, using an array of look up tables. The pixels from hIGear are used as indices into the LUTs. The entry in the LUT at this position is placed into the corresponding channel of the new image.

Number of LUTs must correspond to the number of channels in the image. Input depths of all LUTs must be equal to corresponding channel depths of the image. Channel depths of result image will be equal to output depths of the corresponding LUTs. All items of the LUTs array can point to the same LUT object. This will process all three channels the same.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. (See above.) However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

NOTE: Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

Return value:

Returns the number of ImageGear errors that occurred during this function call.

Applicability:

All


IG_IP_unsharp_mask

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IP_unsharp_mask (
    HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const double dblRadius,
    const UINT nAmount,
    const UINT nThreshold,
    const AT_MODE nColorChannel );

Arguments:

hIGear
HIGEAR handle of image
lpRect
Far pointer to AT_RECT struct specifying a portion of the image to be affected. NULL means entire image. Before ImageGear performs this operation, it will check to see if internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non-rectangular ROI defined by the mask.
dblRadius
Defines the neighborhood to be considered for each pixel.
nAmount
Amount of sharpening, in percents.
nThreshold
Minimal difference between a pixel and its neighbors at which the pixel will be modified.
nColorChannel
Color channel to which the transform shall be applied.

Description:

Unsharp masking filter is used for image sharpening and edge enhancement. The algorithm works by substracting a smoothed version of the image ("unsharp") from the original image.

Parameter dblRadius can range from 0.1 to 500. Typical values for high-resolution images range from 1.0 to 2.0. Use larger values of dblRadius for thicker edges. The smaller dblRadius value is, the faster is this processing .

Parameter nAmount can range from 1 to 500. Typical values for photographic images range from 100 to 200. Use bigger values for greater edge contrast.

Parameter nThreshold can range from 1 to 500. Typical values for photographic images are between 0 and 20. Use nThreshold to apply sharpening only to those areas where contrast changes significantly. Flat areas will remain unchanged. A proper selection of nThreshold allows to ehnance edges on the image while leaving insufficient details, such as noise or grain of the photographic film, unchanged.

Parameter nColorChannel specifies the channel to which the transform shall be applied. The default value is IG_COLOR_COMP_ALL: apply transform to all color channels of the image. To run UnsharpMask process on the Intensity channel of the image, convert the image to YUV colorspace, run UnsharpMask filter with nColorChannel = IG_COLOR_COMP_YUV_Y, and convert back to original colorspace.

This function, like other ImageGear Image Processing and Clipboard API calls, takes AT_RECT structure as an argument, so that you can process a rectangular subregion of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask ().

Applicability: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;
/* Sharpen whole image, radius = 2.0, amount = 150, threshold =
10 */
nErrCount =IG_IP_unsharp_mask ( hIGear, NULL, 2.0, 150, 10,
IG_COLOR_CHANNEL_ALL );

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_layer_array_count_get

Group: Layer Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_array_count_get(
    HIGLAYERARRAY hLayers,
    AT_INT* lpnCount
);

Description:

This function obtains the number of layers in the layer array.

Arguments:

hLayers
Handle to the layer array object.
lpnCount
The number of layers in the layer array.

Return Value:

Error count.


IG_layer_array_create

Group: Layer Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_array_create(
    LPHIGLAYERARRAY lphLayers
);

Description:

This function creates new blank composition of layers. You can attach this composition to an image using IG_image_layers_set to convert the regular raster image into the layered one.

Arguments:

lphLayers
Handle to the created layer array object.

Return Value:

Error count.


IG_layer_array_delete

Group: Layer Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_array_delete(
    HIGLAYERARRAY hLayers
);

Description:

This function deletes the layer array composition object.

Arguments:

hLayers
Handle to the layer array object to delete.

Return Value:

Error count.


IG_layer_array_layer_add

Group: Layer Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_array_layer_add(
    HIGLAYERARRAY hLayers,
    HIGLAYER hLayers
);

Description:

This function adds the layer to the layer array. The layer object is not copied. Instead, a reference is inserted to the end of the list.

Arguments:

hLayers
Handle to the layer array object.
hLayer
Handle to the layer to add. The layer is added to the end of the array.

Return Value:

Error count.


IG_layer_array_layer_get

Group: Layer Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_array_layer_get(
    HIGLAYERARRAY hLayers,
    AT_INT nIndex,
    LPHIGLAYER lphLayer
);

Description:

This function obtains a handle to the layer at the specified index from the layer array. This function doesn't copy the layer, it just returns a reference to it.

Arguments:

hLayers
Handle to the layer array object.
nIndex
Index of the layer to obtain.
lphLayer
Handle to the obtained layer.

Return Value:

Error count.


IG_layer_array_layer_insert

Group: Layer Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_array_layer_insert(
    HIGLAYERARRAY hLayers,
    AT_INT nIndex,
    HIGLAYER hLayer
);

Description:

This function inserts the layer at the specified index position of the layer array. The layer object is not copied. Instead, a reference is inserted at the specified position.

Arguments:

hLayers
Handle to the layer array object.
nIndex
Index to insert at.
hLayer
Handle to the inserted layer.

Return Value:

Error count.


IG_layer_array_layer_remove

Group: Layer Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_array_layer_remove(
    HIGLAYERARRAY hLayers,
    AT_INT nIndex
);

Description:

This function removes the layer at the specified position from the the layer array. The layer object at the specified position is destroyed by this function.

Arguments:

hLayers
Handle to the layer array object.
nIndex
Index of the layer to remove.

Return Value:

Error count.


IG_layer_delete

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_delete(
    HIG_LAYER_HANDLE hLayer
);

Description:

This function deletes layer object.

Arguments:

hLayer
Handle to the layer object to delete.

Return Value:

Error count.


IG_layer_duplicate

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_duplicate(
    HIGLAYER hLayer,
    LPHIGLAYER lphDuplicatedLayer
);

Description:

This function duplicates the layer object.

Arguments:

hLayer
Handle to the layer object to duplicate.
lphDuplicatedLayer
Handle to the duplicated layer.

Return Value:

Error count.


IG_layer_name_get

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_name_get(
    HIGLAYER hLayer,
    LPSTR lpBuffer,
    AT_UINT* lpnBytesCopied
);

Description:

This function obtains name of the layer.

Arguments:

hLayer
Handle to the layer object.
lpBuffer
Poiner to the character buffer to return the name to.
lpnBytesCopied
Length of the name in bytes.

Return Value:

Error count.


IG_layer_name_set

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_name_set(
    HIGLAYER hLayer,
    LPSTR lpBuffer
);

Description:

This function sets new name for the layer.

Arguments:

hLayer
Handle to the layer object.
lpBuffer
Poiner to the character buffer specifying the name.

Return Value:

Error count.


IG_layer_type_get

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_type_get(
    HIGLAYER hLayer,
    enumIGLayersType* lpnType
);

Description:

This function obtains type of the layer.

Arguments:

hLayer
Handle to the layer object.
lpnType
Layer type.

Return Value:

Error count.


IG_layer_visible_get

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_visible_get(
    HIGLAYER hLayer,
    AT_BOOL* lpbVisible
);

Description:

This function obtains visibility state of the layer.

Arguments:

hLayer
Handle to the layer object.
lpbVisible
Layer visibility state.

Return Value:

Error count.


IG_layer_visible_set

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_layer_visible_set(
    HIGLAYER hLayer,
    AT_BOOL bVisible
);

Description:

This function sets new visibility state of the layer.

Arguments:

hLayer
Handle to the layer object.
bVisible
Layer visibility state.

Return Value:

Error count.


IG_lic_solution_name_set

Group: Utility

Declaration:

AT_ERRCODE ACCUAPI IG_lic_solution_name_set (LPCHAR
lpSolutionName);

Arguments:

lpSolutionName
The license solution name.

Description:

This function provides solution name for your ImageGear license. Please see the section ImageGear Licensing API.

Bits Per Pixel: N/A

Return Value:

Returns the result code of this function call.

Sample: All

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_alpha_mode_get

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_alpha_mode_get (enumIGAlphaMode
*lpAlphaMode );

Arguments:

lpAlphaMode
Far pointer to an enumIGAlphaMode variable to receive the current Alpha chanel loading mode setting.

Description:

This function retrieves the last setting made by calling function IG_load_alpha_mode_set ().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

enumIGAlphaMode AlphaMode;
IG_load_alpha_mode_get ( &AlphaMode );

Sample: Filter

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_alpha_mode_set

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_alpha_mode_set (enumIGAlphaMode
AlphaMode );

Arguments:

AlphaMode
IG_ALPHA_MODE_KEEP (default) to load Alpha channel if it is present; IG_ALPHA_MODE_IGNORE to ignore Alpha channel.

Description:

Instructs ImageGear to load or ignore alpha channel when loading an image that contains one.

NOTE: See also IG_load_alpha_mode_get() function.

Bits Per Pixel: all

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Ignore Alpha channel when loading: */
IG_load_alpha_mode_set (IG_ALPHA_MODE_IGNORE );

Sample: Filter

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_auto_detect_get

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_auto_detect_get (
    AT_MODE nFormatType,
    LPBOOL lpOnOff
);

Arguments:

nFormatType
An AT_MODE constant such as IG_FORMAT_BMP telling which filter to obtain the detect-state of
lpOnOff
Far pointer to a variable of type BOOL in which will be returned the current state of the filter: enabled (TRUE), or disabled (FALSE)

Description:

Obtains the current state of the format filter indicated by nFormatType.

NOTE: See also function IG_load_auto_detect_set().

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

BOOL	 bEnabled; /* Will be TRUE if this file format can be
accessed */
nErrCount = IG_load_auto_detect_get ( IG_FORMAT_TIF , &bEnabled
);

Sample: Bar

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_auto_detect_set

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_auto_detect_set(
    AT_MODE nFormatType,
    BOOL bOnOff
);

Arguments:

nFormatType
An AT_MODE constant such as IG_FORMAT_BMP telling which filter to set on (enabled) or off (disabled)
bOnOff
Set the filter enabled (TRUE), or disabled (FALSE). The default value is TRUE.

Description:

Enable or disable a format filter. If disabled, that file format type cannot be accessed by the IG_load_...() functions.

NOTE: See also function IG_load_auto_detect_get().

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

NOTE: The ASCII filter is turned off by default. To turn it on set:
IG_load_auto_detect_set(IG_FORMAT_TXT, TRUE);

Example:

BOOL	 bEnabled; /* If FALSE this file format will be disabled */
nErrCount = IG_load_auto_detect_set ( IG_FORMAT_TIF , FALSE );

Sample: ASCII, Bar

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_CCITT_FD

Group: Image Loading
NOTE: Please, use new upgraded function IG_load_raw_FD(). See note below.

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_CCITT_FD (
    AT_INT fd,
    AT_DIMENSION nWidth,
    AT_DIMENSION nHeight,
    AT_MODE nType,
    AT_MODE nFillOrder,
    LPHIGEAR lphIGear
);

Arguments:

fd
File Descriptor handle of the open file containing raw Fax data to be loaded
nWidth
Number of pixels in each row of data to be read
nHeight
Number of rows of data
nType
Specifies the type of compression: IG_COMPRESSION_CCITT_G3, IG_COMPRESSION_CCITT_G4 or IG_COMPRESSION_G32D. There is no default for this propery.
nFillOrder
IG_FILL_MSB or IG_FILL_LSB, specifying whether the most-significant-bit-first or least-significant-bit-first. There is no default for this propery.
lphIGear
Returned ImageGear handle of resulting HIGEAR image

Description:

This function creates an ImageGear image from raw CCITT Compressed data located in the file whose File Descriptor handle is fd. The pointer must be positioned at the start of the data. (For example, your application should read or seek past any header that is present.) You must specify the type, G3 or G4, by means of argument nType, and you must specify the fill order, most-significant-bit-first or least-significant-bit-first, by argument nFillOrder. The most common fill order is most-significant-bit-first or IG_FILL_MSB.

The width and height of the image are specified by nWidth and nHeight. The handle of the resulting new ImageGear image is returned in the HIGEAR variable pointed to by lphIGear. The resulting image is always 1-bit.

This function is used when you have a non-standard or proprietary G3 or G4 compressed image file and you know the details of the header. There are literally hundreds of different types of image files that fall into this category. In order to be able to successfully read an image of this type you must know enough about the header to find where the height and width are stored. You can usually look at the header with a hex dump utility and see where these values are stored. Once you are able to read past the header plus get the dimensions of the image, you can then use this function. You can experiment with the other settings until the image is read correctly.

NOTE: The functionality of this API call has been upgraded and supported by the new function IG_load_raw_FD(). The reason that this new function has been created to expand the number of raw image types you can load into ImageGear.
In the interest of backward compatibility, we have left the old function in its original form and have retained support for it. If you have already used the old function in your code, it is not mandatory that you modify your code, but it is recommended.
NOTE: G3 compressed images are always 1728 pixels wide. Since G3 files usually have a special code at the end of the image that ImageGear will detect, you can set the height to a value greater than the expected height of the image and it will be corrected once the end of image marker is detected. For G4 files the height and width must be known and in all cases the file pointer must be at the start of the compressed image when this function is called.

Bits Per Pixel: 1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear;         /* Will receive HIGEAR image handle   */
INT	 fd;             /* File Descriptor handle  */
AT_DIMENSION nWid,      /* Pixels per row of data to read */
     nHi;            /* Rows to read  */
AT_ERRCOUNT nErrcount;   /* Returned count of errors */
nErrcount = IG_load_CCITT_FD ( fd, nWid, nHi,
IG_COMPRESSION_CCITT_G3, IG_FILL_MSB, &hIGear );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_CCITT_mem

Group: Image Loading
NOTE: Please, use new upgraded function IG_load_raw_mem(). See note below.

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_CCITT_mem (
    LPVOID lpImage,
    AT_UINT nSize,
    AT_DIMENSION nWidth,
    AT_DIMENSION nHeight,
    AT_MODE nType,
    AT_MODE nFillOrder,
    LPHIGEAR lphIGear
);

Arguments:

lpImage
Far pointer to memory area from which to load
nSize
Size of image in memory.
nWidth
Number of pixels in each row of data to be read
nHeight
Number of rows of data
nType
Specifies the type of compression: IG_COMPRESSION_CCITT_G3, IG_COMPRESSION_CCITT_G4, or IG_COMPRESSION_CCITT_G32D. There is no default for this propery.
nFillOrder
IG_FILL_MSB or IG_FILL_LSB, specifying whether most-significant bit, first or least-significant bit first. There is no default for this propery.
lphIGear
Returned ImageGear handle of resulting HIGEAR image

NOTE: The functionality of this API call has been upgraded and supported by the new function IG_load_raw_mem(). The reason that this new function has been created is that the old function restricted you to loading raw images that are stored with CCITT formatting.
In the interest of backward compatibility, we have left the old function in its original form and have retained support for it. If you have already used the old function in your code, it is not mandatory that you modify your code, but it is recommended.

Description:

This function operates similarly to function IG_load_CCITT_FD (). See the description under that function. Note that lpImage must point to the start of the actual data (not to the start of any header information that may be present).

Bits Per Pixel: 1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear;           /* Will receive HIGEAR image handle  */
LPVOID	 lpPtrToImage;     /* Pointer to image in memory   */
AT_UINT	 nMemImageSize;    /* Size of image in memory */
AT_DIMENSION nWid,        /* Pixels per row of data to read  */
     nHi;               /* Rows to read   */
AT_ERRCOUNT   nErrcount;   /* Returned count of errors  */
nErrcount = IG_load_CCITT_mem ( lpPtrToImage, nMemImageSize,
nWid, nHi, IG_COMPRESSION_CCITT_G3, IG_FILL_MSB, &hIGear );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_color_reduction_get

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_color_reduction_get (LPAT_MODE
lpColorReduceMode );

Arguments:

lpColorReduceMode
Far pointer to an AT_MODE variable to receive the current IG_LOAD_COLOR setting

Description:

This function retrieves the last setting made by calling function IG_load_color_reduction_set (). If no color reduction is in effect, IG_LOAD_COLOR_DEFAULT is returned.

Bits Per Pixel: 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_MODE	 nLoadReduceMode;   /* Will receive the IG_LOAD_COLOR_
constant */
IG_load_color_reduction_get ( &nLoadReduceMode );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_color_reduction_set

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_color_reduction_set ( AT_MODE
nColorReduceMode );

Arguments:

nColorReduceMode
One of IG_LOAD_COLOR_8, IG_LOAD_COLOR_4, or IG_LOAD_COLOR_1, else IG_LOAD_COLOR_DEFAULT if no color reduction is wanted.

Description:

Instructs ImageGear to perform color reduction to reduce the number of Bits Per Pixel whenever loading an image whose bit depth is greater than that specified by nColorReduceMode. The bit depth is reduced to 8, 4, or 1 as specified. Call with nColorReduceMode = IG_LOAD_COLOR_DEFAULT to disable color reduction.

NOTE: See also IG_load_color_reduction_get() function.

Bits Per Pixel: 4, 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Reduce 24-bit images to 8-bit when loading: */
IG_load_color_reduction_set ( IG_LOAD_COLOR_8 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_extra_mode_get

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_extra_mode_get (enumIGExtraMode
*lpExtraMode );

Arguments:

lpExtraMode
Far pointer to an enumIGExtraMode variable to receive the current Extra chanel loading mode setting.

Description:

This function retrieves the last setting made by calling function IG_load_extra_mode_set ().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

enumIGExtraMode ExtraMode;
IG_load_extra_mode_get ( &ExtraMode );

Sample: Filter

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_extra_mode_set

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_extra_mode_set (enumIGExtraMode
ExtraMode );

Arguments:

ExtraMode
IG_ALPHA_MODE_KEEP (default) to load Extra channel if it is present; IG_ALPHA_MODE_IGNORE to ignore Extra channel.

Description:

Instructs ImageGear to load or ignore extra channels when loading an image that contains any.

NOTE: See also IG_load_extra_mode_get() function.

Bits Per Pixel: all

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Ignore Extra channel when loading: */
IG_load_extra_mode_set (IG_ALPHA_MODE_IGNORE );

Sample: Filter

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_FD

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_FD (
    AT_INT fd,
    LONG lOffset,
    UINT nPage,
    UINT nTileNum,
    LPHIGEAR lphIGear
);

Arguments:

fd
File Descriptor Handle of file containing the image to be loaded. This is a handle (always an integer) obtained when using certain Windows functions, such as _lopen(), to open a file.
lOffset
Offset into the file, in bytes, to where the image begins. This is the offset to the beginning of the header, not to the beginning of the bitmap. lOffset is usually 0.
nPageNum
Page number to load if this is a multi- page (multi- image) file. Note that page numbers begin at 1, not 0. Set nPageNum to 1 if this is not a multi-page file.
nTileNum
If loading an image that is tiled, you can set the number of a specific tile to load. Set to 1 for a non-tiled image
lphIGear
Page Far pointer to HIGEAR object to which this function will return the HIGEAR handle of the image loaded

Description:

This function loads an image from a file into memory and creates a DIB for the image. Unlike IG_load_file (), this function is used when the file is already open and you have its File Descriptor handle (fd). The HIGEAR handle, which ImageGear assigns for the loaded image, is returned to you via argument lphIGear. The file indicated by fd may be in any format recognized by ImageGear. IG_load_FD() will determine the format by inspecting the file's header section. See File Format Reference.

NOTE: Simply loading the file does not cause it to be displayed. Refer to IG_dspl_image_draw() and related routines, for how to display an image once it is in memory. See also IG_load_file_display().

lOffset represents the number of bytes, positive or negative, from the position in the file currently pointed to by fd. The fd may have been moved around a few times so that it is no longer pointing to the beginning of the file. Be sure to keep this in mind as you set the value of lOffset.

The nPageNum argument is set to 1 or greater if you are loading from a multi-page file, to indicate which page (image) you want to load. Set nPageNum to 1 for a non-multi-page file.

NOTE: If you set nPageNum to < 1, ImageGear will default the value to 1; if you set nPageNum to greater than the number of pages in the document, ImageGear will default the value to the last page number. This same default procedure applies to the nTileNum parameter as well.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: If you wish to make a subsequent call to IG_info_get_FD_ex(), you must first move the file pointer (of loaded image) to the beginning of the file, or you will receive an error. This happens because after an image is loaded, the file pointer is positioned at the end of the image in the file. To avoid the error: ² Call IG_load_FD(). ² Call the appropriate C or Windows function, that will set the pointer back to the beginning of the image's header information. ² Call IG_info_get_FD_ex().

Example:

HIGEAR	 hIGear;         /* handle ret'd by IG_load_FD   */
INT	 fd;             /* DOS File Descriptor   */
LONG	 lOffset;         /* offset to image in file   */
UINT	 nPageNum;        /* will be 0 for this call  */
AT_ERRCOUNT nErrcount;    /* to test for errors  */
fd = _lopen ( "picture.bmp", OF_READ );   /* open file  */
nPagenum  = 1;                         /* not a multi-page file
*/
lOffset    = 0;          /* access file from start  */
/* Load image, and obtain its HIGEAR handle:    */
nErrcount = IG_load_FD ( fd, lOffset, nPageNum, 1, &hIGear );

Sample: ASCII, DISPLAY, GUIWIN, THUMB, Vector, FILTER, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_FD_CB

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_FD_CB (
    AT_INT fd
    LONG lOffset,
    UINT nPageNum,
    UINT nTileNum,
    LPFNIG_RASTER_SET lpfnRasterSet,
    LPFNIG_DIB_CREATE lpfnDIBCreate,
    LPVOID lpPrivateData
);

Arguments:

fd
File Descriptor handle
lOffset
Offset within file at which the image file begins (normally 0)
nPageNum
Page number to load. Set to 1 or greater for a multi-page file; 1 for a non-multi page file.
nTileNum
If loading an image that is tiled, you can set the number of a specific tile to load. Set to 1 for a non-tiled image.
lpfnRasterSet
Far pointer to callback func to be called after each raster line is read
lpfnDIBCreate
Far pointer to callback func to be called after the file header has been read
lpPrivateData
Far pointer to a private data area. This pointer will be passed to the callback functions.

Description:

This function loads from an already open file whose File Descriptor handle is fd. However, it is the responsibility of your two callback functions, lpfnDIBCreate and lpfnRasterSet, to create the DIB or other structure you want. Your lpfnDIBCreate callback function is called after the file's header has been read. Then your lpfnRasterSet callback function is called for each raster line read. See the descriptions under function types LPFNIG_DIB_CREATE and LPFNIG_RASTER_SET for how these callback functions are called.

The nPageNum argument is set to 1 or greater if you are loading from a multi-page file, to indicate which page (image) you want to load. Set nPageNum to 1 for a non-multi-page file. (Remember that page numbers begin at 1, not 0.)

If you want a HIGEAR handle for the DIB your callback functions have created, you can obtain one (after the load is complete) by calling function IG_image_DIB_import ().

NOTE: Set full CMYK support to get DIB and rasters in CMYK color format.

Bits Per Pixel: 1, 4, 8, 9-6g, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_FD_CB_ex

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_FD_CB_ex(
    AT_INT fd,
    LONG lOffset,
    UINT nPage,
    UINT nTileNum,
    LPFNIG_RASTER_SET lpfnRasterSet,
    LPFNIG_DIB_CREATE_EX lpfnDIBCreateEx,
    LPVOID lpPrivateData
);

Arguments:

fd
File descriptor
lOffset
Offset within file at which the image file begins (normally 0)
nPage
Page number to load. Set to 1 or greater for a multi-page file; 1 for a non-multi-page file.
nTileNum
If loading an image that is tiled, you can set the number of a specific tile to load. Set to 1 for a non-tiled image.
lpfnRasterSet
Pointer to callback function to be called after each raster line is read
lpfnDIBCreateEx
Pointer to callback function to be called after the file header has been read
lpPrivateData
Pointer to a private data area. This pointer will be passed to the callback functions.

Description:

This function loads from an already open file whose File Descriptor handle is fd. However, it is the responsibility of your two callback functions, lpfnDIBCreate and lpfnRasterSet, to create the DIB or other structure you want. Your lpfnDIBCreate callback function is called after the file's header has been read. Then your lpfnRasterSet callback function is called for each raster line read. See the descriptions under function types LPFNIG_DIB_CREATE_EX and LPFNIG_RASTER_SET for how these callback functions are called.

The nPageNum argument is set to 1 or greater if you are loading from a multi-page file, to indicate which page (image) you want to load. Set nPageNum to 1 for a non-multi-page file. (Remember that page numbers begin at 1, not 0.)

If you want a HIGEAR handle for the DIB your callback functions have created, you can obtain one (after the load is complete) by calling function IG_image_DIB_import ().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HFILE fd;               /* File descriptor */
DWORD dwPrivate[10];    /* Some private data */
fd = _lopen("test.jpg", OF_READ);
if (fd != HFILE_ERROR)
{
    nErrcount = IG_load_FD_CB_ex(
        fd,               /* File descriptor             */
        0L,               /* Offset to image             */
        1,                /* Page number to load         */
        1,                /* Reserved. Always set to 1   */
        MyRasterSet,      /* Called for each raster line */
        MyDIBCreateEx,    /* Called after header is read */
        dwPrivate);       /* Callback data               */
    _lclose(fd);
}
AT_ERRCOUNT ACCUAPI MyDIBCreateEx(
    LPVOID             lpPrivate, /* Private data passed in  */
    const HIGDIBINFO   hDIB       /* DIB info object for DIB */
    )
{
    /* Get info about image and allocate storage here */
    return 0;
}
AT_ERRCOUNT ACCUAPI MyRasterSet(
    LPVOID           lpPrivate,   /* Private data passed in  */
    const LPAT_PIXEL lpRaster,    /* Raster line to set      */
    AT_PIXPOS        row,         /* Y position in the image */
    DWORD            rasterSize   /* Size of the raster line */
    )
{
    /* Do something with incoming raster data here */
    return 0;
}

Sample: LOADCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_file

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_file (
    const LPSTR szFilename,
    LPHIGEAR lphIGear
);

Arguments:

szFilename
Far pointer to filename (you may include path with filename) of image file to load into memory
lphIGear
Far pointer to HIGEAR object in which to return the ImageGear handle of the image

Description:

This function loads an image file into memory and creates a DIB for the image. The handle which ImageGear assigns for this image is returned to you in argument lphIGear. The file named by filename may be in any format recognized by ImageGear. IG_load_file() will determine the format by inspecting the file's header section. See File Format Reference Chapter.

NOTE: Note that simply loading the file does not cause it to be displayed. Refer to IG_dspl_image_draw() and related routines, for how to display an image once it is in memory. See also IG_load_file_display().
NOTE: Some file formats, such as TXT, JPEG, and others, may be loaded with additional control, using IG_fltr_ctrl_get()and IG_fltr_ctrl_set(). See the description of these functions also in Using Format Filters API for Filter Control section.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

NOTE: This function does not support loading multiple images from a multi-page file. If used on a multi-page file, it will only load the first image (page). To load multiple images, use IG_load_FD() or IG_load_mem().
NOTE: This function can also be used to load Internet files. See the example code below. The function IG_load_internet() is a more versatile function for loading Internet files.

Example:

HIGEAR 	hIGear            /* Will hold handle returned by
IG_load_file*/
AT_ERRCOUNT	 	nErrcount;    /* Count of errs on stack upon ret
from func*/
/* Load image file "picture.bmp" from current directory,
creating DIB */
/* and obtaining the image's ImageGear handle: */
nErrcount = IG_load_file ( "picture.bmp" , &hIGear );
/* this lines demonstrates loading an Internet file  */
nErrCount = IG_load_file( "http://www.accusoft.com/images/
image1.bmp", &hIGear )

Sample: CLPBRD, COLOR, DISPLAY, GUIWIN, IMG_PROC, JPEG,

MAGNIFY, MDI, MFC, PALEDT, PIX_ACC, THUMB, THREADS, ART,

Vector, FILTER, FlashPix, IC, MULTIMED, Scan, TWAIN, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_file_display

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_file_display (
    const LPSTR lpszFileName,
    DWORD dwGrpID,
    HWND hWnd,
    HDC hDC,
    LPFNIG_LOAD_DISP lpfnLoadDisp,
    LPVOID lpPrivate,
    LPHIGEAR lphIGear
);

Arguments:

lpszFileName
Far pointer to filename (including path if desired) of file to load and display
dwGrpID
Display group identifier that should be used for display operations.
hWnd
Handle of window where to draw image.
hDC
Windows Device Context of device or window to display image in
lpfnLoadDisp
Far pointer to a callback function (or name of callback function) to call when image has been loaded, but before it is displayed
lpPrivate
Far pointer to a private data area. This pointer will be passed to the callback function when it is called
lphIGear
Far pointer to a variable of type HIGEAR to hold the returned ImageGear HIGEAR handle of the newly loaded image

Description:

This function is called to load and then simultaneously display an image. Since you may want to set display attributes prior to displaying, ImageGear first loads the image's header, creating its HIGEAR handle, then calls your callback function (with the image's HIGEAR handle and your lpPrivate pointer) so you can set display attributes, device rectangle, image rectangle, or perform other operations. When your callback function returns, ImageGear then displays the image, one raster line at a time, as the image is loaded.

See the description for callback type LPFNIG_LOAD_DISP, and see also the section Displaying Images for a discussion of display attributes and how to set them.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See the example code in the section Working with ImageGear Callback Functions.

Sample: DISPLAY, Bar

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_internet

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_internet(
    const LPCHAR HostName,
    const LPCHAR URLPath,
    const LPCHAR UserName,
    const LPCHAR Password,
    const LONG nServerPort,
    DWORD dwService,
    LPHIGEAR lphIGear
);

Arguments:

HostName
Set to the name of Internet host, for example "www.accusoft.com."
URLPath
Set to the URL path to the desired file, such as "/images/image1.bmp". In general, this is a path to necessary file on the given host.
UserName
Set to the proper user name to logon.
Password
Give the proper password to logon.
nServerPort
Set to the number of the Internet port. Use one of the settings from parameter 3 of the Win32 function InternetConnect.
dwService
Set to one of the following values: INTERNET_SERVICE_FTP for FTP service, INTERNET_SERVICE_GOPHER for Gopher service, or INTERNET_SERVICE_HTTP for HTTP service.
lphIGear
ImageGear returns you a HIGEAR handle to the newly loaded image.

Description:

This function loads an image from the Internet into memory and returns to you a HIGEAR handle to it. It does essentially the same thing as IG_load_file () except that it also lets you pass user/password, Server Port, and Transfer Services information.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

const  LPCHAR HostName, URLPath, UserName, Password;
const  LONG nServerPort;
DWORD  dwService;
LPHIGEAR  lphIGear;
AT_ERRCOUNT  nErrcount;
HIGEAR hIGear;
LONG lServerPort;
nErrcount = IG_load_internet(("AccuSoft.com", "/images/
image1.bmp", "Jon", "WebMaster", lServerPort,
INTERNET_SERVICE_HTTP, &hIGear);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_internet_ex

Group: Image Loading

Declaration:

AT_ERRCOUNT   ACCUAPI IG_load_internet_ex (
    [IN] const LPCHAR HostName,
    [IN] const LPCHAR URLPath,
    [IN] const LPCHAR UserName,
    [IN] const LPCHAR Password,
    [IN] const LONG nServerPort,
    [IN] DWORD dwService,
    [IN] DWORD dwAccessType,
    [IN] const LPCHAR lpszProxyName,
    [IN] const LPCHAR lpszProxyBypass,
    [IN] DWORD dwFlags,
    [IN] LPHIGEAR lphIGear
);

Arguments:

HostName
Set to the name of Internet host, for example "www.accusoft.com."
URLPath
Set to the URL path to the desired file, such as "/images/image1.bmp." In general, this is a path to necessary file on the given host.
UserName
Set to the proper user name to logon.
Password
Give the proper password to logon.
nServerPort
Set to the number of the Internet port. Use one of the settings from parameter 3 of the Win32 function InternetConnect.
dwService
Set to one of the following values: INTERNET_SERVICE_FTP for FTP service, INTERNET_SERVICE_GOPHER for Gopher service, or INTERNET_SERVICE_HTTP for HTTP service.
dwAccessType
The type of access that will be passed to InternetOpen function. as second parameter. For details see description of function InternetOpen from Miscrosoft Win32 Internet Function Reference.
lpszProxyName
Proxy name for the third parameter of InternetOpen function. See the description of the InternetOpen function from Miscrosoft's Win32 Internet Function Reference.
lpszProxyBypass
Bypass name for fourth parameter of InternetOpen function. See the description of the InternetOpen function from Miscrosoft's Win32 Internet Function Reference
dwFlags
Flags for fifth parameter of InternetOpen function. See the description of the InternetOpen function from Miscrosoft's Win32 Internet Function Reference.
lphIGear
ImageGear returns you a HIGEAR handle to the newly loaded image.

Description:

This function loads an image from the Internet into memory and returns to you a HIGEAR handle to it. It does essentially the same thing as IG_load_file () except that it also lets you pass user/password, Server Port, Transfer Services information and additional proxy information.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_mem

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_mem (
    LPVOID lpImage,
    AT_UINT nSize,
    UINT nPageNum,
    UINT nTileNum,
    LPHIGEAR lphIGear
);

Arguments:

lpImage
Far pointer to memory location of an image file that is currently in memory
nSize
Size of image in memory.
nPageNum
If a multi-page file, this is page number to load. Otherwise, it is set to 1.
nTileNum
If loading an image that is tiled, you can set the number of a specific tile to load. Set to 1 for a non-tiled image.
lphIGear
Far pointer to HIGEAR object in which to return ImageGear handle of the newly loaded image

Description:

This function is very similar in operation to IG_load_file (), except that the file to load from is in memory instead of on a mass storage device. That is, the entire image file (even if a multi-page file) including header, is in memory. The format must be one of the file formats recognized by ImageGear. See File Format Reference.

Argument lpImage is a FAR pointer to the start of the image file in memory. dwSize is the size of the entire file (even if a multi-page file). For a multi-page file, nPageNum is the page number to load. Note that page numbers in multi-page files begin at 1, not 0. Set nPageNum = 1 if the file is a non-multi-page file.

This function creates a DIB for the image and loads the image into it. The handle which ImageGear assigns for this image is returned to you via argument lphIGear.

NOTE: Note that simply loading the file does not cause it to be displayed. Refer to function IG_dspl_image_draw() for how to display an image once it is in memory.
NOTE: If you set nPageNum to < 1, ImageGear will default the value to 1; if you set nPageNum to greater than the number of pages in the document, ImageGear will default the value to the last page number. This same default procedure applies to the nTileNum parameter as well.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;      /* handle ret'd by ImageGear  */
char far * lpWhereFile;   /* ptr to image file in mem   */
AT_UINT nWholeSize;   /* Size of image in memory */
UINT nPageNum;   /* will be 0 for this call    */
AT_ERRCOUNT nErrcount;  /* to test for errors         */
nPageNum     = 1;       /* not a multi-page file      */
lpWhereFile  = ...;      /* where mem image of file begins */
dwWholeSize  = ...;     /* size of whole mem image    */
nErrcount = IG_load_mem ( lpWhereFile, nWholeSize, nPageNum, 1,
&hIGear );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_mem_CB

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_mem_CB (
    LPVOID lpImage,
    AT_UINT nSize,
    UINT nPageNum,
    UINT nTileNum,
    LPFNIG_RASTER_SET lpfnRasterSet,
    LPFNIG_DIB_CREATE lpfnDIBCreate,
    LPVOID lpPrivate
);

Arguments:

lpImage
Far pointer to file image in memory
nSize
Size of image in memory.
nPageNum
If a multi-page file, this is page number to load. Otherwise, it is set to 1.
nTileNum
If loading an image that is tiled, you can set the number of a specific tile to load. Set to 1 for a non-tiled image.
lpfnRasterSet
Far pointer to callback func to be called after each raster line is read
lpfnDIBCreate
Far pointer to callback func to be called after the file header has been read
lpPrivate
Far pointer to a private data area. This pointer will be passed to the callback functions

Description:

The operation of this function is similar to that of IG_load_FD_CB (), except that the file image is in memory beginning at location *lpImage, rather than in a file. See the description under function IG_load_FD_CB(). See also function IG_load_mem ().

NOTE: If you set nPageNum to < 1, ImageGear will default the value to 1; if you set nPageNum to greater than the number of pages in the document, ImageGear will default the value to the last page number. This same default procedure applies to the nTileNum parameter as well.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

LPFNIG_DIB_CREATE  	MyDIB_Create;     /* Create-DIB callback */
LPFNIG_RASTER_SET  	MyRasterSet;    /* Raster-Set callback    */
LPVOID	 cPointerToImage;    /* Ptr to start of file image in
memory */
AT_UINT	 nMemImageSize; /* Size of image in memory */
static char cPrivate[200];  /* Can hold data to pass to
callbacks  */
AT_ERRCOUNT nErrcount;  /* Returned error count  */
nErrcount = IG_load_mem_CB ( cPointerToImage, nMemImageSize, 1,
1,MyRasterSet, MyDIB_Create, (LPVOID) cPrivate );
if ( nErrcount )
{ ... }   /* Either callback might have forced an error on stack
*/
/* See also the examples under LPFNIG_DIB_CREATE and
LPFNIG_RASTER_SET. */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_mem_CB_ex

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_mem_CB_ex(
    LPVOID lpImage,
    AT_UINT nImageSize,
    UINT nPage,
    UINT nReserved,
    LPFNIG_RASTER_SET lpfnRasterSet,
    LPFNIG_DIB_CREATE_EX lpfnDIBCreateEx,
    LPVOID lpPrivateData
);

Arguments:

lpImage
Pointer to file image in memory
nImageSize
Size of image in memory
nPage
If a multi-page file, this is page number to load. Otherwise, it should be set to 1.
nReserved
Reserved, should be set to 0 for now.
lpfnRasterSet
Pointer to callback function to be called after each raster line is read
lpfnDIBCreateEx
Pointer to callback function to be called after the file header has been read
lpPrivateData
Pointer to a private data area. This pointer will be passed to the callback functions.

Description:

The operation of this function is similar to that of IG_load_FD_CB_ex (), except that the file image is in memory beginning at location lpImage, rather than in a file. See the description under function IG_load_FD_CB_ex (). See also function IG_load_mem().

NOTE: If you set nPageNum to < 1, ImageGear will default the value to 1; if you set nPageNum to greater than the number of pages in the document, ImageGear will default the value to the last page number.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

See example for IG_load_FD_CB_ex ().

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_raw_FD

Group: Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_raw_FD(
    AT_INT fd,
    AT_DIMENSION nWidth,
    AT_DIMENSION nHeight,
    UINT nBitsPerPixel,
    AT_MODE nFillOrder,
    AT_ MODE nCompression,
    LPHIGEAR  lphIGear
);

Arguments:

fd
File Descriptor handle to an image that you would like to load
nWidth
The width, in pixels, of the image
nHeight
The height, in pixels, of the image
nBitsPerPixel
The Bits Per Pixel of the raw data to load
nFillOrder
Set to the fill order used in the image: Least Significant Bit first (LSB) or Most Significant Bit first (MSB). Use one of the ImageGear - defined constants:IG_FILL_LSB or IG_FILL_MSB.
  • For G3/G4 compressed data, this parameter specifies the Least/Most significant bit.
  • For 16 bit grayscale uncompressed images, this parameter specifies the Least/Most significant byte.
  • For any other bit depths and compressions, this parameter is ignored.
nCompression
Set to an ImageGear- defined compression constant. The names of such constants begin with the prefix IG_COMPRESSION_ and are defined in accucnst.h.
lphIGear
Returns you a HIGEAR handle to the raw image data just loaded.

Description:

This function creates an ImageGear image from the raw image data of the file whose File Descriptor handle is fd. A raw image file contains no header or identifying information. You must supply this function with all of the information needed to correctly parse the image data, including the compression, byte fill order, width, height, and bit depth. As of this writing, this function can be used to read raw image data from the following types of files: ABIC1, CCITT Group 3 & 4, and raw uncompressed data.

The pointer must be positioned at the start of the data. (For example, your application should read or seek past any header that is present.)

Tell ImageGear the width, height, bit depth, compression, and fill order of the image using nWidth, nHeight, nBitsPerPixel, nFillOrder, and nCompression, respectively. The handle of the resulting new ImageGear image is returned in the HIGEAR variable pointed to by lphIGear.

Additionally, you can specify row alignment of the image using ALIGNMENT image control parameter. See RAW format reference in File Format Reference Chapter for more information.

In all cases the file pointer must be at the start of the compressed image when this function is called.

NOTE: For uncompressed images only, ImageGear's Load Raw functions consider the coordinates (0,0) to refer to the lower-left corner of the bitmap.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear;      /* Will receive HIGEAR image handle */
INT fd;         /* File Descriptor handle    */
AT_DIMENSION nWid,      /* Pixels per row of data to read, */
nHi;                      /* Rows to read       */
AT_ERRCOUNT nErrcount;      /* Returned count of errors */
nErrcount = IG_load_raw_FD ( fd, nWid, nHi, 1, IG_FILL_MSB,
IG_COMPRESSION_CCITT_G3, &hIGear );

Sample: FlashPix

1 This compression type is available as separate component to ImageGear. See the section ImageGear ABIC Component under the section ImageGear Components.


IG_load_raw_file

Group: Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_raw_file(
    const LPSTR lpszFileName,
    LONG lOffset,
    AT_DIMENSION  nWidth,
    AT_DIMENSION nHeight,
    UINT nBitsPerPixel,
    AT_MODE nFillOrder,
    AT_MODE nCompression,
    LPHIGEAR lphIGear
);

Arguments:

lpszFileName
Name of the file
lOffset
Offset in the file where the raw image data starts from
nWidth
The width, in pixels, of the image
nHeight
The height, in pixels, of the image
nBitsPerPixel
The Bits Per Pixel of the raw data to load
nFillOrder
Set to the fill order used in the image: Least Significant Bit first (LSB) or Most Significant Bit first (MSB). Use one of the ImageGear-defined constants: IG_FILL_LSB or IG_FILL_MSB.
  • For G3/G4 compressed data, this parameter specifies the Least/Most significant bit.
  • For 16-bit grayscale uncompressed images, this parameter specifies the Least/Most significant byte.
  • For any other bit depths and compressions, this parameter is ignored.
nCompression
Set to an ImageGear-defined compression constant. The names of such constants begin with the prefix IG_COMPRESSION_ and are defined in accucnst.h.
lphIGear
Returns you a HIGEAR handle to the raw image data just loaded.

Description:

This function loads a raw (no header) image data file from disk. It performs the same operation as the new API functions IG_load_raw_mem () and IG_load_raw_FD (). Please see the descriptions for these API for more details.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_raw_mem

Group: Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_raw_mem(
    LPVOID lpImage,
    AT_UINT nImageSize,
    AT_DIMENSION nWidth,
    AT_DIMENSION nHeight,
    UINT nBitsPerPixel,
    AT_MODE nFillOrder,
    AT_MODE nCompression,
    LPHIGEAR lphIGear
);

Arguments:

lpImage
Far pointer to memory area from which to load
nImageSize
Size of image in memory.
nWidth
The width, in pixels, of the image.
nHeight
The height, in pixels, of the image
nBitsPerPixel
The Bits Per Pixel of the raw data to load
nFillOrder
Set to the fill order used in the image: Least Significant Bit first (LSB) or Most Significant Bit first (MSB). Use one of the ImageGear-defined constants:IG_FILL_LSB or IG_FILL_MSB.
  • For G3/G4 compressed data, this parameter specifies the Least/Most significant bit.
  • For 16-bit grayscale uncompressed images, this parameter specifies the Least/Most significant byte.
  • For any other bit depths and compressions, this parameter is ignored.
nCompression
Set to an ImageGear-defined compression constant. The names of such constants begin with the prefix IG_COMPRESSION_ and are defined in accucnst.h.
lphIGear
Returns you a HIGEAR handle to the raw image data just loaded.

Description:

This function operates similarly to function IG_load_raw_FD (). See the description under that function.

NOTE: Note that lpImage must point to the start of the actual data (not to the start of any header information that may be present).

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR	 	hIGear;     /* Will receive HIGEAR image handle  */
LPVOID lpPtrToImage;  /* Pointer to image in memory  */
AT_UINT nMemImageSize;/* Size of image in memory */
AT_DIMENSION nWid,     /* Pixels per row of data to read  */
        nHi;      /* Rows to read */
AT_ERRCOUNT nErrcount;    /* Returned count of errors  */
nErrcount = IG_load_raw_mem ( lpPtrToImage, nMemImageSize, nWid,
nHi, 16, IG_FILL_LSB, IG_COMPRESSION_NONE, &hIGear );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_rect_get

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_rect_get (
    LPAT_PIXPOS lpX,
    LPAT_PIXPOS lpY,
    LPAT_DIMENSION lpWidth,
    LPAT_DIMENSION lpHeight
);

Arguments:

lpX
Far pointer to variable of type AT_PIXPOS to receive X coordinate of load rectangle
lpX
Far pointer to AT_PIXPOS variable to receive Y coordinate of load rectangle
lpWidth
Far pointer to variable of type AT_DIMENSION to receive width of load rectangle
lpHeight
Far pointer to variable of type AT_DIMENSION to receive height of load rectangle

Description:

This function obtains the current load rectangle, as set in the last call to IG_load_rect_set ().

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

AT_PIXPOS nXLoadCrop,    /* X coordinate of load crop rectangle
*/
         nYLoadCrop;     /* Y coordinate  */
AT_DIMENSION  nWidCrop,     /* Width of load crop rectangle  */
        nHiCrop;     /* Height   */
IG_load_rect_get ( &nXLoadCrop, &nYLoadCrop, &nWidCrop,
&nHiCrop );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_rect_set

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_rect_set (
    AT_PIXPOS nX,
    AT_PIXPOS nY,
    AT_DIMENSION nWidth,
    AT_DIMENSION nHeight
);

Arguments:

nX
X coordinate of load rectangle
nY
Y coordinate of load rectangle
nWidth
Width of load rectangle
nHeight
Height of load rectangle

Description:

This function sets the load rectangle. This will cause an image loaded to be cropped. Portions of the image falling outside the coordinates of this rectangle will be discarded, and will not appear in the image bitmap of the DIB created by the load.

NOTE: To reset ImageGear to its default behavior of loading the whole image, set all parameters to 0.
NOTE: See also IG_load_rect_get() function.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

/* Set to only load the upper left 1000 x 500 of the image: */
IG_load_rect_set ( 0, 0, 1000, 500 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_size_get

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_size_get (
    LPAT_DIMENSION lpWidth,
    LPAT_DIMENSION lpHeight
);

Arguments:

lpWidth
Far pointer to variable of type AT_DIMENSION to receive the load size width
lpHeight
Far pointer to variable of type AT_DIMENSION to receive the load size height

Description:

This function obtains the load size dimensions.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

NOTE: To reset ImageGear so that it will default to normal resolution, set both parameters to 0 using IG_load_size_set().

Example:

AT_DIMENSION nWid, nHi;   /* Will receive current load size
settings */
IG_load_size_get ( &nWid, &nHi );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_size_set

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_size_set (
    AT_DIMENSION nWidth,
    AT_DIMENSION nHeight
);

Arguments:

nWidth
Load size width to set
nHeight
Load size height to set

Description:

This function sets the load size dimensions. These are the dimensions that the DIB image bitmap created by a load, are to have, regardless of the dimensions in the file from which the image is loaded. The effect is similar to loading and then re-sizing the image.

NOTE: To reset ImageGear so that it will default to loading the entire image, set both parameters to 0.
NOTE: See also IG_load_size_get() function.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

/* On loading, map the image into a 512 x 256 image bitmap: */
IG_load_size_set ( 512, 256 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_tag_CB_register

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_tag_CB_register (
    LPFNIG_TAG_SET lpfnTagSet,
    LPVOID lpPrivate
);

Arguments:

lpfnTagSet
Far pointer to callback function to be called with each Tag encountered while loading
lpPrivate
Far pointer to private data (passed to callback function)

Description:

This function registers a callback function of type LPFNIG_TAG_GET, LPFNIG_TAG_SET or LPFNIG_TAG_USER_GET (See in the Core Component Callback Functions Reference section). These callback function types are defined by ImageGear to take a certain set of parameters and to return data to you. Your callback function must supply ImageGear with the type of data required by the callback that you choose.

Once you have written a callback function in one of the types listed above, this function should be called to register it. Once registered, your function will be called once for each Tag encountered while loading a file. A "tag" may also be known as an element in the image's header, or as non-image data. The TIFF format popularized the use of the word "tag".

Different file formats have different sets of tags.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

LPFNIG_TAG_SET    MyTagGet;     /* Declare type of function */
{
static DWORD      dwPrivateFlags;
 ...
IG_load_tag_CB_register ( MyTagSet, (LPVOID) &dwPrivateFlags );

Sample: JPEG, FILTER, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_thumbnail

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_thumbnail (
    const LPSTR lpszFileName,
    LPHIGEAR lphIGear
);

Arguments:

lpszFileName
Name of file
lphIGear
Far pointer to HIGEAR variable to receive handle

Description:

This function loads a thumbnail (if one exists in the file) from file lpszFileName, and returns the HIGEAR handle of the resulting image to the HIGEAR object pointed to by argument lphIGear.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

See the example for function IG_save_thumbnail_set ().

Sample: JPEG

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_thumbnail_FD

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_thumbnail_FD (
    AT_INT fd,
    LONG lOffset,
    LPHIGEAR lphIGear
);

Arguments:

fd
File Descriptor handle
lOffset
Offset in file at which file image begins
lphIGear
Far pointer to HIGEAR variable to receive handle

Description:

This function loads a thumbnail from the open file indicated by fd. The handle of the resulting image is returned to the HIGEAR variable pointed to by argument lphIGear.

NOTE: See also functions IG_load_thumbnail(), and IG_save_thumbnail_set().

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear1;     /* handle ret'd by IG_load_FD  */
HIGEAR hIGear2;     /* handle for thumbnail  */
INT fd;          /* DOS File Descriptor  */
LONG	 lOffset;              /* offset to image in file */
UINT	 nPageNum;             /* will be 0 for this call */
AT_ERRCOUNT nErrcount;     /* to test for errors  */
fd = _lopen ( "picture.bmp", OF_READ );    /* open file  */
nPageNum  = 0;          /* not a multi-page file  */
lOffset    = 0;         /* access file from start */
/* Load image, and obtain its HIGEAR handle:    */
nErrcount = IG_load_FD ( fd, lOffset, nPageNum, 0, &hIGear1 );
if ( nErrcount == 0 )
{ nErrcount = IG_load_thumbnail_FD ( fd, lOffset, &hIGear2 ); }

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_thumbnail_mem

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_thumbnail_mem (
    LPVOID lpImage,
    AT_UINT nImageSize,
    LPHIGEAR lphIGear
);

Arguments:

lpImage
Far pointer to start of file image in memory
nImageSize
Size of image in memory.
lphIGear
Far pointer to HIGEAR variable to receive handle

Description:

This function loads a thumbnail from the file image located in memory at location lpImage. The handle of the resulting image is returned to the HIGEAR variable pointed to by argument lphIGear.

NOTE: See also functions IG_load_thumbnail(), and IG_save_thumbnail_set().

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR	 hIGear1;       /* handle ret'd by IG_load_mem  */
HIGEAR	 hIGear2;       /* ret'd by IG_load_thumbnail_mem  */
char far * lpWhereFile;    /* ptr to image file in mem   */
AT_UINT	 nImageSize;   /* Size of image in memory */
UINT	 nPageNum;      /* will be 0 for this call     */
AT_ERRCOUNT nErrcount;/* to test for errors         */
nPageNum     = 0;     /* not a multi-page file      */
lpWhereFile  = ...;   /* where mem image of file begins */
nImageSize = ...;   /* Size of image in memory */
nErrcount = IG_load_mem ( lpWhereFile, nImageSize, nPageNum, 0,
&hIGear1 );
if ( nErrcount == 0 )
    { nErrcount = IG_load_thumbnail_mem ( lpWhereFile,
nImageSize, &hIGear2 ); }

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_tiles_stitch

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_tiles_stitch(
    const LPSTR lpszFileName,
    UINT nPage,
    LPAT_STITCH  lpStitch,
    LPHIGEAR lphIGear
);

Arguments:

lpszFileName
Set to the filename of the image to load and stitch
nPage
Set to the number of the page to load and stitch. If the file is not multipage, set this to 1.
lpStitch
Set to a structure of type AT_STITCH, which defines the reference tile number, and the number of row and columns of tiles
lphIGear
ImageGear returns you a HIGEAR handle to the newly stitched image in memory.

Description:

This function loads and stitches together a tiled image, returning you a HIGEAR handle to the image in memory.

As of this writing, ImageGear supports the following formats that sometimes use tiled storage: TIFF, IOCA, MO:DCA. To determine whether or not the image has tiles, call IG_tile_count_get ().

The AT_STITCH structure allows you to supply ImageGear with information on which tiles to use as the upper-left corner in the new stitched image, and how many tile rows and columns should be stitched together:

typedef struct tag AT_STITCH
{
    LONG uRefTile;   /* Upper left-hand corner tile #  */
    LONG uTileRows;  /* Number of tiles to stitch across */
    LONG uTileCols;  /* Number of tiles to stitch down   */
}AT_STITCH, FAR *LPAT_STITCH;
NOTE: For a graphical representation of how this works, see the section Working with Tiled Images Simply loading the file does not cause it to be displayed. Refer to IG_dspl_image_draw() and related routines, for how to display an image once it is in memory.

The nPageNum argument is set to 1 or greater if you are loading from a multi-page file, to indicate which page (image) you want to load. Set nPageNum to 1 for a non-multi-page file.

NOTE: If you set nPageNum to < 1, ImageGear will default the value to 1; if you set nPageNum to greater than the number of pages in the document, ImageGear will default the value to the last page number.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: See also IG_load_tiles_stitch_FD(), IG_load_tiles_stitch_mem(), IG_tile_count_get()functions.

For a complete discussion of working with tiled images see the section Working with Tiled Images.

Example:

AT_ERRCOUNT  	nErrcount;
HIGEAR 	hIGear;
AT_STITCH 	lpStitch;
CHAR	  szFile[_MAX_PATH]
nErrCount = IG_load_tiles_stitch(szFile, 1, lpStitch, &hIGear);

Sample: FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_tiles_stitch_FD

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_tiles_stitch_FD(
    AT_INT fd,
    LONG lOffset,
    UINT nPage,
    LPAT_STITCH lpStitch,
    LPHIGEAR lphIGear
);

Arguments:

fd
Set to the File Descriptor handle for the image you would like to load and stitch.
lOffset
Offset into the file, in bytes, to where the image begins. This is the offset to the beginning of the header, not to the beginning of the bitmap. lOffset is usually 0.
nPage
Set to the page number to load if this is a multipage file. Set to 1 if this is not a multipage file.
lpStitch
Set to a structure of type AT_STITCH, which defines the reference tile number, and the number of rows and columns of tiles.
lphIGear
Returns a HIGEAR handle to the newly stitched-together image

Description:

This function loads and stitches together a tiled image, returning you a HIGEAR handle to the image in memory. Unlike IG_load_tiles_stitch (), this function is used when the file is already open and you have its File Descriptor handle.

As of this writing, ImageGear supports the following formats that sometimes use tiled storage: TIFF, IOCA, MO:DCA. To find out whether the image has tiles, call IG_tile_count_get_FD ()function.

The AT_STITCH structure allows you to tell ImageGear which tile to use as the upper-left corner in the new stitched image, and how many tile rows and columns should be stitched together:

typedef struct tag AT_STITCH
{
    LONG uRefTile;     /*Upper left-hand corner tile #  */
    LONG uTileRows;    /* Number of tiles to stitch across  */
    LONG uTileCols; /* Number of tiles to stitch down  	*/
}AT_STITCH, FAR *LPAT_STITCH;
NOTE: For a graphical representation of how this works, see the section Working with Tiled ImagesNote that simply loading and stitching the file does not cause it to be displayed. Refer to IG_dspl_image_draw() and related routines, for how to display an image once it is in memory.
NOTE: lOffset represents the number of bytes, positive or negative, from the position in the file currently pointed to by fd. The current fd position may have been moved around a few times so that it is no longer pointing to the beginning of the image's header information. Be sure to keep this in mind as you set the value of lOffset.

The nPageNum argument is set to 1 or greater if you are loading from a multi-page file, to indicate which page (image) you want to load. Set nPageNum to 1 for a non multi-page file.

NOTE: If you set nPageNum to < 1, ImageGear will default the value to 1; if you set nPageNum to greater than the number of pages in the document, ImageGear will default the value to the last page number.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: See also IG_load_tiles_stitch(), IG_load_tiles_stitch_mem(), IG_tile_count_get_FD()functions.

For a complete discussion of working with tiled images, see the section Working with Tiled Images.

NOTE: If you wish to make a subsequent call to IG_info_get_FD_ex(), you must first move the file pointer (of loaded image) to the beginning of the image's header information, or you will receive an error. This happens because after an image is loaded, the file pointer is positioned at the end of the image in the file. To avoid the error: ² Call IG_load_FD(). ² Call the appropriate C or Windows function, that will set the pointer back to the beginning of the image's header information.
² Call IG_info_get_FD_ex().

Example:

HIGEAR	 hIGear;      /* handle ret'd by IG_load_FD */
INT	 fd;          /* DOS File Descriptor  */
LONG 	lOffset;      /* offset to image in fill  */
UINT	 nPageNum;     /* will be 0 for this call  */
AT_ERRCOUNT nErrcount;   /* to test for errors  */
AT_STITCH  stitchStruct;
LONG lHorizTileCount, lVertTileCount;
fd = _lopen ( "picture.tif", OF_READ );  /* open file  */
nPagenum  = 3;       /* load tiles from page 3  */
lOffset    = 0;         /* access file from start  */
stitchStruct.uRefTile = 5;     /* Use tile 5 as reference  */
stitchStruct.uTileRows = 2;     /* Stitch 2 tiles across  */
stitchStruct.uTileCols = 2;     /* Stitch 2 tiles down  */
/* Load tiles, stitch together and return HIGEAR handle:  */
nErrcount = IG_load_tiles_stitch_FD ( fd, lOffset, nPageNum,
&stitchStruct, &hIGear );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_load_tiles_stitch_mem

Group: Image Loading

Declaration:

AT_ERRCOUNT ACCUAPI IG_load_tiles_stitch_mem(
    LPVOID lpImage,
    AT_UINT nImageSize,
    UINT nPage,
    LPAT_STITCH lpStitch,
    LPHIGEAR lphIGear
);

Arguments:

lpImage
A far pointer to the memory location of an image file that is currently in memory
nImageSize
Size of image in memory.
nPage
Set to the page number to load if this is a multipage file. Set to 1 if this is not a multipage file.
lpStitch
Set to a structure of type AT_STITCH, which defines the reference tile number, and the number of row and columns of tiles
lphIGear
Returns a HIGEAR handle to the newly stitched-together image.

Description:

This function loads and stitches together a tiled image that has already been loaded into memory, returning you a HIGEAR handle to the image. The argument lpImage is a FAR pointer to the start of the image file in memory.

As of this writing, ImageGear supports the following formats that sometimes use tiled storage: TIFF, IOCA, MO:DCA. To find out whether the image has tiles, call IG_tile_count_get_mem ()function.

The AT_STITCH structure allows you to tell ImageGear which tile to use as the upper-left corner in the new stitched image, and how many tile rows and columns should be stitched together:

typedef struct tag AT_STITCH
{
    LONG uRefTile;        /*Upper left-hand corner tile #  */
    LONG uTileRows;     /* Number of tiles to stitch across */
    LONG uTileCols;     /* Number of tiles to stitch down   */
}AT_STITCH, FAR *LPAT_STITCH;

For graphical representation of how this works, see the section Working with Tiled Images.

NOTE: Simply loading and stitching the file does not cause it to be displayed. Refer to IG_dspl_image_draw() and related routines, for how to display an image once it is in memory. See also IG_load_file_display()function.

The nPageNum argument is set to 1 or greater if you are loading from a multi-page file, to indicate which page (image) you want to load. Set nPageNum to 1 for a non multi-page file.

NOTE: If you set nPageNum to < 1, ImageGear will default the value to 1; if you set nPageNum to greater than the number of pages in the document, ImageGear will default the value to the last page number.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: See also IG_load_tiles_stitch(), IG_load_tiles_stitch_FD(), IG_tile_count_get_mem()functions.

For a complete discussion of working with tiled images, see the section Working with Tiled Images.

Example:

AT_ERRCOUNT  nErrcount;
HIGEAR hIGear;
char far * lpWherFile;
AT_UINT	 	nWholeSize;
UINT nPageNum;
AT_STITCH stitchStruct;
nErrcount = IG_load_tiles_stitch_mem(lpWhereFile, nWholeSize,
nPageNum, &stitchStruct, &hIGear);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_LUT_concatenate

Group: Grayscale LUT

Declaration:

AT_ERRCOUNT ACCUAPI IG_LUT_concatenate(
    HIGLUT SrcLUT1,
    HIGLUT SrcLUT2,
    HIGLUT *lpDstLUT
);

Parameters:

SrcLUT1
First LUT to concatenate
SrcLUT2
Second LUT to concatenate
lpDstLUT
Returns concatenated LUT

Description:

Concatenates two LUTs into one LUT. Application of concatenated LUT to an image produces the same result as consequent application of the input LUTs.

Input depth of SrcLUT2 must be equal to output depth of SrcLUT1. If output of the SrcLUT1 is signed, input of SrcLUT2 must be signed; if output of the SrcLUT1 is unsigned, input of SrcLUT2 must be unsigned. Input depth of the result LUT will be equal to input depth of SrcLUT1; Output depth of the result LUT will be equal to output depth of SrcLUT2.

Return value:

Returns the number of ImageGear errors that occurred during this function call.


IG_LUT_copy

Group: Grayscale LUT

Declaration:

AT_ERRCOUNT ACCUAPI IG_LUT_copy(
    HIGLUT SrcLUT,
    HIGLUT *lpDstLUT
);

Arguments:

SrcLUT
Source LUT handle.
lpDstLUT
New LUT handle.

Description:

This function copies the LUT to a new HIGLUT object

Bits Per Pixel: 8...16-bit grayscale

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: Medical

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_LUT_copy_to_byte_array

Group: Grayscale LUT

Declaration:

AT_ERRCOUNT ACCUAPI IG_LUT_copy_to_byte_array(
    HIGLUT SrcLUT,
    AT_INT ArrayLength,
    AT_BYTE *lpArray
);

Arguments:

SrcLUT
LUT to be copied.
ArrayLength
Array length.
lpArray
Byte array.

Description:

This function copies LUT a to byte array. Array length must be equal to 2^InputDepth, where InputDepth is the input depth of the LUT.

Bits Per Pixel: 8...16-bit grayscale

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

None


IG_LUT_copy_to_word_array

Group: Grayscale LUT

Declaration:

AT_ERRCOUNT ACCUAPI IG_LUT_copy_to_word_array(
    HIGLUT SrcLUT,
    AT_INT ArrayLength,
    AT_WORD *lpArray
);

Arguments:

SrcLUT
LUT to be copied.
ArrayLength
Array length.
lpArray
Word array.

Description:

This function copies LUT a to word array.

Array length must be equal to 2^InputDepth, where InputDepth is the input depth of the LUT.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

None


IG_LUT_create

Group: Grayscale LUT

Declaration:

AT_ERRCOUNT ACCUAPI IG_LUT_create(
    AT_INT InputDepth,
    AT_BOOL InputIsSigned,
    AT_INT OutputDepth,
    AT_BOOL OutputIsSigned,
    HIGLUT *lpLUT
);

Arguments:

InputDepth
Input bit count of the LUT.
InputIsSigned
Shows whether input of the LUT is signed.
OutputDepth
Output bit count of the LUT.
OutputIsSigned
Shows whether output of the LUT is signed.
lpLUT
Handle of the created LUT object.

Description:

This function creates a LUT object.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: Medical

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_LUT_destroy

Group: Grayscale LUT

Declaration:

AT_ERRCOUNT ACCUAPI IG_LUT_destroy(
    HIGLUT lut
);

Arguments:

lut
Handle of the LUT to be destroyed.

Description:

This function destroys a LUT object.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: Medical

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_LUT_input_depth_get

Group: Grayscale LUT

Declaration:

AT_INT ACCUAPI IG_LUT_input_depth_get(HIGLUT lut);

Arguments:

lut
LUT handle.

Description:

This function returns input bit count of the LUT.

Input depth defines the length (number of entries) of the lut, as follows:

LUTLength = 2^InputDepth.

Bits Per Pixel: 8...16-bit

Return Value:

Input bit count of the LUT.

Sample:

None


IG_LUT_input_is_signed_get

Group: Grayscale LUT

Declaration:

AT_BOOL ACCUAPI IG_LUT_input_is_signed_get(HIGLUT lut);

Arguments:

lut
LUT handle.

Description:

This function tells whether input of the LUT is signed.

Bits Per Pixel: 8...16-bit

Return Value:

TRUE if the input is signed, FALSE - otherwise.

Sample:

None


IG_LUT_is_valid

Group: Grayscale LUT

Declaration:

AT_BOOL ACCUAPI IG_LUT_is_valid(HIGLUT lut);

Arguments:

lut
LUT handle.

Description:

This function checks whether HIGLUT is valid.

Bits Per Pixel: 8...16-bit

Return Value:

TRUE if HIGLUT is valid, FALSE - otherwise.

Sample:

None


IG_LUT_item_get

Group: Grayscale LUT

Declaration:

AT_INT ACCUAPI IG_LUT_item_get(HIGLUT lut, AT_INT32 index);

Arguments:

lut
Handle of the LUT.
index
Index of the item to be returned.

Description:

This function returns LUT item.

If LUT input is unsigned, valid values for index are in range [0, 2^InputDepth-1].

If LUT input is signed, valid values for index are in range [-2^(InputDepth-1), 2^(InputDepth-1)-1].

Bits Per Pixel: 8...16-bit

Return Value:

LUT item.

Sample:

None


IG_LUT_item_set

Group: Grayscale LUT

Declaration:

AT_VOID ACCUAPI IG_LUT_item_set(
    HIGLUT lut,
    AT_INT32 index,
    AT_INT value
);

Arguments:

lut
LUT handle.
index
Index of the item.
value
Value of the item.

Description:

This function sets the LUT item.

If LUT input is unsigned, valid values for index are in range [0, 2^InputDepth-1].

If LUT input is signed, valid values for index are in range [-2^(InputDepth-1), 2^(InputDepth-1)-1].

Bits Per Pixel: 8...16-bit

Return Value:

None.

Sample:

None


IG_LUT_length_get

Group: Grayscale LUT

Declaration:

AT_INT ACCUAPI IG_LUT_length_get(HIGLUT hlut);

Arguments:

hlut
LUT handle.

Description:

This function returns the number of entries in the LUT.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of entries in the LUT.

Sample: Medical

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_LUT_output_depth_get

Group: Grayscale LUT

Declaration:

AT_INT ACCUAPI IG_LUT_output_depth_get(HIGLUT lut);

Arguments:

lut
LUT handle.

Description:

This function returns output bit count of the LUT.

Output depth defines the size of each entry of the LUT.

Bits Per Pixel: 8...16-bit

Return Value:

Returns output bit count of the LUT.

Sample:

None


IG_LUT_output_is_signed_get

Group: Grayscale LUT

Declaration:

AT_BOOL ACCUAPI IG_LUT_output_is_signed_get(HIGLUT lut);

Arguments:

lut
LUT handle.

Description:

This function tells whether output of the LUT is signed.

Bits Per Pixel: 8...16-bit

Return Value:

TRUE - output of the LUT is signed, FALSE - otherwise.

Sample:

None


IG_LUT_size_get

Group: Grayscale LUT

Declaration:

AT_INT ACCUAPI IG_LUT_size_get(HIGLUT hlut);

Arguments:

hlut
Handle of the LUT.

Description:

This function returns the size, in bytes, of the LUT data.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the size, in bytes, of the LUT data.

Sample:

None


IG_LUT_update_from_byte_array

Group: Grayscale LUT

Declaration:

AT_ERRCOUNT ACCUAPI IG_LUT_update_from_byte_array(
    HIGLUT lut,
    AT_INT ArrayLength,
    const AT_BYTE *lpArray
);

Arguments:

lut
LUT handle.
ArrayLength
Array length.
lpArray
Byte array.

Description:

This function updates LUT from a byte array.

Array length must be equal to 2^InputDepth, where InputDepth is the input depth of the lut.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

None


IG_LUT_update_from_word_array

Group: Grayscale LUT

Declaration:

AT_ERRCOUNT ACCUAPI IG_LUT_update_from_word_array(
    HIGLUT lut,
    AT_INT ArrayLength
    const AT_WORD *lpArray
);

Arguments:

lut
LUT handle.
ArrayLength
Number of WORDs in the array
lpArray
Word array.

Description:

This function updates LUT from a word array.

Array length must be equal to 2^InputDepth, where InputDepth is the input depth of the LUT.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample:

None


IG_mem_CB_register

Group: Callback

Declaration:

AT_ERRCOUNT ACCUAPI IG_mem_CB_register(
    LPFNIG_MEM_ALLOC lpfnAllocFunc,
    LPFNIG_MEM_REALLOC lpfnReAllocFunc,
    LPFNIG_MEM_FREE lpfnFreeFunc
);

Arguments:

lpfnAllocFunc
Far pointer to your function to be called for memory allocations.
lpfnReAllocFunc
Far pointer to your function to be called for memory reallocations.
lpfnFreeFunc
Far pointer to your function to be called to free memory free.

Description:

This function registers your own callback functions to be called to do large memory allocations, memory reallocations, and memory freeing. As shown in the prototype, your memory callback functions must be of types LPFNIG_MEM_ALLOC, LPFNIG_MEM_REALLOC and LPFNIG_MEM_FREE.

NOTE: Your memory allocation functions will only be used when large allocations (allocations greater than 1024) are performed.

Set any of the three arguments to NULL if you want ImageGear to use its own definition for these functions.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Memory Alloc callback function definition
*/
LPBYTE  ACCUAPI MyMemAlloc(DWORD dwSize)/* number of bytes to
alloc    */
{
    /* Put your own memory allocation code here */
    return( buffer);
};
/* Memory ReAlloc callback function definition
*/
LPBYTE ACCUAPI MyMemReAlloc( LPBYTE lpBuffer, DWORD
    dwSize)
{
    /* Put your own memory reallocation code here */
    return( lpBuffer);
};
/* Memory Free callback function definition   */
LPBYTE  ACCUAPI MyMemFree(LPBYTE lpBuffer)
{
    /*Put your free-the-memory code here */
    return NULL;
};
/* Registration Example  */
/* Example one  */
/* Register your own callback functions for all memory routines
*/
nErrcount = IG_mem_CB_register(MyMemAlloc, MyMemReAlloc,
MyMemFree);
/* Example two */
/* Supply callbacks for memory alloc only  */
nErrcount = IG_mem_CB_register(MyMemAlloc, NULL, NULL);

Sample: FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpf_info_get

Group: Multi-page support

Declaration:

AT_ERRCOUNT IG_mpf_info_get(
    [IN]  HMIGEAR hMIGear,
    [OUT] LPAT_MODE lpFileType,
);

Arguments:

hMIGear
Handle to allocated a multi-page image.
lpFileType
Far pointer indicating where to receive file types such as IG_FORMAT_TIF, or IG_FORMAT_MODCA. For a complete list of format types, see the accucnst.h file.

Description:

If a multi-page image hMIGear is associated with the external file image, then this function returns the file format type of the external image through a second parameter, lpFileType. This constant is from the format constant list, which is defined in the accucnst.h include file. If it is not associated with the file, then this function returns an error.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR  hMIGear;  /* handle to multi-page image */
AT_ERRCOUNT	 nErrCount = IGE_SUCCESS;  /* will hold returned
error count  */
AT_MODE	 	nFileType;
 ...
/* initialize multi-page image and assign it with external file
*/
    iErrCnt = IG_mpf_info_get( hMIGear, &nFileType );
    if (!iErrCnt)
    printf("File type:%i\n", (INT)nFileType);

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpf_page_count_get

Group: Multi-page support

Declaration:

AT_ERRCOUNT IG_mpf_page_count_get(
    [IN] HMIGEAR hMIGear,
    [OUT] LPUINT lpnPageCount
);

Arguments:

hMIGear
Handle of the allocated multi-page image.
lpnPageCount
Pointer indicating where to return number of pages of the associated file

Description:

Uses the IG_mpi_file_open ()function to get the number of pages in the external file if it is associated with multi-page image. If the file is not associated with a multi-page image file, the value is 0.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR  hMIGear;      /* handle to multi-page image  */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS; /* will hold returned error
count */
UINT nPageCountI = 0; /* number of pages that should get from
multi-page image */
UINT nPageCountF = 0; /* number of pages that should get from
external source */
HIGEAR hIGear;      /* handle of an image */
 ...
/* initialize multi-page image and assign it with external file
*/
nErrCount = IG_mpi_page_count_get( hMIGear, &nPageCountI );
nErrCount = IG_mpf_page_count_get( hMIGear, &nPageCountF );
printf("Number of pages of multi-page image is:%i\n",
nPageCountI);
printf("Number of pages of external source is:%i", nPageCountF);

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpf_page_delete

Group: Multi-page support

Declaration:

AT_ERRCOUNT IG_mpf_page_delete(
    [IN] HMIGEAR hMIGear,
    [IN] UINT nStartPage,
    [IN] UINT nCount
);

Arguments:

hMIGear
Handle to the allocated multi-page image.
nStartPage
The first page to be deleted
nCount
Number of pages to delete

Description:

This function deletes the nCount number of pages starting with the nStartPage. It then shifts pages with higher numbers to fill the space in the external file associated with the multi-page image using function IG_mpi_file_open (). The multi-page image itself is not changed. Either the multi-page image, or in the external file pages are numbered starting with 0.

NOTE: Not all format filters are supported by this operation. Use the IG_fltr_info_get() function to obtain all information about the supported features for a particular format filter.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR  hMIGear;       /* handle to multi-page image */
AT_ERRCOUNT	 nErrCount = IGE_SUCCESS; /* will hold returned error
count  */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
UINT i;
HIGEAR hIGear;      /* handle of an image */
 ...
/* initialize multi-page image and assign it with external file
*/
nErrCount = IG_mpf_page_count_get( hMIGear, &nPageCount );
for ( i = 0; i < nPageCount; i++ )
    if (!nErrCount)
        if ( !IG_mpi_page_is_valid(hMIGear, i) && (!nErrCount) )
            nErrCount = IG_mpf_page_delete( hMIGear, i, 1 );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpf_page_get

Group: Multi-page support

Declaration:

AT_ERRCOUNT IG_mpf_page_get(
    [IN] HMIGEAR hMIGear,
    [IN] UINT nPage,
    [OUT] LPHIGEAR lphIGear
);

Arguments:

hMIGear
Handle to the allocated multi-page image.
nPage
The index page to load
lphIGear
Indicates where to return the image handle

Description:

If a multi-page image is associated with the external file, it loads a page of the specified index from an external file and returns it using the parameter lphIGear. If a multi-page image is not associated with the external file, or a failure to load a page occurs, then an error is set. This function does not change the multi-page image.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR  hMIGear; /* handle to multi-page image */
AT_ERRCOUNT	  nErrCount = IGE_SUCCESS; /* will hold returned
error count */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
UINT i;
HIGEAR hIGear;    /* handle of an image */
/* initialize multi-page image and assign it with external file
*/
nErrCount = IG_mpf_page_count_get( hMIGear, &nPageCount );
for ( i = 0; i < nPageCount; i++ )
    if (!nErrCount)
    if ( !IG_mpi_page_is_valid(hMIGear, i) && (!nErrCount) )
    {
    nErrCount = IG_mpf_page_load( hMIGear, i, &hIGear );
     ...
    if( IG_image_is_valid( hIGear ) )
    IG_image_delete( hIGear );
    }

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpf_page_info_get

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpf_info_get(
    [IN] HMIGEAR  hMIGear,
    [IN] UINT nPage,
    [OUT] LPAT_MODE lpCompression,
    [OUT] LPAT_DIB lpDib
);

Arguments:

hMIGear
The handle to allocated the multi-page image.
nPage
Index of the page, starting with 0.
lpCompression
Far pointer indicating where to receive the compression method of the given image. It is used for constants such as IG_COMPRESSION_NONE, or IG_COMPRESSION_JPEG. A complete list of compression methods can be found in the accucnst.h file.
lpDib
The far pointer indicating where to return a DIB associated with the page.

Description:

If multi-page image hMIGear is associated with an external file, then this function returns information about the page with an nPage index from the external file. Pages are numbered starting with 0. If the image is not associated with an external file, then this functions returns an error.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;   /* handle to multi-page image  */
AT_ERRCOUNT nErrCount = IGE_SUCCESS; /* will hold returned error
count */
UINT nPageCount = 0;
UINT i;
AT_MODE 	   	nCompression;
AT_DIB	   	Dib;
char str[80];
 ...
/* initialize multi-page image and assign it with external file
*/
     nErrCount = IG_mpf_page_count_get( hMIGear, &nPageCount );
    for( i = 0; i < nPageCount; i++)
      if (!nErrCnt)
    {
    nErrCnt = IG_mpf_page_info_get( hMIGear, i, &nCompression,
&Dib );
    if (!nErrCnt)
    {
    IG_guidlg_compression_name_get( nCompression, str,
sizeof(str) );
    printf( "Page %i\n  Compression method: %s\n", i, str );
    }
}

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpf_page_info_get_ex

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpf_page_info_get_ex(
    HMIGEAR hMIGear,
    UINT nPage,
    LPAT_MODE lpCompression,
    HIGDIBINFO* lpDIB
);

Arguments:

hMIGear
Handle to allocated multi-page image.
nPage
Index of the page, starting with 0.
lpCompression
Pointer indicating where to receive the compression method of the given image. It is used for constants such as IG_COMPRESSION_NONE, or IG_COMPRESSION_JPEG. A complete list of compression methods can be found in the accucnst.h file.
lpDIB
Pointer indicating where to return a DIB info handle associated with the page.

Description:

If multi-page image hMIGear is associated with an external file, then this function returns information about the page with an nPage index from the external file. Pages are numbered starting with 0. If the image is not associated with an external file, then this function returns an error.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;   /* handle to multi-page image  */
AT_ERRCOUNT nErrCount; /* will hold returned error count */
UINT nPageCount = 0;
UINT i;
AT_MODE nCompression;
HIGDIBINFO hDIB;
char str[80];
...
/* initialize multi-page image, assign it with external file */
nErrCount = IG_mpf_page_count_get( hMIGear, &nPageCount );
for( i = 0; i < nPageCount; i++)
if (!nErrCnt)
{
    nErrCnt = IG_mpf_page_info_get_ex( hMIGear, i,
&nCompression, &hDIB );
    if (!nErrCnt)
    {
        IG_guidlg_compression_name_get( nCompression, str,
sizeof(str) );
        printf( "Page %i\n  Compression method: %s\n", i, str );
    }
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpf_page_load

Group: Multi-page support

Declaration:

AT_ERRCOUNT IG_mpf_page_load(
    [IN] HMIGEAR hMIGear,
    [IN] UINT nStartPage,
    [IN] UINT nCount
);

Arguments:

hMIGear
The handle of the allocated multi-page image.
nStartPage
The first page to be loaded
nCount
The total number of pages to be loaded

Description:

If a multi-page image is associated with an external file, it loads and stores the specified number of pages from the external file into a multi-page image. To access the loaded pages, use the IG_mpi_page_get () function.

If the multi-page image is not associated with an external file, or a failure to load a page occurs, then an error is set. This function loads each Nth page from a file into the correspondent Nth page into the multi-page image. Previous page values are not deleted with function IG_image_delete (). If necessary, the number of pages is expanded to fit all loaded pages.

NOTE: The access to the same PDF document from multiple threads is not permitted because the multiple threads cannot share Adobe PDF Library datatypes. PDF doc created/opened in the main thread can be only used from the main thread.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;     /* handle to multi-page image */
AT_ERRCOUNT nErrCount = IGE_SUCCESS; /* will hold returned error
count */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
UINT i;
HIGEAR hIGear;     /* handle of an image */
 ...
/* initialize multi-page image and assign it with external file
*/
nErrCount = IG_mpf_page_count_get( hMIGear, &nPageCount );
for ( i = 0; i < nPageCount; i++ )
    if (!nErrCount)
    if ( !IG_mpi_page_is_valid(hMIGear, i) && (!nErrCount) )
    nErrCount = IG_mpf_page_load( hMIGear, i, 1 );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpf_page_save

Group: Multi-page support

Declaration:

AT_ERRCOUNT IG_mpf_page_save(
    [IN] HMIGEAR hMIGear,
    [IN] UINT nStartPage,
    [IN] UINT nCount,
    [IN] AT_MODE nCompression,
    [IN] AT_MODE nSaveMode
);

Arguments:

hMIGear
The handle of the multi-page image.
nStartPage
First page to save
nCount
Total number of pages to save
nCompression
Compression method to be used when saving the pages
nSaveMode
The methods for saving the pages can be:
  • IG_MPF_SAVE_INSERT
  • IG_MPF_SAVE_REPLACE

Description:

If the multi-page image is associated with an external file then this function saves the specified pages from multi-page image to the external file. If nSaveMode is IG_MPF_SAVE_INSERT, then the specified nCount number of pages are inserted, starting with nStartPage index, and all previous pages are shifted to a higher page number. If nSaveMode is IG_MPF_SAVE_REPLACE, then the function replaces the specified nCount number of pages, starting with the nStartPage index. If a page is NULL in the multi-page image, it is skipped and not saved.

This function takes each specified Nth page from a multi-page image and saves it as the Nth page into an external file. If the image is not associated with an external file, then it returns an error.

NOTE: Not all format filters support IG_MPF_SAVE_REPLACE mode. Use the IG_fltr_info_get() function to obtain information about the supported features for specific format filters.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;      /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS; /* will hold returned error
count  */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
UINT i;
HIGEAR hIGear;      /* handle of an image */
 ...
/* initialize multi-page image and assign it with external file
*/
nErrCount = IG_mpf_page_count_get( hMIGear, &nPageCount );
if ( !nErrCount && (nPageCount > 0) )
IG_mpf_page_save( hMIGear, 0, 1, IG_COMPRESSION_NONE,
IG_MPF_SAVE_INSERT );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpf_page_swap

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpf_page_swap(
    [IN] HMIGEAR hMIGear,
    [IN] UINT nPage1,
    [IN] UINT nPage2
);

Arguments:

hMIGear
The handle of the multi-page image.
nPage1
The number of first page to swap.
nPage2
The number of second page to swap.

Description:

If the multi-page image is associated with an external file, then this function swaps pages with the given page numbers in the external file. If the multi-page image is not associated with an external file, an error is returned. Pages are numerated starting with 0. The multi-page image is not changed.

NOTE: Not all format filters support IG_mpf_page_swap() mode. Use the IG_fltr_info_get() function to obtain information about the supported features for specific format filters.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR	 hMIGear;       /* handle to multi-page image  */
AT_ERRCOUNT  nErrCount = IGE_SUCCESS; /* will hold returned
error count */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
 ...
/* initialize multi-page image and assign it with external file
*/
nErrCount = IG_mpf_page_count_get( hMIGear, &nPageCount );
/* Swap first page and last pages */
if (!nErrCount && nPageCount > 1)
    nErrCount += IG_mpf_page_swap(hMIGear, 0, nPageCount - 1 );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpf_page_unload

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpf_page_unload(
    [IN] HMIGEAR hMIGear,
    [IN] UINT nStartPage,
    [IN] UINT nCount
);

Arguments:

hMIGear
The handle to the valid multi-page image.
nStartPage
The number of the first page to unload.
nCount
The total number of pages to unload

Description:

This function calls IG_image_delete () for the nCount number of pages in the multi-page image, starting with the nStartPage position. The number of pages in the multi-page image is not changed, but the specified positions are removed and set to a default value of NULL. The pages are numbered starting with 0.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR  hMIGear;      /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS; /* will hold returned error
count */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
UINT i;
HIGEAR hIGear;  /* handle of an image */
 ...
/* initialize multi-page image and assign it with external file
*/
nErrCount = IG_mpf_page_count_get( hMIGear, &nPageCount );
for ( i = 0; i < nPageCount; i++ )
    if ( IG_mpi_page_is_valid(hMIGear, i) && (!nErrCount) )
    nErrCount = IG_mpf_page_unload( hMIGear, i, 1 );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpf_tile_count_get

Group: Multi-page support

Declaration:

AT_ERRCOUNT IG_mpf_tile_count_get(
    [IN] HMIGEAR hMIGear,
    [IN] UINT nPage,
    [OUT] LPUINT lpTileRows,
    [OUT] LPUINT lpTileCols
);

Arguments:

hMIGear
The handle of the multi-page image
nPage
The page number from which to get the tile count
LpTileRows
The far pointer to a UINT variable to receive the number of tile rows (for tiled images)
LpTileCols
The far pointer to a UINT variable to receive the number of tile columns (tiled images)

Description:

If the multi-page image is associated with an external file, then this function returns the tile information for the specified page number. An error returns if the image is not associated with an external file. Pages are numbered starting with 0.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR  hMIGear;     /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS; /* will hold returned error
count */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
UINT nTileRows;
UINT nTileCols;
 ...
/* initialize multi-page image and assign it with external file
*/
nErrCount = IG_mpf_page_count_get( hMIGear, &nPageCount );
/* Count number of tiles in the first page */
if (!nErrCount && nPageCount > 0)
    nErrCount += IG_mpf_tile_count_get(hMIGear, 0, &nTileRows,
&nTileCols );
if (!nErrCount)
{
    printf( "Number of tiles in a row:%i\n", nTileRows );
    printf( "Number of tiles in a colomns:&i\n", nTileCols );
}

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_CB_get

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpi_CB_get(
    [IN] HMIGEAR hMIGear,
    [IN] DWORD dwCBID,
    [OUT] LPVOID FAR* lplpPrivate,
    [OUT] LPFNIG_MPCB_UPDATE FAR* lplpfnUpdate
);

Arguments:

hMIGear
The handle of the allocated multi-page image.
dwCBID
A unique identifier of the private data and function.
lplpPrivate
A pointer indicating where to receive the private data.
lplpfnUpdate
A pointer indicating where to receive the update function.

Description:

See the IG_mpi_CB_set () documentation for a description of how notification works with multi-page images. This function returns information about the associated private data pointer and update function using the dwCBID identifier.

If there is no association with an external file, then NULL values are assigned to both pointers.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR	 	hMIGear;    /* handle to multi-page image */
AT_ERRCOUNT nErrCount = IGE_SUCCESS; /* will hold returned error
count */
LPVOID lpData;
LPFNIG_MPCB_UPDATE        lpUpdateFunc;
DWORD dwCBID;
 ...
nErrCount = IG_mpi_CB_set( hMIGear, (LPVOID)hMIGear,
_MPWndUpdate, &dwCBID );
 ...
nErrCount = IG_mpi_CB_get( hMIGear, dwCBID, &lpData,
&lpUpdateFunc );
 ...
VOID  ACCUAPI  _MPWndUpdate(
   DWORD          dwCBID,
   LPVOID         lpPrivate,     /* Private data passed in */
   AT_MODE        nMode,
   UINT           nPage,
   UINT           nCount
)
{
   switch( nMode )
   {
   case  IG_MPCBMODE_MPI_DELETE:
     ...
      break;
   case  IG_MPCBMODE_MPI_ASSOCIATED:
     ...
      break;
   case  IG_MPCBMODE_MPI_CLOSE:
     ...
      break;
     ...
   }
}

Samle: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_CB_reset

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpi_CB_reset(
    [IN] HMIGEAR hMIGear,
    [IN] DWORD dwCBID
);

Arguments:

hMIGear
Handle to allocated multi-page image.
dwCBID
Unique identifier of private data and function.

Description:

See the IG_mpi_CB_set ()documentation for a description of how notification works with multi-page images. This function removes previously associated callback data from the multi-page image using the dwCBID identifier. After calling this function, the appropriate callback function receives notifications and removes the data from the active list.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR  hMIGear;      /* handle to multi-page image */
AT_ERRCOUNT nErrCount = IGE_SUCCESS; /* will hold returned error
count  */
LPVOID lpData;
LPFNIG_MPCB_UPDATE    lpUpdateFunc;
DWORD dwCBID;
 ...
nErrCount = IG_mpi_CB_set( hMIGear, (LPVOID)hMIGear,
_MPWndUpdate, &dwCBID );
 ...
nErrCount = IG_mpi_CB_reset( hMIGear, dwCBID );
 ...
}
VOID  ACCUAPI  _MPWndUpdate(
   DWORD          dwCBID,
   LPVOID         lpPrivate,     /* Private data passed in
*/
   AT_MODE        nMode,
   UINT           nPage,
   UINT           nCount
)
{
   switch( nMode )
   {
   case  IG_MPCBMODE_MPI_DELETE:
     ...
      break;
   case  IG_MPCBMODE_MPI_ASSOCIATED:
     ...
      break;
   case  IG_MPCBMODE_MPI_CLOSE:
     ...
      break;
     ...
   }
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_CB_reset_all

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpi_CB_reset_all(
    [IN] HMIGEAR hMIGear
);

Arguments:

hMIGear
The handle to the allocated multi-page image.

Description:

This function works the same way as the IG_mpi_CB_reset () function, but removes all callback data and functions from the multi-page image.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;     /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS; /* will hold returned error
count  */
DWORD dwCBID1, dwCBID2;
 ...
nErrCount = IG_mpi_CB_set( hMIGear, (LPVOID)hMIGear,
_MPWndUpdate, &dwCBID1 );
nErrCount = IG_mpi_CB_set( hMIGear, (LPVOID)hMIGear,
_MPWndUpdate, &dwCBID2 );
 ...
nErrCount = IG_mpi_CB_reset_all( hMIGear );
 ...
}
VOID  ACCUAPI  _MPWndUpdate(
   DWORD          dwCBID,
   LPVOID         lpPrivate,     /* Private data passed in  */
   AT_MODE        nMode,
   UINT           nPage,
   UINT           nCount
)
{
   switch( nMode )
   {
   case  IG_MPCBMODE_MPI_DELETE:
     ...
      break;
   case  IG_MPCBMODE_MPI_ASSOCIATED:
     ...
      break;
   case  IG_MPCBMODE_MPI_CLOSE:
     ...
      break;
     ...
   }
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_CB_set

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI  IG_mpi_CB_set(
    [IN] HMIGEAR hMIGear,
    [IN] LPVOID lpPrivate,
    [IN] LPFNIG_MPCB_UPDATE lpfnUpdate,
    [OUT] LPDWORD lpdwCBID,
);

Arguments:

hMIGear
The handle to the allocated multi-page image.
lpPrivate
Any private data.
lpfnUpdate
The pointer to the update function
lpdwCBID
Indicates where to return the ID of the associated callback data.

Description:

Multi-page images allow you to notify the application about status changes. Use this function to call code that associates the given multi-page image hMIGear with any lpPrivate data, and updates the defined function as shown below:

typedef  VOID (LPACCUAPI LPFNIG_MPCB_UPDATE)(
   DWORD          dwCBID,
   LPVOID         lpPrivate,     /* Private data passed in
*/
   AT_MODE        nMode,
   UINT           nPage,
   UINT           nCount
);

It returns a unique identifier, which allows multi-page associations with the given information. After the association is made, the application receives notifications about changes to the multi-page image through this function.

The Callback function parameters are described in the table below:

dwCBID
The identifier allocated for this callback function by IG_mpi_CB_set ()
lpPrivate
The private data associated with this identifier
nMode
The type of multi-page image change
nPage, nCount
Usually the first number and and total number of changed pages.

The following table lists all possible values for nMode and the appropriate sense of the nPage and nCount parameters:

nMode
nPage
nCount
Description
IG_MPCBMODE_MPI_
DELETE
Not used
Not used
Notifies the application that the multi-page image is going to be deleted.
IG_MPCBMODE_MPI_
ASSOCIATED
Not used
Not used
Notifies the application that the multi-page image is associated with an external file.
IG_MPCBMODE_MPI_
CLOSE
No used
Not used
Notifies the application that the multi-page image is going to close the associated external file
IG_MPCBMODE_MPI_
CB_SET
Not used
Not used
Notifies the application that this callback data is set. This notification receives only the callback function that has just been set.
IG_MPCBMODE_MPI_
CB_RESET
Not used
Not used
Notifies the application that this callback data is to be reset.
IG_MPCBMODE_MPI_
PAGEINSERTED
index of where
new pages starts
number of new
pages inserted
Notifies the application that new pages have been inserted into the multi-page image.
IG_MPCBMODE_MPI_
PAGEUPDATED
index of the first
updated page
number of updated
pages starting from
nPage
Indicates that the application has updated pages in the multi-page image
IG_MPCBMODE_MPI_
PAGEDELETED
index of first
deleted page
number of deleted
pages
Indicates that the application has deleted pages in the multi-page image.
IG_MPCBMODE_MPF_
PAGEINSERTED
index of where
new pages starts
number of new
pages inserted
Indicates that the application has inserted new pages into the external file image.
IG_MPCBMODE_MPF_
PAGEUPDATED
index of the first
updated page
number of updated
pages starting from
nPage
Indicates that the application has updated pages in the external multi-page image file.
IG_MPCBMODE_MPF_
PAGEDELETED
index of the first
deleted page
number of deleted
pages
Application deleted pages in the external multi-page image file

NOTE: The notification function blocks the execution of the operation that performed the action. This function can be used for thread synchronization. We do not recommended that you call a multi-page API from the notification function (to prevent an unlimited loop from occurring).

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;     /* handle to multi-page image */
AT_ERRCOUNT  nErrCount = IGE_SUCCESS; /* will hold returned
error count */
LPVOID lpData;
LPFNIG_MPCB_UPDATE    lpUpdateFunc;
DWORD dwCBID;
 ...
nErrCount = IG_mpi_CB_set( hMIGear, (LPVOID)hMIGear,
_MPWndUpdate, &dwCBID );
 ...
nErrCount = IG_mpi_CB_get( hMIGear, dwCBID, &lpData,
&lpUpdateFunc );
 ...
}
VOID  ACCUAPI  _MPWndUpdate(
   DWORD          dwCBID,
   LPVOID         lpPrivate,     /* Private data passed in */
   AT_MODE        nMode,
   UINT           nPage,
   UINT           nCount
)
{
   switch( nMode )
   {
   case  IG_MPCBMODE_MPI_DELETE:
     ...
      break;
   case  IG_MPCBMODE_MPI_ASSOCIATED:
     ...
      break;
   case  IG_MPCBMODE_MPI_CLOSE:
     ...
      break;
     ...
   }
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_close

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpi_close( HMIGEAR hMIGear );

Arguments:

hMIGear
The handle to the allocated multi-page image.

Description:

If the multi-page image hMIGear was previously associated with an external image file using the function IG_mpi_file_open (), then this function closes the file and frees all corresponding resources. If the multi-page image is not associated with an external file, then this function does nothing.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;    /* handle to multi-page image */
AT_ERRCOUNT nErrCount = IGE_SUCCESS;  /* will hold returned
error count */
nErrCount = IG_mpi_create( &hMIGear, 0 );
 ...
/* any operations with hMIGear */
nErrCount = IG_mpi_close( hMIGear );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_create

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpi_create(
    LPHMIGEAR lphMIGear,
    UINT nPages
);

Arguments:

lpHMIGear
A pointer indicating where to return the handle of the allocated and initialized multi-page image.
nPage
The number of multi-page image pages that should be created.

Description:

This function allocates and initializes a new multi-page image and returns its handle. This new image is set with nPages. Each image is initialized with the default value NULL. If there is a failure, then the returned handle is NULL and an error is set.

The multi-page image is array of pages where each page is a HIGEAR object. All pages are numbered beginning with a 0 index, so that 0 - is the first page, 1 - is the second page, etc. If the image contains nCount number of pages, then its pages can be accessed through indexes 0 - nCount-1. The value of each page can be either NULL (default value) or value HIGEAR image.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR       hMIGear;     /* handle to multi-page image */
AT_ERRCOUNT   nErrCount = IGE_SUCCESS; /* will hold returned
error count */
nErrCount = IG_mpi_create( &hMIGear, 0 );
 ...
/* any operations with hMIGear */
nErrCount = IG_mpi_delete( hMIGear );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_delete

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI  IG_mpi_delete( HMIGEAR hMIGear );

Arguments:

hMIGear
Handle to allocated multi-page image.

Description:

This function calls IG_image_delete () for all valid pages of multi-page image and frees all resources allocated with multi-page image handle. If it is associated with external file then it is closed with IG_mpi_close () before deletion.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;    /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS; /* will hold returned error
count */
nErrCount = IG_mpi_create( &hMIGear, 0 );
 ...
/* any operations with hMIGear */
nErrCount = IG_mpi_delete( hMIGear );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_file_open

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpi_file_open(
    [IN] const LPCHAR lpFileName,
    [IN] HMIGEAR hMIGear,
    [IN] AT_MODE nFormat,
    [IN] AT_MODE nOpenMode
);

Arguments:

lpFileName
The far pointer to the filename (you may include the path with the filename) of the image file to be associated with a given multi-page image
hMIGear
The handle to the allocated multi-page image.
nFormat
The format of the file, such as IG_FORMAT_UNKNOWN or IG_FORMAT_TIF. See the accucnst.h file for a list of all available IG_FORMAT_... constants.
nOpenMode
An AT_MODE constant, such as IG_MP_OPENMODE_READONLY or IG_MP_OPENMODE_READWRITE

Description:

This function allows you to associate a multi-page image with an external image file. After the association is made, you can then use different page manipulation functions, such as page load, save, delete, and swap. With this association operation, ImageGear allows you to store internal data, allowing you to make page operations faster than if using IG_fltr_... functions. This file can be opened with two modes - IG_MP_OPENMODE_READONLY and IG_MP_OPENMODE_READWRITE.

The first mode, read-only access, it is used only when page loading is necessary. It does not allow you to change the external file. When the image is opened with read only access, it sets the number of pages in the multi-page image equal to the number of pages in the external file using IG_mpi_page_count_set ()function.

The second mode opens file for read-write access and allows all possible page operations with the external file. The multi-page image is not changed.

NOTE: Not all filters support all page manipulation operations. Use the function IG_fltr_info_get(), which returns the information about all supported features of a particular filter.

IG_MP_OPENMODE_NONE is also accepted as a value for nOpenMode and, in this case, this call is equivalent to the IG_mpi_close () call.

The nFormat parameter is used only if a new image file is to be created and nOpenMode= IG_MP_OPENMODE_READWRITE. In this case, the file of the specified format is created. In all other cases this parameter is ignored.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR  hMIGear;    /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS; /* will hold returned error
count */
nErrCount = IG_mpi_create( &hMIGear, 0 );
if (!nErrCount)
nErrCount = IG_mpi_file_open( "picture1.tif", hMIGear, 0,
IG_MP_OPEN_READ );
...
nErrCount = IG_mpi_delete( hMIGear );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_file_save

Group: Multi-page support

Declaration:

AT_ERRCOUNT LACCUAPI IG_mpi_file_save(
    [IN] const LPCHAR lpFileName,
    [IN] HMIGEAR hMIGear,
    [IN] UINT nStartPageFile,
    [IN] UINT nStartIndexDoc,
    [IN] UINT nPageCount,
    [IN] AT_MODE nFormat,
    [IN] AT_MODE nSaveMode
);

Arguments:

lpFileName
Output file name
hMIGear
Multi-page vector document
nStartPageFile
The page number in lpFileName after which pages from hMIGear are inserted. The first page is 0.
nStartIndexDoc
The page number of the first page in hMIGear to save.The first page is 0.
nPageCount
Total number of pages to save
nFormat
IG_FORMAT_PDF or IG_FORMAT_POSTSCRIPT
nSaveMode
IG_MPI_SAVE_OVERWRITE or IG_MPI_SAVE_APPEND

Description:

Use this function to save a multi-page vector document to a file.

NOTE: This function is only used for multi-page vector documents. The following formats are currently supported by this API: PDF, PostScript.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR  hMIGear;    /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS; /* will hold returned error
count */
nErrCount = IG_mpi_create( &hMIGear, 0 );
if (!nErrCount)
nErrCount = IG_mpi_file_open( "picture1.tif", hMIGear, 0,
IG_MP_OPEN_READ );
...
nErrCount = IG_mpi_delete( hMIGear );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_info_get

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpi_info_get(
    [IN] HMIGEAR hMIGear,
    [IN] AT_MODE nMode,
    [IN/OUT] LPVOID lpData,
    [IN] DWORD dwSize
);

Arguments:

hMIGear
The handle to the allocated multi-page image.
nMode
This argument is used to determine the type of information being retrieved
lpData
The far pointer to the buffer indicating where to return the allocated data
dwSize
The size of the buffer

Description:

This function returns status information for the multi-page image, such as the association type, open mode, as well as others. (See the table below.)

Value of parameters depends on nMode. Below in the table is list of all possible combinations.

AT_MODE
constants
Type of third
argument
dwSize
Description
IG_MP_ASSOCIATION_TYPE
LPAT_MODE
Sizeof
(AT_MODE)
Returns the association type of the given multi-page image, which can be:
  • IG_MP_ASSOCIATE_NONE
  • IG_MP_ASSOCIATE_FILE
  • [*]IG_MP_ASSOCIATE_MEMORY
IG_MP_OPENMODE
LPAT_MODE
Sizeof(AT_MODE)
Returns the open mode of the associated file, which can be:
  • IG_MP_OPENMODE_NONE
  • IG_MP_OPENMODE_READONLY
  • IG_MP_OPENMODE_READWRITE
IG_MP_FILE_
NAME
LPCHAR
Length of the
buffer
including last 0
byte
Returns the name of the associated file
[*]IG_MP_MEM_
BUFFER_PTR
LPBYTE
4
Returns a pointer to the memory associated with the multipage image
[*]IG_MP_MEM_
BUFFER_SIZE
LPDWORD
4
Returns the size of the associated memory
IG_MP_FORMAT
File format of the multi-page document. One of the enumIGFormats values.
IG_MP_DOCUMENT
Native document associated with the multi-page document.

[*] - not implemented now.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR  hMIGear;     /* handle to multi-page image */
AT_ERRCOUNT	 nErrCount = IGE_SUCCESS;  /* will hold returned
error count */
HIGEAR hIGear;     /* handle of an image */
AT_MODE nAType;
CHAR FileName[_MAX_PATH];
 ...
/* initialize of multi-page image and assign it with external
file */
nErrCount = IG_mpi_info_get( hMIGear, IG_MP_ASSOCIATION_TYPE ,
&nAType, sizeof(nAType) );
if( nAType== IG_MP_ASSOCIATE_FILE )
{
    IG_mpi_info_get( hMIGear, IG_MP_FILE_NAME, FileName,
sizeof(FileName) );
}

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_is_valid

Group: Multi-page support

Declaration:

AT_BOOL ACCUAPI IG_mpi_is_valid( HMIGEAR hMIGear );

Arguments:

hMIGear
Handle to allocated multi-page image.

Description:

This function is used for checking whether the hMIGear value is a valid multi-page image handle. The multi-page image is valid if the IG_mpi_create () function is returned successfully and IG_mpi_delete () has not been called.

Bits Per Pixel: All

Return Value:

Returns TRUE if the given multi-page image is valid.

Example:

HMIGEAR hMIGear;       /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS; /* will hold returned error
count */
nErrCount = IG_mpi_create( &hMIGear, 0 );
if ( IG_mpi_is_valid(hMIGear) )
    printf("The multi-page image is valid!");
else
    printf("It's not valid multi-page image!");
IG_mpi_delete( hMIGear );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_page_count_get

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpi_page_count_get(
    [IN] HMIGEAR hMIGear,
    [OUT] LPUINT lpPageCount
);

Arguments:

hMIGear
Handle to the allocated multi-page image.
lpPageCount
Pointer indicting where to return the number of pages of the given multi-page image

Description:

This function returns the number of pages in a multi-page image (the size of page array).

NOTE: The HIGEAR handle of any given page is not significant in this function, other than to identify the image; this function simply counts the array size.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;    /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS; /* will hold returned error
count  */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
UINT i,
        j = 0;
HIGEAR hIGear;    /* handle of an image */
 ...
/* initialize multi-page image and assign it with external file
*/
nErrCount = IG_mpi_page_count_get( hMIGear, &nPageCount );
for ( i = 0; i < nPageCount; i++ )
    if (!nErrCount)
    {
        nErrCount = IG_mpi_page_get( hMIGear, i, &hIGear );
        if (IG_mpi_page_is_valid(hMIGear, i))
            j++;
    }
printf("Number of valid pages is:%i", j);

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_page_count_set

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpi_page_count_set(
    [IN] HMIGEAR  hMIGear,
    [IN] UINT  nPageCount
);

Arguments:

hMIGear
The handle to the allocated multi-page image.
nPageCount
The new number of pages

Description:

This function sets the size of the page array of a valid multi-page image. If the size is increased, then new pages are initialized with a default value of NULL. If the array is reduced, then the removed pages are not deleted with the function IG_image_delete (). This function applies only to the image, but does not affect the associated file. The number of pages is not changed.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;       /* handle to multi-page image */
AT_ERRCOUNT nErrCount = IGE_SUCCESS; /* will hold returned error
count */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
UINT i,
 ...
/* initialize of multi-page image and assign it with external
file */
nErrCount = IG_mpi_page_count_get( hMIGear, &nPageCount );
if (!nErrCount)
{
    i = 0;
    while( !IG_mpi_page_is_valid(hMIGear, nPageCount - i - 1 )
&& (i < nPageCount) )
        i++;
    }
    if (!nErrCount)
        nErrCount = IG_mpi_page_count_set( hMIGear, nPageCount -
i );
}

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_page_delete

Group: Multi-page support

Declaration:

AT_ERRCOUNT ACCUAPI IG_mpi_page_delete(
    [IN] HMIGEAR hMIGear,
    [IN] UINT nStartPage,
    [IN] UINT nCount
);

Arguments:

hMIGear
The handle to the allocated multi-page image.
nStartPage
The first page to delete
nCount
The total number of pages to delete

Description:

This function deletes the nCount number of elements starting with the nStartPage index from the page array of the multi-page image. If the deleted pages are valid images, they are deleted with the function IG_image_delete (). Pages with higher indexes are shifted by removing the number and number of pages is decreased so that all pages are numbered from 0 to nPageCount-1.

NOTE: For multi-page vector documents, this function DELETES a page in the underneath vector document data. The following formats are currently supported by this API: PDF, PostScript.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;     /* handle to multi-page image */
AT_ERRCOUNT nErrCount = IGE_SUCCESS; /* will hold returned error
count */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
UINT i;
HIGEAR hIGear;         /* handle of an image */
 ...
/* initialize of multi-page image and assign it with external
file */
nErrCount = IG_mpi_page_count_get( hMIGear, &nPageCount );
/* delete all pages and shrink array to entries pages */
nErrCount = IG_mpi_page_delete( hMIGear, 0, nPageCount );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_page_get

Group: Multi-page support

Declaration:

AT_ERRCOUNT  ACCUAPI  IG_mpi_page_get(
    [IN] HMIGEAR hMIGear,
    [IN] UINT nPage,
    [OUT] LPHIGEAR lpHIPage
);

Arguments:

hMIGear
The handle to the allocated multi-page image.
nPage
The number of the page to return
lpHIPage
The far pointer indicating where to return a handle of the page.

Description:

This function returns the value of a page array with index nPage. This can be either NULL or a valid HIGEAR handle.

The multi-page image is not changed. This function makes a copy of the page handle.

This function does not load the page from an external file, but just returns the current page value of the multi-page image.

NOTE: For multi-page vector documents, this function GETS a page from the underneath vector document data. The following formats are currently supported by this API: PDF, PostScript.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR hMIGear;        /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS;   /* will hold returned
error count */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
UINT I = 0;
HIGEAR hIGear;     /* handle of an image */
 ...
nErrCount = IG_mpi_page_get( hMIGear, i, &hIGear );
 ...

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_page_is_valid

Group: Multi-page support

Declaration:

AT_BOOL ACCUAPI IG_mpi_page_is_valid(
    [IN] HMIGEAR hMIGear,
    [IN] UINT nPage,
);

Arguments:

hMIGear
The handle to the allocated multi-page image.
nPage
The index of the page to check.

Description:

This function returns information about the page with a given index. If the page with such an index exists as well as a valid HIGEAR handle, then it returns TRUE. In all other cases FALSE is returned.

Bits Per Pixel: All

Return Value:

Returns TRUE if the given page is valid.

Example:

HMIGEAR	 hMIGear;      /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount;   /* will hold returned error count */
UINT nPageCount = IGE_SUCCESS; /* number of pages that should
get from multi-page image */
UINT i;
HIGEAR hIGear;     /* handle of an image */
 ...
/* initialize of multi-page image and assign it with external
file */
nErrCount = IG_mpi_page_count_get( hMIGear, &nPageCount );
for ( i = 0; i < nPageCount; i++ )
    if ( !IG_mpi_page_is_valid(hMIGear, i) && (!nErrCount) )
    nErrCount = IG_mpi_page_unload( hMIGear, i, 1 );

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mpi_page_set

Group: Multi-page support

Declaration:

AT_ERRCOUNT IG_mpi_page_set(
    [IN] HMIGEAR hMIGear,
    [IN] UINT nPage,
    [IN] HIGEAR hIPage
);

Arguments:

hMIGear
The handle to the allocated multi-page image.
nPage
The index of the page to set
hIPage
The handle of the image to set

Description:

This function assigns a new value to the page of the multi-page image. The previous value is not deleted with the IG_image_delete () function. The size of the multi-page image is not changed, so that page arrays is not expanded when nPage is greater than nPageCount-1.

NOTE: For multi-page vector documents, this function SETS a page to the underneath vector document data. The following formats are currently supported by this API: PDF, PostScript.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HMIGEAR	 hMIGear;       /* handle to multi-page image */
AT_ERRCOUNT	 	nErrCount = IGE_SUCCESS; /* will hold returned error
count */
UINT nPageCount = 0; /* number of pages that should get from
multi-page image */
HIGEAR hPage1,
        hPage2;
 ...
/* initialize of multi-page image and assign it with external
file */
nErrCount = IG_mpi_page_count_get( hMIGear, &nPageCount );
/* Swap first page and last page */
if (!nErrCount && nPageCount > 1)
{
    nErrCount += IG_mpi_page_get( hMIGear, 0, &hPage1 );
    nErrConut += IG_mpi_page_get( hMIGear, nPageCount - 1,
&hPage2 );
    if (!nErrCount)
    {
    nErrCount += IG_mpi_page_set(hMIGear, iPage1, hPage2 );
    nErrCount += IG_mpi_page_set(hMIGear, iPage2, hPage1 );
    }
}

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_audio_format_get

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_audio_format_get(
    HIGMULT hMult,
    LPAT_UINT lpSampleRate,
    LPAT_UINT lpBitsPerSample,
    LPAT_UINT lpChannels
);

Arguments:

hMult
Multimedia instance handle
lpSampleRate
Number of samples per second
lpBitsPerSample
Number of bits per sample
lpChannels
Number of channels (1 = mono, 2 = stereo)

Description:

This function retrieves the format of the audio in a multimedia instance. Note that audio retrieved using IG_mult_audio_get() is always in uncompressed PCM format. If the multimedia instance does not contain audio, an error will occur.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_UINT nSampleRate;    /* Sample rate of audio */
AT_UINT nBitsPerSample; /* Bits per sample */
AT_UINT nChannels;      /* Number of channels */
nErrcount = IG_mult_audio_format_get(hMult, &nSampleRate,
&nBitsPerSample, &nChannels);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_audio_format_set

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_audio_format_set(
    HIGMULT hMult,
    LPAT_UINT lpSampleRate,
    LPAT_UINT lpBitsPerSample,
    LPAT_UINT lpChannels
);

Arguments:

hMult
Multimedia instance handle
lpSampleRate
Number of samples per second
lpBitsPerSample
Number of bits per sample
lpChannels
Number of channels (1 = mono, 2 = stereo)

Description:

This function sets the format of the audio to be retrieved from a multimedia instance. This is not a necessary step under normal circumstances. If possible, the audio will be converted to the format you specify as it is retrieved using IG_mult_audio_get(). If conversion is not possible, an error will occur.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Ask for 44100Hz 16-bit stereo audio */
AT_ERRCOUNT nErrcount;       /* Number of errors on stack */
HIGMULT hMult;               /* Multimedia instance handle */
AT_UINT nSampleRate = 44100; /* Sample rate of audio */
AT_UINT nBitsPerSample = 16; /* Bits per sample */
AT_UINT nChannels = 2;       /* Number of channels */
nErrcount = IG_mult_audio_format_set(hMult, &nSampleRate,
&nBitsPerSample, &nChannels);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_audio_get

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_audio_get(
    HIGMULT hMult,
    LPAT_VOID lpBuffer,
    LPAT_UINT lpBufferSize
);

Arguments:

hMult
Multimedia instance handle
lpBuffer
Buffer to store audio data in
lpBufferSize
Pointer to the number of bytes of audio to retrieve (in), and the number of bytes actually retrieved (out)

Description:

This function retrieves the next available audio data from a multimedia instance. You must specify the number of bytes of audio data to retrieve in the value pointed to by lpBufferSize, and this number must be a multiple of the sample size ((nBitsPerSample / 8) * nChannels). Audio data is provided in uncompressed PCM format.

You can call this function repeatedly for buffered access to the audio data (for example, one second of audio at a time) or you can retrieve all of the audio at once.

Note that the number of bytes retrieved by this function is returned in the lpBufferSize parameter. If you requested more data than is available (for example, you are near the end of the file) this number will be less than what you requested.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_UINT nSampleRate;    /* Sample rate of audio */
AT_UINT nBitsPerSample; /* Bits per sample */
AT_UINT nChannels;      /* Number of channels */
LPAT_BYTE lpBuffer;     /* Audio buffer */
AT_UINT bufSize;        /* Size of audio buffer */
nErrcount = IG_mult_audio_format_get(hMult, &nSampleRate,
&nBitsPerSample, &nChannels);
/* Calculate # of bytes for one second of audio */
bufSize = nSamplesPerSec * (nBitsPerSample / 8) * nChannels;
lpBuffer = (LPAT_BYTE) malloc(bufSize);
nErrcount = IG_mult_audio_get(hMult, lpBuffer, &bufSize);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_audio_seek_time

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_audio_seek_time(
    HIGMULT hMult,
    AT_UINT msTime
);

Arguments:

hMult
Multimedia instance handle
msTime
Time in milliseconds to seek to

Description:

This function sets the starting position within a multimedia instance for the next audio to be retrieved using IG_mult_audio_get(). If you are streaming audio by calling IG_mult_audio_get() repeatedly, you should not call this function each time you call IG_mult_audio_get(). Excessive seeking could result in discontinuities in the retrieved audio.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_UINT msDuration;     /* Duration of file in milliseconds */
/* Seek to beginning */
nErrcount = IG_mult_audio_seek_time(hMult, 0);
/* Seek to half way */
nErrcount = IG_mult_duration_get(hMult, NULL, &msDuration);
nErrcount = IG_mult_audio_seek_time(hMult, msDuration / 2);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_close

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_close(HIGMULT hMult);

Arguments:

hMult
Multimedia instance handle

Description:

This function closes a multimedia instance. You must call this function after opening a multimedia instance in order to ensure that all associated resources are freed.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
nErrcount = IG_mult_close(hMult);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_current_frame_advance

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_current_frame_advance(HIGMULT
hMult);

Arguments:

hMult
Multimedia instance handle

Description:

This function advances the current frame to the next frame. You can use this in a loop to iterate over all of the frames. This function will not generate an error when you advance beyond the last available frame. You should use IG_mult_current_frame_is_valid() to determine whether or not the end has been reached.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_BOOL bValid;         /* Is current frame valid? */
HIGEAR hIGear;          /* HIGEAR handle of image */
while (IG_mult_current_frame_is_valid(hMult, &bValid) ==
IGE_SUCCESS && bValid)
{
    nErrcount = IG_mult_current_frame_image_get(hMult, &hIGear);
    nErrcount = IG_mult_current_frame_advance(hMult);
}

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_current_frame_duration_get

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_current_frame_duration_get(
    HIGMULT hMult,
    LPAT_UINT lpDuration
);

Arguments:

hMult
Multimedia instance handle
lpDuration
Frame duration (in 100ns units)

Description:

This function returns the duration of the current frame in 100 nanosecond units. This provides a reasonable level of accuracy for the short frame durations that are typical in video. To convert to milliseconds, divide by 10000.

Note that retrieving the durations of individual frames is essential for proper timing when the frame rate is variable, as is often the case with animated GIF files.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_UINT msDuration;     /* Duration of frame in milliseconds */
nErrcount = IG_mult_current_frame_duration_get(hMult,
&duration);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_current_frame_image_get

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_current_frame_image_get(
    HIGMULT hMult,
    LPHIGEAR lphIGear
);

Arguments:

hMult
Multimedia instance handle
lphIGear
Image handle

Description:

This function retrieves the HIGEAR of the current frame's image. This image is owned by ImageGear. You can perform read-only operations such as display or save to a file, but do not attempt to free or alter the image. If you need to alter the image (resize it, for example), use IG_image_duplicate() to make a copy of the image, work with the copy, and free it with IG_image_delete() when finished.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Saves first frame as a 128-pixel-wide thumbnail */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
HIGEAR hIGear;          /* HIGEAR handle of image */
HIGEAR hIGearCopy;      /* HIGEAR handle of duplicate */
AT_DIMENSION w, h;      /* Width and height of image */
nErrcount = IG_mult_current_frame_reset(hMult);
nErrcount = IG_mult_current_frame_image_get(hMult, &hIGear);
nErrcount = IG_image_duplicate(hIGear, &hIGearCopy);
nErrcount = IG_image_dimensions_get(hIGearCopy, &w, &h, NULL);
nErrcount = IG_IP_resize(hIGearCopy, 128, (AT_DIMENSION)
((float) h / (float) w * 128), IG_INTERPOLATION_BICUBIC);
nErrcount = IG_save_file(hIGearCopy, "thumb.jpg", IG_SAVE_JPG);
nErrcount = IG_image_delete(hIGearCopy);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_current_frame_info_get

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_current_frame_info_get(
    HIGMULT hMult,
    AT_MODE infoID,
    LPAT_VOID lpInfo,
    LPAT_UINT lpInfoSize
);

Arguments:

hMult
Multimedia instance handle
infoID
ID of info to get
lpInfo
Pointer to buffer to store info in
lpInfoSize
Size of buffer pointed to by lpInfo

Description:

This function retrieves a specific piece of information about the current frame. You can specify the information to retrieve using the infoID parameter, whose value is a member of enumIGMultInfo defined in accucnst.h.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_current_frame_info_set

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_current_frame_info_set(
    HIGMULT hMult,
    AT_MODE infoID,
    LPAT_VOID lpInfo,
    LPAT_UINT lpInfoSize
);

Arguments:

hMult
Multimedia instance handle
infoID
ID of info to set
lpInfo
Pointer to buffer containing the info
lpInfoSize
Size of buffer pointed to by lpInfo

Description:

This function sets a specific piece of information about the current frame. Specify the information to retrieve using the infoID parameter, whose value is a member of enumIGMultInfo defined in accucnst.h.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_current_frame_is_valid

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_current_frame_is_valid(
    HIGMULT hMult,
    LPAT_BOOL lpbValid
);

Arguments:

hMult
Multimedia instance handle
lpbValid
Boolean that is set to TRUE if the current frame is valid

Description:

This function lets you tell whether or not the current frame is valid. You can use this function in a loop over all of the frames to determine when you have advanced beyond the last available frame.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
HIGEAR hIGear;          /* HIGEAR handle of image */
AT_BOOL bValid;         /* Is current frame valid? */
while (IG_mult_current_frame_is_valid(hMult, &bValid) ==
IGE_SUCCESS && bValid)
{
    nErrcount = IG_mult_current_frame_image_get(hMult, &hIGear);
    nErrcount = IG_mult_current_frame_advance(hMult);
}

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_current_frame_reset

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_current_frame_reset(HIGMULT hMult);

Arguments:

hMult
Multimedia instance handle

Description:

This function resets the current frame to the first frame. You can use it to seek to the beginning of a multimedia instance.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
nErrcount = IG_mult_current_frame_reset(hMult);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_current_frame_seek

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_current_frame_seek(
    HIGMULT hMult,
    AT_UINT frameNum
);

Arguments:

hMult
Multimedia instance handle
frameNum
Frame number to seek to (0 = first frame)

Description:

This function seeks to the given frame number in a multimedia instance.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Seek to last frame */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
AT_UINT numFrames;      /* Total number of frames */
nErrcount = IG_mult_duration_get(hMult, &numFrames, NULL);
nErrcount = IG_mult_current_frame_seek(hMult, numFrames - 1);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_current_frame_seek_time

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_current_frame_seek_time(
    HIGMULT hMult,
    AT_UINT msTime
);

Arguments:

hMult
Multimedia instance handle
msTime
Time to seek to in milliseonds

Description:

This function seeks to the given absolute time in milliseconds since the beginning of the multimedia instance. It locates the frame that would be visible at this time under normal speed playback conditions and makes this the current frame. Seeking to a time of 0 will seek to the beginning, 1000 will seek to one second after the beginning, and so on.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Grab frames at two second intervals */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_BOOL bValid;         /* Is the current frame valid? */
AT_UINT msTime = 0;     /* Timestamp used for seeking */
HIGEAR hIGear;          /* HIGEAR handle of image */
IG_mult_current_frame_reset(hMult);
while (IG_mult_current_frame_is_valid(hMult, &bValid) ==
IGE_SUCCESS && bValid)
{
    nErrcount = IG_mult_current_frame_image_get(hMult, &hIGear);
    msTime += 2000;
    nErrcount = IG_mult_current_frame_seek_time(hMult, msTime);
}

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_duration_get

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_duration_get(
    HIGMULT hMult,
    LPAT_UINT lpNumFrames,
    LPAT_UINT lpDuration
);

Arguments:

hMult
Multimedia instance handle
lpNumFrames
Number of frames
lpDuration
Duration of multimedia file in milliseconds

Description:

This function retrieves the duration of a multimedia instance as a number of frames and a duration in milliseconds. You can pass NULL for one of these arguments if you only need the other one. You can use this function to determine how many frames are in a multimedia instance and how long it would play for if played at normal speed.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_UINT numFrames;      /* Total number of frames in file */
AT_UINT msDuration;     /* Duration of file in milliseconds */
nErrcount = IG_mult_duration_get(hMult, &numFrames,
&msDuration);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_frame_duration_get

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_frame_duration_get(
    HIGMULT hMult,
    AT_UINT frameNum,
    LPAT_UINT lpDuration
);

Arguments:

hMult
Multimedia instance handle
frameNum
Frame number to get duration of (0 = first frame)
lpDuration
Frame duration (in 100ns units)

Description:

This function returns the duration of the given frame in 100 nanosecond units. This provides a reasonable level of accuracy for the short frame durations that are typical in video. To convert to milliseconds, divide by 10000.

Note that retrieving the durations of individual frames is essential for proper timing when the frame rate is variable, as is often the case with animated GIF files.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Retrieve duration of first frame */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_UINT duration;       /* Duration of frame in 100ns units */
nErrcount = IG_mult_frame_duration_get(hMult, 0, &duration);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_frame_image_get

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_frame_image_get(
    HIGMULT hMult,
    AT_UINT frameNum,
    LPHIGEAR lphIGear
);

Arguments:

hMult
Multimedia instance handle
frameNum
Frame number to get image for (0 = first frame)
lphIGear
Image handle

Description:

This function retrieves the HIGEAR of the given frame's image. This image is owned by ImageGear. You can perform read-only operations such as display or save to a file, but do not attempt to free or alter the image. If you need to alter the image (resize it, for example), use IG_image_duplicate() to make a copy of the image, work with the copy, and free it with IG_image_delete() when finished.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Saves first frame as a 128-pixel-wide thumbnail */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
HIGEAR hIGear;          /* HIGEAR handle of image */
HIGEAR hIGearCopy;      /* HIGEAR handle of duplicate */
AT_DIMENSION w, h;      /* Width and height of image */
nErrcount = IG_mult_current_frame_reset(hMult);
nErrcount = IG_mult_current_frame_image_get(hMult, &hIGear);
nErrcount = IG_image_duplicate(hIGear, &hIGearCopy);
nErrcount = IG_image_dimensions_get(hIGearCopy, &w, &h, NULL);
nErrcount = IG_IP_resize(hIGearCopy, 128, (AT_DIMENSION)
((float) h / (float) w * 128), IG_INTERPOLATION_BICUBIC);
nErrcount = IG_save_file(hIGearCopy, "thumb.jpg", IG_SAVE_JPG);
nErrcount = IG_image_delete(hIGearCopy);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_frame_info_get

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_frame_info_get(
    HIGMULT hMult,
    AT_UINT frameNum,
    AT_MODE infoID,
    LPAT_VOID lpInfo,
    LPAT_UINT lpInfoSize
);

Arguments:

hMult
Multimedia instance handle
frameNum
Frame number to get info for (0 = first frame)
infoID
ID of info to get
lpInfo
Pointer to buffer to store info in
lpInfoSize
Size of buffer pointed to by lpInfo

Description:

This function retrieves a specific piece of information about the current frame. You can specify the information to retrieve using the infoID parameter, whose value is a member of enumIGMultInfo defined in accucnst.h.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_frame_info_set

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_frame_info_set(
    HIGMULT hMult,
    AT_UINT frameNum,
    AT_MODE infoID,
    LPAT_VOID lpInfo,
    LPAT_UINT lpInfoSize
);

Arguments:

hMult
Multimedia instance handle
frameNum
Frame number to set info for
infoID
ID of info to set
lpInfo
Pointer to buffer containing info
lpInfoSize
Size of buffer pointed to by lpInfo

Description:

This function sets a specific piece of information about the current frame. Specify the information to retrieve using the infoID parameter, whose value is a member of enumIGMultInfo defined in accucnst.h.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_frame_num_from_time_get

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_frame_num_from_time_get(
    HIGMULT hMult,
    AT_UINT msTime,
    LPAT_UINT lpFrameNum
);

Arguments:

hMult
Multimedia instance handle
msTime
Time in milliseconds (since the beginning)
lpFrameNum
Frame number at given time

Description:

This function returns the number of the frame that would be visible at the given time under normal speed playback conditions.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Finds the # of the frame at 1 second from the beginning */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_UINT frameNum;       /* Returned frame number */
nErrcount = IG_mult_frame_num_from_time_get(hMult, 1000,
&frameNum);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_has_audio

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_has_audio(
    HIGMULT hMult,
    LPAT_BOOL lpbHasAudio
);

Arguments:

hMult
Multimedia instance handle
lpbHasAudio
Pointer to Boolean set to TRUE if multimedia instance has audio

Description:

This function fills a Boolean variable indicating whether or not a multimedia instance has audio data available.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_BOOL bHasAudio;      /* Is audio data available? */
nErrcount = IG_mult_has_audio(hMult, &bHasAudio);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_has_video

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_has_video(
    HIGMULT hMult,
    LPAT_BOOL lpbHasVideo
);

Arguments:

hMult
Multimedia instance handle
lpbHasVideo
Pointer to Boolean set to TRUE if multimedia instance has video

Description:

This function fills a Boolean variable indicating whether or not a multimedia instance has video data available.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_BOOL bHasVideo;      /* Is video data available? */
nErrcount = IG_mult_has_video(hMult, &bHasVideo);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_info_get

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_info_get(
    HIGMULT hMult,
    AT_MODE infoID,
    LPAT_VOID lpInfo,
    LPAT_UINT lpInfoSize
);

Arguments:

hMult
Multimedia instance handle
infoID
ID of info to get
lpInfo
Pointer to buffer to store info in
lpInfoSize
Size of buffer pointed to by lpInfo

Description:

This function retrieves a piece of information for a multimedia instance as a whole. You can specify the information to retrieve using the infoID parameter, whose value is a member of enumIGMultInfo defined in accucnst.h.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Retrieve minimum frame delay setting for animated GIF */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_UINT msDelay;        /* Minimum frame delay (milliseconds) */
nErrcount = IG_mult_info_get(hMult, IG_MULT_INFO_GIF_MIN_DELAY,
&msDelay, sizeof(msDelay));

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_info_set

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_info_set(
    HIGMULT hMult,
    AT_MODE infoID,
    LPAT_VOID lpInfo,
    LPAT_UINT lpInfoSize
);

Arguments:

hMult
Multimedia instance handle
infoID
ID of info to set
lpInfo
Pointer to buffer containing info
lpInfoSize
Size of buffer pointed to by lpInfo

Description:

This function sets a piece of information for a multimedia instance as a whole. You can specify the information to retrieve using the infoID parameter, whose value is a member of enumIGMultInfo defined in accucnst.h.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Set minimum frame delay setting for animated GIF to 100ms */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
AT_UINT msDelay = 100;  /* Minimum frame delay (milliseconds) */
nErrcount = IG_mult_info_set(hMult, IG_MULT_INFO_GIF_MIN_DELAY,
&msDelay, sizeof(msDelay));

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_open_FD

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_open_FD(
    AT_INT fd,
    LPHIGMULT lphMult
);

Arguments:

fd
File descriptor
lphMult
Handle to multimedia instance

Description:

This function creates a multimedia instance from a file descriptor. The file descriptor and contents must remain accessible until the multimedia instance is closed.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Get a multimedia file's duration using a file descriptor */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
LPCSTR szFile;          /* Name of file to open */
HANDLE fd;              /* File descriptor */
AT_UINT numFrames;      /* Total number of frames in file */
AT_UINT duration;       /* Duration of file in milliseconds */
fd = CreateFile(szFile, GENERIC_READ, FILE_SHARE_READ, NULL,
OPEN_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
nErrcount = IG_mult_open_FD(fd, &hMult);
nErrcount = IG_mult_duration_get(hMult, &numFrames, &duration);
nErrcount = IG_mult_close(hMult);
CloseHandle(fd);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_open_FD_format

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_open_FD_format(
    AT_INT fd,
    AT_MODE format,
    LPHIGMULT lphMult
);

Arguments:

fd
File descriptor
format
Format of file (can be IG_FORMAT_UNKNOWN)
lphMult
Handle to multimedia instance

Description:

This function creates a multimedia instance from a file descriptor using only the specified format. The file descriptor and contents must remain accessible until the multimedia instance is closed. Specifying the format lets you bypass the automatic file type identification for situations in which you know the format of the file.

See the multimedia API overview for a list of currently supported formats.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Open an animated GIF file from a file descriptor */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
LPCSTR szFile;          /* Name of file to open */
HANDLE fd;              /* File descriptor */
AT_UINT numFrames;      /* Total number of frames in file */
AT_UINT duration;       /* Duration of file in milliseconds */
fd = CreateFile(szFile, GENERIC_READ, FILE_SHARE_READ, NULL,
OPEN_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
nErrcount = IG_mult_open_FD_format(fd, IG_FORMAT_GIF, &hMult);
nErrcount = IG_mult_duration_get(hMult, &numFrames, &duration);
nErrcount = IG_mult_close(hMult);
CloseHandle(fd);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_open_file

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_open_file(
    LPSTR szFilename,
    LPHIGMULT lphMult
);

Arguments:

szFilename
Filename of multimedia to open
lphMult
Handle to multimedia instance

Description:

This function creates a multimedia instance from a filename. The file must remain accessible until the multimedia instance is closed.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Get a multimedia file's duration using a filename */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
LPCSTR szFile;          /* Name of file to open */
AT_UINT numFrames;      /* Total number of frames in file */
AT_UINT duration;       /* Duration of file in milliseconds */
nErrcount = IG_mult_open_file(szFile, &hMult);
nErrcount = IG_mult_duration_get(hMult, &numFrames, &duration);
nErrcount = IG_mult_close(hMult);

Sample: MediaPlayer

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_open_file_format

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_open_file_format(
    LPSTR szFilename,
    AT_MODE format,
    LPHIGMULT lphMult
);

Arguments:

szFilename
Filename of multimedia to open
format
Format of file (can be IG_FORMAT_UNKNOWN)
lphMult
Handle to multimedia instance

Description:

This function creates a multimedia instance from a filename using only the specified format. The file must remain accessible until the multimedia instance is closed. Specifying the format lets you bypass the automatic file type identification for situations in which you know the format of the file.

See the multimedia API overview for a list of currently supported formats.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Get an animated GIF file's duration using a filename */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
LPCSTR szFile;          /* Name of file to open */
AT_UINT numFrames;      /* Total number of frames in file */
AT_UINT duration;       /* Duration of file in milliseconds */
nErrcount = IG_mult_open_file_format(szFile, IG_FORMAT_GIF,
&hMult);
nErrcount = IG_mult_duration_get(hMult, &numFrames, &duration);
nErrcount = IG_mult_close(hMult);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_open_mem

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_open_mem(
    LPAT_VOID lpMem,
    AT_UINT memLen,
    LPHIGMULT lphMult
);

Arguments:

lpMem
Pointer to data in memory to open
memLen
Length of data in memory in bytes
lphMult
Handle to multimedia instance

Description:

This function creates a multimedia instance from memory. The memory must contain a complete multimedia file and remain accessible until the multimedia instance is closed.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Get a multimedia file's duration using a memory buffer */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
LPAT_VOID lpMem;        /* Memory buffer with multimedia data */
AT_UINT memLen;         /* Length of data in memory buffer */
AT_UINT numFrames;      /* Total number of frames in file */
AT_UINT duration;       /* Duration of file in milliseconds */
nErrcount = IG_mult_open_mem(lpMem, memLen, &hMult);
nErrcount = IG_mult_duration_get(hMult, &numFrames, &duration);
nErrcount = IG_mult_close(hMult);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_mult_open_mem_format

Group: Multimedia

Declaration:

AT_ERRCOUNT ACCUAPI IG_mult_open_mem_format(
    LPAT_VOID lpMem,
    AT_UINT memLen,
    AT_MODE format,
    LPHIGMULT lphMult
);

Arguments:

lpMem
Pointer to data in memory to open
memLen
Length of data in memory in bytes
format
Format of file (can be IG_FORMAT_UNKNOWN)
lphMult
Handle to multimedia instance

Description:

This function creates a multimedia instance from memory using only the specified format. The memory must contain a complete multimedia file and remain accessible until the multimedia instance is closed. Specifying the format lets you bypass the automatic file type identification for situations in which you know the format of the file.

See the multimedia API overview for a list of currently supported formats.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* Get an animated GIF file's duration using a memory buffer */
AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGMULT hMult;          /* Multimedia instance handle */
LPAT_VOID lpMem;        /* Memory buffer with multimedia data */
AT_UINT memLen;         /* Length of data in memory buffer */
AT_UINT numFrames;      /* Total number of frames in file */
AT_UINT duration;       /* Duration of file in milliseconds */
nErrcount = IG_mult_open_mem_format(lpMem, memLen,
IG_FORMAT_GIF, &hMult);
nErrcount = IG_mult_duration_get(hMult, &numFrames, &duration);
nErrcount = IG_mult_close(hMult);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_page_count_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_page_count_get (
    const LPSTR lpszFileName,
    LPUINT lpPageCount
);

Arguments:

lpszFileName
Name of file
lpPageCount
Far pointer to a UINT variable to receive page count

Description:

This function obtains the number of pages in a multi-page file.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

UINT nPages;     /* Will receive number of pages   */
AT_ERRCOUNT nErrcount;   /* Count of returned errors  */
nErrcount = IG_page_count_get ( "picture.tif", &nPages );

Sample: ASCII, DISPLAY, GUIWIN, MEMIO, MFC, Vector, FILTER, MULTIMED

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_page_count_get_FD

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_page_count_get_FD (
    AT_INT fd,
    LONG lOffset,
    LPUINT lpPageCount
);

Arguments:

fd
File Descriptor handle
lOffset
Offset in file at which file image begins
lpPageCount
Far pointer to a UINT variable to receive page count

Description:

This function obtains the number of pages in a multi-page. Call this function when the file is already opened and you have its File Descriptor handle (fd).

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

INT fd;         /* File Descriptor handle  */
UINT nPages;     /* Will receive number of pages */
AT_ERRCOUNT nErrcount;  /* Count of returned errors  */
nErrcount = IG_page_count_get_FD ( fd, 0, &nPages );

Sample: ASCII, Vector, FILTER,

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_page_count_get_mem

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_page_count_get_mem (
    LPVOID lpImage,
    AT_UINT nImageSize,
    LPUINT lpPageCount
);

Arguments:

lpImage
Far pointer to start of file image in memory
nImageSize
Size of image in memory.
lpPageCount
Far pointer to a UINT variable to receive page count

Description:

This function obtains the number of pages in a multi-page file, when the file image is in memory. See also functions IG_page_count_get_FD () and IG_page_count_get ().

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

char FAR * lpMemImage;  /* Pointer to in-memory file  */
AT_UINT nImageSize;      /* Size of image in memory */
UINT nPages;      /* Will receive number of pages    */
AT_ERRCOUNT nErrcount;   /* Count of returned errors      */
nErrcount = IG_page_count_get_mem ( lpMemImage, nImageSize,
&nPages );

Sample: MEMIO

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_palette_entry_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_palette_entry_get (
    HIGEAR hIGear,
    LPAT_RGB lpRGBEntry,
    UINT nIndex
);

Arguments:

hIGear
HIGEAR handle of image
lpRGBEntry
Far pointer to an AT_RGB struct to receive the three color values of the palette entry. (Note that this is not an AT_RGBQUAD struct. Also note that the order of the bytes is Blue, Green, Red in an AT_RGB struct.
nIndex
Which palette entry to get, 0 to 255

Description:

This function obtains from image hIGear's DIB palette, the palette entry indicated by nIndex.

Bits Per Pixel: 1, 4, 8-bit gray level, 8i

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;           /* HIGEAR handle of image    */
AT_RGB rgbPaletteColor;  /* Will hold returned color   */
AT_ERRCOUNT nErrcount;        /* Returned count of errors on
stack*/
/* Get palette entry 255: */
nErrcount = IG_palette_entry_get ( hIGear, rgbPaletteColor, 255
);

Sample: IMG_PROC, PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_palette_entry_set

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_palette_entry_set (
    HIGEAR hIGear,
    const LPAT_RGB lpRGBEntry,
    UINT nIndex
);

Arguments:

hIGear
HIGEAR handle of image
lpRGBEntry
Far pointer to an AT_RGB struct containing the three color values to be set into the palette entry. Note that this is not an AT_RGBQUAD struct. Also note that the order is Blue, Green, Red in an AT_RGB struct.
nIndex
Which palette entry to set, 0 to 255

Description:

This function sets a single palette entry in image hIGear's DIB palette.

Bits Per Pixel: 1, 4, 8-bit gray level, 8i

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;              /* HIGEAR handle of image  */
AT_RGB rgbPaletteColor;     /* Will hold returned color */
AT_ERRCOUNT	 Errcount;         /* Returned count of errors
onstack */
/* Set palette entry 255 to a medium-bright yellow, intensity
175:  */
rgbPaletteColor.b = 0;     /* There's no blue in yellow */
rgbPaletteColor.r  =  rgbPaletteColor.g  =  175;
nErrcount = IG_palette_entry_set ( hIGear, &rgbPaletteColor, 255
);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_palette_get

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_palette_get (
    HIGEAR hIGear,
    LPAT_RGBQUAD lpPalette
);

Arguments:

hIGear
HIGEAR handle of image
lpPalette
Far pointer to the first of an array of AT_RGBQUAD structs sufficient to hold the entire palette from the image's DIB.

Description:

This function obtains the referenced image's DIB palette, storing it in your array of AT_RGBQUAD structs pointed to by lpPalette. The array must be large enough to hold the palette. For example, if an 8-bit image, lpPalette must point to the start of an array of 256 AT_RGBQUAD structs, therefore to an array of at least 256 x 4 = 1024 bytes. If the image is 24-bit, no error is set but no palette is returned.

NOTE: See also function IG_palette_set()function.

Bits Per Pixel: 1, 4, 8

NOTE: To obtain an image's logical palette (the palette after mapping through the display LUTs, or for a 24-bit image the palette that would be used for displaying to an 8-bit device), use function IG_dspl_palette_create().

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;        /* HIGEAR handle of image     */
AT_ERRCOUNT nErrcount;      /* Returned count of errors on stack
*/
AT_RGBQUAD rgbqPalette[256];  /* Array of AT_RGBQUAD structs
*/
nErrcount = IG_palette_get ( hIGear, rgbqPalette );

Sample: PALEDT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_palette_load

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_palette_load (
    const LPSTR lpszFileName,
    LPAT_RGBQUAD lpPalette,
    LPUINT lpNumEntries,
    BOOL bBGR_Order,
    LPAT_MODE lpFileType
);

Arguments:

lpszFileName
Name of file containing saved palette to load
lpPalette
Far pointer to array of AT_RGBQUAD structs to load into (But see the parameter bBGR_Order, below)
lpNumEntries
Far pointer to UINT variable to receive number of palette entries loaded (size of palette)
bBGR_Order
TRUE = store as AT_RGB structs (that is, Blue-Green-Red), instead of AT_RGBQUAD structs (Blue-Green-Red-Unused)
This switch has no affect when reading ImageGear's text format. It loads this information as if writing to AT_RGBQUAD.
lpFileType
An IG_PALETTE_FORMAT_ constant specifying the format of the file. The constants are listed in file accucnst.h.

Description:

This function loads a palette that was saved using IG_palette_save ()function.

Bits Per Pixel: 1, 4, 8-bit gray level, 8i

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

AT_RGBQUAD rgbqPalette[256];     /* Will hold the palette loaded
*/
UINT nEntries;           /* Holds number of entries in palette*/
AT_MODE nPaletteFileType;   /* Will receive IG_PALETTE_...
constant*/
AT_ERRCOUNT1 nErrcount;           /* Returned count of errors
*/
nErrcount = IG_palette_load ( "Palfile.pal", &rgbqPalette[0],
&nEntries, TRUE, &nPaletteFileType );

Sample: PALEDT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_palette_save

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_palette_save (
    const LPSTR lpszFileName,
    LPAT_RGBQUAD lpPalette,
    UINT nNumEntries,
    AT_MODE nFileType
);

Arguments:

lpszFileName
Name of file to save palette to.
lpPalette
Far pointer to array of AT_RGBQUAD structs constituting palette to save.
nNumEntries
Number of entries in palette.
nFileType
IG_PALETTE_FORMAT_ constant specifying format in which to save palette. The constants are listed in accucnst.h.

Description:

This function saves a palette to a file. Argument nFileType lets you select the format in which to save the palette. If you save the palette using IG_PALETTE_FORMAT_TEXT, its format will be as shown for the following palette of a 1-bit black-and-white image:

AccuSoft Palette File ver 7.0.9
0 0 0 0
1 255 255 255

The first line identifies the version of ImageGear that created this Palette text file. Then each succeeding line gives the entry number, followed by the Red, Green, and Blue color intensities, respectively, for that palette color.

Bits Per Pixel: 1, 4, 8

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;      /* Handle of image whose palette to save  */
LPAT_RGBQUAD lpPalettePntr; /* Will hold address of the DIB
palette  */
UINT nEntries;    /* Will hold number of entries in palette  */
/* Obtain address of DIB palette and its number of entries );
IG_image_DIB_palette_pntr_get ( hIGear, &lpPalettePntr,
&nEntries );
/* Save to a file, saving only 3 bytes per entry, in order B-G-
R: */
nErrcount = IG_palette_save ( "Savedpal.pal", lpPalettePntr,
nEntries, IG_PALETTE_FORMAT_RAW_BGR );

Sample: PALEDT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_palette_set

Group: Image Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_palette_set (
    HIGEAR hIGear,
    const LPAT_RGBQUAD lpPalette
);

Arguments:

HIGEAR
HIGEAR handle of image
LpPalette
Far pointer to the first of an array of AT_RGBQUAD structs containing the palette you wish to load into the DIB, as the image's new DIB palette

Description:

This function loads the palette pointed to by lpPalette into the DIB, replacing the prior palette that was present. Your palette pointed to by lpPalette must be in the form of AT_RGBQUAD structs: 4 bytes per entry, ordered Blue-Green-Red-Unused (0). The number of consecutive AT_RGBQUAD structs you need is determined by the number of Bits Per Pixel in the image. For example, for an 8 bit image, you would need an array of 256 AT_RGBQUAD structs.

If the image is 24 bit, this function will set an error and return.

NOTE: See also function IG_palette_set().

Bits Per Pixel: 1, 4, 8

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;        /* HIGEAR handle of image  */
AT_ERRCOUNT  nErrcount;     /* Returned count of errors on stack
*/
AT_RGBQUAD rgbqPalette[256];   /* Array of AT_RGBQUAD structs
*/
INT pix;              /* Loop index, = pixel value  */
/* Create a grayscale palette, and set it into image hIGear's
DIB:  */
for ( pix = 0;  pix <= 255;  pix++ )
    {
    rgbqPalette[pix].rgbBlue  =  pix;
    rgbqPalette[pix].rgbGreen =  pix;
    rgbqPalette[pix].rgbRed   =  pix;
    rgbqPalette[pix].rgbReserved  =  0;
    }
nErrcount = IG_palette_set ( hIGear, rgbqPalette );

Sample: PALEDT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_pixel_bits_per_channel_get

Group: Pixel Access

Declaration:

AT_DEPTH ACCUAPI IG_pixel_bits_per_channel_get(HIGPIXEL
hPixel);

Arguments:

hPixel
Handle of pixel object

Description:

This function returns the number of bits allocated for storing pixel data for a single channel in the given pixel object. It will be 8, 16, or 32.

Bits Per Pixel: All

Return Value:

Return value is the same for all channels and represents the maximal bit depth aligned to all bytes.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGPIXEL hPix;          /* Handle of pixel */
AT_DEPTH bitsPerChan;   /* Number of bits per channel */
nErrcount = IG_load_file("test.jpg", &hImage);
nErrcount = IG_DIB_pix_get(hImage, 0, 0, &hPix);
bitsPerChan = IG_pixel_bits_per_channel_get(hPix);
IG_pixel_delete(hPix);
IG_image_delete(hImage);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_pixel_channel_count_get

Group: Pixel Access

Declaration:

AT_INT ACCUAPI IG_pixel_channel_count_get(HIGPIXEL hPixel );

Arguments:

hPixel
Handle of pixel object

Description:

This function returns the number of channels that are available to store values in the given pixel object.

Bits Per Pixel: All

Return Value:

Number of channels in pixel object.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGPIXEL hPix;          /* Handle of pixel */
AT_DEPTH nChannels;     /* Number of channels */
nErrcount = IG_load_file("test.jpg", &hImage);
nErrcount = IG_DIB_pix_get(hImage, 0, 0, &hPix);
nChannels = IG_pixel_channel_count_get(hPix);
IG_pixel_delete(hPix);
IG_image_delete(hImage);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_pixel_create

Group: Pixel Access

Declaration:

HIGPIXEL ACCUAPI IG_pixel_create(
    AT_INT channelCount,
    AT_DEPTH bitsPerChannel
);

Arguments:

channelCount
Number of channels to allocate
bitsPerChannel
Bits per channel to allocate

Description:

This function creates a new pixel object based on specified attributes. The number of bits per channel is the amount to allocate, and it must be 8, 16, or 32.

Bits Per Pixel: All

Return Value:

Handle of new pixel object.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGPIXEL hPix;          /* Handle of pixel */
AT_INT ChannelCount;    /* Number of channels in image */
AT_INT BitsPerChannel;  /* Bits per channel in image */
nErrcount = IG_load_file("test.jpg", &hImage);
nErrcount = IG_image_channel_count_get(hImage, &ChannelCount);
nErrcount = IG_image_bits_per_channel_get(hImage,
&BitsPerChannel);
hPix = IG_pixel_create(ChannelCount, BitsPerChannel);
/* Pixel is created using same attributes as image */
IG_pixel_delete(hPix);
IG_image_delete(hImage);

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_pixel_data_pointer_get

Group: Pixel Access

Declaration:

LPAT_VOID ACCUAPI IG_pixel_data_pointer_get(HIGPIXEL hPixel);

Arguments:

hPixel
Handle of pixel object

Description:

This function returns a pointer to the pixel data stored for a pixel. The number of accessible bytes can be calculated by multiplying the number of bits allocated per channel (8, 16, or 32) by the number of channels allocated, then dividing by 8.

Bits Per Pixel: All

Return Value:

N/A

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGPIXEL hPix;          /* Handle of pixel */
AT_INT ChannelCount;    /* Number of channels in image */
AT_INT BitsPerChannel;  /* Bits per channel in image */
LPAT_VOID lpPixData;    /* Pixel data */
nErrcount = IG_load_file("test.jpg", &hImage);
nErrcount = IG_image_channel_count_get(hImage, &ChannelCount);
nErrcount = IG_image_bits_per_channel_get(hImage,
&BitsPerChannel);
/* Get the first pixel of an image */
nErrcount = IG_DIB_pix_get(hImage, 0, 0, &hPix);
/* Set the bits in all of its channels to 1's */
lpPixData = IG_pixel_data_pointer_get(hPix);
memset(lpPixData, 255, ChannelCount * (BitsPerChannel / 8));
/* Write the modified pixel data back to the image */
IG_DIB_pix_set(hImage, 0, 0, hPix);
IG_pixel_delete(hPix);
IG_image_delete(hImage);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_pixel_delete

Group: Pixel Access

Declaration:

AT_VOID ACCUAPI IG_pixel_delete(HIGPIXEL hPixel);

Arguments:

hPixel
Handle of pixel object

Description:

This function releases the allocated resources for a pixel object.

Bits Per Pixel: All

Return Value:

N/A

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGPIXEL hPix;          /* Handle of pixel */
AT_DIMENSION w, h;      /* Width and height of image */
AT_INT nChannels;       /* Number of channels in image */
AT_DIMENSION x, y;      /* Used to loop over image */
AT_INT c;               /* Used to loop over channels */
AT_INT nDepth;          /* Channel depth */
AT_UINT inverted;       /* Inverted channel value */
/* Invert colors in upper-left quadrant of image */
nErrcount = IG_load_file("test.jpg", &hImage);
nErrcount = IG_image_channel_count_get(hImage, &nChannels);
nErrcount = IG_image_dimensions_get(hImage, &w, &h, NULL);
for (y = 0; y < h / 2; y++)
    for (x = 0; x < w / 2; x++)
    {
        nErrcount = IG_DIB_pix_get(hImage, x, y, &hPix);
        for (c = 0; c < nChannels; c++)
        {
            IG_image_channel_depth_get(hImage, c, &nDepth);
            nDepth = (1 << nDepth) - 1;
            inverted = nDepth - IG_pixel_value_get(hPix, c);
            IG_pixel_value_set(hPix, c, inverted);
        }
        nErrcount = IG_DIB_pix_set(hImage, x, y, hPix);
        IG_pixel_delete(hPix);
    }
nErrcount = IG_save_file(hImage, OUTPUT_FILENAME,
    IG_SAVE_BMP_UNCOMP);
IG_image_delete(hImage);

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_pixel_value_get

Group: Pixel Access

Declaration:

AT_UINT ACCUAPI IG_pixel_value_get(
    HIGPIXEL hPixel,
    AT_INT channel
);

Arguments:

hPixel
Handle of pixel object
channel
Channel index to get value from

Description:

This function returns the value of the requested channel. The range of possible values depends on the bit depth of the channel.

Bits Per Pixel: All

Return Value:

Channel value.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGPIXEL hPix;          /* Handle of pixel */
AT_DIMENSION w, h;      /* Width and height of image */
AT_INT nChannels;       /* Number of channels in image */
AT_DIMENSION x, y;      /* Used to loop over image */
AT_INT c;               /* Used to loop over channels */
AT_INT nDepth;          /* Channel depth */
AT_UINT inverted;       /* Inverted channel value */
/* Invert colors in upper-left quadrant of image */
nErrcount = IG_load_file("test.jpg", &hImage);
nErrcount = IG_image_channel_count_get(hImage, &nChannels);
nErrcount = IG_image_dimensions_get(hImage, &w, &h, NULL);
for (y = 0; y < h / 2; y++)
    for (x = 0; x < w / 2; x++)
    {
        nErrcount = IG_DIB_pix_get(hImage, x, y, &hPix);
        for (c = 0; c < nChannels; c++)
        {
            IG_image_channel_depth_get(hImage, c, &nDepth);
            nDepth = (1 << nDepth) - 1;
            inverted = nDepth - IG_pixel_value_get(hPix, c);
            IG_pixel_value_set(hPix, c, inverted);
        }
        nErrcount = IG_DIB_pix_set(hImage, x, y, hPix);
        IG_pixel_delete(hPix);
    }
nErrcount = IG_save_file(hImage, OUTPUT_FILENAME,
    IG_SAVE_BMP_UNCOMP);
IG_image_delete(hImage);

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_pixel_value_set

Group: Pixel Access

Declaration:

AT_VOID ACCUAPI IG_pixel_value_set(
    HIGPIXEL hPixel,
    AT_INT channel,
    AT_UINT value
);

Arguments:

hPixel
Handle of pixel object
channel
Channel index to set value for
value
Value to set (range depends on channel bit depth)

Description:

This function updates the value for the specified channel. The range of possible values depends on the bit depth of the channel.

Bits Per Pixel: All

Return Value:

N/A

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HIGEAR hImage;          /* Handle of image */
HIGPIXEL hPix;          /* Handle of pixel */
AT_DIMENSION w, h;      /* Width and height of image */
AT_INT nChannels;       /* Number of channels in image */
AT_DIMENSION x, y;      /* Used to loop over image */
AT_INT c;               /* Used to loop over channels */
AT_INT nDepth;          /* Channel depth */
AT_UINT inverted;       /* Inverted channel value */
/* Invert colors in upper-left quadrant of image */
nErrcount = IG_load_file("test.jpg", &hImage);
nErrcount = IG_image_channel_count_get(hImage, &nChannels);
nErrcount = IG_image_dimensions_get(hImage, &w, &h, NULL);
for (y = 0; y < h / 2; y++)
    for (x = 0; x < w / 2; x++)
    {
        nErrcount = IG_DIB_pix_get(hImage, x, y, &hPix);
        for (c = 0; c < nChannels; c++)
        {
            IG_image_channel_depth_get(hImage, c, &nDepth);
            nDepth = (1 << nDepth) - 1;
            inverted = nDepth - IG_pixel_value_get(hPix, c);
            IG_pixel_value_set(hPix, c, inverted);
        }
        nErrcount = IG_DIB_pix_set(hImage, x, y, hPix);
        IG_pixel_delete(hPix);
    }
nErrcount = IG_save_file(hImage, OUTPUT_FILENAME,
    IG_SAVE_BMP_UNCOMP);
IG_image_delete(hImage);

Sample: PIX_ACC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_runs_row_get

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_runs_row_get(
    HIGEAR hIGear,
    AT_PIXPOS yPos,
    *AT_RUN wRunCount,
    LPAT_RUN *lpRunEnd
);

Arguments:

hIGear
HIGEAR handle of the image to get the run ends information from.
yPos
Y-Offset into the image
wRunCount
The number of runs in the lpRunEnd buffer
lpRunEnd
Returns a pointer to the run-end line specified by yPos.

Description:

This function returns a pointer to the run-end line specified by the yPos parameter. (Run-end encoding is used on 1-bit images only.) wRunCount returns the number of runs that lpRunEnd points to. The read-only data in the pointer returned should not be changed because it may corrupt the image.

NOTE: To safely change the data, use IG_runs_row_set(). Developers should be cautious when using the IG_runs_row_set() function because it is possible to corrupt the image by supplying invalid run-end data.

This function will set an error, if the image specified by hIGear is not in run-ends format or if the yPos parameter is greater than the height of the image.

The format of the run-end encoded data is as follows: Each line in the image starts with a value of type AT_RUN which stores the number of AT_RUN values used to hold the line. This value is equal to the number of runs in the line plus one (for the size value). The rest of the line consists of run ends of type AT_RUN. A run end specifies the first pixel position beyond the run of color. The run ends alternate between white and black, and start with white. The line ends with at least three run ends containing a value equal to the image's width. A 2500 pixel source line with black pixels in positions 0, 7, 23, and 30, would be encoded as runs: 10, 0, 1, 7, 8, 23, 31, 2500, 2500, 2500 (with 10 being the number of AT_RUN values used to store the encoded line.)

This function returns a pointer to the second AT_RUN value of the line in the lpRunEnd parameter, and returns the number of runs in wRunCount. The IG_runs_row_set () function copies the data in the lpRunEnd parameter to the second AT_RUN value of the line. The first AT_RUN value is set to the wRunCount parameter.

Bits Per Pixel: 1

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

AT_ERRCOUNT  	nErrcount;
HIGEAR 	hIGear;
AT_PIXPOS 	y;
WORD 	wRunCount;
LPWORD 	lpRunEnd, lpRunBuffer;
AT_DIMENSION  	nWidth, nHeight;
IG_image_dimensions_get(hIGear, &nWidth, &nHeight, NULL);
/* calculate the maximum size of a raster line */
lpRunBuffer = (LPWORD)malloc((nWidth + 3) * sizeof(WORD));
/* invert the image */
for (y = 0; y < nHeight; y++)
{
    IG_runs_row_get(hIGear, y, &wRunCount, &lpRunEnd);
    if (lpRunEnd[0] != 0)
    {
        lpRunBuffer[0] = 0;
        for (wRunCount = 0; lpRunEnd[wRunCount] !=
            nWidth; wRunCount++)
            lpRunBuffer[wRunCount + 1] = lpRunEnd[wRunCount];
        wRunCount++;
        lpRunBuffer[wRunCount++] = (WORD)nWidth;
        lpRunBuffer[wRunCount++] = (WORD)nWidth;
        lpRunBuffer[wRunCount++] = (WORD)nWidth;
    }
    else
    {
        memcpy(lpRunBuffer, lpRunEnd + 1, (wRunCount - 1) *
sizeof(WORD));
        lpRunBuffer[wRunCount - 1] = nWidth;
    }
    IG_runs_row_set(hIGear, y, wRunCount, lpRunBuffer);
}
InvalidateRect(hWnd, NULL, FALSE);
free(lpRunBuffer);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_runs_row_set

Group: Pixel Access

Declaration:

AT_ERRCOUNT ACCUAPI IG_runs_row_set(
    HIGEAR hIGear,
    AT_PIXPOS yPos,
    AT_RUN wRunCount,
    LPCAT_RUN lpRunEnd
);

Arguments:

hIGear
HIGEAR handle of the image containing the raster line you would like to modify.
yPos
Y-Offset into the image
wRunCount
The number of runs in the lpRunEnd buffer.
lpRunEnd
The Run- end pointer to copy into the image.

Description:

This function sets the run-end data of the line specified by the yPos parameter. The wRunCount parameter should be set to the number of runs contained in the lpRunEnd buffer. Run-end encoding is used on 1-bit images only. This function is faster than using IG_DIB_raster_set () for a 1-bit image. This function copies the data in the lpRunEnd parameter to the second AT_RUN value of the line. The first AT_RUN value is set to the wRunCount parameter.

NOTE: Developers should be cautious when using this function because it is possible to corrupt the image by supplying invalid run-end data.

Both of these functions will set an error if the image specified by hIGear is not in run-ends format or if the yPos parameter is greater than the height of the image.

The format of the run-end encoded data is as follows: Each line in the image starts with a value of type AT_RUN which stores the number of AT_RUN values used to hold the line. This value is equal to the number of runs in the line plus one (for the size value). The rest of the line consists of run ends of type AT_RUN. A run end specifies the first pixel position beyond the run of color. The run ends alternate between white and black, and start with white. The line ends with at least three run ends containing a value equal to the image's width. A 2500 pixel source line with black pixels in positions 0, 7, 23, and 30, would be encoded as runs: 10, 0, 1, 7, 8, 23, 31, 2500, 2500, 2500 (with 10 being the number of AT_RUN values used to store the encoded line.)

NOTE: See also IG_runs_row_get() function.

Bits Per Pixel: 1

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

See the example under IG_runs_row_get ().

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_save_FD

Group: Image Saving

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_FD (
    HIGEAR hIGear,
    AT_INT fd,
    UINT nPageNum,
    UINT nReserved,
    AT_LMODE lFormatType
);

Arguments:

hIGear
HIGEAR handle of image to save
fd
File Descriptor handle of (already opened) file to save to
nPageNum
If saving to a multi-page file, this tells the page number to insert this page as. (Remember that the first page in a multi-page file is page 1, not 0.)
nReserved
Reserved, should always be set = 0 for now.
lFormatType
A constant such as IG_SAVE_TIF_UNCOMP or IG_SAVE_JPG, telling format to save in, and compression scheme if applicable. All AT_LMODE IG_SAVE_... constants are defined in accucnst.h.

Description:

This function saves the image rectangle of HIGEAR image hIGear to a file that has already been opened, and for which your application has the File Descriptor handle. (This is an INT variable, which you provide as argument fd.)

When saving to an existing file having a multi-page format, this function permits you to insert your image into the file at the page number you designate by argument nPageNum. If you want to append your image as the final page of the file, set nPageNum = IG_APPEND_PAGE. lFormatType should specify the format type and compression of the already existing file. If you do not know the format type you can first make a call to IG_info_get_FD_ex ().

NOTE: Please see a pseudo-code example of saving a multi-page files in the end of the section Saving to a Disk File Using a File Descriptor Handle.

When saving to a non-multi-page format, this function will save a new single-image file of the format type and compression specified by lFormatType. Any previous version of the file will be lost. When saving to a non-multi-page format, set nPageNum = 1.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

NOTE: In order for an ImageGear append page operation to work properly, it is absolutely necessary that your File Descriptor handle is pointing to the very beginning of the first image. If the first image has a header, the FD should point to the beginning of the header. If there is no header, the FD should point to the beginning of the bitmap data. The FD should never point to "wrapper data".
Appending and Inserting: While IG_APPEND_PAGE assures you that your loaded image will be appended to a pre-existing multi-page file, there are two other instances in which the value you assign to nPageNum will cause an append: if you set nPageNum to less than 1, or if you set nPageNum to greater than the number of pages in the file that you are saving to.
To summarize: ImageGear will insert your image to a pre-existing multi-image file if you set nPageNum to a value between 1 and the number of the last page in the file.
NOTE: ImageGear does not support the writing of tiled images.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

See the examples in the section Saving to a Disk File Using a File Descriptor Handle.

Sample: LoadCB, FILTER, MULTIMED

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_save_FD_CB

Group: Image Saving

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_FD_CB (
    AT_INT fd,
    UINT nPageNum,
    UINT nReserved,
    AT_LMODE lFormatType,
    LPFNIG_RASTER_GET lpfnRasterGet,
    LPFNIG_DIB_GET lpfnDIBget,
    LPVOID lpPrivate
);

Arguments:

fd
File Descriptor handle for an already opened file
nPageNum
Page number to save as, if a multi-page file; otherwise set to 1.
nReserved
Reserved, should be set to 0 for now.
FormatType
Type and compression to save as, such as IG_SAVE_BMP_RLE. For the full list see file Gear.h or the Table Format & Compression Type Constants (Image Saving Functions).
pfnRasterGet
Far pointer to a function of type LPFNIG_RASTER_GET, which will be called for each raster line of the imag, before that line is saved.
lpfnDIBGet
Far pointer to a function of type LPFNIG_DIB_GET, which will be called just prior to saving the DIB header.
pPrivate
Far pointer to a private data area. This pointer will be passed to the above two callback functions each time they are called.

Description:

This function operates similarly to IG_save_FD (), except that the data constituting the file is provided to ImageGear by your callback functions.

First, your lpfnDIBGet() callback is called. This function supplies ImageGear with the image's width, height, Bits Per Pixel, and all DIB information in the form of a DIB header. If the image requires a palette, this callback function also supplies the palette.

ImageGear then writes a header out to file fd, in the lFormatType format. Next, lpfnRasterGet() is called once for each raster line. ImageGear gets the raster line from the callback function. Then, it compresses the raster line (according to lFormatType) and writes the line to fd. (Note that the calls for the raster lines are not necessarily in order.)

NOTE: Refer to the descriptions for callback function types LPFNIG_DIB_GET and LPFNIG_RASTER_GET in this chapter.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTES: In order for an ImageGear append page operation to work properly, it is absolutely necessary that your File Descriptor handle is pointing to the very beginning of the first image. If the first image has a header, the FD should point to the beginning of the header. If there is no header, the FD should point to the beginning of the bitmap data. The FD should never point to "wrapper data".
Appending and Inserting: While IG_APPEND_PAGE assures you that your loaded image will be appended to a pre-existing multi-page file, there are two other instances in which the value you assign to nPageNum will cause an append: if you set nPageNum to less than 1, or if you set nPageNum to greater than the number of pages in the file that you are saving to.
To summarize: ImageGear will insert your image to a pre-existing multi-image file if you set nPageNum to a value between 1 and the number of the last page in the file.

ImageGear does not support the writing of tiled images.

Example:

LPFNIG_DIB_GET   MyDIBGet;       /* Will provide DIB header */
LPFNIG_RASTER_GET   MyRasterGet;     /* Will provide each raster
*/
INT  fd;        /* File Descriptor handle  */
DWORD  	dwPrivate[10];     /* Some private data  */
AT_ERRCOUNT  	nErrcount;    /* Count of returned errors on
stack*/
nErrcount = IG_save_FD_CB ( fd, 1, 0, IG_SAVE_BMP_UNCOMP,
MyRasterGet, MyDIBGet, (LPVOID) &dwPrivate );

Sample: LoadCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_save_FD_CB_ex

Group: Image Saving

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_FD_CB_ex(
    AT_INT fd,
    UINT nPage,
    UINT nReserved,
    AT_LMODE lFormatType,
    LPFNIG_RASTER_GET lpfnRasterGet,
    LPFNIG_DIB_GET_EX lpfnDIBGetEx,
    LPVOID lpPrivateData
);

Arguments:

fd
File Descriptor handle for an already opened file
nPage
Page number to save as, if a multi-page file; otherwise set to 1.
nReserved
Reserved, should be set to 0 for now.
lFormatType
Type and compression to save as, such as IG_SAVE_BMP_RLE. For the full list see file accucnst.h or the Table Format & Compression Type Constants (Image Saving Functions).
lpfnRasterGet
Pointer to a function of type LPFNIG_RASTER_GET, which will be called for each raster line of the imag, before that line is saved.
lpfnDIBGetEx
Pointer to a function of type LPFNIG_DIB_GET_EX, which will be called just prior to saving the DIB header.
lpPrivateData
Pointer to a private data area. This pointer will be passed to the above two callback functions each time they are called.

Description:

This function operates similarly to IG_save_FD (), except that the data constituting the file is provided to ImageGear by your callback functions.

First, your lpfnDIBGet() callback is called. This function supplies ImageGear with the image's width, height, bits per pixel, and all DIB information in the form of a DIB info object. If the image requires a palette, this callback function also supplies the palette.

ImageGear then writes a header out to file fd, in the lFormatType format. Next, lpfnRasterGet() is called once for each raster line. ImageGear gets the raster line from the callback function. Then, it compresses the raster line (according to lFormatType) and writes the line to fd. (Note that the calls for the raster lines are not necessarily in order.)

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: In order for an ImageGear append page operation to work properly, it is absolutely necessary that your File Descriptor handle is pointing to the very beginning of the first image. If the first image has a header, the FD should point to the beginning of the header. If there is no header, the FD should point to the beginning of the bitmap data. The FD should never point to "wrapper data".
Appending and Inserting: While IG_APPEND_PAGE assures you that your loaded image will be appended to a pre-existing multi-page file, there are two other instances in which the value you assign to nPageNum will cause an append: if you set nPageNum to less than 1, or if you set nPageNum to greater than the number of pages in the file that you are saving to.
To summarize: ImageGear will insert your image to a pre-existing multi-image file if you set nPageNum to a value between 1 and the number of the last page in the file.
NOTE: ImageGear does not support the writing of tiled images.

Example:

AT_ERRCOUNT nErrcount;  /* Number of errors on stack */
HFILE fd;               /* File descriptor */
DWORD dwPrivate[10];    /* Some private data */
fd = _lcreat("test.jpg", 0);
if (fd != HFILE_ERROR)
{
    nErrcount = IG_save_FD_CB_ex(
        fd,               /* File descriptor             */
        1,                /* Page number to save         */
        1,                /* Reserved. Always set to 1   */
        IG_SAVE_BMP_UNCOMP, /* File format to save as    */
        MyRasterGet,      /* Called for each raster line */
        MyDIBGetEx,       /* Called when header is saved */
        dwPrivate);       /* Callback data               */
    _lclose(fd);
}
AT_ERRCOUNT ACCUAPI MyDIBGetEx(
    LPVOID           lpPrivate, /* Private data passed in    */
    HIGDIBINFO*      lphDIB     /* DIB info object to return */
    )
{
    /* Copy handle of an existing DIB info object to lphDIB  */
    return 0;
}
AT_ERRCOUNT ACCUAPI MyRasterGet(
    LPVOID           lpPrivate, /* Private data passed in    */
    LPAT_PIXEL       lpRaster,  /* Raster line to set        */
    AT_PIXPOS        row,       /* Y position in the image   */
    DWORD            rasterSize /* Size of the raster line   */
    )
{
    /* Copy pixel data to write for this raster to lpRaster */
    return 0;
}

Sample: LOADCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_save_file

Group: Image Saving

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_file (
    HIGEAR hIGear,
    LPSTR lpszFilename,
    AT_LMODE lFormatType
);

Arguments:

hIGear
HIGEAR handle of the image to save
lpszFilename
Far pointer to the filename (you may include path with filename) in which to save.
lFormatType
A constant such as IG_SAVE_TIF_UNCOMP or IG_SAVE_BMP_RLE, telling format to save in, and also the compression scheme if applicable. See file accucnst.h for a list of all IG_SAVE_... constants.

Description:

This function will store the image rectangle of the image referenced by hIGear to disk using the name lpszFilename. lFormatType is used to set the format and compression (if applicable) of the output file. If you want to have ImageGear use the file extension provided in your filename string (lpszFilename) to determine the file format to save to, set lFormatType = IG_SAVE_UNKNOWN.

When an image is saved to a multi-page file format (for example, TIFF or DCX), if the file already exists then the new image is appended as a new page in the file. When an image is saved to a non-multi-page file format, if the file already exists it is simply overwritten; the previous version of the file is lost.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: Some file formats, such as TXT, JPEG, and others, may be saved with additional control, using IG_fltr_ctrl_get()and IG_fltr_ctrl_set(). See the description also in the section Using Format Filters API for Filter Control.

Example:

HIGEAR hIGear;      /* Handle of image to save */
AT_ERRCOUNT nErrcount;    /* Count of errs on stack upon ret
from func */
/* Save image to file "picture.bmp" in BMP format without
compression: */
nErrcount = IG_save_file ( hIGear, "picture.bmp",
IG_SAVE_BMP_UNCOMP );

Sample: DISPLAY, MFC, PAGE, THREADS, FlashPix, Scan

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_save_file_size_calc

Group: Image Saving

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_file_size_calc (
    HIGEAR hIGear,
    AT_LMODE lFormatType,
    LPAT_UINT file_size
);

Arguments:

hIGear
HIGEAR handle of the image on which to calculate the size.
lFormatType
A constant such as IG_SAVE_BMP_RLE or IG_SAVE_JPG, determining the file format and compression (if applicable) that will be used. The IG_SAVE_... constants associated with file formats support ed by ImageGear are listed in file accucnst.h.
file_size
Returned argument showing the maximum possible size of the file.

Description:

This function is used to determine the maximum size of the file that would result if the call IG_save_file (hIGear,"filename.ext",lFormatType) were executed just now. This call may be used prior to calling IG_save_mem () to determine the amount of memory that needs to be allocated.

Bits Per Pixel: 1, 4, 8, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

See the example for function IG_save_mem ().

Sample: MEMIO

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_save_JPEG_quality_get

Group: Image Saving

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_JPEG_quality_get ( LPUINT lpQuality
);

Arguments:

lpQuality
A long pointer which returns the current setting for JPEG quality.

Description:

This function returns the current setting for JPEG quality. This refers to the amount of data loss that will occur during JPEG compression. The original type of JPEG compression, which is what ImageGear uses, is a lossy scheme. This means that some data will always be lost during compression. Please see the section JPEG Quality.

NOTE: Use IG_save_JPEG_quality_set() to change the current setting.
NOTE: JPEG Quality is only used when an image is being saved with JPEG compression, not when an image has been compressed.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

UINT	 lpQuality;
IG_save_JPEG_quality_get(&lpQuality);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_save_JPEG_quality_set

Group: Image Saving

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_JPEG_quality_set ( UINT nQuality );

Arguments:

nQuality
An integer value from 1 to 100, where 100 represents the "highest quality" or least amount of pixel data lost.

Description:

This function sets the quality level for JPEG compression. This refers to the amount of data loss that will occur during JPEG compression. The original algorithm for JPEG compression, which is what ImageGear uses, is a lossy scheme. This means that some data will always be lost during compression. Use this function to set the level of loss, where 100 means the least amount possible of pixel data will be lost during compression, and 1 allows the most loss, (resulting in the smallest possible file after compression). Please see the section JPEG Quality.

NOTE: JPEG Quality is only used when an image is being saved with JPEG compression, not when an image has been compressed.

JPEG quality may also be set using IG_fltr_ctrl_set () with the string "QUALITY" as the second argument:

NOTE: A setting of 100 does not give you "lossless" JPEG. The JPEG compression scheme, by design, always results in some loss. If you wish to save as lossless, use IG_fltr_ctrl_set () to set "TYPE" control parameter to IG_JPG_LOSSLESS before saving.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

UINT 	nQuality;
IG_save_JPEG_quality_set(95);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_save_mem

Group: Image Saving

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_mem (
    HIGEAR hIGear,
    LPVOID lpImage,
    AT_UINT  nImageSize,
    AT_UINT  nBufferSize,
    UINT nPageNum,
    UINT nReserved,
    AT_LMODE lFormatType,
    LPAT_UINT lpActualSize
);

Arguments:

hIGear
HIGEAR handle of the image to save to memory
lpImage
Far pointer to first byte of memory area in which to save
nImageSize
Size of image (if exists).
nBufferSize
Size of memory block.
nPageNum
If saving to a multi-page file, set this to the page number to insert this page as. (Remember that the first page in a multi- page file is page 1, not 0.) Otherwise set = 1.
nReserved
Reserved, should always be set = 0 for now.
lFormatType
A constant such as IG_SAVE_TIF_UNCOMP or IG_SAVE_JPG, indicate the format in which to save, and compression scheme if applicable. See file accucnst.h for a list of all IG_SAVE_... constants.
lpActualSize
Size of new file in memory

Description:

This function is very similar to IG_save_FD(), but the image file that results from the call will be saved in memory beginning at location *lpImage, rather than on a mass storage device. You provide the total size of your memory area, nBufferSize, so ImageGear can avoid writing beyond the area you have reserved for the file image. The image file that results will be identical to what would have been written to disk had you used IG_save_FD (): it will begin with a header, and will be in the format you have declared by argument lFormatType. After writing the entire new file to memory, the actual size of this in-memory file is returned to you in the UINT variable pointed to by lpActualSize.

If the file format is multi-page, and if there already is a valid file of that format at location *lpImage, then the HIGEAR image you are saving will be inserted as the page number you've indicated by nPageNum. If you want to append your image to the multi-page file, set nPageNum = IG_APPEND_PAGE.

If the file format is not multi-page, then any file image already at location lpImage will be overwritten. Set nPageNum = 1 for non-multi-page file formats.

It is your application's responsibility to allocate the memory to hold the file image, and to free this memory when it is no longer needed. You may call function IG_save_file_size_calc () to determine the maximum amount of memory you need to allocate. (If you have not allocated enough memory an error will be set and *lpImage will contain an unfinished image. The image left in memory after this condition should not be used.)

NOTE: In order for an ImageGear append page operation to work properly, it is absolutely necessary that your File Descriptor handle is pointing to the very beginning of the first image. If the first image has a header, the FD should point to the beginning of the header. If there is no header, the FD should point to the beginning of the bitmap data. The FD should never point to "wrapper data".
Appending and Inserting: While IG_APPEND_PAGE assures you that your loaded image will be appended to a pre-existing multi-page file, there are two other instances in which the value you assign to nPageNum will cause an append: if you set nPageNum to less than 1, or if you set nPageNum to greater than the number of pages in the file that you are saving to.
To summarize: ImageGear will insert your image to a pre-existing multi-image file if you set nPageNum to a value between 1 and the number of the last page in the file.
NOTE: ImageGear does not support the writing of tiled images.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR  hIGear;         /* ImageGear handle  */
AT_ERRCOUNT nErrcount;      /* # of errors on stack */
AT_LMODE lFormatType;    /* format to save to */
AT_UINT nMaxSize,      /* Max file size might need */
        nActualSize;   /* Size of image */
HGLOBAL hBuf;           /* Windows handle of mem area */
AT_UINT nBuf;           /* Size of memory block */
lFormatType = IG_SAVE_BMP_RLE;/* Will save in BMP format, with
RLE compression:  */
/* Calculate max #bytes file might need: */
nErrcount = IG_save_file_size_calc ( hIGear,lFormatType,
&nMaxSize);
if (nErrcount == 0)     /* If no errs: */
{
/* Allocate sufficient memory:  */
hBuf = GlobalAlloc(GMEM_MOVEABLE|GMEM_ZEROINIT, dwMaxSize);
/* The mem is movable. Lock it, going to reference it:    */
lpBuf = GlobalLock(hBuf);      /* lpBuf = present location  */
/* Now save the image to the mem area:  */
nErrcount = IG_save_mem ( hIGear, lpBuf, 0, nMaxSize, 1, 0,
lFormatType, &lpActualSize );
if (nErrcount == 0);    /* if successful: */
{
/* Resize the buffer to actual #bytes used:  */
    hBuf = GlobalReAlloc ( hBuf, lpActualSize, GMEM_MOVEABLE);
}
GlobalUnlock(hBuf);     /* Unlock buffer so moveable  */
}
If (nErrcount) { ...}      /* Process any errors   */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_save_mem_CB_direct

Group: Image Saving

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_mem_CB_direct(
    LPVOID lpImage,
    AT_UINT nImageSize,
    AT_UINT nBufferSize,
    UINT nPage,
    UINT nReserved,
    AT_LMODE lFormatType,
    LPFNIG_DIRECT_RASTER_GET lpfnRasterGet,
    LPFNIG_DIB_GET    lpfnDIBGet,
    LPVOID lpPrivateData,
    LPAT_UINT lpActualSize
);

Arguments:

lpImage
Far pointer to first byte of memory address to save image to
nImageSize
Size of image (if exists).
nBufferSize
Size of memory block.
nPageNum
Page number to save as, if a multi- page file; otherwise set to 1.
nReserved
Reserved, should be set to 0 for now.
lFormatType
Type/compression to save as, such as IG_SAVE_BMP_RLE. See file accucnst.h for a list of all IG_SAVE_... constants.
lpfnRasterGet
Far pointer to a function of type LPFNIG_RASTER_GET, which will be called for each raster line of the image, before that line is saved
lpfnDIBGet
Far pointer to a function of type LPFNIG_DIB_GET, which will be called just prior to saving the DIB header
lpPrivate
Far pointer to a private data area which is passed to the above two callback functions each time they are called
lpActualSize
Size of new file in memory.

Description:

The operation of this function is similar to that of IG_save_FD_CB_ex (), except that the saving is to the memory area indicated by pointer lpImage, instead of to the file fd. After writing the entire new file to memory, the actual size of this in-memory file is returned to you in the DWORD variable pointed to by lpActualSize.

See the description for function IG_save_FD_CB_ex (), and also the description for function IG_save_mem ().

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24, 32

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_save_mem_CB_ex

Group: Format Filters

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_mem_CB_ex(
    LPVOID lpImage,
    AT_UINT nImageSize,
    AT_UINT nBufferSize,
    UINT nPage,
    UINT nReserved,
    AT_LMODE lFormatType,
    LPFNIG_RASTER_GET lpfnRasterGet,
    LPFNIG_DIB_GET_EX lpfnDIBGetEx,
    LPVOID lpPrivateData,
    LPAT_UINT lpActualSize
);

Arguments:

lpImage
Address to save image
nImageSize
Size of image (if exists)
nBufferSize
Size of memory block
nPage
Page number to save as, if a multi-page file; otherwise set to 1
nReserved
Reserved, should be set to 0 for now
lFormatType
Type/compression to save as, such as IG_SAVE_BMP_RLE. See file accucnst.h or the Table Format & Compression Type Constants (Image Saving Functions) for a list of all IG_SAVE_... constants.
lpfnRasterGet
Pointer to a function of type LPFNIG_RASTER_GET, which will be called for each raster line of the image, before that line is saved
lpfnDIBGetEx
Pointer to a function of type LPFNIG_DIB_GET_EX, which will be called just prior to saving the DIB header
lpPrivateData
Pointer to a private data area which is passed to the above two callback functions each time they are called
lpActualSize
Size of new file in memory

Description:

The operation of this function is similar to that of IG_save_FD_CB_ex(), except that the saving is to the memory area indicated by pointer lpImage, instead of to the file fd. After writing the entire new file to memory, the actual size of this in-memory file is returned to you in the DWORD variable pointed to by lpActualSize.

See the description for function IG_save_FD_CB_ex(), and also the description for function IG_save_mem().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

See the example for IG_save_mem(), and add the following statements:

LPFNIG_DIB_GET_EX MyDIBGet;    /* Will provide DIB header */
LPFNIG_RASTER_GET MyRasterGet; /* Will provide each raster */
DWORD dwPrivate[10];           /* Some private data */
nErrcount = IG_save_mem_CB(lpBuf, 0, nMaxSize, 1, 0,
lFormatType, MyRasterGet, MyDIBGet, (LPVOID) &dwPrivate[0],
lpActualSize);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_save_tag_CB_register

Group: Image Saving

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_tag_CB_register (
    LPFNIG_TAG_GET lpfnTagGet,
    LPFNIG_TAG_USER_GET lpfnTagUserGet,
    LPVOID lpPrivate
);

Arguments:

lpfnTagGet
Far pointer to callback function to be called during save operationS, prior to saving each Tag
lpfnTagUserGet
Far pointer to callback function to be called to obtain additional user Tags
lpPrivate
Far pointer to private data (passed to callback function)

Description:

This function registers a callback function to be called for each Tag while saving a file. A default value of the Tag is supplied, and can be changed in the callback function. See the description for callback function type LPFNIG_TAG_GET.

The second callback function you supply is of type LPFNIG_TAG_USER_GET, and permits you to provide additional tags. This can be used to add additional TIFF Tags when saving in TIFF format.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

LPFNIG_TAG_GET	 MyTagChanger;        /* To change existing tags
*/
LPFNIG_TAG_USER_GET  MyTiffTagger;       /* Can add new tags */
{
char far *    lpPrivate;              /* Pointer to private area
*/
 ...
IG_save_tag_CB_register ( MyTagChanger, MyTiffTagger, (LPVOID)
lpPrivate );
 ...
}

Sample: JPEG, FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_save_thumbnail_set

Group: Image Saving

Declaration:

AT_ERRCOUNT ACCUAPI IG_save_thumbnail_set (
    BOOL bToggle,
    AT_DIMENSION nWidth,
    AT_DIMENSION nHeight
);

Arguments:

bToggle
Thumbnail Flag: TRUE = enable thumbnails, FALSE = disable thumbnails
nWidth
Width of thumbnail rectangle
nHeight
Height of thumbnail rectangle

Description:

This function allows you to save a thumbnail (miniature) version of the image together with the full image, if the format that you are saving to supports thumbnails. Currently, ImageGear reads and writes two file formats that support thumbnails: TGA & JPEG. The size of the new thumbnail will be nWidth x nHeight. The values for nWidth and nHeight are unlimited in JPEG-JFIF, but a TGA thumbnail cannot exceed 64 x 64 pixels. Targa and JPEG-JFIF thumbnails are always 8-bit images. If the image data has a bit depth of greater than 8, ImageGear will automatically reduce the number of bits when creating the thumbnail.

When you load an image using one of the IG_load_...() functions, you will not automatically load any thumbnail that accompanies the main image. To load the thumbnail you must subsequently call one of the IG_load_thumbnail_...() functions. Similarly, when calling any of the IG_save_...() functions, the thumbnail will not be saved unless you first make a call to IG_save_thumbnail_set()function.

NOTE: If you are saving a file that has a thumbnail, but you don't make a call to IG_save_thumbnail_set(), only the image will be saved to the destination file; no thumbnail will be saved.

The example code shows an image named "picture.tif" being loaded first, and then its accompanying thumbnail is loaded. When it is ready to be saved (any desired changes have been made), IG_save_thumbnail_set() is called and then IG_save_file ().

Bits Per Pixel: 8, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR hIGear1;    /* Will hold handle ret'd by IG_load_file  */
HIGEAR hIGear2;     /* Handle returned by IG_load_thumbnail   */
AT_ERRCOUNT	 	nErrcount;  /* Count of errs on stack upon ret from
func */
AT_DIMENSION lWid, lHi;  /* Width and height of thumbnail   */
BOOL	 bToggle;    /* TRUE = thumbnail; FALSE = no thumbnail */
lWid = 32;         /* set width of thumb to 32 pixels        */
lHi = 32;          /* set height of thumbnail to 32 pixels   */
bToggle = TRUE;     /* do save a new thumbnail to new file   */
nErrcount = IG_load_file ( "picture.tif" , &hIGear1 );
if (nErrcount == 0)    /* loading the file was successful   */
    { nErrcount = IG_load_thumbnail ( "picture.tif", &hIGear2 );
}
}
{...perform image processing transformations on image...}
if (nErrcount == 0)           /* image processing was successful
*/
    /* To the file to be saved, add a thumbnail version of
processed image*/
    { nErrcount = IG_save_thumbnail_set ( bToggle, lWid, lHi );
}
}
if (nErrcount == 0)    /* thumbnail set for IMAGE was successful
*/
    {nErrcount=IG_save_file ( &hIGear1, "picture.tif",
IG_FORMAT_TIF_RLE );
}

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_status_bar_CB_register

Group: Callback

Declaration:

AT_ERRCOUNT ACCUAPI IG_status_bar_CB_register (
    LPFNIG_STATUS_BAR lpfnStatusBar,
    LPVOID lpPrivate
);

Arguments:

lpfnStatusBar
Far pointer to a function to be established as your status bar callback function. ImageGear will call this function once for each raster (pixel row) processed during load, save, print, and image processing operations. The argument list and return value of this function must be as shown in the definition of function type LPFNIG_STATUS_BAR.
lpPrivate
Far pointer to private data of your own choosing.

Description:

This function establishes a status bar callback function to be called by ImageGear during load, save, and print operations. ImageGear will call the named function once for each raster (row) processed, transmitting the Y position of that raster, the total number of rasters involved in the transfer, and the value of lpPrivate (pointer to your private data area). Your callback function can use this data to display a status bar showing percent completion, or for any other purpose.

To change to a different status bar function, or to change to a different private data area, call IG_status_bar_CB_register() again with your new callback function name and/or private data area address.

To disable status bar callbacks, call IG_status_bar_CB_register() with argument lpfnStatusBar = NULL.

NOTE: See also the description for function type LPFNIG_STATUS_BAR.

Bits Per Pixel: 1, 4, 8, 9-16-bit gray level, 24

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

LPFNIG_STATUS_BAR    MyStatusBarCallback;    /* Declare type of
function */
{
static DWORD      dwPrivateFlags;
 ...
IG_status_bar_CB_register ( MyStatusBarCallback, (LPVOID)
&dwPrivateFlags );

Sample: DISPLAY, IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_thread_data_ID_associate

Group: Threads

Declaration:

AT_ERRCOUNT ACCUAPI IG_thread_data_ID_associate(
    DWORD dwNewId,
    AT_BOOL bLeaveThreadStorage
);

Arguments:

dwNewId
ID of a new Data storage
bLeaveThreadStorage
If TRUE, old data storage is left in memory even if unused by any of the threads

Description:

ImageGear allows you to have different groups of settings for providing mechanisms for associating a thread with a particular group. By default, each thread uses the global copy. Such a mechanism allows you to have ImageGear settings ("groups" that are identified by specific IDs) that are customized for each thread. This API allows you to associate a thread with different ImageGear settings. Allocation of new settings will result in the use of that group's default values if it doesn't exist prior to the call. The old copy of the settings will be deleted unless it's (a) a global copy used by other threads, or (b) bLeaveThreadStorage is TRUE.

NOTE: The global group of ART settings cannot be used in multi-threaded application. You have to use this function to associate a new local group of settings for each new thread.
NOTE: The access to the same PDF document from multiple threads is not permitted because the multiple threads cannot share Adobe PDF Library datatypes. PDF doc created/opened in the main thread can be only used from the main thread.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

AT_ERRCOUNT nErrCount = 0;
nErrCount = IG_comm_comp_attach("ART");
. . .
AfxBeginThread( IGProcThread1, NULL );
AfxBeginThread( IGProcThread2 , NULL );
UINT IGProcThread1( LPVOID lpData )
{
    AT_ERRCOUNT nErrCnt;
    nErrCnt	= IG_thread_data_ID_associate( 1, TRUE );
    nErrCnt = IG_load_file( "picture1.bmp", &hIGear);
    . . .
    return 0;
}
UINT IGProcThread2( LPVOID lpData )
{
    AT_ERRCOUNT nErrCnt;
    nErrCnt	= IG_thread_data_ID_associate( 2, TRUE );
    nErrCnt = IG_load_file( "picture2.bmp", &hIGear);
    . . .
    return 0;
}:

Sample: THREADS

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_thread_data_ID_get

Group: Threads

Declaration:

AT_ERRCOUNT EXPORT ACCUAPI IG_thread_data_ID_get(LPDWORD
lpdwDataId);

Arguments:

LpdwDataId
A pointer to a variable for receiving information about group ID of settings currently associated with a thread.

Description:

This API retrieves the ID of the group of settings used by a particular thread.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

nErrCnt = IG_thread_data_ID_get( &dwLocalId );

Sample: THREADS

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_thread_local_data_cleanup

Group: Threads

Declaration:

AT_ERRCOUNT EXPORT ACCUAPI IG_thread_local_data_cleanup(DWORD
dwClDataId);

Arguments:

dwClDataId
The group ID of settings to clean up.

Description:

This API destroys a group of settings with a specific ID if it's not being use by any threads.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

nErrCnt = IG_thread_local_data_cleanup( 1 );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_thread_image_lock

Group: Threads

Declaration:

AT_ERRCOUNT EXPORT ACCUAPI IG_thread_image_lock(
    HIGEAR hIGear,
    AT_MODE nLockMode
);

Arguments:

hIGear
HIGEAR image handle
nLockMode
The lock mode (IG_THREAD_LOCK_READ or IG_THREAD_LOCK_WRITE) indicator. Several threads can perform read lock concurrently, but only one thread is allowed to do write lock.

Description:

This API locks HIGEAR for a particular operation. Two APIs (IG_thread_image_lock(), IG_thread_image_unlock ()) are required for those rare situations in which two or more threads-at least one of which is modifying or deleting an image-are simultaneously accessing the same HIGEAR. For example, one thread can save HIGEAR to a JPEG file (read access to a HIGEAR), while another is performing rotation in the asynchronous mode (write access to a HIGEAR). Thus, the "saving" thread would be required to call lock/unlock with the read mode as a parameter, and the "rotation" thread would be required to call lock/unlock with the write mode as a parameter.

NOTE: Please note that all auxilary HIGEARs associated with the main HIGEAR (such as Alpha channel, NRA mask, and transparency mask) need to be locked separately.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

hIGear = pDoc->hMainGear;
    nErrCnt = IG_thread_image_lock( pDoc->hMainGear,
IG_THREAD_LOCK_WRITE );
    if (nErrCnt == 0)
        {
        // locked successfully
        IG_IP_rotate_multiple_90( hIGear, IG_ROTATE_90 );
        IG_thread_image_unlock( pDoc->hMainGear,
IG_THREAD_LOCK_WRITE );
...
        }

Sample: THREADS

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_thread_image_unlock

Group: Threads

Declaration:

AT_ERRCOUNT EXPORT ACCUAPI IG_thread_image_unlock(
    HIGEAR hIGear,
    AT_MODE nLockMode
);

Arguments:

hIGear
ImageGear Image handle
nLockMode
The lock mode (IG_THREAD_LOCK_READ or IG_THREAD_LOCK_WRITE) indicator. Several threads can perform read lock concurrently, but only one thread is allowed to do write lock.

Description:

Two APIs (IG_thread_image_lock () and IG_thread_image_unlock()) are required for those situations in which two or more threads-at least one of which is modifying or deleting an image-are simultaneously accessing the same HIGEAR. For example, one thread can save HIGEAR to a JPEG file (read access to a HIGEAR), while another is performing rotation in the asynchronous mode (write access to a HIGEAR). Thus the "saving" thread would be required to call lock/unlock with the read mode as a parameter, and the "rotation" thread would be required to call lock/unlock with the write mode as a parameter.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

hIGear = pDoc->hMainGear;
    nErrCnt = IG_thread_image_lock( pDoc->hMainGear,
IG_THREAD_LOCK_WRITE );
    if (nErrCnt == 0)
        {
        // locked successfully
        IG_IP_rotate_multiple_90( hIGear, IG_ROTATE_90 );
        IG_thread_image_unlock( pDoc->hMainGear,
IG_THREAD_LOCK_WRITE );
...
        }

Sample: THREADS

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_tile_count_get

Group: Image Utility

Declaration:

LPSTR ACCUAPI IG_tile_count_get (
    const LPSTR lpszFileName,
    UINT nPageNum,
    LPUINT lpTileRows,
    LPUINT lpTileCols
);

Arguments:

lpszFileName
Name of the file containing the image
nPageNum
Page to get the count of tiles for
lpTileRows
Far pointer to a UINT variable to receive the number of tiles in a row (for tiled images)
lpTileCols
Far pointer to a UINT variable to receive the number of tile columns

Description:

This function can be called for images that may be tiled. The number of tiles across (number of tiles in a row) is returned to the UINT variable pointed to by lpTileRows, and the number of tiles down (number of tiles in a column) is returned to the UINT variable pointed to by lpTileCols. (The total number of tiles constituting the page is therefore (lpTileRows * lpTileCols).)

Bits Per Pixel: 1, 4, 8, 24

Return Value:

The return type is AT_ERRCOUNT. This returns the number of errors that occurred during the execution of this function.

Example:

UINT nTileRows;      /* Will receive number of tile rows */
UINT nTileCols;     /* Will receive number of tile cols  */
LPSTR lpszFileName;  /* Holds name of file  */
AT_ERRCOUNT nErrcount;     /* Returned count of errors  */
/* Get number of tiles, first page of file:  */
nErrcount = IG_tile_count_get ( lpszFileName, 1, &nTileRows,
&nTileCols );

Sample: MEMIO, FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_tile_count_get_FD

Group: Image Utility

Declaration:

LPSTR ACCUAPI IG_tile_count_get_FD (
    AT_INT fd,
    LONG lOffset,
    UINT nPageNum,
    LPUINT lpTileRows,
    LPUINT lpTileCols
);

Arguments:

fd
File Descriptor handle
lOffset
Offset in file of file image
nPageNum
Page to get count of tiles for
lpTileRows
Far pointer to a UINT variable to receive the number of tiles in a row rows, if the image is tiled
lpTileCols
Far pointer to a UINT variable to receive the number of tile columns

Description:

This function obtains the number of tiles constituting a page, for file formats that support tiled pages. Use this function when the file is open and you have its File Descriptor handle. See the description under IG_tile_count_get () for the meanings of arguments lpTileRows and lpTileCols.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

The return type is AT_ERRCOUNT. This returns the number of errors that occurred during the execution of this function.

Example:

INT fd;            /* File Descriptor handle  */
UINT nTileRows;     /* Will receive number of tile rows  */
UINT nTileCols;     /* Will receive number of tile cols  */
AT_ERRCOUNT nErrcount;     /* Returned count of errors  */
/* Get number of tiles, first page of file:  */
nErrcount = IG_tile_count_get_FD ( fd, 0, 1, &nTileRows,
&nTileCols );

Sample: FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_tile_count_get_mem

Group: Image Utility

Declaration:

LPSTR ACCUAPI IG_tile_count_get_mem (
    LPVOID lpImage,
    AT_UINT nImageSize,
    UINT nPageNum,
    LPUINT lpTileRows,
    LPUINT lpTileCols
);

Arguments:

lpImage
Far pointer to the start of the image in memory
nImageSize
Size of image in memory
nPageNum
Page to get the count of tiles for
lpTileRows
Far pointer to a UINT variable to receive the number of tiles in a row rows, if the image is tiled
lpTileCols
Far pointer to a UINT variable to receive the number of tile columns

Description:

This function obtains the number of tiles constituting a page, for file formats that support tiled pages. Use this function when the file image is in memory. See the description under IG_tile_count_get () for the meanings of arguments lpTileRows and lpTileCols.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

The return type is AT_ERRCOUNT. This returns the number of errors that occurred during the execution of this function.

Example:

char FAR * lpMemImage;       /* Pointer to file image in memory
*/
AT_UINT nImageSize;           /* Size of image in memory */
UINT nTileRows;        /* Will receive number of tile rows */
UINT nTileCols;       /* Will receive number of tile cols  */
AT_ERRCOUNT nErrcount;      /* Returned count of errors
*/
/* Get number of tiles, first page of file:*/
nErrcount = IG_tile_count_get_mem ( lpMemImage, nImageSize, 1,
&nTileRows, &nTileCols );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_util_colorspace_alpha_count_get

Group: Library Utility

Declaration:

AT_UINT ACCUAPI IG_util_colorspace_alpha_count_get(
    enumIGColorSpaceIDs colorSpace
);

Arguments:

colorSpace
Color space ID

Description:

This function returns the number of alpha channels in the specified color space. Currently it can be either 0 or 1.

Bits Per Pixel: All

Return Value:

The number of alpha channels.

Example:

enumIGColorSpaceIDs colorSpace = IG_COLOR_SPACE_ID_RGBA;
AT_UINT nAlpha;         /* Number of alpha channels */
nAlpha = IG_util_colorspace_alpha_count_get(colorSpace);
/* nAlpha is 1 */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_util_colorspace_color_count_get

Group: Library Utility

Declaration:

AT_UINT ACCUAPI IG_util_colorspace_color_count_get(
    enumIGColorSpaceIDs colorSpace
);

Arguments:

colorSpace
Color space ID

Description:

This function returns the number of color channels in the specified color space. Color channels are all image channels except alpha and extra channels.

Bits Per Pixel: All

Return Value:

The number of color channels.

Example:

enumIGColorSpaceIDs colorSpace = IG_COLOR_SPACE_ID_RGBA;
AT_UINT nColor;         /* Number of color channels */
nColor = IG_util_colorspace_color_count_get(colorSpace);
/* nColor is 3 */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_util_colorspace_contains_alpha

Group: Library Utility

Declaration:

AT_BOOL ACCUAPI IG_util_colorspace_contains_alpha(
    enumIGColorSpaceIDs colorSpace
);

Arguments:

colorSpace
Color space ID

Description:

This function returns whether or not the color space contains an alpha channel (either premultiplied or not premultiplied).

Bits Per Pixel: All

Return Value:

Returns TRUE if the colorspace contains an alpha channel, FALSE otherwise.

Example:

enumIGColorSpaceIDs colorSpace = IG_COLOR_SPACE_ID_RGBA;
AT_BOOL bAlpha;         /* Does the color space have alpha? */
bAlpha = IG_util_colorspace_contains_alpha(colorSpace);
/* bAlpha is TRUE */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_util_colorspace_contains_extra

Group: Library Utility

Declaration:

AT_BOOL ACCUAPI IG_util_colorspace_contains_extra(
    enumIGColorSpaceIDs colorSpace
);

Arguments:

colorSpace
Color space ID

Description:

This function returns whether or not the color space contains extra channels.

Bits Per Pixel: All

Return Value:

Returns TRUE if the colorspace contains extra channels, FALSE otherwise.

Example:

enumIGColorSpaceIDs colorSpace = IG_COLOR_SPACE_ID_RGBAEx;
AT_BOOL bExtra; /* Does the color space have extra channels? */
bExtra = IG_util_colorspace_contains_extra(colorSpace);
/* bExtra is TRUE */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_util_colorspace_extra_count_get

Group: Library Utility

Declaration:

AT_UINT ACCUAPI IG_util_colorspace_extra_count_get(
    enumIGColorSpaceIDs colorSpace,
    AT_UINT totalChannelCount
);

Arguments:

colorSpace
Color space ID
totalChannelCount
Total number of channels in the color space

Description:

This function returns the number of extra channels in the specified color space. You must specify the total number of channels in the color space in order for this to be calculated.

Bits Per Pixel: All

Return Value:

Returns the number of extra channels.

Example:

enumIGColorSpaceIDs colorSpace = IG_COLOR_SPACE_ID_RGBAEx;
AT_UINT nExtra;         /* Number of extra channels */
nExtra = IG_util_colorspace_extra_count_get(colorSpace);
/* nExtra is 1 */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_util_colorspace_is_premultiplied

Group: Library Utility

Declaration:

AT_BOOL ACCUAPI IG_util_colorspace_is_premultiplied(
    enumIGColorSpaceIDs colorSpace
);

Arguments:

colorSpace
Color space ID

Description:

This function checks whether the alpha channel in the color space is premultiplied.

Bits Per Pixel: All

Return Value:

Returns TRUE, if the alpha channel in the color space is premultiplied. Returns FALSE, if the alpha channel in the color space is not premultiplied or the color space does not contain an alpha channel.

Example:

enumIGColorSpaceIDs colorSpace = IG_COLOR_SPACE_ID_RGBA;
AT_BOOL bPremult; /* Does color space have premult. alpha? */
bPremult = IG_util_colorspace_is_premultiplied(colorSpace);
/* bPremult is FALSE */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_util_colorspace_is_valid

Group: Library Utility

Declaration:

AT_BOOL ACCUAPI IG_util_colorspace_is_valid(
    enumIGColorSpaceIDs colorSpace
);

Arguments:

colorSpace
Color space ID

Description:

This function checks whether ImageGear supports the color space identified by the color space constant.

Bits Per Pixel: All

Return Value:

Returns TRUE, if the color space is supported, FALSE otherwise.

Example:

enumIGColorSpaceIDs colorSpace;
/* Invalid color space - can't have non-premult and premult */
colorSpace = IG_COLOR_SPACE_ID_RGBA | IG_COLOR_SPACE_ID_P;
AT_BOOL bValid;         /* Is the color space valid? */
bValid = IG_util_colorspace_is_valid(colorSpace);
/* bValid is FALSE */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_util_colorspace_value_to_ids

Group: Utils

Declaration:

enumIGColorSpaceIDs ACCUAPI IG_util_colorspace_value_to_ids(
    enumColorSpaces colorSpace
);

Arguments:

colorSpace
Legacy ImageGear color space ID

Description:

This function maps from legacy ImageGear color space ID (enumColorSpaces) to current ImageGear color space ID (enumIGColorSpaceIDs). It exists because the newer color space IDs are different and can store more information. See accucnst.h for the definitions of these enumerations.

Bits Per Pixel: N/A

Return Value:

The current ImageGear color space ID that corresponds with the given legacy ImageGear color space ID.

Example:

enumColorSpaces oldCS;  /* Old color space ID */
enumIGColorSpaceIDs cs; /* New color space ID */
oldCS = IG_COLOR_SPACE_CMYK;
cs = IG_util_colorspace_value_to_ids(oldCS);
/* cs is now IG_COLOR_SPACE_ID_CMYK */
oldCS = IG_COLOR_SPACE_RGBA;
cs = IG_util_colorspace_value_to_ids(oldCS);
/* cs is now IG_COLOR_SPACE_ID_RGBA */

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_util_MMX_usage_get

Group: Library Utility

Declaration:

AT_ERRCOUNT LACCUAPI IG_util_MMX_usage_get (LPBOOL
lpbMMXUsage);

Arguments:

lpbMMXUsage
A far pointer that returns a Boolean value indicating whether or not ImageGear is set to optimize for MMX hardware.

Description:

This function returns the current state of MMX optimization. If lpbMMXUsage returns TRUE it means that ImageGear is set to optimize for MMX technology if the computer contains MMX hardware.

If this parameter is TRUE but the MMX processor is not detected, then MMX optimization will not be used.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: See also IG_util_MMX_usage_set() function.

Example:

AT_ERRCOUNT nErrcount;
BOOL bMMXon;
nErrcount = IG_util_MMX_usage_get(bMMXon);

Sample: JPEG

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_util_MMX_usage_set

Group: Library Utility

Declaration:

AT_ERRCOUNT LACCUAPI IG_util_MMX_usage_set(BOOL bMMXUsage);

Arguments:

bMMXUsage
Set to TRUE to turn on MMX optimization; FALSE to turn off MMX optimization.

Description:

This function tells ImageGear whether or not to optimize for MMX hardware. Set lpbMMXUsage to TRUE to instruct ImageGear to optimize for MMX technology if the computer contains MMX hardware.

If you set bMMXUsage = TRUE, MMX technology will be used if it is detected. If it is not detected, no error will be generated, and MMX optimization will not be used.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

NOTE: As of this writing, the JPEG Lossy Compression is the target area for optimization.
NOTE: See also IG_util_MMX_usage_get() function.

Example:

AT_ERRCOUNT   nErrcount;
bMMXusage = TRUE;
nErrcount = IG_util_MMX_usage_set(bMMXusage);

Sample: JPEG

NOTE: The JPEG sample also demonstrates loading images with or without MMX support.


IG_util_version_get

Group: Utility

Declaration:

VOID ACCUAPI IG_util_version_get(
    [OUT] LPCHAR lpStr
);

Arguments:

lpStr
Pointer to an array of chars where necessary string is returned.

Description:

This utility return text information about the ImageGear version.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

CHAR szBuf[256];
 ...
IG_util_version_get( szBuf );
 ...

Sample: MFC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vector_data_get

Group: Vector Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_vector_data_get(
    HIGEAR hIGear,
    LPVOID* lplpVectorData
);

Arguments:

hIGear
HIGEAR handle of the image
lplpVectorData
vector data

Description:

This function returns the vector data interface in the lplpVectorData parameter for the given HIGEAR handle.

NOTE: The second parameter should be converted to the IIGVectorData pointer to become an accessible for the vector data functionality.
NOTE: This function can be used only for the DWF, DXF, DWG, DGN, HPGL and HPGL/ 2, and U3D vector formats with the ImageGear CAD/Vector DWF Component, ImageGear CAD/Vector DWG, DXF Component, ImageGear CAD/Vector DGN Component and ImageGear CAD/Vector HPGL, HPGL/ 2 Component, ImageGear CAD/Vector CGM Component, ImageGear U3D Vector Component attached only.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

/* C++ interface   */
IIGVectorData*   pVectorData;
AT_ERRCOUNT      nErrCount;
nErrCount = IG_vector_data_get(hIGear, (LPVOID*)& pVectorData);
    if(!nErrCount && pVectorData)
    {
    /* Rotate camera to 90 degrees in XY plane */
    pVectorData-> CameraRotate(3.14159/4, IG_DIR_XY);
    }
/* C interface */
IIGVectorData*    pVectorData;
AT_ERRCOUNT       nErrCount;
nErrCount = IG_vector_data_get(hIGear, (LPVOID*)& pVectorData);
    if(!nErrCount && pVectorData)
    {
    /* Rotate camera to 90 degrees in XY plane */
    pVectorData-> lpVtbl->CameraRotate(pVectorData, 3.14159/4,
IG_DIR_XY);
    }

Sample: Vector

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vector_data_to_dib

Group: Vector Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_vector_data_to_dib(
    HIGEAR hIGearSource,
    LPHIGEAR lphIGearDest
);

Arguments:

hIGearSource
Source image handle
lphIGearDest
New image - non-zero pointer to HIGEAR that takes a raster HIGEAR

Description:

This function flushes the vector data to DIB. The second parameter must be a non-zero pointer to HIGEAR that takes a raster HIGEAR. The source HIGEAR should be deleted manually.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIGEAR rasterhigear;
IG_vector_data_to_dib(hIGear, &rasterhigear);
IG_image_delete(hIGear);
hIGear = rasterhigear;

Sample: Vector

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_version_compile_date

Group: Library Utility

Declaration:

LPSTR ACCUAPI IG_version_compile_date (VOID);

Description:

This function can be called to obtain the date of compilation of the version of ImageGear you are using. The return value is a FAR pointer to a string in the form "Mmm dd yyyy", such as "Jul 04 1996."

Bits Per Pixel: N/A

Return Value:

Returns a FAR pointer to a string containing the compile date in the format given above. If there are no errors, the return value is IGE_SUCCESS.

Example:

#include <string.h>
char	  MyCompileDateString[12]; /* Will receive "Mmm dd yyyy" */
strcpy ( MyCompileDateString, IG_version_compile_date())

Sample: MFC, SHARED, Bar

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_version_numbers

Group: Library Utility

Declaration:

AT_ERRCOUNT ACCUAPI IG_version_numbers (
    LPINT lpVerMajor,
    LPINT lpVerMinor,
    LPINT lpVerUpdate
);

Arguments:

lpVerMajor
Far pointer to an INT variable in which will be stored the Major version number of the version of ImageGear that you are using
lpVerMinor
Far pointer to an INT variable in which will be stored the Minor version number of the version of ImageGear that you are using
lpVerUpdate
Far pointer to an INT variable in which will be stored the Update (bug fix) number, reflecting any updates you have received and installed in this version of ImageGear.

Description:

This function returns three integers telling you the version of ImageGear that your application is currently using, including the last update installed. The Major and Minor version numbers are, for example, the "10" and "0" respectively, for the first release of ImageGear 10.0 (ImageGear2000).

The above numbers appear in accucnst.h. Your application can compare the accucnst.h constants with the numbers returned here to verify that the proper version of the ImageGear DLL is being loaded and used.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

INT	 nVerMaj, nVerMin, nVerUpdate;
IG_version_numbers ( &nVerMaj, &nVerMin, &VerUpdate );

Sample: MFC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


Core Component Callback Functions Reference

This section describes each callback supported by ImageGear Core component. They are presented in alphabetical order.


LPAFT_IG_ICC_GET_CB

Group: Callback

Declaration:

typedef VOID (LPACCUAPI  LPAFT_IG_ICC_GET_CB)(
    AT_VOID *lpPrivate,
    AT_BYTE *lpICCData,
    AT_INT DataLength
);

Arguments:

lpPrivate
Private callback data.
lpICCData
ICC profile data, allocated by ImageGear.
DataLength
Length of ICC profile data, in bytes.

Description:

This callback function is called every time when the format filter encounters an ICC profile in the loaded image. The ICC profile is provided in the standard ICC format as a byte array. ImageGear allocates the buffer for ICC profile data so that the application does not delete it. If the application needs to use the ICC profile after the callback call, it copies it to its own buffer.

Use IG_fltr_ICC_callback_set () to register this callback function.

Use IG_fltr_ICC_callback_get () function to retrieve your ICC callback settings.

Bits Per Pixel: N/A

Return Value: N/A

Sample: LoadCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPAFT_IG_METAD_ITEM_ADD_CB

Group: Callback

Declaration:

typedef AT_BOOL (LPACCUAPI LPAFT_IG_METAD_ITEM_ADD_CB)(
    LPVOID lpPrivate,
    AT_MODE FormatID,
    LPCHAR ItemName,
    DWORD ItemID,
    AT_MODE ItemType,
    LPVOID ItemValue,
    AT_MODE ValueType,
    DWORD ValueLength,
    AT_BOOL ReadOnlyValue,
);

Arguments:

lpPrivate
Private callback data.
FormatID
The ID of format filter that send or get the item (IG_FORMAT_... constant).
ItemName
Provides the name of new item.
ItemID
Numerical ID of item.
ItemType
Specifies the type of item and reflect the status of given record. Possible values are:
  • IG_METAD_VALUE_ITEM - this value specifies that current item is value of simplest type and field Value contains actual value of item and ValueType contains identifier of type of this item. ReadOnly can be either TRUE (readonly ) or FALSE (read/ write). Name and/or Id contains textual and numerical identification of item.
  • IG_METAD_LEVEL_START - this value specifies that current item opens sublevel of items and all next items up to correspondent item with LEVEL_END value belongs to this sublevel.
  • IG_METAD_LEVEL_END - this value close current sublevel and tells that next item belongs to higher level.
ItemValue
Value of new item. If ItemType = IG_METAD_VALUE_ITEM then ItemValue contains actual value of item of type specified by ValueType parameter.The ItemValue is stored as array of elements where each element contains values of type ValueType. Length of array is provided in parameter ValueLength.
ValueType
If ItemType = IG_METAD_VALUE_ITEM then contains actual type of value stored in ItemValue pointer. See Non-Image data format section for exact list of possible types.
ValueLength
Length of array in ItemValue.
ReadOnlyValue
If this argument is TRUE then actual value of item can not be changed by callback function and value is passed for information purpose only. If FALSE then value of item can be changed and application can provide new value through next three parameters.

Description:

This callback function is used to insert new items during WRITE filter operation. If return value is TRUE then new value is added and FALSE if value is not added. ImageGear will be calling Add callback function while it returns TRUE so callback function should return TRUE if providing of additional items is it not finished yet, and FALSE if it is finished. All parameters except of lpPrivate is used to get information about new value.

See also IG_fltr_metad_callback_get (), IG_fltr_metad_callback_set (), LPAFT_IG_METAD_ITEM_GET_CB, LPAFT_IG_METAD_ITEM_SET_CB functions and the section Processing of non-image data through filter callback functions.

Bits Per Pixel: ALL

Return Value:

Returns TRUE if new value is added to item data, FALSE if it is not. Returned TRUE will cause to call Add callback function one more time.

Example:

See example for IG_fltr_metad_callback_set () function.

Sample: JPEG

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPAFT_IG_METAD_ITEM_GET_CB

Group: Callback

Declaration:

typedef VOID (LPACCUAPI LPAFT_IG_METAD_ITEM_GET_CB)(
    LPVOID lpPrivate,
    AT_MODE FormatID,
    LPCHAR ItemName,
    DWORD ItemID,
    AT_MODE ItemType,
    LPVOID ItemValue,
    AT_MODE ValueType,
    DWORD ValueLength,
    AT_BOOL ReadOnlyValue,
);

Arguments:

lpPrivate
Private callback data.
FormatID
The ID of format filter that send or get the item (IG_FORMAT_... constant).
ItemName
Name of item.
ItemID
Numerical ID of item.
ItemType
Specifies the type of item and reflect the status of given record. Possible values are:
  • IG_METAD_VALUE_ITEM - this value specifies that current item is value of simplest type and field Value contains actual value of item and ValueType contains identifier of type of this item. ReadOnly can be either TRUE (readonly ) or FALSE (read/ write). Name and/or Id contains textual and numerical identification of item.
  • IG_METAD_LEVEL_START - this value specifies that current item opens sublevel of items and all next items up to correspondent item with IG_METAD_LEVEL_END value belongs to this sublevel.
  • IG_METAD_LEVEL_END - this value close current sublevel and tells that next item belongs to higher level.
ItemValue
If ItemType = IG_METAD_VALUE_ITEM then ItemValue contains actual value of item of type specified by ValueType parameter.Value is stored as array of elements where each element contains values of type ValueType. Length of array is provided in parameter ValueLength.
ValueType
Type of element stored in array ItemValue.
ValueLength
Length of array of elements stored in ItemValue.
ReadOnlyValue
If this argument is TRUE then actual value of item can not be changed by callback function and value is passed for information purpose only. If FALSE then value of item can be changed and application can provide new value through next three parameters.

Description:

This callback function is used to get information about metadata items received during READ filter operation. ReadOnlyValue parameter is used to inform application that value of given item is for information only and can not be changed during future operations. It may allow to simplify future processing of this item at application level.

See also IG_fltr_metad_callback_get (), IG_fltr_metad_callback_set (), LPAFT_IG_METAD_ITEM_ADD_CB, LPAFT_IG_METAD_ITEM_SET_CB functions and the section Processing of non-image data through filter callback functions.

Bits Per Pixel: ALL

Return Value: None

Example:

See example for IG_fltr_metad_callback_set () function.

Sample: JPEG

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPAFT_IG_METAD_ITEM_SET_CB

Group: Callback

Declaration:

typedef AT_BOOL (LPACCUAPI LPAFT_IG_METAD_ITEM_SET_CB)(
    LPVOID lpPrivate,
    AT_MODE FormatID,
    LPCHAR ItemName,
    DWORD ItemID,
    AT_MODE ItemType,
    LPVOID ItemValue,
    AT_MODE ValueType,
    DWORD ValueLength,
    AT_BOOL ReadOnlyValue,
    LPVOID *NewItemValue,
    LPAT_MODE *NewValueType,
    LPDWORD *NewValueLength
);

Arguments:

lpPrivate
Private callback data associated with metadata callback function.
FormatID
The ID of format filter that send or get the item (IG_FORMAT_... constant).
ItemName
Text name of item.
ItemID
Numerical ID of item.
ItemType
Specifies the type of item and reflect the status of given record. Possible values are:
  • IG_METAD_VALUE_ITEM - this value specifies that current item is value of simplest type and field Value contains actual value of item and ValueType contains identifier of type of this item. ReadOnly can be either TRUE (readonly ) or FALSE (read/ write). Name and/or Id contains textual and numerical identification of item.
  • IG_METAD_LEVEL_START - this value specifies that current item opens sublevel of items and all next items up to correspondent item with LEVEL_END value belongs to this sublevel.
  • IG_METAD_LEVEL_END - this value close current sublevel and tells that next item belongs to higher level.
ItemValue
If ItemType = IG_METAD_VALUE_ITEM then this argument contains actual value of item of type specified by ValueType parameter.Value is stored as array of elements where each element contains values of type ValueType. Length of array is provided in parameter ValueLength.
ValueType
If ItemType = IG_METAD_VALUE_ITEM then ValueType contains actual type of value stored in ItemValue pointer. See Non-Image data format section for the exact list of possible types.
ValueLength
If ItemType = IG_METAD_VALUE_ITEM then VaueLength contains number of elements in array ValueItem of type specified by ValueType.
ReadOnlyValue
If this argument is TRUE then actual value of item can not be changed by callback function and value is passed for information purpose only. If FALSE then value of item can be changed and application can provide new value through next three parameters.
NewItemValue
Pointer to new item value that application may request to set as replacement of data passed in ItemValue parameter. If it is not NULL then next two parameters contain the type of value and length of array of elements.
NewValueType
Specifies the type of new item value passed through NewItemValue parameter.
NewValueLength
Specifies the size of array passed through NewItemValue pointer.

Description:

If this callback function is defined in the format filter then during filter WRITE operation it is called every time when some data is ready to be writen. Application can change/provide new value for given item using NewItemValue, NewValueType and NewValueLength parameters. This new value is to be used as replacement for default data passed through ItemValue parameter in the case if ReadOnlyValue is FALSE. Callback function should return TRUE if callback function has changed value, and FALSE if it is not changed.

See also IG_fltr_metad_callback_get (), IG_fltr_metad_callback_set (), LPAFT_IG_METAD_ITEM_ADD_CB, LPAFT_IG_METAD_ITEM_GET_CB functions and the section Processing of non-image data through filter callback functions.

Bits Per Pixel: ALL

Return Value:

Returns TRUE if ImageGear should overwrite the default item data with your data, or FALSE if ImageGear should ignore your data.

Example:

See example for IG_fltr_metad_callback_set () function.

Sample: JPEG

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_BATCH_BEFORE_OPEN

Group: Callback

Declaration:

typedef AT_BOOL (LPACCUAPI LPFNIG_BATCH_BEFORE_OPEN)(
    LPVOID lpPrivate,
    const LPSTR lpszFileName
);

Arguments:

lpPrivate
A far pointer to private data area
lpszFileName
The name of file to be opened

Description:

LPFNIG_BATCH_BEFORE_OPEN is called before a file is opened, allowing you to get the file name and correct some settings. For example, some multimedia formats and PDF file names require you to get the file name before page conversion.

Bits Per Pixel: All

Return Value:

Reserved (must always be TRUE).

Example:

//Dll
//User's BatchBeforeOpen CB
AT_BOOL MyBatchBeforeOpen(
   LPVOID         lpPrivate,     /* Private data passed in*/
        const LPSTR    lpszFileName   /* File name to be open*/
   )
{
// Set PDF control name if the file is PDF
        AT_MODE	nFileType;
        IG_info_get(lpszFileName, 1, NULL, nFileType, NULL,
NULL);
        if(nFileType == IG_FORMAT_PDF)
        {
            IG_fltr_ctrl_set(IG_FORMAT_PDF, "FILENAME", (LPVOID)
lpszFileName, sizeof(lpszFileName));
        }
        return TRUE;
}
// Register BatchBeforeOpen CB
IG_batch_CB_register(MyBatchBeforeOpen, IG_BATCHCB_BEFORE_OPEN,
NULL);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_BATCH_BEFORE_SAVE

Group: Callback

Declaration:

typedef AT_BOOL (LPACCUAPI LPFNIG_BATCH_BEFORE_SAVE)(
    LPVOID lpPrivate,
    HIGEAR hIGear,
    UINT nPageNumber
);

Arguments:

lpPrivate
Far pointer to private data area
hIGear
HIGEAR handle to the image
nPageNumber
This variable is set to the number of pages to be saved

Description:

LPFNIG_BATCH_BEFORE_SAVE is called before an image file is saved, allowing you to correct and image before saving. For example, you might want to rotate an image before saving.

NOTE: Multipage documents can be saved as a set of different files if the flag IG_BATCH_MP_TO_MP is not specified.

Bits Per Pixel: All

Return Value:

Reserved (must always be TRUE).

Example:

// DLL
// User's BatchBeforeSave CB
AT_BOOL MyBatchBeforeSave(
       LPVOID         lpPrivate,   /* Private data passed in     */
    HIGEAR         hIGear,               /* ImageGear image handle
*/
    UINT           nPageNumber           /* Number of page to be
saved */
   )
{
    // Convert bpp to 1 before saving
    UINT bits_per_pixel;
    IG_image_dimensions_get(hIGear, NULL, NULL, &
bits_per_pixel);
    If(bits_per_pixel != 1)
    {
        IG_IP_color_reduce_bayer(hIGear, 1, NULL);
}
    return TRUE;
}
// Register BatchBeforeSave CB
IG_batch_CB_register(MyBatchBeforeSave, IG_BATCHCB_BEFORE_SAVE,
this);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_CHECK_PIXEL

Group: Callback

Declaration:

typedef AT_BOOL (LPACCUAPI LPFNIG_CHECK_PIXEL)(
    AT_INT bitsPerChannel,
    AT_INT channelCount,
    LPAT_VOID checkData,
    LPAT_PIXEL pixel
);

Arguments:

bitsPerChannel
Number of bits per channel used to store the pixel being checked.
channelCount
Number of channels in the pixel being checked.
checkData
User-defined data passed to calling function (for example, detectStruct parameter of IG_IP_detect_area).
pixel
Pointer to the pixel to be checked.

Description:

This callback returns TRUE if the given pixel does not belong to the area (border found), and FALSE otherwise.

Return Value:

True/False


LPFNIG_DIB_CREATE

Group: Callback

Declaration:

typedef AT_ERRCOUNT (ACCUAPI LPFNIG_DIB_CREATE) (
    LPVOID lpPrivate,
    const LPAT_DIB lpDIB,
    const LPAT_RGBQUAD lpRGB
);

Arguments:

lpPrivate
Far pointer to private data area
lpDIB
Far pointer to start of an AT_DIB DIB header (that is, a BITMAPINFOHEADER) struct created by ImageGear
lpRGB
Far pointer to the first of the AT_RGBQUAD structs constituting the palette in the DIB. Will be NULL if the image is 24-bit.

Description:

This is one of the two types of callback functions supplied in calls to IG_load_FD_CB () and IG_load_mem_CB (). This callback function is called by ImageGear to provide your application the information it needs to create its own DIB header and palette.

On entry to this function lpDIB points to an AT_DIB struct which ImageGear has created upon reading the file's header. You can use information from this AT_DIB struct to create your own DIB header, but you should not alter the information at lpDIB.

Similarly, lpRGB points to the palette as obtained from the file. (lpRGB = NULL if no palette.) You can copy the palette, or create your own for the DIB you are creating.

NOTE: If you need to terminate the load, you can place an error on the stack yourself, using IG_error_set(). See the description for that function.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns an error count.

Example:

BOOL  ACCUAPI MyDIB_Create (LPVOID lpPrivate, LPAT_DIB lpDIB,
LPAT_RGBQUAD lpRGB )
{
/* Can allocate memory, create a DIB header (AT_DIB) and
palette. Later, an LPFNIG_RASTER_SET function can create the
image bitmap. */
 ...
return IG_error_check();
}

Sample: LoadCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_DIB_CREATE_EX

Group: Callback

Declaration:

typedef AT_ERRCOUNT (LPACCUAPI LPFNIG_DIB_CREATE_EX)(
    LPVOID lpPrivate,
    HIGDIBINFO hDIB
);

Arguments:

lpPrivate
Far pointer to private data area
hDIB
Extended DIB header

Description:

This callback function is called after the image header has been read. It passes image information, including palette, through HIGDIBINFO structure.

hDIB object is owned by ImageGear. The application shall not use it after exiting from the callback function, and shall not delete it.

Bits Per Pixel: All

Return Value:

Returns an error count.

Sample: LoadCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_DIB_GET

Group: Callback

Declaration:

typedef AT_ERRCOUNT (ACCUAPI LPFNIG_DIB_GET) (
    LPVOID lpPrivate,
    LPAT_DIB lpDIB,
    LPAT_RGBQUAD lpRGB
);

Arguments:

lpPrivate
Far pointer to private data area
lpDIB
Far pointer to start of the DIB header, that is the AT_DIB (BITMAPINFOHEADER) struct that begins the DIB
lpRGB
Far pointer to first of the AT_RGBQUAD structs constituting the palette in the DIB. Will be NULL if it is a 24-bit image.

Description:

This is one of the two types of callback functions supplied in calls to IG_save_FD_CB_ex () and IG_save_mem_CB_ex (). This callback function is called by ImageGear prior to saving the DIB header and palette.

On entry to this function, lpDIB points to the image's DIB header (AT_DIB or BITMAPINFOHEADER struct), and lpRGB points to its DIB palette. This function is responsible for setting the DIB header fields (width, height, bits per pixel, compression, etc.) and for assuring the palette desired if it is not a 24-bit image.

NOTE: If you need to terminate the load, you can place an error on the stack yourself, using IG_error_set(). See the description for that function.

Bits Per Pixel: N/A

Return Value:

Returns an error count.

Example:

BOOL  ACCUAPI MyDIBGet (LPVOID lpPrivate, LPAT_DIB lpDIB,
LPAT_RGBQUAD lpPalette )
{
/* Modify the DIB header fields at *lpDIB as desired, and store
a
   palette at *lpPalette */
 ...
return IG_error_check();
}

Sample: LoadCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_DIB_GET_EX

Group: Callback

Declaration:

typedef AT_ERRCOUNT (LPACCUAPI LPFNIG_DIB_GET_EX)(
    LPVOID lpPrivate,
    HIGDIBINFO *lphDIB
);

Arguments:

lpPrivate
Far pointer to private data area
lphDIB
Extended DIB header

Description:

This callback function is called before writing the image header. The application shall create a new HIGDIBINFO object containing information about the image, and pass through the lphDIB parameter. ImageGear owns the HIGDIBINFO object after exiting from the callback, and eventually deletes it. If the image being saved has a palette, it should be passed with HIGDIBINFO as well.

Bits Per Pixel: N/A

Return Value:

Returns an error count.

Sample: LoadCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ERRMNGR_ADD

Group: Callback

Declaration:

typedef VOID (LPACCUAPI LPFNIG_ERRMNGR_ADD)(
    LPVOID lpPrivate,
    DWORD dwThreadID,
    UINT nRecord,
    INT iLineNumber,
    AT_ERRCODE  iCode,
    UINT nLevel,
    AT_INT lValue1,
    AT_INT lValue2,
    LPCHAR lpFileName,
    LPCHAR lpExtratext
);

Arguments:

lpPrivate
Private data passed in.
dwThreadID
Thread identifier where error happened.
nRecord
Index of this record in the stack.
iLineNumber
Line number where a problem occurred.
iCode
Error code.
nLevel
Level of the error.
lValue1
Specific value idendifying the reason for an error.
lValue2
Specific value idendifying the reason for an error.
lpFileName
Pointer to a string holding a filename or NULL if not available.
lpExtratext
Pointer to a string holding extra info or NULL if not available.

Description:

This callback is called each time when new error record is added by any thread.

Return Value: None

Example:

VOID ACCUAPI ErrGlAddCB(
    LPVOID	 lpPrivate,     /* Private data passed in.  */
    DWORD	 dwThreadID,   /* Thread identifier where record added.
*/
    UINT	 nRecord,     /* index of this record in the stack.
*/
    INT	 iLineNumber,  /* line number where problen occurred.
*/
    AT_ERRCODE	 iCode,     /* error code.        */
    UINT	  nLevel,    /* level of the error. */
    LONG 	lValue1,
    LONG	 lValue2,
    LPCHAR	 lpFileName,   /* filename str ofr NULL if not present.
*/
    LPCHAR	 lpExtratext   /* extra text info about error. */
);
{
    char	 szOutput[1024];
    sprintf( szOutput, "Global CallBack - new error record
added:\nThread=%i\nRecord=%i\nLine=%i\nCode=%i\nLevel=%i\nValue
1=%i; Value2=%i,\nFile Name: %s\nExtra Text: %s",
        dwThreadID, nRecord, iLineNumber, iCode, nLevel, lValue1,
lValue2, lpFileName, lpExtratext );
    //AfxMessageBox( szOutput );
    ::MessageBox(NULL, szOutput, "THREADS", MB_OK);
}

Sample: THREADS

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ERRMNGR_CLEAR

Group: Callback

Declaration:

typedef VOID (LPACCUAPI LPFNIG_ERRMNGR_CLEAR)(
    LPVOID lpPrivate,
    DWORD dwThreadID,
    UINT nRecords
);

Arguments:

lpPrivate
Private data passed in.
dwThreadID
Thread identifier where the stack cleared.
nRecords
Number of records cleared from the stack starting from index 0.

Description:

This callback is called each time an error stack is cleared by any thread. Since each thread has its own independent error stack clearing, a stack by one thread does not cause other stacks to clear.

Return Value: None

Example:

VOID ACCUAPI ErrGlClearCB(
LPVOID    lpPrivate,    /* Private data passed in. */
DWORD     dwThreadID,   /* Thread identifier where stack
cleared.  */
UINT      nRecords    /* Number of records cleared from the stack
starting from 0 index. */
)
{
char      szOutput[1024];
sprintf( szOutput, "Global CallBack - error stack
cleared\nThread:%i, Records cleared:%i", dwThreadID, nRecords
);
    //AfxMessageBox( szOutput );
    ::MessageBox(NULL, szOutput, "THREADS", MB_OK);
}

Sample: THREADS

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ERRSTACK_ADD

Group: Callback

Declaration:

typedef VOID (LPACCUAPI LPFNIG_ERRSTACK_ADD)(
    LPVOID lpPrivate,
    UINT nRecord,
    INT iLineNumber,
    AT_ERRCODE iCode,
    UINT nLevel,
    AT_INT lValue1,
    AT_INT lValue2,
    LPCHAR lpFileName,
    LPCHAR lpExtratext
);

Arguments:

lpPrivate
Private data passed in when you register a callback.
nRecord
Index of this record in the stack.
iLineNumber
Line number where the problem has occurred.
iCode
Error code.
nLevel
Level of the error.
lValue1
Specific value idendifying the reason for the error.
lValue2
Specific value idendifying the reason for the error.
lpFileName
Pointer to a string holding a filename or NULL if not available.
lpExtratext
Pointer to a string holding additional information, or NULL if not available.

Description:

This callback function is called each time a thread that registered this callback (using IG_err_callback_set () function) adds a new record to the error stack.

Return Value: None

Example:

VOID   ACCUAPI  LocThErrAddCB(
LPVOID	 lpPrivate,    /* Private data passed in.  */
UINT 	nRecord,     /* index of this record in the stack    */
INT	 iLineNumber, /* line number where problen occurred   */
AT_ERRCODE   iCode,     /* error code. */
UINT      nLevel,       /* level of the error.     */
LONG      lValue1,
LONG      lValue2,
LPCHAR    lpFileName,  /* filename str ofr NULL if not present.
*/
LPCHAR    lpExtratext  /* extra text info about error.  */
)
{
    char	 szOutput[1024];
    sprintf( szOutput, "Local CallBack - new error record
added:\nThread Id:%u\nThread
Number=%i\nRecord=%i\nLine=%i\nCode=%i\nLevel=%i\nValue1=%i;
Value2=%i,\nFile Name: %s\nExtra Text: %s",
        GetCurrentThreadId(), (int)lpPrivate, nRecord,
iLineNumber, iCode, nLevel, lValue1, lValue2, lpFileName,
lpExtratext );
    //AfxMessageBox( szOutput );
    ::MessageBox(NULL, szOutput, "THREADS", MB_OK);
}

Sample: FILTER, MULTIMED, THREADS

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_ERRSTACK_CLEAR

Group: Callback

Declaration:

typedef VOID (LPACCUAPI LPFNIG_ERRSTACK_CLEAR)(
    LPVOID lpPrivate,
    UINT nRecords
);

Arguments:

lpPrivate
Private data passed in.
nRecords
Number of records cleared from the stack starting with index 0.

Description:

This callback function is called each time a thread that registered this callback (using IG_err_callback_set () function) clears the stack.

Return Value: None

Example:

VOID  ACCUAPI  LocThErrClearCB(
LPVOID	 lpPrivate,     /* Private data passed in.
*/
UINT	 nRecords     /* Number of records cleared from the stack
starting from 0 index. */
)
{
    char	 szOutput[1024];
    sprintf( szOutput, "Local CallBack - error stack
cleared\nThread Id:%u\nThread number:%i, Records cleared:%i",
        GetCurrentThreadId(), (int)lpPrivate, nRecords );
    // AfxMessageBox( szOutput );
    ::MessageBox(NULL, szOutput, "THREADS", MB_OK);
}

Sample: FILTER, FlashPix, MULTIMED, THREADS

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUIPAGEDELETEPROC

Group: Callback

Declaration:

typedef VOID (ACCUAPI LPFNIG_GUIPAGEDELETEPROC)(
    LPVOID lpPrivate,
    HWND hwndPage,
    HIGEAR hIGear,
    UINT nPageNumber,
    BOOL fDestroy
);

Arguments:

lpPrivate
A far pointer to private data that is being passed into the callback
hwndPage
Windows handle to the page sorter window
hIGear
HIGEAR handle to the image
nPageNumber
This integer variable is set to the page number of the image icon in the GUI page sorter that will be deleted.
fDestroy
A variable of type BOOL that gives you the status of whether the page sorter window has been destroyed. TRUE = destroyed.

Description:

This callback function gets called whenever the user presses the Delete key over a page icon from the page sorter window.

This callback must first be registered by calling IG_GUI_page_delete_CB_register ().

Bits Per Pixel: 1, 4, 8, 24

Return Value: None

Example:

HIGEAR hIGear;      /* HIGEAR handle of image   */
HWND hwndPage;  /* Windows handle to the Page Sorter window   */
LPFNIG_GUIPAGEDELETEPROC PageDeleteProc;  /* Callback to handle
deletion*/
IG_GUI_page_delete_CB_register(hwndPage, PageDeleteProc, NULL);
/
***************************************************************
************/
/* Called when a page is deleted
*/
/
***************************************************************
************/
VOID ACCUAPI PageDeleteProc(LPVOID lpPrivateData, HWND
hwndPage, HIGEAR   hIGearPage, UINT nPage, BOOL fDestroy)
{
   CHAR     szBuf[_MAX_PATH + 32];
   UINT     nPageCount;
   lpPrivateData;
   /* delete the image */
   IG_image_delete(hIGearPage);
}
/* See the Page.c sample code for a more complete procedure */

Sample: PAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUIPAGEORDERPROC

Group: Callback

Declaration:

typedef VOID (ACCUAPI LPFNIG_GUIPAGEORDERPROC)(
    LPVOID lpPrivate,
    HWND hwndPage
);

Arguments:

lpPrivate
A far pointer to private data that is being pass into the callback
hwndPage
Windows handle to the GUI page sorter window

Description:

This callback function gets called whenever the pages in the page sorter window have been re-ordered by the user. It gives you notification that the pages have been re-ordered.

This callback must first be registered by calling IG_GUI_page_order_CB_register ().

Bits Per Pixel: 1, 4, 8, 24

Return Value: None

Example:

HIGEAR hIGear;           /* HIGEAR handle of image */
HWND hWndPage;    /* Windows handle to page sorter window  */
LPFNIG_GUIPAGEORDERPROC PageOrderProc; /* Callback for page
reordering*/
IG_GUI_page_order_CB_register(hwndPage, PageOrderProc, NULL);
/
***************************************************************
************/
/* Called when a pages are reordered
*/
/
***************************************************************
************/
VOID ACCUAPI PageOrderProc(
   LPVOID   lpPrivateData,
   HWND     hwndPage
 )
{
   lpPrivateData;
   /* set the global hIGear to the current page */
   IG_GUI_page_handle_get(hwndPage, nCurrentPage, &hIGear);
   InvalidateRect(hWndMain, NULL, FALSE);
   UpdateWindow(hWndMain);
}

Sample: PAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUIPAGESELECTPROC

Group: Callback

Declaration:

typedef VOID (ACCUAPI LPFNIG_GUIPAGESELECTPROC)(
    LPVOID lpPrivate,
    HWND hwndPage,
    HIGEAR hIGear,
    UINT nPageNumber
);

Arguments:

lpPrivate
A far pointer to private data that is being pass into the callback
hwndPage
Windows handle to the GUI page sorter window
hIGear
HIGEAR handle to the image
nPageNumber
The page number of the currently selected page icon

Description:

This callback function gets called every time a page icon is selected (mouse-clicked over) by the user from the page sorter window.

This callback must first be registered by calling IG_GUI_page_select_CB_register ().

Bits Per Pixel: 1, 4, 8, 24

Return Value: None

Example:

HIGEAR hIGear;    /* HIGEAR handle of image  */
HWND hwndPage;   /* Windows handle to the page sorter window
*/
LPFNIG_GUIPAGESELECTPROC PageSelectProc; /* Callback for icon
selection*/
IG_GUI_page_select_CB_register(hwndPage, PageSelectProc, NULL);
/
***************************************************************
************/
/* Called when a page is selected
*/
/
***************************************************************
************/
VOID ACCUAPI PageSelectProc(
   LPVOID   lpPrivateData,
   HWND     hwndPage,
   HIGEAR   hIGearPage,
   UINT     nPage
   )
{
   CHAR     szBuf[_MAX_PATH + 32];
   hwndPage, lpPrivateData;
   hIGear = hIGearPage;
   nCurrentPage = nPage;
   /* change the title of the main window to reflect a page
change */
   wsprintf(szBuf, "%s Page:  %d", (LPVOID)szFile, nPage);
   SetWindowText(hWndMain, szBuf);
   IG_dspl_dithering_set(hIGear, IG_GRP_DEFAULT,
IG_DSPL_DITHER_FIXED_PALETTE);
   InvalidateRect(hWndMain, NULL, FALSE);
   UpdateWindow(hWndMain);
}

Sample: PAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUIPALETTE

Group: Callback

Declaration:

typedef BOOL (ACCUAPI LPFNIG_GUIPALETTE) (
    LPVOID lpPrivate,
    UINT nPaletteIndex,
    LPAT_RGBQUAD lpRGB
);

Arguments:

lpPrivate
Far pointer to private data area
nPaletteIndex
Index of palette entry that changed
lpRGB
Far pointer to the entry

Description:

This type of callback function is registered by calling IG_GUI_palette_CB_register (). It is called any time the user has attempted to change a palette color in the palette window. You may perform any operations you wish here, but you should also return TRUE to tell ImageGear to go ahead with the change and actually modify the DIB palette, FALSE to tell ImageGear to deny the change.

If you have not registered a palette callback function, ImageGear will make each change the user attempts.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Return TRUE to modify the DIB palette, FALSE to make no changes.

Example:

BOOL ACCUAPI  MyPaletteCBFunc ( LPVOID lpPrivate, UINT
nEntryNum, LPAT_RGBQUAD lpRBGQ_PaletteEntry )
{
INT	r, g, b;           /* will hold the palette colors */
                /* Don't let the user change color 0:   */
if ( nEntryNum == 0 )
    { return  FALSE; }  /* Don't store or display the new color
*/
/* If the color is too dark, don't accept it: */
r  =  lpRGBQ_PaletteEntry -> rgbRed;
g  =  lpRGBQ_PaletteEntry -> rgbGreen;
b  =  lpRGBQ_PaletteEntry -> rgbBlue;
if ( (r<20) || (g<20) || (b<20) )
    { return  FALSE; }    /* Too dark, say "Don't store it"   */
return  TRUE;           /* Else OK, store and display new color
*/
}
NOTE: See also the example under function IG_GUI_palette_CB_register().

Sample: PALEDT

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUIPANUPDATE

Group: Callback

Declaration:

typedef VOID (LPACCUAPI LPFNIG_GUIPANUPDATE)(
    LPVOID lpPrivate,
    HWND hwndPan,
    const LPAT_RECT lprcDevice
);

Arguments:

lpPrivate
Private data passed in.
hwndPan
Pan window handle.
lprcDevice
New device rectangle after panned.

Description:

This type of callback function is registered by a call to the IG_GUI_pan_CB_register ()function. It is called after a Pan window is updated.

Bits Per Pixel: N/A

Return Value: None

Example:

 /* CB function*/
VOID  MyPanUpdateCB (LPVOID lpPrivate,  HWND hwndPan,   const
LPAT_RECT   lprcDevice){
 /* Do something with the new device rectangle lprcDevice */}
...
/* register Pan Update CB */
IG_GUI_pan_CB_register (hwndPan, MyPanUpdateCB, NULL);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUISELECT

Group: Callback

Declaration:

typedef VOID (ACCUAPI LPFNIG_GUISELECT) (
    LPVOID lpPrivate,
    const LPAT_RECT lprcSelect
);

Arguments:

lpPrivate
Far pointer to private data area
lprcSelect
Far pointer to Selection Rectangle

Description:

This type of callback function is registered during a call to IG_GUI_select_track_mouse (). The callback function is called when the user has delineated a rectangle, using the mouse, in a GUI image window. Argument lprcSelect tells the coordinates of two opposite corners of the rectangle.

Bits Per Pixel: 1, 4, 8, 24

Return Value: None

Example:

See the example for function IG_GUI_select_track_mouse ().

Sample: CLPBRD, DISPLAY, Recognition

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUITHUMBCOMP

Group: Callback

Declaration:

typedef INT (ACCUAPI LPFNIG_GUITHUMBCOMP) (
    LPVOID lpPrivate,
    HWND hWndThumbnail,
    const LPSTR lpszFileName1,
    const LPSTR lpszFileName2,
    const LPAT_DIB lpDIB1,
    const LPAT_DIB lpDIB2
);

Arguments:

lpPrivate
Far pointer to private data passed in
hWndThumbnail
Thumbnail window handle
lpszFileName1
Far pointer to zero-terminated string; name of the first thumbnail file of two to be compared
lpszFileName2
Far pointer to zero-terminated string; name of the second thumbnail file of two to be compared
lpDIB1
Far pointer to DIB of first thumbnail file
lpDIB2
Far pointer to DIB of second thumbnail file

Description:

This type of callback function is registered during a call to IG_GUI_thumbnail_sort (). It is called automatically for successive pairs of thumbnails in your thumbnail window, until all have been sorted. You are passed both the filename and the DIB pointer for each of the pair of thumbnails, and you may compare them in any way you wish. You return -1 to tell ImageGear that the first thumbnail (file and DIB1) should go "before" the other, or +1 to tell ImageGear that the first should go "after." Return 0 if either order is acceptable.

Bits Per Pixel: N/A

Return Value:

Return a value of -1, 0, or +1, to indicate the first thumbnail is to be before, equal, or after, the second thumbnail.

Example:

For an example of this and other IG_GUI_Thumbnail_ functions and callbacks, see sample application THUMB.

Sample: THUMB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUITHUMBCREATE

Group: Callback

Declaration:

typedef VOID (ACCUAPI LPFNIG_GUITHUMBCREATE) (
    LPVOID lpPrivate,
    HWND hWndThumbnail,
    UINT nIndex
);

Arguments:

lpPrivate
Far pointer to the private data that was passed.
hWndThumbnail
Thumbnail window handle
nIndex
Index of a thumbnail icon

Description:

This type of callback function is registered by a call to IG_GUI_thumbnail_create_CB_register (). It is called when the user appends a thumbnail in the window hWndThumbnail.

Bits Per Pixel: N/A

Return Value: None

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUITHUMBDELETE

Group: Callback

Declaration:

typedef VOID (ACCUAPI LPFNIG_GUITHUMBDELETE) (
    LPVOID lpPrivate,
    HWND hWndThumbnail,
    UINT nIndex
);

Arguments:

lpPrivate
Far pointer to private data passed in
hWndThumbnail
Thumbnail window handle
nIndex
Index of a thumbnail icon

Description:

This type of callback function is registered by a call to IG_GUI_thumbnail_delete_CB_register (). It is called when the user removes a thumbnail in window hWndThumbnail.

Bits Per Pixel: N/A

Return Value: None

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUITHUMBLOAD

Group: Callback

Declaration:

typedef AT_BOOL (LPACCUAPI LPFNIG_GUITHUMBLOAD)(
    LPVOID lpPrivate,
    HWND hwndThumbnail,
    const LPSTR lpszFileName
);

Arguments:

lpPrivate
Private data passed in.
hwndThumbnail
Thumbnail window handle.
lpszFileName
File name of the thumbnail.

Description:

This type of callback function is registered by a call to the IG_GUI_thumbnail_load_CB_register ()function. It is called when the user loads a thumbnail in the window hwndThumbnail.

Bits Per Pixel: N/A

Return Value: None

Example:

 /* CB function*/
AT_BOOL MyLoadCB(LPVOID lpPrivate,  HWND hwndThumbnail,   const
LPSTR lpszFileName)
{
 /* just a test */
MessageBox(hwndThumbnail, (LPCTSTR) lpszFileName, "Thumbnail
file Name", MB_OK);
return TRUE;
}
...
 /* register Load CB */
IG_GUI_thumbnail_load_CB_register(hwndThumbnail, MyLoadCB,
NULL);

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUITHUMBMOUSE

Group: Callback

Declaration:

typedef BOOL (ACCUAPI LPFNIG_GUITHUMBMOUSE) (
    LPVOID lpPrivate,
    HWND hWndThumbnail,
    UINT nMouseAction,
    UINT nKeyFlags,
    UINT x,
    UINT y,
    UINT nIndex
);

Arguments:

lpPrivate
Far pointer to the private data passed in
hWndThumbnail
Thumbnail window handle
nMouseAction
Mouse notification code. Possible values are:
· IG_GUI_MOUSE_LDOWN
· IG_GUI_MOUSE_LUP
· IG_GUI_MOUSE_LDBL
· IG_GUI_MOUSE_RDOWN
· IG_GUI_MOUSE_RUP
· IG_GUI_MOUSE
· IG_GUI_MOUSE_RDBL
nKeyFlags
WM_ flags for mouse messages
x, y
Coordinates of the mouse pointer
nIndex
Index of a thumbnail icon

Description:

This type of callback function is registered by a call to IG_GUI_thumbnail_mouse_CB_register (). It is called when the user selects a thumbnail in window hWndThumbnail.

Bits Per Pixel: N/A

Return Value:

This function should return TRUE to allow further zooming or to select an icon.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUITHUMBSELECT

Group: Callback

Declaration:

typedef VOID (ACCUAPI LPFNIG_GUITHUMBSELECT) (
    LPVOID lpPrivate,
    HWND hWndThumbnail,
    const LPSTR lpszFileName,
    const LPAT_DIB lpDIB,
    UINT nPageNumber
);

Arguments:

lpPrivate
Far pointer to private data passed in
hWndThumbnail
Thumbnail window handle
lpszFileName
Far pointer to zero- terminated string, file name of thumbnail selected
lpDIB
Far pointer to its DIB
nPageNumber
Page number of the thumbnail that was selected from a GUI window. If the thumbnail comes from a non multi-page file, nPageNumber = 1.

Description:

This type of callback function is registered by a call to IG_GUI_thumbnail_CB_register (). It is called when the user selects a thumbnail in window hWndThumbnail. You are passed the filename and the address of a copy of the thumbnail image's DIB header. You are also passed the page number of the image in the file.

Bits Per Pixel: N/A

Return Value: None

Example:

For a complete example showing the use of this and other IG_GUI_Thumbnail functions and callbacks, see sample application THUMB.

Sample: DISPLAY, THUMB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUITHUMBTITLE

Group: Callback

Declaration:

typedef BOOL (ACCUAPI LPFNIG_GUITHUMBTITLE)(
    LPVOID lpPrivate,
    HWND hwndThumbnail,
    const LPSTR lpszFileName,
    const LPAT_DIB lpDIB,
    UINT nPageNumber,
    LPSTR lpszTitle
);

Arguments:

lpPrivate
A far pointer to any private data that you would like to pass in
hwndThumbnail
The Windows handle to the Thumbnail window
lpszFileName
A far pointer that is set to the filename of the thumbnail just loaded
lpDIB
A far pointer to a structure of type AT_DIB. This is set to the Thumbnail's image info
nPageNumber
An integer variable that is set to the Thumbnail page number
lpszTitle
A far pointer to the string you would like to use as a Title to use for this thumbnail. The string length must not exceed 260 characters.

Description:

This callback function allows you to change the title of a thumbnail. It is called when a thumbnail is first loaded. The default title of a thumbnail is its filename. You can override the filename with anything you want. For example, the title might include the filename followed by page number, file size, file date, etc. You must register this function first by calling the IG_GUI_thumbnail_title_CB_register () function.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

If this callback returns TRUE, the title of a thumbnail icon is changed to the title returned by this callback function. Otherwise, if the return value is FALSE, the title will not be changed.

Example:

HIGEAR hIGear;          /* HIGEAR handle of image */
UINT nThumbTitle = ID_OPTIONS_SETTHUMBNAILTITLES_FILENAME;
UINT nThumbTitleHeight = 10;      /* thumbnail title height */
LPFNIG_GUITHUMBTITLE MyThumbTitleFunc; /* Callback for setting
titles */
nErrCount = IG_GUI_thumbnail_title_CB_register(hwndThumb,
MyThumbTitleFunc,(LPVOID)&nThumbTitle);
nErrcount =
IG_GUI_thumbnail_attribute_set(hwndThumb,IG_GUI_THUMBNAIL_TITLE
_HEIGHT, (LPVOID)(DWORD)nThumbTitleHeight);
/
***************************************************************
**********/
/* Callback function that sets the name of a thumbnail title. */
/
***************************************************************
**********/
BOOL ACCUAPI MyThumbTitleFunc(
   LPVOID            lpPrivate,      /* Private data passed in
*/
   HWND              hwndThumbnail,  /* Thumbnail window handle
*/
   const LPSTR       lpszFileName,   /* File name of thumbnail
*/
   const LPAT_DIB    lpDIB,          /* Thumbnail image info
*/
   UINT              nPageNumber,    /* Thumbnail page number */
   LPSTR             lpszTitle       /* Title to use for this
icon*/
)
{
    UINT nThumbTitle;
    CHAR szPath[_MAX_PATH];
    LPSTR lpTitle;
    struct _stat  statBuf;
    nThumbTitle = *(LPUINT)lpPrivate;
    switch (nThumbTitle)
    {
    case ID_OPTIONS_SETTHUMBNAILTITLES_FILENAME:
        #ifndef WIN32
            lpTitle = _fstrrchr(lpszFileName, '\\');
        #else
            lpTitle = strrchr(lpszFileName, '\\');
        #endif
        if (lpTitle)
            lpTitle++;
        else
        lpTitle = lpszFileName;
        lstrcpy(lpszTitle, lpTitle);
        AnsiLower(lpszTitle);
        break;
    case ID_OPTIONS_SETTHUMBNAILTITLES_FILEDATE:
        lstrcpy(szPath, lpszFileName);
        _stat(szPath, &statBuf);
lstrcpy(lpszTitle, ctime(&statBuf.st_atime));
        break;
    case ID_OPTIONS_SETTHUMBNAILTITLES_FILESIZE:
        lstrcpy(szPath, lpszFileName);
        _stat(szPath, &statBuf);
        wsprintf(lpszTitle, "%ld Bytes", statBuf.st_size);
        break;
    case ID_OPTIONS_SETTHUMBNAILTITLES_BITSPERPIXEL:
        if (lpDIB->biBitCount == 1)
            wsprintf(lpszTitle, "%d Bit Per Pixel", lpDIB-
                >biBitCount);
        else
            wsprintf(lpszTitle, "%d Bits Per Pixel",
                lpDIB->biBitCount);
        break;
    case ID_OPTIONS_SETTHUMBNAILTITLES_PAGENUMBER:
        wsprintf(lpszTitle, "Page %d", nPageNumber);
        break;
    }
    return TRUE;
}

Sample: THUMB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_GUIWINDESTROY

Group: Callback

Declaration:

typedef VOID (ACCUAPI LPFNIG_GUIWINDESTROY) (
    LPVOID lpPrivate,
    HIGEAR hIGear,
    HWND hWndImage
);

Arguments:

lpPrivate
Far pointer to private data area
hIGear
HIGEAR handle of image
hWndImage
GUI window handle

Description:

This type of callback function is registered by calling IG_GUI_window_CB_register (). It is called when a GUI image window is destroyed.

Bits Per Pixel: N/A

Return Value: None

Example:

See the example for function IG_GUI_window_create ().

Sample: GUIWIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_IMAGESPOOLED

Group: Callback

Declaration:

typedef BOOL (ACCUAPI LPFNIG_IMAGESPOOLED) (
    LPVOID lpPrivate,
    UINT nImageNumber,
    UINT nPageNumber
);

Arguments:

lpPrivate
Far pointer to private data area you provided in your call to IG_dspl_document_print () and IG_dspl_document_print_custom ()functions
nImageNumber
A variable of type UINT in which you can keep track of the number of hIGear images just processed in the array of images
nPageNumber
A variable of type UINT in which you can keep track of the number of the page (of paper) being printed to

Description:

This function is called by IG_dspl_document_print (). You can use it to determine which image in the array of images has just been spooled to the printer. In addition, nPageNumber is the current page number being printed. This callback does not need to be "registered" by a call to an IG_...CB_register() function.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

This callback function returns TRUE if the image is successfully processed, and FALSE if it is not. As soon as the callback function returns FALSE, ImageGear stops processing the images.

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_LOAD_DISP

Group: Callback

Declaration:

typedef VOID (ACCUAPI LPFNIG_LOAD_DISP) (
    LPVOID lpPrivate,
    HIGEAR hIGear
);

Arguments:

lpPrivate
Far pointer to private data area you provided in your call to IG_load_file_display ()function
hIGear
HIGEAR handle assigned to the image just loaded

Description:

This function is called by IG_load_file_display () after it has loaded the image and assigned to it a HIGEAR handle, but before it has displayed the image.

Using the HIGEAR handle supplied to you in this call, you can set the image and device rectangles, set display attributes, and perform other operations you choose, prior to returning. Upon your return, IG_load_file_display() will continue and will display your image, line by line, using the settings you have made.

Bits Per Pixel: 1, 4, 8, 24

Return Value: None

Example:

See the Example code in the section Working with ImageGear Callback Functions.

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_MEM_ALLOC

Group: Callback

Declaration:

typedef LPBYTE (ACCUAPI LPFNIG_MEM_ALLOC)(AT_UINT nSize);

Arguments:

nSize
Number of bytes to allocate.

Description:

This callback function is registered by calling IG_mem_CB_register (). The register function must be called prior to any user-defined callback functions being used by the ImageGear library. Create a function of this type to give your application the flexibility of replacing ImageGear's memory allocation routine with your own.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

The user supplied callback function should return a pointer to the allocated block of memory.

Example:

/
**************************************************************/
/* Memory Alloc callback function definition */
/*************************************************************/
LPBYTE  ACCUAPI MyMemAlloc(AT_UINT nSize) /* number of bytes to
alloc*/
{
    /* Put your own memory allocation code here */
    return( buffer);
};
/*See also example for IG_mem_CB_register() */
NOTE: Your memory allocation function will only be used when large allocations (allocations greater than 1024) are performed.

Sample: FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_MEM_FREE

Group: Callback

Declaration:

typedef LPBYTE (ACCUAPI LPFNIG_MEM_FREE) ( LPBYTE lpBuffer);

Arguments:

lpBuffer
Far pointer to the buffer to be freed.

Description:

This callback function is registered by calling IG_mem_CB_register (). The register function must be called prior to any user-defined callback functions being used by the ImageGear library. Create a function of this type to give your application the flexibility of replacing ImageGear's memory free routine with your own.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Usually NULL.

Example:

/*************************************************************/
/* Memory Free callback function definition       */
*************************************************************/
LPBYTE  ACCUAPI MyMemFree( LPBYTE lpBuffer)
{
    /*MEMORY FREE CODE*/
    return NULL;
};
/*See also example for IG_mem_CB_register() */

Sample: FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_MEM_REALLOC

Group: Callback

Declaration:

typedef LPBYTE (ACCUAPI LPFNIG_MEM_REALLOC) (
    LPBYTE lpBuffer,
    AT_UINT nSize
);

Arguments:

lpBuffer
Far pointer to the buffer to be reallocated.
nSize
New byte count for realloc buffer.

Description:

This callback function is registered by calling IG_mem_CB_register (). The register function must be called prior to any user-defined callback functions being used by the ImageGear library. Create a function of this type to give your application the flexibility of replacing ImageGear's memory reallocation routine with your own.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

The user supplied callback function should return a pointer to the allocated block of memory.

Example:

***********************************************************/
/* Memory ReAlloc callback function definition        */
***********************************************************/
LPBYTE ACCUAPI MyMemReAlloc( LPBYTE lpbuffer, AT_UINT nSize)
{
    /* Put your memory reallocation code here */
    return( lpBuffer);
};
/*See also example for IG_mem_CB_register() */

Sample: FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_MPCB_UPDATE

Group: Callback

Please see the description for this function in the description of function IG_mpi_CB_set ().


LPFNIG_PROCESS_PIXEL

Group: Callback

Declaration:

typedef AT_VOID (LPACCUAPI LPFNIG_PROCESS_PIXEL)(
    AT_INT bitsPerChannel,
    AT_INT channelCount,
    LPAT_VOID processData,
    LPAT_PIXEL pixel
);

Arguments:

bitsPerChannel
Number of bits per channel used to store the pixel being checked.
channelCount
Number of channels in the pixel being checked.
processData
User-defined data passed to calling function (for example, processStruct parameter of IG_IP_process_area).
pixel
Pointer to the pixel to be processed.

Description:

This callback processes the given pixel.

Return Value:

None


LPFNIG_RASTER_GET

Group: Callback

Declaration:

typedef AT_ERRCOUNT (ACCUAPI LPFNIG_RASTER_GET) (
    LPVOID lpPrivate,
    LPAT_PIXEL lpRast,
    AT_PIXPOS cyPos,
    DWORD cRasterSize
);

Arguments:

lpPrivate
Far pointer to private data area
lpRast
Far pointer to first byte of raster your function is providing
cyPos
The raster's Y position in the image (0 = top line of image)
dwRasterSize
Number of bytes in the raster

Description:

This is one of the two types of callback function supplied in calls to IG_save_FD_CB_ex () or IG_save_mem_CB_ex ()functions. It is called by ImageGear to obtain from your application each raster to be saved. The line's position in the image is identified by cyPos. The lines may not be in order.

lpRast is a pointer to the start of your raster, and dwRasterSize is the number of bytes in the line. ImageGear will compress the line for you as it saves it, according to the compression scheme specified in your original call to save the image. lpPrivate points to the private data area supplied in that call.

NOTE: You should check the ImageGear error count (AT_ERRCOUNT) after each raster is read. If you need to terminate the load, you can place an error on the stack yourself, using IG_error_set(). See the description for that function .

Bits Per Pixel: N/A

Return Value:

Return an error count.

Example:

AT_ERRCOUNT  ACCUAPI MyRasterGet (LPVOID lpPrivate, LPAT_PIXEL
lpRast, AT_PIXPOS lYpos, DWORD dwBytes ){
/* Provide raster row lYpos, by storing it where LPAT_PIXEL
points.
   Should be exactly dwBytes, counting padding. */
 ...
return IG_error_check();
}

Sample: LoadCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_RASTER_SET

Group: Callback

Declaration:

typedef AT_ERRCOUNT (ACCUAPI LPFNIG_RASTER_SET) (
    LPVOID lpPrivate,
    const LPAT_PIXEL lpRast,
    AT_PIXPOS cyPos,
    DWORD cRasterSize
);

Arguments:

lpPrivate
Far pointer to private data area
lpRast
Far pointer to first byte of raster that ImageGear is providing on this call
cyPos
The raster's Y position in the image (0 = top line of image)
dwRasterSize
Number of bytes in the raster

Description:

This is one of the two types of callback function supplied in calls to IG_load_FD_CB () or IG_load_mem_CB ()functions. This function is called by ImageGear to provide to your application each raster as it is obtained from the file. The line's position in the image is identified by cyPos. The lines may not be in order.

lpRast is a pointer to the start of the raster, and dwRasterSize is the number of bytes in the line. You should not attempt to change the data at lpRast. In general, your application will use this data (along with its knowledge of the width of the image it is creating, any compression scheme, etc.) to create the appropriate raster for the image bitmap of the DIB your application is creating.

NOTE: See also callback type LPFNIG_DIB_CREATE.
NOTE: You should check the ImageGear error count (AT_ERRCOUNT) after each raster is read. If you need to terminate the load, you can place an error on the stack yourself, using IG_error_set(). See the description for that function.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Return an error count.

Example:

AT_ERRCOUNT ACCUAPI MyRasterSet (LPVOID lpPrivate, LPAT_PIXEL
lpRast, AT_PIXPOS lYpos, DWORD dwBytes )
{
/* Can use the above information to create a raster or rasters
in image bitmap of DIB that was created by LPFNIG_DIB_CREATE
callback.     */
 ...
return IG_error_check();
}

Sample: LoadCB

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_READ

Group: Callback

Declaration:

typedef LONG (ACCUAPI LPFNIG_READ) (
    LONG fd,
    LPBYTE lpBuffer,
    LONG lSize
);

Arguments:

fd
File Descriptor handle
lpBuffer
Far pointer to buffer into which to read data
lSize
Number of bytes to read

Description:

This type of function is established by calling IG_file_IO_register ()function. It will be called during file operations when a READ is required.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Return the number of bytes read, or -1 to indicate that an error occurred.

Example:

See the example for function IG_file_IO_register ().

Sample: IOSET

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_SEEK

Group: Callback

Declaration:

typedef AT_INT(ACCUAPI LPFNIG_SEEK) (
    AT_INT fd,
    AT_INT lOffset,
    INT nFlag
);

Arguments:

fd
File Descriptor handle
lOffset
Offset to seek to
nFlag
0 = seek from start, 1 = seek from current position, 2 = seek from end

Description:

This type of function is established by calling IG_file_IO_register (). It will be called during file operations when a SEEK is required. This function should return the offset into the file after the seek has completed, or -1 to indicate that an error occurred.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Return offset into file at the completion of the seek, or -1 to indicate an error occurred.

Example:

HIGEAR        hIGear;       /* HIGEAR handle of image */
LPFNIG_READ   MyReadFunc;    /* To be called for READs */
LPFNIG_WRITE  MyWriteFunc;   /* To be called for WRITEs */
LPFNIG_SEEK   MySeekFunc;    /* To be called for SEEKs  */
{
/* Register Read, Write, and Seek callback functions:   */
IG_file_IO_register ( MyReadFunc, MyWriteFunc, MySeekFunc );
 ...
IG_save_file ( hIGear, "picture.bmp", IG_SAVE_BMP_UNCOMP );
 ...
}
/* This will be called for each seek during the above Save:  */
LONG ACCUAPI  MySeekFunc ( AT_INT fd, AT_INT lOffset, INT nFlag
)
{
AT_INT	 nResultOffset;
 ...
return  nResultOffset;
}

Sample: IOSET

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_SIZE_CHANGE

Group: Callback

Declaration:

typedef LONG (LPACCUAPI LPFNIG_SIZE_CHANGE)(
    AT_INT fd,
    AT_INT lSize
);

Arguments:

fd
Descriptor ID, from open
lSize
New size of file in bytes

Description:

This type of function is established by calling IG_file_IO_register (). It will be called during file operations when a change of file size is required.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Returns the new size of the file, or -1 to indicate that an error occurred.


LPFNIG_STATUS_BAR

Group: Callback

Declaration:

typedef BOOL (ACCUAPI LPFNIG_STATUS_BAR) (
    LPVOID lpPrivate,
    AT_PIXPOS cyPos,
    AT_DIMENSION dwHeight
);

Arguments:

lpPrivate
Far pointer to private data area, as specified in your call to IG_status_bar_CB_register ()function.
cyPos
Y position in the image of this raster (row). Calls for the rows are not guaranteed to be in a particular order.
dwHeight
Total number of rasters (rows) in the image

Description:

This is the type of the callback function you specify in calling IG_status_bar_CB_register().

This callback function is called once for each raster (row) in the image. The calls will not necessarily be in row order. See also the description for function IG_status_bar_CB_register ().

Bits Per Pixel: N/A

Return Value:

Your LPFNIG_STATUS_BAR() callback function should return TRUE if ImageGear should continue the load, save, or print operation it is performing, or FALSE if ImageGear should terminate the operation, placing an IGE_INTERRUPTED_BY_USER error on the error stack.

Example:

BOOL ACCUAPI StatusBar(
   LPVOID            lpPrivate,    /* Private data passed in  */
   AT_PIXPOS            cyPos,     /* Y position in the image */
   AT_DIMENSION      dwHeight      /* Height of the image */
   );
  ...
    /* register the status bar callback function */
    err_count = IG_status_bar_CB_register(StatusBar, &si);
if (err_count == 0)
{
    fSBEnabled = TRUE;
    CheckMenuItem(GetMenu(
hWnd),ID_OPTIONS_PROGRESSBAR,MF_CHECKED);
}
            }
else
            {
   /* deregister SB function */
   /* deregister the status bar callback function */
   err_count = IG_status_bar_CB_register( NULL, NULL);
if (err_count == 0)
{
   fSBEnabled = FALSE;
   CheckMenuItem(GetMenu(
hWnd),ID_OPTIONS_PROGRESSBAR,MF_UNCHECKED);
}
            }
  ...

Sample: DISPLAY, IMG_PROC, POSTER, PRINT, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_TAG_GET

Group: Callback

Declaration:

typedef BOOL (ACCUAPI LPFNIG_TAG_GET) (
    LPVOID lpPrivate,
    AT_MODE nIGTag,
    LPAT_MODE lpDataType,
    LPVOID lpTagData,
    DWORD dwSize
);

Arguments:

lpPrivate
A far pointer to a private data area that can be used for anything you like. For example, you might store the HIGEAR handle of the image that is being loaded.
nIGTag
ImageGear supplies you with an IGTAG_ Tag ID constant from file Geartags.h, so that you will know which tag is currently being saved.
lpDataType
ImageGear supplies you with an IG_TAG_TYPE_ constant from file accucnst.h, specifying the data type for this tag (e.g., BYTE, LONG, FLOAT, etc.)
lpTagData
ImageGear supplies you with this pointer to a buffer, where you should store your data. If you read this field, you will find that it contains a default value. For example, the ImageGear default value for the Artist tag is "1996-97 AccuSoft Inc., All rights reserved."
dwSize
ImageGear tells you the size of tag data buffer, in bytes. This is your limit for the length of what you store to lpTagData.

Description:

This callback function is registered by calling IG_save_tag_CB_register (). When ImageGear is going to perform any save operation it will first check to see if you have registered any applicable callbacks. If you have registered a callback of type LPFNIG_TAG_GET, it will be called once for each "non-volatile" tag that is being written. ImageGear will not call your callback for what it terms "volatile" tags, so that you are unable to modify such tags. If you are writing a TIFF file and want to determine which tags you can write to (that is, which tags are non-volatile), please see the TIFF tags section of Geartags.h. This section is comprised of a list of constants for all registered TIFF tags and a 5-column key that gives you information about the read and write ability of each tag.

NOTE: See also the Note under TIFF File Format Reference, for an explanation of how to use the key.

While you may set the data of a non-volatile tag, your data must not exceed the length specified by dwSize. You must also use the proper data type, which you can check by reading the lpDataType parameter.

Your callback could contain a switch statement for each tag you would like to write to. Each case in the switch statement could check the ImageGear default setting of the tag and decide whether to change the data. Set your callback to TRUE if you want ImageGear to overwrite the data of a tag, FALSE if you want it to ignore your data. When you set the callback to FALSE, ImageGear will use its own default value for the current tag, but will still call your callback when it parses the next tag.

NOTE: Note also that some tags can be set only to a certain range of valid values. If your data is out of range for such tags, ImageGear will ignore your data.

If you would like to modify tag data as the image is being read in (for instance, you want it to be modified for display purposes), register a callback of type LPFNIG_TAG_SET.

If you would like to add your own user-defined tags to a TIFF file, register a callback of type LPFNIG_TAG_USER_GET. Your tags will be saved with the image when it is being saved.

NOTE: See also the discussion about Tag Callbacks in the section Working with ImageGear Callback Functions.

Bits Per Pixel: N/A

Return Value:

Returns TRUE if ImageGear should overwrite the default tag data with your data, or FALSE if ImageGear should ignore your data.

Example:

BOOL ACCUAPI TagGet(
   LPVOID         lpPrivate,     /* Private data passed in
*/
   AT_MODE        nIGTag,        /* Tag ID from geartags.h
*/
   LPAT_MODE      lpType,        /* Type of data lpTag points to
*/
   LPBYTE         lpTag,         /* Pointer to tag data
*/
   DWORD          dwSize         /* Size of tag data (bytes)
*/
   )
...
return TRUE; /* FALSE to terminate the save operation */
}
...
   IG_save_tag_CB_register( TagGet, TagUserGet,
(LPVOID)&dwPrivateFlags );
/* The following example may be used for writing additional
information into a GIF file: */
BOOL ACCUAPI GifCallbackTagGet(
    LPVOID 	lpPrivate,
    AT_MODE 	nIGTag,
    LPAT_MODE 	lpType,
    LPVOID 	lpData,
    DWORD 	dwSize
    )
{
    LPBYTE 	lpRGB;
    static INT i=0;
    switch(nIGTag)
    {
        case IGTAG_GIF_SCREEN_WIDTH:
            *(LPWORD)lpData=777;
            break;
        case IGTAG_GIF_SCREEN_FLAGS:
            *(LPBYTE)lpData=0x80 | 0x07;
            break;
        case IGTAG_GIF_IMAGE_FLAGS:
            *(LPBYTE)lpData=0x80 | 0x07;
            break;
        case IGTAG_GIF_IMAGE_LEFT:
            *(LPWORD)lpData=111;
            break;
        case IGTAG_GIF_SCREEN_PALETTE:
            lpRGB=(LPBYTE)lpData;
            for(i=0; i<256; i++)
            {
                lpRGB[3*i]=(BYTE)(0);
                lpRGB[3*i+1]=(BYTE)(i);
                lpRGB[3*i+2]=(BYTE)(0);
            }
            break;
        case IGTAG_GIF_IMAGE_PALETTE:
            lpRGB=(LPBYTE)lpData;
            for(i=0; i<256; i++)
            {
                lpRGB[3*i]=(BYTE)i;
                lpRGB[3*i+1]=(BYTE)(0);
                lpRGB[3*i+2]=(BYTE)(0);
            }
            break;
        case IGTAG_GIF_EXT_NUMBER_BEFORE_IMG:
            *(LPWORD)lpData=4;
            break;
        case IGTAG_GIF_EXT_BEFORE_IMG:
            switch(i++%4)
            {
                case 0:
                    CtrlExt.bLabel=CTRL_EXT_LABLE;
                    CtrlExt.bPacked=249;
                                {
                case 0:
                    CtrlExt.bLabel=CTRL_EXT_LABEL;
                    CtrlExt.bPacked=249;
                    CtrlExt.wDelayTime=555;
                    CtrlExt.bColorIndex=111;
                    *(LPVOID FAR*)lpData=(LPVOID)&CtrlExt;
                    break;
                case 1:
                    TextExt.bLabel=TEXT_EXT_LABEL;
                    TextExt.wTextGridLeft=333;
                    TextExt.lpData=lpStr;
                    *(LPVOID FAR*)lpData=(LPVOID)&TextExt;
                    break;
                case 2:
                    CommExt.bLabel=COMM_EXT_LABEL;
                    CommExt.lpData=lpStr;
                    *(LPVOID FAR*)lpData=(LPVOID)&CommExt;
                    break;
                case 3:
                    ApplExt.bLabel=APPL_EXT_LABEL;
                    strcpy((CHAR*)ApplExt.Identifier,
                        "Accusoft");
                    strcpy((CHAR*)ApplExt.AuthentCode, "6.0");
                    ApplExt.lpData=lpStr;
                    *(LPVOID FAR*)lpData=(LPVOID)&ApplExt;
                    break;
            }
            break;
    }

    return TRUE

Sample: JPEG, FILTER, FlashPix

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_TAG_SET

Group: Callback

Declaration:

typedef BOOL (ACCUAPI LPFNIG_TAG_SET) (
    LPVOID lpPrivate,
    AT_MODE nIGTag,
    AT_MODE nDataType,
    const LPVOID lpTagData,
    DWORD dwSize
);

Arguments:

lpPrivate
A far pointer to a private data area that can be used for anything you like
nIGTag
ImageGear supplies you with an IGTAG_ Tag ID constant from file Geartags.h, so that you will know which tag is currently being processed.
nDataType
ImageGear supplies you with an IG_TAG_TYPE_ constant from file accucnst.h, specifying the data type for this tag (e.g., BYTE, LONG, FLOAT, etc.)
lpTagData
ImageGear supplies you with a copy of the data from the tag currently being read
dwSize
ImageGear tells you the size of tag data, in bytes

Description:

This callback function is registered by calling IG_load_tag_CB_register ()function. When ImageGear is going to perform any load operation it will first check to see if you have registered any applicable callbacks. If you have registered a callback of type LPFNIG_TAG_SET, it will be called once for each tag (both volatile and non-volatile, see LPFNIG_TAG_GET) that is being parsed. ImageGear will not let you write data to any tag while loading.

If you would like to modify tag data as the image is being saved, register a callback of type LPFNIG_TAG_GET().

If you would like to add your own user-defined tags to a TIFF file, register a callback of type LPFNIG_USER_TAG_GET. Your tags will be saved with the image when it is being saved.

NOTE: See also the discussion about Tag Callbacks in the section Working with ImageGear Callback FunctionsThe HIGEAR for the image is not created until after all of the tags have been read in.
NOTE: If you need to store any tag data, make a copy of the data, not the lpTagData pointer.

Bits Per Pixel: N/A

Return Value:

Returns TRUE if ImageGear should overwrite the default tag data with your data, or FALSE if ImageGear should ignore your data.

Example:

BOOL ACCUAPI TagSet(
   LPVOID         lpPrivate,     /* Private data passed in
*/
   AT_MODE        nIGTag,        /* Tag ID from geartags.h
*/
   AT_MODE        nType,         /* Type of data in lpTag
*/
   const LPVOID   lpTag,         /* Pointer to tag data
*/
   DWORD          dwSize         /* Size of tag data (bytes)
*/
   )
...
return TRUE; /* FALSE to terminate the operation */
}
...
IG_load_tag_CB_register( TagSet, (LPVOID)&dwPrivateFlags );
...

The following example illustrates loading a GIF image.

Example:

/* Example of LPFNIG_TAG_SET type function, which may be used
during loading GIF image: 	*/
BOOL ACCUAPI GifCallbackTagSet(
    LPVOID 	lpPrivate,
    AT_MODE	 nIGTag,
    AT_MODE	 nDataType,
    LPVOID 	lpData,
    DWORD 	dwDataLen
{
    WORD 	wWidth;
    WORD 	wLeft;
    WORD 	wExtNumber;
    LPBYTE			lpRGB;
    LPAT_GIF_CTRL_EXT lpCtrlExt;
    LPAT_GIF_TEXT_EXT lpTextExt;
    LPAT_GIF_COMM_EXT lpCommExt;
    LPAT_GIF_APPL_EXT lpApplExt;
    LPVOID			lpExt;
/* Following code illustrates how to get GIF file information								*/
/* Parameter nIGTag in this function informs about kind of data
on which points lpData.    */
/* If GIF image is loaded this parameter may be equal to
IGTAG_GIF_ constants, defined in  */
/* file \ACCUSOFT\GEAR\SOURCE\INCLUDE\geartags.h. For example,
when IGTag is equal to*/
/* IGTAG_GIF_SCREEN_ASPECT lpData must point (after conversion)
to BYTE - bAspectRatio field */
/* of GIF_SCREEN_DESC structure. Analogously for other
IGTAG_GIF_ constants.*/
/* IGTAG_GIF_SCREEN_BG_COLOR - for getting or setting screen
background color index*/
/* - lpData points to BYTE, */
/* 1.When GIF image is loaded: lpData points to GIF Extention
Block structure*/
/* 2.When GIF image is written: lpData must points to LPVOID,
which points to created by user*/
/* GIF Extention Block structure. This structure must exist all
time when image is written.   */
/* IGTAG_GIF_EXT_AFTER_IMG - Analogously as for
IGTAG_GIF_EXT_BEFORE_IMG*/
    switch(nIGTag)
    {
        case IGTAG_GIF_SCREEN_WIDTH:
            wWidth=*(LPWORD)lpData;
            break;
        case IGTAG_GIF_IMAGE_LEFT:
            wLeft=*(LPWORD)lpData;
            break;
        case IGTAG_GIF_SCREEN_PALETTE:
            lpRGB=(LPBYTE)lpData;
            break;
        case IGTAG_GIF_IMAGE_PALETTE:
            lpRGB=(LPBYTE)lpData;
            break;
        case IGTAG_GIF_EXT_NUMBER_BEFORE_IMG:
            wExtNumber=*(LPWORD)lpData;
            break;
        case IGTAG_GIF_EXT_BEFORE_IMG:
            lpExt=lpData;
            switch(*(LPDWORD)lpExt)
            {
                case CTRL_EXT_LABLE:
                    lpCtrlExt=(LPAT_GIF_CTRL_EXT)lpExt;
                    break;
                case TEXT_EXT_LABLE:
                    lpTextExt=(LPAT_GIF_TEXT_EXT)lpExt;
                    break;
                case COMM_EXT_LABLE:
                    lpCommExt=(LPAT_GIF_COMM_EXT)lpExt;
                    break;
                case APPL_EXT_LABLE:
                    lpApplExt=(LPAT_GIF_APPL_EXT)lpExt;
                    break;
            }
            break;
        case IGTAG_GIF_EXT_NUMBER_AFTER_IMG:
            wExtNumber=*(LPWORD)lpData;
            break;
        case IGTAG_GIF_EXT_AFTER_IMG:
            lpExt=lpData;
            switch(*(LPDWORD)lpExt)
            {
                case CTRL_EXT_LABLE:
                    lpCtrlExt=(LPAT_GIF_CTRL_EXT)lpExt;
                    break;
                case TEXT_EXT_LABLE:
                    lpTextExt=(LPAT_GIF_TEXT_EXT)lpExt;
                    break;
                case COMM_EXT_LABLE:
                    lpCommExt=(LPAT_GIF_COMM_EXT)lpExt;
                    break;
                case APPL_EXT_LABLE:
                    lpApplExt=(LPAT_GIF_APPL_EXT)lpExt;
                    break;
            }
            break;
    }

    return TRUE

Sample: JPEG, FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_TAG_USER_GET

Group: Callback

Declaration:

typedef BOOL (ACCUAPI LPFNIG_TAG_USER_GET) (
    LPVOID lpPrivate,
    LPAT_MODE lpUserTag,
    LPAT_MODE lpDataType,
    LPVOID32 FAR *lpTagData,
    LPDWORD lpSize
);

Arguments:

lpPrivate
Far pointer to private data area, which can be used for anything you like, including the storage of the image's HIGEAR handle.
lpIGTag
Far pointer to an AT_MODE variable to receive a private tag number. Your value must be 32768 or higher.
lpDataType
Set to an IG_TAG_TYPE_ constant (these are listed in file accucnst.h) specifying the data type for this tag
lpTagData
Return a pointer to your data
lpSize
Tell ImageGear the size of your data

Description:

This function allows you to store a private TIFF tag with the image being saved. This callback function is registered by calling IG_save_tag_CB_register (). In this callback, you supply a tag number, tag type, and tag data. Note that the value of your private tag number must be higher than 32768.

When ImageGear is going to save a file it will check to see if you have registered any applicable callbacks. If you have registered a callback of type LPFNIG_USER_TAG_GET(), it will be called until you set it to FALSE. While your callback is still set to TRUE, it will add your user-defined tags one at a time to the TIFF image being saved.

lpIGTag is a far pointer to an AT_MODE in which you store a privately defined tag ID#. lpDataType is a pointer to your Tag data type, lpTagData is a pointer to your tag data, and lpSize is the length of your tag data.

This callback function should return TRUE when supplying a tag, in which case it will be called again. Return FALSE when you are done supplying tags. This callback will be called at least once if it has been registered.

Bits Per Pixel: N/A

Return Value:

Return TRUE if returning a tag, in which case this callback function will be called again in case you have more tags to supply. Return FALSE if you are not returning a tag and are done returning tags.

Example:

BOOL ACCUAPI TagUserGet(
   LPVOID         lpPrivate,     /* Private data passed in */
   LPAT_MODE      lpnIGTag,        /* Tag ID from geartags.h */
   LPAT_MODE      lpType,        /* Type of data lpTag points to
*/
   LPVOID  FAR*   lpTag,         /* Pointer to tag data */
   LPDWORD        lpSize         /* Size of tag data (bytes) */
   )
/* set Tag ID, data type, length, and pointer to your data */
{
   *lpSize = 0;
   if( (*lpnIGTag>=IGTAG_JPG_APPDATA) &&
(*lpnIGTag<=IGTAG_JPG_APPDATA_LAST) )
    {
if( (*lpnIGTag-IGTAG_JPG_APPDATA)==12	)	/* supplying only APP13
marker	*/
        {
/* supply application marker data */
            *lpType = IG_TAG_TYPE_RAWBYTES;
            *lpTag = (LPVOID)(&TestData[0]);
            *lpSize = sizeof(TestData);
            return	TRUE;
        }
/* FALSE when no tag being returned */
    }
                      return	FALSE;
}
...
IG_save_tag_CB_register( TagGet, TagUserGet,
(LPVOID)&dwPrivateFlags );
...

Sample: JPEG

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


LPFNIG_WRITE

Group: Callback

Declaration:

typedef LONG (ACCUAPI LPFNIG_WRITE) (
    LONG fd,
    const LPBYTE lpBuffer,
    LONG lSize
);

Arguments:

fd
File Descriptor handle
lpBuffer
Far pointer to buffer to write from
lSize
Number of bytes to write

Description:

This type of function is established by calling IG_file_IO_register (). It will be called during file operations when a WRITE is required.

Bits Per Pixel: 1, 4, 8, 24

Return Value:

Return the number of bytes written, or -1 to indicate that an error occurred.

Example:

HIGEAR       hIGear;        /* HIGEAR handle of image */
LPFNIG_WRITE  MyWriteFunc; /* To be called for file WRITEs */
{
IG_file_IO_register ( NULL, MyWriteFunc, NULL );    /* Register
it */
 ...
IG_save_file ( hIGear, "picture.bmp", IG_SAVE_BMP_UNCOMP );
 ...
}
/* This will be called for each write during the above Save:  */
LONG ACCUAPI  MyWriteFunc ( LONG fd, LPBYTE lpBuffer, LONG
lNumToWrite )
{
LONG	 nNumActuallyWritten;
 ...
return  nNumActuallyWritten; /* Return count, or -1 for error
*/

Sample: IOSET

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


Core Component Enumerations

The ImageGear Core Component has the following enumerations:

enumColorProfileGroups
enumIGAlphaChannelType
enumIGBatchOptions
enumIGBiCompression
enumIGBitonalReductModes
enumIGBlendModes
enumIGBlurModes
enumIGColorChannels
enumIGColorSpaceIDs
enumIGColorSpaces
enumIGCompressions
enumIGContrastModes
enumIGConversionCommands
enumIGConversionOptions
enumIGConvolutionResults
enumIGDepthChangeMode
enumIGDIBExportFormats
enumIGDirections
enumIGDsplAliasModes
enumIGDsplAlignModes
enumIGDsplAspectModes
enumIGDsplBackgroundModes
enumIGDsplContrastFlags
enumIGDsplConvModes
enumIGDsplDitheringModes
enumIGDsplFitModes
enumIGDsplMapModes
enumIGDsplPaletteModes
enumIGDsplScrollBarModes
enumIGDsplScrollType
enumIGDsplTranspModes
enumIGDsplZoomModes
enumIGEdgeDetectionMethods
enumIGEdgeMapMethods
enumIGErrorCodes
enumIGExtraChannelColorType
enumIGExtraChannelType
enumIGFillOrder
enumIGFlipModes
enumIGFltrFormatFlags
enumIGFormats
enumIGFrameModes
enumIGHTTPVerbs
enumIGImageChannelType
enumIGInetServices
enumIGInterpolations
enumIGIPShearFillStyle
enumIGLayerType
enumIGLicenseType
enumIGMaskChannelModes
enumIGMergeModes
enumIGMETADItemType
enumIGNoiseMethods
enumIGOrientationModes
enumIGPaletteFormats
enumIGPixelAccessType
enumIGPixelArrayType
enumIGPixelType
enumIGPromotionModes
enumIGResampleInModes
enumIGResampleOutModes
enumIGResizeModes
enumIGResolutionUnits
enumIGROIType
enumIGRotationModes
enumIGRotationValues
enumIGSaveFormats
enumIGShapeType
enumIGSpotColorVendorIDs
enumIGSysDataType
enumIGTwistModes
enumIGWipeStyles


enumColorProfileGroups

Group: Enumeration

Description:

Identifies a color profile group of the requested color profile.

Values:

IG_CP_GRP_WORKING
WCP (Working Color Profile). This group of color profiles provides information about the default color global parameters used to represent the color data for HIGEAR objects. Those global parameters are used if the image does not have a local color profile associated with it.
IG_CP_GRP_IMPORT
ICP (Import Color Profile). This group of profiles is used during a filter load operation.
IG_CP_GRP_EXPORT
ECP (Export Color Profile). This group of profiles is very similar to ICP but is used in the filter export operation.


enumIGAlphaChannelType

Group: Enumeration

Description:

This enumeration specifies what bit depth an alpha channel should have.

Values:

IG_ALPHA_CREATE_1
1 Bit
IG_ALPHA_CREATE_8
8 Bits


enumIGBatchOptions

Group: Enumeration

Description:

Identifies the options for batch conversion.

Values:

IG_BATCH_MP_TO_MP
Converts multipage file to multipage if the format supports this
IG_BATCH_RECURSIVE
Recursive convertion
IG_BATCH_USE_SRC_NAME
Converts file using its src name


enumIGBiCompression

Group: Enumeration

Description:

Identifies the different compression schemes used for storing image in memory.

Values:

IG_BI_RGB
Standard RGB uncompressed image
IG_BI_RLE
RLE compressed 1-bit image
IG_BI_CMYK
CMYK uncompressed image
IG_BI_GRAYSCALE
9-16 bit grayscale uncompressed image


enumIGBitonalReductModes

Group: Enumeration

Description:

This enumeration specifies types of bitonal color reduction.

Values:

IG_REDUCE_BITONAL_GRAYSCALE
grayscale
IG_REDUCE_BITONAL_AVE
AVE
IG_REDUCE_BITONAL_WEIGHTED
Weighted


enumIGBlendModes

Group: Enumeration

Description:

This enumeration specifies types of blending of two images.

Values:

IG_BLEND_OVER
Blend the first image over the second image
IG_BLEND_IN
Blend the first image into the second image
IG_BLEND_HELD_OUT
The first image is held out by the second image
IG_BLEND_LINEAR
The first and second images are combined in a linear fashion


enumIGBlurModes

Group: Enumeration

Description:

This enumeration contains blur kernel sizes.

Values:

IG_BLUR_3
Kernel size 3
IG_BLUR_5
Kernel size 5


enumIGColorChannels

Group: Enumeration

Description:

Contains the different color components (channels).

Values:

IG_COLOR_COMP_ALL
All components
IG_COLOR_COMP_R
R component of RGB image
IG_COLOR_COMP_G
G component of RGB image
IG_COLOR_COMP_B
B component of RGB image
IG_COLOR_COMP_RGB
R, G and B components of RGB image
IG_COLOR_COMP_I
Used when the ave of RGB is to be used
IG_COLOR_COMP_C
C component of CMYK image
IG_COLOR_COMP_M
M component of CMYK image
IG_COLOR_COMP_Y
Y component of CMYK image
IG_COLOR_COMP_K
K component of CMYK image
IG_COLOR_COMP_CMYK
C, M, Y and K components of CMYK image
IG_COLOR_COMP_YUV_Y
Y component of YUV image
IG_COLOR_COMP_YUV_U
U component of YUV image
IG_COLOR_COMP_YUV_V
V component of YUV image
IG_COLOR_COMP_YUV
Y, U and V components of YUV image


enumIGColorSpaceIDs

Group: Enumeration

Description:

Identifies a color space ID. This ID is a bit field which can combine multiple values from enumIGColorSpaceIDs. It can be made up of one, two, or three components. It must describe the color space (RGB, CMYK, grayscale, etc). It may also indicate that a type of alpha channel is present (alpha, pre-multiplied alpha) and/or the presence of one or more extra channels. For example:

IG_COLOR_SPACE_ID_RGB - RGB with no alpha or extra channels.

IG_COLOR_SPACE_ID_Gy Or IG_COLOR_SPACE_ID_A - grayscale with an alpha channel.

IG_COLOR_SPACE_ID_RGB Or IG_COLOR_SPACE_ID_P Or IG_COLOR_SPACE_ID_Ex - RGB with a pre-multiplied alpha channel and one or more extra channels.

Values:

IG_COLOR_SPACE_ID_None
No regular (color) channels, can be combined with alpha and extra values
IG_COLOR_SPACE_ID_RGB
RGB
IG_COLOR_SPACE_ID_Gy
Grayscale (intensity)
IG_COLOR_SPACE_ID_I
Indexed RGB
IG_COLOR_SPACE_ID_IHS
IHS
IG_COLOR_SPACE_ID_HLS
HLS
IG_COLOR_SPACE_ID_LAB
LAB
IG_COLOR_SPACE_ID_YIQ
YIQ
IG_COLOR_SPACE_ID_CMY
CMY
IG_COLOR_SPACE_ID_CMYK
CMYK
IG_COLOR_SPACE_ID_YCbCr
YCbCr
IG_COLOR_SPACE_ID_YUV
YUV
IG_COLOR_SPACE_ID_XYZ
CIE XYZ
IG_COLOR_SPACE_ID_LAST
Equal to last color space (for color channels) enum value
IG_COLOR_SPACE_ID_ColorMask
Bit mask used to access color space (for color channels) only
IG_COLOR_SPACE_ID_A
Indicates presence of an alpha channel
IG_COLOR_SPACE_ID_P
Indicates presence of a pre-multiplied alpha channel
IG_COLOR_SPACE_ID_Ex
Indicates presence of one or more extra channels
IG_COLOR_SPACE_ID_RGBA
RGB with alpha channel
IG_COLOR_SPACE_ID_RGBPA
RGB with pre-multiplied alpha channel
IG_COLOR_SPACE_ID_GyA
Intensity with alpha channel
IG_COLOR_SPACE_ID_GyPA
Intensity with pre-multiplied alpha channel
IG_COLOR_SPACE_ID_RGBAEx
RGB with alpha and extra channels
IG_COLOR_SPACE_ID_RGBPAEx
RGB with pre-multiplied alpha and extra channels
IG_COLOR_SPACE_ID_Unknown
Unknown - no color or alpha channels, only extra channels are present


enumIGColorSpaces

Group: Enumeration

Description:

Identifies the different color spaces.

Values:

IG_COLOR_SPACE_RGB
RGB
IG_COLOR_SPACE_I
Intensity
IG_COLOR_SPACE_IHS
IHS
IG_COLOR_SPACE_HLS
HLS
IG_COLOR_SPACE_Lab
Lab
IG_COLOR_SPACE_YIQ
YIQ
IG_COLOR_SPACE_CMY
CMY
IG_COLOR_SPACE_CMYK
CMYK
IG_COLOR_SPACE_YCrCb
YCrCb
IG_COLOR_SPACE_YUV
YUV
IG_COLOR_SPACE_MONO
FlashPix only: 8-bit grayscale
IG_COLOR_SPACE_ALPHA
FlashPix only: 8-bit alpha
IG_COLOR_SPACE_MA
FlashPix only: 16-bit: mono + alpha
IG_COLOR_SPACE_AM
FlashPix only: 16-bit: alpha + mono
IG_COLOR_SPACE_RGBA
FlashPix only: 32-bit: RGB + alpha
IG_COLOR_SPACE_ARGB
FlashPix only: 32-bit: alpha + RGB
IG_COLOR_SPACE_YCC
FlashPix only: 24-bit: photoYCC
IG_COLOR_SPACE_YCCA
FlashPix only: 32-bit: photoYCC + alpha
IG_COLOR_SPACE_AYCC
FlashPix only: 32-bit: alpha + photoYCC
IG_COLOR_SPACE_UNKNOWN
FlashPix only: unknown or invalid colorspace
IG_COLOR_SPACE_NOCHANGE
FlashPix only: current colorspace


enumIGCompressions

Group: Enumeration

Description:

Identifies the different format compression schemes.

Values:

IG_COMPRESSION_NONE
No compression
IG_COMPRESSION_PACKED_BITS
Packed bits compression
IG_COMPRESSION_HUFFMAN
Huffman encoding
IG_COMPRESSION_CCITT_G3
CCITT Group 3
IG_COMPRESSION_CCITT_G4
CCITT Group 4
IG_COMPRESSION_CCITT_G32D
CCITT Group 3 2D
IG_COMPRESSION_JPEG
JPEG compression
IG_COMPRESSION_RLE
Run length encoding
IG_COMPRESSION_LZW
LZW compression
IG_COMPRESSION_ABIC_BW
IBM ABIC compression
IG_COMPRESSION_ABIC_GRAY
IBM ABIC compression
IG_COMPRESSION_JBIG
IBM JBIG compression
IG_COMPRESSION_FPX_SINCOLOR
single color compression
IG_COMPRESSION_FPX_NOCHANGE
save with the same compression as loaded
IG_COMPRESSION_DEFLATE
IG_COMPRESSION_IBM_MMR
IG_COMPRESSION_ABIC
IBM ABIC compression
IG_COMPRESSION_PROGRESSIVE
Progressive compression ( Progressive JPEG and may be PNG in future )
IG_COMPRESSION_EQPC
PowerSDK EQPC(Wavelet) compression
IG_COMPRESSION_JBIG2
JBIG2 compression
IG_COMPRESSION_LURAWAVE
Wavelet compression (LuraWave)
IG_COMPRESSION_LURADOC
Document compression (LuraDoc)
IG_COMPRESSION_LURAJP2
Lura JPEG2000 compression
IG_COMPRESSION_ASCII
Image data is converted to ASCII text
IG_COMPRESSION_RAW
Imagedata is stored directory in binary raw format
IG_COMPRESSION_JPEG2K


enumIGContrastModes

Group: Enumeration

Description:

This enumeration specifies types of contrast adjustment.

Values:

IG_CONTRAST_PALETTE
Altering image palette
IG_CONTRAST_PIXEL
Altering image pixels


enumIGConversionCommands

Group: Enumeration

Description:

Identifies the commands for file conversion

Values:

IG_CONVERT_NONE
convert with no processing
IG_CONVERT_ROTATE_90
convert with rotating to 90 degrees
IG_CONVERT_ROTATE_180
convert with rotating to 180 degrees
IG_CONVERT_ROTATE_270
convert with rotating to 270 degrees
IG_CONVERT_FLIP_HORIZONTAL
convert with flipping horizontal
IG_CONVERT_FLIP_VERTICAL
convert with flipping vertical
IG_CONVERT_TRANSPOSE
convert and transpose
IG_CONVERT_TRANSVERSE
convert and transverse


enumIGConversionOptions

Group: Enumeration

Description:

Identifies the options for file conversion.

Values:

IG_CONVERT_OPTION_TRIM
Trims result image dimensions to a multiple of DCT size


enumIGConvolutionResults

Group: Enumeration

Description:

This enumeration specifies types of convolution result.

Values:

IG_CONV_RESULT_RAW
The result is stored as is
IG_CONV_RESULT_ABS
The absolute value of the signed result is stored
IG_CONV_RESULT_8BIT_SIGNED
The result is stored as 8-bit signed values
IG_CONV_RESULT_SIGN_CENTERED
The result is stored as 8-bit signed, but 0 is equal to 0x7F. Positive numbers are from 0x7E to 0x00. Negative numbers are from 0x80 to 0xFF. This is used for images that are to be used as background tiles or watermarks.


enumIGDepthChangeMode

Group: Enumeration

Description:

Identifies modes used for changing channel depths of an image. This is used by the method IGPage.ChannelDepthsChange.

Values:

IG_DEPTH_CHANGE_NO_SCALE
Changes channel depth without scaling of channel values. This results in unchanged channel values (if the new depth is large enough to accomodate the values). The image will likely change in appearance using this option.
IG_DEPTH_CHANGE_SCALE
Changes channel depth with scaling of channel values. This causes channel values to be scaled so that the ratio of new channel value to new channel depth is as close as possible to the ratio of old channel value to old channel depth. The image will likely maintain the same appearance using this option, unless channel depths are reduced too much to maintain accuracy.


enumIGDIBExportFormats

Group: Enumeration

Description:

Identifies DIB format to be used for a DIB export operation.

Values:

IG_DIB_EXPORT_FORMAT_WINDOWS
Export DIB in standard Windows DIB format. 9-16bpp grayscale images cannot be exported in this format. CMYK images will be exported as 24bpp RGB.
IG_DIB_EXPORT_FORMAT_IG_LEGACY
Export DIB in ImageGear legacy format. In this format, DIB compression can be IG_BI_GRAYSCALE for 9-16bpp grayscale, in which case the DIB bit depth will be the actual bit depth from 9 to 16. Also, DIB compression can be IG_BI_CMYK for CMYK images, in which case the DIB bit depth will be 32.


enumIGDirections

Group: Enumeration

Description:

This enumeration contains general purpose compass directions.

Values:

IG_COMPASS_N
North
IG_COMPASS_NE
North-East
IG_COMPASS_E
East
IG_COMPASS_SE
South-East
IG_COMPASS_S
South
IG_COMPASS_SW
South-West
IG_COMPASS_W
West
IG_COMPASS_NW
North-West


enumIGDsplAliasModes

Group: Enumeration

Description:

Identifies the different types of image aliasing. Applicable only if an 1-bit per pixel image is to be drawn and only if the destination image has a lower resolution then the original one.

Values:

IG_DSPL_ANTIALIAS_NONE
Anti-aliasing is not used
IG_DSPL_ANTIALIAS_SCALE_TO_GRAY
The scale to gray algorithm is used and the output image becomes 4 bits per pixel
IG_DSPL_ANTIALIAS_PRESERVE_BLACK
This mode directs ImageGear to preserve black pixels while drawing
IG_DSPL_ANTIALIAS_PRESERVE_WHITE
This mode directs ImageGear to preserve white pixels while drawing
IG_DSPL_ANTIALIAS_SUBSAMPLE
This flag directs ImageGear to use sub-sampling during anti-alias scaling. The output quality is higher and the display speed is considerably faster


enumIGDsplAlignModes

Group: Enumeration

Description:

Identifies the different types of image display allignment modes, i.e. identifies how the displayed image is aligned relative to the device rectangle.

Values:

IG_DSPL_ALIGN_X_LEFT
The image is aligned to the left border of the device rectangle
IG_DSPL_ALIGN_X_CENTER
The image is centered horizontally
IG_DSPL_ALIGN_X_RIGHT
The image is aligned to the right border of the device rectangle
IG_DSPL_ALIGN_Y_LEFT
The image is aligned to the top border of the device rectangle
IG_DSPL_ALIGN_Y_CENTER
The image is centered vertically
IG_DSPL_ALIGN_Y_RIGHT
The image is aligned to the bottom border of the device rectangle


enumIGDsplAspectModes

Group: Enumeration

Description:

Identifies the different types of image's display aspect ratio (i.e. width-to-height ratio).

Values:

IG_DSPL_ASPECT_FIXED
Aspect ratio is the one specified by Aspect Value parameter
IG_DSPL_ASPECT_NOT_FIXED
Aspect ratio is the one of the device rectangle


enumIGDsplBackgroundModes

Group: Enumeration

Description:

Identifies the different modes of image background drawing.

Values:

IG_DSPL_BACKGROUND_NONE
The background is disabled and IG does not fill this area
IG_DSPL_BACKGROUND_UNDER_IMAGE
The image's transparent pixels are drawn with current backgound color and backgound brush. The area outside of Displayed Image Rectangle is not affected
IG_DSPL_BACKGROUND_BEYOND_IMAGE
The transparent pixels that are outside of Displayed Image Rectangle are drawn with current background color and background brush


enumIGDsplContrastFlags

Group: Enumeration

Description:

Identifies the different color components of RGB color.

Values:

IG_DSPL_R_CHANNEL
Red color component
IG_DSPL_G_CHANNEL
Green color component
IG_DSPL_B_CHANNEL
Blue color component
IG_DSPL_ALL_CHANNELS
OR-ed combination of 3 flags above, identifies all 3 color components


enumIGDsplConvModes

Group: Enumeration

Description:

Identifies the coordinate translation methods.

Values:

IG_DSPL_CONV_IMAGE_TO_DEVICE
Converts coordinates from image coordintates to device ones
IG_DSPL_CONV_DEVICE_TO_IMAGE
Converts coordinates from device coordintates to image ones


enumIGDsplDitheringModes

Group: Enumeration

Description:

Identifies the different dithering types.

Values:

IG_DSPL_DITHER_AUTO
Destination device color resolution should be used for dithering. In this mode IG automatically applies dithering only when it is necessary
IG_DSPL_DITHER_TO_8BPP
Forces ImageGear to assume that the output device is 8 bits per pixel and perform the necessary dithering
IG_DSPL_DITHER_TO_4BPP
Forces ImageGear to assume that the output device is 4 bits per pixel and perform the necessary dithering
IG_DSPL_DITHER_TO_1BPP
Forces ImageGear to assume that the output device is 1 bit per pixel and perform the necessary dithering
IG_DSPL_DITHER_NONE
Disables ImageGear's dithering. In this mode dithering is performed by the operating system or the device driver
IG_DSPL_DITHER_FIXED_PALETTE
ImageGear will try to use the standard palette when performing dithering. This may be useful if the output device contains more than one image and by using this flag it is possible to draw images with the same palette
IG_DSPL_DITHER_NETSCAPE_PALETTE
Applicable only if the output device is 8 bits per pixel. It directs ImageGear to use the 216 entries of Netscape's palette.


enumIGDsplFitModes

Group: Enumeration

Description:

Identifies how an image fits to the device rectangle.

Values:

IG_DSPL_FIT_TO_DEVICE
The image is scaled to fit both the width and height of the device rectangle
IG_DSPL_FIT_TO_WIDTH
The image is scaled to fit the width of the device rectangle
IG_DSPL_FIT_TO_HEIGHT
The image is scaled to fit the height of the device rectangle
IG_DSPL_ACTUAL_SIZE
The device rectangle is ignored and the image is scaled 1:1


enumIGDsplMapModes

Group: Enumeration

Description:

Identifies the different mapping modes. The mapping mode defines the unit of measure used to convert logical units to device units. For mode details see MS SDK.

Values:

IG_DSPL_MM_TEXT
GDI MM_TEXT mode
IG_DSPL_MM_LOMETRIC
GDI MM_LOMETRIC mode
IG_DSPL_MM_HIMETRIC
GDI MM_HIMETRIC mode
IG_DSPL_MM_LOENGLISH
GDI MM_LOENGLISH mode
IG_DSPL_MM_HIENGLISH
GDI MM_HIENGLISH mode
IG_DSPL_MM_TWIPS
GDI MM_TWIPS mode
IG_DSPL_MM_ISOTROPIC
GDI MM_ISOTROPIC mode
IG_DSPL_MM_ANISOTROPIC
GDI MM_ANISOTROPIC mode


enumIGDsplPaletteModes

Group: Enumeration

Description:

Identifies the different modes of palette handling.

Values:

IG_DSPL_PALETTE_HIGH
Use the palette in the high priority mode. This means that the operating system palette manager will try to best map colors of DevicePalette to the system palette
IG_DSPL_PALETTE_LOW
Use the palette in the low priority mode. In this mode the palette manager will try to best preserve current view of the destination while drawing the new image on it
IG_DSPL_PALETTE_DISABLE
Not to implement DevicePalette in the destination device while drawing the image


enumIGDsplScrollBarModes

Group: Enumeration

Description:

Identifies the scroll bar display methods.

Values:

IG_DSPL_SB_AUTO
Automaticaly show and hide scroll bars when required accroding with image zoom
IG_DSPL_SB_ENABLED
Always show scroll bar
IG_DSPL_SB_DISABLED
Hide scrollbar


enumIGDsplScrollType

Group: Enumeration

Description:

Identifies the scroll bar type, horizontal or vertical.

Values:

IG_DSPL_SCROLL_HORIZ
Horizontal scrollbar
IG_DSPL_SCROLL_VERT
Vertical scrollbar


enumIGDsplTranspModes

Group: Enumeration

Description:

Identifies the different transparency modes.

Values:

IG_DSPL_TRANSPARENCY_NONE
Transparency is disabled
IG_DSPL_TRANSPARENCY_COLOR
Transparency color is enabled and the color's value assigned to the Transparency Color option is transparent while drawing the image
IG_DSPL_TRANSPARENCY_MASK
Transparency mask is enabled and the Transparency Mask option is used as the transparent bitmap
IG_DSPL_TRANSPMASK_STRETCH_TO_IMAGE
TranspMask image is resized and oriented along with the image being displayed (it is used when the transparency mask is enabled). If this flag is not set, the transparency mask is not scaled
IG_DSPL_TRANSPMASK_LOCATE_TO_IMAGE
Mask is calculated in the image-dependent coordinate system (it is used when the transparency mask is enabled). This means that the mask is oriented as the image is, and that the MaskLocation option is calculated from the original image's ImageRect
IG_DSPL_TRANSPMASK_LOCATE_TO_CLIPRECT
Locates the transparent mask relative to the ClipRect so that the MaskLocation is calculated from the rectangle's top left point (it is used when the transparency mask is enabled)
IG_DSPL_TRANSPMASK_LOCATE_ABSOLUTE
Locates the transparent mask on the output device so that the mask's top left point has the coordinates specified in the MaskLocation option (it is used when the transparency mask is enabled)


enumIGDsplZoomModes

Group: Enumeration

Description:

Identifies how the image is zoomed in the horizontal and vertical directions.

Values:

IG_DSPL_ZOOM_H_NOT_FIXED
This mode allows any horizontal zoom value
IG_DSPL_ZOOM_H_FIXED
Horizontal zoom factor is taken from Horizontal Zoom Value parameter
IG_DSPL_ZOOM_V_NOT_FIXED
This mode allows any vertical zoom value
IG_DSPL_ZOOM_V_FIXED
Vertical zoom factor is taken from the Vertical Zoom Value parameter


enumIGEdgeDetectionMethods

Group: Enumeration

Description:

These constants define the edge detection methods available.

Values:

IG_EDGE_DETECTION_MAXGRADIENT
Edge detection using the maxima of gradient, i.e., maxima of the first order derivative.
IG_EDGE_DETECTION_ZEROXC_DERIV2ND
Edge detection using the zero-crossings of second order derivative along the gradient.
IG_EDGE_DETECTION_DIFF_RECURSIVE
Edge detection using an optimal difference recursive filter.


enumIGEdgeMapMethods

Group: Enumeration

Description:

This enumeration specifies types of edge map operation.

Values:

IG_EDGE_OP_PREWITT
Prewitt
IG_EDGE_OP_ROBERTS
Roberts
IG_EDGE_OP_SOBEL
Sobel
IG_EDGE_OP_LAPLACIAN
Laplacian
IG_EDGE_OP_LOG
Laplacian of Gaussian
IG_EDGE_OP_HORIZONTAL
Horizontal
IG_EDGE_OP_VERTICAL
Vertical
IG_EDGE_OP_DIAG_POS_45
Diagonal positive
IG_EDGE_OP_DIAG_NEG_45
Diagonal negative


enumIGErrorCodes

Group: Enumeration

Description:

Identifies the different ImageGear error/warning codes.

Values:

Please see the Appendix A: Function Error Return Codes Appendix for the all ImageGear error/warning codes.


enumIGExtraChannelColorType

Group: Enumeration

Description:

This enumeration specifies extra channel's color type.

Declaration:

enum enumIGExtraChannelColorType
{
    IG_EXTRA_CHANNEL_COLOR_TYPE_Unknown,
    IG_EXTRA_CHANNEL_COLOR_TYPE_Colorspace,
    IG_EXTRA_CHANNEL_COLOR_TYPE_Vendor
};

Values:

IG_EXTRA_CHANNEL_COLOR_TYPE_Unknown
Unknown color type.
IG_EXTRA_CHANNEL_COLOR_TYPE_Colorspace
Regular color specified by color space and color value.
IG_EXTRA_CHANNEL_COLOR_TYPE_Vendor
Color specified by vendor and color IDs.


enumIGExtraChannelType

Group: Enumeration

Description:

This enumeration specifies types of extra channels (Unknown, Mask or Spot).

Declaration:

enum enumIGExtraChannelType
{
    IG_EXTRA_CHANNEL_TYPE_Unknown,
    IG_EXTRA_CHANNEL_TYPE_Mask,
    IG_EXTRA_CHANNEL_TYPE_Spot
};

Values:

IG_EXTRA_CHANNEL_TYPE_Unknown
Unknown extra channel.
IG_EXTRA_CHANNEL_TYPE_Mask
Alpha mask channel.
IG_EXTRA_CHANNEL_TYPE_Spot
Spot color channel.


enumIGFillOrder

Group: Enumeration

Description:

Identifies the raw bit order.

Values:

IG_FILL_MSB
Little endian bit order
IG_FILL_LSB
Big endian bit order


enumIGFlipModes

Group: Enumeration

Description:

This enumeration specifies types of flipping.

Values:

IG_FLIP_HORIZONTAL
Flipping horizontally
IG_FLIP_VERTICAL
Flipping vertically


enumIGFltrFormatFlags

Group: Enumeration

Description:

Identifies the format flags such as DETECTSUPPORT, PAGEREADSUPPORT and other.

Values:

IG_FLTR_DETECTSUPPORT
Format detection is supported
IG_FLTR_PAGEREADSUPPORT
Page reading is supported
IG_FLTR_MPAGEREADPSUPPORT
Multipage reading is supported
IG_FLTR_MPAGEWRITEPSUPPORT
Multipage writing is supported
IG_FLTR_PAGEINSERTSUPPORT
Page insertion is supported
IG_FLTR_PAGEDELETESUPPORT
Page deleting is supported
IG_FLTR_PAGESWAPSUPPORT
Page swapping is supported
IG_FLTR_MPDATASUPPORT
Multipage data is supported


enumIGFormats

Group: Enumeration

Description:

Identifies the formats supported by IG.

Values:

IG_FORMAT_ABIC_BILEVEL
IBM ABIC
IG_FORMAT_ABIC_CONCAT
IBM ABIC
IG_FORMAT_AFX
Auto FX
IG_FORMAT_ATT
Not supported
IG_FORMAT_AVI
AVI
IG_FORMAT_BMP
Microsoft Windows Bitmap
IG_FORMAT_BRK
BTR
IG_FORMAT_CAD
Not supported
IG_FORMAT_CAL
CAL
IG_FORMAT_CGM
CGM
IG_FORMAT_CLP
CLP
IG_FORMAT_CUR
Windows Cursors
IG_FORMAT_CUT
CUT
IG_FORMAT_DCM
DICOM
IG_FORMAT_DCX
Paintbrush
IG_FORMAT_DGN
DGN
IG_FORMAT_DIB
the same as IG_FORMAT_BMP
IG_FORMAT_DWF
DWF
IG_FORMAT_DWG
DWG
IG_FORMAT_DXF
DXF
IG_FORMAT_EPS
Encapsulated postscript
IG_FORMAT_EXIF_JPEG
Exchangeable image file format
IG_FORMAT_EXIF_TIFF
Exchangeable image file format (EXIF-TIFF)
IG_FORMAT_FPX
FlashPix
IG_FORMAT_G3
Group 3
IG_FORMAT_G32D
Group 3 2D
IG_FORMAT_G4
Group 4
IG_FORMAT_GEM
GEM Raster
IG_FORMAT_GIF
GIF
IG_FORMAT_HPGL
HPGL
IG_FORMAT_ICA
IBM IOCA
IG_FORMAT_ICO
Windows icon
IG_FORMAT_IFF
Interchange File Format
IG_FORMAT_IMR
IMR
IG_FORMAT_IMT
IMT
IG_FORMAT_JB2
Jbig2
IG_FORMAT_JBIG
JBIG
IG_FORMAT_JPEG2K
JPEG2000
IG_FORMAT_JPG
JPEG File Interchange
IG_FORMAT_JPX
JPX
IG_FORMAT_KFX
KFX
IG_FORMAT_LURADOC
LuraDoc(Lura)
IG_FORMAT_LURAJP2
JPEG2000(Lura)
IG_FORMAT_LURAWAVE
Wavelet(Lura)
IG_FORMAT_LV
LV
IG_FORMAT_MAC
MAC
IG_FORMAT_MOD
IBM MO:DCA
IG_FORMAT_MODCA
Not supported
IG_FORMAT_MSP
MSP
IG_FORMAT_MUL
MULTIMEDIA
IG_FORMAT_NCR
NCR
IG_FORMAT_PBM
PBM
IG_FORMAT_PCD
PCD
IG_FORMAT_PCT
Mac PICT
IG_FORMAT_PCX
PC Paintbrush File Format
IG_FORMAT_PDF
Adobe PDF
IG_FORMAT_PGM
Not supported
IG_FORMAT_PJPEG
Not supported
IG_FORMAT_PNG
Portable Network Graphics
IG_FORMAT_PNM
Not supported
IG_FORMAT_POSTSCRIPT
Not supported
IG_FORMAT_PPM
Not supported
IG_FORMAT_PSB
Adobe PSB
IG_FORMAT_PSD
Adobe PSD
IG_FORMAT_PTOCA
PTOCA file
IG_FORMAT_RAS
RAS
IG_FORMAT_RAW
RAW
IG_FORMAT_SCI_CT
Scitex CT file
IG_FORMAT_SCITEX
Not supported
IG_FORMAT_SGI
SGI
IG_FORMAT_STX
Not supported
IG_FORMAT_TGA
TGA
IG_FORMAT_TIF
Tagged Image File Format
IG_FORMAT_TXT
TXT
IG_FORMAT_UNKNOWN
Unknown format
IG_FORMAT_WBMP
Wireless Bitmap File Format
IG_FORMAT_WL16
Not supported
IG_FORMAT_WLT
Not supported
IG_FORMAT_WMF
Windows MetaFile
IG_FORMAT_WPG
WPG
IG_FORMAT_XBM
XBM
IG_FORMAT_XPM
XPM
IG_FORMAT_XRX
IMG
IG_FORMAT_XWD
XWD


enumIGFrameModes

Group: Enumeration

Description:

This enumeration specifies modes of drawing of a frame.

Values:

IG_DRAW_FRAME_EXPAND
The width and the height of an image are expanded by 2 times the width of the frame.
IG_DRAW_FRAME_OVERWRITE
All four sides of an image are overwritten by the frame.


enumIGFXRipplePattern

Group: Enumeration

Description:

This enumeration specifies predefined patterns for the Ripple effect. Please see IG_FX_ripple for reference.

Values:

IG_RIPPLE_PATTERN_0
Ripple pattern 0
IG_RIPPLE_PATTERN_1
Ripple pattern 1
IG_RIPPLE_PATTERN_2
Ripple pattern 2
IG_RIPPLE_PATTERN_3
Ripple pattern 3
IG_RIPPLE_PATTERN_4
Ripple pattern 4
IG_RIPPLE_PATTERN_5
Ripple pattern 5


enumIGHTTPVerbs

Group: Enumeration

Description:

Identifies the method of saving an annotation or image.

Values:

IG_HTTP_VERB_PUT
For saving the annotation page or image to the file.
IG_HTTP_VERB_POST
For transferring the annotation page or image data to the web script.


enumIGImageChannelType

Group: Enumeration

Description:

Identifies the different types of image channel.

Values:

IG_ICT_RED
Red channel
IG_ICT_GREEN
Green channel
IG_ICT_BLUE
Blue channel
IG_ICT_ALPHA
Alpha channel


enumIGInetServices

Group: Enumeration

Description:

Identifies the Inet service for loading from URL

Values:

IG_INETSERV_HTTP
HTTP service
IG_INETSERV_FTP
FTP service
IG_INETSERV_GOPHER
GOPHER service


enumIGInterpolations

Group: Enumeration

Description:

This enumeration specifies types of interpolation.

Values:

IG_INTERPOLATION_NONE
Preserve the original number of palette entries
IG_INTERPOLATION_AVERAGE
Average
IG_INTERPOLATION_BILINEAR
Bilinear
IG_INTERPOLATION_NEAREST_NEIGHBOR
Nearest neighbor
IG_INTERPOLATION_PADDING
Padding
IG_INTERPOLATION_GRAYSCALE
grayscale
IG_INTERPOLATION_PRESERVE_WHITE
Preserve white
IG_INTERPOLATION_PRESERVE_BLACK
Preserve black
IG_INTERPOLATION_BICUBIC
Bicubic


enumIGIPShearFillStyle

Group: Enumeration

Description:

This enumeration specifies Shear effect filling styles. Please see IG_FX_shear function for reference.

Values:

IG_IP_SHEAR_FILLCOLOR
Empty area is filled with the specified color.
IG_IP_SHEAR_NOCHANGE
Empty area remains unchanged.
IG_IP_SHEAR_REPEATEDGE
Empty area is filled with the first or last raster color.
IG_IP_SHEAR_REPEATRASTER
The raster is repeated periodically across the empty area.


enumIGLayerType

Group: Enumeration

Description:

This enumeration specifies the currently supported types of layers.

IG_LAYER_TYPE_IMAGE
Image layer type.
IG_LAYER_TYPE_UNKNOWN
Unknown (unrecognized by ImageGear) layer type.


enumIGLicenseType

Group: Enumeration

Description:

Identifies the different types of product license - evaluation, development, or deployment.

Values:

IG_VERSION_EVAL
Evaluation license
IG_VERSION_DEVELOPMENT_ONLY
Development license
IG_VERSION_DEPLOYMENT
Deployment license


enumIGMaskChannelModes

Group: Enumeration

Description:

This enumeration specifies mode of Mask channel (selected area or masked area).

Declaration:

enum enumIGMaskChannelModes
{
    IG_MASK_CHANNEL_MODES_ColorIndicatesSelectedArea,
    IG_MASK_CHANNEL_MODES_ColorIndicatesMaskedArea
};

Values:

IG_MASK_CHANNEL_MODES_ColorIndicatesSelectedArea
Mask channel indicates selected area,
IG_MASK_CHANNEL_MODES_ColorIndicatesMaskedArea
Mask channel indicates masked area.


enumIGMergeModes

Group: Enumeration

Description:

Identifies the type of arithmetic operation (merge method) that is performed on the values of all intersecting pixels resulting from the merge.

For example, if you set IG_ARITH_ADD merge method, the resulting pixel values (of those pixels that intersected from the two images) equal the sum of the value of the pixel in the original image and the value of pixel in the image being merged.

Values:

IG_ARITH_ADD
Img1 = Img1 + Img2
IG_ARITH_ADD_SIGN_CENTERED
Img1 = Img1+ SC_Img2
IG_ARITH_AND
Img1 = Img1 & Img2
IG_ARITH_DIVIDE
Img1 = Img1 / Img2
IG_ARITH_MULTI
Img1 = Img1 * Img2
IG_ARITH_NOT
Img1 = ~Img1
IG_ARITH_OR
Img1 = Img1 | Img2
IG_ARITH_OVER
Img1 = Img2
IG_ARITH_SUB
Img1 = Img1 - Img2
IG_ARITH_XOR
Img1 = Img1 ^ Img2


enumIGMETADItemType

Group: Enumeration

Description:

Identifies the Inet service for loading from URL.

Values:

IG_METAD_LEVEL_START
Start of new metadata level
IG_METAD_VALUE_ITEM
Metadata item
IG_METAD_LEVEL_END
End of metadata level


enumIGNoiseMethods

Group: Enumeration

Description:

This enumeration contains noise methods for IG_FX_noise.

Values:

IG_NOISE_LINEAR
Linear method
IG_NOISE_GAUSSIAN
Gaussian method


enumIGOrientationModes

Group: Enumeration

Description:

Identifies how the image is oriented before it is drawn on the output device. Possible values are determined by the constants of the form IG_DSPL_ORIENT_X_Y, where each of X and Y can be LEFT, TOP, RIGHT or BOTTOM. X represents the position of the topmost row of the bitmap after applying the transformation. Y represents the position of the left-most column of the bitmap after applying the transformation.

For example, IG_DSPL_ORIENT_RIGHT_TOP means that the left-most column becomes the image's new topmost row, and that the topmost row becomes the image's new right-most column. The image, therefore, is rotated on 90 degrees.

Values:

IG_DSPL_ORIENT_BOTTOM_LEFT
The image is flipped vertically.
IG_DSPL_ORIENT_BOTTOM_RIGHT
The image is rotated 180 degrees.
IG_DSPL_ORIENT_LEFT_BOTTOM
The image is rotated 270 degrees.
IG_DSPL_ORIENT_LEFT_TOP
The image is rotated 270 degrees and then flipped vertically.
IG_DSPL_ORIENT_RIGHT_BOTTOM
The image is rotated 90 degrees and then flipped vertically.
IG_DSPL_ORIENT_RIGHT_TOP
The image is rotated 90 degrees.
IG_DSPL_ORIENT_TOP_LEFT
The image is displayed unchanged.
IG_DSPL_ORIENT_TOP_RIGHT
The image is flipped horizontally.


enumIGPaletteFormats

Group: Enumeration

Description:

Identifies the different formats used for storing image palette in the external file.

Values:

IG_PALETTE_FORMAT_INVALID
Returned when a file could not be read
IG_PALETTE_FORMAT_RAW_BGR
This is the raw DIB format BGR
IG_PALETTE_FORMAT_RAW_BGRQ
This is the raw DIB format BGRQ
IG_PALETTE_FORMAT_RAW_RGB
This is the raw DIB format RGB
IG_PALETTE_FORMAT_RAW_RGBQ
This is the raw DIB format RGBQ
IG_PALETTE_FORMAT_TEXT
ASCII text file
IG_PALETTE_FORMAT_HALO_CUT
Dr Halo .PAL file for use with a CUT file format


enumIGPixelAccessType

Group: Enumeration

Description:

Identifies the different methods of accessing pixel values.

Values:

IG_PIX_ACC_PACKED
Return data in the packed form
IG_PIX_ACC_UNPACKED
Return data in the unpacked form


enumIGPixelArrayType

Group: Enumeration

Description:

Identifies the different types of pixel array.

Values:

IG_PIX_ARR_RGB
Array of RGB values
IG_PIX_ARR_CMYK
Array of CMYK values
IG_PIX_ARR_INDEX_UNPACKED
Array of unpacked indexed pixels (1 pixel occupies 1 byte)
IG_PIX_ARR_GRAY
Array of 9-16 bit grayscale values (1 pixel occupies 2 bytes)


enumIGPixelType

Group: Enumeration

Description:

Identifies the different pixel types.

Values:

IG_PIXEL_RGB
RGB pixel
IG_PIXEL_CMYK
CMYK pixel
IG_PIXEL_GRAY
9-16 bit grayscale pixel
IG_PIXEL_INDEX
indexed pixel


enumIGPromotionModes

Group: Enumeration

Description:

This enumeration specifies modes of color promotion.

Values:

IG_PROMOTE_TO_4
Promotion to 4 bpp
IG_PROMOTE_TO_8
Promotion to 8 bpp
IG_PROMOTE_TO_24
Promotion to 24 bpp
IG_PROMOTE_TO_32
Promotion to 32 bpp


enumIGResampleInModes

Group: Enumeration

Description:

This enumeration contains input modes for IG_FX_pixelate method.

Values:

IG_RESAMPLE_IN_AVE
Average
IG_RESAMPLE_IN_MIN
Min
IG_RESAMPLE_IN_MAX
Max
IG_RESAMPLE_IN_CENTER
Center


enumIGResampleOutModes

Group: Enumeration

Description:

This enumeration contains output modes for IG_FX_pixelate method.

Values:

IG_RESAMPLE_OUT_SQUARE
Square
IG_RESAMPLE_OUT_CIRCLE
Circle


enumIGResizeModes

Group: Enumeration

Description:

This enumeration specifies modes of image resizing.

Values:

IG_RESIZE_ACTUAL
New image dimensions are actual dimensions.
IG_RESIZE_PERCENT
New image dimensions are percentages.


enumIGResolutionUnits

Group: Enumeration

Description:

Identifies the different resolution units.

Values:

IG_RESOLUTION_NO_ABS
No absolute units
IG_RESOLUTION_METERS
Pels (Pixels) Per Meter
IG_RESOLUTION_INCHES
Dots (Pixels) Per Inch
IG_RESOLUTION_CENTIMETERS
Pixles Per Centimeter
IG_RESOLUTION_10_INCHES
Dots (Pixels) Per 10 Inches
IG_RESOLUTION_10_CENTIMETERS
Pixles Per 10 Centimeter


enumIGROIType

Group: Enumeration

Description:

Identifies the different ROI (region of interest) types.

Values:

IG_ROI_ALL_IMAGE
Entire image
IG_ROI_RECT
Rectangular area
IG_ROI_NRA
Non-rectangular area


enumIGRotationModes

Group: Enumeration

Description:

This enumeration specifies modes of image rotation.

Values:

IG_ROTATE_CLIP
Clip the rotated image to keep the image bitmap the same size.
IG_ROTATE_EXPAND
Expand the size of the bitmap if necessary to retain the entire rotated image.


enumIGRotationValues

Group: Enumeration

Description:

This enumeration specifies angles of image rotation by a multiple of 90 degrees.

Values:

IG_ROTATE_0
No rotation
IG_ROTATE_90
Rotation by 90 degrees.
IG_ROTATE_180
Rotation by 180 degrees.
IG_ROTATE_270
Rotation by 270 degrees.


enumIGSaveFormats

Group: Enumeration

Description:

Identifies the formats available for saving.

Values:

IG_SAVE_UNKNOWN
unknown format
IG_SAVE_BRK_G3
BTR with Group 3 compression
IG_SAVE_BRK_G3_2D
BTR with Group 3 2D compression
IG_SAVE_BMP_RLE
Microsoft Windows bitmap with RLE compression
IG_SAVE_BMP_UNCOMP
Microsoft Windows bitmap uncompressed
IG_SAVE_CAL
CAL
IG_SAVE_CLP
CLP
IG_SAVE_DCX
Paintbrush
IG_SAVE_EPS_UNCOMP
Encapsulated postscript uncompressed
IG_SAVE_EPS_JPG
Encapsulated postscript with JPG compression
IG_SAVE_EPS_G3
Encapsulated postscript with Group 3 compression
IG_SAVE_EPS_G4
Encapsulated postscript with Group 4 compression
IG_SAVE_GIF
GIF
IG_SAVE_ICA_G3
IBM IOCA with Group 3 compression
IG_SAVE_ICA_G4
IBM IOCA with Group 4 compression
IG_SAVE_ICA_IBM_MMR
IBM IOCA with IBM MMR compression
IG_SAVE_ICO
windows icon
IG_SAVE_IMT
IMT
IG_SAVE_IFF
Interchange uncompressed
IG_SAVE_IFF_RLE
Interchange with RLE compression
IG_SAVE_JPG
JPEG File Interchange
IG_SAVE_PJPEG
Not supported
IG_SAVE_MOD_G3
IBM MO:DCA with Group 3 compression
IG_SAVE_MOD_G4
IBM MO:DCA with Group 4 compression
IG_SAVE_MOD_IBM_MMR
IBM MO:DCA with MMR compression
IG_SAVE_NCR
NCR uncompressed
IG_SAVE_NCR_G4
NCR with Group 4 compression
IG_SAVE_PBM_ASCII
PBM converted to ASCII text
IG_SAVE_PBM_RAW
PBM binary row format
IG_SAVE_PCT
Mac Pict
IG_SAVE_PCX
PC Paintbrush File Format
IG_SAVE_PDF_UNCOMP
Adobe PDF uncompressed
IG_SAVE_PDF_JPG
Adobe PDF with JPEG compression
IG_SAVE_PDF_G3
Adobe PDF with Group 3 compression
IG_SAVE_PDF_G3_2D
Adobe PDF with Group3 2D compression
IG_SAVE_PDF_G4
Adobe PDF with Group 4 compression
IG_SAVE_PDF_RLE
Adobe PDF with RLE compression
IG_SAVE_PDF_DEFLATE
Adobe PDF with Deflate compression
IG_SAVE_PDF_LZW
Adobe PDF with LZW compression
IG_SAVE_PS_UNCOMP
Postscript uncompressed
IG_SAVE_PS_JPG
Postscript with JPEG compression
IG_SAVE_PS_G3
Postscript with Group 3 compression
IG_SAVE_PS_G3_2D
Postscript with Group3 2D compression
IG_SAVE_PS_G4
Postscript with Group 4 compression
IG_SAVE_PS_RLE
Postscript with RLE compression
IG_SAVE_PS_DEFLATE
Postscript with Deflate compression
IG_SAVE_PS_LZW
Postscript with LZW compression
IG_SAVE_PNG
Portable network graphics
IG_SAVE_PSB
Adobe PSB
IG_SAVE_PSD
Adobe PSD
IG_SAVE_PSD_PACKED
Adobe PSD with packed bits compression
IG_SAVE_RAS
RAS
IG_SAVE_RAW_G3
RAW with Group 3 compression
IG_SAVE_RAW_G4
RAW with Group 4 compression
IG_SAVE_RAW_G32D
RAW with Group 3 2D compression
IG_SAVE_RAW_LZW
RAW with LZW compression
IG_SAVE_RAW_RLE
RAW with RLE compression
IG_SAVE_SGI
SGI
IG_SAVE_SGI_RLE
SGI with RLE compression
IG_SAVE_TGA
TGA
IG_SAVE_TGA_RLE
TGA with RLE compression
IG_SAVE_TIF_UNCOMP
Tagged Image File Format uncompressed
IG_SAVE_TIF_G3
Tagged Image File Format with Group 3 compression
IG_SAVE_TIF_G3_2D
Tagged Image File Format with Group 3 2D compression
IG_SAVE_TIF_G4
Tagged Image File Format with Group 4 compression
IG_SAVE_TIF_HUFFMAN
Tagged Image File Format with Huffman compression
IG_SAVE_TIF_JPG
with JPEG compression
IG_SAVE_TIF_LZW
Tagged Image File Format with LZW compression
IG_SAVE_TIF_PACKED
Tagged Image File Format with Packed Bits compression
IG_SAVE_XBM
XBM
IG_SAVE_XPM
XPM
IG_SAVE_XWD
XWD
IG_SAVE_WMF
Windows MetaFile
IG_SAVE_WLT
NotSupported
IG_SAVE_JB2
Lbig2
IG_SAVE_WL16
Not supported
IG_SAVE_WBMP
Wireless Bitmap File Format
IG_SAVE_FPX_NOCHANGE
FlashPix with the current compression
IG_SAVE_FPX_UNCOMP
FlashPix uncompressed
IG_SAVE_FPX_JPG
FlashPix with JPEG compression
IG_SAVE_FPX_SINCOLOR
FlashPix with the single color compression
IG_SAVE_DCM
DICOM
IG_SAVE_JBIG
JBIG
IG_SAVE_SCI_ST
Scitex CT format
IG_SAVE_LURAWAVE
Wavelet(Lura)
IG_SAVE_LURADOC
LuraDoc(Lura)
IG_SAVE_LURAJP2
JPEG2000(Lura
IG_SAVE_JPEG2K
JPEG2000
IG_SAVE_JPX
JPX
IG_SAVE_EXIF_JPEG
Exchangeable image file format
IG_SAVE_EXIF_TIFF
Exchangeable image file format (EXIF-TIFF)


enumIGShapeType

Group: Enumeration

Description:

Identifies the different shape types.

Values:

IG_SHAPE_RECTANGLE
Rectangle
IG_SHAPE_ELLIPSE
Ellipse
IG_SHAPE_POLYGON
Polygon


enumIGSpotColorVendorIDs

Group: Enumeration

Description:

This enumeration specifies predefined Vendor IDs.

Declaration:

enum enumIGSpotColorVendorIDs
{
    IG_SPOT_COLOR_VENDOR_SYNONYM_ID_Pantone = 3,
    IG_SPOT_COLOR_VENDOR_SYNONYM_ID_Focoltone = 4,
IG_SPOT_COLOR_VENDOR_SYNONYM_ID_Trumatch = 5,
    IG_SPOT_COLOR_VENDOR_SYNONYM_ID_Toyo = 6,
    IG_SPOT_COLOR_VENDOR_SYNONYM_ID_HKS = 10,
    IG_SPOT_COLOR_VENDOR_SYNONYM_ID_DIC = 11,
    IG_SPOT_COLOR_VENDOR_ID_ANPA = 3000,
    IG_SPOT_COLOR_VENDOR_ID_Focoltone = 3001,
    IG_SPOT_COLOR_VENDOR_ID_PantoneCoated = 3002,
    IG_SPOT_COLOR_VENDOR_ID_PantoneProcess = 3003,
    IG_SPOT_COLOR_VENDOR_ID_PantoneProSlim = 3004,
    IG_SPOT_COLOR_VENDOR_ID_PantoneUncoated = 3005,
    IG_SPOT_COLOR_VENDOR_ID_Toyo = 3006,
    IG_SPOT_COLOR_VENDOR_ID_Trumatch = 3007,
    IG_SPOT_COLOR_VENDOR_ID_HKSE = 3008,
    IG_SPOT_COLOR_VENDOR_ID_HKSK = 3009,
    IG_SPOT_COLOR_VENDOR_ID_HKSN = 3010,
    IG_SPOT_COLOR_VENDOR_ID_HKSZ = 3011,
    IG_SPOT_COLOR_VENDOR_ID_DIC = 3012,
    IG_SPOT_COLOR_VENDOR_ID_PantoneMatte = 3013,
    IG_SPOT_COLOR_VENDOR_ID_PantonePastelCoated = 3020,
    IG_SPOT_COLOR_VENDOR_ID_PantonePastelUncoated = 3021,
    IG_SPOT_COLOR_VENDOR_ID_PantoneMetallic = 3022,
    IG_SPOT_COLOR_VENDOR_ID_HKSEProcess = 3024,
    IG_SPOT_COLOR_VENDOR_ID_HKSKProcess = 3025,
    IG_SPOT_COLOR_VENDOR_ID_HKSNProcess = 3026,
    IG_SPOT_COLOR_VENDOR_ID_HKSZProcess = 3027,
    IG_SPOT_COLOR_VENDOR_ID_PantoneProSlimEuro = 3028,
    IG_SPOT_COLOR_VENDOR_ID_PantoneProcessUncoated = 3029,
    IG_SPOT_COLOR_VENDOR_ID_UserColorBook = 3100
};

Values:

IG_SPOT_COLOR_VENDOR_SYNONYM_ID_Pantone
Synonym ID for Pantone
IG_SPOT_COLOR_VENDOR_SYNONYM_ID_Focoltone
Synonym ID for Focoltone
IG_SPOT_COLOR_VENDOR_SYNONYM_ID_Trumatch
Synonym ID for Trumatch
IG_SPOT_COLOR_VENDOR_SYNONYM_ID_Toyo
Synonym ID for Toyo
IG_SPOT_COLOR_VENDOR_SYNONYM_ID_HKS
Synonym ID for HKS
IG_SPOT_COLOR_VENDOR_SYNONYM_ID_DIC
Synonym ID for DIC
IG_SPOT_COLOR_VENDOR_ID_ANPA
VendorID for ANPA
IG_SPOT_COLOR_VENDOR_ID_Focoltone
VendorID for Focoltone
IG_SPOT_COLOR_VENDOR_ID_PantoneCoated
VendorID for PantoneCoated
IG_SPOT_COLOR_VENDOR_ID_PantoneProcess
VendorID for PantoneProcess
IG_SPOT_COLOR_VENDOR_ID_PantoneProSlim
VendorID for PantoneProSlim
IG_SPOT_COLOR_VENDOR_ID_PantoneUncoated
VendorID for PantoneUncoated
IG_SPOT_COLOR_VENDOR_ID_Toyo
VendorID for Toyo
IG_SPOT_COLOR_VENDOR_ID_Trumatch
VendorID for Trumatch
IG_SPOT_COLOR_VENDOR_ID_HKSE
VendorID for HKSE
IG_SPOT_COLOR_VENDOR_ID_HKSK
VendorID for HKSK
IG_SPOT_COLOR_VENDOR_ID_HKSN
VendorID for HKSN
IG_SPOT_COLOR_VENDOR_ID_HKSZ
VendorID for HKSZ
IG_SPOT_COLOR_VENDOR_ID_DIC
VendorID for DIC
IG_SPOT_COLOR_VENDOR_ID_PantoneMatte
VendorID for PantoneMatte
IG_SPOT_COLOR_VENDOR_ID_PantonePastelCoated
VendorID for PantonePastelCoated
IG_SPOT_COLOR_VENDOR_ID_PantonePastelUncoated
VendorID for PantonePastelUncoated
IG_SPOT_COLOR_VENDOR_ID_PantoneMetallic
VendorID for PantoneMetallic
IG_SPOT_COLOR_VENDOR_ID_HKSEProcess
VendorID for HKSEProcess
IG_SPOT_COLOR_VENDOR_ID_HKSKProcess
VendorID for HKSKProcess
IG_SPOT_COLOR_VENDOR_ID_HKSNProcess
VendorID for HKSNProcess
IG_SPOT_COLOR_VENDOR_ID_HKSZProcess
VendorID for HKSZProcess
IG_SPOT_COLOR_VENDOR_ID_PantoneProSlimEuro
VendorID for PantoneProSlimEuro
IG_SPOT_COLOR_VENDOR_ID_PantoneProcessUncoated
VendorID for PantoneProcessUncoated
IG_SPOT_COLOR_VENDOR_ID_UserColorBook
VendorID for User ColorBook


enumIGSysDataType

Group: Enumeration

Description:

Identifies the IG data types

Values:

AM_TID_META_INT8
8 bit signed integer
AM_TID_META_UINT8
8 bit unsigned integer
AM_TID_META_INT16
16 bit signed integer
AM_TID_META_UINT16
16 bit unsigned integer
AM_TID_META_INT32
32 bit signed integer
AM_TID_META_UINT32
32 bit unsigned integer
AM_TID_META_BOOL
Boolean
AM_TID_META_STRING
String
AM_TID_META_RATIONAL_UINT32
Rational 32 bit unsigned integer
AM_TID_META_RATIONAL_INT32
Rational 32 bit bit signed integer
AM_TID_META_FLOAT
Float
AM_TID_META_DOUBLE
Double
AM_TID_RAW_DATA
Raw Data
AM_TID_META_INT64
64 bit signed integer
AM_TID_META_UINT64
64 bit unsigned integer


enumIGTwistModes

Group: Enumeration

Description:

This enumeration contains rotation modes for IG_FX_twist method.

Values:

IG_TWIST_90
90
IG_TWIST_180
180
IG_TWIST_270
270
IG_TWIST_RANDOM
Random


enumIGWipeStyles

Group: Enumeration

Description:

Identifies the different image transition effects.

Values:

IG_WIPE_LEFTTORIGHT
Left-to-Right Wipe.
IG_WIPE_RIGHTTOLEFT
Right-To-Left Wipe.
IG_WIPE_UP_TO_DOWN
Up-to-Down Wipe.
IG_WIPE_DOWN_TO_UP
Down-to-Up Wipe.
IG_WIPE_SPARKLE
Sparkle Transition
IG_WIPE_ULTOLRDIAG
Upper Left to Lower Right wipe
IG_WIPE_LRTOULDIAG
Lower Right to Upper Left wipe
IG_WIPE_URTOLLDIAG
Upper Right to Lower Left wipe.
IG_WIPE_LLTOURDIAG
Lower Left to Upper Right wipe.
IG_WIPE_CLOCK
Clockwise wipe.
IG_WIPE_SPARKLE_CLOCK
Clockwise wipe with sparkles.
IG_WIPE_DOUBLE_CLOCK
Two simultaneous clockwise wipes, 180 grades apart.
IG_WIPE_SLIDE_RIGHT
New image slides in from the left.
IG_WIPE_SLIDE_LEFT
New image slides in from the right.
IG_WIPE_SLIDE_UP
New image slides in from the down.
IG_WIPE_SLIDE_DOWN
New image slides in from the up.
IG_WIPE_RANDOM_BARS_DOWN
Vertical bars of old image fall to reveal new image.
IG_WIPE_RAIN
Vertical lines of new image cover over old, like paint running down the side of a bucket.
IG_WIPE_BOOK
Bookwisw wipe.
IG_WIPE_ROLL
Old image rolls in from right to left.
IG_WIPE_UNROLL
New image rolls out from left to right.
IG_WIPE_EXPAND_PROPORTIONAL
New image expands from the center of old image in diagonal directions.
IG_WIPE_EXPAND_HORIZONTAL
New image expands from the center of old image in horizontal directions.
IG_WIPE_EXPAND_VERTICAL
New image expands from the center of old image in vertical directions.
IG_WIPE_STRIPS_HORIZONTAL
New image appeares as expanding horizontal strips.
IG_WIPE_STRIPS_VERTICAL
New image appeares as expanding vertical strips.
IG_WIPE_CELLS
New image appeares as expanding square cells.
IG_WIPE_BALL
New image appeares as tracks of spirally moving balls.
IG_WIPE_GEARS
New image appeares as tracks of moving ImageGear's icons.


FreqIP Component API Function Reference

FreqIP (Frequency Domain Image Processing) component is responsible for image processing functionalities in frequency domain.


IG_FIP_FFT_forward

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_FFT_forward(HIGCOMPLEXOBJ
hIGComplexObj,, LPHIGCOMPLEXOBJ lphIGComplexObjOut,
enumIGFFTScalingMethods nScalingMethod, AT_BOOL
bCenterTransform);

Arguments (with description):

hIGComplexObj
Handle of the input data
lphIGComplexObjOut
Handle of the result data.
nScalingMethod
Specifies the method of scaling the result data.
bCenterTransform
Flag to indicate whether to center the transform.

Description:

This method performs a forward Fast Fourier Transform.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Example:

HIGCOMPLEXOBJ hIGComplexObj;	/* Handle of input data */
HIGCOMPLEXOBJ hIGComplexObjOut;	/* Handle of result data */
...
IG_FIP_FFT_forward(hIGComplexObj, &hIGComplexObjOut,
IG_FFT_SCALING_SQRTN, TRUE);
...

Sample:

FreqIP


IG_FIP_FFT_forward_from_image

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_FFT_forward_from_image(HIGEAR hIGear,
LPHIGCOMPLEXOBJ lphIGComplexObj, enumIGFFTScalingMethods
nScalingMethod, AT_BOOL bCenterTransform);

Arguments:

hIGear
Handle of the image to be processed
lphIGComplexObj
Handle of the result data.
nScalingMethod
Specifies the method of scaling the result data.
bCenterTransform
Flag to indicate whether to center the transform.

Description:

This method performs a forward Fast Fourier Transform. The difference between this function and IG_FIP_FFT_forward() is that this function takes a HIGEAR as the input.

Bits Per Pixel:

8, 16, or 32bit grayscale images with just one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Example:

HIGEAR hIGear;				/* Handle of input image */
HIGCOMPLEXOBJ hIGComplexObjOut;	/* Handle of output data */
...
IG_FIP_FFT_forward_from_image(hIGear, &hIGComplexObjOut,
IG_FFT_SCALING_SQRTN, TRUE);
...

Sample:

FreqIP


IG_FIP_FFT_inverse

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_FFT_inverse (HIGCOMPLEXOBJ
hIGComplexObj,, LPHIGCOMPLEXOBJ lphIGComplexObjOut,
enumIGFFTScalingMethods nScalingMethod, AT_BOOL
bCenterTransform);

Arguments (with description):

hIGComplexObj
Handle of the input data
lphIGComplexObjOut
Handle of the result data.
nScalingMethod
Specifies the method of scaling the result data.
bCenterTransform
Flag to indicate whether to center the transform.

Description:

This method performs an inverse Fast Fourier Transform.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Example:

HIGCOMPLEXOBJ hIGComplexObj;	/* Handle of input data */
HIGCOMPLEXOBJ hIGComplexObjOut;	/* Handle of result data */
...
IG_FIP_FFT_inverse(hIGComplexObj, &hIGComplexObjOut,
IG_FFT_SCALING_SQRTN, TRUE);
...

Sample:

FreqIP


IG_FIP_FFT_inverse_to_image

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_FFT_inverse_to_image(HIGCOMPLEXOBJ
hIGComplexObj, LPHIGEAR lphIGear, enumIGFFTScalingMethods
nScalingMethod, AT_BOOL bCenterTransform);

Arguments (with description):

hIGComplexObj
Handle of the input data.
lphIGear
Handle of the result image.
nScalingMethod
Specifies the method of scaling the result data.
bCenterTransform
Flag to indicate whether to center the transform.

Description:

This method performs an inverse Fast Fourier Transform. The difference between this function and IG_FIP_FFT_inverse() is that this function returns a HIGEAR as the result, using the default conversion type IG_FIPDATA_CONV_TYPE_REAL.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Example:

HIGCOMPLEXOBJ hIGComplexObj;	/* Handle of input data */
HIGEAR hIGear;				/* Handle of output image */
...
IG_FIP_FFT_inverse_to_image(hIGComplexObj, &hIGear,
IG_FFT_SCALING_SQRTN, TRUE);
...

Sample:

FreqIP


IG_FIP_filter_lowpass

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_filter_lowpass(HIGEAR hIGear, const
LPAT_RECT lpRect, const AT_MODE nFilterBrand, const AT_DOUBLE
dCutoffFreq, const AT_INT nFilterOrder, const AT_DOUBLE
dRippleFactor);

Arguments (with description):

hIGear
Handle of the input image, also pass out filtered image
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image.
nFilterBrand
Brand of the filter to use. Constants IG_FREQIP_FILTER_BRAND_* are listed in file i_FreqIP.h.
dCutoffFreq
Cutoff frequency for the low-pass filter
nFilterOrder
Filter order to use, applicable to all except Ideal filter
dRippleFactor
A factor which determines the pass-band ripple for Chebyshev filters, with vaule between [0, 1].

Description:

This function filters the input image using a low-pass filter, with the specified parameters.

Parameter nFilterBrand specifies the brand of filter to use, with available brands being Ideal, Butterworth, Gaussian, Chebyshev I, and Chebyshev II.

Parameter dCutoffFreq specifies the cutoff frequency for the low-pass filter. This parameter should have value within the range of [0, 1], where 0 is DC and 1 is the Nyquist frequency.

Bits Per Pixel:

8bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Example:

HIGEAR hIGear;			/* Handle of the input image */
...
IG_FIP_filter_lowpass(hIGear, NULL,
IG_FREQIP_FILTER_BRAND_GAUSSIAN, 0.3, 1, 0.5);
...

Sample:

FreqIP


IG_FIP_filter_highpass

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_filter_highpass(HIGEAR hIGear, const
LPAT_RECT lpRect, const AT_MODE nFilterBrand, const AT_DOUBLE
dCutoffFreq, const AT_INT nFilterOrder, const AT_DOUBLE
dRippleFactor );

Arguments (with description):

hIGear
Handle of the input image, also pass out filtered image
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image.
nFilterBrand
Brand of the filter to use. Constants IG_FREQIP_FILTER_BRAND_* are listed in file i_FreqIP.h.
dCutoffFreq
Cutoff frequency for the high-pass filter
nFilterOrder
Filter order to use, applicable to all except Ideal filter
dRippleFactor
A factor which determines the pass-band ripple for Chebyshev filters, with vaule between [0, 1].

Description:

This function filters the input image using a high-pass filter, with the specified parameters.

Parameter nFilterBrand specifies the brand of filter to use, with available brands being Ideal, Butterworth, Gaussian, Chebyshev I, and Chebyshev II.

Parameter dCutoffFreq specifies the cutoff frequency for the high-pass filter. This parameter should have value within the range of [0, 1], where 0 is DC and 1 is the Nyquist frequency.

Bits Per Pixel:

8bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Example:

HIGEAR hIGear;			/* Handle of the input image */
...
IG_FIP_filter_highpass(hIGear, NULL,
IG_FREQIP_FILTER_BRAND_GAUSSIAN, 0.3, 1, 0.5);
...

Sample:

FreqIP


IG_FIP_filter_bandpass

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_filter_bandpass(HIGEAR hIGear, const
LPAT_RECT lpRect, const AT_MODE nFilterBrand, const AT_DOUBLE
dCutoffFreqLow, const AT_DOUBLE dCutoffFreqHigh, const AT_INT
nFilterOrder, const AT_DOUBLE dRippleFactor);

Arguments (with description):

hIGear
Handle of the input image, also pass out filtered image
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image.
nFilterBrand
Brand of the filter to use. Constants IG_FREQIP_FILTER_BRAND_* are listed in file i_FreqIP.h.
dCutoffFreqLow
Lower cutoff frequency for the band-pass filter
dCutoffFreqHigh
Higher cutoff frequency for the band-pass filter
nFilterOrder
Filter order to use, applicable to all except Ideal filter
dRippleFactor
A factor which determines the pass-band ripple for Chebyshev filters, with vaule between [0, 1].

Description:

This function filters the input image using a band-pass filter, with the specified parameters.

Parameter nFilterBrand specifies the brand of filter to use, with available brands being Ideal, Butterworth, Gaussian, Chebyshev I, and Chebyshev II.

Parameters dCutoffFreqLow and dCutoffFreqHigh specify the lower and upper cutoff frequencies for the band-pass filter. The parameters should have values within the range of [0, 1], where 0 is DC and 1 is the Nyquist frequency.

Bits Per Pixel:

8bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Example:

HIGEAR hIGear;			/* Handle of the input image */
...
IG_FIP_filter_bandpass(hIGear, NULL,
IG_FREQIP_FILTER_BRAND_CHEBYSHEV_I , 0.3, 1, 0.5);
...

Sample:

FreqIP


IG_FIP_filter_bandstop

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_filter_bandstop(HIGEAR hIGear, const
LPAT_RECT lpRect, const AT_MODE nFilterBrand, const AT_DOUBLE
dCutoffFreqLow, const AT_DOUBLE dCutoffFreqHigh, const AT_INT
nFilterOrder, const AT_DOUBLE dRippleFactor);

Arguments (with description):

hIGear
Handle of the input image, also pass out filtered image
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image.
nFilterBrand
Brand of the filter to use. Constants IG_FREQIP_FILTER_BRAND_* are listed in file i_FreqIP.h.
dCutoffFreqLow
Lower cutoff frequency for the band-stop filter
dCutoffFreqHigh
Higher cutoff frequency for the band-stop filter
nFilterOrder
Filter order to use, applicable to all except Ideal filter
dRippleFactor
A factor which determines the pass-band ripple for Chebyshev filters, with vaule between [0, 1].

Description:

This function filters the input image using a band-stop filter, with the specified parameters.

Parameter nFilterBrand specifies the brand of filter to use, with available brands being Ideal, Butterworth, Gaussian, Chebyshev I, and Chebyshev II.

Parameters dCutoffFreqLow and dCutoffFreqHigh specify the lower and upper cutoff frequencies for the band-stop filter. The parameters should have values within the range of [0, 1], where 0 is DC and 1 is the Nyquist frequency.

Bits Per Pixel:

8bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Example:

HIGEAR hIGear;			/* Handle of the image to check*/
...
IG_FIP_filter_bandstop(hIGear, NULL,
IG_FREQIP_FILTER_BRAND_BUTTERWORTH , 0.3, 1, 0.5);
...

Sample:

FreqIP


IG_FIP_restore_inverse

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_restore_inverse(HIGEAR hIGear, const
LPAT_RECT lpRect, LPAT_DOUBLE lpPSFVector, const AT_INT
nPSFSize, const AT_DOUBLE dThreshold);

Arguments (with description):

hIGear
Handle of the input image, also pass out the restored image
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image.
lpPSFVector
Pointer to the vector which represents the Point Spread Function (PSF) in spatial domain, also called Degradation Function.
nPSFSize
Size of PSF passed in lpPSFVector.
dThreshold
The threshold parameter for Inverse Filtering.

Description:

This function performs image restoration using inverse filtering in the frequency domain. The idea is to deconvolve PSF from the blurred data to extract the original image.

The deconvolution involves dividing the Fourier transform of the blurred image by the Fourier transform of PSF. If the transform of PSF has very small values, then the division result from those small values could easily dominate the entire result. The approach used to get around this issue is to limit the smallest value of the transform of PSF, thus we require a threshold value, dThreshold, to be passed in as a parameter. Ideally, this value will be just above the noise level in the image. This function places zeros in the output for those data points where the magnitude of PSF transform is below the threshold. In this respect, IG_FIP_restore_inverse is actually an implementation of a pseudo-inverse filter.

Bits Per Pixel:

8bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Example:

HIGEAR hIGear;		/* Handle of the input image */
AT_DOUBLE psfVector[11];
...
IG_FIP_restore_inverse(hIGear, NULL, psfVector, 11, 0.005);
...

Sample:

FreqIP


IG_FIP_restore_wiener

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_restore_wiener(HIGEAR hIGear, const
LPAT_RECT lpRect, LPAT_DOUBLE lpPSFVector, const AT_INT
nPSFSize, const AT_DOUBLE dWienerConstant);

Arguments (with description):

hIGear
Handle of the input image, also pass out the restored image
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image.
lpPSFVector
Pointer to the vector which represents the Point Spread Function (PSF) in spatial domain, also called Degradation Function.
nPSFSize
Size of PSF passed in lpPSFVector.
dWienerConstant
The constant for Wiener Filtering.

Description:

This function performs image restoration using Wiener filtering in the frequency domain. This filter is also commonly referred to as the minimum mean square error filter or the least square error filter.

Usually speaking, Wiener filtering can produce better results than inverse filtering.

Bits Per Pixel:

8bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Example:

HIGEAR hIGear;		/* Handle of the input image */
AT_DOUBLE psfVector[11];
...
IG_FIP_restore_wiener(hIGear, NULL, psfVector, 11, 0.005);
...

Sample:

FreqIP


IG_FIP_convolve

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_convolve(HIGEAR hIGear, LPAT_RECT
lpRect, LPAT_INT lpMatrix, AT_DIMENSION nMatrixWidth,
AT_DIMENSION nMatrixHeight, AT_DOUBLE dNormalizer, AT_BOOL
bAddToOrigin);

Arguments (with description):

hIGear
HIGEAR handle of image to be processed
lpRect
Far pointer to an AT_RECT structure specifying the rectangular portion of the image on which to operate. If NULL, this operation will be performed on the entire image.
lpMatrix
Array of kernel elements to convolve with.
nMatrixWidth
Width of kernel matrix.
nMatrixHeight
Height of kernel matrix.
dNormalizer
Normalizer of kernel.
bAddToOrigin
Whether to add the result of the convolution to the original pixel values, or replace the original pixel values.

Description:

This function convolves an image with the given kernel matrix. The convolution is implemented using FFT, based on the Convolution Theorem, which provides improved performance for larger kernel matrix.

The result of the convolution is multiplied by dNormalizer to scale the data. For kernels that sum to zero, the normalizer is usually set to 1.0.

Bits Per Pixel:

8, 16, 32-bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;				/* Handle of the image */
AT_RECT lpRect;				 /* rectangle to process */
AT_UINT mxConv[] = { 0, 1, 0,
        1, 5, 1,
        0, 1, 0 };		 /* Convolution kernel */
AT_DOUBLE dNormalizer = 0.2;		/* Normalizer of the kernel */
AT_BOOL bAddToOrigin;			/* TRUE = add to original pix vals */
...
IG_FIP_convolve(hIGear, lpRect, 3, 3, mxConv, dNormalizer,
FALSE);
...

Sample:

FreqIP


IG_FIP_DCT_forward

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_dct_forward(HIGCOMPLEXOBJ
hIGComplexObj, LPHIGCOMPLEXOBJ lphIGComplexObjOut);

Arguments (with description):

hIGComplexObj
HIGCOMPLEXOBJ handle of data to be processed.
lphIGComplexObjOut
HIGCOMPLEXOBJ handle of result data.

Description:

This function computes the forward Discrete Cosine Transform (DCT) of the input HIGCOMPLEXOBJ data.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGCOMPLEXOBJ hIGComplexObj;	/* HIGCOMPLEXOBJ handle of input
data */
HIGCOMPLEXOBJ hIGComplexObjOut;	/* HIGCOMPLEXOBJ handle of
result data */
...
IG_FIP_DCT_forward(hIGComplexObj, &hIGComplexObjOut);
...

Sample:

FreqIP


²IG_FIP_DCT_forward_from_image

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_DCT_forward_from_image(HIGEAR
hIGear, LPHIGCOMPLEXOBJ lphIGComplexObj);

Arguments (with description):

hIGear
HIGEAR handle of image to be processed.
lphIGComplexObj
HIGCOMPLEXOBJ handle of result data.

Description:

This function computes the forward Discrete Cosine Transform (DCT) of the input image. The difference between this function and IG_FIP_DCT_forward() is that this function takes a HIGEAR as the input.

Bits Per Pixel:

8, 16, 32-bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;				/* HIGEAR handle of input image */
HIGCOMPLEXOBJ hIGComplexObjOut;	/* HIGCOMPLEXOBJ handle of
output data */
...
IG_FIP_DCT_forward_from_image(hIGear, &hIGComplexObjOut);
...

Sample:

FreqIP


IG_FIP_DCT_inverse

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_DCT_inverse(HIGCOMPLEXOBJ
hIGComplexObj, LP HIGCOMPLEXOBJ lphIGComplexObjOut);

Arguments:

hIGComplexObj
HIGCOMPLEXOBJ handle of data to be processed.
lphIGComplexObjOut
HIGCOMPLEXOBJ handle of result data.

Description:

This function computes the inverse Discrete Cosine Transform of the input HIGCOMPLEXOBJ data.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGCOMPLEXOBJ hIGComplexObj;		/* HIGCOMPLEXOBJ handle of input
data */
HIGCOMPLEXOBJ hIGComplexObjOut;		/* HIGCOMPLEXOBJ handle of
output data */
...
IG_FIP_DCT_inverse(hIGComplexObj, &hIGComplexObjOut);
...

Sample:

FreqIP


IG_FIP_DCT_inverse_to_image

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_DCT_inverse_to_image(HIGCOMPLEXOBJ
hIGComplexObj, LPHIGEAR lphIGear);

Arguments:

hIGComplexObj
HIGCOMPLEXOBJ handle of data to be processed.
lphIGear
HIGEAR handle of result image.

Description:

This function computes the inverse Discrete Cosine Transform of the input HIGCOMPLEXOBJ data. The difference between this function and IG_FIP_DCT_inverse() is that this function returns a HIGEAR as the result, using the default conversion type IG_FIPDATA_CONV_TYPE_REAL.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGCOMPLEXOBJ hIGComplexObj;	/* HIGCOMPLEXOBJ handle of input
data */
HIGEAR hIGear;				/* HIGEAR handle of output image */
...
IG_FIP_DCT_inverse_to_image(hIGComplexObj, &hIGear);
...

Sample:

FreqIP


IG_FIP_DST_forward

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_DST_forward(HIGCOMPLEXOBJ
hIGComplexObj, LP HIGCOMPLEXOBJ lphIGComplexObjOut);

Arguments:

hIGComplexObj
HIGCOMPLEXOBJ handle of data to be processed.
lphIGComplexObjOut
HIGCOMPLEXOBJ handle of result data.

Description:

This function computes the forward Discrete Sine Transform (DST) of the input HIGCOMPLEXOBJ data.

Bits per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGCOMPLEXOBJ hIGComplexObj;	/* HIGCOMPLEXOBJ handle of input
image */
HIGCOMPLEXOBJ hIGComplexObjOut;	/* HIGCOMPLEXOBJ handle of
output image */
...
IG_FIP_DST_forward(hIGComplexObj, &hIGComplexObjOut);
...

Sample:

FreqIP


²IG_FIP_DST_forward_from_image

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_DST_forward_from_image(HIGEAR
hIGear, LP HIGCOMPLEXOBJ lphIGComplexObj);

Arguments:

hIGear
HIGEAR handle of image to be processed.
lphIGComplexObj
HIGCOMPLEXOBJ handle of result data.

Description:

This function computes the forward Discrete Sine Transform (DST) of the input image. The difference between this function and IG_FIP_DST_forward() is that this function takes a HIGEAR as the input.

Bits Per Pixel:

8, 16, 32-bit grayscale images with one channel

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGEAR hIGear;				/* HIGEAR handle of input image */
HIGCOMPLEXOBJ hIGComplexObjOut;	/* HIGCOMPLEXOBJ handle of
output data */
...
IG_FIP_DST_forward_from_image(hIGear, &hIGComplexObjOut);
...

Sample:

FreqIP


IG_FIP_DST_inverse

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_DST_inverse(HIGCOMPLEXOBJ
hIGComplexObj, LPHIGCOMPLEXOBJ lphIGComplexObjOut);

Arguments:

hIGComplexObj
HIGCOMPLEXOBJ handle of data to be processed.
lphIGComplexObjOut
HIGCOMPLEXOBJ handle of result data.

Description:

This function computes the inverse Discrete Sine Transform of the input HIGCOMPLEXOBJ data.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGCOMPLEXOBJ hIGComplexObj;		/* HIGCOMPLEXOBJ handle of input
data */
HIGCOMPLEXOBJ hIGComplexObjOut;		/* HIGCOMPLEXOBJ handle of
output data */
...
IG_FIP_DST_inverse(hIGComplexObj, &hIGComplexObjOut);
...

Sample:

FreqIP


IG_FIP_DST_inverse_to_image

Group: Frequency Domain Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_DST_inverse_to_image(HIGCOMPLEXOBJ
hIGComplexObj, LPHIGEAR lphIGear);

Arguments:

hIGComplexObj
HIGCOMPLEXOBJ handle of data to be processed.
lphIGear
HIGEAR handle of result image.

Description:

This function computes the inverse Discrete Sine Transform of the input image. The difference between this function and IG_FIP_DST_inverse() is that this function returns a HIGEAR as the result, using the default conversion type IG_FIPDATA_CONV_TYPE_REAL.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Example:

HIGCOMPLEXOBJ hIGComplexObj;		/* HIGCOMPLEXOBJ handle of input
data */
HIGEAR hIGear;					/* HIGEAR handle of output image */
...
IG_FIP_DST_inverse_to_image(hIGComplexObj, &hIGear);
...

Sample:

FreqIP


HIGCOMPLEXOBJ

Type: Complex Object

Description:

Handle to the complex object.

Objects of this type can store both real and imaginary part of complex data, which is stored internally using double precision, rather than one of the integral types as in HIGEAR. Objects of this type can be used as input or output for frequency domain image processing functions so as to keep the precision of the data.

Class Members:

IG_FIP_co_obj_create
Create a complex object.
IG_FIP_co_obj_create_empty
Create a complex object, with empty but allocated buffers.
IG_FIP_co_obj_delete
Delete a complex object.
IG_FIP_co_obj_is_valid
Check whether a handle points to a valid complex object.
IG_FIP_co_obj_row_pointers_get
Get the pointers to the beginning of data buffer for the specified row.
IG_FIP_co_obj_dimensions_get
Get dimensions of the object.
IG_FIP_co_obj_to_image
Convert a complex object to a HIGEAR object.


IG_FIP_co_obj_create

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_co_obj_create(HIGCOMPLEXOBJ *
lphIGComplexObj, HIGEAR hIGearRe, HIGEAR hIGearIm);

Arguments (with description):

lphIGComplexObj
Handle to return the newly created object.
hIGearRe
Handle pointing to an image to be used as the real part of the newly created object.
hIGearIm
Handle pointing to an image to be used as the imaginary part of the newly created object.

Description:

This function creates a new object based on the given hIGearRe and hIGearIm.

The dimension of the newly created object is determined by the width and height of hIGearRe and hIGearIm. If hIGearIm is not NULL, this function requires hIGearRe and hIGearIm to have the same width and height; otherwise, the width and height of hIGearRe is used.

Data from hIGearRe and hIGearIm is then used respectively to populate the real and imaginary buffer in the newly created object.

NOTE: hIGearRe and hIGearIm should only have one channel with bit depth being 8, 16 or 32.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FIP_co_obj_create_empty

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_co_obj_create_empty(HIGCOMPLEXOBJ *
lphIGComplexObj, AT_DIMENSION width, AT_DIMENSION height);

Arguments (with description):

lphIGComplexObj
Handle to return the newly created object.
Width
Width of the object to be created.
Height
Height of the object to be created.

Description:

This function creates a new object with empty but allocated buffers, based on the given width and height. The buffers can be populated later by obtaining pointers to the buffers.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FIP_co_obj_delete

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_co_obj_delete(HIGCOMPLEXOBJ
hIGComplexObj);

Arguments (with description):

hIGComplexObj
Handle to the object to be deleted.

Description:

This function deletes the object referenced by hIGComplexObj and frees all the memory associated with it.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FIP_co_obj_is_valid

Declaration:

AT_BOOL ACCUAPI IG_FIP_co_obj_is_valid(HIGCOMPLEXOBJ
hIGComplexObj);

Arguments (with description):

hIGComplexObj
Handle to the object to be checked for validity.

Description:

This function checks to see whether handle hIGComplexObj points to a valid complex object. Note that the return type of the function is AT_BOOL, not AT_ERRCOUNT.

Return Value:

True/False.


IG_FIP_co_obj_row_pointers_get

Declaration:

AT_ERRCOUNT ACCUAPI
IG_FIP_co_obj_row_pointers_get(HIGCOMPLEXOBJ hIGComplexObj,
AT_INT rowNum, AT_DOUBLE ** lplpReal, AT_DOUBLE **
lplpImaginary);

Arguments (with description):

hIGComplexObj
Handle to the object to get data pointers from.
rowNum
Index of the row to get data pointers for.
lplpReal
Returns the pointer to the real buffer at the specified row.
lplpImaginary
Returns the pointer to the imaginary buffer at the specified row.

Description:

This function gets pointers to the beginning of data buffers for the given row.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FIP_co_obj_dimensions_get

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_co_obj_dimensions_get(HIGCOMPLEXOBJ
hIGComplexObj, LPAT_DIMENSION lpWidth, LPAT_DIMENSION
lpHeight);

Arguments (with description):

hIGComplexObj
Handle to the object to get dimensions for.
lpWidth
Returns the width of the object.
lpHeight
Returns the height of the object.

Description:

This function obtains the width and height of the given object.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_FIP_co_obj_to_image

Declaration:

AT_ERRCOUNT ACCUAPI IG_FIP_co_obj_to_image(HIGCOMPLEXOBJ
hIGComplexObj, HIGEAR * lphIGear, enumIGCoObjConvType
nConvType, LPAT_DOUBLE lpMinimum, LPAT_DOUBLE lpScale);

Arguments (with description):

hIGComplexObj
Handle to the object to be converted to HIGEAR.
lphIGear
Returns the converted HIGEAR object.
nConvType
Conversion type used to convert the object to HIGEAR. Constants IG_CO_OBJ_CONV_TYPE_* are listed in file i_FreqIP.h.
lpMinimum
Returns the minimum value of the data before scaling.
lpScale
Returns the scale factor.

Description:

This function converts a complex object to a HIGEAR object, using the conversion type specified by parameter nConvType. A complex object should be converted to HIGEAR only for displaying purpose, otherwise, it should remain in its original format to retain the data accuracy.

Because a HIGCOMPLEXOBJ object contains both real and imaginary data, we need to first combine these two data sets into one in order to store the result in a HIGEAR object, using the option specified by the parameter nConvType. Options available include IG_CO_OBJ_CONV_TYPE_REAL, IG_CO_OBJ_CONV_TYPE_IMAGINARY, IG_CO_OBJ_CONV_TYPE_MAGNITUDE, etc. Please see the help page for enumIGCoObjConvType for details.

The dimensions of the converted HIGEAR object are determined by those of the complex object, with width and height being the same. The depth of the HIGEAR object can be 8, 16 or 32, depending on the image size. If the image size is less than or equal to (1 << 8), then the depth will be 8bit; less than or equal to (1 << 16), then 16bit; otherwise, the depth will be 32bit. Of course, the HIGEAR object will only have one channel.

Once the bit depth is determined, data are then scaled linearly to occupy the entire range of that bit depth and copied to the buffer of HIGEAR. Minimum value before scaling and scale factor can be returned through lpMinimum and lpScale parameters if wanted, so as to provide a coarse way to reconstruct the data.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


enumIGCoObjConvType

Group: Enumeration

Description:

These constants define the conversion types to convert a HIGCOMPLEXOBJ object to a HIGEAR object.

Values (with description):

IG_CO_OBJ_CONV_TYPE_REAL
0
Use the real data.
IG_CO_OBJ_CONV_TYPE_IMAGINARY
1
Use the imaginary data.
IG_CO_OBJ_CONV_TYPE_MAGNITUDE
2
Use the magnitude data.
IG_CO_OBJ_CONV_TYPE_PHASE
3
Use the phase data.
IG_CO_OBJ_CONV_TYPE_LOGMAG
4
Use the logarithm (10) of the magnitude data.
IG_CO_OBJ_CONV_TYPE_LOGMAGP1
5
Use the logarithm (10) of (magnitude data + 1).
IG_CO_OBJ_CONV_TYPE_MAGSQ
6
Use the square of the magnitude.
IG_CO_OBJ_CONV_TYPE_LOGMAGSQ
7
Use the logarithm (10) of the square of the magnitude.
IG_CO_OBJ_CONV_TYPE_LOGMAGSQP1
8
Use the logarithm (10) of (square of the magnitude + 1).


enumIGFFTScalingMethods

Group: Enumeration

Description

These constants define the different scaling methods for the result of Fast Fourier Transform (FFT).

Values

IG_FFT_SCALING_UNITY
0
Unity scaling, i.e., no scaling on the result
IG_FFT_SCALING_N
1
Scale by 1/N on each dimension
IG_FFT_SCALING_SQRTN
2
Scale by 1/sqrt(N) on each dimension


enumIGFreqIPFilterBrands

Group: Enumeration

Description

These constants define the different kind of filter brands available.

Values

IG_FREQIP_FILTER_BRAND_IDEAL
0
Ideal Filter
IG_FREQIP_FILTER_BRAND_BUTTERWORTH
1
Butterworth Filter
IG_FREQIP_FILTER_BRAND_GAUSSIAN
2
Gaussian Filter
IG_FREQIP_FILTER_BRAND_CHEBYSHEV_I
3
Type 1 Chebyshev Filter
IG_FREQIP_FILTER_BRAND_CHEBYSHEV_II
4
Type 2 Chebyshev Filter


GUI Component API Function Reference

In this Chapter you can get the detailed information about all ImageGear GUI dialogs functions:

  • GUI Dialogs Reference


GUI Dialogs Reference

The ImageGear GUI provides a set of common dialog boxes that combine Windows Common Dialog functionality with ImageGear imaging functionality. Dialogs are provided for file opening/saving, color resolution, image processing/filtering, and effects.

The ImageGear GUI greatly simplifies development and saves hours of tedious programming by extending Windows common dialogs to provide imaging-specific capabilities. The component provides professional common imaging dialogs such as image processing, conversion, and special effects. Thumbnail previewing of image changes saves processing time and avoids "undos".

The ImageGear GUI also provides input dialog boxes for the most common ImageGear image processing functions. These dialogs allow you to quickly and easily enable your application to gather input from end-users for the parameters required by the various ImageGear functions. These dialogs can also be used to automatically process the image based on end-user input (thus reducing the amount of code you have to write).

The name of the DLL GUI is igguid.dll. If you use the ImageGear GUI in your ImageGear application, then it is necessary to include this file with your distribution when you deploy your application.

The functions are presented in alphabetical order.


IG_gui_about_dlg

Declaration:

BOOL  ACCUAPI  IG_gui_about_dlg (
    HWND	hWnd,
    LPCHAR	lpszTitle
    );

Arguments:

hWnd
a handle of the parent window
lpszTitle
A title string for ABOUT dialog window.

Purpose:

This function displays ABOUT dialog with basic information about version of ImageGear product. First argument is used as handle for parent window and second for dialog title.

Return Value:

Returns TRUE if OK button is pressed, FALSE - otherwise.

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_clbk_wnd

Declaration:

HWND  ACCUAPI  IG_gui_clbk_wnd(
    HWND        hWnd
    );

Arguments:

hWnd
a handle of the parent window

Purpose:

This function sets callback functions of types LPAFT_IG_METAD_ITEM_SET_CB, LPAFT_IG_METAD_ITEM_ADD_CB and LPAFT_IG_METAD_ITEM_GET_CB, and uses IG_fltr_metad_callback_set ()/IG_fltr_metad_callback_get () functions to manage callback data. It creates a window that displays all this information after filter load operartion and allows to modify this data to be saved with filter save operation. If window is not necessary anymore it can be deleted with all associated information using function DestroyWindow.

Return Value:

Returns a handle of the created window or if the function fails, the return value is NULL.

Sample: Filters, GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_colormismatch_warning

Declaration:

VOID ACCUAPI IG_gui_colormismatch_warning(HWND hWnd, HIGEAR
hIGear);

Arguments:

hWnd
(in) A handle to the parent window.
hIGear
(in) A handle to the image to check whether it has embedded color profile, or has non-RGB color format.

Description:

This function performs several checks to determine whether to show a color mismatch warning dialog, as follows:

The warning dialog will be shown if all of the following are true.

  1. The registry entry for "show color mismatch warning" is enabled.
  2. The ICC support is currently disabled.
  3. The given image either has embedded color profile, or has non-RGB color format.

Bits Per Pixel:

All

Return Value:

None

Example:

HWND hWnd;		/* Handle to the parent window */
HIGEAR hIGear;		/* Handle of the image to check*/
/* Warn to enable ICC support if there is color mismatch */
IG_gui_colormismatch_warning(hWnd, hIGear);
...

Sample:

IMG_PROC


IG_gui_comm_attach_dlg

Declaration:

BOOL  ACCUAPI  IG_gui_comm_attach_dlg(
    HWND	hWndParent
    )

Arguments:

hWnd
a handle of the parent window

Purpose:

This function activates dialog window that alows you to attach the component you want.

Return Value:

Returns TRUE if component is attached, FALSE - otherwise.

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_comm_info_dlg

Declaration:

VOID  ACCUAPI  IG_gui_comm_info_dlg(
    HWND	hWndParent
    )

Arguments:

hWnd
a handle of the parent window

Purpose:

This function displays dialog that provides information about currently attached components.

Return Value:

None.

Sample: All

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_compname_get

Declaration:

VOID  ACCUAPI  IG_gui_compname_get(
    AT_MODE	nCompression,
    LPCHAR	lpStr,
    DWORD	dwSize
    );

Arguments:

nCompression
The ImageGear compression constant by type IG_COMPRESSION_.
lpStr
String representation of compression constant specified by nCompression argument.
dwSize
The buffer size of lpStr argument.

Purpose:

This function returns textual name for compression constants. It accepts IG_COMPRESSION_... constant by the first argument and returns its string representation by the second argument. Third dwSize argument is used to provide lpStr buffer size.

Return Value:

None.

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_decimalstr_convert

Declaration:

VOID  ACCUAPI  IG_gui_decimalstr_convert(
    DWORD	 dwValue,
    LPCHAR 	lpStr,
    UINT	 nStrBufferSize
    );

Arguments:

dwValue
Any digital value
lpStr
The string of converted dwValue in format "XXX,XXX,XXX,XXX".
nStrBufferSize
he size of lpStr buffer.

Purpose:

This function can be used to convert digital value to string in format "XXX,XXX,XXX,XXX" with "," separator after each 3 digits starting from the end. Second parameter is a buffer where to return data and last parameter is a size of buffer.

Return Value:

None.

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_dibname_get

Declaration:

VOID  ACCUAPI  IG_gui_dibname_get(
    DWORD	 dwFormat,
    LPCHAR	 lpStr,
    DWORD	 dwSize
    );

Arguments:

nCompression
The ImageGear compression constant by type IG_COMPRESSION_.
lpStr
String representation of compression constant specified by nCompression argument.
dwSize
The buffer size of lpStr argument.

Purpose:

This function return textual name for DIB format constants. It accepts IG_BI_... constants by first parameter and return string representation via second. Last parameter - size of lpStr buffer.

Return Value:

None.

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_dspl_antialias_dlg

Declaration:

BOOL ACCUAPI IG_gui_dspl_antialias_dlg (
    HWND				hWnd,
    LPAT_IGGUI_DSPL_ANTIALIAS				lpDsplAntialiasData
    );

Arguments:

hWnd
a handle of the parent window
lpDsplAntialiasData
a pointer to the following structure:
AT_IGGUI_DSPL_ANTIALIAS

Structure declaration:

typedef struct tag AT_IGGUI_DSPL_ANTIALIAS
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    DWORD			dwGrpID;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_ERRCOUNT 			nErrCount;
    LPFNIGGUI_DSPL_UPDATE			 lpfnUpdateProc;
    } AT_IGGUI_DSPL_RECT;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
dwGrpID
an identifier of the group from which to get display options
hWnd
a handle of the window to update
lpszTitle
a dialog title
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows a dialog that allows you to change the current anti-alias settings.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_DSPL_ANTIALIAS DsplAntialias;
memset (&DsplAntialias,0,sizeof(DsplAntialias));
DsplAntialias.cbSize = sizeof (DsplAntialias);
DsplAntialias.hWnd = hWnd;
DsplAntialias.hIGear = hIGear;
DsplAntialias.dwGrpID = nGrpID;
IG_gui_dspl_antialias_dlg (hWnd, &DsplAntialias);
InvalidateRect (hWnd,NULL,FALSE);
UpdateWindow (hWnd);

Sample: DISPLAY, IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_dspl_aspect_dlg

Declaration:

BOOL ACCUAPI IG_gui_dspl_aspect_dlg (
    HWND			hWnd,
    LPAT_IGGUI_DSPL_ASPECT			lpDsplAspectData
);

Arguments:

hWnd
a handle of the parent window
lpDsplAspectData
a pointer to the following structure:
AT_IGGUI_DSPL_ASPECT

Structure declaration:

typedef struct tag AT_IGGUI_DSPL_ASPECT
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    DWORD			dwGrpID;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_ERRCOUNT			nErrCount;
    LPFNIGGUI_DSPL_UPDATE			lpfnUpdateProc;
}AT_IGGUI_DSPL_ASPECT;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
dwGrpID
an identifier of the group from which to get display options
hWnd
a handle of the window to update
lpszTitle
a dialog title
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to change the current aspect settings.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_DSPL_ASPECT DsplAspect;
memset (&DsplAspect,0,sizeof(DsplAspect));
DsplAspect.cbSize = sizeof (DsplAspect);
DsplAspect.hWnd = hWnd;
DsplAspect.hIGear = hIGear;
DsplAspect.dwGrpID = nGrpID;
IG_gui_dspl_aspect_dlg (hWnd, &DsplAspect);
InvalidateRect (hWnd,NULL,FALSE);
UpdateWindow (hWnd);

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_dspl_background_dlg

Declaration:

BOOL ACCUAPI IG_gui_dspl_background_dlg (
    HWND				hWnd,
    LPAT_IGGUI_DSPL_BACKGROUND				lpDsplBackgroundData
    );

Arguments:

hWnd
a handle of the parent window
lpDsplBackgroundData
a pointer to the following structure:
AT_IGGUI_DSPL_BACKGROUND

Structure declaration:

typedef struct tag AT_IGGUI_DSPL_BACKGROUND
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    DWORD			dwGrpID;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_ERRCOUNT			nErrCount;
    LPFNIGGUI_DSPL_UPDATE			lpfnUpdateProc;
}AT_IGGUI_DSPL_BACKGROUND;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
dwGrpID
an identifier of the group from which to get display options
hWnd
a handle of the window to update
lpszTitle
a dialog title
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to change the background color or image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero:

Example:

#include "IG_gui_common.h"
AT_IGGUI_DSPL_BACKGROUND DsplBackground;
memset (&DsplBackground,0,sizeof(DsplBackground));
DsplBackground.cbSize = sizeof (DsplBackground);
DsplBackground.hWnd = hWnd;
DsplBackground.hIGear = hIGear;
DsplBackground.dwGrpID = nGrpID;
IG_gui_dspl_background_dlg (hWnd, &DsplBackground);
InvalidateRect (hWnd,NULL,FALSE);
UpdateWindow (hWnd);

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_dspl_dithering_dlg

Declaration:

BOOL ACCUAPI IG_gui_dspl_dithering_dlg (
    HWND				hWnd,
    LPAT_IGGUI_DSPL_DITHERING				lpDsplDitheringData
    );

Arguments:

hWnd
a handle of the parent window
lpDsplDitheringData
a pointer to the following structure:
AT_IGGUI_DSPL_DITHERING

Structure declaration:

typedef struct tag AT_IGGUI_DSPL_DITHERING
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    DWORD			dwGrpID;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_DSPL_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_DSPL_DITHERING;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
dwGrpID
an identifier of the group from which to get display options
hWnd
a handle of the window to update
lpszTitle
a dialog title
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to set dithering options for the given image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.Example:

#include "IG_gui_common.h"
AT_IGGUI_DSPL_DITHERING DsplDithering;
memset (&DsplDithering,0,sizeof(DsplDithering));
DsplDithering.cbSize = sizeof (DsplDithering);
DsplDithering.hWnd = hWnd;
DsplDithering.hIGear = hIGear;
DsplDithering.dwGrpID = nGrpID;
IG_gui_dspl_dithering_dlg (hWnd, &DsplDithering);
InvalidateRect (hWnd,NULL,FALSE);
UpdateWindow (hWnd);

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_dspl_gamma_correction_dlg

Declaration:

BOOL ACCUAPI IG_gui_dspl_gamma_correction_dlg (
    HWND					hWnd,
    LPAT_IGGUI_DSPL_GAMMA_CORRECTION					 lpDsplGammaCorrectionData
    );

Arguments:

hWnd
a handle of the parent window
lpDsplGammaCorrectionData
a pointer to the following structure:
AT_IGGUI_DSPL_GAMMA_CORRECTION

Structure declaration:

typedef struct tag AT_IGGUI_DSPL_GAMMA_CORRECTION
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    DWORD			dwGrpID;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    DOUBLE			dblBrightness;
    DOUBLE			dblContrast;
    DOUBLE			dblGamma;
    AT_ERRCOUNT	 		nErrCount;
    LPFNIGGUI_DSPL_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_DSPL_GAMMA_CORRECTION;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
dwGrpID
an identifier of the group from which to get display options
hWnd
a handle of the window to update
lpszTitle
a dialog title
dblBrightness
a brightness value to use in calculations. Must be in the range from 255.0 to +255.0
dblContrast
a contrast value to use in calculations. Any possible value can be set
dblGamma
a gamma value to use in calculations. Must be greater than 0.0, however the most useful values are in the range from 1.8 to 2.2
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to set LUT tables for the given image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_DSPL_GAMMA_CORRECTION DsplGamma;
memset (&DsplGamma,0,sizeof(DsplGamma));
DsplGamma.cbSize = sizeof (DsplGamma);
DsplGamma.hWnd = hWnd;
DsplGamma.hIGear = hIGear;
DsplGamma.dwGrpID = nGrpID;
IG_gui_dspl_gamma_correction_dlg (hWnd, &DsplGamma);
InvalidateRect (hWnd,NULL,FALSE);
UpdateWindow (hWnd);

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_dspl_rect_dlg

Declaration:

BOOL ACCUAPI IG_gui_dspl_rect_dlg (
    HWND			hWnd,
    LPAT_IGGUI_DSPL_RECT			lpDsplRectData
    );

Arguments:

hWnd
a handle of the parent window
lpDsplRectData
a pointer to the following structure:
AT_IGGUI_DSPL_RECT

Structure declaration:

typedef struct tag AT_IGGUI_DSPL_RECT
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    DWORD			dwGrpID;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    UINT			uRectType;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_DSPL_UPDATE			 lpfnUpdateProc;
} AT_IGGUI_DSPL_RECT;

Structure members:

:
cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
dwGrpID
an identifier of the group from which to get display options
hWnd
a handle of the window to update
lpszTitle
a dialog title
uRectType
a type of rectangle (image, device or clip)
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to change an image (device, clipping) rectangle.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_DSPL_RECT DsplRect;
memset (&DsplRect,0,sizeof(DsplRect));
DsplRect.cbSize = sizeof (DsplRect);
DsplRect.hWnd = hWnd;
DsplRect.hIGear = hIGear;
DsplRect.dwGrpID = nGrpID;
DsplRect.uRectType = IG_IGGUI_DSPL_RECTTYPE_IMAGE;
IG_gui_dspl_rect_dlg (hWnd, &DsplRect);
InvalidateRect (hWnd,NULL,FALSE);
UpdateWindow (hWnd);

Sample: DISPLAY, ART

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_dspl_scroll_dlg

Declaration:

BOOL ACCUAPI IG_gui_dspl_scroll_dlg (
    HWND			hWnd,
    LPAT_IGGUI_DSPL_SCROLL			 lpDsplScrollData
    );

Arguments:

hWnd
a handle of the parent window
lpDsplScrollData
a pointer to the following structure:
AT_IGGUI_DSPL_SCROLL

Structure declaration:

typedef struct tag AT_IGGUI_DSPL_SCROLL
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    DWORD			dwGrpID;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_DSPL_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_DSPL_SCROLL;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
dwGrpID
an identifier of the group from which to get display options
hWnd
a handle of the window to update
lpszTitle
a dialog title
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to customize scrolling options for the given image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_DSPL_SCROLL DsplScroll;
memset (&DsplScroll,0,sizeof(DsplScroll));
DsplScroll.cbSize = sizeof (DsplScroll);
DsplScroll.hWnd = hWnd;
DsplScroll.hIGear = hIGear;
DsplScroll.dwGrpID = nGrpID;
IG_gui_dspl_scroll_dlg (hWnd, &DsplScroll);
InvalidateRect (hWnd,NULL,FALSE);
UpdateWindow (hWnd);

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_dspl_transparency_dlg

Declaration:

BOOL ACCUAPI IG_gui_dspl_transparency_dlg (
    HWND				hWnd,
    LPAT_IGGUI_DSPL_TRANSPARENCY				lpDsplTransparencyData
    );

Arguments:

hWnd
a handle of the parent window
lpDsplTransparencyData
a pointer to the following structure:
AT_IGGUI_DSPL_TRANSPARENCY

Structure declaration:

typedef struct tag AT_IGGUI_DSPL_TRANSPARENCY
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    DWORD			dwGrpID;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_DSPL_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_DSPL_TRANSPARENCY;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
dwGrpID
an identifier of the group from which to get display options
hWnd
a handle of the window to update
lpszTitle
a dialog title
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to set transparency settings for the given image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_DSPL_TRANSPARENCY DsplTransparency;
memset (&DsplTransparency,0,sizeof(DsplTransparency));
DsplTransparency.cbSize = sizeof (DsplTransparency);
DsplTransparency.hWnd = hWnd;
DsplTransparency.hIGear = hIGear;
DsplTransparency.dwGrpID = nGrpID;
IG_gui_dspl_transparency_dlg (hWnd, &DsplTransparency);
InvalidateRect (hWnd,NULL,FALSE);
UpdateWindow (hWnd);

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_dspl_zoom_dlg

Declaration:

BOOL ACCUAPI IG_gui_dspl_zoom_dlg (
    HWND			hWnd,
    LPAT_IGGUI_DSPL_ZOOM			 lpDsplZoomData
    );

Arguments:

hWnd
a handle of the parent window
lpDsplZoomData
a pointer to the following structure:
AT_IGGUI_DSPL_ZOOM

Structure declaration:

typedef struct tag AT_IGGUI_DSPL_ZOOM
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    DWORD			dwGrpID;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_DSPL_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_DSPL_ZOOM;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
dwGrpID
an identifier of the group from which to get display options
hWnd
a handle of the window to update
lpszTitle
a dialog title
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to customize zooming options for the given image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_DSPL_ZOOM DsplZoom;
memset (&DsplZoom,0,sizeof (DsplZoom));
DsplZoom.cbSize = sizeof (DsplZoom);
DsplZoom.hWnd = hWnd;
DsplZoom.hIGear = hIGear;
DsplZoom.dwGrpID = nGrpID;
IG_gui_dspl_zoom_dlg (hWnd, &DsplZoom);
InvalidateRect (hWnd,NULL,FALSE);
UpdateWindow (hWnd);

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_errdescr_get

Declaration:

BOOL  ACCUAPI  IG_gui_errdescr_get(
    AT_ERRCODE		 nErrCode,
    LPCHAR		lpStr,
    UINT		nStrSize
    );

Arguments:

nErrCode
Specifies error code
lpStr
A pointer to string to return text description
nStrSize
A number of characters to be copied

Purpose:

This function retrieve text description of the error constant.

Return Value:

Returns non-zero value in the case of success. If the error code is not found, the return value is zero.

Example:

AT_ERRCODE  nErrCode;  /* Error Code  */
CHAR        Str[50];   /* Error description  */
UINT        nStrSize = 50; /*  Size of the error description
string  */
BOOL        bRet;
// init nErrCode
...
bRet = IG_gui_errdescr_get( nErrCode, &Str, nStrSize );

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_errstack_wnd

Declaration:

HWND ACCUAPI  IG_gui_errstack_wnd (
    HWND	hWnd,
    DWORD	dwFlags
    );

Arguments:

hWnd
a handle of the parent window
dwFlags
a set of bit flags you can use to initialize the window

Purpose:

Creates a return handle of a new error stack window.

Return Value:

Returns the handle of the error window.

Example:

#include "IG_gui_common.h"
IG_gui_errstack_wnd (hWnd,IG_GUI_ERRCTRL_DEFSTACK);

Sample: ASCII, CLPBRD, COLOR, GUIWIN, IMG_PROC, IMGUTIL,

IOSET, JPEG, LoadCB, MAGNIFY, MDI, MEMIO, PAGE,

PALEDT, PAN, PIX_ACC, POSTER, THUMB,

WIPES, MULTPAGE, ART, Vector, FILTER, IC,

MULTIMED, Scan, TWAIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_errstack_opt_dlg

Declaration:

HWND ACCUAPI  IG_gui_errstack_opt_dlg (
    HWND		hWnd,
    DWORD		hCtrl
    );

Arguments:

hWnd
a handle of the parent window
hCtrl
a set of control options you can use to control the error stack GUI window

Purpose:

This function displays the dialog that allows to set control options for error stack GUI window.

Return Value:

Returns the handle of the error window.

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_file_info_dlg

Declaration:

VOID ACCUAPI IG_gui_file_info_dlg (
    HWND		hWnd,
    LPCHAR		lpFileName,
    UINT		nPage
    );

Arguments:

hWnd
a handle of the parent window
lpFileName
a pointer to the file name buffer
nPage
page number to get info about

Purpose:

Show dialog with file image information including different parameters of pages of the image.

Return Value None

Example:

#include "IG_gui_common.h"
IG_gui_file_info_dlg (hWnd, szFile, 0);

Sample: COLOR, DISPLAY, GUIWIN, IMG_PROC, JPEG,

MAGNIFY, MDI, MEMIO, PALEDT, PIX_ACC,

PRINT, ART, Vector, FILTER, IC, Scan, TWAIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_filters_dlg

Declaration:

BOOL  ACCUAPI  IG_gui_filters_dlg(
    HWND	hWnd
    );

Arguments:

hWnd
a handle of the parent window

Purpose:

This function displays dialog that provides all information about available format filters along with control parameters in textual format. It allows also to set new values to control parameters of format filters to customer's value as well as reset to defaults.

Return Value:

Returns TRUE if user pressed OK button, FALSE - otherwise.

Sample: All

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_format_filter_get

Declaration:

VOID  ACCUAPI  IG_gui_format_filter_get(
    LPAT_MODE		lpFormatList,
    UINT		nFListSize,
    BOOL		bShortName,
    LPBYTE		lpFilter,
    UINT		nFilterSize
    );

Arguments:

lpFormatList
An array of IG_FORMAT_ constants. Please see accucnst.h file for the full list of these constants.
nFListSize
The number of elements in lpFormatList array.
bShortName
If this argument is TRUE then short names of file formats are used in lpFilter list. If it is FALSE - long names are used.
lpFilter
The list of formats with default extensions.
nFilterSize
The size of lpFilter buffer.

Purpose:

This function is used to generate textual representation of file format IDs list. The first argument is an array of IG_FORMAT_... constants. The second contains number of elements in lpFormatList array. The third argument is used to select either short or long name of file format. The lpFilter argument should contain buffer large enough to store the list of formats with default extensions. The format of this data is exact to be passed directly to standard OPEN or SAVE dialog with function GetOpenFileName as value of lpstrFilter field in OPENFILENAME structure.

Return Value:

None.

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_add_noise_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_add_noise_dlg (
    HWND				hWnd,
    LPAT_IGGUI_FX_ADD_NOISE				lpFxAddNoiseData
    );

Arguments:

hWnd
a handle of the parent window
lpFxAddNoiseData
a pointer to the following structure:
AT_IGGUI_FX_ADD_NOISE

Structure declaration:

typedef struct tag AT_IGGUI_FX_ADD_NOISE
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		        rc;
    WORD			nType;
    DOUBLE			dblStrength;
    INT			nHitRate;
    DOUBLE			dblSigma;
    AT_MODE			nColorChannel;
    AT_ERRCOUNT	 		nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_ADD_NOISE;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of image to be processed
nType
an IG_NOISE constant such as IG_NOISE_LINEAR, IG_NOISE_GAUSSIAN
dblStrength
from 0.0 to 127.0, specifying the degree of noise alteration to introduce into affected pixels
nHitRate
Set = 1 to add noise to all pixels, > 1 to skip pixels, only adding noise to some. Larger values cause fewer pixels to be affected. Valid range is from 1 to 500
dblSigma
Used with IG_NOISE_GAUSSIAN; the valid range is from 0.1 to 25.0
nColorChannel
an IG_COLOR_COMP_ constant. See file accucnst.h for a complete list
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to create noise in an image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_ADD_NOISE FxAddNoise;
FxAddNoise.cbSize = sizeof (FxAddNoise);
FxAddNoise.hWnd = hWnd;
FxAddNoise.hIGear = hIGear;
FxAddNoise.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_add_noise_dlg (hWnd, &FxAddNoise))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_blur_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_blur_dlg (
    HWND			hWnd,
    LPAT_IGGUI_FX_BLUR			lpFxBlurData
    );

Arguments:

hWnd
a handle of the parent window
lpFxBlurData
a pointer to the following structure:
AT_IGGUI_FX_BLUR

Structure declaration:

typedef struct tag AT_IGGUI_FX_BLUR
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		 rc;
    AT_MODE			nBlurMode;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_BLUR;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
nBlurMode
A constant such as IG_BLUR_3 specifying the kernel size to use to perform the blurring. See file accucnst.h for the IG_BLUR_ constants available
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to make an image appear to be blurred.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_BLUR FxBlur;
FxBlur.cbSize = sizeof (FxBlur);
FxBlur.hWnd = hWnd;
FxBlur.hIGear = hIGear;
FxBlur.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_blur_dlg (hWnd, &FxBlur))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_chroma_key_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_chroma_key_dlg (
    HWND				hWnd,
    LPAT_IGGUI_FX_CHROMA_KEY				lpFxChromaKeyData
    );

Arguments:

hWnd
a handle of the parent window
lpFxChromaKeyData
a pointer to the following structure:
AT_IGGUI_FX_CHROMA_KEY

Structure declaration:

typedef struct tag AT_IGGUI_FX_BLUR
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		        rc;
    CHAR			szBkFileName[_MAX_PATH];
    DOUBLE			dblHueCenter;
    DOUBLE			dblHueRange;
    UINT			nSmooth;
    UINT			nIntensity;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_FX_UPDATE	 lpfnUpdateProc;
}AT_IGGUI_FX_CHROMA_KEY;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
szBkFileName
a file name of the image from which to insert the hue match
dblHueCenter
an angle in degrees (in the standard Color Wheel) of the hue to match. 0.0 - 360.0 (360 == 0)
dblHueRange
the range to allow (in degrees) on either side. 0.0 - 360.0
nSmooth
an integer from 0 to 25 specifying how much to smooth the transition. 0 gives the sharpest edge
nIntensity
an intensity below which to ignore hue, and fail the match (0 - 255)
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to blend two images.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_CHROMA_KEY FxChromaKey;
FxChromaKey.cbSize = sizeof (FxChromaKey);
FxChromaKey.hWnd = hWnd;
FxChromaKey.hIGear = hIGear;
FxChromaKey.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_chroma_key_dlg (hWnd, &FxChromaKey))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_diffuse_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_diffuse_dlg (
    HWND			hWnd,
    LPAT_IGGUI_FX_DIFFUSE			 lpFxDiffuseData
    );

Arguments:

hWnd
a handle of the parent window
lpFxDiffuseData
a pointer to the following structure:
AT_IGGUI_FX_DIFFUSE

Structure declaration:

typedef struct tag AT_IGGUI_FX_DIFFUSE
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		       rc;
    UINT			nStrength;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_DIFFUSE;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
nStrength
an integer from 1 to 16 specifying the amount of diffusion
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to diffuse an image by shuffling the positions of pixels.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_DIFFUSE FxDiffuse;
FxDiffuse.cbSize = sizeof (FxDiffuse);
FxDiffuse.hWnd = hWnd;
FxDiffuse.hIGear = hIGear;
FxDiffuse.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_diffuse_dlg (hWnd, &FxDiffuse))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_emboss_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_emboss_dlg (
    HWND			hWnd,
    LPAT_IGGUI_FX_EMBOSS			 lpFxEmbossData
    );

Arguments:

hWnd
a handle of the parent window
lpFxEmbossData
a pointer to the following structure:
AT_IGGUI_FX_EMBOSS

Structure declaration:

typedef struct tag AT_IGGUI_FX_EMBOSS
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		        rc;
    DOUBLE			dblStrength;
    AT_MODE			nCompassDir;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_EMBOSS;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
dblStrength
the embossing strength. The valid range is from 1.0 to 5.0
nCompassDir
a constant such as IG_COMPASS_N or IG_COMPASS_SE
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to produce a special effect that results in an embossed or 3-D like chiseled-in-stone look to the image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_EMBOSS FxEmboss;
FxEmboss.cbSize = sizeof (FxEmboss);
FxEmboss.hWnd = hWnd;
FxEmboss.hIGear = hIGear;
FxEmboss.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_emboss_dlg (hWnd, &FxEmboss))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_motion_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_motion_dlg (
    HWND hWnd,
    LPAT_IGGUI_FX_MOTION lpFxMotionData
    );

Arguments:

hWnd
a handle of the parent window
lpFxMotionData
a pointer to the following structure:
AT_IGGUI_FX_MOTION

Structure declaration:

typedef struct tag AT_IGGUI_FX_MOTION
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		        rc;
    UINT			nExtent;
    AT_MODE			nCompassDir;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_MOTION;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
nExtent
set to a UINT for the amount of motion you would like applied. If nCompassDir is set to "S, W, E, N", the correct range for this variable is 2 - 15. If nCompassDir is set to "SE, NE, NW, SW", the correct range for this variable is 3 - 22. This variable determines the extent to which the pixels will be "moved" or "smeared." It is the number of pixel lengths to be "moved over"
nCompassDir
an AT_MODE constant such as IG_COMPASS_N or IG_COMPASS_SE
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to cause an image to look as if it was moving when the image was captured.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_MOTION FxMotion;
FxMotion.cbSize = sizeof (FxMotion);
FxMotion.hWnd = hWnd;
FxMotion.hIGear = hIGear;
FxMotion.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_motion_dlg (hWnd, &FxMotion))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_pixelate_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_pixelate_dlg (
    HWND			hWnd,
    LPAT_IGGUI_FX_PIXELATE			 lpFxPixelateData
    );

Arguments:

hWnd
a handle of the parent window
lpFxPixelateData
a pointer to the following structure:
AT_IGGUI_FX_PIXELATE

Structure declaration:

typedef struct tag AT_IGGUI_FX_PIXELATE
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		      rc;
    AT_DIMENSION			nXRes;
    AT_DIMENSION			nYRes;
    AT_MODE			nInputMode;
    AT_MODE			nResult;
    WORD			nRadius;
    AT_RGB			rgbBkColor;
    AT_ERRCOUNT 		nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_PIXELATE;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
nXRes
a distance between the new pixels in the horizontal direction
nYRes
a distance between the new pixels in the vertical direction
nInputMode
An IG_RESAMPLE_IN_ constant. These are listed in accucnst.h
nResult
IG_RESAMPLE_OUT_SQUARE or _CIRCLE, the type of result to produce
nRadius
a radius of new "pixels", in pixels. Only applicable if nResult = IG_RESAMPLE_OUT_CIRCLE
rgbBkColor
a far pointer to an AT_RGB struct specifying the background color surrounding the output circle
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to redraw an image using what appears to be very large pixels.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_PIXELATE FxPixelate;
FxPixelate.cbSize = sizeof (FxPixelate);
FxPixelate.hWnd = hWnd;
FxPixelate.hIGear = hIGear;
FxPixelate.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_pixelate_dlg (hWnd, &FxPixelate))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_posterize_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_posterize_dlg (
    HWND				hWnd,
    LPAT_IGGUI_FX_POSTERIZE				lpFxPosterizeData
    );

Arguments:

hWnd
a handle of the parent window
lpFxPosterizeData
a pointer to the following structure:
AT_IGGUI_FX_POSTERIZE

Structure declaration:

typedef struct tag AT_IGGUI_FX_POSTERIZE
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		        rc;
    WORD			nLevels;
    AT_MODE			nColorChannel;
    AT_ERRCOUNT	 nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_POSTERIZE;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
nLevels
the number of unique colors, or levels, in the resulting image. The valid range is from 1 to 255
nColorChannel
IG_COLOR_COMP_RGB, or use IG_COLOR_COMP_R, _B, or _G to affect only one color channel
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to reduce the number of actual colors in the image by creating a "stair case" in the palette.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_POSTERIZE FxPosterize;
FxPosterize.cbSize = sizeof (FxPosterize);
FxPosterize.hWnd = hWnd;
FxPosterize.hIGear = hIGear;
FxPosterize.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_posterize_dlg (hWnd, &FxPosterize))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_spotlight_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_spotlight_dlg (
    HWND				hWnd,
    LPAT_IGGUI_FX_SPOTLIGHT				lpFxSpotlightData
    );

Arguments:

hWnd
a handle of the parent window
lpFxSpotlightData
a pointer to the following structure:
AT_IGGUI_FX_SPOTLIGHT

Structure declaration:

typedef struct tag AT_IGGUI_FX_SPOTLIGHT
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		        rc;
    AT_PIXPOS			nCenterX;
    AT_PIXPOS			nCenterY;
    AT_DIMENSION			nRadius;
    UINT			nDarkenBy;
    AT_PIXEL		       nSmoothing;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_SPOTLIGHT;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
nCenterX
the X coordinate of the circle's center to receive the spotlight effect; 0 to Width - 1
nCenterY
the Y coordinate of the circle's center; 0 to Height - 1
nRadius
Radius of the circle, in pixels; 2 to Height - 2
nDarkenBy
How much to darken the remainder of the image
nSmoothing
0 to 255, specifying how much smoothing to apply at the edges; 0 = sharp edges, > 0 = smoother edges
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to produce a "spotlight" effect within the circle.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_SPOTLIGHT FxSpotlight;
FxSpotlight.cbSize = sizeof (FxSpotlight);
FxSpotlight.hWnd = hWnd;
FxSpotlight.hIGear = hIGear;
FxSpotlight.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_spotlight_dlg (hWnd, &FxSpotlight))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_stitch_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_stitch_dlg (
    HWND			hWnd,
    LPAT_IGGUI_FX_STITCH			 lpFxStitchData
    );

Arguments:

hWnd
a handle of the parent window
lpFxStitchData
a pointer to the following structure:
AT_IGGUI_FX_STITCH

Structure declaration:

typedef struct tag AT_IGGUI_FX_STITCH
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		      rc;
    DOUBLE			dblStrength;
    AT_MODE			nCompassDir;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_STITCH;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
dblStrength
0.0 to 5.0 (A very low value will produce a gray screen with no detail.)
nCompassDir
a constant such as IG_COMPASS_N or IG_COMPASS_SE
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to produce an effect similar to "emboss", except that the output more closely resembles a quilted stitch pattern.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_STITCH FxStitch;
FxStitch.cbSize = sizeof (FxStitch);
FxStitch.hWnd = hWnd;
FxStitch.hIGear = hIGear;
FxStitch.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_stitch_dlg (hWnd, &FxStitch))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_texture_tile_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_texture_tile_dlg (
    HWND				hWnd,
    LPAT_IGGUI_FX_TEXTURE_TILE				lpFxTextureTileData
    );

Arguments:

hWnd
a handle of the parent window
lpFxTextureTileData
a pointer to the following structure:
AT_IGGUI_FX_TEXTURE_TILE

Structure declaration:

typedef struct tag AT_IGGUI_FX_TEXTURE_TILE
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		      rc;
    CHAR			szFileName[_MAX_PATH];
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_TEXTURE_TILE;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
szFileName
a file name of the 8 bit image to be applied to image HIGEAR to produce a textured effect
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to apply a texture to an image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_TEXTURE_TILE FxTextureTile;
FxTextureTile.cbSize = sizeof (FxTextureTile);
FxTextureTile.hWnd = hWnd;
FxTextureTile.hIGear = hIGear;
FxTextureTile.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_texture_tile_dlg (hWnd, &FxTextureTile))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_twist_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_twist_dlg (
    HWND			hWnd,
    LPAT_IGGUI_FX_TWIST			 lpFxTwistData
    );

Arguments:

hWnd
a handle of the parent window
lpFxTwistData
a pointer to the following structure:
AT_IGGUI_FX_TWIST

Structure declaration:

typedef struct tag AT_IGGUI_FX_TWIST
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		        rc;
    AT_MODE			nType;
    UINT			nSquareSize;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_TWIST;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
nType
One of IG_TWIST_90, IG_TWIST_180, IG_TWIST_270, or IG_TWIST_RANDOM constants
nSquareSize
the size, in pixels, of the regions to apply twisting (the valid range is between 2 and 50)
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to apply a special effect that makes the image look as if it is being viewed through a shower curtain.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_TWIST FxTwist;
FxTwist.cbSize = sizeof (FxTwist);
FxTwist.hWnd = hWnd;
FxTwist.hIGear = hIGear;
FxTwist.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_twist_dlg (hWnd, &FxTwist))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_fx_watermark_dlg

Declaration:

BOOL ACCUAPI IG_gui_fx_watermark_dlg (
    HWND				hWnd,
    LPAT_IGGUI_FX_WATERMARK				lpFxWatermarkData
    );

Arguments:

hWnd
a handle of the parent window
lpFxWatermarkData
a pointer to the following structure:
AT_IGGUI_FX_WATERMARK

Structure declaration:

typedef struct tag AT_IGGUI_FX_WATERMARK
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		          rc;
    CHAR			szFileName[_MAX_PATH];
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_FX_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_FX_WATERMARK;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to be processed
szFileName
a file name of an 8-bit sign centered image to use for watermarking
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to produce a watermark effect.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_FX_WATERMARK FxWatermark;
FxWatermark.cbSize = sizeof (FxWatermark);
FxWatermark.hWnd = hWnd;
FxWatermark.hIGear = hIGear;
FxWatermark.uFlags |= IG_IGGUI_FX_SETUP_EMPTY_RECT;
if (IG_gui_fx_watermark_dlg (hWnd, &FxWatermark))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_get_enableicc

Declaration:

AT_BOOL ACCUAPI IG_gui_get_enableicc();

Arguments:

None

Description:

This method checks to determine whether ICC support is currently enabled.

Bits Per Pixel:

N/A

Return Value:

True/False

Example:

AT_BOOL bICCEnabled = FALSE;
/* Check whether ICC support is enabled */
bICCEnabled = IG_gui_get_enableicc();
...

Sample:

IMG_PROC


IG_gui_get_showiccwarning

Declaration:

AT_BOOL ACCUAPI IG_gui_get_showiccwarning();

Arguments:

None

Description:

This function gets the state of the registry entry that determines whether we should show the warning dialog related to embedded color profile or non-RGB color format.

Bits Per Pixel:

N/A

Return Value:

True/False

Example:

AT_BOOL bShowICCWarning = FALSE;
/* Get the state of the registry entry */
bShowICCWarning = IG_gui_get_showiccwarning();
...

Sample:

IMG_PROC


IG_gui_global_parameters_dlg

Declaration:

BOOL  ACCUAPI  IG_gui_global_parameters_dlg(
    HWND        hWnd
    );

Arguments:

hWnd
a handle of the parent window

Purpose:

This function displays dialog with all currently defined global control parameters. It provides type and value for each parameter. It also allows to change current value of the parameter and add new parameters.

Return Value:

Returns TRUE if user pressed OK button, FALSE - otherwise.

Sample: All

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_image_info_dlg

Declaration:

VOID  ACCUAPI IG_gui_image_info_dlg(
    HWND		hWnd,
    HIGEAR		hIGear
    );

Arguments:

hWnd
A parent window for the image information dialog,
hIGear
An image for which to get information.

Purpose:

This function shows the image information dialog box. The following image parameters are shown: Image Width, Image Height, Bits per pixel, DIB format, DIB size, Resolution units, Horizontal Resolution, Vertical Resolution. Image preview is also available.

Return Value:

None.

Example:

#include "IG_gui_common.h"
IG_gui_image_info_dlg( hWnd, hIGear );

Sample: COLOR, DISPLAY, GUIWIN, IMG_PROC, IOSET, JPEG,

MAGNIFY, MDI, MEMIO, PALEDT, PIX_ACC, POSTER,

PRINT, ART, Vector, FILTER, FlashPix, IC, Scan, TWAIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_img_channels_dlg

Declaration:

BOOL ACCUAPI IG_gui_img_channels_dlg(
    HWND	hWnd,
    HIGEAR	hImage
    );

Arguments:

hWnd
A handle of the parent window.
hImage
HIGEAR handle of an image.

Purpose:

This GUI function demonstrates how to use alpha channel API. It allows to import, create, delete and manage alpha channels.

See also the section ImageGear Alpha Channel Support.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Sample: FILTER, GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_color_promote_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_color_promote_dlg (
    HWND				hWnd,
    LPAT_IGGUI_IP_COLOR_PROMOTE				lpIpColorPromoteData
    );

Arguments:

hWnd
A handle of the parent window.
lpIpColorPromoteData
A pointer to the following structure:
AT_IGGUI_IP_COLOR_PROMOTE

Structure declaration:

typedef struct tag AT_IGGUI_IP_COLOR_PROMOTE
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_MODE			nPromoteTo;
    AT_ERRCOUNT	 		nErrCount;
    LPFNIGGUI_IP_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_IP_COLOR_PROMOTE;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
nPromoteTo
one of the IG_PROMOTE_TO_4, IG_PROMOTE_TO_8, IG_PROMOTE_TO_24, IG_PROMOTE_TO_32 constants
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to increase the number of bits per pixel for the original image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_COLOR_PROMOTE IpColorPromote;
IpColorPromote.cbSize = sizeof (IpColorPromote);
IpColorPromote.hWnd = hWnd;
IpColorPromote.hIGear = hIGear;
if (IG_gui_ip_color_promote_dlg (hWnd, &IpColorPromote))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: COLOR, IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_color_reduce_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_color_reduce_dlg (
    HWND				hWnd,
    LPAT_IGGUI_IP_COLOR_REDUCE				lpIpColorReduceData
    );

Arguments:

hWnd
a handle of the parent window
lpIpColorReduceData
a pointer to the following structure:
AT_IGGUI_IP_COLOR_REDUCE

Structure declaration:

typedef struct tag AT_IGGUI_IP_COLOR_REDUCE
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    UINT			nBits;
    UINT			nReduceType;
    INT			nLevel;
    UINT			nMaxColors;
    BOOL			bFastRemap;
    UINT			nThreshold;
    AT_MODE			nOption;
    UINT			nWeightR;
    UINT			nWeightG;
    UINT			nWeightB;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_IP_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_IP_COLOR_REDUCE;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
nBits
a number of bits per pixel after reduction
nReduceType
a type of color reduction (see IG_IGGUI_IP_COLOR_REDUCE_ constants in accucnst.h file)
nLevel
a threshold value for dithering, 0 to 255
nMaxColors
a maximum number of colors (that is, maximum number of unique pixel values) you want in the resulting image. Must be between 16 and 256
bFastRemap
TRUE if you want the reduction algorithm optimized for speed. FALSE if you want the algorithm optimized for quality
nThreshold
an integer value that specifies which pixel values will be changed to black, and which pixel values will be changed to white. Pixels with values greater than nThreshold will be changed to white, and pixels that have values less than nThreshold will be changed to black
nOption
a constant of type AT_MODE, such as IG_REDUCE_BITONAL_AVE, that specifies what type of reduction to perform. See accucnst.h for the complete list
nWeightR
these values are only used if nOption is set to IG_REDUCE_BITONAL_WEIGHTED. The range of values is between 0 and 255
nWeightG
the range of values is between 0 and 255
nWieghtB
the range of values is between 0 and 255
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to reduce the number of bits per pixel for the original image using different methods.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_COLOR_REDUCE IpColorReduce;
IpColorReduce.cbSize = sizeof (IpColorReduce);
IpColorReduce.hWnd = hWnd;
IpColorReduce.hIGear = hIGear;
IpColorReduce.nReduceType = IG_IGGUI_IP_COLOR_REDUCE_BAYER;
if (IG_gui_ip_color_reduce_dlg (hWnd, &IpColorReduce))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: COLOR

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_contrast_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_contrast_dlg (
    HWND				hWnd,
    LPAT_IGGUI_IP_CONTRAST				lpIpContrastData
    );

Arguments:

hWnd
a handle of the parent window
lpIpContrastData
a pointer to the following structure:
AT_IGGUI_IP_CONTRAST

Structure declaration:

typedef struct tag AT_IGGUI_IP_CONTRAST
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		        rc;
    UINT			nContrastType;
    AT_MODE			nMode;
    DOUBLE			dblContrast;
    DOUBLE			dblBrightness;
    DOUBLE			dblGamma;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_IP_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_IP_CONTRAST;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to operate on
nContrastType
a type of a contrast operation (see IG_IGGUI_IP_CONTRAST_ constants)
nMode
IG_CONTRAST_PIXEL or IG_CONTRAST_PALETTE, telling whether to adjust by altering the pixels themselves, or the palette
dblContrast
a value from -255.0 to +255.0, the adjustment in contrast
dblBrightness
a value from - 255.0 to +255.0, the adjustment in brightness
dblGamma
a value greater than 0.0. The normal range is from 0.75 to 3.0
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to adjust the contrast of the image using different methods.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_CONTRAST IpContrast;
IpContrast.cbSize = sizeof (IpContrast);
IpContrast.hWnd = hWnd;
IpContrast.hIGear = hIGear;
IpContrast.uFlags |= IG_IGGUI_IP_SETUP_EMPTY_RECT;
if (IG_gui_ip_contrast_dlg (hWnd, &IpContrast))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_crop_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_crop_dlg (
    HWND			hWnd,
    LPAT_IGGUI_IP_CROP			 lpIpCropData
    );

Arguments:

hWnd
a handle of the parent window
lpIpCropData
a pointer to the following structure:
AT_IGGUI_IP_CROP

Structure declaration:

typedef struct tag AT_IGGUI_IP_CROP
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		      rc;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_IP_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_IP_CROP;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image to keep. The remainder of the image is removed and discarded
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to change the dimensions of the image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_CROP IpCrop;
IpCrop.cbSize = sizeof (IpCrop);
IpCrop.hWnd = hWnd;
IpCrop.hIGear = hIGear;
IpCrop.uFlags |= IG_IGGUI_IP_SETUP_EMPTY_RECT;
if (IG_gui_ip_crop_dlg (hWnd, &IpCrop))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_crypt_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_crypt_dlg (
    HWND			hWnd,
    LPAT_IGGUI_IP_CRYPT			 lpIpCryptData
    );

Arguments:

hWnd
a handle of the parent window
lpIpCryptData
a pointer to the following structure:
AT_IGGUI_IP_CRYPT

Structure declaration:

typedef struct tag AT_IGGUI_IP_CRYPT
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    BOOL			bDecrypt;
    AT_RECT		      rc;
    AT_MODE			nAlgorithm;
    LPSTR			lpszPassword;
    DWORD			dwPasswordSize;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_IP_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_IP_CRYPT;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
bDecrypt
TRUE to decrypt a portion of the image
rc
an AT_RECT struct specifying the rectangular portion of the image to encode or decode
nAlgorithm
an IG_ENCRYPT_METHOD_ constant specifying how the image was encoded
lpszPassword
a pointer to a zero-terminated password string
dwPasswordSize
a length of the password
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to encrypt/decrypt an image area.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_CRYPT IpCrypt;
IpCrypt.lpszTitle = "Encrypt";
IpCrypt.cbSize = sizeof (IpCrypt);
IpCrypt.hWnd = hWnd;
IpCrypt.hIGear = hIGear;
IpCrypt.lpszPassword = szPassword;
IpCrypt.dwPasswordSize = sizeof (szPassword);
IpCrypt.uFlags |= IG_IGGUI_IP_SETUP_EMPTY_RECT;
if (IG_gui_ip_crypt_dlg (hWnd, &IpCrypt))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_despeckle_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_despeckle_dlg (
    HWND				hWnd,
    LPAT_IGGUI_IP_DESPECKLE				lpIpDespeckleData
    );

Arguments:

hWnd
a handle of the parent window
lpIpDespeckleData
a pointer to the following structure:
AT_IGGUI_IP_DESPECKLE

Structure declaration:

typedef struct tag AT_IGGUI_IP_DESPECKLE
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		        rc;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_IP_UPDATE			lpfnUpdateProc;
}AT_IGGUI_IP_DESPECKLE;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image on which to operate
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to reduce the amount of noise in the 1 bit image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_DESPECKLE IpDespeckle;
IpDespeckle.cbSize = sizeof (IpDespeckle);
IpDespeckle.hWnd = hWnd;
IpDespeckle.hIGear = hIGear;
IpDespeckle.uFlags |= IG_IGGUI_IP_SETUP_EMPTY_RECT;
if (IG_gui_ip_despeckle_dlg (hWnd, &IpDespeckle))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_edge_map_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_edge_map_dlg (
    HWND				hWnd,
    LPAT_IGGUI_IP_EDGE_MAP				lpIpEdgeMapData
    );

Arguments:

hWnd
a handle of the parent window
lpIpEdgeMapData
a pointer to the following structure:
AT_IGGUI_IP_EDGE_MAP

Structure declaration:

typedef struct tag AT_IGGUI_IP_EDGE_MAP
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		      rc;
    AT_MODE			nType;
    AT_ERRCOUNT 			nErrCount;
    LPFNIGGUI_IP_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_IP_EDGE_MAP;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image on which to operate
nType
the type of edge map operation to perform, such as IG_EDGE_OP_LAPLACIAN, IG_EDGE_OP_ROBERTS, etc. The list of available types is in file accucnst.h
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to show where there are changes in contrast in the original image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_EDGE_MAP IpEdgeMap;
IpEdgeMap.cbSize = sizeof (IpEdgeMap);
IpEdgeMap.hWnd = hWnd;
IpEdgeMap.hIGear = hIGear;
IpEdgeMap.uFlags |= IG_IGGUI_IP_SETUP_EMPTY_RECT;
if (IG_gui_ip_edge_map_dlg (hWnd, &IpEdgeMap))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_gaussian_blur_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_gaussian_blur_dlg (
    HWND				hWnd,
    LPAT_IGGUI_IP_GAUSSIAN_BLUR				 lpIpGaussianBlurData
    )

Arguments:

hWnd
a handle of the parent window
lpIpGaussianBlurData
a pointer to the following structure:
AT_IGGUI_IP_GAUSSIAN_BLUR

Structure declaration:

typedef struct tag AT_IGGUI_IP_GAUSSIAN_BLUR
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT			rc;
    double			dblRadius;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_IP_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_IP_SMOOTH;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the portion of the image to be affected
dblRadius
Defines the neighborhood to be considered for each pixel. The value (AT_INT)(Sigma * 3 + 0.5) * 2 + 1 cannot be greater than the smaller of the two image dimensions.
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to choose parameters for, and apply the Gaussian Blur transform. It makes images look softer and slightly out of focus. A specific feature of Gaussian Blur is that it removes the high-frequency component from the image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_GAUSSIAN_BLUR IpGaussianBlur;
IpGaussianBlur.cbSize = sizeof (IpGaussianBlur);
IpGaussianBlur.hWnd = hWnd;
IpGaussianBlur.hIGear = hIGear;
IpGaussianBlur.uFlags |= IG_IGGUI_IP_SETUP_EMPTY_RECT;
IpGaussianBlur.dblRadius = 1.0;
if (IG_gui_ip_gaussian_blur_dlg (hWnd, &IpGaussianBlur))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_median_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_median_dlg (
    HWND			hWnd,
    LPAT_IGGUI_IP_MEDIAN			lpIpMedianData
    );

Arguments:

hWnd
a handle of the parent window
lpIpMedianData
a pointer to the following structure:
AT_IGGUI_IP_MEDIAN

Structure declaration:

typedef struct tag AT_IGGUI_IP_MEDIAN
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		        rc;
    AT_DIMENSION			 nNeighborWidth;
    AT_DIMENSION	 		nNeighborHeight;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_IP_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_IP_MEDIAN;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the rectangular portion of the image on which to operate
nNeighborWidth
a width of the neighborhood to include in computing each new pixel's value
nNeighborHeight
a height of the neighborhood to include
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to perform a median filter on 8-bit gray level and 24 bit images.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_MEDIAN IpMedian;
IpMedian.cbSize = sizeof (IpMedian);
IpMedian.hWnd = hWnd;
IpMedian.hIGear = hIGear;
IpMedian.uFlags |= IG_IGGUI_IP_SETUP_EMPTY_RECT;
if (IG_gui_ip_median_dlg (hWnd, &IpMedian))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_resize_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_resize_dlg (
    HWND			hWnd,
    LPAT_IGGUI_IP_RESIZE			lpIpResizeData
    );

Arguments:

hWnd
a handle of the parent window
lpIpResizeData
a pointer to the following structure:
AT_IGGUI_IP_RESIZE

Structure declaration:

typedef struct tag AT_IGGUI_IP_RESIZE
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_DIMENSION			 nNewWidth;
    AT_DIMENSION			 nNewHeight;
    AT_MODE			nInterpMethod;
    LPAT_PIXEL			 lpBkgndColor;
    BOOL			bFixed;
    BOOL			bPercentage;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_IP_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_IP_RESIZE;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
nErrCount
the number of ImageGear errors that occurred during this function call
nNewWidth
a width that the image is to be after resize
nNewHeight
a height that the image is to be after resize
nInterpMethod
IG_INTERPOLATION_NONE, or the interpolation method to use to compute the new pixel values for the resized image. The IG_INTERPOLATION_ constants are listed in file accucnst.h
lpBkgndColor
a far pointer to the RGB or pixel value that specifies the background color to be used in the displaced areas after the image has been resized using the resize with padding method
bFixed
use proportional resize
bPercentage
use percentage instead of pixels
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to change the dimensions of the image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_RESIZE IpResize;
IpResize.cbSize = sizeof (IpResize);
IpResize.hWnd = hWnd;
IpResize.hIGear = hIGear;
IpResize.uFlags |= IG_IGGUI_IP_SETUP_EMPTY_RECT;
if (IG_gui_ip_resize_dlg (hWnd, &IpResize))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_rotate_any_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_rotate_any_dlg (
    HWND				hWnd,
    LPAT_IGGUI_IP_ROTATE_ANY				 lpIpRotateAnyData
    );

Arguments:

hWnd
a handle of the parent window
lpIpRotateAnyData
a pointer to the following structure:
AT_IGGUI_IP_ROTATE_ANY

Structure declaration:

typedef struct tag AT_IGGUI_IP_ROTATE_ANY
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    INT			nAngle;
    AT_MODE			nMode;
    LPAT_PIXEL 			lpBkgndColor;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_IP_UPDATE			lpfnUpdateProc;
}AT_IGGUI_IP_ROTATE_ANY;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
nAngle
an angle to rotate in degrees; a positive value
nMode
an integer variable of type AT_MODE defined in accucnst.h. The value can be either IG_ROTATE_CLIP or IG_ROTATE_EXPAND, indicating whether to clip the rotated image to keep the image bitmap the same size, or expand the size of the bitmap to retain the entire rotated image.
lpBkgndColor
a far pointer to the RGB or pixel value that specifies the background color to be used in the displaced areas after the image has been rotated
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to rotate the image around its center.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_ROTATE_ANY IpRotateAny;
IpRotateAny.cbSize = sizeof (IpRotateAny);
IpRotateAny.hWnd = hWnd;
IpRotateAny.hIGear = hIGear;
if (IG_gui_ip_rotate_any_dlg (hWnd, &IpRotateAny))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_sharpen_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_sharpen_dlg (
    HWND				hWnd,
    LPAT_IGGUI_IP_SHARPEN				 lpIpSharpenData
    );

Arguments:

hWnd
a handle of the parent window
lpIpSharpenData
a pointer to the following structure:
AT_IGGUI_IP_SHARPEN

Structure declaration:

typedef struct tag AT_IGGUI_IP_SHARPEN
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT		        rc;
    INT			nFactor;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_IP_UPDATE			 lpfnUpdateProc;
}AT_IGGUI_IP_SHARPEN;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the portion of image to be affected
nFactor
the factor indicating the degree of sharpness be decreased or the degree of smoothness to be increased. The valid range is from 1 to 4
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to cause the dark side of a contrast edge to become darker and the light side lighter.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_SHARPEN IpSharpen;
IpSharpen.cbSize = sizeof (IpSharpen);
IpSharpen.hWnd = hWnd;
IpSharpen.hIGear = hIGear;
IpSharpen.uFlags |= IG_IGGUI_IP_SETUP_EMPTY_RECT;
if (IG_gui_ip_sharpen_dlg (hWnd, &IpSharpen))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_smooth_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_smooth_dlg (
    HWND hWnd,
    LPAT_IGGUI_IP_SMOOTH lpIpSmoothData
    );

Arguments:

hWnd
a handle of the parent window
lpIpSmoothData
a pointer to the following structure:
AT_IGGUI_IP_SMOOTH

Structure declaration:

typedef struct tag AT_IGGUI_IP_SMOOTH
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT			rc;
    INT			nFactor;
    AT_ERRCOUNT			 nErrCount;
    LPFNIGGUI_IP_UPDATE	 		lpfnUpdateProc;
}AT_IGGUI_IP_SMOOTH;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the portion of the image to be affected
nFactor
the factor indicating the degree of sharpness be decreased or the degree of smoothness to be increased. The valid range is from 1 to 4
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to make images look softer and slightly out of focus.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_SMOOTH IpSmooth;
IpSmooth.cbSize = sizeof (IpSmooth);
IpSmooth.hWnd = hWnd;
IpSmooth.hIGear = hIGear;
IpSmooth.uFlags |= IG_IGGUI_IP_SETUP_EMPTY_RECT;
if (IG_gui_ip_smooth_dlg (hWnd, &IpSmooth))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMG_PROC, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_ip_unsharp_mask_dlg

Declaration:

BOOL ACCUAPI IG_gui_ip_unsharp_mask_dlg (
    HWND				hWnd,
    LPAT_IGGUI_IP_UNSHARP_MASK				 lpIpUnsharpMaskData
)

Arguments:

hWnd
a handle of the parent window
lpIpUnsharpMaskData
a pointer to the following structure:
AT_IGGUI_IP_UNSHARP_MASK

Structure declaration:

typedef struct tag AT_IGGUI_IP_UNSHARP_MASK
{
    DWORD			cbSize;
    UINT			uFlags;
    HIGEAR			hIGear;
    HWND			hWnd;
    LPCHAR			lpszTitle;
    AT_RECT			rc;
    double			dblRadius;
    UINT			nAmount;
    UINT			nThreshold;
    AT_MODE			nColorChannel;
    AT_ERRCOUNT 			nErrCount;
    LPFNIGGUI_IP_UPDATE	 lpfnUpdateProc;
}AT_IGGUI_IP_SMOOTH;

Structure members:

cbSize
specifies the length, in bytes, of the structure
uFlags
a set of bit flags you can use to initialize the dialog box
hIGear
a handle of an image
hWnd
a handle of the window to update
lpszTitle
a dialog title
rc
an AT_RECT struct specifying the portion of the image to be affected
dblRadius
Defines the neighborhood to be considered for each pixel. The valid range is from 0.1 to 500
nAmount
Amount of sharpening, in percents. The valid range is from 1 to 500.
nThreshold
Minimal difference between a pixel and its neighbors at which the pixel will be modified.The valid range for 8-bit gray level and 24-bit images is from 0 to 255; for 9-16-bit gray level images - from 0 to 65535.
nErrCount
the number of ImageGear errors that occurred during this function call
lpfnUpdateProc
a pointer to the function that is called when the `Apply' button is pressed

Purpose:

This function shows the dialog that allows you to choose parameters for, and apply the Unsharp Mask transform. It is used for image sharpening and edge enhancement. The algorithm works by subtracting a smoothed version of the image ("unsharp") from the original image.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_IP_UNSHARP_MASK IpUnsharpMask;
IpUnsharpMask.cbSize = sizeof (IpUnsharpMask);
IpUnsharpMask.hWnd = hWnd;
IpUnsharpMask.hIGear = hIGear;
IpUnsharpMask.uFlags |= IG_IGGUI_IP_SETUP_EMPTY_RECT;
IpUnsharpMask.dblRadius = 1.0;
IpUnsharpMask.nAmount = 150;
IpUnsharpMask.nThreshold = 10;
IpUnsharpMask.nColorChannel = IG_COLOR_COMP_ALL;
if (IG_gui_ip_unsharp_mask_dlg (hWnd, &IpUnsharpMask))
{
InvalidateRect(hWnd, NULL, FALSE);
    UpdateWindow(hWnd);
}

Sample: IMGPROC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_layers_dlg

Group: GUI Layers

Declaration:

BOOL  ACCUAPI					IG_gui_layers_dlg(
    HWND				hWnd,
    HIGEAR			hIGear
    );

Description:

This function shows the image layers dialog box. User can choose the layers to flatten and display as well as edit the layers properties.

Arguments:

hWnd
A parent window for the image layers dialog.
hIGear
Handle to the image with layers.

Return Value:

Error count.


IG_gui_layer_properties_dlg

Group: GUI Layers

Declaration:

BOOL  ACCUAPI				IG_gui_layer_properties_dlg(
    HWND			hWnd,
    HIGLAYER		hLayer
    );

Description:

This function shows the specified layer's properties dialog box. User can view and edit the layers properties using this dialog.

Arguments:

hWnd
A parent window for the layer properties dialog.
hLayer
Handle to the layer object whose prorerties are accessed.

Return Value:

Error count.


IG_gui_load_filename_dlg

Declaration:

BOOL ACCUAPI IG_gui_load_filename_dlg (
    HWND		hWnd,
    LPCHAR		lpTitle,
    LPCHAR		lpFileName,
    UINT		nFNameSize,
    LPAT_MODE		 lpnFormatID
    );

Arguments:

hWnd
a handle of the parent window
lpTitle
a dialog title
lpFileName
a pointer to the file name buffer
nFNameSize
the file name buffer size
lpnFormatID
a format ID

Purpose:

Shows the file open dialog and returns the file name to load. It also shows the format identifier if the format is detected.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
IG_gui_load_filename_dlg(hWnd, NULL, szFile, sizeof(szFile),
NULL);

Sample: ASCII, DISPLAY, GUIWIN, IMG_PROC, IOSET, JPEG, LoadCB,

PAGE, PRINT, MULTPAGE, FlashPix, MULTIMED, JNIDLL

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_load_options_dlg

Declaration:

BOOL  ACCUAPI  IG_gui_load_options_dlg( HWND hWnd );

Arguments:

hWnd
a handle of the parent window

Purpose:

This function shows the load options dialog that can be used to specify loading parameters for the image file. This dialog can be used to specify:

  • Load size dimensions - the dimensions that the DIB image bitmap created by a load, are to have, regardless of the dimensions in the file from which the image is loaded. The effect is similar to loading and then re-sizing the image.
  • Color reduction - reducing the number of Bits Per Pixel whenever loading an image whose bit depth is greater than that specified by nColorReduceMode. The bit depth is reduced to 8, 4, or 1 as specified.
  • Load rectangle - this will cause an image loaded to be cropped. Portions of the image falling outside the coordinates of this rectangle will be discarded, and will not appear in the image bitmap of the DIB created by the load.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

case  ID_SETTINGS_LOADOPTIONS:
    IG_gui_load_options_dlg( hWnd );
break;

Sample: FILTER

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_load_page_dlg

Declaration:

BOOL ACCUAPI IG_gui_load_page_dlg (
    HWND		hWnd,
    LPCHAR		lpTitle,
    LPCHAR		lpFileName,
    UINT		nFNameSize,
    LPAT_MODE		 lpnFormatID,
    LPUINT		lpnPage
    );

Arguments:

hWnd
a handle of the parent window
lpTitle
a dialog title
lpFileName
a pointer to the file name buffer
nFNameSize
the file name buffer size
lpnFormatID
a format ID
lpnPage
an image page number

Purpose:

Shows the file open dialog and returns the file name and page number to load. It returns the format identifier if the format is detected.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
IG_gui_load_page_dlg(hWnd, NULL, szFile, sizeof(szFile), NULL,
&nPage);

Sample: CLPBRD, COLOR, IMG_PROC, JPEG, MAGNIFY,

MDI, MEMIO, PALEDT, PAN, PIX_ACC, POSTER, PRINT, WIPES,

ART, Vector, FILTER, IC, Scan, TWAIN

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_load_url_dlg

Declaration:

BOOL  ACCUAPI  IG_gui_load_url_dlg(
    HWND			hWnd,
    LPAT_IGGUI_URL_INFO			lpURLInfo
    );

Arguments:

hWnd
a handle of the parent window
lpURLInfo
a pointer to the following structure:
AT_IGGUI_URL_INFO

Structure declaration:

typedef  struct  tagAT_IGGUI_URL_INFO
{
    CHAR	 HostName[_MAX_PATH];
    CHAR	 URLPath[_MAX_PATH];
    CHAR 	UserName[80];
    CHAR	 Password[80];
    LONG	 nServerPort;
    DWORD	 dwService;
    DWORD	 dwAccessType;
    CHAR 	ProxyName[ _MAX_PATH];
    CHAR	 ProxyBypass[ _MAX_PATH];
    DWORD	 dwFlags;
}AT_IGGUI_URL_INFO;

Structure members:

HostName
Filename of host where load from.
URLPath
URL path.
UserName
The same as InternetConnect(...lpszUserName...)
Password
The same as InternetConnect(...lpszPassword...)
nServerPort
The same as InternetConnect(...nServerPort...)
dwService
The same as InternetConnect(...dwService...)
dwAccessType
The same as InternetOpen(...dwAccessType.. )
ProxyName
The same as InternetOpen(...lpszProxyName...)
ProxyBypass
The same as InternetOpen(...lpszProxyBypass...)
dwFlags
The same as InternetOpen(...dwFlags...)

Purpose:

This function opens "Load URL..." dialog that allows to input parameters required to load image from Internet.

It takes a handle of dialog's parent window and fills AT_IGGUI_URL_INFO structure on successful return. The fileds of this structure are collection of parameters necessary to call InternetConnect and InternetOpen functions.

Return Value:

Function returns TRUE if OK button is pressed or FALSE in other case.

Sample: TEMPLATE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_mp_file_wnd

Declaration:

HWND ACCUAPI IG_gui_mp_file_wnd(
    HWND 	hWnd,
    HMIGEAR	 hMImage,
    UINT	 nPWidth,
    UINT 	nPHeight
    );

Arguments:

hWnd
a handle of the parent window
hMImage
a handle of a multi-page image
nPWidth
a page width
nPHeight
a page height

Purpose:

Creates a window with a list of multi-page image pages and corresponding pages from the associated file. It allows you to perform operations either with the image and/or the associated file.

Return Value:

Returns a handle of the created window or if the function fails, the return value is NULL.

Example:

#include "IG_gui_common.h"
IG_gui_mp_file_wnd (hWnd, hMImage, nPWidth, nPHeight);

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_mp_image_wnd

Declaration:

HWND ACCUAPI IG_gui_mp_image_wnd(
    HWND		hWnd,
    HMIGEAR		 hMImage,
    UINT		nPWidth,
    UINT		nPHeight
    );

Arguments:

hWnd
a handle of the parent window
hMImage
a handle of a multi-page image
nPWidth
a page width
nPHeight
a page height

Purpose:

Creates a window with a list of multi-page image pages and allows you to perform operations with its pages.

Return Value:

Returns a handle of the created window or if the function fails, the return value is NULL.

Example:

#include "IG_gui_common.h"
IG_gui_mp_image_wnd (hWnd, hMImage, nPWidth, nPHeight);

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_mp_page_select_dlg

Declaration:

BOOL ACCUAPI IG_gui_mp_page_select_dlg(
    HWND		hWnd,
    HMIGEAR	 	hMImage,
    UINT		nPWidth,
    UINT		nPHeight,
    LPUINT		lpnPage
    );

Arguments:

hWnd
a handle of the parent window
hMImage
a handle of a multi-page image
nPWidth
a page width
nPHeight
a page height
lpnPage
a page number that was selected

Purpose:

This function shows the dialog that allows you to select a page from a multi-page image.

Sample: MULTPAGE

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_mp_savecomp_dlg

Declaration:

BOOL  ACCUAPI	IG_gui_mp_savecomp_dlg(
    HWND		hWnd,
    HMIGEAR	 hMImage,
    LPUINT		lpnPages,
    UINT		nPageCount,
    LPAT_MODE		 lpnCompression
    );

Purpose:

This functions creates a list of applicable compressions for a given list of associated multi-page image pages and returns the selected value.

Example:

#include "IG_gui_common.h"
IG_gui_mp_savecomp_dlg(HWND hWnd, HMIGEAR hMImage,
LPUINT lpnPages, UINT  nPageCount, LPAT_MODE lpnCompression );

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_open_dir_dlg

Declaration:

BOOL  ACCUAPI  IG_gui_open_dir_dlg(
    HWND 	hWnd,
    LPCHAR	 lpDirName,
    UINT	 nBufSize
    );

Arguments:

hWnd
a handle of the parent window
lpDirName
a path to the directory
nBufSize
the size of buffer provided by lpDirName

Purpose:

This function display "Open Directory..." dialog. It accepts handle of parent window as first argument and returns directory path via second lpDirName argument. nBufSize argument specifies the size of buffer provided by second argument.

Return Value:

Function return TRUE if OK button is pressed, or FALSE in other case.

Sample: DISPLAY

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_resname_get

Declaration:

VOID  ACCUAPI  IG_gui_resname_get(
    AT_MODE	 nResolution,
    LPCHAR	 lpStr,
    DWORD	 dwSize
    );

Arguments:

nResolution
The ImageGear compression constant by type IG_RESOLUTION_. See file accucnst.h for the full list of these constants.
lpStr
String representation of compression constant specified by nResolution argument.
dwSize
The buffer size of lpStr argument.

Purpose:

This function returns textual names for resolution constants. It accepts IG_RESOLUTION_... constants by the first argument and returns its string representation via the second argument. Last parameter - size of lpStr buffer.

Return Value:

None.

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_save_filename_dlg

Declaration:

BOOL ACCUAPI IG_gui_save_filename_dlg (
    HWND		hWnd,
    LPCHAR		lpTitle,
    LPAT_MODE		 lpnFormatList,
    UINT		nFListSize,
    LPCHAR		lpFileName,
    UINT		nFNameSize,
    LPAT_MODE	 lpnFormat
    );

Arguments:

hWnd
a handle of the parent window
lpTitle
a dialog title
lpFileName
a pointer to the file name buffer
nFNameSize
the file name buffer size
lpnFormatList
a format list
nFListSize
a format list size
lpnFormat
a format ID

Purpose:

Shows the file save dialog and returns the file name and format identifier if file format of the image is detected.

Return Value:

If the user specifies the parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
IG_gui_save_filename_dlg (hWnd, NULL, NULL, 0, szFile,
sizeof(szFile), &lFormat);

Sample: LoadCB, PAGE, MULTPAGE,

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_save_filter_get

Declaration:

VOID ACCUAPI IG_gui_save_filter_get (
    LPAT_LMODE		 lpSaveList,
    UINT		nSListSize,
    LPBYTE		lpFilter,
    UINT		nFilterSize
    );

Arguments:

lpSaveList
an array of save constants
nSListSize
an array size
lpFilter
a character array
nFilterSize
an array size

Purpose:

Takes list of save constants of type {nFormatID|nCompression<<16} and generates the embossing strength. The valid range is from 1.0 to 5.0. The correspondent char array can be passed directly as OPENFILENAME.lpstrFilter.

Return Value: None

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_save_page_dlg

Declaration:

BOOL ACCUAPI IG_gui_save_page_dlg (
    HWND		hWnd,
    LPCHAR		lpTitle,
    HIGEAR hIGear,
    LPAT_LMODE		 lpnSaveList,
    UINT		nSListSize,
    LPAT_IGGUI_SAVEFILE_INFO lpSFInfo
    );

Arguments:

hWnd
a handle of the parent window
lpTitle
a dialog title
hIGear
a pointer to the HIGEAR
lpnSaveList
a format list
nSListSize
a format list size
lpSFInfo
Stores information about how to save image file. A pointer to the following structure: AT_IGGUI_SAVEFILE_INFO

Structure declaration:

typedef struct tag AT_IGGUI_SAVEFILE_INFO
{
CHAR				FileName[_MAX_PATH];
BOOL				bOverwrite;
AT_MODE				nFormat;
AT_IGGUI_SAVEPAGE_INFO				 PageInfo;
} AT_IGGUI_SAVEFILE_INFO;

Structure members:

FileName
the name of file where to save
bOverwrite
if true then current file will be deleted first
nFormat
format ID to save
PageInfo
used only if bInsertPage=TRUE. A pointer to the following structure:
AT_IGGUI_SAVEPAGE_INFO

Structure declaration:

typedef struct tag AT_IGGUI_SAVEPAGE_INFO
{
    UINT	 nPage;
    AT_MODE	 nCompression;
    BOOL	 bReplace;
}AT_IGGUI_SAVEPAGE_INFO;

Structure members:

nPage
a page to save
nCompression
a compression to use
bReplace
a replacement flag

Purpose:

Shows the file save dialog and returns the file name and page number to save or replace. It also returns the format identifier if file format of the image is detected.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

#include "IG_gui_common.h"
AT_IGGUI_SAVEFILE_INFO				SFInfo;
HIGEAR				hIGear;
LPAT_DIB			lpDIB
memset( &SFInfo, 0, sizeof(SFInfo) );
IG_image_DIB_pntr_get( hIGear, &lpDIB );
IG_gui_save_page_dlg( hWnd, NULL, hIGear, NULL, 0, &SFInfo );

Sample: COLOR, IMG_PROC, JPEG, MDI, PALEDT,

PIX_ACC, PRINT, ART, FILTER, IC, MULTIMED,

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_save_pageinsert_dlg

Declaration:

BOOL  ACCUAPI  IG_gui_save_pageinsert_dlg(
    HWND		hWnd,
    LPAT_DIB		 lpDIB,
    LPAT_IGGUI_FORMAT_CB				 lpFnCB,
    LPAT_IGGUI_SAVEPAGE_INFO	 			lpOutInfo
    );

Arguments:

hWnd
a handle of the parent window
lpDIB
a pointer to the DIB
lpFnCB
A set of callback functions that is used to get information about the file. Pointer to the following structure: AT_IGGUI_FORMAT_CB
lpOutInfo
Stores information about how to save image page. Pointer to the following structure: AT_IGGUI_SAVEPAGE_INFO

Structure declaration:

typedef struct tagAT_IGGUI_SAVEPAGE_INFO
{
UINT		nPage;
AT_MODE 		nCompression;
BOOL		bReplace;
} AT_IGGUI_SAVEPAGE_INFO;

Structure members:

nPage
Position of page to insert.
nCompression
a compression to use
bReplace
a replacement flag

Structure declaration:

typedef  struct  tagAT_IGGUI_FORMAT_CB
{
    LPVOID				lpPrivate;
    LPFNIGGUI_FORMAT_DETECT				 lpfnFormatDetect;
    LPFNIGGUI_PAGE_COUNT_GET				 lpfnPageCountGet;
    LPFNIGGUI_PAGE_INFO_GET				 lpfnPageInfoGet;
    LPFNIGGUI_PAGE_LOAD				 lpfnPageLoad;
}AT_IGGUI_FORMAT_CB;

Structure members:

lpPrivate
A pointer to the private data to be used in the callbacks. Usually it's a file name the page will be inserted to.
lpfnFormatDetect
A pointer to the callback function that implements file format detection routine. LpPrivate is a file name.
lpfnPageCountGet
A pointer to the callback function that calculates a number of pages in the file. LpPrivate is a file name.
lpfnPageInfoGet
A pointer to the callback function that retrieves file information. LpPrivate is a file name.
lpfnPageLoad
A pointer to the callback function that loads a file. LpPrivate is a file name.

Purpose:

This function shows the insert page dialog that can be used to specify the saving parameters for the inserted page.

Return Value:

If the user specifies parameters and clicks the OK button, the return value is nonzero. If the user cancels or closes the dialog box or an error occurs, the return value is zero.

Example:

AT_IGGUI_FORMAT_CB          fcb;
LPAT_IGGUI_OFNCUSTDATA      lpofnCustData;
// lpofnCustData initialization
...
LPAT_IGGUI_SAVEFILE_INFO    lp_sf_info =
lpofnCustData->lp_sf_info;
LPAT_IGGUI_SAVEPAGE_INFO    lp_sp_info = &(lp_sf_info-
>PageInfo);
...
fcb.lpfnFormatDetect  = IG_GUI_CB_detect_file;
fcb.lpfnPageCountGet  = IG_GUI_CB_pagecount_file;
fcb.lpfnPageInfoGet   = IG_GUI_CB_info_file;
fcb.lpfnPageLoad      = IG_GUI_CB_load_file;
fcb.lpPrivate         = FileName;
...
IG_gui_save_pageinsert_dlg( hDlg, lpDIB, &fcb, lp_sp_info );

Sample: GUI

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_gui_switch_enableicc

Declaration:

AT_BOOL ACCUAPI IG_gui_switch_enableicc();

Arguments:

None

Description:

This method switches the state of enabling/disabling ICC support, and returns the state after switching.

Bits Per Pixel:

N/A

Return Value:

True/False

Example:

AT_BOOL bICCEnabled = FALSE;
/* Switch the state and return the result after switching */
bICCEnabled = IG_gui_switch_enableicc();
...

Sample:

IMG_PROC


IG_gui_switch_showiccwarning

Declaration:

AT_BOOL ACCUAPI IG_gui_switch_showiccwarning();

Arguments:

None

Description:

This method switches the state of the registry entry that determines whether we should show the warning dialog related to embedded color profile or non-RGB color format, and returns the result after switching.

Bits Per Pixel:

N/A

Return Value:

True/False

Example:

AT_BOOL bShowICCWarning = FALSE;
/* Switch the state and return the result after switching */
bShowICCWarning = IG_gui_switch_showiccwarning();
...

Sample:

IMG_PROC


ImageClean Component API Function Reference

This Chapter provides detailed information about all ImageGear ImageClean component functions.

NOTE: ImageClean functions are only accessible through the ImageClean component named "CLN". Please see the section Component Manager API.

ImageClean functions are designated with the prefix IG_IC_:

IG_IC_check_for_noise
Checks the image for the number of objects exceeding the size of the specified threshold value.
IG_IC_clean_borders
Automatically detects and removes large black regions near the borders of a 1-bit image.
IG_IC_clean_borders_ex
Detects and removes large black regions that are placed near the borders of a 1-bit image and have characteristics set by parameters of this function.
IG_IC_crop_auto
Automatically crops any white borders from a 1-bit image.
IG_IC_invert_black_image
Inverts all pixel values of a 1-bit image in which the percentage of black pixels is higher than the value you assign.
IG_IC_invert_white_text
Automatically detects areas of white text on black backgrounds in 1-bit images, and inverts them so that they become black text on white backgrounds.
IG_IC_invert_white_text_ex
Automatically detects areas of white text on black backgrounds in 1-bit images and inverts them so that they become black text on white backgrounds. This function scans your entire image and makes adjustments to all areas of white text (on black) that fall within the scope of your settings.
IG_IC_orient_auto
Automatically determines the proper orientation of a 1-bit image and rotates the image to the proper orientation
IG_IC_orient_auto_ex
Automatically determines what the proper orientation of a 1-bit image should be and rotates this image to achieve that proper orientation.
IG_IC_remove_dot_lines
Automatically detects and removes the dot lines on the 1-bit scanned image.
IG_IC_remove_lines
Automatically detects and removes the horizontal and vertical lines on the 1-bit scanned image such as frames and tables.
IG_IC_remove_punch_holes
Automatically detects and removes the punch holes on the 1-bit scanned image.

ImageClean has the following structures:

AT_IC_DOT_LINE_OPTIONS
Specifies parameters for IG_IC_remove_dot_lines method.
AT_IC_LINE_OPTIONS
Specifies parameters for IG_IC_remove_lines method.
AT_IC_PUNCH_HOLE_PARAMS
Specifies parameters for IG_IC_remove_punch_holes method.

ImageClean has the following enumerations:

enumIGICDirection
Specifies types of object orientations for ImageClean API.
enumIGICUnits
Specifies types of the measure units used in ImageClean.


IG_IC_check_for_noise

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IC_check_for_noise (HIGEAR hIGEAR, UINT
nObjectSize, LPUINT lpnObjectsAmount);

Arguments:

hIGear
HIGEAR handle of image
nObjectSize
Object size threshold value
lpnObjectsAmount
Pointer to variable to place the result to

Description:

This function checks the image for the number of objects exceeding the size of the specified threshold value. Object here means a connected group of black pixels. The object size is a diagonal of the minimum circumscribed rectangle that contains the object.

This function can be used to detect blank paper sheets in the scanner tray when the resulting image is almost clear and may contains only several black "noise" pixels.

See also:

Component Manager API

Bits Per Pixel: 1

Return value:

If the function is successful, the return value is IGE_SUCCESS. If the function fails, the return value is the error count.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IC_clean_borders

Group: Image Processing

Declaration:

AT_ERRCOUNT IG_IC_clean_borders ( HIGEAR hIGear);

Arguments:

hIGear
HIGEAR handle of image

Description:

This function automatically detects and removes large black regions near the borders of a 1-bit image. These black borders can result from scanning an image that was reproduced with a copier onto paper that was larger than the image itself.

See also:

Component Manager API

Bits Per Pixel: 1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: IC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IC_clean_borders_ex

Group: Image Processing

Declaration:

AT_ERRCOUNT IG_IC_clean_borders_ex (
    HIGEAR hIGear,
    UINT nMaxLeftBorder,
    UINT nMaxRightBorder,
    UINT nMaxTopBorder,
    UINT nMaxBottomBorder,
    UINT nMinLinesNum,
    UINT nMinLineWidth
);

Arguments:

hIGear
HIGEAR handle of image.
nMaxLeftBorder
Maximal size of left border.
nMaxRightBorder
Maximal size of right border.
nMaxTopBorder
Maximal size of top border.
nMaxBottomBorder
Maximal size of bottom border.
nMinLinesNum
Minimal number of lines with width not less than nMinLineWidth in one border block.
nMinLineWidth
Minimal width of lines in one border block. Those blocks that have not less then nMinLinesNum number of lines with nMinLineWidth width or wider will be removed from image.

Description:

This function detects and removes large black regions that are placed near the borders of a 1-bit image and have characteristics set by parameters of this function. These black borders can appear as a result of scanning an image that was reproduced with a copier onto paper that was larger than the image itself.

First 4 parameters set maximal size of all borders. It means the pixels that lie outside of the borders will not be deleted. But it doesn't mean that all pixels in the borders will be deleted. Last two parameters serve for informing the function which objects in the borders should be deleted - only black objects that have not less than nMinLinesNum lines with width not less than nMinLineWidth will be deleted. As for the left and right borders, objects lines are actually parts of screen lines but as for top and bottom borders those lines are screen columns.

NOTE: This function can be applied several times. First time large values can be set for all parameters and thus large borders will be removed without removing actual image parts. Then setting small values for the parameters will cause removing of small spots near the edges of the image.

See Also:

Component Manager API

Bits Per Pixel:

1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.


IG_IC_crop_auto

Group: Image Processing

Declaration:

AT_ERRCOUNT IG_IC_crop_auto ( HIGEAR hIGear);

Arguments:

hIGear
HIGEAR handle of image

Description:

This function automatically crops any white borders from a 1-bit image. For example, if there is a left margin of 1 inch, where no text is present, this will be cropped away. If the bottom of the page has 3 inches of white space, it will be cropped away. This function automatically determines how much white border exists on all four sides of the image and crops accordingly. The image is not resized.

See also:

Component Manager API

Bits Per Pixel:

1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IC


IG_IC_invert_black_image

Group: Image Processing

Declaration:

AT_ERRCOUNT IG_IC_invert_black_image (
    HIGEAR	 hIGear,
    UINT 	uPercent_of_black
);

Arguments:

hIGear
HIGEAR handle of image
uPercent_of_black
Minimum necessary percentage of black pixels on the image to trigger auto-inversion.

Description:

This function inverts all pixel values of a 1-bit image in which the percentage of black pixels is higher than the value you assign to uPercent_of_black.

See also:

Component Manager API

Bits Per Pixel:

1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IC


IG_IC_invert_white_text

Group: Image Processing

Declaration:

AT_ERRCOUNT IG_IC_invert_white_text (
    HIGEAR hIGear,
    INT MinX,
    INT MinY,
    INT MinT
);

Arguments:

hIGear
HIGEAR handle of image
MinX
Miminal width of the region to be considered
MinY
Minimum height of the region to be considered
MinT
Minimum "thickness" of spaces that fall in between sections of text that will be inverted

Description:

This function automatically detects areas of white text on black backgrounds in 1-bit images, and inverts them so that they become black text on white backgrounds. This function scans your entire image and makes adjustments to all areas of white text on black that fall within the scope of your settings.

The arguments MinX and MinY tell ImageGear the minimum width and height (respectively) for areas that you would like to invert. For example, if you set MinX = 60 and MinY = 20, ImageGear will only invert sections of white text on black background that have a minimum width of 60 pixels and a minimum height of 20 pixels. The third argument of this function, MinT, sets the minimum "thickness" of spaces that fall in-between sections of text that will be inverted. This minimum value tells ImageGear what sections of text should be treated as all one section based on how close they are to one another. As an example: let's say you have three adjacent sections of white text on black backgrounds that contain the words: "There" "is" "hope." If "There" and "hope" meet your minimum size requirements they will be inverted. If "is" is below your minimum size requirements and you have not set MinT, "is" will note be inverted and your final result will be that "There" and "hope" look normal, while "is" remains as white text on black background. To keep this from happening (if you so desire), you would need to set MinT to a value small enough to include the spaces before and after the word "is". This way all the words would be treated as one section and inverted together.

See also:

Component Manager API

Bits Per Pixel:

1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

NOTE: See also IG_IC_invert_white_text_ex() function.

Samples:

IC


IG_IC_invert_white_text_ex

Group: Image Processing

Declaration:

AT_ERRCOUNT IG_IC_invert_white_text_ex (
    HIGEAR hIGear,
    INT MinX,
    MinY,
    INT MinT,
    INT MinLetterSize,
    INT MaxLetterSize,
    INT MaxBorder
);

Arguments:

hIGear
HIGEAR handle of image
MinX
Minimum width of the region to be considered
MinY
Minimum height of the region to be considered
MinT
Minimum "thickness" of spaces falling between sections of text for inversion
MinLetterSize
Minimum size of the white letter
MaxLetterSize
Maximum size of the white letter
MaxBorder
Maximum size of the border around the letter cell

This is another more powerful and flexible function for inverting white text. It automatically detects areas of white text on black backgrounds in 1-bit images and inverts them so that they become black text on white backgrounds. This function scans your entire image and makes adjustments to all areas of white text (on black) that fall within the scope of your settings.

  • The arguments MinX and MinY tell ImageGear the minimum width and height (respectively) for areas that you would like to invert. For example, if you set MinX = 60 and MinY = 20, ImageGear will only invert sections of white text on black background that have a minimum width of 60 pixels and a minimum height of 20 pixels.
  • The third argument of this function, MinT, sets the minimum "thickness" of spaces that fall between sections of text that will be inverted. This minimum value indicates those sections of text to be treated as one section based on how close they are to one another. As an example, let's say you have three adjacent sections of white text on black backgrounds that contain the words, "There," "is," and "hope." If "There" and "hope" meet your minimum size requirements they will be inverted. If "is" is below your minimum size requirements and you have not set MinT, "is" will note be inverted, resulting in "There" and "hope" looking normal, while "is" remains white text on black background. To prevent this (if desired), you would need to set MinT to a value small enough to include the spaces before and after the word "is." This way, all the words would be treated as one section and inverted together.
  • The arguments MinLetterSize and MaxLetterSize determine the minimum and maximum sizes of the white letters to be inverted. In this case letter size means the maximum value of width and height of the letter cell that is the minimum rectangle that completely covers the letter.
  • The argument MaxBorder sets size of the maximum border around the letter that will be inverted along with the letter cell. For example, if width and height of the letter cell are 20 and 30 respectively and MaxBorder = 10, then the width and the height of the rectangle that will be inverted are 40 (10+20+10) and 50 (10+30+10) respectively. Please be careful when setting this parameter. If it is very large, it is possible that incorrect image areas will be inverted.

See also:

Component Manager API

Bits Per Pixel:

1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

NOTE: See also IG_IC_invert_white_text() function.

Sample:

IC


IG_IC_orient_auto

Group: Image Processing

Declaration:

AT_ERRCOUNT IG_IC_orient_auto ( HIGEAR hIGear);

Arguments:

hIGear
HIGEAR handle of image

Description:

This function automatically determines the proper orientation of a 1-bit image and rotates the image to the proper orientation.

You should call this function after the IG_IP_deskew_auto () function because the de-skew function fixes only the angle of an image, not its orientation.

See also:

Component Manager API

Bits Per Pixel:

1

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Sample:

IC


IG_IC_orient_auto_ex

Group: Image Processing

Declaration:

AT_ERRCOUNT IG_IC_orient_auto_ex (
    HIGEAR hIGear,
    INT nDocumentType
);

Arguments:

hIGear
HIGEAR handle of image
nDocumentType
Type of the input document type's alignment. Currently there are three document type's alignment constants:
IG_IC_STANDARD_DOC,
IG_IC_LEFT_ALIGNED_DOC,
IG_IC_RIGHT_ALIGNED_DOC

Description:

This function is the enhanced version of IG_IC_orient_auto () function. It automatically determines what the proper orientation of a 1-bit image should be and rotates this image to achieve that proper orientation.

If the input document is left (or right) aligned and contains only the text formed in one column then set nDocumentType parameter to IG_IC_LEFT_ALIGNED_DOC (or IG_IC_RIGHT_ALIGNED_DOC accordingly). Otherwise (or if you don't know anything about the loaded document) set nDocumentType to IG_IC_STANDARD_DOC.

See also:

Component Manager API

Bits Per Pixel: 1

Return Value:

Returns the number of ImageGear errors that occurred during this function call

Sample: IC

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_IC_remove_dot_lines

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IC_remove_dot_lines(
    HIGEAR hIGear,
    LPAT_IC_DOT_LINES_OPTIONS lpParameters
);

Parameters:

hIGear
Image to apply punch holes removal to.
lpParameters
Parameters for dot lines removal method.

Description:

This method automatically detects and removes the dot lines on the 1-bit scanned image. The method takes a 1-bit image page and the set of advanced parameters specifying the diameter and number of dots in line.

Bits Per Pixel:

1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample:

IC

See Also:

AT_IC_DOT_LINE_OPTIONS


IG_IC_remove_lines

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IC_remove_lines(
            HIGEAR                    hIGear,
            LPAT_IC_LINE_OPTIONS     lpParameters
            );

Parameters:

hIGear
Image to apply punch holes removal to.
lpParameters
Parameters for dot lines removal method.

Description:

This method automatically detects and removes the horizontal and vertical lines on the 1-bit scanned image such as frames and tables. The method takes a 1-bit image page and the set of advanced parameters specifying the orientation of lines to detect and its parameters.

Bits Per Pixel: 1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: IC

See Also:

AT_IC_LINE_OPTIONS


IG_IC_remove_punch_holes

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI IG_IC_remove_punch_holes(
            HIGEAR                        hIGear,
            LPAT_IC_PUNCH_HOLE_PARAMS     lpParameters
            );

Parameters:

hIGear
Image to apply punch holes removal to.
lpParameters
Parameters for punch holes removal method.

Description:

This method automatically detects and removes the punch holes on the 1-bit scanned image. It works for most common hole puncher standards including 2, 3, 4 and 5 hole puncher marks. The method takes a 1-bit image page and the set of advanced parameters specifying the location and diameter of punch holes.

Bits Per Pixel: 1

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: IC

See Also:

AT_IC_PUNCH_HOLE_PARAMS


ImageClean Structures

ImageClean has the following structures:

  • AT_IC_DOT_LINE_OPTIONS
  • AT_IC_LINE_OPTIONS
  • AT_IC_PUNCH_HOLE_PARAMS


AT_IC_DOT_LINE_OPTIONS

Group: Structure

Declaration:

typedef struct tagAT_IC_DOT_LINE_OPTIONS
{
    AT_DOUBLE						dMinDiameter;
    AT_DOUBLE						dMaxDiameter;
    AT_INT						nMinNumber;
    enumIGICUnits						nUnit;
    enumIGICDirection						nDirection;
} AT_IC_DOT_LINE_OPTIONS, *LPAT_IC_DOT_LINE_OPTIONS;

Parameters:

dMinDiameter
Minimal size of dot in line, size considered as diameter of respective circle. Measure unit is set by Unit field. Default value is 1 mm.
dMaxDiameter
Maximal size of dot in line, size considered as diameter of respective circle. Measure unit is set by Unit field. Default value is 3 mm.
nMinNumber
Minimal number of dots in line. Default value is 4.
nDirection
Direction of lines to detect. Default is IG_IC_DIRECTION_HORIZONTAL.
nUnit
Dot's size measure unit. Default value is IG_IC_UNIT_MM.

Description:

This structure specifies parameters for IG_IC_remove_dot_lines method.

See Also:

enumIGICUnits

enumIGICDirection


AT_IC_LINE_OPTIONS

Group: Structure

Declaration:

typedef struct tagAT_IC_LINE_OPTIONS
{
    AT_DOUBLE						dMaxWidth;
    AT_DOUBLE						dMinLength;
    AT_DOUBLE						dMaxBreak;
    enumIGICUnits						nUnit;
    enumIGICDirection						nDirection;
} AT_IC_LINE_OPTIONS, *LPAT_IC_LINE_OPTIONS;

Parameters:

dMinLength
Minimal length of line segment. All lines that do not exceed this value are ignored. Measure unit is set by Unit field. Default value is 10 mm.
dMaxWidth
Maximal width of line segment. All lines that exceed this value are ignored. Measure unit is set by Unit field. Default value is 1 mm.
dMaxBreak
Maximal distance between segments of broken line. Measure unit is set by Unit field. Default value is 1 mm.
nDirection
Direction of lines to detect. Default is IG_IC_DIRECTION_HORIZONTAL.
nUnit
Line's size measure unit. Default value is IG_IC_UNIT_MM.

Description:

This structure specifies parameters for IG_IC_remove_lines method.

See Also:

enumIGICUnits

enumIGICDirection


AT_IC_PUNCH_HOLE_PARAMS

Group: Structure

Declaration:

typedef struct tagAT_IC_PUNCH_HOLE_PARAMS
{
      AT_DOUBLE         dMinDiameter;
      AT_DOUBLE         dMaxDiameter;
      AT_DOUBLE         dMinAspect;
      AT_DOUBLE         dMaxAspect;
      AT_INT            nAccuracy;
      enumIGICUnits     nUnit;
}
AT_IC_PUNCH_HOLE_PARAMS, *LPAT_IC_PUNCH_HOLE_PARAMS;

Parameters:

dMinDiameter
Minimal object size to remove, size considered as diameter respective circle. Measure unit is set by Unit field. Default value is 4 mm.
dMaxDiameter
Maximal object size to remove, size considered as diameter respective circle. Measure unit is set by Unit field. Default value is 8 mm.
dMinAspect
Minimal width/height ratio of object dimensions. It can be used to detect non-round holes. Default value is 0.95.
dMaxAspect
Maximal width/height ratio of object dimensions. It can be used to detect non-round holes. Default value is 1.05
nAccuracy
Accuracy of the punch hole's detection. It is measured in %. Default value is 80%.
nUnit
Hole's size measure unit. Default value is IG_IC_UNIT_MM.

Description:

This structure specifies parameters for IG_IC_remove_punch_holes method.

See Also:

enumIGICUnits


ImageClean Enumerations

The ImageClean component has the following enumerations:

  • enumIGICDirection
  • enumIGICUnits


enumIGICDirection

Group: Enumerations

Description:

This enumeration specifies types of object orientations for ImageClean API.

Declaration:

enum enumIGICDirection
{
    IG_IC_DIRECTION_HORIZONTAL	= 1,
    IG_IC_DIRECTION_VERTICAL	= 2,
};

Values:

IG_IC_DIRECTION_HORIZONTAL
Direction is horizontal.
IG_IC_DIRECTION_VERTICAL
Direction is vertical.


enumIGICUnits

Group: Enumerations

Description:

This enumeration specifies types of the measure units used in ImageClean.

Declaration:

enum enumIGICUnits
{
    IG_IC_UNIT_PIXEL	= 0,
    IG_IC_UNIT_INCH	= 1,
    IG_IC_UNIT_MM	= 2,
};

Values:

IG_IC_UNIT_INCH
Units set in inches.
IG_IC_UNIT_MM
Units set in millimeters.
IG_IC_UNIT_PIXEL
Units set in pixels.


ISIS Component API Function Reference

The ImageGear ISIS component provides high-performance scanning functionality using the Image and Scanner Interface Specification (ISIS) for superior scanner control and speed. This component supports data compression and decompression and file reading and writing in most popular formats.

The ImageGear ISIS component help provides usage information for toolkit functions, tags, and errors. The following function groups are included in this API reference:

  • General Functions
  • ISIS Pipe Functions
  • ISIS Single-Step Driver Control Functions
  • ISIS Driver Communication and Setup Functions
  • Choice Functions
  • Tag Functions
  • Install Driver Functions
  • Custom Scanner Functions
  • Tags


General Functions

IG_ISIS_env_get

Read a value from an entry in the scanning configuration file.

Description

IG_ISIS_env_get reads the value of an entry in the ISIS scanning configuration file SETSCAN.INI.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_env_get(
    LPSTR lpszRoot,
    LPSTR lpszDriver,
    LPSTR lpszKey,
    LPSTR lpszValue,
    WORD  wMax
    );

Parameters

lpszRoot
This parameter is reserved and should always be zero.
lpszDriver
The name of the section in the configuration file that contains the specified entry.
lpszKey
The name of the entry whose value is to be read.
lpszValue
Pointer to a buffer that is to contain the value of the entry.
wMax
Specifies the size, in characters, of the buffer pointed to by lpszValue.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_env_get to read from the scanning configuration file. If you are creating your own scanner selection dialog, you should read from and write to the same sections and entries used by the standard scanner selection dialog in order to ensure compatibility with other ISIS applications. For keeping track of non-scanning related parameters or those scanning parameters that are specific to your application, you should use your own custom INI file.

See Also

IG_ISIS_env_put


IG_ISIS_env_put

Write a value into an entry in the scanning configuration file.

Description

IG_ISIS_env_put writes a value into an entry in the scanning configuration file SETSCAN.INI.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_env_put(
    LPSTR lpszRoot,
    LPSTR lpszDriver,
    LPSTR lpszKey,
    LPSTR lpszValue
    );

Parameters

lpszRoot
This parameter is reserved and should always be zero.
lpszDriver
The name of the section in the configuration file that contains the specified entry.
lpszKey
The name of the entry whose value is to be read.
lpszValue
Pointer to a buffer that is to contain the value of the entry.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_env_put to write to the scanning configuration file. If you are creating your own scanner selection dialog, you should read from and write to the same sections and entries used by the standard scanner selection dialog in order to ensure compatibility with other ISIS applications. For keeping track of non-scanning related parameters or those scanning parameters that are specific to your application, you should use your own custom INI file.

See Also

IG_ISIS_env_get


IG_ISIS_localize_language_get

Retrieve the current localization language number.

Description

IG_ISIS_localize_language_get gets the current language being used for dialog and string localization.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_localize_language_get(
    LPDWORD lpdwLanguage
    );

Parameters

lpdwLanguage
Points to the localization language number after the function returns.

Usage

The strings in the ISIS component used to display information in built-in dialog boxes and report scanner status can be localized to a number of supported languages. These languages are currently French, Spanish, German, Swedish, Italian, and Japanese. The first five are supported on standard English Windows, but Japanese is only available if your system is capable of displaying Japanese text.

Use IG_ISIS_localize_language_get to determine the currently language being used for string localization. See IG_ISIS_localize_language_set for more information on localization support in the toolkit.

See Also

IG_ISIS_localize_language_set.


IG_ISIS_localize_language_set

Set the current localization language number.

Description

IG_ISIS_localize_language_set sets the current language being used for dialog and string localization.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_localize_language_set(
    DWORD dwLanguage
    );

Parameters

dwLanguage
Specifies the localization language number to use.

Usage

The strings in the ISIS component used to display information in built-in dialog boxes and report scanner status can be localized to a number of supported languages. These languages are currently French, Spanish, German, Swedish, Italian, and Japanese. The first five are supported on standard Windows, but Japanese is only available if your system is capable of displaying Japanese text.

There are several methods used to determine which language to use for localization. They are listed below in the order of precedence:

  1. Using the IG_ISIS_localize_language_set function to specify a localization language anytime while the application is running.
  2. Set the iLanguage= line to the desired language in the scanning configuration file, SETSCAN.INI.
  3. In Windows 95 and Windows NT, select the desired default language using the Regional Settings control panel.
  4. In Windows 3.x, set the sLanguage= line to the desired language in the Windows configuration file, WIN.INI.

If a language is selected by the above methods but it is not a currenly supported language, then English will be used as the default.

See Also

IG_ISIS_localize_language_get.


ISIS Pipe Functions

IG_ISIS_drv_append

Add a driver to the end of a pipe.

Description

The IG_ISIS_drv_append function appends a specified driver onto the end of an existing ISIS pipe.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_append(
    HISISDRV hPipe,
    HISISDRV hDriver
    );

Parameters

hPipe
The pipe handle (which is usually the handle of the head driver of the pipe).
hDriver
The driver handle to append to the pipe.

Usage

Use IG_ISIS_drv_append to add a driver to the end of an ISIS pipe. For example, if you have a pipe that includes a scanner driver and a compression driver, you can use IG_ISIS_drv_append to add a file writing driver (such as PIXFPACK) to the end of the pipe, without knowing the handle of the last driver in the pipe.

See Also

IG_ISIS_drv_chop_before_driver, IG_ISIS_drv_chop_tail, IG_ISIS_drv_get_tail.


IG_ISIS_drv_chop_before_driver

Break a pipe into two pipes.

Description

The IG_ISIS_drv_chop_before_driver function unlinks the driver you specify and all following drivers in a pipe. This leaves one pipe consisting of all the drivers up to but not including the driver you specified, and another pipe starting with the driver you specified and drivers that follow it.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_chop_before_driver(
    HISISDRV hPipe,
    HISISDRV hChopee
    );

Parameters

hPipe
The pipe handle (which is usually the handle of the head driver of the pipe).
hChopee
The driver handle before which to break the pipe.

Usage

Use IG_ISIS_drv_chop_before_driver to break an ISIS pipe into two independent pipes. After calling this function, you are left with two pipes in memory-one consisting of the original pipe up to but not including the driver referenced by hChopee, and one starting with hChopee and all drivers that followed it in the original pipe.

See Also

IG_ISIS_drv_append, IG_ISIS_drv_chop_tail, IG_ISIS_drv_get_tail.


IG_ISIS_drv_chop_tail

Unlink the last driver from a pipe.

Description

The IG_ISIS_drv_chop_tail function unlinks the last driver from an ISIS pipe.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_chop_tail(
    HISISDRV hPipe
    );

Parameters

hPipe
The pipe handle (which is usually the handle of the head driver of the pipe).

Usage

Use IG_ISIS_drv_chop_tail to unlink the last driver of a pipe. You do not need to have a handle to the last driver to unlink it.

See Also

IG_ISIS_drv_append, IG_ISIS_drv_chop_before_driver, IG_ISIS_drv_get_tail.


IG_ISIS_drv_get_link

Get the handle of the next driver in a pipe.

Description

The IG_ISIS_drv_get_link function gets the handle of the next driver in a pipe.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_get_link(
    HISISDRV   hPipe,
    LPHISISDRV lphNext
    );

Parameters

hPipe
The handle of the driver for which the handle of the next driver is to be retrieved.
lphNext
A pointer to a handle which is filled in by this function with the handle of the next driver in the pipe.

Usage

Use IG_ISIS_drv_get_link to find out the handle of the next driver in a pipe. This information is useful when you have loaded a pipe with IG_ISIS_drv_load_init_pipe and only have a handle to the head driver.

See Also

IG_ISIS_drv_get_split.


IG_ISIS_drv_get_split

Get the handle of a driver's sibling.

Description

The IG_ISIS_drv_get_split function gets the handle of the a driver that has been split from the specified driver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_get_split(
    HISISDRV   hPipe,
    LPHISISDRV lphSibling
    );

Parameters

hPipe
The handle of the driver for which the handle of the sibling driver is to be retrieved.
lphSibling
A pointer to a handle which is filled in by this function with the handle of the sibling driver.

Usage

Use IG_ISIS_drv_get_split to find out the handle of the specified driver's sibling (if any). If the driver has not been split, and therefore does not have a sibling driver, then this function will fill in lphSibling with 0.

See Also

IG_ISIS_drv_get_link.


IG_ISIS_drv_get_tail

Get the handle of the last driver in a pipe.

Description

The IG_ISIS_drv_get_tail function gets the handle of the last driver in a pipe.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_get_tail(
    HISISDRV   hPipe,
    LPHISISDRV lphTail
    );

Parameters

hPipe
The handle of the pipe (which is usually the handle of the head driver).
lphTail
A pointer to a handle which is filled in by this function with the handle of the last driver in the pipe.

Usage

Use IG_ISIS_drv_get_tail to find out the handle of the last driver in a pipe. This information is required if you want to add another driver, remove a driver, or split the pipe. The functions listed under "See Also," below, all use IG_ISIS_drv_get_tail to perform these functions.

See Also

IG_ISIS_drv_append, IG_ISIS_drv_chop_before_driver, IG_ISIS_drv_chop_tail.


IG_ISIS_drv_init

Initialize a driver.

Description

The IG_ISIS_drv_init function is used to initialize a driver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_init(
    HISISDRV hDriver,
    LPSTR    lpszName,
    AT_MODE  nFlags
    );

Parameters

hDriver
The handle of the driver to be initialized.
lpszName
For most drivers, this parameter can either be the same as the string that was passed to IG_ISIS_drv_load when the driver was loaded or NULL (either will work). When initializing file reading drivers, lpszName may contain the name of the file to read. In previous versions of the toolkit, the application was required to insert a filename, and additionally was required to insert a comma prior to the filename (",filename"); otherwise, a bad parameter error would occur.
nFlags
For most drivers, this parameter must be zero (0).

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

IG_ISIS_drv_init should be called immediately after IG_ISIS_drv_load and before any other functions. Because IG_ISIS_drv_load usually doesn't communicate with the driver. if the driver cannot communicate properly with its target, then IG_ISIS_drv_load will succeed. But because IG_ISIS_drv_init tries to communicate with the driver, it will fail if there is a communication problem.

Example

The following example loads and initializes two drivers:

/* IG_ISIS_drv_init example */
IG_ISIS_drv_load(0, "EKi50i60", &hScan, 0);
IG_ISIS_drv_init(&hScan, "EKi50i60", 0);

See Also

IG_ISIS_drv_link, IG_ISIS_drv_load, IG_ISIS_drv_load_init_pipe


IG_ISIS_drv_link

Establish a link between two drivers.

Description

IG_ISIS_drv_link sets up a link between two drivers. Once links are established, virtually all tags sent to hDriver are also sent to hNext. Note, however, that when data is sent to hDriver (see IG_ISIS_drv_put_data, the data is usually processed before being passed to hNext, so that hNext receives a modified form of the data that was sent to hDriver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_link(
    HISISDRV hDriver,
    HISISDRV hNext
    );

Parameters

hDriver
The handle of the driver from which the link is being originated. The output of this driver is linked to the input of hNext.
hNext
The handle of the driver to which the link is being made. The input of this driver is connected to the output of hDriver.

Usage

IG_ISIS_drv_link and its companion IG_ISIS_drv_split establish ISIS pipes. A pipe is a group of linked drivers that processes image data in a stream. For example, an application could link together a scanner driver, a set of compression drivers, and a file writing driver. When the pipe is invoked, image data moves in a stream from the scanner's output through each driver and is saved in a file in one operation. (In this example, the entire image never exists in memory at one time.).

IG_ISIS_drv_link establishes parent-child relationships between drivers; that is, the linked driver's input is dependent on the linking driver's output. IG_ISIS_drv_split establishes sibling relationships between drivers; that is, the linked driver shares the linking driver's input and each driver's output is independent of the other driver.

To unlink a driver, use IG_ISIS_drv_link to link the driver with a null hNext:

INT32 IG_ISIS_drv_link(hDriver, 0);

A driver can only be linked to a single hNext destination. To link a driver to two destinations, link the driver to the first destination, then use IG_ISIS_drv_split to split the first destination to the second destination. This is illustrated in the example below.

IG_ISIS_drv_link is used as part of a set of four related functions: IG_ISIS_drv_load which loads individual drivers, IG_ISIS_drv_init which initializes both individual drivers and entire linked pipes of drivers, and IG_ISIS_drv_link and IG_ISIS_drv_split which establish relationships between the loaded drivers. Alternatively, the IG_ISIS_drv_load_init_pipe function loads, initializes, and links drivers in a single step. Use the separate load, initialize, and link/split functions when you need to either link and unlink drivers that remain resident in memory, and when you need to split an ISIS pipe into two or more drivers.

NOTE: You cannot link an uninitialized driver, and you cannot unload a linked driver. Attempting to do either of these operations will cause problems including system crashes.

Background

The foundation of using ISIS is understanding ISIS pipes. An ISIS pipe is a linked set of drivers that is established prior to any scanning or image processing. Once all desired drivers are linked, messages from other ISIS functions are sent to the head driver (the first driver in the pipe). The head driver processes the messages and passes them on to the next driver in the pipe. All drivers receive all messages, and either respond to them or ignore them as appropriate. After all necessary configuration and settings are complete, IG_ISIS_run_zone is used to invoke the pipe, causing each driver to perform its intended operation in turn. This pipe structure requires that the desired functionality be implemented as drivers, and allows large image files to be processed without copying the image data from one full-page buffer to another. The result is much faster and more efficient than alternative image processing schemes.

See Also

IG_ISIS_drv_init, IG_ISIS_drv_load, IG_ISIS_drv_load_init_pipe, IG_ISIS_drv_split, IG_ISIS_run_zone .


IG_ISIS_drv_load

Load a driver into memory.

Description

IG_ISIS_drv_load loads a driver into memory so that it may be initialized and linked into an ISIS pipe.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_load(
    LPSTR      lpszRoot,
    LPSTR      lpszName,
    LPHISISDRV lphDriver,
    AT_MODE    nFlags
    );

Parameters

lpszRoot
Reserved for future use. Currently lpszRoot must be (char FAR *) 0. Future implementations may allow an application to specify where to find a driver or other special information.
lpszName
Driver name string or pointer to a callback function.
  • If the IG_ISIS_DRV_LOAD_DIRECT bit of nFlags is false, then lpszName is the filename of a driver. Search location rules are given under "Usage" below. Often, scanner driver filenames are identified by using the IG_ISIS_drv_get_scan_name function. Under Microsoft Windows, the extension .PXW is added to the specified name automatically.
  • If the IG_ISIS_DRV_LOAD_DIRECT bit of nFlags is true, then (INT32 (FAR pascal *) lpszName points to the proc instance of a driver function. This form is useful if you are an advanced programmer and you want to include some driver functionality in your program (called a "minidriver"), but you do not want to create a complete driver. This is most often used to create a "callback" function for your scanning chain.
NOTE: Under Microsoft Windows, the function passed in must be included as an export in the DEF file.
lphDriver
A pointer to a buffer to accept the handle to the driver returned when the driver loads. This handle references the driver until the driver is removed from memory with IG_ISIS_drv_unload.
nFlags
A bit field containing one or more of the following values. Currently, four bits of nFlags are defined:
nFlags Meaning
IG_ISIS_DRV_LOAD_DIRECT False: lpcName is the filename of the driver to load. True: lpcName points to the proc instance of a driver function supplied by the application developer.
IG_ISIS_DRV_LOAD_NEED_ PAGESIZE False: Get IG_ISIS_TAG_PAGESIZE directly from the scanner driver.True: Cause IG_ISIS_TAG_PAGESIZE to be available even if the scanner driver did not implement it.
IG_ISIS_DRV_LOAD_NO_FILTERS False: Load filters as specified in SETSCAN.INI.True: Override other settings and do not load filters.
IG_ISIS_DRV_LOAD_SUPRESS_ DIALOG False: If the driver was already in memory and was not loaded from \WINDOWS\PIXTRAN or from this application's executable directory, display a warning message to the user and load another instance only if the user wants to proceed.True: Do not display warning dialog upon loading another instance of a driver that was already loaded from the "wrong" place 2.
NOTE: Recommended values are shown in bold type.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

You must load each driver that you intend to use, initialize it, then link it with other (previously-loaded and initialized) drivers to form an ISIS pipe. To do this, you use a combination of IG_ISIS_drv_load, IG_ISIS_drv_init, and IG_ISIS_drv_link or IG_ISIS_drv_split. For applications that require simple linear ISIS pipes with no special processing or minidrivers, it is much less work to use the IG_ISIS_drv_load_init_pipe function which can load, initialize, and link all specified drivers in one operation.

Once loaded, initialized, and linked, the driver (and all other linked drivers in the pipe) are used by IG_ISIS_run_zone to process pages as specified by each driver. For example, an application could load a scanner driver, a file compression driver, and a file writing driver to scan, compress and save a file in one operation. In this scenario, three separate drivers need to be loaded, initialized, and linked.

There are several good reasons to use the three separate functions for loading, initializing, and linking drivers as opposed to the single IG_ISIS_drv_load_init_pipe:

  • Using IG_ISIS_drv_split to split a pipe into two driver inputs requires the three step method.
  • Using the IG_ISIS_DRV_LOAD_DIRECT field of nFlags to point to a driver function (that is, to create a minidriver) requires the use of the three step method.
  • In applications where drivers are changed frequently, the three-step method is preferred. Loading drivers from disk into memory is expensive in terms of time. However, there is functionally no performance hit for linking and unlinking drivers. Some application developers may want to load all of the drivers needed during an application instance, and then just link and unlink them as needed. This design requires using the three-step method.

Driver Loading Algorithm

The toolkit uses a special driver loading algorithm to ensure that your application loads the correct version of a driver, even when multiple versions of a driver exist. Keep in mind that some version of the driver you are trying to load may already be loaded in memory, due to some other application or another instance of your application. Once a driver is loaded, loading it again simply references the same driver with a new instance handle. It is not possible to load different copies of a file of the same name.

Each time your application loads a driver that is not already in memory, the toolkit goes through this special driver loading algorithm to:

  1. Ensure that if a driver is already in memory, it is compatible with the version of PIXDFLT you are using.
  2. Ensure that if PIXDFLT is already in memory, it is compatible with the drivers you are trying to load.
  3. Ensure that the version of the driver you are loading is the latest one available.
  4. Provide backward compatibility for older ISIS applications that do not load their drivers from the "correct" place. (The correct place is now \WINDOWS\SYSTEM for all toolkit libraries and \WINDOWS\PIXTRAN for all ISIS drivers.) Many older ISIS applications load their drivers from the application directory, but future support for this capability may be dropped at any time.
NOTE: Your application must check that the specified driver was indeed loaded by IG_ISIS_drv_load before performing any other operations. If, for example, IG_ISIS_drv_init (which should be the very next function call) tries to initialize a driver that is not loaded, unpredictable results will occur, possibly including system crashes.

Background

The foundation of using ISIS is understanding ISIS pipes. An ISIS pipe is a linked set of drivers that is established prior to any scanning or image processing. Once all desired drivers are linked, IG_ISIS_run_zone is used to invoke the pipe, causing each driver to perform its intended operation in turn. This pipe structure requires that the desired functionality be implemented as drivers, and allows large image files to be processed without copying the image data from one full-page buffer to another. The result is much faster and more efficient than alternative image processing schemes.

See Also

IG_ISIS_drv_init, IG_ISIS_drv_link, IG_ISIS_drv_load_init_pipe, IG_ISIS_drv_split, IG_ISIS_run_zone , "AutoPipe" on page 9-1.


IG_ISIS_drv_is_loaded

Checks whether a driver is loaded.

Description

The IG_ISIS_drv_is_loaded function returns true if a driver is loaded.

Syntax

AT_BOOL ACCUAPI IG_ISIS_drv_is_loaded(
    HISISDRV hDriver
    );

Parameters

hDriver
Specifies the handle of the driver whose structure members are to be initialized to zero.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Call IG_ISIS_drv_is_loaded to determine whether or not a particular driver is loaded. You must load and initialize the driver, and then call IG_ISIS_drv_is_loaded to ensure that the driver has been loaded. If the driver was loaded, you can proceed to safely set parameters in the driver, run zones, and so forth. If the driver was not loaded, you can take whatever action necessary for your particular application (for example, the user that there is a problem), and you can skip unloading the driver. (When a driver does not load, it is not a good idea to unload it.

Example

The following example loads a driver and then checks to be sure it loaded before attempting to use the driver.

/* IG_ISIS_drv_is_loaded example */
HISISDRV hDriver;
IG_ISIS_drv_load_init_pipe(0, &hDriver, "driver", 0);
if (IG_ISIS_drv_is_loaded(hDriver)) {
    /* perform actions with driver such as running zones) */
    IG_ISIS_drv_unload(hDriver);


IG_ISIS_drv_load_init_pipe

Load one or more drivers, then initialize and link them.

Description

IG_ISIS_drv_load_init_pipe loads one or more drivers into memory, initializes each driver, and then links them into an ISIS pipe according to the order in which they are specified. This function is functionally equivalent to using IG_ISIS_drv_load, IG_ISIS_drv_init, and IG_ISIS_drv_link multiple times to load, initialized, and link all drivers in a pipe.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_load_init_pipe(
    LPSTR      lpszRoot,
    LPSTR      lpszName,
    LPHISISDRV lphDriver,
    AT_MODE    nFlags
    );

Parameters

lpszRoot
Reserved for future use. Currently lpszRoot must be (char FAR *) 0. Future implementations may allow an application to specify where to find a driver or other special information.
lpszName
Driver name string. Multiple drivers are specified as a single string with each driver name separated by a pipe symbol ( | ). Under Microsoft Windows, the extension .PXW is added to the specified name(s) automatically.
lphDriver
A pointer to a buffer to accept the handle to the head (first) driver, which is returned when the driver loads. This handle references the pipe until the pipe is removed from memory with IG_ISIS_drv_unload_pipe
nFlags
A bit field containing one or more of the following values. Currently, three bits of nFlags are defined:
dwFlags Meaning
IG_ISIS_DRV_LOAD_NEED_ PAGESIZE False: Get IG_ISIS_TAG_PAGESIZE directly from the scanner driver.True: Cause IG_ISIS_TAG_PAGESIZE to be available even if the scanner driver did not implement it.
IG_ISIS_DRV_LOAD_SUPRESS_ DIALOG False: If the driver was already in memory and was not loaded from \WINDOWS\PIXTRAN or from this application's executable directory, display a warning message to the user and load another instance only if the user wants to proceed.True: Do not display warning dialog upon loading another instance of a driver that was already loaded from the "wrong" place 2.
NOTE: Recommended values are shown in bold type.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

IG_ISIS_drv_load_init_pipe automates the process of loading, initializing, and linking drivers to form an ISIS pipe. For applications that require simple linear ISIS pipes with no special processing or minidrivers, IG_ISIS_drv_load_init_pipe is the easiest way to set up a pipe. Keep in mind that you can only reference the entire pipe, because lphDriver is a handle to the head driver only. Also, if your application requires that a pipe's flow be split, or that a callback be used to create a minidriver, or that drivers that remain in memory be linked and unlinked on the fly, then you must use the separate three-step process of calling IG_ISIS_drv_load, IG_ISIS_drv_init, and IG_ISIS_drv_link (and IG_ISIS_drv_split).

NOTE: Your application must check that the specified driver was indeed loaded by IG_ISIS_drv_load before performing any other operations. If, for example, IG_ISIS_drv_init (which should be the very next function call) tries to initialize a driver that is not loaded, unpredictable results will occur, possibly including system crashes.

Once run, all drivers in the pipe can be used by IG_ISIS_run_zone to process pages as specified by each driver. For example, an application could load, initialize, and link a scanner driver, a file compression driver, and a file writing driver to scan, compress and save a file in one operation. In this scenario, all three drivers are loaded, initialized, and linked with one function call.

NOTE: IG_ISIS_drv_load_init_pipe works equally well on single drivers and portions of a pipe. You can, for example, load all of a pipe except the scanner driver, then load the scanner driver separately (so that it can be kept in memory).

Background

The foundation of using ISIS is understanding ISIS pipes. An ISIS pipe is a linked set of drivers that is established prior to any scanning or image processing. Once all desired drivers are linked, IG_ISIS_run_zone is used to invoke the pipe, causing each driver to perform its intended operation in turn. This pipe structure requires that the desired functionality be implemented as drivers, and allows large image files to be processed without copying the image data from one full-page buffer to another. The result is much faster and more efficient than alternative image processing schemes.

See Also

IG_ISIS_drv_init, IG_ISIS_drv_link, IG_ISIS_drv_load, IG_ISIS_drv_split, IG_ISIS_run_zone , "AutoPipe" on page 9-1.


IG_ISIS_drv_split

Split an ISIS pipe into the inputs of two drivers.

Description

IG_ISIS_drv_split takes the input to Driver 1 and routes it to the input of Driver 2 as well. In this way, an ISIS pipe can be made to perform two or more operations simultaneously. For example, a pipe could be made that saves two different types of image files simultaneously.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_split(
    HISISDRV hDriver1,
    HISISDRV hDriver2
    );

Parameters

hDriver1
A handle to the sibling pointer of the driver to which the ISIS pipe was linked by a previous IG_ISIS_drv_link call.
hDriver2
The handle of the driver that is to receive the same input as lpDriver1.

Usage

IG_ISIS_drv_split is used with IG_ISIS_drv_link to establish ISIS pipes. A pipe is a group of linked drivers that processes image data in a stream. For example, an application could link together a scanner driver, a set of compression drivers, and a file writing driver. When the pipe is invoked, image data moves in a stream from the scanner's output through each driver and is saved in a file in one operation. (In this example, the entire image never exists in memory at one time.).

NOTE: IG_ISIS_drv_split splits the input of a driver to the input of another driver. It does not reference the output of any driver A common mistake is to pass in the handle of the driver whose output you want instead of a handle to a driver whose input is desired.

For example, to split the output of driver A into drivers B and C:

WRONG
RIGHT
IG_ISIS_drv_link(A, B);
IG_ISIS_drv_split(A, C);
IG_ISIS_drv_link(A, B);
IG_ISIS_drv_split(B, C);

Where IG_ISIS_drv_link establishes a parent-child relationship between two drivers, IG_ISIS_drv_split establishes a sibling relationship between two drivers.

To understand IG_ISIS_drv_split, it is necessary to understand that each ISIS driver has a child pointer and a sibling pointer. The child pointer references data processed by the driver and points to the next driver in a pipe. The sibling pointer represents data that has not yet been processed by the driver and can be used to point to a driver that is split from the pipe.

To undo a split, use IG_ISIS_drv_split with hDriver2 set to zero (0):

INT32 IG_ISIS_drv_split(hDriver1, 0);

Note that IG_ISIS_drv_split can split the input of a driver into only one other driver. To split a pipe into more than two drivers, you must call IG_ISIS_drv_split multiple times, as shown under "Example" below.

IG_ISIS_drv_split is used in as part of a set of four related functions: IG_ISIS_drv_load which loads individual drivers, IG_ISIS_drv_init which initializes both individual drivers and entire linked pipes of drivers, and IG_ISIS_drv_link and IG_ISIS_drv_split which establish relationships between the loaded drivers. Although the IG_ISIS_drv_load_init_pipe function loads, initializes, and links drivers in a single step, it cannot be used when you need to split an ISIS pipe.

NOTE: A driver can be split to only one other driver. If, for example, a pipe must be split into three drivers, the input of Driver B can be split to Driver C. However, the input of Driver B cannot then be split to Driver D. Instead, the input of Driver C must be split to Driver D. (The end result is the same.)

Example

The following example shows how an ISIS pipe can be established which takes the output of Driver A and sends it to both Driver B and Driver C, and then takes the output of Driver C and sends it to Driver D, Driver E, and Driver F. This example assumes that all five drivers have already been loaded and initialized.

IG_ISIS_drv_link(A, B);
IG_ISIS_drv_split(B C);
IG_ISIS_drv_link(C, D);
IG_ISIS_drv_split(D, E);
IG_ISIS_drv_split(E F);

The above code creates the pipe depicted in the following diagram:

Notice that the last line of the example correctly splits the input of driver E to F. If instead the input of driver D were split again (IG_ISIS_drv_split (D, F)), the split between driver D and E established in the fourth line of the example would be invalidated.

Also note that if you call IG_ISIS_drv_split (D, 0), the link between Driver D and Driver F will be broken.

Background

The foundation of using ISIS is understanding ISIS pipes. An ISIS pipe is a linked set of drivers that is established prior to any scanning or image processing. Once all desired drivers are linked, messages from other ISIS functions are sent to the head driver (the first driver in the pipe). The head driver processes the messages and passes them on to the next driver in the pipe. All drivers receive all messages, and either respond to them or ignore them as appropriate. After all necessary configuration and settings are complete, IG_ISIS_run_zone is used to invoke the pipe, causing each driver to perform its intended operation in turn. This pipe structure requires that the desired functionality be implemented as drivers, and allows large image files to be processed without copying the image data from one full-page buffer to another. The result is much faster and more efficient than alternative image processing schemes.

See Also

IG_ISIS_drv_init, IG_ISIS_drv_link, IG_ISIS_drv_load, IG_ISIS_drv_load_init_pipe, IG_ISIS_run_zone, "AutoPipe" on page 9-1.


IG_ISIS_drv_unload

Remove a driver from memory.

Description

The IG_ISIS_drv_unload function removes a driver from memory and resets interrupt vectors and other system resources.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_unload(
    HISISDRV hDriver
    );

Parameters

hDriver
The handle of the driver to unload.

Usage

IG_ISIS_drv_unload must be called before terminating an application program for each driver loaded by IG_ISIS_drv_load or IG_ISIS_drv_load_init_pipe. If drivers are not unloaded by this function, then interrupt vectors and other system resources will not be properly reset. IamgeGear does not automatically unload any drivers. Drivers left in memory after your application terminates may continue to occupy memory.

IG_ISIS_drv_unload can be called at any time. It performs all necessary cleanup when unloading a driver.

NOTE: Loading and unloading drivers takes processing time. Linking and unlinking loaded drivers takes virtually no processing time. For performance reasons, you may prefer to load most all necessary drivers at the beginning of an application, link and unlink as necessary without unloading, and then unload drivers only upon exiting the application.

Example

The following example loads, initializes, and links a set of drivers, performs some work, and then unlinks and unloads the drivers:

IG_ISIS_drv_load(0, szScanner, &hScan, 0);
IG_ISIS_drv_init(hScan, szScanner, 0);
IG_ISIS_drv_load_init_pipe(0, "RAS2RUN | RUN2G4 | PIXFPACK",
&hPipe, 0);
IG_ISIS_drv_link(hScan, hPipe);
/* Perform ISIS functions on pipe 							*/
/*Unload the pipe											*/
IG_ISIS_drv_link(hScan, 0);
IG_ISIS_drv_unload(hScan);
IG_ISIS_drv_unload_pipe(hPipe);

See Also

IG_ISIS_drv_load, IG_ISIS_drv_load_init_pipe, IG_ISIS_drv_unload_pipe.


IG_ISIS_drv_unload_pipe

Unlink and remove one or more drivers from memory.

Description

The IG_ISIS_drv_unload_pipe function unlinks a linked ISIS pipe and then removes all of the previously linked drivers from memory, resetting their interrupt vectors and other system resources. IG_ISIS_drv_unload_pipe also can be used to unload a driver or pipe that was not set up using IG_ISIS_drv_load_init_pipe.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_unload_pipe(
    HISISDRV hDriver
    );

Parameters

hDriver
The handle of the head (first) driver in the pipe.

Usage

IG_ISIS_drv_unload_pipe can be used in place of IG_ISIS_drv_link (to unlink linked drivers) and IG_ISIS_drv_unload (to unload drivers) to remove an entire ISIS pipe from memory in one operation. This function is often used in applications that use IG_ISIS_drv_load_init_pipe.

NOTE: IG_ISIS_drv_unload_pipe will not unlink or unload drivers in pipes containing splits. If any splits exist in a driver, you must use IG_ISIS_drv_split to unsplit the driver (splitting it to a null pointer (0)), and unload the driver drivers in the split by using IG_ISIS_drv_unload.

Example

The following example loads, initializes, and links a set of drivers, performs some work, and then unlinks and unloads the drivers:

IG_ISIS_drv_load(0, szScanner, &hScan, 0);
IG_ISIS_drv_init(hScan, szScanner, 0);
IG_ISIS_drv_load_init_pipe(0, "RAS2RUN | RUN2G4 | PIXFPACK",
&hPipe, 0);
IG_ISIS_drv_link(hScan, hPipe);
/* Perform ISIS functions on pipe 							*/
/*Unload the pipe											*/
IG_ISIS_drv_unload_pipe(hScan);

See Also

IG_ISIS_drv_link, IG_ISIS_drv_load, IG_ISIS_drv_load_init_pipe, IG_ISIS_drv_split, IG_ISIS_drv_unload.


IG_ISIS_run_zone

Invoke an ISIS pipe and run a zone.

Description

The IG_ISIS_run_zone function combines the functionality of several independent stack, page, and zone functions to make invoking a pipe a one-step process.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_run_zone(
    HISISDRV hDriver,
    LPBYTE   lpBuffer,
    WORD     wSize
    );

Parameters

hDriver
The handle of the head (first) driver in the ISIS pipe. Usually this is either a scanner driver or a file-reading driver.
lpBuffer
A pointer to a character array buffer used by IG_ISIS_run_zone. This array should be 8192 bytes in size, as a larger buffer area is not needed.
wSize
The size of lpBuffer. Must be at least 1 and at most 32K-1. We recommend always using a size of 8192. In testing various scanners, files, and ISIS pipes, this value produced maximum throughput without wasting memory.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

IG_ISIS_run_zone is the easiest way to invoke an ISIS pipe. It causes the head (first) driver to start generating data and sending chunks of data to the next driver in the pipe. Each chunk of data is the amount that will fit into lpBuffer. This, in turn, causes data for a single run (usually a page) to flow through the pipe and produce output. Each IG_ISIS_run_zone call processes exactly one zone (which may be at most a page, and at least a subarea of a page).

NOTE: A zone may be an entire page side, a subarea of the page, or one of multiple subareas that can be defined with certain scanner drivers (by using IG_ISIS_TAG_WINDOW). In typical scanning cases, a zone is a single page. Your application can rely on a zone returning a page, as this is the default behavior for all scanners. Speical programming is required to access any other type of behavior.

Call IG_ISIS_run_zone only after properly loading, linking, and setting parameters on an ISIS pipe.

Calling IG_ISIS_run_zone on a scanner driver causes the scanner to scan a page and output data into the ISIS pipe to which the scanner driver is linked.

After calling IG_ISIS_run_zone, check the return value. If the return value is not IGE_SUCCESS, then an error occurred (for example, a paper jam), and the page should be considered incomplete. If the return value is IGE_SUCCESS, then the page (zone) completed and no more data is available. Another IG_ISIS_run_zone must be called to process the another page (zone).

IG_ISIS_run_zone consists of, among other functions, the following three key functions:

  • IG_ISIS_drv_run_start
  • IG_ISIS_drv_run_step
  • IG_ISIS_drv_run_done

Omitted from these functions is IG_ISIS_drv_run_zone, which is used to pass tags to the head driver just before starting data transfer. This function is needed when the head driver is not a data generator but tags still need to be set. Therefore, there are several cases in which you may want to use the separate functions to invoke an ISIS pipe:

  • The data is coming from a source that is not a part of the ISIS pipe; that is, the head (first) driver in the ISIS pipe is not a data generator. In this case, the IG_ISIS_drv_run_zone function can be used to pass data into the head driver of the ISIS pipe, even though the data originated outside the pipe.
  • The data needs to be broken into small chunks in cases when you do not want to receive the entire page at once. The IG_ISIS_drv_run_step function can be used to specify the size of each "step" of data transfer.
  • The operation needs to yield periodically, for example to give other applications a chance to use CPU cycles and to determine whether or not a Cancel Scan command has been received. This can be important, especially when using very slow scanners, such as color scanners that may take minutes to scan a page. (It may be more convenient to use the yield functionality built into the driver and accessed by IG_ISIS_TAG_YIELDPROC, if you are fortunate enough to be working with one of the few scanner drivers that implement this tag. Otherwise, use a yield process in this scanning loop to implement yielding on all scanners.)

Example

The following example uses IG_ISIS_run_zone to implement a basic scanning loop. Compare this to the example of using the separate IG_ISIS_drv_run... functions on page 18-86.

#define BUFSIZE 8192
AT_ERRCOUNT ScanBatch(HISISDRV hDriver)
{
    LONG lValue;
    AT_ERRCOUNT nErrCount;
    char Buffer[BUFSIZE];
    nErrCount = IG_ISIS_drv_is_page_loaded(hDriver,
IG_ISIS_FEEDER_FEED, &lValue);
    if (nErrCount != IGE_SUCCESS)
        return nErrCount;
    while (lValue & IG_ISIS_DRV_STACKPAGE) {
        nErrCount = IG_ISIS_run_zone(hDriver, Buffer, BUFSIZE);
        if (nErrCount != IGE_SUCCESS)
            return nErrCount;
        nErrCount = IG_ISIS_drv_is_page_loaded(hDriver,
IG_ISIS_FEEDER_FEED, &lValue);
        if (nErrCount != IGE_SUCCESS)
            return nErrCount;
    }
return IGE_SUCCESS;
}

Background

An ISIS pipe exists to transfer image data from one entity (scanner, file, memory) to another. IG_ISIS_run_zone invokes several separate ISIS functions that can also be called independently by an application, if desired. Following is the actual code that is used to define IG_ISIS_run_zone:

if ((nErrCount = IG_ISIS_drv_start_stack(hDriver, &hStack)) ==
IGE_SUCCESS) {
    if ((nErrCount = IG_ISIS_drv_start_page(hStack, &hPage)) ==
IGE_SUCCESS) {
        if ((nErrCount = IG_ISIS_drv_start_zone(hPage, &hZone))
== IGE_SUCCESS) {
            if ((nErrCount = IG_ISIS_drv_forward(hZone, 0)) ==
IGE_SUCCESS)
                nErrCount = IG_ISIS_drv_start_data(hZone);
            if (nErrCount == IGE_SUCCESS) {
                do {
                    nErrCount = IG_ISIS_drv_put_data(hZone, buffer,
size, 0);
                } while (nErrCount == IGE_SUCCESS);
            }
            nErrCount = IG_ISIS_drv_end_zone(hZone);
        }
         nErrCount = IG_ISIS_drv_end_page(hPage);
}
nErrCount = IG_ISIS_drv_end_stack(hStack);
return nErrCount;


ISIS Single-Step Driver Control Functions

IG_ISIS_drv_end_page

Signal end of page.

Description

The IG_ISIS_drv_end_page function tells the driver that the application is done with the current page. Most scanner drivers ignore this message. A scanner that has a flatbed with a feeder mechanism might eject the page when this function is called.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_end_page(
    HISISDRV hPage
    );

Parameters

hPage
The storage location of the page handle which was previously locked by the IG_ISIS_drv_start_page function.

Usage

Upon receiving the ISIS message issued by IG_ISIS_drv_end_page , the default message handler frees the page handle, its tags, choice nodes, and user data. If the page has any child zones, each receives the ISIS message that would normally be issued by IG_ISIS_drv_end_zone. If the userdata points to any additional memory, the driver must free this memory. The driver also may need to do some additional work to prepare the scanner for subsequent operations. A scanner driver should make sure that it calls the default message handler so that the tags, choice nodes, and userdata get properly freed.

IG_ISIS_drv_end_page is one of several hierarchical data transfer functions that are called automatically by the IG_ISIS_drv_run_zone function. The hierarchy of data transfer functions is:

IG_ISIS_drv_start_stack
    IG_ISIS_drv_start_page
        IG_ISIS_drv_start_zone
            IG_ISIS_drv_forward
                IG_ISIS_drv_start_data
                    IG_ISIS_drv_put_data
        IG_ISIS_drv_end_zone
    IG_ISIS_drv_end_page
IG_ISIS_drv_end_stack

Example

The following example is the definition for the IG_ISIS_drv_run_zone function, showing the implementation of the start and end stack, zone, and page functions:

INT32 PUBLIC_FUNC IG_ISIS_run_zone(HISISDRV hDriver,
    char FAR *buffer, INT16 size)
{
    HISISDRV hStack, hPage, hZone;
    AT_ERRCOUNT nErrCount = IGE_SUCCESS;
    IG_ISIS_drv_start_stack(hDriver, &hStack);
    IG_ISIS_drv_start_page(hStack, &hPage);
    IG_ISIS_drv_start_zone(hPage, &hZone);
    IG_ISIS_drv_forward(hZone, 0);
    IG_ISIS_drv_start_data(hZone);
    do {
        nErrCount = IG_ISIS_drv_put_data(hZone, buffer, size, 0);
    } while (nErrCount == IGE_SUCCESS);
    IG_ISIS_drv_end_zone(hZone);
    IG_ISIS_drv_end_page(hPage);
    IG_ISIS_drv_end_stack(hStack);
    return nErrCount;
}

Background

Most applications can use IG_ISIS_drv_run_zone to automatically invoke the IG_ISIS_drv... functions required to acquire and process an image. IG_ISIS_drv_run_zone will call IG_ISIS_drv_start_stack|Page|Zone and IG_ISIS_drv_end_stack|Page|Zone as necessary to process documents, but will not allow a high degree of control over the individual stack, page, and zone levels. If your application needs more control over the individual levels of processing stacks, pages, and zones, then it can call the separate IG_ISIS_drv... functions as necessary. Most drivers ignore this function.

See Also

IG_ISIS_drv_end_stack, IG_ISIS_drv_end_zone, IG_ISIS_drv_start_page, IG_ISIS_drv_run_zone.


IG_ISIS_drv_end_stack

Signal end of stack.

Description

The IG_ISIS_drv_end_stack function tells the driver that the application is done with the current stack of pages. Most scanner drivers ignore this message.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_end_stack(
    HISISDRV hStack
    );

Parameters

hStack
The storage location of the stack handle which was previously locked by the IG_ISIS_drv_start_stack function.

Usage

Upon receiving the ISIS message issued by IG_ISIS_drv_end_stack , the default message handler frees the stack handle, its tags, choice nodes, and userdata. If the stack has any child pages, each receives the ISIS message that would normally be issued by the IG_ISIS_drv_end_page. If the userdata points to any additional memory, the driver must free this memory. The driver also may need to do some additional work to prepare the scanner for subsequent operations. A scanner driver should make sure that it calls the default message handler so that the tags, choice nodes, and userdata get properly freed.

IG_ISIS_drv_end_stack is one of several hierarchical data transfer functions that are called automatically by the IG_ISIS_drv_run_zone function. The hierarchy of data transfer functions is:

IG_ISIS_drv_start_stack
    IG_ISIS_drv_start_page
        IG_ISIS_drv_start_zone
            IG_ISIS_drv_forward
                IG_ISIS_drv_start_data
                    IG_ISIS_drv_put_data
        IG_ISIS_drv_end_zone
    IG_ISIS_drv_end_page
IG_ISIS_drv_end_stack

Example

See IG_ISIS_drv_end_page.

Background

Most applications can use IG_ISIS_drv_run_zone to automatically invoke the IG_ISIS_drv... functions required to acquire and process an image. IG_ISIS_drv_run_zone will call IG_ISIS_drv_start_stack|Page|Zone and IG_ISIS_drv_end_stack|Page|Zone as necessary to process documents, but will not allow a high degree of control over the individual stack, page, and zone levels. If your application needs more control over the individual levels of processing stacks, pages, and zones, then it can call the separate IG_ISIS_drv... functions as necessary. Most drivers ignore this function.

See Also

IG_ISIS_drv_end_page, IG_ISIS_drv_end_zone, IG_ISIS_drv_start_stack , IG_ISIS_drv_run_zone.


IG_ISIS_drv_end_zone

Signal end of zone.

Description

The IG_ISIS_drv_end_zone function tells the driver that the application is done with the current zone. The application may call this function before the scanner is done processing a zone. If it does so, the remaining zone data is discarded. Upon receiving the message issued by this function, a scanner may begin to reset itself and prepare for the next operation.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_end_zone(
    HISISDRV hZone
    );

Parameters

hZone
The storage location of the zone handle which was previously locked by the IG_ISIS_drv_start_zone function.

Usage

Upon receiving the ISIS message issued by IG_ISIS_drv_end_zone , the default message handler frees the zone handle, its tags, choice nodes, and userdata. If the userdata points to any additional memory, the driver must free this memory. The driver also may need to do some additional work to reset the scanner if it has not yet finished scanning. A scanner driver should make sure that it calls the default message handler so that the tags, choice nodes, and userdata get properly freed.

IG_ISIS_drv_end_zone is one of several hierarchical data transfer functions that are called automatically by the IG_ISIS_drv_run_zone function. The hierarchy of data transfer functions is:

IG_ISIS_drv_start_stack
    IG_ISIS_drv_start_page
        IG_ISIS_drv_start_zone
            IG_ISIS_drv_forward
                IG_ISIS_drv_start_data
                    IG_ISIS_drv_put_data
        IG_ISIS_drv_end_zone
    IG_ISIS_drv_end_page
IG_ISIS_drv_end_stack

Applications should call IG_ISIS_drv_end_zone after receiving an End Zone condition from a IG_ISIS_drv_put_data call.

Example

See IG_ISIS_drv_end_page.

Background

Most applications can use IG_ISIS_drv_run_zone to automatically invoke the IG_ISIS_drv... functions required to acquire and process an image. IG_ISIS_drv_run_zone will call IG_ISIS_drv_start_stack|Page|Zone and IG_ISIS_drv_end_stack|Page|Zone as necessary to process documents, but will not allow a high degree of control over the individual stack, page, and zone levels. If your application needs more control over the individual levels of processing stacks, pages, and zones, then it can call the separate IG_ISIS_drv... functions as necessary.

See Also

IG_ISIS_drv_end_page, IG_ISIS_drv_end_stack, IG_ISIS_drv_start_page , IG_ISIS_drv_run_zone.


IG_ISIS_drv_put_data

Transfer data bytes.

Description

The IG_ISIS_drv_put_data function transfers data into or out of a driver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_put_data(
    HISISDRV hDriver,
    LPBYTE   lpBuffer,
    WORD     wCount,
    AT_MODE  nFlags
    );

Parameters

hDriver
The handle of the driver from which data is being transferred.
lpBuffer
A pointer to the buffer that will hold the data to be transferred during the operation.
wCount
The number of bytes to transfer each time the IG_ISIS_drv_put_data function is called. wCount must be at least 1 and no more than 32767.
nFlags
A flag that specifies whether or not to wait until the number of bytes specified in wCount is available before transferring the data. The values of nFlags are as follows:
wWait Meaning
IG_ISIS_DRV_DATAWAIT or 0 Wait until nFlags bytes are available or IG_ISIS_ERR_ENDZONE occurs before transferring any data.
IG_ISIS_DRV_DATANOWAIT Return as many bytes as are immediately available or nFlags bytes, whichever is less.
NOTE: With many scanner drivers, IG_ISIS_drv_put_data waits for wCount bytes even when wWait is set to IG_ISIS_DRV_DATANOWAIT.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

The IG_ISIS_drv_put_data function is very similar in operation to the IG_ISIS_drv_run_step function. The primary difference is that IG_ISIS_drv_run_step operates on a handle to a run that has been established by a IG_ISIS_drv_run_start function while IG_ISIS_drv_put_data operates directly on a handle to a driver. Internally, a driver uses IG_ISIS_drv_put_data to transfer data to the next driver in an ISIS pipe. As an application developer, the following are cases when you may want to consider using IG_ISIS_drv_put_data:

  • To put data into an ISIS pipe when the head (first) driver of the pipe is not a data generator.
  • To get the data from a single driver. Because IG_ISIS_drv_put_data has a handle only to the first driver in an ISIS pipe, when using only one driver you can get the data from the driver by using IG_ISIS_drv_put_data.

IG_ISIS_drv_put_data must be called repeatedly until it returns a value of MAKELONG(0,IG_ISIS_ERR_ENDZONE) indicating that the run is complete. The wCount parameter of IG_ISIS_drv_put_data can be set to any value that fits in with your application's memory environment; an 8K byte buffer generally gives optimum performance.

NOTE: You must check the return value of the IG_ISIS_drv_put_data and wait for IG_ISIS_ERR_ENDZONE before assuming data transfer is complete. Some three-pass color scanners take minutes to reset after each pass. Furthermore, when each pass completes, depending on the driver and the status of the wWait flag, you may get the remainder of the bytes from the current pass, or you may not get the remainder of the bytes until the scanner has completed enough of the next pass to give you wCount bytes (in which case part of the data in lpcBuffer will be one color and part will be another color).

IG_ISIS_drv_put_data is one of several hierarchical data transfer functions that are called automatically by the IG_ISIS_drv_run_zone function. The hierarchy of data transfer functions is:

IG_ISIS_drv_start_stack
    IG_ISIS_drv_start_page
        IG_ISIS_drv_start_zone
            IG_ISIS_drv_forward
                IG_ISIS_drv_start_data
                    IG_ISIS_drv_put_data
        IG_ISIS_drv_end_zone
    IG_ISIS_drv_end_page
IG_ISIS_drv_end_stack

IG_ISIS_drv_start_data must be called before calling IG_ISIS_drv_put_data.

It is possible (although not recommended) to use IG_ISIS_drv_put_data to put data from a scanner into memory without using a minidriver. This will work only when the scanner outputs data in the format that you want, and no other drivers are used to modify the data. If the scanner outputs uncompressed data and you need G4 data, you cannot use this method.

See Also

IG_ISIS_drv_run_step, IG_ISIS_drv_start_data.


IG_ISIS_drv_run_done

Complete and close an ISIS pipe transfer operation.

Description

IG_ISIS_drv_run_done completes a data transfer operation and invalidates the run handle that was initialized by the related IG_ISIS_drv_run_start function.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_run_done(
    HISISDRVRUN hRun
    );

Parameters

hRun
The handle of the "run" (zone data structure) being processed. This handle is initialized by the IG_ISIS_drv_run_start function that invoked the pipe.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Call IG_ISIS_drv_run_done after looping on IG_ISIS_drv_run_step until all data is transferred (as indicated by IG_ISIS_drv_run_step returning IG_ISIS_ERR_ENDZONE). Or, call IG_ISIS_drv_run_done prior to IG_ISIS_ERR_ENDZONE to cancel the run.

Example

See IG_ISIS_drv_run_start examples on page 18-86.

Background

IG_ISIS_drv_run_done is one of the basic components of IG_ISIS_drv_run_zone. It is the last of four functions that when used together invoke an ISIS pipe. Invoking a pipe starts a scanning, reading, writing, compression, or other operation as defined by the drivers linked in the pipe.

See Also

IG_ISIS_drv_run_start, IG_ISIS_drv_run_step, IG_ISIS_drv_run_zone, IG_ISIS_drv_run_zone.


IG_ISIS_drv_run_start

Begin to invoke an ISIS pipe; initialize the run handle.

Description

IG_ISIS_drv_run_start initializes the run.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_run_start(
    HISISDRV      hDriver,
    LPHISISDRVRUN lphRun
    );

Parameters

hDriver
The handle of the head (first) driver in the ISIS pipe.
lphRun
A pointer to the handle of the "run" (zone data structure) which is used to refer to the run zone operation. IG_ISIS_drv_run_start initializes this pointer.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

IG_ISIS_drv_run_start is the first step in transferring data through an ISIS pipe. The head (first) driver in the pipe responds by performing whatever its function may be (scanning, reading, writing, compression) and then passes its data to the next driver in the pipe. IG_ISIS_drv_run_start is the first of four separate functions that are used to scan a page. The other functions are IG_ISIS_drv_run_zone (which returns a pointer to the zone structure to allow setting output parameters if necessary), IG_ISIS_drv_run_step (which transfers a specified number of bytes from the page), and IG_ISIS_drv_run_done (which completes the IG_ISIS_drv_run... operation). For common ISIS operations not requiring special or concurrent processing, it is much more convenient and automatic to use the IG_ISIS_drv_run_zone function.

There are several cases in which you may want to use the four separate functions to invoke an ISIS pipe:

  • The data is coming from a source that is not a part of the ISIS pipe; that is, the head (first) driver in the ISIS pipe is not a data generator. In this case, the IG_ISIS_drv_run_zone function can be used to send data into the head driver of the ISIS pipe, even though the data originated outside the pipe.
  • The data needs to be broken into small chunks in cases when you do not want to receive the entire page at once. The IG_ISIS_drv_run_step function can be used to specify the size of each "step" of data transfer. (However, this can also be done with the IG_ISIS_drv_run_zone function.)
  • The operation needs to yield periodically, for example to give other applications a chance to use CPU cycles and to determine whether or not a Cancel Scan command has been received. This can be important, especially when using very slow scanners, such as color scanners that may take minutes to scan a page. It is possible for a scan to complete without calling the yield process once. IG_ISIS_drv_run_step guarantees that control is given to the application periodically. This turnover of control is suitable for status reporting, displaying a progress monitor, an so forth.

Example

The following example uses IG_ISIS_drv_run_start, IG_ISIS_drv_run_step, and IG_ISIS_drv_run_done in three nested loops to invoke an ISIS pipe that allows background reading or scanning:

/* IG_ISIS_drv_run_start example */
INT32 MyIG_ISIS_run_zone(HISISDRV hDriver, char FAR *lpcBuffer,
int iSize)
{
    HISISDRVRUN hRun;
    AT_ERRCOUNT nErrCount;
    if (!(nErrCount = IG_ISIS_drv_run_start(hDriver, &hRun))) {
        while (nErrCount == IGE_SUCCESS) {
            if (want to cancel the scan)
                break;
            else
                nErrCount = IG_ISIS_drv_run_step(hRun, lpcBuffer, iSize,
0);
            printf("Read %d bytes at address %08lx\n",
                    nErrCount, lpcBuffer);
        }
    }
    nErrCount = IG_ISIS_drv_run_done(hRun);
    return nErrCount;
}

Background

An ISIS pipe exists to transfer image data from one entity (scanner, file, memory) to another. IG_ISIS_drv_run_start begins a data transfer operation of a single zone (image area) through the pipe by setting up a "run" data structure and initializing a handle to it. The run handle is used to refer to a particular zone's data and all of its parameters from the time it enters the first driver of the ISIS pipe until it reaches the destination driver of the pipe. Once a run is complete and a single zone has been transferred, the entire process must be repeated to transfer another image.

The IG_ISIS_drv_run_start function is the first of four functions that when used together invoke an ISIS pipe that has previously been established. Invoking a pipe starts a scanning, reading, writing, compression, or other operation as defined by the drivers linked in the pipe.

NOTE: A zone may be an entire page side, a subarea of the page, or one of multiple subareas that can be defined with certain scanner drivers. Typically, it is an entire page.

IG_ISIS_drv_run_start is one of the basic components of IG_ISIS_drv_run_zone.

See Also

IG_ISIS_drv_run_done, IG_ISIS_drv_run_step, IG_ISIS_drv_run_zone.


IG_ISIS_drv_run_step

Transfer another buffer of data through an ISIS pipe.

Description

IG_ISIS_drv_run_step transfers a specified number of bytes or all available bytes through the ISIS pipe.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_run_step(
    HISISDRVRUN hRun,
    LPBYTE      lpBuffer,
    WORD        wCount,
    AT_MODE     nFlags
    );

Parameters

hRun
The handle of the "run" (zone data structure) being processed. This handle is initialized by the IG_ISIS_drv_run_start function that invoked the pipe.
lpBuffer
A pointer to the buffer that will hold the data to be transferred during the operation.
wCount
The number of bytes to transfer during each IG_ISIS_drv_run_step.
nFlags
A flag that specifies whether or not to wait until the number of bytes specified in wCount is available before transferring the data. The values of nFlags are as follows:
nFlags Meaning
IG_ISIS_DRV_DATAWAIT or 0 Wait until wCount bytes are available or IG_ISIS_ERR_ENDZONE occurs before transferring any data.
IG_ISIS_DRV_DATANOWAIT Return as many bytes as are immediately available or wCount bytes, whichever is less.
NOTE: With many scanner drivers, IG_ISIS_drv_put_data waits for wCount bytes even when nFlags is set to IG_ISIS_DRV_DATANOWAIT.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

IG_ISIS_drv_run_step should only be called after calling IG_ISIS_drv_run_start. Also, if any parameters need to be set prior to invoking the ISIS pipe, IG_ISIS_drv_run_zone must be called after IG_ISIS_drv_run_start and before IG_ISIS_drv_run_step. Then, IG_ISIS_drv_run_step is called repeatedly until it returns a value of IG_ISIS_ERR_ENDZONE indicating that the run is complete. After all data is transferred, IG_ISIS_drv_run_done must be called to complete the run.

The iCount parameter of IG_ISIS_drv_run_step can be set as follows:

  1. If you are putting data into an ISIS pipe, the maximum buffer size is (32K-1 bytes).
  2. If you are only processing an ISIS pipe, but not putting data into it, you can use any value that fits in with your application's memory environment; an 8K byte buffer is the correct size to use.
  3. If you are reading data out of the first driver in an ISIS pipe, the maximum buffer size is (32K-1) bytes.
NOTE: You must check the return value of the IG_ISIS_drv_put_data and wait for IG_ISIS_ERR_ENDZONE before assuming data transfer is complete. Some three-pass color scanners take minutes to reset after each pass. Furthermore, when each pass completes, depending on the driver and the status of the wWait flag, you may get the remainder of the bytes from the current pass, or you may not get the remainder of the bytes until the scanner has completed enough of the next pass to give you wCount bytes (in which case part of the data in lpcBuffer will be one color and part will be another color).

IG_ISIS_drv_run_done can be called before IG_ISIS_drv_run_step has returned IG_ISIS_ERR_ENDZONE to stop zone processing. This is useful in implementing, for example, a "Cancel Scan" button.

Example

See IG_ISIS_drv_run_start examples.

Background

IG_ISIS_drv_run_step is one of the basic components of IG_ISIS_drv_run_zone. It is one of four functions that when used together invoke an ISIS pipe. Invoking a pipe starts a scanning, reading, writing, compression, or other operation as defined by the drivers linked in the pipe.

See Also

IG_ISIS_drv_run_done, IG_ISIS_drv_run_start, IG_ISIS_drv_run_zone.


IG_ISIS_drv_run_zone

Return a pointer to the current run's handle.

Description

IG_ISIS_drv_run_zone (not to be confused with the IG_ISIS_run_zone function) returns a pointer to the current run handle that was initialized by IG_ISIS_drv_run_start. This allows you to use IG_ISIS_tag_set... functions to set output parameters when the ISIS pipe's head (first) driver is not a data generator.

For example, when the head driver is a compression driver and you need to set image width, you would use the IG_ISIS_drv_run_zone function to get the run handle.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_run_zone(
    HISISDRVRUN hRun
    );

Parameters

hRun
The handle of the "run" (zone data structure) being processed. This handle is initialized by the IG_ISIS_drv_run_start function that invoked the pipe.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Call IG_ISIS_drv_run_zone after calling IG_ISIS_drv_run_start and before calling IG_ISIS_drv_run_step. IG_ISIS_drv_run_zone gives you the run handle which you can then pass as a parameter in one or more IG_ISIS_tag_set... functions to set as many parameters as needed. After setting all necessary parameters, loop on IG_ISIS_drv_run_step until all data is transferred (as indicated by IG_ISIS_drv_run_step returning IG_ISIS_ERR_ENDZONE).

Example

See IG_ISIS_drv_run_start examples on page 18-86.

Background

The IG_ISIS_drv_run_zone function is one of four functions that when used together invoke an ISIS pipe. Invoking a pipe starts a scanning, reading, writing, compression, or other operation as defined by the drivers linked in the pipe. IG_ISIS_drv_run_zone returns a pointer to the current run zone handle that was initialized by the related IG_ISIS_drv_run_start function.

See Also

IG_ISIS_drv_run_done, IG_ISIS_drv_run_start, IG_ISIS_drv_run_step, IG_ISIS_drv_run_zone.


IG_ISIS_drv_start_data

Start transferring zone data.

Description

The IG_ISIS_drv_start_data function tells a driver to start transferring zone data.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_start_data(
    HISISDRV hZone
    );

Parameters

hZone
The handle of the zone for which data is to be transferred.

Usage

IG_ISIS_drv_start_data is one of several hierarchical data transfer functions that are called automatically by the IG_ISIS_drv_run_zone function. IG_ISIS_drv_start_data must be called before IG_ISIS_drv_put_data. The IG_ISIS_drv_start_data function sends current tag values to all drivers in the ISIS pipe at the very last minute before actually invoking the pipe, so that each driver is certain to have the most recent tag values.

The hierarchy of data transfer functions is:

IG_ISIS_drv_start_stack
    IG_ISIS_drv_start_page
        IG_ISIS_drv_start_zone
            IG_ISIS_drv_forward
                IG_ISIS_drv_start_data
                    IG_ISIS_drv_put_data
        IG_ISIS_drv_end_zone
    IG_ISIS_drv_end_page
IG_ISIS_drv_end_stack

Example

The following example shows how the IG_ISIS_drv_run_zone function is implemented. The relationships of the functions would be the same in most any scanning application.

INT32 PUBLIC_FUNC IG_ISIS_run_zone(HISISDRV hDriver,
                              char FAR *buffer, INT16 size)
{
    HISISDRV hStack, hPage, hZone;
    AT_ERRCOUNT nErrCount;
    if ((nErrCount = IG_ISIS_drv_start_stack(hDriver, &hStack))
== IGE_SUCCESS) {
        if ((nErrCount = IG_ISIS_drv_start_page(hStack, &hPage))
== IGE_SUCCESS) {
            if ((nErrCount = IG_ISIS_drv_start_zone(hPage,
&hZone)) == IGE_SUCCESS) {
                if ((nErrCount = IG_ISIS_drv_forward(hZone, 0)) ==
IGE_SUCCESS)
                    nErrCount = IG_ISIS_drv_start_data(hZone);
                if (nErrCount == IGE_SUCCESS) {
                    do {
                        nErrCount =
IG_ISIS_drv_put_data(hZone,buffer,size,0);
                    } while (nErrCount == IGE_SUCCESS);
                }
                nErrCount = IG_ISIS_drv_end_zone(hZone);
            }
            nErrCount = IG_ISIS_drv_end_page(hPage);
        }
        nErrCount = IG_ISIS_drv_end_stack(hStack);
    }
    return nErrCount;
}


IG_ISIS_drv_start_page

Start a new page.

Description

The IG_ISIS_drv_start_page function tells a driver to start a new page and returns a page handle.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_start_page(
    HISISDRV   hStack,
    LPHISISDRV lphPage
    );

Parameters

hStack
The handle of the stack in which this page is being created.
lphPage
A pointer to the handle of the page created and returned by the IG_ISIS_drv_start_page function.

Usage

IG_ISIS_drv_start_page is one of several hierarchical data transfer functions that are called automatically by the IG_ISIS_run_zone function. The hierarchy of data transfer functions is:

IG_ISIS_drv_start_stack
    IG_ISIS_drv_start_page
        IG_ISIS_drv_start_zone
            IG_ISIS_drv_forward
                IG_ISIS_drv_start_data
                    IG_ISIS_drv_put_data
        IG_ISIS_drv_end_zone
    IG_ISIS_drv_end_page
IG_ISIS_drv_end_stack

Example

See IG_ISIS_drv_start_data example.


IG_ISIS_drv_start_stack

Start a new stack.

Description

The IG_ISIS_drv_start_stack function tells a driver to start a new stack and returns a stack handle.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_start_stack(
    HISISDRV   hDriver,
    LPHISISDRV lphStack
    );

Parameters

hDriver
The handle of the driver in which this stack is being created.
lphStack
A pointer to the handle of the stack created and returned by the IG_ISIS_drv_start_stack function.

Usage

IG_ISIS_drv_start_stack is the top of several hierarchical data transfer functions that are called automatically by the IG_ISIS_drv_run_zone function. The hierarchy of data transfer functions is:

IG_ISIS_drv_start_stack
    IG_ISIS_drv_start_page
        IG_ISIS_drv_start_zone
            IG_ISIS_drv_forward
                IG_ISIS_drv_start_data
                    IG_ISIS_drv_put_data
        IG_ISIS_drv_end_zone
    IG_ISIS_drv_end_page
IG_ISIS_drv_end_stack

A number of scanners do not support the concept of multiple stacks, and so ignore the message sent by this function.

Example

See IG_ISIS_drv_start_data example.


IG_ISIS_drv_start_zone

Start a new zone.

Description

The IG_ISIS_drv_start_zone function tells a driver to start a new zone and returns a zone handle.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_start_zone(
    HISISDRV   hPage,
    LPHISISDRV lphZone
    );

Parameters

hPage
The handle of the page in which this zone is being created.
lphZone
A pointer to the handle of the zone created and returned by the IG_ISIS_drv_start_zone function.

Usage

IG_ISIS_drv_start_zone is one of several hierarchical data transfer functions that are called automatically by the IG_ISIS_drv_run_zone function. The hierarchy of data transfer functions is:

IG_ISIS_drv_start_stack
    IG_ISIS_drv_start_page
        IG_ISIS_drv_start_zone
            IG_ISIS_drv_forward
                IG_ISIS_drv_start_data
                    IG_ISIS_drv_put_data
        IG_ISIS_drv_end_zone
    IG_ISIS_drv_end_page
IG_ISIS_drv_end_stack

Most scanners do not support the concept of multiple zones, and so ignore this message.

Example

See IG_ISIS_drv_start_data example.


ISIS Driver Communication and Setup Functions

IG_ISIS_area_dialog_CB_register

Set a callback function to display a preview image in the scan area dialog.

Description

IG_ISIS_area_dialog_CB_register designates a callback function to be used when displaying an image in the preview box of the scan area dialog.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_area_dialog_CB_register(
    HINSTANCE        hInst,
    LPFNIG_ISIS_AREA lpfnCB,
    DWORD            lParam
    );

Parameters

hInst
Specifies the handle to the application instance.
lpfnCB
Pointer to area dialog callback function.
lParam
32-bit value which will be passed as the lParam parameter to your callback function.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

When displaying an area dialog using the IG_ISIS_DRV_SET_DIALOG_AREAPREVIEW flag, you have the option of showing a page preview in the preview box. IG_ISIS_area_dialog_CB_register provides the toolkit with the function that will actually draw the preview.

Call IG_ISIS_area_dialog_CB_register before each call to IG_ISIS_drv_area_dialog or IG_ISIS_drv_set_dialog in order to provide your own callback function to draw the preview.

Callback Syntax

typedef LONG (LPACCUAPI LPFNIG_ISIS_AREA)(
    LONG  lCommand,
    DWORD lData,
    DWORD lParam
    );

Callback Parameters

lCommand
Low word is the command to be executed by the callback function. High word is a sub-command specific to the command.
lData
32-bit data associated with the command.
lParam
32-bit user data that was passed as the lParam parameter to IG_ISIS_area_dialog_CB_register.

The possible values for lCommand are:

lCommand
Meaning
IG_ISIS_AREA_INIT
Sub-command: unused 0)
Called when the preview window is created. lData is unused.
Return IGE_SUCCESS if successful. Any other return value will show the preview rectangle without any preview image and no further messages will be sent to the callback.
IG_ISIS_AREA_DONE
Sub-command: unused (0)
Called when the preview window is destroyed. lData is unused.
IG_ISIS_AREA_PAINT
Sub-command: unused (0)
The callback should scale and paint its image into the supplied destRect using the supplied clipping rectangle (clipRect) and device context (hDC). lData is a FAR pointer to a AT_ISIS_AREAPAINTINFO structure which holds these three values.
The callback should return IGE_SUCCESS if successful.
IG_ISIS_AREA_GET
Sub-command: TAG number
Called during dialog initialization to request values from the callback describing the image that will be painted.
lData is a FAR pointer which should be cast to point to the data type of the equivalent tag (AT_ISIS_RAT must be converted to IG_ISIS_TAG_TYPE_RATIONAL). If the callback doesn't provide a particular tag, it must not modify the contents of *lData.
IG_ISIS_TAG_XRESOLUTION
IG_ISIS_TAG_YRESOLUTION
The callback must provide resolution information so that the area dialog can determine how to scale the drawing rectangle. (Type: IG_ISIS_TAG_TYPE_RATIONAL)
IG_ISIS_TAG_IMAGEWIDTH
IG_ISIS_TAG_IMAGELENGTH
The callback must provide the unscaled image size (in pixels). (Type: IG_ISIS_TAG_TYPE_LONG)
IG_ISIS_TAG_XPOSITION
IG_ISIS_TAG_YPOSITION
The callback can optionally provide the unscaled X/Y positions (in pixels) used when the preview image was originally scanned. (Type: IG_ISIS_TAG_TYPE_LONG)
If the position tags are not provided by the callback, the drawing rectangle will be at the top of the page, centered for centerfeed scanners and left aligned for other scanners.

Example

The following example shows IG_ISIS_area_dialog_CB_register being used before each call to IG_ISIS_drv_set_dialog. The application's callback function "MyAreaCallback" will be used by the toolkit if the user clicks on the "Area..." button.

LPFNIG_ISIS_AREA lpfnAreaCB;
lpfnAreaCB = (LPFNIG_ISIS_AREA)MakeProcInstance(
(FARPROC)MyAreaCallback, hInst);
IG_ISIS_area_dialog_CB_register(hInst, lpfnAreaCB, 	(DWORD)(void
FAR *)mPage);
IG_ISIS_drv_set_dialog(hScan, hWnd,
IG_ISIS_DRV_SET_DIALOG_AREAPREVIEW);
if (lpfnAreaCB)
        FreeProcInstance((FARPROC)lpfnAreaCB);

Background

The IG_ISIS_DRV_SET_DIALOG_AREAPREVIEW flag does not imply that a callback will be used. If this flag is used when displaying an area dialog without first providing a callback function the toolkit will display a gray preview box without drawing an image in it.

The toolkit uses the tags provided by the callback to properly scale the drawing rectangle so that the preview image fits into the correct portion of the preview box independent of the current scanner resolution and page size.

Structures

The AT_ISIS_AREAPAINTINFO structure pointed to by lData in the callback function when lCommand is set to IG_ISIS_AREA_PAINT is declared as follows:

typedef struct tagAT_ISIS_AREAPAINTINFO
{
    int size;  // size of structure
    HDC  hDC;
    RECT destRect;
    RECT clipRect;
} AT_ISIS_AREAPAINTINFO, FAR * LPAT_ISIS_AREAPAINTINFO;

See Also

IG_ISIS_drv_area_dialog, IG_ISIS_drv_set_dialog.


IG_ISIS_drv_about_box

Display driver copyright and version dialog box.

Description

The IG_ISIS_drv_about_box function displays a dialog box with copyright and version information for a driver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_about_box(
    HISISDRV hDriver,
    HWND     hWnd
    );

Parameters

hDriver
The driver from which copyright and version information is to be displayed.
hWnd
A handle to a parent window.

Usage

hWnd must be a handle to a parent window.


IG_ISIS_drv_area_dialog

Display set scanning area dialog box.

Description

The IG_ISIS_drv_area_dialog function displays a predefined dialog box that allows the user to set scanning area. This is the same dialog that appears when the user clicks the Area button in the Scanner Settings dialog box.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_area_dialog(
HISISDRV hDriver,
HWND hWnd,
HINSTANCE hInst,
DWORD dwFlags
);

Parameters

hDriver
The handle of the driver for which this dialog box is being displayed.
hWnd
A handle to the parent window.
hInst
A handle to the application instance.
dwFlags
The currently available bits for dwFlags are as follows:
dwFlags Meaning
IG_ISIS_DRV_SET_DIALOG_AREAPREVIEW When this bit is set, the Area dialog box displayed will include a preview box where the user can set the scan area through mouse actions. The preview box may display an image if a callback function has been set with IG_ISIS_area_dialog_CB_register, otherwise it will be gray.

Usage

Use this function to display the Area dialog box, allowing the user to set the area to scan. Changing the settings in the Area dialog box modifies the values of IG_ISIS_TAG_IMAGEWIDTH, IG_ISIS_TAG_IMAGELENGTH, IG_ISIS_TAG_XPOSITION, and IG_ISIS_TAG_YPOSITION when the user click the OK button.

Note that the Units setting of this dialog is saved in SETSCAN.INI.

NOTE: Changing the settings in the Area dialog box does not automatically send the new tag values to the driver. If you are using a Kodak IL500 or IL9xx scanner (special cases), you must issue a IG_ISIS_drv_send_params to send the new scanning area to the scanner. If you are using any other ISIS scanner, simply initiating a scan sends the new scanning area automatically.

See Also

IG_ISIS_drv_set_dialog, IG_ISIS_area_dialog_CB_register.


IG_ISIS_drv_configure

Display driver configuration dialog box.

Description

The IG_ISIS_drv_configure function displays a dialog box showing configuration information for a scanner and allowing the configuration information to be changed by the user.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_configure(
    HISISDRV hDriver,
    HWND     hWnd
    );

Parameters

hDriver
The driver from which to display configuration dialog box.
hWnd
A handle to a parent window.

Usage

hWnd must be a handle to a parent window.

A scanner may display zero or more configuration lists, such as default paper size, default SCSI address, default I/O address, etc. The toolkit includes a predefined configuration dialog box that can accommodate up to four configuration lists.

The built-in configuration dialog works automatically based on the configuration choices in the scanner driver. To implement a custom dialog box, it is necessary to do the following steps:

  1. Determine how many configuration lists exist in the driver:
        IG_ISIS_choice_get_count(hDriver,
IG_ISIS_TAG_CONFIGURATIONS, lpwCount);
  1. Get the names of the configuration lists by incrementing wIndex by 1 from 0 through lpwCount-1:
        IG_ISIS_choice_get_ascii(hDriver,
IG_ISIS_TAG_CONFIGURATIONS, wIndex, lpszValue);
  1. Get the number of items in the first list:
        IG_ISIS_choice_get_count(hDriver, IG_ISIS_TAG_CONFIG_1,
lpwCountI);
  1. Get the name of each item in the first list by incrementing wIndex by 1 from 0 through lpwCount-1:
        IG_ISIS_choice_get_ascii(hDriver, IG_ISIS_TAG_CONFIG_1,
wIndex, lpszValue);
  1. Repeat steps 3 and 4 for each configuration list (IG_ISIS_TAG_CONFIG_2, IG_ISIS_TAG_CONFIG_3,... IG_ISIS_TAG_CONFIG_n.

The built-in scanner configuration dialog box looks similar to this:

The IG_ISIS_drv_configure function works by loading (but not starting) the driver, polling the scanner, and letting the user select information in the dialog box (if the scanner allows this type of configuration). It then saves this information as ASCII text in a scanner-specific section of the SETSCAN.INI file. Prior to performing scanner configuration, the first entry of the scanner-specific section in this file is "Setup=No." When scanner configuration is complete, this entry changes to "Setup=Yes."

A side effect of loading the driver is that permissions are checked at this time. If the user does not have sufficient permissions to use the driver, an appropriate error message will appear and the driver will not be added to the SYSTEM.INI file.

When the user click OK, the dialog box closes and the scanner driver is unloaded.

Note that, under Windows, this dialog box also can be displayed by clicking Setup in the Scanner Selection dialog box.

NOTE: Some scanners have no configuration parameters, or their configuration is set using an operating system level driver. In these cases, invoking the IG_ISIS_drv_configure function displays an appropriate message.

Example

The following example shows how to use IG_ISIS_drv_configure to display the predefined scanner configuration dialog:

/* Load and configure the Fujitsu SCSI scanner driver */
IG_ISIS_drv_load(0, &hDriver, "FUJIGINE", 0);
IG_ISIS_drv_configure(hDriver, hWnd);

See Also

IG_ISIS_drv_get_scan_name, IG_ISIS_drv_load, IG_ISIS_drv_set_scan_name.


IG_ISIS_drv_forward

Forward the tag values to all linked drivers.

Description

The IG_ISIS_drv_forward function forwards the tag values from one driver to all linked drivers.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_forward(
    HISISDRV hSource,
    HISISDRV hDestination
    );

Parameters

hSource
The handle to the driver from which the tag values are being forwarded. Generally, this will be the current driver.
hDestination
Always defined as zero.

Usage

The IG_ISIS_drv_forward function normally is not called directly by an application program. It is called automatically by IG_ISIS_drv_run_step and IG_ISIS_drv_run_zone, so most developers can disregard this information.

The IG_ISIS_drv_forward function takes only one value (lpSource) and uses the value 0 instead of lpDestination. This causes the tag values from lpSource to be forwarded to all drivers linked by IG_ISIS_drv_link. If tag values must be forwarded only to a specific destination driver, then you must use the IG_ISIS_drv_send function to send IG_ISIS_drv_forward's message.

Background

IG_ISIS_drv_forward works by making IG_ISIS_tag_set... calls on the destination driver(s) for each tag in the source driver.

See Also

IG_ISIS_drv_run_step, IG_ISIS_drv_send, IG_ISIS_drv_run_zone


IG_ISIS_drv_get_model_name

Retrieve the current scanner model name.

Description

The IG_ISIS_drv_get_model_name function retrieves the current scanner model name.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_get_model_name(
    LPSTR lpszModelName
    );

Parameters

lpszModelName
A pointer to the buffer that will contain the current scanner model name after executing IG_ISIS_drv_get_model_name. The buffer must be at least IG_ISIS_DRVMAXMODELNAME characters long.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

IG_ISIS_drv_get_model_name retrieves and fills in the currently selected scanner model by reading the "Model =" entry from the section for the current driver in the SETSCAN.INI file.

See Also

IG_ISIS_drv_get_scan_name.


IG_ISIS_drv_get_scan_description

Retrieve supported scanner names from a scanner driver.

Description

IG_ISIS_drv_get_scan_description gets the names of scanner devices supported by a scanner driver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_get_scan_description(
    LPAT_ISIS_FILEFIND lpFindInfo,
    INT                nScanner,
    LPSTR              lpszDescription
    );

Parameters

lpFindInfo
The file description structure returned by a FileFindFirst or FileFindNext call.
nScanner
Specifies an index into the list of scanner names.
lpszDescription
String to be filled in with the name of the scanner at index nScanner.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use FileFindFirst and FileFindNext to find the list of scanner drivers for which you wish to retrieve names. You may then use IG_ISIS_drv_get_scan_description to get the name strings for all the supported devices from a particular scanner driver. This information can be used to build your own scanner selection dialog.

Since ISIS drivers are installed in the WINDOWS\PIXTRAN directory, you should use the FileFind functions to locate all the driver files in that directory. ISIS drivers end with a .PXW extension in Windows 3.x and Windows 95. The driver extension is .PXN in Windows NT. However, since this directory contains ISIS compression and file drivers as well as scanner drivers, you will encounter many errors when calling IG_ISIS_drv_get_scan_description. This is to be expected and should not alarm you. Simply skip over non-scanner ISIS drivers when you find them.

When retrieving scanner names from a particular driver, start with iScanner at 0 and increment the index for each subsequent call to IG_ISIS_drv_get_scan_description until you get an error. This siginifies that you have read in all the supported scanner names for that driver.

Background

This function is provided for those who wish to create their own scanner selection dialog instead of using the built-in scanner selection dialog accessible through IG_ISIS_drv_set_scan_name. If you wish your scanner selection dialog to be compatible with the IG_ISIS_drv_set_scan_name and IG_ISIS_drv_get_scan_name functions, you should do the following:

  1. Set the newly selected driver name in the scanning configuration file SETSCAN.INI with the function call:
IG_ISIS_env_put(0, "Scanner", "Driver", szDriverName);
  1. If the driver contains multiple scanner description strings, also set the newly selected scanner name in SETSCAN.INI within the section for that driver using the function call:
IG_ISIS_env_put (0, szDriverName, "Model", szScannerModelName);

where szDriverName is the name of the driver without the extension, and szScannerModelName is the name of the scanner actually selected.

  1. Use the IG_ISIS_env_get function to retrive the driver name when you need it:
IG_ISIS_env_get (0, "Scanner", "Driver", szDriverName,
sizeof(szDriverName));

See Also

IG_ISIS_drv_get_scan_name, IG_ISIS_drv_set_scan_name, IG_ISIS_env_get, IG_ISIS_env_put.


IG_ISIS_drv_get_scan_name

Retrieve the current scanner driver name.

Description

The IG_ISIS_drv_set_scan_name function retrieves the current driver name.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_set_scan_name(
    HWND  hWnd,
    LPSTR lpszDriverName
    );

Parameters

hWnd
The window handle for the parent window or the value zero (0).
lpszDriverName
A pointer to the buffer that will contain the current driver name (filename root only, e.g. "FUJIGINE") after executing IG_ISIS_drv_set_scan_name.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

IG_ISIS_drv_set_scan_name retrieves and fills in the currently selected scanner driver by reading the "Driver =" entry of the [Scanner] section in the SETSCAN.INI file. If no name is set and hWnd is not zero (0), then the toolkit attempts to get a scanner by calling IG_ISIS_drv_set_scan_name and displaying the Select Scanner dialog box.

Developers need to unload scanner drivers before calling IG_ISIS_drv_set_scan_name. A new scanner driver cannot be loaded while the existing scanner driver is still loaded. This means that the application may have to unload a scanner driver, then reload the driver and initialize it if the user chooses the same scanner or hits the Cancel button.

See Also

IG_ISIS_drv_set_scan_name, IG_ISIS_drv_get_model_name.


IG_ISIS_drv_get_string

Retrieve a string from a driver.

Description

The IG_ISIS_drv_get_string function retrieves a string from a driver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_get_string(
    HISISDRV hDriver,
    LONG     lCode,
    LPSTR    lpszBuffer
    );

Parameters

hDriver
The handle of the driver from which a string is to be retrieved.
lCode
The string code and driver number. lCode is split into a HIWORD and a LOWORD, as described under "Usage," below.
lpszBuffer
A pointer to a buffer that will contain the string returned by IG_ISIS_drv_get_string.

Usage

In most cases, lCode is filled in by the driver that issues an error. The HIWORD of lCode contains the string number (and is normally a negative value). The LOWORD of lCode can contain either a driver number or zero. If the LOWORD of lCode contains a driver number, then hDriver and any Links or Splits are searched to find a match for the LOWORD of lCode. The LOWORD of lCode can be set to zero (0) by the application, in which case a specific string is fetched from hDriver. The following specific strings are defined for all drivers:

lCode
String
IG_ISIS_ATTR_VERSION
Driver name and version
IG_ISIS_ATTR_NAME
Long name of scanner
IG_ISIS_ATTR_COPYRIGHT
Vendor and copyright of driver vendor

Example

The following example shows how to use IG_ISIS_drv_get_string to determine specific driver information:

/* Retrieve specific driver information 	*/
char Buf[132];
IG_ISIS_drv_get_string(hDriver, MAKELONG(0,
IG_ISIS_ATTR_VERSION), Buf);
printf("Version:   %s\n", Buf);
IG_ISIS_drv_get_string(hDriver, MAKELONG(0, IG_ISIS_ATTR_NAME),
Buf);
printf("Name:      %s\n", Buf);
IG_ISIS_drv_get_string(hDriver, MAKELONG(0,
IG_ISIS_ATTR_COPYRIGHT), Buf);
printf("Vendor:    %s\n", Buf);

This program fragment will produce a display similar to the following:

Version: FUJIGINE Version 1.39
Name: Fujitsu ScanPartner10 / M3096Gm / M3097Gm
Copyright : Copyright 1994 Pixel Translations Incorporated

See Also

IG_ISIS_drv_get_version.


IG_ISIS_drv_get_version

Retrieve the version number of a driver.

Description

The IG_ISIS_drv_get_version function retrieves the minor version number of an ISIS driver. Currently, this is the number to the right of the decimal point in the version number. For example, if a driver has the version number "1.234", IG_ISIS_drv_get_version will retrieve the minor version number of "234." The major version number for all ISIS drivers is "1." This is the number to the left of the decimal point.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_get_version(
    HISISDRV hDriver,
    LPSTR    lpszBuffer,
    LPWORD   lpwVersion
    );

Parameters

hDriver
The handle to the driver.
lpszBuffer
A temporary storage buffer. Its size should be at least 5 bytes.
lpwVersion
A pointer that will point to the minor version number. This is the same as the Windows minor version number.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

IG_ISIS_drv_get_version can be used to display the version number of the current scanner driver in a scan settings dialog or with some other status reporting mechanism. It should not, however, be used for version comparison during the application installation process to determine whether to install a particular driver. If you are building an installer and needs to check driver versions to determine whether to install a newer driver, you should check the version resources provided by Windows.

See Also

IG_ISIS_drv_get_scan_name, IG_ISIS_drv_get_string.


IG_ISIS_drv_is_page_loaded

Determine whether or not a page is loaded in the scanner.

Description

The IG_ISIS_drv_is_page_loaded function checks to see whether or not a page is loaded on the scanner's flatbed or feeder (assuming the scanner supports this query).

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_is_page_loaded(
    HISISDRV   hDriver,
    AT_LMODE   lFlags,
    LPAT_LMODE lpResult
    );

Parameters

hDriver
The handle of the scanner driver.
lFlags
A bit field that can contain one of the following values:
lFlags
Meaning
IG_ISIS_TAG_FEEDER_FEED
Determine whether or not a page is loaded in the feeder.
IG_ISIS_TAG_FEEDER_FLAT
Determine whether or not a page is loaded on the flatbed. (Currently no supported scanners support page detection on a flatbed.)
lpResult
A bit field that will contain the result of the IG_ISIS_drv_is_page_loaded function. The following bits are currently defined:
lpResult
Meaning
0
If IG_ISIS_TAG_FEEDER_TELLFEED is not set, do not know whether or not a page is loaded. If IG_ISIS_TAG_FEEDER_TELLFEED is set, no page is loaded.
IG_ISIS_DRV_STACKNOPAGE
If IG_ISIS_TAG_FEEDER_TELLFEED is set, no page is loaded.
IG_ISIS_DRV_STACKPAGE
If IG_ISIS_TAG_FEEDER_TELLFEED is set, page is loaded.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

IG_ISIS_drv_is_page_loaded queries a scanner driver and reports whether or not a page is loaded. Before using IG_ISIS_drv_is_page_loaded, you must include code that uses IG_ISIS_tag_get_long to determine the scanner's capabilities, as shown in the example below. If the scanner does not support telling whether or not a page is loaded in the feeder (when IG_ISIS_FEEDER_TELLFEED = false), then lpdwResult will give zero (0) (can't tell if page is loaded).

The current implementation handles scanners with flatbed page sensors and feeder stack sensors. Future implementations may be enhanced with additional flags to handle hand scanners, frame grabbers, and other devices.

NOTE: Do not set tags between the time that you call IG_ISIS_drv_is_page_loaded and you run the zone. Otherwise, on scanners that must commit a page to determine if a page is loaded, the tags you set will not correctly describe the buffered page that was obtained when the scanner tried to sense whether or not a page was loaded.

Example

The following example checks the scanner to determine whether or not it can report whether there is a page in the feeder, and then checks to see whether or not a page is loaded:

DWORD dwBits;
IG_ISIS_tag_get_long(hDriver, IG_ISIS_TAGIG_ISIS_TAG_FEEDER, 0,
&dwBits);
if (dwBits & IG_ISIS_FEEDER_TELLFEED) {
    IG_ISIS_drv_is_page_loaded(hDriver, IG_ISIS_FEEDER_FEED,
&dwBits);
    if (dwBits & IG_ISIS_DRV_STACKPAGE);
        printf("There is a page ready in the feeder.");
    else
        printf("The feeder is empty.");
}
else
    printf("Can't tell if page is present.");

See Also

IG_ISIS_tag_get_long.


IG_ISIS_drv_read_dither_file

Obtain a user downloadable dither pattern.

Description

The IG_ISIS_drv_read_dither_file function prompts the application user for a dither file and then uses the file data to fill in a downloadable dither pattern for the scanner.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_read_dither_file(
    HISISDRV hDriver,
    AT_MODE  nTag,
    HWND     hWnd
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the tag in which to store the downloadable dither pattern. For scanners that support downloadable dither patterns, this tag should be set to IG_ISIS_TAG_DITHERPATTERN_1 or IG_ISIS_TAG_DITHERPATTERN_2.
hWnd
A handle to the parent window.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Before calling IG_ISIS_drv_read_dither_file, make sure the current scanner supports user downloadable dither patterns by querying the existence of IG_ISIS_TAG_DITHER_PATTERN1 and IG_ISIS_TAG_DITHER_PATTERN2. If the scanner supports one downloadable dither pattern, then IG_ISIS_TAG_DITHER_PATTERN1 will be available. If the scanner supports two patterns, then both tags will be available.

Use IG_ISIS_drv_read_dither_file to prompt the application user to choose a dither file from a File Open dialog, and then set nTag to contain the dither pattern read from the file. IG_ISIS_drv_read_dither_file does not automatically forward the dither pattern down to the scanner. If the user then selects to use the downloaded dither pattern as a parameter for scanning, call IG_ISIS_drv_send_dither to send the pattern data to the scanner hardware.

The function will check for file format validity. However, there is no guarantee that a selected dither pattern is valid. If scanning occurs while an invalid dither pattern is in use, unpredicatable program behavior may result.

The File Open dialog displayed by IG_ISIS_drv_read_dither_file will automatically look for files in the current directory that ends in the extension .PXH. However, it can open any ASCII text file that specifies the dither pattern using the standard format. See IG_ISIS_TAG_DITHER_PATTERN1 for a discussion on the standard dither pattern format.

See Also

IG_ISIS_drv_send_dither, IG_ISIS_drv_read_gamma_file, IG_ISIS_drv_send_gamma, IG_ISIS_TAG_DITHER, IG_ISIS_TAG_DITHER_PATTERN1, IG_ISIS_TAG_DITHER_PATTERN2.


IG_ISIS_drv_read_gamma_file

Obtain a user downloadable gamma table.

Description

The IG_ISIS_drv_read_gamma_file function prompts the application user for a gamma file and then uses the file data to fill in a downloadable gamma correction table for the scanner.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_read_gamma_file(
    HISISDRV hDriver,
    AT_MODE  nTag,
    HWND     hWnd
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the tag in which to store the downloadable gamma table. For scanners that support downloadable gamma tables, this tag should be set to one of the IG_ISIS_TAG_GAMMA_TABLEn tags.
hWnd
A handle to the parent window.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Before calling IG_ISIS_drv_read_gamma_file, make sure the current scanner supports user downloadable gamma tables by querying the existence of the IG_ISIS_TAG_GAMMA_TABLEn tags. If the scanner supports one downloadable gamma table, then IG_ISIS_TAG_GAMMA_TABLE1 will be available. If the scanner supports more than one gamma table, then there will be n number such tags available.

Use IG_ISIS_drv_read_gamma_file to prompt the application user to choose a gamma file from a File Open dialog, and then set nTag to contain the gamma table read from the file. IG_ISIS_drv_read_gamma_file does not automatically forward the gamma table down to the scanner. If the user then selects to use the downloaded gamma table as a parameter for scanning, call IG_ISIS_drv_send_gamma to send the gamma curve data to the scanner hardware.

The function will check for file format validity. However, there is no guarantee that a selected gamma table is valid. If scanning occurs while an invalid gamma correction curve is in use, unpredicatable program behavior may result.

The File Open dialog displayed by IG_ISIS_drv_read_gamma_file will automatically look for files in the current directory that ends in the extension .PXG. However, it can open any ASCII text file that specifies the gamma table using the standard format. See IG_ISIS_TAG_GAMMA_TABLEn for a discussion on the standard gamma correction table format.

See Also

IG_ISIS_drv_send_dither, IG_ISIS_drv_read_gamma_file, IG_ISIS_drv_send_gamma, IG_ISIS_TAG_GAMMA, IG_ISIS_TAG_GAMMA_TABLEn.


IG_ISIS_drv_send

Send a message to a driver's internal data structure.

Description

The IG_ISIS_drv_send function calls the message handler of the driver identified by hDriver (hDriver->hData) and passes wMessage, lParam1, and lParam2 to its internal data structure.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_send(
    HISISDRV hDriver,
    WORD     wMessage,
    LONG     lParam1,
    LONG     lParam2
    );

Parameters

hDriver
The handle of the driver to which the message and parameters are being sent.
wMessage
The message to pass to the driver.
lParam1
The first parameter of the message. (Most messages have two parameters.)
lParam2
The second parameter of the message.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Each ISIS driver has a single entry point through which it communicates. This entry point is accessed by sending messages together with parameters using IG_ISIS_drv_send.

Example

The following example does the functional equivalent of sending a IG_ISIS_tag_set_long function to a driver to set the image width.

IG_ISIS_drv_send(hDriver, IG_ISIS_tag_set_long,
    MAKELONG(IG_ISIS_TAG_IMAGEWIDTH, 0), 2550)


IG_ISIS_drv_send_dither

Send a downloadable dither pattern to the scanner.

Description

The IG_ISIS_drv_send_dither function sends the downloadable dither pattern stored in one of the downloable dither tags down to the scanner.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_send_dither(
    HISISDRV hDriver,
    AT_MODE  nTag
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the downloadable dither tag whose value is to be sent to the scanner, either IG_ISIS_TAG_DITHERPATTERN_1 or IG_ISIS_TAG_DITHERPATTERN_2.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Before calling IG_ISIS_drv_send_dither, you should have already called IG_ISIS_drv_read_dither_file with the tag specified in nTag to obtain a downloadable dither pattern from the user or called IG_ISIS_tag_set_long on nTag to configure a downloadable dither pattern. Use IG_ISIS_drv_send_dither to actually forward the dither pattern data to the scanner hardware.

See Also

IG_ISIS_drv_read_dither_file, IG_ISIS_drv_read_gamma_file, IG_ISIS_drv_send_gamma, IG_ISIS_TAG_DITHER, IG_ISIS_TAG_DITHER_PATTERN1, IG_ISIS_TAG_DITHER_PATTERN2.


IG_ISIS_drv_send_gamma

Send a downloadable gamma table to the scanner.

Description

The IG_ISIS_drv_send_gamma function sends the downloadable gamma correction table stored in one of the downloable gamma tags down to the scanner.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_send_gamma(
    HISISDRV hDriver,
    AT_MODE  nTag
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the downloadable gamma tag whose value is to be sent to the scanner. This should be one of the IG_ISIS_TAG_GAMMA_TABLEn tags.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Before calling IG_ISIS_drv_send_gamma, you should have already called IG_ISIS_drv_read_gamma_file with the tag specified in nTag to obtain a downloadable dither pattern from the user or called IG_ISIS_tag_set_long on nTag to configure a downloadable gamma table. Use IG_ISIS_drv_send_gamma to actually forward the gamma curve data to the scanner hardware.

See Also

IG_ISIS_drv_read_gamma_file, IG_ISIS_drv_send_dither, IG_ISIS_TAG_GAMMA, IG_ISIS_TAG_GAMMA_TABLEn.


IG_ISIS_drv_set_dialog

Display scanner settings dialog box.

Description

The IG_ISIS_drv_set_dialog function displays a predefined dialog box that allows the user to set scanning parameters, such as resolution, dither pattern, brightness, contrast, and so forth.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_set_dialog(
    HISISDRV  hDriver,
    HWND      hWnd,
    HINSTANCE hInst,
    AT_LMODE  lFlags
    );

Parameters

hDriver
The handle of the driver for which this dialog box is being displayed.
hWnd
A handle to the parent window.
hInst
A handle to the application instance window.
lFlags
Future versions of ISIS may allow lFlags to restrict access to the settable values in the dialog box. The values of lFlags are as follows:
dwFlags
Meaning
0
Display normal Scanner Settings dialog box.
IG_ISIS_DRV_SET_DIALOG_BIN
Restrict the scanner settings to binary, effectively preventing the user from choosing grayscale or color modes.
IG_ISIS_DRV_SET_DIALOG_AREA
Show the Area button on the dialog box. When the user clicks the Area button, the Area dialog box appears. When not set, the Area button is not visible.
IG_ISIS_DRV_SET_DIALOG_AREAPREVIEW
When set, if the user clicks on the Area button, the dialog displayed will include a preview box where the user can set the scan area through mouse actions. The preview box may display animage if a callback function has been set with IG_ISIS_area_dialog_CB_register, otherwise it will be gray. Using this flag automatically sets the IG_ISIS_DRV_SET_DIALOG_AREA flag as well. The MVIEW sample included with the toolkit shows how this flag may be used.
IG_ISIS_DRV_SET_DIALOG_RETURN
When set, if the user clicks Cancel, IG_ISIS_drv_set_dialog returns IG_ISIS_ERR_CANCEL. If the user clicks OK, it returns IG_ISIS_SUCCESS. If this flag is not set, IG_ISIS_drv_set_dialog always returns IG_ISIS_SUCCESS.
The Scanner Settings dialog box lets you access a scanner-specific More Settings dialog box for scanners that support this feature. Note that the More button appears dimmed in the dialog box unless IG_ISIS_TAG_MORE_SETTINGS exists in the scanner driver currently selected, and is set to 1. The More dialog can also be displayed by using the IG_ISIS_drv_set_more function:
lStatus = IG_ISIS_drv_set_more (lpDriver, hWnd);
where hWnd is the handle of the parent window.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Application developers should use this function rather than setting scanner parameters explicitly. Applications will then be better able to take advantage of new scanner capabilities as these capabilities are released in new scanner drivers. By using the IG_ISIS_drv_set_dialog function, the new capabilities will appear automatically whenever a new scanner driver is connected.

NOTE: In all cases except the Kodak IL900 and IL500 scanner drivers, changing the Settings dialog box changes the tags that will be used to scan a page. The tags do not get sent until a scan is started. On the Kodak drivers, the user is asked whether or not to send the tags when they click OK in the Settings dialog box.

The built-in Scanner Settings dialog looks similar to this:

This dialog box encompasses the standard settings available on most scanners; however, it may vary depending on the selected scanner. The lower left corner of the dialog displays the Pixdflt and scanner driver version numbers. Buttons along the right edge of the dialog perform the following predefined operations:

Default
Returns all settings in this dialog box to their factory default settings. Factory default settings are established by the person who wrote the scanner driver. Note that factory defaults for Brightness and Contrast may be off-center based on tests conducted with the scanner to determine the setting which gives best results with "normal" pages.
Area...
Displays the predefined Area dialog box, which allows users to specify an area of the page to scan.
More...
Displays a scanner driver-specific dialog box with additional settings. If no additional settings are available, the More.. button does not appear.
Filters...
Displays the predefined Filter Selection dialog box, which allows users to enable and disable image-enhancement filters that were installed in the Scanner Selection dialog. If no filters were installed, the Filters... button is dimmed. The Filters dialog box looks like this, with the actual filter names listed in the two windows:

Example

The following example restores saved tag values from a file, then displays the Scanner Settings dialog, allowing the user to make whatever changes are desired. Finally, it saves any changes made back to the file.

/* Get saved tag values													*/
IG_ISIS_tag_restore_file(hScan, 0, "SETSCAN.INI");
/* Display dialog 												*/
IG_ISIS_drv_set_dialog (hScan, hWnd, 0);
/* Save any changes from using the dialog 							*/
IG_ISIS_tag_save_file(hScan, 0, "SETSCAN.INI");

See Also

IG_ISIS_tag_restore_file, IG_ISIS_tag_restore_value, IG_ISIS_tag_save_file, IG_ISIS_tag_save_value, IG_ISIS_drv_area_dialog, IG_ISIS_drv_set_more, IG_ISIS_area_dialog_CB_register.


IG_ISIS_drv_set_more

Display scanner driver-specific More dialog box.

Description

The IG_ISIS_drv_set_more function displays a predefined dialog box that allows the user to access scanner specific settings, such as pagesize detection, barcode recognition, endorsement, gamma correction, and so forth.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_set_more(
    HISISDRV hDriver,
    HWND     hWnd
    );

Parameters

hDriver
The handle of the driver for which this dialog box is being displayed.
hWnd
A handle to the parent window.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Application developers should allow use of this function even if they support some scanner-specific settings explicitly. End users will then be better able to take advantage of new scanner capabilities as these capabilities are released in new scanner drivers. By using the IG_ISIS_drv_set_more function, the new capabilities will appear automatically whenever a new scanner driver is connected.

Example

The following example checks for the existence and value of IG_ISIS_TAG_MORE_SETTINGS and then displays the More dialog for drivers which support this feature.

LONG lValue;
// Is More dialog supported?
if ( IG_ISIS_tag_get_long(hDriver, IG_ISIS_TAG_MORE_SETTINGS,
0, &lValue) == IGE_SUCCESS ) {
      // Launch More... dialog
      IG_ISIS_drv_set_more(hDriver, hWnd);
}

See Also

IG_ISIS_drv_set_dialog.


IG_ISIS_drv_set_scan_name

Display scanner selection dialog box.

Description

The IG_ISIS_drv_set_scan_name function displays a predefined dialog box that allows the user to choose a scanner, add a scanner, or configure a scanner.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_set_scan_name(
    HWND hWnd
    );

Parameters

hWnd
A handle to the parent window.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Calling IG_ISIS_drv_set_scan_name displays a dialog box that allows the user to choose a scanner from among all the ISIS scanner drivers that can be found on the user's system. When this function is called, PIXDFLT looks for drivers in WINDOWS\PIXTRAN and other places. To guarantee future compatibility and version control, ImageGear now requires locating all scanner drivers in WINDOWS\PIXTRAN.

PIXDFLT keeps track of the currently-selected scanner by making an entry under the [Scanner] heading in the SETSCAN.INI file which is created automatically and stored in the user's WINDOWS directory. IG_ISIS_drv_set_scan_name uses this information to highlight the currently-selected scanner, if any.

Your application can take advantage of the built-in scanner selection dialogs by adding a Select Scanner command to its File menu (or some other suitable menu) that calls IG_ISIS_drv_set_scan_name.

Note that IG_ISIS_drv_set_scan_name selects the scanner driver, but does not try to communicate with the scanner. The application can call IG_ISIS_drv_get_scan_name to retrieve the selected scanner name after setting it with IG_ISIS_drv_set_scan_name. Each time a scanner driver is selected, a section for that scanner is created in the user's SETSCAN.INI file. The first entry in this section is "Setup=No" which indicates that no scanner setup has ever been performed on this user's system.

Buttons along the right edge of the dialog perform the following predefined operations:

Add
Displays the Add Scanner dialog box which allows the user to install additional scanner drivers supplied either by AccuSoft or by companies that develop and market ISIS scanner drivers.
Setup...
Loads the selected scanner driver and displays a scanner-specific configuration dialog box that allows configuration of SCSI addresses, I/O addresses, interrupts, and other parameters required by the scanner communication link, as well as the paper size to be used by default.
Once configuration information is determined for a particular scanner, it is saved under a scanner-specific section name in the SETSCAN.INI file. All scanners ever selected by a user will appear in this SETSCAN.INI file, each in their own section. When the user clicks OK and closes this dialog box, the entries specified in each window of the dialog box are saved in the scanner-specific section of the SETSCAN.INI file. The line "Setup=No" is changed to "Setup=Yes" and the scanner driver is unloaded.
A side effect of loading the driver is that permissions are checked at this time. If the user does not have sufficient permissions to use the driver, an appropriate error message will appear and the driver will not be added to the SYSTEM.INI file.
Note that this dialog box can be displayed independently by using the IG_ISIS_drv_configure function.
Filters...
Displays the predefined Filter Selection dialog box, which allows users to enable and disable image-enhancement filters, if any, that are available for the selected scanner. :
Information about selected filters is saved in the scanner-specific section of the SETSCAN.INI file.

It is recommended that you unload any currently loaded scanner drivers before calling IG_ISIS_drv_set_scan_name. The user may want to add a newer version of the currently selected driver from a different directory. If you did not unload that driver from memory prior to calling IG_ISIS_drv_set_scan_name, the user would be prevented from doing so.

If the user selects a scanner that has never been selected, does not click the Setup button, and then click OK to close the Scanner Selection dialog box, the toolkit checks the SETSCAN.INI file, finds the scanner-specific entry that says "Setup=No" and invokes the Setup dialog box.

NOTE: Some scanners have no configuration parameters, or their configuration is set using an operating system level driver. In these cases, clicking the Setup button displays an appropriate message.

Example

See the example for IG_ISIS_drv_set_dialog.

See Also

IG_ISIS_drv_configure, IG_ISIS_drv_get_scan_name, IG_ISIS_drv_load.


Choice Functions

IG_ISIS_choice_get_ascii

Get a valid ASCII choice value from a driver.

Description

The IG_ISIS_choice_get_ascii function fills in lpszValue with the string referenced by wIndex from tag nTag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_choice_get_ascii(
    HISISDRV hDriver,
    AT_MODE  nTag,
    WORD     wIndex,
    LPSTR    lpszValue
    );

Parameters

hDriver
The handle to the driver.
nTag
The tag for which a valid ASCII value is being requested.
wIndex
An index to a particular element of the array of valid tag values.
lpszValue
A pointer to a buffer that will contain the result of IG_ISIS_choice_get_ascii.

Usage

This function must be used only for tags which have a type of IG_ISIS_TAG_TYPE_STRING. Use the IG_ISIS_tag_get_type function to determine the type of a tag.

wIndex must reference the actual number of legal values defined for a given tag. The IG_ISIS_choice_get_count function can be used to determine the total number of legal values for a tag. wIndex must be at least 0 and at most the value returned by IG_ISIS_choice_get_count - 1. The constants IG_ISIS_CHOICE_LOW, IG_ISIS_CHOICE_HIGH, and IG_ISIS_CHOICE_STEP are not valid values for wIndex, since RANGE is an invalid branch type for ASCII values.

To determine the required size of lpszValue, use the IG_ISIS_choice_get_ascii_len function. Note that IG_ISIS_choice_get_ascii_len may return a different value for each member of an array of valid values referenced by wIndex.

Example

WORD wCount, i;
char lpcString[MAXLEN];
IG_ISIS_choice_get_count(hDriver, IG_ISIS_TAG_PAGESIZE,
&wCount);
  for (i = 0; i < nCount; i++) {							/* add sting to list */
    IG_ISIS_choice_get_ascii_len(hDriver, IG_ISIS_TAG_PAGESIZE,
i, &wLength);
    if (wLength <= maxlen)
    {
      IG_ISIS_choice_get_ascii(hDriver, IG_ISIS_TAG_PAGESIZE, i,
lpcString2);
  else
    strcpy(lpcString2, "too long to fit in window");

See Also

IG_ISIS_choice_get_ascii_len, IG_ISIS_choice_get_count, IG_ISIS_tag_get_type.


IG_ISIS_choice_get_ascii_len

Get the length of an ASCII value from a driver.

Description

The IG_ISIS_choice_get_ascii_len function fills in lpwLength with the length of the string referenced by wIndex from tag nTag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_choice_get_ascii_len(
    HISISDRV hDriver,
    AT_MODE  nTag,
    WORD     wIndex,
    LPWORD   lpwLength
    );

Parameters

hDriver
The handle to the driver.
nTag
The tag for which the length of an ASCII value is being requested.
wIndex
An index to a particular element of the array of tag values.
lpwLength
The address of an unsigned integer in which the string length will be stored.

Usage

This function is often used in conjunction with IG_ISIS_choice_get_ascii to determine the required size of that function's lpszValue parameter.

This function must be used only for tags which have a type of IG_ISIS_TAG_TYPE_STRING. Use the IG_ISIS_tag_get_type function to determine the type of a tag.

wIndex must reference the actual number of legal values defined for a given tag. The IG_ISIS_choice_get_count function can be used to determine the total number of legal values for a tag. wIndex must be at least 0 and at most the value returned by IG_ISIS_choice_get_count - 1. The constants IG_ISIS_CHOICE_LOW, IG_ISIS_CHOICE_HIGH, and IG_ISIS_CHOICE_STEP are not valid values for wIndex.

Note that IG_ISIS_choice_get_ascii_len may return a different value for each member of an array of valid values referenced by wIndex.

Example

See IG_ISIS_choice_get_ascii example.

See Also

IG_ISIS_choice_get_ascii, IG_ISIS_choice_get_count, IG_ISIS_tag_get_type.


IG_ISIS_choice_get_count

Get the total number of legal values for a tag.

Description

The IG_ISIS_choice_get_count function retrieves the total number of legal values from a specified tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_choice_get_count(
    HISISDRV hDriver,
    AT_MODE  nTag,
    LPWORD   lpwCount
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the tag for which the count of legal choice values is being requested.
lpwCount
The address of an unsigned integer in which the number of legal values will be stored. If a choice node is defined for the tag, then this parameter will contain the available number of values in the currently-selected node. If no choice node is defined for the tag, this parameter returns a value of 1.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

The IG_ISIS_choice_get_count function can be used to determine the valid range of the wIndex parameter to use in other IG_ISIS_choice_get... functions. The range is zero to (*lpwCount - 1).

If the tag is defined, IG_ISIS_choice_get_count always returns IGE_SUCCESS. The value returned in lpwCount is valid, and its value depends on the type of choice node for the specified tag:

  • If a choice node is defined for the tag, lpwCount specifies the available number of values in the current node.
  • If the choice node is a range node, the value returned in lpwCount specifies the number of values computed by ((MAX - MIN) / STEP).
  • If no choice node is defined for the tag, lpwCount contains the value 1.

IG_ISIS_choice_get_count returns the correct value even if the choices for a tag are represented as a range (low, high, step).

Example

See IG_ISIS_choice_get_ascii example.

See Also

IG_ISIS_choice_get_ascii, IG_ISIS_choice_get_long, IG_ISIS_choice_get_rational, IG_ISIS_tag_get_type.


IG_ISIS_choice_get_flags

Get a flag word for a tag.

Description

The IG_ISIS_choice_get_flags function fills in lpdwFlags with the flag word from tag nTag. The values contained in this flag word are described below, under "Structures."

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_choice_get_flags(
    HISISDRV   hDriver,
    AT_MODE    nTag,
    LPAT_LMODE lpFlags
    );

Parameters

hDriver
The handle to the driver.
nTag
The tag for which the flag word is being requested.
lpFlags
A pointer to a buffer that will contain the result of IG_ISIS_choice_get_flags. Currently, only two bits of lpFlags are defined:
  • IG_ISIS_CONT_RANGE - Choice values are represented internally as a range, with a low value, a high value, and a step value.
  • IG_ISIS_CONT_LIST - Choice values are represented internally as a simple list of values.

Usage

The flag word returned by IG_ISIS_choice_get_flags is currently used only to differentiate between two types of flag values in a tag: IG_ISIS_CONT_RANGE and IG_ISIS_CONT_LIST. One of these constants should be ANDed with the flag word output by IG_ISIS_choice_get_flags to determine a choice's internal representation.

While most choice functions behave identically regardless of type, the STEP value is only available if the IG_ISIS_CONT_RANGE bit is set.

Example

The following example shows how to use IG_ISIS_choice_get_flags to determine whether a particular tag is a list or a range. This is part of a sample that determines whether a scanner can output binary, grayscale, or color.

main()
{
    LONG lBits, lSamps, lFlags;
    WORD wCount, iIndex;
    HISISDRV hScan;
    AT_ERRCOUNT nErrCount;
/* Load & init a scanner driver. 							*/
    nErrCount = IG_ISIS_drv_load_init_pipe(0, "NIKON", &hScan,
0);
/* Find out how many choices for SAMPLESPERPIXEL. 							*/
    IG_ISIS_choice_get_count(hScan, IG_ISIS_TAG_SAMPLESPERPIXEL,
&wCount);
/* Get and set values for SAMPLESPERPIXEL one at a time.							*/
    for (iIndex = 0; iIndex < wCount; iIndex++) {
        IG_ISIS_choice_get_long(hScan,
IG_ISIS_TAG_SAMPLESPERPIXEL, iIndex,
                    &lSamps);
        IG_ISIS_tag_set_long(hScan, IG_ISIS_TAG_SAMPLESPERPIXEL,
0, lSamps);
/* If SAMPLESPERPIXEL is 1, then must be binary or grayscale.							*/
        if (lSamps == 1) {
            LONG lValue;
/* Determine whether BITSPERSAMPLE is list or range.							*/
            IG_ISIS_choice_get_flags(hScan,
IG_ISIS_TAG_BITSPERSAMPLE, &lFlags);
/* Handle case where BITSPERSAMPLE is a list.							*/
            if (lFlags & IG_ISIS_CONT_LIST) {
                WORD iIndex, wCount;
                LONG lBits;
                IG_ISIS_choice_get_count(hScan,
IG_ISIS_TAG_BITSPERSAMPLE, &wCount);
                for (iIndex = 0; iIndex < wCount; iIndex++) {
                    IG_ISIS_choice_get_long(hScan,
IG_ISIS_TAG_BITSPERSAMPLE,
                        iIndex, &lBits);
                    if (lBits==1)
                        printf("Binary is supported\n");
                    else
                        printf("%d-bit grayscale is supported\n",
                             INT16)lBits);
                }
            }
            else
/* Handle other cases.													*/
            .
            .
            .

See Also

IG_ISIS_choice_get_ascii, IG_ISIS_choice_get_long, IG_ISIS_choice_get_rational, IG_ISIS_tag_get_type.


IG_ISIS_choice_get_long

Get valid byte, short, or long choice value from driver.

Description

The IG_ISIS_choice_get_long function fills in lplValue with the value referenced by wIndex from tag nTag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_choice_get_long(
    HISISDRV hDriver,
    AT_MODE  nTag,
    WORD     wIndex,
    LPLONG   lplValue
    );

Parameters

hDriver
The handle to the driver.
nTag
The tag for which a valid byte, short, or long integer value is being requested.
wIndex
An index to a particular element of the array of valid tag values.
lplValue
A pointer to a buffer that will contain the result of IG_ISIS_choice_get_long.

Usage

This function must be used only for tags which have a type of IG_ISIS_TAG_TYPE_BYTE, IG_ISIS_TAG_TYPE_SHORT, or IG_ISIS_TAG_TYPE_LONG. Use the IG_ISIS_tag_get_type function to determine the type of a tag.

The IG_ISIS_choice_get_count function can be used to determine the total number of legal values for a tag. wIndex must be at least 0 and at most the value returned by IG_ISIS_choice_get_count - 1. The constants IG_ISIS_CHOICE_LOW and IG_ISIS_CHOICE_HIGH can be used to retrieve the 0th and nth values of a list or range; however, keep in mind that a list must be sorted from low to high values for these constants to return the actual low and high values of the list. Also, IG_ISIS_CHOICE_STEP can be used if the flag IG_ISIS_CONT_RANGE is set. The value returned by IG_ISIS_choice_get_long using a wIndex value of IG_ISIS_CHOICE_STEP is the difference between any two consecutive values.

See Also

IG_ISIS_choice_get_count, IG_ISIS_tag_get_type.


IG_ISIS_choice_get_rational

Get a valid rational choice value from a driver.

Description

The IG_ISIS_choice_get_rational function fills in lpValue with the value referenced by wIndex from tag nTag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_choice_get_rational(
    HISISDRV      hDriver,
    AT_MODE       nTag,
    WORD          wIndex,
    LPAT_ISIS_RAT lpValue
    );

Parameters

hDriver
The handle to the driver.
nTag
The tag for which a valid rational value is being requested.
wIndex
An index to a particular element of the array of valid tag values.
lpValue
A pointer to a RAT buffer that will contain the result of IG_ISIS_choice_get_rational.

Usage

This function must be used only for tags which have a type of IG_ISIS_TAG_TYPE_RATIONAL. Use the IG_ISIS_tag_get_type function to determine the type of a tag.

The IG_ISIS_choice_get_count function can be used to determine the total number of legal values for a tag. wIndex must be at least 0 and at most the value returned by IG_ISIS_choice_get_count - 1. The constants IG_ISIS_CHOICE_LOW and IG_ISIS_CHOICE_HIGH can be used to retrieve the 0th and nth values of a list or range; however, keep in mind that a list must be sorted from low to high values for these constants to return the actual low and high values of the list. Also, IG_ISIS_CHOICE_STEP can be used if the flag IG_ISIS_CONT_RANGE is set. The value returned by IG_ISIS_choice_get_rational using a wIndex value of IG_ISIS_CHOICE_STEP is the difference between any two consecutive values.

Example

The following example first determines whether the choices of a rational value, IG_ISIS_TAG_XRESOLUTION, are implemented as a range or a list, then gets each value and prints it to the standard output:

nErrCount = IG_ISIS_choice_get_flags(hDriver,
IG_ISIS_TAG_XRESOLUTION, &lValue);
    if (nErrCount != IGE_SUCCESS)        return nErrCount;
/* If choices are stored as a range, get the low, high, and
step:													 */
    if (lValue & IG_ISIS_CONT_RANGE) {
        nErrCount = IG_ISIS_choice_get_rational(hDriver,
IG_ISIS_TAG_XRESOLUTION,
                         IG_ISIS_CHOICE_LOW, &ratResLo);
        if (nErrCount != IGE_SUCCESS)        return nErrCount;
        nErrCount = IG_ISIS_choice_get_rational(hDriver,
IG_ISIS_TAG_XRESOLUTION,
                         IG_ISIS_CHOICE_HIGH, &ratResHi);
        if (nErrCount != IGE_SUCCESS)        return nErrCount;
        nErrCount = IG_ISIS_choice_get_rational(hDriver,
IG_ISIS_TAG_XRESOLUTION,
                         IG_ISIS_CHOICE_STEP, &ratResStep);
        if (nErrCount != IGE_SUCCESS)        return nErrCount;
        printf("  Range:\n   %ld/%ld - %ld/%ld by %ld/%ld\n",
                ratResLo.Num, ratResLo.Denom,
                ratResHi.Num, ratResHi.Denom,
                ratResStep.Num, ratResStep.Denom);
    }
/* If choices are stored as a list, get and print the entire
list:														 */
    if (lValue & IG_ISIS_CONT_LIST) {
        nErrCount = IG_ISIS_choice_get_count(hDriver,
IG_ISIS_TAG_XRESOLUTION, &wCount);
        if (nErrCount != IGE_SUCCESS)        return nErrCount;
        printf("  Values:\n");
        for (w=0; w < wCount; w++) {
            nErrCount = IG_ISIS_choice_get_rational(hDriver,
IG_ISIS_TAG_XRESOLUTION, w, &ratRes);
            if (nErrCount != IGE_SUCCESS)        return nErrCount;
            printf("   %3ld/%ld" , ratRes.Num, ratRes.Denom);
            if ((w%7) == 6 || (w == wCount-1))
                printf("\n"); // seven per line
        }

Structures

The toolkit's RAG value consists of a signed 32-bit numerator (Num) and a signed 32-bit denominator (Denom), comprising a fractional value: . The individual values of a AT_ISIS_RAT type can be accessed as conventional elements:

    ratValue.Num
    ratValue.Denom

See Also

IG_ISIS_choice_get_count, IG_ISIS_tag_get_type.


Tag Functions

IG_ISIS_drv_update_state

Update the values of dependent values in a dialog box.

Description

The IG_ISIS_drv_update_state function checks the value of an interdependent tag and then updates choices for dependent tags, allowing an application to update the values being displayed in a dialog box dynamically as the user picks various file and color formats. By using this function with Custom Dialog tags, you can create an application that can save files in whatever formats are currently supported by the file converters (*.PXIs) installed on the system. Using this function together with the Custom Dialog tags allows you to design an application which will automatically add new file types to a list box whenever the user installs new file converters.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_drv_update_state(
    HISISDRV hDriver,
    AT_MODE  nTag,
    WORD     wIndex
    );

Parameters

hDriver
The handle of the driver on which tags choices need to be changed. This is a pointer to the handle of the PIXFPACK driver.
nTag
The tag value which is being changed. Usually, this value will be one of IG_ISIS_TAG_FILETYPE_LBS and IG_ISIS_TAG_COLORFMTS_LBS (if you are using one color format list box), or one of IG_ISIS_TAG_FILETYPE_LBS, IG_ISIS_TAG_SPP_LBS, IG_ISIS_TAG_BPS_LBS, and IG_ISIS_TAG_PHOTO_LBS (if you are using three separate list boxes to establish color formats.
wIndex
The index number of the new value of nTag.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

The IG_ISIS_drv_update_state function signals PIXFPACK to update the choices of dependent tags. This is used to update the values of Color Format and Compression when File Type is changed, and to update the values of Compression when Color Format is changed.

To use IG_ISIS_drv_update_state, monitor a list box for a change. If the File Format list box gets changed, first get the current values of the dependent tags, then call IG_ISIS_drv_update_state with nTag set to IG_ISIS_TAG_FILETYPE_LBS and wIndex set to the new index value of the selected file type. IG_ISIS_drv_update_state will update the choices reported by IG_ISIS_TAG_COLORFMTS_LBS and IG_ISIS_TAG_COMPRESSION_LBS. Your application should then compare the new values of each of the dependent tags with the previous values and, if there is a match, keep the setting the same. If there is no match, you must decide on a new setting.

You will need to use IG_ISIS_drv_update_state while monitoring each of the listboxes that set tags that have dependencies. The following dependencies exist:

  • Dependencies in applications with one Color Format list box
  • Dependencies in applications with three Color Format list boxes


IG_ISIS_tag_flush_value

Release memory used by IG_ISIS_tag_save_value.

Description

The IG_ISIS_tag_flush_value function releases the memory allocated by IG_ISIS_tag_save_value. Note that IG_ISIS_tag_restore_value automatically frees this memory.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_flush_value(
    HISISDRV hDriver,
    AT_MODE  nTag
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the tag that was saved and whose memory needs to be flushed. Specify a value of zero if you specified zero in the corresponding IG_ISIS_tag_save_value function.

Usage

Use IG_ISIS_tag_restore_value to free the memory used to store the value(s) saved when the application issued the most current IG_ISIS_tag_save_value call. Each call to IG_ISIS_tag_save_value must have a corresponding call to either IG_ISIS_tag_restore_value or IG_ISIS_tag_flush_value. This is a relatively new requirement, as multiple settings can now be saved in a stack. Previously, only one group of settings could be saved at a time, so only one call to IG_ISIS_tag_restore_value or IG_ISIS_tag_flush_value was required.

The value of nTag should correspond to the value of nTag that was used when the corresponding IG_ISIS_tag_save_value was called. The values are saved in a last-in/first-out stack. By saving the settings of all tags multiple times, it is possible to implement a nested set of settings dialogs, one of which can be cancelled to restore original settings, even after accepting the settings in a previous one. (See IG_ISIS_tag_save_value.)

Example

The following code fragment invokes IG_ISIS_tag_restore_value if the user chooses Cancel, or IG_ISIS_tag_flush_value if the user chooses OK:

switch (GET_WM_COMMAND_ID(wParam, lParam)) {
    case IDCANCEL:
        IG_ISIS_tag_restore_value(DriverP,0);
        if (hModeList) {
            free(hModeList);
            hModeList = 0;
        }
        if (hWindowList) {
            free(hWindowList);
            hWindowList = 0;
        }
        EndDialog(hDlg,IG_ISIS_ERR_CANCEL);
        return TRUE;
    case IDOK:
        IG_ISIS_tag_flush_value(DriverP,0);
        if (hModeList) {
            free(hModeList);
            hModeList = 0;
        }
        if (hWindowList) {
            free(hWindowList);
            hWindowList = 0;
        }

See Also

IG_ISIS_tag_restore_value, IG_ISIS_tag_save_value.


IG_ISIS_tag_get_affect

Get a specific tag from a reference tag's list of affected tags.

Description

The IG_ISIS_tag_get_affect function retrieves a specific tag from the list of tags whose values and ranges of valid values are affected by the specified reference tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_get_affect(
    HISISDRV  hDriver,
    AT_MODE   nTag,
    WORD      wIndex,
    LPAT_MODE lpnAffectedTag
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the reference tag.
wIndex
Specifies the index of the affected tag to get.
lpnAffectedTag
Points to the affected tag specified by wIndex.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_get_affect to determine which tags are affected by changing the value of a reference tag. This is important when you are setting several tags in sequence. If you set a tag that affects other tags you have already set, the values of those affected tags could change unexpectedly.

Example

The following code fragment uses IG_ISIS_tag_get_affect and IG_ISIS_tag_get_affect_count to determine whether IG_ISIS_TAG_BITSPERSAMPLE had an effect on IG_ISIS_TAG_BRIGHTNESS:

/* figure out whether IG_ISIS_TAG_BITSPERSAMPLE affects
IG_ISIS_TAG_BRIGHTNESS */
WORD wCount, wAffectedTag;
IG_ISIS_tag_get_affect_count(hScan, IG_ISIS_TAG_BITSPERSAMPLE,
&wCount);
while (wCount-- >= 0) {
    IG_ISIS_tag_get_affect(hScan, IG_ISIS_TAG_BITSPERSAMPLE ,
wCount, &wAffectedTag);
    if (wAffectedTag == IG_ISIS_TAG_BRIGHTNESS) {
        /* IG_ISIS_TAG_BITSPERSAMPLE does affect
IG_ISIS_TAG_BRIGHTNESS */
    }
}

See Also

IG_ISIS_tag_get_affect_count.


IG_ISIS_tag_get_affect_count

Get the number of tags affected by the specified reference tag.

Description

The IG_ISIS_tag_get_affect_count function retrieves a count of the number of tags whose value or range of valid values is affected by the value of the specified reference tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_get_affect_count(
    HISISDRV hDriver,
    AT_MODE  nTag,
    LPWORD   lpwCount
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the reference tag.
lpwCount
Points to the number of tags affected by nTag.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_get_affect_count to determine how many tags are affected by nTag. This is important when you are setting several tags in sequence. If you set a tag that affects other tags you have already set, the values of those affected tags could change unexpectedly.

See Also

IG_ISIS_tag_get_affect.


IG_ISIS_tag_get_ascii

Get the current value of an ASCII tag.

Description

The IG_ISIS_tag_get_ascii function retrieves the ASCII string that is the current value of the specified tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_get_ascii(
    HISISDRV hDriver,
    AT_MODE  nTag,
    WORD     wLength,
    LPSTR    lpszValue
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the ASCII tag for which to return the current value.
wLength
Specifies the number of characters of the ASCII value to copy into lpcBuffer.
lpszValue
Points to a buffer to hold at most wLength bytes of nTag.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_get_ascii to retrieve the ASCII string that is the current value of the ASCII tag specified in nTag. The IG_ISIS_tag_get_length function can be used to determine the actual length of the string.

Use of IG_ISIS_tag_get_ascii on a non-ASCII tag is undefined. At best, this will cause an invalid return value or a operating system error message, and at worst will cause the system to crash.

Example

The following code fragment uses IG_ISIS_tag_get_ascii to help determine which dither mode has been selected:

/* figure out which dither mode has been selected (result in n)
*/
IG_ISIS_tag_get_ascii(hDriver, IG_ISIS_TAG_DITHER, 128,
lpcBuffer2);
IG_ISIS_choice_get_count(hDriver, IG_ISIS_TAG_DITHER, &wCount);
for (n=0; n<(int)wCount; n++) {
    IG_ISIS_choice_get_ascii(hDriver, IG_ISIS_TAG_DITHER, n,
lpcBuffer1);
    if (!strcmp(lpcBuffer1, lpcBuffer2))
    break;
}

See Also

IG_ISIS_tag_get_ascii_default, IG_ISIS_tag_get_length , IG_ISIS_tag_get_type, IG_ISIS_tag_set_ascii.


IG_ISIS_tag_get_ascii_default

Get the default value of an ASCII tag.

Description

The IG_ISIS_tag_get_ascii_default function retrieves the ASCII string that is the default value of the specified tag. The default value of a tag is specified in the driver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_get_ascii_default(
    HISISDRV hDriver,
    AT_MODE  nTag,
    WORD     wLength,
    LPSTR    lpszValue
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the ASCII tag for which to return the default value.
wLength
Specifies the number of characters of the ASCII value to copy into lpcBuffer.
lpszValue
Points to a buffer to hold at most wLength bytes of nTag.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_get_ascii_default to retrieve the ASCII string that is the default value of the ASCII tag specified in nTag. The IG_ISIS_tag_get_length default function can be used to determine the actual length of the string.

Use of IG_ISIS_tag_get_ascii_default on a non-ASCII tag is undefined. At best, this will cause an invalid return value or a operating system error message, and at worst will cause the system to crash.

Example

The following code fragment uses IG_ISIS_tag_get_ascii_default to determine the default value of IG_ISIS_TAG_ENDORSER_STRING:

case GETDEFAULT:
    rc = IG_ISIS_tag_get_ascii_default(hDriver,
IG_ISIS_TAG_ENDORSER_STRING,
                                 ENDORSER_MAXLEN, lpszBuf);
    if (rc)					/* If error return error code		*/
        return -1L;
    if (*lpszBuf == '\0')	 /* If no string then no endorser					*/
        return (LONG) FALSE;
    return (LONG) TRUE;

See Also

IG_ISIS_tag_get_ascii, IG_ISIS_tag_get_length , IG_ISIS_tag_get_type, IG_ISIS_tag_set_ascii.


IG_ISIS_tag_get_length

Get the number of elements in current value of a tag.

Description

The IG_ISIS_tag_get_length function retrieves the number of elements in the current value of the specified tag. In the case of an ASCII tag, IG_ISIS_tag_get_length returns the number of characters in the current value of the tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_get_length(
    HISISDRV hDriver,
    AT_MODE  nTag,
    LPDWORD  lpdwLength
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the tag for which to return the length.
lpdwLength
Points to the address which will contain the number of elements in nTag after this function completes.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_get_length to retrieve the length of the current value of the tag specified in nTag. This function is especially useful in determining a buffer size to hold the value returned by IG_ISIS_tag_get_ascii, because it obtains the number of characters in the current value of the tag, including the NULL terminator. For most other tags, *lpdwLength is 1.

Example

The following example gets the length of IG_ISIS_TAG_DITHER, allocates enough memory to hold the string, and then gets the ASCII value of IG_ISIS_TAG_DITHER and puts it in the buffer:

IG_ISIS_tag_get_length(hDriver, IG_ISIS_TAG_DITHER, &ulLength);
lpBuffer = malloc((ulLength + 1));
IG_ISIS_tag_get_ascii(hDriver, IG_ISIS_TAG_DITHER, ulLength,
lpBuffer);

See Also

IG_ISIS_tag_get_ascii , IG_ISIS_tag_get_length_default, IG_ISIS_tag_get_long, IG_ISIS_tag_get_rational, IG_ISIS_tag_get_type, IG_ISIS_tag_set_ascii, IG_ISIS_tag_set_long, IG_ISIS_tag_set_rational.


IG_ISIS_tag_get_length_default

Get number of elements in the default value of a tag.

Description

The IG_ISIS_tag_get_length_default function retrieves the number of elements in the default value of the specified tag. In the case of an ASCII tag, IG_ISIS_tag_get_length_default returns the number of characters in the current value of the tag. The default value of a tag is specified in the driver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_get_length_default(
    HISISDRV hDriver,
    AT_MODE  nTag,
    LPDWORD  lpdwLength
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the tag for which to return the length of the default value.
lpdwLength
Points to the address which will contain the number of elements in the default value of nTag after this function completes.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_get_length_default to retrieve the number of elements or the length of the default value of the tag specified in nTag. This function is especially useful in determining a buffer size to hold the value returned by IG_ISIS_tag_get_ascii_default, because it obtains the number of characters in the default value of the tag, including the NULL terminator. For most other tags, lpdwLength is 1.

Example

See IG_ISIS_tag_get_length example.

See Also

IG_ISIS_tag_get_ascii_default, IG_ISIS_tag_get_length, IG_ISIS_tag_get_long_default, IG_ISIS_tag_get_rational_default, IG_ISIS_tag_get_type.


IG_ISIS_tag_get_long

Get current value of a tag of type long.

Description

The IG_ISIS_tag_get_long function retrieves the long value that is the current value of the specified tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_get_long(
    HISISDRV hDriver,
    AT_MODE  nTag,
    WORD     wIndex,
    LPLONG   lplValue
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the type long tag for which to return the current value.
wIndex
Specifies the index of the element to get. Most tags have only one element, in which case wIndex must be zero. Use IG_ISIS_tag_get_length to determine how many elements a tag contains.
lplValue
Points to the current value of the tag after this function completes.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_get_long to retrieve the current value of the type long tag specified in nTag. Use IG_ISIS_tag_get_length to get the number of elements in the tag. If the tag has only one element, wIndex must be zero. If the tag has multiple elements (such as IG_ISIS_TAG_GAMMA_TABLE1), loop on IG_ISIS_tag_get_long to obtain all elements of the current value of the tag.

Use of IG_ISIS_tag_get_long on a tag other than one of type long, short, or byte is undefined. At best, this will cause an invalid return value or a operating system error message, and at worst will cause the system to crash.

Example

The following example gets the value of each element of a multiple value tag and puts them into an array:

BYTE caGamma[256];
DWORD dwCount;
LONG lValue;
IG_ISIS_tag_get_length(hDriver, IG_ISIS_TAG_GAMMA_TABLE1,
&dwCount);
while (dwCount--) {
    IG_ISIS_tag_get_long(hDriver, IG_ISIS_TAG_GAMMA_TABLE1,
dwCount, &lValue);
    caGamma[ulCount] = (BYTE) lValue;
}
/* Now that you have the values in an array, you can do
something 														*/
/* with them in your own function, such as:							*/
showGamma(caGamma);

See Also

IG_ISIS_tag_get_length, IG_ISIS_tag_get_long_default , IG_ISIS_tag_get_type, IG_ISIS_tag_set_long.


IG_ISIS_tag_get_long_default

Get the default value of a tag of type long.

Description

The IG_ISIS_tag_get_long_default function retrieves the long value that is the default value of the specified tag. The default value of a tag is specified in the driver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_get_long_default(
    HISISDRV hDriver,
    AT_MODE  nTag,
    WORD     wIndex,
    LPLONG   lplValue
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the type long tag for which to return the default value.
wIndex
Specifies the index of the element to get. Most tags have only one element, in which case wIndex must be zero. Use IG_ISIS_tag_get_length_default to determine how many elements a tag contains.
lplValue
Points to the default value of the tag after this function completes.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_get_long_default to retrieve the default value of the type long tag specified in nTag. Use IG_ISIS_tag_get_length_default to get the number of elements in the tag. If the tag has only one element, wIndex must be zero. If the tag has multiple elements (such as IG_ISIS_TAG_GAMMA_TABLE1), loop on IG_ISIS_tag_get_long_default to obtain all elements of the default value of the tag.

Use of IG_ISIS_tag_get_long_default on a tag other than one of type long, short, or byte is undefined. At best, this will cause an invalid return value or a operating system error message, and at worst will cause the system to crash. Passing anything other than a pointer to a long to lplValue, even if the tag is of type byte or short, is also undefined. On some systems, a proper value may be returned, but memory corruption will occur on others.

See Also

IG_ISIS_tag_get_length_default, IG_ISIS_tag_get_long , IG_ISIS_tag_get_type, IG_ISIS_tag_set_long.


IG_ISIS_tag_get_rational

Get current value of a tag of type rational.

Description

The IG_ISIS_tag_get_rational function retrieves the rational value that is the current value of the specified tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_get_rational(
    HISISDRV      hDriver,
    AT_MODE       nTag,
    WORD          wIndex,
    LPAT_ISIS_RAT lpValue
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the type rational tag for which to return the current value.
wIndex
Specifies the index of the element to get. Most tags have only one element, in which case wIndex must be zero. Use IG_ISIS_tag_get_length to determine how many elements a tag contains.
lpValue
Points to the current value of the tag after this function completes.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_get_rational to retrieve the current value of the type rational tag specified in nTag. Use IG_ISIS_tag_get_length to get the number of elements in the tag. If the tag has only one element, wIndex must be zero. If the tag has multiple elements, loop on IG_ISIS_tag_get_rational to obtain all elements of the current value of the tag.

Use of IG_ISIS_tag_get_rational on a tag other than one of type rational is undefined. At best, this will cause an invalid return value or a operating system error message, and at worst will cause the system to crash.

The tags most commonly defined as rational are the X and Y position and X and Y resolution tags.

Example

The following example gets the current scanning resolution and prints it to the standard output:

AT_ISIS_RAT ratValue;
IG_ISIS_tag_get_rational(hDriver, IG_ISIS_TAG_XRESOLUTION, 0,
&ratValue);
sprintf(caBuffer, "Scanning resolution is %ld DPI\n",
        (long)(ratValue.Num / ratValue.Denom));

See Also

IG_ISIS_tag_get_length, IG_ISIS_tag_get_rational_default , IG_ISIS_tag_set_rational.


IG_ISIS_tag_get_rational_default

Get default value of a tag of type rational.

Description

The IG_ISIS_tag_get_rational_default function retrieves the rational value that is the default value of the specified tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_get_rational_default(
    HISISDRV      hDriver,
    AT_MODE       nTag,
    WORD          wIndex,
    LPAT_ISIS_RAT lpValue
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the type rational tag for which to return the default value.
wIndex
Specifies the index of the element to get. Most tags have only one element, in which case wIndex must be zero. Use IG_ISIS_tag_get_length_default to determine how many elements a tag contains.
lpValue
Points to the default value of the tag after this function completes.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_get_rational_default to retrieve the default value of the type rational tag specified in nTag. Use IG_ISIS_tag_get_length_default to get the number of elements in the tag. If the tag has only one element, wIndex must be zero. If the tag has multiple elements, loop on IG_ISIS_tag_get_rational_default to obtain all elements of the default value of the tag.

Use of IG_ISIS_tag_get_rational_default on a tag other than one of type rational is undefined. At best, this will cause an invalid return value or a operating system error message, and at worst will cause the system to crash.

See Also

IG_ISIS_tag_get_length, IG_ISIS_tag_get_rational , IG_ISIS_tag_set_rational.


IG_ISIS_tag_get_type

Get the type of a tag.

Description

The IG_ISIS_tag_get_type function retrieves the type of the specified tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_get_type(
    HISISDRV  hDriver,
    AT_MODE   nTag,
    LPAT_MODE lpnType
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the tag for which to return the type.
lpnType
Points to the address which will contain the type of wTag after this function completes. lpnType is filled in with one of the following values:
  • IG_ISIS_TAG_TYPE_STRING - The tag consists of an ASCII string.
  • IG_ISIS_TAG_TYPE_BYTE - The tag consists of one or more signed byte values.
  • IG_ISIS_TAG_TYPE_SHORT - The tag consists of one or more signed integer values.
  • IG_ISIS_TAG_TYPE_LONG - The tag consists of one or more signed long values.
  • IG_ISIS_TAG_TYPE_RATIONAL - The tag consists of one or more rational values.
NOTE: The TIFF specification normally treats all values as unsigned. Note also that the types IG_ISIS_TAG_TYPE_BYTE, IG_ISIS_TAG_TYPE_SHORT, and IG_ISIS_TAG_TYPE_LONG are all accessed as longs in toolkit functions to reduce the total number of functions needed.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_get_type to determine the type of a tag before performing other functions such as IG_ISIS_tag_get_long, IG_ISIS_tag_get_long_default, etc., or IG_ISIS_choice_get_long, etc..

Example

The following example returns a text string that indicates the type of a tag based on checking the tag inside a driver.

char FAR *GetTagText (HISISDRV hDriver, AT_MODE nTag)  {
  DWORD dwLength ;
  LONG lTemp ;
  WORD wTemp ;
  AT_ISIS_RAT    ratValue ;
  char   FAR *cpString ;
  if (IG_ISIS_tag_get_type (hDriver, nTag, &wTemp))
    return NULL ;
  switch (wTemp) {
    case IG_ISIS_TAG_TYPE_STRING:
      IG_ISIS_tag_get_length (hDriver, nTag, &dwLength) ;
      if (NULL == (cpString = (char FAR *) malloc((ulLength +
1))))
        return NULL ;
      IG_ISIS_tag_get_ascii (hDriver, nTag, dwLength, cpString)
;
      return cpString ;
    case IG_ISIS_TAG_TYPE_BYTE:
    case IG_ISIS_TAG_TYPE_SHORT:
    case IG_ISIS_TAG_TYPE_LONG:
      /* Return only first value. */
      if (NULL == (cpString = (char FAR *) malloc(20)))
        return NULL ;
      IG_ISIS_tag_get_long (hDriver, nTag, 0, &lTemp) ;
      sprintf (cpString, "%d", lTemp, 0) ;
      return cpString ;
    case IG_ISIS_TAG_TYPE_RATIONAL:
      /* Return only first value. */
      if (NULL == (cpString = (char FAR *) malloc(20)))
        return NULL ;
      IG_ISIS_tag_get_long (hDriver, nTag, 0, &ratValue) ;
      lTemp = (LONG) (ratValue.Num / ratValue.Denom) ;
sprintf (cpString, "%d", lTemp, 0) ;
return cpString ;
    default:
      return NULL ;
    }
  }

See Also

IG_ISIS_tag_get_ascii , IG_ISIS_tag_get_ascii_default, IG_ISIS_tag_get_length, IG_ISIS_tag_get_length_default, IG_ISIS_tag_get_long, IG_ISIS_tag_get_long_default, IG_ISIS_tag_get_rational, IG_ISIS_tag_get_rational_default, IG_ISIS_tag_set_ascii, IG_ISIS_tag_set_long, IG_ISIS_tag_set_rational.


IG_ISIS_tag_restore_file

Restore saved tag values from a file.

Description

The IG_ISIS_tag_restore_file function restores the values of all tags from a specified file. This allows an application to implement a Restore Settings function that restores previously-saved settings in one operation. This function is only supported on Windows platforms.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_restore_file(
    HISISDRV hDriver,
    LPSTR    lpszSection,
    LPSTR    lpszFileName
    );

Parameters

hDriver
The handle to the driver.
lpszSection
Specifies the name of the [Section] from which to restore the previously-saved values of all tags. [Section] is a standard *.INI file section name of the application's choosing. The name specified will be automatically enclosed in square brackets-do not include them in the lpszSection string. Note that if lpszSection is zero, the name pointed to by hDriver will be used as the section name.
lpszFileName
Specifies the name of the file from which to restore the tag values. If lpszFileName is zero, the name SETSCAN.INI is used, but an application-specific filename is recommended.

Usage

Use IG_ISIS_tag_restore_file to restore the values of all tags that were previously saved in a file by a call to IG_ISIS_tag_save_file. Use this function to give the application the capability to restore the saved scanner settings.

By default, the settings file is read from the current Windows directory (for example, C:\WINDOWS.). Passing a full path name specification in lpszFileName overrides this default.

Example

The following call restores the settings previously saved by IG_ISIS_tag_save_file for the particular scanner whose driver is currently loaded:

IG_ISIS_tag_restore_file(hDriver, 0, "PIXVIEW.INI");

See Also

IG_ISIS_tag_save_file.


IG_ISIS_tag_restore_file_ex

Restore tag values from a function pointer.

Description

The IG_ISIS_tag_restore_file_ex function retrieves the stored values of all tags from a function pointer that can be used by a callback procedure. This allows an application to restore the values of all tags from an application-defined data object that was created by IG_ISIS_tag_save_file_ex.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_restore_file_ex(
    HISISDRV              hDriver,
    LPFNIG_ISIS_RESTOREEX lpfnCallback,
    LPSTR                 lpszFileName
    );

Parameters

hDriver
The handle to the driver.
lpfnCallback
Points to a callback function defined by the application.
lpszFileName
Specifies the name of the file or data object from which to restore the tag values. Passed directly to the callback.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_restore_file_ex to restore the values of all tags from a data object of the application's choice. This function accomplishes the same functionality as IG_ISIS_tag_restore_file except that rather than reading the tag values from a specified file, it sends a message to a callback function each time a value would otherwise be read from a file. Use this function together with a callback function to give the application the capability to restore the current scanner settings, after having used IG_ISIS_tag_save_file_ex to save the settings.

Example

The following code fragment defines a callback function:

LPFNIG_ISIS_RESTOREEX SampleRestoreCallback;
int PUBLIC_FUNC SampleRestoreCallback(char FAR *lpszSection,
    char FAR *lpszEntry, char FAR *lpszDefault, char FAR
    *lpszReturnBuffer, int cbReturnBuffer, char FAR
*lpszFileName);
{
    return GetPrivateProfileString(lpszSection, lpszEntry,
           lpszDefault, lpszReturnBuffer, cbReturnBuffer,
           lpszFileName);
}

The following code fragment defines a function that uses the callback:

int RestoreScanTags(hDriver, HWND hWnd, char FAR *lpszFileName)
{
    AT_ERRCOUNT nErrCount;
    nErrCount = IG_ISIS_tag_restore_file_ex(hDriver,
SampleRestoreCallback,
                                   lpszFileName);
    return nErrCount
};

Structures

The callback's prototype looks like this:

typedef INT (LPACCUAPI LPFNIG_ISIS_RESTOREEX)(
    LPSTR lpszSection,
    LPSTR lpszEntry,
    LPSTR lpszDefault,
    LPSTR lpszReturnBuffer,
    INT   nReturnBuffer,
    LPSTR lpszFileName
    );

See Also

IG_ISIS_tag_save_file_ex.


IG_ISIS_tag_restore_value

Restore tag value(s) saved by IG_ISIS_tag_save_value.

Description

The IG_ISIS_tag_restore_value function restores the values last saved by a IG_ISIS_tag_save_value call, allowing an application to implement cancel or undo functions in settings dialogs so that previous values can be restored.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_restore_value(
    HISISDRV hDriver,
    AT_MODE  nTag
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the tag to be restored. Specify a value of zero to restore all tags saved by a corresponding IG_ISIS_tag_save_value function.

Usage

Use IG_ISIS_tag_restore_value to restore settings to the value(s) that existed when the application issued the most current IG_ISIS_tag_save_value call. If you do not wish to restore settings, then you must call IG_ISIS_tag_flush_value instead. Each call to IG_ISIS_tag_save_value must have a corresponding call to either IG_ISIS_tag_restore_value or IG_ISIS_tag_flush_value. This is a relatively new requirement, as multiple settings can now be saved in a stack. Previously, only one group of settings could be saved at a time, so only one call to IG_ISIS_tag_restore_value or IG_ISIS_tag_flush_value was required.

The value of nTag should correspond to the value of nTag that was used when the corresponding IG_ISIS_tag_save_value was called. The values are saved in a last-in/first-out stack. By saving the settings of all tags multiple times, it is possible to implement a nested set of settings dialogs, one of which can be cancelled to restore original settings, even after accepting the settings in a previous one. (See IG_ISIS_tag_save_value for a complete example.)

Example

See the example for IG_ISIS_tag_flush_value.

See Also

IG_ISIS_tag_flush_value, IG_ISIS_tag_save_value.


IG_ISIS_tag_save_file

Save current tag values in a file.

Description

The IG_ISIS_tag_save_file function saves the current values of all tags in a specified file. This allows an application to implement a Save Settings function and then later restore settings using the IG_ISIS_tag_restore_file function. This function is only supported on Windows platforms.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_save_file(
    HISISDRV hDriver,
    LPSTR    lpszSection,
    LPSTR    lpszFileName
    );

Parameters

hDriver
The handle to the driver.
lpszSection
Specifies the name of the [Section] in which to save the current values of all tags. [Section] is a standard *.INI file section name of the application's choosing. The name specified will be automatically enclosed in square brackets-do not include them in the lpszSection string. Note that if lpszSection is zero, the name pointed to by hDriver will be used as the section name.
lpszFileName
Specifies the name of the file in which to save the current tag values. If lpszFileName is zero, the name SETSCAN.INI is used, but an application-specific filename is recommended.

Usage

Use IG_ISIS_tag_save_file to save the current values of all tags in a file. Use this function to give the application the capability to save the current scanner settings, then use IG_ISIS_tag_restore_file to restore the settings at a later time.

By default, the settings file is saved from the current Windows directory (for example, C:\WINDOWS.). Passing a full path name specification in lpszFileName overrides this default.

Example

The following call saves the current values of all tags in a section named for the particular scanner whose driver is currently loaded:

IG_ISIS_tag_save_file(hDriver, 0, "PIXVIEW.INI");

See Also

IG_ISIS_tag_restore_file.


IG_ISIS_tag_save_file_ex

Save current tag values to a function pointer.

Description

The IG_ISIS_tag_save_file_ex function outputs the current values of all tags to a function pointer that can be used by a callback procedure. This allows an application to save the values of all tags in an application-defined data object.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_save_file_ex(
    HISISDRV           hDriver,
    LPFNIG_ISIS_SAVEEX lpfnCallback,
    LPSTR              lpszFileName
    );

Parameters

hDriver
The handle to the driver.
lpfnCallback
Points to a callback function defined by the application.
lpszFileName
Specifies the name of the file or data object in which to save the current tag values. Passed directly to the callback.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_save_file_ex to save the current values of all tags in a data object of the application's choice. This function accomplishes the same functionality as IG_ISIS_tag_save_file except that rather than writing the tag values to a specified file, it sends a message to a callback function each time a value would otherwise be written to a file. Use this function together with a callback function to give the application the capability to save the current scanner settings, then use IG_ISIS_tag_restore_file_ex to restore the settings at a later time.

Example

The following code fragment defines a callback function:

LPFNIG_ISIS_SAVEEX SampleSaveCallback;
int SampleSaveCallback(char FAR *lpszSection, char FAR
    *lpszEntry, char FAR *lpszString, char FAR *lpszFileName);
{
    if ((WritePriveProfileString(lpszSection, lpszEntry,
lpszString,
        lpszFileName)
        return IGE_SUCCESS;
    else
        return IGE_ERROR;
}

The following code fragment defines a function that uses the callback:

int SaveScanTags(hDriver, HWND hWnd, char FAR *lpszFileName)
{
    AT_ERRCOUNT nErrCount;
    if (hDriver) {
        nErrCount = IG_ISIS_tag_save_file_ex(hDriver,
SampleSaveCallback,
                                   lpszFileName);
    }
    return nErrCount;
}

Structures

The callback's prototype looks like this:

typedef INT (LPACCUAPI LPFNIG_ISIS_SAVEEX)(
    LPSTR lpszSection,
    LPSTR lpszEntry,
    LPSTR lpszString,
    LPSTR lpszFileName
    );

See Also

IG_ISIS_tag_restore_file_ex.


IG_ISIS_tag_save_value

Save current tag value(s) in memory.

Description

The IG_ISIS_tag_save_value function saves the value of a specified tag, or the values of all tags, in a last-in/first-out stack in memory, allowing an application to implement cancel or undo functions in settings dialogs so that previous values can be restored.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_save_value(
    HISISDRV hDriver,
    AT_MODE  nTag
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies that tag whose value is to be saved. Specify a value of zero to save all tags.

Usage

Use IG_ISIS_tag_save_value to save the values of the specified nTag or of all tags (by setting nTag to zero). It is strongly recommended that all calls to IG_ISIS_tag_save_value use a tag value of zero for consistency. Each IG_ISIS_tag_save_value call must have a corresponding call to either IG_ISIS_tag_flush_value or IG_ISIS_tag_restore_value.

Generally, call IG_ISIS_tag_save_value before offering the user the opportunity to change the values of tags (for example, when displaying a Scanner Settings dialog box). The user can either confirm the settings (click OK) or revert to the previous settings (click Cancel). If the user confirms the settings, call IG_ISIS_tag_flush_value to discard the saved settings and free the memory they occupied. If the user wants to revert to the previous settings, call IG_ISIS_tag_restore_value to restore the saved settings to their previous values and free the memory they occupied.

Multiple saves are possible, to support the implementation of multi-level undo or nested settings dialogs. Call IG_ISIS_tag_save_value before presenting each new dialog. In the example illustrated below, IG_ISIS_tag_save_value is called a second time when the user clicks the Next button, storing a second set of saved values on the stack. If the user clicks OK in the Next Settings dialog, the settings values saved when the Next Settings dialog was spawned are restored and the corresponding saved values flushed (but the first set of values saved are still on the stack). If the user clicks Cancel, the settings that were in effect when the Next Settings dialog was spawned are restored. Once back at the original Settings dialog, clicking OK saves whatever settings are in effect at that moment, flushing the first values that were saved on the stack. Clicking Cancel restores all previous settings that were in effect before the user took any action (because the settings that are restored at this point are the ones that were saved before any action was taken in the Next Settings dialog).

NOTE: This function is included to allow application developers to implement their own multi-level settings dialogs. The Scanner Settings and More Settings dialogs that are built-into the toolkit and many ISIS drivers implement this functionality automatically and do not require the use of this function.

Example

IG_ISIS_tag_save_value(hDriver, 0);	/*One group of settings on
stack	*/
IG_ISIS_tag_restore_value(hDriver, 0);	/* No settings saved			 */
IG_ISIS_tag_save_value(hDriver, 0); 	/* One group of settings on
stack	*/
IG_ISIS_tag_save_value(hDriver, 0); 	/* Two groups of settings
on stack	*/
IG_ISIS_tag_save_value(hDriver, 0); 	/* Three group of settings
on stack	 */
IG_ISIS_tag_restore_value(hDriver, 0);	/* Two groups of settings
on stack	*/
IG_ISIS_tag_flush_value(hDriver, 0);	/* One group of settings on
stack				 */
IG_ISIS_tag_restore_value(hDriver, 0);	/* No settings saved			 */

See Also

IG_ISIS_tag_flush_value, IG_ISIS_tag_restore_value.


IG_ISIS_tag_set_ascii

Set the value of an ASCII tag.

Description

The IG_ISIS_tag_set_ascii function sets the value of the specified ASCII tag to the specified string.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_set_ascii(
    HISISDRV hDriver,
    AT_MODE  nTag,
    LPSTR    lpszValue
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the ASCII tag to set.
lpszValue
Points to a buffer that contains the string to which to set nTag.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_set_ascii to set the specified nTag to the ASCII string in lpcBuffer. IG_ISIS_tag_set_ascii automatically sets the tag's length.

Example

The following example gets the ASCII value of the choice for IG_ISIS_TAG_DITHER whose index value is 2 (the third choice), and then sets this tag to that value:

IG_ISIS_choice_get_ascii(hDriver, IG_ISIS_TAG_DITHER, 2,
caBuffer);
IG_ISIS_tag_set_ascii(hDriver, IG_ISIS_TAG_DITHER, caBuffer);

See Also

IG_ISIS_tag_get_ascii, IG_ISIS_tag_set_default, IG_ISIS_tag_set_long, IG_ISIS_tag_set_rational.


IG_ISIS_tag_set_default

Set a tag to its default value.

Description

The IG_ISIS_tag_set_default function resets the specified tag to its default value. It does not set a new default value.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_set_default(
    HISISDRV hDriver,
    AT_MODE  nTag
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the tag to reset.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_set_default to set the specified nTag to the default value that was assigned to it in the driver. The default value is set by the driver developer by the first IG_ISIS_tag_set... call for each tag that is created in the driver. The application has no way to reset or change these defaults.

Example

The following line of code resets all tags to their default values:

IG_ISIS_tag_set_default(hDriver, 0);

See Also

IG_ISIS_tag_get_ascii_default, IG_ISIS_tag_get_length_default, IG_ISIS_tag_get_long_default, IG_ISIS_tag_get_rational_default, IG_ISIS_tag_set_ascii, IG_ISIS_tag_set_long, IG_ISIS_tag_set_rational, .


IG_ISIS_tag_set_length

Set the number of elements in a tag.

Description

The IG_ISIS_tag_set_length function sets the number of elements in the specified tag. Most integer and rational tags have only one element and do not need their lengths set. The length of an ASCII tag is set automatically and does not need its length explicitly set.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_set_length(
    HISISDRV hDriver,
    AT_MODE  nTag,
    DWORD    dwLength
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the tag to set.
dwLength
Specifies the number of elements for nTag. (Default is 1.)

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_set_length to set the number of elements in the specified nTag to a value other than 1. An example of a multiple-element tag is IG_ISIS_TAG_GAMMA_TABLE1, which often requires a table of 256 values for each possible setting.

Do not use IG_ISIS_tag_set_length for ASCII tags-their length is set automatically when IG_ISIS_tag_set_ascii is called.

The IG_ISIS_tag_set_length function is most commonly used to set the sizes of dithers and gammas on scanners.

Example

The following example defines a function in a driver for setting gamma tables. It uses IG_ISIS_tag_set_length to set the number of elements in the resulting gamma table.

void SetGammaTable (
  HISISDRV					hDriver,
  LONG					lLength,
  BYTE					FAR *lpGammaBuffer)
  {
  IG_ISIS_tag_set_long (hDriver, IG_ISIS_TAG_GAMMA_LENGTH1, 0,
lLength) ;
  IG_ISIS_tag_set_long (hDriver, IG_ISIS_TAG_GAMMA_TABLE1, 0, 0)
;
  IG_ISIS_tag_set_length (hDriver, IG_ISIS_TAG_GAMMA_TABLE1, lLength)
;
  while (lLength--)
    IG_ISIS_tag_set_long (hDriver, IG_ISIS_TAG_GAMMA_TABLE1,
lLength,
                   (LONG) lpGammaBuffer[lLength]) ;
  }

See Also

IG_ISIS_tag_get_length, IG_ISIS_tag_get_length_default.


IG_ISIS_tag_set_long

Set the value of a type long tag.

Description

The IG_ISIS_tag_set_long function sets the value of the specified integer tag's specified element to the given value.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_set_long(
    HISISDRV hDriver,
    AT_MODE  nTag,
    WORD     wIndex,
    LONG     lValue
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the type long tag to set.
wIndex
Specifies which element to set. wIndex must be greater than or equal to zero and at most one less than the value returned by IG_ISIS_tag_get_length.
lValue
Specifies the value to which to set nTag's specified element.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_set_long to set the specified element of nTag to the value given in lValue. This function is used to set byte, short, and long values. IG_ISIS_tag_set_long will not automatically increase the number of elements in a tag. You must use IG_ISIS_tag_set_length before calling IG_ISIS_tag_set_long to do this.

Example

See example for IG_ISIS_tag_set_length.

See Also

IG_ISIS_tag_get_long, IG_ISIS_tag_set_ascii, IG_ISIS_tag_set_default, IG_ISIS_tag_set_length, IG_ISIS_tag_set_rational.


IG_ISIS_tag_set_rational

Set the value of a type rational tag.

Description

The IG_ISIS_tag_set_rational function sets the value of the specified type rational tag's specified element to the given value.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_tag_set_rational(
    HISISDRV      hDriver,
    AT_MODE       nTag,
    WORD          wIndex,
    LPAT_ISIS_RAT lpValue
    );

Parameters

hDriver
The handle to the driver.
nTag
Specifies the type rational tag to set.
wIndex
Specifies which element to set. wIndex must be greater than or equal to zero and at most one less than the value returned by IG_ISIS_tag_get_length.
lpValue
Specifies the value to which to set nTag's specified element.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_tag_set_rational to set the specified element of nTag to the rational value given in lpValue. IG_ISIS_tag_set_rational will not automatically increase the number of elements in a tag. You must use IG_ISIS_tag_set_length before calling IG_ISIS_tag_set_rational to do this.

Example

The following example sets the rational value of IG_ISIS_TAG_RESOLUTION:

AT_ISIS_RAT ratValue;
ratValue.Num = 300;
ratValue.Denom = 1;
IG_ISIS_tag_set_rational(hDriver, IG_ISIS_TAG_XRESOLUTION, 0,
&ratValue);

See Also

IG_ISIS_tag_get_rational, IG_ISIS_tag_set_ascii, IG_ISIS_tag_set_default, IG_ISIS_tag_set_length, IG_ISIS_tag_set_long.


Install Driver Functions

IG_ISIS_install_driver

Installs a scanner driver.

Description

IG_ISIS_install_driver installs a scanner driver and any files the driver may need.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_install_driver(
    HWND  hWnd,
    LPSTR lpszDriver,
    LPSTR lpszScanner
    );

Parameters

hWnd
Sets the parent window for any dialogs that will be displayed.
lpszDriver
Specifies the path to the scanner driver.
lpszScanner
(Optional) The name of the scanner being used.

Usage

Use IG_ISIS_install_driver to install a scanner driver and any files that driver needs. If you want more control, use IG_ISIS_install_driver_init, IG_ISIS_install_driver_step and IG_ISIS_install_driver_done.

See Also

IG_ISIS_install_driver_init

IG_ISIS_install_driver_step

IG_ISIS_install_driver_done

IG_ISIS_install_driver_set_long

IG_ISIS_install_driver_get_long

IG_ISIS_install_driver_set_ascii

IG_ISIS_install_driver_get_ascii


IG_ISIS_install_driver_done

Cleans up the driver installation.

Description

IG_ISIS_install_driver_done frees the IG_ISIS_install_driver handle and all memory associated with it.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_install_driver_done(
    HISISINSTALLDRV hInstall
    );

Parameters

hInstall
Cleans up the driver installation.

Usage

Use IG_ISIS_install_driver_done along with IG_ISIS_install_driver_init and IG_ISIS_install_driver_step when you want more control over the driver installation process. Call IG_ISIS_install_driver_set_long and IG_ISIS_install_driver_set_ascii to set up parameters of the installation.

See Also

IG_ISIS_install_driver

IG_ISIS_install_driver_init

IG_ISIS_install_driver_step

IG_ISIS_install_driver_set_long

IG_ISIS_install_driver_get_long

IG_ISIS_install_driver_set_ascii

IG_ISIS_install_driver_get_ascii


IG_ISIS_install_driver_init

Returns a IG_ISIS_install_driver handle.

Description

IG_ISIS_install_driver_init returns a IG_ISIS_install_driver handle for the installation of the driver at the path specified in szDriver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_install_driver_init(
    LPHISISINSTALLDRV lphInstall,
    LPSTR             lpszDriver
    );

Parameters

lphInstall
Returns an IG_ISIS_install_driver handle for the installation of the driver at the path specified in lpszDriver.
lpszDriver
Specifies the path to the scanner driver.

Usage

Use IG_ISIS_install_driver_init along with IG_ISIS_install_driver_step and IG_ISIS_install_driver_done when you want more control over the driver installation process. Call IG_ISIS_install_driver_set_long and IG_ISIS_install_driver_set_ascii to set up parameters of the installation.

See Also

IG_ISIS_install_driver

IG_ISIS_install_driver_step

IG_ISIS_install_driver_done

IG_ISIS_install_driver_set_long

IG_ISIS_install_driver_get_long

IG_ISIS_install_driver_set_ascii

IG_ISIS_install_driver_get_ascii


IG_ISIS_install_driver_get_ascii

Get the current value of an ASCII tag.

Description

The IG_ISIS_install_driver_get_ascii function retrieves the ASCII string that is the current value of the specified tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_install_driver_get_ascii(
    HISISINSTALLDRV hInstall,
    AT_LMODE        lTag,
    LPSTR           lpszValue,
    DWORD           dwSize
    );

Parameters

hInstall
Gets the current value of the specified tag.
lTag
Specifies the ASCII tag to get.
lpszValue
Points to a buffer to hold the result.
dwSize
Specifies the size of the buffer in characters.

Usage

Use IG_ISIS_install_driver_get_ascii to retrieve the ASCII string of any of the following tags:

Tag Name
Description
IG_ISIS_INSTDRIV_SCANNER
Get the name of the scanner being installed.
IG_ISIS_INSTDRIV_TITLE
Get the title to use on dialogs during user interaction.
IG_ISIS_INSTDRIV_YESNO_MSG
Get the question to ask for the current YESNO request.
IG_ISIS_INSTDRIV_SHOWMSG_MSG
Get the message to display for the current SHOWMSG request.
IG_ISIS_INSTDRIV_ASKSTRING_MSG
Get the question to ask for the current ASKSTRING request.
IG_ISIS_INSTDRIV_ASKSTRING_DEFAULT
Get the default answer for the current ASKSTRING request.
IG_ISIS_INSTDRIV_ASKSTRING_ANSWER
Get the answer to the current ASKSTRING request.

See Also

IG_ISIS_install_driver

IG_ISIS_install_driver_init

IG_ISIS_install_driver_step

IG_ISIS_install_driver_done

IG_ISIS_install_driver_get_long

IG_ISIS_install_driver_set_long

IG_ISIS_install_driver_set_ascii


IG_ISIS_install_driver_get_long

Gets information needed to install the scanner.

Description

The IG_ISIS_install_driver_get_long function retrieves the long value that is the current value of the specified tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_install_driver_get_long(
    HISISINSTALLDRV hInstall,
    AT_LMODE        lTag,
    LPLONG          lplValue
    );

Parameters

hInstall
Gets the value of the specified tag.
lTag
Specifies the tag to assign a value.
lplValue
Returns the tag's assigned value.

Usage

Use IG_ISIS_install_driver_get_long when you want to retrieve information using the following tags:

Tag Name
Type
Description
IG_ISIS_INSTDRIV_REQUEST
Long
Get this value when IG_ISIS_install_driver_step returned IG_ISIS_INSTDRIV_NEEDINFO to find out what type of user interaction is needed.
IG_ISIS_INSTDRIV_PARENTWINDOW
HWND
Retrieve the parent window.
IG_ISIS_INSTDRIV_DEFAULTSCANNER
Boolean
Return the value that specifies if this scanner is going to be set up as the default scanner.
IG_ISIS_INSTDRIV_ANSWERED
Boolean
Return the value that specifies if this NEEDINFO has been answered.
IG_ISIS_INSTDRIV_YESNO_DEFAULT
Boolean
Return the default answer for the current YESNO request.
IG_ISIS_INSTDRIV_YESNO_ANSWER
Boolean
Return the answer for the current YESNO request.
IG_ISIS_INSTDRIV_ASKSTRING_NEEDDIR
Boolean
Returns a value that specifies if the current ASKSTRING request needs a directory name as the answer.

See Also

IG_ISIS_install_driver

IG_ISIS_install_driver_init

IG_ISIS_install_driver_step

IG_ISIS_install_driver_done

IG_ISIS_install_driver_set_long

IG_ISIS_install_driver_set_ascii

IG_ISIS_install_driver_get_ascii


IG_ISIS_install_driver_set_ascii

Set the value of an ASCII tag.

Description

The IG_ISIS_install_driver_set_ascii function sets the value of the specified ASCII tag to the specified string.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_install_driver_set_ascii(
    HISISINSTALLDRV hInstall,
    AT_LMODE        lTag,
    LPSTR           lpszValue
    );

Parameters

hInstall
Sets the value of the specified tag.
lTag
Specifies the ASCII tag to set.
lpszValue
Specifies the value to assign the specified tag.

Usage

Use IG_ISIS_install_driver_set_ascii to set any of the following tags to the ASCII string:

Tag Name
Description
IG_ISIS_INSTDRIV_SCANNER
Set the name of the scanner being installed.
IG_ISIS_INSTDRIV_ASKSTRING_ANSWER
Set the answer to the current ASKSTRING request.

See Also

IG_ISIS_install_driver

IG_ISIS_install_driver_init

IG_ISIS_install_driver_step

IG_ISIS_install_driver_done

IG_ISIS_install_driver_get_long

IG_ISIS_install_driver_set_long

IG_ISIS_install_driver_get_ascii


IG_ISIS_install_driver_set_long

Sets information used to install a scanner driver.

Description

IG_ISIS_install_driver_set_long is used to set the value of the specified tag.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_install_driver_set_long(
    HISISINSTALLDRV hInstall,
    AT_LMODE        lTag,
    LONG            lValue
    );

Parameters

hInstall
Sets the value of the specified tag.
lTag
Specifies the tag to assign a value.
lValue
Specifies the value to which to set the tag.

Usage

Use IG_ISIS_install_driver_set_long when you need to set the value of the following tags:

Tag Name
Type
Description
IG_ISIS_INSTDRIV_PARENTWINDOW
HWND
Set the parent window for dialogs.
IG_ISIS_INSTDRIV_DEFAULTSCANNER
Boolean
Set whether the scanner should be set as the default scanner.
IG_ISIS_INSTDRIV_ANSWERED
Boolean
Set to TRUE after you have set your answer to a request returned with IG_ISIS_INSTDRIV_NEEDINFO.
IG_ISIS_INSTDRIV_YESNO_ANSWER
Boolean
Set this when answering a IG_ISIS_INSTDRIV_NEEDINFO of type IG_ISIS_INSTDRIV_REQ_YESNO.

See Also

IG_ISIS_install_driver

IG_ISIS_install_driver_init

IG_ISIS_install_driver_step

IG_ISIS_install_driver_done

IG_ISIS_install_driver_get_long

IG_ISIS_install_driver_set_ascii

IG_ISIS_install_driver_get_ascii


IG_ISIS_install_driver_step

Performs the next step of the installation.

Description

IG_ISIS_install_driver_step allows you to step through the installation process and provide options for user input.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_install_driver_step(
    HISISINSTALLDRV hInstall
    );

Parameters

hInstall
Performs the next step of the installation.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_install_driver_step along with IG_ISIS_install_driver_init and IG_ISIS_install_driver_done when you want more control over the driver installation process. Call IG_ISIS_install_driver_set_long and IG_ISIS_install_driver_set_ascii to set up parameters of the installation.

Example

while ((r = IG_ISIS_install_driver_step (hInstall)) > 0) {
    if (r == IG_ISIS_INSTDRIV_NEEDINFO) {
        ShowUI (hInstall);
    }
}

See Also

IG_ISIS_install_driver

IG_ISIS_install_driver_init

IG_ISIS_install_driver_done

IG_ISIS_install_driver_set_long

IG_ISIS_install_driver_get_long

IG_ISIS_install_driver_set_ascii

IG_ISIS_install_driver_get_ascii


Custom Scanner Functions

IG_ISIS_selection_add_scanner

Copy a driver file from a supplemental location and add it to the list in the ISISSELECTION structure.

Description

The IG_ISIS_selection_add_scanner function copies the driver file specified in driverInfo into the standard system directory and add the driver to the ISISSELECTION.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_selection_add_scanner(
    LPHISISSEL           lphSelectionDestination,
    LPAT_ISIS_DRIVERINFO lpDriverInfo,
    AT_BOOL              bForceInstall
    );

Parameters

lphSelectionDestination
The ISISSELECTION structure as initialized by IG_ISIS_selection_init. The ISISSELECTION must have been initialized with its iSelectionType set to ISISSELECTION_MAINLIST.
lpDriverInfo
Points to a scanner information record obtained by calling IG_ISIS_selection_get_driver_info.
bForceInstall
If this value is set to FALSE, then the driver file will only be copied if it is newer than the existing driver in the standard directory or if there is no existing driver. Otherwise, the driver file will be copied even if it will overwrite a newer version.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use IG_ISIS_selection_add_scanner to install a scanner driver from a non-system directory. First, create a source ISISSELECTION structure by calling IG_ISIS_selection_init with the path to the supplemental directory and with iSelectionType set to IG_ISIS_SELECTION_ADDLIST. Then use IG_ISIS_selection_get_driver_info to retrieve the selected scanner information record from the source ISISSELECTION and pass it to IG_ISIS_selection_add_scanner.

See Also

IG_ISIS_selection_init, IG_ISIS_selection_get_driver_info.


IG_ISIS_selection_build

Create a list of drivers in the ISISSELECTION.

Description

The IG_ISIS_selection_build function adds one driver to the ISISSELECTION structure each time it is called.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_selection_build(
    LPHISISSEL lphSelection,
    LPSTR lpszDriverName,
    DWORD dwDriverNameLen
    );

Parameters

lphSelection
The ISISSELECTION structure as initialized by IG_ISIS_selection_init.
lpszDriverName
Specifies a buffer for storing the name (including the full path) of the current driver.
dwDriverNameLen
The size of the name buffer. It is recommended that you use a buffer of size _MAX_PATH from stdlib.h.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

The IG_ISIS_selection_build function adds one driver to the ISISSELECTION at a time and should be called repeatedly until it returns a positive value. A return value of IGE_SUCCESS indicates more drivers still need to be added. It is recommended that your application display a progress monitor between each call to IG_ISIS_selection_build. The name of the current driver being added is available from DrvName.

See Also

IG_ISIS_selection_init.


IG_ISIS_selection_choose_driver

Write the selected scanner/driver combination to the scanner setup file.

Description

The IG_ISIS_selection_choose_driver function writes the scanner model name and driver name obtained from the specified scanner information record to setscan.ini.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_selection_choose_driver(
    LPHISISSEL           lphSelection,
    LPAT_ISIS_DRIVERINFO lpDriverInfo
    );

Parameters

lphSelection
The ISISSELECTION structure as initialized by IG_ISIS_selection_init.
lpDriverInfo
Points to a scanner information record obtained by calling IG_ISIS_selection_get_driver_info.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use the IG_ISIS_selection_choose_driver function to fill in the "Driver =" and "Model = " entries in setscan.ini. Then call IG_ISIS_selection_configure to perform any necessary setup on the selected scanner.

See Also

IG_ISIS_selection_get_driver_info, IG_ISIS_selection_configure.


IG_ISIS_selection_configure

Configure a scanner/driver combination given a scanner information record.

Description

The IG_ISIS_selection_configure function loads the driver from the specified scaner information record, calls IG_ISIS_drv_configure on it to display the driver configuration dialog, then unloads the driver.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_selection_configure(
    LPHISISSEL           lphSelection,
    LPAT_ISIS_DRIVERINFO lpDriverInfo,
    HWND                 hWndParent,
    AT_BOOL              bOnlyIfNecessary
    );

Parameters

lphSelection
Points to the ISISSELECTION structure as initialized by IG_ISIS_selection_init.
lpDriverInfo
Points to a scanner information record obtained by calling IG_ISIS_selection_get_driver_info.
hWndParent
Handle to the parent window (provided for handling dialogs that may pop up).
bOnlyIfNecessary
If this value is set to TRUE, then IG_ISIS_drv_configure will only be called if the specified scanner/driver combination has not yet been set up. Otherwise, IG_ISIS_drv_configure will always be called even if no further configuration is necessary.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

Use the IG_ISIS_selection_configure function to perform any necessary driver setup and configuration once the user has selected a scanner.

See Also

IG_ISIS_selection_get_driver_info, IG_ISIS_drv_configure.


IG_ISIS_selection_done

Release memory used by the specified ISISSELECTION structure.

Description

The IG_ISIS_selection_done function frees the members in the internal driver list allocated by IG_ISIS_selection_init and clears the specified ISISSELECTION structure.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_selection_done(
    LPHISISSEL lphSelection
    );

Parameters

lphSelection
Points to the ISISSELECTION structure to be cleared as initialized by IG_ISIS_selection_init.

Usage

Each call to the IG_ISIS_selection_init function should correspond with a IG_ISIS_selection_done call.

See Also

IG_ISIS_selection_init.


IG_ISIS_selection_get_driver_info

Look up information about a driver in the ISISSELECTION based on the scanner ID.

Description

The IG_ISIS_selection_get_driver_info function retrieves the AT_ISIS_DRIVERINFO structure from the ISISSELECTION using a scanner entry's ID.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_selection_get_driver_info(
    LPHISISSEL           lphSelection,
    INT                  nId,
    LPAT_ISIS_DRIVERINFO lpDriverInfo
    );

Parameters

lphSelection
Points to the ISISSELECTION structure as initialized by IG_ISIS_selection_init.
nId
Specifies the ID for the scanner.
lpDriverInfo
Points to the driver information record associated with nId.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

If your application keeps track of the association between the name of each scanner and its ID as they are returned from your calls to IG_ISIS_selection_iterate_init and IG_ISIS_selection_iterate_next, then you can use IG_ISIS_selection_get_driver_info to look up the driver record for a particular scanner after the user selects a scanner from the selection dialog.

See Also

IG_ISIS_selection_iterate_init, IG_ISIS_selection_iterate_next.


IG_ISIS_selection_init

Initialize a ISISSELECTION structure.

Description

The IG_ISIS_selection_init function initializes a ISISSELECTION structure for use by other IG_ISIS_selection... functions and counts the number of drivers in the specified directory.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_selection_init(
    LPHISISSEL lphSelection,
    AT_MODE    nSelectionType,
    LPSTR      lpszDirectory
    );

Parameters

lphSelection
The ISISSELECTION structure to be initialized.
nSelectionType
Specifies the type of desired ISISSELECTION structure. Set nSelectionType to ISISSELECTION_MAINLIST if you are accessing drivers from the standard driver directories (<WINDIR> and <WINDIR>\PIXTRAN). Set nSelectionType to ISISSELECTION_ADDLIST if you are adding drivers from a supplemental directory specified by Directory.
lpszDirectory
Specifies the path to the supplemental driver directory if nSelectionType is set to ISISSELECTION_ADDLIST. Otherwise NULL.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

You must initialize a new ISISSELECTION structure for each set of drivers before using any other IG_ISIS_selection... function. Once your ISISSELECTION structure has been initialized, call IG_ISIS_selection_build to populate the structure with an internal list of drivers found in the specified directory.

See Also

IG_ISIS_selection_build, IG_ISIS_selection_done.


IG_ISIS_selection_iterate_done

Release memory used by the specified driver iteration cycle.

Description

The IG_ISIS_selection_iterate_done function releases the memory allocated by IG_ISIS_selection_iterate_init and frees the pointer to the iteration cycle.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_selection_iterate_done(
    LPHISISSELITER lphIteration
    );

Parameters

lphIteration
Points to the driver iteration cycle as initialized by IG_ISIS_selection_iterate_init.

Usage

Call IG_ISIS_selection_iterate_done after you finish retrieving all the scanner information records in the driver iteration cycle or if either IG_ISIS_selection_iterate_init or IG_ISIS_selection_iterate_next returns an error.

See Also

IG_ISIS_selection_iterate_init, IG_ISIS_selection_iterate_next.


IG_ISIS_selection_iterate_init

Initialize the driver iteration cycle to obtain scanner information from a ISISSELECTION structure.

Description

The IG_ISIS_selection_iterate_init function starts the iteration cycle and fills in the first scanner information record.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_selection_iterate_init(
    LPHISISSEL           lphSelection,
    LPHISISSELITER       lphIteration,
    LPAT_ISIS_DRIVERINFO lpDriverInfo
    );

Parameters

lphSelection
Points to the ISISSELECTION structure as initialized by IG_ISIS_selection_init.
lphIteration
Specifies the driver iteration cycle to initialize.
lpDriverInfo
Points to the first scanner information record obtained from the iteration cycle.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

The IG_ISIS_selection_iterate_init and IG_ISIS_selection_iterate_next functions go through the drivers in the mySelection list to obtain information on all scanner models supported by those drivers. Each AT_ISIS_DRIVERINFO structure returned in driverInfo contains the model name of the scanner, its associated driver, and a unique ID. Your application can then present a list of all the supported scanner models to the user. If you keep track of the association between the scanner name and its ID, you can then use the IG_ISIS_selection_get_driver_info function to retrieve the scanner information record after the user selects a scanner.

You should call IG_ISIS_selection_iterate_next repeatedly until all the records have been found. Then call IG_ISIS_selection_iterate_done to release the memory allocated for the iteration cycle.

See Also

IG_ISIS_selection_iterate_next, IG_ISIS_selection_iterate_done, IG_ISIS_selection_get_driver_info.


IG_ISIS_selection_iterate_next

Obtain the next scanner information record in the iteration cycle started by IG_ISIS_selection_iterate_init.

Description

The IG_ISIS_selection_iterate_next function obtains the next record in the driver iteration cycle. It should be called repeatedly until all the records have been retrieved.

Syntax

AT_ERRCOUNT ACCUAPI IG_ISIS_selection_iterate_next(
    LPHISISSELITER       lphIteration,
    LPAT_ISIS_DRIVERINFO lpDriverInfo
    );

Parameters

lphIteration
Points to the driver iteration cycle as initialized by IG_ISIS_selection_iterate_init.
lpDriverInfo
Points to the next scanner information record obtained from the iteration cycle.

Returns

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Usage

The IG_ISIS_selection_iterate_init and IG_ISIS_selection_iterate_next functions go through the driver iteration cycle to obtain information on all scanner models supported by those drivers. Each AT_ISIS_DRIVERINFO structure returned in driverInfo contains the model name of the scanner, its associated driver, and a unique ID. Your application can then present a list of all the supported scanner models to the user. If you keep track of the association between the scanner name and its ID, you can then use the IG_ISIS_selection_get_driver_info function to retrieve the scanner information record after the user selects a scanner.

You should call IG_ISIS_selection_iterate_next repeatedly until all the records have been found. Then call IG_ISIS_selection_iterate_done to release the memory allocated for the iteration cycle.

See Also

IG_ISIS_selection_iterate_init, IG_ISIS_selection_iterate_done, IG_ISIS_selection_get_driver_info.


Tags

There are the following groups of tags in the ImageGear ISIS component:

  • Barcode Detection Tags
  • Custom Dialog Box Tags
  • Custom Tag Tags
  • Data Format Tags
  • Image Interpretation Tags
  • Image Quality Tags
  • Miscellaneous Tags
  • Other Dialog Box Tags
  • Position and Resolution Tags
  • Scanning Mode Tags


Barcode Detection Tags

There are the following Barcode Detection tags:

  • IG_ISIS_TAG_BAR_AUTOREADBACK
  • IG_ISIS_TAG_BAR_AUTOREADFRONT
  • IG_ISIS_TAG_BAR_TYPE
  • IG_ISIS_TAG_BAR_TYPECOUNT
  • IG_ISIS_TAG_BARCODE
  • IG_ISIS_TAG_BARDATA_TEXT
  • IG_ISIS_TAG_BARDATA_TYPE
  • IG_ISIS_TAG_BARDATA_XPOSITION
  • IG_ISIS_TAG_BARDATA_YPOSITION


IG_ISIS_TAG_BAR_AUTOREADBACK

Status of barcode detection on back side pages in a duplex scan. 0x06C1 · 1729

Category: ISIS, Optional.

Description

IG_ISIS_TAG_BAR_AUTOREADBACK allows an application to automatically search for barcode data on the back side of a duplex scan.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Some drivers for scanners that support barcode detection.

Values

Value
Defined Constant
Meaning
0
IG_ISIS_BAR_AUTOREADBACK_OFF
Do not automatically search for barcodes on the back side.
1
IG_ISIS_BAR_AUTOREADBACK_ON
Automatically search for barcodes on the back side.

Usage

Use IG_ISIS_TAG_BAR_AUTOREADBACK to enable automatic barcode search on back sides of a duplex scan using the current barcode search parameters. The search is done after each image is read and before the driver returns IG_ISIS_ERR_ENDZONE. If the driver supports this tag and you choose not to enable automatic search, then you need to call IG_ISIS_drv_send with the message IG_ISIS_DRV_READBARDATA when you want to search a particular page for barcode information. If the driver supports barcode detection but does not support this tag specifically, then automatic search is always enabled.

See Also

IG_ISIS_TAG_BARCODE, IG_ISIS_TAG_BAR_AUTOREADFRONT.


IG_ISIS_TAG_BAR_AUTOREADFRONT

Status of barcode detection on front side pages in a duplex scan. 0x06C0 · 1728

Category: ISIS, Optional.

Description

IG_ISIS_TAG_BAR_AUTOREADFRONT allows an application to automatically search for barcode data on the front side of a duplex scan.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Some drivers for scanners that support barcode detection.

Values

Value
Defined Constant
Meaning
0
IG_ISIS_BAR_AUTOREADFRONT_OFF
Do not automatically search for barcodes on the front side.
1
IG_ISIS_BAR_AUTOREADFRONT_ON
Automatically search for barcodes on the front side.

Usage

Use IG_ISIS_TAG_BAR_AUTOREADFRONT to enable automatic barcode search on front sides of a duplex scan using the current barcode search parameters. The search is done after each image is read and before the driver returns IG_ISIS_ERR_ENDZONE. If the driver supports this tag and you choose not to enable automatic search, then you need to call IG_ISIS_drv_send with the message IG_ISIS_DRV_READBARDATA when you want to search a particular page for barcode information. If the driver supports barcode detection but does not support this tag specifically, then automatic search is always enabled.

See Also

IG_ISIS_TAG_BARCODE, IG_ISIS_TAG_BAR_AUTOREADBACK.


IG_ISIS_TAG_BAR_TYPE

Type of barcode to search. 0x069C · 1692

Category: ISIS, Optional.

Description

IG_ISIS_TAG_BAR_TYPE specifies the type or types or barcodes to search for on a page.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support barcode detection.

Values

These are all the possible values for IG_ISIS_TAG_BAR_TYPE, but the actual barcode types that can be detected will depend on your scanner. Use IG_ISIS_choice_get_long on IG_ISIS_TAG_BAR_TYPE to query the barcode types available on your scanner.

Value
Defined Constant
Barcode Type
0
IG_ISIS_BAR_TYPE_NONE
No barcode.
1
IG_ISIS_BAR_TYPE_EAN8
Type EAN-8.
2
IG_ISIS_BAR_TYPE_EAN13
Type EAN-13.
3
IG_ISIS_BAR_TYPE_CODE39
Type CODE 39
4
IG_ISIS_BAR_TYPE_CODE25_INTERLEAVED
CODE 2/5 interleaved.
5
IG_ISIS_BAR_TYPE_CODE25_MATRIX
CODE 2/5 3 lines (matrix).
6
IG_ISIS_BAR_TYPE_CODE25_DATALOGIC
CODE 2/5 3 lines (datalogic).
7
IG_ISIS_BAR_TYPE_CODE25_INDUSTRIAL
CODE 2/5 5 lines (industrial).
8
IG_ISIS_BAR_TYPE_PATCHCODE
Patch Code Type II, III or Transfer.
9
IG_ISIS_BAR_TYPE_PATCHCODE_II
Patch Code Type II.
10
IG_ISIS_BAR_TYPE_PATCHCODE_III
Patch Code Type III.
11
IG_ISIS_BAR_TYPE_PATCH_TRANSFER
Transfer Patch Code
12
IG_ISIS_BAR_TYPE_CODABAR
Codabar barcode.
13
IG_ISIS_BAR_TYPE_UPC_E
UPC code revision E.
14
IG_ISIS_BAR_TYPE_CODE93
Type CODE 93.
15
IG_ISIS_BAR_TYPE_128
Type 128.
16
IG_ISIS_BAR_TYPE_POSTNET
Postnet.
17
IG_ISIS_BAR_TYPE_CODE25_AIRLINE
CODE 2/5 (airline).
18
IG_ISIS_BAR_TYPE_UPC_A
UPC code revision A.
19
IG_ISIS_BAR_TYPE_MICR_E13B
Check MICR E13B type.
20
IG_ISIS_BAR_TYPE_MICR_CMC7
Check MICR CMC7 type.
21
IG_ISIS_BAR_TYPE_ADDON2
ADDON2.
22
IG_ISIS_BAR_TYPE_ADDON5
ADDON5.
23
IG_ISIS_BAR_TYPE_AUTO
Auto detect any available barcode.

Usage

IG_ISIS_TAG_BAR_TYPE is an indexed tag. It contains a list of one or more values accessible through an index. Use IG_ISIS_TAG_BAR_TYPECOUNT to specify the number of barcode types you wish to search for from the list in IG_ISIS_TAG_BAR_TYPE.

Example

The following example shows how to tell the scanner to search for CODE 39 and Codabar barcodes:

/* set CODE 39 and Codeabar to be indices for
IG_ISIS_TAG_BAR_TYPE */
IG_ISIS_tag_set_long(hScanner, IG_ISIS_TAG_BAR_TYPE, 0,
IG_ISIS_BAR_TYPE_CODE39);
IG_ISIS_tag_set_long(hScanner, IG_ISIS_TAG_BAR_TYPE, 1,
IG_ISIS_BAR_TYPE_CODABAR);
/* set the number of barcode types to search to two */
IG_ISIS_tag_set_long(hScanner, IG_ISIS_TAG_BAR_TYPECOUNT , 0,
2);

See Also

IG_ISIS_TAG_BAR_TYPECOUNT


IG_ISIS_TAG_BAR_TYPECOUNT

Number of barcode types to search. 0x069D · 1693

Category: ISIS, Optional.

Description

IG_ISIS_TAG_BAR_TYPECOUNT specifies the number of barcode types to search for on a page.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support barcode detection.

Values

An integer between 0 and the number of indices in IG_ISIS_TAG_BAR_TYPE.

Usage

Scanners that support barcode detection can often search for more than one type of barcode while examining a particular page. You specify which of the supported barcode types you might want to search for by adding them as indices to IG_ISIS_TAG_BAR_TYPE. Use IG_ISIS_TAG_BAR_TYPECOUNT to specify how many of those indices are active during a single page search.

See Also

IG_ISIS_TAG_BAR_TYPE.


IG_ISIS_TAG_BARCODE

Availability and status of barcode detection. 0x069B · 1691

Category: ISIS, Optional.

Description

IG_ISIS_TAG_BARCODE allows an application to determine whether barcode detection is available on the current scanner. It also controls whether barcode detection is enabled if the feature is supported.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support barcode detection.

Values

If the only available choice for IG_ISIS_TAG_BARCODE is IG_ISIS_TAG_BARCODE_OFF, then barcode detection is not supported in the driver.

Value
Defined Constant
Meaning
0
IG_ISIS_BARCODE_OFF
If this is the only choice, then barcode detection is not available in the scanner. Otherwise, barcode detection is disabled.
1
IG_ISIS_BARCODE_ON
Barcode detection is enabled.

Usage

If the current scanner supports barcode detection and also offers duplex scanning, barcode reading may only be available on one of the sides. To determine whether barcode detection is supported for both sides of a duplex scan, query the choices of IG_ISIS_TAG_BAR_AUTOREADFRONT and IG_ISIS_TAG_BAR_AUTOREADBACK.

See Also

IG_ISIS_TAG_BAR_AUTOREADFRONT, IG_ISIS_TAG_BAR_AUTOREADBACK.


IG_ISIS_TAG_BARDATA_TEXT

Text of the detected barcode. 0x06C7 · 1735

Category: ISIS, Optional.

Description

IG_ISIS_TAG_BARDATA_TEXT holds the decoded NULL terminated string of the current barcode after detection.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support barcode detection.

Values

A string containing the text of the barcode.

Usage

IG_ISIS_TAG_BARDATA_TEXT holds the decoded string from the detected barcode. If no barcode was found, then the value of IG_ISIS_TAG_BARDATA_TEXT has no meaning and should be ignored. You should verify that IG_ISIS_TAG_BARDATA_TYPE has a value other than 0 before querying IG_ISIS_TAG_BARDATA_TEXT.

Prior to checking the value of IG_ISIS_TAG_BARDATA_TEXT and other IG_ISIS_TAG_BARDATA tags, you should make sure that your application received a IG_ISIS_ERR_ENDZONE return code or that the IG_ISIS_run_zone call completed without error.

See Also

IG_ISIS_TAG_BARDATA_TYPE .


IG_ISIS_TAG_BARDATA_TYPE

Type of the detected barcode. 0x06C2 · 1730

Category: ISIS, Optional (Read-only).

Description

IG_ISIS_TAG_BARDATA_TYPE holds the type of the current barcode after detection.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support barcode detection.

Values

These are all the possible values for IG_ISIS_TAG_BARDATA_TYPE, but the actual barcode types that can be detected will depend on your scanner. Use IG_ISIS_choice_get_long on IG_ISIS_TAG_BAR_TYPE to query the barcode types available on your scanner.

Value
Defined Constant
Barcode Type
0
IG_ISIS_BAR_TYPE_NONE
No barcode.
1
IG_ISIS_BAR_TYPE_EAN8
Type EAN-8.
2
IG_ISIS_BAR_TYPE_EAN13
Type EAN-13.
3
IG_ISIS_BAR_TYPE_CODE39
Type CODE 39
4
IG_ISIS_BAR_TYPE_CODE25_INTERLEAVED
CODE 2/5 interleaved.
5
IG_ISIS_BAR_TYPE_CODE25_MATRIX
CODE 2/5 3 lines (matrix).
6
IG_ISIS_BAR_TYPE_CODE25_DATALOGIC
CODE 2/5 3 lines (datalogic).
7
IG_ISIS_BAR_TYPE_CODE25_INDUSTRIAL
CODE 2/5 5 lines (industrial).
8
IG_ISIS_BAR_TYPE_PATCHCODE
Patch Code Type II, III or Transfer.
9
IG_ISIS_BAR_TYPE_PATCHCODE_II
Patch Code Type II.
10
IG_ISIS_BAR_TYPE_PATCHCODE_III
Patch Code Type III.
11
IG_ISIS_BAR_TYPE_PATCH_TRANSFER
Transfer Patch Code
12
IG_ISIS_BAR_TYPE_CODABAR
Codabar barcode.
13
IG_ISIS_BAR_TYPE_UPC_E
UPC code revision E.
14
IG_ISIS_BAR_TYPE_CODE93
Type CODE 93.
15
IG_ISIS_BAR_TYPE_128
Type 128.
16
IG_ISIS_BAR_TYPE_POSTNET
Postnet.
17
IG_ISIS_BAR_TYPE_CODE25_AIRLINE
CODE 2/5 (airline).
18
IG_ISIS_BAR_TYPE_UPC_A
UPC code revision A.
19
IG_ISIS_BAR_TYPE_MICR_E13B
Check MICR E13B type.
20
IG_ISIS_BAR_TYPE_MICR_CMC7
Check MICR CMC7 type.
21
IG_ISIS_BAR_TYPE_ADDON2
ADDON2.
22
IG_ISIS_BAR_TYPE_ADDON5
ADDON5.
23
IG_ISIS_BAR_TYPE_AUTO
Auto detect any available barcode.

Usage

IG_ISIS_TAG_BARDATA_TYPE indicates the type of the barcode found during detection. The possible values are the same as the values for IG_ISIS_TAG_BAR_TYPE. If no barcode was found, IG_ISIS_TAG_BARDATA_TYPE will have the value 0 (IG_ISIS_TAG_BAR_TYPE_NONE), and all other IG_ISIS_TAG_BARDATA tags should be ignored.

Prior to quering the value of IG_ISIS_TAG_BARDATA_TYPE and other IG_ISIS_TAG_BARDATA tags, you should make sure that your application received a IG_ISIS_ERR_ENDZONE return code or that the IG_ISIS_run_zone call completed without error.

See Also

IG_ISIS_TAG_BAR_TYPE, IG_ISIS_TAG_BARDATA_TEXT


IG_ISIS_TAG_BARDATA_XPOSITION

X offset of the detected barcode. 0x06C3 · 1731

Category: ISIS, Optional (Read-only).

Description

IG_ISIS_TAG_BARDATA_XPOSITION holds the x offset of the detected barcode measured in units of the current resolution.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support barcode detection.

Values

An integer indicating the x offset.

Usage

IG_ISIS_TAG_BARDATA_XPOSITION holds the horizontal offset value from the upper left corner of the page to the upper left corner of the barcode. The value is in units of the current resolution. If no barcode was found, then the value of IG_ISIS_TAG_BARDATA_XPOSITION has no meaning and should be ignored. You should verify that IG_ISIS_TAG_BARDATA_TYPE has a value other than 0 before querying IG_ISIS_TAG_BARDATA_XPOSITION.

Prior to checking the value of IG_ISIS_TAG_BARDATA_XPOSITION and other IG_ISIS_TAG_BARDATA tags, you should make sure that your application received a IG_ISIS_ERR_ENDZONE return code or that the IG_ISIS_run_zone call completed without error.

See Also

IG_ISIS_TAG_BARDATA_TYPE, IG_ISIS_TAG_BARDATA_YPOSITION, IG_ISIS_TAG_BARDATA_TEXT .


IG_ISIS_TAG_BARDATA_YPOSITION

Y offset of the detected barcode. 0x06C4 · 1732

Category: ISIS, Optional (Read-only).

Description

IG_ISIS_TAG_BARDATA_YPOSITION holds the y offset of the detected barcode measured in units of the current resolution.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support barcode detection.

Values

An integer indicating the y offset.

Usage

IG_ISIS_TAG_BARDATA_YPOSITION holds the vertical offset value from the upper left corner of the page to the upper left corner of the barcode. The value is in units of the current resolution. If no barcode was found, then the value of IG_ISIS_TAG_BARDATA_YPOSITION has no meaning and should be ignored. You should verify that IG_ISIS_TAG_BARDATA_TYPE has a value other than 0 before querying IG_ISIS_TAG_BARDATA_YPOSITION.

Prior to checking the value of IG_ISIS_TAG_BARDATA_YPOSITION and other IG_ISIS_TAG_BARDATA tags, you should make sure that your application received a IG_ISIS_ERR_ENDZONE return code or that the IG_ISIS_run_zone call completed without error.

See Also

IG_ISIS_TAG_BARDATA_TYPE, IG_ISIS_TAG_BARDATA_XPOSITION, IG_ISIS_TAG_BARDATA_TEXT.


Custom Dialog Box Tags

There are the following Custom Dialog Box tags:

  • IG_ISIS_TAG_ALLFILESFLAG
  • IG_ISIS_TAG_ALLOWEDFORMATS
  • IG_ISIS_TAG_AVAILBITSPERSAMPLE
  • IG_ISIS_TAG_AVAILCOLORFMTS
  • IG_ISIS_TAG_AVAILCOLORFMTSNAME
  • IG_ISIS_TAG_AVAILCOMPRESSION
  • IG_ISIS_TAG_AVAILCOMPRESSIONNAME
  • IG_ISIS_TAG_AVAILFMTS
  • IG_ISIS_TAG_AVAILFORMAT_EXTS
  • IG_ISIS_TAG_AVAILFORMAT_FILETYPES
  • IG_ISIS_TAG_AVAILFORMAT_NAMES
  • IG_ISIS_TAG_AVAILPHOTOMETRIC
  • IG_ISIS_TAG_AVAILSAMPLESPERPIXEL
  • IG_ISIS_TAG_BPS_LBS
  • IG_ISIS_TAG_COLORFMTS_LBS
  • IG_ISIS_TAG_COMPRESSION_LBS
  • IG_ISIS_TAG_FILETYPE_LBS
  • IG_ISIS_TAG_NUMALLOWEDFORMATS
  • IG_ISIS_TAG_OUTPUT_TAGS
  • IG_ISIS_TAG_PHOTO_LBS
  • IG_ISIS_TAG_SPP_LBS


IG_ISIS_TAG_ALLFILESFLAG

Enable "All Files" in dialog boxes. 0x1318 · 4888

Category: ISIS, Optional.

Description

IG_ISIS_TAG_ALLFILESFLAG allows an application to enable or disable the "All Files (*.*)" entry in a common file open dialog box.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

PIXFPACK.

Values

1
Enable "All Files (*.*)."
0
Disable "All Files (*.*)."

Usage

Set IG_ISIS_TAG_ALLFILESFLAG as desired before querying IG_ISIS_TAG_AVAILFMTS to control whether or not the string returned by IG_ISIS_TAG_AVAILFMTS includes the string "All Files (*.*)."

See Also

IG_ISIS_TAG_AVAILFMTS, IG_ISIS_TAG_NUMALLOWEDFORMATS, IG_ISIS_TAG_ALLOWEDFORMATS.


IG_ISIS_TAG_ALLOWEDFORMATS

Limit choices for IG_ISIS_TAG_AVAILFMTS. 0x1322 · 4898

Category: ISIS, Optional.

Description

IG_ISIS_TAG_ALLOWEDFORMATS limits the available formats reported by IG_ISIS_TAG_AVAILFMTS when used with PIXFPACK, allowing your application in a file open or file save dialog to list only a subset of the formats supported by the installed group of file filters (PXIs).

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

PIXFPACK.

Values

IG_ISIS_FILETYPE_TIFF
Allow TIFF files.
IG_ISIS_FILETYPE_PDA
Allow PDA files.
IG_ISIS_FILETYPE_PCX
Allow PCX files.
IG_ISIS_FILETYPE_DCX
Allow DCX files.
IG_ISIS_FILETYPE_GIF
Allow GIF files.
IG_ISIS_FILETYPE_BMP
Allow BMP files.
IG_ISIS_FILETYPE_JPEG
Allow JPEG files.
IG_ISIS_FILETYPE_CALS
Allow CALS files.

Tag Dependencies and Dependent Tags

The number of times IG_ISIS_TAG_ALLOWEDFORMATS can be called depends on the value to which your application sets IG_ISIS_TAG_NUMALLOWEDFORMATS. If IG_ISIS_TAG_NUMALLOWEDFORMATS is set to IG_ISIS_NUMALLOWED_ALL (zero), then all values set by IG_ISIS_TAG_ALLOWEDFORMATS are ignored.

Usage

IG_ISIS_TAG_ALLOWEDFORMATS must be set one per IG_ISIS_tag_set_long call, using an index value derived from IG_ISIS_TAG_NUMALLOWEDFORMATS. For example, if you want to allow five formats, you would set IG_ISIS_TAG_NUMALLOWEDFORMATS to 5, and then set IG_ISIS_TAG_ALLOWEDFORMATS five times, using consecutive index values of 0 through 4.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_AVAILFMTS, IG_ISIS_TAG_NUMALLOWEDFORMATS, IG_ISIS_TAG_AVAILFORMAT_FILETYPES, IG_ISIS_TAG_AVAILFORMAT_NAMES, IG_ISIS_TAG_AVAILFORMAT_EXTS.


IG_ISIS_TAG_AVAILBITSPERSAMPLE

Available BitsPerSample choices. 0x1330 · 4912

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_AVAILBITSPERSAMPLE allows an application to query the currently valid BitsPerSample choices for use in a list box in a common save dialog box. (Read-only.)

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_AVAILBITSPERSAMPLE may contain any currently valid BitsPerSample values.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_AVAILFORMAT_FILETYPES ® IG_ISIS_TAG_AVAILSAMPLESPERPIXEL ® IG_ISIS_TAG_AVAILBITSPERSAMPLE ® IG_ISIS_TAG_AVAILPHOTOMETRIC ® IG_ISIS_TAG_AVAILCOMPRESSION ® IG_ISIS_TAG_AVAILCOMPRESSIONNAME

Usage

The choices for IG_ISIS_TAG_AVAILBITSPERSAMPLE contain the BitsPerSample values for the current SamplesPerPixel setting. The value of this tag has no meaning. Query this tag's choices to obtain the values to put into a list box.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_AVAILSAMPLESPERPIXEL, IG_ISIS_TAG_AVAILPHOTOMETRIC, IG_ISIS_TAG_AVAILCOMPRESSION, IG_ISIS_TAG_AVAILCOMPRESSIONNAME.


IG_ISIS_TAG_AVAILCOLORFMTS

Available color format choices. 0x1324 · 4900

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_AVAILCOLORFMTS allows an application to query the currently valid color format choices for use in a list box in a common save dialog box. (Read-only.)

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_AVAILCOLORFMTS may contain any currently valid color format values.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_AVAILFORMAT_FILETYPES ® IG_ISIS_TAG_AVAILCOLORFMTS ® IG_ISIS_TAG_AVAILCOLORFMTSNAME ® IG_ISIS_TAG_AVAILCOMPRESSION

® IG_ISIS_TAG_AVAILCOMPRESSIONNAME

Usage

The choices for IG_ISIS_TAG_AVAILCOLORFMTS contain the color format values for the current IG_ISIS_TAG_AVAILFORMAT_FILETYPES choices. The value of this tag has no meaning. Query this tag's choices to obtain the values to put into a list box.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_AVAILFORMAT_FILETYPES, IG_ISIS_TAG_AVAILCOLORFMTSNAME, IG_ISIS_TAG_AVAILSAMPLESPERPIXEL, IG_ISIS_TAG_AVAILPHOTOMETRIC, IG_ISIS_TAG_AVAILCOMPRESSION, IG_ISIS_TAG_AVAILCOMPRESSIONNAME.


IG_ISIS_TAG_AVAILCOLORFMTSNAME

Available color format name choices. 0x1325 · 4901

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_AVAILCOLORFMTSNAME allows an application to display the currently valid color format name choices in a list box in a common save dialog box. (Read-only.)

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_AVAILCOLORFMTSNAME may contain any currently valid color format names, such as "Binary", "4-Bit Gray", "8-Bit Palette", or "24-Bit Color".

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_AVAILFORMAT_FILETYPES ® IG_ISIS_TAG_AVAILCOLORFMTS ® IG_ISIS_TAG_AVAILCOLORFMTSNAME ® IG_ISIS_TAG_AVAILCOMPRESSION

® IG_ISIS_TAG_AVAILCOMPRESSIONNAME

Usage

The choices for IG_ISIS_TAG_AVAILCOLORFMTSNAME contain the ASCII color format name values for the current IG_ISIS_TAG_AVAILCOLORFMTS choices. The value of this tag has no meaning. Query this tag's choices to obtain the values to put into a list box.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_AVAILFORMAT_FILETYPES, IG_ISIS_TAG_AVAILCOLORFMTS, IG_ISIS_TAG_AVAILSAMPLESPERPIXEL, IG_ISIS_TAG_AVAILPHOTOMETRIC, IG_ISIS_TAG_AVAILCOMPRESSION, IG_ISIS_TAG_AVAILCOMPRESSIONNAME.


IG_ISIS_TAG_AVAILCOMPRESSION

Available compression choices. 0x1326 · 4902

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_AVAILCOMPRESSION allows an application to query the currently valid compression choices for use in a list box in a common save dialog box. (Read-only.)

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_AVAILCOMPRESSION may contain any currently valid compression values.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_AVAILFORMAT_FILETYPES ® IG_ISIS_TAG_AVAILCOLORFMTS ® IG_ISIS_TAG_AVAILCOLORFMTSNAME ® IG_ISIS_TAG_AVAILCOMPRESSION ® IG_ISIS_TAG_AVAILCOMPRESSIONNAME

Usage

The choices for IG_ISIS_TAG_AVAILCOMPRESSION contain the compression values for the current IG_ISIS_TAG_AVAILCOLORFMTS choices. The value of this tag has no meaning. Query this tag's choices to obtain the values to put into a list box.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_AVAILFORMAT_FILETYPES, IG_ISIS_TAG_AVAILCOLORFMTS, IG_ISIS_TAG_AVAILCOLORFMTSNAME, IG_ISIS_TAG_AVAILSAMPLESPERPIXEL, IG_ISIS_TAG_AVAILPHOTOMETRIC, IG_ISIS_TAG_AVAILCOMPRESSIONNAME.


IG_ISIS_TAG_AVAILCOMPRESSIONNAME

Available compression name choices. 0x1327 · 4903

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_AVAILCOMPRESSIONNAME allows an application to display the currently valid compression name choices in a list box in a common save dialog box. (Read-only.)

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_AVAILCOMPRESSIONNAME may contain any currently valid compression names, such as "None", "Packbits", "Run Length", or "CCITT Group 4".

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_AVAILFORMAT_FILETYPES ® IG_ISIS_TAG_AVAILCOLORFMTS ® IG_ISIS_TAG_AVAILCOLORFMTSNAME ® IG_ISIS_TAG_AVAILCOMPRESSION ® IG_ISIS_TAG_AVAILCOMPRESSIONNAME

Usage

The choices for IG_ISIS_TAG_AVAILCOMPRESSIONNAME contain the compression names for the current IG_ISIS_TAG_AVAILCOLORFMTS choices. The value of this tag has no meaning. Query this tag's choices to obtain the values to put into a list box.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_AVAILFORMAT_FILETYPES, IG_ISIS_TAG_AVAILCOLORFMTS, IG_ISIS_TAG_AVAILCOLORFMTSNAME, IG_ISIS_TAG_AVAILSAMPLESPERPIXEL, IG_ISIS_TAG_AVAILPHOTOMETRIC, IG_ISIS_TAG_AVAILCOMPRESSION.


IG_ISIS_TAG_AVAILFMTS

List box string containing available file formats. 0x1316 · 4886

Category: ISIS, Optional (Read-only).

Description

IG_ISIS_TAG_AVAILFMTS returns an ASCII string based on polling all available file drivers (PXIs), optionally limited by the values specified in IG_ISIS_TAG_NUMALLOWEDFORMATS and IG_ISIS_TAG_ALLOWEDFORMATS. (Read-only.)

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

PIXFPACK.

Values

IG_ISIS_TAG_AVAILFMTS returns a string in the format required by a file type list box in a Windows common open dialog box. An example of this string is:

"TIFF (*.TIF)\0*.tif\0PCX (*.PCX\0*.pcx\0All Files (*.*)\0*.* \0Known Formats\0*.tif, *.pcx, *.bmp\0"

Note that a C string is terminated by a "\0" and so the string returned in IG_ISIS_TAG_AVAILFMTS is actually terminated by two "\0" characters. This is the format that Windows expects for a list box string.

Tag Dependencies and Dependent Tags

The values returned in IG_ISIS_TAG_AVAILFMTS depend on the value of IG_ISIS_TAG_NUMALLOWEDFORMATS and, if IG_ISIS_TAG_NUMALLOWEDFORMATS has a value of other than IG_ISIS_TAG_NUMALLOWED_ALL (zero), also on the values of IG_ISIS_TAG_ALLOWEDFORMATS.

IG_ISIS_TAG_NUMALLOWEDFORMATS ® IG_ISIS_TAG_ALLOWEDFORMATS ® IG_ISIS_TAG_AVAILFMTS

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_ALLOWEDFORMATS, IG_ISIS_TAG_NUMALLOWEDFORMATS, IG_ISIS_TAG_AVAILFORMAT_FILETYPES, IG_ISIS_TAG_AVAILFORMAT_NAMES, IG_ISIS_TAG_AVAILFORMAT_EXTS.


IG_ISIS_TAG_AVAILFORMAT_EXTS

Choices containing extensions of available formats. 0x1321 · 4897

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_AVAILFORMAT_EXTS allows an application to determine the names of the filename extensions for the file types supported by the application. This allows the application to display an open or save dialog box that lists the extensions of the supported file types, and is generally used to filter the filenames displayed so that only files with the selected extension appear in the list. (Read-only.)

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_AVAILFORMAT_EXTS contain values such as "*.gif" and "*.tif".

Tag Dependencies and Dependent Tags

The choices for IG_ISIS_TAG_AVAILFORMAT_EXTS correspond to and depend on the values returned in IG_ISIS_TAG_AVAILFMTS.

IG_ISIS_TAG_NUMALLOWEDFORMATS ® IG_ISIS_TAG_ALLOWEDFORMATS ® IG_ISIS_TAG_AVAILFORMAT_EXTS

Usage

The choices for IG_ISIS_TAG_AVAILFORMAT_EXTS contain the extensions of the available file types. The value of this tag has no meaning. After obtaining an index value for a particular IG_ISIS_TAG_FILETYPE_name (by using the Windows function LB_GETCURSEL to get the current selection of the file type list box), get the filename extension string by calling IG_ISIS_choice_get_ascii using this index value in the wIndex parameter.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_AVAILFMTS, IG_ISIS_TAG_ALLOWEDFORMATS, IG_ISIS_TAG_NUMALLOWEDFORMATS, IG_ISIS_TAG_AVAILFORMAT_FILETYPES, IG_ISIS_TAG_AVAILFORMAT_NAMES.


IG_ISIS_TAG_AVAILFORMAT_FILETYPES

Choices containing file types of available formats. 0x1319 · 4889

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_AVAILFORMAT_FILETYPES allows an application to determine the types of files supported by the application. This allows the application to determine the index of each file type so that other strings (such as IG_ISIS_TAG_AVAILFORMAT_NAMES and IG_ISIS_TAG_AVAILFORMAT_EXTS) can be retrieved and displayed in an open or save dialog box. (Read-only.)

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_AVAILFORMAT_FILETYPES may contain any of the following values:

IG_ISIS_FILETYPE_TIFF
TIFF files are available.
IG_ISIS_FILETYPE_PDA
PDA files are available.
IG_ISIS_FILETYPE_PCX
PCX files are available.
IG_ISIS_FILETYPE_DCX
DCX files are available.
IG_ISIS_FILETYPE_GIF
GIF files are available.
IG_ISIS_FILETYPE_BMP
BMP files are available.
IG_ISIS_FILETYPE_JPEG
JPEG files are available.
IG_ISIS_FILETYPE_CALS
CALS files are available.

Tag Dependencies and Dependent Tags

The choices for IG_ISIS_TAG_AVAILFORMAT_FILETYPES depend on the value of IG_ISIS_TAG_NUMALLOWEDFORMATS and, if IG_ISIS_TAG_NUMALLOWEDFORMATS has a value of other than IG_ISIS_NUMALLOWED_ALL (zero), also on the values of IG_ISIS_TAG_ALLOWEDFORMATS.

IG_ISIS_TAG_NUMALLOWEDFORMATS ® IG_ISIS_TAG_ALLOWEDFORMATS ® IG_ISIS_TAG_AVAILFORMAT_FILETYPES

Usage

The choices for IG_ISIS_TAG_AVAILFORMAT_FILETYPES contain the file type values of the available file types. The value of this tag has no meaning. After obtaining an index value for a particular IG_ISIS_TAG_FILETYPE_name (by using the Windows function LB_GETCURSEL to get the current selection of the file type list box), get the file types by calling IG_ISIS_choice_get_long using this index value in the wIndex parameter.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_AVAILFMTS, IG_ISIS_TAG_ALLOWEDFORMATS, IG_ISIS_TAG_NUMALLOWEDFORMATS, IG_ISIS_TAG_AVAILFORMAT_EXTS, IG_ISIS_TAG_AVAILFORMAT_NAMES.


IG_ISIS_TAG_AVAILFORMAT_NAMES

Choices containing names of available formats. 0x1320 · 4896

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_AVAILFORMAT_NAMES allows an application to determine the names of the file types supported by the application. This allows the application to display an open or save dialog box that lists the names of the supported file types, and is generally used to help the user pick the desired file type. (Read-only.)

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_AVAILFORMAT_NAMES contain values such as "Compuserve (*.GIF)" and "TIFF (*.TIF)".

Tag Dependencies and Dependent Tags

The choices for IG_ISIS_TAG_AVAILFORMAT_NAMES correspond to and depend on the values returned in IG_ISIS_TAG_AVAILFMTS.

IG_ISIS_TAG_NUMALLOWEDFORMATS ® IG_ISIS_TAG_ALLOWEDFORMATS ® IG_ISIS_TAG_AVAILFORMAT_NAMES

Usage

The choices for IG_ISIS_TAG_AVAILFORMAT_NAMES contain the names of the available file types. The value of this tag has no meaning. After obtaining an index value for a particular IG_ISIS_TAG_FILETYPE_name (by using the Windows function LB_GETCURSEL to get the current selection of the file type list box), get the file type name string by calling IG_ISIS_choice_get_ascii using this index value in the wIndex parameter.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_AVAILFMTS, IG_ISIS_TAG_ALLOWEDFORMATS, IG_ISIS_TAG_NUMALLOWEDFORMATS, IG_ISIS_TAG_AVAILFORMAT_FILETYPES, IG_ISIS_TAG_AVAILFORMAT_EXTS.


IG_ISIS_TAG_AVAILPHOTOMETRIC

Available PhotometricInterpretation choices. 0x1329 · 4911

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_AVAILPHOTOMETRIC allows an application to determine the currently valid PhotometricInterpretation choices for displaying in a list box in a common save dialog box. (Read-only.)

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_AVAILPHOTOMETRIC may contain any currently valid PhotometricInterpretation values.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_AVAILFORMAT_FILETYPES ® IG_ISIS_TAG_AVAILSAMPLESPERPIXEL ® IG_ISIS_TAG_AVAILBITSPERSAMPLE ® IG_ISIS_TAG_AVAILPHOTOMETRIC ® IG_ISIS_TAG_AVAILCOMPRESSION ® IG_ISIS_TAG_AVAILCOMPRESSIONNAME

Usage

The choices for IG_ISIS_TAG_AVAILPHOTOMETRIC contain the PhotometricInterpretation values for the current BitsPerSample setting. The value of this tag has no meaning. Query this tag's choices to obtain the values to put into a list box.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_AVAILSAMPLESPERPIXEL, IG_ISIS_TAG_AVAILBITSPERSAMPLE, IG_ISIS_TAG_AVAILCOMPRESSION, IG_ISIS_TAG_AVAILCOMPRESSIONNAME.


IG_ISIS_TAG_AVAILSAMPLESPERPIXEL

Available SamplesPerPixel choices. 0x1328 · 4910

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_AVAILSAMPLESPERPIXEL allows an application to determine the currently valid SamplesPerPixel choices for displaying in a list box in a common save dialog box. (Read-only.)

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_AVAILSAMPLESPERPIXEL may contain any currently valid SamplesPerPixel values.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_AVAILFORMAT_FILETYPES ® IG_ISIS_TAG_AVAILSAMPLESPERPIXEL ® IG_ISIS_TAG_AVAILBITSPERSAMPLE ® IG_ISIS_TAG_AVAILPHOTOMETRIC ® IG_ISIS_TAG_AVAILCOMPRESSION ® IG_ISIS_TAG_AVAILCOMPRESSIONNAME

Usage

The choices for IG_ISIS_TAG_SAMPLESPERPIXEL contain the SamplesPerPixel values for the current FileTypes setting. The value of this tag has no meaning. Query this tag's choices to obtain the values to put into a list box.

See Also

IG_ISIS_TAG_AVAILFORMAT_FILETYPES, IG_ISIS_TAG_AVAILBITSPERSAMPLE, IG_ISIS_TAG_AVAILPHOTOMETRIC, IG_ISIS_TAG_AVAILCOMPRESSION, IG_ISIS_TAG_AVAILCOMPRESSIONNAME.


IG_ISIS_TAG_BPS_LBS

BitsPerSample list box string. 0x1334 · 4916

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_BPS_LBS allows an application to display a list box containing the currently valid BitsPerSample settings. It should be used in conjunction with IG_ISIS_TAG_SPP_LBS and IG_ISIS_TAG_PHOTO_LBS to give the user total control over color format. If separate control is not desired, you should use IG_ISIS_TAG_COLORFMTS_LBS instead.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_BPS_LBS contain values such as "1", "4", and "8".

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_FILETYPE_LBS ® IG_ISIS_TAG_SPP_LBS ®IG_ISIS_TAG_BPS_LBS ® IG_ISIS_TAG_PHOTO_LBS ® IG_ISIS_TAG_COMPRESSION_LBS

Usage

The choices for IG_ISIS_TAG_BPS_LBS contain ASCII strings of the numbers of bits per sample that are currently available based on checking the index values currently selected in the other, related list boxes. This checking is accomplished by the application calling IG_ISIS_drv_update_state whenever the user changes any of the color format selections in the dialog box. The value of this tag has no meaning.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_SPP_LBS, IG_ISIS_TAG_PHOTO_LBS, IG_ISIS_TAG_COLORFMTS_LBS, IG_ISIS_TAG_COMPRESSION_LBS, IG_ISIS_TAG_FILETYPE_LBS, IG_ISIS_drv_update_state.


IG_ISIS_TAG_COLORFMTS_LBS

Color formats list box string. 0x1332 · 4914

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_COLORFMTS_LBS allows an application to display a list box containing the color formats supported by the currently-selected file format. This gives the user one-listbox control over color formats. If you instead want to provide three-listbox control over the individual color format settings, use IG_ISIS_TAG_SPP_LBS, IG_ISIS_TAG_BPS_LBS, and IG_ISIS_TAG_PHOTO_LBS instead.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_COLORFMTS_LBS contain values such as "Binary", "4-level gray", "8-bit palette", and "24-bit color".

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_FILETYPE_LBS ® IG_ISIS_TAG_COLORFMTS_LBS ® IG_ISIS_TAG_COMPRESSION_LBS

Usage

The choices for IG_ISIS_TAG_COLORFMTS_LBS contain the names of the available color formats based on checking the index values currently selected in the other, related list boxes. This checking is accomplished by calling IG_ISIS_drv_update_state whenever the user changes any of the color format selections in the dialog box. The value of this tag has no meaning.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_SPP_LBS, IG_ISIS_TAG_BPS_LBS, IG_ISIS_TAG_PHOTO_LBS, IG_ISIS_TAG_COMPRESSION_LBS, IG_ISIS_TAG_FILETYPE_LBS, IG_ISIS_drv_update_state.


IG_ISIS_TAG_COMPRESSION_LBS

Compression types list box string. 0x1333 · 4915

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_COMPRESSION_LBS allows an application to display a list box containing the compression types supported by the currently-selected file format and color format.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_COMPRESSION_LBS contain values such as "None", "CCITT Group 3", "LZW", and "JPEG".

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_FILETYPE_LBS ® IG_ISIS_TAG_COLORFMTS_LBS ® IG_ISIS_TAG_COMPRESSION_LBS

Usage

The choices for IG_ISIS_TAG_COMPRESSION_LBS contain the names of the available compression types based on checking the index values currently selected in the other, related list boxes. This checking is accomplished by calling IG_ISIS_drv_update_state whenever the user changes any of the color format or file type selections in the dialog box. The value of this tag has no meaning.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_SPP_LBS, IG_ISIS_TAG_BPS_LBS, IG_ISIS_TAG_PHOTO_LBS, IG_ISIS_TAG_COMPRESSION_LBS, IG_ISIS_TAG_FILETYPE_LBS, IG_ISIS_drv_update_state.


IG_ISIS_TAG_FILETYPE_LBS

File type list box string. 0x1331 · 4913

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_FILETYPE_LBS allows an application to display a list box containing the files supported by the currently-installed set of file writing drivers (*.PXIs), giving the user control over the type of file to write to disk. By using IG_ISIS_TAG_FILETYPE_LBS, you can create an application that automatically accommodates new file types whenever their PXI files are installed on the user's disk.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_FILETYPE_LBS contain values such as "Windows Bitmap (*.BMP)", "CALS Files (*.CAL)", "FAX (*.DCX)", and so forth, according to the specific file writing drivers (*.PXIs) installed on the user system.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_FILETYPE_LBS ® IG_ISIS_TAG_COLORFMTS_LBS ®IG_ISIS_TAG_COMPRESSION_LBS

Usage

The choices for IG_ISIS_TAG_FILETYPE_LBS contain the names of the available file formats. The value of this tag has no meaning. This tag is used in a save dialog box to give the user the option of saving in any supported format. It also is used to filter the list of files displayed to show only those files with the selected extension.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_SPP_LBS, IG_ISIS_TAG_BPS_LBS, IG_ISIS_TAG_PHOTO_LBS, IG_ISIS_TAG_COMPRESSION_LBS, IG_ISIS_TAG_COLORFMTS_LBS, IG_ISIS_drv_update_state.


IG_ISIS_TAG_NUMALLOWEDFORMATS

Number of allowed file formats. 0x1323 · 4899

Category: ISIS, Optional.

Description

IG_ISIS_TAG_NUMALLOWEDFORMATS allows an application to specify how many formats to place into IG_ISIS_TAG_AVAILFMTS.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

PIXFPACK.

Values

IG_ISIS_TAG_NUMALLOWEDFORMATS is an integer value specifying the number of formats that should be returned in the IG_ISIS_TAG_AVAILFMTS tag. The defined constant IG_ISIS_NUMALLOWED_ALL (0L) means place all available formats in the list.

Usage

Use IG_ISIS_TAG_NUMALLOWEDFORMATS together with IG_ISIS_TAG_ALLOWEDFORMATS to design an application which displays a particular subset of the available file formats in its common Open or Save dialog. For each allowed format, your application must call IG_ISIS_tag_set_long(driver, IG_ISIS_TAG_ALLOWEDFORMATS, n, IG_ISIS_TAG_FILETYPE_name) where n is a sequential number from zero to IG_ISIS_TAG_NUMALLOWEDFORMATS - 1, and name is the name of one of the file formats to allow (TIFF, PCX, PDA, and so forth). See IG_ISIS_TAG_FILETYPE for a list of all available file types.

Because IG_ISIS_TAG_NUMALLOWED_ALL = 0, it is not possible to specify no allowed formats.

See Also

IG_ISIS_TAG_FILETYPE, IG_ISIS_TAG_ALLOWEDFORMATS, IG_ISIS_TAG_AVAILFMTS.


IG_ISIS_TAG_OUTPUT_TAGS

Pointer to a TAGLIST of current settings. 0x1337 · 4919

Category: ISIS, (Read-only).

Description

IG_ISIS_TAG_OUTPUT_TAGS is a pointer to an AutoPipe TAGLIST structure that contains all of the settings made by the user in a common file open or file save dialog box that was implemented using the IG_ISIS_TAG_..._LBS tags of this toolkit. By using IG_ISIS_TAG_OUTPUT_TAGS, an application can use AutoPipe to automatically construct an ISIS pipe that implements the file type, color format, compression type, and so forth, as selected by the user, without knowledge of the actual settings or which drivers they require.

Type

IG_ISIS_TAG_TYPE_LONG (Actually a LONG pointer to a TAGLIST structure.)

Drivers

PIXFPACK.

Values

A pointer to an AutoPipe TAGLIST structure, IG_ISIS_TAG_OUTPUT_TAGS is not actually a tag, but is used because it is an easy way to give an application a pointer to a TAGLIST.

Usage

Create a dialog box for opening or saving image files that uses IG_ISIS_TAG_FILETYPE_LBS (list box string), IG_ISIS_TAG_COLORFMTS_LBS, IG_ISIS_TAG_COMPRESSION_LBS, and other IG_ISIS_TAG_..._LBS tags as necessary. Each time the user changes one of these list boxes, call IG_ISIS_drv_update_state to update the choices available in all other tags and to save the value that the user just set. When you are ready to construct your pipe, call IG_ISIS_tag_get_long to get the value of IG_ISIS_TAG_OUTPUT_TAGS. Pass this value as a pointer to the TAGLIST structure in AutoPipeIsis to construct your pipe.

See Also

IG_ISIS_drv_update_state, IG_ISIS_tag_get_long, IG_ISIS_TAG_FILETYPE_LBS, IG_ISIS_TAG_COLORFMTS_LBS, IG_ISIS_TAG_COMPRESSION_LBS, IG_ISIS_TAG_BPS_LBS, IG_ISIS_TAG_SPP_LBS, IG_ISIS_TAG_PHOTO_LBS.


IG_ISIS_TAG_PHOTO_LBS

PhotometricInterpretation list box string. 0x1336 · 4918

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_PHOTO_LBS allows an application to display a list box containing the currently valid PhotometricInterpretation settings. It should be used in conjunction with IG_ISIS_TAG_SPP_LBS and IG_ISIS_TAG_BPS_LBS to give the user total control over color format. If separate control is not desired, you should use IG_ISIS_TAG_COLORFMTS_LBS instead.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_PHOTO_LBS contain values such as "WHITE01", "PALETTE", and "RGB".

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_FILETYPE_LBS ® IG_ISIS_TAG_SPP_LBS ® IG_ISIS_TAG_BPS_LBS ® IG_ISIS_TAG_PHOTO_LBS ® IG_ISIS_TAG_COMPRESSION_LBS

Usage

The choices for IG_ISIS_TAG_PHOTO_LBS contain ASCII strings of the values of photometric interpretation that are currently available based on checking the index values currently selected in the other, related list boxes. This checking is accomplished by calling IG_ISIS_drv_update_state whenever the user changes any of the color format selections in the dialog box. The value of this tag has no meaning.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_SPP_LBS, IG_ISIS_TAG_BPS_LBS, IG_ISIS_TAG_COLORFMTS_LBS, IG_ISIS_TAG_COMPRESSION_LBS, IG_ISIS_TAG_FILETYPE_LBS, IG_ISIS_drv_update_state.


IG_ISIS_TAG_SPP_LBS

SamplesPerPixel list box string. 0x1335 · 4917

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_SPP_LBS allows an application to display a list box containing the currently valid SamplesPerPixel settings. It should be used in conjunction with IG_ISIS_TAG_BPS_LBS and IG_ISIS_TAG_PHOTO_LBS to give the user total control over color format. If separate control is not desired, you should use IG_ISIS_TAG_COLORFMTS_LBS instead.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

PIXFPACK.

Values

The choices for IG_ISIS_TAG_SPP_LBS contain values such as "1" and "3".

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_FILETYPE_LBS ® IG_ISIS_TAG_SPP_LBS ® IG_ISIS_TAG_BPS_LBS ® IG_ISIS_TAG_PHOTO_LBS ® IG_ISIS_TAG_COMPRESSION_LBS

Usage

The choices for IG_ISIS_TAG_SPP_LBS contain ASCII strings of the numbers of samples per pixel that are currently available based on checking the index values currently selected in the other, related list boxes. This checking is accomplished by calling IG_ISIS_drv_update_state whenever the user changes any of the color format selections in the dialog box. The value of this tag has no meaning.

See Also

"File Reading and File Writing" on page 8-1, IG_ISIS_TAG_BPS_LBS, IG_ISIS_TAG_PHOTO_LBS, IG_ISIS_TAG_COLORFMTS_LBS, IG_ISIS_TAG_COMPRESSION_LBS, IG_ISIS_TAG_FILETYPE_LBS, IG_ISIS_drv_update_state.


Custom Tag Tags

There are the following Custom Tag tags:

  • IG_ISIS_TAG_PIXFPACK_CALLBACK
  • IG_ISIS_TAG_PIXFPACK_CALLBACK_DATA


IG_ISIS_TAG_PIXFPACK_CALLBACK

Callback for custom tag creation. 0x1300 · 4864

Category: ISIS, Optional.

Description

IG_ISIS_TAG_PIXFPACK_CALLBACK is used to create custom tags to be written into the image file. Writing tags to an image file is supported only by file types that contain tags (TIFF).

Type

IG_ISIS_TAG_TYPE_LONG (value passed in must be of the type PIXIF_CALLBACK FAR *).

Drivers

PIXFPACK.

Values

The callback has the form:

int_export_far_pascal Callback(HISISDRV hDriver, LONG lValue);

Usage

To write a custom tag into an image file, set IG_ISIS_TAG_PIXFPACK_CALLBACK to point to the callback function. When the callback is called, lpDriver will point to a driver on which you can create (using IG_ISIS_tag_create...) and set (using IG_ISIS_tag_set...) tags. Any tags so created will be written into the file. lValue will contain a LONG value which was set in the IG_ISIS_TAG_PIXFPACK_CALLBACK_DATA tag.

See Also

IG_ISIS_TAG_PIXFPACK_CALLBACK_DATA, IG_ISIS_tag_create function in the chapter on Minidrivers (page 11-15), IG_ISIS_tag_set... functions in the Function Reference (Chapter 18).


IG_ISIS_TAG_PIXFPACK_CALLBACK_DATA

Tag value for custom tag. 0x1301 · 4865

Category: ISIS, Optional.

Description

IG_ISIS_TAG_PIXFPACK_CALLBACK_DATA contains the value to which to set the custom tag created by using IG_ISIS_TAG_PIXFPACK_CALLBACK. This tag can be used to pass any desired user data to the IG_ISIS_TAG_PIXFPACK_CALLBACK function.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

PIXFPACK.

Values

The value of IG_ISIS_TAG_PIXFPACK_CALLBACK_DATA will depend on the use for which the custom tag is designed.

Usage

The value of IG_ISIS_TAG_PIXFPACK_CALLBACK_DATA is passed as the second parameter to the callback specified by IG_ISIS_TAG_PIXFPACK_CALLBACK. The default value of zero is passed if this tag is not explicitly set.

See Also

IG_ISIS_TAG_PIXFPACK_CALLBACK.


Data Format Tags

There are the following Data Format tags:

  • IG_ISIS_TAG_COMPRESSION
  • IG_ISIS_TAG_FILLORDER
  • IG_ISIS_TAG_JBIGOPTIONS
  • IG_ISIS_TAG_KFACTOR
  • IG_ISIS_TAG_MAXDCXIFDSIZE
  • IG_ISIS_TAG_PLANARCONFIGURATION


IG_ISIS_TAG_COMPRESSION

Data compression. 0x0103 · 259

Category: ISIS.

Description

IG_ISIS_TAG_COMPRESSION allows you to set or determine the compression being used by a scanner.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

All source and destination drivers.

Values

The application must get choices (using IG_ISIS_choice_get_long) to be aware of the number of possible compression settings available in a scanner. Most scanners either return uncompressed only or uncompressed and Group 4 compressed data. To determine the compression format that exists in a file or other image data, use IG_ISIS_tag_get_long. The following values define the various compression choices that were available when this manual was last revised:

1
IG_ISIS_COMPRESSION_NONE
No compression, each line is packed to one byte.
2
IG_ISIS_COMPRESSION_MG3
Modified (no EOL) CCITT Group 3 1-Dimensional Huffman run-length encoding, each line starts on a new byte. BitsPerSample and SamplesPerPixel must be 1, since this type of compression is defined only for binary images.
3
IG_ISIS_COMPRESSION_G3
Standard CCITT Group 3 coding, 1 Dimensional Huffman run-length encoding. BitsPerSample and SamplesPerPixel must be 1, since this type of compression is defined only for binary images.
4
IG_ISIS_COMPRESSION_G4
Standard CCITT Group 4 encoding. BitsPerSample and SamplesPerPixel must be 1, since this type of compression is defined only for binary images.
5
IG_ISIS_COMPRESSION_LZW
LZW coding as described in the TIFF specification.
6
IG_ISIS_COMPRESSION_JPEG
JPEG coding typically used for grayscale and color only.
32771
IG_ISIS_COMPRESSION_32771
No compression, each line padded to two bytes. (Erroneously called IG_ISIS_ COMPRESSION_N16 in previous documentation.)
32773
IG_ISIS_COMPRESSION_PACK
Packbits compression.
34661
IG_ISIS_COMPRESSION_JBIG
JBIG compression, typically used for binary and grayscale only and returned by very few scanners, is a lossless multi-plane compression format that yields high compression for most business documents. This data can be written to a TIFF file that can be uncompressed and converted into another format.
50000
IG_ISIS_COMPRESSION_PCX
Compression scheme used in PCX files.
50001
IG_ISIS_COMPRESSION_4BYTE
No compression, each line padded to four bytes.
50002
IG_ISIS_COMPRESSION_RUN
Runlist compression; internal use only.
50005
IG_ISIS_COMPRESSION_GIF
Compression scheme used in GIF files.
50006
IG_ISIS_COMPRESSION_BMP
Compression scheme used in BMP files.
50007
IG_ISIS_COMPRESSION_RUNBLOCK
A block of runlists; internal use only.
50014
IG_ISIS_COMPRESSION_WANGJPEG
Wang format JPEG encoding, typically used for grayscale and color only.

Tag Dependencies and Dependent Tags

Some scanner drivers may reset the value of IG_ISIS_TAG_COMPRESSION based on the values of the color format tags. For example, it does not make sense to use JPEG compression on a binary PCX file, because there are no applications that will open such a file. Therefore, you should be sure to set IG_ISIS_TAG_COMPRESSION after setting the desired color format.

IG_ISIS_TAG_SAMPLESPERPIXEL ® IG_ISIS_TAG_BITSPERSAMPLE ® IG_ISIS_TAG_PHOTOMETRICINTERPRETATION ® IG_ISIS_TAG_COMPRESSION

See Also

IG_ISIS_TAG_BITSPERSAMPLE, IG_ISIS_TAG_SAMPLESPERPIXEL, IG_ISIS_TAG_PHOTOMETRICINTERPRETATION.


IG_ISIS_TAG_FILLORDER

Logical order of bits within a byte. 0x010A · 266

Category: ISIS, Required [TIFF].

Description

IG_ISIS_TAG_FILLORDER allows an application to specify or determine the order in which bits are stored in a byte.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

All scanner drivers.

Values

The only legal values for IG_ISIS_TAG_FILLORDER are:

1
IG_ISIS_FILLORDER_MSBLEFT
Pixels are arranged within a byte such that pixels with lower column values are stored in the higher-order bits of the byte. The first bit of the first byte corresponds to the first pixel on an uncompressed binary page.
2
IG_ISIS_FILLORDER_MSBRIGHT
Pixels are arranged within a byte such that pixels with lower column values are stored in the lower order bits of the byte. The last bit of the first byte corresponds to the first pixel on an uncompressed binary page.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_FILLORDER applies only to binary images; therefore it has the following dependencies:

IG_ISIS_TAG_FILETYPE ® IG_ISIS_TAG_SAMPLESPERPIXEL ® IG_ISIS_TAG_BITSPERSAMPLE ® IG_ISIS_TAG_PHOTOMETRICINTERPRETATION ® IG_ISIS_TAG_FILLORDER

Usage

Used only for binary images, IG_ISIS_TAG_FILLORDER lets you indicate the order of pixels in the image data's bytes. The default value is MSB_LEFT, and this value should be used except in unusual circumstances.

Strictly speaking, this tag is optional; however, certain applications require this tag to be defined or they will not load the driver. Therefore, all ISIS drivers from Pixel create this tag.


IG_ISIS_TAG_JBIGOPTIONS

Options for JBIG data. 0x87BE · 34750

Category: ISIS, Optional.

Description

IG_ISIS_TAG_JBIGOPTIONS allows an application to determine or specify various options when working with a JBIG data source.

Type

IG_ISIS_TAG_TYPE_BYTE

Drivers

Drivers for scanners that are capable of generating JBIG files, PIXFPACK.

Values

IG_ISIS_TAG_JBIGOPTIONS consists of 20 bytes that comprise the JBIG header, and have the following values:

Byte
Value
Meaning
0
0
Reserved. (Used for progressive JBIG only 1.)
1
0
Reserved. (Used for progressive JBIG only.)
2
1
Number of planes.
3
0
Always zero.
4-7
Pixels
(Motorola format.)
8-11
Lines
(Motorola format.)
12-15
LinesPerStrip
(Motorola format.)
16
Typically 8
Maximum Adaptive Template pixel horizontal movement
17
Typically 0
Maximum Adaptive Template pixel vertical movement
18
0
Progressive mode ordering. (Not used.)
19
Bit 7 = 0
Always zero.
19
Bit 6
1 = Two-line template; 0 = Three-line template
19
Bit 5 = 0
(Used in progressive JBIG.)
19
Bit 4 = 0
(Used in progressive JBIG.)
19
Bit 3
1 = Typical prediction on; 0 = Typical prediction off.
19
Bit 2 = 0
(Used in progressive JBIG.)
19
Bit 1 = 0
(Used in progressive JBIG.)
19
Bit 0 = 0
(Used in progressive JBIG.)

Usage

Use IG_ISIS_TAG_JBIGOPTIONS to set or read the JBIG header when working with a scanner capable of delivering JBIG data. JBIG compression is currently only available when using a Fujitsu 3099 scanner to produce JBIG data. This data can be written to a TIFF file, but cannot be uncompressed, converted to another compression format.

Information on progressive JBIG will be provided when drivers exist that support it.


IG_ISIS_TAG_KFACTOR

Parameter K for CCITT G32D. 0x050c · 1292

Category: ISIS, Optional [TIFF] (Read-only).

Description

IG_ISIS_TAG_KFACTOR contains the "Parameter K" value as defined in the CCITT Specification for Group 3 two-dimensional compression. It is generated in compressed images from ISIS drivers that support Group 3 2D compression.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for scanners that output Group 3 2D compressed image data.

Values

An integer specifying the K factor. Often set to 4.

See Also

IG_ISIS_TAG_COMPRESSION.


IG_ISIS_TAG_MAXDCXIFDSIZE

Maximum size of DCX offsets list. 0x0912 · 2322

Category: ISIS, Optional.

Description

IG_ISIS_TAG_MAXDCXIFDSIZE allows an application or a driver to set the maximum size of the DCX offsets list.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

None.

Values

Integer which specifies maximum number of bytes to allocate for the offsets list. The value IG_ISIS_TAG_MAXDCXIFDSIZE_DEFAULT is predefined as 1024, which is the default size in the DCX specification.


IG_ISIS_TAG_PLANARCONFIGURATION

How the components of an RGB image are arranged. 0x011C · 284

Category: ISIS, Optional [TIFF] (Required for color).

Description

IG_ISIS_TAG_PLANARCONFIGURATION describes how data in a color RGB image is arranged. This arrangements is often determined by whether you are dealing with a one-pass or three-pas color scanner.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for scanners that output color image data, PIXFPACK.

Values

1
IG_ISIS_PLANARCONFIG_LINE or IG_ISIS_PLANARCONFIG_LINE_ PACK
Line pack. Color data for each pixel is stored in order by line:RGBRGBRGBRGBRGBRGB... RGBEach RGB set represents one pixel of a line. Each line is padded to an even byte boundary. This is probably the easiest format to handle because the data for each pixel is in one place. Supported in TIFF.
2
IG_ISIS_PLANARCONFIG_PAGE
Page. Color data for the entire page is stored by color plane:RRRRRRRRRRRRRRRRRR... RRRRRRRRRRRRRRRRRRRRR... RRRRRRRRRRRRRRRRRRRRR... RRR .GGGGGGGGGGGGGGGGGG... GGGGGGGGGGGGGGGGGGGGG... GGGGGGGGGGGGGGGGGGGGG... GGG .BBBBBBBBBBBBBBBBBB... BBBBBBBBBBBBBBBBBBBBB... BBBBBBBBBBBBBBBBBBBBB... BBBEach RRR... represents red for the entire page. Each line is padded to an even byte boundary. This is common for 3-pass scanners. Supported in TIFF.
5000
IG_ISIS_PLANARCONFIG_ LINE_UNPACK
Line Unpack. Color data for each line is stored by color plane:RRRRRRRRRRRRRRRRRR... RRRGGGGGGGGGGGGGGGGGG... GGGBBBBBBBBBBBBBBBBBB... BBBRRRRRRRRRRRRRRRRRR... RRRGGGGGGGGGGGGGGGGGG... GGGEach RRR... set represents red for an entire line. Each line is padded to an even byte boundary. This format is not supported by TIFF, but the toolkit can be made to save TIFF files using this configuration, which can then be read only by this toolkit. Note that PCX 24-bit color requires this format, and many color scanners return data in this format.

Tag Dependencies and Dependent Tags

The following tags together define the color format of the image data:

IG_ISIS_TAG_SAMPLESPERPIXEL ® IG_ISIS_TAG_BITSPERSAMPLE ® IG_ISIS_TAG_PHOTOMETRICINTERPRETATION ® IG_ISIS_TAG_COMPRESSION ® IG_ISIS_TAG_PLANARCONFIGURATION

IG_ISIS_TAG_PLANARCONFIGURATION is only valid for RGB color images.

See Also

IG_ISIS_TAG_BITSPERSAMPLE, IG_ISIS_TAG_SAMPLESPERPIXEL, IG_ISIS_TAG_PHOTOMETRICINTERPRETATION.


Image Interpretation Tags

There are the following Image Interpretation tags:

  • IG_ISIS_TAG_COLORMAP
  • IG_ISIS_TAG_COLORRESPONSECURVES
  • IG_ISIS_TAG_DATAORIENTATION
  • IG_ISIS_TAG_GRAYRESPONSECURVE
  • IG_ISIS_TAG_GRAYRESPONSEUNIT
  • IG_ISIS_TAG_ORIENTATION
  • IG_ISIS_TAG_PRIMARYCHROMATICITIES
  • IG_ISIS_TAG_WHITEPOINT


IG_ISIS_TAG_COLORMAP

Color map for palette color images. 0x0140 · 320

Category: ISIS, Optional [TIFF].

Description

IG_ISIS_TAG_COLORMAP describes a Red-Green-Blue color map (often called a lookup table) for palette color images, and is used by PIXFPACK and the individual file format filters (*.PXIs) to pass color palette information along with the image.

Type

IG_ISIS_TAG_TYPE_SHORT (array)

Drivers

PIXFPACK.

Values

IG_ISIS_TAG_COLORMAP contains the palette values for a palette image. It has 3 x 2BitsPerSample values. A four-bit palette requires 48 values; an eight-bit palette requires 756 values. All red values come first, followed by all green values, then by all blue values. A value of zero (0) is the absence of that color; a value of 65535 is the maximum amount (saturation) of that color.

Usage

In a palette color image, a pixel's value is used to index into an RGB lookup table. For example, a palette color pixel having a value of 0 would be displayed according to the color specified in the 0th entry in IG_ISIS_TAG_COLORMAP.

The IG_ISIS_TAG_COLORMAP tag is set automatically by ISIS file reading and file writing drivers when they are handling a palette image, and so in most cases, the application developer need not be concerned with this tag.


IG_ISIS_TAG_COLORRESPONSECURVES

Optical density of each pixel value. 0x012D · 301

Category: Custom TIFF.

Description

IG_ISIS_TAG_COLORRESPONSECURVES controls the optical density of each possible pixel value in a color image.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

None.

Values

Either one or three arrays, depending on whether the image has a single value for all color channels, or a separate value for each color channel.

Usage

This ia a TIFF tag that used in describing TIFF files. It is not used by ISIS. Refer to the TIFF Specification's description of the TransferFunction tag.

See Also

IG_ISIS_TAG_PHOTOMETRICINTERPRETATION.


IG_ISIS_TAG_DATAORIENTATION

Actual orientation of image data. 0x0114 · 276

Category: ISIS, Optional.

Description

IG_ISIS_TAG_DATAORIENTATION indicates or specifies the orientation when getting data from certain scanner drivers. If IG_ISIS_TAG_DATAORIENTATION is implemented in the scanner driver, then the scanner has the capability of internally rotating the image and the driver can be queried to determine whether or not the scanner is rotating the image.

Type

IG_ISIS_TAG_TYPE_SHORT

Values

IG_ISIS_TAG_DATAORIENTATION can be set to any one of the following values:

1
IG_ISIS_ORIENTATION_PORT
The image data is in portrait orientation.
2
IG_ISIS_ORIENTATION_LAND
The image data is in landscape orientation.
3
IG_ISIS_ORIENTATION_180
The image data is in upside-down portrait orientation.
4
IG_ISIS_ORIENTATION_270
The image data is in upside-down landscape orientation.
5
IG_ISIS_ORIENTATION_PORTM
The image data is in portrait mirrored orientation.
6
IG_ISIS_ORIENTATION_LANDM
The image data is in landscape mirrored orientation.
7
IG_ISIS_ORIENTATION_180M
In ISIS, the image data is in upside down portrait, mirrored orientation.
8
IG_ISIS_ORIENTATION_270M
The image data is in upside down landscape, mirrored orientation.

Usage

In ISIS, check for the existence of IG_ISIS_TAG_DATAORIENTATION in the currently-selected scanner driver. If this tag exists, check its choices to determine the rotation the scanner is capable of delivering. It you are scanning a portrait, letter-sized page sideways ("Scan and Rotate") to achieve better throughput, AND the scanner implements IG_ISIS_TAG_DATAORIENTATION, AND IG_ISIS_TAG_DATAORIENTATION is IG_ISIS_TAG_DATAORIENTATION_PORT, then the scanner is rotating the data for you, and you should not rotate it. On the other hand, if IG_ISIS_TAG_DATAORIENTATION is not implemented OR if IG_ISIS_TAG_DATAORIENTATION is set to IG_ISIS_TAG_DATAORIENTATION_LAND, then the scanner is not rotating the data for you and you should rotate it.

See Also

IG_ISIS_TAG_ORIENTATION, IG_ISIS_TAG_SCANORIENTATION.


IG_ISIS_TAG_GRAYRESPONSECURVE

Optical density of each pixel value. 0x0123 · 291

Category: Custom TIFF.

Description

IG_ISIS_TAG_GRAYRESPONSECURVE controls the optical density of each possible pixel value in a grayscale image.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

None.

Values

The 0th value of IG_ISIS_TAG_GRAYRESPONSECURVE corresponds to the optical density of a pixel having a value of zero. The tag contains 2BitsPerSample values to define the density of each possible pixel value in the image.

Usage

This tag is not used by ISIS and is not normally used by TIFF, but is defined by the TIFF specification. It is currently ignored by many TIFF readers.

See Also

IG_ISIS_TAG_GRAYRESPONSEUNIT, IG_ISIS_TAG_PHOTOMETRICINTERPRETATION.


IG_ISIS_TAG_GRAYRESPONSEUNIT

Precision of values in IG_ISIS_TAG_GRAYRESPONSECURVE. 0x0122 · 290

Category: Custom TIFF.

Description

IG_ISIS_TAG_GRAYRESPONSEUNIT the precision of the values contained in IG_ISIS_TAG_GRAYRESPONSECURVE.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

None

Values

The precision is specified as an integer that represents a power of tenths factor. For example, if IG_ISIS_TAG_GRAYRESPONSEUNIT is set to 4, this represents then-thousandths of a unit, and a IG_ISIS_TAG_GRAYRESPONSECURVE value for a particular gray level is 3455, then the actual value is 0.3455.

Usage

Optical densitometers typically measure densities in the range of 0.0 to 2.0. For historical reasons, the default IG_ISIS_TAG_GRAYRESPONSEUNIT is 2; however, the TIFF specification recommends using 3 for greater accuracy.

See Also

IG_ISIS_TAG_GRAYRESPONSECURVE.


IG_ISIS_TAG_ORIENTATION

Orientation of the image. 0x0112 · 274

Category: ISIS, Optional [TIFF 1].

Description

IG_ISIS_TAG_ORIENTATION describes the orientation of the image with respect to rows and columns.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

PIXFPACK.

Values

IG_ISIS_TAG_ORIENTATION can contain any one of the following values:

ISIS Value
TIFF Value
Defined Constant
Meaning
1
1
IG_ISIS_ORIENTATION_PORT
Portrait (0°). The 0th row represents the visual top of the image and the 0th column represents the visual left side.
2
8
IG_ISIS_ORIENTATION_LAND
Landscape (90° ccw). The 0th row represents the visual left side of the image and the 0th column represents the visual bottom.
3
3
IG_ISIS_ORIENTATION_180
Upside down portrait (180° ccw). The 0th row represents the visual bottom of the image and the 0th column represents the visual right side.
4
6
IG_ISIS_ORIENTATION_270
Upside down landscape (270° ccw). The 0th row represents the visual right side of the image, and the 0th column represents the visual top.
5
2
IG_ISIS_ORIENTATION_PORTM
Portrait mirrored. The 0th row represents the visual top of the image, and the 0th column represents the visual right side.
6
5
IG_ISIS_ORIENTATION_LANDM
Landscape mirrored. The 0th row represents the visual left side of the image, and the 0th column represents the visual top.
7
4
IG_ISIS_ORIENTATION_180M
Upside down portrait mirrored. The 0th row represents the visual bottom of the image, and the 0th column represents the visual left side. This is the orientation in which Windows BMP files are stored.
8
7
IG_ISIS_ORIENTATION_270M
Upside down landscape mirrored. The 0th row represents the visual right side of the image, and the 0th column represents the visual bottom.

See Also

IG_ISIS_TAG_SCANORIENTATION, IG_ISIS_TAG_DATAORIENTATION.


IG_ISIS_TAG_PRIMARYCHROMATICITIES

Chromaticities of the image's primary colors. 0x013F · 319

Category: Custom TIFF.

Description

IG_ISIS_TAG_PRIMARYCHROMATICITIES specifies the chromaticity of the primaries of the image.

Type

IG_ISIS_TAG_TYPE_RATIONAL

Drivers

None.

Values

An array of six rational value specifying the x and y chromaticities of red, green, and blue.

Usage

Refer to the TIFF specification.


IG_ISIS_TAG_WHITEPOINT

Chromaticity of the image's white point. 0x013E · 318

Category: ISIS, Optional [TIFF].

Description

IG_ISIS_TAG_WHITEPOINT specifies the chromaticity of the white point of the image. This is the chromaticity when each of the primaries has its ReferenceWhite value.

Type

IG_ISIS_TAG_TYPE_RATIONAL

Drivers

Drivers for scanners that support setting white point chromaticity. Currently, the only driver that supports this is the Dunord ISIS driver DUNISIS.PXW.

Values

A rational value specifying the white point.

Usage

Refer to the TIFF specification.


Image Quality Tags

There are the following Image Quality tags:

  • IG_ISIS_TAG_BRIGHTNESS
  • IG_ISIS_TAG_CONTRAST
  • IG_ISIS_TAG_DITHER_LENGTH1
  • IG_ISIS_TAG_DITHER_LENGTH2
  • IG_ISIS_TAG_DITHER_PATTERN1
  • IG_ISIS_TAG_DITHER_PATTERN2
  • IG_ISIS_TAG_DITHER_WIDTH1
  • IG_ISIS_TAG_DITHER_WIDTH2
  • IG_ISIS_TAG_EMPHASIS
  • IG_ISIS_TAG_GAMMA
  • IG_ISIS_TAG_GAMMA_LENGTHn
  • IG_ISIS_TAG_GAMMA_TABLEn
  • IG_ISIS_TAG_MIXEDSCAN
  • IG_ISIS_TAG_OUTLINE
  • IG_ISIS_TAG_RESPONSECURVE
  • IG_ISIS_TAG_TRCMAP8


IG_ISIS_TAG_BRIGHTNESS

Scanner's or displayed image's brightness setting. 0x0502 · 1282

Category: ISIS, Required.

Description

IG_ISIS_TAG_BRIGHTNESS allows you to set or read the brightness setting of a scanner or displayed image.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

All scanner drivers.

Values

The application must get choices (using IG_ISIS_choice_get_long) to be aware of the number of possible positive brightness settings as well as the following special values for IG_ISIS_TAG_BRIGHTNESS. Higher numbers produce lighter pages. These values were chosen so that all possible combinations of brightness can be represented by a single range of values. All scanners support values of at least -2 through 0, and many support, for example, 1 through 127 as well (providing 128 brightness steps).

Value
Defined Constant
Meaning
-3
IG_ISIS_BRIGHTNESS_AUTO
Set brightness value automatically based on real-time sampling during scanning.
-2
IG_ISIS_BRIGHTNESS_DARKEN
Lighten the page relative to IG_ISIS_BRIGHTNESS_NORM. This will result in a particular value being set based on tests conducted by the designer of the scanner driver. To determine this value, read the value of IG_ISIS_TAG_BRIGHTNESS.
-1
IG_ISIS_BRIGHTNESS_NORM
Select a "normal" brightness. This will result in a particular value being set based on tests conducted when the scanner driver was designed. Each model of scanner may have a different IG_ISIS_BRIGHTNESS_ NORM value To determine this value, get the value of IG_ISIS_TAG_BRIGHTNESS.
0
IG_ISIS_BRIGHTNESS_LIGHTEN
Darken the page relative to IG_ISIS_BRIGHTNESS_NORM. This will result in a particular value being set based on tests conducted by the designer of the scanner driver. To determine this value, read the value of IG_ISIS_TAG_BRIGHTNESS.

See Also

IG_ISIS_TAG_CONTRAST.


IG_ISIS_TAG_CONTRAST

Scanner's contrast setting. 0x0501 · 1281

Category: ISIS, Required.

Description

IG_ISIS_TAG_CONTRAST sets or reads the contrast setting of a scanner.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

All scanner drivers.

Values

A value of IG_ISIS_TAG_CONTRAST_AUTO (0) means automatic contrast control or that no contrast control is available. A value greater than zero indicates a specific contrast setting. Higher numbers mean higher contrast.

See Also

IG_ISIS_TAG_BRIGHTNESS.


IG_ISIS_TAG_DITHER_LENGTH1

Length of custom dither pattern. 0x0518 · 1304

Category: ISIS, Optional.

Description

For scanners that support downloadable dithering patterns, IG_ISIS_TAG_DITHER_LENGTH1 specifies the length of the downloadable dithering pattern.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support at least one downloadable dither pattern.

Values

An integer value specifying the length of the downloadable dither pattern. In a four by eight pattern, this value would be 8.

Usage

See IG_ISIS_TAG_DITHER_PATTERN1.

See Also

IG_ISIS_TAG_DITHER_WIDTH1, IG_ISIS_TAG_DITHER_PATTERN1.


IG_ISIS_TAG_DITHER_LENGTH2

Length of custom dither pattern. 0x0519 · 1305

Category: ISIS, Optional.

Description

For scanners that support two downloadable dithering patterns, IG_ISIS_TAG_DITHER_LENGTH2 specifies the length of the second downloadable dithering pattern.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanner that support at least two downloadable dither patterns.

Values

An integer value specifying the length of the downloadable dither pattern.

Usage

See IG_ISIS_TAG_DITHER_PATTERN2.

See Also

IG_ISIS_TAG_DITHER_WIDTH2, IG_ISIS_TAG_DITHER_PATTERN2.


IG_ISIS_TAG_DITHER_PATTERN1

Custom dither pattern data. 0x0548 · 1352

Category: ISIS, Optional.

Description

For scanners that support downloadable dithering patterns, IG_ISIS_TAG_DITHER_PATTERN1 specifies the data for each element of the downloadable dithering pattern.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanner that support at least one downloadable dither pattern.

Values

An array of values, each with valid choices in the range of 0 - 255, that specify the data for a rectangular downloadable dither pattern. This tag has a number of elements equal to the product of IG_ISIS_TAG_DITHER_LENGTH1 and IG_ISIS_TAG_DITHER_WIDTH1.

Bayer Dither [64 steps]

8 8

4 129 35 161 12 137 43 169

192 67 224 98 200 75 231 106

51 177 20 145 59 184 27 153

239 114 208 82 247 122 216 90

16 141 47 173 8 133 39 165

204 78 235 110 196 71 228 102

63 188 31 157 55 180 24 149

251 126 220 94 243 118 212 86

The first line of the file is the name of the dither pattern. The second line specifies the width and then length of the dither pattern. The rest of the file contains the actual dither values.

Usage

To create a downloadable dithering pattern, establish a width and length of the pattern, then fill in the values for each element of the pattern by calling IG_ISIS_tag_set_long. You can also let the user select an existing dither file by calling IG_ISIS_drv_read_dither_file. For more information on downloadable dither patterns, consult the documentation supplied with scanners that support downloadable dither patterns.

See Also

IG_ISIS_TAG_DITHER_LENGTH1, IG_ISIS_TAG_DITHER_WIDTH1, IG_ISIS_TAG_DITHER_PATTERN2, IG_ISIS_drv_read_dither_file.


IG_ISIS_TAG_DITHER_PATTERN2

Custom dither pattern data. 0x0549 · 1353

Category: ISIS, Optional.

Description

For scanners that support two downloadable dithering patterns, IG_ISIS_TAG_DITHER_PATTERN2 specifies the data for each element of the second downloadable dithering pattern.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support at least two downloadable dither patterns.

Values

An array of values, each with valid choices in the range of 0 - 255, that specify the data for a rectangular custom dither pattern. This tag has a number of elements equal to the product of IG_ISIS_TAG_DITHER_LENGTH2 and IG_ISIS_TAG_DITHER_WIDTH2.

Usage

To create a downloadable dithering pattern, establish a width and length of the pattern, then fill in the values for each element of the pattern by calling IG_ISIS_tag_set_long. You can also let the user select an existing dither file by calling IG_ISIS_drv_read_dither_file. For more information on downloadable dither patterns, consult the documentation supplied with scanners that support downloadable dither patterns.

See Also

IG_ISIS_TAG_DITHER_PATTERN1, IG_ISIS_TAG_DITHER_WIDTH2, IG_ISIS_TAG_DITHER_LENGTH2, IG_ISIS_drv_read_dither_file.


IG_ISIS_TAG_DITHER_WIDTH1

Width of custom dither pattern. 0x0538 · 1336

Category: ISIS, Optional.

Description

For scanners that support downloadable dithering patterns, IG_ISIS_TAG_DITHER_WIDTH1 specifies the width of the downloadable dithering pattern.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support at least one downloadable dither pattern.

Values

An integer value specifying the width of the downloadable dither pattern. In a four by eight pattern, this value would be 4.

Usage

See IG_ISIS_TAG_DITHER_PATTERN1.

See Also

IG_ISIS_TAG_DITHER_LENGTH1, IG_ISIS_TAG_DITHER_PATTERN1.


IG_ISIS_TAG_DITHER_WIDTH2

Width of custom dither pattern. 0x0539 · 1337

Category: ISIS, Optional.

Description

For scanners that support two downloadable dithering patterns, IG_ISIS_TAG_DITHER_WIDTH2 specifies the width of the second downloadable dithering pattern.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support at least two downloadable dither patterns.

Values

An integer value specifying the width of the downloadable dither pattern.

Usage

See IG_ISIS_TAG_DITHER_PATTERN2.

See Also

IG_ISIS_TAG_DITHER_LENGTH2, IG_ISIS_TAG_DITHER_PATTERN2.


IG_ISIS_TAG_EMPHASIS

Scanner's emphasis setting. 0x0510 · 1296

Category: ISIS, Optional.

Description

For those scanners that provide an emphasis feature, IG_ISIS_TAG_EMPHASIS allows an application to determine or specify a scanner's emphasis setting.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

All scanner drivers.

Values

Value
Defined Constant
Meaning
0
IG_ISIS_EMPHASIS_OFF
No emphasis.
1
IG_ISIS_EMPHASIS_LOW
Low emphasis setting.
2
IG_ISIS_EMPHASIS_MEDIUM
Medium emphasis setting.
3
IG_ISIS_EMPHASIS_HIGH
High emphasis setting.
4
IG_ISIS_EMPHASIS_SMOOTH
Smooth emphasis setting.

Usage

Consult your scanner's documentation for information on how to use the emphasis settings.


IG_ISIS_TAG_GAMMA

Gamma curve adjustment for scanning. 0x050F · 1295

Category: ISIS, Optional.

Description

IG_ISIS_TAG_GAMMA allows an application to adjust the scanner's gamma curve.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for all scanners that have either automatic or downloadable gamma correction tables.

Values

Legal values for IG_ISIS_TAG_GAMMA include the following, but may also include other values depending on the scanner's specific capabilities. Query the choices for IG_ISIS_TAG_GAMMA to determine the specific values available from the currently-selected scanner.

Value
Defined Constant
Meaning
0
IG_ISIS_GAMMA_AUTO
Scanner's gamma correction is set to automatic.
0x80
IG_ISIS_GAMMA_DOWNLOAD1
Scanner's gamma correction is set to the first downloaded correction table.
0x81
IG_ISIS_GAMMA_DOWNLOAD2
Scanner's gamma correction is set to the second downloaded correction table.
0x82
IG_ISIS_GAMMA_DOWNLOAD3
Scanner's gamma correction is set to the third downloaded correction table.
0x83
IG_ISIS_GAMMA_DOWNLOAD4
Scanner's gamma correction is set to the fourth downloaded correction table.
0x84
IG_ISIS_GAMMA_DOWNLOAD5
Scanner's gamma correction is set to the fifth downloaded correction table.
0x85
IG_ISIS_GAMMA_DOWNLOAD6
Scanner's gamma correction is set to the sixth downloaded correction table.

The downloadable gamma tables are typically lists of 256 values.

Usage

Not all scanners support gamma correction. Of those that do, some provide automatic gamma correction, and may provide downloadable gamma correction tables. Other scanners have built-in gamma correction values that are specific to the scanner. For example, the Ricoh IS-520 has many values, including IG_ISIS_TAG_GAMMA_BOTTOMCLIP, IG_ISIS_TAG_GAMMA_1TO1INVERT, IG_ISIS_TAG_GAMMA_SHARP_61, and so forth. Refer to your scanner's documentation and to the individual scanner tag documentation included with this toolkit for additional information.


IG_ISIS_TAG_GAMMA_LENGTHn

Length of custom gamma table. 0x0558-0x055D · 1368-1373

Category: ISIS, Optional.

Description

For scanners that support downloadable gamma correction curves, IG_ISIS_TAG_GAMMA_LENGTHn specifies the length of the downloadable gamma table.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support at least one downloadable gamma table.

Values

An integer value specifying the length of the downloadable gamma table.

Usage

There are currently six tags in this group: IG_ISIS_TAG_GAMMA_LENGTH1 through IG_ISIS_TAG_GAMMA_LENGTH6. Each IG_ISIS_TAG_GAMMA_LENGTHn tag holds the length of the gamma table stored in its corresponding IG_ISIS_TAG_GAMMA_TABLEn tag.

See Also

IG_ISIS_TAG_GAMMA_TABLEn.


IG_ISIS_TAG_GAMMA_TABLEn

Length of custom gamma table. 0x0568-0x056D · 1384-1389

Category: ISIS, Optional.

Description

For scanners that support downloadable gamma correction curves, IG_ISIS_TAG_GAMMA_TABLEn specifies the data for each element of the downloadable gamma table.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support at least one downloadable gamma table.

Values

A list of value, each with valid choices in the range of 0 - 255, that specifys the data for a downloadable gamma correction curve. Each tag in this group has a number of elements equal to the length value in its corresponding IG_ISIS_TAG_GAMMA_LENTHn tag.

Inverted linear gamma curve

256

255

254

253

<... values continue to descend...>

2

1

0

The first line in the file is the description of the gamma curve. The other lines are the actual gamma table data.

Usage

There are currently six tags in this group: IG_ISIS_TAG_GAMMA_TABLE1 through IG_ISIS_TAG_GAMMA_TABLE6. To create a downloadable gamma table, establish a length for the table, then fill in the values for each element of the table by calling IG_ISIS_tag_set_long. You can also let the user select an existing gamma file by calling IG_ISIS_drv_read_gamma_file. For more information on downloadable gamma tables, consult the documentation supplied with scanners that support downloadable gamma tables.

See Also

IG_ISIS_TAG_GAMMA, IG_ISIS_TAG_GAMMA_LENGTHn, IG_ISIS_drv_read_gamma_file.


IG_ISIS_TAG_MIXEDSCAN

Scanner's mixed scanning setting. 0x0511 · 1297

Category: ISIS, Optional.

Description

For scanners that provide an intelligent text/image mixed scanning feature, IG_ISIS_TAG_MIXEDSCAN allows an application to control whether this setting is on or off. Mixed scanning provides a means to capture dithered binary data from non-textual areas of the page, and non-dithered binary from the textual portions, providing the best readability for both text and graphics with a single scan.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for scanners that support mixed scanning.

Values

Value
Defined Constant
Meaning
0
IG_ISIS_MIXEDSCAN_OFF
Do not perform mixed scanning.
1
IG_ISIS_MIXEDSCAN_ON
Perform mixed scanning.

Usage

Consult your scanner's documentation for information about how to use its mixed scanning feature.


IG_ISIS_TAG_OUTLINE

Scanner's outline setting. 0x05A6 · 1446

Category: ISIS, Optional.

Description

For scanners that provide an outline feature, IG_ISIS_TAG_OUTLINE allows an application to control whether this setting is on or off.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for scanners that have an outline feature.

Values

Value
Defined Constant
Meaning
0
IG_ISIS_OUTLINE_OFF
Do not perform outline scanning.
1
IG_ISIS_OUTLINE_ON
Perform outline scanning.

Usage

Consult your scanner's documentation for information about how to use its outline scanning feature.


IG_ISIS_TAG_RESPONSECURVE

Scanner's response curve setting. 0x0516 · 1302

Category: ISIS, Optional.

Description

For scanners that support mapping image values, IG_ISIS_TAG_RESPONSECURVE defines particular mapping values.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for scanners that support an adjustable response curve.

Values

Value
Defined Constant
Meaning
0
IG_ISIS_RESPONSETYPE_BRIGHTCONT
Image is scanned with contrast and brightness.
1
IG_ISIS_RESPONSETYPE_TRCMAP8
A mapping of eight-bit input values to 8-bit output values is used, as defined in IG_ISIS_TAG_TRCMAP8.

Usage

Consult your scanner's documentation for information about how to map brightness and contrast settings.

See Also

IG_ISIS_TAG_TRCMAP8.


IG_ISIS_TAG_TRCMAP8

Map of input to output levels. 0x0517 · 1303

Category: ISIS, Optional.

Description

IG_ISIS_TAG_TRCMAP8 allows an arbitrary mapping of eight-bit input levels to eight-bit output levels and may, depending on the scanner, affect binary and other modes as well.

Type

IG_ISIS_TAG_TYPE_BYTE

Drivers

Drivers for scanners that implement mapping of input levels to output levels. Currently only the Dunord ISIS driver DUNISIS.PXW implements this tag.

Values

IG_ISIS_TAG_TRCMAP8 has 256 elements, each with valid choices in the range of 0 to 255.

See Also

IG_ISIS_TAG_RESPONSECURVE.


Miscellaneous Tags

There are the following Miscellaneous tags:

  • 0 (Zero)
  • IG_ISIS_TAG_ADFTIMEOUT
  • IG_ISIS_TAG_BELL
  • IG_ISIS_TAG_BUFSIZE
  • IG_ISIS_TAG_ENDORSER_STRING
  • IG_ISIS_TAG_IMAGEDESCRIPTION
  • IG_ISIS_TAG_SCANTYPE
  • IG_ISIS_TAG_SCANNERID
  • IG_ISIS_TAG_USER0 - 99
  • IG_ISIS_TAG_YIELDPROC


0 (Zero)

List of all tags. 0x0000 · 0

Category: ISIS, Required (Read-only).

Description

The special tag 0 (Zero) allows an application to determine all of the tags that a particular driver supports.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

All.

Values

The 0 tag contains a list of all the tags as numeric values. Use IG_ISIS_tag_get_length to get the number of tags, and then use IG_ISIS_tag_get_long with an index value to get the list of tags.

Example

HISISDRV hDriver;  //Set to valid ISIS driver handle.
DWORD uNumTags, uTag;
INT32 lValue;
//Determine number of tags in driver.
IG_ISIS_tag_get_length(hDriver, 0, &uNumTags);
//Cycle through tags in driver.
for (uTag = 0; uTag < uNumTags; uTag++)
{
    //Find out tag number at index position.
    IG_ISIS_tag_get_long(hDriver, 0, uTag, &lValue);
    //Do something with lValue.
}


IG_ISIS_TAG_ADFTIMEOUT

Timeout value for ADF empty condition. 0x06A5 · 1701

Category: ISIS, Optional.

Description

For scanners that support this tag, IG_ISIS_TAG_ADFTIMEOUT specifies the time in seconds that scanner spends attempting to read the next page before reporting that no page was found.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Scanner drivers that support the IG_ISIS_TAG_ADFTIMEOUT tag, including some configurations of Bell & Howell, Kofax, Ricoh, and Kodak.

Values

Integer value representing number of seconds to wait.


IG_ISIS_TAG_BELL

Scanner's bell status. 0x0508 · 1288

Category: ISIS, Required.

Description

IG_ISIS_TAG_BELL lets an application determine whether or not a scanner has an audible alert device. (Read-only.)

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

All scanner drivers.

Values

IG_ISIS_TAG_BELL returns 1 if the scanner has an audible device; 0 otherwise. Note that you cannot use any toolkit functions to activate the alert device; you can only determine whether or not one exists.


IG_ISIS_TAG_BUFSIZE

Size of driver's image buffer. 0x0507 · 1287

Category: ISIS, Required (Read-only).

Description

IG_ISIS_TAG_BUFSIZE lets a driver specify the size of its preferred image buffer. In almost every case, IG_ISIS_TAG_BUFSIZE is set to 8192, which has been shown to be an optimum value almost always.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

All.

Values

Almost always 8192.

Usage

This is an old, mostly unused tag that is included for compatibility only. An application can query the value of IG_ISIS_TAG_BUFSIZE to determine a driver's preferred buffer size to be used in IG_ISIS_run_zone. We recommend that you use 8192 without querying for the preferred buffer size.


IG_ISIS_TAG_ENDORSER_STRING

String to send to scanner's endorser. 0x0583 · 1411

Category: ISIS, Optional.

Description

IG_ISIS_TAG_ENDORSER_STRING is the ASCII string to be printed by the scanner's endorser, if available.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

Drivers for all scanners that have an endorser.

Values

The values acceptable to an endorser are specific to the scanner. Various scanners will support a different set of possible characters, a different maximum number of characters, and may support other tags that control endorsement position, orientation, size, and so forth.

Usage

The application must check for the presence of an endorser by checking whether or not this tag exists (by checking the return value of IG_ISIS_tag_get_ascii, for example). For more information about endorser capabilities, refer to the specific scanner's tag on-line documents included with this release.

See Also

ISISNOTE.TXT, RICOTAGS.WRI, KOFAX20.WRI.


IG_ISIS_TAG_IMAGEDESCRIPTION

Image description string. 0x010E · 270

Category: Custom TIFF.

Description

IG_ISIS_TAG_IMAGEDESCRIPTION can contain a string that describes the subject of the image.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

None.

Values

A string of the user's or application's choice which describes the subject of the image.

Usage

IG_ISIS_TAG_IMAGEDESCRIPTION is not used by any ISIS driver, and must be defined as a custom tag to be used within the toolkit. It is defined in the TIFF specification and may be used in TIFF files. A user may wish, for example, to attach a string to an image such as "Company Picnic, 1996."


IG_ISIS_TAG_SCANTYPE

Scanning source. 0x0514 · 1300

Category: ISIS, Optional.

Description

IG_ISIS_TAG_SCANTYPE specifies the scanning source (flatbed, feeder, and so forth) on those scanners that support this functionality.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for scanners that support selecting the source of the scanned image.

Values

IG_ISIS_TAG_SCANTYPE can be set to any one of the following values:

Value
Defined Constant
Meaning
0
IG_ISIS_SCANTYPE_AUTOMATIC
Scan from the ADF if pages are detected; otherwise, scan from the flatbed.
1
IG_ISIS_SCANTYPE_TRANSPARENCY
Scan from the transparency unit.
2
IG_ISIS_SCANTYPE_FLATBED
Scan from the flatbed.
3
IG_ISIS_SCANTYPE_FEEDERIG_ISIS_SCANTYPE_FRONTONLY
Scan only the front side of the page (duplex scanner).
4
IG_ISIS_SCANTYPE_DUPLEXIG_ISIS_SCANTYPE_FRONTBACK
Scan in duplex mode (duplex scanner), from the feeder.
5
IG_ISIS_SCANTYPE_BACKFRONT
Scan in duplex mode, but return the back side of the page first (duplex scanner), from the feeder.
6
IG_ISIS_SCANTYPE_BACKONLY
Scan only the back side of the page (duplex scanner), from the feeder.

IG_ISIS_TAG_SCANTYPE_AUTOMATIC is the default value.

Usage

For scanners that implement IG_ISIS_TAG_SCANTYPE, your application can control the source of the scan. For other scanners, most will scan as though this tag is set to IG_ISIS_TAG_SCANTYPE_AUTOMATIC. You can query the choices of this tag to determine the capabilities of the currently-selected scanner.

See Also

IG_ISIS_TAG_FEEDER.


IG_ISIS_TAG_SCANNERID

Unique scanner identification string. 0x050A · 1290

Category: ISIS, Optional (Read-only).

Description

IG_ISIS_TAG_SCANNERID returns a unique ASCII string for each supported scanner. If a driver supports more than one scanner, it must return a different string for each scanner.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

Most scanner drivers.

Values

A string containing the identification of the currently-selected scanner.

Usage

This tag returns values for section names in the SETSCAN.INI file. Application developers may find it useful to use this tag to save tags that the toolkit does not save, or to identify a particular scanner when used with a driver that does not identify the scanner, such as KOFAXBIC.


IG_ISIS_TAG_USER0 - 99

User (driver) defined tags. 0x0700 - 0x0763 · 1792 - 1891

Category: ISIS, Optional.

Description

IG_ISIS_TAG_USER_0 through IG_ISIS_TAG_USER_99 have special purposes which depend on each driver. For example, the SHOWDIB sample-only driver (a Windows 3.1 driver that can display an image in a window) uses IG_ISIS_TAG_USER0 to hold the window handle.

Type

Driver-defined.

Drivers

PIXFPACK.

Values

Driver-defined.

Usage

A knowledge of the implementation of these tags is required in order to understand how to use them. Note that these are the only tags which are not automatically forwarded when set.

These tags are defined in header files but do not exist unless a custom driver creates them. They are provided as preset tag values that a driver can use to pass values without concern for conflicting with existing tag definitions.


IG_ISIS_TAG_YIELDPROC

Address of a yield function. 0x0513 · 1299

Category: ISIS, Optional.

Description

IG_ISIS_TAG_YIELDPROC sets the address of an application-defined yield function.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support application yield processing.

Values

A pointer to the address of a yield function int FAR PASCAL function

(void) that has been defined in the application. If IG_ISIS_TAG_YIELDPROC is set to zero, no yielding will occur.

Usage

IG_ISIS_TAG_YIELDPROC allows your application to implement a yield function so that your application, and other applications, can obtain processor attention when the toolkit is busy scanning, reading, or writing a file. If you are using Windows, your YieldProc must be in the DEF file, and you must use MakeProcInstance to get an address to your callback.

Not all scanner drivers support this functionality. However, by using a IG_ISIS_drv_run_start/step/done loop that contains a yieldproc, you can achieve this functionality for all scanners.


Other Dialog Box Tags

There are the following Other Dialog Box tags:

  • IG_ISIS_TAG_CONFIGURATIONS
  • IG_ISIS_TAG_CONFIG_1 - 4
  • IG_ISIS_TAG_MORE_SETTINGS


IG_ISIS_TAG_CONFIGURATIONS

Driver-defined user configuration names. 0x0600 · 1536

Category: ISIS, Optional (Choices-only).

Description

IG_ISIS_TAG_CONFIGURATIONS gives an application the ability to obtain names for one or more driver-defined user default settings. The value of this tag has no meaning. The choices for this tag contain the names of each defined user configuration (IG_ISIS_TAG_CONFIG_1 through IG_ISIS_TAG_CONFIG_4).

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

Many scanner drivers.

Values

The choices for IG_ISIS_TAG_CONFIGURATIONS contain the names of the user configurations that have been defined in the driver with IG_ISIS_TAG_CONFIG_1 through IG_ISIS_TAG_CONFIG_4. The value of this tag has no meaning. You can get these configuration names by calling IG_ISIS_choice_get_ascii. Typical values are:

  • "Default Paper Size"
  • "Default SCSI Address"
  • "Default I/O Address"

and so forth.

Usage

By using IG_ISIS_TAG_CONFIGURATIONS, your application can provide a mechanism to allow the user to choose default values for certain critical tags. By letting the user choose a default page size, the scanner driver will always initialize the scanner to the value that the user has set.

For an example of using IG_ISIS_TAG_CONFIGURATIONS, first delete your SETSCAN.INI file to ensure that no scanner has already been selected and configured. Then run the sample application, choose a scanner, and note the resulting configuration dialog box that appears. If the scanner you are using has no user configurations defined, you will see a message box similar containing a message such as:

"This scanner's configuration is set using the system-level driver."

Otherwise, you will see a dialog box similar to the following:

The dialog box above is one of the dialog boxes built into the ImageGear ISIS toolkit and is displayed by calling IG_ISIS_drv_configure.

Tag Dependencies and Dependent Tags

The choices returned when you query choices on IG_ISIS_TAG_CONFIGURATIONS depend on the values defined in the driver for IG_ISIS_TAG_CONFIG_1 through IG_ISIS_TAG_CONFIG_4.

See Also

IG_ISIS_TAG_CONFIG_1 - 4, IG_ISIS_drv_configure.


IG_ISIS_TAG_CONFIG_1 - 4

Driver-defined user defaults. 0x0601 - 0x0604 · 1537 - 1540

Category: ISIS, Optional.

Description

IG_ISIS_TAG_CONFIG_1 through IG_ISIS_TAG_CONFIG_4 are used inside drivers to give the user the ability to set certain default parameters.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

All scanner drivers that implement IG_ISIS_TAG_CONFIGURATIONS.

Values

The values for IG_ISIS_TAG_CONFIG_1 through IG_ISIS_TAG_CONFIG_4 (if defined in the driver) contain the current user default settings for whatever tags the driver has associated them with. The default values are read from SETSCAN.INI and are checked only once, when the driver is loaded. Once default values are set, the current values can be changed to any other valid values at any time by the user. Each time the driver is reloaded, the default values are restored.

Usage

IG_ISIS_TAG_CONFIG_1 through IG_ISIS_TAG_CONFIG_4 are used by driver developers only. Once they are defined, the tags for which they are associated are set automatically to the user-defined default values as previously explained. The following illustrations shows how these tags appear to the user.

See Also

IG_ISIS_TAG_CONFIGURATIONS, IG_ISIS_drv_configure.


IG_ISIS_TAG_MORE_SETTINGS

More Settings dialog exists in scanner driver. 0x0512 · 1298

Category: ISIS, Optional.

Description

IG_ISIS_TAG_MORE_SETTINGS indicates whether or not the scanner driver impelements a More Settings dialog box and activates the More button in the standard Scanner Settings dialog box.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for all scanners that employ a "More Settings" dialog box.

Values

1
A More Settings dialog box exists in the driver. Enable the More button in the Scanner Settings dialog.
0
A More Settings dialog box does not exist in the driver. Disable the More button in the Scanner Settings dialog.

Usage

When your application calls IG_ISIS_drv_set_dialog to display the built-in Scanner Settings dialog box, the function checks the value of IG_ISIS_TAG_MORE_SETTINGS to determine whether or not the scanner driver has its own More Settings dialog box (as many high-end scanners do). If IG_ISIS_TAG_MORE_SETTINGS has a non-zero value, then the More button of the dialog is automatically enabled. The More Settings dialog box can be displayed independently by calling the IG_ISIS_drv_set_more function:

lStatus = IG_ISIS_drv_set_more(lpDriver, hWnd);

where hWnd is the handle of the parent window.

See Also

IG_ISIS_drv_set_dialog, IG_ISIS_drv_set_more.


Position and Resolution Tags

There are the following Position and Resolution tags:

  • IG_ISIS_TAG_IMAGELENGTH
  • IG_ISIS_TAG_IMAGEWIDTH
  • IG_ISIS_TAG_PAGESIZE
  • IG_ISIS_TAG_RESUNIT
  • IG_ISIS_TAG_XPOSITION
  • IG_ISIS_TAG_XRESOLUTION
  • IG_ISIS_TAG_YPOSITION
  • IG_ISIS_TAG_YRESOLUTION


IG_ISIS_TAG_IMAGELENGTH

Number of rows in the image. 0x0101 · 257

Category: ISIS, Required [TIFF].

Description

IG_ISIS_TAG_IMAGELENGTH contains the number of rows of pixels (height) in an image.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

All source and destination drivers, any many compression drivers.

Values

An integer specifying the number of rows of pixels in the image.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_IMAGELENGTH is reset to the full height of the page when several other tags are set; therefore the following dependencies must be observed:

IG_ISIS_TAG_PAGESIZE ® IG_ISIS_TAG_XRESOLUTION ® IG_ISIS_TAG_YRESOLUTION ® IG_ISIS_TAG_XPOSITION ® IG_ISIS_TAG_YPOSITION ® IG_ISIS_TAG_IMAGEWIDTH® IG_ISIS_TAG_IMAGELENGTH

Usage

IG_ISIS_TAG_IMAGELENGTH is required by a number of image viewing applications as well as file writing drivers and any other processes that need to know the number of rows in the image.

See Also

IG_ISIS_TAG_PAGESIZE, IG_ISIS_TAG_IMAGEWIDTH, IG_ISIS_TAG_YPOSITION, IG_ISIS_TAG_YRESOLUTION.


IG_ISIS_TAG_IMAGEWIDTH

Number of columns in the image. 0x0100 · 256

Category: ISIS, Required [TIFF].

Description

IG_ISIS_TAG_IMAGEWIDTH contains the number of columns of pixels (width) in an image.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

All source and destination drivers, any many compression drivers.

Values

An integer specifying the number of columns of pixels in the image (View: from 1 to IG_ISIS_TAG_IMAGEWIDTH_MAX).

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_IMAGEWIDTH is reset to the full width of the page when several other tags are set; therefore the following dependencies must be observed:

IG_ISIS_TAG_PAGESIZE ® IG_ISIS_TAG_XRESOLUTION ® IG_ISIS_TAG_YRESOLUTION ® IG_ISIS_TAG_XPOSITION ® IG_ISIS_TAG_YPOSITION ® IG_ISIS_TAG_IMAGEWIDTH ® IG_ISIS_TAG_IMAGELENGTH

Usage

IG_ISIS_TAG_IMAGEWIDTH is required by a number of image viewing applications as well as file writing drivers and any other processes that need to know the number of columns in the image.

NOTE: Many scanners can only scan areas with widths that are divisible by eight, or some other number. You must use IG_ISIS_choice_get_long(lpDriver, IG_ISIS_TAG_IMAGEWIDTH, IG_ISIS_CHOICE_STEP, lplValue) to determine the minimum increment.

See Also

IG_ISIS_TAG_PAGESIZE, IG_ISIS_TAG_IMAGELENGTH, IG_ISIS_TAG_XRESOLUTION, IG_ISIS_TAG_XPOSITION.


IG_ISIS_TAG_PAGESIZE

Scanner page size setting. 0x050E · 1294

Category: ISIS, Optional.

Description

IG_ISIS_TAG_PAGESIZE allows the application to obtain and then subsequently set the size of the page that the scanner is to scan.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

Drivers for scanners that support setting the desired page size. In addition, for scanners that do not support setting of page sizes, PIXDFLT has several predefined page sizes.

Values

String containing the current page size to scan; for example, "Letter - 8.5 x 11 in", "Legal - 8.5 x 14 in", "A4 - 210 x 297 mm", and "Scanner's Maximum". The choices for IG_ISIS_TAG_PAGESIZE contain the entire set of page size values defined in the currently-selected scanner driver.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_PAGESIZE affects the values of several other tags and so should be set before all of these other tags:

IG_ISIS_TAG_PAGESIZE ® IG_ISIS_TAG_XRESOLUTION ® IG_ISIS_TAG_YRESOLUTION ® IG_ISIS_TAG_XPOSITION ® IG_ISIS_TAG_YPOSITION ® IG_ISIS_TAG_IMAGEWIDTH ® IG_ISIS_TAG_IMAGELENGTH

Usage

Start by getting the choices for IG_ISIS_TAG_PAGESIZE from the scanner driver. These choices are ASCII strings that vary according to the scanner make, model, and the language of the driver. Display these choices for the user. When the user picks a choice, set this ASCII value on the driver.

If the scanner driver does not support settable page sizes, you can pass in IG_ISIS_DRV_LOAD_NEED_PAGESIZE in the IG_ISIS_drv_is_loaded call and PIXDFLT will return its set of predefined page sizes, from which the user can choose. Choosing one of these predefined page sizes from PIXDFLT is equivalent to (but easier than) setting a scanning area. To the user, the effect is the same: a page of the desired size is obtained.

See Also

IG_ISIS_TAG_XRESOLUTION, IG_ISIS_TAG_YRESOLUTION, IG_ISIS_TAG_XPOSITION, IG_ISIS_TAG_YPOSITION, IG_ISIS_TAG_IMAGELENGTH, IG_ISIS_TAG_IMAGEWIDTH.


IG_ISIS_TAG_RESUNIT

Unit of resolution measurement. 0x0128 · 296

Category: ISIS, Optional (Read-only).

Description

IG_ISIS_TAG_RESUNIT contains the unit of measurement for XResolution and YResolution.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

PIXFPACK. Note that resolution for ISIS drivers is always specified in dots per inch.

Values

Value
Defined Constant
Meaning
1
IG_ISIS_RESUNIT_NONE 1
No absolute unit of measurement. Used for images that may have a non-square aspect ratio, but no meaningful absolute dimensions.
2
IG_ISIS_RESUNIT_INCH
Resolution is specified in dots per inch.
3
IG_ISIS_RESUNIT_CENTIMETER
Resolution is specified in dots per centimeter.

The default value is 2 (IG_ISIS_TAG_RESUNIT_INCH).

The drawback to this value is that different applications will import the image at different sizes. Even if the decision is arbitrary, it might be a good idea to use dots per inch or dots per centimeter, and to pick XResolution and YResolution so that the aspect ratio is correct and the maximum dimension of the image is about an arbitrary four inches.


IG_ISIS_TAG_XPOSITION

Distance from left of page. 0x011E · 286

Category: ISIS, Required [TIFF].

Description

IG_ISIS_TAG_XPOSITION specifies or designates the distance in pixels from the left edge of the page to the start of the image.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

All source and destination drivers.

Values

An integer specifying the X position.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_PAGESIZE ® IG_ISIS_TAG_XRESOLUTION ® IG_ISIS_TAG_YRESOLUTION ® IG_ISIS_TAG_XPOSITION ® IG_ISIS_TAG_YPOSITION ® IG_ISIS_TAG_IMAGEWIDTH ® IG_ISIS_TAG_IMAGELENGTH

Usage

IG_ISIS_TAG_XPOSITION is used to specify a scan area starting position.

See Also

IG_ISIS_TAG_PAGESIZE, IG_ISIS_TAG_IMAGELENGTH, IG_ISIS_TAG_XRESOLUTION, IG_ISIS_TAG_IMAGEWIDTH.


IG_ISIS_TAG_XRESOLUTION

Horizontal resolution. 0x011A · 282

Category: ISIS, Required [TIFF].

Description

IG_ISIS_TAG_XRESOLUTION specifies or indicates the number of pixels per IG_ISIS_TAG_RESUNIT (which for ISIS scanning is always pixels per inch).

Type

IG_ISIS_TAG_TYPE_RATIONAL

Drivers

All source and destination drivers.

Values

A rational value specifying the horizontal resolution in pixels per inch.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_PAGESIZE ® IG_ISIS_TAG_XRESOLUTION ® IG_ISIS_TAG_YRESOLUTION ® IG_ISIS_TAG_XPOSITION ® IG_ISIS_TAG_YPOSITION ® IG_ISIS_TAG_IMAGEWIDTH ® IG_ISIS_TAG_IMAGELENGTH

Note that setting IG_ISIS_TAG_XRESOLUTION sets IG_ISIS_TAG_YRESOLUTION to the same value. If you want to set independent resolutions, you must set IG_ISIS_TAG_YRESOLUTION after setting IG_ISIS_TAG_XRESOLUTION.

Usage

IG_ISIS_TAG_XRESOLUTION is used to specify the horizontal (and usually the vertical) resolution. When scanning, this controls the scanner's resolution. Query the choices for IG_ISIS_TAG_XRESOLUTION to determine the available settings. To find out whether or not the scanner supports independent X and Y resolutions, query the choices for IG_ISIS_TAG_YRESOLUTION. If there is only one choice, and it matches the value set for IG_ISIS_TAG_XRESOLUTION, then the scanner does not support independent resolutions.

When reading an image, IG_ISIS_TAG_XRESOLUTION, if present, indicates the value of the Resolution tag that has been saved in the file.

See Also

IG_ISIS_TAG_PAGESIZE, IG_ISIS_TAG_IMAGELENGTH, IG_ISIS_TAG_YRESOLUTION, IG_ISIS_TAG_IMAGEWIDTH.


IG_ISIS_TAG_YPOSITION

Distance from top of page. 0x011F · 287

Category: ISIS, Required [TIFF].

Description

IG_ISIS_TAG_YPOSITION specifies or designates the distance in pixels from the top edge of the page to the start of the image.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

All source and destination drivers.

Values

An integer specifying the Y position.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_PAGESIZE ® IG_ISIS_TAG_XRESOLUTION ® IG_ISIS_TAG_YRESOLUTION ® IG_ISIS_TAG_XPOSITION ® IG_ISIS_TAG_YPOSITION ® IG_ISIS_TAG_IMAGEWIDTH ® IG_ISIS_TAG_IMAGELENGTH

Usage

IG_ISIS_TAG_YPOSITION is used to specify a scan area starting position.

See Also

IG_ISIS_TAG_PAGESIZE, IG_ISIS_TAG_IMAGELENGTH, IG_ISIS_TAG_XRESOLUTION, IG_ISIS_TAG_YRESOLUTION, IG_ISIS_TAG_IMAGEWIDTH.


IG_ISIS_TAG_YRESOLUTION

Vertical resolution. 0x011B · 283

Category: ISIS, Required [TIFF].

Description

IG_ISIS_TAG_YRESOLUTION specifies or indicates the number of pixels per IG_ISIS_TAG_RESUNIT (which for ISIS scanning is always pixels per inch).

Type

IG_ISIS_TAG_TYPE_RATIONAL

Drivers

All source and destination drivers.

Values

A rational value specifying the vertical resolution in pixels per inch.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_PAGESIZE ® IG_ISIS_TAG_XRESOLUTION ® IG_ISIS_TAG_YRESOLUTION ® IG_ISIS_TAG_XPOSITION ® IG_ISIS_TAG_YPOSITION ® IG_ISIS_TAG_IMAGEWIDTH ® IG_ISIS_TAG_IMAGELENGTH

Note that setting IG_ISIS_TAG_XRESOLUTION sets IG_ISIS_TAG_YRESOLUTION to the same value. If you want to set independent resolutions, you must set IG_ISIS_TAG_YRESOLUTION after setting IG_ISIS_TAG_XRESOLUTION.

Usage

IG_ISIS_TAG_YRESOLUTION is used to specify the vertical resolution on scanners that support independent X and Y resolutions.

When scanning, this controls the scanner's resolution. Query the choices for IG_ISIS_TAG_XRESOLUTION to determine the available settings. To find out whether or not the scanner supports independent X and Y resolutions, query the choices for IG_ISIS_TAG_YRESOLUTION. If there is only one choice, and it matches the value set for IG_ISIS_TAG_XRESOLUTION, then the scanner does not support independent resolutions.

When reading an image, IG_ISIS_TAG_YRESOLUTION, if present, indicates the value of the Resolution tag that has been saved in the file.

See Also

IG_ISIS_TAG_PAGESIZE, IG_ISIS_TAG_IMAGELENGTH, IG_ISIS_TAG_XRESOLUTION, IG_ISIS_TAG_YPOSITION, IG_ISIS_TAG_IMAGEWIDTH.


Scanning Mode Tags

There are the following Scanning Mode tags:

  • IG_ISIS_TAG_BITSPERSAMPLE
  • IG_ISIS_TAG_DETECTJOBSEP
  • IG_ISIS_TAG_DITHER
  • IG_ISIS_TAG_FEEDER
  • IG_ISIS_TAG_JOBSEPDETECTED
  • IG_ISIS_TAG_LASTPAGE_SIDE
  • IG_ISIS_TAG_MAXPAGES
  • IG_ISIS_TAG_MAXTIME
  • IG_ISIS_TAG_PHOTOMETRICINTERPRETATION
  • IG_ISIS_TAG_PLATENLENGTH
  • IG_ISIS_TAG_SAMPLESPERPIXEL
  • IG_ISIS_TAG_SCANAHEAD
  • IG_ISIS_TAG_SCANAHEAD_MAXPAGES
  • IG_ISIS_TAG_SCANAHEAD_PAGES
  • IG_ISIS_TAG_SCANORIENTATION


IG_ISIS_TAG_BITSPERSAMPLE

Number of bits per component. 0x0102 · 258

Category: ISIS, Required.

Description

IG_ISIS_TAG_BITSPERSAMPLE allows you to specify or determine the number of bits in each sample. (A sample is one color plane of an image, so a binary or grayscale image has one sample, while a color image has three or four samples, depending on the color model (RGB, HSB, or CMYK) being used.)

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

All source and destination drivers.

Values

Value
Meaning
1
One bit per sample.
4
Four bits per sample.
8
Eight bits per sample.

Tag Dependencies and Dependent Tags

The following tags together define the color format of the image data:

IG_ISIS_TAG_SAMPLESPERPIXEL ® IG_ISIS_TAG_BITSPERSAMPLE ® IG_ISIS_TAG_PHOTOMETRICINTERPRETATION ® IG_ISIS_TAG_COMPRESSION ® IG_ISIS_TAG_PLANARCONFIGURATION

These tags relate to color format as shown in the following table:

Samples PerPixel
BitsPerSample
Photometric Interpretation
Image Type
1
1
WHITE0 or WHITE1
Binary (black/white)
1
4
WHITE0 typical WHITE1 possible
16-level gray
8
256-level gray
1
4
PALETTE
16-color palette
8
256-color palette
3
1
RGB
3-bit color
8
24-bit color

See Also

IG_ISIS_TAG_SAMPLESPERPIXEL, IG_ISIS_TAG_PHOTOMETRICINTERPRETATION, IG_ISIS_TAG_PLANARCONFIGURATION.


IG_ISIS_TAG_DETECTJOBSEP

Mode for detecting job separator sheets. 0x05A7 · 1447

Category: ISIS, Optional.

Description

IG_ISIS_TAG_DETECTJOBSEP indicates or specifies the current mode for detecting job separator sheets during scanning.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for scanners that support batch or job separator sheet detection.

Values

IG_ISIS_TAG_DETECTJOBSEP can be set to any one of the following values:

Meaning
Value
Defined Constant
Batch detection not enabled.
0
IG_ISIS_DETECTJOBSEP_OFF
Detect and scan separator, continue ScanAhead.
1
IG_ISIS_DETECTJOBSEP_NOSTOP_NOEJECT
Detect and scan separator, stop ScanAhead.
3
IG_ISIS_DETECTJOBSEP_STOP_NOEJECT
Detect and skip separator, continue ScanAhead.
2
IG_ISIS_DETECTSJOBSEP_NOSTOP_EJECT
5
IG_ISIS_DETECTJOBSEP_NOSTOP_EJTSCAN
Detect and skip separator, stop ScanAhead.
4
IG_ISIS_DETECTJOBSEP_STOP_EJECT
6
IG_ISIS_DETECTJOBSEP_STOP_EJTSCAN

Usage

There are two basic settings to consider when detecting job separators. The first setting applies to the separator sheet itself. When a separator sheet is detected, it can either be scanned into the document like any other page, or it can be skipped. The second setting applies to scanners that support ScanAhead. You can choose whether you want to stop ScanAhead when a separator sheet is detected. If you choose to stop ScanAhead, you may change scanner settings for the next batch of pages. If you do not stop ScanAhead, you cannot change your scanner settings because more pages may have already been scanned ahead using the current settings.

When a separator sheet is detected and IG_ISIS_TAG_DETECTJOBSEP is set to any value other than 0, IG_ISIS_run_zone will stop with the error IG_ISIS_ERR_BATCHSEP, and IG_ISIS_TAG_JOBSEPDETECTED will have a non-zero value.

The constants IG_ISIS_DETECTJOBSEP_NOSTOP_EJECT and IG_ISIS_DETECTJOBSEP_NOSTOP_EJTSCAN are equivalent in meaning and mutually exclusive. Some scanners support the first constant, while others support the second, never both. You should query the valid choices for IG_ISIS_TAG_DETECTJOBSEP supported on your scanner to determine the proper constants to use. The same applies to IG_ISIS_DETECTJOBSEP_STOP_EJECT and IG_ISIS_DETECTJOBSEP_STOP_EJTSCAN.

Example

The following example sets the batch detection mode to "detect and skip separator, continue ScanAhead" then checks for job separator sheets detected during the scan loop:

/* set batch detection to Detect and skip separator, continue
ScanAhead */
IG_ISIS_tag_set_long(hDriver, IG_ISIS_TAG_DETECTJOBSEP, 0,
IG_ISIS_DETECTJOBSEP_NOSTOP_EJTSCAN);
/* somewhere later in the code */
while (1) {
    /* check for a page in the ADF */
    lStatus = IG_ISIS_drv_is_page_loaded(hDriver, 0,
&lPageLoaded);
    /* if no pages in the ADF, batch detection is irrelevent */
    if (lPageLoaded != IG_ISIS_DRV_STACKPAGE)
        break;
    /* scan the page */
lStatus = IG_ISIS_run_zone(hDriver, buffer, sizeof(buffer));
    /* check for a separator sheet here */
    IG_ISIS_tag_get_long(hDriver, IG_ISIS_TAG_JOBSEPDETECTED, 0,
&lJobSepDetected);
    if (lStatus == IG_ISIS_ERR_BATCHSEP || lJobSepDetected != 0)
{
        printf("Job seperator was just detected.\n");
        /* if in _STOP mode, we can break out of the loop or
change scan settings */
        /* if in _NOSTOP mode, we should keep scanning */
}
}

See Also

IG_ISIS_TAG_JOBSEPDETECTED.


IG_ISIS_TAG_DITHER

Scanner's dither settings. 0x0500 · 1280

Category: ISIS, Required.

Description

IG_ISIS_TAG_DITHER sets or reads the dither settings of a scanner.

Type

IG_ISIS_TAG_TYPE_STRING

Drivers

All scanner drivers.

Values

The application must get choices (using IG_ISIS_choice_get_ascii) to be aware of the number of values and the actual values of IG_ISIS_TAG_DITHER. Note that the first choice for this tag actually represents no dithering and is usually called "None." The actual values are defined within the scanner itself, and have names such as "A -- 8x8 w/53 grays," and "4x4 Diagonal." Scanners that support dithering store the IG_ISIS_TAG_DITHER values in an array. The lpwCount parameter of the IG_ISIS_choice_get_count function returns the number of dither choices for IG_ISIS_TAG_DITHER. The lpwLength parameter of the IG_ISIS_choice_get_asciiLength function returns the number of characters in each IG_ISIS_TAG_DITHER choice.

Tag Dependencies and Dependent Tags

Many scanners only support dithering of binary images, and so the following tags may affect whether IG_ISIS_TAG_DITHER reports values other than `None.' Furthermore, some scanners may return different choices for IG_ISIS_TAG_DITHER depending on the values of the color format tags.

IG_ISIS_TAG_SAMPLESPERPIXEL ® IG_ISIS_TAG_BITSPERSAMPLE ® IG_ISIS_TAG_PHOTOMETRICINTERPRETATION ® IG_ISIS_TAG_DITHER

Usage

Because dither patterns are unique to each scanner, there is no way to reduce the choices to numbers that can be understood programmatically. Your application must get the ASCII values of each of the IG_ISIS_TAG_DITHER choices, present them to the user, let the user make a selection, and then set the desired choice by setting the ASCII value.

See Also

IG_ISIS_TAG_SAMPLESPERPIXEL, IG_ISIS_TAG_BITSPERSAMPLE, IG_ISIS_TAG_PHOTOMETRICINTERPRETATION.


IG_ISIS_TAG_FEEDER

Information about a scanner's feeder. 0x0503 · 1283

Category: ISIS, Required (Read-only).

Description

IG_ISIS_TAG_FEEDER lets an application determine whether the scanner has a flatbed, feeder, or both, lets the application determine whether or not the scanner can detect whether there is paper in the feeder or flatbed, lets the application determine whether the scanner needs to scan a page to determine whether or not a page is in the feeder or flatbed, and further lets the application determine whether the scanner can safely stop a ScanAhead batch before pages run out in the feeder.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

All scanner drivers.

Values

The values for IG_ISIS_TAG_FEEDER are returned in a bit field whose bits can be checked for the following values:

Value
Defined Constant
Meaning
0x00000001
IG_ISIS_FEEDER_FEED
Scanner has a feeder.
0x00000002
IG_ISIS_FEEDER_FLAT
Scanner has a flatbed
0x00020000
IG_ISIS_FEEDER_TELLFLAT
Scanner can detect whether or not a page is on the flatbed. (Currently no scanners support this ability.)
0x00010000
IG_ISIS_FEEDER_TELLFEED
Scanner can detect whether or not a page is in the feeder.
0x00040000
IG_ISIS_FEEDER_TELLSCAN
Scanner can detect whether a page is loaded in the feeder only by committing a page. Whenever a page is committed, it should also be scanned. You must call IG_ISIS_run_zone to actually get the data from the page that is committed.
0x00080000
IG_ISIS_FEEDER_CENTERFEED
Scanner can center a page in the feeder.
0x00100000
IG_ISIS_FEEDER_CENTERFLAT
Scanner can detect whether or not a page is centered on the flatbed. (Currently no scanners support this ability.)
0x00200000
IG_ISIS_FEEDER_PAUSE
Scanner can safely stop a ScanAhead batch in the middle of the batch and recover all pages left in the buffer. Use this value in conjunction with IG_ISIS_TAG_SCANAHEAD.

See Also

IG_ISIS_TAG_SCANTYPE, IG_ISIS_drv_is_page_loaded, IG_ISIS_TAG_SCANAHEAD.


IG_ISIS_TAG_JOBSEPDETECTED

Status of job separator sheet detection. 0x05A8 · 1448

Category: ISIS, Optional (Read-only).

Description

IG_ISIS_TAG_JOBSEPDETECTED indicates whether the page that had just been scanned was a job separator sheet.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support batch or job separator sheet detection.

Values

0
No job separator sheet detected.
Any non-zero value
Job separator sheet detected.

Usage

Query IG_ISIS_TAG_JOBSEPDETECTED after scanning a page to determine if the page was a job separator sheet. Use IG_ISIS_TAG_DETECTJOBSEP to set up the desired or batch detection.

See Also

IG_ISIS_TAG_DETECTJOBSEP.


IG_ISIS_TAG_LASTPAGE_SIDE

Last side scanned during a duplex batch scan. 0x06FF · 1791

Category: ISIS, Optional.

Description

For scanners that support duplex scanning and can determine which side of a duplex page was last scanned, query IG_ISIS_TAG_LASTPAGE_SIDE after a IG_ISIS_run_zone call to determine the last side scanned.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Kodak and ScanOptics drivers only.

Values

Value
Defined Constant
Meaning
0
IG_ISIS_LASTPAGE_FRONT
Front side was just scanned.
1
IG_ISIS_LASTPAGE_BACK
Back side was just scanned.

Usage

You can use IG_ISIS_TAG_LASTPAGE_SIDE with scanners that support blank page suppression or if you want to implement a mini-driver to suppress blank pages.


IG_ISIS_TAG_MAXPAGES

Page capacity of scanner ADF. 0x0504 · 1284

Category: ISIS, Optional [Required if scanner has ADF].

Description

IG_ISIS_TAG_MAXPAGES contains the maximum number of pages which may be loaded at one time in a scanner's automatic document feeder.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for all scanners that have automatic document feeders.

Values

Integer value specifying the maximum capacity of the scanner's ADF.

Tag Dependencies and Dependent Tags

IG_ISIS_TAG_MAXPAGES applies only to scanners that have document feeders:

IG_ISIS_TAG_FEEDER ® IG_ISIS_TAG_MAXPAGES

Usage

This tag is required to exist in scanner drivers for scanners that have document feeders. You can use this information to allow your application to limit the number of pages that a user can scan at one time.

See Also

IG_ISIS_TAG_FEEDER.


IG_ISIS_TAG_MAXTIME

Maximum time required to scan a page. 0x0505 · 1285

Category: ISIS, Required.

Description

IG_ISIS_TAG_MAXTIME contains the maximum number of tenths of a second required for a scanner to scan a page.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

All scanner drivers.

Values

Integer value specifying the maximum number, in 1/10 seconds, required to scan a page.

Usage

Use IG_ISIS_TAG_MAXTIME to allow your application to exit from its scanning loop after a period of time that indicates that the scanner is not responding.


IG_ISIS_TAG_PHOTOMETRICINTERPRETATION

Color space of image data. 0x0106 · 262

Category: ISIS, Required [TIFF].

Description

IG_ISIS_TAG_PHOTOMETRICINTERPRETATION allows you to specify or determine the color arrangement of the image data. Pixel Translations used to recommend using this tag to invert binary images; however we now strongly recommend that you use IG_ISIS_TAG_INVERT instead, because it properly inverts grayscale and color images as well.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

All scanner drivers.

Values

Value
Defined Constant
Meaning
0
IG_ISIS_PHOTOMETRIC_WHITE0
0 is imaged as white, 1 is imaged as black.
1
IG_ISIS_PHOTOMETRIC_WHITE1
0 is imaged as black, 1 is imaged as white.
2
IG_ISIS_PHOTOMETRIC_RGB
RGB image
3
IG_ISIS_PHOTOMETRIC_PALETTE
Palette color image
120
IG_ISIS_PHOTOMETRIC_BGR
Same as RGB, but blue and red planes are reversed.

Tag Dependencies and Dependent Tags

The following tags together define the color format of the image data:

IG_ISIS_TAG_SAMPLESPERPIXEL ® IG_ISIS_TAG_BITSPERSAMPLE ® IG_ISIS_TAG_PHOTOMETRICINTERPRETATION ® IG_ISIS_TAG_COMPRESSION ® IG_ISIS_TAG_PLANARCONFIGURATION

These tags relate to color format as shown in the following table:

Samples PerPixel
BitsPerSample
Photometric Interpretation
Image Type
1
1
WHITE0 or WHITE1
Binary (black/white)
1
4
WHITE0 typical WHITE1 possible
16-level gray
8
256-level gray
1
4
PALETTE
16-color palette
8
256-color palette
3
1
RGB
3-bit color
8
24-bit color

See Also

IG_ISIS_TAG_SAMPLESPERPIXEL, IG_ISIS_TAG_BITSPERSAMPLE, IG_ISIS_TAG_PLANARCONFIGURATION.


IG_ISIS_TAG_PLATENLENGTH

Maximum flatbed length. 0x050B · 1291

Category: ISIS, Optional (Read-only).

Description

IG_ISIS_TAG_PLATENLENGTH is returns the maximum number of pixels which can be scanned from the scanner's platen (flatbed) at the current resolution.

Type

IG_ISIS_TAG_TYPE_LONG

Drivers

Drivers for scanners that support the platen length feature.

Values

An integer representing the number of pixels that can be scanned at the current resolution.

Usage

Use IG_ISIS_TAG_PLATENLENGTH to determine the maximum capacity of the scanner's flatbed. This may be less than IG_ISIS_TAG_IMAGELENGTH because IG_ISIS_TAG_IMAGELENGTH may reflect the maximum scan area from either the flatbed or the ADF.


IG_ISIS_TAG_SAMPLESPERPIXEL

Number of components per pixel. 0x0115 · 277

Category: ISIS, Required [TIFF].

Description

IG_ISIS_TAG_SAMPLESPERPIXEL contains the number of values each pixel uses to represent its data.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

All source and destination drivers.

Values

Value
Meaning
1
One sample per pixel. Binary, grayscale, and palette color images use this value.
3
Three samples per pixel. RGB color images use this value. Each pixel has three samples: one for red, one for green, and one for blue, regardless of how many bits are used to represent each sample.

The default value is 1.

Tag Dependencies and Dependent Tags

The following tags together define the color format of the image data:

IG_ISIS_TAG_SAMPLESPERPIXEL ® IG_ISIS_TAG_BITSPERSAMPLE ® IG_ISIS_TAG_PHOTOMETRICINTERPRETATION ® IG_ISIS_TAG_COMPRESSION ® IG_ISIS_TAG_PLANARCONFIGURATION

These tags relate to color format as shown in the following table:

Samples PerPixel
BitsPerSample
Photometric Interpretation
Image Type
1
1
WHITE0 or WHITE1
Binary (black/white)
1
4
WHITE0 typical WHITE1 possible
16-level gray
8
256-level gray
1
4
PALETTE
16-color palette
8
256-color palette
3
1
RGB
3-bit color
8
24-bit color

See Also

IG_ISIS_TAG_BITSPERSAMPLE, IG_ISIS_TAG_PHOTOMETRICINTERPRETATION, IG_ISIS_TAG_PLANARCONFIGURATION.


IG_ISIS_TAG_SCANAHEAD

Status of ScanAhead. 0x050D · 1293

Category: ISIS, Optional.

Description

IG_ISIS_TAG_SCANAHEAD returns or allows the application to set the state of the ScanAhead feature.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for scanners that support ScanAhead.

Values

Value
Defined Constant
Meaning
0
IG_ISIS_SCANAHEAD_NO
ScanAhead not enabled.
1
IG_ISIS_SCANAHEAD_YES
ScanAhead enabled.

Usage

Enable ScanAhead before calling IG_ISIS_run_zone to scan more pages than the application has requested. Either the scanner or the scanner driver will buffer the pages until they are requested by subsequent IG_ISIS_run_zone calls. Scanners which scan less than about 10 pages per minute typically do not support IG_ISIS_TAG_SCANAHEAD.

Usually, when the application scans a batch with ScanAhead enabled, it wants to scan all the pages in the feeder before exiting the scan loop. In some instances, such as if the application allows the user to cancel a batch during scanning, the application may need to stop scanning before the feeder is empty. At this point, there are often still pages left in the buffer that have already been scanned ahead. On most scanners, those pages will be lost. However, some high-speed scanners will allow those buffered pages to be retrieved if you stop the batch during the scan loop by setting IG_ISIS_TAG_SCANAHEAD to IG_ISIS_TAG_SCANAHEAD_NO. IG_ISIS_drv_is_page_loaded will then continue to report that a page is available until the buffer is empty. Query the IG_ISIS_TAG_FEEDER_PAUSE bit in IG_ISIS_TAG_FEEDER to determine if the scanner supports this feature.

Example

The following example scans a ScanAhead batch and optionally exits the scan loop if the scanner supports the pause feeder feature and the user chooses to cancel the batch:

IG_ISIS_tag_get_long(hDriver, IG_ISIS_TAG_FEEDER , 0, &lValue);
/* check if scanner supports pausing the feeder */
if (lValue & IG_ISIS_FEEDER_PAUSE)
    bFeederPause = 1;
else
    bFeederPause = 0;
IG_ISIS_tag_set_long(hDriver, IG_ISIS_TAG_SCANAHEAD, 0,
IG_ISIS_SCANAHEAD_YES);
IG_ISIS_drv_is_page_loaded(hDriver, IG_ISIS_FEEDER_FEED,
&lValue);
while (lValue & IG_ISIS_DRV_STACKPAGE)
{
    IG_ISIS_run_zone(lpDriver, Buffer, BUFSIZE);
/* stop batch if the user cancels */
    if (bFeederPause && CheckUserCancel())
        IG_ISIS_tag_set_long(hDriver, IG_ISIS_TAG_SCANAHEAD, 0,
IG_ISIS_SCANAHEAD_NO);
    IG_ISIS_drv_is_page_loaded(hDriver, IG_ISIS_FEEDER_FEED,
&lValue);
}

See Also

IG_ISIS_TAG_SCANAHEAD_PAGES, IG_ISIS_TAG_SCANAHEAD_MAXPAGES, IG_ISIS_TAG_FEEDER.


IG_ISIS_TAG_SCANAHEAD_MAXPAGES

Maximum number of pages to scan ahead. 0x057C · 1404

Category: ISIS, Optional.

Description

IG_ISIS_TAG_SCANAHEAD_MAXPAGES holds the maximum number of pages a user wants to scan.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for scanners that support ScanAhead.

Values

An integer specifying the maximum number of pages to scan ahead. A value of zero means scan until the feeder is empty. Some scanners (such as the Kodak ImageLink models) only support a value of zero because there is no way to tell the scanner how many pages to scan.

NOTE: Setting IG_ISIS_TAG_SCANAHEAD_MAXPAGES does not prevent a IG_ISIS_run_zone call from scanning a page after the specified number of pages have been scanned ahead. Your code must be designed to stop calling IG_ISIS_run_zone at this point if you indeed want to stop scanning.

See Also

IG_ISIS_TAG_SCANAHEAD_PAGES, IG_ISIS_TAG_SCANAHEAD, "ScanAhead™" on page 6-19.


IG_ISIS_TAG_SCANAHEAD_PAGES

Number of pages that have been scanned ahead. 0x0515 · 1301

Category: ISIS, Optional.

Description

IG_ISIS_TAG_SCANAHEAD_PAGES allows the application to find out how many pages have been scanned ahead so it can, for example, advise the user to rescan a certain number of pages after a misfeed or paper jam has occurred.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for scanners that support ScanAhead.

Values

An integer specifying the number of pages that have been scanned ahead.

Usage

Note that due to the type of information available from the scanner, IG_ISIS_TAG_SCANAHEAD_PAGES may not contain an accurate count of the number of pages that have been scanned ahead.

See Also

IG_ISIS_TAG_SCANAHEAD_MAXPAGES, IG_ISIS_TAG_SCANAHEAD, "ScanAhead™" on page 6-19.


IG_ISIS_TAG_SCANORIENTATION

Orientation in which to scan. 0x0113 · 275

Category: ISIS, Optional (Read-only).

Description

IG_ISIS_TAG_SCANORIENTATION indicates the orientation of a page in a scanner's feeder.

Type

IG_ISIS_TAG_TYPE_SHORT

Drivers

Drivers for scanners that support reporting of document feeder page orientation.

Values

IG_ISIS_TAG_SCANORIENTATION can be set to any one of the following values:

Value
Defined Constant
Meaning
1
IG_ISIS_ORIENTATION_PORT
The image data is in portrait orientation.
2
IG_ISIS_ORIENTATION_LAND
The image data is in landscape orientation.
3
IG_ISIS_ORIENTATION_180
The image data is in upside-down portrait orientation.
4
IG_ISIS_ORIENTATION_270
The image data is in upside-down landscape orientation.
5
IG_ISIS_ORIENTATION_PORTM
The image data is in portrait mirrored orientation.
6
IG_ISIS_ORIENTATION_LANDM
The image data is in landscape mirrored orientation.
7
IG_ISIS_ORIENTATION_180M
In ISIS, the image data is in upside down portrait, mirrored orientation.
8
IG_ISIS_ORIENTATION_270M
The image data is in upside down landscape, mirrored orientation.

Usage

Some scanners have the ability to detect the orientation of a page in the feeder, and can pass this information along in IG_ISIS_TAG_SCANORIENTATION. Your application can use this information to, for example, scan only 8.5 inches of a landscape letter-sized page rather than scanning 17 inches and then cropping the data.

See Also

IG_ISIS_TAG_ORIENTATION, IG_ISIS_TAG_DATAORIENTATION.


JPEG2000 Component API Function Reference

ImageGear JPEG2000 component provides access to JPIP Client/Server API and contains objects used to efficiently and dynamically stream portions of a JPEG2000-compressed image over a network. This chapter consist of two major parts:

  • JPIP Client API Reference
  • JPIP Server API Reference
NOTE: AccuSoft JPIP client and server API currently supports JPEG2000 Part I (JP2, JPC, J2K, J2C) format only.


JPIP Client API Reference

JPIP Client API represents the following functions, structures and enums:

  • IG_JPIPC_CB_register
  • IG_JPIPC_close
  • IG_JPIPC_connect
  • IG_JPIPC_create
  • IG_JPIPC_delete
  • IG_JPIPC_disconnect
  • IG_JPIPC_image_component_set
  • IG_JPIPC_image_export
  • IG_JPIPC_image_info_get
  • IG_JPIPC_image_orientation_set
  • IG_JPIPC_metadata_close
  • IG_JPIPC_metadata_find
  • IG_JPIPC_metadata_info_get
  • IG_JPIPC_metadata_next
  • IG_JPIPC_metadata_open
  • IG_JPIPC_metadata_read
  • IG_JPIPC_metadata_seek
  • IG_JPIPC_metareq_add
  • IG_JPIPC_metareq_clear
  • IG_JPIPC_metareq_count
  • IG_JPIPC_metareq_get
  • IG_JPIPC_status_get
  • IG_JPIPC_window_get
  • IG_JPIPC_window_set
  • LPFNIG_JPIPC_ERROR
  • LPFNIG_JPIPC_STATUS
  • AT_JPIPC_EXPORT_OPTIONS
  • AT_JPIPC_METADATA_INFO
  • AT_JPIPC_METAREQ
  • AT_JPIPC_STATUS
  • AT_JPIPC_WINDOW
  • enumJPIPCCBType
  • enumJPIPCChannelTransport
  • enumJPIPCRoundDirection
  • enumJPIPCQualifer


IG_JPIPC_CB_register

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_CB_register(
HIGJPIPC hClient,
LPAT_VOID lpfnCB,
AT_MODE nCBType,
LPAT_VOID lpPrivateData);

Arguments:

hClient
JPIP client object.
lpfnCB
Address of callback function.
nCBType
Type of callback function. See enumJPIPCCBType.
lpPrivateData
Private data to pass to callback function.

Description:

Registers a callback function. Callback functions must be registered before initiating a connection. The callback can be unregistered by passing NULL for the address of the callback function. The nCBType parameter is a value from enumJPIPCCBType which specifies the type of callback function being registered. The lpPrivateData parameter is passed to the callback function every time the callback function is called.

Return Value:

Error count.

Sample:

JPIPC.


IG_JPIPC_close

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_close(HIGJPIPC hClient);

Arguments:

hClient
JPIP client object.

Description:

This function disconnects from the server and discards the entire contents of the cache, causing future values of isAlive and isActive both to be FALSE. It is safe to call this function at any time, regardless of whether or not a connection has been successfully opened.

If IG_JPIPC_disconnect () has already been called, and the underlying transport channel has been saved, this function will not destroy it. That will happen only if a subsequent call to IG_JPIPC_connect cannot use it, if IG_JPIPC_disconnect () is called explicitly with keepTransportOpen = FALSE, or if the object is destroyed with IG_JPIPC_delete.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_connect

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_connect(
HIGJPIPC hClient,
AT_CHAR *lpServer,
AT_CHAR *lpProxy,
AT_CHAR *lpRequest,
AT_MODE channelTransport,
AT_CHAR *lpCacheDir);

Arguments:

hClient
JPIP client object.
lpServer
Server address (hostname or IP address) to connect to. If a port other than the default of 80 is to be used, the port number is appended to this address in standard colon delimited form. For example: 127.0.0.1:81, jpip.accusoft.com:8000
lpProxy
Address (hostname or IP address) of a proxy server to use when communicating with the JPIP server.
lpRequest
Request string to request upon connecting to the JPIP server.
channelTransport
Channel transport to use for communicating with the JPIP server. See enumeration enumJPIPCChannelTransport for it possible values.
lpCacheDir
Directory on the local machine to store cached data in. Future JPIP sessions can re-use this data to avoid downloading the same data from the server again. Specify NULL to disable caching.

Description:

This function initiates a connection to a JPIP server. This is done asynchronously, so this function always returns immediately.

Return Value:

Error count.

Sample:

JPIPC.


IG_JPIPC_create

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_create(LPHIGJPIPC phClient);

Arguments:

phClient
New JPIP client object.

Description:

This function creates a new JPIP client object and returns its handle. This handle must be passed to all other JPIP client API calls. This object represents a single session with a JPIP server for the purpose of interactive transfer of a single image.

Return Value:

Handle of the new JPIP object.

Sample:

JPIPC.


IG_JPIPC_delete

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_delete(HIGJPIPC phClient);

Arguments:

phClient
JPIP client object to delete.

Description:

This function deletes a JPIP client object, disconnecting from the server if necessary, and freeing all internal resources. This must be called for every JPIP client object created with IG_JPIPC_create () function. After this function has been called, the deleted handle must not be passed to any JPIPC functions.

Return Value:

Error count.

Sample:

JPIPC.


IG_JPIPC_disconnect

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_disconnect(
HIGJPIPC hClient,
AT_BOOL keepTransportOpen,
AT_INT timeout);

Arguments:

hClient
JPIP client object.
keepTransportOpen
Attempt to keep the transport open after disconnecting.
timeout
Maximum amount of time (in milliseconds) this function can be blocked while waiting to ensure that the server has released the transport channel from its use in the current session. This should not be long, because it will not be waiting unless the connection was already idle. Nevertheless, if the server does not released the transport within that time, or if an earlier determination can be made that it will not do so, the function closes the existing transport channel anyway, so that it cannot be re-used.

Description:

This function disconnects from the server, but leaves the object open for reading data from the cache. This function may safely be called at any time.

If the IG_JPIPC_close () function has not been called since the last call to IG_JPIPC_connect(), isActive remains TRUE, while isAlive becomes FALSE.

If the keepTransportOpen parameter is set to TRUE, an attempt will be made to keep the underlying transport channel (typically one or more TCP channels) alive, so that a subsequent call to connect can try to re-use it, rather than instantiating a new transport channel from scratch. This is most likely to succeed if the channel status is idle, which can usually be reached quickly by requesting an empty window.

Return Value:

Error count.

Sample:

JPIPC.


IG_JPIPC_image_component_set

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_image_component_set(
HIGJPIPC hClient,
AT_INT componentIndex);

Arguments:

hClient
JPIP client object.
componentIndex
Component index.

Description:

This function sets the image component(s) to use when extracting pixel data from the image. There are two possibilities: First, the default value of IG_JPIPC_ALL_COMPONENTS, which accesses all available image components. Second, the index of a single component to extract. Note that the components extracted depend on how the JPEG2000 image was encoded. For example, it is typical for the components of an RGB image to be extracted as YCrCb.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_image_export

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_image_export(
HIGJPIPC hClient,
HIGEAR hImage,
LPAT_JPIPC_EXPORT_OPTIONS lpExportOptions);

Arguments:

hClient
JPIP client object.
hImage
HIGEAR to copy image data to.
lpExportOptions
Export options.

Description:

Copies image data from JPIP client object to an existing HIGEAR. The HIGEAR must be either 24-bit RGB or 8-bit grayscale. The export options struct can be used to specify options such as source and destination rectangles to use for the copy operation.

It is acceptable to pass NULL for lpExportOptions, in which case default values of 0 will be assumed. (The entire image will be copied in this case, scaled to fit the dimensions of the HIGEAR.)

Note that in order to obtain the best image quality and performance, it is strongly recommended to use an optimal scale factor when using this function. An optimal scale factor is a power of two or integer scale factor. So, for example, if the source image is 1000x1000, and you're copying the entire image, the destination area to copy to should be 1000x1000, 500x500, 250x250, etc.

Return Value:

Error count.

Sample:

JPIPC.


IG_JPIPC_image_info_get

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_image_info_get(
HIGJPIPC hClient,
HIGDIBINFO *lphDIB,
LPAT_VOID reserved);

Arguments:

hClient
JPIP client object.
lphDIB
HIGDIBINFO object.
reserved
Reserved. Must be set to NULL.

Description:

This function creates an HIGDIBINFO object with information about the image such as width, height, original bit depth and channel configuration. The application is responsible for deleting this object.

The last parameter is reserved for future expansion, in case other information besides what can be stored in HIGDIBINFO may need to be made available.

Return Value:

Error count.

Sample:

JPIPC.


IG_JPIPC_image_orientation_set

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_image_orientation_set(
HIGJPIPC hClient,
enumIGOrientationModes orientation);

Arguments:

hClient
JPIP client object.
orientation
Orientation value. See enumIGOrientationModes.

Description:

Sets orientation (flip horizontal, flip vertical, rotate/transpose) to use when accessing image description (dimensions) and pixel data.

This orientation affects the dimensions retrieved via IG_JPIPC_image_info_get () and the coordinates passed to IG_JPIPC_image_export (). It does not affect the coordinates passed to/from the IG_JPIPC_window_set/IG_JPIPC_window_get functions.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_metadata_close

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_metadata_close(HIGJPIPC hClient);

Arguments:

hClient
JPIP client object.

Description:

This function closes the metadata set.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_metadata_find

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_metadata_find(
HIGJPIPC hClient,
AT_INT32 boxType);

Arguments:

hClient
JPIP client object.
boxType
JP2-family box four character code to search for.

Description:

This function sets the currently accessed metadata item to the specified item in the metadata set. The item is identified by JP2-family box type, a four character code stored as a 32-bit integer.

Typical examples of box types are:

    • label boxes ( `lbl `)
    • XML boxes ( `xml `)
    • IP-rights boxes ( `jp2i' )
    • number list boxes ( `nlst' )
    • ROI description boxes ( `roid' )
    • UUID boxes ( `uuid' )

Note that box types with less than four characters use trailing spaces to reach four characters. For example, the XML box type is `x', `m', `l', ` `.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_metadata_info_get

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_metadata_info_get(
HIGJPIPC hClient,
LPAT_JPIPC_METADATA_INFO lpMetadataInfo);

Arguments:

hClient
JPIP client object.
lpMetadataInfo
Metadata info.

Description:

This function retrieves information about the metadata item currently being accessed. This function completes successfully regardless of whether or not a current metadata item exists. If the current metadata item does not exist, the exists field of AT_JPIPC_METADATA_INFO will be set to FALSE.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_metadata_next

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_metadata_next(HIGJPIPC hClient);

Arguments:

hClient
JPIP client object.

Description:

This function sets the currently accessed metadata item to the next item in the metadata set. If there are no more items when this function is called, the function still completes successfully and the currently accessed metadata item is one which has no information. This state can be identified by calling IG_JPIPC_metadata_info_get and examining the exists field of AT_JPIPC_METADATA_INFO.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_metadata_open

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_metadata_open(HIGJPIPC hClient);

Arguments:

hClient
JPIP client object.

Description:

This function opens the image's JPEG2000 metadata set for reading. The metadata set is traversed in a stateful manner with the notion of a "current metadata item".

NOTE: The IG_JPIPC_metadata_* functions provide access to metadata which has been received from the server. The server may return some or all metadata by default. You can use the IG_JPIPC_metareq_* functions to explicitly request metadata if necessary.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_metadata_read

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_metadata_read(
HIGJPIPC hClient,
LPAT_VOID lpBuf,
AT_INT bytesToRead,
LPAT_INT lpBytesRead);

Arguments:

hClient
JPIP client object.
lpBuf
Buffer to read metadata.
bytesToRead
The number of bytes requested.
lpBytesRead
The number of bytes read.

Description:

This function reads data from the metadata item currently being accessed.

The number of bytes read may be less than the number of bytes requested if the end of the box has been reached, or the full contents of the box have not yet been received. In either case, the lpBytesRead parameter tells you how many bytes were actually read, and a call to IG_JPIPC_metadata_info_get () will provide relevant details about how much data is available in the box and what the current read position is.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_metadata_seek

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_metadata_seek(
HIGJPIPC hClient,
AT_INT offset);

Arguments:

hClient
JPIP client object.
offset
Offset within the metadata item.

Description:

This function seeks to the specified offset within the metadata item currently being accessed. This affects subsequent calls to IG_JPIPC_metadata_read.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_metareq_add

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_metareq_add(
HIGJPIPC hClient,
LPAT_JPIPC_METAREQ lpMetareq);

Arguments:

hClient
JPIP client object.
lpMetareq
Description of metadata to add to the window request.

Description:

This function adds an item to the list of requested metadata. It lets you specify criteria for metadata to retrieve from the server. This list affects only the next call to IG_JPIPC_window_set ().

NOTE: The server may return some or all metadata by default. This function is used to explicitly request specific types of metadata, which can be useful if the server does not send that metadata by default. This function only affects requesting the metadata. Use the IG_JPIPC_metadata_* functions to access metadata which has been received.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_metareq_clear

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_metareq_clear(HIGJPIPC hClient);

Arguments:

hClient
JPIP client object.

Description:

This function clears the list of requested metadata. This list affects only the next call to IG_JPIPC_window_set ().

Return Value:

Error count.

Sample:

None.


IG_JPIPC_metareq_count

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_metareq_count(
HIGJPIPC hClient,
LPAT_INT lpMetareqCount);

Arguments:

hClient
JPIP client object.
lpMetareqCount
Returns number of entries in the list of requested metadata.

Description:

This function returns the number of entries in the list of requested metadata. This list affects only the next call to IG_JPIPC_window_set ().

Return Value:

Error count.

Sample:

None.


IG_JPIPC_metareq_get

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_metareq_get(
HIGJPIPC hClient,
LPAT_JPIPC_METAREQ lpMetareq,
AT_INT metareqIndex);

Arguments:

hClient
JPIP client object.
lpMetareq
Pointer to metareq structure to be filled.
metareqIndex
Index of item in the list of requested metadata to retrieve information for.

Description:

This function gets item information for an item in the list of requested metadata. This list affects only the next call to IG_JPIPC_window_set ().

Return Value:

Error count.

Sample:

None.


IG_JPIPC_status_get

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_status_get(
HIGJPIPC hClient,
LPAT_JPIPC_STATUS lpStatus);

Arguments:

hClient
JPIP client object.
lpStatus
Pointer to status structure to be filled.

Description:

This function retrieves current session status and statistics. It can be called at any time. It fills the given AT_JPIPC_STATUS structure with current information. This is the same status information as provided by the status callback, which is registered via IG_JPIPC_CB_register.

Return Value:

Error count.

Sample:

JPIPC.


IG_JPIPC_window_get

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_window_get(
HIGJPIPC hClient,
LPAT_JPIPC_WINDOW lpWindow);

Arguments:

hClient
JPIP client object.
lpWindow
Pointer to window structure to be filled.

Description:

This function may be used to learn about the window which the server is currently servicing. This window may be different from the one requested. For example, if a client requests a large, high-resolution view of an image, the server may shrink the ROI to reduce complexity required on the server side to process the request.

If the server is idle, meaning that it has finished serving all outstanding requests, this function will continue to identify the most recently serviced window as the one which is in progress.

If there is no active connection with the server (isAlive is FALSE), the numComponents member of the window structure will be set to 0.

Return Value:

Error count.

Sample:

None.


IG_JPIPC_window_set

Group: JPIP-Client

Declaration:

AT_ERRCOUNT IG_JPIPC_window_set(
HIGJPIPC hClient,
LPAT_JPIPC_WINDOW lpWindow);

Arguments:

hClient
JPIP client object.
lpWindow
Window to request from the server.

Description:

Requests that a message be delivered to the server identifying a change in the user's window of interest into the compressed image. The message may not be delivered immediately; it may not even be delivered at all, if the function is called again specifying a different access window, before the client has a chance to deliver a request for the current window to the server.

The window of interest encompasses several factors such as spatial region, resolution, and so on, as defined in AT_JPIPC_WINDOW. It also includes a metadata request list which must be set up using the IG_JPIPC_metareq_* functions before requesting the window with IG_JPIPC_window_set.

Return Value:

Error count.

Sample:

JPIPC.


LPFNIG_JPIPC_ERROR

Group: Callback JPIP-Client

Declaration:

typedef AT_VOID (LPACCUAPI LPFNIG_JPIPC_ERROR)(
    AT_CHAR *lpErrorDescription,
    LPAT_VOID lpPrivateData
    );

Arguments:

lpErrorDescription
Error description.
lpPrivateData
Value of Private Data supplied during callback registration.

Description:

Callback function to be called when an error occurs. Since JPIP operates asynchronously, errors can occur at any time and are delivered through a callback function.

A description of the error is provided by the lpErrorDescription parameter. The parameter lpPrivateData provides the value of lpPrivateData supplied during callback registration.

The same callback type is used for both errors and warnings, although the application can register separate callbacks for errors and warnings via IG_JPIPC_CB_register ().

Sample:

JPIPC.


LPFNIG_JPIPC_STATUS

Group: Callback JPIP-Client

Declaration:

typedef AT_VOID (LPACCUAPI LPFNIG_JPIPC_STATUS)(
    HIGJPIPC hClient,
    LPAT_JPIPC_STATUS lpStatus,
    LPAT_VOID lpPrivateData
    );

Arguments:

hClient
JPIP client object.
lpStatus
Status information.
lpPrivateData
Value of Private Data supplied during callback registration.

Description:

Callback function to be called when JPIP client events occur (such as new data being received from the server). Due to the asynchronous nature of JPIP communications, an application will typically take advantage of this event to look for changes in state and respond to them. For example, after initiating a connection, the application can find out as soon as enough of the image has been retrieved to confirm its validity and retrieve its dimensions by looking at the isValidImage member of the status structure when callbacks occur.

Note that this callback function occurs within the JPIP client object's network thread, and the application must minimize the amount of work performed during the callback in order to maintain efficient transfer of network data. Also, the application must not call other JPIP client API functions from within the callback. Some queuing mechanism should be used instead.

Current status information is provided by the struct pointed to by the parameter lpStatus. The parameter lpPrivateData provides the value of lpPrivateData supplied during callback registration.

The same status information can be retrieved at any time (not just this callback) by calling IG_JPIPC_status_get.

Sample:

JPIPC.


AT_JPIPC_EXPORT_OPTIONS

Group: JPIP Client Structure

Description:

Specifies options for exporting image data from JPIP client to a HIGEAR.

Declaration:

struct AT_JPIPC_EXPORT_OPTIONS (
    AT_RECTANGLE rcSrc
    AT_RECTANGLE rcDst);

Structure members:

rcSrc
Rectangle in source JPIP client image to copy image data from, in full-resolution coordinates (all 0's means use the whole area)
rcDst
Rectangle in destination HIGEAR to copy image data to (all 0's means use the whole area)


AT_JPIPC_METADATA_INFO

Group: JPIP Client Structure

Description:

Specifies information about a metadata item in an image's metadata set. The function IG_JPIPC_metadata_info_get provides this information. It is used to retrieve metadata which has been downloaded from the JPIP server.

Declaration:

struct AT_JPIPC_METADATA_INFO(
    AT_BOOL exists
    AT_BOOL isComplete
    AT_INT32 boxType
    AT_INT totalBytes
    AT_INT currentPos
    AT_INT remainingBytes);

Structure Members:

exists
True if the metadata item exists. When this is false, the application should stop iterating over metadata because there is no more. Or, metadata with the box type passed to IG_JPIPC_metadata_find could not be found.
isComplete
True if the metadata item is completely downloaded or cached. (Even if this is false, you can still read partially downloaded metadata.)
boxType
JP2-family box 4 character code, or else 0 (wildcard).
totalBytes
Total number of bytes in the currently open box, including the box header, not just its contents. If the box has a rubber length, this value can only report the number of bytes which have actually been read from the box, starting from the first byte of the box header.
currentPos
Location of the next byte to be read, relative to the start of the box contents.
remainingBytes
Number of bytes in the box's contents which lie beyond the current read pointer. Adding this value to currentPos yields the box's total length. However, if the box's length cannot be determined beforehand, this will be a negative value.
This value will be -1 if the box has a rubber length, meaning that its length field indicated that the box extends to the end of the JP2 source. This value will be converted to a non-negative value once the end of the box is actually encountered by attempting to read or seek past it.


AT_JPIPC_METAREQ

Group: JPIP Client Structure

Description:

Specifies description of metadata to request. The function IG_JPIPC_metareq_add is used to add an entry to the list of metadata to request. This list of metatdata request information is transmitted to the server in the window request initiated by the next call to IG_JPIPC_window_set.

Declaration:

struct AT_JPIPC_METAREQ(
    AT_INT32 boxType
    enumJPIPCQualifer qualifier
    AT_BOOL priority
    AT_INT byteLimit
    AT_BOOL recurse
    AT_INT rootBinID
    AT_INT maxDepth);

Structure members:

boxType
JP2-family box 4 character code, or else 0 (wildcard).
qualifier
Provides qualification of the conditions under which a box matching the boxType value should be considered to be of interest to the client. Takes a logical OR of qualifier types in enumJPIPCQualifer.
priority
True if the boxes described by this record are to have higher priority than image data when delivered by the server. Otherwise, they have lower priority than the image data described by the request window.
byteLimit
Indicates the maximum number of bytes from the contents of any JP2 box conforming to the new metareq record, which are of interest to the client. May not be negative. Guaranteed to be 0 if recurse is true.
recurse
Indicates that the client is also interested in all descendants (via sub-boxes) of any box which matches the boxType and other attributes specified by the various members of this structure. If true, the byteLimit member will be 0, meaning that the client is assumed to be interested only in the header of boxes which match the boxType and the descendants of such boxes.
rootBinID
Indicates the metadata-bin identifier of the data-bin which is to be used as the root when processing this record. If non-zero, the scope of the record is reduced to the set of JP2 boxes which are found in the indicated data-bin or are linked from it via placeholders.
maxDepth
Provides a limit on the maximum depth to which the server is expected to descend within the metadata tree to find JP2 boxes conforming to the other attributes of this record. A value of 0 means that the client is interested only in boxes which are found at the top level of the data-bin identified by rootBinID. A value of 1 means that the client is additionally interested in sub-boxes of boxes which are found at the top level of the data-bin identified by rootBinID; and so forth.


AT_JPIPC_STATUS

Group: JPIP Client Structure

Description:

Specifies information about current session status. This status information is provided by the status callback registered via IG_JPIPC_CB_register. It can also be retrieved at any time by calling IG_JPIPC_status_get.

Declaration:

struct AT_JPIPC_STATUS(
    AT_BOOL isActive
    AT_BOOL isAlive
    AT_BOOL isOneTimeRequest
    AT_BOOL isIdle
    AT_BOOL isValidImage
    AT_BOOL isModifiedWindow
    AT_INT totalBytes
    AT_INT precinctBytes
    AT_INT tileHeaderBytes
    AT_INT tileBytes
    AT_INT mainHeaderBytes
    AT_INT metaBytes);

Structure members:

isActive
True from the point at which connect is called, remaining true until close is called, even if the connection with the server has been dropped, or was never completed.
isAlive
True from the point at which connect is called, remaining true until the network management thread terminates. This happens if close is called, if the network connection is explicitly terminated by a call to disconnect, if the server terminates the connection, or if the original connection attempt failed to complete.
isOneTimeRequest
True if the request string used at connect time represented a one-time request, as defined there. In particular, a one-time request is one which contains a query string with anything other than a target or sub-target request field. In the event that a one-time request was found in the request string passed to connect, this remains true until close is called, i.e., for the same interval over which isActive is true.
isIdle
True if the server has finished responding to all pending requests, but the connection is still alive.
isValidImage
True if the image being requested is valid and the client has finished receiving its headers. (It becomes possible to call IG_JPIPC_image_info_get once this is true.)
isModifiedWindow
True if the server has modified the window parameters since the last call to IG_JPIPC_window_set. A JPIP server can modify window parameters at any time in any way it sees fit. (It typically does this if a client requests a window the server deems too large, and therefore expensive in terms of server-side processing time.)
totalBytes
Total number of bytes received from JPIP server. Includes bytes used for JPIP protocol communications, such as window descriptions.
precinctBytes
Bytes received for precinct-oriented streams.
tileHeaderBytes
Bytes received for tile headers.
tileBytes
Bytes received for tile-part oriented streams.
mainHeaderBytes
Bytes received for code-stream main header.
metaBytes
Bytes received for meta-data and file structure info.


AT_JPIPC_WINDOW

Group: JPIP Client Structure

Description:

Defines a window (region of interest) within an image being served by a JPIP server. This window is communicated to the server in order to request image data. The functions IG_JPIPC_window_set and IG_JPIPC_window_get are used to request a window from the server and find out what window the server is currently servicing (or last serviced).

Declaration:

struct AT_JPIPC_WINDOW(
    AT_POINT resolution
    enumJPIPCRoundDirection roundDirection
    AT_RECTANGLE region
    AT_INT numComponents
    AT_INT firstComponentIndex
    AT_INT maxLayers
    AT_BOOL metadataOnly);

Structure members:

resolution
Describes the preferred image resolution in terms of the width and the height of the full image. For example, to request the original image data at 1:1 zoom level, specify the full dimensions of the image in pixels. To request quarter-resolution, divide each dimension by 2.
Where geometric mapping information is provided via codestream contexts, additional transformations are applied to match the resolution of each codestream to the resolution of the composited result which is identified by the present member.
If both resolution.x and resolution.y are 0, no compressed image data is being requested. Such a request requires the server to send only the essential marker segments from main codestream headers, plus any metadata which is required for correct rendering. Such a request might be sent by a client when it first connects to the server, but would not normally be issued explicitly at the application levels.
roundDirection
Indicates the preferred direction for converting the resolution size to the size of an actual available image resolution in each codestream. The available resolutions for each codestream are found by starting with the image size on the codestream's high resolution canvas, and dividing down by multiples of 2, following the usual rounding conventions of the JPEG2000 canvas coordinate system. Thus, the available image dimensions correspond essentially to the codestream image dimensions obtained by discarding a whole number of highest resolution levels, except that the number of discarded DWT levels is not necessarily limited by the number of DWT levels used in each relevant tile component.
region
Describes a spatial region, expressed relative to the image resolution defined by the resolution member.
numComponents
Number of image components to request. 0 requests all available components.
firstComponentIndex
Zero-based index of first image component to request. Ignored if numComponents is 0.
maxLayers
Max number of quality layers to request. 0 requests all quality layers.
metadataOnly
If this flag is true, the client is not interested in receiving anything other than the metadata which would be returned in response to the requested window. No compressed imagery, or even image headers should be sent. Note that the server may not send any metadata unless it is specifically requested using the separate metadata request specification API.


enumJPIPCCBType

Group: JPIP Client Enumeration

Description:

This enumeration is used to specify the type of callback function to register using IG_JPIPC_CB_register.

Values:

IG_JPIPC_CBT_STATUS
Called on status updates (when JPIP client events occur, such as new data being received from the server).
IG_JPIPC_CBT_ERROR
Called on errors.
IG_JPIPC_CBT_WARNING
Called on warnings.


enumJPIPCChannelTransport

Group: JPIP Client Enumeration

Description:

This enumeration is used to specify the type of the channel transport to use for a JPIP session.

Values:

IG_JPIPC_CHANNEL_HTTP
(Default) A persistent channel is used over HTTP. Multiple requests can be made over the same channel. This is the best compromise between providing good interactive response times and being tolerant of firewalls and proxys.
IG_JPIPC_CHANNEL_HTTP_TCP
A persistent HTTP channel is used for control commands. In addition, a separate persistent TCP channel is used for data transfer. This provides optimal interactive response times and bandwidth efficiency, but firewalls and proxy servers could make it impossible to set up the additional data channel.
IG_JPIPC_CHANNEL_NONE
The request made upon connecting to the server is a one-time request with no persistent channel. Further requests can be made, but a channel is re-established for each one. Not recommended.


enumJPIPCRoundDirection

Group: JPIP Client Enumeration

Description:

This enumeration is used to specify which resolution in an image should be used to satisfy window requests. JPEG2000-encoded images can contain multiple resolutions, and window requests can be for arbitrary resolutions (also can be thought of as "zoom levels"). So, using a higher resolution can result in higher image quality but at the expense of more data transfer.

Values:

IG_JPIPC_ROUND_DOWN
(Default) The requested resolution should be rounded down to the nearest actual available codestream resolution. That is, the actual selected dimensions, X and Y, must satisfy X <= resolution.x and Y <= resolution.y, if possible.
IG_JPIPC_ROUND_UP
The requested resolution should be rounded up to the nearest actual available codestream resolution. That is, the actual selected dimensions, X and Y, must satisfy X >= resolution.x and Y >= resolution.y, if possible.
IG_JPIPC_ROUND_NEAREST
Rounding is to the nearest available codestream image resolution, in the sense of area. Specifically, the actual codestream image resolution's dimensions, X and Y, should minimize |XY - xy| where x and y are the values of resolution.x and resolution.y.


enumJPIPCQualifer

Group: JPIP Client Enumeration

Description:

This enumeration is used to specify the type of the qualifier used for metadata requested from the JPIP server.

Values:

IG_JPIPC_MRQ_WINDOW
Identifies a context which consists of all boxes which are known to be directly associated with a specific (non-global) spatial region of one or more codestreams, so long as the spatial region and other aspects of the metadata intersect with the requested view window.
IG_JPIPC_MRQ_STREAM
Identifies a context which consists of all boxes which are known to be associated with one or more codestreams or codestream contexts associated with the view window, but not with any specific spatial region of any codestream.
IG_JPIPC_MRQ_GLOBAL
Identifies a context which consists of all boxes which are relevant to the requested view window, but do not fall within either of the above two categories.
IG_JPIPC_MRQ_DEFAULT
Union of the above three qualifier types. This is the default qualifier for JPIP metareq requests which do not explicitly identify a box context.
IG_JPIPC_MRQ_ALL
Identifies a context consisting of all JP2 boxes in the entire target.


JPIP Server API Reference

JPIP Server API represents the following functions, structures and enums

  • IG_JPIPS_CB_register
  • IG_JPIPS_config_load
  • IG_JPIPS_config_set
  • IG_JPIPS_config_virtual_dir_add
  • IG_JPIPS_create
  • IG_JPIPS_delete
  • IG_JPIPS_response_set
  • IG_JPIPS_start
  • IG_JPIPS_stop
  • LPFNIG_JPIPS_MESSAGE
  • LPFNIG_JPIPS_REQUEST
  • AT_JPIPS_REQUEST
  • enumJPIPSCBType


IG_JPIPS_CB_register

Group: JPIP-Server

Declaration:

AT_ERRCOUNT IG_JPIPS_CB_register(
HIGJPIPS hServer,
LPAT_VOID lpfnCB,
AT_MODE nCBType,
LPAT_VOID lpPrivateData);

Arguments:

hServer
JPIP server handle.
lpfnCB
Callback function.
nCBType
Callback type.
lpPrivateData
Private data.

Description:

This function registers a callback function.

Callback functions must be registered before starting the server.

The nCBType parameter is a value from enumJPIPSCBType which specifies the type of callback function being registered.

Return Value:

Error count.

Sample:

JPIPS.


IG_JPIPS_config_load

Group: JPIP-Server

Declaration:

AT_ERRCOUNT IG_JPIPS_config_load(
HIGJPIPS hServer,
AT_CHAR *lpFilename);

Arguments:

hServer
JPIP server handle.
lpFilename
The name of the config file.

Description:

This function loads server settings from a configuration file. It must be done before starting the server. The configuration file is in plain text format. A line in the file can contain either one server setting (beginning with a hyphen) or a comment (not beginning with a hyphen). The format of a server setting and the possible server settings are the same as described in the documentation for IG_JPIPS_config_set. Here is an example configuration file:

; Set address and port
-address 127.0.0.1
-port 80
; Set max rate to 64KB/sec
-max_rate 65536

Note that a setting cannot be specified more than once for a single instance of the JPIP server. This means that if a setting is specified in a configuration file, it must not also be specified using IG_JPIPS_config_set, and vice versa.

Return Value:

Error count.

Sample:

JPIPS.


IG_JPIPS_config_set

Group: JPIP-Server

Declaration:

AT_ERRCOUNT IG_JPIPS_config_set(
HIGJPIPS hServer,
AT_CHAR *lpParameter);

Arguments:

hServer
JPIP server handle.
lpParameter
The server settings string.

Description:

This function sets the server settings. The setting name and value(s) are combined in one space-delimited string.

For example: "-log c:\JPIPS.log".

All server settings must be set before starting the server.

There are the following server settings:

address
This setting allows to specify a different IP address.
cd
Specifies directory to store cache files (.cache) in.
cache
Specifies an alternate per-client cache size.
completion_timeout
Specifies the time within which the client must complete all persistent connections required by the relevant protocol.
delegate
Delegate the task of actually serving clients to one or more other servers.
ignore_relevance
Forces the server to ignore the degree to which a precinct overlaps with the spatial window requested by the client.
initial_timeout
Specifies the timeout value to use for the handshaking which is used to establish persistent connection channels.
log
Redirects log messages to the specified log file.
max_chunk
Specifies the maximum size of the image data chunks shipped by the server.
clients
Specifies the maximum amount of client connections that can be serviced at once.
connection_threads
Specifies the maximum number of threads which can be dedicated to managing the establishment of new connections.
time
Specifies the maximum time (in seconds) after which the continuously connected clients will be automatically disconnected.
max_rate
Specified a different maximum transmission rate.
max_rtt
Specifies the maximum value (in seconds) to be used as the server's target round trip time (RTT).
sources
Specifies the maximum amount of the open source files for each client connection.
min_rtt
Specifies minimum value to be used as the server's target round trip time (RTT).
phld_threshold
Represents the threshold, i.e. the maximum size for any JP2 box before that box is replaced by a placeholder in its containing data-bin, where the placeholder identifies a separate data-bin which holds the box's contents.
port
Specifies the port on which the server listens for JPIP connection requests.
record
Specifies whether the server should print all HTTP requests and reply to stdout or not.
wd
Specifies the working directory for the JPIP server.

Return Value:

Error count.

Example:

// Set working directory
GetDlgItemText(hwnd, IDC_WORKINGDIR, serverWorkingDir,
sizeof(serverWorkingDir));
if (!serverWorkingDir[0])
{
MessageBox(hwnd, "Must specify a working directory.",
"JPIP Server Parameters", MB_ICONEXCLAMATION);
break;
}
sprintf(param, "-wd %s", serverWorkingDir);
IG_JPIPS_config_set(hJPIPServer, param);
// Set IP address
GetDlgItemText(hwnd, IDC_IPADDRESS, serverIP,
sizeof(serverIP));
if (!serverIP[0])
{
MessageBox(hwnd, "Must specify an IP address to listen on.",
"JPIP Server Parameters", MB_ICONEXCLAMATION);
break;
}
sprintf(param, "-address %s", serverIP);
IG_JPIPS_config_set(hJPIPServer, param);

Sample:

JPIPS.


IG_JPIPS_config_virtual_dir_add

Group: JPIP-Server

Declaration:

AT_ERRCOUNT IG_JPIPS_config_virtual_dir_add(
HIGJPIPS hServer,
AT_CHAR *lpDirName,
AT_CHAR *lpDirLocation);

Arguments:

hServer
JPIP server handle.
lpDirName
The beginning of the request string.
lpDirLocation
The path to the file to fulfill the request.

Description:

This function adds a virtual directory to the server.

A number of virtual directories can be added to the server to allow a convenient means of the serving images located in a variety of places.

A request string whose beginning matches the lpDirName parameter will use the path specified by the lpDirLocation parameter as the base path, instead of using the working directory specified as part of the server configuration.

Virtual directories must be added before the server has been started.

Here is an example of how this function works:

  1. Application calls IG_JPIPS_config_virtual_dir_add(hServer, "special", "z:\\images\\current\\");
  2. The request comes in from JPIP client for: "special/myfavorite.jp2"
  3. The file used to fulfill the request is: "z:\images\current\myfavorite.jp2"

There is another example which shows nesting of the directories:

  1. Application calls IG_JPIPS_config_virtual_dir_add(hServer, "special", "z:\\images\\current\\");
  2. Request comes in from JPIP client for: "special/24bpp/myfavorite.jp2"
  3. The file used to fulfill the request is: "z:\images\current\24bpp\myfavorite.jp2"

Return Value:

Error count.

Sample:

JPIPS.


IG_JPIPS_create

Group: JPIP-Server

Declaration:

AT_ERRCOUNT IG_JPIPS_create(LPHIGJPIPS phServer);

Arguments:

phServer
JPIP server handle.

Description:

This function creates a new JPIP server object and returns its handle. This handle must be passed to all other JPIP server API calls.

JPIP server object represents a single instance of a JPIP server, which is capable of serving a number of simultaneous client sessions.

Return Value:

Error count.

Sample:

JPIPS.


IG_JPIPS_delete

Group: JPIP-Server

Declaration:

AT_ERRCOUNT IG_JPIPS_delete(HIGJPIPS hServer);

Arguments:

hServer
JPIP server handle.

Description:

Deletes a JPIP server object, disconnects any connected clients and frees all internal resources. It have to be called for every JPIP server object created with IG_JPIPS_create ().

Return Value:

Error count.

Sample:

JPIPS.


IG_JPIPS_response_set

Group: JPIP-Server

Declaration:

AT_ERRCOUNT IG_JPIPS_response_set(
HIGJPIPS hServer,
LPAT_JPIPS_REQUEST lpRequest,
AT_BOOL bDeny,
AT_CHAR *lpDenialReason,
AT_CHAR *lpFilename);

Arguments:

hServer
JPIP server handle.
lpRequest
JPIP Client request handle.
bDeny
If TRUE - the request is denied. FALSE - the request is accepted.
lpDenialReason
The reason for the denial.
lpFilename
The name of JPEG2000 file for the response.

Description:

The application can optionally call this function to indicate to the JPIP server how a JPIP client request should be responded to, and provide data for the response.

This function is to be called only during a callback of type LPFNIG_JPIPS_REQUEST.

The hServer and lpRequest parameters must be the same as received in the callback parameters. If the bDeny parameter is set to TRUE, the request will be denied and other parameters will be ignored. A reason for the denial can optionally be passed by the lpDenialReason parameter.

The lpFilename parameter, if non-NULL, identifies the name of a JPEG2000 image file to use for the response.

NOTE: All memory buffers passed to this function are required to exist only throughout the duration of this function call. The application is permitted to free them immediately after calling this function.

Return Value:

Error count.

Sample:

JPIPS.


IG_JPIPS_start

Group: JPIP-Server

Declaration:

AT_ERRCOUNT IG_JPIPS_start(HIGJPIPS hServer);

Arguments:

hServer
JPIP server handle.

Description:

This function starts the JPIP server. Configuration and callbacks must be set before calling this function.

Return Value:

Error count.

Sample:

JPIPS.


IG_JPIPS_stop

Group: JPIP-Server

Declaration:

AT_ERRCOUNT IG_JPIPS_stop(HIGJPIPS hServer);

Arguments:

hServer
JPIP server handle.

Description:

This function stops the JPIP server. Any connected clients will be notified of the server shutdown.

Return Value:

Error count.

Sample:

JPIPS.


LPFNIG_JPIPS_MESSAGE

Group: Callback JPIP Server

Declaration:

typedef AT_VOID (LPACCUAPI LPFNIG_JPIPS_MESSAGE)(
    AT_CHAR *lpMessage,
    LPAT_VOID lpPrivateData
    );

Arguments:

lpMessage
The message string.
lpPrivateData
Value of Private Data supplied during callback registration.

Description:

Callback function to be called when the server has generated a message. The message could be a routine log message, or an error message.

Different callback types are passed to IG_JPIPS_CB_register () to register callbacks for different types of messages.

The parameter lpPrivateData provides the value of lpPrivateData supplied during callback registration.

Sample:

JPIPS.


LPFNIG_JPIPS_REQUEST

Group: Callback JPIP Server

Declaration:

typedef AT_VOID (LPACCUAPI LPFNIG_JPIPS_REQUEST)(
    HIGJPIPS hServer,
LPAT_JPIPS_REQUEST lpRequest,
    LPAT_VOID lpPrivateData
    );

Arguments:

hServer
Error description.
lpRequest
Request information.
lpPrivateData
Value of Private Data supplied during callback registration.

Description:

Callback function to be called upon an initial request from a JPIP client.

Request information is provided by the struct pointed to by the parameter lpRequest. Request response can be set by calling the function IG_JPIPS_response_set () from within the callback.

The parameter lpPrivateData provides the value of lpPrivateData supplied during callback registration.

Sample:

JPIPS.


AT_JPIPS_REQUEST

Group: JPIP Server Structure

Description:

Specifies information about a JPIP client request being made to a JPIP server.

Declaration:

struct AT_JPIPS_REQUEST(
AT_CHAR *lpIPAddress
AT_CHAR *lpRequest);

Structure members:

lpIPAddress
String containing IP address of JPIP client making the request.
lpRequest
Resource on server requested by JPIP client.


enumJPIPSCBType

Group: JPIP Server Enumeration

Description:

This enumeration determines the type of JPIP Server callback function.

Values:

IG_JPIPS_CBT_LOG
Called on log messages. This allows the application to obtain information about what the server is doing. These messages could be displayed or logged to a file.
NOTE: The server can be configured separately to log to a file.
IG_JPIPS_CBT_ERROR
Called on errors. For example, if the server cannot be started due to an invalid setting, the specific error will be reported through this callback.
IG_JPIPS_CBT_REQUEST
Called on initial requests from JPIP clients. When a client attempts to establish a session with the server, it provides a request string to the server (such as a path and filename). The application can use this callback to monitor such requests, approve or deny them, and supply or generate request results on the fly (in the form of JPEG2000 files).


MD Component API Function Reference

You can call MD component functions using two ways. Firstly, you may call this function through it macro defined in i_MED.h public header file:

#define MED_DCM_load_DICOM(_lpFileName, _lphIGear, _nSyntax,
_page_number)\ (AT_ERRCOUNT (CACCUAPI *)(const LPSTR, \const
LPCHAR, LPHIGEAR, const AT_MODE, const UINT)) \
      IG_comm_function_call)("MED.MED_DCM_load_DICOM", \
(_lpFileName),(_lphIGear),(_nSyntax), (_page_number))

In this case your application will search all included public headers for this macro and call this function through IG_comm_function_call() component manager function call that is also determined in i_MED.h. So if you are going to use MD component function in a multiple loop we would recommend you the second way of using this function type declaration that is also determined in i_MED.h file:

typedef  AT_ERRCOUNT (LPACCUAPI LPAFT_MED_DCM_LOAD_DICOM)(
const LPSTRlpsz			FileName,
LPHIGEAR			lphIGear,
const AT_MODE			nSyntax,
const UINT			page_number
 );

So you should declare the variable of this function type and then use IG_comm_entry_request() function to initialize this variable with correct value and call it then.


MED_DCM_DS_bits_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_bits_get(
const HIGEAR hIGear,
LPUINT lpBitsAllocated,
LPUINT lpBitsStored,
LPUINT lpHighBit,
LPUINT lpSamplesPerPix);

Arguments:

hIGear
HIGEAR handle of the image containing a DICOM Data Set
lpBitsAllocated
A far pointer that returns the number of Bits Allocated (0028,0100) for each pixel in the image Set this to NULL if you do not need this information
lpBitsStored
A far pointer that returns the number of Bits Stored (0028,0101) for each pixel in the image. Set this to NULL if you do not need this information.
lpHighBit
A far pointer that returns the position of the High Bit (0028,0102) of the pixels in a DICOM image. Set this to NULL if you do not need this information.
lpSamplePerPix
A far pointer that returns the number of Samples Per Pixel (0028,0002) for the DICOM image. Set this to NULL if you do not need this information.

Description:

This function returns three critical DE values from the Data Set: the number of Bits Allocated (0028,0100), the number of Bits Stored (0028,0101), and the position of the High Bit (0028,0102). These values are stored in the HDS structure pointed to by the HIGEAR.

The value returned by lpBitsAllocated is not always the same as the number of bits per pixel for the image's DIB. It is the number of bits allocated per sample for each pixel. A 24-bit RGB image would return a Bits Allocated of 8 since each of the 3 samples has 8 bits allocated for it.

The Bits Stored is the number of bits actually used out of the total available (Bits Allocated). You can have a 16-bit grayscale image that only actually uses 12-bits. In this case, the Bits Allocated would be 16 and Bits Stored would be 12. The Bits Stored is always less than or equal to the Bits Allocated.

The High Bit shows where the Bits Stored are placed in the Bits Allocated WORD or DWORD. Since the Bits Stored can be less than the Bits Allocated, the Bits Stored can be placed in the Bits Allocated with different starting points. This value tells you where the Bits Stored actually resides. High Bits is always less than Bits Allocated.

See also:

  • MED_IP_high_bit_transform()
  • MED_IP_reduce_depth_with_LUT()
  • MED_IP_reduce_depth_with_downshift()

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during the function call


MED_DCM_DS_create

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_create(
HIGEAR hIGear,
const AT_MODE Transfer_syntax);

Arguments:

hIGear
HIGEAR handle to the image
Transfer_syntax
Set this variable to the desired Transfer Syntax (TS) with which to create the Data Set. Use one of the ImageGear defined constants defined in DCM.h such as:
MED_DCM_TS_IMPLICIT_VR_LE, MED_DCM_TS_EXPLICIT_VR_LE, MED_DCM_TS_EXPLICIT_VR_BE

Description:

This function creates a Data Set. If there is already a Data Set that is associated with the HIGEAR image, it will be replaced. In addition, the absolute minimum of Critical DEs (Data Elements), such as Pixel Representation and Samples per Pixel will be automatically added to the Data Set.

Below is a list of those Mandatory DEs that will be filled out automatically by this function. See Part 6: Data Dictionary of the DICOM Specification for the definitions of these DEs.

Note that there are two different Group Numbers listed below, and that the Tag numbers (the second numbers shown in the parentheses) identify which Data Element will be filled in:

    Affected DEs from Tag.group				= 0x0028:
    (0028,0010)			/* Rows		*/
    (0028,0011)			/* Columns		*/
    (0028,0100)			/* Bits Allocated			*/
    (0028,0101)			/* Bits Stored			*/
    (0028,0102)			/* High Bit			*/
    (0028,0004)			/* Photometric Interpretation				*/
    (0028,0103)			/* Pixel Representation				*/
    (0028,0002)			/* Samples per pixel		*/
    (0028,0006)			/* Planar Configuration				*/
    Affected DEs from Tag.group				= 0x7FE0;
    (7FE0,0010)			/* Pixel Data			*/

See Working With DICOM Data Structures section for more information.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR				hIGear;
AT_MODE 				Transfer_syntax;
IG_load_file("image1.tif", &hIGear);
Transfer_syntax = MED_DCM_TS_IMPLICIT_VR_LE;
MED_DCM_DS_create(hIGear, Transfer_syntax);


MED_DCM_DS_curr_data_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_curr_data_get(
const HIGEAR hIGear,
LPVOID lapdog,
const DWORD size_of_data,
LPAT_DCM_VL lpActualSize);

Arguments:

hIGear
HIGEAR handle to the image to get data from
lpData
A far pointer to a VOID buffer into which the data will be copied.
size_of_lpData
Size of above buffer, lpData
lpActualSize
Actual number of bytes copied to lpData (NULL if do not care). This will always be equal to or smaller than size_of_lpData. If lpActualSize is less than the VL of the current Data Element then lpData does not contain all the data because lpData does not point to enough memory to hold the entire object.

Description:

This function returns the data (Value Field) of the Current Data Element in its native form. Each Data Element can be of one of many different data types (int, word, bytes, float, double, string, etc.) You must know the VR (Value Representation) of the data in order to use this data. To get the VR and the VL (Value Length), you can use one of the MED_DCM_DS_move_...() functions or MED_DCM_DS_curr_info_get(). Each time you move the Current Data Element with a _move_...() function, the VR and VL of the new Current Data Element are returned to you.

To retrieve the data as a string use MED_DCM_DS_curr_data_get_string().

NOTES: Some VRs depend on the byte order of your operating system (Big Endian or Little Endian ) and the Transfer Syntax of the DICOM file. Examples of such VRs are: WORD, LONG, FLOAT, DOUBLE, etc. The Data Field values will be returned to you already adjusted to the proper format and no byte-swapping is needed.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_curr_data_get_string

Group: Data Set Utility

Declaration:

BOOL ACCUAPI MED_DCM_DS_curr_data_get_string (const HIGEAR
hIGear,
             LPCHAR lpString,
             const DWORD size_of_lpstring);

Arguments:

hIGear
HIGEAR handle to the image to get data from
lpString
A far pointer to a memory location which will be filled with the data from the Current Data Element as a NULL-terminated character string.
size_of_lpString
The variable which tells the function the length of lpString, in bytes, expressed as a DWORD.
If you specify a string length that is not long enough to hold the data, the data will simply be truncated.

Description:

This function gets the data from the Current Data Element, and always returns it to you as a NULL-terminated character string. The marker to the Current Data Element can be moved using one of the MED_DCM_DS_move_...() functions.

Data Elements can be of many different data types (int, word, bytes, float, double, string, etc.), but this function will always convert the data to a string. To return the data in its "natural form", use MED_DCM_DS_curr_data_get().

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_curr_data_set

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_curr_data_set(HIGEAR hIGear,
                    const LPVOID lpData,
                    const DWORD size_of_data);

Arguments:

hIGear
HIGEAR handle of the image
lpData
A far pointer of type VOID. Set this to the data you would like stored into the Data Field of the Current Data Element
size_of_data
Set this DWORD variable to the size of the data in lpData.

Description:

This function allows you to overwrite the Value Field (data) of the Current Data Element, by copying the data from your buffer to the HDS table. The Data must be of the correct data type to match the Value Representation (VR) of the Current DE. You can use MED_DCM_DS_curr_info_get()to find out the VR of the Current DE, and you can use one of the MED_DCM_DS_move_...() functions to set the Current Data Element.

If the Data Value can accept multiple Data Elements, the data values should be set as a single block of memory. To query the Value Multiplicity (VM) use MED_DCM_util_tag_info_get().

The length of a DICOM Data Field must always be an even number. If you set the size_of_lpData to an odd number of bytes, ImageGear will pad it (and your data) to make it an even-numbered length.

An error is set if the data type does not match the VR of the Current DE.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_curr_index_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_curr_index_get(const HIGEAR
hIGear,
                    LPDWORD lpIndex);

Arguments:

hIGearc
The HIGEAR handle to the image being queried
lpIndex
A far pointer of type DWORD which returns with the index of the Current Data Element

Description:

Returns the index of the Current Data Element in the Data Set associated with the current HIGEAR image. This function indexes through all levels of the Data Set. The index of the first Data Element in the table is 0.

To move to a specific index and make it the Current Data Element, use MED_DCM_DS_move_index ().

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_curr_info_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_curr_info_get(const HIGEAR
hIGear,
                   LPAT_DCM_TAG 						lpTag,
                   LPAT_DCM_VR 						lpVR,
                   LPAT_DCM_VL		 				lpVL,
                   LPWORD 						lpLevel,
                   LPDWORD 						lpItem_count);

Arguments:

hIGear
HIGEAR handle to the image
lpTag
A far pointer that returns a 32-bit value of type AT_DCM_TAG indicating the numerical value of the Tag of the Current Data Element; set this to NULL if you do not need this information. The numerical values of the DICOM Tags are defined in DataDict.h
lpVR
A far pointer to variable of type AT_DCM_VR which returns the Value Representation (VR) of the Current Data Element; set this to NULL if you do not need this information.
lpVL
A far pointer to a variable of type DWORD that returns the length, in bytes, of the Current Data Element's Data Field; set this to NULL if you do not need this information.
lpLevel
A far pointer to a WORD which returns the level in the hierarchy of the new Current Data Element; set to NULL if you do not need this information.
lpItem_count
A far pointer that returns the number of items stored in the Data Field; set this to NULL if you do not need this information.

Description:

This function returns information about the Current Data Element (DE). It operates in just the same way as the MED_DCM_move_...() functions except that it does not change the Current DE - it only reports about it.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_curr_remove

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_curr_remove (HIGEAR hIGear,
                    LPBOOL lpRemoved);

Arguments:

hIGear
HIGEAR handle to the image
lpRemoved
A far pointer to a BOOL which returns TRUE if the Current Data Element was removed; it will return FALSE if there are no more removable DEs in the Data Set or if the Current Data Element could not be removed.

Description:

This function removes the Current Data Element from the Data Set. The new Current Data Element will be the Data Element following the one that was just removed, unless you have deleted the last DE, in which case the CDE will be the "new" last DE.

If the Data Set is empty (there are no removable DEs remaining) lpRemoved will return FALSE. The critical DEs cannot be removed. Non-removable DEs also include Sequence and Item Delimiters.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_DE_insert

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_DE_insert(HIGEAR hIGear,
                     const AT_DCM_TAG Tag,
                     const AT_DCM_VR vr,
                     const LPVOID lpData,
                     const DWORD size_of_data);

Arguments:

hIGear
HIGEAR handle to the image
Tag
Set to a Tag value. The Tag must be supplied as a 32-bit value in which the first 16 bits (WORD) represent the Group Number and the second 16 bits represent the Element Number. (See DCM.h ).
vr
Set to the VR (Value Representation) of the Data Element to be inserted. AT_DCM_VR is a structure defined in DCM.h.
lpData
A far VOID pointer to the data that you would like to insert.
size_of_data
Set this DWORD variable to the size of the data in lpData.

Description:

This function inserts a Data Element into the Data Set. Your new Data Element will be placed into the Data Set sorted by its Tag value on the same level as that of the Current Data Element. If the DE already exists, the new one overwrites it. Specifying a Group Length DE does not cause an error, but simply is ignored. Your data will be padded to an even length if necessary.

NOTE: As of this writing, there are no constants defined for those Data Elements that have a VR of "CS." Refer to Part 3 of the Specification for the valid Code Strings which you can enter for data of type CS (Code String). Note also that the length of a Code String is the number of characters between the parentheses.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR		hIGear;
MED_DCM_DS_DE_insert(hIGear, DCM_TAG_PhotometricInterpretation,
MED_DCM_VR_CS, "MONOCHROME2", 11);


MED_DCM_DS_destroy

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_destroy(HIGEAR hIGear);

Arguments:

hIGear
HIGEAR handle of the image whose Data Set will be destroyed.

Description:

This function destroys the Data Set associated with the HIGEAR image specified. Once the Data Set is removed, the image is just like any other image loaded into ImageGear.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_exists

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_exists(const HIGEAR hIGear,
                    LPBOOL lpExists);

Arguments:

hIGear
A HIGEAR handle to an image
lpExists
A far pointer that returns a BOOL. If it returns TRUE, a Data Set exists for the image; if it returns FALSE, a Data Set does not exist for the image.

Description:

This function determines whether an image has a Data Set associated with it. Supply it with the HIGEAR handle to the image you want to check, and lpExists will return whether or not it has a Data Set.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_info_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_info_get(const HIGEAR hIGear,
                    LPDWORD lpNumTags,
                    LPDWORD lpMaxLevel);

Arguments:

hIGear
HIGEAR handle to an image
lpNumTags
A far pointer to a DWORD which returns the number of Data Elements (same as the number of Tags) associated with the image's Data Set.
lpMaxLevel
A far pointer to a DWORD which returns the maximum SQ Level of the Data Set.

Description:

This function returns the number of Data Elements (DEs) associated with the Data Set of the HIGEAR image. You might use the number of DEs returned to set the limit on a loop that iterates through each Data Element in a Data Set. If the DataSet contains SQ (Sequence of Items) data elements, the method returns the total number of data elements, including data elements contained within sequences. If there are no SQ Data Elements, lpMaxLevel is set to 0.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_is_empty

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_is_empty(const HIGEAR hIGear,
                    LPBOOL lpIsEmpty);

Arguments:

hIGear
HIGEAR handle to the image
lpIsEmpty
A far pointer to a BOOL which returns the status of the Tags in the Data Set

Description:

This function returns a TRUE through lpIsEmpty argument if the Data Set associated with HIGEAR has no Data Elements in it.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_LUT_copy_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_LUT_copy_get(
    HIGEAR hIGear,
    HIGEAR hIGearPresstate,
    AT_DCM_TAG lutSqTag,
    HIGLUT *lpLUT
);

Arguments:

hIGear
Image, which dataset is checked for presence of the LUT.
hIGearPresstate
Presentation state HIGEAR, which dataset is checked for presence of the LUT. Set to NULL if no presentation state HIGEAR is available.
lutSqTag
Specifies the LUT sequence.
lpLUT
Returns new HIGLUT object with the LUT obtained from a DataSet.

Description:

This function obtains a new copy of a specified LUT from either presentation state HIGEAR (hIGearPresState), or the image HIGEAR (hIGear). If the LUT exists in both the Presentation state HIGEAR, and in the image HIGEAR, the function returns the LUT from Presentation State HIGEAR.

Use IG_LUT_destroy () to destroy the LUT returned from this function, when it is no longer neded.

This function supports the following LUT sequences:

  • DCM_TAG_ModalityLUTSequence
  • DCM_TAG_VOILUTSequence
  • DCM_TAG_PresentationLUTSequence

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_LUT_exists

Group: Data Set Utility

Declaration:

AT_BOOL ACCUAPI MED_DCM_DS_LUT_exists(
    HIGEAR hIGear,
    HIGEAR hIGearPresstate,
    AT_DCM_TAG lutSqTag
);

Arguments:

hIGear
Image, which dataset is checked for presence of the LUT
hIGearPresstate
Presentation state HIGEAR, which dataset is checked for presence of the LUT. Set to NULL if no presentation state HIGEAR is available.
lutSqTag
Specifies the LUT sequence .

Description:

This function checks whether a presentation state HIGEAR (hIGearPresState), or the image HIGEAR (hIGear) contain specified LUT sequence.

This function supports the following LUT sequences:

  • DCM_TAG_ModalityLUTSequence
  • DCM_TAG_VOILUTSequence
  • DCM_TAG_PresentationLUTSequence

Bits Per Pixel: 8...16-bit

Return Value:

TRUE if the DataSet attached to the HIGEAR has a specified LUT sequence, FALSE - otherwise.


MED_DCM_DS_LUT_update_from

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_LUT_update_from(
    HIGEAR hIGear,
    AT_DCM_TAG lutSqTag,
    HIGLUT lut
);

Arguments:

hIGear
HIGEAR handle to the image
lutSqTag
LUT sequence.
lut
LUT handle.

Description:

This function adds specified LUT to the DataSet.

The function supports the following LUTs:

LUT
Sequence Tag
Modality LUT
DCM_TAG_ModalityLUTSequence
VOI LUT
DCM_TAG_VOILUTSequence, DCM_TAG_SoftcopyVOILUTSequence
Presentation LUT
DCM_TAG_PresentationLUTSequence

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_move_ascend

Group: Data Set Navigation

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_move_ascend(HIGEAR hIGear,
    LPAT_DCM_TAG  lpTag,
    LPAT_DCM_VR   lpVR,
    LPAT_DCM_VL   lpVL,
    LPWORD        lpLevel,
    LPDWORD       lpICount);

Arguments:

hIGear
HIGEAR handle to the image
lpTag
A far pointer that returns a 32-bit value of type AT_DCM_TAG indicating the numerical value of the Tag of the Current Data Element; set this to NULL if you do not need this information. The numerical values of the DICOM Tags are defined in DataDict.h.
lpVR
A far pointer which returns the new current VR (Value Representation). Set to NULL if you don't need this information. AT_DCM_VR is a type defined in DCM.h .
lpVL
A far pointer which returns the length of the Data Field, in bytes. AT_DCM_VL is a data type defined in DCM.h.
lpLevel
A far pointer to a WORD which returns the level in the hierarchy of the new Current Data Element; set to NULL, if you do not need this information.
lpICount
Returns the Item Count of the data; set to NULL if you don't need this information.

Description:

This function moves the Current Data Element up one level. This is only applicable if the Current Data Element is positioned within an SQ Data Element or within an Item Data Element.

If the Current Data Element is positioned anywhere in an SQ, the Current Data Element ascends to the SQ. If within an Item, the new Current DE becomes the Item DE. Only one level is ascended per call.

If the Current DE is at the top level (0), no action is taken.

If this function is successful the lpLevel decreases in value by 1. Zero refers to the top level. As the number gets larger the Data Element is deeper into the hierarchy. Data Elements (as well as SQs and Item Delimiters) are always stored in even-numbered levels; odd-numbered levels contain Items and SQ Delimiters.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_move_descend

Group: Data Set Navigation

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_move_descend (
const HIGEAR hIGear,
LPAT_DCM_TAG lpTag,
LPAT_DCM_VR  lpVR,
LPAT_DCM_VL lpVL,
LPWORD       lpLevel,
LPDWORD      lpICount);

Arguments:

hIGear
HIGEAR handle to the image
lpTag
A far pointer that returns a 32-bit value of type AT_DCM_TAG indicating the numerical value of the Tag of the Current Data Element; set this to NULL if you do not need this information. The numerical values of the DICOM Tags are defined in DataDict.h.
lpVR
A far pointer which returns the new current VR (Value Representation). Set to NULL if you don't need this information. AT_DCM_VR is a structure defined in DCM.h .
lpVL
A far pointer which returns the length of the Data Field, in bytes. AT_DCM_VL is a data type defined in DCM.h.
lpLevel
A far pointer to a WORD which returns the level in the hierarchy of the new Current Data Element; set to NULL, if you do not need this information.
lpICount
Returns the Item Count of the data; set to NULL if you don't need this information.

Description:

This function moves the Current Data Element down one level. This is only applicable if the Current Data Element is positioned at an SQ Data Element or at an Item Data Element.

If the Current Data Element is positioned at an SQ Data Element, the Current Data Element will descend to the first Item in the sequence. If at an Item, the new Current DE becomes the first DE within the Item. Only one level is descended per call.

If the Current DE does not point to an SQ or Item DE, no action is taken and lpLevel returns the Current Level.

If this function is successful the lpLevel increments from its Current DE level. Zero refers to the top level. As the number gets larger the Data Element is deeper into the hierarchy. Data Elements (as well as SQs and Item Delimiters) are always stored in odd-numbered levels; even-numbered levels contain Items and SQ Delimiters.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_move_find

Group: Data Set Navigation

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_move_find(HIGEAR hIGear,
    const AT_MODE    level_op,
    const AT_DCM_TAG Tag,
    LPAT_DCM_VR      lpVR,
    LPAT_DCM_VL		    lpVL,
    LPDWORD          lpLevel,
    LPDWORD          lpICount,
    LPBOOL           lpTagFound);

Arguments:

hIGear
HIGEAR handle to the image
level_op
A variable of type AT_MODE that tells the function how to move when it comes to an SQ. SQs are like indented outline items, allowing for hierarchies of Data Elements. Set this to one of the following constants:
MED_DCM_MOVE_LEVEL_FIXED: This setting tells the function to move only within the same level as the previous Current DE. An SQ and all its Data Elements are skipped over. If you are in a SQ you can only move about the SQ.
MED_DCM_MOVE_LEVEL_FLOAT: This setting tells the function to move up or down as needed to get to the next DE. If the next DE is an SQ the Current DE moves down into it. At the end of the SQ the Current DE will move back out to the lower levels (for example, from Level 2 to Level 1).
Tag
Set to a value of type DWORD that identifies the Tag value you would like to search for. The first 16 bits of the DWORD represent the Group Number; the second 16 bits represent the Element Number.
lpVR
A far pointer which returns the new current VR (Value Representation). Set to NULL if you don't need this information. AT_DCM_VR is a structure defined in DCM.h .
lpVL
A far pointer which returns the length of the Data Field, in bytes. AT_DCM_VL is a data type defined in DCM.h.
lpLevel
A far pointer to a WORD which returns the level in the hierarchy of the new Current Data Element; set to NULL, if you do not need this information.
lpICount
Returns the Item Count of the data; set to NULL if you don't need this information.
lpTagFound
Returns TRUE is the Tag was found; FALSE otherwise.

Description:

This function searches the Data Set associated with hIGear for the Tag specified in lpTag. If the Tag is found, the Data Element becomes the Current Data Element. This function also returns the VR (Value Representation), the number of bytes in the Tag's data, and the Item Count.

The levels of the Data Set that will be searched depends on the setting of level_op.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_move_find_first

Group: Data Set Navigation

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_move_find_first(const HIGEAR
hIGear,
    const AT_MODE level_op,
    const WORD    GroupNum,
    LPAT_DCM_VR   lpVR,
    LPAT_DCM_VL		 lpVL,
    LPDWORD       lpLevel,
    LPDWORD       lpItem_count,
    LPBOOL        lpTagFound);

Arguments:

hIGear
HIGEAR handle of the image
level_op
A variable of type AT_MODE that tells the function how to move when it comes to an SQ. SQs are like indented outline items, allowing for hierarchies of Data Elements. Set this to one of the following constants:
MED_DCM_MOVE_LEVEL_FIXED: This setting tells the function to move only within the same level as the previous Current DE. An SQ and all its Data Elements are skipped over. If you are in a SQ you can only move about the SQ.
MED_DCM_MOVE_LEVEL_FLOAT: This setting tells the function to move up or down as needed to get to the next DE. If the next DE is an SQ the Current DE moves down into it. At the end of the SQ the Current DE will move back out to the lower levels (for example, from Level 2 to Level 1).
GroupNum
Set this WORD variable to the Group Number to search for
lpVR
A far pointer which returns the new current VR (Value Representation). Set to NULL if you don't need this information. AT_DCM_VR is a structure defined in DCM.h .
lpVL
A far pointer which returns the length of the Data Field, in bytes. AT_DCM_VL is a data type defined in DCM.h.
lpLevel
A far pointer to a WORD which returns the level in the hierarchy of the new Current Data Element; set to NULL, if you do not need this information.
lpICount
Returns the Item Count of the data; set to NULL if you don't need this information.
lpTagFound
Returns TRUE is the Tag was found; FALSE otherwise.

Description:

This function searches the Data Set associated with the HIGEAR image for the first Tag of the Group Number specified by GroupNum. When the first Tag with group GroupNum is found, the Data Element is made the Current Data Element. This function also returns the VR (Value Representation), the number of bytes in the Tag's data, and the Item Count.

Which levels of the Data Set will be considered depends on the setting of level_op.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_move_first

Group: Data Set Navigation

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_move_first(const HIGEAR hIGear,
    const AT_MODE level_op,
    LPAT_DCM_TAG  lpTag,
    LPAT_DCM_VR   lpVR,
    LPAT_DCM_VL		 lpVL,
    LPWORD        lpLevel,
    LPDWORD       lpICount);

Arguments:

hIGear
HIGEAR handle to the image
level_op
A variable of type AT_MODE that tells the function how to move when it comes to an SQ. SQs are like indented outline items, allowing for hierarchies of Data Elements. Set this to one of the following constants:
MED_DCM_MOVE_LEVEL_FIXED: This setting tells the function to move only within the same level as the previous Current DE. An SQ and all its Data Elements are skipped over. If you are in a SQ you can only move about the SQ.
MED_DCM_MOVE_LEVEL_FLOAT: This setting tells the function to move up or down as needed to get to the next DE. If the next DE is an SQ the Current DE moves down into it. At the end of the SQ the Current DE will move back out to the lower levels (for example, from Level 2 to Level 1).
lpTag
A far pointer that returns a 32-bit value of type AT_DCM_TAG indicating the numerical value of the Tag of the Current Data Element; set this to NULL if you do not need this information. The numerical values of the DICOM Tags are defined in DataDict.h.
lpVR
A far pointer which returns the new current VR (Value Representation). Set to NULL if you don't need this information. AT_DCM_VR is a structure defined in DCM.h .
lpVL
A far pointer which returns the length of the Data Field, in bytes. AT_DCM_VL is a data type defined in DCM.h.
lpLevel
A far pointer to a WORD which returns the level in the hierarchy of the new Current Data Element; set to NULL, if you do not need this information.
lpICount
Returns the Item Count of the data; set to NULL if you don't need this information.

Description:

This function makes the first Data Element in the specified level the Current Data Element. This function also returns the DE's VR (Value Representation), the number of bytes in the Tag's data, and the Item Count.

Which level of the Data Set will be considered depends upon the setting of level_op.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_move_index

Group: Data Set Navigation

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_move_index(const HIGEAR hIGear,
    const DWORD  index,
    LPAT_DCM_TAG lpTag,
    LPAT_DCM_VR  lpVR,
    LPAT_DCM_VL		lpVL,
    LPDWORD      lpLevel,
    LPDWORD      lpICount);

Arguments:

hIGear
The HIGEAR handle to the image
index
Set to a DWORD that indicates the index that you would like to become the new Current Data Element.
lpTag
A far pointer that returns a 32-bit value of type AT_DCM_TAG indicating the numerical value of the Tag of the Current Data Element; set this to NULL if you do not need this information. The numerical values of the DICOM Tags are defined in DataDict.h.
lpVR
A far pointer which returns the new current VR (Value Representation). Set to NULL if you don't need this information. AT_DCM_VR is a structure defined in DCM.h .
lpVL
A far pointer which returns the length of the Data Field, in bytes. AT_DCM_VL is a data type defined in DCM.h.
lpLevel
A far pointer to a WORD which returns the level in the hierarchy of the new Current Data Element; set to NULL, if you do not need this information.
lpICount
Returns the Item Count of the data; set to NULL if you don't need this information.

Description:

This function moves the Current Data Element to the Data Element in the Data Set indicated by index, which represent a particular index in the array of Data Elements that make up the Data Set. This function also returns the Tag's VR (Value Representation), its Tag value, the number of bytes in the Tag's data, and the Item Count. The index refers to which element in the Data Element array should be used. The first Data Element will always have an index of 0, and the last Data Element will always have an index of (Total # of DEs - 1). Use MED_DCM_DS_info_get()to find out the total # of Data Elements associated with an image's Data Set.

This function pays no attention to Levels. It only returns you the level of the Current Data Element.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_move_last

Group: Data Set Navigation

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_move_last(const HIGEAR hIGear,
    const AT_MODE level_op,
    LPAT_DCM_TAG  lpTag,
    LPAT_DCM_VR   lpVR,
    LPAT_DCM_VL		 lpVL,
    LPWORD        lpLevel,
    LPDWORD       lpICount);

Arguments:

hIGear
HIGEAR handle to the image
level_op
A variable of type AT_MODE that tells the function how to move when it comes to an SQ. SQs are like indented outline items, allowing for hierarchies of Data Elements. Set this to one of the following constants:
MED_DCM_MOVE_LEVEL_FIXED: This setting tells the function to move only within the same level as the previous Current DE. An SQ and all its Data Elements are skipped over. If you are in a SQ you can only move about the SQ.
MED_DCM_MOVE_LEVEL_FLOAT: This setting tells the function to move up or down as needed to get to the next DE. If the next DE is an SQ the Current DE moves down into it. At the end of the SQ the Current DE will move back out to the lower levels (for example, from Level 2 to Level 1).
lpTag
A far pointer that returns a 32-bit value of type AT_DCM_TAG indicating the numerical value of the Tag of the Current Data Element; set this to NULL if you do not need this information. The numerical values of the DICOM Tags are defined in DataDict.h
lpVR
A far pointer which returns the new current VR (Value Representation). Set to NULL if you don't need this information. AT_DCM_VR is a structure defined in DCM.h .
lpVL
A far pointer which returns the length of the Data Field, in bytes. AT_DCM_VL is a data type defined in DCM.h.
lpLevel
A far pointer to a WORD which returns the level in the hierarchy of the new Current Data Element; set to NULL, if you do not need this information.
lpICount
Returns the Item Count of the data; set to NULL if you don't need this information.

Description:

This function moves the Current Data Element to the last Data Element in the Data Set, or in the current level, depending on level_op setting.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_move_next

Group: Data Set Navigation

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_move_next(const HIGEAR hIGear,
    const AT_MODE level_op,
    LPAT_DCM_TAG  lpTag;
    LPAT_DCM_VR   lpVR,
    LPAT_DCM_VL		 lpVL,
    LPWORD        lpLevel,
    LPDWORD       lpICount,
    LPLONG        lpNumRemaining);

Arguments:

hIGear
HIGEAR handle to the image
level_op
A variable of type AT_MODE that tells the function how to move when it comes to an SQ. SQs are like indented outline items, allowing for hierarchies of Data Elements. Set this to one of the following constants:
MED_DCM_MOVE_LEVEL_FIXED: This setting tells the function to move only within the same level as the previous Current DE. An SQ and all its Data Elements are skipped over. If you are in a SQ you can only move about the SQ.
MED_DCM_MOVE_LEVEL_FLOAT: This setting tells the function to move up or down as needed to get to the next DE. If the next DE is an SQ the Current DE moves down into it. At the end of the SQ the Current DE will move back out to the lower levels (for example, from Level 2 to Level 1).
lpTag
A far pointer that returns a 32-bit value of type AT_DCM_TAG indicating the numerical value of the Tag of the Current Data Element; set this to NULL if you do not need this information. The numerical values of the DICOM Tags are defined in DataDict.h
lpVR
A far pointer which returns the new current VR (Value Representation). Set to NULL if you don't need this information. AT_DCM_VR is a structure defined in DCM.h .
lpVL
A far pointer which returns the length of the Data Field, in bytes. AT_DCM_VL is a data type defined in DCM.h.
lpLevel
A far pointer to a WORD which returns the level in the hierarchy of the new Current Data Element; set to NULL, if you do not need this information.
lpICount
Returns the Item Count of the data; set to NULL if you don't need this information.
lpNumRemaining
A far pointer to a LONG that returns the number of DE remaining until the end is reached. If the returned value is 0, you are now at last DE, if the returned value is -1, you have attempted to move past the last DE.

Description:

This function moves the Current Data Element to the next Data Element in the Data Set. The value of lpNumRemaining tells you whether the Tag has now become the last Tag in the list.

The level_op setting determines whether the Current Data Element can move from level to level, or has to stay on the same level.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

AT_ERRCOUNT nErrcount;
HIGEAR			hIGear;
BOOL			IsLast;
AT_DCM_TAG			 lpTag;
AT_DCM_VR			lpVR;
AT_DCM_VL			lpVL;
DWORD			lpICount;
DWORD			size_of_lpData;
IsLast = FALSE:
  MED_DCM_DS_move_first(hIGear, &lpTag, &lpVR, &lpVL,
&lpICount);
/* iterate through all Data Elements returning the Tag, VR, VL
and item count of each one. End the loop when lpIsLast == TRUE
*/
while (IsLast == FALSE) {
    MED_DCM_DS_curr_data_get(hIGear, lpData, size_of_lpData);
    MED_DCM_DS_move_next(hIGear, &lpTag, &lpVR, &lpVL,
&lpICount, &lpIsLast);
}


MED_DCM_DS_move_prev

Group: Data Set Navigation

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_move_prev(const HIGEAR hIGear,
    const AT_MODE level_op,
    LPAT_DCM_TAG  lpTag;
    LPAT_DCM_VR   lpVR,
    LPAT_DCM_VL		 lpVL,
    LPWORD        lpLevel,
    LPDWORD       lpICount,
    LPLONG        lpNumRemaining);

Arguments:

hIGear
HIGEAR handle to the image
level_op
A variable of type AT_MODE that tells the function how to move when it comes to an SQ. SQs are like indented outline items, allowing for hierarchies of Data Elements. Set this to one of the following constants:
MED_DCM_MOVE_LEVEL_FIXED: This setting tells the function to move only within the same level as the previous Current DE. An SQ and all its Data Elements are skipped over. If you are in a SQ you can only move about the SQ.
MED_DCM_MOVE_LEVEL_FLOAT: This setting tells the function to move up or down as needed to get to the next DE. If the next DE is an SQ the Current DE moves down into it. At the end of the SQ the Current DE moves back out to the lower levels (for example, from Level 2 to Level 1).
lpTag
A far pointer that returns a 32-bit value of type AT_DCM_TAG indicating the numerical value of the Tag of the Current Data Element; set this to NULL if you do not need this information. The numerical values of the DICOM Tags are defined in DataDict.h
lpVR
A far pointer which returns the new current VR (Value Representation). Set to NULL if you don't need this information. AT_DCM_VR is a structure defined in DCM.h.
lpVL
A far pointer which returns the length of the Data Field, in bytes. AT_DCM_VL is a data type defined in DCM.h.
lpLevel
A far pointer to a WORD which returns the level in the hierarchy of the new Current Data Element; set to NULL, if you do not need this information.
lpICount
Returns the Item Count of the data; set to NULL if you don't need this information.
lpNumRemaining
A far pointer to a LONG that returns the number of DE remaining until the top is reached. If the returned value is 0, you are now at first DE, if the returned value is -1, you have attempted to move past the first DE.

Description:

This function moves the Current Data Element to the previous Data Element in the Data Set. The value of lpNumRemaining tells you whether the Tag has now become the first Tag in the list.

The level_op setting determines whether the Current Data Element can move from level to level, or has to stay on the same level.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_orig_TS_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_orig_TS_get(const HIGEAR hIGear,
    LPAT_MODE lpOrigTS,
    LPBOOL    lpPart10,
    LPBOOL    lpGrpLengths);

Arguments:

hIGear
HIGEAR handle to the image
lpOrigTS
A far pointer to the original setting for TS (Transfer Syntax). Set to NULL if you do not need this information. Transfer Syntax constants are defined in DataDict.h as : MED_DCM_TS_IMPLICIT_VR_LE, MED_DCM_TS_EXPLICIT_VR_LE, etc.
lpPart10
A far pointer to a BOOL which indicates whether the original file was a Part 10 file.
If TRUE-the original was a Part 10 file;
If FALSE-the original was not a Part 10 file.
Set to NULL if you do not need this information.
lpGrpLengths
A far pointer that returns a Boolean value indicating whether the original DICOM image had any Group Length Data Elements in it. TRUE means that it did have Group Length Data Elements; FALSE means that there were none. Set to NULL if you do not need this information.

Description:

This function returns the original Transfer Syntax used for the image, and indicates whether of not it had a Part 10 header and the group length Data Elements.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_part10_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_part10_get(const HIGEAR hIGear,
    const AT_MODE part10_item,
    const DWORD		 size_of_lpData,
    LPVOID        lpData,
    LPDWORD       lpSize_of_item);

Arguments:

hIGear
HIGEAR handle to the image
part10_item
Set to the item in Part 10 that you would like to get. Use one of the AT_MODE constants defined in DCM.h that begin with DCM_PART10_ITEM_SET_.
size_of_lpData
Set to the size of the buffer lpData that you allocate to receive the data. This function will not copy more than this amount of data from the Part 10 Header, stored in the HIGEAR, to this buffer.
lpData
A far pointer to a VOID buffer in which return the data from the item specified by part10_item.
lpSize_of_Item
A far pointer that returns the actual size of the Data Value that is stored in the Part 10 Header. It is not always the size of the data being returned in lpData. If this parameter returns a value greater than size_of_lpData then lpData does not contain all of the data-some has been clipped.

Description:

This function returns the data from the item in the Part 10 header identified by part10_item.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

#define BUFF_SIZE			150
HIGEAR			hIGear;
char		       data[BUFF_SIZE];
MED_DCM_DS_part10_get(g_hIGear, DCM_PART10_ITEM_PREAMBLE,
BUFF_SIZE, data, &size_of_data);


MED_DCM_DS_part10_set

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_part10_set(const HIGEAR hIGear,
    const AT_MODE   part10_item,
    const LPVOID    lpData,
    const AT_DCM_VL  vl);

Arguments:

hIGear
HIGEAR handle to the image
part10_item
Set this variable to the type of Part 10 item you would like to set. Use one of the constants defined in DCM.h that begin with DCM_PART10_ITEM_
lpData
A far VOID pointer to the data that you would like to store into the Part 10 item.
vl
Set to the length of the Data Field, in bytes. AT_DCM_VL is a data type defined in DCM.h.

Description:

This function sets the data of the item in the Part 10 header identified by part10_item.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_PixPadVal_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_PixPadVal_get(HIGEAR hIGear,
    LPBOOL lpUse_Pix_Padding,
    LPLONG lpPix_Padding_Val,
    LPBYTE lpShow_PPV_as);

Arguments:

hIGear
HIGEAR handle to the image for which you would like to set the value of the "Pixel Padding Value" Data Element (0028,0120).
lpUse_Pix_Padding
Returns TRUE if the value of Pixel Padding Value (0028,0120) will be used; FALSE if the value of Pixel Padding Value will be ignored.
lpPix_Padding_Val
Returns the grayscale value that will be used for padding. This value read is that which is stored in the Pixel Padding Value Data Element (0028,0120) of the internal Data Set.
lpShow_PPV_as
Returns the grayscale value that will be used to display pixels equal to the Pixel Padding Value.

Description:

This function retrieves the Pixel Padding Value (PPV) that is being used for the display of 16-bit grayscale images. This function also returns whether or not the PPV value will be used. The Pixel Padding Value is most often used to fill in the regions around a circular image. This function does not retrieve the PPV Data Element from the Data Set attached to the HIGEAR. It gets the value for PPV from the Internal Data Set (HDS) (which may be equal to the value in the actual Data Set). The purpose of this function is to let you know whether Pixel Padding is set on and off, what, if any value it has, and what color it is set to display as.

Please see the description for MED_DCM_DS_PixPadVal_set() for a complete description of how ImageGear handles the Pixel Padding Value Data Element.

To turn off the Pixel Padding Value or to alter the value being used use MED_DCM_DS_PixPadVal_set().

Bits Per Pixel: 9-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

AT_ERRCOUNT 		nErrcount;
HIGEAR		hIGear;
LONG 		Pix_Padding_Val;
BYTE 		Show_PPV_as;
nErrcount = MED_DCM_DS_PixPadVal_get(g_hIGear, NULL,
&Pix_Padding_Val, &Show_PPV_as);


MED_DCM_DS_PixPadVal_set

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_PixPadVal_set(HIGEAR hIGear,
    const BOOL Use_Pix_Padding,
    const LONG Pix_Padding_Val,
    const BYTE Show_PPV_as);

Arguments:

hIGear
HIGEAR handle to the image for which you would like to set the value of the internal representation of the "Pixel Padding ValueData Element (0028,0120)".
Use_Pix_Padding
Set this to TRUE to use the value of Pixel Padding Value (0028,0120); FALSE to ignore the value of Pixel Padding Value.
Pix_Padding_Val
Set this argument to the grayscale value to use for the image. This value will be stored in the Pixel Padding Value Data Element (0028,0120) of the internal Data Set. This new value is the value that will be locked into the 16x8 LUT when Pixel Padding is turned on.
Show_PPV_as
Set to the grayscale value that will be used to display pixels equal to the Pixel Padding Value.

Description:

This function is used to set the Pixel Padding Value that is to be used while displaying a 16-bit grayscale image. Here is a description of what this Data Element is used for and how ImageGear implements its use:

DICOM images sometimes contain a Data Element called "Pixel Padding Value" (PPV). The PPV is used mostly to fill in the corners of round images. DICOM provides a Tag for PPV which is (0028,0120). This Data Element stores a 16-bit grayscale value that is to be treated as the Pixel Padding Value. Any pixels in the image that have this value are not to be treated as meaningful objects-but as background color.

When ImageGear Medical loads a DICOM image that contains a PPV the value is captured and stored in the HDS, which is attached to the HIGEAR of the new image. In fact, 3 values are stored to the HDS: the PPV from the PPV Data Element, a flag indicating that a PPV was found in the file when it was loaded, and an 8-bit grayscale value to use to display pixels with this value. This function sets the values of these in-memory copies of the PPV data.

When Use_Pix_Padding is set to TRUE, pixels from the original image equal to the PPV are treated as background. All functions that fill the 16x8 LUT skip this value and place the Show_PPV_As value in the PPV slot of the table. This allows an application to adjust the contrast of the image while keeping the PPV or background constant. The background will be displayed with a grayscale value equal to that stored in Show_PPV_As. The PPV is also used for the IP functions. Functions like MED_IP_min_max() ignore pixel values that are equal to the PPV. (see below).

Use_Pix_Padding is initially set to TRUE if the loaded image contained the Pixel Padding Value Data Element (0028,0120). If this Data Element was not found then this defaults to FALSE

Pix_Padding_Val is initially set to the Data Field of the Pixel Padding Value Data Element (0028,0120) if it is found. If it is not it is set to default (NULL).

Show_PPV_As is not part of the PPV Data Element. This value always defaults to 64.

When the Pixel Padding Value is turned "on" (Use_Pix_Padding = TRUE) the MED_IP_min_max() function will know to ignore this value as it searches through the image for the brightest and darkest pixel value so that it avoids treating the Pixel Padding Value as the minimum or max pixel value. This error could easily occur because Pixel Padding Value is most often set to a very large or very small value so that it can be easily differentiated from the real pixel values.

To retrieve the Pixel Padding Value that is currently stored in the HIGEAR (not the one in the Data Set although them may have the same value) see MED_DCM_DS_PixPadVal_get().

Bits Per Pixel: 9-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

AT_ERRCOUNT 		nErrcount;
HIGEAR		hIGear;
LONG 		Pix_Padding_Val;
BYTE 		Show_PPV_as;
BOOL		Pref_use_pix_pad;
nErrcount = MED_DCM_DS_PixPadVal_set(hIGear, bPref_use_pix_pad,
Pix_Padding_Val, Show_PPV_as);


MED_DCM_DS_preamble_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_preamble_get(const HIGEAR
hIGear,
    LPCHAR *lpPreamble);

Arguments:

hIGear
HIGEAR handle to the image
lpPreamble
A far pointer to a buffer that will be used to hold the data from the preamble. The buffer must be at least 128 bytes.

Description:

This function gets the preamble item from the Part 10 header of the image, if one exists. Your receiving buffer must be at least 128 bytes.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_preamble_set

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_preamble_set(const HIGEAR
hIGear,
    LPCHAR      lpPreamble,
    const DWORD bytes_in_lpPreamble);

Arguments:

hIGear
HIGEAR handle to the image
lpPreamble
A far pointer to the preamble of the Data Set
bytes_in_lpPreamble
The number of bytes in your Preamble data

Description:

This function sets the value of the Preamble item of the Part 10 header. Provide it with the address of the Preamble in lpPreamble, and the number of bytes for the new Preamble in bytes_in_lpPreamble. If the length of the data is less than 128 bytes, the remainder of the Preamble is filled with NULLs.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_Rescale_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_Rescale_get(const HIGEAR hIGear,
    LPDOUBLE lpRescale_Slope,
    LPDOUBLE lpRescale_Intercept,
    LPBOOL   lpFound);

Arguments:

hIGear
Set to the HIGEAR handle of the image you would like to retrieve the Rescale values from.
lpRescale_slope
Returns you the value of the Rescale Slope Data Element as a DOUBLE. The Tag value of this DE is (0028,1053).
lpRescale_intercept
Returns you the value of the Rescale Intercept Data Element as a DOUBLE. The Tag value of this DE is (0028,1054).
lpFound
Returns whether or not these two Data Elements were found/present in the image's Data Set.

Description:

This function will search the DICOM Data Set of the HIGEAR image and return the value from Rescale Slope (0028,1053) and Rescale Intercept (0028,1054). This function is a short cut that was created because the values of these Data Elements are often sought after. You could perform this same operation, as you would for getting the information from any DE, by using MED_DCM_DS_move_find () and MED_DCM_DS_curr_data_get ().

If both of these DEs are found in the Data Set, then lpFound returns TRUE. If one or both are missing then lpFound will return FALSE, lpRescale_slope will return 1.0 and lpRescale_intercept will return 0.0. lpFound can be set to NULL if you do not need to know if they are found or not. The returned slope and interface values returned are always usable even if they are not found in the Data Set.

Both this function and MED_DCM_DS_Window_Level_get() should be called before displaying an image using MED_display_contrast ().

Bits Per Pixel: 9-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

AT_ERRCOUNT nErrcount;
HIGEAR			hIGear;
DOUBLE RescaleSlope, RescaleIntercept;
nErrcount = MED_DCM_DS_Rescale_get(hIGear, &RescaleSlope,
&RescaleIntercept, 	NULL);


MED_DCM_DS_TAG_ELEMENT

Group: Data Set Utility
Group: (Macro)

Declaration:

MED_DCM_DS_TAG_ELEMENT(Tag);

Arguments:

Tag
Supply this argument with a 32-bit Tag value that begins with DCM_TAG_

Description:

This macro is used for getting the Element number out of a Tag. Supply it with a 32-bit Tag value and it will return you with the 16-bit Element Number value. The Element Number is the least significant WORD of the 32-bit Tag value. This macro is defined in DataDict.h.

Bits Per Pixel: N/A

Return Value:

Returns the 16-bit Element Number portion of a 32-bit Tag value.

Example:

element = MED_DCM_DS_TAG_ELEMENT(DCM_TAG_IssuerOfPatientID)
/* element equals 0x0021				*/


MED_DCM_DS_TAG_GROUP

Group: Data Set Utility
Group: (Macro)

Declaration:

MED_DCM_DS_TAG_GROUP(Tag)

Arguments:

Tag
Supply this argument with a 32-bit Tag value

Description:

This macro is used for getting the Group Number out of a Tag. Supply it with a 32-bit Tag value and it will return you with the 16-bit Group Number value. The Group Number is the most significant WORD of the 32-bit Tag value. This macro is defined in DataDict.h.

Bits Per Pixel: N/A

Return Value:

Returns the 16-bit Group Number portion of a 32-bit Tag value

Example:

group = MED_DCM_DS_TAG_GROUP(DCM_TAG_IssuerOfPatientID)
/* group equals 0x0010				*/


MED_DCM_DS_TAG_MAKE

Group: Data Set Utility
Group: (Macro)

Declaration:

MED_DCM_DS_TAG_MAKE(gn, en);

Arguments:

gn
Supply this with a valid DICOM Group Number
en
Supply this with a valid DICOM Element Number

Description:

This macro takes a 16-bit Group Number and a 16-bit Element Number and returns a 32-bit Tag value. The returned Tag is compatible with the DCM_TAG_ constants in DataDict.h.

This macro is defined in DataDict.h.

Bits Per Pixel: N/A

Return Value:

Returns the 32-bit Tag value from the 16-bit Group Number and 16-bit Element Number that you provide.

Example:

AT_DCM_TAG Tag;
Tag = MED_DCM_DS_TAG_MAKE(0x0010, 0x0021)
/* Tag equals DCM_TAG_IssuerOfPatientID or 0x00100021 */


MED_DCM_DS_TS_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_TS_get( const HIGEAR hIGear,
    LPAT_MODE lpTransfer_syntax);

Arguments:

hIGear
HIGEAR handle of the image
lpTransfer_syntax
Returns the Transfer Syntax constant that corresponds to the DCM_PART10_ITEM_TRANSSYNTAXUID part 10 item in the DataSet.

Description:

This function returns the Transfer Syntax constant that corresponds to the value of DCM_PART10_ITEM_TRANSSYNTAXUID part 10 item in the DataSet.

lpTransfer_syntax returns one of the Transfer Syntax constants, defined in DataDict.h, such as:

  • MED_DCM_TS_IMPLICIT_VR_LE,
  • MED_DCM_TS_EXPLICIT_VR_LE, etc.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_TS_set

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_TS_set(HIGEAR hIGear,
    const AT_MODE Transfer_syntax);

Arguments:

hIGear
HIGEAR handle of the image
Transfer_syntax
Set to the type of transfer syntax that you would like to store in the Transfer Syntax field of the Part 10 header.

Description:

This function sets the Transfer Syntax value in the Part 10 Header for "Transfer Syntax UID" Data Element (0002,0010). This value also overrides that set by MED_DCM_DS_create() function.

Transfer_syntax must be set to one of the following supported Transfer Syntax constants:

  • MED_DCM_TS_IMPLICIT_VR_LE,
  • MED_DCM_TS_EXPLICIT_VR_LE
  • MED_DCM_TS_EXPLICIT_VR_BE

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_DS_update_file

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_update_file (HIGEAR hIGear,
const LPSTR lpszFileNameSrc, const LPSTR lpszFileNameDst);

Arguments:

hIGear
HIGEAR handle, containing metadata to be saved to result file
lpszFileNameSrc
Source file name
lpszFileNameDst
Result file name

Description:

This function creates a new file with exact copy of source file's pixel data and with new metadata (File Meta Information header and DataSet) taken from HIGEAR image handle. Pixel data is not decoded but copied directly from source to destination file.

This function can be used for updating metadata in an image file without modifying the pixel data. To achieve this, delete the source file after calling this function, and rename result file to the source file name.

The function does not change the tags that affect decoding of pixel data.

The function takes into account the following DICOM filter control parameters:

SAVE_GROUPLENGTHS

SAVE_ASPART10


MED_DCM_DS_Window_Level_get

Group: Data Set Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_DS_Window_Level_get(const HIGEAR
hIGear,
    LPLONG lpWindow_Width,
    LPLONG lpWindow_Center,
    LPBOOL lpFound);

Arguments:

hIGear
HIGEAR handle to the image from which you would like to retrieve the Window Level values
lpWindow_Width
Returns the value of the Window Level Width Data Element (0028,1051).
lpWindow_Center
Returns the value of the Window Level Center Data Element (0028,1050)
lpFound
Returns a TRUE if both of these DEs are found in the Data Set; returns FALSE if one or the other is missing from the Data Set. Set to NULL if you do not need this information.

Description:

This function searches the Data Set of the HIGEAR image for the Window Width and Window Center Data Elements. This function is a short cut that was created because the values of these Data Elements are often sought after. You could perform this same operation, as you would for getting the information from any DE, by using MED_DCM_DS_move_find () and MED_DCM_DS_curr_data_get ().

If both are found they are returned and lpFound is set to TRUE. If one or both of these DEs are not found, lpFound is set to FALSE and ImageGear attempts to calculate adequate values for both Width and Center to display all pixels in the image.

Bits Per Pixel: 9-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

AT_ERRCOUNT 		nErrcount;
HIGEAR		hIGear;
LONG		lWindow_min, lWindow_max;
nErrcount = MED_DCM_DS_Window_Level_get(hIGear, &lWindow_min,
&lWindow_max, 	NULL);


MED_DCM_load_DICOM

Group: Load/Save

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_load_DICOM(const LPSTR
lpszFileName,
    LPHIGEAR	 lphIGear,
    const AT_MODE nSyntax,
    const UINT page_number);

Arguments:

lpFileName
A far pointer to the name of the file to load
lphIGear
A far pointer which returns the HIGEAR handle for the newly loaded image
nSyntax
Set to the type of Transfer Syntax used for the file that you will be loading. Use one of the MED_DCM_TS_ constants defined in DCM.h .
page_number
If the file is a multipage (multiframe) file, you may set this variable to specify the page to load. If the file is not multipage, set this to 1.

Description:

This function loads a DICOM image file. It cannot be used to load an image of any other format. The advantage to using this function over IG_load_file()is that it allows you more control, and is a faster loading utility because ImageGear's filter detection is set off for you.

This function loads the file specified by the path and filename in lpFileName, and returns you a new HIGEAR handle for the image in lphIGear.

To further speed up this function, provide it with the correct Transfer Syntax (TS) of the file. If you do not know the TS, ImageGear detects it for you if you set nSyntax to MED_DCM_TS_AUTODETECT.

You may also specify the page to load from a multipage (multiframe) file.

To remove a HIGEAR image from memory call IG_image_delete().

NOTES: If your application supports unicode or multi-byte strings, you can open a file yourself ad pass us the FD handle. If you prefer to open your own file, use MED_DCM_load_DICOM_FD() .

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_load_DICOM_FD

Group: Load/Save

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_load_DICOM_FD(const AT_INT fd,
    const LONG    lOffset,
    LPHIGEAR	      lphIGear,
    const AT_MODE nSyntax,
    const UINT    page_number);

Arguments:

fd
Set to the File Descriptor handle of the opened image file
lOffset
Set to a LONG value that gives the offset from the current position in the open file to the beginning of the DICOM data. In most cases this value will be 0.
lphIGear
A far pointer which returns the HIGEAR handle for the newly loaded image
nSyntax
Set to the type of Transfer Syntax used for the file that you will be loading. Use one of the MED_DCM_TS_ constants defined in DCM.h.
page_number
If the file is a multipage file, you may set this variable to specify the page to load. If the file is not multipage, set this to 1.

Description:

This function performs the same operation as MED_DCM_load_DICOM() except that is takes a File Descriptor (FD) and offset instead of a filename. lOffset should be set to the position of the image within the file so that the ImageGear Medical knows where to begin decoding the image. If the beginning of the DICOM image file starts at the first byte, pass in an 0L for lOffset.

Since you are responsible for opening and closing the file this function can be used to bypass the IG_load_file() limitation of not handling unicode or multi-byte character strings.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_save_DICOM

Group: Load/Save

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_save_DICOM(const LPSTR
lpszFileName,
    const HIGEAR		 hIGear,
    const AT_MODE	 	nSyntax,
    const BOOL		 bIncludeGroupLengths,
    const BOOL		 bSaveAsPart10,
    const AT_MODE		 PlanarConfiguration,
    const BOOL		 IncludeSmallestLargest,
    const UINT		 nJPEGQuality,
    const DWORD		 dwReserved);

Arguments:

lpszFileName
A far pointer to the name of the file to save
hIGear
The HIGEAR handle of the image to save. This HIGEAR must have an attached DICOM Data Set.
nSyntax
Set to the type of Transfer Syntax to save the image with.
bIncludeGroupLengths
Set this Boolean variable to TRUE if you want to store the Group Lengths with the image
bSaveAsPart10
Set this Boolean variable to TRUE if you want to save a Part 10 header with the image
PlanarConfiguration
Determines how RGB pixel values are to be saved to the DICOM image file. The Planar Configuration Data Element (0028, 0006) will be automatically inserted and this value stored in it. If the Data Set already contains (0028,006) its value is ignored and the value of this parameter is used instead. This parameter is used for RGB only. It is ignored for all other image types. Set to one of the constants that begins with MED_DCM_PLANAR_.
IncludeSmallestLargest
If the image's original Data Set did not contain Data Elements for Smallest Image Pixel Value (0028,0106) and Largest Image Pixel Value (0028,0107) and you set IncludeSmallestLargest = TRUE, ImageGear will scan the image and determine a values for these DEs. Smallest Image Pixel Value and Largest Image Pixel Value will be included in the Data Set of the DICOM image being saved, and will contain the ImageGear-determined values. The values of the DE from the original Data Set (if any) will be ignored.
If you set IncludeSmallestLargest = FALSE, ImageGear will not determine this value for you, and the Data Set of the image being saved will not include the Smallest Image Pixel Value and Largest Image Pixel Value Data Elements. However, if the original Data Set did contain these DEs, ImageGear will preserve and include them in the Data Set being saved.
nJPEGQuality
The value of this argument is only relevant to lossy JPEG compression. When using any other compression scheme, this value will be ignored. (This setting would be meaningless for Lossless JPEG compression). Set to the amount of pixel data to preserve during lossy JPEG compression. The range of valid values is 1-100 with a default value of 70. Higher settings result in higher quality and a larger file. Note that even at 100, JPEG compression is not capable of being completely "lossless." The compression used, if any, is set by nSyntax. (MED_DCM_TS_JPEG_LOSSY_8 indicates the use of 8-bit JPEG compression).
dwReserved
Reserved for future use. Set to 0 for now.

Description:

This function saves a DICOM image file. It cannot be used to save an image of any other format. The advantage to using this function over IG_save_file()is that it allows you more control.

In order to save an image as a DICOM file the HIGEAR must have a Data Set attached to it. If you loaded the HIGEAR from a DICOM file then there already is a Data Set attached. If not, you can use the function MED_DCM_DS_create () to create one. If you are not sure if the image has a Data Set, call MED_DCM_DS_exists() to find out. If you are going to create a Data Set using MED_DCM_DS_create(), then you must still populate the Data Set with valid Data Elements using MED_DCM_DS_DE_insert ().

The nSyntax parameter determines how the DICOM image file is encoded. The valid options are the constants whose names begin with MED_DCM_TS_ (except for _TS_UNKNOWN, and _TS_AUTODETECT).

Group Lengths are optional in a DICOM image file. By default, Group Lengths are not stored in the Data Set that is attached to the HIGEAR. If you have read a DICOM file that included Group Lengths, they have been discarded as they were found. Set bIncludeGroupLength to TRUE to have them recreated and placed in the Data Set as it has been written to disk.

DICOM Image files are supposed to be written to disk using the Meta-Info Header that is defined in Part 10 of the DICOM Specification. However, many DICOM applications choose not to use this header. By setting bSaveAsPart10 using IG_image_control_set() the Meta Information Header are placed at the beginning of the file. Setting this to FALSE will skip the header.

If the image is saved without a Part 10 header, it is often called a Raw DICOM image file. Note that the Part 10 Header Data Elements are not stored the same way as other Data Elements in the Data Set. If you wish to store this data you must populate the header using the MED_DCM_DS_part10_set () function before writing the file.

NOTE: If your application supports unicode or multi-byte strings, you can open a file yourself and pass us the FD handle. If you prefer to open your own file, use MED_DCM_save_DICOM_FD() .

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_save_DICOM_FD

Group: Load/Save

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_save_DICOM_FD(AT_INT fd,
    const HIGEAR		 hIGear,
    const AT_MODE		 nSyntax,
    const BOOL		 bIncludeGroupLengths,
    const BOOL		 bSaveAsPart10,
    const AT_MODE		 nPlanarConfiguration,
    const BOOL		 bInludeSmallestLargest,
    const UINT 		nJPEGQuality,
    const DWORD		 lReserved);

Arguments:

fd
Set to the FD handle of the open image. The image must have been opened with Read/Write access
hIGear
The HIGEAR handle of the image to save. This HIGEAR must have an attached DICOM Data Set.
nSyntax
Set to the type of Transfer Syntax used for the file that you will be saving. Use one of the MED_DCM_TS_ constants defined in DCM.h .
bIncludeGroupLengths
Set this Boolean variable to TRUE if you want to store the Group Lengths with the image
bSaveAsPart10
Set this Boolean variable to TRUE if you want to save a Part 10 header with the image
nPlanarConfiguration
Determines how RGB pixel values are to be saved to the DICOM image file. The Planar Configuration Data Element (0028, 0006) will be automatically inserted and this value stored in it. If the Data Set already contains (0028,006) its value is ignored and the value of this parameter is used instead. This parameter is used for RGB only. It is ignored for all other image types. Set to one of the constants that begins with MED_DCM_PLANAR_.
bIncludeSmallestLargest
Setting this parameter to TRUE will cause the Smallest and Largest pixel value in the image to be computed and saved in Smallest Image Pixel Value (0028,0106) and Largest Image Pixel Value (0028,0107). If the Data Set contains these 2 Data Elements already they are ignored and the computed values are used. If this parameter is set to FALSE these two Data Elements are not stored in the file.
nJPEGQuality
The value of this argument is only relevant to lossy JPEG compression. When using any other compression scheme, this value will be ignored. Set to the amount of pixel data to preserve during lossy JPEG compression. The range of valid values is 1-100 with a default value of 70. Higher settings result is higher quality and a larger file. Note that even at 100, JPEG compression is not capable of being completely "lossless".
lReserved
Reserved for future use. Set to 0 for now.

Description:

This function performs the same operation as MED_DCM_save_DICOM() except that it uses the FD instead of the file name. The file must have been opened with Read/Write access.

Since you are responsible for opening and closing the file this function can be used to bypass the IG_save_file() limitation of not handling unicode or multi-byte character strings.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_util_data_to_string

Group: DICOM Utility

Declaration:

BOOL ACCUAPI MED_DCM_util_data_to_string(const LPCHAR lpData,
    const  AT_DCM_VR vr,
    const  AT_DCM_VL vl,
    const  INT first_item,
    const  INT last_item,
    LPCHAR lpString,
    const  DWORD string_len,
    const  CHAR separator);

Arguments:

lpData
A far pointer to the data from a Data Element which you would like to convert to a string
vr
Set to the Value Representation (VR) for the Data. VR types have defined constants in DCM.h and begin with MED_DCM_VR_
vl
Set to the Value Length of the Data.
first_item
First data value to process. Set to -1 to process all values.
last_item
Data value to stop processing at. This argument is only effective if first_item is not set to -1. If first_item is 0, set this argument to the number of values you'd like to process.
lpString
A far pointer to a NULL-terminated string which returns the representation of the DICOM data field specified in lpData
string_len
Set this to the length in bytes of lpString. If the length is shorter than the data being retrieved, it will simply truncate the data.
separator
Set this to the character that you would like to use to separate multiple data values; for example, you might set it to a comma or semicolon.

Description:

This function takes the DICOM Data Field of the Current Data Element, designated in lpData, and converts it to a NULL-terminated character string.

Set the vr argument to determine how the lpData is to be interpreted.

lpString can only be filled up to string_len - 1. 1 is subtracted from the string_len to accommodate the NULL. Any remainder is simply clipped.

For Data Fields with more than one data value, the separator character specified in separator is used to delimit the items.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_util_tag_info_add

Group: DICOM Utility

Declaration:

BOOL ACCUAPI MED_DCM_util_tag_info_add(const AT_DCM_TAG Tag,
    const AT_DCM_VR VR,
    const AT_DCM_VM VM,
    const WORD      wVersion,
    const LPCHAR    lpszTagName);

Arguments:

Tag
Set to a Tag value. The Tag must be supplied as a 32-bit value in which the first 16 bits (WORD) represent the Group Number and the second 16 bits represent the Element Number. (See AT_DCM_TAG definition in DCM.h ). Group and Element are expressed as WORDs.
lpVR
Set to the VR of the new Tag. The VR must be one of the predefined VRs that start with MED_DCM_VR_ (see DCM.h).
lpVM
Set to the VM of the new Tag. Value Multiplicity tells whether and/or how many items can be stored in this type of Data Element. See Note below.
wVersion
Set this to the DICOM version. This should identify the first version of DICOM that includes this Tag. Most applications should set this to 3 but any value is accepted.
LpszTagName
Set to a character string name that should be provided as the description of this Tag.

Description:

This function allows to add new entries into an internal table of Tag entries. It can be used for adding newly defined DICOM Tags (new to the specification) or for adding private user-defined Tags. Once a new entry is added the new Tag works just like all other Tags do.

NOTES: Set VM to a non-zero positive integer for a Tag which must contain a specific number of Items. Set VM to 0 for a Tag which can have an unlimited number of Items. Set VM to a negative integer for a Tag which can have a limited number of items up to the absolute value of the provided VM. For example, VM = -3 means that the Tag may have up to 3 items.

Bits Per Pixel: N/A

Return Value:

Returns TRUE if the new Tag was successfully added to the Data Dictionary; FALSE otherwise.


MED_DCM_util_tag_info_free

Group: DICOM Utility

Declaration:

BOOL ACCUAPI MED_DCM_util_tag_info_free(VOID);

Arguments:

None.

Description:

This function frees up the user-defined Data Dictionary, if it exists. All User-Defined entries are discarded. The pre-defined Data Dictionary is not affected. This function returns TRUE if a table was freed. FALSE if there was no table to free.

Bits Per Pixel: N/A

Return Value:

TRUE if a table was freed; FALSE if there was no table to free.


MED_DCM_util_tag_info_get

Group: DICOM Utility

Declaration:

BOOL ACCUAPI MED_DCM_util_tag_info_get(const AT_DCM_TAG Tag,
    LPAT_DCM_VR lpVR,
    LPAT_DCM_VM lpVM,
    LPWORD      lpwVersion,
    LPCHAR      lpszTagName);

Arguments:

Tag
Set to a Tag value. The Tag must be supplied as a 32-bit value in which the first 16 bits (WORD) represent the Group Number and the second 16 bits represent the Element Number. (See DCM.h).
lpVR
A far pointer which returns the current VR (Value Representation). Set to NULL if you don't need this information. AT_DCM_VR is a structure defined in DCM.h.
lpVM
A far pointer which returns the VM (Value Multiplicity ) of the current Tag; set to NULL if you don't need this information. Value Multiplicity tells you whether and/or how many items can be stored in this type of Data Element. See Note below.
lpwVersion
Returns the version of DICOM Specification, such as 3.0
lpszTagName
Returns the name of the specified Tag.

Description:

This function returns information about the specified Tag. It returns the Value Representation, Value Multiplicity, DICOM version, and the Tag name. The function searches in the user-defined Data Dictionary first, and then if the Tag is not found, searches in the static Data Dictionary, which represents the Data Dictionary listed in Part 6 of the DICOM standard.

You might use this function before making a call that alters a Data Element.

NOTES: If lpVM returns a Positive integer: there must be this number of Items. If it returns a 0: you may have an unlimited number of items, including 0. If it returns a Negative integer: The number of items may include up to the absolute value of the value returned. For example, if lpVM = -3, you may have up to 3 items.

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_util_VR_info_mode

Group: DICOM Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_util_VR_info_mode(const AT_DCM_VR
vr_mode,
    LPCHAR lpVRstring,
    LPWORD lpwLength,
    LPWORD lpwRestriction,
    LPBOOL lpCheck_form,
    LPBOOL lpIsString);

Arguments:

vr_mode
Set this to the type of VR (or data type) you would like information on. Use one of the MED_DCM_VR_ constants defined in DCM.h
lpVRstring
A far pointer that returns the text representation of VR in 3 characters
lpwLength
A far pointer that returns the size of the VR
lpwRestriction
A far pointer that returns any restriction flags These will be returned as constants that are defined in DCM.h and begin with MED_DCM_LEN_. See below.
lpReserved
This argument has not been implemented yet. Please set to NULL for now.
lpIsString
A far pointer to a BOOL value that tells you whether the data of this type of VR is a NULL-terminated string or not. If TRUE, data of this type is a NULL-terminated string and could be printed using the printf format %s. If FALSE, the data is an integer or other binary data type.

Description:

This function looks up the Value Representation specified in vr_mode and returns the following information about it: its text representation, length, restrictions, and whether or not it can be a NULL-terminated string.

These are the possible restriction flags that can be returned to you:

  • MED_DCM_LEN_MAX - Up to this maximum
  • MED_DCM_LEN_FIXED - Fixed Length
  • MED_DCM_LEN_TS - Depends on Transfer Syntax
  • MED_DCM_LEN_NA - Not applicable
  • MED_DCM_LEN_UNLIMITED - No max length

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_DCM_util_VR_info_string

Group: DICOM Utility

Declaration:

AT_ERRCOUNT ACCUAPI MED_DCM_util_VR_info_string(const LPCHAR
lpVR_string,
    LPWORD lpwLength,
    LPWORD lpwRestriction,
    LPBOOL lpCheck_form,
    LPBOOL lpIsString,
    LPAT_DCM_VR lpVr);

Arguments:

lpVRstring
Set to the 3-character text representation of the VR as used in the DICOM Specification, e.g. "PN", "CS", or "SQ." While these are 2-character codes, the end of line string termination makes it 3.
lpwLength
A far pointer that returns the size of the VR. This is the length in byes of a single instance of data that is of the specified type. For example, a VR of "SL" has a fixed length of 4 bytes per item. If the VM allows more than a single data value, then each one will take up 4 bytes. Other VRs have a maximum length. "PN" and "UI" both have a maximum of 64 bytes.
lpwRestriction
A far pointer that returns any restriction flags . These will be returned as constants that are defined in DCM.h and begin with MED_DCM_LEN_. See below.
lpReserved
This argument has not been implemented yet. Please set to NULL for now.
lpIsString
A far pointer to a BOOL value that tells you whether the data of this type of VR is a NULL-terminated string or not. If TRUE, data of this type is a NULL-terminated string and could be printed using the printf format %s. If FALSE, the data is an integer or other binary data type.
lpVR
A far pointer that returns an AT_MODE constant that identifies the type of Value Representation. Such constants begin with MED_DCM_VR_.

Description:

This function returns the type of Value Representation used. You supply it with a 3-character string (two alphabetic characters plus the end-of-string terminator), and it will return you one of the MED_DCM_VR_ constants defined in DCM.h.

These are the possible restriction flags that can be returned to you:

  • MED_DCM_LEN_MAX - Up to this maximum
  • MED_DCM_LEN_FIXED - Fixed Length
  • MED_DCM_LEN_TS - Depends on Transfer Syntax
  • MED_DCM_LEN_NA - Not applicable
  • MED_DCM_LEN_UNLIMITED - No max length

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_display_color_create

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI MED_display_color_create(const AT_MODE
scheme,
    const LONG param1,
    const LONG param2,
    const LONG param3,
    LPAT_PIXEL lpRLUT,
    LPAT_PIXEL lpGLUT,
    LPAT_PIXEL lpBLUT);

Arguments:

scheme
Set to the pre-defined color scheme that you would like to use to pseudocolor an image. These AT_MODE color schemes are defined in MedAPI.h and begin with DCM_PSEUDOCOLOR_SCHEME_ . See below for details.
param1
Set to a LONG value if the color scheme requires it. See below.
param2
Set to a LONG value if the color scheme requires it. See below.
param3
Set to a LONG value if the color scheme requires it. See below.
lpRLUT
Pass this argument an array of 256 bytes. It returns the Red LUT that will be used to pseudocolor an image when MED_display_color_set() is called.
lpGLUT
Pass this argument an array of 256 bytes. It returns the Green LUT that will be used to pseudocolor an image when MED_display_color_set() is called.
lpBLUT
Pass this argument an array of 256 bytes. It returns the Blue LUT that will be used to pseudocolor an image when MED_display_color_set() is called.

Description:

This function is used to fill 3 LUTs with one of several pseudocolor schemes. The scheme parameter selects which ImageGear pre-defined pseudocolor method to use. Some of the schemes may require parameters that are passed into param1, param2, and param3. Other schemes do not use these parameters and any value passed in are ignored. See below.

lpRLUT, lpGLUT, and lpBLUT must be passed an array of 256 bytes, each. When this function returns, these 3 tables will be filled with values that can be used to pseudocolor an 8-16 bit grayscale image.

This function does not apply the color to an image. It only fills these 3 LUTs. To apply these tables to an image you need to follow this function call with a call to MED_display_color_set().

As of this writing, these are the available preset ImageGear pseudocolor schemes:

DCM_PSEUDOCOLOR_SCHEME_OFF
Reset to grayscale - does not use param1, param2, param3
DCM_PSEUDOCOLOR_SCHEME_1
Oil Film - does not use param1, param2, param3
DCM_PSEUDOCOLOR_SCHEME_2
Dark Blue to Bright Red - does not use param1, param2, param3
DCM_PSEUDOCOLOR_SCHEME_3
Green to Red - does not use param1, param2, param3
DCM_PSEUDOCOLOR_SCHEME_4
Red, Green, Blue - does not use param1, param2, param3
DCM_PSEUDOCOLOR_SCHEME_5
Thermal - does not use param1, param2, param3
DCM_PSEUDOCOLOR_SCHEME_6
Bright Rainbow - does not use Param 1,2,3

Bits Per Pixel: 8-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR		hIGear;
{
AT_PIXEL	 	RLUT[256];
AT_PIXEL		 GLUT[256];
AT_PIXEL		 BLUT[256];
MED_display_color_create(DCM_PSEUDOCOLOR_SCHEME_6, 0, 0, 0,
RLUT, GLUT, BLUT);
MED_display_color_set(hIGear, RLUT, GLUT, BLUT);
repaint_image_and_error_check(hWnd);
}


MED_display_color_limits

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI MED_display_color_limits(HIGEAR hIGear,
    const INT thresh_low,
    const INT low_red,
    const INT low_green,
    INT       low_blue,
    const INT thresh_high,
    const INT high_red,
    const INT high_green,
    const INT high_blue);

Arguments:

hIGear
HIGEAR handle to the image
thresh_low
Set to an INT value for the lower pixel value limit. All pixels at or below this value will be pseudocolored.
low_red
8-16 Set to an INT for the red component of the RGB color that will be used for all pixels below thresh_low
low_green
Set to an INT for the green component of the RGB color that will be used for all pixels below thresh_low
low_blue
Set to an INT for the blue component of the RGB color that will be used for all pixels below thresh_low
thresh_high
Set to an INT value for the upper pixel value limit. All pixels at or above this value will be pseudocolored.
high_red
Set to an INT for the red component of the RGB color that will be used for all pixels above thresh_high
high_green
Set to an INT for the green component of the RGB color that will be used for all pixels above thresh_high
high_blue
Set to an INT for the blue component of the RGB color that will be used for all pixels above thresh_high

Description:

This function can be used to pseudocolor the brightest and the darkest pixels in a 16-bit grayscale image. This is typically used to clearly see pixel values that are over-saturated (255 and up) or under-saturated (0 and below). However, this function lets you customize the settings for the upper and lower pixel value limits with thresh_low and thresh_high.

The color is applied after the 16x8 display LUT is applied to the image and is not affected by altering this LUT.

Pixels having values at or below thresh_low are colored by low_color and pixels having values at or above thresh_high are colored by high_color. All pixels having values within the 2 limits are set to normal linear gray.

To turn off this effect, set thresh_low to -1 and thresh_high to 256.

This function does not cause the image to be displayed or repainted. It only fills the 16x8 LUT. To display the results of this function, use IG_display_image().

Bits Per Pixel: 9-16

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_display_color_set

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI MED_display_color_set(HIGEAR hIGear,
    const LPAT_PIXEL lpRLUT,
    const LPAT_PIXEL lpGLUT,
    const LPAT_PIXEL lpBLUT);

Arguments:

hIGear
HIGEAR handle of the 8-16-bit grayscale image to color
lpRLUT
Set to a 256 byte Red table or set to NULL for ramp
lpGLUT
Set to a 256 byte Green table or set to NULL for ramp
lpBLUT
Set to a 256 byte Blue table or set to NULL for ramp

Description:

This function allows applications to apply pseudocolor to 8-16-bit grayscale images. The 3 LUTs can be user-defined or they can be filled by calling MED_display_color_create(). Each LUT must either be 256 bytes each or set to NULL. If a NULL is passed in as one of the LUTs, a linear 0-255 grayscale LUT is used. If a NULL is not passed in, the LUT points to an array of 256 bytes. The entries from this LUT are used to color the output of the 16x8 LUT.

The pseudocoloring is not altered by any functions that update the 16x8 LUT. This function alters the display of a grayscale image only and does not change the pixel values of the image or any entries in the 16x8 LUT.

To turn off the pseudocolor, simply pass in NULLs for all of the LUT parameters. These three color channels will be reset to their default linear ramps.

This function does not cause the image to be displayed or repainted. It only fills the 16x8 LUT. To display the results of this function, use IG_display_image().

Bits Per Pixel: 8-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

AT_ERRCOUNT nErrcount;
HIGEAR		hIGear;
{
AT_PIXEL 		RLUT[256];
AT_PIXEL 		GLUT[256];
AT_PIXEL 		BLUT[256];
MED_display_color_create(DCM_PSEUDOCOLOR_SCHEME_6, 0, 0, 0,
RLUT, GLUT, BLUT);
MED_display_color_set(hIGear, RLUT, GLUT, BLUT);
repaint_image_and_error_check(hWnd);
}


MED_display_contrast

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI MED_display_contrast(HIGEAR hIGear,
    const DOUBLE rescale_slope,
    const DOUBLE rescale_intercept,
    const LONG window_center,
    const LONG window_width,
    const DOUBLE gamma);

Arguments:

hIGear
16g image having its 16x8 LUT updated
rescale_slope
Set to the desired value for Rescale Slope (0028,1053). Call MED_DCM_DS_Rescale_get() to obtain this value.
rescale_intercept
Set to the desired value for Rescale Intercept (0028,1054). Call MED_DCM_DS_Rescale_get() to obtain this value.
window_center
Set to the desired value for Window Center (0028,1050). Call MED_DCM_DS_Window_Level_get() to obtain this value.
window_width
Set to the desired value for Window Width (0028,1051). Call MED_DCM_DS_Window_Level_get() to obtain this value.
gamma
Set this to the amount of Gamma correction you would like applied to the image. To turn off Gamma correction, set to 1.0. The valid range of values is any DOUBLE between 0.20-1.80.

Description:

This function uses the window/level mapping method to change the contrast of an 9-16-bit image. It takes values for Window Center & Width, and Rescale Slope & Intercept, and it also allows you to apply Gamma correction, if you desire.

This function fills the 16x8 LUT with values that will display a 9-16 bit image according to VOI LUT (Window Center/Width) and Modality LUT (Rescale Intercept/Slope) values that you specify. Any values that have been in the 16x8 LUT are overwritten with these new ones.

If the Rescale Slope and Intercept of the image are known, you should provide them. If they are not known, pass in a 1.0 and 0.0, respectively.

If you do not have values for Window Center and Window Width, these can be calculated using the minimum and maximum pixel values (if you have them known). Here are the formulas you should use to display all pixel values:

Window Center = (max + min) / 2;

Window Width = (max - min);

This function does not cause the image to be displayed or repainted. It only fills the 16x8 LUT. To display the results of this function, use IG_display_image().

See also MED_display_contrast_auto()

Bits Per Pixel: 9-16

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_display_contrast_auto

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI MED_display_contrast_auto(const HIGEAR
hIGear,
    const LPAT_RECT lpRect,
    const DOUBLE     rescale_slope,
    const DOUBLE     rescale_intercept,
    const LONG       lReserved_option,
    LPLONG           lpWindow_center,
    LPLONG           lpWindow_width);

Arguments:

hIGear
The HIGEAR handle to the image to convert
lpRect
Use this AT_RECT structure to specify the rectangular portion of the image for which to optimize the contrast on; set to NULL for the whole image. Please see the ImageGear User's Manual if you are unfamiliar with this structure.
rescale_slope
Set to the value of the Data Element, Rescale Slope (0028,1053). You can use MED_DCM_DS_Rescale_get() to obtain this value. If this Data Element is not present in the Data Set, please set this value to 1.0.
rescale_intercept
Set to the value of the Data Element, Rescale Intercept (0028,1054). You can use MED_DCM_DS_Rescale_get() to obtain this value. If this Data Element is not present in the Data Set, please set this value to 0.0.
lReserved_option
Reserved for future use; please set to 0 for now
lpWindow_center
A far pointer that returns a LONG for the Window Center ; set to NULL if you don't need this information.
lpWindow_width
A far pointer that returns a LONG for the Window Width ; set to NULL if you don't need this information.
lpSigned
A far pointer that returns a BOOL value indicating whether the value is signed or not.

Description:

This function automatically fills the 16x8 LUT of a 16-bit image loaded into ImageGear in order to optimize its displaying. The rectangular portion of the image that you specify (or the whole image) is scanned and the maximum and minimum pixel values are determined; the Window Center and Width are calculated from these.

If the Rescale Slope and Intercept of the image are known, you should provide them. If they are not known, pass in a 1.0 and 0.0, respectively.

The Window Center and Width that this function computes are passed back to you in lpWindow_center and lpWindow_width, unless you set these arguments to NULL.

This function does not cause the image to be displayed or repainted. It only fills the 16x8 LUT. To display the results of this function, use IG_display_image().

See also MED_display_contrast().

NOTES: Since this function must scan the pixels for the minimum and maximum values, it takes more time to run than IG_display_contrast() .

Bits Per Pixel: 9-16

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HIGEAR hIGear;
DOUBLE		fRescaleSlope = 1.0;
DOUBLE		fRescaleIntercept = 1.0;
DOUBLE		fGama = 1.0;
LONG		WindowWidth;
LONG		WindowCenter;
MED_display_contrast_auto(hIGear, NULL, fRescaleSlope,
            fRescaleIntercept, fGamma, 0, &WindowCenter,
                                                    &WindowWidth);


MED_display_grayscale_LUT_build

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI MED_display_grayscale_LUT_build(
    AT_MED_DCM_DISPLAY_SETTINGS *lpDICOMDisplaySettings,
    HIGLUT hLUT
    );

Arguments:

lpDICOMDisplaySettings
AT_MED_DCM_DISPLAY_SETTINGS structure.
hLUT
LUT handle.

Description:

This function builds a grayscale LUT according to lpDICOMDisplaySettings.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_display_grayscale_LUT_build_auto

Group: Display

Declaration:

AT_ERRCOUNT ACCUAPI MED_display_grayscale_LUT_build_auto(
    HIGEAR hIGear,
    const AT_RECT *lpRect,
    AT_MED_DCM_DISPLAY_SETTINGS *lpDICOMDisplaySettings,
    HIGLUT hlut
    );

Arguments:

hIGear
16g image having its 16x8 LUT updated
lpRect
AT_RECT structure.
lpDICOMDisplaySettings
AT_MED_DCM_DISPLAY_SETTINGS structure.
hlut
LUT handle.

Description:

This function calculates lpDICOMDisplaySettings->VOIWindow from image's min and max values, and then builds grayscale LUT according to lpDICOMDisplaySettings.

Bits Per Pixel: 8...16-bit

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_IP_contrast

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI MED_IP_contrast(HIGEAR hIGear,
    const DOUBLE rescale_slope,
    const DOUBLE rescale_intercept,
    const LONG   window_center,
    const LONG   window_width,
    const DOUBLE gamma);
NOTES: The functionality of MED_IP_window_level() has been incorporated into the new function MED_IP_contrast(), which also takes settings for Rescale Slope, Rescale Intercept, and gamma correction

Arguments:

hIGear
16g image that will have its 16x8 LUT updated
rescale_slope
Set to the desired value for Rescale Slope (0028,1053). Call MED_DCM_DS_Rescale_get() to obtain this value.
rescale_intercept
Set to the desired value for Rescale Intercept (0028,1054). Call MED_DCM_DS_Rescale_get() to obtain this value.
window_center
Set to the desired value for Window Center (0028,1050). Call MED_DCM_DS_Window_Level_get() to obtain this value.
window_width
Set to the desired value for Window Width (0028,1051). Call MED_DCM_DS_Window_Level_get() to obtain this value.
gamma
Set this to the amount of Gamma correction you would like applied to the image. To turn off Gamma correction, set to 1.0. The valid range of values is any DOUBLE between 0.20-1.80.

Description:

This function converts a 16-bit grayscale image to an 8-bit grayscale image in the same way as MED_display_contrast(). The difference is that this function permanently alters the pixel values.

See also MED_display_contrast()

Bits Per Pixel: 9-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_IP_contrast_auto

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI MED_IP_contrast_auto(const HIGEAR hIGear,
    const LPAT_RECT lpRect,
    const DOUBLE    rescale_slope,
    const DOUBLE    rescale_intercept,
    const LONG      lReserved_option,
    LPLONG          lpWindow_center,
    LPLONG          lpWindow_width);

Arguments:

hIGear
The HIGEAR handle to the image to convert
lpRect
Use this AT_RECT structure to specify the rectangular portion of the image for which to optimize the contrast on; set to NULL for the whole image. Please see the ImageGear User's Manual if you are unfamiliar with this structure.
rescale_slope
Set to the value of the Data Element, Rescale Slope (0028,1053). You can use MED_DCM_DS_rescale_get() to obtain this value. If this Data Element is not present in the Data Set, please set this value to 1.0.
rescale_intercept
Set to the value of the Data Element, Rescale Intercept (0028,1054). You can use MED_DCM_DS_rescale_get() to obtain this value. If this Data Element is not present in the Data Set, please set this value to 0.0.
lReserved_option
Reserved for future use; please set to 0 for now
lpWindow_center
A far pointer that returns a LONG for the Window Center ; set to NULL if you don't need this information.
lpWindow_width
A far pointer that returns a LONG for the Window Width ; set to NULL if you don't need this information.
lpSigned
A far pointer that returns a BOOL value indicating whether the value is signed or not.

Description:

This function converts a 16-bit grayscale image to an 8-bit grayscale image using the same function as MED_display_contrast_auto() except that this function permanently alters the pixel values.

See also MED_display_contrast_auto(), and MED_IP_reduce_depth_with_downshift().

Bits Per Pixel: 9-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_IP_high_bit_transform

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI MED_IP_high_bit_transform(HIGEAR hIGear,
    const LONG lMin);

Arguments:

hIGear
HIGEAR handle of the image
lMin
New High bit value

Description:

This function changes the High Bit Data Element of the currently loaded DICOM 16-bit grayscale image. The 16-bits are shifted up or down as needed to accommodate the new High Bit value, and the High Bit Data Element is updated. Zeros are shifted in as needed.

Bits Per Pixel: 9-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_IP_histo_clear

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI MED_IP_histo_clear(LPLONG lpHisto,
    const DWORD nBin_count,);

Arguments:

lpHisto
A far pointer of type LONG which points to the buffer that will was used to hold the histogram
nBin_count
Set this DWORD variable to the number of bins allocated for the histogram

Description:

This function is used to clear the histogram created by MED_IP_histo_tabulate().

Bits Per Pixel: N/A

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_IP_histo_tabulate

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI MED_IP_histo_tabulate(const HIGEAR hIGear,
    const LPAT_RECT			 lpRect,
    LPLONG			lpHisto,
    const WORD			 nBin_width,
    const DWORD			 dwBin_count,
    LPBOOL			lpSigned,
    LPLONG			lpCount);

Arguments:

hIGear
The HIGEAR handle to the image to create a histogram for
lpRect
A far pointer to a struct of type AT_RECT that defines the rectangular portion of the image to use for creating a histogram. Please see the ImageGear User's Manual if you are unfamiliar with this structure.
lpHisto
A far pointer to a buffer to be used for holding the histogram
nBin_width
An integer variable that specifies the range of pixel values to be counted into one bin
dwBin_count
A DWORD variable that specifies the number of bins allocated
lpSigned
A far pointer to a BOOL that returns the sign status of the image. If it returns TRUE, the image is signed.
lpCount
A far pointer to a LONG which returns the number of pixels counted.

Description:

This function is used to tabulate the histogram of a 8 or 16-bit grayscale image. The histogram is returned in the memory block, lpHisto, allocated by the application. This memory block must be large enough to hold the histogram for the image. Each histogram bin must be 4 bytes wide. The size of lpHisto needed (in bytes) can be computed as follows:

size = ((possible_pixel_values) * 4) / nBin_width

where possible_pixel_values depends on the bit depth of the image (8g=256, 9g=512,...). nBin_width is used to determine the range of pixel values that are counted in their own bin. A value of 1 indicates that each pixel value is counted in its own histogram bin. A value of 2 would allow neighboring values (such as 128 and 129) to be counted as a single bin (as a single value). If nBin_width==possible_pixel_values then only a single histogram bin (4 bytes) is filled and the count will be equal to the number of pixel values in the lpRect.

nBin_count is used as a safety. This should be set to the number of bins in the histogram that your application has allocated. If a pixel value is going to overflow this memory it will be ignored. This pixel value will not be included in the sum returned in lpCount (you can use this to determine if any values were ignored).

Bits Per Pixel: 8-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_IP_min_max

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI MED_IP_min_max(const HIGEAR hIGear,
    const LPAT_RECT			lpRect,
    LPLONG			lpMin,
    LPLONG			lpMax,
    LPBOOL			lpSigned);

Arguments:

hIGear
The HIGEAR handle of the image to scan
lpRect
Use this AT_RECT structure to specify the rectangular portion of the image to scan. Please see the ImageGear User's Manual if you are unfamiliar with this structure.
lpMin
A far pointer to a LONG which returns the value of the minimum pixel value in the region that was "scanned"
lpMax
A far pointer to a LONG which returns the value of the maximum pixel value in the region that was "scanned"
lpSigned
A far pointer to a BOOL which returns the status of the image sign. TRUE means the image is signed.

Description:

This function scans an 8- or 16-bit grayscale image and returns the raw minimum and maximum pixel values and the "is signed" flag. If the image is 16-bit signed then the returned values are also signed.

Note that this function returns the min and max raw pixel values. That is, the returned values are not corrected using the Modality LUT (Rescale Slope/Intercept) values. To apply this correction to the min and max values that you get from MED_IP_min_max() call the function MED_DCM_DS_Rescale_get() which will return you the values of Rescale Slope and Rescale Intercept. Then use the following formulas:

min_corrected = (min_raw * rescale_slope) + rescale_intercept;

max_corrected = (max_raw * rescale_slope) + rescale_intercept;

When a 16-bit grayscale image is "unsigned" it has pixel values between 0 and 65,000. If a 16-bit image is "signed" it has pixel values between -32k and +32k. By the same rule, when an 8-bit grayscale image is "unsigned" it has pixel values between 0-255. If an 8-bit image is "signed", it has pixel values between -128 and +127. Some modalities of DICOM use signed images. So if you know whether the image is signed or unsigned will help you to interpret the minimum and maximum values.

Bits Per Pixel: 8-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example

HIGEAR hIGear;
AT_ERRCOUNT nErrcount;
AT_RECT rcROI;
LONG lMin, lMax;
BOOL bSigned;
nErrcount = MED_IP_min_max(hIGear, &rcROI, &lMin, &lMax,
&bSigned);


MED_IP_normalize

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI MED_IP_normalize(HIGEAR hIGear,
    const LONG lMin);

Arguments:

hIGear
The HIGEAR handle to the image to normalize
lMin
A variable of type LONG used to set the minimum pixel value for the resulting image

Description:

This function's main purpose is to convert the pixel data of a 16-bit image from signed to unsigned. If you are using it for this reason, set lMin to 0.

It can also be used to convert the minimum pixel value for the image. To do this, set lMin to greater than 0. This function searches the image for the minimum pixel value. It maps this value to lMin. Then, all pixel values are linearly adjusted to maintain the original contrast. If lMin is equal to the min pixel value in hIGear then no change is made. The resulting image remains a 16-bit.

Bits Per Pixel: Input image: 8-16g; Output image: 8-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_IP_promote_to_16_gray

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI MED_IP_promote_to_16_gray(HIGEAR hIGear,
    const UINT iBits,
    const UINT iHighBit);

Arguments:

hIGear
The HIGEAR handle of the image to be converted
iBits
An integer variable that sets the number of bits that are actually used. The value range is 9 - 16 bits.
iHighBit
An integer variable that sets the high bit for the new 16-bit image. The eighth bit of the original 8 bits is positioned here. If the image is saved as a DICOM, this information is saved to the High Bit Data Element (0028,0102).

Description:

This function takes an 8-bit grayscale or color image and converts it to a grayscale image with a bit depth of 16 bpp. The original 8-bit image is discarded. All images created by this function have 16-bit pixels, iBits sets the number of bits out of the 16 that are actually used. iHighBit sets the new position among the 16 bits at which the original 8 bits should be positioned.

Bits Per Pixel: Input: 8g; Output: 9-16

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_IP_reduce_depth_with_downshift

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI MED_IP_reduce_depth_with_downshift (HIGEAR
hIGear,
    const UINT downshift);

Arguments:

hIGear
HIGEAR handle to the image
downshift
A UINT variable specifying the

Description:

This function is used to downshift a chosen range of 8 bits (out of a maximum of 16) to the 256 pixel values that can be shown on an 8-bit display device. For example, if you set iBits to 8, and the image has 16 bpp, bits 8-15 will be downshifted and used alone as the pixel values.

This function will directly alter the pixel data.

See also MED_IP_reduce_depth_with_LUT().

Bits Per Pixel: 9-16 input; 8g output

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_IP_reduce_depth_with_LUT

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI MED_IP_reduce_depth_with_LUT(HIGEAR hIGear,
    const LPBYTE lpLUT,
    const DWORD dwEntries);

Arguments:

hIGear
The HIGEAR handle to the image to convert
lpLUT
A far pointer to the lookup table to use for reduction. Set to 0 to use the display LUT. Set to NULL if you want to use the display LUT.
dwEntries
A variable of type DWORD that specifies the number of entries in the LUT. This value is ignored if the display LUT is used.

Description:

This function takes a 16-bit grayscale image and reduces it to a 8-bit grayscale one using provided (filled) LUT or current 16x8 display LUT. The 16-bit image is discarded and replaced with the new 8-bit grayscale image.

To reduce memory requirements the LUT does not have to have a 16-bit input. dwEntries should hold the number of entries in the LUT. If there is a pixel found that can overflow the LUT it is ignored and replaced with a 0.

NOTES: This function does not reduce 8-bit images. To reduce an 8-bit image, use the appropriate IG_IP_color_reduce_...() function from the baseline ImageGear API.
NOTES: Once this function is called, the display LUT will be thrown away, since it is now an 8-bit image.

See also MED_IP_reduce_depth_with_downshift().

Bits Per Pixel: 9-16 g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_IP_swap_bytes

Group: Image Processing

Declaration:

AT_ERRCOUNT ACCUAPI MED_IP_swap_bytes(HIGEAR hIGear);

Arguments:

hIGear
HIGEAR handle of the image

Description:

This function swaps the 2 bytes of each 16-bit pixel in the image. It can be used to help fix poorly constructed images which have the high and low bytes of each 16-bit grayscale pixel reversed. All pixels in the image are transformed.

Bits Per Pixel: 9-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_modality_transform_apply

Group: Modality

Declaration:

AT_INT MED_modality_transform_apply(
    const AT_MED_MODALITY_RESCALE *lpRescale,
    HIGLUT hModalityLUT,
    AT_INT Value
    );

Arguments:

lpRescale
AT_MED_MODALITY_RESCALE structure
hModalityLUT
Modality LUT handle.
Value
Value to apply Modality transform to.

Description:

If hModalityLUT is not NULL, applies Modality LUT to the specified value. Otherwise, applies the linear modality transform (lpRescale) to the specified value.

Bits Per Pixel: 9-16g

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_overlay_apply

Group: Overlay

Declaration:

AT_ERRCOUNT ACCUAPI MED_overlay_apply(HIGEAR hIGear);

Arguments:

hIGear
Page from which to load overlay planes into ART marks

Description:

Loads overlay planes from DICOM metadata (DataSet) attached to the image and creates ART marks of type IMAGE_EMBEDDED for each overlay plane. Each mark is placed in a separate ART group.

Overlay planes do not support specifying the colors (even black or white). An overlay pixel can only be visible or invisible. All visible overlay pixels are displayed with the same color, which is specified by the application and not stored in the DICOM DataSet. By default, ImageGear uses yellow color to display overlays. The application can change overlay color by going through all marks in the HIGEAR and changing the image palette of IMAGE_EMBEDDED marks.

This function requires the ART component to be attached to ImageGear.

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

See Also:

ARTX Component API Function Reference


MED_overlay_extract

Group: Overlay

Declaration:

AT_ERRCOUNT ACCUAPI MED_overlay_extract(HIGEAR hIGear);

Parameters:

hIGear
Page for which to save annotations into DataSet as overlay planes.

Description:

Saves ART marks into DICOM dataset as overlay planes. Each ART group is saved into a separate overlay plane.

Since overlay planes do not support any types of graphic objects other than bitonal bitmaps, all ART marks from a group are converted into a bitmap before saving into an overlay.

Overlay planes do not support specifying the colors (even black or white). An overlay pixel can only be visible or invisible. All visible overlay pixels are displayed with the same color, which is specified by the application and not stored in the DICOM DataSet.

This function requires the ART component to be attached to ImageGear.

See Also:

ARTX Component API Function Reference


MED_PS_apply

Group: Presentation State

Declaration:

AT_ERRCOUNT ACCUAPI MED_PS_apply (
HIGEAR hIGear,
HIGEAR hIGearPresState,
DWORD dwFeatureFlags,
DWORD dwGrpID,
LPAT_MED_LUT_DESC lpGSDFLUT
)

Arguments:

hIGear
Image to which Pres State shall be applied
hIGearPresState
Image containing Presentation State DataSet
dwFeatureFlags
Tells which features of PS to use - bit mask
dwGrpID
Display Group ID
lpGSDFLUT
GSDF LUT info

Description:

This function extracts PS data from DICOM DataSet of hIGearPresState, and adjusts display of hIGear based on this data. This function may result in the following:

  • Adjust Display LUT associated with the image, using
    • VOI and Modality LUTs found in the presentation state DataSet
    • Presentation LUT found in the presentation state DataSet
    • GSDF LUT parameter
  • Change display layout, including image rectangle, zoom and orientation
  • Add ART objects

If there are no VOI or Modality LUT in the hIGearPresState, the function tries to find them in the DataSet of hIGear. If there are no such LUTs in hIGear, default values are taken.

If MED_PS_FEATURE_PRES_LUT option is specified, the function assumes that MED_PS_FEATURE_CONTRAST is selected as well.

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_PS_display_contrast

Group: Presentation State

Declaration:

AT_ERRCOUNT ACCUAPI MED_PS_display_contrast (
HIGEAR hIGear, // 16g image to have its LUT16x8 updated
DOUBLE rescale_slope, // Rescale Slope (0028,1053)
DOUBLE rescale_intercept, //
LONG window_center, //
LONG window_width, //
DOUBLE gamma, //
LPAT_MED_LUT_DESC lpPresLUTInfo, //
LPAT_MED_LUT_DESC lpGSDFLUTInfo, //
)

Arguments:

hIGear
16g image to have its LUT16x8 updated
rescale_slope
Rescale Slope (0028,1053)
rescale_intercept
Rescale Intercept (0028,1054)
window_center
Window Center (0028,1050)
window_width
Window Width (0028,1051)
gamma
Gamma correction - set to 1.0 to turn off
lpPresLUTInfo
Presentation LUT info
lpGSDFLUTInfo
GSDF LUT info

Description:

Builds the 16x8 display LUT, using rescale, window, Presentaion LUT and GSDF LUT.

If lpGSDFLUTInfo parameter is not NULL, gamma is not used.

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_PS_display_contrast_auto

Group: Presentation State

Declaration:

AT_ERRCOUNT ACCUAPI MED_PS_display_contrast_auto (
HIGEAR hIGear,
LPAT_RECT lpRect,
DOUBLE rescale_slope,
DOUBLE rescale_intercept,
DOUBLE gamma,
LPAT_MED_LUT_DESC lpPresLUTInfo,
LPAT_MED_LUT_DESC lpGSDFLUTInfo,
LPLONG lpWindow_center,
LPLONG lpWindow_width
)

Arguments:

hIGear
16g image to have its LUT16x8 updated
lpRect
set to NULL to scan the entire image
rescale_slope
Rescale Slope (0028,1053)
rescale_intercept
Rescale Intercept (0028,1054)
gamma
Gamma correction - set to 1.0 to turn off
lpPresLUTInfo
Presentation LUT info
lpGSDFLUTInfo
GSDF LUT info
lpWindow_center
Window Center (0028,1050)
lpWindow_width
Window Width (0028,1051)

Description:

Builds the 16x8 display LUT, using rescale, Presentaion LUT and GSDF LUT. Window center and width are calculated automatically, based on min and max values of the image. If lpGSDFLUTInfo parameter is not NULL, gamma is not used.

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_PS_extract

Group: Presentation State

Declaration:

AT_ERRCOUNT ACCUAPI MED_PS_extract (
HIGEAR hIGear,
HIGEAR hIGearPresState,
DWORD dwFeatureFlags,
DWORD dwGrpID
)

Arguments:

hIGear
Image which settings should be exported to PS
hIGearPresState
Image that will contain Presentation State DataSet
dwFeatureFlags
Tells which features of PS to export - bit mask
dwGrpID
Display Group ID

Description:

This function adds Presentation State tags to the DataSet of hIGearPresState, based on the display settings of hIGear, an ART marks attached to it. If any of the tags are already present in the hIGearPresState, they are overwritten.

This function may add/update the following tags/sequences in the hIGearPresState:

  • DCM_TAG_DisplayedAreaSelectionSequence
  • DCM_TAG_GraphicAnnotationSequence
  • DCM_TAG_GraphicLayerSequence
  • DCM_TAG_ImageHorizontalFlip
  • DCM_TAG_ImageRotation

To create a new presentation state DataSet, use the following steps:

  1. Call IG_image_create_DIB_ex() with lCompression set to IG_BI_EMPTY
  2. Call MED_PS_extract() to add Presentation State tags
  3. Add the other tags required by the Presentation State module using general DataSet access functions.
  4. Save Presentation State to file using IG_fltr_save_file() or similar functions

To modify an existing Presentation State DataSet, use the following steps:

  1. Load a Presentation State DataSet using IG_fltr_load_file() or similar functions
  2. Apply the Presentation State to a DICOM image, using MED_PS_apply()
  3. Change display settings or ART marks
  4. Extract Presentation Data from DICOM image back to Presentation State DataSet.
  5. Save Presentation State to file using IG_fltr_save_file() or similar functions

Use MED_PS_pres_LUT_set() to add Presentation LUT to the Presentation State HIGEAR.

Use general DataSet functions to add VOI and Modality LUT to the Presentation State HIGEAR.

Use IG image saving functions (nFormat=IG_FORMAT_DCM) to save lphIGearPresState into a presentation state file (.pre).

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_PS_GSDF_LUT_build

Group: Presentation State

Declaration:

AT_ERRCOUNT ACCUAPI MED_PS_GSDF_LUT_build(
DWORD dwCharactCurveEntryCount,
LPDOUBLE lpCharactCurve,
LPAT_MED_LUT_DESC lpLUT
)

Arguments:

dwCharactCurveEntryCount
Number of entries in Charactistic Curve
lpCharactCurve
Characteristic Curve of the display
lpLUT
GSDF LUT to fill

Description:

This function builds a look up table that maps pixel intencities from DICOM GSDF-compliant color space into pixel intencities of the display device. The user should fill in the members of the lpLUT structure and allocate the lpLUTData buffer. The space necessary for holding the LUT can be calculated using the AM_MED_LUT_SIZE_GET macro.

The LUT obtained from this function can be used for building the 16x8 or 8x8 display LUT. See MED_PS_import(), MED_display_contrast_PS().

At the moment, ImageGear does not support any display devices that are capable of displaying more than 256 shades of grayscale. Hence, MED_PS_GSDF_LUT_build can only build a LUT consisting of 8-bit entries.

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_PS_GSDF_LUT_init

Group: Presentation State

Declaration:

AT_ERRCOUNT ACCUAPI MED_PS_GSDF_LUT_init(
DWORD     dwCharactCurveEntryCount,
LPDOUBLE  lpCharactCurve,
HIGLUT    lut
);

Arguments:

dwCharactCurveEntryCount
Number of entries in Charactistic Curve
lpCharactCurve
Characteristic Curve of the display
lut
GSDF LUT to fill.

Description:

This function initializes the HIGLUT object with GSDF LUT data.

This function replaces MED_PS_GSDF_LUT_build ().

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_PS_pres_LUT_get

Group: Presentation State

Declaration:

MED_PS_pres_LUT_get(
HIGEAR hIGearPresState,
LPAT_MED_LUT_DESC lpPresLUTInfo
);

Arguments:

hIGearPresState
Image that contains Presentation State DataSet
lpPresLUTInfo
Presentation LUT info

Description:

This function fills the Presentation LUT with the data contained in the Presentation State DataSet.

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_PS_pres_LUT_info_get

Group: Presentation State

Declaration:

MED_PS_pres_LUT_info_get(
HIGEAR hIGearPresState,
LPAT_MED_LUT_DESC lpPresLUTInfo
);

Arguments:

hIGearPresState
Image that contains Presentation State DataSet
lpPresLUTInfo
Presentation LUT info

Description:

This function returns information about Presentation LUT contained in a Presentation State DataSet.

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_PS_pres_LUT_set

Group: Presentation State

Declaration:

MED_PS_pres_LUT_set(
HIGEAR hIGearPresState,
LPAT_MED_LUT_DESC lpPresLUTInfo
);

Arguments:

hIGearPresState
Image that contains Presentation State DataSet
lpPresLUTInfo
Presentation LUT info

Description:

This function adds Presentation LUT sequence to the DataSet of hIGearPresState. Use this function together with MED_PS_extract().

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_PS_pres_state_GSDF_apply

Group: Presentation State

Declaration:

AT_ERRCOUNT ACCUAPI MED_PS_pres_state_GSDF_apply(
HIGEAR hIGear,
HIGEAR hIGearPresState,
DWORD dwFeatureFlags,
DWORD dwGrpID,
HIGLUT GSDFLUT
);

Arguments:

hIGear
Image to which Pres State shall be applied.
hIGearPresState
Image containing Presentation State DataSet.
dwFeatureFlags
Tells which features of PS to use - bit mask.
dwGrpID
Display Group ID.
GSDFLUT
GSDF LUT.

Description:

This function extracts PS data from DICOM DataSet of hIGearPresState, and adjusts display of hIGear based on this data. This function may result in the following:

  • Adjust Display LUT associated with the image, using
    • VOI and Modality LUTs found in the presentation state DataSet
    • Presentation LUT found in the presentation state DataSet
    • GSDF LUT parameter
  • Change display layout, including image rectangle, zoom and orientation
  • Add ART objects

If there are no VOI or Modality LUT in hIGearPresState, the function tries to find them in the DataSet of hIGear. If there are no such LUTs in hIGear, default values are taken.

If MED_PS_FEATURE_PRES_LUT option is specified, the function assumes that MED_PS_FEATURE_CONTRAST is selected.

This function replaces MED_PS_apply (). It provides the same functionality as MED_PS_apply (), but uses a more general type HIGLUT for GSDFLUT parameter.

Return Value:

Returns the number of ImageGear errors that occurred during the function call.


MED_VOI_window_init_from_min_max

Group: Window

Declaration:

AT_VOID MED_VOI_window_init_from_min_max(
    AT_MED_VOI_WINDOW *lpWindow,
    AT_INT Min,
    AT_INT Max
    );

Arguments:

lpWindow
Window structure.
Min
Window min.
Max
Window max.

Description:

This function initializes a AT_MED_VOI_WINDOW structure from window Min and Max.

Return Value:

None.


MED_VOI_window_max_get

Group: Window

Declaration:

AT_INT MED_VOI_window_max_get(
    AT_MED_VOI_WINDOW *lpWindow
    );

Arguments:

lpWindow
Window structure.

Description:

This function returns AT_MED_VOI_WINDOW maximum.

Return Value:

AT_MED_VOI_WINDOW maximum.


MED_VOI_window_min_get

Group: Window

Declaration:

AT_INT MED_VOI_window_min_get(
    AT_MED_VOI_WINDOW *lpWindow
    );

Arguments:

lpWindow
Window structure.

Description:

This function returns AT_MED_VOI_WINDOW minimum.

Return Value:

AT_MED_VOI_WINDOW minimum.


AT_MED_DCM_DISPLAY_SETTINGS

Group: Structure

Declaration:

struct AT_MED_DCM_DISPLAY_SETTINGS
{
    AT_MED_MODALITY_RESCALE ModalityRescale;
    HIGLUT ModalityLUT;
    AT_MED_VOI_WINDOW VOIWindow;
    HIGLUT VOILUT;
    AT_BOOL IsInverted;
    AT_DOUBLE Gamma;
    HIGLUT PresentationLUT;
    HIGLUT GSDFLUT;
    AT_MED_PIXEL_PADDING_SETTINGS PixelPadding;
};
typedef struct AT_MED_DCM_DISPLAY_SETTINGS;

Arguments:

ModalityRescale
Specifies linear Modality transform (Rescale Slope/Intercept). Ignored if ModalityLUT is not NULL.
ModalityLUT
Specifies Modality LUT.
VOIWindow
Specifies linear VOI transform (Window center/width). Ignored if VOI LUT is not NULL.
VOILUT
Specifies VOI LUT.
IsInverted
Tells whether the image should be displayed inverted. TRUE Corresponds to MONOCHROME1 photometric interpretation, FALSE coresponds to MONOCHROME2 photometric interpretation.
Gamma
Specifies gamma correction value. Ignored if GSDFLUT is not NULL.
PresentationLUT
Specifies Presentation LUT.
GSDFLUT
Specifies Grayscale Standard Display Function LUT.
PixelPadding
Specifies pixel padding settings.

Description:

This structure contains settings that can be used for displaying DICOM images with proper contrast. The settings are applied in the following order: Modality (LUT or Rescale), VOI (LUT or Window), IsInverted flag, Presentation LUT, Gamma or GSDFLUT.


AT_MED_MODALITY_RESCALE

Group: Structure

Declaration:

struct AT_MED_MODALITY_RESCALE
{
    AT_DOUBLE Slope;
    AT_DOUBLE Intercept;
};
typedef struct AT_MED_MODALITY_RESCALE;

Arguments:

Slope
Rescale slope
Intercept
Rescale Intercept

Description:

This structure specifies linear Modality transform.


AT_MED_PIXEL_PADDING_SETTINGS

Group: Structure

Declaration:

struct AT_MED_PIXEL_PADDING_SETTINGS
{
    AT_BOOL UsePixPadding;
    AT_INT PixPaddingValue;
    AT_INT ShowPaddingAs;
};

Arguments:

UsePixPadding
Specifies whether pixel padding should be taken into account during display.
PixPaddingValue
Specifies pixel padding value.
ShowPaddingAs
Specifies the output intensity for displaying padding pixels.

Description:

This structure represents DICOM pixel padding settings.


AT_MED_VOI_WINDOW

Group: Structure

Declaration:

struct AT_MED_VOI_WINDOW
{
    AT_INT Center;
    AT_INT Width;
};
typedef struct AT_MED_VOI_WINDOW;

Arguments:

Center
Window center
Width
Window width

Description:

This structure specifies linear VOI transform.


enumIGMedTS

Group: Enumeration

Description:

Identifies DICOM Transfer Syntaxes.

Values:

The table below lists the most frequently used DICOM Transfer syntaxes:

MED_DCM_TS_IMPLICIT_VR_LE
Implicit VR Little Endian: Default Transfer Syntax
MED_DCM_TS_EXPLICIT_VR_LE
Explicit VR Little Endian
MED_DCM_TS_EXPLICIT_VR_BE
Explicit VR Big Endian
MED_DCM_TS_JPEG_LOSSY
JPEG baseline Transfer Syntax (process 01)
MED_DCM_TS_JPEG_LOSSLESS
JPEG lossless non-hierachical Huffman transfer Syntax (process 14)
MED_DCM_TS_JPEG_LOSSLESS_FIRSTORDER
JPEG Lossless, Hierarchical, First-Order Prediction
MED_DCM_TS_JPEG_2K_LOSSLESS_ONLY
JPEG 2000 Lossless Only
MED_DCM_TS_JPEG_2K
JPEG 2000
MED_DCM_TS_RLE
RLE

The following constants are not defined by the DICOM standard, but are introduced by the IG Medical Component:

MED_DCM_TS_DEFAULT
Default transfer syntax: same as MED_DCM_TS_EXPLICIT_VR_LE
MED_DCM_TS_UNKNOWN
Unknown Transfer Syntax
MED_DCM_TS_PART_10
This constant can be passed to the LOAD_SYNTAX image control parameter to load only those DICOM files that have a File Meta Information (Part 10) Header.
MED_DCM_TS_AUTODETECT
This constant can be passed to the LOAD_SYNTAX image control parameter to load any detectible DICOM files.


PDF Component API Function Reference

The ImageGear PDF component is responsible for the PDF functionality. The ImageGear PDF component exposes handles and objects described in the following table. The general PDF layer is implemented via "PDF" objects (for example HIG_PDF_DOC). The PDF editing layer is implemented via "PDE" objects (for example HIG_PDE_CONTENT).

NOTE: This chapter links to the PDF reference (Adobe PDF 1.7 specification), which can be downloaded from here: http://partners.adobe.com/asn/tech/pdf/ specifications.jsp


Summary

The following table contains the objects and their descriptions supported by the ImageGear PDF component:

General API
C API
DLL API which provides general ImageGear PDF Component functionality.
Basic Objects
HIG_PDF_BASOBJ
Basic Object - basic PDF object interface. PDF supports eight basic types of object:
  • Boolean values
  • Integer and Fixed (real) numbers
  • Strings
  • Names
  • Arrays
  • Dictionaries
  • Streams
  • The null object
Objects may be labeled so that they can be referred to by other objects. A labeled object is called an indirect object.
HIG_PDF_BASBOOL
Basic Boolean - PDF provides boolean objects identified by the keywords true and false. Boolean objects can be used as the values of array elements and dictionary entries.
HIG_PDF_BASINT
Basic Integer - Integer objects represent mathematical integers within a certain interval centered at 0.
HIG_PDF_BASFIXED
Basic Fixed - Fixed objects approximate mathematical real numbers, but with limited range and precision; they are typically represented in fixed-point, rather than floating-point, form.
HIG_PDF_BASSTR
Basic String - A string object consists of a series of bytes-unsigned integer values in the range 0 to 255. The string elements are not integer objects, but are stored in a more compact format.
HIG_PDF_BASNAME
Basic Name - A name object is an atomic symbol uniquely defined by a sequence of characters.
Uniquely defined means that any two name objects made up of the same sequence of characters are identically the same object. Atomic means that a name has no internal structure; although it is defined by a sequence of characters, those characters are not "elements" of the name.
HIG_PDF_BASARR
Basic Array - an array object is a one-dimensional collection of objects arranged sequentially. Unlike arrays in many other computer languages, PDF arrays may be heterogeneous; that is, an array's elements may be any combination of numbers, strings, dictionaries, or any other objects, including other arrays.
HIG_PDF_BASDICT
Basic Dictionary - a dictionary object is an associative table containing pairs of objects, known as the dictionary's entries. The first element of each entry is the key and the second element is the value. The key must be a name. The value can be any kind of object, including another dictionary.
HIG_PDF_BASNULL
Basic Null - The null object has a type and value that are unequal to those of any other object. There is only one object of type null, denoted by the keyword null.
General Objects
HIG_PDF_ACTION
Handle to a PDF action object, which is a task that performs when a user clicks on a link or a bookmark.
HIG_PDF_ATOM
Atom - a hashed token used in place of strings to optimize performance (it is much faster to compare Atoms than strings). Many methods use Atoms.
HIG_PDF_BOOKMARK
Handle to a PDF bookmark object, which allows the user to navigate interactively from one part of the document to another. It consists of a tree-structured hierarchy of bookmarks.
HIG_PDF_STREAM
Stream - a data stream that may be a buffer in memory, or an arbitrary user-written procedure. Typically used to extract or provide data.
HIG_PDF_DESTINATION
Handle to a PDF destination object, which represents a particular view of a page in a document. It contains a reference to a page, a rectangle on that page, and information specifying how to adjust the view to fit the window's size and shape.
HIG_PDF_DICTIONARY
Handle to a PDF dictionary object, which represents an optional-content membership dictionary object.
HIG_PDF_DOC
Document - the underlying PDF representation of a document. Through PDF Document, your application can perform most of the Edit Pages operations (delete, replace, and so on). Thumbnails can be created and deleted through this object. You can set and retrieve document information fields through this object as well.
HIG_PDF_FONT
Handle to a PDF font object that is used to draw text on a page. A HIG_PDF_FONT has a number of attributes, including an array of widths, the character encoding.
HIG_PDF_LAYER
Handle to a PDF layer object, which represents a named object whose state can be toggled in a UI to affect changes in visibility of content.
HIG_PDF_PAGE
Page - a single page in the PDF representation of a document. A page contains a series of objects representing the objects drawn on the page (Graphic), a list of resources used in drawing the page, annotations (Annotation), an optional thumbnail image of the page, and the beads used in any articles that occur on the page.
HIG_PDF_PREFLIGHT
This is a handle-based object that provides PDF preflight capabilities.
HIG_PDF_PREFLIGHT_REPORT
This is a handle-based object that contains PDF preflight report in a tree form.
HIG_PDF_WORDFINDER
WordFinder - extracts words from a PDF file, and enumerates the words on a single page or on all pages in a document..
HIG_PDF_WORD
Word - a word in a PDF file. Each word contains a sequence of characters in one or more styles (see Style).
HIG_PDF_STYLE
Style - provides access to information about the fonts, font sizes, and colors used in a Word.
HIG_PDF_SYSFONT
SysFont - a reference to a font installed in the host system. SysFont methods allow you to list the fonts available in the host system and to find a font in the system that matches a PDE Font, if it is present.
HIG_PDF_SYSENCODING
SysEncoding - provides system encoding for a PDF file.
Page Editing Objects and Elements
HIG_PDE_OBJECT
Object - base interface for all the PDE objects.
HIG_PDE_CONTENT
Content - modifiable content of a PDF page, which contains elements. Content may be obtained from an existing page or from a Form XObject.
HIG_PDE_COLORSPACE
ColorSpace - a reference to a color space used on a page in a PDF file. The color space is part of the graphics state attributes of a PDE Element.
HIG_PDE_FONT
Font - A reference to a font used on a page in a PDF file. It may be equated with a font in the system.
HIG_PDE_ELEMENT
Element - base interface for the elements of a page display list (PDE content) and for clip objects. The general PDE element methods allow you to get and set general element properties.
HIG_PDE_CLIP
Clip - a list of elements containing a list of Paths and Texts that describe a clip state. Clips can be created and built up with PDE Clip methods. Any PDE Element object can have Clip associated with it. Clip objects can contain PDE Containers and PDE Groups to an arbitrary level of nesting. This allows PDE Containers to be used to mark clip objects.
PDE Groups inside PDE Clips that contain at least one PDE Text and no PDE Paths have a special meaning. All PDE Text objects contained in such a PDE Group are considered to be part of the same BT/ET block. This means that the union of these
PDE Texts makes up a single clipping path-as opposed to the intersection of the PDE Texts.
See Section 5.3 in the PDF reference for more information about BT/ET block.
HIG_PDE_CONTAINER
Container - a group of elements on a page in a PDF file. In the PDF file, containers are delimited by Marked Content BMC/EMC or BDC/EMC pairs. Every container has a Marked Content tag associated with it. In addition to grouping a set of elements, a BDC/EMC pair specifies a property list to be associated with the grouping. Thus a container corresponding to a BDC/EMC pair also has a property list dictionary associated with it.
See Section 10.5 in the PDF reference for more information about Marked Content operators.
HIG_PDE_FORM
Form - an element that corresponds to an instance of XObject Form on a page (or other containing stream such as another XObject Form or annotation form). The context associated with this instance includes the actual stream that represents the XObject Form and the initial conditions of the graphics state. The latter consists of the transformation matrix, initial color values, and so forth. It is possible to have two Forms that refer to the same XObject Form. The forms will exist at different places on the same page, depending on the transformation matrix. They may also have different colors or line stroking parameters. In the case of a transparency group, the opacity is specified in the gstate.
Within a Form, each element has its own gstate (or is a container, place, or group object). These gstates are independent of the parent Form gstate. Form elements may have their own opacity.
Content may be obtained from a Form to edit the form's display list.
HIG_PDE_GROUP
Group - an in-memory representation of objects in Content. It has no state and is not represented in any way in a content stream (that is, Content).
When used in a Clip, this object is used to associate Text objects into a single clipping object.
HIG_PDE_IMAGE
Image - an element that contains an Image XObject or in-line image. You can associate data or a stream with an image.
HIG_PDE_PATH
Path - an element that contains a path. Path objects can be stroked, filled, and/or serve as a clipping path.
HIG_PDE_PLACE
Place - an element that marks a place on a page in a PDF file. In a PDF file, a place is represented by the MP or DP Marked Content operators.
Marked content is useful for adding structure information to a PDF file. For instance, a drawing program may want to mark a point with information, such as the start of a path of a certain type. Marked content provides a way to retain this information in the PDF file. A
DP operator functions the same as the MP operator and, in addition, allows a property list dictionary to be associated with a place.
HIG_PDE_POSTSCRIPT
PostScript - an element representing in-line or XObject pass-through PostScript object. XObject PostScripts are listed in page XObject resources.
HIG_PDE_SOFTMASK
SoftMask- an object for creating and manipulating a soft mask in a PDF file.
HIG_PDE_SHADING
Shading - an element that represents smooth shading.
HIG_PDE_TEXT
Text - an element representing text. It is a container for text as show strings or as individual characters. Each sub-element may have different graphics state properties. However, the same clip applies to all sub-elements of a Text. Also, the char path of a Text can be used to represent a clip.
HIG_PDE_TEXTITEM
TextItem - a PDE element representing a text object.
HIG_PDE_XGROUP
XGroup - a transparency (XGroup) resource.
HIG_PDE_XOBJECT
XObject - an element representing an arbitrary XObject.
Subsidiary Types / DLL Structures
AT_PDF_BOOL
Boolean type with two values: TRUE (1) or FALSE (0)
AT_PDF_FIXED
The Fixed type is a 32-bit quantity representing a rational number with the high (low on little-endian machines) 16 bits representing the number's mantissa and the low (high) 16 bits representing the fractional part. The definition is platform-dependent.
LPAT_PDF_FIXED is a pointer to an AT_PDF_FIXED.
Addition, subtraction, and negation with AT_PDF_FIXED types can be done with + and -, unless you care about overflow. (Overflow in Fixed-value operations is indicated by the values IG_PDF_FIXED_POSITIVE_INFINITY and IG_PDF_FIXED_NEGATIVE_INFINITY.)
AT_PDF_FIXEDPOINT
Point (in two-dimensional space) represented by two fixed numbers.
AT_PDF_FIXEDMATRIX
Matrix containing fixed numbers.
AT_PDF_FIXEDRECT
A rectangle represented by the coordinates of its four sides. A rectangle differs from a quadrilateral in that the former must always have horizontal and vertical sides, and opposite sides must be parallel.
AT_PDF_FIXEDQUAD
Quadrilateral represented by four fixed points (one at each corner). A quadrilateral differs from a rectangle in that the latter must always have horizontal and vertical sides, and opposite sides must be parallel.
AT_PDF_FONT_STYLES
Font Styles.
AT_PDF_FONT_METRICS
Font Metrics.
AT_PDF_PRINTOPTIONS
Used to control printing.
AT_PDE_FONTATTRS
Attributes of a PDE Font and a PDF SysFont.
AT_PDE_COLORVALUE
Color value.
AT_PDE_COLORSPEC
Color specification.
AT_PDE_DASH
Dash specification, as described in Table 4.8 in the PDF Reference. See Section 4.3.2 for more information on line dash patterns.
AT_PDE_GRAPHICSTATE
Attributes of a PDE Element or a PDE Text sub-element.
AT_PDE_TEXTSTATE
Attributes of a PDE Text element.
AT_PDF_SYSFONT_PLATDATA
PDF SysFont platform specific data.
AT_PDE_FONT_INFO
PDE Font information.
AT_PDE_FONT_CREATEFROMSYSFONTPARAMS
Parameters for PDE font creation.
AT_PDE_COLORRANGE
Color range.
AT_PDE_XYZCOLOR
XYZ color.
AT_PDE_COLORDATA_CALGRAY
CalGray color space.
AT_PDE_COLORDATA_CALRGB
CalRGB color space.
AT_PDE_COLORDATA_LAB
L*a*b* color space.
AT_PDE_COLORDATA_ICCBASED
ICC based color space.
AT_PDE_COLORDATA_INDEXED
Indexed color space.
AT_PDE_COLORDATA_SEPARATION
Separation color space
AT_PDE_COLORDATA_DEVICEN
DeviceN color space.
AT_PDE_COLORDATA
Fill in one of the following members of this union, then pass it to PDE ColorSpace creation routine. Please see section 7.10 of the PDF Reference Manual for information on color spaces.
AT_PDE_PSATTRS
Attributes of a PDE PS object.
AT_PDE_IMAGEATTRS
Attributes of a PDE Image object.
AT_PDE_FILTERSPEC
Filter element in a filter array.
AT_PDE_FILTERARRAY
Filter information for streams. Array of FilterSpec elements. Usually consists of 2 filter elements: text encoding and image compression.
AT_PDE_CONTENTATTRS
Attributes of a PDE Content object.


General API

General ImageGear PDF API calls, macros and callback functions.

The following table contains the objects and their descriptions supported by the ImageGear PDF component:

General API
C API
DLL API which provides general ImageGear PDF Component functionality.


C API

Type: Control

Description:

DLL API that provides general ImageGear PDF Component functionality. These general Functions, Macros and Callbacks are used for several different tasks: initialize and terminate the the PDF Component, fixed-point math utilities, Callbacks integrated with ImageGear Core components.

Class Members:

IG_PDE_get_default_gstate
Function
Fills out a LPAT_PDE_GRAPHICSTATE structure with the default graphic state.
IG_PDF_get_host_encoding
Function
Indicates what kind of host encoding a system uses.
IG_PDF_initialize
Function
This function is used to initialize the ImageGear PDF Component.
IG_PDF_register_authproc
Function
Registers the authorization callback
IG_PDF_terminate
Function
This function terminates the ImageGear PDF component, and must be called before terminating a user application.
IG_PDF_text_extract
Function
This function extracts text from pages determined by arguments nStartPage and nPageCount.
IG_PDF_translate_to_host
Function
Translates a string from Unicode or PDFDocEncoding to host encoding.
IG_PDF_translate_to_pdf
Function
Translates a string from host encoding to PDFDocEncoding or Unicode.
AM_PDF_LONG_TO_FIXED
Macro
Converts x to AT_PDF_FIXED and returns it.
AM_PDF_FIXED_ROUND_TO_LONG
Macro
Converts the AT_PDF_FIXED number f to an integer, rounding it to the nearest long integer value and returns it.
AM_PDF_FIXED_TRUNC_TO_LONG
Macro
Converts the AT_PDF_FIXED number f to an integer, truncating it to the next lower long integer value and returns it.
AM_PDF_SHORT_TO_FIXED
Macro
Converts x to AT_PDF_FIXED and returns it.
AM_PDF_FIXED_ROUND_TO_SHORT
Macro
Converts the AT_PDF_FIXED number f to an integer, rounding it to the nearest short integer value and returns it.
AM_PDF_FIXED_TRUNC_TO_SHORT
Macro
Converts the AT_PDF_FIXED number f to an integer, truncating it to the next lower short integer value and returns it.
AM_PDF_DOUBLE_TO_FIXED
Macro
Converts x to AT_PDF_FIXED and returns it.
AM_PDF_FIXED_TO_DOUBLE
Macro
Converts the AT_PDF_FIXED number f to double value and returns it.
LPFNIG_PDF_AUTHPROC
Callback
Callback used by document open routine. It is called when an encrypted document is being opened, to determine whether or not the user is authorized to open the file.
LPFNIG_PDF_STREAM_PROC
Callback
Callback for use by IG_PDF_stream_read_CB_register and IG_PDF_stream_write_CB_register. This procedure must return the number of bytes specified by nDataLen, obtaining them in any way it wishes.
LPFNIG_PDF_STREAM_DESTROYPROC
Callback
Callback for use by IG_PDF_stream_write_CB_register. Called at end of stream so you can do clean up and free allocated memory.
LPFNIG_PDF_SYSFONT_ENUMPROC
Callback
Callback for IG_PDF_sysfont_enumerate. It is called once for each system font.
LPFNIG_PDE_CLIP_ENUMPROC
Callback
Callback for IG_PDE_clip_enumerate_elements, which enumerates all of a PDE Clip's PDE Elements in a flattened manner.


IG_PDE_get_default_gstate

Group: C API Function

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_get_default_gstate(
    LPAT_PDE_GRAPHICSTATE lpGstate
    )

Parameters:

lpGstate
Pointer to AT_PDE_GRAPHICSTATE structure with the default graphic state.

Description:

Fills out a LPAT_PDE_GRAPHICSTATE structure with the default graphic state.

NOTE: Non-NULL objects in the graphic state, such as the fill and stroke color spaces, have their reference counts incremented by this method. Be sure to release these non-NULL objects when disposing of lpGstate.

Return Value:

Error count


IG_PDF_get_host_encoding

Group: C API Function

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_get_host_encoding(
    LPVOID *lpHostEncoding
    )

Arguments:

lpHostEncoding
Returns 0 for a Roman system; nonzero for a non-Roman system (a structure that depends on the host encoding). Users should simply test whether this value is 0 or not.

Description:

Indicates what kind of host encoding a system uses. Allows you to determine whether a system is Roman or non-Roman. (Non-Roman is also known as CJK-capable, that is, capable of handling multi-byte character sets, such as Chinese, Japanese, or Korean.)

Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is MacRomanEncoding in Mac OS and WinAnsiEncoding in Windows. In UNIX (except HP-UX) Roman systems, it is ISO8859-1 (ISO Latin-1); for HP-UX, it is HP-ROMAN8. See Appendix D in the PDF Reference for descriptions of MacRomanEncoding, WinAnsiEncoding, and PDFDocEncoding.

For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). See Section 5.6.4 in the PDF Reference for a list of predefined CMaps.

Use IG_PDF_get_host_encoding to determine if a system's host encoding is Roman or not.

Return Value:

Error count


IG_PDF_initialize

Group: C API Function

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_initialize(
LPVOID lpVoid);

Arguments:

lpVoid
Reserved, must be set to NULL.

Description:

This function is used to initialize the ImageGear PDF Component. To initialize the ImageGear PDF component it needs to be attached to the core ImageGear and then IG_PDF_initialize() function must be called.

The following resource content is required by the ImageGear PDF component initialization routine:

Resource\PDF\CIDFont\
PDF CID fonts directory
Resource\PDF\CMap\
PDF font CMaps directory
Resource\PDF\Font\
PDF fonts directory
Resource\PDF\Unicode\
PDF unicode mappings directory
Resource\PS\ColorRendering\
color rendering PostScript
Resource\PS\ICCProfiles\
Directory containing the ICC profiles that allow using the Adobe® Color Engine® (ACE®)
NOTE: The profiles in this directory must be placed in the system folder named, which on Windows is named \Windows\System32\Color.
Resource\PS\Fonts\
PS fonts directory
Resource\PS\ProcSet\
PostScript procedures
Resource\PS\ps.vm
a file for initializing the PostScript Interpreter's virtual memory
Resource\PS\startupNORM.ps
startup PostScript program used to initialize the PostScript Interpreter
Resource\PS\superatm.db
Adobe® Type Manager® (ATM®) database used to substitute missing fonts

The ImageGear PDF component uses the following PDF global control parameters to locate the resource content:

PDF.PDF_RESOURCE_PATH
path to the Resource\PDF directory
PDF.PS_RESOURCE_PATH
path to the Resource\PS directory
PDF.HOST_FONT_PATH
path to the system font directory
PDF.TMP_PATH
path to the TEMP directory

If the PDF global parameters are not defined, the ImageGear PDF Component behavior depends on the OS:

  • Resource content gets from the ImageGear component directory defined by COMM.PATH parameter
  • Host fonts get from the Windows font directory
  • Temporary directory gets from the GetTempPath() result

Return Value:

Error count


IG_PDF_register_authproc

Group: CAPI Function

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_register_authproc(
    LPFNIG_PDF_AUTHPROC lpfnAuthProc,
    LPVOID lpAuthData
    );

Arguments:

lpfnAuthProc
Authorization callback, called only if the file has been secured (that is, if the file has either the user or the master password set). This callback should obtain whatever information is needed to determine whether the user is authorized to open the file, then call IG_PDF_doc_perm_request (which returns the permissions that the authentication data enables).
lpAuthData
Pointer to user-supplied data to pass to lpfnAuthProc each time it is called.

Description:

Registers the authorization callback, which will be called when open a secured PDF file, i.e. a PDF that has either the user or the master password set.

Return Value:

Error count


IG_PDF_terminate

Group: C API Function

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_terminate();

Description:

This function terminates the ImageGear PDF component, and must be called before terminating a user application.

NOTE: For a multi-threaded application, you must call IG_PDF_initialize and IG_PDF_terminate in the thread - not in the calling module.

Return Value:

Error count


IG_PDF_text_extract

Group: CAPI Function

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_text_extract(
LPSTR lpszFileName,
LPSTR lpszTextName,
UINT nStartPage,
UINT nPageCount);

Arguments:

lpFileName
Name of the PDF or PS document
lpTextFileName
Name of the output TXT file
nStartPage
Number of the first page
nPageCount
Total number of pages to be processed (starting at nStartPage)

Description:

This function extracts text from pages determined by arguments nStartPage and nPageCount.

Return Value:

Error count


IG_PDF_translate_to_host

Group: C API Function

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_translate_to_host(
    LPCSTR szInPDFStr,
    LONG nInPDFStrSize,
    LPSTR szOutHostStr,
    LONG nOutHostStrSize,
    LPLONG lpnOutHostStrBytes
    );

Arguments:

szInPDFStr
Pointer to the string to translate (may point to the same memory as szOutHostStr, allowing strings to translate in place).
nInPDFStrSize
The length of szInPDFStr, in bytes.
szOutHostStr
Pointer to the translated string (may point to the same memory as szInPDFStr).
nOutHostStrSize
The length of the szOutHostStr buffer, in bytes.
lpnOutHostStrBytes
Number of bytes in the translated string szOutHostStr.

Description:

Translates a string from Unicode or PDFDocEncoding to host encoding. This method is useful when setting or retrieving displayed text that might be in Unicode, such as text that appears in a text annotation or bookmark.

A character that cannot be converted to the destination encoding is replaced with a space.

Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is MacRomanEncoding in Mac OS and WinAnsiEncoding in Windows. In UNIX (except HP-UX) Roman systems, it is ISO8859-1 (ISO Latin-1); for HP-UX, it is HP-ROMAN8. See Appendix D in the PDF Reference for descriptions of MacRomanEncoding, WinAnsiEncoding, and PDFDocEncoding.

For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). See Section 5.6.4 in the PDF Reference for information on CMaps.

Use IG_PDF_get_host_encoding to determine if a system's host encoding is Roman or not.

Return Value:

Error count


IG_PDF_translate_to_pdf

Group: C API Function

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_translate_to_pdf(
    AT_PDF_BOOL bUseUnicode,
    LPCSTR szInHostStr,
    LONG nInHostStrSize,
    LPSTR szOutPDFStr,
    LONG nOutPDFStrSize,
    LPLONG lpnOutPDFStrBytes
    );

Parameters:

bUseUnicode
If true, translate the string to Unicode; otherwise use PDFDocEncoding.
szInHostStr
Pointer to the string to translate (may point to the same memory as szOutPDFStr, allowing strings to translate in place).
nInHostStrSize
Number of bytes in szOutPDFStr.
szOutPDFStr
Pointer to the translated string (may point to the same memory as szInHostStr).
nOutPDFStrSize
The length of the szOutPDFStr buffer, in bytes.
lpnOutPDFStrBytes
Number of bytes in the translated string szOutPDFStr.

Description:

Translates a string from host encoding to PDFDocEncoding or Unicode. This method is useful when using text that must be in PDFDocEncoding or Unicode, such as text in a text annotation, bookmark, or article title.

A character that cannot be converted to the destination encoding is replaced with a space.

For example, it converts \n to a space character (\r is present in PDFDocEncoding and is left unchanged).

Host encoding is a platform-dependent encoding for the host machine. For non-UNIX Roman systems, it is MacRomanEncoding in Mac OS and WinAnsiEncoding in Windows. In UNIX (except HP-UX) Roman systems, it is ISO8859-1 (ISO Latin-1); for HP-UX, it is HP-ROMAN8. See Appendix D in the PDF Reference for descriptions of MacRomanEncoding, WinAnsiEncoding, and PDFDocEncoding.

For non-Roman systems, the host encoding may be a variety of encodings, which are defined by a CMap (character map). See Section 5.6.4 in the PDF Reference for a list of predefined CMaps.

Use IG_PDF_get_host_encoding to determine if a system's host encoding is Roman or not.

Return Value:

Error count


AM_PDF_LONG_TO_FIXED

Group: C API Macro

Declaration:

AM_PDF_LONG_TO_FIXED(x)

Arguments:

X
Long integer value.

Description:

Converts x to AT_PDF_FIXED and returns it.

Return Value:

AT_PDF_FIXED value


AM_PDF_FIXED_ROUND_TO_LONG

Group: C API Macro

Declaration:

AM_PDF_FIXED_ROUND_TO_LONG (f)

Arguments:

f
Fixed value.

Description:

Converts the AT_PDF_FIXED number f to an integer, rounding it to the nearest long integer value and returns it.

Return Value:

Long integer value


AM_PDF_FIXED_TRUNC_TO_LONG

Group: C API Macro

Declaration:

AM_PDF_FIXED_TRUNC_TO_LONG (f)

Arguments:

f
Fixed value.

Description:

Converts the AT_PDF_FIXED number f to an integer, truncating it to the next lower long integer value and returns it.

Return Value:

Long integer value


AM_PDF_SHORT_TO_FIXED

Group: C API Macro

Declaration:

AM_PDF_SHORT_TO_FIXED(x)

Arguments:

x
Short integer value.

Description:

Converts x to AT_PDF_FIXED and returns it.

Return Value:

AT_PDF_FIXED value


AM_PDF_FIXED_ROUND_TO_SHORT

Group: C API Macro

Declaration:

AM_PDF_FIXED_ROUND_TO_SHORT (f)

Arguments:

f
Fixed value.

Description:

Converts the AT_PDF_FIXED number f to an integer, rounding it to the nearest short integer value and returns it.

Return Value:

Short integer value


AM_PDF_FIXED_TRUNC_TO_SHORT

Group: C API Macro

Declaration:

AM_PDF_FIXED_TRUNC_TO_SHORT (f)

Arguments:

f
Fixed value.

Description:

Converts the AT_PDF_FIXED number f to an integer, truncating it to the next lower short integer value and returns it.

Return Value:

Short integer value


AM_PDF_DOUBLE_TO_FIXED

Group: C API Macro

Declaration:

AM_PDF_DOUBLE_TO_FIXED (x)

Arguments:

x
Double value.

Description:

Converts x to AT_PDF_FIXED and returns it.

Return Value:

AT_PDF_FIXED Value


AM_PDF_FIXED_TO_DOUBLE

Group: C API Macro

Declaration:

AM_PDF_FIXED_TO_DOUBLE (f)

Arguments:

f
Fixed value.

Description:

Converts the AT_PDF_FIXED number f to double value and returns it.

Return Value:

Double Value


LPFNIG_PDF_AUTHPROC

Group: C API Callback

Declaration:

typedef AT_PDF_BOOL (LPACCUAPI LPFNIG_PDF_AUTHPROC)(
    HIG_PDF_DOC hDoc,
    LPVOID clientData
    );

Arguments:

hDoc
The PDF document to open.
clientData
User-supplied data that was passed in the call to IG_PDF_register_authproc.

Description:

This callback is used by document open routine. It is called when an encrypted document is being opened, to determine whether or not the user is authorized to open the file.

This callback implements whatever authorization strategy you choose and calls the callbacks of the appropriate security handler (the one that was used to secure the document) to obtain and check authorization data.

The LPFNIG_PDF_AUTHPROC should obtain the authorization data (a password) and call IG_PDF_doc_perm_request(). IG_PDF_doc_perm_request in turn calls the document encryption handler's Authorize function, which returns the permissions that the authorization data enables. IG_PDF_doc_perm_request adds these permissions to those currently allowed, and returns the new set of allowed permissions.

Return Value:

TRUE if the user is authorized to open the document, FALSE otherwise.


LPFNIG_PDF_STREAM_PROC

Group: C API Callback

Declaration:

typedef LONG (LPACCUAPI LPFNIG_PDF_STREAM_PROC)(
LPSTR lpData,
UINT nDataLen,
LPVOID clientData );

Arguments:

lpData
Buffer into which your procedure must place the number of bytes specified by nDataLen.
nDataLen
Number of bytes to read from the stream and place into data.
clientData
User-supplied data that was specified in the call to IG_PDF_stream_read_CB_register or IG_PDF_stream_write_CB_register.

Description:

Callback for use by IG_PDF_stream_read_CB_register and IG_PDF_stream_write_CB_register. This procedure must return the number of bytes specified by nDataLen, obtaining them in any way it wishes.

Return Value:

Returns the number of bytes actually read or written.


LPFNIG_PDF_STREAM_DESTROYPROC

Group: C API Callback

Declaration:

typedef void (LPACCUAPI LPFNIG_PDF_STREAM_DESTROYPROC)(
LPVOID clientData );

Arguments:

lpData
Buffer into which your procedure must place the number of bytes specified by nDataLen.
nDataLen
Number of bytes to read from the stream and place into data.
clientData
User-supplied data that was specified in the call to IG_PDF_stream_write_CB_register.

Description:

Callback for use by IG_PDF_stream_write_CB_register. Called at end of stream so you can do clean up and free allocated memory.

Return Value:

Returns the number of bytes actually read or written.


LPFNIG_PDF_SYSFONT_ENUMPROC

Group: C API Callback

Declaration:

typedef (LPACCUAPI LPFNIG_PDF_SYSFONT_ENUMPROC)(
HIG_PDF_SYSFONT hSysFont,
LPVOID clientData );

Arguments:

hSysFont
The system font
clientData
User-supplied data that was specified in the call to IG_PDF_sysfont_enumerate.

Description:

Callback for IG_PDF_sysfont_enumerate. It is called once for each system font.

Return Value:

Returns true to continue enumeration, false to halt enumeration


LPFNIG_PDE_CLIP_ENUMPROC

Group: C API Callback

Declaration:

typedef AT_PDF_BOOL (LPACCUAPI LPFNIG_PDE_CLIP_ENUMPROC)(
HIG_PDE_ELEMENT hElement,
LPVOID clientData );

Arguments:

hElement
The PDE Element currently being enumerated.
clientData
User-supplied data that was passed in the call to IG_PDE_clip_enumerate_elements.

Description:

Callback for IG_PDE_clip_enumerate_elements(), which enumerates all of a PDE Clip's PDE Elements in a flattened manner.

Return Value:

If False, enumeration halts. If True, enumeration continues.


Basic Objects

This chapter describes the basic PDF objects and utility functions used throughout the ImageGear PDF API. These objects provide access to the building blocks used to construct PDF documents. Its methods allow applications to manipulate the low-level data in a PDF file, such as strings, numbers, and dictionaries. Adobe PDF supports eight basic platform-independent types of object:

  • Boolean values
  • Integer and Fixed (real) numbers
  • Strings
  • Names
  • Arrays
  • Dictionaries
  • Streams
  • The null object

These objects may be labeled so that they can be referred to by other objects. A labeled object is called an indirect object. When a direct object is created, the object itself is returned. As a result, a direct object can only be attached to one other Base object at a time; it cannot, for example, be shared by two different dictionaries. When an indirect object is created, something equivalent to a pointer to the object is returned. As a result, an indirect object can be attached to multiple places in a PDF file simultaneously; it can, for example, be shared by two different dictionaries.

PDF documents are trees of these Base objects. Base objects represent document components such as bookmarks, pages, and fonts. Unlike using the other ImageGear PDF Obejcts methods, using Base Object methods improperlycould result in an invalid PDF file. Therefore, you should not use Base Object methods unless necessary, for example to add private data to portions of a PDF file that cannot be accessed in other ways.

The following table contains the objects and their descriptions supported by the ImageGear PDF component:

Basic Objects
HIG_PDF_BASOBJ
Basic Object - basic PDF object interface. PDF supports eight basic types of object:
  • Boolean values
  • Integer and Fixed (real) numbers
  • Strings
  • Names
  • Arrays
  • Dictionaries
  • Streams
  • The null object
Objects may be labeled so that they can be referred to by other objects. A labeled object is called an indirect object.
HIG_PDF_BASBOOL
Basic Boolean - PDF provides boolean objects identified by the keywords true and false. Boolean objects can be used as the values of array elements and dictionary entries.
HIG_PDF_BASINT
Basic Integer - Integer objects represent mathematical integers within a certain interval centered at 0.
HIG_PDF_BASFIXED
Basic Fixed - Fixed objects approximate mathematical real numbers, but with limited range and precision; they are typically represented in fixed-point, rather than floating-point, form.
HIG_PDF_BASSTR
Basic String - A string object consists of a series of bytes-unsigned integer values in the range 0 to 255. The string elements are not integer objects, but are stored in a more compact format.
HIG_PDF_BASNAME
Basic Name - A name object is an atomic symbol uniquely defined by a sequence of characters.
Uniquely defined means that any two name objects made up of the same sequence of characters are identically the same object. Atomic means that a name has no internal structure; although it is defined by a sequence of characters, those characters are not "elements" of the name.
HIG_PDF_BASARR
Basic Array - an array object is a one-dimensional collection of objects arranged sequentially. Unlike arrays in many other computer languages, PDF arrays may be heterogeneous; that is, an array's elements may be any combination of numbers, strings, dictionaries, or any other objects, including other arrays.
HIG_PDF_BASDICT
Basic Dictionary - a dictionary object is an associative table containing pairs of objects, known as the dictionary's entries. The first element of each entry is the key and the second element is the value. The key must be a name. The value can be any kind of object, including another dictionary.
HIG_PDF_BASNULL
Basic Null - The null object has a type and value that are unequal to those of any other object. There is only one object of type null, denoted by the keyword null.


HIG_PDF_BASOBJ

Type: Basic Object

Description:

Handle to the basic object.

Class Members:

IG_PDF_basobj_get_type
Gets an object's type.
IG_PDF_basobj_release
Releases PDF Object.
IG_PDF_basobj_remove
Removes basic object.


IG_PDF_basobj_get_type

Group: Basic Object

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basobj_get_type (HIG_PDF_BASOBJ
hObject,LPLONG lpnType );

Arguments:

hObject
Basic object.
lpnType
The object's type.

Description:

Gets an object's type.

Return Value:

Error count.


IG_PDF_basobj_release

Group: Basic Object

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basobj_release (HIG_PDF_BASOBJ
hObject );

Arguments:

hObject
Object to release.

Description:

Releases PDF Object.

Return Value:

Error count.


IG_PDF_basobj_remove

Group: Basic Object

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basobj_remove(
    HIG_PDF_BASOBJ hObject
    );

Arguments:

hObject
The object to remove.

Description:

Removes basic object. If a composite object (array, dictionary or stream) is removed all the direct objects in it are automatically removed, but the indirect objects in it are not removed.

Return Value:

Error count.


HIG_PDF_BASBOOL

Type: Basic Boolean

Description:

Handle to the basic Boolean object. PDF provides boolean objects identified by the keywords true and false. Boolean objects can be used as the values of array elements and dictionary entries.

Class Members:

IG_PDF_basbool_create
Creates a new boolean object associated with the specified document and having the specified value.
IG_PDF_basbool_get_value
Gets the value of the specified boolean object.


IG_PDF_basbool_create

Group: Basic Boolean

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basbool_create(
HIG_PDF_DOC hDoc,
AT_PDF_BOOL bIndirect,
AT_PDF_BOOL bValue,
LPHIG_PDF_BASOBJ lphBool );

Arguments:

hDoc
The document in which the boolean is used.
bIndirect
If True, creates the boolean object as an indirect object. If False, creates the boolean as a direct object.
bValue
The value the new boolean will have.
lphBool
A boolean object.

Description:

Creates a new boolean object associated with the specified document and having the specified value.

Return Value:

Error count.


IG_PDF_basbool_get_value

Group: Basic Boolean

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basbool_get_value (
HIG_PDF_BASOBJ hBool,
LPAT_PDF_BOOL lpbValue );

Arguments:

hBool
Object
lpbValue
Value

Description:

Gets the value of the specified boolean object.

Return Value:

Error count.


HIG_PDF_BASINT

Type: Basic Integer Object

Description:

Handle to the basic integer object. Integer objects represent mathematical integers within a certain interval centered at 0.

Class Members:

IG_PDF_basint_create
Creates a new integer object associated with the specified document and having the specified value.
IG_PDF_basint_get_value
Gets the value of the specified integer object.


IG_PDF_basint_create

Group: Basic Integer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basint_create(
HIG_PDF_DOC hDoc,
AT_PDF_BOOL bIndirect,
LONG nValue,
LPHIG_PDF_BASOBJ lphInt );

Arguments:

hDoc
The document in which the object is used.
bIndirect
If True, creates the integer as an indirect object. If False, creates the integer as a direct object.
nValue
The value the new integer will have.
lphInt
An integer object.

Description:

Creates a new integer object associated with the specified document and having the specified value.

Return Value:

Error count.


IG_PDF_basint_get_value

Group: Basic Integer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basint_get_value (
HIG_PDF_BASOBJ hInt,
LPLONG lpnValue );

Arguments:

hInt
Object
lpnValue
Value

Description:

Gets the value of the specified integer object.

Return Value:

Error count.


HIG_PDF_BASFIXED

Type: Basic Fixed Object

Description:

Handle to the basic fixed object. Fixed objects approximate mathematical real numbers, but with limited range and precision; they are typically represented in fixed-point, rather than floating-point, form.

Class Members:

IG_PDF_basfixed_create
Creates a new fixed object associated with the specified document and having the specified value.
IG_PDF_basfixed_get_value
Gets the value of the specified fixed object.


IG_PDF_basfixed_create

Group: Basic Fixed

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basfixed_create(
HIG_PDF_DOC hDoc,
AT_PDF_BOOL bIndirect,
LONG nValue,
LPHIG_PDF_BASOBJ lphFixed );

Arguments:

hDoc
The document in which the object is used.
bIndirect
If True, creates the fixed as an indirect object. If False, creates the fixed as a direct object.
nValue
The value the new fixed will have.
lphFixed
The value the new fixed will have.

Description:

Creates a new fixed object associated with the specified document and having the specified value.

Return Value:

Error count.


IG_PDF_basfixed_get_value

Group: Basic Fixed

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basfixed_get_value (
HIG_PDF_BASOBJ hFixed,
LPLONG lpnValue );

Arguments:

hFixed
Object
lpnValue
Value

Description:

Gets the value of the specified fixed object.

Return Value:

Error count.


HIG_PDF_BASSTR

Type: Basic String Object

Description:

Handle to the basic string object. A string object consists of a series of bytes-unsigned integer values in the range 0 to 255. The string elements are not integer objects, but are stored in a more compact format.

Class Members:

IG_PDF_basstr_create
Creates a new string object associated with the specified document and having the specified value.
IG_PDF_basstr_get_value
Copies at most nLen bytes from obj's string value into lpString, and stores the actual length of the basic string in lpnBytes.


IG_PDF_basstr_create

Group: Basic String

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basstr_create(
HIG_PDF_DOC hDoc,
AT_PDF_BOOL bIndirect,
LPBYTE lpString,
LONG nBytes,
LPHIG_PDF_BASOBJ lphString );

Arguments:

hDoc
The document in which the object is used.
bIndirect
If True, creates the string as an indirect object. If False, creates the string as a direct object.
lpString
The value the new string will have.
nBytes
The length of lpString.
lphString
The value the new string will have.

Description:

Creates a new string object associated with the specified document and having the specified value.

Return Value:

Error count.


IG_PDF_basstr_get_value

Group: Basic String

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basstr_get_value (
HIG_PDF_BASOBJ hString,
LPBYTE lpString,
LONG nLen,
LPLONG lpnBytes );

Arguments:

hString
Object
lpString
The buffer into which the original string value is copied or NULL.
nLen
The length of buffer or 0.
lpnBytes
The length of the original string in bytes. Must be a non-NULL pointer.

Description:

Copies at most nLen bytes from obj's string value into lpString, and stores the actual length of the basic string in lpnBytes.

Return Value:

Error count.


HIG_PDF_BASNAME

Type: Basic Name Object

Description:

Handle to the basic name object. A name object is an atomic symbol uniquely defined by a sequence of characters.

Uniquely defined means that any two name objects made up of the same sequence of characters are identically the same object. Atomic means that a name has no internal structure; although it is defined by a sequence of characters, those characters are not "elements" of the name.

Class Members:

IG_PDF_basname_create
Creates a new name object associated with the specified document and having the specified value.
IG_PDF_basname_get_value
Gets the value of the specified name object.


IG_PDF_basname_create

Group: Basic Name

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basname_create(
HIG_PDF_DOC hDoc,
AT_PDF_BOOL bIndirect,
HIG_PDF_ATOM hNameVal,
LPHIG_PDF_BASOBJ lphName);

Arguments:

hDoc
The document in which the object is used.
bIndirect
If True, creates the name as an indirect object. If False, creates the name as a direct object.
hNameVal
The value the new name will have.
lphName
A name object.

Description:

Creates a new name object associated with the specified document and having the specified value.

Return Value:

Error count.


IG_PDF_basname_get_value

Group: Basic Name

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basname_get_value (
HIG_PDF_BASOBJ hName,
LPHIG_PDF_ATOM lphNameVal );

Arguments:

hName
Object
lpnNameVal
Value

Description:

Gets the value of the specified name object.

Return Value:

Error count.


HIG_PDF_BASARR

Type: Basic Array Object

Description:

General HIG_PDF_BASOBJ is used to handle to the basic array object. An array object is a one-dimensional collection of objects arranged sequentially. Unlike arrays in many other computer languages, PDF arrays may be heterogeneous; that is, an array's elements may be any combination of numbers, strings, dictionaries, or any other objects, including other arrays.

Class Members:

IG_PDF_basarr_create
Creates a new array of objects.
IG_PDF_basarr_get_length
Gets the number of elements in hArray.
IG_PDF_basarr_get
Gets the specified element from an array.
IG_PDF_basarr_put
Puts the specified object into the specified location in an array.
IG_PDF_basarr_put_int
Puts the specified fixed value into the specified location in an array.
IG_PDF_basarr_put_fixed
Puts the specified fixed value into the specified location in an array.
IG_PDF_basarr_put_bool
Puts the specified boolean value into the specified location in an array.
IG_PDF_basarr_put_name
Puts the specified name value into the specified location in an array.
IG_PDF_basarr_remove
Finds the first element, if any, equal to the specified object and removes it from the array.
IG_PDF_basarr_remove_nth
Checks whether the position is within the array bounds and then removes it from the array and moves each subsequent element to the slot with the next smaller index and decrements the array's length by 1.


IG_PDF_basarr_create

Group: Basic Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basarr_create(
HIG_PDF_DOC hDoc,
AT_PDF_BOOL bIndirect,
UINT nElements,
LPHIG_PDF_BASOBJ lphArray );

Arguments:

hDoc
The document in which the array is used.
bIndirect
If true, creates the array as an indirect object. If false, creates the dictionary as a direct object.
nElements
Number of entries in the array. This value is only a hint - the arrays grow dynamically as needed.
lphArray
New array

Description:

Creates a new array of objects.

Return Value:

Error count.


IG_PDF_basarr_get_length

Group: Basic Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basarr_get_length(
HIG_PDF_BASOBJ hArray,
LPLONG lpnLength );

Arguments:

hArray
The array.
lpnLength
The number of elements in hArray.

Description:

Gets the number of elements in hArray.

Return Value:

Error count.


IG_PDF_basarr_get

Group: Basic Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basarr_get(
HIG_PDF_BASOBJ hArray,
UINT nIndex,
LPHIG_PDF_BASOBJ lphObject);

Arguments:

hArray
The array from which an element is obtained.
nIndex
The array element to obtain. The first element in an array has an index of zero.
lphObject
The basic object occupying the nIndex element of array. Returns IG_PDF_BASIC_NULL object if index is outside the array bounds.

Description:

Gets the specified element from an array.

Return Value:

Error count.


IG_PDF_basarr_put

Group: Basic Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basarr_put(
HIG_PDF_BASOBJ hArray,
UINT nIndex,
HIG_PDF_BASOBJ hObject);

Arguments:

hArray
The array in which hObject is stored.
nIndex
The location in array to store hObject. The first element of an array has an index of zero.
hObject
The object to insert into hArray.

Description:

Puts the specified object into the specified location in an array. The array is extended as much as necessary.

Return Value:

Error count.


IG_PDF_basarr_put_int

Group: Basic Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basarr_put_int(
HIG_PDF_BASOBJ hArray,
UINT nIndex,
AT_PDF_BOOL bIndirect,
INT nValue );

Arguments:

hArray
The array in which a value is stored.
nIndex
The location in array to store a value. The first element of an array has an index of zero.
bIndirect
If true, creates the key value as an indirect object. If false, creates the key value as a direct object.
nValue
The integer value to insert into hArray.

Description:

Puts the specified integer value into the specified location in an array. The array is extended as much as necessary.

Return Value:

Error count.


IG_PDF_basarr_put_fixed

Group: Basic Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basarr_put_fixed(
HIG_PDF_BASOBJ hArray,
UINT nIndex,
AT_PDF_BOOL bIndirect,
AT_PDF_FIXED nValue );

Arguments:

hArray
The array in which a value is stored.
nIndex
The location in array to store a value. The first element of an array has an index of zero.
bIndirect
If true, creates the key value as an indirect object. If false, creates the key value as a direct object.
nValue
The fixed value to insert into hArray.

Description:

Puts the specified fixed value into the specified location in an array. The array is extended as much as necessary.

Return Value:

Error count.


IG_PDF_basarr_put_bool

Group: Basic Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basarr_put_bool(
HIG_PDF_BASOBJ hArray,
UINT nIndex,
AT_PDF_BOOL bIndirect,
AT_PDF_BOOL bValue );

Arguments:

hArray
The array in which a value is stored.
nIndex
The location in array to store a value. The first element of an array has an index of zero.
bIndirect
If true, creates the key value as an indirect object. If false, creates the key value as a direct object.
bValue
The boolean value to insert into hArray.

Description:

Puts the specified boolean value into the specified location in an array. The array is extended as much as necessary.

Return Value:

Error count.


IG_PDF_basarr_put_name

Group: Basic Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basarr_put_name(
HIG_PDF_BASOBJ hArray,
UINT nIndex,
AT_PDF_BOOL bIndirect,
HIG_PDF_ATOM nName);

Arguments:

hArray
The array in which a value is stored.
nIndex
The location in array to store a value. The first element of an array has an index of zero.
bIndirect
If true, creates the key value as an indirect object. If false, creates the key value as a direct object.
nName
The name value to insert into hArray.

Description:

Puts the specified name value into the specified location in an array. The array is extended as much as necessary.

Return Value:

Error count.


IG_PDF_basarr_remove

Group: Basic Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basarr_remove(
HIG_PDF_BASOBJ hArray,
HIG_PDF_BASOBJ hObject);

Arguments:

hArray
The array in which hObject is removed.
hObject
The object to remove.

Description:

Finds the first element, if any, equal to the specified object and removes it from the array.

Return Value:

Error count.


IG_PDF_basarr_remove_nth

Group: Basic Array

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basarr_remove_nth(
HIG_PDF_BASOBJ hArray,
UINT nIndex);

Arguments:

hArray
The array to remove the member from.
nIndex
The index for the array member to remove. Array indices start at 0.

Description:

Checks whether the position is within the array bounds and then removes it from the array and moves each subsequent element to the slot with the next smaller index and decrements the array's length by 1.

Return Value:

Error count.


HIG_PDF_BASDICT

Type: Basic Dictionary Object

Description:

General HIG_PDF_BASOBJ is used to handle to the basic dictionary object. A dictionary object is an associative table containing pairs of objects, known as the dictionary's entries. The first element of each entry is the key and the second element is the value. The key must be a name. The value can be any kind of object, including another dictionary.

Class Members:

IG_PDF_basdict_create
Creates a new dictionary.
IG_PDF_basdict_known
Tests whether a specific key is found in the specified dictionary.
IG_PDF_basdict_get
Gets the value of the specified key in the specified dictionary.
IG_PDF_basdict_put
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present.
IG_PDF_basdict_put_int
Sets the integer value of a dictionary key, adding the key to the dictionary if it is not already present.
IG_PDF_basdict_put_fixed
Sets the boolean value of a dictionary key, adding the key to the dictionary if it is not already present.
IG_PDF_basdict_put_bool
Sets the boolean value of a dictionary key, adding the key to the dictionary if it is not already present.
IG_PDF_basdict_put_name
Sets the name value of a dictionary key, adding the key to the dictionary if it is not already present.
IG_PDF_basdict_remove
Removes a key-value pair from a dictionary.


IG_PDF_basdict_create

Group: Basic Dictionary

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basdict_create(
HIG_PDF_DOC hDoc,
AT_PDF_BOOL bIndirect,
UINT nEntries,
LPHIG_PDF_BASOBJ lphDictionary );

Arguments:

hDoc
The document in which the dictionary is used.
bIndirect
If true, creates the dictionary as an indirect object. If false, creates the dictionary as a direct object.
nEntries
Number of entries in the dictionary. This value is only a hint - the dictionaries grow dynamically as needed.
lphDictionary
New dictionary

Description:

Creates a new dictionary.

See the PDF Reference for information on dictionary objects that are part of standard PDF, such as annotations or page objects.

Return Value:

Error count.


IG_PDF_basdict_known

Group: Basic Dictionary

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basdict_known(
HIG_PDF_BASOBJ hDictionary,
HIG_PDF_ATOM hKey,
LPAT_PDF_BOOL lpbKnown );

Arguments:

hDictionary
The dictionary in which to look for key.
hKey
The key to find. See the PDF Reference to obtain the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects.
lpbKnown
True if the value of a key is known (exists and is not null) in hDictionary; false otherwise.

Description:

Tests whether a specific key is found in the specified dictionary.

Return Value:

Error count.


IG_PDF_basdict_get

Group: Basic Dictionary

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basdict_get(
HIG_PDF_BASOBJ hDictionary,
HIG_PDF_ATOM hKey,
LPHIG_PDF_BASOBJ lphObject);

Arguments:

hDictionary
The dictionary or stream from which a value is obtained.
hKey
The key whose value is obtained. See the PDF Reference to obtain the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects.
lphObject
The object associated with the specified key. If key is not present or if its value is null, returns an object of type IG_PDF_BASIC_NULL.

Description:

Gets the value of the specified key in the specified dictionary. If called with a stream object instead of a dictionary object, this method gets the value of the specified key from the stream's attributes dictionary.

Return Value:

Error count.


IG_PDF_basdict_put

Group: Basic Dictionary

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basdict_put(
HIG_PDF_BASOBJ hDictionary,
HIG_PDF_ATOM hKey,
HIG_PDF_BASOBJ hObject);

Arguments:

hDictionary
The dictionary in which a value is set.
hKey
The key whose value is set. See the PDF Reference to obtain the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects.
hObject
The value to set.

Description:

Sets the value of a dictionary key, adding the key to the dictionary if it is not already present.

Return Value:

Error count.


IG_PDF_basdict_put_int

Group: Basic Dictionary

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basdict_put_int(
HIG_PDF_BASOBJ hDictionary,
HIG_PDF_ATOM hKey,
AT_PDF_BOOL bIndirect,
INT nValue );

Arguments:

hDictionary
The dictionary in which a value is set.
hKey
The key whose value is set. See the PDF Reference to obtain the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects.
bIndirect
If true, creates the key value as an indirect object. If false, creates the key value as a direct object.
nValue
The integer value to set.

Description:

Sets the integer value of a dictionary key, adding the key to the dictionary if it is not already present.

Return Value:

Error count.


IG_PDF_basdict_put_fixed

Group: Basic Dictionary

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basdict_put_fixed(
HIG_PDF_BASOBJ hDictionary,
HIG_PDF_ATOM hKey,
AT_PDF_BOOL bIndirect,
AT_PDF_FIXED nValue );

Arguments:

hDictionary
The dictionary in which a value is set.
hKey
The key whose value is set. See the PDF Reference to obtain the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects.
bIndirect
If true, creates the key value as an indirect object. If false, creates the key value as a direct object.
nValue
The fixed value to set.

Description:

Sets the fixed value of a dictionary key, adding the key to the dictionary if it is not already present.

Return Value:

Error count.


IG_PDF_basdict_put_bool

Group: Basic Dictionary

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basdict_put_bool(
HIG_PDF_BASOBJ hDictionary,
HIG_PDF_ATOM hKey,
AT_PDF_BOOL bIndirect,
AT_PDF_BOOL bValue );

Arguments:

hDictionary
The dictionary in which a value is set.
hKey
The key whose value is set. See the PDF Reference to obtain the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects.
bIndirect
If true, creates the key value as an indirect object. If false, creates the key value as a direct object.
bValue
The boolean value to set.

Description:

Sets the boolean value of a dictionary key, adding the key to the dictionary if it is not already present.

Return Value:

Error count.


IG_PDF_basdict_put_name

Group: Basic Dictionary

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basdict_put_name(
HIG_PDF_BASOBJ hDictionary,
HIG_PDF_ATOM hKey,
AT_PDF_BOOL bIndirect,
HIG_PDF_ATOM nName);

Arguments:

hDictionary
The dictionary in which a value is set.
hKey
The key whose value is set. See the PDF Reference to obtain the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects.
bIndirect
If true, creates the key value as an indirect object. If false, creates the key value as a direct object.
nName
The name value to set.

Description:

Sets the name value of a dictionary key, adding the key to the dictionary if it is not already present.

Return Value:

Error count.


IG_PDF_basdict_remove

Group: Basic Dictionary

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basdict_remove(
HIG_PDF_BASOBJ hDictionary,
HIG_PDF_ATOM hKey);

Arguments:

hDictionary
The dictionary in which a key is removed.
hKey
The key to remove.

Description:

Removes a key-value pair from a dictionary.

Return Value:

Error count.


HIG_PDF_BASNULL

Type: Basic Null Object

Description:

Handle to the basic null object. The null object has a type and value that are unequal to those of any other object. There is only one object of type null, denoted by the keyword null.

Class Members:

IG_PDF_basnull_create
Creates a direct null object.


IG_PDF_basnull_create

Group: Basic Null

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_basnull_create(
    LPHIG_PDF_BASOBJ lphNull );

Arguments:

lphNull
Null object.

Description:

Creates a direct null object.

Return Value:

Error count.


General Objects

This chapter describes a group of objects that provide access to PDF document's components such as metadata, pages, fonts etc. These objects and methods allow applications to manipulate the PDF content and data. Some of the objects allow you to work with host system fonts and encodings, and the supplementary objects such as Atom and Stream used to simplify and optimize working with PDF content.

The following table contains the objects and their descriptions supported by the ImageGear PDF component:

General Objects
HIG_PDF_ACTION
Handle to a PDF action object, which is a task that performs when a user clicks on a link or a bookmark.
HIG_PDF_ATOM
Atom - a hashed token used in place of strings to optimize performance (it is much faster to compare Atoms than strings). Many methods use Atoms.
HIG_PDF_BOOKMARK
Handle to a PDF bookmark object, which allows the user to navigate interactively from one part of the document to another.
HIG_PDF_DESTINATION
Handle to a PDF destination object, which represents a particular view of a page in a document.
HIG_PDF_DOC
Document - the underlying PDF representation of a document. Through PDF Document, your application can perform most of the Edit Pages operations (delete, replace, and so on). Thumbnails can be created and deleted through this object. You can set and retrieve document information fields through this object as well.
HIG_PDF_PAGE
Page - a single page in the PDF representation of a document. A page contains a series of objects representing the objects drawn on the page (Graphic), a list of resources used in drawing the page, annotations (Annotation), an optional thumbnail image of the page, and the beads used in any articles that occur on the page.
HIG_PDF_STREAM
Stream - a data stream that may be a buffer in memory, or an arbitrary user-written procedure. Typically used to extract or provide data.
HIG_PDF_STYLE
Style - provides access to information about the fonts, font sizes, and colors used in a Word.
HIG_PDF_SYSENCODING
SysEncoding - provides system encoding for a PDF file.
HIG_PDF_SYSFONT
SysFont - a reference to a font installed in the host system. SysFont methods allow you to list the fonts available in the host system and to find a font in the system that matches a PDE Font, if it is present.
HIG_PDF_WORD
Word - a word in a PDF file. Each word contains a sequence of characters in one or more styles (see Style).
HIG_PDF_WORDFINDER
WordFinder - extracts words from a PDF file, and enumerates the words on a single page or on all pages in a document..


HIG_PDF_ACTION

Type: Atom Object

Description:

Handle to a PDF action object, which is a task that performs when a user clicks on a link or a bookmark. Action types include:

  • Going to another view within the same document
  • Going to a specified view in another PDF file
  • Launching an arbitrary file
  • Resolving a URL

See Section 8.5 in the PDF Reference for more information on actions.

Class Members:

IG_PDF_action_create
Creates a new action object.
IG_PDF_action_create_destination
Creates a new action that takes the user to the specified destination view.
IG_PDF_action_create_filename
Creates an action of the specified type from a file name.
IG_PDF_action_delete
Deletes an action object.
IG_PDF_action_get_destination
Gets an action's destination view.
IG_PDF_action_get_dictionary
Gets the dictionary corresponding to an action.
IG_PDF_action_get_filename
Gets a file name from an action.
IG_PDF_action_get_type
Gets an action's type.


IG_PDF_action_create

Group: Action

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_action_create(
    HIG_PDF_DOC hDoc,
    HIG_PDF_ATOM hType,
    LPHIG_PDF_ACTION lphAction
    );

Arguments:

hDoc
The document in which the action is created and used.
hType
The atom corresponding to the action's subtype.
lphAction
The newly created action object.

Description:

Creates a new action object.

Return Value:

Error count.


IG_PDF_action_create_destination

Group: Action

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_action_create_destination(
    HIG_PDF_DOC hDoc,
    HIG_PDF_DESTINATION hDest,
    LPHIG_PDF_ACTION lphAction
    );

Arguments:

hDoc
The document in which the action is created and used.
hDest
The destination.
lphAction
The newly created action object.

Description:

Creates a new action that takes the user to the specified destination view. This method can only be used for destinations in the same document as the source document. Cross-document links must be built up from the base level, populating the Action dictionary for the GotoR action as described in Section 8.5.3 in the PDF Reference.

Return Value:

Error count.


IG_PDF_action_create_filename

Group: Action

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_action_create_filename(
    HIG_PDF_DOC hDoc,
    HIG_PDF_ATOM hType,
    LPCSTR szFileName,
    LPHIG_PDF_ACTION lphAction
    );

Arguments:

hDoc
The document in which the action is created and used.
hType
The type of action to create.
szFileName
The file name.
lphAction
The newly created action object.

Description:

Creates an action of the specified type from a file name.

Return Value:

Error count.


IG_PDF_action_delete

Group: Action

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_action_delete(
    HIG_PDF_ACTION hAction
    );

Arguments:

hAction
The action object to delete.

Description:

Deletes an action object.

Return Value:

Error count.


IG_PDF_action_get_destination

Group: Action

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_action_get_destination(
    HIG_PDF_ACTION hAction,
    LPHIG_PDF_DESTINATION lphDest
    );

Arguments:

hAction
The action whose destination is obtained.
lphDest
The action's destination, which may be either an explicit or named (basic string or name object). Use the IG_PDF_destination_resolve on this returned value to obtain an explicit destination.

Description:

Gets an action's destination view. This only works for actions that contain a view destination - that is, actions whose type is GoTo. For named destinations, this method may return a basic string or name object. See Section 8.2.1 in the PDF Reference for more information on named destinations.

NOTE: Since this method may not return an explicit destination, use the IG_PDF_destination_resolve on the returned value to obtain an explicit destination.

Return Value:

Error count.


IG_PDF_action_get_dictionary

Group: Action

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_action_get_dictionary(
    HIG_PDF_ACTION hAction,
    LPHIG_PDF_BASOBJ lphDictionary
    );

Arguments:

hAction
The action whose dictionary is obtained.
lphDictionary
Dictionary object for the action.

Description:

Gets the dictionary corresponding to an action.

Return Value:

Error count.


IG_PDF_action_get_filename

Group: Action

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_action_get_filename(
    HIG_PDF_ACTION hAction,
    LPSTR lpBuf,
    AT_INT nSize,
    LPAT_INT lpnLen
    );

Arguments:

hAction
The action whose file name is obtained.
lpBuf
The buffer to return a file name.
nSize
Size of lpBuf.
lpnLen
Length of the file name.

Description:

Gets a file name from an action. Not all types of actions have file names; this method only works for actions that contain a file specification. See Section 8.5 in the PDF Reference for more information on the contents of various types of actions.

Return Value:

Error count.


IG_PDF_action_get_type

Group: Action

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_action_get_type(
    HIG_PDF_ACTION hAction,
    LPHIG_PDF_ATOM lphType
    );

Arguments:

hAction
The action whose type is obtained.
lphType
The atom corresponding to the action's type.

Description:

Gets an action's type.

Return Value:

Error count.


HIG_PDF_ATOM

Type: Atom Object

Description:

Handle to the PDF atom object. A hashed token used in place of strings to optimize performance (it is much faster to compare Atoms than strings). Many methods use Atoms.

Class Members:

IG_PDF_atom_from_string
Gets the Atom for the specified string.
IG_PDF_atom_get_string
Gets the string associated with the specified Atom.


IG_PDF_atom_from_string

Group: Atom

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_atom_from_string(
LPCSTR lpString,
LPHIG_PDF_ATOM lphAtom);

Arguments:

lpString
The string for which an atom is obtained.
lphAtom
Atom return value

Description:

Gets the Atom for the specified string. You can also use this method to create an Atom, since it creates one for the string if one does not already exist.

If an Atom already exists for lpString, the existing Atom is returned. Thus Atoms may be compared for equality of the underlying string.

Because Atoms cannot be deleted, they are useful for strings that are used many times, but are not advisable for strings that have a short lifetime. For the same reason, it is not a good idea to create large numbers of Atoms.

Return Value:

Error count.


IG_PDF_atom_get_string

Group: Atom

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_atom_get_string(
HIG_PDF_ATOM hAtom,
LPCSTR *lpString
);

Arguments:

hAtom
The Atom whose string is obtained.
lpString
The string corresponding to hAtom. Returns an empty string if hAtom is equal to IG_PDF_ATOM_NULL or NULL if the hAtom has not been defined.

Description:

Gets the string associated with the specified Atom.

Return Value:

Error count.


HIG_PDF_BOOKMARK

Type: Object

Description:

Handle to a PDF bookmark object, which allows the user to navigate interactively from one part of the document to another. It consists of a tree-structured hierarchy of bookmarks. Each bookmark has:

  • A title that appears on screen
  • An action that specifies what happens when the user clicks on the bookmark

The typical action for a user-created bookmark is to move to another location in the current document or outside of it. Each bookmark in the bookmark tree structure has zero or more children that appear indented on screen, and zero or more siblings that appear at the same indentation level. All bookmarks except the bookmark at the top level of the hierarchy have an one parent, i.e. the bookmark under which it is indented. A bookmark is said to be open, if its children are visible on the screen, and closed, if they are not.

See the section 8.2.2, "Document Outline," in the PDF Reference for more information on bookmarks.

Class Members:

IG_PDF_bookmark_add_child
Adds hChildBookmark as the last child of parent.
IG_PDF_bookmark_add_new_child
Adds a new bookmark to the tree containing hBookmark.
IG_PDF_bookmark_add_next
Adds hNewNext as the new right sibling to hBookmark.
IG_PDF_bookmark_add_new_sibling
Adds a new bookmark to the tree containing hBookmark as the new right sibling.
IG_PDF_bookmark_add_prev
Adds hNewPrev as the new left sibling to hBookmark.
IG_PDF_bookmark_add_subtree
Adds a copy of the bookmark sub-tree source to hBookmark.
IG_PDF_bookmark_delete
Deletes a bookmark object.
IG_PDF_bookmark_find_title
Gets the first bookmark whose title is lpTitle.
IG_PDF_bookmark_get_action
Gets hBookmark's action.
IG_PDF_bookmark_get_color
Gets the color of the specified bookmark.
IG_PDF_bookmark_get_count
Gets the number of open bookmarks in a sub-tree.
IG_PDF_bookmark_get_first_child
Gets hBookmark's first child.
IG_PDF_bookmark_get_flags
Gets the flags of the specified bookmark.
IG_PDF_bookmark_get_indent
Gets the indentation level of a bookmark in its containing tree.
IG_PDF_bookmark_get_last_child
Gets hBookmark's last child.
IG_PDF_bookmark_get_next
Gets hBookmark's next (right) sibling.
IG_PDF_bookmark_get_parent
Gets hBookmark's parent bookmark.
IG_PDF_bookmark_get_prev
Gets hBookmark's previous (left) sibling.
IG_PDF_bookmark_get_title
Gets hBookmark's title.
IG_PDF_bookmark_has_children
Tests whether a bookmark has children.
IG_PDF_bookmark_is_open
Tests whether a bookmark is open.
IG_PDF_bookmark_remove
Removes hBookmark sub-tree from the bookmark tree containing it.
IG_PDF_bookmark_remove_action
Removes hBookmark's action.
IG_PDF_bookmark_set_action
Sets hBookmark 's action.
IG_PDF_bookmark_set_color
Sets hBookmark 's color.
IG_PDF_bookmark_set_flags
Sets the flags of the specified bookmark.
IG_PDF_bookmark_set_open
Opens or closes a bookmark.
IG_PDF_bookmark_set_title
Sets hBookmark's title.
IG_PDF_bookmark_unlink
Unlinks a bookmark from the bookmark tree that contains it.


IG_PDF_bookmark_add_child

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_add_child(
    HIG_PDF_BOOKMARK hBookmark,
    HIG_PDF_BOOKMARK hChildBookmark
    );

Arguments:

hBookmark
The parent of the bookmark being added.
hChildBookmark
The bookmark that will become the last child of hBookmark. hChildBookmark must have been previously unlinked.

Description:

Adds hChildBookmark as the last child of parent, adjusting the tree containing parent appropriately. If parent previously had no children, it is open after the child is added.

Return Value:

Error count.


IG_PDF_bookmark_add_new_child

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_add_new_child(
    HIG_PDF_BOOKMARK hBookmark,
    LPSTR lpszInitialText,
    LPHIG_PDF_BOOKMARK lphChildBookmark
    );

Arguments:

hBookmark
The bookmark to which a new last child is added.
lpszInitialText
The new bookmark's title.
lphChildBookmark
The newly created bookmark.

Description:

Adds a new bookmark to the tree containing hBookmark, as the new last child of hBookmark. If hBookmark previously had no children, it will be open after the child is added.

Return Value:

Error count.


IG_PDF_bookmark_add_next

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_add_next(
    HIG_PDF_BOOKMARK hBookmark,
    HIG_PDF_BOOKMARK hNewNext
    );

Arguments:

hBookmark
The bookmark that will receive a new right sibling.
hNewNext
The bookmark to become the new right sibling of hBookmark. hNewNext must have been previously unlinked.

Description:

Adds hNewNext as the new right sibling to hBookmark.

Return Value:

Error count.


IG_PDF_bookmark_add_new_sibling

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_add_new_sibling(
    HIG_PDF_BOOKMARK hBookmark,
    LPSTR lpszInitialText,
    LPHIG_PDF_BOOKMARK lphSiblingBookmark
    );

Arguments:

hBookmark
The bookmark that will be the left sibling of the new bookmark.
lpszInitialText
The new bookmark's title.
lphSiblingBookmark
The newly created bookmark.

Description:

Adds a new bookmark to the tree containing hBookmark as the new right sibling.

Return Value:

Error count.


IG_PDF_bookmark_add_prev

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_add_prev(
    HIG_PDF_BOOKMARK hBookmark,
    HIG_PDF_BOOKMARK hNewPrev
    );

Arguments:

hBookmark
The bookmark that will receive a new left sibling.
hNewPrev
The bookmark to become the new left sibling of hBookmark. hNewPrev must have been previously unlinked.

Description:

Adds hNewPrev as the new left sibling to hBookmark, adjusting the tree containing hBookmark appropriately.

Return Value:

Error count.


IG_PDF_bookmark_add_subtree

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_add_subtree(
    HIG_PDF_BOOKMARK hBookmark,
    HIG_PDF_BOOKMARK hSubtree,
    LPSTR lpszSourceTitle
    );

Arguments:

hBookmark
The bookmark to which the sub-tree source is added as a new last child.
hSubtree
The bookmark sub-tree to add.
lpszSourceTitle
The new bookmark's title.

Description:

Adds a copy of the bookmark sub-tree source to hBookmark, as a new last child of hBookmark. This

new item will have the text value lpszSourceTitle, will be open, and will have no destination attribute. hSubtree must have been previously unlinked. If hBookmark previously had no children, it will be open after the sub-tree is added.

Return Value:

Error count.


IG_PDF_bookmark_delete

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_delete(
    HIG_PDF_BOOKMARK hBookmark
    );

Arguments:

hBookmark
The bookmark object to delete.

Description:

Deletes a bookmark object.

Return Value:

Error count.


IG_PDF_bookmark_find_title

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_find_title(
    HIG_PDF_BOOKMARK hBookmark,
    LPSTR lpTitle,
    AT_INT nTitleLen,
    AT_INT nMaxDepth,
    LPHIG_PDF_BOOKMARK lphBookmark
    );

Arguments:

hBookmark
The root of the bookmark sub-tree to search.
lpTitle
The text value to search for.
nTitleLen
The length of lpTitle.
nMaxDepth
The number of sub-tree levels to search, not counting the root level.
  • 0 - Only look at hBookmark, not at any of its children.
  • 1 - Check hBookmark and its children, but not any grandchildren or great grandchildren, and so on.
  • -1 - Check the entire sub-tree.
lphBookmark
The bookmark with the specified title or NULL if there is no such bookmark.

Description:

Gets the first bookmark whose title is lpTitle.

Return Value:

Error count.


IG_PDF_bookmark_get_action

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_get_action(
    HIG_PDF_BOOKMARK hBookmark,
    LPHIG_PDF_ACTION lphAction
    );

Arguments:

hBookmark
The bookmark whose action is obtained.
lphAction
The bookmark's action.

Description:

This method gets hBookmark's action.

Return Value:

Error count.


IG_PDF_bookmark_get_color

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_get_color(
    HIG_PDF_BOOKMARK hBookmark,
    LPAT_PDF_COLORVALUE lpBookmarkColor
    );

Arguments:

hBookmark
The bookmark whose color is obtained.
lpBookmarkColor
Color of the bookmark.

Description:

Gets the color of the specified bookmark.

Return Value:

Error count.


IG_PDF_bookmark_get_count

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_get_count(
    HIG_PDF_BOOKMARK hBookmark,
    LPAT_INT lpnCount
    );

Arguments:

hBookmark
The root bookmark of a sub-tree to count.
lpnCount
Number of open bookmarks in the sub-tree (not including hBookmark).

Description:

Gets the number of open bookmarks in a sub-tree.

Return Value:

Error count.


IG_PDF_bookmark_get_first_child

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_get_first_child(
    HIG_PDF_BOOKMARK hBookmark,
    LPHIG_PDF_BOOKMARK lphFirstChild
    );

Arguments:

hBookmark
The bookmark whose first child is obtained.
lphFirstChild
First child of hBookmark or NULL, if hBookmark has no children.

Description:

Gets hBookmark's first child.

Return Value:

Error count.


IG_PDF_bookmark_get_flags

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_get_flags(
    HIG_PDF_BOOKMARK hBookmark,
    LPAT_INT lpnFlags
    );

Arguments:

hBookmark
The bookmark whose flags are obtained.
lpnFlags
Bookmark's flags. The OR value of the enumIGPDFBookmarkFlags.

Description:

Gets the flags of the specified bookmark.

Return Value:

Error count.


IG_PDF_bookmark_get_indent

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_get_indent(
    HIG_PDF_BOOKMARK hBookmark,
    LPAT_INT lpnIndent
    );

Arguments:

hBookmark
The bookmark whose indentation level is obtained.
lpnIndent
The indentation level of hBookmark in its containing tree. The root level has an indentation level of zero.

Description:

Gets the indentation level of a bookmark in its containing tree.

Return Value:

Error count.


IG_PDF_bookmark_get_last_child

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_get_last_child(
    HIG_PDF_BOOKMARK hBookmark,
    LPHIG_PDF_BOOKMARK lphLastChild
    );

Arguments:

hBookmark
The bookmark whose last child is obtained.
lphLastChild
Last child of hBookmark or NULL if hBookmark has no children.

Description:

Gets hBookmark's last child.

Return Value:

Error count.


IG_PDF_bookmark_get_next

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_get_next(
    HIG_PDF_BOOKMARK hBookmark,
    LPHIG_PDF_BOOKMARK lphNext
    );

Arguments:

hBookmark
The bookmark whose right sibling is obtained.
lphNext
hBookmark's next (right) sibling or NULL if hBookmark has no next sibling (it is its parent's last child).

Description:

Gets hBookmark's next (right) sibling.

Return Value:

Error count.


IG_PDF_bookmark_get_parent

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_get_parent(
    HIG_PDF_BOOKMARK hBookmark,
    LPHIG_PDF_BOOKMARK lphParent
    );

Arguments:

hBookmark
The bookmark whose parent is obtained.
lphParent
Parent bookmark of hBookmark or NULL, if hBookmark is the root of its tree.

Description:

Gets hBookmark's parent bookmark.

Return Value:

Error count.


IG_PDF_bookmark_get_prev

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_get_prev(
    HIG_PDF_BOOKMARK hBookmark,
    LPHIG_PDF_BOOKMARK lphPrev
    );

Arguments:

hBookmark
The bookmark whose left sibling is obtained.
lphPrev
Previous (left) sibling of hBookmark or NULL, if hBookmark has no previous sibling (it is its parent's first child).

Description:

Gets hBookmark's previous (left) sibling.

Return Value:

Error count.


IG_PDF_bookmark_get_title

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_get_title(
    HIG_PDF_BOOKMARK hBookmark,
    LPSTR szBuffer,
    AT_INT nSize,
    LPAT_INT lpnBytes
    );

Arguments:

hBookmark
The bookmark whose title is obtained.
szBuffer
Buffer into which the title will be written. If szBuffer is non-NULL, its length is assumed to be nSize + 1, because a null byte is appended to the title.
nSize
The size of szBuffer.
lpnBytes
The number of bytes copied into szBuffer, not counting the trailing null byte. If szBuffer is NULL, the number of bytes in the bookmark is returned.

Description:

Gets hBookmark's title.

Return Value:

Error count.


IG_PDF_bookmark_has_children

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_has_children(
    HIG_PDF_BOOKMARK hBookmark,
    LPAT_PDF_BOOL lpbHasChildren
    );

Arguments:

hBookmark
The bookmark to test.
lpbHasChildren
TRUE if hBookmark has any children, FALSE otherwise.

Description:

This function tests whether a bookmark has children or not.

Return Value:

Error count.


IG_PDF_bookmark_is_open

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_is_open(
    HIG_PDF_BOOKMARK hBookmark,
    LPAT_PDF_BOOL lpbOpen
    );

Arguments:

hBookmark
The bookmark to test.
lpbOpen
TRUE, if hBookmark is open, FALSE otherwise.

Description:

Tests whether a bookmark is open. An open bookmark shows all its children.

Return Value:

Error count.


IG_PDF_bookmark_remove

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_remove(
    HIG_PDF_BOOKMARK hBookmark
    );

Arguments:

hBookmark
The root bookmark of the sub-tree to remove.

Description:

Removes hBookmark sub-tree from the bookmark tree containing it.

Return Value:

Error count.


IG_PDF_bookmark_remove_action

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_remove_action(
    HIG_PDF_BOOKMARK hBookmark
    );

Arguments:

hBookmark
The bookmark whose action is removed.

Description:

Removes hBookmark's action.

Return Value:

Error count.


IG_PDF_bookmark_set_action

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_set_action(
    HIG_PDF_BOOKMARK hBookmark,
    HIG_PDF_ACTION hAction
    );

Arguments:

hBookmark
The bookmark whose action is set.
hAction
The bookmark's action to set.

Description:

Sets hBookmark 's action.

Return Value:

Error count.


IG_PDF_bookmark_set_color

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_set_color(
    HIG_PDF_BOOKMARK hBookmark,
    LPAT_PDF_COLORVALUE lpBookmarkColor
    );

Arguments:

hBookmark
The bookmark whose color is set.
lpBookmarkColor
The bookmark's color to set. Must be in IG_PDF_DEVICE_RGB.

Description:

Sets hBookmark 's color.

Return Value:

Error count.


IG_PDF_bookmark_set_flags

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_set_flags(
    HIG_PDF_BOOKMARK hBookmark,
    AT_INT nFlags
    );

Arguments:

hBookmark
The bookmark whose flags are set.
nFlags
Bookmark's flags. The OR value of the enumIGPDFBookmarkFlags.

Description:

Sets the flags of the specified bookmark.

Return Value:

Error count.


IG_PDF_bookmark_set_open

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_set_open(
    HIG_PDF_BOOKMARK hBookmark,
    AT_PDF_BOOL bIsOpen
    );

Arguments:

hBookmark
The bookmark to open or close.
bIsOpen
TRUE, if the bookmark is opened, FALSE if the bookmark is closed..

Description:

Opens or closes a bookmark. An open bookmark shows its children, while a closed bookmark does not.

Return Value:

Error count.


IG_PDF_bookmark_set_title

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_set_title(
    HIG_PDF_BOOKMARK hBookmark,
    LPCSTR lpTitle,
    AT_INT nTitleLen
    );

Arguments:

hBookmark
The bookmark whose title is set.
lpTitle
String containing the bookmark's new title.
nTitleLen
The size of lpTitle.

Description:

This function sets hBookmark's title.

Return Value:

Error count.


IG_PDF_bookmark_unlink

Group: Bookmark

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_bookmark_unlink(
    HIG_PDF_BOOKMARK hBookmark
    );

Arguments:

hBookmark
The bookmark to unlink.

Description:

Unlinks a bookmark from the bookmark tree that contains it, and adjusts the tree appropriately.

Return Value:

Error count.


HIG_PDF_STREAM

Type: Stream Object

Description:

Handle to the PDF stream object. A data stream that may be a buffer in memory, or an arbitrary user-written procedure. Typically used to extract or provide data.

Class Members:

IG_PDF_stream_open_mem_for_read
Creates a read-only PDF stream from a memory-resident buffer.
IG_PDF_stream_read_CB_register
Creates a read-only PDF stream from an arbitrary data-producing procedure.
IG_PDF_stream_write_CB_register
Creates a PDF stream from an arbitrary data-producing procedure.
IG_PDF_stream_read
Creates a read-only PDF stream from an arbitrary data-producing procedure.
IG_PDF_stream_flush
Flushes any buffered data to the specified stream.
IG_PDF_stream_close
Closes the specified stream.


IG_PDF_stream_open_mem_for_read

Group: Stream

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_stream_open_mem_for_read(
LPSTR lpData,
UINT nLen,
LPHIG_PDF_STREAM lphStream );

Arguments:

lpData
Buffer containing the data to read into the stream. This data buffer must not be disposed of until the stream is closed.
nLen
Length of data, in bytes.
lphStream
Handle to the new stream.

Description:

Creates a read-only PDF stream from a memory-resident buffer. The stream is seek-able.

Return Value:

Error count.


IG_PDF_stream_read_CB_register

Group: Stream

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_stream_read_CB_register(
LPFNIG_PDF_STREAM_PROC lpfnReadProc,
LPVOID lpClientData,
LPHIG_PDF_STREAM lphStream );

Arguments:

lpfnReadProc
User-supplied callback that supplies the stream's data.
lpClientData
Pointer to user-supplied data to pass to lpfnReadProc each time it is called.
lphStream
Handle to the new stream.

Description:

Creates a read-only PDF stream from an arbitrary data-producing procedure. The stream is not seek-able.

lpfnReadProc is called when the client of the stream attempts to read data from it.

Return Value:

Error count.


IG_PDF_stream_write_CB_register

Group: Stream

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_stream_write_CB_register(
LPFNIG_PDF_STREAM_PROC lpfnWriteProc,
LPFNIG_PDF_STREAM_DESTROYPROC lpfnDestroyProc,
LPVOID lpClientData,
LPHIG_PDF_STREAM lphStream );

Arguments:

lpfnWriteProc
User-supplied callback that provides the data for the stream.
lpfnDestroyProc
User-supplied callback that destroys the specified stream.
lpClientData
Pointer to user-supplied data to pass to lpfnWriteProc each time it is called.
lphStream
Handle to the new stream.

Description:

Creates a PDF stream from an arbitrary data-producing procedure. The stream is not seek-able.

Return Value:

Error count.


IG_PDF_stream_read

Group: Stream

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_stream_read(
HIG_PDF_STREAM hStream,
LPSTR lpBuffer,
LONG nItems,
SHORT nItemSize,
LPLONG lpnItemsRead );

Arguments:

hStream
The stream from which data is read.
lpBuffer
Buffer into which data is written.
nItems
Number of items to read. The amount of data read into the memory buffer will be nItems × nItemSize, unless an EOF is encountered first.
The relative values of nItems and nItemSize really do not matter; the only thing that matters is their product. It is often convenient to set nItemSize to 1, so that nItems is the number of bytes to read.
nItemSize
Number of bytes in an item in the stream.
lpnItemsRead
The number of items (not bytes) read.

Description:

Creates a read-only PDF stream from an arbitrary data-producing procedure. The stream is not seek-able.

lpfnReadProc is called when the client of the stream attempts to read data from it.

Return Value:

Error count.


IG_PDF_stream_flush

Group: Stream

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_stream_flush(
HIG_PDF_STREAM hStream,
LPLONG lpnResult );

Arguments:

hStream
The stream to flush.
lpnResult
0 if successful, otherwise non-zero.

Description:

Flushes any buffered data to the specified stream.

Return Value:

Error count.


IG_PDF_stream_close

Group: Stream

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_stream_close(
HIG_PDF_STREAM hStream );

Arguments:

hStream
The stream to close.

Description:

Closes the specified stream.

Return Value:

Error count.


HIG_PDF_DESTINATION

Type: Destination Object

Description:

Handle to a PDF destination object, which represents a particular view of a page in a document. It contains a reference to a page, a rectangle on that page, and information specifying how to adjust the view to fit the window's size and shape. See section 8.2, "Document-Level Navigation," in the PDF Reference for more information on destinations.

Class Members:

IG_PDF_destination_create
Creates a new destination object.
IG_PDF_destination_delete
Deletes a destination object.
IG_PDF_destination_get_explicit_attrs
Gets a destination's fit type, destination rectangle, and zoom factor.
IG_PDF_destination_get_named_attrs
Gets a destination's named attributes.
IG_PDF_destination_get_type
Gets a destination's type.
IG_PDF_destination_remove
Removes a view destination object.
IG_PDF_destination_resolve
Resolves a destination.


IG_PDF_destination_create

Group: Destination

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_destination_create(
    HIG_PDF_DOC hDoc,
    HIG_PDF_PAGE hPage,
    HIG_PDF_ATOM hInitialFitType,
    LPAT_PDF_FIXEDRECT lpInitialRect,
    AT_PDF_FIXED nInitialZoom,
    LPHIG_PDF_DESTINATION lphDest
    );

Arguments:

hDoc
The document in which the destination is used.
hPage
The destination page.
hInitialFitType
Destination fit type. Must be one of the View Destination Fit Types.
lpInitialRect
Pointer to a AT_PDF_FIXEDRECT specifying the destination rectangle, specified in user space coordinates. The appropriate information will be extracted from lpInitialRect, depending on hInitialFitType, to create the destination.
All four of lpInitialRect's components should be set.
nInitialZoom
The zoom factor to set for the destination. Used only if hInitialFitType is XYZ. Use the predefined value IG_PDF_DEST_NULL to indicate a NULL zoom factor.
lphDest
The newly created destination object.

Description:

Creates a new destination object.

Return Value:

Error count.


IG_PDF_destination_delete

Group: Destination

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_destination_delete(
    HIG_PDF_DESTINATION hDest
    );

Arguments:

hDest
The destination object to delete.

Description:

Deletes a destination object.

Return Value:

Error count.


IG_PDF_destination_get_explicit_attrs

Group: Destination

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_destination_get_explicit_attrs(
    HIG_PDF_DESTINATION hDest,
    LPAT_INT lpnPageNum,
    LPHIG_PDF_ATOM lphFitType,
    LPAT_PDF_FIXEDRECT lpRect,
    LPAT_PDF_FIXED lpnZoom
    );

Arguments:

hDest
The destination whose explicit attributes are obtained.
lpnPageNum
The page number of the destination's page..
lphFitType
Destination fit type. One of the Destination Fit Types values.
lpRect
Pointer to a AT_PDF_FIXEDRECT containing the destination's rectangle, specified in user space coordinates.
lpnZoom
The destination's zoom factor.

Description:

Gets a destination's fit type, destination rectangle, and zoom factor. Applies only to IG_PDF_DEST_EXPLICIT type of destination.

Return Value:

Error count.


IG_PDF_destination_get_named_attrs

Group: Destination

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_destination_get_named_attrs(
    HIG_PDF_DESTINATION hDest,
    LPHIG_PDF_BASOBJ lphName
    );

Arguments:

hDest
The destination whose named attributes are obtained.
lphName
Basic array object for the destination. Returns NULL if the destination is invalid.

Description:

Gets a destination's named attributes. Applies only to IG_PDF_DEST_NAMED type of destination.

Return Value:

Error count.


IG_PDF_destination_get_type

Group: Destination

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_destination_get_type(
    HIG_PDF_DESTINATION hDest,
    LPAT_INT lpnType
    );

Arguments:

hDest
The destination whose type is obtained.
lpnType
The destination type. One of the enumIGPDFDestinationType values.

Description:

Gets a destination's type.

Return Value:

Error count.


IG_PDF_destination_remove

Group: Destination

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_destination_remove(
    HIG_PDF_DESTINATION hDest
    );

Arguments:

hDest
The destination to remove.

Description:

Removes a view destination object.

Return Value:

Error count.


IG_PDF_destination_resolve

Group: Destination

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_destination_resolve(
    HIG_PDF_DESTINATION hDest,
    HIG_PDF_DOC hDoc,
    LPHIG_PDF_DESTINATION lphResolvedDest
    );

Arguments:

hDest
The destination whose type is obtained.
hDoc
The PDF document that contains the destination.
lphResolvedDest
The resolved view destination.

Description:

Resolves a destination. hDest is the value of the D key in an action. It can be a real destination (an array) or a name. If it is a name, look it up in hDoc's Dests dictionary. The value found there can be a real destination (an array) or a dictionary. If it's a dictionary, look up the D key in that dictionary. This method is useful for getting an explicit view destination from an action.

Return Value:

Error count.


HIG_PDF_DICTIONARY

Type: Dictionary Object

Desciption:

Handle to a PDF dictionary object, which represents an optional-content membership dictionary object.

Class Members:

IG_PDF_dictionary_create
Creates a new optional-content membership dictionary object in the given document for the given layers and visibility policy.
IG_PDF_dictionary_get_layer
Gets the layer with the specified index in a membership dictionary.
IG_PDF_dictionary_get_layer_count
Gets the number of layers listed in a membership dictionary.
IG_PDF_dictionary_get_unique_id
Returns some 32bit integer that is unique for all Dictionary objects.
IG_PDF_dictionary_get_vis_policy
Gets the optional-content membership dictionary's visibility policy.
IG_PDF_dictionary_release
Releases the native object and frees memory.


IG_PDF_dictionary_create

Group: Dictionary

Declaration:

IG_PDF_dictionary_create(
    HIG_PDF_DOC hDoc,
    LPHIG_PDF_LAYER hLayers,
    AT_INT nLayersCount,
    AT_INT policy,
    LPHIG_PDF_DICTIONARY lphDictionary)

Arguments:

hDoc
The document in which the dictionary is used.
hLayers
Array of layers to be the members of the dictionary.
nLayersCount
The number of layers.
policy
The visibility policy that determines the visibility of content with respect to the ON/OFF state of the layers listed in the dictionary.
lphDictionary
The newly created dictionary object.

Description:

Creates a new optional-content membership dictionary object in the given document for the given layers and visibility policy.

To add layer to the existing dictionary, get the current layers' list, modify it, then create a new dictionary with the new list of layers.

Return Value:

The newly created dictionary object, or NULL if no layers are supplied.


IG_PDF_dictionary_get_layer

Group: Dictionary

Declaration:

IG_PDF_dictionary_get_layer(
    HIG_PDF_DICTIONARY hDictionary,
    UINT nIndex,
    LPHIG_PDF_LAYER lpLayer)

Arguments:

hDictionary
The membership dictionary whose layer is obtained.
nIndex
The index of the needed layer in the dictionary.
lpLayer
The layer object.

Description:

Gets the layer with the specified index in a membership dictionary.

Return Value:

Layer object.


IG_PDF_dictionary_get_layer_count

Group: Dictionary

Declaration:

IG_PDF_dictionary_get_layer_count(
    HIG_PDF_DICTIONARY hDictionary,
    LPUINT lpnCount)

Arguments:

hDictionary
The membership dictionary whose layers count is obtained.
lpnCount
The count of the document's layers.

Description:

Gets the number of layers listed in a membership dictionary.

Return Value:

The count of the document's layers.


IG_PDF_dictionary_get_unique_id

Group: Dictionary

Declaration:

IG_PDF_dictionary_get_unique_id(
    HIG_PDF_DICTIONARY hDictionary,
    LPUINT lpnUniqueId)

Arguments:

hDictionary
Dictionary object.
lpnUniqueId
The unique identifier.

Description:

Returns some 32bit integer that is unique for all Dictionary objects. In other words, it is guaranteed that there cannot be two Dictionary objects with the same UniqueIds.

Can be used for Dictionary objects' identification.

Return Value:

An unique identifier of this Dictionary Object.


IG_PDF_dictionary_get_vis_policy

Group: Dictionary

Declaration:

IG_PDF_dictionary_get_vis_policy(
    HIG_PDF_DICTIONARY hDictionary,
    LPAT_INT lpPolicy)

Arguments:

hDictionary
The dictionary whose policy is obtained.
lpPolicy
The visibility policy.

Description:

Gets the optional-content membership dictionary's visibility policy, which determines the visibility of content with respect to the ON-OFF state of the layers listed in the dictionary.

Return Value:

The visibility policy.


IG_PDF_dictionary_release

Group: Dictionary

Declaration:

IG_PDF_dictionary_release(
    HIG_PDF_DICTIONARY hDictionary)

Arguments:

hDictionary
Dictionary object to release.

Description:

Releases the native object and frees memory.

Return Value:

Nothing.


HIG_PDF_DOC

Type: Document Object

Description:

Handle to the PDF document object. The underlying PDF representation of a document. Through PDF Document, your application can perform most of the Edit Pages operations (delete, replace, and so on). Thumbnails can be created and deleted through this object. You can set and retrieve document information fields through this object as well.

Class Members:

IG_PDF_doc_create
This function creates a PDF document and attaches it to HMIGEAR.
IG_PDF_doc_create_new_page
This function creates a new PDF page for the hMPIDoc.
IG_PDF_doc_delete_pages
Deletes the specified pages.
IG_PDF_doc_insert_pages
This function inserts nPageCount pages from hDoc2 into hDoc.
IG_PDF_doc_get_bookmark
Gets the root of the document's bookmark tree.
IG_PDF_doc_get_info
Gets the value of a key in a document's Info dictionary, or the value of this same key in the XMP metadata, whichever is latest.
IG_PDF_doc_get_layer
Gets the layer with a specified index.
IG_PDF_doc_get_layer_count
Gets the layer count for the document.
IG_PDF_doc_get_page_count
Gets the number of pages in the document.
IG_PDF_doc_get_root
Returns the Catalog dictionary of the PDF document
IG_PDF_doc_set_info
Sets the value of a key in a document's Info dictionary.
IG_PDF_doc_print
Prints PDF pages from a PDF document allowing the user to specify options such as page size, rotation, fit mode.
IG_PDF_doc_create_wordfinder
Creates a word finder that is used to extract text in the host encoding from a PDF file.
IG_PDF_doc_create_wordfinder_ucs
Creates a word finder that is used to extract text in the host encoding from a PDF file.
IG_PDF_doc_get_new_crypt_handler
Gets the specified document's new security handler (that is, the security handler that will be used after the document is saved).
IG_PDF_doc_get_new_security_data
Gets the security data structure for the specified document's new security handler.
IG_PDF_doc_get_new_security_info
Gets the security information from the specified document's new security handler.
IG_PDF_doc_get_security_data
Gets the security data structure for the specified document's new security handler.
IG_PDF_doc_perm_request
Checks the permissions associated with the specified document using the latest permissions format, and determines whether the requested operation is allowed for the specified object in the document.
IG_PDF_doc_set_new_crypt_handler
Sets specified document's new security handler (the security handler that will be used after the document is saved).
IG_PDF_doc_set_new_security_data
Sets the security data structure for the specified document's new security handler.


IG_PDF_doc_create

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_create(
HMIGEAR hMPIDoc);

Arguments:

hMPIDoc
ImageGear document to attach a PDF document to

Description:

This function creates a PDF document and attaches it to HMIGEAR. Doesn't do anything in case if hMPIDoc is already vector document.

To obtain a handle to the PDF document use:

    HIG_PDF_DOC hPDFDoc = (HIG_PDF_DOC)NULL;
    IG_mpi_info_get( hMPIDoc, IG_MP_DOCUMENT, &hPDFDoc,
sizeof(hPDFDoc) );

Return Value:

Error count.


IG_PDF_doc_create_new_page

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_create_new_page(
HMIGEAR hMPIDoc,
LONG nAfterPage,
LPAT_PDF_FIXEDRECT lpMediaBox );

Arguments:

hMPIDoc
The document in which the page is created.
nAfterPage
The page number after which the new page is inserted. The first page is 0. Use IG_PDF_BEFORE_FIRST_PAGE to insert the new page at the beginning of a document.
lpMediaBox
Rectangle specifying the page's media box, specified in user space coordinates.

Description:

This function creates a new PDF page for the hMPIDoc. The new PDF page is created at the specified position.

NOTE: The previous value (if any) is not deleted with the IG_image_delete function. The size of the multi-page image is not changed, so that page arrays is not expanded when nAfterPage is greater than pageCount-1.

To obtain a handle to the PDF page use:

HIGEAR hNewPage = NULL;
IG_mpi_page_get(m_hMPDoc, nAfterPage+1, &hNewPage);
HIG_PDF_PAGE hNewPDFPage = NULL;
IG_vector_data_get( hNewPage, (LPVOID*)&hNewPDFPage );

Return Value:

Error count.


IG_PDF_doc_delete_pages

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_delete_pages(
    HIG_PDF_DOC hDoc,
    LONG nStartPage,
    LONG nPageCount
    );

Arguments:

hDoc
The document from which pages are deleted.
nStartPage
The page number of the first page to delete. The first page is 0.
nPageCount
The number of pages to delete.

Description:

Deletes the specified pages.

Return Value:

Error count.


IG_PDF_doc_insert_pages

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_insert_pages(
    HIG_PDF_DOC hDoc,
    LONG nAfterThisPage,
    HIG_PDF_DOC hDoc2,
    LONG nStartPage,
    LONG nPageCount,
    WORD nInsertFlags
    );

Arguments:

hDoc
The document into which pages are inserted.
nAfterThisPage
The page number in hDoc after which pages from hDoc2 are inserted. The first page is 0. If IG_PDF_BEFORE_FIRST_PAGE is used, the pages are inserted before the first page in hDoc . Use IG_PDF_LAST_PAGE to insert pages after the last page in hDoc.
hDoc2
The document containing the pages that are inserted into hDoc.
nStartPage
The page number of the first page in hDoc2 to insert into hDoc. The first page is 0.
nPageCount
The number of pages in hDoc2 to insert into hDoc. Use IG_PDF_ALL_PAGES to insert all pages from hDoc2 into hDoc.
nInsertFlags
Flags that determine what additional information is copied from hDoc2 into hDoc. An OR of enumIGPDFInsertFlags constants:
  • IG_PDF_INSERT_BOOKMARKS - Inserts bookmarks as well as pages. The bookmark tree of hDoc2 is merged into the bookmark tree of hDoc by copying it as a new first-level subtree of hDoc's bookmark tree root, of which it becomes the last child. If hDoc has no bookmark tree, it acquires one identical to the bookmark tree from hDoc2.
  • IG_PDF_INSERT_THREADS - Inserts threads as well as pages.
  • IG_PDF_INSERT_ALL - Inserts document data from pages.

Description:

This function inserts nPageCount pages from hDoc2 into hDoc. All annotations, and anything else associated with the page (such as a thumbnail image) are copied from the hDoc2 pages to the new pages in hDoc. This method does not insert pages, if hDoc is equal to hDoc2. The nInsertFlags controls whether bookmarks and threads are inserted along with the specified pages.

Return Value:

Error count.


IG_PDF_doc_get_bookmark

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_get_bookmark(
    HIG_PDF_DOC hDoc,
    LPHIG_PDF_BOOKMARK lphRootBookmark
    );

Arguments:

hDoc
The document whose root bookmark is obtained.
lphRootBookmark
The document's root bookmark.

Description:

Gets the root of the document's bookmark tree. The lphRootBookmark value is valid even if document's bookmark tree is empty.

Return Value:

Error count.


IG_PDF_doc_get_info

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_get_info(
HIG_PDF_DOC hDoc,
LPCSTR szInfoKey,
LPSTR szBuffer,
LONG nSize,
LPLONG lpnBytes);

Arguments:

hDoc
The document whose Info dictionary key is obtained.
szInfoKey
The name of the Info dictionary key whose value is obtained.
szBuffer
Result buffer containing the value associated with infoKey. If buffer is NULL, the method will just return the number of bytes required.
nSize
The maximum number of bytes that can be written into buffer.
lpnBytes
If szBuffer is NULL, the number of bytes in the specified key's value. If szBuffer is not NULL, returns the number of bytes copied into buffer, excluding the terminating NULL. You must pass at least the length + 1 as the buffer size since the routine adds a '\0' terminator to the data, even though the data is not a C string (it can contain embedded '\0's).

Description:

Gets the value of a key in a document's Info dictionary, or the value of this same key in the XMP metadata, whichever is latest.

See Section 10.2.1 in the PDF Reference for information about Info dictionaries. All values in the Info dictionary should be strings; other data types such as numbers and Booleans should not be used as values in the Info dictionary.

Users may define their own Info dictionary entries. In this case, it is strongly recommended that the key have the developer's prefix assigned by the Adobe Solutions Network.

Return Value:

Error count.


IG_PDF_doc_get_layer

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_get_layer(
    HIG_PDF_DOC hDoc,
    UINT nIndex,
    LPHIG_PDF_LAYER lphLayer
    );

Arguments:

hDoc
Document whose layer is obtained.
nIndex
Index of the layer to obtain
lphLayer
obtained layer

Description:

Gets the layer with a specified index.

Return Value:

Error count.


IG_PDF_doc_get_layer_count

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_get_layer_count(
    HIG_PDF_DOC hDoc,
    LPUINT lpnCount
    );

Arguments:

hDoc
Document whose layer count is obtained.
lpnCount
Layer count

Description:

Gets the layer count for the document.

Return Value:

Error count.


IG_PDF_doc_get_page_count

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_get_page_count(
    HIG_PDF_DOC hDoc,
    LPUINT lpnCount
    );

Arguments:

hDoc
The document for which the number of pages is obtained.
lpnCount
The number of pages in the document.

Description:

Gets the number of pages in the document.

Return Value:

Error count.


IG_PDF_doc_get_root

Group: Document

Declaration:

AT_VOID IG_PDF_doc_get_root(
HIG_PDF_DOC hDoc,
LPHIG_PDF_BASOBJ lphRootDictionary
);

Parameters:

hDoc
The PDF document
lphRootDictionary
The resulting Catalog dictionary.

Description:

This method returns the Catalog dictionary of the PDF document (this Catalog dictionary is the root of a PDF document`s object hierarchy).

See also the PDF Reference, ch.3.6.


IG_PDF_doc_set_info

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_set_info(
HIG_PDF_DOC hDoc,
LPCSTR szInfoKey,
LPSTR szBuffer,
LONG nSize);

Arguments:

hDoc
The document whose Info dictionary key is set.
szInfoKey
The name of the Info dictionary key whose value is set.
szBuffer
Buffer containing the value to associate with szInfoKey.
nSize
The number of bytes in buffer.

Description:

Sets the value of a key in a document's Info dictionary.

See Section 10.2.1 on Info dictionaries in the PDF Reference for information about Info dictionaries. All values in the Info dictionary should be strings; other data types such as numbers and Booleans should not be used as values in the Info dictionary. If an info dictionary key is specified that is not currently in the info dictionary, it is added to the dictionary.

Return Value:

Error count.


IG_PDF_doc_print

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_print(
HIG_PDF_DOC hDoc,
LPAT_PDF_PRINTOPTIONS lpPrintOptions);

Arguments:

hDoc
Handle to the document to print
lpPrintOptions
Parameters to control printing

Description:

Prints PDF pages from a PDF document allowing the user to specify options such as page size, rotation, fit mode.

Return Value:

Error count.


IG_PDF_doc_create_wordfinder

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_create_wordfinder(HIG_PDF_DOC
hDoc ,LPWORD lpOutEncInfo, LPCHAR *lpOutEncVec, LPCHAR
*lpLigatureTbl, SHORT nAlgVersion, WORD nFlags, LPVOID
lpClientData, LPHIG_PDF_WORDFINDER lphWordFinder )

Arguments:

hDoc
The document on which the word finder is used.
lpOutEncInfo
Array of 256 flags, specifying the type of character at each position in the encoding. Each flag is an OR of the Character Type Codes.
If lpOutEncInfo is NULL, the platform's default encoding info is used. Use lpOutEncInfo and lpOutEncVec together; for every lpOutEncInfo use a corresponding lpOutEncVec to specify the character at that position in the encoding.
lpOutEncVec
Array of 256 null-terminated strings that are the glyph names in encoding order. See the discussion of character names in Section 5.3 of the PostScript Language Reference Manual, Third Edition.
If lpOutEncVec is NULL, the platform's default encoding vector is used.
Use this parameter with lpOutEncInfo.
lpLigatureTbl
A null-terminated array of null-terminated strings. Each string is the glyph name of a ligature in the font. When a word contains a ligature, the glyph name of the ligature is substituted for the ligature (for example, ff is substituted for the ff ligature).
If ligatureTbl is NULL, a default ligature table is used, containing the following ligatures: fi, ff, fl, ffi, ffl, ch, cl, ct, ll, ss, fs, st, oe, OE.
nAlgVersion
The version of the word-finding algorithm to use.
nFlags
Word-finding options that determine the tables filled when using IG_PDF_wordfinder_acquire_word_list. Must be an OR of one or more of enumIGPDFWordFlags.
lpClientData
Pointer to user-supplied data to pass to the newly created word finder. Set to NULL.
lphWordFinder
Handle to the new WordFinder

Description:

Creates a word finder that is used to extract text in the host encoding from a PDF file.

NOTE: The word finder also extracts text from Form XObjects that are executed in the page contents. For information about Form XObjects, see Section 4.9 in the PDF Reference.

This method also works for non-Roman (CJK or Chinese-Japanese-Korean) viewers. In this case, words are extracted to the host encoding. Users desiring Unicode output must use IG_PDF_doc_create_wordfinder_ucs, which does the extraction for Roman or non-Roman text.

The type of WordFinder determines the encoding of the string returned by IG_PDF_word_get_string. For instance, if IG_PDF_doc_create_wordfinder_ucs is used to create the word finder, IG_PDF_word_get_string returns only Unicode.

For CJK viewers, words are stored internally using CID encoding. For more information on CIDFonts and related topics, see Section 5.6 in the PDF Reference. For detailed information on CIDFonts, see Technical Note #5092, CID-Keyed Font Technology Overview, and Technical Note #5014, Adobe CMap and CIDFont Files Specification.

Return Value:

Error count.


IG_PDF_doc_create_wordfinder_ucs

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI
IG_PDF_doc_create_wordfinder_ucs(HIG_PDF_DOC hDoc, SHORT
nAlgVersion, WORD nFlags, LPVOID lpClientData,
LPHIG_PDF_WORDFINDER lphWordFinder )

Arguments:

hDoc
The document on which the word finder is used.
nAlgVersion
The version of the word-finding algorithm to use.
nFlags
Word-finding options that determine the tables filled when using IG_PDF_wordfinder_acquire_word_list. Must be an OR of one or more of enumIGPDFWordFlags.
lpClientData
Pointer to user-supplied data to pass to the newly created word finder. Set to NULL.
lphWordFinder
Handle to the new WordFinder.

Description:

Creates a word finder that is used to extract text in the host encoding from a PDF file.

NOTE: The word finder also extracts text from Form XObjects that are executed in the page contents. For information about Form XObjects, see Section 4.9 in the PDF Reference.

This method also works for non-Roman (CJK or Chinese-Japanese-Korean) viewers. In this case, words are extracted to the host encoding. Users desiring Unicode output must use IG_PDF_doc_create_wordfinder_ucs, which does the extraction for Roman or non-Roman text.

The type of WordFinder determines the encoding of the string returned by IG_PDF_word_get_string. For instance, if IG_PDF_doc_create_wordfinder_ucs is used to create the word finder, IG_PDF_word_get_string returns only Unicode.

For CJK viewers, words are stored internally using CID encoding. For more information on CIDFonts and related topics, see Section 5.6 in the PDF Reference. For detailed information on CIDFonts, see Technical Note #5092, CID-Keyed Font Technology Overview, and Technical Note #5014, Adobe CMap and CIDFont Files Specification.

Return Value:

Error count.


IG_PDF_doc_get_new_crypt_handler

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_get_new_crypt_handler(
    HIG_PDF_DOC hDoc,
    LPHIG_PDF_ATOM lphCryptHandler
    );

Arguments:

hDoc
The document whose new security handler is obtained.
lphCryptHandler
The PDF atom corresponding to the name of the document's new security handler. Returns IG_PDF_ATOM_NULL if the document does not have a new security handler.

Description:

Gets the specified document's new security handler (that is, the security handler that will be used after the document is saved). If the document does not have a new security handler, returns the document's current security handler.

Return Value:

Error count.


IG_PDF_doc_get_new_security_data

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_get_new_security_data(
    HIG_PDF_DOC hDoc,
    LPAT_PDF_SECURITYDATA* lppSecData
    );

Arguments:

hDoc
The document whose new security data structure is obtained.
lppSecData
The security data structure for the document's new security handler.

Description:

Gets the security data structure for the specified document's new security handler. Use IG_PDF_doc_get_security_data to get the security data structure for the document's current security handler.

NOTE: The password strings in PDF are padded or truncated to exactly 32 bytes. If the password string is more than 32 bytes long, used only its first 32 bytes; if it is less than 32 bytes long, it padded by appending the required number of additional bytes from the beginning of the following padding string: < 28 BF 4E 5E 4E 75 8A 41 64 00 4E 56 FF FA 01 08 2E 2E 00 B6 D0 68 3E 80 2F 0C A9 FE 64 53 69 7A >

Return Value:

Error count.


IG_PDF_doc_get_new_security_info

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_get_new_security_info(
    HIG_PDF_DOC hDoc,
    LPUINT lpnSecInfo
    );

Arguments:

hDoc
The document whose new security information is obtained.
lpnSecInfo
The document's new security information. The OR value of the enumIGPDFSecurityInfoFlags.

Description:

Gets the security information from the specified document's new security handler. No permissions are required to call this method.

Return Value:

Error count.


IG_PDF_doc_get_security_data

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_get_security_data(
    HIG_PDF_DOC hDoc,
    LPAT_PDF_SECURITYDATA* lppSecData
    );

Arguments:

hDoc
The document whose security data structure is obtained.
lppSecData
A pointer to the document's current security data structure.

Description:

Gets the security data structure for the specified document's current security handler. Use IG_PDF_doc_get_new_security_data to get the data structure for the document's new security handler.

NOTE: The password strings in PDF are padded or truncated to exactly 32 bytes. If the password string is more than 32 bytes long, used only its first 32 bytes; if it is less than 32 bytes long, it padded by appending the required number of additional bytes from the beginning of the following padding string: < 28 BF 4E 5E 4E 75 8A 41 64 00 4E 56 FF FA 01 08 2E 2E 00 B6 D0 68 3E 80 2F 0C A9 FE 64 53 69 7A >

Return Value:

Error count.


IG_PDF_doc_perm_request

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_perm_request(
    HIG_PDF_DOC hDoc,
    UINT nReqObj,
    UINT nReqOpr,
    LPVOID lpAuthData,
    LPSHORT lpnReqStatus
    );

Arguments:

hDoc
The document whose permissions are being requested.
nReqObj
The target object of the permissions request.
nReqOpr
The target operation of the permissions request.
lpAuthData
A pointer to an authorization data (password string).
lpnReqStatus
One of enumIGPDFPermReqStatus request status constants.

Description:

Checks the permissions associated with the specified document using the latest permissions format, and determines whether the requested operation is allowed for the specified object in the document.

Return Value:

Error count.


IG_PDF_doc_set_new_crypt_handler

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_set_new_crypt_handler(
    HIG_PDF_DOC hDoc,
    HIG_PDF_ATOM hNewCryptHandler
    );

Arguments:

hDoc
The document whose new security handler is set.
hNewCryptHandler
The PDF atom for the name of the new security handler to use for the document. Use IG_PDF_ATOM_NULL to remove security from the document.

Description:

Sets specified document's new security handler (the security handler that will be used after the document is saved). This method returns with no action if the new security handler is the same as the old one.

Return Value:

Error count.


IG_PDF_doc_set_new_security_data

Group: Document

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_doc_set_new_security_data(
    HIG_PDF_DOC hDoc,
    LPAT_PDF_SECURITYDATA lpSecData
    );

Arguments:

hDoc
The document whose new security data structure is set.
lppSecData
Pointer to the new security data structure to set for doc.

Description:

Sets the security data structure for the specified document's new security handler. The new security handler must have been previously set using IG_PDF_doc_set_new_crypt_handler.

Return Value:

Error count.


HIG_PDF_FONT

Type: Font Object

Description:

Handle to a PDF font object that is used to draw text on a page. A HIG_PDF_FONT has a number of attributes, including an array of widths, the character encoding.

Class Members:

IG_PDF_font_get_bbox
Gets a Type 3 font's bounding box
IG_PDF_font_get_charset
Gets the font's character set.
IG_PDF_font_get_cid_systeminfo
Gets Registry and Ordering information for a CIDFont.
IG_PDF_font_get_cid_system_supplement
Gets the SystemSupplement number of a CIDFont.
IG_PDF_font_get_descendant
Gets a Type 0 font's descendant
IG_PDF_font_get_encoding_index
Gets a font's encoding index.
IG_PDF_font_get_encoding_name
Gets a string representing a font's encoding.
IG_PDF_font_get_font_matrix
Gets a font's matrix
IG_PDF_font_get_metrics
Gets a font's metrics
IG_PDF_font_get_name
Gets the name of a font.
IG_PDF_font_get_subtype
Gets a font's subtype.
IG_PDF_font_get_widths
Gets the advance width of every glyph in a font.
IG_PDF_font_is_embedded
Tests whether the specified font is embedded in the PDF file
IG_PDF_font_set_metrics
Sets a font's metrics
IG_PDF_font_translate_string
Translates a string from the hFont's encoding into host encoding.
IG_PDF_font_translate_to_host
Translates a string from the hFont's encoding to host encoding.
IG_PDF_font_translate_to_ucs
Translates a string from whatever encoding the hFont uses to Unicode encoding.
IG_PDF_font_translate_widths
Translates an array of 256 glyph advance widths from their order in the PDF file into host encoding order.


IG_PDF_font_get_bbox

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_get_bbox(
    HIG_PDF_FONT hFont,
    LPAT_PDF_FIXEDRECT lpBBox
    );

Arguments:

hFont
the font whose bounding box is obtained.
lpBBox
the font's bounding box

Description:

Gets a Type 3 font's bounding box, which is the smallest rectangle that would enclose every character in the font if they were overlaid and painted.


IG_PDF_font_get_charset

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_get_charset(
    HIG_PDF_FONT hFont,
    LPAT_INT lpCharSet
    );

Arguments:

hFont
the font whose character set is obtained
lpCharSet
the font's character set

Description:

Gets the font's character set. For non-Roman character set viewers, call IG_PDF_font_get_encoding_name()instead.


IG_PDF_font_get_cid_systeminfo

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_get_cid_systeminfo(
    HIG_PDF_FONT hFont,
    LPHIG_PDF_ATOM lphCIDSystemInfo
    );

Arguments:

hFont
the font whose Registry and Ordering information is obtained
lphCIDSystemInfo
CIDFont's Registry and Ordering information.

Description:

Gets Registry and Ordering information for a CIDFont. IG_PDF_font_get_cid_systeminfo()takes either a Type 0 font or descendant font (CIDType0 or CIDType2) as an argument. This information is always present for any Type 0 font; the actual registry ordering information is a part of the descendant font.


IG_PDF_font_get_cid_system_supplement

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_get_cid_system_supplement(
    HIG_PDF_FONT hFont,
    LPLONG lpCIDSystemSupplement
    );

Arguments:

hFont
the font whose SystemSupplement field is obtained
lpCIDSystemSupplement
the SystemSupplement field from the CIDFont

Description:

Gets the SystemSupplement number of a CIDFont.


IG_PDF_font_get_descendant

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI (
    HIG_PDF_FONT hFont,
    LPHIG_PDF_FONT lphFont
    );

Arguments:

hFont
the font whose descendant is obtained
lphFont
the font's descendant font

Description:

Gets a Type 0 font's descendant, which may be a CIDType0 or CIDType2 font.


IG_PDF_font_get_encoding_index

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_get_encoding_index(
    HIG_PDF_FONT hFont,
    LPLONG lpIndex
    );

Arguments:

hFont
the font whose encoding index is obtained
lpIndex
a font encoding index.

Description:

Gets a font's encoding index. For non-Roman character set viewers, it is not appropriate to call this method. Call IG_PDF_font_get_encoding_name() instead.


IG_PDF_font_get_encoding_name

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_get_encoding_name(
    HIG_PDF_FONT hFont,
    LPBYTE *EncodingName
    );

Arguments:

hFont
the font whose encoding name is obtained
EncodingName
string representing the font's encoding

Description:

Gets a string representing a font's encoding. Use IG_PDF_font_get_encoding_index() to get encoding information for Roman viewers.


IG_PDF_font_get_font_matrix

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_get_font_matrix(
    HIG_PDF_FONT hFont,
    LPAT_PDF_FIXEDMATRIX lpMatrix
    );

Arguments:

hFont
the font whose matrix is obtained
lpMatrix
font's matrix

Description:

Gets a font's matrix, which specifies the transformation from character space to text space. This is only valid for Type 3 fonts.


IG_PDF_font_get_metrics

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_get_metrics(
    HIG_PDF_FONT hFont,
    LPAT_PDF_FONT_METRICS lpFontMetrics
    );

Arguments:

hFont
the font whose metrics are obtained
lpFontMetrics
the font's metrics

Description:

Gets a font's metrics, which provide the information needed to create a substitute multiple master font when the original font is unavailable.


IG_PDF_font_get_name

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_get_name(
    HIG_PDF_FONT hFont,
    LPSTR buffer,
    LONG bufSize,
    LPLONG lpCharacterNum
    );

Arguments:

hFont
the font whose name is obtained
buffer
buffer into which the font's name is stored. The client may pass NULL to obtain the buffer size, then call the method with a buffer of the appropriate size.
bufSize
length of buffer, in bytes.
lpCharacterNum
the number of characters in the font name.

Description:

Gets the name of a font. The behavior depends on the font type; for a Type 3 font it gets the value of the Name key in a PDF Font resource. For other types it gets the value of the BaseFont key in a PDF font resource.


IG_PDF_font_get_subtype

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_get_subtype(
    HIG_PDF_FONT hFont,
    LPHIG_PDF_ATOM lphSubType
    );

Arguments:

hFont
the font whose subtype is obtained
lphSubType
the font's subtype

Description:

Gets a font's subtype.


IG_PDF_font_get_widths

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_get_widths(
    HIG_PDF_FONT hFont,
    LPSHORT lpWidths
    );

Arguments:

hFont
the font whose glyph advance widths are obtained
lphSubType
An array of glyph advance widths, measured in character space units. Unencoded code points will have a width of zero. For non-Roman character set viewers, an array for a single byte range (0 through 255).

Description:

Gets the advance width of every glyph in a font. The advance width is the amount by which the current point advances when the glyph is drawn. The advance width may not correspond to the visible width of the glyph (for example, a glyph representing an accent mark might have an advance width of zero so that characters can be drawn under it). For this reason, the advance width cannot be used to determine the glyphs' bounding boxes. For non-Roman character set viewers, this method gets the width for a single byte range (0 through 255).


IG_PDF_font_is_embedded

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_is_embedded(
    HIG_PDF_FONT hFont,
    LPAT_PDF_BOOL lpbIsEmbedded
    );

Arguments:

hFont
the font to test
lpbIsEmbedded
returns true if the font is embedded in the file, false otherwise

Description:

Tests whether the specified font is embedded in the PDF file (that is, the font is stored as a font file, which is a stream embedded in the PDF file). Only Type 1 and TrueType fonts can be embedded.


IG_PDF_font_set_metrics

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_set_metrics(
    HIG_PDF_FONT hFont,
    LPAT_PDF_FONT_METRICS lpFontMetrics
    );

Arguments:

hFont
the font whose metrics are being set
lpFontMetrics
Pointer to a AT_PDF_FONT_METRICS structure containing the font's metrics

Description:

Sets a font's metrics, which provide the information needed to create a substitute multiple master font when the original font is unavailable. This method can only be used on Type 1, multiple master Type 1, and TrueType fonts; it cannot be used on Type 3 fonts.


IG_PDF_font_translate_string

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_translate_string(
    HIG_PDF_FONT hFont,
    LPSTR inP,
    LPSTR outP,
    LONG len,
    LPAT_PDF_BOOL lpbTableExists
    );

Arguments:

hFont
the font (and hence, encoding) that inP uses
inP
the string to translate
outP
the translated string. outP may point to the same buffer as inP, to allow inplace translation
len
the length of inP and outP
lpbTableExists
returns true if an XlateTable exists in the font, false otherwise. If no XlateTable exists in the font, outP is not written

Description:

Translates a string from the hFont's encoding into host encoding. If any characters cannot be represented in host encoding, they are replaced with space characters. If no XlateTable exists in the font, the function returns false and outP is not written. For non-Roman character set viewers, it is not appropriate to call this method.


IG_PDF_font_translate_to_host

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_translate_to_host(
    HIG_PDF_FONT hFont,
    LPSTR inP,
    LONG inLen,
    LPSTR outP,
    LONG outLen,
    LPLONG lpLen
    );

Arguments:

hFont
the font used in the input string inP
inP
pointer to the string to translate
inLen
length of the inP buffer, in bytes
outP
pointer to the translated string
outLen
the length of the outP buffer, in bytes
lpLen
number of bytes in the translated string outP

Description:

Translates a string from the hFont's encoding to host encoding.


IG_PDF_font_translate_to_ucs

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_translate_to_ucs(
    HIG_PDF_FONT hFont,
    LPSTR inP,
    LONG inLen,
    LPSTR outP,
    LONG outLen,
    LPLONG lpLen
    );

Arguments:

hFont
the font of the input string inP
inP
pointer to the string to translate
inLen
length of the inP buffer, in bytes
outP
pointer to the translated string
outLen
the length of the outP buffer, in bytes
lpLen
number of bytes in the translated string outP

Description:

Translates a string from whatever encoding the hFont uses to Unicode encoding.


IG_PDF_font_translate_widths

Group: Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_font_translate_widths(
    HIG_PDF_FONT hFont,
    LPSHORT inP,
    LPSHORT outP
    );

Arguments:

hFont
the font whose glyph widths are translated
inP
array of glyph advance widths to rearrange
outP
rearranged array of glyph advance widths

Description:

Translates an array of 256 glyph advance widths from their order in the PDF file into host encoding order. If the widths are already in host encoding order, the widths are merely copied. All un-encoded code points are given a width of zero. For non-Roman character set viewers, it is not appropriate to call this method.


HIG_PDF_LAYER

Type: Page Object

Description:

Handle to the PDF layer object which represents a named object whose state can be toggled in a UI to affect changes in visibility of content.

Class Members:

IG_PDF_layer_create
Creates new layer (optional-content group) object in the document.
IG_PDF_layer_get_name
Gets the layer name
IG_PDF_layer_set_name
Sets the new layer name
IG_PDF_layer_get_current_state
Gets the current ON-OFF state of the layer object
IG_PDF_layer_set_current_state
Sets the current ON-OFF state of the layer object
IG_PDF_layer_get_initial_state
Gets the initial ON-OFF state of the layer object
IG_PDF_layer_set_initial_state
Sets the initial ON-OFF state of the layer object
IG_PDF_layer_has_usage_info
Tests whether a layer object is associated with a Usage dictionary
IG_PDF_layer_get_usage_info
Gets usage information from a layer object
IG_PDF_layer_set_usage_info
Sets a Usage dictionary entry in a layer object.
IG_PDF_layer_get_intent
Gets the intent list for a layer.
IG_PDF_layer_set_intent
Sets the Intent entry in a layer's dictionary.
IG_PDF_layer_get_unique_id
Sets a unique ID.
IG_PDF_layer_delete
Deletes a PDF layer object.
IG_PDF_layer_release
Releases a layer object.
IG_PDF_layer_remove
Destroys layer (optional-content group) object.


IG_PDF_layer_create

Group: Layer

Declaration:

IG_PDF_layer_create(
    HIG_PDF_DOC hDoc,
    LPSTR lpTextBuf,
    AT_DWORD nTextLen,
    LPHIG_PDF_LAYER lphLayer)

Arguments:

hDoc
The document in which the group is used.
lpTextBuf
The name of the layer.
nTextLen
Length of the lpTextBuf.
lphLayer
The newly created group object.

Description:

Creates new layer (optional-content group) object in the document.

Return Value:

The newly created group object.


IG_PDF_layer_get_name

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_get_name(
    HIG_PDF_LAYER hLayer,
    LPSTR lpTextBuf,
    UINT nBufSize,
    LPUINT lpnTextLen
    );

Arguments:

hLayer
layer whose name is obtained
lpTextBuf
pointer to a buffer for text string
nBufSize
maximum size of the buffer
lpnTextLen
Actual length of the name string copied into the buffer

Description:

This function gets the layer name.

Return Value:

Error count.


IG_PDF_layer_set_name

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_set_name(
    HIG_PDF_LAYER hLayer,
    LPSTR lpTextBuf,
    UINT nTextLen
    );

Arguments:

hLayer
layer whose name is set
lpTextBuf
pointer to a string buffer
nBufSize
length of the string buffer

Description:

This function sets the new layer name.

Return Value:

Error count.


IG_PDF_layer_get_current_state

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_get_current_state(
    HIG_PDF_LAYER hLayer,
    LPAT_PDF_BOOL lpbState
    );

Arguments:

hLayer
Layer whose current state is obtained.
lpbState
Returns TRUE if the state is ON, FALSE if it is OFF.

Description:

This function gets the current ON-OFF state of the layer object.

Return Value:

Error count.


IG_PDF_layer_set_current_state

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_set_current_state(
    HIG_PDF_LAYER hLayer,
    AT_PDF_BOOL bState
    );

Arguments:

hLayer
Layer whose current state is set.
bState
New state.

Description:

This function sets the current ON-OFF state of the layer object.

Return Value:

Error count.


IG_PDF_layer_get_initial_state

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_get_initial_state(
    HIG_PDF_LAYER hLayer,
    LPAT_PDF_BOOL lpbState
    );

Arguments:

hLayer
Layer whose initial state is obtained.
lpbState
Returns TRUE if the state is ON, FALSE if it is OFF.

Description:

This function gets the initial ON-OFF state of the layer object.

Return Value:

Error count.


IG_PDF_layer_set_initial_state

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_set_initial_state(
    HIG_PDF_LAYER hLayer,
    AT_PDF_BOOL bState
    );

Arguments:

hLayer
Layer whose initial state is set.
bState
The new state.

Description:

This function sets the initial ON-OFF state of the layer object.

Return Value:

Error count.


IG_PDF_layer_has_usage_info

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_has_usage_info(
    HIG_PDF_LAYER hLayer,
    LPAT_PDF_BOOL lpbHasUsage
    );

Arguments:

hLayer
Layer object.
lpbHasUsage
Returns TRUE if the layer has a Usage dictionary, FALSE otherwise.

Description:

This function verifies whether a layer object is associated with a Usage dictionary.

Return Value:

Error count.


IG_PDF_layer_get_usage_info

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_get_usage_info(
    HIG_PDF_LAYER hLayer,
    HIG_PDF_ATOM hUsageKey,
    LPHIG_PDF_BASOBJ lphUsageInfo
    );

Arguments:

hLayer
Layer object whose usage information is obtained.
hUsageKey
The usage key in the usage dictionary entry.
Possible key values are:
  • CreatorInfo
  • Language
  • Export
  • Zoom
  • Print
  • View
  • User
  • PageElement
lphUsageInfo
The usage information associated with the given key in the Usage dictionary for the layer, or a NULL if the operation fails (because the layer is malformed or has no dictionary, or because the dictionary has no entry corresponding to the given key).

Description:

This function gets usage information from a layer object. A Usage dictionary entry provides more specific intended usage information than an intent entry.

Return Value:

Error count.


IG_PDF_layer_set_usage_info

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_set_usage_info(
    HIG_PDF_LAYER hLayer,
    HIG_PDF_ATOM hUsageKey,
    HIG_PDF_BASOBJ hUsageInfo
    );

Arguments:

hLayer
Layer object whose usage information is set.
hUsageKey
The usage key in the usage dictionary entry.
Possible key values are:
  • CreatorInfo
  • Language
  • Export
  • Zoom
  • Print
  • View
  • User
  • PageElement
hUsageInfo
The usage information to associate with the key.

Description:

This function sets a Usage dictionary entry in a layer object. The entry associates usage information with an entry key for retrieval. If a dictionary does not exist, the method creates one.

A Usage dictionary entry provides more specific intended usage information than an intent entry.

The usage value can act as a kind of metadata, describing the sort of things that belong to the layer: for example, text in French, fine detail on a map, or a watermark. The usage values can also be used by the AutoState mechanism to make decisions about what layers should be on and what layers should be off.

Return Value:

Error count.


IG_PDF_layer_get_intent

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_get_intent(
    HIG_PDF_LAYER hLayer,
    LPHIG_PDF_ATOM lphIntent,
    UINT nSize,
    LPUINT lpnLen
    );

Arguments:

hLayer
Layer object whose intent is obtained.
lphIntent
Returns array of intent entries.
nSize
Maximal size of lphIntent.
lpnLen
Actual number of intent entries copied to lphIntent.

Description:

This function gets the intent list for a layer. Intent is an atom value broadly describing the intended use, either View or Design. A layer's content is considered to be optional (that is, the layer's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

Return Value:

Error count.


IG_PDF_layer_set_intent

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_set_intent(
    HIG_PDF_LAYER hLayer,
    LPHIG_PDF_ATOM lphIntent,
    UINT nLen
    );

Arguments:

hLayer
Layer object whose intent is set.
lphIntent
New Intent entry value, an array of intent entries (atoms).
nLen
Number of intent entries in lphIntent.

Description:

This function sets the Intent entry in a layer's dictionary. Intent is an atom value broadly describing the intended use, either View or Design. A layer's content is considered to be optional (that is, the layer's state is considered in its visibility) if any intent in its list matches an intent of the context. The intent list of the context is usually set from the intent list of the document configuration.

Return Value:

Error count.


IG_PDF_layer_get_unique_id

Group: Layer

Declaration:

IG_PDF_layer_get_unique_id(
    HIG_PDF_LAYER hLayer,
    LPUINT lpnUniqueId);

Arguments:

hLayer
Layer object.
lpnUniqueId
The unique identifier.

Description:

Returns some 32bit integer that is unique for all Layer objects. In other words, it is guaranteed that there cannot be two Layer objects with the same UniqueIds.

Can be used for Layer objects' identification.

Return Value:

An unique identifier of this Layer Object.


IG_PDF_layer_delete

Group: Layer

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_layer_delete(
    HIG_PDF_LAYER hLayer
    );

Arguments:

hLayer
Layer object to delete.

Description:

(Use the new IG_PDF_layer_release function instead)

This function deletes a PDF layer object.

Return Value:

Error count.


IG_PDF_layer_release

Group: Layer

Declaration:

IG_PDF_layer_release(
    HIG_PDF_LAYER hLayer)

Arguments:

hLayer
Layer object to release.

Description:

(The same as the old method IG_PDF_layer_delete).

Releases the native object and frees memory.

Return Value:

Nothing.


IG_PDF_layer_remove

Group: Layer

Declaration:

IG_PDF_layer_remove(
    HIG_PDF_LAYER hLayer)

Arguments:

hLayer
The layer object.

Description:

Destroys layer (optional-content group) object. This does not delete any content.


HIG_PDF_PAGE

Type: Page Object

Description:

Handle to the PDF page object. A single page in the PDF representation of a document. A page contains a series of objects representing the objects drawn on the page (Graphic), a list of resources used in drawing the page, annotations (Annotation), an optional thumbnail image of the page, and the beads used in any articles that occur on the page.

Class Members:

IG_PDF_page_get_content
Creates HIG_PDE_CONTENT from HIG_PDF_PAGE.
IG_PDF_page_get_crop_box
Gets the crop box for the page.
IG_PDF_page_get_rotation
Gets the rotation for the page.
IG_PDF_page_make_color_separations
Separates hPage's DeviceN colorants into individual layers.
IG_PDF_page_set_content
Sets the page's PDF content back into the HIG_PDF_PAGE object, using the same compression filters with which the content was previously encoded.
IG_PDF_page_release_content
Decrements HIG_PDF_PAGE's PDF content internal reference count.
IG_PDF_page_reset_display_cache
Causes IG display API to re-render PDF page content for display.
IG_PDF_page_get_annotation_count
Gets the number of annotations on a page.


IG_PDF_page_get_content

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_page_get_content(
HIG_PDF_PAGE hPage,
LPHIG_PDE_CONTENT lpnContent);

Arguments:

hPage
The page whose content object is acquired
lpnContent
PDE content return value

Description:

Creates HIG_PDE_CONTENT from HIG_PDF_PAGE. The PDF content is cached, so that subsequent calls on the same page return the same PDF content.

Return Value:

Error count.


IG_PDF_page_get_crop_box

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI i_IG_PDF_page_get_crop_box(
    HIG_PDF_PAGE hPage,
    LPAT_PDF_FIXEDRECT lpFixedBox
);

Arguments:

hPage
The page whose crop box is obtained.
lpFixedBox
The crop box

Description:

Gets the crop box for the page.


IG_PDF_page_get_rotation

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI i_IG_PDF_page_get_rotation(
    HIG_PDF_PAGE hPage,
    LPSHORT lpRotation
);

Arguments:

hPage
The page whose rotation is obtained.
lpRotation
The rotation.

Description:

Gets the rotation for the page


IG_PDF_page_make_color_separations

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_page_make_color_separations(
HIG_PDF_PAGE hPage,
LPHIG_PDF_ATOM pColorChannels,
UINT nColorChannelsNum,
HIG_PDF_DOC hDoc,
LONG nAfterPage
);

Arguments:

hPage
The page whose content object is acquired.
pColorChannels
Atom array containing the colorant names to separate.
Example: "C", "M", "Y", "K", "PANTONE 300 C", etc.
nColorChannelsNum
Number of elemens in pColorChannels.
hDoc
Output PDF document.
nAfterPage
The page number in the output PDF document after which the result page is inserted.

Description:

Separates hPage's DeviceN colorants into individual layers. The result page is inserted in hDoc after the page with index nAfterPage.

Return Value:

Error count.

Example:

HIG_PDF_ATOM* pColorChannels = new HIG_PDF_ATOM[2];
IG_PDF_atom_from_string("Y", &pColorChannels[0]);
IG_PDF_atom_from_string("PANTONE 300 C", &pColorChannels[1]);
nErrCount +=
IG_PDF_page_make_color_separations(GetCurPDFPage(),
pColorChannels, 2, GetPDFDoc(), nPageCount-2);
delete pColorChannels;


IG_PDF_page_set_content

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_page_set_content(
HIG_PDF_PAGE hPage);

Arguments:

hPage
The page whose content object is set

Description:

Sets the page's PDF content back into the HIG_PDF_PAGE object, using the same compression filters with which the content was previously encoded.

Return Value:

Error count.


IG_PDF_page_release_content

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_page_release_content(
HIG_PDF_PAGE hPage);

Arguments:

hPage
The page whose content object's use count is decremented

Description:

Decrements HIG_PDF_PAGE's PDF content internal reference count. The content is not automatically deleted when the reference count becomes zero - it remains in the cache until the cache slot is needed for another HIG_PDF_PAGE. Thus, you do not need to keep a content acquired for performance reasons.

Return Value:

Error count.


IG_PDF_page_reset_display_cache

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_page_reset_display_cache(
HIG_PDF_PAGE hPage);

Arguments:

hPage
A PDF page.

Description:

Causes IG display API to re-render PDF page content for display.

Return Value:

Error count.


IG_PDF_page_get_annotation_count

Group: Page

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_page_get_annotation_count(
HIG_PDF_PAGE hPage,
LPUINT lpnCount);

Arguments:

hPage
The page for which the number of annotations is obtained
lpnCount
The number of annotations return value

Description:

Gets the number of annotations on a page. Annotations associated with pop-up windows (such as strikeouts) are counted as two annotations. Widget annotations (form fields) are included in the count.

Return Value:

Error count.


HIG_PDF_PREFLIGHT

Type: PDF Preflight Object

Description:

This is a handle-based object that provides PDF preflight capabilities. You can create a HIG_PDF_PREFLIGHT object for each PDF document you want to apply preflight for and use it with IG_PDF_preflight_... API.

Class Members:

IG_PDF_preflight_create
Creates new preflight object for the specified PDF document.
IG_PDF_preflight_delete
Deletes the specified preflight object.
IG_PDF_preflight_verify_compliance
Analyzes PDF document for compliance with PDF/A and PDF/X standards.


IG_PDF_preflight_create

Group: Preflight

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_preflight_create(
    HIG_PDF_DOC hDoc,
    LPHIG_PDF_PREFLIGHT lphPreflight);

Description:

This function creates new preflight object for the specified PDF document.

Arguments:

hDoc
PDF document for which to do preflight.
lphPreflight
PDF preflight object.

Returns:

Error count.


IG_PDF_preflight_delete

Group: Preflight

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_preflight_delete(
    HIG_PDF_PREFLIGHT hPreflight
    );

Description:

This function deletes the specified preflight object.

Arguments:

hPreflight
PDF preflight object to delete.

Returns:

Error count.


IG_PDF_preflight_verify_compliance

Group: Preflight

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_preflight_verify_compliance(
    HIG_PDF_PREFLIGHT hPreflight,
    AT_UINT Profile,
    AT_INT nStartPage,
    AT_INT nPageCount,
    LPHIG_PDF_PREFLIGHT_REPORT lphPreflightReport
    );

Description:

This function analyzes the PDF document the preflight was created and checks it for compliance with PDF/A and PDF/X standards. The result is returned as an HIG_PDF_PREFLIGHT_REPORT object.

If the document is compliant with the specified profile the output report's code value is equal to IG_PDF_PREFLIGHT_SUCCESS. If it is not compliant, the output report's code value is equal to IG_PDF_PREFLIGHT_INCOMPLIANT_DOCUMENT and its records' tree will have a complete report of incompliances.

Arguments:

hPreflight
Preflight object.
Profile
Preflight profile to verify compliance with.
nStartPage
Document's start page to verify.
nPageCount
The number of pages to verify. Specify -1 to verify all pages.
lphPreflightReport
Result of verification as an HIG_PDF_PREFLIGHT_REPORT object.

Returns:

Error count.


HIG_PDF_PREFLIGHT_REPORT

Type: PDF Preflight Report Object

Description:

This is a handle-based object that contains PDF preflight report in a tree form. This report is generated by IG_PDF_preflight_verify_compliance API and contains the compliance issues for the specified profile. You can use HIG_PDF_PREFLIGHT_REPORT object with IG_PDF_preflight_... API.

Class Members:

IG_PDF_preflight_report_delete
Deletes the specified preflight report object.
IG_PDF_preflight_report_get_code
Gets preflight report code of the current report node.
IG_PDF_preflight_report_get_description
Gets description of the current report node.
IG_PDF_preflight_report_get_record
Gets the child report node with the specified index.
IG_PDF_preflight_report_get_record_count
Gets the number of records in the current report node.


IG_PDF_preflight_report_delete

Group: Preflight Report

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_preflight_report_delete(
    HIG_PDF_PREFLIGHT_REPORT hPreflightReport
    );

Description:

This function deletes the specified preflight report object.

Arguments:

hPreflightReport
PDF preflight report object to delete.

Returns:

Error count.


IG_PDF_preflight_report_get_code

Group: Preflight Report

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_preflight_report_get_code(
    HIG_PDF_PREFLIGHT_REPORT hPreflightReport,
    LPAT_INT lpnCode
    );

Description:

This function gets preflight report code of the current report node.

Arguments:

hPreflightReport
Preflight report object.
lpnCode
Returned preflight report code.

Returns:

Error count.


IG_PDF_preflight_report_get_description

Group: Preflight Report

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_preflight_report_get_description(
    HIG_PDF_PREFLIGHT_REPORT hPreflightReport,
    LPSTR szDescription,
    LPAT_INT lpnLength
    );

Description:

This function gets description of the current report node.

Arguments:

hPreflightReport
Preflight report object.
szDescription
Pointer to the buffer to copy description to.
lpnLength
Returned length of description.

Returns:

Error count.


IG_PDF_preflight_report_get_record

Group: Preflight Report

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_preflight_report_get_record(
    HIG_PDF_PREFLIGHT_REPORT hPreflightReport,
    AT_INT nIndex,
    LPHIG_PDF_PREFLIGHT_REPORT lphRecord
    );

Description:

This function gets the child report node with the specified index.

Arguments:

hPreflightReport
Preflight report object.
nIndex
Index of the child report node to obtain.
lphRecord
PDF preflight report's record.

Returns:

Error count.


IG_PDF_preflight_report_get_record_count

Group: Preflight Report

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_preflight_report_get_record_count(
    HIG_PDF_PREFLIGHT_REPORT hPreflightReport,
    LPAT_INT lpnCount
    );

Description:

This function gets the number of records in the current report node.

Arguments:

hPreflightReport
Peflight report object.
lpnCount
PDF preflight report's record count.

Returns:

Error count.


HIG_PDF_WORDFINDER

Type: Word Finder Object

Description:

Handle to the PDF word finder object. Extracts words from a PDF file, and enumerates the words on a single page or on all pages in a document.

Class Members:

IG_PDF_wordfinder_acquire_wordlist
Finds all words on the specified page.
IG_PDF_wordfinder_release_wordlist
Releases the word list for a given page.
IG_PDF_wordfinder_get_word
Gets the word in the word list obtained using IG_PDF_wordfinder_acquire_wordlist.
IG_PDF_wordfinder_delete
Deletes a word finder.


IG_PDF_wordfinder_acquire_wordlist

Group: Word Finder

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_wordfinder_acquire_wordlist(
HIG_PDF_WORDFINDER hWordFinder, LONG nPageNumber, LPLONG
lpnWordCount );

Arguments:

hWordFinder
The word finder used to acquire the word list.
nPageNumber
The page number for which words are found. First page is 0.
lpnWordCount
The number of words found on the page.

Description:

Finds all words on the specified page.

Only words within or partially within the page's crop box are enumerated. Words outside the crop box are skipped.

There can be only one word list in existence at a time; clients must release the previous word list, using IG_PDF_wordfinder_release_wordlist, before creating a new one.

Return Value:

Error count.


IG_PDF_wordfinder_release_wordlist

Group: Word Finder

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_wordfinder_release_wordlist(
HIG_PDF_WORDFINDER hWordFinder, LONG nPageNumber );

Arguments:

hWordFinder
The word finder object.
nPageNumber
The page number for which the word list is released.

Description:

Releases the word list for a given page. Use this to release a list created by IG_PDF_wordfinder_acquire_wordlist when you are done using this list.

Return Value:

Error count.


IG_PDF_wordfinder_get_word

Group: Word Finder

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_wordfinder_get_word (
HIG_PDF_WORDFINDER hWordFinder, WORD nFlags, LONG nIndex,
LPHIG_PDF_WORD lphWord );

Arguments:

hWordFinder
The word finder object.
nFlags
Word-finding options. Must be an OR of one or more of enumIGPDFWordFlags.
nIndex
The index of the word to obtain. The first word on a page has an index of zero. Words are counted in PDF order.
lphWord
A handle to the word object. Returns NULL when the end of the list is reached.

Description:

Gets the word in the word list obtained using IG_PDF_wordfinder_acquire_wordlist.

Return Value:

Error count.


IG_PDF_wordfinder_delete

Group: Word Finder

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_wordfinder_delete(
HIG_PDF_WORDFINDER hWordFinder);

Arguments:

hWordFinder
Word finder object to delete.

Description:

Deletes a word finder. Use this when you are done extracting text in a file.

Return Value:

Error count.


HIG_PDF_WORD

Type: Word Object

Description:

Handle to the PDF word object. A word in a PDF file. Each word contains a sequence of characters in one or more styles (see Style).

Class Members:

IG_PDF_word_get_char_offset
Returns a word's character offset from the beginning of its page.
IG_PDF_word_get_char_style
Returns a PDF Style object for the specified style in a word.
IG_PDF_word_get_length
Gets the number of bytes in a word.
IG_PDF_word_get_quad
Gets the specified word's quad, specified in user space coordinates.
IG_PDF_word_get_quad_count
Gets the number of quads in a word.
IG_PDF_word_get_string
Gets a word's text and also converts ligatures to their constituent characters.
IG_PDF_word_get_style_transition
Gets the locations of style transitions in a word.
IG_PDF_word_delete
Deletes a word object.


IG_PDF_word_get_char_offset

Group: Word

Declaration:

AT_ERRCOUNT ACCUAPI
IG_PDF_word_get_char_offset(HIG_PDF_WORD hWord, LPWORD
lpnCharOffset);

Arguments:

hWord
The word whose character offset is obtained.
lpnCharOffset
The word's character offset. On multi-byte systems, it points to the first byte.

Description:

Returns a word's character offset from the beginning of its page.

Return Value:

Error count.


IG_PDF_word_get_char_style

Group: Word

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_word_get_char_style(
HIG_PDF_WORDFINDER hWordFinder,
HIG_PDF_WORD hWord, LONG nIndex, LPHIG_PDF_STYLE lphStyle );

Arguments:

hWordFinder
A word finder object.
hWord
The word whose character style is obtained.
nIndex
The index of the style to obtain. The first style in a word has an index of zero.
lphStyle
The obtained style in the word. Returns NULL if nIndex is greater than the number of styles in the word.

Description:

Returns a PDF Style object for the specified style in a word.

Return Value:

Error count.


IG_PDF_word_get_length

Group: Word

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_word_get_length(HIG_PDF_WORD hWord,
LPWORD lpnLength);

Arguments:

hWord
The word whose character count is obtained.
lpnLength
The number of characters in the word.

Description:

Gets the number of bytes in a word. This method also works on non-Roman systems.

Return Value:

Error count.


IG_PDF_word_get_quad

Group: Word

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_word_get_quad( HIG_PDF_WORD hWord,
SHORT nIndex, LPAT_PDF_FIXEDQUAD lpQuad, LPAT_PDF_BOOL
lpbHasQuad );

Arguments:

hWord
The word whose quad is obtained.
nIndex
The index of the quad to obtain. The first quad in a word has an index of zero.
lpQuad
Pointer to the word's quad, specified in user-space coordinates.
lpbHasQuad
True if the word has the specified quad, false otherwise.

Description:

Gets the specified word's quad, specified in user space coordinates. See IG_PDF_word_get_quad_count for a description of a quad.

The quad's height is the height of the font's bounding box, not the height of the tallest character used in the word. The font's bounding box is determined by the glyphs in the font that extend farthest above and below the baseline; it often extends somewhat above the top of "A" and below the bottom of "y."

The quad's width is determined from the characters actually present in the word.

As an example, the quads for the words "AWAY" and "away" have the same height, but generally do not have the same width unless the font is a mono-spaced font (a font in which all characters have the same width).

Return Value:

Error count.


IG_PDF_word_get_quad_count

Group: Word

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_word_get_quad_count (HIG_PDF_WORD
hWord, LPWORD lpnQuadCount);

Arguments:

hWord
The word whose quad count is obtained.
lpnQuadCount
The number of quads in the word.

Description:

Gets the number of quads in a word. A quad is a quadrilateral bounding a contiguous piece of a word. Every word has at least one quad. A word has more than one quad, for example, if it is hyphenated and split across multiple lines or if the word is set on a curve rather than on a straight line.

Return Value:

Error count.


IG_PDF_word_get_string

Group: Word

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_word_get_string (
HIG_PDF_WORD hWord, LPCHAR lpString, LONG nLen );

Arguments:

hWord
The word whose string is obtained.
lpString
The word string. The encoding of the string is the encoding used by the PDF WordFinder that supplied the PDF Word. For instance, if IG_PDF_doc_create_wordfinder_ucs is used to create the word finder, this function returns only Unicode.
nLen
Length of string, in bytes. Up to nLen characters of word will be copied into lpString. If lpString is long enough, it will be null-terminated.

Description:

Gets a word's text and also converts ligatures to their constituent characters. The string to return includes any word break characters (such as space characters) that follow the word, but not any that precede the word. The characters that are treated as word breaks are defined in the outEncInfo parameter of IG_PDF_doc_create_wordfinder method.

This method produces a string in whatever encoding the PDF Word uses, for both Roman and non-Roman systems.

Return Value:

Error count.


IG_PDF_word_get_style_transition

Group: Word

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_word_get_style_transition(
HIG_PDF_WORD hWord, LPSHORT lpTransTbl, SHORT nSize, LPSHORT
lpnStTrCount );

Arguments:

hWord
The word whose style transition list is obtained.
lpTransTbl
(Filled by the method) Array of style transitions. Each element is the character offset in word where the style changes. The offset specifies the first character in the word that has the new style. The first character in a word has an offset of zero.
nSize
Number of entries that lpTransTbl can hold. The word is searched only until this number of style transitions has been found.
lpnStTrCount
Number of style transition offsets copied to lpTransTbl.

Description:

Gets the locations of style transitions in a word. Every word has at least one style transition, at character position zero in the word.

Return Value:

Error count.


IG_PDF_word_delete

Group: Word

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_word_delete(
HIG_PDF_WORD hWord);

Arguments:

hWord
Word object to delete.

Description:

Deletes a word object.

Return Value:

Error count.


HIG_PDF_STYLE

Type: Style Object

Description:

Handle to the PDF style object; provides access to information about the fonts, font sizes, and colors used in a Word.

Class Members:

IG_PDF_style_get_color
Gets a style's color.
IG_PDF_style_get_font
Gets the specified style's font.
IG_PDF_style_get_font_size
Get a style's font size.
IG_PDF_style_delete
Deletes a PDF style object.


IG_PDF_style_get_color

Group: Style

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_style_get_color(
    HIG_PDF_STYLE hStyle,
    LPAT_PDF_COLORVALUE lpColor
    );

Arguments:

hStyle
The style whose color is obtained
lpColor
The style's color

Description:

Gets a style's color.


IG_PDF_style_get_font

Group: Style

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_style_get_font(
    HIG_PDF_STYLE hStyle,
    LPHIG_PDF_FONT lphFont
    );

Arguments:

hStyle
The style whose font is obtained
lphFont
The font for the specified style

Description:

Gets the specified style's font.


IG_PDF_style_get_font_size

Group: Style

Declaration:

AT_ERRCOUNT ACCUAPI
IG_PDF_style_get_font_size(HIG_PDF_STYLE hStyle,
LPAT_PDF_FIXED lpnFontSize);

Arguments:

hStyle
The style whose font size is obtained.
lpnFontSize
A style's font size.

Description:

Get a style's font size.

Return Value:

Error count.


IG_PDF_style_delete

Group: Style

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_style_delete(
HIG_PDF_STYLE hStyle );

Arguments:

hStyle
Style object to delete.

Description:

Deletes a PDF style object.

Return Value:

Error count.


HIG_PDF_SYSFONT

Type: System Font Object

Description:

Handle to the system font object. A reference to a font installed in the host system. SysFont methods allow you to list the fonts available in the host system and to find a font in the system that matches a PDE Font, if it is present.

Class Members:

IG_PDF_sysfont_enumerate
Enumerates all of the system fonts with a user-supplied procedure.
IG_PDF_sysfont_find
Finds a system font that matches the requested attributes.
IG_PDF_sysfont_find_for_pdefont
Gets platform-specific data for use by user interface code.
IG_PDF_sysfont_get_platform_data
Gets platform-specific data for use by user interface code.
IG_PDF_sysfont_get_attrs
Gets the attributes of a system font.
IG_PDF_sysfont_get_cid_system_info
Derives the registry, ordering, and supplement information of a multi-byte system font.
IG_PDF_sysfont_get_create_flags
This function obtains lpnFlags that can be passed to IG_PDE_font_create_from_sysfont_and_encoding.
IG_PDF_sysfont_get_info
Gets high-level information about a system font.
IG_PDF_sysfont_get_name
Gets the PostScript or TrueType styled name for a system font.
IG_PDF_sysfont_get_widths
Gets the widths of a single byte encoded system font.
IG_PDF_sysfont_release_platform_data
Releases platform-specific data for the specified hSysFont.
IG_PDF_sysfont_release
Releases a system font object.


IG_PDF_sysfont_enumerate

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_enumerate(
LPFNIG_PDF_SYSFONT_ENUMPROC lpfnEnumProc,
LPVOID lpClientData );

Arguments:

lpfnEnumProc
User-supplied callback to call once for each system font.
Enumeration continues until all fonts have been enumerated, or until lpfnEnumProc returns false.
lpClientData
Pointer to user-supplied data to pass to lpfnEnumProc each time it is called.

Description:

Enumerates all of the system fonts with a user-supplied procedure.

The SysFont parameters must be copied during the enumeration if they are needed beyond the lpfnEnumProc.

Developers should not assume that the lpfnEnumProc will get called. If no system fonts are found, lpfnEnumProc is never called.

Return Value:

Error count.


IG_PDF_sysfont_find

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_find(
LPAT_PDE_FONTATTRS lpAttrs,
LONG nFlags,
LPHIG_PDF_SYSFONT lphSysFont);

Arguments:

lpAttrs
Pointer to AT_PDE_FONTATTRS structure with the attributes of the font you are searching for.
nFlags
Bit field comprised of enumIGPDFSysFontMatchFlags values. Passing zero matches font by name only.
lphSysFont
The desired system font.

Description:

Finds a system font that matches the requested attributes.

Return Value:

Error count.


IG_PDF_sysfont_find_for_pdefont

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_find_for_pdefont(
HIG_PDE_FONT hFont,
LONG nFlags,
LPHIG_PDF_SYSFONT lphSysFont );

Arguments:

hFont
A PDE Font whose matching system font is found.
nFlags
Bit field comprised of enumIGPDFSysFontMatchFlags values. Passing zero matches font by name only.
lphSysFont
The desired system font.

Description:

Finds a system font that matches the requested hFont.

Return Value:

Error count.


IG_PDF_sysfont_get_platform_data

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_get_platform_data(
HIG_PDF_SYSFONT hSysFont,
LPAT_PDF_SYSFONT_PLATDATA *lpPlatData );

Arguments:

hSysFont
A SysFont object referencing a system font.
lpPlatData
Pointer to a LPAT_PDF_SYSFONT_PLATDATA containing information relating to a system font. Returns NULL if out of memory.

Description:

Gets platform-specific data for use by user interface code. Must be released when finished by IG_PDF_sysfont_release_platform_data.

Return Value:

Error count.


IG_PDF_sysfont_get_attrs

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_get_attrs(
HIG_PDF_SYSFONT hSysFont,
LPAT_PDE_FONTATTRS lpAttrs );

Arguments:

hSysFont
A SysFont object referencing a system font.
lpAttrs
Pointer to AT_PDE_FONTATTRS with the attributes of a system font.

Description:

Gets the attributes of a system font.

The attributes will be returned in the buffer pointed to by lpAttrs.

This call can be expensive to execute, as it may involve parsing the font in order to determine attributes.

Return Value:

Error count.


IG_PDF_sysfont_get_cid_system_info

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_get_cid_system_info(
HIG_PDF_SYSFONT hSysFont,
LPHIG_PDF_ATOM lphRegistry,
LPHIG_PDF_ATOM lphOrdering,
LPLONG lpnSupplement );

Arguments:

hSysFont
A SysFont object referencing a multi-byte system font.
lphRegistry
The PDF atom representing the CID Font's registry information, as in "Adobe".
lphOrdering
The PDF atom representing the CID Font's ordering information, for example, "Japan1".
lpnSupplement
The SystemSupplement field from the CID Font.

Description:

Derives the registry, ordering, and supplement information of a multi-byte system font. This information can be used to create a PDE Font from a system font.

Return Value:

Error count.


IG_PDF_sysfont_get_create_flags

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_get_create_flags(
HIG_PDF_SYSFONT hSysFont,
HIG_PDF_SYSENCODING hSysEncoding,
LPLONG lpnFlags );

Arguments:

hSysFont
A SysFont object.
hSysEncoding
A SysEncoding object.
lpnFlags
Create flags that can be passed to IG_PDE_font_create_from_sysfont_and_encoding. If the combination of hSysFont and hSysEncoding is not allowed, it is set to -1.

Description:

This function obtains lpnFlags that can be passed to IG_PDE_font_create_from_sysfont_and_encoding. If the combination of hSysFont and hSysEncoding is not allowed, it is set to -1.

Return Value:

Error count.


IG_PDF_sysfont_get_info

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_get_info(
HIG_PDF_SYSFONT hSysFont,
LPAT_PDE_FONT_INFO lpInfo );

Arguments:

hSysFont
A SysFont object referencing a system font whose information is obtained.
lpInfo
Pointer to AT_PDE_FONT_INFO structure to fill with font information for hSysFont.

Description:

Gets high-level information about a system font.

Return Value:

Error count.


IG_PDF_sysfont_get_name

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_get_name(
HIG_PDF_SYSFONT hSysFont,
LPHIG_PDF_ATOM lphName );

Arguments:

hSysFont
A SysFont object referencing a system font whose name is obtained.
lphName
The PDF atom for the system font's name.

Description:

Gets the PostScript or TrueType styled name for a system font.

Return Value:

Error count.


IG_PDF_sysfont_get_widths

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_get_widths(
HIG_PDF_SYSFONT hSysFont,
LPSHORT lpWidths,
LPAT_PDF_FIXED mmDesignVector );

Arguments:

hSysFont
A SysFont object referencing a system font whose widths are obtained.
lpWidths
Pointer to widths array. lpWidths must have room for 256 entries.
mmDesignVector
If hSysFont is a multiple master font, points to the design vector, whose length must equal the number of design axes of hSysFont.

Description:

Gets the widths of a single byte encoded system font.

Return Value:

Error count.


IG_PDF_sysfont_release_platform_data

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_release_platform_data(
HIG_PDF_SYSFONT hSysFont,
LPAT_PDF_SYSFONT_PLATDATA lpPlatData );

Arguments:

hSysFont
A SysFont object referencing a system font.
lpPlatData
Pointer to AT_PDF_SYSFONT_PLATDATA containing platform-specific data to release.

Description:

Releases platform-specific data for the specified hSysFont.

Return Value:

Error count.


IG_PDF_sysfont_release

Group: System Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysfont_release(
HIG_PDF_SYSFONT hSysFont );

Arguments:

hSysFont
A system font to release.

Description:

Releases a system font object.

Return Value:

Error count.


HIG_PDF_SYSENCODING

Type: System Encoding Object

Description:

Handle to the system encoding object. Provides system encoding for a PDF file.

Class Members:

IG_PDF_sysencoding_create_from_base_name
Create an encoding object from base name.
IG_PDF_sysencoding_create_from_cmap_name
Create an encoding object from a PDF CMap name.
IG_PDF_sysencoding_create_from_code_page
Create an encoding object from a PDF CMap name.
IG_PDF_sysencoding_get_writing_mode
Returns writing mode in lpnWritingMode.
IG_PDF_sysencoding_is_identity
Returns in lpbResult true for Identity-H or Identity-V encoding; false otherwise.
IG_PDF_sysencoding_is_multibyte
Returns in lpbResult true for CMap encoding; false otherwise.
IG_PDF_sysencoding_release
Release an encoding object.


IG_PDF_sysencoding_create_from_base_name

Group: System Encoding

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysencoding_create_from_base_name(
HIG_PDF_ATOM hBaseEncName,
LPCSTR *lpDiffEnc,
LPHIG_PDF_SYSENCODING lphSysEncoding );

Arguments:

hBaseEncName
The base encoding. See Section 5.5.5 in the PDF Reference.
lpDiffEnc
Array of 256 const char* describing the differences from the encoding specified by hBaseEncName. May be NULL.
lphSysEncoding
New encoding object.

Description:

Create an encoding object from base name.

Return Value:

Error count.


IG_PDF_sysencoding_create_from_cmap_name

Group: System Encoding

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysencoding_create_from_cmap_name(
HIG_PDF_ATOM hCMapName,
LPHIG_PDF_SYSENCODING lphSysEncoding );

Arguments:

hCMapName
The CMap name.
lphSysEncoding
New encoding object.

Description:

Create an encoding object from a PDF CMap name.

Return Value:

Error count.


IG_PDF_sysencoding_create_from_code_page

Group: System Encoding

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysencoding_create_from_code_page(
LONG nCodePage,
SHORT nWritingMode,
LPHIG_PDF_SYSENCODING lphSysEncoding );

Arguments:

nCodePage
The code page character-mapping construct. One of enumIGPDFCodePages values.
nWritingMode
0 for horizontal writing, 1 for vertical writing.
lphSysEncoding
New encoding object.

Description:

Create an encoding object from a code page.

Return Value:

Error count.


IG_PDF_sysencoding_get_writing_mode

Group: System Encoding

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysencoding_get_writing_mode(
HIG_PDF_SYSENCODING hSysEncoding,
LPSHORT lpnWritingMode);

Arguments:

hSysEncoding
An encoding object.
lpnWritingMode
0 for horizontal writing and 1 for vertical writing.

Description:

Returns writing mode in lpnWritingMode. 0 for horizontal writing and 1 for vertical writing.

Return Value:

Error count.


IG_PDF_sysencoding_is_identity

Group: System Encoding

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysencoding_is_identity(
HIG_PDF_SYSENCODING hSysEncoding,
LPAT_BOOL lpbResult );

Arguments:

hSysEncoding
An encoding object.
lpbResult
True for Identity-H or Identity-V encoding; false otherwise.

Description:

Returns in lpbResult true for Identity-H or Identity-V encoding; false otherwise.

Return Value:

Error count.


IG_PDF_sysencoding_is_multibyte

Group: System Encoding

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysencoding_is_multibyte(
HIG_PDF_SYSENCODING hSysEncoding,
LPAT_BOOL lpbResult );

Arguments:

hSysEncoding
An encoding object.
lpbResult
True for CMap encoding; false otherwise

Description:

Returns in lpbResult true for CMap encoding; false otherwise.

Return Value:

Error count.


IG_PDF_sysencoding_release

Group: System Encoding

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDF_sysencoding_release(
HIG_PDF_SYSENCODING hSysEncoding )

Arguments:

hSysEncoding
An encoding object to release.

Description:

Release an encoding object.

Return Value:

Error count.


Page Editing Objects and Elements

Objects described in this chapter provide an easy access to PDF page contents. With this group of objects you can treat a page's contents as a list of objects - rather than having to manipulate the content stream's PDF marking operators. The editing (or PDE) objects provide an easy access to PDF page contents. PDE objects are meant to be used in conjunction with the General and Base Object methods for manipulating PDF documents.

The PDE objects are splitted in two groups: PDE elements and PDE objects. A page display list is represented as a PDE object that contains PDE elements. The page's content is usually treated as a list of PDE elements. Each PDE element is a path, text, image, form, or a marked content place or container of PDE Elements. Using the PDE Objects and methods you can add or remove objects inside a PDE Objects. You can also change attributes of Elements in a PDE Object, such as a bounding box, a text font, or a clipping path.

The PDE objects are used to create the PDE elements and provide specific information for the elements. For example, PDE Image, which is an element, usually has or is created based on a PDE ColorSpace, which is an object. PDE text, which is an element, usually has or is created based on a PDE Font, which is an object.

This API is meant to be used in conjunction with basic and general objects.

The following table contains the objects and their descriptions supported by the ImageGear PDF component:

Page Editing Objects and Elements
HIG_PDE_OBJECT
Object - base interface for all the PDE objects.
HIG_PDE_CONTENT
Content - modifiable content of a PDF page, which contains elements. Content may be obtained from an existing page or from a Form XObject.
HIG_PDE_COLORSPACE
ColorSpace - a reference to a color space used on a page in a PDF file. The color space is part of the graphics state attributes of a PDE Element.
HIG_PDE_FONT
Font - A reference to a font used on a page in a PDF file. It may be equated with a font in the system.
HIG_PDE_ELEMENT
Element - base interface for the elements of a page display list (PDE content) and for clip objects. The general PDE element methods allow you to get and set general element properties.
HIG_PDE_CLIP
Clip - a list of elements containing a list of Paths and Texts that describe a clip state. Clips can be created and built up with PDE Clip methods. Any PDE Element object can have Clip associated with it. Clip objects can contain PDE Containers and PDE Groups to an arbitrary level of nesting. This allows PDE Containers to be used to mark clip objects.
PDE Groups inside PDE Clips that contain at least one PDE Text and no PDE Paths have a special meaning. All PDE Text objects contained in such a PDE Group are considered to be part of the same BT/ET block. This means that the union of these
PDE Texts makes up a single clipping path-as opposed to the intersection of the PDE Texts.
See Section 5.3 in the PDF reference for more information about BT/ET block.
HIG_PDE_CONTAINER
Container - a group of elements on a page in a PDF file. In the PDF file, containers are delimited by Marked Content BMC/EMC or BDC/EMC pairs. Every container has a Marked Content tag associated with it. In addition to grouping a set of elements, a BDC/EMC pair specifies a property list to be associated with the grouping. Thus a container corresponding to a BDC/EMC pair also has a property list dictionary associated with it.
See Section 10.5 in the PDF reference for more information about Marked Content operators.
HIG_PDE_FORM
Form - an element that corresponds to an instance of XObject Form on a page (or other containing stream such as another XObject Form or annotation form). The context associated with this instance includes the actual stream that represents the XObject Form and the initial conditions of the graphics state. The latter consists of the transformation matrix, initial color values, and so forth. It is possible to have two Forms that refer to the same XObject Form. The forms will exist at different places on the same page, depending on the transformation matrix. They may also have different colors or line stroking parameters. In the case of a transparency group, the opacity is specified in the gstate.
Within a Form, each element has its own gstate (or is a container, place, or group object). These gstates are independent of the parent Form gstate. Form elements may have their own opacity.
Content may be obtained from a Form to edit the form's display list.
HIG_PDE_GROUP
Group - an in-memory representation of objects in Content. It has no state and is not represented in any way in a content stream (that is, Content).
When used in a Clip, this object is used to associate Text objects into a single clipping object.
HIG_PDE_IMAGE
Image - an element that contains an Image XObject or in-line image. You can associate data or a stream with an image.
HIG_PDE_PATH
Path - an element that contains a path. Path objects can be stroked, filled, and/or serve as a clipping path.
HIG_PDE_PLACE
Place - an element that marks a place on a page in a PDF file. In a PDF file, a place is represented by the MP or DP Marked Content operators.
Marked content is useful for adding structure information to a PDF file. For instance, a drawing program may want to mark a point with information, such as the start of a path of a certain type. Marked content provides a way to retain this information in the PDF file. A
DP operator functions the same as the MP operator and, in addition, allows a property list dictionary to be associated with a place.
HIG_PDE_POSTSCRIPT
PostScript - an element representing in-line or XObject pass-through PostScript object. XObject PostScripts are listed in page XObject resources.
HIG_PDE_SOFTMASK
SoftMask- an object for creating and manipulating a soft mask in a PDF file.
HIG_PDE_SHADING
Shading - an element that represents smooth shading.
HIG_PDE_TEXT
Text - an element representing text. It is a container for text as show strings or as individual characters. Each sub-element may have different graphics state properties. However, the same clip applies to all sub-elements of a Text. Also, the char path of a Text can be used to represent a clip.
HIG_PDE_TEXTITEM
TextItem - a PDE element representing a text object.
HIG_PDE_XGROUP
XGroup - a transparency (XGroup) resource.
HIG_PDE_XOBJECT
XObject - an element representing an arbitrary XObject.


HIG_PDE_OBJECT

Type: Abstract PDE Object

Description:

Handle to abstract PDE object. Base interface for all the PDE objects.

Class Members:

IG_PDE_object_get_type
Gets the type of an object.


IG_PDE_object_get_type

Group: Abstract PDE

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_object_get_type(
HIG_PDE_OBJECT hObject,
LPLONG lpnType);

Arguments:

hObject
The object whose type is obtained.
lpnType
Type return value

Description:

Gets the type of an object.

Return Value:

Error count.


HIG_PDE_CONTENT

Type: PDE Content Object

Description:

Handle to the PDE content object. Modifiable content of a PDF page, which contains elements. Content may be obtained from an existing page or from a Form XObject.

Class Members:

IG_PDE_content_create
Creates empty PDEContent.
IG_PDE_content_get_element
Obtains requested element from content.
IG_PDE_content_add_element
Inserts an element into content.
IG_PDE_content_remove_element
Removes an element from content.
IG_PDE_content_get_element_count
Gets the number of elements in a content.
IG_PDE_content_get_default_color_space
Gets a default color space from hContent.
IG_PDE_content_get_attrs
Gets the attributes of a content.


IG_PDE_content_create

Group: PDE Content

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_content_create(
    LPHIG_PDE_CONTENT lphContent
    );

Arguments:

lphContent
The created PDEContent.

Description:

This method creates empty PDEContent.


IG_PDE_content_get_element

Group: PDE Content

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_content_get_element(
HIG_PDE_CONTENT hContent,
LONG nIndex,
LPHIG_PDE_ELEMENT lphElement);

Arguments:

hContent
Content to obtain from
nIndex
Index of element to obtain
lphElement
PDE element return value

Description:

Obtains requested element from content.

Return Value:

Error count.


IG_PDE_content_add_element

Group: PDE Content

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_content_add_element(
HIG_PDE_CONTENT hContent,
LONG nAfterIndex,
HIG_PDE_ELEMENT hElement);

Arguments:

hContent
Content to which hElement is added
nAfterIndex
Location after which hElement is added. Should be IG_PDE_BEFORE_FIRST to add to the beginning of the display list.
hElement
The element to add to the content.

Description:

Inserts an element into content.

Return Value:

Error count.


IG_PDE_content_remove_element

Group: PDE Content

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_content_remove_element(
HIG_PDE_CONTENT hContent,
LONG nIndex);

Arguments:

hContent
Content to remove from
nIndex
Index of element to remove

Description:

Removes an element from content.

Return Value:

Error count.


IG_PDE_content_get_element_count

Group: PDE Content

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_content_get_element_count(
HIG_PDE_CONTENT hContent,
LPUINT lpnCount);

Arguments:

hContent
Content
lpnCount
The number of elements return value

Description:

Gets the number of elements in a content.

Return Value:

Error count.


IG_PDE_content_get_default_color_space

Group: PDE Content

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_content_get_default_color_space(
HIG_PDE_CONTENT hContent,
HIG_PDF_ATOM hColorSpaceName,
LPHIG_PDE_COLORSPACE lphDefaultColorSpace);

Arguments:

hContent
Content to whose default color space is obtained
hColorSpaceName
An atom for the name of the desired color space. Must be an atom for one of DefaultRGB, DefaultCMYK, or DefaultGray.
lphDefaultColorSpace
The desired color space in hContent. Returns NULL if hColorSpaceName does not correspond to a known default, such as DefaultRGB.

Description:

Gets a default color space from hContent.

See Section 4.5.4 in the PDF Reference for more information about default color spaces.

Return Value:

Error count.


IG_PDE_content_get_attrs

Group: PDE Content

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_content_get_attrs (
HIG_PDE_CONTENT hContent,
LPAT_PDE_CONTENTATTRS lpAttrs );

Arguments:

hContent
Content whose attributes are obtained
lpAttrs
Pointer to a AT_PDE_CONTENTATTRS structure to fill with the attributes of the content.

Description:

Gets the attributes of a content.

Return Value:

Error count.


HIG_PDE_COLORSPACE

Type: PDE Color Space Object

Description:

Handle to the PDE color space object. A reference to a color space used on a page in a PDF file. The color space is part of the graphics state attributes of a PDE Element.

Class Members:

IG_PDE_colorspace_create
Creates a new color space object of the specified type.
IG_PDE_colorspace_get_base_name
Gets the name of the base color space.
IG_PDE_colorspace_get_base_color_components
Gets the number of components in the base color space of an indexed color space.
IG_PDE_colorspace_get_ctable
Gets the component information for an indexed color space.
IG_PDE_colorspace_get_hival
Gets the highest index for the color lookup table for an indexed color space.
IG_PDE_colorspace_get_name
Gets the name of a color space object.
IG_PDE_colorspace_get_color_components
Calculates the number of components in a color space.
IG_PDE_colorspace_release
Releases a color space object.


IG_PDE_colorspace_create

Group: PDE Color Space

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_colorspace_create(
HIG_PDF_ATOM hFamily,
LPAT_PDE_COLORDATA lpColorData,
LPHIG_PDE_COLORSPACE lphColorSpace );

Arguments:

hFamily
Supports the following PDF color spaces:
Device-dependent names: DeviceCMYK, DeviceGray, DeviceN, or DeviceRGB.
Device-independent names: CalGray, CalRGB, Lab, or ICCBased.
Special names: Indexed, Pattern, or Separation.
lpColorData
Color data for the type of color space you want to create.
lphColorSpace
Handle to the new color space

Description:

Creates a new color space object of the specified type.

Return Value:

Error count.


IG_PDE_colorspace_get_base_name

Group: PDE Color Space

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_colorspace_get_base_name (
HIG_PDE_COLORSPACE hColorSpace,
LPHIG_PDF_ATOM lphBaseName );

Arguments:

hColorSpace
The base color space.
lphBaseName
The atom for the name of the base color space.

Description:

Gets the name of the base color space. This is a helper routine for indexed color spaces.

Return Value:

Error count.


IG_PDE_colorspace_get_base_color_components

Group: PDE Color Space

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_colorspace_get_base_color_components
(
HIG_PDE_COLORSPACE hColorSpace,
LPLONG lpnColorComponents);

Arguments:

hColorSpace
The base color space.
lpnColorComponents
Number of components in hColorSpace.

Description:

Gets the number of components in the base color space of an indexed color space.

For example, for [/Indexed /DeviceRGB...], the number of components is 3.

Return Value:

Error count.


IG_PDE_colorspace_get_ctable

Group: PDE Color Space

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_colorspace_get_ctable (
HIG_PDE_COLORSPACE hColorSpace,
LPBYTE lpColorTable);

Arguments:

hColorSpace
The color space whose component information table is obtained.
lpColorTable
The color lookup table, which is nColorComponents *
(nHiVal + 1) bytes long, where nColorComponents = number of components in the base hColorSpace.
Each entry in the table contains nColorComponents bytes, and the table is indexed 0 to nHiVal, where nHiVal is the highest index in the color table. The table is indexed from 0 to nHiVal, thus the table contains nHiVal + 1 entries.

Description:

Gets the component information for an indexed color space.

Return Value:

Error count.


IG_PDE_colorspace_get_hival

Group: PDE Color Space

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_colorspace_get_hival (
HIG_PDE_COLORSPACE hColorSpace,
LPLONG lpnHiVal);

Arguments:

hColorSpace
An indexed color space.
lpnHiVal
The highest index (nHiVal) in the color lookup table.

Description:

Gets the highest index for the color lookup table for an indexed color space. Since the color table is indexed from zero to nHiVal, the actual number of entries is nHiVal + 1.

Return Value:

Error count.


IG_PDE_colorspace_get_name

Group: PDE Color Space

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_colorspace_get_name (
HIG_PDE_COLORSPACE hColorSpace,
LPHIG_PDF_ATOM lphName );

Arguments:

hColorSpace
A color space object.
lphName
The color space object's name. Supports the following PDF color spaces:
Device-dependent names: DeviceCMYK, DeviceGray, DeviceN, or DeviceRGB.
Device-independent names: CalGray, CalRGB, Lab, or ICCBased.
Special names: Indexed, Pattern, or Separation.

Description:

Gets the name of a color space object.

Return Value:

Error count.


IG_PDE_colorspace_get_color_components

Group: PDE Color Space

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_colorspace_get_color_components (
HIG_PDE_COLORSPACE hColorSpace,
LPLONG lnpColorComponents);

Arguments:

hColorSpace
A color space object.
lpnColorComponents
Number of components in hColorSpace. For:
DeviceGray, CalGray, Separation: Returns 1.
DeviceRGB, CalRGB: Returns 3.
DeviceCMYK, Lab: Returns 4.
DeviceN, ICCBased: Returns the number of components dependent on the specific color space object.
Indexed: Returns 1. Use IG_PDE_colorspace_get_base_color_components to get the number of components in the base color space.

Description:

Calculates the number of components in a color space.

Return Value:

Error count.


IG_PDE_colorspace_release

Group: PDE Color Space

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_colorspace_release(
HIG_PDE_COLORSPACE hColorSpace );

Arguments:

hColorSpace
Color space object to release.

Description:

Releases a color space object.

Return Value:

Error count.


HIG_PDE_FONT

Type: PDE Font Object

Description:

Handle to the PDE font object. A reference to a font used on a page in a PDF file. It may be equated with a font in the system.

Class Members:

IG_PDE_font_create
Creates a new PDE Font from the specified parameters.
IG_PDE_font_create_from_sysfont
Creates a PDE Font corresponding to a font in the system.
IG_PDE_font_create_from_sysfont_and_encoding
Create a PDE Font from hSysFont and hSysEncoding.
IG_PDE_font_create_from_sysfont_with_params
Used to obtain a PDE Font corresponding to a font in the system.
IG_PDE_font_get_attrs
Gets the attributes for a font object.
IG_PDE_font_create_tounicode_now
This function creates the /ToUnicode table.
IG_PDE_font_create_widths_now
This function creates width entries for font.
IG_PDE_font_embed_now
This function embeds font stream.
IG_PDE_font_embed_now_dont_subset
Embeds the given hFont inside hDoc without creating a subset.
IG_PDE_font_get_create_need_flags
This function returns flags indicating what needs to be done to make hFont complete.
IG_PDE_font_get_codebyte_count
Gets the number of bytes comprising the next code in a string of single or multi-byte character codes.
IG_PDE_font_get_onebyte_encoding
Gets an array of delta encodings for the given one byte PDE Font.
IG_PDE_font_get_sysencoding
Gets the system encoding object associated with a font object.
IG_PDE_font_get_sysfont
Gets the system font object associated with a font object.
IG_PDE_font_get_widths
Gets the widths for a font object.
IG_PDE_font_get_widths_now
Gets a Type0 font's width information for only the characters used in the file.
IG_PDE_font_is_embedded
Tests whether a font is an embedded font in the document in which it was created.
IG_PDE_font_is_multibyte
Tests whether a font contains any multi-byte characters.
IG_PDE_font_set_sysencoding
Sets the system encoding object associated with a font object.
IG_PDE_font_set_sysfont
Sets the system font object to be used with a font object that does not currently have a system font associated with it.
IG_PDE_font_subset_now
Subsets a given PDE Font in hDoc.
IG_PDE_font_sum_widths
Gets the sum to the widths of nTextLen characters from a string of single or multi-byte characters.
IG_PDE_font_translate_glyphids_to_unicode
Translates a string to Unicode values.
IG_PDE_font_release
Releases PDE font object.


IG_PDE_font_create

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_create(
LPAT_PDE_FONTATTRS lpAttrs,
LONG nFirstCharIndex,
LONG nLastCharIndex,
LPSHORT lpWidths,
LPSTR *lpEncoding,
HIG_PDF_ATOM hEncodingBaseName,
HIG_PDF_STREAM hFontStm,
LONG nLen1,
LONG nLen2,
LONG nLen3,
LPHIG_PDE_FONT lphFont);

Arguments:

lpAttrs
Pointer to AT_PDE_FONTATTRS for the font attributes.
nFirstCharIndex
First character index for the widths array, lpWidths.
nLastCharIndex
Last character index for the widths array, lpWidths.
lpWidths
Widths array.
lpEncoding
Array of 256 glyph names specifying the custom encoding. If any pointer is NULL, no encoding information is written for that entry.
hEncodingBaseName
Encoding base name if the encoding is a custom encoding. If encoding is NULL, encodingBaseName is used as the value of the encoding, and must be one of WinAnsiEncoding, MacRomanEncoding, or MacExpertEncoding. If no encoding value is desired, use IG_PDF_ATOM_NULL.
hFontStm
Stream with font information.
nLen1
Length in bytes of the ASCII portion of the Type 1 font file after it has been decoded. For other font formats, such as TrueType or CFF, only Len1 is used, and it is the size of the font.
nLen2
Length in bytes of the encrypted portion of the Type 1 font file after it has been decoded.
nLen3
Length in bytes of the portion of the Type 1 font file that contains the 512 zeros, plus the cleartomark operator, plus any following data.
lphFont
The specified PDE font.

Description:

Creates a new PDE Font from the specified parameters.

The PDE Font may be represented as an embedded font (a FontFile entry in the font descriptor of the PDF file). To create a PDE Font that is stored as an embedded font, the FontFile stream may be passed in hFontStm, and the nLen1, nLen2, and nLen3 parameters contain the Length1, Length2, and Length3 values of the FontFile stream attributes dictionary. See Section 5.8 in the PDF Reference for more information about embedded fonts.

Call IG_PDE_font_release to dispose of the returned font object when finished with it.

Return Value:

Error count.


IG_PDE_font_create_from_sysfont

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_create_from_sysfont(
HIG_PDF_SYSFONT hSysFont,
LONG nCreateFlags,
HIG_PDF_ATOM hSnapshotName,
LPAT_PDF_FIXED mmDesignVec,
LPHIG_PDE_FONT lphFont );

Arguments:

hSysFont
PDF system font object referencing a system font.
nCreateFlags
Indicates whether to embed the font and whether to subset the font. Must be one of enumIGPDEFontCreateFlags. If you want to subset a font, set both the IG_PDE_FONT_CREATE_EMBEDDED and IG_PDE_FONT_WILL_SUBSET flags.
hSnapshotName
Name to be associated with this particular instantiation of the PDE Font.
mmDesignVec
Multiple master font design vector.
lphFont
The PDE Font corresponding to hSysFont.

Description:

Creates a PDE Font corresponding to a font in the system.

If the font is a multiple master font, mmDesignVec points to the design vector, whose length must equal the number of design axes of the font.

The enumIGPDEFontCreateFlags flags IG_PDE_FONT_CREATE_EMBEDDED and IG_PDE_FONT_WILL_SUBSET must both be set in order to subset a font.

If you create a PDE Font that is subsetted, call IG_PDE_font_subset_now on this font afterwards.

Call IG_PDE_font_release to dispose of the returned font object when finished with it.

Return Value:

Error count.


IG_PDE_font_create_from_sysfont_and_encoding

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI
IG_PDE_font_create_from_sysfont_and_encoding(
HIG_PDF_SYSFONT hSysFont,
HIG_PDF_SYSENCODING hSysEncoding,
HIG_PDF_ATOM hUseThisBaseFont,
LONG nCreateFlags,
LPHIG_PDE_FONT lphFont );

Arguments:

hSysFont
PDF system font object referencing a system font.
hSysEncoding
A PDF SysEncoding object.
hUseThisBaseFont
The base font. An error will be set if the base font name passed is a subset name (XXXXXX+FontName) or an empty string.
nCreateFlags
One of the enumIGPDEFontCreateFlags values.
lphFont
The new PDE Font object.

Description:

Create a PDE Font from hSysFont and hSysEncoding. If it fails, it returns an error. User can call IG_PDF_sysfont_get_create_flags to see if the combination of hSysFont and hSysEncoding makes sense.

Call IG_PDE_font_release to dispose of the returned font object when finished with it.

Return Value:

Error count.


IG_PDE_font_create_from_sysfont_with_params

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI
IG_PDE_font_create_from_sysfont_with_params(
HIG_PDF_SYSFONT hSysFont,
LPAT_PDE_FONT_CREATEFROMSYSFONTPARAMS lpParams,
LPHIG_PDE_FONT lphFont );

Arguments:

hSysFont
PDF system font object referencing a system font.
lpParams
Pointer to the parameters structure.
lphFont
The new PDE Font object.

Description:

Used to obtain a PDE Font corresponding to a font in the system.

Call IG_PDE_font_release to dispose of the returned font object when finished with it.

Return Value:

Error count.


IG_PDE_font_get_attrs

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_get_attrs(
HIG_PDE_FONT hFont,
LPAT_PDE_FONTATTRS lpAttrs);

Arguments:

hFont
PDE font whose attributes are found.
lpAttrs
Font attributes return value

Description:

Gets the attributes for a font object.

Return Value:

Error count.


IG_PDE_font_create_tounicode_now

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_create_tounicode_now(
HIG_PDE_FONT hFont,
HIG_PDF_DOC hDoc );

Arguments:

hFont
PDE font to create /ToUnicode table for.
hDoc
The container document

Description:

This function creates the /ToUnicode table. The user can check the return value of IG_PDE_font_get_create_need_flags to see if calling of IG_PDE_font_create_tounicode_now is needed.

Return Value:

Error count.


IG_PDE_font_create_widths_now

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_create_widths_now(
    HIG_PDE_FONT hFont,
    HIG_PDF_DOC hDoc );

Arguments:

hFont
PDE font to create width entries for.
hDoc
The container document

Description:

This function creates width entries for font. The user can check the return value of IG_PDE_font_get_create_need_flags to see if calling of IG_PDE_font_create_widths_now is needed.

Return Value:

Error count.


IG_PDE_font_embed_now

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_embed_now(
HIG_PDE_FONT hFont,
HIG_PDF_DOC hDoc );

Arguments:

hFont
PDE font to embed
hDoc
The container document

Description:

This function embeds font stream. The user can check the return value of IG_PDE_font_get_create_need_flags to see if calling of IG_PDE_font_embed_now is needed.

Return Value:

Error count.


IG_PDE_font_embed_now_dont_subset

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_embed_now_dont_subset(
    HIG_PDE_FONT hFont,
    HIG_PDF_DOC hDoc );

Arguments:

hFont
PDE font to embed
hDoc
The container document

Description:

Embeds the given hFont inside hDoc without creating a subset. Use this method instead of IG_PDE_font_embed_now if you created font with the IG_PDE_FONT_WILL_SUBSET flag but changed your mind.

Return Value:

Error count.


IG_PDE_font_get_create_need_flags

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_get_create_need_flags(
HIG_PDE_FONT hFont,
LPLONG lpnFlags );

Arguments:

hFont
PDE font object
lpnFlags
A value corresponding to enumIGPDEFontCreateNeedFlags.

Description:

This function returns flags indicating what needs to be done to make hFont complete.

IG_PDE_FONT_CREATE_NEED_WIDTHS can be cleared by IG_PDE_font_create_widths_now.

IG_PDE_FONT_CREATE_NEED_TO_UNICODE can be cleared by IG_PDE_font_create_tounicode_now.

IG_PDE_FONT_CREATE_NEED_EMBED can be cleared by IG_PDE_font_create_embed_now.

Return Value:

Error count.


IG_PDE_font_get_codebyte_count

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_get_codebyte_count(
HIG_PDE_FONT hFont,
LPBYTE lpText,
LONG nTextLen,
LPUINT lpnCount );

Arguments:

hFont
PDE font object
lpText
Pointer into a string of characters.
nTextLen
The length, in bytes, of the string of characters, starting with the character pointed to by lpText.
lpnCount
Number of bytes in the next character code pointed to by lpText.

Description:

Gets the number of bytes comprising the next code in a string of single or multi-byte character codes.

Return Value:

Error count.


IG_PDE_font_get_onebyte_encoding

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_get_onebyte_encoding(
HIG_PDE_FONT hFont,
LPHIG_PDF_ATOM lphEncodingDelta,
LPAT_BOOL lpbGotEncodingDelta );

Arguments:

hFont
PDE font object
lphEncodingDelta
Pointer to an atom array that is filled with the delta encodings for font. Each entry is the atom for a glyph name that differs from the base encoding. See Section 5.5.5 in the PDF Reference for more information about font encodings.
The array must be allocated to hold 256 entries.
lpbGotEncodingDelta
True if encodingDelta is filled, False otherwise.

Description:

Gets an array of delta encodings for the given one byte PDE Font.

Return Value:

Error count.


IG_PDE_font_get_sysencoding

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_get_sysencoding(
HIG_PDE_FONT hFont,
LPHIG_PDF_SYSENCODING lphSysEncoding );

Arguments:

hFont
PDE font whose system encoding is found
lphSysEncoding
The system ensoding object.

Description:

Gets the system encoding object associated with a font object.

Return Value:

Error count.


IG_PDE_font_get_sysfont

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_get_sysfont(
HIG_PDE_FONT hFont,
LPHIG_PDF_SYSFONT lphSysFont );

Arguments:

hFont
PDE font whose system font is found
lphSysFont
The system font object.

Description:

Gets the system font object associated with a font object.

Return Value:

Error count.


IG_PDE_font_get_widths

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_get_widths(
HIG_PDE_FONT hFont,
LPSHORT lpWidths );

Arguments:

hFont
PDE font whose widths are found
lpWidths
Pointer to widths array. lpWidths must have room for 256 values. The widths are returned in character space (1000 EM units). An EM is a typographic unit of measurement equal to the size of a font. To convert to text space, divide the value returned by 1000. To convert to user space, multiply the text space value by the font size.

Description:

Gets the widths for a font object.

Return Value:

Error count.


IG_PDE_font_get_widths_now

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_get_widths_now(
HIG_PDE_FONT hFont,
HIG_PDF_DOC hDoc );

Arguments:

hFont
PDE font whose widths are found
hDoc
The container document

Description:

Gets a Type0 font's width information for only the characters used in the file. Call this routine when the font was created with the IG_PDE_FONT_DEFER_WIDTHS flag but without the IG_PDE_FONT_CREATE_EMBEDDED flag (if the font is to be embedded, call IG_PDE_font_subset_now, which also gets the width info).

Return Value:

Error count.


IG_PDE_font_is_embedded

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_is_embedded(
HIG_PDE_FONT hFont,
LPAT_BOOL lpbResult );

Arguments:

hFont
PDE font object
lpbResult
True if the font is embedded, False if it is not, or if it was created in one document and embedded in a different document.

Description:

Tests whether a font is an embedded font in the document in which it was created.

Return Value:

Error count.


IG_PDE_font_is_multibyte

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_is_multibyte(
HIG_PDE_FONT hFont,
LPAT_BOOL lpbResult );

Arguments:

hFont
PDE font object
lpbResult
True if the font contains any multi-byte characters, False otherwise.

Description:

Tests whether a font contains any multi-byte characters.

Return Value:

Error count.


IG_PDE_font_set_sysencoding

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_set_sysencoding(
HIG_PDE_FONT hFont,
HIG_PDF_SYSENCODING hSysEncoding );

Arguments:

hFont
PDE Font whose system encoding is set.
hSysEncoding
The new system encoding object.

Description:

Sets the system encoding object associated with a font object.

NOTE: Changing the system encoding may produce unexpected results.

Return Value:

Error count.


IG_PDE_font_set_sysfont

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_set_sysfont(
HIG_PDE_FONT hFont,
HIG_PDF_SYSFONT hSysFont );

Arguments:

hFont
PDE Font whose system font is set.
hSysFont
The new system font object.

Description:

Sets the system font object to be used with a font object that does not currently have a system font associated with it.

Return Value:

Error count.


IG_PDE_font_subset_now

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_subset_now(
HIG_PDE_FONT hFont,
HIG_PDF_DOC hDoc );

Arguments:

hFont
PDE font to subset
hDoc
The document whose font is subsetted.

Description:

Subsets a given PDE Font in hDoc.

If you created font with IG_PDE_font_create_from_sysfont, you must have set both the IG_PDE_FONT_CREATE_EMBEDDED and IG_PDE_FONT_WILL_SUBSET set in the flags parameter to be able to subset font.

Return Value:

Error count.


IG_PDE_font_sum_widths

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_sum_widths(
HIG_PDE_FONT hFont,
LPBYTE lpText,
LONG nTextLen,
LPLONG lpnSum );

Arguments:

hFont
PDE font object\
lpText
Pointer into a string of characters.
nTextLen
Number of characters in the string.
lpnSum
Width of text string in EM space. (In EM space, the width of "M" is about 1000 EM units).

Description:

Gets the sum to the widths of nTextLen characters from a string of single or multi-byte characters.

Return Value:

Error count.


IG_PDE_font_translate_glyphids_to_unicode

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_translate_glyphids_to_unicode(
HIG_PDE_FONT hFont,
LPBYTE lpText,
LONG nTextLen,
LPBYTE lpUniText,
LONG nUniTextLen,
LPLONG lpnResult );

Arguments:

hFont
PDE font object
lpText
The string to convert.
nTextLen
The length of lpText, in bytes
lpUniText
Buffer to hold the translated string.
nUniTextLen
The size of the lpUniText buffer.
lpnResult
0 if the string was successfully translated. If lpUniText is too small for the translated string, it returns the number of bytes required.

Description:

Translates a string to Unicode values. The PDE Font must have a /ToUnicode table.

Return Value:

Error count.


IG_PDE_font_release

Group: PDE Font

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_font_release(
HIG_PDE_FONT hFont );

Arguments:

hFont
PDE font object to release

Description:

Releases PDE font object.

Return Value:

Error count.


HIG_PDE_ELEMENT

Type: PDE Element Object

Description:

Handle to the PDE element object. Base interface for the elements of a page display list (PDE content) and for clip objects. The general PDE element methods allow you to get and set general element properties.

Class Members:

IG_PDE_element_get_type
Gets the type of an element.
IG_PDE_element_clone
Makes a copy of an element.
IG_PDE_element_is_at_point
Tests whether a point is on an element.
IG_PDE_element_is_at_rect
Tests whether any part of a rectangle is on an element.
IG_PDE_element_get_bbox
Gets the bounding box for an element.
IG_PDE_element_get_clip
Gets the current clip for an element.
IG_PDE_element_get_gstate
Gets the graphics state information for an element.
IG_PDE_element_set_gstate
Sets the graphics state information for an element.
IG_PDE_element_get_matrix
Gets the transformation matrix for an element.
IG_PDE_element_set_matrix
Sets the transformation matrix for an element.
IG_PDE_element_get_dictionary
Returns a Dictionary (OCMD object).
IG_PDE_element_get_unique_id
Returns some 32bit integer that is unique for all Element objects.
IG_PDE_element_has_gstate
Tests if hElement has a graphics state information.
IG_PDE_element_release
Release the specified element.


IG_PDE_element_get_type

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_get_type(
HIG_PDE_ELEMENT hElement,
LPLONG lpnType);

Arguments:

hElement
The element whose type is obtained.
lpnType
Type return value

Description:

Gets the type of an element.

Return Value:

Error count.


IG_PDE_element_clone

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_clone(
HIG_PDE_ELEMENT hElement,
LONG nFlags,
LPHIG_PDE_ELEMENT lphCloneElement);

Arguments:

hElement
The element to copy.
nFlags
Bit field of enumIGPDEElementCopyFlags.
lphCloneElement
A copy of hElement

Description:

Makes a copy of an element. The caller is responsible for releasing the copy with IG_PDE_element_release.

Return Value:

Error count.


IG_PDE_element_is_at_point

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_is_at_point(
HIG_PDE_ELEMENT hElement,
LPAT_PDF_FIXEDPOINT lpPoint,
LPAT_BOOL lpbResult);

Arguments:

hElement
The element to test.
If hElement is a Text or Image, it uses the bounding box of the element to make the check. If the hElement is a Path and it is stroked, it checks if the point is on the path. If the hElement is a Path and it is filled, it checks if the point is in the fill area, taking into consideration whether it is filled using the non-zero winding number rule or the even-odd rule.
lpPoint
The point, specified in user space coordinates.
lpbResult
TRUE if the point is on the element, FALSE otherwise.

Description:

Tests whether a point is on an element.

Return Value:

Error count.


IG_PDE_element_is_at_rect

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_is_at_rect(
HIG_PDE_ELEMENT hElement,
LPAT_PDF_FIXEDRect lpRect,
LPAT_BOOL lpbResult);

Arguments:

hElement
The element to test.
If hElement is a PDE Text or PDE Image, it uses the bounding box of the PDE Element to make the check. If hElement is a PDE Path and it is stroked, it checks if the rectangle is on the path.
If hElement is a PDE Path and it is filled, it checks if the rectangle is in the fill area, taking into consideration whether it is filled using the non-zero winding number rule or the even-odd rule.
lpRect
The rectangle, specified in user space coordinates.
lpbResult
True if any part of the rectangle is on the element, False otherwise.

Description:

Tests whether any part of a rectangle is on an element.

Return Value:

Error count.


IG_PDE_element_get_bbox

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_get_bbox(
HIG_PDE_ELEMENT hElement,
LPAT_PDF_FIXEDRECT lpBBox );

Arguments:

hElement
An element whose bounding box is obtained.
lpBBox
Pointer to a AT_PDF_FIXEDRECT structure specifying the bounding box of hElement, specified in user space coordinates.

Description:

Gets the bounding box for an element.

The returned bounding box is guaranteed to encompass the element, but is not guaranteed to be the smallest box that could contain the element. For example, for an arc, lpBBox encloses the Bezier control points-not just the curve itself.

Return Value:

Error count.


IG_PDE_element_get_clip

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_get_clip(
HIG_PDE_ELEMENT hElement,
LPHIG_PDE_CLIP lphClip );

Arguments:

hElement
An element whose clip is obtained.
NOTE: A clip may be shared by many elements. Use care when modifying a clip. Copy it first if you want to modify the clip for a specific element.
lphClip
Clip object for hElement.

Description:

Gets the current clip for an element.

Return Value:

Error count.


IG_PDE_element_set_clip

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_set_clip(
HIG_PDE_ELEMENT hElement,
HIG_PDE_CLIP hClip );

Arguments:

hElement
An element whose clip is set.
lphClip
The clip to set for hElement.

Description:

Sets the clip for an element.

Return Value:

Error count.


IG_PDE_element_get_gstate

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_get_gstate(
HIG_PDE_ELEMENT hElement,
LPAT_PDE_GRAPHICSTATE lpGstate );

Arguments:

hElement
An element whose graphics state is obtained.
lpGstate
Pointer to AT_PDE_GRAPHICSTATE structure that contains graphics state information for hElement. This graphics state information may contain PDE objects for color spaces or an ExtGState. They are not acquired by this method.
NOTE: For a PDE Image, only the ExtGState value is used for images. For indexed images, the fill color space and values are categorized in the PDE Image object.

Description:

Gets the graphics state information for an element.

This method is only valid for PDE Form, PDE Image, PDE Path,and PDE Shading elements.

NOTE: Non-NULL objects in the graphic state, such as the fill and stroke color spaces, have their reference counts incremented by this method. Be sure to release these non-NULL objects when disposing of lpGstate.

Return Value:

Error count.


IG_PDE_element_set_gstate

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_set_gstate(
HIG_PDE_ELEMENT hElement,
LPAT_PDE_GRAPHICSTATE lpGstate );

Arguments:

hElement
An element whose graphics state is set.
lpGstate
Pointer to AT_PDE_GRAPHICSTATE structure with graphics state information to set for hElement.

Description:

Sets the graphics state information for an element.

This method is valid only for PDE Form, PDE Image, PDE Path, and PDE Shading elements.

Return Value:

Error count.


IG_PDE_element_get_matrix

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_get_matrix(
HIG_PDE_ELEMENT hElement,
LPAT_PDF_FIXEDMATRIX lpMatrix );

Arguments:

hElement
An element whose transformation matrix is obtained.
lpMatrix
Pointer to AT_PDF_FIXEDMATRIX that holds a transformation matrix for hElement. If hElement is a text object, returns the identity matrix.

Description:

Gets the transformation matrix for an element.

This matrix provides the transformation from user space to device space for the element. If there is no cm operator (concatmatrix) in the page stream, the matrix is the identity matrix.

Return Value:

Error count.


IG_PDE_element_set_matrix

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_set_matrix(
HIG_PDE_ELEMENT hElement,
LPAT_PDF_FIXEDMATRIX lpMatrix );

Arguments:

hElement
An element whose transformation matrix is set.
lpMatrix
Pointer to AT_PDF_FIXEDMATRIX that holds the transformation matrix to set for hElement.

Description:

Sets the transformation matrix for an element.

The element may not be a PDE Container, a PDE Group, a PDE Place, or a PDE Text.

Return Value:

Error count.


IG_PDE_element_get_dictionary

Group: PDE Element

Declaration:

IG_PDE_element_get_dictionary(
    HIG_PDE_ELEMENT hElement,
    LPHIG_PDF_DICTIONARY lphOCMD)

Arguments:

hElement
The Source Element.
lphOCMD
The returned Dictionary (OCMD object).

Description:

Returns a Dictionary (OCMD object), which is associated with this Element. If no Dictionary is associated, returns NULL.

Return Value:

Associated Dictionary, or NULL if no Dictionary is associated.


IG_PDE_element_get_unique_id

Group: PDE Object

Declaration:

IG_PDE_element_get_unique_id(
    HIG_PDE_ELEMENT hElement,
    LPLONG lpnId);

Arguments:

hElement
Element object.
lpnId
The unique identifier.

Description:

Returns some 32bit integer that is unique for all Element objects. In other words, it is guaranteed that there cannot be two Element objects with the same UniqueIds.

Can be used for Element objects' identification.

Return Value:

An unique identifier of this Element Object.


IG_PDE_element_has_gstate

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_has_gstate(
HIG_PDE_ELEMENT hElement,
LPAT_PDF_BOOL lpbHasGstate );

Arguments:

hElement
An element whose graphics state is checked.
lpbHasGstate
Returns True if the element has a graphics state; False otherwise.

Description:

Tests if hElement has a graphics state information.

Return Value:

Error count.


IG_PDE_element_release

Group: PDE Element

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_element_release(
HIG_PDE_ELEMENT hElement );

Arguments:

hElement
The element to release.

Description:

Release the specified element.

Return Value:

Error count.


HIG_PDE_CLIP

Type: PDE Clip Object

Description:

Handle to the PDE clip object. Clip - a list of elements containing a list of Paths and Texts that describe a clip state. Clips can be created and built up with PDE Clip methods. Any PDE Element object can have Clip associated with it. Clip objects can contain PDE Containers and PDE Groups to an arbitrary level of nesting. This allows PDE Containers to be used to mark clip objects.

PDE Groups inside PDE Clips that contain at least one PDE Text and no PDE Paths have a special meaning. All PDE Text objects contained in such a PDE Group are considered to be part of the same BT/ET block. This means that the union of these

PDE Texts makes up a single clipping path-as opposed to the intersection of the PDE Texts.

See Section 5.3 in the PDF reference for more information about BT/ET block.

Class Members:

IG_PDE_clip_create
Creates an empty clip object.
IG_PDE_clip_clone
Makes a deep copy of a PDE Clip object.
IG_PDE_clip_add_element
Adds an element to a clip path.
IG_PDE_clip_get_element
Gets an element from a clip object.
IG_PDE_clip_remove_elements
Removes one or more elements from a clip object.
IG_PDE_clip_get_element_count
Gets the number of top-level elements in a clip object.
IG_PDE_clip_enumerate_elements
For a given PDE Clip, enumerates all of the PDE Elements in a flattened manner.


IG_PDE_clip_create

Group: PDE Clip

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_clip_create(
LPHIG_PDE_CLIP lphClip );

Arguments:

lphClip
The newly created clip object.

Description:

Creates an empty clip object. This represents a clipping object that has no effect on elements that refer to it.

Call IG_PDE_element_release to dispose the object.

Return Value:

Error count.


IG_PDE_clip_clone

Group: PDE Clip

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_clip_clone(
HIG_PDE_CLIP hClip,
LPHIG_PDE_CLIP lphCloneClip);

Arguments:

hClip
The clipping path to copy.
lphCloneClip
The deep copy of hClip.

Description:

Makes a deep copy of a PDE Clip object.

Return Value:

Error count.


IG_PDE_clip_add_element

Group: PDE Clip

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_clip_add_element(
HIG_PDE_CLIP hClip,
LONG nAfterIndex,
HIG_PDE_ELEMENT hElement);

Arguments:

hClip
The clip path to which an element is added.
nAfterIndex
The index after which to add hElement. Use IG_PDE_BEFORE_FIRST to insert an element at the beginning of the clip object.
hElement
The element added, which may be a PDE Path, a PDE Text, a PDE Container, a PDE Group or a PDE Place object.

Description:

Adds an element to a clip path.

Return Value:

Error count.


IG_PDE_clip_get_element

Group: PDE Clip

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_clip_get_element(
HIG_PDE_CLIP hClip,
LONG nIndex,
LPHIG_PDE_ELEMENT lphElement);

Arguments:

hClip
The clip object from which an element is obtained.
nIndex
Index of element to get from clip.
lphElement
The element from the clip object

Description:

Gets an element from a clip object.

Return Value:

Error count.


IG_PDE_clip_remove_elements

Group: PDE Clip

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_clip_remove_elements(
HIG_PDE_CLIP hClip,
LONG nIndex,
LONG nCount );

Arguments:

hClip
The clip object from which an element is removed.
nIndex
First element to remove.
nCount
Number of elements to remove.

Description:

Removes one or more elements from a clip object.

Return Value:

Error count.


IG_PDE_clip_get_element_count

Group: PDE Clip

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_clip_get_element_count(
HIG_PDE_CLIP hClip,
LPUINT lpnCount);

Arguments:

hClip
The clip object to examine.
lpnCount
Number of path and charpath elements in clip. If clip contains PDE Groups, this method returns the top-level PDE Path, PDE Text, PDE Container, PDE Group, or PDE Place object. Use IG_PDE_clip_ enumerate_elements to see only the PDE Path and PDE Text objects.
NOTE: PDEGroup is not a persistent object. You cannot save to PDF and re-get group objects.

Description:

Gets the number of top-level elements in a clip object. Top-level elements may be a path or char-path, a marked content container or place, or a group.

Paths are represented as PDE Path objects; char-paths are represented as PDE Text objects.

Return Value:

Error count.


IG_PDE_clip_enumerate_elements

Group: PDE Clip

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_clip_enumerate_elements (
HIG_PDE_CLIP hClip,
LPFNIG_PDE_CLIP_ENUMPROC lpfnEnumProc,
LPVOID lpClientData,
LPAT_PDF_BOOL lpbResult );

Arguments:

hClip
The PDEClip to enumerate.
lpfnEnumProc
Called with each flattened element. Enumeration continues until all elements have been enumerated, or until lpfnEnumProc returns false.
lpClientData
Pointer to user-supplied data to pass to lpfnEnumProc each time it is called.
lpbResult
Returns value of lpfnEnumProc. True if successful, False otherwise.

Description:

For a given PDE Clip, enumerates all of the PDE Elements in a flattened manner. In other words, PDE Containers and PDE Groups nested in the PDE Clip will not be handed back, but any PDE Paths and PDE Texts nested in them will be. Additionally, PDE Place objects inside the PDE Clip are not returned.

Return Value:

Error count.


HIG_PDE_CONTAINER

Type: PDE Container Object

Description:

Handle to the PDE container object. Container - a group of elements on a page in a PDF file. In the PDF file, containers are delimited by Marked Content BMC/EMC or BDC/EMC pairs. Every container has a Marked Content tag associated with it. In addition to grouping a set of elements, a BDC/EMC pair specifies a property list to be associated with the grouping. Thus a container corresponding to a BDC/EMC pair also has a property list dictionary associated with it.

See Section 10.5 in the PDF reference for more information about Marked Content operators.

Class Members:

IG_PDE_container_create
Creates a container object.
IG_PDE_container_get_content
Gets the PDE Content for hContainer.
IG_PDE_container_set_content
Sets the content for a container.
IG_PDE_container_get_dictionary
Gets the Marked Content dictionary for a container.
IG_PDE_container_set_dictionary
Changes the Marked Content dictionary for a container.
IG_PDE_container_get_mctag
Gets the Marked Content tag for a container.
IG_PDE_container_set_mctag
Sets the Marked Content tag for a hContainer.


IG_PDE_container_create

Group: PDE Container

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_container_create(
HIG_PDF_ATOM hMCTag,
HIG_PDF_BASOBJ hDictionary,
AT_PDF_BOOL bIsInline,
LPHIG_PDE_CONTAINER lphContainer );

Arguments:

hMCTag
Tag name for the container.
hDictionary
Optional Marked Content dictionary for the container.
bIsInline
If True, emits container into the page content stream inline.
lphContainer
The newly created container object.

Description:

Creates a container object.

Call IG_PDE_element_release to dispose the object.

Return Value:

Error count.


IG_PDE_container_get_content

Group: PDE Container

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_container_get_content(
HIG_PDE_CONTAINER hContainer,
LPHIG_PDE_CONTENT lphContent );

Arguments:

hContainer
A container whose content is obtained.
lphContent
The PDE Content for hContainer.

Description:

Gets the PDE Content for hContainer.

Return Value:

Error count.


IG_PDE_container_set_content

Group: PDE Container

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_container_set_content(
HIG_PDE_CONTAINER hContainer,
HIG_PDE_CONTENT hContent );

Arguments:

hContainer
A container whose content is set.
hContent
The content of hContainer.

Description:

Sets the content for a container. The existing PDE Content is released by this method.

Return Value:

Error count.


IG_PDE_container_get_dictionary

Group: PDE Container

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_container_get_dictionary(
HIG_PDE_CONTAINER hContainer,
LPHIG_PDF_BASOBJ lphDictionary,
LPAT_PDF_BOOL lpbIsInline,
LPAT_PDF_BOOL lpbResult );

Arguments:

hContainer
A container.
lphDictionary
Marked Content dictionary for hContainer. NULL if hContainer has no Marked Content dictionary.
lpbIsInline
True if the dictionary is inline, false otherwise. Undefined if hContainer has no Marked Content dictionary.
lpbResult
True if hContainer has a Marked Content dictionary, False otherwise.

Description:

Gets the Marked Content dictionary for a container.

Return Value:

Error count.


IG_PDE_container_set_dictionary

Group: PDE Container

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_container_set_dictionary(
HIG_PDE_CONTAINER hContainer,
HIG_PDF_BASOBJ hDictionary,
AT_PDF_BOOL bIsInline );

Arguments:

hContainer
A container whose dictionary is changed.
hDictionary
Marked Content dictionary being set into hContainer.
bIsInline
If True, the dictionary is emitted inline.

Description:

Changes the Marked Content dictionary for a container.

Return Value:

Error count.


IG_PDE_container_get_mctag

Group: PDE Container

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_container_get_mctag (
HIG_PDE_CONTAINER hContainer,
LPHIG_PDF_ATOM lphMCTag );

Arguments:

hContainer
A container.
lphMCTag
Marked Content tag of hContainer. Returns IG_PDF_ATOM_NULL if hContainer has no Marked Content tag.

Description:

Gets the Marked Content tag for a container.

Return Value:

Error count.


IG_PDE_container_set_mctag

Group: PDE Container

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_container_set_mctag (
HIG_PDE_CONTAINER hContainer,
HIG_PDF_ATOM hMCTag );

Arguments:

hContainer
A container to tag.
hMCTag
Marked Content tag.

Description:

Sets the Marked Content tag for a hContainer.

Return Value:

Error count.


HIG_PDE_FORM

Type: PDE Form Object

Description:

Handle to the PDE form object. Form - an element that corresponds to an instance of XObject Form on a page (or other containing stream such as another XObject Form or annotation form). The context associated with this instance includes the actual stream that represents the XObject Form and the initial conditions of the graphics state. The latter consists of the transformation matrix, initial color values, and so forth. It is possible to have two Forms that refer to the same XObject Form. The forms will exist at different places on the same page, depending on the transformation matrix. They may also have different colors or line stroking parameters. In the case of a transparency group, the opacity is specified in the gstate.

Within a Form, each element has its own gstate (or is a container, place, or group object). These gstates are independent of the parent Form gstate. Form elements may have their own opacity.

Content may be obtained from a Form to edit the form's display list.

Class Members:

IG_PDE_form_create
Creates a new form from an existing object.
IG_PDE_form_clone
Creates a new form from an existing form object.
IG_PDE_form_get_content
Gets a PDE Content object for a form.
IG_PDE_form_set_content
Sets the form content.
IG_PDE_form_has_xgroup
Determines whether the XObject form has a Transparency XGroup
IG_PDE_form_get_xgroup
Acquires the transparency group dictionary of the XObject form.
IG_PDE_form_set_xgroup
Sets the transparency group dictionary of the form XObject.


IG_PDE_form_create

Group: PDE Form

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_form_create (
HIG_PDF_BASOBJ hXObject,
HIG_PDF_BASOBJ hResources,
LPAT_PDF_FIXEDMATRIX lpMatrix,
LPHIG_PDE_FORM lphForm );

Arguments:

hXObject
XObject from which a form is created.
hResources
The hXObject's Resources dictionary. If you do not pass in a Resource object, subsequent calls to IG_PDF_page_get_content will fail (after the file is saved).
lpMatrix
Pointer to AT_PDF_FIXEDMATRIX that holds the transformation matrix to use for the form.
lphForm
The newly created form object.

Description:

Creates a new form from an existing object.

Call IG_PDE_element_release to dispose the object.

Return Value:

Error count.


IG_PDE_form_clone

Group: PDE Form

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_form_clone (
HIG_PDE_FORM hForm,
LPHIG_PDE_FORM lphCloneForm );

Arguments:

hForm
Form object from which a new PDE Form is created.
lphCloneForm
The newly created form object.

Description:

Creates a new form from an existing form object. Creates a copy of the PDE Form, including the underlying objects.

Return Value:

Error count.


IG_PDE_form_get_content

Group: PDE Form

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_form_get_content(
HIG_PDE_FORM hForm,
LPHIG_PDE_CONTENT lphContent );

Arguments:

hForm
The form whose content is obtained.
lphContent
Form content object.

Description:

Gets a PDE Content object for a form.

Return Value:

Error count.


IG_PDE_form_set_content

Group: PDE Form

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_form_set_content(
    HIG_PDE_FORM hForm,
    HIG_PDE_CONTENT hContent );

Arguments:

hForm
The form whose content is set.
hContent
The new content for form.

Description:

Sets the form content.

Return Value:

Error count.


IG_PDE_form_has_xgroup

Group: PDE Form

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_form_has_xgroup(
HIG_PDE_FORM hForm,
LPAT_PDF_BOOL lpbHasXGroup );

Arguments:

hForm
The form object.
lpbHasXGroup
True if the XObject form has a Transparency XGroup.

Description:

Determines whether the XObject form has a Transparency XGroup

Return Value:

Error count.


IG_PDE_form_get_xgroup

Group: PDE Form

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_form_get_xgroup(
HIG_PDE_FORM hForm,
LPHIG_PDE_XGROUP lphXGroup );

Arguments:

hForm
The form whose XGroup is obtained.
lphXGroup
Transparency group object.

Description:

Acquires the transparency group dictionary of the XObject form.

Return Value:

Error count.


IG_PDE_form_set_xgroup

Group: PDE Form

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_form_set_xgroup(
HIG_PDE_FORM hForm,
HIG_PDE_XGROUP hXGroup );

Arguments:

hForm
The form whose XGroup is set.
hXGroup
The transparency dictionary.

Description:

Sets the transparency group dictionary of the form XObject.

Return Value:

Error count.


HIG_PDE_GROUP

Type: PDE Group Object

Description:

Handle to the PDE group object. Group - an in-memory representation of objects in Content. It has no state and is not represented in any way in a content stream (that is, Content).

When used in a Clip, this object is used to associate Text objects into a single clipping object.

Class Members:

IG_PDE_group_create
Creates a PDE Group object.
IG_PDE_group_get_content
Gets a PDE Content object for a group.
IG_PDE_group_set_content
Sets the group's content.


IG_PDE_group_create

Group: PDE Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_group_create (
LPHIG_PDE_GROUP lphGroup );

Arguments:

lphGroup
The newly created group object.

Description:

Creates a PDE Group object.

Return Value:

Error count.


IG_PDE_group_get_content

Group: PDE Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_group_get_content(
HIG_PDE_GROUP hGroup,
LPHIG_PDE_CONTENT lphContent );

Arguments:

hGroup
The group whose content is obtained.
lphContent
Group content object.

Description:

Gets a PDE Content object for a group.

Return Value:

Error count.


IG_PDE_group_set_content

Group: PDE Group

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_group_set_content(
HIG_PDE_GROUP hGroup,
HIG_PDE_CONTENT hContent );

Arguments:

hGroup
The group whose content is set.
hContent
The new content for group.

Description:

Sets the group's content.

Return Value:

Error count.


HIG_PDE_IMAGE

Type: PDE Image Object

Description:

Handle to the PDE image object. Image - an element that contains an Image XObject or in-line image. You can associate data or a stream with an image.

Class Members:

IG_PDE_image_create
Creates an image object.
IG_PDE_image_is_data_encoded
Determines if image data is encoded or not.
IG_PDE_image_get_attrs
Gets the attributes for an image.
IG_PDE_image_get_color_mask
Gets the Mask entry from the image dictionary.
IG_PDE_image_get_colorspace
Gets the color space object for an image.
IG_PDE_image_get_data
Gets an image's data.
IG_PDE_image_get_data_length
Gets the length of data for an image.
IG_PDE_image_get_data_stream
Gets a data stream for an image.
IG_PDE_image_get_decode_array
Gets the decode array for an image.
IG_PDE_image_get_filter_array
Gets the filter array for an image.
IG_PDE_image_get_matte_array
Gets the matte array for the image XObject.
IG_PDE_image_get_soft_mask
Gets the soft mask for an image.
IG_PDE_image_has_soft_mask
Checks whether the image has a soft mask.
IG_PDE_image_is_xobject
Determines if an image is an XObject image.
IG_PDE_image_set_color_mask
Sets the color space of the image.
IG_PDE_image_set_colorspace
Sets the Mask entry from the image dictionary.
IG_PDE_image_set_data
Sets data for an image.
IG_PDE_image_set_data_stream
Sets a data stream for an image.
IG_PDE_image_set_decode_array
Sets the decode array of an image.
IG_PDE_image_set_matte_array
Sets the matte array for the image XObject.
IG_PDE_image_set_soft_mask
Sets the soft mask.


IG_PDE_image_create

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_create(
LPAT_PDE_IMAGEATTRS lpAttrs,
LPAT_PDF_FIXEDMATRIX lpMatrix,
LONG nFlag,
HIG_PDE_COLORSPACE hColorSpace,
LPAT_PDE_COLORVALUE lpColorValue,
LPAT_PDE_FILTERARRAY lpFilters,
HIG_PDF_STREAM hDataStream,
LPBYTE lpData,
LONG nDataLen,
LPHIG_PDE_IMAGE lphImage );

Arguments:

lpAttrs
Pointer to AT_PDE_IMAGEATTRS with attributes of the image.
lpMatrix
Pointer to AT_PDF_FIXEDMATRIX that holds the transformation matrix to use for the image.
nFlag
enumIGPDEImageDataFlags flags. If the AT_PDE_IMAGE_ENCODED_DATA flag is set, and the data is provided directly (not as a stream), then nDataLen must specify the length of data.
hColorSpace
Color space of the image. When the image is an imagemask, hColorSpace is the color space of the lpColorValue argument.
lpColorValue
Pointer to AT_PDE_COLORVALUE structure. If the image is an image mask, lpColorValue must be provided.
lpFilters
Pointer to AT_PDE_FILTERARRAY structure that specifies which filters to use in encoding the contents; may be NULL. Filters will be used to encode the data in the order in which they are specified in the array.
hDataStream
Stream holding the image data.
lpData
Image data. If hDataStream is non-NULL, data is ignored. If there is a great deal of data, as for a large image, it is recommended you use the hDataStream parameter for the image data.
nDataLen
Encoded length of lpData, in bytes.
lphImage
The image object.

Description:

Creates an image object.

The image data may be specified as a stream or as a buffer. If hDataStream is non-NULL, lpData is ignored.

See IG_PDE_image_set_data_stream for information on handling the stream.

The caller must dispose of hDataStream after calling this method.

Call IG_PDE_element_release to dispose the created image object when finished with it.

Return Value:

Error count.


IG_PDE_image_is_data_encoded

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_is_data_encoded(
HIG_PDE_IMAGE hImage,
LPAT_PDF_BOOL lpbIsEncoded,
LPDWORD lpnEncodedLen );

Arguments:

hImage
Image to examine.
lpbIsEncoded
True if IG_PDE_image_get_data returns encoded data, false otherwise. Returns false for XObject images.
lpnEncodedLen
Length of the encoded data-if the data is encoded, that is, lpbIsEncoded returns true.

Description:

Determines if image data is encoded or not. Used only for inline images; not relevant to XObject images.

lpbIsEncoded always returns false for XObject images; XObject image data can be obtained from IG_PDE_image_get_data or IG_PDE_image_get_data_stream, either encoded or decoded.

Only if IG_PDE_image_create is used to explicitly create a new image using encoded data does lpbIsEncoded returns true.

Return Value:

Error count.


IG_PDE_image_get_attrs

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_get_attrs (
HIG_PDE_IMAGE hImage,
LPAT_PDE_IMAGEATTRS lpAttrs );

Arguments:

hImage
Image whose attributes are obtained.
lpAttrs
Pointer to AT_PDE_IMAGEATTRS structure with attributes of image.

Description:

Gets the attributes for an image.

Return Value:

Error count.


IG_PDE_image_get_color_mask

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_get_color_mask(
    HIG_PDE_IMAGE hImage,
    LPLONG lpMask,
    LPUINT lpnLen
    );

Arguments:

hImage
The image object whose color mask is obtained.
lpMask
A pointer to the array of LONG values to fill with color mask values. lpMask must contain enough values to hold the entire color mask array.
lpnLen
The number of color mask elements obtained by the method - size of lpMask array.

Description:

Use this method to obtain the Mask entry from the image dictionary. The mask entry is an array specifying a range of colors to be masked out. Samples in the image that fall within this range are not painted, allowing the existing background to show through. The effect is similar to that of the video technique known as chroma-key.

The value of each Mask entry is an array of 2n integers, [min1 max1 ... minn maxn], where n is the number of color components in the image's color space. Each integer must be in the range 0 to (2^BitsPerComponent - 1), representing color values before decoding with the Decode array. An image sample is masked (not painted) if all of its color components before decoding, c1...cn, fall within the specified ranges.

Return Value:

Error count.


IG_PDE_image_get_colorspace

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_get_colorspace (
HIG_PDE_IMAGE hImage,
LPHIG_PDE_COLORSPACE lphColorSpace );

Arguments:

hImage
Image whose colorspace is obtained.
lphColorSpace
Color space for hImage. Returns NULL if hImage is an image mask.

Description:

Gets the color space object for an image.

Return Value:

Error count.


IG_PDE_image_get_data

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_get_data (
HIG_PDE_IMAGE hImage,
LONG nFlags,
LPBYTE lpData );

Arguments:

hImage
Image whose data is obtained.
nFlags
Unused, must be 0.
lpData
Image data. If the data is decoded, lpData must be large enough to contain the number of bytes specified in the AT_PDE_IMAGEATTRS structure obtained by IG_PDE_image_get_attrs. If the data is encoded, lpData must be large enough to contain the number of bytes in the lpnEncodedLen parameter obtained by IG_PDE_image_is_data_encoded.

Description:

Gets an image's data.

If the image is a XObject image, data is always returned as decoded data.

See the note about inline images under IG_PDE_image_is_data_encoded.

Return Value:

Error count.


IG_PDE_image_get_data_length

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_get_data_length (
HIG_PDE_IMAGE hImage,
LPLONG lpnLength );

Arguments:

hImage
Image whose data length is obtained.
lpnLength
Number of bytes of image data, specified by the width, height, bits per component, and color space of the image.

Description:

Gets the length of data for an image.

Return Value:

Error count.


IG_PDE_image_get_data_stream

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_get_data_stream (
HIG_PDE_IMAGE hImage,
LONG nFlags,
LPHIG_PDF_STREAM lphStream );

Arguments:

hImage
Image whose data stream is obtained.
nFlags
enumIGPDEImageDataFlags flags. If the AT_PDE_IMAGE_ENCODED_DATA flag is set, data is returned in encoded form. Otherwise, data is decoded.
lphStream
Stream for hImage.

Description:

Gets a data stream for an image. May only be called for XObject images.

The caller must dispose of the returned stream by calling IG_PDF_stream_close.

Return Value:

Error count.


IG_PDE_image_get_decode_array

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_get_decode_array (
HIG_PDE_IMAGE hImage,
LPAT_PDF_FIXED lpDecode,
LONG nDecodeSize,
LPLONG lpnLength );

Arguments:

hImage
The image whose decode array is obtained.
lpDecode
Pointer to the decode array. If NULL, the number of decode elements required is returned via lpnLength.
nDecodeSize
Size of lpDecode in bytes.
lpnLength
Number of elements in the decode array.

Description:

Gets the decode array for an image.

Return Value:

Error count.


IG_PDE_image_get_filter_array

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_get_filter_array (
HIG_PDE_IMAGE hImage,
LPAT_PDE_FILTERARRAY lpFilters
LPLONG lpnLength );

Arguments:

hImage
Image whose filter array is obtained.
lpFilters
Pointer to AT_PDE_FILTERARRAY structure to fill with the current filter array for the image. lpFilters must be large enough to contain all of the elements. May be NULL to obtain the number of filter elements via lpnLength.
lpnLength
Number of filter elements.

Description:

Gets the filter array for an image.

Return Value:

Error count.


IG_PDE_image_get_matte_array

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_get_matte_array (
HIG_PDE_IMAGE hImage,
LPAT_PDF_FIXED lpMatte,
LONG nValuesCount,
LPLONG lpnLength );

Arguments:

hImage
The image XObject.
lpMatte
An array of values.
nValuesCount
The number of values in lpMatte.
lpnLength
Number of values copied.

Description:

Gets the matte array for the image XObject.

Return Value:

Error count.


IG_PDE_image_get_soft_mask

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_get_soft_mask (
HIG_PDE_IMAGE hImage,
LPHIG_PDE_IMAGE lphSoftMask );

Arguments:

hImage
The image object.
lphSoftMask
The soft mask for image.

Description:

Gets the soft mask for an image.

Use IG_PDE_element_release to dispose of the object when it is no longer referenced.

Return Value:

Error count.


IG_PDE_image_has_soft_mask

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_has_soft_mask (
HIG_PDE_IMAGE hImage,
LPAT_PDF_BOOL lpbHasSoftMask );

Arguments:

hImage
The image object.
lpbHasSoftMask
True if the soft mask exists; False otherwise.

Description:

Checks whether the image has a soft mask.

Return Value:

Error count.


IG_PDE_image_is_xobject

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_is_xobject (
HIG_PDE_IMAGE hImage,
LPAT_PDF_BOOL lpbIsXObject );

Arguments:

hImage
The image object.
lpbIsXObject
Trrue if the image is an XObject image, false otherwise.

Description:

Determines if an image is an XObject image.

Return Value:

Error count.


IG_PDE_image_set_color_mask

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_set_color_mask(
    HIG_PDE_IMAGE hImage,
    LPLONG lpMask,
    UINT nLen
    );

Arguments:

hImage
The image object whose color mask is set.
lpMask
A pointer to the array of LONG values containing the color mask values.
nLen
The number of color mask elements in lpMask - size of lpMask array.

Description:

Use this method to set the Mask entry from the image dictionary. The mask entry is an array specifying a range of colors to be masked out. Samples in the image that fall within this range are not painted, allowing the existing background to show through. The effect is similar to that of the video technique known as chroma-key.

The value of each Mask entry is an array of 2n integers, [min1 max1 ... minn maxn], where n is the number of color components in the image's color space. Each integer must be in the range 0 to (2^BitsPerComponent - 1), representing color values before decoding with the Decode array. An image sample is masked (not painted) if all of its color components before decoding, c1...cn, fall within the specified ranges.

Return Value:

Error count.

Example:

//24-bit rgb color mask with 1 mask entry
LONG lpMask[] = {250, 255, 250, 255, 250, 255};
int iMaskLen=6;
IG_PDE_image_set_color_mask(hElement,lpMask,iMaskLen);


IG_PDE_image_set_colorspace

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_set_colorspace (
HIG_PDE_IMAGE hImage,
HIG_PDE_COLORSPACE hColorSpace );

Arguments:

hImage
Image whose colorspace is set.
hColorSpace
PDE ColorSpace object.

Description:

Sets the color space of the image.

Return Value:

Error count.


IG_PDE_image_set_data

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_set_data (
HIG_PDE_IMAGE hImage,
LONG nFlags,
LPBYTE lpData,
LONG nLength );

Arguments:

hImage
Image whose data is set.
nFlags
A set of enumIGPDEImageDataFlags flags. If AT_PDE_IMAGE_ENCODED_DATA is set, the data must be encoded for the current filters, and nLength is the length of the encoded data.
If the AT_PDE_IMAGE_ENCODED_DATA flag is not set, data is not encoded and nLength is the size of the decoded data.
lpData
Image data.
nLength
Length of data.

Description:

Sets data for an image.

Return Value:

Error count.


IG_PDE_image_set_data_stream

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_set_data_stream (
HIG_PDE_IMAGE hImage,
LONG nFlags,
LPAT_PDE_FILTERARRAY lpFilters,
HIG_PDF_STREAM hDataStream );

Arguments:

hImage
Image whose data stream is set.
nFlags
enumIGPDEImageDataFlags flags. If the AT_PDE_IMAGE_ENCODED_DATA flag is set, the stream must be encoded.
lpFilters
Pointer to AT_PDE_FILTERARRAY structure. If not NULL, is used to build the objects for the Filter, DecodeParms, and EncodeParms objects. If lpFilters is NULL, the existing Filter and DecodeParms are used. EncodeParms is set to DecodeParms if it exists.
hDataStream
Stream for the image data.

Description:

Sets a data stream for an image. Can only be used for XObject images.

Return Value:

Error count.


IG_PDE_image_set_decode_array

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_set_decode_array (
HIG_PDE_IMAGE hImage,
LPAT_PDF_FIXED lpDecode,
LONG nDecodeSize );

Arguments:

hImage
Image whose decode array is set.
lpDecode
Pointer to the decode array.
nDecodeSize
Size of decode array in bytes.

Description:

Sets the decode array of an image.

Normally, the decode array is accessed through the decode field in the AT_PDE_IMAGEATTRS structure. However, this method defines a decode array to handle images with a color space that has more than 4 components.

Return Value:

Error count.


IG_PDE_image_set_matte_array

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_set_matte_array (
HIG_PDE_IMAGE hImage,
LPAT_PDF_FIXED lpMatte,
LONG nValuesCount );

Arguments:

hImage
The image XObject.
lpMatte
An array of values.
nValuesCount
The number of values in lpMatte.

Description:

Sets the matte array for the image XObject.

Return Value:

Error count.


IG_PDE_image_set_soft_mask

Group: PDE Image

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_image_set_soft_mask (
HIG_PDE_IMAGE hImage,
HIG_PDE_IMAGE hSoftMask );

Arguments:

hImage
The image XObject.
hSoftMask
The soft mask.

Description:

Sets the soft mask.

Return Value:

Error count.


HIG_PDE_PATH

Type: PDE Path Object

Description:

Handle to the PDE path object./ Path - an element that contains a path. Path objects can be stroked, filled, and/or serve as a clipping path.

Class Members:

IG_PDE_path_create
Creates an empty path element.
IG_PDE_path_add_segment
Adds a segment to a path.
IG_PDE_path_get_data
Gets the size of the path data and, optionally, the path data.
IG_PDE_path_set_data
Sets new path data for a path element.
IG_PDE_path_get_paint_op
Gets the fill and stroke attributes of a path.
IG_PDE_path_set_paint_op
Sets the fill and stroke attributes of a path.


IG_PDE_path_create

Group: PDE Path

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_path_create(
LPHIG_PDE_PATH lphPath );

Arguments:

lphPath
Newly created empty path element.

Description:

Creates an empty path element.

Call IG_PDE_element_release to dispose the created path object when finished with it.

Return Value:

Error count.


IG_PDE_path_add_segment

Group: PDE Path

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_path_add_segment(
HIG_PDE_PATH hPath,
LONG nSegType,
AT_PDF_FIXED x1,
AT_PDF_FIXED y1,
AT_PDF_FIXED x2,
AT_PDF_FIXED y2,
AT_PDF_FIXED x3,
AT_PDF_FIXED y3 );

Arguments:

hPath
The path to which a segment is added.
nSegType
A enumIGPDEPathElementType value indicating the type of path to add.
x1
x-coordinate of first point.
y1
y-coordinate of first point.
x2
x-coordinate of second point.
y2
y-coordinate of second point.
x3
x-coordinate of third point.
y3
y-coordinate of third point.

Description:

Adds a segment to a path. The number of AT_PDF_FIXED values used depends upon nSegType:

IG_PDE_MOVE_TO: x1, y1

IG_PDE_LINE_TO: x1, y1

IG_PDE_CURVE_TO: x1, y1, x2, y2, x3, y3

IG_PDE_CURVE_TO_V: x1, y1, x2, y2

IG_PDE_CURVE_TO_Y: x1, y1, x2, y2

IG_PDE_RECT: x1, y1, x2 (width), y2 (height)

IG_PDE_CLOSE_PATH: None

Return Value:

Error count.


IG_PDE_path_get_data

Group: PDE Path

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_path_get_data(
    HIG_PDE_PATH hPath,
    LPLONG lpData,
    LONG nDataSize,
    LPLONG lpnLenght );

Arguments:

hPath
The path whose data is obtained.
lpData
Pointer to path data. If lpData is non-NULL, it contains a variable-sized array of path operators and operands. The format is a 32-bit operator followed by 0 to 3 AT_PDF_FIXEDPOINT values, depending on the operator. Opcodes are codes for moveto, lineto, curveto, rect, or closepath operators; operands are AT_PDF_FIXEDPOINT values.
If data is NULL, the number of bytes required for data is returned in lpnLenght.
NOTE: Returns "raw" path data. If you want the points in page coordinates, concatenate the path data points with the PDE Element matrix obtained from IG_PDE_element_get_matrix.
nDataSize
Specifies the size of the buffer provided in data. If it is less than the length of the path data, the method copies datasize bytes.
lpnLength
Length of data of hPath.

Description:

Gets the size of the path data and, optionally, the path data.

Return Value:

Error count.


IG_PDE_path_set_data

Group: PDE Path

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_path_set_data(
HIG_PDE_PATH hPath,
LPLONG lpData,
LONG nDataSize );

Arguments:

hPath
The path whose data is set.
lpData
Pointer to path data. It is a variable-sized array of path operators and operands. The format is a 32-bit operator followed by 0 to 3 AT_PDF_FIXEDPOINT values, depending on the operator. Operators are codes for moveto, lineto, curveto, rect, or closepath operators and must be one of enumIGPDEPathElementType. Operands are AT_PDF_FIXEDPOINT values.
The data is copied into hPath object.
nDataSize
Size of the new path data, in bytes.

Description:

Sets new path data for a path element.

Return Value:

Error count.


IG_PDE_path_get_paint_op

Group: PDE Path

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_path_get_paint_op(
HIG_PDE_PATH hPath,
LPLONG lpnPaintOpAttrs );

Arguments:

hPath
The path whose fill and stroke attributes are obtained.
lpnPaintOpAttrs
A set of enumIGPDEPathOpFlags flags describing fill and stroke attributes.

Description:

Gets the fill and stroke attributes of a path.

Return Value:

Error count.


IG_PDE_path_set_paint_op

Group: PDE Path

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_path_set_paint_op(
HIG_PDE_PATH hPath,
LONG nPaintOpAttrs );

Arguments:

hPath
The path whose fill and stroke attributes are set.
nPaintOpAttrs
The operation to set; must be one of enumIGPDEPathOpFlags.

Description:

Sets the fill and stroke attributes of a path.

Return Value:

Error count.


HIG_PDE_PLACE

Type: PDE Place Object

Description:

Handle to the PDE place object. Place - an element that marks a place on a page in a PDF file. In a PDF file, a place is represented by the MP or DP Marked Content operators.

Marked content is useful for adding structure information to a PDF file. For instance, a drawing program may want to mark a point with information, such as the start of a path of a certain type. Marked content provides a way to retain this information in the PDF file. A

DP operator functions the same as the MP operator and, in addition, allows a property list dictionary to be associated with a place.

Class Members:

IG_PDE_place_create
Creates a place object.
IG_PDE_place_get_dictionary
Gets the Marked Content dictionary for hPlace.
IG_PDE_place_set_dictionary
Sets the Marked Content dictionary for hPlace.
IG_PDE_place_get_mctag
Gets the Marked Content tag for a hPlace.
IG_PDE_place_set_mctag
Sets the Marked Content tag for a hPlace.


IG_PDE_place_create

Group: PDE Place

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_place_create(
HIG_PDF_ATOM mcTag,
HIG_PDF_BASOBJ mcDict,
AT_PDF_BOOL bIsInline
LPHIG_PDE_PLACE lphPlace );

Arguments:

mcTag
Tag name for the place. Must not contain any white space characters (for example, spaces or tabs).
mcDict
Optional Marked Content dictionary associated with the place.
bIsInline
If True, place is emitted into the page content stream inline.
lphPlace
The place object

Description:

Creates a place object.

Call IG_PDE_element_release to dispose the created place object when finished with it.

Return Value:

Error count.


IG_PDE_place_get_dictionary

Group: PDE Place

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_place_get_dictionary(
HIG_PDE_PLACE hPlace,
LPHIG_PDF_BASOBJ lpmcDict,
LPAT_PDF_BOOL lpbIsInline,
LPAT_PDF_BOOL lpbResult );

Arguments:

hPlace
The place whose Marked Content dictionary is obtained.
lpmcDict
Pointer to the Marked Content dictionary; may be NULL.
lpbIsInline
If True, the Marked Content dictionary is inline; may be NULL.
lpbResult
True if dictionary is obtained, False if no dictionary is present.

Description:

Gets the Marked Content dictionary for hPlace.

Return Value:

Error count.


IG_PDE_place_set_dictionary

Group: PDE Place

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_place_set_dictionary(
HIG_PDE_PLACE hPlace,
HIG_PDF_BASOBJ mcDict,
AT_PDF_BOOL bIsInline );

Arguments:

hPlace
The place whose Marked Content dictionary is set.
lpmcDict
Marked Content dictionary for hPlace.
lpbIsInline
If True, the dictionary is emitted inline.

Description:

Sets the Marked Content dictionary for hPlace.

Return Value:

Error count.


IG_PDE_place_get_mctag

Group: PDE Place

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_place_get_mctag(
HIG_PDE_PLACE hPlace,
LPHIG_PDF_ATOM lpmcTag );

Arguments:

hPlace
The place whose Marked Content tag is obtained.
lpmcTag
Tag for hPlace.

Description:

Gets the Marked Content tag for a hPlace.

Return Value:

Error count.


IG_PDE_place_set_mctag

Group: PDE Place

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_place_set_mctag(
HIG_PDE_PLACE hPlace,
HIG_PDF_ATOM mcTag );

Arguments:

hPlace
The place whose Marked Content tag is set.
mcTag
The tag for hPlace.

Description:

Sets the Marked Content tag for a hPlace.

Return Value:

Error count.


HIG_PDE_POSTSCRIPT

Type: PDE PostScript Object

Description:

Handle to the PDE PostScript object. PostScript - an element representing in-line or XObject pass-through PostScript object. XObject PostScripts are listed in page XObject resources.

Class Members:

IG_PDE_postscript_create
Creates a PDE PostScript object.
IG_PDE_postscript_get_attrs
Gets hPostScript attributes.
IG_PDE_postscript_get_data
Gets all or part of the image data.
IG_PDE_postscript_set_data
Sets the data for hPostScript.
IG_PDE_postscript_get_data_stream
Gets a stream for the data.
IG_PDE_postscript_set_data_stream
Sets a stream for the data.


IG_PDE_postscript_create

Group: PDE PostScript

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_postscript_create(
LPAT_PDE_PSATTRS lpAttrs,
HIG_PDF_STREAM hDataStream,
LPBYTE lpData,
LONG nDataSize
LPHIG_PDE_POSTSCRIPT lphPostScript );

Arguments:

lpAttrs
Pointer to AT_PDE_PSATTRS attributes data structure.
hDataStream
Data stream. May be NULL.
lpData
Data. May be NULL.
nDataSize
Number of bytes of data.
lphPostScript
The postscript object

Description:

Creates a PDE PostScript object. lpData and hDataStream may be NULL. If so, use IG_PDE_postscript_set_data and IG_PDE_postscript_set_data_stream to attach data to the object. If hDataStream is non-NULL, then data will be ignored.

If data is non-NULL and hDataStream is NULL, the data must contain nDataSize number of bytes as specified in the AT_PDE_PSATTRS.

Call IG_PDE_element_release to dispose the created object when finished with it.

Return Value:

Error count.


IG_PDE_postscript_get_attrs

Group: PDE PostScript

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_postscript_get_attrs(
HIG_PDE_POSTSCRIPT hPostScript,
LPAT_PDE_PSATTRS lpAttrs);

Arguments:

hPostScript
PDE postscript object.
lpAttrs
Pointer to AT_PDE_PSATTRS data structure containing the attributes information.

Description:

Gets hPostScript attributes.

Return Value:

Error count.


IG_PDE_postscript_get_data

Group: PDE PostScript

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_postscript_get_data (
HIG_PDE_POSTSCRIPT hPostScript,
LPBYTE lpBuffer,
LONG nBufferSize,
LONG nOffset,
LPLONG lpnBytesWritten);

Arguments:

hPostScript
PDE postscript object.
lpBuffer
Receives the data.
nBufferSize
Size of the buffer.
nOffset
Offset into the source data at which to start filling buffer.
lpnBytesWritten
The number of bytes written into the buffer. If it is less than nBufferSize, then there is no more data.

Description:

Gets all or part of the image data.

Return Value:

Error count.


IG_PDE_postscript_set_data

Group: PDE PostScript

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_postscript_set_data (
HIG_PDE_POSTSCRIPT hPostScript,
LPBYTE lpBuffer,
LONG nBufferSize );

Arguments:

hPostScript
PDE postscript object.
lpBuffer
Contains the data.
nBufferSize
Length of the data in bytes.

Description:

Sets the data for hPostScript.

Return Value:

Error count.


IG_PDE_postscript_get_data_stream

Group: PDE PostScript

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_postscript_get_data_stream (
HIG_PDE_POSTSCRIPT hPostScript,
LPHIG_PDF_STREAM lphStream );

Arguments:

hPostScript
PDE postscript object.
lphStream
Stream for hPostScript.

Description:

Gets a stream for the data. The data in the stream is decoded (no filters).

The caller must dispose of the returned stream by calling IG_PDF_stream_close.

Return Value:

Error count.


IG_PDE_postscript_set_data_stream

Group: PDE PostScript

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_postscript_set_data_stream (
HIG_PDE_POSTSCRIPT hPostScript,
HIG_PDF_STREAM hStream );

Arguments:

hPostScript
PDE postscript object.
hStream
Stream for the data.

Description:

Sets a stream for the data. The data must be un-encoded (no filters).

Return Value:

Error count.


HIG_PDE_SOFTMASK

Type: PDE Soft Mask Object

Description:

Handle to the PDE soft mask object. SoftMask- an object for creating and manipulating a soft mask in a PDF file.

Class Members:

IG_PDE_softmask_create
Creates a new soft mask object.
IG_PDE_softmask_create_from_name
Create a new soft mask from a name.
IG_PDE_softmask_get_form
Acquires the form that defines the soft mask.
IG_PDE_softmask_set_form
Sets the form that defines the soft mask.
IG_PDE_softmask_get_backdrop_color
Gets the array of color values of the backdrop color.
IG_PDE_softmask_set_backdrop_color
Sets the backdrop color values.
IG_PDE_softmask_get_name
Gets the soft mask name.


IG_PDE_softmask_create

Group: PDE Soft Mask

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_softmask_create(
HIG_PDF_DOC hDoc,
LONG nType,
HIG_PDE_FORM hForm,
LPHIG_PDE_SOFTMASK lphSoftMask );

Arguments:

hDoc
The container document.
nType
Specifies how the mask is to be computed. One of the enumIGPDESoftMaskCreateFlags.
hForm
The form XObject that defines the soft mask. It is the source of the mask values and the color space in which the composite computation is to be done.
lphSoftMask
The newly created object.

Description:

Creates a new soft mask object.

Call IG_PDE_element_release to dispose the created object when finished with it.

Return Value:

Error count.


IG_PDE_softmask_create_from_name

Group: PDE Soft Mask

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_softmask_create_from_name(
HIG_PDF_ATOM hName,
LPHIG_PDE_SOFTMASK lphSoftMask );

Arguments:

hName
The new name for the soft mask.
NOTE: Currently, the only valid name is None.
lphSoftMask
The newly created object.

Description:

Create a new soft mask from a name.

Call IG_PDE_element_release to dispose the created object when finished with it.

Return Value:

Error count.


IG_PDE_softmask_get_form

Group: PDE Soft Mask

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_softmask_get_form(
HIG_PDE_SOFTMASK hSoftMask,
LPAT_PDF_FIXEDMATRIX lpMatrix,
LPHIG_PDE_FORM lphForm );

Arguments:

hSoftMask
The soft mask object.
lpMatrix
Matrix defining the transformation from coordinate space to user space.
lphForm
The XObject form of the soft mask.

Description:

Acquires the form that defines the soft mask.

Return Value:

Error count.


IG_PDE_softmask_set_form

Group: PDE Soft Mask

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_softmask_set_form(
HIG_PDE_SOFTMASK hSoftMask,
HIG_PDE_FORM hForm );

Arguments:

hSoftMask
The soft mask object.
hForm
The form XObject.

Description:

Sets the form that defines the soft mask.

Return Value:

Error count.


IG_PDE_softmask_get_backdrop_color

Group: PDE Soft Mask

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_softmask_get_backdrop_color (
HIG_PDE_SOFTMASK hSoftMask,
LPAT_PDF_FIXED lpColorValues,
LONG nColorValuesLen,
LPLONG lpnCount );

Arguments:

hSoftMask
The soft mask object.
lpColorValues
Pointer to an array of color values. If NULL , the number of color values is returned in lpnCount.
nColorValuesLen
Length of the array lpColorValues.
lpnCount
Number of values copied.

Description:

Gets the array of color values of the backdrop color. Given a pointer to an array and the length of the array, copies the color values to that array and returns the number of values copied. If the pointer to the array is NULL, the number of color values is returned in lpnCount.

Return Value:

Error count.


IG_PDE_softmask_set_backdrop_color

Group: PDE Soft Mask

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_softmask_set_backdrop_color (
HIG_PDE_SOFTMASK hSoftMask,
LPAT_PDF_FIXED lpColorValues,
LONG nColorValuesLen );

Arguments:

hSoftMask
The soft mask object.
lpColorValues
Pointer to an array of color values.
nColorValuesLen
The number of values pointed to by lpColorValues.

Description:

Sets the backdrop color values.

Return Value:

Error count.


IG_PDE_softmask_get_name

Group: PDE Soft Mask

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_softmask_get_name (
HIG_PDE_SOFTMASK hSoftMask,
LPHIG_PDF_ATOM lphName );

Arguments:

hSoftMask
The soft mask object.
lphName
Soft mask name if it is a name; IG_PDF_ATOM_NULL otherwise.

Description:

Gets the soft mask name.

Return Value:

Error count.


HIG_PDE_SHADING

Type: PDE Shading Object

Description:

Handle to the PDE shading object. Shading - an element that represents smooth shading.

Class Members:

IG_PDE_shading_create
Creates a smooth shading object.
IG_PDE_shading_get_dictionary
Gets the dictionary for a shading.


IG_PDE_shading_create

Group: PDE Shading

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_shading_create (
HIG_PDF_BASOBJ hDictionary,
LPAT_PDF_FIXEDMATRIX lpMatrix,
LPHIG_PDE_SHADING lphShading );

Arguments:

hDictionary
The shading dictionary.
lpMatrix
The location and transformation matrix of the shading object.
lphShading
A smooth shading object.

Description:

Creates a smooth shading object.

Call IG_PDE_element_release to dispose the created object when finished with it.

Return Value:

Error count.


IG_PDE_shading_get_dictionary

Group: PDE Shading

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_shading_get_dictionary(
HIG_PDE_SHADING hShading,
LPHIG_PDF_BASOBJ lphDictionary);

Arguments:

hShading
A shading object.
lphDictionary
Dictionary for hShading.

Description:

Gets the dictionary for a shading.

Return Value:

Error count.


HIG_PDE_TEXT

Type: PDE Text Object

Description:

Handle to the PDE text object. Text - an element representing text. It is a container for text as show strings or as individual characters. Each sub-element may have different graphics state properties. However, the same clip applies to all sub-elements of a Text. Also, the char path of a Text can be used to represent a clip.

Class Members:

IG_PDE_text_create
Creates an empty text object.
IG_PDE_text_add
Adds a character or a text run to a PDE Text object.
IG_PDE_text_add_item
Adds a text item to a text element at a given index position.
IG_PDE_text_get_advance
Gets the advance width of a character or a text element.
IG_PDE_text_get_bbox
Gets the bounding box of a character or a text run.
IG_PDE_text_get_font
Gets the font for a text character or element.
IG_PDE_text_get_gstate
Gets the graphics state of a character or a text run.
IG_PDE_text_get_item
Obtains a text item from a text element at a given index position.
IG_PDE_text_get_matrix
Returns the matrix of a character or a text element.
IG_PDE_text_get_byte_count
Gets the number of bytes occupied by the character code or text run.
IG_PDE_text_get_char_count
Gets the number of characters in a text object.
IG_PDE_text_get_runs_count
Gets the number of text runs (show strings) in a text object.
IG_PDE_text_get_quad
Gets the quad bounding the specified text run or character.
IG_PDE_text_get_run_for_char
Gets the index of the text run that contains the nth character in a text object.
IG_PDE_text_get_state
Gets the text state of a character or a text element.
IG_PDE_text_get_stroke_matrix
Gets the stroke matrix of a character or a text run.
IG_PDE_text_get_text
Gets the text for a text run or character.
IG_PDE_text_is_at_point
Tests whether a point is on specified text.
IG_PDE_text_is_at_rect
Tests whether any part of a rectangle is on the specified text.
IG_PDE_text_remove
Removes characters or text runs from a text object.
IG_PDE_text_remove_items
Removes contiguous text items from a text element starting at a given index position.
IG_PDE_text_replace_chars
Replaces characters in a text object.
IG_PDE_text_run_get_char_offset
Gets the character offset of the first character of the specified text run.
IG_PDE_text_run_get_char_count
Gets the number of characters in a text run.
IG_PDE_text_run_set_font
Sets the font of a text run.
IG_PDE_text_run_set_gstate
Sets the graphics state of a text run.
IG_PDE_text_run_set_matrix
Sets the matrix of a text run.
IG_PDE_text_run_set_state
Sets the text state of a text run.
IG_PDE_text_run_set_stroke_matrix
Sets the stroke matrix of a text run.
IG_PDE_text_split_run_at
Splits a text run into two text runs.


IG_PDE_text_create

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_create(
LPHIG_PDE_TEXT lphText );

Arguments:

lphText
An empty text object.

Description:

Creates an empty text object.

Call IG_PDE_element_release to dispose the created object when finished with it.

Return Value:

Error count.


IG_PDE_text_add

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_add(
HIG_PDE_TEXT hText,
UINT nFlag,
UINT nIndex,
LPBYTE lpText,
UINT nTextLen,
HIG_PDE_FONT hFont,
LPAT_PDE_GRAPHICSTATE lpGstate,
LPAT_PDE_TEXTSTATE lpTstate,
LPAT_PDF_FIXEDMATRIX lpTextMatrix,
LPAT_PDF_FIXEDMATRIX lpStrokeMatrix );

Arguments:

hText
Text object to which a character or text run is added.
nFlag
enumIGPDETextFlag flag that specifies what kind of text to add. Must be either:
IG_PDE_TEXT_CHAR - for a text character
IG_PDE_TEXT_RUN - for a text run
nIndex
Index after which to add character or text run.
lpText
Pointer to the characters to add.
NOTE: Passing NULL for text can invalidate the text object but will not raise an error. Callers must not pass NULL for this parameter.
nTextLen
Length of the text, in bytes.
hFont
Font for the element.
lpGstate
Pointer to AT_PDE_GRAPHICSTATE structure with the graphics state for the element.
lpTstate
Pointer to AT_PDE_TEXTSTATE structure with text state for the element.
lpTextMatrix
Pointer to AT_PDF_FIXEDMATRIX that holds the matrix for the element.
lpStrokeMatrix
Pointer to AT_PDF_FIXEDMATRIX that holds the matrix for the line width when stroking text. May be NULL.

Description:

Adds a character or a text run to a PDE Text object.

Return Value:

Error count.


IG_PDE_text_add_item

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_add_item(
HIG_PDE_TEXT hText,
UINT nIndex,
HIG_PDE_TEXTITEM hTextItem );

Arguments:

hText
Text object to which an item is added.
nIndex
Index of the text item in hText.
hTextItem
The text item to add.

Description:

Adds a text item to a text element at a given index position.

Return Value:

Error count.


IG_PDE_text_get_advance

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_advance(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPAT_PDF_FIXEDPOINT lpAdvanceWidth );

Arguments:

hText
Text object containing a character or text run whose advance width is found.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
In addition, set the IG_PDE_TEXT_PAGE_SPACE flag to obtain the advance width in user space. If it is not set, the advance width is in character space.
If this flag is not set, this method returns a value that is independent of any sizes, matrices, or scaling, simply adding up the font's raw glyph widths, supplemented only by unscaled character and word spacing.
nIndex
Index of the character or text run in hText.
lpAdvanceWidth
Pointer to AT_PDF_FIXEDPOINT value indicating the advance width.

Description:

Gets the advance width of a character or a text element. Advance width is returned in either character space or user space. The advance width is the amount by which the current point advances when the character is drawn.

Advance width may be horizontal or vertical, depending on the writing style. Thus lpAdvanceWidth has both a horizontal and vertical component.

Return Value:

Error count.


IG_PDE_text_get_bbox

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_bbox(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPAT_PDF_FIXEDRECT lpBBox );

Arguments:

hText
Text object containing a character or text run whose bounding box is found.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
lpBBox
Pointer to AT_PDF_FIXEDRECT to set to the bounding box of specified character or text run.

Description:

Gets the bounding box of a character or a text run.

Return Value:

Error count.


IG_PDE_text_get_font

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_font(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPHIG_PDE_FONT lphFont);

Arguments:

hText
Text object containing a character or text run whose font is found.
nFlags
Specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
lphFont
HIG_PDE_FONT return value.

Description:

Gets the font for a text character or element.

Return Value:

Error count.


IG_PDE_text_get_gstate

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_gstate(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPAT_PDE_GRAPHICSTATE lpGstate );

Arguments:

hText
Text object containing a character or text run whose graphics state is obtained.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
lpGstate
Pointer to a AT_PDE_GRAPHICSTATE structure with graphics state of specified character or text run.

Description:

Gets the graphics state of a character or a text run.

NOTE: Non-NULL objects in the graphic state, such as the fill and stroke color spaces, have their reference counts incremented by this method. Be sure to release these non-NULL objects when disposing of lpGstate.

Return Value:

Error count.


IG_PDE_text_get_item

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_item(
HIG_PDE_TEXT hText,
UINT nIndex,
LPHIG_PDE_TEXTITEM lphTextItem );

Arguments:

hText
Text object from which the text item is obtained.
nIndex
Index of the text item in hText.
lphTextItem
The text item object.

Description:

Obtains a text item from a text element at a given index position.

Return Value:

Error count.


IG_PDE_text_get_matrix

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_matrix(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPAT_PDF_FIXEDMATRIX lpMatrix );

Arguments:

hText
Text object containing a character or text run whose matrix is obtained.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
lpMatrix
Pointer to AT_PDF_FIXEDMATRIX that holds the matrix of specified character or text run.

Description:

Returns the matrix of a character or a text element.

Return Value:

Error count.


IG_PDE_text_get_byte_count

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_byte_count(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPUINT lpnByteCount );

Arguments:

hText
Text object containing a character or text run whose text is examined.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
lpnByteCount
Number of bytes occupied by the text run or character.

Description:

Gets the number of bytes occupied by the character code or text run.

Return Value:

Error count.


IG_PDE_text_get_char_count

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_char_count(
HIG_PDE_TEXT hText,
LPUINT lpnCharCount );

Arguments:

hText
Text object containing a character or text run whose text is examined.
lpnCharCount
Total number of characters in hText.

Description:

Gets the number of characters in a text object.

Return Value:

Error count.


IG_PDE_text_get_runs_count

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_runs_count(
HIG_PDE_TEXT hText,
LPUINT lpnRunsCount);

Arguments:

hText
Text object whose number of text runs is found.
lpnRunsCount
Number of text runs in hText.

Description:

Gets the number of text runs (show strings) in a text object.

Return Value:

Error count.


IG_PDE_text_get_quad

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_quad(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPAT_PDF_FIXEDQUAD lpQuad );

Arguments:

hText
Text object containing a character or text run whose text is examined.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
In addition, if the IG_PDE_TEXT_GET_BOUNDS flag is set, this method uses the font descriptor's FontBBox, which is the smallest rectangle that encloses all characters in the font. The advance portion is based on the x-coordinates of the left and right sides of FontBBox and the advance width.
nIndex
Index of the character or text run in the text object.
lpQuad
Pointer to AT_PDF_FIXEDQUAD that bounds the specified character or text run.

Description:

Gets the quad bounding the specified text run or character.

The advance portion of the quad is based on the left side bearing and advance width.

Return Value:

Error count.


IG_PDE_text_get_run_for_char

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_run_for_char(
HIG_PDE_TEXT hText,
UINT nCharIndex,
LPUINT lpnRunIndex );

Arguments:

hText
Text object containing a character or text run whose text is examined.
nCharIndex
Number of the character to find in hText.
lpnRunIndex
Index of the text run with the specified character index in hText.

Description:

Gets the index of the text run that contains the nth character in a text object.

Return Value:

Error count.


IG_PDE_text_get_state

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_state(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPAT_PDE_TEXTSTATE lpTstate );

Arguments:

hText
Text object containing a character or text run whose text is examined.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
lpTstate
Pointer to AT_PDE_TEXTSTATE structure to fill with the text state of the specified character or text run.

Description:

Gets the text state of a character or a text element.

Return Value:

Error count.


IG_PDE_text_get_stroke_matrix

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_stroke_matrix(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPAT_PDF_FIXEDMATRIX lpMatrix );

Arguments:

hText
Text object containing a character or text run whose text is examined.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
lpMatrix
Pointer to AT_PDF_FIXEDMATRIX that holds the stroke matrix of specified character or text run. This matrix is the transformation for line widths when stroking. The h and v values of the matrix are ignored.

Description:

Gets the stroke matrix of a character or a text run.

Return Value:

Error count.


IG_PDE_text_get_text

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_get_text(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPBYTE lpText,
LPUINT lpnTextLen );

Arguments:

hText
Text object containing a character or text run whose text is found.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
lpText
Text of specified character or text run. lpText must be large enough to hold the returned text.
lpnTextLen
Number of bytes in text run or character.

Description:

Gets the text for a text run or character.

Return Value:

Error count.


IG_PDE_text_is_at_point

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_is_at_point(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPAT_PDF_FIXEDPOINT lpPoint,
LPAT_BOOL lpbResult );

Arguments:

hText
Text object containing a character or text run.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
lpPoint
The point, specified in user space coordinates.
lpbResult
True if the point is on the text, False otherwise.

Description:

Tests whether a point is on specified text. Checks if the point is in a bounding box for hText.

Return Value:

Error count.


IG_PDE_text_is_at_rect

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_is_at_rect(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPAT_PDF_FIXEDRECT lpFixedRect,
LPAT_BOOL lpbResult );

Arguments:

hText
Text object containing a character or text run.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
lpFixedRect
The rectangle, specified in user space coordinates.
lpbResult
True if the text is on the rectangle, False otherwise.

Description:

Tests whether any part of a rectangle is on the specified text.

Return Value:

Error count.


IG_PDE_text_remove

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_remove(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
UINT nCount );

Arguments:

hText
Text object containing a character or text run.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
nCount
Number of characters or text runs to remove.\

Description:

Removes characters or text runs from a text object.

Return Value:

Error count.


IG_PDE_text_remove_items

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_remove_items(
HIG_PDE_TEXT hText,
UINT nIndex,
UINT nCount );

Arguments:

hText
Text object from which the text items are removed.
nIndex
Index of the first text item in pdeText to remove.
nCount
The number of text items to remove.

Description:

Removes contiguous text items from a text element starting at a given index position.

Return Value:

Error count.


IG_PDE_text_replace_chars

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_replace_chars(
HIG_PDE_TEXT hText,
UINT nFlags,
UINT nIndex,
LPBYTE lpText,
UINT nTextLen );

Arguments:

hText
Text object containing a character or text run.
nFlags
enumIGPDETextFlag value that specifies whether index refers to the character offset from the beginning of the text object or the index of the text run in the text object. Must be either:
  • IG_PDE_TEXT_CHAR - for a text character
  • IG_PDE_TEXT_RUN - for a text run
nIndex
Index of the character or text run in the text object.
lpText
Replacement text.
nTextLen
Number of bytes to replace.

Description:

Replaces characters in a text object.

This method does not change the number of characters in the text object-extra characters are ignored.

Return Value:

Error count.


IG_PDE_text_run_get_char_offset

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_run_get_char_offset(
HIG_PDE_TEXT hText,
UINT nRunIndex,
LPUINT lpnOffset );

Arguments:

hText
Text object containing a text run.
nRunIndex
Index of the text run.
lpnOffset
Character offset of the first character of the specified text run in hText.

Description:

Gets the character offset of the first character of the specified text run.

Return Value:

Error count.


IG_PDE_text_run_get_char_count

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_run_get_char_count(
HIG_PDE_TEXT hText,
UINT nRunIndex,
LPUINT lpnCount );

Arguments:

hText
Text object containing a text run.
nRunIndex
Index of the text run.
lpnCount
Number of characters in the specified text run.

Description:

Gets the number of characters in a text run.

Return Value:

Error count.


IG_PDE_text_run_set_font

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_run_set_font(
HIG_PDE_TEXT hText,
UINT nRunIndex,
HIG_PDE_FONT hFont );

Arguments:

hText
Text object containing a text run.
nRunIndex
Index of the text run.
hFont
Font set for the text run.

Description:

Sets the font of a text run.

Return Value:

Error count.


IG_PDE_text_run_set_gstate

Group: PDE Text

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_run_set_gstate(
HIG_PDE_TEXT hText,
UINT nRunIndex,
LPAT_PDE_GRAPHICSTATE lpGstate );

Arguments:

hText
Text object containing a text run.
nRunIndex
Index of the text run.
lpGstate
Pointer to AT_PDE_GRAPHICSTATE structure with graphics state to set.

Description:

Sets the graphics state of a text run.

Return Value:

Error count.


IG_PDE_text_run_set_matrix

Group: IG PDE

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_run_set_matrix(
HIG_PDE_TEXT hText,
UINT nRunIndex,
LPAT_PDF_FIXEDMATRIX lpMatrix );

Arguments:

hText
Text object containing a text run.
nRunIndex
Index of the text run.
lpMatrix
Pointer to AT_PDF_FIXEDMATRIX structure with matrix to set.

Description:

Sets the matrix of a text run.

Return Value:

Error count.


IG_PDE_text_run_set_state

Group: IG PDE

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_run_set_state(
HIG_PDE_TEXT hText,
UINT nRunIndex,
LPAT_PDE_TEXTSTATE lpState );

Arguments:

hText
Text object containing a text run.
nRunIndex
Index of the text run.
lpState
Pointer to AT_PDE_TEXTSTATE structure with state to set.

Description:

Sets the text state of a text run.

Return Value:

Error count.


IG_PDE_text_run_set_stroke_matrix

Group: IG PDE

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_run_set_stroke_matrix(
HIG_PDE_TEXT hText,
UINT nRunIndex,
LPAT_PDF_FIXEDMATRIX lpMatrix );

Arguments:

hText
Text object containing a text run.
nRunIndex
Index of the text run.
lpMatrix
Pointer to AT_PDF_FIXEDMATRIX structure with store matrix to set.

Description:

Sets the stroke matrix of a text run.

Return Value:

Error count.


IG_PDE_text_split_run_at

Group: IG PDE

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_text_split_run_at(
HIG_PDE_TEXT hText,
UINT nSplitLoc );

Arguments:

hText
Text object containing a text run.
nSplitLoc
Split location, relative to the text object. The first text run is from character index 0 up to nSplitLoc. The second text run is from nSplitLoc + 1 to the end of the run.

Description:

Splits a text run into two text runs.

Return Value:

Error count.


HIG_PDE_TEXTITEM

Type: PDE Text Item Object

Description:

Handle to the PDE text item object. TextItem - a PDE element representing a text object.

Class Members:

IG_PDE_textitem_create
Creates a text item element containing a character or text run, which can be added to a PDE Text object.
IG_PDE_textitem_copy_text
Copies the text from a text item element into a character buffer.
IG_PDE_textitem_get_font
Gets the font for a text item.
IG_PDE_textitem_set_font
Sets a font for a text item.
IG_PDE_textitem_get_gstate
Gets the graphics state for a text item.
IG_PDE_textitem_set_gstate
Sets the graphics state of a text item.
IG_PDE_textitem_get_text_length
Gets the text length for a text item.
IG_PDE_textitem_get_matrix
Gets the text matrix for a character in a text item.
IG_PDE_textitem_set_matrix
Sets the text matrix for a text item.
IG_PDE_textitem_get_state
Gets the text state of a text item.
IG_PDE_textitem_set_state
Sets the text state of a text item.
IG_PDE_textitem_remove_chars
Removes contiguous characters from a text item.
IG_PDE_textitem_replace_chars
Replaces characters in a text item.
IG_PDE_textitem_replace_text
Replaces all of the text in a text item.


IG_PDE_textitem_create

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_create(
LPBYTE lpText,
UINT nTextLen,
HIG_PDE_FONT hFont,
LPAT_PDE_GRAPHICSTATE lpGstate,
LPAT_PDE_TEXTSTATE lpTstate,
LPAT_PDF_FIXEDMATRIX lpTextMatrix
LPHIG_PDE_TEXTITEM lphTextItem );

Arguments:

lpText
Pointer to the characters to add.
NOTE: Passing NULL for text can invalidate the text object but will not raise an error. Callers must not pass NULL for this parameter.
nTextLen
Length of the text, in bytes.
hFont
Font for the element.
lpGstate
Pointer to AT_PDE_GRAPHICSTATE structure with the graphics state for the element.
lpTstate
Pointer to AT_PDE_TEXTSTATE structure with text state for the element.
lpTextMatrix
Pointer to AT_PDF_FIXEDMATRIX that holds the matrix for the element.
lphTextItem
A text element object.

Description:

Creates a text item element containing a character or text run, which can be added to a PDE Text object.

Call IG_PDE_element_release to dispose the created object when finished with it.

Return Value:

Error count.


IG_PDE_textitem_copy_text

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_copy_text(
HIG_PDE_TEXTITEM hTextItem,
LPBYTE lpText,
UINT nTextLen,
LPUINT lpnTextItemLen );

Arguments:

hTextItem
Text item object.
lpText
A pointer to a buffer in which to store the copy.
nTextLen
Length of the text buffer, in bytes.
lpnTextItemLen
The length in bytes of hTextItem.

Description:

Copies the text from a text item element into a character buffer.

Return Value:

Error count.


IG_PDE_textitem_get_font

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_get_font(
HIG_PDE_TEXT hTextItem,
LPHIG_PDE_FONT lphFont);

Arguments:

hTextItem
Text item whose font is obtained.
lphFont
Font for hTextItem.

Description:

Gets the font for a text item.

Return Value:

Error count.


IG_PDE_textitem_set_font

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_set_font(
HIG_PDE_TEXT hTextItem,
HIG_PDE_FONT hFont );

Arguments:

hTextItem
Text object containing a text run.
hFont
Font set for a text item.

Description:

Sets a font for a text item.

Return Value:

Error count.


IG_PDE_textitem_get_gstate

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_get_gstate(
HIG_PDE_TEXT hTextItem,
LPAT_PDE_GRAPHICSTATE lpGstate );

Arguments:

hTextItem
Text item whose graphic state is obtained.
lpGstate
Pointer to AT_PDE_GRAPHICSTATE structure with graphics state of the text item.

Description:

Gets the graphics state for a text item.

NOTE: Non-NULL objects in the graphic state, such as the fill and stroke color spaces, have their reference counts incremented by this method. Be sure to release these non-NULL objects when disposing of lpGstate.

Return Value:

Error count.


IG_PDE_textitem_set_gstate

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_set_gstate(
HIG_PDE_TEXTITEM hTextItem,
LPAT_PDE_GRAPHICSTATE lpGstate );

Arguments:

hTextItem
Text item whose graphic state is set.
lpGstate
Pointer to AT_PDE_GRAPHICSTATE structure with graphics state to set.

Description:

Sets the graphics state of a text item.

Return Value:

Error count.


IG_PDE_textitem_get_text_length

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_get_text_length(
HIG_PDE_TEXT hTextItem,
LPLONG lpnLength );

Arguments:

hTextItem
Text item whose length is obtained.
lpnLength
The text length, in bytes.

Description:

Gets the text length for a text item.

Return Value:

Error count.


IG_PDE_textitem_get_matrix

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_get_matrix(
HIG_PDE_TEXTITEM hTextItem,
UINT nCharOffset,
LPAT_PDF_FIXEDMATRIX lpMatrix );

Arguments:

hTextItem
The text item.
nCharOffset
The offset of the character whose text matrix is obtained.
lpMatrix
Pointer to AT_PDF_FIXEDMATRIX with text matrix of the character.

Description:

Gets the text matrix for a character in a text item.

Return Value:

Error count.


IG_PDE_textitem_set_matrix

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_set_matrix(
HIG_PDE_TEXTITEM hTextItem,
LPAT_PDF_FIXEDMATRIX lpMatrix );

Arguments:

hTextItem
The text item.
lpMatrix
Pointer to AT_PDF_FIXEDMATRIX with the new text matrix of the text item.

Description:

Sets the text matrix for a text item.

Return Value:

Error count.


IG_PDE_textitem_get_state

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_get_state(
HIG_PDE_TEXTITEM hTextItem,
LPAT_PDE_TEXTSTATE lpTstate );

Arguments:

hTextItem
The text item.
lpTstate
Pointer to AT_PDE_TEXTSTATE structure with text state of the text item..

Description:

Gets the text state of a text item.

Return Value:

Error count.


IG_PDE_textitem_set_state

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_set_state(
HIG_PDE_TEXTITEM hTextItem,
LPAT_PDE_TEXTSTATE lpTstate );

Arguments:

hTextItem
The text item.
lpTstate
Pointer to AT_PDE_TEXTSTATE structure with new text state of the text item.

Description:

Sets the text state of a text item.

Return Value:

Error count.


IG_PDE_textitem_remove_chars

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_remove_chars (
HIG_PDE_TEXTITEM hTextItem,
UINT nCharOffset,
UINT nCount );

Arguments:

hTextItem
The text item.
nCharOffset
Offset of the first character to remove.
nCount
The number of characters to remove.

Description:

Removes contiguous characters from a text item.

Return Value:

Error count.


IG_PDE_textitem_replace_chars

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_replace_chars (
HIG_PDE_TEXTITEM hTextItem,
UINT nCharIndex,
LPBYTE lpNewChars,
UINT nNewCharsLen);

Arguments:

hTextItem
The text item.
nCharIndex
Index position of the characters to replace.
lpNewChars
Replacement text.
nNewCharsLen
Number of bytes to replace.

Description:

Replaces characters in a text item.

This method does not change the number of characters in the text item-extra characters are ignored.

Return Value:

Error count.


IG_PDE_textitem_replace_text

Group: PDE Text Item

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_textitem_replace_text (
HIG_PDE_TEXTITEM hTextItem,
LPBYTE lpNewText,
UINT nNewTextLen);

Arguments:

hTextItem
The text item.
lpNewText
Replacement text.
nNewTextLen
Number of bytes to replace.

Description:

Replaces all of the text in a text item.

Return Value:

Error count.


HIG_PDE_XGROUP

Type: PDE XGroup Object

Description:

Handle to the PDE XGroup object. XGroup - a transparency (XGroup) resource.

Class Members:

IG_PDE_xgroup_create
Creates a new XGroup of the given type.
IG_PDE_xgroup_get_colorspace
Acquires the color space of the transparency group.
IG_PDE_xgroup_set_colorspace
Sets the color space for the XGroup.
IG_PDE_xgroup_get_isolated
Gets the isolated boolean value of the transparency group.
IG_PDE_xgroup_set_isolated
Sets the XGroup to be isolated or not.
IG_PDE_xgroup_get_knockout
Gets the knockout boolean value of the transparency group.
IG_PDE_xgroup_set_knockout
Sets the knockout value.


IG_PDE_xgroup_create

Group: PDE XGroup

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_xgroup_create(
HIG_PDF_DOC hDoc,
LONG nType,
LPHIG_PDE_XGROUP lphXGroup );

Arguments:

hDoc
The document the object will be created in.
nType
enumIGPDEXGroupCreateFlags value.
lphXGroup
The newly created XGroup object.

Description:

Creates a new XGroup of the given type.

Call IG_PDE_element_release to dispose the created object when finished with it.

Return Value:

Error count.


IG_PDE_xgroup_get_colorspace

Group: PDE XGroup

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_xgroup_get_colorspace (
HIG_PDE_XGROUP hXGroup,
LPHIG_PDE_COLORSPACE lphColorSpace );

Arguments:

hXGroup
The transparency group object
lphColorSpace
The color space.

Description:

Acquires the color space of the transparency group.

Return Value:

Error count.


IG_PDE_xgroup_set_colorspace

Group: PDE XGroup

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_xgroup_set_colorspace (
HIG_PDE_XGROUP hXGroup,
HIG_PDE_COLORSPACE hColorSpace );

Arguments:

hXGroup
The transparency group object
hColorSpace
The color space to associate with the XGroup.

Description:

Sets the color space for the XGroup.

Return Value:

Error count.


IG_PDE_xgroup_get_isolated

Group: PDE XGroup

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_xgroup_get_isolated (
HIG_PDE_XGROUP hXGroup,
LPAT_PDF_BOOL lpbIsolated );

Arguments:

hXGroup
The transparency group object
lpbIsolated
True if the transparency group is isolated; False otherwise.

Description:

Gets the isolated boolean value of the transparency group.

Return Value:

Error count.


IG_PDE_xgroup_set_isolated

Group: PDE XGroup

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_xgroup_set_isolated (
HIG_PDE_XGROUP hXGroup,
AT_PDF_BOOL bIsolated );

Arguments:

hXGroup
The transparency group object
bIsolated
True to isolate the XGroup, False otherwise.

Description:

Sets the XGroup to be isolated or not. Corresponds to the /I key within the XGroup's dictionary.

Return Value:

Error count.


IG_PDE_xgroup_get_knockout

Group: PDE XGroup

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_xgroup_get_knockout(
HIG_PDE_XGROUP hXGroup,
LPAT_PDF_BOOL lpbKnockout );

Arguments:

hXGroup
The transparency group object
lpbKnockout
The knockout value

Description:

Gets the knockout boolean value of the transparency group.

Return Value:

Error count.


IG_PDE_xgroup_set_knockout

Group: PDE XGroup

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_xgroup_set_knockout(
HIG_PDE_XGROUP hXGroup,
AT_PDF_BOOL bKnockout);

Arguments:

hXGroup
The transparency group object
bKnockout
The knockout value.

Description:

Sets the knockout value.

Return Value:

Error count.


HIG_PDE_XOBJECT

Type: PDE XObject Object

Description:

Handle to the PDE XObject object. XObject - an element representing an arbitrary XObject.

Class Members:

IG_PDE_xobject_create
Creates a new XObject from hObject.


IG_PDE_xobject_create

Group: PDE XObject

Declaration:

AT_ERRCOUNT ACCUAPI IG_PDE_xobject_create(
HIG_PDF_BASOBJ hBasObj,
LPHIG_PDE_XOBJECT lphXObject );

Arguments:

hBasObj
Base object for XObject.
lphXObject
XObject corresponding to the hBasObj.

Description:

Creates a new XObject from hObject.

Call IG_PDE_element_release to dispose the created object when finished with it.

Return Value:

Error count.


Subsidiary Types / DLL Structures

Simple structure types that are used for creating, attributing and manipulating general and editing objects.

The following table contains the objects and their descriptions supported by the ImageGear PDF component:

Subsidiary Types / DLL Structures
AT_PDF_BOOL
Boolean type with two values: TRUE (1) or FALSE (0)
AT_PDF_FIXED
The Fixed type is a 32-bit quantity representing a rational number with the high (low on little-endian machines) 16 bits representing the number's mantissa and the low (high) 16 bits representing the fractional part. The definition is platform-dependent.
LPAT_PDF_FIXED is a pointer to an AT_PDF_FIXED.
Addition, subtraction, and negation with AT_PDF_FIXED types can be done with + and -, unless you care about overflow. (Overflow in Fixed-value operations is indicated by the values IG_PDF_FIXED_POSITIVE_INFINITY and IG_PDF_FIXED_NEGATIVE_INFINITY.)
AT_PDF_FIXEDPOINT
Point (in two-dimensional space) represented by two fixed numbers.
AT_PDF_FIXEDMATRIX
Matrix containing fixed numbers.
AT_PDF_FIXEDRECT
A rectangle represented by the coordinates of its four sides. A rectangle differs from a quadrilateral in that the former must always have horizontal and vertical sides, and opposite sides must be parallel.
AT_PDF_FIXEDQUAD
Quadrilateral represented by four fixed points (one at each corner). A quadrilateral differs from a rectangle in that the latter must always have horizontal and vertical sides, and opposite sides must be parallel.
AT_PDF_FONT_STYLES
Font styles.
AT_PDF_FONT_METRICS
Font metrics.
AT_PDF_PRINTOPTIONS
This structure used to provide printing parameters for IG_PDF_doc_print function.
AT_PDF_PRINTPARAMS
This structure indicates how a document should be printed.
AT_PDF_SECURITYDATA
Describes the data for the standard security handler.
AT_PDE_FONTATTRS
Attributes of a PDE Font and a PDF SysFont.
AT_PDE_COLORVALUE
Color value.
AT_PDE_COLORSPEC
Color specification.
AT_PDE_DASH
Dash specification, as described in Table 4.8 in the PDF Reference. See Section 4.3.2 for more information on line dash patterns.
AT_PDE_GRAPHICSTATE
Attributes of a PDE Element or a PDE Text sub-element.
AT_PDE_TEXTSTATE
Attributes of a PDE Text element.
AT_PDF_SYSFONT_PLATDATA
PDF SysFont platform specific data.
AT_PDE_FONT_INFO
PDE Font information.
AT_PDE_FONT_CREATEFROMSYSFONTPARAMS
Parameters for PDE font creation.
AT_PDE_COLORRANGE
Color range.
AT_PDE_XYZCOLOR
XYZ color.
AT_PDE_COLORDATA_CALGRAY
CalGray color space.
AT_PDE_COLORDATA_CALRGB
CalRGB color space.
AT_PDE_COLORDATA_LAB
L*a*b* color space.
AT_PDE_COLORDATA_ICCBASED
ICC based color space.
AT_PDE_COLORDATA_INDEXED
Indexed color space.
AT_PDE_COLORDATA_SEPARATION
Separation color space
AT_PDE_COLORDATA_DEVICEN
DeviceN color space.
AT_PDE_COLORDATA
Fill in one of the following members of this union, then pass it to PDE ColorSpace creation routine. Please see section 7.10 of the PDF Reference Manual for information on color spaces.
AT_PDE_PSATTRS
Attributes of a PDE PS object.
AT_PDE_IMAGEATTRS
Attributes of a PDE Image object.
AT_PDE_FILTERSPEC
Filter element in a filter array.
AT_PDE_FILTERARRAY
Filter information for streams. Array of FilterSpec elements. Usually consists of 2 filter elements: text encoding and image compression.
AT_PDE_CONTENTATTRS
Attributes of a PDE Content object.


AT_PDF_FIXEDPOINT

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDF_FIXEDPOINT
{
    AT_PDF_FIXED h;
    AT_PDF_FIXED v;
} AT_PDF_FIXEDPOINT;
typedef AT_PDF_FIXEDPOINT FAR* LPAT_PDF_FIXEDPOINT;

Arguments:

AT_PDF_FIXED
h
Horizontal value
AT_PDF_FIXED
v
Vertical value

Description:

Point (in two-dimensional space) represented by two fixed numbers.


AT_PDF_FIXEDMATRIX

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDF_FIXEDMATRIX
{
    AT_PDF_FIXED a;
    AT_PDF_FIXED b;
    AT_PDF_FIXED c;
    AT_PDF_FIXED d;
    AT_PDF_FIXED h;
    AT_PDF_FIXED v;
} AT_PDF_FIXEDMATRIX;
typedef AT_PDF_FIXEDMATRIX FAR* LPAT_PDF_FIXEDMATRIX;

Arguments:

AT_PDF_FIXED
a
A value
AT_PDF_FIXED
b
B value
AT_PDF_FIXED
c
C value
AT_PDF_FIXED
d
D value
AT_PDF_FIXED
h
H value
AT_PDF_FIXED
v
V value

Description:

Matrix containing fixed numbers.


AT_PDF_FIXEDRECT

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDF_FIXEDRECT
{
    AT_PDF_FIXED left;
    AT_PDF_FIXED top;
    AT_PDF_FIXED right;
    AT_PDF_FIXED bottom;
} AT_PDF_FIXEDRECT;
typedef AT_PDF_FIXEDRECT FAR* LPAT_PDF_FIXEDRECT;

Arguments:

AT_PDF_FIXED
left
Left value
AT_PDF_FIXED
right
Right value
AT_PDF_FIXED
top
Top value
AT_PDF_FIXED
bottom
Bottom value

Description:

A rectangle represented by the coordinates of its four sides. A rectangle differs from a quadrilateral in that the former must always have horizontal and vertical sides, and opposite sides must be parallel.


AT_PDF_FIXEDQUAD

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDF_FIXEDQUAD
{
    AT_PDF_FIXEDPOINT tl, tr, bl, br;
} AT_PDF_FIXEDQUAD;
typedef AT_PDF_FIXEDQUAD FAR* LPAT_PDF_FIXEDQUAD;

Arguments:

AT_PDF_FIXEDPOINT
tl
Top left value
AT_PDF_FIXEDPOINT
tr
Top right value
AT_PDF_FIXEDPOINT
bl
Bottom left value
AT_PDF_FIXEDPOINT
br
Bottom right value

Description:

Quadrilateral represented by four fixed points (one at each corner). A quadrilateral differs from a rectangle in that the latter must always have horizontal and vertical sides, and opposite sides must be parallel.


AT_PDF_FONT_STYLES

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDF_FONT_STYLES
{
    AT_BYTE sFamilyClassID;
    AT_BYTE sFamilySubclassID;
    AT_BYTE bFamilyType;
    AT_BYTE bSerifStyle;
    AT_BYTE bWeight;
    AT_BYTE bProportion;
} AT_PDF_FONT_STYLES;

Arguments:

sFamilyClassID
Number that identifies the font family and determines the meaning of the remaining Panose digits. Possible families are Latin, Kanji, Hebrew, and so forth.
sFamilySubclassID
Number to identify the kind of family: text, decorative, handwritten, symbols, and so on.
bFamilyType
Number to identify the family type: text, decorative, handwritten, symbols, and so on.
bSerifStyle
Number that specifies the font's serif style, such as cove, obtuse cove, square, bone, and so forth.
bWeight
Number that specifies the font's weight, such as very light, heavy, black, and so on.
bProportion
Number that specifies the font's proportions, such as modern, expanded, condensed, mono spaced, and so on.


AT_PDF_FONT_METRICS

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDF_FONT_METRICS
{
    UINT				flags;
    AT_PDF_FIXEDRECT	fontBBox;
    AT_INT16	  		missingWidth;
    AT_INT16	  		stemV;
    AT_INT16	  		stemH;
    AT_INT16	  		capHeight;
    AT_INT16	  		xHeight;
    AT_INT16	  		ascent;
    AT_INT16	  		descent;
    AT_INT16	  		leading;
    AT_INT16	  		maxWidth;
    AT_INT16	  		avgWidth;
    AT_INT16	  		italicAngle;
    AT_PDF_FONT_STYLES	style;
    AT_INT16			baseLineAdj;
} AT_PDF_FONT_METRICS;

flags
Must be an OR of the Font Flags values. All unused flags must be off.
fontBBox
Font bounding box in 1000 EM units. (An EM is a typographic unit of measurement equal to the size of a font. In a 12-point font, an EM is 12 points.)
missingWidth
Width of missing character.
stemV
Vertical stem width.
stemH
Horizontal stem width.
capHeight
Capital height.
xHeight
X height.
ascent
Max ascender height.
descent
Max descender depth.
Leading
Additional leading between lines.
maxWidth
Maximum character width.
avgWidth
Average character width.
italicAngle
Italic angle in degrees, if any.
style
Panose and sFamily class values.
baseLineAdj
Baseline adjustment, which is a vertical adjustment for font baseline difference and writing mode 1 (vertical). This should only be used for CIDFontType 2 fonts with font substitution.

Arguments:

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


AT_PDF_PRINTOPTIONS

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDF_PRINTOPTIONS
{
    AT_DWORD size;
    AT_PDF_BOOL emitToFile;
    LPAT_PDF_PRINTPARAMS printParams;
    HIG_PDF_STREAM printStm;
    AT_WORD paperWidth;
    AT_WORD paperHeight;
    AT_DWORD dontEmitListLen;
    char ** dontEmitList;
    AT_PDF_BOOL emitToPrinter;
    char *inFileName;
    char *outFileName;
    char *deviceName;
    char *driverName;
    char *portName;
    DEVMODE *pDevMode;
    int   startPage;
    int   endPage;
    int   shrinkToFit;
    int   printAnnots;
    int   psLevel;
    int   nCopies;
    int   binaryOK;
    int   emitHalftones;
    int   reverse;
    BYTE farEastFontOpt;
    int   transQuality;
    int   doOPP;
    LPVOID cancelProc;
    LPVOID clientData;
    int   startResult;
    AT_PDF_BOOL forceGDIPrint;
    HDC hDC;
} AT_PDF_PRINTOPTIONS;
typedef AT_PDF_PRINTOPTIONS FAR* LPAT_PDF_PRINTOPTIONS;

Arguments:

Description:

This structure used to provide printing parameters for IG_PDF_doc_print function.

To print, set printing method to printer, and fill in inFileName, outFileName, deviceName, driverName, portName, dpi, nCopies, startPage, endPage, psLevel, shrinkToFit, binaryOK, emitHalftones.


AT_PDF_PRINTPARAMS

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDF_PRINTPARAMS
{
    AT_UINT size;
    AT_PDF_PAGE_RANGE *ranges;
    AT_INT32 numRanges;
    AT_PDF_BOOL shrinkToFit;
    AT_PDF_BOOL expandToFit;
    AT_PDF_BOOL rotateAndCenter;
    AT_INT16 printWhat;
    AT_INT16 printWhatAnnot;
    AT_PDF_BOOL emitPS;
    AT_INT32 psLevel;
    AT_INT16 outputType;
    AT_INT16 incBaseFonts;
    AT_INT16 incEmbeddedFonts;
    AT_INT16 incType1Fonts;
    AT_INT16 incType3Fonts;
    AT_INT16 incTrueTypeFonts;
    AT_INT16 incCIDFonts;
    AT_INT16 incProcsets;
    AT_INT16 incOtherResources;
    AT_INT32 fontPerDocVM;
    AT_PDF_BOOL emitShowpage;
    AT_PDF_BOOL emitTTFontsFirst;
    AT_PDF_BOOL setPageSize;
    AT_PDF_BOOL emitDSC;
    AT_PDF_BOOL setupProcsets;
    AT_PDF_BOOL emitColorSeps;
    AT_PDF_BOOL binaryOK;
    AT_PDF_BOOL useSubFileDecode;
    AT_PDF_BOOL emitRawData;
    AT_PDF_BOOL TTasT42;
    AT_FLOAT scale;
    AT_PDF_BOOL emitExternalStreamRef;
    AT_PDF_BOOL emitHalftones;
    AT_PDF_BOOL emitPSXObjects;
    AT_PDF_BOOL centerCropBox;
    AT_PDF_BOOL emitSeparableImagesOnly;
    AT_PDF_BOOL emitDeviceExtGState;
    AT_PDF_FIXEDRECT boundingBox;
    AT_PDF_BOOL useFontAliasNames;
    AT_PDF_BOOL emitPageRotation;
    AT_PDF_BOOL reverse;
    AT_PDF_FIXEDRECT *tCropBox;
    AT_PDF_BOOL emitPageClip;
    AT_PDF_BOOL emitTransfer;
    AT_PDF_BOOL emitBG;
    AT_PDF_BOOL emitUCR;
    AT_INT16 farEastFontOpt;
    AT_PDF_BOOL suppressCJKSubstitution;
    AT_PDF_BOOL suppressCSA;
    AT_PDF_BOOL hostBased;
    HIG_PDF_ATOM hostBasedOutputCS;
    AT_INT16 duplex;
    AT_INT16 doTiling;
    LPAT_PDF_TILEEX tileInfo;
    AT_PDF_BOOL rotate;
    AT_PDF_BOOL hostBasedCM;
    char  destProfile[256];
    HIG_PDF_ATOM destCSAtom;
    AT_PDF_BOOL saveVM;
    AT_PDF_BOOL doOPP;
    AT_INT32 suppressOPPWhenNoSpots;
    AT_PDF_BOOL optimizeForSpeed;
    AT_PDF_BOOL brokenCRDs;
    AT_PDF_BOOL useMaxVM;
    AT_INT32 lastWidth;
    AT_INT32 lastHeight;
    AT_DWORD bitmapResolution;
    AT_DWORD gradientResolution;
    AT_DWORD transparencyQuality;
    AT_DWORD ocContext;
    AT_PDF_BOOL applyOCGPrintOverrides;
    AT_PDF_BOOL useFullResolutionJP2KData;
    AT_PDF_BOOL emitInRipSeps;
    AT_DWORD whichMarks;
    AT_PDF_BOOL westernMarksStyle;
    AT_PDF_BOOL doProofing;
    char proofProfile[256];
    AT_PDF_BOOL inkBlack;
    AT_PDF_BOOL paperWhite;
    AT_PDF_BOOL useExecForm;
    LPAT_PDF_FLATTEN flattenInfo;
    AT_PDF_BOOL negative;
    AT_INT16 mirrorprint;
    AT_DWORD numCollatedCopies;
    AT_PDF_BOOL emitFlatness;
    AT_INT32 trapType;
    AT_PDF_BOOL TTasCIDT2;
    AT_DWORD markStyle;
    AT_FLOAT lineWidth;
    AT_PDF_BOOL macQDPrinter;

} AT_PDF_PRINTPARAMS;
typedef AT_PDF_PRINTPARAMS FAR* LPAT_PDF_PRINTPARAMS;

Arguments:

size
Size of the data structure. Must be set to sizeof(AT_PDF_PRINTPARAMS).
ranges
Ranges of pages to print. Use NULL to print the entire document.
numRanges
Number of ranges of pages to print in ranges. The default value is 0.
shrinkToFit
True if the page is scaled to fit the printer page size, false otherwise. This field overrides scale. The default value is false.
expandToFit
True if small pages are to be scaled up to fit the printer page size, false otherwise. Overrides scale. The default value is false.
rotateAndCenter
True if page is to be rotated to fit printer's orientation, and centered in printer's page size; false otherwise.The default value is false. Rotation and centering (true) only occur, however, if the page contents are too wide to fit on a narrow page (or vice versa) and the page contents are less than an inch smaller than the target page in one direction.
printWhat
enumIGPDFPrintWhat flag. Default is IG_PDF_PRINT_DOCUMENT.
printWhatAnnot
Combination of enumIGPDFPrintWhatAnnot flags which extend printWhat to enable Pro product behavior.
emitPS
If true, emit a PostScript file. The default value is true.
psLevel
PostScript level: 1, 2 or 3. The default value is 2.
outputType
Print PostScript or EPS with or without a preview.
incBaseFonts
Embed the base fonts. The default value is IG_PDF_INCLUDE_NEVER.
incEmbeddedFonts
Embed fonts that are embedded in the PDF file. This overrides the incType1Fonts, incTrueTypeFonts, and incCIDFonts fields. The default value is IG_PDF_INCLUDE_ONCE_PER_DOC.
incType1Fonts
Embed Type 1 fonts. The default value is IG_PDF_INCLUDE_ONCE_PER_DOC.
incType3Fonts
Embed Type 3 fonts. The default value is IG_PDF_INCLUDE_ON_EVERY_PAGE.
NOTE: This parameter must always be set to IG_PDF_INCLUDE_ON_EVERY_PAGE. PDF files exist with Type 3 fonts that contain different encodings on different pages.
incTrueTypeFonts
Embed TrueType fonts. The default value is IG_PDF_INCLUDE_ONCE_PER_DOC.
incCIDFonts
Embed CID fonts. The default value is IG_PDF_INCLUDE_ONCE_PER_DOC.
incProcsets
Include Procsets in the file. The default value is IG_PDF_INCLUDE_ONCE_PER_DOC.
incOtherResources
Include all other types of resources in the file. The default value is IG_PDF_INCLUDE_ONCE_PER_DOC.
fontPerDocVM
Amount of VM available for font downloading at the document level. Ignored if <=0.
NOTE: This must be set to 0 for the toolkit; it is only used by the viewer.
emitShowpage
Emit save and restore showpage in PostScript files. The default value is true.
emitTTFontsFirst
Emit TrueType fonts before any other fonts. The default value is false.
setPageSize
(PostScript level 2 only) Set the page size on each page. Use the media box for outputting to PostScript files, use the crop box for EPS files. Default is false.
emitDSC
Write DSC (Document Structuring Conventions) comments. The default value is true.
setupProcsets
If procsets are included, also include init/term code. The default value is true.
NOTE: This must be set to true.
emitColorSeps
Emit images for Level-1 separations. The default value is false.
binaryOK
True if binary data is permitted in the PostScript file, false otherwise. The default value is true.
useSubFileDecode
Add SubFileDecode filter to work around stream problems. The default value is false.
emitRawData
True if add no unnecessary filters when emitting image data, false otherwise. The default value is true.
TTasT42
If including TrueType fonts, convert to Type 42 fonts instead of Type 1 fonts. The default value is false.
scale
Document-wide scale factor. 100.0 = full size. The default value is 100.
emitExternalStreamRef
If an Image resource uses an external stream, emit code that points to the external file. The default value is false.
NOTE: This must be set to false.
emitHalftones
Preserve any halftone screening in the PDF file. The default value is false.
emitPSXObjects
Emit PostScript XObjects into the PostScript stream. The default value is false.
centerCropBox
True if CropBox output is centered on the page when the CropBox < MediaBox, false otherwise. The default value is true.
emitSeparableImagesOnly
If emitting EPS, include only CMYK and gray images.
emitDeviceExtGState
When emitting the extended graphics state, include the device-dependent parameters (overprint, black generation, undercolor removal, transfer, halftone, halftone phase, smoothness, flatness, rendering intent) in addition to the device-independent parameters (font, line width, line cap, line join, miter limit, dash pattern). If this flag is false, only the device-independent parameters will be emitted. This flag overrides emitHalftones; if this is false, then halftones are not emitted. The default value is true.
boundingBox
If all zeroes, is ignored. Otherwise, is used for %BoundingBox DSC comment and in centerCropBox calculations and for setpagedevice. The default value is [0 0 0 0].
useFontAliasNames
Used when printing with system fonts. The default value is false.
emitPageRotation
Emit a concat at the beginning of each page so that the page is properly rotated. Used when emitting EPS. The default value is false.
reverse
If set to true, reverse the order of page output.
tCropBox
Temporary crop box to represent selected region.
emitPageClip
Set to true to emit page clip.
emitTransfer
Set to true to emit transfer.
emitBG
Set to true to emit black generation.
emitUCR
Set to true to emit undercolor removal.
farEastFontOpt
Far East font option. Currently not used. Set to 0.
suppressCJKSubstitution
If true, do not do CJK substitution on the printer.
suppressCSA
If true, don't emit CSAs for 4 component (CMYK) colors.
hostBased
For separator, do host-based color management.
hostBasedOutputCS
The output color space when hostBased color management is true.
duplex
Currently not used. Set to 0.
doTiling
Whether to tile none, all, or only large pages
tileInfo
If non-NULL, tiling is desired with these parameters.
rotate
Enable the auto-rotating behavior from past versions of Acrobat.
hostBasedCM
Host base color management. Default: false, do CSA generation for profiles instead of converting all colors on the host.
destProfile
If hostBaseCM color management is true, use this profile.
destCSAtom
An atom representing the device color space (DeviceGray, DeviceRGB, etc.).
saveVM
True means try to save VM when printing to PostScript.
doOPP
If true, do the overprint preview operation.
suppressOPPWhenNoSpots
When true, suppress OPP for pages that do not contain spot colors
optimizeForSpeed
If true, do it fast; false means PostScript code must be page independent. If set to true, font downloads are forced from IG_PDF_INCLUDE_ON_EVERY_PAGE to IG_PDF_INCLUDE_ONCE_PER_DOC.
brokenCRDs
If true, don't set rendering intent in PostScript stream due to broken non-default CRDs.
useMaxVM
If true, store all possible resources in VM.
lastWidth
Used when setPageSize is true to prevent unneeded setpagedevice calls.
lastHeight
Used when setPageSize is true to prevent unneeded setpagedevice calls.
bitmapResolution
DPI for bitmaps. Default is 300.
gradientResolution
DPI for gradients interior to the object (not edges). Can generally be lower than the bitmapResolution. Default is 150.
transparencyQuality
The transparency level. Range is 1-100.
ocContext
The optional-content context to use for visibility state information, or NULL to use the document's current states in the default context.
applyOCGPrintOverrides
When true, apply print-specific visibility state settings from the optional-content group.
useFullResolutionJP2KData
Whether to use the maximum available JPEG2000 resolution.
emitInRipSeps
When true, requests that separations, one sheet per ink, be generated in the RIP (printer).
whichMarks
Page mark indication. A bit-wise OR of the enumIGPDFPageMarkFlags values.
westernMarksStyle
When true, use western style for page marks.
doProofing
When true, print using proofing settings.
proofProfile
Description string for the proofing profile.
inkBlack
Proofing settings: simulate ink black.
paperWhite
Proofing settings: simulate paper white.
useExecForm
When true, emit execform calls when emitting Form XObjects.
flattenInfo
A structure containing parameters that control tile flattening.
negative
When true, invert the plate.
mirrorprint
PostScript mirroring attribute. Currently not used.
numCollatedCopies
Enables collation for viewer.
emitFlatness
Set to true to emit flatness.
trapType
Specifies trap type.
TTasCIDT2
Set to true to emit TrueType fonts as CIDType2 instead of as CIDFontType0.
markStyle
Specify the style to use for page marks.
lineWidth
Line width to use for printer marks.
macQDPrinter
Set to true if the printer is a Mac QuickDraw printer.

Definition:

This structure indicates how a document should be printed.

NOTE: All fields in the AT_PDF_PRINTPARAMS structure apply to PostScript file creation. AT_PDF_PRINTPARAMS are ignored when printing to non-PostScript devices.


AT_PDF_SECURITYDATA

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDF_SECURITYDATA
{
    DWORD size;
    AT_PDF_BOOL newUserPW;
    AT_PDF_BOOL hasUserPW;
    CHAR userPW[256];
    AT_PDF_BOOL newOwnerPW;
    AT_PDF_BOOL hasOwnerPW;
    CHAR ownerPW[256];
    UINT perms;
    LONG keyLength;
    LONG revision;
    AT_PDF_BOOL encryptMetadata;
    LONG encryptMethod;
    AT_PDF_BOOL encryptAttachmentsOnly;

} AT_PDF_SECURITYDATA;
typedef AT_PDF_SECURITYDATA FAR* LPAT_PDF_SECURITYDATA;

Arguments:

DWORD
size
Size of this stucture.
AT_PDF_BOOL
newUserPW
True if the user password should be changed.
AT_PDF_BOOL
hasUserPW
True if there is a user password.
CHAR
userPW[256]
The user password string.
AT_PDF_BOOL
newOwnerPW
True if the owner password should be changed, false otherwise.
AT_PDF_BOOL
hasOwnerPW
True if an owner password is provided, false otherwise.
CHAR
ownerPW[256]
The owner password string.
UINT
perms
Permissions to allow. An OR of the enumIGPDFPermsFlags values.
LONG
keyLength
Encryption key length in byte.
LONG
revision
Indicates /R value.
AT_PDF_BOOL
encryptMetadata
Flag that indicates whether document metadata will be encrypted.
LONG
encryptMethod
Method of encryption for filters to use. One of the enumIGPDFStdSecurityMethod values.
AT_PDF_BOOL
encryptAttachmentsOnly
Flag to indicate that only Attachments are encrypted - encryptMetadata and encryptAttachmentsOnly cannot both be true.

Description:

This structure describes the data for the standard security handler.

NOTE: The password strings in PDF are padded or truncated to exactly 32 bytes. If the password string is more than 32 bytes long, used only its first 32 bytes; if it is less than 32 bytes long, it padded by appending the required number of additional bytes from the beginning of the following padding string: <28 BF 4E 5E 4E 75 8A 41 64 00 4E 56 FF FA 01 08 2E 2E 00 B6 D0 68 3E 80 2F 0C A9 FE 64 53 69 7A >


AT_PDE_FONTATTRS

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_FONTATTRS
{
    HIG_PDF_ATOM				name;
    HIG_PDF_ATOM				type;
    HIG_PDF_ATOM				charSet;
    HIG_PDF_ATOM				encoding;
    UINT		flags;
    AT_PDF_FIXEDRECT					fontBBox;
    SHORT  		missingWidth;
    SHORT  		stemV;
    SHORT  		stemH;
    SHORT  		capHeight;
    SHORT  		xHeight;
    SHORT  		ascent;
    SHORT  		descent;
    SHORT  		leading;
    SHORT  		maxWidth;
    SHORT  		avgWidth;
    SHORT  		italicAngle;
    HIG_PDF_ATOM				cidFontType;
    SHORT			wMode;
    HIG_PDF_ATOM				psName;
    HIG_PDF_ATOM				platformName;
    HIG_PDF_ATOM				lang;
    HIG_PDF_ATOM				registry;
    HIG_PDF_ATOM				ordering;
    LONG		supplement;
    LONG		cantEmbed;
    HIG_PDF_ATOM				deltaEncoding;
    UINT		protection;
    LONG		packageType;
} AT_PDE_FONTATTRS;
typedef AT_PDE_FONTATTRS FAR* LPAT_PDE_FONTATTRS;

Arguments:

HIG_PDF_ATOM
name
A HIG_PDF_ATOM for font name, as in "Times-Roman." Corresponds to the BaseFont key in the font dictionary of a PDF file (see Section 5.6.3 in the PDF Reference).
HIG_PDF_ATOM
type
A HIG_PDF_ATOM for font type, corresponding to the Subtype key in a font dictionary. May be "Type1," "TrueType," "MMType1," or "Type0."
HIG_PDF_ATOM
charSet
A HIG_PDF_ATOM for "Roman" or IG_PDF_ATOM_NULL. If "Roman," the characters must be a subset of the Adobe Standard Roman Character Set.
HIG_PDF_ATOM
encoding
An HIG_PDF_ATOM for font encoding. May be MacRomanEncoding, WinAnsiEncoding, or IG_PDF_ATOM_NULL. In the case of IG_PDF_ATOM_NULL, call PDSysFontGetEncoding to get more information about the encoding.
UINT
flags
Desired font flags, one or more of Font Flags. Use IG_PDF_SCRIPT, etc. to get flags.
AT_PDF_FIXEDRECT
fontBBox
Font bounding box in 1000 EM units
SHORT
missingWidth
Width of missing character (.notdef)
SHORT
stemV
Vertical stem width
SHORT
stemH
Horizontal stem width
SHORT
capHeight
Capital height
SHORT
xHeight
X height
SHORT
ascent
Max ascender height
SHORT
descent
Max descender depth
SHORT
leading
Additional leading between lines
SHORT
maxWidth
Maximum character width
SHORT
avgWidth
Average character width
SHORT
italicAngle
Italic angle in degrees, if any
HIG_PDF_ATOM
cidFontType
CIDFontType0 or CIDFontType2
SHORT
wMode
Writing mode. Must be one of 0 for horizontal writing or 1 for vertical writing
HIG_PDF_ATOM
psName
HIG_PDF_ATOM representing the PostScript name of a TrueType font.
HIG_PDF_ATOM
platformName
The platform name
HIG_PDF_ATOM
lang
HIG_PDF_ATOM representing the ISO 639 language code. These are available from http://www.iso.ch.
HIG_PDF_ATOM
registry
HIG_PDF_ATOM representing the CIDFont's Registry information, as in "gAdobe-Japan".
HIG_PDF_ATOM
ordering
HIG_PDF_ATOM representing the CIDFont's Ordering information, for example, "g1".
LONG
supplement
The SystemSupplement field from the CIDFont.
LONG
cantEmbed
A non-zero value means the font can't be embedded.
HIG_PDF_ATOM
deltaEncoding
The name of the base encoding; that is, the BaseEncoding entry in an encoding dictionary (see section 5.5.5 of the PDF Reference). The Differences entry of the encoding dictionary describes differences (deltas) from the base encoding.
UINT
protection
protection Allows setting one of the following bits to disable font embedding: IG_PDE_FONT_NO_EMBEDDING = 1: font should not be embedded.
IG_PDE_FONT_NO_EDITABLE_EMBEDDING = 2: font should not be embedded for editing purposes.
LONG
packageType
enumIGPDFSysFontPackageType

Description:

Attributes for HIG_PDE_FONT and HIG_PDF_SYSFONT.


AT_PDE_COLORVALUE

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_COLORVALUE
{
    AT_PDF_FIXED color[7];
    HIG_PDE_OBJECT colorObj2;
    HIG_PDE_OBJECT colorObj;

} AT_PDE_COLORVALUE;
typedef AT_PDE_COLORVALUE FAR* LPAT_PDE_COLORVALUE;

Arguments:

AT_PDF_FIXED
color[7]
Color value components. For instance, a Gray color space has 1 component, an RGB color space has 3 components, a CMYK has 4 components, and so on.
HIG_PDE_OBJECT
colorObj2
For DeviceN color space
HIG_PDE_OBJECT
colorObj
For color spaces whose color values do not have numeric values, such as the Pattern and Separation color spaces.

Description:

Describes color value.


AT_PDE_COLORSPEC

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_COLORSPEC
{
    HIG_PDE_COLORSPACE space;
    AT_PDE_COLORVALUE value;

} AT_PDE_COLORSPEC;
typedef AT_PDE_COLORSPEC FAR* LPAT_PDE_COLORSPEC;

Arguments:

HIG_PDE_COLORSPACE
space
The specified color space
AT_PDE_COLORVALUE
value
The color value.

Description:

Describes color specification.


AT_PDE_DASH

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_DASH
{
    AT_PDF_FIXED dashPhase;
    LONG dashLen;
    AT_PDF_FIXED dashes[11];

} AT_PDE_DASH;
typedef AT_PDE_DASH FAR* LPAT_PDE_DASH;

Arguments:

AT_PDF_FIXED
dashPhase
Dash phase. Phase is a number that specifies a distance in user space into the dash pattern at which to begin marking the path.
LONG
dashLen
Number of entries in the dash array, an element of the Border array.
AT_PDF_FIXED
dashes[11]
Dash array, which specifies distances in user space for the length of dashes and gaps.

Description:

Describes dash specification, as described in Table 4.8 in the PDF Reference. See Section 4.3.2 for more information on line dash patterns.


AT_PDE_GRAPHICSTATE

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_GRAPHICSTATE
{
    UINT wasSetFlags;
    AT_PDE_COLORSPEC fillColorSpec;
    AT_PDE_COLORSPEC strokeColorSpec;
    AT_PDE_DASH dash;
    AT_PDF_FIXED lineWidth;
    AT_PDF_FIXED miterLimit;
    AT_PDF_FIXED flatness;
    LONG lineCap;
    LONG lineJoin;
    HIG_PDF_ATOM renderIntent;
    HIG_PDE_OBJECT extGState;

} AT_PDE_GRAPHICSTATE;
typedef AT_PDE_GRAPHICSTATE FAR* LPAT_PDE_GRAPHICSTATE;

Arguments:

UINT
wasSetFlags
enumIGPDEGraphicStateWasSetFlags indicating if an attribute has been set.
NOTE: Support for these flags is not complete. For compatibility, you should set them, but do not depend on reading their values back. The intended use is with XObject Forms to indicate whether the value is inherited or explicitly set.
AT_PDE_COLORSPEC
fillColorSpec
Fill color specification. The default value is DeviceGray, IG_PDF_FIXED_ZERO.
AT_PDE_COLORSPEC
strokeColorSpec
Stroke color specification. The default value is DeviceGray, IG_PDF_FIXED_ZERO.
AT_PDE_DASH
dash
Dash specification. The default value is [0, 0].
AT_PDF_FIXED
lineWidth
Line width, corresponding to the w (setlinewidth) operator. The default value is IG_PDF_FIXED_ONE.
AT_PDF_FIXED
miterLimit
Miter limit, corresponding to the M (setmiterlimit) operator. The default value is IG_PDF_FIXED_TEN.
AT_PDF_FIXED
flatness
Line flatness, corresponding to the i (setflat) operator. The default value is IG_PDF_FIXED_ZERO.
LONG
lineCap
Line cap style, corresponding to the J (setlinecap) operator. The default value is 0.
LONG
lineJoin
Line join style, corresponding to the j (setlinejoin) operator. The default value is 0.
HIG_PDF_ATOM
renderIntent
A color rendering intent, corresponding to the Intent key in the image dictionary. The default value is 0.
HIG_PDE_OBJECT
extGState
An extended graphics, corresponding to the gs operator. The default value is NULL.

Description:

Attributes of a PDE element or a PDE text sub-element.


AT_PDE_TEXTSTATE

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_TEXTSTATE
{
    UINT wasSetFlags;
    AT_PDF_FIXED charSpacing;
    AT_PDF_FIXED wordSpacing;
    LONG renderMode;
    AT_PDF_FIXED fontSize;
    AT_PDF_FIXED hScale;
    AT_PDF_FIXED textRise;

} AT_PDE_TEXTSTATE;
typedef AT_PDE_TEXTSTATE FAR* LPAT_PDE_TEXTSTATE;

Arguments:

UINT
wasSetFlags
enumIGPDEGraphicStateWasSetFlags indicating if an attribute has been set.
NOTE: Support for these flags is not complete. For compatibility, you should set them, but do not depend on reading their values back. The intended use is with XObject Forms to indicate whether the value is inherited or explicitly set.
NOTE: PDFEdit ignores the wasSetFlags flag, so you must initialize the AT_PDE_TEXTSTATE fields.
AT_PDF_FIXED
charSpacing
Character spacing was set, corresponding to the Tc operator.
AT_PDF_FIXED
wordSpacing
Word spacing, corresponding to the Tw operator.
LONG
renderMode
Text rendering mode, corresponding to the Tr operator.
AT_PDF_FIXED
fontSize
Default is 1.
AT_PDF_FIXED
hScale
Default=100 (==100%)
AT_PDF_FIXED
textRise
Specifies the distance, in text space units that are not scaled, to move the baseline up or down from its default location. See Section 5.2.6 in the PDF Reference.

Description:

Attributes of a PDE text element.


AT_PDF_SYSFONT_PLATDATA

Group: Subsidiary Type

Declaration (WINDOWS):

typedef struct tagAT_PDF_SYSFONT_PLATDATA
{
    DWORD size;
    LOGFONT *lf;
    DWORD fontPath;
    DWORD afmPath;

} AT_PDF_SYSFONT_PLATDATA;
typedef AT_PDF_SYSFONT_PLATDATA FAR* LPAT_PDF_SYSFONT_PLATDATA;

Arguments (WINDOWS):

DWORD
size
sizeof(AT_PDF_SYSFONT_PLATDATA)
LOGFONT
*lf
(Windows only) Windows LOGFONT structure defining font attributes.
DWORD
fontPath
Not used
DWORD
afmPath
Not used

Declaration (MAC):

typedef struct tagAT_PDF_SYSFONT_PLATDATA
{
    DWORD size;
    PDFSysFontFID fontID;
    PDFSysFontFStyle fontStyle;

} AT_PDF_SYSFONT_PLATDATA;
typedef AT_PDF_SYSFONT_PLATDATA FAR* LPAT_PDF_SYSFONT_PLATDATA;

Arguments (MAC):

DWORD
size
sizeof(AT_PDF_SYSFONT_PLATDATA)
PDFSysFontFID
fontID
FontID
PDFSysFontFID
fontStyle
Style value within that Font - default = 0

Declaration (UNIX):

typedef struct tagAT_PDF_SYSFONT_PLATDATA
{
    DWORD size;
    DWORD fontPath;
    DWORD afmPath;

} AT_PDF_SYSFONT_PLATDATA;
typedef AT_PDF_SYSFONT_PLATDATA FAR* LPAT_PDF_SYSFONT_PLATDATA;

Arguments (UNIX):

DWORD
size
sizeof(AT_PDF_SYSFONT_PLATDATA)
DWORD
fontPath
Not used
DWORD
afmPath
Not used

Description:

SysFont platform specific data.


AT_PDE_FONT_INFO

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_FONT_INFO
{
    HIG_PDF_ATOM name;
    HIG_PDF_ATOM type;
    HIG_PDF_ATOM charSet;
    HIG_PDF_ATOM encoding;
    SHORT wMode;

} AT_PDE_FONT_INFO;
typedef AT_PDE_FONT_INFO FAR* LPAT_PDE_FONT_INFO;

Arguments:

HIG_PDF_ATOM
name
HIG_PDF_ATOM for font name, as in "Times-Roman."
HIG_PDF_ATOM
type
HIG_PDF_ATOM for font type, "Type 1," "TrueType," and so on.
HIG_PDF_ATOM
charSet
HIG_PDF_ATOM for "Roman" or IG_PDF_ATOM_NULL. If "Roman," the characters must be a subset of the Adobe Standard Roman Character Set.
HIG_PDF_ATOM
encoding
HIG_PDF_ATOM for font encoding, as in WinAnsiEncoding.
SHORT
wMode
Writing mode: 0 = horizontal; 1 = vertical.

Description:

PDE font information


AT_PDE_FONT_CREATEFROMSYSFONTPARAMS

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_FONT_CREATEFROMSYSFONTPARAMS
{
    UINT structSize;
    UINT flags;
    HIG_PDF_ATOM snapshotName;
    AT_PDF_FIXED *mmDesignVec;
    LONG ctCodePage;
    HIG_PDF_ATOM encoding;

} AT_PDE_FONT_CREATEFROMSYSFONTPARAMS;
typedef AT_PDE_FONT_CREATEFROMSYSFONTPARAMS FAR*
LPAT_PDE_FONT_CREATEFROMSYSFONTPARAMS;

Arguments:

UINT
structSize
Size of the data structure. Must be set to sizeof(AT_PDE_FONT_CREATEFROMSYSFONTPARAMS).
UINT
flags
A bit mask of the enumIGPDEFontCreateFlags.
HIG_PDF_ATOM
snapshotName
The name of a multiple master snapshot. See PDF Reference for more information on snapshots.
AT_PDF_FIXED
*mmDesignVec
Pointer to multiple master font design vector.
LONG
ctCodePage
Used to select a specific code page supported by the font. When a non-zero code page is supplied, embedding must be turned on and the IG_PDE_FONT_ENCODE_BY_GID flag set.
HIG_PDF_ATOM
encoding
Used to specify which encoding to use with a CID font. Pass IG_PDF_ATOM_NULL to use the platform default.

Description:

Data structure used with PDE Font creation.


AT_PDE_COLORRANGE

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_COLORRANGE
{
    float min;
    float max;
} AT_PDE_COLORRANGE;
typedef AT_PDE_COLORRANGE FAR* LPAT_PDE_COLORRANGE;

Arguments:

float
min
float
max

Description:

Contains color range


AT_PDE_XYZCOLOR

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_XYZCOLOR
{
    float x;
    float y;
    float z;

} AT_PDE_XYZCOLOR;
typedef AT_PDE_XYZCOLOR FAR* LPAT_PDE_XYZCOLOR;

Arguments:

float
x
float
y
float
z

Description:

XYZ color data


AT_PDE_COLORDATA_CALGRAY

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_COLORDATA_CALGRAY
{
    AT_PDE_XYZCOLOR whitePoint;
    AT_PDE_XYZCOLOR blackPoint;
    float gamma;
} AT_PDE_COLORDATA_CALGRAY;
typedef AT_PDE_COLORDATA_CALGRAY FAR*
LPAT_PDE_COLORDATA_CALGRAY;

Arguments:

AT_PDE_XYZCOLOR
whitePoint
White point
AT_PDE_XYZCOLOR
blackPoint
Black point
float
gamma
Gamma

Description:

Describes a CalGray color space.

Default calGray = {{0, 0, 0}, {0, 0, 0}, 1};


AT_PDE_COLORDATA_CALRGB

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_COLORDATA_CALRGB
{
    AT_PDE_XYZCOLOR whitePoint;
    AT_PDE_XYZCOLOR blackPoint;
    float redGamma;
    float greenGamma;
    float blueGamma;
    float matrix[9];

} AT_PDE_COLORDATA_CALRGB;
typedef AT_PDE_COLORDATA_CALRGB FAR* LPAT_PDE_COLORDATA_CALRGB;

Arguments:

AT_PDE_XYZCOLOR
whitePoint
White point
AT_PDE_XYZCOLOR
blackPoint
Black point
float
redGamma
Red gamma
float
greenGamma
Green gamma
float
blueGamma
Blue gamma
float
matrix[9]
Matrix

Description:

Describes a CalRGB color space.

Default calRGB = {{0, 0, 0}, {0, 0, 0}, 1, 1, 1, {1, 0, 0, 0, 1, 0, 0, 0, 1}};


AT_PDE_COLORDATA_LAB

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_COLORDATA_LAB
{
    AT_PDE_XYZCOLOR whitePoint;
    AT_PDE_XYZCOLOR blackPoint;
    AT_PDE_COLORRANGE rangeA, rangeB;

} AT_PDE_COLORDATA_LAB;
typedef AT_PDE_COLORDATA_LAB FAR* LPAT_PDE_COLORDATA_LAB;

Arguments:

AT_PDE_XYZCOLOR
whitePoint
White point
AT_PDE_XYZCOLOR
blackPoint
Black point
AT_PDE_COLORRANGE
rangeA, rangeB
Color ranges

Description:

Describes a L*a*b* color space.

Default lab = {{0, 0, 0}, {0, 0, 0}, {-100, 100}, {-100, 100}};


AT_PDE_COLORDATA_ICCBASED

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_COLORDATA_ICCBASED
{
    DWORD size;
    HIG_PDF_STREAM iccstream;
    UINT nComps;
    HIG_PDE_COLORSPACE altCs;

} AT_PDE_COLORDATA_ICCBASED;
typedef AT_PDE_COLORDATA_ICCBASED FAR*
LPAT_PDE_COLORDATA_ICCBASED;

Arguments:

DWORD
size
size = sizeof(AT_PDE_COLORDATA_ICCBASED)
HIG_PDF_STREAM
iccstream
stream containing ICC Profile
UINT
nComps
Number of color components (1, 3, or 4)
HIG_PDE_COLORSPACE
altCs
Alternate ColorSpace (optional)

Description:

ICC based color space


AT_PDE_COLORDATA_INDEXED

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_COLORDATA_INDEXED
{
    DWORD size;
    HIG_PDE_COLORSPACE baseCs;
    WORD hival;
    LPBYTE lookup;
    UINT lookupLen;

} AT_PDE_COLORDATA_INDEXED;
typedef AT_PDE_COLORDATA_INDEXED FAR*
LPAT_PDE_COLORDATA_INDEXED;

Arguments:

DWORD
size
size = sizeof(AT_PDE_COLORDATA_INDEXED)
HIG_PDE_COLORSPACE
baseCs
base colorspace
WORD
hival
highest color value
LPBYTE
lookup
Indexed color lookup data.
UINT
lookupLen
number of bytes in lookup data

Description:

Indexed color space


AT_PDE_COLORDATA_SEPARATION

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_COLORDATA_SEPARATION
{
    DWORD size;
    HIG_PDF_ATOM name;
    HIG_PDE_COLORSPACE alt;
    HIG_PDF_BASOBJ tintTransform;

} AT_PDE_COLORDATA_SEPARATION;
typedef AT_PDE_COLORDATA_SEPARATION FAR*
LPAT_PDE_COLORDATA_SEPARATION;

Arguments:

DWORD
size
size = sizeof(AT_PDE_COLORDATA_SEPARATION)
HIG_PDF_ATOM
name
name of separation or colorant
HIG_PDE_COLORSPACE
alt
Alternative colorspace
HIG_PDF_BASOBJ
tintTransform
The tintTransform dictionary or function. See Section 4.5.5 in the PDF Reference for more information.

Description:

Separation color space


AT_PDE_COLORDATA_DEVICEN

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_COLORDATA_DEVICEN
{
    DWORD size;
    HIG_PDF_ATOM *names;
    UINT nNames;
    HIG_PDE_COLORSPACE alt;
    HIG_PDF_BASOBJ tintTransform;

} AT_PDE_COLORDATA_DEVICEN;
typedef AT_PDE_COLORDATA_DEVICEN FAR*
LPAT_PDE_COLORDATA_DEVICEN;

Arguments:

DWORD
size
size = sizeof(AT_PDE_COLORDATA_DEVICEN)
HIG_PDF_ATOM
*names
names of colorants
UINT
nNames
number of colorants
HIG_PDE_COLORSPACE
alt
Alternative colorspace
HIG_PDF_BASOBJ
tintTransform
The tintTransform dictionary or function. See Section 4.5.5 in the PDF Reference for more information.

Description:

DeviceN color space.


AT_PDE_COLORDATA

Group: Subsidiary Type

Declaration:

typedef union tagAT_PDE_COLORDATA
{
    AT_PDE_COLORDATA_CALGRAY *calGray;
    AT_PDE_COLORDATA_CALRGB *calRGB;
    AT_PDE_COLORDATA_LAB *lab;
    AT_PDE_COLORDATA_ICCBASED *icc;
    AT_PDE_COLORDATA_INDEXED *indexed;
    HIG_PDE_COLORSPACE patternbase;
    AT_PDE_COLORDATA_SEPARATION *sep;
    AT_PDE_COLORDATA_DEVICEN *devn;

} AT_PDE_COLORDATA;
typedef AT_PDE_COLORDATA FAR* LPAT_PDE_COLORDATA;

Arguments:

AT_PDE_COLORDATA_CALGRAY
*calGray
AT_PDE_COLORDATA_CALRGB
*calRGB
AT_PDE_COLORDATA_LAB
*lab
AT_PDE_COLORDATA_ICCBASED
*icc
AT_PDE_COLORDATA_INDEXED
*indexed
HIG_PDE_COLORSPACE
patternbase
AT_PDE_COLORDATA_SEPARATION
*sep
AT_PDE_COLORDATA_DEVICEN
*devn

Description:

Fill in one of the following members of this union then pass this data to PDE color space creation routine. Please see section 7.10 of the PDF Reference Manual for information on color spaces.


AT_PDE_PSATTRS

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_PSATTRS
{
    UINT flags;

} AT_PDE_PSATTRS;
typedef AT_PDE_PSATTRS FAR* LPAT_PDE_PSATTRS;

Arguments:

UINT
flags
IG_PDE_PS_INLINE

Description:

Attributes of a PDE PostScript object


AT_PDE_IMAGEATTRS

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_IMAGEATTRS
{
    UINT flags;
    LONG width;
    LONG height;
    LONG bitsPerComponent;
    AT_PDF_FIXED decode[8];
    HIG_PDF_ATOM intent;

} AT_PDE_IMAGEATTRS;
typedef AT_PDE_IMAGEATTRS FAR* LPAT_PDE_IMAGEATTRS;

Arguments:

UINT
flags
enumIGPDEImageAttrFlags indicating image attributes.
LONG
width
Width of the image, corresponding to the Width key in the image dictionary.
LONG
height
Height of the image, corresponding to the Height key in the image dictionary.
LONG
bitsPerComponent
Number of bits used to represent each color component in the image, corresponding to the BitsPerComponent key in the image dictionary.
AT_PDF_FIXED
decode[8]
An array of numbers specifying the mapping from sample values in the image to values appropriate for the current color space. These values correspond to the Decode key in the image dictionary.
HIG_PDF_ATOM
intent
Color rendering intent, corresponding to the Intent key in the image dictionary.

Description:

Attributes of a PDE Image object


AT_PDE_FILTERSPEC

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_FILTERSPEC
{
    HIG_PDF_BASOBJ decodeParms;
    HIG_PDF_BASOBJ encodeParms;
    HIG_PDF_ATOM name;

} AT_PDE_FILTERSPEC;
typedef AT_PDE_FILTERSPEC FAR* LPAT_PDE_FILTERSPEC;

Arguments:

HIG_PDF_BASOBJ
decodeParms
Parameters used by the decoding filters specified with the Filter key. Corresponds to the DecodeParms key in the stream dictionary. Must be set to NULL if AT_PDE_FILTERSPEC is specified but no decode parameters are specified. This can be done by zeroing the unused decode params. Required decode params for DCTDecode are Columns, Rows, and Colors.
HIG_PDF_BASOBJ
encodeParms
Parameters used when encoding the stream. Required for DCTDecode filter; optional for other filters. Must be set to NULL if AT_PDE_FILTERSPEC is specified but no encode parameters are specified. This can be done by zeroing the unused encode params.
HIG_PDF_ATOM
name
Filter name. Supported filters are: ASCIIHexDecode, ASCII85Decode, LZWDecode, DCTDecode, CCITTFaxDecode, RunLengthDecode, and FlateDecode.

Description:

Filter element in a filter array.


AT_PDE_FILTERARRAY

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_FILTERARRAY
{
    LONG numFilters;
    AT_PDE_FILTERSPEC spec[2];

} AT_PDE_FILTERARRAY;
typedef AT_PDE_FILTERARRAY FAR* LPAT_PDE_FILTERARRAY;

Arguments:

LONG
numFilters
Number of filters in the array.
AT_PDE_FILTERSPEC
spec[2]
Variable length array of filter spec.

Description:

Array of filter specifications usually containing two or less filters: encoding and/or compression.


AT_PDE_CONTENTATTRS

Group: Subsidiary Type

Declaration:

typedef struct tagAT_PDE_CONTENTATTRS
{
    UINT flags;
    AT_PDF_FIXED cacheDevice[8];
    LONG formType;
    AT_PDF_FIXEDRECT bbox;
    AT_PDF_FIXEDMATRIX matrix;
    HIG_PDF_BASOBJ XUID;

} AT_PDE_CONTENTATTRS;
typedef AT_PDE_CONTENTATTRS FAR* LPAT_PDE_CONTENTATTRS;

Arguments:

UINT
flags
enumIGPDEContentFlags
AT_PDF_FIXED
cacheDevice[8]
CharProc attributes
If flags has IG_PDE_SET_CACHE_DEVICE set, the first 6 cache device values contain the operands for the d1 (setcachdevice) page operator. If flags has IG_PDE_SET_CHAR_WIDTH set, cacheDevice contains 2 charwidth values.
LONG
formType
Form attributes
Only used if HIG_PDE_CONTENT contains a Form XObject. Corresponds to FormType key in the XObject Form attributes dictionary.
AT_PDF_FIXEDRECT
bbox
Only used if HIG_PDE_CONTENT contains a Form. Bounding box of the HIG_PDE_CONTENT object. Corresponds to BBox key in the XObject Form attributes dictionary.
AT_PDF_FIXEDMATRIX
matrix
Only used if HIG_PDE_CONTENT contains a Form. Transformation matrix for the HIG_PDE_CONTENT object. Corresponds to Matrix key in the XObject Form attributes dictionary.
HIG_PDF_BASOBJ
XUID
Only used if HIG_PDE_CONTENT contains a Form. The form's XUID, an ID that uniquely identifies the form. Corresponds to XUID key in the XObject Form attributes dictionary.

Description:

Attributes of a PDE Content object


Enumerations

This section represents ImageGear PDF component enumerations including their meaning and values.


enumIGPDFBookmarkFlags

Group: Enumeration

Description:

Represents PDF bookmark flags.

Values:

IG_PDF_BOOKMARK_FONT_ITALIC
1
Italic font
IG_PDF_BOOKMARK_FONT_BOLD
2
Bold font


enumIGPDFCharset

Group: Enumeration

Description:

Represents the PDF Character Set

IG_PDF_CHARSET_UNKNOWN
0
The font does not use Adobe Standard Encoding.
IG_PDF_CHARSET_ROMAN
1
The font uses Adobe Standard encoding. This is determined by the "Uses Adobe Standard Encoding" bit in the font descriptor.
IG_PDF_CHARSET_EXPERT
2
Currently unused.
IG_PDF_CHARSET_LAST

Values:

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


enumIGPDFDestinationType

Group: Enumeration

Description:

Represents the types of PDF object destination.

Values:

IG_PDF_DEST_INVALID
0
Invalid destination
IG_PDF_DEST_EXPLICIT
1
Explicit destination
IG_PDF_DEST_NAMED
2
Named destination


enumIGPDFFixedValues

Group: Enumeration

Description:

PDF Fixed value. A variety of predefined fixed-point constants.

Values:

IG_PDF_FIXED_ZERO
((LONG) 0x00000000L)
0
IG_PDF_FIXED_HUNDREDTH
((LONG) 0x0000028FL)
1/100
IG_PDF_FIXED_SIXTEENTH
((LONG) 0x00001000L)
1/16
IG_PDF_FIXED_TWELFTH
((LONG) 0x00001555L)
1/12
IG_PDF_FIXED_TENTH
((LONG) 0x00001999L)
1/10
IG_PDF_FIXED_EIGHTH
((LONG) 0x00002000L)
1/8
IG_PDF_FIXED_QUARTER
((LONG) 0x00004000L)
1/4
IG_PDF_FIXED_THIRD
((LONG) 0x00005555L)
1/3
IG_PDF_FIXED_HALF
((LONG) 0x00008000L)
1/2
IG_PDF_FIXED_TWOTHIRDS
((LONG) 0x0000AAAAL)
2/3
IG_PDF_FIXED_THREEQUARTERS
((LONG) 0x0000C000L)
3/4
IG_PDF_FIXED_PI4
((LONG) 0x0000c910L)
PI/4
IG_PDF_FIXED_SEVENEIGHTS
((LONG) 0x0000E000L)
7/8
IG_PDF_FIXED_ONE1
((LONG) 0x0000ffffL)
-1
IG_PDF_FIXED_ONE
((LONG) 0x00010000L)
1
IG_PDF_FIXED_PI2
((LONG) 0x00019220L)
PI/2
IG_PDF_FIXED_GOLDEN
((LONG) 0x00019e37L)
Golden
IG_PDF_FIXED_TEN
((LONG) 0x000A0000L)
10
IG_PDF_FIXED_MAX
((LONG) 0x7FFFFFFF)
Max fixed-point value
IG_PDF_FIXED_MIN
((LONG) 0x80000000)
Min fixed-point value
IG_PDF_FIXED_NEGATIVE_INFINITY
((LONG) IG_PDF_FIXED_MAX)
Negative fixed-point infinity
IG_PDF_FIXED_POSITIVE_INFINITY
((LONG) IG_PDF_FIXED_MIN)
Positive fixed-point infinity


enumIGPDEType

Group: Enumeration

Description:

Types of the editing objects.

Values:

IG_PDE_CONTENT
0
Content
IG_PDE_TEXT
1
Text
IG_PDE_PATH
2
Path
IG_PDE_IMAGE
3
Image
IG_PDE_FORM
4
Form
IG_PDE_POSTSCRIPT
5
PostScript
IG_PDE_XOBJECT
6
XObject
IG_PDE_CLIP
7
Clip
IG_PDE_FONT
8
Font
IG_PDE_COLORSPACE
9
ColorSpace
IG_PDE_GSTATE
10
Graphic State
IG_PDE_PLACE
11
Place
IG_PDE_CONTAINER
12
Container
IG_PDF_SYSFONT
13
System Font
IG_PDE_PATTERN
14
Pattern
IG_PDE_DEVICENCOLORS
15
Device N Colors
IG_PDE_SHADING
16
Shading
IG_PDE_GROUP
17
Group
IG_PDE_UNKNOWN
18
Unknown
IG_PDE_BEGIN_CONTAINER
19
Begin Container
IG_PDE_END_CONTAINER
20
End Container
IG_PDE_BEGIN_GROUP
21
Begin Group
IG_PDE_END_GROUP
22
End Group
IG_PDE_XGROUP
23
XGroup
IG_PDE_SOFTMASK
24
SoftMask
IG_PDF_SYSENCODING
25
System Encoding
IG_PDE_DOC
26
Document
IG_PDE_PAGE
27
Page
IG_PDE_READER
28
Reader
IG_PDE_WRITER
29
Writer
IG_PDE_TEXTITEM
30
Text Item
IG_PDE_LASTTYPE
31
Last Type


enumIGPDEFontProtection

Group: Enumeration

Description:

Setting for disabling font embedding.

Values:

IG_PDE_FONT_NO_EMBEDDING
0x00000001
Flags for protection of AT_PDE_FONTATTRS - embedding is not allowed.
IG_PDE_FONT_NO_EDITABLE_EMBEDDING
0x00000002
Flags for protection of AT_PDE_FONTATTRS - editable embedding is not allowed.


enumIGPDETextFlags

Group: Enumeration

Description:

Flags used in the text API.

Values:

IG_PDE_TEXT_RUN
0x0001
Specifies an action for the run
IG_PDE_TEXT_CHAR
0x0002
Specifies an action for single character
IG_PDE_TEXT_PAGE_SPACE
0x0004
Specifies user space
IG_PDE_TEXT_GET_BOUNDS
0x0008
Specifies using the font descriptor's FontBBox


enumIGPDFPageNumber

Group: Enumeration

Description:

PageNumber specification.

Values:

IG_PDF_BEFORE_FIRST_PAGE
-1
Specifies position before the first page. Usually used to insert first document page.
IG_PDF_LAST_PAGE
-2
Specifies the last page position. Usually used to insert last document page.


enumIGPDEInsertElement

Group: Enumeration

Description:

Used for inserting a PDE element into the content.

Values:

IG_PDE_BEFORE_FIRST
((LONG) -1)
Specifies position before the first element. Usually used to insert first content element.
IG_PDE_AFTER_LAST
(IG_PDF_FIXED_MAX - 1)
Specifies the last element position. Usually used to insert last content element.


enumIGPDFFontFlags

Group: Enumeration

Description:

Font flags. Constants that indicate a font's attributes (fixed width, roman or symbolic, sans serif, and so forth).

Values:

IG_PDF_FIXED_WIDTH
0x00000001
All glyphs in the font are the same width.
IG_PDF_SERIF
0x00000002
The font is a serif font.
IG_PDF_PI
0x00000004
The font is a symbolic (pi) font.
IG_PDF_SCRIPT
0x00000008
The font is a script font.
IG_PDF_STD_ENCODING
0x00000020
The font uses standard encoding.
IG_PDF_ITALIC
0x00000040
The font is an italic font.
IG_PDF_ALL_CAP
0x00010000
The font is an all-caps font.
IG_PDF_SMALL_CAP
0x00020000
The font is a small caps font.
IG_PDF_FORCE_BOLD
0x00040000
Force bold characters to draw bold even at small point sizes.


enumIGPDEFontCreateFlags

Group: Enumeration

Description:

Flags for PDE font creation routine. If you want to subset a font, set both the IG_PDE_FONT_CREATE_EMBEDDED and IG_PDE_FONT_WILL_SUBSET flags.

Values:

IG_PDE_FONT_CREATE_NOT_ALLOWED
-1
Creation is not allowed. Usually returns by SysFont's "getCreateFlags" when the combination of SysFont and SysEncoding is not allowed.
IG_PDE_FONT_CREATE_EMBEDDED
0x0001
Embed the font. Create an embedded font. By itself, this will not subset the font.
IG_PDE_FONT_WILL_SUBSET
0x0002
Subset the font. If you want to subset a font, set both the IG_PDE_FONT_CREATE_EMBEDDED and IG_PDE_FONT_WILL_SUBSET flags. You must call "subsetNow" to actually subset the font. Both embedding and sub-setting a font creates a CFF font.
IG_PDE_FONT_DO_NOT_EMBED
0x0004
Do not embed the font. You cannot set both this and the IG_PDE_FONT_WILL_SUBSET flags. Nor can you set IG_PDE_FONT_CREATE_EMBEDDED.
IG_PDE_FONT_ENCODE_BY_GID
0x0008
Create a CIDFont with identity (GID) encoding.
IG_PDE_FONT_DEFER_WIDTHS
0x0010
Wait to get widths until later (affects Type0 fonts only).
IG_PDE_FONT_CREATE_SUBSET
0x0002
Subset the font. If you want to subset a font, set both the IG_PDE_FONT_CREATE_EMBEDDED and IG_PDE_FONT_WILL_SUBSET flags. You must call "subsetNow" to actually subset the font. Both embedding and sub-setting a font creates a CFF font.
IG_PDE_FONT_CREATE_GID_OVERRIDE
0x0020
The library will convert cp to gid with identity embedded
IG_PDE_FONT_CREATE_TO_UNICODE
0x0040
Create ToUnicode cmap
IG_PDE_FONT_CREATE_ALL_WIDTHS
0x0080
Supply entire widths table (affects Type0 fonts only)


enumIGPDEFontCreateNeedFlags

Group: Enumeration

Description:

Flags for PDE Font CreateNeedFlags.

Values:

IG_PDE_FONT_CREATE_NEED_WIDTHS
0x00010000
Need to create width
IG_PDE_FONT_CREATE_NEED_TO_UNICODE
0x00020000
Need to create ToUnicode stream
IG_PDE_FONT_CREATE_NEED_EMBED
0x00040000
Need to embed it


enumIGPDFSysFontPackageType

Group: Enumeration

Description:

Flags for packageType of AT_PDE_FONTATTRS/IGPDEFontAttrs.

Values:

IG_PDF_SYSFONT_UNKNOWN
0
Unknown
IG_PDF_SYSFONT_TYPE1
1
Type1
IG_PDF_SYSFONT_TRUETYPE
2
TrueType
IG_PDF_SYSFONT_CID
3
CID
IG_PDF_SYSFONT_ATC
4
ATC
IG_PDF_SYSFONT_OCF
5
OCF
IG_PDF_SYSFONT_OPENTYPE_CFF
6
OpenType CFF
IG_PDF_SYSFONT_OPENTYPE_CID
7
OpenType CID
IG_PDF_SYSFONT_OPENTYPE_TT
8
OpenType TT


enumIGPDFSysFontMatchFlags

Group: Enumeration

Description:

Font matching flags for SysFont find routine.

Values:

IG_PDF_SYSFONT_MATCH_NAME_AND_CHARSET
0x0001
Match the font name and character set.
IG_PDF_SYSFONT_MATCH_FONT_TYPE
0x0002
Match the font type
IG_PDF_SYSFONT_MATCH_WRITING_MODE
0x0004
Match the writing mode, that is, horizontal or vertical.


enumIGPDEGraphicStateWasSetFlags

Group: Enumeration

Description:

Structure describing the graphics state that was set.

Values:

IG_PDE_FILL_CSPACE_WAS_SET
0x0001
A fill color space was set, corresponding to the cs (setcolorspace) operator.
IG_PDE_FILL_CVALUE_WAS_SET
0x0002
A color fill value was set, corresponding to the sc (setcolor) operator.
IG_PDE_STROKE_CSPACE_WAS_SET
0x0004
A color space stroke value was set, corresponding to the CS (setcolorspace) operator.
IG_PDE_STROKE_CVALUE_WAS_SET
0x0008
A color stroke value was set, corresponding to the SC (setcolor) operator.
IG_PDE_DASH_WAS_SET
0x0010
A dash specification was set, corresponding to the d (setdash) operator.
IG_PDE_LINE_WIDTH_WAS_SET
0x0020
The line width was set, corresponding to the w (setlinewidth) operator.
IG_PDE_MITER_LIMIT_WAS_SET
0x0040
The miter limit was set, corresponding to the M (setmiterlimit) operator.
IG_PDE_FLATNESS_WAS_SET
0x0080
Line flatness was set, corresponding to the i (setflat) operator.
IG_PDE_LINE_CAP_WAS_SET
0x0100
Line cap style was set, corresponding to the J (setlinecap) operator.
IG_PDE_LINE_JOIN_WAS_SET
0x0200
Line join style was set, corresponding to the j (setlinejoin) operator.
IG_PDE_RENDER_INTENT_WAS_SET
0x0400
A color rendering intent was set, corresponding to the Intent key in the image dictionary.
IG_PDE_EXT_GSTATE_WAS_SET
0x0800
An extended graphics state was set, corresponding to the gs operator.


enumIGPDEImageDataFlags

Group: Enumeration

Description:

Image Data Flags.

Values:

AT_PDE_IMAGE_DATA_NOT_ENCODED
0x0000
Indicates filter is active; data is not encoded.
AT_PDE_IMAGE_ENCODED_DATA
0x0001
Indicates filter is active; data is encoded.


enumIGPDEXGroupCreateFlags

Group: Enumeration

Description:

Enumerated data type used to specify the type of transparency group to create.

Values:

IG_PDE_XGROUP_TYPE_TRANSPARENCY
0x0001
Creates a transparency XGroup object.


enumIGPDESoftMaskCreateFlags

Group: Enumeration

Description:

Flags for use with SoftMask create.

Values:

IG_PDE_SOFTMASK_TYPE_LUMINOSITY
0x0001
Specifies how the mask is to be computed.
IG_PDE_SOFTMASK_TYPE_ALPHA
0x0002
Specifies how the mask is to be computed.


enumIGPDEImageAttrFlags

Group: Enumeration

Description:

Flags for AT_PDE_IMAGEATTRS/IGPDEImageAttrs. See Section 4.8.4 in the PDF Reference for more information on image attributes.

Values:

IG_PDE_IMAGE_EXTERNAL
0x0001
Image is an XObject
IG_PDE_IMAGE_MASK
0x0002
Image is an imagemask
IG_PDE_IMAGE_INTERPOLATE
0x0004
Interpolate is true
IG_PDE_IMAGE_HAVE_DECODE
0x0008
We have a decode array
IG_PDE_IMAGE_INDEXED
0x0010
Uses an indexed color space
IG_PDE_IMAGE_MASKED_BY_POSITION
0x0020
Image has a Mask key containing an ImageMask stream
IG_PDE_IMAGE_MASKED_BY_COLOR
0x0040
Image has a Mask key containing an array of color values


enumIGPDEPSAttrFlags

Group: Enumeration

Description:

Flags for AT_PDE_PSATTRS/IGPDEPSAttrs.

Values:

IG_PDE_PS_INLINE
0
Inline PostScript


enumIGPDEElementCopyFlags

Group: Enumeration

Description:

Bitfield for PDE element copy.

Values:

IG_PDE_ELEMENT_COPY_FOR_CLIP
0x0001
Copied element does not need gstate or clip
IG_PDE_ELEMENT_COPY_CLIPPING
0x0002
Acquire the clip path and put it in the copied object


enumIGPDEContentGetResourceFlags

Group: Enumeration

Description:

Bit field for AT_PDE_CONTENTATTRS/IGPDEContentAttrs.

Values:

IG_PDE_GET_FONTS
0
Obtain font resources.
IG_PDE_GET_XOBJECTS
1
Obtain Xobject resources.
IG_PDE_GET_COLORSPACES
2
Obtain color space resources.


enumIGPDEContentFlags

Group: Enumeration

Description:

Bit field for AT_PDE_CONTENTATTRS/IGPDEContentAttrs.

Values:

IG_PDE_SET_CACHE_DEVICE
0x0001
if set, cacheDevice contains 6 cache device values
IG_PDE_SET_CHAR_WIDTH
0x0002
if set, cacheDevice contains 2 charwidth values
IG_PDE_FORM_MATRIX
0x0004
if set, formMatrix contains a valid matrix


enumIGPDFWordFlags

Group: Enumeration

Description:

Context flags.

Values:

IG_PDF_ORDER
0x2
Use PDF order for text enumeration
IG_PDF_XY_SORT
0x4
Use XY order for text enumeration


enumIGPDFWordFinderVersion

Group: Enumeration

Description:

WordFinder algorithm version.

Values:

IG_PDF_WF_LATEST_VERSION
0
The latest available version.
IG_PDF_WF_VERSION_2
2
Version used for Acrobat 3.x, 4.x.
IG_PDF_WF_VERSION_3
3
Available in Acrobat 5.0 without Accessibility enabled. Includes some improved word piecing algorithms.
IG_PDF_WF_VERSION_4
4
For Acrobat 5.0 with Accessibility enabled. Includes advanced word ordering algorithms in addition to improved word piecing algorithms.


enumIGPDFCodePages

Group: Enumeration

Description:

Code page character-mapping constants.

Values:

IG_PDF_CODEPAGE_WIN_EAST_EUROPEAN_ROMAN
1250
Windows code pages
IG_PDF_CODEPAGE_WIN_CYRILLIC
1251
Windows code pages
IG_PDF_CODEPAGE_WIN_GREEK
1253
Windows code pages
IG_PDF_CODEPAGE_WIN_TURKISH
1254
Windows code pages
IG_PDF_CODEPAGE_WIN_HEBREW
1255
Windows code pages
IG_PDF_CODEPAGE_WIN_ARABIC
1256
Windows code pages
IG_PDF_CODEPAGE_WIN_BALTIC
1257
Windows code pages
IG_PDF_CODEPAGE_MAC_CENTRAL_EUROPEAN
-9994
Macintosh pseudo code pages
IG_PDF_CODEPAGE_MAC_CROATIAN
-9993
Macintosh pseudo code pages
IG_PDF_CODEPAGE_MAC_ROMANIAN
-9992
Macintosh pseudo code pages
IG_PDF_CODEPAGE_MAC_CYRILLIC
-9991
Macintosh pseudo code pages
IG_PDF_CODEPAGE_MAC_UKRAINIAN
-9990
Macintosh pseudo code pages
IG_PDF_CODEPAGE_MAC_GREEK
-9989
Macintosh pseudo code pages
IG_PDF_CODEPAGE_MAC_TURKISH
-9988
Macintosh pseudo code pages
IG_PDF_CODEPAGE_MAC_HEBREW
-9987
Macintosh pseudo code pages
IG_PDF_CODEPAGE_MAC_ARABIC
-9986
Macintosh pseudo code pages


enumIGPDEPathElementType

Group: Enumeration

Description:

Constant values that describe path segment operators in PDE path elements.

Values:

IG_PDE_MOVE_TO
0
Designates m (moveto) operator, which moves the current point.
IG_PDE_LINE_TO
1
Designates l (lineto) operator, which appends a straight line segment from the current point.
IG_PDE_CURVE_TO
2
Designates c (curveto) operator, which appends a Bézier curve to the path.
IG_PDE_CURVE_TO_V
3
Designates v (curveto) operator, which appends a Bézier curve to the current path when the first control point coincides with initial point on the curve.
IG_PDE_CURVE_TO_Y
4
Designates y (curveto) operator, which appends a Bézier curve to the current path when the second control point coincides with final point on the curve.
IG_PDE_RECT
5
Designates re operator, which adds a rectangle to the current path.
IG_PDE_CLOSE_PATH
6
Designates h (closepath) operator, which closes the current subpath.


enumIGPDEPathOpFlags

Group: Enumeration

Description:

Flags for paint operators in a PDE path.

Values:

IG_PDE_INVISIBLE
0x00
Path is neither stroked nor filled, so it is invisible.
IG_PDE_STROKE
0x01
Stroke the path, as with the S (stroke) operator.
IG_PDE_FILL
0x02
Fills the path, using the nonzero winding number rule to determine the region to fill, as with the f (fill) operator.
IG_PDE_EO_FILL
0x04
Fills the path, using the even-odd rule to determine the region to fill, as with the f* (eofill) operator.


enumIGPDFBasicType

Group: Enumeration

Description:

Basic PDF objects.

Values:

IG_PDF_BASIC_NULL
0
Null object
IG_PDF_BASIC_INT
1
Integer object
IG_PDF_BASIC_FIXED
2
Fixed (real) object
IG_PDF_BASIC_BOOL
3
Boolean object
IG_PDF_BASIC_NAME
4
Name object
IG_PDF_BASIC_STRING
5
String object
IG_PDF_BASIC_DICT
6
Dictionary object
IG_PDF_BASIC_ARRAY
7
Array object
IG_PDF_BASIC_STREAM
8
Stream object


enumIGPDFPermsFlags

Group: Enumeration

Description:

Flags that describe permissions wanted and granted for a document. Not all permissions will be granted, if the document is protected or if the document is newer version than the application knows about.

Values:

IG_PDF_PERM_OPEN
0x01
The user is permitted to open and decrypt the document.
IG_PDF_PERM_SECURE
0x02
The user is permitted to change the document's security settings.
IG_PDF_PERM_PRINT
0x04
The user is permitted to print the document. Page Setup access is unaffected by this permission, since that affects Acrobat's preferences - not the document's. In the Document Security dialog, this corresponds to the Printing entry.
IG_PDF_PERM_EDIT
0x08
The user is permitted to edit the document more than adding or modifying text notes (see also IG_PDF_PERM_EDIT_NOTES). In the Document Security dialog, this corresponds to the Changing the Document entry.
IG_PDF_PERM_COPY
0x10
The user is permitted to copy information from the document to the clipboard. In the Document Security dialog, this corresponds to the Content Copying or Extraction entry.
IG_PDF_PERM_EDIT_NOTES
0x20
The user is permitted to add, modify, and delete text notes (see also IG_PDF_PERM_EDIT). In the Document Security dialog, this corresponds to the Authoring Comments and Form Fields entry.
IG_PDF_PERM_SAVE_AS
0x40
The user is permitted to perform a "Save As..." If both IG_PDF_PERM_EDIT and IG_PDF_PERM_EDIT_NOTES are disallowed, "Save" will be disabled but "Save As..." is enabled. The "Save As..." menu item is not necessarily disabled even if the user is not permitted to perform a "Save As...".
NOTE: Not settable by clients.
IG_PDF_PERM_EXT
0x80
IG_PDF_PRIV_PERM_FILL_AND_SIGN
0x100
Override other enumIGPDFPermsFlags bits. It allows user to fill-in or sign existing form or signature fields.
IG_PDF_PRIV_PERM_ACCESSIBLE
0x200
Override IG_PDF_PERM_COPY to enable Accessibility API. If a document is saved in Rev2 format (Acrobat 4.0 compatible), only IG_PDF_PERM_COPY bit is checked to determine Accessibility API state.
IG_PDF_PRIV_PERM_DOC_ASSEMBLY
0x400
Override various IG_PDF_PERM_EDIT bit and allow the following operations; page insert/delete/rotate and create bookmark and thumbnail.
IG_PDF_PRIV_PERM_HIGH_PRINT
0x800
This bit is supplement to IG_PDF_PERM_PRINT. If it is clear (disabled) only low quality printing (Print As Image) is allowed. Under UNIX platforms, where "Print As Image" doesn't exist, printing is disabled.
IG_PDF_PERM_OWNER
0x8000
The user is permitted to perform all operations, regardless of the permissions specified by the document. Unless this permission is set, the document's permissions will be reset to those in the document after a full save.
IG_PDF_PRIV_PERM_FORM_SUBMIT
0x10000
Should be set if user can submit forms outside of the browser. This bit is supplement to IG_PDF_PRIV_PERM_FILL_AND_SIGN.
IG_PDF_PRIV_PERM_FORM_SPAWN_TEMPL
0x20000
Should be set if user can spawn template pages. This bit will allow page template spawning even if IG_PDF_PERM_EDIT and IG_PDF_PERM_EDIT_NOTES are clear.
IG_PDF_PERM_ALL
0xFFFFFFFF
IG_PDF_PERM_SETTABLE
IG_PDF_PERM_PRINT + IG_PDF_PERM_EDIT + IG_PDF_PERM_COPY + IG_PDF_PERM_EDIT_NOTES
The OR of all operations that can be set by the user in the Standard Security dialog (IG_PDF_PERM_PRINT + IG_PDF_PERM_EDIT + IG_PDF_PERM_COPY + IG_PDF_PERM_EDIT_NOTES)
IG_PDF_PERM_USER
IG_PDF_PERM_ALL - IG_PDF_PERM_OPEN - IG_PDF_PERM_SECURE
All permissions.


enumIGPDFPreflightProfile

Group: Enumeration

Description:

This enumeration specifies the types of the supported preflight profiles supported by ImageGear.

Values:

IG_PDF_PREFLIGHT_PROFILE_PDFA_1A_2005
Profile for PDF/A-1a standard, revision 2005.
IG_PDF_PREFLIGHT_PROFILE_PDFA_1B_2005
Profile for PDF/A-1b, revision 2005.
IG_PDF_PREFLIGHT_PROFILE_PDFX_3_2003
Profile for PDF/X-3, revision 2003.


enumIGPDFPreflightReportCodes

Group: Enumeration

Description:

This enumeration defines PDF preflight error codes describing incompliance with the specified profile.

Values:

IG_PDF_PREFLIGHT_SUCCESS = 0
Document or Page is compliant with the specified preflight profile. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_DOCUMENT
Document is not compliant. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_PAGE
Page is not compliant. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_FILE_STRUCTURE
File structure is not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_FILE_HEADER
File header is not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_FILE_TRAILER
File trailer is not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_FILTERS
Document contains non-compliant filters. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_EMBEDDED_FILES
Embedded files are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_OPTIONAL_CONTENT
Optional content is not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_GRAPHICS
Graphics are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_COLOR_SPACES
Color spaces are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_ICC_COLOR_SPACES
Not compliant ICCBased color spaces. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_DEVICE_COLOR_SPACES
Not compliant uncalibrated color spaces. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_SPECIAL_COLOR_SPACES
Not compliant Separation/DeviceN color spaces. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_IMAGES
Images are not compliant. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_FORMS
Form XObjects are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_POSTSCRIPT
PostScript XObjects are not compliant. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_EXTGSTATE
Extended graphics state is not compliant. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_FONTS
Fonts are not compliant. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_COMPOSITE_FONTS
Composite fonts are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_CID_FONTS
CIDFonts are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_NOT_EMBEDDED_FONTS
Not embedded font programs are not compliant. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_FONTS_SUBSETS
Fonts subsets are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_CHAR_ENCODINGS
Character encodings are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_UCHAR_MAPS
Unicode character maps are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_TRANSPARENCY
Transparency is not compliant. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_ANNOTATIONS
Annotations are not compliant. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_MULT_ANNOTATIONS
Multimedia annotations are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_ANNOTATIONS_DICT
Annotation dictionaries are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_ACTIONS
Actions are not compliant. Reported by PDF/A and PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_TRIGGER_EVENTS
Trigger events are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_METADATA
Metadata is not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_DOCINFO
Mismatch between document information dictionary and XMP metadata. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_IDENTIFICATION_SCHEMA
PDF/A identification schema is missing or incompliant with namespace URI <http://www.aiim.org/pdfa/ns/id>. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_LOGICAL_STRUCTURE
Logical structure is not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_TAGGED_PDF
Document doesn't conform to the Tagged PDF conventions. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_ARTIFACTS
Artifacts are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_INTERACTIVE_FORMS
Interactive forms are not compliant. Reported by PDF/A compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_COLOR_DATA
Color data is not compliant. Reported by PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_CHAR_PRINTING_CONDITION
Characterized printing condition is not compliant. Reported by PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_FILE_SPEC
File specifications are not compliant. Reported by PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_TRAPPING
Trapping is not compliant. Reported by PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_FILE_IDENTIFICATION
PDF file identification is not compliant. Reported by PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_BOUNDING_BOXES
Bounding boxes are not compliant. Reported by PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_ENCRYPTION
Encryption is not compliant. Reported by PDF/X compliance verifier.
IG_PDF_PREFLIGHT_INCOMPLIANT_VIEW_PREFERENCES
Viewer preferences are not compliant. Reported by PDF/X compliance verifier.


enumIGPDFRevision

Group: Enumeration

Description:

Specifies /R revision value.

Values:

IG_PDF_REVISION_2
2
Support by Acrobat 3.0 and up.
IG_PDF_REVISION_3
3
Support by Acrobat 5.0 and up.
IG_PDF_REVISION_4
4
Support by Acrobat 6.0 and up.


enumIGPDFSecurityInfoFlags

Group: Enumeration

Description:

Flags used to specify various information about the Acrobat viewer's security and permissions.

Values:

IG_PDF_INFO_HAS_USER_PW
IG_PDF_PERM_OPEN
The document has a user password.
IG_PDF_INFO_HAS_OWNER_PW
IG_PDF_PERM_SECURE
The document has an owner password.
IG_PDF_INFO_CAN_PRINT
IG_PDF_PERM_PRINT
The document can be printed.
IG_PDF_INFO_CAN_EDIT
IG_PDF_PERM_EDIT
The document can be modified, for example by adding notes, links, or bookmarks.
IG_PDF_INFO_CAN_COPY
IG_PDF_PERM_COPY
The document text and graphics can be copied to the clipboard.


enumIGPDFStdSecurityMethod

Group: Enumeration

Description:

Specifies standard security algorithms.

Values:

IG_PDF_STD_SECURITY_METHOD_RC4_V2
2
RC4 algorithm for encryption.
IG_PDF_STD_SECURITY_METHOD_AES_V1
5
AES algorithm for encryption with a zero initialized iv.
IG_PDF_STD_SECURITY_METHOD_AES_V2
6
AES algorithm for encryption with a random initialized iv.


ImageGear_for_Windows_DLL-28-519.html

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


Recognition Component API Function Reference

In this Chapter you can get the detailed information about all ImageGear Recognition component functions and enumerations:

  • Recognition Component Functions Reference
  • Recognition Component Enumerations


Recognition Component Functions Reference

For the detailed description how to use ImageGear RecognitionComponent please see the section Using ImageGear Recognition Component in Using ImageGear Chapter.

Please see below the detailed description of Recognition component functions.


IG_REC_BAR_last_type_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_BAR_last_type_get(
        LPBAR_TYPE pBarCodeType
        );

Arguments:

pBarCodeType
Pointer to a BAR_TYPE variable to recieve the type of the last recognized bar code.

Description:

This function returns the type of last recognized one-dimensional bar code.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_BAR_type_name_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_BAR_type_name_get(
        BAR_TYPE Bartype,
        LPSTR *pBarname
        );

Arguments:

Bartype
The bar code type inquired.
pBarname
Address of a pointer to the name of the specified bar code.

Description:

This function returns the full name string of the specified bar code type.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_BAR_types_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_BAR_types_get(
        LPBAR_ENA pBarEna
        );

Arguments:

pBarEna
Pointer to receive the bar code type enable/disable array.

Description:

This function inquires the bar code types currently validated for recognition.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_BAR_types_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_BAR_types_set(
        LPBAR_ENA pBarEna
   );

Arguments:

pBarEna
Pointer to an array of BAR_ENA elements

Description:

This function validates the one-dimensional bar code type(s) for recognition.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_close

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_close(
   );

Description:

This function shuts down the Recognition component. You should call this function before exiting your application.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_correction_is_enabled_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_correction_is_enabled_get(
        LPBOOL pCorrection
        );

Arguments:

pCorrection
If True, correction is enabled.

Description:

This function inquires the Correction mode setting of the checking subsystem.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_correction_is_enabled_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_correction_is_enabled_set(
        BOOL bCorrection
        );

Arguments:

bCorrection
Set to True to enable correction.

Description:

This function enables or disables the Correction mode setting of the checking subsystem. If this mode is enabled, non-compliant words may be automatically corrected during recognition. The Correction mode is a page-level setting, i.e. when it is enabled, it will be applied to all zones of the page for which at least one of the three possible checking algorithms have been enabled.

The application should call this (and other checking-related functions) BEFORE calling the IG_REC_image_recognize function.

If bCorrection is FALSE, non-compliant words will be flagged, but no auto-correction will be done. If bCorrection is TRUE, all unchanged non-compliant words will be flagged, while some characters may also be changed by the checking subsystem.

Though the Correction mode is a page-level setting, it can be disabled for any particular zone by setting the CHK_CORRECTION_DISABLED flag of the zone's chk_control field.

You can control whether the correction feature should ignore or handle proper names. Enabling the zone-level CHK_CORRECT_PROPERNAMES flag allows words after the first in a sentence beginning with an uppercase letter to be checked, and if necessary flagged or changed. Disabling the flag, which is the default, means such words (typically but not always proper names) will not be checked or changed.

The correction feature will construct possible solutions from two sources only: any second or third character guesses for the characters in the word or character-pair solutions in the TEV.SZO file, designed to handle typical OCR-misrecognitions. These solutions are passed to the checking subsystem, which may result in a refused word being changed.

If this function is not called to specify the Correction mode, the default value of TRUE is applied, i.e. auto-correction is enabled.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_decomp_method_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_decomp_method_get(
        IMG_DECOMP *pAlgorithm
        );

Arguments:

pAlgorithm
Address of a variable to receive the current setting of Page parser algorithm.

Description:

This function inquires the current Page parser algorithm setting of the recognition engine.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_decomp_method_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_decomp_method_set(
        IMG_DECOMP Algorithm
        );

Arguments:

Algorithm
Page parser algorithm to be set.

Description:

This function is used to specify the Page parser algorithm setting. This setting is applied whenever the auto-zoning algorithm is activated.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_decomp_nongridded_table_detect_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_decomp_nongridded_table_detect_get(
        BOOL * bEnable
        );

Arguments:

bEnable
Address of a Boolean variable to get the current setting.

Description:

This function inquires whether the non-gridded table detection feature is enabled.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_decomp_nongridded_table_detect_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_decomp_nongridded_table_detect_set(
        BOOL bEnable
        );

Arguments:

bEnable
Non-gridded table detection setting to be set

Description:

This function set the Non-gridded table detection setting of the recognition engine.

Tables with visible gridlines (gridded tables) in an original page can usually be detected successfully by the auto-zoning function. In contrast, tables without visible cell separators in the original are harder to identify as tables, because they could equally as well be word lists or data arranged in columns. The Recognition component offers an algorithm for detecting such non-gridded tables more confidently. This feature of the recognition engine can only be used in conjunction with an auto-zoning step. The algorithm is based on the result of the character recognition.

When this feature is enabled, a special algorithm tries to find non-gridded table(s) on the image. This algorithm is based on the existing zone list of the image and also on the recognized characters, i.e. this algorithm is activated as one of the last steps in the character recognition.

Because of this, its effect might be visible only after a IG_REC_image_recognize () call.

The running of this algorithm is strongly controlled, since it may change the zone list belonging to the image. Accordingly, the non-gridded table detection feature may be allowed to run only if all the following conditions are met:

- the zone list was created through auto-zoning (IG_REC_zones_locate ()),

- there was no change in the zone list (no zone was inserted - IG_REC_zone_insert (), deleted - IG_REC_zone_delete (), etc.)

- none of the zones in zone list was updated by modifying the zone coordinates (IG_REC_zone_info_set ()).

It is recommended to disable the Non-gridded table detection algorithm when the DCM_FAST page parser algorithm was selected (see: IG_REC_decomp_method_set ()).

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_decomp_single_column_force_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_decomp_single_column_force_get(
        BOOL *pbForceSingle
        );

Arguments:

pbForceSingle
Address of a Boolean variable to hold the current Force Single Column mode setting.

Description:

This function inquires the current setting of the Force Single Column mode.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_decomp_single_column_force_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_decomp_single_column_force_set(
        BOOL bForceSingle
        );

Arguments:

bForceSingle
Force Single Column mode to be set (default is FALSE).

Description:

This function specifies the Force Single Column mode for the page-layout (auto-zoning) process. It prevents the decolumnization detecting columns and placing their contents one below the other. It is useful for conserving the columnar structure in tables.

It is highly recommended to switch this on sparingly, only for cases where the image has a single tabular structure and chances are that the automatic decomposition would fail to analyze the layout properly. Its effects are applied to whole pages.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_default_filling_method_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_default_filling_method_get(
        FILLINGMETHOD fmtype
        );

Arguments:

fmtype
Address of a variable to get the default filling method setting.

Description:

This function gets the default filling method setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_default_filling_method_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_default_filling_method_set(
        FILLINGMETHOD *pfmtype
        );

Arguments:

pfmtype
Specifies the default filling method.

Description:

This function specifies the default filling method for the page. The default filling method is applied to all zones on the page with the FM_DEFAULT value in their fm field.

This substitution of the filling method happens at the beginning of the IG_REC_image_recognize () calls.

Comments:

1) Zones with FM_DEFAULT are usually created either by the page-layout decomposition (auto-zoning) process OR by inserting or updating zones to the zone list with this value.

2) The case when FM_DEFAULT is specified as the parameter to this function represents a special situation (i.e. the default filling method is itself "default"). In this case the IG_REC_image_recognize() call won't be able to resolve the filling method for the zones on the page with FM_DEFAULT.

Instead, the automatic type detection algorithm of the recognition engine will be activated (see IG_REC_image_filling_method_detect ()) in order to determine the filling methods zone by zone.

3) If this function has not been called, the value FM_OMNIFONT will be applied for all zones with FM_DEFAULT in their fm field.

4.) There is no similar function for specifying a fixed value for the RM_AUTO recognition module. For each zone having the value RM_AUTO in its rm field, automatic recognition module selection occurs. When one filling method corresponds to only one recognition module, it will be set. When the filling method is supported by more than one recognition module, various tests are run to determine the best choice.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_default_filter_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_default_filter_get(
        CHR_FILTER *pGlfilter
        );

Arguments:

pGlfilter
Pointer to a variable to get the current Global filter setting.

Description:

This function inquires the current Global filter setting. The result is the binary OR-ed combination of one or more disjunct members of the CHR_FILTER enum.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_default_filter_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_default_filter_set(
        CHR_FILTER Glfilter
        );

Arguments:

Glfilter
Global Character Set filter to be applied.

Description:

This function specifies a Global filter, i.e. a Character Set filter to be applied globally, at page level. If this function is not called by the integrating application after the component initialization, the value FILTER_ALL is applied, i.e. the Language environment will not be filtered globally. The Global filter setting is applied to all zones with FILTER_DEFAULT in their filter field

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_deskew_mode_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_deskew_mode_get(
        IMG_DESKEW *pImgDeskew
        );

Arguments:

pImgDeskew
Pointer to a variable to get the current deskewing mode.

Description:

This function inquires the current Image deskewing mode setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_deskew_mode_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_deskew_mode_set(
        IMG_DESKEW ImgDeskew
        );

Arguments:

ImgDeskew
Selects deskewing mode.

Description:

This function specifies which Image deskewing mode will be used during preprocessing. Deskewing mode can be automatic, switched off or programmable.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_despeckle_mode_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_despeckle_mode_get(
        LPBOOL lpbMode
        );

Arguments:

lpbMode
Pointer to a variable to get the current setting.

Description:

This function inquires the current Image despeckle mode setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_despeckle_mode_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_despeckle_mode_set
        BOOL bMode
        );

Arguments:

bMode
Image despeckle mode to be set.

Description:

This function specifies the Image despeckle mode setting, i.e. whether the adaptive noise removal algorithm is to be activated during image pre-processing, auto-zoning or recognition. The noise removal algorithm runs only on bitonal images with a resolution of 280 dpi or higher.

This setting might influence the accuracy of the recognition.

Comments:

1.) When this setting is enabled, bitonal images with a resolution above 280 dpi automatically undergo an implicit secondary image conversion whenever the application calls a Recognition API function whose operation requires a bitonal or despeckled image, e.g. the IG_REC_zones_locate (), the IG_REC_image_preprocess or the IG_REC_image_recognize () functions. The resulting despeckled bitonal images are not available to the application.

2.) Grayscale or color images undergo their own implicit secondary image conversion whenever a bitonal image is required. This conversion results in cleaned bitonal images, so this setting is not applied to them.

3.) If this function is not called to specify the Image despeckle mode setting, by default this setting is enabled.

4.) Immediate despeckling of a bitonal image (regardless of its resolution) is available by calling IG_REC_image_despeckle (). The despeckled image replaces the original one and is available to the application.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_filterplus_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_filterplus_get(
        LPWORD pFilterPlus,
        size_t iSize
        );

Arguments:

pFilterPlus
Pointer to a buffer to get the current FilterPlus character setting in UNICODE.
iSize
Specifies the size of the buffer in bytes. It must be large enough to hold all the characters and the terminating double zero.

Description:

This function gets the FilterPlus characters setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_filterplus_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_filterplus_set(
        LPCWSTR pFilterPlus
        );

Arguments:

pFilterPlus
Pointer to a UNICODE string containing the FilterPlus characters to be set. (The string is terminated with a double zero.)

Description:

This function specifies a set of individual characters, the FilterPlus characters. The FilterPlus characters broaden or define the filtered set of characters globally or on a per-zone basis. To validate these FilterPlus characters, the zone's filter field should have the FILTER_PLUS value enabled, with or without other filter elements.

Comments:

1.) When characters to be added are contained in the ANSI (1252) Code Page, they can be defined in the pFilterPlus string with a wide-character-string literal, L"characters". Characters outside the ANSI (1252) Code Page can be converted one after the other with the IG_REC_util_convert_codepage_to_unicode () utility. It converts a single character code from the current single-byte Code Page value (IG_REC_output_codepage_set ()) to its UNICODE representation.

2.) To broaden the Character Set by the defined characters, the filter value needed in the zone structure is:

FILTER_ALL | FILTER_PLUS.

3.) To add characters to a filtered language environment, FILTER_PLUS should be binary ORed with the other filter values. The FilterPlus characters are added after the effect of the other filter elements. For example, to validate only letters and digits and the filter plus characters (with the punctuation and miscellaneous character categories disabled), the needed value is:

FILTER_ALPHA | FILTER_DIGIT | FILTER_PLUS

4.) To validate only the FilterPlus characters, FILTER_PLUS must be the only filter element in the zone structure field. This disables even the letters validated by the language selection.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_HNR_params_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_HNR_params_get(
        LPHNR_BOXDATA pCharbox,
        BOOL *pbSpaceincl
        );

Arguments:

pCharbox
Address of a structure to receive Character box parameters.
pbSpaceincl
Address of a variable for the space inclusion flag. When the space inclusion flag is TRUE, the recognition module calculates and may return SPACE characters between the recognized numeral characters.

Description:

This function inquires the current space inclusion flag and Character box parameter setting of the RM_HNR handprinted numeral recognition module.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_HNR_params_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_HNR_params_set(
        LPHNR_BOXDATA pCharbox,
        BOOL bSpaceincl
        );

Arguments:

pCharbox
Pointer to a Character box parameter structure.
bSpaceincl
Space inclusion flag. This flag controls whether or not the handprinted numeral recognition module should export spaces detected between characters.

Description:

This function sets character box parameters and the space inclusion flag for the RM_HNR handprinted numerals recognition module.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_HNR_style_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_HNR_style_get(
        HNR_STYLE *pdb
        );

Arguments:

pdb
Address of a variable for the writing style setting.

Description:

This function inquires the writing style setting of the RM_HNR handprinted numeral recognition module.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_HNR_style_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_HNR_style_set(
        HNR_STYLE db
        );

Arguments:

db
Writing style to be set.

Description:

This function sets the writing style setting for the RM_HNR handprinted numerals recognition module.

1.) For example, European style expects sevens (7) to be crossed whereas they are not crossed in the North-American style.

2.) If this function is not called, the default value of STYLE_EURO is applied.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_area_clear

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_area_clear(
        HIG_REC_IMAGE hImg,
        LPCRECT pRect
        );

Arguments:

hImg
Handle of the image to be modified.
pRect
Coordinates of the rectangular area to be cleared by setting all of its bits to zero (0). A NULL value means the entire image.

Description:

This function clears a rectangular area of the hImg image in the recognition engine's memory space.

With a bitonal image, setting all its bits to zero (0) results in an entirely white image. In other cases (but not for palette-color images), the resulting image is entirely black.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_delete

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_delete(
        HIG_REC_IMAGE hImg
   );

Arguments:

hImg
Handle of the recognition image to be removed.

Description:

This function removes the specified image from the recognition image management subsystem.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_deskew

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_deskew(
        HIG_REC_IMAGE hImg,
        int iSlope
        );

Arguments:

hImg
Handle of the image to be deskewed.
iSlope
Integer slope value for deskewing. The value given here is the number of pixels of vertical ascent on 1000 horizontal pixels. That is, the tangent of the deskew angle multiplied by 1000. The iSlope parameter must be in the range -577 to 577; that means the maximal slope value is 30 degrees.

Description:

This function performs immediate deskewing on the given image.

Comments:

1.) Recognition compoennt ignores a skew value if it is 0.5 degree or less.

2.) When this function is called, the coordinates of all defined zones in the zone list will be automatically recalculated.

3.) The image to be deskewed can be of any type (bitonal, grayscale or color).

4.) The function IG_REC_image_skew_detect () can detect the skew of a specified image, but only up to 15 degrees.

5.) This function ignores the current Image deskewing mode setting as set by a previous IG_REC_deskew_mode_set () call and also the value in IG_REC_slope_set (). Those settings relate only to deskewing performed during pre-processing initiated by IG_REC_image_preprocess (), which supports programmed or auto-deskewing.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_despeckle

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_despeckle(
        HIG_REC_IMAGE hImg
        );

Arguments:

hImg
Handle of the image to be despeckled.

Description:

This function performs an immediate adaptive noise removal on the bitonal image specified, irrespective of its resolution. An image despeckled by this function replaces the original one and is available for display and export.

Comment:

1.) If the image specified is not a bitonal one, the function sets ImageGear error with Value1 set to IMG_BITSPERPIXEL_ERR.

2.) This function is useful for typical images, which originally had a grayed or colored background which was not completely removed. It can be useful also for faxed pages or those with a spotted background.

3.) The algorithm will run whatever the resolution, however, it is optimized for images with at least 280 dpi resolution.

4.) As an alternative, the setting IG_REC_despeckle_mode_set () is available. While it is enabled, all bitonal images with a resolution of 280 dpi or higher are copied and despeckled, whenever a function is called which can benefit from a cleaner image, i.e pre-processing, auto-zoning or recognition. However, these despeckled images are not available to the application.

5.) This function is not applied to grayscale or color images, because any implicit conversion the recognition engine makes internally results in cleaned (but hidden) bitonal files.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_export

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_export(
        HIG_REC_IMAGE hRecImage
        LPHIGEAR				lphIGear,
   );

Arguments:

hRecImage
Handle of the recognition image
lphIGear
Pointer to a variable to receive the new HIGEAR image

Description:

This function exports an image from the recognition engine to ImageGear's HIGEAR.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_filling_method_detect

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_filling_method_detect(
        HIG_REC_IMAGE hImg,
        FILLINGMETHOD *pfm
        );

Arguments:

hImg
Handle of the image to be processed.
pfm
Pointer to a variable to get the detected type of filling method or NULL.

Description:

This function tries to determine the type of the text in the zones of a page globally (e.g. handprinted, machine printed or dot-matrix printed text and in special cases for bar codes). The function only looks into zones with the FM_DEFAULT value in their fm field. The detected filling method type is provided in the pfm variable.

Another use of this function is when it is called with NULL in its pfm parameter. In this case the function performs a zone by zone analysis (instead of suggesting a general filling type for the entire image), and if the algorithm can determine a type for a given zone, the function replaces the FM_DEFAULT value in the zone's fm field by the determined one.

Comments:

1.) This function is useful when there is an image with an unknown or uncertain type of text. (This quite often occurs when working with filled forms.) The types that can be detected with this function are FM_OMNIFONT, FM_DRAFTDOT9, FM_DRAFTDOT24, FM_HANDPRINT and FM_NO_OCR.

2.) If there are no zones with FM_DEFAULT type at all in the image, this function will not operate and it provides the value FM_DEFAULT in the pfm variable. When at least one zone with FM_DEFAULT exists, the application may want to call the IG_REC_default_filling_method_set () function with the detected FILLINGMETHOD as its parameter.

3.) If the pfm parameter had an input NULL value, the function tries to detect the filling type, zone by zone. If the detection is successful, the function DOES IMMEDIATELY CHANGE two fields of the given zone,

  • the FILLINGMETHOD field gets the detected value, and
  • the RECOGNITIONMODULE field becomes RM_AUTO.

If the detection was unsuccessful, both fields of the zone remain intact.

4.) When zone-by-zone detection is selected, the function detects even the FM_BARCODE type.

5.) The application should check whether the current recognition engine configuration contains the proper RECOGNITIONMODULE for recognizing the detected filling method.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_import

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_import(
        HIGEAR				hIGear,
        LPHIG_REC_IMAGE	*lphRecImage
   );

Arguments:

hIGear
Handle of a HIGEAR image to import
lphRecImage
Address of a variable to store the handle of the created recognition image.

Description:

This function imports an image into the recognition image management subsystem. If the image is grayscale, this function can import it as a grayscale image or can convert it to bitonal. Incoming color images can be loaded without any conversion or can be converted to grayscale or bitonal. The way this function handles these types of incoming images (bitonal, grayscale or color images) is called the primary image reduction mode. The reduction mode to be applied during the IG_REC_image_import () call can be set by the IG_REC_primary_reduction_mode_set () API function. Until that function is called, the default setting is CNV_NO, which results in images being loaded without any reduction.

This image loading function activates the PID_IMGINPUT process.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_info_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_info_get(
    HIG_REC_IMAGE hImg,
    LPIMG_INFO pImg
    );

Arguments:

hImg
Handle of the requested image.
pImg
Address of an IMG_INFO structure to get the image information.

Description:

This function gets information about any image in the recognition engine. This includes dimensions, resolution, image type (number of bits per pixel) of the specified image.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_invert

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_invert(
        HIG_REC_IMAGE hImg
        );

Arguments:

hImg
Handle of the image to be inverted.

Description:

This function performs immediate image inversion of the image. This function ignores the image inversion mode setting. The inverted image replaces the original one and is available to the recognition engine and the application.

Comments:

1.) For B/W images, the most usual inversion is from white-on-black to black-on-white, because the latter is needed for successful recognition.

2.) For grayscale images, each pixel value is transformed to its complementary value, E.g. for a 4-bit image, a value of 11 is inverted to 4.

3.) For color images, each color component is inverted to its complementary value

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_orient

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_orient(
        HIG_REC_IMAGE 		hImg,
        IMG_ROTATE 			Orientation
   );

Arguments:

hImg
Handle of the image to be oriented.
Orientation
Image orientation to be performed.

Description:

This function immediately rotates and/or mirrors the hImg image according to the Rotation parameter.

When this function is called, the coordinates of all defined zones in the zone list will be automatically recalculated, i.e. the zones are also rotated.

An alternative to this function is the IG_REC_image_preprocess () function with the required Image rotation mode.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_preprocess

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_preprocess(
        HIG_REC_IMAGE		 hImg
   );

Arguments:

hImg
The handle of the image to be pre-processed.

Description:

This function performs a series of image pre-processing steps by activating the PID_IMGPREPROCESS process. Performing these image pre-processing steps may improve the quality of the image from an OCR point of view, which may have an impact on the overall recognition accuracy for the page.

If pre-processing is desired, it should be done before performing auto-zoning and recognition. The available pre-processing steps are image inversion, deskewing, and rotation. The resulting modified images are available to the recognition engine and the application.

Whether and how it does these steps, depends on the settings found in:

IG_REC_deskew_mode_set ()

IG_REC_orientation_mode_set ()

The value needed for programmed deskewing (DSK_SET) can be detected by IG_REC_image_skew_detect () and defined in IG_REC_slope_set ().

Under certain circumstances, image despeckling is also performed internally. These depend on the settings found in:

IG_REC_despeckle_mode_set ()

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_recognition_data_delete

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_recognition_data_delete(
        HIG_REC_IMAGE hImg
        );

Arguments:

hImg
Image handle of the image.

Description:

This function destroys the recognition data (memory object) belonging to the hImg image.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_recognize

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_recognize(
        HIG_REC_IMAGE		 hImg,
        const LPSTR	 		lpszRDFileName,
        AT_BOOL		 bKeepGraphics
   );

Arguments:

hImg
Handle of the image to be recognized.
lpszRDFileName
Specifies what the recognition result will be. When this is
- a real filename signals that the recognition result will be stored in the specified recognition data file. Note that the full path has to be specified.
- NULL signals that the function will recognize a single-page document. In this case the recognition data file is hidden from the application and it is handled by the recognition engine itself.
- the period or full-stop string (".") signals that the recognition result will be kept in memory. The recognition engine will allocate memory and store the result in the recognition data.
bKeepGraphics
Set this parameter to TRUE if you are going to embed graphic areas in the final output document, or if you are going to save the output to some rich format, like Word DOC or HTML. Set to FALSE if you only need text output. Setting this parameter to FALSE will result in a faster recognition.

Description:

This function is used to perform the recognition task for an image loaded into the recognition engine's memory space.

The image to be processed is identified by the hImg parameter.

If the zone list of the hImg image is empty (i.e. there is no zone defined), the PID_DECOMPOSITION page-layout decomposition process is activated automatically in order to create a zone list for the image, before recognition.

The function utilizes the zone information to activate the appropriate recognition module on each zone. Each recognition module recognizes the image parts assigned to it in the zone list.

After all non-graphics zones on the page are recognized, the function collects the necessary information about the recognized characters into a homogenous structure, called the recognition result.

This function offers the services of the checking subsystem to either have suspect characters or words marked, or to allow auto-correction during the recognition process.

Depending on the pRDFileName parameter, this will be written to a file (recognition data file) or will be stored in memory (recognition data).

The IG_REC_image_recognize () function may activate one or more of the processes PID_RECOGNITION1, PID_RECOGNITION2, PID_RECOGNITION3 and PID_SPELLING.

Comments:

1.) If the hImg image is not bitonal (i.e. it is grayscale or color) an implicit secondary image conversion step is performed automatically to convert the image to a new hidden and despeckled bitonal image on which the recognizing function will operate. The parameters for this conversion can be specified through the function IG_REC_secondary_reduction_mode_set ().

2.) The application can register a callback function for progress indication (IG_REC_progress_CB_register ()). The recognition engine will then call the registered (PROGMON_CB) callback entry point to allow progress monitoring for the application.

3.) Since the recognition algorithm may use the services of the checking subsystem, the application should call the IG_REC_spelling_is_enabled_set (), IG_REC_correction_is_enabled_set (), and other checking related functions BEFORE calling the IG_REC_image_recognize() function. Checking of the recognized zone contents may consist of any combination of three facilities:

  • a supplied Language and/or Vertical dictionary,
  • a User dictionary containing literals and/or regular expressions,
  • a user-written checking callback function.

4.) When recognizing machine print text, this function may also apply the training data specified by the IG_REC_training_file_name_set () function.

5.) When pRDFileName contains a file name, a recognition data file is written. If the file does not exist, it is created, otherwise the newly recognized information is appended to the content of the existing file. This allows the program to append further pages to this file before converting it into the final output document, so the recognition of multi-page documents is conveniently supported.

6.) When the function is called with NULL, the recognition engine uses the default recognition data file, and this will always be deleted before new recognition starts. This is convenient for single-page documents, however not suitable for handling multi-page documents at all.

7.) Since the structure of the recognition data file is not documented, a separate IG_REC_output_convert_to_doc () function call is necessary to create the final output document with the required output format. Note that there are some Special Output Text Formats, which provide more information about the recognized character than the character code itself.

8.) When the function has been invoked with a period or full-stop string (".") in its pRDFileName parameter, the recognition engine allocates memory containing the recognized result. This memory object in the recognition engine's memory space - called the recognized data - is associated with the hImg image.

At any moment an image in the recognition engine's memory space will either have or won't have recognized data linked to it. The recognition data consist of 36-byte long LETTER structures for each recognized character. The application can retrieve a copy of the recognition data by calling the IG_REC_letters_get () function ("Letter output") or it can save it into a recognition data file with the IG_REC_RDFile_write () function.

Several IG_REC_RDFile_write () function calls (one for one each image in the recognition engine's memory space) should be followed by a single IG_REC_output_convert_to_doc () function call, which will create the final output document, as described in Comment #7.

When the integrator chooses "Letter output", the application gets the most detailed information about the recognized text. On the other hand, that does not mean losing access to the output formats supported by the recognition engine. The RecPutLetters function can be used to update the recognition data from the application. This allows the recognition data belonging to the hImg image to be replaced by slightly modified data.

9.) When memory output was selected ("."), the application can use the IG_REC_image_recognition_data_delete () function to delete the recognized data belonging to the hImg image.

10.) If a recognition module is not able to recognize an object (i.e. character, bar code or checkmark etc.), this object will be marked as rejected. It will become marked by a rejection symbol during conversion to the final output document. IG_REC_output_rejection_symbol_get () call can be used to specify the rejection symbol for this.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_reduce_to_bitional

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_reduce_to_bitonal(
        HIG_REC_IMAGE hImgIn,
        IMG_CONVERSION Conversion,
        int Brightness,
        int Threshold,
        IMG_RESENH resolenh,
        HIG_REC_IMAGE *phImgOut);

Arguments:

hImgIn
Handle of the image to be converted (either grayscale or color).
Conversion
Image conversion mode to be applied during the conversion of the hImgIn image.
Brightness
Brightness of the image (range is 0 to 100, where 0 means the darkest and 100 means the lightest resulting image). This parameter has effect only if the Conversion parameter is set to CNV_AUTO.
Threshold
Threshold value to be set. Its range should be between 0 and 255. This parameter has effect only if the Conversion parameter is set to CNV_SET.
resolenh
Resolution enhancement setting to be applied during the conversion (IMG_RESENH).
phImgOut
Handle of the bitonal image to be created.

Description:

This function creates another image from an existing one. This function performs a direct secondary image conversion step, converting a color or grayscale image (hImgIn) to a black-and-white (bitonal) one (hImgOut).

If the phImgOut image is no longer needed, it should be removed from the image management subsystem by invoking the IG_REC_image_delete () function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_image_skew_detect

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_image_skew_detect(
        HIG_REC_IMAGE hImg,
        int *pSlope,
        IMG_ROTATE* pImgRotate
        );

Arguments:

hImg
Handle of the image to be analyzed.
pSlope
Detects the orientation and the skew of the image specified.
Depending on the current setting of the Image deskewing and Image rotation modes, this function returns either with the detected image skew / orientation or with the current values of these settings.
pImgRotate
Pointer to a variable to get the orientation of the image.

Description:

This function detects the orientation and the skew of the image specified.

Depending on the current setting of the Image deskewing and Image rotation modes, this function returns either with the detected image skew / orientation or with the current values of these settings.

Comments:

1.) This function's behavior depends on the deskewing mode set in IG_REC_deskew_mode_set ():

  • DSK_AUTO: it detects the skew of the hImg image.
  • DSK_SET, it reports the current slope value setting
  • DSK_NO, it returns zero (0).

The current slope value is the one set by the last call to IG_REC_slope_set ().

2.) Detecting the skew of the image specified is effective with images in the range of one half to 15 degrees skew.

3.) The detected skew value can be placed in IG_REC_image_deskew () to immediately perform the specified amount of deskewing on a single image.

4.) The slope value can also be placed in IG_REC_slope_set (), which makes it available to IG_REC_deskew_mode_set () when DSK_SET is specified. Then all images will be deskewed by the given value whenever IG_REC_image_preprocess () is called.

5.) If the current Image rotation mode (set by a previous IG_REC_orientation_mode_set () call) is ROT_AUTO, this function provides the detected orientation of the hImg image, otherwise the current Image rotation mode setting is provided.

6.) When detecting the image rotation with Image rotation mode setting ROT_AUTO, one of the following values is returned: ROT_NO, ROT_RIGHT, ROT_DOWN, ROT_LEFT.

This is the value by which the image should be rotated to reach the orientation which the program considers correct. This value can be placed in the RecRotateImg function to explicitly perform the image rotation.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_initialize

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_initialize(
   );

Description:

This function initializes Recognition component. You should call it after attaching the Recognition component to ImageGear, and before calling any other function of the Recognition component.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_inversion_mode_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_inversion_mode_get(
        IMG_INVERT *lpMode
        );

Arguments:

lpMode
Pointer to a variable to get the current setting.

Description:

This function inquires the current image inversion mode setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_inversion_mode_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_inversion_mode_set(
        IMG_INVERT Mode
        );

Arguments:

Mode
Image inversion mode to be set.

Description:

This function specifies, which image inversion mode will be used during the forthcoming PID_IMGPREPROCESS processes. The Image inversion mode can be either automatic, switched on or switched off.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_is_char_enabled

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_is_char_enabled(
        WCHAR Unicode,
        CHR_ENA *pChrEnabled
        );

Arguments:

Unicode
Character to be checked, coded in UNICODE.
pChrEnabled
Pointer to a variable to get the flag.

Description:

This function inquires whether a given character is validated for the current page by its Language environment and any filtering, which may include FilterPlus characters for one or more zones on the pages.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_is_feature_licensed_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_is_feature_licensed_get(
        DWORD				dwFeature,
        LPAT_BOOL		 lpIsLicensed
);

Arguments:

dwFeature
Specifies the feature of the Recognition component
lpIsLicensed
Returns TRUE if the feature is licensed, and FALSE is the feature is not licensed.

Description:

This function inquires whether a particular feature of the Recognition component is licensed.

The enumIGRecFeatures enumeration lists the features that are licensed separately.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_languages_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_languages_get(
        LANG_ENA *pLanguages
        );

Arguments:

pLanguages
Pointer to an array to get the current language selection. The size of the array must be LANG_SIZE. Each element of this array represents a language (LANGUAGES enum).

Description:

This function retrieves the current language selection.

The Language environment is primarily determined by the language selection, optionally supplemented by the LanguagesPlus characters setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_languagesplus_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_languagesplus_get(
        LPCWSTR pLanguagesPlus,
        size_t iSize
        );

Arguments:

pLanguagesPlus
Pointer to a buffer to get the string of characters validated by the current LanguagesPlus setting in UNICODE.
iSize
Specifies the size of the buffer in bytes. It must be large enough to hold all the characters and the terminating double zero.

Description:

This function inquires the current contents of the LanguagesPlus characters setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_languagesplus_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_languagesplus_set(
        LPCWSTR pLanguagesPlus
        );

Arguments:

pLanguagesPlus
Pointer to a UNICODE string containing the LanguagesPlus characters to be set. (The string is terminated with a double zero.)

Description:

This function is used to specify some individual characters, the LanguagesPlus characters. These characters are added to the set of characters determined by the language selection. The resulting set of characters is called the Language environment.

Comments:

1.) This function is useful if a client believes the accented letters validated for a given language are insufficient, or for handling texts containing foreign words.

2.) When characters to be added are contained in the ANSI (1252) Code Page, the easiest way to define the pLanguagesPlus string is with a wide-character-string literal, L"characters". If any needed character falls outside the ANSI (1252) Code Page, you can convert these characters one after each other with the IG_REC_util_convert_codepage_to_unicode () utility function which converts a single character code from the current single-byte Code Page value (IG_REC_output_codepage_set ()) to its UNICODE representation. For this a simple word array can be used:

WORD aW[3];
    aW[0] = 0x00c9; //Cap E acute
    aW[1] = 0x00e9; //Lowercase E acute
    aW[2] = 0;

3.) When the application pre-defines the LanguagesPlus characters, the literal string method may be used with ANSI 1252 characters. However, if the application is going to offer the user a way of defining the LanguagesPlus characters, these should be in UNICODE.

4.) An unusual facility of the Language environment is when there is no language selection at all. This means that only the LanguagesPlus characters will be validated. This can be useful, for example with multiple-choice test answers, where only a few letters are valid (e.g. A, B, C, D).

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_languages_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_languages_set(
        LANG_ENA *pLanguages
        );

Arguments:

pLanguages
Address of a Boolean (LANG_ENA) array containing the enabled/disabled information for each recognition language available.

Description:

This function defines the main part of the Language environment of the Character Set. The available languages are represented by the LANGUAGES enum.

Comments:

1.) The Language environment is primarily determined by the language selection, optionally supplemented by the LanguagesPlus characters setting.

2.) The language selection is specified through a LANG_ENA type array, where a LANG_ENABLED value means that the language represented by this element is supported. This array must have LANG_SIZE number of elements.

3.) The recognition module selected for recognition of a zone may also impose restrictions, e.g. the RER recognition module cannot handle Greek characters.

4.) If this function is not called to specify the language(s) to be recognized, the default value, the English language, is applied.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_letters_delete

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_letters_delete(
        HIG_REC_IMAGE hImg,
        LPLETTER pLetter
        );

Arguments:

hImg
Handle of the image whose recognition data should be accessed.
pLetter
Address of a pointer variable to delete.

Description:

This function is used to delete the recognition data belonging to the hImg image of the recognition engine.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

Language selection for multi-lingual documents (e.g. English and German):

LANG_ENA pLang[LANG_SIZE];
for (int i=0; i<LANG_SIZE; i++) {
  pLang[i] = LANG_DISABLED;
}
pLang[LANG_ENG] = LANG_ENABLED;
pLang[LANG_GER] = LANG_ENABLED;
rc = IG_REC_languages_set(pLang);


IG_REC_letters_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_letters_get(
        HIG_REC_IMAGE hImg,
        LPLETTER *ppLetter,
        LPLONG pLength
        );

Arguments:

hImg
Handle of the image whose recognition data should be accessed.
ppLetter
Address of a pointer variable to get the address of the recognized characters.
pLength
Pointer to a variable to hold the number of recognized characters.

Description:

This function makes the recognition data belonging to the hImg image available to the application by creating a new memory object containing the recognized characters (a copy of the recognition data). This function can be called after a successful IG_REC_image_recognize call with a period or full-stop string (".") in its second parameter. The recognized characters are available as an array of LETTER structures.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_letters_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_letters_set(
        HIG_REC_IMAGE hImg,
        LPLETTER pLetter,
        LONG Length);

Arguments:

hImg
Handle of the image whose recognition data should be updated.
pLetter
Pointer to a variable containing the recognition data modified by the application.
Length
Number of characters (LETTER structures) in the modified recognized data.

Description:

This function is used to update the recognition data belonging to the hImg image of the recognition engine.

Comments:

1.) This call is useful when, for any reason, the integrating application is going to slightly modify the recognized result but still wants to generate a final output document in a particular format. In this case, the application should call IG_REC_letters_set () function first. After making some changes, the application can update the recognition data by calling this function. Then, it should call the IG_REC_RDFile_write () function in order to save the modified recognition result into a recognition data file. Finally, a IG_REC_output_convert_to_doc () call is necessary to create the final output document.

2.) When this function is called, the recognition engine reallocates the recognized data, if necessary.

3.) It is strongly recommended to make as few changes as possible while updating the recognition data (since e.g. some fields of the LETTER structure are used internally).

4.) Do not forget to free the memory area containing the recognized data with the IG_REC_letters_delete () function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_MOR_is_faxed_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_MOR_is_faxed_get(
        BOOL *pbFaxed
        );

Arguments:

pbFaxed
Address of a Boolean variable to hold the current Fax image mode setting.

Description:

This function inquires the current setting of the Fax image mode that applies to the RM_OMNIFONT_MOR recognition module only.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_MOR_is_faxed_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_MOR_is_faxed_set(
        BOOL bFaxed
        );

Arguments:

bFaxed
Fax image mode to be set.

Description:

This function is used to switch on or off the Fax image mode for the multi-lingual RM_OMNIFONT_MOR omnifont recognition module.

Turn this setting on (bFaxed=TRUE) if the image file to be loaded is a fax message transmitted in "Draft" mode with 200 x 100 resolution. Its use is not recommended for reading fax card image files transmitted in "Fine" mode (200 x 200 dpi resolution).

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_modules_info_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_modules_info_get(
        LPMODULEINFO *ppModules,
        size_t *pSize
        );

Arguments:

ppModules
Address of a pointer to the module information array.
pSize
Address of a variable holding the number of module information structures.

Description:

This function obtains information about the available modules of recognition engine.

Comments:

1.) You may want to invoke this function just after calling the IG_REC_initialize () function, to see if any module initialization failed AND/OR to get the module version numbers.

2.) During the initialization call, the recognition engine tries to initialize all its modules. There can be two reasons why a module won't be reported as available when the module is missing or not licensed on that particular computer.

  • When a module (or one of its important files) is missing, the initialization of that module will fail. E.g. if the DOT module's basic module DLL file, RNDOT.DLL is missing, neither this module nor its service (9-pin dot-matrix recognition) will be available.
  • When there is no license for a module, even if all the files of the module are present in the ScanSoft binary directory, the initialization of that module will fail.

3.) If there is a zone whose associated recognition module has not been initialized/loaded properly, the IG_REC_image_recognize () function will return with NO_TXT_WARN, signaling that there is at least one zone on the image whose content could not be recognized due to a non-functioning recognition module.

4.) The presence in the ScanSoft binary directory of the modules API, CHR, MGR, IMG and IMF is always required for the successful initialization of the system. The presence of any other module of the recognition engine is optional.

The integrating application may not require all the modules of the recognition engine, so any superfluous files can be simply deleted from the Binary directory.

5.) The application can control, which recognition module should be continuously kept in memory with the function IG_REC_module_is_resident_set ().

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_module_is_resident_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_module_is_resident_get(
        RECOGNITIONMODULE module,
        LPBOOL pbState
        );

Arguments:

module
Selected recognition module to be checked.
pbState
Pointer to a Boolean variable to get the information. The returned value of TRUE means that the selected recognition module is supposed to be kept in memory.

Description:

This function inquires whether the specified recognition module should be kept in memory.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_module_spec_params_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_module_spec_params_get(
        RECOGNITIONMODULE engine,
        LPSTR pParam,
        int bufflen);

Arguments:

engine
Selected recognition module to be checked.
pParam
Pointer to a buffer to which the accociated RM-spec file setting will be copied.
bufflen
Size of buffer in bytes. The buffer must be large enough to hold all the characters and a terminating zero.

Description:

This function can be used to establish whether the specified recognition module (RECOGNITIONMODULE) is associated with an external RM-specific parameter file (called RM-spec file).

If this call returns an empty string, it means that there is no RM-spec association for the specified recognition module.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_module_is_resident_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_module_is_resident_set(
        RECOGNITIONMODULE module,
        BOOL bState
        );

Arguments:

module
Recognition module whose memory residency setting is to be set.
bState
Recognition module resident value, TRUE signals that the Rmodule recognition module should be kept in memory.

Description:

This function specifies whether a recognition module should be kept in memory. This setting is applied to the recognition module defined in the function.

Comments:

1.) This function can speed up processing by prohibiting the recognition engine manager module from discarding the Rmodule recognition module from memory after each recognized image.

2.) If this function is not called, the MOR, MTX, PLUS and RER recognition modules are continuously kept in memory.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_module_spec_params_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_module_spec_params_set(
        RECOGNITIONMODULE module,
        LPCTSTR pParam);

Arguments:

module
Recognition module to be associated with a RM-spec file.
pParam
Name of the RM-spec file or NULL. Use NULL to disable a previously enabled RM-spec file.

Description:

This function can be used to associate a recognition module (RECOGNITIONMODULE) with an external RM-specific parameter file (called an RM-spec file).

When an RM is associated with an existing file, some RM-specific settings are taken from this ASCII text file and used instead of those from the recognition engine's default hard-coded parameters.

This way some settings of the RM originally not supported through the API become settable.

To disable the use of a previously enabled RM-spec file, call the function with NULL in place of the pRMSpecFile parameter.

Comments:

1.) At this moment, the recognition modules RM_MAT, RM_BAR2D and RM_RER support this feature. If a RM-spec file is associated with any other recognition module, the file content will be ignored.

2.) The distribution of the Recognition component contains three RM-spec files, the RM_BAR2D.ini, RM_MAT.ini and RM_RER.ini for the RM_BAR2D, RM_MAT and RM_RER modules, respectively. Use these files as baselines for your changes.

3.) Specifying an RM-spec file for the recognition module RM_AUTO causes an error.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_OMR_params_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_OMR_params_get(
        BOOL *pbFill,
        OMR_FRAME *pFrame,
        OMR_SENSE *pSensitivity
        );

Arguments:

pbFill
Address of a Boolean variable to get the current two/three-value output setting.
pFrame
Pointer to a variable to get the current frame detection method setting.
pSensitivity
Pointer to a variable to get the current mark sensitivity level setting.

Description:

This function inquires the current settings of the RM_OMR optical mark recognition module.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_OMR_params_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_OMR_params_set(
        BOOL bFill,
        OMR_FRAME frame,
        OMR_SENSE sensitivity);

Arguments:

bFill
This parameter determines whether the recognition output can take two or three values. (See comment #2.)
frame
Frame detection method to be set. This specifies whether the OMR zone borders will be visible or invisible in the images.
Possible values are: FRAME_AUTO, FRAME_NO and FRAME_YES.
sensitivity
Mark sensitivity level to be set (Default: SENSE_NORMAL).
Possible values are: SENSE_NORMAL, SENSE_LOW, SENSE_LOWER, SENSE_LOWEST.

Description:

This function specifies the settings of the RM_OMR optical mark recognition module. These are: the filled-in-error feature, the frame detection method and the mark sensitivity level.

Comments:

1.) If this function is not called, the default values are:

  • two-value output from recognition,
  • FRAME_AUTO detection mode, and
  • SENSE_NORMAL sensitivity setting.

2.) Use the bFill parameter to enable or disable a facility, which allows a respondent to correct boxes wrongly checked. If bFill is FALSE, only one of two values can be generated for each RM_OMR zone:

  • 0 = unfilled
  • 1 = filled

If the parameter bFill is TRUE, three values are possible for grouped zones:

  • 0 = unfilled,
  • 1 = filled,
  • 2 = filled-in-error.

To generate the value 2, a respondent should completely blacken or shade the whole zone area; it must be significantly darker and cover much more of the chechmark area than for the value "filled".

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_orientation_mode_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_orientation_mode_get(
        IMG_ROTATE*	 pOrientation
        );

Arguments:

pOrientation
Pointer to a variable to get the current Image orientation mode setting.

Description:

This function inquires the current Image rotation mode setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_orientation_mode_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_orientation_mode_set(
        IMG_ROTATE 			Orientation
        );

Arguments:

Orientation
Image orientation mode to be set.
Possible values are: ROT_AUTO, ROT_NO, ROT_RIGHT, ROT_DOWN, and ROT_LEFT.

Description:

This function specifies, which Image orientation mode will be used during forthcoming PID_IMGPREPROCESS processes. The Image orientation mode can be automatic, switched off or programmable.

At the moment, this function does not support mirroring of the image.

Comments:

1.) The auto-orientation feature (ROT_AUTO) works only on good quality, machine printed images. It does not work with 9-pin dot-matrix texts.

2.) When any of the ROT_FLIPPED, ROT_RIGHT_FLIPPED, ROT_DOWN_FLIPPED and ROT_LEFT_FLIPPED (IMG_ROTATE) enums is specified, the function returns with API_PARAMETER_ERR. These mirroring parameters are available only through the immediate image rotation function IG_REC_image_orient ().

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_codepage_check

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_codepage_check(
        LPCWSTR pMissingChrs,
        size_t buflen
        );

Arguments:

pMissingChrs
Pointer to a buffer to hold any missing characters returned by the function.
buflen
Specifies the size of the buffer in bytes. It must be large enough to hold all the characters and the terminating double zero.

Description:

This function checks whether the current Code Page setting contains all the characters of the current Language environment (characters needed for the language selection, plus any LanguagesPlus characters), and any characters listed as FilterPlus characters.

The buffer will contain any character (in UNICODE) validated for recognition, which can not be found in the current Code Page.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_codepage_first_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_codepage_first_get(
        LPSTR pCodePageName,
        size_t buflen
        );

Arguments:

pCodePageName
Pointer to a buffer for the name of the first available Code Page.
buflen
Specifies the size of the buffer in bytes.

Description:

This function together with IG_REC_output_codepage_next_get (), creates a listing of the available Code Pages.

Comments:

1.) The length of the each Code Page name never exceeds MAXCPNAMELEN characters (including the terminating zero).

2.) The Code Pages are either hard-coded in the recognition engine (Code Page 437, Roman 8, Greek-ELOT, Greek-MEMOTEK, all the supported Windows Code Pages and the 16-bit UNICODE and WordPerfect) or they are defined in Code Page Definition files, *.SET. The Recognition component is shipped with a Code Page Definition file, called RECOGN.SET.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_codepage_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_codepage_get(
        LPSTR pCodePageName,
        size_t buflen
        );

Arguments:

pCodePageName
Pointer to a buffer for the current setting.
buflen
Specifies the size of the buffer in bytes.

Description:

This function provides the current Code Page setting.

The length of any Code Page name never exceeds MAXCPNAMELEN characters (including the terminating zero).

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_codepage_info_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_codepage_info_get(
        LPCSTR pCodePageName,
        LPSTR pDesc,
        size_t size,
        LPOUTCODEPAGETYPE pCodePageType
        );

Arguments:

pCodePageName
Name of the Code Page requested. It should point to a MAXCPNAMELEN size character array.
pDesc
Pointer to a buffer to hold the Code Page descriptor information for the pCodePageName.
size
Specifies the size of the buffer pDesc, in bytes.The size MAXCPNAMELEN is recommended.
pCodePageType
Pointer to an OUTCODEPAGETYPE variable to hold basic Code Page category information.

Description:

This function provides information about the Code Page specified by pCodePageName: a descriptive string and the Code Page's category.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_codepage_next_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_codepage_next_get(
        LPSTR pCodePageName,
        size_t buflen
        );

Arguments:

pCodePageName
Pointer to a buffer for the name of the next available Code Page.
buflen
Specifies the size of the buffer in bytes.

Description:

This function (together with the IG_REC_output_codepage_first_get ()) creates a listing of the available Code Pages.

Comments:

1.) The length of any Code Page name never exceeds MAXCPNAMELEN characters (including the terminating zero).

2.) Repeated calls to this function get a sequence of the available Code Pages and generate a return code IGE_SUCCESS each time. When the function finds no further item to get, it returns with IGW_REC_SCANSOFT_WARNING error code and lValue1 of the error info set to CHR_NOMORE_WARN, signaling that the list is complete.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_codepage_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_codepage_set(
        LPCSTR pCodePageName
        );

Arguments:

pCodePageName
Name of the Code Page to be set. The available Code Pages can be learnt with the IG_REC_output_codepage_first_get () and IG_REC_output_codepage_next_get function-pair.

Description:

This function specifies the Code Page setting of the recognition engine.

Comments:

1.) The current Code Page setting is taken into account in three cases:

when converting a character to its UNICODE representation (IG_REC_util_convert_codepage_to_unicode ()),

when converting a character from its UNICODE representation to the current single-byte Code Page (IG_REC_util_convert_unicode_to_codepage ()),

when converting the recognition data to the final output document during the PID_WRITEFOUTDOC process.

2.) Recognition data is converted to the specified Code Page at export time, except when the specified output text format implies a 16-bit Code Page (e.g. "Word 97, 2000, XP"). This is used instead of any 8-bit Code Page specified.

3.) In order to keep the Code Page setting consistent for all the steps of the processing, it is a good practice to specify the necessary Code Page setting BEFORE calling any Code Page related function, and not to change it until the final output document has been generated.

4.) The selected Code Page should be able to express all characters validated for recognition (i.e. the Character Set for all the zones). Use IG_REC_output_codepage_check () to decide whether the current Code Page really fulfills this requirement.

5.) When the document contains characters missing from the current Code Page (those returned by the IG_REC_output_codepage_check () call), they are recognized, but in the final output document are replaced by a similarly shaped character or the missing symbol (see IG_REC_output_missing_symbol_set ()).

6.) If this function is not called to specify the Code Page setting, the default value, the "Windows ANSI" Code Page (code page 1252) is applied.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_convert_to_doc

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_convert_to_doc(
        const LPSTR				lpRDFileName,
        const LPSTR				lpDocFileName
   );

Arguments:

lpRDFileName
Name of the recognition data file.
If this parameter is NULL, the recognition engine will try to read the default recognition data file. Use the NULL parameter only when previously the IG_REC_image_recognize() function was also called with the parameter NULL and the application has processed a single-page document.
lpDocFileName
Name of the final output document file.
A filename or the period or full-stop string (".") has to be specified. The output format of this document should be specified by a previous IG_REC_output_format_set() function call. The codepage of this file (if applicable) should be specified by a previous IG_REC_output_codepage_set function call.

Description:

This function converts the cumulated recognition result stored in the recognition data file to the final output document, whose format has been specified by the previous IG_REC_output_format_set () and IG_REC_output_codepage_set () function calls.

The IG_REC_output_convert_to_doc function may activate the PID_READRDF, the PID_WRITEFOUTDOC and the PID_CONVERTIMG processes.

Comments:

1.) If instead of specifying the final output document, the integrating application invokes this function with a period or full-stop string ("."), the output is kept in memory. In this case the application can access the recognized output with IG_REC_output_text_get ().

2.) If a file with the specified pDocFileName name already exists, it is overwritten.

3.) This function creates the final output document with the default formatting property values. A preceding call to the IG_REC_output_param_set or to the IG_REC_output_level_set functions can be used to specify formatting properties for the conversion into the final output document.

4.) If you want the final output document to contain graphics for the graphics zones, the Retain Graphics feature should be enabled. For this, set either one of the FULLFORMAT or PARTFORMAT settings, or specify the RetainGraphics field directly and validate your settings with the IG_REC_output_param_set () call.

5.) When converting with the Retain Graphics feature, for each graphics zone a separate CONVERTIMG process is executed.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_format_first_get

Group: Recognition

Declaration:

    AT_ERRCOUNT ACCUAPI IG_REC_output_format_first_get(
        LPSTR					lpszFormatName,
        UINT					buflen
        );

Arguments:

lpszFormatName
Pointer to the name of the first available output text format.
buflen
Specifies the size of the buffer in bytes.

Description:

This function (together with the IG_REC_output_format_next_get () function) creates a listing of the available output text formats.

Comments:

1.) The length of any output text format name never exceeds 64 characters (including the terminating zero).

2.) The content of the resulting list depends on the configuration of the recognition engine, i.e. only output converters covered by the converter files found in the ScanSoft Binary directory during the initialization of the recognition engine are listed.

3.) The IG_REC_output_format_info_get () function provides more information about a particular output text format.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_format_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_format_get(
        LPSTR				lpszFormatName,
        UINT				buflen,
        )

Arguments:

lpszFormatName
Pointer to a buffer where the converter name will be stored.
buflen
Specifies the size of the buffer in bytes.

Description:

This function gets the name of the current output text format setting. The pFormatName will be the format of the final output documents created by IG_REC_output_convert_to_doc () calls.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_format_info_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_format_info_get(
        LPSTR					lpszFormatName,
        OUTPUTCONVERTERINFO *pInfo
        )

Arguments:

lpszFormatName
Name of the specified converter.
pInfo
Address of a converter info structure to which the requested information should be copied.

Description:

This function gets information about a specified output text format converter.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_format_next_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_format_next_get(
        LPSTR					lpszFormatName,
        UINT					buflen
        );

Arguments:

lpszFormatName
Pointer to the name of the next available output text format.
buflen
Specifies the size of the buffer in bytes.

Description:

This function, together with IG_REC_output_format_first_get(), creates a listing of the available output text formats.

Comments:

1.) The length of each output text format name never exceeds 64 characters (including the terminating zero).

2.) Repeated calls to this function get a sequence of the available output text formats and generate a return code IGE_SUCCESS each time. As soon as the function finds no further text format to get, it returns with IGW_REC_SCANSOFT_WARNING and error info's lValue1 field set to TMP_NOMORE_WARN, signaling that the list is complete.

3.) The content of the resulting list depends on the configuration of the recognition engine, i.e. only output converters covered by the converter files found in the ScanSoft Binary directory during the initialization of the recognition engine are listed.

4.) The IG_REC_output_format_info_get function provides more information about a particular output text converter.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_format_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_format_set(
        LPCSTR				lpszFormatName
        )

Arguments:

lpszFormatName
Name of the output text format to be set.

Description:

This function specifies the output text format for the final output document. This setting is applied during following IG_REC_output_convert_to_doc () calls.

Comments:

1.) The full set of the available output text formats is documented in the topic Output Text Format Lists.

2.) Only formats whose converter files are detected during the recognition engine's initialization are available. The two functions IG_REC_output_format_first_get () and IG_REC_output_format_next_get () can be used to obtain the available output text formats.

3.) The IG_REC_output_format_info_get () function can be used to get some information about any output text format converter.

4.) The integrating application should explicitly set the OUTPUTLEVEL to DROPFORMAT when the output text format pFormatName is one supporting ASCII output format. This is necessary - among other reasons - for correct table-zone handling. For more details see the topic Output Text Format List.

5.) If this function has not been called, the default value is used. This is the first available output converter, which is typically "Text - Standard".

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_level_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_level_get(
        OUTPUTLEVEL *poutLevel
        );

Arguments:

poutLevel
Pointer to a variable to get the current level of format retention setting.

Description:

This function gets the current level of format retention for the final output document.

This function returns with one of the four possible settings: FULLFORMAT, PARTFORMAT, or DROPFORMAT. When one is set, it changes a whole series of formatting property values. Each level defines a certain broad level of formatting. However, it is possible to change individual settings to fine-tune them to precise requirements. Therefore a later call to this IG_REC_output_level_get only tells, which of the three levels was used as a starting point - some of the precise settings may no longer be the ones usually associated with that level. E.g. the FULLFORMAT allows export of character attributes: bold, italic, underlined, but any of these can be disabled individually - so a returned result FULLFORMAT is no guarantee that bold text will be exported.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_level_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_level_set(
        OUTPUTLEVEL outLevel
        );

Arguments:

outLevel
Setting of format retention for output.

Description:

This function specifies the level of format retention for the final output document. It can simplify the specifying of output formatting details for the output document. If the application needs full control over the formatting details of the final document, it should use the IG_REC_output_param_set () function instead or in addition to this one.

Comments:

1.) This function should be called before calling the IG_REC_output_convert_to_doc () function. The output text format (e.g. "Word 97, 2000, XP") can be specified by the IG_REC_output_format_set () function.

2.) If an output text format (IG_REC_output_format_set()) is set which does not support certain formatting features included in the format retention setting, these are ignored in producing the final output document.

3.) The application can change individual properties after this function has been called using the IG_REC_output_param_set () function. In this case the changed values may no longer correspond to those reflecting the outLevel output level.

4.) The IG_REC_settings_set_default () function is used to re-initialize all recognition engine settings to their original, default values.

5.) If this function has not been called, the default level of format retention value, FULLFORMAT is applied.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_missing_symbol_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_missing_symbol_get(
        PWCHAR pMissSym
        );

Arguments:

pMissSym
Pointer to a variable to get the missing symbol setting.

Description:

This function inquires the current missing symbol setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_missing_symbol_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_missing_symbol_set(
        WCHAR MissSym
        );

Arguments:

MissSym
The missing symbol to be set.

Description:

This function specifies the code of the missing symbol. The missing symbol is a special character that replaces any character that was recognized by the recognition engine but could not be represented in the final output document, since the character does not exist in the current Code Page.

Comments:

1.) During the conversion to the final output document the IG_REC_output_convert_to_doc () function tries to find a replacement character with a similar shape for one not supported by the current Code Page. Only if this attempt is not successful, the missing symbol is placed in the final output document.

2.) If this function is not called, the default missing character, L"^" (the CIRCUMFLEX character) is applied.

3.) It is best to use a keyboard character for the missing symbol, so that it is supported by all Code Pages. If the defined missing symbol is itself missing from the selected Code Page, a character with a similar shape is set and an error is set with CHR_MISSINGEXPORT_ERR value.

4.) If the missing symbol to be set is contained within the ANSI 1252 Code Page, you can define it with a literal string, e.g.: L"#". If it is not, a UNICODE value should be given.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_param_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_param_get(
        OUTDOCUMENT *pODocu,
        OUTPARAGRAPH *pOPara,
        OUTCHARACTER *pOChar,
        OUTMARK *pOMark);

Arguments:

pODocu
Pointer to the OUTDOCUMENT structure.
pOPara
Pointer to the OUTPARAGRAPH structure.
pOChar
Pointer to the OUTCHARACTER structure.
pOMark
Pointer to the OUTMARK structure.

Description:

This function gets the currently valid set of formatting properties for the final output document.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_param_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_param_set(
        OUTDOCUMENT *pODocu,
        OUTPARAGRAPH *pOPara,
        OUTCHARACTER *pOChar,
        OUTMARK *pOMark
        );

Arguments:

pODocu
Pointer to a OUTDOCUMENT structure containing all the page level formatting properties.
pOPara
Pointer to a OUTPARAGRAPH structure containing all the paragraph level formatting properties.
pOChar
Pointer to a OUTCHARACTER structure containing all the character level formatting properties.
pOMark
Pointer to a OUTMARK structure containing all the requested output marking (coloring and separator marking) in the final output document.

Description:

This function validates formatting properties for the conversion into the final output document. It can be used in conjunction with the IG_REC_output_level_set () function or instead of it.

Comments:

1.) This function should be called before calling the IG_REC_output_convert_to_doc () function. The output text format (e.g. "Word 97, 2000, XP") can be specified by the IG_REC_output_format_set () function.

2.) An easy way of customizing formatting properties is as follows:

  • specify the OUTPUTLEVEL closest to your formatting requirements, using IG_REC_output_level_set ().
  • call IG_REC_output_param_get () to fill four structures with the formatting properties defined by the Format level specified in the previous call,
  • change any fields in these structure variables, as required,
  • call this IG_REC_output_param_set () function to validate your changes.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_rejection_symbol_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_rejection_symbol_get(
        PWCHAR pRejchar
        );

Arguments:

pRejchar
Pointer to a variable to get the rejection symbol setting.

Description:

This function inquires the current rejection symbol setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_rejection_symbol_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_rejection_symbol_set(
        WCHAR Rejchar
        );

Arguments:

Rejchar
The rejection symbol to be set.

Description:

This function specifies, which character is to be used as a symbol for the rejected characters (i.e. unrecognized by the recognition module used in the zone) in the final output document.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_text_delete

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_text_delete(
        );

Description:

This function frees the memory area containing a final output document.

This call is necessary whenever a previous IG_REC_output_text_get () function was called for accessing the final output document stored in the memory.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_output_text_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_output_text_get(
        LPBYTE *ppTxt,
        LPLONG pLength
        );

Arguments:

ppTxt
Address of a pointer variable to get the address of the final output document in memory.
pLength
Address of a variable for the length of the final output document.

Description:

This function makes the final output document stored in memory available to the application. This function can be used after invoking the IG_REC_output_convert_to_doc () function with a period or full-stop string (".") in its second parameter.

Comments:

After having processed (analyzed, saved, etc.) the final output document, the application should call the IG_REC_output_text_delete() function to free the memory area containing the recognized text.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_PDF_page_create

Group: Recognition

Declaration:

AT_ERRCOUNT IG_REC_PDF_page_create(
HIG_REC_IMAGE hImg,
HMIGEAR hPDFDoc,
LPAT_REC_PDF_PAGE_OPTIONS lpOptions);

Arguments:

hImg
Handle of the image.
hPDFDoc
Given PDF document.
lpOptions
Page options.

Description:

Creates a new page in the given PDF document and populates it with recognized text and image.

Pass NULL for lpOptions to use default options, which creates a PDF page containing the recognized image along with hidden text elements suitable for searching, highlighting, selection, copying and pasting, etc.

The lpOptions options are provided by the structure AT_REC_PDF_PAGE_OPTIONS:

  • VisibleText (Boolean) - Create visible text elements (otherwise, the text is hidden if an image is also created)
  • VisibleImage (Boolean) - Create the recognized image as an image covering the whole page
  • PreserveGraphics (Boolean) - Preserve graphics (only applicable if bVisibleText is true and bVisibleImage is false) (Reserved for future use.)
  • ForceProportional (Boolean) - Force all text to use proportional fonts (no monospaced font detection)
  • SpecifyImageCompression (Boolean)- If True the image compression should be set based on ImageCompression member of the structure, if False the image compression should be set based on bit depth.
  • ImageCompression (enumIGCompressions) - Compression to use for image (only used if SpecifyImageCompression is True).

If specifying options, initialize the options structure to all zeroes. Then set the values you want to change.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_PDF_page_populate

Group: Recognition

Declaration:

AT_ERRCOUNT IG_REC_PDF_page_populate(
HIG_REC_IMAGE hImg,
HMIGEAR hPDFDoc,
HIG_PDF_PAGE hPDFPage,
LPAT_REC_PDF_PAGE_OPTIONS lpOptions
);

Arguments:

hImg
Handle of the image.
hPDFDoc
PDF document containing the page to populate.
hPDFPage
PDF page to populate.
lpOptions
Page options.

Description:

Populates an existing PDF page in a PDF document with recognized text and/or image. The content of the existing PDF page is preserved and supplemented.

Pass NULL for lpOptions to use default options, which creates a PDF page containing the recognized image along with hidden text elements suitable for searching, highlighting, selection, copying and pasting, etc.

The lpOptions options are provided by the structure AT_REC_PDF_PAGE_OPTIONS:

  • VisibleText (Boolean) - Create visible text elements (otherwise, the text is hidden if an image is also created)
  • VisibleImage (Boolean) - Create the recognized image as an image covering the whole page
  • PreserveGraphics (Boolean) - Preserve graphics (only applicable if bVisibleText is true and bVisibleImage is false) (Reserved for future use.)
  • ForceProportional (Boolean) - Force all text to use proportional fonts (no monospaced font detection)
  • SpecifyImageCompression (Boolean)- If True the image compression should be set based on ImageCompression member of the structure, if False the image compression should be set based on bit depth.
  • ImageCompression (enumIGCompressions) - Compression to use for image (only used if SpecifyImageCompression is True).

If specifying options, initialize the options structure to all zeroes. Then set the values you want to change.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_primary_reduction_mode_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_primary_reduction_mode_get(
        IMG_CONVERSION *pConversion
        );

Arguments:

pConversion
Address of a variable to receive the current setting of the primary image conversion mode.

Description:

This function inquires the current primary image conversion mode setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_primary_reduction_mode_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_primary_reduction_mode_set
        IMG_CONVERSION Conversion
        );

Arguments:

Conversion
Primary image conversion mode to be set.

Description:

This function specifies, which Image reduction mode will be used during the primary image conversion step. While loading an image to the recognition engine's memory space (PID_IMGINPUT process), an image conversion is performed according to the current image conversion mode setting.

The setting specified here will influence what kind of hImg image will be created in the recognition engine's memory, i.e. whether it will be bitonal grayscale or color.

Comments:

The following table demonstrates what kind of HIMG image will created in the recognition engine as the result of the image loading process.

Primary image conversion mode
Image source is bitonal
Image source is Grayscale
Image source is Color
CNV_AUTO
bitonal
bitonal
bitonal
CNV_SET
bitonal
bitonal
bitonal
CNV_NO
bitonal
Grayscale
Color
CNV_GLOBAL
bitonal
bitonal
bitonal
CNV_GRAY
bitonal
Grayscale
Grayscale

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_progress_CB_register

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_progress_CB_register(
        PROGMON_CB *pCallBack
        );

Arguments:

pCallBack
Address of the callback entry point in the application.

Description:

This function registers a callback address for the PROGMON_CB progress monitoring function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_RDFile_write

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_RDFile_write(
        HIG_REC_IMAGE hImg,
        LPCSTR pRDFileName
        );

Arguments:

hImg
Image handle of the image having the recognized data.
pRDFileName
Name of the recognition data file. The program can concatenate further pages to this file if you are recognizing a multi-page document, e.g. an entire chapter of a book.

Description:

This function saves the recognized data associated with the hImg image (and stored in the engine's memory) to a recognition data file.

After using this call to get all recognition needed for a final output document, the IG_REC_output_convert_to_doc() function can be used to convert the recognition data file to the final output document with the required output format specified by the IG_REC_output_format_set() function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_reduction_brightness_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_reduction_brightness_get(
        int *pBrightness
        );

Arguments:

pBrightness
Address of the variable to get the current brightness setting.

Description:

This function retrieves the current value of the threshold fine tuning setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_reduction_brightness_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_reduction_brightness_set(
        int Brightness
        );

Arguments:

Brightness
Brightness control of the automatic image conversion algorithm. The value range is between zero (0) and 100. A value of 0 tunes the conversion to give a lighter image, while a value of 100 results in a darker image. The default value is 50.

Description:

This function fine tunes the threshold calculation in the automatic adaptive image conversion mode (i.e. when CNV_AUTO has been specified). This influences the brightness/darkness of the resulting bitonal image.

This function influences both the primary and the secondary image conversions. It has an effect only when the CNV_AUTO image conversion mode has been specified.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_reduction_threshold_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_reduction_threshold_get(
        int *pThreshold
        );

Arguments:

pThreshold
Address of the variable that will hold the current threshold value.

Description:

This function inquires the current value of the image conversion threshold setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_reduction_threshold_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_reduction_threshold_set(
        int Threshold
        );

Arguments:

Threshold
The image conversion threshold value to be set. Its range is between zero (0) and 255, default: 128.

Description:

This function specifies the threshold parameter of an image conversion to a bitonal image. This parameter has an effect only when the CNV_SET image conversion mode has been set.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_res_enhancement_mode_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_res_enhancement_mode_get(
        IMG_RESENH *lpRes
        );

Arguments:

lpRes
Pointer to a variable to get the current setting.

Description:

This function inquires the current Image resolution enhancement mode setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_res_enhancement_mode_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_res_enhancement_mode_set
        IMG_RESENH res
        );

Arguments:

bMode
Image despeckle mode to be set.

Description:

This function specifies the Image resolution enhancement mode. This setting is applied only to non-bitonal images stored in the recognition engine's memory space. The value specifies whether the image resolution enhancement is to be activated during the secondary image conversion, i.e. during image pre-processing, auto-zoning or recognition. The resolution enhancement algorithm results in a bitonal image whose resolution is doubled - compared to the original image.

This setting might influence the accuracy of the recognition.

Comments:

1.) When the Image resolution enhancement value RE_YES (IMG_RESENH) is set, all non-bitonal images undergoing a implicit secondary image conversion to bitonal also have their resolution doubled, regardless of their original resolution. This is done on the basis of information taken from the extra pixel depth in the grayscale and color images. These secondary image conversions occur whenever the application calls a RECapi API function whose operation requires a bitonal image, e.g. the IG_REC_zones_locate (), the IG_REC_image_preprocess () or the IG_REC_image_recognize () functions.

2.) With the RE_AUTO setting, only images with a resolution of 150 or less are resolution-enhanced during secondary image conversion.

3.) If this function is not called to specify the Image resolution enhancement mode setting, by default RE_AUTO is applied.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_secondary_reduction_mode_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_secondary_reduction_mode_get(
        LPIMG_CONVERSION pBWConversion
        );

Arguments:

pBWConversion
Address of a variable to receive the current secondary image conversion mode setting.

Description:

This function inquires the current secondary image conversion mode setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_secondary_reduction_mode_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_secondary_reduction_mode_set(
        IMG_CONVERSION BWConversion
        );

Arguments:

BWConversion
Secondary image conversion mode to be set.

Description:

This function specifies, which Secondary image conversion mode will be used during an implicit Secondary image conversion step. This algorithm is performed automatically when the application calls an API function (for example auto-zoning, recognition, deskew detection) whose operation requires a bitonal image, but the requested image is not a bitonal one. This setting influences how a non-bitonal hImg image, stored in the recognition engine, will be converted to a bitonal one.

This setting might influence the accuracy of the recognition.

Comments:

1.) Both the IG_REC_primary_reduction_mode_set () and this IG_REC_secondary_reduction_mode_set() functions specify Image conversion modes.

2.) TheIG_REC_primary_reduction_mode_set() function specifies the mode to be applied during the PID_IMGINPUT process (primary image conversion). The result of this process is a hImg image under the memory space of the recognition engine. Depending on the original image source AND the Primary image conversion mode setting (specified with IG_REC_primary_reduction_mode_set()), the created image will be a bitonal, a grayscale or color one.

3.) On the other hand, a Secondary image conversion with BWConversion mode might be performed on existing hImg images. In this case a second, bitonal image will be created. This step is called either directly (from within the IG_REC_image_reduce_to_bitional () function) or implicitly, as described above.

E.g. when the IG_REC_image_recognize () function has been called for a non-bitonal image, an implicit secondary image conversion will be performed automatically. The IG_REC_image_recognize() function implicitly may include the conversion of the image, if necessary. A previous IG_REC_secondary_reduction_mode_set() call allows you to specify how this implicit conversion will be performed.

4.) When the Secondary image conversion is called implicitly, the resulting bitonal image won't be accessible to the integrating application, so the application doesn't have to take care of freeing it. If the current resolution enhancement mode is RE_YES, or it is RE_AUTO with the image resolution less than 150 dpi, resolution enhancement is applied to the image. This means that the resolution of the created bitonal image will be double of the resolution of the original one.

If the image is a bitonal one, the implicit secondary image conversion may create a despeckled image using an adaptive noise removal algorithm. Though this image is not accessible to the application, in fact internally this despeckled image is passed for the recognition or auto-zoning functions.

5.) If this function is not called, the default value of CNV_AUTO is applied.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_settings_load

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_settings_load(
        const LPSTR pFileName
        );

Arguments:

pFileName
Name of the settings file to be loaded.

Description:

This function loads settings from an recognition engine Settings file previously created with the IG_REC_settings_save () function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_settings_save

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_settings_save(
        const LPSTR pFileName
        );

Arguments:

pFileName
Name of the settings file to be written into.

Description:

This function saves all the current settings of the recognition engine to a file, the recognition engine Settings file, for storing or studying purposes. An recognition engine Settings file can be loaded any time with the IG_REC_settings_load () function.

Though the recognition engine Settings file is an ASCII text file, DO NOT MODIFY IT since once it becomes corrupted it will not be loaded at all and there is no way to learn which line has caused the problem.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_settings_set_default

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_settings_set_default();

Description:

This function re-initializes all recognition engine settings to their original, default values.

Comments:

The following settings are affected and take the following defaults:

  • Images:
    • Primary image reduction mode = CNV_NO;
    • Secondary image reduction mode = CNV_AUTO;
    • Image brightness (used in conjunction with CNV_AUTO) = 50 %;
    • Threshold parameter for image conversion to bitonal = 128;
    • (applied when CNV_SET is set)
    • Image resolution enhancement mode = RE_AUTO;
    • Image inversion mode = INV_AUTO;
    • Image deskewing mode = DSK_AUTO;
    • Slope value for image deskewing (applied when DSK_SET is set) = 0;
    • Image rotation (and mirroring) mode = ROT_AUTO;
    • Image stretching mode = STRETCH_DELETE;
    • Image despeckling mode = TRUE;
  • Global settings:
    • Process timeout = 180 sec (3 minutes) (Applied to: image preprocessing, image parse and recognition.)
  • Page-layout decomposition (auto-zoning) module:
    • Page parser algorithm = DCM_AUTO;
    • Force Single Column mode = FALSE;
    • Non-gridded tabel detection = TRUE;
    • Character Set filter for zones = FILTER_DEFAULT (FILTER_DEFAULT will be resolved by FILTER_ALL; (i.e. no filtering will be applied)
    • Filling method associated with a zone = FM_DEFAULT; (FM_DEFAULT will be resolved by FM_OMNIFONT
    • Recognition module associated with a zone = RM_AUTO; (With FM_OMNIFONT, RM_AUTO will be resolved by RM_OMNIFONT_PLUS3W)
  • Recognition language, Character Set , Code Page:
    • Language selection for recognition = LANG_ENG;
    • LanguagesPlus characters = <empty set>;
    • FilterPlus characters = L".,";
    • Rejection symbol = L"~";
    • Code Page = "Windows ANSI";
    • Missing symbol = L"^";
  • SPL checking module:
    • Checking subsystem enabled = TRUE;
    • Automatic spell correction enabled = TRUE;
    • Spelling language= LANG_AUTO;
    • User dictionary = <empty string>;
  • M/TEXT omnifont recognition module:
    • Trade-off (global setting) = TO_ACCURATE;
  • MOR multi-lingual omnifont recognition module:
    • Trade-off (global setting) = TO_ACCURATE;
    • Fax image mode = FALSE;
  • BAR bar code recognition module:
    • Bar code types enabled for recognition = EAN, ITF, Code 39, Code 128 and Codabar.
  • HNR handprinted numeral recognition module:
    • Trade-off (global setting) = TO_ACCURATE;
    • Character box height = 0; (determined automatically)
    • Character box width = 0; (determined automatically)
    • Character box space = 0; (determined automatically)
    • Space inclusion flag = TRUE;
    • Writing style = STYLE_EURO;
  • RER handprint recognition module:
    • Trade-off (global setting) = TO_ACCURATE;
  • OMR checkmark recognition module:
    • Three-valued (Fill) = FALSE;
    • Frame detection method = FRAME_AUTO;
    • Mark sensitivity = SENSE_NORMAL;
  • Export to the final output document:
    • Output format = the first output text format available in the recognition engine configuration;
    • Format retention for the final output document = FULLFORMAT;

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_slope_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_slope_get(
        int *pSlope
        );

Arguments:

pSlope
Pointer to a variable to get current slope value.

Description:

This function returns the current slope value setting which was set by a previous IG_REC_slope_set () function call.

To detect the skew of an image containing machine printed text, call the IG_REC_image_skew_detect () function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_slope_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_slope_set(
        int iSlope
        );

Arguments:

iSlope
Slope value for deskewing. The value given here is the number of pixels of vertical ascent on 1000 horizontal pixels. That is, the tangent of the deskew angle multiplied by 1000. Its range should be between -577 and 577; that means the max. slope value is 30 degrees.

Description:

This function specifies the value of the skew (slope value). This value is used during the PID_IMGPREPROCESS process when the Image deskewing mode is set to DSK_SET.

Use IG_REC_image_skew_detect () to detect the skew of an image containing machine printed text.

A value of half a degree or less will be ignored.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_spelling_is_enabled_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_spelling_is_enabled_get(
        BOOL *pChksubsystem
        );

Arguments:

pChksubsystem
Address of a flag to get status: TRUE enabled, FALSE disabled.

Description:

This function inquires whether the checking subsystem is enabled or disabled.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_spelling_is_enabled_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_spelling_is_enabled_set(
        BOOL bChksubsystem
        );

Arguments:

bChksubsystem
Flag that indicates whether the checking subsystem is enabled or disabled.

Description:

This function enables or disables the checking subsystem. Its running may improve the overall throughput by marking suspicious words and characters, making it easier to correct them. It can also be set to improve accuracy, by auto-correcting suspicious recognized words.

Comments:

1.) The functionality of the checking subsystem consists of three parts:

  • Spell checking (use of the Language dictionary),
  • UD-checking (use of the User dictionary),
  • User-written checking (use of user-written callback functions).

Once the checking subsystem has been enabled, it can still be configured to use any combination of these three possible checkings.

The language for spell checking (the Spelling language) is specified with IG_REC_spelling_language_set ().

The User dictionary is specified with IG_REC_UD_set (). During UD-checking, the recognized result of a zone is checked against the UDitems belonging to the zone's chk_sect section in the User dictionary.

For user-written checking of the zone contents, CHECKWORD_CB callback functions should be written giving a different type of control to the programmer to influence the decision of the checking.

2.) Depending on the current setting of the Correction mode, the checking subsystem will either only mark non-compliant words or can be permitted to auto-correct them. The Correction mode can be specified by the IG_REC_correction_is_enabled_set () function.

3.) By default the checking subsystem is enabled.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_spelling_language_first_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_spelling_language_first_get(
        LANGUAGES *pLang
        );

Arguments:

pLang
Address of a variable to get the first language.

Description:

This function (together with the IG_REC_spelling_language_next_get () function) creates a listing of the available Spelling languages. This function returns with the LANGUAGES language identifier of the first Spelling language available for the current recognition engine configuration.

Comments:

1.) The content of the resulting list depends on the configuration of the recognition engine, i.e. the presence of the Language dictionary files in the ScanSoft Binary directory. For the list of the supported languages, see the specification (Language Dictionary List topic)

2.) When there is no available Spelling language (since e.g. the Binary directory does not contain any language dictionary file at all), the function returns with IGW_REC_SCANSOFT_WARNING / SPL_NOMORE_WARN.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_spelling_language_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_spelling_language_get(
        LANGUAGES* pLang
        );

Arguments:

pLang
Address of a variable to get the current Spelling language setting.

Description:

This function inquires the current Spelling language setting of the checking subsystem.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_spelling_language_next_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_spelling_language_next_get(
        LANGUAGES *pLang
        );

Arguments:

pLang
Address of a variable to get the next spelling language.

Description:

This function , together with IG_REC_spelling_language_first_get (), creates a listing of the available Spelling languages.

Comments:

1.) The resulting listing depends on the configuration of the recognition engine (the set of Language dictionary files in the ScanSoft Binary directory).

2.) Repeated calls to this function get a sequence of the available Spelling languages and return a return code IGE_SUCCESS each time. As soon as the function finds no further language to get, it returns with IGW_REC_SCANSOFT_WARNING / SPL_NOMORE_WARN, signaling that the list is complete.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_spelling_language_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_spelling_language_set(
        LANGUAGES			Lang
        );

Arguments:

Lang
Identifier of the Spelling language to be set.

Description:

This function specifies the Spelling language for the language checking of the checking subsystem.

Comments:

1.) Spelling language is a page-level setting. Once spell checking is specified, it is applied to all zones on the page, except in zones with their CHK_LANGDICT_PROHIBIT flag set. This is useful for excluding zones containing mostly proper names or text in a different language.

2.) When the SpellLang parameter is LANG_NO, or if it specifies a language, for which there is no language dictionary available, the language checking won't be activated during recognition.

3.) When the SpellLang parameter is set to LANG_AUTO, the language checking will be performed according to the actual recognition language selection (IG_REC_languages_set()) as follows:

  • If the recognition language selection is empty, there won't be language checking.
  • If one language has been set for the Language environment of the Character Set, that language will be automatically selected for language checking assuming that the appropriate Language dictionary is available.
  • If two or more languages are selected for recognition, language checking will be done for all selected languages, for which a Language dictionary is available.

4.) The available spelling languages can be enumerated through the IG_REC_spelling_language_first_get () and IG_REC_spelling_language_next_get () functions. They will enumerate those dictionaries present in the ScanSoft Binary directory.

5.) The application should call this (and other checking-related functions) BEFORE calling the IG_REC_image_recognize () function.

6.) If this function is not called to specify the Spelling language, the default value of LANG_AUTO is applied.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_statistics_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_statistics_get(
        LPSTATISTIC pStat
        );

Arguments:

pStat
Address of a structure to hold the statistical information.

Description:

This function returns information about the accuracy and timing data of the last processed image.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_timeout_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_timeout_get(
        LPDWORD pTimeOut
        );

Arguments:

pTimeOut
Pointer to a variable to get the current module timeout settings, in milliseconds or INFINITE.

Description:

This function inquires the current recognition engine module timeout setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_timeout_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_timeout_set(
        DWORD TimeOut
        );

Arguments:

TimeOut
timeout value to be set, in milliseconds or INFINITE. Specifying the INFINITE timeout value disables the watch-dog mechanism in the recognition engine.

Description:

This function specifies the global timeout setting. This setting is used by the recognition engine to implement a watch-dog feature for avoiding rare but annoying dead-lock situations (infinite loops).

At the moment this feature is applied to the following internal processes of the recognition engine:

  • image pre-processing (PID_IMGPREPROCESS process),
  • page-layout decomposition, also known as page parsing or auto-zoning (PID_DECOMPOSITION process), and
  • recognition (PID_RECOGNITION1, PID_RECOGNITION2 and PID_RECOGNITION3 processes).

Comments:

1.) The value specified here allows a module to process an image for no longer than the time specified. When the TimeOut value is reached, the recognition engine terminates the running of the appropriate module and resets it. The calling function returns with the API_TIMEOUT_ERR return code to the integrating application signaling that the processing of the image could not be successfully completed.

2.) Though disabling the timeout feature (by calling this function with the INFINITE parameter) may speed up the component's initialization, it is recommended to enable the watch-dog mechanism.

3.) If this function is not called to specify the module timeout setting, the default value of this setting, 180000 milliseconds (3 minutes) is applied, i.e. no internal process will be allowed to continue for more than three minutes.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_training_file_name_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_training_file_name_get(
        LPSTR pFileName,
        size_t iSize
        );

Arguments:

pFileName
Pointer to a buffer to which the training file name setting will be copied.
iSize
Length of the buffer. The buffer must be large enough to hold all the characters and a terminating zero.

Description:

This function gets the current training file setting.

Call this function to see whether there is currently a training file in use and what its name is. If this call returns an empty string it means that no training file has been selected.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_training_file_name_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_training_file_name_set(
        LPCSTR pFileName
        );

Arguments:

pFileName
Name of the training file, or NULL. NULL disables the use of a previously loaded training file during recognition.

Description:

This function is used to load a training file for the machine print text recognition. A training file contains the results of a previous training session, and its use may influence the recognition result.

Comments:

The text recognition modules are trainable. This function enables the use of training stored in one of any number of training files. On a document with repeated printing errors or with an unusual typeface some further training can be done to achieve higher accuracy.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_tradeoff_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_tradeoff_get(
        RMTRADEOFF *pTradeoff
        );

Arguments:

pTradeoff
Pointer to a variable to get the current trade-off setting.

Description:

This function provides the current trade-off setting.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_tradeoff_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_tradeoff_set(
        RMTRADEOFF Tradeoff
        );

Arguments:

Tradeoff
trade-off setting to be set.

Description:

This function specifies the tradeoff setting of the recognition engine that will be applied during auto-zoning and recognition. This setting applies to all the relevant recognition modules.

Comments:

Currently the trade-off setting is effective for the following recognition modules:

  • RM_OMNIFONT_MOR: omnifont multi-lingual module,
  • RM_OMNIFONT_MTX: omnifont module,
  • RM_HNR: handprinted numeral module,
  • RM_RER: handprint module,
  • RM_BAR2D: 2D bar code module.

This setting does not influence the behavior of any other RECOGNITIONMODULE recognition module. Not all of the above modules interpret the settings in the same way.

2.) If this function is not called, the default value TO_ACCURATE is applied.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_edit_close

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_edit_close();

Description:

This function closes the User dictionary previously opened by the IG_REC_UD_edit_open () function.

Comments:

To save the latest changes made to the User dictionary, a call to the IG_REC_UD_save () is necessary before calling this function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_edit_open

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_edit_open();

Description:

This function opens a User dictionary for editing purposes: to list its contents (its sections or their items), to add or delete UDitems and to save the changes.

Comments:

1.) The program should call IG_REC_UD_edit_close () for proper closing before terminating the recognition engine with the IG_REC_close () call.

2.) Changes made to the User dictionary need a separate saving step with the IG_REC_UD_save () function before the dictionary is closed.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_get(
        LPSTR pFilename,
        size_t iSize1,
        LPSTR pDefaultSection,
        size_t iSize2
        );

Arguments:

pFilename
Pointer to a buffer to get the name of the current User dictionary. If there is no User dictionary specified, an empty string is returned.
iSize1
Length of the buffer for the name of the User dictionary.
pDefaultSection
Pointer to a buffer to get the name of the current default section name. If there is no default section specified, an empty string is returned, signaling that the first section of the User dictionary is the default section.
iSize2
Length of the buffer for the default section. The length of each section name never exceeds MAXSECTNAMELEN characters (including the terminating zero)

Description:

This function gets the name of the current User dictionary and its default section.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_item_add

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_item_add(
        LPCSTR pSection,
        LPCWSTR pUDitem,
        DWORD itemattrib);

Arguments:

pSection
Name of the section where the word should be added. If the specified section does not exist, a new section will be created automatically.
pUDitem
Pointer to a UNICODE string containing the item to be added.
itemattrib
Attribute for the UDitem to be added. A zero (0) value denotes a literal string and UI_REGEXP denotes a regular expression.

Description:

This function is used to add a new User dictionary item (or simply UDitem), that is a literal or a regular expression, to the User dictionary currently opened for editing by the RecOpenMaintenanceUD function. The item will be added to the pSection of the User dictionary.

Comments:

1.) User dictionary items are UNICODE strings and they must be no longer than MAXUDITEMLEN characters (including the terminating zero). They may contain spaces and punctuation characters.

2.) When adding a new UDitem its itemattrib also has to be specified. An item can be added either as a literal or as a regular expression. UDitems having the regular expression attribute will be evaluated for conformance during the checking of the recognized result.

3.) When the characters to be added are contained in the Windows ANSI (1252) Code Page, the easiest way to define the pUDitem string is with a wide-character-string literal, L"characters". If any needed character falls outside the ANSI (1252) Code Page, you can convert these characters one after each other with the IG_REC_util_convert_codepage_to_unicode () utility function which converts a single character code from the current single-byte Code Page value (IG_REC_output_codepage_set ()) to its UNICODE representation.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_item_delete

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_item_delete(
        LPCSTR pSection,
        LPCWSTR pUDitem,
        DWORD itemattrib
        );

Arguments:

pSection
Name of the section from where the item should be deleted.
pUDitem
Pointer to a UNICODE string containing the word to be deleted. (The string is terminated with a double zero.)
itemattrib
Attribute for the UDitem to be deleted. It can be either zero (0, for a literal) or UI_REGEXP (for a regular expression).

Description:

This function deletes a word from the user dictionary currently opened for editing by the RecOpenMaintenanceUD function. The item to be deleted is specified together with the pUDitem and itemattrib parameters and it is searched under the pSection section only.

Comments:

1.) When the characters to be deleted are contained in the ANSI (1252) Code Page, the easiest way to define the pUDitem string is with a wide-character-string literal, L"characters". If any needed character falls outside the ANSI (1252) Code Page, you can convert these characters one after each other with the IG_REC_util_convert_codepage_to_unicode () utility function, which converts a single character code from the current single-byte Code Page value (IG_REC_output_codepage_set ()) to its UNICODE representation.

2.) When in the pSection there are two pUDitem items (with the same name, but with different attributes), the itemattrib parameter will select the required one to be deleted.

3.) Deleting the last UDitem from a section causes the section to be removed automatically from the User dictionary.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_item_first_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_item_first_get(
        LPCSTR pSection,
        LPWSTR pUDitem,
        size_t buflen,
        LPDWORD pitemattrib
        );

Arguments:

pSection
Name of the section of the User dictionary whose items are to be listed.
pUDitem
Pointer to a buffer to get the first UNICODE item of the item-list.
buflen
Specifies the size of the buffer in bytes.
pitemattrib
Pointer to a variable to hold the item's attribute. It can be either 0 for a literal, or UI_REGEXP for a regular expression.

Description:

This function, together with the IG_REC_UD_item_next_get () function, creates an item-list from the currently opened User dictionary. This function returns the first item (the UDitem and its attribute) from the pSection section of the User dictionary.

The application has to allocate a buffer with sufficient size to accommodate the current UDitem.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_item_next_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_item_next_get(
        LPWSTR pUDitem,
        size_t buflen,
        LPDWORD pitemattrib
        );

Arguments:

pUDitem
Pointer to a buffer to get the next UNICODE item (word) in the item-list. If the returned string is empty, the inquired section of the User dictionary does not contain further elements.
buflen
Specifies the size of the buffer in bytes.
pitemattrib
Pointer to variable to hold the item attribute. It can be either zero (0) for a literal, or UI_REGEXP for a regular expression.

Description:

This function (together with the IG_REC_UD_item_first_get () function) is used to create an item-list from the currently opened User dictionary. This function returns in its pUDitem parameter the next item of the item-list from the section (specified by a previous IG_REC_UD_item_first_get() function call).

Repeated calls to this function get a sequence of the UDitems (User dictionary items) and generate a return code IGE_SUCCESS each time. As soon as the function finds no further item to get, it returns with IGW_REC_SCANSOFT_WARNING / SPL_NOMORE_WARN, signaling that the list is complete.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_save

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_save(
        LPCSTR pFilename
        );

Arguments:

pFilename
Pointer to the name of the User dictionary file. If it is NULL, the current dictionary name will be used as set by a previous call to the IG_REC_UD_set () function.

Description:

This function is used to save the User dictionary to a file.

Comments:

1.) If the current dictionary was created by the IG_REC_UD_set() function called with parameter NULL, the pFilename parameter should specify a real filename, otherwise this function returns with IG_REC_SCANSOFT_ERROR/SPL_FOPEN_ERR.

2.) Saving the User dictionary under a different file name does not specify the User dictionary setting automatically. For this a separate IG_REC_UD_set () call is necessary.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_section_first_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_section_first_get(
        LPSTR pSection,
        size_t buflen
        );

Arguments:

pSection
Pointer to a buffer for the name of the first section in the User dictionary.
buflen
Specifies the size of the buffer in bytes.

Description:

This function, together with IG_REC_UD_section_next_get (), creates a listing of the sections in the User dictionary currently opened for editing by the IG_REC_UD_edit_open () function.

Comments:

1.) The lengths of each section name never exceeds MAXSECTNAMELEN characters (including the terminating zero).

2.) The function returns with IGW_REC_SCANSOFT_WARNING / SPL_NOMORE_WARN if there is no section in the User dictionary, signaling the list is empty.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_section_next_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_section_next_get(
        LPSTR pSection,
        size_t buflen
        );

Arguments:

pSection
Pointer to a buffer for the name of the next section in the User dictionary.
buflen
Specifies the size of the buffer in bytes.

Description:

This function, together with IG_REC_UD_section_first_get (), creates a listing of the sections in the User dictionary currently opened for editing by the IG_REC_UD_edit_open () function.

Comments:

1.) The length of each section name never exceeds MAXSECTNAMELEN characters (including the terminating zero).

2.) Repeated calls to this function get a sequence of the sections and generate a return code IGE_SUCCESS each time. As soon as the function finds no further section to get, it returns with IGW_REC_SCANSOFT_WARNING / SPL_NOMORE_WARN, signaling that the list is complete.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_set(
        LPCSTR pFilename,
        LPCSTR pDefaultSection
        );

Arguments:

pFilename
Name of the User dictionary file. If it is NULL, a new and empty User dictionary will be created in memory.
pDefaultSection
Name of the default section in the User dictionary. If it is NULL, the default section will be the first section of the dictionary, if any.

Description:

This function specifies a User dictionary and its default section for the checking subsystem. This function can also be used to initiate the creation of a new and empty User dictionary in memory.

Comments:

1.) The functionality of the checking subsystem consists of the following three parts:

  • Spell checking (use of Language and/or Vertical dictionary),
  • UD-checking (use of the User dictionary),
  • user-written checking (use of user-written callback functions).

Once the checking subsystem has been enabled, it can be further configured to use any combination of these three possible checkings.

2.) This function call must be used to enable or disable UD-checking during recognition (IG_REC_image_recognize ()).

A call to this function is also necessary to first define a User dictionary, in order to allow the application to maintain it (to create, add or remove items, etc.) with (IG_REC_UD_edit_open ()).

3.) To disable a previously enabled User dictionary, call this function with the NULL pFilename parameter. This same calling is necessary when the application wants to create a new, empty User dictionary.

4.) A User dictionary consists of one or more sections; the sections may contain one or more specified UDitems. The application can enumerate the sections in the User dictionary with the IG_REC_UD_section_first_get () and IG_REC_UD_section_next_get () function-pair. Each zone can be linked to a section in the User dictionary.

An UDitem is always associated with an item attribute. Depending on their attributes, items are added to the User dictionary either as literals (the item attribute is zero, 0) or as regular expressions (UI_REGEXP). Literal-type UDitems can be used as conventional User dictionary items. The use of the regular expressions is documented in the topic Regular expressions.

User dictionary items are UNICODE strings and they must be no longer than MAXUDITEMLEN characters (including the terminating zero). They may contain spaces and punctuation characters.

5.) If no default section is specified, the first section of the User dictionary becomes the default.

6.) The function returns with IGE_REC_SCANSOFT_ERROR/SPL_BADFILEFORMAT_ERR, if the pFilename specified is not a valid User dictionary file. It returns with IGE_REC_SCANSOFT_ERROR /SPL_FOPEN_ERR if the file cannot be opened.

7.) If the pFilename parameter specifies an existing User dictionary file, it must be either a native dictionary file created by a previous IG_REC_UD_save () call, or it must be a word-list file.

A word-list file is a text file; it contains words, one in each line. Regular expressions and sections are not supported. The checking subsystem loads Unicode based word-list files properly, while 8-bit code page based files are treated as Windows ANSI based ones.

Note that the UDCREATE tool used in the previous toolkit version to convert word-list files to native dictionary files is not distributed any more. (To create a native dictionary from a word-list file, simply load it and save the file to have it converted.)

8.) If this function is not called, by default, no UD-checking is enabled.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_UD_state_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_UD_state_get(
        LPBOOL pChanged
        );

Arguments:

pChanged
Address of a variable to get the modified flag.

Description:

This function inquires information about any type of change in the User dictionary, like adding or deleting UDitems.

If the returned pChanged value is TRUE, then the User dictionary has been modified since the last IG_REC_UD_save () saving action or since opening the dictionary with the IG_REC_UD_edit_open () call.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_util_convert_codepage_to_unicode

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_util_convert_codepage_to_unicode(
        BYTE Export,
        LPCWCH pUnicode
        );

Arguments:

Export
Character code to be converted.
pUnicode
Pointer to a UNICODE buffer for the converted character code.

Description:

This function converts a single character code from the current single-byte Code Page value to its UNICODE representation.

Comments:

1.) This function can be useful whenever a character or a character string should be passed to an API function requiring the character's or strings's UNICODE representation. (e.g. IG_REC_output_rejection_symbol_set ()).

2.) The current Code Page may have been set or changed by a previous IG_REC_output_codepage_set () function call.

3.) This function does not support the two-byte WordPerfect code pages.

Example:

Specifying the rejection symbol:

BYTE chRej = '~';
WCHAR wRej;
..
IG_REC_util_convert_codepage_to_unicode(chRej, &wRej);
IG_REC_output_rejection_symbol_set(wRej);

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_util_convert_unicode_to_codepage

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_util_convert_unicode_to_codepage(
        WCHAR Unicode,
        LPBYTE pExport
        );

Arguments:

Unicode
Code of the character to be converted (in UNICODE).
pExport
Pointer to the buffer for the conversion.

Description:

This function converts a UNICODE character to its representation in the current, single-byte Code Page.

Comments:

1.) The current Code Page setting might have been specified by a previous IG_REC_util_convert_codepage_to_unicode () function call.

2.) This function does not support the two-byte WordPerfect code pages.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_util_coordinates_transform

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_util_coordinates_transform(
        HIG_REC_IMAGE hImg,
        int nP,
        LPPOINT pPoint,
        BOOL breverse
        );

Arguments:

hImg
Handle of the image.
nP
Number of points to be calculated (size of the pPoint array).
pPoint
Points to an array of POINT structures containing the input point coordinates.
breverse
When TRUE, the function will treat the values in pPoint array as coordinates belonging to the hImg image, and so it will calculate their corresponding coordinates on the original (incoming) image.
When FALSE, the function will treat the values in pPoint array as coordinates belonging to original (incoming) image, and so the function will calculate the corresponding coordinates on the actual hImg image.

Description:

This function can be used to learn the coordinates of points on the original (incoming) image, when the coordinates of points on the specified hImg image are known. This might be necessary, since images often undergo different image preprocessing steps, such as deskewing, rotation, etc. Alternatively, this function can provide the coordinates of points on the actual hImg image, when their coordinates on the original image are given.

Comments:

1.) As the result of this function call, the calculated point coordinates can be accessed in the pPoint array.

2.) A typical use of this function is when the application needs to know the precise position of a recognized character on the original (incoming) image. Though the API can provide the coordinates of the bounding rectangles for each recognized character, these values cannot be used directly, since they relate to the hImg image, which can significantly differ from the original one.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_vertical_dict_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_vertical_dict_get(
        LPSTR pFilename,
        size_t iSize
        );

Arguments:

pFilename
Pointer to a buffer to get the name of the current Vertical dictionary. If no Vertical dictionary was specified, an empty string is returned.
iSize
Length of the buffer for the name of the Vertical dictionary.

Description:

This function gets the name of the current Vertical dictionary.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_vertical_dict_info_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_vertical_dict_info_get(
        LPSTR pFilename,
        LANGUAGES *pLang,
        LPSTR desc,
        size_t iSize
        );

Arguments:

pFilename
Name of the Vertical dictionary file requested.
pLang
Pointer to a buffer to hold the language of the Vertical dictionary for the pFilename.
desc
Pointer to a buffer to hold the Vertical dictionary descriptor information for the file pFilename.
iSize
Specifies the size of the buffer pDesc, in bytes.

Description:

This function provides information about the Vertical dictionary specified.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_vertical_dict_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_vertical_dict_set(
        LPCSTR pFilename
        );

Arguments:

pFilename
Name of the Vertical dictionary file to be set,or NULL. Use NULL to disable a previously set Vertical dictionary.

Description:

This function specifies a Vertical dictionary for the checking subsystem.

Comments:

1.) Specifying a Vertical dictionary is a page-level setting. Once it is specified, it is applied to all zones on the page, except in zones with their CHK_VERTDICT_PROHIBIT flag set. This is useful for excluding zones from the Vertical dictionary checking.

2.) The distribution file set of the ImageGear Recognition component contains 8 different Vertical dictionaries for two professions (medical and legal) in four languages (English, German, French and Dutch), e.g. MEDICAL_ENG.DMD.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_zone_delete

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_zone_delete(
        HIG_REC_IMAGE 		hImg,
        INT					iZoneIndex
   );

Arguments:

hImg
Handle of the image.
iZoneIndex
Index in the zone list of the zone to be deleted.

Description:

This function deletes a zone from the zone list of the hImg image.

Comments:

1.) The index of the first zone in the zone list is zero (0).

2.) Calling this function disables the Non-gridded table detection algorithm, independently from the Nongridded table detection setting. For more detail see the IG_REC_decomp_nongridded_table_detect_set () function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_zone_info_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_zone_info_get(
        HIG_REC_IMAGE 			hImg,
        INT				nIndex,
        LPZONE				lpZoneInfo
   );

Arguments:

hImg
Handle of the image.
nIndex
Index of the zone in the zone list, whose information is requested.
lpZoneInfo
Pointer to a variable for storing the requested zone information.

Description:

This function gets information about any zone in the zone list of the hImg image.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_zone_info_set

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_zone_info_set(
        HIG_REC_IMAGE			 hImg,
        INT				nIndex,
        LPCZONE				lpZoneInfo
   );

Arguments:

hImg
Handle of the image.
nIndex
Index of the zone to be updated.
lpZoneInfo
Pointer to a zone structure with the necessary updating zone data.

Description:

This function updates the zone data of a single zone in the zone list.

Comments:

1.) The index of the first zone in the zone list is zero (0).

2.) When updating a zone, the application should directly initialize the rect, fm, rm, filter and the type fields of the zone, since they will not take on their default values. The application should not modify the seq zone field, except for OMR zones using the "filled-in-error" facility.

The type field of the zone being updated should be one of the following: WT_FLOW, WT_TABLE, WT_GRAPHIC.

3.) The preferred method for updating a zone is the following:

· call the IG_REC_zone_info_get () to ask the current parameters of the zone,

· modify the zone parameters,

· call the IG_REC_zone_info_set () function.

4.) It is the programmer's responsibility to specify a valid recognition module-filling method pair. Any incorrectly set zone will have no recognition result. For more detail see the Recognition module specifications.

5.) Calling this function may disable the Non-gridded table detection algorithm. This occurs when the zone coordinates after the update differ from their previous coordinate values. For more details see the IG_REC_decomp_nongridded_table_detect_set () function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_zone_insert

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_zone_insert(
        HIG_REC_IMAGE			 hImg,
        INT				nIndex,
        LPCZONE				lpZoneInfo
   );

Arguments:

hImg
Handle of the image.
nIndex
Index in the zone list where the new zone should be inserted. Use zero (0) to insert the zone as the first element of the zone list. To insert a zone as the last element of the zone list, use the IG_REC_zones_count_get function to get (and use) the number of zones in the list.
lpZoneInfo
Pointer to the zone data to be inserted.

Description:

This function inserts a new zone in the zone list of the hImg image. After zone insertion, the zone list is recalculated automatically.

Comments:

1.) When inserting a zone, the application should directly initialize the rect, fm, filter and the type fields of the zone, since they will not take on their default values.

2.) Though in general the seq field is managed by the recognition engine, there is a special case when the integrating application may want to set this field: when OMR zones are recognized with the `filled-in-error' feature. For more detail see the function IG_REC_OMR_params_set ().

3.) The type field of the zone to be inserted should be one of the following: WT_FLOW, WT_TABLE or WT_GRAPHIC.

4.) For successful zone insertion the whole zone area must lie within the hImg image area and the top left coordinates of the zone must have lower values than those of the bottom right ones.

5.) It is the programmer's responsibility to specify a valid recognition module-filling method pair. Any incorrectly set zone will have no recognition result. For more detail see the Recognition module specifications.

6.) Calling this function disables the Non-gridded table detection algorithm, independently from the Nongridded table detection setting. For more detail see the IG_REC_decomp_nongridded_table_detect_set () function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

Insertion of a zone (containing machine printed uppercase flowed text):

HIG_REC_IMAGE hImg;
ZONE zone;
memset(&zone, 0, sizeof(ZONE));
zone.rect.left = 0;
zone.rect.top = 0;
zone.rect.right = 100;
zone.rect.bottom = 200;
zone.fm = FM_OMNIFONT;
zone.rm = RM_OMNIFONT_MOR;
zone.filter = (CHR_FILTER)(FILTER_UPPERCASE | FILTER_DIGIT);
zone.type = WT_FLOW;
RecInsertZone(hImg, &zone, 0);


IG_REC_zones_count_get

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_zones_count_get(
        HIG_REC_IMAGE 		hImg,
        LPINT				lpZoneCount
   );

Arguments:

hImg
Handle of the image.
lpZoneCount
Address of an integer variable to get the number of zones.

Description:

This function gets the number of zones in the zone list of the hImg image.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_zones_delete_all

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_zones_delete_all(
        HIG_REC_IMAGE	 	hImg
   );

Arguments:

hImg
Handle of the image.

Description:

This function deletes all zones in the zone list of the hImg image.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_zones_load

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_zones_load(
        HIG_REC_IMAGE 		hImg,
        const LPSTR	 		lpFileName
   );

Arguments:

hImg
Handle of the image.
lpFileName
Name of the zone file to be loaded.

Description:

This function loads the zone list from a zone file. The function attaches the zone list to the hImg image.

Comments:

Calling this function removes any zone list already attached to the hImg image.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_zones_locate

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_zones_locate(
        HIG_REC_IMAGE		 hImg,
        LPAT_RECT			lpRect
   );

Arguments:

hImg
Handle of the image.
lpRect
Active image area for the analysis. The function will be effective only within this rectangle. If this parameter is NULL, then the entire hImg image will be processed.

Description:

This function is used for parsing the image (also called: auto-zoning), i.e. it analyzes the structure of the page layout of the hImg image and locates blocks for further processing.

The function performs the analysis within the specified area of the image: it finds text or graphics blocks within the specified area, builds a zone list and then connects it to the hImg image.

The IG_REC_zones_locate () function activates the PID_DECOMPOSITION process.

Comments:

1.) If the hImg image is not bitonal one (i.e. it is a grayscale or a color image), an implicit secondary image conversion step is performed automatically to convert the image to a new, internal and despeckled bitonal image on which the auto-zoning function will operate. The parameter for this conversion can be specified through the function IG_REC_secondary_reduction_mode_set ().

With bitonal images at over a resolution of 280 dpi, if the Image despeckle mode setting is enabled, an implicit secondary image conversion step is also performed. This is enabled through the function IG_REC_despeckle_mode_set ().

2.) Zones found by this function are entered in a sequential list, called the zone list, which is attached to the hImg image. When this function is called, any previously inserted zones are deleted from this list.

3.) The IG_REC_zones_count_get () function can be used to retrieve the number of zones in the zone list for an image. Zones can be deleted from this list by the IG_REC_zone_delete () function. The application can get the zone parameters by the IG_REC_zone_info_get () function. After modifying some zone attributes the IG_REC_zone_info_set () function can be used to make the changes effective.

4.) The IG_REC_zones_locate () function finds the zone coordinates and the type of the zones. The zone type determines the role of the zone in the image layout and can be classified into three different groups:

  • Group 1: flowed text types:

WT_COLUMN, WT_FLOW, WT_HEADER, WT_FOOTER, WT_CAPTION, WT_TITLE, WT_OTHER.

These zone types mean that the zone contains textual information without a table type structure (it is flowed text). The types listed above are considered the same, they are differentiated from each other during the later processing stages.

  • Group 2: table text type:

WT_TABLE.

This type means that the zone is detected as containing a table, i.e. with columns, with or without a grid. Such zones are handled differently from those of flowed text type zones.

  • Group 3: graphic zones:

WT_GRAPHIC, WT_SGRAPHIC.

These zones contain graphics, i.e. this zone will not be recognized at all. These zones exist only to allow saving or export of the image inside the zone area.

5.) This version of the Recognition component offers three page parser algorithms to be chosen. Unless specified otherwise, the more accurate one will be applied. Use the IG_REC_decomp_method_set () function to change the Page parser algorithm settings.

6.) Setting the Force Single Column mode (IG_REC_decomp_single_column_force_set ()) can influence the working of this function. It prevents detecting columns, which means decolumnization is not available. It can be useful for conserving the columnar structure in tables.

7.) New zones created by this function always take the value FILTER_DEFAULT, meaning that the zone will take on the global filter setting (which is by default FILTER_ALL to have no filtering).

8.) New zones located by this function always have the FM_DEFAULT and RM_AUTO values in their fm and rm fields, respectively. The "meaning" of the FM_DEFAULT filling method can be specified with the IG_REC_default_filling_method_set () function.

On the other hand, there is no similar function for specifying the default recognition module, since the recognition module to be applied will be automatically chosen according to the zone's filling method FILLINGMETHOD, and Character Set settings. In order to overrule this automatic RECOGNITIONMODULE selection, you must update each zone in the zone list with the IG_REC_zone_info_set () function.

9.) New zones created by this function always have empty strings in their chk_sect field, which specifies the use of the default section of any enabled User dictionary.

10.) Another useful function, IG_REC_image_filling_method_detect () can help when you don't know the type of page to be processed.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_REC_zones_save

Group: Recognition

Declaration:

AT_ERRCOUNT ACCUAPI IG_REC_zones_save(
        HIG_REC_IMAGE		 hImg,
        const LPSTR			 lpFileName
   );

Arguments:

hImg
Handle of the image.
lpFileName
Name of the zone file to be created.

Description:

This function saves the current zone list of the hImg image into a zone file.

Comments:

1.) This function overwrites a pre-existing zone file with the same name.

2.) The zone coordinates are saved in the zone file in 1/1200 inches.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


Recognition Component Enumerations

The following enumerations are used in ImageGear Recognition component:

BAR_ENA
Identifies the possible values for the particular barcode type selection
BAR_TYPE
Identifies the barcode types supported by the BAR recognition module
CHECKWORDRETURNCODE
Identifies the possible values which a user-written checking callback function should return
CHR_ENA
Identifies the values which indicate whether or not a given character is validated for recognition
CHR_FILTER
Identifies the available Character Set filter elements
enumIGRecFeatures
Identifies the features of the ImageGear Recognition component that are licensed separately
FILLINGMETHOD
Identifies the the possible content types of the zones
HNR_STYLE
Identifies the writing style of the characters for the HNR handprinted numerals recognition module
IMG_CONVERSION
Identifies image conversion modes
IMG_DECOMP
Identifies image decomposition modes
IMG_DESKEW
Identifies image deskewing mode settings
IMG_INVERT
Identifies image inversion mode settings.
IMG_RESENH
Identifies resolution enhancement modes
IMG_ROTATE
Identifies image orientation modes
LANG_ENA
Identifies the possible values for the language selection
LANGUAGES
Identifies the different languages supported directly by the recognition engine
MODULES
Identifies the modules of the ScanSoft recognition engine
OMR_FRAME
Identifies the frame detection method to be applied during the running of the OMR optical mark recognition module
OMR_SENSE
Identifies the possible mark sensitivity values to be applied during the running of the OMR checkmark recognition module
OUTCODEPAGETYPE
Identifies the basic Code Page categories.
OUTPUTALIGNMENT
Identifies the values for exporting for the paragraph alignment property to the final output document.
OUTPUTGRAPHICS
Identifies the graphics retaining modes for the final output document
OUTPUTLANGUAGE
Identifies the languages for exporting the document language property to the final output document.
OUTPUTLEVEL
Identifies the pre-defined levels of the format retention for the final output document.
OUTPUTLINESPACE
Identifies the values for exporting the Line Space property to the final output document.
OUTPUTPAPERORIENTATION
Identifies the valid orientation values for exporting the document orientation property to the final output document
OUTPUTPAPERSIZE
Identifies the valid size values for exporting the Paper Size property to the final output document.
OUTPUTSWITCH
General purpose enum type, is used for different output text properties to indicate how they should be handled.
OUTPUTTABLEMETHOD
Identifies the table handling modes for the final output document
OUTPUTTXTTYPE
Identifies output converter type categories.
PROCESSID
Identifies recognition engine processes
RECOGNITIONMODULE
Identifies the recognition modules of the ScanSoft recognition engine
RMTRADEOFF
Identifies the recognition algorithm trade-off setting

Below is an alphabetized reference of ImageGear Recognition Component enumerations.


BAR_ENA

Group: Enumeration

Description:

This enumeration defines the possible values for the particular barcode type selection.

Values:

BAR_DISABLED
The particular barcode type is disabled
BAR_ENABLED
The particular barcode type is enabled


BAR_TYPE

Group: Enumeration

Description:

This enumeration Identifies barcode types.

Values:

BAR_EAN
EAN 8/13
BAR_SUPPL
EAN/UPC with 2 & 5-digit supplement
BAR_UPC_A
UPC-A
BAR_UPC_E
UPC-E (6-digit)
BAR_ITF
ITF (2 of 5 interleaved)
BAR_ITF_CDT
ITF with check digit control and transmit
BAR_C39
Code 39 (does not support lowercase letters)
BAR_C39_CDT
Code 39 with check digit control and transmit
BAR_C39_SST
Code 39 with start-stop char transmit
BAR_C39_FA
Code 39 full ASCII mode (supports both of lower and uppercase letters)
BAR_C128
Code 128
BAR_C128_CDT
Code 128 with check digit transmit
BAR_CB
Codabar
BAR_CB_SST
Codabar with start-stop char transmit
BAR_POSTNET
Postnet code
BAR_A2of5
Airline 2 of 5 (Not supported in this toolkit version)
BAR_UCC128
UCC Code 128
BAR_2of5
Code 2 of 5 (Not supported in this toolkit version)
BAR_93
Code 93 (Not supported in this toolkit version)
BAR_SIZE
Number of supported barcode types


CHR_FILTER

Group: Enumeration

Description:

This enumeration identifies character set filters.

Values:

FILTER_DEFAULT
This value is used to have the zone handled globally. Do not combine this with any other filter
FILTER_DIGIT
[Bit mask] Recognition of numerals only. E.g.: "3" (Digit Three).
FILTER_UPPERCASE
[Bit mask] Recognition of uppercase letters only, including accented ones
FILTER_LOWERCASE
[Bit mask] Recognition of lowercase letters only including accented ones
FILTER_PUNCTUATION
[Bit mask] Recognition of punctuation signs only. E.g.: "!" (Exclamation Mark)
FILTER_MISCELLANEOUS
[Bit mask] Recognition of other miscellaneous characters only. E.g.: "+" (Plus sign)
FILTER_PLUS
[Special, combinable filter] Enables the use of the FilterPlus characters.The FilterPlus characters are added after any filtering
FILTER_ALL
[Pre-defined combined filter] Since all elements are enabled, there is no filtering
FILTER_ALPHA
[Pre-defined combined filter] Recognition of upper and lowercase letters only.
FILTER_NUMBERS
[Pre-defined combined filter] Recognition of the digits, plus the FilterPlus characters.
FILTER_SIZE
Number of possible combinations of the bit mask filters


CHECKWORDRETURNCODE

Group: Enumeration

Description:

This enum defines the possible values which a user-written checking callback function should return. This type of function should be written for zones where the accuracy of the recognition should be improved by providing the recognition module involved with additional checking information derived from the application.

Values:

CW_IMPOSSIBLE
In the application's opinion the recognized string for the given zone passed to the checking function cannot be possible
CW_UNLIKELY
In the application's opinion the recognized string for the given zone passed to the checking function is unlikely to be acceptable
CW_UNRESOLVED
The application's checking function cannot make a decision on the acceptability of the string for the zone
CW_POSSIBLE
In the application's opinion the recognized string for the given zone passed to the checking function is possibly acceptable
CW_SURE
In the application's opinion the recognized string for the given zone passed to the checking function is certainly acceptable


CHR_ENA

Group: Enumeration

Description:

This enumeration provides two values which indicate whether or not a given character is validated for recognition for the current page.

Values:

CHR_DISABLED
The current character is disabled.
CHR_ENABLED
The current character is validated for recognition.


enumIGRecFeatures

Group: Enumeration

Description:

This enumeration identifies the features of the ImageGear Recognition component that are licensed separately.

Values:

IG_REC_FEATURE_NONE
No features
IG_REC_FEATURE_OCR
OCR Optical Character Recognition feature. Enables the following recognition modules:
MTX omnifont recognition module
MOR multi-lingual omnifont recognition module
DOT 9-pin draft dot-matrix recognition module
MAT matrix matching recognition module,
PLUS2W omnifont recognition module,
PLUS3W omnifont recognition module,
FRX multi-lingual omnifont recognition module
IG_REC_FEATURE_ICR
ICR Intellectual Character Recognition feature (handwritten text recognition). Enables the following recognition modules:
HNR handprinted numeral recognition module,
RER alphanumeric handprinted recognition module
IG_REC_FEATURE_OMR
OMR Optical Mark Recognition feature. Enables the following recognition module:
OMR optical mark recognition module
IG_REC_FEATURE_BARCODE_BASIC
Basic Bar Code Recognition feature. Enables the following recognition module:
BAR bar code recognition module
This module provides support for the basic set of 1D bar codes (provided that the BAR module is licensed).
IG_REC_FEATURE_BARCODE_ADVANCED
Advanced Bar Code Recognition feature. Enables the following recognition module:
BAR2D bar code recognition module
This module provides support for the full set of 1D barcodes, and for 2D barcodes (provided that both BAR and BAR2D modules are licensed).


FILLINGMETHOD

Group: Enumeration

Description:

This enumeration identifies zone filling methods.

Values:

FM_DEFAULT
The default zone filling method. The actual zone filling method for all zones of this type will be retrieved just before recognition, according to the DefaultFillingMethod property of the IGRecDocument object .
FM_OMNIFONT
The omnifont zone filling method. It denotes a machine printed text with any typeface which is not too stylized.
FM_DRAFTDOT9
The 9-pin draft dot-matrix zone filling method. It denotes a 9-pin draft dot-matrix printout.
FM_BARCODE
The 1D bar code zone filling method. It denotes a one-dimensional bar code within the zone.
FM_OMR
The optical mark zone filling method. It denotes a possible marking within the zone.
FM_HANDPRINT
The handprinted zone filling method. It denotes handprinting within the zone.
FM_BRAILLE
Not supported.
FM_DRAFTDOT24
The 24-pin draft dot-matrix zone filling method. It denotes a 24-pin draft dot-matrix printout.
FM_OCRA
OCR-A zone filling method.
FM_OCRB
OCR-B zone filling method.
FM_MICR
Magnetic ink character filling method.
FM_BARCODE2D
2D bar code zone filling method.
FM_DOTDIGIT
Dot-digit zone filling method.
FM_DASHDIGIT
Dash-digit zone filling method.
FM_ASIAN
Not supported
FM_NO_OCR
No recognition will be attempted.
FM_SIZE
Number of filling methods


HNR_STYLE

Group: Enumeration

Description:

This enumeration identifies writing style setting for the HNR handprinted numerals recognition module.

Values:

STYLE_EURO
Writing in European style
STYLE_US
Writing in North-American style


IMG_CONVERSION

Group: Enumeration

Description:

This enum identifies image conversion modes to be applied for conversions from grayscale or 24-bit color image sources. These values specify how the different image types will be converted either during the primary image conversions or during the secondary image conversions.

Values:

CNV_AUTO
This has an effect on grayscale or 24-bit color images: a B/W image is created in ENGine's memory. An automatic adaptive thresholding algorithm is applied for the binarization of the image. Use the Brightness property to fine tune the threshold calculation.
CNV_SET
This has an effect on grayscale or 24-bit color images: a bitonal image is created internally. Thresholding with a user defined threshold value, set by the Threshold property.
CNV_NO
There is no conversion while loading the image. The image is loaded without any conversion (i.e. a color image retains its color attributes).
CNV_GLOBAL
This has an effect on grayscale or 24-bit color images: a bitonal image is created internally. An automatic thresholding algorithm with a page-level global threshold value is applied for the binarization of the image.
CNV_GRAY
For a color image: a grayscale image is created internally. For a bitonal or grayscale image: no reduction is performed while loading the image.


IMG_DECOMP

Group: Enumeration

Description:

This enumeration identifies methods for decomposing the document into zones.

Applying the DCM_STANDARD algorithm results in better throughput in overall accuracy, though in some complex cases it might require significantly more time to complete.

Values:

DCM_AUTO
Specifies that the toolkit will determine at run-time whether the DCM_LEGACY or DCM_STANDARD algorithm will be applied.
DCM_LEGACY
Identifies the page-parsing algorithm exclusively used in the ScanSoft toolkit before its version 11.0.
DCM_STANDARD
Identifies the most accurate page parsing algorithm of the Recognition component.
DCM_FAST
This algorithm can be treated as a simplified variant of DCM_LEGACY. This algorithm doesn't try to find tables on the page.
It is the fastest (but least accurate) parsing algorithm available. Use only for simple page parsing tasks!


IMG_DESKEW

Group: Enumeration

Description:

This enumeration identifies image deskewing modes.

Values:

DSK_AUTO
Automatic deskewing
DSK_NO
No deskewing applied
DSK_SET
Deskew with a given angle, set by the IGRecPreprocessingSettings.Skew


IMG_INVERT

Group: Enumeration

Description:

This enumeration identifies image inversion modes

Values:

INV_NO
No inversion required
INV_YES
Image inversion should be performed.
INV_AUTO
Automatically inverts image, if necessary


IMG_RESENH

Group: Enumeration

Description:

This enumeration identifies resolution enhancement modes.

Values:

RE_NO
No resolution enhancement will be done
RE_YES
Resolution enhancement will be done on all non-bitonal images
RE_AUTO
Only images with a resolution of 150 or less are resolution-enhanced during secondary image conversion.


IMG_ROTATE

Group: Enumeration

Description:

This enumeration identifies image orientation modes.

Values:

ROT_AUTO
Automatic image orientation
ROT_NO
Do not orient the image
ROT_RIGHT
Rotate image to the right (90 degrees clockwise)
ROT_DOWN
Rotate image down (rotate twice)
ROT_LEFT
Rotate image to the left (90 degrees counter-clockwise)
ROT_FLIPPED
Flip around the Y axis
ROT_RIGHT_FLIPPED
Flip around the Y axis, then rotate to the right
ROT_DOWN_FLIPPED
Flip around X-axis
ROT_LEFT_FLIPPED
Flip around the Y axis, then rotate to the left


LANG_ENA

Group: Enumeration

Description:

This enumeration defines the possible values for the language selection in the Language environment definition.

Values:

LANG_DISABLED
The particular language is disabled
LANG_ENABLED
The particular language is enabled


LANGUAGES

Group: Enumeration

Description:

This enumeration identifies identifies the different languages supported directly by the Recognition component.

Values

LANG_UD
Used internally
LANG_START
Used internally
LANG_AUTO
Automatic language selection (only for spell checking !).
LANG_NO
No language selection at all. (only for spell checking!)
LANG_ENG
English language selection. Spelling supported.
LANG_GER
German language selection. Spelling supported.
LANG_FRE
French language selection. Spelling supported.
LANG_DUT
Dutch language selection. Spelling supported.
LANG_NOR
Norwegian language selection. Spelling supported.
LANG_SWE
Swedish language selection. Spelling supported.
LANG_FIN
Finnish language selection. Spelling supported.
LANG_DAN
Danish language selection. Spelling supported.
LANG_ICE
Icelandic language selection.
LANG_POR
Portuguese language selection. Spelling supported.
LANG_SPA
Spanish language selection. Spelling supported.
LANG_CAT
Catalan language selection. Spelling supported.
LANG_GAL
Galician language selection
LANG_ITA
Italian language selection. Spelling supported.
LANG_MAL
Maltese language selection.
LANG_GRE
Greek language selection. Spelling supported.(This selection includes the characters of the English language.)
LANG_POL
Polish language selection. Spelling supported.
LANG_CZH
Czech language selection. Spelling supported.
LANG_SLK
Slovakian language selection.
LANG_HUN
Hungarian language selection. Spelling supported.
LANG_SLN
Slovenian language selection. Spelling supported.
LANG_CRO
Croatian language selection.
LANG_ROM
Romanian language selection.
LANG_ALB
Albanian language selection.
LANG_TUR
Turkish language selection.
LANG_EST
Estonian language selection.
LANG_LAT
Latvian language selection.
LANG_LIT
Lithuanian language selection.
LANG_ESP
Esperanto language selection.
LANG_SRL
Serbian (Cyrillic) language selection.(This selection includes the characters of the English language.)
LANG_SRB
Macedonian (Cyrillic) language selection.(This selection includes the characters of the English language.)
LANG_MAC
Moldavian (Cyrillic) language selection.(This selection includes the characters of the English language.)
LANG_MOL
Bulgarian (Cyrillic) language selection.(This selection includes the characters of the English language.)
LANG_BUL
Byelorussian (Cyrillic) language selection.(This selection includes the characters of the English language.)
LANG_BEL
Ukrainian (Cyrillic) language selection.(This selection includes the characters of the English language.)
LANG_UKR
Russian (Cyrillic) language selection. Spelling supported. (This selection includes the characters of the English language.)
LANG_RUS
Afrikaans language selection.
LANG_AFR
Aymara language selection.
LANG_AYM
Basque language selection.
LANG_BAS
Bemba language selection.
LANG_BEM
Blackfoot language selection.
LANG_BLA
Breton language selection.
LANG_BRE
Brazilian-Portuguese
LANG_BRA
Bugotu language selection
LANG_BUG
Chamorro language selection
LANG_CHA
Chechen language selection. Cyrillic alphabet.
LANG_CHE
Tswana language selection (Chuana).
LANG_CHU
Corsican language selection.
LANG_COR
Crow language selection.
LANG_CRW
Eskimo language selection.
LANG_ESK
Faroese language selection.
LANG_FAR
Fijian language selection.
LANG_FIJ
Frisian language selection.
LANG_FRI
Friulian language selection.
LANG_FRU
Gaelic Irish language selection.
LANG_GLI
Gaelic Scottish language selection.
LANG_GLS
Ganda language selection (Luganda).
LANG_GAN
Guarani language selection.
LANG_GUA
Hani language selection.
LANG_HAN
Hawaiian language selection.
LANG_HAW
Ido language selection.
LANG_IDO
Indonesian language selection.
LANG_IND
Interlingua language selection.
LANG_INT
Kabardian language selection. Cyrillic alphabet.
LANG_KAB
Kasub language selection.
LANG_KAS
Kawa language selection.
LANG_KAW
Kikuyu language selection.
LANG_KIK
Kongo language selection.
LANG_KON
Kpelle language selection.
LANG_KPE
Kurdish language selection (Latin alphabet only).
LANG_KUR
Lappish language selection.
LANG_LTN
Latin language selection.
LANG_LUB
Luba language selection.
LANG_LUX
Luxembourgian language selection.
LANG_MLG
Malagasy language selection.
LANG_MLY
Malay language selection.
LANG_MLN
Malinke language selection.
LANG_MAO
Maori language selection.
LANG_MAY
Mayan language selection.
LANG_MIA
Miao language selection (Latin alphabet only).
LANG_MIN
Minankabaw language selection.
LANG_MOH
Mohawk language selection.
LANG_NAH
Nahuatl language selection.
LANG_NYA
Nyanja language selection.
LANG_OCC
Occidental language selection.
LANG_OJI
Ojibway language selection.
LANG_PAP
Papiamento language selection.
LANG_PID
Pigin English language selection.
LANG_PRO
Provencal language selection.
LANG_QUE
Quechua language selection.
LANG_RHA
Rhaetic language selection.
LANG_ROY
Romany language selection.
LANG_RUA
Ruanda language selection.
LANG_RUN
Rundi language selection.
LANG_SAM
Samoan language selection.
LANG_SAR
Sardinian language selection.
LANG_SHO
Shona language selection.
LANG_SIO
Sioux language selection.
LANG_SMI
Sami language selection (Combination of the Sami language family)
LANG_SML
Lule Sami language selection
LANG_SMN
Northern Sami language selection
LANG_SMS
Southern Sami language selection
LANG_SOM
Somali language selection.
LANG_SOT
Sotho language selection (Suto, Sesuto).
LANG_SUN
Sundanese language selection.
LANG_SWA
Swahili language selection.
LANG_SWZ
Swazi language selection.
LANG_TAG
Tagalog language selection.
LANG_TAH
Tahitian language selection.
LANG_TIN
Tinpo language selection.
LANG_TON
Tongan language selection.
LANG_TUN
Tun language selection (Latin alphabet only).
LANG_VIS
Visayan language selection.
LANG_WEL
Welsh language selection.
LANG_WEN
Sorbian language selection (Wend).
LANG_WOL
Wolof language selection.
LANG_XHO
Xhosa language selection.
LANG_ZAP
Zapotec language selection.
LANG_ZUL
Zulu language selection.
LANG_SIZE
Number of languages selectable directly.


MODULES

Group: Enumeration

Description:

This enumeration identifies the modules of the ScanSoft recognition engine.

Values:

INFO_API
ScanSoft core module
INFO_MOR
Multi-lingual MOR omnifont recognition module
INFO_DOT
9-pin draft dot-matrix recognition module
INFO_BAR
Barcode 1D recognition module
INFO_OMR
Optical mark recognition module.
INFO_HNR
Handprinted numeral recognition module.
INFO_DCM
Automatic page-layout decomposition module.
INFO_IMG
Image handling module.
INFO_IMF
Image file I/O module.
INFO_CHR
Character Set and Code Page handling module.
INFO_TMP
Output formatting module.
INFO_TXT
Output file generation module.
INFO_SPL
Checking module.
INFO_RSD
Scanning module (not used in the ImageGear recognition component)
INFO_RER
Handprinted character recognition module.
INFO_BRA
Not available
INFO_MGR
ScanSoft core module
INFO_MTX
M/TEXT omnifont recognition module
INFO_MAT
Matrix matching recognition module
INFO_BAR2D
The 2 dimensional (Seaport) barcode recognition module.
INFO_PLUS2W
PLUS2W omnifont recognition module
INFO_FRX
Multi-lingual FRX omnifont recognition module
INFO_PLUS3W
PLUS3W omnifont recognition module
INFO_ASN
Not available
INFO_SIZE
Number of modules


OMR_FRAME

Group: Enumeration

Description:

This enumeration specifies the frame detection method to be applied during the running of the OMR optical mark recognition module.

Values:

FRAME_AUTO
Automatic frame detection
FRAME_NO
There is no frame within the zone
FRAME_YES
There is a frame within the zone


OMR_SENSE

Group: Enumeration

Description:

This enumeration identifies mark sensitivity levels for the OMR otpical mark recognition component.

Values:

SENCE_NORMAL
Highest mark sensitivity
SENCE_LOW
Less mark sensitivity
SENCE_LOWER
Lower mark sensitivity
SENCE_LOWEST
Lowest mark sensitivity


OUTCODEPAGETYPE

Group: Enumeration

Description:

This enumeration identifies code page categories. Each output converter is classified into one of these categories.

Values:

CODEP_UNKNOWN
Code Pages not classified to any further categories, e.g. Roman-8
SPECIFIC
16-bit Code Pages, e.g. UNICODE
ASCII_BASED
Code Pages typically used by different localized DOS versions and DOS applications, e.g. CodePage 437
ANSI_BASED
Code Pages typically used by different localized Windows versions and Windows applications, e.g. Windows Greek.
MAC_BASED
Code Pages typically used by different localized Mac versions and applications, e.g. Macintosh Central European CP.
INTERNAL_CP
Reserved 8-bit and 16 bit Code Pages used internally by the ENGine.


OUTPUTALIGNMENT

Group: Enumeration

Description:

This enumeration identifies alognment modes for the output document.

Values:

OUT_LEFTALIGNMENT
Text will be left-aligned in the final output document.
OUT_RIGHTALIGNMENT
Text will be right-aligned in the final output document.
OUT_CENTERED
Text will be center-aligned in the final output document.
OUT_JUSTIFIED
Text will be justified in the final output document.


OUTPUTGRAPHICS

Group: Enumeration

Description:

This enumeration identifies the different modes of embedding graphical zones (if any) into the final output document.

Values:

OUT_NONEGR
Suppress all graphics in the final output document.
OUT_BW
Convert all graphics zones to B/W before inserting them into the final output document
OUT_GRAY
Convert all graphics zones to a 8-bit grayscale one before inserting them into the final output document.
OUT_TRUECOLOR
Convert all graphics zones to 24-bit color before inserting them into the final output document
OUT_ORIGINAL
Transmit all graphics zones without conversion


OUTPUTLANGUAGE

Group: Enumeration

Description:

This enumeration identifies languages that can be used for language marking of the final output document.

Values:

OUT_No_Language
Final output document hasn't any language marking setting (Default).
OUT_Albanian
Albanian language.
OUT_French
French language.
OUT_French_Belgian
French (Belgian) language.
OUT_Norwegian_Nynorsk
Norwegian (Nynorsk) language.
OUT_Polish
Polish language.
OUT_Bahasa
Bahasa language.
OUT_Catalan
Catalan language.
OUT_Croato_Serbian_Latin
Croato-Serbian (Latin) language.
OUT_Czech
Czech language.
OUT_Danish
Danish language.
OUT_Dutch
Dutch language.
OUT_Dutch_Belgian
Dutch (Belgian) language.
OUT_English_Australian
English (Australian) language.
OUT_English_UK
English (UK) language.
OUT_English_US
English (US) language.
OUT_Finnish
Finnish language.
OUT_French_Canadian
French (Canadian) language.
OUT_French_Swiss
French (Swiss) language.
OUT_German
German language.
OUT_German_Swiss
German (Swiss) language.
OUT_Greek
Greek language.
OUT_Hungarian
Hungarian language.
OUT_Icelandic
Icelandic language.
OUT_Italian
Italian language.
OUT_Italian_Swiss
Italian (Swiss) language.
OUT_Norwegian
Norwegian language.
OUT_Portuguese_Brazilian
Portuguese (Brazilian) language.
OUT_Portuguese
Portuguese language.
OUT_Rhaeto_Romanic
Rhaeto-Romanic language.
OUT_Romanian
Romanian language.
OUT_Slovak
Slovak language.
OUT_Spanish_Castilian
Spanish (Castilian) language.
OUT_Spanish_Mexican
Spanish (Mexican) language.
OUT_Swedish
Swedish language.
OUT_Turkish
Turkish language.
OUT_Serbo_Croatian_Cyrillic
Serbian (Cyrillic) language.
OUT_Bulgarian
Bulgarian (Cyrillic) language.
OUT_Russian
Russian (Cyrillic) language.


OUTPUTLEVEL

Group: Enumeration

Description:

This enumeration identifies formatting detail level for the output document.

Values:

FULLFORMAT
All formatting retained, including text zoning, if applicable. It keeps the original layout of the pages, including columns. This is done with text, graphical and table zones and frames. This is offered only for target applications capable of handling these.
PARTFORMAT
Partial set of output formatting elements are retained. All of the recognized paragraph and character formatting features will be exported, if applicable.All recognized paragraph and character formatting features along with graphics and tables are exported.
DROPFORMAT
Only some character formatting properties (font size and name) will be exported, if applicable.When exporting to text file types, graphics and tables are not supported.
RFC
Not supported


OUTPUTLINESPACE

Group: Enumeration

Description:

This enumeration identifies line spacing modes for the output document.

Values:

OUT_HALF
Half line spacing.
OUT_ONE
One line spacing.
OUT_ONEANDHALF
One and a half line spacing.
OUT_DOUBLE
Double line spacing.


OUTPUTPAPERORIENTATION

Group: Enumeration

Description:

This enumeration identifies paper orientation modes for the output document.

Values:

IG_REC_OUTPUT_PAPER_ORIENT_PORTRAIT
Portrait orientation
IG_REC_OUTPUT_PAPER_ORIENT_LANDSCAPE
Landscape orientation


OUTPUTPAPERSIZE

Group: Enumeration

Description:

This enumeration identifies paper sizes for the output document.

Values:

OUT_A4
A4 paper size (default).
OUT_A0
A0 paper size.
OUT_A1
A1 paper size.
OUT_A2
A2 paper size.
OUT_A3
A3 paper size.
OUT_A5
A5 paper size.
OUT_A6
A6 paper size.
OUT_A7
A7 paper size.
OUT_B0
B0 paper size.
OUT_B1
B1 paper size.
OUT_B2
B2 paper size.
OUT_B3
B3 paper size.
OUT_B4
B4 paper size.
OUT_B5
B5 paper size.
OUT_B6
B6 paper size.
OUT_B7
B7 paper size.
OUT_LETTER
Letter paper size.
OUT_LEGAL
Legal paper size.
OUT_EXECUTIVE
Executive paper size.
OUT_FROMIMAGEMAX
A unique paper size will be determined from the original images of the document and this will be exported into the final output document.


OUTPUTSWITCH

Group: Enumeration

Description:

This general purpose enum type is used for different output text properties to indicate how they should be handled.

Values:

OUT_NONE
The property will not be exported to the final output document, i.e. even if the final output document supports the particular property, it won't be sent to the document.
OUT_AUTO
The property will be calculated automatically and will be exported to the final output document. This usually mirrors the properties of the original document.
OUT_PREDEFINED
The property will take a programmed value and be exported to the final output document.


OUTPUTTABLEMETHOD

Group: Enumeration

Description:

This enumeration identifies table handling modes for the output document.

Values:

OUT_TABLEUSETABS
Export the recognized table-zones by exporting TAB positions and TAB characters into the final output document.
OUT_TABLEUSECELLS
Export the recognized table-zones as table objects with a row-and-column cell structure into the final output document.


OUTPUTTXTTYPE

Group: Enumeration

Description:

This enumeration identifies output format types, such as plain text, word processor, etc.

Values:

PLAIN
Plain text: only characters, without any formatting information
WP
Word processor output: formatted text
TRUEWP
Sophisticated word processor output: formatted text with images, if requested
_TABLE
Spreadsheet output
_UNKNOWN
Unknown output. The selected output converter is unknown for the ImageGear Recognition component.


PROCESSID

Group: Enumeration

Description:

This enumeration identifies processes of the recognition engine.

Values:

PID_IMGINPUT
This identifies the Image importing process
PID_IMGSAVE
This identifies the image saving process. During this process the image or a part of it is saved to an image file.
PID_IMGPREPROCESS
This identifies the Image pre-processing process.
PID_DECOMPOSITION
This identifies the page-layout decomposition (auto-zoning) process.
PID_RECOGNITION1
This identifies the 1st pass of the Recognition process, if applicable.
PID_RECOGNITION2
This identifies the 2nd pass of the Recognition process, if applicable.
PID_SPELLING
This identifies the Checking process.
PID_READRDF
This identifies reading from the recognition data file.
PID_WRITEFOUTDOC
This identifies the process for writing the recognized text to the final output document (to file or memory).
PID_CONVERTIMG
This identifies the image conversion process activated by the PID_WRITEFOUTDOC process for saving the image of a graphical image zone to the final output document (if this was requested).
PID_RECOGNITION3
This identifies the 3rd pass of the Recognition process. This pass is applicable only for the Omnifont PLUS3W recognition module.
PID_SCANNER_WARMUP
Not available


RECOGNITIONMODULE

Group: Enumeration

escription:

This enumeration identifies recognition modules of the ScanSoft recognition engine.

Values:

RM_AUTO
Specifies that the Recognition component will try to automatically select the most suitable recognition module for the zone. The recognition module to be applied is determined just before recognition, primarily by inquiring the filling method and other settings, most typically the Character Set.
RM_OMNIFONT_MTX
Specifies the M/TEXT omnifont module.
RM_OMNIFONT_MOR
Specifies the multi-lingual MOR omnifont module.
RM_DOT
Specifies the DOT 9-pin draft dot-matrix module.
RM_BAR
Specifies the BAR bar code module.
RM_OMR
Specifies the OMR optical mark module.
RM_HNR
Specifies the HNR handprinted numeral module.
RM_RER
Specifies the third-party RER reRecognition Handprint module.
RM_BRA
Not available
RM_MAT
Specifies the MAT matrix matching module.
RM_BAR2D
Specifies the third-party 2D bar code module.
RM_OMNIFONT_PLUS2W
Specifies the two-way voting POWR++ omnifont recognition module.
RM_OMNIFONT_FRX
Specifies the FireWorX omnifont recognition module.
RM_OMNIFONT_PLUS3W
Specifies the most accurate three-way voting omnifont recognition module.
RM_ASIAN
Not available
RM_SIZE
Number of recognition modules


RMTRADEOFF

Group: Enumeration

Description:

This enumeration identifies recognition tradeoff modes.

Values:

TO_ACCURATE
Most accurate recognition.
TO_BALANCED
Mid-level accuracy/speed recognition.
TO_FAST
Fast recognition.


TWAIN Component API Function Reference

In this Chapter you can get the detailed information about all ImageGear TWAIN component functions and callbacks:

  • TWAIN Component Functions Reference
  • TWAN Component Callback Functions Reference
  • TWAIN Component Enumerations
See Also:

Appendix: TWAIN Scanning Capabilities


TWAIN Component Functions Reference

For the detailed description how to use ImageGear Twain Component please see Using ImageGear Twain Component section in Using ImageGear Chapter.

Please see below the detailed description of Twain functions.


IG_TWAIN_acquire

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_acquire(
LPHIGEAR lphIGear,
AT_BOOL bShowUI)

Arguments:

lphIGear
Far pointer to HIGEAR object in which to return ImageGear handle of the acquired image
bShowUI
This flag determines whether or not the user interface is shown. Set to TRUE if you want ImageGear to obtain the capability settings from the end-user.

Description:

This function acquires a single image from the selected TWAIN device. A DIB will be built to hold the acquired image, and its ImageGear handle will be returned through the lphIGear argument.

Use IG_TWAIN_source_open () to select the desired Data Source, and IG_TWAIN_cap_set () to set desired capabilities values, prior to calling this function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_auto_capture

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_auto_capture(
LONG lImageCount,
LONG lTimeBeforeFirstCapture,
LONG lTimeBetweenCaptures,
LPCSTR lpszImageDirName)

Arguments:

lImageCount
The number of images to be captured.
lTimeBeforeFirstCapture
The number of milliseconds before the first picture is to be taken, or the first image is to be scanned.
lTimeBetweenCaptures
The number of milliseconds to wait between pictures taken or images scanned.
lpszImageDirName
The destination directory within the Source (camera, storage, etc), where captured images will be stored.

Description:

This function automatically captures images from the selected TWAIN device. The captured images are stored on the device in lpszImageDirName directory and can be retrieved through browsing the file system.

Use IG_TWAIN_source_open () to select the desired Data Source, and IG_TWAIN_cap_set () to set desired capabilities values, prior to calling this function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_array_size_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_array_size_get(
HTWAINCAP hTWAINCap,
LPDWORD lpArraySize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpArraySize
Pointer to a DWORD that receives the array size.

Description:

This function gets the size of the array of a capability. Applicable to TW_ON_ARRAY and TW_ON_ENUMERATION containers.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_array_value_add

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_array_value_add(
HTWAINCAP hTWAINCap,
LPCVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that contains the value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function adds an element to the end of the array of a capability. Applicable to TW_ON_ARRAY and TW_ON_ENUMERATION containers.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_array_value_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_array_value_get(
HTWAINCAP hTWAINCap,
DWORD dwIndex,
LPVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
dwIndex
The position of the array element to get.
lpValue
Pointer to a memory buffer that receives the capability value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function gets an element of the array of a capability. Applicable to TW_ON_ARRAY and TW_ON_ENUMERATION containers.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_array_value_set

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_array_value_set(
HTWAINCAP hTWAINCap,
DWORD dwIndex,
LPCVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
dwIndex
The position of the array element to set.
lpValue
Pointer to a memory buffer that contains the value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function sets an element of the array of a capability. Applicable to TW_ON_ARRAY and TW_ON_ENUMERATION containers.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_container_type_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_container_type_get(
HTWAINCAP hTWAINCap,
LPAT_MODE lpContainerType)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpContainerType
Capability container type. Can be one of the following values:
IG_TW_ON_ONEVALUE - A single value whose current and default values are coincident. The range of available values for this type of capability is simply this single value. For example, a capability that indicates the presence of a document feeder could be of this type.
IG_TW_ON_ARRAY - A rectangular array of values that describe a logical item. It is similar to the IG_TW_ON_ONEVALUE because the current and default values are the same and there are no other values to select from. For example, a list of the names, such as the supported capabilities list returned by the IG_TW_CAP_SUPPORTEDCAPS capability, would use this type of container.
IG_TW_ON_ENUMERATION - This is the most general type because it defines a list of values from which the Current Value can be chosen. The values do not progress uniformly through a range and there is not a consistent step size between the values. For example, if a Source's resolution options did not occur in even step sizes then an enumeration would be used (for example, 150, 400, and 600).
G_TW_ON_RANGE - Many capabilities allow users to select their current value from a range of regularly spaced values. The capability can specify the minimum and maximum acceptable values and the incremental step size between values. For example, resolution might be supported from 100 to 600 in steps of 50 (100, 150, 200, ..., 550, 600).

Description:

This function gets the type of a capability container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_create

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_create(
AT_LMODE nCap,
AT_MODE nContainerType,
AT_MODE nItemType,
LPHTWAINCAP lphTWAINCap)

Arguments:

nCap
The numeric designator of the capability (of the form IG_TW_CAP_xxxx, IG_TW_ICAP_xxxx, or IG_TW_ACAP_xxxx).
nContainerType
Capability container type. Can be one of the following values:
IG_TW_ON_ONEVALUE - A single value whose current and default values are coincident. The range of available values for this type of capability is simply this single value. For example, a capability that indicates the presence of a document feeder could be of this type.
IG_TW_ON_ARRAY - A rectangular array of values that describe a logical item. It is similar to the IG_TW_ON_ONEVALUE because the current and default values are the same and there are no other values to select from. For example, a list of the names, such as the supported capabilities list returned by the IG_TW_CAP_SUPPORTEDCAPS capability, would use this type of container.
IG_TW_ON_ENUMERATION - This is the most general type because it defines a list of values from which the Current Value can be chosen. The values do not progress uniformly through a range and there is not a consistent step size between the values. For example, if a Source's resolution options did not occur in even step sizes then an enumeration would be used (for example, 150, 400, and 600).
IG_TW_ON_RANGE - Many capabilities allow users to select their current value from a range of regularly spaced values. The capability can specify the minimum and maximum acceptable values and the incremental step size between values. For example, resolution might be supported from 100 to 600 in steps of 50 (100, 150, 200, ..., 550, 600).
nItemType
Capability data type. Can be one of the following values:
AM_TID_META_INT8
AM_TID_META_UINT8
AM_TID_META_INT16
AM_TID_META_UINT16
AM_TID_META_INT32
AM_TID_META_UINT32
AM_TID_META_BOOL
AM_TID_META_DOUBLE
AM_TID_META_STRING32
AM_TID_META_STRING64
AM_TID_META_STRING128
AM_TID_META_STRING255
AM_TID_META_STRING1024
AM_TID_META_STRING_UNICODE512
AM_TID_META_DRECT
lphTWAINCap
Handle to the created capability container. References the container structure where detailed information about the capability is stored.

Description:

This function creates a new capability container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_current_value_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_current_value_get(
HTWAINCAP hTWAINCap,
LPVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that receives the capability value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function gets the current value of a capability from its container. Applicable to TW_ON_ENUMERATION and TW_ON_RANGE containers.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_current_value_set

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_current_value_set(
HTWAINCAP hTWAINCap,
LPCVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that contains the value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function sets the current value of a capability in its container. Applicable to TW_ON_ENUMERATION and TW_ON_RANGE containers.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_default_value_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_default_value_get(
HTWAINCAP hTWAINCap,
LPVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that receives the capability value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function gets the default value of a capability from its container. Applicable to TW_ON_ENUMERATION and TW_ON_RANGE containers.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_default_value_set

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_default_value_set(
HTWAINCAP hTWAINCap,
LPCVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that contains the value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function sets the default value of a capability in its container. Applicable to TW_ON_ENUMERATION and TW_ON_RANGE containers.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_delete

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_delete(
HTWAINCAP hTWAINCap)

Arguments:

hTWAINCap
Handle to a capability container. References the container structure where detailed information about the capability is stored.

Description:

This function deletes a capability container and frees all resources associated with it.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_get(
AT_LMODE nCap,
AT_MODE nMsgId,
LPHTWAINCAP lphTWAINCap)

Arguments:

nCap
The numeric designator of the capability (of the form IG_TW_CAP_xxxx, IG_TW_ICAP_xxxx, or IG_TW_ACAP_xxxx).
nMsgId
Message ID. Can be one of the following values:
IG_TW_MSG_GET - Get one or more capability values.
IG_TW_MSG_GETCURRENT - Get current capability value.
IG_TW_MSG_GETDEFAULT - Get default (e.g. power up) capability value.
lphTWAINCap
Handle to the container of the requested capability. References the container structure where detailed information about the capability is stored.

Description:

This function gets information about a capability from a Data Source.

Use IG_TWAIN_source_open () to select the desired Data Source, prior to calling this function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_id_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_id_get(
HTWAINCAP hTWAINCap,
LPAT_MODE lpCapId)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpCapId
The numeric designator of the capability (of the form IG_TW_CAP_xxxx, IG_TW_ICAP_xxxx, or IG_TW_ACAP_xxxx).

Description:

This function gets the numeric designator of a capability from its container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_is_valid

Group: TWAIN Component

Declaration:

AT_BOOL ACCUAPI IG_TWAIN_cap_is_valid(
HTWAINCAP hTWAINCap)

Arguments:

hTWAINCap
Handle to a capability container. References the container structure where detailed information about the capability is stored.

Description:

This function checks whether the handle to a capability container is valid.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_item_type_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_item_type_get(
HTWAINCAP hTWAINCap,
LPAT_MODE lpItemType)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpItemType
Capability data type. Can be one of the following values:
AM_TID_META_INT8
AM_TID_META_UINT8
AM_TID_META_INT16
AM_TID_META_UINT16
AM_TID_META_INT32
AM_TID_META_UINT32
AM_TID_META_BOOL
AM_TID_META_DOUBLE
AM_TID_META_STRING32
AM_TID_META_STRING64
AM_TID_META_STRING128
AM_TID_META_STRING255
AM_TID_META_STRING1024
AM_TID_META_STRING_UNICODE512
AM_TID_META_DRECT

Description:

This function gets the data type of a capability from its container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_max_value_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_max_value_get(
HTWAINCAP hTWAINCap,
LPVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that receives the capability value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function gets the maximum value of a capability from its container. Applicable to TW_ON_RANGE container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_max_value_set

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_max_value_set(
HTWAINCAP hTWAINCap,
LPCVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that contains the value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function sets the maximum value of a capability in its container. Applicable to TW_ON_RANGE container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_min_value_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_min_value_get(
HTWAINCAP hTWAINCap,
LPVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that receives the capability value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function gets the minimum value of a capability from its container. Applicable to TW_ON_RANGE container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_min_value_set

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_min_value_set(
HTWAINCAP hTWAINCap,
LPCVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that contains the value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function sets the minimum value of a capability in its container. Applicable to TW_ON_RANGE container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_reset

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_reset(
HTWAINCAP hTWAINCap,
AT_MODE nCap,
AT_MODE nItemType)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
nCap
The numeric designator of the capability (of the form IG_TW_CAP_xxxx, IG_TW_ICAP_xxxx, or IG_TW_ACAP_xxxx).
nItemType
Capability data type. Can be one of the following values:
AM_TID_META_INT8
AM_TID_META_UINT8
AM_TID_META_INT16
AM_TID_META_UINT16
AM_TID_META_INT32
AM_TID_META_UINT32
AM_TID_META_BOOL
AM_TID_META_DOUBLE
AM_TID_META_STRING32
AM_TID_META_STRING64
AM_TID_META_STRING128
AM_TID_META_STRING255
AM_TID_META_STRING1024
AM_TID_META_STRING_UNICODE512
AM_TID_META_DRECT

Description:

This function changes the id and item type of a capability and reallocates the container's memory according to the new item type.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_set

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_set(
HTWAINCAP hTWAINCap,
AT_MODE nMsgId)

Arguments:

hTWAINCap
Handle to a capability container. References the container structure where detailed information about the capability is stored.
nMsgId
Message ID. Can be one of the following values:
IG_TW_MSG_SET - Set one or more capability values.
IG_TW_MSG_RESET - Set current capability value to default value.
ä

Description:

This function sets or resets the current value of a capability.

Use IG_TWAIN_source_open () to select the desired Data Source, prior to calling this function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_step_value_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_step_value_get(
HTWAINCAP hTWAINCap,
LPVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that receives the capability value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function gets the step value of a capability from its container. Applicable to TW_ON_RANGE container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_step_value_set

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_step_value_set(
HTWAINCAP hTWAINCap,
LPCVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that contains the value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function sets the step value of a capability in its container. Applicable to TW_ON_RANGE container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_value_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_value_get(
HTWAINCAP hTWAINCap,
LPVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that receives the capability value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function gets the value of a capability from its container. Applicable to TW_ON_ONEVALUE container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_cap_value_set

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_cap_value_set(
HTWAINCAP hTWAINCap,
LPCVOID lpValue,
DWORD dwValueSize)

Arguments:

hTWAINCap
Handle to the capability container. References the container structure where detailed information about the capability is stored.
lpValue
Pointer to a memory buffer that contains the value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function sets the value of a capability in its container. Applicable to TW_ON_ONEVALUE container.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_CB_register

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_CB_register(
LPVOID lpfnTwainCB,
AT_MODE nCBType,
LPVOID lpData)

Arguments:

lpfnTwainCB
A FAR pointer to the scan callback function you would like to register
nCBType
Set to the type of callback being registered. Use one of the following ImageGear-defined constants:
IG_TW_CBT_BEFORE_PAGE
IG_TW_CBT_AFTER_TRANSFORM_PAGE
IG_TW_CBT_BEFORE_DOC
IG_TW_CBT_AFTER_DOC
IG_TW_CBT_CAP_SET_5
IG_TW_CBT_DEVICE_EVENT
lpData
Optional pointer to pass and receive data from. Set to NULL if you don't need to do this

Description:

This function registers one of the seven available scan callback functions.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_ctrl_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_ctrl_get(
AT_MODE nParamId,
LPVOID lpValue,
DWORD dwValueSize)

Arguments:

nParamId
Control parameter Id. Can be one of the following values:
IG_TW_CTRL_APP_NAME
IG_TW_CTRL_IMAGE_FILE_NAME
IG_TW_CTRL_AUDIO_FILE_NAME
IG_TW_CTRL_SAVE_PAGES_SEPARATELY
lpValue
Pointer to a memory buffer that receives the control parameter value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function gets the value of a TWAIN control parameter.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_ctrl_set

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_ctrl_set(
AT_MODE nParamId,
LPCVOID lpValue,
DWORD dwValueSize)

Arguments:

nParamId
Control parameter Id. Can be one of the following values:
IG_TW_CTRL_APP_NAME
IG_TW_CTRL_IMAGE_FILE_NAME
IG_TW_CTRL_AUDIO_FILE_NAME
IG_TW_CTRL_SAVE_PAGES_SEPARATELY
lpValue
Pointer to a memory buffer that contains the control parameter value.
dwValueSize
The size of memory allocated for lpValue pointer.

Description:

This function sets the value of a TWAIN control parameter.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_driver_info_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_driver_info_get(
LPINT lpVerMajor,
LPINT lpVerMinor)

Arguments:

lpVerMajor
Major release version number of the TWAIN-compliant device
lpVerMinor
Minor release version number of the TWAIN-compliant device

Description:

This function returns the major and minor release version numbers of the TWAIN-compliant image acquisition device. ImageGear currently supports version 1.9 and below. Depending on the results of your query, you may want to display a warning that unexpected results may occur if the version of the TWAIN-compliant device is not one of these versions.

If no TWAIN DLL is currently installed, you will receive an error.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_file_change_dir

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_file_change_dir(
LPCSTR lpszDirName)

Arguments:

lpszDirName
The name of directory.

Description:

This function selects the current device within the Data Source (camera, storage, etc). If the device is a IG_TW_FY_DOMAIN, then this command enters a directory that can contain IG_TW_FY_HOST files. If the device is a IG_TW_FY_HOST, then this command enters a directory that can contain IG_TW_FY_DIRECTORY files. If the device is a IG_TW_FY_DIRECTORY, then this command enters a directory that can contain IG_TW_FY_DIRECTORY or IG_TW_FY_IMAGE files.

Use IG_TWAIN_source_open () to select the desired Data Source.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_file_close

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_file_close(
LPAT_TWAIN_FILEINFO lpFileInfo)

Arguments:

lpFileInfo
Pointer to an AT_TWAIN_FILEINFO structure associated with the file system context.

Description:

This function closes the file system context associated with lpFileInfo. Every call to IG_TWAIN_file_get_first () must be matched by a call to IG_TWAIN_file_close() to release the file system context.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_file_copy

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_file_copy(
LPCSTR lpszDest,
LPCSTR lpszSrc,
AT_BOOL bRecursive)

Arguments:

lpszDest
The path to the destination file/directory.
lpszSrc
The path to the source file/directory.
bRecursive
Specifies whether the copying is recursive or not.

Description:

This function copies the specified file from one directory to another. If the bRecursive flag is TRUE and the file type specified is IG_TW_FY_DIRECTORY, then that directory, and all the files and directories under it, are copied. The application cannot copy files into the root directory.

Use IG_TWAIN_source_open () to select the desired Data Source.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_file_create_dir

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_file_create_dir(
LPCSTR lpszDirName)

Arguments:

lpszDirName
The name of directory.

Description:

This function creates a new directory within the current directory. Pathnames are not allowed, only the name of the new directory can be specified.

Use IG_TWAIN_source_open () to select the desired Data Source.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_file_delete

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_file_delete(
LPCSTR lpszFileName,
AT_BOOL bRecursive)

Arguments:

lpszFileName
The name of file to delete.
bRecursive
Specifies whether it is recursive deleting or not.

Description:

This function deletes a file or directory on the device. Pathnames are not allowed, only the name of the file or directory to be deleted can be specified. Recursive deletion can be specified by setting the bRecursive to TRUE.

Use IG_TWAIN_source_open () to select the desired Data Source.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_file_format_media

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_file_format_media(
LPCSTR lpszDeviceName)

Arguments:

lpszDeviceName
The name of the scanning device.

Description:

This function formats the specified storage. This operation destroys all images and subdirectories under the selected device. Use with caution!

Use IG_TWAIN_source_open () to select the desired Data Source.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_file_get_first

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_file_get_first(
LPAT_TWAIN_FILEINFO lpFileInfo)

Arguments:

lpFileInfo
Pointer to an AT_TWAIN_FILEINFO structure that receives information about the first file in a directory.

Description:

This function gets the first filename in a directory and returns information about that file (the same information that can be retrieved with IG_TWAIN_file_info_get ()). The Data Source positions the file system context to point to the first filename. lpFileInfo->szName contains the absolute path and name of the file. If the Application calls IG_TWAIN_file_get_image (), the current image will be transferred. Applications must not assume any ordering of the files delivered by the Data Source, with one exception: if IG_TWAIN_file_get_first() is called in the root directory, the operation must return an IG_TW_FY_CAMERA device.

Use IG_TWAIN_source_open () to select the desired Data Source.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_file_get_image

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_file_get_image(
LPHIGEAR lphIGear,
LPFNIG_TWAIN_AFTER_AUDIO_SNIPPET lpfnAfterSnippet,
LPVOID lpAfterSnippetData,
AT_MODE nFlags)

Arguments:

lphIGear
Far pointer to HIGEAR object in which to return ImageGear handle of the acquired image.
lpfnAfterSnippet
Far pointer to a callback function that will be called after each audio snippet is acquired.
lpAfterSnippetData
Optional pointer to pass and receive data from. Set to NULL if you don't need to do this.
nFlags
Specifies the type of data to transfer. Can be one of the following values:
IG_TW_IMAGE - transfer the current image.
IG_TW_AUDIO - transfer the audio snippets associated with the current image.

Description:

This function retrieves the image that the device's file system context currently points to. Use IG_TWAIN_file_get_first () and IG_TWAIN_file_get_next () to select the file you want to transfer from the device's file system.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_file_get_next

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_file_get_next(
LPAT_TWAIN_FILEINFO lpFileInfo)

Arguments:

lpFileInfo
Pointer to an AT_TWAIN_FILEINFO structure that receives information about the next file in a directory.

Description:

This function gets the next filename in a directory, and returns information about that file (the same information that can be retrieved with IG_TWAIN_file_info_get ()). The Data Source positions the file system context to point to the next filename. lpFileInfo->szName contains the absolute path and name of the file. If the Application calls IG_TWAIN_file_get_image (), the current image will be transferred. A call to IG_TWAIN_file_get_first () must be issued on a given directory before the first call to IG_TWAIN_file_get_next().

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_file_info_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_file_info_get(
LPCSTR lpszFileName,
LPAT_TWAIN_FILEINFO lpFileInfo)

Arguments:

lpszFileName
The name of the file to get information about.
lpFileInfo
Pointer to an AT_TWAIN_FILEINFO structure that receives information about the requested file.

Description:

This function gets information about the requested file.

Use IG_TWAIN_source_open () to select the desired Data Source.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_file_rename

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_file_rename(
LPCSTR lpszOldName,
LPCSTR lpszNewName)

Arguments:

lpszOldName
The name of the file/directory to be renamed.
lpszNewName
The new name of the file/directory.

Description:

This function renames (and optionally moves) a file or directory. Absolute and relative path names are supported. A file may not be overwritten with this command. If an Application wishes to do this, it must first delete the unwanted file, then issue the rename command. Filenames in the root directory cannot be moved or renamed.

Use IG_TWAIN_source_open () to select the desired Data Source.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_image_layout_get

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_image_layout_get(LPAT_DRECT
rcdImgRect)

Arguments:

rcdImgRect
Pointer to an AT_DRECT representing the physical bounding box of the region to be acquired.

Description:

This function gets the image layout of the selected TWAIN device. You can use this to limit your capture region to a portion of the device's total area. The units are in inches by default. You can set the IG_TW_ICAP_UNITS capability to choose different units.

Use IG_TWAIN_source_open () to select the desired Data Source prior to calling this function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_image_layout_set

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_image_layout_set(LPAT_DRECT
rcdImgRect);

Arguments:

rcdImgRect
Pointer to an AT_DRECT representing the physical bounding box of the region to be acquired.

Description:

This function sets the image layout of the selected TWAIN device. You can use this to limit your capture region to a portion of the device's total area. The units are in inches by default. You can set the IG_TW_ICAP_UNITS capability to choose different units.

Use IG_TWAIN_source_open () to select the desired Data Source prior to calling this function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_preview

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_preview(
LPFNIG_TWAIN_AFTER_PAGE lpfnAfterPage,
LPVOID lpAfterPageData,
AT_BOOL bShowUI)

Arguments:

lpfnAfterPage
Far pointer to a callback function that will be called after each page is acquired.
lpAfterPageData
Optional pointer to pass and receive data from. Set to NULL if you don't need to do this.
bShowUI
This flag determines whether or not the user interface is shown. Set to TRUE if you want Data Source to display preview user interface.

Description:

This function acquires camera preview images from the selected TWAIN device. An example use is to retrieve previews of images stored within a digital camera. The function uses lpfnAfterPage callback function to deliver the acquired images.

Use IG_TWAIN_source_open () to select the desired Data Source, and IG_TWAIN_cap_set () to set desired capabilities values, prior to calling this function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_scan_pages

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_scan_pages(
LPFNIG_TWAIN_AFTER_PAGE lpfnAfterPage,
LPVOID lpAfterPageData,
AT_BOOL bShowUI)

Arguments:

lpfnAfterPage
Far pointer to a callback function that will be called after each page is acquired.
lpAfterPageData
Optional pointer to pass and receive data from. Set to NULL if you don't need to do this.
bShowUI
This flag determines whether or not the user interface is shown. Set to TRUE if you want ImageGear to obtain the capability settings from the end-user.

Description:

This function is used to scan multiple pages from a scanner equipped with an Automatic Document Feeder (ADF). The function uses lpfnAfterPage callback function to deliver the acquired images.

Use IG_TWAIN_source_open () to select the desired Data Source, and IG_TWAIN_cap_set () to set desired capabilities values, prior to calling this function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_scan_pages_to_file

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_scan_pages_to_file(
LPCSTR lpszFileName,
AT_LMODE nFileFormat,
AT_BOOL bShowUI)

Arguments:

lpszFileName
Far pointer to HIGEAR object in which to return ImageGear handle of the acquired image
nFileFormat
Type of format and compression scheme of file that will be created. accucnst.h contains definitions for formats and compression schemes that have already been "OR'd" together.
bShowUI
This flag determines whether or not the user interface is shown. Set to TRUE if you want ImageGear to obtain the capability settings from the end-user.

Description:

This function is used to scan multiple pages from a scanner equipped with an Automatic Document Feeder (ADF).

If lpszFileName specifies only a directory but not a file name, a separate file for each page will be created, using the names 0000001.tif, 00000002.tif, 00000003.tif, etc. If those files already exist, they will be deleted before being scanned into.

If lpszFileName specifies a filename and IG_TW_CTRL_SAVE_PAGES_SEPARATELY is set to TRUE, a separate file for each page will be created, but will use part of the name that you supplied. If the name you supplied was "ScanTest.bmp", your pages will be named as follows: ScanTest1.bmp, ScanTest2.bmp, ScanTest3.bmp ... ScanTest10.bmp, ScanTest11.bmp, etc. If these files already exist, they will be deleted before being scanned into.

If IG_TW_CTRL_SAVE_PAGES_SEPARATELY is FALSE and nFileFormat is set to a format type that supports multiple pages, such as TIFF, DCX, or MO:DCA, the images are stored in one file identified by the lpszFileName parameter.

Use IG_TWAIN_source_open () to select the desired Data Source, and IG_TWAIN_cap_set () to set desired capabilities values, prior to calling this function.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_source_close

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_source_close()

Description:

This function closes the currently opened Data Source. When an application is finished with a Data Source, it must formally close the session between them using this function. This is necessary in case the Data Source only supports connection with a single application (many desktop scanners will behave this way). A Data Source such as this cannot be accessed by other applications until its current session is terminated.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_source_get_default

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_source_get_default(
HWND hMainWnd,
LPSTR lpszDSName)

Arguments:

hMainWnd
The handle of the main window in the application.
lpszDSName
Returns a string identifying which Data Source is currently the default. You must allocate the memory for this string. Please allow 34 characters per the TWAIN restriction.

Description:

This function returns the name of the current or "default" Data Source. The "default" Data Source is the source that was either last opened or installed. Initially, one of your TWAIN devices will be active by default. The default Data Source may be reset by calling the function IG_TWAIN_source_open().

Used in conjunction with IG_TWAIN_source_get_first() and IG_TWAIN_source_get_next(), you can implement your own version of TWAIN's "SelectSource" dialog box, adding customized enhancements or sophistication.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_source_get_first

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_source_get_first(
HWND hMainWnd,
LPSTR lpszDSName)

Arguments:

hMainWnd
The handle of the main window in the application.
lpszDSName
Returns a string identifying which Data Source is the first one detected. You must allocate the memory for this string. Please allow 34 characters per the TWAIN restriction.

Description:

This function returns the name of the first Data Source detected.

Used in conjunction with IG_TWAIN_source_get_next (), you can implement your own version of TWAIN's "SelectSource" dialog box, adding customized enhancements or sophistication.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_source_get_next

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_source_get_next(
HWND hMainWnd,
LPSTR lpszDSName)

Arguments:

hMainWnd
The handle of the main window in the application.
lpszDSName
Returns a string identifying the next Data Source detected. You must allocate the memory for this string. Please allow 34 characters per the TWAIN restriction.

Description:

This function returns the name of the next Data Source detected. You should precede your first call to IG_TWAIN_source_get_next() with a call to IG_TWAIN_source_get_first ().

Used in conjunction with IG_TWAIN_source_get_first (), you can implement your own version of TWAIN's "SelectSource" dialog box, adding customized enhancements or sophistication.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


IG_TWAIN_source_open

Group: TWAIN Component

Declaration:

AT_ERRCOUNT ACCUAPI IG_TWAIN_source_open(
HWND hMainWnd,
LPCSTR lpszDSName,
AT_BOOL bShowUI)

Arguments:

hMainWnd
The handle of the main window in the application.
lpszDSName
The name of the Data Source to open.
bShowUI
If set to TRUE and lpszDSName is NULL a call to this function will cause Data Source Manager to display the default source selection dialog.

Description:

This function loads the specified Data Source into main memory and causes its initialization.

If lpszDSName is NULL and bShowUI is set to TRUE a call to this function will cause Data Source Manager to display the default source selection dialog.

If lpszDSName is NULL and bShowUI is set to FALSE the default Data Source will be opened.

If lpszDSName is a name of an existing Data Source the specified Data Source will be opened.

When an application is finished with the Data Source, call IG_TWAIN_source_close () to close the session between them.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.


TWAN Component Callback Functions Reference

ImageGear TWAIN Component provides the following callback functions:

  • LPFNIG_TWAIN_AFTER_AUDIO_SNIPPET
  • LPFNIG_TWAIN_AFTER_DOC
  • LPFNIG_TWAIN_AFTER_PAGE
  • LPFNIG_TWAIN_AFTER_TRANSFORM_PAGE
  • LPFNIG_TWAIN_BEFORE_DOC
  • LPFNIG_TWAIN_BEFORE_PAGE
  • LPFNIG_TWAIN_CAP_SET_5
  • LPFNIG_TWAIN_DEVICE_EVENT


LPFNIG_TWAIN_AFTER_AUDIO_SNIPPET

Group: TWAIN Component

Declaration:

typedef LONG (LPACCUAPI LPFNIG_TWAIN_AFTER_AUDIO_SNIPPET)(
LONG nSnippetNum,
LPCSTR lpszAudioDataName,
LPCVOID lpAudioData,
LONG nPendCount,
LPCSTR lpszFileName,
LPVOID lpData);

Arguments:

nSnippetNum
The number of the audio snippet just acquired; the first snippet is 1.
lpszAudioDataName
The name of audio data.
lpAudioData
A pointer to the acquired audio snippet.
nPendCount
The number of pending audio snippets left to be acquired.
lpszFileName
If you are using Native Transfer Syntax, this will be the filename given to the snippet that was just acquired. If you are using Disk File Transfer, this was the name given to the snippet that was just acquired.
lpData
A far pointer to private data, as specified in your call to IG_TWAIN_file_get_image() function.

Description:

This callback function, if registered, will be called by ImageGear after each audio snippet has been acquired using the IG_TWAIN_file_get_image () function.

Return Value:

Return 1 if you want to continue acquisition of audio snippets; return 0 to cancel the acquisition after saving the snippet just acquired.


LPFNIG_TWAIN_AFTER_DOC

Group: TWAIN Component

Declaration:

typedef LONG (LPACCUAPI LPFNIG_TWAIN_AFTER_DOC)(
LONG nPageCount,
LONG nADFLoaded,
LPVOID lpData)

Arguments:

nPageCount
The number of pages that were scanned into one document.
nADFLoaded
Returns the status of the paper supply in the ADF (if an ADF is being used). The following values can be returned:
0 - ADF is empty
1 - ADF still contains paper
-1 - TWAIN does not know whether or not the ADF contains paper (i.e. an error is occured).
lpData
A far pointer to private data, as specified in your call to IG_TWAIN_CB_register() function.

Description:

This callback, if registered, will be called by ImageGear after all the pages of a document have been scanned, processed and/or saved. It allows you to find out how many pages have been scanned so far, and what is the status of the paper availability in the ADF.

Return Value:

Set the return value to 0 to return control to ImageGear.


LPFNIG_TWAIN_AFTER_PAGE

Group: TWAIN Component

Declaration:

typedef LONG (LPACCUAPI LPFNIG_TWAIN_AFTER_PAGE)(
LONG nPageNum,
HIGEAR hIGear,
LONG nPendCount,
LPCSTR lpszFileName,
LPVOID lpData);

Arguments:

nPageNum
The number of the page just scanned; the first page is 1.
hIGear
HIGEAR handle to the image just scanned.
nPendCount
The number of pending pages left to be scanned. In the TWAIN lexicon, "pending" refers to how many pages are left in the ADF or in the digital camera. TWAIN requires that the Data Source let it know how many pages are "pending".
lpszFileName
If you are using Native or Buffered Memory Transfer Syntax, this will be the filename given to the page that was just scanned. If you are using Disk File Transfer, this was the name given to the page that was just scanned.
lpData
A far pointer to private data, as specified in your call to IG_TWAIN_scan_pages() or IG_TWAIN_preview() function.

Description:

This callback function, if registered, will be called by ImageGear after each page has been acquired using the IG_TWAIN_scan_pages () and IG_TWAIN_preview () functions.

Return Value:

Return 1 if you want to continue scanning; return 0 to cancel the scanning process after saving the page just scanned.


LPFNIG_TWAIN_AFTER_TRANSFORM_PAGE

Group: TWAIN Component

Declaration:

typedef LONG (LPACCUAPI LPFNIG_TWAIN_AFTER_TRANSFORM_PAGE)(
LONG nPageNum,
HIGEAR hIGear,
LONG nPendCount,
LPCSTR lpszFileName,
LPVOID lpData);

Arguments:

nPageNum
The number of the page just scanned; the first page is 1.
hIGear
HIGEAR handle to the image just scanned.
nPendCount
The number of pending pages left to be scanned. In the TWAIN lexicon, "pending" refers to how many pages are left in the ADF or in the digital camera. TWAIN requires that the Data Source let it know how many pages are "pending".
lpszFileName
If you are using Native or Buffered Memory Transfer Syntax, this will be the filename given to the page that was just scanned. If you are using Disk File Transfer, this was the name given to the page that was just scanned.
lpData
A far pointer to private data, as specified in your call to IG_TWAIN_CB_register() function.

Description:

This callback function, if registered, will be called by ImageGear after each page has been acquired using the IG_TWAIN_acquire (), IG_TWAIN_scan_pages (), IG_TWAIN_scan_pages_to_file () and IG_TWAIN_preview () functions.

Return Value:

Return 1 if you want to continue scanning; return 0 to cancel the scanning process after saving the page just scanned.


LPFNIG_TWAIN_BEFORE_DOC

Group: TWAIN Component

Declaration:

typedef LONG (LPACCUAPI LPFNIG_TWAIN_BEFORE_DOC)(
LPVOID lpData);

Arguments:

lpData
A far pointer to private data, as specified in your call to IG_TWAIN_CB_register() function.

Description:

This callback, if registered, will be called by ImageGear before any of the pages of a document have been retrieved, processed and/or saved.

Return Value:

Return 1 if you want to continue scanning; return 0 to cancel scanning.


LPFNIG_TWAIN_BEFORE_PAGE

Group: TWAIN Component

Declaration:

typedef LONG (LPACCUAPI LPFNIG_TWAIN_BEFORE_PAGE)(
LONG nPageNum,
DOUBLE dblLeft,
DOUBLE dblTop,
DOUBLE dblRight,
DOUBLE dblBottom,
LPVOID lpData);

Arguments:

nPageNum
Returns the number of the page that is about to be scanned. The page numbering begins with 1.
dblLeft
Returns the left coordinate of the selected layout rectangle that will be scanned for the current page.
dblTop
Returns the top coordinate of the selected layout rectangle that will be scanned for the current page.
dblRight
Returns the right coordinate of the selected layout rectangle that will be scanned for the current page.
dblBottom
Returns the bottom coordinate of the selected layout rectangle that will be scanned for the current page.
lpData
A far pointer to private data, as specified in your call to IG_TWAIN_CB_register() function.

Description:

This callback, if registered, will be called by ImageGear just before a new page is acquired using the IG_TWAIN_acquire (), IG_TWAIN_scan_pages (), IG_TWAIN_scan_pages_to_file () and IG_TWAIN_preview () functions. This function returns the page number and the bounding image rectangle (image rectangle) within which the scanning will take place, for the page that is about to be scanned.

Return Value:

Return 1 if you want to continue scanning; return 0 to cancel the scanning process after saving the page just scanned.


LPFNIG_TWAIN_CAP_SET_5

Group: TWAIN Component

Declaration:

typedef LONG (LPACCUAPI LPFNIG_TWAIN_CAP_SET_5)(
LPVOID lpData);

Arguments:

lpData
A far pointer to private data, as specified in your call to IG_TWAIN_CB_register() function.

Description:

This callback, if registered, will be called by ImageGear after the source has been enabled. It allows you to negotiate additional capabilities while Data Source is at State 5.

Return Value:

Return 1 if you want to continue scanning; return 0 to cancel scanning.


LPFNIG_TWAIN_DEVICE_EVENT

Group: TWAIN Component

Declaration:

typedef LONG (LPACCUAPI LPFNIG_TWAIN_DEVICE_EVENT)(
LPAT_TWAIN_DEVICEEVENT lpEvent,
LPVOID lpData);

Arguments:

lpEvent
Provides information about the Event that was raised by the Data Source.
lpData
A far pointer to private data, as specified in your call to IG_TWAIN_CB_register () function.

Description:

This callback, if registered, will be called by ImageGear when a device event occures.

Return Value:

Set the return value to 0 to return control to ImageGear.


TWAIN Component Enumerations

The ImageGear TWAIN component exposes the following enumerations:

enumIGTWAINAlarms
Determines specific audible alarms.
enumIGTWAINAudioFormats
Determines which Audio file formats are supported.
enumIGTWAINBarcodeRotation
Determines the bar code's orientation on the scanned image.
enumIGTWAINBarcodeSearchModes
Restricts barcode searching to certain orientations
enumIGTWAINBarcodeType
Determines the type of bar code found on a page.
enumIGTWAINBitDepthReduction
Specifies the Reduction Method the Source should use to reduce the bit depth of the data.
enumIGTWAINBitOrder
Specifies how the bytes in an image are filled by the Source.
enumIGTWAINCapabilities
Specifies ImageGear TWAIN capabilities.
enumIGTWAINCBType
This enumeration determines the type of callback function.
enumIGTWAINClearBuffers
Determines the type of buffer clearing process.
enumIGTWAINColorDataFormats
Allows the application and Source to identify which color data formats are available.
enumIGTWAINContainerType
Capability container type.
enumIGTWAINControlParams
TWAIN control parameters.
enumIGTWAINCountries
Specifies the country originated the scanned document.
enumIGTWAINDeskewStatus
Determines the status of the deskew operation.
enumIGTWAINDeviceEvents
Determines the device event.
enumIGTWAINDuplex
Determines whether the scanner supports duplex.
enumIGTWAINFeederAlignment
Determines which special actions applicetion may need to take when negotiating frames with the Source.
enumIGTWAINFeederOrder
Determines the order of scanning.
enumIGTWAINFileSystem
This enumeration determines the configuration of TWAIN file system.
enumIGTWAINFileType
File types in the device's file system.
enumIGTWAINFilterType
Determines the color characteristic of the subtractive filter applied to the image data.
enumIGTWAINFlashUsed
Determines which flash the image was acquired to use.
enumIGTWAINFlipRotation
Determines the orientation of images that flip orientation of every other image.
enumIGTWAINImageFilter
Determines the algorithm used to improve the quality of the image.
enumIGTWAINJobControl
Determines how the job can be processed,
enumIGTWAINJPEGQuality
Specifies the kind of JPEG quantization tables that tradeoff quality versus compressed image size.
enumIGTWAINLanguages
Specifies language of the scanned document.
enumIGTWAINLigthPath
Determines whether the image is captured transmissively or reflectively.
enumIGTWAINLightSource
Determines the general color characteristic of the light source used to acquire the image.
enumIGTWAINMessages
This enumeration represents capability control messages.
enumIGTWAINNoiseFilter
Selects the algorithm used to remove noise.
enumIGTWAINOrientation
Determines which edge of the "paper" the image's "top" is aligned with.
enumIGTWAINOverscanModes
Determines the overscanning mode.
enumIGTWAINPatchCode
Determines prioritized list of patch code types dictating the order in which patch codes will be sought
enumIGTWAINPixelFlavor
Describes the sense of the pixel whose numeric value is zero (minimum data value).
enumIGTWAINPixelType
Specifies the type of pixel data that a Source is capable of acquiring (for example, black and white, gray, RGB, etc.).
enumIGTWAINPowerSupply
Reports the kinds of power available to the device.
enumIGTWAINPrinter
Determines the printer devices being used by application.
enumIGTWAINPrinterModes
Specifies current printer mode.
enumIGTWAINSupportedSizes
Specifies the size(s) the Source can/should use to acquire image data.
enumIGTWAINUnits
Determines the unit of measure for all quantities.
enumIGTWAINXferFlags
This enumeration provides the flags for transfer mechanism.
enumIGTWAINXferType
Determines which type of transfer mechanisms the application and Source have in common.


enumIGTWAINAlarms

Group: Enumeration

Description:

This enumeration determines specific audible alarms.

Values:

IG_TW_AL_ALARM
Catchall for alarms not explicitly listed. It is also used where a device only provides control over a single, multi-use alarm.
IG_TW_AL_BARCODE
Barcode alarm
IG_TW_AL_DOUBLEFEED
Cover paper handling errors.
IG_TW_AL_FEEDERERROR
Covers paper handling errors such as jams, double-feeds, skewing and the like; conditions that most likely stop scanning.
IG_TW_AL_FEEDERWARNING
Covers non-fatal events, such as feeder empty.
IG_TW_AL_JAM
Cover paper handling errors.
IG_TW_AL_PATCHCODE
Patchcode alarm
IG_TW_AL_POWER
Generates alarms for any changes in power to the device.
IG_TW_AL_SKEW
Cover paper handling errors.


enumIGTWAINAudioFormats

Group: Enumeration

Description:

This enumeration determines which Audio file formats are supported.

Values:

IG_TW_AF_AIFF
AIFF format
IG_TW_AF_AU
AU format
IG_TW_AF_SND
SND format
IG_TW_AF_WAV
WAV format


enumIGTWAINBarcodeRotation

Group: Enumeration

Description:

This enumeration determines the bar code's orientation on the scanned image.

Values:

IG_TW_BCOR_ROT0
Normal reading orientation
IG_TW_BCOR_ROT180
Rotated 180 degrees clockwise
IG_TW_BCOR_ROT270
Rotated 270 degrees clockwise
IG_TW_BCOR_ROT90
Rotated 90 degrees clockwise
IG_TW_BCOR_ROTX
The orientation is not known.


enumIGTWAINBarcodeSearchModes

Group: Enumeration

Description:

This enumeration restricts barcode searching to certain orientations, or prioritizes one orientation over the other.

Values:

IG_TW_BD_HORZ
Horizontal mode
IG_TW_BD_HORZVERT
Horizontal/Vertical mode
IG_TW_BD_VERT
Vertical mode
IG_TW_BD_VERTHORZ
Vertical/Horizontal mode


enumIGTWAINBarcodeType

Group: Enumeration

Description:

This enumeration determines the type of bar code found on a page.

Values:

IG_TW_BT_2OF5DATALOGIC
2OF5DATALOGIC
IG_TW_BT_2OF5IATA
2OF5IATA
IG_TW_BT_2OF5INDUSTRIAL
2OF5INDUSTRIAL
IG_TW_BT_2OF5INTERLEAVED
2OF5INTERLEAVED
IG_TW_BT_2OF5MATRIX
2OF5MATRIX
IG_TW_BT_2OF5NONINTERLEAVED
2OF5NONINTERLEAVED
IG_TW_BT_3OF9
3OF9
IG_TW_BT_3OF9FULLASCII
3OF9FULLASCII
IG_TW_BT_CODABAR
CODABAR
IG_TW_BT_CODABARWITHSTARTSTOP
CODABARWITHSTARTSTOP
IG_TW_BT_CODE128
CODE128
IG_TW_BT_CODE93
CODE93
IG_TW_BT_EAN13
EAN13
IG_TW_BT_EAN8
EAN8
IG_TW_BT_MAXICODE
MAXICODE
IG_TW_BT_PDF417
PDF417
IG_TW_BT_POSTNET
POSTNET
IG_TW_BT_UCC128
UCC128
IG_TW_BT_UPCA
UPCA
IG_TW_BT_UPCE
UPCE


enumIGTWAINBitDepthReduction

Group: Enumeration

Description:

This enumeration specifies the Reduction Method the Source should use to reduce the bit depth of the data.

Values:

IG_TW_BR_CUSTHALFTONE
Custom Halftone method
IG_TW_BR_DIFFUSION
Diffusion method
IG_TW_BR_HALFTONE
Halftone method
IG_TW_BR_THRESHOLD
Threshold method


enumIGTWAINBitOrder

Group: Enumeration

Description:

This enumeration specifies how the bytes in an image are filled by the Source. IG_TW_BO_MSBFIRST indicates that the leftmost bit in the byte (usually bit 7) is the byte's Most Significant Bit.

Values:

IG_TW_BO_LSBFIRST
LSB
IG_TW_BO_MSBFIRST
MSB


enumIGTWAINCapabilities

Group: Enumeration

Description:

This enumeration specifies ImageGear TWAIN capabilities.

Values:

See Appendix: TWAIN Scanning Capabilities and accucnst.h file.


enumIGTWAINCBType

Group: Enumeration

Description:

This enumeration determines the type of callback function.

Values:

IG_TW_CBT_AFTER_DOC
IG_TW_CBT_AFTER_PAGE
IG_TW_CBT_AFTER_TRANSFORM_PAGE
IG_TW_CBT_BEFORE_DOC
IG_TW_CBT_BEFORE_PAGE
IG_TW_CBT_CAP_SET_5
IG_TW_CBT_DEVICE_EVENT


enumIGTWAINClearBuffers

Group: Enumeration

Description:

This enumeration determines the type of buffer clearing process.

Values:

IG_TW_CB_AUTO
Causes the Source to automatically clear the buffers
IG_TW_CB_CLEAR
Causes the Source to immediately clear its buffers.
IG_TW_CB_NOCLEAR
Causes the Source to preserve images in the buffers.


enumIGTWAINColorDataFormats

Group: Enumeration

Description:

This enumeration allows the application and Source to identify which color data formats are available.

There are two options, "planar" and "chunky."For example, planar RGB data is transferred with the entire red plane of data first, followed by the entire green plane, followed by the entire blue plane (typical for three-pass scanners). "Chunky" mode repetitively interlaces a pixel from each plane until all the data is transferred (R-G-B-R-G-B...) (typical for one-pass scanners).

Values:

IG_TW_PC_CHUNKY
Chunky mode
IG_TW_PC_PLANAR
Planar mode


enumIGTWAINContainerType

Group: Enumeration

Description:

Capability container type.

Values:

IG_TW_ON_ARRAY
Indicates Array container
IG_TW_ON_ENUMERATION
Indicates Enumeration container
IG_TW_ON_ONEVALUE
Indicates OneValue container
IG_TW_ON_RANGE
Indicates Range container


enumIGTWAINControlParams

Group: Enumeration

Description:

This enumeration determines TWAIN control parameters.

Values:

IG_TW_CTRL_APP_NAME
IG_TW_CTRL_AUDIO_FILE_NAME
IG_TW_CTRL_IMAGE_FILE_NAME
IG_TW_CTRL_SAVE_PAGE_BEFORE_CB
IG_TW_CTRL_SAVE_PAGES_SEPARATELY


enumIGTWAINCountries

Group: Enumeration

Description:

This enumeration specifies the country originated the scanned document.

Values:

See igtwain15a.h file.


enumIGTWAINDeskewStatus

Group: Enumeration

Description:

This enumeration determines the status of the deskew operation.

Values:

IG_TW_DSK_DISABLED
Deskew engine not enabled
IG_TW_DSK_FAIL
Deskew failed
IG_TW_DSK_REPORTONLY
Deskew information only
IG_TW_DSK_SUCCESS
Image successfully deskewed


enumIGTWAINDeviceEvents

Group: Enumeration

Description:

This enumeration determines the device event.

Values:

IG_TW_DE_CHECKAUTOMATICCAPTURE
The automatic capture settings on the device have been changed by the user.
IG_TW_DE_CHECKBATTERY
The status of the battery has changed.
IG_TW_DE_CHECKDEVICEONLINE
The device has been turned off and on.
IG_TW_DE_CHECKFLASH
The flash setting on the device has been changed by the user.
IG_TW_DE_CHECKPOWERSUPPLY
The power supply has been changed
IG_TW_DE_CHECKRESOLUTION
The x/y resolution setting on the device has been changed by the user.
IG_TW_DE_CUSTOMEVENTS
Baseline for events specific to a given Source.
IG_TW_DE_DEVICEADDED
The user has added a device (for instance a memory card in a digital camera).
IG_TW_DE_DEVICEOFFLINE
A device has become unavailable, but has not been removed.
IG_TW_DE_DEVICEREADY
The device is ready to capture an image.
IG_TW_DE_DEVICEREMOVED
The user has removed a device.
IG_TW_DE_IMAGECAPTURED
The user has captured an image to the device's internal storage.
IG_TW_DE_IMAGEDELETED
The user has removed an image from the device's internal storage.
IG_TW_DE_LAMPFAILURE
The device's light source has failed.
IG_TW_DE_PAPERDOUBLEFEED
Two or more sheets of paper have been fed together.
IG_TW_DE_PAPERJAM
The device's document feeder has jammed.
IG_TW_DE_POWERSAVE
The device has powered down to save energy.
IG_TW_DE_POWERSAVENOTIFY
The device is about to power down to save energy.


enumIGTWAINDuplex

Group: Enumeration

Description:

This enumeration determines whether the scanner supports duplex.

Values:

IG_TW_DX_1PASSDUPLEX
One duplex is supported.
IG_TW_DX_2PASSDUPLEX
Two duplex is supported.
IG_TW_DX_NONE
No duplex support


enumIGTWAINFeederAlignment

Group: Enumeration

Description:

This enumeration determines which special actions applicetion may need to take when negotiating frames with the Source.

Values:

IG_TW_FA_CENTER
The alignment is centered. This means that the paper will be fed in the middle of the ICAP_PHYSICALWIDTH of the device.
IG_TW_FA_LEFT
The alignment is to the left.
IG_TW_FA_NONE
The alignment is free-floating.
IG_TW_FA_RIGHT
The alignment is to the right.


enumIGTWAINFeederOrder

Group: Enumeration

Description:

This enumeration determines the order of scanning.

Values:

IG_TW_FO_FIRSTPAGEFIRST
Feeder starts with the top of the first page.
IG_TW_FO_LASTPAGEFIRST
Feeder starts with the top of the last page.


enumIGTWAINFileSystem

Group: Enumeration

Description:

This enumeration determines the configuration of TWAIN file system.

Values:

IG_TW_FS_FILESYSTEM
IG_TW_FS_RECURSIVEDELETE


enumIGTWAINFileType

Group: Enumeration

Description:

File types in the device's file system.

Values:

IG_TW_FY_CAMERA
IG_TW_FY_CAMERABOTTOM
IG_TW_FY_CAMERAPREVIEW
IG_TW_FY_CAMERATOP
IG_TW_FY_DIRECTORY
IG_TW_FY_DOMAIN
IG_TW_FY_HOST
IG_TW_FY_IMAGE
IG_TW_FY_UNKNOWN


enumIGTWAINFilterType

Group: Enumeration

Description:

This enumeration determines the color characteristic of the subtractive filter applied to the image data.

Values:

IG_TW_FT_BLACK
Black filter
IG_TW_FT_BLUE
Blue filter
IG_TW_FT_CYAN
Cyan filter
IG_TW_FT_GREEN
Green filter
IG_TW_FT_MAGENTA
Magenta filter
IG_TW_FT_NONE
No filter
IG_TW_FT_RED
Red filter
IG_TW_FT_WHITE
White filter
IG_TW_FT_YELLOW
Yellow filter


enumIGTWAINFlashUsed

Group: Enumeration

Description:

This enumeration determines which flash the image was acquired to use.

Values:

IG_TW_FL_AUTO
Auto flash
IG_TW_FL_NONE
No flash
IG_TW_FL_OFF
Flash is off
IG_TW_FL_ON
Flash is on
IG_TW_FL_REDEYE
Redeye flash


enumIGTWAINFlipRotation

Group: Enumeration

Description:

This enumeration determines the orientation of images that flip orientation of every other image.

Values:

IG_TW_FR_BOOK
The images to be scanned are viewed in book form, flipping each page from left to right or right to left.
IG_TW_FR_FANFOLD
The images to be scanned are viewed in fanfold paper style, flipping each page up or down.


enumIGTWAINImageFilter

Group: Enumeration

Description:

This enumeration determines the algorithm used to improve the quality of the image.

Values:

IG_TW_IF_AUTO
Auto
IG_TW_IF_BANDPASS
Bandpass algorithm. Good for improving text.
IG_TW_IF_FINELINE
Fineline algorithm.
IG_TW_IF_HIGHPASS
Highpass algorithm. Good for improving fine lines.
IG_TW_IF_LOWPASS
Lowpass algorithm. Good for halftone images.
IG_TW_IF_NONE
No algorithm
IG_TW_IF_TEXT
Text algorithm.


enumIGTWAINJobControl

Group: Enumeration

Description:

This enumeration determines how the job can be processed,

Values:

IG_TW_JC_JSIC
Detect and include job separator and continue scanning.
IG_TW_JC_JSIS
Detect and include job separator and stop scanning.
IG_TW_JC_JSXC
Detect and exclude job separator and continue scanning.
IG_TW_JC_JSXS
Detect and exclude job separator and stop scanning.
IG_TW_JC_NONE
No job control.


enumIGTWAINJPEGQuality

Group: Enumeration

Description:

This enumeration specifies the kind of JPEG quantization tables that tradeoff quality versus compressed image size.

Values:

IG_TW_JQ_HIGH
Write-only; implies high quality; the images display the maximum quality that produces any kind of meaningful compression. Note that images at this setting are still considered to be lossy.
IG_TW_JQ_LOW
Write-only; implies low quality; the images are at the maximum compression recommended by the Source.
IG_TW_JQ_MEDIUM
Write-only; implies medium quality; the images are at the balance point between good compression and good images. This is an arbitrary setting on the part of the Source writer that is expected to best represent their device. This is the value that Applications are most encouraged to use.
IG_TW_JQ_UNKNOWN
Read-only; must be the setting for this capability if the user sets the JPEG compression tables using DAT_JPEGCOMPRESSION, and the Source is not able to map the
selected tables to a specific percentage of quality.


enumIGTWAINLanguages

Group: Enumeration

Description:

This enumeration specifies language of the scanned document.

Values:

Please see igtwain15a.h file.


enumIGTWAINLigthPath

Group: Enumeration

Description:

This enumeration determines whether the image is captured transmissively or reflectively.

Values:

IG_TW_LP_REFLECTIVE
Reflective capture
IG_TW_LP_TRANSMISSIVE
Transmissive capture


enumIGTWAINLightSource

Group: Enumeration

Description:

This enumeration determines the general color characteristic of the light source used to acquire the image.

Values:

IG_TW_LS_BLUE
Blue
IG_TW_LS_GREEN
Green
IG_TW_LS_IR
IR
IG_TW_LS_NONE
None
IG_TW_LS_RED
Red
IG_TW_LS_UV
UV
IG_TW_LS_WHITE
White


enumIGTWAINMessages

Group: Enumeration

Description:

This enumeration represents capability control messages.

Values:

IG_TW_MSG_GET
Get one or more values.
IG_TW_MSG_GETCURRENT
Get current value.
IG_TW_MSG_GETDEFAULT
Get default (e.g., power up) value.
IG_TW_MSG_GETFIRST
Get first value.
IG_TW_MSG_GETNEXT
Get next value.
IG_TW_MSG_QUERYSUPPORT
Query capability support.
IG_TW_MSG_RESET
Set current value to default value.
IG_TW_MSG_SET
Set one or more values.


enumIGTWAINNoiseFilter

Group: Enumeration

Description:

This enumeration selects the algorithm used to remove noise.

Values:

IG_TW_NF_AUTO
Auto
IG_TW_NF_LONEPIXEL
Lonepixel
IG_TW_NF_MAJORITYRULE
Majority rule
IG_TW_NF_NONE
None


enumIGTWAINOrientation

Group: Enumeration

Description:

This enumeration determines which edge of the "paper" the image's "top" is aligned with.

Values:

IG_TW_OR_LANDSCAPE
equals IG_TW_OR_ROT270
IG_TW_OR_PORTRAIT
equals IG_TW_OR_ROT0
IG_TW_OR_ROT0
normal orientation
IG_TW_OR_ROT180
Rotated 180 degrees clockwise
IG_TW_OR_ROT270
Rotated 270 degrees clockwise
IG_TW_OR_ROT90
Rotated 90 degrees clockwise


enumIGTWAINOverscanModes

Group: Enumeration

Description:

This enumeration determines the overscanning mode.

Values:

IG_TW_OV_ALL
Overscan all
IG_TW_OV_AUTO
Auto mode
IG_TW_OV_LEFTRIGHT
Left-Right mode
IG_TW_OV_NONE
None
IG_TW_OV_TOPBOTTOM
Top-Bottom mode


enumIGTWAINPatchCode

Group: Enumeration

Description:

This enumeration determines prioritized list of patch code types dictating the order in which patch codes will be sought.

Values:

IG_TW_PCH_PATCH1
Patch 1
IG_TW_PCH_PATCH2
Patch 2
IG_TW_PCH_PATCH3
Patch 3
IG_TW_PCH_PATCH4
Patch 4
IG_TW_PCH_PATCH6
Patch 6
IG_TW_PCH_PATCHT
Patch T


enumIGTWAINPixelFlavor

Group: Enumeration

Description:

This enumeration correctly describes the sense of the pixel whose numeric value is zero (minimum data value).

Values:

IG_TW_PF_CHOCOLATE
This pixel represents the darkest data value that can be generated by the device (the darkest available optical value may measure greater than 0).
IG_TW_PF_VANILLA
This pixel represents the lightest data value that can be generated by the device (the lightest available optical value may measure greater than 0).


enumIGTWAINPixelType

Group: Enumeration

Description:

This enumeration specifies the type of pixel data that a Source is capable of acquiring (for example, black and white, gray, RGB, etc.).

Values:

IG_TW_PT_BW
Black and white
IG_TW_PT_CIEXYZ
CIEXYZ
IG_TW_PT_CMY
CMY
IG_TW_PT_CMYK
CMYK
IG_TW_PT_GRAY
GRAY
IG_TW_PT_PALETTE
PALETTE
IG_TW_PT_RGB
RGB
IG_TW_PT_YUV
YUV
IG_TW_PT_YUVK
YUVK


enumIGTWAINPowerSupply

Group: Enumeration

Description:

This enumeration reports the kinds of power available to the device.

Values:

IG_TW_PS_BATTERY
Battery supply
IG_TW_PS_EXTERNAL
External supply


enumIGTWAINPrinter

Group: Enumeration

Description:

This enumeration determines the printer devices being used by application.

Imprinters are used to print data on documents at the time of scanning, and may be used for any purpose. Endorsers are more specific in nature, stamping some kind of proof of scanning on the document.

Top/Bottom refer to duplex devices, and indicate if the printer is writing on the top or the bottom of the sheet of paper. Simplex devices use the top settings.

Before/After indicates whether printing occurs before or after the sheet of paper has been scanned.

Values:

IG_TW_PR_ENDORSERBOTTOMAFTER
Endorser bottom/after
IG_TW_PR_ENDORSERBOTTOMBEFORE
Endorser bottom/before
IG_TW_PR_ENDORSERTOPAFTER
Endorser top/after
IG_TW_PR_ENDORSERTOPBEFORE
Endorser top/before
IG_TW_PR_IMPRINTERBOTTOMAFTER
Imprinter bottom/after
IG_TW_PR_IMPRINTERBOTTOMBEFORE
Imprinter bottom/before
IG_TW_PR_IMPRINTERTOPAFTER
Imprinter top/after
IG_TW_PR_IMPRINTERTOPBEFORE
Imprinter top/before


enumIGTWAINPrinterModes

Group: Enumeration

Description:

This enumeration specifies current printer mode.

Values:

IG_TW_PM_COMPOUNDSTRING
The printed string will consist of a compound of a String followed by a value followed by a suffix string.
IG_TW_PM_MULTISTRING
The printed text will consist of an enumerated list of strings to be printed in order.
IG_TW_PM_SINGLESTRING
The printed text will consist of a single string.


enumIGTWAINSupportedSizes

Group: Enumeration

Description:

This enumeration specifies the size(s) the Source can/should use to acquire image data.

Values:

IG_TW_SS_2A0
IG_TW_SS_4A0
IG_TW_SS_A0
IG_TW_SS_A1
IG_TW_SS_A10
IG_TW_SS_A2
IG_TW_SS_A3
IG_TW_SS_A4
IG_TW_SS_A4LETTER
IG_TW_SS_A5
IG_TW_SS_A6
IG_TW_SS_A7
IG_TW_SS_A8
IG_TW_SS_A9
IG_TW_SS_B3
IG_TW_SS_B4
IG_TW_SS_B5LETTER
IG_TW_SS_B6
IG_TW_SS_BUSINESSCARD
IG_TW_SS_C0
IG_TW_SS_C1
IG_TW_SS_C10
IG_TW_SS_C2
IG_TW_SS_C3
IG_TW_SS_C4
IG_TW_SS_C5
IG_TW_SS_C6
IG_TW_SS_C7
IG_TW_SS_C8
IG_TW_SS_C9
IG_TW_SS_ISOB0
IG_TW_SS_ISOB1
IG_TW_SS_ISOB10
IG_TW_SS_ISOB2
IG_TW_SS_ISOB3
IG_TW_SS_ISOB4
IG_TW_SS_ISOB5
IG_TW_SS_ISOB6
IG_TW_SS_ISOB7
IG_TW_SS_ISOB8
IG_TW_SS_ISOB9
IG_TW_SS_JISB0
IG_TW_SS_JISB1
IG_TW_SS_JISB10
IG_TW_SS_JISB2
IG_TW_SS_JISB3
IG_TW_SS_JISB4
IG_TW_SS_JISB5
IG_TW_SS_JISB6
IG_TW_SS_JISB7
IG_TW_SS_JISB8
IG_TW_SS_JISB9
IG_TW_SS_NONE
IG_TW_SS_USEXECUTIVE
IG_TW_SS_USLEDGER
IG_TW_SS_USLEGAL
IG_TW_SS_USLETTER
IG_TW_SS_USSTATEMENT


enumIGTWAINUnits

Group: Enumeration

Description:

This enumeration determines the unit of measure for all quantities.

Values:

IG_TW_UN_CENTIMETERS
Centimeters
IG_TW_UN_INCHES
Inches
IG_TW_UN_PICAS
Picas
IG_TW_UN_PIXELS
Pixels
IG_TW_UN_POINTS
Points
IG_TW_UN_TWIPS
Twips


enumIGTWAINXferFlags

Group: Enumeration

Description:

This enumeration provides the flags for transfer mechanism.

Values:

IG_TW_AUDIO
Audio
IG_TW_IMAGE
Image


enumIGTWAINXferType

Group: Enumeration

Description:

This enumeration determines which type of transfer mechanisms the application and Source have in common.

Values:

IG_TW_SX_FILE
File type
IG_TW_SX_FILE2
File to File type
IG_TW_SX_MEMORY
Memory type
IG_TW_SX_NATIVE
Native type


Vector Component API Function Reference

ImageGear Vector component provides you with functions loading, displaying, modifying and saving vector data. With this component initialized you have:

  • Full access to all entities contained in the structure.
  • A possibility to edit any entity, create and delete them.
  • OpenGL or WinAPI graphics depending on user's wishes.
  • More compact representation of the entities in the structure.
  • New color model including red, green, blue and alpha component as well as a flag that defines a color source : Block, Layer or actual color. Alpha component defines a color transparency (OpenGL graphics only)
See Also:

Vector Component General Concepts

Vector Component Functions Reference

Vector Component Enumerations Reference

Vector Component Structures Reference


Vector Component General Concepts

Vector data is created when reading vector files such as DWF, DWG/DXF, DGN, CGM, HPGL, U3D as well as ASCII, PTOCA, WMF and some other. Vector data is attached to HIGEAR handle and draws its content itself during the display operations.

Vector API consists of constants, structures, handles and functions.

  • Constants define different flags, types and attributes.
  • Structures are opened data types that can be modified by the user directly
  • Handles are closed data types. They can be accessed using the functions.

Vector data (Drawing) is accessible via the handle HIG_VECT_DRWNG and the set of functions having the prefix IG_vect_drwng_... .

The content of the Drawing consists of vector primitives - Entities. The samples of the entities are: easy line, text, polyline, block and other. The Entity is created by the Drawing and accessible via the handle HIG_VECT_ENTITY.

Any Entity has some common attributes. They are: Identifier, type, Layer and some flags: Dirty, Selected, Deleted. Entity has also several optional attributes, which do not exist until they are created. These attributes are: draw color, fill color, line type, fill type, thickness, offset, rotation, scale and position. All common Entity features and attributes are accessible via HIG_VECT_ENTITY handle and functions with prefix IG_vect_ent_... .

There is a set of functions for access to the unique features of the entity. They all have the corresponding prefix. For example, the following function returns the radius along the x axes of the ellipse:

IG_vect_ellipse_get_radiusx (HIG_VECT_ENTITY hEntity, float*
lpRadiusx);

The Layer is an object that contains attributes, which can be applied to the group of the entities. The Layer is created by the Drawing and accessed by the handle HIG_VECT_LAYER and functions with the prefix IG_vect_layer_... .

Drawing can have several Views, that is, different points of view to the set of Entities. Every View is represented by its Camera attributes such as position, scale, rotation, focus.

View can be created and destroyed.


Drawing angles

All angles are measured in radians. So, if you have an angle in degrees, you have to translate it to radian using the formula:

Ang_rad = ang_degree / 180 * VECT_PI;

Where VECT_PI is defined in vectapi.h


Color concept

All colors in Drawing have four 8-bit components: red, green, blue and alpha. Alpha provides a transparency for the color (OpenGL graphics only). Alpha equal to 255 means opaque color, 0 - full transparency. Also, the structure describing a color (IGVectColorEx) has a field defining a color source. If this field is equal to IG_VECT_ATTR_SOURCE_ACTUAL then the red, green blue and alpha are used. In case of IG_VECT_ATTR_SOURCE_BLOCK the actual color is obtained from the including block. IG_VECT_ATTR_SOURCE_LAYER prescribes to use a layer color.


Coordinate concept

Every point in the vector data has three coordinates - x, y, z. If this is enough for the point description, then the point is defined by the simple structure IGVectPoint3D. The examples of such points are: start and end point of the easy line, the point of the easy surface, minimum and maximum coordinates of the viewport. But often the point must have some additional attributes. They are: visibility, bulge and thickness of the outgoing line or the weight if the point belongs to the NURBS curve or surface. In these cases the point is represented by the Vertex structure IGVectVertex. Vertexes are created and owned by the Vertex Container. The Vertex container controls all additional Vertex attributes.


Text concept

Vector text is defined by the entity of type IG_VECT_ENT_TEXT. It has some common text attributes such as base line angle and the type of alignment. Moreover, the text string is separated to the several Text Objects which have they own attributes such as font, font width and height, char base and char up angles, color, char spacing and some additional effects. The Text Object is created, owned and destroyed by the Text entity. It can be accessed via the handle HIG_VECT_TEXTOBJ and functions with the prefix IG_vect_textobj_... .


Font concept

Drawing can use two types of font:

  • TrueType font - is created and controlled completely by the Drawing. The user has not to worry about these fonts. He (she) should only tell the typeface and weight. In other hand, he (she) can't change the glyphs of such font.
  • Vector font - is empty just after it has been created by the Drawing. The user must set the size (number of glyphs) of the vector font and fill the Vertex Container of every glyph. The sample is the CAD font described in the .shx files. The CAD filter creates vector fonts contained in the .shx files. The user has the complete controlling and responsibility for such fonts.


Gradient concept

Gradient filling properties are encapsulated by a HIG_VECT_GRADIENT handle. This handle is attached to a HIG_VECT_FILLTYPE object.

There are two types of gradient filllings: linear and radial. Linear gradient is defined by its start and end points. Radial gradient is defined by a start point and an outer circle. Start point should be located inside the outer circle, but not necessarily in its center. Coordinates of the gradient can be absolute or relative (to the bounding rectangle of the entity that uses the gradient).

The color of the gradient is defined by an array of stops. A stop is a pair of offset and color. Stop offsets are relative to gradient coordinates: 0.0 corresponds to the start point; 1.0 corresponds to the end points, in case of a linear gradient, or to a point at the outer circle, in case of radial gradient. If first stop offset is greater than 0.0, or last stop offset is less than 1.0, the gradient is expanded, according to its Spread method. Gradient color is linearly interpolated between the stops.

Gradient filling can be transformed with an affine matrix.


Vector Component Functions Reference

There are the following groups of Vector Component functions:

IG_vect_arc_
Elliptical arc functions
IG_vect_beziercurve_
Bezier curve functions
IG_vect_block_
Block functions. These functions are applicable to the entities of type IG_VECT_ENT_BLOCK.
IG_vect_dblcont_
Functions for access to the container of floats. Such containers are used in the spline curve and surface entities to keep knot vector
IG_vect_drwng_
Vector Drawing functions. The functions below provides an interface to the common settings of the Vector Drawing
IG_vect_easyline_
Easy line - contains only two points
IG_vect_easysurface_
Easy surface functions. Easy surface is defined by its meshes. No interpolation is performed during displaying.
IG_vect_ellipse_
Ellipse functions
IG_vect_ent_
Common entity functions. These functions provide an access to the common entity attributes.
IG_vect_entcont_
Entity container functions. Such entities as Block and Figure have Entity containers to keep another entities inside. The functions below allow an access to the container.
IG_vect_figure_
Figure functions. Figure is a complex entity that includes several regions. Any region can consists of other entities such as easy line, polyline, ellipse and other.
IG_vect_filltype_
Fill type functions. Fill type is created by the Drawing. The functions below allow obtaining some fill type attributes.
IG_vect_font_
Common font functions. These are the common functions for access to both True Type and Vector fonts.
IG_vect_layer_
Layer functions. These functions allow manipulating different attributes of the layer
IG_vect_layercont_
Layer container functions. These functions provide access to the layer container used in Viewport entity
IG_vect_linetype_
Line type functions. Line type is created by the Drawing. The functions below allow obtaining some line type attributes.
IG_vect_NURBScurve_
NURBS curve functions
IG_vect_NURBSsurface_
NURBS surface functions. NURBS surface has m Vertex Containers. Each container has n control points. The surface also has two float containers with knot vectors in M and N direction.
IG_vector_
Common functions of Vector component
IG_vect_polyline_
Polyline functions
IG_vect_polylineex_
Extended polyline - can contain multiple contours
IG_vect_rotation_
Rotation functions. The user specifies rotation angles using Rotation object. The functions below provide an access to the Rotation.
IG_vect_text_
Text functions. Text entity defines common attributes for the text string. It also controls all included Text Objects.
IG_vect_textobj_
Text object. Not an entity. Used with the Text.
Text entity provides some common settings for the text string such as alignment, base line, start point and other. Text string can be separated to several pieces having they own attributes such as font, color, char base and up angle, char spacing and other. These easy portions of text are described by Text Objects. Text Objects are chained inside the Text entity.
IG_vect_vertexcont_
Vertex container functions. Vertex container creates and controls the Vertexes. It has also an internal attribute container for all vertex attributes.
IG_vect_view_
Vector View functions. Vector View represents a way to observe some entities from the different points. Replacing some camera settings such as focus, offset, scale factors and rotation can change the point of view.
IG_vect_viewport_
Viewport functions. Viewport allows mapping of the 3D drawing the bounded square with the specified point of view and scale factors. Usually Viewports are used to map model space to the paper space in AutoCAD systems.


AT_VECT_3DIV_OPTIONS

Group: 3D Surface

Declaration:

typedef struct tagAT_VECT_3DIV_OPTIONS
{
AT_DOUBLE dIsoValue;
AT_INT iLowExcluRange;
AT_INT iHighExcluRange;
AT_BOOL bDoNorms;
AT_BOOL bFlipNorms;
AT_BOOL bAddCoverSlices;
AT_BOOL bLimitDepth;
AT_INT iSurfaceDepth;
AT_BOOL bDecimateY;
AT_INT iYDecimFactor;
AT_BOOL bDecimateZ;
AT_INT iZDecimFactor;
} AT_VECT_3DIV_OPTIONS;

Arguments:

dIsoValue
Intensity value of pixels on the isosurface.
iLowExcluRange
Lower limit of exclusion region.
iHighExcluRange
Upper limit of exclusion region.
bDoNorms
Flag to indicate whether to calculate the normals along with vertices.
bFlipNorms
Flag to indicate whether to flip the normals after calculation.
bAddCoverSlices
Flag to indicate whether to add cover-up slices at the ends.
bLimitDepth
Flag to indicate whether to limit the surface depth.
iSurfaceDepth
Depth of the surface. In effect only if bLimitDepth is TRUE.
bDecimateY
Flag to indicate whether to decimate Y direction when considering surface depth. In effect only if bLimitDepth is TRUE.
iYDecimFactor
Decimation factor in Y direction. In effect only if both bLimitDepth and bDecimateY are TRUE.
bDecimateZ
Flag to indicate whether to decimate Z direction when considering the surface depth. In effect only if bLimitDepth is TRUE.
iZDecimFactor
Decimation factor in Z direction, in effect only if both bLimitDepth and bDecimateZ are TRUE.

Description:

This structure serves as a parameter for function IG_vect_3DIV_isosurface (), and it contains the values for all the options for isosurface algorithm.

The parameter bAddCoverSlices indicates whether "cover-up" slices should be added at both ends. If TRUE, the first and last slices will be placed at both ends, with pixels outside of the 3D object set to transparent.

When the isosurface is generated, a lot of triangles are also generated inside the 3D object despite sometimes we are only interested in the outside surface. The flag bLimitDepth allows the surface to be limited to only a certain depth, thus any triangles further inside will be discarded. This greatly improves the rendering performance, for example, when rotating the 3D object. On the flip side, if surface depth limit is set too low, it is possible that "artificial holes" will be created on the surface because of excessive discarding of triangles.

Parameters bDecimateY, iYDecimFactor, bDecimateZ and iZDecimFactor further refine the process of limiting surface depth. The higher the decimation factors, the better the surface looks, but that also means the more number of triangles. So a balance point is required. For a brain example we looked at, values [10, 5, 5] for [iSurfaceDepth, iYDecimFactor, iZDecimFactor] reduced the number of triangles by about a half while still producing a reasonable 3D surface.

Parameters iLowExcluRange and iHighExcluRange are designed to exclude certain pixels whose intensities fall within the specified range. If this feature is not desired, the user can simply set both of those two parameters to 0.


IG_vect_3DIV_isosurface

Group: 3D Surface

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_3DIV_isosurface(
HMIGEAR hMIGear,
AT_VECT_3DIV_OPTIONS * lpOptions,
LPHIGEAR lphIGear);

Arguments:

hMIGear
A handle to a multi-page image, which has slices of images in a 3D series stacked together in the desired order.
lpOptions
A pointer to a struct AT_VECT_3DIV_OPTIONS, which contains all the calculation options for isosurface algorithm.
lphIGear
The vector image with all the triangles generated.

Description:

This function takes a multi-page image and extracts the 3D surface into a vector image, based on the options specified by lpOptions.

The pages in the multi-page image must be in the desired order as it would be in the 3D object. If the user has a series of single-page images to start with, necessary operations are needed to stack those single-page images together to form a multi-page image.

Bits Per Pixel: 8, 16, and 32

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Example:

HMIGEAR hMIGear; /* Handle to a multi-page image */
HIGEAR hIGear; /* Handle for the generated vector image with all
the triangles */
AT_VECT_3DIV_OPTIONS vect3DIVOptions;/* Struct for calculation
options */
int nErrCount; /* Returned count of errors */
/* If necessary, load the set of single-page images into hMIGear
*/
......
/* Initialize vect3DIVOptions with proper values */
vect3DIVOptions.dIsoValue = 120.0;
...
vect3DIVOptions.bDoNorms = TRUE;
...
nErrCount = IG_vect_3DIV_isosurface(hMIGear, &vect3DIVOptions,
&hIGear);

Sample: Medical

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_get_clockwise

Group: Elliptical arc

Declaration:

IG_vect_arc_get_clockwise(HIG_VECT_ENTITY hEntity, VECT_BOOL*
lpClockwise);

Arguments:

hEntity
Handle to the Entity
lpClockwise
Buffer for drawing direction. If lpClockwise = VECT_TRUE then drawing direction is clockwise, if VECT_FALSE - counter clockwise

Description:

The function returns drawing direction of the elliptical arc.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_set_clockwise

Group: Elliptical arc

Declaration:

IG_vect_arc_set_clockwise(HIG_VECT_ENTITY hEntity, VECT_BOOL
bClockwise);

Arguments:

hEntity
Handle to the Entity
bClockwise
Drawing direction being set. If bClockwise = VECT_TRUE then drawing direction is clockwise, if VECT_FALSE - counter clockwise

Description:

The function sets drawing direction of the elliptical arc

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_get_closetype

Group: Elliptical arc

Declaration:

IG_vect_arc_get_closetype(HIG_VECT_ENTITY hEntity,
enumIGVectArcCloseType* lpClosetype);

Arguments:

hEntity
Handle to the Entity
lpClosetype
Buffer for the constant defining arc close type

Description:

The function tells how an arc is closed.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_set_closetype

Group: Elliptical arc

Declaration:

IG_vect_arc_set_closetype(HIG_VECT_ENTITY hEntity,
enumIGVectArcCloseType nClosetype);

Arguments:

hEntity
Handle to the Entity
nClosetype
Close type to be set

Description:

The function sets an arc close type.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_get_endangle

Group: Elliptical arc

Declaration:

IG_vect_arc_get_endangle(HIG_VECT_ENTITY hEntity, float*
lpEndangle);

Arguments:

hEntity
Handle to the Entity
lpEndangle
Buffer for the end angle

Description:

The function returns an end angle of the elliptical arc.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_set_endangle

Group: Elliptical arc

Declaration:

IG_vect_arc_set_endangle(HIG_VECT_ENTITY hEntity, float
fEndangle);

Arguments:

hEntity
Handle to the Entity
fEndangle
End angle being set

Description:

The function sets an end angle of the elliptical arc.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_get_radiusx

Group: Elliptical arc

Declaration:

IG_vect_arc_get_radiusx(HIG_VECT_ENTITY hEntity, float*
lpRadiusx);

Arguments:

hEntity
Handle to the Entity
lpRadiusx
Buffer for the x radius

Description:

The function returns a radius of the elliptical arc along the x-axes.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_set_radiusx

Group: Elliptical arc

Declaration:

IG_vect_arc_set_radiusx(HIG_VECT_ENTITY hEntity, float
fRadiusx);

Arguments:

hEntity
Handle to the Entity
fRadiusx
X radius being set

Description:

The function sets a radius of the elliptical arc along the x-axes

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_get_radiusy

Group: Elliptical arc

Declaration:

IG_vect_arc_get_radiusy(HIG_VECT_ENTITY hEntity, float*
lpRadiusy);

Arguments:

hEntity
Handle to the Entity
lpRadiusy
Buffer for the y radius

Description:

The function returns a radius of the elliptical arc along the y-axes.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_set_radiusy

Group: Elliptical arc

Declaration:

IG_vect_arc_set_radiusy(HIG_VECT_ENTITY hEntity, float
fRadiusy);

Arguments:

hEntity
Handle to the Entity
fRadiusy
Y radius being set

Description:

The function sets a radius of the elliptical arc along the y-axes.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_get_startangle

Group: Elliptical arc

Declaration:

IG_vect_arc_get_startangle(HIG_VECT_ENTITY hEntity, float*
lpStartangle);

Arguments:

hEntity
Handle to the Entity
lpStartangle
Buffer for the start angle

Description:

The function returns a start angle of the elliptical arc.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_arc_set_startangle

Group: Elliptical arc

Declaration:

IG_vect_arc_set_startangle(HIG_VECT_ENTITY hEntity, float
fStartangle);

Arguments:

hEntity
Handle to the Entity
fStartangle
Start angle being set

Description:

The function sets a start angle of the elliptical arc.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_beziercurve_get_degree

Group: Bezier curve

Declaration:

IG_vect_beziercurve_get_degree(HIG_VECT_ENTITY hEntity, long*
lpDegree);

Arguments:

hEntity
Handle to the Entity
lpDegree
Buffer for the Bezier interpolation degree

Description:

The function returns a degree of the Bezier interpolation.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_beziercurve_set_degree

Group: Bezier curve

Declaration:

IG_vect_beziercurve_set_degree(HIG_VECT_ENTITY hEntity, long
nDegree);

Arguments:

hEntity
Handle to the Entity
nDegree
Bezier interpolation degree being set

Description:

The function sets a degree of the Bezier interpolation.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_beziercurve_get_flags

Group: Bezier curve

Declaration:

IG_vect_beziercurve_get_flags(HIG_VECT_ENTITY hEntity, long*
lpFlags);

Arguments:

hEntity
Handle to the Entity
lpFlags
Buffer for the flags

Description:

The function returns different flags of the interpolated curve. The only possible flag is IG_VECT_NURBS_MCLOSED, if the curve is closed.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_beziercurve_set_flags

Group: Bezier curve

Declaration:

IG_vect_beziercurve_set_flags(HIG_VECT_ENTITY hEntity, long
nFlags);

Parameters:

hEntity
Handle to the Entity
nFlags
Flags being set

Description:

The function returns different flags of the interpolated curve. The only possible flag is IG_VECT_NURBS_MCLOSED, if the curve should be closed.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_beziercurve_get_step

Group: Bezier curve

Declaration:

IG_vect_beziercurve_get_step(HIG_VECT_ENTITY hEntity, float*
lpStep);

Arguments:

hEntity
Handle to the Entity
lpStep
Buffer for the step

Description:

The function returns step of the Bezier interpolation.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_beziercurve_set_step

Group: Bezier curve

Declaration:

IG_vect_beziercurve_set_step(HIG_VECT_ENTITY hEntity, float
nStep);

Arguments:

hEntity
Handle to the Entity
nStep
Step of the Bezier interpolation being set

Description:

The function sets step of the Bezier interpolation. The value must lie between 0 and 1.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_beziercurve_get_vertexcont

Group: Bezier curve

Declaration:

IG_vect_beziercurve_get_vertexcont(HIG_VECT_ENTITY hEntity,
HIG_VECT_VERTEXCONT* lpVertexcont);

Arguments:

hEntity
Handle to the Entity
lpVertexcont
Buffer for the handle to the Vertex Container

Description:

The function returns Vertex Container with control points describing Bezier curve.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_block_get_entitycont

Group: Block

Declaration:

IG_vect_block_get_entitycont(HIG_VECT_ENTITY hEntity,
HIG_VECT_ENTITYCONT* lpEntitycont);

Arguments:

hEntity
Handle to the Entity
lpEntitycont
Buffer for the handle to the entity container

Description:

The function returns a container contained al entities of the block.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_block_get_name

Group: Block

Declaration:

IG_vect_block_get_name(HIG_VECT_ENTITY hEntity, LPCHAR lpName,
long nSize);

Arguments:

hEntity
Handle to the Entity
lpName
Buffer for the block name
nSize
Maximum size of the buffer

Description:

The function returns block name.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_block_set_name

Group: Block

Declaration:

IG_vect_block_set_name(HIG_VECT_ENTITY hEntity, LPCHAR lpName);

Arguments:

hEntity
Handle to the Entity
lpName
Block name being set

Description:

The function sets block name.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_data_copy

Group: Common functions

Declaration:

IG_vect_data_copy(HIGEAR hIGearSrc, HIGEAR hIGearDst,);

Arguments:

hIGearSrc
Source ImageGear handle
hIGearDst
Destination of ImageGear handle

Description:

This function creates a copy of the vector data attached to hIGearSrc and attaches it to hIGearDst. hIGearDst must be a valid HIGEAR handle.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_data_create

Group: Common functions

Declaration:

IG_vect_data_create(HIGEAR hIGear);

Arguments:

hIGear
ImageGear handle

Description:

This function creates vector data and attaches it to the HIGEAR.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_data_get

Group: Common functions

Declaration:

IG_vect_data_get(HIGEAR hIGear, HIG_VECT_DRWNG* lpVectorData );

Arguments:

hIGear
ImageGear handle
lpVectorData
Vector data handle

Description:

This function provides vector data handle attached to the HIGEAR.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_dblcont_clear

Group: Container

Declaration:

IG_vect_dblcont_clear(HIG_VECT_DBLCONT hCont);

Arguments:

hCont
Handle to the float container

Description:

The function clears the container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_dblcont_get_count

Group: Container

Declaration:

IG_vect_dblcont_get_count(HIG_VECT_DBLCONT hCont, LONG*
lpCount);

Arguments:

hCont
Handle to the float container
lpCount
Count of the returned values

Description:

The function returns a count of values in the container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_dblcont_get_data

Group: Container

Declaration:

IG_vect_dblcont_get_data(HIG_VECT_DBLCONT hCont, FLOAT**
lplpData);

Arguments:

hCont
Handle to the float container
lplpData
Buffer for the data pointer being returned

Description:

The function returns a pointer to the value array.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_dblcont_add_value

Group: Container

Declaration:

IG_vect_dblcont_add_value(HIG_VECT_DBLCONT hCont, FLOAT
fValue);

Arguments:

hCont
Handle to the float container
fValue
Value to be added

Description:

The function adds new value to the end of the container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_dblcont_get_value

Group: Container

Declaration:

IG_vect_dblcont_get_value(HIG_VECT_DBLCONT hCont, LONG nIndex,
FLOAT* lpValue);

Arguments:

hCont
Handle to the float container
nIndex
Position of the value in the container
lpValue
Returned value

Description:

The function returns a value specified by the index.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_dblcont_insert_value

Group: Container

Declaration:

IG_vect_dblcont_insert_value(HIG_VECT_DBLCONT hCont, LONG
nIndex, FLOAT fValue);

Arguments:

hCont
Handle to the float container
mIndex
Position where the value is inserted
fValue
Value being inserted

Description:

The function inserts a value to the specified position.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_dblcont_remove_value

Group: Container

Declaration:

IG_vect_dblcont_remove_value(HIG_VECT_DBLCONT hCont, LONG
nIndex);

Arguments:

hCont
Handle to the float container
nIndex
Position of the value being removed

Description:

The function removes a value specified by the index.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_dblcont_set_value

Group: Container

Declaration:

IG_vect_dblcont_set_value(HIG_VECT_DBLCONT hCont, LONG nIndex,
FLOAT fValue);

Arguments:

hCont
Handle to the float container
nIndex
Position where the value is set
fValue
Value being set

Description:

The function sets specified value to the specified position.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_create_gradientfilltype

Group: Vector Drawing

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_drwng_create_gradientfilltype(HIG_VECT_DRWNG hDrwng,
enumIGVectGradientType nType, LPCHAR lpName, long* lpIndex);

Arguments:

hDrwng
Vector data handle.
nType
Gradient fill type.
lpName
Name of the gradient fill type to be created.
lpIndex
Returns the index of the new gradient fill type.

Description:

Creates new fill type with the gradient object specified by gradient name and type. Returns an index of newly created fill type.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_gradientfilltype

Group: Vector Drawing

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_drwng_get_gradientfilltype(HIG_VECT_DRWNG hDrwng,
LPCHAR lpName, long* lpIndex);

Arguments:

hDrwng
Vector data handle.
lpName
Name of the fill type.
lpIndex
Returns the index of the fill type.

Description:

Returns an index of fill type with the specified gradient object.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_units

Group: Vector Drawing

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_drwng_get_units(
    HIG_VECT_DRWNG hDrwng,
    enumIGVectMeasurementUnits* lpUnits,
    double* lpFactor
    );

Arguments:

hDrwng
Vector data handle
lpUnits
Measurement units returned
lpFactor
Units factor returned

Description:

Sets measurement units associated with a drawing. The measurement units, combined with view size as set by IG_vect_view_set_minmax, can be used to define the physical size of the drawing.


IG_vect_drwng_set_units

Group: Vector Drawing

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_drwng_set_units(
    HIG_VECT_DRWNG hDrwng,
    enumIGVectMeasurementUnits nUnits,
    double fFactor
    );

Arguments:

hDrwng
Vector data handle
nUnits
Measurement units to be set
fFactor
Units factor to be set

Description:

Gets measurement units associated with a drawing. The measurement units, combined with view size as returned by IG_vect_view_get_minmax, can be used to determine the physical size of the drawing.


IG_vect_drwng_get_viewcount

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_viewcount(HIG_VECT_DRWNG hDrwng, long*
lpCount);

Arguments:

hDrwng
handle to the Drawing
lpCount
buffer for the count of View

Description:

The function returns total count of Views in the Drawing.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_create_view

Group: Vector Drawing

Declaration:

IG_vect_drwng_create_view(HIG_VECT_DRWNG hDrwng, HIG_VECT_VIEW*
lpView);

Arguments:

hDrwng
Handle to the Drawing
lpView
Buffer that receives a handle to the newly created View

Description:

The function creates new View and adds it to the end of the view container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_delete_view

Group: Vector Drawing

Declaration:

IG_vect_drwng_delete_view(HIG_VECT_DRWNG hDrwng, long nIndex);

Arguments:

hDrwng
Handle to the Drawing
nIndex
Index of View to be removed

Description:

The function removes the specified View from the internal view container and destroys it.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_view

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_view(HIG_VECT_DRWNG hDrwng, long nIndex,
HIG_VECT_VIEW* lpView);

Arguments:

hDrwng
Handle to the Drawing
nIndex
Index of View to be returned
lpView
Buffer for the View handle

Description:

The function returns View from the specified position.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_viewindex

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_viewindex(HIG_VECT_DRWNG hDrwng,
HIG_VECT_VIEW hView, long* lpIndex);

Arguments:

hDrwng
Handle to the Drawing
hView
Handle of the View
lpIndex
Buffer for the View position

Description:

The function returns View position by View handle.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_activeview

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_activeview(HIG_VECT_DRWNG hDrwng,
HIG_VECT_VIEW* lpView);

Arguments:

hDrwng
Handle to the Drawing
lpView
buffer for the active View handle

Description:

The function returns View that is set as active. Only active View can be displayed at one moment.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_set_activeview

Group: Vector Drawing

Declaration:

IG_vect_drwng_set_activeview(HIG_VECT_DRWNG hDrwng, long
nIndex);

Arguments:

hDrwng
Handle to the Drawing
nIndex
Position of View to be set as Active

Description:

The function sets an active View.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_create_entity

Group: Vector Drawing

Declaration:

IG_vect_drwng_create_entity(HIG_VECT_DRWNG hDrwng,
enumIGVectEntities nType, LPCHAR lpId, HIG_VECT_ENTITY*
lpEntity);

Arguments:

hDrwng
Handle to the Drawing
nType
type of the entity to be created
lpId
Entity identifier being assigned
lpEntity
buffer for the handle to the newly created entirty

Description:

The function creates an entity of the specified type and assigns specified ID to it.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_find_entityindex

Group: Vector Drawing

Declaration:

IG_vect_drwng_find_entityindex(HIG_VECT_DRWNG hDrwng, LPCHAR
lpId, long nStartindex, long* lpIndex);

Arguments:

hDrwng
Handle to the Drawing
lpId
ID of the entity
nStartindex
start index in the internal container. This can be a value returned by previous call to IG_vect_drwng_find_entityindex().
LpIndex
buffer for the entity position

Description:

The function looks for an entity with the specified ID.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_entity

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_entity(HIG_VECT_DRWNG hDrwng, long nIndex,
HIG_VECT_ENTITY* lpEntity);

Arguments:

hDrwng
Handle to the Drawing
nIndex
position of the entity to be returned
lpEntity
buffer for the entity handle

Description:

The function returns an Entity from the specified position in the internal container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_linetypeindex

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_linetypeindex(HIG_VECT_DRWNG hDrwng, long
nPattern, float fPatternlen, long* lpIndex);

Arguments:

hDrwng
Handle to the Drawing
nPattern
Line pattern
fPatternlen
Actual length of the pattern
lpIndex
Buffer for the line type index

Description:

The function returns an index of the line type in the internal container by line pattern and pattern length. If line type with such attributes does still not exist, it is created.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_linetype

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_linetype(HIG_VECT_DRWNG hDrwng, long nIndex,
HIG_VECT_LINETYPE* lpLinetype);

Arguments:

hDrwng
Handle to the Drawing
nIndex
Index of the line type to be returned
lpLinetype
Buffer for line type handle

Description:

The function returns line type by its position in the internal container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_filltypeindex

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_filltypeindex(HIG_VECT_DRWNG hDrwng,
enumIGVectFillPattern nPattern, long nMaterial, long* lpIndex);

Arguments:

hDrwng
Handle to the Drawing
nPattern
Fill pattern
nMaterial
Surface material
lpIndex
Buffer for fill type index

Description:

The function returns an index of the fill type in the internal container by fill pattern and material. If fill type with such attributes does still not exist, it is created.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_filltype

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_filltype(HIG_VECT_DRWNG hDrwng, long nIndex,
HIG_VECT_FILLTYPE* lpFilltype);

Arguments:

hDrwng
Handle to the Drawing
nIndex
Fill type index
lpFilltype
buffer for fill type handle

Description:

The function returns fill type by its position in the internal container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_create_layer

Group: Vector Drawing

Declaration:

IG_vect_drwng_create_layer(HIG_VECT_DRWNG hDrwng, LPCHAR
lpName, HIG_VECT_LAYER* lpLayer);

Arguments:

hDrwng
Handle to the Drawing
lpName
Name of the layer to be created
lpLayer
Buffer for the newly created layer handle

Description:

The function creates a layer with the specified name

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_layer

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_layer(HIG_VECT_DRWNG hDrwng, long nIndex,
HIG_VECT_LAYER* lpLayer);

Arguments:

hDrwng
Handle to the Drawing
nIndex
Index of the layer
lpLayer
Buffer for the layer handle

Description:

The function returns layer by its position in the internal container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_find_layer

Group: Vector Drawing

Declaration:

IG_vect_drwng_find_layer(HIG_VECT_DRWNG hDrwng, LPCHAR lpName,
HIG_VECT_LAYER* lpLayer);

Arguments:

hDrwng
Handle to the Drawing
lpName
Name of the buffer to be looked for
lpLayer
Buffer for the layer handle

Description:

The function looks for the layer by the name.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_layercount

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_layercount(HIG_VECT_DRWNG hDrwng, long*
lpCount);

Arguments:

hDrwng
Handle to the Drawing
lpCount
Buffer for the total count of layers

Description:

The function returns total count of layers in the internal container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_create_font

Group: Vector Drawing

Declaration:

IG_vect_drwng_create_font(HIG_VECT_DRWNG hDrwng, LPCHAR*
lpTypeface, long nWeight, VECT_BOOL bVector, HIG_VECT_FONT*
lpFont);

Arguments:

hDrwng
Handle to the Drawing
lpTypeface
Type face of the font
nWeight
Font weight
bVector
Flag that tells whether Vector or TrueType font is created.
lpFont
Buffer for the font handle

Description:

The function creates a font by typeface and weight. If bVector is VECT_TRUE then an empty vector font is creted. The user is responsible for creating every glyph of such font. Otherwise, complete True Type font is created.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_detect_font

Group: Vector Drawing

Declaration:

IG_vect_drwng_detect_font(HIG_VECT_DRWNG hDrwng, LPCHAR*
lpTypeface, long nWeight, VECT_BOOL bVector, HIG_VECT_FONT*
lpFont);

Arguments:

hDrwng
Handle to the Drawing
lpTypeface
Type face of the font
nWeight
Font weight
bVector
Flag that tells whether Vector or TrueType font is created.
lpFont
Buffer for the font handle

Description:

The function looks for the font with the specified typeface, weigth and vector flag. If the font has been found, its handle is returned in lpFont. Otherwise the return value is NULL.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_font

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_font(HIG_VECT_DRWNG hDrwng, long nIndex,
HIG_VECT_FONT* lpFont);

Arguments:

hDrwng
Handle to the Drawing
nIndex
Position of the font
lpFont
Buffer for the font handle

Description:

The function returns font handle by its position in the internal container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_fontcount

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_fontcount(HIG_VECT_DRWNG hDrwng, long*
lpCount);

Arguments:

hDrwng
Handle to the Drawing
lpCount
Buffer for total count of fonts

Description:

The function returns total count of fonts in the internal container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_graphics

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_graphics(HIG_VECT_DRWNG hDrwng,
enumIGVectGraphics* lpGraphics);

Arguments:

hDrwng
Handle to the Drawing
lpGraphics
Buffer for the graphics type

Description:

The function returns type of graphics used for displaying vector objects. The following graphics types are available:

  • IG_VECT_GRAPH_OPENGL - OpenGL graphics is used
  • IG_VECT_GRAPH_WINAPI - Windows GDI graphics is used
  • IG_VECT_GRAPH_AUTO - the type of graphics (OpenGL or Windows GDI ) is defined according to the device context features.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_set_graphics

Group: Vector Drawing

Declaration:

IG_vect_drwng_set_graphics(HIG_VECT_DRWNG hDrwng,
enumIGVectGraphics nGraphics);

Arguments:

hDrwng
Handle to the Drawing
nGraphics
Graphics type being set

Description:

The function sets type of graphics used for displaying vector objects

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_content

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_content(HIG_VECT_DRWNG hDrwng,
HIG_VECT_ENTITY* lpEntity);

Arguments:

hDrwng
Handle to the Drawing
lpEntity
Buffer for the content handle.

Description:

The function returns main content of the Drawing. This is always block.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_find_selection

Group: Vector Drawing

Declaration:

IG_vect_drwng_find_selection(HIG_VECT_DRWNG hDrwng, long nX,
long nY);

Arguments:

hDrwng
Handle to the Drawing
nX
X device coordinate
nY
Y device coordinate

Description:

The function looks for the entity that corresponds to the device coordinates nX and nY. If the entity has been found, it is placed to the internal entity container together with all including blocks. The user can get a handle to this container from the function IG_vect_drwng_get_selection (). If no entity has been found, the entity container is empty.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_selection

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_selection(HIG_VECT_DRWNG hDrwng,
HIG_VECT_ENTITYCONT* lpEntitycont);

Arguments:

hDrwng
Handle to the Drawing
lpEntitycont
Buffer for the handle to the entity container. If the entity has been found then the container includes hierarchical stricture of blocks with the entity being found on the top. If no entity has been found, the container is empty.

Description:

The function returns an entity container filled with previous call to IG_vect_drwng_find_selection () function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_entityname

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_entityname(HIG_VECT_DRWNG hDrwng,
enumIGVectEntities nType, LPCHAR lpName, long nSize);

Arguments:

hDrwng
Handle to the Drawing
nType
Entity type
lpName
Buffer for the entity name
nSize
Maximum size of the buffer

Description:

The function returns entity name by its type. This is convenient for filling list and combo boxes.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_transparency

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_transparency(HIG_VECT_DRWNG hDrwng,
VECT_BOOL* lpEnable);

Description:

The function returns a flag showing whether or not transparency is enabled. If transparency is enabled, all non-transparent objects are drawn first.

Arguments:

hDrwng
Handle to the Drawing
lpEnable
Buffer for the transparency flag

Description:

The function returns a flag showing whether or not transparency is enabled. If transparency is enabled, all non-transparent objects are drawn first.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_set_transparency

Group: Vector Drawing

Declaration:

IG_vect_drwng_set_transparency(HIG_VECT_DRWNG hDrwng, VECT_BOOL
bEnable);

Arguments:

hDrwng
Handle to the Drawing
bEnable
Flag that enables or disables two-step drawing

Description:

The function enables or disables two-step drawing for correct displaying transparency objects. If transparency is enabled, all non-transparent objects are drawn first.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_selection_color

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_selection_color(HIG_VECT_DRWNG hDrwng,
IGVectColor* lpColor);

Arguments:

hDrwng
Handle to the Drawing
lpColor
Buffer for the selection color being returned

Description:

The function returns color that is used for displaying entities being selected.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_set_selection_color

Group: Vector Drawing

Declaration:

IG_vect_drwng_set_selection_color(HIG_VECT_DRWNG hDrwng,
IGVectColor Color);

Arguments:

hDrwng
Handle to the Drawing
Color
Selection color

Description:

The function sets color that is used for displaying entities being selected.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_get_selection_thickness

Group: Vector Drawing

Declaration:

IG_vect_drwng_get_selection_thickness(HIG_VECT_DRWNG hDrwng,
float* lpThickness);

Arguments:

hDrwng
Handle to the Drawing
lpThickness
Buffer for the selection thickness being returned

Description:

The function returns thickness that is used for displaying entities being selected.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_drwng_set_selection_thickness

Group: Vector Drawing

Declaration:

IG_vect_drwng_set_selection_thickness(HIG_VECT_DRWNG hDrwng,
float fThickness);

Arguments:

hDrwng
Handle to the Drawing
fThickness
Selection thickness

Description:

The function returns thickness that is used for displaying entities being selected.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_easyline_get_startpointptr

Group: Easy line

Declaration:

IG_vect_easyline_get_startpointptr(HIG_VECT_ENTITY hEntity,
IGVectPoint3D** lplpPoint);

Arguments:

hEntity
Handle to the Entity
lplpPoint
Buffer for pointer to the start point

Description:

The function returns a pointer to the start point of the line.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_easyline_get_endpointptr

Group: Easy line

Declaration:

IG_vect_easyline_get_endpointptr(HIG_VECT_ENTITY hEntity,
IGVectPoint3D** lplpPoint);

Arguments:

hEntity
Handle to the Entity
lplpPoint
Buffer for pointer to the end point

Description:

The function returns a pointer to the end point of the line.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_easysurface_init

Group: Easy surface

Declaration:

IG_vect_easysurface_init(HIG_VECT_ENTITY hEntity, long m, long
n);

Arguments:

hEntity
Handle to the Entity
m
New size of the meshes in M direction
n
New size of the meshes in N direction

Description:

The function sets initial size of the meshes in M and N direction.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_easysurface_get_m

Group: Easy surface

Declaration:

IG_vect_easysurface_get_m(HIG_VECT_ENTITY hEntity, long* lpM);

Arguments:

hEntity
Handle to the Entity
lpM
buffer for point count in M direction

Description:

The function returns count of points in M direction.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_easysurface_get_n

Group: Easy surface

Declaration:

IG_vect_easysurface_get_n(HIG_VECT_ENTITY hEntity, long* lpN);

Arguments:

hEntity
Handle to the Entity
lpN
buffer for point count in N direction

Description:

The function returns count of points in N direction.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_easysurface_get_pointptr

Group: Easy surface

Declaration:

IG_vect_easysurface_get_pointptr(HIG_VECT_ENTITY hEntity, long
m, long n, IGVectPoint3D** lplpPoint);

Arguments:

hEntity
Handle to the Entity
m
The row to which the point belongs
n
The column to which the point belongs
lplpPoint
Buffer for the pointer to the specified point

Description:

The function returns a pointer to the point, which belongs to the row with m and column n.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_easysurface_get_flags

Group: Easy surface

Declaration:

IG_vect_easysurface_get_flags(HIG_VECT_ENTITY hEntity, long*
lpFlags);

Arguments:

hEntity
Handle to the Entity
lpFlags
Buffer for the flags

Description:

The function returns different surface flags.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_easysurface_set_flags

Group: Easy surface

Declaration:

IG_vect_easysurface_set_flags(HIG_VECT_ENTITY hEntity, long
nFlags);

Arguments:

hEntity
Handle to the Entity
nFlags
Surface flags being set

Description:

The function sets different surface flags.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ellipse_get_radiusx

Group: Ellipse

Declaration:

IG_vect_ellipse_get_radiusx(HIG_VECT_ENTITY hEntity, float*
lpRadiusx);

Arguments:

hEntity
Handle to the Entity
lpRadiusx
Buffer for the x radius

Description:

The function returns a radius of the ellipse along the x-axes.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ellipse_set_radiusx

Group: Ellipse

Declaration:

IG_vect_ellipse_set_radiusx(HIG_VECT_ENTITY hEntity, float
fRadiusx);

Arguments:

hEntity
Handle to the Entity
fRadiusx
x radius being set

Description:

The function sets a radius of the ellipse along the x-axes.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ellipse_get_radiusy

Group: Ellipse

Declaration:

IG_vect_ellipse_get_radiusy(HIG_VECT_ENTITY hEntity, float*
lpRadiusy);

Arguments:

hEntity
Handle to the Entity
lpRadiusy
Buffer for the y radius

Description:

The function returns a radius of the ellipse along the y-axes.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ellipse_set_radiusy

Group: Ellipse

Declaration:

IG_vect_ellipse_set_radiusy(HIG_VECT_ENTITY hEntity, float
fRadiusy);

Arguments:

hEntity
Handle to the Entity
fRadiusy
y radius being set

Description:

The function sets a radius of the ellipse along the y-axes.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_get_type

Group: Common entity

Declaration:

IG_vect_ent_get_type(HIG_VECT_ENTITY hEntity,
enumIGVectEntities* lpType);

Arguments:

hEntity
Handle to the Entity
lpType
Buffer for the entity type
nSize
Maximum size of the buffer

Description:

The function returns a type of the entity.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_get_ID

Group: Common entity

Declaration:

IG_vect_ent_get_ID(HIG_VECT_ENTITY hEntity, LPCHAR lpID, LONG
nSize);

Arguments:

hEntity
Handle to the Entity
lpID
buffer to get an entity ID
nSize
Maximum size of the buffer

Description:

The function returns an entity identifier.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_set_ID

Group: Common entity

Declaration:

IG_vect_ent_set_ID(HIG_VECT_ENTITY hEntity, LPCHAR lpID);

Arguments:

hEntity
Handle to the Entity
lpID
Entity ID being set

Description:

The function sets an entity ID.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_get_layer

Group: Common entity

Declaration:

IG_vect_ent_get_layer(HIG_VECT_ENTITY hEntity, HIG_VECT_LAYER*
lpLayer);

Arguments:

hEntity
Handle to the Entity
lpLayer
Buffer for the layer handle

Description:

The function returns a handle to the layer attached to the entity (that is, the layer the entity belongs to). If there is not layer associated with the entity, lpLayer is set to NULL.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_set_layer

Group: Common entity

Declaration:

IG_vect_ent_set_layer(HIG_VECT_ENTITY hEntity, HIG_VECT_LAYER
hLayer);

Arguments:

hEntity
Handle to the Entity
lpLayer
Buffer for the layer handle

Description:

The function sets a handle to the layer attached to the entity (that is, the layer the entity belongs to).

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_get_minmax

Group: Common entity

Declaration:

IG_vect_ent_get_minmax(HIG_VECT_ENTITY hEntity, IGVectMinMax*
lpMinmax);

Arguments:

hEntity
Handle to the Entity
lpMinmax
Buffer for minimum and maximum entity coordinates

Description:

The function calculates a cube completely including an entity.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_copy_to

Group: Common entity

Declaration:

IG_vect_ent_copy_to(HIG_VECT_ENTITY hEntitySrc, HIG_VECT_ENTITY
hEntityDst);

Arguments:

hEntity
Handle to the Entity
hEntityDst
Handle to the destination Entity

Description:

The function copies one entity to another. hEntitySrc and hEntityDst must be valid entity handles. These entities can belong to different Drawings.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_set_dirty

Group: Common entity

Declaration:

IG_vect_ent_set_dirty(HIG_VECT_ENTITY hEntity);

Arguments:

hEntity
Handle to the Entity

Description:

The function marks an entity as dirty. Some entities contain intermediate data which are calculated only once and used directly for entity drawing. This is done for high performance. The user must call this function every time when any changes in the entity are done.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_get_selected

Group: Common entity

Declaration:

IG_vect_ent_get_selected(HIG_VECT_ENTITY hEntity, VECT_BOOL*
lpSelected);

Arguments:

hEntity
Handle to the Entity
lpSelected
Buffer for the selection flag

Description:

The function returns a flag indicating whether an entity is selected or not. Selected entity is displayed by the color that is set as selection color for the Drawing.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_set_selected

Group: Common entity

Declaration:

IG_vect_ent_set_selected(HIG_VECT_ENTITY hEntity, VECT_BOOL
bSelected);

Arguments:

hEntity
Handle to the Entity
bSelected
Selection flag being set

Description:

The function marks an entity as selected.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_get_deleted

Group: Common entity

Declaration:

IG_vect_ent_get_deleted(HIG_VECT_ENTITY hEntity, VECT_BOOL*
lpDeleted);

Arguments:

hEntity
Handle to the Entity
lpDeleted
Buffer that receives deleted flag

Description:

The function returns a flag specifying whether or not an entity is marked as deleted. When an entity is marked as deleted, it is not actually removed but becomes invisible. The user can query all entities and undo delete operation. Deleted entities are not saved in the files.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_set_deleted

Group: Common entity

Declaration:

IG_vect_ent_set_deleted(HIG_VECT_ENTITY hEntity, VECT_BOOL
bDeleted);

Arguments:

hEntity
Handle to the Entity
bDeleted
Deleted flag being set

Description:

The function sets or clears deleted flag of the entity.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_get_attribflags

Group: Common entity

Declaration:

IG_vect_ent_get_attribflags(HIG_VECT_ENTITY hEntity, LONG*
lpFlags);

Arguments:

hEntity
Handle to the Entity
lpFlags
Optional attributes flag being returned

Description:

The Entity may have different optional attributes such as draw color, fill color, line type, fill type, offset, rotation, scale and position. These attributes do not exist until they will be created. The function returns flags indicating which optional attributes are presented for the entity.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_get_attrib

Group: Common entity

Declaration:

IG_vect_ent_get_attrib(HIG_VECT_ENTITY hEntity,
enumIGVectAttrib nAttrib, VOID** lplpAttribPtr);

Arguments:

hEntity
Handle to the Entity
nAttrib
The constant specifying which attribute should be returned
lpAttribPtr
Buffer that receives a pointer or handle to the attribute. Buffer type depends on the nAttrib parameter.

The attribute type is associated with the buffer type as followed:

Attribute type
Buffer type
IG_VECT_ENT_ATTR_DRAWCOLOR
IGVectColorEx*
IG_VECT_ENT_ATTR_FILLCOLOR
IGVectColorEx*
IG_VECT_ENT_ATTR_LINETYPEINDEX
long*
IG_VECT_ENT_ATTR_THICKNESS
float*
IG_VECT_ENT_ATTR_FILLTYPEINDEX
long*
IG_VECT_ENT_ATTR_OFFSET
IGPoint3D*
IG_VECT_ENT_ATTR_ROTATION
HIG_VECT_ROTATION
IG_VECT_ENT_ATTR_SCALE
IGPoint3D*
IG_VECT_ENT_ATTR_POSITION
IGPoint3D*

Description:

The function returns a pointer to the optional attribute specified by the parameter nAttrib.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_create_attrib

Group: Common entity

Declaration:

IG_vect_ent_create_attrib(HIG_VECT_ENTITY hEntity,
enumIGVectAttrib nAttrib, VOID** lplpAttribPtr);

Arguments:

hEntity
Handle to the Entity
nAttrib
Attribute being created
kpAttribPtr
Buffer that receives a pointer or handle to the attribute. See IG_vect_ent_get_attrib () for description.

Description:

The function creates new attribute specified by nAttrib and returns a pointer to the attribute being created.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_ent_remove_attrib

Group: Common entity

Declaration:

IG_vect_ent_remove_attrib(HIG_VECT_ENTITY hEntity,
enumIGVectAttrib nAttrib);

Arguments:

hEntity
Handle to the Entity
nAttrib
Attribute being removed

Description:

The function removes and destroys an attribute.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_entcont_get_count

Group: Entity container

Declaration:

IG_vect_entcont_get_count(HIG_VECT_ENTITYCONT hEntitycont,
long* lpCount);

Arguments:

hEntitycont
Handle to the Entity Container
lpCount
Buffer for the count of entities in the entity container

Description:

The function returns a count of entities in the entity container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_entcont_add_entity

Group: Entity container

Declaration:

IG_vect_entcont_add_entity(HIG_VECT_ENTITYCONT hEntitycont,
HIG_VECT_ENTITY hEntity);

Arguments:

hEntitycont
Handle to the Entity Container
hEntity
Handle to the entity being added at the tail of the container

Description:

The function adds an entity to the entity container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_entcont_remove_entity

Group: Entity container

Declaration:

IG_vect_entcont_remove_entity(HIG_VECT_ENTITYCONT hEntitycont,
long nIndex);

Arguments:

hEntitycont
Handle to the Entity Container
nIndex
Index of the entity being removed

Description:

The function removes an entity specified by nIndex from the container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_entcont_get_entity

Group: Entity container

Declaration:

IG_vect_entcont_get_entity(HIG_VECT_ENTITYCONT hEntitycont,
long nIndex, HIG_VECT_ENTITY* lpEntity);

Arguments:

hEntitycont
Handle to the Entity Container
nIndex
Index of the entity being returned
lpEntity
Buffer for the handle to the entity

Description:

The function returns an entity specified by nIndex.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_entcont_get_index

Group: Entity container

Declaration:

IG_vect_entcont_get_index(HIG_VECT_ENTITYCONT hEntitycont,
HIG_VECT_ENTITY hEntity, long* lpIndex);

Arguments:

hEntitycont
Handle to the Entity Container
hEntity
Handle to the entity being found in the container
lpIndex
Buffer for the entity index

Description:

The function looks for the index by the entity handle.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_figure_get_fillmode

Group: Figure

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_figure_get_fillmode(
    HIG_VECT_ENTITY hEntity,
    enumIGVectFillMode* lpFillMode
    );

Arguments:

hEntity
Figure entity handle
lpFillMode
Buffer for the figure fill mode

Description:

This function returns a fill mode of the figure. See enumIGVectFillMode enumeration for possible values.

Bits Per Pixel: All

Return Value:

Returns a fill mode of the figure or the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_figure_set_fillmode

Group: Figure

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_figure_set_fillmode(
    HIG_VECT_ENTITY hEntity,
    enumIGVectFillMode nFillMode
    );

Arguments:

hEntity
Figure entity handle
nFillMode
Fill mode to be set

Description:

This function sets a fill mode for the figure. See enumIGVectFillMode enumeration for possible values.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_figure_get_entitycont

Group: Figure

Declaration:

IG_vect_figure_get_entitycont(HIG_VECT_ENTITY hEntity,
HIG_VECT_ENTITYCONT* lpEntitycont);

Arguments:

hEntity
Handle to the Entity
lpEntitycont
Buffer for the handle to the Entity Container

Description:

The function returns an entity container defining the current region. Current region is set by IG_vect_figure_set_region () function.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_figure_get_regioncount

Group: Figure

Declaration:

IG_vect_figure_get_regioncount(HIG_VECT_ENTITY hEntity, long*
lpCount);

Arguments:

hEntity
Handle to the Entity
lpCount
Buffer for the region count

Description:

The function returns a total count of regions in the figure.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_figure_set_region

Group: Figure

Declaration:

IG_vect_figure_set_region(HIG_VECT_ENTITY hEntity, long
nRegion);

Arguments:

hEntity
Handle to the Entity
nRegion
Current region being set

Description:

The function sets the current region.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_filltype_get_gradient

Group: Fill Type

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_filltype_get_gradient(HIG_VECT_FILLTYPE hFilltype,
HIG_VECT_GRADIENT* lpGradient);

Arguments:

hFilltype
Handle to the Fill Type.
lpGradient
Returns handle to the gradient object associated with the specified fill type.

Description:

Returns gradient a object associated with the fill type.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_filltype_get_pattern

Group: Fill type

Declaration:

IG_vect_filltype_get_pattern(HIG_VECT_FILLTYPE hFilltype,
enumIGVectFillPattern* lpPattern);

Arguments:

hFilltype
Handle to the Fill Type
lpPattern
Fill pattern being returned

Description:

The function returns a constant defining a fill pattern. See enumIGVectFillPattern for possible values.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_filltype_get_material

Group: Fill type

Declaration:

IG_vect_filltype_get_material(HIG_VECT_FILLTYPE hFilltype,
LONG* lpMaterial);

Arguments:

hFilltype
Handle to the Fill Type
lpMaterial
Index of the material in the internal container being returned

Description:

The function returnes a material of the surface. This function is not implemented yet. Assuming, the material will be described by diffusion, emission and so on.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_font_get_typeface

Group: Common font

Declaration:

IG_vect_font_get_typeface(HIG_VECT_FONT hFont, LPCHAR
lpTypefase, LONG nSize);

Arguments:

hFont
Handle to the font
lpTypefase
Buffer for the typeface
nSize
Maximum size of the buffer

Description:

The function returns the font type face.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_font_get_weight

Group: Common font

Declaration:

IG_vect_font_get_weight(HIG_VECT_FONT hFont, LONG* lpWeight);

Arguments:

hFont
Handle to the font
lpWeight
Font weight being returned

Description:

The function returns the font weight.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_font_is_vector

Group: Common font

Declaration:

IG_vect_font_is_vector(HIG_VECT_FONT hFont, VECT_BOOL*
lpIsVector);

Arguments:

hFont
Handle to the font
lpIsVector
Boolean value being returned

Description:

The function tells whether the font is vector or True Type.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_font_get_glyph

Group: Common font

Declaration:

IG_vect_font_get_glyph(HIG_VECT_FONT hFont, long nInex,
HIG_VECT_VERTEXCONT* lpGlyph);

Arguments:

hFont
Handle to the font
nIdex
Index of the glyph to be returned
lpGlyph
The glyph being returned

Description:

The function returns Vertex Container for access to the Vector glyph.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_font_get_glyphcount

Group: Common font

Declaration:

IG_vect_font_get_glyphcount(HIG_VECT_FONT hFont, LONG*
lpCount);

Arguments:

hFont
Handle to the font
lpCount
Glyph count being returned

Description:

The function returns number of glyphs in the vector font.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_font_set_glyphcount

Group: Common font

Declaration:

IG_vect_font_set_glyphcount(HIG_VECT_FONT hFont, LONG nCount);

Arguments:

hFont
Handle to the font
nCount
Count of glyphs being set

Description:

The function sets a size ( count of glyphs) of the vector font. The user must set the correct size before filling the glyphs.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_get_coloralign

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_get_coloralign(
    HIG_VECT_ENTITY hEntity,
    long* lpColorAlign);

Arguments:

hEntity
Geometry entity handle
lpColorAlign
The buffer for the color alignment

Description:

This function returns a color alignment of the geometry. Possible values are 3 (RGB) or 4 (RGBA).

Bits Per Pixel: All

Return Value:

Returns the color alignment of the geometry or the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_get_colors

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_get_colors(
    HIG_VECT_ENTITY hEntity,
    unsigned char* lpColors,
    long nStart,
    long nEnd);

Arguments:

hEntity
Geometry entity handle
lpColors
buffer for the local colors of the geometry
nStart
Index of the start color
nEnd
Index of the end color

Description:

This function returns the geometry colors in the range of nStart.. nEnd. Using this function makes sense only if the argument bUseColors of IG_vect_geom_init () is set to VECT_TRUE.

The number of the color components is defined by nColorAlign argument of IG_vect_geom_init (). The color buffer must be long enough to receive (nEnd - nStart + 1) * nColorAlign bytes.

Bits Per Pixel: All

Return Value:

Returns the geometry colors or the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_get_normals

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_get_normals(
    HIG_VECT_ENTITY hEntity,
    VECT_REAL* lpNormals,
    long nStart,
    long nEnd);

Arguments:

hEntity
Geometry entity handle
lpNormals
Buffer for the geometry normals
nStart
Start index of the normal
nEnd
End index of the normal

Description:

The function returns the geometry normals in the range of nStart..nEnd. Using this function makes sense only if argument bUseNormals of IG_vect_geom_init () was set to VECT_TRUE.

The normal buffer must be long enough to receive (nEnd - nStart + 1) * 3 floating point values.

Bits Per Pixel: All

Return Value:

Returns the geometry normals or the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_get_pointcount

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_get_pointcount(
    HIG_VECT_ENTITY hEntity,
    long* lpPointCount);

Arguments:

hEntity
Geometry entity handle
lpPointCount
Buffer for the point count of the geometry.

Description:

The function returns the total point count of the geometry. The return value is also corresponds to the color count and (or) normal count if the arguments bUseColors and/or bUseNormals of IG_vect_geom_init () was set to VECT_TRUE.

Bits Per Pixel: All

Return Value:

Returns the total point count of the geometry or the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_get_points

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_get_points(
    HIG_VECT_ENTITY hEntity,
    VECT_REAL* lpPoints,
    long nStart,
    long nEnd);

Arguments:

hEntity
Geometry entity handle
lpPoints
Buffer for the geometry points
nStart
Start point to be returned
nEnd
End point to be returned

Description:

This function returns the geometry points in the range of nStart..nEnd. The point buffer must be long enough to receive (nEnd - nStart + 1) * 3 floating point values.

Bits Per Pixel: All

Return Value:

Returns the geometry points or the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_get_type

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_get_type(
    HIG_VECT_ENTITY hEntity,
    enumIGVectGeometryType* lpType);

Arguments:

hEntity
Geometry entity handle
lpType
Buffer for the geometry type.

Description:

This function returns the geometry type. See IG_vect_geom_init () for possible values.

Bits Per Pixel: All

Return Value:

Returns the geometry type or the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_get_usecolors

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_get_usecolors(
    HIG_VECT_ENTITY hEntity,
    VECT_BOOL* lpUseColors);

Arguments:

hEntity
Geometry entity handle
lpUseColors
Buffer for the using colors flag.

Description:

This function returns a flag that tells whether or not the geometry uses the local colors. This flag is set when geometry initializes in IG_vect_geom_init () function call.

Bits Per Pixel: All

Return Value:

Returns a flag that tells whether or not the geometry uses the local colors or the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_get_usenormals

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_get_usenormals(
    HIG_VECT_ENTITY hEntity,
    VECT_BOOL* lpUseNormals);

Arguments:

hEntity
Geometry entity handle
lpUseNormals
Buffer for the using normals flag

Description:

This function returns a flag that tells whether or not the geometry uses the normals. This flag is set when geometry initializes in IG_vect_geom_init () function call.

Bits Per Pixel: All

Return Value:

Returns the flag that tells whether or not the geometry uses the normals or the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_init

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_init(
    HIG_VECT_ENTITY hEntity,
    enumIGVectGeometryType nType,
    long nPointCount,
    long nColorAlign,
    VECT_BOOL bUseNormals,
    VECT_BOOL bUseColors);

Arguments:

hEntity
Geometry entity handle
nType
Type of the geometry
nPointCount
Geometry point count
nColorAlign
Color alignment
bUseNormals
Normals usage flag
bUseColors
Local colors usage flag

Description:

The function initializes the geometry entity. An argument nType can be one of the following values:

  • IG_VECT_GEOM_POINTS = 0 - geometry is a set of separated points
  • IG_VECT_GEOM_LINES = 1 - geometry is a group of separated lines
  • IG_VECT_GEOM_LINE_LOOP = 2 - geometry is a group of line segments. The last line is connected to the first one.
  • IG_VECT_GEOM_LINE_STRIP = 3 - geometry is a group of line segments
  • IG_VECT_GEOM_TRIANGLES = 4 - geometry is a group of separated triangles
  • IG_VECT_GEOM_TRIANGLE_STRIP = 5 - geometry is a triangle strip
  • IG_VECT_GEOM_TRIANGLE_FAN = 6 - geometry is a triangle fan
  • IG_VECT_GEOM_QUADS = 7 - geometry is a group of separated qadrilaterals
  • IG_VECT_GEOM_QUAD_STRIP = 8 - geometry is aquadrilateral strip
  • IG_VECT_GEOM_POLYGON = 9 - geometry is a polygon

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_set_colors

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_set_colors(
    HIG_VECT_ENTITY hEntity,
    unsigned char* lpColors,
    long nStart,
    long nEnd);

Arguments:

hEntity
Geometry entity handle
lpColors
Buffer with the colors to be set
nStart
Start color to be set
nEnd
End color to be set

Description:

This function sets the colors in the range of nStart..nEnd. Using this function makes sense only if bUseColors argument was set to VECT_TRUE during the geometry initialization. The color component number must correspond to the nColorAlign argument of IG_vect_geom_init ().

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_set_normals

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_set_normals(
    HIG_VECT_ENTITY hEntity,
    VECT_REAL* lpNormals,
    long nStart,
    long nEnd);

Arguments:

hEntity
Geometry entity handle
lpNormals
Buffer with the normals to be set
nStart
Start normal index
nEnd
End normal index

Description:

This function sets the geometry normals in the range of nStart..nEnd. The function make sense only if bUseColors argument was set to VECT_TRUE during the geometry initialization.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_add_stop

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_gradient_add_stop(HIG_VECT_GRADIENT
hGradient, VECT_REAL fStopOffset, IGVectColorEx StopColor);

Arguments:

hGradient
Handle to a gradient object.
fStopOffset
Offset of the new gradient stop.
StopColor
Color of the new gradient stop.

Description:

Adds new stop to the gradient. A stop is defined by its offset and color.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_get_matrix

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_get_matrix(HIG_VECT_GRADIENT hGradient,
VECT_REAL* lpMat4x4);

Arguments:

hGradient
Handle to a gradient object.
lpMat4x4
Pointer to a memory buffer to recieve a copy of the gradient transformation matrix. The buffer must be big enough to store 16 VECT_REAL values.

Description:

Returns gradient transformation matrix.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_get_name

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_gradient_get_name(HIG_VECT_GRADIENT
hGradient, LPCHAR lpName, LONG nSize);

Arguments:

hGradient
Handle to a gradient object.
lpName
Pointer to a memory buffer to recieve the name of the gradient object.
nSize
Size of the memory buffer.

Description:

Returns gradient name.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_get_spreadmethod

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_get_spreadmethod(HIG_VECT_GRADIENT hGradient,
enumIGVectGradientSpreadMethod* lpnSpreadMethod);

Arguments:

hGradient
Handle to a gradient object.
lpnSpreadMethod
Returns spread method of the gradient object.

Description:

Returns spread method of the specified gradient. Spread method specifies how the gradient is expanded. See enumIGVectGradientSpreadMethod enumeration for the list of available spread methods.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_get_stopcolor

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_get_stopcolor(HIG_VECT_GRADIENT hGradient,
LONG nStopIndex, IGVectColorEx* lpnStopColor);

Arguments:

hGradient
Handle to a gradient object.
nStopIndex
Stop index.
lpnStopColor
Returns the color of the specified stop.

Description:

Returns a color of the specified stop.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_get_stopcount

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_get_stopcount(HIG_VECT_GRADIENT hGradient,
LONG* lpnStopCount);

Arguments:

hGradient
Handle to a gradient object.
lpnStopCount
Returns the number of stops for the specified gradient object.

Description:

Returns the number of stops for the specified gradient object.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_get_stopoffset

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_get_stopoffset(HIG_VECT_GRADIENT hGradient,
LONG nStopIndex, VECT_REAL* lpfStopOffset);

Arguments:

hGradient
Handle to a gradient object.
nStopIndex
Stop index.
lpfStopOffset
Returns offset of the specified stop.

Description:

Returns an offset of the specified stop.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_get_type

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_gradient_get_type(HIG_VECT_GRADIENT
hGradient, enumIGVectGradientType* lpnType);

Arguments:

hGradient
Handle to a gradient object.
lpnType
Returns the type of the specified gradient object.

Description:

Returns the type of the specified gradient object. Two types of gradient objects are available: linear and radial.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_linear_get_vector

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_linear_get_vector(HIG_VECT_GRADIENT hGradient,
IGVectPoint3D* lpPt1, IGVectPoint3D* lpPt2, AT_BOOL*
lpbAbsolute);

Arguments:

hGradient
Handle to a gradient object.
lpPt1
Returns start point of the linear gradient.
lpPt2
Returns end point of the linear gradient.
lpbAbsolute
Returns the flag specifying whether the start and end points are relative or absolute.

Description:

Returns start and end points of the linear gradient and a flag specifying whether they are relative or absolute.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_linear_set_vector

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_linear_set_vector(HIG_VECT_GRADIENT hGradient,
IGVectPoint3D Pt1, IGVectPoint3D Pt2, AT_BOOL bAbsolute);

Arguments:

hGradient
Handle to a gradient object.
Pt1
Start point of the linear gradient.
Pt2
End point of the linear gradient.
bAbsolute
Specifies whether the start and end points are relative or absolute.

Description:

Sets parameters of the linear gradient: start and end points and the flag specifying whether they are relative or absoulte.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_radial_get_vector

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_radial_get_vector(HIG_VECT_GRADIENT hGradient,
IGVectPoint3D* lpPtIn, IGVectPoint3D* lpPtOut, VECT_REAL*
lpRadius, AT_BOOL* lpbAbsolute);

Arguments:

hGradient
Handle to a gradient object.
lpPtIn
Returns coordinates the center of the inner circle.
lpPtOut
Returns coordinates the center of the outer circle.
lpRadius
Returns the radius of the outer circle.
lpbAbsolute
Returns the flag specifying whether the gradient vector is relative or absolute.

Description:

Returns parameters of the specified radial gradient: centers of inner and outer circles, outer radius and the flag that specifies whether these values are relative or absolute.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_radial_set_vector

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_radial_set_vector(HIG_VECT_GRADIENT hGradient,
IGVectPoint3D ptIn, IGVectPoint3D ptOut, VECT_REAL fRadius,
AT_BOOL bAbsolute);

Arguments:

hGradient
Handle to a gradient object.
ptIn
Coordinates of the center of the inner circle.
ptOut
Coordinates of the center of the outer circle.
fRadius
Radius of the outer circle.
bAbsolute
Specifies whether circle coordinates and radius are relative or absolute.

Description:

Sets parameters of the specified radial gradient: centers of inner and outer circles, outer radius and the flag that specifies whether these values are relative or absolute.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_remove_stop

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_remove_stop(HIG_VECT_GRADIENT hGradient, LONG
nStopIndex);

Arguments:

hGradient
Handle to a gradient object.
nStopIndex
Index of the stop to remove.

Description:

Removes the specified stop from the gradient.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_set_matrix

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_set_matrix(HIG_VECT_GRADIENT hGradient,
VECT_REAL* lpMat4x4);

Arguments:

hGradient
Handle to a gradient object.
lpMat4x4
Pointer to a buffer containing 4x4 gradient transformation matrix.

Description:

Sets gradient transformation matrix.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_set_spreadmethod

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_set_spreadmethod(HIG_VECT_GRADIENT hGradient,
enumIGVectGradientSpreadMethod nSpreadMethod);

Arguments:

hGradient
Handle to a gradient object.
nSpreadMethod
Spread method.

Description:

Sets spread method for the gradient. See enumIGVectGradientSpreadMethod enumeration for the list of available spread methods.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_set_stopcolor

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_set_stopcolor(HIG_VECT_GRADIENT hGradient,
LONG nStopIndex, IGVectColorEx StopColor);

Arguments:

hGradient
Handle to a gradient object.
nStopIndex
Stop index.
StopColor
New color for the stop.

Description:

Sets new color for the specified stop.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_gradient_set_stopoffset

Group: Gradient

Declaration:

AT_ERRCOUNT ACCUAPI
IG_vect_gradient_set_stopoffset(HIG_VECT_GRADIENT hGradient,
LONG nStopIndex, VECT_REAL fStopOffset);

Arguments:

hGradient
Handle to a gradient object.
nStopIndex
Stop index.
fStopOffset
New offset for the specified stop.

Description:

Sets new offset for the specified stop.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_geom_set_points

Group: Geometry

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_geom_set_points(
    HIG_VECT_ENTITY hEntity,
    VECT_REAL* lpPoints,
    long nStart,
    long nEnd);

Arguments:

hEntity
Geometry entity handle
lpPoints
Buffer with the points to be set
nStart
Start point index
nEnd
End point index

Description:

This function sets the geometry points in the range of nStart..nEnd.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_hatch_create_line

Group: Vector hatch

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_hatch_create_line(
    HIG_VECT_VECTORHATCH hHatch,
    HIG_VECT_HATCHLINE* lpLine);

Arguments:

hHatch
Handle of the hatch
lpLine
Pointer to buffer for the the new hatch line handle

Description:

This function creates a new hatch line and adds it to the hatch.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIG_VECT_HATCHLINE hHatchLine;

IG_vect_hatch_create_line(hHatch, &hHatchLine);

Sample:

None


IG_vect_hatch_delete_line

Group: Vector hatch

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_hatch_delete_line(
    HIG_VECT_VECTORHATCH hHatch,
    long Index);

Arguments:

hHatch
Handle of the hatch
Index
Index of the line to be deleted

Description:

This function removes the hatch line specified with Index from the hatch and destroys it.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

IG_vect_hatch_delete_line(hHatch, 0);

Sample:

None


IG_vect_hatch_get_line

Group: Vector hatch

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_hatch_get_line(
    HIG_VECT_VECTORHATCH hHatch,
    long Index,
    HIG_VECT_HATCHLINE* lpLine);

Arguments:

hHatch
Handle of the hatch
Index
Index of the line in the hatch
lpLine
Pointer to the buffer for the line handle

Description:

This function allows to get the handle of the hatch line specified by the Index.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIG_VECT_HATCHLINE hLine;
IG_vect_hatch_get_line(hHatch, 0, &hLine);

Sample:

None


IG_vect_hatch_get_linecount

Group: Vector hatch

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_hatch_get_linecount(
    HIG_VECT_VECTORHATCH hHatch,
    long* lpLineCount);

Arguments:

hHatch
handle of the hatch
lpLineCount
pointer to the output count of lines in the hatch

Description:

This function allows gettig the total line count in the hatch.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

long nLineCount;
IG_vect_hatch_get_linecount(hHatch, &nLineCount);

Sample:

None


IG_vect_hatchline_get_basepoint

Group: Vector hatch

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_hatchline_get_basepoint(
    HIG_VECT_HATCHLINE hHatchline,
    IGVectPoint2D** lplpBasePoint);

Arguments:

hHatchline
handle of the hatch line
lplpBasePoint
double pointer to the base point being returned

Description:

This function allows getting the pointer to the base point of the hatch line. The base point is a start point of the first line in the the hatch.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

IGVectPoint2D* lpBasePoint;
IG_vect_hatch_get_basepoint(hHatchLine, &lpBasePoint);

Sample:

None


IG_vect_hatchline_get_lineangle

Group: Vector hatch

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_hatchline_get_lineangle(
    HIG_VECT_HATCHLINE hHatchline,
    float* lpLineAngle);

Arguments:

hHatchline
Handle of the hatch line
lpLineAngle
pointer to the buffer for the line angle

Description:

This function allows to get the angle of the specified hatch line in radians.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

float dblLineAngle;
IG_vect_hatchline_get_lineangle(hHatchLine, &dblLineAngle);

Sample:

None


IG_vect_hatchline_set_lineangle

Group: Vector hatch

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_hatchline_set_lineangle(
    HIG_VECT_HATCHLINE hHatchline,
    float LineAngle);

Arguments:

hHatchline
handle of the hatch line
LineAngle
hatch line angle to be set

Description:

This function allows to set an angle for the specified hatch line in radians.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

IG_vect_hatchline_set_lineangle(hHatchLine, IG_VECT_PI / 2);

Sample:

None


IG_vect_hatchline_get_offset

Group: Vector hatch

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_hatchline_get_offset(
    HIG_VECT_HATCHLINE hHatchline,
    IGVectPoint2D** lplpOffsetPoint);

Arguments:

hHatchline
handle of the hatch line
lplpOffsetPoint
double pointer to the hatch line offset point

Description:

This function allows to get a pointer to the hatch line offset. X and Y offset coordinates specify distance between lines in the hatch.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

IGVectPoint2D* lpOffsetPoint;
IG_vect_hatchline_get_offset(hHatchline, &lpBasePoint);

Sample:

None


IG_vect_hatchline_get_pattern

Group: Vector hatch

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_hatchline_get_pattern(
    HIG_VECT_HATCHLINE hHatchline,
    HIG_VECT_DBLCONT* lpPattern);

Arguments:

hHatchline
handle of the hatch line
lpPattern
pointer to the handle of the pattern container

Description:

This function allows to get a container with floating point values specifying the hatch line pattern. First value in the container corresponds to "pen down", second - to "pen up", and so on.

Bits Per Pixel:

N/A

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Example:

HIG_VECT_DBLCONT hPattern;
IG_vect_hatchline_get_pattern(hHatchLine, &hPattern);

Sample:

None


IG_vect_insertion_get_blockref

Group: Insertion

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_insertion_get_blockref(
    HIG_VECT_ENTITY hEntity,
    HIG_VECT_ENTITY* lpBlockRef
    );

Arguments:

hEntity
Insertion entity handle
lpBlockRef
Buffer for the block handle

Description:

This function returns the handle of the block attached to the insertion.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_insertion_set_blockref

Group: Insertion

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_insertion_set_blockref(
    HIG_VECT_ENTITY hEntity,
    HIG_VECT_ENTITY hBlockRef
    );

Arguments:

hEntity
Insertion entity handle
hBlockRef
Handle of the block to be attached to the insertion

Description:

This function attaches the block to the insertion

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layer_get_name

Group: Layer

Declaration:

IG_vect_layer_get_name(HIG_VECT_LAYER hLayer, LPCHAR lpName,
LONG nSize);

Arguments:

hLayer
Handle to the Layer
lpName
Buffer for the layer name
nSize
Maximum size of the buffer

Description:

The function returns the name of the layer.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layer_set_name

Group: Layer

Declaration:

IG_vect_layer_set_name(HIG_VECT_LAYER hLayer, LPCHAR lpName);

Arguments:

hLayer
Handle to the Layer
lpName
Layer name being set

Description:

The function sets the layer name.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layer_get_hidden

Group: Layer

Declaration:

IG_vect_layer_get_hidden(HIG_VECT_LAYER hLayer, VECT_BOOL*
lpHidden);

Arguments:

hLayer
Handle to the Layer
lpHidden
Buffer for the hidden attribute

Description:

The function returns a flag specifying whether the layer is hidden, or not. If an entity belongs to the hidden layer, it is not displayed.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layer_set_hidden

Group: Layer

Declaration:

IG_vect_layer_set_hidden(HIG_VECT_LAYER hLayer, VECT_BOOL
nHidden);

Arguments:

hLayer
Handle to the Layer
nHidden
Attribute being set. If VECT_TRUE then the layer is hidden.

Description:

The function sets nHidden attribute for the layer.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layer_get_attribflags

Group: Layer

Declaration:

IG_vect_layer_get_attribflags(HIG_VECT_LAYER hLayer, LONG*
lpFlags);

Arguments:

hLayer
Handle to the Layer
lpFlags
Buffer for the optional attributes flag.

Description:

The layer may have different optional attributes such as draw color, fill color, line type, fill type. These attributes can be inherited by the entity, which belongs to the layer. The function returns flags indicating which optional attributes are presented for the layer.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layer_get_attrib

Group: Layer

Declaration:

IG_vect_layer_get_attrib(HIG_VECT_LAYER hLayer,
enumIGVectAttrib nAttrib, VOID** lplpAttribPtr);

Arguments:

hLayer
Handle to the Layer
nAttrib
Constant specifying which attribute should be returned.
lpAttribPtr
Buffer that receives a pointer or handle to the attribute. Buffer type depends on the nAttrib parameter.

The attribute type is associated with the buffer type as followed:

Attribute type
Buffer type
IG_VECT_ENT_ATTR_DRAWCOLOR
IGVectColorEx*
IG_VECT_ENT_ATTR_FILLCOLOR
IGVectColorEx*
IG_VECT_ENT_ATTR_LINETYPEINDEX
long*
IG_VECT_ENT_ATTR_THICKNESS
float*
IG_VECT_ENT_ATTR_FILLTYPEINDEX
long*

Description:

The function returns a pointer to the optional attribute specified by the parameter nAttrib.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layer_create_attrib

Group: Layer

Declaration:

IG_vect_layer_create_attrib(HIG_VECT_LAYER hLayer,
enumIGVectAttrib nAttrib, VOID** lplpAttribPtr);

Arguments:

hLayer
Handle to the Layer
nAttrib
Type of the attribute being created.
lpAttribPtr
Buffer that receives a pointer or handle to the attribute. See IG_vect_layer_get_attrib () for description..

Description:

The function creates new attribute specified by nAttrib and returns a pointer to the attribute being created.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layer_remove_attrib

Group: Layer

Declaration:

IG_vect_layer_remove_attrib(HIG_VECT_LAYER hLayer,
enumIGVectAttrib nAttrib);

Arguments:

hLayer
Handle to the Layer
nAttrib
Attribute being removed.

Description:

The function removes and destroys an attribute.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layercont_add_layer

Group: Layer container

Declaration:

IG_vect_layercont_add_layer(HIG_VECT_LAYERCONT hLayercont,
HIG_VECT_LAYER hLayer);

Arguments:

hLayercont
handle to Layer container
hLayer
handle to the Layer being added

Description:

The function adds a layer to the layer container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layercont_get_layer

Group: Layer container

Declaration:

IG_vect_layercont_get_layer(HIG_VECT_LAYERCONT hLayercont, long
nIndex, HIG_VECT_LAYER* lpLayer);

Arguments:

hLayercont
Handle to Layer container
nIndex
Index of the layer to be returned
lpLayer
Buffer for the layer being returned

Description:

The function returns a layer by the index.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layercont_find_layer

Group: Layer container

Declaration:

IG_vect_layercont_find_layer(HIG_VECT_LAYERCONT hLayercont,
LPCHAR lpName, HIG_VECT_LAYER* lpLayer);

Arguments:

hLayercont
Handle to Layer container
lpName
Name of the layer to be looked for
lpLayer
Buffer for the layer being returned

Description:

The function looks for a layer by the name.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layercont_remove_layer

Group: Layer container

Declaration:

IG_vect_layercont_remove_layer(HIG_VECT_LAYERCONT hLayercont,
long nIndex);

Arguments:

hLayercont
Handle to Layer container
nIndex
Index of the layer to be removed

Description:

The function removes specified layer from the container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_layercont_get_count

Group: Layer container

Declaration:

IG_vect_layercont_get_count(HIG_VECT_LAYERCONT hLayercont,
long* lpCount);

Arguments:

hLayercont
Handle to Layer container
lpCount
Buffer for the count being returned

Description:

The function returns a total count of layers in the container.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_get_ambient

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_get_ambient(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpAmbient
    );

Arguments:

hLightSource
Light source handle
lpAmbient
Buffer for four ambient color components

Description:

This function returns four components (red, green, blue and alpha) of the light source ambient color. The component range is usually 0..1.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_get_attenuation

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_get_attenuation(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpConstant,
    float* lpLinear,
    float* lpQuadratic
    );

Arguments:

hLightSource
Light source handle
lpConstant
Buffer for the constant attenuation factor
lpLinear
Buffer for the linear attenuation factor
lpQuadratic
Buffer for the quadratic attenuation factor

Description:

This function returns the constant, linear and quadratic attenuation factors of the light source.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_get_cutoff

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_get_cutoff(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpCutoff
    );

Arguments:

hLightSource
Light source handle
lpCutoff
Buffer for the cut off angle

Description:

This function returns the cut of angle of the light source. The range of cut off angle is 0..90 or 180 degrees. 180 degrees mean uniform light distribution.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_get_diffuse

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_get_diffuse(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpDiffuse
    );

Arguments:

hLightSource
Light source handle
lpDiffuse
Buffer for four diffuse color components

Description:

This function returns four components (red, green, blue and alpha) of the light source diffuse color. The component range is usually 0..1.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_get_direction

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_get_direction(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpDirection
    );

Arguments:

hLightSource
Light source handle
lpDirection
Buffer for three direction components

Description:

This function returns three direction components (nx, ny, nz) of the light source.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_get_enabled

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_get_enabled(
    HIG_VECT_LIGHTSOURCE hLightSource,
    VECT_BOOL* lpEnabled
    );

Arguments:

hLightSource
Light source handle
lpEnabled
Buffer for the enabling state value.

Description:

This function returns an enabling state of the light source. VECT_FALSE means the light source is disabled.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_get_exponent

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_get_exponent(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpExponent
    );

Arguments:

hLightSource
Light source handle
lpExponent
Buffer for the light spot exponent

Description:

This function returns a spot exponent of the light source. The range of the spot exponent is 0..128.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_get_position

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_get_position(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpPosition
    );

Arguments:

hLightSource
Light source handle
lpPosition
Buffer for three position components

Description:

The function returns three position components (x, y, z) of the light source.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_get_specular

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_get_specular(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpSpecular
    );

Arguments:

hLightSource
Light source handle
lpSpecular
Buffer for four specular color components

Description:

This function returns four components (red, green, blue and alpha) of the light source ambient color. The component range is usually 0..1.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_set_ambient

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_set_ambient(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpAmbient
    );

Arguments:

hLightSource
Light source handle
lpAmbient
Buffer with four ambient color components to be set

Description:

The function sets four ambient color components (red, green, blue and alpha) for the light source. Usually the component range is 0..1.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_set_attenuation

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_set_attenuation(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float fConstant,
    float fLinear,
    float fQuadratic
    );

Arguments:

hLightSource
Light source handle
fConstant
New constant attenuation factor to be set
fLinear
New linear attenuation factor to be set
fQuadratic
New quadratic attenuation factor to be set

Description:

This function sets the new constant, linear and quadratic attenuation factors for the light source.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_set_cutoff

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_set_cutoff(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float fCutoff
    );

Arguments:

hLightSource
Light source handle
fCutoff
New cutoff angle to be set

Description:

This function sets the new cutoff angle for the light source. The cutoff angle range is 0..90 or 180. 180 means uniform light distribution.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_set_diffuse

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_set_diffuse(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpDiffuse
    );

Arguments:

hLightSource
Light source handle
lpDiffuse
Buffer with four diffuse color components to be set

Description:

This function sets four diffuse color components (red, green, blue and alpha) for the light source. Usually the component range is 0..1.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_set_direction

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_set_direction(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpDirection
    );

Arguments:

hLightSource
Light source handle
lpDirection
Buffer with three direction components to be set

Description:

This function sets three direction comonents (nx, ny, nz) for the light source.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_set_enabled

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_set_enabled(
    HIG_VECT_LIGHTSOURCE hLightSource,
    VECT_BOOL bEnabled
    );

Arguments:

hLightSource
Light source handle
bEnabled
Enabling state flag to be set

Description:

This function sets the enabling state for the light source. VECT_FALSE means that the light source is disabled.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_set_exponent

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_set_exponent(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float fExponent
    );

Arguments:

hLightSource
Light source handle
fExponent
New spot exponent to be set

Description:

This function sets the spot exponent for the light source. Spot exponent range is 0..128.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_set_position

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_set_position(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpPosition
    );

Arguments:

hLightSource
Light source handle
lpPosition
Three position components (x, y, z) to be set

Description:

This function sets three position components (x, y, z) for the light source.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_light_set_specular

Group: Light Source

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_light_set_specular(
    HIG_VECT_LIGHTSOURCE hLightSource,
    float* lpSpecular
    );

Arguments:

hLightSource
Light source handle
lpSpecular
Buffer with four specular color components to be set

Description:

This function sets four specular color components (red, green, blue and alpha) for the light source. Usually the component range is 0..1.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_linetype_get_pattern

Group: Line type

Declaration:

IG_vect_linetype_get_pattern(HIG_VECT_LINETYPE hLinetype, LONG*
lpPattern);

Arguments:

hLinetype
Handle to the Line Type
lpPattern
Line pattern being returned

Description:

The function returns line type pattern. The pattern is a 32 - bit mask. The line segment is drawn if the corresponding bit is 1.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_linetype_get_patternlen

Group: Line type

Declaration:

IG_vect_linetype_get_patternlen(HIG_VECT_LINETYPE hLinetype,
FLOAT* lpPatternlen);

Arguments:

hLinetype
Handle to the Line Type
lpPatternlen
Pattern length being returned

Description:

The function returns an absolute length of the pattern.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBScurve_get_vertexcont

Group: NURBS curve

Declaration:

IG_vect_NURBScurve_get_vertexcont(HIG_VECT_ENTITY hEntity,
HIG_VECT_VERTEXCONT* lpVertexcont);

Arguments:

hEntity
Handle to the Entity
lpVertexcont
Buffer for the Vertex Container handle

Description:

The function returns Vertex Container with the control points of the NURBS curve.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBScurve_get_knotcont

Group: NURBS curve

Declaration:

IG_vect_NURBScurve_get_knotcont(HIG_VECT_ENTITY hEntity,
HIG_VECT_DBLCONT* lpKnotcont);

Arguments:

hEntity
Handle to the Entity
lpKnotcont
Buffer for knot container handle

Description:

The function returns a container of the NURBS curve knot vector. If knot vector is empty then the standard knot vector is calculated.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBScurve_get_flags

Group: NURBS curve

Declaration:

IG_vect_NURBScurve_get_flags(HIG_VECT_ENTITY hEntity, long*
lpFlags);

Arguments:

hEntity
Handle to the Entity
lpFlags
Buffer for the flags

Description:

The function returns different NURBS flags.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBScurve_set_flags

Group: NURBS curve

Declaration:

IG_vect_NURBScurve_set_flags(HIG_VECT_ENTITY hEntity, long
nFlags);

Arguments:

hEntity
Handle to the Entity
nFlags
NURBS flags being set

Description:

The function sets different NURBS flags.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBScurve_get_order

Group: NURBS curve

Declaration:

IG_vect_NURBScurve_get_order(HIG_VECT_ENTITY hEntity, long*
lpOrder);

Arguments:

hEntity
Handle to the Entity
lpOrder
Buffer for the NURBS order

Description:

The function returns an order of the NURBS curve. Usually count of knots is equal to control_point_count |+ order. If this is not so then knot vector is corrected.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBScurve_set_order

Group: NURBS curve

Declaration:

IG_vect_NURBScurve_set_order(HIG_VECT_ENTITY hEntity, long
nOrder);

Arguments:

hEntity
Handle to the Entity
nOrder
NURBS order being set

Description:

The function returns an order of the NURBS curve.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBScurve_get_stepcount

Group: NURBS curve

Declaration:

IG_vect_NURBScurve_get_stepcount(HIG_VECT_ENTITY hEntity, long*
lpStepcount);

Arguments:

hEntity
Handle to the Entity
lpStepcount
Buffer for the step count

Description:

The function returns an interpolation step count. Usually this value lies in interval 3-10.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBScurve_set_stepcount

Group: NURBS curve

Declaration:

IG_vect_NURBScurve_set_stepcount(HIG_VECT_ENTITY hEntity, long
nStepcount);

Arguments:

hEntity
Handle to the Entity
nStepcount
Step count being set

Description:

The function sets an interpolation step count. Usually this value lies in interval 3-10.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_init

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_init(HIG_VECT_ENTITY hEntity, long m, long
n);

Arguments:

hEntity
Handle to the Entity
m
Count of control points in M direction
n
Count of control points in N direction

Description:

The function sets initial dimensions of the NURBS surface in M and N direction.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_get_m

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_get_m(HIG_VECT_ENTITY hEntity, long* lpM);

Arguments:

hEntity
Handle to the Entity
lpM
buffer for control point s count

Description:

The function returns count of control points in M direction.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_get_n

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_get_n(HIG_VECT_ENTITY hEntity, long* lpN);

Arguments:

hEntity
Handle to the Entity
lpN
Buffer for control points count

Description:

The function returns count of control points in N direction.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_get_vertexcont

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_get_vertexcont(HIG_VECT_ENTITY hEntity,
long m, HIG_VECT_VERTEXCONT* lpVertexcont);

Arguments:

hEntity
Handle to the Entity
m
Vertex Container number ( index in M direction)
lpVertexcont
Buffer for the Vertex Container handle

Description:

The function returns vertex container with control points that belong to the column m.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_get_mknotcont

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_get_mknotcont(HIG_VECT_ENTITY hEntity,
HIG_VECT_DBLCONT* lpKnotcont);

Arguments:

hEntity
Handle to the Entity
lpKnotcont
Buffer for the container handle

Description:

The function returns container with knot vector in m direction. If this container is empty then the standard knot vector is calculated.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_get_nknotcont

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_get_nknotcont(HIG_VECT_ENTITY hEntity,
HIG_VECT_DBLCONT* lpKnotcont);

Arguments:

hEntity
Handle to the Entity
lpKnotcont
Buffer for the container handle

Description:

The function returns container with knot vector in n direction. If this container is empty then the standard knot vector is calculated.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_get_morder

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_get_morder(HIG_VECT_ENTITY hEntity, long*
lpOrder);

Arguments:

hEntity
Handle to the Entity
lpOrder
Buffer for the order in M direction

Description:

The function returns an order of the NURBS surface in m direction.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_set_morder

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_set_morder(HIG_VECT_ENTITY hEntity, long
nOrder);

Arguments:

hEntity
Handle to the Entity
nOrder
Order in M-direction being set

Description:

The function sets an order of the NURBS surface in m direction. If count of knots in m direction is not equal to m_control_points + m_order then the m-knot vector is corrected.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_get_norder

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_get_norder(HIG_VECT_ENTITY hEntity, long*
lpOrder);

Arguments:

hEntity
Handle to the Entity
lpOrder
Buffer for the order in N direction

Description:

The function returns an order of the NURBS surface in n direction.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_set_norder

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_set_norder(HIG_VECT_ENTITY hEntity, long
nOrder);

Arguments:

hEntity
Handle to the Entity
nOrder
Order in N-direction being set

Description:

The function sets an order of the NURBS surface in n direction. If count of knots in n direction is not equal to n_control_points + n_order then the n-knot vector is corrected.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_get_mstepcount

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_get_mstepcount(HIG_VECT_ENTITY hEntity,
long* lpStepcount);

Arguments:

hEntity
Handle to the Entity
lpStepcount
Buffer for the step count

Description:

The function returns step count for interpolation in m direction. Usually this value lies in interval 3-10.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_set_mstepcount

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_set_mstepcount(HIG_VECT_ENTITY hEntity,
long nStepcount);

Arguments:

hEntity
Handle to the Entity
nStepcount
Stepcount being set

Description:

The function sets step count for interpolation in m direction. Usually this value lies in interval 3-10.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_get_nstepcount

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_get_nstepcount(HIG_VECT_ENTITY hEntity,
long* lpStepcount);

Arguments:

hEntity
Handle to the Entity
lpStepcount
Buffer for the step count

Description:

The function returns step count for interpolation in n direction. Usually this value lies in interval 3-10.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_set_nstepcount

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_set_nstepcount(HIG_VECT_ENTITY hEntity,
long nStepcount);

Arguments:

hEntity
Handle to the Entity
nStepcount
Stepcount being set

Description:

The function sets step count for interpolation in n direction. Usually this value lies in interval 3-10.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_get_flags

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_get_flags(HIG_VECT_ENTITY hEntity, long*
lpFlags);

Arguments:

hEntity
Handle to the Entity
lpFlags
Buffer for the NURBS surface flags

Description:

The function returns different NURBS surface flags.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_NURBSsurface_set_flags

Group: NURBS surface

Declaration:

IG_vect_NURBSsurface_set_flags(HIG_VECT_ENTITY hEntity, long
nFlags);

Arguments:

hEntity
Handle to the Entity
nFlags
NURBS surface flags being set

Description:

The function sets different NURBS surface flags.

Bits Per Pixel: All

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_polyline_get_vertexcont

Group: Polyline

Declaration:

IG_vect_polyline_get_vertexcont(HIG_VECT_ENTITY hEntity,
HIG_VECT_VERTEXCONT* lpVertexcont);

Arguments:

hEntity
Handle to the Entity
lpVertexcont
Buffer for the handle to the vertex container

Description:

The function returns a handle to the vertex container of the polyline.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_polylineex_get_vertexcont

Group: Extended polyline

Declaration:

IG_vect_polylineex_get_vertexcont(HIG_VECT_ENTITY hEntity,
HIG_VECT_VERTEXCONT* lpVertexcont);

Arguments:

hEntity
Handle to the Entity
lpVertexcont
Buffer for the handle to the vertex container

Description:

The function returns a vertex container describing one of the contours of the extended polyline. The contour number is set by IG_vect_polylineex_set_contour () function.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_polylineex_get_contourcount

Group: Extended polyline

Declaration:

IG_vect_polylineex_get_contourcount(HIG_VECT_ENTITY hEntity,
long* lpCount);

Arguments:

hEntity
Handle to the Entity
lpCount
Buffer for the count of contours

Description:

The function returns a total count of the contours in the extended polyline.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_polylineex_set_contour

Group: Extended polyline

Declaration:

IG_vect_polylineex_set_contour(HIG_VECT_ENTITY hEntity, long
nIndex);

Arguments:

hEntity
Handle to the Entity
mIndex
Number of the active contour being set

Description:

The function sets the number of the active contour. IG_vect_polylineex_get_vertexcont () returns the active contour.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_raster_get_data

Group: Raster

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_raster_get_data(
    HIG_VECT_ENTITY hEntity,
    IGVectColor** lplpData
    );

Arguments:

hEntity
Raster entity handle
lplpData
Buffer to the pointer for raster data

Description:

The function returns a pointer to the raster data. Raster data is a sequence of IGVectColor strucrures. The data is available for direct access to the raster colors.

Bits Per Pixel: 32, RGBA

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_raster_get_height

Group: Raster

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_raster_get_height(
    HIG_VECT_ENTITY hEntity,
    long* lpHeight
    );

Arguments:

hEntity
Raster entity handle
lpHeight
Buffer for the raster height

Description:

The function return a raster height.

Bits Per Pixel: 32, RGBA

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_raster_get_leftbottom

Group: Raster

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_raster_get_leftbottom(
    HIG_VECT_ENTITY hEntity,
    IGVectPoint3D** lplpLeftBottom
    );

Arguments:

hEntity
Raster entity handle
lplpLeftBottom
buffer for the pointer to the raster left bottom coordinates

Description:

The function returns a pointer to the IGVectPoint3D structure representing the raster left bottom coordinates.

Bits Per Pixel: 32, RGBA

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_raster_get_lefttop

Group: Raster

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_raster_get_lefttop(
    HIG_VECT_ENTITY hEntity,
    IGVectPoint3D** lplpLeftTop
    );

Arguments:

hEntity
Raster entity handle
lplpLeftTop
buffer for the pointer to the raster left top coordinates

Description:

The function returns a pointer to the IGVectPoint3D structure representing the raster left top coordinates.

Bits Per Pixel: 32, RGBA

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_raster_get_rightbottom

Group: Raster

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_raster_get_rightbottom(
    HIG_VECT_ENTITY hEntity,
    IGVectPoint3D** lplpRigthBottom
    );

Arguments:

hEntity
Raster entity handle
lplpRigthBottom
Buffer for the pointer to the raster right bottom coordinates

Description:

The function returns a pointer to the IGVectPoint3D structure representing the raster right bottom coordinates.

Bits Per Pixel: 32, RGBA

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_raster_get_righttop

Group: Raster

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_raster_get_righttop(
    HIG_VECT_ENTITY hEntity,
    IGVectPoint3D** lplpRigthTop
    );

Arguments:

hEntity
Raster entity handle
lplpRigthTop
buffer for the pointer to the raster right top coordinates

Description:

The function returns a pointer to the IGVectPoint3D structure representing the raster right top coordinates.

Bits Per Pixel: 32, RGBA

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_raster_get_width

Group: Raster

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_raster_get_width(
    HIG_VECT_ENTITY hEntity,
    long* lpWidth
    );

Arguments:

hEntity
Raster entity handle
lpWidth
Buffer for the raster width

Description:

The function returnes the raster width.

Bits Per Pixel: 32, RGBA

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_raster_init

Group: Raster

Declaration:

AT_ERRCOUNT ACCUAPI IG_vect_raster_init(
    HIG_VECT_ENTITY hEntity,
    long nWidth,
    long nHeight
    );

Arguments:

hEntity
Raster entity handle
nWidth
New raster width
nHeight
New raster height

Description:

The function initializes the raster entity with the new width and height and allocates a memory for the color data.

Bits Per Pixel: 32, RGBA

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_rotation_add_angle

Group: Rotation

Declaration:

IG_vect_rotation_add_angle(HIG_VECT_ROTATION hRotation,
enumIGVectDir nDir, FLOAT fAngle);

Arguments:

hRotation
Handle to the rotation
nDir
Constant specifying the rotation direction
fAngle
Angle being added

Description:

The function adds an angle to the rotation.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_rotation_get_angle

Group: Rotation

Declaration:

IG_vect_rotation_get_angle(HIG_VECT_ROTATION hRotation,
enumIGVectDir nDir, FLOAT* lpAngle);

Arguments:

hRotation
Handle to the Rotation
nDir
Constant specifying the rotation direction
fAngle
Angle being set

Description:

The function sets a rotation angle in the specified direction.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_rotation_add_matrix

Group: Rotation

Declaration:

IG_vect_rotation_add_matrix(HIG_VECT_ROTATION hRotation, FLOAT*
lpMat);

Arguments:

hRotation
Handle to the rotation
lpMat
3x3 matrix being added

Description:

The function adds 3x3 matrix to the rotation.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_rotation_get_matrix

Group: Rotation

Declaration:

IG_vect_rotation_get_matrix(HIG_VECT_ROTATION hRotation, FLOAT*
lpMat);

Arguments:

hRotation
Handle to the Rotation
lpMat
3x3 buffer for the matrix rotation matrix

Description:

The function returns a copy of 3x3 matrix rotation matrix.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_rotation_set_matrix

Group: Rotation

Declaration:

IG_vect_rotation_set_matrix(HIG_VECT_ROTATION hRotation, FLOAT*
lpMat);

Arguments:

hRotation
Handle to the Rotation
lpMat
3x3 rotation matrix being set

Description:

The function replaces the rotation matrix.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_text_get_textobj

Group: Text

Declaration:

IG_vect_text_get_textobj(HIG_VECT_ENTITY hEntity, long nIndex,
HIG_VECT_TEXTOBJ* lpTextobj);

Arguments:

hEntity
Handle to the Entity
nIndex
Index of the text object to be returned
lpTextObject
Buffer for the Text Object handle

Description:

The function returns the text object with the index nIndex in the Text Object chain.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_text_create_textobj

Group: Text

Declaration:

IG_vect_text_create_textobj(HIG_VECT_ENTITY hEntity, long
nIndex, HIG_VECT_TEXTOBJ* lpTextobj);

Arguments:

hEntity
Handle to the Entity
nIndex
Position of the new Text Object. If nIndex is less than 0, then the new Text Object is added to the end of the chain.
lpTextObject
Buffer for the Text Object handle

Description:

The function creates new text object and inserted it at nIndex position in the Text Object chain.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_text_delete_textobj

Group: Text

Declaration:

IG_vect_text_delete_textobj(HIG_VECT_ENTITY hEntity, long
nIndex);

Arguments:

hEntity
Handle to the Entity
nIndex
Position of the text object to be removed

Description:

The function removes the Text Object from the position nIndex and destroys it.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_text_get_textobjcount

Group: Text

Declaration:

IG_vect_text_get_textobjcount(HIG_VECT_ENTITY hEntity, long*
lpCount);

Arguments:

hEntity
Handle to the Entity
lpCount
Buffer for the Text Object count

Description:

The function returns the total count of Text Objects in the chain.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_text_get_alignment

Group: Text

Declaration:

IG_vect_text_get_alignment(HIG_VECT_ENTITY hEntity, long*
lpAlignment);

Arguments:

hEntity
Handle to the Entity
lpAlignment
Buffer for the alignment flags.

Description:

The function returns flags defining an alignment of the text string. See enumIGVectAlignment enumeration for possible values.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_text_set_alignment

Group: Text

Declaration:

IG_vect_text_set_alignment(HIG_VECT_ENTITY hEntity, long
nAlignment);

Arguments:

hEntity
Handle to the Entity
nAlignment
Alignment flags being set

Description:

The function sets alignment flags for the text strings.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_text_get_alignpointptr

Group: Text

Declaration:

IG_vect_text_get_alignpointptr(HIG_VECT_ENTITY hEntity,
IGVectPoint2D** lplpPoint);

Arguments:

hEntity
Handle to the Entity
lplpPoint
Buffer for the pointer to the alignment point.

Description:

The function returns a pointer to the additional alignment point. Alignment point is taken into account if IG_VECT_ALIGN_CONTINUOUSX or IG_VECT_ALIGN_CONTINUOUSY alignment flags are set.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_text_get_restrictpointptr

Group: Text

Declaration:

IG_vect_text_get_restrictpointptr(HIG_VECT_ENTITY hEntity,
IGVectPoint2D** lplpPoint);

Arguments:

hEntity
Handle to the Entity
lplpPoint
Buffer for the pointer to the restriction point.

Description:

The function returns a pointer to the additional point defining restriction width and height. Restriction is taken into account if any IG_VECT_RESTRICT_... alignment flag is set.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_text_get_baseline

Group: Text

Declaration:

IG_vect_text_get_baseline(HIG_VECT_ENTITY hEntity, float*
lpBaseline);

Arguments:

hEntity
Handle to the Entity
lpBaseline
Buffer for the base line angle.

Description:

The function returns a base line angle for the whole text string.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_text_set_baseline

Group: Text

Declaration:

IG_vect_text_set_baseline(HIG_VECT_ENTITY hEntity, float
fBaseline);

Arguments:

hEntity
Handle to the Entity
fBaseline
Base line angle being set

Description:

The function sets the base line angle for the whole text string.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_text_copysettings_from

Group: Text

Declaration:

IG_vect_text_copysettings_from(HIG_VECT_ENTITY hEntitydst,
HIG_VECT_ENTITY hEntitysrc);

Arguments:

hEntityDst
handle to the destination Entity
hEntitySrc
handle to the source Entity

Description:

The function copies all common text settings from one text entity to another. This is convenient when the new text string with almost the same settings is created.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_get_text

Group: Text object

Declaration:

IG_vect_textobj_get_text(HIG_VECT_TEXTOBJ hTextobj, LPCHAR
lpText, long nSize);

Arguments:

hTextobj
Handle to the Text Object
lpText
Buffer for the text string
nSize
Maximum size of the buffer

Description:

The function returns a text string assigned to the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_set_text

Group: Text object

Declaration:

IG_vect_textobj_set_text(HIG_VECT_TEXTOBJ hTextobj, LPCHAR
lpText);

Arguments:

hTextobj
Handle to the Text Object
lpText
Text string being set

Description:

The function sets a text string for the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_get_font

Group: Text object

Declaration:

IG_vect_textobj_get_font(HIG_VECT_TEXTOBJ hTextobj,
HIG_VECT_FONT* lpFont);

Arguments:

hTextobj
Handle to the Text Object
lpFont
Buffer for the font handle

Description:

The function returns a font handle assigned to the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_set_font

Group: Text object

Declaration:

IG_vect_textobj_set_font(HIG_VECT_TEXTOBJ hTextobj,
HIG_VECT_FONT hFont);

Arguments:

hTextobj
Handle to the Text Object
hFont
handle to the font being assigned

Description:

The function assigns a font to the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_get_fontwidth

Group: Text object

Declaration:

IG_vect_textobj_get_fontwidth(HIG_VECT_TEXTOBJ hTextobj, float*
lpFontwidth);

Arguments:

hTextobj
Handle to the Text Object
lpFontwidth
Buffer for the font width

Description:

The function returns font width of the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_set_fontwidth

Group: Text object

Declaration:

IG_vect_textobj_set_fontwidth(HIG_VECT_TEXTOBJ hTextobj, float
fFontwidth);

Arguments:

hTextobj
Handle to the Text Object
fFontwidth
Font width being set

Description:

The function sets font width for the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_get_fontheight

Group: Text object

Declaration:

IG_vect_textobj_get_fontheight(HIG_VECT_TEXTOBJ hTextobj,
float* lpFontheight);

Arguments:

hTextobj
Handle to the Text Object
lpFontheight
Buffer for the font heightt

Description:

The function returns font height of the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_set_fontheight

Group: Text object

Declaration:

IG_vect_textobj_set_fontheight(HIG_VECT_TEXTOBJ hTextobj, float
fFontheight);

Arguments:

hTextobj
Handle to the Text Object
fFontheight
Font height being set

Description:

The function sets font height for the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_get_charbase

Group: Text object

Declaration:

IG_vect_textobj_get_charbase(HIG_VECT_TEXTOBJ hTextobj, float*
lpCharbase);

Arguments:

hTextobj
Handle to the Text Object
lpCharbase
Buffer for char base angle

Description:

The function returns char base angle of the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_set_charbase

Group: Text object

Declaration:

IG_vect_textobj_set_charbase(HIG_VECT_TEXTOBJ hTextobj, float
fCharbase);

Arguments:

hTextobj
Handle to the Text Object
fCharbase
Char base angle being set

Description:

The function sets char base angle for the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_get_charup

Group: Text object

Declaration:

IG_vect_textobj_get_charup(HIG_VECT_TEXTOBJ hTextobj, float*
lpCharup);

Arguments:

hTextobj
Handle to the Text Object
lpCharup
Buffer for char up angle

Description:

The function returns char up angle of the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_set_charup

Group: Text object

Declaration:

IG_vect_textobj_set_charup(HIG_VECT_TEXTOBJ hTextobj, float
fCharup);

Arguments:

hTextobj
Handle to the Text Object
fCharup
Char up angle being set

Description:

The function sets char up angle for the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_get_charspacing

Group: Text object

Declaration:

IG_vect_textobj_get_charspacing(HIG_VECT_TEXTOBJ hTextobj,
float* lpCharspacing);

Arguments:

hTextobj
Handle to the Text Object
lpCharspacing
Buffer for char spacing

Description:

The function returns char spacing of the text object. The normal char spacing is 1.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_set_charspacing

Group: Text object

Declaration:

IG_vect_textobj_set_charspacing(HIG_VECT_TEXTOBJ hTextobj,
float fCharspacing);

Arguments:

hTextobj
Handle to the Text Object
lpCharspacing
Char spacing being set

Description:

The function sets char spacing for the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_get_color

Group: Text object

Declaration:

IG_vect_textobj_get_color(HIG_VECT_TEXTOBJ hTextobj,
IGVectColorEx* lpColor);

Arguments:

hTextobj
Handle to the Text Object
lpColor
Buffer for the color

Description:

The function returns a color of the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_set_color

Group: Text object

Declaration:

IG_vect_textobj_set_color(HIG_VECT_TEXTOBJ hTextobj,
IGVectColorEx Color);

Arguments:

hTextobj
Handle to the Text Object
lpColor
Text object color being set

Description:

The function sets a color for the text object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_copysettings_from

Group: Text object

Declaration:

IG_vect_textobj_copysettings_from(HIG_VECT_TEXTOBJ
hTextobjdest, HIG_VECT_TEXTOBJ hTextobjsrc);

Arguments:

hTextobjdest
Handle to the destination Text Object
hTextobjsrc
Handle to the source Text Object

Description:

The function copies all settings from one text object to another except text string. This can be helpful when the new text object with almost the same settings is created.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_get_textwidth

Group: Text object

Declaration:

IG_vect_textobj_get_textwidth(HIG_VECT_TEXTOBJ hTextobj, LPCHAR
lpText, float* lpWidth);

Arguments:

hTextobj
Handle to the Text Object
lpText
Text string to calculate actual width. If this parameter is NULL, then the width is calculated for the text assigned to the text object.
lpWidth
Buffer for the width being calculated

Description:

The function calculates the actual width of the text string taken into account the current Text Object settings.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_get_flags

Group: Text object

Declaration:

IG_vect_textobj_get_flags(HIG_VECT_TEXTOBJ hTextobj, long*
lpFlags);

Arguments:

hTextobj
Handle to the Text Object
lpFlags
Buffer for the flags

Description:

The function returns flags describing different effects for the Text Object such as : Subscript, Superscript, Struck, Double Struck, Underlined.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_textobj_set_flags

Group: Text object

Declaration:

IG_vect_textobj_set_flags(HIG_VECT_TEXTOBJ hTextobj, long
nFlags);

Arguments:

hTextobj
Handle to the Text Object
nFlags
Flags being set

Description:

The function sets flags describing different effects for the Text Object.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_vertexcont_init

Group: Vertex container

Declaration:

IG_vect_vertexcont_init(HIG_VECT_VERTEXCONT hVertexcont, LONG
nSize);

Arguments:

hVertexcont
Handle to the Vertex Container
nSize
Container size being set

Description:

The function sets initial size of the vertex container. This is convenient when vertex count is known in advance.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_vertexcont_create_vertex

Group: Vertex container

Declaration:

IG_vect_vertexcont_create_vertex(HIG_VECT_VERTEXCONT
hVertexcont, IGVectVertex** lplpVertex);

Arguments:

hVertexcont
Handle to the Vertex Container
lplpVertex
Buffer for the new vertex pointer

Description:

The function creates a vertex and adds it at the end of the container.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_vertexcont_get_vertex

Group: Vertex container

Declaration:

IG_vect_vertexcont_get_vertex(HIG_VECT_VERTEXCONT hVertexcont,
long nIndex, IGVectVertex** lplpVertex);

Arguments:

hVertexcont
Handle to the Vertex Container
nIndex
Index of the vertex to be returned
lplpVertex
Buffer for the vertex pointer

Description:

The function returns pointer to the vertex at the specified position.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_vertexcont_get_count

Group: Vertex container

Declaration:

IG_vect_vertexcont_get_count(HIG_VECT_VERTEXCONT hVertexcont,
LONG* lpCount);

Arguments:

hVertexcont
Handle to the Vertex Container
lpCount
Buffer for the count of the vertexes

Description:

The function returns total count of the vertexes in the vertex container.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_vertexcont_clear

Group: Vertex container

Declaration:

IG_vect_vertexcont_clear(HIG_VECT_VERTEXCONT hVertexcont);

Arguments:

hVertexcont
Handle to the Vertex Container

Description:

The function removes al vertexes from the container and destroys them.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_vertexcont_get_attrib

Group: Vertex container

Declaration:

IG_vect_vertexcont_get_attrib( HIG_VECT_VERTEXCONT hVertexcont,
IGVectVertex* lpVertex, enumIGVectVertexData* lpAttribType,
FLOAT* lpAttrib);

Arguments:

hVertexcont
Handle to the Vertex Container
lpVertex
Pointer to the vertex
lpAttribType
Buffer for the attribute type. NULL is returned if vertex has no attributes
LpAttrib
Buffer for the attribute value. Null is returned if vertex has noattributes

Description:

The function returns the vertex attributes if presented. Currently every vertex can have the only attribute of the type float. If the vertex has an attribute, its type is returned with the parameter lpAttribType and value with lpAttrib. Otherwise, both lpAttribType and lpAttrib return NULL.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_vertexcont_set_attrib

Group: Vertex container

Declaration:

IG_vect_vertexcont_set_attrib(HIG_VECT_VERTEXCONT hVertexcont,
IGVectVertex* lpVertex, enumIGVectVertexData nAttribType, FLOAT
fAttrib);

Arguments:

hVertexcont
Handle to the Vertex Container
lpVertex
Pointer to the vertex
nAttribType
Type of the attribute
fAttrib
Attribute value

Description:

The function sets an attribute for the vertex.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_vertexcont_get_hidden

Group: Vertex container

Declaration:

IG_vect_vertexcont_get_hidden(HIG_VECT_VERTEXCONT hVertexcont,
IGVectVertex* lpVertex, VECT_BOOL* lpHidden);

Arguments:

hVertexcont
Handle to the Vertex Container
lpHidden
Buffer for the flag. VECT_TRUE means that the vertex is hidden

Description:

The function returns a flag showing whether the vertex is hidden or not.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_vertexcont_set_hidden

Group: Vertex container

Declaration:

IG_vect_vertexcont_set_hidden(HIG_VECT_VERTEXCONT hVertexcont,
IGVectVertex* lpVertex, VECT_BOOL bHidden);

Arguments:

hVertexcont
Handle to the Vertex Container
bHidden
Hidden flag beinf set. VECT_TRUE means that outgoing line is hidden. The vertex is not hidden by default.

Description:

The function sets the hidden flag for the vertex.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_get_content

Group: Vector View

Declaration:

IG_vect_view_get_content(HIG_VECT_VIEW hView, HIG_VECT_ENTITY*
lpContent);

Arguments:

hView
Handle to the View
lpContent
Buffer for the content

Description:

The function returns View content, that is, any entity to be observed from different points of view.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_set_content

Group: Vector View

Declaration:

IG_vect_view_set_content(HIG_VECT_VIEW hView, HIG_VECT_ENTITY
hContent);

Arguments:

hView
Handle to the View
hContent
Handle of the entity being set as View content

Description:

The function sets View content.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_get_minmax

Group: Vector View

Declaration:

IG_vect_view_get_minmax(HIG_VECT_VIEW hView, IGVectMinMax*
lpMinmax);

Arguments:

hView
Handle to the View
lpMinmax
Buffer bor minimum and maximum coordinates of the View

Description:

The function returns minimum and maximum coordinates of the View. These coordinates may not correspond to the Content minimum and maximum and can be changed by the user.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_set_minmax

Group: Vector View

Declaration:

IG_vect_view_set_minmax(HIG_VECT_VIEW hView, IGVectMinMax*
lpMinmax);

Arguments:

hView
Handle to the View
lpMinmax
Pointer to the IGVectMinMax structure containing minimum and maximum Veiw coordinates being set

Description:

The function sets minimum and maximum coordinates of the View.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_get_focus

Group: Vector View

Declaration:

IG_vect_view_get_focus(HIG_VECT_VIEW hView, float* lpFocus);

Arguments:

hView
Handle to the View
lpFocus
Buffer for the lens focus

Description:

The function returns lens focus of the camera.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_set_focus

Group: Vector View

Declaration:

IG_vect_view_set_focus(HIG_VECT_VIEW hView, float fFocus);

Arguments:

hView
Handle to the View
fFocus
Camera lens focus being set

Description:

The function sets lens focus of the camera.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_get_name

Group: Vector View

Declaration:

IG_vect_view_get_name(HIG_VECT_VIEW hView, LPCHAR lpName, long
nSize);
Arguments:
hView
Handle to the View
lpName
Buffer for View name
nSize
Maximum buffer size

Description:

The function returns View name.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_set_name

Group: Vector View

Declaration:

IG_vect_view_set_name(HIG_VECT_VIEW hView, LPCHAR lpName);
Arguments:
hView
Handle to the View
lpName
View name being set

Description:

The function sets View name.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_get_matrix

Group: Vector View

Declaration:

IG_vect_view_get_matrix(HIG_VECT_VIEW hView, float* lpMatrix);
Arguments:
hView
Handle to the View
lpMatrix
Buffer for camera state matrix

Description:

The function returns 4x4 matrix defining camera state. The matrix is column-ordered.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_set_matrix

Group: Vector View

Declaration:

IG_vect_view_set_matrix(HIG_VECT_VIEW hView, float* lpMatrix);
Arguments:
hView
Handle to the View
lpMatrix
new camera state matrix being set

Description:

The function replaces the current camera state matrix.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_get_bkcolor

Group: Vector View

Declaration:

IG_vect_view_get_bkcolor(HIG_VECT_VIEW hView, IGVectColor*
lpColor);
Arguments:
hView
Handle to the View
lpColor
buffer for the View background color

Description:

The function returns background color of the View.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_set_bkcolor

Group: Vector View

Declaration:

IG_vect_view_set_bkcolor(HIG_VECT_VIEW hView, IGVectColor
Color);
Arguments:
hView
Handle to the View
Color
New background color being set

Description:

The function sets background color for the View.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_get_displayhiddenlayers

Group: Vector View

Declaration:

IG_vect_view_get_displayhiddenlayers(HIG_VECT_VIEW hView,
VECT_BOOL* lpDisplay);
Arguments:
hView
Handle to the View
lpDisplay
buffer for the flag

Description:

The function returns flag defining whether or not the hidden layers should be displayed in the View.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_set_displayhiddenlayers

Group: Vector View

Declaration:

IG_vect_view_set_displayhiddenlayers(HIG_VECT_VIEW hView,
VECT_BOOL bDisplay);
Arguments:
hView
Handle to the View
bDisplay
Flag to be set

Description:

The function sets flag defining whether or not the hidden layers should be displayed in the View.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_move

Group: Vector View

Declaration:

IG_vect_view_move(HIG_VECT_VIEW hView, float fXmove, float
fYmove, float fZmove);
Arguments:
hView
Handle to the View
fXmove
x offset
fYmove
y offset
fZmove
z offset

Description:

The function provides relative moving the View camera.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_scale

Group: Vector View

Declaration:

IG_vect_view_scale(HIG_VECT_VIEW hView, float fXscale, float
fYscale, float fZscale);
Arguments:
hView
Handle to the View
fXscale
x relative scale factors
fYscale
y relative scale factors
fZscale
z relative scale factors

Description:

The function scales the View camera.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_view_rotate

Group: Vector View

Declaration:

IG_vect_view_rotate(HIG_VECT_VIEW hView, float fAngle,
enumIGVectDir nDir, VECT_BOOL bLookpoint);
Arguments:
hView
Handle to the View
fAngle
Rotation angle
nDir
Coordinate plane
bLookpoint
If this flag is VECT_TRUE, then the camera is rotated around the look point, otherwise it is rotated around the camera center point.

Description:

The function rotates the View camera on the specified angle in the specified coordinate plane.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_viewport_get_vpminptr

Group: Viewport

Declaration:

IG_vect_viewport_get_vpminptr(HIG_VECT_ENTITY hEntity,
IGVectPoint3D** lplpVpmin);
Arguments:
hEntity
Handle to the Entity
lplpVpmin
Buffer for the pointer

Description:

The function returns a pointer to the point with minimum coordinates of the viewport.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_viewport_get_vpmaxptr

Group: Viewport

Declaration:

IG_vect_viewport_get_vpmaxptr(HIG_VECT_ENTITY hEntity,
IGVectPoint3D** lplpVpmax);
Arguments:
hEntity
Handle to the Entity
lplpVpmax
Buffer for the pointer

Description:

The function returns a pointer to the point with maximum coordinates of the viewport.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_viewport_get_viewminptr

Group: Viewport

Declaration:

IG_vect_viewport_get_viewminptr(HIG_VECT_ENTITY hEntity,
IGVectPoint3D** lplpViewmin);
Arguments:
hEntity
Handle to the Entity
lplpViewmin
Buffer for the pointer

Description:

The function returns a pointer to the point with minimum coordinates of the view being mapped to the viewport.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_viewport_get_viewmaxptr

Group: Viewport

Declaration:

IG_vect_viewport_get_viewmaxptr(HIG_VECT_ENTITY hEntity,
IGVectPoint3D** lplpViewmax);
Arguments:
hEntity
Handle to the Entity
lplpViewmax
Buffer for the pointer

Description:

The function returns a pointer to the point with maximum coordinates of the view being mapped to the viewport.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_viewport_get_rotation

Group: Viewport

Declaration:

IG_vect_viewport_get_rotation(HIG_VECT_ENTITY hEntity,
HIG_VECT_ROTATION* lpRotation);
Arguments:
hEntity
Handle to the Entity
lpRotation
Buffer for the rotation handle

Description:

The function returns a rotation of the view being mapped.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_viewport_get_content

Group: Viewport

Declaration:

IG_vect_viewport_get_content(HIG_VECT_ENTITY hEntity,
HIG_VECT_ENTITY* lpContent);
Arguments:
hEntity
Handle to the Entity
lpContent
Buffer for the entity handle

Description:

The function returns a handle to the entity being mapped. Usually this is a block containing some other entities.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_viewport_set_content

Group: Viewport

Declaration:

IG_vect_viewport_set_content(HIG_VECT_ENTITY hEntity,
HIG_VECT_ENTITY hContent);
Arguments:
hEntity
Handle to the Entity
hContent
Handle of the entity being set as Viewport content

Description:

The function sets an entity being mapped. Usually this is a block containing some other entities.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_viewport_get_layercont

Group: Viewport

Declaration:

IG_vect_viewport_get_layercont(HIG_VECT_ENTITY hEntity,
HIG_VECT_LAYERCONT* lpLayercont);
Arguments:
hEntity
Handle to the Entity
lpLayercont
Buffer for the layer handle

Description:

The function returns Layer Container of the Viewport. All layers from the container are supposed to be frozen in the viewport. All other layers (including hidden) are visible.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_viewport_get_boundary

Group: Viewport

Declaration:

IG_vect_viewport_get_boundary(HIG_VECT_ENTITY hEntity,
HIG_VECT_ENTITY* lpBoundary);
Arguments:
hEntity
Handle to the Entity
lpBoundary
Buffer for the boundary handle

Description:

The function gets an entity that bounds the viewport. This can be rectangle, polyline, ellipse and opther. If the boundary is not set, the Viewport is bounded by the square.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


IG_vect_viewport_set_boundary

Group: Viewport

Declaration:

IG_vect_viewport_set_boundary(HIG_VECT_ENTITY hEntity,
HIG_VECT_ENTITY hBoundary);
Arguments:
hEntity
Handle to the Entity
hBoundary
Handle to the boundary beinng set

Description:

The function sets bounding entity for the viewport.

Bits Per Pixel: All

Return Value:

Returns vector data handle attached to the HIGEAR.

Sample: None

AccuSoft Corporation
 AccuSoft.com
sales@accusoft.com


Vector Component Enumerations Reference

The following structures are determined in ImageGear Vector Component:

  • enumIGVectAlignment
  • enumIGVectArcCloseType
  • enumIGVectAttrib
  • enumIGVectAttrSource
  • enumIGVectDir
  • enumIGVectEntities
  • enumIGVectFillMode
  • enumIGVectFillPattern
  • enumIGVectHeaderType
  • enumIGVectGeometryType
  • enumIGVectGraphics
  • enumIGVectMeasurementUnits
  • enumIGVectNURBSFlags
  • enumIGVectTxtFlags
  • enumIGVectVertexData


enumIGVectAlignment

Group: Enum

Description:

These constants define text alignment

Declaration:

typedef enum enumIGVectAlignment
{
    IG_VECT_ALIGN_DEFAULT = 0,
    IG_VECT_ALIGN_X_LEFT = 1,
    IG_VECT_ALIGN_X_CENTER = 2,
    IG_VECT_ALIGN_X_RIGHT = 4,
    IG_VECT_ALIGN_Y_TOP = 8,
    IG_VECT_ALIGN_Y_CENTER = 16,
    IG_VECT_ALIGN_Y_BOTTOM = 32,
    IG_VECT_ALIGN_Y_BASELINE = 64,
    IG_VECT_ALIGN_CONTINUOUSX = 128,
    IG_VECT_ALIGN_CONTINUOUSY = 256,
    IG_VECT_RESTRICT = 512,
    IG_VECT_RESTRICT_BASIS = IG_VECT_RESTRICT << 1,
    IG_VECT_RESTRICT_BOXED_CAP = IG_VECT_RESTRICT << 2,
    IG_VECT_RESTRICT_BOXED_ALL = IG_VECT_RESTRICT << 3,
    IG_VECT_RESTRICT_ISOTROPIC_CAP = IG_VECT_RESTRICT << 4,
    IG_VECT_RESTRICT_ISOTROPIC_ALL = IG_VECT_RESTRICT << 5,
    IG_VECT_RESTRICT_JUSTIFIED = IG_VECT_RESTRICT << 6
} enumIGVectAlignment;

Values:

IG_VECT_ALIGN_DEFAULT
default alignment
IG_VECT_ALIGN_X_LEFT
x left alignment
IG_VECT_ALIGN_X_CENTER
x center alignment
IG_VECT_ALIGN_X_RIGHT
x right alignment
IG_VECT_ALIGN_Y_TOP
y top alignment
IG_VECT_ALIGN_Y_CENTER
y center alignment
IG_VECT_ALIGN_Y_BOTTOM
y bottom alignment
IG_VECT_ALIGN_Y_BASELINE
base line alignment
IG_VECT_ALIGN_CONTINUOUSX
the additional align point is used for x alignment
IG_VECT_ALIGN_CONTINUOUSY
the additional align point is used for y alignment
IG_VECT_RESTRICT
the flag defining that the text is restricted
IG_VECT_RESTRICT_BASIS
the text is exactly restricted in the restrict box by the base line
IG_VECT_RESTRICT_BOXED_CAP
the text is exactly restricted in the restrict box by the bottom
IG_VECT_RESTRICT_BOXED_ALL
the same as IG_VECT_RESTRICT_BASIS at the moment
IG_VECT_RESTRICT_ISOTROPIC_CAP
isotropic restriction in the restrict box by the bottom
IG_VECT_RESTRICT_ISOTROPIC_ALL
isotropic restriction in the restrict box by the base line
IG_VECT_RESTRICT_JUSTIFIED
the text is justified inside the restriction box using variable spacing


enumIGVectArcCloseType

Group: Enum

Description:

These constants define how an arc is closed.

Declaration:

typedef enum enumIGVectArcCloseType
{
    IG_VECT_ARC_CLOSE_NONE = 0,
    IG_VECT_ARC_CLOSE_SECTOR = 1,
    IG_VECT_ARC_CLOSE_SEGMENT = 2
} enumIGVectArcCloseType;

Values:

IG_VECT_ARC_CLOSE_NONE
arc is not closed
IG_VECT_ARC_CLOSE_SECTOR
arc is closed as sector
IG_VECT_ARC_CLOSE_SEGMENT
arc is closed as segment


enumIGVectAttrib

Group: Enum

Description:

These constants define common entity attributes. By default, an entity does not have any attribute. Attribute is created when the entity method get_AttribPtr is called. This method returns pointer to the corresponding attribute.

Declaration:

typedef enum enumIGVectAttrib
{
    IG_VECT_ENT_ATTR_DRAWCOLOR = 1,
    IG_VECT_ENT_ATTR_FILLCOLOR = 2,
    IG_VECT_ENT_ATTR_LINETYPEINDEX = 4,
    IG_VECT_ENT_ATTR_THICKNESS = 8,
    IG_VECT_ENT_ATTR_FILLTYPEINDEX = 16,
    IG_VECT_ENT_ATTR_OFFSET = 32,
    IG_VECT_ENT_ATTR_ROTATION = 64,
    IG_VECT_ENT_ATTR_SCALE = 128,
    IG_VECT_ENT_ATTR_POSITION = 256
} enumIGVectAttrib;

Values:

IG_VECT_ENT_ATTR_DRAWCOLOR
The attribute is a draw color. get_AttribPtr returns a pointer to IGVectColorEx.
IG_VECT_ENT_ATTR_FILLCOLOR
The attribute is a fill color. get_AttribPtr returns a pointer to IGVectColorEx.
IG_VECT_ENT_ATTR_LINETYPEINDEX
The attribute is a line type index. get_AttribPtr returns a pointer to long.
IG_VECT_ENT_ATTR_THICKNESS
An attribute is a line thickness. get_AttribPtr returns a pointer to float.
IG_VECT_ENT_ATTR_FILLTYPEINDEX
An attribute is a fill type index. get_AttribPtr returns a pointer to long.
IG_VECT_ENT_ATTR_OFFSET
An attribute is an entity offset. get_AttribPtr returns a pointer to IGVectPoint3D.
IG_VECT_ENT_ATTR_ROTATION
An attribute is an entity rotation. get_AttribPtr returns a pointer to IIGVectRotation.
IG_VECT_ENT_ATTR_SCALE
An attribute is an entity scale factors. get_AttribPtr returns a pointer to IGVectPoint3D.
IG_VECT_ENT_ATTR_POSITION
An attribute is a position of an entity inside the block. get_AttribPtr returns a pointer to IGVectPoint3D.


enumIGVectAttrSource

Group: Enum

Description:

These constants define a source of the attribute. Applicable to color, lite type index and fill type index.

Declaration:

typedef enum enumIGVectAttrSource
{
    IG_VECT_ATTR_SOURCE_ACTUAL = -1,
    IG_VECT_ATTR_SOURCE_NONE = IG_VECT_ATTR_SOURCE_ACTUAL,
    IG_VECT_ATTR_SOURCE_BLOCK = -2,
    IG_VECT_ATTR_SOURCE_LAYER = -3
} enumIGVectAttrSource;

Values:

IG_VECT_ATTR_SOURCE_ACTUAL
use an actual value of attribute. Color is defined by its red, green, blue and alptha components, line type and fill type use they default values.
IG_VECT_ATTR_SOURCE_NONE
the same as IG_VECT_ATTR_SOURCE_ACTUAL
IG_VECT_ATTR_SOURCE_BLOCK
use an attribute attached to the current block
IG_VECT_ATTR_SOURCE_LAYER
use the layer attribute


enumIGVectDir

Group: Enum

Description:

These constants define a direction of the rotate operations.

Declaration:

typedef enum enumIGVectDir
{
    IG_VECT_DIR_XY,
    IG_VECT_DIR_YZ,
    IG_VECT_DIR_XZ
} enumIGVectDir;

Values:

IG_VECT_DIR_XY
rotation in XY direction
IG_VECT_DIR_YZ
rotation in YZ direction
IG_VECT_DIR_XZ
rotation in XZ direction


enumIGVectEntities

Group: Enum

Description:

These constants define all vector entities.

Declaration:

typedef enum enumIGVectEntities
{
    IG_VECT_ENT_UNKNOWN,
    IG_VECT_ENT_BLOCK,
    IG_VECT_ENT_EASYLINE,
    IG_VECT_ENT_POLYGON,
    IG_VECT_ENT_ELLIPSE,
    IG_VECT_ENT_ARC,
    IG_VECT_ENT_TEXT,
    IG_VECT_ENT_BEZIER_CURVE,
    IG_VECT_ENT_NURBS_CURVE,
    IG_VECT_ENT_EASY_SURFACE,
    IG_VECT_ENT_NURBS_SURFACE,
    IG_VECT_ENT_VIEWPORT,
    IG_VECT_ENT_BEZIER_SURFACE,
    IG_VECT_ENT_SHELL,
    IG_VECT_ENT_SHELLEX,
    IG_VECT_ENT_SOLID,
    IG_VECT_ENT_INSERTION,
    IG_VECT_ENT_GEOMETRY
} enumIGVectEntities;

Values:

IG_VECT_ENT_ARC
The entity is a circular or elliptical arc
IG_VECT_ENT_BEZIER_CURVE
The entity is a Bezier curve
IG_VECT_ENT_BLOCK
The entity is a block
IG_VECT_ENT_EASY_SURFACE
The entity ia an easy surface defining by its meshes
IG_VECT_ENT_EASYLINE
The entity is an easy line, that is, the line having only two points
IG_VECT_ENT_ELLIPSE
The entity is a circle or an ellipse
IG_VECT_ENT_NURBS_CURVE
The entity is non-uniform rational Bi-spline
IG_VECT_ENT_NURBS_SURFACE
The entity is NURBS surface
IG_VECT_ENT_POLYGON
The entity is a multiregion polygon
IG_VECT_ENT_TEXT
The entity is a text
IG_VECT_ENT_UNKNOWN
Doesn't currently have any meaning
IG_VECT_ENT_VIEWPORT
The entity is a viewport
IG_VECT_ENT_BEZIER_SURFACE
The entity is a Bezier surface
IG_VECT_ENT_SHELL
The entity is a shell
IG_VECT_ENT_SHELLEX
The entity is an extended shell
IG_VECT_ENT_SOLID
The entity is a solid
IG_VECT_ENT_INSERTION
The entity is an insertion
IG_VECT_ENT_GEOMETRY
The entity is a geometry


enumIGVectFillMode

Group: Enum

Description:

This enumeration specifies vector fill mode constants. These constants define a winding rule for polygons, that is, which part of a polygon is on the interior.

Declaration:

typedef enum enumIGVectFillMode
{
    IG_VECT_FILLMODE_ODD,
    IG_VECT_FILLMODE_NONZERO,
    IG_VECT_FILLMODE_POSITIVE,
    IG_VECT_FILLMODE_NEGATIVE,
    IG_VECT_FILLMODE_ABS_GEQ_TWO
} enumIGVectFillMode;

Values:

IG_VECT_FILLMODE_ODD
Part is filled if a winding number is odd
IG_VECT_FILLMODE_NONZERO
Part is filled if a winding number is non-zero
IG_VECT_FILLMODE_POSITIVE
Part is filled if a winding number is positive
IG_VECT_FILLMODE_NEGATIVE
Part is filled if a winding number is negative
IG_VECT_FILLMODE_ABS_GEQ_TWO
Part is filled if an absolute value of the winding number is greater or equal 2


enumIGVectFillPattern

Group: Enum

Description:

These constants define a fill stile and fill pattern.

Declaration:

typedef enum enumIGVectFillPattern
{
    IG_VECT_FP_SOLID = 0,
    //hatch
    IG_VECT_FP_HATCH_BDIAGONAL = 1,
    IG_VECT_FP_HATCH_CROSS = 2,
    IG_VECT_FP_HATCH_DIAGCROSS = 3,
    IG_VECT_FP_HATCH_FDIAGONAL = 4,
    IG_VECT_FP_HATCH_HORIZONTAL = 6,
    IG_VECT_FP_HATCH_VERTICAL = 7,
    IG_VECT_FP_HATCH_MASK = 0xF,
    // shadow
    // to create shadow pattern do shift shadow level (1-100) to
4 ( level <<= 4)
    IG_VECT_FP_SHADOW_MASK = 0x7F << 4
} enumIGVectFillPattern;

Value:

IG_VECT_FP_SOLID
solid filling
IG_VECT_FP_HATCH_BDIAGONAL
right-to-left diagonal filling
IG_VECT_FP_HATCH_CROSS
cross filling
IG_VECT_FP_HATCH_DIAGCROSS
diagonal cross filling
IG_VECT_FP_HATCH_FDIAGONAL
left-to-right diagonal filling
IG_VECT_FP_HATCH_HORIZONTAL
horizontal line filling
IG_VECT_FP_HATCH_VERTICAL
vertical line filling
IG_VECT_FP_HATCH_MASK
mask that allow detection and selecting hatch fill type
IG_VECT_FP_SHADOW_MASK
mask that allow setting shadow fill pattern. Shadow pattern is created by shifting shadow level (1-100) to 4 and adding to the shadow mask.


enumIGVectHeaderType

Group: Enum

Description:

These constants define how an arc is closed.

Declaration:

typedef enum enumIGVectHeaderType
{
    IG_VECT_HEADER_CAD
} enumIGVectHeaderType;

Values:

IG_VECT_HEADER_CAD - the drawing header is represented in the CAD form

(is not implemented)


enumIGVectGeometryType

Group: Enum

Description:

This enumeration specifies vector geometry types.

Declaration:

typedef enum enumIGVectGeometryType
{
    IG_VECT_GEOM_POINTS = 0,
    IG_VECT_GEOM_LINES = 1,
    IG_VECT_GEOM_LINE_LOOP = 2,
    IG_VECT_GEOM_LINE_STRIP = 3,
    IG_VECT_GEOM_TRIANGLES = 4,
    IG_VECT_GEOM_TRIANGLE_STRIP = 5,
    IG_VECT_GEOM_TRIANGLE_FAN = 6,
    IG_VECT_GEOM_QUADS = 7,
    IG_VECT_GEOM_QUAD_STRIP = 8,
    IG_VECT_GEOM_QUAD_POLYGON = 9
} enumIGVectGeometryType;

Values:

IG_VECT_GEOM_POINTS
geometry is a set of separated points
IG_VECT_GEOM_LINES
geometry is a group of separated lines
IG_VECT_GEOM_LINE_LOOP
geometry is a group of line segments. The last line is connected to the first one
IG_VECT_GEOM_LINE_STRIP
geometry is a group of line segments
IG_VECT_GEOM_TRIANGLES
geometry is a group of separated triangles
IG_VECT_GEOM_TRIANGLE_STRIP
geometry is a triangle strip
IG_VECT_GEOM_TRIANGLE_FAN
geometry is a triangle fan
IG_VECT_GEOM_QUADS
geometry is a group of separated qadrilaterals
IG_VECT_GEOM_QUAD_STRIP
geometry is a quadrilateral strip
IG_VECT_GEOM_POLYGON
geometry is a polygon


enumIGVectGraphics

Group: Enum

Description:

These constants define a graphics tool for vector data drawing.

Declaration:

typedef enum enumIGVectGraphics
{
    IG_VECT_GRAPH_OPENGL
    IG_VECT_GRAPH_WINAPI
} enumIGVectGraphics;

Values:

IG_VECT_GRAPH_OPENGL
drawing with OpenGL
IG_VECT_GRAPH_WINAPI
drawing with WinApi


enumIGVectMeasurementUnits

Group: Enumeration

Description:

Measurement units

Declaration:

typedef enum enumIGVectMeasurementUnits
{
    IG_VECT_MUNIT_UNKNOWN,
    // Metrics units
    IG_VECT_MUNIT_MM,
    IG_VECT_MUNIT_CM,
    IG_VECT_MUNIT_M,
    // English
    IG_VECT_MUNIT_INCHES,
    // Device units
    IG_VECT_MUNIT_PLTS, // plot units, 1/40 mm
    IG_VECT_MUNIT_TWIPS // 1/1440 inch
} enumIGVectMeasurementUnits;

Values:

IG_VECT_MUNIT_UNKNOWN
Unknown
IG_VECT_MUNIT_MM
Metrics units - millimeter
IG_VECT_MUNIT_CM
Metrics units - centimeter
IG_VECT_MUNIT_M
Metrics units - meter
IG_VECT_MUNIT_INCHES
English units - inches
IG_VECT_MUNIT_PLTS
Plot units - 1/40 mm
IG_VECT_MUNIT_TWIPS
Plot units - 1/1440 inch


enumIGVectNURBSFlags

Group: Enum

Description:

These constants define different non-uniform rational Bi-spline flags.

Declaration:

typedef enum enumIGVectNURBSFlags
{
    IG_VECT_NURBS_UNIFORM = 1,
    IG_VECT_NURBS_RATIONAL = 2,
    IG_VECT_NURBS_MCLOSED = 4,
    IG_VECT_NURBS_NCLOSED = 8,
    IG_VECT_NURBS_MINTERPOLATE = 16,
    IG_VECT_NURBS_NINTERPOLATE = 32,
    IG_VECT_NURBS_MFIT = 64,
    IG_VECT_NURBS_NFIT = 128,
} enumIGVectNURBSFlags;

Values:

IG_VECT_NURBS_UNIFORM
the spline is uniform
IG_VECT_NURBS_RATIONAL
the spline is rational
IG_VECT_NURBS_MCLOSED
the spline is closed in M-direction
IG_VECT_NURBS_NCLOSED
the spline is closed in N-direction
IG_VECT_NURBS_MINTERPOLATE
the curve must be interpolated in M-direction
IG_VECT_NURBS_NINTERPOLATE
the curve must be interpolated in N-direction
IG_VECT_NURBS_MFIT
not used now
IG_VECT_NURBS_NFIT
not used now


enumIGVectTxtFlags

Group: Enum

Description:

These constants define additional effects when drawing a text object.

Declaration:

typedef enum enumIGVectTxtFlags
{
    IG_VECT_TXT_UNDERLINED = 1,
    IG_VECT_TXT_STRUCK = 2,
    IG_VECT_TXT_DBLSTRUCK = 4,
    IG_VECT_TXT_SUPERSCRIPT = 8,
    IG_VECT_TXT_SUBSCRIPT = 16
} enumIGVectTxtFlags;

Values:

IG_VECT_TXT_UNDERLINED
a text object is underlined
IG_VECT_TXT_STRUCK
a text object is struck
IG_VECT_TXT_DBLSTRUCK
a text object is double struck
IG_VECT_TXT_SUPERSCRIPT
a text object is a superscript
IG_VECT_TXT_SUBSCRIPT
a text object is a subscript


enumIGVectVertexData

Group: Enum

Description:

These constants define an additional data assigned to the vertex.

Declaration:

typedef enum enumIGVectVertexData
{
    IG_VECT_VERTDATA_NONE,
    IG_VECT_VERTDATA_BULGE,
    IG_VECT_VERTDATA_THICKNESS,
    IG_VECT_VERTDATA_WEIGHT
}
enumIGVectVertexData;

Values:

IG_VECT_VERTDATA_NONE
vertex don't have any additional data
IG_VECT_VERTDATA_BULGE
the outgoing line is bulged
IG_VECT_VERTDATA_THICKNESS
the outgoing line has a local thickness
IG_VECT_VERTDATA_WEIGHT
the vertex has weight. Used with rational Bi splines


Vector Component Structures Reference

The following structures are determined in ImageGear Vector Component:

  • IGVectColor
  • IGVectColorEx
  • IGVectMinMax
  • IGVectPoint2D
  • IGVectPoint3D
  • IGVectPoint3DEx
  • IGVectVertex


IGVectColor

Group: Structure

Declaration:

typedef struct tag_IGVectColor
{
unsigned char m_r;
unsigned char m_g;
unsigned char m_b;
unsigned char m_a;
}
IGVectColor

Structure Members:

m_r
red component
m_g
green component
m_b
blue component
m_a
alpha component

Description:

This structure defines a color for vector drawing.


IGVectColorEx

Group: Structure

Declaration:

typedef struct tag_IGVectColorEx
{
IGVectColor m_color;
long m_flags;
} IGVectColorEx;

Structure Members:

m_color
Actual color value
m_flags
Flags defining a color source. Possible meanings: actual - the m_color field defines a drawing color; byblock - the drawing color is got from the block; bylayer - the drawing color is got from the layer

Description:

Extended color structure. Determines an actual color value for vector drawing.


IGVectMinMax

Group: Structure

Declaration:

typedef struct tag_IGVectMinMax
{
float m_xmin;
float m_xmax;
float m_ymin;
float m_ymax;
float m_zmin;
float m_zmax;
} IGVectMinMax;

Structure Members:

m_xmin
x min coordinate
m_xmax
x max coordinate
m_ymin
y min coordinate
m_ymax
y max coordinate
m_zmin
z min coordinate
m_zmax
z max coordinate

Description:

This structure defines min and max coordinates of views and entities.


IGVectPoint2D

Group: Structure

Declaration:

typedef struct tag_IGVectPoint2D
{
float m_x;
float m_y;
} IGVectPoint2D;

Structure Members:

m_x
x coordinate
m_y
y coordinate

Description:

2D point structure.


IGVectPoint3D

Group: Structure

Declaration:

typedef struct tag_IGVectPoint3D
{
float m_x;
float m_y;
float m_z;
} IGVectPoint3D;

Structure Members:

m_x
x coordinate
m_y
y coopdinate
m_z
z coordinate

Description:

3D point structure.


IGVectPoint3DEx

Group: Structure

Declaration:

typedef struct tag_IGVectPoint3DEx
{
    VECT_REAL m_x;
    VECT_REAL m_y;
    VECT_REAL m_z;
    VECT_REAL m_w;
} IGVectPoint3DEx;

Structure Members:

m_x
x coordinate
m_y
y coopdinate
m_z
z coordinate
m_w
weight of the point

Description:

This structure declares an extended three-dimentional point. The extended point contains one additional field that is used as a weight for NURBS surfaces.


IGVectVertex

Group: Structure

Declaration:

typedef struct tag_IGVectVertex
{
IGVectPoint3D m_point;
unsigned long m_flags;
} IGVectVertex;

Structure Members:

m_point
3D coordinate
m_flags
Flag that is used internally to define different vertex attributes such as visibility, bulge, local thickness and weight. Should not be changed by the user.

Description:

This structure defines a vertex.


enumIGVectGradientSpreadMethod

Group: Enum

Description:

These constants define gradient spread methods. Spread method specifies how the gradient is expanded.

Declaration:

typedef enum enumIGVectGradientSpreadMethod
{
IG_VECT_GRADIENT_SPREAD_PAD,
IG_VECT_GRADIENT_SPREAD_REFLECT,
IG_VECT_GRADIENT_SPREAD_REPEAT
}
enumIGVectGradientSpreadMethod;

Values:

IG_VECT_GRADIENT_SPREAD_PAD
Expand the first or last color.
IG_VECT_GRADIENT_SPREAD_REFLECT
Repeat the gradient with reflection.
IG_VECT_GRADIENT_SPREAD_REPEAT
Repeat the gradient periodically.


enumIGVectGradientType

Group: Enum

Description:

These constants define gradient types.

Declaration:

typedef enum enumIGVectGradientType
{
IG_VECT_GRADIENT_LINEAR,
IG_VECT_GRADIENT_RADIAL
}
enumIGVectGradientType;

Values:

IG_VECT_GRADIENT_LINEAR
Linear gradient.
IG_VECT_GRADIENT_RADIAL
Radial gradient.