Adobe Experience Cloud Scene7 FXG

Transcription

1 Adobe Experience Cloud Scene7 FXG

2 Contents Scene7 FXG What's New in Scene7 FXG FXG Basic Concepts...8 FXG Rendering...9 The Rasterization Model...9 Types of Graphics Elements...9 Painting Shapes...9 Painting Strokes...10 Painting Raster Images...10 Clipping, Masking, and Object Opacity...10 Basic Data Types...11 Basic Data Type Categories...11 Invalid Identifiers for FXG Document Structure...15 Defining an FXG Document Fragment...15 Element Types...15 The Graphic (Root) Element...16 The Group Element...17 Group Instances Versus Definitions...18 Symbols, Instances, and the Library Element...19 The Library Element...20 The Definition Element...20 ThePlaceObject Element...20 Last updated 10/23/2017 Scene7 FXG

3 Contents Coordinate Space Transformations...22 User Coordinate Systems...22 Transformations as Instance Group Properties...22 Transform Element...23 Matrix Element...23 Shapes_ Bounds, Fill, and Stroke Calculations...24 FXG Paths...26 Path Element...26 Path Data...27 moveto...28 closepath...29 lineto...29 Curve Commands...30 Basic FXG Shapes...32 Rect Element...32 Ellipse Element...34 Line Element...35 FXG Text...38 RichText Element...38 div Element...41 Paragraph Element...42 a Element...42 Link Format Elements...43 TextLayoutFormat Element...44 tcy Element...44 img Element...45 span Element...45 br Element...45 tab Element...46 Last updated 10/23/2017 Scene7 FXG

4 Text Box...46 Fidelity...47 Text Rendering...47 Font References...47 Units of Measurement...47 Text Character Set...48 Whitespace Handling...48 Text Formatting...49 Inheritance Model...49 Formatting Attributes...49 Character-Level Attributes...49 Paragraph-Level Attributes...56 Container-Level Attributes...60 Bitmaps...63 Specifying a Source File...63 BitmapImage Element...64 FXG Fills, Strokes, Visibility, and Blend Modes...66 Fills...66 Fills, Strokes, and Transforms...66 SolidColor Element...66 LinearGradient Element...67 RadialGradient Element...69 Bitmap Strokes, Color, Masking, and Transforms...71 Strokes...71 General Stroke Properties...71 SolidColorStroke Element...72 LinearGradientStroke Element...73 RadialGradientStroke Element...74 GradientEntry Element...75 Visibility of Graphical Elements...77 Last updated 10/23/2017 Scene7 FXG

5 Contents Blend Modes and Opacity...77 Blend Modes...78 Color Transformations...79 Masking...81 Clipping, Alpha, and Luminosity...81 Specifying a Mask...82 Determining the Type of Mask...82 Reference Points...83 Naming...86 Versioning...87 Color Management (S7FXG Only)...88 s7:colorsettings (S7FXG Only)...88 s7:documentsetup (S7FXG Only)...88 s7:colordefinitions (S7FXG Only)...89 s7:color (S7FXG Only)...89 Scene7 Variables (S7FXG Only)...90 Server and Plug-In Limitations...91 Server-side limitations...91 Plug-In Limitations...91 Last updated 10/23/2017 Scene7 FXG

6 Scene7 FXG Scene7 FXG 2.0 This document outlines the Scene7 version of the FXG 2.0 specification. Scene7 FXG 2.0 adds private attributes in flm, ATE, and the Scene7 namespace. Note: Throughout this document, features that are specific to Scene7 FXG are marked S7FXG Only. Scene7 FXG differs from FXG because it must support web-to-print capabilities. These capabilities include color management, CMYK color spaces, Scene7 embedded URLs, and print settings. FXG 2.0 describes an XML-based graphics interchange format for the Adobe 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. This specification delves into the technical details governing every element of FXG 2.0. For information about the FXG Server protocol, see FXG Server Protocol.

