Table of Content
- 20
-
Advanced Design Time Configuration
- Additional Variable Configuration
- Adding Additional Variables to Audio Object
- Audio Object description file for tuning and control
Additional Variable Configuration
Additional configuration variables are optional parameters that are needed if a specific object/algorithm needs configuration parameters beyond the default ones. Objects by default have configuration for (as mentioned above):
- Channels
- Elements
- Modes
An object can chose to utilize all the default variables or not. However if the object needs more configuration variables, that’s where additional variables come in. A good example is parameter biquad audio object:
- Channels are used
- Elements represent number of biquads field
- Object Mode is the drop down.
However, the parameter biquad object also allows the user to select the filter topology and whether ramping is needed or not. Those two are represented with additional variables. These are fully customizable by the objects.
Adding Additional Variables to Audio Object
The object needs to inform the toolbox regarding the number of additional variables it needs. This is already described above as part of the object description. Besides the number of additional variables, the object needs to have a description of each additional variable. The audio object developer can provide the following:
Besides the number of additional variables, the object needs to have a description of each additional variable. The audio object developer can provide the following:
- Label for additional variable (example: filter enable or disable)
- Data type for the additional variable
String data type is not supported, as it will add additional bytes to the flash memory. Strings are used only in GTT and not required on target.
- Defaults & Range
- Min
- Max
- Default value
- The dimension for each additional variable
- Data order – Describes how data is ordered. e.g. ascending or descending order
- Dimension description
- Label
- Size of each dimension
- Axis start index (Float always irrespective of datatype)
- Axis increment (Float always irrespective of datatype)
Starting in R release – the sizes of a dynamic additional variable (NOT the count of variables, the size of each variable) can change based on user inputs.
To enable this functionality, make sure to see the static metadata page. You must set the static metadata parameter isAddVarUpdateRequired to true.
Here are the restrictions and features:
- You can access the following members to change your size –
- m_NumElements
- m_NumAudioIn
- m_NumAudioOut
- You can only refer to these if they are true inputs (IE: you are NOT setting them in getObjectIO)
- Example : Your mask says m_NumElements and m_NumAudioOutare NOT configurable by the user (so they are considered derived values).
- You cannot utilize m_NumElements and m_NumAudioOut for changing additional var size – this would create a two way dependency as additional vars are INPUTS to getObjectIO
- You can use m_NumAudioIn freely
Below is an example of an object that has four additional variables.
- First additional variable
- Label : “ Gain Vs Frequency “
- Data type : Float
- Defaults : Min Value = 0.5 Max Value = 1.0 and Default value = 0.75
- Number of dimension = NUM_DIMENTION_VAR1 (2)
- Data order : xAF_NONE (no specific order required)
- Dimension details :
- 1st dimension:
- Size of 1st dimension : SIZE_ADDVAR_1_XAXIS (10)
- Label : “Gain“
- Axis start index : 0
- Axis increment : 1
- 2nd dimension:
- Size of 2nd dimension : SIZE_ADDVAR_1_YAXIS (20)
- Label : “Frequency“
- Axis start index : 0
- Axis increment : 1
- 1st dimension:
- Second additional variable
- Label : “Enable Disable Filter“
- Data Type : Int8 / char
- Defatults : Min Value = 0 Max Value = 1 and Default value = 0
- Number of dimension = 1
- Data order : xAF_NONE (no specific order required)
- Dimension details :
- 1st dimension
- Size of 1st dimension : 10
- Label : “ inputFiltEnable“
- Axis start index : 0
- Axis increment : 1
- 1st dimension
- Third additional variable
- Label : “ Min Max “
- Data type : Int
- Defatults : Min Value = 0 Max Value = 30 and Default value = 5
- Number of dimension = 1
- Data order : xAF_ASCENDING (Data has to be entered in ascending order)
- Dimension details :
- 1st dimension
- Size of 1st dimension : 2
- Label : “ 1st – Min 2nd – Max“
- Axis start index : 0
- Axis increment : 1
- 1st dimension
- Fourth additional variable
- Label : “ Gain “
- Data type : Int
- Defatults : Min Value = -30 Max Value = 20 and Default value = 1
- Number of dimension = 1
- Data order : xAF_NONE (Data has to be entered in ascending order)
- Dimension details :
- 1st dimension
- Size of 1st dimension : 1
- Label : “ Gain “
- Axis start index : 0
- Axis increment : 1
- 1st dimension
The example can be referred to here
An example of the result in the SFD is shown below, with the configuration of additional variable 1:
Audio Object description file for tuning and control
Once a signal flow design is complete, SFD calls the following three Audio Object API functions, getXmlSVTemplate(), getXmlObjectTemplate(), and getXmlFileInfo(), to generate XML that describes the parameter memory layout for tuning purposes and state memory layout for control and debug purposes. This data depends on the object configuration designed in the signal flow.
These functions are enabled only when generating the XML file on a PC. The getXmlSVTemplate() function is called once and used for state variable templates, a single parameter, or control value. This state variable template can be reused in the object template or even the device description. The getXmlObjectTemplate() creates an object template that can be reused in another object template or in the device description. The getXmlFileInfo() uses the block ID assigned by the SFD and the HiQnet address of an object. HiQnet ID of the StateVariable must be unique in an object – even across hierarchical levels.
This data describes the parameter memory layout for tuning purposes and state memory layout for control purposes:
unsigned int CAudioObjectToolbox::getXmlSVTemplate(tTuningInfo* info, char* buffer, unsigned int maxLen){}
unsigned int CAudioObjectToolbox::getXmlObjectTemplate(tTuningInfo* info, char* buffer, unsigned int maxLen){}
unsigned int CAudioObjectToolbox::getXmlFileInfo(tTuningInfo* info, char* buffer, unsigned int maxLen){}
This data must precisely describe the memory layout of the object. Here are some general guidelines:
- Each object should start with a new HiQnet block value.
- Each object should have a unique block ID value.
- Block ID refers to an entire audio object. How sub-blocks are used, depends on the object developer. This is tied to how the developer writes the tuneXTP function. For example, each sub-block in a Biquad that contains multiple filters and multiple channels, can refer to the multiple filters on one channel. Alternatively, each sub-block can refer to one filter in the Biquad.
- This file and tuning are directly related and should be implemented or laid out in the same order.
- Each parameter or state value in an object that the developer wants to expose to the user should be wrapped and described in the segment.
- Category should be set to ‘Tuning‘ for parameter memory and to ’State‘ for control memory or state memory.
To ease the generation of this data, the xAF has created XML helper functions. These functions can be used when writing getXmlSVTemplate(), getXmlObjectTemplate() functions.
The helper function is shown below for an example where getXmlSVTemplate() for a Delay object is written using writeSvTemplate():
For more xml helper functions:
- Internal customers: Refer to XafXmlHelper.h and XafXmlHelper.cpp.
- External customers: Contact Harman.
For more information and details, please check the Device Description File specification guide.
Examples of the XML function that needs to be written is shown inAudio Object Example section.
