Creates a new mesh with the given vertices and indices.
If you don't pass a style, an instance of MeshStyle
will be created
for you. Note that the format of the vertex data will be matched to the
given style right away.
The opacity of the object. 0 = transparent, 1 = opaque. @default 1
The topmost object in the display tree the object is part of.
The blend mode determines how the object is blended with the objects underneath.
The bounds of the object relative to the local coordinates of the parent.
Changes the color of all vertices to the same value. The getter simply returns the color of the first vertex.
The filter that is attached to the display object. The starling.filters
package contains several classes that define specific filters you can use. To combine
several filters, assign an instance of the FilterChain
class; to remove
all filters, assign null
.
Beware that a filter instance may only be used on one object at a time! Furthermore, when you remove or replace a filter, it is NOT disposed automatically (since you might want to reuse it on a different object).
@default null @see starling.filters.FragmentFilter @see starling.filters.FilterChain
The height of the object in pixels. Note that for objects in a 3D space (connected to a Sprite3D), this value might not be accurate until the object is part of the display list.
The index data describing how the vertices are interconnected.
Any change requires a call to setRequiresRedraw
.
Indicates if this object or any of its parents is a 'Sprite3D' object.
The display object that acts as a mask for the current object.
Assign null
to remove it.
A pixel of the masked display object will only be drawn if it is within one of the mask's polygons. Texture pixels and alpha values of the mask are not taken into account. The mask object itself is never visible.
If the mask is part of the display list, masking will occur at exactly the location it occupies on the stage. If it is not, the mask will be placed in the local coordinate system of the target object (as if it was one of its children).
For rectangular masks, you can use simple quads; for other forms (like circles or arbitrary shapes) it is recommended to use a 'Canvas' instance.
Note: a mask will typically cause at least two additional draw
calls: one to draw the mask to the stencil buffer and one to erase it. However, if the
mask object is an instance of starling.display.Quad
and is aligned
parallel to the stage axes, rendering will be optimized: instead of using the
stencil buffer, the object will be clipped using the scissor rectangle. That's
faster and reduces the number of draw calls, so make use of this when possible.
Note: AIR apps require the depthAndStencil
node
in the application descriptor XMLs to be enabled! Otherwise, stencil masking won't
work.
@see Canvas @default null
Indicates if the masked region of this object is set to be inverted.
The name of the display object (default: null). Used by 'getChildByName()' of display object containers.
The total number of indices referencing vertices.
The total number of triangles in this mesh. (In other words: the number of indices divided by three.)
The total number of vertices in the mesh.
The display object container that contains this display object.
The x coordinate of the object's origin in its own coordinate space (default: 0).
The y coordinate of the object's origin in its own coordinate space (default: 0).
Controls whether or not the instance snaps to the nearest pixel. This can prevent the object from looking blurry when it's not exactly aligned with the pixels of the screen. @default false
Indicates if the object needs to be redrawn in the upcoming frame, i.e. if it has changed its location relative to the stage or some other aspect of its appearance since it was last rendered.
The root object the display object is connected to (i.e. an instance of the class that was passed to the Starling constructor), or null if the object is not connected to the stage.
The rotation of the object in radians. (In Starling, all angles are measured in radians.)
Sets both 'scaleX' and 'scaleY' to the same value. The getter simply returns the value of 'scaleX' (even if the scaling values are different). @default 1
The horizontal scale factor. '1' means no scale, negative values flip the object.
The vertical scale factor. '1' means no scale, negative values flip the object.
The horizontal skew angle in radians.
The vertical skew angle in radians.
The stage the display object is connected to, or null if it is not connected to the stage.
The style that is used to render the mesh. Styles (which are always subclasses of
MeshStyle
) provide a means to completely modify the way a mesh is rendered.
For example, they may add support for color transformations or normal mapping.
Beware: a style instance may only be used on one mesh at a time.
@default MeshStyle @see #setStyle()
The texture that is mapped to the mesh (or null
, if there is none).
Indicates if pixels at the edges will be repeated or clamped. Only works for
power-of-two textures; for a solution that works with all kinds of textures,
see Image.tileGrid
. @default false
The smoothing filter that is used for the texture. @default bilinear
Indicates if this object (and its children) will receive touch events.
The transformation matrix of the object relative to its parent.
If you assign a custom transformation matrix, Starling will try to figure out
suitable values for x, y, scaleX, scaleY,
and rotation
.
However, if the matrix was created in a different way, this might not be possible.
In that case, Starling will apply the matrix, but not update the corresponding
properties.
CAUTION: not a copy, but the actual object!
The 3D transformation matrix of the object relative to its parent.
For 2D objects, this property returns just a 3D version of the 2D transformation matrix. Only the 'Sprite3D' class supports real 3D transformations.
CAUTION: not a copy, but the actual object!
Indicates if the mouse cursor should transform into a hand while it's over the sprite.
The vertex data describing all vertices of the mesh.
Any change requires a call to setRequiresRedraw
.
The format used to store the vertices.
The visibility of the object. An invisible object will be untouchable.
The width of the object in pixels. Note that for objects in a 3D space (connected to a Sprite3D), this value might not be accurate until the object is part of the display list.
The x coordinate of the object relative to the local coordinates of the parent.
The y coordinate of the object relative to the local coordinates of the parent.
The default style used for meshes if no specific style is provided. The default is
starling.rendering.MeshStyle
, and any assigned class must be a subclass
of the same.
A factory method that is used to create the 'MeshStyle' for a mesh if no specific
style is provided. That's useful if you are creating a hierarchy of objects, all
of which need to have a certain style. Different to the defaultStyle
property, this method allows plugging in custom logic and passing arguments to the
constructor. Return null
to fall back to the default behavior (i.e.
to instantiate defaultStyle
). The mesh
-parameter is optional
and may be omitted.
Moves the pivot point to a certain position within the local coordinate system of the object. If you pass no arguments, it will be centered.
Dispatches an event to all objects that have registered listeners for its type. If an event with enabled 'bubble' property is dispatched to a display object, it will travel up along the line of parents, until it either hits the root object or someone stops its propagation manually.
Dispatches an event with the given parameters to all objects that have registered listeners for the given type. The method uses an internal pool of event objects to avoid allocations.
Draws the object into a BitmapData object.
This is achieved by drawing the object into the back buffer and then copying the pixels of the back buffer into a texture. This also means that the returned bitmap data cannot be bigger than the current viewPort.
@param out If you pass null, the object will be created for you. If you pass a BitmapData object, it should have the size of the object bounds, multiplied by the current contentScaleFactor. @param color The RGB color value with which the bitmap will be initialized. @param alpha The alpha value with which the bitmap will be initialized.
Returns the texture coordinates of the vertex at the specified index.
Creates a matrix that represents the transformation from the local coordinate system
to another. If you pass an out
-matrix, the result will be stored in this matrix
instead of creating a new object.
Creates a matrix that represents the transformation from the local coordinate system
to another. This method supports three dimensional objects created via 'Sprite3D'.
If you pass an out
-matrix, the result will be stored in this matrix
instead of creating a new object.
Returns the alpha value of the vertex at the specified index.
Returns the RGB color of the vertex at the specified index.
The position of the vertex at the specified index, in the mesh's local coordinate system.
Only modify the position of a vertex if you know exactly what you're doing, as
some classes might not work correctly when their vertices are moved. E.g. the
Quad
class expects its vertices to spawn up a perfectly rectangular
area; some of its optimized methods won't work correctly if that premise is no longer
fulfilled or the original bounds change.
Transforms a point from global (stage) coordinates to the local coordinate system.
If you pass an out
-point, the result will be stored in this point instead of
creating a new object.
Transforms a point from global (stage) coordinates to the 3D local coordinate system.
If you pass an out
-vector, the result will be stored in this point instead of
creating a new object.
If called with one argument, figures out if there are any listeners registered for the given event type. If called with two arguments, also determines if a specific listener is registered.
Checks if a certain point is inside the display object's mask. If there is no mask,
this method always returns true
(because having no mask is equivalent
to having one that's infinitely big).
Transforms a 3D point from the local coordinate system to global (stage) coordinates. This is achieved by projecting the 3D point onto the (2D) view plane.
If you pass an out
-point, the result will be stored in this point instead of
creating a new object.
Transforms a point from the local coordinate system to global (stage) coordinates.
If you pass an out
-point, the result will be stored in this point instead of
creating a new object.
Removes the object from its parent, if it has one, and optionally disposes it.
This method is called whenever the mesh's index data was changed.
The base implementation simply forwards to setRequiresRedraw
.
Forces the object to be redrawn in the next frame. This will prevent the object to be drawn from the render cache.
This method is called every time the object changes in any way. When creating custom mesh styles or any other custom rendering code, call this method if the object needs to be redrawn.
If the object needs to be redrawn just because it does not support the render cache,
call painter.excludeFromCache()
in the object's render method instead.
That way, Starling's skipUnchangedFrames
policy won't be disrupted.
Sets the style that is used to render the mesh. Styles (which are always subclasses of
MeshStyle
) provide a means to completely modify the way a mesh is rendered.
For example, they may add support for color transformations or normal mapping.
When assigning a new style, the vertex format will be changed to fit it.
Do not use the same style instance on multiple objects! Instead, make use of
style.clone()
to assign an identical style to multiple meshes.
@param meshStyle the style to assign. If null
, the default
style will be created.
@param mergeWithPredecessor if enabled, all attributes of the previous style will be
be copied to the new one, if possible.
@see #defaultStyle
@see #defaultStyleFactory
Sets the texture coordinates of the vertex at the specified index to the given values.
Sets the alpha value of the vertex at the specified index to a certain value.
Sets the RGB color of the vertex at the specified index to a certain value.
This method is called whenever the mesh's vertex data was changed.
The base implementation simply forwards to setRequiresRedraw
.
Generated using TypeDoc
The base class for all tangible (non-container) display objects, spawned up by a number of triangles.
Since Starling uses Stage3D for rendering, all rendered objects must be constructed from triangles. A mesh stores the information of its triangles through VertexData and IndexData structures. The default format stores position, color and texture coordinates for each vertex.
How a mesh is rendered depends on its style. Per default, this is an instance of the
MeshStyle
base class; however, subclasses may extend its behavior to add support for color transformations, normal mapping, etc.@see MeshBatch @see starling.styles.MeshStyle @see starling.rendering.VertexData @see starling.rendering.IndexData