TuneXTP

This functionality alerts an object when its parameter memory is updated or modified. It provides information on the exact variables that were modified and allows the object to update internal variables accordingly. An example is in a filter block, where a parameter update (for example a gain/frequency/q change) triggers the recalculation of the filter coefficients in the tuning code. The API triggered is CAudioObject::tuneXTP().

void CAudioObject::tuneXTP(int subblock, int startMemBytes, int sizeBytes, xBool shouldAttemptRamp)
{
}

An ID-based memory addressing scheme is used instead of pure memory offsets. The CAudioObject→tuneXTP() method is called by the framework in CAudioProcessing→setAudioObjectTuning().

CAudioObject::tuneXTP() take in three integers representing the:

• sub-block: index of the sub-block in the audio object.
• startMemBytes: memory offset (in bytes) from the beginning of the sub-block memory.
• sizeBytes: number of the parameters tuned (size in bytes).
• shouldAttemptRamp: flag to indicate audio object should attempt to ramp the tuning parameters or not.

The subblock, startAdr and size are passed into the audio object to enable the calculation of the elements it needs to tune.

The code MUST be written in a manner that allows the tuning of any variable even if the corresponding sub-block is not provided. For example, an object with 2 sub-blocks with 4 variables within each sub-block, the algorithm should be able to support tuning the 5th variable with both commands: tuneXTP(0, 5, 1) AND tuneXTP(1,0,1).

Implementation

Once triggered, the function’s implementation is heavily dependent on the audio object itself and on the corresponding tuning panel (or Device Description/ memory layout) that the tuning tool will use to tune the audio object.

The developer needs to take into consideration the following while designing an object:

• The set file header size. If an object uses a large number of sub-blocks, each sub-block will require additional header data to store its values in the initial tuning file.
• The number of sub-blocks. If there are a lot of sub-blocks, and developers are tuning a big chunk of data, there will be many more xTP messages sent compared to an audio block with fewer sub-blocks.
• The calculations required. Having more sub-blocks can reduce the calculations required in the AudioObject::tuneXTP() functions. The audio object can focus on calculations for a narrower section of audio object memory, which is the sub-block.

For example, if a parameter biquad block is being tuned, the index or sub-block ID passed in by the CAudioProcessing class could determine:

• If a specific channel is being tuned. Once triggered, the function should:
  • Recalculate the filter coefficients characterizing all filters of that specific Biquad channel.
  • Use the memory offset and size variables to recalculate only the filter coefficients whose corresponding parameters were modified.
• A specific filter within a specific channel. Once triggered, this will only compute the coefficients of a single filter.

The xAF team has implemented the Parameter biquad block with the sub-block definition referring to a channel in the biquad block rather than one specific filter. The xAF also uses memory offset and sub-block to recalculate as few filter coefficients as possible.

Examples of what the tuning methods of each individual Audio Object trigger are listed below: