SIDXCAcquire.h File Reference

File containing SIDX acquire usage for reference. More...

#include "SIDXCConstants.h"

Go to the source code of this file.

Functions
int	SIDXAcquireAbort (void *SIDXacquire)
	Interrupt and terminate image Acquire. More...
int	SIDXAcquireArchiveIsWriting (void *SIDXacquire, bool &writing)
	Determine if issued writing to file operations are being completed. More...
int	SIDXAcquireArchiveOpenNew (void *SIDXacquire, const wchar_t *path, const wchar_t *data_type, bool overwrite, void *&SIDXarchive)
	Create an file as an image archive. More...
int	SIDXAcquireArchiveWrite (void *SIDXacquire, int64_t image_index, int64_t image_count)
	Archive the specified images. More...
int	SIDXAcquireClose (void *SIDXacquire)
	Close the Acquire. More...
int	SIDXAcquireGetBufferCount (void *SIDXacquire, int &count)
	Obtain the image buffer count used, that is, the number of images that can be stored in the image buffer. More...
int	SIDXAcquireGetGapInterval (void *SIDXacquire, double &interval)
	Obtain the minimum time interval from the end of an exposure to the start of the next exposure. More...
int	SIDXAcquireGetImageInterval (void *SIDXacquire, double &interval)
	Obtain the time interval between successive images. More...
int	SIDXAcquireGetPollingInterval (void *SIDXacquire, double &interval)
	Obtain the maximum interval between successive calls to the Acquire 'GetStatus' call during image Acquire. More...
int	SIDXAcquireGetReadoutInterval (void *SIDXacquire, double &interval)
	Obtain the readout interval of an exposed image in seconds. More...
int	SIDXAcquireGetStatus (void *SIDXacquire, bool &acquiring)
	Update the Acquire status. More...
int	SIDXAcquireImageGetCount (void *SIDXacquire, int64_t &count)
	Obtain the total number of acquired images since last call to Acquire Start. More...
int	SIDXAcquireImageGetDescription (void *SIDXacquire, int64_t image_index, double &start_time, double &exposure_duration)
	Obtains the exposure duration and start time for a specified image. More...
int	SIDXAcquireRead (void *SIDXacquire, int64_t image_count, short *image_data, size_t length)
	Read images starting from the current read position. More...
int	SIDXAcquireReadGetPosition (void *SIDXacquire, int64_t &position)
	Obtain the current read position. More...
int	SIDXAcquireReadoutExists (void *SIDXacquire, bool &available)
	Determine whether readout interval information is available. More...
int	SIDXAcquireReadSetPosition (void *SIDXacquire, int64_t image_index)
	Set the read position to the specific image. More...
int	SIDXAcquireSpacingGetSize (void *SIDXacquire, size_t &size)
	Obtain the size of an image. More...
int	SIDXAcquireStart (void *SIDXacquire)
	Start Acquire. More...
int	SIDXAcquireStop (void *SIDXacquire)
	Stop Acquire. More...
void	SIDXAcquireGetLastError (void *SIDXacquire, wchar_t *message, size_t length)
	The function translates the error code into a text string. More...
int	SIDXGeometryChannelGetDepth (void *SIDXacquire, int &depth)
	Obtain the pixel depth of one channel from the image data. More...
int	SIDXGeometryImageGetSize (void *SIDXacquire, size_t &size)
	Obtain the data size of an image. More...
int	SIDXGeometryImageGetType (void *SIDXacquire, SIDXImageType &type)
	Obtain the image type of the source image. More...
int	SIDXGeometryPixelGetCount (void *SIDXacquire, int &x, int &y)
	Obtain the x and y pixel count for images. More...
int	SIDXGeometryPixelSpacingGet (void *SIDXacquire, double &x, double &y)
	Obtain the pixel size in x and y. More...

Detailed Description

File containing SIDX acquire usage for reference.

Function Documentation

int SIDXAcquireAbort

(

void *

SIDXacquire

)

Interrupt and terminate image Acquire.

Parameters

SIDXacquire

A handle value that references the open acquire context.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireArchiveIsWriting	(	void *	SIDXacquire,
		bool &	writing
	)

Determine if issued writing to file operations are being completed.

If an error occurs while archiving, all further write operations will report an error.

Parameters

SIDXacquire	A handle value that references the open acquire context.
writing	A variable to receive an boolean value, true if writing images, false if not.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireArchiveOpenNew	(	void *	SIDXacquire,
		const wchar_t *	path,
		const wchar_t *	data_type,
		bool	overwrite,
		void *&	SIDXarchive
	)

Create an file as an image archive.

