Overview
ADesc is a facility (technically, a class library) for storing numeric parameters with an unlimited number of independent and dependent axes and a large - and theoretically unlimited - amount of data. It has been developed as a part of the Noidesc project, whose large amounts of numeric data have been expected to stress the existing, purely XML-based APar class to-and-beyond its limits. In practice, ADesc has proven to be highly efficient with parameters consisting of hundreds of thousands of values, thereby fully meeting the demands of Noidesc. It is expected to meet the demands of challenging future projects as well.
ADesc fits into the existing STx design by offering an alternative to the existing APar class. Just like APar, the new ADesc stores parameters in the existing STx XML database. There are two ways of storing the numeric data:
- In-place in the XML database: This is the conventional way. It keeps all the benefits of XML storage (readable and editable, simple export and import to/from other software) without impairing performance for small and medium-sized parameters.
- Binary storage: For large parameters, there is an optional feature for binary storage. With ADesc binary storage, the parameter itself is still part of the XML database, keeping the advantages of the XML organization fully intact. Only the numeric data values of the axes themselves are stored as an external binary file. The XML axis data contains only a reference to that file and the position within the file. This keeps the XML database small and allows for very fast random access to data values.
The user must decide which kind of storage to use. For large parameters containing hundreds of thousands of numerical values, the performance gain of binary storage may be significant (up to a factor of three for loading and saving the data). At the same time, the saving of space in the XML database by about the same factor (or, more accurately, quotient) increases the speed of the general handling of the XML database.
Aside from performance, the main design criteria for the ADesc class library were flexibility and ease of use. ADesc provides for automatic unit conversion with most regularly used and predefined domains and units. More unusual situations may be handled with user-defined converter classes. There is even room for completely user-defined axes, thereby enabling things such as dynamically supplied data (e.g. live spectrogram) or data calculated on-the-fly.
As a result of the positive experiences with the ADesc class and its performance, plans are in place to fully replace the existing APar class over time.
Object Model
Each parameter is modeled by an instance of the ADesc class or of one of its derivations. There are several such classes derived from ADesc, each one optimized for a number of common cases. At this time, the following ADesc classes exist:
- ADesc: ADesc is the most general parameter class. It handles parameters with an arbitrary number of independent and dependent axes. It is also prepared for handling even infinite axes and dynamic axes, like axes whose values are supplied or computed at run-time.
- ADescX: AdescX is a simpler, less general variation of the most general ADesc, supporting neither infinite nor dynamic axes. Its internal storage is organized such that it matches the current way STx handles large tables. In the long run, it is expected to optimize the STx table handling, thereby possibly rendering ADescX redundant.
- ADesc0: ADesc0 models the special case of parameters without any independent axes.
- ADesc1: ADesc1 optimizes handling of parameters with exactly one independent axis and an arbitrary number of dependent axes. Storage organization is much simpler, rendering ADesc1 by far the fastest kind of ADesc parameter.
- ADesc2: ADesc2 efficiently handles parameters with exactly two independent axes and an arbitrary number of dependent axes. Storage organization is simpler and hence faster than with the general classes. The dedicated ADesc2 class has been supplied, because most parameters encountered so far have proven to have two axes.
The axes of a parameter are modeled by classes derived from AAxis. In general, each axis has a domain (e.g. time or frequency), a unit (e.g. ms or Hz) and, if applicable, a reference value, i.e. a constant value based upon the axis values that have been computed. At this time, the following kinds of axes exist:
- AOrderAxis: The AOrderAxis is the only axis without a domain and unit. Its only property is its cardinality.
- AIncrementAxis: The AIncrementAxis has a fixed start value, a fixed offset, and a cardinality. Each value of the axis equals the sum of its predecessor and the offset value.
- AEnumerationAxis: The AEnumerationAxis stores a finite number of arbitrary values.
- ASegmentIncrementAxis: The ASegmentIncrementAxis is an AIncrementAxis whose values are relative to the beginning of a given STx audio segment.
- ASegmentEnumerationAxis: The ASegmentEnumerationAxis is an AEnumerationAxis whose values are relative to the beginning of a given STx audio segment.#
- ADependentAxis: Each dependent axis of a parameter is modeled by an instance of an ADependentAxis. The number of dependent axes and their data are restricted by the choice of the respective ADesc class used.
The hierarchy of the most important classes making up the ADesc library is the following:
Programming Interface
The ADesc programming interface is as orthogonal a design as possible. The basic access functions are called getValue, setValue, getValues, setValues, getValueMatrix, setValueMatrix, getNativeValues, and setNativeValues. They are available both for the whole parameter and for its individual axes. Depending on which object they are called upon, they also set or retrieve one or more values of the desired axis or axes.
If the parameter modeled by ADesc is considered to be an n-dimensional space (n being the number of independent axes), each point in this space is uniquely described by an n-tuple of coordinates which is the argument to the respective get and set function. The coordinates may be supplied either as an STx vector or as a textual list.
If there is only one dependent axis, the value for each given coordinate is the value of this axis at the respective coordinate. If there is more than one dependent axis, the value for a given coordinate is a vector of length m, such that m is the number of dependent axes. By specifying the index or the name of a desired dependent axis, the user gets the value of this axis at the respective coordinates. By not specifying this information, the caller gets the whole vector of dependent values at the respective coordinates. This maximizes the flexibility for the ADesc user and requires awareness of fewer distinct functions.
Other than functions for retrieving one or more parameter values for a specific coordinate, there are also functions for retrieving a larger number of data at the same time. For example, with two-dimensional parameters (i.e. parameters with exactly two independent axes), there are the functions getValueMatrix and setValueMatrix for efficiently setting all of the data of an independent axis. For all parameters with at least one independent axis, there are the functions getValueVector and setValueVector for accessing the whole of an axis.