Catenary Systems

Victor Image Processing Library version 5

Summary | New Functions | New Features added to Existing Functions

Summary of What's New in Version 5
Over 60 new functions have been introduced and many existing functions have been extended so that the Victor Library has many new features that will enhance your applications' ability to load, save, and process images. These new features include



Optional versions of the 32-bit Library
The standard Victor Library is a DLL that is statically linked with the C run time library. The library for 32-bit Windows is also available in two other forms all multithread safe. These options are available at $50 each to registered owners of the Victor Library v 5.0.

bmpinfofrombuffer


Summary

int bmpinfofrombuffer(buff, bminfo);
unsigned char huge *buff;       Buffer address
BITMAPINFOHEADER far *bminfo;   Structure to receive data
Description
The bmpinfofrombuffer function reads the header information from memory holding BMP file data and places the image information in the bminfo structure. The purpose of the bmpinfofrombuffer function is to identify the type and size of the image and permit allocating enough memory to load the file.

The BITMAPINFOHEADER structure is defined in the WINDOWS SDK and is reproduced below.

typedef struct tagBITMAPINFOHEADER {
   DWORD biSize;          // Size of this struct
   DWORD biWidth;         // Image width in pixels
   DWORD biHeight;        // Image height in pixels
   WORD  biPlanes;        // Planes = 1
   WORD  biBitCount;      // Color bits per pixel 1, 4, 8, 24
   DWORD biCompression;   // Compression type
   DWORD biSizeImage;     // Image size in bytes
   DWORD biXPelsPerMeter, biYPelsPerMeter; // Horiz, vert res
   DWORD biClrUsed;       // Number of colors used
   DWORD biClrImportant;  // Number of important colors
   } BITMAPINFOHEADER;

The BMP file data contains a BITMAPFILEHEADER followed by a device independent bitmap (DIB) consisting of a BITMAPINFO structure and an array of bytes defining the pixels of the bitmap.

Return value    Explanation
NO_ERROR    Function successful
BAD_OPN    Memory handle not available
BAD_BMP    File is not a readable BMP format
BAD_PTR    Buff points at unreadable memory

See also bmpinfo

Example See loadbmpfrombuffer


clienttoimage

            1    8   24 

Summary

int clienttoimage(hwnd, resimg);
HWND hwnd;              Window handle
imgdes far *resimg;     Result image
Description
The clienttoimage function creates a Victor-compatible image from a window's client area. This function provides an easy way to capture the client area of a window displayed on the screen.

The result image will have the same bits per pixel as the current display mode. If the function is successful the image descriptor resimg is filled in. Clienttoimage allocates memory to hold the image, so freeimage must be called when this memory is no longer needed.

Return value    Explanation
NO_ERROR    Function successful
BAD_MEM    Insufficient memory
BAD_BPP    Bits per pixel not 1, 4, 8, 16, or 24

See also
windowtoimage

Example

int CaptureScreenClient(HWND hWnd)
{
   int rcode;
   imgdes timage;
   char *fname = "client.tif";

   // Capture window as Victor image
   rcode = clienttoimage(hWnd, &timage);
   if(rcode == NO_ERROR) {
      // Save captured client area
      rcode = savetif(fname, &timage, 0);
      // Release memory allocated by clienttoimage()
      freeimage(&timage);
      }
   return(rcode)
}

This example captures a window's client area and saves it as a TIFF file.




convertgray8to16

                8 


Summary

int convertgray8to16(srcimg, resimg);
imgdes far *srcimg;     Source image 
imgdes far *resimg;     Result image 

Description
The convert8to16 function converts a grayscale 8-bit per pixel source image area into a grayscale 16-bit per pixel result image area. The source and result image areas are defined by the corresponding image descriptors. A 16-bit grayscale image can be saved with savetif.

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error, see Appendix A
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Source is not 8-bit or result is not 16-bit
BAD_DIB    Source or result is a compressed DIB

Example
See convertgray16to8




convertgray16to8

                16 


Summary

int convertgray16to8(srcimg, resimg);
imgdes far *srcimg;      Source image 
imgdes far *resimg;      Result image 

Description
The convert16to8 function converts a grayscale 16-bit per pixel source image area into a grayscale 8-bit per pixel result image area. The source and result image areas are defined by the corresponding image descriptors.

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error, see Appendix A
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Source is not 16-bit or result is not 8-bit
BAD_DIB    Source or result is a compressed DIB

Example

int process16bitGrayTIFF(char *fname)
{
   int rcode;
   TiffData tdat;
   imgdes timage;

   rcode = tiffinfo(fname, &tdat); // Fill structure
   if(rcode == NO_ERROR && 
      // Make sure image to load is 16-bit grayscale
      tdat.BitsPSample == 16 && tdat->SamplesPPixel == 1)
      // Allocate memory for image storage
      rcode = allocimage(&timage, tdat.width, tdat.length, tdat.vbitcount);
      if(rcode == NO_ERROR)
         // Read in a 16-bit grayscale TIFF file
         rcode = loadtif(fname, &timage);
         if(rcode == NO_ERROR) {
            imgdes nimage;
            allocimage(&nimage, tdat.width, tdat.length, 8);
            // Convert image to 8-bit
            rcode = convertgray16to8(&timage, &nimage);
            if(rcode == NO_ERROR) {
               // Process image
               histoequalize(&nimage, &nimage);
               // Convert image back to 16-bits
               convertgray8to16(&nimage, &timage);
               // Save processed 16-bit image
               rcode = savetif(fname, &timage, 0);
               freeimage(&nimage); // Release memory allocated for 8-bit image
               }
            }
         // Release memory allocated for 16-bit image
         freeimage(&timage);
         }
      }
   return(rcode)
}

This function loads a 16-bit grayscale image, converts it to 8-bits, performs image processing on it, converts it back to a 16-bit image, and saves it.




coverclear

                8   24 


Summary

int coverclear(transcolor, srcimg, oprimg, resimg);
const long transColor;   Transparent color(0-0xffffff)
imgdes far *srcimg;      Source image 
imgdes far *oprimg;      Operator image 
imgdes far *resimg;      Result image 

Description
The coverclear function places the operator image onto the source image. In regions of the operator where pixel values are equal to transcolor the source image will show through. The image areas are defined by the corresponding image descriptors.

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error, see Appendix A
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Images are not both 8- or 24-bit
BAD_DIB    Source or result is a compressed DIB
BAD_FAC    Transcolor is outside the range 0 (black) to 0xffffff (white)

See also
cover

Example

int addShadowWithCoverClear(imgdes *srcimg, imgdes *desimg)
{
   imgdes tmpsrc;
   // Drop shadow at horiz offset 10, vert offset 5
   int hoffset = 10, voffset = 5;
   int rcode, cols, rows;
   long transcolor = 0xffffff; // White

   cols = CALC_WIDTH(srcimg); // Macros in VICDEFS.H
   rows = CALC_HEIGHT(srcimg);

   // Create the shadow in a temp buffer
   rcode = allocimage(&tmpsrc, cols, rows, srcimg->bmh->biBitCount);
   if(rcode == NO_ERROR) {
      zeroimage(255, &tmpsrc); // Set all pixels to white
      tmpsrc.stx = hoffset;
      tmpsrc.sty = voffset;
      copyimage(srcimg, &tmpsrc); // Copy src image to offset pos

      tmpsrc.stx = 0;
      tmpsrc.sty = 0;
      kodalith(255, &tmpsrc, &tmpsrc); // Turn all pixels not white to black
      changebright(64, &tmpsrc, &tmpsrc); // Black -> dark gray
      for(j=0; j<25; j++) // Simulate gaussian blur
         blur(&tmpsrc, &tmpsrc);
      // Cover the shadow with the original image
      rcode = coverclear(transcolor, &tmpsrc, srcimg, desimg);
      freeimage(&tmpsrc); // Delete temp image
      }
   return(rcode);
}

This example creates a drop shadow of all non-white pixels in the image.




ddbtoimage

            1    8   24 


Summary

int ddbtoimage(hbitmap, hpal, resimg);
HBITMAP hbitmap;         Device dependent bitmap handle
HPALETTE hPal;           Palette handle or NULL
imgdes far *resimg;      Result image

Description
The ddbtoimage function creates a Victor-compatible image from a device dependent bitmap and palette. If hPal is NULL the Windows default palette will be used. If the function is successful the image descriptor resimg is filled in.

Ddbtoimage allocates memory to hold the image, so freeimage must be called when this memory is no longer needed.

Return value    Explanation
NO_ERROR    Function successful
BAD_MEM    Insufficient memory
BAD_HANDLE    Invalid bitmap handle

See also
dibtoimage

Example

int SaveBitmapToTiffFile(HBITMAP hBitmap, HPALETTE hPal)
{
   int rcode;
   imgdes timage;
   char *fname = "bitmap.tif";
   
   rcode = ddbtoimage(hBitmap, hPal, &timage);
   if(rcode == NO_ERROR) {
      // Save captured image
      rcode = savetif(fname, &timage, 0);
      freeimage(&timage);
      }
   return(rcode);
}

This example saves a device dependent bitmap as a TIFF file.




dibsecttoimage

            1    8   24 


Summary

int dibsecttoimage(hBitmap, image);
HBITMAP hBitmap;         DIB section handle
imgdes far *image;       Image 

Description
The dibsecttoimage function creates a Victor-compatible image from a DIB-section (WIN32 device independent bitmap). This function is useful when a DIB is imported from another source to allow Victor functions to operate on it.

Although Windows allows the palette data of a DIB to be indexes into the currently realized logical palette, dibsecttoimage assumes explicit RGB values. If the function is successful the image descriptor resimg is filled in.

Dibsecttoimage allocates memory to hold the image, so freeimage must be called when this memory is no longer needed. Dibsecttoimage is available only in the Victor Library for 32-bit Windows, excluding Windows NT versions earlier than 3.51.

Return value    Explanation
NO_ERROR    Function successful
BAD_MEM    Insufficient memory
BAD_HANDLE    HBitmap is not a DIB section bitmap handle
BAD_DIB    DIB is compressed
BAD_BPP    Bits per pixel is not 1, 8, or 24

See also
dibtoimage

Example

int SaveDIBSectToTiffFile(HBITMAP hBitmap)
{
   int rcode;
   imgdes timage;
   char *fname = "bitmap.tif";
   
   rcode = dibsecttoimage(hBitmap, &timage);
   if(rcode == NO_ERROR) {
      // Save captured image
      rcode = savetif(fname, &timage, 0);
      freeimage(&timage);
      }
   return(rcode);
}

This example saves a DIB section as a TIFF file.




dilate

            1    8   24 


Summary

int dilate(amount, srcimg, resimg);
const int amount;        Amount of dilation (0 - 255)
imgdes far *srcimg;      Source image 
imgdes far *resimg;      Result image 

Description
The dilate function darkens an image area by enlarging the dark regions of the image. The variable amount determines the extent of the darkening. Maximum dilation is obtained when amount set to 255 and no dilation occurs if amount is set to zero. If the average brightness of a pixel's 3 x 3 local area is darker than amount, the pixel is replaced by its darkest neighbor.

The image areas are defined by the corresponding image descriptors.

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error (see Appendix A) or image area is less than 3 x 3 pixels
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Images are not both 8- or 24-bit
BAD_DIB    Source or result is a compressed DIB
BAD_FAC    Amount is outside range of 0 - 255

Example

int darkenByDilation(HWND hWnd, imgdes *image)
{
   int rcode, amount = 200;

   rcode = dilate(amount, image, image);
   if(rcode != NO_ERROR)
      MessageBox(hWnd, "Error in darken by dilation", 0, MB_OK);
   return(rcode); 
}

This example darkens an image using dilation.




erode

            1    8   24 


Summary

int erode(amount, srcimg, resimg);
const int amount;        Amount of erosion (0 - 255)
imgdes far *srcimg;      Source image 
imgdes far *resimg;      Result image 

Description
The erode function brightens an image area by enlarging the bright regions of the image. The variable amount determines the extent of the brightening. Maximum erosion is obtained with amount set to 255 and no erosion occurs if amount is set to zero.

Erode examines a pixel's 3 x 3 local area. If the average brightness of the local area is brighter than 255 minus amount, the central pixel is replaced by its brightest neighbor.

The image areas are defined by the corresponding image descriptors.

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error (see Appendix A) or image area is less than 3 x 3 pixels
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Images are not both 8- or 24-bit
BAD_DIB    Source or result is a compressed DIB
BAD_FAC    Amount is outside range of 0 - 255

Example

int brightenByErosion(HWND hWnd, imgdes *image)
{
   int rcode, amount = 200;

   rcode = erode(amount, image, image);
   if(rcode != NO_ERROR)
      MessageBox(hWnd, "Error in brighten by erosion", 0, MB_OK);
   return(rcode); 
}

This example brightens an image using erosion.




getpngcomment


Summary

int getpngcomment(filename, type, buffer, buffermax);
const char far *filename;  Filename to read
char far *type;            Comment type
char far *buffer;          Buffer to receive comment
int buffermax;             Maximum number of characters buffer will hold,
                           including null terminator

Description
The getpngcomment function copies a comment string (if present) from a PNG file to a buffer. If the number of characters in the comment exceeds buffermax, the string is truncated to fit into buffer. To determine the size of the buffer to allocate to hold the string, call getpngcomment with buffer equal 0 (see example).

Only uncompressed comments can be retrieved with getpngcomment. The defined comment type values are "Title", "Author", "Description", "Copyright", "Creation Time", "Software", "Disclaimer", "Warning", "Source", and "Comment."

Return value    Explanation
0 to 32768    Actual number of characters copied into buffer
BAD_OPN    Filename not found
BAD_PNG    File is not a valid PNG file

Example

void readAPNGComment(HWND hWnd, char *fname)
{
   int rcode, comlen;
   char buff[80], near *combuff;

   // Get comment length  
   rcode = getpngcomment(fname, "Comment", 0, 0);
   switch(rcode) {
      case(BAD_OPN):
         wsprintf(buff, "Cannot open %s", (LPSTR)fname); break;
      case(BAD_PNG):
         wsprintf(buff, "Bad PNG: %s", (LPSTR)fname); break;
      case(0):
         wsprintf(buff, "No comment in %s", (LPSTR)fname); break;
      default:  // Getpngcomment() returned length of comment
         comlen = rcode;   // Save length of comment
         // Allocate space for comment string
         combuff = (char near *)calloc(comlen + 1, sizeof(char));
         if(combuff == NULL) {
            wsprintf(buff, "Insufficient memory");
            rcode = BAD_MEM;
            }
         else {    // Get the comment
            getgifcomment(fname, combuff, comlen + 1);
            // Display comment in message box
            MessageBox(hWnd, combuff, 0, MB_OK);
            free(combuff);
            }
      }
   if(rcode <= 0) // If error, display error message
      MessageBox(hWnd, buff, 0, MB_OK);
}

This example reads and displays a comment string in a PNG file.




gifinfofrombuffer


Summary

int gifinfofrombuffer(buff, ginfo);
unsigned char huge *buff;       Buffer address
typedef struct {                Structure to contain GIF file data
   int width, length;           Image width and length in pixels
   int BitsColRes;              Number of bits of color resolution
   int BitsPPixel;              Number of bits per pixel
   int TransColor;              Transparent color
   int Laceflag;                Interlace flag
   int Codesize;                LZW code size
   int GIFvers;                 GIF version, 87 or 89
   int vbitcount;               Victor bits per pixel (used to allocate an
                                image buffer with allocimage)
   } GifData far *ginfo;        Pointer to structure

Description

The gifinfofrombuffer function reads the header information from memory holding GIF file data and places the image information in the ginfo structure. The purpose of the gifinfofrombuffer function is to identify the type and size of the image and permit allocating enough memory to load the file.

If a GIF file contains a transparent color, gifinfo will return it in the structure element TransColor. If a transparent color is not present, TransColor is set to -1.

Return value    Explanation
NO_ERROR    Function successful
BAD_OPN    Memory handle not available
BAD_GIF    File is not a valid GIF file
BAD_PTR    Buff does not point to readable memory

See also
gifinfo

Example
See loadgiffrombuffer




isgrayscaleimage

            1    8   24 


Summary

BOOL isgrayscaleimage(image);
imgdes far *image;          Image 

Description
The isgrayscaleimage function examines the image's palette information and reports whether it is grayscale. This function does not alter the value of the image descriptor element imgtype.

To be judged grayscale an image must have a palette with these characteristics:

This function returns FALSE if the image does not have a palette, for example for a 16-bit grayscale or a 24-bit RGB image.

The file load functions call isgrayscaleimage internally and correctly set the value of the image descriptor element imgtype.

Return value    Explanation
TRUE    Image is grayscale
FALSE    Image is not grayscale




jpeggeterror


Summary

int jpeggeterror(void);

Description
The jpeggeterror function reports extended error information after a JPEG function returns BAD_JPEG.

Return value    Explanation
0    No extended error information
-100    Sample precision is not 8
-101    Unexpected End Of File
-102    Reset marker could not be found
-103    Invalid marker found in the image data
-104    Error reading data from the file
-105    Invalid data found in JPEG file
-106    Component info out of bounds
-107    Blocks in an MCU is greater than 10
-108    Bits per sample is not 8
-109    Invalid number of components
-110    File type not SOF0, SOF1, or SOF2
-111    Unexpected End Of Image
-112    File is not JPEG JFIF
-113    Bad progressive JPEG scan parameter

Example

int loadAJpegFile(HWND hWnd, char *fname, imgdes *image)
{
   JpegData jdat;
   int rcode;

   // Get info on the file we're to load
   rcode = jpeginfo(fname, &jdat);
   if(rcode == NO_ERROR) { // Fill structure
      // Allocate space for an image
      rcode = allocimage(image, (int)jdat.width, (int)jdat.length, jdat.vbitcount);
      if(rcode == NO_ERROR) {
         // Load image
         rcode = loadjpg(fname, image);
         if(rcode == BAD_JPEG) {
            char szBuff[128];
            // Get extended error info
            int extRcode = jpeggeterror();
            wsprintf(szBuff, "Error in loading %s: extended error code %d", (LPSTR)fname, extRcode);
            MessageBox(hWnd, szBuff, 0, MB_OK);
            }
         freeimage(image); // Free image on error
         }
      }
   return(rcode);
}

This function reports extended error information when a JPEG file cannot be loaded.




loadbmpfrombuffer

            1    8   24 


Summary

int loadbmpfrombuffer(buff, image); 
unsigned char huge *buff;   Buffer address
imgdes far *image;          Image 

Description
The loadbmpfrombuffer function loads BMP file data from a memory buffer into an area in an image buffer defined by the image descriptor. Palette data is loaded into the buffer defined by the image descriptor member palette.

The BMP file header includes the image dimensions. If these dimensions do not match the dimensions of the area defined by the image descriptor, the smaller of the two will be used to load the file. Loadbmpfrombuffer will enter into the image descriptor member colors the number of palette colors loaded.

Loadbmpfrombuffer loads 1-, 4-, 8-, 16-, 24-, or 32-bit BMP files. When 4-bit BMP files are loaded, they are expanded into 8-bit image buffers and when 16- or 32-bit BMP files are loaded they are stored in 24-bit image buffers.

BMP file data contains a BITMAPFILEHEADER followed by a device independent bitmap (DIB) consisting of a BITMAPINFO structure, which describes the dimensions and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits in the array are packed together, but each scan line must be zero-padded to end on a LONG boundary. The origin of the bitmap is the lower-left corner.

DIBs are discussed in the Victor User's Guide. The BMP file format data structures are discussed in Microsoft Windows SDK Programmer's Reference.

Return value   Explanation
NO_ERROR   Function successful
BAD_RANGE   Range error, see Appendix A
BAD_IBUF   Invalid image buffer address
BAD_MEM   Insufficient memory
BAD_BPP   Image is not 1-, 8-, or 24-bit or image and file are not compatible bits per pixel
BAD_DIB   Source or result is a compressed DIB
BAD_OPN   Memory handle not available
BAD_BMP   File is not a readable BMP format
BAD_CMP   Unreadable compression scheme
BAD_PTR   Buff points at unreadable memory

See also bmpinfo, savebmp




loadbmppalettefrombuffer


Summary

int loadbmppalettefrombuffer(buff, paltable);
unsigned char huge *buff;    Buffer address where BMP file data begins
RGBQUAD far *paltable;       Storage buffer for palette values

Description
The loadbmppalettefrombuffer function loads the palette data from a memory buffer holding BMP file data into paltable. Paltable must be large enough to hold all of the palette data:
biBitCount  Palette table size (bytes)
1 8
4 64
8 1024
24 0

When loading a BMP file, it is not necessary to call this function, because loadbmpfrombuffer automatically loads any palette data available if the image descriptor member palette is nonzero.

Return value    Explanation
0 - 256   Number of palette colors read
BAD_MEM   Insufficient memory
BAD_OPN   Memory handle not available
BAD_BMP   File is not a readable BMP format
BAD_PTR   Buff points at unreadable memory




loadgiffrombuffer

            1    8 


Summary

int loadgiffrombuffer(buff, image); 
unsigned char huge *buff;   Buffer address
imgdes far *image;          Image 

Description
The loadgiffrombuffer function loads image data from a memory buffer holding GIF file data into an area in an image buffer defined by the image descriptor. Palette data is loaded into the buffer defined by the image descriptor member palette.

Before making the first call to loadgif, unlockLZW should be called to enable reading LZW-compressed files. Otherwise loadgif will only read uncompressed GIF files.

The GIF file header includes the image dimensions. If these dimensions do not match the dimensions of the area defined by the image descriptor, the smaller of the two will be used to load the file.

Loadgiffrombuffer will enter into the image descriptor member colors the number of palette colors loaded. Loadgiffrombuffer loads 1- to 8-bit GIF images. 1-Bit GIF images are loaded into 1-bit image buffers and 2- to 8-bit GIF images are loaded into 8-bit image buffers.
The transparent color in a GIF file can be obtained using the gifinfofrombuffer function.

An attempt to load an image from LZW-compressed file data will return the error code LZW_DISABLED unless LZW functionality has been enabled with unlockLZW. The use of LZW compression requires an LZW license from Unisys Corporation. For information concerning licensing the LZW compression and/or decompression capability, please contact: Unisys Corporation, Welch Licensing Department - C1SW19, Township Line & Union Meeting Roads, P O Box 500, Blue Bell PA 19424, www.unisys.com.

Return value   Explanation
NO_ERROR   Function successful
BAD_RANGE   Range error, see Appendix A
BAD_IBUF   Invalid image buffer address
BAD_MEM   Insufficient memory
BAD_BPP   Image is not 1- or 8-bit
BAD_DIB   Source or result is a compressed DIB
BAD_OPN   Memory handle not available
BAD_GIF   File is not a readable GIF format
LZW_DISABLED   LZW functionality not available, see unlockLZW
BAD_PTR   Buff points at unreadable memory

See also gifinfofrombuffer, loadgifpalettefrombuffer, savegiftobufferex




loadgifpalettefrombuffer


Summary
int loadgifpalettefrombuffer(buff, paltable); 
unsigned char huge *buff;   Buffer address where GIF file data begins
RGBQUAD far *paltable;      Storage buffer for palette values

Description
The loadgifpalettefrombuffer function loads the palette data from a memory buffer holding GIF file data into paltable. Paltable must be an array of 256 RGBQUAD structures (1024 bytes). A GIF image may contain up to 256 colors.

When loading a GIF file, it is not necessary to call this function, because loadgiffrombuffer automatically loads any palette data available if the image descriptor member palette is nonzero.

Return value   Explanation
0 - 256   Number of palette colors read
BAD_MEM   Insufficient memory
BAD_OPN   Memory handle not available
BAD_GIF   File is not a readable GIF format
BAD_PTR   Buff points at unreadable memory




loadpng

            1    8   24 

Summary
int loadpng(filename, image); 
const char far *filename;   Filename to load
imgdes far *image;          Image 

Description
The loadpng function loads image data from a PNG file into an area in an image buffer defined by the image descriptor. Palette data is loaded into the buffer defined by the image descriptor member palette.

The PNG file header includes the image dimensions. If these dimensions do not match the dimensions of the area defined by the image descriptor, the smaller of the two will be used to load the file.

Loadpng will enter into the image descriptor member colors the number of palette colors loaded. Loadpng loads all PNG images. 1-Bit PNG images are loaded into 1-bit image buffers and 2- to 8-bit PNG images are loaded into 8-bit image buffers. All grayscale PNG images are loaded into 8-bit buffers. All RGB images are loaded into 24-bit buffers. Alpha channel data is ignored. Supported pixel depth is 1- to 64-bit.

The transparent color(s) in a PNG file can be obtained using the pnginfo function. If a transparent color is present, pnginfo will return it in the structure element TransData. If a transparent color is not present, the isPresent element of TransData is set to FALSE.

