Skip to content

Latest commit

 

History

History
798 lines (575 loc) · 20.8 KB

usvg_spec.adoc

File metadata and controls

798 lines (575 loc) · 20.8 KB
Raw

Micro SVG Document Structure

Table of Contents

Intro

SVG Micro represents a strip down SVG Full 1.1 subset.

Here is the main differences between SVG Full and SVG Micro.

  • No XML DTD.

  • No CSS.

  • use, marker and nested svg will be resolved.

  • Simplified path notation. Only absolute MoveTo, LineTo, CurveTo and ClosePath segments are allowed.

  • No inheritable attributes.

  • No xlink:href, except the image element.

  • No recursive references.

  • Only valid elements and attributes.

  • No unused elements.

  • No redundant groups.

  • No units.

  • No style attribute.

  • Default attributes are implicit.

You can use usvg to convert a random SVG into a SVG Micro almost losslessly.

Elements

The svg element

The svg element is the root element of the document. It’s defined only once and can’t be nested, unlike by the SVG spec.

Children:

Attributes:

The defs element

Always present. Always the first svg child. Can be empty.

Children:

Attributes:

  • none

The linearGradient element

Doesn’t have a xlink:href attribute because all attributes and stop children will be resolved.

Children:

Attributes:

The radialGradient element

Doesn’t have a xlink:href attribute because all attributes and stop children will be resolved.

Children:

Attributes:

The stop element

Gradient’s stop children will always have unique, ordered offset values in the 0..1 range.

Children:

  • none

Attributes:

The pattern element

Doesn’t have a xlink:href attribute because all attributes and children will be resolved.

Children:

  • g

  • path

  • image

Attributes:

The clipPath element

Children:

  • path

Attributes:

  • id = <string>
    The element ID. Always set. Guarantee to be unique.

  • clip-path = <FuncIRI> ?
    An optional reference to a supplemental clipPath.
    Default: none

  • clipPathUnits = objectBoundingBox?
    Default: userSpaceOnUse

  • transform = <transform> ?

The mask element

Children:

  • g

  • path

  • image

Attributes:

The filter element

Doesn’t have a xlink:href attribute because all attributes and children will be resolved.

Children:

Attributes:

The g element

The group element indicates that a new canvas should be created. All group’s children elements will be rendered on it and then merged into the parent canvas.

Since it’s pretty expensive, especially memory wise, usvg will remove as many groups as possible. And all the remaining one will indicate that a new canvas must be created.

A group can have no children when it has a filter attribute.

A group will have at least one of the attributes present.

Children:

Attributes:

  • id = <string> ?
    An optional, but never empty, element ID.

  • opacity = <opacity> ?

  • clip-path = <FuncIRI> ?
    Cannot be set to none.

  • mask = <FuncIRI> ?
    Cannot be set to none.

  • filter = <FuncIRI> +
    Cannot be set to none.

  • fill = none | <color> | <FuncIRI>
    Will be set only when any of the filter primitives has a FillPaint input.

  • stroke = none | <color> | <FuncIRI>
    Will be set only when any of the filter primitives has a StrokePaint input.

  • transform = <transform> ?

  • enable-background = new | new <number> <number> <positive-number> <positive-number>?

The path element

Children:

  • none

Attributes:

  • id = <string> ?
    An optional, but never empty, element ID.

  • d = <path-data>

  • fill = none | <color> | <FuncIRI>
    If set to none than all fill-* attributes will not be set too.
    Default: black

  • fill-opacity = <opacity> ?
    Default: 1

  • fill-rule = evenodd?
    Default: nonzero

  • stroke = none | <color> | <FuncIRI>
    If set to none than all stroke-* attributes will not be set too.
    Default: none

  • stroke-width = <positive-number> ?
    Default: 1

  • stroke-linecap = round | square?
    Default: butt

  • stroke-linejoin = round | bevel?
    Default: miter

  • stroke-miterlimit = <positive-number> ?
    Guarantee to be > 1.
    Default: 4

  • stroke-dasharray = <list-of-numbers>?
    Guarantee to have even amount of numbers.
    Default: none

  • stroke-dashoffset = <number> ?

  • stroke-opacity = <opacity> ?
    Default: 1

  • clip-rule = evenodd?
    Will be set only inside the clipPath, instead of fill-rule.

  • clip-path = <FuncIRI> ?
    Available only inside the clipPath.

  • shape-rendering = optimizeSpeed | crispEdges?
    Default: geometricPrecision

  • visibility = hidden | collapse?
    Default: visible

  • transform = <transform> ?

The image element

Children:

  • none

Attributes:

Filter primitives

Filter primitive attributes

The attributes below are the same for all filter primitives.

The x, y, width and height attributes can be omited. SVG has a pretty complex rules of resolving them and I don’t fully understand them yet. Neither do others, because they are pretty poorly implemented.

Filter primitive feBlend

Attributes:

Filter primitive feColorMatrix

