Scene¶

Typedefs¶

typedef struct _IPLScene_t *IPLScene¶

A 3D scene, which can contain geometry objects that can interact with acoustic rays.

The scene object itself doesn’t contain any geometry, but is a container for IPLStaticMesh and IPLInstancedMesh objects, which do contain geometry.

typedef struct _IPLStaticMesh_t *IPLStaticMesh¶

A triangle mesh that doesn’t move or deform in any way.

The unchanging portions of a scene should typically be collected into a single static mesh object. In addition to the geometry, a static mesh also contains acoustic material information for each triangle.

typedef struct _IPLInstancedMesh_t *IPLInstancedMesh¶

A triangle mesh that can be moved (translated), rotated, or scaled, but cannot deform.

Portions of a scene that undergo rigid-body motion can be represented as instanced meshes. An instanced mesh is essentially a scene (called the “sub-scene”) with a transform applied to it. Adding an instanced mesh to a scene places the sub-scene into the scene with the transform applied. For example, the sub-scene may be a prefab door, and the transform can be used to place it in a doorway and animate it as it opens or closes.

Functions¶

IPLerror iplSceneCreate(IPLContext context, IPLSceneSettings *settings, IPLScene *scene)¶

Creates a scene.

A scene does not store any geometry information on its own; for that you need to create one or more static meshes or instanced meshes and add them to the scene.

Parameters

context – The context used to initialize Steam Audio.
settings – The settings to use when creating the scene.
scene – [out] The created scene.

Returns

Status code indicating success or failure.

IPLScene iplSceneRetain(IPLScene scene)¶

Retains an additional reference to a scene.

Parameters: scene – The scene to retain a reference to.
Returns: The additional reference to the scene.

void iplSceneRelease(IPLScene *scene)¶

Releases a reference to a scene.

Parameters: scene – The scene to release a reference to.

IPLerror iplSceneLoad(IPLContext context, IPLSceneSettings *settings, IPLSerializedObject serializedObject, IPLProgressCallback progressCallback, void *progressCallbackUserData, IPLScene *scene)¶

Loads a scene from a serialized object.

Typically, the serialized object will be created from a byte array loaded from disk or over the network.

Parameters

context – The context used to initialize Steam Audio.
settings – The settings to use when creating the scene.
serializedObject – The serialized object from which to load the scene.
progressCallback – Callback that reports the percentage of this function’s work that has been completed. May be NULL.
progressCallbackUserData – Pointer to arbitrary data that will be passed to the progress callback. May be NULL.
scene – [out] The created scene.

Returns

Status code indicating whether or not the operation succeeded.

void iplSceneSave(IPLScene scene, IPLSerializedObject serializedObject)¶

Saves a scene to a serialized object.

Typically, the serialized object will then be saved to disk.

This function can only be called on a scene created with IPL_SCENETYPE_DEFAULT.**

Parameters

scene – The scene to save.
serializedObject – The serialized object into which to save the scene.

void iplSceneSaveOBJ(IPLScene scene, IPLstring fileBaseName)¶

Saves a scene to an OBJ file.

An OBJ file is a widely-supported 3D model file format, that can be displayed using a variety of software on most PC platforms. The OBJ file generated by this function can be useful for detecting problems that occur when exporting scene data from your application to Steam Audio.

This function can only be called on a scene created with IPL_SCENETYPE_DEFAULT or IPL_SCENETYPE_EMBREE.**

Parameters

scene – The scene to save.
fileBaseName – Absolute or relative path to the OBJ file to generate.

void iplSceneCommit(IPLScene scene)¶

Commits any changes to the scene.

This function should be called after any calls to the following functions, for the changes to take effect:

iplStaticMeshAdd
iplStaticMeshRemove
iplInstancedMeshAdd
iplInstancedMeshRemove
iplInstancedMeshUpdateTransform

For best performance, call this function once after all changes have been made for a given frame.

This function cannot be called concurrently with any simulation functions.**

Parameters: scene – The scene to commit changes to.

IPLerror iplStaticMeshCreate(IPLScene scene, IPLStaticMeshSettings *settings, IPLStaticMesh *staticMesh)¶

Creates a static mesh.

