A class that can be used for displaying images within existing windows or GUI elements that can provide a window handle. More...

#include <mvIMPACT_acquire_display.h>

Public Member Functions
void	Clear (void) const
	Clears the display.

int	GetAppliedShift (void) const
	Returns the current shift value that has been applied to the last image that has been displayed.

TDisplayMode	GetDisplayMode (void) const
	Returns the current display mode.

void	GetImage (const void *ppData, int pWidth, int pHeight, int pBitsPerPixel, int *pPitch)
	Gets the parameters of the current data block associated with the display.

TInterpolationMode	GetInterpolationMode (void) const
	Gets the current interpolation mode that will be used for scaling if display window rectangle is different to input image rectangle.

int	GetLastError (void) const
	Returns the last error and clears it.

int	GetShift (void) const
	Returns the current shift value as defined by the application.

WindowHandle	GetWindowHandle (void) const
	Returns the current window handle associated with the display object.

	ImageDisplay (WindowHandle hwnd)
	Create a new object that can be used for displaying images.

void	RemoveImage (void)
	Removes the current image from the display.

void	SetBackgroundBrush (BrushHandle hBrush)
	Associates a brush to be used for painting the background within the client area.

void	SetBitmapRectangle (int left, int top, int width, int height)
	Sets the position and dimension of bitmap data region.

void	SetDDrawOverlayKeyColor (ColorValue keyColor)
	Defines the key color for the DirectDraw® overlay.

void	SetDisplayMode (TDisplayMode mode)
	Switches to a different display mode.

void	SetDisplayRectangle (int left, int top, int width, int height)
	Defines the rectangle used for drawing within the window associated with the display structure.

void	SetImage (const mvIMPACT::acquire::ImageBuffer *pBuf)
	Sets the next image to display.

void	SetImage (const mvIMPACT::acquire::Request *pRequest)
	Sets the next image to display.

void	SetImage (const void **ppData, size_t ppDataArraySize, TFormatFlags format, int width, int height, int bitsPerPixel, int pitch)
	Sets the next image to display.

void	SetImage (const void *pData, int width, int height, int bitsPerPixel, int pitch)
	Sets the next image to display.

void	SetImage (std::shared_ptr< Request > pRequest)
	Sets the next image to display.

void	SetInterpolationMode (TInterpolationMode mode)
	Sets the new interpolation mode that will be used for scaling if display window rectangle is different to input image rectangle.

void	SetOverlayCallbackFunction (TImageDisplayOverlayFunction fctOverlay, void *pUserParam)
	Installs an overlay callback function.

void	SetShift (int shift)
	Sets the shift value that shall be subtracted from the shift value needed to display the 8 msb of a pixel.

void	SetWindowHandle (WindowHandle hwnd)
	Assigns a new destination window handle to a display object.

void	Update (void) const
	Immediately redraws the current image.

	~ImageDisplay ()
	Frees the resources previously allocated.

Static Public Member Functions
static bool	ConvertFormatFromPFNC32 (const unsigned int pixelFormat, TFormatFlags pFormat, int pBitsPerPixel)
	Converts a PFNC pixel format into a format that can be digested by this module.

Friends
class	ImageDisplayWindow

Detailed Description

A class that can be used for displaying images within existing windows or GUI elements that can provide a window handle.

Instances of this class can be associated with an existing window object of which the window handle is known and can be passed to the constructor of this class.

The full client area of a window will be consumed by a display object. Where the actual image shall be display relative to the upper left corner of the windows client area can be defined by calling mvIMPACT::acquire::display::ImageDisplay::SetDisplayRectangle(). This function will also limit the area where image data will be displayed. The area outside the display rectangle but within the windows client area can be filled by defining a background brush and then attach this brush to the display by calling mvIMPACT::acquire::display::ImageDisplay::SetBackgroundBrush().

If the actual image size differs from the area defined by mvIMPACT::acquire::display::ImageDisplay::SetDisplayRectangle(), it depends on the display mode if the complete image is scaled, cropped of just drawn in the top left corner of the display rectangle. The display mode can be modified by calling mvIMPACT::acquire::display::ImageDisplay::SetDisplayMode().

In addition to that only a part of the actual image can be selected for drawing by the function mvIMPACT::acquire::display::ImageDisplay::SetBitmapRectangle(). For this region the same scaling and cropping regions will be applied then.

Note: This class can be used without using the rest of Impact Acquire. This is achieved by using a pre-processor check for the presence of a certain include guard that is defined by Impact Acquire. Now in order to be able to use those functions, that can directly work on data types as defined by Impact Acquire, the main Impact Acquire header must be included BEFORE including this header:

#include <mvIMPACT_CPP/mvIMPACT_acquire.h>

#include <mvDisplay/Include/mvIMPACT_acquire_display.h>

See also: mvIMPACT::acquire::display::ImageDisplay::SetDisplayRectangle(),
mvIMPACT::acquire::display::ImageDisplay::SetBitmapRectangle(),
mvIMPACT::acquire::display::ImageDisplay::SetBackgroundBrush(),
mvIMPACT::acquire::display::ImageDisplay::SetDisplayMode()

Examples: ContinuousCapture.win32.cpp, ContinuousCaptureAllDevices.cpp, ContinuousCaptureAllDevices.win32.cpp, ContinuousCaptureMultiPart.cpp, ContinuousCaptureMultiPart.legacy.cpp, ContinuousCaptureOnlyProcessLatest.cpp, ContinuousCaptureOnlyProcessLatest.legacy.cpp, ContinuousCaptureToAVIFile.cpp, GenICamCallbackOnEvent.cpp, GenICamSmartFrameRecallUsage.cpp, GenICamSmartFrameRecallUsage.legacy.cpp, SequenceCapture.cpp, SequenceCapture.win32.cpp, SingleCaptureMasterSlave.cpp, SingleCaptureMasterSlave.legacy.cpp, and TimestampFeatures.cpp.

Constructor & Destructor Documentation

◆ ImageDisplay()

ImageDisplay ( WindowHandle hwnd )

inlineexplicit

Create a new object that can be used for displaying images.

Parameters

hwnd	A handle to the window which should be used for the displaying.

◆ ~ImageDisplay()

~ImageDisplay ( )

inline

Frees the resources previously allocated.

Member Function Documentation

◆ Clear()

void Clear ( void ) const

inline

Clears the display.

Either the windows default background will be displayed afterwards or if a background brush has been defined the background brush will be used to fill the complete client area.

See also: mvIMPACT::acquire::display::ImageDisplay::SetBackgroundBrush()

◆ ConvertFormatFromPFNC32()

static bool ConvertFormatFromPFNC32	(	const unsigned int	pixelFormat,
		TFormatFlags *	pFormat,
		int *	pBitsPerPixel )

inlinestatic

Converts a PFNC pixel format into a format that can be digested by this module.

Returns

true if successful.
false when the PFNC format cannot be displayed properly by this module.

Parameters

[in]	pixelFormat	The PFNC pixel format to convert as unsigned int.
[out]	pFormat	A pointer to variable that receives the format flags that can be passed to functions of this library.
[out]	pBitsPerPixel	A pointer to variable that receives the bits per pixel for the format specified by mvIMPACT::acquire::display::TFormatFlags.

◆ GetAppliedShift()

int GetAppliedShift ( void ) const

inline

Returns the current shift value that has been applied to the last image that has been displayed.

This function returns the shift value that has been applied to the last image that has been displayed. See mvIMPACT::acquire::display::ImageDisplay::SetShift for a detailed explanation about the display behaviour when applying custom shift values.

See also: mvIMPACT::acquire::display::ImageDisplay::SetShift,
mvIMPACT::acquire::display::ImageDisplay::GetShift

Since: 2.4.0

Returns: The current shift value that has been applied to the last image that has been displayed.

◆ GetDisplayMode()

TDisplayMode GetDisplayMode ( void ) const

inline

Returns the current display mode.

Valid display modes are defined by mvIMPACT::acquire::display::TDisplayMode.

Returns: The current display mode.

◆ GetImage()

void GetImage	(	const void **	ppData,
		int *	pWidth,
		int *	pHeight,
		int *	pBitsPerPixel,
		int *	pPitch )

inline

Gets the parameters of the current data block associated with the display.

If a parameter is not needed it might be 0(NULL).

The data returned will always be in packed format.

Parameters

[out]	ppData	A pointer to a variable to receive the storage location of the pixel data. This can be 0 if the value is not needed.
[out]	pWidth	A pointer to a variable to receive the width of the current image. This can be 0 if the value is not needed.
[out]	pHeight	A pointer to a variable to receive the height of the current image. This can be 0 if the value is not needed.
[out]	pBitsPerPixel	A pointer to a variable to receive the bits per pixel of the current image. This can be 0 if the value is not needed.
[out]	pPitch	A pointer to a variable to receive the pitch (bytes per pixel * width in pixel)of the current image. This can be 0 if the value is not needed.

◆ GetInterpolationMode()

TInterpolationMode GetInterpolationMode ( void ) const

inline

Gets the current interpolation mode that will be used for scaling if display window rectangle is different to input image rectangle.

Valid interpolation modes are defined by mvIMPACT::acquire::display::TInterpolationMode.

Returns: The current interpolation mode.

◆ GetLastError()

int GetLastError ( void ) const

inline

Returns the last error and clears it.

If an error has occurred it will not be overwritten by subsequent errors till the error is queried and cleared. After calling this function a second call would return mvIMPACT::acquire::display::IDE_NoError until another error occurs.

Returns: The last error

◆ GetShift()

int GetShift ( void ) const

inline

Returns the current shift value as defined by the application.

This function returns the current shift value as defined by the application by previous calls to mvIMPACT::acquire::display::ImageDisplay::SetShift. See mvIMPACT::acquire::display::ImageDisplay::SetShift for a detailed explanation about the display behaviour when applying custom shift values.

See also: mvIMPACT::acquire::display::ImageDisplay::SetShift,
mvIMPACT::acquire::display::ImageDisplay::GetAppliedShift

Since: 2.4.0

Returns: The current shift value from previous calls to mvIMPACT::acquire::display::ImageDisplay::SetShift.

◆ GetWindowHandle()

WindowHandle GetWindowHandle ( void ) const

inline

Returns the current window handle associated with the display object.

Returns: The current window handle associated with the display object.

◆ RemoveImage()

void RemoveImage ( void )

inline

Removes the current image from the display.

This function will remove the current image attached to the display from the display again. This is mainly meant to be able to free the memory associated with the image buffer without the risk that a later call to an update function or a repaint message would cause another redraw of then freed memory. As only one buffer can be attached to a display at any given time calling mvIMPACT::acquire::display::ImageDisplay::SetImage will effectively remove the previous image as well so this function usually is only needed when ending e.g. a live display.

Examples: ContinuousCapture.win32.cpp, ContinuousCaptureAllDevices.win32.cpp, ContinuousCaptureOnlyProcessLatest.cpp, ContinuousCaptureOnlyProcessLatest.legacy.cpp, ContinuousCaptureToAVIFile.cpp, GenICamCallbackOnEvent.cpp, SequenceCapture.win32.cpp, SingleCaptureMasterSlave.cpp, and SingleCaptureMasterSlave.legacy.cpp.

◆ SetBackgroundBrush()

void SetBackgroundBrush ( BrushHandle hBrush )

inline

Associates a brush to be used for painting the background within the client area.

See mvDispInit() for a detailed description on which regions will be painted using the background brush.

Attention: This only stores the handle to the brush object, not the actual brush, so as long as this handle is set and the display object is used, the referenced brush must NOT be deleted again.

Parameters

[in] hBrush Handle to the brush to be used to paint the background. This brush then will be used to paint the regions of the rectangle used for drawing that will not painted with the image itself.

◆ SetBitmapRectangle()

void SetBitmapRectangle	(	int	left,
		int	top,
		int	width,
		int	height )

inline

Sets the position and dimension of bitmap data region.

This defines the area relative within the area consumed by the window associated with the window handle that is bound to this display. See mvIMPACT::acquire::display::ImageDisplay for a detailed description on how to define the different rectangles and areas for drawing.

See also: mvIMPACT::acquire::display::ImageDisplay
mvIMPACT::acquire::display::ImageDisplay::SetDisplayRectangle()

Parameters

[in]	left	The left offset of the rectangle.
[in]	top	The top offset of the rectangle.
[in]	width	The width of the bitmap rectangle.
[in]	height	The height of the rectangle.

◆ SetDDrawOverlayKeyColor()

void SetDDrawOverlayKeyColor ( ColorValue keyColor )

inline

Defines the key color for the DirectDraw® overlay.

Parameters

[in] keyColor The key color to be used for the DirectDraw® overlay.

◆ SetDisplayMode()

void SetDisplayMode ( TDisplayMode mode )

inline

Switches to a different display mode.

Parameters

[in] mode The new display mode.

◆ SetDisplayRectangle()

void SetDisplayRectangle	(	int	left,
		int	top,
		int	width,
		int	height )

inline

Defines the rectangle used for drawing within the window associated with the display structure.

This function can be used to define a rectangle within the defined window Only this then will be used for drawing. This window can be smaller than the image defined by mvIMPACT::acquire::display::ImageDisplay::SetImage(). Then just a part of the image will be displayed when in mvIMPACT::acquire::display::DM_Fastest or the whole image will be scaled down to fit into the rectangle when in mvIMPACT::acquire::display::DM_Default mode.

When the display rectangle is larger than the image the image will be placed in the lower left corner of the display rectangle (either scaled or unscaled). See ImageDisplay for a detailed description on how to define the different rectangles and areas for drawing.

See also: mvIMPACT::acquire::display::ImageDisplay,
mvIMPACT::acquire::display::ImageDisplay::SetBitmapRectangle

Parameters

[in]	left	The left offset within the window.
[in]	top	The top offset within the window.
[in]	width	The width of the rectangle to use for drawing.
[in]	height	The height of the rectangle to use for drawing.

◆ SetImage() [1/5]

void SetImage ( const mvIMPACT::acquire::ImageBuffer * pBuf )

inline

Sets the next image to display.

This function can deal with any pixel format supported by Impact Acquire.

Parameters

[in] pBuf The image buffer object that shall be displayed.

◆ SetImage() [2/5]

void SetImage ( const mvIMPACT::acquire::Request * pRequest )

inline

Sets the next image to display.

This function can deal with any pixel format supported by Impact Acquire.

Parameters

[in] pRequest The mvIMPACT::acquire::Request object whose image data shall be displayed.

◆ SetImage() [3/5]

void SetImage	(	const void **	ppData,
		size_t	ppDataArraySize,
		TFormatFlags	format,
		int	width,
		int	height,
		int	bitsPerPixel,
		int	pitch )

inline

Sets the next image to display.

Parameters

[in]	ppData	An array of pointers that point to the actual image data For planar RGB images e.g. this can be 3 pointers each pointing to one color plane.
[in]	ppDataArraySize	The number of pointers passed via ppData.
[in]	format	The pixel format as defined by mvIMPACT::acquire::display::TFormatFlags.
[in]	width	The width of the image.
[in]	height	The height of the image.
[in]	bitsPerPixel	The number of bits per pixel.
[in]	pitch	The pitch in bytes of one line of pixel data (bytes per pixel * width in pixel per line).

◆ SetImage() [4/5]

void SetImage	(	const void *	pData,
		int	width,
		int	height,
		int	bitsPerPixel,
		int	pitch )

inline

Sets the next image to display.

This function can deal with RGB888x packed images, 8 bit grey-scale images and 16 bit Packed RGB images. For other formats overloaded versions of this function must be used.

Parameters

[in]	pData	A pointer to the address of the pixel data.
[in]	width	The width of the image.
[in]	height	The height of the image.
[in]	bitsPerPixel	The number of bits per pixel.
[in]	pitch	The pitch in bytes of one line of pixel data (bytes per pixel * width in pixel per line).

Examples: ContinuousCapture.win32.cpp, ContinuousCaptureAllDevices.cpp, ContinuousCaptureAllDevices.win32.cpp, ContinuousCaptureMultiPart.cpp, ContinuousCaptureMultiPart.legacy.cpp, ContinuousCaptureOnlyProcessLatest.cpp, ContinuousCaptureOnlyProcessLatest.legacy.cpp, ContinuousCaptureToAVIFile.cpp, GenICamCallbackOnEvent.cpp, GenICamSmartFrameRecallUsage.cpp, GenICamSmartFrameRecallUsage.legacy.cpp, GenericInterfaceLayout.legacy.cpp, Properties.legacy.cpp, SequenceCapture.cpp, SequenceCapture.win32.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, SingleCaptureMasterSlave.legacy.cpp, and TimestampFeatures.cpp.

◆ SetImage() [5/5]

void SetImage ( std::shared_ptr< Request > pRequest )

inline

Sets the next image to display.

This function can deal with any pixel format supported by Impact Acquire.

Parameters

[in] pRequest The mvIMPACT::acquire::Request object whose image data shall be displayed.

◆ SetInterpolationMode()

void SetInterpolationMode ( TInterpolationMode mode )

inline

Sets the new interpolation mode that will be used for scaling if display window rectangle is different to input image rectangle.

Parameters

[in] mode The new interpolation mode.

◆ SetOverlayCallbackFunction()

void SetOverlayCallbackFunction	(	TImageDisplayOverlayFunction	fctOverlay,
		void *	pUserParam )

inline

Installs an overlay callback function.

This function will be called when operated in mvIMPACT::acquire::display::DM_Default mode and can be used to draw a user defined overlay on top of the image before it is displayed.

Parameters

[in]	fctOverlay	The address of the function to be called for a user defined overlay
[in]	pUserParam	A pointer to a user defined parameter

◆ SetShift()

void SetShift ( int shift )

inline

Sets the shift value that shall be subtracted from the shift value needed to display the 8 msb of a pixel.

This function will allow to select which 8 bits out of a multi-byte pixel format shall be displayed the next time mvIMPACT::acquire::display::ImageDisplay::Update is called. When the shift value is 0 the 8 msb of each pixel will be displayed so e.g. for a 12 bit format bits 11 to 4 will be displayed by default.

Consider the typical layout of 12 mono pixel data in memory:

So with an application defined shift value of 0 (the default), the display module will shift each 2 byte pixel by 4 positions to the right. This will remove the 4 lsb from the data. Afterwards the now empty upper byte of each pixel is removed from the data resulting in the following memory layout which is then displayed on the canvas:

Now sometimes it is required to display other bits from the image e.g. for analysis purposes. As most operating systems only support to display 8 bits per color component this requires to select a different range of pixels to be sent to the canvas. This can be done by calling this function and passing a custom shift value to it. The custom shift value will be subtracted from the value that would be needed to display the 8 msb for a given format.

So to display the 8 lsb for a 12 bit mono format, shift must be set to 4. This then results in the display module to use a actual shift value of 4(required to display the 8 msb) - 4(defined by calling this function) = 0. Then removing the upper byte from each pixel results in only the 8 lsb of each pixel being displayed.

When e.g. setting shift to 3 for a 12 bit mono for would result in bits 8 - 1 to be displayed:

The shift value that has actually been applied the last time an image has been displayed (thus '1' when taking the example in the image above (4(required) - 3(defined))) can be queried by calling mvIMPACT::acquire::display::ImageDisplay::GetAppliedShift.

Note: During the conversion from a multi-byte to a single byte format the pixel data will be clipped to 255 if a pixel value is larger than what can be stored in a single byte after the shift operation.

See also: mvIMPACT::acquire::display::ImageDisplay::GetShift,
mvIMPACT::acquire::display::ImageDisplay::GetAppliedShift

Since: 2.4.0

Parameters

[in] shift The shift value to apply to the displayed images. The maximum value for this function is 8, the minimum 0. Values out of this range will be ignored. It is NOT possible to shift pixel data in such a way that less than 8 bits contain valid data, thus e.g. a shift value of 2 applied to 8 bit mono data will be ignored.

◆ SetWindowHandle()

void SetWindowHandle ( WindowHandle hwnd )

inline

Assigns a new destination window handle to a display object.

Parameters

[in] hwnd The handle of the new destination window.

◆ Update()

void Update ( void ) const

inline

Immediately redraws the current image.

Examples: ContinuousCapture.win32.cpp, ContinuousCaptureAllDevices.cpp, ContinuousCaptureAllDevices.win32.cpp, ContinuousCaptureMultiPart.cpp, ContinuousCaptureMultiPart.legacy.cpp, ContinuousCaptureOnlyProcessLatest.cpp, ContinuousCaptureOnlyProcessLatest.legacy.cpp, ContinuousCaptureToAVIFile.cpp, GenICamCallbackOnEvent.cpp, GenICamSmartFrameRecallUsage.cpp, GenICamSmartFrameRecallUsage.legacy.cpp, GenericInterfaceLayout.legacy.cpp, Properties.legacy.cpp, SequenceCapture.cpp, SequenceCapture.win32.cpp, SingleCapture.cpp, SingleCaptureMasterSlave.cpp, SingleCaptureMasterSlave.legacy.cpp, and TimestampFeatures.cpp.

Friends And Related Symbol Documentation

◆ ImageDisplayWindow

friend class ImageDisplayWindow

friend

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ImageDisplay()

◆ ~ImageDisplay()

Member Function Documentation

◆ Clear()

◆ ConvertFormatFromPFNC32()

◆ GetAppliedShift()

◆ GetDisplayMode()

◆ GetImage()

◆ GetInterpolationMode()

◆ GetLastError()

◆ GetShift()

◆ GetWindowHandle()

◆ RemoveImage()

◆ SetBackgroundBrush()

◆ SetBitmapRectangle()

◆ SetDDrawOverlayKeyColor()

◆ SetDisplayMode()

◆ SetDisplayRectangle()

◆ SetImage() [1/5]

◆ SetImage() [2/5]

◆ SetImage() [3/5]

◆ SetImage() [4/5]

◆ SetImage() [5/5]

◆ SetInterpolationMode()

◆ SetOverlayCallbackFunction()

◆ SetShift()

◆ SetWindowHandle()

◆ Update()

Friends And Related Symbol Documentation

◆ ImageDisplayWindow