Image Manager (CVCUtilities.dll) 14.1
System Information Functions

Functions

cvbbool_t GetCVBDataDirectory (char *DataDirectory, size_t Length)
 Retrieves the path to the Common Vision Blox data directory. More...
 
cvbbool_t GetCVBDataDirectoryW (wchar_t *DataDirectory, size_t Length)
 Retrieves the path to the Common Vision Blox data directory. More...
 
cvbbool_t GetCVBDirectory (char *Directory, size_t Length)
 Retrieves the path to the Common Vision Blox root directory. More...
 
cvbbool_t GetCVBDirectoryW (wchar_t *Directory, size_t Length)
 Retrieves the path to the Common Vision Blox root directory. More...
 
cvbbool_t GetCVBVersion (char *Version, size_t Length)
 Returns the version number of the Common Vision Blox Image Manager as a string. More...
 
cvbbool_t GetCVBVersionEx (char *Version, size_t &Length, CVB_OS_INFO &OSinstalledFor, CVB_OS_INFO &OSCurrent)
 Returns the version number of the Common Vision Blox Image Manager as a string and information about the operating system. More...
 
cvbbool_t GetDefaultImageFile (char *DefaultImageFile, size_t Length)
 Retrieves the currently set value in the "Default Image File" setting in the Common Vision Blox registry key. More...
 
cvbbool_t GetDefaultTimeout (cvbval_t &Value)
 Gets the currently set default acquisition timeout in milliseconds for *.vin-drivers. More...
 
cvbbool_t GetFileVersion (const char *Filename, char *Version, char *Company, cvbval_t Length)
 Returns version information of a given file. More...
 
cvbbool_t GetFileVersionW (const wchar_t *Filename, wchar_t *Version, wchar_t *Company, cvbval_t Length)
 Returns version information of a given file. More...
 
cvbbool_t GetGlobalAsyncACQEnabled (cvbbool_t &Value)
 Retrieves the current value of the "Global AsyncACQ Enabled" setting from the Common Vision Blox key in the Windows registry. More...
 
cvbbool_t GetGlobalDirectDrawEnabled (cvbbool_t &value)
 Reads the state of the "Global DirectDraw Enabled" setting from the Common Vision Blox registry key. More...
 
cvbbool_t GetGlobalPingPongEnabled (cvbbool_t &Value)
 Reads the current state of the "Global PingPong Enabled" setting from the Common Vision Blox registry key. More...
 
cvbbool_t GetLicenseFile (char *LicenseFile, size_t Length)
 Returns the path to the Common Vision Blox license file (usually License.ini) in which tool magic numbers may be stored. More...
 
cvbbool_t GetLoadDefaultImageFile (cvbbool_t &Value)
 Retrieves the currently set value in the "Load Default Image File" setting in the Common Vision Blox registry key. More...
 
cvbbool_t GetManualDisplayRefreshEnabled (cvbbool_t &Value)
 Retrieves the current value of the "Manual Display Refresh Enabled" setting in the Common Vision Blox key of the Windows registry. More...
 
cvbbool_t GetSnapOnLoadDriver (cvbbool_t &Value)
 Retrieves the current value of the "Snap Image On Load Driver" flag from the Common Vision Blox key in the Windows registry. More...
 
cvbres_t IsPre8MTS (const char *MTSFileName, cvbbool_t &IsPre8)
 Checks whether the MTS format is from a Common Vision Blox version prior to CVB 8.0. More...
 
cvbres_t IsPre8MTSW (const wchar_t *MTSFileName, cvbbool_t &IsPre8)
 Checks whether the MTS format is from a Common Vision Blox version prior to CVB 8.0. More...
 
cvbbool_t SetDefaultImageFile (const char *DefaultFile)
 Sets the value in the "Default Image File" setting in the Common Vision Blox registry key. More...
 
cvbbool_t SetDefaultTimeout (cvbval_t Value)
 Sets the default acquisition timeout in milliseconds for *.vin-drivers. More...
 
cvbbool_t SetGlobalAsyncACQEnabled (cvbbool_t Value)
 Sets the value of the "Global AsyncACQ Enabled" setting in the Common Vision Blox key in the Windows registry. More...
 
cvbbool_t SetGlobalDirectDrawEnabled (cvbbool_t value)
 Sets the state of the "Global DirectDraw Enabled" setting in the Common Vision Blox registry key. More...
 
cvbbool_t SetGlobalPingPongEnabled (cvbbool_t Value)
 Sets the value of the "Global PingPong Enabled" setting in the Common Vision Blox registry key. More...
 
cvbbool_t SetLoadDefaultImageFile (cvbbool_t Value)
 Retrieves the current value of the "Load Default Image File" setting in the Common Vision Blox registry key. More...
 
cvbbool_t SetManualDisplayRefreshEnabled (cvbbool_t value)
 Sets the value of the "Manual Display Refresh Enabled" setting in the Common Vision Blox key of the Windows registry. More...
 
cvbbool_t SetSnapOnLoadDriver (cvbbool_t Value)
 Sets the value of the "Snap Image On Load Driver" flag in the Common Vision Blox key in the Windows registry. More...
 
cvbbool_t TranslateFileName (const char *FileNameIn, char *FileNameOut, size_t OutLength)
 Replaces environment variables in a string and copies the result. More...
 
cvbbool_t TranslateFileNameW (const wchar_t *FileNameIn, wchar_t *FileNameOut, size_t OutLength)
 Replaces environment variables in a string and copies the result. More...
 

Detailed Description

Function Documentation

◆ GetCVBDataDirectory()

cvbbool_t GetCVBDataDirectory ( char *  DataDirectory,
size_t  Length 
)

Retrieves the path to the Common Vision Blox data directory.

This function basically returns the current value of the environment variable CVBDATA% created by the Common Vision Blox installer. It may therefore also be substituted with code like this:

auto dir = getenv("CVBDATA") // attention: return value may be NULL!

Under Windows Vista and later the data directory is located in %SystemDrive%\ProgramData\STEMMER IMAGING\Common Vision Blox. Under older versions of Windows the Common Vision Blox data directory used to be identical to the Common Vision Blox root directory.

The Common Vision Blox data directory is commonly used for storing application settings that need to be editable by regular (i.e. non-admin) users.

Parameters
[in]DataDirectoryBuffer to be filled with the path to the CVB data directory.
[in]LengthLength of the buffer pointed to by DataDirectory in characters. This function will copy no more than Length - 1 characters plus a terminating zero to the buffer. If the buffer is not sufficiently big for the entire path, the path will be truncated without further notice, so please provide a sufficiently big buffer.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
TranslateFileName, TranslateFileNameW, GetCVBDataDirectoryW
Sample Code in Delphi:
procedure DoSth;
var Dir: arry [0..259] of AnsiChar;
cvbbool_t GetCVBDataDirectory(char *DataDirectory, size_t Length)
Retrieves the path to the Common Vision Blox data directory.
Definition: CVCUtilities.cpp:2225
Sample Code in C++:
char dataDir[_MAX_PATH] = { 0 };
GetCVBDataDirectory(dataDir, _MAX_PATH);

◆ GetCVBDataDirectoryW()

cvbbool_t GetCVBDataDirectoryW ( wchar_t *  DataDirectory,
size_t  Length 
)

Retrieves the path to the Common Vision Blox data directory.

This function basically returns the current value of the environment variable CVBDATA% created by the Common Vision Blox installer. It may therefore also be substituted with code like this:

auto dir = _wgetenv(L"CVBDATA") // attention: return value may be NULL!

Under Windows Vista and later the data directory is located in %SystemDrive%\ProgramData\STEMMER IMAGING\Common Vision Blox. Under older versions of Windows the Common Vision Blox data directory used to be identical to the Common Vision Blox root directory.

The Common Vision Blox data directory is commonly used for storing application settings that need to be editable by regular (i.e. non-admin) users.

Since
Common Vision Blox 13.00.000
Parameters
[in]DataDirectoryBuffer to be filled with the path to the CVB data directory.
[in]LengthLength of the buffer pointed to by DataDirectory in characters. This function will copy no more than Length - 1 characters plus a terminating zero to the buffer. If the buffer is not sufficiently big for the entire path, the path will be truncated without further notice, so please provide a sufficiently big buffer.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
TranslateFileName, TranslateFileNameW, GetCVBDataDirectoryW
Sample Code in C++:
wchar_t dataDir[_MAX_PATH] = { 0 };
GetCVBDataDirectoryW(dataDir, _MAX_PATH);
cvbbool_t GetCVBDataDirectoryW(wchar_t *DataDirectory, size_t Length)
Retrieves the path to the Common Vision Blox data directory.
Definition: CVCUtilities.cpp:2290

◆ GetCVBDirectory()

cvbbool_t GetCVBDirectory ( char *  Directory,
size_t  Length 
)

Retrieves the path to the Common Vision Blox root directory.

Under Windows this function reads a registry key created by the Common Vision Blox installer. Under Linux the CVB environment variable is queried. Of course the latter would be possible on the Windows platform as well, therefore the following code would work as well:

auto cvbdir = getenv("CVB"); // attention: may return NULL!

As an alternative, in some situations it is possible to use the environment variable CVB% directly, for example when calling the LoadImage method of the Image Control:

