Runtime API

Functions for streaming and rendering data.

Contents

Asset Decoder API
Functions for decompressing streaming data.

Classes

struct UmbraEnvironmentInfo
Environment parameters.
struct UmbraStreamingState
Runtime streaming statistics.
struct UmbraSceneInfo
Scene information.
struct UmbraFilterShape
A filter shape.
struct UmbraRenderable
A renderable object.
struct UmbraSceneCopyDestination
Scene copy destination.
struct UmbraSceneCopySource
Scene copy source.
struct UmbraMeshInfo
Mesh description.
struct UmbraMaterialInfo
Material description.
struct UmbraTextureInfo
Texture description.
struct UmbraRayQueryResult
Ray query result.

Enums

enum (anonymous) { UmbraInvalidUserPointer = 0 }
enum UmbraTextureSupportFlagBits { UmbraTextureSupportFlags_None = 0, UmbraTextureSupportFlags_BC1 = 1 << 0, UmbraTextureSupportFlags_BC2 = 1 << 1, UmbraTextureSupportFlags_BC3 = 1 << 2, UmbraTextureSupportFlags_BC4 = 1 << 3, UmbraTextureSupportFlags_BC5 = 1 << 4, UmbraTextureSupportFlags_BC6H = 1 << 5, UmbraTextureSupportFlags_BC7 = 1 << 6, UmbraTextureSupportFlags_ASTC = 1 << 7, UmbraTextureSupportFlags_ETC1 = 1 << 8, UmbraTextureSupportFlags_ETC2 = 1 << 9, UmbraTextureSupportFlags_EAC_R = 1 << 10, UmbraTextureSupportFlags_EAC_RG = 1 << 11, UmbraTextureSupportFlags_PVRTC1 = 1 << 12, UmbraTextureSupportFlags_PVRTC2 = 1 << 13, UmbraTextureSupportFlags_ATC = 1 << 14, UmbraTextureSupportFlags_HalfFloat = 1 << 15, UmbraTextureSupportFlags_Float = 1 << 16, UmbraTextureSupportFlags_All = 0x7FFFFFFF }
Hardware specific texture formats.
enum UmbraRuntimeFlagBits { UmbraRuntimeFlags_NeverUnload = 1 << 0, UmbraRuntimeFlags_ExclusiveRendering = 1 << 1, UmbraRuntimeFlags_EnableRayQueries = 1 << 2 }
Runtime behavior configuration.
enum UmbraConnectionStatus { UmbraConnectionStatus_Connected = 0, UmbraConnectionStatus_Connecting, UmbraConnectionStatus_ConnectionError }
Scene connection status.
enum UmbraDepthRange { UmbraDepthRange_ZeroToOne = 0, UmbraDepthRange_MinusOneToOne }
Depth range conventions.
enum UmbraFilterShapeType { UmbraFilterShapeType_Sphere = 0, UmbraFilterShapeType_Cylinder }
Filter shape types.
enum UmbraSceneCopyStatus { UmbraSceneCopyStatus_InProgress = 0, UmbraSceneCopyStatus_Done, UmbraSceneCopyStatus_Error }
Scene copy status.
enum UmbraSceneCopyDestinationType { UmbraSceneCopyDestinationType_File = 0, UmbraSceneCopyDestinationType_Directory, UmbraSceneCopyDestinationType_Cloud, UmbraSceneCopyDestinationType_FormatObj }
Scene copy destinations.
enum UmbraSceneCopySourceType { UmbraSceneCopySourceType_Directory = 0, UmbraSceneCopySourceType_Cloud }
Scene copy sources.
enum UmbraAssetType { UmbraAssetType_Material, UmbraAssetType_Texture, UmbraAssetType_Mesh }
Asset types.
enum UmbraAssetLoadResult { UmbraAssetLoadResult_Failure, UmbraAssetLoadResult_OutOfMemory, UmbraAssetLoadResult_Aborted, UmbraAssetLoadResult_Success }
Asset load results.
enum UmbraRayQueryFlagBits { UmbraRayQueryFlags_BackfaceCulling = 1 << 0 }
Ray query flags.

Typedefs

