Name:
feFuncA
Categories:
Transfer function
element
Content model:
Any number of the following elements, in any order:
Attributes:
DOM Interfaces:
SVGFEFuncAElement
The attributes below are the
transfer function element
attributes
, which apply to the
transfer function elements
Attribute definitions:
type
= "
identity | table | discrete | linear | gamma
Indicates the type of component transfer function. The type of
function determines the applicability of the other attributes.
In the following, C is the initial component (e.g.,
), C' is the remapped
component; both in the closed interval [0,1].
For ‘
identity
’:
C' = C
For ‘
table
’, the function is defined
by linear interpolation between values given in the attribute
tableValues
. The table has
n+1
values (i.e., v
to v
specifying the start and end values for
evenly sized
interpolation regions. Interpolations use the following formula:
For a value
C < 1
find
such
that:
k/n <= C < (k+1)/n
The result
C'
is given by:
C' = v
+ (C - k/n)*n *
(v
k+1
- v
If
C = 1
then:
C' = v
For ‘
discrete
’, the function is
defined by the step function given in the attribute
tableValues
, which provides a list of
values (i.e., v
to v
n-1
) in
order to identify a step function consisting of
steps.
The step function is defined by the following formula:
For a value
C < 1
find
such
that:
k/n <= C < (k+1)/n
The result
C'
is given by:
C' = v
If
C = 1
then:
C' = v
n-1
For ‘
linear
’, the function is
defined by the following linear equation:
C' =
slope
* C +
intercept
For ‘
gamma
’, the function is defined
by the following exponential function:
C' =
amplitude
* pow(C,
exponent
) +
offset
Animatable: yes.
tableValues
= "
(list of
s)
When
type="table"
, the list of
v0,v1,...vn
, separated by white space and/or a comma,
which define the lookup table. An empty list results in an identity
transfer function. If the attribute is not specified, then the
effect is as if an empty list were provided.
Animatable: yes.
slope
= "
When
type="linear"
, the slope of
the linear function.
The
lacuna
value
for
slope
is
Animatable: yes.
intercept
= "
When
type="linear"
, the intercept
of the linear function.
The
lacuna
value
for
intercept
is
Animatable: yes.
amplitude
= "
When
type="gamma"
, the amplitude of
the gamma function.
The
lacuna
value
for
amplitude
is
Animatable: yes.
exponent
= "
When
type="gamma"
, the exponent of
the gamma function.
The
lacuna
value
for
exponent
is
Animatable: yes.
offset
= "
When
type="gamma"
, the offset of
the gamma function.
The
lacuna
value
for
offset
is
Animatable: yes.
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
Example for feComponentTransfer
View
this example as SVG (SVG-enabled browsers only)
Name:
feComposite
Categories:
Filter primitive
element
Content model:
Any number of the following elements, in any order:
Attributes:
core
attributes
‘id’
‘xml:base’
‘xml:lang’
‘xml:space’
presentation
attributes
alignment-baseline
baseline-shift
clip
clip-path
clip-rule
color
color-interpolation
color-interpolation-filters
color-profile
color-rendering
cursor
direction
display
dominant-baseline
enable-background
fill
fill-opacity
fill-rule
filter
flood-color
flood-opacity
font
font-family
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-weight
glyph-orientation-horizontal
glyph-orientation-vertical
image-rendering
kerning
letter-spacing
lighting-color
marker
marker-end
marker-mid
marker-start
mask
mix-blend-mode
opacity
overflow
pointer-events
shape-rendering
stop-color
stop-opacity
stroke
stroke-dasharray
stroke-dashoffset
stroke-linecap
stroke-linejoin
stroke-miterlimit
stroke-opacity
stroke-width
text-anchor
text-decoration
text-rendering
unicode-bidi
visibility
word-spacing
writing-mode
filter primitive
attributes
‘x’
‘y’
‘width’
‘height’
‘result’
‘class’
‘style’
‘in’
‘in2’
‘operator’
‘k1’
‘k2’
‘k3’
‘k4’
DOM Interfaces:
SVGFECompositeElement
This filter performs the combination of the two input images
pixel-wise in image space using one of the Porter-Duff [
PORTERDUFF
] compositing operations:
over, in, atop, out, xor
[COMPOSITING]
Additionally, a component-wise
arithmetic
operation (with the
result clamped between [0..1]) can be applied.
The
arithmetic
operation is useful for combining the
output from the
and
filters with
texture data. It is also useful for implementing
dissolve
. If
the
arithmetic
operation is chosen, each result pixel is
computed using the following formula:
result = k1*i1*i2 + k2*i1 + k3*i2 + k4
where:
i1
and
i2
indicate the corresponding
pixel channel values of the input image, which map to
in
and
in2
respectively
k1, k2, k3
and
k4
indicate the values
of the attributes with the same name
For this filter primitive, the extent of the resulting image might
grow as described in the section that describes the
filter primitive subregion
Attribute definitions:
operator
= "
over | in | out | atop | xor | arithmetic
The compositing operation that is to be performed. All of the
operator
types except
arithmetic
match the corresponding operation
as described in [
PORTERDUFF
]. The
arithmetic
operator is described
above. The
lacuna
value
for
operator
is
over
Animatable: yes.
k1
= "
Only applicable if
operator="arithmetic"
The
lacuna
value
for
k1
is
Animatable: yes.
k2
= "
Only applicable if
operator="arithmetic"
The
lacuna
value
for
k2
is
Animatable: yes.
k3
= "
Only applicable if
operator="arithmetic"
The
lacuna
value
for
k3
is
Animatable: yes.
k4
= "
Only applicable if
operator="arithmetic"
The
lacuna
value
for
k4
is
Animatable: yes.
in2
(see
in
attribute)
The second input image to the compositing operation. This
attribute can take on the same values as the
in
attribute.
Animatable: yes.
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
an opaque white surface, thus obliterating the background.
the background, thus sometimes causing the background to continue
to appear in some cases, and in other cases the background
image blends into itself ("double-counting").
Example of feComposite
View this
example as SVG (SVG-enabled browsers only)
Name:
feConvolveMatrix
Categories:
Filter primitive
element
Content model:
Any number of the following elements, in any order:
Attributes:
core
attributes
‘id’
‘xml:base’
‘xml:lang’
‘xml:space’
presentation
attributes
alignment-baseline
baseline-shift
clip
clip-path
clip-rule
color
color-interpolation
color-interpolation-filters
color-profile
color-rendering
cursor
direction
display
dominant-baseline
enable-background
fill
fill-opacity
fill-rule
filter
flood-color
flood-opacity
font
font-family
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-weight
glyph-orientation-horizontal
glyph-orientation-vertical
image-rendering
kerning
letter-spacing
lighting-color
marker
marker-end
marker-mid
marker-start
mask
mix-blend-mode
opacity
overflow
pointer-events
shape-rendering
stop-color
stop-opacity
stroke
stroke-dasharray
stroke-dashoffset
stroke-linecap
stroke-linejoin
stroke-miterlimit
stroke-opacity
stroke-width
text-anchor
text-decoration
text-rendering
unicode-bidi
visibility
word-spacing
writing-mode
filter primitive
attributes
‘x’
‘y’
‘width’
‘height’
‘result’
‘class’
‘style’
‘in’
‘order’
‘kernelMatrix’
‘divisor’
‘bias’
‘targetX’
‘targetY’
‘edgeMode’
‘kernelUnitLength’
‘preserveAlpha’
DOM Interfaces:
SVGFEConvolveMatrixElement
feConvolveMatrix applies a matrix convolution filter effect. A
convolution combines pixels in the input image with neighboring pixels
to produce a resulting image. A wide variety of imaging operations can
be achieved through convolutions, including blurring, edge detection,
sharpening, embossing and beveling.
A matrix convolution is based on an n-by-m matrix (the convolution
kernel) which describes how a given pixel value in the input image is
combined with its neighboring pixel values to produce a resulting
pixel value. Each result pixel is determined by applying the kernel
matrix to the corresponding source pixel and its neighboring pixels.
The basic convolution formula which is applied to each color value for
a given pixel is:
color
orderY
orderX
source
targetX
targetY
kernalMatrix
orderX
1,
orderY
divisor
bias
alpha
where "orderX" and "orderY" represent the X and Y values for the
order
attribute, "targetX" represents the
value of the
targetX
attribute, "targetY" represents
the value of the
targetY
attribute, "kernelMatrix"
represents the value of the
kernelMatrix
attribute, "divisor"
represents the value of the
divisor
attribute, and "bias" represents
the value of the
bias
attribute.
Note in the above formulas that the values in the kernel matrix are
applied such that the kernel matrix is rotated 180 degrees relative to
the source and destination images in order to match convolution theory
as described in many computer graphics textbooks.
To illustrate, suppose you have a input image which is 5 pixels by
5 pixels, whose color values for one of the color channels are as
follows:
20
40
235
235
100
120
140
235
235
200
220
240
235
235
255
255
255
255
255
255
255
255
255
255
and you define a 3-by-3 convolution kernel as follows:
Let's focus on the color value at the second row and second column
of the image (source pixel value is 120). Assuming the simplest case
(where the input image's pixel grid aligns perfectly with the kernel's
pixel grid) and assuming default values for attributes
divisor
targetX
and
targetY
, then resulting color value will
be:
resultChannel
2,2
20
40
100
120
140
200
220
240
Because they operate on pixels, matrix convolutions are inherently
resolution-dependent. To make
produce
resolution-independent results, an explicit value should be provided
for either the
filterRes
attribute on the
element and/or attribute
kernelUnitLength
kernelUnitLength
, in combination with the
other attributes, defines an implicit pixel grid in the filter effects
coordinate system (i.e., the coordinate system established by the
primitiveUnits
attribute). If the pixel
grid established by
kernelUnitLength
is not scaled to match
the pixel grid established by attribute
filterRes
(implicitly or explicitly),
then the input image will be temporarily rescaled to match its pixels
with
kernelUnitLength
. The convolution happens
on the resampled image. After applying the convolution, the image is
resampled back to the original resolution.
When the image must be resampled to match the coordinate system
defined by
kernelUnitLength
prior to convolution, or
resampled to match the device coordinate system after convolution, it
is recommended that high quality viewers make use of appropriate
interpolation techniques, for example bilinear or bicubic. Depending
on the speed of the available interpolents, this choice may be
affected by the
image-rendering
property setting. Note
that implementations might choose approaches that minimize or
eliminate resampling when not necessary to produce proper results,
such as when the document is zoomed out such that
kernelUnitLength
is considerably smaller
than a device pixel.
Attribute definitions:
order
= "
Indicates the number of cells in each dimension for
kernelMatrix
. The values provided must
be
s greater than zero. Values that are not integers will be truncated,
i.e. rounded to the closest integer value towards zero. The first
number,
matrix. The second number,
rows in the matrix. If
to
It is recommended that only small values (e.g., 3) be used; higher
values may result in very high CPU overhead and usually do not
produce results that justify the impact on performance.
The
lacuna
value
for
order
is
Animatable: yes.
kernelMatrix
= "numbers>
The list of
s that make up the kernel matrix for the convolution. Values are
separated by space characters and/or a comma. The number of entries
in the list must equal
Animatable: yes.
divisor
= "
After applying the
kernelMatrix
to
the input image to yield a number, that number is divided by
divisor
to yield the final destination
color value. A divisor that is the sum of all the matrix values
tends to have an evening effect on the overall color intensity of
the result. If the specified divisor is zero then the default value
will be used instead. The
lacuna
value
is the sum of all values in kernelMatrix, with the
exception that if the sum is zero, then the divisor is set to
Animatable: yes.
bias
= "
After applying the
kernelMatrix
to
the input image to yield a number and applying the
divisor
, the
bias
attribute is added to each
component. One application of
bias
is when it is desirable to have
.5
gray value be the zero response of
the filter. The bias property shifts the range of the filter. This
allows representation of values that would otherwise be clamped to 0
or 1.
The
lacuna
value
for
bias
is
Animatable: yes.
targetX
= "
Determines the positioning in X of the convolution matrix
relative to a given target pixel in the input image. The leftmost
column of the matrix is column number zero. The value must be such
that: 0 <= targetX < orderX. By default, the convolution
matrix is centered in X over each pixel of the input image (i.e.,
targetX = floor ( orderX / 2 )).
Animatable: yes.
targetY
= "
Determines the positioning in Y of the convolution matrix
relative to a given target pixel in the input image. The topmost row
of the matrix is row number zero. The value must be such that: 0
<= targetY < orderY. By default, the convolution matrix is
centered in Y over each pixel of the input image (i.e., targetY =
floor ( orderY / 2 )).
Animatable: yes.
edgeMode
= "
duplicate |
wrap | none
Determines how to extend the input image as necessary with color
values so that the matrix operations can be applied when the kernel
is positioned at or near the edge of the input image.
"duplicate" indicates that the input image is extended along each
of its borders as necessary by duplicating the color values at the
given edge of the input image.
Original N-by-M image, where m=M-1 and n=N-1:
11
12
21
22
nm
nM
Nm
NM
Extended by two pixels using "duplicate":
11
11
11
12
11
11
11
12
11
11
11
12
21
21
21
22
nm
nM
nM
nM
Nm
NM
NM
NM
Nm
NM
NM
NM
Nm
NM
NM
NM
"wrap" indicates that the input image is extended by taking the
color values from the opposite edge of the image.
Extended by two pixels using "wrap":
nm
nM
n1
n2
nm
nM
n1
n2
Nm
NM
N1
N2
Nm
NM
N1
N2
1m
1M
11
12
1m
1M
11
12
2m
2M
21
22
2m
2M
21
22
nm
nM
n1
n2
nm
nM
n1
n2
Nm
NM
N1
N2
Nm
NM
N1
N2
1m
1M
11
12
1m
1M
11
12
2m
2M
21
22
2m
2M
21
22
The value
none
indicates that the
input image is extended with pixel values of zero for R, G, B and
A.
The
lacuna
value
for
edgeMode
is
duplicate
Animatable: yes.
kernelUnitLength
= "
The first number is the
the
defaults to the same value as
distance in current filter units (i.e., units as determined by the
value of attribute
primitiveUnits
) between successive
columns and rows, respectively, in the
kernelMatrix
. By specifying value(s)
for
kernelUnitLength
, the kernel becomes
defined in a scalable, abstract coordinate system. If
kernelUnitLength
is not specified, the
default value is one pixel in the offscreen bitmap, which is a
pixel-based coordinate system, and thus potentially not scalable.
For some level of consistency across display media and user agents,
it is necessary that a value be provided for at least one of
filterRes
and
kernelUnitLength
. In some
implementations, the most consistent results and the fastest
performance will be achieved if the pixel grid of the temporary
offscreen images aligns with the pixel grid of the kernel.
If a negative or zero value is specified the default value will be
used instead.
Animatable: yes.
preserveAlpha
= "
false |
true
A value of
false
indicates that the
convolution will apply to all channels, including the alpha channel.
In this case the
ALPHA
X,Y
of the
convolution formula
for a
given pixel is:
ALPHA
X,Y
= (
SUM
I=0 to [
orderY
-1]
SUM
J=0 to [
orderX
-1]
SOURCE
X-
targetX
+J, Y-
targetY
+I
kernelMatrix
orderX
-J-1,
orderY
-I-1
) /
divisor
bias
A value of
true
indicates that the
convolution will only apply to the color channels. In this case, the
filter will temporarily unpremultiply the color component values,
apply the kernel, and then re-premultiply at the end. In this case
the
ALPHA
X,Y
of the
convolution formula
for a
given pixel is:
ALPHA
X,Y
= SOURCE
X,Y
The
lacuna
value
for
preserveAlpha
is
false
Animatable: yes.
8.9.
Filter primitive
Name:
feCustom
Categories:
Filter primitive
element
Content model:
Any number of the following elements, in any order:
Attributes:
core
attributes
‘id’
‘xml:base’
‘xml:lang’
‘xml:space’
presentation
attributes
alignment-baseline
baseline-shift
clip
clip-path
clip-rule
color
color-interpolation
color-interpolation-filters
color-profile
color-rendering
cursor
direction
display
dominant-baseline
enable-background
fill
fill-opacity
fill-rule
filter
flood-color
flood-opacity
font
font-family
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-weight
glyph-orientation-horizontal
glyph-orientation-vertical
image-rendering
kerning
letter-spacing
lighting-color
marker
marker-end
marker-mid
marker-start
mask
mix-blend-mode
opacity
overflow
pointer-events
shape-rendering
stop-color
stop-opacity
stroke
stroke-dasharray
stroke-dashoffset
stroke-linecap
stroke-linejoin
stroke-miterlimit
stroke-opacity
stroke-width
text-anchor
text-decoration
text-rendering
unicode-bidi
visibility
word-spacing
writing-mode
filter primitive
attributes
‘x’
‘y’
‘width’
‘height’
‘result’
‘class’
‘style’
‘geometry’
DOM Interfaces:
SVGFECustomElement
Attribute definitions:
geometry
= "
grid(
detached | attached ]?
See the ‘
geometry
’ descriptor.
Animatable: yes.
The calculations are performed on non-premultiplied color values.
If the input graphics consists of premultiplied color values, those
values are converted into non-premultiplied color values for this
operation.
Each ‘
feCustom
’ element can have any number of
feCustomSource
’ subelements. Each ‘
feCustomSource
’ references one resource.
Attribute definitions:
src
= "
An
Functional IRI reference
to an
resource which defines the custom filter.
Animatable: yes.
format
= "
The format of the resource referenced by the
src
attribute.
Animatable: yes.
Each ‘
feCustom
’ element can have any number of
feCustomParam
’ subelements. Each ‘
feCustomParam
node passes one parameter.
Attribute definitions:
ident
Indicates the parameter name to the shaders.
Animatable: yes.
type
number | array | vec2 | vec3 | vec4 | mat2 | mat3 | mat4 |
color | image | transform
Indicates the type of the parameter passed to the shaders. For
the types ‘
number
’, ‘
array
’, ‘
vec2
’,
vec3
’, ‘
vec4
’, ‘
mat2
’,
mat3
’ and ‘
mat4
’, the
values
attribute passes the values to
the shader. For all other types, the attributes with the same name
pass the parameter to the shader. The
lacuna
value
for
type
is
number
Animatable: yes.
values
list of
The contents of
values
depends on
the value of attribute
type
For
type="number"
values
is a single real number value.
For
type="array"
values
is a list of at least one real
number value.
For
type="vec2"
values
is a list of two real number values.
The value list is interpreted as a vertical list, where the first
entry equals the parameter on the top of the vector.
For
type="vec3"
values
is a list of three real number
values. The value list is interpreted as a vertical list, where
the first entry equals the parameter on the top of the vector.
For
type="vec4"
values
is a list of four real number
values. The value list is interpreted as a vertical list, where
the first entry equals the parameter on the top of the vector.
For
type="mat2"
values
is a list of four real number
values. The list specifies a 2x2 homogeneous matrix in
column-major order.
For
type="mat3"
values
is a list of nine real number
values. The list specifies a 3x3 homogeneous matrix in
column-major order.
For
type="mat4"
values
is a list of 16 real number values.
The list specifies a 4x4 homogeneous matrix in column-major order.
If the attribute is not specified, then the default behavior
depends on the value of attribute
type
. If
type
is ‘
mat2
’, ‘
mat3
’ or ‘
mat4
’, then
this attribute defaults to the identity matrix. If
type
is ‘
number
or ‘
array
’, then this attribute defaults
to the value 0. If
type
is ‘
vec2
’, ‘
vec3
’ or
vec4
’, then this attribute defaults to
a number list with values of 0. The length of the number list
depends on the size of the specified vector.
Animatable: yes.
color
Indicates that a color value is passed as parameter to the
shaders.
Animatable: yes.
image
Indicates that a image is passed as parameter to the shaders.
Animatable: yes.
transform
= "
Indicates that a list of transform functions is passed as
parameter to the shaders.
Animatable: yes.
Name:
feDiffuseLighting
Categories:
Filter primitive
element
Content model:
Any number of
descriptive
elements
and exactly one
light source element
, in any
order.
Attributes:
core
attributes
‘id’
‘xml:base’
‘xml:lang’
‘xml:space’
presentation
attributes
alignment-baseline
baseline-shift
clip
clip-path
clip-rule
color
color-interpolation
color-interpolation-filters
color-profile
color-rendering
cursor
direction
display
dominant-baseline
enable-background
fill
fill-opacity
fill-rule
filter
flood-color
flood-opacity
font
font-family
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-weight
glyph-orientation-horizontal
glyph-orientation-vertical
image-rendering
kerning
letter-spacing
lighting-color
marker
marker-end
marker-mid
marker-start
mask
mix-blend-mode
opacity
overflow
pointer-events
shape-rendering
stop-color
stop-opacity
stroke
stroke-dasharray
stroke-dashoffset
stroke-linecap
stroke-linejoin
stroke-miterlimit
stroke-opacity
stroke-width
text-anchor
text-decoration
text-rendering
unicode-bidi
visibility
word-spacing
writing-mode
filter primitive
attributes
‘x’
‘y’
‘width’
‘height’
‘result’
‘class’
‘style’
‘in’
‘surfaceScale’
‘diffuseConstant’
‘kernelUnitLength’
DOM Interfaces:
SVGFEDiffuseLightingElement
This filter primitive lights an image using the alpha channel as a
bump map. The resulting image is an RGBA opaque image based on the
light color with alpha = 1.0 everywhere. The lighting calculation
follows the standard diffuse component of the Phong lighting model.
The resulting image depends on the light color, light position and
surface geometry of the input bump map.
The light map produced by this filter primitive can be combined
with a texture image using the multiply term of the
arithmetic
compositing method.
Multiple light sources can be simulated by adding several of these
light maps together before applying it to the texture image.
The formulas below make use of 3x3 filters. Because they operate on
pixels, such filters are inherently resolution-dependent. To make
produce
resolution-independent results, an explicit value should be provided
for either the
filterRes
attribute on the
element and/or attribute
kernelUnitLength
kernelUnitLength
, in combination with the
other attributes, defines an implicit pixel grid in the filter effects
coordinate system (i.e., the coordinate system established by the
primitiveUnits
attribute). If the pixel
grid established by
kernelUnitLength
is not scaled to match
the pixel grid established by attribute
filterRes
(implicitly or explicitly),
then the input image will be temporarily rescaled to match its pixels
with
kernelUnitLength
. The 3x3 filters are
applied to the resampled image. After applying the filter, the image
is resampled back to its original resolution.
When the image must be
resampled, it is recommended that high quality viewers make use of
appropriate interpolation techniques, for example bilinear or
bicubic.
Depending on the speed of the available interpolents,
this choice may be affected by the
image-rendering
property setting. Note
that implementations might choose approaches that minimize or
eliminate resampling when not necessary to produce proper results,
such as when the document is zoomed out such that
kernelUnitLength
is considerably smaller
than a device pixel.
For the formulas that follow, the
Norm(A
,A
,A
function
is defined as:
Consider making this into mathml
Norm(A
,A
,A
= sqrt(A
^2+A
^2+A
^2)
The resulting RGBA image is computed as follows:
= k
* N.L *
= k
* N.L * L
= k
* N.L * L
= 1.0
where
= diffuse lighting constant
N = surface normal unit vector, a function of x and y
L = unit vector pointing from surface to light, a function of x and y
in the point and spot light cases
,L
,L
= RGB components of light,
a function of x and y in the spot light case
N is a function of x and y and depends on the surface gradient as
follows:
The surface described by the input alpha image I(x,y) is:
Z (x,y) = surfaceScale * I(x,y)
Surface normal is calculated using the
Sobel gradient 3x3 filter. Different filter kernels are used depending
on whether the given pixel is on the interior or an edge. For each
case, the formula is:
(x,y) = - surfaceScale *
FACTOR
(K
(0,0)*I(x-dx,y-dy) +
(1,0)*I(x,y-dy) + K
(2,0)*I(x+dx,y-dy) +
(0,1)*I(x-dx,y) +
(1,1)*I(x,y) +
(2,1)*I(x+dx,y) +
(0,2)*I(x-dx,y+dy) +
(1,2)*I(x,y+dy) + K
(2,2)*I(x+dx,y+dy))
(x,y) = - surfaceScale * FACTOR
(K
(0,0)*I(x-dx,y-dy) +
(1,0)*I(x,y-dy) + K
(2,0)*I(x+dx,y-dy) +
(0,1)*I(x-dx,y) +
(1,1)*I(x,y) +
(2,1)*I(x+dx,y) +
(0,2)*I(x-dx,y+dy) +
(1,2)*I(x,y+dy) + K
(2,2)*I(x+dx,y+dy))
(x,y) = 1.0
N = (N
, N
, N
) /
Norm((N
,N
,N
))
In these formulas, the
dx
and
dy
values
(e.g.,
I(x-dx,y-dy)
), represent deltas relative to a
given
(x,y)
position for the purpose of estimating the
slope of the surface at that point. These deltas are determined by the
value (explicit or implicit) of attribute
kernelUnitLength
Top/left corner:
FACTOR
=2/(3*dx)
| 0 0 0 |
| 0 -2 2 |
| 0 -1 1 |
FACTOR
=2/(3*dy)
| 0 0 0 |
| 0 -2 -1 |
| 0 2 1 |
Top row:
FACTOR
=1/(3*dx)
| 0 0 0 |
| -2 0 2 |
| -1 0 1 |
FACTOR
=1/(2*dy)
| 0 0 0 |
| -1 -2 -1 |
| 1 2 1 |
Top/right corner:
FACTOR
=2/(3*dx)
| 0 0 0 |
| -2 2 0 |
| -1 1 0 |
FACTOR
=2/(3*dy)
| 0 0 0 |
| -1 -2 0 |
| 1 2 0 |
Left column:
FACTOR
=1/(2*dx)
| 0 -1 1 |
| 0 -2 2 |
| 0 -1 1 |
FACTOR
=1/(3*dy)
| 0 -2 -1 |
| 0 0 0 |
| 0 2 1 |
Interior pixels:
FACTOR
=1/(4*dx)
| -1 0 1 |
| -2 0 2 |
| -1 0 1 |
FACTOR
=1/(4*dy)
| -1 -2 -1 |
| 0 0 0 |
| 1 2 1 |
Right column:
FACTOR
=1/(2*dx)
| -1 1 0|
| -2 2 0|
| -1 1 0|
FACTOR
=1/(3*dy)
| -1 -2 0 |
| 0 0 0 |
| 1 2 0 |
Bottom/left corner:
FACTOR
=2/(3*dx)
| 0 -1 1 |
| 0 -2 2 |
| 0 0 0 |
FACTOR
=2/(3*dy)
| 0 -2 -1 |
| 0 2 1 |
| 0 0 0 |
Bottom row:
FACTOR
=1/(3*dx)
| -1 0 1 |
| -2 0 2 |
| 0 0 0 |
FACTOR
=1/(2*dy)
| -1 -2 -1 |
| 1 2 1 |
| 0 0 0 |
Bottom/right corner:
FACTOR
=2/(3*dx)
| -1 1 0 |
| -2 2 0 |
| 0 0 0 |
FACTOR
=2/(3*dy)
| -1 -2 0 |
| 1 2 0 |
| 0 0 0 |
L, the unit vector from the image sample to the light, is
calculated as follows:
For Infinite light sources it is constant:
= cos(azimuth)*cos(elevation)
= sin(azimuth)*cos(elevation)
= sin(elevation)
For Point and spot lights it is a function of position:
= Light
- x
= Light
- y
= Light
- Z(x,y)
L = (L
, L
, L
) /
Norm(L
, L
, L
where Light
, Light
, and Light
are the input light position.
,L
,L
, the light color vector,
is a function of position in the spot light case only:
Light
*pow((-L.S),specularExponent)
= Light
*pow((-L.S),specularExponent)
= Light
*pow((-L.S),specularExponent)
where S is the unit vector pointing from the light to the point
(pointsAtX, pointsAtY, pointsAtZ) in the x-y plane:
= pointsAtX -
Light
= pointsAtY - Light
= pointsAtZ - Light
S = (S
, S
, S
) /
Norm(S
, S
, S
If L.S is positive, no light is present. (L
= L
= 0). If
limitingConeAngle
is specified, -L.S <
cos(limitingConeAngle) also indicates that no light is present.
Attribute definitions:
surfaceScale
= "
height of surface when A
in
= 1.
If the attribute is not specified, then the effect is as if a value
of
were specified.
Animatable: yes.
diffuseConstant
= "
kd in Phong lighting model. In SVG, this can be any non-negative
number.
If the attribute is not specified, then the effect is as if a value
of
were specified.
Animatable: yes.
kernelUnitLength
= "
The first number is the
the
defaults to the same value as
distance in current filter units (i.e., units as determined by the
value of attribute
primitiveUnits
) for
dx
and
dy
, respectively, in the
surface normal calculation
formulas
. By specifying value(s) for
kernelUnitLength
, the kernel becomes defined
in a scalable, abstract coordinate system. If
kernelUnitLength
is not specified, the
dx
and
dy
values should represent very
small deltas relative to a given
(x,y)
position, which
might be implemented in some cases as one pixel in the intermediate
image offscreen bitmap, which is a pixel-based coordinate system,
and thus potentially not scalable. For some level of consistency
across display media and user agents, it is necessary that a value
be provided for at least one of
filterRes
and
kernelUnitLength
. Discussion of intermediate
images are in the
Introduction
and in
the description of attribute
filterRes
If a negative or zero value is specified the default value will be
used instead.
Animatable: yes.
The light source is defined by one of the child elements
or
. The light color is
specified by property
lighting-color
Name:
feDisplacementMap
Categories:
Filter primitive
element
Content model:
Any number of the following elements, in any order:
Attributes:
core
attributes
‘id’
‘xml:base’
‘xml:lang’
‘xml:space’
presentation
attributes
alignment-baseline
baseline-shift
clip
clip-path
clip-rule
color
color-interpolation
color-interpolation-filters
color-profile
color-rendering
cursor
direction
display
dominant-baseline
enable-background
fill
fill-opacity
fill-rule
filter
flood-color
flood-opacity
font
font-family
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-weight
glyph-orientation-horizontal
glyph-orientation-vertical
image-rendering
kerning
letter-spacing
lighting-color
marker
marker-end
marker-mid
marker-start
mask
mix-blend-mode
opacity
overflow
pointer-events
shape-rendering
stop-color
stop-opacity
stroke
stroke-dasharray
stroke-dashoffset
stroke-linecap
stroke-linejoin
stroke-miterlimit
stroke-opacity
stroke-width
text-anchor
text-decoration
text-rendering
unicode-bidi
visibility
word-spacing
writing-mode
filter primitive
attributes
‘x’
‘y’
‘width’
‘height’
‘result’
‘class’
‘style’
‘in’
‘in2’
‘scale’
‘xChannelSelector’
‘yChannelSelector’
DOM Interfaces:
SVGFEDisplacementMapElement
This filter primitive uses the pixels values from the image from
in2
to spatially displace the image from
in
. This is the transformation to be
performed:
P'(x,y) ← P( x + scale * (XC(x,y) - .5), y + scale * (YC(x,y) - .5))
where P(x,y) is the input image,
in
, and P'(x,y) is the destination.
XC(x,y) and YC(x,y) are the component values of the channel designated
by the
xChannelSelector
and
yChannelSelector
. For example, to use the
R component of
in2
to control displacement in x and the G
component of Image2 to control displacement in y, set
xChannelSelector
to
"R"
and
yChannelSelector
to
"G"
The displacement map,
in2
, defines the inverse of the mapping
performed.
The input image in is to remain premultiplied for this filter
primitive. The calculations using the pixel values from
in2
are performed using non-premultiplied
color values. If the image from
in2
consists of premultiplied color values,
those values are automatically converted into non-premultiplied color
values before performing this operation.
This filter can have arbitrary non-localized effect on the input
which might require substantial buffering in the processing pipeline.
However with this formulation, any intermediate buffering needs can be
determined by
scale
which represents the maximum range
of displacement in either x or y.
When applying this filter, the source pixel location will often lie
between several source pixels. In this case it is recommended that
high quality viewers apply an interpolent on the surrounding pixels,
for example bilinear or bicubic, rather than simply selecting the
nearest source pixel. Depending on the speed of the available
interpolents, this choice may be affected by the
image-rendering
property setting.
The
color-interpolation-filters
property only
applies to the
in2
source image and does not apply to the
in
source image. The
in
source image must remain in its
current color space.
Attribute definitions:
scale
= "
Displacement scale factor. The amount is expressed in the
coordinate system established by attribute
primitiveUnits
on the
element.
When the value of this attribute is
this operation has no effect on the source image.
The
lacuna
value
for
scale
is
Animatable: yes.
xChannelSelector
= "
R | G | B | A
Indicates which channel from
in2
to use to displace the pixels in
in
along the x-axis. The
lacuna
value
for
xChannelSelector
is
Animatable: yes.
yChannelSelector
= "
R | G | B | A
Indicates which channel from
in2
to use to displace the pixels in
in
along the y-axis. The
lacuna
value
for
yChannelSelector
is
Animatable: yes.
in2
(see
in
attribute)
The second input image, which is used to displace the pixels in
the image from attribute
in
. This attribute can take on the same
values as the
in
attribute.
Animatable: yes.
Name:
feDropShadow
Categories:
Filter primitive
element
Content model:
Any number of the following elements, in any order:
Attributes:
core
attributes
‘id’
‘xml:base’
‘xml:lang’
‘xml:space’
presentation
attributes
alignment-baseline
baseline-shift
clip
clip-path
clip-rule
color
color-interpolation
color-interpolation-filters
color-profile
color-rendering
cursor
direction
display
dominant-baseline
enable-background
fill
fill-opacity
fill-rule
filter
flood-color
flood-opacity
font
font-family
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-weight
glyph-orientation-horizontal
glyph-orientation-vertical
image-rendering
kerning
letter-spacing
lighting-color
marker
marker-end
marker-mid
marker-start
mask
mix-blend-mode
opacity
overflow
pointer-events
shape-rendering
stop-color
stop-opacity
stroke
stroke-dasharray
stroke-dashoffset
stroke-linecap
stroke-linejoin
stroke-miterlimit
stroke-opacity
stroke-width
text-anchor
text-decoration
text-rendering
unicode-bidi
visibility
word-spacing
writing-mode
filter primitive
attributes
‘x’
‘y’
‘width’
‘height’
‘result’
‘class’
‘style’
‘in’
‘stdDeviation’
‘dx’
‘dy’
DOM Interfaces:
SVGFEDropShadowElement
This filter creates a drop shadow of the input image. It is a
shorthand filter, and is defined in terms of combinations of other
filter primitives
. The
expectation is that it can be optimized more easily by
implementations.
The result of a
filter primitive is
equivalent to the following:
The above divided into steps:
Take the alpha channel of the input to the
filter primitive and
the
stdDeviation
on the
and do processing as
if the following
was applied:
Offset the result of step 1 by
dx
and
dy
as specified on the
element, equivalent
to applying an
with these parameters:
Do processing as if an
element with
flood-color
and
flood-opacity
as specified on the
was applied:
Composite the result of the
in step 3 with the result
of the
in step 2 as if an
filter primitive with
operator
=‘
in
’ was applied:
Finally merge the result of the previous step, doing processing as
if the following
was performed:
Note that while the definition of the
filter primitive says
that it can be expanded into an equivalent tree it is not required
that it is implemented like that. The expectation is that user agents
can optimize the handling by not having to do all the steps
separately.
Beyond the DOM interface
SVGFEDropShadowElement
there is no way of accessing the internals of the
filter primitive,
meaning
if
the filter primitive is implemented as an equivalent tree then that
tree must not be exposed to the DOM.
8.13.
Filter primitive
Name:
feFlood
Categories:
Filter primitive
element
Content model:
Any number of the following elements, in any order:
Attributes:
core
attributes
‘id’
‘xml:base’
‘xml:lang’
‘xml:space’
presentation
attributes
alignment-baseline
baseline-shift
clip
clip-path
clip-rule
color
color-interpolation
color-interpolation-filters
color-profile
color-rendering
cursor
direction
display
dominant-baseline
enable-background
fill
fill-opacity
fill-rule
filter
flood-color
flood-opacity
font
font-family
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-weight
glyph-orientation-horizontal
glyph-orientation-vertical
image-rendering
kerning
letter-spacing
lighting-color
marker
marker-end
marker-mid
marker-start
mask
mix-blend-mode
opacity
overflow
pointer-events
shape-rendering
stop-color
stop-opacity
stroke
stroke-dasharray
stroke-dashoffset
stroke-linecap
stroke-linejoin
stroke-miterlimit
stroke-opacity
stroke-width
text-anchor
text-decoration
text-rendering
unicode-bidi
visibility
word-spacing
writing-mode
filter primitive
attributes
‘x’
‘y’
‘width’
‘height’
‘result’
‘class’
‘style’
DOM Interfaces:
SVGFEFloodElement
This filter primitive creates a rectangle filled with the color and
opacity values from properties ‘
flood-color
’ and ‘
flood-opacity
’. The rectangle is as large
as the
filter primitive
subregion
established by the
element.
8.13.1.
The ‘
flood-color
property
The ‘
flood-color
’ property indicates what color
to use to flood the current
filter
primitive subregion
. The keyword ‘
currentColor
’ and ICC colors can be specified in
the same manner as within a
fill
’ and ‘
stroke
’ properties.
Name:
flood-color
Value:
currentColor |
Initial:
black
Applies to:
and
elements
Inherited:
no
Percentages:
N/A
Media:
visual
Computed value:
as specified
Animatable:
yes
The ‘
flood-opacity
’ property defines the
opacity value to use across the entire
filter primitive subregion
Name:
flood-opacity
Value:
Initial:
Applies to:
and
elements
Inherited:
no
Percentages:
N/A
Media:
visual
Computed value:
as specified
Animatable:
yes
Name:
feGaussianBlur
Categories:
Filter primitive
element
Content model:
Any number of the following elements, in any order:
Attributes:
core
attributes
‘id’
‘xml:base’
‘xml:lang’
‘xml:space’
presentation
attributes
alignment-baseline
baseline-shift
clip
clip-path
clip-rule
color
color-interpolation
color-interpolation-filters
color-profile
color-rendering
cursor
direction
display
dominant-baseline
enable-background
fill
fill-opacity
fill-rule
filter
flood-color
flood-opacity
font
font-family
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-weight
glyph-orientation-horizontal
glyph-orientation-vertical
image-rendering
kerning
letter-spacing
lighting-color
marker
marker-end
marker-mid
marker-start
mask
mix-blend-mode
opacity
overflow
pointer-events
shape-rendering
stop-color
stop-opacity
stroke
stroke-dasharray
stroke-dashoffset
stroke-linecap
stroke-linejoin
stroke-miterlimit
stroke-opacity
stroke-width
text-anchor
text-decoration
text-rendering
unicode-bidi
visibility
word-spacing
writing-mode
filter primitive
attributes
‘x’
‘y’
‘width’
‘height’
‘result’
‘class’
‘style’
‘in’
‘stdDeviation’
DOM Interfaces:
SVGFEGaussianBlurElement
This filter primitive performs a Gaussian blur on the input image.
The Gaussian blur kernel is an approximation of the normalized
convolution:
G(x,y) = H(x)I(y)
where
H(x) = exp(-x
/ (2s
)) /
sqrt(2* pi*s
and
I(x) = exp(-y
/ (2t
)) /
sqrt(2* pi*t
with ‘
’ being the standard
deviation in the x direction and ‘
being the standard deviation in the y direction, as specified by
stdDeviation
The value of
stdDeviation
can be either one or two
numbers. If two numbers are provided, the first number represents a
standard deviation value along the x-axis of the current coordinate
system and the second value represents a standard deviation in Y. If
one number is provided, then that value is used for both X and Y.
Even if only one value is provided for
stdDeviation
, this can be implemented as
a separable convolution.
For larger values of ‘
’ (s >=
2.0), an approximation can be used: Three successive box-blurs build a
piece-wise quadratic convolution kernel, which approximates the
Gaussian kernel to within roughly 3%.
let d = floor(s * 3*sqrt(2*pi)/4 + 0.5)
... if d is odd, use three box-blurs of size ‘
’, centered on the output pixel.
... if d is even, two box-blurs of size ‘
’ (the first one centered on the pixel
boundary between the output pixel and the one to the left, the second
one centered on the pixel boundary between the output pixel and the
one to the right) and one box blur of size ‘
d+1
’ centered on the output pixel.
The approximation formula also applies correspondingly to ‘
’.
Frequently this operation will take place on alpha-only images,
such as that produced by the built-in input,
SourceAlpha
. The
implementation may notice this and optimize the single channel case.
If the input has infinite extent and is constant (e.g
FillPaint
where the
fill is a solid color), this operation has no effect. If the input has
infinite extent and the filter resultwhere the fill is a solid color)
is the input to an
, the filter is evaluated
with periodic boundary conditions.
By default,
the subregion interacts as input and output clipping and this sentence
would be irrelevant. However, this changes if the WG decides to allow
a choice between input and output clipping.
What about
other inputs with infinite extents? What is the ‘
periodic boundary condition
’?
Attribute definitions:
stdDeviation
= "
The standard deviation for the blur operation. If two
s are provided, the first number represents a standard deviation
value along the x-axis of the coordinate system established by
attribute
primitiveUnits
on the
element. The second value
represents a standard deviation in Y. If one number is provided,
then that value is used for both X and Y.
A value of zero disables the effect of the given filter primitive
(i.e., the result is the filter input image).
If
stdDeviation
is
in only one of X or Y, then the effect is
that the blur is only applied in the direction that has a non-zero
value.
The
lacuna
value
for
stdDeviation
is
Animatable: yes.
The example
at the start of this chapter
makes use of the
filter primitive to
create a drop shadow effect.
8.15.
Filter primitive
Name:
feImage
Categories:
Filter primitive
element
Content model:
Any number of the following elements, in any order:
Attributes:
core
attributes
‘id’
‘xml:base’
‘xml:lang’
‘xml:space’
presentation
attributes
alignment-baseline
baseline-shift
clip
clip-path
clip-rule
color
color-interpolation
color-interpolation-filters
color-profile
color-rendering
cursor
direction
display
dominant-baseline
enable-background
fill
fill-opacity
fill-rule
filter
flood-color
flood-opacity
font
font-family
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-weight
glyph-orientation-horizontal
glyph-orientation-vertical
image-rendering
kerning
letter-spacing
lighting-color
marker
marker-end
marker-mid
marker-start
mask
mix-blend-mode
opacity
overflow
pointer-events
shape-rendering
stop-color
stop-opacity
stroke
stroke-dasharray
stroke-dashoffset
stroke-linecap
stroke-linejoin
stroke-miterlimit
stroke-opacity
stroke-width
text-anchor
text-decoration
text-rendering
unicode-bidi
visibility
word-spacing
writing-mode
filter primitive
attributes
‘x’
‘y’
‘width’
‘height’
‘result’
xlink
attributes
‘xlink:type’
‘xlink:role’
‘xlink:arcrole’
‘xlink:title’
‘class’
‘style’
‘externalResourcesRequired’
‘preserveAspectRatio’
‘xlink:href’
DOM Interfaces:
SVGFEImageElement
This filter primitive refers to a graphic external to this filter
element, which is loaded or rendered into an RGBA raster and becomes
the result of the filter primitive.
This filter primitive can refer to an external image or can be a
reference to another piece of SVG. It produces an image similar to the
built-in image source
SourceGraphic
except that the graphic
comes from an external source.
If the
xlink:href
references a
stand-alone image resource such as a JPEG, PNG or SVG file, then the
image resource is rendered according to the behavior of the
element; otherwise, the
referenced resource is rendered according to the behavior of the
Example of feTurbulence
View this
example as SVG (SVG-enabled browsers only)
The description of the ‘
color-interpolation-filters
’ property is
as follows:
Name:
color-interpolation-filters
Value:
auto | sRGB | linearRGB
Initial:
linearRGB
Applies to:
filter primitives
Inherited:
yes
Percentages:
N/A
Media:
visual
Computed value:
as specified
Animatable
yes
auto
Indicates that the user agent can choose either the ‘
sRGB
’ or ‘
linearRGB
spaces for filter effects color operations. This option indicates
that the author doesn't require that color operations occur in a
particular color space.
sRGB
Indicates that filter effects color operations should occur in the
sRGB color space.
linearRGB
Indicates that filter effects color operations should occur in the
linearized RGB color space.
The ‘
color-interpolation-filters
’ property
specifies the color space for imaging operations performed via filter
effects.
Note that ‘
color-interpolation-filters
’ has a
different initial value than ‘
color-interpolation
’. ‘
color-interpolation-filters
’ has an
initial value of ‘
linearRGB
’, where as
color-interpolation
’ has an initial
value of ‘
sRGB
’. Thus, in the default case,
filter effects operations occur in the linearRGB color space, whereas
all other color interpolations occur by default in the sRGB color
space.
Note that the ‘
color-interpolation-filters
’ propert has
no effect on
Filter Functions
, which operate in the sRGB
color space.
10.
Light source
elements and properties
10.1.
Introduction
The following sections define the elements that define a
light source
and
, and property ‘
lighting-color
’, which defines the color
of the light.
Attribute definitions:
azimuth
= "
Direction angle for the light source on the XY plane (clockwise),
in degrees from the x axis.
The
lacuna
value
for
azimuth
is
Animatable: yes.
elevation
= "
Direction angle for the light source from the XY plane towards
the Z-axis, in degrees. Note that the positive Z-axis points towards
the viewer.
The
lacuna
value
for
elevation
is
Animatable: yes.
The following diagram illustrates the angles which
azimuth
and
elevation
represent in an XYZ coordinate
system.
Angles which azimuth and elevation represent
Use other color then red and green
Attribute definitions:
= "
X location for the light source in the coordinate system
established by attribute
primitiveUnits
on the
element.
The
lacuna
value
for
is
Animatable: yes.
= "
Y location for the light source in the coordinate system
established by attribute
primitiveUnits
on the
element.
The
lacuna
value
for
is
Animatable: yes.
= "
Z location for the light source in the coordinate system
established by attribute
primitiveUnits
on the
element, assuming that, in
the
initial
coordinate system
, the positive Z-axis comes out towards the
person viewing the content and assuming that one unit along the
Z-axis equals
one
unit in X and Y
The
lacuna
value
for
is
Animatable: yes.
pointsAtX
= "
X location in the coordinate system established by attribute
primitiveUnits
on the
element of the point at
which the light source is pointing.
The
lacuna
value
for
pointsAtX
is
Animatable: yes.
pointsAtY
= "
Y location in the coordinate system established by attribute
primitiveUnits
on the
element of the point at
which the light source is pointing.
The
lacuna
value
for
pointsAtY
is
Animatable: yes.
pointsAtZ
= "
Z location in the coordinate system established by the attribute
primitiveUnits
on the
element of the point at
which the light source is pointing, assuming that, in the
initial
coordinate system
, the positive Z-axis comes out towards the
person viewing the content and assuming that one unit along the
Z-axis equals
one unit in X and Y
The
lacuna
value
for
pointsAtZ
is
Animatable: yes.
specularExponent
= "
Exponent value controlling the focus for the light source.
The
lacuna
value
for
specularExponent
is
Animatable: yes.
limitingConeAngle
= "
A limiting cone which restricts the region where the light is
projected. No light is projected outside the cone.
limitingConeAngle
represents the angle in
degrees between the spot light axis (i.e. the axis between the light
source and the point to which it is pointing at) and the spot light
cone.
User agents should apply
a smoothing technique such as anti-aliasing at the boundary of the
cone.
If no value is specified, then no limiting cone will be applied.
Animatable: yes.
The ‘
lighting-color
’ property defines the color
of the light source for
filter
primitives
and
11.
Custom Filter
Function
The custom-filter function allows extending this specification with
a customized filter effect. Customized filter effects are described by
the @filter rule or
feCustom element
element
and referenced internal or external resources. External resource must
be described by a host language. Each @filter rule has a unique
identifier that can be referenced by the custom-filter function.
11.1.
The
@supports
’ condition: ‘
filter
Value:
To verify if a UA supports a certain customized filter effect type,
the support condition syntax
[CSS3-CONDITIONAL]
gets extended by adding the media feature ‘
filter
’.
= webgl
This specification supports the custom filter type ‘
webgl
’ to indicate support for the
shading language
based on WebGL. Future
versions may allow additional keywords.
@support filter(webgl) {
...
11.2.
The @filter
rule
The @filter rule allows specifying custom-filter definitions (like
shaders
) for the use of the ‘
filter
’ property. A
@filter rule consists of the keyword "@filter", followed by an
identifier giving a name for the custom-filter (which will be
referenced using the ‘
custom()
’ filter
function), followed by a set of custom-filter descriptors.
The general form of an @filter at-rule is:
@filter IDENT {
where
descriptor: value;
descriptor: value;
[...]
descriptor: value;
Each @filter rule specifies a value for every custom-filter
descriptor, either implicitly or explicitly. Those not given explicit
values in the rule take the initial value listed with each descriptor
in this specification. When a given descriptor occurs multiple times
in a given @filter rule, only the last specified value is used, all
prior values for that descriptor are ignored.
The following is the grammar for the custom-filter at-rule and
extends the lexical scanner in the
Grammar of CSS 2.1
[CSS21]
Appendix G):
filter_rule
: FILTER_SYM S+ IDENT S* '{' S*
group_rule_body
'}' S*;
@{F}{I}{L}{T}{E}{R} {return FILTER_SYM;}
group_rule_body
as defined in
[CSS3-CONDITIONAL]
Furthermore, the
nested_statement
rule
[CSS3-CONDITIONAL]
gets extended by adding "
filter_rule
".
11.3.
Custom filter
resources: the
src
descriptor
Name:
src
Value:
[
Initial:
N/A
The ‘
src
descriptor takes a comma separated list of resource references with an
optional format function. The resource format is either determined by
a provided custom filter format string with the format function, or by
the MIME type of the resource (e.g. transfered MIME type from the
resource providing server). If a format function is provided, then the
passed string overrides the MIME type definition of the resource. The
type of a customized filter effect depends on the format of the
resources.
It is possible to reference custom filter resources in a document
by a fragment identifier. The format may be identified by the context
of the referenced resource. If the referenced resource is a ‘
Format strings defined by this specification:
String
Custom-filter Format
Common extensions
"x-shader/x-vertex"
WebGL 1.0 vertex shader
.vs
"x-shader/x-fragment"
WebGL 1.0 fragment shader
.fs
11.4.
Custom
filter parameters: the
parameters
descriptor
Name:
parameters
Value:
#
Initial:
N/A
The list of parameters define variables, that get passed into the
custom filter effect (e.g. parameters passed to a shader). Each
parameter has an identifier. If a parameter with the same identifier
occurs more then once in the list of parameters, the latest parameter
definition overrides all previous definitions. A parameter definition
can be overloaded by a parameter definition in the referencing custom
filter function.
= IDENT
+ |
array(
mat2(
mat3(
mat4(
array(
Specifies an array of number values.
A CSS color value. (See
[CSS3COLOR]
.)
A CSS transform function value. (See
[CSS3-TRANSFORMS]
.)
A URL reference to an image source.
The following function definitions describe matrices in
column-major order.
mat2(
Specifies a 2x2 homogeneous matrix of 4 values.
mat3(
Specifies a 3x3 homogeneous matrix of 9 values.
mat4(
Specifies a 4x4 homogeneous matrix of 16 values.
11.5.
Custom
filter geometry: the
geometry
descriptor
grid(
grid(
[ detached | attached ]?)
One or two positive integers greater then zero indicate the
additional number of vertex lines and columns that will make the
vertex mesh. With the initial value of ‘
’ there is a single row and a single column, resulting in
a four-vertices mesh (top-left, top-right, bottom-right,
bottom-left). If the second parameter is not provided, it takes a
value equal to the first. A value of ‘
’ results in a vertex mesh that has n columns and m rows.
This results in a total of (n + 1) * (m + 1) vertices. If one of
the passed parameters is zero or negative, the UA must use the
initial mesh.
The figure illustrates how a mesh of ‘
6 6
’ creates vertices passed to the vertex
shader.
detached
The geometry provided to the vertex shader is made of triangles
which do not share adjacent edges' vertices. A value of ‘
detached
’ implies
that the vertices are detached.
attached
The geometry provided to the vertex shader is made of triangles
which do not share adjacent edges' vertices. A value of ‘
attached
’ implies
that the vertices are attached.
If no value for attachmeny of verices is specified, it computes
to ‘
attached
’.
11.6.
Custom filter
compositing: the
mix
descriptor
Name:
mix
Value:
auto | [
Initial:
auto
auto
The UA must follow the host language's recommendation.
Specifies blending mechanisms for the filter primitive. The host
language must define the meaning.
Specifies composition mechanisms for the filter primitive. The
host language must define the meaning.
11.7.
Custom
filter margins: the
margin
descriptor
Name:
margin
Value:
Initial:
auto
Computed Value:
the percentage as specified or the absolute length. A value of
auto computes to 10% of the input
Filter primitive subregion
The ‘
margin
descriptor values and the input
Filter primitive subregion
define
the filter primitive subregion of the custom filter primitive.
auto
For the definition of the
values see CSS Box
Model
[CSS21]
12.
Custom Shaders
12.1.
Introduction
With Custom Shaders, authors can manipulate the color and shape of a
graphical element in granular ways. The following sections describe
the host language Custom Shaders as extension for
Custom Filter Functions
12.2.
Precedents
There are many precedents for shading languages, for example:
12.3.
Recommended
shading language
This document recommends the adoption of the subset of GLSL ES [
GLSLES
] defined in the WebGL 1.0
WEBGL
] specification.
In particular, the same restrictions as defined in WebGL should
apply to shaders for CSS:
All the parameters specified in the
values (e.g., the
custom-filter at-rule
or the ‘
custom()
’ filter function) will be available as
uniforms to the shader(s) referenced by the ‘
shader
’ property.
The group may consider applying further restrictions to the GLSL ES
language to make it easier to write vertex and fragment shaders.
The OpenGL ES shading language provides a number of variables that
can be passed to shaders, exchanged between shaders or set by shaders.
In particular, a vertex shader can provide specific data to the
fragment shader in the form of "varying" parameters (parameters that
vary per pixel). The following sections describe particular variables
that are assumed for the vertex and fragment shaders.
12.4.
Integration into Custom Filter Functions
Custom Filter Function values have the following meaning for Custom
Shaders:
Values for ‘
mix
’ descriptor
For fragment shaders, each pixel is blended with the
mix-color
by using one of the predefined blend modes and
it's appropriate blend mode keyword (See
[COMPOSITING]
).
For fragment shaders, each pixel is composed with the
mix-color
by using one of the predefined
alpha-compositing operators and it's appropriate alpha-compositing
keyword (See
[COMPOSITING]
).
auto
If the ‘
mix
descriptor value computes to ‘
auto
’, the
effect is as if ‘
normal source-atop
’ was
specified.
12.5.
Shader
Processing Model
This section illustrates the shader processing model as it applies
to an element whose unfiltered rendering is shown in the figure
below
Element before applying shaders
Prior to the shader processing, the input of the filter primitive
gets rendered into an off-screen image (the source texture). The
off-screen size and position is controlled by the
filter primitive subregion
Source texture created by rendering
the element off-screen and adding filter primitive margins
An
element or a ‘
custom()
’ filter function defines a custom filter
primitive. The following figure illustrates its model.
The shader processing model
In a
first step
the source texture is used on a
vertex mesh
. By default, the vertex mesh has
the position and size of the
filter primitive subregion
. In
the following figure, the red markers represent the default vertices
in the default vertex mesh. The diagonal line illustrate how the
vertices define two triangles.
The default vertex mesh and its default vertices
The
geometry
attribute on the
element and the ‘
geometry
descriptor on the
custom-filter at-rule
give more granularity control over the vertex mesh.
A finer, custom vertex mesh
In a
second step
, the
vertex mesh
gets processed through the vertex
shader, which produces a set of transformed vertices. These
transformed vertices are the output as shown in the figure below.
Transformed vertices after applying the vertex shader
The
third step
is the rasterization step. The
filter primitive invokes the fragment shader for every pixel location
inside the vertex mesh to perform per pixel operation and produce the
final pixel color at that vertex mesh location.
Transformed vertices after applying the vertex shader
Note that the fragment shader may be called several
times for what corresponds to the same pixel coordinate on the output,
for example when the vertex mesh folds over itself. Overlaying pixel
values do neither composite nor blend. The pixel value with the least
depth will be choosen.
The ‘
mix
descriptor provides basic functionalities for color manipulation like
blending and alpha compositing on a fragment shader. The processing
model of ‘
mix
’ is
illustrated in the following figure:
fragmentShader: processing model for mix
Each color value passed to the fragment shader gets multiplied with
the
color matrix
, a predefined fragment
shader variable that represents a 4x4 matrix. The matrix is
initialized to an identity matrix, but can be set by a fragment
shader. The resulting color is the
multiplied color
The
mix color
is a second, predefined
fragment shader variable and represents an ‘
RGBA
value. The
mix color
can be set by the fragment
shader. If not specified, the default value is transparent black. The
RGB
’ channels of the
multiplied color
get blended with
the ‘
RGB
’ channels of the
mix color
with the
multiplied color
as destination
and the
mix color
as source
[COMPOSITING]
. The applied
blend mode depends on the passed
normal
’ by default. The result of the
blending and the opacity of the
mix
color
define the
blended color
The
multiplied color
and the
mix color
get composed using the
alpha-compositing rules as described in the Compositing and Blending
spec
[COMPOSITING]
. The applied
alpha-compositing mode is specified by the passed
source-atop
’ by default.
The last step,
step 4
, shows rasterized output. If
the custom filter primitive is the last primitive in the filter chain,
then this output is the filtered rendering of the element. Otherwise,
the output of the primitive becomes the input to the next filter
primitive using it.
12.6.
Differences
to GLSL
12.6.1.
Fragment Shaders Differences with GLSL
A normal GLSL shader requires that the fragment shader computes a
gl_FragColor
value which is the color value for the
processed fragment (pixel).
Because of the
security restrictions
fragment shaders are not allowed to access rendered content pixel
values directly. However, fragment shaders in this specification have
the option to compute a value that is automatically mixed with the
rendered content pixel values (but without ever providing direct
access to these values to the shader code).
In the context of this specification, fragment shaders have the
options to compute the following values:
gl_FragColor
. If the compositing and blending values
for the ‘
mix
descriptor compute to ‘
none
’ the shader
computes a
gl_FragColor
value. This may be useful, for
example, to compute complex patterns.
css_MixColor
. If the compositing and blending values
for the ‘
mix
descriptor do not compute to ‘
none
’, then
the shader computes a
mix color
value that is composited with the rendered content as explained in
the
shaders processing model
css_ColorMatrix
. If the compositing and blending
values for the ‘
mix
’ descriptor do not compute to
none
’, then the shader computes a
color matrix
value that is
multiplied with the rendered content as explained in the
shaders processing model
The following example shows a fragment shader which computes a
simple solid red color:
CSS
@filter red {
src: url('simple.vs') format('x-shader/x-vertex'), url(simple.fs) format('x-shader/x-fragment');
#filtered-element {
filter: custom(red);
simple.vs
attribute vec4 a_position;
void main()
gl_Position = a_position;
simple.fs
void main()
gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
The following example shows a fragment shader which darkens the
rendered content by computing a
css_MixColor
which is
multiplied with the rendered content:
CSS
@filter darken {
src: url('simple2.vs') format('x-shader/x-vertex'), url(simple2.fs) format('x-shader/x-fragment');
mix: multiply;
#filtered-element {
filter: custom(mix);
simple2.vs
attribute vec4 a_position;
void main()
gl_Position = a_position;
simple2.fs
void main()
css_MixColor
= vec4(0.8, 0.8, 0.8, 1.0);
The following example shows a fragment shader which darkens the
rendered content by computing a
css_ColorMatrix
which
varies depending on the texture coordinate:
CSS
@filter colormatrix {
src: url('simple.vs') format('x-shader/x-vertex'), url(simple3.fs) format('x-shader/x-fragment');
#filtered-element {
filter: custom(colormatrix);
simple3.vs
attribute vec4 a_position;
varying vec2 v_texCoord;
void main()
v_texCoord = a_position.xy;
gl_Position = a_position;
simple3.fs
varying vec2 v_texCoord;
void main()
float x = v_texCoord.x;
css_ColorMatrix = mat4(
vec4(x, x, x, x), // 1st column
vec4(x, x, x, x), // 2nd column
vec4(x, x, x, x), // 3rd column
vec4(x, x, x, x), // 4th column
);
12.6.2.
Vertex attribute variables
The following attribute variables are available to the vertex
shader.
attribute variables
description
attribute vec4 a_position
The vertex coordinates in the
Filter primitive subregion
Coordinates are normalized to the [0, 1] range along the x, y and z
axis.
attribute vec3 a_triangleCoord
The x and y values provide the coordinate of the current
tile
’ in the shader mesh. For
example, (0, 0) for the top right tile in the mesh. The x and y
values are in the [0, mesh columns] and [0, mesh rows] range,
respectively.
The z coordinate is computed according to the following figure.
The z coordinate value is provided for each vertex and
corresponding triangle. For example, for the bottom right vertex
of the top triangle, the z coordinate will be 2. For the bottom
right vertex of the bottom triangle, the z coordinate will be 4.
The a_triangleCoord.z value
12.6.3.
Shader
uniform variables
The following uniform variables are set to specific values by the
user agent:
uniform variable
description
uniform vec2 u_textureSize
The input texture's size. Includes the filter margins. The
texture size is given in the actual device pixels and incorporates
the device pixel ratio.
uniform vec2 u_meshSize
The size of the current mesh in terms of tiles. The x coordinate
provides the number of columns and the y coordinate provides the
number of rows.
12.6.4.
Other uniform variables: the CSS shaders
parameters
When there parameters are passed to the custom filter function or
the
filter primitive, the user
agent pass uniforms of the corresponding name and type to the shaders.
The following table shows the mapping between CSS shader parameters
and uniform types.
CSS param type
GLSL uniform type
vec4
float, vec2, vec3 or vec4
float[n]
mat4
mat2(
mat3(
mat4(
mat2, mat3 or mat4
sampler2D
The following code sample illustrates that mechanism.
CSS
@filter distort {
src: url(distort.vs), url(tint.fs);
parameters: distortAmount 0.5, lightVector 1.0 1.0 0.0, disp texture(disp.png);
.shaded {
filter: custom(distort);
Shader (vertex or fragment)
...
uniform float distortAmount;
uniform vec3 lightVector;
uniform sampler2D disp;
uniform vec2 dispSize;
...
As illustrated in the example, for each
texture()
parameter, an additional
vec2
uniform is
passed to the shaders with the size of the corresponding texture.
12.6.5.
Default shaders
If no vertex shader is provided, the default one is as shown below.
attribute vec4 a_position;
void main()
gl_Position = a_position;
If no fragment shader is provided, the default one is shown below.
12.6.6.
Texture access
If shaders access texture values outside the
[0, 1]
range on both axis, the returned value is a fully translucent black
pixel.
13.
The filter CSS
value
The filter() function produces a CSS
value.
It has the following syntax:
13.1.
filter() syntax
= filter(
none |
The function takes two parameters. The first is a CSS
value. The second is the value of a ‘
filter
’ property. The
function take the input image parameter and apply the filter rules,
returning a processing image.
The filter functions may increase the dimension of the
image in comparison to the original image. Does it influence the
offset when passed to a CSS property?
14.
Shorthands
defined in terms of the
element
Below are the equivalents for each of the filter functions
expressed in terms of the ‘
filter element
element. The parameters from the function are labelled with brackets
in the following style: [amount]. In the case of parameters that are
percentage values, they are converted to real numbers.
14.1.
grayscale
(0.2126 - 0.2126 * [1 - amount]) (0.7152 + 0.2848 * [1 - amount]) (0.0722 - 0.0722 * [1 - amount]) 0 0
(0.2126 - 0.2126 * [1 - amount]) (0.7152 - 0.7152 * [1 - amount]) (0.0722 + 0.9278 * [1 - amount]) 0 0
0 0 0 1 0"/>
14.2.
sepia
(0.349 - 0.349 * [1 - amount]) (0.686 + 0.314 * [1 - amount]) (0.168 - 0.168 * [1 - amount]) 0 0
(0.272 - 0.272 * [1 - amount]) (0.534 - 0.534 * [1 - amount]) (0.131 + 0.869 * [1 - amount]) 0 0
0 0 0 1 0"/>
14.3.
saturate
14.4.
hue-rotate
14.5.
invert
14.6.
opacity
14.7.
brightness
14.8.
contrast
14.9.
blur
14.10.
drop-shadow
14.11.
custom
...
...
Name:
enable-background
Value:
accumulate | new
Initial:
accumulate
Applies to:
Typically elements that can contain renderable elements.
language is responsible for defining the applicable set of
elements. For SVG:
container
elements
Inherited:
no
Percentages:
N/A
Media:
visual
Computed value:
as specified
Animatable:
no
The property which enables access to the background image is ‘
enable-background
’:
new
Indicates that a new (i.e., initially transparent black)
background image canvas is established and that (in effect) all
children of the current
container
element
element shall be rendered into the new background image
canvas in addition to being rendered onto the target device.
accumulate
(the initial/default value)
If an ancestor
container
element
element has a property value of ‘
enable-background: new
’, then all renderable child
elements of the current
container
element
element are rendered both onto the parent
container
element
element's background image canvas and onto the target
device.
Otherwise, there is no current background image canvas, so it is
only necessary to render
graphics
elements
the renderable elements onto the target device. (No need
to render to the background image canvas.)
The ‘
enable-background
’ property has no affect
if the ‘
isolation
’ property has a
value of ‘
isolate
[COMPOSITING]
. The
isolation group defined by the ‘
isolation
’ property will establish a new
background image canvas.
Two possible pseudo input images for
filter effects are
BackgroundImage
and
BackgroundAlpha
, which each represent
an image snapshot of the canvas under the
filter region
at the time that the
element is invoked.
BackgroundImage
represents both the color values and alpha channel of the canvas
(i.e., RGBA pixel values), whereas
BackgroundAlpha
represents only the alpha
channel.
Implementations will often need to
maintain supplemental background image buffers in order to support the
BackgroundImage
and
BackgroundAlpha
pseudo input images.
Sometimes, the background image buffers will contain an in-memory copy
of the accumulated painting operations on the current canvas.
Because in-memory image buffers can take up significant system
resources, content must explicitly indicate to the
user agent that the document needs access to the background
image before
BackgroundImage
and
BackgroundAlpha
pseudo input images can be
used.
A background image is what's been
rendered before
the current
element. The host language is responsible for defining what
rendered
before
in this context means. For SVG, that uses the painter's
algorithm,
rendered before
means all of the prior elements in
pre order traversal previous to the element to which the filter is
applied.
If a filter effect specifies either the
BackgroundImage
or the
BackgroundAlpha
pseudo input images and no
ancestor
container
element
element has a property value of ‘
enable-background: new
’, then the background image
request is technically in error. Processing will proceed without
interruption (i.e., no error message) and a transparent black image
shall be provided in response to the request.
15.1.
Accessing the background image in SVG
This section only applies to the SVG definition of
enable-background.
Assume you have an element E in the document and that E has a
series of ancestors A
(its immediate parent),
, etc. (Note: A
is E.) Each ancestor
will have a corresponding temporary background image
offscreen buffer BUF
. The contents of the
background
image
available to a
referenced by E is defined
as follows:
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
This filter discards the SourceGraphic, if any, and just produces
a result consisting of the BackgroundImage shifted down 125 units
and then blurred.
This filter takes the BackgroundImage, shifts it down 125 units, blurs it,
and then renders the SourceGraphic on top of the shifted/blurred background.
View
this example as SVG (SVG-enabled browsers only)
The example above contains five parts, described as follows:
The first set is the reference graphic. The reference graphic
consists of a red rectangle followed by a 50% transparent
element. Inside the
is a green circle that
partially overlaps the rectangle and a a blue triangle that
partially overlaps the circle. The three objects are then outlined
by a rectangle stroked with a thin blue line. No filters are applied
to the reference graphic.
The second set enables background image processing and adds an
empty
element which invokes the
ShiftBGAndBlur filter. This filter takes the current accumulated
background image (i.e., the entire reference graphic) as input,
shifts its offscreen down, blurs it, and then writes the result to
the canvas. Note that the offscreen for the filter is initialized to
transparent black, which allows the already rendered rectangle,
circle and triangle to show through after the filter renders its own
result to the canvas.
The third set enables background image processing and instead
invokes the ShiftBGAndBlur filter on the inner
element. The accumulated
background at the time the filter is applied contains only the red
rectangle. Because the children of the inner
(i.e., the circle and triangle)
are not part of the inner
element's background and
because ShiftBGAndBlur ignores SourceGraphic, the children of the
inner
do not appear in the result.
The fourth set enables background image processing and invokes
the ShiftBGAndBlur on the
element that draws the
triangle. The accumulated background at the time the filter is
applied contains the red rectangle plus the green circle ignoring
the effect of the
opacity
property on the inner
element. (Note that the blurred
green circle at the bottom does not let the red rectangle show
through on its left side. This is due to ignoring the effect of the
opacity
property.) Because the
triangle itself is not part of the accumulated background and
because ShiftBGAndBlur ignores SourceGraphic, the triangle does not
appear in the result.
The fifth set is the same as the fourth except that filter
ShiftBGAndBlur_WithSourceGraphic is invoked instead of
ShiftBGAndBlur. ShiftBGAndBlur_WithSourceGraphic performs the same
effect as ShiftBGAndBlur, but then renders the SourceGraphic on top
of the shifted, blurred background image. In this case,
SourceGraphic is the blue triangle; thus, the result is the same as
in the fourth case except that the blue triangle now appears.
16.
Integration with CSS Animations and CSS
Transitions
The CSS ‘
filter
’ property is animatable.
Interpolation happens between the filter functions only if the ‘
filter
’ values have
the same number of filter functions, and the same functions appearing
in the same order.
The CSS WG may define different
fading transitions in the future.
16.1.
Interpolating filter function parameters
All properties defined as animatable, provided they are one of the
property types listed in CSS3 Transitions
[CSS3-TRANSITIONS]
can be animated.
16.2.
Interpolating the shader-params component in the custom()
function.
To interpolate between ‘
parameters
’ values in a
custom()
filter function or between
attribute values, the
user agent should interpolate between each of the parameter values
according to its type. List of values need to be of the same length.
Matrices need to be of the same dimension. Arrays need to be of the
same size.
Interpolation between shader params only happens if all
the other shader properties are identical: vertex shader, fragment
shader, filter margins and vertex mesh.
Interpolate between each of the values.
Interpolate between each of the values using a step function.
Interpolate between the array elements.
Follows the
CSS3
transform interpolation rules
Interpolate between the matrix components (applies to mat2, mat3
and mat4).
As with the ‘
transform
’ property, it is not possible to
animate the different components of the custom() filter parameters on
different timelines or with different keyframes. This is a generic
issue of animating properties that have multiple components to them.
17.
Security
The following description of the security model is not
sufficient and detailed enough. See
public-fx
mailing list.
17.1.
Rendered Content Access in custom filter
primitives
Since a
custom filter primitive
is
applying a processing operation on input values, it is important that
no protected information leaks from that operation.
study
of the security issues
has led to the requirement that vertex
shaders and fragment shaders do not get access to the rendered content
in order to prevent
timing attacks
If a custom filter primitive does not fulfill these requirements,
the primitive is a
pass through
17.2.
Origin
Restrictions
Input to a filter effect must not include anything as input that
would violate
same origin
restrictions
. If cross-origin access is required, then the
requested content should be explicitly marked with
CORS data
This restriction includes:
Any