Hamamatsu Photonics K.K.(it is described as the following HPK) has copyright of this document and the software sample codes. This document is included in DCAM-SDK. Developer who uses DCAM-API in their custom software can refer this.

This document and the software sample codes are disclosed only for the purpose described above, and do not constitute a license, transfer, or any other entitlement for the owner.

All of risk and result of using software depending on this document remains with the user.

This document may include technical inaccuracies or typographical errors. HPK does not guarantee any damage arising from such errors or this document.

HPK makes no commitment to update or keep current the information contained in this document.

All brand and product names are trademarks or registered trademarks of their respective owners. HPK has copyright of this document with all rights reserved.

No part of this documentation may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form, or by any means, in any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of HPK.

DCAM-API is an application software program interface to control digital cameras and detecting systems manufactured by HAMAMATSU (hereafter referred to simply as "devices"). The DCAM-API installer is downloadable from our website, http://www.dcamapi.com, and it consists of the kernel drivers and DCAM modules which are the core part of DCAM-API itself. They are prepared for each digital I/F, e.g. IEEE 1394, USB, various frame grabber, etc. The DCAM-API installer also installs a manager for all modules to give a transparent control for different device models from the host software.

The DCAM-API software development kit (hereafter referred to as the "SDK") provides resources for making host software programs by their developer.

The SDK consists of header files, library files, reference files of DCAM-API functions, and source code of sample host software to provide knowledge on how to access DCAM-API. The SDK user is free to use this software in any way they like, such as partially modifying source code and creating completely separate program, and/or giving the host software or plugin module to everyone. But the following is not allowed; opening the resources that get from HAMAMATSU as SDK; making a wrapper module that is almost the same as DCAM-API itself.

Concept of DCAM-API is to provide easy development. Under this concept, DCAM-API provides common method to control the same functions in different devices and almost all of functionality are for capturing image and controlling the device. There are no functions for displaying or GUI control. Therefore, the number of functions has been limited to the minimum. For common use, format of calling function are defined in the C programming language.

HDCAM is the handle which specifies the target device on DCAM-API. Almost all DCAM-API functions use this handle as a parameter. The dcamdev_open() function provides this handle to the host software, and the dcamdev_close() function releases this handle terminating the use of the device.

HDCAMWAIT is the handle used to wait for events sent from the device. The dcamwait_open() function provides this handle. Functions with the "dcamwait_" prefix use this handle as a parameter.

HDCAMREC is the handle used for disk recording. The dcamrec_open() function provides this handle. Functions with the "dcamrec_" prefix use this handle as a parameter.

All DCAM-API functions are contained by lowercase letters starting with "dcam". All DCAM-API v4 functions are categorized. Functions in the same group have the same prefix.

All functions except dcamapi_init(), dcamapi_uninit(), and all of the open functions use a handle for the first arguments. The functions with the "dcamwait_" prefix require a HDCAMWAIT handle. The functions with the "dcamrec_" prefix require a HDCAMREC handle. All of the other functions require an HDCAM handle. Some functions require additional arguments. Some of these functions use a pointer to a structure for an argument. In case of these structure parameters, the size member should be initialized to the size of the structure before use. For other structure members that are not input, they should be initialized to 0.

All functions return a DCAMERR value except on success. All values of error are defined with the "DCAMERR_" prefix. If function succeeds, basically DCAMERR_SUCCESS is returned, but some functions return positive values that are not. Those values mean the result of processing, so the values are unstable and not defined by DCAMERR. You can use failed() function to check whether the function is success or not. This function returns TRUE when the argument value means the error.

The word "property" refers to a device parameter. The host software can get, set, and/or query device parameters with some functions with dcamprop_ prefix. Each property has a unique ID. Every property value is handled as double floating value even if it is an integer on the device. Each property has its own, name, attributes, minimum, maximum, stepping, and/or default values. Some properties are enumerative types and their values also have associated text. We call such text as value text.

There are three property value types: MODE, LONG, and REAL. These values are operated with 64bit double float variables. However, LONG and MODE are regarded as 32bit signed integer internally where as REAL is regarded as a 64bit float decimal. The LONG and REAL types are numerical values. The MODE type is not a numerical value but DCAM-API regards it as integer with unique IDs. Every MODE has text for each assigned value. Some LONG and REAL properties also have text.

The host software can distinguish each value type with DCAMPROP_TYPE_MASK from the attribute member of the DCAMPROP_ATTR structure. Every property value on the device is associated with one of these three types. However the property value type may be changed in a future version of DCAM-API. It is recommended that the host software checks the attribute member of DCAMPROP_ATTR structure for the value type to ensure compatibility, instead of assuming the property value type is fixed. The host software can check the default value and range of each property which is also available through the DCAMPROP_ATTR structure.

Each property has "attributes". Each attribute indicates the characteristics of the property. You can see following attributes in attribute member of the DCAMPROP_ATTR structure.

A property may have multiple values with identical functions. Multiple subarray is one of them. In DCAM, this type of properties is called Array. Every element of the array has a different property ID. The element with the index 0 has the base ID. The host software can enumerate the base ID of the array property. The host software can also enumerate each element in array. You can see following attributes in attribute2 member of the DCAMPROP_ATTR structure.

Property attributes are usually independent from the device but some devices may have different attributes from others. The host software should never assume that a property attribute is the same between different device models. For example, DCAM_IDPROP_SENSORTEMPERATURETARGET is readable and writable in some devices, but it is read-only in other devices.

When you use Microsoft Visual Studio and define _LINK_DCAMAPI_LIB before #include dcamapi.h, dcamapi.lib file is assigned as a library file in your project. But the folder of dcamapi.lib is not assigned so you need to describe library folders or add it into your project file.

To begin using DCAM-API, call dcamapi_init() to initialize DCAM. Then call dcamdev_open() to get the HDCAM handle for the device.

The dcamapi_init() function initializes drivers if necessary. This function requires a DCAMAPI_INIT structure as an input which you can use to choose special initialization options. If successful, the iDeviceCount member in the DCAMAPI_INIT structure indicates how many devices are connected.

The dcamdev_open() function initializes a selected device. This function requires the DCAMDEV_OPEN structure as an input which you can use to choose a device by index. This value should be between 0 and DCAMAPI_INIT::iDevceCount-1. If successful, The hdcam member in the DCAMDEV_OPEN structure will be the new HDCAM handle of the device at the specified index.

The dcamdev_close() function finalizes the device specified by the HDCAM handle and closes the handle. The HDCAM handle will no longer be usable. If host software wants to control the device again, call the dcamdev_open() function again. The new HDCAM value may be different from the one previously received. The dcamapi_uninit() function unloads all of the modules and terminates the API.

Almost DCAM-API functions requires a HDCAM handle. The HDCAM handle is used for specifying the camera that the host software controls and it is got by dcamdev_open() function.

The dcamdev_getstring() function can return information about the device and DCAM, e.g. model name, firmware version, DCAM-API version, etc. Please refer list of DCAM_IDSTRs.

DCAM properties are parameters for the device and related hardware. The host software can get and set the property values that are specified by property IDs. There are two method to get the property IDs. You can use predefined property IDs in dcamprop.h directly. This header defines many DCAM property IDs. Be aware that not all properties are supported by some devices. Always check if the device supports the property before using it directly. Another method to get the property IDs is by enumeration. DCAM-API supports property ID enumeration to provide the host software a listing of all supported properties of the current device. DCAM-API also provides information of a property with the dcamprop_getattr() function. This function requires the DCAMPROP_ATTR structure as an input. This can tell the kind of value, the range of values, various attributes, etc.

The dcamprop_getvalue() and dcamprop_setvalue() functions get and set the value of the property. The dcamprop_setgetvalue() function sets a new value then gets the actual value set to the property. The dcamprop_queryvalue() function can get the next and prior values from a selected value.

The dcamprop_getnextid() function provides the next property ID supported by the device. This function provides the ability to retrieve all property IDs that the device supports. This can also enumerate a listing of properties that have been updated when a property is changed. But the elements of array property cannot be enumerated. It is necessary for them to enumerate with the attribute that the base of array property has. The base of array property is enumerated by dcamprop_getnextid(). The dcamprop_getname() function provides the name text of a property. The dcamprop_getvaluetext() function with the DCAMPROP_VALUETEXT structure provides the value text of a specified value of a property.

To capture images, the host software needs to prepare a receiving buffer. There are two method to perform this. The first method is to use the dcambuf_alloc() function to allocate the frame buffer in the DCAM module. This is the most efficient way to receive images from the device. However, by using this method the host software needs to call the dcambuf_lockframe() function to access this data or the dcambuf_copyframe() function to copy it. The second method is to use the dcambuf_attach() function to attached a memory buffer created by the host software. By using this method, the image will be written directly to the user buffer. Therefore the host software will be capable of accessing the data without calling dcambuf_lockframe() or dcambuf_copyframe(). Be aware that some devices and/or interfaces may not support the standard data type. In this case, the DCAM module transforms the data type so the performance may be worse than the first method of using the dcambuf_alloc() function. Before starting a capture, the host software must call either dcambuf_alloc() or dcambuf_attach(). When the capture is completed and the host software no longer needs the data, the host software can call the dcambuf_release() function to release the internal receiving buffer in the DCAM module allocated by dcambuf_alloc(), or to detach the memory that was attached by dcambuf_attach().

If the host software uses the dcambuf_alloc() function to create the image buffer, it will need to use the dcambuf_lockframe() or dcambuf_copyframe() function to access captured image data. The dcambuf_lockframe() function returns a pointer to the data which the host software can use to access the image. In this function, DCAM modules copy image data from primary buffer to reserved memory with necessary conversion. Primary buffer is receiving buffer which hardware and/or lower driver directly copies to. The dcambuf_copyframe() function copies data from DCAM primary buffer to buffer which is specified by DCAMBUF_FRAME structure and managed by host software.

DCAM-API supports three kinds of system defined meta data, TIMESTAMP, FRAMESTAMP and CAMERASTAMP. TIMESTAMP is the timing on received the image. The timing itself can be varied. For example, one is that the camera measure and output the start timing of readout, other is that DCAM module measure the timing of data stream from the interface. To know the detail of this timing, the host software should check the value of DCAM_IDPROP_TIMING_TIMESTAMP and DCAM_IDPROP_TIMESTAMP_PRODUCER. TIMESTAMP_PRODUCER is what records the timing. TIMING_TIMESTAMP is what timing is in data stream. FRAMESTAMP is the number of image. This value is increased by the camera or DCAM on readout. CAMERASTAMP is the value that the host software set to the camera. To get this meta data, the host software can use the dcambuf_lockframe() or dcambuf_copyframe() function. This meta data is included in DCAMBUF_FRAME structure is argument of the function. For TIMESTAMP, the host software can use the dcambuf_attach() function with DCAMBUF_ATTACHKIND_TIMESTAMP. This allows the DCAM module to fill the TIMESTAMP information into the user allocated memory directly. The dcambuf_copymetadata() function is also available to get multiple TIMESTAMPs at once with the DCAM_TIMESTAMPBLOCK structure.

