/* * 1394-Based Digital Camera Control Library * * Video format headers * * Written by Damien Douxchamps * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ #include /*! \file dc1394/video.h \brief Functions related to video modes, formats, framerate and video flow. More details soon */ #ifndef __DC1394_VIDEO_H__ #define __DC1394_VIDEO_H__ /** * Enumeration of iso data speeds * * Most (if not all) cameras are compatible with 400Mbps speed. Only older cameras (pre-1999) may still only work at sub-400 * speeds. However, speeds lower than 400Mbps are still useful: they can be used for longer distances (e.g. 10m cables). * Speeds over 400Mbps are only available in "B" mode (DC1394_OPERATION_MODE_1394B). */ typedef enum { DC1394_ISO_SPEED_100= 0, DC1394_ISO_SPEED_200, DC1394_ISO_SPEED_400, DC1394_ISO_SPEED_800, DC1394_ISO_SPEED_1600, DC1394_ISO_SPEED_3200 } dc1394speed_t; #define DC1394_ISO_SPEED_MIN DC1394_ISO_SPEED_100 #define DC1394_ISO_SPEED_MAX DC1394_ISO_SPEED_3200 #define DC1394_ISO_SPEED_NUM (DC1394_ISO_SPEED_MAX - DC1394_ISO_SPEED_MIN + 1) /** * Enumeration of video framerates * * This enumeration is used for non-Format_7 modes. The framerate can be lower than expected if the exposure time is longer * than the requested frame period. Framerate can be controlled in a number of other ways: framerate feature, external trigger, * software trigger, shutter throttling and packet size (Format_7) */ typedef enum { DC1394_FRAMERATE_1_875= 32, DC1394_FRAMERATE_3_75, DC1394_FRAMERATE_7_5, DC1394_FRAMERATE_15, DC1394_FRAMERATE_30, DC1394_FRAMERATE_60, DC1394_FRAMERATE_120, DC1394_FRAMERATE_240 } dc1394framerate_t; #define DC1394_FRAMERATE_MIN DC1394_FRAMERATE_1_875 #define DC1394_FRAMERATE_MAX DC1394_FRAMERATE_240 #define DC1394_FRAMERATE_NUM (DC1394_FRAMERATE_MAX - DC1394_FRAMERATE_MIN + 1) /** * Operation modes * * Two operation modes exist: the legacy and most common 1394a, and the newer 1394B. The latter allows speeds over 400Mbps, but * can also be used at other speeds. */ typedef enum { DC1394_OPERATION_MODE_LEGACY = 480, DC1394_OPERATION_MODE_1394B } dc1394operation_mode_t; #define DC1394_OPERATION_MODE_MIN DC1394_OPERATION_MODE_LEGACY #define DC1394_OPERATION_MODE_MAX DC1394_OPERATION_MODE_1394B #define DC1394_OPERATION_MODE_NUM (DC1394_OPERATION_MODE_MAX - DC1394_OPERATION_MODE_MIN + 1) /** * List of framerates * * dc1394framerates_t contains a list of available framerates for a particular video mode. */ typedef struct { uint32_t num; dc1394framerate_t framerates[DC1394_FRAMERATE_NUM]; } dc1394framerates_t; /** * Video frame structure. * * dc1394video_frame_t is the structure returned by the capture functions. It contains the captured image as well as a number of * information. * * In general this structure should be calloc'ed so that members such as "allocated size" * are properly set to zero. Don't forget to free the "image" member before freeing the struct itself. */ typedef struct __dc1394_video_frame { unsigned char * image; /* the image. May contain padding data too (vendor specific). Read/write allowed. Free NOT allowed if returned by dc1394_capture_dequeue() */ uint32_t size[2]; /* the image size [width, height] */ uint32_t position[2]; /* the WOI/ROI position [horizontal, vertical] == [0,0] for full frame */ dc1394color_coding_t color_coding; /* the color coding used. This field is valid for all video modes. */ dc1394color_filter_t color_filter; /* the color filter used. This field is valid only for RAW modes and IIDC 1.31 */ uint32_t yuv_byte_order; /* the order of the fields for 422 formats: YUYV or UYVY */ uint32_t data_depth; /* the number of bits per pixel. The number of grayscale levels is 2^(this_number). This is independent from the colour coding */ uint32_t stride; /* the number of bytes per image line */ dc1394video_mode_t video_mode; /* the video mode used for capturing this frame */ uint64_t total_bytes; /* the total size of the frame buffer in bytes. May include packet- multiple padding and intentional padding (vendor specific) */ uint32_t image_bytes; /* the number of bytes used for the image (image data only, no padding) */ uint32_t padding_bytes; /* the number of extra bytes, i.e. total_bytes-image_bytes. */ uint32_t packet_size; /* the size of a packet in bytes. (IIDC data) */ uint32_t packets_per_frame; /* the number of packets per frame. (IIDC data) */ uint64_t timestamp; /* the unix time [microseconds] at which the frame was captured in the video1394 ringbuffer */ uint32_t frames_behind; /* the number of frames in the ring buffer that are yet to be accessed by the user */ dc1394camera_t *camera; /* the parent camera of this frame */ uint32_t id; /* the frame position in the ring buffer */ uint64_t allocated_image_bytes; /* amount of memory allocated in for the *image field. */ dc1394bool_t little_endian; /* DC1394_TRUE if little endian (16bpp modes only), DC1394_FALSE otherwise */ dc1394bool_t data_in_padding; /* DC1394_TRUE if data is present in the padding bytes in IIDC 1.32 format, DC1394_FALSE otherwise */ } dc1394video_frame_t; #ifdef __cplusplus extern "C" { #endif /*************************************************************************** Video functions: formats, framerates,... ***************************************************************************/ /** * Gets a list of video modes supported by the camera. */ dc1394error_t dc1394_video_get_supported_modes(dc1394camera_t *camera, dc1394video_modes_t *video_modes); /** * Gets a list of supported video framerates for a given video mode. This function only works with non-scalable formats. */ dc1394error_t dc1394_video_get_supported_framerates(dc1394camera_t *camera, dc1394video_mode_t video_mode, dc1394framerates_t *framerates); /** * Gets the current framerate. This is meaningful only if the video mode is not scalable. */ dc1394error_t dc1394_video_get_framerate(dc1394camera_t *camera, dc1394framerate_t *framerate); /** * Sets the current framerate. This is meaningful only if the video mode is not scalable. */ dc1394error_t dc1394_video_set_framerate(dc1394camera_t *camera, dc1394framerate_t framerate); /** * Gets the current video mode. */ dc1394error_t dc1394_video_get_mode(dc1394camera_t *camera, dc1394video_mode_t *video_mode); /** * Sets the current video mode. */ dc1394error_t dc1394_video_set_mode(dc1394camera_t *camera, dc1394video_mode_t video_mode); /** * Gets the current operation mode. */ dc1394error_t dc1394_video_get_operation_mode(dc1394camera_t *camera, dc1394operation_mode_t *mode); /** * Sets the current operation mode. */ dc1394error_t dc1394_video_set_operation_mode(dc1394camera_t *camera, dc1394operation_mode_t mode); /** * Gets the current ISO speed. */ dc1394error_t dc1394_video_get_iso_speed(dc1394camera_t *camera, dc1394speed_t *speed); /** * Sets the current ISO speed. Speeds over 400Mbps require 1394B. */ dc1394error_t dc1394_video_set_iso_speed(dc1394camera_t *camera, dc1394speed_t speed); /** * Gets the current ISO channel */ dc1394error_t dc1394_video_get_iso_channel(dc1394camera_t *camera, uint32_t * channel); /** * Sets the current ISO channel */ dc1394error_t dc1394_video_set_iso_channel(dc1394camera_t *camera, uint32_t channel); /** * Gets the current data depth, in bits. Only meaningful for 16bpp video modes (RAW16, RGB48, MONO16,...) */ dc1394error_t dc1394_video_get_data_depth(dc1394camera_t *camera, uint32_t *depth); /** * Starts/stops the isochronous data transmission. In other words, use this to control the image flow. */ dc1394error_t dc1394_video_set_transmission(dc1394camera_t *camera, dc1394switch_t pwr); /** * Gets the status of the video transmission */ dc1394error_t dc1394_video_get_transmission(dc1394camera_t *camera, dc1394switch_t *pwr); /** * Turns one-shot mode on or off */ dc1394error_t dc1394_video_set_one_shot(dc1394camera_t *camera, dc1394switch_t pwr); /** * Gets the status of the one-shot mode. */ dc1394error_t dc1394_video_get_one_shot(dc1394camera_t *camera, dc1394bool_t *is_on); /** * Turns multishot mode on or off */ dc1394error_t dc1394_video_set_multi_shot(dc1394camera_t *camera, uint32_t numFrames, dc1394switch_t pwr); /** * Gets the status of the multi-shot mode. */ dc1394error_t dc1394_video_get_multi_shot(dc1394camera_t *camera, dc1394bool_t *is_on, uint32_t *numFrames); /** * Gets the bandwidth usage of a camera. * * This function returns the bandwidth that is used by the camera *IF* ISO was ON. * The returned value is in bandwidth units. The 1394 bus has 4915 bandwidth units * available per cycle. Each unit corresponds to the time it takes to send one * quadlet at ISO speed S1600. The bandwidth usage at S400 is thus four times the * number of quadlets per packet. Thanks to Krisitian Hogsberg for clarifying this. */ dc1394error_t dc1394_video_get_bandwidth_usage(dc1394camera_t *camera, uint32_t *bandwidth); #ifdef __cplusplus } #endif #endif