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 */ 41 typedef 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 */ 60 typedef 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 */ 80 typedef 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 */ 93 typedef 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 */ 107 typedef 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 139 extern "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 */ 149 dc1394error_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 */ 154 dc1394error_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 */ 159 dc1394error_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 */ 164 dc1394error_t dc1394_video_set_framerate(dc1394camera_t *camera, dc1394framerate_t framerate); 165 166 /** 167 * Gets the current video mode. 168 */ 169 dc1394error_t dc1394_video_get_mode(dc1394camera_t *camera, dc1394video_mode_t *video_mode); 170 171 /** 172 * Sets the current video mode. 173 */ 174 dc1394error_t dc1394_video_set_mode(dc1394camera_t *camera, dc1394video_mode_t video_mode); 175 176 /** 177 * Gets the current operation mode. 178 */ 179 dc1394error_t dc1394_video_get_operation_mode(dc1394camera_t *camera, dc1394operation_mode_t *mode); 180 181 /** 182 * Sets the current operation mode. 183 */ 184 dc1394error_t dc1394_video_set_operation_mode(dc1394camera_t *camera, dc1394operation_mode_t mode); 185 186 /** 187 * Gets the current ISO speed. 188 */ 189 dc1394error_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 */ 194 dc1394error_t dc1394_video_set_iso_speed(dc1394camera_t *camera, dc1394speed_t speed); 195 196 /** 197 * Gets the current ISO channel 198 */ 199 dc1394error_t dc1394_video_get_iso_channel(dc1394camera_t *camera, uint32_t * channel); 200 201 /** 202 * Sets the current ISO channel 203 */ 204 dc1394error_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 */ 209 dc1394error_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 */ 214 dc1394error_t dc1394_video_set_transmission(dc1394camera_t *camera, dc1394switch_t pwr); 215 216 /** 217 * Gets the status of the video transmission 218 */ 219 dc1394error_t dc1394_video_get_transmission(dc1394camera_t *camera, dc1394switch_t *pwr); 220 221 /** 222 * Turns one-shot mode on or off 223 */ 224 dc1394error_t dc1394_video_set_one_shot(dc1394camera_t *camera, dc1394switch_t pwr); 225 226 /** 227 * Gets the status of the one-shot mode. 228 */ 229 dc1394error_t dc1394_video_get_one_shot(dc1394camera_t *camera, dc1394bool_t *is_on); 230 231 /** 232 * Turns multishot mode on or off 233 */ 234 dc1394error_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 */ 239 dc1394error_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 */ 250 dc1394error_t dc1394_video_get_bandwidth_usage(dc1394camera_t *camera, uint32_t *bandwidth); 251 252 #ifdef __cplusplus 253 } 254 #endif 255 256 #endif 257