walkthrough.txt

彩信浏览器

.. _walkthrough-section:

How does the AmbulantPlayer play a SMIL document?
=================================================

Last updated for Ambulant version 1.8.

Introduction
------------

This section attempts to explain the basic structure of the Ambulant Player by
loosely explaining what happens when you run it and play a document.

There is an informal `overall structure diagram`_ that tries to put the whole
design in one pretty picture and may be worthwhile to keep handy while reading
this document.

The main program is platform dependent and GUI-toolkit dependent. The details
of this main program are skipped here (and they can actually vary quite a bit
for the platforms we support), but at some point after the program has started
the GUI is put on the screen, with the usual set of menus for Open, Play, etc.

Opening a document
------------------

When the user selects Open (or Open URL, or double-clicks or drags a document)
we need to get the data, parse the document into a DOM tree and create a
player to play that DOM tree. In addition, we need to tell the player how
it can obtain media data, create windows, and more.

Most player implementations (the Windows player is an exception) have a
class with a name like ``mainloop`` to handle this. Such a mainloop is created
per SMIL document. Actually, Ambulant provides a class ``gui_player`` which
can be used as a skeleton for such a mainloop class, handling most of the bookkeeping
sketched below.

The mainloop object should first create the various factories
and populate them:

- A ``window_factory`` is usually implemented by the main program itself. The
  player will call this when it needs a window. Usually the first request to
  create a window will actually return the document window (after resizing to
  the appropriate size).

- A ``global_playable_factory`` is created. This is the object the player will
  use to create renderers for the various media types. The global factory
  is filled with the various renderers this ambulant player supports. In effect,
  this is the step where you get to decide how various media are rendered.

- A ``datasource_factory`` is created and filled with the factory functions that
  will create datasources for audio, video or other, raw, data such as text.
  The factory functions that are added to the datasource_factory partially
  determine how data is retrieved over the net, which protocols and formats
  are supported and such. Partially, because some media items (audio and video,
  notably) may be rendered by simply passing the URL to some underlying media
  infrastructure such as DirectX or QuickTime.
  
- A ``parser_factory`` is created and populated with the default XML parser.

- A ``node_factory`` used to create the DOM tree nodes.

Next ``init_plugins`` is called, and if the
architecture supports dynamically loadable plugins we get the ``plugin_engine``
singleton object and ask it to load the plugins. This will search the plugin
directories for dynamic objects with the correct naming convention, load them,
and call their ``initialize`` routine. The ``factories`` object (another interface
usually implemented by ``gui_player``) and ``gui_player`` object are passed to
the ``initialize`` routine, so the plugin itself can register any factories
it wants. Additionally, a plugin could modify the ``gui_player`` to allow
it to get controllater, during playback of the document.

The next step is to create the DOM tree. One way to do this is to use
``read_data_from_url`` to read the data from the document, and then pass this
data to ``document::create_from_string``. This will return a ``document`` object.
This object contains the DOM tree itself (implemented by the ``node`` object) and
some context information (XML namespace information, original URL for resolving
relative URLs used in the document, a mapping from XML IDs to node objects). There is a
convenience function ``create_document`` that does all this for you.

The final step is to create a ``player`` object. This is done through
``create_smil2_player``, passing the ``document``, the ``factories`` and one
final object, ``embedder``. This object is again implemented by the main program,
and implements a small number of auxiliary functions, such as opening an
external webbrowser or opening a new SMIL document.

Creating the player
-------------------

When the ``smil_player`` object is created it gets the ``document``, ``factories``
and ``embedder`` arguments. It now needs to create its internal data structures
to facilitate playback later on:

- A ``timer`` and ``event_processor`` are created. The timer is the master clock
  for the presentation, and the event processor is a runqueue object that is
  used for low-level scheduling. Whenever the high-level scheduler wants some
  code to be executed it will add an ``event`` to the ``event_processor``, possibly
  with a timeout and a priority. The event processor runs in a separate thread,
  waits for events in its runqueue to become elegible and then runs them.
  This mechanism is the underlying engine that makes the whole player work,
  anything that needs to wait doesn't do so inline but uses the event processor
  to get a callback at a later stage: the scheduler, renderers needing input data,
  etc.
  
- A ``layout_manager`` is created, which will be used to find where media
  items should be displayed. The ``smil_layout_manager`` reads the ``<layout>`` section
  of the DOM tree and builds a parallel layout tree (which also contains information
  on some of the body media nodes, the ones that have layout information themselves)
  of ``region_node`` objects. Then this tree of ``region_node`` objects is
  converted into a tree of ``surface_template`` objects. To create toplevel windows
  the ``new_topsurface`` method of the window factory is used, and subregions are
  created using the ``new_subsurface`` method of their parent ``surface_template``.
  The layout manager also contains mappings to be able to get from a ``node`` to the
  corresponding ``region_node`` to the ``surface_template``, and this will be used
  during playback to play media items in the correct location.
  
- A ``timegraph`` is created. This is the internal representation of the ``<body>``
  part of the DOM tree that will be used to play back the document. In addition 
  a ``scheduler`` is created, which will interpret the data in the ``timegraph``.

Starting playback
-----------------

When the user selects Play we call the ``start`` method of the ``player`` object.
This will invoke ``start`` on the scheduler. This will start playing the root
node of the tree. The scheduler will now do all the SMIL 2 magic, whereby events
such as the root node being played causes other nodes to become playable, etc.

At some point a media item needs to be rendered. The scheduler calls the ``new_playable``
method from the ``global_playable_factory``. This will pass the DOM ``node`` to the
various factories until one signals it can create a ``playable`` for the object.
In addition, if the playable has a renderer (which is true for most media objects,
but not for things like SMIL animations) we also obtain the ``surface`` on which
the media item should be renderered, through the ``layout_manager``. We then tell
the renderer which surface to use.

Soon afterwards the ``start`` method of the playable is called to start playback.
An average renderer will need to obtain data from some URL. It will do this by creating
a ``datasource`` for the document through the ``datasource_factory`` object. Every time
the renderer wants more data it calls the ``start`` method of the datasource passing
a callback routine. Whever data is available the datasource will schedule a call
to the callback routine, through the event processor. When the renderer has enough
information to start drawing it will not actually draw immedeately, but it will
send a ``need_redraw`` call to its surface. This will percolate up the surface
hierarchy, to the GUI code, and eventually come back down as a ``redraw`` call all
the way to the renderer (assuming it is not obscured by other media items, etc).
At this point the bits finally get drawn on the screen.

Whenever anything "interesting" happens in the renderer (the media item stopped playing,
the user clicked the mouse, etc) it invokes a corresponding method on its
``playable_notification``. This interface is implemented by the scheduler, and these
notifications are how the scheduler gets informed that it can start scheduling new things,
etc.