typedef uint32_t UmbraTextureSupportFlags
A bitmask of UmbraTextureSupportFlagBits.
typedef uint32_t UmbraRuntimeFlags
A bitmask of UmbraRuntimeFlagBits.
typedef uint32_t UmbraRayQueryFlags
A bitmask of UmbraRayQueryFlagBits.
typedef uint64_t UmbraUserPointer
An opaque asset handle type.
typedef struct UmbraRuntime UmbraRuntime
Opaque runtime object.
typedef struct UmbraScene UmbraScene
Opaque scene object.
typedef struct UmbraView UmbraView
Opaque view object.
typedef struct UmbraSceneCopy UmbraSceneCopy
Opaque scene copy handle.
typedef struct UmbraAssetLoad UmbraAssetLoad
Opaque asset load object.
typedef struct UmbraAssetUnload UmbraAssetUnload
Opaque asset unload object.
typedef struct UmbraTextureMetaData UmbraTextureMetaData
Opaque texture metadata object.

Functions

void UmbraEnvironmentInfoDefaults(UmbraEnvironmentInfo* environment)
Initializes a default environment.
UmbraRuntime* UmbraRuntimeCreate(UmbraClient* client, const UmbraEnvironmentInfo* environment, UmbraRuntimeFlags flags)
Create a runtime object.
void UmbraRuntimeUpdate(UmbraRuntime* runtime)
Update a runtime object.
void UmbraRuntimeGetStreamingState(UmbraRuntime* runtime, UmbraStreamingState* streamingState)
Get streaming statistics.
void UmbraRuntimeDestroy(UmbraRuntime* runtime)
Destroy a runtime object.
UmbraSceneCopy* UmbraSceneCopyCreate(UmbraRuntime* runtime, const UmbraSceneCopyDestination* destination, const UmbraSceneCopySource* source, const UmbraEnvironmentInfo* environment, const UmbraFilterShape* filter)
Start a scene copy from source to destination.
UmbraSceneCopyStatus UmbraSceneCopyGetStatus(UmbraSceneCopy* sceneCopy, float* progress)
Get the status of a scene copy.
const char* UmbraSceneCopyGetError(UmbraSceneCopy* sceneCopy)
Returns the error message of the scene copy object.
void UmbraSceneCopyDestroy(UmbraSceneCopy* sceneCopy)
Destroy a scene copy object.
uint32_t UmbraVertexAttributeGetElementByteSize(UmbraVertexAttribute vertexAttribute)
Get the element size of a vertex attribute type.
UmbraAssetLoad* UmbraRuntimeNextAssetLoad(UmbraRuntime* runtime)
Get the next asset load object from the asset load queue.
UmbraAssetType UmbraAssetLoadGetType(const UmbraAssetLoad* assetLoad)
Get the type of an asset load object.
void UmbraAssetLoadPrepare(UmbraAssetLoad* assetLoad, UmbraUserPointer ptr)
Prepare an asset load object by assigning it a unique identifier.
UmbraBool UmbraAssetLoadAbortRequested(const UmbraAssetLoad* assetLoad)
Check if an asset load has been aborted by the runtime.
void UmbraAssetLoadFinish(UmbraAssetLoad* assetLoad, UmbraAssetLoadResult result)
Finish an asset load.
void UmbraMeshLoadFinishExternal(UmbraAssetLoad* assetLoad, UmbraAssetLoadResult result, const UmbraElementBuffer vertexBuffers[UmbraVertexAttributeCount], const UmbraElementBuffer* indexBuffer)
Finish a serialized mesh load.
void UmbraMeshLoadGetInfo(const UmbraAssetLoad* assetLoad, UmbraMeshInfo* meshInfo)
Get mesh metadata.
UmbraBool UmbraMeshLoadGetData(const UmbraAssetLoad* assetLoad, const UmbraElementBuffer vertexBuffers[UmbraVertexAttributeCount], const UmbraElementBuffer* indexBuffer)
Decode a mesh.
UmbraBool UmbraMeshStreamSetBuffers(const UmbraAssetLoad* assetLoad, const UmbraElementBuffer vertexBuffers[UmbraVertexAttributeCount], const UmbraElementBuffer* indexBuffer)
Start a streamed mesh decode.
UmbraBool UmbraMeshStreamNext(const UmbraAssetLoad* assetLoad, uint32_t* numVertices, uint32_t* numIndices)
Decode the next chunk of a mesh.
UmbraBool UmbraMeshStreamDone(const UmbraAssetLoad* assetLoad)
Check if a streaming mesh decode has completed.
UmbraBool UmbraMeshLoadSerialize(const UmbraAssetLoad* assetLoad, UmbraByteBuffer buffer)
Serialize a mesh into a buffer.
uint32_t UmbraMeshLoadGetSerializedSize(const UmbraAssetLoad* assetLoad)
Get the amount of space required to serialize a mesh into a buffer.
uint32_t UmbraTextureGetMipmapLevelByteSize(const UmbraTextureInfo* textureInfo, int level)
Get the data size of a texture's mipmap level.
uint32_t UmbraTextureGetMipmapLevelOffset(const UmbraTextureInfo* textureInfo, int level)
Get the data offset of a texture's mipmap level.
void UmbraTextureLoadGetInfo(const UmbraAssetLoad* assetLoad, UmbraTextureInfo* textureInfo)
Get texture metadata.
UmbraBool UmbraTextureLoadGetData(const UmbraAssetLoad* assetLoad, const UmbraByteBuffer* buffer)
Decode a texture.
uint32_t UmbraTextureLoadGetSerializedSize(const UmbraAssetLoad* assetLoad)
Get the amount of space required to serialize a texture into a buffer.
UmbraBool UmbraTextureLoadSerialize(const UmbraAssetLoad* assetLoad, UmbraByteBuffer buffer)
Serialize a texture into a buffer.
void UmbraMaterialLoadGetInfo(const UmbraAssetLoad* assetLoad, UmbraMaterialInfo* materialInfo)
Get material information.
UmbraAssetUnload* UmbraRuntimeNextAssetUnload(UmbraRuntime* runtime)
Get the next asset unload object from the asset unload queue.
UmbraAssetType UmbraAssetUnloadGetType(const UmbraAssetUnload* assetUnload)
Get the type of an asset unload.
UmbraUserPointer UmbraAssetUnloadGetUserPointer(const UmbraAssetUnload* assetUnload)
Get the asset's user pointer from an asset unload object.
void UmbraAssetUnloadFinish(UmbraAssetUnload* assetUnload)
Finish an asset unload.
UmbraDouble3 UmbraGeodeticToEcef(UmbraDouble3 geodetic)
Converts a geodetic coordinate to an ECEF coordinate.
UmbraDouble3 UmbraEcefToGeodetic(UmbraDouble3 ecef)
Converts an ECEF coordinate to a geodetic coordinate.

Enum details

enum (anonymous)

Enumerators
UmbraInvalidUserPointer

The invalid UmbraUserPointer.

enum UmbraTextureSupportFlagBits

Hardware specific texture formats.

Enumerators
UmbraTextureSupportFlags_None
UmbraTextureSupportFlags_BC1
UmbraTextureSupportFlags_BC2
UmbraTextureSupportFlags_BC3
UmbraTextureSupportFlags_BC4
UmbraTextureSupportFlags_BC5
UmbraTextureSupportFlags_BC6H
UmbraTextureSupportFlags_BC7
UmbraTextureSupportFlags_ASTC
UmbraTextureSupportFlags_ETC1
UmbraTextureSupportFlags_ETC2
UmbraTextureSupportFlags_EAC_R
UmbraTextureSupportFlags_EAC_RG
UmbraTextureSupportFlags_PVRTC1
UmbraTextureSupportFlags_PVRTC2
UmbraTextureSupportFlags_ATC
UmbraTextureSupportFlags_HalfFloat

16-bit floating point textures.

UmbraTextureSupportFlags_Float

32-bit floating point textures.

UmbraTextureSupportFlags_All

A forward-compatible way to declare you support every format.

May be useful for software rendering.

enum UmbraRuntimeFlagBits

Runtime behavior configuration.

Enumerators
UmbraRuntimeFlags_NeverUnload

Never release assets after they are loaded into memory.

UmbraRuntimeFlags_ExclusiveRendering
UmbraRuntimeFlags_EnableRayQueries

Enable ray queries.

This requires additional memory.

enum UmbraConnectionStatus

Scene connection status.

