Shaku

Back To Table of Content

Gfx

Gfx

Gfx is the graphics manager. Everything related to rendering and managing your game canvas goes here.

To access the Graphics manager you use Shaku.gfx.

Kind: global class

• Gfx
  • new Gfx()
  • .builtinEffects : Dictionary
  • .defaultTextureFilter : TextureFilterModes
  • .TextureWrapModes : TextureWrapModes
  • .whiteTexture : TextureAsset
  • .webglVersion ⇒ Number
  • .maxLineSegments ⇒ Number
  • .canvas ⇒ HTMLCanvasElement
  • .DrawBatch
  • .SpriteBatch
  • .SpriteBatch3D
  • .TextSpriteBatch
  • .ShapesBatch
  • .LinesBatch
  • .Effect
  • .SpritesEffect
  • .SpritesEffectNoVertexColor
  • .ShapesEffect
  • .Sprites3dEffect
  • .MsdfFontEffect
  • .Sprite
  • .SpritesGroup
  • .Matrix
  • .Vertex
  • .TextAlignments
  • .BlendModes
  • .TextureWrapModes
  • .TextureFilterModes
  • .drawCallsCount ⇒ Number
  • .quadsDrawCount ⇒ Number
  • .shapePolygonsDrawCount ⇒ Number
  • .setContextAttributes(flags)
  • .setCanvas(element)
  • .createCamera(withViewport) ⇒ Camera
  • .createCamera3D(withViewport) ⇒ Camera3D
  • .setCameraOrthographic(offset) ⇒ Camera
  • .maximizeCanvasSize([limitToParent], [allowOddNumbers])
  • .setRenderTarget(texture, [keepCamera])
  • .setResolution(width, height, updateCanvasStyle)
  • .resetCamera()
  • .applyCamera(camera)
  • .getRenderingRegion(includeOffset) ⇒ Rectangle
  • .getRenderingSize() ⇒ Vector2
  • .getCanvasSize() ⇒ Vector2
  • .buildText(fontTexture, text, [fontSize], color, [alignment], [offset], [marginFactor]) ⇒ SpritesGroup
  • .centerCanvas()
  • .inScreen(shape) ⇒ Boolean
  • .centerCamera(position, useCanvasSize)
  • .clear([color])
  • .clearDepth([value])

new Gfx()

Create the manager.

gfx.builtinEffects : Dictionary

A dictionary containing all built-in effect instances.

Kind: instance property of Gfx

gfx.defaultTextureFilter : TextureFilterModes

Default texture filter to use when no texture filter is set.

Kind: instance property of Gfx

gfx.TextureWrapModes : TextureWrapModes

Default wrap modes to use when no wrap mode is set.

Kind: instance property of Gfx

gfx.whiteTexture : TextureAsset

A 1x1 white texture.

Kind: instance property of Gfx

gfx.webglVersion ⇒ Number

Get the init WebGL version.

Kind: instance property of Gfx
Returns: Number - WebGL version number.

gfx.maxLineSegments ⇒ Number

Maximum number of vertices we allow when drawing lines.

Kind: instance property of Gfx
Returns: Number - max vertices per lines strip.

gfx.canvas ⇒ HTMLCanvasElement

Get the canvas element controlled by the gfx manager. If you didn’t provide your own canvas before initialization, you must add this canvas to your document after initializing Shaku.

Kind: instance property of Gfx
Returns: HTMLCanvasElement - Canvas we use for rendering.
Example

document.body.appendChild(Shaku.gfx.canvas);

gfx.DrawBatch

Get the draw batch base class.

Kind: instance property of Gfx
See: DrawBatch

gfx.SpriteBatch

Get the sprites batch class.

Kind: instance property of Gfx
See: SpriteBatch

gfx.SpriteBatch3D

Get the 3d sprites batch class.

Kind: instance property of Gfx
See: SpriteBatch3D

gfx.TextSpriteBatch

Get the text sprites batch class.

Kind: instance property of Gfx
See: TextSpriteBatch

gfx.ShapesBatch

Get the shapes batch class.

Kind: instance property of Gfx
See: ShapesBatch

gfx.LinesBatch

Get the lines batch class.

Kind: instance property of Gfx
See: LinesBatch

gfx.Effect

Get the Effect base class, which is required to implement custom effects.

Kind: instance property of Gfx
See: Effect

gfx.SpritesEffect

Get the default sprites effect class.

Kind: instance property of Gfx
See: SpritesEffect

gfx.SpritesEffectNoVertexColor

Get the default sprites effect class that is used when vertex colors is disabled.

Kind: instance property of Gfx
See: SpritesEffectNoVertexColor

gfx.ShapesEffect

Get the default shapes effect class that is used to draw 2d shapes.

Kind: instance property of Gfx
See: ShapesEffect

gfx.Sprites3dEffect

Get the default 3d sprites effect class that is used to draw 3d textured quads.

Kind: instance property of Gfx
See: Sprites3dEffect

gfx.MsdfFontEffect

Get the Effect for rendering fonts with an MSDF texture.

Kind: instance property of Gfx
See: MsdfFontEffect

gfx.Sprite

Get the sprite class.

Kind: instance property of Gfx
See: Sprite

gfx.SpritesGroup

Get the sprites group object.

Kind: instance property of Gfx
See: SpritesGroup

gfx.Matrix

Get the matrix object.

Kind: instance property of Gfx
See: Matrix

gfx.Vertex

Get the vertex object.

Kind: instance property of Gfx
See: Vertex

gfx.TextAlignments

Get the text alignments options.

• Left: align text to the left.
• Right: align text to the right.
• Center: align text to center.

Kind: instance property of Gfx
See: TextAlignments

gfx.BlendModes

Get the blend modes enum.

• AlphaBlend
• Opaque
• Additive
• Multiply
• Subtract
• Screen
• Overlay
• Invert
• DestIn
• DestOut

Kind: instance property of Gfx
See: BlendModes

gfx.TextureWrapModes

Get the wrap modes enum.

• Clamp: when uv position exceed texture boundaries it will be clamped to the nearest border, ie repeat the edge pixels.
• Repeat: when uv position exceed texture boundaries it will wrap back to the other side.
• RepeatMirrored: when uv position exceed texture boundaries it will wrap back to the other side but also mirror the texture.

Kind: instance property of Gfx
See: TextureWrapModes

gfx.TextureFilterModes

Get texture filter modes.

• Nearest: no filtering, no mipmaps (pixelated).
• Linear: simple filtering, no mipmaps (smooth).
• NearestMipmapNearest: no filtering, sharp switching between mipmaps,
• LinearMipmapNearest: filtering, sharp switching between mipmaps.
• NearestMipmapLinear: no filtering, smooth transition between mipmaps.
• LinearMipmapLinear: filtering, smooth transition between mipmaps.

Kind: instance property of Gfx
See: TextureFilterModes

gfx.drawCallsCount ⇒ Number

Get number of actual WebGL draw calls we performed since the beginning of the frame.

Kind: instance property of Gfx
Returns: Number - Number of WebGL draw calls this frame.

gfx.quadsDrawCount ⇒ Number

Get number of textured / colored quads we drawn since the beginning of the frame.

Kind: instance property of Gfx
Returns: Number - Number of quads drawn in this frame.

gfx.shapePolygonsDrawCount ⇒ Number

Get number of shape polygons we drawn since the beginning of the frame.

Kind: instance property of Gfx
Returns: Number - Number of shape polygons drawn in this frame.

gfx.setContextAttributes(flags)

Set WebGL init flags (passed as additional params to the getContext() call). You must call this before initializing Shaku.

By default, Shaku will init WebGL context with the following flags:

• antialias: true.
• alpha: true.
• depth: false.
• premultipliedAlpha: true.
• desynchronized: false.

Kind: instance method of Gfx

Param	Type	Description
flags	Dictionary	WebGL init flags to set.

Example

Shaku.gfx.setContextAttributes({ antialias: true, alpha: false });

gfx.setCanvas(element)

Set the canvas element to initialize on. You must call this before initializing Shaku. Calling this will prevent Shaku from creating its own canvas.

Kind: instance method of Gfx

Param	Type	Description
element	HTMLCanvasElement	Canvas element to initialize on.

Example

Shaku.gfx.setCanvas(document.getElementById('my-canvas')); 

gfx.createCamera(withViewport) ⇒ Camera

Create and return a new camera instance.

Kind: instance method of Gfx
Returns: Camera - New camera object.

Param	Type	Description
withViewport	Boolean	If true, will create camera with viewport value equal to canvas’ size.

gfx.createCamera3D(withViewport) ⇒ Camera3D

Create and return a new 3D camera instance.

Kind: instance method of Gfx
Returns: Camera3D - New camera object.

Param	Type	Description
withViewport	Boolean	If true, will create camera with viewport value equal to canvas’ size.

gfx.setCameraOrthographic(offset) ⇒ Camera

Set default orthographic camera from offset.

Kind: instance method of Gfx
Returns: Camera - Camera instance.

Param	Type	Description
offset	Vector2	Camera top-left corner.

gfx.maximizeCanvasSize([limitToParent], [allowOddNumbers])

Set resolution and canvas to the max size of its parent element or screen. If the canvas is directly under document body, it will take the max size of the page.

Kind: instance method of Gfx

Param	Type	Description
[limitToParent]	Boolean	if true, will use parent element size. If false, will stretch on entire document.
[allowOddNumbers]	Boolean	if true, will permit odd numbers, which could lead to small artefacts when drawing pixel art. If false (default) will round to even numbers.

gfx.setRenderTarget(texture, [keepCamera])

Set a render target (texture) to render on.

Kind: instance method of Gfx

Param	Type	Description
texture	TextureAsset | Array.<TextureAsset> | null	Render target texture to set as render target, or null to reset and render back on canvas. Can also be array for multiple targets, which will take layouts 0-15 by their order.
[keepCamera]	Boolean	If true, will keep current camera settings. If false (default) will reset camera.

Example

// create render target
let renderTarget = await Shaku.assets.createRenderTarget('_my_render_target', 800, 600);

// use render target
Shaku.gfx.setRenderTarget(renderTarget);
// .. draw some stuff here

// reset render target and present it on screen
// note the negative height - render targets end up with flipped Y axis
Shaku.gfx.setRenderTarget(null);
Shaku.gfx.draw(renderTarget, new Shaku.utils.Vector2(screenX / 2, screenY / 2), new Shaku.utils.Vector2(screenX, -screenY));

gfx.setResolution(width, height, updateCanvasStyle)

Set resolution and canvas size.

Kind: instance method of Gfx

Param	Type	Description
width	Number	Resolution width.
height	Number	Resolution height.
updateCanvasStyle	Boolean	If true, will also update the canvas css size in pixels.

Example

// set resolution and size of 800x600.
Shaku.gfx.setResolution(800, 600, true);

gfx.resetCamera()

Reset camera properties to default camera.

Kind: instance method of Gfx

gfx.applyCamera(camera)

Set viewport, projection and other properties from a camera instance. Changing the camera properties after calling this method will not update the renderer, until you call applyCamera again.

Kind: instance method of Gfx

Param	Type	Description
camera	Camera	Camera to apply.

gfx.getRenderingRegion(includeOffset) ⇒ Rectangle

Get current rendering region.

Kind: instance method of Gfx
Returns: Rectangle - Rectangle with rendering region.

Param	Type	Description
includeOffset	Boolean	If true (default) will include viewport offset, if exists.

gfx.getRenderingSize() ⇒ Vector2

Get current rendering size. Unlike ‘canvasSize’, this takes viewport and render target into consideration.

Kind: instance method of Gfx
Returns: Vector2 - rendering size.

gfx.getCanvasSize() ⇒ Vector2

Get canvas size as vector.

Kind: instance method of Gfx
Returns: Vector2 - Canvas size.

gfx.buildText(fontTexture, text, [fontSize], color, [alignment], [offset], [marginFactor]) ⇒ SpritesGroup

Generate a sprites group to render a string using a font texture. Take the result of this method and use with gfx.drawGroup() to render the text. This is what you use when you want to draw texts with Shaku. Note: its best to always draw texts with batching enabled.

Kind: instance method of Gfx
Returns: SpritesGroup - Sprites group containing the needed sprites to draw the given text with its properties.

Param	Type	Description
fontTexture	FontTextureAsset	Font texture asset to use.
text	String	Text to generate sprites for.
[fontSize]	Number	Font size, or undefined to use font texture base size.
color	Color | Array.<Color>=	Text sprites color. If array is set, will assign each color to different vertex, starting from top-left.
[alignment]	TextAlignment	Text alignment.
[offset]	Vector2	Optional starting offset.
[marginFactor]	Vector2	Optional factor for characters and line spacing. For example value of 2,1 will make double horizontal spacing.

Example

// load font texture
let fontTexture = await Shaku.assets.loadFontTexture('assets/DejaVuSansMono.ttf', {fontName: 'DejaVuSansMono'});

// generate 'hello world!' text (note: you don't have to regenerate every frame if text didn't change)
let text1 = Shaku.gfx.buildText(fontTexture, "Hello World!");
text1.position.set(40, 40);

// draw text
Shaku.gfx.drawGroup(text1, true);

gfx.centerCanvas()

Make the renderer canvas centered.

Kind: instance method of Gfx

gfx.inScreen(shape) ⇒ Boolean

Check if a given shape is currently in screen bounds, not taking camera into consideration.

Kind: instance method of Gfx
Returns: Boolean - True if given shape is in visible region.

Param	Type	Description
shape	Circle | Vector | Rectangle | Line	Shape to check.

gfx.centerCamera(position, useCanvasSize)

Make a given vector the center of the camera.

Kind: instance method of Gfx

Param	Type	Description
position	Vector2	Camera position.
useCanvasSize	Boolean	If true, will always use cancas size when calculating center. If false and render target is set, will use render target’s size.

gfx.clear([color])

Clear screen to a given color.

Kind: instance method of Gfx

Param	Type	Description
[color]	Color	Color to clear screen to, or black if not set.

Example

Shaku.gfx.clear(Shaku.utils.Color.cornflowerblue);

gfx.clearDepth([value])

Clear depth buffer. Only relevant when depth is used.

Kind: instance method of Gfx

Param	Type	Description
[value]	Number	Value to clear depth buffer to.