Version
menu

Wwise SDK 2023.1.14
AkCommonDefs.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 // AkCommonDefs.h
28 
29 /// \file
30 /// AudioLib common defines, enums, and structs.
31 
32 
33 #ifndef _AK_COMMON_DEFS_H_
34 #define _AK_COMMON_DEFS_H_
35 
42 
43 //-----------------------------------------------------------------------------
44 // AUDIO DATA FORMAT
45 //-----------------------------------------------------------------------------
46 
47 // Audio data format.
48 // ------------------------------------------------
49 
50 const AkDataTypeID AK_INT = 0; ///< Integer data type (uchar, short, and so on)
51 const AkDataTypeID AK_FLOAT = 1; ///< Float data type
52 
53 const AkDataInterleaveID AK_INTERLEAVED = 0; ///< Interleaved data
54 const AkDataInterleaveID AK_NONINTERLEAVED = 1; ///< Non-interleaved data
55 
56 // Native format currently the same on all supported platforms, may become platform specific in the future
57 const AkUInt32 AK_LE_NATIVE_BITSPERSAMPLE = 32; ///< Native number of bits per sample.
58 const AkUInt32 AK_LE_NATIVE_SAMPLETYPE = AK_FLOAT; ///< Native data type.
59 const AkUInt32 AK_LE_NATIVE_INTERLEAVE = AK_NONINTERLEAVED; ///< Native interleaved setting.
60 
61 /// Defines the parameters of an audio buffer format.
63 {
64  AkUInt32 uSampleRate; ///< Number of samples per second
65 
66  AkChannelConfig channelConfig; ///< Channel configuration.
67 
68  AkUInt32 uBitsPerSample :6; ///< Number of bits per sample.
69  AkUInt32 uBlockAlign :10;///< Number of bytes per sample frame. (For example a 5.1 PCM 16bit should have a uBlockAlign equal to 6(5.1 channels)*2(16 bits per sample) = 12.
70  AkUInt32 uTypeID :2; ///< Data type ID (AkDataTypeID).
71  AkUInt32 uInterleaveID :1; ///< Interleave ID (AkDataInterleaveID).
72 
73  /// Get the number of channels.
74  /// \return The number of channels
76  {
78  }
79 
80  /// Query if LFE channel is present.
81  /// \return True when LFE channel is present
82  AkForceInline bool HasLFE() const
83  {
84  return channelConfig.HasLFE();
85  }
86 
87  /// Query if center channel is present.
88  /// Note that mono configurations have one channel which is arbitrary set to AK_SPEAKER_FRONT_CENTER,
89  /// so HasCenter() returns true for mono signals.
90  /// \return True when center channel is present and configuration has more than 2 channels.
91  AkForceInline bool HasCenter() const
92  {
93  return channelConfig.HasCenter();
94  }
95 
96  /// Get the number of bits per sample.
97  /// \return The number of bits per sample
99  {
100  return uBitsPerSample;
101  }
102 
103  /// Get the block alignment.
104  /// \return The block alignment
106  {
107  return uBlockAlign;
108  }
109 
110  /// Get the data sample format (Float or Integer).
111  /// \return The data sample format
113  {
114  return uTypeID;
115  }
116 
117  /// Get the interleaved type.
118  /// \return The interleaved type
120  {
121  return uInterleaveID;
122  }
123 
124  /// Set all parameters of the audio format structure.
125  /// Channels are specified by channel mask (standard configs).
126  void SetAll(
127  AkUInt32 in_uSampleRate, ///< Number of samples per second
128  AkChannelConfig in_channelConfig, ///< Channel configuration
129  AkUInt32 in_uBitsPerSample, ///< Number of bits per sample
130  AkUInt32 in_uBlockAlign, ///< Block alignment
131  AkUInt32 in_uTypeID, ///< Data sample format (Float or Integer)
132  AkUInt32 in_uInterleaveID ///< Interleaved type
133  )
134  {
135  uSampleRate = in_uSampleRate;
136  channelConfig = in_channelConfig;
137  uBitsPerSample = in_uBitsPerSample;
138  uBlockAlign = in_uBlockAlign;
139  uTypeID = in_uTypeID;
140  uInterleaveID = in_uInterleaveID;
141  }
142 
143  AkForceInline bool operator==(const AkAudioFormat & in_other) const
144  {
145  return uSampleRate == in_other.uSampleRate
146  && channelConfig == in_other.channelConfig
147  && uBitsPerSample == in_other.uBitsPerSample
148  && uBlockAlign == in_other.uBlockAlign
149  && uTypeID == in_other.uTypeID
150  && uInterleaveID == in_other.uInterleaveID;
151  }
152 
153  AkForceInline bool operator!=(const AkAudioFormat & in_other) const
154  {
155  return uSampleRate != in_other.uSampleRate
156  || channelConfig != in_other.channelConfig
157  || uBitsPerSample != in_other.uBitsPerSample
158  || uBlockAlign != in_other.uBlockAlign
159  || uTypeID != in_other.uTypeID
160  || uInterleaveID != in_other.uInterleaveID;
161  }
162 };
163 
164 typedef AkUInt8(*AkChannelMappingFunc)(const AkChannelConfig &config, AkUInt8 idx);
165 
167 {
168  SourceChannelOrdering_Standard = 0, // Microsoft L-R-C-LFE-RL-RR-RC-SL-SR-HL-HR-HC-HRL-HRR-HRC-T
169  // or ACN ordering + SN3D norm
170 
171  SourceChannelOrdering_Film, // L-C-R-SL-SR-LFE
173  SourceChannelOrdering_Last // End of enum, invalid value.
174 };
175 
176 #define AK_MAKE_CHANNELCONFIGOVERRIDE(_config,_order) ((AkInt64)_config.Serialize()|((AkInt64)_order<<32))
177 #define AK_GET_CHANNELCONFIGOVERRIDE_CONFIG(_over) (_over&UINT_MAX)
178 #define AK_GET_CHANNELCONFIGOVERRIDE_ORDERING(_over) ((AkSourceChannelOrdering)(_over>>32))
179 
180 // Build a 32 bit class identifier based on the Plug-in type,
181 // CompanyID and PluginID.
182 //
183 // Parameters:
184 // - in_pluginType: A value from enum AkPluginType (4 bits)
185 // - in_companyID: CompanyID as defined in the Plug-in's XML file (12 bits)
186 // * 0-63: Reserved for Audiokinetic
187 // * 64-255: Reserved for clients' in-house Plug-ins
188 // * 256-4095: Assigned by Audiokinetic to third-party plug-in developers
189 // - in_pluginID: PluginID as defined in the Plug-in's XML file (16 bits)
190 // * 0-32767: Set freely by the Plug-in developer
191 #define AKMAKECLASSID( in_pluginType, in_companyID, in_pluginID ) \
192  ( (in_pluginType) + ( (in_companyID) << 4 ) + ( (in_pluginID) << ( 4 + 12 ) ) )
193 
194 #define AKGETPLUGINTYPEFROMCLASSID( in_classID ) ( (in_classID) & AkPluginTypeMask )
195 #define AKGETCOMPANYIDFROMCLASSID( in_classID ) ( ( (in_classID) & 0x0000FFF0 ) >> 4 )
196 #define AKGETPLUGINIDFROMCLASSID( in_classID ) ( ( (in_classID) & 0xFFFF0000 ) >> ( 4 + 12 ) )
197 
198 #define CODECID_FROM_PLUGINID AKGETPLUGINIDFROMCLASSID
199 
200 
201 namespace AK
202 {
203  /// Struct containing metering information about a buffer. Depending on when this struct is generated, you may get metering data computed in the previous frame only.
204  struct AkMetering
205  {
206  /// Peak of each channel in this frame.
207  /// Vector of linear peak levels, corresponding to each channel. NULL if AK_EnableBusMeter_Peak is not set (see IAkMixerPluginContext::SetMeteringFlags() or AK::SoundEngine::RegisterBusMeteringCallback()).
209 
210  /// True peak of each channel (as defined by ITU-R BS.1770) in this frame.
211  /// Vector of linear true peak levels, corresponding to each channel. NULL if AK_EnableBusMeter_TruePeak is not set (see IAkMixerPluginContext::SetMeteringFlags() or AK::SoundEngine::RegisterBusMeteringCallback()).
213 
214  /// RMS value of each channel in this frame.
215  /// Vector of linear rms levels, corresponding to each channel. NULL if AK_EnableBusMeter_RMS is not set (see IAkMixerPluginContext::SetMeteringFlags() or AK::SoundEngine::RegisterBusMeteringCallback()).
217 
218  /// Mean k-weighted power value in this frame, used to compute loudness (as defined by ITU-R BS.1770).
219  /// Total linear k-weighted power of all channels. 0 if AK_EnableBusMeter_KPower is not set (see IAkMixerPluginContext::SetMeteringFlags() or AK::SoundEngine::RegisterBusMeteringCallback()).
221  };
222 
223  static inline bool IsBankCodecID(AkUInt32 in_codecID)
224  {
225  return in_codecID == AKCODECID_BANK ||
226  in_codecID == AKCODECID_BANK_EVENT ||
227  in_codecID == AKCODECID_BANK_BUS;
228  }
229 }
230 
231 // 3D Audio Object.
232 // ------------------------------------------------
233 
234 /// Default listener transform.
235 #define AK_DEFAULT_LISTENER_POSITION_X (0.0f) // at coordinate system's origin
236 #define AK_DEFAULT_LISTENER_POSITION_Y (0.0f)
237 #define AK_DEFAULT_LISTENER_POSITION_Z (0.0f)
238 #define AK_DEFAULT_LISTENER_FRONT_X (0.0f) // looking toward Z,
239 #define AK_DEFAULT_LISTENER_FRONT_Y (0.0f)
240 #define AK_DEFAULT_LISTENER_FRONT_Z (1.0f)
241 #define AK_DEFAULT_TOP_X (0.0f) // top towards Y
242 #define AK_DEFAULT_TOP_Y (1.0f)
243 #define AK_DEFAULT_TOP_Z (0.0f)
244 
245 
246 /// 3D data needed for 3D spatialization.
247 /// Undergoes transformations based on emitter-listener placement.
248 struct Ak3dData
249 {
251  : spread(1.f)
252  , focus(1.f)
253  , uEmitterChannelMask(0xffffffff)
254  {
256  }
257 
258  AkTransform xform; ///< Object position / orientation.
259  AkReal32 spread; ///< Spread [0,1]
260  AkReal32 focus; ///< Focus [0,1]
261  AkChannelMask uEmitterChannelMask; ///< Emitter channel mask. With 3D spatialization, zeroed channels should be dropped.
262 };
263 
264 /// Positioning data inherited from sound structures and mix busses.
266 {
268  : center(1.f)
269  , panLR(0.f)
270  , panBF(0.f)
271  , panDU(0.f)
272  , panSpatMix(1.f)
275  , enableHeightSpread(true)
276  {}
277 
278  AkReal32 center; ///< Center percentage [0,1]
279  AkReal32 panLR; ///< Pan left-right [-1,1]
280  AkReal32 panBF; ///< Pan back-front [-1,1]
281  AkReal32 panDU; ///< Pan down-up [-1,1]
282  AkReal32 panSpatMix; ///< Panning vs 3D spatialization mix ([0,1], 1 being 100% spatialized).
283  Ak3DSpatializationMode spatMode; ///< 3D spatialization mode.
284  AkSpeakerPanningType panType; ///< Speaker panning type.
285  bool enableHeightSpread; ///< When true, audio objects 3D spatialized onto a planar channel configuration will be given a minimum spread value based on their elevation angle, equal to sin(elevation)**2.
286 };
287 
288 /// Positioning data of 3D audio objects.
290 {
291  Ak3dData threeD; ///< 3D data used for 3D spatialization.
292  AkBehavioralPositioningData behavioral; ///< Positioning data inherited from sound structures and mix busses.
293 };
294 
295 // Forward defines
296 namespace AK
297 {
298  class IAkPluginParam;
299 }
300 
301 /// An audio object refers to an audio signal with some attached metadata going through the sound engine pipeline.
302 /// The AkAudioObject struct encapsulates the metadata part. The signal itself is contained in a separate AkAudioBuffer instance.
304 {
305  /// Constructor
308  ,cumulativeGain(1.f, 1.f)
311  {}
312 
313  /// Destructor
315  {
317  objectName.Term();
318  }
319 
320  static const AkUInt64 kObjectKeyNumBits = 56;
321  static const AkUInt64 kObjectKeyMask = (((AkUInt64)1 << kObjectKeyNumBits) - 1);
322 
323  AkAudioObjectID key; ///< Unique ID, local to a given bus. Only the lower 56 of 64 bits are used for the object itself. The highest 8 bits are available for channel indexing.
324 
325  AkPositioningData positioning; ///< Positioning data for deferred 3D rendering.
326  AkRamp cumulativeGain; ///< Cumulative ramping gain to apply when mixing down to speaker bed or final endpoint
327  AkPipelineID instigatorID; ///< Profiling ID of the node from which the object stems (typically the voice, instance of an actor-mixer).
328  AkPriority priority; ///< Audio object playback priority. Object with a higher priority will be rendered using the hardware's object functionality on platforms that supports it, whereas objects with a lower priority will be downmixed to a lower resolution 3D bed. Audio object priorities should be retrieved, or set through IAkPluginServiceAudioObjectPriority to retain compatibility with future Wwise releases.
329 
330  /// Custom object metadata.
332  {
333  AkPluginID pluginID; ///< Full plugin ID, including company ID and plugin type. See AKMAKECLASSID macro.
334  AkUniqueID contextID; ///< (Profiling) ID of the sound or bus from which the custom metadata was fetched.
335  AK::IAkPluginParam* pParam; ///< Custom, pluggable medata. Note: any custom metadata is expected to exist for only the current sound engine render tick, and persistent references to it should not be stored.
336  };
337 
338  /// Array type for carrying custom metadata.
339  class ArrayCustomMetadata : public AkArray<CustomMetadata, const CustomMetadata&, AkPluginArrayAllocator>
340  {
341  public:
343 
344  ArrayType::Iterator FindByPluginID(AkPluginID pluginID) const
345  {
346  for (auto it = Begin(); it != End(); ++it)
347  {
348  if ((*it).pluginID == pluginID)
349  return it;
350  }
351  return End();
352  }
353  };
354 
355  ArrayCustomMetadata arCustomMetadata; ///< Array of custom metadata, gathered from visited objects. Note: any custom metadata is expected to exist for only the current sound engine render tick, and persistent references to it should not be stored.
356 
357  typedef AkString<AkPluginArrayAllocator, char> String; ///< String type for use in 3D audio objects.
358  String objectName; ///< Name string of the object, to appear in the object profiler. This is normally used by out-of-place object processors for naming their output objects. Built-in sound engine structures don't use it.
359 
360  /// Copies object metadata (everything but the key) from another object.
362  const AkAudioObject& in_src ///< Object from which metadata is copied.
363  )
364  {
365  positioning = in_src.positioning;
367  instigatorID = in_src.instigatorID;
368  priority = in_src.priority;
370  objectName = in_src.objectName; // AkString performs a shallow copy when it can, like here.
371  }
372 
373  /// Moves object metadata (everything but the key) from another object.
375  AkAudioObject& in_src ///< Object from which metadata is moved.
376  )
377  {
378  positioning = in_src.positioning;
380  instigatorID = in_src.instigatorID;
381  priority = in_src.priority;
384  }
385 
386  void SetCustomMetadata(CustomMetadata* in_aCustomMetadata, AkUInt32 in_uLength)
387  {
388  if (arCustomMetadata.Resize(in_uLength))
389  {
390  for (int i = 0; i < (int)in_uLength; ++i)
391  {
392  arCustomMetadata[i] = in_aCustomMetadata[i];
393  }
394  }
395  }
396 
397  /// Transfer function for transfer move policies.
398  void Transfer(
399  AkAudioObject& in_from ///< Object from which data is transferred.
400  )
401  {
402  key = in_from.key;
403  TransferContents(in_from);
404  }
405 
406  /// Object processors may give an explicit name to objects.
407  /// \return AK_Success if the string was allocated successfully, AK_InsufficientMemory otherwise.
409  AK::IAkPluginMemAlloc* in_pAllocator, ///< Memory allocator.
410  const char* in_szName ///< Null-terminated string to allocate and store on this object.
411  )
412  {
413  objectName.Init(in_pAllocator);
414  objectName = in_szName;
415  return objectName.AllocCopy();
416  }
417 
418  /// Reset object state in preparation for next frame.
419  void ResetState()
420  {
421  cumulativeGain = AkRamp(1.f, 1.f);
422  arCustomMetadata.Term(); // Reset custom metadata in preparation for next frame.
423  objectName.ClearReference(); // Clear reference to string in preparation for next frame.
424  }
425 };
426 
427 /// Structure containing information about system-level support for 3D audio.
428 /// "3D Audio" refers to a system's ability to position sound sources in a virtual 3D space, pan them accordingly on a range of physical speakers, and produce a binaural mix where appropriate.
429 /// We prefer "3D Audio" to "Spatial" to avoid ambiguity with spatial audio, which typically involves sound propagation and environment effects.
431 {
432  AkChannelConfig channelConfig{}; ///< Channel configuration of the main mix.
433  AkUInt32 uMaxSystemAudioObjects = 0; ///< Maximum number of System Audio Objects that can be active concurrently. A value of zero indicates the system does not support this feature.
434  AkUInt32 uAvailableSystemAudioObjects = 0; ///< How many System Audio Objects can currently be sent to the sink. This value can change at runtime depending on what is playing. Can never be higher than uMaxSystemAudioObjects.
435  bool bPassthrough = false; ///< Separate pass-through mix is supported.
436  bool bMultiChannelObjects = false; ///< Can handle multi-channel objects
437 };
438 
439 /// Enum of the possible object destinations when reaching a 3D audio-capable sink
441 {
442  eDefault = 0, // The destination will be chosen based on the audio object's metadata and channel configuration
443  eMainMix = 1, // The audio object will be mixed to the sink's main mix
444  ePassthrough = 2, // The audio object will be mixed to the sink's passthrough mix
445  eSystemAudioObject = 3 // The audio object will not be mixed; it will be sent separately to the system's 3D audio endpoint
446 };
447 
448 // Audio buffer.
449 // ------------------------------------------------
450 
451 /// Native sample type.
452 /// \remarks Sample values produced by insert effects must use this type.
453 /// \remarks Source plug-ins can produce samples of other types (specified through
454 /// according fields of AkAudioFormat, at initial handshaking), but these will be
455 /// format converted internally into the native format.
456 /// \sa
457 /// - \ref iaksourceeffect_init
458 /// - \ref iakmonadiceffect_init
459 typedef AkReal32 AkSampleType; ///< Audio sample data type (32 bit floating point)
460 
461 /// Audio buffer structure including the address of an audio buffer, the number of valid frames inside,
462 /// and the maximum number of frames the audio buffer can hold.
463 /// \sa
464 /// - \ref fx_audiobuffer_struct
466 {
467 public:
468 
469  /// Constructor.
471  {
472  Clear();
473  }
474 
475  /// Clear data pointer.
477  {
478  pData = NULL;
479  uValidFrames = 0;
480  }
481 
482  /// Clear members.
484  {
485  ClearData();
486  uMaxFrames = 0;
488  }
489 
490  /// \name Channel queries.
491  //@{
492  /// Get the number of channels.
494  {
496  }
497 
498  /// Returns true if there is an LFE channel present.
499  AkForceInline bool HasLFE() const
500  {
501  return channelConfig.HasLFE();
502  }
503 
505 
506  //@}
507 
508  /// \name Interleaved interface
509  //@{
510  /// Get address of data: to be used with interleaved buffers only.
511  /// \remarks Only source plugins can output interleaved data. This is determined at
512  /// initial handshaking.
513  /// \sa
514  /// - \ref fx_audiobuffer_struct
516  {
517  return pData;
518  }
519 
520  /// Attach interleaved data. Allocation is performed outside.
521  inline void AttachInterleavedData( void * in_pData, AkUInt16 in_uMaxFrames, AkUInt16 in_uValidFrames )
522  {
523  pData = in_pData;
524  uMaxFrames = in_uMaxFrames;
525  uValidFrames = in_uValidFrames;
527  }
528  /// Attach interleaved data with a new channel config. Allocation is performed outside.
529  inline void AttachInterleavedData( void * in_pData, AkUInt16 in_uMaxFrames, AkUInt16 in_uValidFrames, AkChannelConfig in_channelConfig )
530  {
531  pData = in_pData;
532  uMaxFrames = in_uMaxFrames;
533  uValidFrames = in_uValidFrames;
534  channelConfig = in_channelConfig;
535  }
536  //@}
537 
538  /// \name Deinterleaved interface
539  //@{
540 
541  /// Check if buffer has samples attached to it.
542  AkForceInline bool HasData() const
543  {
544  return ( NULL != pData );
545  }
546 
547  /// Convert a channel, identified by a single channel bit, to a buffer index used in GetChannel() below, for a given channel config.
548  /// Standard indexing follows channel bit order (see AkSpeakerConfig.h). Pipeline/buffer indexing is the same but the LFE is moved to the end.
550  AkChannelConfig in_channelConfig, ///< Channel configuration.
551  AkUInt32 in_uChannelIdx ///< Channel index in standard ordering to be converted to pipeline ordering.
552  )
553  {
554  if ( in_channelConfig.HasLFE() )
555  {
556  AKASSERT( in_channelConfig.eConfigType == AK_ChannelConfigType_Standard ); // in_channelConfig.HasLFE() would not have returned true otherwise.
557  AKASSERT( AK::GetNumNonZeroBits( in_channelConfig.uChannelMask ) );
558  AkUInt32 uIdxLFE = AK::GetNumNonZeroBits( ( AK_SPEAKER_LOW_FREQUENCY - 1 ) & in_channelConfig.uChannelMask );
559  if ( in_uChannelIdx == uIdxLFE )
560  return in_channelConfig.uNumChannels - 1;
561  else if ( in_uChannelIdx > uIdxLFE )
562  return in_uChannelIdx - 1;
563  }
564 
565  return in_uChannelIdx;
566  }
567 
568  /// Get the buffer of the ith channel.
569  /// Access to channel data is most optimal through this method. Use whenever the
570  /// speaker configuration is known, or when an operation must be made independently
571  /// for each channel.
572  /// \remarks When using a standard Wwise pipeline configuration, use ChannelBitToIndex() to convert channel bits to buffer indices.
573  /// \return Address of the buffer of the ith channel.
574  /// \sa
575  /// - \ref fx_audiobuffer_struct
576  /// - \ref fx_audiobuffer_struct_channels
578  AkUInt32 in_uIndex ///< Channel index [0,NumChannels()-1]
579  )
580  {
581  AKASSERT( in_uIndex < NumChannels() );
582  return (AkSampleType*)((AkUInt8*)(pData) + ( in_uIndex * sizeof(AkSampleType) * MaxFrames() ));
583  }
584 
585  /// Get the buffer of the LFE.
586  /// \return Address of the buffer of the LFE. Null if there is no LFE channel.
587  /// \sa
588  /// - \ref fx_audiobuffer_struct_channels
589  inline AkSampleType * GetLFE()
590  {
592  return GetChannel( NumChannels()-1 );
593 
594  return (AkSampleType*)0;
595  }
596 
597  /// Can be used to transform an incomplete into a complete buffer with valid data.
598  /// The invalid frames are made valid (zeroed out) for all channels and the validFrames count will be made equal to uMaxFrames.
600  {
601  AKASSERT(pData != nullptr || MaxFrames() == 0);
602  // The following members MUST be copied locally due to multi-core calls to this function.
603  const AkUInt32 uNumChannels = NumChannels();
604  const AkUInt32 uNumCurrentFrames = AkMin(uValidFrames, MaxFrames());
605  const AkUInt32 uNumZeroFrames = MaxFrames() - uNumCurrentFrames;
606  if ( uNumZeroFrames )
607  {
608  AKASSERT(pData != nullptr);
609  for ( AkUInt32 i = 0; i < uNumChannels; ++i )
610  {
611  memset( GetChannel(i) + uNumCurrentFrames, 0, uNumZeroFrames * sizeof(AkSampleType) );
612  }
614  }
615  }
616 
617  /// Attach deinterleaved data where channels are contiguous in memory. Allocation is performed outside.
618  AkForceInline void AttachContiguousDeinterleavedData( void * in_pData, AkUInt16 in_uMaxFrames, AkUInt16 in_uValidFrames, AkChannelConfig in_channelConfig )
619  {
620  AttachInterleavedData( in_pData, in_uMaxFrames, in_uValidFrames, in_channelConfig );
621  }
622  /// Detach deinterleaved data where channels are contiguous in memory. The address of the buffer is returned and fields are cleared.
624  {
625  uMaxFrames = 0;
626  uValidFrames = 0;
628  void * pDataOld = pData;
629  pData = NULL;
630  return pDataOld;
631  }
632 
634 
635  //@}
636 
637  void RelocateMedia( AkUInt8* in_pNewMedia, AkUInt8* in_pOldMedia )
638  {
639  AkUIntPtr uMemoryOffset = (AkUIntPtr)in_pNewMedia - (AkUIntPtr)in_pOldMedia;
640  pData = (void*) (((AkUIntPtr)pData) + uMemoryOffset);
641  }
642 
643  /// Access to the number of sample frames the buffer can hold.
644  /// \return Number of sample frames the buffer can hold.
646 
647 protected:
648  void * pData; ///< Start of the audio buffer.
649  AkChannelConfig channelConfig; ///< Channel config.
650 
651 public:
652  AKRESULT eState; ///< Execution status
653 
654 protected:
655  AkUInt16 uMaxFrames; ///< Number of sample frames the buffer can hold. Access through AkAudioBuffer::MaxFrames().
656 
657 public:
658  AkUInt16 uValidFrames; ///< Number of valid sample frames in the audio buffer
659 };
660 
661 /// A collection of audio objects. Encapsulates the audio data and metadata of each audio object in separate arrays.
663 {
664  AkAudioObjects(AkUInt32 in_uNumObjects = 0, AkAudioBuffer** in_ppObjectBuffers = nullptr, AkAudioObject** in_ppObjects = nullptr)
665  : uNumObjects(in_uNumObjects)
666  , ppObjectBuffers(in_ppObjectBuffers)
667  , ppObjects(in_ppObjects)
668  {}
669 
670  AkUInt32 uNumObjects; ///< Number of audio objects.
671  AkAudioBuffer** ppObjectBuffers; ///< Array of pointers to audio object buffers.
672  AkAudioObject** ppObjects; ///< Array of pointers to audio objects.
673 };
674 
675 #endif // _AK_COMMON_DEFS_H_
void Transfer(AkAudioObject &in_from)
Transfer function for transfer move policies.
Definition: AkCommonDefs.h:398
AkString< AkPluginArrayAllocator, char > String
String type for use in 3D audio objects.
Definition: AkCommonDefs.h:357
AkForceInline bool HasLFE() const
Returns true if there is an LFE channel present.
Definition: AkCommonDefs.h:499
bool enableHeightSpread
When true, audio objects 3D spatialized onto a planar channel configuration will be given a minimum s...
Definition: AkCommonDefs.h:285
#define AkMin(x1, x2)
AkUInt8 AkDataInterleaveID
Data interleaved state ID.
Definition: AkTypes.h:70
@ AK_DirectSpeakerAssignment
No panning: route to matching channels between input and output.
Definition: AkTypes.h:1113
AkUInt32 uAvailableSystemAudioObjects
How many System Audio Objects can currently be sent to the sink. This value can change at runtime dep...
Definition: AkCommonDefs.h:434
AkSampleType * GetChannel(AkUInt32 in_uIndex)
Definition: AkCommonDefs.h:577
#define AK_DEFAULT_TOP_Z
Definition: AkCommonDefs.h:243
uint16_t AkUInt16
Unsigned 16-bit integer.
Audiokinetic namespace.
AkForceInline bool HasData() const
Check if buffer has samples attached to it.
Definition: AkCommonDefs.h:542
AkAudioObject()
Constructor.
Definition: AkCommonDefs.h:306
static const AkUInt64 kObjectKeyNumBits
Definition: AkCommonDefs.h:320
AkForceInline bool HasCenter() const
AkPositioningData positioning
Positioning data for deferred 3D rendering.
Definition: AkCommonDefs.h:325
@ SourceChannelOrdering_FuMa
Definition: AkCommonDefs.h:172
AkReal32 center
Center percentage [0,1].
Definition: AkCommonDefs.h:278
AkRamp cumulativeGain
Cumulative ramping gain to apply when mixing down to speaker bed or final endpoint.
Definition: AkCommonDefs.h:326
AkForceInline AkChannelConfig GetChannelConfig() const
Definition: AkCommonDefs.h:504
void Transfer(AkString< TAlloc, T_CHAR > &in_from)
Definition: AkString.h:108
AkUInt64 AkAudioObjectID
Audio Object ID.
Definition: AkTypes.h:88
AKRESULT Copy(const AkArray< T, ARG_T, TAlloc, TGrowBy, TMovePolicy > &in_rSource)
Definition: AkArray.h:866
@ SourceChannelOrdering_Standard
Definition: AkCommonDefs.h:168
AkReal32 panSpatMix
Panning vs 3D spatialization mix ([0,1], 1 being 100% spatialized).
Definition: AkCommonDefs.h:282
bool bMultiChannelObjects
Can handle multi-channel objects.
Definition: AkCommonDefs.h:436
AkUInt32 AkPipelineID
Unique node (bus, voice) identifier for profiling.
Definition: AkTypes.h:86
AkAudioBuffer()
Constructor.
Definition: AkCommonDefs.h:470
AkUInt32 uMaxSystemAudioObjects
Maximum number of System Audio Objects that can be active concurrently. A value of zero indicates the...
Definition: AkCommonDefs.h:433
AkUInt32 uNumChannels
Number of channels.
static const AkUInt64 kObjectKeyMask
Definition: AkCommonDefs.h:321
AkAudioObjectID key
Unique ID, local to a given bus. Only the lower 56 of 64 bits are used for the object itself....
Definition: AkCommonDefs.h:323
AkForceInline void * DetachContiguousDeinterleavedData()
Detach deinterleaved data where channels are contiguous in memory. The address of the buffer is retur...
Definition: AkCommonDefs.h:623
AkForceInline AkUInt32 NumChannels() const
Get the number of channels.
Definition: AkCommonDefs.h:493
AkForceInline void Clear()
Clear members.
Definition: AkCommonDefs.h:483
#define AK_DEFAULT_LISTENER_FRONT_Y
Definition: AkCommonDefs.h:239
AKRESULT
Standard function call result.
Definition: AkTypes.h:131
AkUInt32 uChannelMask
Channel mask (configuration).
static AkUInt32 StandardToPipelineIndex(AkChannelConfig in_channelConfig, AkUInt32 in_uChannelIdx)
Definition: AkCommonDefs.h:549
@ AK_ChannelConfigType_Standard
Channels must be identified with standard defines in AkSpeakerConfigs.
AkForceInline bool HasCenter() const
Definition: AkCommonDefs.h:91
void Set(const AkVector &in_position, const AkVector &in_orientationFront, const AkVector &in_orientationTop)
Set position and orientation. Orientation front and top should be orthogonal and normalized.
Definition: AkTypes.h:571
static const AkAudioObjectID AK_INVALID_AUDIO_OBJECT_ID
Invalid audio object ID.
Definition: AkTypes.h:109
AkUInt32 AkChannelMask
Channel mask (similar to WAVE_FORMAT_EXTENSIBLE). Bit values are defined in AkSpeakerConfig....
Definition: AkTypes.h:81
AkChannelConfig channelConfig
Channel configuration.
Definition: AkCommonDefs.h:66
#define AK_DEFAULT_LISTENER_POSITION_Z
Definition: AkCommonDefs.h:237
@ SourceChannelOrdering_Film
Definition: AkCommonDefs.h:171
void RelocateMedia(AkUInt8 *in_pNewMedia, AkUInt8 *in_pOldMedia)
Definition: AkCommonDefs.h:637
uint8_t AkUInt8
Unsigned 8-bit integer.
AkUInt32 uBitsPerSample
Number of bits per sample.
Definition: AkCommonDefs.h:68
#define AK_DEFAULT_LISTENER_POSITION_Y
Definition: AkCommonDefs.h:236
@ SourceChannelOrdering_Last
Definition: AkCommonDefs.h:173
void CopyContents(const AkAudioObject &in_src)
Copies object metadata (everything but the key) from another object.
Definition: AkCommonDefs.h:361
Positioning data inherited from sound structures and mix busses.
Definition: AkCommonDefs.h:266
AkUInt32 uTypeID
Data type ID (AkDataTypeID).
Definition: AkCommonDefs.h:70
#define AK_DEFAULT_TOP_X
Definition: AkCommonDefs.h:241
Specific implementation of array.
Definition: AkArray.h:259
AK::SpeakerVolumes::VectorPtr rms
Definition: AkCommonDefs.h:216
#define NULL
Definition: AkTypes.h:46
float AkReal32
32-bit floating point
void TransferContents(AkAudioObject &in_src)
Moves object metadata (everything but the key) from another object.
Definition: AkCommonDefs.h:374
AKRESULT eState
Execution status.
Definition: AkCommonDefs.h:652
AK::SpeakerVolumes::VectorPtr truePeak
Definition: AkCommonDefs.h:212
AkReal32 panDU
Pan down-up [-1,1].
Definition: AkCommonDefs.h:281
AkUInt16 uValidFrames
Number of valid sample frames in the audio buffer.
Definition: AkCommonDefs.h:658
uintptr_t AkUIntPtr
Integer (unsigned) type for pointers.
static const AkPriority AK_DEFAULT_PRIORITY
Default sound / I/O priority.
Definition: AkTypes.h:112
AKRESULT SetName(AK::IAkPluginMemAlloc *in_pAllocator, const char *in_szName)
Definition: AkCommonDefs.h:408
#define AK_DEFAULT_TOP_Y
Definition: AkCommonDefs.h:242
AkForceInline void Init(AK::IAkPluginMemAlloc *in_pAllocator)
AkReal32 * VectorPtr
Volume vector. Access each element with the standard bracket [] operator.
void * pData
Start of the audio buffer.
Definition: AkCommonDefs.h:648
AkAudioObjectDestination
Enum of the possible object destinations when reaching a 3D audio-capable sink.
Definition: AkCommonDefs.h:441
AkChannelConfig channelConfig
Channel config.
Definition: AkCommonDefs.h:649
AkUInt32 AkUniqueID
Unique 32-bit ID.
Definition: AkTypes.h:52
bool Resize(AkUInt32 in_uiSize)
Resize the array to the specified size.
Definition: AkArray.h:823
AkAudioBuffer ** ppObjectBuffers
Array of pointers to audio object buffers.
Definition: AkCommonDefs.h:671
Ak3DSpatializationMode
3D spatialization mode.
Definition: AkTypes.h:1146
AkReal32 fMeanPowerK
Definition: AkCommonDefs.h:220
#define AK_DEFAULT_LISTENER_POSITION_X
Default listener transform.
Definition: AkCommonDefs.h:235
const AkDataTypeID AK_FLOAT
Float data type.
Definition: AkCommonDefs.h:51
AkUInt32 AkPluginID
Source or effect plug-in ID.
Definition: AkTypes.h:63
AkUInt16 AkDataTypeID
Data sample type ID.
Definition: AkTypes.h:69
void ResetState()
Reset object state in preparation for next frame.
Definition: AkCommonDefs.h:419
#define AKASSERT(Condition)
Definition: AkAssert.h:67
AkUInt32 uNumObjects
Number of audio objects.
Definition: AkCommonDefs.h:670
AkSpeakerPanningType panType
Speaker panning type.
Definition: AkCommonDefs.h:284
ArrayCustomMetadata arCustomMetadata
Array of custom metadata, gathered from visited objects. Note: any custom metadata is expected to exi...
Definition: AkCommonDefs.h:355
#define AKCODECID_BANK_BUS
Bank encoding for bus banks. These banks are contained in the /bus sub-folder.
Definition: AkTypes.h:1025
static const AkPipelineID AK_INVALID_PIPELINE_ID
Invalid pipeline ID (for profiling)
Definition: AkTypes.h:108
const AkUInt32 AK_LE_NATIVE_BITSPERSAMPLE
Native number of bits per sample.
Definition: AkCommonDefs.h:57
bool bPassthrough
Separate pass-through mix is supported.
Definition: AkCommonDefs.h:435
Volume ramp specified by end points "previous" and "next".
Definition: AkTypes.h:886
AkUInt16 uMaxFrames
Number of sample frames the buffer can hold. Access through AkAudioBuffer::MaxFrames().
Definition: AkCommonDefs.h:655
Iterator End() const
Returns the iterator to the end of the array.
Definition: AkArray.h:353
AkPluginID pluginID
Full plugin ID, including company ID and plugin type. See AKMAKECLASSID macro.
Definition: AkCommonDefs.h:333
AkInt8 AkPriority
Priority.
Definition: AkTypes.h:67
AkBehavioralPositioningData behavioral
Positioning data inherited from sound structures and mix busses.
Definition: AkCommonDefs.h:292
ArrayType::Iterator FindByPluginID(AkPluginID pluginID) const
Definition: AkCommonDefs.h:344
AkForceInline void Clear()
Clear the channel config. Becomes "invalid" (IsValid() returns false).
AkReal32 AkSampleType
Audio sample data type (32 bit floating point)
Definition: AkCommonDefs.h:459
AK::IAkPluginParam * pParam
Custom, pluggable medata. Note: any custom metadata is expected to exist for only the current sound e...
Definition: AkCommonDefs.h:335
void ClearReference()
Definition: AkString.h:49
const AkUInt32 AK_LE_NATIVE_SAMPLETYPE
Native data type.
Definition: AkCommonDefs.h:58
#define AK_DEFAULT_LISTENER_FRONT_X
Definition: AkCommonDefs.h:238
void Transfer(AkArray< T, ARG_T, TAlloc, TGrowBy, TMovePolicy > &in_rSource)
Definition: AkArray.h:853
AkPipelineID instigatorID
Profiling ID of the node from which the object stems (typically the voice, instance of an actor-mixer...
Definition: AkCommonDefs.h:327
Iterator Begin() const
Returns the iterator to the first item of the array, will be End() if the array is empty.
Definition: AkArray.h:345
Ak3dData threeD
3D data used for 3D spatialization.
Definition: AkCommonDefs.h:291
AkForceInline AkUInt32 GetNumNonZeroBits(AkUInt32 in_uWord)
Definition: AkBitFuncs.h:196
Struct containing metering information about a buffer. Depending on when this struct is generated,...
Definition: AkCommonDefs.h:205
AkForceInline AkUInt32 GetBitsPerSample() const
Definition: AkCommonDefs.h:98
@ AK_DataNeeded
The consumer needs more.
Definition: AkTypes.h:157
Positioning data of 3D audio objects.
Definition: AkCommonDefs.h:290
A collection of audio objects. Encapsulates the audio data and metadata of each audio object in separ...
Definition: AkCommonDefs.h:663
#define AKCODECID_BANK_EVENT
Bank encoding for event banks. These banks are contained in the /event sub-folder.
Definition: AkTypes.h:1024
uint64_t AkUInt64
Unsigned 64-bit integer.
AkUInt32 uBlockAlign
Number of bytes per sample frame. (For example a 5.1 PCM 16bit should have a uBlockAlign equal to 6(5...
Definition: AkCommonDefs.h:69
AkChannelConfig channelConfig
Channel configuration of the main mix.
Definition: AkCommonDefs.h:432
AkForceInline AkUInt32 GetInterleaveID() const
Definition: AkCommonDefs.h:119
#define AK_DEFAULT_LISTENER_FRONT_Z
Definition: AkCommonDefs.h:240
AkForceInline bool operator!=(const AkAudioFormat &in_other) const
Definition: AkCommonDefs.h:153
#define AKCODECID_BANK
Bank encoding.
Definition: AkTypes.h:1002
void ZeroPadToMaxFrames()
Definition: AkCommonDefs.h:599
AkForceInline bool HasLFE() const
Definition: AkCommonDefs.h:82
@ AK_SpatializationMode_None
No spatialization.
Definition: AkTypes.h:1147
AkForceInline AkUInt32 GetBlockAlign() const
Definition: AkCommonDefs.h:105
AKRESULT AllocCopy()
Definition: AkString.h:84
AkChannelMask uEmitterChannelMask
Emitter channel mask. With 3D spatialization, zeroed channels should be dropped.
Definition: AkCommonDefs.h:261
uint32_t AkUInt32
Unsigned 32-bit integer.
void SetCustomMetadata(CustomMetadata *in_aCustomMetadata, AkUInt32 in_uLength)
Definition: AkCommonDefs.h:386
AkUInt8(* AkChannelMappingFunc)(const AkChannelConfig &config, AkUInt8 idx)
Definition: AkCommonDefs.h:164
AkSpeakerPanningType
Speaker panning type: type of panning logic when object is not 3D spatialized (i.e....
Definition: AkTypes.h:1112
AkUInt32 eConfigType
Channel config type (AkChannelConfigType).
AkReal32 panLR
Pan left-right [-1,1].
Definition: AkCommonDefs.h:279
AkForceInline void AttachContiguousDeinterleavedData(void *in_pData, AkUInt16 in_uMaxFrames, AkUInt16 in_uValidFrames, AkChannelConfig in_channelConfig)
Attach deinterleaved data where channels are contiguous in memory. Allocation is performed outside.
Definition: AkCommonDefs.h:618
void Term()
Term the array. Must be called before destroying the object.
Definition: AkArray.h:555
AkReal32 spread
Spread [0,1].
Definition: AkCommonDefs.h:259
AkForceInline bool HasLFE() const
~AkAudioObject()
Destructor.
Definition: AkCommonDefs.h:314
AkPriority priority
Audio object playback priority. Object with a higher priority will be rendered using the hardware's o...
Definition: AkCommonDefs.h:328
AkForceInline bool operator==(const AkAudioFormat &in_other) const
Definition: AkCommonDefs.h:143
AkSampleType * GetLFE()
Definition: AkCommonDefs.h:589
AkForceInline void * GetInterleavedData()
Definition: AkCommonDefs.h:515
String objectName
Name string of the object, to appear in the object profiler. This is normally used by out-of-place ob...
Definition: AkCommonDefs.h:358
Custom object metadata.
Definition: AkCommonDefs.h:332
AkForceInline AkUInt32 GetNumChannels() const
Definition: AkCommonDefs.h:75
void Term()
Definition: AkString.h:39
#define AK_SPEAKER_LOW_FREQUENCY
Low-frequency speaker bit mask.
Array type for carrying custom metadata.
Definition: AkCommonDefs.h:340
static bool IsBankCodecID(AkUInt32 in_codecID)
Definition: AkCommonDefs.h:223
const AkDataTypeID AK_INT
Integer data type (uchar, short, and so on)
Definition: AkCommonDefs.h:50
#define AkForceInline
Definition: AkTypes.h:63
Defines the parameters of an audio buffer format.
Definition: AkCommonDefs.h:63
AkUInt32 uInterleaveID
Interleave ID (AkDataInterleaveID).
Definition: AkCommonDefs.h:71
AkUniqueID contextID
(Profiling) ID of the sound or bus from which the custom metadata was fetched.
Definition: AkCommonDefs.h:334
bool CheckValidSamples()
Position and orientation of objects in a "local" space.
Definition: AkTypes.h:542
AkForceInline AkUInt32 GetTypeID() const
Definition: AkCommonDefs.h:112
AkForceInline bool IsValid() const
Returns true if valid, false otherwise (as when it is constructed, or invalidated using Clear()).
AkReal32 focus
Focus [0,1].
Definition: AkCommonDefs.h:260
AkTransform xform
Object position / orientation.
Definition: AkCommonDefs.h:258
AkForceInline void ClearData()
Clear data pointer.
Definition: AkCommonDefs.h:476
void AttachInterleavedData(void *in_pData, AkUInt16 in_uMaxFrames, AkUInt16 in_uValidFrames)
Attach interleaved data. Allocation is performed outside.
Definition: AkCommonDefs.h:521
AkAudioObjects(AkUInt32 in_uNumObjects=0, AkAudioBuffer **in_ppObjectBuffers=nullptr, AkAudioObject **in_ppObjects=nullptr)
Definition: AkCommonDefs.h:664
AkAudioObject ** ppObjects
Array of pointers to audio objects.
Definition: AkCommonDefs.h:672
AkUInt32 uSampleRate
Number of samples per second.
Definition: AkCommonDefs.h:64
AK::SpeakerVolumes::VectorPtr peak
Definition: AkCommonDefs.h:208
const AkDataInterleaveID AK_NONINTERLEAVED
Non-interleaved data.
Definition: AkCommonDefs.h:54
Ak3DSpatializationMode spatMode
3D spatialization mode.
Definition: AkCommonDefs.h:283
AkReal32 panBF
Pan back-front [-1,1].
Definition: AkCommonDefs.h:280
const AkDataInterleaveID AK_INTERLEAVED
Interleaved data.
Definition: AkCommonDefs.h:53
AkSourceChannelOrdering
Definition: AkCommonDefs.h:167
void AttachInterleavedData(void *in_pData, AkUInt16 in_uMaxFrames, AkUInt16 in_uValidFrames, AkChannelConfig in_channelConfig)
Attach interleaved data with a new channel config. Allocation is performed outside.
Definition: AkCommonDefs.h:529
void SetAll(AkUInt32 in_uSampleRate, AkChannelConfig in_channelConfig, AkUInt32 in_uBitsPerSample, AkUInt32 in_uBlockAlign, AkUInt32 in_uTypeID, AkUInt32 in_uInterleaveID)
Definition: AkCommonDefs.h:126
const AkUInt32 AK_LE_NATIVE_INTERLEAVE
Native interleaved setting.
Definition: AkCommonDefs.h:59
AkForceInline AkUInt16 MaxFrames() const
Definition: AkCommonDefs.h:645

Cette page a-t-elle été utile ?

Besoin d'aide ?

Des questions ? Des problèmes ? Besoin de plus d'informations ? Contactez-nous, nous pouvons vous aider !

Visitez notre page d'Aide

Décrivez-nous de votre projet. Nous sommes là pour vous aider.

Enregistrez votre projet et nous vous aiderons à démarrer sans aucune obligation !

Partir du bon pied avec Wwise