RenderWebGL

RenderWebGL

new RenderWebGL(canvas, xLeftopt, xRightopt, yBottomopt, yTopopt)

See:

Create a renderer for drawing Scratch sprites to a canvas using WebGL. Coordinates will default to Scratch 2.0 values if unspecified. The stage's "native" size will be calculated from the these coordinates. For example, the defaults result in a native size of 480x360. Queries such as "touching color?" will always execute at the native size.

Parameters:
Name Type Attributes Default Description
canvas canvas

The canvas to draw onto.

xLeft int <optional>
-240

The x-coordinate of the left edge.

xRight int <optional>
240

The x-coordinate of the right edge.

yBottom int <optional>
-180

The y-coordinate of the bottom edge.

yTop int <optional>
180

The y-coordinate of the top edge.

Listens to Events:

Members

(static, constant) MAX_TOUCH_SIZE :Array.<int>

To Do:
  • Figure out a reasonable max size. Maybe this should be configurable?

Maximum touch size for a picking check.

Type:
  • Array.<int>

(static, constant) TOLERANCE_TOUCHING_COLOR :object.<string, int>

"touching {color}?" or "{color} touching {color}?" tests will be true if the target is touching a color whose components are each within this tolerance of the corresponding component of the query color. between 0 (exact matches only) and 255 (match anything).

Type:
  • object.<string, int>

_allDrawables :Array.<Drawable>

Type:

_allSkins :Array.<Skin>

Type:

_allSkins[undefined] :PenSkin

Type:

_allSkins[undefined] :PenSkin

Type:

_allSkins[undefined] :PenSkin

Type:

_allSkins[undefined] :PenSkin

Type:

_drawList :Array.<int>

Type:
  • Array.<int>

_nextDrawableId :int

Type:
  • int

_nextSkinId :int

Type:
  • int

_projection :module:twgl/m4.Mat4

Type:
  • module:twgl/m4.Mat4

_shaderManager :ShaderManager

Type:

_tempCanvas :HTMLCanvasElement

Type:
  • HTMLCanvasElement

gl

Methods

(private) _createGeometry()

Build geometry (vertex and index) buffers.

(private) _drawThese(drawables, drawMode, projection, optsopt)

Draw a set of Drawables, by drawable ID

Parameters:
Name Type Attributes Description
drawables Array.<int>

The Drawable IDs to draw, possibly this._drawList.

drawMode ShaderManager.DRAW_MODE

Draw normally, silhouette, etc.

projection module:twgl/m4.Mat4

The projection matrix to use.

opts object <optional>

Options for drawing

Properties
Name Type Description
filter idFilterFunc

An optional filter function.

extraUniforms object.<string, *>

Extra uniforms for the shaders.

effectMask int

Bitmask for effects to allow

isStamping boolean

Stamp mode ignores sprite visibility, always drawing.

_filterCandidatesTouching(drawableID, candidateIDs, bounds) → (nullable) {Array.<int>}

Filter a list of candidates for a touching query into only those that could possibly intersect the given bounds.

Parameters:
Name Type Description
drawableID int

ID for drawable of query.

candidateIDs Array.<int>

Candidates for touching query.

bounds Rectangle

Bounds to limit candidates to.

Returns:

Filtered candidateIDs, or null if none.

Type
Array.<int>

_getConvexHullPointsForDrawable(drawableID) → {Array.<Array.<number>>}

Get the convex hull points for a particular Drawable. To do this, draw the Drawable unrotated, unscaled, and untranslated. Read back the pixels and find all boundary points. Finally, apply a convex hull algorithm to simplify the set.

Parameters:
Name Type Description
drawableID int

The Drawable IDs calculate convex hull for.

Returns:

points Convex hull points, as [[x, y], ...]

Type
Array.<Array.<number>>

(private) _setNativeSize(width, height)

Set the "native" size of the stage, which is used for pen, query renders, etc.

Parameters:
Name Type Description
width int

the new width to set.

height int

the new height to set.

Fires:

_touchingBounds(drawableID) → (nullable) {Rectangle}

Get the candidate bounding box for a touching query.

Parameters:
Name Type Description
drawableID int

ID for drawable of query.

Returns:

Rectangle bounds for touching query, or null.

Type
Rectangle

createBitmapSkin(bitmapData, costumeResolutionopt, non-null, rotationCenternullable) → (non-null) {int}

Create a new bitmap skin from a snapshot of the provided bitmap data.

