The Victor Image Processing Library and the device support modules are Dynamic Link Libraries (DLLs) and your programming language must be able to produce an application capable of calling functions contained in a DLL.
The Victor Image Processing Library for 32-bit Windows requires the presence of Windows NT/2000/XP or Windows 9x/ME. A 32-bit programming language is required to create a 32-bit Victor application.
Check your package to see if everything is there. If any items are missing, contact the retailer from whom you purchased the product. In the package you should find the following items:
| Registration card | Please fill out and mail the registration card or fill out the online registration card. | |
| Files | The file filelist.txt lists the description of all files in the Victor package. | |
| Victor User's Guide and Library Reference | This manual. |
Unzip all the downloaded files and place them in a new directory named \vicwin32.
For use with Visual Basic place VIC32.DLL and VICTW32.DLL in the subdirectory with the VB executable program, vb5.exe or vb6.exe. It is not necessary to register the Victor Library. It is not a COM object. It is not an ActiveX control. Double click on the VicDemo.exe icon to run VicDemo, the demonstration program.
The Victor Image Processing Library for Windows can be used to create applications for working with images in the Microsoft Windows environment.
Capabilities that can be built into a Windows application by using the Victor Library include:
These features are described in the pages that follow. The implementation is straightforward and easily accomplished by reading the function description and following the examples.
This manual was written with the assumption that you are generally familiar with Windows programming. Good elementary Windows programming texts are Programming Windows 95, by Charles Petzold, Microsoft Press 1996 and Advanced Windows NT, by Jeffrey Richter, Microsoft Press 1994.
The first section of this manual is the User's Guide and provides information necessary to successfully incorporate Victor functions into Windows programs. It should be read and understood.
The second section is the Library Reference which contains detailed information about all Victor functions.
Appendix A contains the summary of function return codes.
Additional Versions of the 32-bit Library
The standard Victor Library is a DLL that is statically linked with the C run time library. The library for 32-bit Windows is also available in two other forms -- all are multithread safe.
Contact Catenary Systems for information about these options.
The Victor package includes the source code for one Visual Basic and two C/C++ programs that run under 32-bit Windows.
Loadpic is a Visual Basic program to load and save, display, and print an image. It also includes Twain support to select a source and capture an image. Loadpic allows you to load and save bmp, gif, jpeg, png, and tiff files. It will automatically convert between file types as necessary.
This is the first program you should create using Visual Basic and the Victor Library to make sure VB can find all the necessary components.
Place the VIC32.DLL and VICTW32.DLL in the subdirectory with the VB executable program, vb6.exe.
LoadNSho is a simple program to load and display a single image. This is the first program you should compile using your C compiler and the Victor Library to make sure the compiler can find all the necessary components. Project files are included for Microsoft and Borland compilers.
VicDemo is a fully functional image processing program that can be used for scanning, printing, file conversion, and enhancing images.
VicDemo illustrates some of the features and functions available in the Victor Library, and provides practical examples of using Victor functions. It should be used as a guide in calling Victor routines in your applications.
For information about the VicDemo commands and image processing tips and techniques select the Help command. VicDemo has an extensive Help system describing the program and the library.
VicDemo is a multi-module program. The source code is provided. Refer to the project file to compile the modules and link the program.
Your application can call Victor functions as easily as it calls Windows functions, because the Victor Library for Windows is a dynamic link library (DLL).
There are three Victor Library components necessary for creating a C/C++ application: dynamic link libraries, import libraries, and the header file, VICDEFS.H.
DLLs contain the Victor functions called by your application during execution. All of the image handling functions are in a single DLL, VIC32.DLL.
TWAIN and support functions are contained in VICTW32.DLL. This DLL is only necessary if your application includes TWAIN device support.
| Victor 32-bit library | Contains |
| VIC32.DLL | Image handling functions |
| VICTW32.DLL | TWAIN support |
Import libraries are used with the C/C++ programming language only. The import library is linked to your application at compilation time and relates function calls to actual entry points in the corresponding DLL.
| Victor 32-bit import library | Contains |
| VIC32xx.LIB | Image handling functions |
| VCTW32xx.LIB | TWAIN support |
VICDEFS.H contains function declarations, data structure definitions, and error codes.
Follow these steps to create your application:
For additional information on compiling and linking your application see the README.DOC file.
Creating a Visual Basic Application
Place the VIC32.DLL and any other required dlls in the subdirectory with the VB executable program, vb6.exe. Before creating your own application using Victor functions, run the LOADPIC sample. This will ensure that VIC32.DLL, VICTW32.DLL, and the source files can be found by VB. To run LOADPIC, start VB, load the project file LOADPIC, and choose Run Start.
Follow these steps to create your own application:
For additional information on compiling and linking your application see the VBREAD.DOC file.
Creating an App with Unicode Support
To create a C/C++ application with Unicode support place the following two lines at the top of each source file:
#include <tchar.h> #define UNICODE TRUE
(Normally, you would also #define _UNICODE TRUE for proper Unicode string handling in your app.)
This will cause the Unicode version of Victor functions to be used. If Unicode is defined it is not possible to use the ANSI version of a Victor function, the Unicode version will always be used.
Or you may call the Unicode version of the Victor function directly. The Unicode version of a Victor function has a "W" appended to the end of the function name. For example, bmpinfo takes an ANSI string as the first argument, and bmpinfoW takes a Unicode character string as the first argument.
Windows can be a difficult environment to program under. If you have problems using Victor functions in your application you may benefit from the following suggestions.
If a Victor function returns a value other than NO_ERROR or the function doesn't behave as you expect it to, examine the data being sent to the function:
imgdes *imagePtr; // This is wrong allocimage(imagePtr, 640, 480, 8);
The function allocimage fills in the elements of the image descriptor, but since imagePtr was not initialized, this data is written to random memory. As a result the program will probably crash.
The correct code is:
imgdes image; // This is correct allocimage(&image, 640, 480, 8);
In this case the image descriptor has been properly defined and space for the image descriptor elements reserved.
Visit the website http://www.catenary.com for more code examples of using Victor to accomplish various tasks. Select Sample Code.
If you need additional assistance using the Victor Library you may contact Catenary Systems for technical support during normal business hours 8 am to 5 pm (USA Central Time) Monday through Friday:
voice: (314) 962-7833
fax: (314) 962-8037
e-mail: support@catenary.com
url: www.catenary.com
Device Independent Bitmap (DIB) Review
Victor Library functions operate on an image stored in memory as an uncompressed Device IndependentBitmap (DIB).
The Microsoft Windows version 3.1 Programmer's Reference (Vol 3, p 236) defines a DIB as follows:
"A Windows DIB consists of two distinct parts: a BITMAPINFO structure, which describes the dimensions and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits in the array are packed together, but each scan line must be zero-padded to end on a LONG boundary. Segment boundaries, however, can appear anywhere in the bitmap. The origin of the bitmap is the lower-left corner."
A DIB provides a uniform format for moving bitmaps between different devices. Windows uses a DIB to create a bitmap or display image data on a display device.
The DIB is composed of header, palette, and pixel data. There are two forms of DIB, the original packed DIB and the newer DIB Section. Victor functions operate on both types.
The original packed DIB format has all the image data together in a single contiguous block of memory. The packed DIB is used when a DIB is placed in the Windows clipboard and the data is referred to as type CF_DIB. This was the only type of DIB available in 16-bit Windows
The DIB Section is only available in 32-bit Windows and has the header and palette data in one memory location while the pixel data reside in another location. This DIB format also includes a bitmap handle that makes the DIB usable with the Windows graphics functions.
How Victor Images Differ from Windows DIBs
Victor functions operate on a subset of Windows DIBs. The differences lie in compression, bits per pixel, and palette.
The Image Descriptor Defined
Victor's most important data structure is the image descriptor. All of the information necessary for a Victor function to operate on an image area is contained in the image descriptor data structure that describes that image. The image descriptor is defined in VICDEFS.H as type imgdes and is a required argument for most Victor functions. The image descriptor is defined as follows:
typedef struct {
unsigned char huge *ibuff; Image buffer address
unsigned stx, sty, endx, endy; Image area of interest
unsigned buffwidth; Image buffer width in bytes
RGBQUAD far *palette; Palette address
int colors; Number of palette colors
int imgtype; Image type: bit 0 = 1
if image is grayscale
BITMAPINFOHEADER far *bmh; BITMAPINFOHEADER address
HBITMAP hBitmap; Device Independent Bitmap handle
} imgdes;
The Elements of the Image Descriptor
The origin of the bitmap is the lower-left corner. This means that the address ibuff represents is
the first pixel in the last row of image data as viewed on the screen.
stx, sty, endx, endy
| Bits per pixel | Maximum palette colors | |
|
|
1 | 2 |
|
|
8 | 256 |
|
|
16 | 0 |
|
|
24 | 0 |
typedef struct tagBITMAPINFO {
BITMAPINFOHEADER bmiHeader;
RGBQUAD bmiColors[1];
} BITMAPINFO;
typedef struct tagBITMAPINFOHEADER {
DWORD biSize;
DWORD biWidth;
DWORD biHeight;
WORD biPlanes;
WORD biBitCount;
DWORD biCompression;
DWORD biSizeImage;
DWORD biXPelsPerMeter;
DWORD biYPelsPerMeter;
DWORD biClrUsed;
DWORD biClrImportant;
} BITMAPINFOHEADER;
A nonzero value of hBitmap indicates that the image is a DIB section. A value of zero indicates that the image is a packed DIB.