v24.2.6764

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 DCIMG-SDK. Developer who uses DCIMG-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


DCIMG-API
DCIMG-API is an application software program interface to read files which are recorded by DCAM-API recording functions, hereafter referred to simply as “DCIMG file”). DCAM-API is application software program interface to control preparing digital cameras and detecting system manufactured by HAMAMATSU (hereafter referred to simply as “devices”). DCIMG-API is installed when DCAM-API is installed. DCAM-API itself is downloadable from website, www.dcamapi.com.


SDK
The DCIMG software development kit (hereafter referred to as the “SDK”) gives resource for making host software program by their developer.
The SDK consists of header files, library files, reference files of DCIMG-API functions, and source code of sample application software to give knowledge how to access DCIMG-API. SDK users are free to use the software in any way they like, such as partially modifying source codes and creating completely separate program, and also giving application software or plugin module for everyone. But followings are not allowed; opening the resources that get from HAMAMMATSU as SDK; making very thin wrapper module that is almost same as DCIMG-API itself.


Concept
Concept of DCIMG-API is to give easy access to DCIMG files. HPK does not open file format itself but gives API for accessing these files because DCIMG file format may be expanded when DCAM-API supports new function. So supporting by DCIMG-API is easier for developer than opening DCIMG file format. Basically functions are for reading file into PC memory, there is no function for displaying and 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"
HDCIMG
HDCIMG is the handle which specifies the target file on DCIMG-API. Almost DCIMG-API functions use this handle as a parameter. dcimg_open() function returns this handle to host software, and dcimg_close() function releases it at terminating using the device.


Related to "Functions"
Function name
All DCIMG-API functions are contained by small letters and they start by "dcimg_".

Function arguments
All function except dcimg_init() function and dcimg_open() function, the first arguments are always HDCIMG handle. Some functions need additional argument and if there are 3 parameters or more, structure is used. In case of structure parameter, function requires a pointer and the first member of the structure indicates a size of the structure. If you do not have any option for other members, please fill them with 0.

Function return
All function returns value of DCIMG_ERR. All values are defined with DCIMG_ERR_ prefix. If function successes DCIMG_ERR_SUCCESS is return value.

Frame, Session and File
The smallest content of DCIMG file is "Frame". Frame is 2D image. The series of contiguous capturing images is called as "Session". The first frame in session is beginning capturing or resuming recording. The last frame is the last before stopping capturing or pausing recording. DCIMG file can contain multiple session.

Go to top of this chapter


Calling sequence


Initialization and Termination, and HDCIMG handle
Initialization
At starting using DCIMG-API, host software needs to call dcimg_init() function first, then call dcimg_open() function to get HDCIMG handle.

Termination
To release HDCIMG handle at ending using the file, host software needs to call dcimg_close() function. There is no ending function for DCIMG-API itself.

HDCIMG handle
Almost DCIMG-API functions require a HDCIMG handle. The HDCIMG handle is used for specifying the DCIMG file that the host software controls and it is got by dcimg_open() function.


Access to image data and metadata
Lock image data
An easy way to access image data is calling dcimg_lockframe() function. First preparing instance of structure DCIMG_FRAME, second setting size member and iFrame member, then call this function to get the image information and point to access image data.

Copy image data
dcimg_copyframe() function is used to copy image data into user prepared buffer. Before calling this function, the host software has to fill necessary member of structure DCIMG_FRAME. The function dcimg_getparaml() is prepared to get some information, e.g. image size, pixeltype and so on.

Metadata
DCIMG file includes not only image data but also other data, which is called "metadata". The function dcimg_copymetadata() can return single metadata of a frame. The function dcimg_copymetadatablock() can return metadata across multiple frames.

Frame index
Frame index in DCIMG-API is 0 based. The index of first frame in a session is 0.


Additional access
Session
In DCIMG-API, from starting record to finishing is called session. DCIMG file can include multiple sessions. dcimg_setsessionindex() function can change current session by session index. dcimg_getsessionindex() function can return current session index. Session index is 0 base. The first session index is 0.

