1/*
2 * 1394-Based Digital Camera Control Library
3 *
4 * Written by Damien Douxchamps <ddouxchamps@users.sf.net>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 */
20
21#include <dc1394/log.h>
22#include <stdio.h>
23
24#ifndef __DC1394_CAMERA_H__
25#define __DC1394_CAMERA_H__
26
27/*! \file dc1394/camera.h
28 \brief Basic system and camera functions
29 \author Damien Douxchamps: coding
30 \author Peter Antoniac: documentation maintainer
31
32 More details soon
33*/
34
35/**
36 * List of IIDC versions
37 *
38 * Currently, the following versions exist: 1.04, 1.20, PTGREY, 1.30 and 1.31 (1.32 coming soon)
39 * Observing other versions means that there's a bug crawling somewhere.
40 */
41typedef enum {
42 DC1394_IIDC_VERSION_1_04 = 544,
43 DC1394_IIDC_VERSION_1_20,
44 DC1394_IIDC_VERSION_PTGREY,
45 DC1394_IIDC_VERSION_1_30,
46 DC1394_IIDC_VERSION_1_31,
47 DC1394_IIDC_VERSION_1_32,
48 DC1394_IIDC_VERSION_1_33,
49 DC1394_IIDC_VERSION_1_34,
50 DC1394_IIDC_VERSION_1_35,
51 DC1394_IIDC_VERSION_1_36,
52 DC1394_IIDC_VERSION_1_37,
53 DC1394_IIDC_VERSION_1_38,
54 DC1394_IIDC_VERSION_1_39
55} dc1394iidc_version_t;
56#define DC1394_IIDC_VERSION_MIN DC1394_IIDC_VERSION_1_04
57#define DC1394_IIDC_VERSION_MAX DC1394_IIDC_VERSION_1_39
58#define DC1394_IIDC_VERSION_NUM (DC1394_IIDC_VERSION_MAX - DC1394_IIDC_VERSION_MIN + 1)
59
60/**
61 * Enumeration of power classes
62 *
63 * This is currently not used in libdc1394.
64 */
65typedef enum {
66 DC1394_POWER_CLASS_NONE=608,
67 DC1394_POWER_CLASS_PROV_MIN_15W,
68 DC1394_POWER_CLASS_PROV_MIN_30W,
69 DC1394_POWER_CLASS_PROV_MIN_45W,
70 DC1394_POWER_CLASS_USES_MAX_1W,
71 DC1394_POWER_CLASS_USES_MAX_3W,
72 DC1394_POWER_CLASS_USES_MAX_6W,
73 DC1394_POWER_CLASS_USES_MAX_10W
74} dc1394power_class_t;
75#define DC1394_POWER_CLASS_MIN DC1394_POWER_CLASS_NONE
76#define DC1394_POWER_CLASS_MAX DC1394_POWER_CLASS_USES_MAX_10W
77#define DC1394_POWER_CLASS_NUM (DC1394_POWER_CLASS_MAX - DC1394_POWER_CLASS_MIN + 1)
78
79/**
80 * Enumeration of PHY delays
81 *
82 * This is currently not used in libdc1394.
83 */
84typedef enum {
85 DC1394_PHY_DELAY_MAX_144_NS=640,
86 DC1394_PHY_DELAY_UNKNOWN_0,
87 DC1394_PHY_DELAY_UNKNOWN_1,
88 DC1394_PHY_DELAY_UNKNOWN_2
89} dc1394phy_delay_t;
90#define DC1394_PHY_DELAY_MIN DC1394_PHY_DELAY_MAX_144_NS
91#define DC1394_PHY_DELAY_MAX DC1394_PHY_DELAY_UNKNOWN_0
92#define DC1394_PHY_DELAY_NUM (DC1394_PHY_DELAY_MAX - DC1394_PHY_DELAY_MIN + 1)
93
94/**
95 * Camera structure
96 *
97 * This structure represents the camera in libdc1394. It contains a number of useful static information, such as model/vendor names,
98 * a few capabilities, some ROM offsets, a unique identifier, etc...
99 */
100typedef struct __dc1394_camera
101{
102 /* system/firmware information */
103 uint64_t guid;
104 int unit;
105 uint32_t unit_spec_ID;
106 uint32_t unit_sw_version;
107 uint32_t unit_sub_sw_version;
108 uint32_t command_registers_base;
109 uint32_t unit_directory;
110 uint32_t unit_dependent_directory;
111 uint64_t advanced_features_csr;
112 uint64_t PIO_control_csr;
113 uint64_t SIO_control_csr;
114 uint64_t strobe_control_csr;
115 uint64_t format7_csr[DC1394_VIDEO_MODE_FORMAT7_NUM];
116 dc1394iidc_version_t iidc_version;
117 char * vendor;
118 char * model;
119 uint32_t vendor_id;
120 uint32_t model_id;
121 dc1394bool_t bmode_capable;
122 dc1394bool_t one_shot_capable;
123 dc1394bool_t multi_shot_capable;
124 dc1394bool_t can_switch_on_off;
125 dc1394bool_t has_vmode_error_status;
126 dc1394bool_t has_feature_error_status;
127 int max_mem_channel;
128
129 /* not used, for future use: */
130 uint32_t flags;
131
132} dc1394camera_t;
133
134/**
135 * A unique identifier for a functional camera unit
136 *
137 * Since a single camera can contain several functional units (think stereo cameras), the GUID is not enough to identify an IIDC camera.
138 * The unit number must also be used, hence this struct.
139 */
140typedef struct
141{
142 uint16_t unit;
143 uint64_t guid;
144} dc1394camera_id_t;
145
146/**
147 * A list of cameras
148 *
149 * Usually returned by dc1394_camera_eumerate().
150 */
151typedef struct __dc1394camera_list_t
152{
153 uint32_t num;
154 dc1394camera_id_t *ids;
155} dc1394camera_list_t;
156
157typedef struct __dc1394_t dc1394_t;
158
159#ifdef __cplusplus
160extern "C" {
161#endif
162
163/***************************************************************************
164 General system functions
165 ***************************************************************************/
166
167/**
168 * Creates a new context in which cameras can be searched and used. This should be called before using any other libdc1394 function.
169 */
170dc1394_t* dc1394_new (void);
171
172/**
173 * Liberates a context. Last function to use in your program. After this, no libdc1394 function can be used.
174 */
175void dc1394_free (dc1394_t *dc1394);
176
177/**
178 * Sets and gets the broadcast flag of a camera. If the broadcast flag is set,
179 * all devices on the bus will execute the command. Useful to sync ISO start
180 * commands or setting a bunch of cameras at the same time. Broadcast only works
181 * with identical devices (brand/model). If the devices are not identical your
182 * mileage may vary. Some cameras may not answer broadcast commands at all. Also,
183 * this only works with cameras on the SAME bus (IOW, the same port).
184 */
185dc1394error_t dc1394_camera_set_broadcast(dc1394camera_t *camera, dc1394bool_t pwr);
186dc1394error_t dc1394_camera_get_broadcast(dc1394camera_t *camera, dc1394bool_t *pwr);
187
188/**
189 * Resets the IEEE1394 bus which camera is attached to. Calling this function is
190 * "rude" to other devices because it causes them to re-enumerate on the bus and
191 * may cause a temporary disruption in their current activities. Thus, use it
192 * sparingly. Its primary use is if a program shuts down uncleanly and needs to
193 * free leftover ISO channels or bandwidth. A bus reset will free those things
194 * as a side effect.
195 */
196dc1394error_t dc1394_reset_bus(dc1394camera_t *camera);
197dc1394error_t dc1394_read_cycle_timer (dc1394camera_t * camera,
198 uint32_t * cycle_timer, uint64_t * local_time);
199
200/**
201 * Gets the IEEE 1394 node ID of the camera.
202 */
203dc1394error_t dc1394_camera_get_node(dc1394camera_t *camera, uint32_t *node,
204 uint32_t * generation);
205
206
207/***************************************************************************
208 Camera functions
209 ***************************************************************************/
210
211/**
212 * Returns the list of cameras available on the computer. If present, multiple cards will be probed
213 */
214dc1394error_t dc1394_camera_enumerate(dc1394_t *dc1394, dc1394camera_list_t **list);
215
216/**
217 * Frees the memory allocated in dc1394_enumerate_cameras for the camera list
218 */
219void dc1394_camera_free_list(dc1394camera_list_t *list);
220
221/**
222 * Create a new camera based on a GUID (Global Unique IDentifier)
223 */
224dc1394camera_t * dc1394_camera_new(dc1394_t *dc1394, uint64_t guid);
225
226/**
227 * Create a new camera based on a GUID and a unit number (for multi-unit cameras)
228 */
229dc1394camera_t * dc1394_camera_new_unit(dc1394_t *dc1394, uint64_t guid, int unit);
230
231/**
232 * Frees a camera structure
233 */
234void dc1394_camera_free(dc1394camera_t *camera);
235
236/**
237 * Print various camera information, such as GUID, vendor, model, supported IIDC specs, etc...
238 */
239dc1394error_t dc1394_camera_print_info(dc1394camera_t *camera, FILE *fd);
240
241/**
242 * Returns a pointer to a string identifying the platform for the cameras. Platforms strings are:
243 * juju, linux, macosx, windows, usb
244 */
245dc1394error_t dc1394_camera_get_platform_string(dc1394camera_t *camera, const char **platform);
246
247#ifdef __cplusplus
248}
249#endif
250
251#endif
252

source code of include/dc1394/camera.h