ImageDecompressor Class#

Provides convenient access to cameras that support image compression and helps with decompressing these images.

Inheritance Hierarchy#

System.Object
Basler.Pylon.ImageDecompressor

Syntax#

C#

public class ImageDecompressor : IDisposable

VB

Public Class ImageDecompressor
    Implements IDisposable

The ImageDecompressor type exposes the following members.

Constructors#

	Name	Description
	ImageDecompressor()	Creates an empty decompressor without compression descriptor.
	ImageDecompressor(Byte[])	Creates a decompressor and initializes it with the compression descriptor provided.
	ImageDecompressor(ICamera)	Creates a decompressor and initializes it with a compression descriptor that is retrieved from the camera.
	ImageDecompressor(ImageDecompressor)	Creates a decompressor by copying from another decompressor.
	ImageDecompressor(IntPtr, Int32)	Creates a decompressor and initializes it with the compression descriptor provided.

Properties#

	Name	Description
	CompressionDescriptor	Initializes or gets the currently set compression descriptor.
	CompressionDescriptorHash	Gets the hash of the currently set compression descriptor.
	HasCompressionDescriptor	Determines whether the decompressor already has a compression descriptor.

Methods#

	Name	Description
	ComputeCompressionDescriptorHash(Byte[])	Computes the hash for a given compression descriptor.
	ComputeCompressionDescriptorHash(IntPtr, Int32)	Computes the hash for a given compression descriptor.
	ComputeCompressionDescriptorHash(IntPtr, Int32, IntPtr, Int32)	Computes the hash for a given compression descriptor.
	DecompressImage(IntPtr, Int32, IGrabResult)	Decompresses the image of the grab result provided.
	DecompressImage(IntPtr, Int32, IntPtr, Int32)	Decompresses the image of the grab buffer provided.
	DecompressImage(T)(T[], IGrabResult)	Decompresses the image of the grab result provided.
	DecompressImage(T)(T[], IntPtr, Int32)	Decompresses the image of the grab buffer provided.
	Dispose	Releases all resources used by the ImageDecompressor
	Equals	Compares this instance with another decompressor. (Overrides Object.Equals(Object).)
	GetCompressionDescriptor(ICamera)	Gets the current compression descriptor from the camera.
	GetCompressionDescriptor(IntPtr, Int32)	Gets the currently set compression descriptor.
	GetCompressionDescriptor(IntPtr, Int32, ICamera)	Gets the current compression descriptor from the camera.
	GetCompressionDescriptorHash(ICamera)	Gets the hash of the current compression descriptor from the camera.
	GetCompressionDescriptorHash(IGrabResult)	Gets the hash of the compression descriptor that is required for decompressing the grab result provided.
	GetCompressionDescriptorHash(IGrabResult, Endianness)	Gets the hash of the compression descriptor that is required for decompressing the grab result provided.
	GetCompressionDescriptorHash(IntPtr, Int32)	Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.
	GetCompressionDescriptorHash(IntPtr, Int32)	Gets the hash of the currently set compression descriptor.
	GetCompressionDescriptorHash(IntPtr, Int32, Endianness)	Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.
	GetCompressionDescriptorHash(IntPtr, Int32, ICamera)	Gets the current compression descriptor hash from the camera.
	GetCompressionDescriptorHash(IntPtr, Int32, IGrabResult)	Gets the hash of the compression descriptor that is required for decompressing the grab result provided.
	GetCompressionDescriptorHash(IntPtr, Int32, IGrabResult, Endianness)	Gets the hash of the compression descriptor that is required for decompressing the grab result provided.
	GetCompressionDescriptorHash(IntPtr, Int32, IntPtr, Int32)	Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.
	GetCompressionDescriptorHash(IntPtr, Int32, IntPtr, Int32, Endianness)	Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.
	GetCompressionInfo(CompressionInfo, IGrabResult)	Gets compression information about a grab result.
	GetCompressionInfo(CompressionInfo, IGrabResult, Endianness)	Gets compression information about a grab result.
	GetCompressionInfo(CompressionInfo, IntPtr, Int32)	Gets compression information about a grab buffer.
	GetCompressionInfo(CompressionInfo, IntPtr, Int32, Endianness)	Gets compression information about a grab buffer.
	GetCompressionMode	Retrieves the current compression mode from the camera's node map.
	GetImageSizeForDecompression	Gets size (in bytes) required for allocating buffers for decompressing the images during streaming.
	ResetCompressionDescriptor	Resets the compression descriptor in the decompressor.
	SetCompressionDescriptor(ICamera)	Initializes a decompressor with a compression descriptor that is retrieved from the camera.
	SetCompressionDescriptor(IntPtr, Int32)	Initializes a decompressor with the compression descriptor provided.

Remarks#

A decompressor requires a compression descriptor in order to be able to decompress images. You can set a compression descriptor via the constructor or the SetCompressionDescriptor methods (in both cases, either using the node map or manually).

A compression descriptor can be identified via a hash. This hash can be used to identify the matching compression descriptor for a particular compressed image. It can be computed using one of the ComputeCompressionDescriptorHash methods or retrieved from the camera, decompressor, or a grab buffer/result using one of the GetCompressionDescriptorHash methods.

Grab buffers/results may contain different kinds of data. You can use the decompressor's GetCompressionInfo methods to distinguish between them. For that to work, a grab buffer/result must have been received successfully and it must contain the payload type chunk (for grab results you can get the payload type using the GetPayloadType method).

If compression info for the grab buffer/result provided is available, GetCompressionInfo returns true and you will receive the compression info via the CompressionInfo struct. If the field HasCompressedImage in the struct is true, the grab buffer/result contains a compressed image. In this case, you should check the CompressionStatus field in the struct to check whether the camera was able to compress the image properly. The camera can't compress an image if the amount of data required for compressing the image exceeds the desired compression rate. The image can be decompressed if CompressionStatus is Ok. If the field HasCompressedImage in the struct is false, the grab buffer/result contains an already decompressed image. In this case, the DecompressedImageSize and DecompressedPayloadSize fields will not be used. All other fields contain information about the decompressed data.

ImageDecompressor.ComputeCompressionDescriptorHash Method (Byte[])#

Computes the hash for a given compression descriptor.

Syntax#

C#

public static byte[] ComputeCompressionDescriptorHash(
    byte[] compressionDescriptor
)

VB

Public Shared Function ComputeCompressionDescriptorHash ( 
    compressionDescriptor As Byte()
) As Byte()

Parameters#

compressionDescriptor: Type: System.Byte[]
Array (one-dimensional) with the compression descriptor. This parameter must not be null.

Return Value#

Type: Byte[]
Returns an array (one-dimensional) with the hash of the given compression descriptor.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if no valid array with the compression descriptor is passed.

ImageDecompressor.ComputeCompressionDescriptorHash Method (IntPtr, Int32)#

Computes the hash for a given compression descriptor.

Syntax#

C#

public static byte[] ComputeCompressionDescriptorHash(
    IntPtr pCompressionDescriptor,
    int sizeCompressionDescriptor
)

VB

Public Shared Function ComputeCompressionDescriptorHash ( 
    pCompressionDescriptor As IntPtr,
    sizeCompressionDescriptor As Integer
) As Byte()

Parameters#

pCompressionDescriptor: Type: System.IntPtr
Pointer to the compression descriptor. This parameter must not be null.
sizeCompressionDescriptor: Type: System.Int32
Size of the data (in bytes) of the compression descriptor.

Return Value#

Type: Byte[]
Returns an array (one-dimensional) with the hash of the given compression descriptor.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the input parameters are invalid.

ImageDecompressor.ComputeCompressionDescriptorHash Method (IntPtr, Int32, IntPtr, Int32)#

Computes the hash for a given compression descriptor.

Syntax#

C#

public static void ComputeCompressionDescriptorHash(
    IntPtr pHash,
    ref int sizeHash,
    IntPtr pCompressionDescriptor,
    int sizeCompressionDescriptor
)

VB

Public Shared Sub ComputeCompressionDescriptorHash ( 
    pHash As IntPtr,
    ByRef sizeHash As Integer,
    pCompressionDescriptor As IntPtr,
    sizeCompressionDescriptor As Integer
)

Parameters#

pHash: Type: System.IntPtr
Pointer to the buffer that will receive the compression descriptor hash or null if you only want to get the size of the buffer for buffer allocation.
sizeHash: Type: System.Int32
On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not null). On output, the variable will receive the actual buffer size required for the current compression descriptor hash.
pCompressionDescriptor: Type: System.IntPtr
Pointer to the compression descriptor. This parameter must not be null.
sizeCompressionDescriptor: Type: System.Int32
Size of the data (in bytes) of the compression descriptor.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

ImageDecompressor.DecompressImage Method (IntPtr, Int32, IGrabResult)#

Decompresses the image of the grab result provided.

Syntax#

C#

public CompressionInfo DecompressImage(
    IntPtr pOutputBuffer,
    ref int sizeOutputBuffer,
    IGrabResult grabResult
)

VB

Public Function DecompressImage ( 
    pOutputBuffer As IntPtr,
    ByRef sizeOutputBuffer As Integer,
    grabResult As IGrabResult
) As CompressionInfo

Parameters#

pOutputBuffer: Type: System.IntPtr
Pointer to the buffer that will receive the decompressed image. This parameter must not be null.
sizeOutputBuffer: Type: System.Int32
On input, the variable specifies the size of the buffer (in bytes) for the decompressed image (must be larger or equal to the value in the DecompressedImageSize field in the CompressionInfo struct received via the GetCompressionInfo methods; alternatively, the GetImageSizeForDecompression(ICamera) method can be used to get the image size required for decompression). On output, the variable will receive the actual buffer size required for the decompressed image.
grabResult: Type: Basler.Pylon.IGrabResult
Grab result that holds the compressed data. This parameter must not be null.

Return Value#

Type: CompressionInfo
Returns the struct with the compression information of the compressed image.

Remarks#

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor property.

The grab result provided must contain a compressed image that has been received without errors.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab result does not contain compressed data, the data is corrupt, the image cannot be decompressed, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the decompressed image).

ImageDecompressor.DecompressImage Method (IntPtr, Int32, IntPtr, Int32)#

Decompresses the image of the grab buffer provided.

Syntax#

C#

public CompressionInfo DecompressImage(
    IntPtr pOutputBuffer,
    ref int sizeOutputBuffer,
    IntPtr pGrabBuffer,
    int payloadSize
)

VB

Public Function DecompressImage ( 
    pOutputBuffer As IntPtr,
    ByRef sizeOutputBuffer As Integer,
    pGrabBuffer As IntPtr,
    payloadSize As Integer
) As CompressionInfo

Parameters#

pOutputBuffer: Type: System.IntPtr
Pointer to the buffer that will receive the decompressed image. This parameter must not be null.
sizeOutputBuffer: Type: System.Int32
On input, the variable specifies the size of the buffer (in bytes) for the decompressed image (must be larger or equal to the value in the DecompressedImageSize field in the CompressionInfo struct received via the GetCompressionInfo methods; alternatively, the GetImageSizeForDecompression(ICamera) method can be used to get the image size required for decompression). On output, the variable will receive the actual buffer size required for the decompressed image.
pGrabBuffer: Type: System.IntPtr
Pointer to the grab buffer that holds the compressed data. This parameter must not be null.
payloadSize: Type: System.Int32
Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).