7 What's New in Scene7 FXG What's New in Scene7 FXG 2.0 Following is a description of what is new in Scene7 FXG 2.0. Support for TLF text (except for a few attributes) Scene7 FXG 2.0 supports TLF text. Most of the attributes and elements of the TLF specification are supported. Color model that supports CMYK, gray, lab, spot, and globally defined colors To make handling color spaces other than RGB easier, Scene7 FXG 2.0 supports CMYK, gray, lab, and spot colors, as well as globally defined process colors. Clipping, alpha, and luminosity masking (not with text elements) Scene7 FXG 2.0 supports three different forms of masking: clipping, alpha, and luminosity. New fit modes for BitmapImage Scene7 FXG 2.0 supports these new fit modes for BitmapImage: clip and repeat. Better implementation of gradients, allowing colors at different points to have different color spaces The mid-point attribute has been added to the GradientEntry element. This attribute allows one-to-one mapping between Scene7 FXG and Illustrator and InDesign. As in InDesign, different gradient entries within a single gradient can have color specified in different color spaces. Improved support of text on path and text inside path (using reference ids) In FXG 1.0, path data was emitted as a private attribute in the TextGraphic element. Consequently, users had to modify path data at two places in order to modify the path. Moreover, attributes such as x, y, scalex, scaley, rotation, if the user changed them on the path element, would not automatically affect the text element placement. With the current approach, however, this workflow is much smoother. Support for Adobe Illustrator-type point text There are few basic differences between FXG point text and Illustrator point text. With the addition of the new private attribute s7:aipointtext=<true/false>, users can have both workflows. They can treat point text as it is treated in Illustrator.

8 FXG Basic Concepts 8 FXG Basic Concepts This topic defines basic FXG concepts. Concept Graphical objects Definition FXG provides common, basic shapes with the Path, Rect, and Ellipse elements for graphical objects. 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 reuse multiple symbols within a single FXG document. A symbol defines a named grouping element containing graphical elements, grouping elements, and other symbols. After a symbol is defined in an FXG file, it can be referenced by name in the same file. Symbols can be used at different sizes and orientations. They 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, weight, and style; they rely on the rendering environment to provide the matching font definition.

9 FXG Rendering 9 FXG Rendering The FXG 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. These features 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 deviates slightly due to limitations of the environment. (For example, 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). Implementation can also deviate slightly due to practical limitations in implementing a precise mathematical model (for realistic performance, for example, curves are approximated by straight lines). Following 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 approach 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. Compared to the painters model approach, the use of a single rasterization pass makes for subtle differences in the way that the edge of a shape is composited with the background, especially when two edges are coincident. The FXG rasterization model matches Flash Player's closed-open model. 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. Types of Graphics Elements FXG supports three fundamental types of graphics elements that can be rendered onto the canvas. Shapes represent some combination of straight line and curves. Text represents some combination of character glyphs. Raster images represent an array of values that specify the paint color and opacity (often termed alpha) at a series of points on a rectangular grid. Raster images are pulled from a Scene7 IS or IR server. Scene7 FXG supports embedded FXGs. Painting Shapes Shapes can be filled (paint applied to the interior of the shape) and stroked (paint applied along the outline of the shape).

10 FXG Rendering 10 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 the other half falls on the outside. Each fill and stroke operation has its own opacity settings. You can fill 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. <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 that the shape is defined in. Instead, a processor typically first transforms the points of a path into document space, then applies 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 and stroke operations: Solid color Gradient (linear and radial) 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. 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. See Masking. 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 as though the masked element had no mask applied.

11 Basic Data Types 11 Basic Data Types This section describes basic data types for elements and attributes of FXG 2.0 and also the names FXG 2.0 does not allow as valid identifiers. Basic Data Type Categories This topic describes the basic data type categories for FXG's elements and attributes. Data type category <angle> Description An angle value is an arbitrary <number> specified as degrees. Angles are clockwise. <boolean> A <boolean> is specified as data type that can have one of two values: true or false. Typically, these values are used for logical operations. <color> <color> is assumed to be a specification for a color in the srgb color space. <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, like so: #RRGGBB. In Scene7 FXG 2.0, it is possible to specify color values in other colorspaces such as CMYK, Gray, Lab, Spot Colors, and RGB by using private attributes in S7 namespace. These attributes are described in Color Management (S7FXG Only). <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). <identifier> A text string for the id property that matches the regular expression [A-Za-z][A-Za-z0-9_]. ActionScript keywords as well as FXG element names are not allowed as valid identifiers. <integer> An <integer> is specified as an optional sign character (+ or -) followed by one or more digits (0 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) to <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 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>.

12 Basic Data Types 12 Data type category Description Unless stated otherwise for a particular attribute or property, a <number> has the capacity for at least a single-precision floating point number 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. s7:basecolorspace To specify colors in color spaces other than RGB, this attribute can be used at all places where color can be used. The valid values of this attribute are: CMYK, RGB, Gray, defined (for spot or global named process colors), and Lab. If this attribute is absent, the color attribute of FXG 2.0 specification is used for defining color in RGB color space. s7:basecolorvalue This attribute specifies color values for each component of the color space established using s7:colorspace. It is a numerical specification in hexadecimal notation. It is specified by a # immediately followed by n hexadecimal characters, where n can be anything that is a multiple of 2. The maximum useful length of characters is double the number of colors in the current color space. Remaining characters are ignored. If the number of characters specified is less than the double the number of colors in the current color space, those missing color components are assumed to be zero. s7:colorname (S7FXG Only) If s7:colorspace value is defined, this attribute specifies the name of the defined color. This color can be a spot color or a global named process color. This information is retrieved from s7:colordefinitions element. s7:colorspace (S7FXG Only) To specify colors in color spaces other than RGB, this attribute can be used at all places where color can be used. The valid values of this attribute are: CMYK, RGB, Gray, defined (for spot or global named process colors), and Lab. If this attribute is absent, the color attribute of FXG 2.0 specification is used for defining color in RGB color space. Note: Lab here means that it uses D50 lab color space. s7:colorvalue (S7FXG Only) This attribute specifies color values for each component of the color space established using s7:colorspace. It is a numerical specification in hexadecimal notation. It is specified by a # immediately followed by n hexadecimal characters, where n can be anything that is a multiple of 2. The maximum useful length of characters is double the number of colors in the current color space. Remaining characters are ignored. If the number of characters specified is less than the double the number of

13 Basic Data Types 13 Data type category Description colors in the current color space, those missing color components are assumed to be zero. s7:elementid (S7FXG Only) This attribute can be used with any tag without affecting the rendering aspect. It is used by the DOM manipulation feature as a key to perform operations on whatever tag that contains it. Invalid Identifiers for FXG 2.0 This topic lists the names that FXG 2.0 does not allow as valid identifiers. Category ActionScript keywords Identifier as, each, false, final, get, include, internal, is, native, null, set, super, to, use FXG element and property names a Application BevelFilter BitmapFill BitmapImage BlurFilter br CDATASection ColorMatrixFilter colortransform ColorTransform content Definition DesignLayer div DropShadowFilter Ellipse fill filters GlowFilter GradientBevelFilter GradientEntry GradientGlowFilter Graphic Group

14 Basic Data Types 14 Category Identifier img kprivelement kunknownelement Library Line LinearGradient LinearGradientStroke linkactiveformat linkhoverformat linknormalformat mask matrix Matrix p Path PlaceObject Private RadialGradient RadialGradientStroke Rect RichText segments SolidColor SolidColorStroke span State states stroke tab tcy TextLayoutFormat transform Transform VariantContent

15 Document Structure 15 Document Structure This section describes the logical structure of FXG documents. Defining an FXG Document Fragment 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 and references to platform fonts by family name and style name, but are otherwise self-contained. FXG elements must be scoped within an XML document under the FXG namespace. The FXG 1.0 and 2.0 namespace is \*. 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 four categories: control, object definition, object instance, and relationship. Element Type Control Elements Definition 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. Others are illegal on definition elements. The Graphic tag in an FXG file is considered to be an object definition element because 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.

16 Document Structure 16 Element Type Definition Group elements can serve as both object definition and instance at the same time. In this 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 Graphic (Root) Element The Graphic element serves as the root for any FXG document. Except as the root element, it cannot appear anywhere else in an FXG document. 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, associates the definition contained within an FXG file with the name of the file. The Graphic element can optionally contain a single child <Library/> element, <mask/> element, or graphical element. The rules governing the ordering of <Library/> and <mask/> elements are as follows: <Library> tag is always first, and optional <mask> tag is always first, and optional If both <Library> and <mask> are present, <Library> is first and <mask> is second 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. This table lists children and attributes of the Graphic element. Children Library Group <mask> Any graphical element Attributes scalegridleft scalegridright scalegridtop scalegridbottom viewwidth viewheight version mask

17 Document Structure 17 flm:isolated <Boolean> (S7FXG Only): Default is false if the alpha value is 1.0; otherwise it is true. Used for transparency groups. flm:knockout <Boolean> (S7FXG Only): Default is false. Used for transparency groups. 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. This table lists children and attributes of the Graphic element. Children transform filters mask Group Any graphical element Attributes rotation <angle>; defaults to 0 scalex <number>; defaults to 1 scaley <number>; defaults to 1 x <number>; defaults to 0 y <number>; defaults to 0 blendmode <string> (add, alpha, darken, difference, erase, hardlight, invert, layer, lighten, multiply, normal, overlay, screen, shader, subtract, colordodge,

18 Document Structure 18 colorburn, exclusion, softlight, hue, saturation, color, luminosity, auto); defaults to auto alpha <number>; defaults to 1 id <string, optional>; no default masktype <string> (clip, alpha); defaults to clip visible <boolean>; defaults to True scalegridleft <number>; defaults to 1 scalegridright <number>; defaults to 1 scalegridtop <number>; defaults to 1 scalegridbottom <number>; defaults to 1 flm:isolated <Boolean> (S7FXG Only): Default is false if the alpha value value is 1.0; otherwise, it is true. Used for transparency groups. flm:knockout <Boolean> (S7FXG Only): Default is false. Used for transparency groups. Group Instances Versus 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 three optional child elements that 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. Note: FXG is modeled after MXML, and MXML is produced by combining rules with a type system that occasionally results in situations like the nesting of exactly on Transform child allowed inside a transform element. 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 contain exactly one element named mask. If present, the children of this element are the same as the mask element that can appear as the child of Graphic. For more information, see Masking. An Instance Group element can optionally define an id attribute. An id attribute cannot be defined on a Group definition. For more information, see Naming. The transform and filters and mask child elements, if present, can appear anywhere in the child order. Their position within the parent group does not affect the rendering.

19 Document Structure 19 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 follow-ing 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 The <Definition /> tag can never be nested at any time, but references to the definition (i.e., the symbol) can be referenced in other definitions. For example, the following nested definition is illegal: <Library> <Definition name="a"> <Definition name="b"/> </Definition> </Library> While the referencing of one symbol inside another definition is legal, like so: <Library> <Definition name="a/> <Definition name="b"> <A/> </Definition> </Library> Symbols can only be used in places where Group tags are legal. All of the attributes that are legal on a Group instance element are legal on a symbol. An FXG renderer applies the values of these attributes to the top-level Group element inside the corresponding Group definition for this instance.

