Lomse Hacking Guide
Layouting is defined as the process of planning and arranging in detail something, such as a page or book to be reproduced. Wikipedia defines layout (in reference to computer graphics) as the process of calculating the position of objects in space, subject to various constraints.
In lomse, layouting will be used with this meaning, and will refer to the process of deciding wich graphical symbols (lines, notes, rests, texts, etc.) will be used to build the visual representation of a lomse document, as well as deciding all details about this: where to place the symbols and their attributes (color, size, etc.). The result of the layouting process is the graphical model.
As you know, the InternalModel is a general purpose independent representation of the document content. From it, any other specific representation can be derived. For displaying a document, the layouting process traverses the internal model, taking decisions about the suitable graphical symbols, and their sizes and positions, and builds the graphical model.
For deciding the general layout of a document, a flow based approach is followed. Flow based means that it is assumed that most of the time it is possible to compute the geometry as the internal model is traversed (in a single pass). Elements later in the flow typically do not affect the geometry of elements that are earlier in the flow, so layout can proceed left-to-right, top-to-bottom through the document. There are exceptions: for example, scores and tables require more complex approaches.
Layouting is a recursive process. It begins at the root ImoDocument object, which corresponds to the lenmusdoc tag of the LDP representation. Layout continues recursively through all of the internal model hierarchy, computing all the graphical information for each ImoObj object.
The result is the graphical model, a tree of objects representing graphical information, including positions, sizes, and all other attributes.
The layouting process, related objects and algorithms is described in detail in section Layouting: graphical model creation.
To represent the visual information, the approach followed has been to capture the graphical structure by splitting the representation in containers and visible objects. For example, usually, a score is printed on several pages. A page contains systems. A system contains one or more staves. Finally, a staff contains visible objects (staff lines, notes, rests, barlines, etc.).
All objects defining the graphical model derive from abstract class GmoObj (Graphical Model Object). All container classes derive from abstract class GmoBox. And all visible objects derive from abstract class GmoShape.
The graphical model is a tree of boxes and shapes. The root of the representation is a GmoBoxDocument object, that is, a box containing all document graphical objects.
The GmoObj objects correspond to the ImoObj objects, but the relation is not one to one as an ImoObj can generate multiple GmoObjs (i.e. a tie can generate two arches, or a key signature can generate as many shapes as systems in the score). Also, the tree structure is different.
The graphical model is described in detail is section The graphical model in detail.
Rendering is the process of generating an image from the graphical model. In Lomse, the image to generate will be placed on the bitmap provided by the user application. It can be a bitmap big enough to contaion the full document or it can cover just a part of the document (i.e the viewport currently displayed into the screen).
Once the graphical model is created, the rendering process takes place. For this, Lomse uses the AGG rendering software (http://www.antigrain.com/).
From the point of view of the rendering process GmoShape objects behave as vertex sources, providing the coordinates for the polygons that define the shape.
Coordinates are then converted by applying different transformations, such as scaling, rotation and shift.
The converted coordinates creates a collecton of polygons that define the final image to be generated. For creating the image, an scanline rendering algorithm is applied (see, for instance, http://en.wikipedia.org/wiki/Scanline_rendering). The result of this process is a bitmap with the image.
Therefore, the rendering pipeline is as follows:
LenMus--> Vertex source
--> Coordinate conversion
--> Scanline rasterizer
--> Rendering buffer
--> Screen output
Some important Lomse specific issues of the rendering process are described in section rendering-details. But this document does not describe standard computer graphics concepts and algorithms, such as the scanline algorithm.