The Victor loadpng function is based on the source code for the ZLIB compression library by Jean-loup Gailly and Mark Adler. PNG stands for Portable Network Graphics. This format is intended to be a patent-free replacement for GIF and uses the LZ77 compression rather than LZW.

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error, see Appendix A
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Image is not 1-, 8-, or 24-bit
BAD_DIB    Source or result is a compressed DIB
BAD_OPN    Filename not found
BAD_PNG    File is not a readable Png format

See also

pnginfo, loadpngpalette, savepng, pnggeterror

Example

int loadAPng(HWND hWnd, char *fname, imgdes *image)
{
   PngData pdat;
   int rcode;

   // Get info on the file we're to load
   rcode = pnginfo(fname, &pdat);
   if(rcode != NO_ERROR) { // Fill structure
      MessageBox(hWnd,"Error in reading file", 0, MB_OK);
      return(rcode);
      }
   // Allocate space for the image
   rcode = allocimage(image, pdat.width, pdat.length, pdat.vbitcount);
   if(rcode != NO_ERROR) {
      MessageBox(hWnd,"Not enough memory to load file", 0, MB_OK);
      return(rcode);
      }
   // Load image
   rcode = loadpng(fname, image);
   if(rcode != NO_ERROR) { 
      char szBuff[80];
      wsprintf(szBuff, "Could not load %s", fname);
      MessageBox(hWnd, szBuff, 0, MB_OK); 
      }
   freeimage(image); // Free image on error
   return(rcode);
} 

This example loads an image from a PNG file.




loadpngfrombuffer

            1    8   24 


Summary

int loadpngfrombuffer(buff, image); 
unsigned char huge *buff;     Buffer address
imgdes far *image;            Image 

Description
The loadpngfrombuffer function loads PNG file data from a memory buffer into an area in an image buffer defined by the image descriptor. Palette data is loaded into the buffer defined by the image descriptor member palette.

The PNG file header includes the image dimensions. If these dimensions do not match the dimensions of the area defined by the image descriptor, the smaller of the two will be used to load the file.

Loadpngfrombuffer will enter into the image descriptor member colors the number of palette colors loaded. Loadpngfrombuffer loads all PNG images. 1-Bit PNG images are loaded into 1-bit image buffers and 2- to 8-bit PNG images are loaded into 8-bit image buffers. All grayscale PNG images are loaded into 8-bit buffers. All RGB images are loaded into 24-bit buffers. Alpha channel data is ignored. Supported pixel depth is 1- to 64-bit.

The Victor loadpngfrombuffer function is based on the source code for the ZLIB compression library by Jean-loup Gailly and Mark Adler. PNG stands for Portable Network Graphics. This format is intended to be a patent-free replacement for GIF. It uses the LZ77 compression rather than LZW.

Return value  Explanation
NO_ERROR  Function successful
BAD_RANGE   Range error, see Appendix A
BAD_IBUF  Invalid image buffer address
BAD_MEM   Insufficient memory
BAD_BPP   Image is not 1-, 8-, or 24-bit or image and file are not compatible bits per pixel
BAD_DIB   Source or result is a compressed DIB
BAD_OPN   Memory handle not available
BAD_PNG   File is not a readable PNG format
BAD_PTR   Buff points at unreadable memory

See also
pnginfofrombuffer, loadpngpalettefrombuffer, savepngtobuffer, pnggeterror




loadpngpalettefrombuffer


Summary

int loadpngpalettefrombuffer(buff, paltable); 
unsigned char huge *buff;     Buffer address where PNG data begins
RGBQUAD far *paltable;        Storage buffer for palette values

Description
The loadpngpalettefrombuffer function loads the palette data from a memory buffer holding PNG file data into paltable. Paltable must be an array of 256 RGBQUAD structures (1024 bytes). A PNG image may contain up to 256 colors.

When loading a PNG file, it is not necessary to call this function, because loadpngfrombuffer automatically loads any palette data available if the image descriptor member palette is nonzero.

Return value  Explanation
0 - 256  Number of palette colors read
BAD_MEM  Insufficient local memory
BAD_OPN  Memory handle not available
BAD_PNG  File is not a readable PNG format
BAD_PTR  Buff points at unreadable memory




loadpngpalette


Summary

int loadpngpalette(filename, paltable); 
char far *filename;      Filename of PNG file
RGBQUAD far *paltable;   Storage buffer for palette values

Description
The loadpngpalette function loads the palette data from a PNG image file into paltable.

Paltable must be an array of 256 RGBQUAD structures (1024 bytes) since a PNG image may contain up to 256 colors. When loading a PNG file, it is not necessary to call this function, because loadpng automatically loads any palette data available if the image descriptor member palette is nonzero.

Return value    Explanation
0 - 256    Number of palette colors read
BAD_MEM    Insufficient memory
BAD_OPN    Filename not found
BAD_PNG    File is not a readable PNG format

Example

int getPNGpal(HWND hWnd, char *fname, 
   RGBQUAD *paltable)  // paltable must be sizeof(RGBQUAD) * 256
{
   int colors;
   char szBuff[80];

   // Load palette data 
   colors = loadpngpalette(fname, paltable); 
   if(colors >= 0)   // Check range for error 
      wsprintf(szBuff, "%s contains %d colors", (LPSTR)fname, colors);
   else
      wsprintf(szBuff, "Error on loading palette of %s", (LPSTR)fname);
   MessageBox(hWnd, szBuff, 0, MB_OK);
   return(colors);
}

This example loads a PNG color palette into an array and if there are no errors, displays the number of palette colors loaded.




loadtiffrombuffer

            1    8   16   24 


Summary

int loadtiffrombuffer(buff, image);
unsigned char huge *buff;   Buffer address
imgdes far *image;          Image 

Description
The loadtiffrombuffer function loads TIFF file data from a memory buffer into an area in an image buffer. The image area is defined by the image descriptor. Palette data, if present in the file, is loaded into the buffer defined by the image descriptor member palette. For a list of all the formats read by this function refer to loadtif.

The TIFF file header includes the image dimensions. If these dimensions do not match the dimensions of the area defined by the image descriptor, the smaller of the two will be used. Loadtiffrombuffer will enter into the image descriptor member colors the number of palette colors loaded. When 4-bit TIFF files are loaded, they are expanded into 8-bit image buffers. When a grayscale TIFF image is loaded, bit 0 of the image descriptor member imgtype is set to 1.

An attempt to load an LZW-compressed TIFF image will return the error code LZW_DISABLED unlessLZW functionality has been enabled with unlockLZW. The use of LZW compression requires an LZW license from Unisys Corporation. For information concerning licensing the LZW compression/decompression capability, please contact: Unisys Corporation, Welch Licensing Department - C1SW19 Township Line & Union Meeting Roads, P O Box 500, Blue Bell PA 19424, www.unisys.com.

Return value  Explanation
NO_ERROR   Function successful
BAD_RANGE  Range error, see Appendix A
BAD_IBUF   Invalid image buffer address
BAD_MEM   Insufficient memory
BAD_BPP   Image is not 1-, 8-, 16-, or 24-bit or image and file are not compatible bits per pixel
BAD_DIB   Source or result is a compressed DIB
BAD_OPN   Memory handle not available
BAD_TIFF   File is not a readable TIFF format
BAD_CMP   Unreadable compression scheme
TOO_CPLX   File data is too complex to read
LZW_DISABLED   LZW functionality not available, seeunlockLZW
BAD_PTR   Buff points at unreadable memory

See also loadtif, tiffinfofrombuffer, savetiftobuffer




loadtifpagebyindex

            1    8   16   24 


Summary

int loadtifpagebyindex(filename, image, pageIndex);
char far *filename;          Filename of TIFF file
imgdes far *image;           Image 
int pageIndex;               Index of target page to load

Description
The loadtifpagebyindex function loads an image from a single or multipage TIFF file. The image that is to be loaded is specified by the pageIndex parameter, which is zero-based.

Use loadtifpagebyindex to load an image based on its position in the file. Use loadtifpage to load an image based on its page number tag.

Except for being able to load a specific image from a multipage TIFF file, loadtifpagebyindex is identical to the loadtif function.

To determine the number of pages and their page numbers in a multipage TIFF file, use the tiffgetpageinfo function.

If pageIndex is set to -1, calling loadtifpagebyindex will load the first image in a TIFF file.

Return value  Explanation
NO_ERROR   Function successful
BAD_RANGE  Range error, see Appendix A
BAD_IBUF   Invalid image buffer address
BAD_MEM   Insufficient memory
BAD_BPP   Image is not 1-, 8-, 16-, or 24-bit or image and file are not compatible bits per pixel
BAD_DIB   Source or result is a compressed DIB
BAD_OPN   Filename not found
BAD_TIFF   File is not a readable TIFF format
BAD_CMP   Unreadable compression scheme
TOO_CPLX   File data is too complex to read
TIFF_NOPAGE  TIFF page not found and pageIndex is not -1
LZW_DISABLED   LZW functionality not available, seeunlockLZW

See also loadtif, loadtifpage, tiffgetpageinfo, tiffinfopage




loadtifpalettefrombuffer


Summary

int loadtifpalettefrombuffer(buff, paltable); 
unsigned char huge *buff;   Buffer address where TIFF file data begins
RGBQUAD far *paltable;      Storage buffer for palette values

Description
The loadtifpalettefrombuffer function loads the palette data from a memory buffer holding TIFF file data into paltable. Paltable must be an array of 256 RGBQUAD structures (1024 bytes), since a TIFF image may contain up to 256 colors.

When loading a TIFF file, it is not necessary to call this function, because loadtiffrombuffer automatically loads any palette data available if the image descriptor member palette is nonzero.

Return value Explanation
0 - 256   Number of palette colors read
BAD_MEM   Insufficient memory
BAD_OPN   Memory handle not available
BAD_TIFF   File is not a readable TIFF format
BAD_PTR   Buff points at unreadable memory




loadtifpalettepagebyindex


Summary

int loadtifpalettepagebyindex(filename, paltable, pageIndex); 
char far *filename;      Filename of TIFF file
RGBQUAD far *paltable;   Storage buffer for palette values
int pageIndex;           Index of page to load palette from

Description
The loadtifpalettepagebyindex function loads the palette data from a specified page in a palette color TIFF image file into paltable. Paltable must be an array of 256 RGBQUAD structures (1024 bytes), since a TIFF image may contain up to 256 colors.

Use loadtifpalettepagebyindex to load an image palette based on its position in the file. Use loadtifpalettepage to load an image palette based on its page number tag.

When loading a TIFF image, it is not necessary to call this function, because loadtifpagebyindex automatically loads any palette data available if the image descriptor member palette is nonzero.

Return value Explanation
0 - 256   Number of palette colors read
BAD_MEM   Insufficient memory
BAD_OPN   Filename not found
BAD_TIFF   File is not a readable TIFF format
TIFF_NOPAGE   TIFF page not found and pageIndex is not -1

See also
loadtifpalette, loadtifpalettepage




matrixconvex

                8   24 


Summary

int matrixconvex(ksize, kernel, divsr, srcimg, resimg);
const int ksize;         Width of local area (3 - 63)
const char far *kernel;  Convolution matrix
const int divsr          Divisor
imgdes far *srcimg;      Source image 
imgdes far *resimg;      Result image 

Description
The matrixconvex function transforms an image area with a ksize x ksize convolution matrix. The source and result image areas are defined by the corresponding image descriptors.

Result = (convolution of Source with kernel) / divsr

For more information about matrix convolution, see the matrixconv function.

The function argument kernel is a ksize x ksize array whose elements can range from -127 to 127. Ksize must be in the range 3 to 63. This function differs from matrixconv in that matrixconvex allows using a ksize greater than 3 and the divisor value is not the last element of the kernel array.

As an example, to duplicate the blur function use the kernel:

1/9     1/9     1/9
1/9     1/9     1/9
1/9     1/9     1/9

by defining the array:

   char kernel[9] = {1,1,1,1,1,1,1,1,1};

and calling the function:

   matrixconvex(3, kernel, 9 &srcimg, &resimg);

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error, see Appendix A
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Images are not both 8- or 24-bit
BAD_DIB    Source or result is a compressed DIB
BAD_FAC    Divisor value is zero or ksize not 3 to 63

See also  
matrixconv

Example

int detect_horiz2(HWND hWnd, imgdes *image)
{
   static char dethoriz[] = {1, 1, 1, 0, 0, 0, -1, -1, -1};
   int divsr = 1;
   int rcode;
   
   rcode = matrixconvex(3, dethoriz, divsr, image, image);
   if(rcode != NO_ERROR)
      MessageBox(hWnd,"Error at matrixconvex()", 0, MB_OK);
   return(rcode);
}

This example emphasizes the horizontal lines in an image.




medianfilter

                8   24 


Summary

int medianfilter(ksize,  srcimg, resimg);
const int ksize;         Width of local area (3 - 11)
imgdes far *srcimg;      Source image 
imgdes far *resimg;      Result image 

Description
The medianfilter function removes random noise from an image area by replacing a central pixel value with the median of its local area. The local area size is defined as ksize x ksize pixels.

Result = median of ksize x ksize local area

The source and result image areas are defined by the corresponding image descriptors.

The medianfilter function is identical to the removenoise function if ksize equals 3.

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error, see Appendix A
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Images are not both 8- or 24-bit
BAD_DIB    Source or result is a compressed DIB
BAD_FAC    Ksize not 3 to 11

See also removenoise

Example

int watercolor(HWND hWnd, imgdes *image)
{
   int rcode;
   
   rcode = medianfilter(3, image, image);
   if(rcode != NO_ERROR)
      MessageBox(hWnd,"Error at matrixconvex()", 0, MB_OK);
   else {
      medianfilter(5, image, image);
      medianfilter(7, image, image);
      sharpen(image, image);
      }
   return(rcode);
}

This example creates a watercolor painting effect in an image.




pnggeterror


Summary

int pnggeterror(void);

Description
The pnggeterror function reports extended error information after a PNG function returns BAD_PNG.

Return value    Explanation
0    No extended error information
-100    Unknown critical chunk
-101    Not enough IDATs for image
-102    Invalid IHDR chunk
-103    Invalid bit depth in IHDR
-104    Invalid color type in IHDR
-105    Invalid color type/bit depth combo
-106    Invalid interlace method in IHDR
-107    Invalid compression method in IHDR
-108    Invalid filter method in IHDR
-109    Invalid image size in IHDR
-110    Bad PNG signature
-111    Bad CRC value
-112    Extra data at end of file
-113    Unexpected End Of File
-114    Memory error
-115    Decompression error
-116    Compression error
-117    Out of disk space

Example

int loadAPngFile(HWND hWnd, char *fname, imgdes *image)
{
   PngData pdat;
   int rcode;

   // Get info on the file we're to load
   rcode = pnginfo(fname, &pdat);
   if(rcode == NO_ERROR) { // Fill structure
      // Allocate space for an image
      rcode = allocimage(image, (int)pdat.width, (int)pdat.length, pdat.vbitcount);
      if(rcode == NO_ERROR) {
         // Load image
         rcode = loadpng(fname, image);
         if(rcode == BAD_PNG) {
            char szBuff[128];
            // Get extended error info
            int extRcode = pnggeterror();
            wsprintf(szBuff, "Error in loading %s: extended error code %d", (LPSTR)fname, extRcode);
            MessageBox(hWnd, szBuff, 0, MB_OK);
            }
         freeimage(image); // Free image on error
         }
      }
   return(rcode);
}

This function reports extended error information when a PNG file cannot be loaded.




pnginfo


Summary

int pnginfo(filename, pinfo);
char far *filename;      Filename to read
typedef struct {
   unsigned width;       PNG image width, length
   unsigned length;
   int bitDepth;         Bits per pixel, 1, 2, 4, 8, or 16
   int vbitcount;        Victor bits per pixel (used to allocate an image buffer with allocimage)
   int colorType;        Color types: 0=GS, 2=RGB, 3=PalCol, 4=GS+alpha, 6=RGB+alpha
   int interlaced;       0 = non-interlaced, 1 = interlaced
   int imageId;          Identifier for colorType/bitDepth
   int channels;         Number of channels of data per pixel
   int pixelDepth;       Number of bits per pixel
   unsigned rowBytes;    Bytes in one image row
   PNGTRANSINFO transData;Transparency data
   PNGTRANSINFO backData;Background color data
   DWORD igamma;         Gamma as float = igamma / 100000   
   DWORD physXres;       X,Y axis pixels per unit
   DWORD physYres;
   DWORD physUnits;
   PNGSIGBITS sigBit;    Significant bits in file
   DWORD offsXoffset;    X,Y axis offset
   DWORD offsYoffset;
   UCHAR offsUnits;
  } PngData far *pinfo;  Pointer to data structure to be filled in

Description
The pnginfo function reads the header of a PNG file and places the image information in the pinfo structure. The structure is defined in the header file VICDEFS.H. The purpose of the pnginfo function is to determine if a PNG file is readable and permit allocating enough memory to load the file.

If a PNG file contains a transparent color(s), pnginfo will return it in the element transData. If a transparent color is not present, the isPresent element of transData is set to FALSE. The transData element is of type PNGTRANSINFO and is defined in VICDEFS.H as

     typedef struct {
       BOOL isPresent;    TRUE if transparency data is present
       UCHAR data[6];     Up to 6 bytes of transparency data
       int byteCount;     Bytes of transparency data
       } PNGTRANSINFO;
         
PNG Transparent Color Interpretation
ColorTypeTransData.byteCountInterpretation of TransData.data[]
0, grayscale2grayscale value as a short integer
2,RGB6RGB integer values
3, palette color1palette index

Return value    Explanation
NO_ERROR    Function successful
BAD_OPN    Filename not found
BAD_PNG    File is not a valid PNG file

See also

loadpng

Example

void pngsize(HWND hWnd, char *fname)
{
   PngData pdat;             /* Reserve space for structure */
   int rcode;
   char szBuff[80];

   rcode = pnginfo(fname, &pdat);
   if(rcode == BAD_OPN) {
      wsprintf(szBuff, "Could not find %s", (LPSTR)fname);
      MessageBox(hWnd, szBuff, 0, MB_OK);
      }
   else if(rcode == BAD_PNG) {
      wsprintf(szBuff, "%s is not a PNG file", (LPSTR)fname);
      MessageBox(hWnd, szBuff, 0, MB_OK);
      }
   else {
      wsprintf(szBuff, 
         "%s image dimensions: Width=%d, Length=%d",
         (LPSTR)fname, pdat.width, pdat.length);
      MessageBox(hWnd, szBuff, 0, MB_OK);
      }
}

This example reads a PNG file and prints the image size.




pnginfofrombuffer

            1    8   24 


Summary

int pnginfofrombuffer(buff, pinfo);
unsigned char huge *buff;     Buffer address
typedef struct {
   unsigned width;       PNG image width, length
   unsigned length;
   int bitDepth;         Bits per pixel, 1, 2, 4, 8, or 16
   int vbitcount;        Victor bits per pixel (used to allocate an image buffer with allocimage)
   int colorType;        Color types: 0=GS, 2=RGB, 3=PalCol, 4=GS+alpha, 6=RGB+alpha
   int interlaced;       0 = non-interlaced, 1 = interlaced
   int imageId;          Identifier for colorType/bitDepth
   int channels;         Number of channels of data per pixel
   int pixelDepth;       Number of bits per pixel
   unsigned rowBytes;    Bytes in one image row
   PNGTRANSINFO transData;Transparency data
   PNGTRANSINFO backData;Background color data
   DWORD igamma;         Gamma as float = igamma / 100000   
   DWORD physXres;       X,Y axis pixels per unit
   DWORD physYres;
   DWORD physUnits;
   PNGSIGBITS sigBit;    Significant bits in file
   DWORD offsXoffset;    X,Y axis offset
   DWORD offsYoffset;
   UCHAR offsUnits;
  } PngData far *pinfo;  Pointer to data structure to be filled in

Description
The pnginfofrombuffer function reads the header information from memory holding PNG file data and places the image information in the pinfo structure. The structure is defined in the header file VICDEFS.H.

Refer to the pnginfo function for additional information.

Return value  Explanation
NO_ERROR   Function successful
BAD_OPN   Memory handle not available
BAD_PNG   File is not a valid PNG file
BAD_PTR   Buff does not point to readable memory




resizeex

            1    8   24 


Summary

int resizeex(srcimg, resimg, mode);
imgdes far *srcimg;     Source image 
imgdes far *resimg;     Result image 
int mode;               Resize mode (0=pixel replication, 1=interpolation)

Description
The resizeex function resizes an image area in a source buffer horizontally and vertically to fit into an image area in a destination buffer. The source and result image areas are defined by the corresponding image descriptors. This function is useful for zoom applications, where an image is enlarged or reduced for display.

The image area can be reduced or increased to any size. Most image areas are resized into new buffers, so resizeex copies the source image palette data to the result image.

Defined constants for resize mode determine the algorithm to use for generating the new pixels:

RESIZEFAST - pixel replication for the fastest resize
RESIZEBILINEAR - bilinear interpolation for the best quality image

Resizeex is a more flexible version of the resize function, since it allows resizing by interpolation in addition to pixel replication. Resizing by interpolation generally produces better quality images without blockiness.

The RESIZEBILINEAR resize mode is not available for 1-bit and 8-bit palette color images, so resizeex will use the RESIZEFAST resize mode for these image types.

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error (see Appendix A) or destination image area width or height is zero
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Images are not both 1-, 8-, or 24-bit
BAD_DIB    Source or result is a compressed DIB
(bad mode value results in pixel replication)

Example

void ResizeImageByInterp(HWND hWnd, imgdes *image)
{
   imgdes timage;
   int dx, dy, rcode, pct = 50; // 50% reduction
   int mode = RESIZEBILINEAR; // Bilinear interpolation

   // Allocate space for the new DIB
   dx = (int)(((long)(image->endx - image->stx + 1)) * pct / 100);
   dy = (int)(((long)(image->endy - image->sty + 1)) * pct / 100);
   if((rcode = allocimage(&timage, dx, dy,
      image->bmh->biBitCount)) == NO_ERROR) {
      // Resize Image into timage
      if((rcode = resizeex(image, &timage, mode)) == NO_ERROR) {
         // Success, free source image
         freeimage(image);
         // Assign timage to image
         copyimgdes(&timage, image);
         }
      else // Error in resizing image, release timage memory
         freeimage(&timage);
      }
   if(rcode != NO_ERROR)
      MessageBox(hWnd, "Error at resizeex()", 0, MB_OK);
}

This example resizes an image area using interpolation and replaces the original image with the new image.




savebmptobuffer

            1    8   24 


Summary

int savebmptobuffer(buff, image, compression); 
unsigned char huge *far *buff;   Resulting buffer address
imgdes far *image;               Image 
int comp;                        Compression type (0=none 1=RLE8)

Description
The savebmptobuffer function saves an image area as 1-, 8-, or 24-bit BMP file data in a memory buffer. The memory buffer is allocated by the savebmptobuffer function and the resulting buffer address is returned in buff. This memory must be released when no longer needed.

To free the memory:

   GlobalFreePtr(buff);     // Windowsx.h macro

To determine the size of the buffer:
   BUFFER_SIZE(buff);     // Vicdefs.h macro

The image area and palette are defined by the image descriptor. Palette information must be located in a table pointed to by the image descriptor member palette. The number of colors in the table must be contained in the image descriptor member colors.

8-Bit per pixel images may be saved as uncompressed or compressed BMP files. The RLE8 compression scheme efficiency can be poor for photographic-type images and may actually result in larger files.

Return value   Explanation
NO_ERROR   Function successful
BAD_RANGE   Range error, see Appendix A
BAD_IBUF   Invalid image buffer address
BAD_MEM   Insufficient memory
BAD_BPP   Image is not 1-, 8-, or 24-bit
BAD_DIB   Image is a compressed DIB
BAD_CRT   Cannot write BMP data to buffer
BAD_CMP   Unsupported compression scheme for the image bits per pixel




savegifex

            1    8 


Summary

int savegifex(filename, image, saveMode, transColor);
char far *filename;              Filename to save
imgdes far *image;               Image 
int saveMode;                    Save mode
int transColor;                  Transparent color (0-255)

Description
The savegifex function saves an image area as 1-, 4- or 8-bit GIF file with interlace, transparent color, and compression options. The image area and palette are defined by the image descriptor.

