Effects in FXG and MXML graphics

Masks in FXG and MXML graphics
- FXG example
- MXML graphics example
Filters in FXG and MXML graphics
- FXG examples
- MXML graphics examples
Blend modes in FXG and MXML graphics
Color transformations in FXG and MXML graphics

You can add effects such as masks, alpha, and blend modes to graphic elements and groups.

Flash Player renders graphic elements and effects on those elements in the following order:

GraphicElement or Group
Alpha
Masks
Filters
Blend modes

Masks in FXG and MXML graphics

You can add masks to any instance group element. A mask defines the region in which the group’s content is rendered. There are two kinds of masking: clipping and alpha.

In clip masking, only the actual path, shapes, and fills defined by the mask are used to determine the effect on the source content. Strokes and bitmap filters on the mask are ignored. Filled regions in the mask are considered filled, and Flash Player renders the source content. The type of fill is not relevant: solid color, gradient fill, or bitmap fills in a mask all render the underlying source content, regardless of the alpha values of the mask fill.

In alpha masking, the opacity of each pixel in the source content is multiplied by the opacity of the corresponding region of the mask.

To specify a mask, you add a mask as a child of a group or graphic element. A mask must contain a single child tag, either a Group instance or a locally-defined tag from the library. The mask defines its child to be the clipping mask for its parent.

You set the type of masking to use with the maskType property on the mask’s parent graphical element. You can set the value of this property to either alpha or clip.

In FXG, if the <mask> tag is a child of the root tag, then it must be the first tag. If there is a <Library> tag, then it must be the second tag.

FXG example

The following example uses FXG components to define masks:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/SimpleMaskExample.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:comps="comps.*">

      <s:VGroup gap="10" left="10" top="10">
            <s:RichText text="Ellipse.maskType = 'alpha'"/>
            <comps:AlphaMaskComp/>  

            <s:RichText text="Ellipse.maskType = 'clip'"/>
            <comps:ClipMaskComp/>  

      </s:VGroup>
</s:Application>The executing SWF file for the previous example is shown below:

The following FXG file defines the AlphaMaskComp FXG component used in the previous example:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/comps/AlphaMaskComp.fxg -->
<Graphic xmlns="http://ns.adobe.com/fxg/2008" version="2">    
    <Ellipse width="400" height="200" maskType="alpha">
          <mask>
                <Group>
                      <Rect width="100" height="100">
                            <fill>
                                  <SolidColor alpha="0.1"/>
                            </fill>
                      </Rect>
                </Group>
          </mask>
          <fill>
                <SolidColor color="#FF00FF"/>
          </fill>
    </Ellipse>
</Graphic>

The following FXG file defines the ClipMaskComp FXG component used in the previous example:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/comps/ClipMaskComp.fxg -->
<Graphic xmlns="http://ns.adobe.com/fxg/2008" version="2">    
    <Ellipse width="400" height="200" maskType="clip">
          <mask>
                <Group>
                      <Rect width="100" height="100">
                            <fill>
                                  <SolidColor/>
                            </fill>
                      </Rect>
                </Group>
          </mask>
          <fill>
                <SolidColor color="#FF00FF"/>
          </fill>
    </Ellipse>
</Graphic>

MXML graphics example

The following MXML graphics example shows the two types of masks, and their effect on the underlying graphic:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/SimpleMaskExampleMXML.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">

      <s:VGroup gap="10" left="10" top="10">
            <s:RichText text="Ellipse.maskType = 'alpha'"/>
            <s:Ellipse width="400" height="200" maskType="alpha">
                  <s:mask>
                        <s:Group>
                              <s:Rect width="100" height="100">
                                    <s:fill>
                                          <s:SolidColor alpha="0.1"/>
                                    </s:fill>
                              </s:Rect>
                        </s:Group>
                  </s:mask>
                  <s:fill>
                        <s:SolidColor color="#FF00FF"/>
                  </s:fill>
            </s:Ellipse>

            <s:RichText text="Ellipse.maskType = 'clip'"/>
            <s:Ellipse width="400" height="200" maskType="clip">
                  <s:mask>
                        <s:Group>
                              <s:Rect width="100" height="100">
                                    <s:fill>
                                          <s:SolidColor/>
                                    </s:fill>
                              </s:Rect>
                        </s:Group>
                  </s:mask>
                  <s:fill>
                        <s:SolidColor color="#FF00FF"/>
                  </s:fill>
            </s:Ellipse>

      </s:VGroup>
</s:Application>The executing SWF file for the previous example is shown below:

Filters in FXG and MXML graphics

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.

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 library object that references a defined group.

To define a filter in FXG, add the <filters> child tag to the Group or shape you want to apply the filter to. To define a filter in MXML graphics, you add a <s:filters> tag to the Group or shape you want to apply the filter to. The filters are defined in the spark.filters package.

