NOTE-VML-19980513

Vector Markup Language (VML)

World Wide Web Consortium Note 13-May-1998

Submission to the World Wide Web Consortium

Status of this document

This document is a submission to the World Wide Web Consortium.  It is the initial draft of the specification of VML.  It is intended for review and comment by W3C members and is subject to change. There are W3C Staff comments on this submission.

This document is a NOTE made available by the W3 Consortium for discussion only. This indicates no endorsement of its content, nor that the Consortium has, is, or will be allocating any resources to the issues addressed by the NOTE.

Abstract

This document defines the Vector Markup Language (VML).  VML is an application of Extensible Markup Language (XML) 1.0 which defines a format for the encoding of vector information together with additional markup to describe how that information may be displayed and edited.  The first part of this document is an introduction, which gives an overview of the way VML is organized and how it interacts with both XML and HTML as defined by the HTML 4.0 Specification.  This is followed by detailed technical definition of the behavior of every VML element and the permitted and recommended behaviors for all applications.

The introduction to this document is intended to be appropriate reading for someone who wishes to gain an overview of VML.  The technical specification is intended for authors of application software which might use VML and for people who wish to assess the suitability of VML for a particular application.  It may also be used by people who need to hand-author VML content.  However it is anticipated that most such authoring will proceed by copy and paste of existing VML - VML is intended to be treated in this way.

Table Of Contents

• Introduction to VML
  • A Simple Example
  • Design Requirements
  • Implementation
• The Technical Specification of VML
  • Introduction
  • Use of CSS
  • Local Coordinate Space
  • Attribute Types
  • DTD Entity Definitions
  • Top-Level Elements
  • The shape Element
  • The shapetype Element
  • The group Element
  • The background Element
  • Advanced Properties of Shapes
  • The path Element
  • The formulas Element
  • The handles Element
  • The fill Element
  • The stroke Element
  • The shadow Element
  • The textbox Element
  • The textpath Element
  • The imagedata Element
  • Predefined Shapes
  • Common Properties of All Predefined Shapes
  • The line Element
  • The polyline Element
  • The curve Element
  • The roundrect Element
  • The oval Element
  • The arc Element
  • The image Element
• Normative References
• Informative References

Introduction to VML

The Vector Markup Language (VML) supports the markup of vector graphic information in the same way that HTML supports the markup of textual information.  Within VML the content is composed of paths described using connected lines and curves.  The markup gives semantic and presentation information for the paths.

VML is written using the syntax of XML just as HTML is written using the syntax of SGML (the Standard Generalized Markup Language, [ISO 8879]) - XML is a restricted form of SGML.  VML uses Cascading Style Sheets, Level 2 in the same way as HTML to determine the layout of the vector graphics which it contains.  The workflow involved in rendering VML can be compared to that involved in rendering HTML as show in the following figure.

The primary difference between the HTML workflow and the VML workflow is in the last but one step - character layout versus path transformations.  In the HTML case, the workflow generates locations and other information for sequences of characters which are then rendered using native operating system functionality.  In the VML, case the workflow generates locations and related information for vector paths and related objects (such as bitmaps) which are then rendered using native operating system functionality.

The common workflow is an essential part of VML - two design requirements were to integrate VML with existing HTML and to avoid requiring a user agent to reinvent the wheel by using different representations or implementations of existing HTML or CSS functionality.

Like HTML, VML describes objects which will often be further edited.  In the case of HTML, these objects are paragraphs, forms or tables.  In the case of VML, the objects are shapes or collections of shapes known as groups.   VML does not require a particular approach to editing - it accommodates a wide variety of editors.  The enormous range of graphical data requires that VML pays careful attention to how an editor records the semantic information related to the VML description.  VML ensures that different editors can recognize and correctly handle each other's data (even though they will not normally understand it).

A Simple Example

The simple diagram below contains both simple graphics and text.

Although the bitmap compression used makes the image very small (it only requires about 8kbytes) the bitmap has none of the information necessary to make further changes to the diagram - for example a user who needs to change "Product" to "Products" must recreate the bitmap from scratch.  The corresponding VML has all the necessary editing information in about 2.5kbytes.

.font5 {
 color: black;
 font-size: 18.0pt;
 font-weight: 400;
 font-style: normal;
 text-decoration: none;
 vertical-align: text-bottom;
 font-family: "Times New Roman";
}

<v:group
  style='position: absolute;
         margin-left: 10.2pt;
         margin-top: 4.8pt;
         width: 90pt;
         height: 191.4pt;
         z-index: 1'
  coordsize="21600, 21600">

 <v:shapetype id="irregularSeal1" coordorigin="17, 8" coordsize="150, 319"
   path="m10800,5800l8352,2295,7312,6320,370,2295,4627,7617,,8615,3722,11775,135,14587,
      5667,13937,4762,17617,7715,15627,8485,21600,10532,14935,13247,19737,14020,
      14457,18145,18095,16837,12942,21600,13290,17607,10475,21097,8137,16702,7315,
      18380,4457,14155,5325,14522,0xe">
  <v:stroke joinstyle="miter"/>
  <v:path gradientshapeok="t" textboxrect="4627, 6320, 16702, 13937"/>
 </v:shapetype>

 <v:shape type="#irregularSeal1"
   style='position: absolute;
          left: 17; top: 8; width: 150; height: 120'
   fillcolor="#f06">
  <v:fill type="gradient" color2="fill lighten(0)"
   method="linear sigma" angle="-135" focus="100%"/>
  <v:textbox>
   <div>
    <span class="font5">Idea</span>
   </div>
  </v:textbox>
 </v:shape>

 <v:shapetype id="downArrow" coordsize="21600, 21600"
   adj="16200, 5400"
   path="m0@0l@1@0@1,0@2,0@2@0,21600@0,10800,21600xe">
  <v:stroke joinstyle="miter"/>
  <v:formulas>
   <v:f eqn="sum #0 0 0"/>
   <v:f eqn="sum #1 0 0"/>
   <v:f eqn="sum height 0 #1"/>
   <v:f eqn="sum 10800 0 #1"/>
   <v:f eqn="sum width 0 #0"/>
   <v:f eqn="prod @4 @3 10800"/>
   <v:f eqn="sum width 0 @5"/>
  </v:formulas>
  <v:path textboxrect="@1, 0, @2, @6"/>
  <v:handles>
   <v:h position="#1, #0" xrange="0, 10800" yrange="0, 21600"/>
  </v:handles>
 </v:shapetype>

 <v:shape type="#downArrow"
   style='position: absolute; left: 40; top: 143; width: 105; height: 105'
   adj="11632, 4371"
   fillcolor="#6f9">
  <v:fill type="gradientScale" color2="fill lighten(0)"
   method="linear sigma" angle="-135" focus="100%"/>
 </v:shape>

 <v:shapetype id="flowChartTerminator" coordsize="21600, 21600"
   v="m3475,0qx0,10800qy3475,21600l18125,21600qx21600,10800qy18125,0xe">
  <v:stroke joinstyle="miter"/>
  <v:path gradientshapeok="t" textboxrect="1018, 3163, 20582, 18437"/>
 </v:shapetype>

 <v:shape type="#flowChartTerminator"
   style='position: absolute; left: 17; top: 263; width: 150; height: 64'
   fillcolor="#39f">
  <v:fill type="gradient" color2="fill lighten(0)"
   method="linear sigma" angle="-135" focus="100%"/>
  <v:textbox>
   <div>
    <span class="font5">Product</span>
   </div>
  </v:textbox>
 </v:shape>

</v:group>

This VML contains all the information required both to edit and to display the diagram.   The VML has been color coded as follows:

Blue - XML structure.  VML is formatted according to the rules of XML.  The v: prefix on each VML tag identifies the tag as VML, following the current suggestion for handling namespaces in XML.  Any standard XML parser can parse the VML and hand off the resultant data to a VML specific processor.

Green - CSS information.  The first block of CSS is used in the HTML which defines the text in the diagram - this is just standard CSS.   Each shape and group element has a CSS style attribute which defines the position and size of the shape within the page.  The location of the top-level group is defined completely by the CSS - a layout engine need not understand any aspect of VML to handle this positioning information.

Black - VML.  The remainder of the data describes the graphical properties of the diagram.  Notice how this data is associated with the shape and shapetype elements.  The shape elements are rendered in the diagram, the shapetype elements allow reuse of geometric information between shapes.  In this case, because there are three different shapes in the diagram, there are also three shapetype elements, but in more complex cases the same shape would be used multiple times (each instance referencing the same shapetype element).

Brown - HTML text.  This text is associated with shape elements in the diagram.  The VML in italics controls the location of the HTML text.

Purple - the most basic VML geometric information describes closed or open paths.  These paths may be parameterized - this allows a single shapetype element to define multiple related paths.  For example, the downArrow shapetype above is defined parametrically and the following four arrows all share the same basic shape.

The corresponding VML is:

<v:shape type="#downArrow"
  style='position: absolute; left: 77; top: 16; width: 64; height: 128'
/>
<v:shape type="#downArrow"
  style='position: absolute; left: 149; top: 16; width: 64; height: 128'
  adj=", 9450"
/>
<v:shape type="#downArrow"
  style='position: absolute; left: 219; top: 16; width: 64; height: 128'
  adj="14175, 2025"
/>
<v:shape type="#downArrow"
  style='position: absolute; left: 292; top: 16; width: 64; height: 128'
  adj="7088, 7425"
/>

The combination of parameterization with a concise path description allows VML diagrams to be relatively compact, despite the large amount of editing information.  Indeed, large VML diagrams become dominated by the CSS required to position the elements.   VML defines a defaulting mechanism for CSS which allows the container box to be inherited in order to avoid this overhead on complex illustrations.

Design Requirements

Many requirements guided the design of VML.  The most crucial are listed below in order of importance.

1. Retain the information required for further editing of VML.  This requirement has the important consequence that VML must be extensible - it is inconceivable that VML meets the requirements of all editing applications, therefore it must be possible for every application to add the required editing data specific to that application.
2. Support interchange of data between applications.  One application must be able to read and edit the data of another application, even though the first requirement means that, potentially, both applications will add application specific data.
3. Use the existing mechanisms of HTML and CSS - this facilitates implementation of VML and ensures that implementations can reuse existing code and techniques.
4. Be backward compatible with existing user agents.  VML adoption will be inhibited unless it is possible to produce VML which works with existing web browsers.   VML has special provisions to allow alternate bitmap representations of graphics for backward compatibility.
5. Provide efficient representations of vector graphics.  Textual representations tend to be verbose.  VML addresses this by defining a compact representation of path elements and by following a design principle of using concise names for frequently used attributes and more verbose names for less frequently used attributes.
6. Allow the implementation of subsets where an application does not require the full functionality of VML.  Normally a viewer will implement the full specification, however editors should be able to implement only the subset required for their own data.
7. Support hand-editing.  This leads to a design principle that the structure of the graphic be obvious and that the syntax be familiar to HTML programmers - effectively the same as requirement (3).
8. VML should support scripting, including the requirements of animation.  This, again, leads to a desire for the structure of VML to match the structure of the graphics.   It also leads to the use of types within VML attributes which are appropriate to animation - for example 2D coordinates are defined as single attributes "x, y" rather than pairs of attributes.

Implementation

An implementation of VML will fall into one of two classes.  A viewer implementation will normally implement the full specification, although it can avoid the need to implement any functionality to edit VML (beyond that required by any script language which the viewer supports).  An editor implementation may only need to implement those specific features necessary to output the data which the editor manipulates.  Even an editor which potentially manipulates VML produced by other applications may need nothing more than a subset of the CSS2 visual rendering model.   Such an editor can correctly position the VML produced by other applications even though it may not be able to render individual shapes.

The implementation model follows the diagram at the start of this document.  An implementation can proceed in five separate, independent, steps.

1. Each implementation requires an XML parser.  This performs lexical analysis of VML and identifies the individual elements.  XML parsers are already widely available.
2. Non-trivial implementations will need to parse the structure of the individual VML attributes.  To make this easy, VML defines basic types which have canonical internal representations - no VML implementation is required to store greater accuracy than that implied by the canonical representation and all VML data can be converted to the corresponding representations.  This means that the implementor need only write a small number of string parsers to be able to handle all VML data.  Most of these parsers are already present either as part of language libraries or as a consequence of the need to parse CSS.
3. An implementation must handle that part of the CSS2 visual rendering model used by VML.  VML uses a small subset of CSS2 to define the block level boxes for each VML element.  Implementing this gives a minimal VML implementation which can handle the layout of elements (using their block level boxes) without doing any rendering.
4. Viewing implementations and most editing implementations must handle the path parameterization required by VML - a small set of mathematically defined transformations allow the VML representation of a path to be reduced to a simple set of closed or open line segments.  Extensions to VML may add transformations, however VML allows such extensions to be accompanied by equivalent definitions of the same information in unextended VML.
5. Finally the implementation must render the path level data in the way specified by the VML rendering attributes.  Normally this operation maps easily onto widely available operating system facilities.

Each of these five steps is testable in isolation and implementable independently of the other steps.  Only steps (2) and (4) are VML specific, and step (2) can reuse standard technology available in many places.

The Technical Specification of VML

Introduction

The overall structure of VML may be summarized by the XML definitions of the two primary elements - shape and group.

A shape element is used to define a visible vector graphic element.   Most shapes have a path definition - a sequence of straight lines and cubic bézier curves which defines an outline.  The outline may be stroked, as specified by attributes on the shape and the stroke sub-element.  It may also be filled, under the control of shape attributes and the fill sub-element.  Additional sub-elements support raster (bitmap) images, more advanced transformations of the path and text drawn on top of the shape.

Below is an example of a simple shape and its VML representation.

<v:shape style='top: 0; left: 0; width: 250; height: 250'
       stroke="true" strokecolor="red" strokeweight="2" fill="true"
       fillcolor="green" coordorigin="0 0" coordsize="175 175">
<v:path v="m 8,65
  l 72,65,92,11,112,65,174,65,122,100,142,155,92,121,42,155,60,100
  x e"/>
</v:shape>

A group element is used to group together several shapes so that they may be transformed together as one unit.

In addition VML defines several auxiliary top-level elements to help make the editing and representation of complex graphical information more compact and convenient.

The shapetype element is used to define a prototype definition of a shape.   A shape element may reference a shapetype in order to instantiate several copies of the same shape.

Several predefined shapes may be used as convenient alternatives to explicitly declaring a shape element with a path.  These predefined shapes are line, polyline, curve, rect, roundrect, oval, arc, and image.

Use of CSS

The style attribute uses the syntax described in "Visual rendering model" in Cascading Style Sheets, Level 2.   The positioning may be absolute or relative unless the shape is within a group, in which case it must be absolute (relative to the top left of the parent group). The z order of the elements within the group is from the first (lowest) to the last (highest) - i.e. later elements obscure earlier elements.  The elements establish no relative position - hence the restriction to use of absolute positioning.

The VML shape and group elements participate fully in the CSS2 visual rendering model.  In addition to standard CSS layout the VML elements may also be rotated or flipped.  Each element also establishes a coordinate space for its content - this allows scaling of the content with respect to the containing elements.   The following VML specific CSS properties support this.

The value specifies a rotation for the shape or group in clockwise degrees about its center (i.e. positive is clockwise, negative is counterclockwise - the normal definition in an inverted coordinate space).

The value specifies that the shape or group is flipped about its center about either the x or the y axis according to the following table.

Both x and y may be specified in the flip property.

center-x, center-y

These properties may be used to specify the center of the block level box of the element within its parent container box.  They are alternatives to left and right and convey the same information.  It is an error to specify both left and center-x.  A user agent should respond to the error by honoring center-x (or center-y).  The user agent may issue a diagnostic to the user if this is appropriate.

Local Coordinate Space

The shape and group elements are containing blocks for their content - they define a CSS2 "block level box".  Inside the containing block a local coordinate system is defined for any sub-elements using the coordsize and coordorigin attributes.  All CSS2 positioning information is expressed in terms of this local coordinate space.  Consequently CSS2 position attributes (left, top, width, height and so on) have no unit specifier - they are simple numbers, not CSS length quantities.

The coordsize attribute defines how many units there are along the width of the containing block. The coordorigin attribute defines the coordinate at the top left corner of the containing block.  For example, if a group were defined as follows:

<v:group style='width: 300px; height: 250px' coordsize="1000,1000" coordorigin="-500,-500" />

The containing block would be 300 pixels wide by 250 pixels high (assume that the parent element of this group was not another group).  Then the coordinate system inside the containing block would range from –500.0 to 500.0 along the x-axis and –500.0 to 500.0 along the y-axis with 0.0, 0.0 right in the center of the rectangle.   Any shapes inside the group are positioned and sized according to this local coordinate system.  No matter how the width and height of the group is changed, the local coordinate system inside will remain the same.

The rationale behind this is that the vectors defining a shape can be specified in a local coordinate system.  If the containing block for the shape is changed, the outline of the shape will be automatically scaled to the new box. Similarly, shapes within the local ordinate system of a group will be automatically scaled if the containing block of the group changes.

It is important to note that the containing block does not establish a clipping region.  Sub-elements and paths may be drawn outside the boundaries of the containing block.  The containing block merely serves to map the local coordinate space to the page space.

Attribute Types

Basic types of attributes are identified according to their lexical form as follows.

A complete set of data types is defined for VML along with canonical representations which ensure that the minimum precision which an authoring tool must store and the maximum which it can rely on are well defined.  At this stage the tables in this document do not give the underlying data types.

DTD Entity Definitions

VML shape elements (shape and group and the predefined shapes) use the standard HTML core attributes plus some attributes which may appear on any element.

In addition shape elements and the special pre-defined elements have standard attributes to control rendering.

Sub-elements are used within shape elements to define more sophisticated rendering operations.

At most one instance of each sub-element may occur in a shape element.  If multiple elements do occur the user agent should respond to the error by merging the repeated elements and retaining only the last values specified if the same attribute is specified more than once.   The user agent may also issue a diagnostic if appropriate.

The entity %extensions; acts as a placeholder for future extensions.   Any extension element may be qualified by the v:ext attribute.

<!attlist (%extensions;)
  v:ext cdata "backwardcompatible" -- may also be "view" or "edit" --
>

When an authoring agent encounters such an element the v:ext attribute tells it how to handle the extension.

These rules give an editor application the ability to edit any VML document.  If an editor just changes the document layout it can still handle even v:ext="view" extensions - the VML definition ensures that the editor knows the CSS layout properties of the shape.  The rules accommodate a wide variety of editor behavior - an editor might chose to lock an extended shape to prevent invalidation of the extension information for example.

Top-Level Elements

The shape Element

This is the top-level element used to describe a shape. This element may appear by itself or within a <group> element. If a <shapetype> is referenced using the type= attribute, any attributes specified in the shape will override those found in the shapetype.

The path definition is described in more detail below.  Path parameterization allows one canonical path to describe a range of shapes which differ only in geometric proportions (for example, ring shapes where the ratio of the inner to the outer circle diameter varies).

Attribute Descriptions.

XML template

Throughout this document XML templates are used to summarize the full set of attributes which may appear on each element.  The shape elements - shape, group and most of the predefined shapes have CSS2 positioning information which locates the shape within its container.  This is not reflected in the templates as there are several different ways of specifying the same information.  A top-level shape will typically use absolute positioning plus margin-left and margin-top properties:

style='position: absolute; margin-left: 10pt; margin-top: 10pt; width: 100pt; z-index: 1.5'

A shape within a group can use left/top or center-x/center-y as appropriate:

style='left: 100; top: 100; width: 1000; height: 1000'

style='center-x: 550; center-y: 550; width: 1000; height: 1000; rotation: 55deg'

The rotation, z-index and flip properties may also be given when required.

The shapetype Element

Description

This is the element used to describe a shape so that it may be referenced at a later point in the document by a shape element.  It is identical to the shape element except that it cannot reference another shapetype element and that the visibility property is always hidden.  (Authoring agents may choose to make shapetype elements visible to allow them to be edited - in this case the CSS positioning properties become relevant.)

When a shape element makes reference to a shapetype, the shape may duplicate some of the attributes that have already been specified in the shapetype.   In these cases, the attributes in the shape override those of the shapetype.

Attribute Descriptions

See <shape>.

XML Template

The group Element

This top-level element is used to group shapes (including other groups) so that they can be positioned and transformed as a single unit.

Attribute Descriptions

See <shape> for the descriptions of the following attributes: id, class, style (top, left, width, height, rotation, z-index, position, visibility), title, href, target, alt, coordsize, coordorigin.

XML template

The background Element

Description

This element describes the fill of the background of a page using vector graphics fills.  This illustrates how the rendering description of VML can be extended to existing and new HTML objects.

Attribute Descriptions

See <shape> for the descriptions of id, fill and fillcolor.

XML template

Advanced Properties of Shapes

The following sub-elements may be used to describe more advanced properties of shapes. For example, the shape element only allows the description of a solid color fill. One would use the fill sub-element to describe a gradient fill.

The path Element

This sub-element may appear inside a shape or a shapetype to define the path that makes up the shape. This is done through a string that contains a rich set of pen movement commands.  This sub-element also describes the limo-stretch point, inscribed textbox rectangle locations, and connection site locations.  The limo-stretch definition and the formulas element (described below) allow greater designer control of how the path scales.   They allow, for example, definition of a true rounded corner rectangle where the corners remain circular even though the rectangle is scaled anisotropically.

Properties

The v attribute string (or the path property of shape) is made up of a rich set of commands as summarized in the following table:

Edit behavior extensions

VML does not mandate a user interface for editing applications. It attempts to convey information about the object which is being edited - this may imply the behavior of an editor.  One common operation implied by VML is the need to edit the points in a path. The edit behavior extensions attempt to identify some common behavior of v objects so that applications behave consistently however the information encoded is very low level.  Consequently these extensions may be ignored completely by a conforming application and any conforming application is free to remove or rewrite the edit information in the path.

The extensions define the behavior of all following points under editing operations which move the points or the associated line segments. Nine different behaviors are identified for the vertices in the path attribute (the end points, not the control points) depending on whether the associated line segment is a line or curve.

The line segment type defines whether the behavior applies to points which are adjacent to lines or whether it applies to points adjacent to curves. The vertex behavior specifies how the two line segments either side of a point are expected to behave as the point is moved.

The auto behavior implements some application-defined algorithm to guess the correct control points when a point is moved. This is, effectively, the default - it implies that the application should use other information to determine the control point behavior. The symmetric, smooth and corner behaviors determine how one control point behaves when the other at that vertex is moved. The freeform behavior does not recalculate control point position as vertices are moved.

Lexical format of the v attribute value

This value consists of commands followed by zero or more parameters.  The number of parameters is given in the table above.  In this table, the suffix "*" indicates that the parameter set may be repeated (but the number of parameters must be a multiple of the given number).  The quadratic bézier must have more than two pairs of parameters.

• Either commas or spaces may be used to delimit parameters for each command.  E.g. "m 0,0" and "m0 0" are both acceptable.
• Parameters that are zero may be omitted using commas with no parameter.  E.g. "c 10,10,0,0,25,13" and "c 10,10,,,25,13" are equivalent.
• Parameterized paths are also allowed. In this case, the shape must also have a formula element with a list of formulas that may be substituted into the path using the @ symbol followed by the number of the formula. The adj property of the shape contains the input parameters for these formulas.  E.g. "moveto @1@4".   The evaluations of the formulas are substituted into the appropriate positions.   Note that @ also serves as a delimiter.

In the event that a path is malformed VML requires the following behavior if the page is displayed.

• Missing parameter values must be supplied as 0.
• Unrecognized commands must be skipped - they should be treated as though they are space characters.

An application is also permitted to fail to display the page (with a diagnostic) or to alert the user that some content is malformed.

XML template

The formulas Element

This sub-element may appear inside a shape or a shapetype to define formulas that can vary the path of a shape, its inscribed text rectangles, and connection sites.  Formula values change as the adj values change on the shape.  Formulas can reference other formulas defined earlier in the same formulas element.

Attribute Descriptions for <formulas>

none

The f element of formulas

Each f element defines a single value as the result of the evaluation of an expression. The expression is defined by the cdata content of the eqn attribute and has the general form of an operation followed by up to three arguments, which may be adjust handle values, the results of earlier guide formulas, fixed numbers or pre-defined values.

Attribute Descriptions <f>

In the following table, the arguments are given the names v, P1, P2 (in that order), thus the element is simply:

<f eqn="operation v P1 P2">

