Contains information about a captured buffer. More...

#include <mvIMPACT_acquire.h>

Public Member Functions
int	attachUserBuffer (void *pBuf, int bufSize)
	Convenience function to attach a user supplied buffer to a mvIMPACT::acquire::Request object.

int	configure (void)
	Sets a request into configuration mode.

int	detachUserBuffer (void)
	Convenience function to detach a user supplied buffer from a mvIMPACT::acquire::Request object.

BufferPart &	getBufferPart (unsigned int index) const
	Returns a reference to a buffer part descriptor of this request.

unsigned int	getBufferPartCount (void) const
	Returns the number of buffer parts currently associated with this request.

unsigned int	getChunkCounterCount (void) const
	Returns the number of counter values that can be returned as part of the additional data of the buffer containing the request data.

PropertyI64	getChunkCounterValue (unsigned int index) const
	Returns a 64 bit integer property (read-only) defining the selected counter value at the time of the internal frame start event for this request.

PropertyF	getChunkGain (const std::string &name) const
	Returns a floating point property (read-only) defining the selected gain value at the time of the internal frame start event for this request.

PropertyF	getChunkGain (unsigned int index) const
	Returns a floating point property (read-only) defining the selected gain value at the time of the internal frame start event for this request.

unsigned int	getChunkGainCount (void) const
	Returns the number of gain values that can be returned as part of the additional data of the buffer containing the request data.

unsigned int	getChunkTimerCount (void) const
	Returns the number of timer values that can be returned as part of the additional data of the buffer containing the request data.

PropertyF	getChunkTimerValue (unsigned int index) const
	Returns a floating point property (read-only) defining the selected timer value at the time of the internal frame start event for this request.

DeviceComponentLocator	getComponentLocator (void) const
	Returns a component locator for this request.

const ImageBufferDesc &	getImageBufferDesc (void) const
	Returns a const reference to the image buffer descriptor of this request.

Component	getImageProcessingResultsIterator (void) const
	Returns an iterator for iterating inside the info/imageProcessingResults list of the request.

mvIMPACT::Image	getIMPACTImage (TImpactBufferFlag flags) const
	Returns an mvIMPACT image buffer representation of the image associated with this request.

mvIMPACT::Image	getIMPACTImage (void) const
	Returns an mvIMPACT image buffer representation of the image associated with this request.

Component	getInfoIterator (void) const
	Returns an iterator for iterating inside the info list of the request.

const std::string &	getName (void) const
	Returns the name associated with this request.

int	getNumber (void) const
	Returns the number associated with this request.

bool	hasProcessingBeenSkipped (void) const
	Checks if image processing that was set up for this request has been skipped for performance reasons.

bool	isOK (void) const
	Convenience function to check if a request has been processed successfully.

Request &	operator= (const Request &rhs)
	Allows assignments of mvIMPACT::acquire::Request objects.

	Request (const Request &src)
	Constructs a new mvIMPACT::acquire::Request from an existing one.

int	save (const std::string &fileName, TImageFileFormat format=iffAuto) const
	Stores the image described by this request into a file.

int	unlock (void)
	Unlocks the request for the driver again.

virtual	~Request ()

Public Attributes
PropertyI64	bufferSizeFilled
	A 64bit integer property (read-only) containing the total amount of data (in bytes) that has been captured during the last capture operation.

PropertyI64	chunkDynamicRangeMax
	A 64 bit integer property (read-only) containing the maximum value of dynamic range of the image as returned in the chunk data attached to the image.

PropertyI64	chunkDynamicRangeMin
	A 64 bit integer property (read-only) containing the minimum value of dynamic range of the image as returned in the chunk data attached to the image.

PropertyF	chunkExposureTime
	A floating point property (read-only) containing the exposure time used to capture the image as returned in the chunk data attached to the image.

PropertyI64	chunkHeight
	A 64 bit integer property (read-only) containing the height of the image in pixels as returned in the chunk data attached to the image.

PropertyI64	chunkLineStatusAll
	A 64 bit integer property (read-only) containing the status of all I/O lines at the time of the internal frame start signal of the image as returned in the chunk data attached to the image.

PropertyI64	chunkmvCustomIdentifier
	A 64 bit integer property (read-only) containing the previously configured user defined identifier attached to the image.

PropertyI64	chunkOffsetX
	A 64 bit integer property (read-only) containing the X-offset of the image in pixels as returned in the chunk data attached to the image.

PropertyI64	chunkOffsetY
	A 64 bit integer property (read-only) containing the Y-offset of the image in pixels as returned in the chunk data attached to the image.

PropertyI64	chunkPixelFormat
	A 64 bit integer property (read-only) containing the pixel format of the image as returned in the chunk data attached to the image.

PropertyI64	chunkSequencerSetActive
	A 64-bit integer property (read-only) containing the index of the active set of the running sequencer use during the creation of this block of data.

PropertyI64	chunkTimestamp
	A 64 bit integer property (read-only) containing the timestamp value of the internal frame start signal of the image as returned in the chunk data attached to the image.

PropertyI64	chunkWidth
	A 64 bit integer property (read-only) containing the width of the image in pixels as returned in the chunk data attached to the image.

PropertyIBayerMosaicParity	imageBayerMosaicParity
	An enumerated integer property (read-only) containing the Bayer parity of this image.

PropertyI	imageBytesPerPixel
	An integer property (read-only) containing the number of bytes per pixel in this image.

PropertyI	imageChannelBitDepth
	An integer property (read-only) containing the number of effective bits stored in each channel belonging to the current image.

PropertyI	imageChannelCount
	An integer property (read-only) containing the number of channels this image consists of.

PropertyS	imageChannelDesc
	A string property (read-only) containing the string descriptors of each channel belonging to the current image.

PropertyI	imageChannelOffset
	An integer property (read-only) containing the offset (in bytes) to each channel belonging to the current image relative to the address contained in mvIMPACT::acquire::Request::imageData.

PropertyPtr	imageData
	A pointer property (read-only) containing the start address of the image data.

PropertyPtr	imageFooter
	A pointer property (read-only) containing the start address of the footer associated with this image.

PropertyI	imageFooterSize
	An integer property (read-only) containing the size (in bytes) of the footer associated with this image.

PropertyI	imageHeight
	An integer property (read-only) containing the height of the image in pixels.

PropertyI	imageHeightTotal
	An integer property (read-only) containing the total height of the image in pixels if this buffer is part of a larger image.

PropertyI	imageLinePitch
	An integer property (read-only) containing the offset (in bytes) to the next line of each channel belonging to the current image.

PropertyIRequestImageMemoryMode	imageMemoryMode
	An enumerated integer property (read-only) containing the memory mode used for this request.

PropertyI	imageOffsetX
	An integer property (read-only) containing the X-offset of the image in pixels.

PropertyI	imageOffsetY
	An integer property (read-only) containing the Y-offset of the image in pixels.

PropertyIImageBufferPixelFormat	imagePixelFormat
	An enumerated integer property (read-only) containing the pixel format of this image.

PropertyI	imagePixelPitch
	An integer property (read-only) containing the offset (in bytes) to the next pixel of the specified channel of this image.

PropertyI	imageSize
	An integer property (read-only) containing the size (in bytes) of the whole image.

PropertyI	imageWidth
	An integer property (read-only) containing the width of the image in pixels.

PropertyI	imageWidthTotal
	An integer property (read-only) containing the total width of the image in pixels if this buffer is part of a larger image.

PropertyICameraOutput	infoCameraOutputUsed
	An enumerated integer property (read-only) containing the camera output used to transmit the image to the capture device.

PropertyI	infoExposeStart_us
	An integer property (read-only) containing a timestamp (in us) defining the time the device started the exposure of the image associated with this mvIMPACT::acquire::Request object.

PropertyI	infoExposeTime_us
	An integer property (read-only) containing the 'real' expose time (in us) used to generate this image.

PropertyI64	infoFrameID
	A 64 bit integer property (read-only) containing a frame identifier.

PropertyI64	infoFrameNr
	A 64 bit integer property (read-only, zero-based) containing the number of image requests processed since this driver instance has been opened.

PropertyF	infoGain_dB
	A float property (read-only) containing the gain(in dB) this image has been taken with.

PropertyF	infoImageAverage
	Currently unsupported.

PropertyI	infoIOStatesAtExposureEnd
	An integer property (read-only) containing the state of all the IO lines at the end of the frame exposure as a device specific bit field.

PropertyI	infoIOStatesAtExposureStart
	An integer property (read-only) containing the state of all the IO lines at the beginning of the frame exposure as a device specific bit field.

PropertyI	infoLineCounter
	An integer property (read-only) containing the number of lines since the last trigger event.

PropertyF	infoMissingData_pc
	A float property (read-only) containing the amount of data missing in the current image.

PropertyI	infoSettingUsed
	A enumerated integer property (read-only) containing the setting that was used for processing this request.

PropertyI64	infoTimeStamp_us
	A 64 bit integer property (read-only) containing a timestamp to define the exact time this image has been captured (usually either at exposure start or exposure end, depending on the device).

PropertyI	infoTransferDelay_us
	An integer property (read-only) containing the time the transaction of this image has been delayed (in us) because either the bus was blocked or the CPU was busy.

PropertyI	infoVideoChannel
	An integer property (read-only) containing the video input channel of the device this image has been acquired from.

PropertyIPayloadType	payloadType
	An enumerated integer property (read-only) defining the payload type of this request.

PropertyIRequestResult	requestResult
	An enumerated integer property (read-only) defining the result of this request.

PropertyIRequestState	requestState
	An enumerated integer property (read-only) defining the current state of this request.

Protected Member Functions
	Request (Device *pDev, int requestNr)

Friends
class	FunctionInterface

Detailed Description

Contains information about a captured buffer.

This class provides access to all sorts of information about the captured buffer. Only Instances of mvIMPACT::acquire::FunctionInterface are allowed to create objects of mvIMPACT::acquire::Request. Consequently the only way to get access to a mvIMPACT::acquire::Request object is via a call to mvIMPACT::acquire::FunctionInterface::getRequest.

A mvIMPACT::acquire::Request represents an object used by the driver to fill its internal job queues. Whenever a buffer shall be captured a mvIMPACT::acquire::Request is sent to the driver and the hardware then tries to capture the desired buffer as fast as possible.

Requests are managed by the driver. The only thing the user needs to configure is the maximum number of requests he wants the driver to work with. To make sure a certain number of requests are available, the property mvIMPACT::acquire::SystemSettings::requestCount can be used. This can be useful for time critical applications where the hardware can capture images in the background while the PC performs other tasks. In that case it's necessary to make sure that the request queue never runs low to ensure lossless data acquisition.

Examples: CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, CaptureToUserMemory.legacy.cpp, ContinuousCapture.linux.cpp, ContinuousCapture.win32.cpp, ContinuousCaptureAllDevices.cpp, ContinuousCaptureAllDevices.linux.cpp, ContinuousCaptureAllDevices.win32.cpp, ContinuousCaptureAllFormats.win32.cpp, ContinuousCaptureMultiPart.legacy.cpp, ContinuousCaptureOnlyProcessLatest.cpp, ContinuousCaptureOnlyProcessLatest.legacy.cpp, ContinuousCaptureToAVIFile.cpp, GenICamCallbackOnEvent.cpp, GenICamCommonSettingsUsage.legacy.cpp, GenICamInterfaceLayout.legacy.cpp, GenICamSequencerParameterChangeAtRuntime.cpp, GenICamSequencerUsage.cpp, GenICamSequencerUsage.legacy.cpp, GenICamSequencerUsageWithPaths.cpp, GenICamSequencerUsageWithPaths.legacy.cpp, GenICamSmartFrameRecallUsage.cpp, GenICamSmartFrameRecallUsage.legacy.cpp, GenericInterfaceLayout.cpp, GenericInterfaceLayout.legacy.cpp, Properties.cpp, Properties.legacy.cpp, SequenceCapture.win32.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, SingleCaptureMasterSlave.legacy.cpp, SingleCaptureStorage.cpp, TimestampFeatures.cpp, and exampleHelper.h.

Constructor & Destructor Documentation

◆ Request() [1/2]

Request	(	Device *	pDev,
		int	requestNr )

inlineexplicitprotected

◆ Request() [2/2]

Request ( const Request & src )

inline

Constructs a new mvIMPACT::acquire::Request from an existing one.

Parameters

[in] src A constant reference to the mvIMPACT::acquire::Request object, this object shall be created from

◆ ~Request()

virtual ~Request ( )

inlinevirtual

Member Function Documentation

◆ attachUserBuffer()

int attachUserBuffer	(	void *	pBuf,
		int	bufSize )

inline

Convenience function to attach a user supplied buffer to a mvIMPACT::acquire::Request object.

This function just provides a nicer way to attach a user supplied buffer to a mvIMPACT::acquire::Request.

It e.g. makes it possible to write code like this:

// 'fi' is assumed to be a valid instance of mvIMPACT::acquire::FunctionInterface,
const Request* pRequest = fi.getRequest( 0 ); // get access to request 0
pRequest->attachUserBuffer( getBufferFromSomewhere(), getBufferSizeFromSomewhere() );

Instead if this:

// 'fi' is assumed to be a valid instance of mvIMPACT::acquire::FunctionInterface,
const Request* pRequest = fi.getRequest( 0 ); // get access to request 0
if( pRequest->configure() == DMR_NO_ERROR )
{
  pRequest->imageMemoryMode.write( rimmUser );
  pRequest->imageData.write( getBufferFromSomewhere() );
  pRequest->imageSize.write( getBufferSizeFromSomewhere() );
  pRequest->unlock();
}

To find out more about capturing to user supplied buffers please refer to the example CaptureToUserMemory.cpp and have a look at the documentation of the function mvIMPACT::acquire::Request::configure.

See also: mvIMPACT::acquire::Request::detachUserBuffer,
mvIMPACT::acquire::FunctionInterface::imageRequestUnlock,
mvIMPACT::acquire::Request::unlock,
mvIMPACT::acquire::FunctionInterface::imageRequestConfigure,
mvIMPACT::acquire::Request::configure

Since: 1.12.68

Returns

mvIMPACT::acquire::DMR_NO_ERROR if successful.
A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Parameters

[in]	pBuf	A pointer to a user supplied buffer
[in]	bufSize	The size of the user supplied buffer

Examples: CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, and CaptureToUserMemory.legacy.cpp.

◆ configure()

int configure ( void )

inline

Sets a request into configuration mode.

In configuration mode certain properties like mvIMPACT::acquire::Request::imageData, mvIMPACT::acquire::Request::imageSize, mvIMPACT::acquire::Request::imageMemoryMode of a request object can be modified. This can be used to configure one or more requests to use a user supplied memory. To use only a subset of the mvIMPACT::acquire::Request objects available the mvIMPACT::acquire::ImageRequestControl::requestToUse feature can be used.

Only requests that are currently not used by the driver and are not locked because they contain image data that hasn't been processed can be set into configuration mode.

Note: Instead of calling this function directly for most cases it is much more convenient to use the functions mvIMPACT::acquire::Request::attachUserBuffer and mvIMPACT::acquire::Request::detachUserBuffer instead.

User supplied buffers must follow the alignment and size requirements reported by versions of the function mvIMPACT::acquire::FunctionInterface::getCurrentCaptureBufferLayout. Calling a version of this function will return all the information required to allocate buffers that can be used to capture data for the specified settings.

When allocating memory on the heap, the complete buffer size is needed which is calculated like this:

size + alignment

Note: The address passed to the request object must be aligned already!

Device* pDev = getDevicePointerFromSomewhere()
FunctionInterface fi(pDev);
Request* pRequest = fi.getRequest( 0 );
// the buffer assigned to the request object must be aligned accordingly
// the size of the user supplied buffer MUST NOT include the additional size
// caused by the alignment
if( pRequest->attachUserBuffer( getAlignedMemoryPtr(), getAlignedMemorySize() ) ) == DMR_NO_ERROR )
{
  ImageRequestControl irc(pDev);
  irc.requestToUse.write( 0 ); // use the buffer just configured for the next image request
  // now the next image will be captured into the user supplied memory
  fi.imageRequestSingle( &irc ); // this will send request '0' to the driver
  // wait for the buffer. Once it has been returned by the driver AND the user buffer shall no
  // longer be used call
  if( pRequest->detachUserBuffer() != DMR_NO_ERROR )
  {
    // handle error
  }
  // now this request will use internal memory again.
}
else
{
   // handle error
}

Note: A request that is in configuration mode can't be sent to the driver for acquisition until mvIMPACT::acquire::Request::unlock or mvIMPACT::acquire::FunctionInterface::imageRequestUnlock has been called again. By using mvIMPACT::acquire::Request::attachUserBuffer and mvIMPACT::acquire::Request::detachUserBuffer this locking and unlocking is done internally thus the application does not need to worry about this.

See also: mvIMPACT::acquire::FunctionInterface::imageRequestSingle,
mvIMPACT::acquire::Request::attachUserBuffer,
mvIMPACT::acquire::Request::detachUserBuffer,
mvIMPACT::acquire::Request::unlock,
mvIMPACT::acquire::FunctionInterface::imageRequestUnlock,
mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor,
mvIMPACT::acquire::FunctionInterface::imageRequestReset

Since: 1.12.68

Returns

mvIMPACT::acquire::DMR_NO_ERROR if successful.
A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

◆ detachUserBuffer()

int detachUserBuffer ( void )

inline

Convenience function to detach a user supplied buffer from a mvIMPACT::acquire::Request object.

This function just provides a nicer way to detach a user supplied buffer from a mvIMPACT::acquire::Request. It e.g. allows to write code like this:

// 'fi' is assumed to be a valid instance of mvIMPACT::acquire::FunctionInterface
const Request* pRequest = fi.getRequest( 0 ); // get access to request 0
pRequest->detachUserBuffer();

Instead if this:

// 'fi' is assumed to be a valid instance of mvIMPACT::acquire::FunctionInterface
const Request* pRequest = fi.getRequest( 0 ); // get access to request 0
if( pRequest->configure() == DMR_NO_ERROR )
{
  pRequest->imageMemoryMode.write( rimmAuto );
  pRequest->unlock();
}

To find out more about capturing to user supplied buffers please refer to the example CaptureToUserMemory.cpp and have a look at the documentation of the function mvIMPACT::acquire::Request::configure.

See also: mvIMPACT::acquire::Request::attachUserBuffer,
mvIMPACT::acquire::FunctionInterface::imageRequestUnlock,
mvIMPACT::acquire::Request::unlock,
mvIMPACT::acquire::FunctionInterface::imageRequestConfigure,
mvIMPACT::acquire::Request::configure

Since: 1.12.68

Returns

mvIMPACT::acquire::DMR_NO_ERROR if successful.
A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Examples: CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, and CaptureToUserMemory.legacy.cpp.

◆ getBufferPart()

BufferPart & getBufferPart ( unsigned int index ) const

inline

Returns a reference to a buffer part descriptor of this request.

This function returns a reference to a mvIMPACT::acquire::BufferPart at index index associated with this mvIMPACT::acquire::Request.

Attention: Please do NEVER work with old references to this class. So do NOT store this reference in some variable to use it for the evaluation of the next mvIMPACT::acquire::Request object as well, as this might not work because the buffer layout might have changed. Whenever mvIMPACT::acquire::Request::getBufferPart is called the function will make sure that the data in the returned structure is up to date while when working with an old reference to the mvIMPACT::acquire::BufferPart structure the containing data might refer to a previous result or worse an invalid memory location. This reference will remain valid until an application calls mvIMPACT::acquire::Request::unlock for the corresponding request.

See also: mvIMPACT::acquire::Request::getBufferPartCount
Multi-Part Format

Since: 2.20.0

Returns: A reference to the buffer part defined by index

Parameters

[in] index The index of the buffer part to return

Examples: ContinuousCaptureMultiPart.legacy.cpp, and exampleHelper.h.

◆ getBufferPartCount()

unsigned int getBufferPartCount ( void ) const

inline

Returns the number of buffer parts currently associated with this request.

Certain device drivers are able to deliver multiple buffer part within a single request object.

See also: Multi-Part Format

Since: 2.20.0

Returns: The number of buffer parts currently associated with this request. This might be zero in case the device driver delivers a standard data stream. It might also be 1 for special data formats such as JPEG, which must be handled differently from an image describing properties perspective.

Examples: ContinuousCaptureMultiPart.legacy.cpp, and exampleHelper.h.

◆ getChunkCounterCount()

unsigned int getChunkCounterCount ( void ) const

inline

Returns the number of counter values that can be returned as part of the additional data of the buffer containing the request data.

A device may support a large number of counters even though just a few of them or none is configured for counting. In such a case situation when switching on the transmission of the counter values at the time of the internal frame start event will allow to access the number of counters returned by this function but then the data in these counters of course will be meaningless.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Since: 2.0.15

Returns: The number of counter values that can be returned as part of the additional data of the buffer containing the request data.

◆ getChunkCounterValue()

PropertyI64 getChunkCounterValue ( unsigned int index ) const

inline

Returns a 64 bit integer property (read-only) defining the selected counter value at the time of the internal frame start event for this request.

If index is invalid(too large) an STL out_of_range exception will be thrown.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Since: 2.0.15

Parameters

[in] index The index of the counter to return

◆ getChunkGain() [1/2]

PropertyF getChunkGain ( const std::string & name ) const

inline

Returns a floating point property (read-only) defining the selected gain value at the time of the internal frame start event for this request.

If name is invalid(not a valid gain to select) a mvIMPACT::acquire::EInvalidInputParameter exception will be thrown.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Since: 2.17.3

Parameters

[in] name The name of the gain to return (as selected by mvIMPACT::acquire::GenICam::AnalogControl::gainSelector)

◆ getChunkGain() [2/2]

PropertyF getChunkGain ( unsigned int index ) const

inline

Returns a floating point property (read-only) defining the selected gain value at the time of the internal frame start event for this request.

If index is invalid(too large) an STL out_of_range exception will be thrown.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Since: 2.17.3

Parameters

[in] index The index of the gain to return

◆ getChunkGainCount()

unsigned int getChunkGainCount ( void ) const

inline

Returns the number of gain values that can be returned as part of the additional data of the buffer containing the request data.

A device may support a large number of gains even though just a few of them or none is configured to run. In such a case situation when switching on the transmission of the gain values at the time of the internal frame start event will allow to access the number of gains returned by this function but then the data in these gains of course will be meaningless.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Since: 2.17.3

◆ getChunkTimerCount()

unsigned int getChunkTimerCount ( void ) const

inline

Returns the number of timer values that can be returned as part of the additional data of the buffer containing the request data.

A device may support a large number of timers even though just a few of them or none is configured to run. In such a case situation when switching on the transmission of the timer values at the time of the internal frame start event will allow to access the number of timers returned by this function but then the data in these timers of course will be meaningless.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Since: 2.0.15

◆ getChunkTimerValue()

PropertyF getChunkTimerValue ( unsigned int index ) const

inline

Returns a floating point property (read-only) defining the selected timer value at the time of the internal frame start event for this request.

If index is invalid(too large) an STL out_of_range exception will be thrown.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Since: 2.0.15

Parameters

[in] index The index of the timer to return

◆ getComponentLocator()

DeviceComponentLocator getComponentLocator ( void ) const

inline

Returns a component locator for this request.

This will allow to write custom feature bind operations.

Since: 1.12.68

Returns: A component locator for this request.

◆ getImageBufferDesc()

const ImageBufferDesc & getImageBufferDesc ( void ) const

inline

Returns a const reference to the image buffer descriptor of this request.

This function returns a const reference to the mvIMPACT::acquire::ImageBufferDesc associated with this mvIMPACT::acquire::Request.

Attention: Please do NEVER work with old references to this structure. So do NOT store this reference in some variable to use it for the evaluation of the next mvIMPACT::acquire::Request object as well, as this will not work. Whenever mvIMPACT::acquire::Request::getImageBufferDesc is called the function will make sure that the data in the returned structure is up to date while when working with an old reference to the mvIMPACT::acquire::ImageBufferDesc structure the containing data might refer to a previous result.

Examples: SequenceCapture.win32.cpp, and SingleCapture.cpp.

◆ getImageProcessingResultsIterator()

Component getImageProcessingResultsIterator ( void ) const

inline

Returns an iterator for iterating inside the info/imageProcessingResults list of the request.

This can be useful when custom or device specific algorithms have been applied to the request object that weren't known at compile time.

For a code example please refer to the documentation of mvIMPACT::acquire::Request::getInfoIterator

See also: mvIMPACT::acquire::Request::getInfoIterator

Since: 2.14.0

Returns: An iterator for iterating inside the info/imageProcessingResults list of the request.

◆ getIMPACTImage() [1/2]

mvIMPACT::Image getIMPACTImage ( TImpactBufferFlag flags ) const

inline

Returns an mvIMPACT image buffer representation of the image associated with this request.

Note: This function might be fast depending on the flags parameter or might behave like mvIMPACT::acquire::Request::getIMPACTImage.

Valid values for flags are defined by the enumeration mvIMPACT::acquire::TImpactBufferFlag.

Attention: This function will only be available if mvIMPACT.h has been included before including this interface!

Parameters

[in] flags Flags defining how the buffer is created and behaves.

◆ getIMPACTImage() [2/2]

mvIMPACT::Image getIMPACTImage ( void ) const

inline

Returns an mvIMPACT image buffer representation of the image associated with this request.

Attention: This function is slow, as it performs a copy of the image data. So using this function will not affect the actual image data from the device when modifying the image object.

Note: This function is provided for backward compatibility only. New applications should use the overloaded function accepting a parameter of type mvIMPACT::acquire::TImpactBufferFlag. This function might be faster and provides the user with more control over the way the image is constructed. However if the new function is used also a new driver has to be deployed on every target system running software compiled with this interface. At least version 1.3.5 of the mvDeviceManager-lib.

Attention: This function will only be available if mvIMPACT.h has been included before including this interface!

◆ getInfoIterator()

Component getInfoIterator ( void ) const

inline

Returns an iterator for iterating inside the info list of the request.

This can be useful when custom or device specific information has been attached to the request object that wasn't known at compile time.

It allows to write code like this:

// 'fi' is assumed to be a valid instance of mvIMPACT::acquire::FunctionInterface,
// 'nr' is assumed to be a valid request number returned from a previous call to
// mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor()
const Request* pRequest = fi.getRequest( nr );
if( pRequest )
{
  Component it(pRequest->getInfoIterator());
  std::map<std::string, std::string> m;
  while( it.isValid() )
  {
    // collect all entries that are properties and store their current name and value in a map
    if( it.isProp() && it.isVisible() )
    {
      Property prop( it );
      m.insert( std::make_pair( prop.name(), prop.readS() ) );
    }
    ++it;
  }
  // Here you can work with the information you just obtained
}

Returns: An iterator for iterating inside the info list of the request.

◆ getName()

const std::string & getName ( void ) const

inline

Returns the name associated with this request.

Since: 2.32.0

◆ getNumber()

int getNumber ( void ) const

inline

Returns the number associated with this request.

Examples: CaptureToMegaBuffer.cpp, CaptureToUserMemory.cpp, CaptureToUserMemory.legacy.cpp, ContinuousCaptureOnlyProcessLatest.cpp, and ContinuousCaptureOnlyProcessLatest.legacy.cpp.

◆ hasProcessingBeenSkipped()

bool hasProcessingBeenSkipped ( void ) const

inline

Checks if image processing that was set up for this request has been skipped for performance reasons.

If mvIMPACT::acquire::Device::userControlledImageProcessingEnable is set to mvIMPACT::acquire::bTrue and mvIMPACT::acquire::SystemSettings::imageProcessingMode is set to mvIMPACT::acquire::ipmProcessLatestOnly this function can be used to check if at least one algorithm has been skipped because of a lack of processing time.

See also: mvIMPACT::acquire::Device::userControlledImageProcessingEnable,
mvIMPACT::acquire::SystemSettings::imageProcessingMode

Since: 2.14.0

Returns

true if at least one internal algorithm has been skipped.
false otherwise.

◆ isOK()

bool isOK ( void ) const

inline

Convenience function to check if a request has been processed successfully.

This is just a nicer way of checking the value of the requestResult property. It allows to write code like this:

// 'fi' is assumed to be a valid instance of mvIMPACT::acquire::FunctionInterface,
// 'nr' is assumed to be a valid request number returned from a previous call to
// mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor()
const Request* pRequest = fi.getRequest( nr );
if( pRequest->isOK() )
{
  // do something
}

Instead if this:

// 'fi' is assumed to be a valid instance of mvIMPACT::acquire::FunctionInterface,
// 'nr' is assumed to be a valid request number returned from a previous call to
// mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor()
const Request* pRequest = fi.getRequest( nr );
if( pRequest->requestResult.read() == rrOK )
{
  // do something
}

Since: 1.12.63

Returns

true if the request has been processed successfully.
false otherwise.

Examples: CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, CaptureToUserMemory.legacy.cpp, ContinuousCapture.linux.cpp, ContinuousCapture.win32.cpp, ContinuousCaptureAllDevices.cpp, ContinuousCaptureAllDevices.linux.cpp, ContinuousCaptureAllDevices.win32.cpp, ContinuousCaptureAllFormats.win32.cpp, ContinuousCaptureMultiPart.legacy.cpp, ContinuousCaptureOnlyProcessLatest.cpp, ContinuousCaptureOnlyProcessLatest.legacy.cpp, ContinuousCaptureToAVIFile.cpp, GenICamCallbackOnEvent.cpp, GenICamCommonSettingsUsage.legacy.cpp, GenICamInterfaceLayout.legacy.cpp, GenICamSequencerParameterChangeAtRuntime.cpp, GenICamSequencerUsage.cpp, GenICamSequencerUsage.legacy.cpp, GenICamSequencerUsageWithPaths.cpp, GenICamSequencerUsageWithPaths.legacy.cpp, GenICamSmartFrameRecallUsage.cpp, GenICamSmartFrameRecallUsage.legacy.cpp, GenericInterfaceLayout.cpp, GenericInterfaceLayout.legacy.cpp, Properties.cpp, Properties.legacy.cpp, SequenceCapture.win32.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, SingleCaptureMasterSlave.legacy.cpp, SingleCaptureStorage.cpp, and TimestampFeatures.cpp.

◆ operator=()

Request & operator= ( const Request & rhs )

inline

Allows assignments of mvIMPACT::acquire::Request objects.

◆ save()

int save	(	const std::string &	fileName,
		TImageFileFormat	format = iffAuto ) const

inline

Stores the image described by this request into a file.

This function stores the image described by this request into a file.

Note: Internally The FreeImage is used for this operation. If the library cannot be located in a supported version on the host system calling this function will fail.

Since: 2.23.0

Returns

mvIMPACT::acquire::DMR_NO_ERROR if successful.
mvIMPACT::acquire::DMR_LIBRARY_NOT_FOUND if the required version of the FreeImage library could not be located on the host system.
mvIMPACT::acquire::DEV_UNSUPPORTED_PARAMETER if a pixel format has been passed to the function that is not supported by the internal algorithms.
mvIMPACT::acquire::DEV_INPUT_PARAM_INVALID if a pixel format has been passed to the function that is not supported by the FreeImage library.
A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Parameters

[in]	fileName	The full path of the file to create.
[in]	format	The format of the file to be created. If this parameter is set to mvIMPACT::acquire::iffAuto make sure to specify a proper file extension.

◆ unlock()

int unlock ( void )

inline

Unlocks the request for the driver again.