Parameter
dcimg_getparaml() function can return various parameter in DCIMG file. enum DCIMG_IDPARAML can specify which parameter host software wants to know.

Go to top of this chapter


Type Declarations



DCIMG_ERR
DCIMG_ERR_NOMEMORY not enough memory
DCIMG_ERR_INVALIDHANDLE invalid file handle
DCIMG_ERR_INVALIDPARAM invalid parameter
DCIMG_ERR_INVALIDVALUE invalid value
DCIMG_ERR_INVALIDVIEW invalid view index
DCIMG_ERR_INVALIDFRAMEINDEX invalid frame index
DCIMG_ERR_INVALIDSESSIONINDEX invalid session index
DCIMG_ERR_FILENOTOPENED failed to open file
DCIMG_ERR_UNKNOWNFILEFORMAT unknown file format
DCIMG_ERR_NOTSUPPORT not support the function or id with read file
DCIMG_ERR_FAILEDREADDATA failed to read data
DCIMG_ERR_UNKNOWNSIGN signature of file header is unknown or corrupted
DCIMG_ERR_OLDERFILEVERSION version of file header is older than version that used DCIMGAPI supports
DCIMG_ERR_NEWERFILEVERSION version of file header is newer than version that used DCIMGAPI supports
DCIMG_ERR_NOIMAGE no image
DCIMG_ERR_UNKNOWNIMAGEPROC unknown image process type
DCIMG_ERR_NOTSUPPORTIMAGEPROC not support set image process
DCIMG_ERR_NODATA target data isn't recorded.
DCIMG_ERR_IMAGE_UNKNOWNSIGNATURE signature of image header is unknown or corrupted
DCIMG_ERR_IMAGE_NEWRUNTIMEREQUIRED version of image header is newer than version that used DCIMGAPI supports
DCIMG_ERR_IMAGE_ERRORSTATUSEXIST image header stands error status
DCIMG_ERR_IMAGE_HEADERCORRUPTED image header value is strange
DCIMG_ERR_IMAGE_BROKENCONTENT image content is corrupted
DCIMG_ERR_UNKNOWNCOMMAND unknown command
DCIMG_ERR_UNKNOWNPARAMID unknown PARAMID
DCIMG_ERR_SUCCESS no error, general success code.
DCIMG_ERR_UNREACH internal error


DCIMG_CODEPAGE
DCIMG_CODEPAGE__SHIFT_JIS Shift JIS
DCIMG_CODEPAGE__UTF16_LE UTF-16 (Little Endian)
DCIMG_CODEPAGE__UTF16_BE UTF-16 (Big Endian)
DCIMG_CODEPAGE__UTF7 UTF-7
DCIMG_CODEPAGE__UTF8 UTF-8
DCIMG_CODEPAGE__NONE No data


DCIMG_FRAME_OPTION
DCIMG_FRAME_OPTION__VIEW_CURRENT Current View
DCIMG_FRAME_OPTION__VIEW_1 View1
DCIMG_FRAME_OPTION__VIEW_2 View2
DCIMG_FRAME_OPTION__VIEW_3 View3
DCIMG_FRAME_OPTION__VIEW_4 View4


DCIMG_PIXELTYPE
DCIMG_PIXELTYPE_NONE None
DCIMG_PIXELTYPE_MONO8 Mono 8bit
DCIMG_PIXELTYPE_MONO16 Mono 16bit


DCIMG_METADATAKIND
DCIMG_METADATAKIND_USERDATATEXT user metadata text
DCIMG_METADATAKIND_USERDATABIN user metadata binary
DCIMG_METADATAKIND_TIMESTAMPS time stamp of image
DCIMG_METADATAKIND_FRAMESTAMPS frame stamp of image


DCIMG_METADATAOPTION
DCIMG_METADATAOPTION__LOCATION_FRAME access frame metadata
DCIMG_METADATAOPTION__LOCATION_FILE access file metadata
DCIMG_METADATAOPTION__LOCATION_SESSION access session metadata
DCIMG_METADATAOPTION__VIEW_CURRENT current view
DCIMG_METADATAOPTION__VIEW_1 view1
DCIMG_METADATAOPTION__VIEW_2 view2
DCIMG_METADATAOPTION__VIEW_3 view3
DCIMG_METADATAOPTION__VIEW_4 view4


DCIMG_IDPARAML
DCIMG_IDPARAML_NUMBEROF_TOTALFRAME number of total frame in the file
DCIMG_IDPARAML_NUMBEROF_SESSION number of session in the file
DCIMG_IDPARAML_NUMBEROF_FRAME number of frame in current session
DCIMG_IDPARAML_SIZEOF_USERDATABIN_SESSION byte size of current session binary USER META DATA
DCIMG_IDPARAML_SIZEOF_USERDATABIN_FILE byte size of file binary USER META DATA
DCIMG_IDPARAML_SIZEOF_USERDATATEXT_SESSION byte size of current session text USER META DATA
DCIMG_IDPARAML_SIZEOF_USERDATATEXT_FILE byte size of file text USER META DATA
DCIMG_IDPARAML_IMAGE_WIDTH image width in current session
DCIMG_IDPARAML_IMAGE_HEIGHT image height in current session
DCIMG_IDPARAML_IMAGE_ROWBYTES image rowbytes in current session
DCIMG_IDPARAML_IMAGE_PIXELTYPE image pixeltype in current session
DCIMG_IDPARAML_MAXSIZE_USERDATABIN maximum byte size of frame binary USER META DATA in current session
DCIMG_IDPARAML_MAXSIZE_USERDATABIN_SESSION maximum byte size of session binary USER META DATA in the file
DCIMG_IDPARAML_MAXSIZE_USERDATATEXT maximum byte size of frame text USER META DATA in current session
DCIMG_IDPARAML_MAXSIZE_USERDATATEXT_SESSION maximum byte size of session text USER META DATA in the file
DCIMG_IDPARAML_CURRENT_SESSION current session index
DCIMG_IDPARAML_NUMBEROF_VIEW number of view in current session
DCIMG_IDPARAML_FILEFORMAT_VERSION file format version
DCIMG_IDPARAML_CAPABILITY_IMAGEPROC capability of image process


DCIMGDATA_OPTION
DCIMGDATA_OPTION__VIEW_CURRENT Current View
DCIMGDATA_OPTION__VIEW_1 View1
DCIMGDATA_OPTION__VIEW_2 View2
DCIMGDATA_OPTION__VIEW_3 View3
DCIMGDATA_OPTION__VIEW_4 View4


DCIMGDATA_KIND
DCIMGDATA_KIND__REGION Region of Extraction
DCIMGDATA_KIND__SENSORPARAM Sensor Parameter


DCIMGDATA_REGIONTYPE
DCIMGDATA_REGIONTYPE__RECT16ARRAY Array of DCIMGDATA_REGIONRECT


DCIMG_CAPABILITY_IMAGEPROC
DCIMG_CAPABILITY_IMAGEPROC__HIGHCONTRAST Capability flag to support High Contrast image processing

Go to top of this chapter


Functions



dcimg_init()

Declaration
DCIMG_ERR dcimg_init(
DCIMG_INIT* param
);

Parameter
param
an instance of structure DCIMG_INIT which can specify initialize option

Remarks
dcimg_init() function initializes DCIMG-API runtime. Host software calls this function before calling other functions.

dcimg_open()

Declaration
DCIMG_ERR dcimg_open(
DCIMG_OPEN* param
);

Parameter
param
an instance of structure DCIMG_OPEN which can specify DCIMG file path to acquire HDCIMG handle

Remarks
dcimg_open() function opens the DCIMG file specified by member path of the structure DCIMG_OPEN and return HDCIMG handle. Host software calls this function to get HDCIMG handle. If host software does not need the HDCIMG handle any more, it should call dcimg_close() function. After calling dcimg_close() function, HDCIMG handle is not available and host software can call dcaimg_open() function to get HDCIMG handle again. If this function can open the file, this function returns DCIMG_ERR_SUCCESS and the member hdcimg of the structure DCIMG_OPEN return the HDCIMG handle of specified file. If DCIMG-API could not open the specified file, this function returns error code.

dcimg_close()

Declaration
DCIMG_ERR dcimg_close(
HDCIMG hdcimg
);

Parameter
hdcimg
specify HDCIMG handle that will be released

Remarks
dcimg_close() function release HDCIMG handle and the DCIMG file. After calling this function and success, the HDCIMG handle is not available. To use same DCIMG file again, host software has to call dcimg_open() function for getting HDCIMG handle.

dcimg_getdata()

Declaration
DCIMG_ERR dcimg_getdata(
HDCIMG hdcimg,
DCIMGDATA_HDR* hdr
);

Parameter
hdcimg
specify HDCIMG handle as reference
hdr
a pointer of DCIMGDATA_HDR instance for getting data. DCIMGDATA_HDR is first member of the structure to get data.

Remarks
dcimg_getdata() function gets the data that it is impossible to get with paraml. The structure is prepared by the kind of data. These structures have DCIMGDATA_HDR as the first member.

dcimg_lockframe()

Declaration
DCIMG_ERR dcimg_lockframe(
HDCIMG hdcimg,
DCIMG_FRAME* pFrame
);

Parameter
hdcimg
specify HDCIMG handle as reference
pFrame
a pointer of DCIMG_FRAME instance for getting buffer infomation for access. See the description of DCIMG_FRAME to know which members have to be set prior to calling dcimg_lockframe() and which members contain information afterwards.

Remarks
dcimg_lockframe() function returns a pointer that host software can use to access an image data in DCIMG file. Next calling this function will prepare new data, so the DCIMG_FRAME parameter which was filled by last call is no more available. If the image frame which is specified by DCIMG_FRAME::iFrame is not exist, dcimg_lockframe() function will return DCIMG_ERR_INVALIDFRAMEINDEX. To avoid this situation, host software get the number of frame in session to call dcimg_getparaml() with DCIMG_IDPARAML_NUMBEROF_FRAME.

dcimg_copyframe()

Declaration
DCIMG_ERR dcimg_copyframe(
HDCIMG hdcimg,
DCIMG_FRAME* pFrame
);

Parameter
hdcimg
specify HDCIMG handle as reference
pFrame
a pointer of DCIMG_FRAME instance to describe the details of the copy process. See the description of DCIMG_FRAME to know which members have to be set prior calling dcimg_copyframe() and which members contain information afterwards.

Remarks
dcimg_copyframe() function copies image data from DCIMG file to specified buffer that host software gives

dcimg_copymetadata()

Declaration
DCIMG_ERR dcimg_copymetadata(
HDCIMG hdcimg,
DCIMG_METADATAHDR* hdr
);

Parameter
hdcimg
specify HDCIMG handle as reference
hdr
a pointer of hdr member as a destination buffer for copying meta data

Remarks
dcimg_copymetadata() function copies meta data from DCIMG file to specified buffer that host software gives.

dcimg_copymetadatablock()

Declaration
DCIMG_ERR dcimg_copymetadatablock(
HDCIMG hdcimg,
DCIMG_METADATAHDR* hdr
);

Parameter
hdcimg
specify HDCIMG handle as reference
hdr
a pointer of hdr member as a destination buffer for copying meta data

Remarks
dcimg_copymetadatablock() function copies plural meta data from DCIMG file to specified buffer that host software gives. Available kinds of meta data are TIMESTAMP and FRAMESTAMP.

dcimg_setsessionindex()

Declaration
DCIMG_ERR dcimg_setsessionindex(
HDCIMG hdcimg,
int32 index
);

Parameter
hdcimg
specify HDCIMG handle for changing current session
index
specify a session index

Remarks
dcimg_setsessionindex() function changes the target session when DCIMG file has some session. The session index is 0 based.

dcimg_getsessionindex()

Declaration
DCIMG_ERR dcimg_getsessionindex(
HDCIMG hdcimg,
int32* pIndex
);

