Renderer - Documentation

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()

Update the webgl contexts line and point settings.

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