HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
spatialAudio.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef USDMEDIA_GENERATED_SPATIALAUDIO_H
25 #define USDMEDIA_GENERATED_SPATIALAUDIO_H
26 
27 /// \file usdMedia/spatialAudio.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdMedia/api.h"
32 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/stage.h"
35 
36 #include "pxr/base/vt/value.h"
37 
38 #include "pxr/base/gf/vec3d.h"
39 #include "pxr/base/gf/vec3f.h"
40 #include "pxr/base/gf/matrix4d.h"
41 
42 #include "pxr/base/tf/token.h"
43 #include "pxr/base/tf/type.h"
44 
46 
47 class SdfAssetPath;
48 
49 // -------------------------------------------------------------------------- //
50 // SPATIALAUDIO //
51 // -------------------------------------------------------------------------- //
52 
53 /// \class UsdMediaSpatialAudio
54 ///
55 /// The SpatialAudio primitive defines basic properties for encoding
56 /// playback of an audio file or stream within a USD Stage. The SpatialAudio
57 /// schema derives from UsdGeomXformable since it can support full spatial
58 /// audio while also supporting non-spatial mono and stereo sounds. One or
59 /// more SpatialAudio prims can be placed anywhere in the namespace, though it
60 /// is advantageous to place truly spatial audio prims under/inside the models
61 /// from which the sound emanates, so that the audio prim need only be
62 /// transformed relative to the model, rather than copying its animation.
63 ///
64 /// \section Usd_SpatialAudio_TimeScaling Timecode Attributes and Time Scaling
65 /// \a startTime and \a endTime are \ref SdfTimeCode "timecode" valued
66 /// attributes which gives them the special behavior that
67 /// \ref SdfLayerOffset "layer offsets" affecting the layer in
68 /// which one of these values is authored are applied to the attribute's value
69 /// itself during value resolution. This allows audio playback to be kept in
70 /// sync with time sampled animation as the animation is affected by
71 /// \ref SdfLayerOffset "layer offsets" in the composition. But this behavior
72 /// brings with it some interesting edge cases and caveats when it comes to
73 /// \ref SdfLayerOffset "layer offsets" that include scale.
74 ///
75 /// #### Layer Offsets do not affect Media Dilation
76 /// Although authored layer offsets may have a time scale which can scale the
77 /// duration between an authored \a startTime and \a endTime, we make no
78 /// attempt to infer any playback dilation of the actual audio media itself.
79 /// Given that \a startTime and \a endTime can be independently authored in
80 /// different layers with differing time scales, it is not possible, in general,
81 /// to define an "original timeframe" from which we can compute a dilation to
82 /// composed stage-time. Even if we could compute a composed dilation this way,
83 /// it would still be impossible to flatten a stage or layer stack into a single
84 /// layer and still retain the composed audio dilation using this schema.
85 ///
86 /// #### Inverting startTime and endTime
87 /// Although we do not expect it to be common, it is possible to apply a
88 /// negative time scale to USD layers, which mostly has the effect of reversing
89 /// animation in the affected composition. If a negative scale is applied to a
90 /// composition that contains authored \a startTime and \a endTime, it will
91 /// reverse their relative ordering in time. Therefore, we stipulate when
92 /// \a playbackMode is "onceFromStartToEnd" or "loopFromStartToEnd", if
93 /// \a endTime is less than \a startTime, then begin playback at \a endTime,
94 /// and continue until \a startTime. When \a startTime and \a endTime are
95 /// inverted, we do not, however, stipulate that playback of the audio media
96 /// itself be inverted, since doing so "successfully" would require perfect
97 /// knowledge of when, within the audio clip, relevant audio ends (so that we
98 /// know how to offset the reversed audio to align it so that we reach the
99 /// "beginning" at \a startTime), and sounds played in reverse are not likely
100 /// to produce desirable results.
101 ///
102 ///
103 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
104 /// that are text/tokens, the actual token is published and defined in \ref UsdMediaTokens.
105 /// So to set an attribute to the value "rightHanded", use UsdMediaTokens->rightHanded
106 /// as the value.
107 ///
109 {
110 public:
111  /// Compile time constant representing what kind of schema this class is.
112  ///
113  /// \sa UsdSchemaKind
115 
116  /// Construct a UsdMediaSpatialAudio on UsdPrim \p prim .
117  /// Equivalent to UsdMediaSpatialAudio::Get(prim.GetStage(), prim.GetPath())
118  /// for a \em valid \p prim, but will not immediately throw an error for
119  /// an invalid \p prim
120  explicit UsdMediaSpatialAudio(const UsdPrim& prim=UsdPrim())
121  : UsdGeomXformable(prim)
122  {
123  }
124 
125  /// Construct a UsdMediaSpatialAudio on the prim held by \p schemaObj .
126  /// Should be preferred over UsdMediaSpatialAudio(schemaObj.GetPrim()),
127  /// as it preserves SchemaBase state.
128  explicit UsdMediaSpatialAudio(const UsdSchemaBase& schemaObj)
129  : UsdGeomXformable(schemaObj)
130  {
131  }
132 
133  /// Destructor.
135  virtual ~UsdMediaSpatialAudio();
136 
137  /// Return a vector of names of all pre-declared attributes for this schema
138  /// class and all its ancestor classes. Does not include attributes that
139  /// may be authored by custom/extended methods of the schemas involved.
141  static const TfTokenVector &
142  GetSchemaAttributeNames(bool includeInherited=true);
143 
144  /// Return a UsdMediaSpatialAudio holding the prim adhering to this
145  /// schema at \p path on \p stage. If no prim exists at \p path on
146  /// \p stage, or if the prim at that path does not adhere to this schema,
147  /// return an invalid schema object. This is shorthand for the following:
148  ///
149  /// \code
150  /// UsdMediaSpatialAudio(stage->GetPrimAtPath(path));
151  /// \endcode
152  ///
154  static UsdMediaSpatialAudio
155  Get(const UsdStagePtr &stage, const SdfPath &path);
156 
157  /// Attempt to ensure a \a UsdPrim adhering to this schema at \p path
158  /// is defined (according to UsdPrim::IsDefined()) on this stage.
159  ///
160  /// If a prim adhering to this schema at \p path is already defined on this
161  /// stage, return that prim. Otherwise author an \a SdfPrimSpec with
162  /// \a specifier == \a SdfSpecifierDef and this schema's prim type name for
163  /// the prim at \p path at the current EditTarget. Author \a SdfPrimSpec s
164  /// with \p specifier == \a SdfSpecifierDef and empty typeName at the
165  /// current EditTarget for any nonexistent, or existing but not \a Defined
166  /// ancestors.
167  ///
168  /// The given \a path must be an absolute prim path that does not contain
169  /// any variant selections.
170  ///
171  /// If it is impossible to author any of the necessary PrimSpecs, (for
172  /// example, in case \a path cannot map to the current UsdEditTarget's
173  /// namespace) issue an error and return an invalid \a UsdPrim.
174  ///
175  /// Note that this method may return a defined prim whose typeName does not
176  /// specify this schema class, in case a stronger typeName opinion overrides
177  /// the opinion at the current EditTarget.
178  ///
180  static UsdMediaSpatialAudio
181  Define(const UsdStagePtr &stage, const SdfPath &path);
182 
183 protected:
184  /// Returns the kind of schema this class belongs to.
185  ///
186  /// \sa UsdSchemaKind
188  UsdSchemaKind _GetSchemaKind() const override;
189 
190 private:
191  // needs to invoke _GetStaticTfType.
192  friend class UsdSchemaRegistry;
194  static const TfType &_GetStaticTfType();
195 
196  static bool _IsTypedSchema();
197 
198  // override SchemaBase virtuals.
200  const TfType &_GetTfType() const override;
201 
202 public:
203  // --------------------------------------------------------------------- //
204  // FILEPATH
205  // --------------------------------------------------------------------- //
206  /// Path to the audio file.
207  /// In general, the formats allowed for audio files is no more constrained
208  /// by USD than is image-type. As with images, however, usdz has stricter
209  /// requirements based on DMA and format support in browsers and consumer
210  /// devices. The allowed audio filetypes for usdz are M4A, MP3, WAV
211  /// (in order of preference).
212  /// \sa <a href="http://graphics.pixar.com/usd/docs/Usdz-File-Format-Specification.html#UsdzFileFormatSpecification-UsdzSpecification">Usdz Specification</a>
213  ///
214  ///
215  /// | ||
216  /// | -- | -- |
217  /// | Declaration | `uniform asset filePath = @@` |
218  /// | C++ Type | SdfAssetPath |
219  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Asset |
220  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
223 
224  /// See GetFilePathAttr(), and also
225  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
226  /// If specified, author \p defaultValue as the attribute's default,
227  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
228  /// the default for \p writeSparsely is \c false.
230  UsdAttribute CreateFilePathAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
231 
232 public:
233  // --------------------------------------------------------------------- //
234  // AURALMODE
235  // --------------------------------------------------------------------- //
236  /// Determines how audio should be played.
237  /// Valid values are:
238  /// - spatial: Play the audio in 3D space if the device can support spatial
239  /// audio. if not, fall back to mono.
240  /// - nonSpatial: Play the audio without regard to the SpatialAudio prim's
241  /// position. If the audio media contains any form of stereo or other
242  /// multi-channel sound, it is left to the application to determine
243  /// whether the listener's position should be taken into account. We
244  /// expect nonSpatial to be the choice for ambient sounds and music
245  /// sound-tracks.
246  ///
247  ///
248  /// | ||
249  /// | -- | -- |
250  /// | Declaration | `uniform token auralMode = "spatial"` |
251  /// | C++ Type | TfToken |
252  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
253  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
254  /// | \ref UsdMediaTokens "Allowed Values" | spatial, nonSpatial |
257 
258  /// See GetAuralModeAttr(), and also
259  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
260  /// If specified, author \p defaultValue as the attribute's default,
261  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
262  /// the default for \p writeSparsely is \c false.
264  UsdAttribute CreateAuralModeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
265 
266 public:
267  // --------------------------------------------------------------------- //
268  // PLAYBACKMODE
269  // --------------------------------------------------------------------- //
270  /// Along with \a startTime and \a endTime, determines when the
271  /// audio playback should start and stop during the stage's animation
272  /// playback and whether the audio should loop during its duration.
273  /// Valid values are:
274  /// - onceFromStart: Play the audio once, starting at \a startTime,
275  /// continuing until the audio completes.
276  /// - onceFromStartToEnd: Play the audio once beginning at \a startTime,
277  /// continuing until \a endTime or until the audio completes, whichever
278  /// comes first.
279  /// - loopFromStart: Start playing the audio at \a startTime and continue
280  /// looping through to the stage's authored \a endTimeCode.
281  /// - loopFromStartToEnd: Start playing the audio at \a startTime and
282  /// continue looping through, stopping the audio at \a endTime.
283  /// - loopFromStage: Start playing the audio at the stage's authored
284  /// \a startTimeCode and continue looping through to the stage's authored
285  /// \a endTimeCode. This can be useful for ambient sounds that should always
286  /// be active.
287  ///
288  ///
289  /// | ||
290  /// | -- | -- |
291  /// | Declaration | `uniform token playbackMode = "onceFromStart"` |
292  /// | C++ Type | TfToken |
293  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
294  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
295  /// | \ref UsdMediaTokens "Allowed Values" | onceFromStart, onceFromStartToEnd, loopFromStart, loopFromStartToEnd, loopFromStage |
298 
299  /// See GetPlaybackModeAttr(), and also
300  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
301  /// If specified, author \p defaultValue as the attribute's default,
302  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
303  /// the default for \p writeSparsely is \c false.
305  UsdAttribute CreatePlaybackModeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
306 
307 public:
308  // --------------------------------------------------------------------- //
309  // STARTTIME
310  // --------------------------------------------------------------------- //
311  /// Expressed in the timeCodesPerSecond of the containing stage,
312  /// \a startTime specifies when the audio stream will start playing during
313  /// animation playback. This value is ignored when \a playbackMode is set
314  /// to loopFromStage as, in this mode, the audio will always start at the
315  /// stage's authored \a startTimeCode.
316  /// Note that \a startTime is expressed as a timecode so that the stage can
317  /// properly apply layer offsets when resolving its value. See
318  /// \ref Usd_SpatialAudio_TimeScaling for more details and caveats.
319  ///
320  ///
321  /// | ||
322  /// | -- | -- |
323  /// | Declaration | `uniform timecode startTime = 0` |
324  /// | C++ Type | SdfTimeCode |
325  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->TimeCode |
326  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
329 
330  /// See GetStartTimeAttr(), and also
331  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
332  /// If specified, author \p defaultValue as the attribute's default,
333  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
334  /// the default for \p writeSparsely is \c false.
336  UsdAttribute CreateStartTimeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
337 
338 public:
339  // --------------------------------------------------------------------- //
340  // ENDTIME
341  // --------------------------------------------------------------------- //
342  /// Expressed in the timeCodesPerSecond of the containing stage,
343  /// \a endTime specifies when the audio stream will cease playing during
344  /// animation playback if the length of the referenced audio clip is
345  /// longer than desired. This only applies if \a playbackMode is set to
346  /// onceFromStartToEnd or loopFromStartToEnd, otherwise the \a endTimeCode
347  /// of the stage is used instead of \a endTime.
348  /// If \a endTime is less than \a startTime, it is expected that the audio
349  /// will instead be played from \a endTime to \a startTime.
350  /// Note that \a endTime is expressed as a timecode so that the stage can
351  /// properly apply layer offsets when resolving its value.
352  /// See \ref Usd_SpatialAudio_TimeScaling for more details and caveats.
353  ///
354  ///
355  /// | ||
356  /// | -- | -- |
357  /// | Declaration | `uniform timecode endTime = 0` |
358  /// | C++ Type | SdfTimeCode |
359  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->TimeCode |
360  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
363 
364  /// See GetEndTimeAttr(), and also
365  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
366  /// If specified, author \p defaultValue as the attribute's default,
367  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
368  /// the default for \p writeSparsely is \c false.
370  UsdAttribute CreateEndTimeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
371 
372 public:
373  // --------------------------------------------------------------------- //
374  // MEDIAOFFSET
375  // --------------------------------------------------------------------- //
376  /// Expressed in seconds, \a mediaOffset specifies the offset from
377  /// the referenced audio file's beginning at which we should begin playback
378  /// when stage playback reaches the time that prim's audio should start.
379  /// If the prim's \a playbackMode is a looping mode, \a mediaOffset is
380  /// applied only to the first run-through of the audio clip; the second and
381  /// all other loops begin from the start of the audio clip.
382  ///
383  ///
384  /// | ||
385  /// | -- | -- |
386  /// | Declaration | `uniform double mediaOffset = 0` |
387  /// | C++ Type | double |
388  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Double |
389  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
392 
393  /// See GetMediaOffsetAttr(), and also
394  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
395  /// If specified, author \p defaultValue as the attribute's default,
396  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
397  /// the default for \p writeSparsely is \c false.
399  UsdAttribute CreateMediaOffsetAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
400 
401 public:
402  // --------------------------------------------------------------------- //
403  // GAIN
404  // --------------------------------------------------------------------- //
405  /// Multiplier on the incoming audio signal. A value of 0 "mutes"
406  /// the signal. Negative values will be clamped to 0.
407  ///
408  ///
409  /// | ||
410  /// | -- | -- |
411  /// | Declaration | `double gain = 1` |
412  /// | C++ Type | double |
413  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Double |
415  UsdAttribute GetGainAttr() const;
416 
417  /// See GetGainAttr(), and also
418  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
419  /// If specified, author \p defaultValue as the attribute's default,
420  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
421  /// the default for \p writeSparsely is \c false.
423  UsdAttribute CreateGainAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
424 
425 public:
426  // ===================================================================== //
427  // Feel free to add custom code below this line, it will be preserved by
428  // the code generator.
429  //
430  // Just remember to:
431  // - Close the class declaration with };
432  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
433  // - Close the include guard with #endif
434  // ===================================================================== //
435  // --(BEGIN CUSTOM CODE)--
436 };
437 
439 
440 #endif
static USDMEDIA_API UsdMediaSpatialAudio Get(const UsdStagePtr &stage, const SdfPath &path)
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USDMEDIA_API UsdAttribute CreateMediaOffsetAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDMEDIA_API UsdAttribute CreatePlaybackModeAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDMEDIA_API UsdAttribute CreateAuralModeAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
static USDMEDIA_API UsdMediaSpatialAudio Define(const UsdStagePtr &stage, const SdfPath &path)
static const UsdSchemaKind schemaKind
Definition: spatialAudio.h:114
UsdSchemaKind
Definition: common.h:127
USDMEDIA_API UsdAttribute GetGainAttr() const
USDMEDIA_API UsdAttribute GetFilePathAttr() const
USDMEDIA_API UsdAttribute GetStartTimeAttr() const
static USDMEDIA_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Represents a concrete typed schema.
Definition: prim.h:132
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
#define USDMEDIA_API
Definition: api.h:40
Definition: path.h:290
USDMEDIA_API UsdAttribute CreateFilePathAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDMEDIA_API UsdAttribute CreateGainAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
UsdMediaSpatialAudio(const UsdPrim &prim=UsdPrim())
Definition: spatialAudio.h:120
USDMEDIA_API UsdSchemaKind _GetSchemaKind() const override
USDMEDIA_API UsdAttribute GetAuralModeAttr() const
USDMEDIA_API UsdAttribute GetPlaybackModeAttr() const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1394
USDMEDIA_API UsdAttribute GetEndTimeAttr() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USDMEDIA_API UsdAttribute CreateEndTimeAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Definition: type.h:64
UsdMediaSpatialAudio(const UsdSchemaBase &schemaObj)
Definition: spatialAudio.h:128
USDMEDIA_API UsdAttribute GetMediaOffsetAttr() const
USDMEDIA_API UsdAttribute CreateStartTimeAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Definition: value.h:166
virtual USDMEDIA_API ~UsdMediaSpatialAudio()
Destructor.