To ensure that no image data is overwritten by another image request while the user still deals with the image from a previous acquisition each image buffer will be locked by the driver when it is returned to the user by a call to mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor. No new image will be captured into the same buffer until the user unlocks the buffer again by calling mvIMPACT::acquire::Request::unlock or mvIMPACT::acquire::FunctionInterface::imageRequestUnlock.

Note: After unlocking a request it is no longer guaranteed that the memory once referenced by the request and the image buffer belonging to it stays valid, so do NEVER try to access memory belonging to an unlocked request object. If you need to copy the image buffer or modify it in any other way, do everything you have to do BEFORE calling this function!

See also: mvIMPACT::acquire::FunctionInterface::imageRequestReset,
mvIMPACT::acquire::FunctionInterface::imageRequestSingle,
mvIMPACT::acquire::FunctionInterface::imageRequestWaitFor
mvIMPACT::acquire::FunctionInterface::imageRequestConfigure,
mvIMPACT::acquire::Request::configure

Since: 1.12.68

Returns

mvIMPACT::acquire::DMR_NO_ERROR if successful.
A negative error code of type mvIMPACT::acquire::TDMR_ERROR otherwise.

Examples: CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, CaptureToUserMemory.legacy.cpp, ContinuousCapture.linux.cpp, ContinuousCapture.win32.cpp, ContinuousCaptureMultiPart.legacy.cpp, ContinuousCaptureOnlyProcessLatest.cpp, ContinuousCaptureOnlyProcessLatest.legacy.cpp, GenICamCallbackOnEvent.cpp, GenICamCommonSettingsUsage.legacy.cpp, GenICamSequencerParameterChangeAtRuntime.cpp, GenICamSequencerUsageWithPaths.cpp, GenICamSequencerUsageWithPaths.legacy.cpp, GenICamSmartFrameRecallUsage.cpp, and GenICamSmartFrameRecallUsage.legacy.cpp.

Friends And Related Symbol Documentation

◆ FunctionInterface

friend class FunctionInterface

friend

Member Data Documentation

◆ bufferSizeFilled

PropertyI64 bufferSizeFilled

A 64bit integer property (read-only) containing the total amount of data (in bytes) that has been captured during the last capture operation.

In contrast to mvIMPACT::acquire::Request::imageSize, this value might be smaller than the original amount of memory, that has been allocated upfront. This e.g. might be true for a JPEG transmission of a triggered linescan application where mvIMPACT::acquire::Request::imageSize would contain the maximum amount of data that could be captured while this value holds the number of bytes actually captured.

This value in connection with mvIMPACT::acquire::Request::imageData is sufficient to copy the complete image without having any additional information about it.

See also: mvIMPACT::acquire::Request::imageData,
mvIMPACT::acquire::Request::imageSize,
mvIMPACT::acquire::Request::imageFooter,
mvIMPACT::acquire::Request::imageFooterSize

Since: 3.3.0

Examples: exampleHelper.h.

◆ chunkDynamicRangeMax

PropertyI64 chunkDynamicRangeMax

A 64 bit integer property (read-only) containing the maximum value of dynamic range of the image as returned in the chunk data attached to the image.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

◆ chunkDynamicRangeMin

PropertyI64 chunkDynamicRangeMin

A 64 bit integer property (read-only) containing the minimum value of dynamic range of the image as returned in the chunk data attached to the image.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

◆ chunkExposureTime

PropertyF chunkExposureTime

A floating point property (read-only) containing the exposure time used to capture the image as returned in the chunk data attached to the image.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Since: 2.5.16

Examples: GenICamSequencerParameterChangeAtRuntime.cpp, GenICamSequencerUsage.cpp, and GenICamSequencerUsage.legacy.cpp.

◆ chunkHeight

PropertyI64 chunkHeight

A 64 bit integer property (read-only) containing the height of the image in pixels as returned in the chunk data attached to the image.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Examples: GenICamSequencerUsage.cpp, and GenICamSequencerUsage.legacy.cpp.

◆ chunkLineStatusAll

PropertyI64 chunkLineStatusAll

A 64 bit integer property (read-only) containing the status of all I/O lines at the time of the internal frame start signal of the image as returned in the chunk data attached to the image.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

◆ chunkmvCustomIdentifier

PropertyI64 chunkmvCustomIdentifier

A 64 bit integer property (read-only) containing the previously configured user defined identifier attached to the image.

This identifier can be specified by some other functions belonging to this SDK. If not specified this value will be 0.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Since: 2.17.3

Examples: GenICamSmartFrameRecallUsage.cpp, and GenICamSmartFrameRecallUsage.legacy.cpp.

◆ chunkOffsetX

PropertyI64 chunkOffsetX

A 64 bit integer property (read-only) containing the X-offset of the image in pixels as returned in the chunk data attached to the image.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

◆ chunkOffsetY

PropertyI64 chunkOffsetY

A 64 bit integer property (read-only) containing the Y-offset of the image in pixels as returned in the chunk data attached to the image.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

◆ chunkPixelFormat

PropertyI64 chunkPixelFormat

A 64 bit integer property (read-only) containing the pixel format of the image as returned in the chunk data attached to the image.

This will NOT be a valid Impact Acquire pixel format but e.g. a GigE Vision, USB3 Vision of PFNC compliant pixel format or something else.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

◆ chunkSequencerSetActive

PropertyI64 chunkSequencerSetActive

A 64-bit integer property (read-only) containing the index of the active set of the running sequencer use during the creation of this block of data.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Since: 2.12.3

Examples: GenICamSequencerParameterChangeAtRuntime.cpp, GenICamSequencerUsage.cpp, and GenICamSequencerUsage.legacy.cpp.

◆ chunkTimestamp

PropertyI64 chunkTimestamp

A 64 bit integer property (read-only) containing the timestamp value of the internal frame start signal of the image as returned in the chunk data attached to the image.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Examples: TimestampFeatures.cpp.

◆ chunkWidth

PropertyI64 chunkWidth

A 64 bit integer property (read-only) containing the width of the image in pixels as returned in the chunk data attached to the image.

Note: For additional information about the chunk data format please refer to Chunk Data Format.

Examples: GenICamSequencerUsage.cpp, and GenICamSequencerUsage.legacy.cpp.

◆ imageBayerMosaicParity

PropertyIBayerMosaicParity imageBayerMosaicParity

An enumerated integer property (read-only) containing the Bayer parity of this image.

If the current image does not contain Bayer data, this value will be mvIMPACT::acquire::bmpUndefined.

Valid values for this property are defined by the enumeration mvIMPACT::acquire::TBayerMosaicParity.

Examples: GenICamSequencerUsage.cpp, and GenICamSequencerUsage.legacy.cpp.

◆ imageBytesPerPixel

PropertyI imageBytesPerPixel

An integer property (read-only) containing the number of bytes per pixel in this image.

Examples: CaptureToMegaBuffer.cpp, and ContinuousCaptureToAVIFile.cpp.

◆ imageChannelBitDepth

PropertyI imageChannelBitDepth

An integer property (read-only) containing the number of effective bits stored in each channel belonging to the current image.

Note: This property will store imageChannelCount values. These can be queried one by one using the index parameter of the function mvIMPACT::acquire::PropertyI::read() or in a single call by using the overloaded read function accepting a reference to a vector.

◆ imageChannelCount

PropertyI imageChannelCount

An integer property (read-only) containing the number of channels this image consists of.

For an RGB image this value e.g. would be 3. This value also defines how many parameters are stored by the properties mvIMPACT::acquire::Request::imagePixelPitch,
mvIMPACT::acquire::Request::imageLinePitch,
mvIMPACT::acquire::Request::imageChannelBitDepth,
mvIMPACT::acquire::Request::imageChannelDesc and
mvIMPACT::acquire::Request::imageChannelOffset.

If e.g. the channel count is 3 a call like pRequest->imageChannelOffset.read( 2 ) would return the channel offset of channel 3 (as calls to the read functions of properties are '0' based).

◆ imageChannelDesc

PropertyS imageChannelDesc

A string property (read-only) containing the string descriptors of each channel belonging to the current image.

Note: This property will store imageChannelCount values. These can be queried one by one using the index parameter of the function mvIMPACT::acquire::PropertyS::read() or in a single call by using the overloaded read function accepting a reference to a vector.

For an RGB image this property e.g. might contain three values "R", "G" and "B".

FunctionInterface& fi = getFunctionInterfaceFromSomewhere();
int currentRequestNr = getCurrentRequestNumberFromSomewhere();
const Request* pRequest = fi.getRequest( currentRequestNr );
int channelCount = pRequest->imageChannelCount.read();
for( int i=0; i<channelCount; i++ )
{
  cout << "channel[" << i << "]: " << pRequest->imageChannelDesc.read( i ) << endl;
}

Examples: CaptureToMegaBuffer.cpp.

◆ imageChannelOffset

PropertyI imageChannelOffset

An integer property (read-only) containing the offset (in bytes) to each channel belonging to the current image relative to the address contained in mvIMPACT::acquire::Request::imageData.

Note: This property will store imageChannelCount values. These can be queried one by one using the index parameter of the function mvIMPACT::acquire::PropertyI::read() or in a single call by using the overloaded read function accepting a reference to a vector.

Examples: CaptureToMegaBuffer.cpp.

◆ imageData

PropertyPtr imageData

A pointer property (read-only) containing the start address of the image data.

This address in connection with mvIMPACT::acquire::Request::imageSize is sufficient to copy the complete image without having any additional information about it. Sometimes however mvIMPACT::acquire::Request::bufferSizeFilled might be more suitable for this.

FunctionInterface& fi = getFunctionInterfaceFromSomewhere();
int currentRequestNr = getCurrentRequestNumberFromSomewhere();
const Request* pRequest = fi.getRequest( currentRequestNr );
char* pTempBuf = new char[pRequest->imageSize.read()];
memcpy( pTempBuf, pRequest->imageData.read(), pRequest->imageSize.read() );
// free the memory once no longer needed...

Note: It's not always necessary to copy the image data! Each image buffer is an integral part of the mvIMPACT::acquire::Request object returned to the user by a call to the corresponding 'waitFor' function offered by the interface. The data in this buffer remains valid until the user either unlocks the request buffer or closes the mvIMPACT::acquire::Device again.; By unlocking the mvIMPACT::acquire::Request, the user informs the driver that this mvIMPACT::acquire::Request and the image buffer belonging to that mvIMPACT::acquire::Request is no longer needed by the user. The driver then queues this mvIMPACT::acquire::Request for capturing image data into it once again. However, once a mvIMPACT::acquire::Request has been returned to the user, its image buffer can't be overwritten by the driver! Therefore the user can work with, modify, store or copy the data safely until he unlocks the mvIMPACT::acquire::Request again.; This property will become writeable if this request is in configuration mode.

See also: mvIMPACT::acquire::FunctionInterface::imageRequestConfigure,
mvIMPACT::acquire::Request::configure,
mvIMPACT::acquire::Request::imageSize,
mvIMPACT::acquire::Request::bufferSizeFilled,
mvIMPACT::acquire::Request::imageFooterSize

Examples: CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, CaptureToUserMemory.legacy.cpp, ContinuousCaptureAllFormats.win32.cpp, ContinuousCaptureToAVIFile.cpp, GenICamSequencerUsage.cpp, GenICamSequencerUsage.legacy.cpp, and SingleCaptureStorage.cpp.

◆ imageFooter

PropertyPtr imageFooter

A pointer property (read-only) containing the start address of the footer associated with this image.

A footer may contain additional data like e.g. information about the image (e.g. the exposure time used for this image). If this property contains the value '0' no footer is attached to this image.

Note: In general it is not necessary to access footer data. Sometime e.g. when the hardware already does some image pre-processing a footer containing additional information about the image data might be attached to the image. In this case some additional information about the structure of the footer might be needed as well.

◆ imageFooterSize

PropertyI imageFooterSize

An integer property (read-only) containing the size (in bytes) of the footer associated with this image.

If this property contains the value '0' no footer is attached to this image.

Examples: CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, and CaptureToUserMemory.legacy.cpp.

◆ imageHeight

PropertyI imageHeight

◆ imageHeightTotal

PropertyI imageHeightTotal

An integer property (read-only) containing the total height of the image in pixels if this buffer is part of a larger image.

Note: This feature will be supported by devices using an Impact Acquire driver greater or equal version 1.11.50. Not every device driver will be capable of dealing with multiple buffers forming a single image. If a device driver can not deliver parts of a larger image, then this property will always contain the same value as returned by mvIMPACT::acquire::Request::imageHeight.

◆ imageLinePitch

PropertyI imageLinePitch

An integer property (read-only) containing the offset (in bytes) to the next line of each channel belonging to the current image.

Note: This property will store imageChannelCount values. These can be queried one by one using the index parameter of the function mvIMPACT::acquire::PropertyI::read() or in a single call by using the overloaded read function accepting a reference to a vector.

Examples: CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, CaptureToUserMemory.legacy.cpp, ContinuousCapture.linux.cpp, ContinuousCaptureAllFormats.win32.cpp, ContinuousCaptureToAVIFile.cpp, and SingleCaptureStorage.cpp.

◆ imageMemoryMode

PropertyIRequestImageMemoryMode imageMemoryMode

An enumerated integer property (read-only) containing the memory mode used for this request.

Valid values for this property are defined by the enumeration mvIMPACT::acquire::TRequestImageMemoryMode.

Note: This property will become writeable if this request is in configuration mode.

See also: mvIMPACT::acquire::FunctionInterface::imageRequestConfigure,
mvIMPACT::acquire::Request::configure

Examples: CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, and CaptureToUserMemory.legacy.cpp.

◆ imageOffsetX

PropertyI imageOffsetX

An integer property (read-only) containing the X-offset of the image in pixels.

Note: This feature will be supported by devices using an Impact Acquire driver greater or equal version 1.10.92.

Examples: ContinuousCaptureMultiPart.legacy.cpp, and GenICamSequencerParameterChangeAtRuntime.cpp.

◆ imageOffsetY

PropertyI imageOffsetY

An integer property (read-only) containing the Y-offset of the image in pixels.

Note: This feature will be supported by devices using an Impact Acquire driver greater or equal version 1.10.92.

Examples: ContinuousCaptureMultiPart.legacy.cpp, and GenICamSequencerParameterChangeAtRuntime.cpp.

◆ imagePixelFormat

PropertyIImageBufferPixelFormat imagePixelFormat

An enumerated integer property (read-only) containing the pixel format of this image.

This might be important, when the image data needs to be processed or stored in a file or maybe even if the image shall be displayed.

Valid values for this property are defined by the enumeration mvIMPACT::acquire::TImageBufferPixelFormat.

Examples: CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, CaptureToUserMemory.legacy.cpp, ContinuousCapture.linux.cpp, GenICamSequencerUsage.cpp, GenICamSequencerUsage.legacy.cpp, and SingleCapture.cpp.

◆ imagePixelPitch

PropertyI imagePixelPitch

An integer property (read-only) containing the offset (in bytes) to the next pixel of the specified channel of this image.

Note: This property will store imageChannelCount values. These can be queried one by one using the index parameter of the function mvIMPACT::acquire::PropertyI::read() or in a single call by using the overloaded read function accepting a reference to a vector.

Examples: CaptureToMegaBuffer.cpp, ContinuousCaptureAllFormats.win32.cpp, and SingleCaptureStorage.cpp.

◆ imageSize

PropertyI imageSize

An integer property (read-only) containing the size (in bytes) of the whole image.

This value in connection with mvIMPACT::acquire::Request::imageData is sufficient to copy the complete image without having any additional information about it. Sometimes however mvIMPACT::acquire::Request::bufferSizeFilled might be more suitable for this.

Note: This property will become writeable if this request is in configuration mode.

See also: mvIMPACT::acquire::FunctionInterface::imageRequestConfigure,
mvIMPACT::acquire::Request::configure,
mvIMPACT::acquire::Request::imageData,
mvIMPACT::acquire::Request::bufferSizeFilled,
mvIMPACT::acquire::Request::imageFooterSize

