IC Imaging Control Class Library User's Guide

Welcome to IC Imaging Control, the image acquisition toolkit for Visual Basic, Visual C++ and .NET. With IC Imaging Control your application immediately supports Firewire cameras from Sony, The Imaging Source and other vendors, USB cameras, DV cameras, PCI frame grabbers and video-to-Firewire converters.

Introduction

This chapter discusses the following topics: Manual organization, System requirements, Distributing applications developed using IC Imaging Control

What's New

This part discusses the new features introduced in previous IC Imaging Control releases.

Project Wizards

For Visual C++ 7.1, 8.0, 9.0 and 10, there are so called "wizards" that allow you to easily setup an application using IC Imaging Control. Similarly, there are others that may be used to setup a frame filter and a frame filter module.

Programmer's Guide

This part illustrates how to perform your first steps with IC Imaging Control. In addition, a set of sample projects show the usage of the library. They focus on special aspects such as image processing, display and overlay techniques etc.

Technical Articles

Complete list of all technical articles.

Class Library Reference

Complete list of all classes and functions.

IC Imaging Control Standard Filters

IC Imaging Control ships with several standard frame filters. They can be explored with the Filter Inspector application.


Introduction

This chapter discusses the following topics: Manual organization, System requirements, Distributing applications developed using IC Imaging Control

System Requirements

How this Manual is Organized

Distributing your Applications

<< IC Imaging Control Class Library User's Guide


System Requirements

The Imaging Control Class Library requires the following minimum configuration:

  • Windows® 2000 with service pack 4 or Windows® XP® or higher.
  • DirectX® 9.0c or higher.
  • Microsoft® Visual C++® 7.1 (2003), Visual C++® 8 (2005), Visual C++® 9 (2008) or Visual C++® 10 (2010)
  • One or more WDM compliant video devices.

<< Introduction


How this Manual is Organized

  • Part 1, Introduction covers the topics: Manual Organization, System Requirements and Distributing Applications developed using IC Imaging Control.
  • Part 2, What's New discusses the new features introduced in the latest IC Imaging Control releases.
  • Part 3, Programmer's Guide, describes how to use IC Imaging Control with Microsoft® Visual C++®.
  • Part 4, Technical Articles, describes in detail general concepts, in addition to some special features of IC Imaging Control.
  • Part 5, Class Library Reference, contains a list of IC Imaging Control's classes, functions and data structures in alphabetical order.
  • Part 6, IC Imaging Control Standard Filters, describes the frame filters that are delivered with IC Imaging Control.

<< Introduction


Distributing your Applications

Required Files:

The following lists show all the files necessary for IC Imaging Control to operate properly. You must ensure that the files exist on your client's machine. If your client's machine has older versions of these files, you should update them.

The default IC Imaging Control installation path is My Documents\IC Imaginging Control 3.2. Please keep in mind, that the name "My Documents" is localized to your operating systems language. The binary files can be found in the classlib\win32\release folder for 32 bit applications and in classlib\x64\release for 64 bit applications.

The 64 bit versions of the files have all the text _x64 in their file names.

Following files are needed:

Runtime DLLs for Visual Studio™ 2003 generated applications:

32 bit only:

  • TIS_DShowLib09.dll
  • TIS_UDSHL09_vc71.dll

Target directory: The application's directory.

Runtime DLLs for Visual Studio™ 2005 generated applications:

32 bit:

  • TIS_DShowLib09.dll
  • TIS_UDSHL09_vc8.dll

Target directory: The application's directory.

Runtime DLLs for Visual Studio™ 2008 generated applications:

32 bit:

  • TIS_DShowLib09.dll
  • TIS_UDSHL09_vc9.dll

64 bit:

  • TIS_DShowLib09_x64.dll
  • TIS_UDSHL09_vc9_x64.dll

Target directory: The application's directory.

Runtime DLLs for Visual Studio™ 2010 generated applications:

32 bit:

  • TIS_DShowLib09.dll
  • TIS_UDSHL09_vc10.dll

64 bit:

  • TIS_DShowLib09_x64.dll
  • TIS_UDSHL09_vc10_x64.dll

Target directory: The application's directory.

System:

If Visual Studio™ 2003 is used for the application, following VC++ runtime files are needed:

  • Mfc71.dll **)
  • Msvcp71.dll **)
  • Msvcr71.dll **)

Target directory: Windows\System32

For higher versions of Visual Studio™ we suggest to use the VC runtime installations from Microsoft™.

<< Introduction


What's New

This part discusses the new features introduced in previous IC Imaging Control releases.

What's New in Version 3.2 since Version 3.0

Description of the changes from IC Imaging Control 3.0 to IC Imaging Control 3.2.

What's New in Version 3.0 since Version 2.0

Description of the changes from IC Imaging Control 2.0 to IC Imaging Control 3.0.

What's New in Version 2.0 since Version 1.41

Description of the changes from IC Imaging Control 1.41 to IC Imaging Control 2.0.

<< IC Imaging Control Class Library User's Guide


What's New in Version 3.2 since Version 3.0

Description of the changes from IC Imaging Control 3.0 to IC Imaging Control 3.2.

Init Library

<< What's New


What's New in Version 3.0 since Version 2.0

Description of the changes from IC Imaging Control 2.0 to IC Imaging Control 3.0.

Frame Filter

With frame filters, a versatile and powerful way to manipulate image data is introduced. Frame filters can be used to do:

  • control which frames will be removed (dropped) from the image stream
  • read and write image data to and from frames of the image stream, without having to copy the image data to a ring buffer. In other words: the frame filter allows image processing directly on buffers of the image stream (DirectShow buffers).
  • to change the video format (pixel format and/or width and height) of the image stream
  • implement image processing

Frame filters can be applied to the video stream at 3 locations: directly behind the video capture device, in front of the display and in front of the sink. This concept allows various functions to be implemented, such as a gate filter that passes only specific frames to a media file and drops the other ones. Frame filters can be implemented as part of an application or may reside in a filter container module. IC Imaging Control 3.0 comes with several often-used frame filters that can be loaded by the filter container module stdfilters.ftf:

  • ROI filter: changes the width and height of the image stream
  • DeBayer filter: transforms color raw data in Bayer format into an RGB color format.
  • Flip and rotation filter: Allows the image stream to be rotated (90°, 180° and 270°) and flipped (vertically and horizontally)
  • De-noise Filter: sums up a specified number of frames and divides the result by the number.

For details, please refer to the chapter: IC Imaging Control Standard Filters

New Sink Concept

IC Imaging Control 3.0 introduces a new sink concept. Therefore, the old sink classes AviSink and FrameGrabberSink have been deprecated and will not be available in future versions:

  • FrameHandlerSink: This class replaces the old FrameGrabberSink. It simplifies the creation and initialization, provides asynchronous grabbing of a specific number of images to the ring buffer and allows frame filters to be used in order to manipulate image data and control the copy process to the ring buffer collection. Using a frame filter, it is possible to create a ring buffer with a user defined pixel organization or omit the ring buffer collection totally by doing image processing directly on the buffers of the image stream (DirectShow buffers)
  • MediaStreamSink: This class replaces the old AviSink. It simplifies creation and initialization and allows other stream containers than AVI to be used. For a description of the currently supported stream containers, please refer to MediaStreamContainer. In addition, MediaStreamSink allows frame filters to be used, in order to manipulate image data and control which frames are written to the stream file. This allows, for example, real time lapse functionality to be implemented.

Advanced Overlay Concept

Instead of having one overlay in the image stream just behind the device, IC Imaging Control 3.0 now allows up to 3 overlay objects to be used. The 3 possible locations are:

  • Behind the device: this overlay appears in the display, as well as in the sink (ring buffer, stream file)
  • In front of the display: this overlay appears in the display only
  • In front of the sink: this overlay appears in the sink (ring buffer, stream file) only

This new concept, for example, allows you to have an overlay on the display, while doing image processing on the original image data or having different overlays on the display and on the sink (ring buffer and stream file).

Support for Raw Color Data in Bayer Format.

With IC Imaging Conrol 3.0, it is possible to apply color interpolation to raw image data in Bayer format. The color interpolation is called de-bayering and may be applied to the display, as well as to the data that goes to the sink (ring buffer and stream file). For details, please refer to the chapter Debayering.

Support for 16 bit Monochrome Formats

IC Imaging Control 3.0 now supports high resolution monochrome and raw color (Bayer) formats with a pixel depth of up to 16 bit. A suitable display mode for all these formats is provided. For information about which high resolution formats are supported and how their image data is organized, please refer to the YGB0 format and YGB1 format.

Project Wizards

With the new project Wizards for Visual Studio .NET, setting up a project for an application or a frame filter can now be done with only a few mouse clicks. Please refer to the wizard overview for details.

FilterInfoObject

The class FilterInfoObject has been substituted by the class Codec. This interface change was necessary, in order to prevent confusion between frame filters and codecs.

New Features Reference

List of all new features

<< What's New


New Features Reference

List of all new features

Extended Classes

List of all classes that were extended in IC Imaging Control 3.0

New Classes

List of all classes that were introduced in IC Imaging Control 3.0

New Constants

List of all constants that were introduced in IC Imaging Control 3.0

New Enumerations

List of all enumerations that were introduced in IC Imaging Control 3.0

New Functions

List of all functions that were introduced in IC Imaging Control 3.0

New Structures

List of all structures that were introduced in IC Imaging Control 3.0

New Type Definitions

List of all type definitions that were introduced in IC Imaging Control 3.0

<< What's New in Version 3.0 since Version 2.0


Extended Classes

List of all classes that were extended in IC Imaging Control 3.0

New Methods of Grabber

List of methods that were added to the Grabber class in IC Imaging Control 3.0

New Methods of Grabber

List of methods that were added to the Grabber class in IC Imaging Control 3.2

New Methods of IVCDPropertyItems

List of methods that were added to the IVCDPropertyItems class in IC Imaging Control 3.0

New Methods of MemBuffer

List of methods that were added to the MemBuffer class in IC Imaging Control 3.0

New Methods of MemBufferCollection

List of methods that were added to the MemBufferCollection class in IC Imaging Control 3.0

New Methods of OverlayBitmap

List of methods that were added to the OverlayBitmap class in IC Imaging Control 3.0

<< New Features Reference


New Methods of Grabber

List of methods that were added to the Grabber class in IC Imaging Control 3.2

Grabber::tVidFmtDescPtr

A tVidFmtDescPtr is a smart pointer to a VideoFormatDesc object.

Grabber::tVidFmtDescList

A tVidFmtDescList is a std::vector of smart pointers to VideoFormatDesc objects.

Grabber::tVidFmtDescListPtr

A tVidFmtDescListPtr is smart pointer to a tVidFmtDescList. objects.

Grabber::getAvailableVideoFormatDescs

Returns a list of VideoFormatDesc objects describing all video formats supported by the current video capture device according to the current video norm.

<< Extended Classes


Grabber::setOverlayBitmapPathPosition

Grabber::setOverlayBitmapPathPosition Method
Sets the positions of OverlayBitmap objects in the graph.
Syntax:
bool setOverlayBitmapPathPosition( DWORD OVBPathPositions );

Parameter | Description
OVBPathPositions | Specifies the position of the OverlayBitmap objects in the graph. This can be a member of the tPathPosition enumeration or an ORed combination of them.
Return value:

true, if the operation was successful. If an error occurred, call getLastError to obtain extended error information.

Remarks:

You should set the positions before calling startLive. When the image stream is running you cannot change the position.

The default setting is ePP_DEVICE. If you do not need an overlay in your application, it is always a good idea to disable all overlays by calling this method with ePP_NONE.

In contrast to OverlayBitmap::setEnable, setOverlayBitmapPathPosition can not be used after live mode has been started.

Information:

Introduced in version 3.0
Example:

To enable the overlay bitmap for both sink and display, but not for the device, use ePP_SINK|ePP_DISPLAY as a parameter.

See also: Grabber, OverlayBitmap, tPathPosition, Grabber::getOverlayBitmapPathPosition

<< Grabber


Grabber::getOverlayBitmapPathPosition

Grabber::getOverlayBitmapPathPosition Method
Returns the current position of OverlayBitmap objects in the graph.
Syntax:
DWORD getOverlayBitmapPathPosition() const;
Return value:

The position of OverlayBitmap objects in the graph, specified by a tPathPosition or an ORed combination of them.

Information:

Introduced in version 3.0
See also: Grabber, OverlayBitmap, tPathPosition, Grabber::setOverlayBitmapPathPosition

<< Grabber


Grabber::getSinkTypePtr

Grabber::getSinkTypePtr Method
Returns a pointer to the currently selected sink.
Syntax:
smart_ptr<GrabberSinkType> getSinkTypePtr() const;
Return value:

A pointer to the currently selected sink, or 0 if no sink is selected.

Information:

Introduced in version 3.0
See also: Grabber, Grabber::setSinkType, GrabberSinkType

<< Grabber


Grabber::setDeviceFrameFilters

Grabber::setDeviceFrameFilters Method
Inserts a list of frame filters in the device path of the image stream. If an overlay is present in the device path, the filter list is inserted in front it. This means that the filter list is located between the device and the overlay.
Syntax:
bool setDeviceFrameFilters( IFrameFilter* pFilter );
bool setDeviceFrameFilters( const tFrameFilterList& filterList );

Parameter | Description
pFilter | Pointer to an IFrameFilter object. If this parameter is used, a filter list is generated and the IFrameFilter object is inserted.
filterList | A tFrameFilterList containing pointers to IFrameFilter objects.
Return value:

true, if the operation was successful. If an error occurred, call getLastError to obtain extended error information.

Remarks:

The life time of filter instances has to be checked by the caller of this method. Therefore, the caller remains responsible for the filter objects that are referenced by the plain pointers in the filter list. If you want to use filters here that have been loaded from a module, you have to call the get method of the smart_com pointer that holds the filter instance in order to obtain a plain pointer. Filters that have been inserted in the device path must not be destroyed unless they have been removed by calling setDeviceFrameFilters using a Null pointer as a parameter.

Information:

Introduced in version 3.0
Sample:

The following code fragment shows how to create two frame filter instances and set them as a filter chain.

m_pROIFilter = FilterLoader::createFilter( "ROI" );
m_pRotFlipFilter = FilterLoader::createFilter( "Rotate Flip" );

// Set filter parameters.
tFrameFilterList filterList;

// Use .get to extract a plain pointer from the smart pointer.
filterList.push_back( m_pROIFilter.get() );
filterList.push_back( m_pRotFlipFilter.get() );

m_Grabber.setDeviceFrameFilters( filterList );

Please note the use of smart_com.get() to extract a plain pointer out of the smart pointers.

See also: Grabber, IFrameFilter, Grabber::getDeviceFrameFilters, Grabber::setDisplayFrameFilters

<< Grabber


Grabber::getDeviceFrameFilters

Grabber::getDeviceFrameFilters Method
Returns the list of frame filters that are currently set behind the device.
Syntax:
const tFrameFilterList getDeviceFrameFilters() const;
Return value:

The list of frame filters that are currently set behind the device, or NULL if no list nor a single frame filter has been set.

Remarks:

The elements in the list are pointers to frame filter objects that are maintained elsewhere. Therefore, these pointers may not be freed. If the method setDeviceFrameFilters was called with a pointer to a IFrameFilter (instead of a list), the list returned by getDeviceFrameFilters has only one element.

Information:

Introduced in version 3.0
See also: Grabber, Grabber::setDeviceFrameFilters, IFrameFilter

<< Grabber


Grabber::getVideoDataDimension

Grabber::getVideoDataDimension Method
Returns the actual dimension of the image data which is passed to the display. This may be different from the video format of the currently active video capture device, if you have used setDeviceFrameFilters or setDisplayFrameFilters to insert frame filters in the image stream behind the device or in front of the display. If IFrameFilter objects are used by the FrameHandlerSink, the dimension of the MemBufferCollection may be different from the video data dimension as well.
Syntax:
bool getVideoDataDimension( SIZE& dim ) const;

Parameter | Description
dim | Size of the image data.
Return value:

true, if the operation was successful. If an error occurred, call getLastError to obtain extended error information.

Remarks:

You can only retrieve this information, when the image stream has been setup by a call to either prepareLive or startLive.

Information:

Introduced in version 3.0
Sample:

The following example uses the ROI filter from stdfilters.ftf to resize the video format of the live display.

Grabber grabber;
grabber.showDevicePage();

// Create an instance of the ROI filter, and let the user change the ROI
smart_com<IFrameFilter> pROIFilter = FilterLoader::createFilter( "ROI" );
pROIFilter->callDialog( 0 );

// Set the filter, and call prepareLive.
grabber.setDisplayFrameFilters( pROIFilter.get() );
grabber.prepareLive( true );

// After prepareLive has been called, getVideoDataDimension returns the size of the
// live display.
SIZE dim;
if( grabber.getVideoDataDimension( dim ) )
{
    std::cout << "Display video format: " << dim.cx << "x" << dim.cy << std::endl;
}
else
{
    std::cerr << "Unable to determine display video format" << std::endl;
}

After prepareLive has been called, getVideoDataDimension returns the size of the live display video format.

See also: Grabber, Grabber::prepareLive, Grabber::startLive

<< Grabber


Grabber::prepareLive

Grabber::prepareLive Method
Tries to setup the image stream by connecting the device with the display and the sink and inserting frame filters and overlays.
Syntax:
bool prepareLive( bool bUseVideoRenderer );

Parameter | Description
bUseVideoRenderer | Specifies whether you want to use live display when you start the image stream.
Return value:

true, if the operation was successful. If an error occurred, call getLastError to obtain extended error information.

Remarks:

This method can be used to check, whether it is possible to insert all specified objects (frame filters, overlays and the sink) in the image stream. In the prepared state, the video capture device does not allocate bandwidth but the image stream is setup completely. Therefore, a subsequent call to startLive will take far less time than the same operation called when the image stream is stopped. This allows you to setup several image streams for several devices (using one Grabber object for every image stream) and switch between them very quickly by changing the state from prepared to live and back to prepared by calling suspendLive.

No operation which may change the layout of the video stream is permitted after prepareLive is called. These operations are:

  • setVideoFormat
  • setFrameRate
  • setFPS
  • setVideoNorm
  • setSinkType
  • setVideoFormat
  • setOverlayBitmapPathPosition
  • setExternalTrigger
  • setFlipH
  • setFlipV
  • setDeviceFrameFilters
  • setDisplayFrameFilters

A call to the methods stopLive and closeDev ends the prepared state.

Information:

Introduced in version 3.0
Sample:

The following example shows how to use prepareLive and suspendLive in order to grab images "simultaneously" from two high-resolution cameras that are connected to the same bus:

// Assume we connected 2 high resolution cameras to the same FireWire bus and
// set both cameras to UYVY 1024x768, 15fps.
// They will not be able to run at the same time with the specified video format
// and frame rate because each camera allocates 77% of the available bandwidth.

// Open camera 1
Grabber grabber1;
grabber1.openDev( "DFx 31AF03" );
grabber1.setVideoFormat( "UYVY (1024x768)" );
grabber1.setFPS( 15.0 );

// Open camera 2
Grabber grabber2;
grabber2.openDev( "DFx 31BF03" );
grabber2.setVideoFormat( "UYVY (1024x768)" );
grabber2.setFPS( 15.0 );

// Set sink types:
// FrameHandlerSink containing a 10-buffer MemBufferCollection of RGB24 images.
tFrameHandlerSinkPtr pSink1 = FrameHandlerSink::create( eRGB24, 10 );
grabber1.setSinkType( pSink1 );
tFrameHandlerSinkPtr pSink2 = FrameHandlerSink::create( eRGB24, 10 );
grabber2.setSinkType( pSink2 );

// Set the grabbers to 'prepared' state.
// Almost all necessary initializations are done then,
// and startLive() will be a fast operation.
if( !grabber1.prepareLive( false ) )
{
    std::cerr << "grabber1.prepareLive failed: " << grabber1.getLastError() << std::endl;
    return;
}
if( !grabber2.prepareLive( false ) )
{
    std::cerr << "grabber2.prepareLive failed: " << grabber2.getLastError() << std::endl;
    return;
}

DWORD start = ::GetTickCount();

for( int i = 0; i < 10; ++i )
{
    // Snap one image from camera 1
    grabber1.startLive( false );
    pSink1->snapImages( 1 );
    grabber1.suspendLive();

    // Snap one image from camera 2
    grabber2.startLive( false );
    pSink2->snapImages( 1 );
    grabber2.suspendLive();
}

DWORD stop = ::GetTickCount();
std::cout << "2x10 images snapped in " << (stop-start) << "ms" << std::endl;

// Stop both cameras
grabber1.stopLive();
grabber2.stopLive();

// Save the snapped images
pSink1->getMemBufferCollection()->save( "cam1-*.bmp" );
pSink2->getMemBufferCollection()->save( "cam2-*.bmp" );

For another example showing the use of prepareLive, please refer to Grabber::getVideoDataDimension.

See also: Grabber, Grabber::suspendLive, Grabber::getVideoDataDimension

<< Grabber


Grabber::isLivePrepared

Grabber::isLivePrepared Method
Returns whether the image stream is in 'prepared' state.
Syntax:
bool isLivePrepared() const;
Return value:

true, if prepareLive or suspendLive was called successfully and no other operation ended the 'prepared' state.

Remarks:

Information:

Introduced in version 3.0
Sample:

For an example, please refer to Grabber::prepareLive.

See also: Grabber, Grabber::prepareLive, Grabber::suspendLive, Grabber::startLive, Grabber::stopLive

<< Grabber


Grabber::suspendLive

Grabber::suspendLive Method
Suspends an image stream and puts it into prepared state.
Syntax:
bool suspendLive();
Return value:

true, if the operation was successful. If an error occurred, call getLastError to obtain extended error information.

Information:

Introduced in version 3.0
Sample:

For examples on how to use suspendLive, please refer to Grabber::prepareLive.

See also: Grabber, Grabber::prepareLive

<< Grabber


Grabber::setDisplayFrameFilters

Grabber::setDisplayFrameFilters Method
Inserts a list of frame filters in the display path of the image stream. If an overlay is present in the display path, the filter list is inserted in front of it. This means that the overlay is located between the filter list and the display. If there is no overlay in the display path, the filter list is inserted in front of the the display.
Syntax:
bool setDisplayFrameFilters( IFrameFilter* pFilter );
bool setDisplayFrameFilters( const tFrameFilterList& filterList );

Parameter | Description
pFilter | Pointer to an IFrameFilter object. If this parameter is used, a filter list is generated and the IFrameFilter object is inserted.
filterList | A tFrameFilterList, containing pointers to IFrameFilter objects.
Return value:

true, if the operation was successful. If an error occurred, call getLastError to obtain extended error information.

Remarks:

The life time of filter instances has to be checked by the caller of this method. Therefore, the caller remains responsible for the filter objects that are referenced by the plain pointers in the filter list. If you want to use filters here that have been loaded from a module, you have to call the get method of the smart_com pointer that holds the filter instance in order to obtain a plain pointer. Filters that have been inserted in the display path must not be destroyed unless they have been removed by calling setDisplayFrameFilters using a null pointer as a parameter.

Information:

Introduced in version 3.0
Sample:

The following code fragment shows how to create two frame filter instances and set them as a filter chain.

m_pROIFilter = FilterLoader::createFilter( "ROI" );
m_pRotFlipFilter = FilterLoader::createFilter( "Rotate Flip" );

// Set filter parameters.
tFrameFilterList filterList;

// Use .get to extract a plain pointer from the smart pointer.
filterList.push_back( m_pROIFilter.get() );
filterList.push_back( m_pRotFlipFilter.get() );

m_Grabber.setDisplayFrameFilters( filterList );

Please note the use of smart_com.get() to extract a plain pointer out of the smart pointers.

See also: Grabber, IFrameFilter, Grabber::getDisplayFrameFilters, Grabber::setDeviceFrameFilters

<< Grabber


Grabber::getDisplayFrameFilters

Grabber::getDisplayFrameFilters Method
Returns the list of frame filters that are currently set in front of the display.
Syntax:
const tFrameFilterList getDisplayFrameFilters() const;
Return value:

The list of frame filters that are currently set in front of the display, or NULL if neither a list, nor a single frame filter have been set.

Remarks:

The elements in the list are pointers to frame filter objects that are maintained elsewhere. Therefore, these pointers may not be freed. If the method setDisplayFrameFilters was called with a pointer to an IFrameFilter (instead of a list), the list returned by getDisplayFrameFilters has only one element.

Information:

Introduced in version 3.0
See also: Grabber, Grabber::setDisplayFrameFilters, IFrameFilter

<< Grabber


Grabber::getDeBayerTransform

Grabber::getDeBayerTransform Method
Returns a pointer to a DeBayerTransform object. If a BY8 Bayer video format is selected, the image data will be debayered automatically. The DeBayerTransform class allows the debayering to be checked.
Syntax:
smart_ptr<DeBayerTransform> getDeBayerTransform() const;
Return value:

A pointer to the DeBayerTransform.

Remarks:

This method returns a valid pointer even, if no debayering is applied to the video data. In this case, the method DeBayerTransform::isActive returns false.

Information:

Introduced in version 3.0
Sample:

Debayering
See also: Grabber, DeBayerTransform, Debayering

<< Grabber


Grabber::getOverlay

Grabber::getOverlay Method
This method returns a pointer to an instance of the OverlayBitmap object. The OverlayBitmap is used to draw text and graphics on the video stream.
Syntax:
smart_ptr<OverlayBitmap> getOverlay() const;
smart_ptr<OverlayBitmap> getOverlay( tPathPosition PathPositionToFetch ) const;
Return value:

A pointer to the instance of OverlayBitmap for the specified path position.

Remarks:

When no path position is specified, the OverlayBitmap for the device path is returned.

To see the things you draw in live video and grabbed images, you have to activate the OverlayBitmaps, using setOverlayBitmapPathPosition.

Sample:

This example demonstrates how to enable the overlay bitmap and draw the text "Hello Word" in the upper left corner of the live video.

// Make sure, the overlay for the text is enabled
m_Grabber.getOverlay()->setEnable(true);
// Draw the text
m_Grabber.getOverlay()->drawText( RGB(255,0,0),  0, 0, "Hello World" );
See also: Grabber, OverlayBitmap, setOverlayBitmapPathPosition

<< Grabber


Grabber::saveDeviceState

Grabber::saveDeviceState Method
Saves the state of the opened device. A saved state can be restored using loadDeviceState.
Syntax:
std::string saveDeviceState( bool bDevice = true, bool bGrabberDeviceSetup = true, bool bVCDProperties = true ) const;
std::wstring    saveDeviceStateW( bool bDevice = true, bool bGrabberDeviceSetup = true, bool bVCDProperties = true ) const;

Parameter | Description
bDevice | When this parameter is set to true, the currently opened device's name and serial number are saved.
bGrabberDeviceSetup | When this parameter is set to true, the currently selected Video Norm, Video Format, Input Channel, FPS, FlipH and FlipV are saved.
bVCDProperties | When this parameter is set to true, the VCDProperties of the currently opened device are saved.
Return value:

Returns a string that contains the device settings. The string is formatted in XML. On error, an empty string is returned. Use Grabber::getLastError to verify whether or not an error occurred.

Information:

Introduced in version 2.0
Sample:

// Retrieve the device state.
std::string deviceState = m_Grabber.saveDeviceState();
MessageBox( deviceState.c_str(), "Saved device state" );

// Close the device.
m_Grabber.closeDev();

// The device is now closed. Open the saved device.
m_Grabber.loadDeviceState( deviceState );

// Show live video again.
m_Grabber.startLive();
See also: loadDeviceState

<< Grabber


Grabber::saveDeviceStateToFile

Grabber::saveDeviceStateToFile Method
Saves the state of the currently opened device to a file. The grabber state can be restored using loadDeviceStateFromFile.
Syntax:
bool saveDeviceStateToFile( const std::string& filename, bool bDevice, bool bGrabberDeviceSetup = true, bool bVCDProperties = true  );
bool saveDeviceStateToFile( const std::wstring& filename, bool bDevice, bool bGrabberDeviceSetup = true, bool bVCDProperties = true  );

Parameter | Description
filename | Specifies the filename of the settings data file.
bDevice | When this parameter is set to true, the currently opened device's name and serial number are saved.
bGrabberDeviceSetup | When this parameter is set to true, the currently selected Video Norm, Video Format, Input Channel, FPS, FlipH and FlipV are saved.
bVCDProperties | When this parameter is set to true, the VCDProperties of the currently opened device are saved.
Return value:

true, if the operation was successful. If an error occurred, call getLastError to obtain extended error information.

Remarks:

The settings data file contains the opened device's settings in XML format. The file contains exactly the same information as the string returned by saveDeviceState.

Information:

Introduced in version 2.0
Sample:

// Save the device state to "device.xml".
m_Grabber.saveDeviceStateToFile( "device.xml" );

// Close the device.
m_Grabber.closeDev();

// The device is now closed. Open the saved device.
m_Grabber.loadDeviceStateFromFile( "device.xml" );

// Show live video again.
m_Grabber.startLive();
See also: loadDeviceStateFromFile

<< Grabber


Grabber::tVidFmtDescPtr

tVidFmtDescPtr
A tVidFmtDescPtr is a smart pointer to a VideoFormatDesc object.
Syntax:
typedef smart_ptr<VideoFormatDesc> tVidFmtDescPtr;

<< Grabber


Grabber::tVidFmtDescList

tVidFmtDescList
A tVidFmtDescList is a std::vector of smart pointers to VideoFormatDesc objects.
Syntax:
typedef std::vector<tVidFmtDescPtr> tVidFmtDescList;

<< Grabber


Grabber::tVidFmtDescListPtr

tVidFmtDescListPtr
A tVidFmtDescListPtr is smart pointer to a tVidFmtDescList. objects.
Syntax:
typedef smart_ptr<tVidFmtDescList> tVidFmtDescListPtr;

<< Grabber


Grabber::getAvailableVideoFormatDescs

Grabber::getAvailableVideoFormatDescs Method
Returns a list of VideoFormatDesc objects describing all video formats supported by the current video capture device according to the current video norm.
Syntax:
tVidFmtDescListPtr    getAvailableVideoFormatDescs() const;
tVidFmtDescListPtr    getAvailableVideoFormatDescs( const VideoNormItem& videoNorm ) const;

Parameter | Description
videonorm | If a video norm is specified, a list of all video format descriptions that are compatible to this video norm is returned.
Return value:

A pointer to a list of VideoFormatDescs or 0, if an error occurred.

Information:

Introduced in version 3.2
See also: Grabber, Grabber::tVidFmtDescListPtr, VideoFormatDesc, VideoNormItem

<< Grabber


New Methods of IVCDPropertyItems

List of methods that were added to the IVCDPropertyItems class in IC Imaging Control 3.0

IVCDPropertyItems::findInterfacePtr

Searches the collection for a IVCDPropertyInterface with a given combination of item, element and interface id. In contrast to the findInterface method, this method has a templated output parameter, and the found and the type of this parameter is queried from the found interface.

<< Extended Classes


IVCDPropertyItems::findInterfacePtr

IVCDPropertyItems::findInterfacePtr Method
Searches the collection for a IVCDPropertyInterface with a given combination of item, element and interface id. In contrast to the findInterface method, this method has a templated output parameter, and the found and the type of this parameter is queried from the found interface.
Syntax:
// VC 6:
template<class TItf>
TItf findInterfacePtr( const GUID& itemID, const GUID& elementID, TItf& pRval )
// VC 7.1:
template<class TItf>
smart_com<TItf> findInterfacePtr( const GUID& itemID, const GUID& elementID, smart_com<TItf>& pRval )

Name | Description
itemID | Item ID of the interface to be searched for. For a list of available GUIDs, see Standard Property Item GUIDs.
elementID | Element ID of the interface for which to search. For a list of available GUIDs, see Standard Element GUIDs.
pRval | Pointer to IVCDPropertyInterface-derived class. When the method succeeds, this parameter points to the found and queried interface, otherwise it is 0.
Return Value:

When the method succeeds, it returns the found and queried interface, otherwise 0.

See also: IVCDPropertyItems

<< IVCDPropertyItems


New Methods of MemBuffer

List of methods that were added to the MemBuffer class in IC Imaging Control 3.0

MemBuffer::getFrameType

returns an object that describes the pixel depth, pixel organization and the extent of the image data stored in the buffer.

<< Extended Classes


MemBuffer::getFrameType

MemBuffer::getFrameType Method
returns an object that describes the pixel depth, pixel organization and the extent of the image data stored in the buffer.
Syntax:
virtual const FrameTypeInfo& getFrameType() const;
Return value:

An object that describes the pixel depth, pixel organization and the extents of the image data stored in the buffer.

Information:

Introduced in version 3.0
See also: MemBuffer, FrameTypeInfo

<< MemBuffer


New Methods of MemBufferCollection

List of methods that were added to the MemBufferCollection class in IC Imaging Control 3.0

MemBufferCollection::create

This factory function creates a MemBufferCollection for use with the FrameHandlerSink or the Grabber.

MemBufferCollection::getFrameType

Returns the frame type of the collection.

<< Extended Classes


MemBufferCollection::create

MemBufferCollection::create Method
This factory function creates a MemBufferCollection for use with the FrameHandlerSink or the Grabber.
Syntax:
static tMemBufferCollectionPtr create( const FrameTypeInfo& frame_type, DWORD count );
static tMemBufferCollectionPtr create( const FrameTypeInfo& frame_type, DWORD count, BYTE* buffers[] );
static tMemBufferCollectionPtr create( tColorformatEnum colorformat, SIZE dim, DWORD count );
static tMemBufferCollectionPtr create( tColorformatEnum colorformat, SIZE dim, DWORD count, BYTE* buffers[] );

Parameter | Description
frame_type | A FrameTypeInfo structure, describing the frame type of the new MemBufferCollection.
count | The number of buffers to be created.
buffers | Array of user-specified image data pointers. These will be used by the MemBuffers for the image data. The array must contain count pointers, which must not be 0.
colorformat | The colorformat of the MemBuffers. Must be a valid colorformat.
dim | The dimensions of the MemBuffers created.
Return value:

This function returns 0, if one of the parameters is not valid, otherwise a MemBufferCollection instance.

Information:

Introduced in version 3.0
See also: MemBufferCollection, FrameHandlerSink, Grabber

<< MemBufferCollection


MemBufferCollection::getFrameType

MemBufferCollection::getFrameType Method
Returns the frame type of the collection.
Syntax:
const FrameTypeInfo& getFrameType() const;
Return value:

The FrameTypeInfo object, describing the frame type of the collection.

Information:

Introduced in version 3.0
See also: MemBufferCollection, FrameTypeInfo

<< MemBufferCollection


New Methods of OverlayBitmap

List of methods that were added to the OverlayBitmap class in IC Imaging Control 3.0

OverlayBitmap::setColorMode

Set the color mode of this OverlayBitmap. The color mode determines, whether the overlay bitmap is painted in color or grayscale. The images provided by the video capture device are converted into the selected format before drawing the overlay.

OverlayBitmap::getColorMode

Returns the currently selected color mode of this OverlayBitmap.

OverlayBitmap::tOVBColorMode

The members of this enumeration are used to set the color format of the OverlayBitmap, using setColorMode.

OverlayBitmap::getPathPosition

Returns the path position of this OverlayBitmap.

OverlayBitmap::getFrameType

Returns a FrameTypeInfo object describing the current format of this OverlayBitmap.

<< Extended Classes


OverlayBitmap::setColorMode

OverlayBitmap::setColorMode Method
Set the color mode of this OverlayBitmap. The color mode determines, whether the overlay bitmap is painted in color or grayscale. The images provided by the video capture device are converted into the selected format before drawing the overlay.
Syntax:
bool setColorMode( tOVBColorMode newMode );
Parameter Description
newMode

Specifies the new color mode. Possible values are members of OverlayBitmap::tOVBColorMode:

Value | Description
eCOLOR | Forces the overlay bitmap to operate in color mode. If the source frame type (video format or output of a filter) is a grayscale format, the images are converted into a colored format (e.g. RGB24), so that colored texts and lines can be drawn on image data.
eGRAYSCALE | Forces the overlay bitmap to operate in grayscale mode. If the source frame type (video format or output of a filter) is a color format, the images are converted into a grayscale format (e.g. Y800). If colored lines or texts are drawn onto the overlay bitmap, their color will be converted to the nearest matching color of the gray image.
eBESTFIT | This mode lets the overlay bitmap accept colored and grayscale images. It will select the mode at which preferably no color format conversions are necessary. Call OverlayBitmap::getColorformat to find out which format was actually chosen after live mode has been prepared or started. When drawing lines or texts onto the overlay bitmap, the drawing color is converted to its nearest equivalent in the actually used format.
Return value:

Value | Description
true | The color mode was set successfully.
false | The color mode could not be set.
Remarks:

The color mode can only be changed, if the Grabber which owns this OverlayBitmap is not in live or prepared mode.

Information:

Introduced in version 3.0
Example:

The following example shows how to enable the overlay bitmap for the display path and force it to color mode:

// Check whether the OverlayBitmap object can be inserted in front of the
// display.
if( !m_Grabber.setOverlayBitmapPathPosition(ePP_DISPLAY) )
{
    MessageBox( m_Grabber.getLastError().c_str(),"Error",MB_ICONERROR);
}
else
{
    smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
    pOverlayBitmap = m_Grabber.getOverlay(ePP_DISPLAY);
    // Set the color mode to grayscale.
    pOverlayBitmap->setColorMode( OverlayBitmap::eCOLOR );
}

After this initialization, colored drawings can be placed onto the live display. The original, grayscale image data is sent to the sink in its original form.

See also: OverlayBitmap, OverlayBitmap::getColorMode, OverlayBitmap::tOVBColorMode, OverlayBitmap::getColorformat

<< OverlayBitmap


OverlayBitmap::getColorMode

OverlayBitmap::getColorMode Method
Returns the currently selected color mode of this OverlayBitmap.
Syntax:
tOVBColorMode getColorMode() const;
Return value:

This function returns the selected tOVBColorMode.

Information:

Introduced in version 3.0
See also: OverlayBitmap, OverlayBitmap::setColorMode, OverlayBitmap::tOVBColorMode

<< OverlayBitmap


OverlayBitmap::tOVBColorMode
The members of this enumeration are used to set the color format of the OverlayBitmap, using setColorMode.
Enumeration | Description
eBESTFIT | Let the OverlayBitmap select the best matching color format.
eGRAYSCALE | Use grayscale mode.
eCOLOR | Use color mode.

<< OverlayBitmap


OverlayBitmap::getPathPosition

OverlayBitmap::getPathPosition Method
Returns the path position of this OverlayBitmap.
Syntax:
tPathPosition getPathPosition() const;
Return value:

This function returns the selected tPathPosition of this OverlayBitmap.

Information:

Introduced in version 3.0
See also: OverlayBitmap, Grabber::setOverlayBitmapPathPosition, Grabber::getOverlay, tPathPosition

<< OverlayBitmap


OverlayBitmap::getFrameType

OverlayBitmap::getFrameType Method
Returns a FrameTypeInfo object describing the current format of this OverlayBitmap.
Syntax:
FrameTypeInfo getFrameType() const;
Return value:

The return value of this method generally only makes sense after Grabber::prepareLive or Grabber::startLive has been called.

Information:

Introduced in version 3.0
See also: OverlayBitmap, Grabber::getOverlay, FrameTypeInfo

<< OverlayBitmap


New Classes

List of all classes that were introduced in IC Imaging Control 3.0

Codec

The Codec class represents a video compressor. It replaces the deprecated FilterInfoObject, that was used in previous versions of IC Imaging Control.

DeBayerTransform

The DeBayerTransform class allows you to control the automatic debayering process of IC Imaging Control.

FilterLoader

This static class contains methods to create instances of frame filters that are loaded from filter modules ( *.ftf ).

FrameHandlerSink

The FrameHandlerSink is the SinkType used to grab (copy) frames from the image stream. It replaces the deprecated FrameGrabberSink and contains a MemBufferCollection and optionally allows you to specify one or more IFrameFilters that are responsible for copying the image data to the buffers of the MemBufferCollection. The IFrameFilter implementation can perform user-defined transformations while copying the data, and they can intentionally drop unwanted frames. If no frame filter is registered, the frames are copied to the MemBufferCollection without being changed.

IFrameFilter

IFrameFilter is the base class of all frame filters. It contains methods to access the filter's parameters, display a configuration dialog and save filter settings. This class provides the interface to use an existing filter.

FrameFilterImpl

To implement a transform filter, you have to derive from this class.

FrameUpdateFilterImpl

To implement an update filter, you have to derive from this class.

IFrame

Interface to an image buffer.

FrameTypeInfoArray

This class is a list of FrameTypeInfo objects. It is used in the communication between FrameFilterImpl-derived classes when the image stream is setup and the filters are inserted in the image stream.

MediaStreamContainer

A MediaStreamContainer describes a video file format. The most common video file format is AVI, which is identified by the GUID MSC_AviContainer.

MediaStreamSink

The MediaStreamSink replaces the deprecated AVISink. A MediaStreamSink can save image data in video files and optionally allows you to specify one or more IFrameFilters that can analyze and/or transform the image data before it is written to the video file.

FrameTypeInfo

This structure contains all information to describe the layout (pixel depth and pixel organization) and the extents of one frame (image buffer) in the image stream.

<< New Features Reference


Codec

The Codec class represents a video compressor. It replaces the deprecated FilterInfoObject, that was used in previous versions of IC Imaging Control.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Methods

Method | Description
callDialog | This method calls a dialog box, if the codec has one.
getAvailableCodecs | Returns a tCodecListPtr, containing the video compressors that were found on your system.
getInternalInterface | Returns a reference to an internal interface.
getName | Returns the readable name of the codec.
getSettings | This method returns a string that contains the parameters of this codec / compressor.
hasDialog | Checks whether the codec has a dialog box.
hasSettings | Checks whether setting data can be retrieved from or set to the codec.
isVfwCodec | Returns whether this codec is a Video for Windows codec.
operator!= | Determine whether two codec objects differ.
operator< | Compares the string representations of this Codec with the string representation of another one.
operator== | Checks whether a Codec equals another codec object or its name equals a specified string.
setSettings | This method is used to set previously retrieved codec data.
toString | Returns a string representation of this object.

<< Classes


Codec::callDialog

Codec::callDialog Method
This method calls a dialog box, if the codec has one.
Syntax:
bool callDialog( HWND hParent = 0 );

Parameter | Description
hParent | Specifies the parent window of the dialog box that should be shown.
Return value:

Value | Description
true | The dialog box was successfully displayed.
false | An error occurred.
Remarks:

In most cases, this method blocks until the dialog box is closed.

See also: Codec, Codec::hasDialog

<< Codec


Codec::getAvailableCodecs

Codec::getAvailableCodecs Method
Returns a tCodecListPtr, containing the video compressors that were found on your system.
Syntax:
static tCodecListPtr getAvailableCodecs();
Return value:

The list may be empty ( size() == 0 ), if no codecs were found. Otherwise, it contains the available codecs as present on the system.

See also: Codec, tCodecListPtr

<< Codec


Codec::getInternalInterface

Codec::getInternalInterface Method
Returns a reference to an internal interface.
Syntax:
template<class TItf>
smart_com<TItf> getInternalInterface( smart_com<TItf>& pItf ) const;
template<class TItf>
smart_com<TItf> getInternalInterface( REFIID riid, smart_com<TItf>& pItf ) const;

Parameter | Description
pItf | A smart_com to an interface reference.
riid | An interface ID.
Return value:

A reference to the interface requested or 0, if the interface is not supported.

Remarks:

Using this method, it is possible to fetch a custom interface from a codec.

To use this method, the compiler must support the __uuidof operator.

If the compiler supports the __declspec( uuid( "iid" ) ) option, an iid can be assigned to the interface this way. If the compiler does not support this option, the iid must be passed to the method as a parameter.

Sample:

This example shows how to fetch an interface from a codec.

smart_com<ICodecInterface> pItf;
if( pCodec->getInternalInterface( pItf ) == 0 )
{
    ... // interface is not supported, so error handling
}
else
{
    ... // use the interface
}
See also: Codec, smart_com

<< Codec


Codec::getName

Codec::getName Method
Returns the readable name of the codec.
Syntax:
std::string getName() const;
Return value:

The readable name of the codec.

Remarks:

toString and getName return the same text.

See also: Codec, Codec::toString

<< Codec


Codec::getSettings

Codec::getSettings Method
This method returns a string that contains the parameters of this codec / compressor.
Syntax:
std::string getSettings() const;
std::wstring getSettingsW() const;
Return value:

A string containing the codec parameters.

Remarks:

An application needs this method in order to save the current parameters of a compressor filter in a file or registry.

See also: Codec, Codec::setSettings, Codec::hasSettings

<< Codec


Codec::hasDialog

Codec::hasDialog Method
Checks whether the codec has a dialog box.
Syntax:
bool hasDialog() const;
Return value:

Value | Description
true | This codec has a property dialog box.
false | This codec does not have a property dialog box.
See also: Codec, Codec::callDialog

<< Codec


Codec::hasSettings

Codec::hasSettings Method
Checks whether setting data can be retrieved from or set to the codec.
Syntax:
bool hasSettings() const;
Return value:

Value | Description
true | This codec allows to get and set settings.
false | Setting data is not available.
See also: Codec, Codec::getSettings, Codec::setSettings

<< Codec


Codec::isVfwCodec

Codec::isVfwCodec Method
Returns whether this codec is a Video for Windows codec.
Syntax:
bool isVfwCodec() const;
Return value:

Value | Description
true | This codec is a Video for Windows codec.
false | This codec is not a Video for Windows codec.
See also: Codec

<< Codec


Codec::operator!=

Codec::operator!= Method
Determine whether two codec objects differ.
Syntax:
bool operator!=( const Codec& op ) const;

Parameter | Description
op | Another codec with which to compare.
Return value:

Value | Description
true | The operands are not equal.
false | The operands are equal.
See also: Codec, Codec::operator==

<< Codec


Codec::operator<

Codec::operator< Method
Compares the string representations of this Codec with the string representation of another one.
Syntax:
bool operator<( const Codec& op ) const;

Parameter | Description
op | Another codec with which to compare.
Return value:

Value | Description
true | The string representation of this codec comes alphabetically before the name of the object with which to compare.
false | This string representation is equal to or comes alphabetically after the name of the object with which to compare.
Remarks:

Compares the string representations of this filter info object with the string representation of another one. The return value is the result of a lexicographical comparison between the two strings.

See also: Codec, Codec::toString

<< Codec


Codec::operator==

Codec::operator== Method
Checks whether a Codec equals another codec object or its name equals a specified string.
Syntax:
bool operator==( const Codec& op ) const;
bool operator==( const std::string& op ) const;
bool operator==( const std::wstring& op ) const;

Parameter | Description
op | Another codec object or string with which to compare.
Return value:

Value | Description
true | Both operands are equal.
false | The operands are not equal.
See also: Codec, Codec::operator!=

<< Codec


Codec::setSettings

Codec::setSettings Method
This method is used to set previously retrieved codec data.
Syntax:
bool setSettings( const std::string& data );
bool setSettings( const std::wstring& data );

Parameter | Description
data | The string with the data to copy into the codec.
Return value:

Value | Description
true | The operation was successful.
false | The operation failed, i.e. because the data was retrieved from a different codec.
See also: Codec, Codec::getSettings, Codec::hasSettings

<< Codec


Codec::toString

Codec::toString Method
Returns a string representation of this object.
Syntax:
std::string toString() const;
std::wstring toStringW() const;
Return value:

A string representation of this object.

Remarks:

toString and getName return the same text.

See also: Codec, Codec::getName

<< Codec


DeBayerTransform

The DeBayerTransform class allows you to control the automatic debayering process of IC Imaging Control.

If a BY8 Bayer video format is selected, the image data will be debayered automatically. This class allows the debayering to be controlled.

Call Grabber::getDeBayerTransform to get an instance of the DeBayerTransform class. In order to check whether IC Imaging Control is going to apply automatic debayering to the image data, call the method isActive. If the camera produces raw image data in Bayer format, but does not provide a BY8 video format, the debayering can by applied to the image data explicitly by using the DeBayer frame filter that can be loaded from the StdFilter.ftf module. For more information about debayering using the DeBayer filter, please refer to Debayering.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Methods

Method | Description
getDeBayerMode | Returns the currently active debayering algorithm.
getStartPattern | Returns the currently selected start pattern.
isActive | Checks whether the image data is currently debayered by IC Imaging Control.
setDeBayerMode | Selects the algorithm for the debayering of the image data.
setStartPattern | Sets the pattern to determine how the algorithm interprets the pixels of the raw image data. It has to match the pattern of the first two pixels of the first line.

Enumerations

Enumeration | Description
tDeBayerMode | The tDeBayerMode enumeration is used to set the debayering algorithm.
tStartPattern | Enumeration containing all possible bayer start patterns of the first row of the image data.

<< Classes


DeBayerTransform::getDeBayerMode

DeBayerTransform::getDeBayerMode Method
Returns the currently active debayering algorithm.
Syntax:
tDeBayerMode getDeBayerMode() const;
Return value:

A tDeBayerMode member describing the currently selected algorithm.

See also: DeBayerTransform, DeBayerTransform::setDeBayerMode

<< DeBayerTransform


DeBayerTransform::getStartPattern

DeBayerTransform::getStartPattern Method
Returns the currently selected start pattern.
Syntax:
tStartPattern getStartPattern() const;
Return value:

A tStartPattern, describing the currently selected start pattern.

See also: DeBayerTransform, DeBayerTransform::setStartPattern

<< DeBayerTransform


DeBayerTransform::isActive

DeBayerTransform::isActive Method
Checks whether the image data is currently debayered by IC Imaging Control.
Syntax:
bool isActive() const;
Return value:

Value | Description
true | The image data is currently debayered by IC Imaging Control.
false | Otherwise.
Remarks:

Changing the settings of the DeBayerTransform class will only have an effect on the image data, if this method returns true.

See also: DeBayerTransform

<< DeBayerTransform


DeBayerTransform::setDeBayerMode

DeBayerTransform::setDeBayerMode Method
Selects the algorithm for the debayering of the image data.
Syntax:
void setDeBayerMode( tDeBayerMode b );

Parameter | Description
b | A member of the tDeBayerMode enumeration.
See also: DeBayerTransform, DeBayerTransform::getDeBayerMode

<< DeBayerTransform


DeBayerTransform::setStartPattern

DeBayerTransform::setStartPattern Method
Sets the pattern to determine how the algorithm interprets the pixels of the raw image data. It has to match the pattern of the first two pixels of the first line.
Syntax:
void setStartPattern( tStartPattern pat );

Parameter | Description
pat | A member of the tStartPattern enumeration.
Remarks:

You have to select the value that matches the layout of the camera's mosaic filter in front of the CCD. In general, this has to be found out by try and error because this information may be hard to find in the camera documentation.

See also: DeBayerTransform, DeBayerTransform::getStartPattern

<< DeBayerTransform


DeBayerTransform::tDeBayerMode
The tDeBayerMode enumeration is used to set the debayering algorithm.
Constant | Description
eNearestColor | Simplest and fastest algorithm, but lesser output image quality.
eBilinear | Algorithm with both acceptable speed and image quality.
eEdgeSensing | This algorithm creates the best image quality, but is rather slow.

<< DeBayerTransform


DeBayerTransform::tStartPattern
Enumeration containing all possible bayer start patterns of the first row of the image data.
Value | Description
eBG | The first two pixels of the pattern are interpreted as blue and green.
eGB | The first two pixels of the pattern are interpreted as green and blue.
eGR | The first two pixels of the pattern are interpreted as green and red.
eRG | The first two pixels of the pattern are interpreted as red and green.

<< DeBayerTransform


FilterLoader

This static class contains methods to create instances of frame filters that are loaded from filter modules ( *.ftf ).

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Methods

Method | Description
createFilter | Creates a frame filter instance.
getAvailableFrameFilters | Returns a std::vector of FilterInfo structures containing information about the available frame filters.
setLoadPath | Sets a path from where the filter modules are loaded.

<< Classes


FilterLoader::createFilter

FilterLoader::createFilter Method
Creates a frame filter instance.
Syntax:
static smart_com<IFrameFilter> createFilter( const FilterInfo& fi );
static smart_com<IFrameFilter> createFilter( const std::string& filter_name,
                                             const std::string& module = std::string() );
static smart_com<IFrameFilter> createFilter( const std::wstring& filter_name,
                                             const std::wstring& module = std::wstring() );

Parameter | Description
fi | FilterInfo structure, describing the filter to create. FilterLoader::getAvailableFrameFilters returns a list of FilterInfo structures, which you can pass to this method.
filter_name | Name of the frame filter to create.
module | Path to the module in which the frame filter to be created is implemented.
Return value:

This method returns a smart_com to an IFrameFilter interface of the created frame filter. The pointer is 0, when the filter could not be created.

Remarks:

When a combination of filter_name and module is passed to this method, it will look in the list of available frame filters for a filter matching the specified values.

When the module parameter is omitted, the filter loader create an instance of the first frame filter implementation it finds with a matching name.

Example:

The following code creates an instance of the Rotate Flip filter in stdfilters.ftf and sets it as device frame filter:

smart_com<IFrameFilter> pRotFlipFilter = FilterLoader::createFilter( "Rotate Flip" );
grabber.setDeviceFrameFilters( pRotFlipFilter.get() );
See also: FilterLoader, FilterLoader::getAvailableFrameFilters

<< FilterLoader


FilterLoader::getAvailableFrameFilters

FilterLoader::getAvailableFrameFilters Method
Returns a std::vector of FilterInfo structures containing information about the available frame filters.
Syntax:
static std::vector<FilterInfo> getAvailableFrameFilters( tFilterClass filterClass = eFC_ALL );
Parameter Description
filterClass

You can restrict the number of filters that will appear in the vector by specifying one or more filter classes. Valid filter classes are members of the tFilterClass enumeration:

Value | Description
eFC_GENERIC | List filters that are flagged as generic. Generic filters should work in any environment without special knowledge about the parameters.
eFC_INTERNAL | List filters that are flagged as internal. Internal filters are not guaranteed to work in generic applications that do not know how to setup the filter's parameters in the required way (e.g. specifying a valid filename for a filter that saves an image buffer).
eFC_ALL | List all available frame filters.
Return value:

A std::vector of FilterInfo structures containing information about the available frame filters.

Remarks:

Frame filters are loaded from: i) the directory of the applications's executable, ii) the directory of the loaded TIS_UDSHL0X_vcYY.DLL and iii) the directory specified to setLoadPath.

Example:

The following code prints information about the available frame filters to the console:

void printAvailableFrameFilters()
{
    std::vector<FilterInfo> filterInfos = FilterLoader::getAvailableFrameFilters();

    std::cout << "Available frame filters:" << std::endl;
    for( unsigned int i = 0; i < filterInfos.size(); ++i )
    {
        std::cout << i << ":" << std::endl;

        std::cout << "Name: " << filterInfos[i].getFilterName() << std::endl;
        std::cout << "Module: " << filterInfos[i].getModuleName() << std::endl;
        std::cout << "Path: " << filterInfos[i].getModulePath() << std::endl;
        std::cout << "Filter class: ";
        switch(  filterInfos[i].getFilterClass() )
        {
        case eFC_GENERIC:
            std::cout << "generic" << std::endl;
            break;
        case eFC_INTERNAL:
            std::cout << "internal" << std::endl;
            break;
        default:
            std::cout << "unknown" << std::endl;
            break;
        }
    }
    std::cout << std::endl;
}
See also: FilterLoader, FilterLoader::setLoadPath, FilterLoader::createFilter

<< FilterLoader


FilterLoader::setLoadPath

FilterLoader::setLoadPath Method
Sets a path from where the filter modules are loaded.
Syntax:
static void setLoadPath( const std::wstring& path );

Parameter | Description
path | The path to be searched for frame filters.
Remarks:

Calling this function resets the list of available frame filters.

Frame filters are loaded from: i) the directory of the applications's executable, ii) the directory of the loaded TIS_UDSHLXX_vcYY.DLL and iii) the directory specified by setLoadPath.

See also: FilterLoader

<< FilterLoader


FrameHandlerSink

The FrameHandlerSink is the SinkType used to grab (copy) frames from the image stream. It replaces the deprecated FrameGrabberSink and contains a MemBufferCollection and optionally allows you to specify one or more IFrameFilters that are responsible for copying the image data to the buffers of the MemBufferCollection. The IFrameFilter implementation can perform user-defined transformations while copying the data, and they can intentionally drop unwanted frames. If no frame filter is registered, the frames are copied to the MemBufferCollection without being changed.

Frames are copied one after another to the MemBufferCollection, starting with the first buffer of the collection. When a frame is copied into the last buffer, the next frame is copied to the first buffer and so on.

The FrameHandlerSink can operate in snap mode, or in grab mode. The mode can be toggled by calling the method setSnapMode. In grab mode, frames are copied continuously to the MemBufferCollection, as soon as Grabber::startLive is called. A call to Grabber::stopLive ends the copy process. On the other hand, in snap mode, every call to FrameHandlerSink::snapImages or FrameHandlerSink::snapImagesAsync copies the specified number of frames to the MemBufferCollection. Grabber::startLive has to be called before any call to FrameHandlerSink::snapImages.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Inheritance

GrabberSinkType
FrameHandlerSink

Methods

Method | Description
create | Creates a new FrameHandlerSink.
getCreateData | Returns a tCreateData structure, containing the information that was used to create this instance.
getFrameCount | Returns the number of frames that were copied into this MemBufferCollection since the last call to Grabber::startLive.
getFrameFilters | Returns the currently set list of IFrameFilters.
getLastAcqMemBuffer | Returns the MemBuffer, in which the last frame was fully copied. Each restart of the sink sets the start of the MemBufferCollection to the first buffer. After stopping the sink, this function returns the last acquired frame until the sink is restarted.
getMemBufferCollection | Returns the current MemBufferCollection.
getOutputFrameType | Returns the frame type of the sink. This is the frame type of the MemBufferCollection or the output frame type of the handler, when no MemBufferCollection is set.
getSinkType | This implementation of GrabberSinkType::getSinkType returns eFRAMEHANDLER_SINK.
getSnapMode | Returns whether this FrameHandlerSink is currently in snap mode.
setMemBufferCollection | Sets a MemBufferCollection for this FrameHandlerSink.
setSnapMode | Changes this sink's operating mode between Grab and Snap mode. In grab mode, all frames reaching the sink are presented to the frame filter or filter chain and then copied into the MemBufferCollection. After that, the frameReady event of the GrabberListener is called. In snap mode, snapImages or snapImagesAsync has to be called in order to trigger the image acquisition process.
snapImages | Queues up a snap job, thus allowing a number of frames to be copied into the MemBufferCollection. The method returns when either the specified number of frames are snapped, or the timeout has occurred.
snapImagesAsync | Queues up a snap job, thus copying a number of frames into the MemBufferCollection. The method returns immediately after queuing the job.

Structs

Struct | Description
tCreateData | This structure describes the parameters that were used to create a FrameHandlerSink. You can access the tCreateData of a FrameHandlerSink by calling FrameHandlerSink::getCreateData, and passing it to FrameHandlerSink::create to create a similar FrameHandlerSink.

<< Classes


GrabberSinkType

This is the abstract base class for all sinks which cannot be instantiated. A sink specifies the format to which the image stream is converted and it specifies the way in which single frames can be accessed.

Information

Header File: tisudshl.h
Namespace: DShowLib

Inheritance

GrabberSinkType
FrameGrabberSink
FrameHandlerSink
MediaStreamSink
AviSink

Methods

Method | Description
getSinkMode | This method returns the current sink mode.
getSinkType | This virtual function has to return the type of the derived GrabberSinkType.
isAttached | Returns whether this sink has been attached to a Grabber object.
setSinkMode | This method sets a new sink mode.

Enumerations

Enumeration | Description
tSinkModes | tSinkModes enumerates the available sink modes.

<< Classes


GrabberSinkType::getSinkMode

GrabberSinkType::getSinkMode Method
This method returns the current sink mode.
Syntax:
virtual tSinkModes getSinkMode() const;
Return value:

The current sink mode. The possible modes are described at GrabberSinkType::tSinkModes.

See also: GrabberSinkType::setSinkMode, GrabberSinkType::tSinkModes

<< GrabberSinkType


GrabberSinkType::getSinkType

GrabberSinkType::getSinkType Method
This virtual function has to return the type of the derived GrabberSinkType.
Syntax:
virtual tSinkType getSinkType() const = 0;
Return value:

The type of the derived sink.

See also: tSinkType

<< GrabberSinkType


GrabberSinkType::isAttached

GrabberSinkType::isAttached Method
Returns whether this sink has been attached to a Grabber object.
Syntax:
virtual bool isAttached() const;
Return value:

This method returns true, if this sink is currently attached to a Grabber object, otherwise false.

Remarks:

When the sink is created, this method initially returns false. Once it has been attached to a Grabber by calling Grabber::setSinkType, this method returns true. When another sink is assigned to the grabber, this sink becomes unattached and this method returns false again.

See also: GrabberSinkType, Grabber, Grabber::setSinkType

<< GrabberSinkType


GrabberSinkType::setSinkMode

GrabberSinkType::setSinkMode Method
This method sets a new sink mode.
Syntax:
virtual tSinkModes setSinkMode( tSinkModes mode );

Parameter | Description
mode | Specifies the new mode to set.
Return value:

The current sink mode. On success, the returned sink mode is identical to the sink mode passed to the function.

Remarks:

This method is used to pause and restart a image stream for avi capturing and frame grabbing. After the sink mode is set to ePAUSE, frame grabbing and avi saving will not start before the sink mode is set to eRUN.

If the sink mode is set to ePAUSE and startLive() is called, the live video is displayed (if enabled) but no frames are passed to the sink. Now, an application can pass eRun to setSinkMode to start avi capturing or frame grabbing without latency because the image stream is already initialized.

Example:

This example demonstrates how to set the sink mode after it was created.

// Create an MediaStreamSink to record an AVI file with the selected CoDec
tMediaStreamSinkPtr pSink = MediaStreamSink::create(
    MediaStreamContainer::create( MSC_AviContainer ), pCodecs->at( choice ) );

// Set the filename.
pSink->setFilename( filename );

// The sink is initially paused, so that no video data is written to the file.
pSink->setSinkMode( GrabberSinkType::ePAUSE );

// Set pSink as the current sink.
grabber.setSinkType( pSink );

// Start the live mode. The live video will be displayed but no images will be written
// to the AVI file because pSink is in pause mode.
if( !grabber.startLive( true ) )
{
    std::cerr << grabber.getLastError().toString() << std::endl;
    return -1;
}

std::cout << "Press [enter] to start capturing!";
std::cin.get();

// Start the sink. The image stream is written to the AVI file.
pSink->setSinkMode(GrabberSinkType::eRUN );

std::cout << "Video recording started." << std::endl;
std::cout << "Press [enter] to stop capturing!";
std::cin.get();

// Pause the sink. This stops writing the image stream to the AVI file.
// A subsequent call to setSinkMode with GrabberSinkType::eRUN as the
// parameter would restart AVI recording.
pSink->setSinkMode(GrabberSinkType::ePAUSE );

std::cout << "Video recording stopped." << std::endl;

// Stop the live mode. This stops writing images to the AVI file if the mode is not
// GrabberSinkType::ePAUSE. The AVI file is closed.
grabber.stopLive();
See also: GrabberSinkType::getSinkMode, GrabberSinkType::tSinkModes

<< GrabberSinkType


GrabberSinkType::tSinkModes
tSinkModes enumerates the available sink modes.
Enumeration | Description
eRUN | Starts avi capturing or frame grabbing.
ePAUSE | Pauses avi capturing or frame grabbing.
eUNCONNECTED | This mode cannot be set, it is only valid if the image stream or the sink is not initialized.

<< GrabberSinkType


FrameHandlerSink::create

FrameHandlerSink::create Method
Creates a new FrameHandlerSink.
Syntax:
static tFrameHandlerSinkPtr create( unsigned int countBuffers );
static tFrameHandlerSinkPtr create( IFrameFilter* pFilter,
                                    unsigned int countBuffers = 0 );
static tFrameHandlerSinkPtr create( const tFrameFilterList& lst,
                                    unsigned int countBuffers = 0 );

static tFrameHandlerSinkPtr create( IFrameFilter* pFilter,
                                    const FrameTypeInfo& type,
                                    unsigned int countBuffers );
static tFrameHandlerSinkPtr create( const tFrameFilterList& lst,
                                    const FrameTypeInfo& type,
                                    unsigned int countBuffers );
static tFrameHandlerSinkPtr create( IFrameFilter* pFilter,
                                    const smart_ptr<MemBufferCollection>& pCol );
static tFrameHandlerSinkPtr create( const tFrameFilterList& lst,
                                    const smart_ptr<MemBufferCollection>& pCol );

static tFrameHandlerSinkPtr create( const smart_ptr<MemBufferCollection>& pCol );
static tFrameHandlerSinkPtr create( const FrameTypeInfo& type,
                                    unsigned int countBuffers );
static tFrameHandlerSinkPtr create( tColorformatEnum colorformat,
                                    unsigned int countBuffers );
static tFrameHandlerSinkPtr create( const FrameTypeInfoArray& acceptedInputTypes,
                                    unsigned int countBuffers );

static tFrameHandlerSinkPtr create( const tCreateData& data );

Parameter | Description
countBuffers | The number of buffers to create in the MemBufferCollection. When countBuffers is 0, no MemBufferCollection is created. In this case, the frame filter (or the last filter of the filter chain) is called with no destination frame. In this kind of filter, you can perform image analysis similar to the GrabberListener approach, but the time of one copy operation is saved, because the image data is not copied into the MemBufferCollection.
pFilter | The frame filter for the transform/copy operation.
lst | A tFrameFilterList of frame filters. The filters in this list are connected in a filter chain that is used to transform the image data.
type | The image data type in the MemBufferCollection.
colorformat | The image data color format in the MemBufferCollection.
pCol | Pointer to a custom MemBufferCollection.
acceptedInputTypes | A FrameTypeInfoArray of allowed frame types that this sink accepts. When the live video is started, one of these types is selected in order to minimize the necessary conversion operations.
data | To duplicate a FrameHandlerSink, you can call FrameHandlerSink::getCreateData to access the parameters with which it was created. You can use this tCreateData structure to initialize another FrameHandlerSink.
Return Value:

A pointer to the new FrameHandlerSink, or 0, if an error occurred.

Examples:

The simplest way to create a FrameHandlerSink is to only specify the number of MemBuffers in the MemBufferCollection of the sink:

// Create a sink containing a MemBufferCollection of 5 buffers.
// The buffer format will be selected automatically.
tFrameHandlerSinkPtr pSink = FrameHandlerSink::create( 5 );

// Set the sink.
m_Grabber.setSinkType( pSink );

You can select the format of the MemBuffers in the MemBufferCollection by specifying a FrameTypeInfo. Because FrameTypeInfo has a constructor that takes a tColorformatEnum, you can use eRGB24, eRGB32 to select the buffer format:

// Create a sink containing a MemBufferCollection of 3 RGB24 buffers.
tFrameHandlerSinkPtr pSink = FrameHandlerSink::create( eRGB24, 3 );

// Set the sink.
m_Grabber.setSinkType( pSink );

You can customize the copy operation to the MemBuffers using frame filters. Use FilterLoader to load a frame filter from stdfilters.ftf:

// Load the Rotate/Flip filter from stdfilters.ftf
m_pRotFlipFilter = FilterLoader::createFilter( "Rotate Flip" );
// Enable vertical flip.
m_pRotFlipFilter->setParameter( "flipv", true );

// Create a sink, using this frame filter to copy the image data into
// a MemBufferCollection of 5 RGB24 buffers.
//
// Note: m_pRotFlipFilter.get() is used to get a plain pointer from the smart_com.
//       The smart_com must not be deleted, while it is being used by the sink.
tFrameHandlerSinkPtr pSink = FrameHandlerSink::create( m_pRotFlipFilter.get(), eRGB24, 5 );

// Set the sink.
m_Grabber.setSinkType( pSink );

To create a filter chain, load multiple filters and insert them into a tFrameFilterList. If you pass a list of frame filters to FrameHandlerSink::create, the transform functions of the filters will be called to transform and copy the image data into the MemBufferCollection:

// Load the Rotate/Flip filter from stdfilters.ftf
m_pRotFlipFilter = FilterLoader::createFilter( "Rotate Flip" );
// Enable horizontal flip.
m_pRotFlipFilter->setParameter( "fliph", true );

// Load the ROI filter from stdfilters.ftf
m_pROIFilter = FilterLoader::createFilter( "ROI" );
// Set an ROI.
m_pROIFilter->setParameter( "X", 10 );
m_pROIFilter->setParameter( "Y", 10 );
m_pROIFilter->setParameter( "Width", 100 );
m_pROIFilter->setParameter( "Height", 100 );

// Create a filter chain using these two filters, by putting them into a
// tFrameFilterList.
//
// Note: .get() is used to get a plain pointer from the smart_com.
//       The smart_com's must not be deleted while it is being used by the sink.
tFrameFilterList filterChain;
filterChain.push_back( m_pRotFlipFilter.get() );
filterChain.push_back( m_pROIFilter.get() );

// Create a sink, using this frame filter chain to copy the image data into
// a MemBufferCollection of 3 Y800 buffers.
tFrameHandlerSinkPtr pSink = FrameHandlerSink::create( filterChain, eY800, 3 );

// Set the sink.
m_Grabber.setSinkType( pSink );
See also: FrameHandlerSink, tFrameHandlerSinkPtr, MemBufferCollection, IFrameFilter, FrameTypeInfo, FrameTypeInfoArray, tFrameFilterList

<< FrameHandlerSink


FrameHandlerSink::getCreateData

FrameHandlerSink::getCreateData Method
Returns a tCreateData structure, containing the information that was used to create this instance.
Syntax:
const tCreateData& getCreateData() const;
Return Value:

A tCreateData structure containing the information that was used to create this instance.

Remarks:

The returned tCreateData structure is a snapshot of the parameters that were used to create the sink. Later changed, such as swapping the MemBufferCollection, are not reflected in the returned data.

See also: FrameHandlerSink, FrameHandlerSink::tCreateData

<< FrameHandlerSink


FrameHandlerSink::getFrameCount

FrameHandlerSink::getFrameCount Method
Returns the number of frames that were copied into this MemBufferCollection since the last call to Grabber::startLive.
Syntax:
unsigned int getFrameCount() const;
Return Value:

The number of frames that were copied into the MemBufferCollection.

See also: FrameHandlerSink, MemBufferCollection

<< FrameHandlerSink


FrameHandlerSink::getFrameFilters

FrameHandlerSink::getFrameFilters Method
Returns the currently set list of IFrameFilters.
Syntax:
const tFrameFilterList getFrameFilters() const;
Return Value:

This function returns a tFrameFilterList containing pointers to the filters that were passed to FrameHandlerSink::create.

Remarks:

When one frame filter was set by passing a pointer to it in FrameHandlerSink::create, the return value is a list containing that pointer.

See also: FrameHandlerSink, IFrameFilter, tFrameFilterList

<< FrameHandlerSink


FrameHandlerSink::getLastAcqMemBuffer

FrameHandlerSink::getLastAcqMemBuffer Method
Returns the MemBuffer, in which the last frame was fully copied. Each restart of the sink sets the start of the MemBufferCollection to the first buffer. After stopping the sink, this function returns the last acquired frame until the sink is restarted.
Syntax:
smart_ptr<MemBuffer> getLastAcqMemBuffer() const;
Return Value:

The last filler MemBuffer This function returns 0, if no frame has yet been acquired, or no MemBufferCollection is set.

See also: FrameHandlerSink, FrameHandlerSink::create, MemBufferCollection, MemBuffer

<< FrameHandlerSink


FrameHandlerSink::getMemBufferCollection

FrameHandlerSink::getMemBufferCollection Method
Returns the current MemBufferCollection.
Syntax:
smart_ptr<MemBufferCollection> getMemBufferCollection() const;
Return Value:

The current MemBufferCollection. The function returns 0, if no collection is used.

See also: FrameHandlerSink, FrameHandlerSink::create, MemBufferCollection

<< FrameHandlerSink


FrameHandlerSink::getOutputFrameType

FrameHandlerSink::getOutputFrameType Method
Returns the frame type of the sink. This is the frame type of the MemBufferCollection or the output frame type of the handler, when no MemBufferCollection is set.
Syntax:
bool getOutputFrameType( FrameTypeInfo& info ) const;

Parameter | Description
info | If the information is available, info is filled with the output frame type of the sink.
Return Value:

true, if the information is available and info was filled with the according data, otherwise false.

See also: FrameHandlerSink, FrameTypeInfo

<< FrameHandlerSink


FrameHandlerSink::getSinkType

FrameHandlerSink::getSinkType Method
This implementation of GrabberSinkType::getSinkType returns eFRAMEHANDLER_SINK.
Syntax:
tSinkType getSinkType() const;
Return Value:

eFRAMEHANDLER_SINK
See also: FrameHandlerSink, GrabberSinkType::getSinkType

<< FrameHandlerSink


FrameHandlerSink::getSnapMode

FrameHandlerSink::getSnapMode Method
Returns whether this FrameHandlerSink is currently in snap mode.
Syntax:
bool getSnapMode() const;
Return Value:

Value | Description
true | The sink is in snap mode.
false | The sink is in grab mode.
See also: FrameHandlerSink, FrameHandlerSink::setSnapMode

<< FrameHandlerSink


FrameHandlerSink::setMemBufferCollection

FrameHandlerSink::setMemBufferCollection Method
Sets a MemBufferCollection for this FrameHandlerSink.
Syntax:
bool setMemBufferCollection( const smart_ptr<MemBufferCollection>& pCol );

Parameter | Description
pCol | The new MemBufferCollection, or 0 to remove the one that is currently set.
Return Value:

true, if the new MemBufferCollection was successfully set, otherwise false.

Remarks:

The frame type of the MemBufferCollection must match the output frame type of the registered IFrameFilter or the input type of the sink, if no transform handler is registered.

See also: FrameHandlerSink, MemBufferCollection

<< FrameHandlerSink


FrameHandlerSink::setSnapMode

FrameHandlerSink::setSnapMode Method
Changes this sink's operating mode between Grab and Snap mode. In grab mode, all frames reaching the sink are presented to the frame filter or filter chain and then copied into the MemBufferCollection. After that, the frameReady event of the GrabberListener is called. In snap mode, snapImages or snapImagesAsync has to be called in order to trigger the image acquisition process.
Syntax:
void setSnapMode( bool mode );

Parameter | Description
mode | A boolean determining the new snap mode.
Example:

The following example shows how to create a sink that runs in continuous mode:

{
// Create a sink, containing a MemBufferCollection of 5 buffers.
tFrameHandlerSinkPtr pSink = FrameHandlerSink::create( 5 );

// Disable snap mode.
pSink->setSnapMode( false );

// Set the sink.
m_Grabber.setSinkType( pSink );
}
See also: FrameHandlerSink, IFrameFilter, MemBufferCollection, GrabberListener, FrameHandlerSink::getSnapMode

<< FrameHandlerSink


FrameHandlerSink::snapImages

FrameHandlerSink::snapImages Method
Queues up a snap job, thus allowing a number of frames to be copied into the MemBufferCollection. The method returns when either the specified number of frames are snapped, or the timeout has occurred.
Syntax:
Error snapImages( unsigned int count, DWORD timeout = INFINITE );

Parameter | Description
count | Number of frames to copy into the MemBufferCollection.
timeout | Number of milliseconds to wait before returning from this function, should no frames be available from the device.
Return Value:

An error object reporting the status of the performed operation. Use Error::isError to check whether the operation was successful.

Remarks:

If the method runs into a timeout, it is not guaranteed, that count frames are snapped. In the case of a timeout, it is possible that by the time this method has returned, GrabberListener::frameReady has already been called.

If live mode has not been started, this method starts live mode before grabbing the image and stops live mode afterward. Because starting live mode is a very time-consuming operation, it is usually preferable to start live mode before calling snapImage more than once.

Example:

The following example shows how to snap an image and save it to a bitmap file. It assumes that a FrameHandlerSink, containing a MemBufferCollection has been setup using FrameHandlerSink::create and assigned to the grabber with Grabber::setSinkType.

// This cast is only valid, if we have previously assigned a FrameHandlerSink to the grabber.
tFrameHandlerSinkPtr pSink = m_Grabber.getSinkTypePtr();

// Snap one image and copy it into the MemBufferCollection.
Error e = pSink->snapImages( 1 );
if( e.isError() )
{
    // Display an error.
    ::MessageBox( 0, e.toString().c_str(), "Error", MB_OK|MB_ICONERROR );
}
else
{
    // Save the image to a bitmap file.
    pSink->getLastAcqMemBuffer()->save( "image.bmp" );
}
See also: FrameHandlerSink, FrameHandlerSink::snapImagesAsync

<< FrameHandlerSink


FrameHandlerSink::snapImagesAsync

FrameHandlerSink::snapImagesAsync Method
Queues up a snap job, thus copying a number of frames into the MemBufferCollection. The method returns immediately after queuing the job.
Syntax:
Error snapImagesAsync( unsigned int count );

Parameter | Description
count | Number of frames to copy into the MemBufferCollection.
Return Value:

An error object, reporting the status of the performed operation.

Remarks:

You cannot terminate this snap job unless you stop live mode by calling Grabber::stopLive.

See also: FrameHandlerSink, FrameHandlerSink::snapImages

<< FrameHandlerSink


FrameHandlerSink::tCreateData

FrameHandlerSink::tCreateData Structure
This structure describes the parameters that were used to create a FrameHandlerSink. You can access the tCreateData of a FrameHandlerSink by calling FrameHandlerSink::getCreateData, and passing it to FrameHandlerSink::create to create a similar FrameHandlerSink.
Syntax:
struct tCreateData {
    tCreateData( unsigned int countBuffers );
    tCreateData( IFrameFilter* pFilter, unsigned int countBuffers = 0 );
    tCreateData( const tFrameFilterList& lst, unsigned int countBuffers = 0 );
    tCreateData( IFrameFilter* pFilter, const FrameTypeInfo& type, unsigned int countBuffers );
    tCreateData( const tFrameFilterList& lst, const FrameTypeInfo& type, unsigned int countBuffers );
    tCreateData( IFrameFilter* pFilter, const smart_ptr<MemBufferCollection>& pCol );
    tCreateData( const tFrameFilterList& lst, const smart_ptr<MemBufferCollection>& pCol );

    tCreateData( const smart_ptr<MemBufferCollection>& pCol );
    tCreateData( const FrameTypeInfo& type, unsigned int countBuffers );
    tCreateData( const FrameTypeInfoArray& acceptedInputTypes, unsigned int countBuffers );

    unsigned int                   m_BufferCount;

    FrameTypeInfoArray             m_FrameTypes;
    smart_ptr<MemBufferCollection> m_pCollection;

    tFrameFilterList               m_filterChain;
};

Value | Description
m_BufferCount | Specifies the number of buffers in the MemBufferCollection.
m_FrameTypes | Specifies the allowed frame types of the MemBufferCollection.
m_pCollection | Specifies a custom MemBufferCollection
m_filterChain | Specifies a chain of IFrameFilters.

<< FrameHandlerSink


IFrameFilter

IFrameFilter is the base class of all frame filters. It contains methods to access the filter's parameters, display a configuration dialog and save filter settings. This class provides the interface to use an existing filter.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Inheritance

IFrameFilter
FrameFilterImpl
FrameUpdateFilterImpl

Methods

Method | Description
beginParamTransfer | beginParamTransfer and endParamTransfer synchronize the access to a frame filter's parameters.
callDialog | This method calls a dialog box, if the filter has one.
endParamTransfer | beginParamTransfer and endParamTransfer synchronize the access to a frame filter's parameters.
getAvailableParameters | Returns the available parameters of a frame filter.
getData | Reads a data parameter. A data parameter allows the the filter to provide a raw block of data to the user.
getDataLength | Returns the length of the blob that can be read using getData.
getFilterInfo | This method returns a FilterInfo structure, containing information about the name of the filter and the directory from which it was loaded.
getParameter | Reads a frame filter parameter.
getSettings | This method returns a string that contains all parameters of this filter.
hasDialog | Checks whether the filter has a dialog box.
setData | Sets a data parameter. A data parameter allows the user to copy a raw blob into the filter.
setParameter | Sets a frame filter parameter.
setSettings | This method is used to set previously retrieved filter settings.

Enumerations

Enumeration | Description
tParamType | Enumeration that describes the type of a frame filter parameter.

Structs

Struct | Description
ParamDesc | The ParamDesc structure, describes a frame filter parameter. You can retrieve a tParamArray, containing ParamDesc structures by calling IFrameFilter::getAvailableParameters.

Type Definitions

Type | Description
tParamArray | tParamArray is a std::vector of ParamDesc structures.

<< Classes


IFrameFilter::beginParamTransfer

IFrameFilter::beginParamTransfer Method
beginParamTransfer and endParamTransfer synchronize the access to a frame filter's parameters.
Syntax:
void beginParamTransfer() const;
Remarks:

This method acquires a lock that has to be released using endParamTransfer as soon as possible.

Example:

All calls to setData have to be inside a beginParamTransfer / endParamTransfer block:

pFrameFilter->beginParamTransfer();

// All calls to setParameter and getParameter here...

pFrameFilter->endParamTransfer();

For an example how to set or read parameters, see IFrameFilter::setParameter or IFrameFilter::getParameter.

See also: IFrameFilter, IFrameFilter::endParamTransfer

<< IFrameFilter


IFrameFilter::callDialog

IFrameFilter::callDialog Method
This method calls a dialog box, if the filter has one.
Syntax:
virtual bool callDialog( HWND hParent = 0 );

Parameter | Description
hParent | Specifies the parent window of the dialog box to show.
Return value:

Value | Description
true | The dialog box was successfully displayed.
false | An error occurred.
Remarks:

Depending on the filter implementation this method may block until the dialog box is closed.

See also: IFrameFilter, IFrameFilter::hasDialog

<< IFrameFilter


IFrameFilter::endParamTransfer

IFrameFilter::endParamTransfer Method
beginParamTransfer and endParamTransfer synchronize the access to a frame filter's parameters.
Syntax:
void endParamTransfer() const;
Example:

All calls to setData have to be inside a beginParamTransfer / endParamTransfer block:

pFrameFilter->beginParamTransfer();

// All calls to setParameter and getParameter here...

pFrameFilter->endParamTransfer();

For an example how to set or read parameters, see IFrameFilter::setParameter or IFrameFilter::getParameter.

See also: IFrameFilter, IFrameFilter::beginParamTransfer

<< IFrameFilter


IFrameFilter::getAvailableParameters

IFrameFilter::getAvailableParameters Method
Returns the available parameters of a frame filter.
Syntax:
tParamArray getAvailableParameters() const;
Return Value:

A tParamArray containing descriptions of all available parameters of this filter.

See also: IFrameFilter, IFrameFilter::tParamArray, IFrameFilter::setParameter, IFrameFilter::getParameter

<< IFrameFilter


IFrameFilter::getData

IFrameFilter::getData Method
Reads a data parameter. A data parameter allows the the filter to provide a raw block of data to the user.
Syntax:
tFilterError getData( const std::string& name, void* pData, size_t& length );
tFilterError getData( const std::wstring& name, void* pData, size_t& length );

Parameter | Description
name | The name of the data parameter to be read.
pData | A pointer to a buffer that receives the data. Has to be at least length bytes in length.
length | Length of the buffer pointed to by pData.
Return Value:

A member of the tFilterError enumeration:

Value | Description
eNO_ERROR | The data was read successfully.
ePARAM_NOT_FOUND | The filter does not have a parameter with the specified name. To obtain a list with the valid parameters, use getAvailableParameters.
eINCOMPATIBLE_PARAM_VALUE | name is not a data parameter. To obtain a list with the valid parameters and its types, use getAvailableParameters.
eINVALID_FILTER_STATE | The filter could return the data, because it is in a state that prevents the data from being read, e.g. not in live mode.
Remarks:

All calls to setData have to be inside a beginParamTransfer / endParamTransfer block.

See also: IFrameFilter, IFrameFilter::setData, IFrameFilter::getDataLength, IFrameFilter::getAvailableParameters

<< IFrameFilter


IFrameFilter::getDataLength

IFrameFilter::getDataLength Method
Returns the length of the blob that can be read using getData.
Syntax:
tFilterError getDataLength( const std::string& name, size_t& length );
tFilterError getDataLength( const std::wstring& name, size_t& length );

Parameter | Description
name | The name of the data parameter which size is determined.
length | This parameter receives the required size of the buffer for the next call to getData.
Return Value:

A member of the tFilterError enumeration:

Value | Description
eNO_ERROR | The data size was read successfully.
ePARAM_NOT_FOUND | The filter does not have a parameter with the specified name. To obtain a list with the valid parameters, use getAvailableParameters.
eINCOMPATIBLE_PARAM_VALUE | name is not a data parameter. To obtain a list with the valid parameters and its types, use getAvailableParameters.
eINVALID_FILTER_STATE | The filter could return the data size, because it is in a state that prevents the data size from being determined, e.g. not in live mode.
See also: IFrameFilter, IFrameFilter::getData, IFrameFilter::getAvailableParameters

<< IFrameFilter


IFrameFilter::getFilterInfo

IFrameFilter::getFilterInfo Method
This method returns a FilterInfo structure, containing information about the name of the filter and the directory from which it was loaded.
Syntax:
FilterInfo getFilterInfo() const;
Return Value:

A FilterInfo structure filled with the filter's name, module and filter class.

Example:

The following example prints information about the filters in a filter chain to the console. The information is retrieved using the getFilterInfo method.

void printFilterList( const tFrameFilterList& filters )
{
    std::cout << "Filter Chain:" << std::endl;
    for( unsigned int i = 0; i < filters.size(); ++i )
    {
        std::cout << i << ":" << std::endl;

        FilterInfo fi = filters[i]->getFilterInfo();
        std::cout << "Name: " << fi.getFilterName() << std::endl;
        std::cout << "Module: " << fi.getModuleName() << std::endl;
        std::cout << "Path: " << fi.getModulePath() << std::endl;
        std::cout << "Filter class: ";
        switch( fi.getFilterClass() )
        {
        case eFC_GENERIC:
            std::cout << "generic" << std::endl;
            break;
        case eFC_INTERNAL:
            std::cout << "internal" << std::endl;
            break;
        default:
            std::cout << "unknown" << std::endl;
            break;
        }
    }
    std::cout << std::endl;
}
See also: IFrameFilter, IFrameFilter::getAvailableParameters

<< IFrameFilter


IFrameFilter::getParameter

IFrameFilter::getParameter Method
Reads a frame filter parameter.
Syntax:
tFilterError getParameter( const std::string& name, std::string& value );
tFilterError getParameter( const std::string& name, bool& value );
tFilterError getParameter( const std::string& name, long& value );
tFilterError getParameter( const std::string& name, int& value );
tFilterError getParameter( const std::string& name, float& value );
tFilterError getParameter( const std::wstring& name, std::wstring& value );
tFilterError getParameter( const std::wstring& name, bool& value );
tFilterError getParameter( const std::wstring& name, long& value );
tFilterError getParameter( const std::wstring& name, int& value );
tFilterError getParameter( const std::wstring& name, float& value );

Parameter | Description
name | The name of the parameter to be read.
value | This parameter receives the current value of the parameter.
Return Value:

A member of the tFilterError enumeration.

Value | Description
eNO_ERROR | The parameter was read successfully.
ePARAM_NOT_FOUND | The filter does not have a parameter with the specified name. To obtain a list with the valid parameters, use getAvailableParameters.
eINCOMPATIBLE_PARAM_VALUE | The type of the value does not match the data type of the parameter. To obtain a list with the valid parameters and its types, use getAvailableParameters.
eINVALID_FILTER_STATE | The filter could return a value for the parameter, because it is in a state that prevents the parameter from being read, e.g. not in live mode.
Remarks:

All calls to getParameter have to be inside a beginParamTransfer / endParamTransfer block. Especially when reading multiple parameters, such as X/Y-coordinates, this is important to ensure parameter consistency.

To save all parameters of a frame filter, use IFrameFilter::getSettings.

Example:

The following example shows how to get the parameters of a frame filter. Assume a frame filter was loaded and set with the following code:

smart_com<IFrameFilter> pRotFlipFilter = FilterLoader::createFilter( "Rotate Flip" );
grabber.setDeviceFrameFilters( pRotFlipFilter.get() );

The parameters are read using beginParamTransfer, getParameter and endParamTransfer:

pRotFlipFilter->beginParamTransfer();

long rot = 0;
if( eNO_ERROR != pRotFlipFilter->getParameter( "Rotation Angle", rot ) )
{
    std::cerr << "Error getting parameter 'rotation'" << std::endl;
}
else
{
    std::cout << "Rotation Angle = " << rot << std::endl;
}

bool flipH = false;
if( eNO_ERROR != pRotFlipFilter->setParameter( "Flip H", flipH ) )
{
    std::cerr << "Error getting parameter 'fliph'" << std::endl;
}
else
{
    std::cout << "Flip H = " << flipH << std::endl;
}

bool flipV = false;
if( eNO_ERROR != pRotFlipFilter->setParameter( "Flip V", flipV ) )
{
    std::cerr << "Error getting parameter 'flipv'" << std::endl;
}
else
{
    std::cout << "Flip V = " << flipV << std::endl;
}

pRotFlipFilter->endParamTransfer();
See also: IFrameFilter, IFrameFilter::setParameter, IFrameFilter::getAvailableParameters, IFrameFilter::beginParamTransfer, IFrameFilter::endParamTransfer

<< IFrameFilter


IFrameFilter::getSettings

IFrameFilter::getSettings Method
This method returns a string that contains all parameters of this filter.
Syntax:
std::string getSettings() const;
std::wstring getSettingsW() const;
Return value:

A string containing the filter parameters.

Remarks:

An application needs this method in order to save the current parameters of a filter in a file or registry.

See also: IFrameFilter, IFrameFilter::setSettings

<< IFrameFilter


IFrameFilter::hasDialog

IFrameFilter::hasDialog Method
Checks whether the filter has a dialog box.
Syntax:
virtual bool hasDialog() const;
Return value:

Value | Description
true | This filter has a property dialog box.
false | This filter does not have a property dialog box.
See also: IFrameFilter, IFrameFilter::callDialog

<< IFrameFilter


IFrameFilter::setData

IFrameFilter::setData Method
Sets a data parameter. A data parameter allows the user to copy a raw blob into the filter.
Syntax:
tFilterError setData( const std::string& name, void* pData, size_t length );
tFilterError setData( const std::wstring& name, void* pData, size_t length );

Parameter | Description
name | The name of the data parameter to be set.
pData | A pointer to the data to be set. Has to be at least length bytes in length.
length | Length of the data pointed to by pData.
Return Value:

A member of the tFilterError enumeration:

Value | Description
eNO_ERROR | The data was set successfully.
ePARAM_NOT_FOUND | The filter does not have a parameter with the specified name. To obtain a list with the valid parameters, use getAvailableParameters.
eINCOMPATIBLE_PARAM_VALUE | name is not a data parameter. To obtain a list with the valid parameters and its types, use getAvailableParameters.
eINVALID_PARAM_VALUE | The value was not accepted, e.g. the data length is not what the filter expected.
eINVALID_FILTER_STATE | The filter could not accept the parameter, because it is in a state that prevents the data from being changed, e.g. in live mode.
Remarks:

All calls to setData have to be inside a beginParamTransfer / endParamTransfer block.

See also: IFrameFilter, IFrameFilter::getData, IFrameFilter::getDataLength, IFrameFilter::getAvailableParameters

<< IFrameFilter


IFrameFilter::setParameter

IFrameFilter::setParameter Method
Sets a frame filter parameter.
Syntax:
tFilterError setParameter( const std::string& name, const _variant_t& value );
tFilterError setParameter( const std::string& name, const std::string& value );
tFilterError setParameter( const std::string& name, int value );
tFilterError setParameter( const std::string& name, long value );
tFilterError setParameter( const std::string& name, float value );
tFilterError setParameter( const std::string& name, bool value );
tFilterError setParameter( const std::wstring& name, const _variant_t& value );
tFilterError setParameter( const std::wstring& name, const std::wstring& value );
tFilterError setParameter( const std::wstring& name, int value );
tFilterError setParameter( const std::wstring& name, long value );
tFilterError setParameter( const std::wstring& name, float value );
tFilterError setParameter( const std::wstring& name, bool value );

Parameter | Description
name | The name of the parameter to be set.
value | The new value of the parameter.
Return Value:

A member of the tFilterError enumeration:

Value | Description
eNO_ERROR | The parameter was set successfully.
ePARAM_NOT_FOUND | The filter does not have a parameter with the specified name. To obtain a list with the valid parameters, use getAvailableParameters.
eINCOMPATIBLE_PARAM_VALUE | The type of the value does not match the data type of the parameter. To obtain a list with the valid parameters and its types, use getAvailableParameters.
eINVALID_PARAM_VALUE | The value was not accepted, e.g. because it is out of range.
eINVALID_FILTER_STATE | The filter could not accept the parameter, because it is in a state that prevents the parameter from being changed, e.g. in live mode.
Remarks:

All calls to setParameter have to be inside a beginParamTransfer / endParamTransfer block. Especially when setting multiple parameters, like X/Y-coordinates, this is important to ensure parameter consistency.

Example:

The following example shows how to set the parameters of a frame filter. Assume a frame filter was loaded and set with the following code:

smart_com<IFrameFilter> pRotFlipFilter = FilterLoader::createFilter( "Rotate Flip" );
grabber.setDeviceFrameFilters( pRotFlipFilter.get() );

The parameters are set using beginParamTransfer, setParameter and endParamTransfer:

pRotFlipFilter->beginParamTransfer();

if( eNO_ERROR != pRotFlipFilter->setParameter( "Rotation Angle", 90 ) )
{
    std::cerr << "Error setting parameter 'Rotation Angle'" << std::endl;
}

if( eNO_ERROR != pRotFlipFilter->setParameter( "Flip H", false ) )
{
    std::cerr << "Error setting parameter 'Flip H'" << std::endl;
}
if( eNO_ERROR != pRotFlipFilter->setParameter( "Flip V", true ) )
{
    std::cerr << "Error setting parameter 'Flip V'" << std::endl;
}

pRotFlipFilter->endParamTransfer();
See also: IFrameFilter, IFrameFilter::getParameter, IFrameFilter::getAvailableParameters, IFrameFilter::beginParamTransfer, IFrameFilter::endParamTransfer

<< IFrameFilter


IFrameFilter::setSettings

IFrameFilter::setSettings Method
This method is used to set previously retrieved filter settings.
Syntax:
bool setSettings( const std::string& data );
bool setSettings( const std::wstring& data );

Parameter | Description
data | The string with the data to copy into the filter.
Return value:

Value | Description
true | The operation was successful.
false | The operation failed, i.e. because the data was retrieved from a different filter.
See also: IFrameFilter, IFrameFilter::getSettings

<< IFrameFilter


IFrameFilter::tParamType
Enumeration that describes the type of a frame filter parameter.
Name | Description
eParamLong | The parameter is a 32-bit integer.
eParamBoolean | The parameter is a boolean flag.
eParamFloat | The parameter is a single-precision floating point number.
eParamString | The parameter is a string.
eParamData | The parameter is a data parameter.

<< IFrameFilter


IFrameFilter::ParamDesc

IFrameFilter::ParamDesc Structure
The ParamDesc structure, describes a frame filter parameter. You can retrieve a tParamArray, containing ParamDesc structures by calling IFrameFilter::getAvailableParameters.
Syntax:
struct ParamDesc
{
    wchar_t      name[30];
    tParamType   type;
    wchar_t      typeDesc[30];
    std::string  getTypeDesc() const;
    std::string  getName() const;
};

Member | Description
name | Name of the parameter
type | A tParamType describing the type of the parameter.
typeDesc | A string describing the type of the parameter.
getTypeDesc | Helper function returning a std::string describing the type of the parameter.
getName | Helper function returning the parameter name in a std::string.

<< IFrameFilter


IFrameFilter::tParamArray

tParamArray
tParamArray is a std::vector of ParamDesc structures.
Syntax:
typedef std::vector<ParamDesc> tParamArray;

<< IFrameFilter


FrameFilterImpl

To implement a transform filter, you have to derive from this class.

FrameFilterImpl and FrameUpdateFilterImpl

FrameFilterImpl-derived filters copy image data in their transform method from a source to a destination frame.

FrameUpdateFilterImpl-derived filters can analyze and modify a single buffer that is presented to them in updateInPlace.

Depending on your task, it is better to either derive from FrameFilterImpl or from FrameUpdateFilterImpl.

Implementation

To get a working transform filter, you do at least have to implement:

  • transform
  • getSupportedInputTypes
  • getTransformOutputTypes

To customize the behavior of the filter, you can also override:

  • notifyStart
  • notifyStop
  • checkInputType
  • checkTransformTypes

To add a dialog box to your transform filter, you have to override methods from IFrameFilter:

  • IFrameFilter::hasDialog
  • IFrameFilter::callDialog

To register parameters that can be queried and modified using IFrameFilter::getAvailableParameters, IFrameFilter::setParameter and IFrameFilter::getParameter, use

  • addBoolParam
  • addLongParam
  • addFloatParam
  • addStringParam
  • addDataParam

To derive from FrameFilterImpl, use the name of your derived class as a template parameter:

class MyFilter
    :   public DShowLib::FrameFilterImpl<MyFilter>
{
    // ...
};

Every class derived from FrameFilterImpl has to have a static method getStaticFilterInfo, returning a FilterInfo structure containing information about the filter:

public:
    // FrameFilterImpl implementation
    static    DShowLib::FilterInfo getStaticFilterInfo();

See Writing a Frame Filter: Binarization to see how to implement that method.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Inheritance

IFrameFilter
FrameFilterImpl
FrameUpdateFilterImpl

Methods

Method | Description
addBoolParam | Registers a boolean parameter than can be accessed using the methods of IFrameFilter.
addDataParam | Registers a data parameter than can be accessed using the methods of IFrameFilter.
addFloatParam | Registers a float parameter than can be accessed using the methods of IFrameFilter.
addLongParam | Registers a long (integer) parameter than can be accessed using the methods of IFrameFilter.
addStringParam | Registers a string parameter than can be accessed using the methods of IFrameFilter.
checkInputType | Determines whether a specific input type is supported by the filter.
checkTransformTypes | Determines whether a specific conversion is supported by the filter.
getSupportedInputTypes | This method is called to request the types which this transform filter supports as input types.
getTransformOutputTypes | This method is called to request the possible output types.
notifyStart | This method is called when the transformation process (live mode) is started.
notifyStop | This method is called when the transformation process (live mode) is stopped.
transform | This method is called when a frame must be transformed or copied from the source to the destination IFrame.

<< Classes


FrameFilterImpl::addBoolParam

FrameFilterImpl::addBoolParam Method
Registers a boolean parameter than can be accessed using the methods of IFrameFilter.
Syntax:
protected:
     void addBoolParam( const std::string& name, tFilterError (T::*getFunc)( bool& ), tFilterError (T::*setFunc)( bool ) );
     void addBoolParam( const std::wstring& name, tFilterError (T::*getFunc)( bool& ), tFilterError (T::*setFunc)( bool ) );

Name | Description
name | Name of the parameter. This string has to be passed to IFrameFilter::setParameter or IFrameFilter::getParameter to access the parameter.
getFunc | Name of a member function of the class derived from FrameFilterImpl. Has to take a reference to a bool as it only parameter and return a tFilterError.
setFunc | Name of a member function of the class derived from FrameFilterImpl. Has to take a bool as its only parameter and return a tFilterError.
Remarks:

You should register all parameters of your frame filter in your constructor.

Example:

For an example how to register a parameter, see addFloatParam.

See also: FrameFilterImpl, FrameFilterImpl::addLongParam, FrameFilterImpl::addFloatParam, FrameFilterImpl::addStringParam, FrameFilterImpl::addDataParam

<< FrameFilterImpl


FrameFilterImpl::addDataParam

FrameFilterImpl::addDataParam Method
Registers a data parameter than can be accessed using the methods of IFrameFilter.
Syntax:
protected:
    void addDataParam( const std::string& name, tFilterError (T::*getLenFunc)( size_t& length), tFilterError (T::*getFunc)( void*, size_t& ), tFilterError (T::*setFunc)( void*, size_t ) );
    void addDataParam( const std::wstring& name, tFilterError (T::*getLenFunc)( size_t& length), tFilterError (T::*getFunc)( void*, size_t& ), tFilterError (T::*setFunc)( void*, size_t ) );

Name | Description
name | Name of the parameter. This string has to be passed to IFrameFilter::setData or IFrameFilter::getData to access the parameter.
getLenFunc | Name of a member function of the class derived from FrameFilterImpl. Has to take a reference to a size_t as its only parameter and return a tFilterError.
getFunc | Name of a member function of the class derived from FrameFilterImpl. Has to take a void* and a reference to a size_t as parameters and return a tFilterError.
setFunc | Name of a member function of the class derived from FrameFilterImpl. Has to take a void* and a size_t as parameters and return a tFilterError.
Remarks:

You should register all parameters of your frame filter in your constructor.

See also: FrameFilterImpl, FrameFilterImpl::addBoolParam, FrameFilterImpl::addLongParam, FrameFilterImpl::addFloatParam, FrameFilterImpl::addStringParam

<< FrameFilterImpl


FrameFilterImpl::addFloatParam

FrameFilterImpl::addFloatParam Method
Registers a float parameter than can be accessed using the methods of IFrameFilter.
Syntax:
protected:
    void addFloatParam( const std::string& name, tFilterError (T::*getFunc)( float& ), tFilterError (T::*setFunc)( float ) );
    void addFloatParam( const std::wstring& name, tFilterError (T::*getFunc)( float& ), tFilterError (T::*setFunc)( float ) );

Name | Description
name | Name of the parameter. This string has to be passed to IFrameFilter::setParameter or IFrameFilter::getParameter to access the parameter.
getFunc | Name of a member function of the class derived from FrameFilterImpl. Has to take a reference to a float as its only parameter and return a tFilterError.
setFunc | Name of a member function of the class derived from FrameFilterImpl. Has to take a float as its only parameter and return a tFilterError.
Remarks:

You should register all parameters of your frame filter in your constructor.

Example:

This example shows how to register a float parameter and implement the necessary access methods.

In the constructor of your frame filter implementation, add a call to addFloatParam:

CRotateTransform::CRotateTransform()
    :    m_Angle( 0.0f )
{
    addFloatParam( "angle", &CRotateTransform::getAngle, &CRotateTransform::setAngle );
}

Declare the methods setAngle and getAngle in the header file...

DShowLib::tFilterError    setAngle( float val );
DShowLib::tFilterError    getAngle( float& val );

...and implement them in the source file:

tFilterError    CRotateTransform::setAngle( float val )
{
    m_Angle = val;
    return eNO_ERROR;
}
tFilterError    CRotateTransform::getAngle( float& val )
{
    val = m_Angle;
    return eNO_ERROR;
}
See also: FrameFilterImpl, FrameFilterImpl::addBoolParam, FrameFilterImpl::addLongParam, FrameFilterImpl::addStringParam, FrameFilterImpl::addDataParam

<< FrameFilterImpl


FrameFilterImpl::addLongParam

FrameFilterImpl::addLongParam Method
Registers a long (integer) parameter than can be accessed using the methods of IFrameFilter.
Syntax:
protected:
    void addLongParam( const std::string& name, tFilterError (T::*getFunc)( long& ), tFilterError (T::*setFunc)( long ) );
    void addLongParam( const std::wstring& name, tFilterError (T::*getFunc)( long& ), tFilterError (T::*setFunc)( long ) );

Name | Description
name | Name of the parameter. This string has to be passed to IFrameFilter::setParameter or IFrameFilter::getParameter to access the parameter.
getFunc | Name of a member function of the class derived from FrameFilterImpl. Has to take a reference to a long as its only parameter and return a tFilterError.
setFunc | Name of a member function of the class derived from FrameFilterImpl. Has to take a long as its only parameter and return a tFilterError.
Remarks:

You should register all parameters of your frame filter in your constructor.

Example:

For an example on how to register a parameter, see addFloatParam.

See also: FrameFilterImpl, FrameFilterImpl::addBoolParam, FrameFilterImpl::addFloatParam, FrameFilterImpl::addStringParam, FrameFilterImpl::addDataParam

<< FrameFilterImpl


FrameFilterImpl::addStringParam

FrameFilterImpl::addStringParam Method
Registers a string parameter than can be accessed using the methods of IFrameFilter.
Syntax:
protected:
    void addStringParam( const std::string& name, tFilterError (T::*getFunc)( _bstr_t& ), tFilterError (T::*setFunc)( _bstr_t ) );
    void addStringParam( const std::wstring& name, tFilterError (T::*getFunc)( _bstr_t& ), tFilterError (T::*setFunc)( _bstr_t ) );

Name | Description
name | Name of the parameter. This string has to be passed to IFrameFilter::setParameter or IFrameFilter::getParameter to access the parameter.
getFunc | Name of a member function of the class derived from FrameFilterImpl. Has to take a reference to a _bstr_t as its only parameter and return a tFilterError.
setFunc | Name of a member function of the class derived from FrameFilterImpl. Has to take a _bstr_t as its only parameter and return a tFilterError.
Remarks:

You should register all parameters of your frame filter in your constructor.

Example:

For an example how to register a parameter, see addFloatParam.

See also: FrameFilterImpl, FrameFilterImpl::addBoolParam, FrameFilterImpl::addLongParam, FrameFilterImpl::addFloatParam, FrameFilterImpl::addDataParam

<< FrameFilterImpl


FrameFilterImpl::checkInputType

FrameFilterImpl::checkInputType Method
Determines whether a specific input type is supported by the filter.
Syntax:
virtual bool checkInputType( const FrameTypeInfo& inpType ) const;

Parameter | Description
inpType | Suggested input frame type.
Return Value:

Value | Description
true | The input type can be accepted.
false | The filter can not handle the input type.
Remarks:

You can override this method when you need some filter-specific behavior.

The default implementation calls getSupportedInputTypes to check whether the transformation is possible.

See also: FrameFilterImpl, FrameTypeInfo

<< FrameFilterImpl


FrameFilterImpl::checkTransformTypes

FrameFilterImpl::checkTransformTypes Method
Determines whether a specific conversion is supported by the filter.
Syntax:
virtual bool checkTransformTypes( const FrameTypeInfo& in_type,
                                  const FrameTypeInfo& out_type ) const;

Parameter | Description
in_type | Suggested input frame type.
out_type | Suggested output frame type.
Return Value:

Value | Description
true | The transformation is possible.
false | The transformation is not possible.
Remarks:

You can override this method when you need some filter-specific behavior.

The default implementation calls getTransformOutputTypes to check whether the transformation is possible.

See also: FrameFilterImpl, FrameTypeInfo

<< FrameFilterImpl


FrameFilterImpl::getSupportedInputTypes

FrameFilterImpl::getSupportedInputTypes Method
This method is called to request the types which this transform filter supports as input types.
Syntax:
virtual void getSupportedInputTypes( FrameTypeInfoArray& arr ) const = 0;

Parameter | Description
arr | Reference to an FrameTypeInfoArray with supported frame types. This array has to be filled with the frame types this transform filter can handle.
Remarks:

When you override checkInputType, this method is not called, unless you call it in your own implementation.

See also: FrameFilterImpl, FrameFilterImpl::checkInputType, FrameTypeInfoArray, FrameTypeInfo

<< FrameFilterImpl


FrameFilterImpl::getTransformOutputTypes

FrameFilterImpl::getTransformOutputTypes Method
This method is called to request the possible output types.
Syntax:
virtual bool getTransformOutputTypes( const FrameTypeInfo& in_type,
                                      FrameTypeInfoArray& out_types ) const = 0;

Parameter | Description
in_type | The type of the frames passed in the input buffers.
out_types | A collection of frame types this filter may generate.
Return Value:

Value | Description
true | The list with supported output types was filled.
false | No transformation available.
Remarks:

The types should be ordered, depending upon the preference of the transform operation. The output type of this transform filter will be chosen based on the capabilities and input preference of the next filter and this filter.

When you override checkTransformTypes, this method is not called unless you call it in your own implementation.

See also: FrameFilterImpl, FrameFilterImpl::checkTransformTypes, FrameTypeInfo, FrameTypeInfoArray

<< FrameFilterImpl


FrameFilterImpl::notifyStart

FrameFilterImpl::notifyStart Method
This method is called when the transformation process (live mode) is started.
Syntax:
virtual void notifyStart( const FrameTypeInfo& in_type,
                          const FrameTypeInfo& out_type );

Parameter | Description
in_type | The input frame type for the starting transform process.
out_type | The output frame type for the starting transform process.
Remarks:

In this method, you can allocate buffers or do any other necessary initialization work.

The default implementation does nothing.

See also: FrameFilterImpl, FrameFilterImpl::notifyStop

<< FrameFilterImpl


FrameFilterImpl::notifyStop

FrameFilterImpl::notifyStop Method
This method is called when the transformation process (live mode) is stopped.
Syntax:
virtual void notifyStop();
Remarks:

The implementation of this method is a good place to free any resources that were allocated in notifyStart.

The default implementation does nothing.

See also: FrameFilterImpl, FrameFilterImpl::notifyStart

<< FrameFilterImpl


FrameFilterImpl::transform

FrameFilterImpl::transform Method
This method is called when a frame must be transformed or copied from the source to the destination IFrame.
Syntax:
virtual bool transform( const IFrame& src, IFrame& dest ) = 0;

Parameter | Description
src | Source frame. You must not write to this frame.
dest | Destination frame. You should only write to the destination frame when you return true.
Return Value:

Value | Description
true | The transformation was successful.
false | Discard the frame.
Remarks:

The image data pointer returned by IFrame::getPtr may be 0 for the destination frame dest. In this case, no target for the copy operation is available, e.g. all buffers of the MemBufferCollection are locked. The transform filter is called, because the implementation may need to analyze the input data.

See also: FrameFilterImpl, IFrame

<< FrameFilterImpl


FrameUpdateFilterImpl

To implement an update filter, you have to derive from this class.

FrameFilterImpl and FrameUpdateFilterImpl

Filters that are derived from FrameFilterImpl copy image data in their transform method from a source to a destination frame.

Filters that are derived from FrameUpdateFilterImpl can analyze and modify a single buffer that is presented to them in updateInPlace.

Depending on your task, it is better to either derive from FrameFilterImpl or from FrameUpdateFilterImpl.

Implementation

To get a working update filter, you need to have implemented at least the following:

  • updateInPlace
  • FrameFilterImpl::getSupportedInputTypes

To customize the behavior of the filter, you can also override:

  • modifiesData
  • FrameFilterImpl::notifyStart
  • FrameFilterImpl::notifyStop
  • FrameFilterImpl::checkInputType

To add a dialog box to your transform filter, you have to override methods from IFrameFilter:

  • IFrameFilter::hasDialog
  • IFrameFilter::callDialog

To register parameters that can be queried and modified using IFrameFilter::getAvailableParameters, IFrameFilter::setParameter and IFrameFilter::getParameter, use

  • FrameFilterImpl::addBoolParam
  • FrameFilterImpl::addLongParam
  • FrameFilterImpl::addFloatParam
  • FrameFilterImpl::addStringParam
  • FrameFilterImpl::addDataParam

To derive from FrameUpdateFilterImpl, use the name of your derived class as a template parameter:

class MyFilter
    :   public DShowLib::FrameUpdateFilterImpl<MyFilter>
{
    // ...
};

Every class derived from FrameUpdateFilterImpl has to have a static method getStaticFilterInfo that returns a FilterInfo structure, containing information about the filter:

public:
    // FrameFilterImpl implementation
    static    DShowLib::FilterInfo getStaticFilterInfo();

See Writing a Frame Filter: Binarization to see how to implement that method.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Inheritance

IFrameFilter
FrameFilterImpl
FrameUpdateFilterImpl

Methods

Method | Description
modifiesData | This method returns whether this frame update callback modifies the presented image data. The default implementation returns true.
updateInPlace | This method is called when a frame can be updated.

<< Classes


FrameUpdateFilterImpl::modifiesData

FrameUpdateFilterImpl::modifiesData Method
This method returns whether this frame update callback modifies the presented image data. The default implementation returns true.
Syntax:
virtual bool modifiesData() const;
Return Value:

The return value gives the class library a hint whether it has to create a copy of the image data before presenting it to this frame update callback.

Value | Description
true | This filter may modify the image data presented in updateInPlace.
false | This filter may not modify the image data presented in updateInPlace.
Remarks:

Overwrite this method and return false, if your frame filter never modifies the presented image data.

See also: FrameUpdateFilterImpl, FrameUpdateFilterImpl::updateInPlace

<< FrameUpdateFilterImpl


FrameUpdateFilterImpl::updateInPlace

FrameUpdateFilterImpl::updateInPlace Method
This method is called when a frame can be updated.
Syntax:
virtual bool    updateInPlace( IFrame& frame ) = 0;

Parameter | Description
frame | The source and destination frame of the call.
Return Value:

The return value determines whether this frame should be delivered downstream.

Value | Description
true | Continue processing this frame
false | Discard this frame
See also: FrameUpdateFilterImpl, IFrame

<< FrameUpdateFilterImpl


IFrame

Interface to an image buffer.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Inheritance

IFrame
MemBuffer

Methods

Method | Description
getFrameType | Returns the frame type of this frame.
getPtr | Returns a pointer to the image data.
getSampleDesc | This method returns a reference to a sample description structure that contains the time stamps for the frame.

<< Classes


IFrame::getFrameType

IFrame::getFrameType Method
Returns the frame type of this frame.
Syntax:
virtual const FrameTypeInfo& getFrameType() const = 0;
Return value:

This frame's FrameTypeInfo.

See also: IFrame, MemBuffer, FrameTypeInfo

<< IFrame


IFrame::getPtr

IFrame::getPtr Method
Returns a pointer to the image data.
Syntax:
virtual BYTE* getPtr() const = 0;
Return value:

A pointer to the image data.

Remarks:

Please note, that depending of the frame type, images may be stored bottom up, therefore the pointer returned by this method may point to the first byte of the first pixel of the last line of the image.

You can get information about how to interpret the data by calling getFrameType.

The example Accessing an Image Buffer shows how to access the image data in image buffers.

See also: IFrame, IFrame::getFrameType, MemBuffer

<< IFrame


IFrame::getSampleDesc

IFrame::getSampleDesc Method
This method returns a reference to a sample description structure that contains the time stamps for the frame.
Syntax:
virtual const tsMediaSampleDesc& getSampleDesc() const = 0;
Return value:

A reference to a tsMediaSampleDesc structure.

See also: MemBuffer, tsMediaSampleDesc

<< IFrame


FrameTypeInfoArray

This class is a list of FrameTypeInfo objects. It is used in the communication between FrameFilterImpl-derived classes when the image stream is setup and the filters are inserted in the image stream.

FrameTypeInfoArray is derived from std::vector<FrameTypeInfo>.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Methods

Method | Description
FrameTypeInfoArray | Constructs a new FrameTypeInfoArray.
addFrameType | Adds a frame type or color format to the list.
createOptimalTypesArray | Creates an array filled with types that allow fast transformations.
createRGBArray | Creates an array filled with RGB frame types.
createStandardTypesArray | Creates an array filled with frame types that are commonly used.

<< Classes


FrameTypeInfoArray::FrameTypeInfoArray

FrameTypeInfoArray::FrameTypeInfoArray Method
Constructs a new FrameTypeInfoArray.
Syntax:
FrameTypeInfoArray();
explicit FrameTypeInfoArray( tColorformatEnum fmt );
explicit FrameTypeInfoArray( const FrameTypeInfo& info );

Parameter | Description
fmt | Color format to be inserted into the array.
info | Frame type to be inserted into the array.
See also: FrameTypeInfoArray, tColorformatEnum, FrameTypeInfo

<< FrameTypeInfoArray


FrameTypeInfoArray::addFrameType

FrameTypeInfoArray::addFrameType Method
Adds a frame type or color format to the list.
Syntax:
void addFrameType( tColorformatEnum fmt, unsigned int width = 0, int height = 0 );
void addFrameType( const GUID& subtype, unsigned int width = 0, int height = 0 );
void addFrameType( const FrameTypeInfo& info );
void addFrameType( const FrameTypeInfo* pInfoList, unsigned int count = 1 );

Parameter | Description
fmt | Color format of the frame type to be added.
width | Width of the frame type to be added.
height | Height of the frame type to be added.
subtype | GUID of the format of the frame type to be added.
info | Frame type to be inserted into the array.
pInfoList | Array of FrameTypeInfo structures to be added.
count | Number of FrameTypeInfo structures in pInfoList.
Remarks:

When setting fmt to eInvalidColorformat, the connection format is chosen by the connection itself and not influenced by the user.

See also: FrameTypeInfoArray, tColorformatEnum, FrameTypeInfo

<< FrameTypeInfoArray


FrameTypeInfoArray::createOptimalTypesArray

FrameTypeInfoArray::createOptimalTypesArray Method
Creates an array filled with types that allow fast transformations.
Syntax:
static FrameTypeInfoArray createOptimalTypesArray();
Remarks:

This function inserts the following frame types into the array:

  • RGB32
  • RGB24
  • Y800
See also: FrameTypeInfoArray, FrameTypeInfoArray::createRGBArray, FrameTypeInfoArray::createStandardTypesArray

<< FrameTypeInfoArray


FrameTypeInfoArray::createRGBArray

FrameTypeInfoArray::createRGBArray Method
Creates an array filled with RGB frame types.
Syntax:
static FrameTypeInfoArray createRGBArray();
Remarks:

This function inserts the following frame types into the array:

  • RGB32
  • RGB24
  • RGB565
  • RGB555
  • RGB8
See also: FrameTypeInfoArray, FrameTypeInfoArray::createStandardTypesArray, FrameTypeInfoArray::createOptimalTypesArray

<< FrameTypeInfoArray


FrameTypeInfoArray::createStandardTypesArray

FrameTypeInfoArray::createStandardTypesArray Method
Creates an array filled with frame types that are commonly used.
Syntax:
static FrameTypeInfoArray createStandardTypesArray();
Remarks:

This function inserts the following frame types into the array:

  • RGB32
  • RGB24
  • RGB565
  • RGB555
  • RGB8
  • Y800
See also: FrameTypeInfoArray, FrameTypeInfoArray::createRGBArray, FrameTypeInfoArray::createOptimalTypesArray

<< FrameTypeInfoArray


MediaStreamContainer

A MediaStreamContainer describes a video file format. The most common video file format is AVI, which is identified by the GUID MSC_AviContainer.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Methods

Method | Description
clone | Creates a copy of the stream container, which is completely independent from the current object, but copies the internal state and data of the container.
create | Creates the container specified with the id.
getAvailableMediaStreamContainers | Returns a list of available container types.
getDescription | This method returns the string representation of this container type.
getInternalInterface | Returns a reference to an internal interface.
getMediaStreamContainerID | Returns the unique container type ID, which you can use to create the container without referring to the description string.
getPreferredFileExtension | Returns the standard file extension used by this container, e.g. "avi" for AVI files.
isCustomCodecSupported | Returns, if this container does support a codec. If true, then you can create a sink with a Codec or uncompressed format GUID.
operator== | Checks whether the name of this MediaStreamContainer equals a specified string.
toString | Returns the string representation of this container type.

<< Classes


MediaStreamContainer::clone

MediaStreamContainer::clone Method
Creates a copy of the stream container, which is completely independent from the current object, but copies the internal state and data of the container.
Syntax:
smart_ptr<MediaStreamContainer> clone() const;
Return Value:

A copy of this media stream container.

Remarks:

You must not use one instance of MediaStreamContainer to create two independent MediaStreamSink objects. Use clone to duplicate the container before you create a second sink.

See also: MediaStreamContainer, MediaStreamSink

<< MediaStreamContainer


MediaStreamContainer::create

MediaStreamContainer::create Method
Creates the container specified with the id.
Syntax:
static tMediaStreamContainerPtr create( const GUID& id );

Parameter | Description
id | The container id of the container.
Return Value:

Returns 0, when the container could not be found or created, otherwise a reference to the container.

Remarks:

You can either use a GUID of the Standard MediaStreamContainer GUIDs or a GUID of a container object that you retrieved using MediaStreamContainer::getMediaStreamContainerID.

See also: MediaStreamContainer, Standard MediaStreamContainer GUIDs, MediaStreamContainer::getMediaStreamContainerID

<< MediaStreamContainer


MediaStreamContainer::getAvailableMediaStreamContainers

MediaStreamContainer::getAvailableMediaStreamContainers Method
Returns a list of available container types.
Syntax:
static tMediaStreamContainerListPtr    getAvailableMediaStreamContainers();
Return Value:

The list may be empty ( size() == 0 ) when no containers were found. Otherwise, it contains the available containers that are available on the system.

Example:

The following example shows how to retrieve the list of available media stream containers and displays their names and GUIDs in a list box:

CListBox* pContainerList = (CListBox*)GetDlgItem( IDC_CONTAINERS );

// Get a list of the available media stream containers.
tMediaStreamContainerListPtr pList =
    MediaStreamContainer::getAvailableMediaStreamContainers();

// Display them in a list box.
for( int i = 0; i < int(pList->size()); ++i )
{
    tMediaStreamContainerPtr pContainer = pList->at( i );

    std::string item;
    item += pContainer->getDescription() + " ";
    item += wstoas( GUIDToWString( pContainer->getMediaStreamContainerID() ) );

    pContainerList->AddString( item.c_str() );
}
See also: MediaStreamContainer, tMediaStreamContainerListPtr

<< MediaStreamContainer


MediaStreamContainer::getDescription

MediaStreamContainer::getDescription Method
This method returns the string representation of this container type.
Syntax:
std::string getDescription() const;
std::wstring getDescriptionW() const;
Return Value:

A text describing this MediaStreamContainer
Remarks:

The text returned by this method should only be used to display its name to the user of the application program.

To save a selected MediaStreamContainer, you should rather refer to the the GUID returned by MediaStreamContainer::getMediaStreamContainerID.

See also: MediaStreamContainer, MediaStreamContainer::toString, MediaStreamContainer::getMediaStreamContainerID

<< MediaStreamContainer


MediaStreamContainer::getInternalInterface

MediaStreamContainer::getInternalInterface Method
Returns a reference to an internal interface.
Syntax:
template<class TItf>
smart_com<TItf> getInternalInterface( smart_com<TItf>& pItf ) const;
template<class TItf>
smart_com<TItf> getInternalInterface( REFIID riid, smart_com<TItf>& pItf ) const;

Parameter | Description
pItf | A smart_com to an interface reference.
riid | An interface ID.
Return value:

A reference to the interface requested or 0, if the interface is not supported.

Remarks:

This method allows it to fetch a custom interface from a media stream container.

To use this method, the compiler must support the __uuidof operator.

If the compiler supports the __declspec( uuid( "iid" ) ) option, an iid can be assigned to the interface this way. If the compiler does not support this option, the iid must be passed to the method as a parameter.

Sample:

This example shows how to fetch an interface from a codec.

smart_com<IMSCInterface> pItf;
if( pContainer->getInternalInterface( pItf ) == 0 )
{
    ... // interface is not supported, so error handling
}
else
{
    ... // use the interface
}
See also: MediaStreamContainer, smart_com

<< MediaStreamContainer


MediaStreamContainer::getMediaStreamContainerID

MediaStreamContainer::getMediaStreamContainerID Method
Returns the unique container type ID, which you can use to create the container without referring to the description string.
Syntax:
GUID getMediaStreamContainerID() const;
Return Value:

A GUID identifying this type of media stream container.

Remarks:

You can use this GUID to save which media stream container was used in your application and re-create the container with the ID using MediaStreamSink::create when needed.

See also: MediaStreamSink, MediaStreamSink::create

<< MediaStreamContainer


MediaStreamContainer::getPreferredFileExtension

MediaStreamContainer::getPreferredFileExtension Method
Returns the standard file extension used by this container, e.g. "avi" for AVI files.
Syntax:
std::string getPreferredFileExtension() const;
std::wstring getPreferredFileExtensionW() const;
Return Value:

A string containing the default extension for files written by this media stream container.

See also: MediaStreamContainer

<< MediaStreamContainer


MediaStreamContainer::isCustomCodecSupported

MediaStreamContainer::isCustomCodecSupported Method
Returns, if this container does support a codec. If true, then you can create a sink with a Codec or uncompressed format GUID.
Syntax:
bool isCustomCodecSupported() const;
Return Value:

Value | Description
true | This media stream container supports codecs.
false | This media stream container does not support codecs.
Remarks:

Certain containers do support codecs, like AVI, others do not like MPEG2.

See also: MediaStreamContainer, Codec

<< MediaStreamContainer


MediaStreamContainer::operator==

MediaStreamContainer::operator== Method
Checks whether the name of this MediaStreamContainer equals a specified string.
Syntax:
bool operator==( const std::string& op ) const;
bool operator==( const std::wstring& op ) const;

Parameter | Description
op | String to which the name of this instance is to be compared.
Return Value:

Value | Description
true | The specified string op equals the name of this instance.
false | The specified string op is not equal to the name of this instance.
See also: MediaStreamContainer

<< MediaStreamContainer


MediaStreamContainer::toString

MediaStreamContainer::toString Method
Returns the string representation of this container type.
Syntax:
std::string toString() const;
std::wstring toStringW() const;
Return Value:

The string representation of this container type.

Remarks:

This method returns the same value as MediaStreamContainer::getDescription.

See also: MediaStreamContainer, MediaStreamContainer::getDescription

<< MediaStreamContainer


MediaStreamSink

The MediaStreamSink replaces the deprecated AVISink. A MediaStreamSink can save image data in video files and optionally allows you to specify one or more IFrameFilters that can analyze and/or transform the image data before it is written to the video file.

The IFrameFilter implementation can also drop certain frames in order to implement time lapse recording. The video file format is specified by a MediaStreamContainer, while the format of the image data in the file is determined either by a GUID (uncompressed format) or a codec (compressed format). The MediaStreamContainer determines the video file format; the most common MediaStreamContainer is AVI. Many media stream containers allow the specification of a Codec to compress the image data before writing it to the file.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Inheritance

GrabberSinkType
MediaStreamSink
AviSink

Methods

Method | Description
create | Creates a new MediaStreamSink.
getCodec | Returns the Codec that was set when creating this sink.
getContainer | Returns the MediaStreamContainer that was set when this sink was created.
getCreateData | Returns a tCreateData structure, containing the information that was used to create this instance.
getFilename | Returns the currently set target filename.
getFrameFilters | Returns a tFrameFilterList, containing the frame filters that are currently used to analyze or transform the image data before it is written to the video file.
getSinkType | This implementation of GrabberSinkType::getSinkType returns eMEDIASTREAM_SINK.
getSubType | Returns the subtype of the selected uncompressed format.
setFilename | Sets the target video filename.
setFrameFilter | Sets a frame filter or a tFrameFilterList or frame filters. The filters are used to transform the image data before it is written to the video file.

Structs

Struct | Description
tCreateData | This structure describes the parameters, which were used to create a MediaStreamSink. You can access the tCreateData of a MediaStreamSink by calling MediaStreamSink::getCreateData, and passing it to MediaStreamSink::create to create a similar MediaStreamSink.

<< Classes


MediaStreamSink::create

MediaStreamSink::create Method
Creates a new MediaStreamSink.
Syntax:
static tMediaStreamSinkPtr create( const tMediaStreamContainerPtr& pCont,
                                   IFrameFilter* pFilter = 0 );
static tMediaStreamSinkPtr create( const tMediaStreamContainerPtr& pCont,
                                   const tFrameFilterList& lst );

static tMediaStreamSinkPtr create( const tMediaStreamContainerPtr& pCont,
                                   const smart_ptr<Codec>& pCodec,
                                   IFrameFilter* pFilter = 0 );
static tMediaStreamSinkPtr create( const tMediaStreamContainerPtr& pCont,
                                   const smart_ptr<Codec>& pCodec,
                                   const tFrameFilterList& lst );

static tMediaStreamSinkPtr create( const tMediaStreamContainerPtr& pCont,
                                   const GUID& subtype,
                                   IFrameFilter* pFilter = 0 );
static tMediaStreamSinkPtr create( const tMediaStreamContainerPtr& pCont,
                                   const GUID& subtype,
                                   const tFrameFilterList& lst );

static tMediaStreamSinkPtr create( const GUID& containerID,
                                   IFrameFilter* pFilter = 0 );
static tMediaStreamSinkPtr create( const GUID& containerID,
                                   const tFrameFilterList& lst );

static tMediaStreamSinkPtr create( const GUID& containerID,
                                   const smart_ptr<Codec>& pCodec,
                                   IFrameFilter* pFilter = 0 );
static tMediaStreamSinkPtr create( const GUID& containerID,
                                   const smart_ptr<Codec>& pCodec,
                                   const tFrameFilterList& lst );

static tMediaStreamSinkPtr create( const GUID& containerID,
                                   const GUID& subtype,
                                   IFrameFilter* pFilter = 0 );
static tMediaStreamSinkPtr create( const GUID& containerID,
                                   const GUID& subtype,
                                   const tFrameFilterList& lst );

static tMediaStreamSinkPtr create( const tCreateData& create_data );

Parameter | Description
pCont | Pointer to a MediaStreamContainer. You can obtain a list with available Codec objects by calling MediaStreamContainer::getAvailableMediaStreamContainers, or directly by creating MediaStreamContainer objects by specifying a GUID to MediaStreamContainer::create.
containerID | GUID of a MediaStreamContainer or one of the Standard MediaStreamContainer GUIDs.
pFilter | The frame filter that can analyze or transform the image data before it is written to the video file.
lst | A tFrameFilterList of frame filters. The filters in this list are connected in a filter chain to transform the image data.
pCodec | Pointer to a MediaStreamContainer. You can obtain a list with available Codec objects, by calling Codec::getAvailableCodecs.
subtype | The subtype specifies the image format of uncompressed video.
create_data | To duplicate a MediaStreamSink, you can call MediaStreamSink::getCreateData to access the parameters with which it was created. You can use this tCreateData structure to initialize another MediaStreamSink.
Return Value:

A pointer to the new MediaStreamSink, or 0, if an error occurred.

Remarks:

Some media stream containers do not work with certain codecs. On the other hand, some media stream containers do not accept uncompressed video formats. In this case, Grabber::startLive will fail and you will have to try a different container/codec combination.

Examples:

To record an AVI file, you have to create an AVI media stream container that is identified by MSC_AviContainer. Select a codec from the list returned by Codec::getAvailableCodecs and create the MediaStreamSink. After the sink has been created, you have to set a video filename, by calling MediaStreamSink::setFilename:

// Create an AVI Media Stream Container.
tMediaStreamContainerPtr pAVIContainer = MediaStreamContainer::create( MSC_AviContainer );

// Obtain a list of available codecs.
tCodecListPtr pAvailableCodecList = Codec::getAvailableCodecs();

// Select the first codec. You would usually allow the user to make this choice
// or hard code the search for a codec name.
tCodecPtr pCodec = pAvailableCodecList->at( 0 );

// Create the media stream sink from these parameters.
tMediaStreamSinkPtr pSink = MediaStreamSink::create( pAVIContainer, pCodec );

// Set a target filename.
pSink->setFilename( "test.avi" );

// Set the sink.
m_Grabber.setSinkType( pSink );

To get a list of the available MediaStreamContainers, use MediaStreamContainer::getAvailableMediaStreamContainers. You can find out whether a MediaStreamContainer supports codecs or uncompressed formats by calling MediaStreamContainer::isCustomCodecSupported. In this case, you can create the sink as seen above. When no custom codecs are supported, you are not allowed to specify a codec in MediaStreamSink::create. To set a matching video filename, you can call MediaStreamContainer::getPreferredFileExtension to get the default file extension for that video file format.

// Get a list of the available media stream containers.
tMediaStreamContainerListPtr pAvailableContainers =
    MediaStreamContainer::getAvailableMediaStreamContainers();

// Select the first container. You would usually allow the user to make this choice
// or hard code the search for a container name.
tMediaStreamContainerPtr pContainer = pAvailableContainers->at( 0 );

// Sink object to be created.
tMediaStreamSinkPtr pSink;

// If the container supports codecs, select one.
if( pContainer->isCustomCodecSupported() )
{
    // Obtain a list of available codecs.
    tCodecListPtr pAvailableCodecList = Codec::getAvailableCodecs();

    // Select the first codec. You would usually allow the user to make this choice
    // or hard code the search for a codec name.
    tCodecPtr pCodec = pAvailableCodecList->at( 0 );

    // Create the media stream sink from these parameters.
    pSink = MediaStreamSink::create( pContainer, pCodec );
}
else
{
    // No codec support; just create the sink.
    pSink = MediaStreamSink::create( pContainer );
}

// Create a file name from a name and the preferred extension of the container.
std::string filename = "test.";
filename += pContainer->getPreferredFileExtension();
pSink->setFilename( filename );

// Set the sink.
m_Grabber.setSinkType( pSink );

To save uncompressed AVI, use the subtype of the desired uncompressed format as second parameter to MediaStreamSink::create.

// Create an AVI Media Stream Container.
tMediaStreamContainerPtr pAVIContainer = MediaStreamContainer::create( MSC_AviContainer );

// Create the media stream sink from these parameters.
tMediaStreamSinkPtr pSink = MediaStreamSink::create( pAVIContainer, MEDIASUBTYPE_RGB24 );

// Set a target filename.
pSink->setFilename( "test.avi" );

// Set the sink.
m_Grabber.setSinkType( pSink );
See also: MediaStreamSink, MediaStreamContainer, IFrameFilter

<< MediaStreamSink


MediaStreamSink::getCodec

MediaStreamSink::getCodec Method
Returns the Codec that was set when creating this sink.
Syntax:
virtual smart_ptr<Codec> getCodec() const;
Return Value:

The Codec that was set when creating this sink, or 0, when the selected MediaStreamContainer does not support codecs or a subtype was specified for uncompressed video.

See also: MediaStreamSink

<< MediaStreamSink


MediaStreamSink::getContainer

MediaStreamSink::getContainer Method
Returns the MediaStreamContainer that was set when this sink was created.
Syntax:
virtual smart_ptr<MediaStreamContainer> getContainer() const;
Return Value:

The MediaStreamContainer that was set when this sink was created.

See also: MediaStreamSink

<< MediaStreamSink


MediaStreamSink::getCreateData

MediaStreamSink::getCreateData Method
Returns a tCreateData structure, containing the information that was used to create this instance.
Syntax:
const tCreateData& getCreateData() const;
Return Value:

A tCreateData structure, containing the information that was used to create this instance.

Remarks:

The returned tCreateData structure is a snapshot of the parameters that were used to create the sink. The filename is not part of the returned data.

See also: MediaStreamSink, MediaStreamSink::tCreateData

<< MediaStreamSink


MediaStreamSink::getFilename

MediaStreamSink::getFilename Method
Returns the currently set target filename.
Syntax:
std::string getFilename() const;
std::wstring getFilenameW() const;
Return Value:

The currently set target filename.

See also: MediaStreamSink

<< MediaStreamSink


MediaStreamSink::getFrameFilters

MediaStreamSink::getFrameFilters Method
Returns a tFrameFilterList, containing the frame filters that are currently used to analyze or transform the image data before it is written to the video file.
Syntax:
const tFrameFilterList getFrameFilters() const;
Return Value:

A tFrameFilterList, containing the currently set frame filters.

See also: MediaStreamSink, IFrameFilter, MediaStreamSink::setFrameFilter

<< MediaStreamSink


MediaStreamSink::getSinkType

MediaStreamSink::getSinkType Method
This implementation of GrabberSinkType::getSinkType returns eMEDIASTREAM_SINK.
Syntax:
tSinkType getSinkType() const;
Return Value:

eMEDIASTREAM_SINK
See also: MediaStreamSink, GrabberSinkType::getSinkType

<< MediaStreamSink


MediaStreamSink::getSubType

MediaStreamSink::getSubType Method
Returns the subtype of the selected uncompressed format.
Syntax:
virtual GUID    getSubType() const;
Return Value:

The subtype of the selected uncompressed format, or GUID_NULL, if a Codec is used or the selected MediaStreamContainer does not support custom codecs.

See also: MediaStreamSink, Standard Mediasubtype GUIDs

<< MediaStreamSink


MediaStreamSink::setFilename

MediaStreamSink::setFilename Method
Sets the target video filename.
Syntax:
bool setFilename( const std::string& str ) const;
bool setFilename( const std::wstring& str ) const;

Parameter | Description
str | Name of the target video file.
Return Value:

Value | Description
true | The filename was successfully set.
false | The filename was not set, e.g. because the sink was already streaming.
Remarks:

This method can not be called when the grabber to which this sink was assigned is in live mode.

See also: MediaStreamSink

<< MediaStreamSink


MediaStreamSink::setFrameFilter

MediaStreamSink::setFrameFilter Method
Sets a frame filter or a tFrameFilterList or frame filters. The filters are used to transform the image data before it is written to the video file.
Syntax:
bool setFrameFilter( IFrameFilter* pFilter );
bool setFrameFilter( const tFrameFilterList& lst );

Parameter | Description
pFilter | New frame filter.
lst | List of frame filters that will be combined to form a filter chain.
Return Value:

Value | Description
true | The filter or filter chain was successfully set.
false | The filter could not be set.
Remarks:

See also: MediaStreamSink, IFrameFilter, MediaStreamSink::getFrameFilters

<< MediaStreamSink


MediaStreamSink::tCreateData

MediaStreamSink::tCreateData Structure
This structure describes the parameters, which were used to create a MediaStreamSink. You can access the tCreateData of a MediaStreamSink by calling MediaStreamSink::getCreateData, and passing it to MediaStreamSink::create to create a similar MediaStreamSink.
Syntax:
struct tCreateData
{
    tCreateData( const tMediaStreamContainerPtr& pCont, IFrameFilter* pCB = 0 );
    tCreateData( const tMediaStreamContainerPtr& pCont, const GUID& subtype, IFrameFilter* pFilter = 0 );
    tCreateData( const tMediaStreamContainerPtr& pCont, const smart_ptr<Codec>& pCodec, IFrameFilter* pFilter = 0 );
    tCreateData( const tMediaStreamContainerPtr& pCont, const tFrameFilterList& lst );
    tCreateData( const tMediaStreamContainerPtr& pCont, const GUID& subtype, const tFrameFilterList& lst );
    tCreateData( const tMediaStreamContainerPtr& pCont, const smart_ptr<Codec>& pCodec, const tFrameFilterList& lst );

    tCreateData( const GUID& cont_id, IFrameFilter* pCB = 0 );
    tCreateData( const GUID& cont_id, const GUID& subtype, IFrameFilter* pFilter = 0 );
    tCreateData( const GUID& cont_id, const smart_ptr<Codec>& pCodec, IFrameFilter* pFilter = 0 );

    tCreateData& operator=( const tCreateData& op2 );

    tMediaStreamContainerPtr m_pContainer;
    GUID                     m_ContainerID;
    smart_ptr<Codec>         m_pCodec;
    GUID                     m_Subtype;
    tFrameFilterList         m_filterChain;
};

Value | Description
m_pContainer | The selected MediaStreamContainer.
m_ContainerID | The GUID of the selected MediaStreamContainer.
m_pCodec | The selected Codec, if a codec is used, otherwise 0.
m_Subtype | The selected subtype of uncompressed video, the video data is saved uncompressed; otherwise GUID_NULL.
m_filterChain | A chain of IFrameFilters.

<< MediaStreamSink


FrameTypeInfo

This structure contains all information to describe the layout (pixel depth and pixel organization) and the extents of one frame (image buffer) in the image stream.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

Properties

Property | Description
buffersize | Returns the number of bytes required for one frame.
dim | The dimensions of this frame type.
subtype | Returns the GUID of this frame type.

Methods

Method | Description
FrameTypeInfo | Constructs a new FrameTypeInfo.
getBitsPerPixel | Returns the number of bits used to store one pixel in frames of this type.
getColorformat | Returns, if possible, the color format equivalent to the media subtype of this frame type.
isBottomUpFrameType | Returns whether the image data of this frame type is stored bottom-up in the buffer.

<< Classes


FrameTypeInfo::buffersize

FrameTypeInfo::buffersize Property
Returns the number of bytes required for one frame.
Syntax:
unsigned int    buffersize;
See also: FrameTypeInfo

<< FrameTypeInfo


FrameTypeInfo::dim

FrameTypeInfo::dim Property
The dimensions of this frame type.
Syntax:
SIZE dim;
See also: FrameTypeInfo

<< FrameTypeInfo


FrameTypeInfo::subtype

FrameTypeInfo::subtype Property
Returns the GUID of this frame type.
Syntax:
GUID subtype;
Remarks:

Please refer to Standard Mediasubtype GUIDs for more information. If GUID_NULL is returned, this frame type is compatible to all color formats (pixel depth and pixel organization).

See also: FrameTypeInfo, Constants

<< FrameTypeInfo


FrameTypeInfo::FrameTypeInfo

FrameTypeInfo::FrameTypeInfo Method
Constructs a new FrameTypeInfo.
Syntax:
FrameTypeInfo();
FrameTypeInfo( tColorformatEnum fmt, unsigned int width = 0, int height = 0, unsigned int buf_size = 0 );
FrameTypeInfo( tColorformatEnum fmt, const SIZE& dim, unsigned int buf_size = 0 );
FrameTypeInfo( const GUID& subtype, unsigned int width = 0, int height = 0, unsigned int buf_size = 0 );
FrameTypeInfo( const GUID& subtype, const SIZE& dim, unsigned int buf_size = 0 );
FrameTypeInfo( unsigned int buf_size );

Parameter | Description
fmt | Color format of the frame type.
width | Width of the frame type. A value of 0 allows any width.
height | Height of the frame type. A value of 0 allows any height.
buf_size | Number of bytes required for one frame.
dim | Width and height of one frame in a SIZE structure.
subtype | GUID of the frame format. Please refer to Standard Mediasubtype GUIDs for more information. If GUID_NULL is specified, the created frame type is compatible to all color formats (pixel depth and pixel organization).
See also: FrameTypeInfo, tColorformatEnum, Standard Mediasubtype GUIDs

<< FrameTypeInfo


FrameTypeInfo::getBitsPerPixel

FrameTypeInfo::getBitsPerPixel Method
Returns the number of bits used to store one pixel in frames of this type.
Syntax:
unsigned int getBitsPerPixel() const;
Return Value:

Number of bits per pixel for this frame type.

See also: FrameTypeInfo

<< FrameTypeInfo


FrameTypeInfo::getColorformat

FrameTypeInfo::getColorformat Method
Returns, if possible, the color format equivalent to the media subtype of this frame type.
Syntax:
tColorformatEnum getColorformat() const;
Return Value:

The color format of this frame.

See also: FrameTypeInfo, tColorformatEnum

<< FrameTypeInfo


FrameTypeInfo::isBottomUpFrameType

FrameTypeInfo::isBottomUpFrameType Method
Returns whether the image data of this frame type is stored bottom-up in the buffer.
Syntax:
bool isBottomUpFrameType() const;
Return Value:

true, if the format is a bottom-up format.

Remarks:

Bottom-up formats store the pixel data from left to right, but the first line in the buffer is the last line of the image. Therefore, the last line in the buffer contains the first line of the image. All RGB formats , for example, are bottom-up formats if the device does not provide horizontal flipping.

See also: FrameTypeInfo

<< FrameTypeInfo


New Constants

List of all constants that were introduced in IC Imaging Control 3.0

Standard Mediasubtype GUIDs

Mediasubtype GUIDs are used to define color formats for FrameTypeInfo or as uncompressed video formats in MediaStreamSink::create.

Standard MediaStreamContainer GUIDs

MediaStreamContainer GUIDs are used to create instances using MediaStreamContainer::create.

<< New Features Reference


constants::Standard Mediasubtype GUIDs

Standard Mediasubtype GUIDs
Mediasubtype GUIDs are used to define color formats for FrameTypeInfo or as uncompressed video formats in MediaStreamSink::create.
Most subtypes have an equivalent in tColorformatEnum.
For a description of the pixel organization in the various color formats, have a look at the example Accessing an Image Buffer.
Constant | Description
MEDIASUBTYPE_RGB24 | 24-bit color format, tColorformatEnum::eRGB24
MEDIASUBTYPE_RGB32 | 32-bit color format, tColorformatEnum::eRGB32
MEDIASUBTYPE_RGB8 | 8-bit grayscale format, tColorformatEnum::eRGB8 and tColorformatEnum::eY8
MEDIASUBTYPE_UYVY | Color format, tColorformatEnum::eUYVY
MEDIASUBTYPE_RGB555 | 16-bit color format, tColorformatEnum::eRGB555
MEDIASUBTYPE_RGB565 | 16-bit color format, tColorformatEnum::eRGB565
MEDIASUBTYPE_Y800 | 8-bit grayscale format, tColorformatEnum::eY800. In contrast to RGB8, the images are stored top-down.
MEDIASUBTYPE_BY8 | 8-bit format containing a bayer pattern, tColorformatEnum::eBY8. See Debayering for information on how to handle this format.
MEDIASUBTYPE_YGB0 | 10-bit grayscale format, tColorformatEnum::eYGB0
MEDIASUBTYPE_YGB1 | 10-bit grayscale format, tColorformatEnum::eYGB1

<< Class Library Reference


constants::Standard MediaStreamContainer GUIDs

Standard MediaStreamContainer GUIDs
MediaStreamContainer GUIDs are used to create instances using MediaStreamContainer::create.
Constant | Description
MSC_AviContainer | The AVI container format.
MSC_OGMContainer | Media Stream Container Format that was developed by the Vorbis dev team. The project is currently set to hold, therefore, it is better to use Matroska (see below).
MSC_MatroskaContainer | Media Stream Container Format that was developed to replace avi with an open source multi stream format. See http://www.matroska.org for further information. Currently used for videos with multiple subtitles and/or audio streams, which are not encoded in MPEG2 or windows media.

<< Class Library Reference


New Enumerations

List of all enumerations that were introduced in IC Imaging Control 3.0

tFilterClass

Frame filters have a filter class that allows them to be categorized:

tFilterError

The members of this enumerations describe error conditions returned by the methods of IFrameFilter, such as getParameter or setParameter.

tPathPosition

tPathPosition enumerates the possible positions of the OverlayBitmap in the image stream.

<< New Features Reference


refenum::tFilterClass

tFilterClass
Frame filters have a filter class that allows them to be categorized:
Enumeration | Description
eFC_GENERIC | Generic filters are filters that should work in any environment without special knowledge about the parameters.
eFC_INTERNAL | Internal filters are filters that are not guaranteed to work in generic applications. They do not know about how to handle the filter's parameters.
eFC_ALL | Any kind of filter.

<< Class Library Reference


refenum::tFilterError

tFilterError
The members of this enumerations describe error conditions returned by the methods of IFrameFilter, such as getParameter or setParameter.
Enumeration | Description
eNO_ERROR | The operation was completed successfully.
ePARAM_NOT_FOUND | The filter does not have a parameter with the specified name. To obtain a list containing valid parameters, use IFrameFilter::getAvailableParameters.
eINCOMPATIBLE_PARAM_VALUE | The type of the provided value does not match the data type of the parameter. To obtain a list containing valid parameters and its types, use IFrameFilter::getAvailableParameters.
eINVALID_PARAM_VALUE | The value was not accepted, e.g. because it is out of range.
eINVALID_FILTER_STATE | The filter could not accept the parameter, because it is in a state that prevents the parameter from being changed, e.g. in live mode.

<< Class Library Reference


refenum::tPathPosition

tPathPosition
tPathPosition enumerates the possible positions of the OverlayBitmap in the image stream.
Enumeration | Description
ePP_NONE | The OverlayBitmap will not be visible at all.
ePP_DEVICE | The OverlayBitmap will be visible in both the live video display and grabbed images/videos.
ePP_SINK | The OverlayBitmap will be visible in grabbed images and videos, but not in the live display.
ePP_DISPLAY | The OverlayBitmap will be visible in the live display, but not in grabbed images or videos.

<< Class Library Reference


New Functions

List of all functions that were introduced in IC Imaging Control 3.0

getBitsPerPixel

Returns the number of bits needed to store one pixel of image data in the specified format.

getSubtypeFromColorformat

Returns the media subtype GUID, corresponding to the specified color format.

getColorformatFromSubtype

Returns the tColorformatEnum, corresponding to the specified media subtype.

calcBufferSize

Calculates the number of bytes needed to store one frame of image data with a specified dimension and color format.

calcRequiredBuffersize

Calculates the number of bytes needed to store one frame of image data with the specified FrameTypeInfo.

createBitmapInfoHeader

Creates a BITMAPINFOHEADER structure filled with the frame type description from a FrameTypeInfo.

convertToString

Creates a string representation from a FrameTypeInfo.

isBottomUpFrameType

Checks whether a frame type is a bottom-up video format.

createFCCMediaSubType

Creates a FourCC media subtype from a 4-character-string.

wstoas

Converts a std::wstring into a std::string.

astows

Converts a std::string into a std::wstring.

StringToGUID

Creates a GUID from a string containing the GUID in the format {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}.

GUIDToWString

Returns a string representation of a GUID.

<< New Features Reference


reffunctions::getBitsPerPixel

getBitsPerPixel Method
Returns the number of bits needed to store one pixel of image data in the specified format.
Syntax:
int getBitsPerPixel( tColorformatEnum colorformat );
int getBitsPerPixel( const GUID& subtype );

Name | Description
colorformat | A member of the tColorformatEnum enumeration
subtype | A GUID specifying a media subtype. A list with possible media subtypes can be found at Constants.
Return Value:

This function returns the number of allocated bits per pixel in the specified color format or subtype, if the format is known.

If the specified format is unknown, the return value is 0.

Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: tColorformatEnum, Constants

<< Class Library Reference


reffunctions::getSubtypeFromColorformat

getSubtypeFromColorformat Method
Returns the media subtype GUID, corresponding to the specified color format.
Syntax:
GUID getSubtypeFromColorformat( tColorformatEnum colorformat );

Name | Description
colorformat | A member of the tColorformatEnum enumeration.
Return Value:

A Media Subtype GUID, corresponding to the supplied colorformat.

Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: tColorformatEnum, Constants, getColorformatFromSubtype

<< Class Library Reference


reffunctions::getColorformatFromSubtype

getColorformatFromSubtype Method
Returns the tColorformatEnum, corresponding to the specified media subtype.
Syntax:
tColorformatEnum getColorformatFromSubtype( const GUID& subtype );

Name | Description
subtype | A GUID, specifying a media subtype. A list with possible media subtypes can be found at Constants.
Return Value:

This method returns the member of tColorformatEnum that corresponds to the specified media subtype.

Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: tColorformatEnum, Constants, getSubtypeFromColorformat

<< Class Library Reference


reffunctions::calcBufferSize

calcBufferSize Method
Calculates the number of bytes needed to store one frame of image data with a specified dimension and color format.
Syntax:
DWORD calcBufferSize( const SIZE& dim, tColorformatEnum colorformat );

Name | Description
dim | Size of one frame
colorformat | Color format as tColorformatEnum
Return Value:

Number of bytes needed to store one frame with the size dim in colorformat.

Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: tColorformatEnum, calcRequiredBuffersize

<< Class Library Reference


reffunctions::calcRequiredBuffersize

calcRequiredBuffersize Method
Calculates the number of bytes needed to store one frame of image data with the specified FrameTypeInfo.
Syntax:
DWORD calcRequiredBuffersize( const FrameTypeInfo& type );

Name | Description
type | Description of the frame type in a FrameTypeInfo
Return Value:

Number of bytes required to store one frame.

Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: FrameTypeInfo, calcBufferSize

<< Class Library Reference


reffunctions::createBitmapInfoHeader

createBitmapInfoHeader Method
Creates a BITMAPINFOHEADER structure filled with the frame type description from a FrameTypeInfo.
Syntax:
smart_ptr<BITMAPINFOHEADER> createBitmapInfoHeader( const FrameTypeInfo& type );

Name | Description
type | The FrameTypeInfo to be converted into a BITMAPINFOHEADER.
Return Value:

smart_ptr to a BITMAPINFOHEADER representing the supplied frame type.

Remarks:

This method is useful, when drawing frames using Windows GDI functions.

Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: FrameTypeInfo

<< Class Library Reference


reffunctions::convertToString

convertToString Method
Creates a string representation from a FrameTypeInfo.
Syntax:
std::string convertToString( const FrameTypeInfo& type );
std::wstring convertToStringW( const FrameTypeInfo& type );
std::string convertToStringA( const FrameTypeInfo& type );

Name | Description
type | A FrameTypeInfo object
Return Value:

String representation of the specified frame type.

Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: FrameTypeInfo

<< Class Library Reference


reffunctions::isBottomUpFrameType

isBottomUpFrameType Method
Checks whether a frame type is a bottom-up video format.
Syntax:
bool isBottomUpFrameType( tColorformatEnum colorformat );
bool isBottomUpFrameType( const GUID& subtype );

Name | Description
colorformat | A member of tColorformatEnum.
subtype | A GUID specifying a media subtype. A list with possible media subtypes can be found at Constants.
Return Value:

Value | Description
true | The images in the specified format are stored bottom-up.
false | The images in the specified format are stored top-down.
Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: tColorformatEnum, Constants

<< Class Library Reference


reffunctions::createFCCMediaSubType

createFCCMediaSubType Method
Creates a FourCC media subtype from a 4-character-string.
Syntax:
GUID createFCCMediaSubType( const wchar_t* pFCC );
GUID createFCCMediaSubType( const char* pFCC );

Name | Description
pFCC | String, describing the subtype to create. Has to be 4 chars in length.
Return Value:

Media subtype GUID, describing the color format identified by the specified string pFCC.

Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0

<< Class Library Reference


reffunctions::wstoas

wstoas Method
Converts a std::wstring into a std::string.
Syntax:
std::string wstoas( const std::wstring& op );
std::string& wstoas( const std::wstring&, op, std::string& rval );

Name | Description
op | std::wstring to be converted
rval | std::string to receive the converted data.
Return Value:

Converted std::string
Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: astows

<< Class Library Reference


reffunctions::astows

astows Method
Converts a std::string into a std::wstring.
Syntax:
std::wstring astows( const std::string& op );
std::wstring& astows( const std::string&, op, std::wstring& rval );

Name | Description
op | std::string to be converted
rval | std::wstring to receive the converted data.
Return Value:

Converted std::string
Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: wstoas

<< Class Library Reference


reffunctions::StringToGUID

StringToGUID Method
Creates a GUID from a string containing the GUID in the format {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}.
Syntax:
GUID StringToGUID( const wchar_t* pString );

Name | Description
pString | String containing the GUID.
Return Value:

GUID
Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: GUIDToWString

<< Class Library Reference


reffunctions::GUIDToWString

GUIDToWString Method
Returns a string representation of a GUID.
Syntax:
std::wstring    GUIDToWString( const GUID& id );

Name | Description
id | GUID to be converted into a string.
Return Value:

A string representation of the specified GUID.

Information:

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.0
See also: StringToGUID

<< Class Library Reference


New Structures

List of all structures that were introduced in IC Imaging Control 3.0

FilterInfo

The FilterInfo structure contains information about a frame filter that can be loaded from a .ftf file.

<< New Features Reference


refstruct::FilterInfo

FilterInfo Structure
The FilterInfo structure contains information about a frame filter that can be loaded from a .ftf file.
Syntax:
struct FilterInfo
{
    wchar_t            name[30];
    wchar_t            module[MAX_PATH];
    tFilterClass    filterClass;

    std::string        getFilterName() const;
    std::wstring    getFilterNameW() const;

    std::string        getModulePath() const;
    std::wstring    getModulePathW() const;

    std::string        getModuleName() const;
    std::wstring    getModuleNameW() const;

    tFilterClass    getFilterClass() const;

    bool operator<( const FilterInfo& op2 ) const;
};

Member | Description
name | Contains the name of the frame filter.
module | Contains the full path to the module in which the frame filter is implemented.
filterClass | A tFilterClass member, describing the frame filter's class.
getFilterName | Returns the name of the filter in a std::string.
getModulePath | Returns the full path to the filter module in a std::string.
getModuleName | Returns the filename of the filter module without the path.
getFilterClass | Returns the filter's tFilterClass.

<< Class Library Reference


New Type Definitions

List of all type definitions that were introduced in IC Imaging Control 3.0

tFrameFilterList

tFrameFilterList is a vector of pointers to IFrameFilter objects.

tCodecPtr

tCodecPtr is a smart_ptr to a Codec.

tCodecList

tCodecList is a std::vector of tCodecPtrs.

tCodecListPtr

tCodecListPtr is a smart_ptr to a tCodecList.

tFrameHandlerSinkPtr

tFrameHandlerSinkPtr is a smart pointer to a FrameHandlerSink.

tMediaStreamSinkPtr

tMediaStreamSinkPtr is a smart pointer to a MediaStreamSink.

tMediaStreamContainerPtr

A smart_ptr to a MediaStreamContainer object.

tMediaStreamContainerList

A vector of tMediaStreamContainerPtrs.

tMediaStreamContainerListPtr

A smart_ptr to a tMediaStreamContainerList.

<< New Features Reference


typedef::tFrameFilterList

tFrameFilterList
tFrameFilterList is a vector of pointers to IFrameFilter objects.
Syntax:
typedef std::vector<IFrameFilter*> tFrameFilterList;

<< Class Library Reference


typedef::tCodecPtr

tCodecPtr
tCodecPtr is a smart_ptr to a Codec.
Syntax:
typedef smart_ptr<Codec> tCodecPtr;

<< Class Library Reference


typedef::tCodecList

tCodecList
tCodecList is a std::vector of tCodecPtrs.
Syntax:
typedef std::vector<tCodecPtr> tCodecList;

<< Class Library Reference


typedef::tCodecListPtr

tCodecListPtr
tCodecListPtr is a smart_ptr to a tCodecList.
Syntax:
typedef smart_ptr<tCodecList> tCodecListPtr;

<< Class Library Reference


typedef::tFrameHandlerSinkPtr

tFrameHandlerSinkPtr
tFrameHandlerSinkPtr is a smart pointer to a FrameHandlerSink.
Syntax:
typedef smart_ptr<FrameHandlerSink> tFrameHandlerSinkPtr;

<< Class Library Reference


typedef::tMediaStreamSinkPtr

tMediaStreamSinkPtr
tMediaStreamSinkPtr is a smart pointer to a MediaStreamSink.
Syntax:
typedef smart_ptr<MediaStreamSink> tMediaStreamSinkPtr;

<< Class Library Reference


typedef::tMediaStreamContainerPtr

tMediaStreamContainerPtr
A smart_ptr to a MediaStreamContainer object.
Syntax:
typedef smart_ptr<MediaStreamContainer> tMediaStreamContainerPtr;

<< Class Library Reference


typedef::tMediaStreamContainerList

tMediaStreamContainerList
A vector of tMediaStreamContainerPtrs.
Syntax:
typedef std::vector<tMediaStreamContainerPtr> tMediaStreamContainerList;

<< Class Library Reference


typedef::tMediaStreamContainerListPtr

tMediaStreamContainerListPtr
A smart_ptr to a tMediaStreamContainerList.
Syntax:
typedef smart_ptr<tMediaStreamContainerList> tMediaStreamContainerListPtr;

<< Class Library Reference


What's New in Version 2.0 since Version 1.41

Description of the changes from IC Imaging Control 1.41 to IC Imaging Control 2.0.

Video Capture Device Properties

Video Capture Device Properties provide a generic, hardware independent and extendable way of controlling the settings of a video capture device. In the following, the shortcut VCD is used for Video Capture Device.

DCAM Prop DLL

The DCAM Prop DLL is not needed anymore. The special DCAM features can now be accessed and manipulated, using the appropriate VCDProperties.

A detailed list of equivalent functionality for all functions and procedures of the DCAM Prop DLL can be found in the technical article DCAM_Prop_DLL

Loading and saving Codec data

The procedure for loading and saving codec properties has been changed. The AviCodecData class has been removed, and the access to the data is now handled through the members of FilterInfoObject.

For more information about loading and saving codec properties, see:

  • FilterInfoObject::getCodecData
  • FilterInfoObject::setCodecData
  • FilterInfoObject::isCodecDataAvailable

Serializing the device state

A new set of functions allows you to save and restore the settings of the currently opened device in a string or a file:

  • Grabber::saveDeviceState
  • Grabber::saveDeviceStateToFile
  • Grabber::loadDeviceState
  • Grabber::loadDeviceStateFromFile

Detecting video signal on a frame grabber input channel

With the new methods of the Grabber class, it is possible to determine whether a video device is connected to an input channel of a frame grabber:

  • Grabber::isSignalDetectedAvailable
  • Grabber::getSignalDetected

Frame Rate

Several methods have been added to control the frame rates of devices.

  • Grabber::isFrameRateListAvailable
  • Grabber::getAvailableFPS
  • Grabber::getCurrentActualFPS
  • Grabber::getCurrentMaxAvailableFPS
  • Grabber::getFPS
  • Grabber::setFPS

Counting dropped frames

It is possible to retrieve the number of frames that have been dropped or not dropped with the new functions:

  • Grabber::isCountOfFramesDroppedAvailable
  • Grabber::getCountOfFramesDropped
  • Grabber::getCountOfFramesNotDropped

Pause the live mode

The new Grabber::setPauseLive and Grabber::getPauseLive methods allow you to pause both the live display and the delivery of frames to the ImageAvailable event.

Built-in Dialogs

ICImagingControl comes with 2 dialogs that allow the user to open a device and adjust device settings.

  • Grabber::showDevicePage shows a dialog box that lets the user open a device and configure the video norm, video format, input channel, frame rate and flip states.
  • Grabber::showVCDPropertyPage shows a dialog allowing the user to adjust the VCD Properties.

Device recognition

With the new unique name and the display name of devices, it is possible to open specific devices regardless of whether there is more that one device of the same type connected to the computer.

  • Grabber::openDevByUniqueName
  • Grabber::openDevByDisplayName
  • VideoCaptureDeviceItem::getUniqueName
  • VideoCaptureDeviceItem::getDisplayName
  • VideoCaptureDeviceItem::getBaseName

Saving image buffers

Several functions have been added to save the contents of an image buffer. Images can be saved in JPEG and various BMP formats.

  • saveToFileJPEG
  • saveToFileBMP

OverlayBitmap

The following methods have been added to the OverlayBitmap class:

  • OverlayBitmap::drawFrameRect
  • OverlayBitmap::drawSolidEllipse
  • OverlayBitmap::drawFrameEllipse
  • OverlayBitmap::getColorformat

New Features Reference

List of all new features

<< What's New


New Features Reference

List of all new features

IVCDAbsoluteValueProperty

This class represents an absolute value interface to a value of a video capture device property.

IVCDButtonProperty

This class represents a button interface to a value of a video capture device property.

IVCDMapStringsProperty

This class represents an interface to a video capture device property, which uses a string representation for every value.

IVCDPropertyElement

This class represents an element of video capture device property.

IVCDPropertyInterface

This class represents an interface to a value of a video capture device property.

IVCDPropertyItem

This class represents an item of a video capture device property.

IVCDRangeProperty

This class represents a range interface to a value of a video capture device property.

IVCDSwitchProperty

This class represents a switch interface to a value of a video capture device property.

CSimplePropertyAccess

This class wraps access to VCDProperties to make them easier to use.

Grabber::getAvailableVCDProperties

Returns a collection of the IVCDPropertyItems of the currently opened device.

Grabber::getPauseLive

Returns whether pause mode is enabled.

Grabber::setPauseLive

Pauses the live mode.

Grabber::saveDeviceState

Saves the state of the opened device. A saved state can be restored using loadDeviceState.

Grabber::loadDeviceState

Restores grabber settings that were saved by saveDeviceState.

Grabber::saveDeviceStateToFile

Saves the state of the currently opened device to a file. The grabber state can be restored using loadDeviceStateFromFile.

Grabber::loadDeviceStateFromFile

Restores the device settings from a file that was previously saved by saveDeviceStateToFile.

Grabber::getCountOfFramesDropped

Returns the number of frames that were dropped by the video capture device.

Grabber::getCountOfFramesNotDropped

Returns the number of frames that were delivered by the device.

Grabber::showDevicePage

Shows a device settings page.

Grabber::showVCDPropertyPage

Shows the property page for this device. With the property page, the user can adjust property settings like brightness.

Grabber::isSignalDetectedAvailable

Checks whether a device can be queried for a list of available video stream.

Grabber::getSignalDetected

Returns whether a signal was detected by the device.

Grabber::openDevByUniqueName

Opens a device by its unique name.

Grabber::openDevByDisplayName

Opens a device by its display name.

Grabber::isFrameRateListAvailable

Checks whether the currently selected video capture device supports different frame rates that can be set by the user.

Grabber::getAvailableFPS

Returns the available frame rates.

Grabber::getCurrentActualFPS

Retrieves the actual frame rate achieved by the device.

Grabber::getCurrentMaxAvailableFPS

Returns the current maximal frames per second (FPS) that the device can achieve on the bus.

Grabber::getFPS

Returns the frame rate currently set.

Grabber::setFPS

Sets the frame rate of the device.

VideoCaptureDeviceItem::getUniqueName

Returns a unique name for this device.

VideoCaptureDeviceItem::getDisplayName

Returns the display name of the video capture device.

VideoCaptureDeviceItem::getBaseName

Returns the base name of the video capture device.

saveToFileJPEG

This function saves the contents of an image buffer to a JPEG file.

saveToFileBMP

This function saves the contents of an image buffer to a .BMP file.

OverlayBitmap::drawFrameRect

Draws the frame of a rectangle on the live video.

OverlayBitmap::drawSolidEllipse

Draws a solid ellipse on the live video.

OverlayBitmap::drawFrameEllipse

Draws the frame of an ellipse on the live video.

OverlayBitmap::getColorformat

Returns the current color format used for the overlay.

<< What's New in Version 2.0 since Version 1.41


IVCDAbsoluteValueProperty

This class represents an absolute value interface to a value of a video capture device property.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 2.0

Inheritance

IVCDPropertyInterface
IVCDAbsoluteValueProperty

Methods

Method | Description
getDefault | Returns the default value for this property.
getDimFunction | Returns the dimension function, which describes how to map a linear range - such as a slider - to the range of the absolute values. This increases the usability for your programs.
getDimType | Returns a string describing the physical dimension of the absolute value.
getRange | Returns the minimum and maximum value of the range
getRangeMax | Returns the maximum value of the range.
getRangeMin | Returns the minimum value of the range.
getValue | Gets the current value of the range.
setValue | Sets the current value of the range.

Enumerations

Enumeration | Description
tAbsDimFunction | tAbsDimFunction enumerates all possible dimension functions. The dimension function describes how to map a linear range - such as a slider - to the range of the absolute values. This increases the usability for your programs.

<< Classes


IVCDPropertyInterface

This class represents an interface to a value of a video capture device property.

IVCDPropertyInterface is an abstract base class for several more specialized interfaces.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 2.0

Inheritance

IVCDPropertyInterface
IVCDAbsoluteValueProperty
IVCDButtonProperty
IVCDRangeProperty
IVCDMapStringsProperty
IVCDSwitchProperty

Methods

Method | Description
QueryInterface | Tries to retrieve a more specialized interface for this property. The desired interface is determined by the passed parameter.
getAvailable | Checks whether the interface is currently available for reading and/or writing operations.
getInterfaceID | Gets the GUID of the interface.
getParent | Retrieves the element to which this interface belongs.
getReadOnly | Checks whether the interface allows write operations.

<< Classes


IVCDPropertyInterface::QueryInterface

IVCDPropertyInterface::QueryInterface Method
Tries to retrieve a more specialized interface for this property. The desired interface is determined by the passed parameter.
Syntax:
// VC 6
template<class TItf>
TItf QueryInterface( TItf& pItf );
// VC 7.1
template<class TItf>
smart_com<TItf>& QueryInterface( smart_com<TItf>& rval );

Parameter | Description
pItf | A pointer to the desired interface. You have to use a tIVCD%%%PropertyPtr here.
rval | A smart_com to the desired interface. You may use tIVCD%%%PropertyPtr here.
Return value:

This function returns its parameter.

See also: IVCDPropertyInterface

<< IVCDPropertyInterface


IVCDPropertyInterface::getAvailable

IVCDPropertyInterface::getAvailable Method
Checks whether the interface is currently available for reading and/or writing operations.
Syntax:
bool getAvailable() const;
Return value:

true, if the Interface is available for reading and/or writing operations, false otherwise.

See also: IVCDPropertyInterface, IVCDPropertyInterface::getReadOnly

<< IVCDPropertyInterface


IVCDPropertyInterface::getInterfaceID

IVCDPropertyInterface::getInterfaceID Method
Gets the GUID of the interface.
Syntax:
GUID getInterfaceID() const;
Return value:

The GUID of the interface.

See also: IVCDPropertyInterface, Standard Interface GUIDs

<< IVCDPropertyInterface


IVCDPropertyInterface::getParent

IVCDPropertyInterface::getParent Method
Retrieves the element to which this interface belongs.
Syntax:
tIVCDPropertyElementPtr getParent() const;
Return value:

A pointer to the parent element.

See also: IVCDPropertyInterface, IVCDPropertyElement

<< IVCDPropertyInterface


IVCDPropertyInterface::getReadOnly

IVCDPropertyInterface::getReadOnly Method
Checks whether the interface allows write operations.
Syntax:
bool getReadOnly() const;
Return value:

true, if the interface allows write operations, false otherwise.

See also: IVCDPropertyInterface, IVCDPropertyInterface::getAvailable

<< IVCDPropertyInterface


IVCDAbsoluteValueProperty::getDefault

IVCDAbsoluteValueProperty::getDefault Method
Returns the default value for this property.
Syntax:
double getDefault() const;
Return value:

The default value of this property.

See also: IVCDAbsoluteValueProperty, IVCDPropertyInterface, IVCDAbsoluteValueProperty::getRangeMin, IVCDAbsoluteValueProperty::getRangeMax

<< IVCDAbsoluteValueProperty


IVCDAbsoluteValueProperty::getDimFunction

IVCDAbsoluteValueProperty::getDimFunction Method
Returns the dimension function, which describes how to map a linear range - such as a slider - to the range of the absolute values. This increases the usability for your programs.
Syntax:
tAbsDimFunction getDimFunction() const;
Return value:

The dimension function.

See also: IVCDAbsoluteValueProperty, IVCDPropertyInterface, IVCDAbsoluteValueProperty::tAbsDimFunction, IVCDAbsoluteValueProperty::getDimType

<< IVCDAbsoluteValueProperty


IVCDAbsoluteValueProperty::getDimType

IVCDAbsoluteValueProperty::getDimType Method
Returns a string describing the physical dimension of the absolute value.
Syntax:
std::string getDimType() const;
std::string getDimTypeA() const;
std::wstring getDimTypeW() const;
Return value:

A string describing the physical dimension of the absolute value.

Remarks:

Returns the dimension type of the property.

See also: IVCDAbsoluteValueProperty, IVCDPropertyInterface, IVCDAbsoluteValueProperty::getDimFunction

<< IVCDAbsoluteValueProperty


IVCDAbsoluteValueProperty::getRange

IVCDAbsoluteValueProperty::getRange Method
Returns the minimum and maximum value of the range
Syntax:
std::pair<double,double> getRange() const;
Return value:

The minimum and maximum value of the range as a pair.

See also: IVCDAbsoluteValueProperty, IVCDPropertyInterface

<< IVCDAbsoluteValueProperty


IVCDAbsoluteValueProperty::getRangeMax

IVCDAbsoluteValueProperty::getRangeMax Method
Returns the maximum value of the range.
Syntax:
double getRangeMax() const;
Return value:

The maximum value of the range.

See also: IVCDAbsoluteValueProperty, IVCDPropertyInterface, IVCDAbsoluteValueProperty::getRangeMin, IVCDAbsoluteValueProperty::getDefault

<< IVCDAbsoluteValueProperty


IVCDAbsoluteValueProperty::getRangeMin

IVCDAbsoluteValueProperty::getRangeMin Method
Returns the minimum value of the range.
Syntax:
double getRangeMin() const;
Return value:

The minimum value of the range.

See also: IVCDAbsoluteValueProperty, IVCDPropertyInterface, IVCDAbsoluteValueProperty::getRangeMax, IVCDAbsoluteValueProperty::getDefault

<< IVCDAbsoluteValueProperty


IVCDAbsoluteValueProperty::getValue

IVCDAbsoluteValueProperty::getValue Method
Gets the current value of the range.
Syntax:
double getValue() const;
Return value:

The current value of the range.

See also: IVCDAbsoluteValueProperty, IVCDPropertyInterface, IVCDAbsoluteValueProperty::setValue

<< IVCDAbsoluteValueProperty


IVCDAbsoluteValueProperty::setValue

IVCDAbsoluteValueProperty::setValue Method
Sets the current value of the range.
Syntax:
void setValue( double val ) const;
See also: IVCDAbsoluteValueProperty, IVCDPropertyInterface, IVCDAbsoluteValueProperty::getValue

<< IVCDAbsoluteValueProperty


IVCDAbsoluteValueProperty::tAbsDimFunction
tAbsDimFunction enumerates all possible dimension functions. The dimension function describes how to map a linear range - such as a slider - to the range of the absolute values. This increases the usability for your programs.
Enumeration | Description
eLinear | The dimension function is linear.
eLog | The dimension function is logarithmic.
eOther | The dimension function is of another type. This is currently not defined, if you encounter this value use linear mapping instead.

<< IVCDAbsoluteValueProperty


IVCDButtonProperty

This class represents a button interface to a value of a video capture device property.

Button interfaces allow operations to be triggered, rather than setting property values.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 2.0

Inheritance

IVCDPropertyInterface
IVCDButtonProperty

Methods

Method | Description
push | Invokes the operation controlled by this interface.

<< Classes


IVCDButtonProperty::push

IVCDButtonProperty::push Method
Invokes the operation controlled by this interface.
Syntax:
void push();
See also: IVCDButtonProperty, IVCDPropertyInterface

<< IVCDButtonProperty


IVCDMapStringsProperty

This class represents an interface to a video capture device property, which uses a string representation for every value.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 2.0

Inheritance

IVCDPropertyInterface
IVCDRangeProperty
IVCDMapStringsProperty

Methods

Method | Description
getString | Gets the name of the current value of the property controlled through this interface.
getStrings | Returns a list with the available strings to which this property can be set.
setString | Sets the name of the current value of the property controlled through this interface.

<< Classes


IVCDRangeProperty

This class represents a range interface to a value of a video capture device property.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 2.0

Inheritance

IVCDPropertyInterface
IVCDRangeProperty
IVCDMapStringsProperty

Methods

Method | Description
getDefault | Returns the default value of the range.
getDelta | Returns the length of the interval between the valid values of the range.
getRange | Returns the minimum and maximum value of the range.
getRangeMax | Returns the maximum value of the range.
getRangeMin | Returns the minimum value of the range.
getValue | Gets the current value of the range.
setValue | Sets the current value of the range.

<< Classes


IVCDRangeProperty::getDefault

IVCDRangeProperty::getDefault Method
Returns the default value of the range.
Syntax:
long getDefault() const;
Return value:

The default value of the range.

See also: IVCDRangeProperty, IVCDPropertyInterface, IVCDRangeProperty::getRangeMin, IVCDRangeProperty::getRangeMax

<< IVCDRangeProperty


IVCDRangeProperty::getDelta

IVCDRangeProperty::getDelta Method
Returns the length of the interval between the valid values of the range.
Syntax:
long getDelta() const;
Return value:

The length of the interval between the valid values of the range.

See also: IVCDRangeProperty, IVCDPropertyInterface

<< IVCDRangeProperty


IVCDRangeProperty::getRange

IVCDRangeProperty::getRange Method
Returns the minimum and maximum value of the range.
Syntax:
std::pair<long,long> getRange() const;
Return value:

The minimum and maximum value of the range as a pair.

See also: IVCDRangeProperty, IVCDPropertyInterface

<< IVCDRangeProperty


IVCDRangeProperty::getRangeMax

IVCDRangeProperty::getRangeMax Method
Returns the maximum value of the range.
Syntax:
long getRangeMax() const;
Return value:

The maximum value of the range.

See also: IVCDRangeProperty, IVCDPropertyInterface, IVCDRangeProperty::getRangeMin, IVCDRangeProperty::getDefault

<< IVCDRangeProperty


IVCDRangeProperty::getRangeMin

IVCDRangeProperty::getRangeMin Method
Returns the minimum value of the range.
Syntax:
long getRangeMin() const;
Return value:

The minimum value of the range.

See also: IVCDRangeProperty, IVCDPropertyInterface, IVCDRangeProperty::getRangeMax, IVCDRangeProperty::getDefault

<< IVCDRangeProperty


IVCDRangeProperty::getValue

IVCDRangeProperty::getValue Method
Gets the current value of the range.
Syntax:
long getValue() const;
Return value:

The current value of the range.

See also: IVCDRangeProperty, IVCDPropertyInterface, IVCDRangeProperty::setValue

<< IVCDRangeProperty


IVCDRangeProperty::setValue

IVCDRangeProperty::setValue Method
Sets the current value of the range.
Syntax:
void setValue( long val ) const;
See also: IVCDRangeProperty, IVCDPropertyInterface, IVCDRangeProperty::getValue

<< IVCDRangeProperty


IVCDMapStringsProperty::getString

IVCDMapStringsProperty::getString Method
Gets the name of the current value of the property controlled through this interface.
Syntax:
std::wstring getStringW() const;
std::string getString() const;
Return value:

The name of the current value of the property controlled through this interface.

See also: IVCDMapStringsProperty, IVCDMapStringsProperty::setString, IVCDMapStringsProperty::getStrings

<< IVCDMapStringsProperty


IVCDMapStringsProperty::getStrings

IVCDMapStringsProperty::getStrings Method
Returns a list with the available strings to which this property can be set.
Syntax:
tStringVecW& getStringsW( tStringVecW& vec ) const;
tStringVec getStrings() const;
tStringVec& getStrings( tStringVec& vec ) const;

Parameter | Description
vec | A vector of strings where the map strings are appended to.
Return value:

An array that contains the map strings. If an array was given as a parameter to this method, the given array contains the map strings after this call.

See also: IVCDMapStringsProperty, IVCDMapStringsProperty::setString, IVCDMapStringsProperty::getString

<< IVCDMapStringsProperty


IVCDMapStringsProperty::setString

IVCDMapStringsProperty::setString Method
Sets the name of the current value of the property controlled through this interface.
Syntax:
void setString( const std::wstring& str );
void setString( const std::string& str );
See also: IVCDMapStringsProperty, IVCDMapStringsProperty::getString, IVCDMapStringsProperty::getStrings

<< IVCDMapStringsProperty


IVCDPropertyElement

This class represents an element of video capture device property.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 2.0

Methods

Method | Description
getElementID | Gets the GUID of the Element.
getInterface | Returns the desired interface to the element, if it exists.
getInterfacePtr | Retrieves a pointer to an interface of this element. The type of desired interface is determined by the parameter.
getInterfaces | Returns all interfaces that are contained by the element.
getName | Gets the display name of the element.
getNameW | Gets the display name of the element.
getParent | Retrieves the item to which this element belongs.

<< Classes


IVCDPropertyElement::getElementID

IVCDPropertyElement::getElementID Method
Gets the GUID of the Element.
Syntax:
GUID getElementID() const;
Return value:

The GUID of the element.

See also: IVCDPropertyElement, Standard Element GUIDs

<< IVCDPropertyElement


IVCDPropertyElement::getInterface

IVCDPropertyElement::getInterface Method
Returns the desired interface to the element, if it exists.
Syntax:
smart_com<IVCDPropertyInterface> getInterface( const GUID& id = GUID_NULL );

Parameter | Description
id | Specifies the GUID of the interface for which to search.
Return value:

The interface of the element with the specified GUID, or 0 if the interface was not found.

See also: IVCDPropertyElement, IVCDPropertyInterface, Standard Interface GUIDs

<< IVCDPropertyElement


IVCDPropertyElement::getInterfacePtr

IVCDPropertyElement::getInterfacePtr Method
Retrieves a pointer to an interface of this element. The type of desired interface is determined by the parameter.
Syntax:
// VC 6:
template<class TItf>
TItf getInterfacePtr( TItf& pItf )
// VC 7.1:
template<class TItf>
smart_com<TItf> getInterfacePtr( smart_com<TItf>& pRval )

Parameter | Description
pItf | Pointer to a VCDPropertyInterface-derived type. You must use a tIVCD%%%PropertyPtr here. If the method is successful, the pointer will point to the found interface.
pRval | Pointer to a VCDPropertyInterface-derived type. If the method is successful, the pointer will point to the found interface.
Return value:

This method returns its parameter.

See also: IVCDPropertyElement, IVCDPropertyInterface

<< IVCDPropertyElement


IVCDPropertyElement::getInterfaces

IVCDPropertyElement::getInterfaces Method
Returns all interfaces that are contained by the element.
Syntax:
tVCDPropertyInterfaceArray getInterfaces();
tVCDPropertyInterfaceArray getInterfaces() const;
Return value:

An array of interfaces that are contained by the element.

See also: IVCDPropertyElement, IVCDPropertyInterface, tVCDPropertyInterfaceArray

<< IVCDPropertyElement


IVCDPropertyElement::getName

IVCDPropertyElement::getName Method
Gets the display name of the element.
Syntax:
std::string getName() const;
Return value:

The display name of the element.

See also: IVCDPropertyItem, IVCDPropertyItem::getNameW

<< IVCDPropertyElement


IVCDPropertyElement::getNameW

IVCDPropertyElement::getNameW Method
Gets the display name of the element.
Syntax:
std::wstring getNameW() const;
Return value:

The display name of the element.

See also: IVCDPropertyElement, IVCDPropertyItem::getName

<< IVCDPropertyElement


IVCDPropertyElement::getParent

IVCDPropertyElement::getParent Method
Retrieves the item to which this element belongs.
Syntax:
tIVCDPropertyItemPtr getParent() const;
Return value:

A pointer to the parent item.

See also: IVCDPropertyElement, IVCDPropertyItem

<< IVCDPropertyElement


IVCDPropertyItem

This class represents an item of a video capture device property.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 2.0

Methods

Method | Description
findElement | Searches the collection for a IVCDPropertyElement with a given combination of item and element id.
getElements | Returns all elements that are contained by the item.
getItemID | Gets the GUID of the item.
getName | Gets the display name of the item.
getNameW | Gets the display name of the item.
load | Restores the values of the elements with the values previously saved in an XML string.
loadW | Restores the values of the elements with the values previously saved in an XML string.
save | Saves the values of all elements to an XML string.
saveW | Saves the values of all elements to an XML string.

<< Classes


IVCDPropertyItem::findElement

IVCDPropertyItem::findElement Method
Searches the collection for a IVCDPropertyElement with a given combination of item and element id.
Syntax:
smart_com<IVCDPropertyElement> findElement( const GUID& elemGUID ) const;

Parameter | Description
elemGUID | Specifies GUID of the element for which to search.
Return value:

If the element is found, a pointer to the element is returned. If the search failed, 0 is returned.

See also: IVCDPropertyItem, IVCDPropertyElement, Standard Element GUIDs

<< IVCDPropertyItem


IVCDPropertyItem::getElements

IVCDPropertyItem::getElements Method
Returns all elements that are contained by the item.
Syntax:
tVCDPropertyElementArray getElements() const;
Return value:

An array of elements that are contained by the item.

See also: IVCDPropertyItem, IVCDPropertyElement, tVCDPropertyElementArray

<< IVCDPropertyItem


IVCDPropertyItem::getItemID

IVCDPropertyItem::getItemID Method
Gets the GUID of the item.
Syntax:
GUID getItemID() const;
Return value:

The GUID of the item.

See also: IVCDPropertyItem, Standard Property Item GUIDs

<< IVCDPropertyItem


IVCDPropertyItem::getName

IVCDPropertyItem::getName Method
Gets the display name of the item.
Syntax:
std::string getName() const;
Return value:

The display name of the item.

See also: IVCDPropertyItem, IVCDPropertyItem::getNameW

<< IVCDPropertyItem


IVCDPropertyItem::getNameW

IVCDPropertyItem::getNameW Method
Gets the display name of the item.
Syntax:
std::wstring getNameW() const;
Return value:

The display name of the item.

See also: IVCDPropertyItem, IVCDPropertyItem::getName

<< IVCDPropertyItem


IVCDPropertyItem::load

IVCDPropertyItem::load Method
Restores the values of the elements with the values previously saved in an XML string.
Syntax:
void load( const std::string& data );

Parameter | Description
data | Specifies the string that contains the previously saved data. This string can be obtained by a call to IVCDPropertyItem::save.
See also: IVCDPropertyItem, IVCDPropertyItem::save, IVCDPropertyItem::saveW, IVCDPropertyItem::loadW

<< IVCDPropertyItem


IVCDPropertyItem::loadW

IVCDPropertyItem::loadW Method
Restores the values of the elements with the values previously saved in an XML string.
Syntax:
void loadW( const std::wstring& data );

Parameter | Description
data | Specifies the string that contains the previously saved data. This string can be obtained by a call to IVCDPropertyItem::saveW.
See also: IVCDPropertyItem, IVCDPropertyItem::saveW, IVCDPropertyItem::save, IVCDPropertyItem::load

<< IVCDPropertyItem


IVCDPropertyItem::save

IVCDPropertyItem::save Method
Saves the values of all elements to an XML string.
Syntax:
std::string save() const;
Return value:

A string that contains the saved data.

See also: IVCDPropertyItem, IVCDPropertyItem::load, IVCDPropertyItem::saveW, IVCDPropertyItem::loadW

<< IVCDPropertyItem


IVCDPropertyItem::saveW

IVCDPropertyItem::saveW Method
Saves the values of all elements to an XML string.
Syntax:
std::wstring saveW() const;
Return value:

A string that contains the saved data.

See also: IVCDPropertyItem, IVCDPropertyItem::loadW, IVCDPropertyItem::save, IVCDPropertyItem::load

<< IVCDPropertyItem


IVCDSwitchProperty

This class represents a switch interface to a value of a video capture device property.

A switch interface is used to enable or disable settings of a property.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 2.0

Inheritance

IVCDPropertyInterface
IVCDSwitchProperty

Methods

Method | Description
getSwitch | Gets the current state of the switch.
setSwitch | Sets the switch.

<< Classes


IVCDSwitchProperty::getSwitch

IVCDSwitchProperty::getSwitch Method
Gets the current state of the switch.
Syntax:
bool getSwitch();
Return value:

The current state of the switch.

See also: IVCDSwitchProperty, IVCDPropertyInterface, IVCDSwitchProperty::setSwitch

<< IVCDSwitchProperty


IVCDSwitchProperty::setSwitch

IVCDSwitchProperty::setSwitch Method
Sets the switch.
Syntax:
void setSwitch( bool b );

Parameter | Description
b | Specifies the new value to which the switch will be set.
See also: IVCDSwitchProperty, IVCDPropertyInterface, IVCDSwitchProperty::getSwitch

<< IVCDSwitchProperty


CSimplePropertyAccess

This class wraps access to VCDProperties to make them easier to use.

Information

Header File: Samples\VC71\Common\SimplePropertyAccess.h
Source File: Samples\VC71\Common\SimplePropertyAccess.cpp
Introduced in version 2.0

Methods

Method | Description
CSimplePropertyAccess | Constructs a new instance of CSimplePropertyAccess. If no IVCDPropertyItems are specified, you have to call init to use any other method of the class.
getAuto | Checks whether automation is currently enabled for a specified property.
getDefault | Returns the default value of a specified property.
getRangeMax | Returns the highest possible value of a specified property.
getRangeMin | Returns the lowest possible value of a specified property.
getValue | Returns the value of a specified property.
init | Sets an IVCDPropertyItems collection with the properties to be controlled by this instance.
isAutoAvailable | Returns whether automation is available for a specified property.
isAvailable | Checks whether a specified property is available.
isOnePushAvailable | Returns whether one push is available for a specified property.
push | Invokes one push at a specified property.
setAuto | Enables or disables automation for a specified property.
setValue | Sets the value of a specified property.

<< Helper Classes


CSimplePropertyAccess::CSimplePropertyAccess

CSimplePropertyAccess::CSimplePropertyAccess Method
Constructs a new instance of CSimplePropertyAccess. If no IVCDPropertyItems are specified, you have to call init to use any other method of the class.
Syntax:
CSimplePropertyAccess();
CSimplePropertyAccess( DShowLib::tIVCDPropertyItemsPtr pItems );

Parameter | Description
pItems | Pointer to a IVCDPropertyItems collection, containing the properties to be controlled by this instance.
See also: CSimplePropertyAccess, CSimplePropertyAccess::init, IVCDPropertyItems

<< CSimplePropertyAccess


CSimplePropertyAccess::getAuto

CSimplePropertyAccess::getAuto Method
Checks whether automation is currently enabled for a specified property.
Syntax:
bool    getAuto( const GUID& id );

Parameter | Description
id | GUID of the property to be queried.
Return value:

true, if the property automation is currently enabled, otherwise false.

See also: CSimplePropertyAccess, CSimplePropertyAccess::setAuto

<< CSimplePropertyAccess


CSimplePropertyAccess::getDefault

CSimplePropertyAccess::getDefault Method
Returns the default value of a specified property.
Syntax:
long    getDefault( const GUID& id );

Parameter | Description
id | GUID of the property to be queried.
Return value:

The default value of the property.

See also: CSimplePropertyAccess, CSimplePropertyAccess::setValue

<< CSimplePropertyAccess


CSimplePropertyAccess::getRangeMax

CSimplePropertyAccess::getRangeMax Method
Returns the highest possible value of a specified property.
Syntax:
long    getRangeMax( const GUID& id );

Parameter | Description
id | GUID of the property to be queried.
Return value:

The maximum value of the property.

See also: CSimplePropertyAccess, CSimplePropertyAccess::getRangeMin

<< CSimplePropertyAccess


CSimplePropertyAccess::getRangeMin

CSimplePropertyAccess::getRangeMin Method
Returns the lowest possible value of a specified property.
Syntax:
long    getRangeMin( const GUID& id );

Parameter | Description
id | GUID of the property to be queried.
Return value:

The minimum value of the property.

See also: CSimplePropertyAccess, CSimplePropertyAccess::getRangeMax

<< CSimplePropertyAccess


CSimplePropertyAccess::getValue

CSimplePropertyAccess::getValue Method
Returns the value of a specified property.
Syntax:
long    getValue( const GUID& id );

Parameter | Description
id | GUID of the property whose value is to be retrieved.
Return value:

The current value of the property.

See also: CSimplePropertyAccess, CSimplePropertyAccess::setValue

<< CSimplePropertyAccess


CSimplePropertyAccess::init

CSimplePropertyAccess::init Method
Sets an IVCDPropertyItems collection with the properties to be controlled by this instance.
Syntax:
void init( DShowLib::tIVCDPropertyItemsPtr pItems );

Parameter | Description
pItems | Pointer to a IVCDPropertyItems collection, containing the properties to be controlled by this instance.
See also: CSimplePropertyAccess, CSimplePropertyAccess::CSimplePropertyAccess

<< CSimplePropertyAccess


CSimplePropertyAccess::isAutoAvailable

CSimplePropertyAccess::isAutoAvailable Method
Returns whether automation is available for a specified property.
Syntax:
bool    isAutoAvailable( const GUID& id );

Parameter | Description
id | GUID of the property to be queried.
Return value:

true, if the property supports automation, otherwise false.

See also: CSimplePropertyAccess, CSimplePropertyAccess::setAuto

<< CSimplePropertyAccess


CSimplePropertyAccess::isAvailable

CSimplePropertyAccess::isAvailable Method
Checks whether a specified property is available.
Syntax:
bool isAvailable( const GUID& id );

Parameter | Description
id | GUID of the property to be queried for.
See also: CSimplePropertyAccess, CSimplePropertyAccess::isAutoAvailable, CSimplePropertyAccess::isOnePushAvailable

<< CSimplePropertyAccess


CSimplePropertyAccess::isOnePushAvailable

CSimplePropertyAccess::isOnePushAvailable Method
Returns whether one push is available for a specified property.
Syntax:
bool isOnePushAvailable( const GUID& id );

Parameter | Description
id | GUID of the property to be queried.
Return value:

true, if the property supports one push, otherwise false.

See also: CSimplePropertyAccess, CSimplePropertyAccess::push

<< CSimplePropertyAccess


CSimplePropertyAccess::push

CSimplePropertyAccess::push Method
Invokes one push at a specified property.
Syntax:
void push( const GUID& id );

Parameter | Description
id | GUID of the property for which the one push is to be invoked.
See also: CSimplePropertyAccess, CSimplePropertyAccess::isOnePushAvailable

<< CSimplePropertyAccess


CSimplePropertyAccess::setAuto

CSimplePropertyAccess::setAuto Method
Enables or disables automation for a specified property.
Syntax:
void    setAuto( const GUID& id, bool b );

Parameter | Description
id | GUID of the property whose automation is to be enabled or disabled.
b | New automation state.
See also: CSimplePropertyAccess, CSimplePropertyAccess::getAuto

<< CSimplePropertyAccess


CSimplePropertyAccess::setValue

CSimplePropertyAccess::setValue Method
Sets the value of a specified property.
Syntax:
void    setValue( const GUID& id, long val );

Parameter | Description
id | GUID of the property whose value is to be set.
val | The new value of the property. Must lie in the interval [ getRangeMax.. getRangeMin ].
See also: CSimplePropertyAccess, CSimplePropertyAccess::getValue, CSimplePropertyAccess::getRangeMin, CSimplePropertyAccess::getRangeMax

<< CSimplePropertyAccess


Grabber::getAvailableVCDProperties

Grabber::getAvailableVCDProperties Method
Returns a collection of the IVCDPropertyItems of the currently opened device.
Syntax:
smart_com<IVCDPropertyItems> getAvailableVCDProperties() const;
Return value:

A IVCDPropertyItems object containing all properties of the currently opened device.

Remarks:

A device has to be opened and valid to use this method.

Information:

Introduced in version 2.0
See also: Grabber, IVCDPropertyItems

<< Grabber


Grabber::getPauseLive

Grabber::getPauseLive Method
Returns whether pause mode is enabled.
Syntax:
bool getPauseLive() const;
Return value:

true, if the pause mode is enabled, false, otherwise.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::setPauseLive

<< Grabber


Grabber::setPauseLive

Grabber::setPauseLive Method
Pauses the live mode.
Syntax:
bool setPauseLive( bool on );

Parameter | Description
on | If true, the live mode will be set to pause. If false and live mode is in pause, the live mode will be resumed.
Return value:

true on success, false otherwise.

Remarks:

In live mode the video is immediately paused. Outside live mode the mode is saved and will be set when a Grabber::startLive is called.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::getPauseLive, Grabber::startLive

<< Grabber


Grabber::loadDeviceState

Grabber::loadDeviceState Method
Restores grabber settings that were saved by saveDeviceState.
Syntax:
bool loadDeviceState( const std::string& xmlStr, bool bOpenDev = true );
bool loadDeviceState( const std::wstring& xmlStr, bool bOpenDev = true );

Parameter | Description
xmlStr | Specifies a string that holds the settings. This string can be obtained by calling saveDeviceState.
bOpenDev | If the parameter is set to true, the method tries to open the device that is specified by the settings data. If the parameter is false, no device will be opened, but the settings data will be applied to a device that is already opened.
Return value:

true, if the device state is successfully loaded. If an error occurred, you can call getLastError to retrieve the error code. Malformed XML data in xmlStr causes the error value to be set to eINVALID_PARAM_VAL. If the data is incompatible with this version of IC Imaging Control, the error code is eINCOMPATIBLE_VERSION. eINCOMPLETE tells that not all properties could be initialized with the values in the data string.

Remarks:

If the parameter bOpenDev is set to true, a device specified by its name and its serial number which are stored in the settings data will be opened. If the parameter is set to false, the settings are applied to a device that is already open. The device to which the settings are applied must be of the same type than the device from which the settings data originates.

Information:

Introduced in version 2.0
Sample:

For an example of how to save and load Grabber states, see saveDeviceState
See also: saveDeviceState

<< Grabber


Grabber::loadDeviceStateFromFile

Grabber::loadDeviceStateFromFile Method
Restores the device settings from a file that was previously saved by saveDeviceStateToFile.
Syntax:
bool loadDeviceStateFromFile( const std::string& filename, bool bOpenDev = true );

bool loadDeviceStateFromFile( const std::wstring& filename, bool bOpenDev = true );

Parameter | Description
filename | Specifies the XML file that contains the settings data.
bOpenDev | If the parameter is set to true, the method tries to open the device that is specified by the settings data. If the parameter is false, no device will be opened, but the settings data will be applied to an already opened device.
Return value:

true, if the operation was successful, otherwise false. Call getLastError for extended error information.

Remarks:

If the parameter bOpenDev is set to true, a device specified by its name and its serial number which are stored in the settings data will be opened. If the parameter is set to false, the settings are applied to a device that is already open. The device to which the settings are applied must be of the same type as the device from which the settings data originate.

Information:

Introduced in version 2.0
See also: saveDeviceStateToFile

<< Grabber


Grabber::getCountOfFramesDropped

Grabber::getCountOfFramesDropped Method
Returns the number of frames that were dropped by the video capture device.
Syntax:
long getCountOfFramesDropped() const;
Return value:

The number of droppend frames. This may be 0, if the device does not support this feature.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::isCountOfFramesDroppedAvailable, Grabber::getCountOfFramesNotDropped

<< Grabber


Grabber::getCountOfFramesNotDropped

Grabber::getCountOfFramesNotDropped Method
Returns the number of frames that were delivered by the device.
Syntax:
long getCountOfFramesNotDropped() const;
Return value:

The number of frames that were delivered successfully by the video capture device. This may be 0, if the device does not support this feature.

Remarks:

Please note that frames that were delivered successfully by the video capture device can still be dropped along the way. The return value just counts the number of frames successfully delivered by the device.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::isCountOfFramesDroppedAvailable, Grabber::getCountOfFramesDropped

<< Grabber


Grabber::showDevicePage

Grabber::showDevicePage Method
Shows a device settings page.
Syntax:
bool showDevicePage( HWND hParent = 0 );

Parameter | Description
hParent | The parent of this dialog. If set to 0 (this is the default), then the active window is used as the parent, because the page needs to be modal.
Return value:

true if the user selected a device and clicked OK, false otherwise. Check Grabber::getLastError for details about the error condition.

Remarks:

The device settings page allows easy configuration of the video capture device. The dialog allows the setting of the device, the video norm, the video format, the input channel, the frame rate and it shows the serial number of the currently selected device. Please note: The device must not be in live mode for the device settings page to work.

Information:

Introduced in version 2.0
See also: Grabber

<< Grabber


Grabber::showVCDPropertyPage

Grabber::showVCDPropertyPage Method
Shows the property page for this device. With the property page, the user can adjust property settings like brightness.
Syntax:
bool showVCDPropertyPage( HWND hParent = 0, const std::string& title = "" );
bool showVCDPropertyPage( HWND hParent, const std::wstring& title );

Parameter | Description
hParent | The parent window of this property page. If set to 0 (this is the default), then the active window is used as the parent, because the page needs to be modal.
title | The title of the property dialog. It defaults to an empty string (no title).
Return value:

true on success, false otherwise.

Information:

Introduced in version 2.0
See also: Grabber

<< Grabber


Grabber::isSignalDetectedAvailable

Grabber::isSignalDetectedAvailable Method
Checks whether a device can be queried for a list of available video stream.
Syntax:
bool isSignalDetectedAvailable() const;
Return value:

true, if a device can be queried for a list of available video stream, false otherwise.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::getSignalDetected

<< Grabber


Grabber::getSignalDetected

Grabber::getSignalDetected Method
Returns whether a signal was detected by the device.
Syntax:
bool getSignalDetected() const;
Return value:

true, if the driver of the device detected a signal, false, if either no signal was detected or an error occurred (e.g. option not available).

Remarks:

This flag is only intended for devices that get a signal from an external device, e.g. a converter which gets its video from an analog camera.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::isSignalDetectedAvailable

<< Grabber


Grabber::openDevByUniqueName

Grabber::openDevByUniqueName Method
Opens a device by its unique name.
Syntax:
bool openDevByUniqueName( const std::string& unique_name );
bool openDevByUniqueName( const std::wstring& unique_name );

Parameter | Description
unique_name | The unique name that specifies the device to be opened.
Return value:

true, if the video capture device could be opened successfully, false otherwise.

Remarks:

The unique name of a device can be obtained by calling VideoCaptureDeviceItem::getUniqueName.

Please note that the unique name includes the serial number of the device. Therefore, it only exists for devices that have a serial number.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::openDev, VideoCaptureDeviceItem::getUniqueName

<< Grabber


Grabber::openDevByDisplayName

Grabber::openDevByDisplayName Method
Opens a device by its display name.
Syntax:
bool openDevByDisplayName( const std::string& display_name );
bool openDevByDisplayName( const std::wstring& display_name );

Parameter | Description
display_name | The display name that specifies the device to be opened.
Return value:

true, if the video capture device could be opened successfully, false otherwise.

Remarks:

The display name of a device can be obtained by calling VideoCaptureDeviceItem::getDisplayName.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::openDev, VideoCaptureDeviceItem::getDisplayName

<< Grabber


Grabber::isFrameRateListAvailable

Grabber::isFrameRateListAvailable Method
Checks whether the currently selected video capture device supports different frame rates that can be set by the user.
Syntax:
bool isFrameRateListAvailable() const;
bool isFrameRateListAvailable( const VideoFormatItem& op ) const;

Parameter | Description
VideoFormatItem | Specifies the video format that should be checked for supported frame rates. If no video format is specified, the currently selected video format is used.
Return value:

true if the device supports different frame rates for the given video format, false otherwise.

Remarks:

If the device supports multiple frame rates, list can be retrieve by getAvailableFPS.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::getAvailableFPS, Grabber::getCurrentActualFPS, Grabber::getCurrentMaxAvailableFPS, Grabber::getAvailableFrameRates, Grabber::getFPS, Grabber::setFPS

<< Grabber


Grabber::getAvailableFPS

Grabber::getAvailableFPS Method
Returns the available frame rates.
Syntax:
tFPSListPtr getAvailableFPS() const;
tFPSListPtr getAvailableFPS( const VideoFormatItem& op ) const;

Parameter | Description
VideoFormatItem | Specifies the video format for which to get the frame rates. If no video format is specified, the current video format is used.
Return value:

A pointer to an array that contains the available frame rates.

Remarks:

The frame rates describe the number of frames per second.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::isFrameRateListAvailable, Grabber::getCurrentActualFPS, Grabber::getCurrentMaxAvailableFPS, Grabber::getFPS, Grabber::setFPS, Grabber::tFPSListPtr

<< Grabber


Grabber::getCurrentActualFPS

Grabber::getCurrentActualFPS Method
Retrieves the actual frame rate achieved by the device.
Syntax:
double getCurrentActualFPS() const;
Return value:

The current frame rate.

Remarks:

The frame rate describes the time from the start of one frame to the next in milliseconds.

This method is only available in live mode.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::isFrameRateListAvailable, Grabber::getAvailableFPS, Grabber::getCurrentMaxAvailableFPS, Grabber::getFPS, Grabber::setFPS

<< Grabber


Grabber::getCurrentMaxAvailableFPS

Grabber::getCurrentMaxAvailableFPS Method
Returns the current maximal frames per second (FPS) that the device can achieve on the bus.
Syntax:
double getCurrentMaxAvailableFPS() const;
Return value:

The maximal frame rate, or 0, if the device does not support this feature or cannot supply it in the current mode of operation.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::isFrameRateListAvailable, Grabber::getAvailableFPS, Grabber::getCurrentActualFPS, Grabber::getFPS, Grabber::setFPS

<< Grabber


Grabber::getFPS

Grabber::getFPS Method
Returns the frame rate currently set.
Syntax:
double getFPS() const;
Return value:

The current frame rate. The return value describes number for frames per second.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::isFrameRateListAvailable, Grabber::getAvailableFPS, Grabber::getCurrentActualFPS, Grabber::getCurrentMaxAvailableFPS, Grabber::setFPS

<< Grabber


Grabber::setFPS

Grabber::setFPS Method
Sets the frame rate of the device.
Syntax:
bool setFPS( double fps );

Parameter | Description
fps | The frame rate to be set, specified in frames per second.
Return value:

true, if the frame rate could be set successfully, false, otherwise.

Remarks:

The frame rate can only be set, if the device is not in live mode.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::isFrameRateListAvailable, Grabber::getAvailableFPS, Grabber::getCurrentActualFPS, Grabber::getCurrentMaxAvailableFPS, Grabber::getFPS

<< Grabber


VideoCaptureDeviceItem::getUniqueName

VideoCaptureDeviceItem::getUniqueName Method
Returns a unique name for this device.
Syntax:
std::string getUniqueName() const;
std::wstring getUniqueNameW() const;
Return value:

A string containing the unique name of the device. If an error occurred, an empty string is returned.

Remarks:

A unique name is only available for devices that return a serial number. Using this name, a device can be identified unambiguously.

Information:

Introduced in version 2.0
See also: VideoCaptureDeviceItem, VideoCaptureDeviceItem::c_str, VideoCaptureDeviceItem::toString, VideoCaptureDeviceItem::getName, VideoCaptureDeviceItem::getBaseName, VideoCaptureDeviceItem::getDisplayName

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::getDisplayName

VideoCaptureDeviceItem::getDisplayName Method
Returns the display name of the video capture device.
Syntax:
std::string getDisplayName() const;
std::wstring getDisplayNameW() const;
Return value:

The display name of the video capture device.

Remarks:

This method returns the unique name of the device on the system. USB devices keep the same name as long their USB port is not changed. IEEE 1394 devices keep their names, but may have a different name on a different machine.
Information:

Introduced in version 2.0
See also: VideoCaptureDeviceItem, VideoCaptureDeviceItem::c_str, VideoCaptureDeviceItem::toString, VideoCaptureDeviceItem::getName, VideoCaptureDeviceItem::getBaseName, VideoCaptureDeviceItem::getDisplayName

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::getBaseName

VideoCaptureDeviceItem::getBaseName Method
Returns the base name of the video capture device.
Syntax:
std::string getBaseName() const;
std::wstring getBaseNameW() const;
Return value:

The base name of the video capture device.

Remarks:

The base name of a video capture device is its device name without the identification number appended. For example, if three identical devices (in this case, "Video to 1394 Converters") are connected to the PC, their names, as getName returns, are:

  • Video to 1394 Converter
  • Video to 1394 Converter 1
  • Video to 1394 Converter 2

The numbers appended to the name are used to distinguish between the devices. This method, however, returns the base name which is the same for all 3 devices above:

  • Video to 1394 Converter
Information:

Introduced in version 2.0
See also: VideoCaptureDeviceItem, VideoCaptureDeviceItem::c_str, VideoCaptureDeviceItem::toString, VideoCaptureDeviceItem::getName, VideoCaptureDeviceItem::getUniqueName, VideoCaptureDeviceItem::getDisplayName

<< VideoCaptureDeviceItem


reffunctions::saveToFileJPEG

saveToFileJPEG Method
This function saves the contents of an image buffer to a JPEG file.
Syntax:
Error saveToFileJPEG( const IFrame& buf, const std::string& filename, int quality = 75 );
Error saveToFileJPEG( const IFrame& buf, const std::wstring& filename, int quality = 75 );
Error saveToFileJPEG( const IFrame& buf, const wchar_t* pFilename, int quality = 75 );

Parameter | Description
buf | The buffer that is to be saved.
filename | Specifies the filename of the JPEG file.
pFilename | Specifies the filename of the JPEG file.
quality | Specifies the quality of the JPEG file. This value must be within the range [0,100], with 100 being the highest quality.
Return value:

This method returns an error object. If successful, it is set to eNOERROR. If the conversion fails, eINVALID_PARAM_VAL is returned.

Remarks:

This method saves the contents of the passed IFrame into a JPEG file with the given quality. The contents of the IFrame are internally converted into JPEG format. This conversion may take a while.

Information:

Introduced in version 2.0
Sample:

The following sample shows how to snap an image and save it to a JPEG file.

if( m_Grabber.isLive())
{
    if( m_Grabber.snapImages())
    {
        DShowLib::saveToFileJPEG(*m_Grabber.getActiveMemBuffer(),"Testimage.jpg",90);
    }
}
See also: IFrame, saveToFileBMP

<< Class Library Reference


reffunctions::saveToFileBMP

saveToFileBMP Method
This function saves the contents of an image buffer to a .BMP file.
Syntax:
Error saveToFileBMP( const IFrame& buf, const std::string& filename );
Error saveToFileBMP( const IFrame& buf, const std::wstring& filename );
Error saveToFileBMP( const IFrame& buf, const wchar_t* pFilename );

Error saveToFileBMP( const IFrame& buf, const std::string& filename, tColorformatEnum file_fmt );
Error saveToFileBMP( const IFrame& buf, const std::wstring& filename, tColorformatEnum file_fmt );
Error saveToFileBMP( const IFrame& buf, const wchar_t* pFilename, tColorformatEnum file_fmt );

Parameter | Description
buf | The buffer that is to be saved.
filename | Specifies the filename of the .BMP file.
pFilename | Specifies the filename of the .BMP file.
file_fmt | Specifies the color format of the .BMP file.
Return value:

This method returns an error object. On success, it is set to eNOERROR. If the conversion fails, eINVALID_PARAM_VAL is returned.

Remarks:

This method saves the contents of the passed IFrame into a .BMP file. If no file_fmt parameter is given, the format of the bitmap file (BITMAPINFO) is specified by the IFrame. If file_fmt is set and it differs from the color format currently set in IFrame, the contents are converted on the fly. This conversion may take awhile.

Information:

Introduced in version 2.0
See also: IFrame, saveToFileJPEG, tColorformatEnum

<< Class Library Reference


OverlayBitmap::drawFrameRect

OverlayBitmap::drawFrameRect Method
Draws the frame of a rectangle on the live video.
Syntax:
bool drawFrameRect( COLORREF color, const RECT& rect );

Parameter | Description
color | Specifies the color of the frame of the rectangle. The color can be specified with the RGB macro.
rect | The rectangle to be drawn in pixel coordinates. A CRect object or a RECT structure can be passed for this parameter.
Return value:

true on success, false otherwise.

Information:

Introduced in version 2.0
Sample:

This example demonstrates how draw two rectangles on the live video stream.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
pOverlayBitmap = m_Grabber.getOverlay();
if( pOverlayBitmap->canRender() == true)
{
    // Make sure, the overlay is enabled.
    pOverlayBitmap->setEnable(true);

    // Draw a rectangle in magenta, using a CRect object.
    pOverlayBitmap->drawFrameRect( RGB(255,0,255),
                                  CRect(100,50,50,25));

    // Draw a rectangle in blue, using a RECT structure.
    RECT rectangle;
    rectangle.left   = 160;
    rectangle.right  = 200;
    rectangle.top    = 160;
    rectangle.bottom = 180;
    pOverlayBitmap->drawFrameRect( RGB(0,0,255),    rectangle);
}
See also: OverlayBitmap, OverlayBitmap::drawText, OverlayBitmap::drawLine, OverlayBitmap::drawSolidRect, OverlayBitmap::drawSolidEllipse, OverlayBitmap::drawFrameEllipse

<< OverlayBitmap


OverlayBitmap::drawSolidEllipse

OverlayBitmap::drawSolidEllipse Method
Draws a solid ellipse on the live video.
Syntax:
bool drawSolidEllipse( COLORREF color, const RECT& rect );

Parameter | Description
color | Specifies the color of the ellipse. The color can be specified with the RGB macro.
rect | Specifies the surrounding rectangle of the ellipse in pixel coordinates. A CRect object or a RECT structure can be passed for this parameter.
Return value:

true on success, false otherwise.

Information:

Introduced in version 2.0
Sample:

This example demonstrates how draw two ellipses on the live video stream.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
pOverlayBitmap = m_Grabber.getOverlay();
if( pOverlayBitmap->canRender() == true)
{
    // Make sure, the overlay is enabled.
    pOverlayBitmap->setEnable(true);

    // Draw a rectangle in magenta, using a CRect object.
    pOverlayBitmap->drawSolidEllipse( RGB(255,0,255),
                                    CRect(100,50,50,25));

    // Draw a rectangle in blue, using a RECT structure.
    RECT rectangle;
    rectangle.left   = 160;
    rectangle.right  = 200;
    rectangle.top    = 160;
    rectangle.bottom = 180;
    pOverlayBitmap->drawSolidEllipse( RGB(0,0,255),    rectangle);
}
See also: OverlayBitmap, OverlayBitmap::drawText, OverlayBitmap::drawLine, OverlayBitmap::drawSolidRect, OverlayBitmap::drawFrameRect, OverlayBitmap::drawFrameEllipse

<< OverlayBitmap


OverlayBitmap::drawFrameEllipse

OverlayBitmap::drawFrameEllipse Method
Draws the frame of an ellipse on the live video.
Syntax:
bool drawFrameEllipse( COLORREF color, const RECT& rect );

Parameter | Description
color | Specifies the color of the ellipse. The color can be specified with the RGB macro.
rect | Specifies the surrounding rectangle of the ellipse in pixel coordinates. A CRect object or a RECT structure can be passed for this parameter.
Return value:

true on success, false otherwise.

Information:

Introduced in version 2.0
Sample:

This example demonstrates how draw two ellipses on the live video stream.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;

pOverlayBitmap = m_Grabber.getOverlay();
if( pOverlayBitmap->canRender() == true)
{
    // Make sure, the overlay is enabled.
    pOverlayBitmap->setEnable(true);

    // Draw a rectangle in magenta, using a CRect object.
    pOverlayBitmap->drawFrameEllipse( RGB(255,0,255),
        CRect(100,50,50,25));

    // Draw a rectangle in blue, using a RECT structure.
    RECT rectangle;
    rectangle.left   = 160;
    rectangle.right  = 200;
    rectangle.top    = 160;
    rectangle.bottom = 180;
    pOverlayBitmap->drawFrameEllipse( RGB(0,0,255),    rectangle);
}
See also: OverlayBitmap, OverlayBitmap::drawText, OverlayBitmap::drawLine, OverlayBitmap::drawSolidRect, OverlayBitmap::drawFrameRect, OverlayBitmap::drawSolidEllipse

<< OverlayBitmap


OverlayBitmap::getColorformat

OverlayBitmap::getColorformat Method
Returns the current color format used for the overlay.
Syntax:
tColorformatEnum    getColorformat() const;
Return value:

This method returns the current color format.

Information:

Introduced in version 2.0
See also: OverlayBitmap

<< OverlayBitmap


Project Wizards

For Visual C++ 7.1, 8.0, 9.0 and 10, there are so called "wizards" that allow you to easily setup an application using IC Imaging Control. Similarly, there are others that may be used to setup a frame filter and a frame filter module.

All IC Imaging Control wizard names start with "IC" e.g. "IC Frame Filter Class".

Dialog Application Wizard

This chapter shows how to use a project wizard to set up a Visual C++ dialog based application project that uses the library.

Frame Filter Class Wizard

This chapter shows how to create a new frame filter class, using the frame filter class wizard.

Frame Filter Parameter Wizard

This chapter shows how to add a new parameter to a frame filter class using the Frame Filter Parameter wizard.

Frame Filter Module Wizard

This chapter shows how to use a project wizard to create a frame filter module. A frame filter module can be loaded by other IC Imaging Control applications.

<< IC Imaging Control Class Library User's Guide


Dialog Application Wizard

This chapter shows how to use a project wizard to set up a Visual C++ dialog based application project that uses the library.

Introduction

Since there are many things to be considered when you create a new Visual VC++ project, IC Imaging Control comes with an application wizard. This wizard creates a dialog based application. The following functionality is available as default:

  • Button handler for opening a video capture device
  • Button handler for image settings
  • Button handler for start and stop the live video
  • Automatic reload of the previously used video capture device

Optional functions are:

  • Add image processing capabilities
  • Display the result of the image processing instead of the live video

How to use

First of all, start Visual Studio 2003 as usual. As soon as the Start Page is shown, click on the New Project button. Otherwise, select File -> New -> Project from Visual Studio's menu.

The following dialog is shown:

Select the icon named IC Dialog Application. Enter a valid project name at the Name input field e.g. "ImageProcessing". Then, click on the OK button. Now, you can adjust the projects's properties:

Enter the license key that was provided with IC Imaging Control in the input field IC License Key If you are using the trial version of IC Imaging Control, please enter '0';

If you check the check box Enable image processing, the wizard inserts a class CListener in to the project. This class is inherited from GrabberListener. It will be registered as callback handler object to the Grabber. The image processing is done in the CListener object. The source code that the wizard generates illustrates how to invert an image - a basic image processing task.

If you check the check box Display the resulting image, the result of the image processing, instead of the live video is displayed in the dialog.

The input field IC Installation Path contains the installation directory of IC Imaging Control. The classlib\*\TIS_UDSHL*.LIB libraries are included from this directory. Additionally, the executable of the project is saved into these directories. This ensures that all dependencies can be solved.

When you have followed the steps discussed on this page, click on the Finish button. The project will be created by the wizard. To run the project, press the F5 key. The newly created dialog application looks like this:

<< First Steps


Frame Filter Class Wizard

This chapter shows how to create a new frame filter class, using the frame filter class wizard.

Introduction

The frame filter class wizard creates the source code for a frame filter class. Optionally, a property dialog for this frame filter can be added. The image processing implemented by the filter inverts the incoming frames. This should be overwritten by the programmer.

The frame filter class wizard adds two member variables to the class:

m_bEnabled
This boolean value can be used in the transform method of the frame filter class to enable or disable image processing. This variable is exported by the frame filter class. Thus, the methods setEnabled and getEnabled are inserted into the frame filter class. In the constructor of the class, this variable is added to the property list of the frame filter:
addBoolParam( L"Enable", getEnabled, setEnabled);
m_lValue
This long value is only for educational purposes. It shows how to add and export a frame filter variable as a parameter. The code for the import and export methods and the insertion of the variable into the exported parameter list is created by the wizard.

If a property dialog is created by the frame filter class wizard (see below), then these two member variables can be modified in this dialog.

The Frame Filter Parameter Wizard can be used to add new property variables to a frame filter class.

How to use

The Frame Filter Class Wizard can be used in an application project only. Thus, an IC Imaging Control application should be created first. The Dialog Application Wizard can be used for this task.

In Visual Studio, open the Class View. In the Class View, right click on the applications name (the root entry on the top). In the context menu that is now displayed, select Add... -> Add class.... Now, the class wizard selection is shown:

Next, double click the IC Frame Filter Class icon. Now, the properties of the frame filter class are shown:

Input field description

Class name
This is the name of the class e.g. CMyFilter.
.h file
This is the name of the header file of the class. The name is generated by the class wizard. You may overwrite this name, if you wish.
.cpp file
This is the name of the cpp file of the class. The name is generated by the class wizard. You may overwrite this name, if you wish.
Filter name
This is the name of the filter that is used, if the filter is inserted into a filter list in an application. Click here for a sample of the resulting source code.
Transform filter / Update filter
These radio buttons determine, whether the newly created frame filter is a transform or an update filter. If the video format or color format of a frame is changed in the filter, then a transform filter is used. It creates a new frame in memory in to which the data of the source frame is copied.
The update filter performs the changes directly in the current frame.
Property dialog
If you check this check box, the wizard creates a property dialog for the frame filter class. You can use the property dialog to adjust the parameters of the class.
Notify at start and stop live video
If this check box is checked, then the frame filter class wizard inserts the methods that are called when startLive and stopLive are called. The methods are named notifyStart and notifyStop. You can also add a new boolean attribute 'm_bLiveVideoRunning' to the class. The methods look like follows:
//////////////////////////////////////////////////////////////////////////
// This method is called by the framework when the live video is started.
//////////////////////////////////////////////////////////////////////////
void CMyFilter::notifyStart( const FrameTypeInfo& in_type, const FrameTypeInfo& out_type )
{
    m_bLiveVideoRunning = true;
}

//////////////////////////////////////////////////////////////////////////
// This method is called by the framework when the live video is stopped.
//////////////////////////////////////////////////////////////////////////
void CMyFilter::notifyStop()
{
    m_bLiveVideoRunning = false;
}

Once you have completed all of the above steps, click the Finish button. Now, the wizard creates the class.

<< Project Wizards


Frame Filter Parameter Wizard

This chapter shows how to add a new parameter to a frame filter class using the Frame Filter Parameter wizard.

Introduction

A frame filter parameter provides a generic way of manipulating a frame filter's behavior. After a frame filter has been created, using the Frame Filter Module Wizard, frame filter parameters can be added. By using the Frame Filter Parameter Wizard, a member variable and two access methods are added to the filter class. The access methods are registered in the filter's constructor, so that they can be accessed from code that uses the frame filter.

How to use

You can find the Frame Filter Parameter Wizard in Visual Studio's Class View. In the Class View, right click on the application's name (the root entry on the top). In the context menu that is now displayed, click on the Add button and on the sub-menu Add class. (Please be sure that you use Add Class - due to technical reasons the context menu of the Class View can not be enhanced.) The parameter wizard selection is shown, as follows:

Select the IC Frame Filter Parameter icon. Then, click on the Open button. Now, you can enter the properties of the new member variable:

Input field description

Class name
The class in to which the new member variable is to be inserted, can be selected in this combo box. This combo box contains all frame filter classes of the current project.
Display name
This is the name of the parameter that is used when an application accesses the parameter, using IFrameFilter::setParameter or IFrameFilter::getParameter.
Variable name
This is the C++ name of the member variable in the frame filter class.
Type
Using this combo box, you can select the type of the member variable.
Access
Using this combo box, you can select the access type (public, private or protected) of the member variable.
Parameter limits
If the new member variable is of a numeric type, such as long or float, you can set minimum and maximum values. In the associated set-method of this member variable, the limits are checked. Should a value be set that does not lie within the bounds of the values specified here, eINVALID_PARAM_VALUE is returned by the set-method:
tFilterError CMyFilter::setTheVariable(long Value)
{
    if( Value >= 0 && Value <= 255)
        m_TheVariable = Value;
    else
        return eINVALID_PARAM_VALUE;
    return eNO_ERROR;
}
Can only be set, if live video is not running
Some properties may only be set, if live video is not running. If this check box is checked, the functionality for checking this will be implemented into the frame filter class. If the notifyStart and notifyStop methods are not already implemented in the frame filter class, they will be implemented automatically by the Frame Filter Parameter Wizard. Using these methods, the frame filter class can determine, whether the live video has been started or stopped. A new internal member variable m_bLiveVideoRunning is inserted in to the class. When the live video is started, it is set to true. This variable is checked in the set-method of the new parameter:
tFilterError CMyFilter::setTheVariable(long Value)
{
    if( m_bLiveVideoRunning == true )
        return eINVALID_FILTER_STATE;
    else
    {
        m_TheVariable = Value;
    }
    return eNO_ERROR;
}
If the setTheVariable method is called while the live video is running, the member variable m_TheVariable will not be set. Instead eINVALID_FILTER_STATE is returned.

Once you have followed all the above instructions, click on the finish button. The new member variable and the related methods are implemented by the Frame Filter Parameter Wizard. If a property dialog is associated with the frame filter class, it is not altered by the Frame Filter Parameter Wizard.

<< Project Wizards


Frame Filter Module Wizard

This chapter shows how to use a project wizard to create a frame filter module. A frame filter module can be loaded by other IC Imaging Control applications.

How to use

First of all, start Visual Studio 2003. If the "Start Page" is shown, click on the button "New Project". Otherwise, select File -> New -> Project from Visual Studio's menu.

The following dialog is shown:

Select the icon called IC Frame Filter Module. Enter a valid project name into the Name input field e.g. MyFilterModule. - this will be the name of the resulting FTF module file. Then, click the OK button. Now the project properties can be adjusted:

Input field description

The Frame Filter Module Wizards adds a Frame Filter class to the project. The input fields are nearly the same as in the Frame Filter Class Wizard

Filter name
This is the name of the filter that is specified by the user of the filter when creating it. Click here for a sample of the resulting source code.
Class name
This is the name of the class e.g. CMyFilter.
.h file
This is the name of the header file of the class. The name is generated by the class wizard. You may overwrite this name.
.cpp file
This is the name of the cpp file of the class. The name is generated by the class wizard. You may overwrite this name.
Transform filter / Update filter
These radio buttons determine, whether the newly created frame filter is a transform or an update filter. If the video format or color format of a frame is changed in the filter, a transform filter is used. It creates a new frame in memory in to which the data of the source frame is copied.
The update filter performs the changes directly in the current frame, so it is changed.
Property dialog
If this check box is checked, then the wizard will create a property dialog for the frame filter class. The property dialog is used to adjust parameters of the class.
Notify at start and stop live video
If you check this check box, the frame filter class wizard inserts the methods, that are called when startLive and stopLive are called. The methods are named notifyStart and notifyStop. Also a new boolean attribute m_bLiveVideoRunning is added to the class. The methods look like follows:
//////////////////////////////////////////////////////////////////////////
// This method is called by the framework when the live video is started.
//////////////////////////////////////////////////////////////////////////

void CMyFilter::notifyStart( const FrameTypeInfo& in_type, const FrameTypeInfo& out_type )
{
    m_bLiveVideoRunning = true;
}

//////////////////////////////////////////////////////////////////////////
// This method is called by the framework when the live video is stopped.
//////////////////////////////////////////////////////////////////////////

void CMyFilter::notifyStop()
{
    m_bLiveVideoRunning = false;
}
IC installation path
This text box contains the installation directory of IC Imaging Control. The classlib\*\TIS_UDSHL*.LIB libraries are included from this path. Additionally, the .ftf file that is created is saved in this directory.

Once you have followed all of the above steps, click on the Finish button. Now the wizard creates the class.

<< Project Wizards


Programmer's Guide

This part illustrates how to perform your first steps with IC Imaging Control. In addition, a set of sample projects show the usage of the library. They focus on special aspects such as image processing, display and overlay techniques etc.

First Steps

This chapter shows you how to set up a Visual C++ .NET project that uses the class library.

Acquire Video Format Information

This example demonstrates how to acquire information about the available video formats.

Binning and ROI

This chapter shows you how to handle video capture device, that support binning and ROI on the sensor.

Acquire Property Information

This example demonstrates how to acquire information about the properties supported by a selected video capture device.

Using a Callback Function

This example demonstrates how to use a GrabberListener derived callback handler object to process events.

Using Memory Buffer Collections

This example demonstrates how to create a memory buffer collection, which uses user allocated buffers.

Making Device Settings

This chapter shows you how to create a custom device settings dialog.

Writing Image Streams to an AVI file

This example demonstrates how to write a sequence of images to an AVI file.

Writing an Image Stream to a video file

This example demonstrates how to write a sequence of images to a video file.

Properties of a Codec

This example demonstrates how to get and set the properties of a codec.

Scroll and Zoom

This example demonstrates how to change the size and how to scroll the live video image.

Creating an Overlay

This example demonstrates how to draw graphic elements, such as lines and text on the live video image.

Accessing an Image Buffer

This example shows the how to handle image buffers.

Basic Use of VCD Properties

This chapter describes the basic functionality of the VCDProperties. It shows you how to retrieve interfaces, which allow you to manipulate elements, such as the value or the automation state of a property.

List VCD Properties

This chapter shows you how to retrieve all properties of a video capture device, using the new VCD property interface. In addition, it is shown how to access and manipulate a property using predefined IDs.

Filter Inspector

This example demonstrates how to use frame filters to perform basic image processing.

Writing a Frame Filter: Binarization

This example demonstrates how to create frame filters to apply binarization to live video.

Creating a Filter Module

This example demonstrates how to create a filter module, containing frame filter implementations.

Project Wizards

For Visual C++ 7.1, 8.0, 9.0 and 10, there are so called "wizards" that allow you to easily setup an application using IC Imaging Control. Similarly, there are others that may be used to setup a frame filter and a frame filter module.

<< IC Imaging Control Class Library User's Guide


First Steps

This chapter shows you how to set up a Visual C++ .NET project that uses the class library.

Dialog Application Wizard

This chapter shows how to use a project wizard to set up a Visual C++ dialog based application project that uses the library.

First Steps VC.NET

This chapter shows you how to manually set up a Visual C++ .NET project that uses the library, without using a wizard.

<< Programmer's Guide


First Steps VC.NET

This chapter shows you how to manually set up a Visual C++ .NET project that uses the library, without using a wizard.

Steps

  • Creating the Project
  • Project Properties
  • Including the class library header files
  • Library Initialization
  • Instanciating the Grabber
  • Select a Video Capture Device and display a Live Image

<< First Steps


Acquire Video Format Information

This example demonstrates how to acquire information about the available video formats.

The program can be found in the %TOPLEVEL%\Samples\VC71\VideoNormFormat directory. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6. In order to run the program, open the solution file VidNormFormat.sln in this directory and select Build -> Build VideoNormFormat in the menu. Then the program can be executed by selecting Debug -> Start.

Opening a Device

The program will generate a list of all available video capture devices and prompt the user for the device to open.

Grabber::tVidCapDevListPtr pVidCapDevList = grabber.getAvailableVideoCaptureDevices();
if( pVidCapDevList == 0 || pVidCapDevList->empty() )
{
    return -1; // No device available.
}

int choice = presentUserChoice( toStringArrayPtr( pVidCapDevList ) );
// Open the selected video capture device.
if( choice == -1 )
{
    return -1;
}
grabber.openDev( pVidCapDevList->at( choice ) );

First, Grabber::getAvailableVideoCaptureDevices is called to retrieve a list with the video capture devices connected to the computer. The helper function presentUserChoice from %TOPLEVEL%\Samples\VC71\Common\CmdHelper.h is called to output the available devices to the console and let the user input a number.

The selected video capture device is opened by calling Grabber::openDev.

Selecting a Video Norm

If the selected device supports multiple video norms, all available video norms will be printed to the screen and the user will be asked for a norm. If the user selects a norm, all video formats available for the selected norm are printed on the screen and the user is again prompted for a video norm until he terminates the program by pressing "q".

// Check whether video norms are available with the current video capture device.
if( grabber.isVideoNormAvailableWithCurDev() )
{
    // Query for all available video norms.
    Grabber::tVidNrmListPtr pVidNrmList = grabber.getAvailableVideoNorms();

    if( pVidNrmList == 0 )
    {
        std::cerr << "Error: " << grabber.getLastError().toString() << std::endl;
        return -1;
    }
    while ( true )
    {
        std::cout << "Video Norms available for " << grabber.getDev().toString() << std::endl;

        int choice = presentUserChoice( *pVidNrmList );
        if( choice != -1 )
        {
            // Set the selected video norm before
            // retrieving the according video formats.
            grabber.setVideoNorm( pVidNrmList->at( choice ) );

Grabber::isVideoNormAvailableWithCurDev is called to check whether the opened video capture device supports video norms. In this case, a list with the available video norms is retrieved by calling Grabber::getAvailableVideoNorms.

After the user selected one of the video norms in presentUserChoice, Grabber::setVideoNorm is used to set the selected norm.

Displaying the Available Video Formats

When a video norm was selected, or video norms are not supported, the available video formats are printed to the screen:

Grabber::tVidFmtListPtr pVidFmtList = grabber.getAvailableVideoFormats();

if( pVidFmtList == 0 ) // No video formats available?
{
    std::cerr << "Error : " << grabber.getLastError().toString() << std::endl;
}
else
{
    unsigned int counter = 0;
    // List the available video formats.
    for( Grabber::tVidFmtList::iterator it = pVidFmtList->begin();
        it != pVidFmtList->end();
        ++it )
    {
        std::cout << "\t[" << counter++ << "] " << it->toString() << std::endl;
    }
}

Grabber::getAvailableVideoFormats returns a list containing the available video formats. In a loop, the names of the formats are displayed. You can get the name of a video format by calling VideoFormatItem::toString.

<< Programmer's Guide


Binning and ROI

This chapter shows you how to handle video capture device, that support binning and ROI on the sensor.

Setting a Video Format with Binning and ROI

In case your video capture device supports binning and ROI, then the most simple way to set a binning and ROI using video format is:

cGrabber.setVideoFormat("RGB32 (640x188) [Binning 4x]");

Enumerate Video Format Descriptions

The following sample code shows, how to enumerate the video format descriptions and create the their video formats with maximum resolution:

Grabber::tVidFmtDescListPtr DecriptionList;

DecriptionList = cGrabber.getAvailableVideoFormatDescs();

for( Grabber::tVidFmtDescList::iterator pDescription = DecriptionList->begin(); pDescription != DecriptionList->end(); pDescription++ )
{
    printf("%s\n", (*pDescription)->toString().c_str());
}

The loop will give following result (this depends on the video capture device):

RGB32 (96x96-2592x1944)
RGB32 (96x96-1296x972) [Binning 2x]
RGB32 (96x96-648x484) [Binning 4x]
Y800 (96x96-2592x1944)
Y800 (96x96-1296x972) [Binning 2x]
Y800 (96x96-648x484) [Binning 4x]
BY8 (96x96-2592x1944)
BY8 (96x96-1296x972) [Binning 2x]
BY8 (96x96-648x484) [Binning 4x]
RGB24 (96x96-2592x1944)
RGB24 (96x96-1296x972) [Binning 2x]
RGB24 (96x96-648x484) [Binning 4x]

The first chars describe the video format, e.g. RBG32. Then the supported minimum resolution, e.g. 96x96 and the supported maximum resolution e.g. 2592x1944 follow. The range between minimum and maximum resolution means, that it is possible to set nearly any size between them to use a custom video format.

If binning is supported in the current video format description, then the text [Binning 2x] or [Binning 4x] follows.

<< Programmer's Guide


Acquire Property Information

This example demonstrates how to acquire information about the properties supported by a selected video capture device.

The program can be found in the %TOPLEVEL%\Samples\VC71\SimpleProperty directory. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6. In order to run the program, open the solution file SimpleProperty.sln in this directory and select Build -> Build SimpleProperty in the menu. Then the program can be executed by selecting Debug -> Start.

The program uses Grabber::showDevicePage to let the user select a video capture device.

The class CSimplePropertyAccess from the %TOPLEVEL%\Samples\VC71\Common directory is used to access the device properties:

CSimplePropertyAccess prop( grabber.getAvailableVCDProperties() );

if( prop.isAvailable( VCDID_Brightness ) )
{
    std::cout << "Brightness property available" << std::endl;

    if( prop.getAuto( VCDID_Brightness ) )
    {
        std::cout << "Brightness auto enabled" << std::endl;
    }
    else
    {
        std::cout << "Brightness auto disabled" << std::endl;

        long val = prop.getValue( VCDID_Brightness );
        std::cout << "Current Brightness value: " << val << std::endl;

        long min = prop.getRangeMin( VCDID_Brightness );
        long max = prop.getRangeMax( VCDID_Brightness );
        std::cout << "Brightness Range: [" << min << ".." << max << "]" << std::endl;
    }

By calling CSimplePropertyAccess::isAvailable with the parameter VCDID_Brightness, the program checks whether the opened video capture device supports the "brightness" property. If brightness is supported, CSimplePropertyAccess::getAuto is called to determine whether the brightness property is in auto mode.

If the brightness property is not in auto mode, CSimplePropertyAccess::getValue is called to get the current brightness value.

<< Programmer's Guide


Using a Callback Function

This example demonstrates how to use a GrabberListener derived callback handler object to process events.

The program can be found in the %TOPLEVEL%\Samples\VC71\Callback directory. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6. In order to run the program, open the solution file SinkType.sln in this directory and select Build -> Build Callback in the menu. Then the program can be executed by selecting Debug -> Start.

Introduction

This example uses a function called setupDeviceFromFile. The source code for this function can be found at %TOPLEVEL%\Samples\VC71\Common\CmdHelper.h. This function asks the user to select the desired video capture device, video norm, video format and input channel. The selected settings are saved, so that you do not have to re-select them every time you run the program.

The following code demonstrates how to setup the FrameHandlerSink that contains the MemBufferCollection that receives the grabbed images.

// Create a FrameTypeInfoArray data structure describing the allowed color formats.
FrameTypeInfoArray acceptedTypes = FrameTypeInfoArray::createRGBArray();

// Create the frame handler sink
smart_ptr<FrameHandlerSink> pSink = FrameHandlerSink::create( acceptedTypes, NUM_BUFFERS );

// enable snap mode (formerly tFrameGrabberMode::eSNAP).
pSink->setSnapMode( true );

// Apply the sink to the grabber.
grabber.setSinkType( pSink );

The program derives a class called "CListener" from GrabberListener. The class implementation can be found in the files "Listener.h" and "Listener.cpp" in the sample's directory.

The class CListener will be registered for GrabberListener::overlayCallback and GrabberListener::frameReady events:

// Register the pListener object for the frame ready and
// the overlay callback event.
grabber.addListener( pListener, GrabberListener::eFRAMEREADY|
                                    GrabberListener::eOVERLAYCALLBACK );

In the GrabberListener::overlayCallback method a frame counter is drawn on the live video.

//////////////////////////////////////////////////////////////////////////
/*! The overlayCallback() method draws the number of the current frame. The
    frame count is a member of the tsMediaSampleDesc structure that is passed
    to overlayCallback() by the Grabber.
*/
void    CListener::overlayCallback( Grabber& caller, smart_ptr<OverlayBitmap> pBitmap,
                                   const tsMediaSampleDesc& MediaSampleDesc)
{
    char szText[25];
    if( pBitmap->getEnable() == true ) // Draw only, if the overlay bitmap is enabled.
    {
        sprintf( szText,"%04d ", MediaSampleDesc.FrameNumber);
        pBitmap->drawText( RGB(255,0,0), 0, 0, szText );
    }
}

In the GrabberListener::frameReady method the specified buffer will be saved to a .BMP file by a call to the CListener::saveImage method.

//////////////////////////////////////////////////////////////////////////
/*! The frameReady() method calls the saveImage method to save the image buffer to disk.
*/
void    CListener::frameReady( Grabber& caller, smart_ptr<MemBuffer> pBuffer, DWORD currFrame)
{
    std::cout << "Buffer " << currFrame << " processed in CListener::frameReady()." << std::endl;

    saveImage( pBuffer, currFrame ); // Do the buffer processing.

    ::Sleep(250); // Simulate a time expensive processing.
}

The public CListener::saveImage method saves the specified buffer to a BMP file. It marks in a bool array which buffers have been saved to disk. Also a Sleep(250) is used to simulate a time expensive processing operation. Therefore, the GrabberListener::frameReady method is not called for all captured buffers.

//////////////////////////////////////////////////////////////////////////
/*! The image passed by the MemBuffer pointer is saved to a BMP file.
*/
void    CListener::saveImage( smart_ptr<MemBuffer> pBuffer, DWORD currFrame)
{
    char filename[MAX_PATH];
    if( currFrame < m_BufferWritten.size() )
    {
        sprintf( filename, "image%02i.bmp", currFrame );

        saveToFileBMP( *pBuffer, filename );

        m_BufferWritten.at( currFrame ) = true;
    }
}

The main() function of the sample uses the bool array of CListener to determine, which captured buffers are not processed in the GrabberListener::frameReady callback. For each not processed buffer, the CListener::saveImage method is called to process the buffer. This shows that no buffer is lost, although the GrabberListener::frameReady callback has not been called for each captured buffer.

// Save the buffers for which CListener::frameReady() has not been called.
// Since CListener::frameReady() calls Sleep(250), it cannot be called for
// every buffer. Nevertheless, all buffers are copied to the MemBufferCollection.
for( size_t i = 0; i < pListener->m_BufferWritten.size(); i++ )
{
    if( !pListener->m_BufferWritten[i] )
    {
        std::cout << "Buffer " << i << " processed in main()." << std::endl;
        pListener->saveImage( pSink->getMemBufferCollection()->getBuffer( i ), i);
    }
}

<< Programmer's Guide


Using Memory Buffer Collections

This example demonstrates how to create a memory buffer collection, which uses user allocated buffers.

The program can be found in the %TOPLEVEL%\Samples\VC71\MemBufferCollection directory. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6. In order to run the program, open the solution file MemBufferCollection.sln in this directory and select Build -> Build MemBufferCollection in the menu. You can then start the program by selecting Debug -> Start.

Opening a Device

The example program uses the setupDeviceFromFile function from %TOPLEVEL%\Samples\VC71\Common\CmdHelper.h. This function displays the device selection dialog and saves the selected device in a configuration file, that is loaded when the function is called again.

Grabber grabber;
if( !setupDeviceFromFile( grabber ) )
{
    return -1;
}

Determine the Required Buffer Size

To find out the required size for the user-allocated buffers, we set a FrameHandlerSink with the desired color format (in this case eY800 ) and call Grabber::prepareLive. After this call, we can retrieve the sink format by calling FrameHandlerSink::getOutputFrameType.

// Set the image buffer format to eY800. eY800 means monochrome, 8 bits (1 byte) per pixel.
// Let the sink create a matching MemBufferCollection with 1 buffer.
tFrameHandlerSinkPtr pSink = FrameHandlerSink::create( eY800, 1 );

// We use snap mode.
pSink->setSnapMode( true );

// Set the sink.
grabber.setSinkType( pSink );

// Prepare the live mode, to get the output size if the sink.
if( !grabber.prepareLive( false ) )
{
    std::cerr << "Could not render the VideoFormat into a eY800 sink.";
    return -1;
}

// Retrieve the output type and dimension of the handler sink.
// The dimension of the sink could be different from the VideoFormat, when
// you use filters.
FrameTypeInfo info;
pSink->getOutputFrameType( info );

Creating a MemBufferCollection with User-Allocated Buffers

Now that we found the sink format, we can create buffers with the appropriate size. FrameTypeInfo::buffersize contains the number of bytes for one image. The MemBufferCollection is created by calling MemBufferCollection::create with the frame type, the number of buffers and the buffer array as parameters:

BYTE* pBuf[5];
// Allocate 5 image buffers of the above calculate buffer size.
for( int i = 0; i < 5; ++i )
{
    pBuf[i] = new BYTE[info.buffersize];
}

// Create a new MemBuffer collection that uses our own image buffers.
tMemBufferCollectionPtr pCollection = MemBufferCollection::create( info, 5, pBuf );
if( pCollection == 0 || !pSink->setMemBufferCollection( pCollection ) )
{
    std::cerr << "Could not set the new MemBufferCollection, because types do not match.";
    return -1;
}

Snapping and Saving Images

After the MemBufferCollection has been set up, the program snaps five images into the buffers and saves them to disk:

// Start live mode for fast snapping. The live video will not be displayed,
// because false is passed to startLive().
grabber.startLive( false );

// Snap 5 images. The images are copied to the MemBufferCollection the
// application created above.
pSink->snapImages( 5 );

// Stop the live video.
grabber.stopLive();

// Close the device.
grabber.closeDev();

// Save the five captured images in the MemBuffer collection to separate files.
pCollection->save( "file*.bmp" );

<< Programmer's Guide


Making Device Settings

This chapter shows you how to create a custom device settings dialog.

The sample program can be found in the %TOPLEVEL%\Samples\VCx\Making Device Settings directory. In order to run the program, open the project file "MakingDeviceSettings.vcproj" in this directory and select "Build" in the toolbar. Then the program can be executed by selecting "Execute Program".

IC Imaging Control also offers a built-in dialog, which can be used to select and set up a device. If, however, the dialog provided by IC Imaging Control does not fit your needs, this chapter shows you how to create a custom dialog.

Setting up the Project

In order to use the custom device settings dialog, you will need a main application that calls the dialog. The sample program of this chapter contains a dialog based main application that calls the dialog. To set up such a project, follow the steps as described in the FirstSteps chapter, except that this sample is a "Dialog based" type of application instead of a "Single Document" type as described in the FirstSteps.

The main program contains a button labeled "Device". If this button is clicked, the device settings dialog is called with the following code:

CDeviceDlg dlg( &m_Grabber, this );

// Call the dialog
if( dlg.DoModal() == -1 )
{
    AfxMessageBox( TEXT("The dialog could not be created") );
    return;
}

CDeviceDlg is the class that contains the device settings dialog. m_Grabber is an instance of the grabber class of IC Imaging Control, which is used by the main application. It is passed to the dialog class at construction time, in order to allow the device settings dialog to change the settings. Finally, dlg.DoModal shows the actual dialog. This is all you need, to call the dialog.

Creating the Dialog

To create the dialog, choose "Insert" from the menu and then select "Resource...". Select "Dialog" and click the "New" button. Now choose "View" from the menu and select "ClassWizard...". The class wizard dialog opens, asking you to create a new class for the dialog. Click the "OK" button and name the class CDeviceDlg. Now add 5 combo boxes, 2 check boxes and a static text field to the form, in order to display the serial number.

Adding Functionality to the Dialog

First, we need a data structure that will store the state of the device. This is necessary since that state has to be restored, if the user clicks the "Cancel" button of the dialog. For this sample, the data structure is contained in the dialog class's header file ("DeviceDlg.h" in this sample) and looks as follows:

struct Settings
{
    bool bDeviceAvail;
    std::string szDevice;

    bool bVideoNormAvail;
    std::string szVideoNorm;

    std::string szVideoFormat;

    bool bFrameRateAvail;
    double lfFrameRate;

    bool bInputChannelAvail;
    std::string szInputChannel;

    bool bFlipVAvail;
    bool bFlipV;

    bool bFlipHAvail;
    bool bFlipH;
};

Add 2 private member variables to the dialog class:

Grabber*    m_pGrabber;
Settings    m_tDeviceState;

In order to initialize the dialog correctly, its standard constructor must be extended as follows:

CDeviceDlg::CDeviceDlg( Grabber* pGrabber, CWnd* pParent )
    :    CDialog(CDeviceDlg::IDD, pParent),
        m_pGrabber( pGrabber )
{
    //{{AFX_DATA_INIT(CDeviceDlg)
    //}}AFX_DATA_INIT
}

When the dialog is called, the device combo box has to be filled with appropriate values. Also, the state of the currently valid device has to be saved. This is done with the OnInitDialog function. To add the function, open the class wizard and choose CDeviceDlg as "Class name". As "Object ID", choose the class itself and as "Message", choose "WM_INITDIALOG". Now click on "Add Function" and add the following code to it:

BOOL CDeviceDlg::OnInitDialog()
{
    CDialog::OnInitDialog();

    if( m_pGrabber->isDevValid() )
    {
        if( m_pGrabber->isLive() )
        {
            // Display a message that the dialog cannot be displayed while the
            // grabber is in live mode.
            AfxMessageBox( TEXT("The device settings dialog is not available while the live video is running.\n\nStop the live video first.") );

            // call the click event of OK button of the super class
            CDialog::OnOK();

            return TRUE;

        }
    }

    // Store the state of the currently valid device.
    saveDeviceSettings();

    // Fill the device combo box with appropriate values.
    updateDevices();

    return TRUE;  // return TRUE unless you set the focus to a control
                  // EXCEPTION: OCX Property Pages should return FALSE
}

It is important to note that the OnInitDialog function also performs a check, whether the grabber is in live mode. If so, it displays a message that the dialog cannot be displayed while the grabber is in live mode. This behavior was implemented to point out that changing the device will cause side effects. The MemBufferCollection will become invalid when the device is changed. Therefore, image data in the MemBufferCollection is lost. Additionally, e.g. the frameReady event will not be called anymore, because of the invalid MemBufferCollection.

If the user clicks the "Cancel" button of the dialog, the state of the device has to be restored, in order to undo all changes. To do this add a click event for the "Cancel" button and insert the following code:

void CDeviceDlg::OnCancel()
{
    restoreDeviceSettings();

    CDialog::OnCancel();
}

The function restoreDeviceSettings restores the previously saved state of the device. The functions saveDeviceSettings and restoreDeviceSettings are implemented as follows:

void CDeviceDlg::saveDeviceSettings()
{
    if( m_pGrabber->isDevValid() )
    {
        m_tDeviceState.bDeviceAvail = true;
        m_tDeviceState.szDevice = m_pGrabber->getDev().c_str();

        if( m_pGrabber->isVideoNormAvailableWithCurDev() )
        {
            m_tDeviceState.bVideoNormAvail = true;
            m_tDeviceState.szVideoNorm = m_pGrabber->getVideoNorm().c_str();
        }
        else
        {
            m_tDeviceState.bVideoNormAvail = false;
        }

        m_tDeviceState.szVideoFormat = m_pGrabber->getVideoFormat().c_str();

        if( m_pGrabber->isFrameRateListAvailable() )
        {
            m_tDeviceState.bFrameRateAvail = true;
            m_tDeviceState.lfFrameRate = m_pGrabber->getFPS();
        }
        else
        {
            m_tDeviceState.bFrameRateAvail = false;
        }

        if( m_pGrabber->isInputChannelAvailableWithCurDev() )
        {
            m_tDeviceState.bInputChannelAvail = true;
            m_tDeviceState.szInputChannel = m_pGrabber->getInputChannel().c_str();
        }
        else
        {
            m_tDeviceState.bInputChannelAvail = false;
        }

        if( m_pGrabber->isFlipVAvailable() )
        {
            m_tDeviceState.bFlipVAvail = true;
            m_tDeviceState.bFlipV = m_pGrabber->getFlipV();
        }
        else
        {
            m_tDeviceState.bFlipVAvail = false;
        }

        if( m_pGrabber->isFlipHAvailable() )
        {
            m_tDeviceState.bFlipHAvail = true;
            m_tDeviceState.bFlipH = m_pGrabber->getFlipH();
        }
        else
        {
            m_tDeviceState.bFlipHAvail = false;
        }
    }
    else
    {
        m_tDeviceState.bDeviceAvail = false;
    }
}

void CDeviceDlg::restoreDeviceSettings()
{
    if( m_tDeviceState.bDeviceAvail )
    {
        m_pGrabber->openDev( m_tDeviceState.szDevice );

        if( m_tDeviceState.bVideoNormAvail )
        {
            m_pGrabber->setVideoNorm( m_tDeviceState.szVideoNorm );
        }

        m_pGrabber->setVideoFormat( m_tDeviceState.szVideoFormat );

        if( m_tDeviceState.bFrameRateAvail )
        {
            m_pGrabber->setFPS( m_tDeviceState.lfFrameRate );
        }

        if( m_tDeviceState.bInputChannelAvail )
        {
            m_pGrabber->setInputChannel( m_tDeviceState.szInputChannel );
        }

        if( m_tDeviceState.bFlipVAvail )
        {
            m_pGrabber->setFlipV( m_tDeviceState.bFlipV );
        }

        if( m_tDeviceState.bFlipHAvail )
        {
            m_pGrabber->setFlipH( m_tDeviceState.bFlipH );
        }
    }
    else
    {
        m_pGrabber->closeDev();
    }
}

To handle the controls of the dialog, use the class wizard to add a "CBN_SELCHANGE" event for every of the 5 combo boxes. Also add the "BN_CLICKED" events for both check boxes. To access the controls, finally add a member variable for every combo box, for the check boxes and for the static text field that should display the serial number of a device.

The code for the "CBN_SELCHANGE" event for the device combo box looks as follows:

void CDeviceDlg::OnSelchangeComboDevice()
{
    // Open the device
    if( m_cboDevice.IsWindowEnabled() )
    {
        CString device;

        m_cboDevice.GetWindowText( device );

        if( m_pGrabber->openDev( (LPCTSTR)device ) )
        {
            __int64 iSerial;
            CString serial;

            // Try to read out the serial number
            if( m_pGrabber->getDev().getSerialNumber( iSerial ) )
            {
                // Display serial
                serial.Format( TEXT("%I64X"), iSerial );
                m_staticSerialOut.SetWindowText( serial );
            }
            else
            {
                // Display "n\a"
                m_staticSerialOut.SetWindowText( NOT_AVAILABLE );
            }

            // Update the other controls, since they depend on the current device.
            updateVideoNorms();
            updateInputChannels();
            updateFlip();
        }
    }
}

The code above reads out the selected text of the combo box. Then the selected device is opened. After that, the serial number is read out and displayed. If the serial number of the device cannot be retrieved, or the device has no serial number, "n\a" is displayed (NOT_AVAILABLE is actually a define for "n\a"). Then, the other controls are updated with a call to the respective "update" function.

The code for the other "CBN_SELCHANGE" events is even easier. Take a look at the code for the input channel combo box:

void CDeviceDlg::OnSelchangeComboInputchannel()
{
    if( m_cboInputChannel.IsWindowEnabled() )
    {
        CString inputchannel;

        m_cboInputChannel.GetWindowText( inputchannel );

        if( !m_pGrabber->setInputChannel( (LPCTSTR)inputchannel ) )
        {
            AfxMessageBox( TEXT("Input Channel Error") );
        }
    }
}

The function just retrieves the selected text of the combo box and sets the input channel accordingly. The code for the other combo boxes is similar, except that the "CBN_SELCHANGE" event for the video norm calls "updateVideoFormats", because the video format depends on the video norm and the "CBN_SELCHANGE" event for the video format calls "updateFrameRates" for the same reason. Also the code for the frame rates must be modified because the setFPS method accepts variables of type double as a parameter, but m_cboFrameRate.GetWindowText returns a string.

Now the code for the check boxes:

void CDeviceDlg::OnCheckFlipv()
{
    if( m_pGrabber->isFlipVAvailable () )
    {
        m_pGrabber->setFlipV( m_chkFlipV.GetCheck() == 1 );
    }
}

The code for the horizontal flip is similar.

Now let us take a look at the update functions. There is an update function for every combo box. They are used to fill the respective combo box with appropriate values. Here is the code for the updateDevice function:

void CDeviceDlg::updateDevices()
{
    // Clear combo box
    m_cboDevice.ResetContent();

    // Retrieve the list of available video capture devices.
    Grabber::tVidCapDevListPtr pVidCapDevList = m_pGrabber->getAvailableVideoCaptureDevices();
    if( pVidCapDevList == 0 || pVidCapDevList->empty() )
    {
        m_cboDevice.AddString( NOT_AVAILABLE );
        m_cboDevice.EnableWindow( false );
        m_cboDevice.SetCurSel( 0 );
        return;
    }

    m_cboDevice.EnableWindow( true );

    // Fill the combo box
    for ( Grabber::tVidCapDevList::iterator it =
          pVidCapDevList->begin();
          it != pVidCapDevList->end();
          ++it )
    {
        m_cboDevice.AddString( CString( it->c_str() ) );
    }

    // Select the currently valid device
    if( m_pGrabber->isDevValid() )
    {
        m_cboDevice.SelectString( -1, CString( m_pGrabber->getDev().c_str() ) );
    }

    // Update the other controls since they depend on this one.
    updateVideoNorms();
    updateInputChannels();
    updateFlip();
}

The code for the other combo boxes is basically the same.

And finally the code for the updateFlip function:

void CDeviceDlg::updateFlip()
{
    // Check horizontal flip.
    if( m_pGrabber->isFlipHAvailable() )
    {
        m_chkFlipH.EnableWindow( true );
        if( m_pGrabber->getFlipH() )
        {
            m_chkFlipH.SetCheck( 1 );
        }
        else
        {
            m_chkFlipH.SetCheck( 0 );
        }
    }
    else
    {
        m_chkFlipH.EnableWindow( false );
        m_chkFlipH.SetCheck( 0 );
    }

    // Check vertical flip.
    if( m_pGrabber->isFlipVAvailable() )
    {
        m_chkFlipV.EnableWindow( true );
        if( m_pGrabber->getFlipV() )
        {
            m_chkFlipV.SetCheck( 1 );
        }
        else
        {
            m_chkFlipV.SetCheck( 0 );
        }
    }
    else
    {
        m_chkFlipV.EnableWindow( false );
        m_chkFlipV.SetCheck( 0 );
    }
}

<< Programmer's Guide


Writing Image Streams to an AVI file

This example demonstrates how to write a sequence of images to an AVI file.

The program can be found in the %TOPLEVEL%\Samples\VC71\SinkType directory. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6. In order to run the program, open the solution file SinkType.sln in this directory and select Build -> Build SinkType in the menu. Then, the program can be executed by selecting Debug -> Start.

The program generates a list of all available video compressors and asks the end user for the name of the compressor that he/she would like to use and a filename. As soon as the end user presses any key, the program starts capturing. It stops capturing when enter is pressed again, at which point, it writes the captured data to an AVI file.

Opening a Device

The example program uses the setupDeviceFromFile function from %TOPLEVEL%\Samples\VC71\Common\CmdHelper.h. This function displays the device selection dialog and saves the selected device in a configuration file, that is loaded when the function is called again.

Grabber grabber;
if( !setupDeviceFromFile( grabber ) )
{
    return -1;
}

Selecting a Codec

The static method Codec::getAvailableCodecs returns a list with the available video compressors. With the help of presentUserChoice and toStringArrayPtrListPtr from %TOPLEVEL%\Samples\VC71\Common\CmdHelper.h, this list is displayed on the console and the end user can select one of the available codecs.

tCodecListPtr pCodecs = Codec::getAvailableCodecs();

// Display all codec names on the screen.
int choice = presentUserChoice( toStringArrayPtrListPtr( pCodecs ) );
if( choice == -1 )
{
    return -1;
}

Controlling Video Recording

In order to save image data to a video file, a MediaStreamSink is created and initialized to record an AVI files. The selected codec and filename are set. The sink is initially paused by calling GrabberSinkType::setSinkMode with the parameter ePAUSE.

// Create an MediaStreamSink to record an AVI file with the selected CoDec
tMediaStreamSinkPtr pSink = MediaStreamSink::create(
    MediaStreamContainer::create( MSC_AviContainer ), pCodecs->at( choice ) );

// Set the filename.
pSink->setFilename( filename );

// The sink is initially paused, so that no video data is written to the file.
pSink->setSinkMode( GrabberSinkType::ePAUSE );

// Set pSink as the current sink.
grabber.setSinkType( pSink );

// Start the live mode. The live video will be displayed but no images will be written
// to the AVI file because pSink is in pause mode.
if( !grabber.startLive( true ) )
{
    std::cerr << grabber.getLastError().toString() << std::endl;
    return -1;
}

std::cout << "Press [enter] to start capturing!";
std::cin.get();

// Start the sink. The image stream is written to the AVI file.
pSink->setSinkMode(GrabberSinkType::eRUN );

std::cout << "Video recording started." << std::endl;
std::cout << "Press [enter] to stop capturing!";
std::cin.get();

// Pause the sink. This stops writing the image stream to the AVI file.
// A subsequent call to setSinkMode with GrabberSinkType::eRUN as the
// parameter would restart AVI recording.
pSink->setSinkMode(GrabberSinkType::ePAUSE );

std::cout << "Video recording stopped." << std::endl;

// Stop the live mode. This stops writing images to the AVI file if the mode is not
// GrabberSinkType::ePAUSE. The AVI file is closed.
grabber.stopLive();

After live mode has been started using Grabber::startLive, the program waits for user input. To actually start AVI recording, the sink is unpaused.

See also

Properties of a Codec

<< Programmer's Guide


Writing an Image Stream to a video file

This example demonstrates how to write a sequence of images to a video file.

The program can be found in the %TOPLEVEL%\Samples\VC71\CreateVideoFile directory. Similarly, you can find a VC6 version in the directory %TOPLEVEL%\Samples\VC6. In order to run the program, open the solution file CreateVideoFile.sln in this directory and select Build -> Build CreateVideoFile in the menu. You can execute the program by selecting Debug -> Start.

The program generates a list of all available media stream containers and prompts the end user to select one. In a second step, the end user may choose between 3 possible ways of storing the video data in the file:

  • Codec: If this option is selected, a list of all available video compressors is generated and the end user is asked to select one from the list.
  • Uncompressed: The end user may select an uncompressed format from a list.
  • Unspecified: If this option is selected, the current device, the frame filters and the overlays in the device path and the sink path determine the uncompressed video format.

In the next step, the program asks for a filename. Once the end user has entered a file name, the program waits until another key is pressed. Then, it starts capturing. It proceeds to capture, writing data into the video file, until enter is pressed.

Opening a Device

The example program uses the setupDeviceFromFile function from %TOPLEVEL%\Samples\VC71\Common\CmdHelper.h. This function displays the device selection dialog and saves the selected device in a configuration file. When the function is called again, this configuration file is reloaded.

Grabber grabber;
if( !setupDeviceFromFile( grabber ) )
{
    return 1;
}

Selecting the video data format

the end user may choose between 3 possible ways to store the video data in the file:

  • Codec: The static method Codec::getAvailableCodecs returns a list with the available video compressors. With the help of presentUserChoice and toStringArrayPtrListPtr from %TOPLEVEL%\Samples\VC71\Common\CmdHelper.h, this list is displayed on the console and the end user has to select one of the available codecs.
  • Uncompressed: With the help of presentUserChoice and toStringArrayPtrListPtr from %TOPLEVEL%\Samples\VC71\Common\CmdHelper.h, a list of uncompressed video formats s_UncompressedFormatList is displayed on the console, allowing the end user to select one of the available formats.
  • Unspecified: If this option is selected, the current device, frame filters and overlays in the device path and the sink path determine the uncompressed video format.

In order to save image data to a video file, a MediaStreamSink is created and initialized.

// Check whether codecs are supported by the container.
if( pCont->isCustomCodecSupported() )
{
    static const char* pCodecOrCompressorChoice[] =
    {
        "Codec",
        "Uncompressed Video",
        "Unspecified Type (uses the video format specified by either the device, frame filters or OverlayBitmap)"
    };

    int idx = presentUserChoice( pCodecOrCompressorChoice, pCodecOrCompressorChoice + 3 );
    if( idx == -1 )
    {
        std::cerr << "No choice was made between Codec or Uncompressed Video." << std::endl;
        return 1;
    }

    if( idx == 0 )
    {
        // Get a list of all available video compressors (codecs)
        tCodecListPtr pCodecList = Codec::getAvailableCodecs();
        if( pCodecList == 0 )
        {
            std::cerr << "No codecs found." << std::endl;
            return 1;
        }

        int Compressor_idx = presentUserChoice( toStringArrayPtrListPtr( pCodecList ) );
        if( Compressor_idx == -1 )
        {
            std::cerr << "No compressor chosen." << std::endl;
            return 1;
        }
        tCodecPtr pCodec = pCodecList->at( Compressor_idx );

        // If the codec provides a dialog, display it.
        if( pCodec->hasDialog() )
        {
            std::cout << "Setup the codec: " << std::endl;
            pCodec->callDialog();
        }
        // Create the sink with the specified codec.
        pSink = MediaStreamSink::create( pCont, pCodec );
    }
    else if( idx == 1 )
    {
        // Let the user select an uncompressed format.
        int UFL_idx = presentUserChoice( s_UncompressedFormatList, s_UncompressedFormatList + s_UncompressedFormatListCount );
        if( UFL_idx == -1 )
        {
            std::cerr << "No uncompressed video format chosen" << std::endl;
            return 1;
        }
        // Create the sink with the specified uncompressed format.
        GUID fmt_id = s_UncompressedFormatList[UFL_idx].id;

        pSink = MediaStreamSink::create( pCont, fmt_id );
    }
    else
    {
        // Create the sink with the format that is determined by the device, frame filters or overlay.
        pSink = MediaStreamSink::create( pCont );
    }
}
else
{
    // Create the sink with the format that is determined by the device, frame filters or overlay.
    pSink = MediaStreamSink::create( pCont );
}

/* The combinations of codec and container might not be created, so we have to check
 * this here.
 */
if( pSink == 0 )
{
    std::cerr << "The selected sink could not be built." << std::endl;
    return 1;
}

Controlling Video Recording

In order to save image data to a video file, a MediaStreamSink is created and initialized to record an AVI files. The selected codec and filename are set. The sink is initially paused by calling GrabberSinkType::setSinkMode with the parameter ePAUSE.

// The sink is initially paused, so that no video data is written to the file.
pSink->setSinkMode( GrabberSinkType::ePAUSE );

// apply the sink
grabber.setSinkType( pSink );

// Start the live mode. The live video will be displayed but no images will be written
// to the AVI file because pSink is in pause mode.
if( !grabber.startLive( true ) )
{
    std::cerr << grabber.getLastError().toString() << std::endl;
    return -1;
}

fflush(stdin);

std::cout << "Press [enter] to start capturing!";
std::cin.get();

// Start the sink. The image stream is written to the AVI file.
pSink->setSinkMode(GrabberSinkType::eRUN );

std::cout << "Video recording started." << std::endl;
std::cout << "Press [enter] to stop capturing!";
std::cin.get();

// Stop the live mode. This stops writing the avi file to disk.
grabber.stopLive();

After live mode has been started using Grabber::startLive, the program waits for end user input. To actually start AVI recording, the sink is put in run mode.

See also

Properties of a Codec

<< Programmer's Guide


Properties of a Codec

This example demonstrates how to get and set the properties of a codec.

The program can be found in the %TOPLEVEL%\Samples\VC71\CodecProperty directory. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6. In order to run the program, open the solution file CodecProperty.sln in this directory and select Build -> Build CodecProperty in the menu. Then the program can be executed by selecting Debug -> Start.

The program generates a list of all available video compressors and asks the user for the name of the compressor it should use and a filename. If the selected codec has a property dialog, this dialog will now be displayed. After the dialog has been closed, the program retrieves the properties set in the property dialog and saves them to the file "codec.xml". Then it loads the properties that had been previously saved from the file and puts them in the codec. It then waits for a key press to start the capturing of the image stream. It will then write the image stream into the AVI file until enter is pressed again.

Not every codec has a property dialog that allows parameters to be set externally. The following codecs have a property dialog:

  • Cinepak2
  • MJPEG
  • DV Video Encoder
  • Indeo video 5.10 compression filter
  • Lead MCMP/MJPEG Codec (VfW)
  • DivX412
  • DivX500

Saving Codec Settings

To save the data of a codec, use Codec::getSettings. This method returns an XML formatted string, containing the codec data. You can write this string to a file or the registry to save your program's codec settings:

std::string codec_settings = codec.getSettings();
if( !codec_settings.empty() )
{
    std::ofstream file( filename.c_str() );
    if( file.good() )
    {
        file << codec_settings;
        bSucceded = true;
    }
    else
    {
        std::cerr << "Error : Could not open file " << filename << std::endl;
    }
}
else
{
    std::cerr << "Error : No data available from the codec" << std::endl;
}

Loading Codec Settings

To restore codec settings, use Codec::setSettings:

std::ifstream file( filename.c_str() );
if( file.good() )
{
    std::string codec_settings;
    while( file.good() )    // read the file char by char
    {
        codec_settings += file.get();
    }
    if( !codec_settings.empty() )    // no data in the file check
    {
        if( codec.setSettings( codec_settings ) )    // set the data
        {
            bSucceded = true;
        }
        else
        {
            std::cerr << "Error : Data does not fit codec" << std::endl;
        }
    }
    else
    {
        std::cerr << "Error : No data found in the supplied file" << std::endl;
    }
}
else
{
    std::cerr << "Error : Could not open file " << filename << std::endl;
}

See also

Writing Image Streams to an AVI file

<< Programmer's Guide


Scroll and Zoom

This example demonstrates how to change the size and how to scroll the live video image.

The example is located in the %TOPLEVEL%\samples\vc71\scrollandzoom directory of the IC Imaging Control installation. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6. It is derived from the classlib Demoapp example and implements the new features of scroll and zoom.

Changing the size of the displayed live video image lets the image zoom in and out. This means that the video image is stretched bigger or smaller.

Scrolling means moving the live video image in a parent window.

Zoom

Zooming of the live video image, further named "video window", is achieved by changing the size of the live video image. The Grabber implements methods to retrieve and set the video window's size.

getWindowPosition( long&x0, long&y0, long&width, long&height ) retrieves the current position and size of the video window. The default position is at (0/0) in the parent window and the default size is set to the size of the current video format.

Changing the video window's size by calling the method setWindowSize(long width, long height) stretches the video images to the new size. This results in digital zooming.

In the sample, a combo box is placed in the toolbar. The combo box contains zoom values from 10% to 300%. These values are not limits but they are good enough for this example. The OnSelchangeZoom of CMainFrame is the handler of the combo box. The new zoom factor is set in this handler.

void CMainFrame::OnSelchangeZoom()
{
    float fZoomFactor = 1.0f;
    long lWidth;        // New width of the video window
    long lHeight;       // New Height of the video window

    if( m_Grabber.isDevValid() && m_Grabber.isLive()  )
    {
        fZoomFactor = m_cZoomCombo.GetCurSel() + 1;  // It is a zero based value,
                                                     // so 1 has to be added;
        fZoomFactor /= 10.0f;                        // calculate to percent.

        // Get the current video format size
        lWidth = m_Grabber.getAcqSizeMaxX();
        lHeight = m_Grabber.getAcqSizeMaxY();

        // Calculate the zoom factor
        lWidth  = (long)((float)lWidth  * fZoomFactor);
        lHeight = (long)((float)lHeight * fZoomFactor);

        // Turn off the default window position, so the grabber can change
        // the video window size.
        m_Grabber.setDefaultWindowPosition(false);

        // Set the new window size
        m_Grabber.setWindowSize(lWidth, lHeight);
    }
}

(This code can be found in the file samples/vc71/scrollandzoom/mainframe.cpp.)

Important: Before setting the video window size, the method setDefaultWindowPosition() must be called once with the parameter false. If this is not performed, the video window size always is set to the default values. Then, resizing the video window is not possible.

Adding Scrolling Capabilities

The window that contains the video window has to implement the scrollbars and has to handle the WM_HSCROLL and WM_VCSROLL messages.

Implementing the Scrollbars

The example has a child window of the class "CChildView". The class "CChildView" is derived from MFC's "CWnd".

The method CChildView::SetupScrollBars sets the current position and size of the video window and initializes the scrollbars. This method has to be called, if the size of the video window changes (i.e. on a zoom or on video format change). To hide a scrollbar, the nPage member of the SCROLLINFO structure must be greater than the nMax member. If they are equal, the scrollbar will be displayed automatically. If the video window's size is equal to the parent window's size, an if statement must be used. This causes the scrollbars not to be displayed.

Setting up the scrollbars is a little tricky. Take a look at the following to see how it is done:

void CChildView::SetupScrollBars()
{
    long posx;
    long posy;
    long width;
    long height;
    RECT clientRect;    // Rectangle of the client window
    long clientEdge;    // Will contain the length of the edges
    SCROLLINFO si;        // Structure to setup the scroll bars

    ZeroMemory(&si, sizeof(SCROLLINFO) );
    si.cbSize = sizeof(si);

    if( m_pGrabber->isDevValid())
    {
        // Get the size of the client rect, that is our window.
        GetClientRect( &clientRect );

        // Retrieve the actual size and position of the Grabber's video window.
        if( m_pGrabber->getWindowPosition( posx, posy, width, height ) == true )
        {
            // Make sure that the whole client area is used.
            clientEdge = clientRect.right - clientRect.left;
            if( clientEdge > width + posx && posx < 0)
            {
                posx -= posx + width - clientEdge;
                if( posx > 0) posx = 0;
            }

            clientEdge = clientRect.bottom - clientRect.top;
            if( clientEdge > height + posy && posy < 0)
            {
                posy -= posy + height - clientEdge;
                if( posy > 0) posy = 0;
            }

            m_pGrabber->setWindowPosition(posx ,posy);

            si.fMask = SIF_PAGE|SIF_RANGE|SIF_POS;
            si.nMin  = 0;
            if( height > clientRect.bottom) // Hide the scroll bar, if the sizes are equal.
            {
                // The page size for the scroll bar is the width or height of the client window.
                si.nPage =  clientRect.bottom ;

                // The maximum scroll value is the width or height of the video window. If
                // the maximum is less than the page size, the scroll bar is hidden.
                si.nMax = height;

                // The current scroll position is the negative value of the video window's
                // position.
                si.nPos = -posy;
            }
            else
            {
                si.nMax     = 2;
                si.nPage = si.nMax +1; // This hides the scroll bar.
            }

            // Setup the vertical scroll bar.
            SetScrollInfo( SB_VERT,&si);

            if( width > clientRect.right) // Hide the scroll bar, if the sizes are equal.
            {
                // Do the same for the horizontal scrollbar.
                si.nPage = clientRect.right;
                si.nMax =  width;
                si.nPos = -posx;
            }
            else
            {
                si.nMax     = 2;
                si.nPage = si.nMax +1; // This hides the scrollbar.
            }
            SetScrollInfo( SB_HORZ,&si);
            PaintImage();
        }
    }
}

The method SetupScrollBars has to be called, whenever the size of the video window changes. This is the case when the zoom factor changes, a WM_SIZE event occurs, setDefaultWindowSize(true) or liveStart() is called.

Scrollbars produce the WM_HSCROLL and the WM_VSCROLL messages. They are handled in the methods OnHScroll and OnVScroll:

///////////////////////////////////////////////////////////////////////////////
/*! The OnVScroll message handler is called, if the user modifies the vertical scroll bar.
*/
void CChildView::OnVScroll(UINT nSBCode, UINT nPos, CScrollBar* pScrollBar)
{
    OnScroll(nSBCode, nPos, SB_VERT);
}

///////////////////////////////////////////////////////////////////////////////
/*! The same has to be done for the horizontal scrollbar.
*/
void CChildView::OnHScroll(UINT nSBCode, UINT nPos, CScrollBar* pScrollBar)
{
    OnScroll(nSBCode, nPos, SB_HORZ);
}

The message handlers for WM_HSCROLL and WM_VSCROLL both call the method OnScroll because the handling is the same for both events. The scrollbar that has initiated the event is passed as a parameter to OnScroll.

First of all, the current size and position of the video window is retrieved in OnScroll. These values are used later for setWindowPosition. Then a case statement checks what kind of action has to be performed on the scrollbar and calculates the new scrollbar value. The flag bSIsScroll indicates whether a new scroll position was calculated or not. If this flag was set to true, the scrolling is done by passing the previously retrieved window parameters and the new scroll position to setWindowPosition. This moves the video window in the client window of the application.

//////////////////////////////////////////////////////////////////////////
/*! OnScroll handles the HScroll and VScroll events.
*/
void CChildView::OnScroll(UINT nSBCode, UINT nPos, int iScrollBar)
{
    long posx;
    long posy;
    long width;
    long height;
    bool bIsScroll = false;
    SCROLLINFO si;    // Structure to setup the scroll bars.
    ZeroMemory(&si, sizeof(SCROLLINFO) );

    // Get the current size and position of the video window.
    m_pGrabber->getWindowPosition( posx, posy, width, height);

    si.cbSize = sizeof(si);
    si.fMask = SIF_POS;
    GetScrollInfo( iScrollBar, &si);

    switch( nSBCode )
    {
        case SB_LINERIGHT :    si.nPos++;
                            bIsScroll = true;
                            break;

        case SB_LINELEFT :  si.nPos--;
                            bIsScroll = true;
                            break;

        case SB_PAGERIGHT : si.nPos+=5;
                            bIsScroll = true;
                            break;

        case SB_PAGELEFT :  si.nPos-=5;
                            bIsScroll = true;
                            break;

        case SB_THUMBTRACK:
        case SB_THUMBPOSITION:    si.nPos   = nPos;
                                bIsScroll = true;
                                break;
    }

    // Check whether a scroll event has been sent.
    if( bIsScroll == true )
    {
        // Scroll vertically or horizontally by passing the scroll bar position
        // as parameter to setWindowPosition.
        // The scroll position of the scroll bar has to be passed as a negative
        // value to setWindowPosition.
        if( iScrollBar == SB_HORZ )
        {
            m_pGrabber->setWindowPosition(-si.nPos, posy );
        }
        else
        {
            m_pGrabber->setWindowPosition(posx ,-si.nPos);
        }

        // Very important: The new scroll position must be passed to the scroll bar.
        // If not, the scroll bar would not show the new position.
        si.fMask  = SIF_POS;
        SetScrollInfo( iScrollBar, &si, TRUE);
        OnPaint();

    }
}

Some hints to scrollbars:

1. The newly calculated scroll position must be passed to the related scrollbar. If this is not done, the new value is not accepted by the scrollbar and scrolling is not possible.

2. After a WM_HSCROLL or WM_VSCROLL message is sent, a second one is initiated by the system. The second message should not processed for scrolling because it passes an invalid nPos value (it is 0) to the message handler.

Extending the Zoom Function

Now that we have implemented scrolling, we have to extend CMainFrame::OnSelchangeZoom() because the current implementation resets the video window's position to (0/0) every time the zoom factor is changed.

We call getWindowPosition to retrieve the current position of the window and calculate the window position according to the new zoom factor. The position that is thus calculated can be set with setWindowPosition after the call to setDefaultWindowPosition(false), which reset the window position to (0/0).

void CMainFrame::OnSelchangeZoom()
{
    float fZoomFactor = 1.0f;
    float fOldZoomFactor = 1.0f;
    long lXpos;
    long lYpos;
    long lWidth;        // New width of the video window.
    long lHeight;        // New heigth of the video window.

    if( m_Grabber.isDevValid()  )
    {
        fZoomFactor = m_cZoomCombo.GetCurSel() + 1.0f; // It is a zero based value, so 1 has to be added.
        fZoomFactor /= 10.0f;                        // Convert to percent.

        // Retrieve the current window position.
        m_Grabber.getWindowPosition(lXpos,lYpos,lWidth, lHeight);

        // Calculate the old zoom factor to recalculate the window position
        // at zoom factor 1.0.
        fOldZoomFactor = (float)lWidth / (float)m_Grabber.getAcqSizeMaxX();

        lXpos = (long)((float)lXpos / fOldZoomFactor);
        lYpos = (long)((float)lYpos / fOldZoomFactor);

        lXpos = (long)((float)lXpos * fZoomFactor);
        lYpos = (long)((float)lYpos * fZoomFactor);

        // Get the current video format size.
        lWidth = m_Grabber.getAcqSizeMaxX();
        lHeight = m_Grabber.getAcqSizeMaxY();

        // Calculate the new width and height according to the zoom factor.
        lWidth  = (long)((float)lWidth  * fZoomFactor);
        lHeight = (long)((float)lHeight * fZoomFactor);

        // Turn off the default window position, so the grabber can change
        // the video window size.
        m_Grabber.setDefaultWindowPosition(false);

        // Set the new window position and size.
        m_Grabber.setWindowPosition(lXpos,lYpos);
        m_Grabber.setWindowSize( lWidth, lHeight);
        m_wndView.SetupScrollBars();
    }
}

void CMainFrame::OnSelchangeZoom()
{
    float fZoomFactor = 1.0f;
    float fOldZoomFactor = 1.0f;
    long lXpos;
    long lYpos;
    long lWidth;        // New width of the video window.
    long lHeight;       // New height of the video window.

    if( m_Grabber.isDevValid() )
    {
        fZoomFactor = m_cZoomCombo.GetCurSel() + 1; // It is a zero based value, so 1 has to be added.
        fZoomFactor /= 10.0f;                        // Convert to percent.

        // Retrieve the current window position.
        m_Grabber.getWindowPosition(lXpos,lYpos,lWidth, lHeight);

        // Calculate the old zoom factor to recalculate the window position
        // at zoom factor 1.0.
        fOldZoomFactor = (float)lWidth / (float)m_Grabber.getAcqSizeMaxX();

        lXpos = (long)((float)lXpos / fOldZoomFactor);
        lYpos = (long)((float)lYpos / fOldZoomFactor);

        lXpos = (long)((float)lXpos * fZoomFactor);
        lYpos = (long)((float)lYpos * fZoomFactor);

        // Get the current video format size.
        lWidth = m_Grabber.getAcqSizeMaxX();
        lHeight = m_Grabber.getAcqSizeMaxY();

        // Calculate the new width and height according to the zoom factor.
        lWidth  = (long)((float)lWidth  * fZoomFactor);
        lHeight = (long)((float)lHeight * fZoomFactor);

        // Turn off the default window position, so the grabber can change
        // the video window size.
        m_Grabber.setDefaultWindowPosition(false);

        // Set the new window position and size.
        m_Grabber.setWindowPosition(lXpos,lYpos);
        m_Grabber.setWindowSize( lWidth, lHeight);
        m_wndView.SetupScrollBars();
    }
}

Affected Methods

Zooming, resizing and scrolling related methods are:

Grabber::setDefaultWindowPosition Grabber::getDefaultWindowPosition Grabber::getWindowPosition Grabber::setWindowPosition

<< Programmer's Guide


Creating an Overlay

This example demonstrates how to draw graphic elements, such as lines and text on the live video image.

It shows, how to:

  • draw simple text
  • display the current time using a timer event
  • use the callback to display a frame counter
  • enable the overlay for live display or sink

The example is located in the %TOPLEVEL%\samples\vc71\Creating an Overlay directory of the IC Imaging Control installation. You can find a VC6 version in the directory %TOPLEVEL%\Samples\VC6. You can find a VC8 version in the directory %TOPLEVEL%\Samples\VC8. It is derived from the classlib Demoapp example and implements the new overlay features.

Using the OverlayBitmap Objects

IC Imaging Control provides a special object for drawing and writing on the live video. The object is named OverlayBitmap. The OverlayBitmap object contains a bitmap, that has the same size as the video format, or the size of a frame filter that transforms the image data before the overlay bitmap is applied. An application can draw text and graphics on this overlay bitmap. The overlay bitmap is copied to each sample of the video. A dropout color can be specified to determine, which pixels of the overlay bitmap are transparent and therefore not copied to the live video.

The overlay bitmap can only be used, if Grabber::startLive or Grabber::prepareLive has been called at least once after the video format has been changed. It is only visible, if the live video is running.

Enabling and disable overlay for device, sink and display paths

Since version 3.0, IC Imaging Control allows you to select whether the overlay is drawn on live video, on grabbed and recorded images, or both.

You can use Grabber::setOverlayBitmapPathPosition to set an ORed combination of tPathPosition values specifying the path positions at which OverlayBitmap objects will be inserted.

Accessing the OverlayBitmap Objects

To access one of the 3 OverlayBitmap objects, call Grabber::getOverlay. The parameter of that method selects the position of the OverlayBitmap that is accessed.

Specifying the color mode of an OverlayBitmap

By default, the color format of the overlay bitmap is selected automatically according to the color format of the input image data. However, you might want to draw colored lines and text on a grayscale live video. The OverlayBitmap::setColorMode method allows you to force the overlay bitmap to use color or grayscale mode.

Draw a Simple Text

At first, we are going to display a simple text in the upper left corner of the video display. The text is visible in the captured image, as well as in a recorded AVI file.

The video capture device, video format and sink type must have been setup before an application can use the overlay for drawing. The following code is called from the void CMainFrame::OnPreviewStart() method.

void CMainFrame::drawOverlay( DShowLib::tPathPosition pos )
{
    smart_ptr<OverlayBitmap> ob = m_Grabber.getOverlay(pos);

    ob->setEnable(true);
    ob->setFont("Courier",14);
    ob->drawText( RGB(255,0,0),  0, 0, "IC Imaging Control 3.2" );

    switch( pos )
    {
    case ePP_DEVICE:
        ob->drawText( RGB(0,255,0),  20, 20,  "Device Overlay Active" );
        return;
    case ePP_SINK:
        ob->drawText( RGB(0,255,0),  20, 40,  "Sink Overlay Active" );
        return;
    case ePP_DISPLAY:
        ob->drawText( RGB(0,255,0),  20, 60,  "Display Overlay Active" );
        return;
    }
}

At first, a pointer to an OverlayBitmap object is retrieved by calling Grabber::getOverlay with the desired path position as a parameter.

The line ob->setEnable(true); enables the overlay. If the overlay is not enabled, it is not rendered on the video stream.

After that, a font name and size is selected to format the text that is displayed.

The line ob->drawText( RGB(255,0,0), 0, 0, "IC Imaging Control 3.0" ); sets the text color, the coordinates (0,0) and the text itself that are displayed in the live video stream. The text "IC Imaging Control 3.0" is drawn in red in the upper left corner of the live video stream. The drawText method has to be called only once. The text remains on the overlay until it is deleted or overwritten.

Depending on the overlay bitmap's path position, further text is printed to indicate which overlay bitmaps are visible on the live display and in the images that are sent to the sink.

Display a Clock

In the next step, we are going to display the current time in the lower right hand corner of the live video stream. The clock should be surrounded by a white rectangle. A timer with 1000 milliseconds delay is used for the clock. The timer events are handled in the corresponding method CMainFrame::OnTimer( UINT nIDEvent ). In this method, the method CMainFrame::displayTime is called that draws the current time by overwriting the old time.

void CMainFrame::displayTime()
{
    CString szTimeString;    // The string will contain the time.
    CTime cTime = CTime::GetCurrentTime();
    SIZE  StringSize;        // Size of the rectangle that is needed by the string.
    smart_ptr<DShowLib::OverlayBitmap> ob;
    RECT TimeRect;
    // Displaying the time is only useful, if the live video is running.
    if ( m_Grabber.isLive() )
    {
        ob = m_Grabber.getOverlay();

        // Call beginPaint to tell the OverlayBitmap class that we start drawing and
        // will use a DC (device context) for GDI operations.
        ob->beginPaint();

        // Set a font that uses a non proportional charset.
        ob->setFont("Courier",14);

        // Copy the current time to the time string.
        szTimeString = cTime.Format("%H:%M:%S");

        // Get the size in pixels that is used by the time string in the overlay bitmap.
        GetTextExtentPoint32( m_Grabber.getOverlay()->getDC(),szTimeString,
                                szTimeString.GetLength(), &StringSize);

        // This rectangle is used to draw a rectangle around the time.
        TimeRect.left = m_Grabber.getAcqSizeMaxX()-StringSize.cx-2;
        TimeRect.top = m_Grabber.getAcqSizeMaxY()-StringSize.cy-2;
        TimeRect.right = TimeRect.left + StringSize.cx+1 ;
        TimeRect.bottom = TimeRect.top + StringSize.cy+1 ;

        // Write the time string in the lower right corner.
        ob->drawText(RGB(255,255,255),
                      TimeRect.left + 1,
                     TimeRect.top + 1,
                     (LPCTSTR)szTimeString);

        // Draw a rectangle around the time string.
        ob->drawLine( RGB(255,255,255),  TimeRect.left,  TimeRect.top, TimeRect.right,  TimeRect.top);
        ob->drawLine( RGB(255,255,255), TimeRect.right,  TimeRect.top, TimeRect.right,  TimeRect.bottom);
        ob->drawLine( RGB(255,255,255), TimeRect.right,  TimeRect.bottom, TimeRect.left,  TimeRect.bottom);
        ob->drawLine( RGB(255,255,255),  TimeRect.left,  TimeRect.top, TimeRect.left,  TimeRect.bottom);

        // Call endPaint to release the DC and tell the OverlayBitmap class
        // that drawing has been finished.
        ob->endPaint();

    }
}

Displaying the time on the live video only makes sense, if the live video is running. Therefore, an if( m_Grabber.isLive() ) statement is used. The font "Courier" is used to display the time. "Courier" is a non-proportional font, therefore all characters of this font have the same size. Using a non-proportional font avoids garbage pixels, if the displayed time string is shorter than the previously displayed time. The time is retrieved in a MFC CTime object and formated into a CString szTimeString object. The GetTextExtentPoint32 function computes the width and height of the time string. To display the time string in the lower right corner, the previously calculated width and height of the time string is subtracted from the live video image's width and height.

The method OverlayBitmap::beginPaint must be called, because the application needs the device context (DC) of the OverlayBitmap. If OverlayBitmap::beginPaint has not been called, the method OverlayBitmap::getDC returns 0.

A OverlayBitmap::beginPaint at the beginning of GDI graphic operations must be followed by an OverlayBitmap::endPaint at the end of all GDI graphic operations.

OverlayBitmap::beginPaint and OverlayBitmap::endPaint are not needed, if an application does not need the device context (DC) of the OverlayBitmap object and uses only the built-in graphic operations such as drawText, drawLine etc.

Note: If this code is copied to another application, please make sure, that the overlay has been enabled. If the overlay has not been enabled, the time is not displayed.

Using the Overlay Callback Function

The OverlayBitmap object provides a callback for every frame of the image stream. With this callback, an application can draw frame specific data on the overlay, i.e. a frame counter. The following code example illustrates how to implement a simple frame counter that is displayed in the image stream.

At first, a handler for the callback has to be implemented. This is done by creating a new class that implements a callback method for the overlay update event. This new class is derived from the class GrabberListener that is the base class for all classes implementing a callback. The new class is called "COverlayCallback". It is a member of the class CMainFrame. The instance of COverlayCallback must be registered as a new "listener" to the Grabber. This is done in the constructor of CMainframe, after the Grabber has been instantiated.

m_Grabber.addListener(&m_cOverlayCallback, DShowLib::GrabberListener::eOVERLAYCALLBACK);

The parameter DShowLib::GrabberListener::eOVERLAYCALLBACK causes the Grabber to call the overlayCallback method only.

The declaration of the COverlayCallback class is as follows:

class COverlayCallback : public GrabberListener
{
public:
    COverlayCallback();
    virtual ~COverlayCallback();
    virtual void overlayCallback( Grabber& param, smart_ptr<OverlayBitmap> pBitmap, const tsMediaSampleDesc& );

private:
    int    m_displayCallCount;
};

The Grabber calls the GrabberListener::overlayCallback method of the COverlayCallback object before the overlay is rendered onto a frame. Drawing operations can be performed in this method. The callback method is implemented in the following way:

void COverlayCallback::overlayCallback( Grabber& param, smart_ptr<OverlayBitmap> pBitmap, const tsMediaSampleDesc &MediaSample )
{
    CString szText;

    switch( pBitmap->getPathPosition() )
    {
    case ePP_DEVICE:
        szText.Format( TEXT("Device: Frame %d   "), MediaSample.FrameNumber );
        pBitmap->drawText(RGB(255,255,0), 20, 100, (LPCTSTR)szText );
        break;
    case ePP_SINK:
        szText.Format( TEXT("Sink: Frame %d   "), MediaSample.FrameNumber );
        pBitmap->drawText(RGB(255,255,0), 20, 120, (LPCTSTR)szText );
        break;
    case ePP_DISPLAY:
        szText.Format( TEXT("Display: No Frame Number Available, called %d times"), m_displayCallCount++ );
        pBitmap->drawText(RGB(255,255,0), 20, 140, (LPCTSTR)szText );
        break;
    }
}

To find out the path position of the overlay bitmap for that the callback is executed, call OverlayBitmap::getPathPosition.

In this example, a text displaying the current frame number is displayed. Because the overlay bitmap in the display path does not have access to frame numbers, a member variable m_displayCallCount is used to keep track of the call count.

Additional Information about Dropout Color

The OverlayBitmap class uses a dropout color to determine, which pixel color is transparent on the video stream. Each pixel that has the dropout color is not copied on to the live video. The dropout color can be set by calling OverlayBitmap::setDropOutColor and retrieved by calling OverlayBitmap::getDropOutColor. When the overlay bitmap is created, the color of all pixels is set to the default dropout color. The default dropout color is black (RGB(0,0,0)).

An application can change the dropout color with the following line of code:

// Set dropout color to magenta.
m_Grabber.getOverlay()->setDropOutColor( RGB(255,0,255) );

Now, the live video image is completely black, because the dropout color has been changed to magenta. (Not the color of the pixels in the overlay bitmap.) All black pixels are now copied to the live video (only magenta pixels are not copied). To fill the entire overlay bitmap with magenta, use the following line of code:

// Fill the overlay bitmap with magenta (current dropout color)
m_Grabber.getOverlay()->fill( RGB(255,0,255) );

To delete a line of text that has been written on the overlay bitmap use the following lines of code:

// Draw the text with a visible color
m_Grabber.getOverlay()->drawText(RGB(255,0,0),
                                 0, 0, "Hello World" );
// To hide the text, draw it with the current dropout color again
m_Grabber.getOverlay()->drawText(m_Grabber.getOverlay()->getDropOutColor(),
                                 0, 0, "Hello World" );

This simply draws the same text on the same coordinates with the current dropout color. Now, the text is invisible.

<< Programmer's Guide


Accessing an Image Buffer

This example shows the how to handle image buffers.

The program can be found in the %TOPLEVEL%\Samples\VC71\Pixelformat directory. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6. In order to run the program, open the solution file Pixelformat.sln in this directory and select Build -> Build Pixelformat in the menu. You can then execute the program by clicking Debug -> Start.

Available Data Formats

Y800

The Y800 color format is an 8 bit monochrome format. Every pixel is represented by one byte. The organization of the pixels in the image buffer is from left to right and top down. In other words: The first byte of the image buffer corresponds to the first pixel of the first line of the image.

RGB8

The RGB8 color format is an 8 bit monochrome format. Every pixel is represented by one byte. The organization of the pixels in the image buffer is from left to right and bottom up. In other words: The first byte of the image buffer corresponds to the first pixel of the last line of the image.

RGB24

RGB24 is a 24 bit color format. Every pixel is represented by 3 bytes, while every byte of this triple corresponds to one color value. The letters 'RGB' mean Red, Green and Blue, so one byte represents the red value, one byte represents the green value and the last byte represents the blue value.

RGB32

RGB32 is a 32 bit color format. It is like RGB24, except that every pixel has an additional byte to store an alpha value. An alpha value describes the transparency of the pixel. Therefore, every pixel consists of 4 bytes. RGB32 is also referred to as RGBA, where the A stands for Alpha. The A value is not used in IC Imaging Control and is therefore always 0. As for the RGB24 pixel format, IC Imaging Control uses the BGRA byte order for the RGB32 pixel format. The organization of the pixels in the image buffer is from left to right and bottom up.

RGB555

RGB555 is a 16 bit color format. Every pixel is represented by two bytes. The characters 555 stand for the number of bits used for every color value. In this case, 5 bits are used for every color value, so only 15 bits are needed. The last bit (most significant bit) is unused. The organization of the pixels in the image buffer is from left to right and bottom up.

RGB565

The RGB565 color format is the same as the RGB555 color format, except that 6 bits are used for the green value instead of 5. Therefore, all 16 bits are in use. The organization of the pixels in the image buffer is from left to right and bottom up.

UYVY

The UYVY color format is basically a 16 bit color format. In contrast to the RGB formats, it contains no values for red, green or blue. It uses values for luminance and chrominance instead. Y stands for the luminance. U (or Cb) and V (or Cr) describe the chrominance. For further details refer to the following link:

YGB0

YGB0 is a 10 bit grayscale format. Every pixel is stored in two bytes. Only 10 of the 16 bits of these two bytes contain relevant image data, the other bits are unused. The organization of the pixels in the image buffer is from left to right and top down.

YGB1

YGB1 is a 10 bit grayscale format. Every pixel is stored in two bytes. Only 10 of the 16 bits of these two bytes contain relevant image data, the other bits are unused. The organization of the pixels in the image buffer is from left to right and top down.

<< Programmer's Guide


Y800

The Y800 color format is an 8 bit monochrome format. Every pixel is represented by one byte. The organization of the pixels in the image buffer is from left to right and top down. In other words: The first byte of the image buffer corresponds to the first pixel of the first line of the image.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a MemBufferCollection, which defines the image data color format must first have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of Y800.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, we start live mode and call Grabber::snapImages.

Accessing the buffer

The following code retrieves a byte pointer to the image data:

// get pointer to the image data
BYTE* pbImgData = pActiveBuf->getPtr();

In this example, we want to output the first (upper left) two pixels of the image. In a second step we are going to manipulate the first 3 pixels. Because Y800 images are stored top-down, the index of the upper left pixel is 0:

// Calculate the index of the upper left pixel
// Images are stored top-down in the image buffer, so the first pixel has index 0.
int iOffsUpperLeft = 0;

Now that we have the offset to the the first pixel, we can read it out:

printf( "\nImage buffer pixel format is eY800\n" );
printf( "Pixel 1: %d\n", pbImgData[iOffsUpperLeft  ] );
printf( "Pixel 2: %d\n", pbImgData[iOffsUpperLeft+1] );

Manipulating Image Data

Instead of only reading pixel data, it is, of course, possible to manipulate the data as well. The following code will set the upper left hand pixel to black and the next 2 pixels to gray and white. After this manipulation, the image is saved as a BMP file.

// overwrite the first 3 pixels and save image to disk
pbImgData[iOffsUpperLeft  ] = 0;    // Set the first pixel to BLACK
pbImgData[iOffsUpperLeft+1] = 128;    // Set the second pixel to GRAY
pbImgData[iOffsUpperLeft+2] = 255;    // Set the third pixel to WHITE

pActiveBuf->save( "Y800.bmp" );

To check the result, open the saved image and take a look at the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


RGB8

The RGB8 color format is an 8 bit monochrome format. Every pixel is represented by one byte. The organization of the pixels in the image buffer is from left to right and bottom up. In other words: The first byte of the image buffer corresponds to the first pixel of the last line of the image.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a MemBufferCollection, which defines the image data color format must first have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of RGB8.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, live mode is started and Grabber::snapImages is called.

Accessing the buffer

The following code retrieves a byte pointer to the image data:

// get pointer to the image data
BYTE* pbImgData = pActiveBuf->getPtr();

In this example, we want to output the first (upper left hand) two pixels of the image. In a second step we manipulate the first 3 pixels. As mentioned before, the image data is stored bottom up. Therefore, pbImgData points to the first pixel of the last line of the image. To get access to the first pixel of the first line of the image, the following calculation has to be performed:

// Calculate the index of the upper left pixel
// Images are stored upside down in the image buffer
SIZE dim = pActiveBuf->getFrameType().dim;
int iOffsUpperLeft = (dim.cy-1) * dim.cx;

At first, we retrieve the width and height of the image in terms of pixels. Then the offset to the upper left hand pixel is calculated. Since every pixel is exactly 1 byte in size, we can calculate the offset as:

(Height-1) * Width

Now that we have the offset to the the first pixel, we can read it out:

printf( "\nImage buffer pixel format is eRGB8\n" );
printf( "Pixel 1: %d\n", pbImgData[iOffsUpperLeft  ] );
printf( "Pixel 2: %d\n", pbImgData[iOffsUpperLeft+1] );

Manipulating Image Data

Instead of only reading pixel data, it is, of course, possible to manipulate the data as well. The following code will set the upper left hand pixel to black and the next 2 pixels to gray and white. After this manipulation, the image is saved as a BMP file.

// overwrite the first 3 pixels and save image to disk
pbImgData[iOffsUpperLeft  ] = 0;    // Set the first pixel to BLACK
pbImgData[iOffsUpperLeft+1] = 128;    // Set the second pixel to GRAY
pbImgData[iOffsUpperLeft+2] = 255;    // Set the third pixel to WHITE

pActiveBuf->save( "RGB8.bmp" );

To check the result, open the saved image and take a look at the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


RGB24

RGB24 is a 24 bit color format. Every pixel is represented by 3 bytes, while every byte of this triple corresponds to one color value. The letters 'RGB' mean Red, Green and Blue, so one byte represents the red value, one byte represents the green value and the last byte represents the blue value.

Please note that the name RGB can be misleading since the first byte of a pixel does not necessarily have to represent the red value. In the Windows© environment, RGB data is typically organized in the order BGR. This means that the first byte represents the blue value, the second byte represents the green value and the third byte represents the red value of a RGB24 pixel. IC Imaging Control uses BGR order for the RGB24 pixel format. The organization of the pixels in the image buffer is from left to right and bottom up.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a MemBufferCollection, which defines the image data color format must have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of RGB24.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, we start live mode and call Grabber::snapImages.

Accessing the buffer

The following code retrieves a byte pointer to the image data. We use a structure, RGB24Pixel to access the pixel's components, and reduce coordinate calculation to the level of RGB8:

struct RGB24Pixel {
    BYTE b;
    BYTE g;
    BYTE r;
};
RGB24Pixel* pbImgData = (RGB24Pixel*) pActiveBuf->getPtr();

In this example, we want to output the first (upper left hand) two pixels of the image. In a second step, we are going to manipulate the first 3 pixels. As mentioned before, the image data is stored bottom up. Therefore, pbImgData points to the first pixel of the last line of the image. To get access to the first pixel of the first line of the image, the following calculation has to be performed:

// Calculate the index of the upper left pixel
// Images are stored upside down in the image buffer
SIZE dim = pActiveBuf->getFrameType().dim;
int iOffsUpperLeft = (dim.cy-1) * dim.cx;

At first, we retrieve the width and height of the image in terms of pixels. Then, the offset to the upper left pixel is calculated. Since every pixel is exactly 1 byte in size, we can calculate the offset as:

(Height-1) * Width

Now that we have the offset to the the first pixel, we can read it out:

printf( "\nImage buffer pixel format is eRGB24\n" );
// Please note: RGB values are stored in the following order: B,G,R
printf( "Pixel 1(RGB): %d %d %d\n", pbImgData[iOffsUpperLeft].r,    //RED
                                    pbImgData[iOffsUpperLeft].g,    //GREEN
                                    pbImgData[iOffsUpperLeft].b );    //BLUE
printf( "Pixel 2(RGB): %d %d %d\n", pbImgData[iOffsUpperLeft+1].r,    //RED
                                    pbImgData[iOffsUpperLeft+1].g,    //GREEN
                                    pbImgData[iOffsUpperLeft+1].b );    //BLUE

Manipulating Image Data

Instead of only reading pixel data, it is, of course, possible to manipulate the data as well. The following code will set the upper left hand pixel to red and the next 2 pixels to green and blue. After this manipulation, the image is saved to a .bmp file.

// overwrite the first 3 pixels and save image to disk
// Set the first pixel to RED
pbImgData[iOffsUpperLeft].b = 0;    // BLUE
pbImgData[iOffsUpperLeft].g = 0;    // GREEN
pbImgData[iOffsUpperLeft].r = 255;    // RED

// Set the second pixel to GREEN
pbImgData[iOffsUpperLeft+1].b = 0;    // BLUE
pbImgData[iOffsUpperLeft+1].g= 255;    // GREEN
pbImgData[iOffsUpperLeft+1].r = 0;    // RED

// Set the third pixel to BLUE
pbImgData[iOffsUpperLeft+2].b = 255;    // BLUE
pbImgData[iOffsUpperLeft+2].g = 0;    // GREEN
pbImgData[iOffsUpperLeft+2].r = 0;    // RED

saveToFileBMP( *pActiveBuf, "RGB24.bmp" );

To check the result, open the saved image and take a look at the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


RGB32

RGB32 is a 32 bit color format. It is like RGB24, except that every pixel has an additional byte to store an alpha value. An alpha value describes the transparency of the pixel. Therefore, every pixel consists of 4 bytes. RGB32 is also referred to as RGBA, where the A stands for Alpha. The A value is not used in IC Imaging Control and is therefore always 0. As for the RGB24 pixel format, IC Imaging Control uses the BGRA byte order for the RGB32 pixel format. The organization of the pixels in the image buffer is from left to right and bottom up.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a MemBufferCollection, which defines the image data color format must have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of RGB32.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, live mode is started and Grabber::snapImages is called.

Accessing the buffer

The following code retrieves a byte pointer to the image data. We use a structure declared in windows.h, RGBQUAD to access the pixel's components and reduce coordinate calculation to the level of RGB8:

RGBQUAD* pbImgData = (RGBQUAD*)pActiveBuf->getPtr();

In this example, we want to output the first (upper left hand) two pixels of the image. In a second step, we are going to manipulate the first 3 pixels. As mentioned before, the image data is stored bottom up. Therefore, pbImgData points to the first pixel of the last line of the image. To get access to the first pixel of the first line of the image, the following calculation has to be performed:

// Calculate the index of the upper left pixel
// Images are stored upside down in the image buffer
SIZE dim = pActiveBuf->getFrameType().dim;
int iOffsUpperLeft = (dim.cy-1) * dim.cx;

At first, we retrieve the width and height of the image in terms of pixels. Then, the offset to the upper left pixel is calculated. Since every pixel is exactly 1 byte in size, we can calculate the offset as:

(Height-1) * Width

Now that we have the offset to the the first pixel, we can read it out:

printf( "\nImage buffer pixel format is eRGB32\n" );
printf( "Pixel 1(RGBA): %d %d %d %d\n", pbImgData[iOffsUpperLeft].rgbRed,
                                          pbImgData[iOffsUpperLeft].rgbGreen,
                                        pbImgData[iOffsUpperLeft].rgbBlue,
                                        pbImgData[iOffsUpperLeft].rgbReserved );
printf( "Pixel 2(RGBA): %d %d %d %d\n", pbImgData[iOffsUpperLeft+1].rgbRed,
                                          pbImgData[iOffsUpperLeft+1].rgbGreen,
                                        pbImgData[iOffsUpperLeft+1].rgbBlue,
                                        pbImgData[iOffsUpperLeft+1].rgbReserved );

Manipulating Image Data

Instead of only reading pixel data, it is, of course, possible to manipulate the data as well. The following code sets the upper left hand pixel to red and the next 2 pixels to green and blue. After this manipulation, the image is saved as a .bmp file.

// overwrite first 3 pixels and save image to disk
// Set the first pixel to RED
pbImgData[iOffsUpperLeft].rgbRed = 0xff;
pbImgData[iOffsUpperLeft].rgbGreen = 0;
pbImgData[iOffsUpperLeft].rgbBlue = 0;
pbImgData[iOffsUpperLeft].rgbReserved = 0;

// Set the second pixel to GREEN
pbImgData[iOffsUpperLeft+1].rgbRed = 0;
pbImgData[iOffsUpperLeft+1].rgbGreen = 0xff;
pbImgData[iOffsUpperLeft+1].rgbBlue = 0;
pbImgData[iOffsUpperLeft+1].rgbReserved = 0;

// Set the third pixel to BLUE
pbImgData[iOffsUpperLeft+2].rgbRed = 0;
pbImgData[iOffsUpperLeft+2].rgbGreen = 0;
pbImgData[iOffsUpperLeft+2].rgbBlue = 0xff;
pbImgData[iOffsUpperLeft+2].rgbReserved = 0;

saveToFileBMP( *pActiveBuf, "RGB32.bmp" );

To check the result, open the saved image and take a look at the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


RGB555

RGB555 is a 16 bit color format. Every pixel is represented by two bytes. The characters 555 stand for the number of bits used for every color value. In this case, 5 bits are used for every color value, so only 15 bits are needed. The last bit (most significant bit) is unused. The organization of the pixels in the image buffer is from left to right and bottom up.

Memory Layout

As illustrated above, the 5 least significant bits of the WORD correspond to the blue value, bits 5 - 9 correspond to the green value and bits 10 to 14 correspond to the red value. Bit 15 is unused in this case. Please note that on the x86 architecture WORDs are stored in little endian order, which means the LOW BYTE is saved first. This is important when accessing the image data with a byte pointer.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a MemBufferCollection, which defines the image data color format must first have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of RGB555.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, we start live mode and call Grabber::snapImages.

Accessing the buffer

The following code retrieves a pointer to the image data. Please note, that getPtr() returns a BYTE pointer which will be type-casted to a WORD pointer. This makes it much easier to access the pixel data since RGB555 is a 16 bit color format.

WORD* pwImgData = (WORD*) pActiveBuf->getPtr();

In this example, we want to output the first (upper left hand) pixel of the image and manipulate the first 3. As previously mentioned, the image data is stored bottom up. Therefore, pwImgData points to the first byte of the first pixel of the last line in the buffer. To get access to this first byte, the following calculation has to be performed:

// Calculate the index of the upper left pixel
// Images are stored upside down in the image buffer
// * 1: a pixel is 2 byte, but since we have a WORD pointer (which is also 2 bytes)
// we count in pixel not in bytes
SIZE dim = pActiveBuf->getFrameType().dim;
int iOffsUpperLeft = (dim.cy-1) * dim.cx * 1;

At first, we retrieve the width and height of the image in terms of pixels. Then, the offset to the upper left pixel is calculated. Please note that we multiply with Width * 1 and not Width * 2. This is because we use a WORD pointer to access the image data. Of course, the multiplication by 1 is just for illustration and can be left out.

(Height-1) * Width

Now that we have the offset to the the first pixel, we can read it out:

// Please note: RGB values are stored within a WORD in the following order: R,G,B
// A binary AND operation is done with the color mask to extract the specific color.
// After the AND operation, a right shift is done so that the output is displayed correctly.
printf( "\nImage buffer pixel format is eRGB555\n" );

printf( "Pixel 1(RGB): %d %d %d\n", ( pwImgData[iOffsUpperLeft] & eRGB555_R ) >> 10 ,
    ( pwImgData[iOffsUpperLeft] & eRGB555_G ) >> 5,
    ( pwImgData[iOffsUpperLeft] & eRGB555_B ) );
printf( "Pixel 2(RGB): %d %d %d\n", ( pwImgData[iOffsUpperLeft+1] & eRGB555_R ) >> 10 ,
    ( pwImgData[iOffsUpperLeft+1] & eRGB555_G ) >> 5,
    ( pwImgData[iOffsUpperLeft+1] & eRGB555_B ) );

As seen in the code above, we perform a binary AND operation with the appropriate pixel mask on the current pixel to extract the color value. After that, the values for red and green must be shifted to the right to get the correct value (otherwise the value would be 1024 (32 times too large)).

Manipulating Image Data

Shifting is also important when assigning values. For example, if 7 is assigned to the red value, it must be shifted 10 times to the left. Instead of writing:

// Assign 7 to the red value
pwImgData[iOffsUpperLeft] = 7;  // this is WRONG

which assigns 7 to the blue value, the following code should be used:

// Assign 7 to the red value
pwImgData[iOffsUpperLeft] = 7 << 10;

Another important thing to note is that the assignment above will overwrite the values for green and blue. To prevent this, the value must be ORed to the pixel data as the following code will show:

// Clear the red value (set all bits to 0)
pwImgData[iOffsUpperLeft] &= ~eRGB555_R;

// Assign 7 to the red value without overwriting green and blue values
pwImgData[iOffsUpperLeft] |= 7 << 10;

Please note that all bits of the appropriate color should be set to 0, as does the code above. Consider, for example, that the previous red value could have been 16 (or 10000 binary). If we then perform a binary OR operation with 7 (or 111 binary), the result will be 23 (or 10111 binary). Therefore, it is better to set all bits of the appropriate channel to 0.

Now we set the upper left pixel to red, the next to green and the third to blue.

// overwrite the first 3 pixels and save image to disk
// set the first pixel to RED
pwImgData[iOffsUpperLeft] = 0;            // clear the pixel
pwImgData[iOffsUpperLeft] |= 31 << 10;    // Assign the value for red

// set the second pixel to GREEN
pwImgData[iOffsUpperLeft+1] = 0;        // clear the pixel
pwImgData[iOffsUpperLeft+1] |= 31 << 5;    // Assign the value for green

// set the third pixel to BLUE
pwImgData[iOffsUpperLeft+2] = 0;        // clear the pixel
pwImgData[iOffsUpperLeft+2] |= 31;        // Assign the value for blue

pActiveBuf->save( "RGB555.bmp" );

To check the result, just open the saved image and examine the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


RGB565

The RGB565 color format is the same as the RGB555 color format, except that 6 bits are used for the green value instead of 5. Therefore, all 16 bits are in use. The organization of the pixels in the image buffer is from left to right and bottom up.

Memory Layout

As illustrated above, the 5 least significant bits of the WORD correspond to the blue value, bits 5 - 10 correspond to the green value and bits 11 to 15 correspond to the red value. Please note that on the x86 architecture WORDs are stored in little-endian order, which means the LOW BYTE is saved first. This is important when accessing the image data with a byte pointer.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a MemBufferCollection, which defines the image data color format must first have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of RGB555.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, we start live mode and call Grabber::snapImages.

Accessing the buffer

The following code retrieves a pointer to the image data. Please note, that getPtr() returns a BYTE pointer, which will be type-casted to a WORD pointer. This makes it much easier to access the pixel data since RGB565 is a 16 bit color format.

WORD* pwImgData = (WORD*) pActiveBuf->getPtr();

In this example, we want to output the first (upper left hand) pixel of the image and manipulate the first 3. As previously mentioned, the image data is stored bottom up. Therefore, pwImgData points to the first byte of the first pixel of the last line in the buffer. To get access to this first byte, the following calculation has to be performed:

// Calculate the index of the upper left pixel
// Images are stored upside down in the image buffer
// * 1: a pixel is 2 byte, but since we have a WORD pointer (which is also 2 bytes)
// we count in pixel not in bytes
SIZE dim = pActiveBuf->getFrameType().dim;
int iOffsUpperLeft = (dim.cy-1) * dim.cx * 1;

At first, we retrieve the width and height of the image in terms of pixels. Then, the offset to the upper left pixel is calculated. Please note that we multiply with Width * 1 and not Width * 2. This is because we use a WORD pointer to access the image data. Of course, the multiplication by 1 is just for illustration and can be left out.

(Height-1) * Width

Now that we have the offset to the the first pixel, we can read it out:

// Please note: RGB values are stored within a WORD in the following order: R,G,B
// A binary AND operation is done with the color mask to extract the specific color.
// After the AND operation, a right shift is done so that the output is displayed correctly.
printf( "\nImage buffer pixel format is eRGB565\n" );
printf( "Pixel 1(RGB): %d %d %d\n", ( pwImgData[iOffsUpperLeft] & eRGB565_R ) >> 11,
    ( pwImgData[iOffsUpperLeft] & eRGB565_G ) >> 5,
    ( pwImgData[iOffsUpperLeft] & eRGB565_B ) );
printf( "Pixel 2(RGB): %d %d %d\n", ( pwImgData[iOffsUpperLeft+1] & eRGB565_R ) >> 11 ,
    ( pwImgData[iOffsUpperLeft+1] & eRGB565_G ) >> 5,
    ( pwImgData[iOffsUpperLeft+1] & eRGB565_B ) );

As seen in the code above, we perform a binary AND operation with the appropriate pixel mask on the current pixel to extract the color value. After that, the values for red and green must be shifted to the right to get the correct value (otherwise the value would be 2048 (32 times too big)).

Manipulating Image Data

Shifting is also important when assigning values. For example, if 7 is assigned to the red value, it must be shifted 11 times to the left. Instead of writing:

// Assign 7 to the red value
pwImgData[iOffsUpperLeft] = 7;  // this is WRONG

which assigns 7 to the blue value, the following code should be used:

// Assign 7 to the red value
pwImgData[iOffsUpperLeft] = 7 << 11;

Another important thing to note is that the assignment above will overwrite the values for green and blue. To prevent this, the value must be ORed to the pixel data as the following code will show:

// Clear the red value (set all bits to 0)
pwImgData[iOffsUpperLeft] &= ~eRGB565_R;

// Assign 7 to the red value without overwriting green and blue values
pwImgData[iOffsUpperLeft] |= 7 << 11;

Please note that all bits of the appropriate color should be set to 0, as the code above does. Consider, for example, that the previous red value could have been 16 (or 10000 binary). If we then perform a binary OR operation with 7 (or 111 binary), the result will be 23 (or 10111 binary). Therefore, it is better to set all bits of the appropriate channel to 0.

Now we set the upper left hand pixel to red, the next to green and the third to blue.

// overwrite the first 3 pixels and save image to disk
// set the first pixel to RED
pwImgData[iOffsUpperLeft] = 0;            // clear the pixel
pwImgData[iOffsUpperLeft] |= 31 << 11;    // Assign the value for red

// set the second pixel to GREEN
pwImgData[iOffsUpperLeft+1] = 0;        // clear the pixel
pwImgData[iOffsUpperLeft+1] |= 63 << 5;    // Assign the value for green

// set the third pixel to BLUE
pwImgData[iOffsUpperLeft+2] = 0;        // clear the pixel
pwImgData[iOffsUpperLeft+2] |= 31;        // Assign the value for blue

pActiveBuf->save( "RGB565.bmp" );

To check the result, just open the saved image and examine the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


UYVY

The UYVY color format is basically a 16 bit color format. In contrast to the RGB formats, it contains no values for red, green or blue. It uses values for luminance and chrominance instead. Y stands for the luminance. U (or Cb) and V (or Cr) describe the chrominance. For further details refer to the following link:

http://www.fourcc.org

The organization of the pixels in the image buffer is from left to right and top down.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a MemBufferCollection, which defines the image data color format must first have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of UYVY.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, we start live mode and call Grabber::snapImages.

Accessing the buffer

The following code retrieves a byte pointer to the image data. We use a structure UYVYQuad to access the different components of the pixel pairs:

// UYVY Images are stored top-down, so the upper left pixel starts at byte 0.
// Each 4 bytes represent the color for 2 neighboring pixels:
//
// [ U0 | Y0 | V0 | Y1 ]
//
// Y0 is the brightness of pixel 0, Y1 the brightness of pixel 1.
// U0 and V0 is the color of both pixels.
struct UYVYQuad
{
    BYTE U0;
    BYTE Y0;
    BYTE V0;
    BYTE Y1;
};
UYVYQuad* pImgData = (UYVYQuad*)pActiveBuf->getPtr();

In this example, we want to output the first (upper left hand) four pixels of the image. In a second step, we are going to manipulate the first six pixels. Because UYVY images are stored top-down, the index of the upper left two pixels is 0:

// Calculate the index of the upper left pixel
// Images are stored top-down in the image buffer, so the first two pixels have index 0.
int iOffsUpperLeft = 0;

Now that we have the offset to the the first pixel, we can read it out:

printf( "\nImage buffer pixel format is eUYVY\n" );
printf( "Pixel 1 (Y U V): %d %d %d\n", pImgData[iOffsUpperLeft].Y0,
    pImgData[iOffsUpperLeft].U0, pImgData[iOffsUpperLeft].V0 );
printf( "Pixel 2 (Y U V): %d %d %d\n", pImgData[iOffsUpperLeft].Y1,
    pImgData[iOffsUpperLeft].U0, pImgData[iOffsUpperLeft].V0 );
printf( "Pixel 3 (Y U V): %d %d %d\n", pImgData[iOffsUpperLeft+1].Y0,
    pImgData[iOffsUpperLeft+1].U0, pImgData[iOffsUpperLeft+1].V0 );
printf( "Pixel 4 (Y U V): %d %d %d\n", pImgData[iOffsUpperLeft+1].Y1,
    pImgData[iOffsUpperLeft+1].U0, pImgData[iOffsUpperLeft+1].V0 );

Please note, that while the two pixels of a pixel pair have separate Y (brightness) values, they share the color values U and V.

Manipulating Image Data

Instead of only reading pixel data, it is, of course, possible to manipulate the data as well. The following code sets the upper left six pixels to red, light red, green, dark green, blue and light blue. After this manipulation, the image is saved as a BMP file.

// Overwrite the first 6 pixels and save image to disk
// set the first 2 pixels to RED
pImgData[0].U0 = 90;
pImgData[0].V0 = 240;
pImgData[0].Y0 = 82;
pImgData[0].Y1 = 164;    // Make the 2nd pixel brighter

// set the 3rd and 4th to GREEN
pImgData[1].U0 = 54;
pImgData[1].V0 = 34;
pImgData[1].Y0 = 145;
pImgData[1].Y1 = 72;    // Make the 2nd pixel darker

// set the 5th and 6th pixel to BLUE
pImgData[2].U0 = 240;
pImgData[2].V0 = 110;
pImgData[2].Y0 = 41;
pImgData[2].Y1 = 82;    // Make the 2nd pixel brighter

// The values above were calculated using the following formulas:
//
//    Y  =  (0.257 * R) + (0.504 * G) + (0.098 * B) + 16
//  V  =  (0.439 * R) - (0.368 * G) - (0.071 * B) + 128
//  U  = -(0.148 * R) - (0.291 * G) + (0.439 * B) + 128
//

// We save the buffer as RGB24, so that other software can view it.
saveToFileBMP( *pActiveBuf, "UYVY.bmp", eRGB24 );

To check the result, open the saved image and take a look at the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


YGB0

YGB0 is a 10 bit grayscale format. Every pixel is stored in two bytes. Only 10 of the 16 bits of these two bytes contain relevant image data, the other bits are unused. The organization of the pixels in the image buffer is from left to right and top down.

Memory Layout

As illustrated above, the low byte contains the bits 2 to 9, while the least significant bits 0 and 1 are stored in the high byte. To convert a 16-bit-pixel from the image buffer to a 16-bit-value (in range 0-1023) that can be used in image processing, the bytes have to be swapped and a right-shift has to be performed. The following code shows how to convert to and from the YGB0 format:

unsigned __int16 YGB0PixelFromInt16Value( unsigned __int16 value )
{
    return byteSwap( value << 6 );
}

unsigned __int16 Int16ValueFromYGB0Pixel( unsigned __int16 pixel )
{
    return byteSwap( pixel ) >> 6;
}

The function Int16ValueFromYGB0Pixel takes a 16-bit word from the image buffer and converts it to a logical brightness value for that pixel in the range 0 to 1023.

YGB0PixelFromInt16Value reverses that operation by converting a brightness value to a number that can be stored in the image buffer.

The functions rely on the byteSwap function that is implemented as follows:

unsigned __int16 byteSwap( unsigned __int16 x )
{
    BYTE* p = (BYTE*)&x;
    return ((unsigned int)p[0] << 8) | p[1];
}

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a MemBufferCollection, which defines the image data color format must first have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of YGB0.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, live mode is started and Grabber::snapImages is called.

Accessing the buffer

The following code retrieves a pointer to the image data. Please note that getPtr() returns a BYTE pointer which will be type-casted to an unsigned __int16 pointer. This makes it much easier to access the pixel data since YGB0 is a 16 bit format.

// YGB0 Images are stored top-down, so the upper left pixel starts at byte 0.
// 2 Byte represent one pixel.
unsigned __int16* pImgData = (unsigned __int16*)pActiveBuf->getPtr();

In this example, we want to output the first (upper left hand) pixel of the image and manipulate the first 3. As previously mentioned, the image data is stored top down. Therefore, pImgData points to the first pixel of the first line in the buffer.

To convert the pixel data to brightness values, the function YGB0PixelFromInt16Value from above is used:

// To get a "value" (in range 0-1023) for the pixel, use
// Int16ValueFromYGB0Pixel:
unsigned __int16 val0 = Int16ValueFromYGB0Pixel( pImgData[0] );
unsigned __int16 val1 = Int16ValueFromYGB0Pixel( pImgData[1] );

printf( "\nImage buffer pixel format is eYGB0\n" );
printf( "Pixel 1 (Y16): %d\n", val0 );
printf( "Pixel 2 (Y16): %d\n", val1 );

Manipulating Image Data

Now we set the upper left hand three pixels to black, gray and white. The function YGB0PixelFromInt16Value from above is used to convert from brightness values to pixel data:

pImgData[0] = YGB0PixelFromInt16Value( 0 );        // Set the first pixel to BLACK
pImgData[1] = YGB0PixelFromInt16Value( 511 );    // Set the second pixel to GRAY
pImgData[2] = YGB0PixelFromInt16Value( 1023 );    // Set the third pixel to WHITE

// We save the buffer as RGB24, so that other software can view it.
saveToFileBMP( *pActiveBuf, "YGB0.bmp", eRGB24 );

To check the result, just open the saved image and examine the upper left pixels. They should look as follows:

<< Accessing an Image Buffer


YGB1

YGB1 is a 10 bit grayscale format. Every pixel is stored in two bytes. Only 10 of the 16 bits of these two bytes contain relevant image data, the other bits are unused. The organization of the pixels in the image buffer is from left to right and top down.

Memory Layout

As illustrated above, the high byte contains the bits 0 to 7, while the most significant bits 8 and 9 are stored in the low byte. To convert a 16-bit-pixel from the image buffer to a 16-bit-value (in range 0-1023) that can be used in image processing, the bytes have to be swapped. The following code shows how to convert to and from the YGB1 format:

unsigned __int16 YGB1PixelFromInt16Value( unsigned __int16 value )
{
    return byteSwap( value );
}

unsigned __int16 Int16ValueFromYGB1Pixel( unsigned __int16 pixel )
{
    return byteSwap( pixel );
}

The function Int16ValueFromYGB1Pixel takes a 16-bit word from the image buffer and converts it to a logical brightness value for that pixel in the range 0 to 1023.

YGB1PixelFromInt16Value reverses that operation by converting a brightness value to a number that can be stored in the image buffer.

The functions rely on the byteSwap function that is implemented as follows:

unsigned __int16 byteSwap( unsigned __int16 x )
{
    BYTE* p = (BYTE*)&x;
    return ((unsigned int)p[0] << 8) | p[1];
}

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a MemBufferCollection, which defines the image data color format must have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of YGB1.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, we start live mode and call Grabber::snapImages.

Accessing the buffer

The following code retrieves a pointer to the image data. Please note, that getPtr() returns a BYTE pointer which will be type-casted to an unsigned __int16 pointer. This makes it much easier to access the pixel data since YGB1 is a 16 bit format.

// YGB1 Images are stored top-down, so the upper left pixel starts at byte 0.
// 2 Byte represent one pixel.
unsigned __int16* pImgData = (unsigned __int16*)pActiveBuf->getPtr();

In this example, we want to output the first (upper left hand) pixel of the image and manipulate the first 3. As previously mentioned, the image data is stored top down. Therefore, pImgData points to the first pixel of the first line in the buffer.

To convert the pixel data to brightness values, the function YGB1PixelFromInt16Value from above is used:

// To get a "value" (in range 0-1023) for the pixel, use
// Int16ValueFromYGB1Pixel:
unsigned __int16 val0 = Int16ValueFromYGB1Pixel( pImgData[0] );
unsigned __int16 val1 = Int16ValueFromYGB1Pixel( pImgData[1] );

printf( "\nImage buffer pixel format is eYGB1\n" );
printf( "Pixel 1 (Y16): %d\n", val0 );
printf( "Pixel 2 (Y16): %d\n", val1 );

Manipulating Image Data

Now we set the upper left three pixels to black, gray and white. The function YGB1PixelFromInt16Value from above is used to convert from brightness values to pixel data:

pImgData[0] = YGB1PixelFromInt16Value( 0 );        // Set the first pixel to BLACK
pImgData[1] = YGB1PixelFromInt16Value( 511 );    // Set the second pixel to GRAY
pImgData[2] = YGB1PixelFromInt16Value( 1023 );    // Set the third pixel to WHITE

// We save the buffer as RGB24, so that other software can view it.
saveToFileBMP( *pActiveBuf, "YGB1.bmp", eRGB24 );

To check the result, just open the saved image and examine the upper left pixels. They should look as follows:

<< Accessing an Image Buffer


Basic Use of VCD Properties

This chapter describes the basic functionality of the VCDProperties. It shows you how to retrieve interfaces, which allow you to manipulate elements, such as the value or the automation state of a property.

Introduction

This sample uses the "Brightness" property to demonstrate how the properties are organized and how they are accessed. First, the IVCDPropertyItem for "Brightness" is retrieved from the IVCDPropertyItems collection (for details refer to Grabber::getAvailableVCDProperties ). Then a switch and a range interface are retrieved from the respective elements of this IVCDPropertyItem. The switch interface is used to toggle the automation state of this property (on and off). The range interface is used to manipulate the value of this property.

The source code for this sample program can be found in the %TOPLEVEL%\samples\VC71\VCD Simple sample source directory. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6.

Creating the Project

The sample program of this chapter is a dialog based application. To set up such a project, follow the steps as described in the FirstSteps chapter. This sample is very similar, however it is a "Dialog based" type of application instead of a "Single Document" type as described in the FirstSteps.

Now, add a check box and a slider to the form. Give the check box the ID IDC_BRIGHTNESS_CHECK and the slider IDC_BRIGHTNESS_SLIDER. To display the live video add a static text control to the dialog and give it the ID IDC_DISPLAY.

Retrieving a VCDPropertyItem

After a valid video capture device has been selected, the IVCDPropertyItem for "Brightness" is retrieved. This is done in the InitPropertyControls method, which is called by the OnInitDialog method:

tIVCDPropertyItemsPtr pItems = m_Grabber.getAvailableVCDProperties();
if( pItems != 0 )
{
    // Try to find the brightness item
    tIVCDPropertyItemPtr pBrightnessItem = pItems->findItem( VCDID_Brightness );

Just declare a variable pItems of type tIVCDPropertyItemsPtr which will hold the available VCD Properties. Then declare a variable pBrightnessItem of type tIVCDPropertyItemPtr and use the findItem method to assign the appropriate property. The property item that should be retrieved must be specified by its item ID (or GUID). In this case, it is VCDID_Brightness for the "Brightness" property item.

Retrieving Interfaces and Initialize the Controls

Properties consist of one or more elements such as the value, automation state, one push operation and further parameters, if supported. To manipulate a property, interfaces are used. They can be retrieved from the elements of a property item. Add 2 member variables to the CVCDSimpleDlg class that will hold the interfaces to the value and the automation state:

DShowLib::tIVCDRangePropertyPtr        m_pBrightnessRange;
DShowLib::tIVCDSwitchPropertyPtr    m_pBrightnessAuto;

The following code shows you how to actually retrieve a switch and a range interface and how to get their current states in order to initialize the associated user controls.

tIVCDPropertyElementPtr pBrightnessValueElement = pBrightnessItem->findElement( VCDElement_Value );
tIVCDPropertyElementPtr pBrightnessAutoElement =  pBrightnessItem->findElement( VCDElement_Auto );

// If a value element exists, try to acquire a range interface
if( pBrightnessValueElement != 0 )
{
    pBrightnessValueElement->getInterfacePtr( m_pBrightnessRange );
}

// If an auto element exists, try to acquire a switch interface
if( pBrightnessAutoElement != 0 )
{
    pBrightnessAutoElement->getInterfacePtr( m_pBrightnessAuto );

    // If successful, disable automation
    if( m_pBrightnessAuto != 0 )
        m_pBrightnessAuto->setSwitch( false );
}

The interface is retrieved in 2 steps. In the first step, the appropriate element that should be manipulated is retrieved. This is done using the IVCDPropertyItem::findElement method. In the second step, the desired interfaces are retrieved from the respective elements. This is done using the IVCDPropertyElement::getInterfacePtr method, which returns a reference to the specified interface.

Now that the we have the interfaces, the user controls can be initialized. The following code shows you how this is done:

// Check whether we were able to acquire a range interface to brightness value
if( m_pBrightnessRange != 0 )
{
    m_BrightnessSlider.EnableWindow();

    // Set the slider range
    int delta = m_pBrightnessRange->getDelta();
    m_BrightnessSlider.SetRangeMin( m_pBrightnessRange->getRangeMin() / delta );
    m_BrightnessSlider.SetRangeMax( m_pBrightnessRange->getRangeMax() / delta );

    // Set the slider position
    m_BrightnessSlider.SetPos( m_pBrightnessRange->getValue() / delta );
}
else
{
    m_BrightnessSlider.EnableWindow( FALSE );
}

// Check whether we were able to acquire a switch interface to brightness auto
if( m_pBrightnessAuto != 0 )
{
    m_BrightnessAutoCheck.EnableWindow();

    m_BrightnessAutoCheck.SetCheck( m_pBrightnessAuto->getSwitch() );
}
else
{
    m_BrightnessAutoCheck.EnableWindow( FALSE );
}

As the code above illustrates, the interface classes let you easily access the elements of a property item.

Manipulating the Elements of a Property

In this final step, we want to show you how to use the interfaces to manipulate the property. Add a Click event for the check box and a handler for the WM_HSCROLL message. The check box toggles the automation state of the "Brightness" property. The code looks as follows:

if( m_BrightnessAutoCheck.GetCheck() )
{
    m_BrightnessSlider.EnableWindow( FALSE );
    m_pBrightnessAuto->setSwitch( true );
}
else
{
    m_BrightnessSlider.EnableWindow();
    m_pBrightnessAuto->setSwitch( false );
}

The code above just assigns the current state of the check box to the automation element of the "Brightness" property. Additionally, the slider is disabled, if the automation state is on.

The code for the Scroll event of the slider is even simpler:

int delta = m_pBrightnessRange->getDelta();
m_pBrightnessRange->setValue( m_BrightnessSlider.GetPos() * delta );

Now you can run the program and manipulate the "Brightness" property using the slider and the check box.

<< Programmer's Guide


List VCD Properties

This chapter shows you how to retrieve all properties of a video capture device, using the new VCD property interface. In addition, it is shown how to access and manipulate a property using predefined IDs.

All properties that are retrieved from the video capture device are displayed in a TreeView. The TreeView was chosen, because it perfectly matches the organization of the properties, since they naturally form a tree structure. The root of the tree is the IVCDPropertyItems collection. The collection contains all IVCDPropertyItems that are provided by the current video capture device. Each IVCDPropertyItem has one or more IVCDPropertyElements, which in turn have one or more IVCDPropertyInterfaces, that are used to access the property.

The source code for this sample program is contained in the %TOPLEVEL%\samples\VC71\List VCDProperties sample source directory. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6.

Setting up the Project

The sample program of this chapter is a dialog based application. To set up such a project, follow the steps as described in the FirstSteps chapter, except that this sample is a "Dialog based" type of application, instead of a "Single Document" type as described in the FirstSteps.

There are some classes in the samples\VC6\Common directory, which are used to manipulate the properties. In order to use them, they must be added to the project. To do so, right mouse click on the project in the project explorer. Choose "New Folder..." and name the folder controls. The "File extension" field can be left open. Now right click on the folder that was just created and select "Add Files to Folder...". Browse to the samples\VC6\Common directory and select all files that begin with "VCD". Click the "OK" button and the files will be added to the project.

Some bitmaps have to be included for the tree view. Select "Resource..." from the "Insert" menu. In the "Insert Resource" dialog select "Bitmap" and click on the "Import" button. In the dialog that follows, set the "Files of type" to "All Files (*.*)" and browse to the directory of this sample. Open the "res" subdirectory, select all bitmap files and click the "Import" button. Now give them appropriate IDs like IDB_AUTO and IDB_BUTTON.

Adding Functionality to the Application

Add two buttons to the dialog. Label them "Select Device..." and "Property Page" and give them the IDs "IDC_SELECT_DEVICE" and "IDC_SHOW_PAGE". Now, add a tree control and give it the ID "IDC_VCDTREE". The tree control is used to visualize the organization of the VCDProperties. Add a static text field and give it the ID "IDC_DISPLAY". Open the property dialog of the text field and check the "Border" property under the "Styles" tab. This control will be used to display the live video. Finally, add a group box and give it the ID "IDC_CTRL_FRAME". The appropriate controls to manipulate the properties will be placed inside this frame at runtime.

To call the dialog, open the file "VCD Property Tree.cpp" and change the code in the InitInstance method as follows:

CVCDPropertyTreeDlg dlg;

if( !dlg.selectDevice() )
{
    AfxMessageBox( TEXT("No device was selected.") );
    return FALSE;
}

m_pMainWnd = &dlg;
dlg.DoModal();

// Since the dialog has been closed, return FALSE so that we exit the
// application, rather than start the application's message pump.
return FALSE;

This ensures that the device selection dialog is called before the main dialog and ensures that there is a valid device, otherwise the application shows a message box and terminate.

In order to add functionality to the dialog class, open the file "VCD Property TreeDlg.h" and include the file "VCDPropertyCtrl.h":

#include "../Common/VCDPropertyCtrl.h"

Also insert some using statements directly above the class definition:

using DShowLib::tIVCDPropertyItemsPtr;
using DShowLib::tIVCDPropertyItemPtr;
using DShowLib::tIVCDPropertyElementPtr;
using DShowLib::tIVCDPropertyInterfacePtr;

We need a little container class, in which the interface path is stored. An interface path consists of an itemID, an elementID and an interfaceID. The class is implemented as follows:

class CInterfacePath
{
public:
    GUID itemID;
    GUID elementID;
    GUID interfaceID;
};

Now add a public method selectDevice and some protected methods and variables to the CVCDPropertyTreeDlg class:

public:
    bool    selectDevice();

protected:
    HICON m_hIcon;

    DShowLib::Grabber    m_Grabber;

    CImageList            m_ImageList;    // Contains graphical elements for the tree view.

    void QueryVCDProperties();
    void QueryVCDPropertyItems( tIVCDPropertyItemsPtr pItems, HTREEITEM hRoot );
    void QueryVCDPropertyElements( tIVCDPropertyItemPtr pItem, HTREEITEM hItem );
    void QueryVCDPropertyInterfaces( tIVCDPropertyElementPtr pElem, HTREEITEM hElem );

    void ListAllPropertyItems();

    smart_ptr< CWnd >    m_pCurrentControl;
    smart_ptr< CWnd >    m_pBuddy;
    std::vector< CInterfacePath > m_InterfaceVector;

Now edit the file "VCD Property TreeDlg.cpp" to implement the methods. First, include the interface classes for the properties and declare the namespace DShowLib:

#include "../Common/VCDRangeSlider.h"
#include "../Common/VCDSwitchCheck.h"
#include "../Common/VCDButtonButton.h"
#include "../Common/VCDMapStringsCombo.h"
#include "../Common/VCDAbsValSlider.h"

using namespace DShowLib;

The graphical elements for the tree view, are stored in the image list at construction time of the dialog. Therefore, extend the standard constructor as follows:

CVCDPropertyTreeDlg::CVCDPropertyTreeDlg(CWnd* pParent /*=NULL*/)
    : CDialog(CVCDPropertyTreeDlg::IDD, pParent)
{
    //{{AFX_DATA_INIT(CVCDPropertyTreeDlg)
        // NOTE: the ClassWizard will add member initialization here
    //}}AFX_DATA_INIT
    // Note that LoadIcon does not require a subsequent DestroyIcon in Win32
    m_hIcon = AfxGetApp()->LoadIcon(IDR_MAINFRAME);

    // Create the image list for the tree view and load images
    m_ImageList.Create( 16, 16, ILC_COLOR4, 0, 7 );

    CBitmap bm;
    bm.LoadBitmap( IDB_ITEM );
    m_ImageList.Add( &bm, RGB(0,0,0) );
    bm.Detach();
    bm.LoadBitmap( IDB_VALUE );
    m_ImageList.Add( &bm, RGB(0,0,0) );
    bm.Detach();
    bm.LoadBitmap( IDB_AUTO );
    m_ImageList.Add( &bm, RGB(0,0,0) );
    bm.Detach();
    bm.LoadBitmap( IDB_RANGE );
    m_ImageList.Add( &bm, RGB(0,0,0) );
    bm.Detach();
    bm.LoadBitmap( IDB_SWITCH );
    m_ImageList.Add( &bm, RGB(0,0,0) );
    bm.Detach();
    bm.LoadBitmap( IDB_BUTTON );
    m_ImageList.Add( &bm, RGB(0,0,0) );
    bm.Detach();
    bm.LoadBitmap( IDB_MAPSTRINGS );
    m_ImageList.Add( &bm, RGB(0,0,0) );
    bm.Detach();
}

This fills the image list with the graphical elements, previously added to the resources.

On the OnInitDialog event, the grabber and the tree view need to be set up. Add the following code to the OnInitDialog method to do so:

m_Grabber.setHWND( GetDlgItem( IDC_DISPLAY )->GetSafeHwnd() );
m_Grabber.startLive();

CTreeCtrl* pTree = (CTreeCtrl*)GetDlgItem( IDC_VCDTREE );
pTree->SetImageList( &m_ImageList, TVSIL_NORMAL );

// Print the property tree to debug out
ListAllPropertyItems();

QueryVCDProperties();

The code above first sets the HWND of the grabber to the static text control, so that it displays the live video. The image list is bound to the tree view via SetImageList, so that the tree view control has access to the graphical elements. Finally, ListAllPropertyItems and QueryVCDProperties are called. ListAllPropertyItems prints the tree structure of all supported properties to the debug output window. The debug output shows you the pure organization of the VCDProperties without taking care of other aspects like controls, while QueryVCDProperties builds up the tree view. Please note that you have to run the program in debug mode in order to see the property tree in the debug output window.

The public method selectDevice, which is called at startup, shows the device selection dialog. It is implemented as follows:

bool CVCDPropertyTreeDlg::selectDevice()
{
    m_Grabber.showDevicePage( m_hWnd );

    return m_Grabber.isDevValid();
}

Now use the class wizard to insert the click events for the two buttons "IDC_SELECT_DEVICE" and "IDC_SHOW_PAGE". A click on the buttons should bring up the appropriate dialog. The implementation of the click event for the "IDC_SHOW_PAGE" button is simple: you just have to call the property dialog:

void CVCDPropertyTreeDlg::OnShowPage()
{
    // Show the property page
    m_Grabber.showVCDPropertyPage( m_hWnd );
}

The implementation of the click event for the "IDC_SELECT_DEVICE" event needs some more lines of code, because it must be checked, if the live mode is running. Additionally, the tree view has to be be updated after a new device has been selected. The code to do this, is as follows:

void CVCDPropertyTreeDlg::OnSelectDevice()
{
    // Live mode has to be stopped before showing the device page
    m_Grabber.stopLive();

    // Show device page
    m_Grabber.showDevicePage( m_hWnd );

    // start live mode if a valid device is selected
    if( m_Grabber.isDevValid() )
        m_Grabber.startLive();

    // Print the property tree to debug out
    ListAllPropertyItems();

    // Re-Build the tree
    QueryVCDProperties();
}

ListAllPropertyItems prints the property tree to debug out. it is implemented as follows:

void CVCDPropertyTreeDlg::ListAllPropertyItems()
{
    OutputDebugString( TEXT("\n\nVCD Tree:\n\n") );

    // Get all property items
    tIVCDPropertyItemsPtr pVCDProperties = m_Grabber.getAvailableVCDProperties();
    if( pVCDProperties != 0 )
    {
        // Iterate through the items and print the names.
        tVCDPropertyItemArray itemArray = pVCDProperties->getItems();
        for( tVCDPropertyItemArray::const_iterator itItem = itemArray.begin(); itItem != itemArray.end(); ++itItem )
        {
            // Print the item name
            OutputDebugString( CString( (*itItem)->getName().c_str() ) );
            OutputDebugString( TEXT("\n") );

            // Iterate through the elements and print the names.
            tVCDPropertyElementArray elemArray = (*itItem)->getElements();
            for( tVCDPropertyElementArray::iterator itElem = elemArray.begin(); itElem != elemArray.end(); ++itElem )
            {
                // Print the element name
                OutputDebugString( TEXT("   Element : ") );
                OutputDebugString( CString( (*itElem)->getName().c_str() ) );
                OutputDebugString( TEXT("\n") );

                // Iterate through the interfaces and print the names.
                tVCDPropertyInterfaceArray itfArray = (*itElem)->getInterfaces();
                for( tVCDPropertyInterfaceArray::const_iterator itItf = itfArray.begin(); itItf != itfArray.end(); ++itItf )
                {
                    // Check the interface type and print the name
                    OutputDebugString( TEXT("        Interface : ") );

                    GUID iid = (*itItf)->getInterfaceID();

                    if( iid == IID_IVCDAbsoluteValueProperty )
                    {
                        OutputDebugString( TEXT("Absolute Value\n") );
                    }
                    else if( iid == IID_IVCDMapStringsProperty )
                    {
                        OutputDebugString( TEXT("Mapstrings\n") );
                    }
                    else if( iid ==  IID_IVCDSwitchProperty )
                    {
                        OutputDebugString( TEXT("Switch\n") );
                    }
                    else if( iid == IID_IVCDButtonProperty )
                    {
                        OutputDebugString( TEXT("Button\n") );
                    }
                    else if( iid == IID_IVCDRangeProperty )
                    {
                        OutputDebugString( TEXT("Range\n") );
                    }
                }
            }
        }
    }
}

The three nested for loops in the code above reflect the tree structure of the VCDProperties. The first loop covers all available IVCDPropertyItems and prints their names to the debug output. For each item, the second loop prints out all available IVCDPropertyElements. The third loop finally prints out all types of interfaces that the element provides. Please note that the interfaces are sorted according to their level of detail. The most detailed one is the "AbsoluteValue" interface, followed by the "MapStrings" interface. "Switch" and "Button" are detailed interfaces providing simple functionality: toggle On/Off, trigger. The "Range" interface is the most generic one, but does not provide a meaning for the values that it represents. For example the "Brightness" range may be from 0 to 255. There is no way to tell, whether 0 or 255 is the maximum brightness value.

The method QueryVCDProperties initializes the tree view with the properties of the current video capture device:

void CVCDPropertyTreeDlg::QueryVCDProperties()
{
    CTreeCtrl* pTree = (CTreeCtrl*)GetDlgItem( IDC_VCDTREE );

    // Clear the tree
    pTree->DeleteAllItems();

    // Insert the root item
    HTREEITEM hRoot = pTree->InsertItem( TEXT("VCD Properties") );

    // Set item data to MAXDWORD, because this is not an interface.
    pTree->SetItemData( hRoot, MAXDWORD );

    tIVCDPropertyItemsPtr pVCDProperties = m_Grabber.getAvailableVCDProperties();
    if( pVCDProperties != 0 )
    {
        QueryVCDPropertyItems( pVCDProperties, hRoot );
    }

    // Make sure the tree is expanded
    pTree->Expand( hRoot, TVE_EXPAND );
}

The procedure above clears the tree view and creates a new root node. The root node is labeled "VCDPropertyItems". The procedure QueryVCDPropertyItems inserts all available property items. QueryVCDPropertyItems looks as follows:

void CVCDPropertyTreeDlg::QueryVCDPropertyItems( tIVCDPropertyItemsPtr pItems, HTREEITEM hRoot )
{
    CTreeCtrl* pTree = (CTreeCtrl*)GetDlgItem( IDC_VCDTREE );

    // Iterate through the items, insert them into the tree and query for their elements.
    tVCDPropertyItemArray itemArray = pItems->getItems();
    for( tVCDPropertyItemArray::const_iterator i = itemArray.begin(); i != itemArray.end(); ++i )
    {
        // Insert an item node.
        HTREEITEM hItem = pTree->InsertItem( CString( (*i)->getName().c_str() ), 0, 0, hRoot );

        // Set node data to MAXDWORD.
        pTree->SetItemData( hItem, MAXDWORD );

        // Query for elements
        QueryVCDPropertyElements( *i, hItem );

        // Make sure the tree is expanded.
        pTree->Expand( hItem, TVE_EXPAND );
    }
}

QueryVCDPropertyItems iterates through all available property items. For each item, it creates a new node. Every node that represents an item is a direct child of the root node. The node is labeled with the name of the IVCDPropertyItem (e.g. "Brightness", "Gain" or "Exposure"). Then, QueryVCDPropertyElements is called for the new node. QueryVCDPropertyElements looks as follows:

void CVCDPropertyTreeDlg::QueryVCDPropertyElements( tIVCDPropertyItemPtr pItem, HTREEITEM hItem )
{
    CTreeCtrl* pTree = (CTreeCtrl*)GetDlgItem( IDC_VCDTREE );

    CString name;
    int imgIndex;

    tVCDPropertyElementArray elemArray = pItem->getElements();
    for( tVCDPropertyElementArray::const_iterator i = elemArray.begin(); i != elemArray.end(); ++i )
    {

        GUID eid = (*i)->getElementID();
        if( eid == VCDElement_Value )
        {
            name = "VCDElement_Value";
            imgIndex = 1;
        }
        else if( eid == VCDElement_Auto )
        {
            name = "VCDElement_Auto";
            imgIndex = 2;
        }
        else if( eid == VCDElement_OnePush )
        {
            name = "VCDElement_OnePush";
            imgIndex = 5;
        }
        else if( eid == VCDElement_WhiteBalanceBlue )
        {
            name = "VCDElement_WhiteBalanceBlue";
            imgIndex = 1;
        }
        else if( eid == VCDElement_WhiteBalanceRed )
        {
            name = "VCDElement_WhiteBalanceRed";
            imgIndex = 1;
        }
        else
        {
            name = "Unknown element";
            imgIndex = 1;
        }

        name = name + ": '" + (*i)->getName().c_str() + "'";

        HTREEITEM hElem = pTree->InsertItem( name, imgIndex, imgIndex, hItem );

        // Set node data to MAXDWORD.
        pTree->SetItemData( hElem, MAXDWORD );

        QueryVCDPropertyInterfaces( *i, hElem );

        pTree->Expand( hElem, TVE_EXPAND );
    }
}

QueryVCDPropertyElements iterates through all available elements. For each element, it creates a new node. Each node that represents an element is a child of the node which represents the IVCDPropertyItem to which this IVCDPropertyElement belongs. The if..then..else block determines the appropriate graphical tree element for the node and sets its base name depending on the type of the element. The name of the IVCDPropertyElement (e.g. "Value", "Auto" or "Enable") is added to the base name and then used to label the node. Then, QueryVCDPropertyInterfaces is called for the new node. QueryVCDPropertyInterfaces looks as follows:

void CVCDPropertyTreeDlg::QueryVCDPropertyInterfaces( tIVCDPropertyElementPtr pElem, HTREEITEM hElem )
{
    CTreeCtrl* pTree = (CTreeCtrl*)GetDlgItem( IDC_VCDTREE );

    CWnd* pCtrl = 0;

    CString name;
    int imgIndex;

    tVCDPropertyInterfaceArray itfArray = pElem->getInterfaces();
    for( tVCDPropertyInterfaceArray::const_iterator i = itfArray.begin(); i != itfArray.end(); ++i )
    {
        GUID iid = (*i)->getInterfaceID();
        if( iid == IID_IVCDRangeProperty )
        {
            name = "Range";
            imgIndex = 3;
        }
        else if( iid == IID_IVCDSwitchProperty )
        {
            name = "Switch";
            imgIndex = 4;
        }
        else if( iid == IID_IVCDButtonProperty )
        {
            name = "Button";
            imgIndex = 5;
        }
        else if( iid == IID_IVCDMapStringsProperty )
        {
            name = "MapStrings";
            imgIndex = 6;
        }
        else if( iid == IID_IVCDAbsoluteValueProperty )
        {
            name = "AbsoluteValue";
            imgIndex = 3;
        }
        else
        {
            name = "Unknown Interface";
            imgIndex = 3;
        }

        // Insert the interface item
        HTREEITEM hItf = pTree->InsertItem( name, imgIndex, imgIndex, hElem );

        // Store the interface path within the vector.
        CInterfacePath ItfPath;

        ItfPath.itemID = (*i)->getParent()->getParent()->getItemID();
        ItfPath.elementID = (*i)->getParent()->getElementID();
        ItfPath.interfaceID = (*i)->getInterfaceID();

        m_InterfaceVector.push_back( ItfPath );

        // Store the position in the vector as node data
        pTree->SetItemData( hItf, m_InterfaceVector.size()-1 );
    }
}

QueryVCDPropertyInterfaces iterates through all available interfaces of an element. For each interface, it creates a new node. Each node that represents an interface is a child of the node which represents the IVCDPropertyElement to which this IVCDPropertyInterface belongs. The if..then..else block determines the appropriate graphical tree element for the node and sets its name depending on the type of the interface. The name is then used to label the node. Now that we have an interface node, the interface path is created. An interface path consists of an itemID, an elementID and an interfaceID. The interfaceID can be retrieved directly from the current interface. The elementID must be retrieved from the parent of the interface. The parent is retrieved with IVCDPropertyInterface::getParent. Finally, the itemID is retrieved from the parent of the parent of the interface. As mentioned above, we use the container class CInterfacePath to store the interface path in a vector. The index in the vector is stored in the node with SetItemData. The interface node makes up a leaf of the tree.

Accessing and Manipulating a VCDProperty

Now that the tree is build up, we, of course, want to access the properties. To do this, add an SelChanged event for the tree view and insert the following code:

void CVCDPropertyTreeDlg::OnSelchangedVcdtree(NMHDR* pNMHDR, LRESULT* pResult)
{
    NM_TREEVIEW* pNMTreeView = (NM_TREEVIEW*)pNMHDR;
    CTreeCtrl* pTree = (CTreeCtrl*)GetDlgItem( IDC_VCDTREE );

    DWORD index = pTree->GetItemData( pNMTreeView->itemNew.hItem );

    // If the index equals MAXDWORD, the node is not a leaf.
    if( index == MAXDWORD )
        return;

    // Destroy the buddy window
    m_pBuddy = 0;

    // Retrieve the interface path
    CInterfacePath ItfPath = m_InterfaceVector.at( index );

    // Get a pointer to the interface specified by itemID, elementID and interfaceID.
    tIVCDPropertyInterfacePtr pItf = m_Grabber.getAvailableVCDProperties()->findInterface( ItfPath.itemID,
                                                                                ItfPath.elementID,
                                                                                ItfPath.interfaceID );

    // Build an appropriate text for the frame.
    CString frameText( pItf->getParent()->getParent()->getName().c_str() );

    // Test whether the interface is IVCDRangeProperty
    if( ItfPath.interfaceID == IID_IVCDRangeProperty )
    {
        // Acquire the interface pointer
        tIVCDRangePropertyPtr pRangeItf;
        pItf->QueryInterface( pRangeItf );
        if( pRangeItf == 0 )
            return;

        // Create a range slider control
        CVCDRangeSlider* pSlider = new CVCDRangeSlider();
        pSlider->Create( WS_CHILD|TBS_NOTICKS, CRect( 300, 450, 500, 480 ), this, 0 );

        // Create a buddy window to display the value text
        CStatic* pBuddy = new CStatic();
        pBuddy->Create( TEXT("0"), WS_VISIBLE|WS_CHILD|SS_CENTERIMAGE, CRect( 0, 0, 100, 23 ), this );
        pBuddy->SetFont( GetDlgItem( IDC_VCDTREE )->GetFont() );
        pSlider->SetBuddy( pBuddy, FALSE );
        m_pBuddy = pBuddy;

        pSlider->setupCtrl( pRangeItf );

        m_pCurrentControl = pSlider;

        // Add the element name to the frame text
        frameText += TEXT(": ");
        frameText += pItf->getParent()->getName().c_str();
    }
    // Test whether the interface is IVCDSwitchProperty
    else if( ItfPath.interfaceID == IID_IVCDSwitchProperty )
    {
        // Acquire the interface pointer
        tIVCDSwitchPropertyPtr pSwitchItf;
        pItf->QueryInterface( pSwitchItf );
        if( pSwitchItf == 0 )
            return;

        // Create a switch check control
        CVCDSwitchCheck* pButton = new CVCDSwitchCheck();
        pButton->Create( CString( pItf->getParent()->getName().c_str() ), WS_CHILD|BS_CHECKBOX, CRect( 300, 450, 500, 480 ), this, 0 );
        pButton->SetFont( GetDlgItem( IDC_VCDTREE )->GetFont() );
        pButton->setupCtrl( pSwitchItf, 0 );

        m_pCurrentControl = pButton;
    }
    // Test whether the interface is IVCDButtonProperty
    else if( ItfPath.interfaceID == IID_IVCDButtonProperty )
    {
        // Acquire the interface pointer
        tIVCDButtonPropertyPtr pButtonItf;
        pItf->QueryInterface( pButtonItf );
        if( pButtonItf == 0 )
            return;

        // Create a button control
        CVCDButtonButton* pButton = new CVCDButtonButton();
        pButton->Create( CString( pItf->getParent()->getName().c_str() ), WS_CHILD|BS_PUSHBUTTON, CRect( 300, 450, 380, 474 ), this, 0 );
        pButton->SetFont( GetDlgItem( IDC_VCDTREE )->GetFont() );
        pButton->setupCtrl( pButtonItf, 0 );

        m_pCurrentControl = pButton;
    }
    // Test whether the interface is IVCDMapStringsProperty
    else if( ItfPath.interfaceID == IID_IVCDMapStringsProperty )
    {
        // Acquire the interface pointer
        tIVCDMapStringsPropertyPtr pMapStringsItf;
        pItf->QueryInterface( pMapStringsItf );
        if( pMapStringsItf == 0 )
            return;

        // Create a combo control
        CVCDMapStringsCombo* pCombo = new CVCDMapStringsCombo();
        pCombo->Create( WS_CHILD|CBS_DROPDOWNLIST|WS_VSCROLL, CRect( 300, 450, 500, 550 ), this, 0 );
        pCombo->SetFont( GetDlgItem( IDC_VCDTREE )->GetFont() );
        pCombo->setupCtrl( pMapStringsItf );

        m_pCurrentControl = pCombo;

        // Add the element name to the frame text
        frameText += TEXT(": ");
        frameText += pItf->getParent()->getName().c_str();
    }
    // Test whether the interface is IVCDAbsoluteValueProperty
    else if( ItfPath.interfaceID == IID_IVCDAbsoluteValueProperty )
    {
        // Acquire the interface pointer
        tIVCDAbsoluteValuePropertyPtr pAbsValItf;
        pItf->QueryInterface( pAbsValItf );
        if( pAbsValItf == 0 )
            return;

        // Create a absolute value slider control
        CVCDAbsValSlider* pSlider = new CVCDAbsValSlider();
        pSlider->Create( WS_CHILD|TBS_NOTICKS, CRect( 300, 450, 500, 480 ), this, 0 );

        CStatic* pBuddy = new CStatic();
        pBuddy->Create( TEXT("0"), WS_VISIBLE|WS_CHILD|SS_CENTERIMAGE, CRect( 0, 0, 100, 23 ), this );
        pBuddy->SetFont( GetDlgItem( IDC_VCDTREE )->GetFont() );
        pSlider->SetBuddy( pBuddy, FALSE );
        m_pBuddy = pBuddy;

        pSlider->setupCtrl( pAbsValItf );

        m_pCurrentControl = pSlider;

        // Add the element name to the frame text
        frameText += TEXT(": ");
        frameText += pItf->getParent()->getName().c_str();
    }

    // Show the control in case it was (initially) hidden
    if( m_pCurrentControl != 0 )
        m_pCurrentControl->ShowWindow( SW_SHOW );

    // Set the frame title
    GetDlgItem( IDC_CTRL_FRAME )->SetWindowText( frameText );

    *pResult = 0;
}

If you now click a node in the tree view, the method above is called. If a leaf is clicked, the interface path is retrieved from the vector and the appropriate interface is returned by the findInterface method. Next, the type of interface that we received is checked, so that the correct control can be initialized and displayed. This is done in the if..then..else block, where the appropriate control is dynamically created.

<< Programmer's Guide


Filter Inspector

This example demonstrates how to use frame filters to perform basic image processing.

It shows, how to:

  • Enumerate the available frame filters.
  • Create frame filter instances.
  • Set a frame filter to perform image processing on live video.

The example is located in the %TOPLEVEL%\samples\vc71\Filter Inspector directory of the IC Imaging Control installation. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6.

Initialization

In the OnInitDialog method, the Grabber is initialized. The most important part here is to disable graphic overlay completely, by calling Grabber::setOverlayBitmapPathPosition, thus avoiding interference with the possible color formats of the frame filters. After that, the device selection dialog is displayed and live mode is started.

// Set the live video output window to the static IDC_DISPLAY.
m_Grabber.setHWND( GetDlgItem( IDC_DISPLAY )->GetSafeHwnd() );

// Disable all overlay bitmaps.
m_Grabber.setOverlayBitmapPathPosition( ePP_NONE );

// Show the device page to let the user select a video capture device.
m_Grabber.showDevicePage( m_hWnd );

// When a video capture device was selected, start live mode.
if( m_Grabber.isDevValid() )
{
    Startlive();
}

Enumerating Available Frame Filters

To obtain a list of available frame filters, call FilterLoader::getAvailableFrameFilters, which returns a vector of FilterInfo structures. The parameter of this static method checks which kind of filters should be loaded. You have the choice between generic filters ( eFC_GENERIC ) that should work in all environments and filters that were designed to work only in certain programs ( eFC_INTERNAL ). The latter kind of filter may not work properly, if not initialized correctly. In this example, we use eFC_ALL to load all available filters:

// Get a list with all available frame filters.
std::vector<FilterInfo> filterInfos = FilterLoader::getAvailableFrameFilters( eFC_ALL );

Now we want to fill a list box with the names of the files in which the filters have been found. To do that, we look at each filter and add its module name to the list box, while filling FilterFileList with the module paths of the filters. The module names are not added when the module path is already in the vector:

CListBox* pFilesList = (CListBox*)GetDlgItem( IDC_FILES );

// In this loop, we create a list with all files that contain filters.
for( size_t i = 0; i < filterInfos.size(); ++i )
{
    // For each filter, see if its module was already added to the list.
    // If not, add it, otherwise skip it.
    bool bFound = false;
    for( size_t j = 0; j < m_FilterFileList.size(); ++j )
    {
        if( m_FilterFileList[j] == filterInfos[i].getModulePath() )
        {
            bFound = true;
            break;
        }
    }

    if( !bFound )
    {
        // Save the filter module path in a list to access it when the
        // user selects the list entry.
        m_FilterFileList.push_back( filterInfos[i].getModulePath() );

        // Add the filter file name to the list.
        pFilesList->AddString( filterInfos[i].getModuleNameW().c_str() );
    }
}

In the event handler that is called when the user selects a filter module name from the list box, a second list box is filled with the names of the filters in that module:

void CFilterInspectorDlg::OnLbnSelchangeFiles()
{
    CListBox* pFilesList = (CListBox*)GetDlgItem( IDC_FILES );
    CListBox* pFilterList = (CListBox*)GetDlgItem( IDC_FILTERS );

    // Get a list with all available frame filters.
    std::vector<FilterInfo> filterInfos = FilterLoader::getAvailableFrameFilters( eFC_ALL );

    // Get the index of the currently selected filter file.
    int sel = pFilesList->GetCurSel();
    if( sel != -1 )
    {
        // If a filter file was selected, fill the filter list with the filter of that file.

        // First, clear the list.
        pFilterList->ResetContent();

        // Add all filters of the selected file to the list.
        int n = 0;
        for( int i = 0; i < int(filterInfos.size()); ++i )
        {
            FilterInfo& fi = filterInfos[i];

            // Check whether the filter's module matches the selected file.
            if( m_FilterFileList[sel] == fi.getModulePath() )
            {
                pFilterList->AddString( fi.getFilterNameW().c_str() );

                // Save the index of the filter in the list of the
                // available filters in the list item's item data.
                pFilterList->SetItemData( n++, i );
            }
        }
    }
}

In a loop, the filter module paths of all filters are compared to the path of the selected file. If the filter comes from the selected file, its name is added to the filter list box. The index of the filter in the original filter list that was retrieved from FilterLoader::getAvailableFrameFilters is stored in the list box item data by calling CListBox::SetItemData, thus allowing to find the filter when the user clicks the item.

Creating Frame Filter Instances

When the user selects a filter from the filter list, the item data of the selected item is read using CListBox::GetItemData. Because we previously stored the filter's index in the list of available filters in the item data, we can use this number now to select the FilterInfo in the filterInfos list:

// We previously stored the index of the filter in the list of available
// filters in the item data of the list item. Read it back.
int filterIndex = (int)pFilterList->GetItemData( sel );

// Filters can only be set when live mode is stopped.
bool bIsLive = m_Grabber.isLive();
Stoplive();

// Create the new filter instance.
m_pFilter = FilterLoader::createFilter( filterInfos[filterIndex] );

The frame filter instance is created by calling FilterLoader::createFilter with the FilterInfo structure as parameter.

Set the Frame Filter

To activate the frame filter, it has to be registered at the grabber object. Use Grabber::setDeviceFrameFilters to set the frame filter to transform the image data coming from the video capture device.

// Set the filter as device frame filter.
m_Grabber.setDeviceFrameFilters( m_pFilter.get() );

// Restart live mode, if possible.
if( m_Grabber.isDevValid() && bIsLive )
{
    Startlive();
}

// Enable the "Dialog..."-Button if the filter has a built-in dialog.
GetDlgItem( IDC_DIALOG )->EnableWindow( m_pFilter->hasDialog() );

Live mode has to be stopped to set a frame filter.

Handling Pointers to Filter Instances

The pointer to the frame filter instance is stored in a member variable of the dialog class, so that the filter instance exists after the event handler has been executed. As the pointer to the frame filter instance is a smart_com, the instance would be destroyed once a local pointer variable runs out of scope.

Live mode has to be stopped before the new filter instance is assigned to the member variable m_pFilter, because the assignment destroys the filter instance it previously pointed to.

<< Programmer's Guide


Writing a Frame Filter: Binarization

This example demonstrates how to create frame filters to apply binarization to live video.

It shows, how to:

  • Derive a class from FrameFilterImpl and implement the pure virtual methods.
  • Set the frame filter to affect only the live display.
  • Alter frame filter parameters.

The example is located in the %TOPLEVEL%\samples\vc71\Binarization directory of the IC Imaging Control installation. Similarly, you can find a VC6 version in the directory %TOPLEVEL%\Samples\VC6.

Creating a Frame Filter

All frame filter implementations have to be derived from FrameFilterImpl or FrameUpdateFilterImpl. As the binarization changes every pixel of the image, it is better to implement a transform filter rather than an update filter for this purpose. FrameFilterImpl is a class template that expects the name of derived class as the template parameter:

class CBinarizationFilter
    :    public DShowLib::FrameFilterImpl<CBinarizationFilter>
{
public:
    CBinarizationFilter();

Every class derived from FrameFilterImpl has to have a static method getStaticFilterInfo that returns a FilterInfo structure, containing information about the filter:

public:
    // FrameFilterImpl implementation
    static    DShowLib::FilterInfo getStaticFilterInfo();

To create a working frame filter, the methods getSupportedInputTypes, getTransformOutputTypes and transform need to be implemented:

public:
    // IFrameFilter implementation
    virtual    void getSupportedInputTypes( DShowLib::FrameTypeInfoArray& arr ) const;
    virtual    bool getTransformOutputTypes( const DShowLib::FrameTypeInfo& in_type,
                                          DShowLib::FrameTypeInfoArray& out_types ) const;
    virtual    bool transform( const DShowLib::IFrame& src, DShowLib::IFrame& dest );

Two member variables control the binarization process. Two methods allow these member variables to be altered from the application that uses the filter:

public:
    // Enables or disabled binarizarion
    void    enable( bool bEnable );
    // Sets the threshold for the binarization
    void    setThreshold( int th );

private:
    bool    m_bEnabled;
    int        m_threshold;
};

Implementing the Frame Filter

In the constructor of CBinarizationFilter, the member variables are initialized to default values:

CBinarizationFilter::CBinarizationFilter()
    :    m_bEnabled( false ),
        m_threshold( 127 )
{
}

The getStaticFilterInfo implementation fills a FilterInfo structure with a filter name. The filterClass member is set to eFC_INTERNAL, because the filter cannot be used by generic applications such as the Filter Inspector:

FilterInfo CBinarizationFilter::getStaticFilterInfo()
{
    // Return a filter name and declare the filter as eFC_INTERNAL.
    FilterInfo fi = { L"Binarization", L"", eFC_INTERNAL };
    return fi;
}

In the getSupportedInputTypes method, a FrameTypeInfoArray is filled with frame types that the frame filter accepts as inputs. To keep things simple, only 8-bit formats may be used: eRGB8 and eY800. When the video format of the video capture device differs from this, the image data is automatically converted before it is presented to the frame filter.

void CBinarizationFilter::getSupportedInputTypes( DShowLib::FrameTypeInfoArray& arr ) const
{
    // This filter works for 8-bit-gray images only
    arr.push_back( eRGB8 );
    arr.push_back( eY800 );
}

The getTransformOutputTypes method fills the FrameTypeInfoArray out_types with frame types that the filter can produce from a specified input frame type. Because the binarization filter does not change the frame type or size, we just insert the input type into that array:

bool CBinarizationFilter::getTransformOutputTypes( const DShowLib::FrameTypeInfo& in_type,
                                                   DShowLib::FrameTypeInfoArray& out_types ) const
{
    // We don't change the image type, output = input
    out_types.push_back( in_type );

    return true;
}

The transform method is called for every frame. It is responsible to perform the binarization, according to the current settings.

Because the transform method runs in a different thread from the user interface, access to the member variables m_bEnabled and m_threshold from parallel calls to setThreshold or enable has to be protected.

First, IFrameFilter::beginParamTransfer is called. Internally, this method enters a critical section. When a user of the frame filter wants to set parameters, he/she has to call beginParamTransfer, too. IFrameFilter::endParamTransfer leaves the critical section. The values of the member variables are copied to local stack variables, so that they remain constant for the whole transformation.

The binarization itself is a simple operation: Compare each pixel's gray value to the threshold. If the gray value is greater than the threshold, set the pixel to the maximum gray value, otherwise set it to zero.

bool CBinarizationFilter::transform( const DShowLib::IFrame& src, DShowLib::IFrame& dest )
{
    // Check whether the destination frame is available
    if( dest.getPtr() == 0 ) return false;

    BYTE* pIn = src.getPtr();
    BYTE* pOut = dest.getPtr();

    // Copy the member variables to the function's stack, to protect them from being
    // overwritten by parallel calls to setThreshold() etc.
    //
    // beginParamTransfer/endParamTransfer makes sure that the values from various
    // member variables are consistent, because the user of this filter must enclose
    // writing parameter access into beginParamTransfer/endParamTransfer, too.
    beginParamTransfer();
    bool enabled = m_bEnabled;
    int threshold = m_threshold;
    endParamTransfer();

    // Check whether binarization is enabled
    if( m_bEnabled )
    {
        // For each byte in the input buffer, check whether it is greater or
        // equal to the threshold.
        int bufferSize = src.getFrameType().buffersize;
        while( bufferSize-- > 0 )
        {
            if( *pIn++ >= threshold )
            {
                *pOut++ = 255;
            }
            else
            {
                *pOut++ = 0;
            }
        }
    }
    else
    {
        // Binarization is disabled: Copy the image data without modifying it.
        memcpy( pOut, pIn, src.getFrameType().buffersize );
    }

    return true;
}

The methods enable and setThreshold change the filter behavior:

void CBinarizationFilter::enable( bool bEnable )
{
    m_bEnabled = bEnable;
}

void CBinarizationFilter::setThreshold( int th )
{
    m_threshold = th;
}

Using the Frame Filter

We create an instance of CBinarizationFilter as a member variable of the dialog class: m_binarizationFilter.

When the Grabber object is initialized, Grabber::setDeviceFrameFilters is called to set our frame filter:

// Set the live video output window
m_Grabber.setHWND( GetDlgItem( IDC_DISPLAY )->GetSafeHwnd() );

// Disable overlay bitmap
m_Grabber.setOverlayBitmapPathPosition( ePP_NONE );

// Set the binarization filter as device frame filter
m_Grabber.setDeviceFrameFilters( &m_binarizationFilter );

// Show device settings dialog
m_Grabber.showDevicePage( GetSafeHwnd() );

// If a device was selected, start live mode.
if( m_Grabber.isDevValid() )
{
    m_Grabber.startLive();
}

When live mode is started, all images coming from the video capture device are transformed by our frame filter.

Accessing Frame Filter Parameters

In the event handler for the check box that enables or disables the binarization, CBinarizationFilter::enable is called.

All calls to methods modifying filter parameters have to be enclosed by IFrameFilter::beginParamTransfer and IFrameFilter::endParamTransfer.

void CBinarizationDlg::OnBnClickedBinarizeEnable()
{
    // Read current checked state
    bool bEnable = m_BinarizeEnable.GetCheck() == BST_CHECKED;

    // Enclose frame filter parameter access into beginParamTransfer/endParamTransfer,
    // to get consistent values.
    m_binarizationFilter.beginParamTransfer();
    m_binarizationFilter.enable( bEnable );
    m_binarizationFilter.endParamTransfer();

    // Set threshold slider availability
    m_BinarizeThreshold.EnableWindow( bEnable );
    m_BinarizeThresholdStatic.EnableWindow( bEnable );
}

In the event handler for the threshold slider, CBinarizationFilter::setThreshold is called.

This call also has to be enclosed by IFrameFilter::beginParamTransfer and IFrameFilter::endParamTransfer.

void CBinarizationDlg::OnHScroll(UINT nSBCode, UINT nPos, CScrollBar* pScrollBar)
{
    // Read current slider position
    int th = m_BinarizeThreshold.GetPos();

    // Enclose frame filter parameter access into beginParamTransfer/endParamTransfer,
    // to get consistent values.
    m_binarizationFilter.beginParamTransfer();
    m_binarizationFilter.setThreshold( th );
    m_binarizationFilter.endParamTransfer();

    // Display the threshold in the static window.
    char buf[20];
    m_BinarizeThresholdStatic.SetWindowText( itoa( th, buf, 10 ) );

    CDialog::OnHScroll(nSBCode, nPos, pScrollBar);
}

<< Programmer's Guide


Creating a Filter Module

This example demonstrates how to create a filter module, containing frame filter implementations.

This article shows you how to:

  • Setup a Visual Studio project to create a filter module.
  • Create a frame filter class that can be loaded from a filter module.
  • Add a dialog to the frame filter.

You can find a Visual Studio project with a working filter module in the samples\vc71\DemoFilters directory of the IC Imaging Control installation. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6.

In this article, the filter that was created in Writing a Frame Filter: Binarization will be used. For information on how a frame filter is implemented, please take a look at this article.

Setup a Visual Studio project for a frame filter module

If you are using Visual C++, you can use the Frame Filter Module Wizard to create a frame filter module project with a few mouse clicks.

However, if you would like to know how to create such a project by hand, or you are using a different version of Visual C++, here is what to do:

Create a new project with the project template Visual C++ Projects -> Win32 -> Win32 Project. Select DLL as application type.

Setup compiler settings, as described for applications at First Steps VC.NET: Project Properties or First Steps VC6: Project Settings.

Name the output file of the project <name>.ftf. The filter loader only loads modules with this file extension.

Open the file stdafx.h and enter the following lines of code:

#include <tisudshl.h>
#include <FilterFactory.h>

Besides the usual tisudshl.h, you also have to include FilterFactory.h.

Implement the Frame Filter Class

We will now extend the binarization filter from Writing a Frame Filter: Binarization to work inside a filter module.

A generic application that loads a filter does now know the filter's interface (like the CBinarizationFilter::enable or CBinarizationFilter::setThreshold methods). To be able to set filter parameters from that program, there is a generic filter interface implemented in IFrameFilter and FrameFilterImpl. The application can use IFrameFilter::getAvailableParameters to find out which parameters a filter supports and then call IFrameFilter::setParameter to alter parameter values.

To make the binarization filter support such parameters, it has to use FrameFilterImpl::addBoolParam or one of the other parameter registration methods. Extend the constructor of CBinarizationFilter to register two parameters:

CBinarizationFilter::CBinarizationFilter()
    :    m_bEnabled( false ),
        m_threshold( 127 )
{
    // Add 'enable' parameter to enable or disable the binarization
    addBoolParam( "enable", &CBinarizationFilter::getEnable, &CBinarizationFilter::setEnable );

    // Add 'threshold' parameter to set the binarization threshold
    addLongParam( "threshold", &CBinarizationFilter::getThreshold, &CBinarizationFilter::setThreshold );
}

The first parameter of the registration functions is the name by which an application can access the parameter. The second and third parameter are names of member functions of CBinarizationFilter. Replace the old enable and setThreshold methods by the following code:

public:
    // Enables or disables binarizarion
    DShowLib::tFilterError getEnable( bool& bEnable );
    DShowLib::tFilterError setEnable( bool bEnable );

    // Sets the threshold for the binarization
    DShowLib::tFilterError getThreshold( long& threshold );
    DShowLib::tFilterError setThreshold( long threshold );

private:
    bool    m_bEnabled;
    int        m_threshold;
};

These methods will be called when a program that loaded the filter calls setParameter( "enable", true ) or setParameter( "threshold", 100 ).

Their implementation is very simple:

/*
 *    Returns the 'enabled' state of the binarization
 */
tFilterError CBinarizationFilter::getEnable( bool& bEnable )
{
    bEnable = m_bEnabled;
    return eNO_ERROR;
}

/*
 *    Sets the 'enabled' state of the binarization
 */
tFilterError CBinarizationFilter::setEnable( bool bEnable )
{
    m_bEnabled = bEnable;
    return eNO_ERROR;
}

/*
 *    Returns the binarization threshold
 */
tFilterError CBinarizationFilter::getThreshold( long& threshold )
{
    threshold = m_threshold;
    return eNO_ERROR;
}

/*
 *    Sets the binarization threshold
 */
tFilterError CBinarizationFilter::setThreshold( long threshold )
{
    m_threshold = threshold;
    return eNO_ERROR;
}

We now created a filter that should work with generic applications. Change the getStaticFilterInfo method to flag the filter as eFC_GENERIC:

FilterInfo CBinarizationFilter::getStaticFilterInfo()
{
    // Return a filter name and declare the filter as eFC_GENERIC.
    FilterInfo fi = { L"Demo_Binarization", L"", eFC_GENERIC };
    return fi;
}

Registering the Frame Filter Class

Go to the main file of your filter module and add a FILTERDLL_REGISTER_FILTER-line for the name of your filter class inside the FILTERDLL_BEGIN_EXPORT- FILTERDLL_END_EXPORT-section.

FILTERDLL_BEGIN_EXPORT()
    FILTERDLL_REGISTER_FILTER(CRotateTransform)
    FILTERDLL_REGISTER_FILTER(CDeNoiseTransform)
    FILTERDLL_REGISTER_FILTER(CSnapFilter)
    FILTERDLL_REGISTER_FILTER(CBinarizationFilter)
FILTERDLL_END_EXPORT()

Adding a dialog to the frame filter

To add a user interface to your filter, you can override the IFrameFilter::hasDialog and IFrameFilter::callDialog methods.

The default implementation of hasDialog returns false, so we need to change it to true:

bool    CBinarizationFilter::hasDialog() const
{
    return true;
}

In the callDialog implementation, we save the current settings of the filter, using IFrameFilter::getSettings and display a dialog box allowing the user to change the filter's parameters. If the user exists the dialog by clicking the cancel button, the filter setting are restored to the saved values.

bool    CBinarizationFilter::callDialog( HWND hParent )
{
    // Save settings
    std::string data = getSettings();

    // Display modal dialog.
    // Pass the pointer to this instance to WM_INITDIALOG.
    INT_PTR result = DialogBoxParam( g_hInst,
                                    MAKEINTRESOURCE(IDD_BINARIZATION_CONFIG),
                                    hParent,
                                    BinarizationConfigDlgProc,
                                    (LPARAM)this );

    // When the user clicked 'cancel' restore settings
    if( result == IDCANCEL )
    {
        setSettings( data );
    }

    // Return true when the dialog was displayed.
    return result >= 1;
}

<< Programmer's Guide


Technical Articles

Complete list of all technical articles.

Concepts and Components

This chapter describes the components that make up IC Imaging Control and the basic concepts behind the library.

Frame Filters

With frame filters, a versatile and powerful way to manipulate image data is introduced. Besides other features, frame filters can be used to change or convert the video format of the image stream, implement image processing and control which frames are processed.

Debayering

Certain color cameras output image data in raw format, which is called Bayer format. This chapter discusses what is involved to transform this raw data into a real color format that can be displayed as a color image.

VCDProperties

VCD Properties provide a generic, hardware independent and extendable way to control the settings of a video capture device.

DCAMprop DLL

The DCAM Prop DLL that provided access to special DCAM properties in version 1.41 is no longer need, as these special properties can now be accessed and manipulated using the new VCD properties. This document describes alternatives for all functions and procedures of the DCAM Prop DLL.

<< IC Imaging Control Class Library User's Guide


Concepts and Components

This chapter describes the components that make up IC Imaging Control and the basic concepts behind the library.

Introduction

The IC Imaging Control class library is an API that covers all aspects of DirectShow that are related to managing, controlling and accessing imaging devices and image data. It simplifies the usage of DirectShow by maintaining its hardware independently. The abstraction implemented by the class library addresses all programmers who are familiar with frame grabbers. In other words: IC Imaging Control lets DirectShow look like a frame grabber.

Basic Components

The idea behind IC Imaging Control is to build something similar to a frame grabber and thus the main class is called Grabber. Typically, frame grabber APIs are made up of a collection of functions that control the inputs, video formats, and the grabbing process. This is the reason why the Grabber class provides all this functionality as one "fat interface". There are additional classes that provide functionality to enumerate and specify devices ( VideoCaptureDeviceItem ), video formats ( VideoFormatItem ), video norms ( VideoNormItem ) and inputs ( AnalogChannelItem ). In contrast to most frame grabber APIs, IC Imaging Control provides:

  • A sink concept for creating image stream files ( MediaStreamSink, MediaStreamContainer ) including software compression ( Codec )
  • A sink concept for handling image buffers ( FrameHandlerSink ) with ring buffer management ( MemBufferCollection, MemBuffer ) including buffer locking and image data access through callbacks ( GrabberListener ).
  • Advanced display capabilities including scrolling and zooming that can be controlled using the Grabber class.

The image data is generated by the video capture device as consecutive frames that build an image stream running from the device to the sink. If the display is activated, the image stream is split, feeding the sink and the display. In this case, the image stream is a graph that looks like a "Y" and consists of the following segments:

  • Device Path: Segment between the device and the split point
  • Display Path: Segment between the split point and the display
  • Sink Path: Segment between the split point and the sink

While the figure above illustrates the flow of image data, the next figure shows the relationship between the image stream and the classes.

Advanced Components

IC Imaging Control provides generic access to device properties, multiple overlays and filter chains at different locations of the image stream:

  • Generic device properties: Although DirectShow allows device independent code to be written using the two defined sets of properties VideoProcAmp and CameraControl, this concept suffers from serious limitations. On the one hand, a lot of video capture devices provide more properties, than defined by DirectShow. On the other hand, the values that may be specified for a property do not have a meaning. With VCDProperties, IC Imaging Control provides a totally generic and extendable way to handle unknown properties and add a meaning to property values.
  • Multiple Overlays: The class OverlayBitmap implements an overlay that can be rendered on the image stream at three locations: device path, display path and sink path. Methods for drawing text and graphical elements, such as rectangles and lines, as well as callbacks for generating frame based overlays are provided.
  • Filter Chains: IC Imaging Control allows filters or filter chains to be inserted in the image stream at three locations: device path, display path and sink path. Filters are called frame filters and are used to change or convert the video format of the image stream, implement image processing and control which frames are processed. For details on frame filters, please refer to the section Frame Filters.

Performance

As described above, IC Imaging Control provides very powerful components to manipulate and control the acquisition and display of image streams. It is obvious that this functionality requires a certain overhead for internal management and processing. This may lead to the conclusion that IC Imaging Control is not suitable for high speed image processing application. This is absolutely not the case, as all features that make it so easy to build complex applications with IC Imaging Control may be switched off. For applications that require as much CPU time for image processing as possible, IC Imaging Control may be configured in a way that the overhead to process the image stream is comparable to a low level frame grabber or FireWire library. In order to reduce the internal overhead to a minimum, you have to:

  • Switch off the display: this will remove the display path completely from the image stream.
  • Prevent automatic color space conversion: by specifying the same video format for the device and the sink.
  • Switching off all overlays.
  • Do not use the ring buffer: by inserting one frame filter in the sink path that will implement the image processing or interface a third party image processing library instead of sending frames to the sink.
  • Do not insert additional frame filters in the device path or in the sink path.

Doing so guarantees that the image data is not modified or copied by IC Imaging Control, nor DirectShow. The figure below shows the layout of the image stream for this configuration.

<< Technical Articles


Frame Filters

With frame filters, a versatile and powerful way to manipulate image data is introduced. Besides other features, frame filters can be used to change or convert the video format of the image stream, implement image processing and control which frames are processed.

Introduction

In contrast to other DirectShow libraries, the frame filters of IC Imaging Control are not DirectShow filters. But they are executed in the context of a DirectShow thread that processes the image stream. This saves the programmer the hassle of creating a DirectShow filter module, registering it and defining interfaces for the parameters. Frame filters are implemented by deriving from the class FrameFilterImpl or FrameUpdateFilterImpl. Easy access to the parameters of a frame filter is provided by the class IFrameFilter. On the one hand, frame filters may be implemented as part of a filter module. On the other hand, a frame filter can be created directly in an application, if its class is known. In order to simplify the creation of frame filter classes and frame filter modules, there are Project Wizards for Visual Studio .NET. With theses wizards, creating a filter is done with just a few mouse clicks. Frame filters are basically far easier to implement and to use as DirectShow filters by providing the same performance with regard to image processing.

Filter Categories

Frame filters open the door to a vast number of new IC Imaging Control based applications. In order to show you what is possible with this new concept, we discuss categories of tasks that can be implemented with frames filters. For some of these tasks, frame filters are shipped with IC Imaging Control.

Gate:
Gate filters drop unwanted frames based on image analysis or other information like the frame count or time stamps.
Color Space Conversion:
All kinds of transformations from one color format to another fall in to this category. In addition, the reduction of the pixel depth, e.g. extracting the 8 most significant bits out of a 10 or 12 bit monochrome format is regarded as a color space conversion. The reduction of the pixel depth is used to display a 10 or 12 bit monochrome image. A good example for a color space conversion is the DeBayer Filter contained in stdfilters.ftf. It converts color raw data in Bayer format to RGB.
ROI:
Filters in this category allow a Region Of Interest to be cropped out of an image stream. The ROI Filter that is contained in stdfilters.ftf implements this functionality.
Rotation:
This category includes rotatation and flipping. The Rotate Flip Filter that is contained in stdfilters.ftf provides rotation by 90°, 180° and 270°, aswell as flipping on the horizontal and vertical axis. There is a filter in the DemoFilter.ftf that provides rotation by any angle, but this filter is a demo implementation and very slow.
Scaling:
Scaling up and down may be necessary to match a predefined display size or to save disk space for surveillance applications.
Sink:
Sink filters are consumers. They process the image stream in their transform method completely and do not send frames to the IC Imaging Control sink. If you want to use professional high performance codecs, you would inplement a sink filter in order to interface the codec's API. This approach is necessary because most professional codecs come as a DLL instead of a DirectShow codec. These codecs provides functionality to compress image data and write it to a file at the same time, which makes a sink obsolete. Of course, you could use the MembufferCollection of a FrameHandlerSink to access the image data and send it to the codec's API. In this case, the image data would have been copied by the sink to the MembufferCollection which is not the case, if the codec is interfaced using a frame filter. In other words, the sink filter approach saves one copy operation per frame, which can increase the performance significantly, especially if large frames are processed.
Extraction:
Extraction filters take specific frames out of the image stream and apply processing on them, e.g. saving them to disk as image files. The image stream itself remains unchanged and is sent further to the sink. Such a filter allows specific images to be saved uncompressed, while a MediaStreamSink generates a compressed video file.
Image Processing:
All image processing functions that produce one image as output can be implemented easily by a frame filter. For functions that produce more than one image, special concepts have to be developed. One possible concept would be to write the output images one after the other into the resulting image. If data other than images is generated by the function (e.g. data generated by a blob analysis), the application could read out this data by using filter parameters.
Buffer Format Conversion:
Most image processing libraries have a special internal image buffer format. Frame filters can be used to convert image buffers of the image stream to such a special image buffer format. Doing so, the elements in the ring buffer of the FrameHandlerSink contain data in the special format. Therefore, the data of these buffers may be passed directly to the according image processing library. This saves one copy step and, therefore, increases the preformance of the system.

Filter Types

There are 2 basic types of frame filters which will be discussed in the following. Both types provide the same way of parameter access and allow frames to be dropped explicitly.

Transform Filter
This type of frame filter has to be derived from FrameFilterImpl and allows to implement a conversion from one video format to another. This includes changing the color format (e.g. eY800 to RGB24), as well as changing the width and height.
Update Filter
This type of filter has to be derived from FrameUpdateFilterImpl. In contrast to a transform filter, an update filter may not change the color format nor the width and height. In order to speed up the processing of the image stream, an update filter can tell the framework that it will only read image data. This allows the framework to make certain optimizations. As a rule of thumb, update filters should only be used, if the image data is not changed at all or only a few pixels are modified. This is because the framework has to copy image buffers before it calls the FrameUpdateFilterImpl::updateInPlace method, if the filter has indicated that it will modify image data by returning true in the method FrameUpdateFilterImpl::modifiesData.

Using Existing Frame Filters

As described earlier, frame filters can be created directly in an application or loaded from a filter module. IC Imaging Control provides some filters in the module stdfilters.ftf. In order to obtain a list of the frame filters in all currently available filter modules, call the method FilterLoader::getAvailableFrameFilters. With the method FilterLoader::setLoadPath, an additional path for filter modules may be specified. A call to FilterLoader::createFilter creates an instance of a filter that was selected from the list of available filters. Now that we have a frame filter instance, we can insert it at three different locations in the image stream:

  • Behind the device: Grabber::setDeviceFrameFilters
  • In front of the display: Grabber::setDisplayFrameFilters
  • In front of the sink: MediaStreamSink::create, FrameHandlerSink::create

Please note that the same instance of a frame filter should not be used at more than one place in the image stream because its internal state may get inconsistent, especially if FrameFilterImpl::notifyStart and FrameFilterImpl::notifyStop are used. If it is necessary to insert the same filter at more than one location in the image stream, different instances of the frame filter should be used.

The internal data of a frame filter can be accessed through the parameter interface. With the method IFrameFilter::getParameter and IFrameFilter::setParameter, the following basic data types can be read from or written to the filter: bool, int, long float and std::string. A block of binary data can be exchanged with a frame filter by the methods IFrameFilter::getData and IFrameFilter::setData. Since the transform method of a filter is executed within a DirectShow thread, it is very important to synchronize external and internal access to the filter's data. Therefore, it is very important that a sequence of calls to the four methods mentioned above is preceded by a call to IFrameFilter::beginParamTransfer and is followed by a call to IFrameFilter::endParamTransfer:

pFrameFilter->beginParamTransfer();

// All calls to setParameter and getParameter here...

pFrameFilter->endParamTransfer();

If a frame filter is used by generic applications, such as the Filter Inspector, a dialog should be implemented that allows the parameters to be altered interactively. A frame filter indicates that it provides a parameter dialog by returning true in the method IFrameFilter::hasDialog. The dialog should be displayed when the method IFrameFilter::callDialog is called.

Every frame filter should provide the serialization of its internal data by implementing the methods IFrameFilter::getSettings and IFrameFilter::setSettings. The representation of the data has to be string compatible.

Creating a Frame Filter

For Visual Studio .NET, there is a wizard that allows a frame filter to be created with just a few mouse clicks. For details, please refer to Project Wizards. If you want to understand what the wizard is doing, a detailed step by step description can be found in the section: Writing a Frame Filter: Binarization.

Creating a Frame Filter Module

For Visual Studio .NET, there is a wizard that allows a frame filter module to be created with just a few mouse clicks. For details, please refer to Project Wizards. If you want to know what the wizard is doing, a detailed step by step description can be found in the section: Creating a Filter Module.

<< Technical Articles


Debayering

Certain color cameras output image data in raw format, which is called Bayer format. This chapter discusses what is involved to transform this raw data into a real color format that can be displayed as a color image.

Introduction

IC Imaging Control provides built-in functionality to debayer raw image data. There is a class DeBayerTransform that allows the debayering process to be controlled. The prerequisite to use this buit-in functionality is that the camera provides BY8 video formats that identify raw data in Bayer format. Some cameras provide only grayscale video formats (e.g. Y800, RGB8 etc.) but output color raw data when these formats are selected. This is possible because the color raw data in Bayer format consists of only one value per pixel (for detailed information about color raw data, please refer to the glossary of our website http://www.theimagingsource.com and search for Bayer camera ). In this case the debayering has to be done explicitly by using the DeBayer frame filter that can be loaded from the StdFilters.ftf module.

Automatic Debayering

If a BY8 video format is selected, IC Imaging Control applies debayering to the image data. Call Grabber::getDeBayerTransform to get the object that controls the debayering. The method DeBayerTransform::isActive can be used to determine whether automatic debayering is active. For details on the debayer object, please refer to the DeBayerTransform reference. In order to switch off automatic debayering for the sink, you have to specify a bayer format, e.g. eBY8 or MEDIASUBTYPE_BY_8 when creating the sink. The only way to switch off automatic debayering for the display is to insert a frame filter in the display path that accepts only a bayer format at the input and outputs a monochrome format. All this filter has to do is to copy the data from the input to the output without any changes. The complete implementation of the filter looks like this:

//Filter that allows unconverted, raw Bayer data to be displayed.
class CBayerRaw: public DShowLib::FrameFilterImpl<CBayerRaw>
{
public:
    CBayerRaw(){};
    ~CBayerRaw(){};
    static DShowLib::FilterInfo getStaticFilterInfo();

protected:
    virtual void    getSupportedInputTypes( FrameTypeInfoArray& arr ) const
    {
        // Specify Bayer raw data as the only input format that will be accepted.
        arr.addFrameType( MEDIASUBTYPE_BY8 );
    }

    virtual bool    getTransformOutputTypes( const FrameTypeInfo& in_type, FrameTypeInfoArray& out_types ) const
    {
        // Specify Y800 as the output format.
        out_types.addFrameType( eY800, in_type.dim.cx, in_type.dim.cy );
        return true;
    }

    virtual bool    transform( const IFrame& src, IFrame& dest )
    {
        // Just copy the image data without any changes.
        memcpy(dest.getPtr(),src.getPtr(), dest.getFrameType().buffersize);
        return true;
    }
};

DShowLib::FilterInfo CBayerRaw::getStaticFilterInfo()
{
    // Specify a symbolic name for the filter.
    static FilterInfo f = { L"BayerRaw" };
    return f;
}

If you now create an instance of the frame filter and insert it in the display path, you will see the raw image data in the live display:

// Create an instance of the frame filter.
CBayerRaw bayerRaw;

// Select a Bayer raw format.
m_Grabber.setVideoFormat("BY 8 (640x480)");

// Insert the Frame filter in the display path.
m_Grabber.setDisplayFrameFilters( &bayerRaw );

// ... do something here

// As soon as you are done, remove the frame filter from the display path.
m_Grabber.setDisplayFrameFilters( 0 );

// Now the filter object 'bayerRaw' may be destroyed.

For details on frame filters please refer to Frame Filters or Binarization.

Explicit Debayering

In oder to apply debayering explicitly to the image stream, you have to load the DeBayer frame filter from the StdFilter.ftf module, insert it in to the desired segment of the image stream and setup the filters parameters to match the Bayer pattern and the desired algorithm:

        // Load the DeBayer filter from the std_filters.ftf module.
#ifdef _DEBUG
        smart_com<IFrameFilter> pFilter = FilterLoader::createFilter( "DeBayer",   // Filter name.
                                                                      "stdfiltersd.ftf" ); // Module file.
#else
        smart_com<IFrameFilter> pFilter = FilterLoader::createFilter( "DeBayer",   // Filter name.
                                                                      "stdfilters.ftf" ); // Module file.
#endif

        pFilter->setParameter( "Start Pattern", 2 /* eGR */ );
        pFilter->setParameter( "Mode", 1 /* Bilinear */ );

        m_Grabber.setDeviceFrameFilters( pFilter.get() );

For details on frame filters please refer to Frame Filters.

<< Technical Articles


VCDProperties

VCD Properties provide a generic, hardware independent and extendable way to control the settings of a video capture device.

Introduction

DirectShow defines two sub sets of properties for video capture devices: VideoProcAmp and CameraControl. There is only one scalar data type ( long ) defined to represent a property value. Although this concept is an abstraction that allows you to write device independent code, there are two problems:

  • Some video capture devices provide more properties than the ones defined by DirectShow.
  • If the values of some properties, such as "exposure" are mapped to a "long", the meaning of the value gets lost. With regard to "exposure" the question is for example: which value corresponds to 1/20.000 sec? There is an approach in DirectShow to overcome this problem with negative values. The value -2, for example, means 2 to the power of -2, which is 1/4 seconds. These negative values are called "physical values" because they have a physical meaning (in this case in terms of seconds). There is one problem with this approach, it suffers from inaccurcy. There is no way to specify 1/3 second as an exposure time in "physical values". The same problem exist with the properties "iris" and "zoom".

On one hand, VCD properties provide interfaces that allow you to manipulate property values in terms of physical dimensions, such as seconds. On the other hand, these interfaces provide high precision. If you are happy with the simple and somehow restricted way of accessing properties through the methods Grabber::setProperty and Grabber::getProperty, you should use the helper class CSimplePropertyAccess. This class allows you to port old code that uses setProperty and getProperty with minimum effort. If this class is used, most benefits of VCD properties are not available.

Basic concepts

The basic idea behind VCD properties is a structured organisation. In order to understand this, we will have to consider the elements of which a property consists. First of all, a property has a name like "exposure". In addition, it contains elements such as the value and an automation state. Therefore, we may say that a property is an object that containes a name and a set of elements. This object is called IVCDPropertyItem. The elements are called IVCDPropertyElement and contain a set of interfaces that allow the element to be manipulated. The interfaces provide different access methods to the property. The interface IVCDRangeProperty, for example, provides access to the property that is equivalent to the property access of DirectShow. The IVCDAbsoluteValueProperty allows access to the property in terms of a physical dimension with high accuracy. After this consideraton, the structure of VCD property is clear: The property item contains property elements, which contain one or more interfaces. In order to be able to manipulate a property, you have to retrieve the appropriate item, element and interface. Please open the application "VCD Property Inspector" from the IC Imaging Control start menu in order to get an idea how the VCD properties are organized for your device.

Finding Property objects

First of all, we need a way to specify a property item, element or interface in order to be able to find it. There are GUIDs (Global Unique IDentifiers) for every property item, element and interface defined. They are listed under constants. These GUIDs should be used in the VCD property find methods. All property items that are supported by the currently active video capture device are contained in the IVCDPropertyItems collection. This collection provides methods for retrieving a property item, element or interface. They are called IVCDPropertyItems::findItem, IVCDPropertyItems::findElement and IVCDPropertyItems::findInterface. The object to be retrieved has to specified by a single GUID for findItem and a combination of GUIDs for the other two. In the following, we will call the GUID or combination of GUIDs that specifiy a property object, a GUID path.

Finding Interfaces

As described earlier, an interface is the object that actually allows data to be read from and to be writen a property. As described in the previous section, we will use the GUID path for the desired interface as a parameter to IVCDPropertyItems::findInterface to retrieve the interface. Before we do this, we will have to decide which interface we want to use. In case of an auto item ( IVCDPropertyElement, GUID: VCDElement_Auto) we will try to retrieve a swith interface ( IVCDSwitchProperty, GUID: IID_IVCDSwitchProperty) because a switch is the expected functionality of the auto item. In case of the value item - the actual value of the property - we have to search for the best interface. The best or most advanced interface is the absoulte value interface (refer to IVCDAbsoluteValueProperty for details).

As described at the beginning, the absolute values interface provides high accuracy and a meaning of the value it represents. The following code retrieves the absolute value interface for the value element of the exposure property item:

// Get supported property items.
tIVCDPropertyItemsPtr pItems = m_Grabber.getAvailableVCDProperties();

// Retrieve the absolute value interface for exposure.
tIVCDAbsoluteValuePropertyPtr pAbsVal = 0;
if( pItems->findInterfacePtr( VCDID_Exposure, VCDElement_Value, pAbsVal ) != 0 )
{
    // Interface successfully retrieved.
}
else
{
    // There is no absolute value interface for the value element
    // of the exposure property item.
}

If the absolute values interface does not exist for this property, we try to retrieve the map strings interface ( IVCDMapStringsProperty, GUID: IID_IVCDMapStringsProperty). It is not as accurate as the absolute values interface, but it provides a meaning for the value. The following code retrieves the map strings interface for the value element of the exposure property item:

// Get supported property items.
tIVCDPropertyItemsPtr pItems = m_Grabber.getAvailableVCDProperties();

// Retrieve the map strings interface for exposure.
tIVCDMapStringsPropertyPtr pMapStrings = 0;
if( pItems->findInterfacePtr( VCDID_Exposure, VCDElement_Value, pMapStrings ) != 0 )
{
    // Interface successfully retrieved.
}
else
{
    // There is no map strings interface for the value element
    // of the exposure property item.
}

If the map strings interface does not exist for this property, we try to retrieve the range interface ( IVCDRangeProperty, GUID: IID_IVCDRangeProperty). This interface does not provide a meaning for the value but it may provide more values than the map strings interface. The following code retrieves the range interface for the value element of the exposure property item:

// Get supported property items.
tIVCDPropertyItemsPtr pItems = m_Grabber.getAvailableVCDProperties();

// Retrieve the range interface for exposure.
tIVCDRangePropertyPtr pRange = 0;
if( pItems->findInterfacePtr( VCDID_Exposure, VCDElement_Value, pRange ) != 0 )
{
    // Interface successfully retrieved.
}
else
{
    // There is no range interface for the value element
    // of the exposure property item.
}

Using Interfaces

In the previous section, we learned how to get an interface. Now we will discuss how use them in order to get information about the property and manipulate the value. All interfaces provide the following properties:

  • Available: Indicates whether this interface is currently available. For example, interfaces for the trigger property item may not be available while the image stream is running.
  • ReadOnly: Indicates whether a value may be assigned to the Value of the interface.
  • Default: Is the default value.
  • Value: The Value of the interface.

The absolute values and the range interface provide properties to get information about the minimum, maximum value that can be assigned to the actual value. The absolute values interface provides additional information about the physical dimension of the value. The map strings interface provides a collection of strings which build the set of possible values the may be assigned to the actual value.

If the absolute values interface could be retrieved the code for accessing the interface looks as follows:

// AbsValItf is a valid absolute value interface for exposure.
if( pAbsVal->getAvailable() )
{
    // Set the current value to the average.
    pAbsVal->setValue( ( pAbsVal->getRangeMin() + pAbsVal->getRangeMax() ) / 2 );
}

If the map strings interface could be retrieved the code for accessing the interface looks as follows:

// pMapStrings is a valid map strings interface for exposure.
if( pMapStrings->getAvailable() )
{
    // Set the current value to the average.
    pMapStrings->setValue( ( pMapStrings->getRangeMin() + pMapStrings->getRangeMax() ) / 2 );
}

If only the range interface could be retrieved the code for accessing the interface looks as follows:

// pRange is a valid range interface for exposure.
if( pRange->getAvailable() )
{
    // Set the current value to the average.
    pRange->setValue( ( pRange->getRangeMin() + pRange->getRangeMax() ) / 2 );
}

Serialisation of property values

The IVCDPropertyItems collection provides a method called IVCDPropertyItems::save that serialize the current state of all VCD properties of the currently selected device into a string. The property values are stored in XML format. Therefore, it is easy to store the string in the registry or a file for later restore operations. Please note that the XML representation is not documented and will change without notice. The method for restoring all property values is called IVCDPropertyItems::load.

<< Technical Articles


DCAMprop DLL

The DCAM Prop DLL that provided access to special DCAM properties in version 1.41 is no longer need, as these special properties can now be accessed and manipulated using the new VCD properties. This document describes alternatives for all functions and procedures of the DCAM Prop DLL.

IsPhysicalUnits%%%, SetPhysicalUnits%%%

If physical units are supported for the property %%%, the appropriate VCD property provides a map strings interface ( IVCDMapStringsProperty ). It might be necessary to activate physical units support for a specific device explicitly by a special driver setup. Please refer to the device documentation for details. There is a new interface called 'absolute value' ( IVCDAbsoluteValueProperty ). Like the physical units of the map strings interface, it provides meaning for the values. In addition, it provides a high resolution. Therefore, you should use the absolute values interface, if supported.

IsWhiteBalance%%%, GetWhiteBalace%%%, SetWhiteBalance%%%

Basically there are two ways to handle these functions. The first one is to use the CSimplePropertyAccess class. The usage of this class is described in the Using the VCD Simple Property Class chapter of the user's guide. The helper class offers methods, which allow to get, set or check the availability of a certain property. Every method of this helper class needs an ID that specifies the property for which the method is to be called. The IDs for "WhiteBalanceBlue" and "WhiteBalanceRed" are VCDElement_WhiteBalanceBlue and VCDElement_WhiteBalanceRed. For detailed information refer to the CSimplePropertyAccess class.

The second way is to directly use the new VCDProperties. The chapters Basic Use of VCD Properties and List VCD Properties of the user's guide show you how to use them. When using the new VCDProperties, it is important to know how they are organized. There are IVCDPropertyItems, IVCDPropertyElements and IVCDPropertyInterfaces. Each item has one or more elements and each element has one ore more interfaces. The interfaces allow the according property elements to be manipulated. In order to check, if "WhiteBalance%%%" is available, use the IVCDPropertyItems::findElement method with VCDID_WhiteBalance and VCDElement_WhiteBalance%%% as parameter. VCDID_WhiteBalance describes the property item, while VCDElement_WhiteBalance%%% describes the element "WhiteBalanceRed" or "WhiteBalanceBlue". If the property is supported, the respective element is returned. If it is not supported, 0 is returned.

To get or set the values for "WhiteBalance%%%", retrieve the appropriate interface with the IVCDPropertyItems::findInterface, IVCDPropertyElement::getInterface or IVCDPropertyElement::getInterfacePtr method. As soon as the interface is retrieved, its methods can be used to manipulate the property. For detailed information refer to IVCDPropertyInterface.

// Get supported property items.
tIVCDPropertyItemsPtr pItems = m_Grabber.getAvailableVCDProperties();

// Retrieve the range interface for WhiteBalanceRed.
tIVCDRangePropertyPtr pRange = 0;
if( pItems->findInterfacePtr( VCDID_WhiteBalance, VCDElement_WhiteBalanceRed, pRange ) != 0 )
{
    // Initialize the slider m_sldWhiteBalanceRed with the values of the WhiteBalanceRed property.
    m_sldWhiteBalanceRed.SetRange( pRange->getRangeMin(), pRange->getRangeMax() );
    m_sldWhiteBalanceRed.SetPos( pRange->getValue() );
    m_sldWhiteBalanceRed.EnableWindow();
}
else
{
    m_sldWhiteBalanceRed.EnableWindow( FALSE );
}

IsHorizontalFlipAvailable, GetHorizontalFlip, SetHorizontalFlip

To check whether the horizontal flip is available, use the Grabber::isFlipHAvailable property. To get or set the horizontal flip, the Grabber::getFlipH and Grabber::setFlipH methods are used.

<< Technical Articles


Class Library Reference

Complete list of all classes and functions.

Constants

Complete list of all constants

Helper Classes

Complete list of Helper Classes.

Classes

Complete list of all classes.

Enumerations

Complete list of all enumerations.

Functions

Complete list of all functions.

Structures

Complete list of all structures.

Type Definitions

Complete list of all type definitions in namespace DShowLib.

<< IC Imaging Control Class Library User's Guide


Constants

Complete list of all constants

Enumerations

Enumeration | Description
Standard Element GUIDs | The Standard Element GUIDs are used to find a IVCDPropertyElement of a IVCDPropertyItem.
Standard Interface GUIDs | The Standard Interface GUIDs are used to find interface objects of a IVCDPropertyElement.
Standard MediaStreamContainer GUIDs | MediaStreamContainer GUIDs are used to create instances using MediaStreamContainer::create.
Standard Mediasubtype GUIDs | Mediasubtype GUIDs are used to define color formats for FrameTypeInfo or as uncompressed video formats in MediaStreamSink::create.
Standard Property Item GUIDs | The Standard Property Item GUIDs are used to retrieve a IVCDPropertyItem from the IVCDPropertyItems collection. The GUIDs are passed to the IVCDPropertyItems::findItem method.

<< Class Library Reference


constants::Standard Element GUIDs

Standard Element GUIDs
The Standard Element GUIDs are used to find a IVCDPropertyElement of a IVCDPropertyItem.
After an IVCDPropertyItem interface has been retrieved with one of the Standard Property Item GUIDs, the property elements of the property item can be retrieved.
#include "tisudshl.h"
The GUIDs are declared in the namespace DShowLib.
The GUIDs are passed to the IVCDPropertyItem::findElement method. The element type is used to specify a sub property of a camera property. For example the exposure camera property can have a value and an auto element. The value element is used to retrieve and set an value (e.g. 114). The auto element is used to enable or disable automation for exposure. An interface to an element is retrieved by adding a string from the Standard Interface GUIDs to the Standard Element GUID.
The Basic Use of VCD Properties article in the Programmer's Guide shows how to use the element GUIDs.
Constant | Description
VCDElement_Value | Specifies a value element with minimum and maximum.
VCDElement_Auto | Specifies an auto element to enable or disable automation of a property.
VCDElement_OnePush | Specifies a button element, such as white balance OnePush.
VCDElement_ResetValue | Specifies the reset value element.
VCDElement_WhiteBalanceBlue | Specifies the white balance blue element of DCAM cameras.
VCDElement_WhiteBalanceRed | Specifies the white balance red element of DCAM cameras.
VCDElement_AutoReference | Specifies the auto reference value for the auto exposure function.
VCDElement_TriggerPolarity | Specifies the trigger polarity element.
VCDElement_TriggerMode | Specifies the trigger mode element.
VCDElement_MultiSlope_SlopeValue0 | Specifies the multi slope 0 value element.
VCDElement_MultiSlope_ResetValue0 | Specifies the multi slope reset 1 value element.
VCDElement_MultiSlope_SlopeValue1 | Specifies the multi slope 1 value element.
VCDElement_MultiSlope_ResetValue1 | Specifies the multi slope reset 1 value element.
VCDElement_MultiSlope_SlopeValue2 | Specifies the multi slope 2 value element.
VCDElement_MultiSlope_ResetValue2 | Specifies the multi slope reset 3 value element.
VCDElement_MultiSlope_SlopeValue3 | Specifies the multi slope 3 value element.
VCDElement_MultiSlope_ResetValue3 | Specifies the multi slope reset 3 value element.
VCDElement_MultiSlope_SlopeValue4 | Specifies the multi slope 4 value element.
VCDElement_MultiSlope_ResetValue4 | Specifies the multi slope reset 4 value element.
VCDElement_MultiSlope_SlopeValue5 | Specifies the multi slope 5 value element.
VCDElement_MultiSlope_ResetValue5 | Specifies the multi slope reset 5 value element.
VCDElement_MultiSlope_SlopeValue6 | Specifies the multi slope 6 value element.
VCDElement_MultiSlope_ResetValue6 | Specifies the multi slope reset 6 value element.
VCDElement_MultiSlope_SlopeValue7 | Specifies the multi slope 7 value element.
VCDElement_PartialScanOffsetX | Specifies the horizontal start position of the area on the CCD that is transferred in partial scan mode.
VCDElement_PartialScanOffsetY | Specifies the vertical start position of the area on the CCD that is transferred in partial scan mode.
VCDElement_GPIOIn | Specifies the General Purpose input property.
VCDElement_GPIOOut | Specifies the GPIO (General Purpose Input/Output) output property.
VCDElement_GPIOWrite | Specifies the write action for the GPIO (General Purpose Input/Output).
VCDElement_GPIORead | Specifies the read action for the GPIO (General Purpose Input/Output).
VCDElement_StrobePolarity | Specifies the polarity property for the strobe output.
VCDElement_StrobeDuration | Specifies the duration property for the strobe output.
VCDElement_StrobeDelay | Specifies the delay property for the strobe output.

<< Class Library Reference


constants::Standard Interface GUIDs

Standard Interface GUIDs
The Standard Interface GUIDs are used to find interface objects of a IVCDPropertyElement.
The interface of a IVCDPropertyElement determines the handling of the regarded property element. For example, an auto element should be handled by a switch interface. The GUID is passed to the IVCDPropertyElement::getInterface method to get the desired interface.
The Basic Use of VCD Properties article in the Programmer's Guide shows how to use the interface GUIDs.
Constant | Description
VCDInterface_Range | Finds an IVCDRangeProperty.
VCDInterface_Switch | Finds an IVCDSwitchProperty.
VCDInterface_Button | Finds an IVCDButtonProperty.
VCDInterface_MapStrings | Finds an IVCDMapStringsProperty.
VCDInterface_AbsoluteValue | Finds an IVCDAbsoluteValueProperty.

<< Class Library Reference


constants::Standard Property Item GUIDs

Standard Property Item GUIDs
The Standard Property Item GUIDs are used to retrieve a IVCDPropertyItem from the IVCDPropertyItems collection. The GUIDs are passed to the IVCDPropertyItems::findItem method.
A Standard Property Item Identifier String can be combined with a GUID from the Standard Element GUIDs and a GUID from the Standard Interface GUIDs, to find a specific element or interface.
#include "tisudshl.h"
The GUIDs are declared in the DShowLib namespace.
The Basic Use of VCD Properties article in the Programmer's Guide shows how to use the property item GUIDs.
Constant | Description
VCDID_Brightness | Retrieves the brightness property item.
VCDID_Contrast | Retrieves the contrast property item.
VCDID_Hue | Retrieves the hue property item.
VCDID_Saturation | Retrieves the saturation property item.
VCDID_Sharpness | Retrieves the sharpness property item.
VCDID_Gamma | Retrieves the gamma property item.
VCDID_ColorEnable | Retrieves the color enable property item.
VCDID_WhiteBalance | Retrieves the white balance property item.
VCDID_BacklightCompensation | Retrieves the backlight compensation property item.
VCDID_Gain | Retrieves the gain property item.
VCDID_Pan | Retrieves the pan property item.
VCDID_Tilt | Retrieves the tilt property item.
VCDID_Roll | Retrieves the roll property item.
VCDID_Zoom | Retrieves the zoom property item.
VCDID_Exposure | Retrieves the exposure property item.
VCDID_Iris | Retrieves the iris property item.
VCDID_Focus | Retrieves the focus property item.
VCDID_VCRCompatibilityMode | Retrieves the VCR compatibility mode property item.
VCDID_TriggerPolarity | Retrieves the trigger polarity property item.
VCDID_Trigger | Retrieves the trigger mode property item.
VCDID_TestPattern | Retrieves the test pattern property of the Dxx 21F04 camera series
VCDID_MultiSlope | Retrieves the multi slope property item.
VCDID_SignalDetected | Retrieves the signal detected property item.
VCDID_PartialScanOffset | Retrieves the Partial Scan Offset property item.
VCDID_GPIO | Retrieves the General Purpose IO property item.
VCDID_Strobe | Retrieves the Strobe property item.

<< Class Library Reference


Helper Classes

Complete list of Helper Classes.

CSimplePropertyAccess

This class wraps access to VCDProperties to make them easier to use.

<< Class Library Reference


Classes

Complete list of all classes.

AnalogChannelItem

An AnalogChannelItem represents an input of a video capture device.

AviSink

[Deprecated] The AviSink writes the image stream that comes from the currently active video capture device, to an avi file. If a codec is specified in the constructor AviSink::AviSink, the image stream is compressed using this codec.

Codec

The Codec class represents a video compressor. It replaces the deprecated FilterInfoObject, that was used in previous versions of IC Imaging Control.

DeBayerTransform

The DeBayerTransform class allows you to control the automatic debayering process of IC Imaging Control.

Error

The Error class gives information about an errors that occur during a call to the class library. Grabber::getLastError returns the error object which is associated to the last call of a method of the Grabber instance.

FilterInfoObject

[Deprecated] A FilterInfoObject contains the name of a video codec used for avi file compression.

FilterLoader

This static class contains methods to create instances of frame filters that are loaded from filter modules ( *.ftf ).

FrameFilterImpl

To implement a transform filter, you have to derive from this class.

FrameGrabberSink

[Deprecated] The FrameGrabberSink is the SinkType used to grab (copy) frames from the image stream to the buffers of the currently active MemBufferCollection. Frames are copied one after another, starting with the first buffer of MemBufferCollection. When a frame is copied into the last buffer, the next frame is copied to the first buffer and so on.

FrameHandlerSink

The FrameHandlerSink is the SinkType used to grab (copy) frames from the image stream. It replaces the deprecated FrameGrabberSink and contains a MemBufferCollection and optionally allows you to specify one or more IFrameFilters that are responsible for copying the image data to the buffers of the MemBufferCollection. The IFrameFilter implementation can perform user-defined transformations while copying the data, and they can intentionally drop unwanted frames. If no frame filter is registered, the frames are copied to the MemBufferCollection without being changed.

FrameTypeInfo

This structure contains all information to describe the layout (pixel depth and pixel organization) and the extents of one frame (image buffer) in the image stream.

FrameTypeInfoArray

This class is a list of FrameTypeInfo objects. It is used in the communication between FrameFilterImpl-derived classes when the image stream is setup and the filters are inserted in the image stream.

FrameUpdateFilterImpl

To implement an update filter, you have to derive from this class.

Grabber

This is the main class of the IC Imaging Control Class Library. It provides the basic functionality to control the flow of image buffers in an image stream from the source (a video capture device) to the sink (a collection of image buffers or a media file). The display of a live image can be toggled on and off. The idea behind this class is to provide the functionality of a standard frame grabber to users of WDM streaming devices.

GrabberListener

The GrabberListener class is the base class for all classes implementing a callback handler. A callback handler class has to be derived from GrabberListener and has to overwrite one or more callback methods. Every instance of a callback handler class has to be registered in Grabber by a call to Grabber::addListener. The available methods are:

GrabberSinkType

This is the abstract base class for all sinks which cannot be instantiated. A sink specifies the format to which the image stream is converted and it specifies the way in which single frames can be accessed.

IFrame

Interface to an image buffer.

IFrameFilter

IFrameFilter is the base class of all frame filters. It contains methods to access the filter's parameters, display a configuration dialog and save filter settings. This class provides the interface to use an existing filter.

IVCDAbsoluteValueProperty

This class represents an absolute value interface to a value of a video capture device property.

IVCDButtonProperty

This class represents a button interface to a value of a video capture device property.

IVCDMapStringsProperty

This class represents an interface to a video capture device property, which uses a string representation for every value.

IVCDPropertyElement

This class represents an element of video capture device property.

IVCDPropertyInterface

This class represents an interface to a value of a video capture device property.

IVCDPropertyItem

This class represents an item of a video capture device property.

IVCDPropertyItems

This class is a collection of IVCDPropertyItem objects.

IVCDRangeProperty

This class represents a range interface to a value of a video capture device property.

IVCDSwitchProperty

This class represents a switch interface to a value of a video capture device property.

MediaStreamContainer

A MediaStreamContainer describes a video file format. The most common video file format is AVI, which is identified by the GUID MSC_AviContainer.

MediaStreamSink

The MediaStreamSink replaces the deprecated AVISink. A MediaStreamSink can save image data in video files and optionally allows you to specify one or more IFrameFilters that can analyze and/or transform the image data before it is written to the video file.

MemBuffer

A MemBuffer represents a single buffer in a MemBufferCollection (organized as a ring buffer).

MemBufferCollection

The MemBufferCollection stores several MemBuffers. The MemBufferCollection is organized as a ring buffer: If a frame is grabbed to the last buffer of the collection, the next frame will be grabbed to the first one.

OverlayBitmap

The OverlayBitmap object is used to draw graphical elements like lines and text onto the video stream.

VideoCaptureDeviceItem

The VideoCaptureDeviceItem identifies a video capture device. A VideoCaptureDeviceItem is a temporary object and may not be stored permanently. For permanent storage use the string representation as returned by c_str, toString, getName and operator const char*.

VideoFormatDesc

A VideoFormatDesc describes an available video format using the media subtype, a binning factor and size constraints. The size constraints are described by a minimum size, a maximum size and a step size.

VideoFormatItem

The VideoFormatItem represents a video format that describes the width, height and the color format of an image stream generated by a video capture device. The available video formats depend on the selected video norm.

VideoNormItem

The VideoNormItem represents a video norm supported by a video capture device.

smart_com

smart_com is a reference counting pointer to COM objects. It releases reference to the IUnknown interface when it is destroyed.

smart_ptr

The smart_ptr is a reference counting pointer object. Whenever a method of the IC Imaging Control Class Library returns a pointer, it will be an object of this class.

<< Class Library Reference


AnalogChannelItem

An AnalogChannelItem represents an input of a video capture device.

Some video capture devices such as converters may have one or more input channels. For example, an analog to 1394 converter may have 1 S-Video and 2 Composite inputs. Each input channel is represented by an instance of this class.

This class cannot be used for video capture devices that do not support input channels.

Remarks

The name of this class may change to InputChannelItem in future versions of IC Imaging Control. Please refer to this class with tInputChannelItem which is a typedef to AnalogChannelItem.

Information

Header File: tisudshl.h
Namespace: DShowLib

Methods

Method | Description
AnalogChannelItem | Constructs a new AnalogChannelItem object by copying an existing one.
c_str | Returns the string representation of this input channel.
getIndex | Returns a numerical representation of this input channel.
isValid | Checks whether this object is valid.
operator const char* | Returns a string representation of this channel item.
operator!= | Checks whether two input channel items differ.
operator< | Compares the indexes of two AnalogChannelItems.
operator= | Assigns another AnalogChannelItem to this.
operator== | Checks whether two input channels are equal.
toString | Returns the string representation of this input channel.

<< Classes


AnalogChannelItem::AnalogChannelItem

AnalogChannelItem::AnalogChannelItem Method
Constructs a new AnalogChannelItem object by copying an existing one.
Syntax:
AnalogChannelItem( const AnalogChannelItem& op );

Parameter | Description
op | The existing AnalogChannelItem that is to be copied
See also: AnalogChannelItem

<< AnalogChannelItem


AnalogChannelItem::c_str

AnalogChannelItem::c_str Method
Returns the string representation of this input channel.
Syntax:
const char* c_str() const;
Return value:

A 0-terminated string.

See also: AnalogChannelItem, AnalogChannelItem::toString

<< AnalogChannelItem


AnalogChannelItem::getIndex

AnalogChannelItem::getIndex Method
Returns a numerical representation of this input channel.
Syntax:
int getIndex() const;
Return value:

The index of this input channel.

Remarks:

This method returns -1, if an error occurred. -1 may also be valid input channel. Use AnalogChannelItem::isValid to determine whether the channel is valid or an error occurred.

See also: AnalogChannelItem

<< AnalogChannelItem


AnalogChannelItem::isValid

AnalogChannelItem::isValid Method
Checks whether this object is valid.
Syntax:
bool isValid() const;
Return value:

true, if the input channel is valid, false otherwise.

Remarks:

If the video capture device does not support multiple input channels or, if an error occurred, a call to Grabber::getInputChannel returns an invalid object.

See also: AnalogChannelItem

<< AnalogChannelItem


AnalogChannelItem::operator const char*

AnalogChannelItem::operator const char* Method
Returns a string representation of this channel item.
Syntax:
operator const char*() const;
Return value:

A pointer to a string.

See also: AnalogChannelItem

<< AnalogChannelItem


AnalogChannelItem::operator!=

AnalogChannelItem::operator!= Method
Checks whether two input channel items differ.
Syntax:
bool operator!=( const AnalogChannelItem& op ) const;

Parameter | Description
op | Another input channel with which to compare this.
Return value:

true, if this is different from op, false otherwise.

See also: AnalogChannelItem, AnalogChannelItem::operator==

<< AnalogChannelItem


AnalogChannelItem::operator<

AnalogChannelItem::operator< Method
Compares the indexes of two AnalogChannelItems.
Syntax:
bool operator<( const AnalogChannelItem& op ) const;

Parameter | Description
op | Another input channel with which to compare this.
Return value:

true, if the index of this is smaller than the index of the given AnalogChannelItem, false otherwise.

See also: AnalogChannelItem

<< AnalogChannelItem


AnalogChannelItem::operator=

AnalogChannelItem::operator= Method
Assigns another AnalogChannelItem to this.
Syntax:
AnalogChannelItem& operator=( const AnalogChannelItem& op2 );

Parameter | Description
op | The AnalogChannelItem to assign.
Return value:

A reference to this.

See also: AnalogChannelItem

<< AnalogChannelItem


AnalogChannelItem::operator==

AnalogChannelItem::operator== Method
Checks whether two input channels are equal.
Syntax:
bool operator==( const AnalogChannelItem& op ) const;
bool operator==( const std::string& opString ) const;
bool operator==( const std::wstring& op ) const;

Parameter | Description
op | Another input channel with which to compare this.
opString | A pointer to a string with which this channel item should be compared.
Return value:

true, if the input channels are equal, false otherwise.

See also: AnalogChannelItem, AnalogChannelItem::operator!=

<< AnalogChannelItem


AnalogChannelItem::toString

AnalogChannelItem::toString Method
Returns the string representation of this input channel.
Syntax:
std::string toString() const;
std::wstring    toStringW() const;
Return value:

A string representation of this input channel.

Information:

Introduced in version 2.0
See also: AnalogChannelItem, AnalogChannelItem::c_str

<< AnalogChannelItem


AviSink

AviSink [Deprecated]

The AviSink writes the image stream that comes from the currently active video capture device, to an avi file. If a codec is specified in the constructor AviSink::AviSink, the image stream is compressed using this codec.

Remarks

Since this class will not be available in future versions of IC Imaging Control, the class MediaStreamSink should be used instead. The following code fragment shows you how to setup a MediaStreamSink to record AVI files:

// Select the first available codec.
tCodecPtr pCodec = Codec::getAvailableCodecs()->at( 0 );

// Create a media stream sink to record AVI files, using this codec.
tMediaStreamSinkPtr pSink = MediaStreamSink::create( MSC_AviContainer, pCodec );

// Set a video file name.
pSink->setFilename( "test.avi" );

// Set the sink.
m_Grabber.setSinkType( pSink );

Information

Header File: tisudshl.h
Namespace: DShowLib
This class is deprecated since version 3.0.
To record any kind of video file, use MediaStreamSink.

Inheritance

GrabberSinkType
MediaStreamSink
AviSink

Methods

Method | Description
AviSink | Constructs a AviSink object.
getCodecType | Returns the GUID of the codec associated with this AviSink.
getFileName | Returns the name of the avi file to which the video stream will be written.
getFilterInfo | Retrieves the associated FilterInfoObject representing the AVI Codec.
getSinkType | This method returns the type of this sink: eAviSink.

<< Classes


AviSink::AviSink

AviSink::AviSink Method
Constructs a AviSink object.
Syntax:
AviSink( std::string filename, const GUID& codec_type, tSinkModes AutoStart = eRUN );
AviSink( const wchat_t* filename, const GUID& codec_type, tSinkModes AutoStart = eRUN );
AviSink( std::string filename, const FilterInfoObject& finfo, const GUID& codec_type = GUID_NULL, tSinkModes AutoStart = eRUN );
AviSink( const wchar_t* filename, const FilterInfoObject& finfo, const GUID& codec_type = GUID_NULL, tSinkModes AutoStart = eRUN );

Parameter | Description
filename | Specifies the name of the AVI file to which the image stream will be saved.
finfo | Specifies a codec to be used for compression. (The FilterInfoObject contains the name of the codec).
code_type | Specifies the codec to be used to compress the stream. If this is GUID_NULL, the video format of the source is used.
avisink | Specifies another AviSink object to be copied.
AutoStart | Specifies a sink mode with member of the tSinkModes enumeration. It defaults to eRun.
See also: AviSink

<< AviSink


AviSink::getCodecType

AviSink::getCodecType Method
Returns the GUID of the codec associated with this AviSink.
Syntax:
GUID getCodecType() const;
Return value:

The GUID of the codec associated with this AviSink.

See also: AviSink, Grabber::getAvailableVideoCompressors

<< AviSink


AviSink::getFileName

AviSink::getFileName Method
Returns the name of the avi file to which the video stream will be written.
Syntax:
std::string getFilename() const;
Return value:

The name of the avi file.

See also: AviSink, AviSink::AviSink

<< AviSink


AviSink::getFilterInfo

AviSink::getFilterInfo Method
Retrieves the associated FilterInfoObject representing the AVI Codec.
Syntax:
smart_ptr<FilterInfoObject> getFilterInfo() const;
Return value:

A smart_ptr to the associated FilterInfoObject. If no codec is associated, 0 is returned.

See also: AviSink, AviSink::AviSink

<< AviSink


AviSink::getSinkType

AviSink::getSinkType Method
This method returns the type of this sink: eAviSink.
Syntax:
tSinkType getSinkType() const;
Return value:

The type of this sink: eAviSink.

See also: AviSink, GrabberSinkType

<< AviSink


Error

The Error class gives information about an errors that occur during a call to the class library. Grabber::getLastError returns the error object which is associated to the last call of a method of the Grabber instance.

Information

Header File: tisudshl.h
Namespace: DShowLib

Methods

Method | Description
Error | Constructs a new Error object.
c_str | This method returns a string representation of this error.
getString | This method returns a string representation of this error.
getVal | This method returns the enumeration value of this error. See tErrorEnum for a list of possible values.
isError | Checks whether this object represents an error. Error objects of type eNOERROR do not represent an error. This value indicates that the last call to a method of an instance of Grabber was successfull.
operator const char* | Returns a string representation of this error.
operator std::string | Returns a string representation of this error.
operator tErrorEnum | Returns the tErrorEnum value of this error.
toString | This method returns a string representation of this error.

<< Classes


Error::Error

Error::Error Method
Constructs a new Error object.
Syntax:
Error();
Error( const Error& err );
Remarks:

The default constructor will create an object, which represents an unknown error. Its value will be eUNKNOWN and its describing string will be set to "Unknown Error".

The copy constructor will copy the value and the string representation of the given Error object.

See also: Error

<< Error


Error::c_str

Error::c_str Method
This method returns a string representation of this error.
Syntax:
const char* c_str() const;
Return value:

A pointer to a 0-terminated string that describes this error.

See also: Error, Error::getString, Error::operator const char*, Error::operator std::string, Error::toString

<< Error


Error::getString

Error::getString Method
This method returns a string representation of this error.
Syntax:
std::string getString() const;
std::wstring getStringW() const;
Return value:

A string describing this error.

See also: Error, Error::c_str, Error::operator const char*, Error::operator std::string, Error::toString

<< Error


Error::getVal

Error::getVal Method
This method returns the enumeration value of this error. See tErrorEnum for a list of possible values.
Syntax:
tErrorEnum getVal() const;
Return value:

A tErrorEnum value of this error.

See also: Error, Error::operator tErrorEnum, tErrorEnum

<< Error


Error::isError

Error::isError Method
Checks whether this object represents an error. Error objects of type eNOERROR do not represent an error. This value indicates that the last call to a method of an instance of Grabber was successfull.
Syntax:
bool isError() const;
Return value:

true, if this object has a type different from eNOERROR, false otherwise.

See also: Error, tErrorEnum

<< Error


Error::operator const char*

Error::operator const char* Method
Returns a string representation of this error.
Syntax:
operator const char*() const;
Return value:

A string representation of this error.

See also: Error, Error::c_str

<< Error


Error::operator std::string

Error::operator std::string Method
Returns a string representation of this error.
Syntax:
operator std::string() const;
Return value:

A string representation of this error.

See also: Error, Error::getString, Error::toString

<< Error


Error::operator tErrorEnum

Error::operator tErrorEnum Method
Returns the tErrorEnum value of this error.
Syntax:
operator tErrorEnum() const;
Return value:

The tErrorEnum value of this error.

See also: Error, Error::getVal, tErrorEnum

<< Error


Error::toString

Error::toString Method
This method returns a string representation of this error.
Syntax:
std::string toString() const;
std::wstring toStringW() const;
Return value:

A string describing this error.

See also: Error, Error::c_str, Error::operator const char*, Error::operator std::string, Error::getString

<< Error


FilterInfoObject

FilterInfoObject [Deprecated]

A FilterInfoObject contains the name of a video codec used for avi file compression.

Remarks

The FilterInfoObject for the currently selected codec can be retrieved with the method getFilterInfo from the AviSink. A list of FilterInfoObjects of all codecs currently available on the system is returned by Grabber::getAvailableVideoCompressors.

Information

Header File: tisudshl.h
Namespace: DShowLib
This class is deprecated since version 3.0.
To use video compressors, refer to the Codec class.

Methods

Method | Description
FilterInfoObject | Constructs a new FilterInfoObject by copying an existing one.
c_str | Returns a string representation of this object.
callDialog | This method calls a dialog box, if the filter has one.
createInvalid | Returns an invalid FilterInfoObject.
getCodecData | This method returns a blob that contains the parameter of a codec / compressor.
getInternalInterface | Returns a reference to an internal interface.
getName | Returns a string representation of this object.
hasDialog | Checks whether the codec has a dialog box.
isCodecDataAvailable | Checks whether the setting data can be retrieved from or set to the codec.
isValid | Checks whether this object is valid.
operator const char* | Returns a string representation of this filter info object.
operator!= | Determine whether two filter info objects differ.
operator< | Compares the string representations of this filter info object with the string representation of another one.
operator= | Assigns another FilterInfoObject to this object.
operator== | Checks whether two filter info objects are equal.
setCodecData | This method is used to set previously retrieved codec data.
toString | Returns a string representation of this object.

<< Classes


FilterInfoObject::FilterInfoObject

FilterInfoObject::FilterInfoObject Method
Constructs a new FilterInfoObject by copying an existing one.
Syntax:
FilterInfoObject( const FilterInfoObject& filtinfobj );

Parameter | Description
filtinfobj | Specifies the FilterInfoObject to copy.

<< FilterInfoObject


FilterInfoObject::c_str

FilterInfoObject::c_str Method
Returns a string representation of this object.
Syntax:
const char* c_str() const;
Return value:

A 0-terminated string.

Remarks:

toString, getName and c_str all return the same text.

See also: FilterInfoObject, FilterInfoObject::getName

<< FilterInfoObject


FilterInfoObject::callDialog

FilterInfoObject::callDialog Method
This method calls a dialog box, if the filter has one.
Syntax:
bool callDialog( HWND hParent = 0 );

Parameter | Description
hParent | Specifies the parent window of the dialog box to show.
Return value:

true on success, false otherwise.

Remarks:

In general this method is blocked, until the dialog box is closed.

See also: FilterInfoObject, FilterInfoObject::hasDialog

<< FilterInfoObject


FilterInfoObject::createInvalid

FilterInfoObject::createInvalid Method
Returns an invalid FilterInfoObject.
Syntax:
static FilterInfoObject createInvalid();
Return value:

An invalid FilterInfoObject.

See also: FilterInfoObject, FilterInfoObject::isValid

<< FilterInfoObject


FilterInfoObject::getCodecData

FilterInfoObject::getCodecData Method
This method returns a blob that contains the parameter of a codec / compressor.
Syntax:
bool getCodecData( BYTE* pData, DWORD& size );

Parameter | Description
pData | The data buffer into which to copy the data. May be 0, if you only want to retrieve the size of the buffer.
size | The size of the data.
Return value:

true on success, false otherwise.

Remarks:

An application needs this method in order to save the current parameters of a compressor filter to a binary file or registry. The FilterInfoObject for the currently selected codec can be retrieved with the method getFilterInfo from the AviSink.

See also: FilterInfoObject, FilterInfoObject::setCodecData, FilterInfoObject::isCodecDataAvailable, AviSink::getFilterInfo

<< FilterInfoObject


FilterInfoObject::getInternalInterface

FilterInfoObject::getInternalInterface Method
Returns a reference to an internal interface.
Syntax:
template<class TItf>
smart_com<TItf> getInternalInterface( smart_com<TItf>& pItf ) const;
smart_com<TItf> getInternalInterface( REFIID riid, smart_com<TItf>& pItf ) const;

Parameter | Description
pItf | A smart_com to an interface reference.
riid | An interface ID.
Return value:

A reference to the interface requested or 0, if the interface is not supported.

Remarks:

This method allows it to fetch a custom interface from a codec.

To use this method, the compiler must support the __uuidof operator.

If the compiler supports the __declspec( uuid( "iid" ) ) option, an iid can be assigned to the interface this way. If the compiler does not support this option, the iid must be passed to the method as a parameter.

Information:

Introduced in version 2.0
Sample:

This example shows how to fetch an interface from a codec.

smart_com<ICodecInterface> pItf;
if( pFilterInfoObject->getInternalInterface( pItf ) == 0 )
{
    ... // interface is not supported, so error handling
}
else
{
    ... // use the interface
}
See also: FilterInfoObject, smart_com

<< FilterInfoObject


FilterInfoObject::getName

FilterInfoObject::getName Method
Returns a string representation of this object.
Syntax:
std::string getName() const;
Return value:

A string representation of this object.

Remarks:

toString, getName and c_str all return the same text.

See also: FilterInfoObject, FilterInfoObject::c_str, FilterInfoObject::toString

<< FilterInfoObject


FilterInfoObject::hasDialog

FilterInfoObject::hasDialog Method
Checks whether the codec has a dialog box.
Syntax:
bool hasDialog() const;
Return value:

true, if this codec has a property dialog box; false otherwise.

See also: FilterInfoObject, FilterInfoObject, FilterInfoObject::callDialog

<< FilterInfoObject


FilterInfoObject::isCodecDataAvailable

FilterInfoObject::isCodecDataAvailable Method
Checks whether the setting data can be retrieved from or set to the codec.
Syntax:
bool isCodecDataAvailable() const;
Return value:

true, if this codec has codec data, false otherwise.

Information:

Introduced in version 2.0
See also: FilterInfoObject, FilterInfoObject::getCodecData, FilterInfoObject::setCodecData

<< FilterInfoObject


FilterInfoObject::isValid

FilterInfoObject::isValid Method
Checks whether this object is valid.
Syntax:
bool isValid() const;
Return value:

true, if this object is a valid representation of a filter info, false otherwise.

See also: FilterInfoObject, FilterInfoObject::createInvalid

<< FilterInfoObject


FilterInfoObject::operator const char*

FilterInfoObject::operator const char* Method
Returns a string representation of this filter info object.
Syntax:
bool operator const char*() const;
Return value:

A string representation of this filter info object.

See also: FilterInfoObject

<< FilterInfoObject


FilterInfoObject::operator!=

FilterInfoObject::operator!= Method
Determine whether two filter info objects differ.
Syntax:
bool operator!=( const FilterInfoObject& op ) const;

Parameter | Description
op | Another FilterInfoObject with which to compare.
Return value:

true, if the filter info objects differ, false if they are equal.

See also: FilterInfoObject, FilterInfoObject::operator==

<< FilterInfoObject


FilterInfoObject::operator<

FilterInfoObject::operator< Method
Compares the string representations of this filter info object with the string representation of another one.
Syntax:
bool operator<( const FilterInfoObject& op ) const;

Parameter | Description
op | Another filter info object with which to compare.
Return value:

true, if the string representation of this filter info object comes alphabetically before the string with which to compare. False, if this string representation is equal to or comes alphabetically after the string with which to compare.

Remarks:

Compares the string representations of this filter info object with the string representation of another one. The return value is the result of a lexicographical comparison between the two strings.

See also: FilterInfoObject

<< FilterInfoObject


FilterInfoObject::operator=

FilterInfoObject::operator= Method
Assigns another FilterInfoObject to this object.
Syntax:
FilterInfoObject& operator=( const FilterInfoObject& op );

Parameter | Description
op | The FilterInfoObject to assign.
Return value:

A reference to this.

See also: FilterInfoObject

<< FilterInfoObject


FilterInfoObject::operator==

FilterInfoObject::operator== Method
Checks whether two filter info objects are equal.
Syntax:
bool operator==( const FilterInfoObject& op ) const;
bool operator==( const std::string& op ) const;
bool operator==( const std::wstring& op ) const;

Parameter | Description
op | Another filter info object with which to compare.
string | A pointer to a string with which the string representation of this filter info object should be compared.
Return value:

true, if both operands are equal, false otherwise.

See also: FilterInfoObject, FilterInfoObject::operator!=

<< FilterInfoObject


FilterInfoObject::setCodecData

FilterInfoObject::setCodecData Method
This method is used to set previously retrieved codec data.
Syntax:
bool setCodecData( BYTE* pData, DWORD data_size );

Parameter | Description
pData | The data buffer with the data to copy into the codec.
size | The size of the data.
Return value:

true on success, false otherwise.

See also: FilterInfoObject, FilterInfoObject::getCodecData, FilterInfoObject::isCodecDataAvailable

<< FilterInfoObject


FilterInfoObject::toString

FilterInfoObject::toString Method
Returns a string representation of this object.
Syntax:
std::string toString() const;
std::wstring toStringW() const;
Return value:

A string representation of this object.

Remarks:

toString, getName and c_str all return the same text.

Information:

Introduced in version 2.0
See also: FilterInfoObject, FilterInfoObject::c_str, FilterInfoObject::getName

<< FilterInfoObject


FrameGrabberSink

FrameGrabberSink [Deprecated]

The FrameGrabberSink is the SinkType used to grab (copy) frames from the image stream to the buffers of the currently active MemBufferCollection. Frames are copied one after another, starting with the first buffer of MemBufferCollection. When a frame is copied into the last buffer, the next frame is copied to the first buffer and so on.

There is a grab mode and a snap mode for grabbing frames. This mode has to be specified in the constructor of FrameGrabberSink. In grab mode, frames are continuously copied to MemBufferCollection as soon as Grabber::startLive is called. A call to Grabber::stopLive ends the copy process. On the other hand, in snap mode, every call to Grabber::snapImages copies the specified number of frames to the MemBufferCollection. Grabber::startLive has to be called before any call to Grabber::snapImages.

Remarks

Since the FrameGrabberSink will not be available in future versions of the library, code that uses this sink should be ported to use the new FrameHandlerSink. You should consider the following when you port code:

  • The MemBufferCollection is no longer part of the Grabber object. It is now part of the FrameHandlerSink.
  • The grabbing of frames to the MemBufferCollection is controlled by methods of the FrameHandlerSink. Please refer to FrameHandlerSink::snapImages and FrameHandlerSink::snapImagesAsync for details.

Information

Header File: tisudshl.h
Namespace: DShowLib
This class is deprecated since version 3.0.
Please use the new FrameHandlerSink instead.

Inheritance

GrabberSinkType
FrameGrabberSink

Methods

Method | Description
FrameGrabberSink | Constructs a new FrameGrabberSink object.
getColorformat | Returns the color format (bit depth and organization of a pixel) of the associated image buffers.
getMode | Returns the currently active mode.
getSinkType | Returns the type of this sink.
newMemBufferCollection | Creates a new MemBufferCollection, which fits to this sink.
operator= | Assigns a FrameGrabberSink to this object.

Enumerations

Enumeration | Description
tFrameGrabberMode | tFrameGrabberMode enumerates the possible modes in which frames can be grabbed to the memory buffer.

Type Definitions

Type | Description
tMemBufferCollectionPtr | A pointer to a MemBufferCollection.

<< Classes


FrameGrabberSink::FrameGrabberSink

FrameGrabberSink::FrameGrabberSink Method
Constructs a new FrameGrabberSink object.
Syntax:
FrameGrabberSink( FrameGrabberSink::tFrameGrabberMode mode, tColorformatEnum colorformat = eRGB24, tSinkModes AutoStart = eRUN );
FrameGrabberSink( const FrameGrabberSink& framegrabbersink );
Parameter Description
mode

Specifies how images are copied to the currently active MemBufferCollection.

Value | Description
eSNAP | Snap mode: images will only be copied to the memory buffer, if Grabber::snapImages is called.
eGRAB | Grab mode: images will be continuously copied to the memory buffer, if Grabber::startLive is called.
colorformat

Specifies the color format to be used with this frame buffer. See tColorformatEnum for the available color formats.

AutoStart

Specifies a GrabberSinkType::tSinkModes. It defaults to eRun.

framegrabbersink

Specifies another FrameGrabberSink object which will be copied.

See also: FrameGrabberSink

<< FrameGrabberSink


FrameGrabberSink::getColorformat

FrameGrabberSink::getColorformat Method
Returns the color format (bit depth and organization of a pixel) of the associated image buffers.
Syntax:
tColorformatEnum getColorformat() const;
Return value:

A tColorformatEnum.

Remarks:

Returns the color format of the associated image buffers. The color format describes the number of bits and the organization of one pixel.

The color format for the FrameGrabberSink is specified in the constructor.

See also: FrameGrabberSink, FrameGrabberSink::FrameGrabberSink

<< FrameGrabberSink


FrameGrabberSink::getMode

FrameGrabberSink::getMode Method
Returns the currently active mode.
Syntax:
FrameGrabberSink::tFrameGrabberMode getMode() const;
Return value:

A FrameGrabberSink::tFrameGrabberMode.

Remarks:

The mode has to be specified in the constructor.

See also: FrameGrabberSink, FrameGrabberSink::FrameGrabberSink

<< FrameGrabberSink


FrameGrabberSink::getSinkType

FrameGrabberSink::getSinkType Method
Returns the type of this sink.
Syntax:
tSinkType getSinkType() const;
Return value:

The type of the sink as an eFrameGrabberSink.

Remarks:

This methods return value is always eFrameGrabberSink.

See also: FrameGrabberSink

<< FrameGrabberSink


FrameGrabberSink::newMemBufferCollection

FrameGrabberSink::newMemBufferCollection Method
Creates a new MemBufferCollection, which fits to this sink.
Syntax:
tMemBufferCollectionPtr newMemBufferCollection( DWORD buffer_count ) const;

tMemBufferCollectionPtr newMemBufferCollection( DWORD buffersize, BYTE* buffers[], DWORD buffer_count ) const;

Parameter | Description
buffer_count | Specifies the number of buffers in the collection.
buffersize | Specifies the size of a user allocated buffer.
buffers | An array of pointers that contains buffer_count pointers to buffers. These buffers are used for the MemBufferCollection. (If one entry is 0, then 0 is returned).
Return value:

A pointer to the memory buffer collection or 0, if an error occurred.

Information:

Introduced in version 2.0
See also: FrameGrabberSink, MemBufferCollection

<< FrameGrabberSink


FrameGrabberSink::operator=

FrameGrabberSink::operator= Method
Assigns a FrameGrabberSink to this object.
Syntax:
FrameGrabberSink& operator=( const FrameGrabberSink& op2 );
Return value:

A reference to this.

See also: FrameGrabberSink

<< FrameGrabberSink


FrameGrabberSink::tFrameGrabberMode
tFrameGrabberMode enumerates the possible modes in which frames can be grabbed to the memory buffer.
Enumeration | Description
eSNAP | While in live mode an image or a sequence of images will only be copied to the memory buffer, if Grabber::snapImages is called.
eGRAB | After calling Grabber::startLive, every image is copied into the memory buffer, until Grabber::stopLive is called.

<< FrameGrabberSink


FrameGrabberSink::tMemBufferCollectionPtr

tMemBufferCollectionPtr
A pointer to a MemBufferCollection.
Syntax:
typedef smart_ptr<MemBufferCollection> tMemBufferCollectionPtr;

<< FrameGrabberSink


Grabber

This is the main class of the IC Imaging Control Class Library. It provides the basic functionality to control the flow of image buffers in an image stream from the source (a video capture device) to the sink (a collection of image buffers or a media file). The display of a live image can be toggled on and off. The idea behind this class is to provide the functionality of a standard frame grabber to users of WDM streaming devices.

Using this class, programmers can:

  • select a video source
  • change parameters of a video source
  • display a live image
  • prepare, start and stop the image stream from the device to the sink (image buffers / media file)
  • specify the sink (image buffers / media file)
  • apply one or more frame filters to the image stream
  • apply overlays at 3 different locations to the image stream

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 1.x

Methods

Method | Description
Grabber | Constructs a new Grabber object.
addListener | This method registers a callback handler object for the specified events.
closeDev | Closes the currently active video capture device.
getAcqSizeMaxX | Returns the width in pixels of the currently selected video format.
getAcqSizeMaxY | Returns the height in pixels of the currently selected video format.
getActiveMemBuffer | [Deprecated] Returns the MemBuffer to which the current image is grabbed.
getActiveMemBufferCollection | [Deprecated] This method returns a pointer to the currently active MemBufferCollection.
getAvailableFPS | Returns the available frame rates.
getAvailableFrameRates | Returns the frame rates supported by the device.
getAvailableInputChannels | Returns a list of input channels supported by the current device.
getAvailableVCDProperties | Returns a collection of the IVCDPropertyItems of the currently opened device.
getAvailableVideoCaptureDevices | Returns a list of all currently available video capture devices.
getAvailableVideoCompressors | [Deprecated] Returns a list of all video compressors available for avi output.
getAvailableVideoFormatDescs | Returns a list of VideoFormatDesc objects describing all video formats supported by the current video capture device according to the current video norm.
getAvailableVideoFormats | Returns a list of all video formats supported by the current video capture device according to the current video norm.
getAvailableVideoNorms | Returns a list of all video norms supported by the current video capture device.
getCallback | [Deprecated] Returns a pointer to the currently active callback function
getCountOfFramesDropped | Returns the number of frames that were dropped by the video capture device.
getCountOfFramesNotDropped | Returns the number of frames that were delivered by the device.
getCurReferenceTime | Retrieves the current reference time.
getCurrentActualFPS | Retrieves the actual frame rate achieved by the device.
getCurrentActualFrameRate | Returns the current actual frame rate.
getCurrentMaxAvailableFPS | Returns the current maximal frames per second (FPS) that the device can achieve on the bus.
getDeBayerTransform | Returns a pointer to a DeBayerTransform object. If a BY8 Bayer video format is selected, the image data will be debayered automatically. The DeBayerTransform class allows the debayering to be checked.
getDefaultWindowPosition | This method returns the current value of the grabber's default window position flag.
getDev | Returns the currently active video capture device.
getDeviceFrameFilters | Returns the list of frame filters that are currently set behind the device.
getDisplayFrameFilters | Returns the list of frame filters that are currently set in front of the display.
getExternalTransportMode | Returns the current mode of the external transport control.
getExternalTrigger | Returns true, if the external trigger is enabled.
getFPS | Returns the frame rate currently set.
getFlipH | This method returns whether horizontal flipping is enabled.
getFlipV | This method returns whether vertical flipping is enabled.
getFrameCount | Read the internal frame counter.
getFrameRate | Returns the currently set time between two frames.
getGraphStartReferenceTime | This method retrieves the reference time at which the image stream (the filter graph) was started.
getHWND | This method returns a handle to the window, which is used to display the live image.
getInputChannel | Returns the currently active input channel. This method will fail, if there is no video capture device open.
getLastError | Returns information about an error that occurred, during the last library-method call.
getOverlay | This method returns a pointer to an instance of the OverlayBitmap object. The OverlayBitmap is used to draw text and graphics on the video stream.
getOverlayBitmapPathPosition | Returns the current position of OverlayBitmap objects in the graph.
getPauseLive | Returns whether pause mode is enabled.
getProperty | Returns the actual value of a property of the current video capture device.
getPropertyDefault | This method returns the default value of a property.
getPropertyRange | Returns a tsPropertyRange structure specifying the range of possible property values.
getSignalDetected | Returns whether a signal was detected by the device.
getSinkType | Returns the current output method of image streams.
getSinkTypePtr | Returns a pointer to the currently selected sink.
getUserMemBufferSize | [Deprecated] Calculates the required size for a user allocated memory buffer.
getVideoDataDimension | Returns the actual dimension of the image data which is passed to the display. This may be different from the video format of the currently active video capture device, if you have used setDeviceFrameFilters or setDisplayFrameFilters to insert frame filters in the image stream behind the device or in front of the display. If IFrameFilter objects are used by the FrameHandlerSink, the dimension of the MemBufferCollection may be different from the video data dimension as well.
getVideoFormat | This method returns the currently selected video format or an invalid object, if no video format is set (ie. the device is not open).
getVideoNorm | This method returns the currently selected video norm or an invalid object, if no video norm is selected.
getWindowPosition | This method retrieves the current position and size of the grabber's live video window.
hasExternalTransport | Returns true, if the device has an external transport control.
hasExternalTrigger | Returns true, if the current device has an external trigger.
isCountOfFramesDroppedAvailable | Returns whether the device supports retrieving the current dropped frames counter.
isDevOpen | Checks whether a video capture device is opened.
isDevValid | Checks whether the video capture device associated with this object still exists. A video capture device may become invalid at any time (e.g. if the device has been unplugged).
isFlipHAvailable | This method returns whether horizontal flipping is available.
isFlipVAvailable | This method returns whether vertical flipping is available.
isFrameRateListAvailable | Checks whether the currently selected video capture device supports different frame rates that can be set by the user.
isInputChannelAvailableWithCurDev | This method checks whether the currently active video capture device supports input channels.
isListenerRegistered | This method checks whether the specified callback handler is registered for the specified events.
isLive | Checks whether the current video capture device is in live mode.
isLivePrepared | Returns whether the image stream is in 'prepared' state.
isPropertyAutomationAvailableWithCurDev | Checks whether the current video capture device is capable of setting a specific property automatically.
isPropertyAutomationEnabled | Checks whether the automation for a specific property is enabled.
isPropertyAvailableWithCurDev | Checks whether the current video capture device supports the manual setting of a specific property.
isSignalDetectedAvailable | Checks whether a device can be queried for a list of available video stream.
isVideoNormAvailableWithCurDev | Checks whether the current video capture device supports the selection of the video norm.
loadDeviceState | Restores grabber settings that were saved by saveDeviceState.
loadDeviceStateFromFile | Restores the device settings from a file that was previously saved by saveDeviceStateToFile.
newMemBufferCollection | [Deprecated] Creates a new memory buffer collection.
openDev | Opens a video capture device for grabbing.
openDevByDisplayName | Opens a device by its display name.
openDevByUniqueName | Opens a device by its unique name.
prepareLive | Tries to setup the image stream by connecting the device with the display and the sink and inserting frame filters and overlays.
removeListener | This method unregisters a callback handler object for the specified events.
saveDeviceState | Saves the state of the opened device. A saved state can be restored using loadDeviceState.
saveDeviceStateToFile | Saves the state of the currently opened device to a file. The grabber state can be restored using loadDeviceStateFromFile.
setActiveMemBufferCollection | [Deprecated] Sets the MemBufferCollection in which the grabbed images will be stored.
setCallback | [Deprecated] Sets a callback function.
setDefaultWindowPosition | Enables or disables the default window size lock of the video window.
setDeviceFrameFilters | Inserts a list of frame filters in the device path of the image stream. If an overlay is present in the device path, the filter list is inserted in front it. This means that the filter list is located between the device and the overlay.
setDisplayFrameFilters | Inserts a list of frame filters in the display path of the image stream. If an overlay is present in the display path, the filter list is inserted in front of it. This means that the overlay is located between the filter list and the display. If there is no overlay in the display path, the filter list is inserted in front of the the display.
setExternalTransportMode | Sets a new mode for the external transport control.
setExternalTrigger | Enables/disables the external trigger.
setFPS | Sets the frame rate of the device.
setFlipH | Specifies whether all frames of an image stream should be flipped horizontally.
setFlipV | Specifies whether all frames of an image stream will be flipped vertically.
setFrameRate | Sets the time between two frames.
setHWND | Sets the handle to the window in which the live image will be displayed.
setInputChannel | Sets the input channel of the currently active video capture device.
setOverlayBitmapPathPosition | Sets the positions of OverlayBitmap objects in the graph.
setPauseLive | Pauses the live mode.
setProperty | This method sets the value for a device property of the current video capture device to a specific value or activates/deactivates the "automatic mode" for this property.
setSinkType | Sets the format of the sink. A sink specifies the output target of an image stream. A sink may only be set, if the image stream is in neither live mode, nor prepared mode.
setVideoFormat | This method sets the video format to be used by the currently active video capture device.
setVideoNorm | This method sets the video of the currently active video capture device. A list of available video norms may be retrieved by calling Grabber::getAvailableVideoNorms.
setWindowPosition | Sets the position of the grabber's live video window.
setWindowSize | Sets the size of the video window.
showDevicePage | Shows a device settings page.
showVCDPropertyPage | Shows the property page for this device. With the property page, the user can adjust property settings like brightness.
snapImages | [Deprecated] Snaps images from the live stream to the current active MemBuffer.
startLive | Puts the grabber in live mode.
stopLive | Stops the grabber
suspendLive | Suspends an image stream and puts it into prepared state.

Enumerations

Enumeration | Description
tCameraPropertyEnum | tCameraPropertyEnum enumerates the properties of a video camera.
tVideoPropertyEnum | tVideoPropertyEnum specifies video property types. This enumeration comes directly from DirectX 8.

Type Definitions

Type | Description
tCompressorItems | A tCompressorItem describes an AVI-Compressor.
tCompressorList | A list of tCompressorItems
tCompressorListPtr | A pointer to a list of tCompressorItems.
tFPSList | An array of double values that describe the number of frames per second.
tFPSListPtr | A pointer to a tFPSList.
tFrameRateList | An array of long values that describe the time between two frames in milliseconds.
tFrameRateListPtr | A pointer to a tFrameRateList.
tInChnList | A list of AnalogChannelItems.
tInChnListPtr | A pointer to a list of tVideoFormatItems.
tInputChannelItem | A AnalogChannelItem.
tMemBufferCollectionPtr | A pointer to a MemBufferCollection.
tMemBufferPtr | A pointer to a MemBuffer.
tVidCapDevList | A list of tVideoCaptureDeviceItems.
tVidCapDevListPtr | A pointer to a list of tVideoCaptureDeviceItems.
tVidFmtDescList | A tVidFmtDescList is a std::vector of smart pointers to VideoFormatDesc objects.
tVidFmtDescListPtr | A tVidFmtDescListPtr is smart pointer to a tVidFmtDescList. objects.
tVidFmtDescPtr | A tVidFmtDescPtr is a smart pointer to a VideoFormatDesc object.
tVidFmtList | A list of tVideoFormatItems.
tVidFmtListPtr | A pointer to a list of tVideoFormatItems.
tVidNrmList | A list of tVideoNormItems.
tVidNrmListPtr | A pointer to a list of tVideoNormItems.
tVideoCaptureDeviceItem | A VideoCaptureDeviceItem.
tVideoFormatItem | A VideoFormatItem.
tVideoNormItem | A VideoNormItem.

<< Classes


Grabber::Grabber

Grabber::Grabber Method
Constructs a new Grabber object.
Syntax:
Grabber();
See also: Grabber, Grabber::openDev

<< Grabber


Grabber::addListener

Grabber::addListener Method
This method registers a callback handler object for the specified events.
Syntax:
void addListener( GrabberListener* pListener, DWORD callback = -1 );

Parameter | Description
pListener | Specifies a pointer to the callback handler object that is to be registered. The callback handler object has to be derived from GrabberListener.
callback | Specifies the events that will be handled by the object referred to by pListener. A combination of GrabberListener::tListenerTypes specifies the events. A binary OR is used to combine two or more listener types. It defaults to -1. -1 is the combination of all possible GrabberListener::tListenerTypes.
Remarks:

This method is used to add a GrabberListener object to an internal list of the grabber. If one of the events occur that is defined by GrabberListener::tListenerType, the grabber calls the callback methods of all listener objects in the list that were added for this event. One GrabberListener object may handle more than one event. The parameter callback specifies the set of events that will be handled by the listener object. For possible values of callback, refer to GrabberListener::tListenerType. For more informations about callbacks, refer to GrabberListener.

The GrabberListener::frameReady method will be called, if the sink is a FrameHandlerSink and snap mode is set to false or snap mode is set to true and FrameHandlerSink::snapImages was called.

The GrabberListener::frameReady method will only be called, if a MemBufferCollection is used. To do so, create and set a FrameHandlerSink with at least one image buffer.

Sample:

For an example of how to use the addListener method, see Using a Callback Function.

See also: Grabber, Grabber::removeListener, Grabber::isListenerRegistered, GrabberListener, GrabberListener::tListenerType, GrabberListener::frameReady, FrameHandlerSink, FrameHandlerSink::create, FrameHandlerSink::setSnapMode

<< Grabber


Grabber::closeDev

Grabber::closeDev Method
Closes the currently active video capture device.
Syntax:
bool closeDev();
Return value:

true, if the device was closed successfully, or if no device was opened, false otherwise

See also: Grabber, Grabber::isDevOpen, Grabber::openDev

<< Grabber


Grabber::getAcqSizeMaxX

Grabber::getAcqSizeMaxX Method
Returns the width in pixels of the currently selected video format.
Syntax:
long getAcqSizeMaxX() const;
Return value:

The width in pixels.

Remarks:

This method was used in early versions of the library. Now, the VideoFormatItem::getSize method should be used instead. In order to determine the width of the image that will be rendered by the display, the method Grabber::getVideoDataDimension should be called.

See also: Grabber, Grabber::getAcqSizeMaxY, VideoFormatItem::getSize, Grabber::getVideoDataDimension

<< Grabber


Grabber::getAcqSizeMaxY

Grabber::getAcqSizeMaxY Method
Returns the height in pixels of the currently selected video format.
Syntax:
long getAcqSizeMaxY() const;
Return value:

The height in pixels.

Remarks:

This method was used in early versions of the library. Now, the VideoFormatItem::getSize method should be used instead. In order to determine the height of the image that will be rendered by the display, the method Grabber::getVideoDataDimension should be called.

See also: Grabber, Grabber::getAcqSizeMaxX, VideoFormatItem::getSize, Grabber::getVideoDataDimension

<< Grabber


Grabber::getActiveMemBuffer

Grabber::getActiveMemBuffer Method [Deprecated]

Returns the MemBuffer to which the current image is grabbed.
Syntax:
tMemBufferPtr getActiveMemBuffer() const;
Return value:

A pointer to the currently active memory buffer, or 0 if no buffer is active.

Remarks:

This method returns the currently active memory buffer. This is the buffer with the most recent complete frame. This method returns 0, if there is currently no buffer active.

Information:

This method is deprecated since version 3.0.
This method only works when using the deprecated FrameGrabberSink. When using the new FrameHandlerSink, use FrameHandlerSink::getLastAcqMemBuffer instead.

See also: Grabber, Grabber::getActiveMemBufferCollection, Grabber::setActiveMemBufferCollection, Grabber::tMemBufferPtr

<< Grabber


Grabber::getActiveMemBufferCollection

Grabber::getActiveMemBufferCollection Method [Deprecated]

This method returns a pointer to the currently active MemBufferCollection.
Syntax:
tMemBufferCollectionPtr getActiveMemBufferCollection() const;
Return value:

A pointer to the currently active memory buffer collection.

Remarks:

You can change the active memory buffer collection by creating a new collection with Grabber::newMemBufferCollection and making it active with Grabber::setActiveMemBufferCollection.

Information:

This method is deprecated since version 3.0.
Use the FrameHandlerSink instead of the FrameGrabberSink and retrieve the MemBufferCollection using FrameHandlerSink::getMemBufferCollection.

See also: Grabber, Grabber::getActiveMemBuffer, Grabber::newMemBufferCollection, Grabber::setActiveMemBufferCollection, Grabber::tMemBufferCollectionPtr

<< Grabber


Grabber::getAvailableFrameRates

Grabber::getAvailableFrameRates Method
Returns the frame rates supported by the device.
Syntax:
tFrameRateListPtr getAvailableFrameRates() const;
tFrameRateListPtr getAvailableFrameRates( const VideoFormatItem& item ) const;

Parameter | Description
item | If a video format is specified, the method returns the frame rates for this video format, else it returns the available frame rates for the current video format.
Return value:

A list of supported frame rates. This list may be empty or the smart_ptr may point to 0, if an error occurred (e.g. the device does not support frame rates).

See also: Grabber, Grabber::setFrameRate, Grabber::getFrameRate, Grabber::getCurrentActualFrameRate, Grabber::getAvailableFPS

<< Grabber


Grabber::getAvailableInputChannels

Grabber::getAvailableInputChannels Method
Returns a list of input channels supported by the current device.
Syntax:
tInChnListPtr getAvailableInputChannels()const;
Return value:

A pointer to a list of Grabber::tInputChannelItems on success or 0, if an error occurred.

Remarks:

This method generates a list of all input channels supported by the current video capture device. Some devices do not support input channels, therefore this list may be empty. You may pick one item out of this list and make it the active input channel with the method Grabber::setInputChannel.

See also: Grabber, Grabber::isInputChannelAvailableWithCurDev, Grabber::getInputChannel, Grabber::setInputChannel, Grabber::tInChnListPtr

<< Grabber


Grabber::getAvailableVideoCaptureDevices

Grabber::getAvailableVideoCaptureDevices Method
Returns a list of all currently available video capture devices.
Syntax:
tVidCapDevListPtr getAvailableVideoCaptureDevices() const;
Return value:

A pointer to a list of all available video capture devices. If an error occurred, 0 is returned.

Remarks:

Generates a list of all available video capture devices (compliant with WDM). This list is empty, if no devices are available.

See also: Grabber, Grabber::tVidCapDevListPtr, Grabber::getDev, Grabber::openDev

<< Grabber


Grabber::getAvailableVideoCompressors

Grabber::getAvailableVideoCompressors Method [Deprecated]

Returns a list of all video compressors available for avi output.
Syntax:
tCompressorListPtr getAvailableVideoCompressors() const;
Return value:

A pointer to a list of all available video codecs. If an error occurred, 0 is returned.

Remarks:

This method generates a list of all available compression filters (codecs). This list may be empty. The elements of the list are FilterInfoObjects.

Information:

This method is deprecated since version 3.0.
Use Codec::getAvailableCodecs instead.

See also: Grabber, AviSink, Grabber::tCompressorListPtr

<< Grabber


Grabber::getAvailableVideoFormats

Grabber::getAvailableVideoFormats Method
Returns a list of all video formats supported by the current video capture device according to the current video norm.
Syntax:
tVidFmtListPtr getAvailableVideoFormats() const;
tVidFmtListPtr getAvailableVideoFormats(const VideoNormItem& videonorm) const;

Parameter | Description
videonorm | If a video norm is specified, a list of all video formats that are compatible to this video norm is returned.
Return value:

A pointer to a list of VideoFormatItems or 0, if an error occurred.

Remarks:

This method creates a list of all video formats supported by the currently active video capture device. The available video formats are dependent on the currently selected video norm.

Note: This method returns 0, if there is no video capture device open.

See also: Grabber, Grabber::tVidFmtListPtr, Grabber::getVideoFormat, Grabber::setVideoFormat, VideoNormItem

<< Grabber


Grabber::getAvailableVideoNorms

Grabber::getAvailableVideoNorms Method
Returns a list of all video norms supported by the current video capture device.
Syntax:
tVidNrmListPtr getAvailableVideoNorms() const;
Return value:

A pointer to a list of VideoNormItems or 0, if an error occurred.

Remarks:

This method generates a list of all video norms (e.g. PAL, NTSC, ...) supported by the currently active video capture device. Some video devices (i.e. DCAM cameras) do not support video norms, therefore this list may be empty. Grabber::isVideoNormAvailableWithCurDev may be used to determine whether the device supports video norms.

Sample:

///////////////////////////////////////////////////////////////////////////////
//
// This example demonstrates how to query the available
// video norms and formats.
// If the current video capture device supports video norms, the available
// video formats depend on the current video norm. This example allows the user
// to select a video norm in this case, before it retrieves the video formats.
//
// If the current video capture device does not support video norms, the video
// formats are retrieved immediately.
//
#include "stdafx.h"
#include <conio.h>
#include "tisudshl.h"
using namespace _DShowLib_NAMESPACE;
int main(int argc, char* argv[])
{
    int choice, input;
    int i=0;
    // Initialize the library.
    if( !DShowLib::InitLibrary() )
    {
        fprintf( stderr, "The library could not be initialized ");
        fprintf( stderr, "(invalid license key?).\n");
        exit( 1 );
    }
    Grabber *grabber=new Grabber();
    Grabber::tVidCapDevListPtr pVidCapDevList = grabber->getAvailableVideoCaptureDevices();
    if( pVidCapDevList == 0 || pVidCapDevList->empty() )
    {
        delete grabber;
        exit( 1 ); // No device available.
    }
    // Retrieve all available video capture devices and display them.
    printf( "Available Grabbers: \n" );
    for ( Grabber::tVidCapDevListPtr::value_type::iterator it =
              pVidCapDevList->begin();
          it != pVidCapDevList->end();
          ++it )
    {
        printf( "[%i] %s\n", i++, it->c_str() );
    }
    // Prompt the user to select a video capture device.
    printf( "Your Choice: ");
    input=scanf( "%i", &choice );
    // Open the selected video capture device.
    if ( choice>=0 && choice < pVidCapDevList->size() )
    {
        grabber->openDev( pVidCapDevList->at( choice ) );
    }
    else
    {
        delete grabber;
        exit( 0 ); // No Grabber selected, exit the example.
    }
    // Check whether video norms are availble with the current video capture device.
    if ( grabber->isVideoNormAvailableWithCurDev() )
    {
        // Query for all available video norms.
        Grabber::tVidNrmListPtr pVidNrmList = grabber->getAvailableVideoNorms();
        if ( pVidNrmList == 0 )
        {
            fprintf( stderr, "Error: %s\n", grabber->getLastError() );
            delete grabber;
            exit( 1 );
        }
        while ( true )
        {
            i=0;
            // Display the available video norms.
            printf( "\n\nAvailable video norms:\n" );
            for ( Grabber::tVidNrmListPtr::value_type::iterator it =
                      pVidNrmList->begin();
                  it != pVidNrmList->end();
                  ++it )
            {
                printf( "[%i] %s\n", i++, it->c_str() );
            }
            // Prompt the user to select a video norm.
            printf( "Your choice (q to quit): ");
            // Exit the example if nothing was entered.
            input=scanf( "%i", &choice );
            if ( input == 0 )  break;
            if ( choice>=0 && choice <pVidNrmList->size() )
            {
                // Set the selected video norm to the video capture device before
                // retrieving the according video formats.
                grabber->setVideoNorm( pVidNrmList->at( choice ) );
                printf( "\n\nVideo Formats available for %s: \n", pVidNrmList->at( choice ).c_str() );
                // Now retrieve the video formats.
                Grabber::tVidFmtListPtr pVidFmtList = grabber->getAvailableVideoFormats();
                if ( pVidFmtList == 0 ) // No video formats available?
                {
                    fprintf( stderr, "Error: %s\n", grabber->getLastError() );
                    break;
                }
                i = 0;
                // List the available video formats.
                for ( Grabber::tVidFmtListPtr::value_type::iterator it =
                          pVidFmtList->begin();
                      it != pVidFmtList->end();
                      ++it )
                {
                    printf( "[%i] %s\n", i++, it->c_str() );
                }
            }
        }
    }
    else
    {
        // If the current video capture device does not support video norms,
        // the available video formats can be retrieved immediately.
        printf( "\n\nVideo Formats available: \n" );
        Grabber::tVidFmtListPtr pVidFmtList = grabber->getAvailableVideoFormats();
        if ( pVidFmtList == 0 ) // No video formats available?
        {
            fprintf( stderr, "Error: %s\n", grabber->getLastError() );
        }
        else
        {
            i = 0;
            // Display all available video formats on the screen.
            for ( Grabber::tVidFmtListPtr::value_type::iterator it =
                      pVidFmtList->begin();
                  it != pVidFmtList->end();
                  ++it )
            {
                printf( "[%i] %s\n", i++, it->c_str() );
            }
        }
    }
    delete grabber;
    printf("Press any key to continue");
    getch();
    return 0;
}
See also: Grabber, Grabber::isVideoNormAvailableWithCurDev, Grabber::getVideoNorm, Grabber::setVideoNorm, Grabber::tVidNrmListPtr

<< Grabber


Grabber::getCallback

Grabber::getCallback Method [Deprecated]

Returns a pointer to the currently active callback function
Syntax:
tsFrameEndCallback getCallback() const;
Return value:

A pointer to the currently installed callback function.

Remarks:

This method returns a pointer to the currently installed callback function.

Refer to Grabber::setCallback for more information.

This method will only work, if the grabber is opened and valid and may be called, if the grabber is in live mode.

Information:

This method is deprecated since version 3.0.
Please use the class GrabberListener instead.

See also: Grabber, Grabber::setCallback, tsFrameEndCallback

<< Grabber


Grabber::getCurReferenceTime

Grabber::getCurReferenceTime Method
Retrieves the current reference time.
Syntax:
bool getCurReferenceTime(REFERENCE_TIME& RTime) const;
Return value:

true on success, false otherwise.

Remarks:

The returned value in RTime specifies the time in 100 nanosecond (or 1/10000 millisecond) resolution. The resolution depends on the reference clock used internally by DirectShow (but it is mostly equivalent to QueryPerformanceCounter).

This method fails, if no reference clock is available.

See also: Grabber, Grabber::getGraphStartReferenceTime

<< Grabber


Grabber::getCurrentActualFrameRate

Grabber::getCurrentActualFrameRate Method
Returns the current actual frame rate.
Syntax:
long getCurrentActualFrameRate() const;
Return value:

The actual time between two frames in milliseconds. A return value of 0 indicates that an error occurred.

Remarks:

This method returns the actual time between two frames. This time may be greater than the desired time, returned by Grabber::getFrameRate.

This method is only available if a device is open and valid. Further the method does only work in live mode.

If the bandwidth is too low, the desired frame rate cannot be achieved. In this case getCurrentActualFrameRate would return a value greater than the default value of the video capture device or the passed value to Grabber::setFrameRate. Also the returned values of Grabber::getFrameRate and getCurrentActualFrameRate would differ. The returned value of getCurrentActualFrameRate would be bigger than the value of Grabber::getFrameRate.

It is recommended to call getCurrentActualFrameRate continuously to check the current achieved frame rate, because USB devices and 1394 devices can have variable frame rates.

If an error occurs or the method is not supported by the current video capture device, getCurrentActualFrameRate returns 0. GetLastError() will be set to one of the following values:

  • eNO_DEVICE_OPENED
  • eDEVICE_INVALID
  • eOPTION_NOT_AVAILABLE
  • eFUNC_ONLY_AVAIL_IN_LIVEMODE
See also: Grabber, Grabber::setFrameRate, Grabber::getFrameRate, Grabber::getAvailableFrameRates

<< Grabber


Grabber::getDefaultWindowPosition

Grabber::getDefaultWindowPosition Method
This method returns the current value of the grabber's default window position flag.
Syntax:
bool getDefaultWindowPosition();
Return value:

The value set by setDefaultWindowPosition().

If the return value is true, the grabber adjusts the live video display window to the width and height of the current video format. While this method returns true, it is not possible to change the grabber's video window size.

This method returns false, if the size of the window for the live video display is independent from the width and height of the current video format. In this mode, the size and position of the live video window may be set by calling Grabber::setDefaultWindowPosition.

See also: Grabber, Grabber::setDefaultWindowPosition, Grabber::getWindowPosition, Grabber::setWindowPosition

<< Grabber


Grabber::getDev

Grabber::getDev Method
Returns the currently active video capture device.
Syntax:
tVideoCaptureDeviceItem getDev() const;
Return value:

A VideoCaptureDeviceItem that represents the current video capture device. An invalid VideoCaptureDeviceItem is returned, on error, or if no video capture device is open.

See also: Grabber, Grabber::getAvailableVideoCaptureDevices

<< Grabber


Grabber::getExternalTransportMode

Grabber::getExternalTransportMode Method
Returns the current mode of the external transport control.
Syntax:
long getExternalTransportMode() const;
Return value:

The current mode of the external transport control or 0, if an error occurred. For possible modes refer to Grabber::setExternalTransportMode.

Remarks:

This method is only available, if a device is open and valid.

See also: Grabber, Grabber::setExternalTransportMode, Grabber::hasExternalTransport

<< Grabber


Grabber::getExternalTrigger

Grabber::getExternalTrigger Method
Returns true, if the external trigger is enabled.
Syntax:
bool getExternalTrigger() const;
Return value:

true, if the external trigger is enabled, false otherwise.

Remarks:

Returns true, if the external trigger is enabled, false otherwise. If an error occurs (e.g. the device has no external trigger), it returns false and sets the internal error value.

This method is only available, if a device is open and valid.

See also: Grabber, Grabber::hasExternalTrigger, Grabber::setExternalTrigger

<< Grabber


Grabber::getFlipH

Grabber::getFlipH Method
This method returns whether horizontal flipping is enabled.
Syntax:
bool getFlipH() const;
Return value:

true, if horizontal flipping is enabled, false otherwise.

See also: Grabber, Grabber::isFlipHAvailable, Grabber::setFlipH

<< Grabber


Grabber::getFlipV

Grabber::getFlipV Method
This method returns whether vertical flipping is enabled.
Syntax:
bool getFlipV() const;
Return value:

true, if vertical flipping is enabled, false otherwise.

See also: Grabber, Grabber::isFlipVAvailable, Grabber::setFlipV

<< Grabber


Grabber::getFrameCount

Grabber::getFrameCount Method
Read the internal frame counter.
Syntax:
DWORD getFrameCount() const;
Return value:

The current frame count.

Remarks:

This method returns the current value of the internal frame counter.

The internal frame counter increases automatically each time a frame is copied to the currently active MemBufferCollection.

The counter is reset by calling Grabber::setActiveMemBufferCollection, Grabber::setSinkType or Grabber::startLive.

See also: Grabber

<< Grabber


Grabber::getFrameRate

Grabber::getFrameRate Method
Returns the currently set time between two frames.
Syntax:
long getFrameRate() const;
Return value:

The desired time in milliseconds between the start of frame n and the start of frame n + 1. A return value of 0 indicates that an error occurred.

This time may be set with Grabber::setFrameRate.

In case of low bandwidth on the bus, the device may not be able to send frames according to the desired frame rate. Thus, the interval between to frames will become greater than the one specified by the desired frame rate. Call Grabber::getCurrentActualFrameRate in order to get the actual interval.

Remarks:

This method is only available, if a device is open and valid.

See also: Grabber, Grabber::setFrameRate, Grabber::getAvailableFrameRates, Grabber::getCurrentActualFrameRate

<< Grabber


Grabber::getGraphStartReferenceTime

Grabber::getGraphStartReferenceTime Method
This method retrieves the reference time at which the image stream (the filter graph) was started.
Syntax:
bool getGraphStartReferenceTime(REFERENCE_TIME& GraphStart) const;

Parameter | Description
GraphStart | Specifies a REFERENCE_TIME variable that will receive the reference time.
Return value:

true on success, false otherwise.

Remarks:

The returned value in GraphStart specifies the time in 100 nanosecond (or 1/10000 millisecond) resolution. The resolution depends on the reference clock used internally by DirectShow (but it is mostly equivalent to QueryPerformanceCounter).

If no reference clock is available, this method fails.

See also: Grabber, Grabber::getCurReferenceTime

<< Grabber


Grabber::getHWND

Grabber::getHWND Method
This method returns a handle to the window, which is used to display the live image.
Syntax:
HWND getHWND() const;
Return value:

A "window handle" or NULL, if no handle is set.

See also: Grabber, Grabber::setHWND

<< Grabber


Grabber::getInputChannel

Grabber::getInputChannel Method
Returns the currently active input channel. This method will fail, if there is no video capture device open.
Syntax:
tInputChannelItem getInputChannel() const;
Return value:

A Grabber::tInputChannelItem that represents the currently active input channel or an invalid Grabber::tInputChannelItem object, if the device does not support input channels or an error occurred.

See also: Grabber, VideoCaptureDeviceItem, Grabber::tInputChannelItem, AnalogChannelItem::isValid, Grabber::setInputChannel

<< Grabber


Grabber::getLastError

Grabber::getLastError Method
Returns information about an error that occurred, during the last library-method call.
Syntax:
Error getLastError();
Return value:

An Error object.

Remarks:

Returns the error that occurred during the last call to a method of this object. If no error occurred, eNO_ERROR is returned.

The MemBufferCollection has its own MemBufferCollection::getLastError method. Errors that occur in a method call to a MemBufferCollection object will be reported there.

Sample:
if( grabber->getLastError() )
{
    printf( "Error: %s\n", grabber->getLastError().c_str() );
}
See also: Grabber, Error, MemBufferCollection::getLastError

<< Grabber


Grabber::getProperty

Grabber::getProperty Method
Returns the actual value of a property of the current video capture device.
Syntax:
long getProperty( tCameraPropertyEnum CameraPropType ) const;
long getProperty( tVideoPropertyEnum VideoPropType ) const;

Parameter | Description
CameraPropType | Specifies the camera property to be queried. The possible properties are specified in Grabber::tCameraPropertyEnum.
VideoPropType | Specifies the video property to be queried. The possible properties are specified by Grabber::tVideoPropertyEnum.
Return value:

The current value of the given property.

Remarks:

This method returns the value of the specified property. The range of possible values can be determined by calling Grabber::getPropertyRange. Grabber::getPropertyDefault returns the default value for the specified property.

If an error occurred, 0 is returned, which may also be a valid property value. You should use Grabber::getLastError to determine whether an error occurred or not.

Note that the value for a property may only be queried, if "automatic mode" is disabled.

See also: Grabber, Grabber::getPropertyDefault, Grabber::getPropertyRange, Grabber::isPropertyAutomationAvailableWithCurDev, Grabber::isPropertyAutomationEnabled, Grabber::isPropertyAvailableWithCurDev, Grabber::setProperty, Grabber::tCameraPropertyEnum, Grabber::tVideoPropertyEnum

<< Grabber


Grabber::getPropertyDefault

Grabber::getPropertyDefault Method
This method returns the default value of a property.
Syntax:
long getPropertyDefault( tCameraPropertyEnum CameraPropType ) const;
long getPropertyDefault( tVideoPropertyEnum VideoPropType ) const;

Parameter | Description
CameraPropType | Specifies the camera property to be queried. The possible properties are specified in Grabber::tCameraPropertyEnum.
VideoPropType | Specifies the video property to be queried. The possible properties are specified by Grabber::tVideoPropertyEnum.
Return value:

The default value of the specified property.

See also: Grabber, Grabber::getProperty, Grabber::getPropertyRange, Grabber::setProperty, Grabber::tCameraPropertyEnum, Grabber::tVideoPropertyEnum

<< Grabber


Grabber::getPropertyRange

Grabber::getPropertyRange Method
Returns a tsPropertyRange structure specifying the range of possible property values.
Syntax:
tsPropertyRange getPropertyRange( tCameraPropertyEnum CameraType ) const;
tsPropertyRange getPropertyRange( tVideoPropertyEnum VideoType ) const;

Parameter | Description
CameraPropType | Specifies the camera property to be queried. The possible properties are specified in Grabber::tCameraPropertyEnum.
VideoPropType | Specifies the video property to be queried. The possible properties are specified by Grabber::tVideoPropertyEnum.
Return value:

A tsPropertyRange structure

See also: Grabber, Grabber::getPropertyDefault, Grabber::setProperty, Grabber::isPropertyAvailableWithCurDev, Grabber::tCameraPropertyEnum, Grabber::tVideoPropertyEnum, tsPropertyRange

<< Grabber


Grabber::getSinkType

Grabber::getSinkType Method
Returns the current output method of image streams.
Syntax:
const GrabberSinkType& getSinkType() const;
Return value:

A reference to a GrabberSinkType.

Remarks:

This method returns the currently selected sink type.

For more information about sink types refer to AviSink and FrameGrabberSink.

See also: Grabber, Grabber::setSinkType

<< Grabber


Grabber::getUserMemBufferSize

Grabber::getUserMemBufferSize Method [Deprecated]

Calculates the required size for a user allocated memory buffer.
Syntax:
DWORD getUserMemBufferSize() const;
Return value:

The number of bytes required for a user allocated buffer.

Remarks:

This method returns the number of bytes required for an user allocated image buffer, according to the current color format and region of interest settings.

Information:

This method is deprecated since version 3.0.
Use the FrameHandlerSink instead of the FrameGrabberSink and specify the MemBufferCollection in FrameHandlerSink::create.

See also: Grabber, Grabber::newMemBufferCollection

<< Grabber


Grabber::getVideoFormat

Grabber::getVideoFormat Method
This method returns the currently selected video format or an invalid object, if no video format is set (ie. the device is not open).
Syntax:
VideoFormatItem getVideoFormat() const;
Return value:

A VideoFormatItem object, or an invalid object, if an error occurred.

See also: Grabber, Grabber::getAvailableVideoFormats, Grabber::setVideoFormat

<< Grabber


Grabber::getVideoNorm

Grabber::getVideoNorm Method
This method returns the currently selected video norm or an invalid object, if no video norm is selected.
Syntax:
VideoNormItem getVideoNorm() const;
Return value:

A VideoNormItem or an invalid object, if no video norm is set.

See also: Grabber, Grabber::setVideoNorm

<< Grabber


Grabber::getWindowPosition

Grabber::getWindowPosition Method
This method retrieves the current position and size of the grabber's live video window.
Syntax:
bool getWindowPosition( long& posx, long& posy, long& width, long& height);

Parameter | Description
posx | Receives the x-coordinate of the upper left hand corner of the video window.
posy | Receives the y-coordinate of the upper left hand corner of the video window.
width | Receives the width of the video window, defaults to the width of the video format.
height | Receives the height of the video window, defaults to the height of the video format.
Return value:

true on success, false otherwise.

Sample:

This example demonstrates how to retrieve the size and position of the grabber's live video window and store them into four long variables.

long posx;
long posy;
long width;
long height;
if( grabber.getWindowPosition( posx, posy, width, height ) == true )
{
    printf("Current window position is %d %d %d %d\n",posx, posy, width, height);
}
See also: Grabber, Grabber::setWindowPosition, Grabber::setWindowSize, Grabber::setDefaultWindowPosition, Grabber::getDefaultWindowPosition

<< Grabber


Grabber::hasExternalTransport

Grabber::hasExternalTransport Method
Returns true, if the device has an external transport control.
Syntax:
bool hasExternalTransport() const;
Return value:

true, if the current device has an external transport control, false otherwise.

Remarks:

Returns true, if the current device has an external transport control. DV cameras have such a control.

This method is only available, if a device is open and valid.

See also: Grabber, Grabber::getExternalTransportMode, Grabber::setExternalTransportMode

<< Grabber


Grabber::hasExternalTrigger

Grabber::hasExternalTrigger Method
Returns true, if the current device has an external trigger.
Syntax:
bool hasExternalTrigger() const;
Return value:

true, if the current device has an external trigger, false otherwise.

Remarks:

This method is only available, if a device is open and valid.

See also: Grabber, Grabber::getExternalTrigger, Grabber::setExternalTrigger

<< Grabber


Grabber::isCountOfFramesDroppedAvailable

Grabber::isCountOfFramesDroppedAvailable Method
Returns whether the device supports retrieving the current dropped frames counter.
Syntax:
bool isCountOfFramesDroppedAvailable() const;
Return value:

true, if the device supports a dropped frames counter, false otherwise.

Information:

Introduced in version 2.0
See also: Grabber, Grabber::getCountOfFramesDropped, Grabber::getCountOfFramesNotDropped

<< Grabber


Grabber::isDevOpen

Grabber::isDevOpen Method
Checks whether a video capture device is opened.
Syntax:
bool isDevOpen() const;
Return value:

true, if a device is associated with this object, false otherwise.

Remarks:

Checks whether a video capture device is associated with this object.

If the device was opened with Grabber::openDev and has become invalid in the meantime (e.g. the device has been unplugged), this method will still return true. The Grabber::isDevValid method can be used to determine whether the video capture device is accessible.

See also: Grabber, Grabber::closeDev, Grabber::isDevValid, Grabber::openDev

<< Grabber


Grabber::isDevValid

Grabber::isDevValid Method
Checks whether the video capture device associated with this object still exists. A video capture device may become invalid at any time (e.g. if the device has been unplugged).
Syntax:
bool isDevValid() const;
Return value:

true, if a device is associated with this object and present in the system, false otherwise.

See also: Grabber, Grabber::isDevOpen

<< Grabber


Grabber::isFlipHAvailable

Grabber::isFlipHAvailable Method
This method returns whether horizontal flipping is available.
Syntax:
bool isFlipHAvailable() const;
Return value:

true, if horizontal flipping is available, false otherwise.

See also: Grabber, Grabber::setFlipH, Grabber::getFlipH

<< Grabber


Grabber::isFlipVAvailable

Grabber::isFlipVAvailable Method
This method returns whether vertical flipping is available.
Syntax:
bool isFlipVAvailable() const;
Return value:

true, if vertical flipping is available, false otherwise.

See also: Grabber, Grabber::setFlipV, Grabber::getFlipV

<< Grabber


Grabber::isInputChannelAvailableWithCurDev

Grabber::isInputChannelAvailableWithCurDev Method
This method checks whether the currently active video capture device supports input channels.
Syntax:
bool isInputChannelAvailableWithCurDev() const;
Return value:

true, if the device supports input channels, false otherwise.

Remarks:

A list of available input channels can be queried with Grabber::getAvailableInputChannels.

See also: Grabber, Grabber::getAvailableInputChannels

<< Grabber


Grabber::isListenerRegistered

Grabber::isListenerRegistered Method
This method checks whether the specified callback handler is registered for the specified events.
Syntax:
bool isListenerRegistered( GrabberListener* pListener, DWORD callback = -1 );

Parameter | Description
pListener | Specifies a pointer to a GrabberListener callback handler that is to be checked.
callback | Specifies the events to be checked. It can be a combination of GrabberListener::tListenerTypes. To combine two or more listener types, use a binary OR operation. It defaults to -1. -1 is the combination of all available GrabberListener::tListenerTypes.
Return value:

true, if the callback handler is registered for at least one of the specified events. Otherwise, false is returned.

Sample:

This example shows how to register a callback handler that is derived from GrabberListener for a set of events. It shows also how to unregister the object for the events for which it was registered. Finally, it shows how to delete the callback handler object in a safe way.

Grabber *grabber      = new DShowLib::Grabber();
CListener *pcListener = new CListener();    // Create the GrabberListener object.
                                            // CListener is derived from
                                            // GrabberListener.
// Register the pcListener object to the Grabber's GrabberListener objects list.
grabber->addListener( pcListener, DShowLib::GrabberListener::eFRAMEREADY|
                                  DShowLib::GrabberListener::eOVERLAYCALLBACK );
grabber->startLive( true );            // Start the grabber
// Events are handled now
fflush(stdin);
printf("Press [enter] to stop!");
getchar();
// The GrabberListener object must be unregistered for the events
// for which it was registered, before it can be deleted.
// First, unregister it for the frame ready event.
grabber->removeListener(pcListener, DShowLib::GrabberListener::eFRAMEREADY);
// Second, unregister it for the overlay callback event.
grabber->removeListener(pcListener, DShowLib::GrabberListener::eOVERLAYCALLBACK);
// Wait until all remove requests have been processed
while( grabber->isListenerRegistered( pcListener, eALL) )
{
    Sleep( 0 ); // Wait
}
// Now, the application can be sure that the CListener methods
// are no longer called by the Grabber. It is now safe to delete the
// CListener object.
delete pcListener;
grabber->stopLive();            // Stop the grabber
delete grabber;
See also: Grabber, Grabber::addListener, Grabber::removeListener, Grabber::isListenerRegistered, GrabberListener, GrabberListener::tListenerType

<< Grabber


Grabber::isLive

Grabber::isLive Method
Checks whether the current video capture device is in live mode.
Syntax:
bool isLive() const;
Return value:

true ,if the grabber is currently in live mode, false otherwise.

Remarks:

If the grabber is in live mode, images are continuously grabbed and either copied to the screen or to a memory buffer. The behavior of the grabber, while in live mode, is selected with the Grabber::startLive method.

See also: Grabber, Grabber::startLive, Grabber::stopLive

<< Grabber


Grabber::isPropertyAutomationAvailableWithCurDev

Grabber::isPropertyAutomationAvailableWithCurDev Method
Checks whether the current video capture device is capable of setting a specific property automatically.
Syntax:
bool isPropertyAutomationAvailableWithCurDev(  tCameraPropertyEnum CameraPropType ) const;
bool isPropertyAutomationAvailableWithCurDev(  VideoPropertyEnum VideoPropType ) const;

Parameter | Description
CameraPropType | @@NONSENSE@@ Specifies the camera property which default value should be determined. The possible properties are specified in Grabber::tCameraPropertyEnum.
VideoPropType | @@NONSENSE@@ Specifies the video property which default value should be determined. The possible properties are specified by Grabber::tVideoPropertyEnum.
Return value:

true, if the device is capable of setting the value for the given property automatically, false otherwise.

Remarks:

Note that the capability of setting a certain property automatically does not mean that all device properties may be set automatically. The Grabber::setProperty method may be used to enable automation of a certain property for the current video capture device.

See also: Grabber, Grabber::isPropertyAutomationEnabled, Grabber::setProperty, Grabber::tCameraPropertyEnum, Grabber::tVideoPropertyEnum

<< Grabber


Grabber::isPropertyAutomationEnabled

Grabber::isPropertyAutomationEnabled Method
Checks whether the automation for a specific property is enabled.
Syntax:
bool isPropertyAutomationEnabled( tCameraPropertyEnum CameraPropType ) const;
bool isPropertyAutomationEnabled( VideoPropertyEnum VideoPropType) const;

Parameter | Description
CameraPropType | @@NONSENSE@@ Specifies the camera property which automation status should be determined. The possible properties are specified in Grabber::tCameraPropertyEnum.
VideoPropType | @@NONSENSE@@ Specifies the video property which automation status should be determined. The possible properties are specified by Grabber::tVideoPropertyEnum.
Return value:

true, if automation is enabled for the given property, false otherwise.

Remarks:

Checks whether a device property is set automatically by the video capture device.

Some video capture devices are capable of setting certain properties such as brightness, contrast or focus automatically. If the property automation is enabled, it cannot be set manually by calling the Grabber::setProperty ( tCameraPropertyEnum type, newPropertyValue ); method. The automation must be disabled with Grabber::setProperty ( tCameraPropertyEnum type, false ); before setting the affected value manually.

See also: Grabber, Grabber::getProperty, Grabber::setProperty, Grabber::isPropertyAvailableWithCurDev, Grabber::tCameraPropertyEnum, Grabber::tVideoPropertyEnum

<< Grabber


Grabber::isPropertyAvailableWithCurDev

Grabber::isPropertyAvailableWithCurDev Method
Checks whether the current video capture device supports the manual setting of a specific property.
Syntax:
bool isPropertyAvailableWithCurDev( tCameraPropertyEnum CameraPropType ) const;
bool isPropertyAvailableWithCurDev( tVideoPropertyEnum VideoPropType ) const;

Parameter | Description
CameraPropType | Specifies the camera property type that will be checked for availability. The properties are specified in Grabber::tCameraPropertyEnum.
VideoPropType | Specifies the video property type that will be checked for availability. The properties are specified in Grabber::tVideoPropertyEnum.
Return value:

true, if the device supports this property, false otherwise.

Remarks:

This method checks whether the current video capture device supports the setting of the value for a specific property.

Most video capture devices support the setting of just a few device properties. To check whether the device supports the setting of the property automatically, use the Grabber::isPropertyAutomationAvailableWithCurDev method.

See also: Grabber, Grabber::getProperty, Grabber::getPropertyDefault, Grabber::getPropertyRange, Grabber::isPropertyAutomationEnabled, Grabber::isPropertyAutomationAvailableWithCurDev, Grabber::setProperty, Grabber::tCameraPropertyEnum, Grabber::tVideoPropertyEnum

<< Grabber


Grabber::isVideoNormAvailableWithCurDev

Grabber::isVideoNormAvailableWithCurDev Method
Checks whether the current video capture device supports the selection of the video norm.
Syntax:
bool isVideoNormAvailableWithCurDev() const;
Return value:

true if the device supports the selection of the video norm, false otherwise.

Remarks:

This function checks whether the current video capture device supports different video norms (e.g. PAL, NTSC,...). Not all devices support the selection of the video norm.

Note: This function fails, if there is no video capture device open (see Grabber::openDev )

See also: Grabber, Grabber::getAvailableVideoNorms

<< Grabber


Grabber::newMemBufferCollection

Grabber::newMemBufferCollection Method [Deprecated]

Creates a new memory buffer collection.
Syntax:
tMemBufferCollectionPtr newMemBufferCollection( DWORD count = 1 ) const;
tMemBufferCollectionPtr newMemBufferCollection( SIZE size,
                                                tColorformatEnum colorformat,
                                                DWORD count = 1 ) const;
tMemBufferCollectionPtr newMemBufferCollection( SIZE size,
                                                tColorformatEnum colorformat,
                                                DWORD buffersize,
                                                BYTE* buffers[],
                                                DWORD count ) const;
tMemBufferCollectionPtr newMemBufferCollection(  DWORD buffersize,
                                                 BYTE* buffers [],
                                                 DWORD count ) const;

Parameter | Description
size | Specifies the size of the frames to be stored in the collection.
count | Specifies the number of frames to be stored in the collection. This value should be at least 1
colorformat | Specifies the color format of the frames to be stored in the collection.
buffers | An array of pointers to user allocated buffers.
buffersize | The size of a single user allocated buffer.
Return value:

A pointer to the MemBufferCollection.

Remarks:

This method creates a new MemBufferCollection.

An error will be generated, if count is 0.

Giving just a count value as an argument will create a MemBufferCollection which fits the current settings of the video capture device. It will contain count distinct MemBuffers. The memory required will be allocated by this method.

If you provide a size, colorformat and count parameter to the constructor, a MemBufferCollection which fits these parameters will be created and memory for the buffers will be allocated.

You may also provide buffers to the MemBufferCollection which were previously allocated elsewhere in your application, by passing an array of pointers and information about the size of each buffer to the constructor. This should be handled very carefully as actions on the MemBufferCollection will take place in kernel-mode. Thus providing wrong buffersize information to the constructor will lead almost certainly to a system crash.

Information:

This method is deprecated since version 3.0.
Use the FrameHandlerSink instead of the FrameGrabberSink and create the MemBufferCollection with FrameHandlerSink::create or MemBufferCollection::create.

See also: Grabber, Grabber::setActiveMemBufferCollection, Grabber::getUserMemBufferSize

<< Grabber


Grabber::openDev

Grabber::openDev Method
Opens a video capture device for grabbing.
Syntax:
bool openDev( const VideoCaptureDeviceItem& dev );
bool openDev( const char* dev );
bool openDev( const std::string& devstring );
bool openDev( const std::wstring& devstring );
bool openDev( const __int64& serial );

Parameter | Description
VideoCaptureDeviceItem& dev | Specifies the video device to be opened.
char* dev | Specifies the name of the video capture device to be opened.
devstring | Specifies the name of the video capture device to be opened.
serial | Specifies the serial number of the video capture device to be opened.
Return value:

true, if the device was opened successfully, false, otherwise.

Remarks:

An already opened device will be closed before opening a new one.

openDev is usually one of the first actions on the Grabber. Querying for device capabilities such as the available video formats ( Grabber::getAvailableVideoFormats ) is only possible, if a device is open. You can get a VideoCaptureDeviceItem by iterating the list generated by Grabber::getAvailableVideoCaptureDevices.

After opening the device, a video format has to be set to a valid one, using Grabber::setVideoFormat.

Please note that even if you have a device opened with Grabber::openDev, it may become invalid at any time (e.g. if the device is unplugged). A device which has become invalid will not automatically be reopened, if it gets plugged in again. You should rather check whether the device is still valid using Grabber::isDevValid by time and react accordingly.

See also: Grabber, Grabber::closeDev, Grabber::getAvailableVideoCaptureDevices, Grabber::isDevOpen

<< Grabber


Grabber::removeListener

Grabber::removeListener Method
This method unregisters a callback handler object for the specified events.
Syntax:
bool removeListener( GrabberListener* pListener, DWORD callback = -1 );

Parameter | Description
pListener | Specifies a pointer to a GrabberListener derived callback handler object that is to be unregistered.
callback | Specifies the events that may not be handled by the specified callback handler anymore. To combine two or more listener types, use a binary OR operation. It defaults to -1. -1 is the combination of all possible GrabberListener::tListenerTypes.
Return value:

true, if the callback handler that was specified in pListener could be unregistered successfully. This is only possible, if no callbacks for the specified events are currently being processed. If callbacks are being processed, the grabber stores the remove request for the handler and returns false. As soon as all pending callbacks are finished, the stored remove request is processed.

Remarks:

If an application tries to unregister a callback handler for all events for which it was registered, it may only destroy the callback handler, if removeListener returns true. If false is returned, the application has to wait until the remove request is carried out by calling Grabber::isListenerRegistered in a loop. It is important to do a Sleep(0) in the loop, otherwise the loop would put too much load on the processor and the pending callbacks may not get CPU time. This would cause a deadlock. As soon as Grabber::isListenerRegistered returns true, the callback handler may be destroyed.

Sample:

This example shows how to register a callback handler that is derived from GrabberListener for a set of events. It shows also how to unregister the object for the event for which it was registered. Finally, it shows how to delete the callback handler object in a safe way.

Grabber *grabber      = new DShowLib::Grabber();
CListener *pcListener = new CListener();    // Create the GrabberListener object.
                                            // CListener is derived from
                                            // GrabberListener.
// Register the pcListener object to the Grabber's GrabberListener objects list.
grabber->addListener( pcListener, DShowLib::GrabberListener::eFRAMEREADY|
                                  DShowLib::GrabberListener::eOVERLAYCALLBACK );
grabber->startLive( true );            // Start the grabber
// Events are handled now
fflush(stdin);
printf("Press [enter] to stop!");
getchar();
// The GrabberListener object must be unregistered for the events
// for which is was registered, before it can be deleted.
// First, unregister it for the frame ready event.
grabber->removeListener(pcListener, DShowLib::GrabberListener::eFRAMEREADY);
// Second, unregister it for the overlay callback event.
grabber->removeListener(pcListener, DShowLib::GrabberListener::eOVERLAYCALLBACK);
// Wait until all remove requests have been processed
while( grabber->isListenerRegistered( pcListener, eALL) )
{
    Sleep( 0 ); // Wait
}
// Now, the application can be sure that the CListener methods
// are no longer called by the Grabber. It is now safe to delete the
// CListener object.
delete pcListener;
grabber->stopLive();            // Stop the grabber
delete grabber;
See also: Grabber, Grabber::addListener, Grabber::isListenerRegistered, GrabberListener, GrabberListener::tListenerType

<< Grabber


Grabber::setActiveMemBufferCollection

Grabber::setActiveMemBufferCollection Method [Deprecated]

Sets the MemBufferCollection in which the grabbed images will be stored.
Syntax:
bool setActiveMemBufferCollection( tMemBufferCollectionPtr pBuffer );

Parameter | Description
pBuffer | A pointer to a MemBufferCollection, as returned by Grabber::newMemBufferCollection.
Return value:

true, if the collection was set successfully, false, if an error occurred.

Remarks:

This method sets the MemBufferCollection to be used for grabbing.

The active MemBufferCollection contains the buffers into which grabbed images will be written to.

A call to this method will fail, if the grabber is in live mode.

Please note that the GrabberListener::frameReady method is only called, if an active MemBufferCollection and a sink type is set. Otherwise, the frameReady event will never be called. A call to Grabber::setVideoFormat and Grabber::setSinkType removes the MemBufferCollection from the sink. Therefore, the sequence of calls to the methods mentioned above has to be:

  • Grabber::setVideoFormat
  • Grabber::setSinkType
  • Grabber::setActiveMemBufferCollection
  • Grabber::addListener
Information:

This method is deprecated since version 3.0.
Use the FrameHandlerSink instead of the FrameGrabberSink and specify the MemBufferCollection in FrameHandlerSink::create or FrameHandlerSink::setMemBufferCollection.

See also: Grabber, Grabber::getActiveMemBuffer, Grabber::getActiveMemBufferCollection

<< Grabber


Grabber::setCallback

Grabber::setCallback Method [Deprecated]

Sets a callback function.
Syntax:
bool setCallback( const tsFrameEndCallback& callback = tsFrameEndCallback() );

Parameter | Description
callback | A structure that describes the callback function.
Return value:

true, if the callback could be successfully installed, false otherwise.

Remarks:

The function is called on a frame end. Only one callback function may be set, subsequent calls to setCallback will override the previous function. The callback function will be started as a new thread. However, only one thread at the time will get started.

Note that if you grab more images than the actual MemBufferCollection can store and the callback function takes a lot of time to run, the buffer which is processed by the callback function may get filled with a new image while the function is still running.

If the callback function takes more time to run than the grabber needs to grab one frame, the next callback function will be called on the first frame-end-event on which the other callback function is no longer running. In this case some frames will be missed, but these frames will be stored in the active MemBufferCollection.

Grabber::snapImages and (if the grabber is set to continuous grab mode with an appropriate FrameGrabberSink ) Grabber::stopLive will block until the last callback function has returned.

A callback function may only be set, if the grabber is opened, valid and not in live mode. See Grabber::isDevOpen, Grabber::isDevValid and Grabber::isLive for information on how to query for these grabber states.

The callback function should be defined like the following:

void callBackFunc( void *data, tMemBufferPtr buffer, unsigned long ctr );

Where the parameters have the following meaning:

Parameter | Description
data | A pointer to user data. This is the pointer you provide with setCallback.
buffer | A pointer to the buffer where the just grabbed image is stored.
ctr | This is the value of the internal frame counter at the time the frame was grabbed. (See Grabber::getFrameCount )

To set a callback function, the pointer to the function and a pointer to the user data have to be put into a structure of type tsFrameEndCallback. See the code example on how to do this.

Information:

This method is deprecated since version 3.0.
Please use the class GrabberListener instead.

See also: Grabber, Grabber::getCallback

<< Grabber


Grabber::setDefaultWindowPosition

Grabber::setDefaultWindowPosition Method
Enables or disables the default window size lock of the video window.
Syntax:
bool setDefaultWindowPosition( bool bDefault );

Parameter | Description
bDefault | If bDefault is set to true, the grabber adjusts the live video window display to the width and height of the current video format. In this mode, it is not possible to change the grabber's video window size. If bDefault is set to false, the size of the window for the live video display is independent from the width and height of the current video format. In this mode, the size and position of the live video window may be set by calling setDefaultWindowPosition. The default value is true.
Return value:

true on success, false otherwise.

Remarks:

This Method is used to enable or disable automatic resizing of the live video window to the width and height of the current video format. The size of the live video window can only be set independently from the width and height of the current video format, if automatic resizing is disabled.

If an application needs to fit the video window into a control's window, the parameter bDefault must be set to false.

Setting pDefault to true, sets the size of the video window immediately to the width and height of the current video format. A subsequent call to Grabber::setWindowPosition fails, because the size of the video window is dependent on the current video format.

See also: Grabber, Grabber::getDefaultWindowPosition, Grabber::getWindowPosition, Grabber::setWindowPosition, Grabber::setWindowSize

<< Grabber


Grabber::setExternalTransportMode

Grabber::setExternalTransportMode Method
Sets a new mode for the external transport control.
Syntax:
bool setExternalTransportMode( long mode );

Parameter | Description
mode | Specifies the new mode the external tranport control should be set to.
Return value:

true on success, false otherwise.

Remarks:

This method sets the external transport control to a new mode. This method is only available, if a device is open and valid.

Possible values for the mode parameter may be (in the DirectShow documentation under IAMExtTransport::put_Mode):

Value | Description
ED_MODE_PLAY | Play
ED_MODE_STOP | Stop
ED_MODE_FREEZE | Freeze (pause)
ED_MODE_THAW | Resume
ED_MODE_FF | Fast forward
ED_MODE_REW | Rewind
ED_MODE_RECORD | Record
ED_MODE_RECORD_STROBE | Record single frame
ED_MODE_STEP_FWD | Single step forward
ED_MODE_STEP_REV | Single step backward
See also: Grabber, Grabber::hasExternalTransport, Grabber::getExternalTransportMode

<< Grabber


Grabber::setExternalTrigger

Grabber::setExternalTrigger Method
Enables/disables the external trigger.
Syntax:
bool setExternalTrigger( bool newValue );

Parameter | Description
newValue | If set to true, the external trigger will be enabled. If set to false, it will be disabled
Return value:

true on success, false otherwise.

Remarks:

Enables/disables the external trigger of the current device. Returns true, if the operation was successful, false, otherwise.

This method is only available, if a device is open and valid. If live mode is active, this method is not available. Calling setExternalTrigger while live mode is active returns false.

See also: Grabber, Grabber::hasExternalTrigger, Grabber::getExternalTrigger

<< Grabber


Grabber::setFlipH

Grabber::setFlipH Method
Specifies whether all frames of an image stream should be flipped horizontally.
Syntax:
bool setFlipH( bool flip = true );

Parameter | Description
flip | Specifies whether the frames are flipped or not. true means: all frames will be flipped. false means: all frames will not be flipped.
Return value:

true on success, false otherwise.

See also: Grabber, Grabber::isFlipHAvailable, Grabber::getFlipH, Grabber::setFlipV

<< Grabber


Grabber::setFlipV

Grabber::setFlipV Method
Specifies whether all frames of an image stream will be flipped vertically.
Syntax:
bool setFlipV( bool flip = true );

Parameter | Description
flip | Specifies whether the frames are flipped or not. true means: all frames will be flipped. false means: all frames will not be flipped.
Return value:

true on success, false otherwise.

See also: Grabber, Grabber::isFlipVAvailable, Grabber::getFlipV, Grabber::setFlipH

<< Grabber


Grabber::setFrameRate

Grabber::setFrameRate Method
Sets the time between two frames.
Syntax:
bool setFrameRate( long rate );

Parameter | Description
rate | Specifies the frame rate in milliseconds between the start of frame n and the start of frame n + 1.
Return value:

true on success, false otherwise.

Remarks:

This method is only available, if a device is open and valid. Furthermore, the method cannot set a frame rate in live mode.

Valid values for rate must be retrieved from a list, which can be retrieved by Grabber::getAvailableFrameRates. Any other value an application tries to pass will result in an error.

If an application wants to set a frame rate of 20 frames per second, a value of 50 must be passed to setFrameRate (1000 / 20 = 50). If the bandwidth is too low, the desired frame rate cannot be achieved. In this case Grabber::getCurrentActualFrameRate returns a value greater than the passed value (here 50).

See also: Grabber, Grabber::getFrameRate, Grabber::getAvailableFrameRates, Grabber::getCurrentActualFrameRate

<< Grabber


Grabber::setHWND

Grabber::setHWND Method
Sets the handle to the window in which the live image will be displayed.
Syntax:
bool setHWND( HWND hwnd );

Parameter | Description
hwnd | A handle to a window.
Return value:

true on success, false otherwise

See also: Grabber, Grabber::getHWND, Grabber::startLive

<< Grabber


Grabber::setInputChannel

Grabber::setInputChannel Method
Sets the input channel of the currently active video capture device.
Syntax:
bool setInputChannel( const tInputChannelItem& inChnItem );
bool setInputChannel( DWORD channel );
bool setInputChannel( const std::string& inputchannel );
bool setInputChannel( const std::wstring& inputchannel );

Parameter | Description
inChnItem | Specifies the input channel. A list of available input channels may be obtained by calling Grabber::getAvailableInputChannels.
channel | Specifies the input channel as a numerical index. The index is the position of the desired input channel in the list of available input channels, starting at 0.
inputchannel | Specifies the input channel as a string representation.
Return value:

true, if the channel could be changed successfully, false otherwise.

Remarks:

Not all devices provide channels. In order to determine whether the selection of an input channel is supported by the current device you can use Grabber::isInputChannelAvailableWithCurDev.

See also: Grabber, Grabber::isInputChannelAvailableWithCurDev, Grabber::getAvailableInputChannels, Grabber::getInputChannel

<< Grabber


Grabber::setProperty

Grabber::setProperty Method
This method sets the value for a device property of the current video capture device to a specific value or activates/deactivates the "automatic mode" for this property.
Syntax:
bool setProperty( tCameraPropertyEnum CameraPropType, bool autom );
bool setProperty( tVideoPropertyEnum VideoPropType, bool autom );
bool setProperty( tCameraPropertyEnum CameraPropType, long val );
bool setProperty( tVideoPropertyEnum VideoPropType, long val );

Parameter | Description
CameraPropType | Specifies the camera property to be set. The possible properties are specified by Grabber::tCameraPropertyEnum.
VideoPropType | Specifies the video property to be set. The possible properties are specified by Grabber::tVideoPropertyEnum.
autom | Specifies whether "automatic mode" will be enabled. true means: enable "automatic mode" and ignore the val parameter false means: disable "automatic mode" and use the val parameter
val | Set the property to the value val. The value should be in the range returned by Grabber::getPropertyRange for this property or an error occurs. The setting of a value will only work, if "automatic mode" is not specified and the property is supported by the currently active device.
Return value:

true, if the property was changed successfully, false otherwise.

Remarks:

A specific device supports only a subset of all defined properties. You can check whether a property is supported by the currently active device by calling Grabber::isPropertyAvailableWithCurDev.

"Automatic mode" is available only for a subset of the supported properties. To determine whether "automatic mode" is available for a certain property, call Grabber::isPropertyAutomationAvailableWithCurDev

To determine whether a property is set to "automatic mode" you have to call Grabber::isPropertyAutomationEnabled.

The default value for a property may be queried by calling Grabber::getPropertyDefault.

See also: Grabber, Grabber::getProperty, Grabber::getPropertyDefault, Grabber::getPropertyRange, Grabber::isPropertyAutomationEnabled, Grabber::isPropertyAvailableWithCurDev, Grabber::isPropertyAutomationAvailableWithCurDev, Grabber::tCameraPropertyEnum, Grabber::tVideoPropertyEnum

<< Grabber


Grabber::setSinkType

Grabber::setSinkType Method
Sets the format of the sink. A sink specifies the output target of an image stream. A sink may only be set, if the image stream is in neither live mode, nor prepared mode.
Syntax:
bool setSinkType( smart_ptr<GrabberSinkType> pNewSink );

Parameter | Description
pNewSink | Specifies the new sink type.
Return value:

Description | Description
true | The sink type was changed successfully.
false | An error occurred.
Remarks:

For more information about sink types, please refer to: FrameHandlerSink and MediaStreamSink
Sample:

This example demonstrates how to set a MediaStreamSink:

Grabber grabber;
if( !setupDeviceFromFile( grabber ) )
{
    return -1;
}

tCodecListPtr pCodecs = Codec::getAvailableCodecs();

// Display all codec names on the screen.
int choice = presentUserChoice( toStringArrayPtrListPtr( pCodecs ) );
if( choice == -1 )
{
    return -1;
}

// Create an MediaStreamSink to record an AVI file with the selected CoDec
tMediaStreamSinkPtr pSink = MediaStreamSink::create(
    MediaStreamContainer::create( MSC_AviContainer ), pCodecs->at( choice ) );

// Set the filename.
pSink->setFilename( filename );

// The sink is initially paused, so that no video data is written to the file.
pSink->setSinkMode( GrabberSinkType::ePAUSE );

// Set pSink as the current sink.
grabber.setSinkType( pSink );

// Start the live mode. The live video will be displayed but no images will be written
// to the AVI file because pSink is in pause mode.
if( !grabber.startLive( true ) )
{
    std::cerr << grabber.getLastError().toString() << std::endl;
    return -1;
}

std::cout << "Press [enter] to start capturing!";
std::cin.get();

// Start the sink. The image stream is written to the AVI file.
pSink->setSinkMode(GrabberSinkType::eRUN );

std::cout << "Video recording started." << std::endl;
std::cout << "Press [enter] to stop capturing!";
std::cin.get();

// Pause the sink. This stops writing the image stream to the AVI file.
// A subsequent call to setSinkMode with GrabberSinkType::eRUN as the
// parameter would restart AVI recording.
pSink->setSinkMode(GrabberSinkType::ePAUSE );

std::cout << "Video recording stopped." << std::endl;

// Stop the live mode. This stops writing images to the AVI file if the mode is not
// GrabberSinkType::ePAUSE. The AVI file is closed.
grabber.stopLive();
See also: Grabber, Grabber::startLive, Grabber::getSinkType, MediaStreamSink, FrameHandlerSink

<< Grabber


Grabber::setVideoFormat

Grabber::setVideoFormat Method
This method sets the video format to be used by the currently active video capture device.
Syntax:
bool setVideoFormat( const VideoFormatItem& videoformat );
bool setVideoFormat( const std::string& videoformatstring );
bool setVideoFormat( const std::wstring& videoformatstring );

Parameter | Description
videoformat | Specifies the new video format to be used by the currently active video capture device.
videoformatstring | Specifies the name of the new video format to be used by the currently active video capture device.
Return value:

true, if the video format could be changed successfully, false otherwise.

Remarks:

This method sets the video format to be used by the current video capture device. The selectable video formats depend on the currently active video norm (see Grabber::setVideoNorm ).

See also: Grabber, VideoFormatItem, Grabber::getAvailableVideoFormats, Grabber::getVideoFormat

<< Grabber


Grabber::setVideoNorm

Grabber::setVideoNorm Method
This method sets the video of the currently active video capture device. A list of available video norms may be retrieved by calling Grabber::getAvailableVideoNorms.
Syntax:
bool setVideoNorm( const VideoNormItem& videonorm );
bool    setVideoNorm( const std::string& videonormstring );
bool    setVideoNorm( const std::wstring& videonormstring );

Parameter | Description
videonorm | Specifies the new video norm to be used by the current video capture device.
videonormstring | Specifies the name of the new video norm to be used by the current video capture device.
Return value:

true, if the video norm was set successfully, false otherwise.

Remarks:

After changing the video norm, the current video format will become invalid. A new video format has to be set with Grabber::setVideoFormat before Grabber::startLive may be called. A list of available video formats may be retrieved by calling Grabber::getAvailableVideoFormats.

Note that the active MemBufferCollection will become invalid after a call to this method and there is no MemBufferCollection set. You have to create a new collection with Grabber::newMemBufferCollection and make it the active one by calling Grabber::setActiveMemBufferCollection.

See also: Grabber, VideoNormItem, Grabber::getAvailableVideoNorms, Grabber::isVideoNormAvailableWithCurDev

<< Grabber


Grabber::setWindowPosition

Grabber::setWindowPosition Method
Sets the position of the grabber's live video window.
Syntax:
bool setWindowPosition( long posx, long posy );

Parameter | Description
posx | Specifies the x-coordinate of the upper left hand corner of the video window. It defaults to 0.
posy | Specifies the y-coordinate of the upper left hand corner of the video window. It defaults to 0.
Return value:

true on success, false otherwise.

Remarks:

A position for the live video window can only be set, if Grabber::getDefaultWindowPosition returns false. If an application wants to alter the position of the live video window, it should call Grabber::setDefaultWindowPosition(false) first.

Sample:

This example demonstrates how to set the position of the grabber's live video window.

long posx   = 50;
long posy   = 50;
long width  = 150;
long height = 100;
if( grabber.setWindowPosition( posx, posy ) == true )
{
    printf("New window position is %d %d\n",posx, posy);
}
else
{
    printf("Failed to set the new window position!\n");
}
See also: Grabber, Grabber::setWindowSize, Grabber::getWindowPosition, Grabber::setDefaultWindowPosition, Grabber::getDefaultWindowPosition

<< Grabber


Grabber::setWindowSize

Grabber::setWindowSize Method
Sets the size of the video window.
Syntax:
bool setWindowSize( long width, long height );

Parameter | Description
width | Specifies the width of the video window.
height | Specifies the height of the video window.
Return value:

true on success, false otherwise.

Remarks:

The size of the live video window can only be set, if Grabber::getDefaultWindowPosition returns false. If an application wants to alter the size of the live video window, it should call Grabber::setDefaultWindowPosition(false) first.

Sample:

This example demonstrates how to set the size of the grabber's live video window.

long width  = 150;
long height = 100;
// Check whether the window position and size can be set
if( grabber.getDefaultWindowPosition() == true )
{
    printf("Default window position is enabled.\n");
    printf("It is not possible to set the window position and size now!\n");
}
else
{
    if( grabber.setWindowSize( width, height ) == true )
    {
        printf("New window size is %d %d\n", width, height);
    }
    else
    {
        printf("Failed to set the new window size!\n");
    }
}
See also: Grabber, Grabber::setWindowPosition, Grabber::getWindowPosition, Grabber::setDefaultWindowPosition, Grabber::getDefaultWindowPosition

<< Grabber


Grabber::snapImages

Grabber::snapImages Method [Deprecated]

Snaps images from the live stream to the current active MemBuffer.
Syntax:
bool snapImages( DWORD count = 1, DWORD timeout = 0xFFFFFFFF );

Parameter | Description
count | Specifies the number of frames to be grabbed into the active MemBufferCollection.
timeout | Specifies the timeout time in milliseconds after which the SnapImages method returns if 1. the device does not send samples (e.g. ExternalTransport is set to stop) 2. the copy operation takes too long 3. all buffers are locked 4. the user callback takes too long. If timeout == 0xFFFFFFFF the method waits forever.
Return value:

true, if the images could be snapped successfully, false otherwise.

Remarks:

This method snaps an image sequence of the specified length to the currently active MemBufferCollection. This method may be called only, if Grabber::startLive was called before.

There are two ways to access grabbed image data:

  • using the currently active MemBufferCollection, which can be determined by calling Grabber::getActiveMemBufferCollection.
  • using the active MemBuffer which can be determined by a call to Grabber::getActiveMemBuffer.

The memory buffer collection is used as a ring buffer. Refer to the class MemBufferCollection for details.

If a GrabberListener object is used, the method GrabberListener::frameReady will be called as soon as the currently grabbed frame is complete.

Or use Grabber::setCallback in order to install a callback which will be called as soon as the currently grabbed frame is complete. An application should not use the GrabberListener::frameReady method and a callback simultaneously.

It cannot be guaranteed that the callback, or the GrabberListener::frameReady method are called for every frame. Depending on the power of your processor and the bandwidth of the image stream, the callback may not be called for certain frames. This does not mean that image data will be lost. Despite this, it is guaranteed that the callback for the last frame of the sequence is called, if at least one frame could be copied.

Locked buffers will never be overwritten.

snapImages will block until the last image is grabbed and the last callback function has returned, or when timeout != 0xFFFFFFFF, until the timeout has elapsed.

Information:

This method is deprecated since version 3.0.
This method only works when using the deprecated FrameGrabberSink. When using the FrameHandlerSink, use FrameHandlerSink::snapImages or FrameHandlerSink::snapImagesAsync.

See also: Grabber, VideoNormItem, Grabber::getAvailableVideoNorms, Grabber::isVideoNormAvailableWithCurDev

<< Grabber


Grabber::startLive

Grabber::startLive Method
Puts the grabber in live mode.
Syntax:
bool startLive( bool show = true );

Parameter | Description
show | Specifies whether the image stream is displayed while the grabber is in live mode.
Return value:

true, if the live mode was started successfully, false otherwise.

Remarks:

This method starts the image stream and has to be called before you can grab images. The bool parameter of this method specifies whether a live image is displayed or not. If the active sink type is set to an AviSink, this method will start writing the image stream to an avi file on disk. If the active sink type is set to FrameGrabberSink, images can be grabbed. Please refer to FrameGrabberSink for details on grabbing images.

In order to display a live image in a window, you have to set a handle to this window first, using the Grabber::setHWND method. If no window handle is set, a new window called "Active Movie" will be opened and the live image will be displayed there.

The live mode can be stopped with the Grabber::stopLive method. If the grabber becomes invalid (e.g. it gets unplugged) while in live mode, the live mode will be stopped internally.

Note: a valid video format has to be set after a call to Grabber::openDev before startLive may be called. Please refer to Grabber::setVideoFormat for details on setting a valid video format.

See also: Grabber, Grabber::isLive, Grabber::openDev, Grabber::setVideoFormat, Grabber::snapImages, Grabber::stopLive

<< Grabber


Grabber::stopLive

Grabber::stopLive Method
Stops the grabber
Syntax:
bool stopLive();
Return value:

true, if the grabber could be stopped successfully, false otherwise.

Remarks:

This method stops the grabber, if it is in live mode. If the grabber was already stopped nothing happens. If the active sink type is an AviSink, this method will stop writing the image stream to disk.

See also: Grabber, Grabber::isLive, Grabber::startLive

<< Grabber


Grabber::tCameraPropertyEnum
tCameraPropertyEnum enumerates the properties of a video camera.
Enumeration | Description
CameraControl_Pan | Identifies the pan function of the camera's pan/tilt unit
CameraControl_Tilt | Identifies the tilt function of the camera's pan/tilt unit
CameraControl_Roll | Identifies the roll function of the camera's pan/tilt unit
CameraControl_Zoom | Identifies the zoom function of the camera's motor zoom lens
CameraControl_Exposure | Identifies the exposure setting of the camera
CameraControl_Iris | Identifies the iris function of the camera's motor zoom lens
CameraControl_Focus | Identifies the focus function of the camera's motor zoom lens

<< Grabber


Grabber::tVideoPropertyEnum
tVideoPropertyEnum specifies video property types. This enumeration comes directly from DirectX 8.
Enumeration | Description
VideoProcAmp_Brightness | Identifies the brightness setting of the camera
VideoProcAmp_Contrast | Identifies the contrast setting of the camera
VideoProcAmp_Hue | Identifies the hue setting of the camera
VideoProcAmp_Saturation | Identifies the saturation setting of the camera
VideoProcAmp_Sharpness | Identifies the sharpness setting of the camera
VideoProcAmp_Gamma | Identifies the gamma setting of the camera
VideoProcAmp_ColorEnable | Identifies a function to set the camera to operate in color or monochrome mode
VideoProcAmp_WhiteBalance | Identifies the white balance setting of the camera
VideoProcAmp_BacklightCompensation | Identifies the back light compensation setting of the camera
VideoProcAmp_Gain | Identifies the gain setting of the camera

<< Grabber


Grabber::tCompressorItems

tCompressorItems
A tCompressorItem describes an AVI-Compressor.
Syntax:
typedef FilterInfoObject tCompressorItems;

<< Grabber


Grabber::tCompressorList

tCompressorList
A list of tCompressorItems
Syntax:
typedef std::vector<FilterInfoObject> tCompressorList;

<< Grabber


Grabber::tCompressorListPtr

tCompressorListPtr
A pointer to a list of tCompressorItems.
Syntax:
typedef smart_ptr<tCompressorList> tCompressorListPtr;

<< Grabber


Grabber::tFPSList

tFPSList
An array of double values that describe the number of frames per second.
Syntax:
typedef std::vector<double> tFPSList;

<< Grabber


Grabber::tFPSListPtr

tFPSListPtr
A pointer to a tFPSList.
Syntax:
typedef smart_ptr<tFPSList> tFPSListPtr;

<< Grabber


Grabber::tFrameRateList

tFrameRateList
An array of long values that describe the time between two frames in milliseconds.
Syntax:
typedef std::vector<long> tFrameRateList;

<< Grabber


Grabber::tFrameRateListPtr

tFrameRateListPtr
A pointer to a tFrameRateList.
Syntax:
typedef smart_ptr<tFrameRateList> tFrameRateListPtr;

<< Grabber


Grabber::tInChnList

tInChnList
A list of AnalogChannelItems.
Syntax:
typedef std::vector<tInputChannelItem> tInChnList;

<< Grabber


Grabber::tInChnListPtr

tInChnListPtr
A pointer to a list of tVideoFormatItems.
Syntax:
typedef smart_ptr<tInChnList> tInChnListPtr;

<< Grabber


Grabber::tInputChannelItem

tInputChannelItem
A AnalogChannelItem.
Syntax:
typedef AnalogChannelItem tInputChannelItem;

<< Grabber


Grabber::tMemBufferCollectionPtr

tMemBufferCollectionPtr
A pointer to a MemBufferCollection.
Syntax:
typedef smart_ptr<MemBufferCollection> tMemBufferCollectionPtr;

<< Grabber


Grabber::tMemBufferPtr

tMemBufferPtr
A pointer to a MemBuffer.
Syntax:
typedef smart_ptr<MemBuffer> tMemBufferPtr;

<< Grabber


Grabber::tVidCapDevList

tVidCapDevList
A list of tVideoCaptureDeviceItems.
Syntax:
typedef std::vector<tVideoCaptureDeviceItem> tVidCapDevList;

<< Grabber


Grabber::tVidCapDevListPtr

tVidCapDevListPtr
A pointer to a list of tVideoCaptureDeviceItems.
Syntax:
typedef smart_ptr<tVidCapDevList> tVidCapDevListPtr;

<< Grabber


Grabber::tVidFmtList

tVidFmtList
A list of tVideoFormatItems.
Syntax:
typedef std::vector<tVideoFormatItem> tVidFmtList;

<< Grabber


Grabber::tVidFmtListPtr

tVidFmtListPtr
A pointer to a list of tVideoFormatItems.
Syntax:
typedef smart_ptr<tVidFmtList> tVidFmtListPtr;

<< Grabber


Grabber::tVidNrmList

tVidNrmList
A list of tVideoNormItems.
Syntax:
typedef std::vector<tVideoNormItem> tVidNrmList;

<< Grabber


Grabber::tVidNrmListPtr

tVidNrmListPtr
A pointer to a list of tVideoNormItems.
Syntax:
typedef smart_ptr<tVidNrmList> tVidNrmListPtr;

<< Grabber


Grabber::tVideoCaptureDeviceItem

tVideoCaptureDeviceItem
A VideoCaptureDeviceItem.
Syntax:
typedef VideoCaptureDeviceItem tVideoCaptureDeviceItem;

<< Grabber


Grabber::tVideoFormatItem

tVideoFormatItem
A VideoFormatItem.
Syntax:
typedef VideoFormatItem tVideoFormatItem;

<< Grabber


Grabber::tVideoNormItem

tVideoNormItem
A VideoNormItem.
Syntax:
typedef VideoNormItem tVideoNormItem;

<< Grabber


GrabberListener

The GrabberListener class is the base class for all classes implementing a callback handler. A callback handler class has to be derived from GrabberListener and has to overwrite one or more callback methods. Every instance of a callback handler class has to be registered in Grabber by a call to Grabber::addListener. The available methods are:

  • The GrabberListener::overlayCallback method. It is called directly after the video capture device has delivered a new frame. Applications use this method to draw on the live video. It is called before the GrabberListener::frameReady method is called.
  • The GrabberListener::frameReady method. It is called after a frame has been copied into a memory buffer. Graphics and text that have been drawn in the GrabberListener::overlayCallback method are visible in the memory buffer when this method is called. Applications may use this method for image processing, because direct access to the image data is provided in this callback method.
  • The GrabberListener::deviceLost method. It is called, when the video capture device is no more available, i.e. it was unplugged.

Information

Header File: tisudshl.h
Namespace: DShowLib

Methods

Method | Description
deviceLost | This method is called when the video capture device is lost, i.e. unplugged.
frameReady | This method is called after the video capture device has copied a new frame into a memory buffer.
overlayCallback | This method is called after the video capture device has delivered a new frame and allows modifications to the OverlayBitmap.

Enumerations

Enumeration | Description
tListenerType | tListenerType enumerates the callback types supported by the Grabber.

<< Classes


GrabberListener::deviceLost

GrabberListener::deviceLost Method
This method is called when the video capture device is lost, i.e. unplugged.
Syntax:
virtual void deviceLost( Grabber& caller );

Parameter | Description
caller | Identifies the Grabber object, whose video capture device was lost.
Remarks:

If the video capture device was lost - for example it was unplugged - this callback method is called.

This callback method is called only if the GrabberListener object was registered by a call to Grabber::addListener with the parameter eDEVICELOST or eALL.

See also: GrabberListener, Grabber::addListener, GrabberListener::tListenerType, GrabberListener::frameReady, GrabberListener::overlayCallback

<< GrabberListener


GrabberListener::frameReady

GrabberListener::frameReady Method
This method is called after the video capture device has copied a new frame into a memory buffer.
Syntax:
virtual void frameReady( Grabber& caller, smart_ptr<MemBuffer> pBuffer, DWORD FrameNumber );

Parameter | Description
caller | Identifies the Grabber object that called this method.
pBuffer | Specifies a pointer to the MemBuffer that contains the new frame.
framenumber | Specifies the number of the frame for which this method is called. The frame number is incremented for every frame that is copied to a buffer. A call to Grabber::startLive resets the frame numbers to 0.
Remarks:

After a call to Grabber::startLive, the first frame that is copied to a buffer gets the frame number 0. Please note that the frame count is incremented for every copied frame. Therefore, the frame count and the index of a buffer in the MemBufferCollection is not identical if the number of copied frames exceeds the number of buffers in the MemBufferCollection.

This callback method is only called, if the GrabberListener object was registered by a call to Grabber::addListener with the parameter eFRAMEREADY or eALL.

Exceptions that occur in the frameReady event will get lost in the system. Therefore, bugs in the code that cause an exception cannot be recognized. To avoid this, all code in the event handler should be enclosed by a try ... catch block. If you need to display error messages, do not use a message box. Use a "debug trace" instead (e.g. TRACE(...) ). This is very important, because otherwise the system may run into a deadlock which will cause the application to hang.

See also: GrabberListener, Grabber::addListener, GrabberListener::tListenerType, GrabberListener::deviceLost, GrabberListener::overlayCallback, MemBuffer

<< GrabberListener


GrabberListener::overlayCallback

GrabberListener::overlayCallback Method
This method is called after the video capture device has delivered a new frame and allows modifications to the OverlayBitmap.
Syntax:
virtual void overlayCallback( Grabber& caller, smart_ptr<OverlayBitmap> pBitmap, const tsMediaSampleDesc& desc );

Parameter | Description
caller | Identifies the Grabber object that called this method.
pBitmap | Specifies a pointer to an OverlayBitmap object.
desc | Specifies a reference to a tsMediaSampleDesc structure.
Remarks:

This callback method is called directly after a frame has been delivered by the video capture device. In this method, graphics and text can be drawn on the live video that is frame dependent, i.e. a frame counter.

This callback method is only called, if the GrabberListener object was registered by a call to Grabber::addListener with the parameter eOVERLAYCALLBACK or eALL.

The overlayCallback method is called even if the overlay is disabled with a call to OverlayBitmap::setEnable.

Exceptions that occur in the OverlayCallback event will get lost in the system. Therefore, bugs in the code that cause an exception cannot be recognized. To avoid this, all code in the event handler should be enclosed by a try ... catch block. If you need to display error messages, do not use a message box. Use a "debug trace" instead (e.g. TRACE(...) ). This is very important, because otherwise the system may run into a deadlock which will cause the application to hang.

See also: GrabberListener, Grabber::addListener, GrabberListener::tListenerType, GrabberListener::deviceLost, GrabberListener::frameReady, OverlayBitmap, tsMediaSampleDesc

<< GrabberListener


GrabberListener::tListenerType
tListenerType enumerates the callback types supported by the Grabber.
Enumeration | Description
eDEVICELOST | If this parameter is passed to Grabber::addListener, the method GrabberListener::deviceLost of a GrabberListener object is called.
eFRAMEREADY | If this parameter is passed to Grabber::addListener, the method GrabberListener::frameReady of a GrabberListener object is called.
eOVERLAYCALLBACK | If this parameter is passed to Grabber::addListener, the method GrabberListener::overlayCallback of a GrabberListener object is called.
eALL | If this parameter is passed to Grabber::addListener, all 3 callbacks of GrabberListener will be called.

<< GrabberListener


IVCDPropertyItems

This class is a collection of IVCDPropertyItem objects.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 2.0

Methods

Method | Description
findElement | Searches the collection for a IVCDPropertyElement with a given combination of item and element id.
findInterface | Searches the collection for a IVCDPropertyInterface with a given combination of item, element and interface id.
findInterfacePtr | Searches the collection for a IVCDPropertyInterface with a given combination of item, element and interface id. In contrast to the findInterface method, this method has a templated output parameter, and the found and the type of this parameter is queried from the found interface.
findItem | Searches the collection for a IVCDPropertyItem with the given item id.
getCategoryMap | Returns a data structure mapping the available properties to categories.
getItems | Returns an tVCDPropertyItemArray with the IVCDPropertyItems in this collection.
load | Restores the values of all VCD Property Items with the data provided in an XML string.
save | Saves the values of all VCD Property Items to an XML string.

<< Classes


IVCDPropertyItems::findElement

IVCDPropertyItems::findElement Method
Searches the collection for a IVCDPropertyElement with a given combination of item and element id.
Syntax:
smart_com<IVCDPropertyElement> findElement( const GUID& itemID, const wchar_t* pElementName ) const;
smart_com<IVCDPropertyElement> findElement( const GUID& itemID, const GUID& elementID ) const;

Parameter | Description
itemID | Specifies the ItemID for which to search.
elementID | Specifies the elementID of the element that the item should contain.
pElementName | Specifies the name of the element that the itme should contain.
Return value:

If the collection contains an item with an element matching the given element path, the findElement method returns a pointer to the IVCDPropertyElement. If the element is not found, 0 is returned.

See also: IVCDPropertyItems, IVCDPropertyItem, IVCDPropertyElement, Standard Property Item GUIDs, Standard Element GUIDs

<< IVCDPropertyItems


IVCDPropertyItems::findInterface

IVCDPropertyItems::findInterface Method
Searches the collection for a IVCDPropertyInterface with a given combination of item, element and interface id.
Syntax:
smart_com<IVCDPropertyInterface> findInterface( const GUID& itemID, const wchar_t* pElementName,
                                                              const GUID& itfTypeID = GUID_NULL ) const;
smart_com<IVCDPropertyInterface> findInterface( const GUID& itemID, const GUID& elementID,
                                                              const GUID& itfTypeID = GUID_NULL ) const;

Parameter | Description
itemID | Specifies the ItemID for which to search.
elementID | Specifies the elementID of the element that the item should contain.
pElementName | Specifies the name of the element that the itme should contain.
itfTypeID | Specifies the interfaceID, defaults to GUID_NULL.
Return value:

If the collection contains an item with an interface matching the given interface path, the findInterface method returns a pointer to the IVCDPropertyInterface. If the interface is not found, 0 is returned.

See also: IVCDPropertyItems, IVCDPropertyItem, IVCDPropertyInterface, Standard Property Item GUIDs, Standard Element GUIDs, Standard Interface GUIDs

<< IVCDPropertyItems


IVCDPropertyItems::findItem

IVCDPropertyItems::findItem Method
Searches the collection for a IVCDPropertyItem with the given item id.
Syntax:
smart_com<IVCDPropertyItem> findItem( const GUID& itemID ) const;

Parameter | Description
itemID | Specifies the ItemID for which to search.
Return value:

If the collection contains an item with an id equal to the given item id, the findItem method returns a pointer to the IVCDPropertyItem. If the item is not found, 0 is returned.

See also: IVCDPropertyItems, IVCDPropertyItem, Standard Property Item GUIDs

<< IVCDPropertyItems


IVCDPropertyItems::getCategoryMap

IVCDPropertyItems::getCategoryMap Method
Returns a data structure mapping the available properties to categories.
Syntax:
tVCDCategoryMap getCategoryMap();
tVCDCategoryMapW getCategoryMapW();
Return value:

The category map.

See also: IVCDPropertyItems, tVCDCategoryMap

<< IVCDPropertyItems


IVCDPropertyItems::getItems

IVCDPropertyItems::getItems Method
Returns an tVCDPropertyItemArray with the IVCDPropertyItems in this collection.
Syntax:
tVCDPropertyItemArray getItems();
Return value:

An array with all VCDPropertyItems in this collection.

See also: IVCDPropertyItems, tVCDPropertyItemArray, IVCDPropertyItem

<< IVCDPropertyItems


IVCDPropertyItems::load

IVCDPropertyItems::load Method
Restores the values of all VCD Property Items with the data provided in an XML string.
Syntax:
void load( const std::string& s );
void loadW( const std::wstring& s );

Parameter | Description
s | Specifies the string that contains the previously saved data. This string can be obtained by calling IVCDPropertyItems::save
See also: IVCDPropertyItems, IVCDPropertyItems::save

<< IVCDPropertyItems


IVCDPropertyItems::save

IVCDPropertyItems::save Method
Saves the values of all VCD Property Items to an XML string.
Syntax:
std::string save() const;
std::wstring saveW() const;
Return value:

A string that contains the saved properties.

See also: IVCDPropertyItems, IVCDPropertyItems::load

<< IVCDPropertyItems


MemBuffer

A MemBuffer represents a single buffer in a MemBufferCollection (organized as a ring buffer).

It is possible to lock a buffer, so that the buffer cannot be overwritten by the grabber. If the grabber tries to overwrite a locked buffer, it sets the WasLockedFlag and tries to write to the next buffer. If all buffers are locked, the grabber does not copy any frames and waits until an unlocked buffer is available.

Information

Header File: tisudshl
Namespace: DShowLib

Inheritance

IFrame
MemBuffer

Methods

Method | Description
MemBuffer | Constructs a new MemBuffer by copying all data of the specified buffer.
forceUnlock | This method sets the lock count to 0. This unlocks the MemBuffer completely.
getBitmapInfoHeader | This method returns a pointer to a BitmapInfoHeader structure that describes the image data contained in this buffer.
getBitsPerPixel | Returns the number of bits that represent a single pixel.
getBufferSize | Returns the size of the MemBuffer in bytes.
getCollection | This method returns a reference to the MemBufferCollection that contains this buffer.
getCollectionPos | Returns the index of this buffer in the containing MemBufferCollection.
getColorformat | Returns the color format of this buffer.
getFrameType | returns an object that describes the pixel depth, pixel organization and the extent of the image data stored in the buffer.
getSize | Returns the width and height of the image data stored in this buffer.
getWasLockedFlag | Returns true, if the buffer was locked when the grabber tried to write data to it.
isLocked | This method returns true, if the buffer is locked.
lock | This method increments the lock count of this buffer by 1, so that the grabber cannot overwrite the data in this buffer.
save | Writes the buffer to disk as a .BMP file.
unlock | This method decrements the lock count by 1.

Type Definitions

Type | Description
tBmInfHPtr | A pointer to a BITMAPINFOHEADER structure.

<< Classes


MemBuffer::MemBuffer

MemBuffer::MemBuffer Method
Constructs a new MemBuffer by copying all data of the specified buffer.
Syntax:
MemBuffer( const MemBuffer& membuffer );

Parameter | Description
membuffer | Specifies the MemBuffer to copy.
Remarks:

MemBuffers are created on allocation of a new MemBufferCollection with MemBufferCollection::create or Grabber::newMemBufferCollection.

See also: MemBuffer, Grabber::newMemBufferCollection, MemBufferCollection::create

<< MemBuffer


MemBuffer::forceUnlock

MemBuffer::forceUnlock Method
This method sets the lock count to 0. This unlocks the MemBuffer completely.
Syntax:
void forceUnlock();
See also: MemBuffer, MemBuffer::lock, MemBuffer::unlock, MemBuffer::isLocked, MemBuffer::getWasLockedFlag

<< MemBuffer


MemBuffer::getBitmapInfoHeader

MemBuffer::getBitmapInfoHeader Method
This method returns a pointer to a BitmapInfoHeader structure that describes the image data contained in this buffer.
Syntax:
MemBuffer::tBmInfHPtr getBitmapInfoHeader() const;
Return value:

A pointer to a BitmapInfoHeader structure.

Please note: the BitmapInfoHeader is not part of a DIB.

See also: MemBuffer, MemBuffer::tBmInfHPtr

<< MemBuffer


MemBuffer::getBitsPerPixel

MemBuffer::getBitsPerPixel Method
Returns the number of bits that represent a single pixel.
Syntax:
int getBitsPerPixel() const;
Return value:

The number of bits that represent a single pixel with the current color format.

See also: MemBuffer, MemBuffer::getColorformat, MemBufferCollection::getColorformat

<< MemBuffer


MemBuffer::getBufferSize

MemBuffer::getBufferSize Method
Returns the size of the MemBuffer in bytes.
Syntax:
DWORD getBufferSize() const;
Return value:

The size of the MemBuffer in bytes.

See also: MemBuffer, Grabber::getUserMemBufferSize, MemBuffer::getSize, MemBufferCollection::getBufferSize, MemBufferCollection::getFrameSize

<< MemBuffer


MemBuffer::getCollection

MemBuffer::getCollection Method
This method returns a reference to the MemBufferCollection that contains this buffer.
Syntax:
const MemBufferCollection& getCollection() const;
Return value:

A reference to a MemBufferCollection.

See also: MemBuffer, MemBuffer::getCollectionPos

<< MemBuffer


MemBuffer::getCollectionPos

MemBuffer::getCollectionPos Method
Returns the index of this buffer in the containing MemBufferCollection.
Syntax:
DWORD getCollectionPos() const;
Return value:

The index of this buffer in the MemBufferCollection.

Remarks:

Please note that the index count starts with 0.

See also: MemBuffer, MemBufferCollection::getBuffer

<< MemBuffer


MemBuffer::getColorformat

MemBuffer::getColorformat Method
Returns the color format of this buffer.
Syntax:
tColorformatEnum getColorformat() const;
Return value:

The color format of this buffer as a tColorformatEnum.

See also: MemBuffer, tColorformatEnum, MemBuffer::getBitsPerPixel, MemBufferCollection::getColorformat

<< MemBuffer


MemBuffer::getSize

MemBuffer::getSize Method
Returns the width and height of the image data stored in this buffer.
Syntax:
const SIZE& getSize() const;
Return value:

A SIZE structure, containing the width and height of the image data stored in this buffer.

See also: MemBuffer, MemBufferCollection::getFrameSize

<< MemBuffer


MemBuffer::getWasLockedFlag

MemBuffer::getWasLockedFlag Method
Returns true, if the buffer was locked when the grabber tried to write data to it.
Syntax:
bool getWasLockedFlag();
Return value:

true, if the flag is set, false otherwise.

Remarks:

This method returns true, if the grabber tried to copy a new frame to MemBuffer, but failed because the MemBuffer was locked (due to a call to MemBuffer::lock ).

See also: MemBuffer, MemBuffer::lock, MemBuffer::unlock, MemBuffer::isLocked

<< MemBuffer


MemBuffer::isLocked

MemBuffer::isLocked Method
This method returns true, if the buffer is locked.
Syntax:
bool isLocked();
Return value:

true, if the buffer is locked, false otherwise.

See also: MemBuffer, MemBuffer::lock, MemBuffer::unlock, MemBuffer::forceUnlock, MemBuffer::getWasLockedFlag

<< MemBuffer


MemBuffer::lock

MemBuffer::lock Method
This method increments the lock count of this buffer by 1, so that the grabber cannot overwrite the data in this buffer.
Syntax:
void lock();
Remarks:

If the grabber cannot write to this buffer, the WasLockedFlag is set.

See also: MemBuffer, MemBuffer::unlock, MemBuffer::forceUnlock, MemBuffer::isLocked, MemBuffer::getWasLockedFlag

<< MemBuffer


MemBuffer::save

MemBuffer::save Method
Writes the buffer to disk as a .BMP file.
Syntax:
Error save( const std::string& filename ) const;
Error save( const std::wstring& filename ) const;
Error save( const wchar_t* pFilename ) const;

Parameter | Description
filename | Specifies the name and the path of the file. The path is specified relative to the current directory.
pFilename | Specifies the name and the path of the file. The path is specified relative to the current directory.
Return value:

An Error object.

Remarks:

To set the image file color format and to write JPEG images, use the new saveToFileBMP and saveToFileJPEG functions.

See also: MemBuffer, saveToFileBMP, saveToFileJPEG, MemBufferCollection::save

<< MemBuffer


MemBuffer::unlock

MemBuffer::unlock Method
This method decrements the lock count by 1.
Syntax:
void unlock();
Remarks:

The buffer is locked, if the lock count is greater than 0. If the lock count is 0, this method has no effect.

See also: MemBuffer, MemBuffer::lock, MemBuffer::forceUnlock, MemBuffer::isLocked, MemBuffer::getWasLockedFlag

<< MemBuffer


MemBuffer::tBmInfHPtr

tBmInfHPtr
A pointer to a BITMAPINFOHEADER structure.
Syntax:
typedef smart_ptr<BITMAPINFOHEADER> tBmInfHPtr;

<< MemBuffer


MemBufferCollection

The MemBufferCollection stores several MemBuffers. The MemBufferCollection is organized as a ring buffer: If a frame is grabbed to the last buffer of the collection, the next frame will be grabbed to the first one.

Information

Header File: tisudshl.h
Namespace: DShowLib

Methods

Method | Description
create | This factory function creates a MemBufferCollection for use with the FrameHandlerSink or the Grabber.
getBitmapInfoHeader | Returns a smart_ptr to a BITMAPINFOHEADER structure, which describes the image data contained in the buffers of this collection.
getBitsPerPixel | Returns the number of bits that represent a single pixel in a buffer of the collection.
getBuffer | Returns a smart_ptr to the MemBuffer with the specified index. This method returns 0, if the MemBufferCollection is not initialized or the given index is greater than the number of contained buffers (see MemBufferCollection::getBufferCount ).
getBufferCount | Returns the number of buffers stored in this collection.
getBufferDataSize | Returns the size of valid data in the buffer in bytes.
getBufferSize | Returns the number of bytes required for the image data of one buffer.
getColorformat | Returns the color format (organization of one pixel) of the image data stored in this collection. This method returns an undefined value, if the collection is not initialized. Use MemBufferCollection::getLastError in order to determine whether the returned color format is valid or not.
getFrameSize | Returns the width and height in pixels of one frame stored in this collection.
getFrameType | Returns the frame type of the collection.
getLastError | This method returns information about an error occurred during the last call to a method of this object.
isInit | Checks whether the collection is initialized.
operator[] | Returns the MemBuffer at the specified index in the collection.
save | Saves all buffers of this collection to disk as a .BMP file.

Type Definitions

Type | Description
tBmInfHPtr | A pointer to a BITMAPINFOHEADER structure.
tMemBufferPtr | A pointer to a MemBuffer.

<< Classes


MemBufferCollection::getBitmapInfoHeader

MemBufferCollection::getBitmapInfoHeader Method
Returns a smart_ptr to a BITMAPINFOHEADER structure, which describes the image data contained in the buffers of this collection.
Syntax:
MemBufferCollection::tBmInfHPtr getBitmapInfoHeader() const;
Return value:

A pointer to a BitmapInfoHeader structure.

Please note: the BitmapInfoHeader is not part of a DIB.

Remarks:

This structure contains information about the dimensions and the color format of one buffer in this collection. It is defined in the Windows GDI.

See also: MemBufferCollection, MemBuffer::tBmInfHPtr

<< MemBufferCollection


MemBufferCollection::getBitsPerPixel

MemBufferCollection::getBitsPerPixel Method
Returns the number of bits that represent a single pixel in a buffer of the collection.
Syntax:
int getBitsPerPixel() const;
Return value:

The number of bits per pixel.

See also: MemBufferCollection, MemBufferCollection::getColorformat

<< MemBufferCollection


MemBufferCollection::getBuffer

MemBufferCollection::getBuffer Method
Returns a smart_ptr to the MemBuffer with the specified index. This method returns 0, if the MemBufferCollection is not initialized or the given index is greater than the number of contained buffers (see MemBufferCollection::getBufferCount ).
Syntax:
Grabber::tMemBufferPtr getBuffer( DWORD pos ) const;

Parameter | Description
pos | Specifies the position of the buffer within the MemBufferCollection. The first buffer is at position 0.
Return value:

A pointer to the MemBuffer, or 0 on error.

Remarks:

Returns 0, if the MemBufferCollection is not initialized or if the given index is greater than the number of contained buffers (see MemBufferCollection::getBufferCount ).

See also: MemBufferCollection, MemBufferCollection::getBufferCount

<< MemBufferCollection


MemBufferCollection::getBufferCount

MemBufferCollection::getBufferCount Method
Returns the number of buffers stored in this collection.
Syntax:
DWORD getBufferCount() const;
Return value:

The number of buffers stored in this collection.

See also: MemBufferCollection

<< MemBufferCollection


MemBufferCollection::getBufferDataSize

MemBufferCollection::getBufferDataSize Method
Returns the size of valid data in the buffer in bytes.
Syntax:
DWORD getBufferDataSize() const;
Return value:

The size of valid data in the buffer in bytes.

Remarks:

User allocated buffers may be larger than the actual data which is defined through:

(getFrameSize().cx * getFrameSize().cy * getBitsPerPixel()) / 8.

Information:

Introduced in version 2.0
See also: MemBufferCollection

<< MemBufferCollection


MemBufferCollection::getBufferSize

MemBufferCollection::getBufferSize Method
Returns the number of bytes required for the image data of one buffer.
Syntax:
DWORD getBufferSize() const;
Return value:

The size of one frame in bytes.

Remarks:

Please note that all buffers in the collection have the same size.

See also: MemBufferCollection, Grabber::getUserMemBufferSize, MemBufferCollection::getFrameSize

<< MemBufferCollection


MemBufferCollection::getColorformat

MemBufferCollection::getColorformat Method
Returns the color format (organization of one pixel) of the image data stored in this collection. This method returns an undefined value, if the collection is not initialized. Use MemBufferCollection::getLastError in order to determine whether the returned color format is valid or not.
Syntax:
tColorformatEnum getColorformat() const;
Return value:

The color format, as a tColorformatEnum, which was passed to the object during initialization.

Remarks:

This method returns an undefined value, if the collection is not initialized. Use MemBufferCollection::getLastError in order to determine whether the returned color format is valid or not.

See also: MemBufferCollection, MemBufferCollection::getBitsPerPixel

<< MemBufferCollection


MemBufferCollection::getFrameSize

MemBufferCollection::getFrameSize Method
Returns the width and height in pixels of one frame stored in this collection.
Syntax:
const SIZE& getFrameSize() const;
Return value:

A SIZE structure.

Remarks:

All frames of a MemBufferCollection have the same size.

See also: MemBufferCollection, Grabber::getUserMemBufferSize

<< MemBufferCollection


MemBufferCollection::getLastError

MemBufferCollection::getLastError Method
This method returns information about an error occurred during the last call to a method of this object.
Syntax:
Error getLastError() const;
Return value:

An Error object.

See also: MemBufferCollection, Grabber::getLastError

<< MemBufferCollection


MemBufferCollection::isInit

MemBufferCollection::isInit Method
Checks whether the collection is initialized.
Syntax:
bool isInit() const;
Return value:

true if the MemBufferCollection is initialized, false otherwise.

Remarks:

The collection is not initialized, if it was created with Grabber::newMemBufferCollection(0).

See also: MemBufferCollection

<< MemBufferCollection


MemBufferCollection::operator[]

MemBufferCollection::operator[] Method
Returns the MemBuffer at the specified index in the collection.
Syntax:
tMemBufferPtr operator[]( DWORD pos ) const;

Parameter | Description
pos | Specifies the Index of the MemBuffer that should be returned. pos must lie in the range [0, getBufferCount() - 1].
Return value:

A pointer to the desired MemBuffer.

See also: MemBufferCollection, MemBuffer, MemBufferCollection::getBufferCount, tMemBufferPtr

<< MemBufferCollection


MemBufferCollection::save

MemBufferCollection::save Method
Saves all buffers of this collection to disk as a .BMP file.
Syntax:
bool save( const std::string& filename ) const;
bool save( const std::wstring& filename ) const;

Parameter | Description
filename | Specifies the basename of the files to which the buffers are going to be written. The filename must contain one "*" which will be replaced by the indexes of the frames.
Return value:

true, if the buffers could be saved successfully, false otherwise.

Remarks:

This method saves buffers into a file using the windows "bmp" format. If a file of the given name already exists, it will be overwritten by this method.

The filename must contain one "*" which will be replaced by the index of the according buffer.

See also: MemBufferCollection, MemBuffer::save

<< MemBufferCollection


MemBufferCollection::tBmInfHPtr

tBmInfHPtr
A pointer to a BITMAPINFOHEADER structure.
Syntax:
typedef smart_ptr<BITMAPINFOHEADER> tBmInfHPtr;

<< MemBufferCollection


MemBufferCollection::tMemBufferPtr

tMemBufferPtr
A pointer to a MemBuffer.
Syntax:
typedef smart_ptr<MemBuffer> tMemBufferPtr;

<< MemBufferCollection


OverlayBitmap

The OverlayBitmap object is used to draw graphical elements like lines and text onto the video stream.

There are three possible locations where overlay objects may be inserted in the image stream:

  • Behind the device ( Device Path ): this overlay will appear in the display as well as in the sink (ring buffer, stream file)
  • In front of the display ( Display Path ): this overlay will appear in the display only
  • In front of the sink ( Sink Path ): this overlay will appear in the sink (ring buffer, stream file) only

Internally, the OverlayBitmap object uses a bitmap (HBITMAP) for drawing text and graphical elements on the video stream. Its size and color depth are dependent on the video format of the currently active video capture device and all frame filters that are inserted between the device and itself. Therefore, the internal bitmap is destroyed and recreated, if:

  • the devices's video format is changed,
  • the sink's video format is changed because it may require automatic color space conversion somewhere in front of the overlay,
  • frame filters are inserted/removed between the device and the overlay
  • parameters of a frame filter that are inserted between the device and the overlay are altered in a way that the video format of the image stream is changed.

The color format of the overlay is determined by the objects that are located in front and behind it in the image stream. In addition, the color format can be forced to monochrome or RGB with a call to OverlayBitmap::setColorMode.

The functionality of the OverlayBitmap object is not available and the method OverlayBitmap::canRender returns false in two cases:

  • the sink's color format is set to YUV
  • the filter that is inserted just behind the overlay requires YUV as the input format

Pointers to instances of OverlayBitmap objects can be retrieved with a call to the Grabber's method Grabber::getOverlay.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 1.x

Methods

Method | Description
beginPaint | Prepares the overlay bitmap for graphic operations.
canRender | Returns whether the framework is able to render the overly on the video stream.
drawFrameEllipse | Draws the frame of an ellipse on the live video.
drawFrameRect | Draws the frame of a rectangle on the live video.
drawLine | Draws a line on the live video.
drawSolidEllipse | Draws a solid ellipse on the live video.
drawSolidRect | Draws a solid rectangle on the live video.
drawText | Draws a text on the live video.
endPaint | Releases the overlay bitmap from the internal device context.
fill | Fills the entire overlay bitmap with the specified color.
getColorMode | Returns the currently selected color mode of this OverlayBitmap.
getColorformat | Returns the current color format used for the overlay.
getDC | Returns the device context.
getDropOutColor | Returns the currently used dropout color.
getEnable | Returns whether the overlay is visible on the live video stream.
getFlipVertical | Returns whether the overlay bitmap is displayed vertically flipped on the video.
getFont | Retrieves a pointer to an IFont COM font object pointer.
getFontBKColor | Returns the background color for text drawings.
getFontTransparent | Returns the background mode for text drawings.
getFrameType | Returns a FrameTypeInfo object describing the current format of this OverlayBitmap.
getHeight | Returns the height of the OverlayBitmap.
getPathPosition | Returns the path position of this OverlayBitmap.
getWidth | Returns the width of the OverlayBitmap.
setColorMode | Set the color mode of this OverlayBitmap. The color mode determines, whether the overlay bitmap is painted in color or grayscale. The images provided by the video capture device are converted into the selected format before drawing the overlay.
setDropOutColor | Sets the dropout color.
setEnable | Enables or disables the display of the overlay bitmap on the live video.
setFlipVertical | Enables or disables the vertical flip of the overlay bitmap.
setFont | Sets the OverlayBitmaps object font to the specified font.
setFontBKColor | Sets the background color for drawing text to the specified color value, or to the nearest physical color if the device cannot represent the specified color value.
setFontTransparent | Sets the background mode for text drawings.

Enumerations

Enumeration | Description
tOVBColorMode | The members of this enumeration are used to set the color format of the OverlayBitmap, using setColorMode.

<< Classes


OverlayBitmap::beginPaint

OverlayBitmap::beginPaint Method
Prepares the overlay bitmap for graphic operations.
Syntax:
bool beginPaint() const;
Return value:

true on success, false otherwise.

Remarks:

beginPaint creates a device context (HDC) for the OverlayBitmap object. After beginPaint has been called, an application can retrieve a valid device context (HDC) by calling the OverlayBitmap objects' method OverlayBitmap::getDC. With this device context (HDC) GDI functions can be performed on the bitmap of the OverlayBitmap object. The OverlayBitmap object's bitmap is allready selected into the device context (HDC) after beginPaint has been called.

The method beginPaint is only needed, if GDI functions need to be called, that are not implemented in the OverlayBitmap class. For example, the GDI function BitBlt needs a preceding call to beginPaint.

Graphic methods of the OverlayBitmap object, such as OverlayBitmap::drawText do not need a preceding call to beginPaint.

When the application no longer needs the device context (HDC), the OverlayBitmap::endPaint method must be called to delete it. Only after the method OverlayBitmap::endPaint has been called, the new graphics are visible on the live video.

See also: OverlayBitmap, OverlayBitmap::endPaint, OverlayBitmap::getDC

<< OverlayBitmap


OverlayBitmap::canRender

OverlayBitmap::canRender Method
Returns whether the framework is able to render the overly on the video stream.
Syntax:
bool canRender() const;
Return value:

true, if the overlay bitmap can be rendered on the live video, false otherwise.

Remarks:

This method returns whether it is possible to copy the internal bitmap of the OverlayBitmap object on the video stream. The bitmap can be copied to the live video only, if the sink or frame filter that is located to the right in the image stream accepts a monochrome or RGB color format. If the object to the right requires a color eUYVY or other non monochrome or non RGB format, the bitmap will not be copied on the live video. In this case, text and drawings are not visible on the live video.

See also: OverlayBitmap, FrameGrabberSink, AviSink, tColorformatEnum

<< OverlayBitmap


OverlayBitmap::drawLine

OverlayBitmap::drawLine Method
Draws a line on the live video.
Syntax:
bool drawLine( COLORREF color, int iXStart, int iYStart, int iXEnd, int iYEnd );

Parameter | Description
color | Specifies the color of the line. The color can be specified with the RGB macro.
iXStart | Specifies the column in pixel units where the text should start on the live video.
iYStart | Specifies the row in pixel units where the line should start on the live video.
iXEnd | Specifies the column in pixel units where the line should end on the live video.
iYEnd | Specifies the row in pixel units where the line should end on the live video.
Return value:

true on success, false otherwise.

Sample:

This example demonstrates how draw a red rectangle on the live video stream.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
pOverlayBitmap = m_Grabber.getOverlay();
if( pOverlayBitmap->canRender() == true)
{
    // Make sure, the overlay is enabled.
    pOverlayBitmap->setEnable(true);

    // Draw a rectangle in red.
    pOverlayBitmap->drawLine( RGB(255,0,0),  10,  10, 100,  10);
    pOverlayBitmap->drawLine( RGB(255,0,0), 100,  10, 100, 100);
    pOverlayBitmap->drawLine( RGB(255,0,0), 100, 100,  10, 100);
    pOverlayBitmap->drawLine( RGB(255,0,0),  10,  10,  10, 100);
}
See also: OverlayBitmap, OverlayBitmap::drawText, OverlayBitmap::drawSolidRect, OverlayBitmap::drawFrameRect, OverlayBitmap::drawSolidEllipse, OverlayBitmap::drawFrameEllipse

<< OverlayBitmap


OverlayBitmap::drawSolidRect

OverlayBitmap::drawSolidRect Method
Draws a solid rectangle on the live video.
Syntax:
bool drawSolidRect( COLORREF color, const RECT& rect );

Parameter | Description
color | Specifies the color of the rectangle. The color can be specified with the RGB macro.
rect | The rectangle to be drawn in pixel coordinates. A CRect object or a RECT structure can be passed for this parameter.
Return value:

true on success, false otherwise.

Sample:

This example demonstrates how draw two rectangles on the live video stream.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
pOverlayBitmap = m_Grabber.getOverlay();
if( pOverlayBitmap->canRender() == true)
{
    // Make sure, the overlay is enabled.
    pOverlayBitmap->setEnable(true);

    // Draw a rectangle in magenta, using a CRect object.
    pOverlayBitmap->drawSolidRect( RGB(255,0,255),
                                     CRect(100,50,50,25));

    // Draw a rectangle in blue, using a RECT structure.
    RECT rectangle;
    rectangle.left   = 160;
    rectangle.right  = 200;
    rectangle.top    = 160;
    rectangle.bottom = 180;
    pOverlayBitmap->drawSolidRect( RGB(0,0,255),    rectangle);
}
See also: OverlayBitmap, OverlayBitmap::drawText, OverlayBitmap::drawLine, OverlayBitmap::drawFrameRect, OverlayBitmap::drawSolidEllipse, OverlayBitmap::drawFrameEllipse

<< OverlayBitmap


OverlayBitmap::drawText

OverlayBitmap::drawText Method
Draws a text on the live video.
Syntax:
bool drawText( COLORREF color, int iX, int iY, const char* szText );
bool drawText( COLORREF color, int iX, int iY, const std::string& szText );
bool drawText( COLORREF color, int iX, int iY, const std::wstring& szText );

Parameter | Description
color | Specifies the color of the text to be drawn. The color can be specified with the RGB macro
iX | Specifies the column in pixel units where the text should start on the live video.
iY | Specifies the row in pixel units where the text should start on the live video.
szText | Points to a null terminated string that is to be drawn.
Return value:

true on success, false otherwise.

Remarks:

The used background color of the text is specified by a call to OverlayBitmap::setFontBKColor. The used background mode of the text is set by a call to OverlayBitmap::setFontTransparent.

Sample:

This example demonstrates how to enable the overlay bitmap and draw the text "Hello Word" in the upper left corner of the live video.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
pOverlayBitmap = m_Grabber.getOverlay();
if( pOverlayBitmap->canRender() == true)
{
    // Make sure, the overlay for the text is enabled.
    pOverlayBitmap->setEnable(true);

    // Draw the text.
    pOverlayBitmap->drawText( RGB(255,0,0),  0, 0, "Hello World" );
}
See also: OverlayBitmap, OverlayBitmap::setFontBKColor, OverlayBitmap::getFontBKColor, OverlayBitmap::setFontTransparent, OverlayBitmap::getFontTransparent

<< OverlayBitmap


OverlayBitmap::endPaint

OverlayBitmap::endPaint Method
Releases the overlay bitmap from the internal device context.
Syntax:
bool endPaint() const;
Return value:

true on success, false otherwise.

Remarks:

If an application has called beginPaint, it must call OverlayBitmap::endPaint after all graphics operation have been completed. OverlayBitmap::endPaint deletes the device context (HDC), that has been created in beginPaint.

All graphics operations that are enclosed in a beginPaint OverlayBitmap::endPaint sequence will become visible on the live video after a call to endPaint. Only after a call to OverlayBitmap::endPaint, the new created graphics are displayed.

After endPaint has been called, a call to OverlayBitmap::getDC returns NULL and an exception is thrown.

See also: OverlayBitmap, OverlayBitmap::beginPaint, OverlayBitmap::getDC

<< OverlayBitmap


OverlayBitmap::fill

OverlayBitmap::fill Method
Fills the entire overlay bitmap with the specified color.
Syntax:
bool fill( COLORREF color );

Parameter | Description
color | Specifies the color that is used to fill the overly. The color can be specified with the RGB macro.
Return value:

true on success, false otherwise.

Remarks:

This method fills the entire overlay bitmap with the specified color. The bitmap will be completely overwritten. This method can be used to clear the overlay bitmap, if the specified color is the currently used dropout color.

Sample:

This example demonstrates how to fill the complete overlay bitmap with the color magenta that was set as the current dropout color before. This makes the complete overlay bitmap transparent (invisible) on the video stream.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
pOverlayBitmap = m_Grabber.getOverlay();
if( pOverlayBitmap->canRender() == true)
{
    // Make sure, the overlay is enabled.
    pOverlayBitmap->setEnable(true);
    pOverlayBitmap->setDropOutColor( RGB(255,0,255));   // Magenta
    // Fill the bitmap with the dropout color to make it completely transparent.
    pOverlayBitmap->fill(pOverlayBitmap->getDropOutColor());
}
See also: OverlayBitmap, OverlayBitmap::setDropOutColor, OverlayBitmap::getDropOutColor

<< OverlayBitmap


OverlayBitmap::getDC

OverlayBitmap::getDC Method
Returns the device context.
Syntax:
HDC getDC() const;
Return value:

If the method succeeds, the return value identifies the currently used device context of the OverlayBitmap object.

If the function fails, the return value is NULL.

Remarks:

An application can use the returned device context to perform GDI operations that are not provided by a method of the OverlayBitmap class.

Before getDC can be called, an application must call OverlayBitmap::beginPaint. OverlayBitmap::beginPaint creates the device context and selects the bitmap of the OverlayBitmap object in this new device context.

If getDC is called without a preceeding call to OverlayBitmap::beginPaint, getDC returns NULL and an exception is thrown.

After all GDI operations have been performed, the OverlayBitmap::endPaint method must be called to release the device context and make the result of the GDI operations visible on the live video.

Sample:

This example demonstrates how to retrieve the device context of the OverlayBitmap object.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
HDC hDC;
pOverlayBitmap = m_Grabber.getOverlay();
pOverlayBitmap->beginPaint();
hDC = pOverlayBitmap->getDC();
if( hDC != NULL)
{
    // Now, perform some GDI functions, using the hDC.
}
pOverlayBitmap->endPaint();
See also: OverlayBitmap, OverlayBitmap::beginPaint, OverlayBitmap::endPaint

<< OverlayBitmap


OverlayBitmap::getDropOutColor

OverlayBitmap::getDropOutColor Method
Returns the currently used dropout color.
Syntax:
COLORREF getDropOutColor() const;
Return value:

The currently used dropout color. It can be used in the OverlayBitmap::fill method to clear the overlay bitmap.

Sample:

This example demonstrates how to fill the complete overlay bitmap with the color magenta - the current dropout color. This makes the complete overlay bitmap transparent on the video stream.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
pOverlayBitmap = m_Grabber.getOverlay();
pOverlayBitmap->setDropOutColor( RGB(255,0,255));   // Magenta

// Fill the bitmap with the dropout color to make it completely transparent.
pOverlayBitmap->fill(pOverlayBitmap->getDropOutColor());
See also: OverlayBitmap, OverlayBitmap::setDropOutColor, OverlayBitmap::fill

<< OverlayBitmap


OverlayBitmap::getEnable

OverlayBitmap::getEnable Method
Returns whether the overlay is visible on the live video stream.
Syntax:
bool getEnable() const;
Return value:

true, if the overlay is visible, false otherwise.

Remarks:

This method is used to query whether the overlay bitmap is enabled. It returns the value, that is set by a call to OverlayBitmap::setEnable.

See also: OverlayBitmap, OverlayBitmap::setEnable

<< OverlayBitmap


OverlayBitmap::getFlipVertical

OverlayBitmap::getFlipVertical Method
Returns whether the overlay bitmap is displayed vertically flipped on the video.
Syntax:
bool getFlipVertical() const;
Return value:

true, if the overlay bitmap is copied bottom up to the live video, false otherwise.

See also: OverlayBitmap, OverlayBitmap::setFlipVertical

<< OverlayBitmap


OverlayBitmap::getFont

OverlayBitmap::getFont Method
Retrieves a pointer to an IFont COM font object pointer.
Syntax:
IFont* getFont() const;
Return value:

A pointer to an IFont COM font object pointer.

Remarks:

An IFont COM font object is an object wrapper around a Windows font object. For more information about the IFont COM font please refer to the MSDN Library.

Important: The IFont COM object pointer retrieved by getFont() must be stored in a local IFont pointer variable. For example, getFont()->put_Underline(TRUE) is not allowed.

If the IFont interface is not used anymore, the IFont::Release() method must be called to avoid memory leaks.

Sample:

This example demonstrates how to draw underlined, bold text.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
IFont *piFont = NULL;

pOverlayBitmap = m_Grabber.getOverlay();

// Make sure, the overlay bitmap is enabled.
pOverlayBitmap->setEnable(true);

// Set a font.
pOverlayBitmap->setFont("Arial",20);

// Retrieve the IFont interface pointer.
piFont = pOverlayBitmap->getFont();

piFont->put_Underline( TRUE );
piFont->put_Bold( TRUE );

// If the retrieved IFont interface is no longer used,
// Release() must be called.
piFont->Release();

// Now, draw the text.
pOverlayBitmap->drawText( RGB(255,0,0),  5, 0, "Underlined text" );
See also: OverlayBitmap, OverlayBitmap::getFont, OverlayBitmap::drawText

<< OverlayBitmap


OverlayBitmap::getFontBKColor

OverlayBitmap::getFontBKColor Method
Returns the background color for text drawings.
Syntax:
COLORREF getFontBKColor() const;
Return value:

The currently used background color for text drawings.

See also: OverlayBitmap, OverlayBitmap::drawText, OverlayBitmap::setFontBKColor

<< OverlayBitmap


OverlayBitmap::getFontTransparent

OverlayBitmap::getFontTransparent Method
Returns the background mode for text drawings.
Syntax:
bool getFontTransparent() const;
Return value:

The currently used background mode for text drawings.

See also: OverlayBitmap, OverlayBitmap::drawText, OverlayBitmap::setFontBKColor, OverlayBitmap::setFontTransparent

<< OverlayBitmap


OverlayBitmap::getHeight

OverlayBitmap::getHeight Method
Returns the height of the OverlayBitmap.
Syntax:
long getHeight() const;
Return value:

The height in pixels of the OverlayBitmap.

Remarks:

The height of the OverlayBitmap is equal to the height of the currently used video format.

See also: OverlayBitmap, OverlayBitmap::getWidth

<< OverlayBitmap


OverlayBitmap::getWidth

OverlayBitmap::getWidth Method
Returns the width of the OverlayBitmap.
Syntax:
long getWidth() const;
Return value:

The width in pixels of the OverlayBitmap.

Remarks:

The width of the OverlayBitmap is equal to the width of the currently used video format.

See also: OverlayBitmap, OverlayBitmap::getHeight

<< OverlayBitmap


OverlayBitmap::setDropOutColor

OverlayBitmap::setDropOutColor Method
Sets the dropout color.
Syntax:
bool setDropOutColor( COLORREF color);

Parameter | Description
color | Specifies the color that is used as a dropout color. The color can be specified with the RGB macro. The default dropout color is black (RGB(0,0,0))
Return value:

true on success, false otherwise.

Remarks:

The dropout color determines, which pixels of the overlay bitmap are not copied to the live video. Each dropout colored pixel of the overlay bitmap is not copied on the video sample.

If the video format or the sinktype is an RGB color format such as RGB555, RGB565, RGB24 or RGB32, the dropout color can be specified with the standard RGB macro. For example, if the dropout color is magenta, it can be specified with RGB(255,0,255).

If a monochrome RGB8 video format or sinktype is used, the dropout color can also be specified using the RGB macro. The single values for red, green and blue must be equal to each other: RGB(100,100,100). IC Imaging Control tries to find the nearest color to the specified dropout color in the color palette of the overlay bitmap. If no matching color is found, the video can not be seen. Instead of the live video a only non-transparent bitmap is displayed. If a bitmap is unintentional not transparent, another dropout color can be used.

The default dropout color is black (RGB(0,0,0)). If the overlay bitmap is created, it is filled with this color automatically.

Sample:

This example demonstrates how to fill the complete overlay bitmap with the color magenta that was set as the current dropout color. This makes the complete overlay bitmap transparent on the video stream.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
pOverlayBitmap = m_Grabber.getOverlay();
pOverlayBitmap->setDropOutColor( RGB(255,0,255));   // Magenta

// Fill the bitmap with the dropout color to make it completely transparent.
pOverlayBitmap->fill(pOverlayBitmap->getDropOutColor());
See also: OverlayBitmap, OverlayBitmap::fill, OverlayBitmap::getDropOutColor

<< OverlayBitmap


OverlayBitmap::setEnable

OverlayBitmap::setEnable Method
Enables or disables the display of the overlay bitmap on the live video.
Syntax:
bool setEnable( bool bOnOff );

Parameter | Description
bOnOff | Specifies whether the the overlay should be displayed or not. It defaults to false. If set to true, the overlay will be displayed on the live video stream. If set to false, the overlay is not displayed.
Return value:

true on success, false otherwise.

Remarks:

This method is used to enable or disable the display of the overlay on the live video. If the overlay is disabled, no CPU time is used because the overlay bitmap is not rendered. Since this is the default state, all applications that do not need an overlay will not suffer from a performance decrease.

See also: OverlayBitmap, OverlayBitmap::getEnable

<< OverlayBitmap


OverlayBitmap::setFlipVertical

OverlayBitmap::setFlipVertical Method
Enables or disables the vertical flip of the overlay bitmap.
Syntax:
bool setFlipVertical( bool bFlip );

Parameter | Description
bFlip | Specifies whether the the bitmap of the OverlayBitmap object should be flipped vertically. If bFlip is true, then the bitmap of the OverlayBitmap object will be copied bottom up on the video stream. If set to false, the bitmap of the OverlayBitmap object will be copied bottom down on the video stream.
Return value:

true on success, false otherwise.

Remarks:

This method is used to specify whether the bitmap of the OverlayBitmap object should be copied bottom up or bottom down on the live video. This is useful, if the video capture device delivers vertically flipped video images.

See also: OverlayBitmap, OverlayBitmap::getFlipVertical

<< OverlayBitmap


OverlayBitmap::setFont

OverlayBitmap::setFont Method
Sets the OverlayBitmaps object font to the specified font.
Syntax:
bool setFont(const char* faceName, int iSize = 10);
bool setFont(const std::string& faceName, int iSize = 10);
bool setFont(const std::wstring& szFaceName, int iSize = 10);
bool setFont(IFont* pFont);

Parameter | Description
faceName | A null-terminated string that specifies the typeface name of the font. The length of this string must not exceed 30 characters.
iSize | Specifies the desired size (in logical units) of the font. It defaults to 10
pFont | Interface pointer to an IFont COM font object pointer.
Return value:

true on success, false otherwise.

Remarks:

This method is used to set a font for drawing text on the bitmap of the OverlayBitmap object. Once a font is set, it is used for all text drawings until a new font is set.

The specified font is also used for the GDI TextOut() function.

Sample:

This example demonstrates how to set different font sizes.

smart_ptr<DShowLib::OverlayBitmap> pOverlayBitmap;
pOverlayBitmap = m_Grabber.getOverlay();

// Make sure, the overlay bitmap is enabled.
pOverlayBitmap->setEnable(true);

// Draw a big caption.
pOverlayBitmap->setFont("Arial",20);
pOverlayBitmap->drawText( RGB(255,0,0),  5, 0, "Caption" );

// Draw some text with a smaller font.
pOverlayBitmap->setFont("Arial",10);
pOverlayBitmap->drawText( RGB(255,0,0),  10, 35, "Text line 1" );
pOverlayBitmap->drawText( RGB(255,0,0),  10, 50, "Text line 2" );
See also: OverlayBitmap, OverlayBitmap::getFont, OverlayBitmap::drawText

<< OverlayBitmap


OverlayBitmap::setFontBKColor

OverlayBitmap::setFontBKColor Method
Sets the background color for drawing text to the specified color value, or to the nearest physical color if the device cannot represent the specified color value.
Syntax:
bool setFontBKColor( COLORREF background );

Parameter | Description
background | Specifies the color of the text background. The color can be specified with the RGB macro.
Return value:

true on success, false otherwise.

Remarks:

The background color is used to fill gaps between styled lines, gaps between hatched lines in brushes and character cells.

The text background is only visible, if the text background mode is opaque. This is to be done by a call to setFontTransparent(false). Otherwise, the text background is not drawn.

If the background color is set to the current dropout color, the background of the text is not visible.

The specified background color is used for all text drawings, until a new background color is set.

This method implements the same behavior as the GDI function SetBkColor().

See also: OverlayBitmap, OverlayBitmap::drawText, OverlayBitmap::getFontBKColor, OverlayBitmap::setFontTransparent, OverlayBitmap::getFontTransparent

<< OverlayBitmap


OverlayBitmap::setFontTransparent

OverlayBitmap::setFontTransparent Method
Sets the background mode for text drawings.
Syntax:
bool setFontTransparent( bool IsTransparent );

Parameter | Description
isTransparent | Specifies whether the background of the text is transparent. If set to true, the background under the text is filled with the current background color before the text is drawn. If set to false, the background under the text remains untouched.
Return value:

true on success, false otherwise.

See also: OverlayBitmap, OverlayBitmap::drawText, OverlayBitmap::setFontBKColor, OverlayBitmap::getFontTransparent

<< OverlayBitmap


VideoCaptureDeviceItem

The VideoCaptureDeviceItem identifies a video capture device. A VideoCaptureDeviceItem is a temporary object and may not be stored permanently. For permanent storage use the string representation as returned by c_str, toString, getName and operator const char*.

The list returned by Grabber::getAvailableVideoCaptureDevices consists of VideoCaptureDeviceItems. This list may be iterated or searched for a specific capture device with std::find.

Information

Header File: tisudshl.h
Namespace: DShowLib

Methods

Method | Description
VideoCaptureDeviceItem | Constructs a new VideoCaptureDeviceItem by copying an existing one.
c_str | This method returns the name of the video capture device as reported by its driver.
createInvalid | This method creates an invalid VideoCaptureDeviceItem.
getBaseName | Returns the base name of the video capture device.
getDisplayName | Returns the display name of the video capture device.
getName | This method returns the name of the video capture device as reported by its driver.
getSerialNumber | Returns the serial number of the device.
getUniqueName | Returns a unique name for this device.
isValid | Checks whether this object represents a video capture device or not.
operator const char* | Returns a name of this video capture device.
operator< | Compares the name of the video capture device with the name of another one.
operator= | Assigns a VideoCaptureDeviceItem to this object.
operator== | Checks whether two video capture devices are identical.
toString | This method returns the name of the video capture device as reported by its driver.

<< Classes


VideoCaptureDeviceItem::VideoCaptureDeviceItem

VideoCaptureDeviceItem::VideoCaptureDeviceItem Method
Constructs a new VideoCaptureDeviceItem by copying an existing one.
Syntax:
VideoCaptureDeviceItem( const VideoCaptureDeviceItem& vidcapdevitem );

Parameter | Description
vidcapdevitem | Specifies a VideoCaptureDeviceItem to be copied.
See also: VideoCaptureDeviceItem, Grabber::getAvailableVideoCaptureDevices

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::c_str

VideoCaptureDeviceItem::c_str Method
This method returns the name of the video capture device as reported by its driver.
Syntax:
const char* c_str() const;
Return value:

A 0-terminated string that contains the name of the video capture device.

Remarks:

toString, getName and c_str return the same text.

See also: VideoCaptureDeviceItem, VideoCaptureDeviceItem::toString, VideoCaptureDeviceItem::getName, VideoCaptureDeviceItem::getBaseName, VideoCaptureDeviceItem::getDisplayName, VideoCaptureDeviceItem::getUniqueName

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::createInvalid

VideoCaptureDeviceItem::createInvalid Method
This method creates an invalid VideoCaptureDeviceItem.
Syntax:
static VideoCaptureDeviceItem createInvalid();
Return value:

An invalid VideoCaptureDeviceItem.

See also: VideoCaptureDeviceItem, VideoCaptureDeviceItem::isValid

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::getName

VideoCaptureDeviceItem::getName Method
This method returns the name of the video capture device as reported by its driver.
Syntax:
const std::string& getName() const;
Return value:

A string that contains the name of the video capture device.

Remarks:

toString, getName and c_str return the same text.

See also: VideoCaptureDeviceItem, VideoCaptureDeviceItem::c_str, VideoCaptureDeviceItem::toString, VideoCaptureDeviceItem::getBaseName, VideoCaptureDeviceItem::getDisplayName, VideoCaptureDeviceItem::getUniqueName

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::getSerialNumber

VideoCaptureDeviceItem::getSerialNumber Method
Returns the serial number of the device.
Syntax:
bool getSerialNumber( __int64& id ) const;

Parameter | Description
id | A __int64 variable that is to receive the copied device id.
Return value:

true, if the serial number has been retrieved successfully. false, if the device does not provide access to its serial number or has no serial number.

Remarks:

Please note that this method returns the serial number that is returned by the firmware of the device. For most devices, this serial number differs from the one printed on the label that can be found on the device's housing. Even if it possible to find a transformation between the serial number on the label and the serial number returned by this method, the probability is high that the schema for one of them changes, thus causing the transformation to become invalid. The only safe way of identifying devices is to connect them to a system, using a tool that prints the return value of this method (like the code fragment below) and use this number to identify the device in your own software.

Sample:

This example demonstrates how to retrieve and interpret the serial number of the currently selected video capture device.

LARGE_INTEGER iResult ;
iResult.QuadPart = 0;
if( m_Grabber.getDev().getSerialNumber( iResult.QuadPart ) == true )
{
    TRACE("Serial number is %I64X\n", iResult.QuadPart);
    TRACE("Serial number high part : %d, low part %d\n", iResult.HighPart, iResult.LowPart);
}
else
{
    TRACE("Serial number could not be retrieved.\n");
}
See also: VideoCaptureDeviceItem

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::isValid

VideoCaptureDeviceItem::isValid Method
Checks whether this object represents a video capture device or not.
Syntax:
bool isValid() const;
Return value:

true, if the video capture device is valid, false otherwise.

See also: VideoCaptureDeviceItem, Grabber::isDevValid

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::operator const char*

VideoCaptureDeviceItem::operator const char* Method
Returns a name of this video capture device.
Syntax:
bool operator const char*() const;
Return value:

A string that represents this video capture device.

See also: VideoCaptureDeviceItem

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::operator<

VideoCaptureDeviceItem::operator< Method
Compares the name of the video capture device with the name of another one.
Syntax:
bool operator<( const VideoCaptureDeviceItem& op ) const;

Parameter | Description
op | A video capture device with which to compare.
Return value:

true, if the name of this video capture device item comes alphabetically before the string with which to compare. False, if this name is identical to or comes alphabetically after the string with which to compare.

Remarks:

Compares the names of this video capture device with the name of another one. The return value is the result of a lexicographical comparison between the two strings.

See also: VideoCaptureDeviceItem

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::operator=

VideoCaptureDeviceItem::operator= Method
Assigns a VideoCaptureDeviceItem to this object.
Syntax:
VideoCaptureDeviceItem& operator=( const VideoCaptureDeviceItem& op2 );

Parameter | Description
op2 | The VideoCaptureDeviceItem to assign.
Return value:

A reference to this.

See also: VideoCaptureDeviceItem

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::operator==

VideoCaptureDeviceItem::operator== Method
Checks whether two video capture devices are identical.
Syntax:
bool operator==( const VideoCaptureDeviceItem& op2 ) const;
bool operator==( const std::string& string ) const;
bool operator==( const __int64& serial ) const;

Parameter | Description
op2 | A video capture device with which to compare.
string | A pointer to a string with which the name of the video capture device should be compared.
serial | A serial number with which the serial number of this video capture device should be compared.
Return value:

true, if both operands are identical, false if they differ.

See also: VideoCaptureDeviceItem

<< VideoCaptureDeviceItem


VideoCaptureDeviceItem::toString

VideoCaptureDeviceItem::toString Method
This method returns the name of the video capture device as reported by its driver.
Syntax:
std::string toString() const;
std::wstring toStringW() const;
Return value:

A string that contains the name of the video capture device.

Remarks:

toString, getName and c_str return the same text.

Information:

Introduced in version 2.0
See also: VideoCaptureDeviceItem, VideoCaptureDeviceItem::c_str, VideoCaptureDeviceItem::getName, VideoCaptureDeviceItem::getBaseName, VideoCaptureDeviceItem::getDisplayName, VideoCaptureDeviceItem::getUniqueName

<< VideoCaptureDeviceItem


VideoFormatDesc

A VideoFormatDesc describes an available video format using the media subtype, a binning factor and size constraints. The size constraints are described by a minimum size, a maximum size and a step size.

To set a video format for a device, a VideoFormatItem instance has to be created by using VideoFormatDesc::createVideoFormat.

Information

Header File: tisudshl.h
Namespace: DShowLib
Introduced in version 3.2

Methods

Method | Description
createVideoFormat | This method creates a VideoFormatItem with the specified size based on the specification of this VideoFormatDesc.
getBinningFactor | Returns the binning factor of this VideoFormatDesc.
getColorformatString | Returns a string representation of the color format of this VideoFormatDesc.
getMaxSize | Returns the maximum possible size for video formats created from this VideoFormatDesc.
getMinSize | Returns the minimum possible size for video formats created from this VideoFormatDesc.
getStepSize | Returns the step size for video formats created from this VideoFormatDesc.
getSubtype | Returns the GUID of the media subtype of this video format description.
isROIFormat | Returns whether this VideoFormatDesc describes a ROI format.
isValidSize | This method checks whether a specified size matches the size constraints of this VideoFormatDesc.
toString | Returns a string representation of this VideoFormatDesc.

<< Classes


VideoFormatDesc::createVideoFormat

VideoFormatDesc::createVideoFormat Method
This method creates a VideoFormatItem with the specified size based on the specification of this VideoFormatDesc.
Syntax:
VideoFormatItem    createVideoFormat( SIZE size ) const;
VideoFormatItem    createVideoFormat( int width, int height ) const;

Parameter | Description
size | Size of the video format to be created.
width | Width of the video format to be created.
height | Height of the video format to be created.
Return value:

A VideoFormatItem instance with the specified size. An invalid VideoFormatItem is returned if the specified size does not match this VideoFormatDesc.

Remarks:

The validity of a size can be checked beforehand by calling VideoFormatDesc::isValidSize.

See also: VideoFormatItem, VideoFormatDesc::isValidSize

<< VideoFormatDesc


VideoFormatDesc::getBinningFactor

VideoFormatDesc::getBinningFactor Method
Returns the binning factor of this VideoFormatDesc.
Syntax:
int    getBinningFactor() const;
Return value:

The binning factor of this VideoFormatDesc.

See also: VideoFormatDesc

<< VideoFormatDesc


VideoFormatDesc::getColorformatString

VideoFormatDesc::getColorformatString Method
Returns a string representation of the color format of this VideoFormatDesc.
Syntax:
std::string    getColorformatString() const;
std::wstring    getColorformatStringW() const;
Return value:

A string representation of the media subtype of this VideoFormatDesc.

See also: VideoFormatDesc, VideoFormatDesc::getSubtype

<< VideoFormatDesc


VideoFormatDesc::getMaxSize

VideoFormatDesc::getMaxSize Method
Returns the maximum possible size for video formats created from this VideoFormatDesc.
Syntax:
SIZE    getMaxSize() const;
Return value:

The maximum possible size for video format instances.

See also: VideoFormatDesc, VideoFormatDesc::getMinSize, VideoFormatDesc::getStepSize

<< VideoFormatDesc


VideoFormatDesc::getMinSize

VideoFormatDesc::getMinSize Method
Returns the minimum possible size for video formats created from this VideoFormatDesc.
Syntax:
SIZE    getMinSize() const;
Return value:

The minimum possible size for video format instances.

See also: VideoFormatDesc, VideoFormatDesc::getMaxSize, VideoFormatDesc::getStepSize

<< VideoFormatDesc


VideoFormatDesc::getStepSize

VideoFormatDesc::getStepSize Method
Returns the step size for video formats created from this VideoFormatDesc.
Syntax:
SIZE    getStepSize() const;
Return value:

The step size for video format instances.

See also: VideoFormatDesc, VideoFormatDesc::getMinSize, VideoFormatDesc::getMaxSize

<< VideoFormatDesc


VideoFormatDesc::getSubtype

VideoFormatDesc::getSubtype Method
Returns the GUID of the media subtype of this video format description.
Syntax:
GUID    getSubtype() const;
Return value:

The GUID of the subtype.

See also: VideoFormatDesc, Standard Mediasubtype GUIDs

<< VideoFormatDesc


VideoFormatDesc::isROIFormat

VideoFormatDesc::isROIFormat Method
Returns whether this VideoFormatDesc describes a ROI format.
Syntax:
bool    isROIFormat() const;
Return value:

See also: VideoFormatDesc

<< VideoFormatDesc


VideoFormatDesc::isValidSize

VideoFormatDesc::isValidSize Method
This method checks whether a specified size matches the size constraints of this VideoFormatDesc.
Syntax:
bool    isValidSize( const SIZE& sz ) const;

Parameter | Description
sz | Size to be checked for validity.
Return value:

true, if a valid VideoFormatItem can be created with the specified size, otherwise false.

See also: VideoFormatDesc, VideoFormatDesc::createVideoFormat

<< VideoFormatDesc


VideoFormatDesc::toString

VideoFormatDesc::toString Method
Returns a string representation of this VideoFormatDesc.
Syntax:
std::string    toString() const;
std::wstring    toStringW() const;
Return value:

A string representation of this VideoFormatDesc.

See also: VideoFormatDesc

<< VideoFormatDesc


VideoFormatItem

The VideoFormatItem represents a video format that describes the width, height and the color format of an image stream generated by a video capture device. The available video formats depend on the selected video norm.

A VideoFormatItem is a temporary object and may not be stored permanently. For permanent storage use the string representation as returned by c_str, toString and operator const char*.

Information

Header File: tisudshl.h
Namespace: DShowLib

Methods

Method | Description
VideoFormatItem | Constructs a new VideoFormatItem object by copying an existing one.
c_str | This method returns a 0-terminated string that describes this video format.
createInvalid | This method creates a VideoFormatItem object that contains an invalid item.
getBinningFactor | Returns the binning factor of the video format.
getBitsPerPixel | This method returns the number of bits that represent a single pixel of the respective video format.
getColorformat | This method returns the GUID of the color format used by this video format.
getColorformatString | This method returns the name of the color format used by this video format.
getSize | This method returns a SIZE structure containing the width and height of one frame of this video format.
getSizeString | This method returns a string that describes the size of a frame of this video format.
getSubtype | This method returns the GUID of the subtype used by this video format.
isValid | Checks whether this instance is a valid video format for the currently active video capture device.
operator const char* | Returns a 0-terminated string that describes this video format.
operator!= | Checks whether two video formats differ.
operator< | Compares the names of two video format items.
operator= | Assigns a VideoFormatItem to this object.
operator== | Checks whether two video formats are identical.
toString | Returns a string that describes this video format.

<< Classes


VideoFormatItem::VideoFormatItem

VideoFormatItem::VideoFormatItem Method
Constructs a new VideoFormatItem object by copying an existing one.
Syntax:
VideoFormatItem( const DShowLib::VideoFormatItem& vidfmtitem );

Parameter | Description
vidfmtitem | Specifies an existing VideoFormatItem to copy.
See also: VideoFormatItem, Grabber::getVideoFormat, Grabber::getAvailableVideoFormats, Grabber::setVideoFormat

<< VideoFormatItem


VideoFormatItem::c_str

VideoFormatItem::c_str Method
This method returns a 0-terminated string that describes this video format.
Syntax:
const char* c_str() const;
Return value:

A 0-terminated string that describes the video format.

Remarks:

toString and c_str return the same text.

See also: VideoFormatItem, VideoFormatItem::toString

<< VideoFormatItem


VideoFormatItem::createInvalid

VideoFormatItem::createInvalid Method
This method creates a VideoFormatItem object that contains an invalid item.
Syntax:
static VideoFormatItem createInvalid();
Return value:

An invalid VideoFormatItem.

See also: VideoFormatItem, VideoFormatItem::isValid

<< VideoFormatItem


VideoFormatItem::getBinningFactor

VideoFormatItem::getBinningFactor Method
Returns the binning factor of the video format.
Syntax:
int    getBinningFactor() const;
Return value:

The binning factor of the video format.

See also: VideoFormatItem

<< VideoFormatItem


VideoFormatItem::getBitsPerPixel

VideoFormatItem::getBitsPerPixel Method
This method returns the number of bits that represent a single pixel of the respective video format.
Syntax:
DWORD getBitsPerPixel() const;
Return value:

The number of bits that represent a single pixel.

See also: VideoFormatItem

<< VideoFormatItem


VideoFormatItem::getColorformat

VideoFormatItem::getColorformat Method
This method returns the GUID of the color format used by this video format.
Syntax:
GUID getColorformat() const;
Return value:

The GUID of the color format.

See also: VideoFormatItem, VideoFormatItem::getColorformatString

<< VideoFormatItem


VideoFormatItem::getColorformatString

VideoFormatItem::getColorformatString Method
This method returns the name of the color format used by this video format.
Syntax:
std::string getColorformatString() const;
std::wstring getColorformatStringW() const;
Return value:

A string that describes the color format.

See also: VideoFormatItem, VideoFormatItem::c_str, VideoFormatItem::getSizeString

<< VideoFormatItem


VideoFormatItem::getSize

VideoFormatItem::getSize Method
This method returns a SIZE structure containing the width and height of one frame of this video format.
Syntax:
SIZE getSize() const;
Return value:

A SIZE structure.

See also: VideoFormatItem

<< VideoFormatItem


VideoFormatItem::getSizeString

VideoFormatItem::getSizeString Method
This method returns a string that describes the size of a frame of this video format.
Syntax:
std::string getSizeString() const;
std::wstring getSizeStringW() const;
Return value:

A string that describes the size of a frame of this video format.

See also: VideoFormatItem, VideoFormatItem::c_str, VideoFormatItem::getColorformatString

<< VideoFormatItem


VideoFormatItem::getSubtype

VideoFormatItem::getSubtype Method
This method returns the GUID of the subtype used by this video format.
Syntax:
GUID getSubtype() const;
Return value:

The GUID of the subtype.

Information:

Introduced in version 3.0
See also: VideoFormatItem, VideoFormatItem::getColorformat, VideoFormatItem::getColorformatString

<< VideoFormatItem


VideoFormatItem::isValid

VideoFormatItem::isValid Method
Checks whether this instance is a valid video format for the currently active video capture device.
Syntax:
bool isValid() const;
Return value:

true, if this instance is a valid video format, false otherwise.

See also: VideoFormatItem, Grabber::getAvailableVideoFormats

<< VideoFormatItem


VideoFormatItem::operator const char*

VideoFormatItem::operator const char* Method
Returns a 0-terminated string that describes this video format.
Syntax:
operator const char* () const;
Return value:

A 0-terminated string that describes this video format.

See also: VideoFormatItem

<< VideoFormatItem


VideoFormatItem::operator!=

VideoFormatItem::operator!= Method
Checks whether two video formats differ.
Syntax:
bool operator!=( const VideoFormatItem& op ) const;

Parameter | Description
op | A VideoFormatItem with which to compare.
Return value:

true, if the video formats differ, false if they are identical.

See also: VideoFormatItem, VideoFormatItem::operator==

<< VideoFormatItem


VideoFormatItem::operator<

VideoFormatItem::operator< Method
Compares the names of two video format items.
Syntax:
bool operator<( const VideoFormatItem& op ) const;

Parameter | Description
op | A VideoFormatItem with which to compare.
Return value:

true, if the name of this video format item comes alphabetically before the name of the video format with which to compare. false, if the name of this video format is identical to or comes alphabetically after the name of the video format with which to compare.

Remarks:

Compares the names of two video format items. The return value is the result of a lexicographical comparison between the two strings. The name is a string that describes this video format.

See also: VideoFormatItem

<< VideoFormatItem


VideoFormatItem::operator=

VideoFormatItem::operator= Method
Assigns a VideoFormatItem to this object.
Syntax:
VideoFormatItem& operator=( const VideoFormatItem& op2 );

Parameter | Description
op2 | The VideoFormatItem to assign.
Return value:

A reference to this.

See also: VideoFormatItem

<< VideoFormatItem


VideoFormatItem::operator==

VideoFormatItem::operator== Method
Checks whether two video formats are identical.
Syntax:
bool operator==( const VideoFormatItem& op ) const;
bool operator==( const std::string& string ) const;
bool operator==( const std::wstring& string ) const;

Parameter | Description
op | A VideoFormatItem with which to compare.
string | A pointer to a string with which the name of this VideoFormatItem should be compared. The name is a string that describes this video format.
Return value:

true, if both operands are identical, false if they differ.

See also: VideoFormatItem, VideoFormatItem::operator!=

<< VideoFormatItem


VideoFormatItem::toString

VideoFormatItem::toString Method
Returns a string that describes this video format.
Syntax:
std::string toString() const;
std::wstring toStringW() const;
Return value:

A string that describes this object.

Remarks:

toString and c_str return the same text.

Information:

Introduced in version 2.0
See also: VideoFormatItem, VideoFormatItem::c_str

<< VideoFormatItem


VideoNormItem

The VideoNormItem represents a video norm supported by a video capture device.

The list generated by Grabber::getAvailableVideoNorms consists of VideoNormItems. This list may be iterated or searched for a specific string describing a video norm with std::find.

Information

Header File: tisudshl.h
Namespace: DShowLib

Methods

Method | Description
VideoNormItem | Constructs a new VideoNormItem by copying an existing one.
c_str | This method returns the name of this video norm.
createInvalid | This method creates an invalid VideoNormItem object.
getVideoNorm | This method returns the analog video standard used by this VideoNormItem.
isValid | This method checks whether this video norm is valid for the current video capture device or not.
operator const char* | Returns the name of this video norm.
operator!= | Checks whether two video norms differ.
operator< | Compares the name of two video format items.
operator= | Assigns a VideoNormItem to this object.
operator== | Checks whether two video norms are the same.
toString | Returns the name of this object

<< Classes


VideoNormItem::VideoNormItem

VideoNormItem::VideoNormItem Method
Constructs a new VideoNormItem by copying an existing one.
Syntax:
VideoNormItem( const DShowLib::VideoNormItem& vidnrmitem );

Parameter | Description
vidnrmitem | Specifies the other video norm item to copy.
See also: VideoNormItem, Grabber::getAvailableVideoNorms, Grabber::getVideoNorm, Grabber::setVideoNorm

<< VideoNormItem


VideoNormItem::c_str

VideoNormItem::c_str Method
This method returns the name of this video norm.
Syntax:
const char* c_str() const;
Return value:

A 0-terminated string that represents the video norm.

Remarks:

toString and c_str return the same text.

See also: VideoNormItem, VideoNormItem::toString

<< VideoNormItem


VideoNormItem::createInvalid

VideoNormItem::createInvalid Method
This method creates an invalid VideoNormItem object.
Syntax:
static VideoNormItem createInvalid();
Return value:

An invalid VideoNormItem.

See also: VideoNormItem, VideoNormItem::isValid

<< VideoNormItem


VideoNormItem::getVideoNorm

VideoNormItem::getVideoNorm Method
This method returns the analog video standard used by this VideoNormItem.
Syntax:
AnalogVideoStandard getVideoNorm() const;
Return value:

An AnalogVideoStandard.

Remarks:

The AnalogVideoStandard is an enumeration defined in Microsoft DirectX 8.

See also: VideoNormItem, VideoNormItem::c_str

<< VideoNormItem


VideoNormItem::isValid

VideoNormItem::isValid Method
This method checks whether this video norm is valid for the current video capture device or not.
Syntax:
bool isValid() const;
Return value:

true, if this video norm is valid for the current video capture device, false, otherwise.

See also: VideoNormItem, VideoNormItem::createInvalid

<< VideoNormItem


VideoNormItem::operator const char*

VideoNormItem::operator const char* Method
Returns the name of this video norm.
Syntax:
operator const char* () const;
Return value:

A string that describes this video norm.

See also: VideoNormItem

<< VideoNormItem


VideoNormItem::operator!=

VideoNormItem::operator!= Method
Checks whether two video norms differ.
Syntax:
bool operator!=( const VideoNormItem& op ) const;

Parameter | Description
op | A VideoNormItem with which to compare.
Return value:

true, if this video norm and the compared one differ, false, if the video norms are the same.

See also: VideoNormItem, VideoNormItem::operator==

<< VideoNormItem


VideoNormItem::operator<

VideoNormItem::operator< Method
Compares the name of two video format items.
Syntax:
bool operator<( const VideoNormItem& op ) const;

Parameter | Description
op | A VideoFormatItem with which to compare.
Return value:

true, if the name of this video capture device item comes alphabetically before the string with which to compare. False, if this name is equal to or comes alphabetically after the string with which to compare.

Remarks:

Compares the name of two video norm items. The return value is the result of a lexicographical comparison between the two strings.

See also: VideoNormItem

<< VideoNormItem


VideoNormItem::operator=

VideoNormItem::operator= Method
Assigns a VideoNormItem to this object.
Syntax:
VideoNormItem& operator=( const VideoNormItem& op2 );

Parameter | Description
op2 | The VideoNormItem to assign.
Return value:

A reference to this.

See also: VideoNormItem

<< VideoNormItem


VideoNormItem::operator==

VideoNormItem::operator== Method
Checks whether two video norms are the same.
Syntax:
bool operator==( const VideoNormItem& op ) const;
bool operator==( const std::string& string ) const;
bool operator==( const std::wstring& string ) const;

Parameter | Description
op | A VideoNormItem with which to compare.
string | A pointer to a string with which the name of this VideoNormItem should be compared with.
Return value:

true, if both operands are equal, false, if they differ.

See also: VideoNormItem, VideoNormItem::operator!=

<< VideoNormItem


VideoNormItem::toString

VideoNormItem::toString Method
Returns the name of this object
Syntax:
std::string toString() const;
std::wstring toStringW() const;
Return value:

The name of this object.

Remarks:

toString and c_str return the same text.

Information:

Introduced in version 2.0
See also: VideoNormItem, VideoNormItem::c_str

<< VideoNormItem


smart_com

smart_com is a reference counting pointer to COM objects. It releases reference to the IUnknown interface when it is destroyed.

Information

Header File: tisudshl.h

Methods

Method | Description
getIID | Returns the interface ID of the type of objects this object points to.
operator!= | Checks whether op2 or p differ from this smart_com.
operator-> | Returns a pointer to the object to which this points to. If the pointer is not set, this operator will fail with a null pointer exception.
operator= | Assigns another smart_com to this.
operator== | Checks whether op2 or p and this smart_com are identical.

<< Classes


smart_com::getIID

smart_com::getIID Method
Returns the interface ID of the type of objects this object points to.
Syntax:
static GUID getIID();
Return value:

The IID of the type this pointer points to.

See also: smart_com

<< smart_com


smart_com::operator!=

smart_com::operator!= Method
Checks whether op2 or p differ from this smart_com.
Syntax:
bool operator!=( const smart_com& op2 ) const;
bool operator!=( const pointer p ) const;
Return value:

true if the pointers differ, false if they are equal.

See also: smart_com, smart_com::operator==

<< smart_com


smart_com::operator->

smart_com::operator-> Method
Returns a pointer to the object to which this points to. If the pointer is not set, this operator will fail with a null pointer exception.
Syntax:
pointer operator->();
const_pointer operator->() const;
Return value:

A pointer to the object referenced by this.

See also: smart_com

<< smart_com


smart_com::operator=

smart_com::operator= Method
Assigns another smart_com to this.
Syntax:
smart_com& operator=( smart_ptr op2 );

Parameter | Description
op2 | The smart_com to be assigned to this.
Return value:

A reference to this.

Remarks:

If the target of the assignment pointed to an object before the operation, Release will be called on that object. The object will be deleted, if this instance of smart_com held the last reference.

AddRef will be called on the object pointed to by the assigned smart_com.

See also: smart_com

<< smart_com


smart_com::operator==

smart_com::operator== Method
Checks whether op2 or p and this smart_com are identical.
Syntax:
bool operator==( const smart_com& op2 ) const;
bool operator==( const pointer p ) const;
Return value:

true if the pointers are identical, false if they differ.

See also: smart_com, smart_com::operator!=

<< smart_com


smart_ptr

The smart_ptr is a reference counting pointer object. Whenever a method of the IC Imaging Control Class Library returns a pointer, it will be an object of this class.

Information

Header File: tisudshl.h

Methods

Method | Description
operator!= | Checks whether op2 or p differs from this smart_ptr.
operator* | Returns the object to which this points. If the pointer is not set, this operator will fail with a null pointer exception.
operator-> | Returns a pointer to the object to which this points. If the pointer is not set, this operator will fail with a null pointer exception.
operator= | Assigns another smart_ptr to this.
operator== | Checks whether op2 or p and this smart_ptr are identical.

<< Classes


smart_ptr::operator!=

smart_ptr::operator!= Method
Checks whether op2 or p differs from this smart_ptr.
Syntax:
bool operator!=( const smart_ptr& op2 ) const;
bool operator!=( const pointer p ) const;
Return value:

true if the pointers differ, false if they are equal.

See also: smart_ptr, smart_ptr::operator==

<< smart_ptr


smart_ptr::operator*

smart_ptr::operator* Method
Returns the object to which this points. If the pointer is not set, this operator will fail with a null pointer exception.
Syntax:
reference operator*();
const_reference operator*() const;
Return value:

The object pointed to by this.

See also: smart_ptr, smart_ptr::operator->

<< smart_ptr


smart_ptr::operator->

smart_ptr::operator-> Method
Returns a pointer to the object to which this points. If the pointer is not set, this operator will fail with a null pointer exception.
Syntax:
pointer operator->();
const_pointer operator->() const;
Return value:

A pointer to the object to which this points.

See also: smart_ptr, smart_ptr::operator*

<< smart_ptr


smart_ptr::operator=

smart_ptr::operator= Method
Assigns another smart_ptr to this.
Syntax:
smart_ptr& operator=( smart_ptr op2 );

Parameter | Description
op2 | The smart_ptr to be assigned to this.
Return value:

A reference to this.

Remarks:

If the target of the assignment pointed to an object before the operation, the reference counter for that object will be decreased and the object will be deleted, if this instance of smart_ptr held the last reference.

The reference count of the object pointed to by the assigned smart_ptr is increased by one.

See also: smart_ptr

<< smart_ptr


smart_ptr::operator==

smart_ptr::operator== Method
Checks whether op2 or p and this smart_ptr are identical.
Syntax:
bool operator==( const smart_ptr& op2 ) const;
bool operator==( const pointer p ) const;
Return value:

true if the pointers are identical, false if they differ.

See also: smart_ptr, smart_ptr::operator!=

<< smart_ptr


Enumerations

Complete list of all enumerations.

Enumerations

Enumeration | Description
RGB555Mask | RGB555Mask defines the masks you can use to access the color channels of images stored in RGB555-format.
RGB565Mask | RGB565Mask defines the masks you can use to access the color channels of images stored in RGB565-format.
tColorformatEnum | tColorformatEnum enumerates the possible color formats.
tErrorEnum | tErrorEnum enumerates the possible error types.
tFilterClass | Frame filters have a filter class that allows them to be categorized:
tFilterError | The members of this enumerations describe error conditions returned by the methods of IFrameFilter, such as getParameter or setParameter.
tFrameDesc | tFrameDesc enumerates the possible frame types.
tPathPosition | tPathPosition enumerates the possible positions of the OverlayBitmap in the image stream.
tSinkType | tSinkType enumerates the possible sink types.

<< Class Library Reference


refenum::RGB555Mask

RGB555Mask
RGB555Mask defines the masks you can use to access the color channels of images stored in RGB555-format.
Enumeration | Description
eRGB555_B | Access the blue bits
eRGB555_G | Access the green bits
eRGB555_R | Access the red bits

<< Class Library Reference


refenum::RGB565Mask

RGB565Mask
RGB565Mask defines the masks you can use to access the color channels of images stored in RGB565-format.
Enumeration | Description
eRGB565_B | Access the blue bits
eRGB565_G | Access the green bits
eRGB565_R | Access the red bits

<< Class Library Reference


refenum::tColorformatEnum

tColorformatEnum
tColorformatEnum enumerates the possible color formats.
For a description of the pixel organization in the various color formats, have a look at the example Accessing an Image Buffer.
Enumeration | Description
eInvalidColorformat | Invalid color format (do not use).
eRGB32 | 32 bit color depth
eRGB24 | 24 bit color depth
eRGB565 | 16 bit color depth with red 5 green 6 blue 5 bit encoding
eRGB555 | 16 bit color depth with red 5 green 5 blue 5 bit encoding
eRGB8 | 8 bit grayscale
eUYVY | UYVY color format
eY800 | 8 bit Y format, top down
eYGB0 | 16 bit Y (10 bit valid) format
eYGB1 | 16 bit Y (10 bit valid) format
eBY8 | 8 bit bayer raw format. See Debayering for information on how to handle this format.

<< Class Library Reference


refenum::tErrorEnum

tErrorEnum
tErrorEnum enumerates the possible error types.
Enumeration | Description
eNOERROR | No error occurred.
eUNKNOWN | An unknown error occurred.
eDShowLib_EXCEPTION | An unexpected DShowLibException occurred, please contact the producer's support department.
eUNEXPECTED_DShowLib_BEHAVIOUR | DShowLib behaves unexpected, please contact the producer's support department.
eOUT_OF_MEMORY | The system ran out of memory.
eWRITE_ERROR | An error occurred while writing.
eNO_VIDEO_HARDWARE_FOUND | No video hardware could be found on this system.
eINVALID_PARAM_VAL | A function was called with an invalid parameter.
eAUTOMATION_ENABLED | A property value should be changed, but automation is enabled for this property.
eNO_CURRENT_VALUE | A value should be queried, but there is no value that could be returned. For example, this is the case, if the value of a property is queried, but the property does not exist on the current video capture device.
eINVALID_MEMBUFFER | The format of the MemBuffer does not match the format of the frame grabber.
eMODE_ALREADY_ACTIVE | The frame grabber should be put into live mode or stopped from live mode, but the requested mode is already selected.
eNO_DEVICE_OPENED | There is currently no video capture device opened.
eDEVICE_INVALID | The current video capture device has become invalid. This usually means it was unplugged.
eDRIVER_INSTALLATION | A required driver component could not be loaded.
eNOT_AVALILABLE_WITH_CURRENT_DEVICE | The called function is not available on the current video capture device.
eAUTOMATION_NOT_AVAILABLE | Automation should be enabled for a specific property, but the video capture device does not support automation for this property.
eDEVICE_NOT_FOUND | The requested device was not found.
eITEM_DOES_NOT_FIT_TO_DEV | The given item does not fit to the current device.
eFUNC_NOT_AVAIL_IN_LIVEMODE | A function that does not work when the grabber is in live mode has been called.
eFUNC_ONLY_AVAIL_IN_LIVEMODE | A function that only works when the grabber is in live mode has been called.
eNOT_INITIALIZED | The object has not yet been initialized.
eNO_FRAMEGRABBER_SINK | The called function requires the current sink to be of type FrameGrabberSink, but another SinkType is selected.
eSERIALNUMBER_INVALID | The library was not initialized with the correct serial number / license key.
eVIDEOFORMAT_INVALID | The current video format is invalid.
eUNEXPECTED_SINKFORMAT_CHANGE | The sink format of an avi sink or frame grabber sink changed for some unknown reason while the filter graph was being built.
eNO_EXTERNALTRANSPORT_AVAILABLE | An application tries to use external transport, but the video capture device does not support external transport.
eTIMEOUT_PREMATURLY_ELAPSED | An application is trying to snap images, however, no images are being delivered by the video capture device. The timeout default is 2 seconds.
ePASSED_DATA_DOES_NOT_FIT_TO_COMPRESSOR | An application tries to send invalid parameters to a codec.
eOPTION_NOT_AVAILABLE | An application tries to perform a feature, that is not supported by the video capture device.
eCOMPONENT_NOT_FOUND | A DLL or TCA file is missing.
eNO_CODECS_FOUND | There are no video compressors (codecs) found on the system.
eINCOMPATIBLE_VERSION | The version of the data format passed to the function is incompatible with the function.
eREAD_ERROR | An error occurred while trying to read data from a file.
eINCOMPLETE | The operation was only partially successful, e.g. not all properties of the grabber could be restored.

<< Class Library Reference


refenum::tFrameDesc

tFrameDesc
tFrameDesc enumerates the possible frame types.
Enumeration | Description
eFRAME_INTERLEAVED | The frame is an interleaved frame.
eFRAME_FIELD1 | The frame is the first field of a frame.
eFRAME_FIELD2 | The frame is the second field of a frame.

<< Class Library Reference


refenum::tSinkType

tSinkType
tSinkType enumerates the possible sink types.
Enumeration | Description
eFRAME_GRABBER_SINK | The sink type is an instance of FrameGrabberSink.
eAVI_SINK | The sink type is an instance of AviSink.
eMEDIASTREAM_SINK | The sink type is an instance of MediaStreamSink.
eFRAMEHANDLER_SINK | The sink type is an instance of FrameHandlerSink.

<< Class Library Reference


Functions

Complete list of all functions.

Methods

Method | Description
CanUnloadLibrary | This function checks whether all objects returned by the library are destroyed.
ExitLibrary | This function unloads the library and relinquishes all allocated resources.
GUIDToWString | Returns a string representation of a GUID.
InitLibrary | This function initializes the IC Imaging Control class library.
StringToGUID | Creates a GUID from a string containing the GUID in the format {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}.
astows | Converts a std::string into a std::wstring.
calcBufferSize | Calculates the number of bytes needed to store one frame of image data with a specified dimension and color format.
calcRequiredBuffersize | Calculates the number of bytes needed to store one frame of image data with the specified FrameTypeInfo.
convertToString | Creates a string representation from a FrameTypeInfo.
createBitmapInfoHeader | Creates a BITMAPINFOHEADER structure filled with the frame type description from a FrameTypeInfo.
createFCCMediaSubType | Creates a FourCC media subtype from a 4-character-string.
getBitsPerPixel | Returns the number of bits needed to store one pixel of image data in the specified format.
getColorformatFromSubtype | Returns the tColorformatEnum, corresponding to the specified media subtype.
getSubtypeFromColorformat | Returns the media subtype GUID, corresponding to the specified color format.
isBottomUpFrameType | Checks whether a frame type is a bottom-up video format.
saveToFileBMP | This function saves the contents of an image buffer to a .BMP file.
saveToFileJPEG | This function saves the contents of an image buffer to a JPEG file.
wstoas | Converts a std::wstring into a std::string.

<< Class Library Reference


reffunctions::CanUnloadLibrary

CanUnloadLibrary Method
This function checks whether all objects returned by the library are destroyed.
Syntax:
bool CanUnloadLibrary();
Return value:

The method returns true, if all objects that were returned by the library are destroyed. If one or more objects are still alive, false is returned.

Remarks:

CanUnloadLibrary can be used to determine the best time to unload the library (e.g. for COM objects).

Information:

Introduced in version 2.0

<< Class Library Reference


reffunctions::ExitLibrary

ExitLibrary Method
This function unloads the library and relinquishes all allocated resources.
Syntax:
void ExitLibrary();
Remarks:

For every call to InitLibrary there should be a call to ExitLibrary. You can use this method to implement unloading of IC Imaging Control.

Information:

Introduced in version 3.1
See also: InitLibrary

<< Class Library Reference


reffunctions::InitLibrary

InitLibrary Method
This function initializes the IC Imaging Control class library.
Syntax:
bool InitLibrary();
bool InitLibrary( const char* pLicenseKey, DWORD coinitmode = 0 );

Parameter | Description
pLicenseKey | If you have a professional version of IC Imaging Control, pass your license key here. Otherwise always pass 0.
coinitmode | Specifies the parameter to pass to CoInitializeEx. If you pass -1, the library does not initialize COM. If you pass any other value (e.g. COINIT_MULTITHREADED or COINIT_APARTMENTTHREADED ) it is used. When you do not specify this parameter COINIT_MULTITHREADED is used.
Return value:

The method returns true on success, otherwise it returns false.

Remarks:

InitLibrary must be called at the start of an application. It must be called once before any other classes of IC Imaging Control can be used. When you do not specify the coinitmode parameter, COM is initialized with COINIT_MULTITHREADED. For every call to InitLibrary there should be a corresponding call to ExitLibrary
Sample:

This example demonstrates how to use InitLibrary.

if( !DShowLib::InitLibrary() )
{
    return FALSE;
}

This example demonstrates how to use InitLibrary when you already called CoInitialize

CoInitialize( 0 );
if( !DShowLib::InitLibrary( 0, -1 ) )
{
    return FALSE;
}
See also: ExitLibrary

<< Class Library Reference


Structures

Complete list of all structures.

Structs

Struct | Description
FilterInfo | The FilterInfo structure contains information about a frame filter that can be loaded from a .ftf file.
tsFrameEndCallback | The tsFrameEndCallback contains information about a user callback function called on each frame end event. You should not use the callback functions, use GrabberListener instead.
tsMediaSampleDesc | The tsMediaSampleDesc contains timestamp information about a frame.
tsPropertyRange | The tsPropertyRange contains the range for the values of a device property.

<< Class Library Reference


refstruct::tsFrameEndCallback

tsFrameEndCallback Structure
The tsFrameEndCallback contains information about a user callback function called on each frame end event. You should not use the callback functions, use GrabberListener instead.
Syntax:
struct tsFrameEndCallback
{
    typedef smart_ptr< MemBuffer > tMemBufferPtr;

    typedef void (*tFrameEndCallbackFuncPtr)( void* ptr, tMemBufferPtr pBuffer, DWORD frameCount );

    tsFrameEndCallback();
    tsFrameEndCallback( tFrameEndCallbackFuncPtr func, void* data );

    tFrameEndCallbackFuncPtr pFunc;
    void* pData;
};

<< Class Library Reference


refstruct::tsMediaSampleDesc

tsMediaSampleDesc Structure
The tsMediaSampleDesc contains timestamp information about a frame.
Syntax:
typedef struct
{
    REFERENCE_TIME  SampleStart;
    REFERENCE_TIME  SampleEnd;
    DWORD           FrameNumber;
    tFrameDesc      FrameType;      // Type of the frame
} tsMediaSampleDesc;

Members | Description
SampleStart | Start time of the sample, as set by the video capture device.
SampleEnd | End time of the sample, as set by the video capture device.
FrameNumber | Frame number of the sample, as set by the video capture device. The device does not need to set this field, or keep it updated.
FrameType | Type of frame, described with a tFrameDesc enumeration member.

<< Class Library Reference


refstruct::tsPropertyRange

tsPropertyRange Structure
The tsPropertyRange contains the range for the values of a device property.
Syntax:
typedef struct
{
    long min;
    long max;
} tsPropertyRange

Members | Description
min | Minimum value for the property
max | Maximum value for the property

<< Class Library Reference


Type Definitions

Complete list of all type definitions in namespace DShowLib.

Type Definitions

Type | Description
tCodecList | tCodecList is a std::vector of tCodecPtrs.
tCodecListPtr | tCodecListPtr is a smart_ptr to a tCodecList.
tCodecPtr | tCodecPtr is a smart_ptr to a Codec.
tFrameFilterList | tFrameFilterList is a vector of pointers to IFrameFilter objects.
tFrameHandlerSinkPtr | tFrameHandlerSinkPtr is a smart pointer to a FrameHandlerSink.
tGUIDArray | An array of GUIDs.
tIVCDAbsoluteValuePropertyPtr | A pointer to an IVCDAbsoluteValueProperty.
tIVCDButtonPropertyPtr | A pointer to an IVCDButtonProperty.
tIVCDMapStringsPropertyPtr | A pointer to an IVCDMapStringsProperty.
tIVCDMapSwitchPropertyPtr | A pointer to an IVCDSwitchProperty.
tIVCDPropertyElementPtr | A pointer to an IVCDPropertyElement.
tIVCDPropertyInterfacePtr | A pointer to an IVCDPropertyInterface.
tIVCDPropertyInterfacePtr | A pointer to an IVCDPropertyInterface.
tIVCDPropertyItemPtr | A pointer to an IVCDPropertyItem.
tIVCDPropertyItemsPtr | A pointer to an IVCDPropertyItems collection.
tIVCDRangePropertyPtr | A pointer to an IVCDRangeProperty.
tMediaStreamContainerList | A vector of tMediaStreamContainerPtrs.
tMediaStreamContainerListPtr | A smart_ptr to a tMediaStreamContainerList.
tMediaStreamContainerPtr | A smart_ptr to a MediaStreamContainer object.
tMediaStreamSinkPtr | tMediaStreamSinkPtr is a smart pointer to a MediaStreamSink.
tMemBufferCollectionPtr | A pointer to a MemBufferCollection.
tVCDCategoryMap | A map that maps properties that belong together in to one group. The group is described by a string.
tVCDPropertyElementArray | An array of tIVCDPropertyElementPtrs.
tVCDPropertyInterfaceArray | An array of tIVCDPropertyInterfacePtrs.
tVCDPropertyItemArray | An array of tIVCDPropertyItemPtrs.

<< Class Library Reference


typedef::tGUIDArray

tGUIDArray
An array of GUIDs.
Syntax:
typedef std::vector<GUID> tGUIDArray;

<< Class Library Reference


typedef::tIVCDAbsoluteValuePropertyPtr

tIVCDAbsoluteValuePropertyPtr
A pointer to an IVCDAbsoluteValueProperty.
Syntax:
typedef smart_com<IVCDAbsoluteValueProperty> tIVCDAbsoluteValuePropertyPtr;

<< Class Library Reference


typedef::tIVCDButtonPropertyPtr

tIVCDButtonPropertyPtr
A pointer to an IVCDButtonProperty.
Syntax:
typedef smart_com<IVCDButtonProperty> tIVCDButtonPropertyPtr;

<< Class Library Reference


typedef::tIVCDMapStringsPropertyPtr

tIVCDMapStringsPropertyPtr
A pointer to an IVCDMapStringsProperty.
Syntax:
typedef smart_com<IVCDMapStringsProperty> tIVCDMapStringsPropertyPtr;

<< Class Library Reference


typedef::tIVCDMapSwitchPropertyPtr

tIVCDMapSwitchPropertyPtr
A pointer to an IVCDSwitchProperty.
Syntax:
typedef smart_com<IVCDSwitchProperty> tIVCDMapSwitchPropertyPtr;

<< Class Library Reference


typedef::tIVCDPropertyElementPtr

tIVCDPropertyElementPtr
A pointer to an IVCDPropertyElement.
Syntax:
typedef smart_com<IVCDPropertyElement> tIVCDPropertyElementPtr;

<< Class Library Reference


typedef::tIVCDPropertyInterfacePtr

tIVCDPropertyInterfacePtr
A pointer to an IVCDPropertyInterface.
Syntax:
typedef smart_com<IVCDPropertyInterface> tIVCDPropertyInterfacePtr;

<< Class Library Reference


typedef::tIVCDPropertyItemPtr

tIVCDPropertyItemPtr
A pointer to an IVCDPropertyItem.
Syntax:
typedef smart_com<IVCDPropertyItem> tIVCDPropertyItemPtr;

<< Class Library Reference


typedef::tIVCDPropertyItemsPtr

tIVCDPropertyItemsPtr
A pointer to an IVCDPropertyItems collection.
Syntax:
typedef smart_com<IVCDPropertyItems> tIVCDPropertyItemsPtr;

<< Class Library Reference


typedef::tIVCDRangePropertyPtr

tIVCDRangePropertyPtr
A pointer to an IVCDRangeProperty.
Syntax:
typedef smart_com<IVCDRangeProperty> tIVCDRangePropertyPtr;

<< Class Library Reference


typedef::tMemBufferCollectionPtr

tMemBufferCollectionPtr
A pointer to a MemBufferCollection.
Syntax:
typedef smart_com<MemBufferCollection> tMemBufferCollectionPtr;

<< Class Library Reference


typedef::tVCDCategoryMap

tVCDCategoryMap
A map that maps properties that belong together in to one group. The group is described by a string.
Syntax:
typedef std::map<std::string, tGUIDArray> tVCDCategoryMap;
typedef std::map<std::wstring, tGUIDArray> tVCDCategoryMapW;

<< Class Library Reference


typedef::tVCDPropertyElementArray

tVCDPropertyElementArray
An array of tIVCDPropertyElementPtrs.
Syntax:
typedef std::vector<tIVCDPropertyElementPtr> tVCDPropertyElementArray;

<< Class Library Reference


typedef::tVCDPropertyInterfaceArray

tVCDPropertyInterfaceArray
An array of tIVCDPropertyInterfacePtrs.
Syntax:
typedef std::vector<tIVCDPropertyInterfacePtr> tVCDPropertyInterfaceArray;

<< Class Library Reference


typedef::tVCDPropertyItemArray

tVCDPropertyItemArray
An array of tIVCDPropertyItemPtrs.
Syntax:
typedef std::vector<tIVCDPropertyItemPtr> tVCDPropertyItemArray;

<< Class Library Reference


IC Imaging Control Standard Filters

IC Imaging Control ships with several standard frame filters. They can be explored with the Filter Inspector application.

The frame filter module stdfilters.ftf contains four filters:

  • DeBayer: Converts raw image data to RGB
  • DeNoise: Denoising by image integration
  • ROI: Region of Interest
  • Rotate Flip: Rotation and Flipping
  • Bayer to Y800: Converts BY8 to Y800

Module Files

The module file stdfilters.ftf is located in the classlib\release directory and the ICImagingControl.ocx's directory (common files directory). The debug compiled version of the module is named stdfiltersd.ftf and is located in the classlib\debug directory of the IC Imaging Control installation path.

Bayer to Y800 Filter

The Bayer to Y800 filter reinterprets the raw color data in BY8 images as Y800. Using this filter, it is possible to display the raw color data. The BY8 image data is de-bayered automatically before the video stream is rendered on screen.

DeBayer Filter

The DeBayer filter is used to convert raw image data into an RGB image. In a raw color image, every pixel represents a value for one basic color, instead of three as is the case for an RGB image. In order to get a real color image, the two missing colors have to be interpolated. This is exactly what this filter does.

DeNoise Filter

The DeNoise filter reduces noise in the frames by averaging a number of frames.

ROI Filter

The ROI filter cuts a region of interest out of the incoming frames. It creates a new output video format.

Rotate Flip Filter

The Rotate Flip filter allows image data to be flipped and rotated in steps of 90 degrees.

<< IC Imaging Control Class Library User's Guide


Bayer to Y800 Filter

The Bayer to Y800 filter reinterprets the raw color data in BY8 images as Y800. Using this filter, it is possible to display the raw color data. The BY8 image data is de-bayered automatically before the video stream is rendered on screen.

Using the Bayer to Y800 Filter

The Bayer to Y800 filter is loaded by an application using following code:

#ifdef _DEBUG
        smart_com<IFrameFilter> pFilter = FilterLoader::createFilter( "Bayer to Y800",   // Filter name.
                                                                      "stdfiltersd.ftf" ); // Module file.
#else
        smart_com<IFrameFilter> pFilter = FilterLoader::createFilter( "Bayer to Y800",   // Filter name.
                                                                      "stdfilters.ftf" ); // Module file.
#endif

Parameters

The Bayer to Y800 filter does not have any parameters.

Property Dialog

The Bayer to Y800 filter does not have a property dialog.

<< IC Imaging Control Standard Filters


DeBayer Filter

The DeBayer filter is used to convert raw image data into an RGB image. In a raw color image, every pixel represents a value for one basic color, instead of three as is the case for an RGB image. In order to get a real color image, the two missing colors have to be interpolated. This is exactly what this filter does.

Using the DeBayer Filter

The DeBayer filter is loaded by an application using the following code:

    // Load the DeBayer filter from the stdfilters.ftf module.
#ifdef _DEBUG
    smart_com<IFrameFilter> pFilter =  FilterLoader::createFilter( "DeBayer",   // Filter name.
                                                                   "stdfiltersd.ftf" ); // Module file.
#else
    smart_com<IFrameFilter> pFilter =  FilterLoader::createFilter( "DeBayer",   // Filter name.
                                                                   "stdfilters.ftf" ); // Module file.
#endif

Parameters

There are two parameters that control the de-bayering process:

Start Pattern
The parameter Start Pattern defines how the Bayer Mosaic pattern in the raw image data is to be interpreted.
Available start patterns are:
  • BG: The raw image data starts with a blue/green line. Set Start Pattern to 0.
  • GB: The raw image data starts with a green/blue line. Set Start Pattern to 1.
  • GR: The raw image data starts with a green/red line. Set Start Pattern to 2.
  • RG: The raw image data starts with a red/green line. Set Start Pattern to 3.
Mode
The Mode parameter selects the algorithm used to de-bayer the raw image data.
Available algorithms are:
  • Nearest Color: Simple and fast algorithm, but rather bad output image quality. Set Mode to 0.
  • Bilinear: Fast algorithm producing good output image quality. Set Mode to 1.
  • Edge Sensing: This algorithm has the best output image quality but is rather slow. Set Mode to 2.

If the algorithm should be set programmatically, then following code can be used:

// Retrieve the current mode.
long mode;
pFilter->getParameter( "Mode", mode );

// Set a new mode.
mode = 1;
pFilter->setParameter( "Mode", mode );

Property Dialog

All parameters can be accessed using the built-in property dialog. The property dialog of the DeBayer filter is as follows:

<< IC Imaging Control Standard Filters


DeNoise Filter

The DeNoise filter reduces noise in the frames by averaging a number of frames.

Using the DeNoise Filter

The DeNoise filter is loaded by an application using the following code:

        // Load the DeNoise filter from the stdfilters.ftf module.
#ifdef _DEBUG
    smart_com<IFrameFilter> pFilter = FilterLoader::createFilter( "DeNoise",   // Filter name.
                                                                  "stdfiltersd.ftf" ); // Module file.
#else
    smart_com<IFrameFilter> pFilter = FilterLoader::createFilter( "DeNoise",   // Filter name.
                                                                  "stdfilters.ftf" ); // Module file.
#endif

Parameters

The only parameter of the DeNoise filter is the DeNoise Level:

DeNoise Level
The parameter DeNoise Level determines the number of frames to be averaged.
Note: The actual number of frames that are averaged is 2^n, so when setting DeNoise Level to 2, 4 frames are averaged.
This parameter can only be set while the live video stream is stopped.

Property Dialog

The number of frames to be averaged can be adjusted in the filter's property dialog:

Programmatically Access the Parameter

The following source code can be used, if the parameter should be set by an application:

long level = 0;
// Retrieve the current denoise level.
pFilter->getParameter( "DeNoise Level", level );

// Set a new denoise level.
level = 3;
if( m_Grabber.isLive() == false )
{
    // A new denoise level can only be set, while the live video is stopped.
    // Otherwise, an error is returned by setParameter().
    pFilter->setParameter( "DeNoise Level", level );
}

<< IC Imaging Control Standard Filters


ROI Filter

The ROI filter cuts a region of interest out of the incoming frames. It creates a new output video format.

Using the ROI Filter

The ROI filter is loaded by an application using following code:

        // Load the ROI filter from the stdfilters.ftf module.
#ifdef _DEBUG
    smart_com<IFrameFilter> pFilter = FilterLoader::createFilter( "ROI",   // Filter name.
                                                                  "stdfiltersd.ftf" ); // Module file.
#else
    smart_com<IFrameFilter> pFilter = FilterLoader::createFilter( "ROI",   // Filter name.
                                                                  "stdfilters.ftf" ); // Module file.
#endif

Parameters

The part of the image that is copied to the destination frame is determined by four filter parameters:

Left
This value specifies the left column on the source frame at which the region of interest (ROI) starts. This value is used to move the region of interest horizontally to the source frame. It can be changed regardless of whether the live video is running or not.
Top
This value specifies the top row on the source frame at which the region of interest starts. This value is used to move the region of interest vertically to the source frame. It can be changed regardless of whether the live video is running or not.
Width
This value specifies the width of the region of interest. It can only be set while the live video is stopped. Otherwise, the resulting video format would be changed.
The width will be aligned to eight pixels in the filter automatically.
Height
This value specifies the height of the region of interest. It can only be set while the live video is stopped. Otherwise, the resulting video format would be changed.

Property Dialog

The dimensions and the start positions of the region of interest can be specified in the ROI filter's property dialog:

Programmatically access the Parameter

The following source code can be used, if the parameter should be set by an application:

long lLeft = 0;
long lTop = 0;
long lHeight = 0;
long lWidth = 0;

// Retrieve the current ROI rectangle:
pFilter->getParameter( "Left", lLeft );
pFilter->getParameter( "Top", lTop );
pFilter->getParameter( "Height",lHeight  );
pFilter->getParameter( "Width", lWidth );

// Set a new ROI.
lLeft = 100;
lTop = 50;
// The position of the ROI can be set, regardless of whether the live video is running
// because the size of the resulting video format is not changed.
pFilter->setParameter( "Left", lLeft );
pFilter->setParameter( "Top", lTop );

if( m_Grabber.isLive() == false )
{
    // A new ROI width and height can only be set while the live video is stopped. Otherwise,
    // an error is returned by setParameter().
    lHeight = 120;
    lWidth = 180;
    pFilter->setParameter( "Height",lHeight  );
    pFilter->setParameter( "Width", lWidth );
}

<< IC Imaging Control Standard Filters


Rotate Flip Filter

The Rotate Flip filter allows image data to be flipped and rotated in steps of 90 degrees.

Using the Rotate Flip Filter

The Rotate Flip filter is loaded by an application using the following code:

    // Load the Rotate Flip filter from the stdfilters.ftf module.
#ifdef _DEBUG
    smart_com<IFrameFilter> pFilter = FilterLoader::createFilter( "Rotate Flip",   // Filter name.
                                                                  "stdfiltersd.ftf" ); // Module file.
#else
    smart_com<IFrameFilter> pFilter = FilterLoader::createFilter( "Rotate Flip",   // Filter name.
                                                                  "stdfilters.ftf" ); // Module file.
#endif

Parameters

The part of the image that is copied to the destination frame is determined by four filter parameters:

Rotation Angle
This parameter sets the rotation angle.
Available angles are:
  • 0°
  • 90°
  • 180°
  • 270°
Please note that this parameter can only be changed in steps of 180° when live mode is running. Otherwise, the changes would alter the output video format.
Flip V
This parameter determines whether the image should be flipped vertically. As it is a boolean parameter, valid values are true and false. The setting of the flip parameters does not cause a video format change. Thus, they can be set regardless of whether the live video is running or not.
Flip H
This parameter determines whether the image should be flipped horizontally. As it is a boolean parameter, valid values are true and false. The setting of the flip parameters does not cause a video format change. Thus, they can be set regardless of whether the live video is running or not.

Property Dialog

The rotation angle and flipping modes can be specified in the filter's property dialog:

Programmatically access the Parameters

If the parameters should be set by an application, the following source code can be used:

long lAngle = 0;
long lNewAngle = 0;
bool bFlipVertical = false;
bool bFlipHorizontal = false;

//Retrieve the current parameter settings.
pFilter->getParameter( "Rotation Angle", lAngle  );
pFilter->getParameter( "Flip V", bFlipVertical );
pFilter->getParameter( "Flip H", bFlipHorizontal );

//Change the parameters.
lNewAngle = 90; // Only the values 0, 90, 180 270 are allowed.
// If the rotation value is 90 or 270, then the resulting video format
// is changed. Thus, the new value can only be set while the live video is
// stopped. Otherwise, an error is returned by setParameter().
if( abs(lAngle - lNewAngle) == 90 || abs(lAngle - lNewAngle ) == 270 )
{
    if( m_Grabber.isLive() == false )
    {
        pFilter->setParameter( "Rotation Angle", lAngle  );
    }
}
else
{
    pFilter->setParameter( "Rotation Angle", lAngle  );
}

// The flip parameters do not cause a video format change, so they can be
// set regardless of whether the live video is running.
bFlipVertical = true;
bFlipHorizontal = true;
pFilter->setParameter( "Flip V", bFlipVertical );
pFilter->setParameter( "Flip H", bFlipHorizontal );

<< IC Imaging Control Standard Filters


First Steps VC6

Creating the Project

Please run one of the demo programs from the "start menu", in order to verify that you are able to open a video capture device and display a live image.

Start a new project by selecting "New" in the "File" menu. In the dialog that then appears, select "MFC AppWizard(exe)". Enter "FirstStep" into the "Project name" field and choose the location at which the project directory should be created. The paths to the required include and library files depend on the location of this directory. The examples shown here assume the directory is created in the "IC Imaging Control" top level directory, which is "Program Files\The Imaging Source Europe GmbH\IC Imaging Control 3.0" by default. Press "OK" to confirm the dialog.

Now the AppWizard asks you how to set up the project. In the first dialog, select "Single document", "Document/View architecture support" and the language that should be supported by your application. Now click on "Next".

In the second step, choose "None" for the database to include and click on "Next".

In the third step, select "None" for the document support to include. The check boxes for "other support to include" should be deselected. Now click on "Next".

In the fourth step, deselect all check boxes and click on "Next".

In the fifth step, select "MFC Standard" for the style of the project. Select "Yes" to create source file comments. Select "As a shared DLL" at the question on how the MFC library should be used. Finally click on "Next".

In the last step, the AppWizard shows you which classes will be created. Click on "Finish" to complete the creation of the project.

Now a dialog box summarizes the created project. Confirm this dialog with a click on "Finish".


First Steps VC.NET

Creating the Project

Please run one of the demo programs from the "start menu", in order to verify that you are able to open a video capture device and display a live image.

Start a new project by selecting "New" -> "Project..." in the "File" menu. In the dialog that appears, choose "Visual C++ Projects" as the project type and "MFC Application" as the template. Enter "FirstStep" in the "Name" text field and choose the location at which the project directory should be created. The paths to the required include and library files depend on the location of this directory. The examples shown here assume the directory is created in the "IC Imaging Control" toplevel directory, which is My Documents\IC Imaging Control 3.1 by default. Please keep in mind, "My Documents" may is localized to the language of your operating system. Press "OK" to confirm the dialog.

Now you can change the project settings. Click on the "Application Type" tab and select "Single document" as "Application type". Make sure the "Document/View architecture support" check box is checked and select the language you want.

Select the "Compound Document Support" tab and make sure that "None" is selected.

The "Document Template Strings" tab can be left as it is.

Now make sure that under the "Database Support" tab "None" is checked.

Deselect "Initial status bar" under the "User Interface Features" tab and select "None" as "Toolbars".

Deselect all under the "Advanced Features" tab.

Finally, the "Generated Classes" tab shows you all the classes that will be generated automatically by the Application Wizard.

Now click on the "Finish" button and the project will be created.

Next Step: Project Properties


First Steps VC6

This chapter shows you how to set up a Visual C++ 6.0 project, which uses the library.

Steps

  • Creating the Project
  • Project Settings
  • Including the class library header files
  • Library Initialization
  • Instanciating the Grabber
  • Select a Video Capture Device and display a Live Image


First Steps VC6

Select a Video Capture Device and display a Live Image

Select "Class Wizard..." in the "View" menu to open the class wizard. Select "CFirstStepView" in the "Class name" field. Then select "OnInitialUpdate" in the "Messages" list and press the "Add function" button.

In order to select a video capture device, use the built-in device selection dialog. This is done in the "OnInitialUpdate" method of the CFirstStepView class, generated by the class wizard. Change its code as follows:

void CFirstStepView::OnInitialUpdate()
{
    CView::OnInitialUpdate();

    // TODO: Add your specialized code here and/or call the base class

    // Get the grabber from the document class.
    DShowLib::Grabber* pGrabber = GetDocument()->m_pGrabber;

    // Show the device page.
    pGrabber->showDevicePage();

    // Check if there is a valid device.
    if( pGrabber->isDevValid() )
    {
        // Set the window that should display the live video.
        pGrabber->setHWND( m_hWnd );
        // Start the live video.
        pGrabber->startLive();
    }
    else
    {
        AfxMessageBox( "No device was selected." );
    }
}

The OnCloseDocument method closes the device when the program terminates. To add the OnCloseDocument method, open the class wizard and select "CFirstStepDoc" in the "Class name" field. Select "OnCloseDocument" in the "Messages" list and press the "Add function" button. Insert the following code into the OnCloseDocument method:

void CFirstStepDoc::OnCloseDocument()
{
    // TODO: Add your specialized code here and/or call the base class

    // Stop live mode.
    m_pGrabber->stopLive();

    // this call will also succeed if no device is open
    m_pGrabber->closeDev();

    CDocument::OnCloseDocument();
}

Now compile and run the project. After a device has been selected in the device selection dialog, a live image will be displayed.


First Steps VC.NET

Select a Video Capture Device and display a Live Image

Open the class view in the project explorer and right click on the "CFirstStepView" class. Select "Properties" from the context menu and click on the "Overrides" button. Now add the OnInitialUpdate method.

To select a video capture device, use the built-in device selection dialog. This is done in the OnInitialUpdate method of the CFirstStepView class. Change its code as follows:

void CFirstStepView::OnInitialUpdate()
{
    CView::OnInitialUpdate();

    // TODO: Add your specialized code here and/or call the base class

    // Get the grabber from the document class.
    DShowLib::Grabber* pGrabber = GetDocument()->m_pGrabber;

    // Show the device page.
    pGrabber->showDevicePage();

    // Check if there is a valid device.
    if( pGrabber->isDevValid() )
    {
        // Set the window that should display the live video.
        pGrabber->setHWND( m_hWnd );
        // Start the live video.
        pGrabber->startLive();
    }
    else
    {
        AfxMessageBox( "No device was selected." );
    }
}

Before the application terminates, the live video should be stopped and the device should be closed. To do so, add the OnCloseDocument method. Open the class view in the project explorer and right click on the "CFirstStepDoc" class. Select "Properties" from the context menu and click on the "Overrides" button. Now add the OnCloseDocument method.

Insert the following code into the OnCloseDocument method:

void CFirstStepDoc::OnCloseDocument()
{
    // TODO: Add your specialized code here and/or call the base class

    // Stop live mode.
    m_pGrabber->stopLive();

    // this call will also succeed if no device is open
    m_pGrabber->closeDev();

    CDocument::OnCloseDocument();
}

Now compile and run the project. After a device has been selected in the device selection dialog, a live image will be displayed.


First Steps VC6

Including the class library header files

The classes and methods of the library are defined in header files, which have to be included in the code. The file "tisudshl.h" includes all the files required by the library. To include this file in your source code, open the file "StdAfx.h" (which was created by the AppWizard) and insert the following lines:

#include "tisudshl.h"
#include <algorithm>

above the last

#endif // !defined(AFX_STDAFX_H__86FED897_D63B_49B1_B368_966EC966FE03__INCLUDED_)

statement.


First Steps VC.NET

Including the class library header files

The classes and methods of the library are defined in header files, which have to be included in the code. The file tisudshl.h will include all the files required by the library. To include this file in your source code, open the file StdAfx.h (which was created by the AppWizard) and insert the following lines at the end:

#include "tisudshl.h"
#include <algorithm>

Next step: Library Initialization


First Steps VC6

Library Initialization

The library has to be initialized, before any action on the Grabber is permitted.

To initialize the library, open the file "FirstStep.cpp", created by the AppWizard, and go to the CFirstStepApp::InitInstance() method.

if( ! DShowLib::InitLibrary() )
{
    return FALSE;
}

The InitLibrary function returns true, if the library could be initialized properly.

The function returns false if:

  • your system does not meet the minimum system requirements.


First Steps VC.NET

Library Initialization

The library has to be initialized, before any action on the Grabber is permitted.

To initialize the library, open the file "FirstStep.cpp", created by the AppWizard, and go to the CFirstStepApp::InitInstance() method.

if( ! DShowLib::InitLibrary() )
{
    return FALSE;
}

atexit( _DShowLib::ExitLibrary );

The InitLibrary function returns true, if the library could be initialized properly.

The function returns false if:

  • your system does not meet the minimum system requirements.

Next step: Instanciating the Grabber


First Steps VC6

Instanciating the Grabber

Open the file "FirstStepDoc.h", which was created by the AppWizard and add a public member to the class CFirstStepDoc by inserting the line:

DShowLib::Grabber* m_pGrabber;

just below the lines:

// Attributes
public:

Open the file "FirstStepDoc.cpp", which was created by the AppWizard. Create a new Grabber in the constructor of the CFirstStepDoc class. The constructor should then look as follows:

CFirstStepDoc::CFirstStepDoc()
{
    // TODO: add one-time construction code here
    m_pGrabber = new DShowLib::Grabber();
    ASSERT( m_pGrabber );
}

The Grabber object has to be deleted, when the program terminates. To achieve this, change the destructor of the CFirstAppDoc class to the following:

CFirstStepDoc::~CFirstStepDoc()
{
    delete m_pGrabber;
}

In order to verify the changes you have made so far, please build the project by selecting "Rebuild All" from the "Build" menu.


First Steps VC.NET

Instanciating the Grabber

Open the file "FirstStepDoc.h", which was created by the AppWizard and add a public member to the class CFirstStepDoc by inserting the line:

DShowLib::Grabber* m_pGrabber;

just below the lines:

// Attributes
public:

Open the file "FirstStepDoc.cpp", which was created by the AppWizard. Create a new Grabber in the constructor of the CFirstStepDoc class. The constructor should then look like the following:

CFirstStepDoc::CFirstStepDoc()
{
    // TODO: add one-time construction code here
    m_pGrabber = new DShowLib::Grabber();
    ASSERT( m_pGrabber );
}

The Grabber object has to be deleted, when the program terminates. To achieve this, change the destructor of the CFirstAppDoc class to the following:

CFirstStepDoc::~CFirstStepDoc()
{
    delete m_pGrabber;
}

In order to verify the changes you have made so far, please build the project by selecting "Rebuild Solution" from the "Build" menu.

Next step: Select a Video Capture Device and display a Live Image


First Steps VC6

Project Settings

Open the "Project Settings" dialog by selecting "Settings..." in the "Project" menu.

In the settings dialog, click on the "General" tab and change the path for the executable in the "Output files:" text box from "Debug" to "..\Classlib\Debug" for debug configurations. For release configurations, change the path from "Release" to "..\Classlib\Release".

In the settings dialog, click on the "C/C++" tab and choose "Code Generation" in the "Category" list box:

Make sure a "Multithreaded DLL" is selected in the "Use run-time library" list box. For debug configurations, the "Debug Multithreaded DLL" and for release configurations, the "Multithreaded DLL" has to be selected.

Select "Preprocessor" in the "Category" list box. Enter the path of the directory in which the include files for the class library reside, using the "Additional include directories" text box. If the project was created in the "IC Imaging Control" toplevel directory, the include path is "../Classlib/include". If the include files for the DirectX SDK are not in the standard include path, the directory for these files has to be added here too. Different paths are separated by a comma.

Select the "Link" tab and choose "Input" in the "Category" list box. Enter "TIS_UDSHL07_vc6d.lib strmiids.lib" in the "Object/library modules" text box. The 2 module names are separated by a space character. Enter the path to the class libraries in the "Additional library path" text box. If the project was created in the "IC Imaging Control" toplevel directory, the path is "../Classlib/debug" for debug configurations and "../Classlib/release" for release configurations. Please note that "TIS_UDSHL07_vc6.lib" must be used for release configurations instead of "TIS_UDSHL07_vc6d.lib".

Now click on "OK" to confirm all changes.


First Steps VC.NET

Project Properties

Open the "Project Properties" dialog by selecting "Properties" in the "Project" menu.

In the properties dialog, click on the "General" tab and change the path for the executable in the "Output Directory" text box from "Debug" to C:\Documents and Settings\username\My Documents\IC Imaging Control 3.1\classlib\$(PlatformName)\debug for debug configurations. For release configurations change the path from "Release" to C:\Documents and Settings\username\My Documents\IC Imaging Control 3.1\classlib\$(PlatformName)\release. Please exchange "username" with your user name. The macro $(PlatformName) will be substituted with "win32" or "X64" while the project is built.

Click on the "C/C++" tab and choose "Code Generation". Make sure a "Multi-threaded DLL" is selected in the "Runtime Library" text box. For debug configurations, the "Multi-threaded Debug DLL" and for release configurations, the "Multi-threaded DLL" has to be selected.

Now select "General" in the "C/C++" tab. Enter the path of the directory in which the include files for the class library reside, in the "Additional Include Directories" text box. If the project was created in the "IC Imaging Control" toplevel directory the include path is C:\Documents and Settings\username\My Documents\IC Imaging Control 3.1\classlib\include. Please exchange "username" with your user name

Select "General" in the "Linker" tab and enter the path to the class library in the "Additional Library Directories" field. If the project was created in the IC Imaging Control toplevel directory, the path is "..\ClassLib\Debug" for debug configurations and "..\ClassLib\Release" for release configurations.

Next Step: Including the class library header files


Sample Programs

These programs demonstrate several aspects of the "IC Imaging Control" class library.

By default, IC Imaging Control is installed into the Program Files\The Imaging Source Europe GmbH\IC Imaging Control 3.0 directory. This is IC Imaging Control's top level directory and is referred to as %TOPLEVEL%.

Samples

  • Acquire Video Format Information
  • Acquire Property Information
  • Using a Callback Function
  • Using Memory Buffer Collections
  • Making Device Settings
  • Writing Image Streams to an AVI file
  • Properties of a Codec
  • Scroll and Zoom
  • Creating an Overlay
  • Accessing an Image Buffer
  • Basic Use of VCD Properties
  • Using the VCD Simple Property Class
  • List VCD Properties
  • Filter Inspector
  • Writing a Frame Filter: Binarization
  • Creating a Filter Module


Using the VCD Simple Property Class

Up to the version 1.41 of IC Imaging Control, the properties of a device could be accessed using the properties %%Auto, %%AutoAvailable, %%Available, %%Default and %%Range. Since version 2.0, these properties are depreciated. The new VCD properties allow more detailed and generic access to the device's properties, but they require a little more coding. If you are happy with the old properties, a new helper class is introduced in version 2.0 that provides access methods to the old style VCD properties. This chapter shows you how to use this helper class.

Setting up the Project

The source code for this sample program can be found in the %TOPLEVEL%\samples\VC6\VCD Simple Property or %TOPLEVEL%\samples\VC71\VCD Simple Property sample source directories. It also uses the files "SimplePropertyAccess.h" and "SimplePropertyAccess.cpp" that implement the helper class. They are located in the %TOPLEVEL%\samples\VC6\common or %TOPLEVEL%\samples\VC71\common directory.

Create a project as described in the FirstSteps chapter, but choose "Dialog based" application type instead of "Single document".

As mentioned above, the files "SimplePropertyAccess.h" and "SimplePropertyAccess.cpp" have to be added to the project in order to be able to use the "Simple Property Class" CSimplePropertyAccess. In VC6, right click on the project in the project explorer and select "New Folder..." from the context menu. Name the folder SimplePropertyAccess and click the "OK" button. The "File extensions" field can be left out. Now right click on the folder that has just been created in the project explorer and select "Add Files to Folder...". Browse to the %TOPLEVEL%\samples\VC6\common directory, select the files "SimplePropertyAccess.h" and "SimplePropertyAccess.cpp" and click the "OK" button. The files are now part of the project and the "Simple Property Class" is ready for use.

In VC71, right click on the project in the solution explorer and select "Add" from the context menu and then "New Folder". Name the folder SimplePropertyAccess. Right click on the folder that has just been created in the solution explorer and select "Add" and then "Add Existing Item...". Browse to the %TOPLEVEL%\samples\VC71\common directory, select the files "SimplePropertyAccess.h" and "SimplePropertyAccess.cpp" and click the "Open" button. The files are now part of the project and the "Simple Property Class" is ready for use.

Accessing a Property

First of all, we are going to add some controls to the dialog. They will allow us to manipulate a device property. Add a slider, a label and a check box. Give the slider the ID IDC_WB_SLIDER, the label the ID IDC_WB_VALUE and the check box IDC_WB_CHECK. Now add a static text field to the dialog. Give it the ID IDC_DISPLAY. It will be used to display the live video. Use the class wizard to add member variables for all these controls. Name them m_staticDisplay, m_sldWhiteBalance, m_lblValue and m_chkAuto. These controls will be used to manipulate the "WhiteBalance" property of a device.

We need an instance of the helper class in order to use it. Therefore, include the helper class and add an instance to the CCodeContainerDlg class:

#include "../Common/SimplePropertyAccess.h"

protected:
    HICON m_hIcon;

    DShowLib::Grabber m_Grabber;

    smart_com<DShowLib::IFrameFilter>    m_pRotFlipFilter;
    smart_com<DShowLib::IFrameFilter>    m_pROIFilter;

    // An instance of the helper class
    CSimplePropertyAccess m_VCDProp;

As you can see above, the grabber object is also declared here.

The helper class and the controls are initialized in the OnInitDialog method. This is accomplished by the following code:

BOOL CCodeContainerDlg::OnInitDialog()
{
    CDialog::OnInitDialog();

    // Set the icon for this dialog. The framework does this automatically
    // when the application's main window is not a dialog.
    SetIcon(m_hIcon, TRUE);            // Set big icon
    SetIcon(m_hIcon, FALSE);        // Set small icon

    // Initialize the VCDProp object to access the properties of the ICImagingControl
    // object.
    m_VCDProp.init( m_Grabber.getAvailableVCDProperties() );

    // Initialize the auto check boxes and deactivate automation.
    if( !m_VCDProp.isAutoAvailable( VCDID_WhiteBalance ) )
    {
        m_chkAuto.EnableWindow( FALSE );
    }
    else
    {
        m_VCDProp.setAuto( VCDID_WhiteBalance, false );
    }

    // Initialize the white balance slider.
    if( !m_VCDProp.isAvailable( VCDID_WhiteBalance ) )
    {
        m_sldWhiteBalance.EnableWindow(FALSE);
    }
    else
    {
        m_sldWhiteBalance.EnableWindow();
        m_sldWhiteBalance.SetRangeMin( m_VCDProp.getRangeMin( VCDID_WhiteBalance ) );
        m_sldWhiteBalance.SetRangeMax( m_VCDProp.getRangeMax( VCDID_WhiteBalance ) );
        int val = m_VCDProp.getValue( VCDID_WhiteBalance );
        m_sldWhiteBalance.SetPos( val );

        CString s;
        s.Format( "%d", val );
        m_lblValue.SetWindowText( s );
    }

    // Set output window for live mode.
    m_Grabber.setHWND( m_staticDisplay.m_hWnd );

    // Start live mode.
    m_Grabber.startLive();

    return TRUE;  // return TRUE, unless you set the focus to a control.
}

First, the helper class is initialized, then the controls. After that the live video is started.

To add functionality to the controls, use the class wizard to add a click event for the check box and a handler for the WM_HSCROLL message. The click event of the check box toggles the automation on/off. It is implemented as follows:

void CCodeContainerDlg::OnWbCheck()
{
    if( m_chkAuto.GetCheck() )
    {
        m_VCDProp.setAuto( VCDID_WhiteBalance, true );
        m_sldWhiteBalance.EnableWindow( FALSE );
    }
    else
    {
        m_VCDProp.setAuto( VCDID_WhiteBalance, false );
        m_sldWhiteBalance.EnableWindow( TRUE );
    }
}

The event handler for the WM_HSCROLL message updates the "WhiteBalance" property. It is implemented as follows:

void CCodeContainerDlg::OnHScroll(UINT nSBCode, UINT nPos, CScrollBar* pScrollBar)
{
    int pos = ((CSliderCtrl*) pScrollBar)->GetPos();
    CString posText;
    posText.Format( "%d", pos );

    m_VCDProp.setValue( VCDID_WhiteBalance, pos );
    m_lblValue.SetWindowText( posText );

    CDialog::OnHScroll(nSBCode, nPos, pScrollBar);
}

Before any properties can be manipulated, a valid video capture device must be selected. This is done via the built-in device selection dialog, which is displayed before the main dialog appears. To select a valid video capture device, change the code in the InitInstance of the CodeContainerApp class to the following:

CCodeContainerDlg dlg;

if( !dlg.selectDevice() )
{
    AfxMessageBox( "No device was selected." );
    return FALSE;
}

m_pMainWnd = &dlg;
dlg.DoModal();

The selectDevice method of the CodeContainerDlg class calls the built-in dialog and is implemented as follows:

bool CCodeContainerDlg::selectDevice()
{
    m_Grabber.showDevicePage( m_hWnd );

    return m_Grabber.isDevValid();
}

Now run the application and use the slider to manipulate the "WhiteBalance" property or use the check box to toggle the automation feature of the property.

Accessing advanced Properties

There are some properties that allow more detailed access than the one described above. In case of "WhiteBalance", it is possible to specify a value for red and blue and to perform an automatic adjustment for a limited time - this is called "one push". These advanced properties can be accessed using the following IDs: VCDElement_WhiteBalanceBlue and VCDElement_WhiteBalanceRed. The "One Push" operation is triggered by calling the push method of the helper class with VCDID_WhiteBalance as a parameter.

The following sample shows you how to access "WhiteBalanceBlue" and "WhiteBalanceRed" property. It will also access the "Brightness" property to show the difference between the standard property and the advanced way.

Set up a project as described in the FirstSteps chapter, but choose "Dialog based" application type instead of "Single document". Now, add 3 sliders to the dialog. Give them the IDs IDC_BRIGHTNESS_SLIDER, IDC_WBBLUE_SLIDER and IDC_WBRED_SLIDER. Corresponding to the sliders add 3 static text fields and give them the IDs IDC_BRIGHTNESS_STATIC, IDC_WBBLUE_STATIC and IDC_WBRED_STATIC. They will display the current value of the according property. Then, add 2 check boxes with the IDs IDC_BRIGHTNESS_AUTO and IDC_WB_AUTO and a button with the ID IDC_WB_ONEPUSH. To display a live video, add a static text control with the ID IDC_DISPLAY.

Before the main dialog is called, the device selection dialog should be displayed. Therefore, add a call to the function selectDevice to the InitInstance method of the CVCDSimplePropertyApp class:

CVCDSimplePropertyDlg dlg;

if( !dlg.selectDevice() )
{
    AfxMessageBox( "No device was selected." );
    return FALSE;
}

m_pMainWnd = &dlg;
dlg.DoModal();

Now edit the file "VCD Simple PropertyDlg.h" and include the header file "SimplePropertyAccess.h" of the helper class:

#include "../Common/SimplePropertyAccess.h"

Declare a public function selectDevice and some protected variables:

public:
    bool selectDevice();

protected:
    HICON m_hIcon;

    DShowLib::Grabber m_Grabber;

    // An instance of the helper class
    CSimplePropertyAccess m_VCDProp;

    // The controls
    CSliderCtrl* m_pBrightnessSlider;
    CStatic* m_pBrightnessStatic;
    CButton* m_pBrightnessCheck;

    CSliderCtrl* m_pWbBlueSlider;
    CStatic* m_pWbBlueStatic;
    CSliderCtrl* m_pWbRedSlider;
    CStatic* m_pWbRedStatic;
    CButton* m_pWbCheck;
    CButton* m_pWbOnePush;

The helper class and the controls are initialized in the OnInitDialog method. Edit the file "VCD Simple PropertyDlg.cpp" and insert the following code:

BOOL CVCDSimplePropertyDlg::OnInitDialog()
{
    CDialog::OnInitDialog();

    // Set the icon for this dialog.  The framework does this automatically
    //  when the application's main window is not a dialog
    SetIcon(m_hIcon, TRUE);            // Set big icon
    SetIcon(m_hIcon, FALSE);        // Set small icon

    // Get references to the controls
    m_pBrightnessSlider = (CSliderCtrl*)GetDlgItem( IDC_BRIGHTNESS_SLIDER );
    m_pBrightnessStatic = (CStatic*)GetDlgItem( IDC_BRIGHTNESS_STATIC );
    m_pBrightnessCheck = (CButton*)GetDlgItem( IDC_BRIGHTNESS_AUTO );

    m_pWbBlueSlider = (CSliderCtrl*)GetDlgItem( IDC_WBBLUE_SLIDER );
    m_pWbBlueStatic = (CStatic*)GetDlgItem( IDC_WBBLUE_STATIC );
    m_pWbRedSlider = (CSliderCtrl*)GetDlgItem( IDC_WBRED_SLIDER );
    m_pWbRedStatic = (CStatic*)GetDlgItem( IDC_WBRED_STATIC );
    m_pWbCheck = (CButton*)GetDlgItem( IDC_WB_AUTO );
    m_pWbOnePush = (CButton*)GetDlgItem( IDC_WB_ONEPUSH );

    // Initialize the VCDProp object to access the properties of our ICImagingControl
    // object
    m_VCDProp.init( m_Grabber.getAvailableVCDProperties() );

    // Initialize the auto checkboxes and deactivate automation
    if( !m_VCDProp.isAutoAvailable( VCDID_Brightness ) )
    {
        m_pBrightnessCheck->EnableWindow( FALSE );
    }
    else
    {
        m_VCDProp.setAuto( VCDID_Brightness, false );
    }

    if( !m_VCDProp.isAutoAvailable( VCDID_WhiteBalance) )
    {
        m_pWbCheck->EnableWindow( FALSE );
    }
    else
    {
        m_VCDProp.setAuto( VCDID_WhiteBalance, false );
    }

    // Initialize the one push button
    if( !m_VCDProp.isOnePushAvailable( VCDID_WhiteBalance ) )
    {
        m_pWbOnePush->EnableWindow( FALSE );
    }

    // Initialize the brightness slider
    if( !m_VCDProp.isAvailable( VCDID_Brightness ) )
    {
        m_pBrightnessSlider->EnableWindow(FALSE);
    }
    else
    {
        m_pBrightnessSlider->EnableWindow();
        m_pBrightnessSlider->SetRangeMin( m_VCDProp.getRangeMin( VCDID_Brightness ) );
        m_pBrightnessSlider->SetRangeMax( m_VCDProp.getRangeMax( VCDID_Brightness ) );
        int val = m_VCDProp.getValue( VCDID_Brightness );
        m_pBrightnessSlider->SetPos( val );

        CString s;
        s.Format( "%d", val );
        m_pBrightnessStatic->SetWindowText( s );
    }

    // Initialize the slider for whitebalance blue
    if( !m_VCDProp.isAvailable( VCDElement_WhiteBalanceBlue ) )
    {
        m_pWbBlueSlider->EnableWindow(FALSE);
    }
    else
    {
        m_pWbBlueSlider->EnableWindow();
        m_pWbBlueSlider->SetRangeMin( m_VCDProp.getRangeMin( VCDElement_WhiteBalanceBlue ) );
        m_pWbBlueSlider->SetRangeMax( m_VCDProp.getRangeMax( VCDElement_WhiteBalanceBlue ) );
        int val = m_VCDProp.getValue( VCDElement_WhiteBalanceBlue );
        m_pWbBlueSlider->SetPos( val );

        CString s;
        s.Format( "%d", val );
        m_pWbBlueStatic->SetWindowText( s );
    }

    // Initialize the slider for whitebalance red
    if( !m_VCDProp.isAvailable( VCDElement_WhiteBalanceRed ) )
    {
        m_pWbRedSlider->EnableWindow(FALSE);
    }
    else
    {
        m_pWbRedSlider->EnableWindow();
        m_pWbRedSlider->SetRangeMin( m_VCDProp.getRangeMin( VCDElement_WhiteBalanceRed ) );
        m_pWbRedSlider->SetRangeMax( m_VCDProp.getRangeMax( VCDElement_WhiteBalanceRed ) );
        int val = m_VCDProp.getValue( VCDElement_WhiteBalanceRed );
        m_pWbRedSlider->SetPos( val );

        CString s;
        s.Format( "%d", val );
        m_pWbRedStatic->SetWindowText( s );
    }

    // Set output window for live mode
    m_Grabber.setHWND( GetDlgItem( IDC_DISPLAY )->GetSafeHwnd() );
    // Start live mode
    m_Grabber.startLive();

    return TRUE;  // return TRUE  unless you set the focus to a control
}

As you can see above, the code to initialize the sliders for "WhiteBalanceBlue" and "WhiteBalanceRed" is the same as the code to initialize the slider for "Brightness". The only difference is that you must use the element ID "VCDElement_WhiteBalanceBlue" or "VCDElement_WhiteBalanceRed" instead of the item ID "VCDID_Brightness".

The selectDevice method that is called at program start calls the built-in device selection dialog. It is implemented as follows:

bool CVCDSimplePropertyDlg::selectDevice()
{
    m_Grabber.showDevicePage( m_hWnd );

    return m_Grabber.isDevValid();
}

Finally, all we need are the event handlers of the controls. We start with the event handlers of the check boxes. Use the class wizard to add a click event for every check box and insert the following code:

void CVCDSimplePropertyDlg::OnBrightnessAuto()
{
    if( m_pBrightnessCheck->GetCheck() )
    {
        m_VCDProp.setAuto( VCDID_Brightness, true );
        m_pBrightnessSlider->EnableWindow( FALSE );
    }
    else
    {
        m_VCDProp.setAuto( VCDID_Brightness, false );
        m_pBrightnessSlider->EnableWindow();
    }
}

The click event for the "WhiteBalance" check box is implemented the same way except that both sliders "WhiteBalanceBlue", "WhiteBalanceRed" and the "One Push" button must be disabled/enabled.

The click event for the "One Push" button has a very simple implementation. It just calls the push method of the helper class:

void CVCDSimplePropertyDlg::OnWbOnepush()
{
    m_VCDProp.push( VCDID_WhiteBalance );
}

Finally add an event that handles the ON_WM_HSCROLL message. It is used to update the slider controls. Since the ON_WM_HSCROLL is sent to the dialog window and not to the respective control itself, this event handles all 3 slider controls. The correct slider control is determined via the ID of the control. This is done by the switch statement. Then the property and the appropriate static text field is set to the current value. The implementation looks as follows:

void CVCDSimplePropertyDlg::OnHScroll(UINT nSBCode, UINT nPos, CScrollBar* pScrollBar)
{
    int pos = ((CSliderCtrl*) pScrollBar)->GetPos();
    CString posText;
    posText.Format( "%d", pos );

    // Check which slider was scrolled
    switch( pScrollBar->GetDlgCtrlID() )
    {
    case IDC_WBBLUE_SLIDER:
        {
            m_VCDProp.setValue( VCDElement_WhiteBalanceBlue, pos );
            m_pWbBlueStatic->SetWindowText( posText );
        }
        break;
    case IDC_WBRED_SLIDER:
        {
            m_VCDProp.setValue( VCDElement_WhiteBalanceRed, pos );
            m_pWbRedStatic->SetWindowText( posText );
        }
        break;
    case IDC_BRIGHTNESS_SLIDER:
        {
            m_VCDProp.setValue( VCDID_Brightness, pos );
            m_pBrightnessStatic->SetWindowText( posText );
        }
        break;
    }

    CDialog::OnHScroll(nSBCode, nPos, pScrollBar);
}

Now run the application and use the sliders and the "One Push" button to manipulate the properties or use the check boxes to toggle the automation feature of the properties.