When DCAM_IDPROP_FRAMEBUNDLE_MODE is enabled, the method of accessing the information in DCAMBUF_ATTACH::buffer may differ depending on the value of dcambuf_attach::iKind. If dcambuf_attach::iKind = DCAMBUF_ATTACHKIND_FRAME, then the number of images (bundled images) specified by DCAM_IDPROP_FRAMEBUNDLE_NUMBER will be stored as shown in the above figure. On the other hand, if dcambuf_attach::iKind = DCAMBUF_ATTACHKIND_PRIMARY_TIMESTAMP/FRAMESTAMP is specified, the metadata will be stored as shown below. In this case, to access the first address of the bufferIndex of each frame with nNewestFrameIndex, use the surplus of nNewestFrameIndex*FRAMEBUNDLE_NUMBER divided by DCAMBUF_ATTACH::buffercount.

To begin capturing images, the host software should call the dcamcap_start() function. If the driver is not ready to begin capturing, e.g. dcambuf_alloc() has not been called yet, the dcamcap_start() function will return a DCAMERR. The dcamcap_start() function also has a DCAMCAP_START input that controls the capturing method. DCAMCAP_START_SEQUENCE sets continuous capturing. When the capturing reaches the final allocated frame, it will continue to capture more data going back to the first frame and overwritten the existing data. DCAMCAP_START_SNAP sets a single cycle capturing. When the capturing reaches the final allocated frame in this mode, the capturing stops. When the host software calls the dcamcap_stop() function, capturing is stopped.

The host software can check the capturing status with the dcamcap_status() function. It will return a DCAMCAP_STATUS. The dcamcap_transferinfo() function returns the total number of images captured and the frame index of the last captured image. These functions do not wait for any events and will return with their values immediately. These functions are useful for polling however this is stressful to the CPU. We recommend using dcamwait functions to wait for events such as the arrival of new frames, then calling these functions to check status and/or transferred information.

The DCAM module supports software trigger if it is supported in the device. In some cases if the device does not support it, the DCAM module may emulate software triggering. Therefore, in almost all cases the host software can use software trigger. To use software trigger, the host software needs to set DCAMPROP_TRIGGERSOURCE__SOFTWARE to the DCAM_IDPROP_TRIGGERSOURCE property and start capturing. When the host software calls the dcamcap_firetrigger() function, the DCAM Module fires a trigger to device. If dcamcap_firetrigger() is called before the camera is ready to receive the trigger signal, the DCAM module will wait until the device can recognize the trigger, then it will fire. If the host software needs to synchronize with other devices, it can call the dcamcap_firetrigger() function when these other devices are ready.

DCAM-API can record images to disk simultaneously while capturing. To do this, after preparing HDCAMREC handle, host software needs to call dcamcap_record() function before calling dcamcap_start() function. This is a one time function so if host software wants to record again at next capturing, it has to call dcamcap_record() function again.

The HDCAMWAIT handle is prepared for the dcamwait functions. The handle is associated to the HDCAM handle and it is created by the dcamwait_open() function. When the host software does not need the handle anymore, it should call the dcamwait_close() function.

The host software can wait for specific capturing and recording events by calling the dcamwait_start() function. There are several EVENTs that the host software can wait for. The capturing events are named with the DCAMWAIT_CAPEVENT_ prefix and recording events are named with the DCAMWAIT_RECEVENT_ prefix. Timeout is specified by the DCAMWAIT_START::timeout member. The timeout is defined in milliseconds. To wait indefinitely until the event comes, the timeout value should be set to DCAMWAIT_TIMEOUT_INFINITE. To cancel the waiting, call the dcamwait_abort() function to terminate the waiting specified by the HDCAMWAIT handle.

To use the disk recorder, the target file must be prepared first by calling the dcamrec_open() function. The HDCAM handle is not used with this function. To start recording, the dcamcap_record() function should be called during READY state. Finally, calling the dcamcap_start() function after dcamcap_record() starts the recording. When the host software calls the dcamrec_close() function, all of the file information is stored. Be aware that if the host software terminates without calling the dcamrec_close() function, some data may be lost.

If the host software wants to pause the disk recorder, the dcamrec_pause() function should be called. If the host software wants to resume the recorder during capturing, the dcamrec_resume() function should be called, however this will need additional time to prepare the file. When the capturing has ended or the recorder has reached the specified recording frame number, the recorder will automatically stop. To get the current recording status, use the dcamrec_status() function. If DCAMREC_STATUS::flags has DCAMREC_STATUSFLAG_RECORDING flag, recording is in process.

During a recording session, the host software can access the frames that have already been recorded by using the dcamrec_lockframe() or dcamrec_copyframe() function. These functions will cause some stress to the computer so we do not recommend using them during a recording.

The DCAM modules support three types of meta data. The first type is TIME STAMP. This will record the capture timing by hardware, kernel driver, or the DCAM module. The other two meta data types are USERDATA types. One is TEXT and the other is BINARY. Usually, the meta data is associated to each frame, but DCAM also prepares meta data associated with the session and/or file.

User meta data can be written by dcamrec_writemetadata() function. When the host software is writing TEXT type meta data, the DCAM_USERDATATEXT structure should be used as argument with DCAM_METADATAKIND_USERDATATEXT for the hdr.iKind member. When the host software is writing BINARY type meta data, the DCAM_USERDATABIN structure should be used as argument with DCAM_METADATAKIND_USERDATABIN for the hdr.iKind member. To choose the target for the meta data, use the DCAMREC_METADATAOPTION enum and set into hdr.option.

To get the meta data, the host software should use the dcamrec_lockmetadata() function or the dcamrec_copymetadata() function. If using DCAM_USERDATATEXT and DCAM_USERDATABIN, The host software needs to set hdr->iKind and hdr->iOption. dcamrec_lockmetadata() function returns pointer which host software can access to data and dcamrec_copymetadata() function copies data from meta file buffer in DCAM to user specified buffer. Above two functions only access to one data. To access many meta data at once, dcamrec_lockmetadatablock() function and dcamrec_copymetadatablock() function are available. DCAM_METADATAKIND_TIMESTAMPS is defined to give TIMESTAMP in buffer.

Even if DCAM property settings are same, recording data size can be different depending on camera, interface, peripheral devices, etc. DCAM can return recording data size except meta data. DCAM_IDPROP_RECORDFIXEDBYTES_PERFRAME is per frame, DCAM_IDPROP_RECORDFIXEDBYTES_PERFILE and DCAM_IDPROP_RECORDFIXEDBYTES_PERSESSION are per file and session. Following equation returns recording data size: (RECORDFIXEDBYTES_PERFILE + File meta data size) + (RECORDFIXEDBYTES_PERSESSION + Session meta data size) + ((RECORDFIXEDBYTES_PERFRAME + Frame meta data size) * Number of Frames).

DCAMERR dcamapi_init( DCAMAPI_INIT* param );

The dcamapi_init() function initializes the DCAM-API manager, modules, and drivers. Only one session of DCAM-API can be open at any time. If the host software wants to call dcamapi_init() again, it should end the current session of DCAM-API with the dcamapi_uninit() function. If this function finds any supported device, this function returns DCAMERR_SUCCESS. DCAMAPI_INIT::iDeviceCount will be set to the number of supported devices found. If DCAM does not find any supported device, this function will return an error code.

DCAMERR dcamapi_uninit(void);

The dcamapi_uninit() function cleanups all resources and objects used by DCAM. All opened devices will be forcefully closed. Any resources used by the individual devices will also be released. No new devices can be opened unless the dcamapi_init() function is called again.

DCAMERR dcamdev_open( DCAMDEV_OPEN* param );

The dcamdev_open() function opens the specified device and returns an HDCAM handle. If the host software does not need the HDCAM handle anymore, it should call the dcamdev_close() function. After calling the dcamdev_close() function, the HDCAM handle is no longer valid. The host software can call dcamdev_open() function to get the HDCAM handle again. If this function succeeds, DCAMDEV_OPEN::hdcam will be set to the HDCAM handle of specified device. If DCAM fails to open the specified device, this function will return an error code.

DCAMERR dcamdev_close( HDCAM h );

The dcamdev_close() function releases the HDCAM handle and the associated device. If this function succeeds, the HDCAM handle will no longer be valid. To use the same device again, the host software must call dcamdev_open() again to get a new HDCAM handle. The dcamdev_close() function forcibly terminates active capturing and waiting sessions, and releases attached or allocated buffers if they exist.

DCAMERR dcamdev_getcapbility( HDCAM h, DCAMDEV_CAPABILITY* param );

The dcamdev_getcapability() function returns the capability information not to get from the property in DCAMDEV_CAPABILITY structure. This information is set by DCAMDEV_CAPFLAG.

DCAMERR dcamdev_getstring( HDCAM h, DCAMDEV_STRING* param );

The dcamdev_getstring() function returns device information specified by DCAM_IDSTR　or error information specified by DCAMERR. The host software can call this function with the HDCAM handle received by the dcamdev_open() function. To receive the information without calling dcamdev_open(), this function can be called with the device index. If DCAM does not support specified DCAM_IDSTR id, this function will return an error code. If successful, DCAM fills '\0' at the end of the character string. If the requested information is longer than buffer size, it will be truncated.

DCAMERR dcamdev_setdata( HDCAM h, DCAMDATA_HDR* param );

The dcamdev_setdata() function sets the data that it is impossible to set with the property. The structure is prepared by the kind of data. These structures have DCAMDATA_HDR as the first member.

DCAMERR dcamdev_getdata( HDCAM h, DCAMDATA_HDR* param );

The dcamdev_getdata() function gets the data that it is impossible to get with the property. The structure is prepared by the kind of data. These structures have DCAMDATA_HDR as the first member.

DCAMERR dcamprop_getattr( HDCAM h, DCAMPROP_ATTR* param );

The dcamprop_getattr() function fills the DCAMPROP_ATTR structure with attribute information of the property. The DCAMPROP_ATTR structure is specified by param parameter, and the property is specified property ID by the iProp member. Before using the DCAMPROP_ATTR structure, the host software should initialize it to 0 then set the iProp member. Please refer to section structure DCAMPROP_ATTR. If the device does not support the specified property, this function will return an error code.

DCAMERR dcamprop_getvalue( HDCAM h, int32 iProp, double* pValue );

