Wwise Version
Wwise SDK 2021.1.5
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.5 Build: 7749
25  Copyright (c) 2006-2021 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  */
44 #ifdef __cplusplus
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.
55 
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  */
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  */
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  {
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  */
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  */
160  };
161 
162  /**
163  * \brief The C interface, fulfilled by your plug-in.
164  */
166  {
169  {
171  [](
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  };
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 
197  static Interface g_interface;
198  return &g_interface;
199  }
201  return this;
202  }
204  return this;
205  }
206 
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  */
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.
278  /// Latest version of the C++ PropertyDisplayName interface.
280 
283 } // of namespace AK::Wwise::Plugin
284 
285 #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:968
@ 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:722
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)