A static mesh represents a triangle mesh that does not change after it is created. A static mesh also contains an array of acoustic material properties, and a mapping between each of its triangles and their acoustic material properties.

Static mesh objects should be used for scene geometry that is guaranteed to never change, such as rooms, buildings, or triangulated terrain. A scene may contain multiple static meshes, although typically one is sufficient.

Parameters

scene – The scene in which the static mesh should be created.
settings – The settings to use when creating the static mesh.
staticMesh – [out] The created static mesh.

Returns

Status code indicating whether or not the operation succeeded.

IPLStaticMesh iplStaticMeshRetain(IPLStaticMesh staticMesh)¶

Retains an additional reference to a static mesh.

Parameters: staticMesh – The static mesh to retain a reference to.
Returns: The additional reference to the static mesh.

void iplStaticMeshRelease(IPLStaticMesh *staticMesh)¶

Releases a reference to a static mesh.

Parameters: staticMesh – The static mesh to release a reference to.

IPLerror iplStaticMeshLoad(IPLScene scene, IPLSerializedObject serializedObject, IPLProgressCallback progressCallback, void *progressCallbackUserData, IPLStaticMesh *staticMesh)¶

Loads a static mesh from a serialized object.

Typically, the serialized object will be created from a byte array loaded from disk or over the network.

Parameters

scene – The scene in which the static mesh should be created.
serializedObject – The serialized object from which to load the scene.
progressCallback – Callback that reports the percentage of this function’s work that has been completed. May be NULL.
progressCallbackUserData – Pointer to arbitrary data that will be passed to the progress callback. May be NULL.
staticMesh – [out] The created static mesh.

Returns

Status code indicating whether or not the operation succeeded.

void iplStaticMeshSave(IPLStaticMesh staticMesh, IPLSerializedObject serializedObject)¶

Saves a static mesh to a serialized object.

Typically, the serialized object will then be saved to disk.

This function can only be called on a static mesh that is part of a scene created with IPL_SCENETYPE_DEFAULT.

Parameters

staticMesh – The static mesh to save.
serializedObject – The serialized object into which to save the static mesh.

void iplStaticMeshAdd(IPLStaticMesh staticMesh, IPLScene scene)¶

Adds a static mesh to a scene.

This function should be called after iplStaticMeshCreate, or at any point after iplStaticMeshRemove, for the static mesh to start affecting sound propagation.

After calling this function, iplSceneCommit must be called for the changes to take effect.

Parameters

staticMesh – The static mesh to add.
scene – The scene to which to add the static mesh. This must be the scene which was passed when calling iplStaticMeshCreate.

void iplStaticMeshRemove(IPLStaticMesh staticMesh, IPLScene scene)¶

Removes a static mesh from a scene.

After this function is called, the static mesh will stop affecting sound propagation, until it is added back using iplStaticMeshAdd.

After calling this function, iplSceneCommit must be called for the changes to take effect.

Parameters

staticMesh – The static mesh to remove.
scene – The scene from which to remove the static mesh. This must be the scene which was passed when calling iplStaticMeshCreate.

IPLerror iplInstancedMeshCreate(IPLScene scene, IPLInstancedMeshSettings *settings, IPLInstancedMesh *instancedMesh)¶

Creates an instanced mesh.

An instanced mesh takes one scene and positions it within another scene. This is useful if you have the same object, like a pillar, that you want to instantiate multiple times within the same scene. A scene can be instantiated multiple times within another scene, without incurring any significant memory overhead.

The instanced mesh can be moved, rotated, and scaled freely at any time, providing an easy way to implement dynamic objects whose motion can be described purely in terms of rigid-body transformations.

Parameters

scene – The scene in which the instanced mesh should be created.
settings – The settings used to create the instanced mesh.
instancedMesh – [out] The created instanced mesh.

Returns

Status code indicating whether or not the operation succeeded.

IPLInstancedMesh iplInstancedMeshRetain(IPLInstancedMesh instancedMesh)¶

Retains an additional reference to a instanced mesh.

Parameters: instancedMesh – The instanced mesh to retain a reference to.
Returns: The additional reference to the instanced mesh.

void iplInstancedMeshRelease(IPLInstancedMesh *instancedMesh)¶

Releases a reference to a instanced mesh.