The parameter saveMode determines which options are used just as in the savegifex function. SaveMode is assembled from defined constants that have the values listed below. Any combination of flags can be used.
GIF File Types Written by savegifex
FlagMeaningNotes
GIFLZWCOMP (0) Write baseline GIF LZW-compressed file1
GIFINTERLACE (1) Use interlaced row storage
GIFTRANSPARENT (2)Use transColor as transparent color 2
GIFWRITE4BIT (4) Save image with 4 bits per pixel 3
GIFNOCOMP (8) Write GIF without LZW compression 4
    Notes
  1. A saveMode of 0 is equivalent to using savegif.
  2. Set the parameter transColor to the transparent color when calling savegifex. TransColor must be in the range 0 - 255.
  3. To save an image as a 4-bit GIF file, the image must be an 8-bit image with pixel values ranging from 0 to 15 and have 16 or fewer palette colors. A 256-color image can be converted to a suitable 16-color image using reduceimagecolors.
  4. In general, LZW-compressed files are approximately 50% smaller than uncompressed GIF files.

Flag values should be ORed together to achieve the desired mode value. For example, to save an interlaced uncompressed image use:

   saveMode = GIFINTERLACE | GIFNOCOMP;   // value = 9

An attempt to save an image as an LZW-compressed file will return the error code LZW_DISABLED unless LZW functionality has been enabled with unlockLZW. The use of LZW compression requires an LZW license from Unisys Corporation. For information concerning licensing the LZW compression and/or decompression capability, please contact: Unisys Corporation, Welch Licensing Department - C1SW19, Township Line & Union Meeting Roads, P O Box 500, Blue Bell PA 19424, www.unisys.com.

Return value  Explanation
NO_ERROR   Function successful
BAD_RANGE   Range error, see Appendix A, or greater than 16 palette colors (4-bit GIF file only)
BAD_FAC    TransColor not 0 to 255 (transparent GIF only)
BAD_IBUF   Invalid image buffer address
BAD_MEM   Insufficient memory
BAD_BPP   Image is not 1- or 8-bit
BAD_DIB   Image is a compressed DIB
BAD_CRT   Cannot create file or directory is invalid
BAD_DSK   Disk full, file not written
LZW_DISABLED   LZW functionality not available, see unlockLZW

See also savegiftobufferex, loadgif

Example

int save_GifEx(HWND hWnd, char *fname, imgdes *image)
{
#define VINTERLACE   1 // Defined in VICDEFS.H
#define VTRANSPARENT 2
#define VWRITE4BIT   4
int rcode;

// Write a transparent, interlaced GIF
int saveMode = VINTERLACE | VTRANSPARENT;
int transColor = 10; // Transparent color is 10

// Write a 4-bit GIF if palette colors are 16 or less
if(image->colors <= 16)
   saveMode |= VWRITE4BIT;

rcode = savegifex(fname, imgptr, saveMode, trasnColor);
if(rcode != NO_ERROR) {
   char szBuff[80];
   wsprintf(szBuff, "Could not save %s", (LPSTR)fname);
   MessageBox(hWnd, szBuff, 0, MB_OK);
   }
return(rcode);
}

This example saves an image area as a transparent, interlaced, 4- or 8-bit GIF file.




savegiftobufferex

            1    8 


Summary

int savegiftobufferex(buff, image, saveMode, transColor);
unsigned char huge *far *buff;   Resulting buffer address
imgdes far *image;               Image 
int saveMode;                    Save mode
int transColor;                  Transparent color (0-255)

Description
The savegiftobufferex function saves an image area as 1-, 4- or 8-bit GIF file data in a memory buffer. The memory buffer is allocated by the savegiftobufferex function and the resulting buffer address is returned in buff. This memory must be released when no longer needed.

To free the memory:

   GlobalFreePtr(buff);     // Windowsx.h macro

To determine the size of the buffer:
   BUFFER_SIZE(buff);     // Vicdefs.h macro

The image area and palette are defined by the image descriptor.

The parameter saveMode determines which options are used just as in the savegifex function. SaveMode is assembled from defined constants that have the values listed in Table 12. Any combination of flags can be used. Flag values should be ORed together to achieve the desired mode value. For example, to save an interlaced uncompressed image use:

   saveMode = GIFINTERLACE | GIFNOCOMP;   // value = 9

An attempt to save an image as an LZW-compressed file will return the error code LZW_DISABLED unless LZW functionality has been enabled with unlockLZW. The use of LZW compression requires an LZW license from Unisys Corporation. For information concerning licensing the LZW compression and/or decompression capability, please contact: Unisys Corporation, Welch Licensing Department - C1SW19, Township Line & Union Meeting Roads, P O Box 500, Blue Bell PA 19424, www.unisys.com.

Return value  Explanation
NO_ERROR   Function successful
BAD_RANGE   Range error, see Appendix A, or greater than 16 palette colors (4-bit GIF file only)
BAD_FAC    TransColor not 0 to 255 (transparent GIF only)
BAD_IBUF   Invalid image buffer address
BAD_MEM   Insufficient memory
BAD_BPP   Image is not 1- or 8-bit
BAD_DIB   Image is a compressed DIB
BAD_CRT   Cannot write GIF data to buffer
LZW_DISABLED   LZW functionality not available, see unlockLZW

See also savegifex, loadgiffrombuffer




savejpgex

                8   24 


Summary

int savejpgex(filename, image, quality, mode); 
char * filename;         Filename to save
imgdes far *image;       Image 
int quality;             Image quality (1 - 100)
int mode;                Save mode (0=baseline, 1=progressive, 2=sequential optimized)

Description
The savejpgex function saves an 8- or 24-bit image area in the JPEG File Interchange Format (JFIF) file format to a disk file. The image area is defined by the image descriptor. The amount of data compression is determined by quality. A quality of 100 represents maximum quality and minimum compression. The mode determines the type of JPEG file to be written.

         
ModeDescriptionFile type
JPGSEQ (0)Baseline sequential (uses standard Huffman tables)SOF0 or SOF1
JPGPROG (1)Progressive (multipass)SOF2
JPGSEQOPT (2)Sequential optimized (computes best Huffman tables)SOF0 or SOF1

Progressive JPEG files (mode 1) are generally slightly smaller than baseline sequential, but are normally slower to write and load. Also, many applications do not read progressive JPEG files. Sequential optimized JPEG files (mode 2) are generally 5-10 percent smaller than baseline JPEG files. Any JPEG reader should be able to read sequential optimized JPEG files.

Refer to savejpg for additional information about saving an image using JPEG compression. Savejpgex is an enhanced version of the savejpg function (savejpg writes only baseline sequential, mode 0, files).

Invalid value for mode results in a baseline sequential JPEG file.

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error, see Appendix A
NO_ERROR    Function successful
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Image is not 8- or 24-bit
BAD_DIB    Image is a compressed DIB
BAD_CRT    Cannot create file or directory is invalid
BAD_DSK    Disk full, file not written

See also
savejpg, savejpgtobuffer, savejpgtobufferex

Example

int saveProgressiveJpeg(HWND hWnd, char *fname, imgdes *image)
{
   int j, rcode, quality = 75;
   int savemode = JPGPROG;
   char szBuff[80];

   rcode = savejpgex(fname, image, quality, savemode);
   if(rcode != NO_ERROR) {
      wsprintf(szBuff, "Could not save %s", (LPSTR)fname);
      MessageBox(hWnd, szBuff, 0, MB_OK);
      }
   return(rcode);
}

This example saves an image as a progressive JPEG file.




savejpgtobufferex

            1    8   24 


Summary

int savejpgtobufferex(buffer, image, quality,mode); 
unsigned char huge * far *buffer;  Buffer address
imgdes far *image;                 Image 
int quality;                       Image quality (1 - 100)
int mode;                          Save mode (0=baseline, 1=progressive, 2=sequential optimized)

Description
The savejpgtobufferex function saves an 8- or 24-bit image area in the JPEG File Interchange Format (JFIF) file format into a memory buffer. The image area is defined by the image descriptor. The amount of data compression is determined by quality. A quality of 100 represents maximum quality and minimum compression. The mode determines the type of JPEG file to be written.

The memory buffer is allocated by savejpgtobufferex and the address is returned in buffer. This memory must be released when no longer needed by calling:

     GlobalFreePtr(buffer); // WINDOWSX.H macro

To determine the size of the buffer:
   BUFFER_SIZE(buffer);     // Vicdefs.h macro

Refer to savejpgtobuffer and savejpgex for additional information.

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error, see Appendix A
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Image is not 8- or 24-bit
BAD_DIB    Image is a compressed DIB
BAD_CRT    Cannot create JPEG data in buffer

See also
savejpg, savejpgtobuffer, savejpgtobufferex

Example
See savejpgtobuffer




savepng

            1    8   24 


Summary

int savepng(filename, image, comp);
char far *filename;      Filename to save
imgdes far *image;       Image 
int comp;                Compression type (0-11)

Description
The savepng function saves an image area as a 1-, 8-, or 24-bit PNG file. The image area and palette are defined by the image descriptor.

Comp selects the type of filtering to use while compressing the image data.

         
Comp Description
PNGALLFILTERS (0) Use best filter for each row (best compression)
PNGNOFILTER (2) No filter is used (fastest to execute)
PNGSUBFILTER (4) Difference filter with adjacent pixel
PNGUPFILTER (6) Difference filter with pixel in previous row
PNGAVGFILTER (8) Average filter
PNGPAETHFILTER (10) Paeth filter

To save an image as an interlaced file, bitwise OR comp with the defined constant PNGINTERLACE (1). So, to save the image with maximum compression in an interlaced file use PNGALLFILTERS | PNGINTERLACE for comp.

The Victor savepng function is based on the source code for the ZLIB compression library by Jean-loup Gailly and Mark Adler. PNG stands for Portable Network Graphics. This format is intended to be a patent-free replacement for GIF and uses the LZ77 compression rather than LZW.

Return value    Explanation
NO_ERROR    Function successful
BAD_RANGE    Range error, see Appendix A
BAD_IBUF    Invalid image buffer address
BAD_MEM    Insufficient memory
BAD_BPP    Image is not 1-, 8-, or 24-bit
BAD_DIB    Image is a compressed DIB
BAD_CRT    Cannot create file or directory is invalid
BAD_DSK    Disk full, file not written
BAD_PNG_CMP    Compressor error

Example

int saveAPng(HWND hWnd, char *fname, imgdes *image)
{
   int rcode;
   int comp = PNGALLFILTERS | PNGINTERLACE;
   char szBuff[80];

   histoequalize(image, image);
   rcode = savepng(fname, image, comp);
   if(rcode != NO_ERROR) {
      wsprintf(szBuff, "Could not save %s", (LPSTR)fname);
      MessageBox(hWnd, szBuff, 0, MB_OK);
      }
   return(rcode);
}

This example brightens an image and saves it with maximum compression as an interlaced PNG file.




savepngtobuffer

            1    8   24 


Summary

int savepngtobuffer(buff, image, comp);
unsigned char huge *far *buff;  Resulting buffer address
imgdes far *image;              Image 
int comp;                       Compression type (0-11)

Description
The savepngtobuffer function saves an image area as 1-, 8-, or 24-bit PNG file data in a memory buffer. The memory buffer is allocated by the savepngtobuffer function and the resulting buffer address is returned in buff. This memory must be released when no longer needed.

To free the memory:

   GlobalFreePtr(buff);     // Windowsx.h macro

To determine the size of the buffer:
   BUFFER_SIZE(buff);     // Vicdefs.h macro

The image area and palette are defined by the image descriptor.

The comp argument in a PNG file lets you select the type of filtering to use while compressing the image data.
         
Comp Description
PNGALLFILTERS (0) Use best filter for each row (best compression)
PNGNOFILTER (2) No filter is used (fastest to execute)
PNGSUBFILTER (4) Difference filter with adjacent pixel
PNGUPFILTER (6) Difference filter with pixel in previous row
PNGAVGFILTER (8) Average filter
PNGPAETHFILTER (10) Paeth filter

To save an image as an interlaced file, bitwise OR comp with the defined constant PNGINTERLACE (1). For example to save the image with maximum compression in an interlaced file use PNGALLFILTERS | PNGINTERLACE for comp.

The Victor savepng function is based on the source code for the ZLIB compression library by Jean-loup Gailly and Mark Adler. PNG stands for Portable Network Graphics. This format is intended to be a patent-free replacement for GIF. It uses the LZ77 compression rather than LZW. The PNG file format specification is available at .

Return value   Explanation
NO_ERROR   Function successful
BAD_RANGE   Range error, see Appendix A
BAD_IBUF   Invalid image buffer address
BAD_MEM   Insufficient memory
BAD_BPP   Image is not 1-, 8-, or 24-bit
BAD_DIB   Image is a compressed DIB
BAD_CRT   Cannot write PNG data to buffer
BAD_PNG_CMP   Compressor error




