Euresys Recorder low-level C API. More...

Functions
RECORDER_API	RecorderInitLib ()
	Open the Recorder library. More...

RECORDER_API	RecorderCloseLib ()
	Close the Recorder library. More...

RECORDER_API	RecorderOpen (const char path, RECORDER_OPEN_MODE mode, RECORDER_HANDLE handle, uint32_t *fileVersion)
	Open a recorder object. More...

RECORDER_API	RecorderClose (RECORDER_HANDLE handle, RECORDER_CLOSE_MODE mode)
	Close a recorder object. More...

RECORDER_API	RecorderSetParameterString (RECORDER_HANDLE handle, RECORDER_PARAMETER parameter, const char *value)
	Set a recorder object parameter string value. More...

RECORDER_API	RecorderGetParameterString (RECORDER_HANDLE handle, RECORDER_PARAMETER parameter, char value, size_t size)
	Get a recorder object parameter string value. More...

RECORDER_API	RecorderSetParameterInteger (RECORDER_HANDLE handle, RECORDER_PARAMETER parameter, int64_t value)
	Set a recorder object parameter integer value. More...

RECORDER_API	RecorderGetParameterInteger (RECORDER_HANDLE handle, RECORDER_PARAMETER parameter, int64_t *value)
	Get a recorder object parameter integer value. More...

RECORDER_API	RecorderRead (RECORDER_HANDLE handle, RECORDER_BUFFER_INFO info, void buffer, size_t bufferSize, void reserved)
	Read the record at the current index position from a recorder container opened in read mode. More...

RECORDER_API	RecorderWrite (RECORDER_HANDLE handle, const RECORDER_BUFFER_INFO info, const void buffer, void reserved1, void reserved2, void *reserved3)
	Write buffer info and data to a recorder container opened in write or append mode. More...

RECORDER_API	RecorderExport (RECORDER_HANDLE handle, const char path, size_t count, uint32_t exportPixelFormat, unsigned int reserved, RECORDER_PROGRESS_CALLBACK progressCallback, void *progressContext)
	Export a range of recorded images to files. More...

RECORDER_API	RecorderStartChapter (RECORDER_HANDLE handle, const char name, const char info)
	Start a new chapter. More...

Detailed Description

Euresys Recorder low-level C API.

Function Documentation

◆ RecorderInitLib()

RECORDER_API Euresys::EGrabberRecorder::RecorderInitLib ( )

Open the Recorder library.

◆ RecorderCloseLib()

RECORDER_API Euresys::EGrabberRecorder::RecorderCloseLib ( )

Close the Recorder library.

◆ RecorderOpen()

RECORDER_API Euresys::EGrabberRecorder::RecorderOpen	(	const char *	path,
		RECORDER_OPEN_MODE	mode,
		RECORDER_HANDLE *	handle,
		uint32_t *	fileVersion
	)

Open a recorder object.

Parameters

path	path to the recorder container to open
mode	the operation mode of the recorder
handle	out: the handle of the opened recorder in case of success
fileVersion	out: the version of the recorder container format (optional, fileVersion may be NULL)

◆ RecorderClose()

RECORDER_API Euresys::EGrabberRecorder::RecorderClose	(	RECORDER_HANDLE	handle,
		RECORDER_CLOSE_MODE	mode
	)

Close a recorder object.

Parameters

handle the handle of the recorder object to close

mode

specifies how the recorder container is closed:

if mode is RECORDER_CLOSE_MODE_TRIM: the recorder container is reduced to the smallest size that fits the container contents
if mode is RECORDER_CLOSE_MODE_KEEP: the recorder container size is unchanged
if the flag RECORDER_CLOSE_MODE_DONT_TRIM_CHAPTERS is added to the mode, the trailing chapters will be kept even if they are empty; by default, trailing empty chapters are removed

◆ RecorderSetParameterString()

RECORDER_API Euresys::EGrabberRecorder::RecorderSetParameterString	(	RECORDER_HANDLE	handle,
		RECORDER_PARAMETER	parameter,
		const char *	value
	)

Set a recorder object parameter string value.

Parameters

handle	the handle of the recorder object
parameter	the identifier of the parameter to set (see RECORDER_PARAMETER)
value	the new string value of the parameter