Parameters: instancedMesh – The instanced mesh to release a reference to.

void iplInstancedMeshAdd(IPLInstancedMesh instancedMesh, IPLScene scene)¶

Adds an instanced mesh to a scene.

This function should be called after iplInstancedMeshCreate, or at any point after iplInstancedMeshRemove, for the instanced mesh to start affecting sound propagation.

After calling this function, iplSceneCommit must be called for the changes to take effect.

Parameters

instancedMesh – The instanced mesh to add.
scene – The scene to which to add the instanced mesh. This must be the scene which was passed when calling iplInstancedMeshCreate.

void iplInstancedMeshRemove(IPLInstancedMesh instancedMesh, IPLScene scene)¶

Removes an instanced mesh from a scene.

After this function is called, the instanced mesh will stop affecting sound propagation, until it is added back using iplInstancedMeshAdd.

After calling this function, iplSceneCommit must be called for the changes to take effect.

Parameters

instancedMesh – The instanced mesh to remove.
scene – The scene from which to remove the instanced mesh. This must be the scene which was passed when calling iplInstancedMeshCreate.

void iplInstancedMeshUpdateTransform(IPLInstancedMesh instancedMesh, IPLScene scene, IPLMatrix4x4 transform)¶

Updates the local-to-world transform of an instanced mesh within its parent scene.

This function allows the instanced mesh to be moved, rotated, and scaled dynamically.

After calling this function, iplSceneCommit must be called for the changes to take effect.

Parameters

instancedMesh – The instanced mesh whose transform is to be updated.
scene – The parent scene that contains the instanced mesh.
transform – The new 4x4 local-to-world transform matrix.

Structures¶

struct IPLTriangle¶

A triangle in 3D space.

Triangles are specified by their three vertices, which are in turn specified using indices into a vertex array.

Steam Audio uses a counter-clockwise winding order. This means that when looking at the triangle such that the normal is pointing towards you, the vertices are specified in counter-clockwise order.

Each triangle must be specified using three vertices; triangle strip or fan representations are not supported.

Public Members

IPLint32 indices[3]¶: Indices of the three vertices of this triangle.

struct IPLMaterial¶

The acoustic properties of a surface.

You can specify the acoustic material properties of each triangle, although typically many triangles will share a common material.

The acoustic material properties are specified for three frequency bands with center frequencies of 400 Hz, 2.5 KHz, and 15 KHz.

Below are the acoustic material properties for a few standard materials.

{"generic",{0.10f,0.20f,0.30f,0.05f,0.100f,0.050f,0.030f}}
{"brick",{0.03f,0.04f,0.07f,0.05f,0.015f,0.015f,0.015f}}
{"concrete",{0.05f,0.07f,0.08f,0.05f,0.015f,0.002f,0.001f}}
{"ceramic",{0.01f,0.02f,0.02f,0.05f,0.060f,0.044f,0.011f}}
{"gravel",{0.60f,0.70f,0.80f,0.05f,0.031f,0.012f,0.008f}},
{"carpet",{0.24f,0.69f,0.73f,0.05f,0.020f,0.005f,0.003f}}
{"glass",{0.06f,0.03f,0.02f,0.05f,0.060f,0.044f,0.011f}}
{"plaster",{0.12f,0.06f,0.04f,0.05f,0.056f,0.056f,0.004f}}
{"wood",{0.11f,0.07f,0.06f,0.05f,0.070f,0.014f,0.005f}}
{"metal",{0.20f,0.07f,0.06f,0.05f,0.200f,0.025f,0.010f}}
{"rock",{0.13f,0.20f,0.24f,0.05f,0.015f,0.002f,0.001f}}

Public Members

IPLfloat32 absorption[3]¶

Fraction of sound energy absorbed at low, middle, high frequencies.

Between 0.0 and 1.0.

IPLfloat32 scattering¶

Fraction of sound energy scattered in a random direction on reflection.

Between 0.0 (pure specular) and 1.0 (pure diffuse).

IPLfloat32 transmission[3]¶

Fraction of sound energy transmitted through at low, middle, high frequencies.

Between 0.0 and 1.0. Only used for direct occlusion calculations.

struct IPLRay¶

