Version
menu_open
Wwise SDK 2024.1.4
PropertyDisplayName.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Copyright (c) 2025 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 /**
28  * \brief Wwise Authoring Plug-ins - Plug-in API for property display name.
29  * \file AK/Wwise/Plugin/PropertyDisplayName.h
30  */
31 
32 #pragma once
33 
34 #include "PluginInfoGenerator.h"
35 
36 /**
37  * \brief Backend API to specify display names for properties
38  *
39  * \aknote It is preferrable to specify names directly in the XML. This interface can be useful when implementing
40  * properties that have different meanings dependending on the state of other properties. \endaknote
41  */
42 struct ak_wwise_plugin_property_display_name_v1
43 #ifdef __cplusplus
44  : public ak_wwise_plugin_base_interface
45 #endif
46 {
47 #ifndef __cplusplus
48  ak_wwise_plugin_base_interface m_baseInterface;
49 #endif
50 
51 #ifdef __cplusplus
52  /// Base instance type for providing display names to properties.
53  using Instance = ak_wwise_plugin_property_display_name_instance_v1;
54 
55  ak_wwise_plugin_property_display_name_v1() :
56  ak_wwise_plugin_base_interface(AK_WWISE_PLUGIN_INTERFACE_TYPE_PROPERTY_DISPLAY_NAME, 1)
57  {}
58 #endif
59 
60  /**
61  * \brief Gets the user-friendly name of the specified property.
62  *
63  * This function should write the user-friendly name of the specified property to the char buffer
64  * out_pszDisplayName, which is of maximum length in_unCharCount.
65  *
66  * \aknote This function used to be deprecated, but is actually useful in case of dynamic naming.
67  * As such, it has been reinstated. However, its usage is still not preferred. By default,
68  * you should provide your naming inside the XML, and use this function only in cases
69  * where you cannot reliably name the property in your XML. For example, you might have
70  * a switch between two modes, and the same property might have two different names. This
71  * function can then be used for this particular case. \endaknote
72  *
73  * \param[in] in_this Current instance of this interface.
74  * \param[in] in_pszPropertyName The internal name of the property.
75  * \param[out] out_pszDisplayName The returned user-friendly name, as a null-terminated string.
76  * \param[in] in_unCharCount The maximum number of char in the buffer, including the terminating null.
77  * \return true if the property has a user-friendly name.
78  */
79  bool(*DisplayNameForProp)(
80  const struct ak_wwise_plugin_property_display_name_instance_v1* in_this,
81  const char * in_pszPropertyName,
82  char * out_pszDisplayName,
83  uint32_t in_unCharCount
84  );
85 
86  /**
87  * \brief Get the user-friendly names of possible values for the specified property.
88  *
89  * This function should write pairs of value and text for the specified property to
90  * the WCHAR buffer out_pszDisplayName, which is of length in_unCharCount.
91  *
92  * Pairs are separated by commas, and each pair contains the value and the
93  * text, separated by a colon.
94  *
95  * Here are a few examples:
96  * - Numeric property: "-100:Left,0:Center,100:Right"
97  * - Boolean property: "0:Off,1:On"
98  * - Numeric property seen as an enumeration:
99  * "0:Low Pass,1:High Pass,2:Band Pass,3:Notch,4:Low Shelf,5:High Shelf,6:Peaking"
100  *
101  * \aknote This function used to be deprecated, but is actually useful in case of dynamic naming.
102  * As such, it has been reinstated. However, its usage is still not preferred. By default,
103  * you should provide your naming inside the XML, and use this function only in cases
104  * where you cannot reliably name the property in your XML. For example, you might have
105  * a switch between two modes, and the same property might have two different names. This
106  * function can then be used for this particular case. \endaknote
107  *
108  * \param[in] in_this Current instance of this interface.
109  * \param[in] in_pszPropertyName The internal name of the property.
110  * \param[out] out_pszValuesName The returned property value names, as a null-terminated string.
111  * \param[in] in_unCharCount The maximum number of char in the buffer, including the terminating null.
112  * \return true if the property has a user-friendly value name.
113  *
114  * \sa
115  * - \ref wwiseplugin_displaynames
116  */
117  bool(*DisplayNamesForPropValues)(
118  const struct ak_wwise_plugin_property_display_name_instance_v1* in_this,
119  const char * in_pszPropertyName,
120  char * out_pszValuesName,
121  uint32_t in_unCharCount
122  );
123 };
124 #define AK_WWISE_PLUGIN_PROPERTY_DISPLAY_NAME_V1_ID() \
125  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_PROPERTY_DISPLAY_NAME, 1)
126 #define AK_WWISE_PLUGIN_PROPERTY_DISPLAY_NAME_V1_CTOR(/* ak_wwise_plugin_info* */ in_pluginInfo, /* void* */ in_data) \
127 { \
128  .m_baseInterface = AK_WWISE_PLUGIN_BASE_INTERFACE_CTOR(AK_WWISE_PLUGIN_PROPERTY_DISPLAY_NAME_V1_ID(), in_pluginInfo, in_data) \
129 }
130 
131 #ifdef __cplusplus
132 namespace AK::Wwise::Plugin
133 {
134  namespace V1
135  {
136  using CPropertyDisplayName = ak_wwise_plugin_property_display_name_v1;
137  class PropertyDisplayName : public CPropertyDisplayName::Instance
138  {
139  public:
140  /**
141  * \brief The interface type, as provided by this plug-in.
142  */
143  enum : InterfaceTypeValue
144  {
145  /**
146  * \brief The interface type, as provided by this plug-in.
147  */
148  k_interfaceType = AK_WWISE_PLUGIN_INTERFACE_TYPE_PROPERTY_DISPLAY_NAME
149  };
150  /**
151  * \brief The interface version, as provided by this plug-in.
152  */
153  enum : InterfaceVersion
154  {
155  /**
156  * \brief The interface version, as provided by this plug-in.
157  */
158  k_interfaceVersion = 1
159  };
160 
161  /**
162  * \brief The C interface, fulfilled by your plug-in.
163  */
164  struct Interface : public CPropertyDisplayName
165  {
166  using Instance = PropertyDisplayName;
167  Interface()
168  {
169  CPropertyDisplayName::DisplayNameForProp =
170  [](
171  const struct ak_wwise_plugin_property_display_name_instance_v1* in_this,
172  const char * in_pszPropertyName,
173  char * out_pszDisplayName,
174  uint32_t in_unCharCount)
175  {
176  return (bool)static_cast<const Instance*>(in_this)->DisplayNameForProp(
177  in_pszPropertyName,
178  out_pszDisplayName,
179  in_unCharCount);
180  };
181  CPropertyDisplayName::DisplayNamesForPropValues = [](
182  const struct ak_wwise_plugin_property_display_name_instance_v1* in_this,
183  const char * in_pszPropertyName,
184  char * out_pszValuesName,
185  uint32_t in_unCharCount)
186  {
187  return (bool)static_cast<const Instance*>(in_this)->DisplayNamesForPropValues(
188  in_pszPropertyName,
189  out_pszValuesName,
190  in_unCharCount);
191  };
192  }
193  };
194 
195  InterfacePtr GetInterfacePointer() {
196  static Interface g_interface;
197  return &g_interface;
198  }
199  CPropertyDisplayName::Instance* GetInstancePointer() {
200  return this;
201  }
202  const CPropertyDisplayName::Instance* GetInstancePointer() const {
203  return this;
204  }
205 
206  PropertyDisplayName() :
207  CPropertyDisplayName::Instance()
208  {
209  }
210 
211  virtual ~PropertyDisplayName() {}
212 
213  /**
214  * \brief Gets the user-friendly name of the specified property.
215  *
216  * This function should write the user-friendly name of the specified property to the char buffer
217  * out_pszDisplayName, which is of maximum length in_unCharCount.
218  *
219  * \aknote This function used to be deprecated, but is actually useful in case of dynamic naming.
220  * As such, it has been reinstated. However, its usage is still not preferred. By default,
221  * you should provide your naming inside the XML, and use this function only in cases
222  * where you cannot reliably name the property in your XML. For example, you might have
223  * a switch between two modes, and the same property might have two different names. This
224  * function can then be used for this particular case. \endaknote
225  *
226  * \param[in] in_pszPropertyName The internal name of the property.
227  * \param[out] out_pszDisplayName The returned user-friendly name, as a null-terminated string.
228  * \param[in] in_unCharCount The maximum number of char in the buffer, including the terminating null.
229  * \return true if the property has a user-friendly name.
230  */
231  virtual bool DisplayNameForProp(
232  const char * in_pszPropertyName,
233  char * out_pszDisplayName,
234  uint32_t in_unCharCount
235  ) const { return false; }
236 
237  /**
238  * \brief Get the user-friendly names of possible values for the specified property.
239  *
240  * This function should write pairs of value and text for the specified property to
241  * the WCHAR buffer out_pszDisplayName, which is of length in_unCharCount.
242  *
243  * Pairs are separated by commas, and each pair contains the value and the
244  * text, separated by a colon.
245  *
246  * Here are a few examples:
247  * - Numeric property: "-100:Left,0:Center,100:Right"
248  * - Boolean property: "0:Off,1:On"
249  * - Numeric property seen as an enumeration:
250  * "0:Low Pass,1:High Pass,2:Band Pass,3:Notch,4:Low Shelf,5:High Shelf,6:Peaking"
251  *
252  * \aknote This function used to be deprecated, but is actually useful in case of dynamic naming.
253  * As such, it has been reinstated. However, its usage is still not preferred. By default,
254  * you should provide your naming inside the XML, and use this function only in cases
255  * where you cannot reliably name the property in your XML. For example, you might have
256  * a switch between two modes, and the same property might have two different names. This
257  * function can then be used for this particular case. \endaknote
258  *
259  * \param[in] in_pszPropertyName The internal name of the property.
260  * \param[out] out_pszValuesName The returned property value names, as a null-terminated string.
261  * \param[in] in_unCharCount The maximum number of char in the buffer, including the terminating null.
262  * \return true if the property has a user-friendly value name.
263  *
264  * \sa
265  * - \ref wwiseplugin_displaynames
266  */
267  virtual bool DisplayNamesForPropValues(
268  const char * in_pszPropertyName,
269  char * out_pszValuesName,
270  uint32_t in_unCharCount
271  ) const { return false; }
272  };
273  } // of namespace V1
274 
275  /// Latest version of the C PropertyDisplayName interface.
276  using CPropertyDisplayName = V1::CPropertyDisplayName;
277  /// Latest version of the C++ PropertyDisplayName interface.
278  using PropertyDisplayName = V1::PropertyDisplayName;
279 
280  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(PropertyDisplayName);
281  AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(PropertyDisplayName);
282 } // of namespace AK::Wwise::Plugin
283 
284 #endif
AK.Wwise::Plugin::V1::PropertyDisplayName::DisplayNamesForPropValues
virtual bool DisplayNamesForPropValues(const char *in_pszPropertyName, char *out_pszValuesName, uint32_t in_unCharCount) const
Get the user-friendly names of possible values for the specified property.
Definition: PropertyDisplayName.h:267
AK.Wwise::Plugin::V1::CPropertyDisplayName
ak_wwise_plugin_property_display_name_v1 CPropertyDisplayName
Definition: PropertyDisplayName.h:136
AK.Wwise::Plugin::V1::PropertyDisplayName::GetInstancePointer
CPropertyDisplayName::Instance * GetInstancePointer()
Definition: PropertyDisplayName.h:199
AK.Wwise::Plugin::InterfaceVersion
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
Definition: PluginInfoGenerator.h:50
ak_wwise_plugin_property_display_name_v1::DisplayNamesForPropValues
bool(* DisplayNamesForPropValues)(const struct ak_wwise_plugin_property_display_name_instance_v1 *in_this, const char *in_pszPropertyName, char *out_pszValuesName, uint32_t in_unCharCount)
Get the user-friendly names of possible values for the specified property.
Definition: PropertyDisplayName.h:117
PluginInfoGenerator.h
Wwise Authoring Plug-ins - C++ class helper to automatically determine the plug-in interfaces used in...
AK.Wwise::Plugin::InterfacePtr
CInterfacePtr InterfacePtr
Definition: PluginDef.h:1057
AK.Wwise::Plugin::V1::PropertyDisplayName::k_interfaceType
@ k_interfaceType
The interface type, as provided by this plug-in.
Definition: PropertyDisplayName.h:148
AK.Wwise::Plugin::V1::PropertyDisplayName::Interface
The C interface, fulfilled by your plug-in.
Definition: PropertyDisplayName.h:165
ak_wwise_plugin_property_display_name_instance_v1
Base instance type for providing display names to properties through ak_wwise_plugin_property_display...
Definition: PluginDef.h:760
AK.Wwise::Plugin::V1::PropertyDisplayName::GetInstancePointer
const CPropertyDisplayName::Instance * GetInstancePointer() const
Definition: PropertyDisplayName.h:202
AK.Wwise::Plugin::InterfaceTypeValue
std::underlying_type< InterfaceType >::type InterfaceTypeValue
PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface.
Definition: PluginInfoGenerator.h:49
AK.Wwise::Plugin::V1::PropertyDisplayName::k_interfaceVersion
@ k_interfaceVersion
The interface version, as provided by this plug-in.
Definition: PropertyDisplayName.h:158
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
AK_WWISE_PLUGIN_INTERFACE_TYPE_PROPERTY_DISPLAY_NAME
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_PROPERTY_DISPLAY_NAME
2021.1 Property display name overrides. ak_wwise_plugin_property_display_name_v1
Definition: PluginBaseInterface.h:68
ak_wwise_plugin_property_display_name_v1
Backend API to specify display names for properties.
Definition: PropertyDisplayName.h:46
AK.Wwise::Plugin::V1::PropertyDisplayName::DisplayNameForProp
virtual bool DisplayNameForProp(const char *in_pszPropertyName, char *out_pszDisplayName, uint32_t in_unCharCount) const
Gets the user-friendly name of the specified property.
Definition: PropertyDisplayName.h:231
ak_wwise_plugin_base_interface
Interface description and base class for every Wwise Authoring plug-in interface.
Definition: PluginBaseInterface.h:120
AK.Wwise::Plugin::PropertyDisplayName
V1::PropertyDisplayName PropertyDisplayName
Latest version of the C++ PropertyDisplayName interface.
Definition: PropertyDisplayName.h:278
ak_wwise_plugin_property_display_name_v1::DisplayNameForProp
bool(* DisplayNameForProp)(const struct ak_wwise_plugin_property_display_name_instance_v1 *in_this, const char *in_pszPropertyName, char *out_pszDisplayName, uint32_t in_unCharCount)
Gets the user-friendly name of the specified property.
Definition: PropertyDisplayName.h:79
ak_wwise_plugin_property_display_name_v1::ak_wwise_plugin_property_display_name_v1
ak_wwise_plugin_property_display_name_v1()
Definition: PropertyDisplayName.h:55
AK.Wwise::Plugin::AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(AudioPlugin)

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise