SoVRMLAudioClip(3)

📦 version 3.1.3, in fedora 43, fedora 44

SoVRMLAudioClip(3) — hiii bestie, you just opened the Library Functions Manual 🎀 and this is the whole entire vibe of SoVRMLAudioClip. It's a lot, so buckle up: this is part 1 of 2, and the rest is coming right after, so don't go anywhere. 💅

✨ NAME ✨

SoVRMLAudioClip — the class that is literally used to load and store audio data. That's the whole job description. It loads. It stores. Iconic behaviour, no notes. 🎧✨

🌸 SYNOPSIS 🌸

First things first, you gotta pull it in:

#include <Inventor/VRMLnodes/SoVRMLAudioClip.h>

And it inherits from SoNode — so it's out here living that node life, with all the node drama that comes with it. 🦋

🎀 Public Types 🎀

These are the callback types you can hand over, fr fr:

  • open_func — typedef void * open_func(const SbStringList &url, SoVRMLAudioClip *clip, void *userdataptr) — the "open it up" hook 🫶
  • read_func — typedef size_t read_func(void *datasource, void *buffer, int numframes, int &channels, SoVRMLAudioClip *clip, void *userdataptr) — the "read it" hook, and yes it takes numframes and hands you back channels 💖
  • seek_func — typedef int seek_func(void *datasource, long offset, int whence, SoVRMLAudioClip *clip, void *userdataptr) — the "jump around" hook ✨
  • tell_func — typedef long tell_func(void *datasource, SoVRMLAudioClip *clip, void *userdataptr) — the "where even are we rn" hook 👑
  • close_func — typedef int close_func(void *datasource, SoVRMLAudioClip *clip, void *userdataptr) — the "ok bye" hook 💀

✨ Public Types inherited from SoNode ✨

Just one, and it's a whole enum moment:

enum NodeType { INVENTOR = 0x0000, VRML1 = 0x0001, VRML2 = 0x0002,
    INVENTOR_1 = 0x0004, INVENTOR_2_0 = 0x0008, INVENTOR_2_1 = 0x0010,
    INVENTOR_2_5 = 0x0020, INVENTOR_2_6 = 0x0040, COIN_1_0 = 0x0080,
    COIN_2_0 = 0x0100, EXTENSION = 0x0200, COIN_2_2 = 0x0400, COIN_2_3 =
    0x0800, COIN_2_4 = 0x1000, INVENTOR_5_0 = 0x2000, COIN_2_5 = 0x4000,
    COIN_3_0 = 0x8000, INVENTOR_6_0 = 0x10000 }

💅 Public Member Functions 💅

The actual main-character functions of this class, in order:

  • virtual SoType getTypeId (void) const — the type-checker, she's virtual 💖
  • SoVRMLAudioClip (void) — the constructor, hi bestie 👋
  • int getSampleRate () — grab that sample rate 🎵
  • void * open (const SbStringList &url) — open it up
  • size_t read (void *datasource, void *buffer, int numframes, int &channels) — read those frames
  • int seek (void *datasource, long offset, int whence) — seek, seek, seek
  • long tell (void *datasource) — tell me where we at
  • int close (void *datasource) — close her down
  • void setCallbacks (open_func *opencb, read_func *readcb, seek_func *seekcb, tell_func *tellcb, close_func *closecb, void *userdataptr) — swap in all your custom hooks in one go, slay 🫶

🌈 Public Member Functions inherited from SoNode 🌈

All of these come straight from SoNode, unchanged — listing them all anyway because we do not skip, ever:

  • void setOverride (const SbBool state)
  • SbBool isOverride (void) const
  • void setNodeType (const NodeType type)
  • NodeType getNodeType (void) const
  • virtual SoNode * copy (SbBool copyconnections=FALSE) const
  • virtual SbBool affectsState (void) const
  • virtual void doAction (SoAction *action)
  • virtual void GLRender (SoGLRenderAction *action)
  • virtual void GLRenderBelowPath (SoGLRenderAction *action)
  • virtual void GLRenderInPath (SoGLRenderAction *action)
  • virtual void GLRenderOffPath (SoGLRenderAction *action)
  • virtual void callback (SoCallbackAction *action)
  • virtual void getBoundingBox (SoGetBoundingBoxAction *action)
  • virtual void getMatrix (SoGetMatrixAction *action)
  • virtual void handleEvent (SoHandleEventAction *action)
  • virtual void pick (SoPickAction *action)
  • virtual void rayPick (SoRayPickAction *action)
  • virtual void search (SoSearchAction *action)
  • virtual void write (SoWriteAction *action)
  • virtual void audioRender (SoAudioRenderAction *action)
  • virtual void getPrimitiveCount (SoGetPrimitiveCountAction *action)
  • virtual void grabEventsSetup (void)
  • virtual void grabEventsCleanup (void)
  • virtual void startNotify (void)
  • virtual void notify (SoNotList *l)
  • uint32_t getNodeId (void) const
  • virtual SoChildList * getChildren (void) const
  • virtual void writeInstance (SoOutput *out)
  • virtual SoNode * addToCopyDict (void) const
  • virtual void copyContents (const SoFieldContainer *from, SbBool copyconnections)
  • virtual SoFieldContainer * copyThroughConnection (void) const

