AVT Direct FirePackage
Software Manual
V2.0.0
24 July 2006
Allied Vision Technologies GmbH Taschenweg 2a D-07646 Stadtroda / Germany
Legal notice
Trademarks Unless stated otherwise, all trademarks appearing in this document of Allied Vision Technologies are brands protected by law.
Warranty The information provided by Allied Vision Technologies is supplied without any guarantees or warranty whatsoever, be it specific or implicit. Also excluded are all implicit warranties concerning the negotiability, the suitability for specific applications or the non-breaking of laws and patents. Even if we assume that the information supplied to us is accurate, errors and inaccuracy may still occur.
Copyright All texts, pictures and graphics are protected by copyright and other laws protecting intellec- tual property. It is not permitted to copy or modify them for trade use or transfer, nor may they be used on web sites.
Allied Vision Technologies GmbH 07/2006 All rights reserved. Managing Director: Mr. Frank Grube Tax ID: DE 184383113 Support: Taschenweg 2A D-07646 Stadtroda, Germany Tel.: +49 (0)36428 6770 Fax: +49 (0)36428 677-28 e-mail: [email protected]
AVT Direct FirePackage Software Manual V2.0.0 2
Contents
1 Installation ...... 5 1.1 System requirements...... 5 1.2 Scope of delivery...... 5 1.3 Installation instruction ...... 5 1.4 Directories ...... 7 2 Tutorial ...... 9 2.1 Step by step to the first frame ...... 9 2.1.1 Step 1: Creating the Project...... 9 2.1.2 Step 2: COM and DirectShow ...... 9 2.1.3 Step 3: The filter graph ...... 10 2.1.4 Step 4: Adding the camera ...... 11 2.1.5 Step 5: Showing the images on the screen...... 13 2.2 System overview ...... 13 2.2.1 DirectX and DirectShow ...... 13 2.2.2 System architecture and streaming driver ...... 15 3 AVT Picture Control ...... 22 3.1 Features and user interface...... 22 3.1.1 Standard view...... 24 3.1.2 Still image view ...... 26 3.1.3 Special Views...... 27 3.1.4 Limitation...... 27 3.2 Automation interface...... 28 3.2.1 CMainFrmObj ...... 30 3.2.2 Enumerators CNameArray, CFriendlyNameArray, CViewArray...... 32 3.2.3 CNormalChild ...... 33 3.2.4 CActiveXChild ...... 35 3.2.5 CActiveXWrapper und CControl...... 37 3.2.6 CCameraObj ...... 38 3.3 Extension interface...... 41 3.3.1 Property FriendlyCameraName ...... 42 3.3.2 Method CameraProperties ...... 42
AVT Direct FirePackage Software Manual V2.0.0 3
3.3.3 Method FormatProperties...... 42 3.3.4 Method Run...... 42 3.3.5 Method Stop...... 42 3.3.6 Method ActivateMenu ...... 42 3.3.7 Method HandleMenuCommand...... 43 3.3.8 Method IsRunning...... 43 3.3.9 Method IsWritingFile ...... 43 3.3.10 Method DeInitialize ...... 43 3.3.11 Method GetStandardSize...... 44 4 Programming interface ...... 45 4.1 COM interface ...... 45 5 ActiveX Controls ...... 52 5.1 Applying the controls ...... 52 5.2 Functions and properties...... 54 5.3 Events ...... 60 5.4 Samples ...... 61 5.4.1 Initialisation ...... 61 5.4.2 Save an image ...... 61 5.4.3 Direct buffer access ...... 62 5.4.4 Sample projects ...... 65
AVT Direct FirePackage Software Manual V2.0.0 4
1 Installation 1.1 System requirements This package is developed for Windows 2000, Windows XP and all following Windows versions. The installation of DirectX 9 or later is necessary. Additionally, the installation of the latest Windows and DirectX service packs is strongly recommended. 1.2 Scope of delivery The package is including the following parts: • WDM- streaming driver • Property Pages for AVT camera features • TWAIN data source • Programming interface (COM) for camera features, including header files • ActiveX controls for AVT cameras • Mono8 to RGB transfom filter • YUV411 to RGB transform filter • AVT Picture Control, a viewer application based on standards of DirectX • SmartView for WDM, a viewer application, optimized for maximum performance • Programming samples 1.3 Installation instruction The installation is guided by an installation program. This copies all required files and registers the COM components automatically. In addition, the install program seeks for all AVT cameras connected to the system and updates the corresponding drivers.
AVT Direct FirePackage Software Manual V2.0.0 5
All programs are put in the default directory: C:\[Program Files]\Allied Vision Technologies\Direct FirePackage
Note If an earlier version of the package is found, please uninstall it first.
AVT Direct FirePackage Software Manual V2.0.0 6
1.4 Directories The following picture shows the standard menu and directory structure.
The single directories contain the following program parts: Direct FirePackage • two executable viewer applications (AVT PictureControl and SmartView for WDM) to test AVT cameras and their features • driver install utility • all DLLs • all drivers and installation files • Mono8 to RGB convert filter (including Bayer demosaicing filter) • YUV 411 to RGB convert filter
AVTCameraDemo • Visual Basic (VB.NET) sample in which the AVT camera ActiveX control is used
AVTCameraDemo6 • the same sample in Visual Basic 6
AVT Direct FirePackage Software Manual V2.0.0 7
AVTCameraDemoHTML • example for the usage of the ActiveX control in an HTML document
AVTAccessDemo • VB.net example for using the camera and accessing an image buffer without providing a preview window
PictureAccess • VB.NET sample that shows the way of accessing an image buffer
WindowsApplication1 • Another simple VB.net viewer
C++ Sample • Visual C++ sample for a simple viewer
GraphSample • Visual C++ sample with a little Graphical User Interface (GUI)
Batch • a collection of VBScript samples for the automation interface of the AVT Picture Control viewer application Include • propset.h - a commented include file for the use of the COM programming interface • various type libraries for COM components including comments that explain their usage
AVT Direct FirePackage Software Manual V2.0.0 8
2 Tutorial 2.1 Step by step to the first frame The following sample shows step by step, how to develop a C++ application to get frames from the camera and show them on the screen. The sample uses Visual Studio .NET 2003.
2.1.1 Step 1: Creating the Project The application is created as a simple console project.
2.1.2 Step 2: COM and DirectShow DirectShow is based on COM. That’s why at first a COM initialisation is required. Additionaly, it’s required to include some ATL helper classes. This makes the usage of COM much easier.
// C++Sample.cpp : Defines the entry point for the // Console application //
#include "stdafx.h"
#include
int _tmain(int argc, _TCHAR* argv[]) { HRESULT hRes = ::CoInitialize(NULL);
::CoUninitialize(); return 0; }
AVT Direct FirePackage Software Manual V2.0.0 9
In addition DirectShow support has to be added to the project by including the required header files
... #include
int _tmain(int argc, _TCHAR* argv[]) ...
and linking the following library:
C:\DXSDK\Samples\C++\DirectShow\BaseClasses\Debug\strmbasd.lib1
2.1.3 Step 3: The filter graph A central object in DirectShow is the filter graph. It represents the path of the image data, starting with capturing an image and ending with the image display on the screen. Like all other objects in the COM model, the filter graph is represented by an interface. To display the image data on the screen, an interface is required to control the filter graph. DirectShow provides its own object to create the filter graph and add filter objects to the graph. The programming code for this is as follows: HRESULT hr = ::CoInitialize(NULL);
if(SUCCEEDED(hr)) { CComPtr
1 The creation of strmbasd.lib is described in the help file of the platform SDK AVT Direct FirePackage Software Manual V2.0.0 10
hr = m_pGraph.CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC); if(SUCCEEDED(hr)) { hr = m_pCapture.CoCreateInstance(CLSID_CaptureGraphBuilder2 , NULL, CLSCTX_INPROC); if(SUCCEEDED(hr)) { hr = m_pGraph->QueryInterface(IID_IMediaControl, (void **)&m_pMC); if(SUCCEEDED(hr)) { hr = m_pGraph->QueryInterface(IID_IVideoWindow, (LPVOID *)&m_pVideoWindow); if(SUCCEEDED(hr)) { } } } } }
::CoUninitialize();
2.1.4 Step 4: Adding the camera At least a camera object is missing to complete the program code. To determine the camera object is a little bit difficult, but fortunately DirectShow guides us through this process. At first an enumeration object has to be created that lists all video capture devices. The returned list can be searched for different criteria (in this example the first AVT camera is selected) and afterwards the discovered object can be created.
#include
#include
HRESULT FindCaptureDevice(CComPtr
CComPtr
hr = pDevEnum.CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC); if(FAILED(hr)) return hr;
CComPtr
AVT Direct FirePackage Software Manual V2.0.0 11
hr = pDevEnum->CreateClassEnumerator (CLSID_VideoInputDeviceCategory, &pClassEnum, 0); if(FAILED(hr)) return hr;
if(pClassEnum == NULL) return E_FAIL;
while(S_OK == (pClassEnum->Next(1, &pMoniker2, &cFetched))) { CComPtr
hr = pMoniker->BindToStorage(0, 0, IID_IPropertyBag, (void **)&pBag); if(SUCCEEDED(hr)) { VARIANT var; var.vt = VT_BSTR; hr = pBag->Read(L"FriendlyName", &var, NULL); if(SUCCEEDED(hr)) { CString temp(var.bstrVal); VariantClear(&var);
if(temp.Left(3) == "AVT") { hr = pMoniker->BindToObject(0, 0, IID_IBaseFilter, (void**)&pSrc); if(FAILED(hr)) return hr; return S_OK; } } } pMoniker = NULL; } return E_FAIL; } ... CComPtr
2 Using monikers is described in the COM manual.
AVT Direct FirePackage Software Manual V2.0.0 12
2.1.5 Step 5: Showing the images on the screen Finally the elements of the filter graph have to be connected and the resulting graph has to be started.
hr = FindCaptureDevice(pSrc); if(SUCCEEDED(hr)) { hr = pCapture->SetFiltergraph(pGraph); if(SUCCEEDED(hr)) { hr = pGraph->AddFilter(pSrc, L"Video Capture Source"); if(SUCCEEDED(hr)) { hr = pCapture->RenderStream(&PIN_CATEGORY_CAPTURE, &MEDIATYPE_Video, pSrc, NULL, NULL); if(SUCCEEDED(hr)) { pMC->Run(); Sleep(10000); pMC->Stop(); } } } }
DirectShow creates its own window to display the frames. The complete sample is part of the package.
2.2 System overview
2.2.1 DirectX and DirectShow DirectShow is a programming interface, provided by Microsoft, to handle streaming data in a simple way. DirectShow is a part of DirectX3 and also based on COM. In fact, the access to all functions is provided via COM interfaces. Some parts of DirectShow are very time critical. These are implemented as kernel mode drivers. To access these components DirectShow provides proxy objects. So they look like normal COM objects to the user. The following diagram provides an overview of drivers for DirectShow and DirectX.
3 You need DirectX SDK 9 and the Platform SDK to develop DirectShow applications.
AVT Direct FirePackage Software Manual V2.0.0 13
The central object in DirectShow is the filter graph. This object manages the image data from capturing to showing them on the screen. For these purposes for each image processing step different filter graph objects are created. To control the filter graph as well as to create and connect the particular filter graph objects DirectShow provides a filter graph manager. In order that the specific objects can exchange image data they have to negotiate to a consistant format. Therefore, every filter object provides so called pins as interconnecting points wherby each pin can provide different types and formats.
If the filter graph manager receives the directive to connect the different filter graph objects, it searches for an input and an output pin of the same type and format.
AVT Direct FirePackage Software Manual V2.0.0 14
The diagram above shows a typical filter graph used to capture images from a video camera and to display them on a screen.
2.2.2 System architecture and streaming driver The Direct FirePackage includes a WDM streaming driver. This driver is embedded in Microsoft DirectShow and allows that in all corresponding programs AVT cameras are made available as video capture devices.
AVT Direct FirePackage Software Manual V2.0.0 15
The driver is developed as video streaming miniclass driver.
The following interfaces are provided by the driver (or DirectShow respectively): • IAMCameraControl • IAMVideoProcAmp • IAMDroppedFrames • IAMStreamConfig • IAMVideoControl • IAMBufferNegotiation
The capture device provides these two pins to the user: • PINNAME_VIDEO_CAPTURE • PINNAME_VIDEO_STILL
AVT Direct FirePackage Software Manual V2.0.0 16
Dependent on the type of camera, the following capture pin formats are supported: Mono 8, Mono 16, YUV 4:2:2, YUV 4:1:1 and RGB. The subtype is Y800, Y160, UYVY, Y411 or RGB. Some formats are supported with an encoder from Microsoft. For the other formats the package includes transformation filters, except Mono16. This filters converts images in RGB images.
For the standard feature and the advanced feature the package installs some custom property pages. To open a property page in an application see the following C++ code segment:4
LRESULT CChildFrame::OnCameraproperties(WORD /*wNotifyCode*/, WORD /*wID*/, HWND /*hWndCtl*/, BOOL &bHandled) { HRESULT hr;
CComPtr
hr = m_pSrc->QueryInterface(IID_ISpecifyPropertyPages, (void **)&pSpec);
if(SUCCEEDED(hr)) { hr = pSpec->GetPages(&cauuid);
// m_pSrc is a Ptr to a IBaseFilter Interface hr = OleCreatePropertyFrame(m_hWnd, 30, 30, NULL, 1, (IUnknown **)&(m_pSrc.p), cauuid.cElems, (GUID *)cauuid.pElems, 0, 0, NULL);
CoTaskMemFree(cauuid.pElems); }
bHandled = true; return 0; }
4 The usage of property pages is described more detailed in the corresponding chapters of the Platform SDK help file.
AVT Direct FirePackage Software Manual V2.0.0 17
The different tabs implement the following properties:
2.2.2.1 Camera Info This tab shows information about the camera, the vendor and the camera model. Additionally, you can find the serial number, and the driver version.
2.2.2.2 Camera Control 1 To adjust the Gain and Whitebalance (separated by U- and V- values) use the Camera Control 1 tab.
For a manual adjustment of Gain or Whitebalance the corresponding slider or edit box can be used. Alternatively, if the camera supports the corresponding Auto or One Push feature the related check box is enabled and can be selected. On every change the slider position is updated automatically in a few CPU cycles. Additionally, dependent on the camera model, the user can select some test images to test the sensor functionality and the image data transmission between the camera and PC. All changes take effect immediately. That’s why the Apply button is always disabled.
AVT Direct FirePackage Software Manual V2.0.0 18
2.2.2.3 Camera Control 2 This tab allows the user to adjust the Brightness and the Shutter time by using the corresponding sliders.
If the camera supports the auto shutter functionality, this feature can be enabled by setting the related check box. Additionally, a time base for the exposure time can be selected. The possible values are pre-defined between 1µs and 1 second. Please note that this selection is only possible if the camera is stopped. Moreover, the AVT cameras have an advanced feature, called extended shutter. This function allows the user to adjust the exposure time more precisely and over a larger range. If the slider is activated by checking the corresponding check box, the extended shutter time can be set in steps of 1ms to a value between 0..67s. Furthermore the user can enable the gamma correction, if the camera provides an appropriate Look Up Table (LUT).
AVT Direct FirePackage Software Manual V2.0.0 19
2.2.2.4 Direct Access The Direct Access tab allows direct access to the registers of the camera. The registers can be read or written by using the corresponding buttons.5
2.2.2.5 Format 7 In addition to the standard formats the AVT cameras provide format 7. If the camera mode is set to format 7, the user can set a certain area of interest (AOI) by clicking the ‘Change Format 7 settings’ button.
The values are sent to the camera, checked and the registers are set accordingly. Afterwards the user can select the new format in the data stream format dialog. Also the user can set the MultiShot feature on this page. This controls, how many images the camera captures. Wherby, a value of zero activates the continuous shot mode.
5 A detailed description of the registers and whether they can be read and/or written can be found in the camera manual and the DCAM specification. AVT Direct FirePackage Software Manual V2.0.0 20
2.2.2.6 Data stream format This dialog is a standard DirectShow dialog.
The user can choose a colour coding, a resolution and a frame rate. Possible values depend on the camera. Because these parameters are attributes of the filter graph, not the camera, the code to show the dialog is a little bit different:
LRESULT CChildFrame::OnFormatprops(WORD /*wNotifyCode*/, WORD /*wID*/, HWND /*hWndCtl*/, BOOL& /*bHandled*/) { HRESULT hr;
if(m_pCapture) { CComPtr
hr = m_pCapture->FindInterface(&PIN_CATEGORY_CAPTURE, &MEDIATYPE_Video, m_pSrc, IID_IAMStreamConfig, (void **)&pSC);
CComPtr
hr = pSC->QueryInterface(IID_ISpecifyPropertyPages, (void **)&pSpec);
if(SUCCEEDED(hr)) { hr = pSpec->GetPages(&cauuid); hr = OleCreatePropertyFrame(m_hWnd, 30, 30, NULL, 1, (IUnknown **)&(pSC.p), cauuid.cElems, (GUID *)cauuid.pElems, 0, 0, NULL);
CoTaskMemFree(cauuid.pElems); } } return 0; }
AVT Direct FirePackage Software Manual V2.0.0 21
3 AVT Picture Control The application AVT Picture Control allows the user, to access the AVT cameras in a simple way without any additional efforts. You can adjust different features and see the captured frames on the screen. Alternatively the stream can be saved as an AVI file. Individual frames can be captured via a snap shot function and save as bitmaps or copy in the clipboard. More complex operations are handled in different ways. The program provides an automatied interface to define complex functions and execute them automatically. The other way is the IAVTExtender interface. It allows the user to include controls for image processing and integrate them in the application.
3.1 Features and user interface The main menu has a simple structure. By selecting ‘File’, the user can open new camera views or execute automated scripts (‘Start Batch …’).
The ‘Devices and Views’ dialog (shown on the next page) is opened when selecting the ‘New’ menu entry under ‘File’. The dialog provides a list of detected cameras. On the right side the user can select between the standard view (a simple live stream) and the provided extended views, which are listed below. Please note that extended views can only be displayed if the SampleViews.dll is registered. The registration can be performed by using the regsvr32 command inside a DOS prompt.
AVT Direct FirePackage Software Manual V2.0.0 22
The second option under the ‘File’ menu entry is ‘Start Batch…’. This command can be used to execute predefined scripts. The script files can be found in the directory ‘Batch’, installed with the Direct FirePackage. A special icon and a message is shown in the status bar of the application when a script is used.
Under View some standard functions are provided, like show and hide the tool and/or status bar.
Under options the Video Rendere 9 can be enabled or disabled.
By selecting ‘Help’ the AVT Picture Control application can be registered. Please note that the registration is only necessary if there is no AVT camera used. Please refer to the chapter 3.1.4 Limitation to get more information about this issue.
Additionally, by choosing ‘About Picture Control’ the version of the application is provided.
AVT Direct FirePackage Software Manual V2.0.0 23
3.1.1 Standard view
The standard view displays a live stream from the camera. The menu “Capture” allows the user to start and stop the capturing. Also, the user inputs a file name to save the stream in an AVI file. If you save the file, the display of the images on the screen can be delayed. The menu “Properties” provides the dialogs for format and camera properties.
AVT Direct FirePackage Software Manual V2.0.0 24
The dialog for the format properties is similar to the dialog in the SmartView for WDM application. It simplifies the GUI use and makes the setting of all format 7 parameters possible. To scale the picture with the correct aspect ratio, the menu “Window“ provides some features. With “Full Screen” it starts displaying frames on the complete screen without windows. To stop this mode, press “Escape”.
The status bar of the view window shows information about resolution and colour format. Also it displays counts of captured and dropped frames and the average frame rate.
The camera button takes a snap shot of the stream and displays the still image in a separate window with its own view type.
AVT Direct FirePackage Software Manual V2.0.0 25
3.1.2 Still image view
The menu item “Take Picture“ makes more snap shots. Attention! All previous image data will be overwritten. This is only possible, if no other view has reserved the camera. You can show a timestamp on the picture. The picture can be saved as bitmap or copied to the clipboard.
AVT Direct FirePackage Software Manual V2.0.0 26
3.1.3 Special Views
If the user chooses an extended view type, this view can add its own items in the main menu. The functionality depends on the view control. Before using the views, the sample lib must be registerd. To do this change to directory [Program Files]\Allied Vision Technologies\Direct FirePackage and run the command: regsvr32 SampleViews.dll. This DLL requires a DirectX 3D interface.
3.1.4 Limitation The application in embedded in the DirectShow world. That’s why all video capture sources can be used with this program. If you attach at least one AVT camera, the application is unlimited. In other cases, the software is a free- of- charge demo version and limited to evaluation purposes. Once 5000 frames have been displayed, the program stops and a message pop up. For registration you need a key from Allied Vision Technologies or you can reinstall the package. To get the key, send the displayed code to AVT. Write the key from AVT in the dialog box. After a new installation you must input the key again, so don’t lose it.
AVT Direct FirePackage Software Manual V2.0.0 27
3.2 Automation interface The application can automate complex or routine operations. For instance this can be to open all cameras and start capturing frames. Another task is to start capturing and take a snap shot every 10 minutes and save it in a file. All these operations can be done by the automated interface. To do this, the program includes the Microsoft Scripting Host. This module provides an environment for a scripting language. The viewer application uses Visual Basic Script. This offers all the possibilities of Microsoft VBScript6 to the user. You only select the item , choose a script file and the program will be executed in the context of the application.
The following simple example shows a message on the screen:
1: MsgBox "Hello World"
Of course the application needs a connection between the scripting host and the application specific functionality. That’s why the program provides a collection of COM- Objects, to bring all functions to the scripting host user. The base for all other objects is CMainFrmObj. All methods and properties can be used directly in the script. Here is a second sample to show a text in the status bar:
1: PaintStatusText "Hello World"
All functions are structured in different COM objects. The organization is oriented on the user interface of the application. The following diagram gives you an overview of all objects and their dependencies:
6 For a detailed description look at Microsoft MSDN
http://msdn.microsoft.com/library/default.asp?url=/library/enus/script56/html/vtorivbscript.asp
AVT Direct FirePackage Software Manual V2.0.0 28
The object CMainFrmObj provides access to different enumerators. This lists all cameras and views. The following script sample lists all user- friendly camera names:
1: for each name in FriendlyNames 2: MsgBox name 3: next
All implemented objects and their methods and properties are described below:
AVT Direct FirePackage Software Manual V2.0.0 29
3.2.1 CMainFrmObj This object represents the application and is the base for all actions. It provides access to all other objects.
AVT Direct FirePackage Software Manual V2.0.0 30
Type Name Parameter Description Method PaintStatusText [in] BSTR text Show text in the application status bar Method ShowNormal Move the application window to normal Method ShowMaximized Maximize the application window method ShowMinimized Minimize the application window propget CameraNames [out, retval] IDispatch** pVal Return the enumerator for unique camera names propget FriendlyNames [out, retval] IDispatch** pVal Return enumerator for user friendly camera names method ShowDeviceDialog [out, retval] IDispatch** pVal Display the open dialog and return the opend view object method OpenCamera [in] LONG camera Open a new view [in] LONG view window [out,retval] IDispatch** obj View: 0… Standard View, 1..n installed Views and return the view window object method Cascade Cascade all windows method Tile [in] VARIANT_BOOL horizontal Tile all windows method GetActive [out,retval] IDispatch** camera Get the active view window object propget ViewNames [out, retval] IDispatch** pVal Return enumerator for all installed views method GetIndexForName [in] BSTR name Get the index for a [out,retval] LONG* index unique camera name method GetIndexForFriendlyName [in] BSTR friendlyName Get the first index [out,retval] LONG* index for a user friendly camera name method GetIndexForView [in] BSTR view Get the index for a [out,retval] LONG* index view method Sleep [in] LONG milliseconds Stops the execution of the script for n milliseconds. Capturing frames continues
AVT Direct FirePackage Software Manual V2.0.0 31
3.2.2 Enumerators CNameArray, CFriendlyNameArray, CViewArray
All enumerators provide the same interface. This interface allows VBScript the use of for each- loops.
Type Name Parameter Description propget _NewEnum [out, retval] IUnknown **ppUnk Makes a copy of the enumerator object propget Item [in] long Index, Get a value by an index [out, retval] VARIANT *pVal propget Count [out, retval] long *pVal Counts the elements
LONG GetIndex CComBSTR name Get the index of a value (this method provides the application object, not the enumerator)
AVT Direct FirePackage Software Manual V2.0.0 32
3.2.3 CNormalChild This object represents a window, the standard view.
AVT Direct FirePackage Software Manual V2.0.0 33
Type Name Parameter Description method Start void Start capturing method Stop void Stop capturing method FullSize void Show the frame in full size (with correct aspect ration) depend on the selected resolution method HalfSize void Show the frame in half size method QuarterSize void Show the frame in quarter size method FullScreen void Display the frame on full screen propget XPos [out, retval] LONG* pVal Left corner of the window propput XPos [in] LONG newVal propget YPos [out, retval] LONG* pVal Top corner of the window propput YPos [in] LONG newVal propget Width [out, retval] LONG* pVal With of the window propput Width [in] LONG newVal propget Height [out, retval] LONG* pVal Height of the window propput Height [in] LONG newVal propget PictureWidth [out, retval] LONG* pVal With of the picture (without window frame elements) propput PictureWidth [in] LONG newVal propget PictureHeight [out, retval] LONG* pVal Height of the picture (without window frame elements) propput PictureHeight [in] LONG newVal method FormatDialog void Show format properties dialog method PropertieDialog void Show camera properties dialog method ShowMaximized void Maximize window method ShowMinimized void Minimize window method ShowNormal void Move window normal propget CameraName [out, retval] BSTR* pVal Get unique camera name propget FriendlyName [out, retval] BSTR* pVal Get user friendly camera name propget ViewType [out, retval] BSTR* pVal Get view name propget CameraObj [out, retval] IDispatch** pVal Get camera object method TakePicture void Take a snap shot and open a view method SavePicture [in] BSTR filename Take a snap shot and save it as bitmap
AVT Direct FirePackage Software Manual V2.0.0 34
3.2.4 CActiveXChild This object represents an extended view window
AVT Direct FirePackage Software Manual V2.0.0 35
Type Name Parameter Description method Start void Start capturing method Stop void Stop capturing method FullSize void Show the frame in full size (with correct aspect ration) depend on the selected resolution method HalfSize void Show the frame in half size method QuarterSize void Show the frame in quarter size method FullScreen void Display the frame on full screen propget XPos [out, retval] LONG* pVal Left corner of the window propput XPos [in] LONG newVal propget YPos [out, retval] LONG* pVal Top corner of the window propput YPos [in] LONG newVal propget Width [out, retval] LONG* pVal With of the window propput Width [in] LONG newVal propget Height [out, retval] LONG* pVal Height of the window propput Height [in] LONG newVal method FormatDialog void Show format properties dialog method PropertieDialog void Show camera properties dialog method ShowMaximized void Maximize window method ShowMinimized void Minimize window method ShowNormal void Move window normal propget CameraName [out, retval] BSTR* pVal Get unique camera name propget FriendlyName [out, retval] BSTR* pVal Get user friendly camera name propget ViewType [out, retval] BSTR* pVal Get view name propget Control [out, retval] IDispatch** pVal Return the ActiveX control propget AVTExtender [out, retval] IDispatch** pVal Return the IAVTExtender interface Propget CameraObj [out, retval] IDispatch** pVal Get the camera object
AVT Direct FirePackage Software Manual V2.0.0 36
3.2.5 CActiveXWrapper und CControl These objects represent the ActiveX control inside the window. You can access the IAVTExtender interface via CActiveXWrapper object. This interface is described in chapter 3.3. The CControl object provides access to the custom methods of the ActiveX control.
Type Name Parameter Description propget FriendlyCameraName [out, retval] BSTR* pVal User friendly camera name propput FriendlyCameraName [in] BSTR newVal method CameraProperties void Show the camera properties dialog method FormatProperties void Show the format properties dialog method Run void Start capturing method Stop void Stop capturing method ActivateMenu [in] ULONG hMenu Allows the control to include own items into the main menu method HandleMenuCommand [in] ULONG commandID Handle custom menu commands method IsRunning [out,retval] VARIANT_BOOL* retval Check, if capture frames method IsWritingFile [out,retval] VARIANT_BOOL* retval Check, if writing file method DeInitialize void Deinitialize the control (Attention!) method GetStandardSize [out] LONG* width, [out] LONG* Get picture standard height size
AVT Direct FirePackage Software Manual V2.0.0 37
3.2.6 CCameraObj The CCameraObj represent the AVT camera and provides access to the complete programming interface.
AVT Direct FirePackage Software Manual V2.0.0 38
Type Name Parameter Description propget Gamma [out, retval] VARIANT_BOOL* pVal Enable gamma correction propput Gamma [in] VARIANT_BOOL newVal propget GainMin [out, retval] LONG* pVal Min. gain value propget GainMax [out, retval] LONG* pVal Max. gain value propget GainAutoAvailable [out, retval] VARIANT_BOOL* pVal Gain automode available propget GainOnePushAvailable [out, retval] VARIANT_BOOL* pVal Gain OnePush available propget Gain [out, retval] LONG* pVal Gain value propput Gain [in] LONG newVal propget GainOnePush [out, retval] VARIANT_BOOL* pVal Gain OnePush propput GainOnePush [in] VARIANT_BOOL newVal propget GainAuto [out, retval] VARIANT_BOOL* pVal Gain Automode propput GainAuto [in] VARIANT_BOOL newVal propget WhitebalanceVMin [out, retval] LONG* pVal Whitebalance V min. value propget WhitebalanceVMax [out, retval] LONG* pVal Whitebalance V max. value propget WhitebalanceVAutoAvailable [out, retval] VARIANT_BOOL* pVal Whitebalance V autom. mode available propget WhitebalanceVOnePushAvailable [out, retval] VARIANT_BOOL* pVal Whitebalance V One Push available propget WhitebalanceV [out, retval] LONG* pVal Whitebalance V value propput WhitebalanceV [in] LONG newVal propget WhitebalanceVOnePush [out, retval] VARIANT_BOOL* pVal Whitebalance V One Push propput WhitebalanceVOnePush [in] VARIANT_BOOL newVal propget WhitebalanceVAuto [out, retval] VARIANT_BOOL* pVal Whitebalance V autom. Mode propput WhitebalanceVAuto [in] VARIANT_BOOL newVal propget WhitebalanceUMin [out, retval] LONG* pVal Whitebalance U min. value propget WhitebalanceUMax [out, retval] LONG* pVal Whitebalance U max. value propget WhitebalanceUAutoAvailable [out, retval] VARIANT_BOOL* pVal Whitebalance U autom. mode available propget WhitebalanceUOnePushAvailabl [out, retval] VARIANT_BOOL* pVal Whitebalance U One e Push available propget WhitebalanceU [out, retval] LONG* pVal Whitebalance U value propput WhitebalanceU [in] LONG newVal propget WhitebalanceUOnePush [out, retval] VARIANT_BOOL* pVal Whitebalance U One Push propput WhitebalanceUOnePush [in] VARIANT_BOOL newVal propget WhitebalanceUAuto [out, retval] VARIANT_BOOL* pVal Whitebalance U autom. mode propput WhitebalanceUAuto [in] VARIANT_BOOL newVal propget BrightnessMin [out, retval] LONG* pVal Brightness min. value propget BrightnessMax [out, retval] LONG* pVal Brightness max.
AVT Direct FirePackage Software Manual V2.0.0 39
Type Name Parameter Description value propget BrightnessAutoAvailable [out, retval] VARIANT_BOOL* pVal Brightness autom. Mode available propget BrightnessOnePushAvailable [out, retval] VARIANT_BOOL* pVal Brigthness OnePush available propget Brightness [out, retval] LONG* pVal Brightness value propput Brightness [in] LONG newVal propget BrightnessOnePush [out, retval] VARIANT_BOOL* pVal Brightness One Push propput BrightnessOnePush [in] VARIANT_BOOL newVal propget BrightnessAuto [out, retval] VARIANT_BOOL* pVal Brightness autom. mode propput BrightnessAuto [in] VARIANT_BOOL newVal propget ExposureMin [out, retval] LONG* pVal Exposure min. value propget ExposureMax [out, retval] LONG* pVal Exposure max. value propget ExposureAutoAvailable [out, retval] VARIANT_BOOL* pVal Exposure autom. Mode available propget ExposureOnePushAvailable [out, retval] VARIANT_BOOL* pVal Exposure One Push available propget Exposure [out, retval] LONG* pVal Exposure value propput Exposure [in] LONG newVal propget ExposureOnePush [out, retval] VARIANT_BOOL* pVal Exposure One Push propput ExposureOnePush [in] VARIANT_BOOL newVal propget ExposureAuto [out, retval] VARIANT_BOOL* pVal Exposure autom. mode propput ExposureAuto [in] VARIANT_BOOL newVal propget TestImageAvailable [out, retval] LONG* pVal Bitfield of available test images propget TestImage [out, retval] LONG* pVal Enable test image propput TestImage [in] LONG newVal propget Vendor [out, retval] BSTR* pVal Camera vendor propget Model [out, retval] BSTR* pVal Camera model propget Driver [out, retval] BSTR* pVal Driver version propget SerialNumber [out, retval] LONG* pVal Camera serial number propget TimeBase [out, retval] LONG* pVal Exposure time base propput TimeBase [in] LONG newVal method SetValue [in] LONG address, LONG value Write camera register direct method GetValue [in] LONG address, Read camera [out,retval] LONG* value register direct
AVT Direct FirePackage Software Manual V2.0.0 40
3.3 Extension interface The extension interface allows the user to integrate views with any functionality and complexity into the application. The extension is a normal ActiveX control, which provides an additional interface: [ object, uuid(103163ED-6FDE-430f-9C10-5D8CCB96CABB), dual, nonextensible, helpstring("IAVTExtender-Schnittstelle"), pointer_default(unique) ] interface IAVTExtender : IDispatch { [propget, id(1), helpstring("property FriendlyCameraName")] HRESULT FriendlyCameraName([out, retval] BSTR* pVal); [propput, id(1), helpstring("property FriendlyCameraName")] HRESULT FriendlyCameraName([in] BSTR newVal); [id(2), helpstring("method CameraProperties")] HRESULT CameraProperties(void); [id(3), helpstring("method FormatProperties")] HRESULT FormatProperties(void); [id(4), helpstring("method Run")] HRESULT Run(void); [id(5), helpstring("method Stop")] HRESULT Stop(void); [id(6), helpstring("method ActivateMenu")] HRESULT ActivateMenu([in] ULONG hMenu); [id(7), helpstring("method HandleMenuCommand")] HRESULT HandleMenuCommand([in] ULONG commandID); [id(8), helpstring("method IsRunning")] HRESULT IsRunning([out,retval] VARIANT_BOOL* retval); [id(9), helpstring("method IsWritingFile")] HRESULT IsWritingFile([out,retval] VARIANT_BOOL* retval); [id(10), helpstring("method DeInitialize")] HRESULT DeInitialize(void); [id(11), helpstring("method GetStandardSize")] HRESULT GetStandardSize([out] LONG* width, [out] LONG* height); };
The installation of custom views is very simple. First register the control in the usual way. In the second step add an entry to the file AVTPictureControl.ini in the section [Extend]. This entry has the form “name of view”=”ActiveX control ID”:
[Extend] Frame Sequence=SampleViews.BMPSequence.1 3D View=SampleViews.Direct3DView.1 Color Splitter=SampleViews.ColorSplitter.1 Histogramm=SampleViews.Histogramm.1
The methods and properties are described in the following chapters.
AVT Direct FirePackage Software Manual V2.0.0 41
3.3.1 Property FriendlyCameraName This property specifies the camera, which the user selected.
3.3.2 Method CameraProperties This method is called, if the user selects the menu item. He expects a dialog box to adjust the camera properties.
3.3.3 Method FormatProperties This method is also activated through the menu item. It should open a dialog box with the format properties.
3.3.4 Method Run It starts capturing.
3.3.5 Method Stop This method stops capturing.
3.3.6 Method ActivateMenu The application calls this method on activating the main menu. It provides the possibility to include custom menus in the main menu. Look at the sample implementation: STDMETHOD(ActivateMenu)(ULONG hMenu) { m_hMenu = ::CreateMenu();
InsertMenu(m_hMenu, -1, MF_BYPOSITION | MF_STRING, WM_USER + 1000, "Save Bitmap..."); InsertMenu(m_hMenu, -1, MF_BYPOSITION | MF_SEPARATOR, 0, NULL); InsertMenu(m_hMenu, -1, MF_BYPOSITION | MF_STRING, WM_USER + 1001, "Show Time"); InsertMenu(m_hMenu, -1, MF_BYPOSITION | MF_STRING, WM_USER + 1002, "Select Time Color...");
InsertMenu((HMENU)hMenu, 3, MF_BYPOSITION | MF_POPUP, (UINT_PTR)m_hMenu, "Sequence");
return S_OK; }
The control can use message id’s starting with WM_USER + 1000.
AVT Direct FirePackage Software Manual V2.0.0 42
3.3.7 Method HandleMenuCommand If the user selects a custom menu item, this method is called to handle the request: STDMETHOD(HandleMenuCommand)(ULONG commandID) { switch(commandID) { case WM_USER + 1000: Save(); break; case WM_USER + 1001: m_bShow = !m_bShow;
for(int i = 0; i < 6; i++) m_cPicture[i].m_bShowTime = m_bShow;
if(m_bShow) CheckMenuItem(m_hMenu, WM_USER + 1001, MF_CHECKED | MF_BYCOMMAND); else CheckMenuItem(m_hMenu, WM_USER + 1001, MF_UNCHECKED | MF_BYCOMMAND); break; case WM_USER + 1002: SelectColor(); break; default: break; } return S_OK; }
This example also shows, how menu items could be checked and unchecked.
3.3.8 Method IsRunning The system ask the control for running state, for instance to set the button states.
3.3.9 Method IsWritingFile The system asks the control for writing a file, for instance to set the button states.
3.3.10 Method DeInitialize If the view window is closed and before the control is transferred, the application calls this function. That way the control can release memory and so on.
AVT Direct FirePackage Software Manual V2.0.0 43
3.3.11 Method GetStandardSize The application calls this method, to get the standard size. This is the base for handling menu commands like “Full Size”, “Half Size” and so on.
AVT Direct FirePackage Software Manual V2.0.0 44
4 Programming interface 4.1 COM interface To adjust the features of the AVT cameras a COM interface is provided. It allows simple access to the parameters. The methods have the following basic structure:
• Request the value range • Get function • Set function
The method names are like the parameter names of the camera. You can find a detailed description in the camera manual and the DCAM specification. With the GetValue and SetValue functions provide the interface direct access to the camera register. This is a short example to instantiate the COM interface:
...
CComPtr
CComQIPtr
if(pTest) { BOOL value = FALSE; hr = pTest->SetGamma(TRUE); hr = pTest->GetGamma(&value);
ULONG gainMin, gainMax;
hr = pTest->GetGainRange(&gainMin, &gainMax); }
...
And a detailed definition of the interface:
// GUID for AVT- PropSet
// {DEC6F81A-8C51-4279-A45F-2623826BA892} DEFINE_GUID(PROPSETID_VIDCAP_AVT, 0xdec6f81a, 0x8c51, 0x4279, 0xa4, 0x5f, 0x26, 0x23, 0x82, 0x6b, 0xa8, 0x92); AVT Direct FirePackage Software Manual V2.0.0 45
// Interface for AVT- Propset interface IAVTDolphinPropSet: public IUnknown { // Gamma STDMETHOD(GetGamma)(BOOL *pbOn) = 0; STDMETHOD(SetGamma)(BOOL bOn) = 0;
// Gain STDMETHOD(GetGain)(ULONG *pulGain, BOOL *pbAuto, BOOL *pbOnePush) = 0; STDMETHOD(SetGain)(ULONG ulGain, BOOL bAuto, BOOL bOnePush) = 0; STDMETHOD(GetGainRange)(ULONG *pulGainMin, ULONG *pulGainMax, BOOL *pbAuto, BOOL *pbOnePush) = 0;
// Whitebalance U STDMETHOD(GetWhitebalanceU)(ULONG *pulWhitebalanceU, BOOL *pbAuto, BOOL *pbOnePush) = 0; STDMETHOD(SetWhitebalanceU)(ULONG ulWhitebalanceU, BOOL bAuto, BOOL bOnePush) = 0; STDMETHOD(GetWhitebalanceURange)(ULONG *pulWhitebalanceUMin, ULONG *pulWhitebalanceUMax, BOOL *pbAuto, BOOL *pbOnePush) = 0;
// Whitebalance V STDMETHOD(GetWhitebalanceV)(ULONG *pulWhitebalanceV, BOOL *pbAuto, BOOL *pbOnePush) = 0; STDMETHOD(SetWhitebalanceV)(ULONG ulWhitebalanceV, BOOL bAuto, BOOL bOnePush) = 0; STDMETHOD(GetWhitebalanceVRange)(ULONG *pulWhitebalanceVMin, ULONG *pulWhitebalanceVMax, BOOL *pbAuto, BOOL *pbOnePush) = 0;
// Test Image STDMETHOD(GetTestImage)(ULONG *pulImage) = 0; STDMETHOD(SetTestImage)(ULONG ulImage) = 0; STDMETHOD(GetTestImageAvailable)(ULONG *pulMask) = 0;
// Brightness STDMETHOD(GetBrightness)(ULONG *pulBrightness, BOOL *pbAuto, BOOL *pbOnePush) = 0; STDMETHOD(SetBrightness)(ULONG ulBrightness, BOOL bAuto, BOOL bOnePush) = 0; AVT Direct FirePackage Software Manual V2.0.0 46
STDMETHOD(GetBrightnessRange)(ULONG *pulBrightnessMin, ULONG *pulBrightnessMax, BOOL *pbAuto, BOOL *pbOnePush) = 0;
//Exposure STDMETHOD(GetExposure)(ULONG *pulExposure, BOOL *pbAuto, BOOL *pbOnePush) = 0; STDMETHOD(SetExposure)(ULONG ulExposure, BOOL bAuto, BOOL bOnePush) = 0; STDMETHOD(GetExposureRange)(ULONG *pulExposureMin, ULONG *pulExposureMax, BOOL *pbAuto, BOOL *pbOnePush) = 0;
// Extended Shutter STDMETHOD(GetExtShutter)(ULONG *pulExtShutter) = 0; STDMETHOD(SetExtShutter)(ULONG ulExtShutter) = 0; STDMETHOD(GetExtShutterRange)(ULONG *pulExtShutterMin, ULONG *pulExtShutterMax) = 0;
// Timebase (index) STDMETHOD(GetTimeBase)(ULONG *pulTimeBase) = 0; STDMETHOD(SetTimeBase)(ULONG ulTimeBase) = 0;
// Info STDMETHOD(GetModelInfo)(char **vendor, char **model, char **driver, PULONG serial) = 0; STDMETHOD(GetModelInfoEx)(char **vendor, char **model, char **driver, PULONG serial, char **microc, char **fpga) = 0;
// Obsolete, don't use STDMETHOD(SetFormat7)(BOOL bAvailable, ULONG xPos, ULONG yPos, ULONG width, ULONG height, ULONG payload, BOOL bAvailable2, ULONG xPos2, ULONG yPos2, ULONG width2, ULONG height2, ULONG payload2, ULONG multishot) = 0; STDMETHOD(GetFormat7)(BOOL *bAvailable, ULONG *pxPos, ULONG *pyPos, ULONG *pwidth, ULONG *pheight, ULONG *ppayload, BOOL *bAvailable2, ULONG *pxPos2, ULONG *pyPos2, ULONG *pwidth2, ULONG *pheight2, ULONG *ppayload2, ULONG *pmultishot) = 0;
AVT Direct FirePackage Software Manual V2.0.0 47
// Direct Access STDMETHOD(SetValue)(ULONG address, ULONG value) = 0; STDMETHOD(GetValue)(ULONG address, ULONG *pvalue) = 0;
// Format 7 + Multishot STDMETHOD(GetFormat7Count)(ULONG *pcount) = 0;
// index don't use, call SetFormat7Index before use this functions STDMETHOD(GetFormat7All)(ULONG index, ULONG *pxPos, ULONG *pyPos, ULONG *pwidth, ULONG *pheight, ULONG *ppayload, ULONG *punitWidth, ULONG *punitHeight, ULONG *pmaxWidth, ULONG *pmaxHeight, ULONG *pColorCoding, ULONG *pmultishot) = 0; STDMETHOD(SetFormat7All)(ULONG index, ULONG xPos, ULONG yPos, ULONG width, ULONG height, ULONG ColorCoding, ULONG multishot) = 0;
STDMETHOD(SetEnableFormat7)(ULONG index, ULONG enable) = 0; STDMETHOD(GetEnableFormat7)(ULONG *pindex, ULONG *penable) = 0;
// index starts at 0 to GetFormat7Count - 1 STDMETHOD(SetFormat7Index)(ULONG index) = 0;
STDMETHOD(SetFlags)(ULONG flags) = 0; STDMETHOD(GetFlags)(ULONG *pFlags) = 0;
STDMETHOD(SetFormat7AllPayload)(ULONG index, ULONG xPos, ULONG yPos, ULONG width, ULONG height, ULONG ColorCoding, ULONG multishot, ULONG payload) = 0;
STDMETHOD(GetFormat7PayloadRange)(ULONG index, ULONG *min, ULONG *max) = 0;
// Mirror STDMETHOD(GetMirrorAvailable)(BOOL *pbOK) = 0; AVT Direct FirePackage Software Manual V2.0.0 48
STDMETHOD(GetMirror)(BOOL *pbOn) = 0; STDMETHOD(SetMirror)(BOOL bOn) = 0;
STDMETHOD(GetFormat7MaxPayload)(ULONG index, ULONG colorCoding, ULONG x, ULONG y, ULONG w, ULONG h, ULONG *min, ULONG *max) = 0;
// Sharpness STDMETHOD(GetSharpness)(ULONG *pulSharpness, BOOL *pbAuto, BOOL *pbOnePush) = 0; STDMETHOD(SetSharpness)(ULONG ulSharpness, BOOL bAuto, BOOL bOnePush) = 0; STDMETHOD(GetSharpnessRange)(ULONG *pulSharpnessMin, ULONG *pulSharpnessMax, BOOL *pbAuto, BOOL *pbOnePush) = 0;
// Hue STDMETHOD(GetHue)(ULONG *pulHue, BOOL *pbAuto, BOOL *pbOnePush) = 0; STDMETHOD(SetHue)(ULONG ulHue, BOOL bAuto, BOOL bOnePush) = 0; STDMETHOD(GetHueRange)(ULONG *pulHueMin, ULONG *pulHueMax, BOOL *pbAuto, BOOL *pbOnePush) = 0;
// Saturation STDMETHOD(GetSaturation)(ULONG *pulSaturation, BOOL *pbAuto, BOOL *pbOnePush) = 0; STDMETHOD(SetSaturation)(ULONG ulSaturation, BOOL bAuto, BOOL bOnePush) = 0; STDMETHOD(GetSaturationRange)(ULONG *pulSaturationMin, ULONG *pulSaturationMax, BOOL *pbAuto, BOOL *pbOnePush) = 0;
// Auto Shutter STDMETHOD(GetAutoShutter)(ULONG *pulMin, ULONG *pulMax) = 0; STDMETHOD(SetAutoShutter)(ULONG ulMin, ULONG ulMax) = 0;
// Auto Gain STDMETHOD(GetAutoGain)(ULONG *pulMin, ULONG *pulMax) = 0; STDMETHOD(SetAutoGain)(ULONG ulMin, ULONG ulMax) = 0;
// Auto AOI STDMETHOD(GetAutoAOI)(BOOL *pbShow, BOOL *pbOn, ULONG *pulXPos, ULONG *pulYPos, ULONG *pulWidth, ULONG *pulHeight) = 0; STDMETHOD(SetAutoAOI)(BOOL bShow, BOOL bOn, ULONG ulXPos, ULONG ulYPos, ULONG ulWidth, ULONG ulHeight) = 0;
AVT Direct FirePackage Software Manual V2.0.0 49
// Color Correction STDMETHOD(GetColorCorrection)(BOOL *pbOn) = 0; STDMETHOD(SetColorCorrection)(BOOL bOn) = 0;
// Frame Info STDMETHOD(GetFrameInfo)(ULONG *counter) = 0; STDMETHOD(ResetFrameInfo)() = 0;
// Reset STDMETHOD(ResetCamera)() = 0;
// Shading Control STDMETHOD(GetShadingControl)(BOOL *pbOn, BOOL *pbShow, BOOL *pbBuild, BOOL *pbError, BOOL *pbBusy, ULONG *pulGrabCount) = 0; STDMETHOD(SetShadingControl)(BOOL bOn, BOOL bShow, BOOL bBuild, BOOL bError, BOOL bBusy, ULONG ulGrabCount) = 0; STDMETHOD(GetShadingImage)(ULONG *buffer, ULONG *size) = 0; STDMETHOD(SetShadingImage)(ULONG *buffer, ULONG size) = 0;
// LUT Control STDMETHOD(GetLUTControl)(BOOL *pbOn, ULONG *pulLutNum, ULONG *pulMaxLuts, ULONG *pulLutSize) = 0; STDMETHOD(SetLUTControl)(BOOL bOn, ULONG ulLutNum) = 0; STDMETHOD(SetLUT)(ULONG *buffer, ULONG size, ULONG ulLutNum) = 0;
// DSNU Control STDMETHOD(SetDSNU)(BOOL bOn, BOOL bShowImage, BOOL bComputeData, BOOL bLoadData, BOOL bZeroData, ULONG ulGrabCount) = 0; STDMETHOD(GetDSNU)(BOOL *pbOn, BOOL *pbShowImage, BOOL *pbComputeError, BOOL *pbBusy, ULONG *pulGrabCount) = 0;
// Blemish Control STDMETHOD(SetBlemish)(BOOL bOn, BOOL bShowImage, BOOL bComputeData, BOOL bLoadData, BOOL bZeroData, ULONG ulGrabCount) = 0; STDMETHOD(GetBlemish)(BOOL *pbOn, BOOL *pbShowImage, BOOL *pbComputeError, BOOL *pbBusy, ULONG *pulGrabCount) = 0;
// HDR Control STDMETHOD(SetHDR)(BOOL bOn, ULONG ulKneePoints) = 0;
AVT Direct FirePackage Software Manual V2.0.0 50
STDMETHOD(GetHDR)(BOOL *pbOn, ULONG *pulKneePoints, ULONG *pulMaxKneePoints) = 0; STDMETHOD(SetKneepoint)(ULONG ulPoint, ULONG ulValue) = 0; STDMETHOD(GetKneepoint)(ULONG ulPoint, ULONG *pulValue) = 0;
// Integration Delay STDMETHOD(SetIntegrationDelay)(BOOL bOn, ULONG ulTime) = 0; STDMETHOD(GetIntegrationDelay)(BOOL *pbOn, ULONG *pulTime) = 0;
// Trigger Delay STDMETHOD(SetTriggerDelay)(BOOL bOn, ULONG ulTime) = 0; STDMETHOD(GetTriggerDelay)(BOOL *pbOn, ULONG *pulTime) = 0;
// High SNR STDMETHOD(SetHighSNR)(BOOL bOn, ULONG ulImages) = 0; STDMETHOD(GetHighSNR)(BOOL *pbOn, ULONG *pulImages) = 0;
// Deferred Transfer STDMETHOD(SetDeferredTrans)(BOOL bSend, BOOL bHold, BOOL bFastCapture, ULONG ulNumImages) = 0; STDMETHOD(GetDeferredTrans)(BOOL *pbSend, BOOL *pbHold, BOOL *pbFastCapture, ULONG *pulNumImages, ULONG *pulFifoSize) = 0;
enum IORegister { Input1=0, Input2, Output1, Output2 };
// IO Control STDMETHOD(SetIOCtrl)(IORegister reg, ULONG ulPolarity, ULONG ulMode, ULONG ulState) = 0; STDMETHOD(GetIOCtrl)(IORegister reg, ULONG *pulPolarity, ULONG *pulMode, ULONG *pulState) = 0; };
A header file with the interface and the GUID-s is part of the package:
AVT Direct FirePackage Software Manual V2.0.0 51
5 ActiveX Controls Based on the fundamentals of working with ActiveX Controls in this manual only special functions, properties and events of the controls is explained.
5.1 Applying the controls The AVT ActiveX controls are installed together with the package and registered automatically on the computer. For inserting a control into a project add it first into the IDE toolbox.
AVT Direct FirePackage Software Manual V2.0.0 52
AVT Direct FirePackage Software Manual V2.0.0 53
Now it can be used via drag and drop like all other controls.
5.2 Functions and properties
Initialize the control and build a list of all available cameras:
C++: HRESULT InitCameraList(void);
VB.NET: InitCameraList()
Property; ReadOnly; counts all cameras in the list: C++: HRESULT CameraCount([out, retval] LONG* pVal);
VB.NET: ReadOnly CameraCount As Integer
Gets the name of the camera with the given index:
C++: HRESULT GetCameraName([in] LONG index, [out,retval] BSTR* name);
VB.NET: GetCameraName(index as Integer) as String
AVT Direct FirePackage Software Manual V2.0.0 54
Selects a camera for further use with the control:
C++: HRESULT SelectCamera([in] LONG index);
VB.NET: SelectCamera(index as Integer)
Start image capture:
C++: HRESULT Start(void);
VB.NET: Start()
Stop image capture:
C++: HRESULT Stop(void);
VB.NET: Stop()
Property; ReadOnly; is indicating whether the stream is colored or b/w:
C++: HRESULT BW([out, retval] VARIANT_BOOL* pVal);
VB.NET: ReadOnly BW as Boolean
Displays the DirectShow-Format-Properties-Dialog; the parameter can be a handle from a parent window:
C++: HRESULT CameraProperties([in] LONG hWnd);
VB.NET: CameraProperties(hWnd as Integer)
Displays the Camera-Properties-Dialog; the parameter can be a handle from a parent window:
C++: HRESULT FormatProperties([in] LONG hWnd);
VB.NET: FormatProperties(hWnd as Integer)
AVT Direct FirePackage Software Manual V2.0.0 55
[Only AVTCamera]
Property; Read/Write; control, if the image is scaled to the control size:
C++: HRESULT FrameResize([out, retval] VARIANT_BOOL* pVal);
VB.NET: FrameResize as Boolean
Property; ReadOnly; width of the image in pixel:
C++: HRESULT Width([out, retval] LONG* pVal);
VB.NET: ReadOnly Width as Integer
Property; ReadOnly; height of the image in pixel:
C++: HRESULT Height([out, retval] LONG* pVal);
VB.NET: ReadOnly Height as Integer
Save the image with the given path name:
C++: HRESULT SavePicture(BSTR fileName);
VB.NET: SavePicture(fileName as String)
This function is only because compatibility part of the interface. Use instead of this function the SetFormatFPS- function:
C++: HRESULT Format([in] LONG width, LONG height, [in] VARIANT_BOOL color);
VB.NET: Format(width as Integer, height as Integer, color as Boolean)
Allow access to all camera registers:
C++: HRESULT SetValue(ULONG address, ULONG value);
VB.NET: SetValue(address as System.UInt32, value as System.UInt32)
AVT Direct FirePackage Software Manual V2.0.0 56
Allow access to all camera registers:
C++: HRESULT GetValue([in] ULONG address, [out,retval] ULONG* value);
VB.NET: GetValue(address as System.UInt32) as System.UInt32
Count all available colour formats:
C++: HRESULT GetColorCount([out,retval] LONG* colors);
VB.NET: GetColorCount() as Integer
Return a description of the colour format with the given index
C++: HRESULT GetColor([in] LONG index, [out,retval] BSTR* color);
VB.NET: GetColor(index as Integer) as String
Return the count of resolutions to a given colour format
C++: HRESULT GetResolutionCount([in] LONG color, [out,retval] LONG* count);
VB.NET: GetResolutionCount(color as Integer) as Integer
Return a description of a resolution:
C++: HRESULT GetResolution(LONG color, LONG index, [out,retval] BSTR* resolution);
VB.NET: GetResolution(color as Integer, index as Integer) as String
Return the maximal possible frame rate to a resolution and colour format:
C++: HRESULT GetMaxFPS(LONG color, LONG index, [out,retval] DOUBLE* fps);
VB.NET: GetMaxFPS(color as Integer, index as Integer) as Double
AVT Direct FirePackage Software Manual V2.0.0 57
Select a certain format. The possible index values can be determined with the before described functions. This function is possible only if the image capturing is stopped:
C++: HRESULT SetFormatFPS(LONG color, LONG resolution, DOUBLE fps);
VB.NET: SetFormatFPS(color as Integer, resolution as Integer, fps as Double)
The following functions allow the direct access to the buffer with the image data:
[Only AVTCamera]
Property; Read/Write; enable the direct buffer access;
C++: HRESULT BufferAccess([out, retval] VARIANT_BOOL* pVal);
VB.NET: BufferAccess as Boolean
Remark: with enabled access the performance is a little lower.
C++: HRESULT GetBuffer([out,retval] BYTE** buffer);
VB.NET: GetBuffer() as System.IntPtr
[Only AVTAccess]
Get a pointer to the buffer with the image data. The control allocates new memory and copy the data. The calling application must free the memory!
C++: HRESULT GetBuffer([in] LONG index, [out,retval] BYTE** buffer);
VB.NET: GetBuffer(Integer index) as System.IntPtr
Get the size of the buffer in bytes.
C++: HRESULT GetBufferSize([out,retval] LONG* size);
VB.NET: GetBufferSize() as Integer
Get a pointer to a buffer with a valid bitmap header. The control allocates new memory and copy the data. The calling application must free the memory!
AVT Direct FirePackage Software Manual V2.0.0 58
C++: HRESULT GetBitmapHeader([out,retval] BYTE** header);
VB.NET: GetBitmapHeader() as System.IntPtr
Get the size of the buffer for the bitmap header in bytes:
C++: HRESULT GetBitmapHeaderSize([out,retval] LONG* size);
VB.NET: GetBitmapHeaderSize() as Integer
Get a pointer to a buffer with a valid bitmap file header. The control allocates new memory and copy the data. The calling application must free the memory!
C++: HRESULT GetBitmapFileHeader([out,retval] BYTE** buffer);
VB.NET: GetBitmapFileHeader() as System.IntPtr
Get the size of the buffer for the bitmap header in bytes:
C++: HRESULT GetBitmapFileHeaderSize([out,retval] LONG* size);
VB.NET: GetBitmapFileHeaderSize() as Integer
Allow access to camera objects of DirectShow:
C++: HRESULT GetCameraForFormat([out,retval] IUnknown** result);
VB.NET: GetCameraForFormat() as Object
Allow access to stream object from DirectShow
C++: HRESULT GetStreamForFormat([out,retval] IUnknown** result);
VB.NET: GetStreamForFormat() as Object
Property; count image buffer
C++: HRESULT BufferCount([out, retval] LONG* pVal);
VB.NET: BufferCount as Integer AVT Direct FirePackage Software Manual V2.0.0 59
5.3 Events
Triggered, when a file is saved HRESULT SavePicture([in] BSTR file);
Triggered, after a new image is captured HRESULT NextPicture([in] DOUBLE time);
Triggered, after a file is saved or the direct access to the image data is possible HRESULT SaveOk(void);
AVT Direct FirePackage Software Manual V2.0.0 60
5.4 Samples
All functions are described by the provided examples. In the following several basic approches are given.
5.4.1 Initialisation
Dim cameraCounter As Integer Dim i As Integer Dim name As String
AxAVTCamera1.InitCameraList() cameraCounter = AxAVTCamera1.CameraCount
CameraList.Items.Clear()
For i = 0 To cameraCounter - 1 Step 1 name = AxAVTCamera1.GetCameraName(i) CameraList.Items.Add(name) Next
If CameraList.Items.Count > 0 Then CameraList.SelectedIndex = 0 End If
5.4.2 Save an image The picture is stored with a click on a button. The control waits, until the camera supplies the next picture. Then the picture is stored and the appropriate event is released. The application evaluates the parameters of the events and calls a registered application for the displaying of the picture.
Private Sub Button5_Click(ByVal sender As System.Object, ByVal e As 2 System.EventArgs) Handles Button5.Click AxAVTCamera1.SavePicture(“Test.bmp”) End Sub AVT Direct FirePackage Software Manual V2.0.0 61
Private Sub AxAVTCamera1_SavePictureEvent(ByVal sender As Object, ByVal e 2 As AxAVTCameraLib._IAVTCameraEvents_SavePictureEvent) Handles 2 AxAVTCamera1.SavePictureEvent Dim pInfo As New ProcessStartInfo pInfo.FileName = e.file pInfo.UseShellExecute = True Dim p As Process = Process.Start(pInfo) End Sub
5.4.3 Direct buffer access
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As 2 System.EventArgs) Handles MyBase.Load … Me.AxAVTCamera1.SelectCamera(0) Me.AxAVTCamera1.BufferAccess = True …
Private Sub AxAVTCamera1_SaveOk(ByVal sender As Object, ByVal e As 2 System.EventArgs) Handles AxAVTCamera1.SaveOk ‘ if you try to access the buffer in this event, it's a bad idea ' because the next event can come quickly ' and the framework mix the parameters of the events ' so you get something strange with the Marshal interface...
Console.WriteLine("SaveOk") Me.Button5.Enabled = True End Sub
AVT Direct FirePackage Software Manual V2.0.0 62
Private Sub Button5_Click(ByVal sender As System.Object, ByVal e As 2 System.EventArgs) Handles Button5.Click ' the pointer to the buffer for ' the picture data (BGR) ' the bitmap header ' the bitmap file header Dim picBuffer As System.IntPtr Dim headerBuffer As System.IntPtr Dim fileBuffer As System.IntPtr
' the size of buffers Dim picLen As Integer Dim headerLen As Integer Dim fileLen As Integer
' get the size picLen = Me.AxAVTCamera1.GetBufferSize() headerLen = Me.AxAVTCamera1.GetBitmapHeaderSize() fileLen = Me.AxAVTCamera1.GetBitmapFileHeaderSize()
'reserve the own buffers Dim myPicBuffer(picLen) As Byte Dim myHeaderBuffer(headerLen) As Byte Dim myFileBuffer(fileLen) As Byte
' get the buffers picBuffer = Me.AxAVTCamera1.GetBuffer() headerBuffer = Me.AxAVTCamera1.GetBitmapHeader() fileBuffer = Me.AxAVTCamera1.GetBitmapFileHeader()
' is the pointer valid ? If picBuffer.ToInt32() <> 0 Then ' copy the data in a way, ' unmanaged code can understand it
AVT Direct FirePackage Software Manual V2.0.0 63
' I love the Marshal Class:
Marshal.Copy(picBuffer, myPicBuffer, 0, picLen)
' never forget to free the buffer!
Marshal.FreeCoTaskMem(picBuffer) End If
' same procedure as... If headerBuffer.ToInt32() <> 0 Then Marshal.Copy(headerBuffer,myHeaderBuffer,0,headerLen) Marshal.FreeCoTaskMem(headerBuffer) End If
' ... If fileBuffer.ToInt32() <> 0 Then Marshal.Copy(fileBuffer, myFileBuffer, 0, fileLen) Marshal.FreeCoTaskMem(fileBuffer) End If
' open a file Dim fs As New FileStream("temp.bmp", FileMode.Create) Dim w As New BinaryWriter(fs)
' and write the buffer ' (if you forget the len parameter, VB add a 0), so... w.Write(myFileBuffer, 0, fileLen) w.Write(myHeaderBuffer, 0, headerLen) w.Write(myPicBuffer, 0, picLen)
' and close it w.Close() fs.Close() End Sub
AVT Direct FirePackage Software Manual V2.0.0 64
5.4.4 Sample projects The following sample projects are installed by the package:
C:\..\Allied Vision Technologies\Direct FirePackage\avtcamerademo
A VB.NET Sample, which shows basic examples, like selection of a camera, show property pages, save a picture and build an own format dialog.
AVT Direct FirePackage Software Manual V2.0.0 65
C:\..\Allied Vision Technologies\Direct FirePackage\avtcamerademo6
A VB6 project that shows the same features.
AVT Direct FirePackage Software Manual V2.0.0 66
C:\..\Allied Vision Technologies\Direct FirePackage\ avtcamerademohtml
Makes clear the usage of the control in a HTML and scripting environment:
C:\..\Allied Vision Technologies\DirectFire Package\pictureaccess
This VB.NET sample shows basic functions of direct register access:
AVT Direct FirePackage Software Manual V2.0.0 67