/*!

\page index C++ interface reference

\xmlonly
<mvWrapperDoc><htmlinclude ref="code_fragment_start_cpp.html"/></mvWrapperDoc>
\endxmlonly
\htmlinclude code_fragment_start_cpp.html

This is the documentation for developers who want to work with the C++ interface of the driver. It is based on the C Interface but provides a more convenient and object orientated approach to properties and functions offered by the driver.

The complete C++ part of the interface is provided in source. This has some advantages:

- This interface works for every C++ compiler
- The C++ wrapper might act as help for programmer coming from other languages(e.g. Delphi) when writing their own wrappers
- The user can step through this part of the code

\htmlinclude code_fragment_end.html
\xmlonly
<mvWrapperDoc><htmlinclude ref="code_fragment_end.html"/></mvWrapperDoc>
\endxmlonly
\section Overview Overview

Every program written using this interface will start in one or the other form with creating an instance of the class <b>mvIMPACT::acquire::DeviceManager</b>. Each application needs at least one instance of this class while devices shall be accessed. To find out how to gain access to a certain device look at the detailed description of this class.

Once a pointer(or in other words: access) to the desired device represented by an instance of the class <b>mvIMPACT::acquire::Device</b> has been obtained every other device related properties or functions can be accessed.

\note
When the last instance to objects of the class <b>mvIMPACT::acquire::DeviceManager</b> is destroyed, every device pointer or handle to interface properties will become invalid automatically, as the destructor of the device manager decrements an internal usage counter, that automatically closes all devices and frees allocated resources, once this usage counter reaches 0. So make sure there is always at least one instance of the device manager present in your application.

Some source code samples how to locate a certain <b>mvIMPACT::acquire::Device</b> also can be found in the detailed description of the device manager class.

\section GettingStarted Getting started

To capture an image an instance of the class <b>mvIMPACT::acquire::FunctionInterface</b> is needed as well. This class can be constructed by passing a pointer to the <b>mvIMPACT::acquire::Device</b> object obtained from the <b>mvIMPACT::acquire::DeviceManager</b> to the class constructor.

The function interface class provides access to most of the devices executable functions, while most of the settings (e.g. the exposure time or the trigger mode) are implemented as properties (<b>mvIMPACT::acquire::Property</b>).

Getting the first image might e.g. look like that:

\xmlonly
<mvWrapperDoc><htmlinclude ref="code_fragment_start_cpp.html"/></mvWrapperDoc>
\endxmlonly
\htmlinclude code_fragment_start_cpp.html
\code
//-----------------------------------------------------------------------------
int main(int argc, char* argv[])
//-----------------------------------------------------------------------------
{
	mvIMPACT::acquire::DeviceManager devMgr;
	if( devMgr.deviceCount() == 0 )
	{
		cout << "No MATRIX VISION device found! Unable to continue!" << endl;
		char ch = getch();
		return 0;
	}

	cout << "Initialising the device. This might take some time..." << endl;
	// create an interface to the first MATRIX VISION device found
	mvIMPACT::acquire::Device* pDev = devMgr[0];
	try
	{
		pDev->open();
	}
	catch(mvIMPACT::acquire::ImpactAcquireException& e )
	{
		// this e.g. might happen if the same device is already opened in another process...
		cout << "An error occurred while opening the device(error code: " << e.errCode() << "). Press any key to end the application..." << endl;
		char ch = getch();
		return 0;
	}

	mvIMPACT::acquire::FunctionInterface fi( pDev );

	// make sure there is at least 1 request to capture an image
	// requests are structures containing information for the driver how to capture an image
	// and return information about the image back to user when the image has been captured
	fi.ensureRequests(1);

	// send a request to the default request queue of the device and wait for the result.
	fi.imageRequestSingle();
	const int maxWaitTime_ms = 500;
	// wait for results from the default capture queue
	int requestNr = fi.imageRequestWaitFor( maxWaitTime_ms );

	// check if the image has been captured without any problems
	if( !fi.isRequestNrValid( requestNr ) )
	{
		// this can not happen in this sample, but may happen if you wait for a request without
		// sending one to the driver before
		cout << "ERROR! No request has been sent to the driver." << endl;
		return 0;
	}

	const mvIMPACT::acquire::Request* pRequest = fi.getRequest(requestNr);
	if( !fi.isRequestOK( pRequest ) )
	{
		cout << "ERROR! Code " << pRequest->getResult().result << endl;
		return 0;
	}

	// everything went well. Do whatever you like with the result
	const mvIMPACT::acquire::ImageBuffer& ib = pRequest->getImageBuffer();
	// unlock the buffer to let the driver know that you no longer need this buffer
	fi.imageRequestUnlock( requestNr );
	return 0;
}
\endcode
\htmlinclude code_fragment_end.html
\xmlonly
<mvWrapperDoc><htmlinclude ref="code_fragment_end.html"/></mvWrapperDoc>
\endxmlonly

This sample contains everything the user needs to do to capture one image including all initialisation work and error handling for every source of error one can thing of. 

Several sample applications will provide an even better understanding of the interface.

\section WorkingWithProperties Working with properties

As mentioned before, most of the settings available are implemented as properties rather then as functions. A growing collection of classes provide access to properties, which can be read and some of them set by the user. All objects which grant access to device driver interface properties will require the pointer to the <b>mvIMPACT::acquire::Device</b> acquired from a <b>mvIMPACT::acquire::DeviceManager</b> object again.

\note
It is not necessary to call <b>mvIMPACT::acquire::Device::open</b> before creating objects requiring a pointer to a device object, but each constructor accepting such a pointer will need the device to be opened, so the first object constructed from a pointer to a closed <b>mvIMPACT::acquire::Device</b> object will try to initialise the device, which is why the first constructor call might take some time.

\note
If for some reason the device can't be initialised, an exception might be thrown by any of those constructors.

Objects the user can create to modify or read <b>mvIMPACT::acquire::Property</b> values include(among other):

\if BUILD_MVGRABBER_DOCUMENTATION

<table width="100%">
<tr>
  <th>Name of the class</th>
  <th>Description</th>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::CameraSettingsFrameGrabber</b></td>
  <td>A collection of camera related settings. Please note that device specific classes derived from this class might offer more features</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::ImageDestination</b></td>
  <td>Properties to control the destination format of the image</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::ImageProcessing</b></td>
  <td>Various properties and methods to process the image before transmitted to the user</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::Settings</b></td>
  <td>A combination of the three classes mentioned above</td></td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::InfoFrameGrabber</b></td>
  <td>General information about the device and the driver</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::IOSubSystemFrameGrabber</b></td>
  <td>Provides access to the digital I/Os of the device and to real time control machines if available</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::StatisticsFrameGrabber</b></td>
  <td>Provides access to statistical information like the current frames per second</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::SystemSettings</b></td>
  <td>Provides access to settings controlling the overall behaviour of the driver</td>
</tr>
</table>

\elseif BUILD_MVBLUEFOX_DOCUMENTATION

<table width="100%">
<tr>
  <th>Name of the class</th>
  <th>Description</th>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::CameraSettingsBlueFOX</b></td>
  <td>A collection of camera related settings. Please note that device specific classes derived from this class might offer more features</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::ImageDestination</b></td>
  <td>Properties to control the destination format of the image</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::ImageProcessingBlueFOX</b></td>
  <td>Various properties and methods to process the image before transmitted to the user</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::SettingsBlueFOX</b></td>
  <td>A combination of the three classes mentioned above</td></td>
<tr>
  <td><b>mvIMPACT::acquire::InfoBlueFOX</b></td>
  <td>General information about the device and the driver</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::IOSubSystemBlueFOX</b></td>
  <td>Provides access to the digital I/Os of the device and to real time control machines if available</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::StatisticsBlueFOX</b></td>
  <td>Provides access to statistical information like the current frames per second</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::SystemSettings</b></td>
  <td>Provides access to settings controlling the overall behaviour of the driver</td>
</tr>
</table>

\else

<table width="100%">
<tr>
  <th>Name of the class</th>
  <th>Description</th>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::CameraSettingsBase</b></td>
  <td>A collection of camera related settings. Please note that device specific classes derived from this class might offer more features</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::ImageDestination</b></td>
  <td>Properties to control the destination format of the image</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::ImageProcessing</b></td>
  <td>Various properties and methods to process the image before transmitted to the user</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::Settings</b></td>
  <td>A combination of the three classes mentioned above</td></td>
<tr>
  <td><b>mvIMPACT::acquire::Info</b></td>
  <td>General information about the device and the driver</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::IOSubSystem</b></td>
  <td>Provides access to the digital I/Os of the device and to real time control machines if available</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::Statistics</b></td>
  <td>Provides access to statistical information like the current frames per second</td>
</tr>
<tr>
  <td><b>mvIMPACT::acquire::SystemSettings</b></td>
  <td>Provides access to settings controlling the overall behaviour of the driver</td>
</tr>
</table>

\endif

\if BUILD_MVGRABBER_DOCUMENTATION
<div class="qindex">< prev. section: \ref Working_with_camera_descriptions | \ref index "top" | next section: \ref ExampleApplications_page_0 ></div>
\elseif BUILD_MVBLUEFOX_DOCUMENTATION
<div class="qindex">< prev. section: \ref ImageAcquisition_section_settings | \ref index "top" | next section: \ref ExampleApplications_page_0 ></div>
\elseif BUILD_MVBLUECOUGAR_DOCUMENTATION
<div class="qindex">< prev. section: \ref ImageAcquisition_section_settings | \ref index "top" | next section: \ref ExampleApplications_page_0 ></div>
\endif

*/