The dcamprop_getvalue() function returns a double floating value into the pValue argument with the property value specified by the iProp argument.

DCAMERR dcamprop_setvalue( HDCAM h, int32 iProp, double fValue );

The dcamprop_setvalue() function sets a double floating value specified by fValue into the property specified by iProp. If the device specified by the h argument does not support the iProp property id, this function will fail with the error code DCAMERR_NOTSUPPORT. If the iProp property does not have AUTOROUNDING and the value specified by fValue is not valid value, the function will fail and will generate the error code DCAMERR_INVALIDPARAM.

DCAMERR dcamprop_setgetvalue( HDCAM h, int32 iProp, double* pValue, int32 option );

The dcamprop_setgetvalue() function sets a double floating value specified by the pValue argument to the property specified by iProp then gets the accurate value if successful. If the device does not support the iProp property id, this function will fail with the error code DCAMERR_NOTSUPPORT. If the pValue argument is invalid, this function will fail and will generate the error code DCAMERR_INVALIDPARAM. If the iProp property does not have AUTOROUNDING and the value specified by pValue is not a valid value, the function will fail and will generate the error code DCAMERR_INVALIDPARAM.

DCAMERR dcamprop_queryvalue( HDCAM h, int32 iProp, double* pValue, int32 option );

The dcamprop_queryvalue() function returns the actual property value when a given value is set but without setting the new value. If the option argument is set to DCAMPROP_OPTION_PRIOR or DCAMPROP_OPTION_NEXT, this function will return the prior or next value. If the device does not support the property, this function will fail with the error code DCAMERR_NOTSUPPORT. If the device supports the property but the prior or next values are out of range, this function will fail with the error code DCAMERR_OUTOFVALUE.

DCAMERR dcamprop_getnextid( HDCAM h, int32* pProp, int32 option );

The dcamprop_getnextid() function provides a way to query all supported property IDs of a device. If the host software calls this function with the iProp value set to 0, the function will return the next property ID in the iProp value. If the host software calls the dcamprop_getnextid() function in a loop where you set iProp with the value of the previous property ID, you will be able to retrieve all the property IDs that the device supports. The end of the list is determined when iProp returns 0. If the device does not support the input property ID, the property ID will be the next value which it supports. Please see Sample - Enumerate supported properties. If the host software sets the option DCAMPROP_OPTION_UPDATED, this function enumerates only the properties that the value have changed. If the host software sets the option DCAMPROP_OPTION_VOLATILE, this function enumerates all of the VOLATILE properties.

DCAMERR dcamprop_getname( HDCAM h, int32 iProp, char* text , int32 textbytes );

The dcamprop_getname() function returns the character string as the name of the property specified by the iProp argument. If the device specified by the h argument does not support the iProp property ID, this function will fail with the error code DCAMERR_NOTSUPPORT.

DCAMERR dcamprop_getvaluetext( HDCAM h, DCAMPROP_VALUETEXT* param );

The dcamprop_getvaluetext() function returns the character string as a property value. The host software has to set property ID as iProp and the value as a value member. If the device does not support the property, this function will fail with the error code DCAMERR_NOTSUPPORT. If the device supports the property but the value is not available, the function will fail with the error code DCAMERR_INVALIDVALUE.

DCAMERR dcambuf_alloc( HDCAM h, int32 framecount );

The dcambuf_alloc() function allocates internal image buffers for image acquisition. This function does not start the capture. To start capture, dcamcap_start() should be called. dcambuf_attach() function is exclusive. When the images are received, dcambuf_lockframe() and dcambuf_copyframe() can be used to access the data from the buffer. When the internal buffers are no longer necessary, call dcambuf_release() to release them. If capturing has already begun or properties condition is not good, this function will return an error.

DCAMERR dcambuf_attach( HDCAM h, const DCAMBUF_ATTACH* param );

The dcambuf_attach() function assigns allocated memory as the capturing buffer for the host software. DCAM will transfer the image data directly from the device to these buffers. The dcambuf_attach() function should be called after setting necessary properties and before calling dcamcap_start() function. The dcambuf_alloc() function is exclusive. The host software can get the required buffer size by getting the property value of DCAM_IDPROP_BUFFER_FRAMEBYTES. DCAM does not verify if the frame buffer pointers are valid. The system may hang up if the frame buffer pointers contain an invalid address. If the host software no longer requires the attached buffer, the dcambuf_release() function should be called to release the buffer from DCAM.

DCAMERR dcambuf_release( HDCAM h, int32 iKind );

The dcambuf_release() function releases capturing buffer which is allocated by dcambuf_alloc() or assigned by dcambuf_attached(). If capturing is in progress, the dcambuf_release() function returns DCAMERR_BUSY to notify the host software that the device is in BUSY status.

DCAMERR dcambuf_lockframe( HDCAM h, const DCAMBUF_FRAME* pFrame );

The dcambuf_lockframe() function returns a pointer that the host software can use to access the captured image data. If the host software needs to copy the image data into its own memory, the dcambuf_copyframe() function can be used instead. If the image frame specified by DCAMBUF_FRAME::iFrame has not been filled yet, the dcambuf_lockframe() function will return DCAMERR_BUSY.

DCAMERR dcambuf_copyframe( HDCAM h, DCAMBUF_FRAME* pFrame );

The dcambuf_copyframe() function copies image data from capturing buffer to a buffer provided by the host software. The capturing buffer must be prepared by the dcambuf_alloc() function. If the host software is using the dcambuf_attach() function, this function will fail.

DCAMERR dcambuf_copymetadata( HDCAM h, DCAM_METADATAHDR* hdr );

The dcambuf_copymetadata() function copies meta data from the DCAM internal buffer to a specified buffer that the host software provides. The available kinds of meta data are TIMESTAMP and FRAMESTAMP.

DCAMERR dcamcap_start( HDCAM h, int32 mode );

The dcamcap_start() function start capturing images. Before calling this function, a capturing buffer should be prepared with dcambuf_alloc() or dcambuf_attach(). With the DCAMCAP_START_SEQUENCE mode, capturing will be continuing until the dcamcap_stop() function is called. With the DCAMCAP_START_SNAP mode, capturing is terminated when the capturing buffer is filled or until the dcamcap_stop() function is called.

DCAMERR dcamcap_stop( HDCAM h );

The dcamcap_stop() function terminates capture started by the dcamcap_start() function. If the capturing has already been terminated, this function will do nothing. If the device is recording, that process will also be terminated.

DCAMERR dcamcap_status( HDCAM h, int32* pStatus );

The dcamcap_status() function returns current capturing status.

DCAMERR dcamcap_transferinfo( HDCAM h, DCAMCAP_TRANSFERINFO* param );

The dcamcap_transferinfo() function returns current image transfer status.

DCAMERR dcamcap_firetrigger( HDCAM h, int32 iKind );

The dcamcap_firetrigger() function fires a software trigger to the device. This is only effective while capturing in SOFTWARE trigger mode.

DCAMERR dcamcap_record( HDCAM h, HDCAMREC hrec );

The dcamcap_record() function prepares for the recording of images into storage during capturing. Before calling this function, the HDCAMREC handle should be prepared by the dcamrec_open() function. After calling dcamcap_record() function, the dcamcap_start() function starts image capturing and recording. The dcamrec_pause() function can stop the recording.

DCAMERR dcamwait_open( DCAMWAIT_OPEN* param );

The dcamwait_open() function creates the HDCAMWAIT handle. Before calling this function, the DCAMWAIT_OPEN structure should set the size and hdcam member. The hdcam member should be the HDCAM handle of the target device. If the function succeeds, the hwait member will be set with created HDCAMWAIT handle. The supportevent member indicates which events are supported in the device. To wait for an event, you should call the dcamwait_start() function with HDCAMWAIT handle. To cancel waiting for an event, call the dcamwait_abort() function. When HDCAMWAIT handle is no longer needed, call the dcamwait_close() function to release the handle.

DCAMERR dcamwait_close( HDCAMWAIT h );

The dcamwait_close() function releases the HDCAMWAIT handle. Please call this function when the HDCAMWAIT handle is no longer needed.

DCAMERR dcamwait_start( HDCAMWAIT h, DCAMWAIT_START* param );

The dcamwait_start() function start waiting for a specified DCAM event. Before calling this function, the DCAMWAIT_START structure should be initialize size member, eventmask member and timeout member. eventmask member should be filled with DCAM events which host software wants to wait. The DCAM events are assigned to individual bits so eventmask member can have several events. timeout member specifies how long this function will wait as maximum by mili-seconds. If host software wants to wait until event happens, please set DCAMWAIT_TIMEOUT_INFINITE value. When the function succeeded, eventhappened member is set with one of DCAMWAIT_EVENT values which were set in eventmask member. If any DCAM events did not happen, function returns DCAMERR_TIMEOUT error. And if host software calls aborting function, e.g. dcamwait_abort(), function returns DCAMERR_ABORT error.

DCAMERR dcamwait_abort( HDCAMWAIT h );

The dcamwait_abort() function aborts a dcamwait_start() call with same HDCAMWAIT handle while it is waiting for a DCAM event. If the dcamwait_abort() function succeeds, the dcamwait_start() function will return with the error code DCAMERR_ABORT. If there is no waiting function, nothing will happen.

DCAMERR dcamrec_open( DCAMREC_OPEN* param );

The dcamrec_open() function creates a HDCAMREC handle. Before calling this function, DCAMREC_OPEN structure instance which is pointed by param argument should be set size member and path member which specifies the file path for storing. If host software uses meta data, the maximum bytes should be set into the members. For starting recording, call dcamcap_record() function before dcamcap_start() function.

DCAMERR dcamrec_close( HDCAMREC hrec );

When the HDCAMREC handle is no longer needed, the dcamrec_close() function flushes all of the data including the meta data and releases it. If host software uses recorded file, use DCIMGAPI function.

DCAMERR dcamrec_lockframe( HDCAMREC hrec, DCAMREC_FRAME* pFrame );

The dcamrec_lockframe() function returns a pointer that the host software can use to access the recorded image data. Next calling this function will prepare new data, so parameter which was filled by last call is no more available. To avoid this situation, it is better host software calls dcamrec_lockframe() function from A thread. If host software needs to copy image data into its own memory, dcamrec_copyframe() function is suitable. If the image frame which is specified by DCAMREC_FRAME::iFrame is not filled yet, dcamrec_lockframe() function will return DCAMERR_BUSY.

DCAMERR dcamrec_copyframe( HDCAMREC hrec, DCAMREC_FRAME* pFrame );

The dcamrec_copyframe() function copies image data from recorded image to specified buffer that host software gives.

DCAMERR dcamrec_writemetadata( HDCAMREC hrec, const DCAM_METADATAHDR* hdr );

The dcamrec_writemetadata() function writes meta data into recording file. Meta data can be associated to each frame, the session and file itself.

DCAMERR dcamrec_lockmetadata( HDCAMREC hrec, DCAM_METADATAHDR* hdr );

The dcamrec_lockmetadata() function gets the address of meta data in the recording file. The meta data is associated with each frame, each session, and the file itself.

DCAMERR dcamrec_copymetadata( HDCAMREC hrec, DCAM_METADATAHDR* hdr );

The dcamrec_copymetadata() function copies meta data in recording file into the user specified buffer. Meta data is associated to each frame, session, and the file itself.

DCAMERR dcamrec_lockmetadatablock( HDCAMREC hrec, DCAM_METADATABLOCKHDR* hdr );

The dcamrec_lockmetadatablock() function gets multiple addresses of meta data from a recording file.

DCAMERR dcamrec_copymetadatablock( HDCAMREC hrec, DCAM_METADATABLOCKHDR* hdr );

The dcamrec_copymetadatablock() function copies multiple addresses of meta data from a recording file into the user specified buffer.

DCAMERR dcamrec_pause( HDCAMREC hrec );

The dcamrec_pause() function pauses the disk recorder. However, this function does not stop the image capturing to the DCAM buffer. To resume recording, use the dcamrec_resume() function.

DCAMERR dcamrec_resume( HDCAMREC hrec );

The dcamrec_resume() function resumes the disk recording.

DCAMERR dcamrec_status( HDCAMREC hrec, DCAMREC_STATUS* pStatus );

The dcamrec_status() function gets the current recording status.

