Detailed Description
The Guido Engine operates on two kinds of music representation:
- an abstract representation that corresponds to the Guido Music Notation elements. An important part of the layout - the logical layout, that decides on the stems direction for example - is applied to the abstract representation.
- a graphic representation that corresponds to a graphic instantiation of an abstract representation. Algorithms such as spacing and line breaking are applied to the graphic representation.
The functions described in this section are intended to build abstract and graphic representations.
Function Documentation
Initialises the Guido Engine. Must be called before any attempt to read a Guido file or to use the Guido Factory
- Parameters:
-
desc | the graphic environment description. |
- Returns:
- a Guido error code.
WARNING: the caller must ensure desc maintains a constant reference on a valid VGDevice, because Guido keeps it internally (to calculate fonts, etc.)
Initialises the Guido Engine with an independent SVG device, avoiding the need to pass a description. Useful for contexts (like javascript) where structures cannot be easily manipulated.
Guido Engine shutdown
Actually release the font allocated by the engine. Anyway, the fonts are release when the client application exit but the function provides control over the time of the release.
Parses a Guido Music Notation (.gmn) file and builds the corresponding abstract representation.
- Parameters:
-
filename | the file to parse. |
ar | on output: a Guido opaque handle to an abstract music representation. It's the caller responsability to free the handle using GuidoFreeAR. |
- Returns:
- a Guido error code.
Parses a buffer and builds the corresponding abstract representation. The buffer if expected to contain gmn code.
- Parameters:
-
str | the null terminated buffer to parse. |
ar | on output: a Guido opaque handle to an abstract music representation. It's the caller responsability to free the handle using GuidoFreeAR. |
- Returns:
- a Guido error code.
Transforms a Guido abstract representation into a Guido graphic representation. The engine applies layout algorithms according to the settings given as argument.
- Note:
- You can safely free the AR after the transformation.
- Parameters:
-
ar | the handler to the abstract representation. |
settings | a pointer to the settings for the graphic layout. If null, default settings are applied. |
gr | on output: a Guido opaque handle to a graphic music representation It's the caller responsability to free the handle using GuidoFreeGR. |
- Returns:
- a Guido error code.
Applies new layout settings to an existing Guido graphic representation.
- Parameters:
-
gr | the handler to the graphic representation. |
settings | a pointer to the settings for the graphic layout. If null, default settings are applied. |
- Returns:
- a Guido error code.
Releases a Guido abstract representation.
- Parameters:
-
ar | the handler to the abstract representation. |
Releases a Guido graphic representation.
- Parameters:
-
gr | the handler to the graphic representation. |
Gives a textual description of a Guido error code.
- Parameters:
-
errCode | a Guido error code. |
- Returns:
- a string describing the error.
int GuidoGetParseErrorLine |
( |
) |
|
Gives the line of a Guido script where the last parse error has occured.
- Returns:
- a line number.
Gives the default values of the layout settings.
- Parameters:
-
settings | on output, a pointer to the settings to be filled with default values. |