/*!

\page Logging Logging

This section contains a detailed explaination how the log output for mvIMPACT Acquire devices is configured and how it works in general.

It's not necessary to understand all the details in this chapter, as the configuration of the log-output can be achieved easily using <b>mvDeviceConfigure</b>. So those who just need to configure the log output for a certain device can skip the next section and jump directly to the section \ref ConfigureLogOutputWith_mvDeviceConfigure.

The key to all *.log-output is a parameter file called \a 'mvDebugFlags.mvd'. This file under Windows&reg; will be installed to <b>'%ALLUSERS%\\Documents\\MATRIX VISION\\mvIMPACT Acquire\\Logs'</b> whenever a device driver is installed. Under Windows&reg; this is the one and only location, where this file can be located. Otherwise no log-files will be created. Under Linux this file should be in the current working directory.

The file itself is an <b>XML</b> file containing sections for each library and each device the user wants to get *.log output from.

The first line in this file should be the <b>XML</b> declaration and therefore will look somehow like this:

\code
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>
\endcode

To form a well formed and valid <b>XML</b> document a root item must be introduced. For this file it will be a tag call \a DebugWriterList. The simplest structure this file can have therefore will be something like this:

\code
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>
<DebugWriterList>
</DebugWriterList>
\endcode

Within this root item an arbitrary number of log sections (tag name: \a DebugWriter ) can be placed. All other <b>XML</b> tags will be ignored.

The <b>D</b>ocument <b>T</b>ype <b>D</b>escription (<b>DTD</b>) for this file therefore can roughly be expressed like this:

\code
<!DOCTYPE DebugWriterList [
  <!ELEMENT DebugWriterList (DebugWriter*)>
  <!ELEMENT DebugWriter (#PCDATA)>
]>
\endcode

\section LogSection Log sections

One log section in the \a *.mvd-file looks more or less like this:

\code
<DebugWriter name="mvDeviceManager" flags="01111111" outputmask="110" outputfile="STDLOGDIR\mvDeviceManager.xml" clearFile="1"></DebugWriter>
\endcode

A complete parameter file to define and configure *.log output for a certain module therefore could look like this:

\code
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>
<DebugWriterList>
  <DebugWriter name="mvDeviceManager" flags="01111111" outputmask="110" outputfile="STDLOGDIR\mvDeviceManager.xml" clearFile="1"></DebugWriter>
</DebugWriterList>
\endcode

The meaning of the individual attributes will be explained in the following sub sections.

The order of appearance of the attributes is not defined and not all attributes are required. The following sample will all be valid *.log-configuration:

\code
<DebugWriterList>
  <DebugWriter name=" mvSampleDevice666" flags="01111100" outputmask="100" outputfile="STDLOGDIR/mvSampleDevice" clearFile="1"></DebugWriter>
  <DebugWriter flags="01111100" outputmask="100" name=" mvSampleDevice667" outputfile="STDLOGDIR/mvSampleDevice"></DebugWriter>
  <DebugWriter outputfile="STDLOGDIR/mvSampleDevice668" name=" mvSampleDevice668" flags="01111100" clearFile="1"></DebugWriter>
  <DebugWriter outputfile="STDLOGDIR/mvSampleDevice668" name=" mvSampleDevice668" flags="01111100" clearFile="1" stylesheet="none" ></DebugWriter>
  <DebugWriter outputfile="STDLOGDIR/mvSampleDevice668" name=" mvSampleDevice668" flags="01111100" clearFile="1" stylesheet="myStyleSheet.xsl" ></DebugWriter>
  <DebugWriter flags="01111100" outputmask="010" name=" mvSampleDevice669"></DebugWriter>
</DebugWriterList>
\endcode

\note
As it can be seen it the sample from above several devices / log configurations can use the same file to send their messages to.

The complete DTD for log configuration files looks like this:

\code
<!DOCTYPE DebugWriterList [
  <!ELEMENT DebugWriterList (DebugWriter*)>
  <!ELEMENT DebugWriter (#PCDATA)>
  <!ATTLIST DebugWriter 
    name CDATA #REQUIRED
    flags CDATA #REQUIRED
    outputmask CDATA "010"
    outputfile CDATA #IMPLIED
    clearFile CDATA "1"
    stylesheet CDATA "mvIMPACT_acquireLogFile.xsl"
  >
]>
\endcode

\subsection nameAttr property 'name'

The \a name property is the name of the library(without extension) or the device for which *.log-output shall be generated. In this case it's the <b>mvDeviceManager</b> library. For devices the name will build from the value of the property 'Family' in the device list and the current device ID. So e.g. \a mvSampleDevice666 would specify the log-section for a device belonging to the product family group \a mvSampleDevice and has been assigned a device ID of 666. In the parameter file the corresponding section would look somehow like this:

\code
<DebugWriter name="mvSampleDevice666" flags="01111111" outputmask="110" outputfile="STDLOGDIR\mvSampleDevice666" clearFile="1"></DebugWriter>
\endcode

\note
<b>This attribute is required.</b>

\subsection flagsAttr property 'flags'

The \a flags property is a string containing either \a 0 or \a 1 for each type of log message while \a 0 means that this *.log-messages will <b>NOT</b> be written to the log output and \a 1 that the messages will be send to the log output.

From right to left the numbers have the following meaning:

- information (these type of messages will only be available in debug builds)
- important information (these type of messages will only be available in debug builds)
- warning
- error
- fatal error
- log message
- general purpose

So something like this: \a flags="001110" will result in messages internally classified as <b>important information</b> (first \a '1' from the right), <b>warning</b> (2nd \a '1' from the right) or <b>error</b> to be send to the output.

\note
<b>This attribute is required.</b>

\subsection outputMaskAttr property 'outputmask'

Log messages can be send to multiple destinations. where the output will be send to can be defined by the property \a 'outputmask'. It contains three digits (either \a '0' or \a '1') to activate certain destinations. The rightmost digit defines the systems standard output, the digit in the middle the systems standard debug output and the digit on the left a file.

From right to left the flags have the following meaning:

- system standard output
- system debug output
- file

So \a outputmask="110" results in log messages to be send to the systems standard debug output <b>AND</b> a file while \a outputmask="001" would send the log messages to the systems standard output only.

\note
<b>This attribute is optional. If omitted messages will only be send to the system debug output</b>

\subsection outputFileAttr property 'outputfile'

If log messages shall be send to a file, this property should contain the name of the output file.

If the name of the output file starts with <b>STDLOGDIR</b> then the file will be created in the same folder where the file \a 'mvDebugFlags.mvd' is located after the installation.

So \a outputfile="STDLOGDIR\\mvDeviceManager.xml" und Windows&reg; will send all log messages to <b>%ALLUSERS%\\Documents\\MATRIX VISION\\mvIMPACT Acquire\\Logs</b>, while under Linux the current working directory will be used.

Once a device has been initialised the name and the full path to the log file can be obtained by reading the value of the property <b>mvIMPACT::acquire::InfoBase::logFile</b>.

\note
It is <b>NOT</b> necessary to specify the file extension \a .xml explicitly. If the file name does not end with \a .xml it will be appended automatically. This however implies, that only the *.xml format is currently supported and later will be the default.

\note
<b>This attribute is optional. If omitted no messages will be send to a file and no file will be created.</b>

\subsection clearFileAttr property 'clearFile'

Defines if new information is appended at the end of an existing file from a previous session (\a '0' ), or if a new file shall be created for each session (\a '1' ) overwriting existing files.

\note
The term \a session means the time the device drivers library is in process memory, which might be longer then the time the device is actually initialised. To remove a device driver from process memory, the device manager must be closed.

\note
Appending to existing files is slow and might produce very large files when used over a long period of time which might affect the overall performance of the system. So using the append feature is an option, but it is <b>NOT recommend</b>. Only use it if necessary!

\note
<b>This attribute is optional. If omitted existing files will be overwritten.</b>

\subsection stylesheetAttr property 'stylesheet'

Defines if a stylesheet shall be embedded into the log-file. If no stylesheet shall be referenced by the resulting log-file this property must be set to \a 'none'. Otherwise this property defines the name of the stylesheet file that will later be used to transform the log-file into the desired output format.

\note
<b>This attribute is optional. If omitted the standard stylesheet 'mvIMPACT_acquireLogFile.xsl' will be embedded in the *.log-file. This stylesheet is part of the installation and will be installed to the same directory as the *.mvd-file</b>

\section ConfigureLogOutputWith_mvDeviceConfigure Configure the log output using mvDeviceConfigure

To start the dialog allowing the log output configuration for certain devices and modules belonging to the driver the menu item <b>'Configure log output'</b> must be selected from the <b>Action</b> menu of <b>mvDeviceConfigure</b>.

Afterwards an initially empty list will be displayed together with some general information in the lower part of the screen. In order to modify an existing log configuration press the \a Load... button and select the file containing the configuration to be modified.

\image html mvDevConf_OpenLogConfigFile.png
<center>Figure 1: mvDeviceConfigure - Opening an existing configuration file </center>

\note
Under Windows&reg; the file, that is evaluated a runtime <b>MUST</b> be stored under <b>%ALLUSERS%\\Documents\\MATRIX VISION\\mvIMPACT Acquire\\Logs</b>, while under Linux the current working directory will be used. The name of the file <b>MUST</b> be \a mvDebugFlags.mvd.

Afterwards the interpreted content of the file will be displayed in the list control in the upper part of the screen:

\image html mvDevConf_AfterFileLoad.png
<center>Figure 2: mvDeviceConfigure - The default log output configuration </center>

The columns have the following meaning:

\subsection SectionName section name

This is the name of the logger as later used by the driver. These is either a library name, a device family name or a device family name directly followed by a device ID. The <b>mvIMPACT Acquire</b> interface consists more or less of 2 device indepentdent libraries (mvPropHandling and mvDeviceManager) and a device specific library for each device family (e.g. mvBlueFOX). A <b>mvBlueFOX</b> with a device ID 0 therefore would be configured by a section called \a mvBlueFOX0.

\subsection DevicesUsingThisSection devices using this section

This column contains information about the devices, that will later write log messages based on this section. The general device family specific section e.g. will be used by any device belonging to that family whenever general information needs to be written, that does not use the device specific section. The information will be generated based on the devices detected in the current system.

\subsection flagsToAlwaysClearFile flags, output destinations, output file name, 'always clear file' and 'stylesheet'

These sections contain information for the driver how, to which location and which information needs to be send to the log output. They are described in detail in the section explaining the XML file format for the *.mvd file.

\subsection Configuration configuration

Now e.g. to setup log output for an <b>mvBlueFOX</b> device with a device ID '0' right click on the corresponding list entry an select \a Configure \a item from the popup menu.

This will result in the following dialog:

\image html mvDevConf_LogOutputConfig.png
<center>Figure 3: mvDeviceConfigure - log output configuration </center>

Here the user can configure the way the log output shall be generated. When this dialog is ended by pressing the <b>OK</b> button the changes will be applied to the list of configurations.

\subsection AddNewConfiguration adding a new configuration

When a new configuration shall be generated for one or more devices this can be done by right-clicking on the empty list control and then selecting 'Insert item' from the popup menu. The application then will display a list of log configurations that haven't been configured so far based on the devices detected in the system. If the device so far is not present in the system or the configuration shall be created for another system select 'User defined'. Please don't forget to name the section correctly as described in the sub section 'section name'.

\image html mvDevConf_AddConfig.png
<center>Figure 4: mvDeviceConfigure - adding a new log configuration</center>

<div class="qindex">< prev. section: \ref Porting_page_Current | \ref Logging "top" | next section: <a class="el" href="../InstallationFromPrivateSetupRoutines.html">Installation from private setup routines</a> ></div>

*/

/*!
\if BUILD_MVGRABBER_DOCUMENTATION
\page Working_with_camera_descriptions Working with camera descriptions

Certain capture device (e.g. frame grabber) can process data from a wide range of imaging devices (e.g. cameras). However in order to interpret the incoming data from an imaging device correctly, the capture device needs to be given a certain amount of information about the structure of the video signal.

The <b>mvIMPACT Acquire</b> interface addresses this necessity by the introduction of so called <i>camera descriptions</i>. A <i>camera description</i> is a certain set of parameters that should enable the capture device to cope with the incoming image data to reconstruct a correct image from the imaging device in the memory of the host system. For instance this information may contain information whether the image is transmitted as a whole or if it's transmitted as individual blocks (e.g. when dealing with interlaced cameras) that need to be reconstructed in a certain way to form the complete image.

Each capture device will support different sets of parameters. For example some capture devices will only be able to capture image data from standard video source such as a <b>PAL</b> or <b>NTSC</b> compliant camera, while others might only be capable to acquire data from digital image sources such as <b>CameraLink&reg;</b> compliant cameras. To reflect these device specific capabilities the <i>camera descriptions</i> have been grouped into different base classes. See <b>mvIMPACT::acquire::CameraDescriptionBase</b> and derived classes to find out how the basic structure of these objects look. Which basic <i>camera description</i> classes are supported by an individual device can be seen directly after the device has been initialised by creating and instance of <b>mvIMPACT::acquire::CameraDescriptionManager</b>. These objects will contain different lists for each camera class. One or more of this lists might be empty for a device, which indicates, that this device doesn't support this particular group of descriptions. 

\note
For devices that don't support camera descriptions at all, creating an instance of <b>mvIMPACT::acquire::CameraDescriptionManager</b> will raise an exception, that should be handled appropriately.

To select a certain camera description to be used to prepare the capture device for the expected data the property <b>mvIMPACT::acquire::CameraSettingsFrameGrabber::type</b> can be modified. It's translation dictionary (e.g. see <b>mvIMPACT::acquire::EnumPropertyI::getTranslationDictString</b>) will contain every camera description currently available.

\section CreateANewCameraDescription Create a new camera description

Now when a camera is connected, that differs in one or more parameters from the default offered by one of the available base classes and no special description for the imaging device in question is available a new matching description must be generated.

\note
It's also possible to modify one of the standard descriptions to adapt the parameter set to the used imaging device, but this method is not recommend as this would define something to be 'standard', which in fact is not. Therefore it is not possible to store the standard descriptions permanently. It is however possible to modify and work with the changed parameters, but these changes will be lost once the device is closed.

The recommended way of adapting an imaging source to a capture device is to create a new description for a imaging device that does not completely fall into one of the offered standard descriptions. The first thing to decide when creating a new camera description is to which existing description offers the closest match for the new description. Once this has been decided a copy of this description can be created with an arbitrary name(that must be unique within the family the description is created from). 

\note
For an example how to create a new camera description see the description of <b>mvIMPACT::acquire::CameraDescriptionBase</b>.

Afterwards the newly created camera description will be added to the list of existing ones. It will therefore be available via the instance of <b>mvIMPACT::acquire::CameraDescriptionManager</b> and also selectable via <b>mvIMPACT::acquire::CameraSettingsFrameGrabber::type</b> It's parameters at this point will match the <i>parent</i> description(the one the function <b>mvIMPACT::acquire::CameraDescriptionBase::copyDescription</b> was executed from) completely.

Now the reason for creating a new camera description was that the parameters in the existing description didn't exactly match the connected imaging device. Therefore the next step would probably be to modify some of the parameters. 

\section StoringCameraDescriptions Storing camera descriptions

\note
A new camera description will <b>NOT</b> be stored permanently by default. In order to make this description available the next time the capture device is initialised, the newly created description must be exported via a function call.

To store a camera description permanently the function <b>mvIMPACT::acquire::CameraDescriptionBase::exportDescription</b> of the new camera description must be invoked. 

As a direct result the modified settings will become the new default values of this particular camera description. 
 
\note
Please note, that this will <b>NOT</b> work for one of the standard camera descriptions. Whenever the user tries to export one of these, the error <b>mvIMPACT::acquire::TDMR_ERROR::DMR_EXECUTION_PROHIBITED</b> will be returned. This is to reflect the fact, that a standard can't be manually modified. This must <b>ALWAYS</b> be done by creating a new description.

When exporting a camera description a file in XML format will be written to disc. Under Windows&reg; camera descriptions will be stored under <b>%ALLUSERS%\\Documents\\MATRIX VISION\\mvIMPACT Acquire\\CameraFiles</b> while under other platforms these files will end up in the current working directory.

Now when closing and re-opening a device only the default camera descriptions an the one selected before settings have been saved will appear in the list of camera descriptions of an instance of <b>mvIMPACT::acquire::CameraDescriptionManager</b>. This is to save memory. However all detected camera descriptions will be available via the property <b>mvIMPACT::acquire::CameraSettingsFrameGrabber::type</b>

Once a description is selected, that hasn't been in the list of camera descriptions before, it will be created and thus will become available for modifications again via the class <b>mvIMPACT::acquire::CameraDescriptionManager</b>. 

Again: For a different camera a new description should be generated, to operate complex cameras in different modes, a either a new description can be generated or an existing one can be modified.

After a camera has been modified the function <b>mvIMPACT::acquire::CameraDescriptionBase::importDescription</b> can be used to fall back to the values stored in the camera description file. This will restore the default settings for this description. The function <b>mvIMPACT::acquire::ComponentCollection::restoreDefault</b> does serve the same purpose, but will work for default descriptions as well.

\section PropertyInteraction Property interaction

Certain properties will affect other properties depending on the value written to the property. This section is meant to help to answer some of the questions, that might arise from this behaviour.

<b>mvIMPACT::acquire::CameraSettingsFrameGrabber::acquisitionField</b> <-> <b>mvIMPACT::acquire::CameraDescriptionStandardBase::startField</b>:

While <b>mvIMPACT::acquire::CameraSettingsFrameGrabber::acquisitionField</b> is set to <b>mvIMPACT::acquire::TAcquisitionField::afAuto</b> the field selected in the property <b>mvIMPACT::acquire::CameraDescriptionStandardBase::startField</b> will be used to trigger the acquisition.

<b>mvIMPACT::acquire::CameraSettingsFrameGrabber::interlacedMode</b> <-> <b>mvIMPACT::acquire::CameraDescriptionNonStandard::interlacedType</b>:

When the latter property is set to <b>mvIMPACT::acquire::TCameraInterlacedType::citNone</b> the property <b>mvIMPACT::acquire::CameraSettingsFrameGrabber::interlacedMode</b> will be invisible, as it doesn't make sense to define how an interlaced signal has to be reconstructed if no interlaced signal is present.

If <b>mvIMPACT::acquire::CameraDescriptionNonStandard::interlacedType</b> is set either to <b>mvIMPACT::acquire::TCameraInterlacedType::citInterlaced</b> or <b>mvIMPACT::acquire::TCameraInterlacedType::citInvertedInterlaced</b>, <b>mvIMPACT::acquire::CameraSettingsFrameGrabber::interlacedMode</b> can be used to define whether the resulting image shall be reconstructed from the odd and even frame of the interlaced signal (<b>mvIMPACT::acquire::CameraSettingsFrameGrabber::interlacedMode</b> then must be set to <b>mvIMPACT::acquire::TInterlacedMode::imOn</b>) or if the single fields shall be treated as individual images (<b>mvIMPACT::acquire::CameraSettingsFrameGrabber::interlacedMode</b> then must be set to <b>mvIMPACT::acquire::TInterlacedMode::imOff</b>).

In the latter situation either just one particular field (either odd or even) or every field can be captured. This again can be defined via the two properties <b>mvIMPACT::acquire::CameraSettingsFrameGrabber::acquisitionField</b> and <b>mvIMPACT::acquire::CameraDescriptionStandardBase::startField</b>. The following table will show the behaviour for a camera signal depending on these selections:

\htmlonly
<table width="100%">
<tr>
  <td class="header" width="20%">Value of &quot;interlacedType&quot;</td>
  <td class="header" width="10%">Value of &quot;interlacedMode&quot;</td>
  <td class="header" width="20%">Value of &quot;acquisitionField&quot;</td>
  <td class="header" width="10%">Value of &quot;startField&quot;</td>  
  <td class="header" width="40%">Result of this setting / behaviour</td>
</tr>
<tr>
  <td class="indexvalue">citNone</td>
  <td class="indexvalue">no influence(will be invisible)</td>
  <td class="indexvalue">no influence(will be invisible)</td>
  <td class="indexvalue">no influence</td>
  <td class="indexvalue"><b>interlaced video sources</b>:<br>all fields will be treated like individual images no matter whether it's an odd or even field.<br><br><b>non-interlaced video sources</b>:<br>Here we are just dealing with full frames thus every frame will be captured.</td>
</tr>
<tr>
  <td class="indexvalue">citInterlaced or citInvertedInterlaced</td>
  <td class="indexvalue">imOn</td>
  <td class="indexvalue">no influence(will be invisible)</td>
  <td class="indexvalue">afEven</td>
  <td class="indexvalue">full images merged from one even and one odd field will be captured. The acquisition will start with the next detected even field after an image has been requested.</td>
</tr>
<tr>
  <td class="indexvalue">citInterlaced or citInvertedInterlaced</td>
  <td class="indexvalue">imOn</td>
  <td class="indexvalue">no influence(will be invisible)</td>
  <td class="indexvalue">afOdd</td>
  <td class="indexvalue">full images merged from one even and one odd field will be captured. The acquisition will start with the next detected odd field after an image has been requested.</td>
</tr>
<tr>
  <td class="indexvalue">citInterlaced or citInvertedInterlaced</td>
  <td class="indexvalue">imOn</td>
  <td class="indexvalue">no influence(will be invisible)</td>
  <td class="indexvalue">afAny</td>
  <td class="indexvalue">full images merged from one even and one odd field will be captured. The acquisition will start with the next detected field after an image has been requested.</td>
</tr>
<tr>
  <td class="indexvalue">citInterlaced or citInvertedInterlaced</td>
  <td class="indexvalue">imOff</td>
  <td class="indexvalue">afAuto (the value of &quot;startField&quot; will be used)</td>
  <td class="indexvalue">afEven</td>
  <td class="indexvalue" rowspan="2">Only even fields will be captured. These will be treated as individual images.</td>
</tr>
<tr>
  <td class="indexvalue">citInterlaced or citInvertedInterlaced</td>
  <td class="indexvalue">imOff</td>
  <td class="indexvalue">afEven</td>
  <td class="indexvalue">no influence</td>
</tr>
<tr>
  <td class="indexvalue">citInterlaced or citInvertedInterlaced</td>
  <td class="indexvalue">imOff</td>
  <td class="indexvalue">afAuto (the value of &quot;startField&quot; will be used)</td>
  <td class="indexvalue">afOdd</td>
  <td class="indexvalue" rowspan="2">Only odd fields will be captured. These will be treated as individual images.</td>
</tr>
<tr>
  <td class="indexvalue">citInterlaced or citInvertedInterlaced</td>
  <td class="indexvalue">imOff</td>
  <td class="indexvalue">afOdd</td>
  <td class="indexvalue">no influence</td>
</tr>
<tr>
  <td class="indexvalue">citInterlaced or citInvertedInterlaced</td>
  <td class="indexvalue">imOff</td>
  <td class="indexvalue">afAuto (the value of &quot;startField&quot; will be used)</td>
  <td class="indexvalue">afAny</td>
  <td class="indexvalue" rowspan="2">all fields will be captured and treated like individual images (alternating odd and even).</td>
</tr>
<tr>
  <td class="indexvalue">citInterlaced or citInvertedInterlaced</td>
  <td class="indexvalue">imOff</td>
  <td class="indexvalue">afAny</td>
  <td class="indexvalue">afAny</td>
</tr>
</table>
\endhtmlonly

<div class="qindex">< prev. section: \ref ImageAcquisition_page_settings | \ref Working_with_camera_descriptions "top" | next section: <a class="el" href="index.html">C++ interface reference</a> ></div>
\endif
*/