If the file already exists and the 'overwrite' parameter is set to 'true', the existing file will be destroyed. If the file already exists and the 'overwrite' parameter is set to 'false', SIDX returns an error.

Parameters

SIDXacquire	A handle value that references the open acquire context.
path	A text string specifying the path to the archive file to create.
data_type	A text string specifying the type of archive data file to write. This value must be the text string "TIFF".
overwrite	A boolean value, true if SIDX should overwrite the existing file, false if it should not.
SIDXarchive	A variable to receive a handle value to use to access the image archive.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireArchiveWrite	(	void *	SIDXacquire,
		int64_t	image_index,
		int64_t	image_count
	)

Archive the specified images.

This operation is valid only if an archive is open. The operation is asynchronous, it will return before the images have been archived. All images to be archived must exist.

Parameters

SIDXacquire	A handle value that references the open acquire context.
image_index	An integer value specifying the starting image number to archive.
image_count	An integer value specifying the number of images to archive.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireClose

(

void *

SIDXacquire

)

Close the Acquire.

After this call, the Acquire is no longer valid and camera settings can be changed.

Parameters

SIDXacquire

A handle value that references the open acquire context.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireGetBufferCount	(	void *	SIDXacquire,
		int &	count
	)

Obtain the image buffer count used, that is, the number of images that can be stored in the image buffer.

This value may differ from the setting.

Parameters

SIDXacquire	A handle value that references the open acquire context.
count	A variable to receive an integer value representing the image buffer count, as a number of images.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireGetGapInterval	(	void *	SIDXacquire,
		double &	interval
	)

Obtain the minimum time interval from the end of an exposure to the start of the next exposure.

Parameters

SIDXacquire	A handle value that references the open acquire context.
interval	A variable to receive a real (floating-point) value specifying the minimum time interval gap between the end of one exposure and the start of the next, in seconds.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireGetImageInterval	(	void *	SIDXacquire,
		double &	interval
	)

Obtain the time interval between successive images.

This value is an estimate based on the camera settings. For cameras in modes with controlled timing, this value may be accurate. For example, if the camera supports fixed-rate image streaming with overlapped image integration and readout, this value may be the actual interval between successive images. For external trigger modes, the reported interval is the minimum time from the start of one image exposure to the start of the next. The actual interval is determined by the external trigger. The image interval is constant during Acquire, it does not change.

Parameters

SIDXacquire	A handle value that references the open acquire context.
interval	A variable to receive a real (floating-point) value specifying the image interval in seconds.

Returns

Non-zero if the function failed, zero if it succeeded.

void SIDXAcquireGetLastError	(	void *	SIDXacquire,
		wchar_t *	message,
		size_t	length
	)

The function translates the error code into a text string.

Parameters

SIDXacquire	A handle value that references the open acquire context.
message	A text string to receive the text associated with the last error occurred.
length	The length of the array to receive the text string, measured in characters. The array should include space for a null character at the end of the string.

int SIDXAcquireGetPollingInterval	(	void *	SIDXacquire,
		double &	interval
	)

Obtain the maximum interval between successive calls to the Acquire 'GetStatus' call during image Acquire.

For example, if the maximum service interval is 250ms, during Acquire, the Acquire 'GetStatus' operation must be called at least once every 250ms.

Parameters

SIDXacquire	A handle value that references the open acquire context.
interval	A variable to receive a real (floating-point) value representing the maximum service interval, in seconds.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireGetReadoutInterval	(	void *	SIDXacquire,
		double &	interval
	)

Obtain the readout interval of an exposed image in seconds.

Parameters

SIDXacquire	A handle value that references the open acquire context.
interval	A variable to receive a real (floating-point) value specifying the readout interval in seconds.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireGetStatus	(	void *	SIDXacquire,
		bool &	acquiring
	)

Update the Acquire status.

This is a polling operation. The operation must be called at least once within the service interval. For example, if the Acquire service interval is 500ms, this operation must be called at least once every 500ms. The function returns true or false to indicate that the camera is actually acquiring. If an error occurs, than the boolean value is undefined.

Parameters

SIDXacquire	A handle value that references the open acquire context.
acquiring	A variable to receive a boolean value, true if the camera is acquiring, false if not.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireImageGetCount	(	void *	SIDXacquire,
		int64_t &	count
	)

Obtain the total number of acquired images since last call to Acquire Start.

Parameters

SIDXacquire	A handle value that references the open acquire context.
count	A variable to receive an integer count containing the total number of images acquired since Acquire started.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireImageGetDescription	(	void *	SIDXacquire,
		int64_t	image_index,
		double &	start_time,
		double &	exposure_duration
	)

Obtains the exposure duration and start time for a specified image.

