Image Manager (CVCImg.dll) 14.0
Object Management

Functions to manage the life-time of an OBJ. More...

Typedefs

typedef void * OBJ
 CVB reference counted object handle. More...
 

Functions

cvbbool_t IsGrabber (IMG Image)
 Verifies whether the given Image handle has an IGrabber object. More...
 
cvbbool_t IsImage (IMG Image)
 Verifies whether the given Image handle has an IImageVPA object. More...
 
cvbbool_t IsIUnknown (OBJ Unknown)
 Verifies whether the passed object is a valid OBJ handle. More...
 
cvbbool_t IsPixels (OBJ PixelList)
 Verifies whether the given PixelList handle has an IPixelList object. More...
 
cvbval_t RefCount (OBJ Object)
 Returns the current value of the reference count for the given Object. More...
 
cvbval_t ReleaseImage (IMG Image)
 
cvbval_t ReleaseIUnknown (OBJ Unknown)
 
cvbbool_t ReleaseObject (OBJ &Object)
 Decrements the reference count of the given InterfaceContainer Object. More...
 
cvbval_t ShareImage (IMG Image)
 
cvbbool_t ShareObject (OBJ Object)
 Increments the reference count of the given InterfaceContainer Object. More...
 
cvbbool_t ShowDriverDialog (OBJ Object)
 Shows a simple built-in dialog for camera port and board selection. More...
 

Detailed Description

Functions to manage the life-time of an OBJ.

Typedef Documentation

◆ OBJ

OBJ

CVB reference counted object handle.

Base handle type of all reference counted CVB handles enabling shared ownership. An OBJ is an InterfaceContainer which aggregates multiple CVB interfaces by their base interface IDisposableType and manages their life-time:

When using a function which has a handle as a parameter, the InterfaceContainer queries the needed interface, like IImageVPA, if the function needs to access the image's properties or data. If the required interface is not in the container, the function will return false if the return type is cvbbool_t or CVC_ERROR( CVC_E_WRONGOBJECT )/CVC_ERROR( CVC_E_NOIMAGE ) if the return type is cvbres_t.

Note
CVB's type design mandates that each call to ShareObject or a create function, like LoadImageFile or CreateGenericImage, is paired with exactly one call to ReleaseObject, when the object is not needed anymore.

Reference Count

The InterfaceContainer holds the thread safe reference count and manages its life-time with it. The container is alive as long as the reference count is greater than zero. If the reference count reaches zero the container and its aggregated interface objects are destroyed.

Normally newly created objects have a reference count of 1. Every component that wants to take part in life-time management (uses the object) can share the handle via ShareObject and thus increase the reference count by 1. If the component does not need the object anymore, it releases the handle via ReleaseObject which will decrease the reference count by 1.

Note
The simple example above with the starting reference count of 1 does not hold true for complex objects like a driver loaded via LoadImageFile. The starting reference count is higher, but the rule that every call of a create function (like LoadImageFile) must be paired with one ReleaseObject call still is valid. In this case the reference count falls to zero even though the reference count was not 1!

Reference Count and Components

If you set e.g. an IMG 'object' into another component, it shares the given InterfaceContainer object holding the IImageVPA object. Components can be ActiveX Controls like the Display Active X control or the Foundation Package's FBlob tool. Any prior set IMG object is released on a successful set, thus automatically managing the life-time of the given IMG. That is the reason why you don't need to concern yourself too much with reference counting if you let the Image ActiveX control manage your images.

Note
A component storing an OBJ can itself be composed of multiple internal components (the Display ActiveX control is such an example). Thus setting an IMG object on a Display ActiveX control will increase the reference count by 2. If the Display ActiveX control is destroyed or a new image (or nullptr handle) is set, the old IMG object's reference count will also be decreased by two.
Attention
Never depend on the reference count in your application. The RefCount is only for debugging purposes! The exact values of such increases/decreases may change in a future version as the only contract is that each create or ShareObject call must be paired with exactly one ReleaseObject call.
Life-time Management Functions

cvbbool_t ReleaseObject(OBJ &Object)
cvbbool_t ShareObject(OBJ Object)
cvbval_t RefCount(OBJ Object)
Note
The implementation changed to the form described above in CVB 2017 (13.00.000), but behaves exactly the same seen from the C-API. The change was from a IUnknown base interface to the InterfaceContainer and IDisposableType base interface.
Attention
Although incrementing/decrementing the reference count is thread safe, the associated operations may not necessarily be thread safe!
For example loading a Vin-driver or freeing it is not thread safe: Thus sharing and releasing handles is safe until you reach the reference count of 0. This results in the ReleaseObject function not being thread safe with drivers as you often cannot assure which is the last call to ReleaseObject. With a normal image created via CreateGenericImage, though, the ReleaseObject function is thread safe.

Function Documentation

◆ IsGrabber()

