Class: DrawContext

DrawContext(gl)

Provides current state during rendering. The current draw context is passed to most rendering methods in order to make those methods aware of current state.

Constructor

new DrawContext(gl)

Constructs a DrawContext. Applications do not call this constructor. A draw context is created by a WorldWindow during its construction.
Parameters:
Name Type Description
gl WebGLRenderingContext The WebGL rendering context this draw context is associated with.
Source:
Throws:
If the specified WebGL rendering context is null or undefined.
Type
ArgumentError

Members

canvas2D :HTMLElement

A 2D canvas for creating texture maps.
Type:
  • HTMLElement
Source:

clearColor :Color

The current clear color.
Type:
Default Value:
  • Color.TRANSPARENT (red = 0, green = 0, blue = 0, alpha = 0)
Source:

ctx2D

A 2D context for this draw context's canvas property.
Source:

currentFramebuffer :FramebufferTexture

The current WebGL framebuffer. Null indicates that the default WebGL framebuffer is active.
Type:
Source:

currentGlContext :WebGLRenderingContext

The current WebGL rendering context.
Type:
  • WebGLRenderingContext
Source:

currentLayer :Layer

The layer being rendered.
Type:
Source:

currentProgram :GpuProgram

The current WebGL program. Null indicates that no WebGL program is active.
Type:
Source:

deepPicking :Boolean

Indicates that picking will return all objects at the pick point, if any. The top-most object will have its isOnTop flag set to true. If deep picking is false, the default, only the top-most object is returned, plus the picked-terrain object if the pick point is over the terrain.
Type:
  • Boolean
Default Value:
  • false
Source:

(readonly) eyePoint :Vec3

The eye point in model coordinates, relative to the globe's center.
Type:
Source:

eyePosition :Position

The current eye position.
Type:
Source:

fadeTime :Number

The number of milliseconds over which to fade shapes that support fading. Fading is most typically used during decluttering.
Type:
  • Number
Default Value:
  • 500
Source:

frameStatistics :FrameStatistics

Frame statistics.
Type:
Source:

(readonly) frustumInModelCoordinates :Frustum

The viewing frustum in model coordinates. The frustum originates at the eyePoint and extends outward along the forward vector. The near distance and far distance identify the minimum and maximum distance, respectively, at which an object in the scene is visible.
Type:
Source:

globe :Globe

The globe being rendered.
Type:
Source:

globeStateKey :String

A copy of the current globe's state key. Provided here to avoid having to recompute it every time it's needed.
Type:
  • String
Source:

gpuResourceCache :GpuResourceCache

The GPU resource cache, which tracks WebGL resources.
Type:
Source:

layers :Array.<Layer>

The layers being rendered.
Type:
Source:

(readonly) modelview :Matrix

The model-view matrix. The model-view matrix transforms points from model coordinates to eye coordinates.
Type:
Source:

(readonly) modelviewNormalTransform :Matrix

The matrix that transforms normal vectors in model coordinates to normal vectors in eye coordinates. Typically used to transform a shape's normal vectors during lighting calculations.
Type:
Source:

(readonly) modelviewProjection :Matrix

The concatenation of the DrawContext's model-view and projection matrices. This matrix transforms points from model coordinates to clip coordinates.
Type:
Source:

(readonly) objectsAtPickPoint :PickedObjectList

The objects at the current pick point.
Type:
Source:

orderedRenderables :Array

The list of ordered renderables.
Type:
  • Array
Source:

orderedRenderingMode :Boolean

Indicates whether this draw context is in ordered rendering mode.
Type:
  • Boolean
Source:

(readonly) pickFramebuffer :FramebufferTexture

The off-screen WebGL framebuffer used during picking.
Type:
Source:

(readonly) pickFrustum :Frustum

The current pick frustum, created anew each picking frame.
Type:
Source:

pickingMode :Boolean

Indicates whether the frame is being drawn for picking.
Type:
  • Boolean
Source:

pickPoint :Vec2

The current pick point, in screen coordinates.
Type:
Source:

pickRay :Line

The current pick ray originating at the eyePoint and extending through the pick point.
Type:
Source:

pickRectangle :Rectangle

The current pick rectangle, in WebGL (lower-left origin) screen coordinates.
Type:
Source:

pickTerrainOnly :Boolean

Indicates that picking will return only the terrain object, if the pick point is over the terrain.
Type:
  • Boolean
Default Value:
  • false
Source:

(readonly) previousRedrawTimestamp :Number

The time stamp of the last visible frame, in milliseconds. This indicates the time stamp that was current during the WorldWindow's last frame, ignoring frames associated with a picking operation. The difference between the previous redraw time stamp and the current time stamp indicates the duration between visible frames, e.g. timeStamp - previousRedrawTimestamp.
Type:
  • Number
Source:

(readonly) projection :Matrix

The projection matrix. The projection matrix transforms points from eye coordinates to clip coordinates.
Type:
Source:

redrawRequested :Boolean

Indicates whether a redraw has been requested during the current frame. When true, this causes the World Window associated with this draw context to redraw after the current frame.
Type:
  • Boolean
Source:

regionPicking :Boolean

Indicates that picking will return all objects that intersect the pick region, if any. Visible objects will have the isOnTop flag set to true.
Type:
  • Boolean
Default Value:
  • false
Source:

screenCreditController :ScreenCreditController

The screen credit controller responsible for collecting and drawing screen credits.
Type:
Source:

screenProjection :Matrix

The current screen projection matrix.
Type:
Source:

surfaceOpacity :Number

The opacity to apply to terrain and surface shapes. Should be a number between 0 and 1.
Type:
  • Number
Default Value:
  • 1
Source:

surfaceRenderables :Array

The list of surface renderables.
Type:
  • Array
Source:

surfaceShapeTileBuilder :SurfaceShapeTileBuilder

The surface shape tile builder used to create and draw surface shapes.
Type:
  • SurfaceShapeTileBuilder
Source:

surfaceShapeTileController :FramebufferTileController

Provides access to a multi-resolution WebGL framebuffer arranged as adjacent tiles in a pyramid. Surface shapes use these tiles internally to draw on the terrain surface.
Type:
Source:

surfaceTileRenderer :SurfaceTileRenderer

The surface-tile-renderer to use for drawing surface tiles.
Type:
Source:

terrain :Terrain

The terrain for the current frame.
Type:
Source:

textRenderer :TextRenderer

A shared TextRenderer instance.
Type:
Source:

(readonly) timestamp :Number

The starting time of the current frame, in milliseconds. The frame timestamp is updated immediately before the WorldWindow associated with this draw context is rendered, either as a result of redrawing or as a result of a picking operation.
Type:
  • Number
Source:

verticalExaggeration :Number

The current vertical exaggeration.
Type:
  • Number
Source:

(readonly) viewport :Rectangle

The current viewport.
Type:
Source:

Methods

addOrderedRenderable(orderedRenderable, eyeDistance)

Adds an ordered renderable to this draw context's ordered renderable list.
Parameters:
Name Type Description
orderedRenderable OrderedRenderable The ordered renderable to add. May be null, in which case the current ordered renderable list remains unchanged.
eyeDistance Number An optional argument indicating the ordered renderable's eye distance. If this parameter is not specified then the ordered renderable must have an eyeDistance property.
Source:

addOrderedRenderableToBack(orderedRenderable)

Adds an ordered renderable to the end of this draw context's ordered renderable list, denoting it as the most distant from the eye point.
Parameters:
Name Type Description
orderedRenderable OrderedRenderable The ordered renderable to add. May be null, in which case the current ordered renderable list remains unchanged.
Source:

addPickedObject(pickedObject)

Adds an object to the current picked-object list. The list identifies objects that are at the pick point but not necessarily the top-most object.
Parameters:
Name Type Description
pickedObject PickedObject The object to add.
Source:

addSurfaceRenderable(surfaceRenderable)

Adds a surface renderable to this draw context's surface renderable list.
Parameters:
Name Type Description
surfaceRenderable SurfaceRenderable The surface renderable to add. May be null, in which case the current surface renderable list remains unchanged.
Source:

bindFramebuffer(framebuffer)

Binds a specified WebGL framebuffer. This function also makes the framebuffer the active framebuffer.
Parameters:
Name Type Description
framebuffer FramebufferTexture The framebuffer to bind. May be null or undefined, in which case the default WebGL framebuffer is made active.
Source:

bindProgram(program)

Binds a specified WebGL program. This function also makes the program the current program.
Parameters:
Name Type Description
program GpuProgram The program to bind. May be null or undefined, in which case the currently bound program is unbound.
Source:

computeTextTextureStateKey(text, attributes) → {String}

Computes a state key that relates to a text label, foregoing the TextAttributes TextAttributes properties that are not related to texture rendering (offset, scale, and depthTest).
Parameters:
Name Type Description
text String The label's string of text.
attributes TextAttributes The TextAttributes object associated with the text label to render.
Source:
Returns:
A state key composed of the original string of text plus the TextAttributes associated with texture rendering.
Type
String

contextLost()

Notifies this draw context that the current WebGL rendering context has been lost. This function removes all cached WebGL resources and resets all properties tracking the current WebGL state.
Source:

contextRestored()

Notifies this draw context that the current WebGL rendering context has been restored. This function prepares this draw context to resume rendering.
Source:

convertPointToViewport(point, result) → {Vec2}

Converts a window-coordinate point to WebGL screen coordinates.

The specified point is understood to be in the window coordinate system of the WorldWindow, with the origin in the top-left corner and axes that extend down and to the right from the origin point.

The returned point is in WebGL screen coordinates, with the origin in the bottom-left corner and axes that extend up and to the right from the origin point.

Parameters:
Name Type Description
point Vec2 The window-coordinate point to convert.
result Vec2 A pre-allocated Vec2 in which to return the computed point.
Source:
Throws:
If either argument is null or undefined.
Type
ArgumentError
Returns:
The specified result argument set to the computed point.
Type
Vec2

createTextTexture(text, textAttributes) → {Texture}

Propagates the values contained in a TextAttributes object to the currently attached TextRenderer TextRenderer as to provide format to a string of text. It first checks if the 2D texture is not already cached according to the text string and its attached TextAttributes TextAttributes state key. The TextRenderer then produces a 2D Texture with the aforementioned text and format to be used as a label for a Text Text subclass (e.g. Annotation Annotation or Placemark Placemark).
Parameters:
Name Type Description
text String The string of text that will be given color, font, and outline from which the resulting texture will be based on.
textAttributes TextAttributes Attributes that will be applied to the string. See TextAttributes TextAttributes.
Source:
Returns:
A texture Texture with the specified text string, font, colors, and outline.
Type
Texture

findAndBindProgram(programConstructor) → {GpuProgram}

Binds a potentially cached WebGL program, creating and caching it if it isn't already cached. This function also makes the program the current program.
Parameters:
Name Type Description
programConstructor function The constructor to use to create the program.
Source:
Throws:
If the specified constructor is null or undefined.
Type
ArgumentError
Returns:
The bound program.
Type
GpuProgram

getExtension(extensionName) → {Object|null}

Returns a WebGL extension and caches the result for subsequent calls.
Parameters:
Name Type Description
extensionName String The name of the WebGL extension.
Source:
Throws:
If the argument is null or undefined.
Type
ArgumentError
Returns:
A WebGL extension object, or null if the extension is not available.
Type
Object | null

isSmall(extent, numPixels) → {Boolean}

Indicates whether an extent is smaller than a specified number of pixels.
Parameters:
Name Type Description
extent BoundingBox The extent to test.
numPixels Number The number of pixels below which the extent is considered small.
Source:
Returns:
True if the extent is smaller than the specified number of pixels, otherwise false. Returns false if the extent is null or undefined.
Type
Boolean

makePickFramebuffer()

Creates an off-screen WebGL framebuffer for use during picking and stores it in this draw context. The framebuffer width and height match the WebGL rendering context's drawingBufferWidth and drawingBufferHeight.
Source:

makePickFrustum() → {Boolean}

Creates a pick frustum for the current pick point and stores it in this draw context. If this context's pick rectangle is null or undefined then a pick rectangle is also computed and assigned to this context. If the existing pick rectangle extends beyond the viewport then it is truncated by this method to fit within the viewport. This method assumes that this draw context's pick point or pick rectangle has been set. It returns false if neither one of these exists.
Source:
Returns:
true if the pick frustum could be created, otherwise false.
Type
Boolean

nextScreenRenderable() → {OrderedRenderable}

Returns the ordered renderable at the head of the ordered renderable list and removes it from the list.
Source:
Returns:
The first ordered renderable in this draw context's ordered renderable list, or null if the ordered renderable list is empty.
Type
OrderedRenderable

peekOrderedRenderable() → {OrderedRenderable}

