Menu - Top - Home - Donate to Me

H3DU

Back to documentation index.

H3DU

The Public Domain HTML 3D Library contains classes and utility methods to ease the development of HTML 3D applications, such as Web sites, in browsers that support 3D drawing using the HTML5 Canvas. See the Library Overview tutorial.

This page describes miscellaneous utility methods included in the library.

Methods

(static) H3DU.createCanvasElement(parent, width, height)

Creates an HTML canvas element, optionally appending it to an existing HTML element.

Parameters

Return Value

The resulting canvas element. (Type: Element)

(static) H3DU.get3DContext(canvasElement, err)

Creates a 3D rendering context from an HTML canvas element.

Parameters

Return Value

A 3D rendering context, or null if an error occurred in creating the context. Returns null if "canvasElement" is null or not an HTML canvas element. (Type: Object)

(static) H3DU.get3DOr2DContext(canvasElement)

Creates a 3D rendering context from an HTML canvas element, falling back to a 2D context if that fails.

Parameters

Return Value

A 3D or 2D rendering context, or null if an error occurred in creating the context. Returns null if "canvasElement" is null or not an HTML canvas element. (Type: Object)

(static) H3DU.getPromiseResults(promises, [progressResolve], [progressReject])

Utility function that returns a promise that resolves after the given list of promises finishes its work.

Parameters

Return Value

A promise that is never rejected and resolves when all of the promises are each resolved or rejected. The result of the promise will be an object with three keys:

(Type: Promise)

(static) H3DU.getPromiseResultsAll(promises, [progressResolve], [progressReject])

Utility function that returns a promise that resolves or is rejected after the given list of promises finishes its work.

Parameters

Return Value

A promise that is resolved when all of the promises are each resolved; the result will be an array of results from those promises, in the order in which those promises were listed. Will be rejected if any of the promises is rejected; the result will be an object as specified in H3DU.getPromiseResults. (Type: Promise)

(static) H3DU.getTimePosition(timer, timeInMs, intervalInMs)

Gets the position of a time value within an interval. This is useful for doing animation cycles lasting a certain number of seconds, such as rotating a shape in a 5-second cycle. This method may be called any number of times each frame.

Parameters

Return Value

A value in the range [0, 1), where closer to 0 means "timeInMs" lies closer to the start, and closer to 1 means closer to the end of the interval. If an initial time wasn't set, returns 0. (Type: number)

Example

The following code sets an angle of rotation, in degrees, such that an object rotated with the angle does a 360-degree turn in 5 seconds (5000 milliseconds). The variable time is assumed to be a time value in milliseconds, such as the parameter of a requestAnimationFrame() callback method.

var angle = 360 * export var getTimePosition(timer, time, 5000);

(static) H3DU.is3DContext(context)

Returns whether the given object is a 3D rendering context.

Parameters

Return Value

Return value. (Type: boolean)

(static) H3DU.loadFileFromUrl(url, [responseType])

Loads a file from a URL asynchronously, using XMLHttpRequest.

Parameters

Return Value

A promise that resolves when the data file is loaded successfully (the result will be an object with two properties: "url", the URL of the file, and "data", the file's text or data), as given below, and is rejected when an error occurs (the result may be an object with one property: "url", the URL of the file). If the promise resolves, the parameter's "data" property will be:

(Type: Promise)

(static) H3DU.loadGltfFromUrl(url)

Loads a 3D scene stored in glTF format, together with the buffers and shaders it uses.

This method is considered a supplementary method to the Public Domain HTML 3D Library and is not considered part of that library.

To use this class, you must include the script "extras/gltf.js"; the class is not included in the "h3du_min.js" file which makes up the HTML 3D Library. Example:

<script type="text/javascript" src="extras/gltf.js"></script>

Parameters

Return Value

A promise; when it resolves, the result will be an object that implements the following methods:

If an error occurs in loading the glTF data or any of the buffers and shaders it uses, the promise will be rejected. (Type: Promise.<Object>)

(static) H3DU.loadStlFromUrl(url)

Loads a .STL file asynchronously.

This method is considered a supplementary method to the Public Domain HTML 3D Library and is not considered part of that library.

To use this method, you must include the script "extras/stl.js"; the class is not included in the "h3du_min.js" file which makes up the HTML 3D Library. Example:

<script type="text/javascript" src="extras/stl.js"></script>

Parameters

Return Value

A promise that resolves when the .STL file is loaded successfully (the result will be an H3DU.MeshBuffer object), and is rejected when an error occurs when loading the .STL file. (Type: Promise.<H3DU.MeshBuffer>)

(static) H3DU.newFrames(timer, timeInMs)

Returns the number of frame-length intervals that occurred since the last known time, where a frame's length is 1/60 of a second. This method should be called only once each frame.

Parameters

Return Value

The number of frame-length intervals relative to the last known time held in the parameter "timer". The number can include fractional frames. If an initial time or last known time wasn't set, returns 0. (Type: number)

(static) H3DU.renderLoop(func)

This method will call a function once before returning, and queue requests to call that function once per frame, using window.requestAnimationFrame or a "polyfill" method.

Parameters

Return Value

This function doesn't return a value. (Type: void)

(static) H3DU.toGLColor(r, g, b, [a])

Creates a 4-element array representing a color. Each element can range from 0 to 1 and specifies the red, green, blue or alpha component, respectively. This method also converts HTML and CSS colors to 4-element RGB colors. The following lists the kinds of colors accepted:

For more information, see the "Color Strings" tutorial.

Parameters

Return Value

The color as a 4-element array; if the color is invalid, returns [0,0,0,0], or transparent black. Numbers less than 0 are clamped to 0, and numbers greater than 1 are clamped to 1. (Type: Array.<number>)

Back to documentation index.