1 /* This file is part of the Pangolin Project.
2  * http://github.com/stevenlovegrove/Pangolin
3  *
4  * Copyright (c) 2011 Steven Lovegrove
5  *
6  * Permission is hereby granted, free of charge, to any person
7  * obtaining a copy of this software and associated documentation
8  * files (the "Software"), to deal in the Software without
9  * restriction, including without limitation the rights to use,
10  * copy, modify, merge, publish, distribute, sublicense, and/or sell
11  * copies of the Software, and to permit persons to whom the
12  * Software is furnished to do so, subject to the following
13  * conditions:
14  *
15  * The above copyright notice and this permission notice shall be
16  * included in all copies or substantial portions of the Software.
17  *
18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
20  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
21  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
22  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
23  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25  * OTHER DEALINGS IN THE SOFTWARE.
26  */
27 
28 #pragma once
29 
30 #include <pangolin/utils/picojson.h>
31 #include <pangolin/video/stream_info.h>
32 
33 #include <memory>
34 #include <vector>
35 
36 #define PANGO_HAS_TIMING_DATA        "has_timing_data"
37 #define PANGO_HOST_RECEPTION_TIME_US "host_reception_time_us"
38 #define PANGO_CAPTURE_TIME_US        "capture_time_us"
39 #define PANGO_EXPOSURE_US            "exposure_us"
40 #define PANGO_GAMMA                  "gamma"
41 // analog gain is in linear scale and not dB
42 #define PANGO_ANALOG_GAIN            "analog_gain"
43 #define PANGO_ANALOG_BLACK_LEVEL     "analog_black_level"
44 #define PANGO_SENSOR_TEMPERATURE_C   "sensor_temperature_C"
45 #define PANGO_ESTIMATED_CENTER_CAPTURE_TIME_US "estimated_center_capture_time_us"
46 #define PANGO_JOIN_OFFSET_US         "join_offset_us"
47 #define PANGO_FRAME_COUNTER          "frame_counter"
48 
49 namespace pangolin {
50 
51 //! Interface to video capture sources
52 struct PANGOLIN_EXPORT VideoInterface
53 {
~VideoInterfaceVideoInterface54     virtual ~VideoInterface() {}
55 
56     //! Required buffer size to store all frames
57     virtual size_t SizeBytes() const = 0;
58 
59     //! Get format and dimensions of all video streams
60     virtual const std::vector<StreamInfo>& Streams() const = 0;
61 
62     //! Start Video device
63     virtual void Start() = 0;
64 
65     //! Stop Video device
66     virtual void Stop() = 0;
67 
68     //! Copy the next frame from the camera to image.
69     //! Optionally wait for a frame if one isn't ready
70     //! Returns true iff image was copied
71     virtual bool GrabNext( unsigned char* image, bool wait = true ) = 0;
72 
73     //! Copy the newest frame from the camera to image
74     //! discarding all older frames.
75     //! Optionally wait for a frame if one isn't ready
76     //! Returns true iff image was copied
77     virtual bool GrabNewest( unsigned char* image, bool wait = true ) = 0;
78 };
79 
80 //! Interface to GENICAM video capture sources
81 struct PANGOLIN_EXPORT GenicamVideoInterface
82 {
~GenicamVideoInterfaceGenicamVideoInterface83     virtual ~GenicamVideoInterface() {}
84 
85     virtual bool GetParameter(const std::string& name, std::string& result) = 0;
86 
87     virtual bool SetParameter(const std::string& name, const std::string& value) = 0;
88 
CameraCountGenicamVideoInterface89     virtual size_t CameraCount() const
90     {
91         return 1;
92     }
93 };
94 
95 struct PANGOLIN_EXPORT BufferAwareVideoInterface
96 {
~BufferAwareVideoInterfaceBufferAwareVideoInterface97     virtual ~BufferAwareVideoInterface() {}
98 
99     //! Returns number of available frames
100     virtual uint32_t AvailableFrames() const = 0;
101 
102     //! Drops N frames in the queue starting from the oldest
103     //! returns false if less than n frames arae available
104     virtual bool DropNFrames(uint32_t n) = 0;
105 };
106 
107 struct PANGOLIN_EXPORT VideoPropertiesInterface
108 {
~VideoPropertiesInterfaceVideoPropertiesInterface109     virtual ~VideoPropertiesInterface() {}
110 
111     //! Access JSON properties of device
112     virtual const picojson::value& DeviceProperties() const = 0;
113 
114     //! Access JSON properties of most recently captured frame
115     virtual const picojson::value& FrameProperties() const = 0;
116 };
117 
118 enum UvcRequestCode {
119   UVC_RC_UNDEFINED = 0x00,
120   UVC_SET_CUR = 0x01,
121   UVC_GET_CUR = 0x81,
122   UVC_GET_MIN = 0x82,
123   UVC_GET_MAX = 0x83,
124   UVC_GET_RES = 0x84,
125   UVC_GET_LEN = 0x85,
126   UVC_GET_INFO = 0x86,
127   UVC_GET_DEF = 0x87
128 };
129 
130 struct PANGOLIN_EXPORT VideoFilterInterface
131 {
~VideoFilterInterfaceVideoFilterInterface132     virtual ~VideoFilterInterface() {}
133 
134     template<typename T>
FindMatchingStreamsVideoFilterInterface135     std::vector<T*> FindMatchingStreams()
136     {
137         std::vector<T*> matches;
138         std::vector<VideoInterface*> children = InputStreams();
139         for(size_t c=0; c < children.size(); ++c) {
140             T* concrete_video = dynamic_cast<T*>(children[c]);
141             if(concrete_video) {
142                 matches.push_back(concrete_video);
143             }else{
144                 VideoFilterInterface* filter_video = dynamic_cast<VideoFilterInterface*>(children[c]);
145                 if(filter_video) {
146                     std::vector<T*> child_matches = filter_video->FindMatchingStreams<T>();
147                     matches.insert(matches.end(), child_matches.begin(), child_matches.end());
148                 }
149             }
150         }
151         return matches;
152     }
153 
154     virtual std::vector<VideoInterface*>& InputStreams() = 0;
155 };
156 
157 struct PANGOLIN_EXPORT VideoUvcInterface
158 {
~VideoUvcInterfaceVideoUvcInterface159     virtual ~VideoUvcInterface() {}
160     virtual int IoCtrl(uint8_t unit, uint8_t ctrl, unsigned char* data, int len, UvcRequestCode req_code) = 0;
161     virtual bool GetExposure(int& exp_us) = 0;
162     virtual bool SetExposure(int exp_us) = 0;
163     virtual bool GetGain(float& gain) = 0;
164     virtual bool SetGain(float gain) = 0;
165 };
166 
167 struct PANGOLIN_EXPORT VideoPlaybackInterface
168 {
~VideoPlaybackInterfaceVideoPlaybackInterface169     virtual ~VideoPlaybackInterface() {}
170 
171     /// Return monotonic id of current frame
172     /// The 'current frame' is the frame returned from the last successful call to Grab
173     virtual size_t GetCurrentFrameId() const = 0;
174 
175     /// Return total number of frames to be captured from device,
176     /// or 0 if unknown.
177     virtual size_t GetTotalFrames() const = 0;
178 
179     /// Return frameid on success, or next frame on failure
180     virtual size_t Seek(size_t frameid) = 0;
181 };
182 
183 }
184