v25.5.6964

Read before using


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.

Go to top of this chapter


Overview


DCAM-API
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.

SDK
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
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.

Go to top of this chapter


General rule


Related to "Handles"
HDCAM
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
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
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.


Related to "Functions"
Function name
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.
List of Function Prefixes
prefix function name target
dcamapi_ init, uninit DCAM-API
dcamdev_ open, close, getcapability, getstring, setdata, getdata DCAM device
dcambuf_ alloc, attach, release, lockframe, copyframe, copymetadata capturing buffer
dcamcap_ start, stop, status, transferinfo, firetrigger, record capturing
dcamwait_ open, close, start, abort event waiting
dcamrec_ open, close, pause, resume, status, lockframe, copyframe, writemetadata, lockmetadata, copymetadata, lockmetadatablock, copymetadatablock recording

Function arguments
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.

Function return
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.


Property
What is "Property" in DCAM?
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.

Property Value Types
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.
List of Property value types
Type ID
MODE DCAMPROP_TYPE_MODE
LONG DCAMPROP_TYPE_LONG
REAL DCAMPROP_TYPE_REAL
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.

Property Attributes
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.
DCAMPROPATTRIBUTE flag
DCAMPROP_ATTR_ explanation
READABLE The value of this property can be read. The almost properties has this attribute but if it is a kind of "action", it does not have this attribute.
WRITABLE The value of this property can be changed. Some properties, like information, do not have this attribute.
AUTOROUNDING The property value will be adjusted if host software does not set an accurate value. The module will usually round-up to the next valid value or round-down if the value is bigger than maximum. A MODE property will never have this attribute.
STEPPING_INCONSISTENT The stepping value of this property is not consistent throughout its range
VOLATILE The value of this property may be changed manually and/or automatically by the device. Temperature status is one of them.
DATASTREAM Changing the value of this property will affect the data stream
ACCESSREADY The value of this property can be changed during READY state. If the property does not have this attribute and you access it during READY state, DCAM returns the error DCAMERR_NOTSTABLE.
ACCESSBUSY The value of this property can be changed during BUSY state. If the property does not have this attribute and you access it during BUSY state, DCAM returns the error DCAMERR_BUSY.

Array
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.
DCAMPROPATTRIBUTE2 flag
DCAMPROP_ATTR_ explanation
ARRAYBASE Represent existing multiple similar properties as Array. The top of element in an Array has ARRAYBASE flag.
ARRAYELEMENT Represent the property is one element of an Array.
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.


Compile option
_LINK_DCAMAPI_LIB
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.

Go to top of this chapter


Calling sequence


Initialization and Termination, and HDCAM handle
Initialization
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.

Termination
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.

HDCAM handle
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.

Getting device and DCAM information
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.


Property access
Accessing property
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.

Getting, setting and querying value
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.

Enumeration, property text and property value text
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.


Acquisition buffer control
alloc, attach and release
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().

lockframe and copyframe
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.

meta data
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.

Example of buffer access for a frame bundle
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.


Capturing control
start and stop capturing
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.

capturing status
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.

Software trigger
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.

Recording
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.


Synchronization control
HDCAMWAIT handle, open, and close
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.

Waiting EVENT and abort
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.


Recording control
Preparation, start, and stop recording.
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.

pause, resume, and status.
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.

Access image data
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.


Access metadata at recording
Kind of meta data
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.

Writing user meta data
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.

Getting user meta data
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.

Recording data size
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).

Go to top of this chapter


Type Declarations



