Pylon::CPylonBitmapImage#

Module: Image Handling Support

This class can be used to easily create Windows bitmaps for displaying images. More…

#include <pylon/PylonBitmapImage.h>

Inherits from Pylon::CPylonImageBase, Pylon::IReusableImage, Pylon::IImage

Public Functions#

Additional inherited members#

Public Functions inherited from Pylon::IReusableImage

Public Functions inherited from Pylon::IImage

Detailed Description#

class Pylon::CPylonBitmapImage;

This class can be used to easily create Windows bitmaps for displaying images.

Buffer Handling:

The bitmap buffer that is automatically created by the CPylonBitmapImage class. The Release() method can be used to release a bitmap.

Thread Safety:

The CPylonBitmapImage class is not thread-safe.

• Automatically handles the bitmap creation and lifetime.
• Provides methods for loading and saving an image in different file formats.
• Serves as target format for the CImageFormatConverter image format converter.

Public Functions Documentation#

function CPylonBitmapImage#

CPylonBitmapImage()

Creates an invalid image.

Error Safety:

Does not throw C++ exceptions.

See Pylon::IImage on how the properties of an invalid image are returned.

function CPylonBitmapImage#

CPylonBitmapImage(
    const CPylonBitmapImage & source
)

Copies the image properties and creates a reference to the bitmap of the source image.

Parameters:

• source The source image.

Postcondition:

• Another reference to the source bitmap is created.
• Creates an invalid image if the source image is invalid.

Error Safety:

Does not throw C++ exceptions.

function ~CPylonBitmapImage#

virtual ~CPylonBitmapImage()

Destroys a pylon image object.

Attention: The bitmap handle must not be currently selected into a DC. Otherwise the bitmap is not freed.

Error Safety:

Does not throw C++ exceptions.

function operator=#

virtual CPylonBitmapImage & operator=(
    const CPylonBitmapImage & source
)

Copies the image properties and creates a reference to the bitmap of the source image.

Parameters:

• source The source image.

Postcondition:

• Another reference to the source bitmap is created.
• Creates an invalid image if the source image is invalid.

Error Safety:

Does not throw C++ exceptions.

function CopyImage#

virtual void CopyImage(
    const IImage & image
)

Copies the image data from a different image.

Parameters:

• image The source image, e.g. a CPylonImage, CPylonBitmapImage, or Grab Result Smart Pointer object.

Precondition: The preconditions of the Reset() method must be met.

Postcondition:

• The source image is automatically converted.
• Creates an invalid image if the source image is invalid.

Error Safety:

Throws an exception when the bitmap could not be created. Throws an exception when the preconditions of the Reset() method are not met.

The input image is automatically converted if needed to PixelType_Mono8 if Pylon::IsMonoImage( pixelTypeSource) is true, otherwise it is converted to PixelType_BGR8packed. The orientation of the image is changed to bottom up.

If more control over the conversion is required, the CImageFormatConverter class can be used to convert other images with a CPylonBitmapImage object as target.

function CopyImage#

virtual void CopyImage(
    const void * pBuffer,
    size_t bufferSizeBytes,
    EPixelType pixelType,
    uint32_t width,
    uint32_t height,
    size_t paddingX,
    EImageOrientation orientation
)

Sets an image from a user buffer.

Parameters:

• pBuffer The pointer to the buffer of the source image.
• bufferSizeBytes The size of the buffer of the source image.
• pixelType The pixel type of the source image.
• width The number of pixels in a row in the source image.
• height The number of rows in the source image.
• paddingX The number of extra data bytes at the end of each row.
• orientation The vertical orientation of the image in the image buffer.

Precondition:

• The pixel type must be valid.
• The width value must be >= 0 and < _I32_MAX.
• The height value must be >= 0 and < _I32_MAX.
• The pointer to the source buffer must not be NULL.
• The source buffer must be large enough to hold the image described by the parameters.
• The preconditions of the Reset() method must be met.

Postcondition: The source image is automatically converted. See CopyImage().

Error Safety:

Throws an exception when when the bitmap could not be created. Throws an exception when the preconditions of the Reset() method are not met.

function IsValid#

virtual bool IsValid() const

Can be used to check whether an image is valid.

Return: Returns false if the image is invalid.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::IsValid

function GetPixelType#

virtual EPixelType GetPixelType() const

Get the current pixel type.

Return: Returns the pixel type or PixelType_Undefined if the image is invalid.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::GetPixelType

function GetWidth#

virtual uint32_t GetWidth() const

Get the current number of columns in pixels.

Return: Returns the current number of columns in pixels or 0 if the image is invalid.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::GetWidth

function GetHeight#

virtual uint32_t GetHeight() const

Get the current number of rows.

