Renderer

Renderer

The renderer handles displaying of graphics data to a render context.
It accepts an object containing the settings for the renderer.

Constructor

new Renderer(sumerianRunner, options)

Parameters:
Name Type Description
sumerianRunner sumerianRunner

The SumerianRunner that owns this Renderer.

options Object

Renderer settings.

Properties
Name Type Attributes Default Description
alpha boolean <optional>
false

Enables the possibility to render non-opaque pixels.

premultipliedAlpha boolean <optional>
true

Whether the colors are premultiplied with the alpha channel.

antialias boolean <optional>
true

Enables antialiasing.

stencil boolean <optional>
false

Enables the stencil buffer.

preserveDrawingBuffer boolean <optional>
false
useDevicePixelRatio boolean <optional>
false

Take into account the device pixel ratio (for retina screens
etc).

canvas canvas <optional>

If not supplied, Renderer will create a new canvas.

onError function <optional>

Called with message when error occurs.

Members

(readonly) clearColor :Vector4

Current clear color of the scene. Use .setClearColor() to set it.

context :WebGLRenderingContext

currentHeight :number

currentWidth :number

(readonly) devicePixelRatio :number

downScale :number

Used to scale down/up the pixels in the canvas. If you set downScale=2, you will get half the number of pixels in
X and Y. Default is 1.

rendererRecord :RendererRecord

shaderPrecision :string

Can be one of:

  • lowp
  • mediump
  • highp

If the shader doesn't specify a precision, a string declaring this precision will be added.

viewportHeight :number

viewportWidth :number

viewportX :number

viewportY :number

Methods

_calculateBatches(instancedRenderList, occlusionGraph, lights) → {Number}

Sorts instanced renderables into batches that share render state

Parameters:
Name Type Description
instancedRenderList Map
occlusionGraph Octree
lights Array.<Light>

_checkDualTransparency(material, meshData)

Checks a material for dualTransparency and if enabled, draws the MeshData buffers again with inverse cullFace.

Parameters:
Name Type Description
material Material
meshData MeshData

_deallocateAllSamplers()

Deallocates a texture Sampler object.

_deallocateMeshData(meshData)

Deallocates a meshdata with the Renderer's webgl context.

Parameters:
Name Type Description
meshData MeshData

_deallocateRenderTarget(renderTarget)

Deallocates a render target with the Renderer's webgl context.

Parameters:
Name Type Description
renderTarget RenderTarget

_deallocateSampler(sampler)

Deallocates a texture Sampler object.

Parameters:
Name Type Description
sampler Sampler

_deallocateShader(shader)

Deallocates a shader.

Parameters:
Name Type Description
shader Shader

_deallocateTexture(texture)

Deallocates a texture with the Renderer's webgl context.

Parameters:
Name Type Description
texture Texture

_doRender(renderList, instancedRenderList, occlusionGraph, views, lights)

Renders a list of rendererables

Parameters:
Name Type Description
renderList Array.<Entity>

A list of "renderables". Eg Entities with the right components or objects with mesh data, material and transform.

instancedRenderList Array.<Entity>

A list of "renderables" that'll be instanced. Eg Entities with the right components or objects with mesh data, material and transform.

occlusionGraph Octree
views Array.<View> | View

A list of Views to render into; a single View will render as normal

lights Array.<Light>

Lights used in the rendering.

_drawBuffers(meshData)

Draw the buffers of a MeshData using the specified index-mode.

Parameters:
Name Type Description
meshData MeshData

_drawBuffersInstanced(meshData, instanceCount)

Draw the buffers of a MeshData using the specified index-mode and instancing.

Parameters:
Name Type Description
meshData MeshData
instanceCount number

_override(mat1, mat2, store)

Fills the store parameter with the combined properties of mat1 and mat2.

Parameters:
Name Type Description
mat1 Material
mat2 Material
store Material

bindBuffer(buffer, target)

Binds a buffer to the webgl context.

Parameters:
Name Type Description
buffer WebGLBuffer
target string

for example 'ArrayBuffer'.

bindData(bufferData)

Binds the given BufferData's buffer, or creates a buffer and bind it if none exist.

Parameters:
Name Type Description
bufferData BufferData

BufferData to bind.

bindTexture(context, texture, unit, record, sampler) → {WebGLSampler}

Binds a texture to webgl.

Parameters:
Name Type Description
context WebGLRenderingContext
texture Texture
unit number

The index for the textureRecord.

record Object
sampler Sampler

bindVertexAttribute(attribIndex, attribute)

