@@ -19,67 +19,154 @@ namespace PokemonAutomation{
1919
2020
2121class VideoSession
22- : public VideoFeed
23- , private VideoFrameListener
24- , private VideoSource::RenderedFrameListener
22+ : public VideoFeed // interface class the automation programs have access to to query video snapshots
23+ // and reset the video source
24+ , private VideoFrameListener // listens to incoming frames from video source
25+ , private VideoSource::RenderedFrameListener // listens to newly rendered frame from video source
2526 , private WatchdogCallback
2627{
2728public:
29+ // other classes can inherit this struct to react to state changes in the VideoSession.
30+ // You need to call VideoSession::add_state_listener() to add other classes as listeners
31+ // and remove them by VideoSession::remove_state_listener() when they are no longer needed.
32+ // When a state change happens, VideoSession will call the corresponding callback functions
33+ // in the StateListener.
2834 struct StateListener {
35+ // Called whenever the video source is initialized or reset.
36+ // This also includes when the video resolution is changed as we need to rebuild the video
37+ // source with the new resolution.
2938 virtual void post_startup (VideoSource* source){}
3039
31- // Sent before the video source shuts down. Listeners should drop their
40+ // Sent before the video source resets or shuts down. Listeners should drop their
3241 // references to the internal video source before returning.
42+ // This also includes when the video resolution is changed as we need to rebuild the video
43+ // source with the new resolution.
3344 virtual void pre_shutdown (){}
45+ // Currently not called by VideoSession yet.
3446 virtual void post_shutdown (){}
35-
47+ // Currently not called by VideoSession yet.
3648 virtual void pre_resolution_change (Resolution resolution){}
49+ // Currently not called by VideoSession yet.
3750 virtual void post_resolution_change (Resolution resolution){}
3851 };
3952
53+ // Add a state listener for it to react to state changes in the VideoSession.
54+ // When a state change happens, VideoSession will call the corresponding callback functions
55+ // in the StateListener.
4056 void add_state_listener (StateListener& listener);
57+ // Remove the state listener.
4158 void remove_state_listener (StateListener& listener);
4259
60+ // Implements VideoFeed::add_frame_listener().
61+ // Add a VideoFrameListener for it to react to incoming frames in the video source.
62+ // Whenever the video source sends a frame, VideoSession will call the callback functions
63+ // in added listeners.
4364 virtual void add_frame_listener (VideoFrameListener& listener) override ;
65+ // Implements VideoFeed::remove_frame_listener().
66+ // Remove the frame listener.
4467 virtual void remove_frame_listener (VideoFrameListener& listener) override ;
4568
4669
4770public:
4871 ~VideoSession ();
72+ // Built from a VideoSourceOption.
73+ // VideoSourceOption manages the current VideoSourceDescriptor, which are the descriptors
74+ // to build a VideoSource.
75+ // VideoSession stores a reference of the passed in VideoSourceOption to manipulate the
76+ // option according to user selection.
4977 VideoSession (Logger& logger, VideoSourceOption& option);
5078
5179 Logger& logger (){
5280 return m_logger;
5381 }
5482
83+ // Current video source descriptor.
84+ // This function is thread-safe. It has a lock to prevent concurrent calls
85+ // of other VideoSession functions.
5586 std::shared_ptr<const VideoSourceDescriptor> descriptor () const ;
5687
5788 // Warning, not thread-safe with any source changes.
5889 VideoSource* current_source (){
5990 return m_video_source.get ();
6091 }
6192
93+ // Return current resolution.
94+ // This function is thread-safe. It has a lock to prevent concurrent calls
95+ // of other VideoSession functions.
6296 Resolution current_resolution ();
97+ // Return supported resolutions.
98+ // This function is thread-safe. It has a lock to prevent concurrent calls
99+ // of other VideoSession functions.
63100 std::vector<Resolution> supported_resolutions () const ;
64101
102+ // Implements VideoFeed::snapshot() to provide a snapshot from the current video stream.
103+ // It will wait for a latest snapshot, blocking the current thread to wait for it.
104+ // This function is thread-safe. It has a lock to prevent concurrent calls
105+ // of other VideoSession functions.
65106 virtual VideoSnapshot snapshot_latest_blocking () override ;
107+ // Implements VideoFeed::snapshot_recent_nonblocking() to provide a snapshot from the
108+ // current video stream.
109+ // It will use the most recent available frame, therefore non-blocking.
110+ // This function is thread-safe. It has a lock to prevent concurrent calls
111+ // of other VideoSession functions.
66112 virtual VideoSnapshot snapshot_recent_nonblocking (WallClock min_time) override ;
67113
114+ // Implements VideoFeed::fps_source().
115+ // Returns the currently measured frames/second for the video source.
116+ // Use this for diagnostic purposes.
117+ // This function is thread-safe. It has a lock to prevent concurrent fps calls.
68118 virtual double fps_source () const override ;
119+ // Implements VideoFeed::fps_display().
120+ // Returns the currently measured frames/second for the video display thread.
121+ // Use this for diagnostic purposes.
122+ // This function is thread-safe. It has a lock to prevent concurrent fps calls.
69123 virtual double fps_display () const override ;
70124
71125
72126public:
127+ // Get current video source option
73128 void get (VideoSourceOption& option);
129+ // Set a new video source. This will close the old video source.
130+ // This equals to calling VideoSession::set_source(option.descriptor()).
131+ // Change of video source and resolution will be reflected on the internal
132+ // referenced video source option (aka the VideoSourceOption passed to the
133+ // VideoSession constructor).
134+ // The change is dispatched to the Qt main thread to execute.
74135 void set (const VideoSourceOption& option);
75-
136+ // Implements VideoFeed::reset().
137+ // Reset the current video source. This equals to close the old video source
138+ // and reopen it.
139+ // This may also change the internal referenced video source option (aka the
140+ // VideoSourceOption passed to the VideoSession constructor).
141+ // The change is dispatched to the Qt main thread to execute.
76142 virtual void reset () override ;
143+ // Set a new video source. This will close the old video source.
144+ // Change of video source and resolution will be reflected on the internal
145+ // referenced video source option (aka the VideoSourceOption passed to the
146+ // VideoSession constructor).
147+ // The change is dispatched to the Qt main thread to execute.
77148 void set_source (const std::shared_ptr<VideoSourceDescriptor>& device);
149+ // Change video resolution.
150+ // This will trigger a video source reset.
151+ // Change of resolution will be reflected on the internal referenced video
152+ // source option (aka the VideoSourceOption passed to the VideoSession
153+ // constructor).
154+ // The change is dispatched to the Qt main thread to execute.
78155 void set_resolution (Resolution resolution);
79156
80157
81158private:
159+ // Overwrites VideoFrameListener::on_frame()
160+ // When this function is called, the VideoSession will update its internal fps record
161+ // and call frame listeners added by VideoSession::add_frame_listener().
162+ // This function is thread-safe as it has a lock to prevent concurrent fps calls.
163+ // Note the lock does not protect the other frame listeners added by
164+ // VideoSession::add_frame_listener().
82165 virtual void on_frame (std::shared_ptr<const VideoFrame> frame) override ;
166+ // Overwrites VideoSource::RenderedFrameListener::on_rendered_frame()
167+ // This function is called when the video source finds a new rendered frame so
168+ // VideoSession can update its internal fps record.
169+ // This function is thread-safe as it has a lock to prevent concurrent fps calls.
83170 virtual void on_rendered_frame (WallClock timestamp) override ;
84171
85172 virtual void on_watchdog_timeout () override ;
0 commit comments