savetiftobuffer

            1    8   16   24 


Summary

int savetiftobuffer(buff, image, comp); 
unsigned char huge *far *buff; Resulting buffer address
imgdes far *image;             Image 
int comp;                      Compression type (0-4, 0x10-0x14)

Description
The savetiftobuffer function saves an image area as TIFF file data in a memory buffer. The memory buffer is allocated by the savetiftobuffer function and the resulting buffer address is returned in buff. This memory must be released when no longer needed.

To free the memory:

   GlobalFreePtr(buff);     // Windowsx.h macro

To determine the size of the buffer:
   BUFFER_SIZE(buff);     // Vicdefs.h macro

The image area and palette data are defined by the image descriptor. For additional information about saving in the TIFF file format refer to savetif.

Return value Explanation
NO_ERROR Function successful
BAD_RANGE Range error, see Appendix A
BAD_IBUF Invalid image buffer address
BAD_MEM Insufficient memory
BAD_BPP Image is not 1-, 8-, 16-, or 24-bit
BAD_DIB Image is a compressed DIB
BAD_CRT Cannot create file or directory is invalid
BAD_DSK Disk full, file not written
BAD_CMP Unsupported compression scheme for the image bits per pixel
LZW_DISABLED LZW functionality not available, see unlockLZW

See also savetif, loadtiffrombuffer




tiffgeterror


Summary

int tiffgeterror(void);

Description
The tiffgeterror function reports extended error information after a TIFF function returns BAD_TIFF.

Return value    Explanation
0    No extended error information
-100    Invalid data found in TIF file
-101    Error reading data from the file
-102    Unexpected end of file
-103    Trans point arrays not large enough

Example

int loadATiffFile(HWND hWnd, char *fname, imgdes *image)
{
   TiffData tdat;
   int rcode;

   // Get info on the file we're to load
   rcode = tiffinfo(fname, &tdat);
   if(rcode == NO_ERROR) { // Fill structure
      // Allocate space for an image
      rcode = allocimage(image, (int)tdat.width, (int)tdat.length, tdat.vbitcount);
      if(rcode == NO_ERROR) {
         // Load image
         rcode = loadtif(fname, image);
         if(rcode == BAD_TIFF) {
            char szBuff[128];
            // Get extended error info
            int extRcode = tiffgeterror();
            wsprintf(szBuff, "Error in loading %s: extended error code %d", (LPSTR)fname, extRcode);
            MessageBox(hWnd, szBuff, 0, MB_OK);
            }
         freeimage(image); // Free image on error
         }
      }
   return(rcode);
}

This function reports extended error information when a TIFF file cannot be loaded.




tiffinfofrombuffer


Summary

int tiffinfofrombuffer(buff, tinfo);
unsigned char huge *buff;  Buffer address
typedef struct {           Structure to contain TIFF file data
   unsigned ByteOrder;     Intel or Motorola ("II" or "MM")
   unsigned width, length; Image width and length in pixels
   unsigned BitsPSample;   Bits per sample
   unsigned Comp;          Compression scheme
   unsigned SamplesPPixel; Samples per pixel
   unsigned PhotoInt;      Photometric interpretation
   unsigned PlanarCfg;     Planar configuration
   int vbitcount;          Victor bits per pixel (used to allocate an image buffer with allocimage)
   } TiffData far *tinfo;  Pointer to structure

Description
The tiffinfofrombuffer function reads the header information from memory holding TIFF file data and places the image information in the tinfo structure. The purpose of the tiffinfofrombuffer function is to identify the type and size of the image and permit allocating enough memory to load the file.

Return value   Explanation
NO_ERROR    Function successful
BAD_OPN    Memory handle not available
BAD_TIFF    File is not a valid TIFF file
BAD_PTR    Buff does not point to readable memory

See also tiffinfo

Example See loadtiffrombuffer




tiffinfopagebyindex


Summary

int tiffinfopagebyindex(filename, tinfo, pageIndex);
const char far *filename;     Filename of multi-page TIFF file
typedef struct {              Structure to contain TIFF file data
	unsigned ByteOrder;        Intel or Motorola ("II" or "MM")
	unsigned width, length;    Image width and length in pixels
	unsigned BitsPSample;      Bits per sample
	unsigned Comp;             Compression scheme
	unsigned SamplesPPixel;    Samples per pixel
	unsigned PhotoInt;         Photometric interpretation
	unsigned PlanarCfg;        Planar configuration
	int vbitcount;             Victor bits per pixel (used to allocate an image buffer with allocimage)
} TiffData far *tinfo;        Pointer to structure
int pageIndex;                Index number of the target page number to get information about

Description
The tiffinfopagebyindex function reads the header of a page in a multi-page TIFF file and places the image information in the tinfo structure. The structure is defined in the file VICDEFS.H.

The purpose of the tiffinfopagebyindex function is to identify the type and size of a page in a multipage TIFF file to permit allocating enough memory to load the page.

Use tiffinfopagebyindex to get information about an image based on its position in the file. Use tiffinfopage to get information about an image based on its page number tag.

Except for obtaining information about a specific page (image) in a multipage TIFF file, tiffinfopagebyindex is identical to the tiffinfo function. To determine the pages present in a multipage TIFF file, use the tiffgetpageinfo function. If pageIndex is set to -1, calling tiffinfopagebyindex obtains information on the first image in a TIFF file whether or not the file contains multiple pages.

Return value   Explanation
NO_ERROR    Function successful
BAD_OPN    Filename not found
BAD_TIFF    File is not a valid TIFF file
BAD_MEM    Insufficient memory
TIFF_NOPAGE    TIFF page not found and tiffPageIndex is not -1

See also
tiffinfo, tiffinfopage, loadtifpage, tiffgetpageinfo

Example
See loadtifpagebyindex




windowtoimage

            1    8   24 


Summary

int windowtoimage(hwnd, resimg);
HWND hwnd;              Window handle
imgdes far *resimg;     Result image

Description
The windowtoimage function creates a Victor-compatible image from a window. This function provides an easy way to capture a window displayed on the screen. The result image will have the same bits per pixel as the current display mode.

If the function is successful the image descriptor resimg is filled in.

Windowtoimage allocates memory to hold the image, so freeimage must be called when this memory is no longer needed.

Return value    Explanation
NO_ERROR    Function successful
BAD_MEM    Insufficient memory
BAD_BPP    Bits per pixel not 1, 4, 8, 16, or 24

See also
clienttoimage

Example

int CaptureScreenWindow(HWND hWnd)
{
   int rcode;
   imgdes timage;
   char *fname = "window.tif";

   // Capture window as Victor image
   rcode = windowtoimage(hWnd, &timage);
   if(rcode == NO_ERROR) {
      // Save captured window
      rcode = savetif(fname, &timage, 0);
      // Release memory allocated by windowtoimage()
      freeimage(&timage);
      }
   return(rcode)
}

This example captures a window's area and saves it as a TIFF file.





Victorversionex


Summary

WORD Victorversionex(verinfo);
typedef struct {       Structure to contain version information
   WORD version;       Version number
   WORD exver;         Extended version information
   } VIC_VERSION_INFO far *verinfo

Description
The Victorversionex function places version information about the Victor Image Processing Library in the verinfo structure. The structure is defined in the file VICDEFS.H.

The library version number is placed in the version element as a two-byte WORD. The high-order byte contains the major version number and the low-order byte contains the minor version number as a two-digit decimal number.

The exver element receives extended version information. The bits in exver are defined as:
BitBit valueMeaning
00Uses C dynamic run-time library, i.e., MSVCRTxx.DLL
1Uses C static run-time library
10Not multithread-safe
1Multithread-safe
20Beta prerelease version
1Release version
30Nonevaluation (retail) version
1Evaluation version, time limited

As an example exver = 7 indicates a release version, multithread- safe Victor Library that uses the C static run-time library.

Return value The version number is returned as a two-byte WORD.

Example

void showVicVersionex(HWND hWnd, char *fname, imgdes *image)
{
   char szBuff[80];
   VIC_VERSION_INFO verinfo;

   Victorversionex(&verinfo);
   wsprintf(szBuff, "Victor Library version %d.%02d,%02d",
      HIBYTE(verfino.version), LOBYTE(verinfo.version),
         verinfo.flags); 
   MessageBox(hWnd, szBuff, 0, MB_OK);
}

This example displays the Victor Library version information in a message box.


TWdetecttwain


Summary

TWdetecttwain 							
Summary
int TWdetecttwain(hWnd);
HWND hWnd;		          Window handle
Description
The TWdetecttwain function verifies the presence of the TWAIN source manager (TWAIN.DLL or TWAIN_32.DLL). This function does not determine if a TWAIN data source is present.

The TWdetecttwain function may appear to execute slowly because the function determines the presence of the TWAIN source manager by opening it. When opened, the source manager searches for all available data sources. This may take some time depending on operating system and number of TWAIN drivers installed.

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_BUSY    TWAIN module is busy
BAD_MEM    nsufficient memory

Example

void EnableTwainScanMenuItems(HWND hWnd, HMENU hMenu) 
{
   static BOOL scanDriverReady = FALSE;
   int mstate;

   // Enable/disable scan menu items
   if(scanDriverReady == FALSE) {
      // Enable/disable scan menu items
      mstate = MF_GRAYED;
      // If Twain source manager (TWAIN.DLL or TWAIN_32.DLL) 
      // is present, enable the scan menu items
      if(TWdetecttwain(hWnd) == NO_ERROR) {
         scanDriverReady = TRUE;
         mstate = MF_ENABLED;
         }
      EnableMenuItem(hMenu, IDM_F_SELECTSOURCE, mstate);
      EnableMenuItem(hMenu, IDM_F_ACQUIRE, mstate);
      }
}

This example enables or disables the TWAIN scan menu items.


TWgetbrightness


Summary

int TWgetbrightness(hWnd, brightdata);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *brightdata;    Pointer to structure;

Description
The TWgetbrightness function gets the valid range of brightness levels that can be used to set the brightness in a call to TWsetbrightness. The data is returned in the brightdata structure, usually in a TWAIN_RANGE container. Typically brightness values range from -1000 to +1000. TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H.

TWgetbrightness may not be able to verify a parameter change made by a TWsetbrightness call. This is because the new value to set is not sent to the device until a scan image function is called.

Return value
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example
See TWsetbrightness


TWgetcontrast


Summary

int TWgetcontrast(hWnd, contrastdata);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *contrastdata;  Pointer to structure;

Description
The TWgetcontrast function gets the valid range of contrast values that can be used to set the contrast in a call to TWsetcontrast. The data is returned in the contrastdata structure, usually in a TWAIN_RANGE container. Typically contrast values range from - 1000 to +1000. TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H.

TWgetcontrast may not be able to verify a parameter change made by a TWsetcontrast call. This is because the new value to set is not sent to the device until a scan image function is called.

Return value
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example
See TWsetcontrast


TWgeterror


Summary

int TWgeterror(void);	

Description
The TWgeterror function reports extended error information. When the return code from a Victor TWAIN function is not NO_ERROR or TWAIN_SCAN_CANCEL, calling TWgeterror usually provides additional information about why the function failed.
Return value Explanation
0 TWCC_SUCCESS Operation successful
1 TWCC_BUMMER Failure due to unknown causes
2 TWCC_LOWMEMORY Not enough memory to perform operation
3 TWCC_NODS No Data Source
4 TWCC_MAXCONNECTIONS Source already in use
5 TWCC_OPERATIONERROR Source or Source Manager error already reported to user
6 TWCC_BADCAP Unknown capability requested
9 TWCC_BADPROTOCOL Unrecognized DataGroup / Data ArgType / Msg combination
10 TWCC_BADVALUE Parameter out of range
11 TWCC_SEQERROR Message received out of sequence
12 TWCC_BADDEST Unknown destination App/Src in DSM_Entry
-55 TWAIN_NOWND Could not create parent window
-54 TWAIN_NODSM TWAIN Source Manager not found

Example
See TWscanimage


TWgetmeasureunit


Summary

int TWgetmeasureunit(hWnd, unitTypes);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *unitTypes;      Pointer to structure;

Description
The TWgetmeasureunit function gets the valid range of values that can be used to set the measurement units in a call to TWsetmeasureunit. The data is returned in the unitTypes structure, usually in a TWAIN_ENUMTYPE container. TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H. The unit type constants are defined as follows:
Value Description
0 TWUN_INCHES Inches
1 TWUN_CENTIMETERS Centimeters
2 TWUN_PICAS Picas (1/6 inch)
3 TWUN_POINTS Points (1/72 inch)
4 TWUN_TWIPS Twips
5 TWUN_PIXELS Pixels

TWgetmeasureunit may not be able to verify a parameter change made by a TWsetmeasureunit call. This is because the new value to set is not sent to the device until a scan image function is called.

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example
See TWsetpixeltype


TWgetpixeltype


Summary

int TWgetpixeltype(hWnd, pixelTypes);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *pixelTypes; Pointer to structure;

Description
The TWgetpixeltype function gets the valid range of values that can be used to set the pixel type in a call to TWsetpixeltype. The data is returned in the pixelTypes structure, usually in a TWAIN_ENUMTYPE container. TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H. The pixel type constants are defined as follows:
Value Description
0 TWPT_BW Black and white
1 TWPT_GRAY Grayscale
2 TWPT_RGB RGB
3 TWPT_PALETTE Palette color
4 TWPT_CMY CMY
5 TWPT_CMYK CMYK
6 TWPT_YUV YUV
7 TWPT_YUVK YUVK
8 TWPT_CIEXYZ CIEXYZ

TWgetpixeltype may not be able to verify a parameter change made by a TWsetpixeltype call. This is because the new value to set is not sent to the device until a scan image function is called

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example
See TWsetpixeltype


TWgetsourcenames


Summary

int TWgetsourcenames(hWnd, nameList, nameCount);
HWND hWnd;                      Window handle
TW_STR32 far *nameList;         List of Twain sources
int far *nameCount;             Number of sources in nameList

Description
The TWgetsourcenames function gets a list of available Twain data sources from the source manager. If nameList is NULL, TWgetsourcenames just enters the number of available data sources into nameCount. This allows the calling program to allocate adequate space for nameList.

If nameList represents a valid array, the list of available data source names is copied into nameList and nameCount is not altered. Up to nameCount names will be copied. TW_STR32 is defined in VICDEFS.H as a 34-element char array.

See also
TWselectsourcebyname

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info
BAD_MEM    Insufficient memory

Example

int SelectDataSourceByName(HWND hWnd)
   int j, rcode;
   char far *targetDS="DeskScan II"; // HP ScanJet data source
   TW_STR32 far *nameList; // List of Twain data sources
   int nameCount; // Number of sources in nameList
    
   // Store App name to display in Source dialog box
   TWsetproductname("My App");

   nameList = NULL;
   // Get number of data sources available
   rcode = TWgetsourcenames(hWnd, nameList, &nameCount);

   // Allocate space for names of data sources
   nameList = (TW_STR32 far *)calloc(nameCount, sizeof(TW_STR32));

   // Get data source names
   rcode = TWgetsourcenames(hWnd, nameList, &nameCount);
   if(rcode == NO_ERROR) {
      // Compare data source names found to our target
      for(j=0; j<nameCount; j++) {
         if(lstrcmpi(targetDS, (char far *)&nameList[j]) == 0)
            break; // Found a match
         }
      if(j == nameCount)
         rcode = TWAIN_NODS;  // Target data source not found
      else // Select the data source for image acquisition
         rcode = TWselectsourcebyname(hWnd, (char far *)&nameList[j]);
      }
   if(nameList)
      free(nameList);
   return(rcode);
}

This example retrieves a list of TWAIN data sources and then selects the data source for the HP ScanJet scanner.


TWgetxresolution


Summary

int TWgetxresolution(hWnd, resdata);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *resdata;  Pointer to structure;

Description
The TWgetxresolution function gets the valid range of resolutions that can be used to set the resolution in a call to TWsetxresolution. The data is returned in the resdata structure, usually in a TWAIN_RANGE container. TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H.

TWgetxresolution may not be able to verify a parameter change made by a TWsetxresolution call. This is because the new value to set is not sent to the device until a scan image function is called.

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example
See TWscanimageex


TWgetyresolution


Summary

int TWgetyresolution(hWnd, resdata);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *resdata;  Pointer to structure;

Description
The TWgetyresolution function gets the valid range of resolution values that can be used to set the resolution in a subsequent call to TWsetyresolution. The data is returned in the resdata structure, usually in a TWAIN_RANGE container. TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H.

TWgetyresolution may not be able to verify a parameter change made by a TWsetyresolution call. This is because the new value to set is not sent to the device until a scan image function is called.

Return value
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example
See TWscanimageex


TWscanimage

            1    8   24 

Summary

int TWscanimage(hWnd, simage);
HWND hWnd;               Window handle
imgdes far *simage;      Image 

Description
The TWscanimage function acquires an image from a TWAIN data source and creates a Victor-compatible image described by the image descriptor simage.

This function allocates memory to hold the image and enters the correct data into all elements of the image descriptor simage. The image in memory must be released with freeimage when no longer needed.

Calling this function causes the data source to display a dialog box that the user can fill in to acquire an image. This dialog box allows specifying image characteristics such as dimensions and pixel depth. When the user selects "FINAL" the image is transferred from the data source to simage. If the user cancels the dialog box, TWAIN_SCAN_CANCEL is returned.

The data source used by TWscanimage can be selected by TWselectsource or TWselectsourcebyname. If a data source is not selected the default data source will be used. If no data source is available it will not be possible to acquire an image. See the section about Scanning Images in the Victor User's Guide for more information about acquiring images with TWAIN.

See also
TWscanimageex, TWscanmultipleimages

Return value    Explanation
NO_ERROR    Function successful
TWAIN_SCAN_CANCEL    User canceled image transfer
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call Twgeterror for more info
BAD_MEM    Insufficient memory
BAD_CMP    TWAIN image has unreadable compression scheme
BAD_BPP    Bits per pixel of TWAIN image is not 1, 4, 8, or 24

Example

int AcquireAnImage(HWND hWnd, imgdes far *desimg)
{
   int rcode;
   
   // Store App name to display in Source dialog box. 
   // String may contain up to 32 chars.
   Twsetproductname("OurApp");

   // Acquire image from selected/default source
   rcode = TWscanimage(hWnd, desimg);
   if(rcode != NO_ERROR){ // Handle any errors
      char szBuff[80];
      wsprintf(szBuff, "Error in acquiring image: %d, %d",
         rcode, TWgeterror());
      MessageBox(hWnd, szBuff, "TWAIN Error", MB_OK);
      }
   return(rcode);
}

This example acquires an image from a TWAIN source and stores it in an image buffer.


TWscanimageex

            1    8   24 

Summary

int TWscanimageex(hWnd, simage, srect, showUI);
HWND hWnd;               Window handle
imgdes far *simage;      Image 
RECT far *srect;         Area on scan bed to be scanned in 1/1000 unit of measure
BOOL showUI;             Flag to display the acquire dialog box

Description
The TWscanimageex function acquires an image from a TWAIN data source and creates a Victor-compatible image described by the image descriptor simage.

This function allocates memory to hold the image and enters the correct data into all elements of the image descriptor simage. The image in memory must be released with freeimage when no longer needed.

TWscanimageex allows specifying the scan window and if the acquire dialog box should be displayed. The scan window is the rectangular section of the scan bed that is scanned. This window is defined by the srect structure in increments of 1/1000 unit of measure, usually inches.

The variable showUI controls whether the acquire dialog box will be displayed. If showUI is TRUE the data source displays a dialog box that the user can fill in to acquire an image. Setting showUI to FALSE instructs the data source to acquire an image without displaying the dialog box. Note that some data sources may not allow bypassing the acquire dialog box.

The acquire dialog box allows specifying image characteristics such as dimensions and pixel type. When the user selects "FINAL" the image is transferred from the data source to simage. If the user cancels the dialog box, TWAIN_SCAN_CANCEL is returned.

The data source used by TWscanimageex can be selected by TWselectsource or TWselectsourcebyname. If a data source is not selected the default data source will be used. If no data source is available it will not be possible to acquire an image. See the section about Scanning Images in the Victor User's Guide for more information about acquiring images with TWAIN.

Image acquisition properties can be controlled by using TWsetbrightness, TWsetcontrast, TWsetpixeltype, TWsetmeasureunit, TWsetxresolution, and TWsetyresolution,

See also
TWscanimage, TWscanmultipleimagesex

Return value    Explanation
NO_ERROR    Function successful
TWAIN_SCAN_CANCEL    User canceled image transfer
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info
BAD_MEM    Insufficient memory
BAD_CMP    TWAIN image has unreadable compression scheme
BAD_BPP    Bits per pixel of TWAIN image not 1, 4, 8, or 24

Example

int AcquireSmallImage(HWND hWnd, imgdes *desimg)
{
   int rcode;
   // Area to scan: 1.25 inches from left, 0.0 inches from
   // top, end at 3.0 inches from left and 3.5 inches from top
   static RECT scanRc = { 1250, 0, 3000, 3500 }; // lf,tp,rt,bt
   BOOL showUI = FALSE; // Don't display acquire dialog
   TWAIN_CAP_DATA newXRes;
   TWAIN_CAP_DATA newBrt;
   TWAIN_CAP_DATA newPixType;

   // Store App name to display in Source dialog box. 
   // String may contain up to 32 chars.
   TWsetproductname("OurApp");

   newPixType.conType = TWON_ONEVALUE; // Container type
   // TWPT_BW=0, TWPT_GRAY, TWPT_RGB, TWPT_PALETTE,
   // Acquire RGB image 
   newPixType.oneValue.val = TWPT_RGB; 
   rcode = TWsetpixeltype(hWnd, &newPixType);

   newBrt.conType = TWON_ONEVALUE; // Container type
   newBrt.oneValue.val = 200;
   rcode = TWsetbrightness(hWnd, &newBrt);

   newXRes.conType = TWON_ONEVALUE; // Container type
   newXRes.oneValue.val = 150; // 150 dpi
   rcode = TWsetxresolution(hWnd, &newXRes);
  
   // Acquire image from selected/default source
   // without acquire dialog 
   rcode = TWscanimageex(hWnd, desimg, &scanRc, showUI);
   if(rcode != NO_ERROR){ // Handle any errors
      char szBuff[80];
      wsprintf(szBuff, "Error in acquiring image: %d, %d",
         rcode, TWgeterror());
      MessageBox(hWnd, szBuff, "TWAIN Error", MB_OK);
      }
   return(rcode);
}

This example sets the pixel type, brightness, and horizontal resolution, and acquires an image from a TWAIN source without displaying the acquire dialog box.


TWscanmultipleimages

            1    8   24 

Summary

int TWscanmultipleimages(hWnd, simage, saveScan);
 HWND hWnd;              Window handle
imgdes far *simage;      Image
int (WINAPI *saveScan)(imgdes far *currentimg))	Pointer to function used to save acquired images

Description
The TWscanmultipleimages function acquires one or more images from the default TWAIN source.

Calling this function causes the data source to display a dialog box that the user can fill in to acquire images. When the "FINAL" (or "FINISH") button is pressed, transfer of the images from the data source to the application begins.

Simage is the address of an empty image descriptor that is filled in by the function with the description of the last image acquired. The image in memory must be released with freeimage when no longer needed.

SaveScan is a pointer to a function you provide in your application. SaveScan is called from within TWscanmultipleimages each time an image is acquired from the source. An image descriptor describing the captured image is sent to the saveScan function. SaveScan can use this information to save, display, or print each image, as required. The saveScan function definition must be exported from your application and be of type WINAPI. (Either use the "_export" keyword in the function definition or list the function name under EXPORTS in a .DEF file.)

The saveScan function must return NO_ERROR to continue acquiring images. Any other return code causes TWscanmultipleimages to instruct the source to stop acquiring images. The return code from saveScan is passed to and returned by TWscanmultipleimages unless saveScan returns the special code TWAIN_STOP_SCAN (-67)

If you elect to have saveScan cancel image acquisition by returning a value other than NO_ERROR, verify that the data source doesn't cause the application to "hang." If this cannot be verified then within the saveScan function display a message box instructing the user to select "CANCEL" in the user interface.

The data source used by TWscanmultipleimages can be selected by TWselectsource or TWselectsourcebyname. If a data source is not selected the default data source will be used. If no data source is available it will not be possible to acquire an image. See the section about Scanning Images in the Victor User's Guide for more information about acquiring images with TWAIN.

For each image acquired TWscanmultipleimages allocates memory to hold the image. This memory must be released with freeimage when no longer needed.

See also
Twscanimage, Twscanimageex, TWscanmultipleimagesex