Enumerators
UmbraConnectionStatus_Connected
UmbraConnectionStatus_Connecting
UmbraConnectionStatus_ConnectionError

The scene connection failed.

It can fail for many reasons, such as an invalid sdk-concept-api-key or a network failure.

enum UmbraDepthRange

Depth range conventions.

Enumerators
UmbraDepthRange_ZeroToOne

The Direct3D convention, where the depth range is in [0,1] after the w division.

UmbraDepthRange_MinusOneToOne

The OpenGL convention, where the depth range is in [-1,1] after the w division.

enum UmbraFilterShapeType

Filter shape types.

Enumerators
UmbraFilterShapeType_Sphere

A sphere, defined by its center and radius.

UmbraFilterShapeType_Cylinder

A cylinder of infinite length, defined by an axis and radius.

enum UmbraSceneCopyStatus

Scene copy status.

Enumerators
UmbraSceneCopyStatus_InProgress

The copy is in progress, and has neither succeeded nor failed.

UmbraSceneCopyStatus_Done

The copy completed successfully.

UmbraSceneCopyStatus_Error

The copy failed.

enum UmbraSceneCopyDestinationType

Scene copy destinations.

Enumerators
UmbraSceneCopyDestinationType_File

A local file.

UmbraSceneCopyDestinationType_Directory

A local directory containing many files.

UmbraSceneCopyDestinationType_Cloud

The Umbra Cloud.

UmbraSceneCopyDestinationType_FormatObj

A local Wavefront OBJ file.

enum UmbraSceneCopySourceType

Scene copy sources.

Enumerators
UmbraSceneCopySourceType_Directory

A local directory.

UmbraSceneCopySourceType_Cloud

The Umbra Cloud.

enum UmbraAssetType

Asset types.

Enumerators
UmbraAssetType_Material

A material.

UmbraAssetType_Texture

A texture.

UmbraAssetType_Mesh

A mesh.

enum UmbraAssetLoadResult

Asset load results.

Enumerators
UmbraAssetLoadResult_Failure

The load failed for some unspecified reason.

UmbraAssetLoadResult_OutOfMemory

Ran out of memory.

UmbraAssetLoadResult_Aborted

The load was aborted.

UmbraAssetLoadResult_Success

The load completed successfully.

enum UmbraRayQueryFlagBits

Ray query flags.

Enumerators
UmbraRayQueryFlags_BackfaceCulling

Ray queries pass through backfaces when this flag is set.

Typedef details

typedef uint64_t UmbraUserPointer

An opaque asset handle type.

Function details

void UmbraEnvironmentInfoDefaults(UmbraEnvironmentInfo* environment)

Initializes a default environment.

Parameters
environment The environment.

UmbraRuntime* UmbraRuntimeCreate(UmbraClient* client, const UmbraEnvironmentInfo* environment, UmbraRuntimeFlags flags)

Create a runtime object.

Parameters
client in The client whose platform services will be used by the runtime object.
environment in The pointer to the UmbraEnvironmentInfo structure describing environment parameters.
flags in The bitmask of UmbraRuntimeFlagBits specifying runtime behaviour. Can be 0.
Returns A new runtime object.

void UmbraRuntimeUpdate(UmbraRuntime* runtime)

Update a runtime object.

Parameters
runtime in The runtime object.

void UmbraRuntimeGetStreamingState(UmbraRuntime* runtime, UmbraStreamingState* streamingState)

Get streaming statistics.

Parameters
runtime in The runtime object.
streamingState out Streaming stats.

void UmbraRuntimeDestroy(UmbraRuntime* runtime)

Destroy a runtime object.

Parameters
runtime in The runtime object.

UmbraSceneCopy* UmbraSceneCopyCreate(UmbraRuntime* runtime, const UmbraSceneCopyDestination* destination, const UmbraSceneCopySource* source, const UmbraEnvironmentInfo* environment, const UmbraFilterShape* filter)

Start a scene copy from source to destination.

Parameters
runtime in The runtime object.
destination in The copy destination.
source in The copy source.
environment in Environment information at the destination.
filter in A filter shape, limiting what geometry should be copied. Can be NULL, in which case all geometry is copied.
Returns A new scene copy object.

UmbraSceneCopyStatus UmbraSceneCopyGetStatus(UmbraSceneCopy* sceneCopy, float* progress)

