2009-11-08 Chris Toshok <toshok@ximian.com>

[moon.git] / NOTES

This contains a minimal runtime in C for trying out some ideas for the
Moonlight binding.   It is not designed to be our final implementation. 

The C++ file here was merely to test Agg, but the public API is pure C
and without agg (which is currently disabled due to laziness on my
part) it should build with a C compiler

This is not likely the final version of this code.

* Use of C++

        C++ is only used for the class hierarchy and API entry points
        are not exposed as C++ member methods but instead they are exposed
        as regular C-callable methods that have access to the C++
        public fields or any other public inline declarations.

        Object creation uses the gtk-like naming scheme for constructors:

                ClassName *class_name_new ();

        All classes that inherit from DependencyObject have to be constructable,
        even though their C# counterparts are abstract, because their C# 
        counterparts still have a public constructor (there can be derived 
        classes with no corresponding unmanaged representation, and we have
        to use the C class of the abstract C# class).

        Destruction of these objects is also done in the C-like way:

                class_name_destroy (ClassName *object)

        This is done so that our public API can be easily P/Invoked
        from the managed side. 

        Notice that the majority of property setters and getters for
        DependencyProperties will be done through two calls:

                dependency_object_set_value
                dependency_object_get_value

        So there is no need to bind much more than that for
        getting/setting, unless those setting/getting are useful to
        develop/debug the C++ code.

* Base and Reference Counting

        Base objects use a system similar to Gtk's object reference
        counting.  Objets are born in "floating" mode, which when
        first refed turn into "refcount = 1".

        This allows code like this:

                shape_set_brush (rect, new SolidBrush ());

        Without having to manually decrement the reference count for 
        the SolidBrush immediately following it.

        When an object is exposed to the managed world, it must be
        referenced.

* Items

        Items for the base class for all the objects that are rendered,
        items contain a bounding box (double x1, y1, x2, y2) which must
        be updated when the virtual method ->getbounds is called.

        In addition each item can contain an affine transformation,
        the code tracks the user set values as well as an absolute
        affine transformation.
        
        The encoding of the affine transformation is done with a
        "double *" which, if not-NULL should point to six doubles in 
        the format expected by cairo_matrix_t (and libart).

        The double [6] can be casted into a cairo_matrix_t, which is why
        this appers like that in the source code.  This was done in
        case we want to switch to AGG.

* Class Hierarchy

        I tried to simplify the class hierarchy from the one found in:

                www.mono-project.com/WPFNotes

        We will likely have to introudce some of the same classes to mirror
        the hierarchy as my over-simplification left a few things out.

* Lighter objects

        Currently the code stores all the properties in the classes,
        this needs to be changed to use a DependencyProperty-like system,
        which basically makes objects lightweight.

        All objects basically have a hashtable:

                Hashtable properties;

        And properties become for example:

                static default_value_for_x;

                object_get_x ()
                {
                        if (properties.Contains ("x"))
                                return properties ["x"];
                        else
                                return default_value_for_x;
                }

        This ensures that objects with a few hundred exposed
        properties (that are barely changed) do not consume a lot of memory.

* Caching commonly used values in DepdendencyObjects

        For commonly used fields that might live in a dependency property, it 
        might be best to keep the data on the object itself.    The only
        way of doing this, and still support the DependencyObject system is
        to use the class instance fields as a cache.

        To do this, you can cache the values in the instance variable of the
        class and  monitor changes to the property overriding the OnPropertyChange
        method.

        The OnPropertyChange method is called after the actual value has changed
        so you must update your internally cached version of it with the value
        in the dependencyproperty.

* DependencyObject::On*Changed methods

        The following are guidelines for the different methods used in
        property change notifications.

        OnPropertyChanged:

                To perform operations when a property defined on your class is
                changed, you must override this method.


                void
                MySubclass::OnPropertyChanged (DependencyProperty *prop)
                {
                        if (prop->type != Type::MYSUBCLASSTYPE) {
                                ParentClass::OnPropertyChanged (prop);
                                return;
                        }

                        if (prop == MySubclass::FirstProperty) {
                                /* do stuff */
                        }
                        else if (prop == MySubclass::FirstProperty) {
                                /* do different stuff stuff */
                        }
                        else if ...

                        .
                        .
                        .
                }

                you don't need to explicitly call NotifyAttacheesOfPropertyChange.
                this is done for you.



        OnSubPropertyChanged:

                if your class has a property that is a DependencyObject (say a
                property of type Brush or Transform), you should override this
                method to catch changes to that object's properties.


                It should look like this:


                void
                MySubclass::OnSubPropertyChanged (DependencyProperty *prop, DependencyProperty *subprop)
                {
                        if (prop == MySubclass::FirstProperty) {
                                /* do this whenever any part of the value of FirstProperty changes */
                        }
                        else if (prop == MySubclass::SecondProperty &&
                                 subprop == SecondClass::Property) {

                                /* do this whenever the property "SecondClass::Property" changes on
                                   the object stored in our MySubclass::SecondProperty property */
                        }
                        .
                        .
                        .
                        else
                                ParentClass::OnSubPropertyChanged (prop, subprop);
                }

        OnChildPropertyChanged:

                if your class defines "attached" properties, like the Canvas
                class's Left and Top, you must override this method to add
                support for them


                It should look like this:

                bool
                MySubclass::OnChildPropertyChanged (DependencyProperty *prop, DependencyObject *child)
                {
                        if (prop == MySubclass::FirstAttachedProperty) {
                                // do something when "child"'s value for FirstAttachedProperty changes

                                return true;
                        }
                        else if (prop == MySubclass::SecondAttachedProperty) {
                                // do something when "child"'s value for SecondAttachedProperty changes

                                return true;
                        }

                        return false;
                }


        OnCollectionChanged:

                if your class has any collection properties, it must override
                this method to be able to deal with changes to elements of the
                collection.


                It should look like this:

                void
                MySubclass::OnCollectionChanged (Collection *col, CollectionChangeType type,
                                                 DependencyObject *obj, DependencyProperty *prop)
                {
                        if (col == GetValue (MySubclass::MyCollectionProperty)->AsMyCollection()) {
                                /* do something when the collection MyCollectionProperty changes in any way */
                        }
                        else if (type == CollectionChangeItemRemoved &&
                                 col == ...) {
                                /* do something only when an item is removed */
                        }
                        .
                        .
                        .
                        else
                                ParentClass::OnCollectionChanged (col, type, obj, prop);
                }

* Video

        The video stuff is *incredibly* early at this point and
        requires an FFmpeg installation from SVN (the only available
        one). 

        Currently this is very basic, it merely does video frame decoding, and
        makes no attempt to keep track of the clock (as it should) nor to do any
        kind of audio output (yet).

        The video is also busted, I do not know why, but the "decoded"
        video is incorrect, it has the wrong colors.

        The video thread currently sends "messages" to the main thread
        to do two things: 

                * To inform the main thread that the video has been
                  initialized and that the video bounds can be computed.

                * To request an invalidate (when a new frame is ready)

        The invalidate request could *perhaps* be done by taking the
        Gdk lock and issuing the invalidate directly.

        The issue is that we might need to lock also on the
        (Item *) structures in case the user-code is making changes to the
        affine transform and hence the bounding box as we are trying
        to access those from the Gdk lock. 

* Rendering

        Currently we are using Cairo and an xlib surface that points to
        a pixmap to do the rendering, but this has proven for some users
        to be slower than the software rendering that we were using.

        The software rendering used to use gdk_draw_pixbuf, which had
        one problem: gdk_draw_pixbuf expects the data to be in a slightly
        different ARGB format than the ones that Cairo and libswscale 
        support.

        To support software rendering we should re-implement this code and
        and add support for byte swapping to the format required by gdk_draw_pixbuf

* Demo

        The demo has a couple of hardcoded videos for now, you must
        edit the filenames hardcoded inside of it.

        Sometimes you might also have to define VIDEO_DEMO at the top,
        as every once in a while I will disable them.

        There is currently a race condition in the rendering engine,
        I have not yet been able to find out what it is, so sometimes
        the engine will not display anything, restart it in those cases.

        You will notice some rectangles painting, thats where the
        video should be, it is also not clear why those move

* Mozilla plugin

        To browser plugin installation, use:

                make

                make install-plugin

        It will install all need stuff to your local plugin folder at
        ~/.mozilla/plugins. In plugin/test folder theres a file 
        index.html that can be use to see plugin in action. Since plugin
        is under development, if you have any problems with it try to 
        execute your browser from command line and check log messsages, 
        this information can be useful to help us fix the problem.

        If you debug this, you will run into:


                Program received signal SIGSEGV, Segmentation fault.
                [Switching to Thread 1088688944 (LWP 9517)]
                0x43827037 in GC_find_limit (p=0x89cb1ec "", up=0) at os_dep.c:813
                813                     GC_noop1((word)(*result));
                
        This is OK and is perfectly harmless, type "cont" to
        resume execution.

* Mozilla plugin installer (user plugin)

        To build a mozilla plugin installer (XPI) configure with
        --enable-user-plugin and build as above.  This modifies the libraries
        to open the libraries it needs from ~/.mozilla/plugins and builds an
        unsigned .xpi file which you may use to install the plugin in your
        browser.

        To install the plugin open the plugin/novell-moonlight.xpi with your
        mozilla-based browser and follow the prompts.

* Some undocumented Silverlight features and their Moonlight implementation details 
  are listed on:

        http://www.mono-project.com/MoonlightQuirks
        
----------------------------------------------------------------------------------
Issues
----------------------------------------------------------------------------------

* Reference Counting

        1. Value() holds a ref to its contained dependency
           object. This means we don't have to do anything special for
           anything stored in a DP.
        
        2. Collections hold a ref to their constituents.

        3. If you *must* cache an DO pointer in an instance field, you
           must ref/unref it properly.  But really, you shouldn't need
           to cache it.

* Value and Kinds

        I wonder if we should move instead to use as keys not the enum
        values that we have, but instead the void * to the managed "Type"
        as the key for the various types.

        That would further unify the managed and native code

* XAML Parsing

        We are going to need a way of flagging classes as abstract to
        avoid instantiating those from XAML.

        Maybe a flag in UIElement::flags

* Cairo Considerations

        surface_clear: should we use something like this?

        cairo_set_source_rgba (s->cairo, 1.0, 1.0, 1.0, 1.0);
        cairo_set_operator (s->cairo, CAIRO_OPERATOR_SOURCE);
        cairo_paint (s->cairo);

        But with a rectangle to set the region to clear?

        Missing features:

        - cairo line's cap (cairo_[g|s]et_line_cap) are identical for 
        both start and end. SL supports different line cap style on 
        both (StrokeStartCap and StrokeEndCap)

        - cairo dashes (cairo_set_dash) do not support line cap. SL
        support this (StrokeDashCap).

        - cairo gradient brushes, like radial, don't behave the same
        if the center point is outside the circle

        - cairo currently doesn't have an implementation of the
        documented cairo_stroke_to_path which is needed to be able
        to render the ink's strokes outline color.

* Rendering Considerations

        Currently we draw in an off-screen cairo surface when the
        widget is not realized, seems like a waste of power, but its    
        used for bounding box computations.

        Should we have a if (!realized) return in those places and
        merely have a single cairo context that we paint to?

* Ink

        It seems that Silverlight ignores pressure information when
        rendering static ink.

        We currently hack around the OutlineColor (draw Outline then
        draw inner color on top of it) so we can use a big pen (line
        width) to draw strokes (otherwise we would need 
        cairo_stroke_to_path).

        We don't (yet) support different Height/Width but that could
        be added using a transform (and adjusting the coordinates).

* Optimization Ideas

        The GSList that we use to keep track of attached objects could
        actually be abused to store the values there, we can use the
        bottom bit to track this info:

                If bottom bit is set, the pointer to the value stored
                there is:

                        ->value & ~1

                If the bit is not set, we got a regular pointer to a
                GSList.


* Adding a new class

        There are several things you must do when adding a new
        class for use in moon.
        
        a)  If the class inherits from DependencyObject, you have to:
                1. Override GetObjectType() to return that type.
                2. Execute typegen.sh.

        b)  If the class does NOT inherit from DependencyObject, you have to:
                1.  Add a Value::Kind entry for it (in value.h.in).
                2.  add line(s) to types_init_first in type.cpp.in registering the
                    type and its parent type (if there is one.)
                3.  If it's used in the C++ code, add an As$TYPE method in
                    value.h.in and an implementation of it to runtime.cpp
                4.  Execute typegen.sh.

* TimeManager::Instance::Start

        Currently we call this in runtime_init(), it should be further delayed until
        we determine that we have a storyboard to play, otherwise we are wasting cycles.