Graphics - Vircadia API Docs

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts

The Graphics API enables you to access and manipulate avatar, entity, and overlay models in the rendered scene. This includes getting mesh and material information for applying Material entities.

Methods

Name	Return Value	Summary
`canUpdateModel`	boolean	Checks whether the model for an avatar, entity, or overlay can be updated in the rendered scene. Only avatars, `"Model"` entities and `"model"` overlays can have their meshes updated.
`exportModelToOBJ`	string	Exports a model to OBJ format.
`getModel`	GraphicsModel	Gets a handle to the model data used for displaying an avatar, 3D entity, or 3D overlay. Note: The model data may be used for more than one instance of the item displayed in the scene.
`newMesh`	GraphicsMesh	Creates a new graphics mesh.
`newModel`	GraphicsModel	Creates a new graphics model from meshes.
`updateModel`	boolean	Updates the model for an avatar, 3D entity, or 3D overlay in the rendered scene.

Type Definitions

BufferElementFormat
Type: object

Details of a buffer element's format.

Properties

Name	Type	Summary
type	string	Type.
semantic	string	Semantic.
dimension	string	Dimension.
scalarCount	number	Scalar count.
byteSize	number	Byte size.
BYTES_PER_ELEMENT	number	Bytes per element.

BufferFormat
Type: object

Details of buffer's format.

Properties

Name	Type	Summary
slot	number	Slot.
length	number	Length.
byteLength	number	Byte length.
offset	number	Offset.
stride	number	Stride.
element	Graphics.BufferElementFormat	Element format.

BufferType
Type: Vec4 | Vec3 | Vec2

The type of a graphics buffer value as accessed by JavaScript.

Type	Name	Description
Vec3	`"position"`	Position buffer.
Vec3	`"normal"`	normal buffer.
Vec3	`"tangent"`	Tangent buffer.
Vec4	`"color"`	Color buffer.
Vec4	`"skin_cluster_index"`	Skin cluster index buffer.
Vec4	`"skin_cluster_weight"`	Skin cluster weight buffer.
Vec2	`"texcoord0"`	First UV coordinates buffer.
Vec2	`"texcoord1"`	Second UV coordinates buffer.
Vec2	`"texcoord2"`	Third UV coordinates buffer.
Vec2	`"texcoord3"`	Fourth UV coordinates buffer.
Vec2	`"texcoord4"`	Fifth UV coordinates buffer.

BufferTypeName
Type: string

The type name of a graphics buffer.

Value	Description
`"position"`	Position buffer.
`"normal"`	normal buffer.
`"tangent"`	Tangent buffer.
`"color"`	Color buffer.
`"skin_cluster_index"`	Skin cluster index buffer.
`"skin_cluster_weight"`	Skin cluster weight buffer.
`"texcoord0"`	First UV coordinates buffer.
`"texcoord1"`	Second UV coordinates buffer.
`"texcoord2"`	Third UV coordinates buffer.
`"texcoord3"`	Fourth UV coordinates buffer.
`"texcoord4"`	Fifth UV coordinates buffer.

IFSData
Type: object

IFS (Indexed-Face Set) data defining a mesh.

Properties

Name	Type	Attributes	Summary
name	string	<optional>	Mesh name. (Useful for debugging.) Default Value: ""
topology	Graphics.MeshTopology		Element interpretation. Currently only triangles is supported.
indices	Array.<number>		Vertex indices to use for the mesh faces, in tuples per the `topology`.
positions	Array.<Vec3>		Vertex positions, in model coordinates.
normals	Array.<Vec3>	<optional>	Vertex normals (normalized). Default Value: []
colors	Array.<Vec3>	<optional>	Vertex colors (normalized). Default Value: []
texCoords0	Array.<Vec2>	<optional>	Vertex texture coordinates (normalized). Default Value: []

Material
Type: object

A material in a GraphicsModel.

Properties