Binds vertex attributes to the webgl context.

Parameters:
Name Type Description
attribIndex number
attribute Object

See MeshData.createAttribute for definition.

callShaderProcessors(material, renderInfo)

Call the shader processors of the given material and update material cache.

Parameters:
Name Type Description
material Material
renderInfo RenderInfo

checkRescale(texture, image, width, height, maxSize, index)

Updates a texture in webgl with the Texture objects settings.

Parameters:
Name Type Description
texture Texture
image Image

Can be an Image, TypedArray or an array of Images (for cubemaps).

width number

The new image width.

height number

The new image height.

maxSize number
index number

checkResize(cameraopt, skipSetSize)

Checks if this.domElement.offsetWidth or Height / this.downScale is unequal to this.domElement.width or height.
If that is the case it will call this.setSize.
Also checks if the camera aspect changed and updates it by calling camera.setFrustumPerspective().

Parameters:
Name Type Attributes Description
camera Camera <optional>

optional camera argument.

skipSetSize Boolean

clear(color, depth, stencil)

Clears the webgl context with the specified options.

Parameters:
Name Type Description
color boolean
depth boolean
stencil boolean

clearShaderCache()

Remove all shaders from cache.

combineTextures(textureA, channelsA, textureB, channelsB, textureC, channelsC, textureD, channelsD) → {Texture}

Combines texture data together into an RT.

Parameters:
Name Type Description
textureA Texture
channelsA number
textureB Texture
channelsB number
textureC Texture
channelsC number
textureD Texture
channelsD number

configureRenderInfo(renderInfo, materialIndex, material, orMaterial, originalData, flatOrWire) → {Material}

Decides which MeshData and Material to set on the renderInfo parameter object, also returns the specified material.

Parameters:
Name Type Description
renderInfo RenderInfo
materialIndex number
material Material
orMaterial Material
originalData MeshData
flatOrWire string

Can be one of 'flat' or 'wire'

drawArraysVBO(indexModes, indexLengths)

Draws a vertex buffer object (VBO) using drawArrays.

Parameters:
Name Type Description
indexModes Array.<string>

Array of index-modes.

indexLengths Array.<number>

Array of index-counts per index-mode.

drawArraysVBOInstanced(indexModes, indexLengths, instanceCount)

Draws a vertex buffer object (VBO) using drawArrays.

Parameters:
Name Type Description
indexModes Array.<string>

Array of index-modes.

indexLengths Array.<number>

Array of index-counts per index-mode.

instanceCount number

drawElementsVBO(indices, indexModes, indexLengths)

Draws a vertex buffer object (VBO) using drawElements.

Parameters:
Name Type Description
indices BufferData

The index-buffer.

indexModes Array.<string>

Array of index-modes.

indexLengths Array.<number>

Array of index-counts per index-mode.

drawElementsVBOInstanced(indices, indexModes, indexLengths, instanceCount)

Draws a vertex buffer object (VBO) using drawElements.

Parameters:
Name Type Description
indices BufferData

The index-buffer.

indexModes Array.<string>

Array of index-modes.

indexLengths Array.<number>

Array of index-counts per index-mode.

instanceCount number

establishContext()

Fetches a working webgl context element and sets it to the Renderer.

findOrCacheMaterialShader(material, renderInfo)

Finds shader of the material in the cache, or add it to the cache if not added yet. Then update the uniforms to the cached shader.

Parameters:
Name Type Description
material Material
renderInfo RenderInfo

finish()

calls finish on the webgl context.

flush()

Flushes the webgl context.

getSamplerObject(sampler)

Retrieves ,also creates if necessary, one of the global samplers since we can use one sampler with many textures

Parameters:
Name Type Description
sampler Object

describes what kind of sampler we need

initRenderTarget(renderTarget, frameBuffers, msFrameBuffers)

Initalizes a render target creating a framebuffer if none provided, creating a texture if a depthbuffer or colorbuffer needs read access
and creating a renderbuffer if we have colorbuffer without readaccess or depthbuffer without read access
*

Parameters:
Name Type Description
renderTarget RenderTarget
frameBuffers Array.<Array.<WebGLFramebuffer>>

Can be null if needs to be created for given RT (if RT is first of MRT or if single RT)

msFrameBuffers Array.<Array.<WebGLFramebuffer>>

Can be null if needs to be created for given RT (if RT is first of MRT or if single RT)

loadCompressedTexture(context, target, texture, imageData)

Loads a compressed texture into webgl and optionally generates mipmaps.

Parameters:
Name Type Description
context WebGLRenderingContext
target number

For example context.TEXTURE_2D.

texture Texture
imageData Uint8Array | ArrayBufferView

The image data object.

onDebugError(err, functionName, args)

Outputs the webgl errors with the respective erroring function name and arguments using console.error.

Parameters:
Name Type Description
err Object
functionName string
args Array

pick(clientX, clientY, pickingStore, camera)

Determine what entity ID is at a specific pixel of the camera.

Parameters:
Name Type Description
clientX number

pixel position X to pick at.

clientY number

pixel position Y to pick at.

pickingStore Object

An object with variables 'id' and 'depth' to be populated by the function.

camera Camera

Same camera that was used with Renderer.renderToPick.

precompileShaders(renderList, lights)

Precompiles shaders of the supplied "renderables".

Parameters:
Name Type Description
renderList Array

An array of all the "renderables".

lights Array.<Light>

preloadMaterials(renderList) → {Promise}

Preloads textures that come with the materials on the supplied "renderables".

Parameters:
Name Type Description
renderList Array

An array of all the "renderables".

readPixels(x, y, width, height, store)

Read pixels from current framebuffer to a typed array (ArrayBufferView).

Parameters:
Name Type Description
x number

x offset of rectangle to read from.

y number

y offset of rectangle to read from.

width number

width of rectangle to read from.

height number

height of rectangle to read from.

store ArrayBufferView

ArrayBufferView to store data in (Uint8Array).

readTexturePixels(texture, x, y, width, height, store)

Read pixels from a texture to a typed array (ArrayBufferView).

Parameters:
Name Type Description
texture Texture

texture to read pixels from.

x number

x offset of rectangle to read from.

y number

y offset of rectangle to read from.

width number

width of rectangle to read from.

height number

height of rectangle to read from.

store ArrayBufferView

ArrayBufferView to store data in (Uint8Array).

render(renderList, occlusionGraph, viewer, lights, renderTargetopt, clearopt, overrideMaterialsopt, instancedRenderList, faceIdxopt)

Renders a "renderable" or a list of renderables. Handles all setup and updates of materials/shaders and states.

Parameters:
Name Type Attributes Default Description
renderList Array.<Entity>

A list of "renderables". Eg Entities with the right components or objects with mesh data, material and transform.

occlusionGraph Octree
viewer Viewer | View

Main viewpoint for rendering.

lights Array.<Light>

Lights used in the rendering.

renderTarget Array.<RenderTarget> <optional>
null

Optional array of rendertarget to use as multiple targets (or single) for rendering, or null to render to the screen.

clear boolean | Object <optional>
false

true/false to clear or not clear all types, or an object in the form {color:true/false, depth:true/false, stencil:true/false}

overrideMaterials Array.<Material> <optional>

Optional list of materials to override the renderList materials.

instancedRenderList Array.<Entity>

A list of "renderables" that'll be instanced. Eg Entities with the right components or objects with mesh data, material and transform.

faceIdx number <optional>
0

Cube Render Target's face index. (0...6).

renderMesh(renderInfo)

Renders a mesh from a RenderInfo.

Parameters:
Name Type Description
renderInfo RenderInfo

renderMeshInstanced(renderInfo)

Renders a group of meshes from a RenderInfoInstanced.

Parameters:
Name Type Description
renderInfo RenderInfoInstanced

renderMeshMaterial(materialIndex, materials, flatOrWire, originalData, renderInfo)

Render a material with the given parameters.

Parameters:
Name Type Description
materialIndex number
materials Array.<Material>
flatOrWire boolean
originalData MeshData
renderInfo RenderInfo

renderToPick(renderList, camera, clearopt, skipUpdateBuffer, doScissor, clientX, clientY, customPickingMaterial, skipOverride)

Render entities to be used with the Renderer.pick.

Parameters:
Name Type Attributes Default Description
renderList Array.<Entity>

A list of "renderables". Eg Entities with the right components or objects with mesh data, material and transform.

camera Camera

Main camera for rendering to pick.

clear boolean | Object <optional>
false

true/false to clear or not clear all types, or an object in the form {color:true/false, depth:true/false, stencil:true/false}

skipUpdateBuffer boolean
doScissor boolean
clientX number

scissor position X.

clientY number

scissor position Y.

customPickingMaterial Material

Custom picking material.

skipOverride boolean

setClearColor(r, g, b, a)

Set the background color of the 3D view. All colors are defined in the range 0.0 - 1.0.

Parameters:
Name Type Description
r number

Red value.

g number

Green value.

b number

Blue value.

a number

Alpha value.

setMultipleRenderTarget(renderTarget)

Binds the supplied render target's FBO to the webgl context.
Creates FBO and RBO for the render target if not set already.

Parameters:
Name Type Description
renderTarget Array.<RenderTarget>

setRenderTarget(renderTarget, cubeIdx)

Binds the supplied render target's FBO to the webgl context.
Creates FBO and RBO for the render target if not set already.

Parameters:
Name Type Description
renderTarget RenderTarget
cubeIdx number

// Used for cubemap RTs

setSize(width, height, fullWidthopt, fullHeightopt)

Sets this.domElement.width and height using the parameters.
Then it calls this.setViewport(0, 0, width, height);
Finally it resets the hardwarePicking.pickingTarget.

Parameters:
Name Type Attributes Description
width number

Aspect ratio corrected width.

height number

Aspect ratio corrected height.

fullWidth number <optional>

Full viewport width.

fullHeight number <optional>

Full viewport height.

setupDebugging(options)

Enables debug mode on the webgl context for easier development.

Parameters:
Name Type Description
options Object
Properties
Name Type Description
validate boolean

setupFrameBuffer(framebuffer, renderTarget, textureTarget, renderTargetIndex)

Setup a Frame Buffer Object with the supplied render target.

Parameters:
Name Type Description
framebuffer WebGLFramebuffer
renderTarget RenderTarget
textureTarget number

For instance context.TEXTURE_2D.

renderTargetIndex number

used for MRT framebuffer

setupRenderBuffer(renderTarget, attachmentIndex)

Setup an Render Buffer Object with the supplied render target.

Parameters:
Name Type Description
renderTarget RenderTarget
attachmentIndex number

setViewport(xopt, yopt, widthopt, heightopt)

Sets this.viewportX and viewportY to the parameters or to 0.
Sets this.viewportWidth and viewportHeight to the parameters or to this.domElement.width and height.
Finally it calls this.context.viewport(x, y, w, h) with the resulting values.

Parameters:
Name Type Attributes Description
x number <optional>

optional x coordinate.

y number <optional>

optional y coordinate.

width number <optional>

optional width coordinate.

height number <optional>

optional height coordinate.

unbindTexture(context, texture, unit, record)

Unbinds a texture from webgl.

Parameters:
Name Type Description
context WebGLRenderingContext
texture Texture
unit number

The index for the textureRecord.

record Object

updateAttributeData(attributeData, offset)

Update the data buffer of an attribute at it's offset location.

Parameters:
Name Type Description
attributeData ArrayBuffer

New attribute data buffer.

offset number

The starting location offset to the attribute buffer.

updateBlending(material)

Update the blend settings on the webgl context.

Parameters:
Name Type Description
material Material

updateCulling(material)

Update the webgl contexts culling settings.

Parameters:
Name Type Description
material Material

updateDepthTest(material)

Update the webgl contexts depth test settings.

Parameters:
Name Type Description
material Material

updateLineAndPointSettings(material)

Update the webgl contexts line and point settings.

Parameters:
Name Type Description
material Material

updateOffset(material)

Updates the polygon offset settings on the webgl context.

Parameters:
Name Type Description
material Material

updateRenderTargetMipmap(renderTarget)

Updates the render targets mipmaps.

Parameters:
Name Type Description
renderTarget RenderTarget

updateShadows(partitioner, entities, lights)

Update the shadowHandler for the provided entities and lights.

Parameters:
Name Type Description
partitioner SimplePartitioner

The partitioner used to determine what gets to be shadowed.

entities Array.<Entity>

Array of all the entities to cast shadows.

lights Array.<Light>

Array of all the lights to cast shadows for.

updateTexture(context, texture, unit, record, sampler)

Updates a texture in webgl with the Texture objects settings.

Parameters:
Name Type Description
context WebGLRenderingContext
texture Texture
unit number
record Object
sampler SamplerObject

updateTextureParameters(texture, isImagePowerOfTwo)

Update the webgl contexts settings of a single texture, such as filtering and wrapping.

Parameters:
Name Type Description
texture Texture
isImagePowerOfTwo boolean

updateTextures(material)

Update the webgl contexts settings concerning textures.
updates the material textures if necessary.

Parameters:
Name Type Description
material Material

useDevicePixelRatio(useDevicePixelRatio)

Set the flag to determine whether to use devicePixelRatio or not

Parameters:
Name Type Description
useDevicePixelRatio Boolean