SurfaceBuilder

Back to documentation index.

### new SurfaceBuilder()

An evaluator of surface evaluator objects for generating vertex attributes for a surface.

For more information, see the Parametric Curves and Parametric Surfaces tutorial.

Methods

• attribute
  Sets the parametric surface used to generate vertex attribute values.
• clearVertices
  Clears the arrays of attribute values (such as positions and normals) and vertex indices generated so far.
• constantAttribute
  Sets a value for an attribute semantic that will be the same for all future vertices generated by the “evalSurface” method.
• constantColor
  Sets a value for a color attribute that will be the same for all future vertices generated by the “evalSurface” method.
• evalSurface
  Generates the vertex attributes of the parametric surfaces.
• position
  Sets the parametric surface used to generate vertex positions.
• positionNormal
  Sets the parametric surface used to generate vertex positions and normals.
• positionNormalTexCoord
  Sets the parametric surface used to generate vertex positions and normals, and sets a surface evaluator that generates texture coordinates in the interval [0, 1] along the U and V axes of the surface.
• positionTexCoord
  Sets the parametric surface used to generate vertex positions, and sets a surface evaluator that generates texture coordinates in the interval [0, 1] along the U and V axes of the surface.
• surfaceToBuffer
  Convenience method for creating a mesh buffer from a parametric surface.
• texCoord
  Sets the parametric surface used to generate texture coordinates.
• toMeshBuffer
  Generates a mesh buffer containing the vertex attributes generated so far.

### SurfaceBuilder#attribute(surface, semantic, [semanticIndex], [size])

Sets the parametric surface used to generate vertex attribute values.

Parameters

• surface (Type: Object)
  A surface evaluator object that describes the parametric surface used to generate attribute values. U and V coordinates for the given surface correspond to U and V coordinates, respectively, for the surface used to generate vertex positions.

• semantic (Type: number

  string) An attribute semantic, such as Semantic.POSITION, “POSITION”, or “TEXCOORD_0”. Throws an error if this value is a string and the string is invalid.

• semanticIndex (Type: number) (optional)
  The set index of the attribute for the given semantic. 0 is the first index of the attribute, 1 is the second, and so on. This is ignored if “name” is a string. If null, undefined, or omitted, the default is 0.
• size (Type: number) (optional)
  The number of elements in each position and normal. For example, if the attribute is 3-dimensional, this parameter is 3. If null, undefined, or omitted, the default is 3. Throws an error if this value is 0 or less.

Return Value

This object. (Type: SurfaceBuilder)

Examples

The following example sets the surface function for texture coordinates to a linear evaluator. Thus, coordinates passed to the evalSurface method will be interpolated as direct texture coordinates.

surface.attribute({"evaluate":function(u,v) {
"use strict"; return [u,v] }},Semantic.TEXCOORD);

### SurfaceBuilder#clearVertices()

Clears the arrays of attribute values (such as positions and normals) and vertex indices generated so far. The attributes themselves will remain.

Return Value

This object. (Type: SurfaceBuilder)

### SurfaceBuilder#constantAttribute(constantValue, semantic, [semanticIndex])

Sets a value for an attribute semantic that will be the same for all future vertices generated by the “evalSurface” method.

Parameters

• constantValue (Type: Object

  number) A constant value for the attribute semantic.

• semantic (Type: number

  string) An attribute semantic, such as Semantic.POSITION, “POSITION”, or “TEXCOORD_0”. Throws an error if this value is a string and the string is invalid.

• semanticIndex (Type: number) (optional)
  The set index of the attribute for the given semantic. 0 is the first index of the attribute, 1 is the second, and so on. This is ignored if “name” is a string. If null, undefined, or omitted, the default is 0.

Return Value

This object. (Type: SurfaceBuilder)

Examples

This example sets the color to use for future vertices to be generated for the surface.

// Set color to red
surface.constantAttribute([1,0,0],"COLOR");

### SurfaceBuilder#constantColor(color, [semanticIndex])

Sets a value for a color attribute that will be the same for all future vertices generated by the “evalSurface” method.

Parameters

• color (Type: Array.<number>

  number

  string) A color vector or string identifying the constant color value. The alpha channel of the resulting color will be ignored.

• semanticIndex (Type: number) (optional)
  The set index of the attribute for the given semantic. 0 is the first index of the attribute, 1 is the second, and so on. If null, undefined, or omitted, the default is 0.

Return Value

This object. (Type: SurfaceBuilder)

Examples

This example sets the color to use for future vertices to be generated for the surface.

// Set color to red
surface.constantColor("red");

### SurfaceBuilder#evalSurface([mode], [un], [vn], [u1], [u2], [v1], [v2])

Generates the vertex attributes of the parametric surfaces.

Parameters

• mode (Type: number) (optional)
  If this value is MeshBuffer.TRIANGLES, or is null, undefined, or omitted, generates a series of triangles defining the surface. If this value is MeshBuffer.LINES, generates a series of lines defining the surface. If this value is MeshBuffer.POINTS, generates a series of points along the surface. For any other value, this method has no effect.
• un (Type: number) (optional)
  Number of subdivisions along the U axis. Default is 24. If 0, this method has no effect. Throws an error if this value is less than 0.
• vn (Type: number) (optional)
  Number of subdivisions along the V axis. Default is 24. If 0, this method has no effect. Throws an error if this value is less than 0.
• u1 (Type: number) (optional)
  Starting U coordinate of the surface to evaluate. Default is the starting U coordinate given by the surface evaluator object, or 0 if not given.
• u2 (Type: number) (optional)
  Ending U coordinate of the surface to evaluate. Default is the ending U coordinate given by the surface evaluator object, or 1 if not given.
• v1 (Type: number) (optional)
  Starting V coordinate of the surface to evaluate. Default is the starting V coordinate given by the surface evaluator object, or 0 if not given.
• v2 (Type: number) (optional)
  Ending V coordinate of the surface to evaluate. Default is the ending V coordinate given by the surface evaluator object, or 1 if not given.

Return Value

This object. (Type: SurfaceBuilder)

### SurfaceBuilder#position(surface, [size])

Sets the parametric surface used to generate vertex positions.

Parameters

• surface (Type: Object)
  A surface evaluator object that describes the parametric surface used to generate position values.
• size (Type: number) (optional)
  The number of elements in each position value. For example, if the attribute is 3-dimensional, this parameter is 3. If null, undefined, or omitted, the default is 3. Throws an error if this value is 0 or less.

Return Value

This object. (Type: SurfaceBuilder)

### SurfaceBuilder#positionNormal(surface, [size])

Sets the parametric surface used to generate vertex positions and normals.

Parameters

• surface (Type: Object)
  A surface evaluator object that describes the parametric surface used to generate positions.
• size (Type: number) (optional)
  The number of elements in each position and normal. For example, if the attribute is 3-dimensional, this parameter is 3. If null, undefined, or omitted, the default is 3. Throws an error if this value is 0 or less.

Return Value

This object. (Type: SurfaceBuilder)

### SurfaceBuilder#positionNormalTexCoord(surface, [size])

Sets the parametric surface used to generate vertex positions and normals, and sets a surface evaluator that generates texture coordinates in the interval [0, 1] along the U and V axes of the surface.

Parameters

• surface (Type: Object

  null) A surface evaluator object that describes the parametric surface used to generate positions. U and V texture coordinates, which will each be in the interval [0, 1] by this method, correspond to U and V coordinates, respectively, for the given surface.

• size (Type: number) (optional)
  The number of elements in each position and normal. For example, if the attribute is 3-dimensional, this parameter is 3. If null, undefined, or omitted, the default is 3. The texture coordinates will be 2-dimensional.

Return Value

This object. (Type: SurfaceBuilder)

### SurfaceBuilder#positionTexCoord(surface, [size])

Sets the parametric surface used to generate vertex positions, and sets a surface evaluator that generates texture coordinates in the interval [0, 1] along the U and V axes of the surface.

Parameters

• surface (Type: Object

  null) A surface evaluator object that describes the parametric surface used to generate positions. U and V texture coordinates, which will each be in the interval [0, 1] by this method, correspond to U and V coordinates, respectively, for the given surface.

• size (Type: number) (optional)
  The number of elements in each position. For example, if the attribute is 3-dimensional, this parameter is 3. If null, undefined, or omitted, the default is 3. The texture coordinates will be 2-dimensional. Throws an error if this value is 0 or less.

Return Value

This object. (Type: SurfaceBuilder)

### (static) SurfaceBuilder.surfaceToBuffer(surface, [mode], [un], [vn], [u1], [u2], [v1], [v2])

Convenience method for creating a mesh buffer from a parametric surface. The mesh buffer will contain positions, vertex normals, and texture coordinates that cover the given surface.

Parameters

• surface (Type: Object)
  A surface evaluator object that describes the parametric surface used to generate positions. U and V texture coordinates, which will each be in the interval [0, 1] by this method, correspond to U and V coordinates, respectively, for the given surface.
• mode (Type: number) (optional)
  If this value is MeshBuffer.TRIANGLES, or is null, undefined, or omitted, generates a series of triangles defining the surface. If this value is MeshBuffer.LINES, generates a series of lines defining the surface. If this value is MeshBuffer.POINTS, generates a series of points along the surface. For any other value, this method has no effect.
• un (Type: number) (optional)
  Number of subdivisions along the U axis. Default is 24.
• vn (Type: number) (optional)
  Number of subdivisions along the V axis. Default is 24.
• u1 (Type: number) (optional)
  Starting U coordinate of the surface to evaluate. Default is the starting U coordinate given by the surface evaluator object, or 0 if not given.
• u2 (Type: number) (optional)
  Ending U coordinate of the surface to evaluate. Default is the ending U coordinate given by the surface evaluator object, or 1 if not given.
• v1 (Type: number) (optional)
  Starting V coordinate of the surface to evaluate. Default is the starting V coordinate given by the surface evaluator object, or 0 if not given.
• v2 (Type: number) (optional)
  Ending V coordinate of the surface to evaluate. Default is the ending V coordinate given by the surface evaluator object, or 1 if not given.

Return Value

The generated mesh buffer. (Type: MeshBuffer)

### SurfaceBuilder#texCoord(surface, [size])

Sets the parametric surface used to generate texture coordinates.

Parameters

• surface (Type: Object)
  A surface evaluator object that describes the parametric surface used to generate texture coordinates. U and V coordinates for the given surface correspond to U and V coordinates, respectively, for the surface used to generate vertex positions.
• size (Type: number) (optional)
  The number of elements in each value of the attribute. For example, if the attribute is 3-dimensional, this parameter is 3. If null, undefined, or omitted, the default is 2.

Return Value

This object. (Type: SurfaceBuilder)

### SurfaceBuilder#toMeshBuffer()

Generates a mesh buffer containing the vertex attributes generated so far. The mesh buffer’s primitive type will equal the last type passed to the “mode” parameter in the SurfaceBuilder.surfaceEval method.

Return Value

The generated mesh buffer. (Type: MeshBuffer)

Back to documentation index.