Parameter
hdcimg
specify HDCIMG handle for getting current session
pIndex
a pointer of a variable for receiving current session index

Remarks
dcimg_getsessionindex() function returns the target session index. The session index is 0 based.

dcimg_getparaml()

Declaration
DCIMG_ERR dcimg_getparaml(
HDCIMG hdcimg,
DCIMG_IDPARAML index,
int32* paraml
);

Parameter
hdcimg
specify HDCIMG handle for getting parameters
index
a parameter index for getting parameter
paraml
a pointer of a variable for receiving current session index

Remarks
dcimg_getparaml() function returns a int32 value into paraml argument with DCIMG_IDPARAML value specified by the index argument.

Go to top of this chapter


Structures



DCIMG_GUID

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

Remarks
A structure type for DCIMG_INIT::guid member. This is not used in general.


DCIMG_INIT

struct DCIMG_INIT {
int32 size; // sizeof(*this)
int32 reserved; // reserved
const DCIMG_GUID* guid; // GUID option, usually NULL
};

size
Set byte size of DCIMG_INIT structure.
reserved
Set 0 because this member is reserved.
guid
Set pointer of DCIMG_GUID instance. Set NULL usually.

Remarks
This is used as a pointer for calling dcimg_init() function. Host software initializes DCIMG-API and will be able to call other DCIMG functions


DCIMG_OPEN

struct DCIMG_OPEN {
int32 size; // size of this structure
int32 codepage; // DCIMG_CODEPAGE_*
HDCIMG hdcimg; //
LPCTSTR path; // file path
};

codepage
If it is not 0, the string specified by path is treated with the encoding specified by codepage.
hdcimg
dcimg_open() function fills this value with DCIMG file handle value if success.
path
Host software fills this value with a point to specify DCIMG file path.

DCIMG_TIMESTAMP

struct DCIMG_TIMESTAMP {
_ui32 sec; // second
int32 microsec; // micro second
};

Remarks
This is used to get time stamp in some structure.


DCIMG_FRAME

struct DCIMG_FRAME {
int32 size; // size of this structure.
int32 iKind; // 0 reserved
int32 option; // DCIMG_FRAME_OPTION
int32 iFrame; // frame index
void* buf; // pointer for top-left image
int32 rowbytes; // byte size for next line
DCIMG_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
DCIMG_TIMESTAMP timestamp; // time stamp
int32 framestamp; // frame stamp
int32 camerastamp; // camera stamp
};

size
Set size of this structure.
iKind
Reserved. Set 0.
option
Set optiion to access image
iFrame
Specify frame by index.
buf
dcimg_lockframe() fills this with the address of top-left corner of the image data.
Set this as the definition pointer before calling dcimg_copyframe().
rowbytes
dcimg_lockframe() fills this with the byte size offset value from a line to the next line. This value can be negative in some cases.
dcimg_copyframe() requires this as a byte size offset value from a line to the next line. This value can be negative if destination image is up-side-down.
type
dcimg_lockframe() fills this with a DCIMG_PIXELTYPE value of image buffer.
dcimg_copyframe() requires 0 and host application should set before calling the function.
width
dcimg_lockframe() fills this with a value of horizontal pixel count in the frame.
dcimg_copyframe() requires this with the number of horizontal pixels that host application wants to copy.
height
dcimg_lockframe() fills this with a value of vertical line count in the frame.
dcimg_copyframe() requires this with number of vertical lines that host application wants to copy.
left
dcimg_lockframe() fills this with a value of horizontal offset address that image starts. Usually this is 0.
dcimg_copyframe() requires this with horizontal offset address that host application wants to copy as top-left corner.
top
dcimg_lockframe() fills this with a value of vertical offset address that image starts. Usually this is 0.
dcimg_copyframe() requires this with vertical offset address that host application wants to copy as top-left corner.
timestamp
time stamp value is filled if it is recorded. If this value is 0, timestamp is not available in the frame.
framestamp
frame stamp value is filled if it is recorded. frame stamp starts by 0 from beginning of session.
camerastamp
camera stamp value is filled if it is recorded. camera stamp is supported in several cameras and user or host application can set.

DCIMG_METADATAHDR

struct DCIMG_METADATAHDR {
int32 size; // size of whole structure, not only this
int32 iKind; // DCIMG_METADATAKIND
int32 option; // DCIMG_METADATAOPTION
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.

DCIMG_USERDATATEXT

struct DCIMG_USERDATATEXT {
DCIMG_METADATAHDR hdr; // size member should be size of this structure
char* text; // pointer to receive meta data
int32 text_len; // byte size of destination buffer
int32 codepage; // character encoding value, see DCIMG_CODEPAGE
};

hdr
iKind should be DCIMG_METADATAKIND_USERDATATEXT. option should be one of DCIMG_METADATAOPTION__LOCATION.
text
Set the destination buffer to receive the text of meta data.
text_len
Set the size of the destinanation buffer to receive.
codepage
Set one of DCIMG_CODEPAGE as character encoding value.

DCIMG_USERDATABIN

struct DCIMG_USERDATABIN {
DCIMG_METADATAHDR hdr; // size member should be size of this structure
void* bin; // pointer to receive meta data
int32 bin_len; // byte size of destination buffer
int32 reserved; // 0 reserved
};

hdr
iKind should be DCIMG_METADATAKIND_USERDATABIN. option should be one of DCIMG_METADATAOPTION__LOCATION.
bin
Set the destination buffer to receive the binary of meta data.
bin_len
Set the size of the destinanation buffer to receive.
reserved
This member is reserved. Set to 0.

DCIMG_USERDATATEXTBLOCK

struct DCIMG_USERDATATEXTBLOCK {
DCIMG_METADATAHDR hdr; // size member should be size of this structure
void* userdatatext; // pointer for userdatatext block
int32 userdatatextsize; // size of one userdatatext
int32* userdatatextvalidsize; // return the written data text size of each frame
int32 userdatatextmax; // maximum number of userdatatext which can receive
int32 userdatatextcount; // number of userdatatext written to buffer
int32 userdatatext_kind; // DCIMG_METADATAOPTION__LOCATION
int32* userdatatextcodepage; // encode type of each written userdatatext
};

hdr
iKind should be DCIMG_METADATAKIND_USERDATATEXT.
userdatatext
Set the destination buffer to receive the block of user text.
userdatatextsize
Set the size of one userdatatext.
userdatatextvalidsize
Set the array to receive the written data text size of each frame.
userdatatextmax
Set the maximum number of userdatatext which can receive. userdatatext pointer should have userdatatextsize * userdatatextmax.
userdatatextcount
Return how many userdatatext are filled.
userdatatext_kind
Choose userdatatext kind from DCIMG_METADATAOPTION__LOCATION (File, Session, Frame).
userdatatextcodepage
Return encode type of each written userdatatext.

DCIMG_USERDATABINBLOCK

struct DCIMG_USERDATABINBLOCK {
DCIMG_METADATAHDR hdr; // size member should be size of this structure
void* userdatabin; // pointer for userdatabin block
int32 userdatabinsize; // size of one userdatabin
int32* userdatabinvalidsize; // return the written data bin size of each frame
int32 userdatabinmax; // maximum number of userdatabin which can receive
int32 userdatabincount; // number of userdatabin written to buffer
int32 userdatabin_kind; // DCIMG_METADATAOPTION__LOCATION
};

hdr
iKind should be DCIMG_METADATAKIND_USERDATABIN.
userdatabin
Set the destination to receive the block of userdatabin.
userdatabinsize
Set the buffer size for one userdatabin.
userdatabinvalidsize
Set the array to receive the written data bin size of each frame.
userdatabinmax
Set the maximum number of userdatabin which can receive. userdatabin pointer should have userdatabinsize * userdatabinmax.
userdatabincount
Return how many userdatabin are filled.
userdatabin_kind
Choose userdatabin kind from DCIMG_METADATAOPTION__LOCATION (File, Session, Frame).

DCIMG_TIMESTAMPBLOCK

struct DCIMG_TIMESTAMPBLOCK {
DCIMG_METADATAHDR hdr; // size member should be size of this structure
DCIMG_TIMESTAMP* timestamps; // pointer for TIMESTAMP block
int32 timestampmax; // maximum number of timestamp to receive
int32 timestampkind; // reserved to return timestamp kind
int32 timestampsize; // sizeof(DCIMG_TIMESTAMP)
int32 timestampvalidsize; // the written data size of DCIMG_TIMESTAMP
int32 timestampcount; // number of timestamp written to timestamps
};

hdr
iKind should be DCIMG_METADATAKIND_TIMESTAMPS.
timestamps
Set the array of TIMESTAMP to receive the timestamp.
timestampmax
Set the maximum number of timestamp which can receive.
timestampkind
Reserved to return timestamp kind(Hardware, Driver, DCAM etc...).
timestampsize
Set to the byte size of DCIMG_TIMESTAMP structure.
timestampvalidsize
Return the written data size of DCIMG_TIMESTAMP.
timestampcount
Return how many timestamp are filled.
This member is reserved. Set to 0.

DCIMG_FRAMESTAMPBLOCK

struct DCIMG_FRAMESTAMPBLOCK {
DCIMG_METADATAHDR hdr; // size member should be size of this structure
int32* framestamps; // pointer for framestamp block
int32 framestampmax; // maximum number of framestamp to receive
int32 framestampcount; // number of framestamp written to buffer
int32 reserved; // 0 reserved.
};

hdr
iKind should be DCIMG_METADATAKIND_FRAMESTAMPS.
framestamps
Set the destination buffer to receive framestamp block.
framestampmax
Set the maximum number of frametamp which can receive.
framestampcount
Return how many framestamp are filled.
reserved
This member is reserved. Set to 0.

DCIMGDATA_HDR

struct DCIMGDATA_HDR {
int32 size; // size of whole structure, not only this
int32 iKind; // DCIMGDATA_KIND
int32 option; // DCIMGDATA_OPTION
int32 reserved; // 0 reserved
};

size
Set this to the byte size of the structure that has included this DCIMGDATA_HDR structure.
iKind
Set the DCIMGDATA_KIND
option
Set the DCIMGDATA_OPTION
reserved
This member is reserved. Set to 0.

DCIMGDATA_REGION

struct DCIMGDATA_REGION {
DCIMGDATA_HDR hdr; // iKind = DCIMGDATA_KIND__REGION
int32 option; // 0 reserved
int32 type; // DCIMGDATA_RETIONTYPE
void* data; // top of data
int32 datasize; // size of data
int32 reserved; // 0 reserved
};

hdr
size member should be size of this structure
option
This member is reserved. Set to 0.
type
Get data type of region
data
Get pointer of region data.
datasize
Get data size
reserved
This member is reserved. Set to 0.

DCIMGDATA_REGIONRECT

struct DCIMGDATA_REGIONRECT {
short left; // left side
short top; // top side
short right; // right side
short bottom; // bottom side
};

Remarks
This is used to get rectangle information.


DCIMGDATA_SENSORPARAM

struct DCIMGDATA_SENSORPARAM {
DCIMGDATA_HDR hdr; // iKind = DCIMGDATA_KIND__SENSORPARAM
int32 option; // 0 reserved
int32 binning; // binning
int32 sensorhpos; // horizontal offset of sensor
int32 sensorhsize; // horizontal size of sensor
int32 sensorvpos; // vertical offset of sensor
int32 sensorvsize; // vertical size of sensor
};

hdr
size member should be size of this structure
option
This member is reserved. Set to 0.
binning
Get binning of recorded image
sensorhpos
Get horizontal offset of recorded image on sensor coordinate.
sensorhsize
Get horizontal size of recorded image on sensor coordinate.
sensorvpos
Get vertical offset of recorded image on sensor coordinate.
sensorvsize
Get vertical size of recorded image on sensor coordinate.

Go to top of this chapter