Version
menu_open
Wwise SDK 2023.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) 2024 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  */
43 #ifdef __cplusplus
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.
54 
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  */
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  */
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  {
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  */
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  */
159  };
160 
161  /**
162  * \brief The C interface, fulfilled by your plug-in.
163  */
165  {
168  {
170  [](
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  };
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 
196  static Interface g_interface;
197  return &g_interface;
198  }
200  return this;
201  }
203  return this;
204  }
205 
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  */
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.
277  /// Latest version of the C++ PropertyDisplayName interface.
279 
282 } // of namespace AK::Wwise::Plugin
283 
284 #endif
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.
ak_wwise_plugin_property_display_name_v1 CPropertyDisplayName
CPropertyDisplayName::Instance * GetInstancePointer()
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
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.
Wwise Authoring Plug-ins - C++ class helper to automatically determine the plug-in interfaces used in...
CInterfacePtr InterfacePtr
Definition: PluginDef.h:995
@ k_interfaceType
The interface type, as provided by this plug-in.
The C interface, fulfilled by your plug-in.
Base instance type for providing display names to properties through ak_wwise_plugin_property_display...
Definition: PluginDef.h:738
const CPropertyDisplayName::Instance * GetInstancePointer() const
std::underlying_type< InterfaceType >::type InterfaceTypeValue
PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface.
@ k_interfaceVersion
The interface version, as provided by this plug-in.
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_PROPERTY_DISPLAY_NAME
2021.1 Property display name overrides. ak_wwise_plugin_property_display_name_v1
Backend API to specify display names for properties.
virtual bool DisplayNameForProp(const char *in_pszPropertyName, char *out_pszDisplayName, uint32_t in_unCharCount) const
Gets the user-friendly name of the specified property.
Interface description and base class for every Wwise Authoring plug-in interface.
V1::PropertyDisplayName PropertyDisplayName
Latest version of the C++ PropertyDisplayName interface.
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.
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