Get the status of a scene copy.

Parameters
sceneCopy in The scene copy object.
progress out The copy progress, ranging from 0.0 to 1.0. May be NULL.
Returns The copy status.

const char* UmbraSceneCopyGetError(UmbraSceneCopy* sceneCopy)

Returns the error message of the scene copy object.

Parameters
sceneCopy in The scene copy object.
Returns An ASCII encoded string describing the scene copy status. It is statically allocated and doesn't need to be deallocated.

void UmbraSceneCopyDestroy(UmbraSceneCopy* sceneCopy)

Destroy a scene copy object.

Parameters
sceneCopy in The scene copy object.

uint32_t UmbraVertexAttributeGetElementByteSize(UmbraVertexAttribute vertexAttribute)

Get the element size of a vertex attribute type.

Parameters
vertexAttribute in The vertex attribute type.
Returns The element size in bytes.

UmbraAssetLoad* UmbraRuntimeNextAssetLoad(UmbraRuntime* runtime)

Get the next asset load object from the asset load queue.

Parameters
runtime in The runtime object.
Returns A pointer to an opaque asset load object, or NULL if the asset load queue is empty.

UmbraAssetType UmbraAssetLoadGetType(const UmbraAssetLoad* assetLoad)

Get the type of an asset load object.

Parameters
assetLoad in The asset load object.
Returns The asset load object's type.

void UmbraAssetLoadPrepare(UmbraAssetLoad* assetLoad, UmbraUserPointer ptr)

Prepare an asset load object by assigning it a unique identifier.

Parameters
assetLoad in The asset load object whose state to be prepared.
ptr in The user pointer used to identify the asset.

UmbraBool UmbraAssetLoadAbortRequested(const UmbraAssetLoad* assetLoad)

Check if an asset load has been aborted by the runtime.

Parameters
assetLoad in The asset load object.
Returns Non-zero if the load has been aborted.

void UmbraAssetLoadFinish(UmbraAssetLoad* assetLoad, UmbraAssetLoadResult result)

Finish an asset load.

Parameters
assetLoad in The asset load.
result in The asset load result.

void UmbraMeshLoadFinishExternal(UmbraAssetLoad* assetLoad, UmbraAssetLoadResult result, const UmbraElementBuffer vertexBuffers[UmbraVertexAttributeCount], const UmbraElementBuffer* indexBuffer)

Finish a serialized mesh load.

Parameters
assetLoad in The asset load.
result in The asset load result.
vertexBuffers in The decoded vertex buffers.
indexBuffer in The decoded index buffer.

void UmbraMeshLoadGetInfo(const UmbraAssetLoad* assetLoad, UmbraMeshInfo* meshInfo)

Get mesh metadata.

Parameters
assetLoad in The asset load object.
meshInfo out Mesh metadata.

UmbraBool UmbraMeshLoadGetData(const UmbraAssetLoad* assetLoad, const UmbraElementBuffer vertexBuffers[UmbraVertexAttributeCount], const UmbraElementBuffer* indexBuffer)

Decode a mesh.

Parameters
assetLoad in The asset load object.
vertexBuffers out The vertex buffers.
indexBuffer out The index buffer.
Returns Non-zero on success. Fails if the buffers don't meet the conditions listed below.

UmbraBool UmbraMeshStreamSetBuffers(const UmbraAssetLoad* assetLoad, const UmbraElementBuffer vertexBuffers[UmbraVertexAttributeCount], const UmbraElementBuffer* indexBuffer)

Start a streamed mesh decode.

Parameters
assetLoad in The asset load object.
vertexBuffers out The vertex buffers.
indexBuffer out The index buffer.
Returns Non-zero on success. Fails and returns zero if the buffers don't meet the conditions listed under UmbraMeshLoadGetData.

UmbraBool UmbraMeshStreamNext(const UmbraAssetLoad* assetLoad, uint32_t* numVertices, uint32_t* numIndices)

Decode the next chunk of a mesh.

Parameters
assetLoad in The asset load object.
numVertices out The number of vertices decoded with this function call.
numIndices out The number of indices decoded with this function call.
Returns Non-zero if the chunk was successfully decoded.

UmbraBool UmbraMeshStreamDone(const UmbraAssetLoad* assetLoad)

Check if a streaming mesh decode has completed.

Parameters
assetLoad in The asset load object.
Returns Non-zero if the decode completed, zero if there is still data to decode.

UmbraBool UmbraMeshLoadSerialize(const UmbraAssetLoad* assetLoad, UmbraByteBuffer buffer)

Serialize a mesh into a buffer.

Parameters
assetLoad in The asset load object.
buffer out The output buffer. Must be aligned to at least 16 bytes.
Returns Non-zero on success.

uint32_t UmbraMeshLoadGetSerializedSize(const UmbraAssetLoad* assetLoad)

Get the amount of space required to serialize a mesh into a buffer.

Parameters
assetLoad in The asset load object.
Returns Required buffer size in bytes.

uint32_t UmbraTextureGetMipmapLevelByteSize(const UmbraTextureInfo* textureInfo, int level)

Get the data size of a texture's mipmap level.

Parameters
textureInfo in The texture.
level in The mip level. Must be 0, or less than UmbraTextureInfo::numMipLevels.
Returns The size of the requested mipmap level's pixel data, in bytes.

uint32_t UmbraTextureGetMipmapLevelOffset(const UmbraTextureInfo* textureInfo, int level)

Get the data offset of a texture's mipmap level.

Parameters
textureInfo in The texture.
level in The mip level. Must be 0, or less than UmbraTextureInfo::numMipLevels.
Returns The offset of the request mipmap level's pixel data, in bytes.

void UmbraTextureLoadGetInfo(const UmbraAssetLoad* assetLoad, UmbraTextureInfo* textureInfo)

Get texture metadata.

Parameters
assetLoad in The asset load object.
textureInfo out Texture metadata.

UmbraBool UmbraTextureLoadGetData(const UmbraAssetLoad* assetLoad, const UmbraByteBuffer* buffer)

Decode a texture.

Parameters
assetLoad in The asset load object.
buffer out The output buffer.
Returns Non-zero on success.

uint32_t UmbraTextureLoadGetSerializedSize(const UmbraAssetLoad* assetLoad)

Get the amount of space required to serialize a texture into a buffer.

Parameters
assetLoad in The asset load object.
Returns Required buffer size in bytes.

UmbraBool UmbraTextureLoadSerialize(const UmbraAssetLoad* assetLoad, UmbraByteBuffer buffer)

Serialize a texture into a buffer.

Parameters
assetLoad in The asset load object.
buffer out The output buffer. Must be aligned to at least 16 bytes.
Returns Non-zero on success.

void UmbraMaterialLoadGetInfo(const UmbraAssetLoad* assetLoad, UmbraMaterialInfo* materialInfo)

Get material information.

Parameters
assetLoad in The asset load object.
materialInfo out The material information.

UmbraAssetUnload* UmbraRuntimeNextAssetUnload(UmbraRuntime* runtime)

Get the next asset unload object from the asset unload queue.

Parameters
runtime in The runtime object.
Returns A pointer to an opaque asset unload object, or NULL if the asset unload queue is empty.

UmbraAssetType UmbraAssetUnloadGetType(const UmbraAssetUnload* assetUnload)

Get the type of an asset unload.

Parameters
assetUnload in The asset unload object.
Returns The type of the asset unload object.

UmbraUserPointer UmbraAssetUnloadGetUserPointer(const UmbraAssetUnload* assetUnload)

Get the asset's user pointer from an asset unload object.

Parameters
assetUnload in The asset unload object.
Returns The asset's user pointer.

void UmbraAssetUnloadFinish(UmbraAssetUnload* assetUnload)

Finish an asset unload.

Parameters
assetUnload in The asset unload object.

UmbraDouble3 UmbraGeodeticToEcef(UmbraDouble3 geodetic)

Converts a geodetic coordinate to an ECEF coordinate.

Parameters
geodetic in Longitude, latitude and elevation.
Returns The ECEF coordinate.

UmbraDouble3 UmbraEcefToGeodetic(UmbraDouble3 ecef)

Converts an ECEF coordinate to a geodetic coordinate.

Parameters
ecef in x, y and z coordinates in ECEF space.
Returns The geodetic coordinate as longitude, latitude and elevation.