A ray in 3D space.

Public Members

IPLVector3 origin¶: Origin of the ray.

IPLVector3 direction¶: Unit vector direction of the ray.

struct IPLHit¶

Information about a ray’s intersection with 3D geometry.

This information should be provided by ray tracer callbacks when using IPL_SCENETYPE_CUSTOM. Not all fields are required.

Public Members

IPLfloat32 distance¶

Distance along the ray from origin to hit point.

Set to INFINITY if nothing was hit.

IPLint32 triangleIndex¶

(Optional) Index of the primitive hit by the ray.

-1 if not provided.

IPLint32 objectIndex¶

(Optional) Index of the scene object hit by the ray.

-1 if not provided.

IPLint32 materialIndex¶

(Optional) Index of the material associated with the primitive hit by the ray.

-1 if not provided.

IPLVector3 normal¶

Unit length surface normal at the hit point.

Ignored if nothing was hit.

IPLMaterial *material¶

Pointer to the material at the hit point.

Ignored if nothing was hit.

struct IPLSceneSettings¶

Settings used to create a scene.

Public Members

IPLSceneType type¶: Type of scene to create.

IPLClosestHitCallback closestHitCallback¶

Callback for finding the closest hit along a ray.

Only for IPL_SCENETYPE_CUSTOM.

IPLAnyHitCallback anyHitCallback¶

Callback for finding whether a ray hits anything.

Only for IPL_SCENETYPE_CUSTOM.

IPLBatchedClosestHitCallback batchedClosestHitCallback¶

Callback for finding the closest hit along a batch of rays.

Only for IPL_SCENETYPE_CUSTOM.

IPLBatchedAnyHitCallback batchedAnyHitCallback¶

Callback for finding whether a batch of rays hits anything.

Only for IPL_SCENETYPE_CUSTOM.

void *userData¶

Arbitrary user-provided data for use by ray tracing callbacks.

Only for IPL_SCENETYPE_CUSTOM.

IPLEmbreeDevice embreeDevice¶

Handle to an Embree device.

Only for IPL_SCENETYPE_EMBREE.

IPLRadeonRaysDevice radeonRaysDevice¶

Handle to a Radeon Rays device.

Only for IPL_SCENETYPE_RADEONRAYS.

struct IPLStaticMeshSettings¶

Settings used to create a static mesh.

Public Members

IPLint32 numVertices¶: Number of vertices.

IPLint32 numTriangles¶: Number of triangles.

IPLint32 numMaterials¶: Number of materials.

IPLVector3 *vertices¶: Array containing vertices.

IPLTriangle *triangles¶: Array containing (indexed) triangles.

IPLint32 *materialIndices¶: Array containing, for each triangle, the index of the associated material.

IPLMaterial *materials¶: Array of materials.

struct IPLInstancedMeshSettings¶

Settings used to create an instanced mesh.

Public Members

IPLScene subScene¶: Handle to the scene to be instantiated.

IPLMatrix4x4 transform¶: Local-to-world transform that places the instance within the parent scene.

Enumerations¶

enum IPLSceneType¶

The types of scenes that can be created.

Each scene type corresponds to a different ray tracing implementation.

Values:

enumerator IPL_SCENETYPE_DEFAULT¶

Steam Audio’s built-in ray tracer.

Supports multi-threading. Runs on all platforms that Steam Audio supports.

enumerator IPL_SCENETYPE_EMBREE¶

The Intel Embree ray tracer.

Supports multi-threading. This is a highly optimized implementation, and is likely to be faster than the default ray tracer. However, Embree requires Windows, Linux, or macOS, and a 32-bit x86 or 64-bit x86_64 CPU.

enumerator IPL_SCENETYPE_RADEONRAYS¶

The AMD Radeon Rays ray tracer.

This is an OpenCL implementation, and can use either the CPU or any GPU that supports OpenCL 1.2 or later. If using the GPU, it is likely to be significantly faster than the default ray tracer. However, with heavy real-time simulation workloads, it may impact your application’s frame rate. On supported AMD GPUs, you can use the Resource Reservation feature to mitigate this issue.

enumerator IPL_SCENETYPE_CUSTOM¶

Allows you to specify callbacks to your own ray tracer.

