ddbtoimage

Function Prototypes

Visual Basic	Declare Function ddbtoimage Lib "VIC32.DLL" (ByVal hbitmap As Long, ByVal hpal As Long, resimg As imgdes) As Long
C/C++	int ddbtoimage(HBITMAP hbitmap, HPALETTE hPal, imgdes *resimg);
Java	int vic.vic32jni.ddbtoimage(int hbitmap, int hPal, imgdes resimg);

Function Arguments

hbitmap	Device dependent bitmap handle
hPal	Palette handle or NULL
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

NO_ERROR	Function successful
BAD_MEM	Insufficient memory
BAD_HANDLE	Invalid bitmap handle

See also
dibtoimage

Example C/C++

defaultpalette

Function Prototypes

Visual Basic	Declare Function defaultpalette Lib "VIC32.DLL" (resimg As imgdes) As Long
C/C++	int defaultpalette(imgdes *resimg);
Java	int vic.vic32jni.defaultpalette(imgdes resimg);

Function Arguments

resimg

Image which is to receive the new palette

Description

The defaultpalette function creates a 16-color palette consisting of the Windows default (or static) colors. This palette is stored in the palette location defined in the image descriptor element palette. The red, green, and blue contributions for each color are shown in Table 6. The function enters 16 into the image descriptor element colors. Defaultpalette is for use with 8-bit images. Defaultpalette creates an all-purpose palette for displaying color images. It can be used with matchcolorimage to force an 8-or 24-bit image to use a standard palette. When limited to using 16 colors use defaultpalette with matchcolorimage to display a 24-bit RGB image as an 8-bit palette color image and to display multiple 8-bit images using the same palette.

Table 6. The 16-color Default Palette
Color number	Red	Green	Blue
0	0	0	0
1	128	0	0
2	0	0	128
3	128	0	128
4	0	128	0
5	128	128	0
6	0	128	128
7	192	192	192
8	128	128	128
9	255	0	0
10	0	0	255
11	255	0	255
12	0	255	0
13	255	255	0
14	0	255	255
15	255	255	255

Return value

Returns number of colors placed in the palette, 0 - 16.

See also

rainbowpalette

Example C/C++

dibsecttoimage

Function Prototypes

Visual Basic	Declare Function dibsecttoimage Lib "VIC32.DLL" (ByVal hBitmap As Long, resimg As imgdes) As Long
C/C++	int dibsecttoimage(HBITMAP hBitmap, imgdes *resimg);
Java	int vic.vic32jni.dibsecttoimage(int hBitmap, imgdes resimg);

Function Arguments

hBitmap	DIB section handle
resimg	Result 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

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 C/C++

dibtobitmap

Function Prototypes

Visual Basic	Declare Function dibtobitmap Lib "VIC32.DLL" (ByVal hdc As Long, ByVal dib As Long, hBitmap As Long) As Long
C/C++	int dibtobitmap(HDC hdc, UCHAR *dib, HBITMAP *hBitmap);
Java	int vic.vic32jni.dibtobitmap(int hdc, int dib, refvar hBitmap);

Function Arguments

hdc	Device context handle
dib	Address of packed DIB
hBitmap	Bitmap handle to be filled in

Description

The dibtobitmap function creates a device dependent bitmap based on an existing packed device independent bitmap (DIB). In the Victor Library for 32-bit Windows this function is generally unneeded because the allocimage function enters a handle to a bitmap in the image descriptor element hBitmap. If dibtobitmap must be used, then the original DIB must be allocated with the allocdib function instead of allocimage.

Although Windows allows the palette data of a DIB to be indexes into the currently realized logical palette, dibtobitmap assumes explicit RGB values, not palette indexes.

If the function successfully creates the device dependent bitmap, the bitmap handle is placed in the hBitmap variable. This handle must be released with the Windows DeleteObject function when no longer needed.

Return value

NO_ERROR	Function successful
BAD_MEM	Insufficient global memory

See also

Converting a Victor Image to a Device Dependent Bitmap, in the Victor User's Guide.

Example C/C++

dibtoimage

Function Arguments

dib	Address of source packed dib
resimg	Result image

Description

The dibtoimage function creates a Victor-compatible image from a source packed device independent bitmap (DIB). This function is useful when a DIB is imported from the clipboard or other 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, dibtoimage assumes explicit RGB values.

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

Note: this function allocates global memory to hold the image, this memory must be released with freeimage when no longer needed.

Return value

NO_ERROR	Function successful
BAD_BPP	Bits per pixel of DIB not 1, 4, 8, 16, 24, or 32
BAD_IBUF	Invalid image buffer address
BAD_MEM	Insufficient global memory
BAD_LOCK	Global memory could not be locked
BAD_CMP	Unreadable compression scheme

See also

setupimgdes

Example C/C++ | Example VB

dilate

Function Prototypes

Visual Basic	Declare Function dilate Lib "VIC32.DLL" (ByVal amount As Long, srcimg As imgdes, resimg As imgdes) As Long
C/C++	int dilate(int amount, imgdes *srcimg, imgdes *resimg);
Java	int vic.vic32jni.dilate(int amount, imgdes srcimg, imgdes resimg);

Function Arguments

amount	Amount of dilation (0 - 255)
srcimg	Source image
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.

If 3 x 3 local area average brightness < amount
    then Result = darkest pixel in 3 x 3 area

Return value

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 C/C++ | Example VB

divide

Function Prototypes

Visual Basic	Declare Function divide Lib "VIC32.DLL" (ByVal divisor As Long, srcimg As imgdes, resimg As imgdes) As Long
C/C++	int divide(int divisor, imgdes *srcimg, imgdes *resimg);
Java	int vic.vic32jni.divide(int divisor, imgdes srcimg, imgdes resimg);

Function Arguments

divisor	Divisor (1 - 32767)
srcimg	Source image
resimg	Result image

Description

The divide function decreases the brightness level of each pixel in the source image area by dividing the level value by a factor and placing the quotient in the result image area.

Result = Source / divisor

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

Return value

NO_ERROR	Function successful
BAD_RANGE	Range error, see Appendix A
BAD_IBUF	Invalid image buffer address
BAD_MEM	Insufficient local memory
BAD_BPP	Images are not both 8- or 24-bit
BAD_DIB	Source or result is a compressed DIB
BAD_FAC	Divisor is outside the range 1 to 32767

Example C/C++ | Example VB

drawhisto

Function Prototypes

Visual Basic	Declare Function drawhisto Lib "VIC32.DLL" (ByVal hdc As Long, rect As RECT, ByVal bppixel As Long, redtab As Long, grntab As Long, blutab As Long) As Long
C/C++	int drawhisto(HDC hdc, RECT *rect, int bppixel, long *redtab, long *grntab, long *blutab);
Java	int vic.vic32jni.drawhisto(int hdc, RECT rect, int bppixel, int[] redtab, int[] grntab, int[] blutab);

Function Arguments

hdc	Device context handle
rect	Size and location of histogram in device pixels
bppixel	Bits per pixel (8 or 24)
redtab	Red histogram data to display
grntab	Green histogram data to display)
blutab	Blue histogram data to display

Description

The drawhisto function creates a graph of the histogram data on a device context. The vertical axis is frequency and the horizontal axis is brightness level. The histogram data are taken from arrays of 256 long integers.

The rect structure defines the size and location of the histogram transferred to the device context.

If bppixel is 8 the redtab data is plotted as a single graph. If bppixel is 24 the redtab, grntab, and blutab data is plotted as three stacked graphs.

Return value

NO_ERROR	Function successful
BAD_RANGE	Range error (see Appendix A) or bits per pixel and number of histogram tables are incompatible
BAD_IBUF	Invalid image buffer address
BAD_MEM	Insufficient local memory
BAD_BPP	Image is not 8- or 24-bit
BAD_DIB	Source or result is a compressed DIB

Example C/C++ 1

Example C/C++ 2

erode

Function Prototypes

Visual Basic	Declare Function erode Lib "VIC32.DLL" (ByVal amount As Long, srcimg As imgdes, resimg As imgdes) As Long
C/C++	int erode(int amount, imgdes *srcimg, imgdes *resimg);
Java	int vic.vic32jni.erode(int amount, imgdes srcimg, imgdes resimg);

Function Arguments

amount	Amount of erosion (0 - 255)
srcimg	Source image
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.

If 3 x 3 local area average brightness > (255 - amount)
    then Result = brightest pixel in 3 x 3 area

Return value

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 C/C++ | Example VB

exchangelevel

Function Prototypes

Visual Basic	exchangelevel Lib "VIC32.DLL" (ByVal min As Long, ByVal max As Long, ByVal newval As Long, srcimg As imgdes, resimg As imgdes) As Long
C/C++	int exchangelevel(int min, int max, int newval, imgdes *srcimg, imgdes *resimg);
Java	int vic.vic32jni.exchangelevel(int min, int max, int newval, imgdes srcimg, imgdes resimg);

Function Arguments

min	Low end of pixel values to change (0-255)
max	High end of pixel values to change (0-255)
newval	Replacement value (0-255)
srcimg	Source image
resimg	Result image

Description

The exchangelevel function selectively changes a range of brightness levels within an image area to a new value.

if Source >= min and Source <= max
Result = newval
else
Result = Source

For an RGB image the source red, green, and blue components all must be between min and max for the result pixel to be set to newval. The source and result image areas are defined by the corresponding image descriptors.

Return value

NO_ERROR	Function successful
BAD_RANGE	Range error, see Appendix A
BAD_IBUF	Invalid image buffer address
BAD_MEM	Insufficient local memory
BAD_BPP	Images are not both 8- or 24-bit
BAD_DIB	Source or result is a compressed DIB
BAD_FAC	Min, max, or newval is outside the range 0 - 255

Example C/C++ | Example VB

expandcontrast

Function Prototypes

Visual Basic	Declare Function expandcontrast Lib "VIC32.DLL" (ByVal min As Long, ByVal max As Long, srcimg As imgdes, resimg As imgdes) As Long
C/C++	int expandcontrast(int min, int max, imgdes *srcimg, imgdes *resimg);
Java	int vic.vic32jni.expandcontrast(int min, int max, imgdes srcimg, imgdes resimg);

Function Arguments

min	Low end of pixel values to expand (0-255)
max	High end of pixel values to expand (0-255)
srcimg	Source image
resimg	Result image

Description

The expandcontrast function increases the contrast of the source image area by expanding the brightness range. The value for the lower level is set to 0 (black) and the value for the upper level is set to 255 (white). Values between lower and upper are rescaled.

Result = 255 * (source - lower) / (upper - lower)

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

Return value

NO_ERROR	Function successful
BAD_RANGE	Range error, see Appendix A
BAD_IBUF	Invalid image buffer address
BAD_MEM	Insufficient local memory
BAD_BPP	Images are not both 8- or 24-bit
BAD_DIB	Source or result is a compressed DIB
BAD_FAC	Lower or upper is outside the range 0 to 255

Example C/C++ | Example VB

flipimage

Function Prototypes

Visual Basic	Declare Function flipimage Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long
C/C++	int flipimage(imgdes *srcimg, imgdes *resimg);
Java	int vic.vic32jni.flipimage(imgdes srcimg, imgdes resimg);

Function Arguments

srcimg	Source image
resimg	Result image

Description

The flipimage function flips an image area top to bottom. The source and result image areas are defined by the corresponding image descriptors.

Return value

NO_ERROR	Function successful
BAD_RANGE	Range error, see Appendix A
BAD_IBUF	Invalid image buffer address
BAD_MEM	Insufficient local memory
BAD_BPP	Images are not both 1-, 8-, or 24-bit
BAD_DIB	Source or result is a compressed DIB

Example C/C++ | Example VB

freeimage

Function Prototypes

Visual Basic	Declare Sub freeimage Lib "VIC32.DLL" (image As imgdes)
C/C++	void freeimage(imgdes far *image);
Java	void vic.vic32jni.freeimage(imgdes image);

Function Arguments

image

Image

Description

The freeimage function releases the global memory associated with the image descriptor and sets all image descriptor elements to zero. Use freeimage to release memory allocated with allocimage, allocDIB, clienttoimage, ddbtoimage, dibtoimage, dibsecttoimage, windowtoimage, and all of the TWscanxxxx functions.

Return value

There is no return value

See also

allocimage, dibtoimage

Example C/C++ | Example VB

gammabrighten

Function Prototypes

Visual Basic	Declare Function gammabrighten Lib "VIC32.DLL" (ByVal gamma As Double, srcimg As imgdes, resimg As imgdes) As Long
C/C++	int gammabrighten(double gamma, imgdes far *srcimg, imgdes far *resimg);
Java	int vic.vic32jni.gammabrighten(double gamma, imgdes srcimg, imgdes resimg);

Function Arguments

gamma	Gamma factor
srcimg	Source image
resimg	Result image

Description

The gammabrighten function increases or decreases the brightness level of each pixel in the source image area and places the result in the result image area. The new pixel value is calculated as

Result = ((Source / 255)^gamma ) * 255

To brighten an image use a gamma value between 0.0 and 1.0. The lower the value, the brighter the resulting image. To darken an image enter a value above 1.0. The higher the value, the darker the resulting image.

To reverse a gamma operation, call gammabrighten a second time and set the gamma value to the inverse of the previous gamma correction factor. For example, brighten an image with gamma of 0.5, and restore it to its original appearance with gamma of 2.0.

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

Return value

NO_ERROR	Function successful
BAD_RANGE	Range error, see Appendix A
BAD_IBUF	Invalid image buffer address
BAD_MEM	Insufficient local memory
BAD_BPP	Images are not both 8- or 24-bit
BAD_DIB	Source or result is a compressed DIB

Example C/C++ | Example VB

getgifcomment

Function Prototypes

Visual Basic	Declare Function getgifcomment Lib "VIC32.DLL" (ByVal filename As String, ByVal commentstring As String, ByVal commentstringsize As Long) As Long
C/C++	int getgifcomment(LPCSTR filename, char *commentstring, int commentstringsize);
Java	int vic.vic32jni.getgifcomment(String filename, char[] commentstring, int commentstringsize);

Function Arguments

filename	Filename to read
commentstring	Buffer to receive comment
commentstringsize	Number of characters buffer can hold

Description

The getgifcomment function copies a comment string (if present) from a GIF file to a buffer. If the number of characters in the comment exceeds commentstringsize, the string is truncated to fit into the buffer. To determine the size of the buffer to allocate to hold the string, call getgifcomment with the commentstring value equal NULL (see example).

Return value

0 to 32768	Actual number of characters copied into buffer
BAD_OPN	Filename not found
BAD_GIF	File is not a valid GIF file

See also

setgifcomment

Example C/C++

getpixelcolor

Function Prototypes

Visual Basic	Declare Function getpixelcolor Lib "VIC32.DLL" (srcimg As imgdes, ByVal xcoord As Long, ByVal ycoord As Long) As Long
C/C++	long getpixelcolor(imgdes *srcimg, int xcoord, int ycoord);
Java	int vic.vic32jni.getpixelcolor(imgdes srcimg, int xcoord, int ycoord);

Function Arguments

srcimg	Source image
xcoord	Pixel x-coordinate
ycoord	Pixel y-coordinate

Description

The getpixelcolor function returns the value of a pixel in the image buffer at (xcoord,ycoord). A negative return value indicates an error.

The source image is defined by the image descriptor.

For a 1-bit image, the value returned is either 0 or 1. For an 8-bit image, the value returned is between 0 and 255. For a 24-bit image, RGB values are returned as long integers that can be decomposed as follows:

blue = (return_value / 65536) & 255
green = (return_value / 256) & 255
red = return_value & 255

Return value

0 - 0xFFFFFF	Pixel value
BAD_RANGE	Xcoord is greater or equal to image.bmh.biWidth or ycoord is greater or equal to image.bmh.biHeight
BAD_BPP	Source image is not 1-, 8-, or 24-bit

Example C/C++ | Example VB

Visual Basic	Declare Function getpngcomment Lib "VIC32.DLL" (ByVal filename As String, ByVal commenttype As String, ByVal commentstring As String, ByVal commentstringsize As Long) As Long
C/C++	int getpngcomment(LPCSTR filename, char * commenttype, char * commentstring, int commentstringsize);
Java	int vic.vic32jni.getpngcomment(String filename, String commenttype, char[] commentstring, int commentstringsize);

