Graphics - Overte 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: []

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.

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