The Stage3D texture object the texture is based on.
The Context3DTextureFormat
of the underlying texture data.
The texture frame if it has one (see class description), otherwise null
.
CAUTION: not a copy, but the actual object! Do not modify!
The width of the texture in points, taking into account the frame rectangle (if there is one).
The height of the texture in points, taking into account the frame rectangle (if there is one).
The height of the texture in points.
Indicates if the texture contains mip maps.
The height of the texture in pixels (without scale adjustment).
The width of the texture in pixels (without scale adjustment).
Indicates if the alpha values are premultiplied into the RGB values.
The concrete texture the texture is based on.
The scale factor, which influences width and height properties.
The matrix that is used to transform the texture coordinates into the coordinate space of the parent texture, if there is one. @default null
CAUTION: not a copy, but the actual object! Never modify this matrix!
The matrix that is used to transform the texture coordinates into the coordinate space of the root texture, if this instance is not the root. @default null
CAUTION: not a copy, but the actual object! Never modify this matrix!
The width of the texture in points.
Indicates if it should be attempted to upload bitmaps asynchronously when the async
parameter
is supplied to supported methods. Since this feature is still not 100% reliable in AIR 26 (especially on
Android), it defaults to 'false' for now.
If the feature is disabled or not available in the current AIR/Flash runtime, the async callback will still be executed; however, the upload itself will be made synchronously.
Returns the maximum size constraint (for both width and height) for uncompressed textures in the current Context3D profile.
Disposes the underlying texture data. Note that not all textures need to be disposed: SubTextures (created with 'Texture.fromTexture') just reference other textures and and do not take up resources themselves; this is also true for textures from an atlas.
Reads a pair of texture coordinates from the given VertexData instance and transforms them into the current texture's coordinate system. (Remember, the VertexData instance will always contain the coordinates in the root texture's coordinate system!)
Transforms the given texture coordinates from the root texture's coordinate system to the local coordinate system.
Transforms the given texture coordinates from the local coordinate system into the root texture's coordinate system.
Writes the given texture coordinates to a VertexData instance after transforming them into the root texture's coordinate system. That way, the texture coordinates can be used directly to sample the texture in the fragment shader.
Sets up a VertexData instance with the correct texture coordinates for 4 vertices so that the texture is mapped to the complete quad.
@param vertexData the vertex data to which the texture coordinates will be written. @param vertexID the start position within the VertexData instance. @param attrName the attribute name referencing the vertex positions.
Sets up a VertexData instance with the correct positions for 4 vertices so that
the texture can be mapped onto it unscaled. If the texture has a frame
,
the vertices will be offset accordingly.
@param vertexData the VertexData instance to which the positions will be written. @param vertexID the start position within the VertexData instance. @param attrName the attribute name referencing the vertex positions. @param bounds useful only for textures with a frame. This will position the vertices at the correct position within the given bounds, distorted appropriately.
Creates an empty texture of a certain size. Beware that the texture can only be used after you either upload some color data ("texture.root.upload...") or clear the texture ("texture.root.clear()").
@param width in points; number of pixels depends on scale parameter @param height in points; number of pixels depends on scale parameter @param premultipliedAlpha the PMA format you will use the texture with. If you will use the texture for bitmap data, use "true"; for ATF data, use "false". @param mipMapping indicates if mipmaps should be used for this texture. When you upload bitmap data, this decides if mipmaps will be created; when you upload ATF data, this decides if mipmaps inside the ATF file will be displayed. @param optimizeForRenderToTexture indicates if this texture will be used as render target @param scale if you omit this parameter, 'Starling.contentScaleFactor' will be used. @param format the context3D texture format to use. Pass one of the packed or compressed formats to save memory (at the price of reduced image quality). @param forcePotTexture indicates if the underlying Stage3D texture should be created as the power-of-two based "Texture" class instead of the more memory efficient "RectangleTexture".
Creates a texture from ATF data (Adobe Texture Compression). Beware: you must not dispose 'data' if Starling should handle a lost device context; alternatively, you can handle restoration yourself via "texture.root.onRestore".
@param data the raw data from an ATF file.
@param scale the scale factor of the created texture. This affects the reported
width and height of the texture object.
@param useMipMaps If the ATF data contains mipmaps, this parameter controls if they
are used; if it does not, this parameter has no effect.
@param async If you pass a callback function, the texture will be decoded
asynchronously, which allows a smooth framerate even during the
loading process. However, don't use the texture before the callback
has been executed. This is the expected definition:
function(texture:Texture):void;
@param premultipliedAlpha Indicates if the ATF data contains pixels in PMA format.
This is "false" for most ATF files, but can be customized in some
tools.
Creates a texture object from a bitmap. Beware: you must not dispose the bitmap's data if Starling should handle a lost device context (except if you handle restoration yourself via "texture.root.onRestore").
@param bitmap the texture will be created with the bitmap data of this object.
@param generateMipMaps indicates if mipMaps will be created.
@param optimizeForRenderToTexture indicates if this texture will be used as
render target
@param scale the scale factor of the created texture. This affects the reported
width and height of the texture object.
@param format the context3D texture format to use. Pass one of the packed or
compressed formats to save memory (at the price of reduced image
quality).
@param forcePotTexture indicates if the underlying Stage3D texture should be created
as the power-of-two based "Texture" class instead of the more memory
efficient "RectangleTexture".
@param async If you pass a callback function, the texture will be uploaded
asynchronously, which allows smooth rendering even during the
loading process. However, don't use the texture before the callback
has been executed. This is the expected definition:
function(texture:Texture, error:ErrorEvent):void;
The second parameter is optional and typically null
.
Creates a texture object from bitmap data. Beware: you must not dispose 'data' if Starling should handle a lost device context (except if you handle restoration yourself via "texture.root.onRestore").
@param data the bitmap data to upload to the texture.
@param generateMipMaps indicates if mipMaps will be created.
@param optimizeForRenderToTexture indicates if this texture will be used as
render target
@param scale the scale factor of the created texture. This affects the reported
width and height of the texture object.
@param format the context3D texture format to use. Pass one of the packed or
compressed formats to save memory (at the price of reduced image
quality).
@param forcePotTexture indicates if the underlying Stage3D texture should be created
as the power-of-two based "Texture" class instead of the more memory
efficient "RectangleTexture".
@param async If you pass a callback function, the texture will be uploaded
asynchronously, which allows smooth rendering even during the
loading process. However, don't use the texture before the callback
has been executed. This is the expected definition:
function(texture:Texture, error:ErrorEvent):void;
The second parameter is optional and typically null
.
Creates a texture with a certain size and color.
@param width in points; number of pixels depends on scale parameter @param height in points; number of pixels depends on scale parameter @param color the RGB color the texture will be filled up @param alpha the alpha value that will be used for every pixel @param optimizeForRenderToTexture indicates if this texture will be used as render target @param scale if you omit this parameter, 'Starling.contentScaleFactor' will be used. @param format the context3D texture format to use. Pass one of the packed or compressed formats to save memory. @param forcePotTexture indicates if the underlying Stage3D texture should be created as the power-of-two based "Texture" class instead of the more memory efficient "RectangleTexture".
Creates a texture from any of the supported data types, using the specified options.
@param data Either an embedded asset class, a Bitmap, BitmapData, or a ByteArray with ATF data. @param options Specifies options about the texture settings, e.g. the scale factor. If left empty, the default options will be used.
Creates a texture object from an embedded asset class. Textures created with this method will be restored directly from the asset class in case of a context loss, which guarantees a very economic memory usage.
@param assetClass must contain either a Bitmap or a ByteArray with ATF data. @param mipMapping for Bitmaps, indicates if mipMaps will be created; for ATF data, indicates if the contained mipMaps will be used. @param optimizeForRenderToTexture indicates if this texture will be used as render target. @param scale the scale factor of the created texture. @param format the context3D texture format to use. Ignored for ATF data. @param forcePotTexture indicates if the underlying Stage3D texture should be created as the power-of-two based "Texture" class instead of the more memory efficient "RectangleTexture". (Only applicable to bitmaps; ATF textures are always POT-textures, anyway.)
Creates a video texture from a NetStream.
Below, you'll find a minimal sample showing how to stream a video from a file.
Note that ns.play()
is called only after creating the texture, and
outside the onComplete
-callback. It's recommended to always make the
calls in this order; otherwise, playback won't start on some platforms.
@param stream the NetStream from which the video data is streamed. Beware that 'play'
should be called only after the method returns, and outside the
onComplete
callback.
@param scale the scale factor of the created texture. This affects the reported
width and height of the texture object.
@param onComplete will be executed when the texture is ready. Contains a parameter
of type 'Texture'.
Creates a texture that contains a region (in pixels) of another texture. The new texture will reference the base texture; no data is duplicated.
@param texture The texture you want to create a SubTexture from. @param region The region of the parent texture that the SubTexture will show (in points). @param frame If the texture was trimmed, the frame rectangle can be used to restore the trimmed area. @param rotated If true, the SubTexture will show the parent region rotated by 90 degrees (CCW). @param scaleModifier The scale factor of the new texture will be calculated by multiplying the parent texture's scale factor with this value.
Creates a texture from a TextureBase
object.
@param base a Stage3D texture object created through the current context. @param width the width of the texture in pixels (not points!). @param height the height of the texture in pixels (not points!). @param options specifies options about the texture settings, e.g. the scale factor. If left empty, the default options will be used. Note that not all options are supported by all texture types.
Generated using TypeDoc
A texture stores the information that represents an image. It cannot be added to the display list directly; instead it has to be mapped onto a display object. In Starling, the most probably candidate for this job is the
Image
class.Creating a texture
The
Texture
class is abstract, i.e. you cannot create instance of this class through its constructor. Instead, it offers a variety of factory methods, likefromBitmapData
orfromEmbeddedAsset
.Texture Formats
Since textures can be created from a "BitmapData" object, Starling supports any bitmap format that is supported by Flash. And since you can render any Flash display object into a BitmapData object, you can use this to display non-Starling content in Starling - e.g. Shape objects.
Starling also supports ATF textures (Adobe Texture Format), which is a container for compressed texture formats that can be rendered very efficiently by the GPU. Refer to the Flash documentation for more information about this format.
Beginning with AIR 17, you can use Starling textures to show video content (if the current platform supports it; see "SystemUtil.supportsVideoTexture"). The two factory methods "fromCamera" and "fromNetStream" allow you to make use of this feature.
Mip Mapping
MipMaps are scaled down versions of a texture. When an image is displayed smaller than its natural size, the GPU may display the mip maps instead of the original texture. This reduces aliasing and accelerates rendering. It does, however, also need additional memory; for that reason, mipmapping is disabled by default.
Texture Frame
The frame property of a texture allows you to let a texture appear inside the bounds of an image, leaving a transparent border around the texture. The frame rectangle is specified in the coordinate system of the texture (not the image):
This code would create an image with a size of 30x30, with the texture placed at
x=10, y=10
within that image (assuming that 'anotherTexture' has a width and height of 10 pixels, it would appear in the middle of the image).The texture atlas makes use of this feature, as it allows to crop transparent edges of a texture and making up for the changed size by specifying the original texture frame. Tools like TexturePacker use this to optimize the atlas.
Texture Coordinates
If, on the other hand, you want to show only a part of the texture in an image (i.e. to crop the the texture), you can either create a subtexture (with the method 'Texture.fromTexture()' and specifying a rectangle for the region), or you can manipulate the texture coordinates of the image object. The method
image.setTexCoords
allows you to do that.Context Loss
When the current rendering context is lost (which can happen on all platforms, but is especially common on Android and Windows), all texture data is destroyed. However, Starling will try to restore the textures. To do that, it will keep the bitmap and ATF data in memory - at the price of increased RAM consumption. You can optimize this behavior, though, by restoring the texture directly from its source, like in this example:
The
onRestore
-method will be called when the context was lost and the texture has been recreated (but is still empty). If you use the "AssetManager" class to manage your textures, this will be done automatically.@see starling.display.Image @see starling.utils.AssetManager @see starling.utils.SystemUtil @see TextureAtlas