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. 
