starling-framework

import MeshSubset from "../utils/MeshSubset"; import RenderState from "./RenderState"; import Program from "./Program"; import BatchToken from "./BatchToken"; import Mesh from "../display/Mesh"; import DisplayObject from "../display/DisplayObject"; import Rectangle from "openfl/geom/Rectangle"; import Matrix from "openfl/geom/Matrix"; import Context3DRenderMode from "openfl/display3D/Context3DRenderMode"; import Context3D from "openfl/display3D/Context3D"; import Stage3D from "openfl/display/Stage3D"; declare namespace starling.rendering { /** * 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 <code>Starling.painter</code>. * * * * 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 <code>state</code> property. Use the methods * * <code>pushState</code> and <code>popState</code> to store a specific state and restore * * it later. That makes it easy to write rendering code that doesn't have any side effects. * * * * <listing> * * 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</listing> * * * * @see RenderState * */ export class 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. */ constructor(stage3D: Stage3D, sharedContext?: boolean); /** * The value with which the stencil buffer will be cleared, * * and the default reference value used for stencil tests. */ static DEFAULT_STENCIL_VALUE: number; /** * Disposes all mesh batches, programs, and - if it is not being shared - * * the render context. */ dispose(): 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 * */ requestContext3D(renderMode: Context3DRenderMode, profile: any): 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 <code>shareContext</code> 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. * * * * @param viewPort the position and size of the area that should be rendered * * into, in pixels. * * @param contentScaleFactor only relevant for Desktop (!) HiDPI screens. If you want * * to support high resolutions, pass the 'contentScaleFactor' * * of the Flash stage; otherwise, '1.0'. * * @param antiAlias from 0 (none) to 16 (very high quality). * * @param enableDepthAndStencil 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. * * @param supportBrowserZoom if enabled, zooming a website will adapt the size of * * the back buffer. * */ configureBackBuffer(viewPort: Rectangle, contentScaleFactor: number, antiAlias: number, enableDepthAndStencil: boolean, supportBrowserZoom?: boolean): void; /** * Registers a program under a certain name. * * If the name was already used, the previous program is overwritten. */ registerProgram(name: string, program: Program): void; /** * Deletes the program of a certain name. */ deleteProgram(name: string): void; /** * Returns the program registered under a certain name, or null if no program with * * this name has been registered. */ getProgram(name: string): Program; /** * Indicates if a program is registered under a certain name. */ hasProgram(name: string): boolean; /** * 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. * */ pushState(token?: BatchToken): void; /** * Modifies the current state with a transformation matrix, alpha factor, and blend mode. * * * * @param transformationMatrix Used to transform the current <code>modelviewMatrix</code>. * * @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. * */ setStateTo(transformationMatrix: Matrix, alphaFactor?: number, blendMode?: string): void; /** * 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. * */ popState(token?: BatchToken): void; /** * Restores the render state that was last pushed to the stack, but does NOT remove * * it from the stack. */ restoreState(): void; /** * Updates all properties of the given token so that it describes the current position * * within the render cache. */ fillToken(token: BatchToken): void; /** * 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 <code>starling.display.Quad</code> 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 <code>maskee</code>, the method will automatically * * call <code>excludeFromCache(maskee)</code> for you. * */ drawMask(mask: DisplayObject, maskee?: DisplayObject): void; /** * 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 <code>drawMask()</code> call. * */ eraseMask(mask: DisplayObject, maskee?: DisplayObject): void; /** * 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 <code>null</code>, the complete * * mesh will be used. * */ batchMesh(mesh: Mesh, subset?: MeshSubset): void; /** * Finishes the current mesh batch and prepares the next one. */ finishMeshBatch(): 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. * */ enableBatchTrimming(enabled?: boolean, interval?: number): void; /** * Completes all unfinished batches, cleanup procedures. */ finishFrame(): 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. */ setupContextDefaults(): void; /** * Resets the current state, state stack, batch processor, stencil reference value, * * clipping rectangle, and draw count. Furthermore, depth testing is disabled. */ nextFrame(): void; /** * Draws all meshes from the render cache between <code>startToken</code> and * * (but not including) <code>endToken</code>. The render cache contains all meshes * * rendered in the previous frame. */ drawFromCache(startToken: BatchToken, endToken: BatchToken): void; /** * Prevents the object from being drawn from the render cache in the next frame. * * Different to <code>setRequiresRedraw()</code>, 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. * */ excludeFromCache(object: DisplayObject): 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 * * <code>context.drawTriangles()</code>. * */ prepareToDraw(): 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'. */ clear(rgb?: number, alpha?: number): void; /** * Resets the render target to the back buffer and displays its contents. */ present(): 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). * */ refreshBackBufferSize(scaleFactor: number): void; /** * Indicates the number of stage3D draw calls. */ get drawCount(): number; set drawCount(value: 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! * */ get stencilReferenceValue(): number; set stencilReferenceValue(value: number) /** * 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 * */ get cacheEnabled(): boolean; set cacheEnabled(value: boolean) /** * 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. * */ get state(): RenderState; /** * The Stage3D instance this painter renders into. */ get stage3D(): Stage3D; /** * The Context3D instance this painter renders into. */ get context(): Context3D; /** * 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 * * <code>Starling.frameID</code> instead. */ get frameID(): number; set frameID(value: number) /** * The size (in points) that represents one pixel in the back buffer. */ get pixelSize(): number; set pixelSize(value: number) /** * Indicates if another Starling instance (or another Stage3D framework altogether) * * uses the same render context. @default false */ get shareContext(): boolean; set shareContext(value: boolean) /** * Indicates if Stage3D render methods will report errors. Activate only when needed, * * as this has a negative impact on performance. @default false */ get enableErrorChecking(): boolean; set enableErrorChecking(value: boolean) /** * 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 'backBufferScaleFactor' * * for the actual pixel count. Alternatively, use the Context3D-property with the * * same name: it will return the exact pixel values. */ get backBufferWidth(): 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 'backBufferScaleFactor' * * for the actual pixel count. Alternatively, use the Context3D-property with the * * same name: it will return the exact pixel values. */ get backBufferHeight(): 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'. */ get backBufferScaleFactor(): number; /** * Indicates if the Context3D object is currently valid (i.e. it hasn't been lost or * * disposed). */ get contextValid(): boolean; /** * The Context3D profile of the current render context, or <code>null</code> * * if the context has not been created yet. */ get profile(): string; /** * 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. */ get sharedData(): any; } } export default starling.rendering.Painter;