DCAMERR
DCAMERR_BUSY device status is DCAM_STATUS_BUSY.
DCAMERR_NOTREADY device status is not DCAM_STATUS_READY.
DCAMERR_NOTSTABLE device status is not DCAM_STATUS_STABLE.
DCAMERR_UNSTABLE device status is not DCAM_STATUS_STABLE.
DCAMERR_NOTBUSY device status is not DCAM_STATUS_BUSY.
DCAMERR_EXCLUDED some resource is exclusive and already used
DCAMERR_COOLINGTROUBLE a problem occurred with the cooler
DCAMERR_NOTRIGGER no trigger was received when expected. Some devices support this error.
DCAMERR_TEMPERATURE_TROUBLE temperature warning on the device
DCAMERR_TOOFREQUENTTRIGGER input trigger is too frequent. Some devices support this error.
DCAMERR_ABORT process was aborted
DCAMERR_TIMEOUT process has timed out
DCAMERR_LOSTFRAME frame data has been lost
DCAMERR_MISSINGFRAME_TROUBLE frame data has been lost due to problems in the low level driver
DCAMERR_INVALIDIMAGE hpk format data is invalid data
DCAMERR_NORESOURCE not enough resources other than memory
DCAMERR_NOMEMORY not enough memory
DCAMERR_NOMODULE no sub module
DCAMERR_NODRIVER no driver
DCAMERR_NOCAMERA no device
DCAMERR_NOGRABBER no grabber
DCAMERR_FAILOPEN Fail to open
DCAMERR_INVALIDMODULE dcamapi_init() function found invalid module
DCAMERR_INVALIDCOMMPORT invalid serial port
DCAMERR_FAILOPENBUS the bus or driver are not available
DCAMERR_FAILOPENCAMERA device report error during opening
DCAMERR_DEVICEPROBLEM Device has the trobule.
DCAMERR_FRAMEGRABBER_NEEDS_FIRMWAREUPDATE Need to update the firmware of frame grabber.
DCAMERR_INVALIDCAMERA invalid device
DCAMERR_INVALIDHANDLE invalid device handle
DCAMERR_INVALIDPARAM invalid parameter
DCAMERR_INVALIDVALUE invalid property value
DCAMERR_OUTOFRANGE value is out of range
DCAMERR_NOTWRITABLE the property is not writable
DCAMERR_NOTREADABLE the property is not readable
DCAMERR_INVALIDPROPERTYID the property id is invalid
DCAMERR_NEWAPIREQUIRED action requires use of newer API version
DCAMERR_WRONGHANDSHAKE DCAM received an error code from the device unexpectedly
DCAMERR_NOPROPERTY there is no alternative or influence id, or no more property id
DCAMERR_INVALIDCHANNEL the property id specifies invalid channel
DCAMERR_INVALIDVIEW the property id specifies invalid view
DCAMERR_INVALIDSUBARRAY the combination of subarray values are invalid. e.g. DCAM_IDPROP_SUBARRAYHPOS + DCAM_IDPROP_SUBARRAYHSIZE is greater than the number of horizontal pixel of sensor.
DCAMERR_ACCESSDENY the property cannot be accessed during this DCAM STATUS
DCAMERR_NOVALUETEXT the property does not have value text
DCAMERR_WRONGPROPERTYVALUE at least one property value is wrong
DCAMERR_DISHARMONY the paired devices do not have the same parameters
DCAMERR_FRAMEBUNDLESHOULDBEOFF framebundle mode should be OFF under current property settings
DCAMERR_INVALIDFRAMEINDEX the frame index is invalid
DCAMERR_INVALIDSESSIONINDEX the session index is invalid
DCAMERR_NOCORRECTIONDATA dark or shading correction data has not been taken yet.
DCAMERR_NOTSUPPORT device does not support the function or property with current settings
DCAMERR_CHANNELDEPENDENTVALUE each channel has own property value so can't return overall property value.
DCAMERR_VIEWDEPENDENTVALUE each view has own property value so can't return overall property value.
DCAMERR_NODEVICEBUFFER Frame count is larger than device buffer size.
DCAMERR_REQUIREDSNAP Need to set snap as capture mode on using device memory.
DCAMERR_INVALIDCALIBSETTING Setting of properties is invalid on sampling calibraiton data.
DCAMERR_LESSSYSTEMMEMORY System memory size is too small to control camera. PC doesn't have enough memory or is limited memory by WOW64.
DCAMERR_INVALID_REALTIMEGAINCORRECTREGIONS the combination of hpos and hsize for correct region of realtime gain are invalid. e.g. DCAM_IDPROP_REALTIMECORRECTREGION_HPOS + DCAM_IDPROP_REALTIMECORRECTREGION_HSIZE is grater than the number of horizontal pixel of sensor.
DCAMERR_FAILREADCAMERA Receiving or reading register was failed.
DCAMERR_FAILWRITECAMERA Sending or writing register was failed.
DCAMERR_CONFLICTCOMMPORT Comm port setting is conflict
DCAMERR_OPTICS_UNPLUGGED Optics part is unplugged
DCAMERR_FAILCALIBRATION fail calibration
DCAMERR_MISMATCH_CONFIGURATION Mismatch between camera output(connection) and frame grabber specification.
DCAMERR_INVALIDMEMBER_x x-th member variable is invalid value.
DCAMERR_FAILEDOPENRECFILE Failed to open recording file
DCAMERR_INVALIDRECHANDLE Recording handle is invalid
DCAMERR_FAILEDWRITEDATA Failed to write data into recording file
DCAMERR_FAILEDREADDATA Failed to read data from recording file
DCAMERR_NOWRECORDING Device is now recording
DCAMERR_WRITEFULL There is no space to write to target
DCAMERR_ALREADYOCCUPIED Recording file is already attached to different HDCAM
DCAMERR_TOOLARGEUSERDATASIZE Specified user data size is too large
DCAMERR_INVALIDWAITHANDLE Invalid wait handle
DCAMERR_NEWRUNTIMEREQUIRED DCAM module version is older than the version that the camera requests
DCAMERR_VERSIONMISMATCH camera returns the error on setting parameter to limit version
DCAMERR_RUNAS_FACTORYMODE Camera runs as factory mode. Camera may need to be rewritten with firmware.
DCAMERR_IMAGE_UNKNOWNSIGNATURE signature of image header is unknown or corrupted
DCAMERR_IMAGE_NEWRUNTIMEREQUIRED version of image header is newer than version that used DCAM supports
DCAMERR_IMAGE_ERRORSTATUSEXIST image header stands error status
DCAMERR_IMAGE_HEADERCORRUPTED image header value is strange
DCAMERR_IMAGE_BROKENCONTENT image content is corrupted
DCAMERR_UNKNOWNMSGID unknown message id
DCAMERR_UNKNOWNSTRID unknown string id
DCAMERR_UNKNOWNPARAMID unknown parameter id
DCAMERR_UNKNOWNBITSTYPE unknown bitmap bits type
DCAMERR_UNKNOWNDATATYPE unknown frame data type
DCAMERR_NONE no error
DCAMERR_INSTALLATIONINPROGRESS installation in progress
DCAMERR_UNREACH internal error
DCAMERR_UNLOADED calling after process terminated
DCAMERR_NOCONNECTION HDCAM lost connection to device
DCAMERR_NOTIMPLEMENT not yet implemented
DCAMERR_DELAYEDFRAME Specified frame fails in real-time transfer. this frame is retransferred after stopping acquisition.
DCAMERR_FAILRELOADFRAME Failed to reload frame from hardware buffer with device buffer mode.
DCAMERR_CANCELRELOADFRAME Canceled to reload frame from hardware buffer with device buffer mode.
DCAMERR_DEVICEINITIALIZING Device is in the process of being initialized.
DCAMERR_APIINIT_INITOPTIONBYTES DCAMAPI_INIT::initoptionbytes is wrong
DCAMERR_APIINIT_INITOPTION DCAMAPI_INIT::initoption is wrong
DCAMERR_INITOPTION_COLLISION_BASE Between DCAMERR_INITOPTION_COLLISION_BASE and DCAMERR_INITOPTION_COLLISION_MAX means there is collision with initoption in DCAMAPI_INIT. The value "(error code) - DCAMERR_INITOPTION_COLLISION_BASE" indicates the index which second INITOPTION group happens.
DCAMERR_INITOPTION_COLLISION_MAX Reserved for indication INITOPTION collision.
DCAMERR_MISSPROP_TRIGGERSOURCE Need to set internal or syncreadout as trigger mode on using device memory.
DCAMERR_SUCCESS no error, general success code, app should check the value is positive.


DCAM_IDSTR
DCAM_IDSTR_BUS BUS information.
DCAM_IDSTR_CAMERAID Camera ID. This will be the serial number if it can be retrieved from the device. If not, it will be a bus specific string, e.g. "COM1". In this case, this device is connected to COM1.
DCAM_IDSTR_VENDOR Camera Manufacturer. This is always "Hamamatsu"
DCAM_IDSTR_MODEL Camera Model Name. The model number of the device, e.g. "C11440-22C". Some device may have additional options. Those options are described in this string after "with".
DCAM_IDSTR_CAMERAVERSION Camera version. This value will represent the version of the firmware and/or hardware.
DCAM_IDSTR_DRIVERVERSION Driver Version. This is the version of the lower level driver which DCAM is using for this device. This value can represent the kernel driver and/or shared library.
DCAM_IDSTR_MODULEVERSION Module Version. This is the version of the DCAM module.
DCAM_IDSTR_DCAMAPIVERSION DCAM-API Version. This is the version of DCAM-API specification. For example, if this is "4.0", it means the device can run with DCAM-API v4.0 specification.
DCAM_IDSTR_CAMERA_SERIESNAME Camera Series Name or Nickname. When camera doesn't have, error or model name is returned.


DCAM_IDSTR_OPTICALBLOCK
DCAM_IDSTR_OPTICALBLOCK_MODEL Optical block model name
DCAM_IDSTR_OPTICALBLOCK_ID Optical block serial number
DCAM_IDSTR_OPTICALBLOCK_DESCRIPTION Description of optical block
DCAM_IDSTR_OPTICALBLOCK_CHANNEL_1 Description of optical block channel 1.
DCAM_IDSTR_OPTICALBLOCK_CHANNEL_2 Description of optical block channel 2.


DCAMAPI_INITOPTION
DCAMAPI_INITOPTION_APIVER__LATEST Initialize as DCAM latest version.
DCAMAPI_INITOPTION_APIVER__4_0 Initialize as DCAM version 4.0.
DCAMAPI_INITOPTION_MULTIVIEW__DISABLE Individualize two cameras support multiview
DCAMAPI_INITOPTION_ENDMARK Set the last of the initoption array


DCAMCAP_STATUS
DCAMCAP_STATUS_BUSY Device is now capturing.
DCAMCAP_STATUS_READY Device is not capturing, but ready to start capturing.
DCAMCAP_STATUS_STABLE Device is not prepared for capturing.
DCAMCAP_STATUS_UNSTABLE Device is not fixed capture mode.


DCAM_PIXELTYPE
DCAM_PIXELTYPE_MONO8 One pixel consists of one byte. Value is unsigned 8 bit and range is from 0 to 255.
DCAM_PIXELTYPE_MONO12 Two pixel consists of three byte. Value is unsigned 12 bit and range is from 0 to 4045. Two pixel is packed, so pixel align is 3 byte by 2 pixel horizontally. The bit array of packed data is the following table.
DCAM_PIXELTYPE_MONO12P Two pixel consists of three byte. Value is unsigned 12 bit and range is from 0 to 4045. Two pixel is packed, so pixel align is 3 byte by 2 pixel horizontally. The bit array of packed data is the following table.
DCAM_PIXELTYPE_MONO16 One pixel consists of two byte. Value is unsigned 16 bit and range is from 0 to 65535. Some device output is less than 16 bit data, but pixel align is 2 byte horizontally.
DCAM_PIXELTYPE_RGB24 One pixel consists of three byte. Color order is red, green, and blue; and each color value is unsigned 8 bit.
DCAM_PIXELTYPE_RGB48 One pixel consists of six byte. Color order is red, green, and blue; and each color value is unsigned 16 bit. Some device output is less than 16 bit data, but pixel align is 2 byte horizontally.
DCAM_PIXELTYPE_BGR24 One pixel consists of three byte. Color order is blue, green, and red; and each color value is unsigned 8 bit.
DCAM_PIXELTYPE_BGR48 One pixel consists of six byte. Color order is blue, green, and red; and each color value is unsigned 16 bit. Some device output is less than 16 bit data, but pixel align is 2 byte horizontally.

MONO12 Packed Format
This is output data format of DCAM_PIXELTYPE_MONO12. P is the pixel transmitted by the camera. B is the byte in buffer received data.
Buffer Pixel Data
B[0] P[0] bits 11 ... 4
B[1] P[1] bits 3 ... 0 | P[0] bits 3 ... 0
B[2] P[1] bits 11 ... 4
... ...
B[m-2] P[n-1] bits 11 ... 4
B[m-1] P[n] bits 3 ... 0 | [n-1] bits 3 ... 0
B[m] P[n] bits 11 ... 4

MONO12P Packed Format
This is output data format of DCAM_PIXELTYPE_MONO12P. P is the pixel transmitted by the camera. B is the byte in buffer received data.
Buffer Pixel Data
B[0] P[0] bits 7 ... 0
B[1] P[1] bits 3 ... 0 | P[0] bits 11 ... 8
B[2] P[1] bits 11 ... 4
... ...
B[m-2] P[n-1] bits 7 ... 0
B[m-1] P[n] bits 3 ... 0 | [n-1] bits 11 ... 8
B[m] P[n] bits 11 ... 4


DCAMDEV_CAPDOMAIN
DCAMDEV_CAPDOMAIN__FUNCTION Check capability of FUNCTION
DCAMDEV_CAPDOMAIN__DCAMDATA Check capability of DCAMDATA
DCAMDEV_CAPDOMAIN__FRAMEOPTION Check capability of FRAMEOPTION


DCAMDEV_CAPFLAG
DCAMDEV_CAPFLAG_FRAMESTAMP Image data has Frame Stamp.
DCAMDEV_CAPFLAG_TIMESTAMP Image data has Time Stamp.
DCAMDEV_CAPFLAG_CAMERASTAMP Image data has Camera Stamp.


DCAMDATA_OPTION
DCAMDATA_OPTION__VIEW_ALL Set or get data to all view.
DCAMDATA_OPTION__VIEW_1 Set or get data to View1
DCAMDATA_OPTION__VIEW_2 Set or get data to View2
DCAMDATA_OPTION__VIEW_3 Set or get data to View3
DCAMDATA_OPTION__VIEW_4 Set or get data to View4


DCAMDATA_KIND
DCAMDATA_KIND__REGION DCAMDATA kind is Region.
DCAMDATA_KIND__LUT DCAMDATA kind is LUT.


DCAMDATA_REGIONTYPE
DCAMDATA_REGIONTYPE__BYTEMASK Data type to set Region is Byte Mask
DCAMDATA_REGIONTYPE__RECT16ARRAY Data type to set Region is the array of DCAMDATA_REGIONRECT.
DCAMDATA_REGIONTYPE__ACCESSREADY It is possible to set Region on Ready status
DCAMDATA_REGIONTYPE__ACCESSBUSY It is possible to set Region on Busy status


DCAMDATA_LUTTYPE
DCAMDATA_LUTTYPE__SEGMENTED_LINEAR Data type to set LUT is the array of DCAMDATA_LINEARLUT.
DCAMDATA_LUTTYPE__MONO16 Data type to set LUT is the array of unsigned short.
DCAMDATA_LUTTYPE__ACCESSREADY It is possible to set LUT on Ready status
DCAMDATA_LUTTYPE__ACCESSBUSY It is possible to set LUT on Busy status


DCAMWAIT_EVENT
DCAMWAIT_CAPEVENT_TRANSFERRED DCAM module received data from device, but the data is not ready to be accessed yet
DCAMWAIT_CAPEVENT_FRAMEREADY Image data ready to be accessed from host software
DCAMWAIT_CAPEVENT_CYCLEEND A capturing cycle is finished. Cycle is defined by how many frames were prepared for the buffer. Once they are filled, this event occurs.
DCAMWAIT_CAPEVENT_EXPOSUREEND Device finished exposure of a frame
DCAMWAIT_CAPEVENT_STOPPED Capturing has stopped
DCAMWAIT_CAPEVENT_RELOADFRAME DCAM module received retransferred frame on using device memory, and image data readys to be accessd from host software.
DCAMWAIT_RECEVENT_STOPPED Recording is finished
DCAMWAIT_RECEVENT_WARNING Recording speed is slow and there is a danger of missing frames
DCAMWAIT_RECEVENT_MISSED Some frames have been missed
DCAMWAIT_RECEVENT_DISKFULL Target disk is full and recording cannot continue
DCAMWAIT_RECEVENT_WRITEFAULT There was writing error
DCAMWAIT_RECEVENT_SKIPPED Image data is corrupted, so it is skipped to record.


DCAMBUF_ATTACHKIND
DCAMBUF_ATTACHKIND_FRAME Attach pointer array of user buffer to copy image
DCAMBUF_ATTACHKIND_TIMESTAMP Attach pointer array of user buffer to copy timestamp
DCAMBUF_ATTACHKIND_FRAMESTAMP Attach pointer array of user buffer to copy framestamp
DCAMBUF_ATTACHKIND_PRIMARY_TIMESTAMP Attach user buffer to copy timestamp
DCAMBUF_ATTACHKIND_PRIMARY_FRAMESTAMP Attach user buffer to copy framestamp


DCAMBUF_FRAME_OPTION
DCAMBUF_FRAME_OPTION__VIEW_ALL Return image data of all view
DCAMBUF_FRAME_OPTION__VIEW_1 Return image data of view1
DCAMBUF_FRAME_OPTION__VIEW_2 Return image data of view2
DCAMBUF_FRAME_OPTION__VIEW_3 Return image data of view3
DCAMBUF_FRAME_OPTION__VIEW_4 Return image data of view4
DCAMBUF_FRAME_OPTION__PROC_HIGHCONTRAST Return image data processed High Contrast


DCAMBUF_METADATAOPTION
DCAMBUF_METADATAOPTION__VIEW_ALL Return same metadata as DCAMBUF_FRAME
DCAMBUF_METADATAOPTION__VIEW_1 Return metadata of view1
DCAMBUF_METADATAOPTION__VIEW_2 Return metadata of view2
DCAMBUF_METADATAOPTION__VIEW_3 Return metadata of view3
DCAMBUF_METADATAOPTION__VIEW_4 Return metadata of view4


DCAMBUF_PROCTYPE
DCAMBUF_PROCTYPE__HIGHCONTRASTMODE flag of High Contrast processing in DCAMDEV_CAPABILITY_FRAMEOPTION


DCAMREC_STATUSFLAG
DCAMREC_STATUSFLAG_RECORDING On recording


DCAMREC_FRAME_OPTION
DCAMREC_FRAME_OPTION__VIEW_CURRENT Retrurn image data of current view
DCAMREC_FRAME_OPTION__VIEW_1 Retrurn image data of view1
DCAMREC_FRAME_OPTION__VIEW_2 Retrurn image data of view2
DCAMREC_FRAME_OPTION__VIEW_3 Retrurn image data of view3
DCAMREC_FRAME_OPTION__VIEW_4 Retrurn image data of view4
DCAMREC_FRAME_OPTION__PROC_HIGHCONTRAST Retrurn image data processed High Contrast


DCAMREC_METADATAOPTION
DCAMREC_METADATAOPTION__LOCATION_FRAME meta data associated to each frame
DCAMREC_METADATAOPTION__LOCATION_SESSION meta data associated to each session
DCAMREC_METADATAOPTION__LOCATION_FILE meta data associated to file


DCAMBUF_METADATAKIND
DCAMBUF_METADATAKIND_TIMESTAMPS captured timing
DCAMBUF_METADATAKIND_FRAMESTAMPS frame index


DCAMREC_METADATAKIND
DCAMREC_METADATAKIND_USERDATATEXT Readable user meta data. This supports text strings with encoding format UTF8.
DCAMREC_METADATAKIND_USERDATABIN Any type of user meta data. The host software can use with user defined format.
DCAMREC_METADATAKIND_TIMESTAMPS captured timing
DCAMREC_METADATAKIND_FRAMESTAMPS frame index


DCAM_CODEPAGE
DCAM_CODEPAGE__SHIFT_JIS Shift JIS
DCAM_CODEPAGE__UTF16_LE UTF-16 (Little Endian)
DCAM_CODEPAGE__UTF16_BE UTF-16 (Big Endian)
DCAM_CODEPAGE__UTF7 UTF-7 translation
DCAM_CODEPAGE__UTF8 UTF-8 translation


DCAMCAP_TRANSFERKIND
DCAMCAP_TRANSFERKIND_FRAME Return count and latest index of frame


DCAMCAP_START
DCAMCAP_START_SEQUENCE continuously capturing images. If the last buffer frame has been used, the next image will be copied to the first buffer frame.
DCAMCAP_START_SNAP captures images until the buffer is filled completely then it will stop.

Go to top of this chapter


Functions


Initialize, uninitialize and misc.

dcamapi_init()

Declaration
DCAMERR dcamapi_init(
DCAMAPI_INIT* param
);

Parameter
param
the pointer to the DCAMAPI_INIT structure which specifies initialization options and receives the number of connected devices

Remarks
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.

dcamapi_uninit()

Declaration
DCAMERR dcamapi_uninit(void);

Remarks
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.

dcamdev_open()

Declaration
DCAMERR dcamdev_open(
DCAMDEV_OPEN* param
);

Parameter
param
the pointer to the DCAMDEV_OPEN structure which specifies the device index to be opened and receives the HDCAM handle of the device

Remarks
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.

dcamdev_close()

Declaration
DCAMERR dcamdev_close(
HDCAM h
);

Parameter
h
the HDCAM handle of the device

Remarks
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.


Device Data

dcamdev_getcapbility()

Declaration
DCAMERR dcamdev_getcapbility(
HDCAM h,
DCAMDEV_CAPABILITY* param
);

Parameter
h
the HDCAM handle of the device
param
the instance of DCAMDEV_CAPABILITY structure which can receive information of supported function.

Remarks
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.

dcamdev_getstring()

Declaration
DCAMERR dcamdev_getstring(
HDCAM h,
DCAMDEV_STRING* param
);

Parameter
h
the HDCAM handle or camera index of the device
param
the pointer to the DCAMDEV_STRING structure which specifies the string index and receives device information

Remarks
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.

dcamdev_setdata()

Declaration
DCAMERR dcamdev_setdata(
HDCAM h,
DCAMDATA_HDR* param
);

Parameter
h
the HDCAM handle of the device
param
the pointer of the DCAMDATA_HDR structure

Remarks
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.

dcamdev_getdata()

Declaration
DCAMERR dcamdev_getdata(
HDCAM h,
DCAMDATA_HDR* param
);

Parameter
h
the HDCAM handle of the device
param
the pointer of the DCAMDATA_HDR structure

Remarks
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.


Property control

dcamprop_getattr()

Declaration
DCAMERR dcamprop_getattr(
HDCAM h,
DCAMPROP_ATTR* param
);

Parameter
h
the HDCAM handle of the device
param
the instance of the DCAMPROP_ATTR structure which can receive information of property specified by property id

Remarks
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.

dcamprop_getvalue()

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

Parameter
h
the HDCAM handle of the device
iProp
the property ID
pValue
the pointer of a double variable that will receive the current value of the property specified by iProp

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

dcamprop_setvalue()

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

Parameter
h
the HDCAM handle of the device
iProp
the property ID
fValue
the value to set to the property

Remarks
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.

dcamprop_setgetvalue()

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

Parameter
h
the HDCAM handle of the device
iProp
the property ID
pValue
the pointer to a value to set to the property and to receive the new value
option
this value is reserved as options for setting property value, set to 0

Remarks
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.

dcamprop_queryvalue()

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

Parameter
h
the HDCAM handle of the device
iProp
the property ID
pValue
the pointer to a value to query from the property and to receive the new value
option
Option to request the kind of value. This parameter can be one of following values;
DCAMPROP_OPTION_NONE return value is the actual set value for the device when host software calls dcamprop_setvalue()
DCAMPROP_OPTION_PRIOR return value is the prior value
DCAMPROP_OPTION_NEXT return value is the next value

Remarks
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.

dcamprop_getnextid()

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

Parameter
h
the HDCAM handle of the device
pProp
the pointer to a property ID which will also receive the next property ID
option
Option for getting next property id. This parameter can be one of the following values
DCAMPROP_OPTION_SUPPORT content of pProp will be the ID of the next property that the device supports
DCAMPROP_OPTION_UPDATED content of pProp will be the ID of the next property which the value or mode has been changed. An internal flag is set when the property value has been updated allowing the property to be found by the method. But this flag is reset when the property is found by this method.
DCAMPROP_OPTION_VOLATILE content of iProp will be the ID of the next property which the value or mode which can be changed unexpectedly by user manually or by the device automatically. All of these properties have the VOLATILE attribute.
DCAMPROP_OPTION_ARRAYELEMENT content of iProp will be the ID of next array element property. If the input iProp is not of an array, this function returns DCAMERR_NOPROPERTY.

Remarks
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.

dcamprop_getname()

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

Parameter
h
the HDCAM handle of the device
iProp
the property ID
text
the pointer of a buffer to receive the property name
textbytes
the size of the buffer that will receive the property name

Remarks
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.

dcamprop_getvaluetext()

Declaration
DCAMERR dcamprop_getvaluetext(
HDCAM h,
DCAMPROP_VALUETEXT* param
);

Parameter
h
the HDCAM handle of the device
param
the instance of the DCAMPROP_VALUETEXT structure which receives the property value text of specified by property and value

Remarks
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.


Buffer control

dcambuf_alloc()

Declaration
DCAMERR dcambuf_alloc(
HDCAM h,
int32 framecount
);

Parameter
h
the HDCAM handle of the device
framecount
the number of frames DCAM will allocate

Remarks
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.

dcambuf_attach()

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

Parameter
h
the HDCAM handle of the device
param
a pointer to the DCAMBUF_ATTACH structure which provides user buffer information

Remarks
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.

dcambuf_release()

Declaration
DCAMERR dcambuf_release(
HDCAM h,
int32 iKind
);

Parameter
h
the HDCAM handle of the device
iKind
the type of buffer to be released

Remarks
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.

dcambuf_lockframe()

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

Parameter
h
the HDCAM handle of the device
pFrame
the pointer to the DCAMBUF_FRAME structure which specifies the frame to be locked and to receive a pointer to the image data

Remarks
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.

dcambuf_copyframe()

Declaration
DCAMERR dcambuf_copyframe(
HDCAM h,
DCAMBUF_FRAME* pFrame
);

Parameter
h
the HDCAM handle of the device
pFrame
the pointer to the DCAMBUF_FRAME structure which specifies the frame to be copied and the destination buffer

Remarks
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.

dcambuf_copymetadata()

Declaration
DCAMERR dcambuf_copymetadata(
HDCAM h,
DCAM_METADATAHDR* hdr
);

Parameter
h
the HDCAM handle of the device
hdr
a pointer to the DCAM_METADATAHDR structure

Remarks
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.


Capturing control

dcamcap_start()

Declaration
DCAMERR dcamcap_start(
HDCAM h,
int32 mode
);

Parameter
h
the HDCAM handle of the device
mode
the capturing mode

Remarks
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.

dcamcap_stop()

Declaration
DCAMERR dcamcap_stop(
HDCAM h
);

Parameter
h
the HDCAM handle of the device

Remarks
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.

dcamcap_status()

Declaration
DCAMERR dcamcap_status(
HDCAM h,
int32* pStatus
);

Parameter
h
the HDCAM handle of the device
pStatus
the pointer that receives DCAMCAP_STATUS as the current capturing status.

Remarks
The dcamcap_status() function returns current capturing status.

dcamcap_transferinfo()

Declaration
DCAMERR dcamcap_transferinfo(
HDCAM h,
DCAMCAP_TRANSFERINFO* param
);

Parameter
h
the HDCAM handle of the device
param
the pointer of the DCAMCAP_TRANSFERINFO structure which receives the current transfer status

Remarks
The dcamcap_transferinfo() function returns current image transfer status.

dcamcap_firetrigger()

Declaration
DCAMERR dcamcap_firetrigger(
HDCAM h,
int32 iKind
);