CVimage.LoadImage("%CVB%\\Tutorial\\bracket.bmp");
Parameters
[in]DirectoryBuffer to be filled with the path to the CVB root directory.
[in]LengthLength of the buffer pointed to by Directory in characters. This function will copy no more than Length - 1 characters plus a terminating zero to the buffer. If the buffer is not sufficiently big for the entire path, the path will be truncated without further notice, so please provide a sufficiently big buffer.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetCVBDirectoryW, GetCVBDataDirectory, TranslateFileName
Sample Code in Delphi:
procedure Demo;
var CvbDirectory: array [0..260] of AnsiChar;
begin
GetCVBDirectory(CvbDirectory, 260);
end;
cvbbool_t GetCVBDirectory(char *Directory, size_t Length)
Retrieves the path to the Common Vision Blox root directory.
Definition: CVCUtilities.cpp:1734
Sample Code in C++:
char directory[_MAX_PATH] = { 0 };
GetCVBDirectory(directory, _MAX_PATH);

◆ GetCVBDirectoryW()

cvbbool_t GetCVBDirectoryW ( wchar_t *  Directory,
size_t  Length 
)

Retrieves the path to the Common Vision Blox root directory.

Under Windows this function reads a registry key created by the Common Vision Blox installer. Under Linux the CVB environment variable is queried. Of course the latter would be possible on the Windows platform as well, therefore the following code would work as well:

auto cvbdir = _wgetenv(L"CVB"); // attention: may return NULL!

As an alternative, in some situations it is possible to use the environment variable CVB% directly, for example when calling the LoadImage method of the Image Control:

CVimage.LoadImage(L"%CVB%\\Tutorial\\bracket.bmp");
Since
Common Vision Blox 13.00.000
Parameters
[in]DirectoryBuffer to be filled with the path to the CVB root directory.
[in]LengthLength of the buffer pointed to by Directory in characters. This function will copy no more than Length - 1 characters plus a terminating zero to the buffer. If the buffer is not sufficiently big for the entire path, the path will be truncated without further notice, so please provide a sufficiently big buffer.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetCVBDataDirectory, TranslateFileName
Sample Code in C++:
wchar_t directory[_MAX_PATH] = { 0 };
GetCVBDirectoryW(directory, _MAX_PATH);
cvbbool_t GetCVBDirectoryW(wchar_t *Directory, size_t Length)
Retrieves the path to the Common Vision Blox root directory.
Definition: CVCUtilities.cpp:1798

◆ GetCVBVersion()

cvbbool_t GetCVBVersion ( char *  Version,
size_t  Length 
)

Returns the version number of the Common Vision Blox Image Manager as a string.

The Windows version of this function reads the Common Vision Blox version from the Common Vision Blox registry key (as stored there by the Common Vision Blox installer). The Linux version returns a string that has been defined during the build process of the CVCUtilities.dll.

Parameters
[in]VersionBuffer to be filled with the version string.
[in]LengthThe length of the buffer pointed to by Version. This function will write no more than Length characters to that buffer. If the buffer has not been allocated big enough the version string will be truncated. Buffer sizes of 10 characters are usually sufficient.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetFileVersion

◆ GetCVBVersionEx()

cvbbool_t GetCVBVersionEx ( char *  Version,
size_t &  Length,
CVB_OS_INFO OSinstalledFor,
CVB_OS_INFO OSCurrent 
)

Returns the version number of the Common Vision Blox Image Manager as a string and information about the operating system.

The part of the function that fills the Version buffer works identical to the function GetCVBVersion. In addition to what GetCVBVersion does, \ GetCVBVersionEx will return information about the operating system and CPU architecture as defined in the CVB_OS_INFO enumeration.

Parameters
[in]VersionBuffer to be filled with the version string. Version may be NULL, in which case no version information will be returned. Instead, Length will receive the number of characters necessary to store the version information.
[in,out]LengthThe length of the buffer pointed to by Version. The function will cover Length characters (or the whole version string - whichever is smaller) into the buffer pointed to by Value. When returning, Length will contain the number of actually written characters (or the required buffer length, if Value was NULL).
[out]OSinstalledForArchitecture and operating system for which the CVCUtilities.dll was built.
[out]OSCurrentOperating system under which the calling program is currently running.
Returns
TRUE if successful, FALSE otherwise.

◆ GetDefaultImageFile()

cvbbool_t GetDefaultImageFile ( char *  DefaultImageFile,
size_t  Length 
)

Retrieves the currently set value in the "Default Image File" setting in the Common Vision Blox registry key.

By default, the value "Default Image File" will not be set and an empty string will be returned.

If set to a value that provides the path to an existing and valid image file and if the "Load Default Image File" setting is TRUE (see GetLoadDefaultImageFile and SetLoadDefaultImageFile) this image file will automatically loaded into all newly instantiated Image Controls (unless they did serialize a valid FileName property at design time, in which case that file will be loaded instead).

This function is only available on the Windows platform.

This setting is also accessible through the "General" section in the Common Vision Blox Management Console.

Parameters
[in]DefaultImageFileBuffer to be filled with the current value of the "Default Image File" setting.
[in]LengthThe length of the buffer pointed to by DefaultFile. This function will copy at most Length bytes; if that is not sufficient for copying the entire file name, the file name will be truncated.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
SetDefaultImageFile, GetLoadDefaultImageFile, SetLoadDefaultImageFile

◆ GetDefaultTimeout()

cvbbool_t GetDefaultTimeout ( cvbval_t &  Value)

Gets the currently set default acquisition timeout in milliseconds for *.vin-drivers.

All *.vin drivers, when loaded, should come up with the timeout that has been set as the default timeout (unless the value that has been set as the default timeout is incompatible with the acquisition device).

The Windows implementation of this function will read the default timeout from the setting "Default Timeout" in the Common Vision Blox key in the Windows registry.

The Linux implementation currently uses a fixed value. This may change in future versions.

Parameters
[out]ValueCurrently used default acquisition timeout in milliseconds.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
SetDefaultTimeout

◆ GetFileVersion()

cvbbool_t GetFileVersion ( const char *  Filename,
char *  Version,
char *  Company,
cvbval_t  Length 
)

Returns version information of a given file.

The file's version data is returned as a set of strings. This function will not copy more than Length bytes to the output buffers. Typically, 256 bytes will do.

Under Windows this function returns the version information stored in the version resource of any PE file. If called on a file without version information it will return false. Under Linux the result of calling this function will always be false.

Parameters
[in]FilenameFile for which to retrieve the version information.
[out]VersionBuffer that will receive the version information.
[out]CompanyBuffer that will receive the manufacturer information.
[in]LengthLength of the buffers pointed to by Version and Company (both buffers will need to have identical size.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetCVBVersion
C++ Example
#include <iostream>
#include <iomanip>
#include <iCVCUtiltities.h>
static const cvbval_t STRINGLEN = 256;
void print_version_info(const char *filename)
{
char version[STRINGLEN] = { 0 };
char company[STRINGLEN] = { 0 };
if (GetFileVersion(filename, version, company, STRINGLEN))
{
std::cout << filename << " from " << company << ", version " << version << std::endl;
}
else
{
std::cout << filename << " (no version information found!)" << std::endl;
}
}
cvbbool_t GetFileVersion(const char *Filename, char *Version, char *Company, cvbval_t Length)
Returns version information of a given file.
Definition: FileVersion.cpp:243

◆ GetFileVersionW()

cvbbool_t GetFileVersionW ( const wchar_t *  Filename,
wchar_t *  Version,
wchar_t *  Company,
cvbval_t  Length 
)

Returns version information of a given file.

The file's version data is returned as a set of strings. This function will not copy more than Length bytes to the output buffers. Typically, 256 bytes will do.

Under Windows this function returns the version information stored in the version resource of any PE file. If called on a file without version information it will return false. Under Linux the result of calling this function will always be false.

Since
Common Vision Blox 13.00.000
Parameters
[in]FilenameFile for which to retrieve the version information.
[out]VersionBuffer that will receive the version information.
[out]CompanyBuffer that will receive the manufacturer information.
[in]LengthLength of the buffers pointed to by Version and Company (both buffers will need to have identical size.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetCVBVersion
C++ Example
#include <iostream>
#include <iomanip>
#include <iCVCUtiltities.h>
static const cvbval_t STRINGLEN = 256;
void print_version_info(const wchar *filename)
{
wchar version[STRINGLEN] = { 0 };
wchar company[STRINGLEN] = { 0 };
if (GetFileVersionW(filename, version, company, STRINGLEN))
{
std::wcout << filename << L" from " << company << L", version " << version << std::endl;
}
else
{
std::wcout << filename << L" (no version information found!)" << std::endl;
}
}
cvbbool_t GetFileVersionW(const wchar_t *Filename, wchar_t *Version, wchar_t *Company, cvbval_t Length)
Returns version information of a given file.
Definition: FileVersion.cpp:326

◆ GetGlobalAsyncACQEnabled()

cvbbool_t GetGlobalAsyncACQEnabled ( cvbbool_t &  Value)

Retrieves the current value of the "Global AsyncACQ Enabled" setting from the Common Vision Blox key in the Windows registry.

The "Global AsyncACQ Enabled" setting controls how the Image Control propagates the ImageSnaped event to the user. If the setting is set to false the Image Control processes the ImageSnaped event from within the control's user interface thread, whereas if it is set to true processing will take place in the control's acquisition thread.

Attention
This has significant implications:
  • if "Global AsyncACQ Enabled" is set to true, no user interface component should be touched/updated from within the processing inside ImageSnaped directly as this will lead to undefined behavior (most virtually all commonly used UI toolkits are not thread-safe).
    If a user interface object needs to be updated from within ImageSnaped while "Global AsyncACQ Enabled" is true it must* be done via SendMessage or PostMessage (Invoke or BeginInvoke in Windows Forms applications).
  • Setting the "Global AsyncACQ Enabled" flat to true will automatically lead to asynchronous processing - which implicitly that the code inside the ImageSnaped handler (and the code invoked by it) needs to be thread-safe.
  • Setting this flag to true will render some of the Common Vision Blox tutorials inoperable as they have not been adapted to the requirements stated earlier.

This function is only available on the Windows platform.

Parameters
[out]ValueTRUE if "Global AsyncACQ Enabled" is set to a value other than zero in the registry, FALSE otherwise.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
SetGlobalAsyncACQEnabled, multi-threading

◆ GetGlobalDirectDrawEnabled()

cvbbool_t GetGlobalDirectDrawEnabled ( cvbbool_t &  value)

Reads the state of the "Global DirectDraw Enabled" setting from the Common Vision Blox registry key.

The "Global DirectDraw Enabled" flag from the Common Vision Blox key in the Windows registry may be used to globally suppress/allow the use of DirectDraw on a system. While set to false (0) no Display Control instantiated will be able to use DirectDraw.

Attention
This flag is no indication of whether or not use of DirectDraw is technically possible (see CanCVBDirectDraw for this). It is merely informing about whether or not use of DirectDraw is permitted.

This setting is also accessible through the "General" section in the Common Vision Blox Management Console.

This function is only available on the Windows platform.

Parameters
[out]valueTRUE indicates that the use of direct draw is generally permitted, FALSE indicates that the use of DirectDraw is globally suppressed..
Returns
TRUE if successful, FALSE otherwise.
Related Topics
SetGlobalDirectDrawEnabled, CanCVBDirectDraw, DirectDrawEnabled property of the Display ActiveX control, Important Considerations when using Direct Draw

◆ GetGlobalPingPongEnabled()

cvbbool_t GetGlobalPingPongEnabled ( cvbbool_t &  Value)

Reads the current state of the "Global PingPong Enabled" setting from the Common Vision Blox registry key.

The "Global PingPong Enabled" flag from the Common Vision Blox key in the Windows registry may be used to globally suppress/allow the use of PingPong on a system. While set to false (0) no Image Control instantiated will be able to use PingPong acquisition (i.e. asynchronous acquisition through the IGrab2 interface); instead the control will resort to using single snaps.

This setting is also accessible through the "General" section in the Common Vision Blox Management Console.

This function is only available on the Windows platform.

Parameters
[out]ValueTRUE indicates that the use of PingPong acquisition is generally permitted, FALSE indicates that the use of PingPong acquisition is globally suppressed.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
SetGlobalPingPongEnabled, PingPongEnabled property of the CV Image ActiveX control

◆ GetLicenseFile()

cvbbool_t GetLicenseFile ( char *  LicenseFile,
size_t  Length 
)

Returns the path to the Common Vision Blox license file (usually License.ini) in which tool magic numbers may be stored.

The Windows version of this function will read the returned information from the Common Vision Blox key in the Windows registry (value "License File"). The Linux version will simply return false (this behavior may change in future versions).

Parameters
[in]LicenseFileBuffer to be filled with the CVB license file path.
[in]LengthThe length of the buffer pointed to be LicenseFile in characters. No more than Length characters will be written to the buffer. If the buffer is not big enough for the path to be written to it the path will simply be truncated without further notice, so make sure to provide a sufficiently big buffer.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
CVB software protection concept

◆ GetLoadDefaultImageFile()

cvbbool_t GetLoadDefaultImageFile ( cvbbool_t &  Value)

Retrieves the currently set value in the "Load Default Image File" setting in the Common Vision Blox registry key.

If this flag is true, the Image ActiveX control loads a default image on initialization if one has been set in the "Default Image File" entry (see SetDefaultImageFile and GetDefaultImageFile).

This setting is also accessible through the "General" section in the Common Vision Blox Management Console.

This function is only available on the Windows platform.

Parameters
[out]ValueTRUE indicates that the Image Control will try to load a default image when initialize, FALSE indicates that this will not happen.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
SetLoadDefaultImageFile, SetDefaultImageFile, GetDefaultImageFile

◆ GetManualDisplayRefreshEnabled()

cvbbool_t GetManualDisplayRefreshEnabled ( cvbbool_t &  Value)

Retrieves the current value of the "Manual Display Refresh Enabled" setting in the Common Vision Blox key of the Windows registry.

The "Manual Display Refresh Enabled" setting defines the default value for the ManualDisplayRefresh property of newly created Display Controls.

This function is only available on the Windows platform.

Parameters
[out]ValueThe current value of the "Manual Display Refresh Enabled" registry setting.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
SetManualDisplayRefreshEnabled

◆ GetSnapOnLoadDriver()

cvbbool_t GetSnapOnLoadDriver ( cvbbool_t &  Value)

Retrieves the current value of the "Snap Image On Load Driver" flag from the Common Vision Blox key in the Windows registry.

If this flag is set to true then the Image Control will execute a Snap call (CVCDriver.dll) whenever an image with an IGrabber interface has been newly loaded.

The "Snap Image On Load Driver" setting is also accessible through the Common Vision Blox Management Console.

This function is only available on the Windows platform.

Parameters
[out]ValueTRUE if the registry setting is set to a value other than 0, FALSE otherwise.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
SetSnapOnLoadDriver

◆ IsPre8MTS()

cvbres_t IsPre8MTS ( const char *  MTSFileName,
cvbbool_t &  IsPre8 
)

Checks whether the MTS format is from a Common Vision Blox version prior to CVB 8.0.

Starting with CVB 8.0.0 the file format of MTS files has changed slightly due to the switch from the Delphi-based Image Manager to the C++ based one. This introduced compatibility problems. For the Minos versions included in CVB 8.0.0 and newer, it is no problem to read and use MTS files from older versions of Minos (in fact it will silently convert them into the new format). However, the Minos versions shipped prior to CVB 8.0.0 will not be able to read MTS files generated with a newer version of Minos.

To prevent potential problems arising from the automatic conversion into the new file format, function IsPre8MTS has been introduced in Common Vision Blox CVB 8.0.2. Call this function on an MTS file to find out, whether or not it has been generated with an older version.

Mind that although the MTS file will be analyzed, it will not actually be verified to be an MTS file, so make sure to provide only MTS files here to get useful information.

Parameters
[in]MTSFileNameName of the MTS file to be analyzed.
[out]IsPre8Will be set to TRUE if the file pointed to by FileName has been generated with a version of Minos shipped prior to CVB 8.0.0, FALSE otherwise.
Returns
cvbres_t - less than zero on error.

◆ IsPre8MTSW()

cvbres_t IsPre8MTSW ( const wchar_t *  MTSFileName,
cvbbool_t &  IsPre8 
)

Checks whether the MTS format is from a Common Vision Blox version prior to CVB 8.0.

Starting with CVB 8.0.0 the file format of MTS files has changed slightly due to the switch from the Delphi-based Image Manager to the C++ based one. This introduced compatibility problems. For the Minos versions included in CVB 8.0.0 and newer, it is no problem to read and use MTS files from older versions of Minos (in fact it will silently convert them into the new format). However, the Minos versions shipped prior to CVB 8.0.0 will not be able to read MTS files generated with a newer version of Minos.

To prevent potential problems arising from the automatic conversion into the new file format, function IsPre8MTS has been introduced in Common Vision Blox CVB 8.0.2. Call this function on an MTS file to find out, whether or not it has been generated with an older version.

Mind that although the MTS file will be analyzed, it will not actually be verified to be an MTS file, so make sure to provide only MTS files here to get useful information.

Since
Common Vision Blox 13.00.000
Parameters
[in]MTSFileNameName of the MTS file to be analyzed.
[out]IsPre8Will be set to TRUE if the file pointed to by FileName has been generated with a version of Minos shipped prior to CVB 8.0.0, FALSE otherwise.
Returns
cvbres_t - less than zero on error.

◆ SetDefaultImageFile()

cvbbool_t SetDefaultImageFile ( const char *  DefaultFile)

Sets the value in the "Default Image File" setting in the Common Vision Blox registry key.

If set to a value that provides the path to an existing and valid image file and if the "Load Default Image File" setting is TRUE (see GetLoadDefaultImageFile and SetLoadDefaultImageFile) this image file will automatically loaded into all newly instantiated Image Controls (unless they did serialize a valid FileName property at design time, in which case that file will be loaded instead).

This function is only available on the Windows platform.

This setting is also accessible through the "General" section in the Common Vision Blox Management Console.

Attention
An application calling this function must run with sufficient privileges to write to Common Vision Blox registry key. Unless the access rights in the registry have been modified or UAC has been disabled admin privileges will be required for this.
Parameters
[in]DefaultFileValue to be set in the registry. Provide an empty string to not use this feature.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
SetDefaultImageFile, GetLoadDefaultImageFile, SetLoadDefaultImageFile

◆ SetDefaultTimeout()

cvbbool_t SetDefaultTimeout ( cvbval_t  Value)

Sets the default acquisition timeout in milliseconds for *.vin-drivers.

All *.vin drivers, when loaded, should come up with the timeout that has been set as the default timeout (unless the value that has been set as the default timeout is incompatible with the acquisition device).

The Windows implementation of this function will write the default timeout to the setting "Default Timeout" in the Common Vision Blox key in the Windows registry.

The Linux implementation currently always returns false. This may change in future versions.

Parameters
[out]ValueValue to be used as the default acquisition timeout in milliseconds.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetDefaultTimeout

◆ SetGlobalAsyncACQEnabled()

cvbbool_t SetGlobalAsyncACQEnabled ( cvbbool_t  Value)

Sets the value of the "Global AsyncACQ Enabled" setting in the Common Vision Blox key in the Windows registry.

The "Global AsyncACQ Enabled" setting controls how the Image Control propagates the ImageSnaped event to the user. If the setting is set to false the Image Control processes the ImageSnaped event from within the control's user interface thread, whereas if it is set to true processing will take place in the control's acquisition thread.

Attention
This has significant implications:
  • if "Global AsyncACQ Enabled" is set to true, no user interface component should be touched/updated from within the processing inside ImageSnaped directly as this will lead to undefined behavior (most virtually all commonly used UI toolkits are not thread-safe).
    If a user interface object needs to be updated from within ImageSnaped while "Global AsyncACQ Enabled" is true it must* be done via SendMessage or PostMessage (Invoke or BeginInvoke in Windows Forms applications).
  • Setting the "Global AsyncACQ Enabled" flat to true will automatically lead to asynchronous processing - which implicitly that the code inside the ImageSnaped handler (and the code invoked by it) needs to be thread-safe.
  • Setting this flag to true will render some of the Common Vision Blox tutorials inoperable as they have not been adapted to the requirements stated earlier.
An application calling this function must run with sufficient privileges to write to Common Vision Blox registry key. Unless the access rights in the registry have been modified or UAC has been disabled admin privileges will be required for this.

This function is only available on the Windows platform.

Parameters
[out]ValueValue to set in the registry setting.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetGlobalAsyncACQEnabled, multi-threading

◆ SetGlobalDirectDrawEnabled()

cvbbool_t SetGlobalDirectDrawEnabled ( cvbbool_t  value)

Sets the state of the "Global DirectDraw Enabled" setting in the Common Vision Blox registry key.

The "Global DirectDraw Enabled" flag from the Common Vision Blox key in the Windows registry may be used to globally suppress/allow the use of DirectDraw on a system. While set to false (0) no Display Control instantiated will be able to use DirectDraw.

This setting is also accessible through the "General" section in the Common Vision Blox Management Console.

This function is only available on the Windows platform.

Attention
An application calling this function must run with sufficient privileges to write to Common Vision Blox registry key. Unless the access rights in the registry have been modified or UAC has been disabled admin privileges will be required for this.
Parameters
[in]valueTRUE indicates that the use of direct draw is generally permitted, FALSE indicates that the use of DirectDraw is globally suppressed..
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetGlobalDirectDrawEnabled, CanCVBDirectDraw, DirectDrawEnabled property of the Display ActiveX control, Important Considerations when using Direct Draw

◆ SetGlobalPingPongEnabled()

cvbbool_t SetGlobalPingPongEnabled ( cvbbool_t  Value)

Sets the value of the "Global PingPong Enabled" setting in the Common Vision Blox registry key.

The "Global PingPong Enabled" flag from the Common Vision Blox key in the Windows registry may be used to globally suppress/allow the use of PingPong on a system. While set to false (0) no Image Control instantiated will be able to use PingPong acquisition (i.e. asynchronous acquisition through the IGrab2 interface); instead the control will resort to using single snaps.

This setting is also accessible through the "General" section in the Common Vision Blox Management Console.

Attention
An application calling this function must run with sufficient privileges to write to Common Vision Blox registry key. Unless the access rights in the registry have been modified or UAC has been disabled admin privileges will be required for this.

This function is only available on the Windows platform.

Parameters
[in]ValueValue to be set.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetGlobalPingPongEnabled, PingPongEnabled property of the CV Image ActiveX control

◆ SetLoadDefaultImageFile()

cvbbool_t SetLoadDefaultImageFile ( cvbbool_t  Value)

Retrieves the current value of the "Load Default Image File" setting in the Common Vision Blox registry key.

If this flag is true, the Image ActiveX control loads a default image on initialization if one has been set in the "Default Image File" entry (see SetDefaultImageFile and GetDefaultImageFile).

This setting is also accessible through the "General" section in the Common Vision Blox Management Console.

This function is only available on the Windows platform.

Attention
An application calling this function must run with sufficient privileges to write to Common Vision Blox registry key. Unless the access rights in the registry have been modified or UAC has been disabled admin privileges will be required for this.
Parameters
[in]ValueTRUE indicates that the Image Control will try to load a default image when initialize, FALSE indicates that this will not happen.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
SetLoadDefaultImageFile, SetDefaultImageFile, GetDefaultImageFile

◆ SetManualDisplayRefreshEnabled()

cvbbool_t SetManualDisplayRefreshEnabled ( cvbbool_t  value)

Sets the value of the "Manual Display Refresh Enabled" setting in the Common Vision Blox key of the Windows registry.

The "Manual Display Refresh Enabled" setting defines the default value for the ManualDisplayRefresh property of newly created Display Controls.

This function is only available on the Windows platform.

Parameters
[out]valueValue to be set for the "Manual Display Refresh Enabled" registry setting.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetManualDisplayRefreshEnabled

◆ SetSnapOnLoadDriver()

cvbbool_t SetSnapOnLoadDriver ( cvbbool_t  Value)

Sets the value of the "Snap Image On Load Driver" flag in the Common Vision Blox key in the Windows registry.

If this flag is set to true then the Image Control will execute a Snap call (CVCDriver.dll) whenever an image with an IGrabber interface has been newly loaded.

Attention
When setting this flag to true, make sure that the cameras or grabbers are actually capable of sending an image (a common mistake with respect to this flag is setting the flag to true and loading a driver for a camera that is in triggered mode and not providing a trigger signal to the camera - in that case, loading a new image into an Image Control will stall execution until a timeout occurs.

The "Snap Image On Load Driver" setting is also accessible through the Common Vision Blox Management Console.

This function is only available on the Windows platform.

Attention
An application calling this function must run with sufficient privileges to write to Common Vision Blox registry key. Unless the access rights in the registry have been modified or UAC has been disabled admin privileges will be required for this.
Parameters
[in]ValueValue to write to the registry..
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetSnapOnLoadDriver

◆ TranslateFileName()

cvbbool_t TranslateFileName ( const char *  FileNameIn,
char *  FileNameOut,
size_t  OutLength 
)

Replaces environment variables in a string and copies the result.

Despite what the name implies, this function is not actually limited to file names but can be used on any input string. The environment variable notations supported by it are %...% and $(...). For example the strings "%CVB%\CVCImg.dll" and "$(CVB)\CVCImg.dll" would both be transformed into "C:\Program Files\STEMMER IMAGING\Common Vision Blox\CVCImg.dll" (assuming that this is where Common Vision Blox has been installed to.

Note that the Common Langua Runtime exposes a similar functionality in the function System.Environment.ExpandEnvironmentVariables.

Parameters
[in]FileNameInInput string with environment variables.
[out]FileNameOutPointer to the buffer that is to receive the result string without environment variables.
[in]OutLengthThe length of the buffer pointed to by FileNameOut. No more than OutLength characters will be copied to the destination buffer function will copy at most OutLength bytes and if necessary the output string will be truncated.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetCVBDirectory, GetCVBDataDirectory
Sample Code in Delphi:
procedure dosth;
var pcDir: arry [0..259] of AnsiChar;
begin
TranslateFilename('%CVB%\cvcimg.dll', pcDir, 260);
end;
Sample Code in C++:
const char ENV_PATH[] = "%CVB%\\Tutorial\\ShapeFinder\\Images\\CD\\cd.sfm";
char filename[_MAX_PATH] = { 0 };
TranslateFileName(ENV_PATH, filename, _MAX_PATH);
cvbbool_t TranslateFileName(const char *FileNameIn, char *FileNameOut, size_t OutLength)
Replaces environment variables in a string and copies the result.
Definition: CVCUtilities.cpp:2111

◆ TranslateFileNameW()

cvbbool_t TranslateFileNameW ( const wchar_t *  FileNameIn,
wchar_t *  FileNameOut,
size_t  OutLength 
)

Replaces environment variables in a string and copies the result.

Despite what the name implies, this function is not actually limited to file names but can be used on any input string. The environment variable notations supported by it are %...% and $(...). For example the strings "%CVB%\CVCImg.dll" and "$(CVB)\CVCImg.dll" would both be transformed into "C:\Program Files\STEMMER IMAGING\Common Vision Blox\CVCImg.dll" (assuming that this is where Common Vision Blox has been installed to.

Note that the Common Langua Runtime exposes a similar functionality in the function System.Environment.ExpandEnvironmentVariables.

Since
Common Vision Blox 13.00.000
Parameters
[in]FileNameInInput string with environment variables.
[out]FileNameOutPointer to the buffer that is to receive the result string without environment variables.
[in]OutLengthThe length of the buffer pointed to by FileNameOut. No more than OutLength characters will be copied to the destination buffer function will copy at most OutLength bytes and if necessary the output string will be truncated.
Returns
TRUE if successful, FALSE otherwise.
Related Topics
GetCVBDirectory, GetCVBDataDirectory
Sample Code in C++:
const wchar_t ENV_PATH[] = L"%CVB%\\Tutorial\\ShapeFinder\\Images\\CD\\cd.sfm";
wchar_t filename[_MAX_PATH] = { 0 };
TranslateFileNameW(ENV_PATH, filename, _MAX_PATH);
cvbbool_t TranslateFileNameW(const wchar_t *FileNameIn, wchar_t *FileNameOut, size_t OutLength)
Replaces environment variables in a string and copies the result.
Definition: CVCUtilities.cpp:2163