[Gnash-commit] gnash ChangeLog backend/render_handler.h gui/gu...

[Udo Giacomozzi]

CVSROOT:        /cvsroot/gnash
Module name:    gnash
Changes by:     Udo Giacomozzi <udog>   06/11/07 13:09:38

Modified files:
        .              : ChangeLog 
        backend        : render_handler.h 
        gui            : gui.cpp gui.h 

Log message:
        Added comments

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnash/ChangeLog?cvsroot=gnash&r1=1.1544&r2=1.1545
http://cvs.savannah.gnu.org/viewcvs/gnash/backend/render_handler.h?cvsroot=gnash&r1=1.20&r2=1.21
http://cvs.savannah.gnu.org/viewcvs/gnash/gui/gui.cpp?cvsroot=gnash&r1=1.45&r2=1.46
http://cvs.savannah.gnu.org/viewcvs/gnash/gui/gui.h?cvsroot=gnash&r1=1.36&r2=1.37

Patches:
Index: ChangeLog
===================================================================
RCS file: /cvsroot/gnash/gnash/ChangeLog,v
retrieving revision 1.1544
retrieving revision 1.1545
diff -u -b -r1.1544 -r1.1545
--- ChangeLog   7 Nov 2006 11:55:01 -0000       1.1544
+++ ChangeLog   7 Nov 2006 13:09:37 -0000       1.1545
@@ -1,3 +1,8 @@
+2006-11-06 Udo Giacomozzi <address@hidden>
+       
+       * backend/render_handler.h, gui/gui.cpp, gui/gui.h:
+       Further described invalidated bounds
+
 2006-11-07 Sandro Santilli <address@hidden>
 
        * server/action.cpp, server/swf/ASHandlers.cpp: turn

Index: backend/render_handler.h
===================================================================
RCS file: /cvsroot/gnash/gnash/backend/render_handler.h,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -b -r1.20 -r1.21
--- backend/render_handler.h    2 Nov 2006 13:59:37 -0000       1.20
+++ backend/render_handler.h    7 Nov 2006 13:09:38 -0000       1.21
@@ -17,7 +17,7 @@
 // 
 //
 
-/* $Id: render_handler.h,v 1.20 2006/11/02 13:59:37 udog Exp $ */
+/* $Id: render_handler.h,v 1.21 2006/11/07 13:09:38 udog Exp $ */
 
 #ifndef RENDER_HANDLER_H
 #define RENDER_HANDLER_H
@@ -145,6 +145,10 @@
 /// the renderer to do so (for example, to save time during blitting).
 /// The GUI can also completely ignore the region information. 
 /// 
+/// It's also importanto to note that the bounds passed to the GUI are just
+/// a hint and the GUI /is/ allowed to further process and alter the 
information
+/// in any way.
+/// 
 /// As for the integer/float discussion: I used rect (floats) because all
 /// the bounds calculation involves floats anyway and so it's probably
 /// faster than converting between ints and floats all the way.
@@ -244,10 +248,14 @@
        virtual YUV_video* create_YUV_video(int width, int height) = 0; 
        virtual void delete_YUV_video(YUV_video* yuv) = 0;
 
-       /// Sets the update region (called prior to begin_display).
+       /// Sets the update region (called prior to begin_display). The 
renderer 
+       /// might do clipping and leave the region outside these bounds 
unchanged,
+       /// but he is allowed to change them if that makes sense. After 
rendering
+       /// a frame the area outside the invalidated region can be undefined 
and 
+       /// is not used. 
        //
        /// It is not required for all renderers.
-       /// Parameters are world coordinates.
+       /// Parameters are world coordinates (TWIPS).
        ///
        /// For more info see page \ref region_update.
        ///

Index: gui/gui.cpp
===================================================================
RCS file: /cvsroot/gnash/gnash/gui/gui.cpp,v
retrieving revision 1.45
retrieving revision 1.46
diff -u -b -r1.45 -r1.46
--- gui/gui.cpp 3 Nov 2006 15:56:27 -0000       1.45
+++ gui/gui.cpp 7 Nov 2006 13:09:38 -0000       1.46
@@ -234,10 +234,12 @@
        if (redraw_flag) _redraw_flag=false;
 
        // Find out the surrounding frame of all characters which
-       // have been updated.
+       // have been updated. This just checks what region of the stage has 
changed
+       // due to ActionScript code, the timeline or user events. The GUI can 
still
+  // choose to render a different part of the stage. 
        m->get_invalidated_bounds(&changed_bounds, false);
 
-       if (redraw_flag)
+       if (redraw_flag)     // TODO: Remove this and want_redraw to avoid 
confusion!?
        {
                // TODO: use more meaningful ordinate values ?
                changed_bounds = rect(-1e10f, -1e10f, +1e10f, +1e10f);
@@ -248,11 +250,16 @@
 
        if ( ! changed_bounds.is_null() )       //vv
        {
-               // Tell the GUI that we only need to update this region
-               // (it may ignore this information)
+               // Tell the GUI(!) that we only need to update this region. 
Note the GUI can
+               // do whatever it wants with this information. It may simply 
ignore the 
+               // bounds (which will normally lead into a complete redraw), or 
it may
+               // extend or shrink the bounds as it likes. So, by calling 
+    // set_invalidated_bounds we have no guarantee that only this part of the
+    // stage is rendered again.
                set_invalidated_region(changed_bounds);
 
-               // render the frame      
+               // render the frame. It's up to the GUI/renderer combination to 
do any
+    // clipping, if desired.     
                m->display();
   
                // show invalidated region using a red rectangle

Index: gui/gui.h
===================================================================
RCS file: /cvsroot/gnash/gnash/gui/gui.h,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -b -r1.36 -r1.37
--- gui/gui.h   5 Nov 2006 23:10:43 -0000       1.36
+++ gui/gui.h   7 Nov 2006 13:09:38 -0000       1.37
@@ -104,9 +104,13 @@
     /// Register event handlers.
     virtual bool setupEvents() = 0;
     
-    /// Defines the region on the stage that needs to be redrawn/updated.
-    //
-    /// Changes outside that region are unnecessary but not disallowed.
+    /// Gives the GUI a *hint* which region of the stage should be redrawn.
+    /// There is *no* restriction what the GUI might do with these 
coordinates. 
+    /// Normally the GUI forwards the information to the renderer so that
+    /// it avoids rendering regions that did not change anyway. The GUI can
+    /// also alter the bounds before passing them to the renderer and it's
+    /// absolutely legal for the GUI to simply ignore the call.
+    ///
     /// Coordinates are in TWIPS!
     ///
     /// Note this information is given to the GUI and not directly to the 
@@ -118,8 +122,7 @@
       // does not need to be implemented (optional feature),
       // but still needs to be available.
       // Why "rect" (floats)? Because the gui does not really
-      // know about the
-      // scale the renderer currently uses... 
+      // know about the scale the renderer currently uses... 
     } 
 
     /// Asks the GUI handler if the next frame should be redrawn completely.