Parameter
h
the HDCAM handle of the device
iKind
This value is reserved as option which specifies which type of software trigger to be fired. Set to 0.

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

dcamcap_record()

Declaration
DCAMERR dcamcap_record(
HDCAM h,
HDCAMREC hrec
);

Parameter
h
the HDCAM handle of the device
hrec
the HDCAMREC handle of the recording file

Remarks
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.


Waiting event control

dcamwait_open()

Declaration
DCAMERR dcamwait_open(
DCAMWAIT_OPEN* param
);

Parameter
param
the pointer of the DCAMWAIT_OPEN structure which specifies the HDCAM handle and acquires the HDCAMWAIT handle.

Remarks
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.

dcamwait_close()

Declaration
DCAMERR dcamwait_close(
HDCAMWAIT h
);

Parameter
h
the HDCAMWAIT handle

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

dcamwait_start()

Declaration
DCAMERR dcamwait_start(
HDCAMWAIT h,
DCAMWAIT_START* param
);

Parameter
h
the HDCAMWAIT handle
param
the pointer of the DCAMWAIT_START structure which specifies the event the host software will wait for

Remarks
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.

dcamwait_abort()

Declaration
DCAMERR dcamwait_abort(
HDCAMWAIT h
);

Parameter
h
the HDCAMWAIT handle

Remarks
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.


Recording control

dcamrec_open()

Declaration
DCAMERR dcamrec_open(
DCAMREC_OPEN* param
);

Parameter
param
the pointer of the DCAMREC_OPEN structure which specifies the recording file and to acquire the HDCAMREC handle

Remarks
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.

dcamrec_close()

Declaration
DCAMERR dcamrec_close(
HDCAMREC hrec
);

Parameter
hrec
the HDCAMREC handle of the recording file

Remarks
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.

dcamrec_lockframe()

Declaration
DCAMERR dcamrec_lockframe(
HDCAMREC hrec,
DCAMREC_FRAME* pFrame
);

Parameter
hrec
the HDCAMREC handle of the recording file
pFrame
the pointer to the DCAMREC_FRAME structure which retrieves the locked frame buffer information

Remarks
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.

dcamrec_copyframe()

Declaration
DCAMERR dcamrec_copyframe(
HDCAMREC hrec,
DCAMREC_FRAME* pFrame
);

Parameter
hrec
the HDCAMREC handle of the recording file
pFrame
the pointer to the DCAMREC_FRAME structure which receives the image data

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

dcamrec_writemetadata()

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

Parameter
hrec
the HDCAMREC handle of the recording file
hdr
the pointer to the DCAM_METADATAHDR structure which provides the source data for writing

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

dcamrec_lockmetadata()

Declaration
DCAMERR dcamrec_lockmetadata(
HDCAMREC hrec,
DCAM_METADATAHDR* hdr
);

Parameter
hrec
the HDCAMREC handle of the recording file
hdr
the pointer to the DCAM_METADATAHDR structure which retrieves locked meta data

Remarks
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.

dcamrec_copymetadata()

Declaration
DCAMERR dcamrec_copymetadata(
HDCAMREC hrec,
DCAM_METADATAHDR* hdr
);

Parameter
hrec
the HDCAMREC handle of the recording file
hdr
the pointer to the DCAM_METADATAHDR structure which retrieves locked meta data

Remarks
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.

dcamrec_lockmetadatablock()

Declaration
DCAMERR dcamrec_lockmetadatablock(
HDCAMREC hrec,
DCAM_METADATABLOCKHDR* hdr
);

Parameter
hrec
the HDCAMREC handle of the recording file
hdr
the pointer to the DCAM_METADATAHDR structure which retrieves a locked meta data block

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

dcamrec_copymetadatablock()

Declaration
DCAMERR dcamrec_copymetadatablock(
HDCAMREC hrec,
DCAM_METADATABLOCKHDR* hdr
);

Parameter
hrec
the HDCAMREC handle of the recording file
hdr
the pointer to the DCAM_METADATAHDR structure which retrieves a locked meta data block

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

dcamrec_pause()

Declaration
DCAMERR dcamrec_pause(
HDCAMREC hrec
);

Parameter
hrec
the HDCAMREC handle of the recording file

Remarks
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.

dcamrec_resume()

Declaration
DCAMERR dcamrec_resume(
HDCAMREC hrec
);

Parameter
hrec
the HDCAMREC handle of the recording file

Remarks
The dcamrec_resume() function resumes the disk recording.

dcamrec_status()

Declaration
DCAMERR dcamrec_status(
HDCAMREC hrec,
DCAMREC_STATUS* pStatus
);

Parameter
hrec
the HDCAMREC handle of the recording file
pStatus
the pointer to the DCAMREC_STATUS structure which retrieves the recording status

Remarks
The dcamrec_status() function gets the current recording status.

Go to top of this chapter


Structures



DCAM_GUID

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

Remarks
The structure for DCAMAPI_INIT::guid member. This is used only for special conditions.


DCAMAPI_INIT

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
};

size
Set to the byte size of the DCAMAPI_INIT structure.
iDeviceCount
After calling dcamapi_init(), this will return with the number of recognized devices .
reserved
This member is reserved. Set to 0.
initoptionbytes
Set the byte size of initoption which specifies the DCAMAPI_INITOPTION array. Set to 0 if the host software does not use DCAMAPI_INITOPTION.
initoption
Set to the pointer of the DCAMAPI_INITOPTION array or NULL if the host software does not use DCAMAPI_INITOPTION.
guid
Under special conditions, set to the pointer of the DCAM_GUID structure. Otherwise set to NULL.

Remarks
This structure is used as an argument when calling the dcamapi_init() function. The host software can specify initialize options for DCAM-API and can get the number of recognized devices.


DCAMDEV_OPEN

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

size
Set to the byte size of the DCAMDEV_OPEN structure.
index
Set to the index of the device to open. The index is 0 based therefore this value must be greater than or equal to 0 and less than the number of devices returned by DCAMAPI_INIT::iDeviceCount.
hdcam
After calling dcamdev_open(), this will return with the device handle.

DCAMDEV_CAPABILITY

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

size
Set the size of whole structure. When this is included in another structure, this value is the size of the structure.
domain
Set DCAMDEV_CAPDOMAIN to get the capability of target function
capflag
This will return the supported flag. It is necessary to set the detail of "domain" by "kind".
kind
Set the kind of data of function set by "domain".

DCAMDEV_CAPABILITY_LUT

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
};

