Options
All
  • Public
  • Public/Protected
  • All
Menu

Class VertexData

The VertexData class manages a raw list of vertex information, allowing direct upload to Stage3D vertex buffers. You only have to work with this class if you're writing your own rendering code (e.g. if you create custom display objects).

To render objects with Stage3D, you have to organize vertices and indices in so-called vertex- and index-buffers. Vertex buffers store the coordinates of the vertices that make up an object; index buffers reference those vertices to determine which vertices spawn up triangles. Those buffers reside in graphics memory and can be accessed very efficiently by the GPU.

Before you can move data into the buffers, you have to set it up in conventional memory — that is, in a Vector or a ByteArray. Since it's quite cumbersome to manually create and manipulate those data structures, the IndexData and VertexData classes provide a simple way to do just that. The data is stored sequentially (one vertex or index after the other) so that it can easily be uploaded to a buffer.

Vertex Format

The VertexData class requires a custom format string on initialization, or an instance of the VertexDataFormat class. Here is an example:

vertexData = new VertexData("position:number2, color:bytes4"); vertexData.setPoint(0, "position", 320, 480); vertexData.setColor(0, "color", 0xff00ff);

This instance is set up with two attributes: "position" and "color". The keywords after the colons depict the format and size of the data that each property uses; in this case, we store two floats for the position (for the x- and y-coordinates) and four bytes for the color. Please refer to the VertexDataFormat documentation for details.

The attribute names are then used to read and write data to the respective positions inside a vertex. Furthermore, they come in handy when copying data from one VertexData instance to another: attributes with equal name and data format may be transferred between different VertexData objects, even when they contain different sets of attributes or have a different layout.

Colors

Always use the format bytes4 for color data. The color access methods expect that format, since it's the most efficient way to store color data. Furthermore, you should always include the string "color" (or "Color") in the name of color data; that way, it will be recognized as such and will always have its value pre-filled with pure white at full opacity.

Premultiplied Alpha

Per default, color values are stored with premultiplied alpha values, which means that the rgb values were multiplied with the alpha values before saving them. You can change this behavior with the premultipliedAlpha property.

Beware: with premultiplied alpha, the alpha value always affects the resolution of the RGB channels. A small alpha value results in a lower accuracy of the other channels, and if the alpha value reaches zero, the color information is lost altogether.

Tinting

Some low-end hardware is very sensitive when it comes to fragment shader complexity. Thus, Starling optimizes shaders for non-tinted meshes. The VertexData class keeps track of its tinted-state, at least at a basic level: whenever you change color or alpha value of a vertex to something different than white (0xffffff) with full alpha (1.0), the tinted property is enabled.

However, that value is not entirely accurate: when you restore the color of just a range of vertices, or copy just a subset of vertices to another instance, the property might wrongfully indicate a tinted mesh. If that's the case, you can either call updateTinted() or assign a custom value to the tinted-property.

@see VertexDataFormat @see IndexData

Hierarchy

  • VertexData

Index

Constructors

constructor

  • new VertexData(format?: any, initialCapacity?: number): VertexData
  • Creates an empty VertexData object with the given format and initial capacity.

    @param format

    Either a VertexDataFormat instance or a String that describes the data format. Refer to the VertexDataFormat class for more information. If you don't pass a format, the default MeshStyle.VERTEX_FORMAT will be used.

    @param initialCapacity

    The initial capacity affects just the way the internal ByteArray is allocated, not the numIndices value, which will always be zero when the constructor returns. The reason for this behavior is the peculiar way in which ByteArrays organize their memory:

    The first time you set the length of a ByteArray, it will adhere to that: a ByteArray with length 20 will take up 20 bytes (plus some overhead). When you change it to a smaller length, it will stick to the original value, e.g. with a length of 10 it will still take up 20 bytes. However, now comes the weird part: change it to anything above the original length, and it will allocate 4096 bytes!

    Thus, be sure to always make a generous educated guess, depending on the planned usage of your VertexData instances.

    Parameters

    • Optional format: any
    • Optional initialCapacity: number

    Returns VertexData

Properties

format

The format that describes the attributes of each vertex. When you assign a different format, the raw data will be converted accordingly, i.e. attributes with the same name will still point to the same data. New properties will be filled up with zeros (except for colors, which will be initialized with an alpha value of 1.0). As a side-effect, the instance will also be trimmed.

formatString

formatString: string

The format string that describes the attributes of each vertex.

numVertices

numVertices: number

The total number of vertices. If you make the object bigger, it will be filled up with 1.0 for all alpha values and zero for everything else.

premultipliedAlpha

premultipliedAlpha: boolean

Indicates if color attributes should be stored premultiplied with the alpha value. Changing this value does not modify any existing color data. If you want that, use the setPremultipliedAlpha method instead. @default true

rawData

rawData: ByteArray

The raw vertex data; not a copy!

size

size: number

The size (in bytes) of the raw vertex data.

sizeIn32Bits

sizeIn32Bits: number

The size (in 32 bit units) of the raw vertex data.

tinted

