This Library Reference contains an entry for each function in the Victor Library. The function prototypes are shown for C/C++, Java, and Visual Basic. The function arguments and explanations are listed. And a description of the operation, return codes, and sample use of each function is given. The functions are listed alphabetically.
Image Pixel Depth
At the top of each function entry the numbers in the tinted boxes indicate the pixel depth of image that the function can operate on: 1-, 8-, 16-, or 24-bits per pixel. For example, addimage (first of the function descriptions) can operate on an 8- or 24-bit per pixel image.
For loadfile functions the boxed numbers describe the pixel depth of the image the file is loaded into and not the file pixel depth. If boxed numbers are not displayed the function operation is independent of image bits per pixel.
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function addimage Lib "VIC32.DLL" (srcimg As imgdes, oprimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int addimage(imgdes *srcimg, imgdes *oprimg, imgdes *resimg); |
| Java | int vic.vic32jni.addimage(imgdes srcimg, imgdes oprimg, imgdes resimg); |
Function Arguments
| srcimg | Source image |
| oprimg | Operator image |
| resimg | Result image |
Description
The addimage function adds the brightness level of each pixel in the source image area to the brightness level of the corresponding pixel in the operator image area and places the sum in the result image area. Result values greater than 255 are set to 255.
The 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 all 8- or 24-bit |
| BAD_DIB | One of the images is a compressed DIB |
| 1 | 8 | 16 | 24 |
Function Prototypes
| Visual Basic | Declare Function allocDIB Lib "VIC32.DLL" (image As imgdes, ByVal width As Long, ByVal length As Long, ByVal vbitcount As Long) As Long |
| C/C++ | int allocDIB(imgdes *image, int width, int length, int vbitcount); |
| Java | int vic.vic32jni.allocDIB(imgdes image, int width, int length, int vbitcount); |
Function Arguments
| image | Image |
| width | Image buffer width |
| length | Image buffer length |
| vbitcount | Bits per pixel (1, 8, 16, or 24) |
Description
The allocDIB function allocates space for an image in contiguous global memory as a packed device independent bitmap (DIB). The memory allocated is sufficient to hold the BITMAPINFOHEADER header, palette, and image data of the DIB. The width, length, and vbitcount parameters determine the amount of memory allocated.
AllocDIB is similar to allocimage, but allocDIB allocates memory that is guaranteed contiguous, that is, the DIB components (BITMAPINFO struct and image data) are in adjacent memory blocks. This is a packed DIB and is compatible with the Windows clipboard CF_DIB format.
Allocimage, on the other hand, allocates memory that may not be contiguous -- the DIB components are not necessarily in adjacent memory blocks. If you are creating an image to pass to the clipboard, use allocDIB, otherwise, use allocimage.
If successful, allocDIB fills in the image descriptor and BITMAPINFOHEADER fields. The allocDIB function always sets the image descriptor element hBitmap to zero. For details, see allocimage.
The source code for allocDIB is included with the library in the module VICCORE.C. In the 16-bit library allocDIB is defined as allocimage.
Return value
| NO_ERROR | Function successful |
| BAD_RANGE | Width or length is zero |
| BAD_MEM | Insufficient global memory |
| BAD_BPP | Vbitcount is not 1, 4, 8, 16, or 24 |
See also
allocimage
| 1 | 8 | 16 | 24 |
Function Prototypes
| Visual Basic | Declare Function allocimage Lib "VIC32.DLL" (image As imgdes, ByVal width As Long, ByVal length As Long, ByVal vbitcount As Long) As Long |
| C/C++ | int allocimage(imgdes *image, int width, int length, int vbitcount); |
| Java | int vic.vic32jni.allocimage(imgdes image, int width, int length, int vbitcount); |
Function Arguments
| image | Image |
| width | Image buffer width |
| length | Image buffer length |
| vbitcount | Bits per pixel (1, 8, 16, or 24) |
Description
The allocimage function allocates space for an image as a DIB. The memory allocated is sufficient to hold the BITMAPINFOHEADER header, palette, and image data of the DIB. The width, length, and vbitcount parameters determine the amount of memory allocated.
The size of the palette area is dependent upon the vbitcount parameter. As shown below, the palette_size variable equals the amount of memory in bytes allocated for the palette data.
If successful, the allocimage function fills the following image descriptor fields:
| ibuff | = image data address |
| stx | = 0 |
| sty | = 0 |
| endx | = width - 1 |
| endy | = length - 1 |
| buffwidth | = (width * vbitcount + 31) / 32 * 4) |
| palette | = palette data address |
| colors | = 1 << vbitcount for 1- or
8-bit image
= 0 for 16- or 24-bit image |
| imgtype | = 1 for 1- or 8-bit image
= 0 for 24-bit image |
| bmh | = bitmapinfoheader address |
| hBitmap | = device independent bitmap handle |
Allocimage also fills the BITMAPINFOHEADER fields:
| biSize | = BITMAPINFOHEADER size in bytes |
| biWidth | = width |
| biHeight | = length |
| biPlanes | = 1 |
| biBitCount | = vbitcount (1, 8, 16, or 24) |
| biCompression | = BI_RGB (no compression) |
| biSizeImage | = buffwidth * length |
| biXPelsPerMeter | = 0 |
| biYPelsPerMeter | = 0 |
| biClrUsed | = 1 << vbitcount for 1-
or 8-bit image
= 0 for 16- or 24-bit image |
| biClrImportant | = 1 << vbitcount
for 1- or 8-bit image
= 0 for 16- or 24-bit image |
Allocimage initializes the palette to grayscale for an 8-bit image, and black and white for a 1-bit image.
An image allocated with allocimage must be released with freeimage when no longer needed to free memory used by the image.
If allocimage is called with vbitcount equal to 4, an 8-bit image buffer is allocated. This is to simplify loading a 4-bit BMP file.
If allocimage is called with vbitcount equal to 16, a 16-bit grayscale image buffer is allocated.
The source code for allocimage is included with the library in the module VICCORE.C.
There are some subtle differences between the allocimage functions as
implemented in the 16-
and 32-bit libraries that are worth noting:
Return value
| NO_ERROR | Function successful |
| BAD_RANGE | Width or length is zero |
| BAD_MEM | Insufficient global memory |
| BAD_BPP | Vbitcount is not 1, 4, 8, 16, or 24 |
See also
allocDIB
| 1 | 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function andimage Lib "VIC32.DLL" (srcimg As imgdes, oprimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int andimage(imgdes *srcimg, imgdes *oprimg, imgdes *resimg); |
| Java | int vic.vic32jni.andimage(imgdes srcimg, imgdes oprimg, imgdes resimg); |
Function Arguments
| srcimg | Source image |
| oprimg | Operator image |
| resimg | Result image |
Description
The andimage function ANDs the value of each pixel in the source image area
with the value of
the corresponding pixel in the operator image area and places the result in
the result image area.
The 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 all 1-, 8-, or 24-bit |
| BAD_DIB | One of the images is a compressed DIB |
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function blur Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int blur(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.blur(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Source image |
| resimg | Result image |
Description
The blur function softens the appearance of an image area by averaging 9 neighboring pixels to produce a smoothed image with softened edges.
The image areas are defined by the corresponding image descriptors.
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 local memory |
| BAD_BPP | Images are not both 8- or 24-bit |
| BAD_DIB | Source or result is a compressed DIB |
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function blurthresh Lib "VIC32.DLL" (ByVal threshold As Long, srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int blurthresh(int threshold, imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.blurthresh(int threshold, imgdes srcimg, imgdes resimg); |
Function Arguments
| threshold | Threshold value (0-255) |
| srcimg | Source image |
| resimg | Result image |
Description
The blurthresh function is similar to the blur routine in that it softens the appearance of an image area, but also uses a threshold value which allows smoothing without degrading the edges of the image. If a pixel's brightness value differs from its neighbors' average value by greater than the threshold amount, it will not be changed. So, a threshold of 0 produces no blurring, while 255 is equivalent to using the blur function. The threshold value determines the amount of smoothing that occurs.
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) or Image area is less than 3 x 3 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 |
| BAD_FAC | Threshold is outside the range 0 to 255 |
See also
blur
Function Prototypes
| Visual Basic | Declare Function bmpinfo Lib "VIC32.DLL" (ByVal filename As String, ByRef bminfo As BITMAPINFOHEADER) As Long |
| C/C++ | int bmpinfo(LPCSTR filename, BITMAPINFOHEADER *bminfo); |
| Java | int vic.vic32jni.bmpinfo(String filename, BITMAPINFOHEADER bminfo); |
Function Arguments
| filename | Filename to read |
| bminfo | Variable of type BITMAPINFOHEADER to receive the data |
Description
The bmpinfo function reads the header of a BMP file and places the information in the bminfo structure. The purpose of the bmpinfo function is to identify the type and size of the image in the file to permit allocating enough memory to load the file.The BITMAPINFOHEADER structure is defined in the file WINDOWS.H and is shown below.
The BITMAPINFOHEADER structure elements are defined as follows:
| biSize | Size of this struct |
| biWidth | Image width in pixels |
| biHeight | Image height in pixels |
| biPlanes | Planes = 1 |
| biBitCount | Color bits per pixel 1, 4, 8, 24 |
| biCompression | Compression type |
| biSizeImage | Image size in bytes |
| biXPelsPerMeter | Horizontal resolution |
| biYPelsPerMeter | Vertical resolution |
| biClrUsed | Number of colors used |
| biClrImportant | Number of important colors |
The BMP file 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. For more information, see loadbmp.
Return value
| NO_ERROR | Function successful |
| BAD_OPN | Filename not found |
| BAD_BMP | File is not a readable BMP format |
See also
loadbmp, savebmp
Function Prototypes
| Visual Basic | Declare Function bmpinfofrombuffer Lib "VIC32.DLL" (ByVal buff As Long, ByRef bminfo As BITMAPINFOHEADER) As Long |
| C/C++ | int bmpinfofrombuffer(UCHAR *buff, BITMAPINFOHEADER *bminfo); |
| Java | int vic.vic32jni.bmpinfofrombuffe(int buff, BITMAPINFOHEADER bminfo); |
Function Arguments
| buff | Buffer address |
| bminfo | Variable of type BITMAPINFOHEADER to receive the data |
The BITMAPINFOHEADER structure elements are defined as follows:
| biSize | Size of this struct |
| width | Image width in pixels |
| biSize | Size of this struct |
| biWidth | Image width in pixels |
| biHeight | Image height in pixels |
| biPlanes | Planes = 1 |
| biBitCount | Color bits per pixel 1, 4, 8, 24 |
| biCompression | Compression type |
| biSizeImage | Image size in bytes |
| biXPelsPerMeter | Horizontal resolution |
| biYPelsPerMeter | Vertical resolution |
| biClrUsed | Number of colors used |
| biClrImportant | Number of important colors |
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
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function brightenmidrange Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int brightenmidrange(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.brightenmidrange(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Source image |
| resimg | Result image |
The brightenmidrange function brightens the intermediate brightness levels within an image area. The source and result image areas are defined by the corresponding image descriptors. The brightenmidrange function is useful in brightening an image before printing.
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 |
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function calcavglevel Lib "VIC32.DLL" (srcimg As imgdes, redavg As Long, grnavg As Long, bluavg As Long) As Long |
| C/C++ | int calcavglevel(imgdes *image, int *redavg, int *grnavg, int *bluavg); |
| Java | int vic.vic32jni.calcavglevel(imgdes srcimg, refvar redavg, refvar grnavg, refvar bluavg); |
Function Arguments
| image | Source image |
| redavg | Average level for an grayscale image,
or average red level for a color image |
| grnavg | Average green level |
| bluavg | Average blue level |
Description
The calcavglevel function calculates the average value of the pixels in an image area. The image area is defined by the image descriptor.
For an 8-bit grayscale image, the average level is placed in redavg. For an 8- or 24-bit color image, the average red, green, and blue values are placed in redavg, grnavg, and bluavg, respectively.
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 | Image is not 8- or 24-bit |
| BAD_DIB | Image is a compressed DIB |
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function calchisto Lib "VIC32.DLL" (image As imgdes, redtable As Long, grntable As Long, blutable As Long) As Long |
| C/C++ | int calchisto(imgdes *image, long *redtable, long *grntable, long *blutable); |
| Java | int vic.vic32jni.calchisto(imgdes image, int[] redtable, int[] grntable, int[] blutable); |
Function Arguments
| image | Source image |
| redtable | Buffer to receive
histogram data for an 8-bit image
or red histogram data for a 24-bit image |
| grntable | Buffer to receive green histogram data (24-bit only) |
| blutable | Buffer to receive blue histogram data (24-bit only) |
Description
The calchisto function calculates histogram data for an image area. The image area is defined by the image descriptor. The function counts the number of pixels at level 0 through level 255, and places the data in an array of 256 long integers.
For 8-bit images only the redtable buffer is filled. For 24-bit images data is placed into redtable, grntable, and blutable. Note that each array used must be capable of holding 256 long integers.
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 | Image is not 8- or 24-bit |
| BAD_DIB | Source or result is a compressed DIB |
See also
calchistorgb
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function calchistorgb Lib "VIC32.DLL" (image As imgdes, redtable As Long, grntable As Long, blutable As Long, ByVal histoMode As Long) As Long |
| C/C++ | int calchistorgb(imgdes *image, long *redtable, long *grntable, long *blutable, int histoMode); |
| Java | int vic.vic32jni.calchistorgb(imgdes image, int[] redtable, int[] grntable, int[] blutable, int histoMode); |
Function Arguments
| image | Source image |
| redtable | Buffer to receive
histogram data for an 8-bit image
or red histogram data for a 24-bit image |
| grntable | Buffer to receive green histogram data (24-bit only) |
| blutable | Buffer to receive blue histogram data (24-bit only) |
| histoMode | Mode 0 = interpret palette color image as gray 1 = interpret palette color image as RGB |
Description
The calchistorgb function calculates histogram data for an image area. The image area is defined by the image descriptor. The function counts the number of pixels at level 0 through level 255, and places the data in an array of 256 long integers.
The histogram data is stored in one table (redtable) or three tables
(redtable, grntable, and
blutable). A grayscale image fills one table and a 24-bit RGB image fills
three tables. A color
palette image fills one or three tables depending on histoMode. If histoMode
is zero, a palette
color image is interpreted as a grayscale image and one table is filled. If
histoMode is nonzero, a
palette color image is interpreted as a 24-bit RGB image and three tables
are filled. This is
summarized below. Note that each array used must be capable of holding 256
long integers.
| Table 4. Calchistorgb Characteristics | ||
| Image Type | histoMode | Histogram tables filled |
| 8-bit grayscale | 0 | redtable |
| 1 | redtable | |
| 8-bit palette color | 0 | redtable |
| 1 | redtable, grntable, blutable | |
| 24-bit RGB | 0 | redtable, grntable, blutable |
| 1 | redtable, grntable, blutable | |
If histoMode is zero, calchistorgb is equivalent to calchisto. To set histoMode, two constants have been defined:
| Value | Defined Constant |
| 0 | PALETTEIMAGEASGRAY |
| 1 | PALETTEIMAGEASRGB |
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 | Image is not 8- or 24-bit |
| BAD_DIB | Source or result is a compressed DIB |
See also
calchisto
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function changebright Lib "VIC32.DLL" (ByVal amount As Long, srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int changebright(int amount, imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.changebright(int amount, imgdes srcimg, imgdes resimg); |
Function Arguments
| amount | Amount to change (-255 to 255) |
| srcimg | Source image |
| resimg | Result image |
Description
The changebright function increases or decreases the brightness level of each pixel in the source image area by the specified amount and places the result in the result image area.
Result brightness values less than 0 are set to 0 and values greater than 255 are set to 255. 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 | Amount to add is outside the range -255 to 255 |
| 1 | 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function clienttoimage Lib "VIC32.DLL" (ByVal hWnd As Long, resimg As imgdes) As Long |
| C/C++ | int clienttoimage(HWND hWnd, imgdes *resimg); |
| Java | int vic.vic32jni.clienttoimage(int hWnd, imgdes resimg); |
Function Arguments
| hWnd | Window handle |
| 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
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function colordither Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes, ByVal palmode As Long) As Long |
| C/C++ | int colordither(imgdes *srcimg, imgdes *resimg, int palmode); |
| Java | int vic.vic32jni.colordither(imgdes srcimg, imgdes resimg, int palmode); |
Function Arguments
| srcimg | Source image |
| resimg | Result image |
| palmode | zero = 16-color standard
palette
nonzero = 256-color rainbow palette |
Description
The colordither function converts an 8- or 24-bit color image area into an 8-bit palette color image area. The result image is a dither representation using either the Windows 16-color standard palette or a 256-color rainbow palette, depending on the value of the palmode argument.
This function provides a very quick and accurate method for displaying a color image on a video adapter limited to 16 or 256 colors.
The color palette that is created is stored at the location defined by the result image descriptor member palette and the image descriptor member colors is set to 16 or 256.
The colordither function uses the Victor defaultpalette function or the rainbowpalette function to create the 16- or 256-color palettes used by the function.
Return value
| NO_ERROR | Function successful |
| BAD_RANGE | Range error (see Appendix A) or result does not have space for color palette (resimg.palette = 0) |
| BAD_IBUF | Invalid image buffer address |
| BAD_MEM | Insufficient local memory |
| BAD_BPP | Source is not 8- or 24-bit or result is not 8-bit |
| BAD_DIB | Source or result is a compressed DIB |
See also
convertrgbtopal, colorscatter
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function colorscatter Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes, ByVal palmode As Long) As Long |
| C/C++ | int colorscatter(imgdes *srcimg, imgdes *resimg, int palmode); |
| Java | int vic.vic32jni.colorscatter(imgdes srcimg, imgdes resimg, int palmode); |
Function Arguments
| srcimg | Source image |
| resimg | Result image |
| palmode | zero = 16-color standard
palette
nonzero = 256-color rainbow palette |
Description
The colorscatter function converts an 8- or 24-bit color image area into an 8-bit palette color image area. The result image is a scatter representation using either the Windows 16-color standard palette or a 256-color rainbow palette, depending on the value of the palmode argument.
This function provides a quick and accurate method for displaying a color image on a video adapter limited to 16 or 256 colors.
The color palette that is created is stored at the location defined by the result image descriptor member palette and the image descriptor member colors is set to 16 or 256. The colorscatter function uses the Victor defaultpalette function or the rainbowpalette function to create the 16-or 256-color palettes used by the function.
Return value
| NO_ERROR | Function successful |
| BAD_RANGE | Range error (see Appendix A) or result does not have space for a color palette (resimg.palette = 0) |
| BAD_IBUF | Invalid image buffer address |
| BAD_MEM | Insufficient local memory |
| BAD_BPP | Source is not 8- or 24-bit or result is not 8-bit |
| BAD_DIB | Source or result is a compressed DIB |
See also
convertrgbtopal, colordither
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function colortogray Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int colortogray(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.colortogray(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Color image, 8-bit or 24-bit |
| resimg | Grayscale image, 8-bit |
Description
The colortogray function converts an 8-bit or 24-bit color image area into an 8-bit grayscale image area. This function is used primarily to convert a color image to grayscale for printing. The source and result image areas are described by the corresponding image descriptors.
A grayscale palette is created and stored at the location defined by the result image descriptor member palette and colors is set to 256.
The grayscale intensity of a result pixel is based on red, green, and blue levels of the corresponding source pixel using the following formula:
gray = (30 * red + 59 * green + 11 * blue) / 100
The values 30, 59, and 11 represent the relative red, green, and blue intensities.
Return value
| NO_ERROR | Function successful |
| BAD_RANGE | Range error (see Appendix A) or result does not have space for a color palette (resimg->palette is 0) |
| BAD_IBUF | Invalid image buffer address |
| BAD_MEM | Insufficient local memory |
| BAD_BPP | Source is not 8- or 24-bit or result is not 8-bit |
| BAD_DIB | Source or result is a compressed DIB |
| 1 |
Function Prototypes
| Visual Basic | Declare Function convert1bitto8bit Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int convert1bitto8bit(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.convert1bitto8bit(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Source image, 1-bit |
| resimg | Result image, 8-bit |
Description
The convert1bitto8bit function converts a 1-bit per pixel source image area into an 8-bit per pixel result image area. The source and result image areas are defined by the corresponding image descriptors. This function is primarily used to convert a bilevel image to a grayscale image for subsequent image processing.
In the conversion a source pixel value of 1 is converted to a result pixel value of 255. A grayscale palette is created and stored at the location defined by the result image descriptor member palette and colors is set to 256. Bit 0 of the image descriptor member imgtype is set to 1.
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 | Source is not 1-bit or result is not 8-bit |
| BAD_DIB | Source or result is a compressed DIB |
See also
convert8bitto1bit
| 1 |
Function Prototypes
| Visual Basic | Declare Function convert1bitto8bitsmooth Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int convert1bitto8bitsmooth(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.convert1bitto8bitsmooth(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Source image, 1-bit |
| resimg | Result image, 8-bit |
Description
The convert1bitto8bitsmooth function converts a 1-bit per pixel source image area into an 8-bit per pixel result image area. The pixels are smoothed horizontally during the conversion. The source and result image areas are defined by the corresponding image descriptors.
This function is primarily used as a "scale to gray" method to convert a bilevel image to a grayscale image for subsequent improved appearance.
A grayscale palette is created and stored at the location defined by the result image descriptor member palette and colors is set to 256. Bit 0 of the image descriptor member imgtype is set to 1.
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 | Source is not 1-bit or result is not 8-bit |
| BAD_DIB | Source or result is a compressed DIB |
See also
convert1bitto8bit
| 8 |
Function Prototypes
| Visual Basic | Declare Function convert8bitto1bit Lib "VIC32.DLL" (ByVal conmode As Long, srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int convert8bitto1bit(int conmode, imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.convert8bitto1bit(int conmode, imgdes srcimg, imgdes resimg); |
Function Arguments
| conmode | Conversion mode (0-2) |
| srcimg | Source image, 8-bit |
| resimg | Result image, 1-bit |
Description
The convert8bitto1bit function converts an 8-bit per pixel source image area into a 1-bit per pixel result image area. The source and result image areas are defined by the corresponding image descriptors.
This function is primarily used to convert a grayscale image to a bilevel
image.
If the source image is a palette color image, convert8bitto1bit produces a
1-bit image
based on the grayscale intensity of the source image.
| conmode | Conversion technique | |
| 0 | Scatter (error diffusion) | |
| 1 | Ordered dither | |
| 2 | Threshold |
The scatter and dither conversion methods are very good for simulating gray levels in bilevel images. The threshold method converts pixels with gray levels below 128 to 0, and those above or equal to 128 to 1.
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 | Source is not 8-bit or result is not 1-bit |
| BAD_DIB | Source or result is a compressed DIB |
| 8 |
Function Prototypes
| Visual Basic | Declare Function convertgray8to16 Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int convertgray8to16(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.convertgray8to16(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Source image, 8-bit grayscale |
| resimg | Result image, 16-bit grayscale |
Description
The convertgray8to16 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
| 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 |
| 16 |
Function Prototypes
| Visual Basic | Declare Function convertgray16to8 Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int convertgray16to8(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.convertgray16to8(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Source image, 16-bit grayscale |
| resimg | Result image, 8-bit grayscale |
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
| 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 |
| 8 |
Function Prototypes
| Visual Basic | Declare Function convertpaltorgb Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int convertpaltorgb(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.convertpaltorgb(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Source image, 8-bit palette color |
| resimg | Result image, 24-bit RGB color |
Description
The convertpaltorgb function converts an 8-bit palette color image area into a 24-bit RGB image area. For each pixel in the source image area, red, green, and blue pixels are calculated and placed in the result buffer.
This function can be used to convert a 256-color image to a 24-bit RGB image for subsequent color image processing.
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 | Source is not 8- or result is not 24-bit |
| BAD_DIB | Source or result is a compressed DIB |
| 24 |
Function Prototypes
| Visual Basic | Declare Function convertrgbtopal Lib "VIC32.DLL" (ByVal palcolors As Long, srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int convertrgbtopal(int palcolors, imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.convertrgbtopal(int palcolors, imgdes srcimg, imgdes resimg); |
Function Arguments
| palcolors | Number of colors in result image (2-256) |
| srcimg | Source image, 24-bit RGB color |
| resimg | Result image, 8-bit color |
Description
The convertrgbtopal function converts a 24-bit RGB image area into an 8-bit palette color image area. The color palette is stored at the location defined by the result image descriptor member palette and colors is set to palcolors.
This function calculates the palette color image using the median-cut algorithm and follows the scheme:
Convertrgbtopal uses a through-space-distance (TSD) method to assign palette colors to pixels. Diffusion scatter is not used (see convertrgbtopalex for additional information).
This function can be used to convert 24-bit RGB images into palette color images for display on 16- and 256-color display adapters.The time required to create the palette color image depends upon the size of the area and complexity of the source 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 | Source is not 24- or result is not 8-bit |
| BAD_DIB | Source or result is a compressed DIB |
| BAD_FAC | Palcolors is outside the range 2 to 256 |
See also
convertrgbtopalex, colordither, colorscatter
| 24 |
Function Prototypes
| Visual Basic | Declare Function convertrgbtopalex Lib "VIC32.DLL" (ByVal palcolors As Long, srcimg As imgdes, resimg As imgdes, ByVal colredmode As Long) As Long |
| C/C++ | int convertrgbtopalex(int palcolors, imgdes *srcimg, imgdes *resimg, int colredmode); |
| Java | int vic.vic32jni.convertrgbtopalex(int palcolors, imgdes srcimg, imgdes resimg, int colredmode); |
Function Arguments
| palcolors | Number of colors in result image (2-256) |
| srcimg | Source image, 24-bit RGB color |
| resimg | Result image, 8-bit color |
| colredmode | Color reduction mode to use |
Description
The convertrgbtopalex function converts a 24-bit RGB image area into an 8-bit palette color image area. The color palette is stored at the location defined by the result image descriptor member palette and colors is set to palcolors.
This function calculates the palette color image using the median-cut algorithm and follows the scheme:
The colredmode parameter determines the mode to use to assign palette colors to pixels:
| Table 5. Convertrgbtopalex Color Reduction Modes | ||||
| Colredmode | Speed | Image quality | Color matching method | Use diffusion? |
| CR_OCTREENODIFF | fastest | good | octree | no |
| CR_OCTREEDIFF | faster | better | octree | yes |
| CR_TSDNODIFF1 | faster | better | TSD2 | no |
| CR_TSDDIFF | fast | best | TSD2 | yes |
In general, there is a trade-off of speed for quality, mode CR_TSDDIFF gives the best color matching but takes the longest time.
Convertrgbtopalex can use either an octree or a through-space-distance (TSD) method for mapping a pixel to a palette color. The octree method uses an octree to select the palette color, while the TSD method calculates the minimum distance in 3-D RGB space to select the palette color. The TSD method provides a more accurate color match but also takes a little longer.
Convertrgbtopalex can also use error diffusion. Error diffusion creates a higher quality image by distributing a pixel's error to its nearest neighbors. Diffusion should not be used if an image is to be processed further, in this case use mode CR_TSDNODIFF or CR_OCTREENODIFF.
This function can be used to convert 24-bit RGB images into palette color images for display on 16- and 256-color display adapters.
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 | Source is not 24- or result is not 8-bit |
| BAD_DIB | Source or result is a compressed DIB |
| BAD_FAC | Palcolors is outside the range 2 to 256, or colredmode is not 0 to 3 |
See also
colordither, colorscatter
| 1 | 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function copyimage Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int copyimage(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.copyimage(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Source image |
| resimg | Result image |
Description
The copyimage function copies a source image area and palette to a result image area and palette. The source and result image areas and palette tables are defined by the corresponding image descriptors.
The copyimage function will work correctly, even if the source and result image areas overlap within the same buffer. If the source and result image areas are not the same size, the copyimage function will use the smaller of the two areas.
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 |
| 1 | 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function copyimagebits Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int copyimagebits(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.copyimagebits(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Source image |
| resimg | Result image |
Description
The copyimagebits function copies a source image area to a result image area. The source and result image areas are defined by the corresponding image descriptors. This function does not copy palette information. The copyimagebits function will work correctly, even if the source and result image areas overlap within the same buffer. If the source and result image areas are not of the same size, the copyimagebits function will use the smaller of the two areas.
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 |
| 1 | 8 |
Function Prototypes
| Visual Basic | Declare Function copyimagepalette Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int copyimagepalette(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.copyimagepalette(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Source image |
| resimg | Result image |
Description
The copyimagepalette function copies a source image palette to a result image palette. The source and result image palettes are defined by the corresponding image descriptors. The number of colors copied is determined by the source image descriptor member colors.
Return value
There is no return value.
Function Prototypes
| Visual Basic | Declare Function copyimgdes Lib "VIC32.DLL" (srcimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int copyimgdes(imgdes *srcimg, imgdes *resimg); |
| Java | int vic.vic32jni.copyimgdes(imgdes srcimg, imgdes resimg); |
Function Arguments
| srcimg | Source image |
| resimg | Result image |
Description
The copyimgdes function copies all elements of a source image descriptor to a result image descriptor. Note that this function does not copy any image data, it only copies structure member data. Copyimgdes is equivalent to:
| resimg.ibuff | = srcimg.ibuff |
| resimg.stx | = srcimg.stx |
| resimg.sty | = srcimg.sty |
| resimg.endx | = srcimg.endx |
| resimg.endy | = srcimg.endy |
| resimg.buffwidth | = srcimg.buffwidth |
| resimg.palette | = srcimg.palette |
| resimg.colors | = srcimg.colors |
| resimg.imgtype | = srcimg.imgtype |
| resimg.bmh | = srcimg.bmh |
| resimg.hBitmap | = srcimg.hBitmap |
Return value
There is no return value.
Example C/C++ 1 | Example C/C++ 2 | Example VB
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function cover Lib "VIC32.DLL" (ByVal thresh As Long, srcimg As imgdes, oprimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int cover(int thresh, imgdes *srcimg, imgdes *oprimg, imgdes *resimg); |
| Java | int vic.vic32jni.cover(int thresh, imgdes srcimg, imgdes oprimg, imgdes resimg); |
Function Arguments
| thresh | Threshold (0-255) |
| srcimg | Source image |
| oprimg | Operator image |
| resimg | Result image |
Description
The cover function places a bright section of the operator image onto the source image. The source image can be thought of as providing a backdrop for the operator image. It is in the darker regions of the operator that the source shows through. Cover uses a threshold to determine if a source pixel shows through. Any operator pixel having a brightness level less than the threshold is replaced by the source pixel in the result area. The resulting image consists of the bright pixels of the operator with the source providing the background.
if Operator <= threshold then
For an RGB image the operator pixel value is calculated
The 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 | Threshold is outside the range 0 to 255 |
| 8 | 24 |
Function Prototypes
| Visual Basic | Declare Function coverclear Lib "VIC32.DLL" (ByVal transColorAs Long, srcimg As imgdes, oprimg As imgdes, resimg As imgdes) As Long |
| C/C++ | int coverclear(int transColor, imgdes *srcimg, imgdes *oprimg, imgdes *resimg); |
| Java | int vic.vic32jni.coverclear(int transColor, imgdes srcimg, imgdes oprimg, imgdes resimg); |
Function Arguments
| transColor | Transparent color(0-0xffffff) |
| srcimg | Source image |
| oprimg | Operator image |
| 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