struct DCAM_GUID { _ui32 Data1; // unsigned short Data2; // unsigned short Data3; // unsigned char Data4[8]; // };

struct DCAMAPI_INIT { int32 size; // sizeof(*this) int32 iDeviceCount; // number of recognized devices int32 reserved; // Reserved int32 initoptionbytes; // maximum bytes of the initoption array const int32* initoption; // initialize options, array of DCAMAPI_INITOPTION const DCAM_GUID* guid; // GUID option };

struct DCAMDEV_OPEN { int32 size; // sizeof(*this) int32 index; // index of the device to open HDCAM hdcam; // };

struct DCAMDEV_CAPABILITY { int32 size; // size of whole structure int32 domain; // Specify domain int32 capflag; // supported flag int32 kind; // detail of domain };

struct DCAMDEV_CAPABILITY_LUT { DCAMDEV_CAPABILITY hdr; // size = sizeof(*this), domain = DCAMDEV_CAPDOMAIN__DCAMDATA, kind = DCAMDATA_KIND__LUT int32 linearpointmax; // max count of point for linear LUT };

struct DCAMDEV_CAPABILITY_REGION { DCAMDEV_CAPABILITY hdr; // size = sizeof(*this), domain = DCAMDEV_CAPDOMAIN__DCAMDATA, kind = DCAMDATA_KIND__REGION int32 horzunit; // horizontal step of region int32 vertunit; // vertical step of region };

struct DCAMDEV_CAPABILITY_FRAMEOPTION { DCAMDEV_CAPABILITY hdr; // size = sizeof(*this), domain = DCAMDEV_CAPDOMAIN__FRAMEOPTION int32 supportproc; // supported DCAMBUF_PROCTYPE };

struct DCAMDEV_STRING { int32 size; // sizeof(*this) int32 iString; // char* text; // int32 textbytes; // };

struct DCAMDATA_HDR { int32 size; // size of whole structure, not only this int32 iKind; // int32 option; // DCAMDATA_OPTION int32 reserved2; // reserved };

struct DCAMDATA_REGION { DCAMDATA_HDR hdr; // size member should be size of this structure int32 option; // reserved int32 type; // DCAMDATA_REGIONTYPE void* data; // top pointer of data int32 datasize; // size of data int32 reserved; // reserved };

struct DCAMDATA_REGIONRECT { short left; // short top; // short right; // short bottom; // };

struct DCAMDATA_LUT { DCAMDATA_HDR hdr; // size member should be size of this structure int32 type; // DCAMDATA_LUTTYPE int32 page; // page number void* data; // top pointer of data int32 datasize; // size of data int32 reserved; // reserved };

struct DCAMDATA_LINEARLUT { int32 lutin; // int32 lutout; // };

struct DCAMPROP_ATTR { int32 cbSize; // sizeof(*this) int32 iProp; // DCAMIDPROPERTY int32 option; // reserved int32 iReserved1; // reserved int32 attribute; // DCAMPROPATTRIBUTE int32 iGroup; // reserved int32 iUnit; // DCAMPROPUNIT int32 attribute2; // DCAMPROPATTRIBUTE2 double valuemin; // minimum value double valuemax; // maximum value double valuestep; // minimum stepping value between two contiguous valid values double valuedefault; // default value int32 nMaxChannel; // max channel if supported int32 iReserved3; // 0 reserved int32 nMaxView; // max view if supported int32 iProp_NumberOfElement; // property id to get number of elements of this property if it is array int32 iProp_ArrayBase; // base id of array if element int32 iPropStep_Element; // step for iProp to next element };

struct DCAMPROP_VALUETEXT { int32 cbSize; // sizeof(*this) int32 iProp; // DCAMIDPROP double value; // value of the property char* text; // text of the value int32 textbytes; // text buf size };

struct DCAMBUF_ATTACH { int32 size; // sizeof(*this) int32 iKind; // DCAMBUF_ATTACHKIND void** buffer; // array of buffer pointers int32 buffercount; // number of pointers in array "buffer" };

struct DCAM_TIMESTAMP { int32 sec; // int32 microsec; // };

struct DCAMBUF_FRAME { int32 size; // sizeof(*this) int32 iKind; // reserved int32 option; // reserved int32 iFrame; // frame index void* buf; // pointer to the image int32 rowbytes; // byte size for next line DCAM_PIXELTYPE type; // pixel type in image data int32 width; // horizontal pixel count int32 height; // vertical line count int32 left; // horizontal start pixel int32 top; // vertical start line DCAM_TIMESTAMP timestamp; // time stamp int32 framestamp; // frame stamp int32 camerastamp; // camera stamp };

struct DCAMREC_FRAME { int32 size; // sizeof(*this) int32 iKind; // reserved int32 option; // DCAMREC_FRAME_OPTION int32 iFrame; // frame index void* buf; // pointer for top-left image int32 rowbytes; // byte size for next line DCAM_PIXELTYPE type; // this member is reserved, set to 0 int32 width; // horizontal pixel count int32 height; // vertical line count int32 left; // horizontal start pixel int32 top; // vertical start line DCAM_TIMESTAMP timestamp; // time stamp int32 framestamp; // frame stamp int32 camerastamp; // camera stamp };

struct DCAMWAIT_OPEN { int32 size; // sizeof(*this) int32 supportevent; // supported events HDCAMWAIT hwait; // handle for dcamwait functions HDCAM hdcam; // the HDCAM handle of the device };

struct DCAMWAIT_START { int32 size; // sizeof(*this) int32 eventhappened; // int32 eventmask; // int32 timeout; // };

struct DCAMCAP_TRANSFERINFO { int32 size; // sizeof(*this) int32 iKind; // DCAMCAP_TRANSFERKIND int32 nNewestFrameIndex; // index of the newest frame int32 nFrameCount; // number of captured frames };

struct DCAMREC_OPEN { int32 size; // sizeof(*this) int32 reserved; // HDCAMREC hrec; // handle for dcamrec functions const TCHAR* path; // destination path const TCHAR* ext; // extension of destination file int32 maxframepersession; // maximum per session int32 userdatasize; // user data size int32 userdatasize_session; // user data size for session int32 userdatasize_file; // user data size for file int32 usertextsize; // user text size int32 usertextsize_session; // user text size for session int32 usertextsize_file; // user text size for file };

struct DCAM_METADATAHDR { int32 size; // size of whole structure, not only this int32 iKind; // DCAM_METADATAKIND (DCAMBUF_METADATAKIND or DCAMREC_METADATAKIND) int32 option; // value meaning depends on DCAM_METADATAKIND int32 iFrame; // frame index };

struct DCAM_METADATABLOCKHDR { int32 size; // size of whole structure, not only this int32 iKind; // DCAM_METADATAKIND int32 option; // value meaning depends on DCAMBUF_METADATAOPTION or DCAMREC_METADATAOPTION int32 iFrame; // start frame index int32 in_count; // max count of meta data int32 outcount; // count of got meta data };

struct DCAM_USERDATATEXT { DCAM_METADATAHDR hdr; // size member should be size of this structure char* text; // Text meta data int32 text_len; // byte size of meta data int32 codepage; // DCAM_CODEPAGE };

struct DCAM_USERDATABIN { DCAM_METADATAHDR hdr; // size member should be size of this structure void* bin; // binary meta data int32 bin_len; // byte size of binary meta data int32 reserved; // 0 reserved };

struct DCAM_TIMESTAMPBLOCK { DCAM_METADATABLOCKHDR hdr; // size member should be size of this structure DCAM_TIMESTAMP* timestamps; // pointer for TIMESTAMP block int32 timestampsize; // sizeof(DCAM_TIMESTAMP) int32 timestampvaildsize; // return the written data size of DCAM_TIMESTAMP int32 timestampkind; // return timestamp kind(Hardware, Driver, DCAM etc..) int32 reserved; // 0 reserved };

struct DCAM_FRAMESTAMPBLOCK { DCAM_METADATABLOCKHDR hdr; // size member should be size of this structure int32* framestamps; // pointer for frame stamp block int32 reserved; // 0 reserved };

struct DCAM_METADATATEXTBLOCK { DCAM_METADATABLOCKHDR hdr; // size member should be size of this structure void* text; // array of pointer for user text metadata int32* textsizes; // array of pointer for sizes of user text metadata int32 bytesperunit; // global size of text metadata int32 reserved; // reserved int32* textcodepage; // code page for text };

struct DCAM_METADATABINBLOCK { DCAM_METADATABLOCKHDR hdr; // size member should be size of this structure void* bin; // array of pointers for user data int32* binsizes; // array of pointer for sizes of user binary metadata int32 bytesperunit; // global size of binary metadata int32 reserved; // reserved };

struct DCAMREC_STATUS { int32 size; // sizeof(*this) int32 currentsession_index; // current session index int32 maxframecount_per_session; // maximum frame count per session int32 currentframe_index; // current frame index int32 missingframe_count; // missing frame count int32 flags; // DCAMREC_STATUSFLAG int32 totalframecount; // total frame count int32 reserved; // reserved };