Wwise SDK 2024.1.1

Wwise의 오픈 아키텍처는, 사운드를 생성하는 음원 플러그인, 사운드를 향상키기는 효과 플러그인, Wwise에서 소스 컨트롤 소프트웨어를 사용할 수 있게 만드는 소스 컨트롤 플러인, 이렇게 세 가지 플러그인을 지원합니다. 음원 플러그인과 효과 플러그인은, XML 플러그인 설명 파일을 사용해 기본 속성 값과 같은 자신의 플러그인 설정을 코드 재컴파일 없이 빠르게 변경할 수 있도록 합니다. Wwise 플러그인 DLL에는 여러 플러그인이 들어갈 수 있으며, 연관 XML 파일에 설명돼있어야 합니다. 각 Wwise 플러그인 DLL의 XML 설명 파일은, XML 파일 확장자를 제외하고는 해당 DLL과 동일한 이름이어야 합니다. 예를 들어, 자신의 DLL 이름이 "MyPlugin.dll"이라면, 플러그인 설명 파일 또한 "MyPlugin.xml"이라는 이름이어야합니다.

Wwise 오픈 아키텍처 또한 Wwise 오브젝트의 커스텀 속성을 정의할 수 있도록 합니다. 플러그인을 정의하는 것과 거의 동일한 방식으로 Wwise 속성도 XML 설명을 통해 제어됩니다. 더 자세한 정보는 Defining 사용자 지정 속성 정의하기 을(를) 참고하세요.

속성 구성 요소

<Properties>
    ...
</Properties>

Properties 섹션에서 플러그인의 속성 및 레퍼런스를 정의합니다. Property 와 Reference 구성 요소는 XML에서와 동일한 방식으로 사용자 인터페이스에서 정리됩니다.

속성들은 플러그인의 사용자 인터페이스에서 사용자가 조정할 수 있는 슬라이더나 체크 상자와 같은 컨트롤에 해당되며, 사운드 엔진 플러그인 코드가 계산에 사용할 수 있는 값과 동일합니다.
레퍼런스는 Wwise 오브젝트의 레퍼런스를 담고 있는 영역에 해당됩니다. 프로젝트에 정의된 Game Parameter 오브젝트를 가리키는 레퍼런스가 한 예입니다.

Property 는 주로 다음과 같이 정의됩니다.

<Property Name="GainBand1" Type="Real32" SupportRTPCType="Exclusive" DataMeaning="Decibels" DisplayName="Band 1 Gain">
    <UserInterface Step="0.5" Fine="0.1" Decimals="1" />
    <DefaultValue>0</DefaultValue>
    <AudioEnginePropertyID>1</AudioEnginePropertyID>
    <Restrictions>
        <ValueRestriction>
            <Range Type="Real32">
                <Min>-24</Min>
                <Max>24</Max>
            </Range>
        </ValueRestriction>
    </Restrictions>
    <Dependencies>
        <PropertyDependency Name="OnOffBand1" Action="Enable">
            <Condition>
                <Enumeration Type="bool">
                    <Value>1</Value>
                </Enumeration>
            </Condition>
        </PropertyDependency>
    </Dependencies>
</Property>

Reference는 주로 다음과 같이 정의됩니다.

<Reference Name="OutputGameParameter" DisplayName="Output Game Parameter">
    <Restrictions>
        <TypeEnumerationRestriction>
            <Type Name="GameParameter" />
        </TypeEnumerationRestriction>
    </Restrictions>
</Reference>

Property 와 Reference 구성 요소에는 몇 가지 속성을 담을 수 있습니다:

Name [Property, Reference] (타입: string, 필수): Wwise 플러그인에서 사용되는 문자열 ID로서, 속성을 식별합니다. 다음과 같은 곳에서 사용됩니다:

Binding of properties to controls: 컨트롤을 이 속성에 바인딩하기 위해 플러그인의 대화창 리소스 (Prop=<Property Name>)에서 지정해야 하는 이름입니다.

Persistence: 이 속성과 관련된 데이터를 유지하기 위해 Wwise Project 파일 내 Property 구성 요소에 표시될 이름입니다.

경고: 기존 속성 이름을 변경하지 마세요. 자신의 플러그인을 사용하는 프로젝트는 사용자가 해당 속성에 설정해놓았던 모든 값과 랜더마이저, RTPC를 잃게 됩니다.

in_szPropertyName parameter in:
- AK::Wwise::Plugin::NotificationsPropertySet::NotifyPropertyChanged()
- AK::Wwise::Plugin::PropertyDisplayName::DisplayNameForProp()
- AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues()

참고: Property Name은 UI에 나타나는 이름은 아니지만, 사용자가 Project 파일에서 볼 수 있으므로 의미있게 만드는 것이 좋습니다. UI에 나타나는 이름은 DisplayName 속성에서 지정합니다.

참고: 커스텀 속성을 정의할 때에는 Name 속성에 반드시 "Custom"이라는 접두어를 붙여야 합니다. 더 자세한 정보는 Defining 사용자 지정 속성 정의하기 을(를) 참고하세요.

DisplayName [Property, Reference] (타입: string, 기본설정: 공란): Wwise 내 많은 곳에서 표시될 Property의 표시명을 정의합니다. This attribute supersedes the function AK::Wwise::Plugin::PropertyDisplayName::DisplayNameForProp.
DisplayGroup [Property, Reference] (타입: string, 기본설정: 공란): Tree 내 속성이나 레퍼런스를 체계적으로 정리할 때 사용하는 슬래시로 구분된 경로를 정의합니다. 예: "Audio/HDR"
IsVisible [Property, Reference] (타입: boolean, 기본설정: true, 선택 사항):기본 설정 값은 true 입니다. 아무 내용도 없을 경우, 해당 속성이 일반 편집기에 나타나게 됩니다. 속성 및 해당 값이 사용자에게 큰 의미가 없거나 일반 편집기(예: List View 내)에서 보여지지 않게 하려면 IsVisible 을 false 로 설정하세요.
Type [Property] (필수): 속성 타입입니다. Possible values are:
- bool: Boolean
- int16: 16-bit integer
- Uint16: 16-bit unsigned integer
- int32: 32-bit integer
- Uint32: 32-bit unsigned integer
- int64: 64-bit integer
- Uint64: 64-bit unsigned integer
- Real32: Single-precision float (32-bit)
- Real64: Double-precision float (64-bit)
- string: UTF-8, null-terminated character string
Plug-ins write properties to SoundBanks using the AK::Wwise::Plugin::DataWriter service, which supports writing any of the types listed above. Strings are serialized as null-terminated UTF-8 c-strings. Bool values are serialized as 1-byte values, where 1 stands for true and 0 for false.
In the case of custom properties added to a Wwise project, the values supported in SoundBanks are restricted to:
- int32: 32-bit integer
- Real32: Single-precision float (32-bit)
The bool type can still be used as custom properties, however values are interpreted as int32 where 1 stands for true and 0 for false. However, custom properties typed as Strings are not exported to SoundBanks because they cannot be represented numerically.
SupportLink [Property, Reference] (타입: boolean, 기본설정: false, 선택 사항): Property 나 Reference 가 Link/Unlink 기능 지원 여부를 정의합니다.
SupportStates [Property] (type: boolean, default: true, optional): Defines if the Property supports State mapping to control its value. Note that State mapping is only supported if the property also defines SupportRTPCType as either Additive or Boolean.
SupportRTPCType [Property] (type: string, default: undefined, optional): If not specified, the property will not support RTPCs. If specified, possible values are:
- Additive: The value computed from the RTPC curve will be added to the base property value of the object and to other RTPCs on the same property.
- Multiplicative: The value computed from the RTPC curve will be multiplied by the base property value of the object and by other RTPCs on the same property.
- Exclusive: The value computed from the RTPC curve has exclusive control over the property's value, completely overriding the value set in the property's control within the dialog. (That control will be disabled to make it clear to the Wwise user that it does not have any effect on the property.)
- Boolean: Equivalent logical operations are applied to enable or disable boolean properties. This attribute also enables State mapping to affect the property's value when the RTPC type is either Additive or Boolean.
ForceRTPCCurveSegmentShape [Property] (type: string, default: undefined, optional, used with SupportRTPCType): Restricts the possible segment shapes used in RTPC curves on this property. 특별히 지정되지 않을 경우, 곡선 내 어떤 세그먼트든 사용자가 자유롭게 형태를 변경할 수 있습니다. 특별히 지정할 경우, 사용할 수 있는 값은 다음과 같습니다.
- Constant: 곡선의 모든 세그먼트가 상수 보간(constant interpolation)을 사용한다는 것을 뜻합니다 (인접한 두 지점 사이 Y 값은 해당 짝의 가장 왼쪽 지점과 동일). 속성이 boolean이나 열거와 같이 분별 있는 값을 나타낼 때 사용하세요.
DataMeaning [Property] (타입: string, 기본설정: undefined, 선택 사항): 특별히 정의될 경우, 속성이 데시벨과 같이 특별한 타입의 데이터를 나타냅니다.

사용 가능한 값은 다음과 같습니다.
- Decibels: 이 속성은 데시벨을 나타냅니다. RTPC 곡선은 데시벨 척도를 기본으로 사용하지만, 사용자는 데시벨과 선형 척도 중 하나를 선택할 수 있습니다. 데시벨 척도는 지점 간 값들이 보간되는 방식에 영향을 미칩니다. 예를 들어, 0 dB과 -96.3 dB에 각각 지점 하나씩이 있을 경우, 정확히 두 지점 사이에서 평가된 선형 곡선 세그먼트가 선형 척도를 사용할 때는 -48.15 dB의 값을 생성하고, 데시벨 척도를 사용할 때는 -6 dB 정도를 생성합니다 (진폭의 이등분에 해당).
- Frequency: 이 속성은 Hz 단위의 주파수를 나타냅니다. 주파수 척도는 지점 간 값들이 보간되는 방식에 영향을 미칩니다. 예를 들어, 1000 Hz와 4000 Hz(두 옥타브 위)에 각각 지점이 하나씩 있을 경우, 정확히 두 지점 사이에서 평가된 선형 곡선 세그먼트가 선형 척도를 사용할 때는 2500 Hz의 값을 생성하고, 주파수 척도를 사용할 때는 2000 Hz의 값(한 오타브 위)을 생성합니다.

참고: 자신의 플러그인이 생성하는 사운드나 효과가 Wwise 사용자가 설정한 다음 게임 도중 바뀌지 않도록 만들 경우, RTPC를 지원하지 않도록 설정하세요.

DefaultValue 구성 요소는 속성의 기본값을 지정합니다. 이 기본값은 인스턴스를 생성할 때의 초기값을 나타내며, 사용자가 Ctrl 키를 누른 상태에서 속성의 컨트롤을 클릭할 때 속성이 초기화되는 값입니다. 이 값은 속성의 범위(아래) 및 타입( Property 구성 요소의 Type 속성으로 지정)과 일치해야 합니다.

작은 정보: XML 파일은 모든 텍스트 편집기나 XML 편집기로 편집할 수 있습니다. 주요 Wwise 설치 폴더 아래 "plugins" 폴더 내, 플러그인 DLL과 같은 폴더에 위치하고 있습니다. 커스텀 플러그인을 사용하는 Wwise 사용자는 자신의 플러그인의 XML 파일을 편집하여, 재컴파일할 필요 없이 플러그인 속성의 기본값을 변경할 수 있습니다. 이 변경에는 개발자 수준의 전문 지식이 필요하지 않습니다.

AudioEnginePropertyID 구성 요소는 Sound Engine 내 이 속성을 식별합니다. 이는 0-32767 범위 내 양의 정수여야 하며, wcustomproperties 파일만 예외적으로 0-150 범위여야 합니다. AudioEnginePropertyID 구성 요소에 설정한 값은 AK::IAkEffectParam::SetParam()의 AkFXParamID 매개 변수와 일치하므로, AK::IAkEffectParam::SetParam() 구현과 플러그인 설명 파일의 속성 ID가 동일하게 유지되도록 주의하세요.

UserInterface

UserInterface 구성 요소는 사용자 인터페이스의 작동 및 외관과 관련된 속성을 정의합니다. 다음 속성들은 모두 선택 사항이며 UserInterface 구성 요소에 설정할 수 있습니다.