tinted: boolean

Indicates if the mesh contains any vertices that are not white or not fully opaque. If false (and the value wasn't modified manually), the result is 100% accurate; true represents just an educated guess. To be entirely sure, you may call updateTinted().

vertexSize

vertexSize: number

The size (in bytes) of each vertex.

vertexSizeIn32Bits

vertexSizeIn32Bits: number

The size (in 32 bit units) of each vertex.

Methods

clear

  • clear(): void

clone

colorize

  • colorize(attrName?: string, color?: number, alpha?: number, vertexID?: number, numVertices?: number): void
  • Writes the given RGB and alpha values to the specified vertices.

    Parameters

    • Optional attrName: string
    • Optional color: number
    • Optional alpha: number
    • Optional vertexID: number
    • Optional numVertices: number

    Returns void

copyAttributeTo

  • copyAttributeTo(target: VertexData, targetVertexID: number, attrName: string, matrix?: Matrix, vertexID?: number, numVertices?: number): void
  • Copies a specific attribute of all contained vertices (or a range of them, defined by 'vertexID' and 'numVertices') to another VertexData instance. Beware that both name and format of the attribute must be identical in source and target. If the target is not big enough, it will be resized to fit all the new vertices.

    If you pass a non-null matrix, the specified attribute will be transformed by that matrix before storing it in the target object. It must consist of two float values.

    Parameters

    • target: VertexData
    • targetVertexID: number
    • attrName: string
    • Optional matrix: Matrix
    • Optional vertexID: number
    • Optional numVertices: number

    Returns void

copyTo

  • copyTo(target: VertexData, targetVertexID?: number, matrix?: Matrix, vertexID?: number, numVertices?: number): void
  • Copies the vertex data (or a range of it, defined by 'vertexID' and 'numVertices') of this instance to another vertex data object, starting at a certain target index. If the target is not big enough, it will be resized to fit all the new vertices.

    If you pass a non-null matrix, the 2D position of each vertex will be transformed by that matrix before storing it in the target object. (The position being either an attribute with the name "position" or, if such an attribute is not found, the first attribute of each vertex. It must consist of two float values containing the x- and y-coordinates of the vertex.)

    Source and target do not need to have the exact same format. Only properties that exist in the target will be copied; others will be ignored. If a property with the same name but a different format exists in the target, an exception will be raised. Beware, though, that the copy-operation becomes much more expensive when the formats differ.

    Parameters

    • target: VertexData
    • Optional targetVertexID: number
    • Optional matrix: Matrix
    • Optional vertexID: number
    • Optional numVertices: number

    Returns void

createVertexBuffer

  • createVertexBuffer(upload?: boolean, bufferUsage?: string): VertexBuffer3D
  • Creates a vertex buffer object with the right size to fit the complete data. Optionally, the current data is uploaded right away.

    Parameters

    • Optional upload: boolean
    • Optional bufferUsage: string

    Returns VertexBuffer3D

getAlpha

  • getAlpha(vertexID: number, attrName?: string): number

getBounds

  • getBounds(attrName?: string, matrix?: Matrix, vertexID?: number, numVertices?: number, out?: Rectangle): Rectangle
  • Calculates the bounds of the 2D vertex positions identified by the given name. The positions may optionally be transformed by a matrix before calculating the bounds. If you pass an 'out' Rectangle, the result will be stored in this rectangle instead of creating a new object. To use all vertices for the calculation, set 'numVertices' to '-1'.

    Parameters

    • Optional attrName: string
    • Optional matrix: Matrix
    • Optional vertexID: number
    • Optional numVertices: number
    • Optional out: Rectangle

    Returns Rectangle

getBoundsProjected

  • getBoundsProjected(attrName: string, matrix: Matrix3D, camPos: Vector3D, vertexID?: number, numVertices?: number, out?: Rectangle): Rectangle
  • Calculates the bounds of the 2D vertex positions identified by the given name, projected into the XY-plane of a certain 3D space as they appear from the given camera position. Note that 'camPos' is expected in the target coordinate system (the same that the XY-plane lies in).

    If you pass an 'out' Rectangle, the result will be stored in this rectangle instead of creating a new object. To use all vertices for the calculation, set 'numVertices' to '-1'.

    Parameters

    • attrName: string
    • matrix: Matrix3D
    • camPos: Vector3D
    • Optional vertexID: number
    • Optional numVertices: number
    • Optional out: Rectangle

    Returns Rectangle

getColor

  • getColor(vertexID: number, attrName?: string): number

getFloat

  • getFloat(vertexID: number, attrName: string): number

getFormat

  • getFormat(attrName: string): string
  • Returns the format of a certain vertex attribute, identified by its name. Typical values: float1, float2, float3, float4, bytes4.

    Parameters

    • attrName: string

    Returns string

getOffset

  • getOffset(attrName: string): number

getOffsetIn32Bits

  • getOffsetIn32Bits(attrName: string): number

getPoint

  • getPoint(vertexID: number, attrName: string, out?: Point): Point

getPoint3D

  • getPoint3D(vertexID: number, attrName: string, out?: Vector3D): Vector3D
  • Reads a Vector3D from the specified vertex and attribute. The 'w' property of the Vector3D is ignored.

    Parameters

    • vertexID: number
    • attrName: string
    • Optional out: Vector3D

    Returns Vector3D

getPoint4D

  • getPoint4D(vertexID: number, attrName: string, out?: Vector3D): Vector3D
  • Reads a Vector3D from the specified vertex and attribute, including the fourth coordinate ('w').

    Parameters

    • vertexID: number
    • attrName: string
    • Optional out: Vector3D

    Returns Vector3D

getSize

  • getSize(attrName: string): number

getSizeIn32Bits

  • getSizeIn32Bits(attrName: string): number

getUnsignedInt

  • getUnsignedInt(vertexID: number, attrName: string): number

Protected get_format

Protected get_formatString

  • get_formatString(): string

Protected get_numVertices

  • get_numVertices(): number

Protected get_premultipliedAlpha

  • get_premultipliedAlpha(): boolean

Protected get_rawData

  • get_rawData(): ByteArray

Protected get_size

  • get_size(): number

Protected get_sizeIn32Bits

  • get_sizeIn32Bits(): number

Protected get_tinted

  • get_tinted(): boolean

Protected get_vertexSize

  • get_vertexSize(): number

Protected get_vertexSizeIn32Bits

  • get_vertexSizeIn32Bits(): number

hasAttribute

  • hasAttribute(attrName: string): boolean

scaleAlphas

  • scaleAlphas(attrName: string, factor: number, vertexID?: number, numVertices?: number): void
  • Multiplies the alpha values of subsequent vertices by a certain factor.

    Parameters

    • attrName: string
    • factor: number
    • Optional vertexID: number
    • Optional numVertices: number

    Returns void

setAlpha

  • setAlpha(vertexID: number, attrName: string, alpha: number): void

setColor

  • setColor(vertexID: number, attrName: string, color: number): void
  • Writes the RGB color to the specified vertex and attribute (alpha is not changed).

    Parameters

    • vertexID: number
    • attrName: string
    • color: number

    Returns void

setFloat

  • setFloat(vertexID: number, attrName: string, value: number): void

setPoint

  • setPoint(vertexID: number, attrName: string, x: number, y: number): void

setPoint3D

  • setPoint3D(vertexID: number, attrName: string, x: number, y: number, z: number): void
  • Writes the given coordinates to the specified vertex and attribute.

    Parameters

    • vertexID: number
    • attrName: string
    • x: number
    • y: number
    • z: number

    Returns void

setPoint4D

  • setPoint4D(vertexID: number, attrName: string, x: number, y: number, z: number, w?: number): void
  • Writes the given coordinates to the specified vertex and attribute.

    Parameters

    • vertexID: number
    • attrName: string
    • x: number
    • y: number
    • z: number
    • Optional w: number

    Returns void

setPremultipliedAlpha

  • setPremultipliedAlpha(value: boolean, updateData: boolean): void

setUnsignedInt

  • setUnsignedInt(vertexID: number, attrName: string, value: number): void

Protected set_format

Protected set_numVertices

  • set_numVertices(value: number): number

Protected set_premultipliedAlpha

  • set_premultipliedAlpha(value: boolean): boolean

Protected set_tinted

  • set_tinted(value: boolean): boolean

toString

  • toString(): string

transformPoints

  • transformPoints(attrName: string, matrix: Matrix, vertexID?: number, numVertices?: number): void
  • Transforms the 2D positions of subsequent vertices by multiplication with a transformation matrix.

    Parameters

    • attrName: string
    • matrix: Matrix
    • Optional vertexID: number
    • Optional numVertices: number

    Returns void

translatePoints

  • translatePoints(attrName: string, deltaX: number, deltaY: number, vertexID?: number, numVertices?: number): void
  • Translates the 2D positions of subsequent vertices by a certain offset.

    Parameters

    • attrName: string
    • deltaX: number
    • deltaY: number
    • Optional vertexID: number
    • Optional numVertices: number

    Returns void

trim

  • trim(): void
  • Optimizes the ByteArray so that it has exactly the required capacity, without wasting any memory. If your VertexData object grows larger than the initial capacity you passed to the constructor, call this method to avoid the 4k memory problem.

    Returns void

updateTinted

  • updateTinted(attrName?: string): boolean
  • Updates the tinted property from the actual color data. This might make sense after copying part of a tinted VertexData instance to another, since not each color value is checked in the process. An instance is tinted if any vertices have a non-white color or are not fully opaque.

    Parameters

    • Optional attrName: string

    Returns boolean

uploadToVertexBuffer

  • uploadToVertexBuffer(buffer: VertexBuffer3D, vertexID?: number, numVertices?: number): void
  • Uploads the complete data (or a section of it) to the given vertex buffer.

    Parameters

    • buffer: VertexBuffer3D
    • Optional vertexID: number
    • Optional numVertices: number

    Returns void

Generated using TypeDoc