Examples: CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, CaptureToUserMemory.legacy.cpp, ContinuousCaptureToAVIFile.cpp, GenICamSequencerUsage.cpp, and GenICamSequencerUsage.legacy.cpp.

◆ imageWidth

PropertyI imageWidth

◆ imageWidthTotal

PropertyI imageWidthTotal

An integer property (read-only) containing the total width of the image in pixels if this buffer is part of a larger image.

Note: This feature will be supported by devices using an Impact Acquire driver greater or equal version 1.11.50. Not every device driver will be capable of dealing with multiple buffers forming a single image. If a device driver can not deliver parts of a larger image, then this property will always contain the same value as returned by mvIMPACT::acquire::Request::imageWidth.

◆ infoCameraOutputUsed

PropertyICameraOutput infoCameraOutputUsed

An enumerated integer property (read-only) containing the camera output used to transmit the image to the capture device.

Valid values for this property are defined by the enumeration mvIMPACT::acquire::TCameraOutput.

Note: This property is not supported by every device. Therefore always call the function mvIMPACT::acquire::Component::isValid to check if this property is available or not.

◆ infoExposeStart_us

PropertyI infoExposeStart_us

An integer property (read-only) containing a timestamp (in us) defining the time the device started the exposure of the image associated with this mvIMPACT::acquire::Request object.

This value will stay 0 if nothing is known about the time the exposure did start. In such a case the mvIMPACT::acquire::Request::infoTimeStamp_us property should be used instead.

◆ infoExposeTime_us

PropertyI infoExposeTime_us

An integer property (read-only) containing the 'real' expose time (in us) used to generate this image.

This might differ slightly from the value selected by the user via the corresponding exposure property depending on the precision available for the device or the connected camera.

Note: When working with the mvIMPACT::acquire::dilGenICam this value will reflect the last value of the corresponding device property when it was written thus is a cached copy of the value that has been set by the application. For various operation modes this might NOT be the value actually used by the device for taking the image described by this request object. For example when AEC (exposureAuto) is active or the device is operated in a special sequencer mode the value of this property might be incorrect. When precise information about this value is needed it is recommended to work in chunk mode and use the exposure provided as chunk information instead.

See also: mvIMPACT::acquire::Device::interfaceLayout,
mvIMPACT::acquire::GenICam::ChunkDataControl,
mvIMPACT::acquire::GenICam::AcquisitionControl::exposureAuto,
mvIMPACT::acquire::Request::getChunkExposureTime

◆ infoFrameID

PropertyI64 infoFrameID

A 64 bit integer property (read-only) containing a frame identifier.

This parameter is returned as part of the mvIMPACT::acquire::Request. It is used to associate a certain image with a unique identifier.

When an mvIMPACT::acquire::RTCtrProgramStep instruction of the type mvIMPACT::acquire::rtctrlProgTriggerSet is executed, the frameID is set to the value of the property FrameID of a corresponding mvIMPACT::acquire::RTCtrProgramStep if the HRTC is used and any program step executes the setting of the ID.

If a device (e.g. a digital camera) supports the transmission of a unique identifier for an image, this property will reflect the identifier as transmitted by the device.

Note

mvBlueFOX and mvHYPERION specific: This property will only contain meaningful data if the device supports at least one HRTC and a program is running and writing data to the property OR if a device supports the transmission of a unique identifier for an image. Currently HRTC programs are supported by mvBlueFOX and mvHYPERION devices.

GigE Vision and USB3 Vision specific: This is the property where the so called block ID will be stored which is a unique identifier for each frame that will be transferred by the device as part of each frame as defined by the standard.

For GigE Vision 1.x compliant devices, this will be a 16 bit counter that will be incremented with every data block(e.g. an image or chunk data) transmitted by the device where '0' is a reserved value, which will never be used, thus values like this will be transmitted in a round robin scheme: 1, 2, 3, ..., 65535, 1, 2, ...
For devices complying with version 2.0 and greater of the GigE Vision specification, this will be a 64 bit counter that will be incremented with every data block(e.g. an image or chunk data) transmitted by the device where '0' is a reserved value, which will never be used, thus values like this will be transmitted in a round robin scheme: 1, 2, 3, ..., ((2^64)-1), 1, 2, ...
For USB3 Vision compliant devices, this will be a 64 bit counter that will be incremented with every data block(e.g. an image or chunk data) transmitted by the device, thus values like this will be transmitted in a round robin scheme: 0, 1, 2, ..., ((2^64)-1), 0, 1, ...

Please note that due to the nature of mvIMPACT::acquire::amContinuous there might be gaps between the last image of a continuous stream and the first image of the next continuous stream if the device is stopped or re-programmed in between.

Examples: ContinuousCaptureMultiPart.legacy.cpp, GenICamSequencerParameterChangeAtRuntime.cpp, GenICamSequencerUsage.cpp, GenICamSequencerUsage.legacy.cpp, SingleCaptureMasterSlave.cpp, SingleCaptureMasterSlave.legacy.cpp, and TimestampFeatures.cpp.

◆ infoFrameNr

PropertyI64 infoFrameNr

A 64 bit integer property (read-only, zero-based) containing the number of image requests processed since this driver instance has been opened.

This counter is incremented regardless of the result this request is returned with thus also e.g. if a request did time out, was aborted(e.g. due to a call to mvIMPACT::acquire::FunctionInterface::imageRequestReset or mvIMPACT::acquire::FunctionInterface::acquisitionStop) or the data was not completely captured. So if a mvIMPACT::acquire::Request object contains the value 6 here, 6 requests have been processed before this one(the first request would contain the value 0) This value is reset to 0 only if the current driver instance is closed.

Examples: SingleCaptureMasterSlave.cpp, and SingleCaptureMasterSlave.legacy.cpp.

◆ infoGain_dB

PropertyF infoGain_dB

A float property (read-only) containing the gain(in dB) this image has been taken with.

Note: When working with the mvIMPACT::acquire::dilGenICam this value will reflect the last value of the corresponding device property when it was written thus is a cached copy of the value that has been set by the application. For various operation modes this might NOT be the value actually used by the device for taking the image described by this request object. For example when AGC (gainAuto) is active or the device is operated in a special sequencer mode the value of this property might be incorrect. When precise information about this value is needed it is recommended to work in chunk mode and use the gain provided as chunk information instead.

See also: mvIMPACT::acquire::Device::interfaceLayout,
mvIMPACT::acquire::GenICam::ChunkDataControl,
mvIMPACT::acquire::GenICam::AnalogControl::gainAuto,
mvIMPACT::acquire::Request::getChunkGainCount,
mvIMPACT::acquire::Request::getChunkGain

◆ infoImageAverage

PropertyF infoImageAverage

Currently unsupported.

◆ infoIOStatesAtExposureEnd

PropertyI infoIOStatesAtExposureEnd

An integer property (read-only) containing the state of all the IO lines at the end of the frame exposure as a device specific bit field.

See mvIMPACT::acquire::Request::infoIOStatesAtExposureStart for details on how to interpret the data.

Note: This property is not supported by every device. Therefore always call the function mvIMPACT::acquire::Component::isValid to check if this property is available or not.

◆ infoIOStatesAtExposureStart

PropertyI infoIOStatesAtExposureStart

An integer property (read-only) containing the state of all the IO lines at the beginning of the frame exposure as a device specific bit field.

The following table documents which bit in this property represents the state of which digital I/O for mvBlueFOX devices:

bit	IO
0	in 0
1	in 1
2	in 2(if available)
3	in 3(if available)
4	out 0
5	out 1
6	out 2(if available)
7	out 3(if available)

Attention: This feature is currently only available for mvBlueFOX-MLC devices!

#include <sstream>
#include <mvIMPACT/mvIMPACT_acquire.h>
 
using namespace std;
using namespace mvIMPACT::acquire;
 
//-----------------------------------------------------------------------------
template<typename _Ty>
string decToBinString( _Ty value )
//-----------------------------------------------------------------------------
{
  const size_t bitCount = sizeof(_Ty)*8;
  ostringstream oss;
  for( size_t i=0; i<bitCount; i++ )
  {
    oss << ( ( value & ( 1 << ( bitCount - 1 - i ) ) ) ? "1" : "0" );
  }
  return oss.str();
}
 
//-----------------------------------------------------------------------------
void printIOStateOfAValidRequest( const Request* pRequest )
//-----------------------------------------------------------------------------
{
  if( pRequest->infoIOStatesAtExposureStart.isValid() )
  {
     cout << pRequest->infoIOStatesAtExposureStart.name() << ": " << decToBinString( pRequest->infoIOStatesAtExposureStart.read() ) << endl;
  }
}

Note: This property is not supported by every device. Therefore always call the function mvIMPACT::acquire::Component::isValid to check if this property is available or not.

◆ infoLineCounter

PropertyI infoLineCounter

An integer property (read-only) containing the number of lines since the last trigger event.

Will contain

the number of lines since last trigger event of the first line of the snap if line counting is enabled
-1 otherwise

Note: This property is not supported by every device. Therefore always call the function mvIMPACT::acquire::Component::isValid to check if this property is available or not.

◆ infoMissingData_pc

PropertyF infoMissingData_pc

A float property (read-only) containing the amount of data missing in the current image.

The value of this property will be 0 almost always. However if a device can detect blocks of missing data and an image request has returned with mvIMPACT::acquire::rrFrameIncomplete to indicate that not all the data has been captured, this property will contain the amount of data missing in percent.

◆ infoSettingUsed

PropertyI infoSettingUsed

A enumerated integer property (read-only) containing the setting that was used for processing this request.

The string representation will be a valid setting name, the integer representation can be casted into a mvIMPACT::acquire::HOBJ type.

◆ infoTimeStamp_us

PropertyI64 infoTimeStamp_us

A 64 bit integer property (read-only) containing a timestamp to define the exact time this image has been captured (usually either at exposure start or exposure end, depending on the device).

mvBlueFOX specific: The counter of the timestamp starts when the camera gets initialized. It is measured in us.

Examples: ContinuousCaptureMultiPart.legacy.cpp, ContinuousCaptureOnlyProcessLatest.cpp, ContinuousCaptureOnlyProcessLatest.legacy.cpp, GenICamSequencerUsage.cpp, GenICamSequencerUsage.legacy.cpp, GenICamSmartFrameRecallUsage.cpp, GenICamSmartFrameRecallUsage.legacy.cpp, and TimestampFeatures.cpp.

◆ infoTransferDelay_us

PropertyI infoTransferDelay_us

An integer property (read-only) containing the time the transaction of this image has been delayed (in us) because either the bus was blocked or the CPU was busy.

Normally this value will be 0. A value larger than 0 indicates that the system can't manage the current load.

Note: This property is not supported by every device. Therefore always call the function mvIMPACT::acquire::Component::isValid to check if this property is available or not.

◆ infoVideoChannel

PropertyI infoVideoChannel

An integer property (read-only) containing the video input channel of the device this image has been acquired from.

Note: This property is not supported by every device and will only be available if the device has more than one input channel. Therefore always call the function mvIMPACT::acquire::Component::isValid to check if this property is available or not.

◆ payloadType

PropertyIPayloadType payloadType

An enumerated integer property (read-only) defining the payload type of this request.

This parameter indicates the current payload type of this request.

Valid values for this property are defined by the enumeration mvIMPACT::acquire::TPayloadType.

Since: 3.2.0

Examples: SingleCapture.cpp, and exampleHelper.h.

◆ requestResult

PropertyIRequestResult requestResult

An enumerated integer property (read-only) defining the result of this request.

This parameter indicates whether a previous image acquisition has been successful or not.

Valid values for this property are defined by the enumeration mvIMPACT::acquire::TRequestResult.

Examples: CaptureToMegaBuffer.cpp, CaptureToOpenGLMemory.cpp, CaptureToUserMemory.cpp, CaptureToUserMemory.legacy.cpp, ContinuousCapture.linux.cpp, ContinuousCapture.win32.cpp, ContinuousCaptureAllDevices.cpp, ContinuousCaptureAllDevices.linux.cpp, ContinuousCaptureAllDevices.win32.cpp, ContinuousCaptureAllFormats.win32.cpp, ContinuousCaptureMultiPart.legacy.cpp, ContinuousCaptureOnlyProcessLatest.cpp, ContinuousCaptureOnlyProcessLatest.legacy.cpp, ContinuousCaptureToAVIFile.cpp, GenICamCallbackOnEvent.cpp, GenICamCommonSettingsUsage.legacy.cpp, GenICamInterfaceLayout.legacy.cpp, GenICamSequencerUsage.cpp, GenICamSequencerUsage.legacy.cpp, GenICamSequencerUsageWithPaths.cpp, GenICamSequencerUsageWithPaths.legacy.cpp, GenICamSmartFrameRecallUsage.cpp, GenICamSmartFrameRecallUsage.legacy.cpp, GenericInterfaceLayout.cpp, GenericInterfaceLayout.legacy.cpp, Properties.cpp, Properties.legacy.cpp, SequenceCapture.win32.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, SingleCaptureMasterSlave.legacy.cpp, SingleCaptureStorage.cpp, and TimestampFeatures.cpp.

◆ requestState

PropertyIRequestState requestState

An enumerated integer property (read-only) defining the current state of this request.

This parameter indicates the current state of this request. A mvIMPACT::acquire::Request e.g. can currently be idle. This would mean that it is currently not used for image acquisition. Also a mvIMPACT::acquire::Request can be in 'Capturing' state, which means it is currently processed by the driver.

Valid values for this property are defined by the enumeration mvIMPACT::acquire::TRequestState.

Public Member Functions

Public Attributes

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Request() [1/2]

◆ Request() [2/2]

◆ ~Request()

Member Function Documentation

◆ attachUserBuffer()

◆ configure()

◆ detachUserBuffer()

◆ getBufferPart()

◆ getBufferPartCount()

◆ getChunkCounterCount()

◆ getChunkCounterValue()

◆ getChunkGain() [1/2]

◆ getChunkGain() [2/2]

◆ getChunkGainCount()

◆ getChunkTimerCount()

◆ getChunkTimerValue()

◆ getComponentLocator()

◆ getImageBufferDesc()

◆ getImageProcessingResultsIterator()

◆ getIMPACTImage() [1/2]

◆ getIMPACTImage() [2/2]

◆ getInfoIterator()

◆ getName()

◆ getNumber()

◆ hasProcessingBeenSkipped()

◆ isOK()

◆ operator=()

◆ save()

◆ unlock()

Friends And Related Symbol Documentation

◆ FunctionInterface

Member Data Documentation

◆ bufferSizeFilled

◆ chunkDynamicRangeMax

◆ chunkDynamicRangeMin

◆ chunkExposureTime

◆ chunkHeight

◆ chunkLineStatusAll

◆ chunkmvCustomIdentifier

◆ chunkOffsetX

◆ chunkOffsetY

◆ chunkPixelFormat

◆ chunkSequencerSetActive

◆ chunkTimestamp

◆ chunkWidth

◆ imageBayerMosaicParity

◆ imageBytesPerPixel

◆ imageChannelBitDepth

◆ imageChannelCount

◆ imageChannelDesc

◆ imageChannelOffset

◆ imageData

◆ imageFooter

◆ imageFooterSize

◆ imageHeight

◆ imageHeightTotal

◆ imageLinePitch

◆ imageMemoryMode

◆ imageOffsetX

◆ imageOffsetY

◆ imagePixelFormat

◆ imagePixelPitch

◆ imageSize

◆ imageWidth

◆ imageWidthTotal

◆ infoCameraOutputUsed

◆ infoExposeStart_us

◆ infoExposeTime_us

◆ infoFrameID

◆ infoFrameNr

◆ infoGain_dB

◆ infoImageAverage

◆ infoIOStatesAtExposureEnd

◆ infoIOStatesAtExposureStart