Function Arguments

filename	Filename to read
commenttype	Type of comment to receive
commentstring	Buffer to receive comment
commentstringsize	Number of characters buffer can hold

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 commentstringsize, the string is truncated to fit into the buffer. To determine the size of the buffer to allocate to hold the string, call getpngcomment with the commentstring value 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

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 C/C++

gifframecount

Function Arguments

filename	Filename to read
totalframes	Variable to receive the number of frames in the file

Description

The gifframecount function determines the number of frames in a multiframe GIF file and places the value in the totalframes parameter.

Return value

NO_ERROR	Function successful
BAD_OPN	Filename not found
BAD_GIF	File is not a valid GIF file

Example C/C++

gifframecountfrombuffer

Function Arguments

buffer	Buffer address
totalframes	Variable to receive the number of frames in the file

Description

The gifframecountfrombuffer function determines the number of frames in a multiframe GIF file stored in memory at buffer address buffer and places the value in the totalframes parameter.

Return value

NO_ERROR	Function successful
BAD_PTR	Cannot read memory buffer
BAD_GIF	File is not a valid GIF file

Example C/C++

gifinfo

Function Arguments

filename	Filename to read
gdat	Variable of type GifData to receive the data

Description

The gifinfo function reads the header of a GIF file and places the image information in the ginfo structure. The structure is defined in the header file VICDEFS.H.

The GifData structure elements are defined as follows:

width	Image width in pixels
length	Image length in pixels
BitsColRes	Number of bits of color resolution
BitsPPixel	Number of bits per pixe
TransColor	Transparent color
Laceflag	Interlace flag
Codesize	LZW code size
GIFvers	GIF version 87 or 89
vbitcount	Victor bits per pixel (used to allocate an imagebuffer with allocimage)

The purpose of the gifinfo function is to determine if a GIF file is readable and permit allocating enough memory to load the file. The GIF file format specification is available on Compuserve.

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

NO_ERROR	Function successful
BAD_OPN	Filename not found
BAD_GIF	File is not a valid GIF file

See also

loadgif, savegif

Example C/C++ | Example VB

gifinfoallframes

Function Arguments

filename	Filename to read
gdata	GifGlobalData structure to be filled in
fdatarray	Array of GifFrameData structures to be filled in
frameElem	Number of GifFrameData structures in fdatarray

Description

The gifinfoallframes function reads through an entire multiframe GIF file and places the file and the frame information for frameElem number of frames in the data structures.

The GifGlobalData structure elements are defined as follows:

saveData	Global data of type GifGlobalSaveData scrwidth Maximum pixel width of the animation scrlength Maximum pixel length of the animation hasColorMap nonzero = global palette bckColor Color index of screen background color loop Number of times the animation should repeat
BitsPPixel	Bitcount
colorRes	int pixelAspectRatio;
commentOffset	Bytes from file start to first comment extension
colors	Number of colors in global color table
colorMapOffset	Global color table offset in file

The GifFrameData structure elements are defined as follows:

saveData	Frame data of type GifFrameSaveData startx X pixel position with respect to scrwidth starty Y pixel position with respect to scrlength hasColorMap Local palette is present! delay 100ths of a second to display frame transColor Transparent color index, 0 - 255 or -1 for no transparancy removeBy How frame is to be treated after display: 0 – The image is left unremoved 1 – The image is left unremoved 2 – The image is replaced by the background 3 – The image is replaced by the previous image waitForUserInput nonzero = expect user input
vbitcount	Victor bits per pixel
width	GIF image width, length
length	GIF image width, length
frame	Frame number the data describes
interlace	Interlaced image
codesize	Code size
colors	Number of colors in local color table
colorMapOffset	Local color table offset in file
rasterDataOffset	Bytes from file start to start of raster data

This function should be preceded by a call to gifframecount to determine the number of frames in the file.

Return value

NO_ERROR	Function successful
BAD_OPN	Filename not found
BAD_GIF	File is not a valid GIF file
BAD_DATA	File has been corrupted

See also

loadgif, savegif

Example C/C++

gifinfoframe

Function Arguments

filename	Filename to read
ginfo	GifData structure to be filled in
gdata	GifGlobalData structure to be filled in
fdata	GifFrameData structure to be filled in
frameTarget	Frame number (zero-based)

Description

The gifinfoframe function reads the header of a GIF file and the frame header of a specified frame and places the file and image information in the data structures. The first frame in a file is frame number zero.

The GifData structure elements are defined as follows:

width	Image width in pixels
length	Image length in pixels
BitsColRes	Number of bits of color resolution
BitsPPixel	Number of bits per pixe
TransColor	Transparent color
Laceflag	Interlace flag
Codesize	LZW code size
GIFvers	GIF version 87 or 89
vbitcount	Victor bits per pixel (used to allocate an imagebuffer with allocimage)

The GifGlobalData structure elements are defined as follows:

saveData	Global data of type GifGlobalSaveData scrwidth Maximum pixel width of the animation scrlength Maximum pixel length of the animation hasColorMap nonzero = global palette bckColor Color index of screen background color loop Number of times the animation should repeat
BitsPPixel	Bitcount
colorRes	int pixelAspectRatio;
commentOffset	Bytes from file start to first comment extension
colors	Number of colors in global color table
colorMapOffset	Global color table offset in file

The GifFrameData structure elements are defined as follows:

