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

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.01.0. If "fallthrough" then it falls through to the material below.

opacity number | string <optional>

The opacity, range 0.01.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.01.0. If "fallthrough" then it falls through to the material below. "hifi_pbr" model only.

roughness number | string <optional>

The roughness, range 0.01.0. If "fallthrough" then it falls through to the material below. "hifi_pbr" model only.

metallic number | string <optional>

The metallicness, range 0.01.0. If "fallthrough" then it falls through to the material below. "hifi_pbr" model only.

scattering number | string <optional>

The scattering, range 0.01.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.01.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.

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: "http://content.highfidelity.com/seefo/production/puck-attach/vive_tracker_puck.obj",
    dimensions: { x: 0.945, y: 0.921, z: 0.423 },
    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.