The FXG <filters> child tag and the <s:filters> MXML tag must contain one or more of the bitmap filter types.

Flash Player applies filters to the rendered content of the tag in the order that they appear in the document: the first filter modifies the rendered content, the second filter modifies the output of the first filter, and so on.

The following table lists the filters that are supported by FXG and MXML graphics. It also lists the FXG attributes and children. For the supported properties of the MXML graphics equivalents, see the ActionScript 3.0 Reference for the Adobe Flash Platform.

FXG tag	Equivalent MXML graphics tag and ActionScript class	FXG tag attributes	Children
BevelFilter	<s:BevelFilter> spark.filters.BevelFilter	angle blurX blurY highlightAlpha highlightColor distance knockout quality shadowAlpha shadowColor strength type	None.
BlurFilter	<s:BlurFilter> spark.filters.BlurFilter	blurX blurY quality	None.
ColorMatrixFilter	<s:ColorMatrixFilter> spark.filters.ColorMatrixFilter	matrix	None.
DropShadowFilter	<s:DropShadowFilter> spark.filters.DropShadowFilter	alpha angle blurX blurY color distance inner hideObject knockout quality strength	None.
GlowFilter	<s:GlowFilter> spark.filters.GlowFilter	alpha blurX blurY color inner knockout quality strength	None.
GradientGlowFilter	<s:GradientGlowFilter> spark.filters.GradientGlowFilter	angle blurX blurY distance inner knockout quality strength	GradientEntry
GradientBevelFilter	<s:GradientBevelFilter> spark.filters.GradientBevelFilter	angle blurX blurY distance knockout quality strength type	GradientEntry

MXML graphics also support an AnimateFilter effect, that lets you animate a filter at runtime. Unlike effects that animate properties of the target, the AnimateFilter effect animates properties of the filter applied to the target. For more information, see Spark filter effects.

In some cases, you can use the RectangularDropShadow class to apply a drop shadow to a graphic element, rather than using the DropShadowFilter effect. It is more efficient, but limited in some ways.

FXG examples

The following FXG-based example applies a drop shadow filter to a rectangle:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/FilteredRectExample.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:comps="comps.*">
     
     <mx:Panel title="Rectangle With DropShadowFilter Example"
        height="75%" width="75%" layout="horizontal"
        paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10">

        <s:Group>
            <comps:FilteredRectComp/>    
        </s:Group>
     </mx:Panel>
</s:Application>The executing SWF file for the previous example is shown below:

The following file defines the FilteredRectComp FXG component used in the previous example:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/comps/FilteredRectComp.fxg -->
<Graphic xmlns="http://ns.adobe.com/fxg/2008" version="2">    
   <Group>
        <filters>
            <DropShadowFilter distance="12" alpha=".5" strength=".33"/>
        </filters>
        <Rect height="100" width="200">                              
             <stroke>
                  <SolidColorStroke color="#000000" weight="1"/>
             </stroke>
             <fill>
                  <SolidColor color="#FF0000"/>                
             </fill>
        </Rect>
   </Group>
</Graphic>

You can also apply filters to the RichText element, as the following example shows:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/FilteredTextExample.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:comps="comps.*">
     
     <mx:Panel title="TextGraphic with BlurFilter Example"
        height="75%" width="75%" layout="horizontal"
        paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10">

        <s:Group>
            <comps:TextFilterComp/>    
        </s:Group>
     </mx:Panel>
</s:Application>The executing SWF file for the previous example is shown below:

The following file defines the TextFilterComp FXG component used in the previous example:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/comps/TextFilterComp.fxg -->
<Graphic xmlns="http://ns.adobe.com/fxg/2008" version="2">    
   <Group>
        <filters>
            <BlurFilter/>
        </filters>
        <RichText>
           <content>Hello World!</content>
        </RichText>
   </Group>
</Graphic>

MXML graphics examples

The following MXML graphics example applies a drop shadow filter to a rectangle:

<?xml version="1.0" encoding="utf-8"?>
<!-- fxg/FilteredRectExampleMXML.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:comps="comps.*">
     
     <mx:Panel title="Rectangle With DropShadowFilter MXML Graphics Example"
        height="75%" width="75%" layout="horizontal"
        paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10">

        <s:Group>
            <s:filters>
                <s:DropShadowFilter distance="12" alpha=".5" strength=".33"/>
            </s:filters>
            <s:Rect height="100" width="200">                              
                 <s:stroke>
                      <s:SolidColorStroke color="0x000000" weight="1"/>
                 </s:stroke>
                 <s:fill>
                      <s:SolidColor color="0xFF0000"/>                
                 </s:fill>
            </s:Rect>
        </s:Group>
     </mx:Panel>
</s:Application>The executing SWF file for the previous example is shown below:

Blend modes in FXG and MXML graphics

Graphical elements can control how their content is composited with the background by specifying a blendMode attribute. A grouping element with the blendMode property set to 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.

In FXG, you specify a blend mode by setting the value of the blendMode attribute on the <Group> or graphic element (like <Rect>).

In MXML graphics, you specify a blend mode by setting the value of the blendMode attribute on the <s:Group> tag or graphic tag (like <s:Rect>). The possible values are defined by the flash.display.BlendMode class.

The following table describes the available blend modes in FXG:

Blend mode	Description
`add`	Adds the values of the constituent colors of the element to the colors of its background, applying a ceiling of 0xFF.
`alpha`	Applies the alpha value of each pixel of the element to the background.
`auto`	For grouping elements, acts the same as setting the blend mode to `normal` when the alpha of the group is 0 or 1, and the blend mode is `layer` when the alpha of the group is strictly between 0 and 1. For shape elements, acts the same as setting the blend mode to `normal`.
`color`	Creates a resulting color with the luminance of the base color and the hue and saturation of the blend color. This preserves the gray levels in the artwork and is useful for coloring monochrome artwork and for tinting color artwork.
`colordodge`	Brightens the base color to reflect the blend color. Blending with black produces no change.
`colorburn`	Darkens the base color to reflect the blend color. Blending with white produces no change.
`darken`	Selects the darker of the constituent colors of the element and the colors of the background (the colors with the smaller values).
`difference`	Compares the constituent colors of the element with the colors of its background, and subtracts the darker of the values of the two constituent colors from the lighter value.
`erase`	Erases the background based on the alpha value of the element.
`exclusion`	Creates an effect similar to but lower in contrast than the Difference mode. Blending with white inverts the base-color components. Blending with black produces no change.
`hardlight`	Adjusts the color of each pixel based on the darkness of the element. If the element is lighter than 50% gray, the element and background colors are screened, which results in a lighter color. If the element is darker than 50% gray, the colors are multiplied, which results in a darker color. This setting is commonly used for shading effects.
`hue`	Creates a resulting color with the luminance and saturation of the base color and the hue of the blend color.
`invert`	Inverts the background.
`layer`	The element content is pre-composed in a temporary buffer before it is processed further.
`lighten`	Selects the lighter of the constituent colors of the element and the color of the background (the colors with the larger values).
`luminosity`	Creates a resulting color with the hue and saturation of the base color and the luminance of the blend color. This mode creates an inverse effect from that of the Color mode.
`multiply`	Multiplies the values of the element's constituent colors by the colors of the background color, and then normalizes by dividing by 0xFF, resulting in darker colors.
`normal`	The element content appears in front of the background. Pixel values of the element override those of the background. Where the element is transparent, the background is visible.
`overlay`	Adjusts the color of each pixel based on the darkness of the background. If the background is lighter than 50% gray, the element and background colors are screened, which results in a lighter color. If the background is darker than 50% gray, the colors are multiplied, which results in a darker color.
saturation	Creates a resulting color with the luminance and hue of the base color and the saturation of the blend color. Painting with this mode in an area with no saturation (gray) causes no change.
`screen`	Multiplies the complement (inverse) of the display object color by the complement of the background color, resulting in a bleaching effect. This setting is commonly used for highlights or to remove black areas of the display object.
`softlight`	Darkens or lightens the colors, depending on the blend color. The effect is similar to shining a diffused spotlight on the artwork.If the blend color (light source) is lighter than 50% gray, the artwork is lightened, as if it were dodged. If the blend color is darker than 50% gray, the artwork is darkened, as if it were burned in. Painting with pure black or white produces a distinctly darker or lighter area but does not result in pure black or white.
`subtract`	Subtracts the values of the constituent colors in the element from the values of the background color, applying a floor of 0.

You can also set the blend mode of a shape.

For more information about using blend modes in FXG, see the FXG 2.0 specification.

Color transformations in FXG and MXML graphics

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

Color transforms are applied to the rendering of a group or shape element after any bitmap filters are applied; color transforms 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.

In FXG, you specify a color transformation by adding a <transform> tag as a child tag of a group. The <transform> tag must have a single child tag <Transform>. The <Transform> tag can have a child tag <colorTransform>. The <colorTransform> tag must have a single child tag <ColorTransform>. The supported attributes of the <ColorTransform> tag are shown in Graphics classes and elements.

In MXML graphics, you specify a color transformation with the flash.geom.ColorTransform class.

Transformations are considered instanced group properties, and can only be defined on shape elements and Groups whose parent tag is another grouping element, or on instances of symbols. Specifically, transformations cannot be defined on Groups whose parent tag is a <Definition> tag, or on the topmost <Graphic> tag of an FXG document.

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, 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

For more information about using color transformations in FXG, see the FXG 2.0 specification.