menu
search
language
English
Français
日本語
한국어
中文
Wwise
arrow_drop_down
Strata
arrow_drop_down
Solutions
arrow_drop_down
Learning
arrow_drop_down
Community
arrow_drop_down
Documentation
arrow_drop_down
Help
arrow_drop_down
Sign In
Download
 
Version
2021.1.14.8108
arrow_drop_down

2024.1.4.8780

2023.1.12.8706

2022.1.18.8567

2021.1.14.8108

2019.2.15.7667

2019.1.11.7296

2018.1.11.6987

2017.2.10.6745

2017.1.9.6501

2016.2.6.6153

2015.1.9.5624

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