DisplayName (타입: string, 기본설정: 공란): (추후 사용 중단) Wwise 내 많은 곳에서 표시될 Property의 표시명을 정의합니다. 이 속성은 Property 나 Reference 내 정의된 DisplayName 속성으로 대체됩니다.
Decimals (타입: integer, 기본설정: 0): 소수점 뒤에 표시될 숫자의 개수를 정의합니다. 이 값은 음수가 아닌 정수여야 합니다. 0으로 설정할 경우, 소수점을 포함한 그 뒤 숫자는 표시되지 않습니다.
Step (타입: float, 기본설정: 1): 슬라이더를 움직일 때 변하는 숫자 값의 양을 정의합니다. 이 값은 제어가 연결되는 속성의 타입에 따라 정수가 될 수도 있고 소수점 이하 숫자가 될 수도 있습니다.
Fine (타입: float, 기본설정: 1): Shift 키를 누른 상태에서 슬라이더를 움직일 때 변하는 숫자 값의 양을 정의합니다. 이 값은 제어가 연결되는 속성의 타입에 따라 정수가 될 수도 있고 소수점 이하 숫자가 될 수도 있습니다.
SliderType (타입: integer, 기본설정: 0): 전체 슬라이더 범위 값의 매핑을 정의합니다.
- 0: 선형 (기본 설정)
- 1: 의사 대수 (Pseudo-Logarithmic), -96.3 dB에서 0 dB 사이
- 2: 의사 대수 (Pseudo-Logarithmic), -96.3 dB에서 96.3 dB 사이
- 4: 의사 대수 (Pseudo-Logarithmic), 20 Hz에서 20000 Hz 사이
- 5: 의사 대수 (Pseudo-Logarithmic), 20 Hz에서 12000 Hz 사이
- 6: 의사 대수 (Pseudo-Logarithmic), -96.3 dB에서 12 dB 사이
- 11: 의사 대수 (Pseudo-Logarithmic), 0.02 Hz에서 20000 Hz 사이
- 12: 의사 대수 (Pseudo-Logarithmic), 0.02 Hz에서 20 Hz 사이
- 15: 의사 대수 (Pseudo-Logarithmic), -24 dB에서 24 dB 사이
- 16: 의사 대수 (Pseudo-Logarithmic), -96.3 dB에서 24 dB 사이
Mid (타입: float, 기본설정: 0): 중립으로 간주되는 [min,max] 범위 내 값을 정의합니다. 이 값은 슬라이더 컨트롤의 출력에 영향을 끼칩니다.
UIMin (타입: float, 기본설정: 범위의 Min 값): 슬라이더를 사용할 때 맨 처음 설정되는 최소 값을 정의합니다. 이 값이 Min 속성에 지정된 값보다 클 경우, 사용자가 더 작은 값을 직접 입력하면 제어의 범위가 넓어집니다.
UIMax (타입: float, 기본설정: 범위의 Max 값): 슬라이더를 사용할 때 처음 설정되는 최대 값을 정의합니다. 이 값이 Max 속성에 지정된 값보다 작을 경우, 사용자가 더 큰 값을 직접 입력하면 제어의 범위가 넓어집니다.
AutoUpdate (타입: boolean, 기본설정: false): 슬라이더를 움직이는 동안 값을 업데이트할 것인지 여부를 정의합니다. 오디오 성능 결함으로 인해 값을 너무 자주 업데이트할 경우 이 속성을 false 로 설정하세요.
LRMixDisplay (타입: boolean, 기본설정: false): 값을 특별한 Left-Right 균형 범위 방식으로 나타낼 지 여부를 정의합니다. 값 범위는 -100과 +100 사이여야 하며, 0이 Center인 Left to Right 균형/믹스로 매핑돼야 합니다.
ControlClass (타입: string, 기본설정: 공란): List View나 Multi Editor와 같은 뷰에서 속성에 사용되는 사용자 인터페이스 컨트롤을 정의합니다. 사용할 수 있는 값은 다음과 같습니다.
- ColorPicker: 색상 선택기.
- ReadOnlyText: 속성 값이 사용자 인터페이스에서 읽기 전용으로 됩니다.
DropDown (타입: string, 기본설정: 공란): 숫자 열거로 사용하면 (예: int16 타입의 Enumeration), Enumeration 의 각 값이 메뉴에 어떻게 나타날 지를 지정할 수 있습니다. 사용할 수 있는 값은 다음과 같습니다.
- Menu: 드롭다운 대신 해당되는 enum 값의 바로가기 메뉴를 나타냅니다. 메뉴의 경로는 Enumeration 내 Value 의 DisplayName 으로 정의됩니다. 예를 들어, "/Bus Volume/Reset Bus Volume" 값의 DisplayName 은 Reset Bus Volume을 하위 메뉴로 둔 Bus Volume 메뉴를 출력합니다. 이 메뉴를 클릭하면 속성을 14 값으로 설정합니다.
- CurveIn: 0에서 8 사이 해당되는 값에 대해 다음 함수들의 곡선(양의 기울기)을 표시합니다: Logarithmic (기본 3), Sine, Logarithmic (기본 1.41), Inverted S-Curve, Exponential (기본 1.41), Reciprocal Sine 및 Exponential (Base 3).
- CurveOut: 0에서 8 사이 해당되는 값에 대해 다음 함수들의 곡선(음의 기울기)을 표시합니다: Logarithmic (기본 3), Sine, Logarithmic (기본 1.41), Inverted S-Curve, Exponential (기본 1.41), Reciprocal Sine 및 Exponential (Base 3).

작은 정보: UIMin 와 UIMax 속성의 목적은, 속성 범위가 매우 클 경우 컨트롤 슬라이더의 최초 범위를 더 유용하게 사용할 수 있도록 하는 것입니다. 만약 특정 속성이 큰 이론적 범위를 갖고 있지만 일반적으로는 사용자가 제한적 범위를 사용하는 경우, Min/Max 속성을 이용해 실제 범위를 설정하고 UIMin/UIMax 속성을 이용해 슬라이더의 최초 범위를 설정합니다.

제한 사항

Wwise XML 설명은 속성 제한 사항 및 레퍼런스 제한 사항 을(를) 지정할 수 있습니다.

속성 제한 사항

속성에는 해당 데이터 값에 대해 선택 사항으로 다음 두 가지 제한 사항 중 하나가 있을 수 있습니다.

Range 제한에는 (Restrictions/ValueRestriction/Range 섹션), 숫자로 된 속성의 범위를 정의할 수 있습니다.

<Restrictions>
    <ValueRestriction>
        <Range Type="Real64">
            <Min>0</Min>
            <Max>100</Max>
        </Range>
    </ValueRestriction>
</Restrictions>

Enumeration 제한에는 (Restrictions/ValueRestriction/Enumeration 섹션), 각각의 표시명 및 사용 가능한 값의 목록을 정의할 수 있습니다.

<Restrictions>
    <ValueRestriction>
        <Enumeration Type="int32">
            <Value DisplayName="Low Pass">0</Value>
            <Value DisplayName="High Pass">1</Value>
            <Value DisplayName="Band Pass">2</Value>
            <Value DisplayName="Notch">3</Value>
            <Value DisplayName="Low Shelf">4</Value>
            <Value DisplayName="High Shelf">5</Value>
            <Value DisplayName="Peaking">6</Value>
        </Enumeration>
    </ValueRestriction>
</Restrictions>

bool 과 string 속성은 범위가 필요하지 않습니다. 이 범위는 RTPC Curve Editor를 비롯한 Wwise 내 여러 곳에서 사용되어 그래프의 Y 축 범위를 정의합니다.

이 파일의 포맷은, 주요 Wwise 설치 폴더 아래 "/Authoring/Data/Schemas" 폴더 내 Plugin.xsd XML Schema 파일에 공식적으로 설명돼있습니다.

레퍼런스 제한 사항

레퍼런스는 참조된 오브젝트에 대해 선택 사항으로 다음 제한 사항 중 하나의 목록을 가질 수 있습니다.

TypeEnumerationRestriction: 레퍼런스의 유효한 Wwise 오브젝트 타입 목록을 정의합니다.

<Restrictions>
    <TypeEnumerationRestriction>
        <Type Name="GameParameter" />
        ...
    </TypeEnumerationRestriction>
</Restrictions>

Type Name에는 다음과 같은 것들이 사용될 수 있습니다: ActorMixer, RandomSequenceContainer, SwitchContainer, BlendContainer, Sound, Bus, Event, SwitchGroup, Switch, State, GameParameter, MidiParameter, SoundBank, Effect, MusicSegment, MusicTrack, MusicTrackSequence, MusicPlaylistContainer, MusicSwitchContainer, Trigger, Attenuation, DialogueEvent, MotionBus, MotionFX, Conversion, AuxBus, ModulatorLfo, ModulatorEnvelope.

CategoryEnumerationRestriction: 레퍼런스의 유효한 Wwise 오브젝트 카테고리 목록을 정의합니다.

<Restrictions>
    <CategoryEnumerationRestriction>
        <Category Name="AudioObjects" />
        ...
    </CategoryEnumerationRestriction>
</Restrictions>

Category Name에는 다음과 같은 것들이 사용될 수 있습니다: Busses, AudioObjects, Events, Switches, States, SoundBanks, GameParameters, Effects, AudioDevices, Presets, SoundcasterSessions, MixingSessions, Queries, InteractiveMusic, Triggers, Attenuations, DynamicDialogue, Conversions, Modulators, ControlSurfaceSessions.

PlayableRestriction: 오브젝트가 재생 가능해야 하는지 여부를 정의합니다.

<Restrictions>
    <PlayableRestriction />
</Restrictions>

NotNullRestriction: 오브젝트가 null이 되서는 안 될지 여부를 정의합니다.

<Restrictions>
    <NotNullRestriction />
</Restrictions>

의존성

속성이나 레퍼런스는 의존성이 아예 없거나 여러 개를 가질 수도 있습니다. 의존성은 속성들을 서로 연결할 수 있게 만들어, 다른 속성의 값에 따라 한 속성이 활성화 또는 비활성화될 수 있도록 합니다.

현재 의존성은 다음 상황에서만 사용된다는 점에 주의하세요.

Property Editor - All Properties 탭
Effect의 Default User Interface (but 소스 제외)
List View
Multi Editor
Query View
Reference View

The dependencies are not being used in the Effect Editor if you implement your own user interface by providing a dialog in AK::Wwise::Plugin::AudioPlugin::GetDialog(). 활성화 또는 비활성화된 State는 플러그인의 사용자 인터페이스에 구현돼야 합니다.

다음 예제는 "GainBand1"에서 "OnOffBand1"로 의존성을 추가합니다. "OnOffBand1"이 "True"로 됐을 때 "GainBand1" 속성이 활성화됩니다.

<Property Name="GainBand1" ...>
    <...>
    <Dependencies>
        <PropertyDependency Name="OnOffBand1" Action="Enable">
            <Condition>
                <Enumeration Type="bool">
                    <Value>True</Value>
                </Enumeration>
            </Condition>
        </PropertyDependency>
    </Dependencies>
</Property>

Condition 구성 요소는 Enumeration 구성 요소나 Range 구성 요소 중 하나를 담을 수 있습니다. PropertyDependency 구성 요소 안에 지정된 Action 구성 요소는 "Enable"이어야 합니다. 조건이 충족됐을 때 해당 속성이 활성화되는 것을 지정합니다.

Enumeration 조건:

<Enumeration Type="int32">
    <Value>0</Value>
    <Value>1</Value>
</Enumeration>

Range 조건:

<Range Type="Real32">
    <Min>-24</Min>
    <Max>24</Max>
</Range>

또한, Context 속성은 PropertyDependency 에 지정될 수 있어 Condition 이 평가되는 오브젝트를 변경합니다. Context 속성은 "Parent"나 "Self" 중 하나로 설정할 수 있으며, 명백하게 주어진 것이 없을 경우에는 기본 설정을 "Self"로 할 수 있습니다.

이전 예제에 이어서, PropertyDependency 에 콘텍스트를 추가하면 현재 오브젝트의 상위 오브젝트에서 "OnOffBand1"이 "True"로 설정됐을 때 "GainBand1" 속성이 활성화됩니다.

<Property Name="GainBand1" ...>
    <...>
    <Dependencies>
        <PropertyDependency Name="OnOffBand1" Action="Enable" Context="Parent">
            <Condition>
                <Enumeration Type="bool">
                    <Value>True</Value>
                </Enumeration>
            </Condition>
        </PropertyDependency>
    </Dependencies>
</Property>