Return: Returns the current number of rows or 0 if the image is invalid.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::GetHeight

function GetPaddingX#

virtual size_t GetPaddingX() const

Get the number of extra data bytes at the end of each row.

Return: Returns the number of extra data bytes at the end of each row or 0 if the image is invalid.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::GetPaddingX

function GetOrientation#

virtual EImageOrientation GetOrientation() const

Get the vertical orientation of the image in memory.

Return: Returns the orientation of the image or ImageOrientation_TopDown if the image is invalid.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::GetOrientation

function GetBuffer#

virtual void * GetBuffer()

Get the pointer to the buffer.

Return: Returns the pointer to the used buffer or NULL if the image is invalid.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::GetBuffer

function GetBuffer#

virtual const void * GetBuffer() const

Get the pointer to the buffer containing the image.

Return: Returns the pointer to the used buffer or NULL if the image is invalid.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::GetBuffer

The buffer is at least as large as the value returned by GetImageSize().

function GetImageSize#

virtual size_t GetImageSize() const

Get the size of the image in bytes.

Return: Returns the size of the image in bytes or 0 if the image is invalid.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::GetImageSize

function IsUnique#

virtual bool IsUnique() const

Indicates that the referenced buffer is only referenced by this image.

Return: Returns true if the referenced buffer is only referenced by this image. Returns false if the image is invalid.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::IsUnique

function GetStride#

virtual bool GetStride(
    size_t & strideBytes
) const

Get the stride in bytes.

Parameters:

• strideBytes The stride in byte if it can be computed.

Return: Returns true if the stride can be computed.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::GetStride

The stride in bytes can not be computed for packed image format when the stride is not byte aligned. See also Pylon::IsPacked(). The stride in bytes can not be computed if the image is invalid.

function IsSupportedPixelType#

virtual bool IsSupportedPixelType(
    EPixelType pixelType
) const

Can be used to check whether the pixel type is supported.

Return: Returns true if the pixel type is supported.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::IsSupportedPixelType

function IsAdditionalPaddingSupported#

virtual bool IsAdditionalPaddingSupported() const

Can be used to check whether the value of PaddingX can be defined by the user.

Return: Returns true if the value of PaddingX can be defined by the user.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::IsAdditionalPaddingSupported

function Reset#

virtual void Reset(
    EPixelType pixelType,
    uint32_t width,
    uint32_t height,
    EImageOrientation orientation =ImageOrientation_BottomUp
)

Resets the image properties and creates a new Windows bitmap if required.

Parameters:

• pixelType The pixel type of the new image.
• width The number of pixels in a row in the new image.
• height The number of rows in the new image.
• orientation The vertical orientation of the image in the image buffer.

Precondition:

• The width value must be > 0 and < _I32_MAX.
• The height value must be > 0 and < _I32_MAX.

Postcondition:

• If the previously referenced bitmap is also referenced by another pylon bitmap image, a new Windows bitmap is created.
• If the previously referenced bitmap is able to hold an image with the given properties, a new Windows bitmap is created.
• If no bitmap has been created before, a new Windows bitmap is created.

Error Safety:

Throws an exception when the preconditions are not met. Throws an exception when no buffer with the required size could be allocated.

Reimplements: Pylon::CPylonImageBase::Reset

function Release#

virtual void Release()

Releases the image buffer and resets to an invalid image.

Postcondition:

• PixelType = PixelType_Undefined.
• Width = 0.
• Height = 0.
• PaddingX = 0.
• No buffer is allocated.

Error Safety:

Does not throw C++ exceptions.

Reimplements: Pylon::CPylonImageBase::Release

function operator HBITMAP#

virtual operator HBITMAP() const

Get the handle of the windows bitmap.

Return: Returns the handle of the windows bitmap or NULL if the image is invalid.

Attention: The handle must not be freed using DeleteObject(). The handle is invalid after calling Release(). The handle may be invalid after calling Reset().

Error Safety:

Does not throw C++ exceptions.

function Detach#

virtual HBITMAP Detach()

Detach the windows bitmap.

Return: Returns the handle of the windows bitmap or NULL if the image is invalid.

Precondition: IsUnique() must return true. No other image must reference the bitmap.

Postcondition:

• The image is invalid.
• The ownership of the bitmap goes to the caller who is responsible for deleting it.

Error Safety:

Does not throw C++ exceptions.

function Save#

virtual void Save(
    EImageFileFormat imageFileFormat,
    const String_t & filename,
    CImagePersistenceOptions * pOptions =NULL
) const

Saves the image to disk.

Parameters:

• imageFileFormat File format to save the image in.
• filename Name and path of the image.
• pOptions Additional options.

Precondition: The pixel type of the image to be saved must be a supported input format of the Pylon::CImageFormatConverter.

Error Safety:

Throws an exception if the saving of the image fails.

Converts the image to a format that can be saved if required.

This is a convenience method that calls CImagePersistence::Save().

If required, the image is automatically converted into a new image and saved afterwards. See CImagePersistence::CanSaveWithoutConversion() for more information. An image with a bit depth higher than 8 bit is stored with 16 bit bit depth, if supported by the image file format. In this case the pixel data is MSB aligned.

If more control over the conversion is required, the CImageFormatConverter class can be used to convert the input image before saving it.

function Load#

virtual void Load(
    const String_t & filename
)

Loads an image from a disk.

Parameters:

• filename Name and path of the image.

Precondition: The image object must be able to hold the image format of the loaded image.

Error Safety:

Throws an exception if the image cannot be loaded. The image buffer content is undefined when the loading of the image fails.

This is a convenience method that calls CImagePersistence::Load()

function CanSaveWithoutConversion#

virtual bool CanSaveWithoutConversion(
    EImageFileFormat imageFileFormat
) const

Can be used to check whether the image can be saved without prior conversion.

Parameters:

• imageFileFormat Target file format for the image to be saved.

Return: Returns true, if the image can be saved without prior conversion.

Error Safety:

Does not throw C++ exceptions.

This is a convenience method that calls CImagePersistence::CanSaveWithoutConversion().

function GetPixelData#

virtual SPixelData GetPixelData(
    uint32_t posX,
    uint32_t posY
) const

Retrieves the data of a pixel.

Parameters:

• posX Horizontal position of the pixel. The first column has position 0.
• posY Vertical position of the pixel. The first row has position 0.

Return: Returns the data of a pixel for supported pixel types. For unsupported pixel types pixel data of the [SPixelData::PixelDataType_Unknown](struct_pylon_1_1_s_pixel_data.md type is returned.

Note This method is relativly slow. Do not use it for image processing tasks.

Precondition:

• The image must be valid.
• The pixel position defined by posX and posY must be located inside the image area.

Error Safety:

Throws an exception, if the preconditions are not met.

Supported pixel types:

• PixelType_Mono1packed
• PixelType_Mono2packed
• PixelType_Mono4packed
• PixelType_Mono8
• PixelType_Mono8signed
• PixelType_Mono10
• PixelType_Mono10packed
• PixelType_Mono10p
• PixelType_Mono12
• PixelType_Mono12packed
• PixelType_Mono12p

• PixelType_Mono16

• PixelType_BayerGR8

• PixelType_BayerRG8
• PixelType_BayerGB8
• PixelType_BayerBG8
• PixelType_BayerGR10
• PixelType_BayerRG10
• PixelType_BayerGB10
• PixelType_BayerBG10
• PixelType_BayerGR12
• PixelType_BayerRG12
• PixelType_BayerGB12
• PixelType_BayerBG12
• PixelType_BayerGR12Packed
• PixelType_BayerRG12Packed
• PixelType_BayerGB12Packed
• PixelType_BayerBG12Packed
• PixelType_BayerGR10p
• PixelType_BayerRG10p
• PixelType_BayerGB10p
• PixelType_BayerBG10p
• PixelType_BayerGR12p
• PixelType_BayerRG12p
• PixelType_BayerGB12p
• PixelType_BayerBG12p
• PixelType_BayerGR16
• PixelType_BayerRG16
• PixelType_BayerGB16

• PixelType_BayerBG16

• PixelType_RGB8packed

• PixelType_BGR8packed
• PixelType_RGBA8packed
• PixelType_BGRA8packed
• PixelType_RGB10packed
• PixelType_BGR10packed
• PixelType_RGB12packed
• PixelType_BGR12packed
• PixelType_RGB12V1packed
• PixelType_RGB16packed
• PixelType_RGB8planar
• PixelType_RGB10planar
• PixelType_RGB12planar

• PixelType_RGB16planar

• PixelType_YUV422packed

• PixelType_YUV422_YUYV_Packed

function Create#

static CPylonBitmapImage Create(
    EPixelType pixelType,
    uint32_t width,
    uint32_t height,
    EImageOrientation orientation =ImageOrientation_BottomUp
)

Creates an image and a Windows bitmap for it.

Parameters:

• pixelType The pixel type of the new image.
• width The number of pixels in a row in the new image.
• height The number of rows in the new image.
• orientation The vertical orientation of the image in the image buffer.

Precondition:

• The pixel type must be supported, see IsSupportedPixelType().
• The width value must be > 0 and < _I32_MAX.
• The height value must be > 0 and < _I32_MAX.

Error Safety:

Throws an exception when the parameters are invalid. Throws an exception when the bitmap could not be created.