Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Painter

A class that orchestrates rendering of all Starling display objects.

A Starling instance contains exactly one 'Painter' instance that should be used for all rendering purposes. Each frame, it is passed to the render methods of all rendered display objects. To access it outside a render method, call Starling.painter.

The painter is responsible for drawing all display objects to the screen. At its core, it is a wrapper for many Context3D methods, but that's not all: it also provides a convenient state mechanism, supports masking and acts as __iddleman between display objects and renderers.

The State Stack

The most important concept of the Painter class is the state stack. A RenderState stores a combination of settings that are currently used for rendering, e.g. the current projection- and modelview-matrices and context-related settings. It can be accessed and manipulated via the state property. Use the methods pushState and popState to store a specific state and restore it later. That makes it easy to write rendering code that doesn't have any side effects.

painter.pushState(); // save a copy of the current state on the stack painter.state.renderTarget = renderTexture; painter.state.transformModelviewMatrix(object.transformationMatrix); painter.state.alpha = 0.5; painter.prepareToDraw(); // apply all state settings at the render context drawSomething(); // insert Stage3D rendering code here painter.popState(); // restores previous state

@see RenderState

Hierarchy

  • Painter

Index

Constructors

constructor

  • new Painter(stage3D: Stage3D, sharedContext?: null | boolean): Painter
  • Creates a new Painter object. Normally, it's not necessary to create any custom painters; instead, use the global painter found on the Starling instance.

    Parameters

    • stage3D: Stage3D
    • Optional sharedContext: null | boolean

    Returns Painter

Properties

backBufferHeight

backBufferHeight: number

Returns the current height of the back buffer. In most cases, this value is in pixels; however, if the app is running on an HiDPI display with an activated 'supportHighResolutions' setting, you have to multiply with 'backBufferPixelsPerPoint' for the actual pixel count. Alternatively, use the Context3D-property with the same name: it will return the exact pixel values.

backBufferScaleFactor

backBufferScaleFactor: number

The number of pixels per point returned by the 'backBufferWidth/Height' properties. Except for desktop HiDPI displays with an activated 'supportHighResolutions' setting, this will always return '1'.

backBufferWidth

backBufferWidth: number

Returns the current width of the back buffer. In most cases, this value is in pixels; however, if the app is running on an HiDPI display with an activated 'supportHighResolutions' setting, you have to multiply with 'backBufferPixelsPerPoint' for the actual pixel count. Alternatively, use the Context3D-property with the same name: it will return the exact pixel values.

cacheEnabled

cacheEnabled: boolean

Indicates if the render cache is enabled. Normally, this should be left at the default; however, some custom rendering logic might require to change this property temporarily. Also note that the cache is automatically reactivated each frame, right before the render process.

@default true

context

context: Context3D

The Context3D instance this painter renders into.

contextValid

contextValid: boolean

