1/*
2 * 1394-Based Digital Camera Control Library
3 *
4 * Video format headers
5 *
6 * Written by Damien Douxchamps <ddouxchamps@users.sf.net>
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21 */
22
23#include <dc1394/log.h>
24
25/*! \file dc1394/video.h
26 \brief Functions related to video modes, formats, framerate and video flow.
27
28 More details soon
29*/
30
31#ifndef __DC1394_VIDEO_H__
32#define __DC1394_VIDEO_H__
33
34/**
35 * Enumeration of iso data speeds
36 *
37 * Most (if not all) cameras are compatible with 400Mbps speed. Only older cameras (pre-1999) may still only work at sub-400
38 * speeds. However, speeds lower than 400Mbps are still useful: they can be used for longer distances (e.g. 10m cables).
39 * Speeds over 400Mbps are only available in "B" mode (DC1394_OPERATION_MODE_1394B).
40 */
41typedef enum {
42 DC1394_ISO_SPEED_100= 0,
43 DC1394_ISO_SPEED_200,
44 DC1394_ISO_SPEED_400,
45 DC1394_ISO_SPEED_800,
46 DC1394_ISO_SPEED_1600,
47 DC1394_ISO_SPEED_3200
48} dc1394speed_t;
49#define DC1394_ISO_SPEED_MIN DC1394_ISO_SPEED_100
50#define DC1394_ISO_SPEED_MAX DC1394_ISO_SPEED_3200
51#define DC1394_ISO_SPEED_NUM (DC1394_ISO_SPEED_MAX - DC1394_ISO_SPEED_MIN + 1)
52
53/**
54 * Enumeration of video framerates
55 *
56 * This enumeration is used for non-Format_7 modes. The framerate can be lower than expected if the exposure time is longer
57 * than the requested frame period. Framerate can be controlled in a number of other ways: framerate feature, external trigger,
58 * software trigger, shutter throttling and packet size (Format_7)
59 */
60typedef enum {
61 DC1394_FRAMERATE_1_875= 32,
62 DC1394_FRAMERATE_3_75,
63 DC1394_FRAMERATE_7_5,
64 DC1394_FRAMERATE_15,
65 DC1394_FRAMERATE_30,
66 DC1394_FRAMERATE_60,
67 DC1394_FRAMERATE_120,
68 DC1394_FRAMERATE_240
69} dc1394framerate_t;
70#define DC1394_FRAMERATE_MIN DC1394_FRAMERATE_1_875
71#define DC1394_FRAMERATE_MAX DC1394_FRAMERATE_240
72#define DC1394_FRAMERATE_NUM (DC1394_FRAMERATE_MAX - DC1394_FRAMERATE_MIN + 1)
73
74/**
75 * Operation modes
76 *
77 * Two operation modes exist: the legacy and most common 1394a, and the newer 1394B. The latter allows speeds over 400Mbps, but
78 * can also be used at other speeds.
79 */
80typedef enum {
81 DC1394_OPERATION_MODE_LEGACY = 480,
82 DC1394_OPERATION_MODE_1394B
83} dc1394operation_mode_t;
84#define DC1394_OPERATION_MODE_MIN DC1394_OPERATION_MODE_LEGACY
85#define DC1394_OPERATION_MODE_MAX DC1394_OPERATION_MODE_1394B
86#define DC1394_OPERATION_MODE_NUM (DC1394_OPERATION_MODE_MAX - DC1394_OPERATION_MODE_MIN + 1)
87
88/**
89 * List of framerates
90 *
91 * dc1394framerates_t contains a list of available framerates for a particular video mode.
92 */
93typedef struct {
94 uint32_t num;
95 dc1394framerate_t framerates[DC1394_FRAMERATE_NUM];
96} dc1394framerates_t;
97
98/**
99 * Video frame structure.
100 *
101 * dc1394video_frame_t is the structure returned by the capture functions. It contains the captured image as well as a number of
102 * information.
103 *
104 * In general this structure should be calloc'ed so that members such as "allocated size"
105 * are properly set to zero. Don't forget to free the "image" member before freeing the struct itself.
106 */
107typedef struct __dc1394_video_frame
108{
109 unsigned char * image; /* the image. May contain padding data too (vendor specific). Read/write allowed. Free NOT allowed if
110 returned by dc1394_capture_dequeue() */
111 uint32_t size[2]; /* the image size [width, height] */
112 uint32_t position[2]; /* the WOI/ROI position [horizontal, vertical] == [0,0] for full frame */
113 dc1394color_coding_t color_coding; /* the color coding used. This field is valid for all video modes. */
114 dc1394color_filter_t color_filter; /* the color filter used. This field is valid only for RAW modes and IIDC 1.31 */
115 uint32_t yuv_byte_order; /* the order of the fields for 422 formats: YUYV or UYVY */
116 uint32_t data_depth; /* the number of bits per pixel. The number of grayscale levels is 2^(this_number).
117 This is independent from the colour coding */
118 uint32_t stride; /* the number of bytes per image line */
119 dc1394video_mode_t video_mode; /* the video mode used for capturing this frame */
120 uint64_t total_bytes; /* the total size of the frame buffer in bytes. May include packet-
121 multiple padding and intentional padding (vendor specific) */
122 uint32_t image_bytes; /* the number of bytes used for the image (image data only, no padding) */
123 uint32_t padding_bytes; /* the number of extra bytes, i.e. total_bytes-image_bytes. */
124 uint32_t packet_size; /* the size of a packet in bytes. (IIDC data) */
125 uint32_t packets_per_frame; /* the number of packets per frame. (IIDC data) */
126 uint64_t timestamp; /* the unix time [microseconds] at which the frame was captured in
127 the video1394 ringbuffer */
128 uint32_t frames_behind; /* the number of frames in the ring buffer that are yet to be accessed by the user */
129 dc1394camera_t *camera; /* the parent camera of this frame */
130 uint32_t id; /* the frame position in the ring buffer */
131 uint64_t allocated_image_bytes; /* amount of memory allocated in for the *image field. */
132 dc1394bool_t little_endian; /* DC1394_TRUE if little endian (16bpp modes only),
133 DC1394_FALSE otherwise */
134 dc1394bool_t data_in_padding; /* DC1394_TRUE if data is present in the padding bytes in IIDC 1.32 format,
135 DC1394_FALSE otherwise */
136} dc1394video_frame_t;
137
138#ifdef __cplusplus
139extern "C" {
140#endif
141
142/***************************************************************************
143 Video functions: formats, framerates,...
144 ***************************************************************************/
145
146/**
147 * Gets a list of video modes supported by the camera.
148 */
149dc1394error_t dc1394_video_get_supported_modes(dc1394camera_t *camera, dc1394video_modes_t *video_modes);
150
151/**
152 * Gets a list of supported video framerates for a given video mode. This function only works with non-scalable formats.
153 */
154dc1394error_t dc1394_video_get_supported_framerates(dc1394camera_t *camera, dc1394video_mode_t video_mode, dc1394framerates_t *framerates);
155
156/**
157 * Gets the current framerate. This is meaningful only if the video mode is not scalable.
158 */
159dc1394error_t dc1394_video_get_framerate(dc1394camera_t *camera, dc1394framerate_t *framerate);
160
161/**
162 * Sets the current framerate. This is meaningful only if the video mode is not scalable.
163 */
164dc1394error_t dc1394_video_set_framerate(dc1394camera_t *camera, dc1394framerate_t framerate);
165
166/**
167 * Gets the current video mode.
168 */
169dc1394error_t dc1394_video_get_mode(dc1394camera_t *camera, dc1394video_mode_t *video_mode);
170
171/**
172 * Sets the current video mode.
173 */
174dc1394error_t dc1394_video_set_mode(dc1394camera_t *camera, dc1394video_mode_t video_mode);
175
176/**
177 * Gets the current operation mode.
178 */
179dc1394error_t dc1394_video_get_operation_mode(dc1394camera_t *camera, dc1394operation_mode_t *mode);
180
181/**
182 * Sets the current operation mode.
183 */
184dc1394error_t dc1394_video_set_operation_mode(dc1394camera_t *camera, dc1394operation_mode_t mode);
185
186/**
187 * Gets the current ISO speed.
188 */
189dc1394error_t dc1394_video_get_iso_speed(dc1394camera_t *camera, dc1394speed_t *speed);
190
191/**
192 * Sets the current ISO speed. Speeds over 400Mbps require 1394B.
193 */
194dc1394error_t dc1394_video_set_iso_speed(dc1394camera_t *camera, dc1394speed_t speed);
195
196/**
197 * Gets the current ISO channel
198 */
199dc1394error_t dc1394_video_get_iso_channel(dc1394camera_t *camera, uint32_t * channel);
200
201/**
202 * Sets the current ISO channel
203 */
204dc1394error_t dc1394_video_set_iso_channel(dc1394camera_t *camera, uint32_t channel);
205
206/**
207 * Gets the current data depth, in bits. Only meaningful for 16bpp video modes (RAW16, RGB48, MONO16,...)
208 */
209dc1394error_t dc1394_video_get_data_depth(dc1394camera_t *camera, uint32_t *depth);
210
211/**
212 * Starts/stops the isochronous data transmission. In other words, use this to control the image flow.
213 */
214dc1394error_t dc1394_video_set_transmission(dc1394camera_t *camera, dc1394switch_t pwr);
215
216/**
217 * Gets the status of the video transmission
218 */
219dc1394error_t dc1394_video_get_transmission(dc1394camera_t *camera, dc1394switch_t *pwr);
220
221/**
222 * Turns one-shot mode on or off
223 */
224dc1394error_t dc1394_video_set_one_shot(dc1394camera_t *camera, dc1394switch_t pwr);
225
226/**
227 * Gets the status of the one-shot mode.
228 */
229dc1394error_t dc1394_video_get_one_shot(dc1394camera_t *camera, dc1394bool_t *is_on);
230
231/**
232 * Turns multishot mode on or off
233 */
234dc1394error_t dc1394_video_set_multi_shot(dc1394camera_t *camera, uint32_t numFrames, dc1394switch_t pwr);
235
236/**
237 * Gets the status of the multi-shot mode.
238 */
239dc1394error_t dc1394_video_get_multi_shot(dc1394camera_t *camera, dc1394bool_t *is_on, uint32_t *numFrames);
240
241/**
242 * Gets the bandwidth usage of a camera.
243 *
244 * This function returns the bandwidth that is used by the camera *IF* ISO was ON.
245 * The returned value is in bandwidth units. The 1394 bus has 4915 bandwidth units
246 * available per cycle. Each unit corresponds to the time it takes to send one
247 * quadlet at ISO speed S1600. The bandwidth usage at S400 is thus four times the
248 * number of quadlets per packet. Thanks to Krisitian Hogsberg for clarifying this.
249 */
250dc1394error_t dc1394_video_get_bandwidth_usage(dc1394camera_t *camera, uint32_t *bandwidth);
251
252#ifdef __cplusplus
253}
254#endif
255
256#endif
257

source code of include/dc1394/video.h