If the camera does not provide a start time, SIDX will provide the software time of the received image. The exposure duration is constant throughout an acquisition, except in the case that the exposure duration is set by an external trigger signal. In that case, the camera may provide the actual exposure duration separately for each image and SIDX will return a value of zero (0). If the camera does not provide the exposure duration, SIDX will return the exposure duration that was set. If the camera does provide the exposure duration, SIDX will return the value from the camera.

Parameters

SIDXacquire	A handle value that references the open acquire context.
image_index	An integer value specifying the image for which to return time.
start_time	A variable to receive a real (floating-point) value specifying the start time.
exposure_duration	A variable to receive a real (floating-point) value specifying the exposure duration.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireRead	(	void *	SIDXacquire,
		int64_t	image_count,
		short *	image_data,
		size_t	length
	)

Read images starting from the current read position.

The number of images read is the same as the image_count, otherwise SIDX will report an error.

Parameters

SIDXacquire	A handle value that references the open acquire context.
image_count	An integer value specifying the number of images to read.
image_data	The buffer to receive the image data.
length	The length of the buffer to receive the image data, in units of pixels. Each pixel occupies a short (2-bytes).

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireReadGetPosition	(	void *	SIDXacquire,
		int64_t &	position
	)

Obtain the current read position.

The read position is an integer image index. The first image is at position zero.

Parameters

SIDXacquire	A handle value that references the open acquire context.
position	A variable to receive an integer value representing the read position.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireReadoutExists	(	void *	SIDXacquire,
		bool &	available
	)

Determine whether readout interval information is available.

Parameters

SIDXacquire	A handle value that references the open acquire context.
available	A variable to receive a boolean value, true if the readout interval is available, false if the readout interval is not available.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireReadSetPosition	(	void *	SIDXacquire,
		int64_t	image_index
	)

Set the read position to the specific image.

Parameters

SIDXacquire	A handle value that references the open acquire context.
image_index	An integer value specifying new read position, expressed as an image number. The image number is greater than or equal to zero.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireSpacingGetSize	(	void *	SIDXacquire,
		size_t &	size
	)

Obtain the size of an image.

The size of an image is the amount of storage required for an image during acquisition, including padding. For example, if images during acquisition are padded to the next multiple of 512 bytes, this value will always be a multiple of 512

Parameters

SIDXacquire	A handle value that references the open acquire context.
size	A variable to receive an integer value representing the size of an image, measured in bytes.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireStart

(

void *

SIDXacquire

)

Start Acquire.

For a given open acquire context, the Acquire can start/stop an arbitrary number of times.

Parameters

SIDXacquire

A handle value that references the open acquire context.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXAcquireStop

(

void *

SIDXacquire

)

Stop Acquire.

This operation should be used only if Acquire has completed as expected, the operation should not be used to interrupt running image Acquire.

Parameters

SIDXacquire

A handle value that references the open acquire context.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXGeometryChannelGetDepth	(	void *	SIDXacquire,
		int &	depth
	)

Obtain the pixel depth of one channel from the image data.

For grayscale image, there is one channel. For RGB image, there are three channels which represent red, green and blue respectively.

Parameters

SIDXacquire	A handle value that references the open acquire context.
depth	A variable to receive an integer value representing the channel depth.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXGeometryImageGetSize	(	void *	SIDXacquire,
		size_t &	size
	)

Obtain the data size of an image.

The data size of an image is the size of the data in an image, excluding any padding.

Parameters

SIDXacquire	A handle value that references the open acquire context.
size	A variable to receive an integer value representing the size of the data in an image, measured in bytes.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXGeometryImageGetType	(	void *	SIDXacquire,
		SIDXImageType &	type
	)

Obtain the image type of the source image.

Parameters

SIDXacquire	A handle value that references the open acquire context.
type	A variable to receive a value describing the type of source image.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXGeometryPixelGetCount	(	void *	SIDXacquire,
		int &	x,
		int &	y
	)

Obtain the x and y pixel count for images.

Parameters

SIDXacquire	A handle value that references the open acquire context.
x	A variable to receive an integer value representing the pixel count on the x axis.
y	A variable to receive an integer value representing the pixel count on the y axis.

Returns

Non-zero if the function failed, zero if it succeeded.

int SIDXGeometryPixelSpacingGet	(	void *	SIDXacquire,
		double &	x,
		double &	y
	)

Obtain the pixel size in x and y.

Parameters

SIDXacquire	A handle value that references the open acquire context.
x	A variable to receive a real (floating point) value representing the horizontal pixel spacing, measured in meters.
y	A variable to receive a real (floating point) value representing the vertical pixel spacing, measured in meters.

Returns

Non-zero if the function failed, zero if it succeeded.