GNOME.org
 

ekiga r6333 - in trunk: . lib/engine/videooutput/common lib/engine/videooutput/skel

Author: mschneid
Date: Thu May 29 14:52:12 2008
New Revision: 6333
URL: http://svn.gnome.org/viewvc/ekiga?rev=6333&view=rev

Log:
Last commenting commit...


Modified:
   trunk/ChangeLog
   trunk/lib/engine/videooutput/common/videooutput-manager-common.h
   trunk/lib/engine/videooutput/skel/videooutput-core.h
   trunk/lib/engine/videooutput/skel/videooutput-manager.h

Modified: trunk/lib/engine/videooutput/common/videooutput-manager-common.h
==============================================================================
--- trunk/lib/engine/videooutput/common/videooutput-manager-common.h	(original)
+++ trunk/lib/engine/videooutput/common/videooutput-manager-common.h	Thu May 29 14:52:12 2008
@@ -43,8 +43,8 @@
  */
 
 
-#ifndef _VIDEODISPLAY_H_
-#define _VIDEODISPLAY_H_
+#ifndef _VIDEOOUTPUT_MANAGER_COMMON_H_
+#define _VIDEOOUTPUT_MANAGER_COMMON_H_
 
 #include "videooutput-manager.h"
 #include "runtime.h"
@@ -57,12 +57,51 @@
  * @{
  */
 
+  /** Common VideoOutputManager implementation for DX and XV
+   *
+   * This class features the shared functionality between the DX and XV output managers.
+   * The GMVideoOutputManager consists of a special thread that will do all accesses 
+   * to the dxWindow and xWindow/xvWindow classes (important for windows where all
+   * accesses to a specific window not only have to be thread-safe, but also have to
+   * come all from the same thread). The main task of that thread is to wait for triggers
+   * and then act on them, the thread itself will be active for the whole lifetime of Ekiga.
+   * A call to open() from the core will signal the thread to execute the initalize function,
+   * with open() blocking until the thread has finished its task. 
+   * The thread is now ready to accept frames, which will arrive from the core via
+   * set_frame_data(). set_frame_data will make a local copy of the image via memcpy,
+   * and signal the thread that a new remote or local frame has arrived and is ready to be
+   * displayed. Then set_frame_data() will be left, while the actual display of the frame
+   * will be performed in the thread.
+   * Once the thread has been triggered with a new frame to display, it will first call redraw
+   * for passing the frame to the graphics adaptor, and then do_sync to actually displaying it.
+   * The reason these procedures are separate has the following motivation: do_sync can block for
+   * quite some time if synv-to-vblank is active. If this would be executed in the mutex-protected
+   * redraw procedure, we would be blocking the video processing threads, possibly leading to lost packets
+   * and interfering with synchronous frame transmission.
+   * redraw() will check whether the dxWindow/xvWindow classes need to be reinitialized (e.g. we want to 
+   * switching from non-pip mode to pip mode, etc.), do that if desired and then pass pointers to the 
+   * (copied) frames to the dxWindow/xvWindow classes via display_frame() and display_pip_frames(). It will
+   * also determine if only one or both frames need to be synched to the screen.
+   * Once the device has been opened/initialized and no new frame arrives, the frames will nevertheless
+   * be updated every 250 ms.
+   * In order to close the devices, an uninit request is sent to the thread, which performes the 
+   * necessary cleanup. Like open(), close() blocks until the thread signals the cleanup has been completed.
+
+   * the frames to all of them.
+   * Before passing the first frame, start() has to be called. In order to close the video,
+   * stop() has to be called. The video output core interacts with the GUI when switching to fullscreen,
+   * when the size of the video has been changed and when a device is opened and closed.
+   */
   class GMVideoOutputManager
     : public PThread,
       public Ekiga::VideoOutputManager
   {
     PCLASSINFO(GMVideoOutputManager, PThread); 
+
   public:
+ 
+   /** See videooutput-manager.h for the API
+     */
 
     GMVideoOutputManager (Ekiga::ServiceCore & core);
 
@@ -73,10 +112,10 @@
     virtual void close ();
 
     virtual void set_frame_data (const char* data,
-                                unsigned width,
-                                unsigned height,
-                                bool local,
-                                int devices_nbr);
+                                  unsigned width,
+                                  unsigned height,
+                                  bool local,
+                                  int devices_nbr);
 
     virtual void set_display_info (const Ekiga::DisplayInfo & _display_info)
     {
@@ -91,45 +130,46 @@
     } UpdateRequired;
 
     /** The main video thread loop
-    * The video output thread loop that waits for a frame and
-    * then displays it
-    */
+     * The video output thread loop that waits for a frame and
+     * then displays it
+     */
     virtual void Main ();
   
     /** Check if the display needs to be reinitialized
-    * Returns true if the given settings require a
-    * reinitialization of the display, false
-    * otherwise.
-    */
+     * Returns true if the given settings require a
+     * reinitialization of the display, false
+     * otherwise.
+     * @return wether the display needs to be reopened.
+     */
     virtual bool frame_display_change_needed ();
   
     /** Set up the display
-    * Setup the display following the display type,
-    * picture dimensions and zoom value.
-    * Returns false in case of failure.
-    */
+     * Setup the display following the display type,
+     * picture dimensions and zoom value.
+     * Returns false in case of failure.
+     */
     virtual void setup_frame_display () = 0;
   
     /** Close the display
-    * Closes the frame display and returns false
-    * in case of failure.
-    */
+     * Closes the frame display and returns false
+     * in case of failure.
+     */
     virtual void close_frame_display () = 0;
   
     /** Display one frame
-    * Display the given frame on the correct display.
-    * The display needs to be initialized first by using 
-    * setup_frame_display(). 
-    */
+     * Display the given frame on the correct display.
+     * The display needs to be initialized first by using 
+     * setup_frame_display().
+     */
     virtual void display_frame (const char *frame,
                                 unsigned width,
                                 unsigned height) = 0;
 
-    /** Display two frames as picture-in-pictu
-    * Display the given frames as Picture in Picture.
-    * The display needs to be initialized first by using 
-    * setup_frame_display().
-    */
+    /** Display two frames as picture-in-picture
+     * Display the given frames as Picture in Picture.
+     * The display needs to be initialized first by using 
+     * setup_frame_display().
+     */
     virtual void display_pip_frames (const char *local_frame,
                                     unsigned lf_width,
                                     unsigned lf_height,
@@ -138,25 +178,31 @@
                                     unsigned rf_height) = 0;
   
     /** Draw the frame 
-    * Draw the frame to a backbuffer, do not show it yet.
-    */
+     * Draw the frame to a backbuffer, do not show it yet.
+     * @return wether the local, the remote or both frames need to be synced to the screen.
+     */
     virtual UpdateRequired redraw ();
-  
-    
+
     /** Sync the output of the frame
-    * Bring the frame to the screen. May block for 
-    * a while if sync-to-vblank is active
-    */
+     * Bring the frame to the screen. May block for 
+     * a while if sync-to-vblank is active
+     * @param sync_required  wether the local, the remote or both frames need to be synced to the screen.
+     */
     virtual void sync(UpdateRequired sync_required) = 0;
-  
+
     /** Initialises the display
-    */
+     */
     virtual void init ();
   
     /** Uninitialises the display
-    */
+     */
     virtual void uninit ();
 
+    /** Update the GUI about the new device state
+     * Triggers a device_closed and device_opened callback.
+     * Used to inform the GUI that the second video signal 
+     * has arrived for the first time 
+     */
     void update_gui_device();
 
     virtual void get_display_info (Ekiga::DisplayInfo & _display_info) {
@@ -217,4 +263,4 @@
  * @}
  */
 
-#endif /* VIDEODISPLAY */
+#endif /* _VIDEOOUTPUT_MANAGER_COMMON_H_ */

Modified: trunk/lib/engine/videooutput/skel/videooutput-core.h
==============================================================================
--- trunk/lib/engine/videooutput/skel/videooutput-core.h	(original)
+++ trunk/lib/engine/videooutput/skel/videooutput-core.h	Thu May 29 14:52:12 2008
@@ -29,7 +29,7 @@
  *                         ------------------------------------------
  *   begin                : written in 2007 by Matthias Schneider
  *   copyright            : (c) 2007 by Matthias Schneider
- *   description          : declaration of the interface of a videooutput core.
+ *   description          : Declaration of the interface of a videooutput core.
  *                          A videooutput core manages VideoOutputManagers.
  *
  */
@@ -62,6 +62,12 @@
   class VideoOutputManager;
 
   /** Core object for the video display support
+   *
+   * The VideoOutputCore will control the different VideoOutputManagers and pass pointers to 
+   * the frames to all of them.
+   * Before passing the first frame, start() has to be called. In order to close the video,
+   * stop() has to be called. The video output core interacts with the GUI when switching to fullscreen,
+   * when the size of the video has been changed and when a device is opened and closed.
    */
   class VideoOutputCore
     : public Service
@@ -128,7 +134,14 @@
 
       /** Display a single frame
        * Pass the pointer to the frame to all registered mangers.
+       * The video output must have been started before.
+       * @param data a pointer to the buffer with the data to be written. It will not be freed.
+       * @param width the width in pixels of the frame to be written.
+       * @param height the height in pixels of the frame to be written.
+       * @param local true if the frame is a frame of the local video source, false if it is from the remote end.
+       * @param devices_nbr 1 if only local or remote device has been opened, 2 if both have been opened.
        */
+
       void set_frame_data (const char *data,
                            unsigned width,
                            unsigned height,
@@ -149,7 +162,7 @@
       };
 
 
-      /*** Display Related Signals ***/
+      /*** Signals ***/
 
       /** See videooutput-manager.h for the API
        */

Modified: trunk/lib/engine/videooutput/skel/videooutput-manager.h
==============================================================================
--- trunk/lib/engine/videooutput/skel/videooutput-manager.h	(original)
+++ trunk/lib/engine/videooutput/skel/videooutput-manager.h	Thu May 29 14:52:12 2008
@@ -52,7 +52,6 @@
    *
    * Each VideoOutputManager represents a sink for video frames.
    * A VideoOutputManager can display the video signal, record single frames or record video signal.
-   * The VideoOutputCore will control the different managers and pass the frames to all of them.
    */
   class VideoOutputManager
     {
@@ -85,7 +84,7 @@
        * @param width the width in pixels of the frame to be written.
        * @param height the height in pixels of the frame to be written.
        * @param local true if the frame is a frame of the local video source, false if it is from the remote end.
-       * @param devices_nbr 1 if only local or remote device has been opened, 2 if both have been opened. //FIXME
+       * @param devices_nbr 1 if only local or remote device has been opened, 2 if both have been opened.
        */
       virtual void set_frame_data (const char *data,
                                    unsigned width,
@@ -99,7 +98,10 @@
       /*** API to act on VideoOutputDevice events ***/
 
       /** This signal is emitted when a video output device is opened.
-       * @param hw_accel_status actual hardware acceleration support active on the video output device opened).
+       * @param videooutput_accel actual hardware acceleration support active on the video output device opened.
+       * @param mode the mode in which the device was initially opened.
+       * @param zoom the initial zoom level when de device was opened.
+       * @param both_streams if a frame from both local and remote stream has been received.
        */
       sigc::signal<void, VideoOutputAccel, VideoOutputMode, unsigned, bool> device_opened;
 
@@ -107,7 +109,23 @@
        */
       sigc::signal<void> device_closed;
 
+      /** This signal is emitted when a manager switches autonomously into or out of fullscreen mode.
+       * Some managers like DX and XV  allow the user to switch between FS
+       * by pressing a key or clicking a mouse button on top of the video. In order to
+       * This signal is called whenever the size of the widget carrying the video signal
+       * has to be changed. This happens when the displayed video changes in resolution
+       * or when it is being zoomed in or out.
+       * @param toggle VO_FS_ON or VO_FS_OFF depending on whether FS was activated or deactivated.
+       */
       sigc::signal<void, VideoOutputFSToggle> fullscreen_mode_changed;
+
+      /** This signal is emitted the video output size has changed.
+       * This signal is called whenever the size of the widget carrying the video signal
+       * has to be changed. This happens when the displayed video changes in resolution
+       * or when it is being zoomed in or out.
+       * @param width the new width of the widget.
+       * @param height the new height of the widget.
+       */
       sigc::signal<void, unsigned, unsigned> size_changed;
 
   protected:
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]