saveData	Frame data of type GifFrameSaveData startx X pixel position with respect to scrwidth starty Y pixel position with respect to scrlength hasColorMap Local palette is present! delay 100ths of a second to display frame transColor Transparent color index, 0 - 255 or -1 for no transparancy removeBy How frame is to be treated after display: 0 – The image is left unremoved 1 – The image is left unremoved 2 – The image is replaced by the background 3 – The image is replaced by the previous image waitForUserInput nonzero = expect user input
vbitcount	Victor bits per pixel
width	GIF image width, length
length	GIF image width, length
frame	Frame number the data describes
interlace	Interlaced image
codesize	Code size
colors	Number of colors in local color table
colorMapOffset	Local color table offset in file
rasterDataOffset	Bytes from file start to start of raster data

Return value

NO_ERROR	Function successful
BAD_OPN	Filename not found
BAD_GIF	File is not a valid GIF file

See also

loadgif, savegif

Example C/C++

gifinfoframefrombuffer

Function Arguments

buffer	Buffer address
ginfo	GifData structure to be filled in
gdata	GifGlobalData structure to be filled in
fdata	GifFrameData structure to be filled in
frameTarget	Frame number (zero-based)

Description

The gifinfoframefrombuffer function reads from a GIF file in memory and places the file and frame image information in the data structures. The first frame in a file is frame number zero.

The GifData structure elements are defined as follows:

width	Image width in pixels
length	Image length in pixels
BitsColRes	Number of bits of color resolution
BitsPPixel	Number of bits per pixe
TransColor	Transparent color
Laceflag	Interlace flag
Codesize	LZW code size
GIFvers	GIF version 87 or 89
vbitcount	Victor bits per pixel (used to allocate an imagebuffer with allocimage)

The GifGlobalData structure elements are defined as follows:

saveData	Global data of type GifGlobalSaveData scrwidth Maximum pixel width of the animation scrlength Maximum pixel length of the animation hasColorMap nonzero = global palette bckColor Color index of screen background color loop Number of times the animation should repeat
BitsPPixel	Bitcount
colorRes	int pixelAspectRatio;
commentOffset	Bytes from file start to first comment extension
colors	Number of colors in global color table
colorMapOffset	Global color table offset in file

The GifFrameData structure elements are defined as follows:

saveData	Frame data of type GifFrameSaveData startx X pixel position with respect to scrwidth starty Y pixel position with respect to scrlength hasColorMap Local palette is present! delay 100ths of a second to display frame transColor Transparent color index, 0 - 255 or -1 for no transparancy removeBy How frame is to be treated after display: 0 – The image is left unremoved 1 – The image is left unremoved 2 – The image is replaced by the background 3 – The image is replaced by the previous image waitForUserInput nonzero = expect user input
vbitcount	Victor bits per pixel
width	GIF image width, length
length	GIF image width, length
frame	Frame number the data describes
interlace	Interlaced image
codesize	Code size
colors	Number of colors in local color table
colorMapOffset	Local color table offset in file
rasterDataOffset	Bytes from file start to start of raster data

Return value

NO_ERROR	Function successful
BAD_GIF	File is not a valid GIF file
BAD_PTR	Buffer does not point to readable memory

See also

loadgif, savegif

gifinfofrombuffer

Function Arguments

buffer	Buffer address
ginfo	Variable of type GifData to receive the data

Description

The gifinfofrombuffer function reads the header information from memory holding GIF file data and places the image information in the ginfo structure.

The GifData structure elements are defined as follows:

width	Image width in pixels
length	Image length in pixels
BitsColRes	Number of bits of color resolution
BitsPPixel	Number of bits per pixe
TransColor	Transparent color
Laceflag	Interlace flag
Codesize	LZW code size
GIFvers	GIF version 87 or 89
vbitcount	Victor bits per pixel (used to allocate an imagebuffer with allocimage)

The purpose of the gifinfofrombuffer function is to identify the type and size of the image and permit allocating enough memory to load the image.

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

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 C/C++

histobrighten

Function Prototypes

Visual Basic	Declare Function histobrighten Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long
C/C++	int histobrighten(imgdes *srcimg, imgdes *resimg);
Java	int vic.vic32jni.histobrighten(imgdes srcimg, imgdes resimg);

Function Arguments

srcimg	Source image
resimg	Result image

Description

The histobrighten function brightens an image area by reassigning brightness levels so that the integral of the resulting histogram increases quadratically with brightness level. The source and result image areas are defined by the corresponding image descriptors.

Histogram brightening generally reduces the number of brightness levels present in the image. Contrast is improved, but details may be lost. Histogram brightening is sometimes very effective in bringing out the details of an image when the subject of interest is hidden in shadows.

Return value

NO_ERROR	Function successful
BAD_RANGE	Range error (see Appendix A) or image area is less than 16 pixels
BAD_IBUF	Invalid image buffer address
BAD_MEM	Insufficient local memory
BAD_BPP	Images are not both 8- or 24-bit
BAD_DIB	Source or result is a compressed DIB

See also

histoequalize

Example C/C++ | Example VB

histoequalize

Function Prototypes

Visual Basic	Declare Function histoequalize Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long
C/C++	int histoequalize(imgdes *srcimg, imgdes *resimg);
Java	int vic.vic32jni.histoequalize(imgdes srcimg, imgdes resimg);

Function Arguments

srcimg	Source image
resimg	Result image

Description

The histoequalize function reassigns brightness levels of the image area so that the integral of the resulting histogram increases linearly with brightness level. The source and result image areas are defined by the corresponding image descriptors. Histogram equalization is most effective when applied to a dark image.

Return value

NO_ERROR	Function successful
BAD_RANGE	Range error, see Appendix A
BAD_IBUF	Invalid image buffer address
BAD_MEM	Insufficient local memory
BAD_BPP	Images are not both 8- or 24-bit
BAD_DIB	Source or result is a compressed DIB

Example C/C++ | Example VB

hsv2rgb

Function Prototypes

Visual Basic	Declare Sub hsv2rgb Lib "VIC32.DLL" (ByRef hsvtab As HSVTRIPLE, ByRef rgbtab As RGBQUAD, ByVal colors As Long)
C/C++	void hsv2rgb(HSVTRIPLE *hsvtab, RGBQUAD *rgbtab, int colors);
Java	void vic.vic32jni.hsv2rgb(HSVTRIPLE[] hsvtab, RGBQUAD[] rgbtab, int colors);

Function Arguments

hsvtab	HSV data table
rgbtab	RGB palette table
colors	Number of colors to convert

Description

The hsv2rgb function converts a hue, saturation, value (HSV) table to a red, green, blue (RGB) color palette. This function and the rgb2hsv function are used to convert between the RGB and HSV color models.

The HSVTRIPLE structure describes a color consisting of relative intensities of hue, saturation, and value. The hsvtab variable is an array of HSVTRIPLE structures. HSVTRIPLE is a Victor Library data structure.

The RGBQUAD structure describes a color consisting of relative intensities of red, green, and blue. The rgbtab variable is an array of RGBQUAD structures. RGBQUAD is a Windows data structure.

Each HSV table entry can range from 0 to 255. The RGB table must be large enough to hold colors RGBQUAD structures. Each RGB table entry will range from 0 to 255.

Return value

There is no return value.

Example C/C++

imageareatorect

Function Prototypes

Visual Basic	Declare Sub imageareatorect Lib "VIC32.DLL" (ByRef srcimg As imgdes, ByRef arect As RECT)
C/C++	void imageareatorect(imgdes *srcimg, RECT *arect);
Java	void vic.vic32jni.imageareatorect(imgdes srcimg, RECT arect);

Function Arguments

srcimg	Source image
arect	Variable of type RECT to receive the data

Description

The imageareatorect function sets the members of a RECT data structure to the image area defined by the image descriptor.

The RECT structure elements are defined as follows:

left	X-coordinate of the rectangle's upper-left corner
top	Y-coordinate of the rectangle's upper-left corner
right	X-coordinate of the rectangle's lower-right corner
bottom	Y-coordinate of the rectangle's lower-right corner

This function performs the following assignments:

arect.left	= image.stx
arect.top	= image.sty
arect.right	= image.endx
arect.bottom	= image.endy

Return value

There is no return value.

Example C/C++

imagetodib

Function Prototypes

Visual Basic	Declare Function imagetodib Lib "VIC32.DLL" (ByRef srcimg As imgdes, ByRef dibaddr As Long) As Long
C/C++	int imagetodib(imgdes *srcimg, UCHAR **dibaddr);
Java	int vic.vic32jni.imagetodib(imgdes srcimg, refvar dibaddr);

Function Arguments

srcimg	Source image
dibaddr	Variable to receive result DIB address

Description

The imagetodib example creates a packed device independent bitmap (DIB) from an image area. The image area is defined by the image descriptor. This function is useful for passing an image to the clipboard. In 32-bit Windows imagetoDIB uses the allocDIB function to create a clipboard-compatible DIB in contiguous memory.

A DIB created with this function must be released when no longer needed. To free the memory the following code can be used:

   hMem = GlobalPtrHandle(dib); // WINDOWSX.H macro
   GlobalUnlock(hMem);  // Unlock the handle to the DIB
   GlobalFree(hMem);

If the DIB is passed to the clipboard, memory owned by the DIB must NOT be freed, since Windows assumes responsibility for this memory.

Return value

NO_ERROR	Function successful
BAD_RANGE	Range error, see Appendix A
BAD_IBUF	Invalid image buffer address
BAD_MEM	Insufficient global memory
BAD_BPP	Image is not 1-, 8-, or 24-bit
BAD_DIB	Source or result is a compressed DIB
BAD_LOCK	Global memory could not be locked

Example C/C++ | Example VB

isgrayscaleimage

Function Prototypes

Visual Basic	Declare Function isgrayscaleimage Lib "VIC32.DLL" (srcimg As imgdes) As Long
C/C++	BOOL isgrayscaleimage(imgdes far *srcimg);
Java	int vic.vic32jni.isgrayscaleimage(imgdes srcimg);

Function Arguments

srcimg

Source 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.

The source image is defined by the image descriptor.

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

• The red, green, and blue values of each palette entry must be equal
• The interval between adjacent palette entries must be positive and constant.

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 loadfile functions call isgrayscaleimage internally and correctly set the value of the image descriptor element imgtype.

Return value

nonzero	Image is grayscale
0	Image is not grayscale

jpeggeterror

Function Prototypes

Visual Basic	Declare Function jpeggeterror Lib "VIC32.DLL" () As Long
C/C++	int jpeggeterror(void);
Java	int vic.vic32jni.jpeggeterror();

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

Return value

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 C/C++

jpeginfo

Function Arguments

filename	Filename to read
jinfo	Variable of type JpegData to receive the data

Description

The jpeginfo function reads the header of a JPEG File Interchange Format (JFIF) file and places the image information in the jinfo structure.

