FXG 1.0 - Functional and Design Specification

FXG 1.0 Public Specification

FXG 1.0 describes an XML-based graphics interchange format for the Flash Platform. FXG contains high-level graphical and text primitives that can be used to create, group, transform and visually modify basic vector and bitmap shapes. The FXG rendering model follows very closely the Flash Player 10 rendering model and exposes all graphics capabilities of the Flash platform as well as offering expandable support to accommodate future capabilities of the Flash Player. The specification below dives into the technical details governing every element of FXG 1.0.

FXG vs SVG

When initial work on an XML-based graphics interchange format began, the natural first thought was to use SVG. However, there are key differences between SVG and Flash Player's graphics capabilities. These include core differences in SVG and Flash's rendering model with regards to filters, transforms and text. Additionally, the interchange format needed to be able to support future Flash Player features, which would not necessarily map to SVG features. As such, the decision was made to go with a new interchange format, FXG, instead of having a non-standard implementation of SVG. FXG does borrow from SVG whenever possible.

It is important to note that this specification follows much of the SVG specification format organization as well as copying related concept prose. The SVG specification is available at http://www.w3.org/TR/SVG/.

FXG Basic Concepts

Graphical Objects

FXG provides a general Path element that can be used to create a huge variety of graphical objects, and also provides common basic shapes such as Rectangles and Ellipses. These are convenient for hand coding and can be used in the same ways as the more general Path element. FXG provides fine control over the coordinate system in which graphical objects are defined and the transformations that are applied during rendering.

Symbols

FXG allows users to define and re-use multiple symbols within a single FXG document. A symbol defines a named grouping element containing graphical elements, grouping elements, and other symbols. Once a symbol is defined in a file, it can be referenced by name in other symbols in the same file.

Symbols can be used at different sizes and orientations, and can be restyled to fit in with the rest of the graphical composition.

Symbols cannot contain graphical objects directly. Instead, Symbols can contain Graphic grouping elements, that can in turn define individual graphical objects. Symbols can also contain instances of other symbol definitions.

Raster Effects

FXG allows the declarative specification of filters, either singly or in combination, that can be applied to any grouping element in the FXG document. These are specified in such a way that the graphics are still scalable and displayable at different resolutions.

Text and Fonts

FXG includes text elements that can render a set of shapes based on a Unicode string combined with a referenced font. Fonts are referenced by family and style, relying on the rendering environment to provide the matching font definition.

FXG Rendering

FXG's rendering model is intended to mirror the rendering model of the Flash Player, as of version 10. Implementations of FXG are expected to behave as though they implement a rendering (or imaging) model corresponding to the player's model. A real implementation is not required to implement the model in this way, but the result of any implementation should match the reference rendering of the Flash Player.

FXG is also intended for support on Flash Player 9.  Some features of FXG rely on rendering and API enhancements added in Flash Player 10, and will degrade gracefully when compiled for Player 9.  In some cases, the rendering is correct, but less optimized.  In some cases, the rendering is a best approximation. 

In practice an actual implementation will deviate slightly because of limitations of the environment (for example, only a limited range of colors might be supported, or a particular tool or technology might be mapping an FXG document to an existing rendering model) and because of practical limitations in implementing a precise mathematical model (for example, for realistic performance, curves are approximated by straight lines, the approximation need only be sufficiently precise to match the conformance requirements).

What follows is a general description of the portion of the Flash rendering model supported in FXG. While this document is intended to be complete, where details are unclear, the Flash Player should serve as the reference implementation.

The Rasterization Model

FXG rasterizes all elements on screen at the same time using a single rasterization pass.  This is different from a traditional painters model approach, in which each element is painted onto the surface in succession, from back to front.  In an FXG processor, a rasterizer sweeps across each scanline, rendering only those elements that are visible at each pixel of the output image.  Elements (and portions of elements) that are completely obscured by elements with a higher depth are never considered in the rasterization.  This can have subtle differences in the way the edge of a shape is composited with the background from the painters model approach, especially when two edges are coincident. 

FXG's rasterization model  matches Flash Player's closed-open model.

Rendering Order

Elements in an FXG document fragment have an implicit depth.  A processor assigns depth by walking the document in a depth first order, assigning each leaf node an incrementing depth as it goes.  Each element effectively paints above its previous siblings in the document. Additionally, children are painted above their parent.

How Groups are Rendered

Grouping elements are rendered in one of two ways, depending on their properties:

Transformation Groups

By default, group elements are not painted to the output of the FXG document. A standard group defines properties that transform the rendering of its descendants (geometry, color transforms, and clipping masks), but does not render directly by itself. These transformations are aggregated together as the FXG processor walks the document and are used to transform the rendering of each leaf node descendant of the group.

Surface Groups

Certain settings on a group (blend modes and filter effects, among others) have the effect of rendering the contents of the group in isolation.  The effect is akin to producing a temporary separate canvas initialized to transparent black onto which the child elements are painted.

Upon the completion of the group, any filter effects specified for the group are applied to create a modified temporary canvas. The modified temporary canvas is then composited into the background taking into account any group-level masking and alpha settings on the group.

Any group with either a non-normal blend mode or one or more filter effects applied will render as a surface group.

For example, if a clipping transformation group contains a surface group that does a blur, the contents of the surface group are blurred and then clipped. Generally, the order of processing is:

1. All content is transformed into the document coordinate space.
2. Content is rendered from the leaf nodes upward into the most immediate surface parent, with any intervening clipping paths applied.
3. The resulting surface is composited into its next most immediate surface parent with any intervening clipping paths applied.

Types of Graphics Elements

FXG supports three fundamental types of graphics elements that can be rendered onto the canvas:

• Shapes, which represent some combination of straight line and curves.
• Text, which represents some combination of character glyphs.
• Raster images, which represent an array of values that specify the paint color and opacity (often termed alpha) at a series of points on a rectangular grid. (See the Bitmaps section for a list of supported image file formats).

Painting Shapes

Shapes can be filled (you can apply paint to the interior of the shape) and stroked (you can apply paint along the outline of the shape). A stroke operation is centered on the outline of the object; thus, in effect, half of the stroke paint falls on the interior of the shape and half of the paint falls outside of the shape.

Each fill and stroke operation has its own opacity settings; thus, you can fill and/or stroke a shape with a semi-transparently drawn solid color, with different opacity values for the fill and stroke operations.

Painting Strokes

The stroke of a shape is painted as a separate operation, above the fill of the shape, but below the next highest element. This gives the appe,arane of painting the stroke over the fill.  For example, in the following FXG example, the stroke renders with a 50% opacity, showing the red fill color beneath it:

<Rect width="200" height="200">
   <fill>
      <SolidColor color="#FF0000" />
   </fill>
   <stroke>
      <SolidColorStroke weight="10" color="#0000FF" alpha="0.5" />
   </stroke>
</Rect>

In general, strokes in FXG are not affected by the transform of the user coordinate space the shape is defined in.  Instead, a processor will typically first transform the points of a path into document space, then apply the properties of the stroke to the path to define the stroke's paint region.

The weight of a stroke is transformed based on the scale factor between document and user coordinates of its parent group element. To define the rendered width of a stroke in document space, a processor first extracts the x and y scale factor from the stroke's user space composite matrix (sx,sy) and transforms the weight w, as the following example shows:

weight_in_document_space = sqrt(2 * ( (w*sx)^2 + (w*sy)^2))

FXG supports the following built-in types of paint that can be used in fill operations:

• Solid color
• Gradient (linear and radial)
• Bitmap

FXG supports the following built-in types of paint that can be used in stroke operations:

• Solid color
• Gradient (linear and radial)

Painting Text 

Text elements in an FXG document are painted as though the text were a bitmap rendering of the text used to fill a rectangular path.  The text can be rendered with a solid color, with no support for strokes.  The bitmap is rendered with any inherited color transform applied (a typical implementation will render glyphs directly to get a higher quality rendering, but the effect should be the same). FXG is defined under the assumption that it is matching the Flash Player 10 rendering model, that does not impose limitations on how text can be transformed.

Painting Raster Images

When a raster image is rendered, the original samples are "resampled" using standard algorithms to produce samples at the positions required on the output device. Resampling requirements are discussed under conformance requirements.

Filtering Painted Regions

FXG allows any grouping element to be filtered. The filters of a grouping element are applied to the rendererd result of the element's children For more information, see the section on filter effects.

Any group with a filter applied is rendered as a surface group.

Clipping, Masking and Object Opacity

FXG allows any grouping element to limit the painting of its child elements to a subregion of the output device by masking. This is described in the [Masking] section below.

Masking uses a separate grouping element to define a region of the output device to which paint can be applied. Any painting operation executed within the scope of the clipping must be rendered such that only those parts of the device that fall within the region defined by the masking element are affected by the painting operation. A masking element is treated as a 1-bit mask when applied; pixels left unfilled by the masking element are left unfilled by the masked element, while pixels with any non-transparent fill value in the masking element are filled the same as if the masked element had no mask applied.

Basic Data Types

The common data types for FXG's properties and attributes fall into the following categories:

<angle>

An angle value is an arbitrary <number> specified as degrees. Angles are clockwise.

<color>

The basic type <color> is assumed to be a specification for a color in the sRGB color space SRGB. <color> is a component of the definitions of fills, strokes, and text color.

A <color> is a numerical RGB specification in hexadecimal notation. It is specified by a '#' immediately followed by six hexadecimal characters.

<coordinate>

A <coordinate> represents a <length> in the local coordinate system that is the given distance from the origin of the local coordinate system along the relevant axis (the x-axis for X coordinates, the y-axis for Y coordinates).

<integer>

An <integer> is specified as an optional sign character ('+' or '-') followed by one or more digits "0" to "9". If the sign character is not present, the number is non-negative. Unless stated otherwise for a particular attribute or property, the range for an <integer> encompasses (at a minimum) -2147483648 to 2147483647.

<length>

A length is a distance measurement. The format of a <length> is a <number>.

<number> (real number value)

A <number> is specified either in decimal notation, or in scientific notation. Decimal notation consists of either an <integer>, or an optional sign character followed by zero or more digits followed by a dot (.) followed by one or more digits. Scientific notation consists of a decimal-number immediately followed by the letter "e" or "E" immediately followed by an <integer>.

Unless stated otherwise for a particular attribute or property, a <number> has the capacity for at least a single-precision floating point number (see ICC32) and has a range (at a minimum) of -3.4e+38F to +3.4e+38F.

<percentage>

The format of a percentage value is a <number> immediately followed by a '%'. Percentage values are always relative to another value; for example, a length. Each attribute or property that allows percentages also defines the reference distance measurement to which the percentage refers.

Document Structure

FXG documents have a logical structure. This structure is described in the section below.  

Defining an FXG Document Fragment: Graphic Element

An FXG document fragment consists of a single definition and an optional library that is contained within a Graphic element.

An FXG document fragment can be one of the following:

• An empty definition (a single Graphic element).
• A very simple FXG document fragment containing a Graphic definition with a single graphics element such as a 'Rect'.
• A complex, deeply nested collection of container elements and graphics elements.

An FXG document fragment can stand by itself as a self-contained file or resource, in which case the FXG document fragment is an FXG document, or it can be embedded inline as a fragment within a parent XML document.

FXG documents contain references to external bitmaps, but are otherwise self contained.  FXG documents do not reference other FXG documents.

FXG elements must be scoped within an XML document under the FXG namespace. The FXG 1.0 namespace is '*http://ns.adobe.com/fxg/2008*'.

Element Types

The structure of an FXG document can be thought of as object-graph based.  In other words, an FXG document is modeled to represent the scene graph of a runtime rendering of the document.