Parameters:
Name Type Attributes Default Description
bitmapData ImageData | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement

new contents for this skin.

costumeResolution int <optional>
1

The resolution to use for this bitmap.

rotationCenter Array.<number> <nullable>

Optional: rotation center of the skin. If not supplied, the center of the skin will be used

Returns:

the ID for the new skin.

Type
int

createDrawable() → {int}

Create a new Drawable and add it to the scene.

Returns:

The ID of the new Drawable.

Type
int

createPenSkin() → (non-null) {int}

Create a new PenSkin - a skin which implements a Scratch pen layer.

Returns:

the ID for the new skin.

Type
int

createSVGSkin(svgDatanon-null, rotationCenternullable) → (non-null) {int}

Create a new SVG skin.

Parameters:
Name Type Attributes Description
svgData string

new SVG to use.

rotationCenter Array.<number> <nullable>

Optional: rotation center of the skin. If not supplied, the center of the skin will be used

Returns:

the ID for the new skin.

Type
int

destroyDrawable(drawableID)

Destroy a Drawable, removing it from the scene.

Parameters:
Name Type Description
drawableID int

The ID of the Drawable to remove.

destroySkin(skinIdnon-null)

Destroy an existing skin. Do not use the skin or its ID after calling this.

Parameters:
Name Type Description
skinId int

The ID of the skin to destroy.

draw()

Draw all current drawables and present the frame on the canvas.

extractColor(x, y, radius) → (nullable) {ColorExtraction}

Return drawable pixel data and color at a given position

Parameters:
Name Type Description
x int

The client x coordinate of the picking location.

y int

The client y coordinate of the picking location.

radius int

The client radius to extract pixels with.

Returns:

Data about the picked color

Type
ColorExtraction

extractDrawable(drawableID, x, y) → (nullable) {DrawableExtraction}

Return drawable pixel data and picking coordinates relative to the drawable bounds

Parameters:
Name Type Description
drawableID int

The ID of the drawable to get pixel data for

x int

The client x coordinate of the picking location.

y int

The client y coordinate of the picking location.

Returns:

Data about the picked drawable

Type
DrawableExtraction

getBounds(drawableID) → {object}

Get the precise bounds for a Drawable.

Parameters:
Name Type Description
drawableID int

ID of Drawable to get bounds for.

Returns:

Bounds for a tight box around the Drawable.

Type
object

getFencedPositionOfDrawable(drawableID, position) → {Array.<number, number>}

Update the position object's x & y members to keep the drawable fenced in view.

Parameters:
Name Type Description
drawableID int

The ID of the Drawable to update.

position Array.<number, number>

to be fenced - An array of type [x, y]

Returns:

The fenced position as an array [x, y]

Type
Array.<number, number>

getNativeSize() → {Array.<int>}

Returns:

the "native" size of the stage, which is used for pen, query renders, etc.

Type
Array.<int>

getSkinSize(drawableID) → {Array.<number>}

Get the current skin (costume) size of a Drawable.

Parameters:
Name Type Description
drawableID int

The ID of the Drawable to measure.

Returns:

Skin size, width and height.

Type
Array.<number>

isTouchingColor(drawableID, color3b, mask3bopt) → {boolean}

Check if a particular Drawable is touching a particular color.

Parameters:
Name Type Attributes Description
drawableID int

The ID of the Drawable to check.

color3b Array.<int>

Test if the Drawable is touching this color.

mask3b Array.<int> <optional>

Optionally mask the check to this part of Drawable.

Returns:

True iff the Drawable is touching the color.

Type
boolean

isTouchingDrawables(drawableID, candidateIDs) → {boolean}

Check if a particular Drawable is touching any in a set of Drawables.

Parameters:
Name Type Description
drawableID int

The ID of the Drawable to check.

candidateIDs Array.<int>

The Drawable IDs to check, otherwise all.

Returns:

True iff the Drawable is touching one of candidateIDs.

Type
boolean

(private) onNativeSizeChanged(event)

Respond to a change in the "native" rendering size. The native size is used by buffers which are fixed in size regardless of the size of the main render target. This includes the buffers used for queries such as picking and color-touching. The fixed size allows (more) consistent behavior across devices and presentation modes.

Parameters:
Name Type Description
event object

The change event.

penClear(penSkinID)

Clear a pen layer.

Parameters:
Name Type Description
penSkinID int

the unique ID of a Pen Skin.

penLine(penSkinID, penAttributes, x0, y0, x1, y1)

Draw a line on a pen layer.

Parameters:
Name Type Description
penSkinID int

the unique ID of a Pen Skin.

penAttributes PenAttributes

how the line should be drawn.

x0 number

the X coordinate of the beginning of the line.

y0 number

the Y coordinate of the beginning of the line.

x1 number

the X coordinate of the end of the line.

y1 number

the Y coordinate of the end of the line.

penPoint(penSkinID, penAttributes, x, y)

Draw a point on a pen layer.

Parameters:
Name Type Description
penSkinID int

the unique ID of a Pen Skin.

penAttributes PenAttributes

how the point should be drawn.

x number

the X coordinate of the point to draw.

y number

the Y coordinate of the point to draw.

penStamp(penSkinID, stampID)

Stamp a Drawable onto a pen layer.

Parameters:
Name Type Description
penSkinID int

the unique ID of a Pen Skin.

stampID int

the unique ID of the Drawable to use as the stamp.

pick(centerX, centerY, touchWidth, touchHeight, candidateIDs) → {int}

Detect which sprite, if any, is at the given location.

Parameters:
Name Type Description
centerX int

The client x coordinate of the picking location.

centerY int

The client y coordinate of the picking location.

touchWidth int

The client width of the touch event (optional).

touchHeight int

The client height of the touch event (optional).

candidateIDs Array.<int>

The Drawable IDs to pick from, otherwise all.

Returns:

The ID of the topmost Drawable under the picking location, or RenderConstants.ID_NONE if there is no Drawable at that location.

Type
int

resize(pixelsWide, pixelsTall)

Set the physical size of the stage in device-independent pixels. This will be multiplied by the device's pixel ratio on high-DPI displays.

Parameters:
Name Type Description
pixelsWide int

The desired width in device-independent pixels.

pixelsTall int

The desired height in device-independent pixels.

setBackgroundColor(red, green, blue)

Set the background color for the stage. The stage will be cleared with this color each frame.

Parameters:
Name Type Description
red number

The red component for the background.

green number

The green component for the background.

blue number

The blue component for the background.

setDebugCanvas(canvas)

Tell the renderer to draw various debug information to the provided canvas during certain operations.

Parameters:
Name Type Description
canvas canvas

The canvas to use for debug output.

setDrawableOrder(drawableID, order, optIsRelativeopt, optMinopt) → (nullable) {number}

Set a drawable's order in the drawable list (effectively, z/layer). Can be used to move drawables to absolute positions in the list, or relative to their current positions. "go back N layers": setDrawableOrder(id, -N, true, 1); (assuming stage at 0). "go to back": setDrawableOrder(id, 1); (assuming stage at 0). "go to front": setDrawableOrder(id, Infinity);

Parameters:
Name Type Attributes Description
drawableID int

ID of Drawable to reorder.

order number

New absolute order or relative order adjusment.

optIsRelative boolean <optional>

If set, order refers to a relative change.

optMin number <optional>

If set, order constrained to be at least optMin.

Returns:

New order if changed, or null.

Type
number

setStageSize(xLeft, xRight, yBottom, yTop)

Set logical size of the stage in Scratch units.

Parameters:
Name Type Description
xLeft int

The left edge's x-coordinate. Scratch 2 uses -240.

xRight int

The right edge's x-coordinate. Scratch 2 uses 240.

yBottom int

The bottom edge's y-coordinate. Scratch 2 uses -180.

yTop int

The top edge's y-coordinate. Scratch 2 uses 180.

updateDrawableProperties(drawableID, properties)

Update the position, direction, scale, or effect properties of this Drawable.

Parameters:
Name Type Description
drawableID int

The ID of the Drawable to update.

properties object.<string, *>

The new property values to set.

updateSVGSkin(skinIdnon-null, svgDatanon-null, rotationCenternullable)

Update an existing SVG skin, or create an SVG skin if the previous skin was not SVG.

Parameters:
Name Type Attributes Description
skinId int

the ID for the skin to change.

svgData string

new SVG to use.

rotationCenter Array.<number> <nullable>

Optional: rotation center of the skin. If not supplied, the center of the skin will be used

Type Definitions

idFilterFunc(drawableID) → {bool}

Parameters:
Name Type Description
drawableID int

The ID to filter.

Returns:

True if the ID passes the filter, otherwise false.

Type
bool

Events

event:NativeSizeChanged

Properties:
Name Type Description
newSize Array.<int>

the new size of the renderer

NativeSizeChanged event

Type:
  • object
Listeners of This Event: