Runtime View API

Functions for managing views.

Functions

UmbraView* UmbraViewCreate(UmbraRuntime* runtime)
Create a view object.
void UmbraViewUpdateRendering(UmbraView* view, const UmbraFloat4_4* cameraWorldToClip, const UmbraFloat3* cameraPosition, UmbraDepthRange cameraDepthRange, UmbraMatrixFormat cameraMatrixFormat, float quality, const UmbraFloat3 directionalLights[], int numDirectionalLights)
Recompute view's renderables for a camera.
void UmbraViewUpdateFilter(UmbraView* view, const UmbraFilterShape* filterShape)
Recompute view's renderables for a filter shape.
int UmbraViewNextRenderables(UmbraView* view, UmbraRenderable renderables[], int numRenderables)
Read the set of renderables.
void UmbraViewResetRenderables(UmbraView* view)
Reset a view's renderables cursor, so the next call to UmbraViewNextRenderables starts from the first renderable.
void UmbraViewDestroy(UmbraView* view)
Destroy a view object.
UmbraBool UmbraViewRayQuery(UmbraView* view, const UmbraFloat3* rayOrigin, const UmbraFloat3* rayDirection, float maxDistance, UmbraRayQueryFlags flags, UmbraRayQueryResult* result)
Perform a ray cast against a view.

Function details

UmbraView* UmbraViewCreate(UmbraRuntime* runtime)

Create a view object.

Parameters
runtime in The runtime object.
Returns A new view object.

void UmbraViewUpdateRendering(UmbraView* view, const UmbraFloat4_4* cameraWorldToClip, const UmbraFloat3* cameraPosition, UmbraDepthRange cameraDepthRange, UmbraMatrixFormat cameraMatrixFormat, float quality, const UmbraFloat3 directionalLights[], int numDirectionalLights)

Recompute view's renderables for a camera.

Parameters
view in The view.
cameraWorldToClip in The world to clip space transformation.
cameraPosition in The camera position.
cameraDepthRange in The camera depth range.
cameraMatrixFormat in cameraWorldToClip's matrix format.
quality in The rendering quality, between 0.0 (lowest quality) and 1.0 (highest quality).
directionalLights in An array of up to 31 directional lights. Can be NULL.
numDirectionalLights in The number of directional lights in the directionalLights array. Can be 0, and should be when directionalLights is NULL.

Calling this function re-computes the renderables that should be rendered for this view. If the renderables are not already resident, loads will be issued. This function returns immediately and doesn't wait for network traffic or asset loads to complete. Instead, list of renderables for this view continues to update as new data becomes available.

void UmbraViewUpdateFilter(UmbraView* view, const UmbraFilterShape* filterShape)

Recompute view's renderables for a filter shape.

Parameters
view in The view.
filterShape in The new filter shape.

Like UmbraViewUpdateRendering, except that instead of computing renderables based on camera parameters the list of renderables is computed based on the given filter volume.

UpdateFilter() and UpdateRendering() both re-compute the list of renderables from scratch, overriding the state set by previous UpdateFilter() or UpdateRendering()call. Thus it is not possible to combine camera-based rendering and a filter in a single view.

A common use case for UpdateFilter() is to stream in renderables at a certain fixed LOD level around the camera to serve as a collision mesh.

int UmbraViewNextRenderables(UmbraView* view, UmbraRenderable renderables[], int numRenderables)

Read the set of renderables.

Parameters
view in The view.
renderables out An array of renderables.
numRenderables in The size of the renderables array.
Returns The number of renderables stored.

Each time you call this function, it copies up to numRenderables renderables to the renderables array and advances an internal cursor. To read the complete set, you should call this function repeatedly until its return value is less than numRenderables.

void UmbraViewResetRenderables(UmbraView* view)

Reset a view's renderables cursor, so the next call to UmbraViewNextRenderables starts from the first renderable.

Parameters
view in The view.

void UmbraViewDestroy(UmbraView* view)

Destroy a view object.

Parameters
view in The view.

UmbraBool UmbraViewRayQuery(UmbraView* view, const UmbraFloat3* rayOrigin, const UmbraFloat3* rayDirection, float maxDistance, UmbraRayQueryFlags flags, UmbraRayQueryResult* result)

Perform a ray cast against a view.

Parameters
view in The view.
rayOrigin in The ray origin in world space.
rayDirection in The ray direction. Must be unit length.
maxDistance in The maximum distance in world space units. Can be FLT_MAX.
flags in The bitmask of UmbraRayQueryFlagBits specifying ray traversal behaviour. Can be 0.
result out Where to store the UmbraRayQueryResult structure, or NULL if ignored.
Returns Non-zero if the ray hit anything. Zero if the ray missed all the geometry, or if the runtime object wasn't created with the UmbraRuntimeFlags_EnableRayQueries flag.

This function intersects a ray against the meshes in a view, and returns information about the intersection point.