Output port

Output port is a function that makes it easy to manage and control the audio output destination.
This is useful when playing on a device other than the main output destination or when playing in a special way using platform functions.

Output port basics

When an audio with a specified output port is played, it is automatically played through that output port.
However, please note that output ports are not actual output destinations (output devices).
In principle, the output destination in CRI ADX is handled by creating an ASR rack. In the output port, the ASR rack ID must be set as the actual output destination.
By setting an ASR rack as the output destination for the output port, the audio that passes through the output port will be output from the set output destination.

Usage patterns of output ports

There are mainly two usage patterns for output ports.

1. Set the output port in advance with CRI Atom Craft
2. Create an output port from the application

1. Set the output port in advance with CRI Atom Craft

Set the output port in CRI Atom Craft

Set the output port in CRI Atom Craft and specify the output port name in the track.
For details on how to set it up, see Output port .

Work to be done in the application

Output ports at runtime are handled by output port handles.
Handles are created in the ACF for output ports set in CRI Atom Craft when the ACF file is registered.
When a track with a specified output port name is played, an output port handle with the same name is searched for in the ACF, and playback is performed via that output port.

Before the application plays audio through the output port, it sets the appropriate output destination (ASR rack) to the output port handle.
The output port handle in the ACF is obtained by the output port name. The output port name set in the ACF is written in the ACF header.

/* Register ACF file */
criAtomEx_RegisterAcfFile(NULL, ACF_PATH, NULL, 0);
            :
            :
/* Get output port handle in ACF */
port_hn = criAtomExAcf_GetOutputPortHnByName("Output_port_name");
 
/* Create appropriate output destination (ASR rack) for output port */
rack_id = create_asr_rack_for_output_port();
 
/* Set ASR rack ID to output port handle */
criAtomExOutputPort_SetAsrRackId(port_hn, rack_id);

Since output port name can be specified for each track in advance with CRI Atom Craft, it is also possible to play tracks with different output destinations simultaneously in one cue.
Even if you want to play special audio such as pad speaker playback or playback with limited distribution, you can simply specify an output port for the audio in advance in CRI Atom Craft and set the ASR rack with that function as the output port, making runtime operations easier.

The following figure shows an example of a track specified to play on a pad speaker in CRI Atom Craft.
Even if there are tracks in the same cue, only tracks with an output port name specified will be played from the intended output destination ASR rack via the output port.

2. Create an output port from the application

In addition to the output ports in ACF, you can also create output port handles from your application. This function is useful when you need to change the output destination according to the application's situation.
Output ports created from your application are used for the following two functions.

• Specify the output destination for all audio from the player
• Specify an alternative to the output port specified in CRI Atom Craft

Specify the output destination for all audio from the player

You can add an output port handle created from your application to a player using the criAtomExPlayer_AddOutputPort function.
When you add an output port handle, all audio played from that player will be played through the added output port, ignoring other settings.
You can also add multiple output port handles to a single player. In that case, the added output will consume voice.

The following figure shows an example of a case where an output port corresponding to a new pad speaker has been added to a player.
Audio played from a player to which an output port has been added will be played through the added output port, ignoring other settings, including the output port name.

Specify an alternative output port to the one specified in CRI Atom Craft

You can add an output port handle with the same name as an output port in the ACF to the player as the preferred output port using the criAtomExPlayer_AddPreferredOutputPort function.
The preferred output port is used instead of the output port in the ACF with the same name.
For example, when a track with an output port name Hoge is played, it is usually played through the Hoge output port in the ACF.
However, if you create an output port handle with the same name Hoge and add it to the player as the preferred output port, the track will be played through the preferred output port.
The preferred output port does not affect tracks that do not specify an output port name or tracks that specify a different output port name.

The following figure shows an example of adding an output port corresponding to a new pad speaker as the preferred output port.
A priority output port with the same name as an output port in the ACF only affects the track that has that output port name specified.

Output port type

When creating an output port handle, specify the type (for output ports in the ACF, the type set in CRI Atom Craft is specified).
The output port type is selected based on how the audio passing through that output port is played.
However, since the output port itself is not the output destination, please note that how the audio passing through a certain output port is output depends on the ASR rack set for that output port.
There are currently two types of output ports.

• Audio
• Vibration

Audio

This type is specified when you want to play audio through an output port as normal audio.
Specify this when you want to play audio not only to the main output destination, but also to output ports that perform special playback such as pad speaker playback and playback with limited distribution.
There are no restrictions on the ASR racks that can be set to this type of output port.

Vibration

This type is specified when you want to play audio through an output port as audio-based vibration.
On platforms that support audio-based vibration, create an appropriate ASR rack and set it to this type of output port.
Additional functions for controlling vibration are available for this type of output port. For details, see the samples for each platform.
The ASR rack that you set to this type of output port must have an output channel of 2.

For platforms that do not support audio-based vibration

In multi-platform development, ACF files with vibration-type output ports may be used on platforms that do not support audio-based vibration.
In this case, if you play a track with a vibration type output port without doing anything, a warning will be generated and it will be played on the main output destination.
To prevent the playback of tracks intended for vibration, for example, you can consider the following method.

1. Create an ASR rack with output channel set to 2
2. Set the created ASR rack to the vibration type output port
3. Set the volume of the master bus of the ASR rack to 0

Disable output port category

Output ports have the function to disable the influence of a specific Category .
Use this function if you do not want the influence of the category set in the cue to be applied to the track in the cue with a specific output port set.

For example, a sound effect cue may contain both a sound effect track and a vibration effect track.
If you set the sound effect category to such a cue, the volume of the category will also be applied to the vibration effect track.
By disabling the effect of the SE category on the vibration type output port, adjusting the volume of the SE category will not affect the vibration track.

The categories to be disabled can be set with the criAtomExOutputPort_IgnoreCategoryParametersById function.
The set categories can also be reset with the criAtomExOutputPort_ResetIgnoreCategory function.

The maximum number of categories that can be disabled is specified by CriAtomExOutputPortConfig::max_ignored_categories .

Note

The default value set by criAtomExOutputPort_SetDefaultConfig is 4.

Next:Meters