SoVRMLSound Class Reference
[VRML97 nodes]
Specifies position and spatial representation of a sound [Windows only] .
More...
#include <Inventor/VRMLnodes/SoVRMLSound.h>
Public Member Functions | |
| virtual SoType | getTypeId () const |
| SoVRMLSound () | |
Static Public Member Functions | |
| static SoType | getClassTypeId () |
Public Attributes | |
| SoSFNode | source |
| SoSFFloat | intensity |
| SoSFFloat | priority |
| SoSFVec3f | location |
| SoSFVec3f | direction |
| SoSFFloat | minFront |
| SoSFBool | spatialize |
| SoSFFloat | dopplerFactor |
| SoSFFloat | dopplerVelocity |
|
| |
| SoSFFloat | maxFront |
| SoSFFloat | minBack |
| SoSFFloat | maxBack |
Detailed Description
Specifies position and spatial representation of a sound [Windows only] .
This node has an effect only on Windows.
NOTE: This class does not exist in Open Inventor 10.0 and later.The SoVRMLSound node describes the positioning and spatial presentation of a sound in a VRML scene. The sound may be located at a point and emit sound in a spherical or ellipsoid pattern, in the local coordinate system. The ellipsoid is pointed in a particular direction and may be shaped to provide more or less directional focus from the location of the sound. The sound node may also be used to describe an ambient sound which tapers off at a specified distance from the sound node.
VRML97 SPECIFICATION
- This section describes the expected behavior of the node in a conforming VRML97 browser application. In some cases, the application is responsible for implementing portions of the expected behavior. Open Inventor viewer classes and IVF classes implement some of the application behaviors.
- Support of the Doppler effect. The Doppler effect depends on the velocities of the source and the listener relative to the medium (air, water,...) and speed of sound propagation in that medium. If F is the original frequency, then F', the effective Doppler shifted frequency is computed as follows:
F' = dopplerFactor * F * (dopplerVelocity-VL)/(dopplerVelocity+VS)
with VL being the listener velocity and VS being the source velocity.
- This node is not thread safe so it does not work with the MultiPipe extension.
- The priority and spatialize fields are not implemented. Setting these fields has no effect.
- If source is an SoVRMLAudioClip, only wave files (.wav extension) are supported.
- If source is an SoVRMLMovieTexture, the sound is extracted only from AVI files.
- minFront (but not minBack, maxFront or maxBack) is used to specify the volume space of the sound. minFront determines the radius of a sphere within which the sound is not attenuated. Outside of this sphere, the attenuation is as described by the VRML2 specification.
- OpenAL ( http://connect.creativelabs.com/openal/default.aspx ), the Open Audio Library, is used for the spatialization of the sound. The OpenAL library is supplied separate from the Open Inventor libraries.
This section may reference portions of the VRML97 specification that are not present in this help file. The complete VRML97 spec is available at http://www.web3d.org.
The SoVRMLSound node describes the positioning and spatial presentation of a sound in a VRML scene. The sound may be located at a point and emit sound in a spherical or ellipsoid pattern, in the local coordinate system. The ellipsoid is pointed in a particular direction and may be shaped to provide more or less directional focus from the location of the sound. The sound node may also be used to describe an ambient sound which tapers off at a specified distance from the sound node.
The SoVRMLSound node also enables ambient background sound to be created by setting of the maxFront and maxBack to the radius of the area for the ambient noise. If ambient noise is required for the whole scene then these values should be set to at least cover the distance from the location to the farthest point in scene from that point (including effects of transforms).
The source field specifies the sound source for the sound node. If there is no source specified the SoVRMLSound will emit no audio. The source field will specify either an SoVRMLAudioClip or an SoVRMLMovieTexture node. Furthermore, the SoVRMLMovieTexture node must refer to a movie format that supports sound (e.g. MPEG1-Systems).
The intensity field adjusts the volume of each sound source; The intensity is an SFFloat that ranges from 0.0 to 1.0. An intensity of 0 is silence, and an intensity of 1 is the full volume of the sound in the sample or the full volume of the MIDI clip.
The priority field gives the author some control over which sounds the browser will choose to play when there are more sounds active than sound channels available. The priority varies between 0.0 and 1.0, with 1.0 being the highest priority. For most applications priority 0.0 should be used for a normal sound and 1.0 should be used only for special event or cue sounds (usually of short duration) that the author wants the user to hear even if they are farther away and perhaps of lower intensity than some other ongoing sounds. Browsers should make as many sound channels available to the scene as is efficiently possible.
If the browser does not have enough sound channels to play all of the currently active sounds, it is recommended that the browser sort the active sounds into an ordered list using the following sort keys:
1. decreasing priority;
2. for sounds with priority > 0.5, increasing (now- startTime )
3. decreasing intensity at viewer location ((intensity/distance)**2);
where now represents the current time, and startTime is the startTime field of the audio source node specified in the source field.
It is important that sort key #2 be used for the high priority (event and cue) sounds so that new cues will be heard even when the channels are "full" of currently active high priority sounds. Sort key #2 should not be used for normal priority sounds so selection among them will be based on sort key #3 - intensity and distance from the viewer.
The browser should play as many sounds from the beginning of this sorted list as it has available channels. On most systems the number of concurrent sound channels is distinct from the number of concurrent MIDI streams. On these systems the browser may maintain separate ordered lists for sampled sounds and MIDI streams.
A sound's location in the scene graph determines its spatial location (the sound's location is transformed by the current transformation) and whether or not it can be heard. A sound can only be heard while it is part of the traversed scene; sound nodes that are descended from SoVRMLLOD, SoVRMLSwitch, or any grouping or prototype node that disables traversal (i.e., drawing) of its children will not be audible unless they are traversed. If a sound is silenced for a time under an SoVRMLSwitch or SoVRMLLOD node, and later it becomes part of the traversal again, the sound picks up where it would have been had it been playing continuously.
Around the location of the emitter, minFront and minBack determine the extent of the full intensity region in front of and behind the sound. If the location of the sound is taken as a focus of an ellipsoid, the minBack and minFront values, in combination with the direction vector determine the two focii of an ellipsoid bounding the ambient region of the sound. Similarly, maxFront and maxBack determine the limits of audibility in front of and behind the sound; they describe a second, outer ellipsoid. If minFront equals minBack and maxFront equals maxBack, the sound is omnidirectional, the direction vector is ignored, and the min and max ellipsoids become spheres centered around the sound node. The fields minFront, maxFront, minBack, and maxBack are scaled by the parent transformations - these values must be >= 0.0.
The inner ellipsoid defines a space of full intensity for the sound. Within that space the sound will play at the intensity specified in the sound node. The outer ellipsoid determines the maximum extent of the sound. Outside that space, the sound cannot be heard at all. In between the two ellipsoids, the intensity drops off proportionally with inverse square of the distance. With this model, an SoVRMLSound usually will have smooth changes in intensity over the entire extent is which it can be heard. However, if at any point the maximum is the same as or inside the minimum, the sound is cut off immediately at the edge of the minimum ellipsoid.
The ideal implementation of the sound attenuation between the inner and outer ellipsoids is an inverse power dropoff. A reasonable approximation to this ideal model is a linear dropoff in decibel value. Since an inverse power dropoff never actually reaches zero, it is necessary to select an appropriate cutoff value for the outer ellipsoid so that the outer ellipsoid contains the space in which the sound is truly audible and excludes space where it would be negligible. Keeping the outer ellipsoid as small as possible will help limit resources used by nearly inaudible sounds. Experimentation suggests that a 20dB dropoff from the maximum intensity is a reasonable cutoff value that makes the bounding volume (the outer ellipsoid) contain the truly audible range of the sound. Since actual physical sound dropoff in an anechoic environment follows the inverse square law, using this algorithm it is possible to mimic real-world sound attenuation by making the maximum ellipsoid ten times larger than the minimum ellipsoid. This will yield inverse square dropoff between them.
Browsers should support spatial localization of sound as well as their underlying sound libraries will allow. The spatialize field is used to indicate to browsers that they should try to locate this sound. If the spatialize field is TRUE, the sound should be treated as a monaural sound coming from a single point. A simple spatialization mechanism just places the sound properly in the pan of the stereo (or multichannel) sound output. Sounds are faded out over distance as described above. Browsers may use more elaborate sound spatialization algorithms if they wish.
Authors can create ambient sounds by setting the spatialize field to FALSE. In that case, stereo and multichannel sounds should be played using their normal separate channels. The distance to the sound and the minimum and maximum ellipsoids (discussed above) should affect the intensity in the normal way. Authors can create ambient sound over the entire scene by setting the minFront and minBack to the maximum extents of the scene.
Differences between the VSG implementation and the VRML97 specification
Limitations
Note: These new fields are not compatible with VRML97. If you set these fields to non-default values and then write a VRML file, the VRML file will not be readable by standard VRML97 readers. Older versions of Open Inventor will not be able to read the file either and will generate an Inventor read error (unknown field).
FILE FORMAT/DEFAULT
- VRMLSound {
| direction | 0 0 1 |
| intensity | 1 |
| location | 0 0 0 |
| maxBack | 10 |
| maxFront | 10 |
| minBack | 1 |
| minFront | 1 |
| priority | 0 |
| source | NULL |
| spatialize | TRUE |
| dopplerFactor | 0.0 |
| dopplerVelocity | 343 |
| metadata | NULL |
EVENTS
- Deprecated:
-
Deprecated since Open Inventor 9500
The VRML API is no longer supported. See section http://oivdoc95.vsg3d.com/content/compatibility-notes-4#Deprecation of the Reference Manual. - Inventor/VRMLnodes/SoVRMLSound.h
eventIn
| SoSFVec3f | set_direction |
| SoSFFloat | set_intensity |
| SoSFVec3f | set_location |
| SoSFFloat | set_maxBack (Note: Not implemented) |
| SoSFFloat | set_maxFront (Note: Not implemented) |
| SoSFFloat | set_minBack (Note: Not implemented) |
| SoSFFloat | set_minFront |
| SoSFFloat | set_priority (Note: Not implemented) |
| SoSFNode | set_source |
| SoSFNode | set_metadata |
eventOut
| SoSFVec3f | direction_changed |
| SoSFFloat | intensity_changed |
| SoSFVec3f | location_changed |
| SoSFFloat | maxBack_changed (Note: Not implemented) |
| SoSFFloat | maxFront_changed (Note: Not implemented) |
| SoSFFloat | minBack_changed (Note: Not implemented) |
| SoSFFloat | minFront_changed |
| SoSFFloat | priority_changed (Note: Not implemented) |
| SoSFNode | source_changed |
| SoSFNode | metadata_changed |
Constructor & Destructor Documentation
| SoVRMLSound::SoVRMLSound | ( | ) |
Constructor.
Member Function Documentation
| static SoType SoVRMLSound::getClassTypeId | ( | ) | [static] |
Returns the type identifier for this class.
Reimplemented from SoVRMLNode.
| virtual SoType SoVRMLSound::getTypeId | ( | ) | const [virtual] |
Returns the type identifier for this specific instance.
Reimplemented from SoVRMLNode.
Member Data Documentation
The direction the ellipsoidal sound pattern is pointing.
Doppler factor value.
0 deactivates the Doppler effect.
NOTE: field available since Open Inventor 4.0NOTE 2: This field is not compatible with VRML97. If you specify a non-default value for this field, when this node is written to a VRML file, the file will contain this incompatible field and standard VRML97 file readers will not be able to read it.
Doppler velocity value in meters/sec. NOTE: field available since Open Inventor 4.0
NOTE 2: This field is not compatible with VRML97. If you specify a non-default value for this field, when this node is written to a VRML file, the file will contain this incompatible field and standard VRML97 file readers will not be able to read it.
Adjusts the volume of each sound source.
Position of the sound source.
(Note: Not implemented) Around the location of the emitter, minFront and minBack determine the extent of the full intensity region in front of and behind the sound.
If the location of the sound is taken as a focus of an ellipsoid, the minBack and minFront values, in combination with the direction vector determine the two focii of an ellipsoid bounding the ambient region of the sound. Similarly, maxFront and maxBack determine the limits of audibility in front of and behind the sound; they describe a second, outer ellipsoid.
(Note: Not implemented) Around the location of the emitter, minFront and minBack determine the extent of the full intensity region in front of and behind the sound.
If the location of the sound is taken as a focus of an ellipsoid, the minBack and minFront values, in combination with the direction vector determine the two focii of an ellipsoid bounding the ambient region of the sound. Similarly, maxFront and maxBack determine the limits of audibility in front of and behind the sound; they describe a second, outer ellipsoid.
(Note: Not implemented) Around the location of the emitter, minFront and minBack determine the extent of the full intensity region in front of and behind the sound.
If the location of the sound is taken as a focus of an ellipsoid, the minBack and minFront values, in combination with the direction vector determine the two focii of an ellipsoid bounding the ambient region of the sound. Similarly, maxFront and maxBack determine the limits of audibility in front of and behind the sound; they describe a second, outer ellipsoid.
Around the location of the emitter, minFront and minBack determine the extent of the full intensity region in front of and behind the sound.
If the location of the sound is taken as a focus of an ellipsoid, the minBack and minFront values, in combination with the direction vector determine the two focii of an ellipsoid bounding the ambient region of the sound. Similarly, maxFront and maxBack determine the limits of audibility in front of and behind the sound; they describe a second, outer ellipsoid.
(Note: Not implemented) Controls which sound is heard when more than one sound is active.
Not implemented.
Sound source for the sound node.
(Note: Not implemented) If TRUE, the sound is treated as a monaural sound from a single point.
If FALSE, ambient sounds can be created.
The documentation for this class was generated from the following file: