Functions

Building abstract and graphic representations

Functions

GuidoErrCode GuidoInit (GuidoInitDesc *desc)
GuidoErrCode GuidoInitWithIndependentSVG ()
void GuidoShutdown ()
GuidoErrCode GuidoParseFile (const char *filename, ARHandler *ar) __attribute__((deprecated))
GuidoErrCode GuidoParseString (const char *str, ARHandler *ar) __attribute__((deprecated))
GuidoErrCode GuidoAR2GR (ARHandler ar, const GuidoLayoutSettings *settings, GRHandler *gr)
GuidoErrCode GuidoUpdateGR (GRHandler gr, const GuidoLayoutSettings *settings)
void GuidoFreeAR (ARHandler ar)
void GuidoFreeGR (GRHandler gr)
const char * GuidoGetErrorString (GuidoErrCode errCode)
int GuidoGetParseErrorLine () __attribute__((deprecated))
void GuidoGetDefaultLayoutSettings (GuidoLayoutSettings *settings)

Detailed Description

The Guido Engine operates on two kinds of music representation:

The functions described in this section are intended to build abstract and graphic representations.


Function Documentation

GuidoErrCode GuidoInit ( GuidoInitDesc desc )

Initialises the Guido Engine. Must be called before any attempt to read a Guido file or to use the Guido Factory

Parameters:
descthe 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.)

GuidoErrCode GuidoInitWithIndependentSVG (  )

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.

void GuidoShutdown (  )

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.

GuidoErrCode GuidoParseFile ( const char *  filename,
ARHandler ar 
)

Parses a Guido Music Notation (.gmn) file and builds the corresponding abstract representation.

Parameters:
filenamethe file to parse.
aron 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.
GuidoErrCode GuidoParseString ( const char *  str,
ARHandler ar 
)

Parses a buffer and builds the corresponding abstract representation. The buffer if expected to contain gmn code.

Parameters:
strthe null terminated buffer to parse.
aron 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.
GuidoErrCode GuidoAR2GR ( ARHandler  ar,
const GuidoLayoutSettings settings,
GRHandler gr 
)

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:
arthe handler to the abstract representation.
settingsa pointer to the settings for the graphic layout. If null, default settings are applied.
gron 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.
GuidoErrCode GuidoUpdateGR ( GRHandler  gr,
const GuidoLayoutSettings settings 
)

Applies new layout settings to an existing Guido graphic representation.

Parameters:
grthe handler to the graphic representation.
settingsa pointer to the settings for the graphic layout. If null, default settings are applied.
Returns:
a Guido error code.
void GuidoFreeAR ( ARHandler  ar )

Releases a Guido abstract representation.

Parameters:
arthe handler to the abstract representation.
void GuidoFreeGR ( GRHandler  gr )

Releases a Guido graphic representation.

Parameters:
grthe handler to the graphic representation.
const char* GuidoGetErrorString ( GuidoErrCode  errCode )

Gives a textual description of a Guido error code.

Parameters:
errCodea 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.
void GuidoGetDefaultLayoutSettings ( GuidoLayoutSettings settings )

Gives the default values of the layout settings.

Parameters:
settingson output, a pointer to the settings to be filled with default values.