20 Document Structure 20 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. It 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. It s one child is: 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 2.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. This table lists children and attributes of the Definition element. Children Group Attributes name <Identifier>: The name of the symbol that is used to reference it when declaring an instance in the file. It is required. ThePlaceObject Element Any Group defined in a Definition tag in the Library section of an FXG document defines a template object that can be reused (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. A PlaceObject is how a symbol instance is specified in an FXG graphic. The term PlaceObject is a conceptual term used for the purposes of this specification. It never actually appears inside 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. 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

21 Document Structure 21 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. A PlaceObject element can optionally contain exactly one element named mask. If present, the children of this element are the same as the mask element that can appear as the child of Graphic. For more information, see Masking. The transform filters and mask child elements, if present, can appear in any order. This table lists children and attributes of the PlaceObject element. Children transform filters mask Attributes id <Identifier>; for more information, see Naming.

22 Coordinate Space Transformations 22 Coordinate Space Transformations This chapter examines coordinate space transformations. User Coordinate Systems 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 it extends downward along the positive y axis to the right along the positive x axis. One unit corresponds to 1 point on the paper or screen. When the FXG document is embedded or referenced (for example, by an MXML application), the surrounding context can define a different 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. By default, each grouping instance element and graphic element 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 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 as Instance Group Properties Transformations are considered instance group properties, and can only be defined on shape elements and Groups or on PlaceObject tags. Specifically, transformations cannot be defined on Groups whose parent element is a Definition element, or on the topmost Graphic element. For more information about instances and definitions, see Group Instances Versus 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 these attributes: x,y, scalex, scaley, and rotation. These attributes are combined to create a 2D transform matrix to define the Group's coordinate space as follows: Scale by scalex, scaley Rotate by rotation Translate by x,y <Group x="32" rotation="45" scalex="0.5" scaley="0.5" > <Rectangle width="200" height="200" /> </Group>

23 Coordinate Space Transformations 23 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> For more details, see Matrix Element. Transform Element 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 information about the colortransform element, see Color Transformations. 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. This table lists children and attributes of the Transform element. Children Matrix colortransform Attributes None Matrix Element 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.

24 Coordinate Space Transformations 24 The following example shows how the attributes map to coefficients: a b tx c d ty This table lists children and attributes of the Matrix element. Children None 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. Shapes_ Bounds, Fill, and Stroke Calculations Every element has natural bounds, defined in its own coordinate space. For all shapes, the natural bounds are [unstroked path minx, unstroked path miny], [unstroked path maxx, unstroked path maxy]. For a rect, this means the natural bounds are [0,0], [width,height] For an ellipse, this means the natural bounds are [0,0], [width,height] Note: x,y, like all transformation properties, do not affect the natural bounds of the element. Every element has natural stroke bounds, defined in its own coordinate space. For all shapes, the natural stroke bounds are [stroked path minx, stroked path miny], [stroked path maxx, stroked path maxy] For a rect, this means the natural stroke bounds are [0-strokeWeight/2,0-strokeWeight/2], [width+stroke-weight/2,height+strokeweight/2] For an ellipse, this means the natural stroke bounds are [0-strokeWeight/2,0-strokeWeight/2], [width+stroke-weight/2,height+strokeweight/2] Note: x,y, like all transformation properties, do not affect the natural stroke bounds of the element. Every element has a transform matrix associated with it. This can be defined via an explicit matrix or via the discreet transform properties, or it can be left as the default. For all elements, the default transform is [1,0,0,1,0,0] Every fill type has a fill rect, defined in the fill's own coordinate space as: For a linear gradient, the default fill rect is [0,0], [1,1] For a radial gradient, the default fill rect is [.5], [.5,.5] For a solid fill, the fill rect is infinite.

25 Coordinate Space Transformations 25 For a bitmap fill, the default fill rect is [0,0], [source bitmap width, source bitmap height]. Every stroke type has a stroke rect. These mirror the fill rects of the corresponding fill type. Every fill type has a transform matrix associated with it. This can be defined via an explicit matrix, or via the discreet transform properties. Or it can be left as the default. For a linear gradient, the default transform matrix is [element natural bounds width, 0, 0, element natural bounds height, element natural bounds left, element natural bounds top] For a radial gradient, the default transform matrix is [element natural bounds width, 0, 0, element natural bounds height, element natural bounds horizontal center, element natural bounds vertical center] For a solid fill, the transform matrix is irrelevant, but defaults to the identity. If a fill type defines discreet transform properties, they replace only that component of the default transform matrix. If only the scalex is defined, only the scalex portion of the default transform matrix is replaced. If the x is defined, the tx portion of the default transform matrix is replaced. If a fill type defines an explicit matrix, the explicit matrix replaces the entire default transform matrix. Every stroke type has a transform matrix associated with it. These mirror the behavior of the fill type transforms, except that when determining the default, the filled element's natural stroke bounds are used instead. Every fill and stroke type has a policy for how to render pixels that fall outside the fill bounds. Based on the position in the fill's own coordinate space for a point that lies outside the fill bounds: SolidColor: N/A LinearGradient: The gradient tiles vertically, and extends horizontally. RadialGradient: The gradient extends both vertically and horizontally (takes on the ending value of the gradient). The fill and stroke are defined in their own coordinate space, which is a child of the element's coordinate space. To render a fill or stroke in document space, concatenate the transform matrix of every ancestor of the element with the element's own transform matrix with the fill or stroke's own transform matrix.

26 FXG Paths 26 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 the following elements: moveto: Set a new current point lineto: Draw a straight line curveto: Draw a curve using a cubic or quadratic Bézier arcto and closepath: Close the current shape by drawing a line to the last moveto element Compound paths (that is, a path with multiple sub-paths) are possible to allow effects such as "donut holes" in objects. Path Element 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 data 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. If no fill or stroke is defined on the Path, the Path is still preserved upon output but is invisible. Path elements are transformable elements. They support all of the transform attributes and children (see Coordinate Space Transformations), as well as the color transform attributes and children (see Color Transformations). Path elements support blendmodes and masks (<<<see Masking on page 59>>>). A Path element can optionally contain exactly one element named transform. If present, this element must contain exactly one Transform element. A Path element can optionally contain exactly one element named filters. If present, this element must contain one or more filter type elements. A Path element can optionally contain exactly one element named mask. If present, this element must contain a mask description (see Masking). This table lists children and attributes of the Path element. Children fill stroke transform mask

27 FXG Paths 27 Attributes data <path data>: The definition of the outline of a shape. See Path Data. x <number>: Defaults to 0. y <number>: Defaults to 0. rotation <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, colordodge, colorburn, exclusion, softlight, hue, saturation, color, luminosity, auto): Defaults to auto. visible <boolean>: Defaults to true. alpha <number>: Defaults to 1. winding <string> (evenodd, nonzero): Fill rule for intersecting or overlapping path segments. Defaults to evenodd. s7:textpathid <number> (S7FXG Only): In case the path element is used as base for text on path or text in path this attribute contains a unique ID. The same ID is present in the RichText element as s7:onpathref or s7:inpathref attribute. This links the two elements, Path and RichText. s7:filloverprint <boolean> (S7FXG Only): Defaults to false. Specifies the overprint for fill. s7:filloverprintmode <boolean> (S7FXG Only): Defaults to true. Specifies the overprintmode for fill. s7:strokeoverprint <boolean> (S7FXG Only): Defaults to false. Specifies the overprint for stroke. s7:strokeoverprintmode <Boolean> (S7FXG Only): Defaults to true. Specifies the overprintmode for stroke. s7:referencepoint <string> (northwest, north, northeast, west, center, east, southwest, south, southeast, none, inherit) (S7FXG Only): Defaults to none. Specifies the reference position on the bounding box of the object. This position is referred to when applying different transformations such as rotation and scaling to the object. Path Data A Path is defined by including a Path element that contains a data=(path data) attribute, where the data 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 L indicates lineto commands; and the z indicates a closepath command). <Path data="m L L z"> <fill>

28 FXG Paths 28 <SolidColor color="#ff0000" /> </fill> <stroke> <SolidColorStroke weight="3" color="#0000ff" /> </stroke> </Path> 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 only supports 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); no other delimiter characters are allowed. (For example, the following is an invalid numeric value in a path data stream: 13, Instead, use the following: ) All of the path operator parameters are numbers. Superfluous white space and separators such as commas can be eliminated (e.g., M L , which contains unnecessary spaces and could be expressed more compactly as M L ). For the relative versions of the commands, all coordinate values are relative to the current point at the start of the command. In the sections that follow, this notation is used: (): grouping of parameters +: 1 or more of the given parameter(s) is required moveto The moveto command (M or m) establishes a new current point. The effect is as if a 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 (for example, when the moveto is not the first command) represent the start of a new sub-path and are optional. 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. Command Parameters Description M (absolute) m (relative) (x y)+ Start a new sub-path at the given (x,y) coordinate. M (uppercase) indicates that absolute coordinates follow; m (lowercase) indicates that relative coordinates follow. If a relative moveto (m) appears as the first element of the Path, it is treated as a pair of absolute coordinates. If a moveto is followed by multiple pairs of coordinates, the subsequent pairs are treated as implicit lineto commands.