Returns the ordered renderable at the head of the ordered renderable list without removing it from the list.
Source:
Returns:
The first ordered renderable in this draw context's ordered renderable list, or null if the ordered renderable list is empty.
Type
OrderedRenderable

peekSurfaceRenderable() → {SurfaceRenderable}

Returns the surface renderable at the head of the surface renderable list without removing it from the list.
Source:
Returns:
The first surface renderable in this draw context's surface renderable list, or null if the surface renderable list is empty.
Type
SurfaceRenderable

pixelSizeAtDistance(distance) → {Number}

Computes the approximate size of a pixel at a specified distance from the eye point.

This method assumes rectangular pixels, where pixel coordinates denote infinitely thin spaces between pixels. The units of the returned size are in model coordinates per pixel (usually meters per pixel). This returns 0 if the specified distance is zero. The returned size is undefined if the distance is less than zero.

Parameters:
Name Type Description
distance Number The distance from the eye point at which to determine pixel size, in model coordinates.
Source:
Returns:
The approximate pixel size at the specified distance from the eye point, in model coordinates per pixel.
Type
Number

popOrderedRenderable() → {OrderedRenderable}

Returns the ordered renderable at the head of the ordered renderable list and removes it from the list.
Source:
Returns:
The first ordered renderable in this draw context's ordered renderable list, or null if the ordered renderable list is empty.
Type
OrderedRenderable

popSurfaceRenderable() → {SurfaceRenderable}

Returns the surface renderable at the head of the surface renderable list and removes it from the list.
Source:
Returns:
The first surface renderable in this draw context's surface renderable list, or null if the surface renderable list is empty.
Type
SurfaceRenderable

project(modelPoint, result) → {boolean}

Transforms the specified model point from model coordinates to WebGL screen coordinates.

The resultant screen point is in WebGL screen coordinates, with the origin in the bottom-left corner and axes that extend up and to the right from the origin.

This function stores the transformed point in the result argument, and returns true or false to indicate whether or not the transformation is successful. It returns false if the modelview or projection matrices are malformed, or if the specified model point is clipped by the near clipping plane or the far clipping plane.

Parameters:
Name Type Description
modelPoint Vec3 The model coordinate point to project.
result Vec3 A pre-allocated vector in which to return the projected point.
Source:
Throws:
If either the specified point or result argument is null or undefined.
Type
ArgumentError
Returns:
true if the transformation is successful, otherwise false.
Type
boolean

projectWithDepth(modelPoint, depthOffset, result) → {boolean}

Transforms the specified model point from model coordinates to WebGL screen coordinates, applying an offset to the modelPoint's projected depth value.

The resultant screen point is in WebGL screen coordinates, with the origin in the bottom-left corner and axes that extend up and to the right from the origin.

This function stores the transformed point in the result argument, and returns true or false to indicate whether or not the transformation is successful. It returns false if the modelview or projection matrices are malformed, or if the modelPoint is clipped by the near clipping plane or the far clipping plane, ignoring the depth offset.

The depth offset may be any real number and is typically used to move the screenPoint slightly closer to the user's eye in order to give it visual priority over nearby objects or terrain. An offset of zero has no effect. An offset less than zero brings the screenPoint closer to the eye, while an offset greater than zero pushes the projected screen point away from the eye.

Applying a non-zero depth offset has no effect on whether the model point is clipped by this method or by WebGL. Clipping is performed on the original model point, ignoring the depth offset. The final depth value after applying the offset is clamped to the range [0,1].

Parameters:
Name Type Description
modelPoint Vec3 The model coordinate point to project.
depthOffset Number The amount of offset to apply.
result Vec3 A pre-allocated vector in which to return the projected point.
Source:
Throws:
If either the specified point or result argument is null or undefined.
Type
ArgumentError
Returns:
true if the transformation is successful, otherwise false.
Type
boolean

readPickColor(pickPoint) → {Color}

Reads the color from the current render buffer at a specified point. Used during picking to identify the item most recently affecting the pixel at the specified point.
Parameters:
Name Type Description
pickPoint Vec2 The current pick point.
Source:
Returns:
The color at the pick point.
Type
Color

readPickColors(pickRectangle) → {Object}

Reads the current pick buffer colors in a specified rectangle. Used during region picking to identify the items not occluded.
Parameters:
Name Type Description
pickRectangle Rectangle The rectangle for which to read the colors.
Source:
Returns:
An object containing the unique colors in the specified rectangle, excluding the current clear color. The colors are referenced by their byte string (see Color.toByteString.
Type
Object

reset()

Prepare this draw context for the drawing of a new frame.
Source:

resolvePick(pickableObject) → {null}

Determines whether a specified picked object is under the pick point, and if it is adds it to this draw context's list of picked objects. This method should be called by shapes during ordered rendering after the shape is drawn. If this draw context is in single-picking mode, the specified pickable object is added to the list of picked objects whether or not it is under the pick point.
Parameters:
Name Type Description
pickableObject
Source:
Returns:
Type
null

reverseSurfaceRenderables()

Reverses the surface renderable list in place. After this function completes, the functions peekSurfaceRenderable and popSurfaceRenderable return renderables in the order in which they were added to the surface renderable list.
Source:

sortOrderedRenderables()

Sorts the ordered renderable list from nearest to the eye point to farthest from the eye point.
Source:

surfacePointForMode(latitude, longitude, offset, altitudeMode, result) → {Vec3}

Computes a Cartesian point at a location on the surface of this terrain according to a specified altitude mode. If there is no current terrain, this function approximates the returned point by assuming the terrain is the globe's ellipsoid.
Parameters:
Name Type Description
latitude Number The location's latitude.
longitude Number The location's longitude.
offset Number Distance above the terrain, in meters relative to the specified altitude mode, at which to compute the point.
altitudeMode String The altitude mode to use to compute the point. Recognized values are WorldWind.ABSOLUTE, WorldWind.CLAMP_TO_GROUND and WorldWind.RELATIVE_TO_GROUND. The mode WorldWind.ABSOLUTE is used if the specified mode is null, undefined or unrecognized, or if the specified location is outside this terrain.
result Vec3 A pre-allocated Vec3 in which to return the computed point.
Source:
Throws:
If the specified result argument is null or undefined.
Type
ArgumentError
Returns:
The specified result parameter, set to the coordinates of the computed point.
Type
Vec3

uniquePickColor() → {Color}

Computes a unique color to use as a pick color.
Source:
Returns:
A unique color.
Type
Color

unitCubeBuffer() → {Object}

Returns the VBO ID of an array buffer containing a unit cube expressed as eight 3D vertices at (0, 1, 0), (0, 0, 0), (1, 1, 0), (1, 0, 0), (0, 1, 1), (0, 0, 1), (1, 1, 1) and (1, 0, 1). The buffer is created on first use and cached. Subsequent calls to this method return the cached buffer.
Source:
Returns:
The VBO ID identifying the array buffer.
Type
Object

unitCubeElements() → {Object}

Returns the VBO ID of a element array buffer containing the tessellation of a unit cube expressed as a single buffer containing both triangle indices and line indices. This is intended for use in conjunction with unitCubeBuffer. The unit cube's interior and outline may be rasterized as shown in the following WebGL pseudocode: 
// Assumes that the VBO returned by unitCubeBuffer is used as the source of vertex positions.
bindBuffer(ELEMENT_ARRAY_BUFFER, drawContext.unitCubeElements());
drawElements(TRIANGLES, 36, UNSIGNED_SHORT, 0); // draw the unit cube interior
drawElements(LINES, 24, UNSIGNED_SHORT, 72); // draw the unit cube outline
The buffer is created on first use and cached. Subsequent calls to this method return the cached buffer.
Source:
Returns:
The VBO ID identifying the element array buffer.
Type
Object

unitQuadBuffer() → {Object}

Returns the VBO ID of a buffer containing a unit quadrilateral expressed as four 2D vertices at (0, 1), (0, 0), (1, 1) and (1, 0). The four vertices are in the order required by a triangle strip. The buffer is created on first use and cached. Subsequent calls to this method return the cached buffer.
Source:
Returns:
The VBO ID identifying the vertex buffer.
Type
Object

unitQuadBuffer3() → {Object}

Returns the VBO ID of a buffer containing a unit quadrilateral expressed as four 3D vertices at (0, 1, 0), (0, 0, 0), (1, 1, 0) and (1, 0, 0). The four vertices are in the order required by a triangle strip. The buffer is created on first use and cached. Subsequent calls to this method return the cached buffer.
Source:
Returns:
The VBO ID identifying the vertex buffer.
Type
Object

update()

Computes any values necessary to render the upcoming frame. Called after all draw context state for the frame has been set.
Source: