Creates a new canvas with a starting width and height, setting CanvasViewport#canvas and Viewport#context. Failure to get a canvas context results in an exception.
Texture bleeding prevention should be enabled for CanvasViewports that are used as the output (top-most) Viewport, but only if the Viewport will be used in a 3D engine. If used in, for example, a DOMRoot, then there should be no texture bleeding issues, so texture bleeding prevention is disabled for DOMRoots. For engines like Wonderland Engine, texture bleeding prevention is enabled.
Should not be used in nested Viewports as there are no texture bleeding issues in nested Viewports; it technically can be enabled, but it would be a waste of resources.
Protected_forceDoes the canvas size need to be updated? For internal use only.
Private_maxCurrent maximum canvas height. For internal use only.
Private_maxCurrent maximum canvas width. For internal use only.
Private_prevESXPrevious horizontal effective scale. For internal use only.
Private_prevESYPrevious vertical effective scale. For internal use only.
ReadonlycanvasThe internal canvas. Widgets are painted to this
ReadonlychildThe Viewport's child. Painting and layout will be relative to this.
Layout constraints of viewport when resolving widget's layout. A 4-tuple containing, respectively, minimum width, maximum width, minimum height and maximum height.
By default, has no minimum width nor height and unconstrained maximum width and height.
ReadonlycontextThe render target's (canvas) 2D context. Alpha is enabled.
Note that readonly in this context means that this property is a getter, not that it is immutable. Ideally, this is a getter that gets the current rendering context. Some Viewport implementations (such as CanvasViewport) will always use the same context, while others (such as ClippedViewport) will occasionally change the context.
Private ReadonlydirtyThe list of dirty rectangles, relative to the internal canvas.
ProtectedforceShould the layout be resolved, even if the child widget doesn't have a dirty layout?
The offset of the child inside the Viewport. Depending on the Viewport implementation, this may update the actual position of the child Widget, or it may just affect how the paint method behaves.
The parent Viewport of this Viewport. Since positions are relative to this, absolute positions can be calculated by following all the parents.
If null, this is the topmost Viewport and owned by the UI Root.
Should be set by the owner when the owner is attached or detached.
ReadonlypreventIs texture atlas bleeding prevention enabled? If true, then a 1 pixel fully transparent black border will be added around the canvas, effectively reducing the usable canvas by 2 pixels horizontally and vertically.
Can only be set on CanvasViewport creation.
Is texture bleeding prevention enabled? If true, then out-of-bounds old painted Widgets that were kept because of the canvas shrinking will be cleared after the paint method is called.
Can be changed at any time, but will only take effect once the Viewport#child Widget is re-painted.
The actual dimensions and position of the viewport, relative to the parent Viewport (or the UI Root if there is no parent Viewport, meaning that positions are absolute in that case); for example, this would be the equivalent to an iframe's dimensions and position (the HTML body in the iframe can have different dimensions than the iframe itself and be scrolled by some amount).
Do not use this value for resolving the layout. Only use this for event handling or other logic that doesn't affect layout.
Should be set by the owner of the Viewport (a Root or a ViewportWidget) when finalizing layout.
ReadonlyrelativeThe coordinate system used for this Viewport. If true, then coordinates are relative to the Viewport itself (Viewport#child always has a position of 0,0). If false, then coordinates are absolute (relative to the nearest relative parent Viewport, or topmost Viewport, or 0,0 if this is the topmost Viewport).
The resolution of the canvas. If possible, the canvas will be scaled by this amount.
PrivateshrunkHas the "real" size of the child Widget in the canvas shrunk? Used for texture bleeding prevention. For internal use only.
Will be ignored if CanvasViewport#preventBleeding is false.
Protected StaticdimensionlessHas the warning for dimensionless canvases been issued?
Protected StaticmaxThe maximum retries allowed for resolving the layout. The first attempt is not counted. Only retries that exceed this limit are discarded; if maxRelayout is 4, then the 5th retry will be discarded.
Protected StaticpowerHas the warning for non-power of 2 dimensions been issued?
The current dimensions of the internal canvas
Get the canvas scale that will be applied to the Viewport's child. Used for checking whether a child's dimensions exceeds a canvas' maximum dimensions.
Note that readonly in this context means that this property is a getter, not that it is immutable. Ideally, this is a getter that calculates the effective scale of the viewport via the canvas dimensions and max dimensions, which may returns different values, not the same value every time.
The maximum height the CanvasViewport#canvas can have. If the layout exceeds this height, then the content will be scaled to fit the canvas.
Non-integer numbers will be rounded.
The maximum width the CanvasViewport#canvas can have. If the layout exceeds this width, then the content will be scaled to fit the canvas.
Non-integer numbers will be rounded.
PrivaterealThe "real" dimensions of the child Widget; the dimensions that the child Widget occupies in the canvas, taking resolution and maximum canvas dimensions into account.
The current usable dimensions of the internal canvas. If CanvasViewport#preventAtlasBleeding is false, then this will be equivalent to CanvasViewport#canvasDimensions.
The usable maximum height of the internal canvas. If CanvasViewport#preventAtlasBleeding is false, then this will be equivalent to CanvasViewport#maxCanvasHeight.
The usable maximum width of the internal canvas. If CanvasViewport#preventAtlasBleeding is false, then this will be equivalent to CanvasViewport#maxCanvasWidth.
PrivateclipAdd a clipping rectangle to the internal canvas context.
Dispatch an event to the Viewport's Viewport#child. Only TricklingEvent is supported.
The event to dispatch down the UI tree
Returns the widget that captured the event or null if none captured the event.
Get the rect of the child alongside more extra information, clipped/clamped to the bounds of the viewport. Usually only for internal, but can be used externally if you know what you're doing.
Mark a rectangle relative to this viewport as dirty.
A rectangle with the area that was marked as dirty
ProtectedmergedPaint the Viewport#child to the Viewport#context and, if it makes sense to do so, paint to the Viewport#parent Viewport's context.
Nothing is done if the child was not re-painted.
Note that, unlike other Viewport implementations, this implementation doesn't actually need to have extraDirtyRects passed; an empty array will suffice, assuming you're marking dirty regions with CanvasViewport#pushDirtyRects.
Ignored in this Viewport implementation, but would otherwise have the damage regions that need to be repainted.
Returns true if the child was re-painted, else, false.
Implements Viewport#paint, but only paints to the internal canvas. Call this instead of Viewport#paint if you are using this Viewport's canvas as the output canvas (such as in the Root).
Paints the internal canvas to the parent viewport. Note that you are assumed to have already called CanvasViewport#paintToInternal, and must pass the ClippedViewportRect from CanvasViewport#getClippedViewportRect.
You probably don't need to call this. Check CanvasViewport#paint instead.
Resolves the Viewport child's layout (including position) in one call, using the previous position.
May resize or rescale the canvas.
Expands CanvasViewport#canvas if the new layout is too big for the current canvas. Expansion is done in powers of 2 to avoid issues with external 3D libraries.
Returns true if the widget or canvas were resized, or the canvas rescaled, else, false.
A Viewport with an internal canvas, where the rendering context used for the Viewport is the internal canvas' context instead of an inherited context from a parent Viewport.
Mostly used as the top-most Viewport, such as the Viewport in a Root.
Coordinates are relative to the internal canvas, instead of absolute. Because of this, viewport contents may be blurred if the position of the viewport is fractional.