The purpose of the jpeginfo function is to determine if a JPEG file is readable and permit allocating enough memory to load the image.

The JpegData structure elements are defined as follows:

ftype	File type, 0 - 11 are valid file types, ftype is set to -1 if the file type cannot be determined.
width	Image width in pixels
length	Image length in pixels
comps	Number of components, 1 for a grayscale image, 3 or 4 for a color image
precision	Sample precision, 8 or 12 bits per component
sampFac[4]	Sampling factors for each component. Each sampFac[] element contains the horizontal and vertical sampling factors in the most significant 4 bits and the least significant 4 bits, respectively. Each sampling factor can be 1, 2, or 4.
vbitcount	Victor bits per pixel (used to allocate an imagebuffer with allocimage).

JPEG references:

1. The Data Compression Book, Mark Nelson, M & T Books, San Mateo, CA 94402, 1992. A good discussion of most of the principles involved in JPEG compression, but this book does not actually implement the algorithm as specified in the standard.
2. The archive JPSRC3.ZIP. Available from various sources including CompuServe in the GRAPHICSUPPORT forum (GO PICS), library 10. This archive contains CJPEG.EXE, DJPEG.EXE, and oodles of source code.
3. "Digital Compression and Coding of Continuous-tone Still Images, Part 1, Requirements and Guidelines", ISO/IEC DIS 10918-1. Available from ANSI sales at (212) 642-4900.
4. JFIF file specification. Available from Literature Dept., C-Cube Microsystems, Inc., 399A W. Trimble Rd., San Jose, CA 95131, (408) 944-6300. The savejpg() and loadjpg() routines read and write files using the JPEG File Interchange Format (JFIF), which is described in this document.

Return value

NO_ERROR	Function successful
BAD_OPN	Filename not found
BAD_JPEG	File is not a valid JPEG JFIF file

See also

loadjpg, savejpg

Example C/C++

jpeginfoex

Function Arguments

filename	Filename to read
jinfoex	JpegDataEx structure to be filled in

Description

The jpeginfoex function reads the header of a JPEG File Interchange Format (JFIF) file and places the image information in the jinfoex structure. Jpeginfoex provides the same information as jpeginfo and, in addition, supplies resolution and thumbnail data.

The JpegDataEx structure elements are defined as follows:

ftype	File type, 0 - 11 are valid file types, ftype is set to -1 if the file type cannot be determined.
width	Image width in pixels
length	Image length in pixels
comps	Number of components, 1 for a grayscale image, 3 or 4 for a color image
precision	Sample precision, 8 or 12 bits per component
sampFac[4]	Sampling factors for each component. Each sampFac[] element contains the horizontal and vertical sampling factors in the most significant 4 bits and the least significant 4 bits, respectively. Each sampling factor can be 1, 2, or 4.
vbitcount	Victor bits per pixel (used to allocate an imagebuffer with allocimage).
xres	Horizontal resolution
yres	Vertical resolution
resunit	Resolution units: 0 = No units, xres/yres represent aspect ratio 1 = Dots per inch (dpi) 2 = Dots per centimeter (dpc)
thumbNail	Thumbnail descriptor of type JPEG_THUMB_DATA hasThumbNail nonzero if thumbnail image is present width Thumbnail width in pixels length Thumbnail length in pixels bitcount Thumbnail bits per pixel, 8 or 24 coding Thumbnail coding 0x10 = JPEG encoded thumbnail 0x11 = 8-bit palette color thumbnail 0x13 = 24-bit RGB thumbnail

Return value

NO_ERROR	Function successful
BAD_OPN	Filename not found
BAD_JPEG	File is not a valid JPEG JFIF file
BAD_MEM	Insufficient memory

See also

jpeginfo

jpeginfofrombuffer

Function Arguments

buff	Buffer address
jinfo	JpegData structure to be filled in

Description

The jpeginfofrombuffer function reads JPEG header data from memory holding JPEG file data and places the image information in the jinfo structure.

The purpose of the jpeginfofrombuffer function is to determine if JPEG data is readable and permit allocating enough memory to load the image.

The JpegData structure elements are defined as follows:

ftype	File type, 0 - 11 are valid file types, ftype is set to -1 if the file type cannot be determined.
width	Image width in pixels
length	Image length in pixels
comps	Number of components, 1 for a grayscale image, 3 or 4 for a color image
precision	Sample precision, 8 or 12 bits per component
sampFac[4]	Sampling factors for each component. Each sampFac[] element contains the horizontal and vertical sampling factors in the most significant 4 bits and the least significant 4 bits, respectively. Each sampling factor can be 1, 2, or 4.
vbitcount	Victor bits per pixel (used to allocate an imagebuffer with allocimage).

JPEG references:

1. The Data Compression Book, Mark Nelson, M & T Books, San Mateo, CA 94402, 1992. A good discussion of most of the principles involved in JPEG compression, but this book does not actually implement the algorithm as specified in the standard.
2. The archive JPSRC3.ZIP. Available from various sources including CompuServe in the GRAPHICSUPPORT forum (GO PICS), library 10. This archive contains CJPEG.EXE, DJPEG.EXE, and oodles of source code.
3. "Digital Compression and Coding of Continuous-tone Still Images, Part 1, Requirements and Guidelines", ISO/IEC DIS 10918-1. Available from ANSI sales at (212) 642-4900.
4. JFIF file specification. Available from Literature Dept., C-Cube Microsystems, Inc., 399A W. Trimble Rd., San Jose, CA 95131, (408) 944-6300. The savejpg() and loadjpg() routines read and write files using the JPEG File Interchange Format (JFIF), which is described in this document.

