All Files Functions Typedefs Enumerations Enumerator Macros Pages
Typedefs | Functions
BconAdapterStream.h File Reference

BCON adapter stream interface. More...

#include <stddef.h>
#include "BconAdapterDefines.h"
#include "BconAdapterTypes.h"

Typedefs

typedef struct
BconAdapterStream_tag * 
BconAdapterStreamHandle
 Opaque handle representing a stream A handle value of null is considered invalid.
 
typedef struct
BconAdapterBuffer_tag * 
BconAdapterBufferHandle
 Opaque handle representing a buffer A handle value of NULL is considered invalid.
 
typedef void(BCON_ADAPTER_CALL * BconAdapterStreamBufferReadyCallback )(BconAdapterStreamHandle hStream, size_t imageReadyCount, void *context)
 Stream callback function. Call this function when the number of images ready changes. More...
 

Functions

BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamCreate (const char deviceID[], BconAdapterStreamHandle *phStream)
 Creates the stream. Allocates memory and/or other resources as required. Assigns a unique handle representing the stream. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamDestroy (BconAdapterStreamHandle hStream)
 Destroys the stream. Frees memory and/or other resources. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamOpen (BconAdapterStreamHandle hStream)
 Opens the stream. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamClose (BconAdapterStreamHandle hStream)
 Closes the stream. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamGetProperty (BconAdapterStreamHandle hStream, uint64_t propertyId, void *pValue, size_t valueSize)
 Gets a property value. The property value is written to the buffer given in pValue. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamSetProperty (BconAdapterStreamHandle hStream, uint64_t propertyId, const void *pValue, size_t valueSize)
 Sets a property value. The property value is read from the buffer given in pValue. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamConfigureStreamingParameters (BconAdapterStreamHandle hStream, uint32_t width, uint32_t height, uint32_t pixelFormatPfncValue, uint32_t clockFrequency, uint32_t pixelsPerClockCycle, size_t *payloadSizeOut)
 Configures the main streaming parameters. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamPrepareGrab (BconAdapterStreamHandle hStream, size_t maxNumBuffer, size_t maxBufferSize)
 Prepares a stream for grabbing. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamRegisterBuffer (BconAdapterStreamHandle hStream, void *pBuffer, size_t bufferSize, BconAdapterBufferHandle *phBuffer)
 Registers a buffer for grabbing. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamDeregisterBuffer (BconAdapterStreamHandle hStream, BconAdapterBufferHandle hBuffer, void **ppBuffer)
 Deregisters a buffer. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamFlushBuffers (BconAdapterStreamHandle hStream)
 Aborts all pending transfers. Transfers canceled buffers to the output queue. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamStartStreaming (BconAdapterStreamHandle hStream)
 Starts the streaming thread. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamStopStreaming (BconAdapterStreamHandle hStream)
 Stops the streaming thread. Cancels all buffers by calling FlushBuffers(). More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamQueueBuffer (BconAdapterStreamHandle hStream, BconAdapterBufferHandle hBuffer, const void *context)
 Queues a registered buffer for grabbing. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamRetrieveResult (BconAdapterStreamHandle hStream, BconGrabResult *pGrabResult, size_t *pNumBuffersLeft)
 Retrieves a grab result. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamFinishGrab (BconAdapterStreamHandle hStream)
 Finishes a grab session. More...
 
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamRegisterCallback (BconAdapterStreamHandle hStream, BconAdapterStreamBufferReadyCallback pCallback, void *context)
 Registers a callback. Call this function when the number of grabbed images changes. The callback replaces previously registered callbacks. Passing NULL deregisters the callback. More...
 

Detailed Description

BCON adapter stream interface.

Typedef Documentation

typedef void(BCON_ADAPTER_CALL * BconAdapterStreamBufferReadyCallback)(BconAdapterStreamHandle hStream, size_t imageReadyCount, void *context)

Stream callback function. Call this function when the number of images ready changes.

Parameters
[in]hStreamStream handle.
[in]imageReadyCountNumber of images ready. If the grabber implementation cannot tell how many images are ready, it is sufficient to pass 0 to indicate that no buffers are available or 1 to indicate that one or more buffers are available.
[in]contextThe context contains the value passed when the callback has been registered using BconAdapterStreamRegisterCallback().
Attention
This callback must only be used to signal to other threads that they can progress further. Do not acquire any locks or call further functions of the BCON Adapter API from the callback.

Function Documentation

BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamClose ( BconAdapterStreamHandle  hStream)

Closes the stream.

Parameters
[in]hStreamStream handle
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Precondition
Stream is open. BconAdapterStreamOpen() or BconAdapterStreamFinishGrab() has been called before.
Postcondition
Stream is idle on success.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamConfigureStreamingParameters ( BconAdapterStreamHandle  hStream,
uint32_t  width,
uint32_t  height,
uint32_t  pixelFormatPfncValue,
uint32_t  clockFrequency,
uint32_t  pixelsPerClockCycle,
size_t *  payloadSizeOut 
)

Configures the main streaming parameters.

Parameters
[in]hStreamStream handle.
[in]widthImage width to be set for the camera.
[in]heightImage height to be set for the camera.
[in]pixelFormatPfncValuePixel Format Naming Convention value (see www.emva.org) to be set for the camera.
[in]clockFrequencyClock frequency value in Hz to be set for the camera.
[in]pixelsPerClockCyclePixels per clock cycle to be set for the camera (1 = 'One', 2 = 'Two').
[out]payloadSizeOutRequired buffer size for grabbing an image with the above properties and the frame grabber used by the BCON adapter.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Precondition
Stream is open.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamCreate ( const char  deviceID[],
BconAdapterStreamHandle phStream 
)

Creates the stream. Allocates memory and/or other resources as required. Assigns a unique handle representing the stream.

Parameters
[in]deviceIDDevice identifier received during enumeration.
[out]phStreamHandle representing the stream created.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_S_ALREADY_CREATEDStream has already been created.
AnyOther BCON adapter error code.
Postcondition
Stream is idle on success.
Thread Safety:
This function must be thread-safe. It is assumed that a known fixed amount of cameras is attached to a BCON system, so that required data structures can be allocated when BconAdapterInit() is called. Therefore, thread-safety can be assured without using additional locking.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamDeregisterBuffer ( BconAdapterStreamHandle  hStream,
BconAdapterBufferHandle  hBuffer,
void **  ppBuffer 
)

Deregisters a buffer.

Parameters
[in]hStreamStream handle.
[in]hBufferBuffer handle.
[out]ppBufferOptional. Pointer to the buffer.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
BCON_E_INVALID_BUFFER_HANDLEBuffer has already been deregistered or buffer handle is invalid.
BCON_E_BUFFER_STILL_QUEUEDBuffer is still queued for grabbing.
AnyOther BCON adapter error code.
Postcondition
The buffer will no longer be accessed by the stream. The buffer handle is invalid.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamDestroy ( BconAdapterStreamHandle  hStream)

Destroys the stream. Frees memory and/or other resources.

Parameters
[in]hStreamStream handle.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Precondition
Stream is idle. BconAdapterStreamCreate() or BconAdapterStreamClose() has been called before.
Postcondition
hStream is invalid.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamFinishGrab ( BconAdapterStreamHandle  hStream)

Finishes a grab session.

Parameters
[in]hStreamStream handle.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Precondition
Stream is prepared. BconAdapterStreamPrepareGrab() or BconAdapterStreamStopStreaming() has been called before.
Postcondition
Stream is idle on success. All buffers are placed in the output queue.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamFlushBuffers ( BconAdapterStreamHandle  hStream)

Aborts all pending transfers. Transfers canceled buffers to the output queue.

Parameters
[in]hStreamStream handle.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Precondition
Stream is prepared.
Postcondition
All buffers are marked as canceled and are placed in the output queue.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamGetProperty ( BconAdapterStreamHandle  hStream,
uint64_t  propertyId,
void *  pValue,
size_t  valueSize 
)

Gets a property value. The property value is written to the buffer given in pValue.

Parameters
[in]hStreamStream handle.
[in]propertyIdID of the property to be read.
[in]pValuePointer to allocated and writable memory.
[in]valueSizeSize of the allocated memory in bytes.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INSUFFICIENT_BUFFERpValue was NULL or valueSize was too small to hold the data.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Precondition
Stream is created.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function can be implemented. If the BCON adapter library is used with pylon, this method can be accessed via the "StreamGrabberPort" port of the pylon stream grabber node map.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamOpen ( BconAdapterStreamHandle  hStream)

Opens the stream.

Parameters
[in]hStreamStream handle.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Precondition
Stream is idle. BconAdapterStreamCreate() or BconAdapterStreamClose() has been called before.
Postcondition
Stream is open on success.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamPrepareGrab ( BconAdapterStreamHandle  hStream,
size_t  maxNumBuffer,
size_t  maxBufferSize 
)

