[Gnash-commit] gnash ChangeLog server/sprite_instance.h

[Sandro Santilli]

CVSROOT:        /sources/gnash
Module name:    gnash
Changes by:     Sandro Santilli <strk>  07/05/11 04:47:39

Modified files:
        .              : ChangeLog 
        server         : sprite_instance.h 

Log message:
                * server/sprite_instance.h: improved documentation for the
                  add_display_object() method. I think this is where we're going
                  to add a TimelineInfo record (see Timeline Control page on the
                  wiki).

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnash/ChangeLog?cvsroot=gnash&r1=1.3160&r2=1.3161
http://cvs.savannah.gnu.org/viewcvs/gnash/server/sprite_instance.h?cvsroot=gnash&r1=1.106&r2=1.107

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/gnash/gnash/ChangeLog,v
retrieving revision 1.3160
retrieving revision 1.3161
diff -u -b -r1.3160 -r1.3161
--- ChangeLog   11 May 2007 04:21:20 -0000      1.3160
+++ ChangeLog   11 May 2007 04:47:39 -0000      1.3161
@@ -1,3 +1,10 @@
+2007-05-11 Sandro Santilli <address@hidden>
+
+       * server/sprite_instance.h: improved documentation for the
+         add_display_object() method. I think this is where we're going
+         to add a TimelineInfo record (see Timeline Control page on the
+         wiki).
+
 2007-05-11 Zou Lunkai <address@hidden>
 
        * testsuite/misc-ming.all/: displaylist_depths_test6.c:

Index: server/sprite_instance.h
===================================================================
RCS file: /sources/gnash/gnash/server/sprite_instance.h,v
retrieving revision 1.106
retrieving revision 1.107
diff -u -b -r1.106 -r1.107
--- server/sprite_instance.h    10 May 2007 13:14:42 -0000      1.106
+++ server/sprite_instance.h    11 May 2007 04:47:39 -0000      1.107
@@ -327,8 +327,27 @@
        boost::intrusive_ptr<character> add_textfield(const std::string& name,
                        int depth, float x, float y, float width, float height);
 
-       /// Add an object to the DisplayList. 
+       /// Place a character or mask to the DisplayList (make a timeline 
instance) 
        //
+       /// This method instantiates the given character definition 
(character_id)
+       /// and places it on the stage at the given depth using the specified
+       /// parameters for name, position, color, ratio(?) and clipping depth 
(if any).
+       ///
+       /// If the specified depth is already occupied by an instance of the 
same
+       /// character (character_id), the existing instance will be transformed 
using
+       /// move_display_object() instead.
+       ///
+       /// If the specified depth is already occupied by an instance of a 
different
+       /// character (including any dynamically-created instance), the 
behaviour is
+       /// controlled by the replace_if_depth_is_occupied parameter. If false, 
this
+       /// call will result in a no-op. If true, the previously existing 
character
+       /// will be replaced by the new one, with unload() method invoked on the
+       /// removed character.
+       ///
+       /// Any successful new placement triggers invokation of the newly 
created
+       /// instance's LOAD event.
+       ///
+       ///
        /// @param character_id
        ///     The ID of the character to be added.
        ///     It will be seeked in the CharacterDictionary
@@ -345,10 +364,10 @@
        ///     The depth to assign to the newly created instance.
        ///
        /// @param replace_if_depth_is_occupied
-       ///     If true, any existing character at the given depth will be
-       ///     replaced by the new one. If false, the presence of a character
-       ///     at the target depth will make this call a no-op, and NULL
-       ///     will be returned.
+       ///     This parameter control behaviour in case an existing instance 
is found at
+       ///     the given depth but is NOT an instance of the given 
character_id.
+       ///     In this case: if this paremeter is true, the old instance will 
be replaced by
+       ///     the new one, otherwise nothing happens and this function 
returns NULL.
        ///
        /// @param color_transform
        ///     The color transform to apply to the newly created instance.
@@ -359,6 +378,10 @@
        /// @param ratio
        ///
        /// @param clip_depth
+       ///     If != character::noClipDepthValue, mark the created instance
+       ///     as a clipping layer. The shape of the placed character will be
+       ///     used as a mask for all higher depths up to this value.
+       ///     TODO: assert(clip_depth > depth) ?
        ///
        /// @return 
        ///     A pointer to the character being added or NULL