Useful if your application already uses a high-performance ray tracer. This option uses the least amount of memory at run-time, since it does not have to build any ray tracing data structures of its own.

Callbacks¶

typedef void (*IPLClosestHitCallback)(const IPLRay *ray, IPLfloat32 minDistance, IPLfloat32 maxDistance, IPLHit *hit, void *userData)¶

Callback for calculating the closest hit along a ray.

Strictly speaking, the intersection is calculated with a ray interval (equivalent to a line segment). Any ray interval may have multiple points of intersection with scene geometry; this function must return information about the point of intersection that is closest to the ray’s origin.

Parameters

ray – The ray to trace.
minDistance – The minimum distance from the origin at which an intersection may occur for it to be considered. This function must not return any intersections closer to the origin than this value.
maxDistance – The maximum distance from the origin at which an intersection may occur for it to be considered. This function must not return any intersections farther from the origin than this value. If this value is less than or equal to minDistance, the function should ignore the ray, and return immediately.
hit – [out] Information describing the ray’s intersection with geometry, if any.
userData – Pointer to a block of memory containing arbitrary data, specified during the call to iplSceneCreate.

typedef void (*IPLAnyHitCallback)(const IPLRay *ray, IPLfloat32 minDistance, IPLfloat32 maxDistance, IPLuint8 *occluded, void *userData)¶

Callback for calculating whether a ray hits any geometry.

Strictly speaking, the intersection is calculated with a ray interval (equivalent to a line segment).

Parameters

ray – The ray to trace.
minDistance – The minimum distance from the origin at which an intersection may occur for it to be considered. This function must not return any intersections closer to the origin than this value.
maxDistance – The maximum distance from the origin at which an intersection may occur for it to be considered. This function must not return any intersections farther from the origin than this value. If this value is less than or equal to minDistance, the function should ignore the ray, set occluded to 1, and return immediately.
occluded – [out] An integer indicating whether the ray intersects any geometry. A value of 0 indicates no intersection, 1 indicates that an intersection exists.
userData – Pointer to a block of memory containing arbitrary data, specified during the call to iplSceneCreate.

typedef void (*IPLBatchedClosestHitCallback)(IPLint32 numRays, const IPLRay *rays, const IPLfloat32 *minDistances, const IPLfloat32 *maxDistances, IPLHit *hits, void *userData)¶

Callback for calculating the closest hit along a batch of rays.

Strictly speaking, the intersection is calculated with a ray interval (equivalent to a line segment). Any ray interval may have multiple points of intersection with scene geometry; this function must return information about the point of intersection that is closest to the ray’s origin.

Parameters

numRays – The number of rays to trace.
rays – Array containing the rays.
minDistances – Array containing, for each ray, the minimum distance from the origin at which an intersection may occur for it to be considered.
maxDistances – Array containing, for each ray, the maximum distance from the origin at which an intersection may occur for it to be considered. If, for some ray with index i, maxDistances[i] is less than minDistances[i], the function should ignore the ray.
hits – [out] Information describing each ray’s intersection with geometry, if any.
userData – Pointer to a block of memory containing arbitrary data, specified during the call to iplSceneCreate.

typedef void (*IPLBatchedAnyHitCallback)(IPLint32 numRays, const IPLRay *rays, const IPLfloat32 *minDistances, const IPLfloat32 *maxDistances, IPLuint8 *occluded, void *userData)¶

Callback for calculating for each ray in a batch of rays, whether the ray hits any geometry.

Strictly speaking, the intersection is calculated with a ray interval (equivalent to a line segment).

Parameters

numRays – The number of rays to trace.
rays – Array containing the rays.
minDistances – Array containing, for each ray, the minimum distance from the origin at which an intersection may occur for it to be considered.
maxDistances – Array containing, for each ray, the maximum distance from the origin at which an intersection may occur for it to be considered. If, for some ray with index i, maxDistances[i] is less than minDistances[i], the function should ignore the ray and set occluded[i] to 1.
occluded – [out] Array of integers indicating, for each ray, whether the ray intersects any geometry. 0 indicates no intersection, 1 indicates that an intersection exists.
userData – Pointer to a block of memory containing arbitrary data, specified during the call to iplSceneCreate.