Re: translators / engravers / performers

[Reinhold Kainhofer]

Am Freitag, 26. November 2010, um 12:26:08 schrieb David Santamauro:
> Greetings,
> 
> After browsing the code for a couple weeks, I have a few questions.
> First, though, if there is a skeleton Performer, commented thoroughly,
> please disregard the rest of this email and point me to it. Otherwise...

Well, first, you are talking particularly about Performers. In fact, Engravers 
and Performers are exactly the same thing (all translator-derived), just with 
different purpose (engravers create graphical objects, performers create MIDI 
objects). So everything general said about performers is also true for 
engravers and vice versa.

> What makes up a skeleton performer?
> 
> // definition as subclass of "Performer"
> class Skeleton_performer : public Performer
> {
> 
> public:
>   // standard declarations common to all translators
>   TRANSLATOR_DECLARATIONS (Skeleton_performer);
> 
> protected:
>   // methods this performer wishes to override
>   void start_translation_timestep ();
>   void process_music ();
>   void stop_translation_timestep ();

Yes, called at the begin/end of each timestep and when all the music events 
have been received (i.e. all listeners have done their job for this time step, 
so you have a picture of which relevant events are happening at this timestep)

> 
>   // this was taken from piano-pedal-performer.cc
>   // I'm assuming this is what this performer is
>   // is interested in "listening" to but what is
>   // is being listened to? I don't see where the
>   // symbol 'sustain' is defined.
>   // DECLARE_TRANSLATOR_LISTENER (sustain);

This listens to music events of type sustain-event (defined in scm/define-
event-classes.scm as a music event called sustain-event, and used in 
scm/define-music-types.scm for the SustainEvent).
In particular, the \sustainOn command is defined (in ly/spanners-init.ly) as:
    sustainOn = #(make-span-event 'SustainEvent START)

DECLARE_TRANSLATOR_LISTENER is a macro, so it does lots of things in the 
background, including creating derived names from the passed name.


>   // .. and my own
>   DECLARE_TRANSLATOR_LISTENER (mySymbol);
>   // My best guess is that a command \mySymbol
>   // is what is being listened to and acted upon

Nope, it listens to all music-events (defined in scm/define-music-types.scm) 
of type mySymbol-event (hierarchy of the music-event types defined in 
scm/define-event-classes.scm).

> }
> 
> // here is the actual implementation of the
> // mySymbol listener
> IMPLEMENT_TRANSLATOR_LISTENER (Skeleton_performer, mySymbol);
> void
> Skeleton_performer::listen_mySymbol(Stream_event *ev)
> {
>   // do something
> }
> 
> // register new performer
> ADD_TRANSLATOR (Skeleton_performer,
>                 /* doc */
>                 "something that does nothing",
> 
>                 /* create: CREATE WHAT? */
>                 "",

Which grob (graphical object) types are created by this engraver.

> 
>                 /* read: READ WHAT? */
>                 "",
> 
>                 /* write: WRITE WHAT? */
>                 ""

Read/write Context properties.

These settings are also used to detect unused or undefined properties.


> So a few major questions:
> 
> 1) what are the real steps to register a performer? Does this include
> possible initialization / registration in an .ly script or is the class
> definition sufficient?

Of course, you need the class definition and the implementation in a C++ file 
in the lily/ directory. the build system will automatically include all 
performers/engravers in the build without the need to adjust the makefile.

This makes the engraver/performer available to lilypond, but it is only used 
in a particular context if you \consist it in that context. This is usually 
done in ly/engraver-init.ly and in ly/performer-init.ly ... Of course, you 
don't have to do it system-wise, you can also just add the engraver to a 
context in your own lilypond file.


> 2) what are the overridable methods and what is the order and function
> of each in the grand concept of a performer (or engraver).

The most important are (I think they are typically called in that order):
-) void initialize ();
      Called at the begin of score (or to be exact, when the engraver's
      context is created) to initialize everything needed.

Then iteration starts and for each moment, the following calls happen:

-) void start_translation_timestep ();   // At the begin of a moment

-) All LISTENER callbacks are executed for the music events they are
      registered for

-) void process_music ();   
      All music events for the current time step (=moment) have been received, 
      so you have a clear picture of what relevant events happened at that 
      moment and you can create the appropriate grobs (which should be
      announced with announce_grob, so other engravers can notice them), etc.

-) All ACKNOWLEDGER callbacks are executed for all created grobs (created and
      announced by all other engravers, too!). This is similar to LISTENERS
      for music-events, but works with grobs.

-) void stop_translation_timestep ();  
      Clean up: The whole moment has been processed

And finally, the cleanup:

-) void finalize ();
      Called at the end of a context to do global clean-up (e.g. close a
      spanner with a missing closing event, etc.)



> I guess this is enough to digest for the moment. Any answers to the
> above comments / questions will surely provide me more fuel for further
> research.

Cheers,
Reinhold

-- 
------------------------------------------------------------------
Reinhold Kainhofer, address@hidden, http://reinhold.kainhofer.com/
 * Financial & Actuarial Math., Vienna Univ. of Technology, Austria
 * http://www.fam.tuwien.ac.at/, DVR: 0005886
 * LilyPond, Music typesetting, http://www.lilypond.org