💜 Public Member Functions inherited from SoFieldContainer 💜

Field-container core, all inherited:

  • void setToDefaults (void)
  • SbBool hasDefaultValues (void) const
  • SbBool fieldsAreEqual (const SoFieldContainer *container) const
  • void copyFieldValues (const SoFieldContainer *container, SbBool copyconnections=FALSE)
  • SbBool set (const char *const fielddata)
  • void get (SbString &fielddata)
  • virtual int getFields (SoFieldList &l) const
  • virtual int getAllFields (SoFieldList &l) const
  • virtual SoField * getField (const SbName &name) const
  • virtual SoField * getEventIn (const SbName &name) const
  • virtual SoField * getEventOut (const SbName &name) const
  • SbBool getFieldName (const SoField *const field, SbName &name) const
  • SbBool enableNotify (const SbBool flag)
  • SbBool isNotifyEnabled (void) const
  • SbBool set (const char *fielddata, SoInput *input)
  • void get (SbString &fielddata, SoOutput *out)
  • virtual SbBool validateNewFieldValue (SoField *field, void *newval)
  • virtual void addWriteReference (SoOutput *out, SbBool isfromfield=FALSE)
  • SbBool getIsBuiltIn (void) const
  • virtual void getFieldsMemorySize (size_t &managed, size_t &unmanaged) const
  • void setUserData (void *userdata) const
  • void * getUserData (void) const

🦋 Public Member Functions inherited from SoBase 🦋

The O.G. base class crew, inherited as-is:

  • void ref (void) const
  • void unref (void) const
  • void unrefNoDelete (void) const
  • int32_t getRefCount (void) const
  • void touch (void)
  • SbBool isOfType (SoType type) const
  • virtual SbName getName (void) const
  • virtual void setName (const SbName &newname)
  • void addAuditor (void *const auditor, const SoNotRec::Type type)
  • void removeAuditor (void *const auditor, const SoNotRec::Type type)
  • const SoAuditorList & getAuditors (void) const
  • SbBool shouldWrite (void)
  • void assertAlive (void) const

🌟 Static Public Member Functions 🌟

The static ones that belong to the class itself, not an instance:

  • static SoType getClassTypeId (void) — class type ID, periodt
  • static void initClass (void) — run this to set the class up ✨
  • static void setSubdirectories (const SbList< SbString > &subdirectories) — set those subdirectories
  • static const SbStringList & getSubdirectories () — get those subdirectories
  • static void setDefaultPauseBetweenTracks (SbTime pause) — default pause between tracks, the lil breather 🎶
  • static SbTime getDefaultPauseBetweenTracks () — grab that pause value
  • static void setDefaultIntroPause (SbTime pause) — default intro pause, the pre-roll moment
  • static SbTime getDefaultIntroPause () — grab that intro pause
  • static void setDefaultSampleRate (int samplerate) — set the default sample rate 🎵
  • static int getDefaultSampleRate () — get the default sample rate
  • static void setDefaultTimerInterval (SbTime interval) — set the default timer interval ⏱️
  • static SbTime getDefaultTimerInterval () — get that timer interval

⭐ Static Public Member Functions inherited from SoNode ⭐

  • static uint32_t getCompatibilityTypes (const SoType &nodetype)
  • static SoType getClassTypeId (void)
  • static SoNode * getByName (const SbName &name)
  • static int getByName (const SbName &name, SoNodeList &l)
  • static void initClass (void)
  • static void initClasses (void)
  • static uint32_t getNextNodeId (void)
  • static int getActionMethodIndex (const SoType type)
  • static void getBoundingBoxS (SoAction *action, SoNode *node)
  • static void GLRenderS (SoAction *action, SoNode *node)
  • static void callbackS (SoAction *action, SoNode *node)
  • static void getMatrixS (SoAction *action, SoNode *node)
  • static void handleEventS (SoAction *action, SoNode *node)
  • static void pickS (SoAction *action, SoNode *node)
  • static void rayPickS (SoAction *action, SoNode *node)
  • static void searchS (SoAction *action, SoNode *node)
  • static void writeS (SoAction *action, SoNode *node)
  • static void audioRenderS (SoAction *action, SoNode *node)
  • static void getPrimitiveCountS (SoAction *action, SoNode *node)

🌸 Static Public Member Functions inherited from SoFieldContainer 🌸

  • static void initClass (void)
  • static SoType getClassTypeId (void)
  • static void cleanupClass (void)
  • static void initCopyDict (void)
  • static void addCopy (const SoFieldContainer *orig, const SoFieldContainer *copy)
  • static SoFieldContainer * checkCopy (const SoFieldContainer *orig)
  • static SoFieldContainer * findCopy (const SoFieldContainer *orig, const SbBool copyconnections)
  • static void copyDone (void)

🎀 Static Public Member Functions inherited from SoBase 🎀

  • static void initClass (void)
  • static SoType getClassTypeId (void)
  • static void addName (SoBase *const base, const char *const name)
  • static void removeName (SoBase *const base, const char *const name)
  • static void incrementCurrentWriteCounter (void)
  • static void decrementCurrentWriteCounter (void)
  • static SoBase * getNamedBase (const SbName &name, SoType type)
  • static int getNamedBases (const SbName &name, SoBaseList &baselist, SoType type)
  • static SbBool read (SoInput *input, SoBase *&base, SoType expectedtype)
  • static void setInstancePrefix (const SbString &c)
  • static void setTraceRefs (SbBool trace)
  • static SbBool getTraceRefs (void)
  • static SbBool connectRoute (SoInput *input, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname)
  • static SbBool readRoute (SoInput *input)

👑 Public Attributes 👑

These are the fields you actually set on an audio clip, and they're kind of the whole point:

  • SoSFString description — a description field 🫶
  • SoSFBool loop — loop it or don't, your call
  • SoSFFloat pitch — the pitch 🔥
  • SoSFTime startTime — when it starts
  • SoSFTime stopTime — when it stops
  • SoMFString url — the URL(s), and yes it's multi, bestie 🌈

💖 Protected Member Functions 💖

  • virtual const SoFieldData * getFieldData (void) const
  • virtual ~SoVRMLAudioClip ()

💜 Protected Member Functions inherited from SoNode 💜

  • SoNode (void)
  • virtual ~SoNode ()
  • virtual SbBool readInstance (SoInput *in, unsigned short flags)

✨ Protected Member Functions inherited from SoFieldContainer ✨

  • SoFieldContainer (void)
  • virtual ~SoFieldContainer ()

🌈 Protected Member Functions inherited from SoBase 🌈

  • SoBase (void)
  • virtual ~SoBase ()
  • virtual void destroy (void)
  • SbBool hasMultipleWriteRefs (void) const
  • SbBool writeHeader (SoOutput *out, SbBool isgroup, SbBool isengine) const
  • void writeFooter (SoOutput *out) const
  • virtual const char * getFileFormatName (void) const

⭐ Static Protected Member Functions ⭐

  • static const SoFieldData ** getFieldDataPtr (void)

🦋 Static Protected Member Functions inherited from SoNode 🦋

  • static const SoFieldData ** getFieldDataPtr (void)
  • static void setNextActionMethodIndex (int index)
  • static int getNextActionMethodIndex (void)
  • static void incNextActionMethodIndex (void)
  • static void setCompatibilityTypes (const SoType &nodetype, const uint32_t bitmask)

🎀 Static Protected Member Functions inherited from SoBase 🎀

  • static uint32_t getCurrentWriteCounter (void)
  • static void staticDataLock (void)
  • static void staticDataUnlock (void)

🔥 Protected Attributes 🔥

  • SoSFTime duration_changed — this one's protected, so it's for the class's own business, not yours 🙈
  • SoSFBool isActive — also protected, also class business

💅 Protected Attributes inherited from SoNode 💅

  • uint32_t uniqueId

🌸 Protected Attributes inherited from SoFieldContainer 🌸

  • SbBool isBuiltIn

💖 Additional Inherited Members 💖

Protected Types inherited from SoBase

enum BaseFlags { IS_ENGINE = 0x01, IS_GROUP = 0x02 }

Static Protected Attributes inherited from SoNode

  • static uint32_t nextUniqueId = 1
  • static int nextActionMethodIndex = 0

(part 1 of 2 — hold on bestie, there's more coming 💅)

💖 Detailed Description 💖

okay so bestie, the SoVRMLAudioClip class is literally the load-and-store audio data queen. 👑 she holds your audio data, she plays it, she's the whole vibe.

audio data gets loaded using the simage library, so make sure you've built simage with support for the audio file formats you intend to use — that means libogg, libvorbis and libvorbisfile for OggVorbis, plus libsndfile for WAV and several other formats. no cap. 🎧✨

the detailed class documentation is taken verbatim from the VRML97 standard (ISO/IEC 14772-1:1997). It is copyright The Web3D Consortium, and is used by permission of the Consortium:

       AudioClip {
         exposedField   SFString description      ""
         exposedField   SFBool   loop             FALSE
         exposedField   SFFloat  pitch            1.0        # (0, inf)
         exposedField   SFTime   startTime        0          # (-inf, inf)
         exposedField   SFTime   stopTime         0          # (-inf, inf)
         exposedField   MFString url              []
         eventOut       SFTime   duration_changed
         eventOut       SFBool   isActive
       }

An AudioClip node specifies audio data that can be referenced by Sound nodes. the description field is just a textual description of the audio source. a browser is not required to display the description field, but it may choose to do so in addition to playing the sound. the url field specifies the URL from which the sound is loaded. browsers shall support at least the wavefile format in uncompressed PCM format (see http://www.web3d.org/x3d/specifications/vrml/ISO-IEC-14772-VRML97/part1/bibliography.html#[WAV]). it is recommended that browsers also support the MIDI file type 1 sound format (see http://www.web3d.org/x3d/specifications/vrml/ISO-IEC-14772-VRML97/part1/references.html#[MIDI]); MIDI files are presumed to use the General MIDI patch set. Subclause 4.5, VRML and the World Wide Web (http://www.web3d.org/x3d/specifications/vrml/ISO-IEC-14772-VRML97/part1/concepts.html#4.5), contains details on the url field.

💀 the results are undefined when no URLs refer to supported data types.

the loop, startTime, and stopTime exposedFields and the isActive eventOut, and their effects on the AudioClip node, are discussed in detail in 4.6.9, Time-dependent nodes (http://www.web3d.org/x3d/specifications/vrml/ISO-IEC-14772-VRML97/part1/concepts.html#4.6.9). the "cycle" of an AudioClip is the length of time in seconds for one playing of the audio at the specified pitch. the pitch field specifies a multiplier for the rate at which sampled sound is played. values for the pitch field shall be greater than zero. changing the pitch field affects both the pitch and playback speed of a sound. a set_pitch event to an active AudioClip is ignored and no pitch_changed eventOut is generated. if pitch is set to 2.0, the sound shall be played one octave higher than normal and played twice as fast. for a sampled sound, the pitch field alters the sampling rate at which the sound is played. the proper implementation of pitch control for MIDI (or other note sequence sound clips) is to multiply the tempo of the playback by the pitch value and adjust the MIDI Coarse Tune and Fine Tune controls to achieve the proper pitch change. a duration_changed event is sent whenever there is a new value for the "normal" duration of the clip. typically, this will only occur when the current url in use changes and the sound data has been loaded, indicating that the clip is playing a different sound source. the duration is the length of time in seconds for one cycle of the audio for a pitch set to 1.0. changing the pitch field will not trigger a duration_changed event. a duration value of "-1" implies that the sound data has not yet loaded or the value is unavailable for some reason. a duration_changed event shall be generated if the AudioClip node is loaded when the VRML file is read or the AudioClip node is added to the scene graph. the isActive eventOut may be used by other nodes to determine if the clip is currently active. if an AudioClip is active, it shall be playing the sound corresponding to the sound time (i.e., in the sound's local time system with sample 0 at time 0):

t = (now - startTime) modulo (duration / pitch)

💅 Constructor & Destructor Documentation 💅

✨ SoVRMLAudioClip::SoVRMLAudioClip (void )

Constructor. that's it. that's the whole thing. she's born. 🎀

🦋 SoVRMLAudioClip::~SoVRMLAudioClip () [protected], [virtual]

Destructor. protected, virtual, and ready to say bye. 💅

👑 Member Function Documentation 👑

🌟 SoType SoVRMLAudioClip::getTypeId (void ) const [virtual]

Returns the type identification of an object derived from a class inheriting SoBase. this is used for run-time type checking and "downward" casting.

usage example, bestie:

       void foo(SoNode * node)
       {
         if (node->getTypeId() == SoFile::getClassTypeId()) {
           SoFile * filenode = (SoFile *)node;  // safe downward cast, knows the type
         }
       }

for application programmers wanting to extend the library with new nodes, engines, nodekits, draggers or others: this method needs to be overridden in all subclasses. this is typically done as part of setting up the full type system for extension classes, which is usually accomplished by using the pre-defined macros available through for instance Inventor/nodes/SoSubNode.h (SO_NODE_INIT_CLASS and SO_NODE_CONSTRUCTOR for node classes), Inventor/engines/SoSubEngine.h (for engine classes) and so on.

for more information on writing Coin extensions, see the class documentation of the toplevel superclasses for the various class groups.

Implements SoBase.

💜 const SoFieldData * SoVRMLAudioClip::getFieldData (void ) const [protected], [virtual]

Returns a pointer to the class-wide field data storage object for this instance. if no fields are present, returns NULL.

Reimplemented from SoFieldContainer.

🎧 void * SoVRMLAudioClip::open (const SbStringList & urlref)

Opens an audio source with the given url. Returns a handle to the datasource. slay. 🔥

📖 size_t SoVRMLAudioClip::read (void * datasource, void * buffer, int numframes, int & channels)

Reads numframes frames of audio with channels channels from datasource into buffer. Buffer must be allocated by the caller, and must be able to hold all the audio data (size = numframes * channels * sizeof(int16_t)). the function must always fill the buffer completely unless buffer == NULL.

when an error occurs, or when end-of-file has been reached, this function returns 0. otherwise, the function should return numframes.

when the caller receives a return value of 0, it will queue the returned buffer for playing. when this buffer is finished playing, the caller will call read() one final time, with buffer == NULL. the read() function can then set the isActive field to FALSE, free any resources allocated, etc.

🌀 int SoVRMLAudioClip::seek (void * datasource, long offset, int whence)

Moves the "filepointer" in the datasource, returns -1L on error.

🧭 long SoVRMLAudioClip::tell (void * datasource)

Returns the current position of the "filepointer" in the datasource, or -1L on error.

🔒 int SoVRMLAudioClip::close (void * datasource)

Closes datasource. bye bestie. 👋

🪄 void SoVRMLAudioClip::setCallbacks (open_func * opencb, read_func * readcb, seek_func * seekcb, tell_func * tellcb, close_func * closecb, void * userdataptr)

Sets callbacks for opening, reading, seeking, telling and closing an audio source. specifying NULL for a function is OK, except for the read function. if a function set to NULL is later called, a default implementation doing nothing is called in its place.

💎 Member Data Documentation 💎

🌸 SoSFString SoVRMLAudioClip::description

Description of the audio clip. default value is an empty string.

🔁 SoSFBool SoVRMLAudioClip::loop

Specifies whether sound should be looped. is FALSE by default.

🎵 SoSFFloat SoVRMLAudioClip::pitch

Specifies the pitch. the default value is 1.0.

Alters the sampling rate at which the sound is played. a pitch of 2.0 means that the sound should be played twice as fast and one octave higher than normal.

⏰ SoSFTime SoVRMLAudioClip::startTime

Specifies the start time. default value is 0.

🛑 SoSFTime SoVRMLAudioClip::stopTime

Specifies the stop time. default value is 0.

🌐 SoMFString SoVRMLAudioClip::url

The audio data URL.

⏳ SoSFTime SoVRMLAudioClip::duration_changed [protected]

An eventOut sent when a new sound starts playing.

🟢 SoSFBool SoVRMLAudioClip::isActive [protected]

This eventOut is sent when the sound starts/stops playing.

✍️ Author ✍️

Generated automatically by Doxygen for Coin from the source code.

okay bestie, that's the whole page. 💖 this little masterpiece came from Coin Version 3.1.3, and it's the SoVRMLAudioClip(3) manual page. go forth and slay your audio clips. periodt. 💅✨

📦 where this page comes from