◆ RecorderGetParameterString()

RECORDER_API Euresys::EGrabberRecorder::RecorderGetParameterString	(	RECORDER_HANDLE	handle,
		RECORDER_PARAMETER	parameter,
		char *	value,
		size_t *	size
	)

Get a recorder object parameter string value.

Parameters

handle	the handle of the recorder object
parameter	the identifier of the parameter to get (see RECORDER_PARAMETER)
value	optional output buffer for the parameter value: if value is NULL: the required size of the output buffer is written to the output parameter size if value is not NULL: the string value is written to the output buffer
size	in/out: size of output buffer

◆ RecorderSetParameterInteger()

RECORDER_API Euresys::EGrabberRecorder::RecorderSetParameterInteger	(	RECORDER_HANDLE	handle,
		RECORDER_PARAMETER	parameter,
		int64_t	value
	)

Set a recorder object parameter integer value.

Parameters

handle	the handle of the recorder object
parameter	the identifier of the parameter to set (see RECORDER_PARAMETER)
value	the new integer value of the parameter

◆ RecorderGetParameterInteger()

RECORDER_API Euresys::EGrabberRecorder::RecorderGetParameterInteger	(	RECORDER_HANDLE	handle,
		RECORDER_PARAMETER	parameter,
		int64_t *	value
	)

Get a recorder object parameter integer value.

Parameters

handle	the handle of the recorder object
parameter	the identifier of the parameter to get (see RECORDER_PARAMETER)
value	out: the current integer value of the parameter

◆ RecorderRead()

RECORDER_API Euresys::EGrabberRecorder::RecorderRead	(	RECORDER_HANDLE	handle,
		RECORDER_BUFFER_INFO *	info,
		void *	buffer,
		size_t *	bufferSize,
		void *	reserved
	)

Read the record at the current index position from a recorder container opened in read mode.

Parameters

handle	the handle of the recorder object
info	out: optional output buffer where record buffer info will be written
buffer	out: optional output buffer where record buffer data will be written
bufferSize	in/out: size of output buffer
reserved	must be nullptr

Note

the function reads the buffer info and data of the record at the position defined by the parameter RECORDER_PARAMETER_RECORD_INDEX

when buffer is NULL: the recorder index is not changed
when buffer is not NULL: the recorder index is automatically set to the next record after a successful read

◆ RecorderWrite()

RECORDER_API Euresys::EGrabberRecorder::RecorderWrite	(	RECORDER_HANDLE	handle,
		const RECORDER_BUFFER_INFO *	info,
		const void *	buffer,
		void *	reserved1,
		void *	reserved2,
		void *	reserved3
	)

Write buffer info and data to a recorder container opened in write or append mode.

Parameters

handle	the handle of the recorder object
info	the buffer info to write to the container
buffer	the buffer data to write to the container
reserved1	must be nullptr
reserved2	must be nullptr
reserved3	must be nullptr

Note: the buffer info and data are written to the container at the current index position (RECORDER_PARAMETER_RECORD_INDEX); the recorder index is automatically incremented by one after a write and the recorder count (RECORDER_PARAMETER_RECORD_COUNT) is also adapted accordingly

◆ RecorderExport()

RECORDER_API Euresys::EGrabberRecorder::RecorderExport	(	RECORDER_HANDLE	handle,
		const char *	path,
		size_t *	count,
		uint32_t	exportPixelFormat,
		unsigned int	reserved,
		RECORDER_PROGRESS_CALLBACK	progressCallback,
		void *	progressContext
	)

Export a range of recorded images to files.

The container must be opened in read mode

Parameters

handle	the handle of the recorder object
path	the path template of the exported files (see note for a description of the name decoration)
count	on input: the number of records to export on output: the number of records actually exported
exportPixelFormat	the pixel format of the exported file; or 0 to disable image conversions and keep the original pixel format
reserved	must be 0
progressCallback	optional progress callback; if progressCallback is different from NULL, it is called before exporting each buffer; the export continues as long as the callback returns 0; if the callback returns a value different from 0, RecorderExport will stop and return RECORDER_STATUS_ABORTED
progressContext	progress context passed to progress callback

Note

export starts at the current index position (RECORDER_PARAMETER_RECORD_INDEX) in the container and goes on until "count" records have been exported or the end of the container is reached; the count parameter is updated accordingly; the RECORDER_PARAMETER_RECORD_INDEX is updated accordingly.

file name decoration uses the @ character as a place holder for the following:

@i for the index relative to the first record in the container (number of digits used is defined by the number of records in the container)
@n for the index relative to the current record written (number of digits used is defined by the count parameter)
@p for the part index relative to the record (number of digits used is defined by the buffer part count of the record)
@t for the timestamp value in RECORDER_BUFFER_INFO::timestamp of the exported record
@c for the chapter index
@C for the chapter name
@@ for the literal @ All other @ patterns are invalid and a RECORDER_STATUS_INVALID_ARGUMENT is returned.

the file format is derived from the file extension

.tiff or .tif for the TIFF file format
.mkv for the Matroska MKV file format (using the V_UNCOMPRESSED codec) If the path does not have an extension, a RECORDER_STATUS_INVALID_ARGUMENT is returned

the allowed values for exportPixelFormat depend on the file type.

TIFF files support the following: Mono8, Mono16, RGB8, RGB16
MKV files support the following: Mono8, RGB8

for TIFF files:

if count is greater than 1 and path does not contain any @ pattern, we add .@n before the file extension
if a record contains more than 1 part and the path does not contain the @p pattern, we add .@p before the file extension

for MKV files:

the export operation creates one MKV file per chapter; if the export operation spans several chapters, we add @.n automatically before the file extension
the image width, height and pixel format must be constant for the entire file. The first exported image is used to define these values. A subsequent image with a different format will be simply skipped and the returned count will not be updated.
timestamps increase monotonically; when a backward discontinuity is detected i.e. the relative time from the beginning of the file of the image to be written is less than the relative time of the latest image written, a new time reference is taken

most of the times, a record contains one image (one buffer part) so the number of exported images matches the number of exported records; but, if a record contains more than 1 part, each part is exported as a separate image so the number of exported images will be greater than the output "count"

Records containing Bayer formats are converted using the decoding method defined by the parameter RECORDER_PARAMETER_BAYER_DECODING_METHOD

◆ RecorderStartChapter()

RECORDER_API Euresys::EGrabberRecorder::RecorderStartChapter	(	RECORDER_HANDLE	handle,
		const char *	name,
		const char *	info
	)

Start a new chapter.

The container must be in write mode.

Parameters

handle	the handle of the recorder object
name	optional name of the new chapter (may be nullptr)
info	an optional info string (may be nullptr)

Note: a chapter helps grouping recordings and provides a synchronization point between system and UTC timestamps; a chapter is automatically created if needed on the first write after opening the container if this function has not been called. The name of the automatically created chapter is "Chapter<xx>" where "<xx>" is the index of the new chapter.; it is allowed to call this method at any time to signal a time discontinuity or start a new group of recordings; the newly created chapter becomes the current chapter and the RECORDER_CHAPTER_XXXX parameters are updated accordingly; the chapter name must comply with the regular expression [A-Za-z_][-A-Za-z0-9_ ]*; the chapter name length cannot exceed 255 characters; the chapter name must be unique within the container; the chapter name cannot be like a default chapter name (i.e. Chapter[0-9]+) unless it matches the default name it would get automatically; when a chapter is created, a synchronized pair of system/UTC timestamps is captured and stored in the storage as RECORDER_PARAMETER_CHAPTER_TIMESTAMP and RECORDER_PARAMETER_CHAPTER_UTC; the system time timestamp is expressed in nanoseconds since the computer booted;; when reading back from a container, the pair of synchronized timestamps of the corresponding chapter is used internally to compute the value of the (non-zero) utc field of a RECORDER_BUFFER_INFO record from the value of the (system) timestamp field

Functions

Detailed Description

Function Documentation

◆ RecorderInitLib()

◆ RecorderCloseLib()

◆ RecorderOpen()

◆ RecorderClose()

◆ RecorderSetParameterString()

◆ RecorderGetParameterString()

◆ RecorderSetParameterInteger()

◆ RecorderGetParameterInteger()

◆ RecorderRead()

◆ RecorderWrite()

◆ RecorderExport()

◆ RecorderStartChapter()