Elements in an FXG document fall into three categories:

Control Elements

Control elements define how a section of the document should be processed.  For example, a Definition element dictates that its content represents a definition of a Group rather than an instance of a Group, and should not be rendered in the output.

FXG control elements are:

• Library
• Definition

Object Definition Elements

Object definition elements define a fragment of FXG that can be instantiated elsewhere.  Certain features of FXG are only supported on definition elements, while others are illegal on definition elements.  The Graphic tag in an FXG file is considered to be an object definition element, as it defines the entire document. Any immediate child of a definition element is considered to be an object definition.

Object Instance Elements

Object instance elements create an instance of an element whose behavior is defined elsewhere, either within the FXG document, or globally by the FXG format  For elements that can appear both as definition elements and as instance elements, there are certain attributes and elements that are only valid on instances (and some that are illegal on instances).  The naming 'id' attribute can only be placed on object instance elements.

Group elements can serve as both object definition and instance at the same time. In which case all attributes and children are legal.

Relationship Elements

Some elements in FXG exist to define the relationship between two object elements. The <mask> element, for example, defines its child (a Group instance) to be the clipping mask for its parent (a graphical element instance).

The Root Graphic Element

The Graphic element serves as the root for any FXG document. It cannot appear anywhere else in an FXG document than as the root element.

The Graphic element root definition has no explicitly defined name; any name associated with the definition by a particular environment is derived externally from the surrounding context. The MXML compiler, for example, will associate the definition contained within an FXG file with the name of the file.

The Graphic element can optionally contain a single child Library element.

The Graphic element is functionally equivalent to a Group definition element. It can define children, but cannot be named, or define filters or transforms. See the group element below for more information.

Children

• Library
• Group
• Any graphical element

Attributes

• scaleGridLeft
• scaleGridRight
• scaleGridTop
• scaleGridBottom
• viewWidth
• viewHeight
• version
• mask

The Group Element

The Group element is a container element for grouping together related graphics elements.

A group of elements, as well as individual objects, can be given a name by using the id attribute. Named groups are needed in interactive environments for animation and runtime modification.

The following example shows a Graphic element:

<Graphic>
    <Group id="trainBody">
        <Ellipse x="20" y="100" width="40" height="40" id="backWheel" />
        <Ellipse x="80" y="100" width="40" height="40" id="frontWheel" />
    </Group>
<Graphic>

A Group element defines a new local coordinate space for its immediate child elements. The new coordinate space is transformed by geometry transformation that is optionally defined on the Group element.

A Group element can contain other Group elements nested within it, to an arbitrary depth.

A Group element can contain zero or more graphical elements as children.

The order of the graphical object and group element children of a Group determine their depth order when rendered.

Group Instances vs. Definitions

The Group tag can appear inside the Graphic tag, inside other Group tags, or inside a Definition tag in the Library section of an FXG document. When a Group is used inside a Definition tag, it is considered a symbol definition. When it is used inside a Graphic or other Group, it is considered an instance group. Groups have two optional child elements than are only legal on instance groups, not on symbol definitions.

An Instance Group element can optionally contain exactly one element named 'transform'. If present, this element must contain exactly one child element of type Transform.

An Instance Group element can optionally contain exactly one element named 'filters'. If present, this element must contain zero or more child elements matching filter types.

An Instance Group element can optionally define an id attribute. An id attribute can not be defined on a Group definition. See the naming section for details.

The transform and filters child elements, if present, can appear anywhere in the child order. Their position within the parent group does not affect the rendering.

Children

• transform
• filters
• Group
• Any graphical element

Attributes

• rotation
• scaleX
• scaleY
• x
• y
• blendMode
• alpha
• id
• transformX
• transformY
• maskType
• visible
• scaleGridLeft
• scaleGridRight
• scaleGridTop
• scaleGridBottom

Symbols, Instances, and the Library Element

An FXG document can define one or more symbols that can be instantiated multiple times at various locations within the document. Symbols are Group elements defined and named within the Library section of the document. For example, to define a filled rectangle for use elsewhere in the document, you first define a Group in the Library and give it a name, as the following example shows:

<Library>
    <Definition name="BlueRect">
        <Group>
            <Rect width="200" height="200">
                <fill>
                    <SolidColor color="#0000FF" />
                </fill>
            </Rect>
        </Group>
    </Definition>
</Library>

Defined symbols can be referenced elsewhere in the document by using the Definition name as a tag name. The following example places the symbol that was defined in the previous code snippet:

<Graphic>
    <BlueRect x="25" y="30" />
</Graphic>

Symbols can only be used in places where Group tags are legal.

When an FXG renderer encounters an unknown tag, it attempts to resolve it as a defined symbol. An unknown tag can be resolved as a defined symbol if:

• It is a direct child of a Graphic or Group tag.
• It is within the FXG namespace.
• The localname of the element matches the value of the name attribute of a definition element in the Library section of the document.

A symbol instance can not appear within its own definition, directly or nested within other groups or instances.

The Library Element

The Library element is a container element for definitions. The Library element can only be placed as a child of the root of the FXG document, and defines symbols that can be referenced by name anywhere in the document (as appropriate). The Library element must be declared prior to its use. An error should be emitted as soon as an unknown library element is referenced.

The library element contains zero or more definition child elements.

Children

• Definition

The Definition Element

The Definition element represents a single definition in the FXG document library. It must contain exactly one child element, which in FXG 1.0 must be a Group element.

The Definition element creates an enclosed scope for id attribute values defined within its element subtree. Within the Definition, all id attribute values must be unique. id attribute values defined within the Definition can duplicate id attribute values defined inside other Definitions or elsewhere in the document. The Definition element must be declared prior to its use. An error should be emitted as soon as an unknown Definition is referenced.

Attributes

• name <Identifier>: The name of the symbol that is used to reference it when declaring an instance in the file, and is required. See [FXG Name Mangling].

Children

• Group

The PlaceObject Element

Any Group defined in a Definition tag in the Library section of an FXG document defines a template object that can be re-used (i.e., "instanced") in the FXG document with a [PlaceObject] element. The [PlaceObject] element references another element and indicates that the graphical contents of that element are included/drawn at that given point in the document.

The term '[PlaceObject]' is a conceptual term used for the purposes of this specification, but never actually appears inside of an FXG document. To create an instance of a Group that is defined in the Library, an FXG document contains an element whose localname matches the _name attribute of the definition being referred to. See the overview above for an example.

Other than the localname of the element, the schema of the instance element must exactly match the schema and use of the [PlaceObject] tag as described here.

The rendered effect of a [PlaceObject] element is as if the [PlaceObject] element itself were replaced by a deep clone of the contents of the referenced definition.

By default, the instanced content is rendered into a rectangular region at the origin of the [PlaceObjects]'s parent coordinate system with a width and height that matches the width and height of the instanced content. This rectangular region can be modified by an optional two dimensional transformation defined on the [PlaceObject] tag. The 2D transformation can be specified as a 2D matrix, as part of a child transform assigned as a child element to the [PlaceObject].

A [PlaceObject] element can optionally contain exactly one element named 'transform'. If present, this element must contain exactly one child element of type Transform.

A [PlaceObject] element can optionally contain exactly one element named 'filters'. If present, this element must contain zero or more child elements matching filter types.

The transform and filters child elements, if present, can appear in any order.

Attributes

• id <Identifier>: See the naming section for details.

Children

• transform
• filters

Coordinate Space Transformations

FXG defines two coordinate system concepts: the document coordinate system, and the user coordinate system.

The document coordinate system refers to the coordinate system of the root Graphic tag of the FXG document.  By default, its origin sits at the top left of the document, and extends downward along the positive y axis, and to the right along the positive x axis. 1 unit corresponds to 1 pixel on the screen.

When the FXG document is embedded or referenced (such as by an MXML application), the surrounding context can define a different document coordinate system.  In Flex, for example, the  FXG document might be used within a  further hierarchy of MXML components, each with their own geometry transform that modifies the FXG document coordinate system.

The user coordinate system refers to the coordinate system defined on any individual element in the document. The user coordinate system at the root Graphic element is identical to the document coordinate system. 

Each grouping instance element and graphic element by default defines its user coordinate system to be identical to that of its parent.  Any geometry transform defined on the element (through attributes or child transform elements) transforms its parent's user coordinate system into a new system.

All attributes of elements in FXG are defined in units of the current user coordinate system.  So the coordinates of a the segments of a Path element are relative to its coordinate system. To determine the position of the Path segments in document coordinates, you would multiply its x and y by the geometry transform of the Path and each of its parent elements until you reached the root graphic element.

Some fills and strokes in FXG have their own user coordinate system.  As with Groups, the default coordinate system is aligned with the coordinate system of their most immediate parent instance.  As appropriate, fills and strokes support geometry transforms that can modify their coordinate space.

Transformations are considered instanced group properties, and can only be defined on shape elements and Groups whose parent element is another grouping element, or on [PlaceObject] tags. Specifically, transformations cannot be defined on Groups whose parent element is a Definition element, or on the topmost Graphic element. See the [Document Structure] section for more details on Instances vs. Definitions.

Transformations can be defined on an element in one of two ways: through discrete transform attributes, or through a child Transformation and Matrix element. It is illegal to specify both a child element matrix transformation and one or more transform attributes on the same Group instance.

Discrete transforms can be specified with the attributes: x,y, scaleX, scaleY, rotation, transformX, and transformY. These attributes are combined to create a 2D transform matrix to define the Group's coordinate space as follows:

• Translate by -transformX, -transformY
• Scale by scaleX, scaleY
• Rotate by rotation
• Translate by x,y
• Translate by transformX, transformY

<Group transformX="40" x="32" rotation="45" scaleX="0.5" scaleY="0.5" >
   <Rectangle width="200" height="200" />
</Group>

Alternatively, an element can define the coefficients of a 3x3 2D matrix as part of a transform child element:

<Group>
    <transform>
        <Transform>
            <matrix>
                <Matrix a="0.5" d="0.5" tx="32" />
            </matrix>
        </Transform>
    </transform>
    <Rect width="200" height="200" />
</Group>

See the [Matrix] section below for more details.

Transform

The Transform element serves as a grouping element to define the matrix based transformations that are applied to a grouping element and all of its descendants. A Transform element appears as the only child of a <transform> element, which is an optional child element of a shape or instance grouping element.

The Transform can optionally contain exactly one child element named 'colorTransform'. If present, this element must contain exactly one child element of type [ColorTransform]. For details on the [ColorTransform] element, see the [color] section.

The Transform can optionally contain exactly one child element named 'matrix'. If present, this element must contain exactly one child element of type Matrix.

The order of the colorTransform and matrix child elements is irrelevant.

Transformable elements can define their coordinate space transformation using either the discrete transform attributes, or using a matrix/Matrix element inside a child transform/Transform element, but not both. If the grouping element specifies one or more transform attributes, it is legal for it to contain a transform/Transform element, but not legal for that Transform element to contain a matrix/Matrix element.

Attributes

None.

Children

• matrix
• colorTransform

Matrix

The Matrix element represents a 3x3 2D affine transform matrix. It can appear as a child of a matrix element inside a Transform element.

The Matrix element assumes the bottom left and bottom center coefficients in the matrix are zero (using column vectors). The other coefficients can be specified as attributes.

The following example shows how the attributes map to coefficients:

a b tx
c d ty
0 0 1

Attributes

• a <Number>: The top left coefficient of the matrix.
• b <Number>: The top center coefficient of the matrix.
• c <Number>: The center left coefficient of the matrix.
• d <Number>: The center center coefficient of the matrix.
• tx <Number>: The top right coefficient of the matrix.
• ty <Number>: The center right coefficient of the matrix.

Children

None.

FXG Paths

Paths represent the outline of a shape that can be filled and/or stroked.

A path is described using the concept of a current point. In an analogy with drawing on paper, the current point can be thought of as the location of the pen. The position of the pen can be changed, and the outline of a shape (open or closed) can be traced by dragging the pen in either straight lines or curves.

Paths represent the geometry of the outline of an object, defined in terms of moveto (set a new current point), lineto (draw a straight line), curveto (draw a curve using a cubic Bézier) and closepath (close the current shape by drawing a line to the last moveto) elements. Compound paths (i.e., a path with multiple sub-paths) are possible to allow effects such as "donut holes" in objects.

A path is defined in FXG using the Path element. As with all vector shape elements in FXG, the Path element can optionally define fill and stroke types using child elements. A Path element can specify its winding, or fill rule for intersecting or overlapping paths, to be either evenOdd or nonZero. The actual Path itself can be defined in compact form, using the d attribute and setting that to a series of coordinate points.

A Path element can optionally contain exactly one element named 'fill'. If present, this element must contain exactly one fill type child element.

A Path element can optionally contain exactly one element named 'stroke'. If present, this element must contain exactly one stroke type child element.

Path elements are transformable elements. They support all of the transform attribute and children defined  in the coordinate system and transforms section, as well as the color transform attributes and children defined in the color transformations section.

Path elements support blendModes and bitmap filters. See the [filter effect] section for more information.

Attributes

• data <path data>: The definition of the outline of a shape. See [Path data].
• x <Number>
• y <Number>
• transformX <Number>
• transformY <Number>
• rotation <Number> (<angle>)
• scaleX <Number>
• scaleY <Number>
• blendMode <String> (add, alpha, darken, difference, erase, hardlight, invert, layer, lighten, multiply, normal, overlay, screen, shader, subtract)
• visible <Boolean>
• winding <String> (evenOdd, nonZero): Fill rule for intersecting or overlapping path segments.

Children

• fill
• stroke
• filters
• transform

Path Data

A Path is defined by including a Path element that contains a data="(path data)" attribute, where the d attribute contains the moveto, line, curve (both cubic and quadratic Béziers), arc and closepath instructions.

The example below specifies a Path in the shape of a triangle. (The M indicates a moveto command, the Ls indicate lineto commands, and the z indicates a closepath command).

<Group>
    <Path data="M 100 100 L 300 100 L 200 300 z">
        <fill>
            <SolidColor color="#FF0000" />
        </fill>
        <stroke>
            <SolidColorStroke weight="3" color="#0000FF" />
        </stroke>
    </Path>
</Group>

Path data can contain newline characters and thus can be broken up into multiple lines to improve readability. Because of line length limitations with certain related tools, it is recommended that FXG generators split long Path data strings across multiple lines, with each line not exceeding 255 characters. Note that newline characters are only allowed at certain places within Path data.

The syntax of Path data is borrowed from the SVG specification, and was designed originally to be concise. Compact Path data minimizes file sizes, and prevents the Path data from overwhelming human readers trying to understand overall file structure. FXG will only support the short, concise syntax.

The Path data syntax is a prefix notation (i.e., commands followed by parameters). The only allowable decimal point is a Unicode UNICODE FULL STOP (".") character (also referred to in Unicode as PERIOD, dot and decimal point) and no other delimiter characters are allowed. (For example, the following is an invalid numeric value in a path data stream: "13,000.56". Instead, use the following: "13000.56".)

For the relative versions of the commands, all coordinate values are relative to the current point at the start of the command.

In the tables below, the following notation is used:

(): grouping of parameters

+: 1 or more of the given parameter(s) is required

The following sections list the commands.

The "moveto" commands

The "moveto" commands (M or m) establish a new current point. The effect is as if the "pen" were lifted and moved to a new location. A Path data segment (if there is one) must begin with a "moveto" command. Subsequent "moveto" commands (i.e., when the "moveto" is not the first command) represent the start of a new sub-path.

When a moveto is used in the middle of the data for an FXG Path, the previous sub-path is implicitly closed. An implicitly closed path is filled as though there were a final lineTo segment from the final point of the path to the starting point. This implicit line segment is not stroked. 

Attributes

• x <Number>
• y <Number>

The "closepath" command

The "closepath" (Z or z) ends the current sub-path and causes an automatic straight line to be drawn from the current point to the initial point of the current sub-path.

A closepath command is functionally equivalent to a lineTo command that ends in the same point that began the current sub-path.  Specifically, when a sub-path ends on the same point it began on, the Path is considered closed, and an appropriate join is rendered between the starting and ending segment.

A moveTo command implicitly begins a new sub-path. If a moveTo command appears in a Path's data without immediately following a closepath command, the previous sub-path is implicitly closed with an unstroked straight line segment from the ending point to the starting point of the sub-path.

If the final element in a sub-path's data is not a closepath command,  it is implicitly closed, as above.

Attributes

None.

The "lineto" commands

The various "lineto" commands draw straight lines from the current point to a new point:

Attributes

• x <Number>
• y <Number>

The Curve Commands

The following groups of commands draw curves:

Cubic Bézier commands (C, c, S and s). A cubic Bézier segment is defined by a start point, an end point, and two control points.

Quadratic Bézier commands (Q, q, T and t). A quadratic Bézier segment is defined by a start point, an end point, and one control point.

The cubic Bézier commands are as follows:

Attributes

• control1X <Number>
• control1Y <Number>
• control2X <Number>
• control2Y <Number>

The quadratic Bézier commands are as follows:

Attributes

• control1X <Number>
• control1Y <Number>

Basic FXG Shapes

FXG contains the following set of basic shape elements:

• Rectangles (including optional rounded corners)
• Ellipses
• Lines

Mathematically, these shape elements are equivalent to a Path element that would construct the same shape (with the small exception that they require elliptical arc segments, which Paths don't support). The basic shapes can be stroked and filled.

Shapes, like Paths, are transformable elements.  They support all of the transform attributes and child elements. See the section on [coordinate spaces and transformations]for details. They also support color transforms, and associated properties/attributes. See the [Color Transforms] section for details.

Shapes can have blend modes and bitmap filter effects applied to them. See the section on [filter effects] for more details.

The Rect element

The Rect element defines a rectangle that is axis-aligned with the current coordinate system. Rounded rectangles can be achieved by setting appropriate values for attributes radiusX and radiusY.

Attributes

• width <length>: The width of the rectangle. A negative value is an error.
• height <length>: The height of the rectangle. A negative value is an error.
• radiusX <length>: For rounded rectangles, the x-axis radius of the ellipse used to round off the corners of the rectangle. A negative value is an error. See the notes below about what happens if the attribute is not specified.
• radiusY <length>: For rounded rectangles, the y-axis radius of the ellipse used to round off the corners of the rectangle. A negative value is an error See the notes below about what happens if the attribute is not specified.
• x <Number>
• y <Number>
• transformX <Number>
• transformY <Number>
• rotation <Number> (<angle>)
• scaleX <Number>
• scaleY <Number>
• blendMode <String> (add, alpha, darken, difference, erase, hardlight, invert, layer, lighten, multiply, normal, overlay, screen, shader, subtract)
• visible <Boolean>

If a properly-specified value is provided for radiusX but not for radiusY, then the user agent processes the Rect element with the effective value for radiusY as equal to radiusX. If radiusX is not specified, or is specified as zero, then the user agent processes the Rect element as if no rounding had been specified, resulting in square corners. If radiusX is greater than half of the width of the rectangle, then the user agent processes the Rect element with the effective value for radiusX as half of the width of the rectangle. If radiusY is greater than half of the height of the rectangle, then the user agent processes the Rect element with the effective value for radiusY as half of the height of the rectangle.

Children 

• transform
• filters
• fill
• stroke
• mask

The Ellipse element

The Ellipse element defines an ellipse that is axis-aligned with the current user coordinate system based on a bounding rectangle. The bounding rectangle defines the bounds of the actual Ellipse path. Any stroke applied to the Ellipse can extend beyond the bounding rectangle, according to the painting rules of the stroke.

Attributes

• width <length>: The x-axis length of the ellipse path bounding rectangle.
• height <length>: The y-axis length of the ellipse path bounding rectangle.
• x <Number>
• y <Number>
• transformX <Number>
• transformY <Number>
• rotation <Number> (<angle>)
• scaleX <Number>
• scaleY <Number>
• blendMode <String> (add, alpha, darken, difference, erase, hardlight, invert, layer, lighten, multiply, normal, overlay, screen, shader, subtract)
• visible <Boolean>

The arc of an Ellipse element begins at the "3 o'clock" point on the radius and progresses towards the "9 o'clock" point. The starting point and direction of the arc are affected by the user space transform in the same manner as the geometry of the element.

Children 

• transform
• filters
• fill
• stroke
• mask

The Line element

The Line element defines a line that is axis-aligned with the current coordinate system.

Attributes

• xFrom <Number> The x-axis starting point of the line. Defaults to 0.
• yFrom <Number> The y-axis starting point of the line. Defaults to 0.
• xTo <Number> The x-axis ending point of the line. Defaults to 0.
• yTo <Number> The y-axis ending point of the line. Defaults to 0.
• x <Number> Defaults to 0.
• y <Number> Defaults to 0.
• transformX <Number> Defaults to 0.
• transformY <Number> Defaults to 0.
• rotation <Number> (<angle>) Defaults to 0.
• scaleX <Number> Defaults to 1.
• scaleY <Number> Defaults to 1.
• blendMode <String> (add, alpha, darken, difference, erase, hardlight, invert, layer, lighten, multiply, normal, overlay, screen, shader, subtract) Defaults to layer.
• alpha <Number> Defaults to 1.
• id
• maskType Defaults to clip.
• visible <Boolean> Defaults to true.

Children 

• transform
• filters
• fill
• stroke
• mask

FXG Text

This section defines a simple, conservative text representation based on a subset of the new capabilities of Flash Player 10's advanced text support.

TextGraphic Element

Text in FXG is defined with the TextGraphic element. A TextGraphic element can have two element children, <transform> and/or <content>. <transform> is described in the [Transformation]section of the FXG spec. <content> is the content of the TextGraphic element. So in the simplest case, a TextGraphic might look like the following:

<TextGraphic fontFamily="Verdana" fontWeight="bold"><content>Hello, World</content></TextGraphic>

When a transform is applied, it looks like the following:

<TextGraphic fontFamily="Verdana" fontWeight="bold">
    <transform>...</transform>
    <content>Hello, World</content>
</TextGraphic>

The text content in a [TextGraphic] tag needs to be contiguous and contained in a <content> property. The following is legal:

<TextGraphic fontFamily="Verdana" fontWeight="bold">
    <content>Hello, World</content>
    <transform>...</transform>
</TextGraphic>

The following is not legal:

<TextGraphic fontFamily="Verdana" fontWeight="bold">
    <content>Hello, World</content>
    <transform>...</transform>
    <content>Hello again</content>
</TextGraphic>

The ordering of child tags of a TextGraphic element is not significant, so the transform tag can also appear before the content tag as in this example:

<TextGraphic fontFamily="Verdana" fontWeight="bold">
    <transform>...</transform>
    <content>Hello, World</content>
</TextGraphic>

The contents of a content property can be a sequence of characters, <p>, <br/> or <span> elements. The <p> and <span> elements can be implied. Rules for reconstituting implied elements are listed below.

The preceding examples are simple, single-format text with implied <p> and <span> elements. The following example is identical to the previous example:

<TextGraphic fontFamily="Verdana" fontWeight="bold">
    <transform>...</transform>
    <content><p><span>Hello, World</span></p></content>
</TextGraphic>

The following example has multiple text formats, with one implied span and one explicit span:

<TextGraphic fontFamily="Verdana" fontWeight="bold">
    <content>Hello, <span fontWeight="normal">World</span></content>



</TextGraphic>

The equivalent verbose example is as follows:

<TextGraphic fontFamily="Verdana" fontWeight="bold">
    <content>
        <p><span>Hello, </span><span fontWeight="normal">World</span></p>
    </content>
</TextGraphic>

The following example shows multiple paragraphs:

<TextGraphic fontFamily="Verdana">
    <content>First paragraph
    <p textIndent="15">Second para</p>
    Third Para</content>
</TextGraphic>

The equivalent verbose version of the same example is as follows:

<TextGraphic fontFamily="Verdana">
    <content>
        <p><span>First paragraph </span></p>
        <p textIndent="15"><span>Second para</span></p>
        <p><span> Third Para</span></p>
    </content>
</TextGraphic>

A <p> always starts a new paragraph.

Any text content (including spans) that comes before the <p> and is not part of <p> is placed in a paragraph automatically. Likewise any text that follows the </p> is placed in a paragraph. *Exception:*If the text content before <p>...</p> or after <p>...</p> is all whitespace in a single span, it is not placed in a paragraph automatically. It is removed. In XML DOM terminology, any text node that is a direct child of the <content> property is removed if it is all whitespace.

If the <content> element has text content and no paragraph, a paragraph is automatically generated for the text.

A TextGraphic element can also be empty. A TextGraphic element can have an empty <content/> property as well. The value of the <content> property is one <p> tag with one empty <span/> tag in it.

paragraph Element

The p element is for use in TextGraphic elements that have multiple paragraphs. A <p> starts a new paragraph. A <p> can be a child of a TextGraphic. Children are character sequences, <br/> elements, or <span> elements. Every <p> has at least one <span> that can be implied. Character sequences that are direct children of <p> are in an implied <span>.

span Element

All character sequences in the <content> value are contained in one or more <span> elements. Explicit span elements can be used for formatting runs of characters within a paragraph. Every <span> element is a child of a <p> element. A span can contain character sequences and/or <br/> elements. A <span> element can be empty.

Unlike in XHTML, spans must not be nested. The reason for this is the increased cost in number of objects required to represent the text. 

br Element

The <br/> element behaves as a Unicode line separator character. It does not end the paragraph, it merely forces a line break at the position where it appears. As defined by Unicode spec: "A line separator indicates that a line break should occur at this point; although the text continues on the next line, it does not start a new paragraph---no interparagraph line spacing or paragraph indentation is applied." They are always a child of <span> elements, though the <span> element can be implied. The <br> element must have no children (empty tag).

The Text Box

A TextGraphic element defines a text box, specified in the parent Group element's coordinate space, to contain the provided text. The text box is specified using the x/y and width/height attributes on the TextGraphic element.

When you measure the text, it has a logical extent that is calculated using the font metrics. When you draw, it inks pixels. The pixels that are inked don't exactly correspond to the logical bounds because characters can hang over the left or right edge. Hanging over the left edge can happen, for instance, for a capital "J" where the hook on the J typically extends leftwards. Hanging over the right edge can also happen, notably if the text is italic. Calculations of the text box dimensions are done based on the logical extent and not the inked bounds.

The TextGraphic element automatically clips the text rendering to the bounds of the text box.

If no width/height is specified on the TextGraphic element, or if the specified width or height is 0, a width and height is calculated based on the text content. This is done using the following logic for horizontal text:

• If the width is specified, but the height is not, the container height is set to the height required to fit the text (i.e., text wraps to the width of the container, and the total height of the text becomes the container height).
• If the width is not specified, then the text breaks only at line breaks and at the paragraph end. The width of the container is then set to the width of the longest line.
• If neither width nor height are specified, the width is set as described above, and then the height is set based on the width.
• If the height is specified, and the text exceeds what will fit, then the remaining text is preserved but does not appear in the container; it is clipped. Note that the client can choose to add scroll bars to view the additional text, but scroll bars are not part of FXG.

For vertical text, all the logic remains the same, but switch width and height in the preceding description.

You should note the following:

• This is not an optimal fit case where the width is calculated to fit a specified height.
• There are some cases where width and/or height are not specified and a large amount of incoming text is supplied. In this case, the client must determine a reasonable break off point for how much of the text to compose before setting the width and height in order to avoid slowdowns.

Fidelity

It is a non-goal to preserve appearance or layout between clients. The meaning of the text is preserved, and the attributes that are understood by the client are preserved, but the text will re-layout for each client. The lines breaks are likely to be different, what glyphs are used to render the text can be different, the fonts used can be different. The clients preserve the meaning of the text, and the logical settings, and use them to drive the layout according to their own rules. Hence a text snippet that can be five lines in one client, could be three in a different client, and seven in still another one.

Text Rendering

Text is rendered as a graphic element similar to paths and shapes, but with a restricted subset of rendering options. TextGraphic elements are always rendered using a solid fill color, modified by any opacity, blend mode, and color transformation defined by parent elements, and clipped to any clipping content defined on its parent elements. TextGraphic content is only filled, not stroked.

With Flash Player 10, previous problems rendering text in device fonts with containers that have been rotated or skewed are fixed, and alpha with device text also works.

Font References

FXG documents refer to fonts via their family name in the fontFamily attribute of the TextGraphic tag. It is the processor's job to resolve font family names to font implementations, typically using the local machine's installed font list. FXG 1.0 does not support the ability to refer directly to a font definition file on disk. Fonts in FXG are always by name; fonts cannot be embedded or linked to FXG. All applications using FXG should have consistent mechanisms for mapping from the font reference to a font installed in the host OS or editing application.

Text Character Set

The full Unicode 5.0 character set is supported, including surrogate characters and Unicode control characters. Support for characters is, however, dependent on the font that is being used for rendering. Please consult the Unicode spec for more information (http://unicode.org/versions/Unicode5.0.0/). For info specifically on the Unicode control characters, see http://www.unicode.org/versions/Unicode5.0.0/ch16.pdf.

Entity support applies to all of FXG. The following standard XML entities are supported: lt, gt, quot, apos, and amp.

Whitespace Handling

The problem here is how to tell which characters in the text are there for pretty-printing the XML, and which should really be considered as part of the text content. Flex counts all characters that appear in the text content as actual desired text content. XHTML takes a different approach and assumes that users can add newlines, tabs, and spaces that are really only there for viewing and editing the file in XML, and they don't want to see the characters in the actual text when displayed in the document. This is controlled with the whiteSpaceCollapse property.

For example, these two snippets are equivalent:

<TextGraphic fontFamily="Verdana" fontWeight="bold" whiteSpaceCollapse="collapse">
    <content>
        <p>First para,
        separated into
        several lines in the XML.</p>
        <p>Second para.</p>
    </content>
</TextGraphic>

The whitespace (indenting and newlines) inside the <p>...</p> tags is there only for pretty-printing. By using collapse mode, that pretty-printing is removed, resulting in this equivalent snippet:

<TextGraphic fontFamily="Verdana" fontWeight="bold" whiteSpaceCollapse="preserve">
    <content><p><span>First para, separated into several lines in the XML.</span><p><span>Second para.</span></p></content>
</TextGraphic>

Note that the newlines in the original XML snippet turned into single spaces.

The <br/> tag is used most often in collapse mode, to ensure that linebreaks happen where intended. For example, suppose you started with this snippet:

<TextGraphic fontFamily="Verdana" fontWeight="bold">
<content>
    <p>First line.

    Second line.</p>
</content>
</TextGraphic>

The intention is to have a line separated by two linebreaks, followed by a second line. However, because the default value of the whiteSpaceCollapse attribute on TextGraphic is 'collapse', the newlines are replaced by a single space. The following is an equivalent snippet:

<TextGraphic fontFamily="Verdana" fontWeight="bold" whiteSpaceCollapse="preserve">
<content>
    <p><span>First line. Second line.</span></p>
</content>
</TextGraphic>

To get the desired results, you must use explicit <br/> tags.

<TextGraphic fontFamily="Verdana" fontWeight="bold">
<content>
    <p>First line.<br/>
    <br/>
    Second line.</p>
</content>
</TextGraphic>

If a Unicode line separator character appears as a character in the paragraph, it is treated exactly the same as a <br/>.

Note that FXG has no support for tab settings. It is up to the client to determine how to display tabs that come in text where collapseWhitespace is false.

Text Direction and Flow

There is a paragraph level attribute for controlling writing direction, and a container level attribute controlling horizontal/vertical text.

• direction <String> (ltr, rtl): Controls the dominant writing direction for the paragraphs (left-to-right or right-to-left), and how characters with no implicit writing direction, such as punctuation, are treated. Default is left-to-right.
• blockProgression <String> (tb, rl): Controls the direction in which lines are stacked. In Latin text, this is tb, because lines start at the top and proceed downward. In vertical Chinese or Japanese, this is rl, because lines start at the right side of the container and proceed leftward. (Note, post FXG 1.0 lockdown, the 'lr' value was removed. Some FXG processors may still reference the lr value).

Text Formatting

Formatting properties are set directly on the element as XML attributes. Properties can be inherited from the parent, but they are not applied in styles as in CSS.

Character Style Attributes

The following character style attributes can be applied to the <TextGraphic>, <p>, or <span> elements, and apply to the direct content of the element. Attributes are inherited from the parent element, if there is one, and cascade down from the TextGraphic element.

• fontFamily <String>: The font family name used to render the text. If no font is supplied, the client will pick one that is a variant of the Times family, dependent on platform. Which font is used for rendering the text is up to the client and also depends on the glyphs that are being rendered and the fonts that are available. Default value is Times New Roman (Times on Mac OS X).
• fontSize <Number>: The size of the glyphs that is used to render the text, specified in point sizes. Default is 12. Minimum 1 point. Maximum 500 points.
• fontStyle <String> (normal, italic): The style of the glyphs that is used to render the text. Legal values are 'normal' and 'italic'. Default is normal.
• fontWeight <String>(normal, bold): The boldness or lightness of the glyphs that is used to render the text. Default is normal.
• lineHeight <Percent> | <Number>: The leading, or the distance from the previous line's baseline to this one, in points. This can be specified in absolute pixels, or as a percentage of the point size. Default is 120%. Minimum value for percent or number is 0.
• tracking <Percent>: Space added to the advance after each character, as a percentage of the current point size. Percentages can be negative, to bring characters closer together. Default is 0.
• textDecoration <String> (none, underline): The decoration to apply to the text. Default is none.
• lineThrough <Boolean>: true if text has strikethrough applied, false otherwise. Default is false.
• color <Color>: The color of the text. Default is 0x000000.
• textAlpha <alpha>: The alpha value applied to the text. Default is 1.0.
• whiteSpaceCollapse <String> (preserve, collapse): This is an enumerated value. A value of "collapse" converts line feeds, newlines, and tabs to spaces and collapses adjacent spaces to one. See [Text collapse examples] for details on collapse handling. Updated:-Leading and trailing whitespace is trimmed. A value of "preserve" passes whitespace through unchanged,except as noted earlier, when the whitespace would result in an implied <p> and <span> that is all whitespace, in which case the whitespace is removed.
• lineBreak <String> (toFit, explicit): This is an enumeration. A value of "toFit" wraps the lines at the edge of the enclosing TextGraphic. A value of "explicit" breaks the lines only at a Unicode line end character (such as a newline or line separator). toFit is the default.
• kerning <String> (on, off, auto): If on, pair kerns are honored. If off, there is no font-based kerning applied. If auto, kerning is applied to all characters except Kanji, Hiragana or Katakana. The default is auto.

Otherwise characters are drawn with no pair kerning adjustments. True is the default.

Paragraph Attributes

The following paragraph attributes can be applied to TextGraphic or p elements:

• textAlign <String> (left, center, right, justify): The alignment of the text relative to the text box edges. Default is left.
• textAlignLast <String> (left, center, right, justify): The alignment of the last line of the paragraph, applies if textAlign is justify. To make a paragraph set all lines justified, set textAlign and textAlignLast to justify. Default is left.
• textIndent <Number>: The indentation of the first line of text in a paragraph. The indent is relative to the left margin. Measured in pixels. Default is 0. Can be negative.
• marginLeft <Number>: The indentation applied to the left edge. Measured in pixels. Default is 0.
• marginRight <Number>: The indentation applied to the right edge. Measured in pixels. Default is 0.
• marginTop <Number>: This is the "space before" the paragraph. As in CSS, adjacent vertical space collapses. Given two adjoining paragraphs (A, B), where A has marginBottom 12 and B has marginBottom 24, the total space between the paragraphs is 24, the maximum of the two, and not 36, the sum. If the paragraph is at the top of the column, no extra space is left for the margin. This might be different from CSS. Default is 0. Minimum is 0.
• marginBottom <Number>: This is the "spaceAfter" the paragraph. As in CSS, adjacent vertical space collapses (see note for marginTop). No margin is necessary if the paragraph falls at the bottom of the TextGraphic. Default is 0. Minimum is 0.
• direction <String> (ltr, rtl): Controls the dominant writing direction for the paragraphs (left-to-right or right-to-left), and how characters with no implicit writing direction, such as punctuation, are treated. Default is left-to-right.
• blockProgression <String> (tb, rl): Controls the direction in which lines are stacked. In Latin text, this is tb, because lines start at the top and proceed downward. In vertical Chinese or Japanese, this is rl, because lines should start at the right side of the container and proceed leftward. (Note, post FXG 1.0 lockdown, the 'lr' value was removed. Some FXG processors may still reference the lr value).

TextGraphic Attributes

These attributes can only be applied to TextGraphic.

The following attributes are the same as for all graphic element types and Group:

• rotation <Number> (ASDegrees): Defaults to 0.
• scaleX <Number>: Defaults to 1.
• scaleY <Number>: Defaults to 1.
• x <Number>: The horizontal placement of the left edge of the text box, relative to the parent grouping element. Defaults to 0.
• y <Number>: The vertical placement of the top edge of the text box, relative to the parent grouping element. Defaults to 0.
• blendMode <String> (normal, add, alpha, darken, difference, erase, hardlight, invert, layer, lighten, multiply, normal, subtract, screen, overlay): Defaults to normal.
• alpha <Number> (ASAlpha): Defaults to 1.
• id <String> (ASIdentifier): Optional, no default ("" empty string).
• transformX <Number>: Defaults to 0.
• transformY <Number>: Defaults to 0.
• maskType <String> (clip, alpha): Defaults to clip.
• visible <Boolean>: Whether or not the text box is visible. Defaults to true.

These attributes are only for TextGraphic:

• width <Number>: The width of the text box to render text in. If no width is specified, one is calculated by the client based on the content (see TextBox section for a full discussion).
• height <Number>: The height of the text box to render text in. If no height is specified, one is calculated by the client based on the content. (See TextBox section for a full discussion).
• paddingLeft <Number>: Inset from left edge to content area. Units in pixels, defaults to 0.
• paddingRight <Number>: Inset from right edge to content area. Units in pixels, defaults to 0.
• paddingTop <Number>: Inset from top edge to content area. Units in pixels, defaults to 0.
• paddingBottom <Number>: Inset from bottom edge to content area. Units in pixels, defaults to 0.

The distance from the top of the container to the baseline of the first line of text is equal to the line's ascent.

By default, the parts of a TextGraphic are transparent where text doesn't get inked.

Bitmaps

FXG uses bitmap images in two ways---either as the source data to fill a shape or path, or as a graphic element in its own right via the BitmapGraphic element.  

Source Formats

FXG supports the following image file formats as sources for BitmapGraphic or BitmapFill elements:

• GIF
• PNG
• JPG

Specifying a Source File

For both BitmapGraphic and BitmapFill elements, the source image data is defined using the source attribute.

The source attribute is specified using an @Embed directive. The format is:

source="@Embed('<imageFileName>')"

The image filename can be either a fully qualified file, url, or a relative path rooted in the same location as the FXG file. The '/' is the only legal directory separator.

FXG bitmap data is always assumed to be 32bit RGBA.  If the source data doesn't contain an alpha channel, the bitmap is assumed to be completely opaque.

BitmapGraphic Element

A BitmapGraphic element defines a rectangular region in its parent element's coordinate space, filled with bitmap data drawn from a source file.

Rendering 

The BitmapGraphic element renders its source image into a rectangle defined by in its parent coordinate system.  The default image rectangle has its top/left at the origin, with its width/height defaulting to the size of the source image.

The image rectangle can be modified by setting the x/y and width/height attributes on the BitmapGraphic element.   If the image rectangle is smaller than the source image, the bitmap is clipped to fit the rectangle.  If the image rectangle is larger, it will optionally tile the image to fill the extra space.

Attributes

• x <Number>: The left edge of the image rectangle, in the parent coordinate system. Defaults to 0.
• y <Number>: The top edge of the image rectangle, in the parent coordinate system. Defaults to 0.
• width <Number>: The width of the image rectangle, in the parent coordinate system. Defaults to the width of the source image data.
• height <Number>: The height of the image rectangle, in the parent coordinate system. Defaults to the height of the source image data.
• repeat <Boolean>: Whether the image data should be tiled to fill the image rectangle, if necessary. Defaults to true.
• source <embed reference>: An embedded reference to the file defining the image data to render. Must be a PNG, JPG, or GIF file.  Required attribute.
• visible <Boolean>: Whether or not the BitmapGraphic is visible. Defaults to true.

Children

FXG Fills, Strokes, Visibility and Blend Modes

Paths and basic shapes can be filled (which means painting the interior of the object) and stroked (which means painting along the outline of the object). Filling and stroking both can be thought of in more general terms as painting operations.

With FXG, you can fill a path or shape with:

• a solid color
• a solid color with opacity
• a gradient (linear or radial)
• a bitmap image (possibly tiled)

You can stroke a path or shape with:

• a solid color
• a solid color with opacity
• a gradient (linear or radial)

Fills

Paths and shapes are by default left unfilled. To create a filled shape, the element must have a child element of type fill. The fill element must have a single child element that must be one of the fill types listed below.  The following example specifies a solid red color fill for a rectangle:

<Rect x="20" y="20" width="300" height="300">
    <fill>
        <SolidColor color="#FF0000" />
    </fill>
</Rect>

FXG shapes and paths are always filled with an even-odd fill rule. This rule determines the "insideness" of a point on the canvas by drawing a ray from that point to infinity in any direction and counting the number of path segments from the given shape that the ray crosses. If this number is odd, the point is inside and is filled; if even, the point is outside.

Fills, Strokes, and Transforms 

Fills and strokes generally define a default bounding area that they fill, clipped by the path they are filling.  Fills and strokes can define their own user coordinate space, which defaults to the coordinate space of the object they are filling.  A fill or stroke can modify its coordinate space with transform attributes and child elements, similar to a Group, that is concatenated with its parent element's transforms to define a fill region in document coordinates.

Applying a scale-9 effect to a fill complicates the way in which the fill is transformed. See the Scale 9 section for more details. 

SolidColor Element

The SolidColor element fills a path or shape with a single solid color or solid color with opacity.

Children

None.

Attributes

• alpha <Number>: A real number value ranging from 0 to 1 specifying the opacity of the fill, with 1 being opaque. Defaults to 1.
• color <Color>: An RGB value (in the form #rrggbb) that defines the single color value to fill the shape with. Defaults to #000000.

LinearGradient

The LinearGradient element fills a path or shape with a continuously smooth color transition between a list of colors along a vector. 

The gradient vector is the vector stretching from (0,-0.5) to (0,0.5), in the coordinate space of the shape's parent grouping element's coordinate system, transformed by any matrix transformation defined on the LinearGradient.

LinearGradient Transform

The gradient vector can be modified using either discreet transform attributes on the LinearGradient element, or by providing an explicit 2D matrix transform as a child element. discreet transform attributes are useful for hand authoring, or for runtime manipulation of the gradient.  The child matrix element is useful for tools, and for more complex transforms than can be expressed by the discreet attributes.

The discreet transform attributes x, y, scaleX, and rotation are combined at runtime, if specified, to create a transform matrix that is applied to the vector stretching from (0,0) to (0,1). The vector is first scaled in the X direction by scaleX, rotated by rotation, and translated by x/y. 

Alternatively, the LinearGradient can optionally have a child element of type matrix. If this child element exists, it must have a single child element of type Matrix.  If the matrix child element is defined, it replaces the entire default transform applied to the gradient vector. 

It is illegal to define both discreet transform attributes and child matrix element on the same LinearGradient. 

The Default Transform

By default, a LinearGradient is transformed to fill the bounding box of the shape being filled.  For the purposes of the default gradient transform, the bounding box is defined to be the bounding box of the anchor points of the path, and not the control points. The gradient vector is first scaled by the width of the bounding box, rotating it around the z axis by 0, then translating it in the horizontal/vertical by the centerpoint of the bounding box.  This lets FXG define gradient fills on shapes that are dynamically modified at runtime, without requiring the runtime code to know how the shape is filled.

Any discreet transform attribute specified on the gradient overrides only that portion of the default transform.  For example, consider the following gradient:

<Rect width="200" height="100">
    <fill>
        <LinearGradient scaleX="100"/>
    <fill>
</Rect>

This example renders a rectangle whose center 100 pixels are filled with the gradient (the translation still takes place).

spreadMethod

LinearGradient elements support three methods for determining the fill colors for pixels that lay outside the gradient vector:

• pad: Pixels take on the color of the closest point on the gradient vector.
• reflect: The gradient is repeated infinitely, reversing its direction with each repeat.
• repeat: The gradient is repeated infinitely.

Gradient Entries

The colors, opacities, and their positions used in the gradient vector are defined by the GradientElement children of the LinearGradient element. These children must appear in positional order; namely, for any child GradientEntry element, its ratio attribute must be higher than the ratio attribute of the previous GradientEntry sibling.

See the GradientEntry section for more details.

Children

• GradientEntry
• matrix

Attributes

• x <Number>: The horizontal translation of the gradient transform that defines the horizontal center of the gradient.
• y <Number>: The vertical translation of the gradient transform that defines the vertical center of the gradient.
• scaleX <Number>: The horizontal scale of the gradient transform that defines the width of the (unrotated) gradient.
• rotation <Number> (<angle>): The rotation of the gradient transform.
• spreadMethod <String> (pad, reflect, repeat): How to choose the fill of pixels outside the gradient vector.
• interpolationMethod <String> (rgb, linearRGB): How to interpolate between entries of the gradient.

RadialGradient

The RadialGradient element fills a path or shape with a continuously smooth color transition between a list of colors along the radius of a circle.

The circle used is the circle bounded by the box stretching from (-0.5, -0.5) to (0.5,0.5). Like LinearGradient, it is transformed by the matrix transform defined on the gradient.

RadialGradient supports all the same transform attributes and child elements that LinearGradient does. Additionally, because its rendering is defined by a box and not just a horizontal vector, it supports a scaleY attribute that is used along with scaleX to scale the bounding box before the other transform attributes are applied.

RadialGradient elements also define the attribute focalPointRatio. This defines where along the horizontal axis (of the untransformed box) the focal point of the radial gradient lies. A value of 1 places it at the right hand edge of the box (at 0.5,0). A value of -1 places it at the left hand edge of the box (at -0.5,0).

RadialGradient elements use child GradientEntry elements the same way LinearGradient elements do.

Children

• GradientEntry
• matrix

Attributes

• x <Number>: The horizontal translation of the gradient transform that defines the horizontal center of the gradient.
• y <Number>: The vertical translation of the gradient transform that defines the vertical center of the gradient.
• scaleX <Number>: The horizontal scale of the gradient transform that defines the width of the (unrotated) gradient.
• scaleY <Number>: The vertical scale of the gradient transform that defines the width of the (unrotated) gradient.
• rotation <Number> (<angle>): The rotation of the gradient transform.
• spreadMethod <String> (pad, reflect, repeat): How to choose the fill of pixels outside the gradient vector.
• interpolationMethod <String> (rgb, linearRGB): How to interpolate between entries of the gradient.
• focalPointRatio <Number>: The placement of the focal point of the radial gradient along the horizontal center axis of the gradient bounding box. A value of 1 lies against the right edge of the box; a value of -1 lies against the left edge. The default value of 0 places it in the middle of the box.

BitmapFill

The BitmapFill element fills a path or shape with an optionally repeating bitmap image.

By default, the bitmap image is used to paint a fill rectangle stretching from (0,0) at the top left to the (width,height) of the bitmap image, in the coordinate space of the shape's parent grouping element's coordinate system, transformed by any matrix transformation defined on the Fill.

Transform

The fill rectangle can be modified using either discreet transform attributes on the BitmapFill element, or by providing an explicit 2D matrix transform as a child element. discreet transform attributes are useful for hand authoring, or for runtime manipulation of the gradient.  The child matrix element is useful for tools, and for more complex transforms than can be expressed by the discreet attributes.

The discreet transform attributes x, y, scaleX, scaleY, rotation, transformX, and transformY are combined at runtime, if specified, to create a transform matrix that is applied to the default fill rectangle. The attributes are combined into a transform by:

• Translate by -transformX, -transformY
• Scale by scaleX, scaleY
• Rotate by rotation
• Translate by x,y
• Translate by transformX, transformY

Alternatively, the BitmapFill can optionally have a child element of type matrix. If this child element exists, it must have a single child element of type Matrix.  If the matrix child element is defined, it replaces the entire default transform applied to the fill rectangle. 

It is illegal to define both discreet transform attributes and child matrix element on the same BitmapFill.  

Tiling

By default, the BitmapFill uses the supplied image data to fill the intersection of the fill rectangle and the path being filled, and leaves the remainder of the shape unpainted. You can instruct the renderer to instead fill the entire path by setting the repeat attribute of the BitmapFill to true. When set, the BitmapFill will tile the fill rectangle to fill an infinite plane with the image data.

Setting the Source Data

The Image data for a bitmap fill is specified by setting the source attribute of the element to point to an external bitmap file. The bitmap file must be in one of the supported bitmap formats for FXG, and must be specified using @Embed() syntax. See the Bitmap section for more details on supported formats. The @Embed() syntax is described in the basic types section.

Children

• matrix

Attributes

• x <Number>: The horizontal translation of the transform that defines the horizontal center of the gradient.
• y <Number>: The vertical translation of the transform that defines the vertical center of the gradient.
• scaleX <Number>: The horizontal scale of the transform that defines the width of the (unrotated) gradient.
• scaleY <Number>: The vertical scale of the transform that defines the width of the (unrotated) gradient.
• rotation <Number> (<angle>): The rotation of the transform.
• transformX <Number>: The horizontal point of origin for the scale and rotation portions of the transform.
• transformY <Number>: The vertical point of origin for the scale and rotation portions of the transform.
• source <embedded bitmap>: A reference to the file containing the image data to use as fill.
• repeat <Boolean>: Whether the image data should be rendered once, or tiled to fill an infinite plane.

Strokes

Paths and shapes are by default left unstroked. To create a stroked shape, the element must have a child element of type 'stroke'. The stroke element must have a single child element that must be one of the stroke types listed below.  To specify a solid red color stroke for a rectangle, for example:

<Rect x="20" y="20" width="300" height="300">
    <stroke>
        <SolidColorStroke color="#FF0000" />
    </stroke>
</Rect>

General Stroke Properties

Weight

A stroke applied to a shape or path paints a filled region along the screen whose midpoint lies directly on the on the path. The width of the stroke is defined in pixels by the weight property. Strokes with a transformed weight less than 1 are always rounded up to a single pixel weight when rendered.

The paint of the stroke is defined to be at a higher depth than the paint of any fill applied to the shape. This means that if the stroke is painted with a non-opaque value, the fill is seen beneath the half of the stroke that overlaps the shape.

The stroke is painted as though it were a filled shape itself, defined by the silhouette of the stroke region. This means that where the stroke overlaps itself, it is only painted a single time. Specifically, if the stroke is painted with a non-opaque value, the overlapping region will appear the same as a non-overlapping region rather than as a region painted twice with semi-transparent paint.

Scale Mode

A stroke is extrapolated from a path or shape after the points have been converted into document coordinate space.  Generally, the local transform of the shape isn't applied to the stroke. However, during painting, the weight of the paint applied to the transformed shape is adjusted to match the scale factor in the shape's transform matrix. How the scale factor affects the weight of the stroke is controlled by the stroke's scale mode. Strokes support the following scale modes:

• normal: Scale the stroke outline using the scale component of the current coordinate transformation.
• none: No scale is applied to the stroke weight.
• vertical: The weight of the stroke is scaled by the vertical scale component of the transform applied to the shape. The horizontal scale component has no effect on the stroke weight.
• horizontal: The weight of the stroke is scaled by the horizontal scale component of the transform applied to the shape. The vertical scale component has no effect on the stroke weight.

When the weight is scaled, a processor first extracts the x and y scale factor from the stroke's user space composite matrix (sx,sy) and transforms the weight w, as the following example shows:

t = sqrt(((w*sx)^2 + (w*sy)^2) / 2)
weight_in_document_space = Max(1,t);

When the scaleMode attribute is set to horizontal, the sy value in the above equation is constant at 1.  When the scaleMode attribute is set to vertical, the sx value is held constant at 1.

End Caps

FXG strokes support three types of end caps when painting strokes, specified with the caps attribute. Legal values are:

• none: The stroke ends exactly where the path ends.
• round: The stroke end is capped with a half circle whose diameter matches the weight of the stroke.
• square: The stroke end is capped with a half square whose side-length matches the weight of the stroke.

Joint Style

FXG strokes support three ways of rendering the joints between path segments, specified with the joints attribute. Legal values are:

• bevel: The joint is capped by the line running through the joint perpendicular to the line bisecting the joint angle.
• miter: The joint is rendered by slicing the stroke of the two joining segments with the outer edge of the opposite segment's stroke.
• round: The joint is rendered with a circle whose diameter matches the weight of the stroke centered on the joint.

FXG strokes also support the miterLimit attribute. This is a numeric value that imposes a limit on the ratio between the stroke weight and the miter length. When the limit is exceeded, the join is converted from a miter to a bevel. Valid values range from 0 to 255.

SolidColorStroke

The SolidColorStroke element represents a stroke painted with a solid color, or a solid color with opacity. It is similar to the SolidColor fill type.

Children

None.

Attributes

• alpha <Number>: A real number value ranging from 0 to 1 specifying the opacity of the stroke, with 1 being opaque. Defaults to 1.
• caps <String> (round, square, none): Specifies the type of caps at the end of lines.
• color <Color>: An RGB value (in the form #rrggbb) that defines the single color value to stroke the shape with. Defaults to #000000.
• joints <String> (round, miter, bevel): Specifies the type of joint appearance used at angles.
• miterLimit <Number>: Indicates the limit at which a miter is cut off. Valid values range from 0 to 255. Defaults to 0.
• pixelHinting <Boolean>: Specifies whether to hint strokes to full pixels. This value affects both the position of anchors of a curve and the line stroke size itself. Defaults to false.
• scaleMode <String> (normal, none, horizontal, vertical): A value that specifies which scale mode to use. Defaults to "normal".
• weight <Number>: The line weight, in pixels. Defaults to 1.

LinearGradientStroke

The LinearGradientStroke paints a stroke along a path or shape with a continuously smooth color transition between a list of colors along a vector. 

The LinearGradientStroke operates almost identically to the LinearGradient fill type. As with the fill, By default, a LinearGradientStroke is transformed to fill the bounding box of the path being stroked. The bounding box is computed by computing the bounding box of the anchor points of the path, and expanding its borders outward in each direction by half the weight of the stroke.

Otherwise its rendering behavior is identical to that of the LinearGradientFill.

Children

• matrix
• GradientEntry

Attributes

• x <Number>: The horizontal translation of the gradient transform that defines the horizontal center of the gradient.
• y <Number>: The vertical translation of the gradient transform that defines the vertical center of the gradient.
• scaleX <Number>: The horizontal scale of the gradient transform that defines the width of the (unrotated) gradient.
• rotation <Number> (<angle>): The rotation of the gradient transform.
• spreadMethod <String> (pad, reflect, repeat): How to choose the fill of pixels outside the gradient vector.
• interpolationMethod <String> (rgb, linearRGB): How to interpolate between entries of the gradient.
• scaleMode <String> (normal, none, vertical, horizontal): A value that specifies which scale mode to use. Defaults to "normal".
• caps <String> (none, round, square): A value that specifies the type of caps at the end of lines. Defaults to "none".
• joints <String> (bevel, miter, round): A value that specifies the type of joint appearance used at angles. Defaults to "round".
• miterLimit <Number>: A number that indicates the limit at which a miter is cut off. Valid values range from 0 to 255.

RadialGradientStroke

The RadialGradientStroke element paints a stroke along a path or shape with a continuously smooth color transition between a list of colors along the radius of a circle.

The RadialGradientStroke operates almost identically to the RadialGradient fill type. As with the fill, by default a RadialGradientStroke is transformed to fill the bounding box of the path being stroked. The bounding box is computed by computing the bounding box of the anchor points of the path, and expanding its borders outward in each direction by half the weight of the stroke.

Otherwise its rendering behavior is identical to that of the RadialGradientFill.

Children

• matrix
• GradientEntry

Attributes

• x <Number>: The horizontal translation of the gradient transform that defines the horizontal center of the gradient.
• y <Number>: The vertical translation of the gradient transform that defines the vertical center of the gradient.
• scaleX <Number>: The horizontal scale of the gradient transform that defines the width of the (unrotated) gradient.
• scaleY <Number>: The vertical scale of the gradient transform that defines the width of the (unrotated) gradient.
• rotation <Number> (<angle>): The rotation of the gradient transform.
• spreadMethod <String> (pad, reflect, repeat): How to choose the fill of pixels outside the gradient vector.
• interpolationMethod <String> (rgb, linearRGB): How to interpolate between entries of the gradient.
• focalPointRatio <Number>: The placement of the focal point of the radial gradient along the horizontal center axis of the gradient bounding box. A value of 1 lies against.
• scaleMode <String> (normal, none, vertical, horizontal): A value that specifies which scale mode to use. Defaults to "normal".
• caps <String> (none, round, square): A value that specifies the type of caps at the end of lines. Defaults to "round".
• joints <String> (bevel, miter, round): A value that specifies the type of caps at the end of lines. Defaults to "round".
• miterLimit <Number>: A number that indicates the limit at which a miter is cut off. Valid values range from 0 to 255.

GradientEntry

The GradientEntry element defines a stop in the list of colors used to render a gradient in a fill or stroke. A GradientEntry element must appear as a direct child of one of the four gradient fill or stroke types.

Each entry defines three values used in the gradient rendering: an RGB color value, an opacity value, and a position along the gradient vector (defined by the ratio attribute). When rendering the gradient, the entry specifies that the rendering at its ratio must exactly match its color and opacity. The gradient uses its assigned interpolation method to transition the color between the entry and its nearest neighbors.

GradientEntry elements can leave their ratio unspecified. If no ratio is assigned, the Gradient will automatically determine an appropriate value when rendering. If the first entry in a gradient has no specified ratio, it is assumed to be 0. If the last entry has no ratio, it assumed to be 1. If the gradient contains other entries with no ratio specified, they are distributed evenly between the ratios of the most immediate entries before and after that have definite values.

In the following example, there are two gradient entries with no specified ratio. Their nearest left and right neighbors with ratios specified define a range from 0.1 to 0.7. The two unspecified gradients would be distributed across this range, placing them at 0.3 and 0.5:

<LinearGradient ... >
    <GradientEntry ratio="0" />
    <GradientEntry ratio="0.1" />
    <GradientEntry />
    <GradientEntry />
    <GradientEntry ratio="0.7" />
</LinearGradient>

In the following example, none of the entries have specified ratios. The first entry is automatically placed at ratio 0, and the last at ratio 1. That leaves three unspecified ratios to be distributed across the defined range 0-1, placing them at 0.25, 0.50, and 0.75:

<LinearGradient ... >
    <GradientEntry />
    <GradientEntry />
    <GradientEntry />
    <GradientEntry />
    <GradientEntry />
</LinearGradient>

Each GradientEntry must either have no defined ratio or have a ratio larger than that specified by any of its previous sibling GradientEntry elements.

A gradient in FXG cannot have more than 16 GradientEntry elements in its definition.

Children

None.

Attributes

• color <Color>: An RGB value specifying the color that should be used at that point in the gradient. Defaults to #000000.
• alpha <Number>: A number from 0-1 specifying the opacity that should be used at that point in the gradient. Defaults to 1.
• ratio <Number>: A value from 0-1 specifying where on the gradient the entry should be pinned.

Visibility

FXG elements can control whether or not they are visible by specifying a visible attribute, which defaults to true. The visibility of a graphical element is defined by the visible attribute of the element and all of its parent elements. That is, if any parent of the element is hidden, that element is not rendered. Non-visible graphical elements still exist and are considered for any bounding box calculations necessary to render the document.

For example, if the size of the root Graphic element is left unspecified, it is calculated as the bounding box of all of the content in the document, including any non-visible content. To prevent non-visible elements from affecting the bounding box calculations, the global bounding box can be specified explicitly.

Blend Modes and Opacity

FXG elements can control how their content is composited with the background by specifying a blendMode attribute.

Grouping elements are rendered in one of two different ways, depending on their blend mode. A grouping element with a blend mode of 'normal' acts only as a transformation on the elements contained within. Its 2D transform, color transform, and opacity are multiplied down into its child elements, where they are combined with any local values to render the child element into the current surface. This has a visible effect on the use of opacity in an FXG document, as the following example shows:

<Group blendMode="normal" opacity="0.5">
    <Rect x="100" y="100" width="100" height="100">
        <fill>
            <SolidColor color="#FF0000" />
        </fill>
    </Rect>
    <Rect x="0" y="0" width="200" height="200">
        <fill>
            <SolidColor color="#0000FF" />
        </fill>
    </Rect>
</Group>

The opacity of the group would multiply down into the two child rectangles. The larger, frontmost blue rectangle would render with a 50% opacity, revealing the smaller red rectangle underneath.

All other blend modes force the group to act as a temporary compositing surface onto which its child elements are rendered. The surface is initialized to transparent black, and the child elements are composited in. The temporary surface is then composited into the grouping element's parent's surface, applying the grouping element's opacity, color transform, and 2D transform in the process.

Shape elements are affected similarly by their blendMode setting. A shape with a blendMode of normal composite transforms into the fill and stroke of the shape, which are rendered into the current surface. Any other blendmode type will effectively render its fill and stroke into a temporary compositing surface, which is then composited into the parent surface using the shape's color transform.

The default blendMode of an element is 'layer.' (Note, this change was made post FXG 1.0 lockdown, so some processors may reference a default blendMode of 'normal').

FXG supports the following blend modes:

Color Transformations

Color Transformations are a high performance way to modify the color of an FXG group or shape element. A color transform can be used, for example, to tint a group, adjust its brightness, or modify its opacity.

Rendering

Color transforms are applied to the rendering of a group or shape element after any bitmap filters are applied; color transforms will affect the output of a filter (such as tinting the drop shadow). They are applied before the group element is composited with its background;  blend modes use the transformed color value when combining the group with the background content.

A ColorTransform element can specify multipliers and offsets for each individual channel of the RGBA rendering of a group element.  It is similar to a 5x5 matrix where only the diagonal (scale) values and right column (translation) are exposed---all other coefficients are set to zero.

Color Attributes vs. Color Transforms

Group and shape elements support both color transform child elements, as well as convenient color transform attributes (specifically, alpha).  As with the geometry transform, an individual element can use either attributes or child elements to define its color transform, but not both.  The alpha attribute corresponds to the alpha multiplier in the ColorTransform; there are no convenience attributes for defining the other coefficients of the matrix.

ColorTransform elements are only legal on shapes and Group instances---either an in-place group or a PlaceObject tag. They can not be placed in a group whose direct parent is in a definition element.

Defining a Color Transform

The following example shows how a group defines a color transform:

<Group>
    <transform>
        <Transform>
            <colorTransform>
                <ColorTransform redMultiplier="0.5" redOffset="20" />
            </colorTransform>
        </Transform>
    </transform>
</Group>

An element can optionally have a single child element of type transform. If present, the transform element must have a single child element of type Transform. The Transform element can optionally have a single child element of type colorTransform. The colorTransform element must have a single child element of type ColorTransform.

Attributes

• alphaMultiplier <Number>: A decimal value that is multiplied with the alpha transparency channel value. Defaults to 1.  
• alphaOffset <Number>: A number from -255 to 255 that is added to the alpha transparency channel value after it has been multiplied by the alphaMultiplier value. Defaults to 0.
• blueMultiplier <Number>: A decimal value that is multiplied with the blue transparency channel value. Defaults to 1.
• blueOffset <Number>: A number from -255 to 255 that is added to the blue transparency channel value after it has been multiplied by the blueMultiplier value. Defaults to 0.
• greenMultiplier <Number>: A decimal value that is multiplied with the green transparency channel value. Defaults to 1.
• greenOffset <Number>: A number from -255 to 255 that is added to the green transparency channel value after it has been multiplied by the greenMultiplier value. Defaults to 0.
• redMultiplier <Number>: A decimal value that is multiplied with the red transparency channel value. Defaults to 1.
• redOffset <Number>: A number from -255 to 255 that is added to the red transparency channel value after it has been multiplied by the redMultiplier value. Defaults to 0.

Children

None.

Masking

FXG supports applying a clipping mask to any instance group element.  A clipping mask is a subtree of graphical FXG, contained in a Group tag, and defines the region in which the group's content is rendered.

Clipping vs. Alpha

FXG supports two different forms of masking: clipping and alpha. 

Clip Masking

When masking in clip mode, a clipping mask is reduced to 1-bit.  This means that a mask will not affect the opacity of a pixel in the source content; it either leaves the value unmodified, if the corresponding pixel in the mask is has a non-zero alpha value, or makes it fully transparent, if the mask pixel value has an alpha value of zero.

When clip masking is used, only the actual path, shape vectors, and fills defined by the mask are used to determine the effect on the source content. Strokes and bitmap filters defined on the mask are ignored. Any filled region in the mask is considered filled, and renders the source content.  The type and parameters of the fill is irrelevant;  a solid color fill, gradient fill, or bitmap fill in a mask will all render the underlying source content, regardless of the alpha values of the mask fill.

BitmapGraphic elements are treated as bitmap filled rectangles when used in a clipping mask.  As a result, the alpha channel of the source bitmap is irrelevant when part of a mask---the bitmap affects the mask in the same manner as solid filled rectangle of equivalent dimensions.

Alpha Masking 

In alpha mode, the opacity of each pixel in the source content is multiplied by the opacity of the corresponding region of the mask. For example, a pixel in the source content with an opacity of 1 that is masked by a region of opacity of 0.5 will have a resulting opacity of 0.5. A source pixel with an opacity of 0.8 masked by a region with opacity of 0.5 will have a resulting opacity of 0.4.

Conceptually, alpha masking is equivalent to rendering the transformed mask and source content into separate RGBA surfaces, and multiplying the alpha channel of the mask content into the alpha channel of the source content.  All of the mask content is rendered into its surface before compositing into the source content's surface. As a result, all FXG features, such as strokes, bitmap filters, and fill opacity will affect the final composited content.

When in alpha mode, the alpha channel of any bitmap data is composited normally into the mask alpha channel, and will affect the final rendered content. This holds true for both BitmapGraphic elements and bitmap filled shapes and paths.

Specifying a Mask

A Group, Graphic Path or shape object can support masks by defining a single child element of type 'mask'. If the mask child element exists, it must contain a single child element---either a Group instance element or a PlaceObject element.

The path data of the specified mask defines the clipping mask.   

The masking element inherits the target group's coordinate space, as though it were a direct child element.  It can be further modified with the standard group transform attributes or child elements.  The masking element is not rendered in the output.

The type of masking used is determined via the maskType attribute. legal values are 'clip' and 'alpha'. The default value is clip.

<Group maskType="clip">
    <mask>
        <Group x="10" y="10" scaleX="3" scaleY="3">
            <Ellipse x="20" y="20" width="30" height="10">
                <fill>
                    <SolidColor color="#000000" />
                </fill>
            </Ellipse>
        </Group>
    </mask>

    <Rect width="150" height="150">
        <fill>
            <SolidColor color="#FF0000" />
        </fill>
    </Rect>
</Group>

Filter Effects

Bitmap Filters

FXG supports bitmap filter effects to be defined on shapes and grouping elements. A filter effect consists of a series of graphic operations applied to the rendered graphic of a grouping element and its children before compositing it into the background.

Filter effects are operations performed on a bitmap, and hence require an element to be pre-rendered into a temporary surface before being composited into the background.  This has an effect on how blend modes and opacity are treated on the group and its contents.  Adding a filter to an element with a blend mode of normal forces it to render as though it had a blend mode of 'layer.'

Filters are applied to an element after its content is rendered, but before it is composited into the background. This means that opacity, blend modes, and color transforms defined on the group are all applied to the output content of the filter.

Filters can only be defined on shapes and group instances, not group definitions. That means they can be defined on a Group tag placed as an immediate child of a Graphic or other Group tag, or as a child of a PlaceObject tag referencing a defined group.

Filters are defined on an element by defining a filters element as an immediate child.  The filters element must contain one or more of the pre-defined bitmap filter types.  Bitmap filters are applied to the rendered content of the element in the order they appear in the document---the first filter modifies the rendered content, the second filter modifies the output of the first filter, etc.

The following sections contain an overview of each of the bitmap filters defined by FXG.

 Bitmap Filters and Transforms

Bitmap filters are applied to the group content after it has been transformed into the document coordinate system by applying the composite transform of the group instance and all of its parent elements.  Scale, Rotation, and Skew transforms on content affect the input bitmap the group's filter list is applied to, but not the output bitmap.  Take the following three groups as an example:

<Group>
   <Group>
      <filters>
         <BlurFilter  />
      </filters>
      <Group scaleY="3">
         <Rect>
            ...
         </Rect>
      </Group>
   </Group>
</Group>

<Group>
   <Group scaleY="3">
      <filters>
         <BlurFilter  />
      </filters>
      <Group>
         <Rect>
            ...
         </Rect>
      </Group>
   </Group>
</Group>

<Group scaleY="3">
   <Group>
      <filters>
         <BlurFilter  />
      </filters>
      <Group>
         <Rect>
            ...
         </Rect>
      </Group>
   </Group>
</Group>

In all three examples, the final size of the transformed, rendered 'blurred' group is the same. Because the blur filter is applied after the group is transformed, the final rendered filtered output is the same, regardless of where the scale factor is applied.

Filter Types

The following sections contain an overview of each of the bitmap filters defined by FXG.

quality

Most of the filters below define a 'quality' attribute. This attribute defines the level of oversampling performed when applying the filter.  The quality attribute can take the following values:

• 1: no oversampling
• 2: 2x2 = 4X oversampling
• 3: 4x4 = 16X oversampling

BlurFilter

Applies a blur effect to the input element.

Attributes

• blurX <Number>: The amount of blur applied to the rendered content in the horizontal.
• blurY <Number>: The amount of blur applied to the rendered content in the vertical.
• quality <Number>: The quality of the rendered effect.

DropShadowFilter

Applies a drop shadow to the input element.

Attributes 

• alpha <Number>: The transparency of the generated effect.
• angle <Number>: The angle of the generated drop shadow. This angle is expressed in document coordinate space.
• blurX <Number>: The amount of blur applied to the rendered content in the horizontal.
• blurY <Number>: The amount of blur applied to the rendered content in the horizontal.
• color <Color>: The color of the rendered drop shadow.
• distance <Number>: The distance between each pixel in the source and its corresponding shadow in the output.
• inner <Boolean>: If true, drop shadow values are rendered above the original source content, and masked by the original content. If false, it is rendered below the original content.
• hideObject <Boolean>: If true, the original content is not copied into the final output.
• knockout <Boolean>: Renders the effect only where the value in the original content was 100% transparent. All other pixels are 100% transparent.
• quality <Number>: The quality of the rendered effect.
• strength <Number>: The strength of the imprint or spread. The higher the value, the more color is imprinted and the stronger the contrast between the shadow and the background. Valid values are from 0 to 255.0. The default is 1.0.

BevelFilter

Applies a Bevel effect to the input element.

Attributes 

• angle <Number>: The angle of the generated bevel. This angle is expressed in document coordinate space.
• blurX <Number>: The amount of blur applied to the rendered content in the horizontal.
• blurY <Number>: The amount of blur applied to the rendered content in the vertical.
• highlightAlpha <Number>: The transparency of the generated highlight color.
• highlightColor <Color>: The color of the generated highlight color.
• distance <Number>: The height of the bevel.
• knockout <Boolean> Renders the effect only where the value in the original content was 100% transparent. All other pixels are 100% transparent.
• quality <Number>: The quality of the rendered effect.
• shadowAlpha <Number>: The transparency of the generated shadow of the bevel.
• shadowColor <Color>: The color of the generated shadow of the bevel.
• strength <Number>: The strength of the imprint or spread. The higher the value, the more color is imprinted and the stronger the contrast between the bevel and the background. Valid values are from 0 to 255.0. The default is 1.0.
• type <String> (inner, outer, full): The placement of the bevel on the object. Defaults to "inner".

GradientGlowFilter

Applies a Glow effect to the input element, using a specified gradient to fill the glow rather than a single color.

The gradient used in a GradientGlow is specified using child GradientEntry elements. See the section on gradient fills for more details.

Attributes 

• angle <Number>: The angle of the generated glow. This angle is expressed in document coordinate space.
• blurX <Number>: The amount of blur applied to the rendered content in the horizontal.
• blurY <Number>: The amount of blur applied to the rendered content in the horizontal.
• distance <Number>: The offset between the element content and the rendered glow in the output.
• inner <Boolean>: If true, glow values are rendered above the original source content, and masked by the original content. If false, it is rendered below the original content.
• knockout <Boolean>: Renders the effect only where the value in the original content was 100% transparent. All other pixels are 100% transparent.
• quality <Number>: The quality of the rendered effect. Defaults to 1.
• strength <Number>: The strength of the imprint or spread. The higher the value, the more color is imprinted and the stronger the contrast between the glow and the background. Valid values are 0 to 255. The default is 2.

Children

• GradientEntry

GradientBevelFilter

Applies a Bevel effect to the input element, using a specified gradient to fill the bevel rather than a highlight and shadow color.

The gradient used in a GradientBevel is specified using child GradientEntry elements. See the section on gradient fills for more details.

Attributes 

• angle <Number>: The angle of the generated bevel. This angle is expressed in document coordinate space.
• blurX <Number>: The amount of blur applied to the rendered content in the horizontal.
• blurY <Number>: The amount of blur applied to the rendered content in the horizontal.
• distance <Number>: The height of the bevel.
• knockout <Boolean> Renders the effect only where the value in the original content was 100% transparent. All other pixels are 100% transparent.
• quality <Number> The quality of the rendered effect.
• strength <Number> The strength of the imprint or spread. The higher the value, the more color is imprinted and the stronger the contrast between the bevel and the background. Valid values are from 0 to 255.0. The default is 1.0.
• type <String> (inner, outer, full): The placement of the bevel on the object. Defaults to "inner".

Children

• GradientEntry

ColorMatrixFilter

The ColorMatrixFilter class lets you apply a 4x5 matrix transformation on the RGBA color and alpha values of every pixel in the input image to produce a result with a new set of RGBA color and alpha values. It allows saturation changes, hue rotation, luminance to alpha, and various other effects.

Attributes 

• matrix: A comma-delimited list of 20 doubles that comprise a 4x5 matrix applied to the rendered element.  The matrix is in row major order---that is, the first five elements are multiplied by the vector [srcR,srcG,srcB,srcA,1] to determine the output red value, the second five determine the output green value, etc.

Scale-9

As a language targeted at describing rich interactive graphics, one major use of FXG is to describe the appearance of user interface controls.  Most applications define a single look for common elements of their user interface that can grow dynamically to be used at different sizes in different contexts.  The resizing process for these elements is such a common design pattern in interactive graphics that FXG has a specific feature to support it.

Imagine a designer creating a graphic to be used as a resizable panel control.  As the panel resizes, the four corners of the design typically would maintain a constant size, moving out to stay aligned into the corners of the panel's region on screen. The four edges of the panel would maintain a constant size in one direction, and  stretch in the other--the horizontal edges stretching horizontally, the vertical edges stretching vertically--to fill the space between the aligned corners.  The center region of the panel would stretch in both directions to fill the remained of the panel's region on screen.

Using FXG, a designer can specify this exact behavior on a group instance element.  The designer specifies a scale-9 grid that defines how the group content is sliced up at rendering time into corners, edges, and center content; the FXG processor uses the scale grid to apply the scale-9 algorithm when resizing the content.

Implementation Issue

The proposed ActionScript implementation has a use case that it can not accurately implement.

Naming

When a developer writes code to manipulate an FXG document in an interactive environment, they want to limit the amount that their code depends on the structure of the document to function. While some structure can be dictated by how the developer will code against it, portions of the FXG are irrelevant to the task the code is trying to accomplish. 

Forcing the code to traverse irrelevant structure to reach the portion it does care about it a recipe for fragile brittle code. 

Defining Contracts 

Instead, FXG allows a document author to identify specific elements in the document by name. 

An interactive environment supporting FXG (such as Flex) can provide APIs for the developer to reference specifically named elements, insulating them from changes in the overall structure of the document. A designer and developer will typically agree upon a set of required elements names (and potentially types).

This agreement defines a contract between the design and the logic.

Setting the id Attribute

Defines its own naming attribute, the 'id' attribute.

An id attribute on an element assigns a well defined name to that element. The value of an id attribute must be unique within the definition scope in which it appears. The FXG document creates its own definition scope. Each definition tag within the FXG library create a new definition scope.  ids are never visible across definitions scopes. The same id value can appear in the main document structure as well as within a library definition.

The value of the id attribute must be a valid ActionScript identifier. An id value should not contain spaces, start with a number, be a single number, or be a reserved ActionScript keyword.

Where id Attributes Can Appear 

The elements defined by FXG fall into three broad categories:

• content elements: Elements such as <Group>, <Rect>, <SolidColor> define actual content that typically appear in or directly affect the rendering of an FXG document.  These are the bulk of the elements defined.
• relationship elements: Elements such as <fill>, <stroke>, and <transform> exist to define a relationship between a parent element and a child element.  <fill>, for example, indicates that the <SolidColor> element it contains is used as the fill for the <Rect> it is contained by. 
• control elements: Elements such as <mxml>, <library>, <definition> control how a section of the document are processed, and don't directly define content.

FXG processors are generally meant to expose FXG as content, necessarily as a document model.  When exposing FXG as content, relationships and control structure generally are exposed as context, rather than as objects that can be named (unlike a document model, where each element is exposed as an element, independent of its function).  As a result, id names are only allowed on content elements.

Symbol (Definition) names

See: [FXG Name Mangling]

Versioning

The FXG format includes a version number for identifying what revision of this specification the document conforms to.  The version number is specified as a required 'version' attribute on the root Graphics tag of any FXG file.

The version number must be read as a decimal value.  The integer portion of the version represents the major version of the document, while the fractional portion corresponds to the minor version.

The values of versions should be compared as real values, not an integer values.  Thus, a version attribute of "5.200" represents a major version 5, with a minor version of 2.  "5.200" and "5.2" represent equivalent version numbers. "5.2" is a newer version number than "5.100".

Responding to version numbers 

Each FXG processor implements/conforms to one or more versions (major.minor). An FXG processor should treat unknown major and minor versions as follows:

• An unknown major version number represents a change to the FXG syntax such that a parser based on an earlier major version number could not be expected to reasonably understand and represent the file. Alternatively, a different major version number might represent such a significant change to the content that can appear in an FXG file that a parser based on an earlier major version would fail to understand a significant portion of the content in the file. Processors discovering an later major version number SHOULD report the version mismatch to the user. Processors MAY offer to attempt to process the file regardless.
• An unknown minor version number represents a small change to the FXG format.  The change can be one of syntax or content.  A processor based on an earlier minor version number should be able to render the file with little or no loss of fidelity.

Processors discovering a later minor version number MUST ignore unknown attributes and elements for rendering and SHOULD preserve them in round-tripping use cases. Known elements that are descendents of an unknown element MUST be ignored for rendering and SHOULD be preserved for round-tripping.

Processors that discover attribute values that are out of range or have unexpected values (e.g., an enum value that does not match the enumeration constraint for the version the processor conforms to) SHOULD ignore those values and/or substitute default values for rendering and MUST preserve the original values for round-tripping use cases.

Processors discovering a later minor version MAY report the version mismatch and MAY report unknown elements, unknown attributes, or known attributes with unexpected values, to the user after processing. Recommended best practice is to avoid sending the user too many notifications; you should keep the reporting of unknowns to a minimum.

Processors MUST preserve and write (export) the original version number when round-tripping unknown elements or attributes. For example, a user imports/opens a 1.1 file with a 1.0 processor. The 1.1 file contains a <Foo> tag, which is unknown to 1.0 processors. The 1.0 processor shows the contents of the file, ignoring the <Foo> tag and all of its children. The user adds some text to the file in a way that does not disturb the <Foo> tag or its contents (as far as the 1.0 processor can tell). The user then saves the FXG file again. If the saved file includes the <Foo> tag, it MUST have the original version number also, which is 1.1