Return value    Explanation
NO_ERROR    Function successful
TWAIN_SCAN_CANCEL    User canceled image transfer
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call Twgeterror for more info
BAD_MEM    Insufficient memory
BAD_CMP    TWAIN image has unreadable compression scheme
BAD_BPP    Bits per pixel of TWAIN image is not 1, 4, 8, or 24

Example

static int imgCtr = 0; // Counts scanned images
int _export WINAPI saveScannedImage(imgdes far *simage)
{
   int rcode;
   char filnam[64];

   // Create a filename to save the scanned image
   wsprintf((LPSTR)filnam, (LPSTR)"test%d.tif", imgCtr);
   // Save the image
   rcode = savetif(filnam, simage, 0);
   if(++imgCtr >= 10) 
      rcode = TWAIN_STOP_SCAN;   // Quit after 10 images
   // Free image buffer after it's saved
   freeimage(simage);
   return(rcode);
}

// Acquire command selected
int AcquireMultipleImages(HWND hWnd)
{
   int rcode;
   imgdes simage;
   
   imgCtr = 0;  // Initialize image counter

   // Store App name to display in Source dialog box.
   // String may contain up to 32 chars.
   TWsetproductname("MyApp");

   // Acquire images and save to disk via saveScannedImage()
   rcode = TWscanmultipleimages(hWnd, &simage, saveScannedImage);

   if(rcode != NO_ERROR){ // Handle any errors
      char szBuff[80];
      wsprintf(szBuff, "Error in acquiring image: %d, %d",
         rcode, TWgeterror());
      MessageBox(hWnd, szBuff, "TWAIN Error", MB_OK);
      }
   return(rcode);
}

This example acquires up to 10 images from a TWAIN source and stores them as TIFF files.


TWscanmultipleimagesex

            1    8   24 

Summary

int TWscanmultipleimagesex(hWnd, simage, pRect, showUI, saveScan);
HWND hWnd;               Window handle
imgdes far *simage;      Image
RECT far *pRect;         Area on scan bed to be scanned
BOOL showUI;             Flag to display the Acquire dialog box
int (WINAPI *saveScan)(imgdes far *currentimg);  Pointer to function used to save acquired images

Description
The TWscanmultipleimagesex function acquires one or more images from the default TWAIN source. The scan bed area to be scanned is specified by pRect, the display of the device-supplied TWAIN user interface is specified by showUI, and the callback function for handling each image as it is acquired is specified by saveScan. The simage argument is the address of an empty image descriptor that the function fills in with the description of the last image acquired. Refer to the other TWscanmultipleimages for additional information.

See also
TWscanimage, TWscanimageex, TWscanmultipleimages

Return value    Explanation
NO_ERROR    Function successful
TWAIN_SCAN_CANCEL    User canceled image transfer
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info
BAD_MEM    Insufficient memory
BAD_CMP    TWAIN image has unreadable compression scheme
BAD_BPP    Bits per pixel of TWAIN image is not 1, 4, 8, or 24 Example
See TWscanmultipleimages


TWselectsource


Summary

int TWselectsource(hWnd);
HWND hWnd;		Window handle

Description
The TWselectsource function allows the user to select a new default TWAIN data source. The data source controls the imaging device.

Calling this function causes the source manager (TWAIN.DLL or TWAIN_32.DLL) to display a Select Data Source dialog box containing a list of TWAIN data sources. From this list the user can select a data source to become the default data source. This source will be used for subsequent calls to the Victor TWscan image functions. If no TWAIN data source is available the list will be empty and it will not be possible to acquire an image.

See the section about Scanning Images in the Victor User's Guide for more information about acquiring images with TWAIN.

See also
TWselectsourcebyname

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info
BAD_MEM    Insufficient memory

Example

int SelectDefaultSource(HWND hWnd)
{
   // Call the TWAIN source manager to select a data source 
   // for image acquisition
   return(TWselectsource(hWnd));
}

The example allows the user to select a new TWAIN data source.


TWselectsourcebyname


Summary

int TWselectsourcebyname(hWnd, dsname);
HWND hWnd;               Window handle
LPCSTR dsname;           TWAIN data source name

Description
The TWselectsourcebyname function allows selecting a TWAIN data source without displaying the Select Data Source dialog box.. In this way a data source can be selected without user intervention.

The data source controls the imaging device.

For a data source to be selected, dsname must match a name as it would be displayed in the Select Source dialog box, though case is not important in this comparison. The parameter dsname is a null-terminated string such as "Deskscan II 2.3".

The selected source will be used for subsequent calls to TWscanimage and TWscanimageex. If the source manager cannot find the data source associated with dsname, the default data source will be used. If no TWAIN data source is available it will not be possible to acquire an image.

See the section about Scanning Images in the Victor User's Guide for more information about acquiring images with TWAIN.

See also
TWselectsource

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODS    Could not find specified TWAIN data source
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info
BAD_MEM    Insufficient memory

Example

int SelectSourceByName(HWND hWnd)
{
   LPCSTR dsname = "Logitech ScanMan";

   // Select the ScanMan data source for image acquisition
   return(TWselectsourcebyname(hWnd, dsname));
}

The example selects a TWAIN data source for use with the Logitech ScanMan scanner.


TWsetbrightness


Summary

int TWsetbrightness(hWnd, brightdata);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *brightdata;  Pointer to structure;

Description
The TWsetbrightness function sets the brightness level to be used for future image acquisition. To set the brightness place the new brightness in oneVal.val and set conType to TWON_ONEVALUE. To determine the valid brightness range call Twgetbrightness.

TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H.

The new brightness value is not put into effect until an image is acquired with a scan image function call and may not be verifiable by calling TWgetbrightness.

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example

int setTWbright(HWND hWnd, int newbright) // newbright is 0 - 255
{
   int slope, rcode;
   TWAIN_CAP_DATA curBrt, newBrt;

   rcode = TWgetbrightness(hWnd, &curBrt);
   // If brightness is returned in a range container
   if(curBrt.conType == TWON_RANGE) {
      slope = (curBrt.range.max - curBrt.range.min) / 255;  
      newBrt.oneValue.val = slope * newbright + curBrt.range.min;
      newBrt.conType = TWON_ONEVALUE; // Container type
      rcode = TWsetbrightness(hWnd, &newBrt);
      }
   return(rcode);
}

This example sets the brightness of a TWAIN device given a brightness value between 0 and 255.


TWsetcontrast


Summary

int TWsetcontrast(hWnd, contrastdata);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *contrastdata;   Pointer to structure;

Description
The TWsetcontrast function sets the contrast adjustment to be used for future image acquisition. To set the contrast place the new value in oneVal.val and set conType to TWON_ONEVALUE. To determine the valid contrast range call TWgetcontrast. TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H.

The new contrast value is not put into effect until an image is retrieved with a scan image function call and may not be verifiable by calling TWgetcontrast.

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example
See TWsetbrightness


TWsetmeasureunit


Summary

int TWsetmeasureunit((hWnd, unitTypes);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *unitTypes;     Pointer to structure;

Description
The TWsetmeasureunit function sets the measurement unit to be used for future image acquisition. To set the measurement unit place the proper defined constant in oneVal.val and set conType to TWON_ONEVALUE. To determine the valid measurement units call TWgetmeasureunit. TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H.

The new measurement unit is not put into effect until an image is acquired with a scan image function call and may not be verifiable by calling TWgetmeasureunit.

The unit type constants are defined as follows:
Value Description
0 TWUN_INCHES Inches
1 TWUN_CENTIMETERS Centimeters
2 TWUN_PICAS Picas (1/6 inch)
3 TWUN_POINTS Points (1/72 inch)
4 TWUN_TWIPS Twips
5 TWUN_PIXELS Pixels

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example
See TWsetpixeltype


TWsetpixeltype


Summary

int TWsetpixeltype(hWnd, pixelTypes);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *pixelTypes;    Pointer to structure;

Description
The TWsetpixeltype function sets the pixel type to be used for future image acquisition. To set the pixel type place the proper defined constant in oneVal.val and set conType to TWON_ONEVALUE. To determine the valid pixel types call TWwgetpixeltype. TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H.

The new pixel type is not put into effect until an image is retrieved with a scan image function call and may not be verifiable by calling TWgetpixeltype.
Value Description
0 TWPT_BW Black and white
1 TWPT_GRAY Grayscale
2 TWPT_RGB RGB
3 TWPT_PALETTE Palette color
4 TWPT_CMY CMY
5 TWPT_CMYK CMYK
6 TWPT_YUV YUV
7 TWPT_YUVK YUVK
8 TWPT_CIEXYZ CIEXYZ

The Victor TWscan image functions can accept black and white, grayscale, RGB, and palette color images.

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example

int setTWpixeltype(HWND hWnd)
{
   int rcode, j, k;
   TWAIN_CAP_DATA curPT, newPT;
   // Pixel types, listed in preferred order
   int preferred_types[3] = {TWPT_RGB, TWPT_GRAY, TWPT_BW};

   rcode = TWgetpixeltype(hWnd, &curPT);
   // If pixel type is returned in a range container
   if(curPT.conType == TWON_ENUMERATION) {
      newBrt.oneValue.val = curPT.enumType.array[0];  
      for(k = 0; k < 3; k++) {
         for(j = 0; j < curPT.enumType.nelems; j++) {
            if(preferred_types[k] == curPT.enumType.array[j]) {
               newPT.oneValue.val = preferred_types[k];  
               goto setPT;
               }
            }
         }
setPT:
      newPT.conType = TWON_ONEVALUE; // Container type
      rcode = TWsetpixeltype(hWnd, &newPT);
      }
   return(rcode);
}

The example sets the pixel type of a TWAIN device to one of the preferred types given.


TWsetproductname


Summary

int TWsetproductname(appname);
LPCSTR appname;                 Application name

Description
The TWsetproductname function tells the TWAIN data source the name of the calling application. This name may be displayed by the data source during image acquisition. The variable appname may contain up to 32 characters.

Return value
There is no return code.


TWsetxresolution


Summary

int TWsetxresolution(hWnd, resdata);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *resdata;    Pointer to structure;

Description
The TWsetxresolution function sets the horizontal resolution to be used for future image acquisition. To set the resolution place the new value in oneVal.val and set conType to TWON_ONEVALUE. To determine the valid horizontal resolution range call TWgetxresolution. TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H.

The new resolution is not put into effect until an image is retrieved with a scan image function call and may not be verifiable by calling TWgetxresolution.

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example
See TWscanimageex


TWsetyresolution


Summary

int TWsetyresolution(hWnd, resdata);
HWND hWnd;                      Window handle
typedef struct {
   short conType;               Container type, TWON_ONEVALUE, TWON_ENUMERATION, or TWON_RANGE,
   TWAIN_ONEVALUE oneVal;       Data for onevalue-type container 
   TWAIN_ENUMTYPE enum;         Data for enum-type container
   TWAIN_RANGE range;           Data for range-type container
   } TWAIN_CAP_DATA far *resdata;     Pointer to structure;

Description
The TWsetyresolution function sets the vertical resolution to be used for future image acquisition. To set the resolution place the new value in oneVal.val and set conType to TWON_ONEVALUE. To determine the valid vertical resolution range call TWgetyresolution. TWAIN_ONEVALUE, TWAIN_ENUMTYPE, and TWAIN_RANGE container structures are defined in VICDEFS.H.

The new resolution is not put into effect until an image is retrieved with a scan image function call and may not be verifiable by calling TWgetyresolution.

Return value    Explanation
NO_ERROR    Function successful
TWAIN_NODSM    Could not open TWAIN Source Manager
TWAIN_NODS    Could not open TWAIN Data Source
TWAIN_BUSY    TWAIN module is busy
TWAIN_ERR    Function failed, call TWgeterror for more info

Example
See TWscanimageex


TWvicversion


Summary

WORD TWvicversion(void)

Description
The TWvicversion function returns the version of the Victor Library TWAIN support module.

Return value
The version number is returned as a two-byte WORD. The high-order byte contains the major version number. The low-order byte contains the minor version number as a two-digit decimal number.

Example

void showVicTWVersion(HWND hWnd, char *fname, imgdes *image)
{
   WORD version;
   char szBuff[80];

   version = TWvicversion();
   wsprintf(szBuff, "Victor Library TWAIN Support Module\n"
      "Version %d.%02d", HIBYTE(version), LOBYTE(version));
   MessageBox(hWnd, szBuff, 0, MB_OK);
}

This example displays the Victor Library TWAIN support module version number in a message box.