Re: translators / engravers / performers

[Reinhold Kainhofer]

Am Freitag, 26. November 2010, um 15:48:01 schrieben Sie:
> On Fri, 26 Nov 2010 13:30:21 +0100
> Reinhold Kainhofer <address@hidden> wrote:
> > 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.
> 
> This is very valuable. So assuming I had a brilliant idea that was a
> derivative of a span-event, let's call it "span-modulation-event"
> that creates midi modulation swells. I would
> 
> a) ... possibly? do something so that my new event-representing symbols
> are recognized by the parser

No need for that. In d) you create the lilypond symbols/variables that insert 
those events into the music. 

> b) add my new event to the list of span-event in
> scm/define-event-classes.scm
> 
> c) add an event "ModulationEvent" in scm/define-music-types.scm as
> 
> (ModulationEvent
>   . (( description . "Execute a MIDI modulation swell.")
>      ( types . (general-music span-event modulation-event) )
>     )
> )
> 
> d) add a definition in ly/spanners-init.ly, e.g.,
> modulationStop = #(make-span-event 'ModulationEvent STOP)
> modulationStart = #(make-span-event 'ModulationEvent START)
> 
> e) write my class Modulation_Performer

Exactly.


> > 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).
> 
> In my fictitious case above
> 
> DECLARE_TRANSLATOR_LISTENER (modulation)

Yes. In the listener function you can either store the event to be processed 
in process_music (), or immediately handle it:

IMPLEMENT_TRANSLATOR_LISTENER (Modulation_Performer, modulation);
void
Modulation_Performer::listen_modulation (Stream_event *ev)
{
  // modulation_ is a Stream_event * member of your performer
  ASSIGN_EVENT_ONCE (modulation_, ev);
}



> Assuming I wanted it system-wide in the Voice context, something like
> this should suffice:
> 
> \context {
>   \type "Performer_group"
>   \name Voice
>   % the rest and then ...
>   % my new performer
>   \consists "Modulation_performer"
> }

Yes.

> > > 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.
> 
> What would be done here that the class constructor can't handle.

In the constructor you don't have access to the context yet. For example, the 
Key_engraver sets some context properties (keySignature, lastKeySignature, 
etc) to default values, since it later on wants to detect all changes to those 
properties.


> > Then iteration starts and for each moment, the following calls happen:
> > 
> > -) void start_translation_timestep ();   // At the begin of a moment
> 
> I'll dig a bit into moment(s).

In the iteration stage, lilypond goes through the score one timestep (i.e. 
moment) after the other. In each of those timestep all events (notes, rests, 
whatever...) are sent to the iterators and from there to the translators to be 
processed. So you don't have to worry how something was entered (e.g. parallel 
music or so), lilypond will always give you all events from the current time 
step, no matter how the input looked like.

BTW, I just realized the Contributor's Guide already contains a nice section 
on engravers:
http://lilypond.org/doc/v2.13/Documentation/contributor/engraver-tutorial

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