Indicates if the Context3D object is currently valid (i.e. it hasn't been lost or disposed).

drawCount

drawCount: number

Indicates the number of stage3D draw calls.

enableErrorChecking

enableErrorChecking: boolean

Indicates if Stage3D render methods will report errors. Activate only when needed, as this has a negative impact on performance. @default false

frameID

frameID: number

Returns the index of the current frame if the render cache is enabled; otherwise, returns zero. To get the frameID regardless of the render cache, call Starling.frameID instead.

pixelSize

pixelSize: number

The size (in points) that represents one pixel in the back buffer.

profile

profile: string

The Context3D profile of the current render context, or null if the context has not been created yet.

Protected programs

programs: Map<string, Program>

shareContext

shareContext: boolean

Indicates if another Starling instance (or another Stage3D framework altogether) uses the same render context. @default false

sharedData

sharedData: Map<string, any>

A dictionary that can be used to save custom data related to the render context. If you need to share data that is bound to the render context (e.g. textures), use this dictionary instead of creating a static class variable. That way, the data will be available for all Starling instances that use this stage3D / context.

stage3D

stage3D: Stage3D

The Stage3D instance this painter renders into.

state

The current render state, containing some of the context settings, projection- and modelview-matrix, etc. Always returns the same instance, even after calls to "pushState" and "popState".

When you change the current RenderState, and this change is not compatible with the current render batch, the batch will be concluded right away. Thus, watch out for changes of blend mode, clipping rectangle, render target or culling.

stencilReferenceValue

stencilReferenceValue: number

The current stencil reference value of the active render target. This value is typically incremented when drawing a mask and decrementing when erasing it. The painter keeps track of one stencil reference value per render target. Only change this value if you know what you're doing!

Static DEFAULT_STENCIL_VALUE

DEFAULT_STENCIL_VALUE: number

The value with which the stencil buffer will be cleared, and the default reference value used for stencil tests.

Methods

batchMesh

  • Adds a mesh to the current batch of unrendered meshes. If the current batch is not compatible with the mesh, all previous meshes are rendered at once and the batch is cleared.

    @param mesh The mesh to batch. @param subset The range of vertices to be batched. If null, the complete mesh will be used.

    Parameters

    Returns void

clear

  • clear(rgb?: number, alpha?: number): void
  • Clears the render context with a certain color and alpha value. Since this also clears the stencil buffer, the stencil reference value is also reset to '0'.

    Parameters

    • Optional rgb: number
    • Optional alpha: number

    Returns void

configureBackBuffer

  • configureBackBuffer(viewPort: Rectangle, contentScaleFactor: number, antiAlias: number, enableDepthAndStencil: boolean, supportBrowserZoom?: boolean): void
  • Sets the viewport dimensions and other attributes of the rendering buffer. Starling will call this method internally, so most apps won't need to mess with this.

    Beware: if shareContext is enabled, the method will only update the painter's context-related information (like the size of the back buffer), but won't make any actual changes to the context.

    Parameters

    • viewPort: Rectangle

      the position and size of the area that should be rendered into, in pixels.

    • contentScaleFactor: number

      only relevant for Desktop (!) HiDPI screens. If you want to support high resolutions, pass the 'contentScaleFactor' of the Flash stage; otherwise, '1.0'.

    • antiAlias: number

      from 0 (none) to 16 (very high quality).

    • enableDepthAndStencil: boolean

      indicates whether the depth and stencil buffers should be enabled. Note that on AIR, you also have to enable this setting in the app-xml (application descriptor); otherwise, this setting will be silently ignored.

    • Optional supportBrowserZoom: boolean

      if enabled, zooming a website will adapt the size of the back buffer.

    Returns void

deleteProgram

  • deleteProgram(name: string): void

dispose

  • dispose(): void

drawFromCache

drawMask

  • Draws a display object into the stencil buffer, incrementing the buffer on each used pixel. The stencil reference value is incremented as well; thus, any subsequent stencil tests outside of this area will fail.

    If 'mask' is part of the display list, it will be drawn at its conventional stage coordinates. Otherwise, it will be drawn with the current modelview matrix.

    As an optimization, this method might update the clipping rectangle of the render state instead of utilizing the stencil buffer. This is possible when the mask object is of type starling.display.Quad and is aligned parallel to the stage axes.

    Note that masking breaks the render cache; the masked object must be redrawn anew in the next frame. If you pass maskee, the method will automatically call excludeFromCache(maskee) for you.

    Parameters

    Returns void

enableBatchTrimming

  • enableBatchTrimming(enabled?: boolean, interval?: number): void
  • Indicate how often the internally used batches are being trimmed to save memory.

    While rendering, the internally used MeshBatches are used in a different way in each frame. To save memory, they should be trimmed every once in a while. This method defines how often that happens, if at all. (Default: enabled = true, interval = 250)

    @param enabled If trimming happens at all. Only disable temporarily! @param interval The number of frames between each trim operation.

    Parameters

    • Optional enabled: boolean
    • Optional interval: number

    Returns void

eraseMask

  • Draws a display object into the stencil buffer, decrementing the buffer on each used pixel. This effectively erases the object from the stencil buffer, restoring the previous state. The stencil reference value will be decremented.

    Note: if the mask object meets the requirements of using the clipping rectangle, it will be assumed that this erase operation undoes the clipping rectangle change caused by the corresponding drawMask() call.

    Parameters

    Returns void

excludeFromCache

  • Prevents the object from being drawn from the render cache in the next frame. Different to setRequiresRedraw(), this does not indicate that the object has changed in any way, but just that it doesn't support being drawn from cache.

    Note that when a container is excluded from the render cache, its children will still be cached! This just means that batching is interrupted at this object when the display tree is traversed.

    Parameters

    Returns void

fillToken

finishFrame

  • finishFrame(): void

finishMeshBatch

  • finishMeshBatch(): void

getProgram

  • getProgram(name: string): Program

Protected get_backBufferHeight

  • get_backBufferHeight(): number

Protected get_backBufferScaleFactor

  • get_backBufferScaleFactor(): number

Protected get_backBufferWidth

  • get_backBufferWidth(): number

Protected get_cacheEnabled

  • get_cacheEnabled(): boolean

Protected get_context

  • get_context(): Context3D

Protected get_contextValid

  • get_contextValid(): boolean

Protected get_drawCount

  • get_drawCount(): number

Protected get_enableErrorChecking

  • get_enableErrorChecking(): boolean

Protected get_frameID

  • get_frameID(): number

Protected get_pixelSize

  • get_pixelSize(): number

Protected get_profile

  • get_profile(): string

Protected get_programs

  • get_programs(): Map<string, Program>

Protected get_shareContext

  • get_shareContext(): boolean

Protected get_sharedData

  • get_sharedData(): Map<string, any>

Protected get_stage3D

  • get_stage3D(): Stage3D

Protected get_state

Protected get_stencilReferenceValue

  • get_stencilReferenceValue(): number

hasProgram

  • hasProgram(name: string): boolean

nextFrame

  • nextFrame(): void
  • Resets the current state, state stack, batch processor, stencil reference value, clipping rectangle, and draw count. Furthermore, depth testing is disabled.

    Returns void

popState

  • Restores the render state that was last pushed to the stack. If this changes blend mode, clipping rectangle, render target or culling, the current batch will be drawn right away.

    If you pass a BatchToken, it will be updated to point to the current location within the render cache. That way, you can later reference this location to render a subset of the cache.

    Parameters

    Returns void

prepareToDraw

  • prepareToDraw(): void
  • Applies all relevant state settings to at the render context. This includes blend mode, render target and clipping rectangle. Always call this method before context.drawTriangles().

    Returns void

present

  • present(): void

pushState

  • Pushes the current render state to a stack from which it can be restored later.

    If you pass a BatchToken, it will be updated to point to the current location within the render cache. That way, you can later reference this location to render a subset of the cache.

    Parameters

    Returns void

refreshBackBufferSize

  • refreshBackBufferSize(scaleFactor: number): void
  • Refreshes the values of "backBufferWidth" and "backBufferHeight" from the current context dimensions and stores the given "backBufferScaleFactor". This method is called by Starling when the browser zoom factor changes (in case "supportBrowserZoom" is enabled).

    Parameters

    • scaleFactor: number

    Returns void

registerProgram

  • registerProgram(name: string, program: Program): void

requestContext3D

  • requestContext3D(renderMode: string, profile: any): void
  • Requests a context3D object from the stage3D object. This is called by Starling internally during the initialization process. You normally don't need to call this method yourself. (For a detailed description of the parameters, look at the documentation of the method with the same name in the "RenderUtil" class.)

    @see starling.utils.RenderUtil

    Parameters

    • renderMode: string
    • profile: any

    Returns void

restoreState

  • restoreState(): void

setStateTo

  • setStateTo(transformationMatrix: Matrix, alphaFactor?: number, blendMode?: string): void
  • Modifies the current state with a transformation matrix, alpha factor, and blend mode.

    @param transformationMatrix Used to transform the current modelviewMatrix. @param alphaFactor Multiplied with the current alpha value. @param blendMode Replaces the current blend mode; except for "auto", which means the current value remains unchanged.

    Parameters

    • transformationMatrix: Matrix
    • Optional alphaFactor: number
    • Optional blendMode: string

    Returns void

Protected set_cacheEnabled

  • set_cacheEnabled(value: boolean): boolean

Protected set_drawCount

  • set_drawCount(value: number): number

Protected set_enableErrorChecking

  • set_enableErrorChecking(value: boolean): boolean

Protected set_frameID

  • set_frameID(value: number): number

Protected set_pixelSize

  • set_pixelSize(value: number): number

Protected set_shareContext

  • set_shareContext(value: boolean): boolean

Protected set_stencilReferenceValue

  • set_stencilReferenceValue(value: number): number

setupContextDefaults

  • setupContextDefaults(): void
  • Makes sure that the default context settings Starling relies on will be refreshed before the next 'draw' operation. This includes blend mode, culling, and depth test.

    Returns void

Generated using TypeDoc