Name	Type	Attributes	Summary
name	string		The name of the material.
model	string		Different material models support different properties and rendering modes. Supported models are: `"hifi_pbr"` and `"hifi_shader_simple"`.
albedo	Vec3 \| string	<optional>	The albedo color. Component values are in the range `0.0` – `1.0`. If `"fallthrough"` then it falls through to the material below.
opacity	number \| string	<optional>	The opacity, range `0.0` – `1.0`. If `"fallthrough"` then it falls through to the material below.
opacityCutoff	number \| string	<optional>	The opacity cutoff threshold used to determine the opaque texels of the `opacityMap` when `opacityMapMode` is `"OPACITY_MAP_MASK"`. Range `0.0` – `1.0`. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
roughness	number \| string	<optional>	The roughness, range `0.0` – `1.0`. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
metallic	number \| string	<optional>	The metallicness, range `0.0` – `1.0`. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
scattering	number \| string	<optional>	The scattering, range `0.0` – `1.0`. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
unlit	boolean \| string	<optional>	`true` if the material is unaffected by lighting, `false` if it it is lit by the key light and local lights. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
emissive	Vec3 \| string	<optional>	The emissive color, i.e., the color that the material emits. Component values are in the range `0.0` – `1.0`. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
albedoMap	string	<optional>	The URL of the albedo texture image. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
opacityMap	string	<optional>	The URL of the opacity texture image. `"hifi_pbr"` model only.
opacityMapMode	string	<optional>	The mode defining the interpretation of the opacity map. Values can be: `"OPACITY_MAP_OPAQUE"` for ignoring the opacity map information. `"OPACITY_MAP_MASK"` for using the `opacityMap` as a mask, where only the texel greater than `opacityCutoff` are visible and rendered opaque. `"OPACITY_MAP_BLEND"` for using the `opacityMap` for alpha blending the material surface with the background. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
occlusionMap	string	<optional>	The URL of the occlusion texture image. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
lightMap	string	<optional>	The URL of the light map texture image. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
lightmapParams	string	<optional>	Parameters for controlling how `lightMap` is used. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only. Currently not used.
scatteringMap	string	<optional>	The URL of the scattering texture image. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
emissiveMap	string	<optional>	The URL of the emissive texture image. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
metallicMap	string	<optional>	The URL of the metallic texture image. If `"fallthrough"` then it and `specularMap` fall through to the material below. Only use one of `metallicMap` and `specularMap`. `"hifi_pbr"` model only.
specularMap	string	<optional>	The URL of the specular texture image. Only use one of `metallicMap` and `specularMap`. `"hifi_pbr"` model only.
roughnessMap	string	<optional>	The URL of the roughness texture image. If `"fallthrough"` then it and `glossMap` fall through to the material below. Only use one of `roughnessMap` and `glossMap`. `"hifi_pbr"` model only.
glossMap	string	<optional>	The URL of the gloss texture image. Only use one of `roughnessMap` and `glossMap`. `"hifi_pbr"` model only.
normalMap	string	<optional>	The URL of the normal texture image. If `"fallthrough"` then it and `bumpMap` fall through to the material below. Only use one of `normalMap` and `bumpMap`. `"hifi_pbr"` model only.
bumpMap	string	<optional>	The URL of the bump texture image. Only use one of `normalMap` and `bumpMap`. `"hifi_pbr"` model only.
materialParams	string	<optional>	Parameters for controlling the material projection and repetition. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only. Currently not used.
cullFaceMode	string	<optional>	Specifies Which faces of the geometry to render. Values can be: `"CULL_NONE"` to render both sides of the geometry. `"CULL_FRONT"` to cull the front faces of the geometry. `"CULL_BACK"` (the default) to cull the back faces of the geometry. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only. Default Value: "CULL_BACK"
texCoordTransform0	Mat4 \| string	<optional>	The transform to use for all of the maps apart from `occlusionMap` and `lightMap`. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
texCoordTransform1	Mat4 \| string	<optional>	The transform to use for `occlusionMap` and `lightMap`. If `"fallthrough"` then it falls through to the material below. `"hifi_pbr"` model only.
procedural	string		The definition of a procedural shader material. `"hifi_shader_simple"` model only. Currently not used.
defaultFallthrough	boolean		`true` if all properties fall through to the material below unless they are set, `false` if properties respect their individual fall-through settings.

MaterialLayer
Type: object

A material layer.

Properties

Name	Type	Summary
material	Graphics.Material	The layer's material.
priority	number	The priority of the layer. If multiple materials are applied to a mesh part, only the layer with the highest priority is applied, with materials of the same priority randomly assigned.

MeshExtents
Type: object

The extents of a mesh.

Properties

Name	Type	Summary
brn	Vec3	The bottom right near (minimum axes values) corner of the enclosing box.
tfl	Vec3	The top far left (maximum axes values) corner of the enclosing box.
center	Vec3	The center of the enclosing box.
dimensions	Vec3	The dimensions of the enclosing box.

MeshTopology
Type: string

The interpretation of mesh elements.

Value	Description
`"points"`	Points.
`"lines"`	Lines.
`"line_strip"`	Line strip.
`"triangles"`	Triangles.
`"triangle_strip"`	Triangle strip.
`"quads"`	Quads.
`"quad_strip"`	Quad strip.

Method Details

(static) canUpdateModel( id, meshIndexopt, partNumberopt ) → {boolean}
Returns: true if the model can be updated, false if it can't.

Checks whether the model for an avatar, entity, or overlay can be updated in the rendered scene. Only avatars, "Model" entities and "model" overlays can have their meshes updated.

Parameters

Name	Type	Attributes	Default Value	Description
`id`	Uuid			The ID of the avatar, entity, or overlay.
`meshIndex`	number	<optional>	-1	Not used.
`partNumber`	number	<optional>	-1	Not used.

Example

Test whether different types of items can be updated.

var modelEntityID = Entities.addEntity({
    type: "Model",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(Camera.orientation, { x: -0.5, y: 0, z: -3 })),
    rotation: MyAvatar.orientation,
    modelURL: "https://apidocs.vircadia.dev/models/cowboy-hat.fbx",
    dimensions: { x: 0.8569, y: 0.3960, z: 1.0744 },
    lifetime: 300  // Delete after 5 minutes.
});
var shapeEntityID = Entities.addEntity({
    type: "Shape",
    shape: "Cylinder",
    position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(Camera.orientation, { x: 0.5, y: 0, z: -3 })),
    dimensions: { x: 0.4, y: 0.6, z: 0.4 },
    lifetime: 300  // Delete after 5 minutes.
});

Script.setTimeout(function () {
    print("Can update avatar:", Graphics.canUpdateModel(MyAvatar.sessionUUID));  // true
    print("Can update model entity:", Graphics.canUpdateModel(modelEntityID));  // true
    print("Can update shape entity:", Graphics.canUpdateModel(shapeEntityID));  // false
}, 1000);  // Wait for the entities to rez.

(static) exportModelToOBJ( model ) → {string}
Returns: The OBJ format representation of the model.

Exports a model to OBJ format.

Parameters

Name	Type	Description
`model`	GraphicsModel	The model to export.

(static) getModel( id ) → {GraphicsModel}
Returns: The model data for the avatar, entity, or overlay, as displayed. This includes the results of applying any Material entities to the item.

Gets a handle to the model data used for displaying an avatar, 3D entity, or 3D overlay.

Note: The model data may be used for more than one instance of the item displayed in the scene.

Parameters

Name	Type	Description
`id`	UUID	The ID of the avatar, 3D entity, or 3D overlay.

Example

Report some details of your avatar's model.

var model = Graphics.getModel(MyAvatar.sessionUUID);
var meshes = model.meshes;
var numMeshparts = 0;
for (var i = 0; i < meshes.length; i++) {
    numMeshparts += meshes[i].numParts;
}

print("Avatar:", MyAvatar.skeletonModelURL);
print("Number of meshes:", model.numMeshes);
print("Number of mesh parts:", numMeshparts);
print("Material names: ", model.materialNames);
print("Material layers:", Object.keys(model.materialLayers));

(static) newMesh( ifsMeshData ) → {GraphicsMesh}
Returns: The new graphics mesh.

Creates a new graphics mesh.

Parameters

Name	Type	Description
`ifsMeshData`	Graphics.IFSData	Index-Faced Set (IFS) data defining the mesh.

(static) newModel( meshes ) → {GraphicsModel}
Returns: The new graphics model.

Creates a new graphics model from meshes.

Parameters

Name	Type	Description
`meshes`	Array.<GraphicsMesh>	The meshes to include in the model.

(static) updateModel( id, model ) → {boolean}
Returns: true if the update was completed successfully, false if it wasn't.

Updates the model for an avatar, 3D entity, or 3D overlay in the rendered scene.

Parameters

Name	Type	Description
`id`	Uuid	The ID of the avatar, 3D entity, or 3D overlay to update.
`model`	GraphicsModel	The model to update the avatar, 3D entity, or 3D overlay with.