Graphics

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.

TypeNameDescription
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.

ValueDescription
"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: []

MaterialLayer
Type: object

A material layer.

Properties

Name Type Summary
material Entities.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.

ValueDescription
"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.overte.org/examples/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.