Return value

NO_ERROR	Function successful
BAD_OPN	Memory handle not available
BAD_JPEG	File is not a valid JPEG JFIF file
BAD_PTR	Buff does not point to readable memory

See also

jpeginfo

Example C/C++

jpeginfofrombufferex

Function Arguments

buff	Buffer address
jinfoex	JpegDataEx structure to be filled in

Description

The jpeginfofrombufferex function reads the header information from memory holding JPEG file data and places the image information in the jinfoex structure. Jpeginfofrombufferex provides the same information as jpeginfofrombuffer and, in addition, supplies resolution and thumbnail data.

The JpegDataEx structure elements are defined as follows:

ftype	File type, 0 - 11 are valid file types, ftype is set to -1 if the file type cannot be determined.
width	Image width in pixels
length	Image length in pixels
comps	Number of components, 1 for a grayscale image, 3 or 4 for a color image
precision	Sample precision, 8 or 12 bits per component
sampFac[4]	Sampling factors for each component. Each sampFac[] element contains the horizontal and vertical sampling factors in the most significant 4 bits and the least significant 4 bits, respectively. Each sampling factor can be 1, 2, or 4.
vbitcount	Victor bits per pixel (used to allocate an imagebuffer with allocimage).
xres	Horizontal resolution
yres	Vertical resolution
resunit	Resolution units: 0 = No units, xres/yres represent aspect ratio 1 = Dots per inch (dpi) 2 = Dots per centimeter (dpc)
thumbNail	Thumbnail descriptor of type JPEG_THUMB_DATA hasThumbNail nonzero if thumbnail image is present width Thumbnail width in pixels length Thumbnail length in pixels bitcount Thumbnail bits per pixel, 8 or 24 coding Thumbnail coding 0x10 = JPEG encoded thumbnail 0x11 = 8-bit palette color thumbnail 0x13 = 24-bit RGB thumbnail

Return value

NO_ERROR	Function successful
BAD_OPN	Memory handle not available
BAD_JPEG	File is not a valid JPEG JFIF file
BAD_PTR	Buff does not point to readable memory
BAD_MEM	Insufficient memory

jpeginfofrombuffer, loadjpgfrombuffer

jpegsetthumbnailsize

Function Prototypes

Visual Basic	Declare Function jpegsetthumbnailsize Lib "VIC32.DLL" (ByVal longEdge As Long) As Long
C/C++	int jpegsetthumbnailsize(int longEdge);/td>
Java	int vic.vic32jni.jpegsetthumbnailsize(int longEdge);

Function Arguments

longEdge

Size of longer dimension, width or length (1 - 255)

Description

The jpegsetthumbnailsize function sets the size for embedded thumbnails for all subsequent JPEG files created with savejpgex. The value of longEdge is used for the longer dimension, width or length, and the other dimension is calculated to preserve the image aspect ratio. LongEdge must be in the range 1 - 255.

Even if jpegsetthumbnailsize returns NO_ERROR, that does not guarantee that savejpgex will be able to write a JPEG file with an embedded thumbnail of the size specified. The embedded thumbnail must occupy less than 65536 bytes. This is only a concern for 24-bit images where the calculation is

   thumbnail bytes = width * length * 3 +16

So, for example, if longEdge is set to 255 and the other dimension is greater than 85, savejpgex will fail and return BAD_TN_SIZE.

Return value

NO_ERROR	Function successful
BAD_FAC	LongEdge is outside the range 1 to 255

See also
savejpgex

Example C/C++

jpegsetxyresolution

Function Arguments

xres	Horizontal resolution in pixels (0 - 65535)
yres	Vertical resolution in pixels (0 - 65535)
resUnit	Resolution unit (0-2) 0 = No unit of measurement, xres/yres represent aspect ratio 1 = Inch 2 = Centimeter

Description

The jpegsetxyresolution function sets the horizontal and vertical resolution and resolution unit for a JPEG file. All subsequent files saved with the savejpg functions will use the values set by jpegsetxyresolution. The default values are xres = 1, yres = 1, resunit = 0 (no units); that is, the default setting represents a pixel aspect ratio of 1:1 (square).

Return value

There is no return value.

See also

tiffsetxyresolution

kodalith

Function Prototypes

Visual Basic	Declare Function kodalith Lib "VIC32.DLL" (ByVal threshold As Long, srcimg As imgdes, resimg As imgdes) As Long
C/C++	int kodalith(const int threshold, imgdes far *srcimg, imgdes far *resimg);
Java	int vic.vic32jni.kodalith(int threshold, imgdes srcimg, imgdes resimg);

Function Arguments

threshold	Threshold value for separation (0-255)
srcimg	Source image
resimg	Result image

Description

The kodalith function creates a high contrast image area, containing only black and white pixels, similar to a Kodalith print. The threshold value determines whether a pixel is set to black or white.

if Source > threshold
Result = 255
if Source <= threshold
Result = 0

For an RGB image the source pixel value is calculated

Source = (red + green + blue) / 3

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

Return value

NO_ERROR	Function successful
BAD_RANGE	Range error, see Appendix A
BAD_IBUF	Invalid image buffer address
BAD_MEM	Insufficient local memory
BAD_BPP	Images are not both 8- or 24-bit
BAD_DIB	Source or result is a compressed DIB
BAD_FAC	Thresh is outside the range 0 to 255

Example C/C++ | Example VB