Return Value#

Type: CompressionInfo
Returns the struct with the compression information of the compressed image.

Remarks#

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor property.

The grab buffer provided must contain a compressed image that has been received without errors.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab buffer does not contain compressed data, the data is corrupt, the image cannot be decompressed, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the decompressed image).

ImageDecompressor.DecompressImage(T) Method (T[], IGrabResult)#

Decompresses the image of the grab result provided.

Syntax#

C#

public CompressionInfo DecompressImage<T>(
    T[] outputBuffer,
    IGrabResult grabResult
)

VB

Public Function DecompressImage(Of T) ( 
    outputBuffer As T(),
    grabResult As IGrabResult
) As CompressionInfo

Parameters#

outputBuffer: Type: T[]
The array (one-dimensional) that will receive the decompressed image. The size of the array (in bytes) must be larger or equal to the value in the DecompressedImageSize field in the CompressionInfo struct received via the GetCompressionInfo methods. Alternatively, the GetImageSizeForDecompression(ICamera) method can be used to get the image size required for decompression. Keep in mind that the size of the array (in bytes) is calculated by multiplying the length of the array with the size of the array's elements. This parameter must not be null.
grabResult: Type: Basler.Pylon.IGrabResult
Grab result that holds the compressed data. This parameter must not be null.

Type Parameters#

T: The element type of the array for the decompressed image.

Return Value#

Type: CompressionInfo
Returns the struct with the compression information of the compressed image.

Remarks#

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor property.

The grab result provided must contain a compressed image that has been received without errors.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab result does not contain compressed data, the data is corrupt, the image cannot be decompressed, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the decompressed image).

ImageDecompressor.DecompressImage(T) Method (T[], IntPtr, Int32)#

Decompresses the image of the grab buffer provided.

Syntax#

C#

public CompressionInfo DecompressImage<T>(
    T[] outputBuffer,
    IntPtr pGrabBuffer,
    int payloadSize
)

VB

Public Function DecompressImage(Of T) ( 
    outputBuffer As T(),
    pGrabBuffer As IntPtr,
    payloadSize As Integer
) As CompressionInfo

Parameters#

outputBuffer: Type: T[]
The array (one-dimensional) that will receive the decompressed image. The size of the array (in bytes) must be larger or equal to the value in the DecompressedImageSize field in the CompressionInfo struct received via the GetCompressionInfo methods. Alternatively, the GetImageSizeForDecompression(ICamera) method can be used to get the image size required for decompression. Keep in mind that the size of the array (in bytes) is calculated by multiplying the length of the array with the size of the array's elements. This parameter must not be null.
pGrabBuffer: Type: System.IntPtr
Pointer to the grab buffer that holds the compressed data. This parameter must not be null.
payloadSize: Type: System.Int32
Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).

Type Parameters#

T: The element type of the array for the decompressed image.

Return Value#

Type: CompressionInfo
Returns the struct with the compression information of the compressed image.

Remarks#

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor property.

The grab buffer provided must contain a compressed image that has been received without errors.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab buffer does not contain compressed data, the data is corrupt, the image cannot be decompressed, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the decompressed image).

ImageDecompressor.Dispose Method#

Releases all resources used by the ImageDecompressor

Syntax#

C#

public void Dispose()

VB

Public Sub Dispose

Implements#

IDisposable.Dispose()

ImageDecompressor.Equals Method#

Compares this instance with another decompressor.

Syntax#

C#

public override bool Equals(
    Object object
)

VB

Public Overrides Function Equals ( 
    object As Object
) As Boolean

Parameters#

object: Type: System.Object
The decompressor on the right hand side of the comparison.

Return Value#

Type: Boolean
True if both decompressors are equal or false otherwise.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Does not throw exceptions.

ImageDecompressor.GetCompressionDescriptor Method (ICamera)#

Gets the current compression descriptor from the camera.

Syntax#

C#

public static byte[] GetCompressionDescriptor(
    ICamera camera
)

VB

Public Shared Function GetCompressionDescriptor ( 
    camera As ICamera
) As Byte()

Parameters#

camera: Type: Basler.Pylon.ICamera
Camera to be used for retrieving the compression descriptor. This parameter must not be null.

Return Value#

Type: Byte[]
Returns the array (one-dimensional) with the compression descriptor.

Remarks#

This method requires image compression to be enabled in the camera. You can determine this via the GetCompressionMode(ICamera) method.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if compression is not enabled in the camera (or unavailable) or an error is encountered while determining the compression descriptor.

ImageDecompressor.GetCompressionDescriptorHash Method (ICamera)#

Gets the hash of the current compression descriptor from the camera.

Syntax#

C#

public static byte[] GetCompressionDescriptorHash(
    ICamera camera
)

VB

Public Shared Function GetCompressionDescriptorHash ( 
    camera As ICamera
) As Byte()

Parameters#

camera: Type: Basler.Pylon.ICamera
Camera to be used for retrieving the compression descriptor hash. This parameter must not be null.

Return Value#

Type: Byte[]
Returns the array (one-dimensional) with the compression descriptor hash.

Remarks#

This method requires image compression to be enabled in the camera. You can determine this via the GetCompressionMode(ICamera) method.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if compression is not enabled in the camera (or unavailable) or an error is encountered while determining the compression descriptor hash.

ImageDecompressor.GetCompressionDescriptorHash Method (IGrabResult)#

Gets the hash of the compression descriptor that is required for decompressing the grab result provided.

Syntax#

C#

public static byte[] GetCompressionDescriptorHash(
    IGrabResult grabResult
)

VB

Public Shared Function GetCompressionDescriptorHash ( 
    grabResult As IGrabResult
) As Byte()

Parameters#

grabResult: Type: Basler.Pylon.IGrabResult
Grab result that holds the compressed data. This parameter must not be null.

Return Value#

Type: Byte[]
Returns the array (one-dimensional) with the compression descriptor hash.

Remarks#

This method will try to auto detect the endianness of the grab result's content.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab result does not contain compressed data or the data is corrupt.

ImageDecompressor.GetCompressionDescriptorHash Method (IntPtr, Int32, IntPtr, Int32, Endianness)#

Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.

Syntax#

C#

public static void GetCompressionDescriptorHash(
    IntPtr pHash,
    ref int sizeHash,
    IntPtr pGrabBuffer,
    int payloadSize,
    Endianness endianness
)

VB

Public Shared Sub GetCompressionDescriptorHash ( 
    pHash As IntPtr,
    ByRef sizeHash As Integer,
    pGrabBuffer As IntPtr,
    payloadSize As Integer,
    endianness As Endianness
)

Parameters#

pHash: Type: System.IntPtr
Pointer to the buffer that will receive the compression descriptor hash or null if you only want to get the size of the buffer for buffer allocation.
sizeHash: Type: System.Int32
On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not null). On output, the variable will receive the actual buffer size required for the current compression descriptor hash.
pGrabBuffer: Type: System.IntPtr
Pointer to the grab buffer that holds the compressed data. This parameter must not be null.
payloadSize: Type: System.Int32
Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).
endianness: Type: Basler.Pylon.Endianness
Endianness of the grab buffer's content. If not known, auto detection can be used.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab buffer does not contain compressed data, the data is corrupt, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

ImageDecompressor.GetCompressionDescriptorHash Method (IGrabResult, Endianness)#

Gets the hash of the compression descriptor that is required for decompressing the grab result provided.

Syntax#

C#

public static byte[] GetCompressionDescriptorHash(
    IGrabResult grabResult,
    Endianness endianness
)

VB

Public Shared Function GetCompressionDescriptorHash ( 
    grabResult As IGrabResult,
    endianness As Endianness
) As Byte()

Parameters#

grabResult: Type: Basler.Pylon.IGrabResult
Grab result that holds the compressed data. This parameter must not be null.
endianness: Type: Basler.Pylon.Endianness
Endianness of the grab result's content. If not known, auto detection can be used.

Return Value#

Type: Byte[]
Returns the array (one-dimensional) with the compression descriptor hash.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab result does not contain compressed data or the data is corrupt.

ImageDecompressor.GetCompressionDescriptorHash Method (IntPtr, Int32)#

Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.

Syntax#

C#

public static byte[] GetCompressionDescriptorHash(
    IntPtr pGrabBuffer,
    int payloadSize
)

VB

Public Shared Function GetCompressionDescriptorHash ( 
    pGrabBuffer As IntPtr,
    payloadSize As Integer
) As Byte()

Parameters#

pGrabBuffer: Type: System.IntPtr
Pointer to the grab buffer that holds the compressed data. This parameter must not be null.
payloadSize: Type: System.Int32
Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).

Return Value#

Type: Byte[]
Returns the array (one-dimensional) with the compression descriptor hash.

Remarks#

This method will try to auto detect the endianness of the grab buffer's content.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab buffer does not contain compressed data or the data is corrupt.

ImageDecompressor.GetCompressionDescriptorHash Method (IntPtr, Int32, Endianness)#

Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.

Syntax#

C#

public static byte[] GetCompressionDescriptorHash(
    IntPtr pGrabBuffer,
    int payloadSize,
    Endianness endianness
)

VB

Public Shared Function GetCompressionDescriptorHash ( 
    pGrabBuffer As IntPtr,
    payloadSize As Integer,
    endianness As Endianness
) As Byte()

Parameters#

pGrabBuffer: Type: System.IntPtr
Pointer to the grab buffer that holds the compressed data. This parameter must not be null.
payloadSize: Type: System.Int32
Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).
endianness: Type: Basler.Pylon.Endianness
Endianness of the grab buffer's content. If not known, auto detection can be used.

Return Value#

Type: Byte[]
Returns the array (one-dimensional) with the compression descriptor hash.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab buffer does not contain compressed data or the data is corrupt.

ImageDecompressor.GetCompressionDescriptorHash Method (IntPtr, Int32)#

Gets the hash of the currently set compression descriptor.

Syntax#

C#

public void GetCompressionDescriptorHash(
    IntPtr pHash,
    ref int sizeHash
)

VB

Public Sub GetCompressionDescriptorHash ( 
    pHash As IntPtr,
    ByRef sizeHash As Integer
)

Parameters#

pHash: Type: System.IntPtr
Pointer to the buffer that will receive the compression descriptor hash or null if you only want to get the size of the buffer for buffer allocation.
sizeHash: Type: System.Int32
On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not null). On output, the variable will receive the actual buffer size required for the current compression descriptor hash.

Remarks#

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor property.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the decompressor has no compression descriptor set or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

ImageDecompressor.GetCompressionDescriptorHash Method (IntPtr, Int32, ICamera)#

Gets the current compression descriptor hash from the camera.

Syntax#

C#

public static void GetCompressionDescriptorHash(
    IntPtr pHash,
    ref int sizeHash,
    ICamera camera
)

VB

Public Shared Sub GetCompressionDescriptorHash ( 
    pHash As IntPtr,
    ByRef sizeHash As Integer,
    camera As ICamera
)

Parameters#

pHash: Type: System.IntPtr
Pointer to the buffer that will receive the compression descriptor hash or null if you only want to get the size of the buffer for buffer allocation.
sizeHash: Type: System.Int32
On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not null). On output, the variable will receive the actual buffer size required for the current compression descriptor hash.
camera: Type: Basler.Pylon.ICamera
Camera to be used for retrieving the compression descriptor hash. This parameter must not be null.

Remarks#

This method requires image compression to be enabled in the camera. You can determine this via the GetCompressionMode(ICamera) method.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if compression is not enabled in the camera (or unavailable) or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

ImageDecompressor.GetCompressionDescriptorHash Method (IntPtr, Int32, IGrabResult)#

Gets the hash of the compression descriptor that is required for decompressing the grab result provided.

Syntax#

C#

public static void GetCompressionDescriptorHash(
    IntPtr pHash,
    ref int sizeHash,
    IGrabResult grabResult
)

VB

Public Shared Sub GetCompressionDescriptorHash ( 
    pHash As IntPtr,
    ByRef sizeHash As Integer,
    grabResult As IGrabResult
)

Parameters#

pHash: Type: System.IntPtr
Pointer to the buffer that will receive the compression descriptor hash or null if you only want to get the size of the buffer for buffer allocation.
sizeHash: Type: System.Int32
On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not null). On output, the variable will receive the actual buffer size required for the current compression descriptor hash.
grabResult: Type: Basler.Pylon.IGrabResult
Grab result that holds the compressed data. This parameter must not be null.

Remarks#

This method will try to auto detect the endianness of the grab result's content.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab result does not contain compressed data, the data is corrupt, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

ImageDecompressor.GetCompressionDescriptorHash Method (IntPtr, Int32, IGrabResult, Endianness)#

Gets the hash of the compression descriptor that is required for decompressing the grab result provided.

Syntax#

C#

public static void GetCompressionDescriptorHash(
    IntPtr pHash,
    ref int sizeHash,
    IGrabResult grabResult,
    Endianness endianness
)

VB

Public Shared Sub GetCompressionDescriptorHash ( 
    pHash As IntPtr,
    ByRef sizeHash As Integer,
    grabResult As IGrabResult,
    endianness As Endianness
)

Parameters#

pHash: Type: System.IntPtr
Pointer to the buffer that will receive the compression descriptor hash or null if you only want to get the size of the buffer for buffer allocation.
sizeHash: Type: System.Int32
On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not null). On output, the variable will receive the actual buffer size required for the current compression descriptor hash.
grabResult: Type: Basler.Pylon.IGrabResult
Grab result that holds the compressed data. This parameter must not be null.
endianness: Type: Basler.Pylon.Endianness
Endianness of the grab result's content. If not known, auto detection can be used.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab result does not contain compressed data, the data is corrupt, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

ImageDecompressor.GetCompressionDescriptorHash Method (IntPtr, Int32, IntPtr, Int32)#

Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.

Syntax#

C#

public static void GetCompressionDescriptorHash(
    IntPtr pHash,
    ref int sizeHash,
    IntPtr pGrabBuffer,
    int payloadSize
)

VB

Public Shared Sub GetCompressionDescriptorHash ( 
    pHash As IntPtr,
    ByRef sizeHash As Integer,
    pGrabBuffer As IntPtr,
    payloadSize As Integer
)

Parameters#

pHash: Type: System.IntPtr
Pointer to the buffer that will receive the compression descriptor hash or null if you only want to get the size of the buffer for buffer allocation.
sizeHash: Type: System.Int32
On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not null). On output, the variable will receive the actual buffer size required for the current compression descriptor hash.
pGrabBuffer: Type: System.IntPtr
Pointer to the grab buffer that holds the compressed data. This parameter must not be null.
payloadSize: Type: System.Int32
Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).

Remarks#

This method will try to auto detect the endianness of the grab buffer's content.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the grab buffer does not contain compressed data, the data is corrupt, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

ImageDecompressor.GetCompressionDescriptor Method (IntPtr, Int32)#

Gets the currently set compression descriptor.

Syntax#

C#

public void GetCompressionDescriptor(
    IntPtr pCompressionDescriptor,
    ref int sizeCompressionDescriptor
)

VB

Public Sub GetCompressionDescriptor ( 
    pCompressionDescriptor As IntPtr,
    ByRef sizeCompressionDescriptor As Integer
)

Parameters#

pCompressionDescriptor: Type: System.IntPtr
Pointer to the buffer that will receive the compression descriptor or null if you only want to get the size of the buffer for buffer allocation.
sizeCompressionDescriptor: Type: System.Int32
On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor (if pCompressionDescriptor is not null). On output, the variable will receive the actual buffer size required for the current compression descriptor.

Remarks#

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor property.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the decompressor has no compression descriptor set or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor).

ImageDecompressor.GetCompressionDescriptor Method (IntPtr, Int32, ICamera)#

Gets the current compression descriptor from the camera.

Syntax#

C#

public static void GetCompressionDescriptor(
    IntPtr pCompressionDescriptor,
    ref int sizeCompressionDescriptor,
    ICamera camera
)

VB

Public Shared Sub GetCompressionDescriptor ( 
    pCompressionDescriptor As IntPtr,
    ByRef sizeCompressionDescriptor As Integer,
    camera As ICamera
)

Parameters#