hdr
Set DCAMDEV_CAPDOMAIN__DCAMDATA to "domain" and DCAMDATA_KIND__LUT to "kind". This will return the supported DCAMDATA_LUTTYPE to capflag. The attribute flag can change by other setting.
linearpointmax
This will return the maximum count of point for linear LUT.

DCAMDEV_CAPABILITY_REGION

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
};

hdr
Set DCAMDEV_CAPDOMAIN__DCAMDATA to "domain" and DCAMDATA_KIND__REGION to "kind". This will return the supported DCAMDATA_REGIONTYPE to capflag.
horzunit
This will return the horizontal step that the camera can extract. When set data doesn't fit to step, DCAM spreads the region with step.
vertunit
This will return the vertical step that the camera can extract. When set data doesn't fit to step, DCAM spreads the region with step.

DCAMDEV_CAPABILITY_FRAMEOPTION

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

hdr
Set DCAMDEV_CAPDOMAIN__FRAMEOPTION to "domain". This will return the available DCAMBUF_PROCTYPE to capflag in current condition.
supportproc
This will return the supported DCAMBUF_PROCTYPE. Some function has the condition to work, so it is necessary to check whether the function is available with hdr.capflag in current condition.

DCAMDEV_STRING

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

size
Set to the byte size of the DCAMDEV_STRING structure.
iString
Set the DCAM_IDSTR or DCAMERR of the requested text information.
text
Set the destination buffer pointer to receive the text information.
textbytes
Set the byte size of the destination buffer that will receive text information.

DCAMDATA_HDR

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

size
Set this to the byte size of the structure that has included this DCAMDATA_HDR structure.
iKind
Set the DCAMDATA_KIND
option
Set the DCAMDATA_OPTION
reserved2
This member is reserved. Set to 0.

DCAMDATA_REGION

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
};

hdr
iKind should be DCAMDATA_KIND_REGION.
option
This member is reserved. Set to 0.
type
Set data format of region
data
Set pointer of data. This data type is set DCAMDATA_REGIONTYPE.
datasize
Set data size
reserved
This member is reserved. Set to 0.

DCAMDATA_REGIONRECT

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

left
Set horizontal position of left
top
Set vertical position of top
right
Set horizontal position of right
bottom
Set vertical position of bottom

DCAMDATA_LUT

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
};

hdr
iKind should be DCAMDATA_KIND_LUT.
type
Set data format of LUT
page
Set page to load or store
data
Set pointer of data. This data type is set DCAMDATA_LUTTYPE
datasize
Set data size
reserved
This member is reserved. Set to 0.

DCAMDATA_LINEARLUT

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

lutin
Set value of input data on segment point
lutout
Set value of output data on segment point

DCAMPROP_ATTR

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
};

cbSize
Set to the byte size of the DCAMPROP_ATTR structure.
iProp
Set to the specified ID of the property.
option
This member is reserved. Set to 0.
iReserved1
This member is reserved. Set to 0.
attribute
Returns the attributes of the property by a bit field specified in enum DCAMPROPATTRIBUTE.
iGroup
This member is reserved. Set to 0.
iUnit
Returns the DCAMPROPUNIT value of the property.
attribute2
Returns the attribute of the property by bit field specified in enum DCAMPROPATTRIBUTE2.
valuemin
Returns the minimum valid value of the property.
valuemax
Returns the maximum valid value of the property.
valuestep
Returns the minimum stepping between two contiguous valid values.
valuedefault
Returns the default value of the property.
nMaxChannel
Returns the maximum channel index of the property.
nMaxView
Returns the maximum view index of the property.
iProp_NumberOfElement
Returns property id to get the number of the array elements of the property.
iProp_ArrayBase
Returns the first property id of the array elements.
iPropStep_Element
If the property is in an array, this value indicates the gap of property id to the next element or previous.

DCAMPROP_VALUETEXT

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
};

cbSize
Set to the byte size of the DCAMPROP_VALUETEXT structure.
iProp
Set to the property ID.
value
Set to the value of the property.
text
Set to the destination buffer pointer that will receive the text information.
textbytes
Set to the byte size of the destination buffer.

DCAMBUF_ATTACH

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"
};

size
Set to the byte size of the DCAMBUF_ATTACH structure.
iKind
Set to the kind of attached buffers.
buffer
Set to the array of pointers of attached buffers.
buffercount
Set to the number of attached buffers.

DCAM_TIMESTAMP

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

sec
Indicates seconds based on January 1 1970.
microsec
Indicates micro-seconds based on January 1 1970.

DCAMBUF_FRAME

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
};

size
Set to the byte size of the DCAMBUF_FRAME structure.
iFrame
Set to the index of the image buffer. This can also be set to -1 to retrieve the latest captured image.
buf
For dcambuf_lockframe(), this will return with the address to the image data. For dcambuf_copyframe(), set this to the pointer of the destination buffer for the image to be copied to.
rowbytes
For dcambuf_lockframe(), this will return the byte size offset value between the start of two lines. For dcambuf_copyframe(), set this to the byte size offset value between the start of two lines. This value can be negative if destination image is up-side-down.
type
For dcambuf_lockframe(), this will return the DCAM_PIXELTYPE value of image. For dcambuf_copyframe(), set this to 0.
width
For dcambuf_lockframe(), this will return the number of horizontal pixels of the image. For dcambuf_copyframe(), set this to the number of horizontal pixels for copying the image.
height
For dcambuf_lockframe(), this will return the number of vertical pixels of an image buffer. For dcambuf_copyframe(), set this to the number of vertical pixels for copying the image.
left
For dcambuf_lockframe(), set this to 0. For dcambuf_copyframe(), set this to the left offset of the source image.
top
For dcambuf_lockframe(), set this to 0. For dcambuf_copyframe(), set this to the top offset of the source image.
timestamp
This returns the time stamp of specified frame.
framestamp
This returns the frame stamp of specified frame.
camerastamp
This returns the camera stamp of HDCAM device.

DCAMREC_FRAME

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
};

size
Set byte size of DCAMREC_FRAME structure.
iFrame
Set to the index of the image buffer. This can also be set to -1 to retrieve the latest captured image.
buf
For dcamrec_lockframe(), this will return with the address to the image data. For dcamrec_copyframe(), set this to the pointer of the destination buffer for the image to be copied to.
rowbytes
For dcamrec_lockframe(), this will return the byte size offset value between the start of two lines. For dcamrec_copyframe(), set this to the byte size offset value between the start of two lines. This value can be negative if the destination image is upside down.
width
For dcamrec_lockframe(), this will return the number of horizontal pixels of the image. For dcamrec_copyframe(), set this to the number of horizontal pixels to be copied.
height
For dcamrec_lockframe(), this will return the number of vertical pixels of the image. For dcamrec_copyframe(), set this to the number of lines to be copied.
left
For dcamrec_lockframe(), this member is reserved. Set it to 0. For dcamrec_copyframe(), set this to the left offset of the source image.
top
For dcamrec_lockframe(), this member is reserved. Set it to 0. For dcamrec_copyframe(), set this to the top offset of the source image.
timestamp
This returns the time stamp of specified frame.
framestamp
This returns the frame stamp of specified frame.
camerastamp
This returns the camera stamp of HDCAM device.

DCAMWAIT_OPEN

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
};

size
Set this to the byte size of the DCAMWAIT_OPEN structure.
supportevent
This will return the supported DCAMWAIT_EVENTs.
hwait
This will return the HDCAMWAIT handle to be used by other dcamwait functions.
hdcam
Set to the HDCAM handle of the target device.

DCAMWAIT_START

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

size
Set this to the byte size of the DCAMWAIT_START structure.
eventhappened
This will return the event that occurred.
eventmask
Set this to the events to wait for.
timeout
Set this to the timeout in milliseconds.

DCAMCAP_TRANSFERINFO

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

size
Set this to the byte size of the DCAMCAP_TRANSFERINFO structure.
nNewestFrameIndex
This will return the index of the last captured frame.
nFrameCount
This will return the number of captured frames.

DCAMREC_OPEN

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
};

size
Set this to the byte size of the DCAMREC_OPEN structure.
hrec
This will return the HDCAMREC handle that can be used by other dcamrec functions.
path
Set this to the destination path without the extension.
ext
Set this to the extension for the destination file.
maxframepersession
Set this to the maximum number of the frames in a session.
userdatasize
Set this to the maximum bytes of binary user meta data for each frame.
userdatasize_session
Set this to the maximum bytes of binary user meta data for each session.
userdatasize_file
Set this to the maximum bytes of binary user meta data for the file.
usertextsize
Set this to the maximum bytes of user text meta data for each frame.
usertextsize_session
Set this to the maximum bytes of user text meta data for each session.
usertextsize_file
Set this to the maximum bytes of user text meta data for the file.

DCAM_METADATAHDR

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
};

size
Set this to the byte size of the structure that has included this DCAM_METADATAHDR structure.
iKind
Set this to the kind of METADATA.
option
Set this for the option of the METADATA.
iFrame
If the target is a frame, set this to the index of the target frame.

DCAM_METADATABLOCKHDR

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
};

size
Set this to the byte size of the structure that has included this DCAM_METADATABLOCKHDR structure.
iKind
Set this to the kind of METADATA.
option
Set this to the option of the METADATA.
iFrame
Set this to the start index of target frame.
in_count
Set this to the number of requested metadata. 0 means the number of available metadata.
outcount
This will return the number of acquired metadata.

DCAM_USERDATATEXT

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
};

hdr
iKind should be DCAM_METADATAKIND_USERDATATEXT. option should be one of DCAMREC_METADATAOPTION.
text
Set text meta data.
text_len
Set the byte size of text data.
codepage
Text encoding ID should be set.

DCAM_USERDATABIN

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
};

hdr
iKind should be DCAM_METADATAKIND_USERDATABIN. option should be one of DCAMREC_METADATAOPTION.
bin
Set binary meta data.
bin_len
Set the byte size of binary data.

DCAM_TIMESTAMPBLOCK

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
};

hdr
iKind should be DCAM_METADATAKIND_TIMESTAMPS. option should be one of DCAMBUF_METADATAOPTION or DCAMREC_METADATAOPTION.
timestamps
dcamrec_lockmetadatablock() fills this with a pointer for array of DCAM_TIMESTAMP. dcamrec_copymetadatablock() requires this as a destination pointer for copying array of DCAM_TIMESTAMP.
timestampsize
Set size of DCAM_TIMESTAMP structure. This requires to keep backward compatibility when DCAM_TIMESTAMP structure is changed.
timestampvaildsize
Returns written byte size into each DCAM_TIMESTAMP structure. This requires to keep backward compatibility when DCAM_TIMESTAMP structure is changed.
timestampkind
Returns the kind of which hardware produces these timestamp.
reserved
This member is reserved.

DCAM_FRAMESTAMPBLOCK

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
};

hdr
iKind should be DCAM_METADATAKIND_FRAMESTAMPS. option should be one of DCAMBUF_METADATAOPTION or DCAMREC_METADATAOPTION.
framestamps
dcamrec_lockmetadatablock() fills this with a pointer for array of frame stamp. dcamrec_copymetadatablock() requires this as a destination pointer for copying array of frame stamp.

DCAM_METADATATEXTBLOCK

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
};

text
For dcamrec_copymetadatablock() function, host software has to set for setting text metadata.
For dcamrec_lockmetadatablock() function, return pointers for each text metadata.
textsizes
For dcamrec_copymetadatablock() function, host software can specify each text metadata length.
For dcamrec_lockmetadatablock() function, return pointers for each text metadata length.
bytesperunit
For dcamrec_copymetadatablock() function, host software has to set the size of buffer to receive text metadata. Each buffer has to have this size of buffer.
For dcamrec_lockmetadatablock() function, return the value of max bytes per unit which is set at DCAMREC_OPEN.
textcodepage
For dcamrec_copymetadatablock() function, host software has to set pointer of array to get each code page.
For dcamrec_lockmetadatablock() function, return codepages array pointer of each meta data text.

DCAM_METADATABINBLOCK

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
};

bin
For dcamrec_copymetadatablock() function, set this for setting binary metadata. For dcamrec_lockmetadatablock() function, this will return pointers for each binary metadata.
binsizes
For dcamrec_copymetadatablock() function, host software can specify each binary metadata length.
For dcamrec_lockmetadatablock() function, return pointers for each binary metadata length.
bytesperunit
For dcamrec_copymetadatablock() function, host software has to set the size of buffer to receive binary metadata. Each buffer has to have this size of buffer.
For dcamrec_lockmetadatablock() function, return the value of max bytes per unit which is set at DCAMREC_OPEN.

DCAMREC_STATUS

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
};

size
Set to the byte size of this structure.
currentsession_index
This will return index of current session.
maxframecount_per_session
This will return the maximum frame count in the session.
currentframe_index
This will return the index of the current frame in the current session.
missingframe_count
This will return the missing frame count in the current recording.
totalframecount
This will return the total frame count in the file.

Go to top of this chapter