adcirc-render

A WebGL renderer and supporting tools for the visualization of ADCIRC data.

API Reference

The adcirc-render library consists of three main types. First, a renderer which knows how to communicate with the browser in order to draw things on the screen. Second, geometries, which describe what to draw. And third, shaders, which describe how to draw.

Renderer

# adcirc.gl_renderer(selection)

Creates a new WebGL renderer. The selection parameter must be an HTML canvas element selected using d3.select(). Returns the new renderer object if WebGL is available, otherwise returns undefined.

# gl_renderer.add_view(view)

Adds the view to the renderer. The view is rendered each time the renderer updates. The renderer updates the projection matrix of the view's active shader in response to user interaction.

# gl_renderer.clear_color([specifier])

Gets or sets the background color of the rendering area. If getting, the color is returned as a d3.rgb(). The color can be set by passing in a color specifier, parsing as defined by d3.rgb().

# gl_renderer.gl_context()

Returns the WebGL rendering context.

# gl_renderer.remove_view(view)

Removes the view from the renderer. The view will no longer be rendered when the renderer updates.

# gl_renderer.render()

Requests that the renderer redraw all views. Note that this is a deferred render, and the actual rendering will happen when the next animation frame is available.

# gl_renderer.zoom_to(item)

Translates and zooms the renderer view to the bounding box of item, which must provide a bounding_box() method.

Geometry

Geometries are used by adcirc-render to bridge the gap between how meshes are represented from the perspective of an ADCIRC modeler and how WebGL needs to organize and view data in order for it to be rendered properly.

# adcirc.geometry(gl, mesh)

Creates a new geometry. gl is a WebGL rendering context, mesh is a mesh.

Upon creation of the geometry, the buffers needed for rendering will be created in the WebGL context, but only the vertex position and vertex normal buffers will be filled. The vertex positions (i.e. x- and y-coordinates) will be retrieved from the mesh, and the vertex normals will be generated to allow for single-pass wireframe rendering.

Geometries are rendered using drawArrays, so vertices are duplicated within the buffers (i.e. no indexed rendering). Geometry provides the elemental_value and nodal_value methods which perform the correct transfer of ADCIRC data (which is indexed) to the (non-indexed) buffers in the WebGL context.

The following buffers are used to render ADCIRC data:

• position_buffer - The x- and y- coordinates for each vertex (node)
• value_buffer - The 'z-value' for each vertex. Not necessarily a vertical elevation, rather this is the data field we are interested in displaying (e.g. elevation, depth, velocity, residual, etc.). This value is used by all shaders to color vertices.
• normal_buffer - This is a collection of ones and zeros that are generated by the geometry, and should never be changed. They provide the data necessary for the shader to perform single-pass wireframe rendering.

# geometry.bind_buffer(attribute)

Binds the requested attribute, if it is available, and returns the bound buffer. Returns undefined if the attribute is not available.

The returned buffer is an object containing the following:

• buffer
• size
• type
• normalized
• stride
• offset

See vertexAttribPointer documentation for description of each field. The buffer field is the WebGL array buffer.

# geometry.bounding_box()

Returns the bounding box of the mesh that the geometry is responsible for rendering.

# geometry.draw_arrays()

Performs rendering of the entire mesh. Simply calls drawArrays with the appropriate parameters.

Note to self: this is where I should implement rendering of portions of meshes. WebGL drawArrays accepts a start index and count, so this function could take a list of [start, count, start, count, ...] to allow for drawing subsets

# geometry.elemental_value(value)

If the mesh contains the elemental value value, fills the vertex value buffer with the data associated with that value.

# geometry.nodal_value(value)

If the mesh contains the nodal value value, fills the vertex value buffer with the data associated with that value.

Shaders

Shaders are used by adcirc-render to describe how a geometry should be rendered. A number of methods are provided by every shader, while specific methods are provided by individual shaders based on functionality.

# shader.attribute(attribute)

If it exists, returns the specified shader attribute.

# shader.attributes([callback])

If callback is not specified, returns a list of attributes available to the shader. If callback is specified, it is called for each attribute available in the shader, passing the attribute location and the attribute name as arguments.

Every shader will have the following attributes:

• 'vertex_normal'
• 'vertex_position'
• 'vertex_value'

# shader.set_projection(matrix)

Sets the projection matrix used to transform vertices. This should only every need to be called by the renderer in order to provide interactivity.

# shader.uniform(uniform)

If it exists, returns the specified shader uniform.

# shader.uniforms()

Returns a list of all uniforms available to the shader.

All shaders will have the 'projection_matrix' uniform, and all shaders that provide wireframe rendering will have the following uniforms:

• 'wire_alpha'
• 'wire_color'
• 'wire_width'

# shader.use()

Instructs the rendering context to use the shader program for any subsequent rendering calls.

# shader.wire_alpha([alpha])

Only available to shaders that provide wireframe rendering

Returns the wire alpha, a value in the range [0, 1], if alpha is not provided. Sets the alpha value and returns the shader if alpha is provided.

# shader.wire_color([color])

Only available to shaders that provide wireframe rendering

Returns the wire color if color is not provided. Sets the wire color and returns the shader if color is provided.

# shader.wire_width([*width])

Only available to shaders that provide wireframe rendering

Return the wire width if width is not provided. Sets the wire width and returns the shader if width is provided.

Basic Shader

A basic shader renders a mesh a single color. Supports wireframe.

# adcirc.basic_shader(gl)

Creates a basic shader using the WebGL context gl.

# basic_shader.face_color([color])

Gets or sets the uniform color used to render the mesh.

Gradient Shader

A gradient shader renders a mesh using any number of colors, linearly interpolating between the colors using the values from the value_buffer. Supports wireframe.

# adcirc.gradient_shader(gl, num_colors[, min, max])

Creates a gradient shader with num_colors colors using the WebGL context gl. Gradient shaders must have at least two colors. By default, color stops are evenly spaced between 0 and 1 with colors from d3.schemeCategory20. To interpolate between stops other than 0 and 1, optionally pass in min and max.

# gradient_shader.gradient_colors([colors])

Gets or sets the gradient colors. The colors list must contain d3.rgb() colors, or objects that have r, g, and b properties. The colors list must have the correct number of colors, as defined when creating the gradient shader instance.

# gradient_shader.gradient_stops([stops])

Gets or sets the gradient stops. The stops list must contain the correct number of stops, as defined when creating the gradient shader instance.

View

# view.elemental_value(value)

Instructs the geometry associated with this view to use the data associated with the elemental value value.

# view.nodal_value(value)

Instructs the geometry associated with this view to use the data associated with the nodal value value.

# view.render()

Renders the view.

# view.shader()

Returns the shader currently being used by the view.