cvbbool_t IsGrabber ( IMG  Image)

Verifies whether the given Image handle has an IGrabber object.

All devices that can produce image data provide this interface. Thus by calling this function on an IMG, you can determine whether you work with a pure or a driver image.

Note
Since CVB 2017 (13.00.000) this function always returns a correct result.
Parameters
[in]ImageObject handle to be checked.
Returns
true if the object supports the IGrabber interface; false otherwise.

◆ IsImage()

cvbbool_t IsImage ( IMG  Image)

Verifies whether the given Image handle has an IImageVPA object.

Note
Since CVB 2017 (13.00.000) this function always returns a correct result.
Parameters
[in]ImageObject handle to be checked.
Returns
true if the object supports the IImageVPA interface; false otherwise.

◆ IsIUnknown()

cvbbool_t IsIUnknown ( OBJ  Unknown)

Verifies whether the passed object is a valid OBJ handle.

Deprecated:
Since Common Vision Blox 2017 (13.00.000) there is no IUnknown type available anymore. Use the typed check functions like IsImage or IsGrabber.
Parameters
[in]UnknownObject handle to be checked.
Returns
true if the object is a valid InterfaceContainer; false otherwise.

◆ IsPixels()

cvbbool_t IsPixels ( OBJ  PixelList)

Verifies whether the given PixelList handle has an IPixelList object.

Note
Since CVB 2017 (13.00.000) this function always returns a correct result.
Parameters
[in]PixelListObject handle to be checked.
Returns
true if the object supports the IPixelList interface; false otherwise.

◆ RefCount()

cvbval_t RefCount ( OBJ  Object)

Returns the current value of the reference count for the given Object.

Note
This function only intended for debugging purposes. As described in the OBJ type, every create and ShareObject must be paired with a ReleaseObject.
This function is thread safe. But as an object may be released right after the call by another thread, you can not use this information in multi-threaded or production code. If you want to ensure a valid Object, use the ShareObject function. This function only succeeds on a valid object.
Attention
Production source code that depends on this function is fundamentally broken.
Parameters
[in]ObjectObject handle to InterfaceContainer object.
Returns
Current reference count.
See also
ShareObject, ReleaseObject

◆ ReleaseImage()

cvbval_t ReleaseImage ( IMG  Image)

Decrements the reference count of the given InterfaceContainer Object.

Deprecated:
Use ReleaseObject instead.
Attention
This function is not thread safe.
Parameters
[in]ImageImage object handle.
Returns
Reference count after the decrement.

◆ ReleaseIUnknown()

cvbval_t ReleaseIUnknown ( OBJ  Unknown)

Decrements the reference count of the given InterfaceContainer Object.

Deprecated:
Since Common Vision Blox 2017 (13.00.000) there is no IUnknown type available anymore. Use ReleaseObject instead.
Attention
This function is not thread safe.
Parameters
[in]UnknownObject handle.
Returns
Reference count after the decrement.

◆ ReleaseObject()

cvbbool_t ReleaseObject ( OBJ Object)

Decrements the reference count of the given InterfaceContainer Object.

When the reference count reaches zero, the object will be destroyed and its memory and resources freed.

Note
Since CVB 2017 (13.00.000) this function always returns a correct result.
Attention
As described in the OBJ documentation, this function is thread safe on pure images, but not on driver IMG objects!
Parameters
[in,out]ObjectObject handle to release; will be set to nullptr if object is destroyed.
Returns
true if reference counter reached zero; false otherwise.
See also
ShareObject, RefCount

◆ ShareImage()

cvbval_t ShareImage ( IMG  Image)

Increments the reference count of the given InterfaceContainer Object.

Deprecated:
Use ShareObject instead.
Attention
This function is not thread safe.
Parameters
[in]ImageImage object handle.
Returns
Reference count after the increment; -1 on error.

◆ ShareObject()

cvbbool_t ShareObject ( OBJ  Object)

Increments the reference count of the given InterfaceContainer Object.

This function should be called when you store the Object in a component, like a class. Every call to this function must be paired with a call to ReleaseObject, when the object is not needed anymore (e.g. call this in the class destructor).

Note
Since CVB 2017 (13.00.000) this function always returns a correct result.
Parameters
[in]ObjectObject handle to InterfaceContainer.
Returns
true if reference count was incremented successfully; false otherwise.
See also
ReleaseObject, RefCount

◆ ShowDriverDialog()

cvbbool_t ShowDriverDialog ( OBJ  Object)

Shows a simple built-in dialog for camera port and board selection.

Deprecated:
This functionality is deprecated and in fact no longer supported by most of the current CVB Vin-drivers. Therefore it should no longer be used in an application.
Attention
This method is not implemented under non-Windows systems.
Parameters
[in]ObjectObject handle.
Returns
true if the dialog was opened, false otherwise.