# RenderWebGL

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

See:
  - RenderWebGL#setStageSize
  - RenderWebGL#resize

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:

- RenderWebGL#event:NativeSizeChanged

### 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 :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:

- int

#### _allDrawables :Array.<Drawable>

##### Type:

- Array.<Drawable>

#### _allSkins :Array.<Skin>

##### Type:

- Array.<Skin>

#### _allSkins[undefined] :PenSkin

##### Type:

- PenSkin

#### _allSkins[undefined] :PenSkin

##### Type:

- PenSkin

#### _allSkins[undefined] :PenSkin

##### Type:

- PenSkin

#### _allSkins[undefined] :PenSkin

##### Type:

- PenSkin

#### _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:

- ShaderManager

#### _skinUrlMap :Object.<string, int>

##### Type:

- Object.<string, int>

#### _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:

- RenderWebGL#event:NativeSizeChanged

#### _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

#### createSkinFromURL(skinUrlnon-null, costumeResolutionopt, non-null, rotationCenternullable) → (non-null) {int}

Deprecated:
  - Yes

Create a skin by loading a bitmap or vector image from a URL, or reuse an existing skin created this way. WARNING: This method is deprecated and will be removed in the near future. Use `createBitmapSkin` or `createSVGSkin` instead.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`skinUrl` | string |  | The URL of the skin.
`costumeResolution` | int | <optional> | Optional: resolution for the skin. Ignored unless creating a new Bitmap skin.
`rotationCenter` | Array.<number> | <nullable> | Optional: rotation center of the skin. If not supplied, the center of the skin will be used.

##### Returns:

The ID of the 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.

#### 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.

### 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:

- PenSkin
- RenderWebGL