New Type System for CVB’s DLL Interface

With CVB 2011 a new type system has been introduced for the DLL interface of Common Vision Blox, with the aim of being able to provide and use the same header files for the Win32, the Win64 and the Lin64 platform.

Prior to CVB 2011, the header files for the CVB DLLs have mostly been using the compilers’ built-in types like int, long etc. in the functions’ signatures.

This was working well enough because these built in types always had a fixed size and meaning on the Win32 platform.

With Win64 and Lin64 entering the image, things have gotten slightly more complex:

•Wherever we are looking at memory offsets, we now need a 64 bit value type on Win64, while on Win32 a 32 bit value type was and is still sufficient

•While C++’s long on Win64 still has the same meaning as on Win32, the compilers on Lin64 typically treat long as a 64 bit integer value

•Some types that are generally available on the Win32 platform and that have been used in CVB in the past are not usually defined on the Lin64 platform (e.g. HRESULT, GUID)

To compensate for these effects, we have come up with a type system that now replaces the use of the built-in types in the CVB header files.

The significant definitions are all located at the beginning of iCVCImg.h, where pre-processor statements branch into the Win32/Win64 and Lin64 sections.

The basic concept was to define and use the new types according to what they stand for instead of simply fixing the bit size of those types for the old and new platforms:

Type	sizeof Win32	sizeof Win64	sizeof Lin64	Rationale
cvbbool_t	4	4	1	Used for Boolean values and results. For backward compatibility this maps to BOOL on Win32 and Win64 instead of the built-in type bool.
cvbdatatype_t	4	4	4	Represents a CVB image plane’s data type identifier bit field as returned by the ImageDatatype function and used by CreateGenericImageDT.
cvbdensity_t	4	4	8	Represents a search density as used by the ScanImage/ScanPlane functions. Valid values range from 0 to 1000.
cvbdim_t	4	4	8	Represents an x, y or z coordinate in pixels/planes.
cvblicres_t	4	4	4	Result type for the (obsolete!) functions GetLicenseInfo and GetSerialNumber.
cvbres_t	4	4	4	Return type used by most CVB functions outside the CVCImg.dll. This type is interpreted similar to the Windows HRESULT: The most significant bit indicates an error condition, the remaining bits indicate the nature of the error (which is usually one of the values defined in CVCError.h).
cvbval_t	4	4	8	Generic integer value type where the actual amount of bits in the parameter is insignificant for the purposes where this type is being used.
cvbint64_t	8	8	8	Integer value type that is guaranteed to be 64 bits wide.
cvbuint64_t	8	8	8	Unsigned integer value type that is guaranteed to be 64 bits wide.
cvbint32_t	4	4	4	Integer value type that is guaranteed to be 32 bits wide.
cvbuint32_t	4	4	4	Unsigned integer value type that is guaranteed to be 32 bits wide.
cvbint16_t	2	2	2	Integer value type that is guaranteed to be 16 bits wide.
cvbuint16_t	2	2	2	Unsigned integer value type that is guaranteed to be 16 bits wide.
cvbint8_t	1	1	1	Integer value type that is guaranteed to be 8 bits wide.
cvbuint8_t	1	1	1	Unsigned integer value type that is guaranteed to be 8 bits wide.
cvbguid_t	16	16	16	Regular Universally Unique Identifier.

Platform-Polymorphic Types

Of course there are occasions where it is necessary to have a type that is precisely 32 bits wide on the 32 bit platform and 64 bits wide on the 64 bit platforms – think e.g. of the VPAT, where the offset entries can (and for compatibility reasons should) continue to be 32 bits wide on Win32 but where they should rather have 64 bits on Win64 and Lin64.

Luckily, the C++ standard already provides us with these types once the header stddef.h has been included in the form of the three types size_t, uintptr_t and intptr_t. Where appropriate, we have substituted long/int by these standard types rather than defined our own version of them.

Breaking Changes

While we did manage to achieve binary compatibility of the CVB DLLs between CVB 10.x and CVB 2011 on Win32, we did have to introduce some changes to function signatures that will break backward compatibility on the compiler level.

In other words: Some applications will need to be modified slightly before they will compile without errors with the headers shipped with CVB 2011.

The affected functions are:

•AnalyseXVPAT, AnalyseYVPAT and GetLinearAccess (iCVCUtilities.h)
These functions return memory increments by reference, and in response to the requirements of the 64 bit platforms the output parameters’ types have changed from long* to intptr_t*.
Please update the types used in your source code accordingly.

•Callbacks TFLine, TFPixelUnary, TFPixelBinary (iCVCImg.h)
The return type of these callbacks has changed from long to cvbbool_t because the original use of long here was ill-considered as, internally, the return type has always been evaluated in terms of a Boolean result. In order to pass the compiler’s type checks, the callbacks defined in your code need to be switched to cvbbool_t.

These examples refer to the Image Manager only.
There may be others in tools or in the Foundation Package, but generally your compiler will point this kind of problems out to you either by means of an error (if even implicit type conversion cannot fix the situation) or a warning (make sure to switch on Level 4 warnings and 64bit portability warnings in order to be alerted to all potential conflicts).