Add a specification for how the official DeckLink driver stores interlaced frmaes.

[bmusb] / bmusb / bmusb.h

diff --git a/bmusb/bmusb.h b/bmusb/bmusb.h
index 506685dc4c6a7401d17143cdb611315981c7b187..b61b66f2e2e9e59b72b3ba42faddcbcb611cfbb8 100644 (file)
--- a/bmusb/bmusb.h
+++ b/bmusb/bmusb.h
@@ -4,6 +4,7 @@
 #include <libusb.h>
 #include <stdint.h>
 #include <atomic>
+#include <chrono>
 #include <condition_variable>
 #include <deque>
 #include <functional>
@@ -39,6 +40,14 @@ class FrameAllocator {
                // If so, <len> and <size> are still about the number of total bytes
                // so if size == 1024, there's 512 bytes in data and 512 in data2.
                bool interleaved = false;
+
+               // At what point this frame was received. Note that this marks the
+               // _end_ of the frame being received, not the beginning.
+               // Thus, if you want to measure latency, you'll also need to include
+               // the time the frame actually took to transfer (usually 1/fps,
+               // ie., the frames are typically transferred in real time).
+               std::chrono::steady_clock::time_point received_timestamp =
+                       std::chrono::steady_clock::time_point::min();
        };
 
        virtual ~FrameAllocator();
@@ -93,8 +102,10 @@ struct VideoMode {
 
 // Represents the format of an actual frame coming in.
 // Note: Frame rate is _frame_ rate, not field rate. So 1080i60 gets 30/1, _not_ 60/1.
-// "second_field_start" is only valid for interlaced modes; it signifies
-// how many lines from the very top of the frame there are before the second field
+// "second_field_start" is only valid for interlaced modes. If it is 1,
+// the two fields are actually stored interlaced (ie., every other line).
+// If not, each field is stored consecutively, and it signifies how many lines
+// from the very top of the frame there are before the second field
 // starts (so it will always be >= height/2 + extra_lines_top).
 struct VideoFormat {
        uint16_t id = 0;  // For debugging/logging only.
@@ -175,6 +186,10 @@ class BMUSBCapture : public CaptureInterface {
 
        ~BMUSBCapture() {}
 
+       // Note: Cards could be unplugged and replugged between this call and
+       // actually opening the card (in configure_card()).
+       static unsigned num_cards();
+
        std::map<uint32_t, VideoMode> get_available_video_modes() const override;
        uint32_t get_current_video_mode() const override;
        void set_video_mode(uint32_t video_mode_id) override;
@@ -251,9 +266,11 @@ class BMUSBCapture : public CaptureInterface {
        // The callback function transfers ownership. If you don't want to hold
        // on to the device given to you in the callback, you need to call
        // libusb_unref_device().
-       static void set_card_connected_callback(card_connected_callback_t callback)
+       static void set_card_connected_callback(card_connected_callback_t callback,
+                                               bool hotplug_existing_devices_arg = false)
        {
                card_connected_callback = callback;
+               hotplug_existing_devices = hotplug_existing_devices_arg;
        }
 
        // Similar to set_card_connected_callback(), with the same caveats.
@@ -299,6 +316,7 @@ class BMUSBCapture : public CaptureInterface {
        std::unique_ptr<FrameAllocator> owned_audio_frame_allocator;
        frame_callback_t frame_callback = nullptr;
        static card_connected_callback_t card_connected_callback;
+       static bool hotplug_existing_devices;
        card_disconnected_callback_t card_disconnected_callback = nullptr;
 
        std::thread dequeue_thread;