operation	para- meters	exact?	result	description
val	1	yes	v	Defines a guide value from some other value.
sum	3	yes	v + P1 ­ P2	Used for addition and subtraction.
product	3	rounds	v × P1 / P2	Used for multiplication and division.
mid	2	rounds to zero	(v + P1) / 2	Average.
abs	1	yes	abs(v)	Absolute value.
min	2	yes	min(v, P1)	The lesser of v and P1.
max	2	yes	max(v, P1)	The greater of v and P1.
if	3	yes	v > 0 ? P1 : P2	Condition testing.
mod	3	no		Modulus (etc.)
atan2	2	no	atan2(P1, v)	Polar arithmetic – result is in degreesˇ216. (fd units.)
sin	2	no	v × sin(P1)	Sine, argument is in degreesˇ216. (fd units.)
cos	2	no	v × cos(P1)	Cosine, argument is in degreesˇ216. (fd units.)
cosatan2	3	no	v × cos(atan2(P2, P1)	Preserves full accuracy in intermediate calculation.
sinatan2	3	no	v × sin(atan2(P2, P1)
sqrt	1	no	sqrt(v)	Result is positive, rounds down.
sumangle	3	yes	v + P1×216 - P2×216	v is an existing angle (scaled by 216), P1 and P2 are numbers of degrees.
ellipse	3	no
tan	2	no	v × tan(P1)	Tangent, argument is in degreesˇ216. (fd units.)

The formulas are evaluated to full precision - however the result is always a 32-bit integer.  Formula authors should avoid formulas which are discontinuous - not only are many of the trigonometric operations inexact, the transformations within the coordinate spaces are also inexact.  This can mean that a set of formulas which is discontinuous evaluates to give very different  path values with the same input on two different systems.

When an operation is marked as exact then a conforming implementation must always generate the correct arithmetic answer (unless the calculations overflow internally).   The product operation is required to round to the nearest integer.   If the result is exactly 0.5 then it must be rounded up to the next numerically greater integer.  (So the absolute value of a negative result will decrease - -1.5 must be evaluated as -1.)

The mid operation is required to round towards 0.

All other operations are inexact, however the implementation must round non-integral values down (towards -infinity) and should perform internal calculations with this form of rounding.

The arguments used in the evaluation of a formula are normally either fixed numbers, the result of the evaluation of a previous guide formula or an adjust value - the value of the corresponding entry in the shape adj attribute.  Fixed numbers must be positive integral values in the range 0 to 65535, i.e. unsigned 16 bit numbers.

Notice that a pixel value should be in a square coordinate space - so it may be necessary to (effectively) report a higher device resolution than that which is available if the device has non-square pixels.  The pixel value parameters serve the specific purpose of allowing a formula author to handle some aspects of device pixelization.  They must not be used to produce paths with elements which have a constant physical size. The EMU parameters must be used for this purpose.

VML limits the total number of adjust values, guide formulas and adjust handles.

1. Up to 8 adjust values.
2. Up to 128 guide formulas.
3. Up to 4 adjust handles.

XML template

<formulas>
  <f eqn="sum #0 0 10800"/>
  <f eqn="prod #0 2 1"/>
  <f eqn="sum 21600 0 @1"/>
  <f eqn="sum 0 0 @2"/>
  <f eqn="sum 21600 0 @3"/>
  <f eqn="if @0 @3 0"/>
  <f eqn="if @0 21600 @1"/>
  <f eqn="if @0 0 @2"/>
  <f eqn="if @0 @4 21600"/>
  <f eqn="mid @5 @6"/>
  <f eqn="mid @8 @5"/>
  <f eqn="mid @7 @8"/>
  <f eqn="mid @6 @7"/>
  <f eqn="sum @6 0 @5"/>
</formulas>

The handles Element

This sub-element may appear inside a shape or a shapetype to define user interface elements which can vary the adj values on the shape, thereby changing the value of formulas and the rendering of a path based on formulas and adj values.

Attribute Descriptions for <handles>

none.

The h sub-element of handles

Each handle is specified using a single h sub-element.   This defines which pair of adjust values store the position of the handle and how the handle position can vary as the handle is adjusted.  The handle is moved under user control, within the constraints imposed by the handle definition, and the final position is stored back in the adjust values.

Positions are stored within the shape coordinate space - this means that handle positions are independent of the actual size of the shape.

Attribute Descriptions for <h>

XML template

<handles>
  <h
    position=null
    polar=null
    map="0, 1000"
    invx="false"
    invy="false"
    switch="false"
    xrange="0, 1000"
    yrange="0, 1000"
    radiusrange="0, 1000"
  /h>
</handles>

The fill Element

This sub-element may appear inside a shape, shapetype, background or most predefined shape elements to describe how the path should be filled if something beyond a solid color fill is desired.  The attributes of the fill element can used to describe a powerful set of image or gradient based fill patterns.   Extensions to the VML fill definition may be encoded as sub-elements of fill.

Properties

XML template

The stroke Element

The sub-element may appear inside a shape, shapetype or any predefined shape element to describe how to draw the path if something beyond a solid line with a solid color is desired.  The attributes of the stroke element can used to describe a powerful set of stroke properties.  Extensions to the VML stroke definition may be encoded as sub-elements of the stroke element.

Properties

The dashstyle attribute allows the user to specify a custom defined dash pattern.  This is done using a series of numbers.  Dash styles are defined in terms of the length of the dash (the drawn part of the stroke) and the length of the space between the dashes.  The lengths are relative to the line width - a length of "1" is equal to the line width.  The endcap style is applied to each dash, the arrow style is not.  The string first defines the length of the dash then the length of the space.  This may be repeated to form complex dash styles.   The string should always contain a pair of numbers.  If it contains an odd number of numbers the last should be disregarded.  The following table lists some typical values and a description of the intended effect.  "0" implies a dot which should be four-fold symmetrical (with round end caps it should be a circle).   If the line end cap is flat a viewer should choose a built-in operating system dash where possible (i.e. something which is fast to draw).

XML template

The shadow Element

This sub-element may appear inside a shape or a shapetype to define a shadow effect on a shape.

Properties

XML template

The textbox Element

This sub-element may appear inside a shape or a shapetype to define text that is to appear inside the shape. This text may contain rich formatting and will be rendered to fit inside the textboxrect defined by the path element.

Properties

XML template

<textbox
  id=null
  style='
    v-padding-auto:   true;
    padding-left:     0.1in;
    padding-top:      0.05in;
    padding-right:    0.1in;
    padding-bottom:   0.05in;
    v-text-anchor:    top;
    v-text-wrapping:  true;
    v-text-flow:      horizontal;
    v-text-direction: rtl'
/>

The textpath Element

This sub-element may appear inside a shape or a shapetype to define a vector path based on the text data, font and font styles supplied.  The path which results is then mapped into the region defined by the v attribute of the shape.

Attribute Descriptions

XML template

The imagedata Element

This sub-element may appear inside a shape or a shapetype to define a picture to be rendered on top of a shape. There is also a top-level element, image, which has these attributes, along with most of the same attributes as shape.

Properties

XML template

Predefined Shapes

Predefined shapes serve two purposes - they provide a more compact representation of a small number of very frequently encountered drawing operations (particularly rectangles and circles) and they give an easy to use form for people who hand-edit VML.

Common Properties of All Predefined Shapes

Predefined shapes have the same properties as shape except that the type attribute is not permitted.  In some cases the definition of the shape precludes use of some of the standard shape properties.  These exceptions are given below.

The line Element

This element is used to specify a straight line.

Attributes

XML template

The polyline Element

The polyline element is used to define shapes made up of connected line segments.

Attributes

It is necessary to compute the bounding rectangle of the polyline to determine the content width and height.

XML template

The curve Element

This element is used to draw a cubic bézier curve.

Attributes

XML template

The rect Element

This element is used to draw a simple rectangle.  The rectangle is defined by the content width specified in the CSS2 properties.

XML template

The roundrect Element

This element is used to draw a rectangle with rounded corners.

Attributes

XML template

The oval Element

This element is used to draw an oval defined by the CSS2 content width and height.

XML template

The arc Element

This element is used to draw an arc defined as a segment of an oval.  The content width and height define the width and height of that oval.  The arc is defined by the intersection of the oval with the start and end radius vectors given by the angles.   The angles are calculated on the basis of a circle (width equal to height) which is then scaled anisotropically to the desired width and height.

Properties

XML template

The image Element

This element is used to draw a bitmap that has been loaded from an external source. There is an implied rectangle that is the same size as the image. Any stroke or fill will be applied to this implied rectangle.  The fill will be behind the image and it will therefore only be visible through transparent areas of the bitmap.  The stroke is drawn on top of the image.  The bitmap may have transparency encoded in the file (if it is a PNG bitmap) or a chromakey color value may be specified using the chromakey attribute.

Properties

XML template

Normative references

VML is based on several other standard forms.  Some of these are as yet incomplete (CSS2, XML namespaces).  This section references those documents which are normative so far as VML is concerned - they define behavior which must be both understood and implemented for VML to function correctly.

HTML 4.0 Specification

This is a W3C recommendation, therefore is not subject to change.

Cascading Style Sheets, Level 2

This is a W3C proposed recommendation, the review period has now ended and the proposal is likely to become a recommendation in the immediate future.  For the most part VML is based on CSS1 (see below), therefore reliance on CSS2 is minimal.

Cascading Style Sheets, level 1

This defines many of the basic types used in VML - for example the fundamental lexical syntax used to describe length and color are defined here.   This is a W3C recommendation, therefore not subject to change.

Extensible Markup Language (XML) 1.0

This defines the basic lexical form used for the encoding of VML.  It is a W3C recommendation, not subject to change.  VML requires proposed extensions to XML to support the VML extensibility mechanisms.  VML also defines mechanisms which facilitate the interaction of HTML and VML XML within a single HTML page.

Namespaces in XML

This is a W3C working draft, therefore subject to change.  The document defines a mechanism to identify unknown XML tags and to reliably and safely add new XML tags.   It is intended that VML track the relevant changes, although at this stage it seems certain that the fundamental requirements of VML will be met.

XML Linking Language (XLink)

Applications needing VML must identify links to external objects even though they may occur in extensions.  The specifications adopted for identifying such links within XML will be used by VML.

IEC 61966-2

This IEC Technical Committee will formalize the definition of sRGB (61966-2.1).  At present the document is a working draft.  However it seems unlikely that any changes will be made to the encoding model on which VML has some reliance.

PNG (Portable Network Graphics) Specification

This defines the PNG file format, one of the recommended formats for raster data in VML.   The definition can also be found at PNG (Portable Network Graphics) Specification on the W3C web site.

ISO 10918-1 (JPEG)

This defines the underlying compression scheme used in the other raster format recommended by VML.  However it is important to realize that VML expects JPEG data to be presented in particular forms - JFIF or Exif - arbitrary JPEG data is not compatible with VML.  ISO standards can be obtained from national standards organizations, ANSI Catalogs & Standards Information in the US.

---

Informative references

VML does not rely on the definition of PostScript, however that definition is extremely helpful in understanding VML.

The PostScript Language Reference Manual

ISBN 0-201-10174-2, Adobe Systems, Addison-Wesley.  Either edition of the book is appropriate.  It contains the clearest description of the "filled path" imaging model which underlies most two dimensional vector graphic implementations.

Inside Macintosh, Imaging with QuickDraw

ISBN 0-201-63242-X.  VML is designed to be implementable with QuickDraw on a Macintosh.   Implementations based on QuickDraw must do more work (because of the lack of arbitrary path support), yet highly efficient implementations are still possible.

The original W3C requirements specification can be found at W3C Scalable Graphics Requirements.

VML is based on well-established vector graphical techniques.  The intention is to make the references in this section reflect parts of that work which are particularly important to VML.

JPEG Still Image Data Compression Standard

William B. Pennebaker, Joan L. Mitchell, ISBN 0-442-01727-1.  This book not only contains a detailed description of JPEG but also has ISO DIS 10918-1 in an appendix (this being a copy of the draft standard before it was approved).

ISO 8879

ISO 88790:1986 (E).  Information processing - Text and Office Systems - Standard Generalized Markup Language (SGML).  This is the basis of XML - XML is an application profile of SGML.

OpenType Specification v.1.1

This describes the OpenType and TrueType definition of the quadratic bézier (which omits the end points of the curve).