Prepares a stream for grabbing.

Parameters
[in]hStreamStream handle.
[in]maxNumBufferMaximum number of buffers registered at any time during streaming.
[in]maxBufferSizeMaximum buffer size used for streaming.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Precondition
Stream is open. BconAdapterStreamOpen() or BconAdapterStreamFinishGrab() has been called before.
Postcondition
Stream is prepared on success.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamQueueBuffer ( BconAdapterStreamHandle  hStream,
BconAdapterBufferHandle  hBuffer,
const void *  context 
)

Queues a registered buffer for grabbing.

Parameters
[in]hStreamStream handle.
[in]hBufferHandle of a registered buffer.
[in]contextAdditional data for this buffer. This is returned when buffer is retrieved.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
BCON_E_INVALID_BUFFER_HANDLEBuffer handle is invalid.
BCON_E_BUFFER_ALREADY_QUEUEDBuffer is already queued.
AnyOther BCON adapter error code.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamRegisterBuffer ( BconAdapterStreamHandle  hStream,
void *  pBuffer,
size_t  bufferSize,
BconAdapterBufferHandle phBuffer 
)

Registers a buffer for grabbing.

Parameters
[in]hStreamStream handle.
[in]pBufferBuffer.
[in]bufferSizeBuffer size in bytes.
[out]phBufferUnique handle for the buffer.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_BUFFER_ALREADY_REGISTEREDBuffer is already registered.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Postcondition
Buffer is ready to be used by the stream.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamRegisterCallback ( BconAdapterStreamHandle  hStream,
BconAdapterStreamBufferReadyCallback  pCallback,
void *  context 
)

Registers a callback. Call this function when the number of grabbed images changes. The callback replaces previously registered callbacks. Passing NULL deregisters the callback.

Parameters
[in]hStreamStream handle.
[in]pCallbackOptional. Callback function.
[in]contextOptional. User context, will be given to callback.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamRetrieveResult ( BconAdapterStreamHandle  hStream,
BconGrabResult *  pGrabResult,
size_t *  pNumBuffersLeft 
)

Retrieves a grab result.

Parameters
[in]hStreamStream handle.
[out]pGrabResultPointer to a grab result structure.
[out]pNumBuffersLeftOptional. Returns the number of buffers available in the output queue. Can be NULL.
Returns
Status of the operation.
Return values
BCON_OKGrab result has been retrieved.
BCON_E_INVALID_HANDLEStream handle is invalid.
BCON_E_NO_BUFFER_AVAILABLENo result is available.
AnyOther BCON adapter error code.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamSetProperty ( BconAdapterStreamHandle  hStream,
uint64_t  propertyId,
const void *  pValue,
size_t  valueSize 
)

Sets a property value. The property value is read from the buffer given in pValue.

Parameters
[in]hStreamStream handle.
[in]propertyIdID of the property to be written.
[in]pValuePointer to memory where the property value should be read from.
[in]valueSizeSize of memory in bytes.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Precondition
Stream is created.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function can be implemented. If the BCON adapter library is used with pylon, this method can be accessed via the "StreamGrabberPort" port of the pylon stream grabber node map.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamStartStreaming ( BconAdapterStreamHandle  hStream)

Starts the streaming thread.

Parameters
[in]hStreamStream handle.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Precondition
Stream is prepared. BconAdapterStreamPrepareGrab() or BconAdapterStreamStopStreaming() has been called before.
Postcondition
Stream is streaming.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.
BCONSTATUS BCON_ADAPTER_CALL BconAdapterStreamStopStreaming ( BconAdapterStreamHandle  hStream)

Stops the streaming thread. Cancels all buffers by calling FlushBuffers().

Parameters
[in]hStreamStream handle.
Returns
Status of the operation.
Return values
BCON_OKSuccess.
BCON_E_INVALID_HANDLEStream handle is invalid.
AnyOther BCON adapter error code.
Precondition
Stream is streaming. BconAdapterStreamStartStreaming() has been called before.
Postcondition
Stream is prepared on success.
Thread Safety:
This function must be thread-safe. Multiple threads, one for each stream of different cameras, can access this function at the same time. However, only one thread at a time can access a stream.
Note
This function must be implemented if the BCON adapter library is supposed to support streaming.

BCONAdapterAPI 3.0
© 2016-2017 Basler AG (Tue May 30 2017 17:24:55)