Attributes:

  • in = <filter-input>

  • type = matrix | saturate | hueRotate | luminanceToAlpha

  • values = <list-of-numbers>?

    • For type=matrix, contains 20 numbers.

    • For type=saturate, contains a single number in a 0..1 range.

    • For type=hueRotate, contains a single number.

    • Not present for type=luminanceToAlpha.

  • Filter primitive attributes

Filter primitive feComponentTransfer

Children:

  • feFuncR

  • feFuncG

  • feFuncB

  • feFuncA

The all four will always be present.

Attributes:

feFunc(R|G|B|A) attributes:

  • type = identity | table | discrete | linear | gamma

  • tableValues = <list-of-numbers>?
    Present only when type=table | discrete. Can be empty.

  • slope = <number> ?
    Present only when type=linear.

  • intercept = <number> ?
    Present only when type=linear.

  • amplitude = <number> ?
    Present only when type=gamma.

  • exponent = <number> ?
    Present only when type=gamma.

  • offset = <number> ?
    Present only when type=gamma.

Filter primitive feComposite

Attributes:

Filter primitive feConvolveMatrix

Attributes:

Filter primitive feDiffuseLighting

Children:

Only one of:

  • feDistantLight

  • fePointLight

  • feSpotLight

Attributes:

feDistantLight attributes:

fePointLight attributes:

feSpotLight attributes:

Filter primitive feDisplacementMap

Attributes:

Filter primitive feDropShadow

Attributes:

Filter primitive feFlood

Attributes:

Filter primitive feGaussianBlur

Attributes:

Filter primitive feImage

Attributes:

Filter primitive feMerge

Children:

  • feMergeNode

Attributes:

feMergeNode attributes:

Filter primitive feMorphology

Attributes:

Filter primitive feOffset

Attributes:

Filter primitive feSpecularLighting

Children:

Only one of:

  • feDistantLight

  • fePointLight

  • feSpotLight

Attributes:

feDistantLight attributes:

fePointLight attributes:

feSpotLight attributes:

Filter primitive feTile

Attributes:

Filter primitive feTurbulence

Attributes:

Data types

If an attribute has the ? symbol after the type that’s mean that that this attribute is optional.

<string> - A Unicode (UTF-8) string.

<number> - A real number.
number ::= [-]? [0-9]+ "." [0-9]+

<positive-number> - A positive real number.
positive-number ::= [0-9]+ "." [0-9]+

<integer> - An integer.
integer ::= [-]? [0-9]+

<positive-integer> - A positive integer.
positive-integer ::= [0-9]+

<opacity> - A real number in a 0..1 range.
opacity ::= positive-number

<offset> - A real number in a 0..1 range.
offset ::= positive-number

<color> - A hex-encoded RGB color.

color    ::= "#" hexdigit hexdigit hexdigit hexdigit hexdigit hexdigit
hexdigit ::= [0-9a-f]

<IRI> - An Internationalized Resource Identifier. Always a valid, local reference.
IRI ::= string

<FuncIRI> - Functional notation for an IRI. Always a valid, local reference.
FuncIRI ::= url( <IRI> )

<filter-input> - A filter source. A reference to a result guarantee to be valid.

filter-input ::= SourceGraphic | SourceAlpha | BackgroundImage
                 | BackgroundAlpha | FillPaint | StrokePaint
                 | <string>

<viewBox> - Defines an element viewBox. viewBox ::= <number> " " <number> " " <positive-number> " " <positive-number>

<preserveAspectRatio> - A scaling method definition. Works exactly the same as described in the SVG spec.

<transform> - A transformation matrix. Always a matrix and not translate, scale, etc. Numbers are space-separated.
transform ::= matrix( <number> " " <number> " " <number> " " <number> " " <number> " " <number> )

<path-data> - A path data.

  • Contains only absolute MoveTo, LineTo, CurveTo and ClosePath segments.

  • All segments are explicit.

  • The first segment is guarantee to be MoveTo.

  • Segments, commands and coordinates are separated only by space.

  • Path and all subpaths are guarantee to have at least two segments.

Grammar:

svg-path:
    moveto-drawto-command-groups
moveto-drawto-command-groups:
    moveto-drawto-command-group
    | moveto-drawto-command-group " " moveto-drawto-command-groups
moveto-drawto-command-group:
    moveto " " drawto-commands
drawto-commands:
    drawto-command
    | drawto-command " " drawto-commands
drawto-command:
    closepath
    | lineto
    | curveto
moveto:
    "M " coordinate-pair
lineto:
    "L " coordinate-pair
curveto:
    "C " coordinate-pair " " coordinate-pair " " coordinate-pair
closepath:
    "Z"
coordinate-pair:
    coordinate " " coordinate
coordinate:
    sign? digit-sequence "." digit-sequence
sign:
    "-"
digit-sequence:
    digit
    | digit digit-sequence
digit:
    "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

Basically, a path looks like this: M 10.5 20 L 30 40. Commands and numbers are separated by a space. Numbers with an exponent are not allowed. Trimmed numbers like -.5 are not allowed.