VTS Browser Renderer API

VTS Browser Renderer API

This module provides methods for rendering.

Renderer State Methods

Method	Returns	Description
clear(<ClearOptions> options)	this	Clears the renderer.
createState(<StateOptions> options)	RenderState	Creates a renderer state.
setState(<RenderState> state)	this	Sets a renderer state.

Clear Options

Option	Type	Default	Description
clearColor	bool	true	Sets whether the screen color buffer will be cleared.
clearDepth	bool	true	Sets whether the screen depth buffer will be cleared.
color	RGBA	[255,255,255,255]	Sets the color to which the color buffer will be cleared.
depth	Number	1.0	Sets he depth to which the depth buffer will be cleared.

State Options

Option	Type	Default	Description
blend	bool	false	Sets whether the rendered primitives will be blended. Read more about the blending operation below.
stencil	bool	false	Sets whether the rendered primitives will write and test the stencil buffer. Read more about the stencil operation below.
zoffset	Number	0	Sets whether the rendered primitives will be have a depth offset.
zwrite	bool	true	Sets whether the rendered primitives will write to the depth buffer.
ztest	bool	true	Sets whether the rendered primitives will test the depth buffer.
zequal	bool	true	Sets the depth buffer test. If true the test is "less or equal". If false the test is "less only".
culling	bool	true	Sets whether the rendered polygons will be face culled.

Todo: definition of blend and stencil operation.

Resource Creation Methods

Method	Returns	Description
createTexture(<CreateTextureOptions> options)	GpuTexture	Creates a texture.
createMesh(<CreateMeshOptions> options)	GpuMesh	Creates a mesh.
createShader(<CreateShaderOptions> options)	GpuShader	Creates a shader.

Create Texture Options

Option	Type	Default	Description
source	Image/Uint8Array	null	Sets data source from which the texture will be created
width	Number	null	Width of the texture. Used only when the texture is generated from a Uint8Array
height	Number	null	Width of the texture. Used only when the texture is generated from a Uint8Array
filter	String	"linear"	Texture filtering used for rendering. Posible values are: "nearest", "linear", "trilinear".
repeat	Bool	false	Set whether the texture will be repeated.

Create Mesh Options

Option	Type	Default	Description
vertices	Float32Array	null	Sets polygon vertices.
vertexSize	Number	3	Sets size of the vertex vector.
uvs	Float32Array	null	Sets polygon uv vertices.
uvSize	Number	2	Sets the size of the uv vector.

Create Shader Options

Option	Type	Default	Description
vertexShader	string	null	Sets vertex shader code.
fragmentShader	string	null	Sets fragment shader code.

Resource Removal Methods

Method	Returns	Description
removeResource(object resource)	null	Destroys resources. Resource data will be removed from memory. Supported resources are: Texture, Mesh, Shader.

Render Jobs Methods

Method	Returns	Description
addJob(<AddJobOptions> options)	this	Adds a render job.
clearJobs()	this	Clears render jobs.

Add Job Options

TODO:

Rendering Methods

Method	Returns	Description
drawMesh(<DrawMeshOptions> options)	this	Draws a Mesh.
drawImage(<DrawImageOptions> options)	this	Draws a 2D Image in screen space.
drawBillboard(<DrawBillboardOptions> options)	this	Draws a 3D Billboard.
drawLinestring(<DrawLinestringOptions> options)	this	Draws a Linestring in screen space.
drawJobs(<DrawJobsOptions> options)	this	Draws Jobs.

Draw Mesh Options

Option	Type	Default	Description
mesh	GPUMesh	null	Sets a mesh to be rendered.
texture	GPUTexture	null	Sets a texture.
shader	GPUShader/String	"textured"	Sets a shader. There is a set of named built in shaders. Supported built in shaders are: "textured", "shaded", "textured-and-shaded", "hit".
shaderAttributes	Object	null	All object properties and values will be applied to the shader as attributes. The attributes have the following form: "attribute" : "nameInShader". Supported attributes are "vertex", "uv", "normal".
shaderVariables	Object	null	All object properties and values will be applied to the shader as variables. The variables have the following form: "name" : ["variableType", value]. Supported variable types are: "floatArray", "float", "mat4", "vec2", "vec3", "vec4", "sampler".

Build in Shaders

name	Description
textured	Textured mesh without lighting. Supported variables are: "uMV" - model view matrix(mat4).
shaded	Untextured mesh with lighting only.
textured-and-shaded	Textured mesh with lighting.
hit	Special shader used for meshes which can be detected by the getHitCoords method.

Supported variables for build in shaders are:

name	type	Description
uMV	mat4	The model view matrix.
uProj	mat4	The projection matrix.
uFogDensity	float	The fog factor. Zero value means no fog.
uMaterial	mat4	The matrix defining material with the following form. [aR, aG, aB, 0, dR, dG, dB, 0, sR, sG, sB, 0, shininess, 0, 0, 0]. Where aR, aG, aB is ambient color, dR, dG, dB is diffuse color, sR, sG, sB is specular color. Range of values is from 0 to 255.

Draw Image Options

Option	Type	Default	Description
rect	Rect	null	Sets image area. Rect is defined as [left, top, width, height] in screen pixels.
texture	GPUTexture	null	Sets the texture.
texrureRect	Rect	null	[unimplemented] Sets texture area. Rect is defined as [left, top, width, height] in texture pixels. If this option is not defined the whole texture area will be rendered.
depth	Number	0	Sets depth position of the image.
depthOffset	DepthOffset	null	Sets depth buffer tolerance.
depthTest	false	null	Sets whether the depth buffer will be tested.
writeDepth	Bool	false	Sets whether depth will be written to the depth buffer.
blend	Bool	false	Sets whether the billboard will be blended with background.
useState	Bool	false	Sets whether the current state will be used for rendering. If state is used then options like "depthTest", "writeDepth", "blend" will be determined by the render state itself. Use of render state can speed up rendering of primitives which share the same render state.

Draw Billboard Options

Option	Type	Default	Description
mvp	Matrix	null	Sets the Model-View-Projection matrix.
texture	GPUTexture	null	Sets the texture.
texrureRect	Rect	null	[unsupported] Sets texture area. Rect is defined as [left, top, width, height] in texture pixels. If this option is not defined the whole texture area will be rendered.
depthOffset	DepthOffset	null	Sets depth buffer tolerance.
depthTest	false	null	Sets whether the depth buffer will be tested.
writeDepth	Bool	false	Sets whether the depth will be written to the depth buffer.
blend	Bool	false	Sets whether the billboard will be blended with background.
useState	Bool	false	Sets whether the current state will be used for rendering. If state is used then options like "depthTest", "writeDepth", "blend" will be determined by the render state itself. Use of render state can speed up rendering of primitives which share same render state.

Draw Line String Options

Option	Type	Default	Description
points	Array of Point2D	null	Array of line points where point is defined as [left, top].
color	RGBA	[255,255,255,255]	Color of the line.
size	Number	null	Width of the line in pixels.
depthOffset	DepthOffset	null	Sets depth buffer tolerance.
depthTest	false	null	Sets whether the depth buffer will be tested
writeDepth	Bool	false	Sets whether the depth will be written to the depth buffer.
blend	Bool	false	Sets whether the line will be blended with background.
useState	Bool	false	Sets whether the current state will be used for rendering. If state is used then options like "depthTest", "writeDepth", "blend" will be determined by the render state itself. Use of render state can speed up rendering of primitives which share same render state.

Canvas Methods

Method	Returns	Description
getCanvasCoords(<Coords> coords, <Matrix> mvp)	Coords	Returns the position of a 3D point in screen coordinates (pixels). Position of the 3D point has to be relative to the camera.
getCanvasSize()	[width, height]	Returns the size of the screen in pixels.

Definition of Coords

The coords is an array of the following values [Number x,Number y,Number z].

Definition of Matrix

The 4x4 row major matrix (array of 16 numbers).

Definition of DepthOffset

The array of 3 numbers representing [globalFactor, distanceFactor, tiltFactor]. Default value is [0,0,0]. When all three number are zeros then resulting depth is not affected. Negative values means that feature will be closer to camera. Positive values move feature farther from the camera.