pCompressionDescriptor: Type: System.IntPtr
Pointer to the buffer that will receive the compression descriptor or null if you only want to get the size of the buffer for buffer allocation.
sizeCompressionDescriptor: Type: System.Int32
On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor (if pCompressionDescriptor is not null). On output, the variable will receive the actual buffer size required for the current compression descriptor.
camera: Type: Basler.Pylon.ICamera
Camera to be used for retrieving the compression descriptor. This parameter must not be null.

Remarks#

This method requires image compression to be enabled in the camera. You can determine this via the GetCompressionMode(ICamera) method.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if compression is not enabled in the camera (or unavailable) or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor).

ImageDecompressor.GetCompressionInfo Method (CompressionInfo, IGrabResult)#

Gets compression information about a grab result.

Syntax#

C#

public static bool GetCompressionInfo(
    ref CompressionInfo compressionInfo,
    IGrabResult grabResult
)

VB

Public Shared Function GetCompressionInfo ( 
    ByRef compressionInfo As CompressionInfo,
    grabResult As IGrabResult
) As Boolean

Parameters#

compressionInfo: Type: Basler.Pylon.CompressionInfo
Reference to the struct that will receive the compression information if the grab result contains such information.
grabResult: Type: Basler.Pylon.IGrabResult
Grab result that holds the compressed data. This parameter must not be null.

Return Value#

Type: Boolean
Returns true if compression information could be extracted from the the grab result or false otherwise.

Remarks#

This method will try to auto detect the endianness of the grab result's content.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the input parameters are invalid.

ImageDecompressor.GetCompressionInfo Method (CompressionInfo, IGrabResult, Endianness)#

Gets compression information about a grab result.

Syntax#

C#

public static bool GetCompressionInfo(
    ref CompressionInfo compressionInfo,
    IGrabResult grabResult,
    Endianness endianness
)

VB

Public Shared Function GetCompressionInfo ( 
    ByRef compressionInfo As CompressionInfo,
    grabResult As IGrabResult,
    endianness As Endianness
) As Boolean

Parameters#

compressionInfo: Type: Basler.Pylon.CompressionInfo
Reference to the struct that will receive the compression information if the grab result contains such information.
grabResult: Type: Basler.Pylon.IGrabResult
Grab result that holds the compressed data. This parameter must not be null.
endianness: Type: Basler.Pylon.Endianness
Endianness of the grab result's content. If not known, auto detection can be used.

Return Value#

Type: Boolean
Returns true if compression information could be extracted from the the grab result or false otherwise.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the input parameters are invalid.

ImageDecompressor.GetCompressionInfo Method (CompressionInfo, IntPtr, Int32)#

Gets compression information about a grab buffer.

Syntax#

C#

public static bool GetCompressionInfo(
    ref CompressionInfo compressionInfo,
    IntPtr pGrabBuffer,
    int payloadSize
)

VB

Public Shared Function GetCompressionInfo ( 
    ByRef compressionInfo As CompressionInfo,
    pGrabBuffer As IntPtr,
    payloadSize As Integer
) As Boolean

Parameters#

compressionInfo: Type: Basler.Pylon.CompressionInfo
Reference to the struct that will receive the compression information if the grab buffer contains such information.
pGrabBuffer: Type: System.IntPtr
Pointer to the grab buffer that holds the compressed data. This parameter must not be null.
payloadSize: Type: System.Int32
Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).

Return Value#

Type: Boolean
Returns true if compression information could be extracted from the the grab buffer or false otherwise.

Remarks#

This method will try to auto detect the endianness of the grab buffer's content.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the input parameters are invalid. are invalid.

ImageDecompressor.GetCompressionInfo Method (CompressionInfo, IntPtr, Int32, Endianness)#

Gets compression information about a grab buffer.

Syntax#

C#

public static bool GetCompressionInfo(
    ref CompressionInfo compressionInfo,
    IntPtr pGrabBuffer,
    int payloadSize,
    Endianness endianness
)

VB

Public Shared Function GetCompressionInfo ( 
    ByRef compressionInfo As CompressionInfo,
    pGrabBuffer As IntPtr,
    payloadSize As Integer,
    endianness As Endianness
) As Boolean

Parameters#

compressionInfo: Type: Basler.Pylon.CompressionInfo
Reference to the struct that will receive the compression information if the grab buffer contains such information.
pGrabBuffer: Type: System.IntPtr
Pointer to the grab buffer that holds the compressed data. This parameter must not be null.
payloadSize: Type: System.Int32
Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).
endianness: Type: Basler.Pylon.Endianness
Endianness of the grab buffer's content. If not known, auto detection can be used.

Return Value#

Type: Boolean
Returns true if compression information could be extracted from the the grab buffer or false otherwise.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if the input parameters are invalid.

ImageDecompressor.GetCompressionMode Method#

Retrieves the current compression mode from the camera's node map.

Syntax#

C#

public static CompressionMode GetCompressionMode(
    ICamera camera
)

VB

Public Shared Function GetCompressionMode ( 
    camera As ICamera
) As CompressionMode

Parameters#

camera: Type: Basler.Pylon.ICamera
Camera to be used for retrieving the compression mode. This parameter must not be null.

Return Value#

Type: CompressionMode
Returns the current compression mode of the camera.

Remarks#

This indicates which kind of compression is active or whether compression is not enabled (or unavailable).

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if an error is encountered while determining the compression mode.

ImageDecompressor.GetImageSizeForDecompression Method#

Gets size (in bytes) required for allocating buffers for decompressing the images during streaming.

Syntax#

C#

public static int GetImageSizeForDecompression(
    ICamera camera
)

