Provides a more efficient path for sprite rendering in Draw2D. Rendered with a call to draw2D.drawSprite.
Summary
Syntax
var sprite = Draw2DSprite.create({
texture : tex,
textureRectangle : [u1, v1, u2, v2],
width : w,
height : h,
color : [r, g, b, a],
x : x,
y : y,
rotation : rotation,
origin : [ox, oy],
scale : [sx, sy],
shear : [sx, sy]
});
Specifies the Texture to be used in rendering the sprite. This texture must be mipmapped and have power of 2 dimensions.
If unspecified (Or set to null/undefined), then a solid fill will be used when rendering the sprite instead.
Specify which region of the texture is to be used for this sprite.
Texture coordinates defined in pixels.
Default value is [0, 0, texture.width, texture.height]. The implicit solid fill texture used when none is specified has dimensions 1x1.
Specify the width of the sprite in pixels.
Default value is texture.width. * If texture is not specified then the width must be provided.
Specify the height of the sprite in pixels.
Default value is texture.height. * If texture is not specified then the height must be provided.
Specify the color of the sprite. Colors are given in normalized values in the range [0,1].
This color is multiplied with the texture to give the final appearance of the sprite before blending.
Default value is [1, 1, 1, 1].
Specify the x-coordinate in pixels for the sprite to be placed. The position is relative to the origin of the sprite.
Default value is 0.
Specify the y-coordinate in pixels for the sprite to be placed. The position is relative to the origin of the sprite.
Default value is 0.
Specify the rotation of the sprite in clockwise radians. Rotation is performed about the origin of the sprite.
This transformation occurs after scaling and shearing, but before translation to position.
Default value is 0.
Specify the local position for the origin of the sprite in pixels.
This is where all transformations, and where positioning of sprite is given relative to: if this is the actual center of the sprite then when rotating, rotation will be performed about the center and when positioning, we define the position where the center of the sprite will go on the screen.
Default value is [width / 2, height / 2].
Specify the scaling factors for the sprite.
This transformation occurs after shearing, but before rotation and translation.
Default value is [1, 1].
Specify the shearing factors for the sprite.
This transformation occurs before any other.
Default value is [0, 0].
A value of null will be returned if a texture is not supplied and the width/height of the sprite are unspecified.
The following are defined as properties of the sprite so as to be most efficient.
Any necessary side effects occur lazily upon drawing the sprite object.
Summary
The x-coordinate in pixels to place the origin of the sprite to the screen.
This value can be modified at any time including between draw calls of the same sprite object.
Syntax
var x = sprite.x;
sprite.x = 10;
Summary
The y-coordinate in pixels to place the origin of the sprite to the screen.
This value can be modified at any time including between draw calls of the same sprite object.
Syntax
var y = sprite.y;
sprite.y = 10;
Summary
The rotation of the sprite about its origin in clockwise radians.
This value can be modified at any time including between draw calls of the same sprite object.
Modification to the rotation has a minimal overhead upon drawing the sprite. In any case that the rotation is unchanged there is no overhead.
Syntax
var rotation = sprite.rotation;
sprite.rotation = Math.PI;
The following are defined as methods as it is not expected for them to be used continuously the same way that position and rotation is.
Any necessary side effects occur immediately so as not to add overhead to the draw calls.
Summary
Get the current color of the sprite.
Syntax
var color = sprite.getColor();
// or
sprite.getColor(color);
The return value is the array containing the color of the sprite. Modifications to this array will not change the color of the sprite which must be done using the setColor method.
Summary
Set the current color of the sprite.
Syntax
sprite.setColor([r, g, b, a]);
Summary
Get the current Texture assigned to the sprite.
Syntax
var texture = sprite.getTexture();
if (texture)
{
...
}
Summary
Set the Texture assigned to the sprite.
Syntax
sprite.setTexture(texture);
Summary
Get current texture-rectangle of sprite.
Syntax
var textureRectangle = sprite.getTextureRectangle();
// or
sprite.getTextureRectangle(textureRectangle);
The return value is the array containing texture-rectangle. Modifications to this array will not change the texture-rectangle of the sprite which must be done using the setTextureRectangle method.
Summary
Set the texture-rectangle of the sprite.
Syntax
sprite.setTextureRectangle([u1, v1, u2, v2]);
Summary
Get the current scaling of the sprite.
Syntax
var scale = sprite.getScale();
// or
sprite.getScale(scale);
The return value is the array containing the scale factors of the sprite. Modifications to this array will not change the scaling of the sprite which must be done using the setScale method.
Summary
Set the current scaling of the sprite.
Syntax
sprite.setScale([scaleX, scaleY]);
Summary
Get the current shearing of the sprite.
Syntax
var shear = sprite.getShear();
// or
sprite.getShear(shear);
The return value is the array containing the shearing factors of the sprite. Modifications to this array will not change the shearing of the sprite which must be done using the setShear method.
Summary
Set the current shearing of the sprite.
Syntax
sprite.setShear([shearX, shearY]);
Summary
Get the current width of the sprite.
Syntax
var width = sprite.getWidth();
Summary
Set the current width of the sprite.
Syntax
sprite.setWidth(width);
Summary
Get the current height of the sprite.
Syntax
var height = sprite.getHeight();
Summary
Set the current height of the sprite.
Syntax
sprite.setHeight(height);
Summary
Get the current locally defined origin of the sprite in pixels.
Syntax
var origin = sprite.getOrigin();
// or
sprite.getOrigin(origin);
The return value is the array containing the origin of the sprite. Modifications to this array will not change the origin of the sprite which must be done using the setOrigin method.
Summary
Set the origin of the sprite.
Syntax
sprite.setOrigin([originX, originY]);
Provides an efficient sprite based 2D rendering API based on WebGL.
Coordinate values are based on pixels relative to the top-left corner of the GraphicsDevice window.
Draw2D operates in 2 distinct states; a drawing, and non-drawing state.
Drawing state is entered whenever the first call to begin is made to permit rendering of objects and exited when the last call to end in the stack is made.
Draw calls may only be made in the drawing state, whilst actions like configuring the draw2D object, setting or copying a render target may only be made in the non-drawing state.
A third implicit state occurs when the draw2D object is destroyed and may no longer be used.
Summary
Syntax
var draw2D = Draw2D.create({
graphicsDevice : graphicsDevice,
blendModes : {
"customBlendMode" : technique,
...
},
initialGpuMemory : 1024,
maxGpuMemory : (1024 * 1024)
});
An optional dictionary providing compatible Technique objects for custom rendering techniques and blending behaviors.
To best explain what constitutes a compatible Technique, the built in blend modes are based upon the following CGFX shaders:
float4 clipSpace;
sampler2D texture = sampler_state
{
MinFilter = LinearMipMapNearest;
MagFilter = Linear;
WrapS = ClampToEdge;
WrapT = ClampToEdge;
};
void vp_draw2D(in float2 InPosition : POSITION,
in float4 InColor : COLOR,
in float2 InTexCoord : TEXCOORD0,
out float4 OutPosition : POSITION,
out float4 OutColor : COLOR,
out float2 OutTexCoord : TEXCOORD0)
{
OutPosition = float4(InPosition * clipSpace.xy + clipSpace.zw, 0.0, 1.0);
OutColor = InColor;
OutTexCoord = InTexCoord;
}
float4 fp_draw2D(float4 InColor : COLOR,
float2 InTexCoord : TEXCOORD0) : COLOR
{
return InColor * tex2D(texture, InTexCoord);
}
Any custom Technique must expose the clipSpace and texture parameters but may do what it likes in terms of the output values and blending functions on the technique.
Custom blend mode techniques are appended, and may replace those provided by Draw2D (opaque, alpha, additive)
The initial amount of memory in bytes allocated on the GPU for vertex and index buffers by draw2D.
This value is clamped to be in the range [140,2293760] and has default value of 140.
The maximum amount of memory in bytes that may be allocated on GPU for vertex and index buffers by draw2D.
This value is clamped to be greater or equal to the initialGpuMemory, and has no upper limit though a hard limit is placed at 2293760 internally.
The hard limit at 2293760 is a direct result of the amount of memory used per-vertex for drawing sprites and the choice of 16bit integers for index data.
Summary
Dictionary of supported scale modes for parameters of configure method.
Syntax
var mode0 = draw2D.scale.none; //mode0 === 'none'
var mode1 = draw2D.scale.scale; //mode1 === 'scale'
With scale mode ‘none’, the draw2D viewport will be mapped to the screen with no scaling performed. The viewport will be aligned to the top-left corner of the graphicsDevice window.
This is the default scale mode.
Note
Read Only
Summary
Dictionary of supported sort modes for parameters of begin method.
Syntax
var mode0 = draw2D.sort.immediate; //mode0 === 'immediate'
var mode1 = draw2D.sort.deferred; //mode1 === 'deferred'
var mode2 = draw2D.sort.texture; //mode2 === 'texture'
With sort mode ‘deferred’, each draw call made will be buffered with dispatching occurring only once the corresponding end or a nested begin call is made. Draw order will be preserved with draw calls batched into as long as possible chains to minimize state changes.
This is the default sort mode.
With sort mode ‘texture’, draw calls will be buffered like in deferred mode. But draw order will not be preserved with all draw calls using the same texture batched together. In this way we guarantee at most N state changes, where N is the number of textures used.
When only one texture is in use, this sort mode is equivalent to deferred.
The benefits of this sort mode, whilst preserving draw order can often be found by creating a sprite sheet so that the number of different textures used is minimal.
Note
Read Only
Summary
Dictionary of supported blend modes for parameters of begin method.
Syntax
var mode0 = draw2D.blend.opaque; //mode0 === 'opaque'
var mode1 = draw2D.blend.alpha; //mode1 === 'alpha'
var mode2 = draw2D.blend.additive; //mode2 === 'additive'
// auxiliary blend modes defined in construction of draw2D object.
..
var modeN = draw2D.blend.customBlendMode; //modeN === 'customBlendMode'
With blend mode ‘opaque’, sprites will be drawn with full alpha regardless of any alpha present in textures, or the sprite color.
This is the default blend mode.
With blend mode ‘additive’, sprites will be drawn respecting color and texture alpha values, but with color values added together when sprites overlap.
In this blend mode draw order makes no difference.
Note
Read Only
Summary
Performance data collected by Draw2D.
For applicable fields, values can be reset by calling resetPerformanceData.
Fields
The amount of memory in bytes this draw2D object has allocated on the GPU for vertex and index buffers. This will increase as you draw more sprites at any given time.
Draw2D will additionally allocate some additional bytes for such things as the default solid fill texture which are not included here.
This field is not reset by resetPerformanceData.
The minimum size of a rendered batch.
This value is equal to undefined when batchCount === 0.
The maximum size of a rendered batch.
This value is equal to undefined when batchCount === 0.
The average size of a rendered batch.
This value is equal to undefined when batchCount === 0.
Note
Read Only
Summary
Configure memory usage parameters, viewport and scale mode.
Syntax
var success = draw2D.configure({
scaleMode : 'scale',
viewportRectangle : [x1, y1, x2, y2]
});
If specified will define the new scale mode to use. Otherwise the scale mode will be unchanged from its current value.
If the scale mode defined is not present in the draw2D.scale dictionary then this method will fail and false will be returned.
If defining scale mode ‘scale’, then a viewport must currently be defined on the draw2D object, whether by this call or a previous one.
If specified will define the new viewport to use. Otherwise the viewport will be unchanged from its current value.
By default (and by setting explicitly to null/undefined in this call), there is no viewport for this draw2D object, and the entire graphicsDevice window will be used as an implicit viewport with top left corner at (0,0).
A viewport must be defined to use the ‘scale’ scale mode.
This function cannot be called whilst in a drawing state.
Summary
Destroy draw2D object, performing necessary deallocation of resources from GraphicsDevice.
Syntax
draw2D.destroy();
Once destroyed, you may no longer use the draw2D object.
Summary
Begin a new drawing state.
Syntax
var success = draw2D.begin(blendMode, sortMode);
The blend mode to use. If this is the first call to begin, and this value is unspecified then the default blend mode ‘opaque’ will be used. Otherwise when unspecified, the blend mode will be unchanged.
This method will fail with false if blend mode is specified, but is not defined in the draw2D.blend dictionary.
The sort mode to use. If this is the first call to begin, and this value is unspecified then the default sort mode ‘deferred’ will be used. Otherwise when unspecified, the sort mode will be unchanged.
This method will fail with false if sort mode is specified, but is not defined in the draw2D.sort dictionary.
These calls may as hinted be nested:
draw2D.begin('alpha');
// blendMode = 'alpha', sortMode = 'deferred' (default)
draw2D.begin('additive');
//blendMode = 'additive', sortMode = 'deferred' (unchanged)
draw2D.end();
// blendMode = 'alpha', sortMode = 'deferred' (both reverted to previous value at begin call)
draw2D.end();
Summary
End a drawing state.
Syntax
var success = draw2D.end();
This call may only occur during a drawing state, in any other case will fail with false.
Summary
Clear current draw target.
Syntax
var success = draw2D.clear([r, g, b, a]);
Specify the RGBA color with which to clear the current draw target.
Color is defined with normalized values in the range [0, 1].
Default value is [0, 0, 0, 1]
Summary
Get current viewport.
Syntax
var viewport = draw2D.getViewport();
// or
draw2D.getViewport(viewport);
The return value is the array containing the current viewport (if defined), or in the case that a viewport is not presently defined on the draw2D object the implicit viewport [0, 0, graphicsDevice.width, graphicsDevice.height].
Summary
Get current viewport in screen coordinates.
Syntax
var viewport = draw2D.getScreenSpaceViewport();
// or
draw2D.getScreenSpaceViewport(viewport);
The return value is the array containing the screen space viewport, with viewport defined as in getViewport.
Screen space is defined in pixels with (0,0) at the top-left corner of the graphicsDevice window.
Summary
Map screen space point into draw2D point.
Syntax
var point = draw2D.viewportMap(x, y);
// or
draw2D.viewportMap(x, y, point);
Returns the array containing mapped point. This point is not clamped to the viewport.
Screen space is defined in pixels with (0,0) at the top-left corner of the graphicsDevice window.
Summary
Map draw2D point into screen space point.
Syntax
var point = draw2D.viewportUnmap(x, y);
// or
draw2D.viewportUnmap(x, y, point);
Returns the array containing unmapped point. This point is not clamped to the graphicsDevice window.
Screen space is defined in pixels with (0,0) at the top-left corner of the graphicsDevice window.
Summary
Clamp draw2D point to the viewport.
Syntax
draw2D.viewportClamp(point);
This function will return the same point object after clamping.
Summary
Draw a sprite defined by a rotated rectangle with given texture to draw2D.
Syntax
draw2D.draw({
texture : texture,
sourceRectangle : [u1, v1, u2, v2],
destinationRectangle : [x1, y1, x2, y2],
rotation : rotation,
origin : [x, y],
color : [r, g, b, a]
});
Specifies the Texture to use in rendering the sprite. This texture must be mipmapped and have power of 2 dimensions.
If unspecified (Or explicitly set as null/undefined) then the sprite will be drawn with a solid fill.
Specifies the region of the texture corresponding to the sprite to be drawn.
This field is unused if no texture is specified. Otherwise its default value is [0, 0, texture.width, texture.height].
Specify the rotation of the sprite rectangle in clockwise radians.
This rotation will occur at the defined origin of the sprite.
Drawing a sprite with a non-zero rotation is inherently slower than drawing with 0 rotation.
By default this is equal to 0.
Specify the origin of the sprite relative to the top-left corner of the destination rectangle in pixels.
This is the center of rotation for the sprite with default value [width / 2, height / 2] for the width/height of destinationRectangle.
The color to draw sprite with. This is specified with normalized values in the range [0,1].
This color is multiplied with the sprite texture to determine final sprite appearance before blending.
By default this is equal to [1, 1, 1, 1].
For performance reasons, this method does not perform any checking of input parameters or draw2D object state but should be called only whilst in a drawing state.
Summary
Draw a Draw2DSprite object to draw2D.
Syntax
draw2D.drawSprite(sprite);
For performance reasons, this method does not perform any checking of input parameters or draw2D object state but should be called only whilst in a drawing state.
Summary
Draw buffered sprite information to draw2D with given Texture.
This is the most performant way of drawing sprites and is best used to pre-batch large amounts of static sprites.
Syntax
draw2D.drawRaw(texture, buffer, count, offset);
The Texture to draw sprites from buffer with. This texture must be mipmapped and have power of 2 dimensions.
If undefined or null then the sprites will be drawn with a solid fill.
Buffered sprite data to be drawn. This buffer must adhere to the following semantics:
[ x1, y1, x2, y2, x3, y3, x4, y4, cr, cg, cb, ca, u1, v1, u2, v2, ** repeated ** ]
Each sprite is represented by 16 values:
The vertices of the quad in draw2D coordinates defining the post-transformed sprite rectangle.
These are given in the order top-left, top-right, bottom-left, bottom-right.
The normalized texture coordinates for the region of the texture corresponding to the sprite.
Normalized texture coordinates can be found by dividing by texture width/height to get values in the range [0, 1].
Specify the number of sprites to be drawn.
By default this is equal to buffer.length / 16.
Specify a sprite offset at which to begin drawing. This is an offset in terms of the number of sprites represented to be skipped so that an offset of 1 means to started rendering at index 16 in the buffer.
By default this is equal to 0.
For performance reasons, this method does not perform any checking of input parameters or draw2D object state but should only be called in a drawing state.
Summary
Buffer the present state of a Draw2DSprite object for use with drawRaw method.
Syntax
draw2D.bufferSprite(buffer, sprite, index);
The buffer (An Array, or WebGL Float32Array) in which to place sprite data.
In the case of a WebGL Array, it should be large enough to fit the data.
For performance reasons, this method does not perform any checking of input parameters. It can be called at any time.
Summary
Create a new 2D RenderTarget object with a related Texture.
Syntax
// Dynamic render target matching viewport size.
// When the viewport changes size, so will this render target and its texture.
var renderTargetIndex = draw2D.createRenderTarget({
name : "texture name",
backBuffer : true
});
// Static render target with supplied fixed size.
var renderTargetIndex = draw2D.createRenderTarget({
name : "texture name",
backBuffer : true,
width : targetWidth,
height : targetHeight,
});
Specify the name for the related Texture object.
If unspecified the name “RenderTarget#N” with N replaced by the returned index will be used.
Specify the nature of this render target.
So that the texture related to this render target can be mipmapped, the texture is created with power of 2 dimensions.
If this render target is used (as is the usual case) as an intermediate rendering buffer before or during application of texture effects before being copied onto the screen, then we want to have pixel perfect rendering.
The only way to achieve that is to only render to the subset of the texture corresponding to the width/height of the render target.
This field - when true (default) - specifies that this is the case, and this property is respected when copying a render target to draw2d.
If false, then the entire texture will be used instead.
Specify a fixed height for this render target.
The width/height fields are only respected when both are supplied, and in this case the render target will be made static.
When one or both of the fields are unspecified, this render target is created as dynamic and will be dynamically reconstructed when the viewport changes size.
This render target, and its related texture are owned by the draw2D object, and will be destroyed when the draw2D object is destroyed.
Summary
Get the current RenderTarget object allocated for the given render target index.
Syntax
var renderTarget = draw2D.getRenderTarget(renderTargetIndex);
For static render targets, you may assume that the RenderTarget object allocated will not be changed at run-time and that this method will always return the same object.
However it is suggested that you do not rely on this assumption should you later decide to change the render target to be created as dynamic.
Summary
Get the current Texture object allocated for the given render target index.
Syntax
var texture = draw2D.getRenderTargetTexture(renderTargetIndex);
For static render targets, you may assume that the Texture object allocated will not be changed at run-time and that this method will always return the same object.
However it is suggested that you do not rely on this assumption should you later decide to change the render target to be created as dynamic.
This texture is equal to draw2D.getRenderTarget(renderTargetIndex).colorTexture0.
Summary
Set current render target of draw2D object to the graphicsDevice back-buffer.
Syntax
var success = draw2D.setBackBuffer();
This method may only be called outside of a drawing state and will fail returning false otherwise.
Summary
Set current render target of draw2D object to the given render target.
Syntax
var success = draw2D.setRenderTarget(renderTargetIndex);
This method may only be called outside of a drawing state and will fail returning false otherwise.
This method will also fail if the given index does not relate to any created render target.
Summary
Copy the given render target to fill the active draw target of draw2D.
Syntax
var success = draw2D.copyRenderTarget(renderTargetIndex);
This method is not a draw call, and may only occur outside of a drawing state.
This method is a fast copy, with no blending performed.
This method will return false if the given index does not relate to any created render target.
This method is sensitive to the render target nature; if the render target was created with backBuffer = true so that only the subset of the texture representing the render target dimension is used, then only that subset will be copied to draw2D.
Summary
Reset recorded performance data for this object.
Syntax
draw2D.resetPerformanceData();