Provides a shader-based immediate mode rendering API.
The GraphicsDevice object can be used to create the following objects:
The data contained on the vertex and index buffer objects can either be set at once when creating the buffer with the data option, or it can be supplied later by the application by using setData or map / unmap to get an iterator object that can be used to write data into the buffer.
Shader objects can contain multiple rendering techniques which can be queried per name. In order to render anything, one Technique must be set on the GraphicsDevice. Shader parameters can either be set from a TechniqueParameters or changed directly on the technique after setting it on the device. The former is recommended for updating multiple values at the same time. When the technique parameter is an array with many values a TechniqueParameterBuffer object can be used to set the whole array at once, it can be updated in a similar way vertex and index buffers can be updated.
To use Texture objects they have to be set as shader parameters. Pixel data on a Texture object can be set either by setting the data option at creation time, by loading from an image file or by rendering to the Texture through a RenderTarget object. Multiple image files can be archived and loaded as a ”.tar” file, this removes the cost of multiple connections to the server.
Once a Technique is set, a geometry must also be set on the device, it can be done either by using vertex and index buffers, or by using beginDraw / endDraw for inline geometry. Multiple VertexBuffers can be set at the same time on the device as soon as they are referenced by different semantics. When using vertex and index buffers, a separate call to one of the draw methods is required in order to tell the device how much data must be used from those buffers.
The GraphicsDevice is implemented using WebGL for canvas versions and OpenGL for plugin versions. The majority of behavior is identical between the two implementations however there are a number of differences:
See the WebGL specification http://www.khronos.org/registry/webgl/specs/latest for full details.
Summary
Signals the beginning of a new render frame.
This can fail if the host window is not visible, e.g. the browser is minimized or the window is not on the active tab.
Syntax
if (graphicsDevice.beginFrame())
{
drawScene();
graphicsDevice.endFrame();
}
Summary
Signals the end of the current render frame. The backbuffer will be presented to the screen.
Syntax
if (graphicsDevice.beginFrame())
{
drawScene();
graphicsDevice.endFrame();
}
Summary
Sets the viewport that maps the device coordinates to window coordinates.
It defaults to the size of the host window.
See also setScissor.
It should only be called between beginFrame/endFrame.
Syntax
graphicsDevice.setViewport(x, y, width, height);
//example usage:
graphicsDevice.setViewport(100, 100, (graphicsDevice.width - 100), (graphicsDevice.height - 100));
Summary
Sets the scissor rectangle that limits the active rendering buffer rectangle.
Typically the arguments are the same as those for setViewport.
It defaults to the size of the host window.
It should only be called between beginFrame/endFrame.
Syntax
graphicsDevice.setScissor(x, y, width, height);
//example usage:
graphicsDevice.setScissor(100, 100, (graphicsDevice.width - 100), (graphicsDevice.height - 100));
Summary
Clears the active rendering buffers.
It should only be called between beginFrame/endFrame.
Syntax
var clearColor = [0.0, 0.0, 0.0, 1.0];
var clearDepth = 1.0;
var clearStencil = 0;
graphicsDevice.clear(clearColor, clearDepth, clearStencil);
Summary
Creates a Texture object. If a src parameter is given then the Texture returned is not valid until the onload function is called. Returns immediately.
Syntax
// For a procedural texture (without a src parameter)
var proceduralTextureParameters = {
name: "checkers",
width: 4,
height: 4,
depth: 1,
format: graphicsDevice.PIXELFORMAT_L8,
mipmaps: false,
cubemap: false,
renderable: false,
dynamic: false,
data: [ 0, 255, 0, 255,
255, 0, 255, 0,
0, 255, 0, 255,
255, 0, 255, 0]
};
var proceduralTexture = graphicsDevice.createTexture(proceduralTextureParameters);
// To load a texture from a URL
var loadingTexture;
var textureParameters = {
src: "textures/crate.jpg",
mipmaps: true,
onload: function onLoadedTextureFn(texture, status)
{
if (texture)
{
sharedTechniqueParameters.diffuse = texture;
assetsToLoad -= 1;
}
else
{
alert("Texture missing!");
}
loadedTexture = loadingTexture;
}
};
loadingTexture = graphicsDevice.createTexture(textureParameters);
status
A JavaScript number. The HTTP response status code. For example, status 200 is OK. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10 for more information.
data
Data with which to initialize the Texture. This property can be a Typed Array in which case the data will be set in an optimized way if the size and type of the array are appropriate for the PixelFormat of the Texture (as described in the WebGL standards).
Returns a Texture object or null if parameters are missing or incorrect. For more information on the parameters see the Texture object. Supported formats: DDS, JPG, PNG and TGA.
Note
You should manage the response status codes correctly. See the RequestHandler for handling connection and service busy issues. Alternatively, use the TextureManager to load textures.
Summary
Creates a Shader object.
Syntax
var shaderLoaded = function shaderLoadedFn(shaderDefinitionString)
{
if (shaderDefinitionString)
{
var shaderDefinition = JSON.parse(shaderDefinitionString);
var shader = graphicsDevice.createShader(shaderDefinition);
if (shader)
{
technique = shader.getTechnique("textured2D");
}
}
};
TurbulenzEngine.request("shaders/generic2D.cgfx.json", shaderLoaded);
Returns a Shader object.
Summary
Sets the active Technique.
It should only be called between beginFrame/endFrame.
Syntax
var technique = shader.getTechnique("phong");
graphicsDevice.setTechnique(technique);
Summary
Creates a TechniqueParameterBuffer object.
Syntax
var skinBones = graphicsDevice.createTechniqueParameterBuffer({
numFloats : (numBones * 12),
dynamic : true
});
Returns a TechniqueParameterBuffer object.
Summary
Creates a TechniqueParameters object.
Syntax
var TechniqueParameters = graphicsDevice.createTechniqueParameters({
diffuse: texture,
color: mathDevice.v4Build(1.0, 1.0, 1.0, 1.0)
});
Returns a TechniqueParameters object.
Summary
Sets the TechniqueParameters properties to the active Technique.
It should only be called between beginFrame/endFrame.
Syntax
graphicsDevice.setTechniqueParameters(globalTechniqueParameters);
for (var n = 0; n < numNodes; n += 1)
{
graphicsDevice.setTechniqueParameters(sharedTechniqueParameters, instanceTechniqueParameters);
drawNode(nodes[n]);
}
This method can receive multiple TechniqueParameters objects, all the properties from each TechniqueParameters will be set to the Technique in turn.
Summary
Creates a Semantics object.
Syntax
var semantics = graphicsDevice.createSemantics(semanticsValues);
var baseSemantics = graphicsDevice.createSemantics([graphicsDevice.SEMANTIC_POSITION,
graphicsDevice.SEMANTIC_NORMAL,
graphicsDevice.SEMANTIC_COLOR]);
Returns a Semantics object.
Summary
Creates a VertexBuffer object.
Syntax
var vertexbufferParameters = {
numVertices: 4,
attributes: [graphicsDevice.VERTEXFORMAT_FLOAT2,
graphicsDevice.VERTEXFORMAT_SHORT2],
dynamic: false,
'transient': false,
data:[100.0, 200.0, 3, 1000,
200.0, 200.0, 4, 2000,
100.0, 100.0, 5, 3000,
200.0, 100.0, 6, 4000]
};
var vertexbuffer = graphicsDevice.createVertexBuffer(vertexbufferParameters);
data
A JavaScript array containing the data to put into the buffer. The size of the data array is the number of vertices multiplied by the total size of the attributes types (i.e. the stride). This data is treated in the same way as arguments to setData.
Returns a VertexBuffer object.
Note
The number of attributes per VertexBuffer is limited to a maximum of 8.
Summary
Sets a VertexBuffer object to represent specific semantics.
It should only be called between beginFrame/endFrame.
Syntax
var semantics = graphicsDevice.createSemantics([graphicsDevice.SEMANTIC_POSITION,
graphicsDevice.SEMANTIC_NORMAL,
graphicsDevice.SEMANTIC_COLOR]);
var vertexBuffer = graphicsDevice.createVertexBuffer(vertexbufferParameters);
var offset = 0;
graphicsDevice.setStream(vertexBuffer, semantics, offset);
Summary
Creates an IndexBuffer object.
Syntax
var indexBufferParameters = {
numIndices: 4,
format: graphicsDevice.INDEXFORMAT_USHORT,
dynamic: false,
'transient': false,
data: [ 0, 1, 2, 3 ]
};
var indexBuffer = graphicsDevice.createIndexBuffer(indexBufferParameters);
numIndices
The capacity of the IndexBuffer expressed as index count.
format
The format of indices.
dynamic
Set to true if you intend to update the values of the indices at runtime.
data
If given, the IndexBuffer is initialized with this data. See setData for details of this data, in particular using the correct Typed Array objects for this property results in optimal data transfer.
Returns an IndexBuffer object.
See also isSupported for format support.
Summary
Sets the active IndexBuffer.
It should only be called between beginFrame/endFrame.
Syntax
graphicsDevice.setIndexBuffer(indexbuffer);
Summary
Creates a DrawParameters object.
Syntax
var drawParameters = graphicsDevice.createDrawParameters();
Summary
Draws a geometry defined by indices from the active IndexBuffer and the active VertexBuffer streams using the active Technique.
It should only be called between beginFrame/endFrame.
Syntax
graphicsDevice.drawIndexed(primitive, numIndices, first);
Summary
Draws a geometry defined only by the active VertexBuffer streams using the active Technique.
It should only be called between beginFrame/endFrame.
Syntax
graphicsDevice.draw(primitive, numVertices, first);
Summary
Draws an array of DrawParameters.
It should only be called between beginFrame/endFrame.
Syntax
graphicsDevice.drawArray(drawParametersArray, globalTechniqueParametersArray, sortMode);
The mode to sort the array by using the DrawParameters.sortKey.
- -1 for sorting by least
- 1 for sorting by greatest
- 0 for no sorting to preserve order or for presorted arrays.
Summary
Starts dispatching of inline geometry.
It should only be called between beginFrame/endFrame.
Syntax
var semantics = graphicsDevice.createSemantics([graphicsDevice.SEMANTIC_POSITION,
graphicsDevice.SEMANTIC_TEXCOORD0])
var vertexFormats = [graphicsDevice.VERTEXFORMAT_FLOAT2, graphicsDevice.VERTEXFORMAT_FLOAT2];
var writer = graphicsDevice.beginDraw(primitive, numVertices, vertexFormats, semantics);
if (writer)
{
writer(-1.0, 1.0, 0.0, 0.0);
writer(-1.0 + width, 1.0, 1.0, 0.0);
writer(-1.0 + width, 1.0 + height, 1.0, 1.0);
writer(-1.0, 1.0 + height, 0.0, 1.0);
graphicsDevice.endDraw(writer);
}
Summary
Ends dispatching of inline geometry.
It should only be called between beginFrame/endFrame.
Syntax
var vertexFormats = [graphicsDevice.VERTEXFORMAT_FLOAT2, graphicsDevice.VERTEXFORMAT_FLOAT2];
var writer = graphicsDevice.beginDraw(primitive, numVertices, vertexFormats, semantics);
if (writer)
{
writer(-1.0, 1.0, 0.0, 0.0);
writer(-1.0 + width, 1.0, 1.0, 0.0);
writer(-1.0 + width, 1.0 + height, 1.0, 1.0);
writer(-1.0, 1.0 + height, 0.0, 1.0);
graphicsDevice.endDraw(writer);
}
Summary
Creates a RenderBuffer object.
Syntax
var depthBuffer = graphicsDevice.createRenderBuffer({
width: 256,
height: 256,
format: graphicsDevice.PIXELFORMAT_D24S8
});
Returns a RenderBuffer object. This can be null if the pass in arguments are not supported by the graphics card.
Summary
Creates a RenderTarget object.
Syntax
var baseRenderTarget = graphicsDevice.createRenderTarget({
colorTexture0: albedoTexture,
colorTexture1: specularTexture,
colorTexture2: normalTexture,
colorTexture3: depthTexture,
depthBuffer: depthBuffer
});
Returns a RenderTarget object.
Summary
Start rendering to a RenderTarget object.
This sets the viewport and scissor to be the size of the RenderTarget.
It should only be called between beginFrame/endFrame.
Syntax
if (graphicsDevice.beginRenderTarget(renderTarget))
{
drawOpaque();
graphicsDevice.endRenderTarget();
}
Summary
Ends rendering to a RenderTarget object.
This resets the viewport and scissor to be the values they were when beginRenderTarget was called.
It should only be called between beginFrame/endFrame.
Syntax
if (graphicsDevice.beginRenderTarget(baseRenderTarget))
{
drawOpaque();
graphicsDevice.endRenderTarget();
}
Summary
Creates an OcclusionQuery object.
Syntax
var occlusionQuery = graphicsDevice.createOcclusionQuery();
Returns an OcclusionQuery object.
Summary
Starts an occlusion query.
It should only be called between beginFrame/endFrame.
Syntax
if (graphicsDevice.beginOcclusionQuery(occlusionQuery))
{
graphicsDevice.draw(primitive, numVertices);
graphicsDevice.endOcclusionQuery();
}
Summary
Ends an occlusion query.
It should only be called between beginFrame/endFrame.
Syntax
if (graphicsDevice.beginOcclusionQuery(occlusionQuery))
{
graphicsDevice.draw(primitive, numVertices);
graphicsDevice.endOcclusionQuery();
}
// Latency of at least one frame
if (occlusionQuery.pixelCount > 2000)
{
}
Summary
Loads a collection of Texture objects from an archive. Returns immediately.
Syntax
var archiveParameters = {
src: 'textures/level0.tar',
mipmaps: true,
ontextureload: function ontextureloadFn(texture)
{
loadedTexture(texture.name);
},
onload: function onloadFn(success, status)
{
if (success)
{
loadedArchive();
}
}
};
graphicsDevice.loadTexturesArchive(archiveParameters);
Returns true if the request can be made or false if parameters are incorrect.
Note
You should manage the response status codes correctly. See the RequestHandler for handling connection and service busy issues. Alternatively, use the TextureManager to load textures.
Summary
Returns an array with the pixel values of the current frontbuffer. Each pixel will be represented by 4 values in the range [0..255] in RGBA order.
Syntax
var compress = false;
var width = graphicsDevice.width;
var height = graphicsDevice.height;
var canvas = document.getElementById("screenshot");
var ctx = canvas.getContext("2d");
var imageData = ctx.createImageData(width, height);
var data = imageData.data;
var pixels = graphicsDevice.getScreenshot(compress);
if (!pixels)
{
alert("Failed to get screenshot.");
return;
}
var srcRowStride = (width * 4);
var srcRow = ((height - 1) * srcRowStride);
var desItem = 0;
for (var y = 0; y < height; y += 1)
{
var srcItem = srcRow;
for (var x = 0; x < width; x += 1)
{
data[desItem + 0] = pixels[srcItem + 0];
data[desItem + 1] = pixels[srcItem + 1];
data[desItem + 2] = pixels[srcItem + 2];
data[desItem + 3] = 255;
srcItem += 4;
desItem += 4;
}
srcRow -= srcRowStride;
}
ctx.putImageData(imageData, 0, 0);
Note
Any arguments passed must be passed in order (compress, x, y, width, height); and to pass any argument, all arguments higher in the order must be passed as well.
Summary
Used to see if features are supported.
See also maxSupported.
Syntax
var feature = "OCCLUSION_QUERIES";
if (graphicsDevice.isSupported(feature))
{
// ...
}
Returns a boolean.
Summary
Used to see maximim values for features.
See also isSupported.
Syntax
var feature = "RENDERTARGET_COLOR_TEXTURES";
if (graphicsDevice.maxSupported(feature) === 1)
{
// DeferredRending not supported
}
Returns an integer.
Summary
Creates a Video playback object.
Syntax
graphicsDevice.createVideo({
src: videoURL,
looping: true,
onload: function (v)
{
if (v)
{
video = v;
v.play();
}
else
{
window.alert("Failed to load video!");
}
}
});
Returns a Video object.
Summary
Calls flush on the underlying context. See the OpenGL specification for details.
Syntax
graphicsDevice.flush();
Summary
Calls finish on the underlying context, which waits until all issued render commands are completed. See the OpenGL specification for details.
As this function will block it is not recommended for use in final code.
One use case is to measure remaining cost of rendering.
Syntax
graphicsDevice.finish();
Summary
The name of the company responsible for the OpenGL implementation used by the graphics device.
Syntax
var vendorString = graphicsDevice.vendor;
if (-1 !== vendorString.indexOf('Intel'))
{
usingIntelVideoCard();
}
Note
Read Only
Summary
The name of the OpenGL renderer used by the graphics device. This name is typically specific to a particular configuration of a hardware platform.
Syntax
var rendererString = graphicsDevice.renderer;
if (-1 !== rendererString.indexOf('9400'))
{
using9400Model();
}
Note
Read Only
Summary
The OpenGL version supported by the renderer used by the graphics device. May contain additional driver specific information separated by spaces.
Syntax
var openglVersionString = graphicsDevice.rendererVersion;
if ('3' === openglVersionString[0])
{
opengl3supported();
}
Note
Read Only
Summary
The OpenGL Shading Language version supported by the renderer used by the graphics device.
Syntax
var shadingLanguageVersionString = graphicsDevice.shadingLanguageVersion;
if (!shadingLanguageVersionString)
{
glslNotSupported();
}
Note
Read Only
Summary
The amount of dedicated video memory in megabytes available to the renderer used by the graphics device. This may return 0 if its unknown.
Syntax
var videoRam = graphicsDevice.videoRam;
if (videoRam > 0 && videoRam < 256)
{
notEnoughVideoRam();
}
Note
Read Only
Summary
List of the OpenGL extensions supported by the renderer used by the graphics device.
Syntax
var extensionsString = graphicsDevice.extensions;
Note
Read Only
Summary
Dimensions of the main rendering buffer.
Syntax
var aspectRatio = (graphicsDevice.width / graphicsDevice.height);
if (aspectRatio !== camera.aspectRatio)
{
camera.aspectRatio = aspectRatio;
camera.updateProjectionMatrix();
}
Note
Read Only
Summary
The current (main screen) desktop resolution. The screen used to determine this may or may not be the screen used for fullscreen mode, and should therefore only be used as a rough indicator of fullscreen resolution. The application should check the resolution using width and height after transitioning into fullscreen mode to get the precise fullscreen dimensions.
Syntax
// Rough guide to resolution
var useLowResAssets = false;
if (graphicsDevice.desktopWidth < 1024 && graphicsDevice.desktopHeight < 768)
{
useLowResAssets = true;
}
Note
Read Only
Summary
Frames rendered during the last second.
Syntax
var fps = graphicsDevice.fps;
if (lastFps !== fps)
{
lastFps = fps;
updateFpsUI(fps);
}
Note
Read Only
Summary
Controls and informs about fullscreen rendering. Defaults to false.
Syntax
var fullscreen = graphicsDevice.fullscreen;
if (!fullscreen)
{
graphicsDevice.fullscreen = true;
updateRenderBuffers();
}
Summary
Valid semantic values, required when setting vertex streams.
|
|
|
Syntax
var semantics = graphicsDevice.createSemantics([graphicsDevice.SEMANTIC_POSITION,
graphicsDevice.SEMANTIC_TEXCOORD]);
Note
Read Only
Summary
Valid primitive values, required when drawing primitives.
|
|
|
Syntax
var primitive = graphicsDevice.PRIMITIVE_TRIANGLES;
d.draw(primitive, numVertices);
Note
Read Only
Summary
Valid vertex format values, required when creating vertex buffers.
|
|
|
Syntax
var vertexbufferParameters = {
numVertices: 4,
attributes: [graphicsDevice.VERTEXFORMAT_FLOAT2,
graphicsDevice.VERTEXFORMAT_SHORT2],
dynamic: false
};
var vertexbuffer = graphicsDevice.createVertexBuffer(vertexbufferParameters);
Note
Read Only
Summary
Valid pixel format values, required when creating textures.
|
|
Syntax
var textureParameters = {
name : "checkers",
width : 4,
height : 4,
format : graphicsDevice.PIXELFORMAT_L8,
mipmaps : false,
dynamic : false,
data : [ 0, 255, 0, 255,
255, 0, 255, 0,
0, 255, 0, 255,
255, 0, 255, 0]
};
var texture = graphicsDevice.createTexture(textureParameters);
Note
Read Only
Summary
Valid index format values, required when creating index buffers.
- INDEXFORMAT_UBYTE
- INDEXFORMAT_USHORT
- INDEXFORMAT_UINT
Syntax
var indexbufferParameters = {
numIndices: 4,
format: graphicsDevice.INDEXFORMAT_USHORT
dynamic: false,
data: [ 0, 1, 2, 3 ]
};
var indexbuffer = graphicsDevice.createIndexBuffer(indexbufferParameters);
Note
Read Only