|
|
Version
1.0 |
|
© 12/2006 MARIAN, reproduction, distribution, and
publication through any media permitted with written authorization of MARIAN
only. |
|
|
|
Version
1.0 |
|
© 12/2006 MARIAN, reproduction, distribution, and
publication through any media permitted with written authorization of MARIAN
only. |
|
This documentation covers the software
interface to the Trace PRO driver, which is useful for third party application
software to control the Trace PRO audio signals. It includes:
· Analog Input Level Control
·
Mixer Channel Control
·
Sum Channel Control
·
Output Volume Control
·
Output Signal Routing
· Signal Level Analysis
The software interface is delivered by the 32-Bit Windows™ DLL file “tproifc.dll”. Thus, it makes it very easy to use it in any 32-Bit-Windows™ based application software. The documentation includes a C++ language header file (tproifc.h) which contains all function prototypes and other declarations like constants and structures. Additional, this documentation comes with the Trace PRO user manual which helps to understand how the Trace PRO is working and how the Trace PRO Manager software visualizes the cards functionality.
In the following, the Trace PRO Control API
is called TPROIFC.
The application software should first initialize the TPROIFC by use of the function tpro_Init. Multiple clients of the interface are supported via the same DLL module.
If the software application finishes the use of TPROIFC it must call tpro_Done.
It is essential for the client software to get the number of installed and active Trace PRO PCI cards via tpro_GetNumCards because the number of the card is a main identifier for many functions.
BOOL TPROCALL tpro_Init();
// initializes usage of TPROIFC
VOID TPROCALL tpro_Done();
// finalizes usage of TPROIFC
LONG TPROCALL tpro_GetNumCards();
// returns the number of installed, active Trace
PRO PCI cards
Every mixer parameter and also every output
parameter can be read and set by use of two functions:
tpro_mx_GetValue and tpro_mx_SetValue. Each parameter is uniquely identified by a set of ID’s – the Card
ID, the Channel Type ID, the Channel ID and the Parameter ID. Some parameters
require also a sub parameter ID. Use the functions tpro_mx_GetValueEx and tpro_mx_SetValueEx to access these parameters.
The Card ID is a simple number beginning from 0 to the number of installed cards – 1. The number of installed cards can be easily determined through the function tpro_GetNumCards. All other ID’s are explained in the following sections.
LONG TPROCALL tpro_mx_GetValue (
LONG
crdid,
LONG
typid,
LONG
chnid,
LONG
parid,
PLONG pValue
);
// Gets the current Value of a
specific mixer parameter
// Input:
// crdid
= Card Id
// typid
= Channel Type Id (see tpro_typid defines)
// chnid
= Channel Id (see tpro_chnid defines)
// parid
= Parameter Id (see tpro_parid defines)
// pValue = Pointer to a LONG variable for the
result
// Output:
// *pValue filled will the current parameter
value
// return < 0 ? Error : Success
LONG TPROCALL tpro_mx_GetValueEx (
LONG crdid,
LONG typid,
LONG chnid,
LONG parid,
LONG sparid,
PLONG pValue
);
// Gets the current Value of a specific mixer parameter
// Input:
// crdid = Card Id
// typid = Channel Type Id (see tpro_typid defines)
// chnid = Channel Id (see tpro_chnid defines)
// parid = Parameter Id (see tpro_parid defines)
// sparid = Sub-Parameter Id (see tpro_sparid defines)
// pValue = Pointer to a LONG variable for the result
// Output:
// *pValue filled will the current parameter value
//
return < 0 ? Error : Success
LONG TPROCALL tpro_mx_SetValue (
LONG
crdid,
LONG
typid,
LONG
chnid,
LONG
parid,
LONG
Value
);
// Sets the Value of a specific
mixer parameter
// Input:
// crdid
= Card Id
// typid
= Channel Type Id (see tpro_typid defines)
// chnid
= Channel Id (see tpro_chnid defines)
// parid
= Parameter Id (see tpro_parid defines)
// Value
= New Value for the Parameter
// Output:
// return < 0 ? Error : Success
LONG TPROCALL tpro_mx_SetValueEx (
LONG crdid,
LONG typid,
LONG chnid,
LONG parid,
LONG sparid,
LONG Value
);
// Sets the Value of a specific mixer parameter
// Input:
// crdid = Card Id
// typid = Channel Type Id (see tpro_typid defines)
// chnid = Channel Id (see tpro_chnid defines)
// parid = Parameter Id (see tpro_parid defines)
// sparid = Sub-Parameter Id (see tpro_sparid defines)
// Value = New Value for the Parameter
// Output:
//
return < 0 ? Error : Success
The Mixer of the Trace PRO consists of 20 mono channels.
The first four channels control the audio signals of the input channels of the card. The next eight channels of the mixer channels control the audio signals of the playback channels of the card. “Playback channels” does not mean output channels. It really means the playback signals which any audio application sends to the drivers software. And the last eight channels control the signals laying on TDM BUS and which are used here as mixer input channels.
Which audio signal can be heard at a output depends on the Output Routing (see Output Control).
The signals of all mixer channels are mixed to eight individually sums – AUX1 … AUX6 and MASTER.
Each mixer channel is identified by an ID for its type as mixer channel and an individual channel ID.
|
Type
ID (tpro_typid) |
Channel
ID (tpro_chnid) |
Trace PRO Device |
|
0 |
0 |
Analog Input 1 |
|
0 |
1 |
Analog Input 2 |
|
0 |
2 |
Digital Input L |
|
0 |
3 |
Digital Input R |
|
0 |
4 |
Play 1 |
|
0 |
5 |
Play 2 |
|
0 |
6 |
Play 3 |
|
0 |
7 |
Play 4 |
|
0 |
8 |
Play 5 |
|
0 |
9 |
Play 6 |
|
0 |
10 |
Play 7 |
|
0 |
11 |
Play 8 |
|
0 |
12 |
TDM 1 |
|
0 |
13 |
TDM 2 |
|
0 |
14 |
TDM 3 |
|
0 |
15 |
TDM 4 |
|
0 |
16 |
TDM 5 |
|
0 |
17 |
TDM 6 |
|
0 |
18 |
TDM 7 |
|
0 |
19 |
TDM 8 |
See the appropriate type ID’s (tpro_typid_xxx) and channels ID’s (tpro_chnid_xxx) also in the tproifc.h.
Each mixer channel has a number of parameters. The following table shows these parameter.
|
Parameter
ID |
Name |
|
Remarks |
|||
|
0 |
Source Select |
Value |
Source |
Digital Input Channel Only: Determines the physical audio connector for the channel. |
||
|
0 |
XLR
Input |
|||||
|
1 |
CD
Input |
|||||
|
8 |
|
Value |
Level
== 0dBfs |
For Analog Input Channels Only. Determines which analog level causes 0 dbfs on the digital side. Influences the recording level too. |
||
|
0 |
-6
dBv |
|||||
|
1 |
+8
dBu |
|||||
|
2 |
+15
dBu |
|||||
|
3 |
+18
dBu |
|||||
|
9 |
Analog Gain |
0..0x0A400
== -INF ..+18
dB |
For Analog Input Channels Only. Influences the recording level too |
|||
|
1 |
Digital |
0..0x10000
== -INF ..+6
dB |
Signal Level Adjustment. |
|||
|
2 |
AUX Volume |
0..0x10000
== -INF ..+6
dB |
Signal level for mix at AUX N. This parameter needs a sub parameter which specifies the AUX number |
|||
|
3 |
AUX Pre Fader |
1
|| 0 == on || off |
Determines whether or not the channel signal is mixed to the AUX N Bus pre (on) or post (off) the fader section. This parameter needs a sub parameter which specifies the AUX number |
|||
|
4 |
Mute |
1
|| 0 == on || off |
Mutes (On) the channel signal at the AUX and Master Busses. |
|||
|
5 |
Solo |
1
|| 0 == on || off |
Set the channel signal at the Master Sum to Solo (On). |
|||
|
6 |
Master PAN |
Value |
Left |
Right |
Determines the signal level of the channel at the left and right channel of the Master sum. |
|
|
0 |
+6
dB |
-INF |
||||
|
0x08000 |
0 dB |
0 dB |
||||
|
0x10000 |
-INF |
+6
dB |
||||
|
7 |
Master Volume |
0..0x10000
== -INF ..+6
dB |
Signal level for the mix at the Master Sum |
|||
Generally, all the values for dB ranges are like PCM sample values. The maximum value is +6 dB. Every “shift right” operation of the parameter value decreases the dB value by 6 dB. Thus, the following conversion routines apply:
Parameter Value to dB Value:
dBValue = Log2
(ParamValue/0x10000)*6 + 6;
dB Value to Parameter Value:
ParamValue = Round (Power (2,
(dBValue-(-90))/6));
The Analog Gain Inputs is set directly in the AD converter. Thus, another value
to dB conversion applies. Only the bits D8..D15 are
significant. Please see the conversion table in the file ek4620a.pdf page 33. Additional, when the gain of the
analog inputs is manipulated, this also influences the analog recording level,
not only the mixer input level.
Each Sum channel is identified by an ID for its type as sum channel and an individual sum channel ID.
|
Type
ID (tpro_typid) |
Channel
ID (tpro_chnid) |
Sum Channel |
|
1 |
0 |
Master Left |
|
1 |
1 |
Master Right |
|
1 |
2 |
Aux 1 |
|
1 |
3 |
Aux 2 |
|
1 |
4 |
Aux 3 |
|
1 |
5 |
Aux 4 |
|
1 |
6 |
Aux 5 |
|
1 |
7 |
Aux 6 |
See the appropriate type ID’s (tpro_typid_xxx) and channels ID’s (tpro_chnid_xxx) also in the tproifc.h.
Each sum channel has a parameter for the level adjustment of the audio mix. The following table shows this parameter and it’s value range.
|
Parameter
ID |
Name |
|
Remarks |
|
0 |
Volume |
0..0x8000
== -INF ..
0 dB |
Sets the audio mix level for sum channel. |
The conversion from dB value to parameter value and back should proceed like
described in “Mixer
Channel Control”.
The main task of the output control is the output signal routing and the control of the output signal level. Each channel of the output control is assigned to a physical output of the Trace PRO.
Each output stereo channel is identified by an ID for its type as output channel and an individual channel ID.
|
Type
ID (tpro_typid) |
Channel
ID (tpro_chnid) |
Trace PRO Device |
|
2 |
0 |
Analog Output 1-2 |
|
2 |
1 |
Digital Output |
|
2 |
2 |
TDM Bus Output 1-2 |
|
2 |
3 |
TDM Bus Output 3-4 |
|
2 |
4 |
TDM Bus Output 5-6 |
|
2 |
5 |
TDM Bus Output 7-8 |
See the appropriate type ID’s (tpro_typid_xxx) and channels ID’s (tpro_chnid_xxx) also in the tproifc.h.
Each output channel has a number of parameters, shown in this table.
|
Parameter
ID |
Name |
|
Remarks |
|
|
0 |
Source Select |
Value |
Source |
Determines the source signal which should be used for the output. Any of the available signals can be used – input, playback or sum signals |
|
0 |
Play
1-2 |
|||
|
1 |
Play
3-4 |
|||
|
2 |
Play
5-6 |
|||
|
3 |
Play
7-8 |
|||
|
4 |
Play
9-10 |
|||
|
5 |
Play
11-12 |
|||
|
6 |
Play
13-14 |
|||
|
7 |
Play
15-16 |
|||
|
8 |
Analog
Input |
|||
|
9 |
Digital
Input |
|||
|
12 |
TDM
1-2 |
|||
|
13 |
TDM
3-4 |
|||
|
14 |
TDM
5-6 |
|||
|
15 |
TDM
7-8 |
|||
|
16 |
Master
Sum |
|||
|
17 |
Aux
1-2 |
|||
|
18 |
Aux
3-4 |
|||
|
19 |
Aux
5-6 |
|||
|
1 |
Mute |
1 || 0 == On || Off |
Mutes the Output (on) |
|
|
2 |
Volume Left |
0..0x8000 == -INF ..
0 dB |
Controls output level left channel |
|
|
3 |
Volume Right |
0..0x8000 == -INF ..
0 dB |
Controls output level right channel |
|
|
4 |
TDM On Bus |
1 || 0 == On || Off |
For TDM Output Channels only: Switches the signal on the Bus or not |
|
|
5 |
|
Value |
Output Level @ 0 dbfs |
For Analog Output channels Only: determines the analog level when having a digital level of 0 dbfs |
|
0 |
-6 dBv |
|||
|
1 |
+8 dBu |
|||
|
2 |
+18 dBu |
|||
|
6 |
Format |
1 || 0 == |
For Digital Output Channels Only: Sets the according AES3 channel state |
|
The conversion from dB value to parameter value and
back should proceed like described in “Mixer
Channel Control”.
The Trace
PRO hardware analyzes the level of every audio signal available. Thus, any
client software is able to get the results of the level analysis for its own
purposes – mainly for the implementation of level meters.
The Trace
PRO hardware stores level values in a special part of the card memory. But
before a level value is stored, the hardware compares it with the previous
stored value which is only overwritten, if the new value is higher than the
older. The stored value is reset to zero, if the driver software reads the
value from the hardware. This way, the driver software always gets the maximum
level which occurred between two read operations.
The driver
software does the same for registered client software. It reads the level value
from the hardware compares it with the last stored, client related level value
and stores it only, if the client level value is less than the new level value.
The client related level value is reset to zero, if the client software read
its level value.
In this
manner the hardware works with every sample, the driver does it approximately
every 1 ms and it is up to the client software to get the level value in
intervals which are appropriate for the clients
purpose.
The
implementation of a level meter can be done very easily. The client software
could have 2 processes. The first process gets the level and displays it only
if the actual displayed level display is less than the new value. The second
process simply decreases the level display by a determined dB value in a
determined time.
typedef
struct {
LONG Pre; // Source Level Pre Gain
LONG Post; // Level measured after
Gain/Pan/Volume/Mute
BOOL AdOvl; // AD Channels only: AD signaled an
Input Overload
BOOL
ParChanged; // Any of channel parameters has changed - read
parameter values again
LONG
Code; // Channel specific Error Code of last Get/Request
Operation
LONG
Requests; // Number of clients who need the level info of
this channel
ULONG Handle; // Driver spec. Handle, do not use
ULONG hDev; // Driver spec. Handle, do not use
} TPRO_CHNLEVELINFO,
*PTPRO_CHNLEVELINFO;
typedef
struct {
LONG CardId; //
IN: ID of target card
LONG reserved;
TPRO_CHNLEVELINFO Levels[TPRO_NUMCHANNELS];
// LevelInfo for each Mono signal
available; indexes see: tpro_lvi_XXX constants
} TPRO_LEVELINFO,
*PTPRO_LEVELINFO;
The structure TPRO_LEVELINFO with its array of TPRO_CHNLEVELINFO is used to request and get the level values for the different mono
channels. For each mono channel a TPRO_CHNLEVELINFO structure is assigned in the Levels array of TPRO_LEVELINFO. Please see the array indexes in the following table and the “tproifc.h”.
|
Index |
Channel |
|
0 |
Analog Input 1 |
|
1 |
Analog Input 2 |
|
2 |
Digital Input L |
|
3 |
Digital Input R |
|
4 |
Play 1 |
|
5 |
Play 2 |
|
6 |
Play 3 |
|
7 |
Play 4 |
|
8 |
Play 5 |
|
9 |
Play 6 |
|
10 |
Play 7 |
|
11 |
Play 8 |
|
12 |
Tdm 1 |
|
13 |
Tdm 2 |
|
14 |
Tdm 3 |
|
15 |
Tdm 4 |
|
16 |
Tdm 5 |
|
17 |
Tdm 6 |
|
18 |
Tdm 7 |
|
19 |
Tdm 8 |
|
20 |
Play 9 |
|
21 |
Play 10 |
|
22 |
Play 11 |
|
23 |
Play 12 |
|
24 |
Play 13 |
|
25 |
Play 14 |
|
26 |
Play 15 |
|
27 |
Play 16 |
|
28 |
Master Sum L |
|
29 |
Master Sum R |
|
30 |
Aux 1 |
|
31 |
Aux 2 |
|
32 |
Aux 3 |
|
33 |
Aux 4 |
|
34 |
Aux 5 |
|
35 |
Aux 6 |
LONG TPROCALL tpro_RequestLevel
(PTPRO_LEVELINFO pLevelInfo);
// Switchs Level Anaysis for
specific stereo channels on/off
// Input:
// pLevelInfo = pointer to level information
structure
// pLevelInfo->CardId = ID of target card
// pLevelInfo->Levels[].Requests =
initialized with >0 if Level required
// Output:
// pLevelInfo->Levels[].Code = Error Code
for Request
// pLevelInfo->Levels[].Handle = Driver
specific handle for client channel
// return < 0 ? Error : Success
This function switches the level analysis for specific stereo channels on and off. The driver software uses the information in pLevelInfo->Levels[].Requests for the level analysis state of the channel.
The client software can check the success of the operation for each channel by use of pLevelInfo->Levels[].Code. A value less than 0 indicates that the request could not be executed. This may occur with the Digital/TDM input channel only because of inappropriate clock settings (see users manual).
Example: The client software request the levels for the AES/EBU Input and any of the TDM inputs. With the default clock settings the driver assumes that both digital input clocks are not synchronized. Since the Trace PRO always works with one clock only, the signal of the AES/EBU input can be evaluated by using the clock of this input as reference. In this case, the TDM input clock can not be evaluated.
The client software should also observe the information in pLevelInfo->Levels[].Code after calling tpro_GetLevel because it may change because of recording/playback requests from audio recording applications. Read more about this in tprotpro_GetLevel.
The client software must use always the identical TPRO_LEVELINFO variable for tpro_RequestLevel and tpro_GetLevel calls because the driver writes client related information into this structure.
The client software must deactivate the
level analysis for all channels before it exits.
LONG TPROCALL tpro_GetLevel
(PTPRO_LEVELINFO pLevelInfo);
// Get the Levels for all
requested MONO channels
// Input:
// pLevelInfo = pointer to level information
structure,
// pLevelInfo->CardId = ID of target card
// Output:
// pLevelInfo->Levels[].Code = Error Code for Get
( < 0 ? Error : Success)
// pLevelInfo->Levels[].Pre = Level of the Source Signal
(PRE Gain/Fader)
// pLevelInfo->Levels[].Post = Level of the Signal after Gain, Pan,
Fader, Mute
// pLevelInfo->Levels[].AdOvl = if TRUE then the AD Converter signaled
an Input Overload
// pLevelInfo->Levels[].ParChanged = if TRUE
then any parameter of the channel has changed
// return < 0 ? Error : Success
Using this function, the client software can get the levels of the different channels. The client software gets the level peak values that occurred between this and the previous call. A call of tpro_GetLevel reset the driver stored peak value to zero.
Before the first call of tpro_GetLevel, the TPRO_LEVELINFO variable must be initialized with tpro_RequestLevel.
The level value in Pre, Post of the TPRO_CHNLEVEKINFO structure is expressed like a PCM sample value. A conversion to a dB value can be done in the same way like the parameter values are converted (see Mixer Channel Control).
The following table contains the value ranges of the level values.
|
pLevelInfo->Levels[].Pre |
0..0x08000
== -INF ..
0 dB |
|
pLevelInfo->Levels[].Post |
0..0x08000
== -INF ..
+6 dB |
The level value in Pre of the TPRO_CHNLEVELINFO structure always represent the level of the source signal. That means for
· Analog Input Channels the level after the gain control
· All other Mixer Channels the level prior the gain control
· Sum Channels the level prior the fader
The level value in Post of the TPRO_HNLEVELINFO structure always represent the level post fader. This way it is very easy for the client software to implement a switchable “pre fader metering”.
The client software should use pLevelInfo->Levels[].Code to evaluate to validity of the level values. This code can contain an error state for that channel even if tpro_RequestLevel not returned an error. This can be the case for the AES/EBU and TDM input channels only.
Example:
Like mentioned, the Trace PRO works always with one reference clock only, means
also with one sample rate only. If a client software
requests a level information for the AES/EBU input with sample rate converters
switched off, the driver uses the clock of this input. Imagine the AES/EBU
input runs at 44.1 kHz and a recording software requests a recording from the
analog input at 48 kHz. Since recording and playback have always the higher priority
towards level analysis, the driver, according its default clock settings, would
switch to the internal clock and would set it to 48 kHz. In this case, the
level of the digital input could not be evaluated and the pLevelInfo->Levels[].Code
would signal an error. After the recording has
finished, the driver looks at the level request table and ensures the right
clock settings for the requested levels. The pLevelInfo->Levels[].Code
would signal no error again.