VB

Public Shared Function GetImageSizeForDecompression ( 
    camera As ICamera
) As Integer

Parameters#

camera: Type: Basler.Pylon.ICamera
Camera to be used for retrieving the image size required for decompression. This parameter must not be null.

Return Value#

Type: Int32
Returns the buffer size (in bytes) required for image decompression.

Remarks#

This method requires image compression to be enabled in the camera. You can determine this via the GetCompressionMode(ICamera) method.

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if an error is encountered while determining the image size required for decompression.

ImageDecompressor.ResetCompressionDescriptor Method#

Resets the compression descriptor in the decompressor.

Syntax#

C#

public void ResetCompressionDescriptor()

VB

Public Sub ResetCompressionDescriptor

Remarks#

After calling this method, no images can be decompressed by the decompressor because it is back in uninitialized state.

Thread Safety: This method is thread-safe.

Error Safety: Does not throw exceptions.

ImageDecompressor.SetCompressionDescriptor Method (ICamera)#

Initializes a decompressor with a compression descriptor that is retrieved from the camera.

Syntax#

C#

public void SetCompressionDescriptor(
    ICamera camera
)

VB

Public Sub SetCompressionDescriptor ( 
    camera As ICamera
)

Parameters#

camera: Type: Basler.Pylon.ICamera
Camera to be used for retrieving the compression descriptor. This parameter must not be null.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if no memory can be allocated or no proper compression descriptor can be retrieved from the camera.

ImageDecompressor.SetCompressionDescriptor Method (IntPtr, Int32)#

Initializes a decompressor with the compression descriptor provided.

Syntax#

C#

public void SetCompressionDescriptor(
    IntPtr pCompressionDescriptor,
    int sizeCompressionDescriptor
)

VB

Public Sub SetCompressionDescriptor ( 
    pCompressionDescriptor As IntPtr,
    sizeCompressionDescriptor As Integer
)

Parameters#

pCompressionDescriptor: Type: System.IntPtr
Pointer to the compression descriptor. This parameter must not be null.
sizeCompressionDescriptor: Type: System.Int32
Size of the data (in bytes) of the compression descriptor.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Throws an exception if no memory can be allocated or the compression descriptor provided is invalid (e.g., because it is corrupt) or incompatible (e.g., because a compression descriptor of a newer compression implementation is passed).

ImageDecompressor Constructor#

Creates an empty decompressor without compression descriptor.

Syntax#

C#

public ImageDecompressor()

VB

Public Sub New

Remarks#

This constructor does not initialize the decompressor with a compression descriptor. You will have to initialize the decompressor first by using one of the SetCompressionDescriptor methods in order to be able to decompress images. You will get an exception if you access methods that require the decompressor to be initialized (see method descriptions for which methods are affected by that precondition).

Error Safety: Throws an exception if no memory can be allocated.

ImageDecompressor Constructor (ICamera)#

Creates a decompressor and initializes it with a compression descriptor that is retrieved from the camera.

Syntax#

C#

public ImageDecompressor(
    ICamera camera
)

VB

Public Sub New ( 
    camera As ICamera
)

Parameters#

camera: Type: Basler.Pylon.ICamera
Camera to be used for retrieving the compression descriptor. This parameter must not be null.

Remarks#

Error Safety: Throws an exception if no memory can be allocated or no proper compression descriptor can be retrieved from the camera.

ImageDecompressor Constructor (ImageDecompressor)#

Creates a decompressor by copying from another decompressor.

Syntax#

C#

public ImageDecompressor(
    ImageDecompressor imageDecompressor
)

VB

Public Sub New ( 
    imageDecompressor As ImageDecompressor
)

Parameters#

imageDecompressor: Type: Basler.Pylon.ImageDecompressor
Decompressor to copy from during initialization.

Remarks#

Error Safety: Throws an exception if no memory can be allocated.

ImageDecompressor Constructor (Byte[])#

Creates a decompressor and initializes it with the compression descriptor provided.

Syntax#

C#

public ImageDecompressor(
    byte[] compressionDescriptor
)

VB

Public Sub New ( 
    compressionDescriptor As Byte()
)

Parameters#

compressionDescriptor: Type: System.Byte[]
The array (one-dimensional) with the compression descriptor. This parameter must not be null.

Remarks#

Error Safety: Throws an exception if no memory can be allocated or the compression descriptor provided is invalid (e.g., because it is corrupt) or incompatible (e.g., because a compression descriptor of a newer compression implementation is passed).

ImageDecompressor Constructor (IntPtr, Int32)#

Creates a decompressor and initializes it with the compression descriptor provided.

Syntax#

C#

public ImageDecompressor(
    IntPtr pCompressionDescriptor,
    int sizeCompressionDescriptor
)

VB

Public Sub New ( 
    pCompressionDescriptor As IntPtr,
    sizeCompressionDescriptor As Integer
)

Parameters#

pCompressionDescriptor: Type: System.IntPtr
Pointer to the compression descriptor. This parameter must not be null.
sizeCompressionDescriptor: Type: System.Int32
Size of the data (in bytes) of the compression descriptor.

Remarks#

Error Safety: Throws an exception if no memory can be allocated or the compression descriptor provided is invalid (e.g., because it is corrupt) or incompatible (e.g., because a compression descriptor of a newer compression implementation is passed).

ImageDecompressor.ComputeCompressionDescriptorHash Method#

Overload List#

	Name	Description
	ComputeCompressionDescriptorHash(Byte[])	Computes the hash for a given compression descriptor.
	ComputeCompressionDescriptorHash(IntPtr, Int32)	Computes the hash for a given compression descriptor.
	ComputeCompressionDescriptorHash(IntPtr, Int32, IntPtr, Int32)	Computes the hash for a given compression descriptor.

ImageDecompressor.DecompressImage Method#

Overload List#

	Name	Description
	DecompressImage(T)(T[], IGrabResult)	Decompresses the image of the grab result provided.
	DecompressImage(T)(T[], IntPtr, Int32)	Decompresses the image of the grab buffer provided.
	DecompressImage(IntPtr, Int32, IGrabResult)	Decompresses the image of the grab result provided.
	DecompressImage(IntPtr, Int32, IntPtr, Int32)	Decompresses the image of the grab buffer provided.

ImageDecompressor.GetCompressionDescriptor Method#

Overload List#

	Name	Description
	GetCompressionDescriptor(ICamera)	Gets the current compression descriptor from the camera.
	GetCompressionDescriptor(IntPtr, Int32)	Gets the currently set compression descriptor.
	GetCompressionDescriptor(IntPtr, Int32, ICamera)	Gets the current compression descriptor from the camera.

ImageDecompressor.GetCompressionDescriptorHash Method#

Overload List#

	Name	Description
	GetCompressionDescriptorHash(ICamera)	Gets the hash of the current compression descriptor from the camera.
	GetCompressionDescriptorHash(IGrabResult)	Gets the hash of the compression descriptor that is required for decompressing the grab result provided.
	GetCompressionDescriptorHash(IGrabResult, Endianness)	Gets the hash of the compression descriptor that is required for decompressing the grab result provided.
	GetCompressionDescriptorHash(IntPtr, Int32)	Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.
	GetCompressionDescriptorHash(IntPtr, Int32)	Gets the hash of the currently set compression descriptor.
	GetCompressionDescriptorHash(IntPtr, Int32, Endianness)	Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.
	GetCompressionDescriptorHash(IntPtr, Int32, ICamera)	Gets the current compression descriptor hash from the camera.
	GetCompressionDescriptorHash(IntPtr, Int32, IGrabResult)	Gets the hash of the compression descriptor that is required for decompressing the grab result provided.
	GetCompressionDescriptorHash(IntPtr, Int32, IGrabResult, Endianness)	Gets the hash of the compression descriptor that is required for decompressing the grab result provided.
	GetCompressionDescriptorHash(IntPtr, Int32, IntPtr, Int32)	Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.
	GetCompressionDescriptorHash(IntPtr, Int32, IntPtr, Int32, Endianness)	Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.

ImageDecompressor.GetCompressionInfo Method#

Overload List#

	Name	Description
	GetCompressionInfo(CompressionInfo, IGrabResult)	Gets compression information about a grab result.
	GetCompressionInfo(CompressionInfo, IGrabResult, Endianness)	Gets compression information about a grab result.
	GetCompressionInfo(CompressionInfo, IntPtr, Int32)	Gets compression information about a grab buffer.
	GetCompressionInfo(CompressionInfo, IntPtr, Int32, Endianness)	Gets compression information about a grab buffer.

ImageDecompressor.SetCompressionDescriptor Method#

Overload List#

	Name	Description
	SetCompressionDescriptor(ICamera)	Initializes a decompressor with a compression descriptor that is retrieved from the camera.
	SetCompressionDescriptor(IntPtr, Int32)	Initializes a decompressor with the compression descriptor provided.

ImageDecompressor Constructor#

Overload List#

	Name	Description
	ImageDecompressor()	Creates an empty decompressor without compression descriptor.
	ImageDecompressor(Byte[])	Creates a decompressor and initializes it with the compression descriptor provided.
	ImageDecompressor(ICamera)	Creates a decompressor and initializes it with a compression descriptor that is retrieved from the camera.
	ImageDecompressor(ImageDecompressor)	Creates a decompressor by copying from another decompressor.
	ImageDecompressor(IntPtr, Int32)	Creates a decompressor and initializes it with the compression descriptor provided.

ImageDecompressor.CompressionDescriptor Property#

Initializes or gets the currently set compression descriptor.

Syntax#

C#

public byte[] CompressionDescriptor { get; set; }

VB

Public Property CompressionDescriptor As Byte()
    Get
    Set

Property Value#

Type: Byte[]
The array (one-dimensional) with the compression descriptor. This value must not be null.

Remarks#

Thread Safety: This property is thread-safe.

Error Safety: When setting the property, throws an exception if no memory can be allocated or the compression descriptor provided is invalid (e.g., because it is corrupt) or incompatible (e.g., because a compression descriptor of a newer compression implementation is passed). When getting the property, throws an exception if the decompressor has no compression descriptor set.

ImageDecompressor.CompressionDescriptorHash Property#

Gets the hash of the currently set compression descriptor.

Syntax#

C#

public byte[] CompressionDescriptorHash { get; }

VB

Public ReadOnly Property CompressionDescriptorHash As Byte()
    Get

Property Value#

Type: Byte[]
The array (one-dimensional) with the hash of the currently set compression descriptor.

Remarks#

Thread Safety: This property is thread-safe.

Error Safety: Throws an exception if the decompressor has no compression descriptor set.

ImageDecompressor.HasCompressionDescriptor Property#

Determines whether the decompressor already has a compression descriptor.

Syntax#

C#

public bool HasCompressionDescriptor { get; }

VB

Public ReadOnly Property HasCompressionDescriptor As Boolean
    Get

Return Value#

Type: Boolean
Returns true if the decompressor is already initialized with a compression descriptor or false otherwise.

Remarks#

Thread Safety: This method is thread-safe.

Error Safety: Does not throw exceptions.