mvIMPACT Acquire SDK C++
ImageDisplay Class Reference

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

Public Member Functions

void Clear (void) const
 Clears the display. More...
 
int GetAppliedShift (void) const
 Returns the current shift value that has been applied to the last image that has been displayed. More...
 
TDisplayMode GetDisplayMode (void) const
 Returns the current display mode. More...
 
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. More...
 
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. More...
 
int GetLastError (void) const
 Returns the last error and clears it. More...
 
int GetShift (void) const
 Returns the current shift value as defined by the application. More...
 
WindowHandle GetWindowHandle (void) const
 Returns the current window handle associated with the display object. More...
 
 ImageDisplay (WindowHandle hwnd)
 Create a new object that can be used for displaying images. More...
 
void RemoveImage (void)
 Removes the current image from the display. More...
 
void SetBackgroundBrush (BrushHandle hBrush)
 Associates a brush to be used for painting the background within the client area. More...
 
void SetBitmapRectangle (int left, int top, int width, int height)
 Sets the position and dimension of bitmap data region. More...
 
void SetDDrawOverlayKeyColor (ColorValue keyColor)
 Defines the key color for the DirectDraw® overlay. More...
 
void SetDisplayMode (TDisplayMode mode)
 Switches to a different display mode. More...
 
void SetDisplayRectangle (int left, int top, int width, int height)
 Defines the rectangle used for drawing within the window associated with the display structure. More...
 
void SetImage (const mvIMPACT::acquire::ImageBuffer *pBuf)
 Sets the next image to display. More...
 
void SetImage (const mvIMPACT::acquire::Request *pRequest)
 Sets the next image to display. More...
 
void SetImage (const void **ppData, size_t ppDataArraySize, TFormatFlags format, int width, int height, int bitsPerPixel, int pitch)
 Sets the next image to display. More...
 
void SetImage (const void *pData, int width, int height, int bitsPerPixel, int pitch)
 Sets the next image to display. More...
 
void SetImage (std::shared_ptr< Request > pRequest)
 Sets the next image to display. More...
 
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. More...
 
void SetOverlayCallbackFunction (TImageDisplayOverlayFunction fctOverlay, void *pUserParam)
 Installs an overlay callback function. More...
 
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. More...
 
void SetWindowHandle (WindowHandle hwnd)
 Assigns a new destination window handle to a display object. More...
 
void Update (void) const
 Immediately redraws the current image. More...
 
 ~ImageDisplay ()
 Frees the resources previously allocated. More...
 

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 mvIMPACT Acquire. This is achieved by using a pre-processor check for the presence of a certain include guard that is defined by mvIMPACT Acquire. Now in order to be able to use those functions, that can directly work on data types as defined by mvIMPACT Acquire, the main mvIMPACT Acquire header must be included BEFORE including this header:
See also
mvIMPACT::acquire::display::ImageDisplay::SetDisplayRectangle(),
mvIMPACT::acquire::display::ImageDisplay::SetBitmapRectangle(),
mvIMPACT::acquire::display::ImageDisplay::SetBackgroundBrush(),
mvIMPACT::acquire::display::ImageDisplay::SetDisplayMode()

Constructor & Destructor Documentation

◆ ImageDisplay()

ImageDisplay ( WindowHandle  hwnd)
inlineexplicit

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

Parameters
hwndA 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()

◆ 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]ppDataA pointer to a variable to receive the storage location of the pixel data. This can be 0 if the value is not needed.
[out]pWidthA pointer to a variable to receive the width of the current image. This can be 0 if the value is not needed.
[out]pHeightA pointer to a variable to receive the height of the current image. This can be 0 if the value is not needed.
[out]pBitsPerPixelA 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]pPitchA 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.

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.

◆ 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]hBrushHandle 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]leftThe left offset of the rectangle.
[in]topThe top offset of the rectangle.
[in]widthThe width of the bitmap rectangle.
[in]heightThe height of the rectangle.

◆ SetDDrawOverlayKeyColor()

void SetDDrawOverlayKeyColor ( ColorValue  keyColor)
inline

Defines the key color for the DirectDraw® overlay.

Parameters
[in]keyColorThe key color to be used for the DirectDraw® overlay.

◆ SetDisplayMode()

void SetDisplayMode ( TDisplayMode  mode)
inline

Switches to a different display mode.

Parameters
[in]modeThe 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]leftThe left offset within the window.
[in]topThe top offset within the window.
[in]widthThe width of the rectangle to use for drawing.
[in]heightThe 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 mvIMPACT Acquire.

Parameters
[in]pBufThe 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 mvIMPACT Acquire.

Parameters
[in]pRequestThe 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]ppDataAn 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]ppDataArraySizeThe number of pointers passed via ppData.
[in]formatThe pixel format as defined by mvIMPACT::acquire::display::TFormatFlags.
[in]widthThe width of the image.
[in]heightThe height of the image.
[in]bitsPerPixelThe number of bits per pixel.
[in]pitchThe 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]pDataA pointer to the address of the pixel data.
[in]widthThe width of the image.
[in]heightThe height of the image.
[in]bitsPerPixelThe number of bits per pixel.
[in]pitchThe pitch in bytes of one line of pixel data (bytes per pixel * width in pixel per line).

◆ 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 mvIMPACT Acquire.

Parameters
[in]pRequestThe 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]modeThe 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]fctOverlayThe address of the function to be called for a user defined overlay
[in]pUserParamA 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 send 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]shiftThe 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]hwndThe handle of the new destination window.

◆ Update()

void Update ( void  ) const
inline

Immediately redraws the current image.

Friends And Related Function Documentation

◆ ImageDisplayWindow

friend class ImageDisplayWindow
friend

The documentation for this class was generated from the following file: