W3C home > Mailing lists > Public > public-fx@w3.org > October to December 2012

[filter-effects] New syntax proposal for 'custom' filter function

From: Dirk Schulze <dschulze@adobe.com>
Date: Thu, 15 Nov 2012 14:04:57 -0800
To: "public-fx@w3.org" <public-fx@w3.org>
Message-ID: <556E2E25-0DF8-4EDD-9974-7BA6F662E196@adobe.com>
In the thread "[filters] Shading language recommendation"[1] people asked for support of possible future versions of the recommended shading language as well as optional support for other shading languages for the custom filter function. This may cause a slightly different syntax then the proposed syntax of the current working draft[2].

Our team at Adobe had the following goals when thinking about the syntax of the custom filter function:

1) Support future versions of recommended shading languages. Future versions may add or remove shader types (e.g. vertex, fragment, geometry, etc.).
2) Support multiple shading languages.
3) Avoid downloading shader files of unsupported shading languages.
4) Avoid repetition of values that stay constant during animations or transitions.
5) Be able to define shaders of different languages in different CSS files. Sometimes authors Base64 encode their shader sources and include them inline in CSS to avoid extra HTTP requests. In this case, they may want to serve different CSS files with different shaders depending on the client.

To address these goals we came up with a syntax as in the example below:

	@custom-filter "page-curl-other" {
		format: "other-shader-language";
		parameters: curlDirection 135, curlRadius 0.1, curlAmount 0.0;

		vertex: url(page-curl-other.vs);
		fragment: url(page-curl-other.fs);
		geometry: url(page-curl-other.gs);

	@custom-filter "page-curl-glsl" {
		format: "glsl";
		mix: normal source-in;
		parameters: curlDirection 135, curlRadius 0.1, curlAmount 0.0;
		mesh: 3 3 content-mask detached;

		vertex: url(page-curl-glsl.vs);
		fragment: url(page-curl-glsl.fs);

	filter: custom("page-curl-other" "page-curl-glsl", ctm scale(2));

We propose the new custom-filter at-rule, that includes all shader information. See syntax and behavior below.

Syntax of 'custom' function.

The formal syntax for the 'custom' function would be:

	custom([ none | IDENT ]+ [, <params>]*)

* IDENT is the name of a custom-filter at-rule. 
* <params> is a definition of a shader parameter as defined in the current working draft[3].

If a list of custom-filter at-rules is provided, then this list interacts as fall back shader list. The UA takes the first successfully parsed custom-filter at-rule with a supported shading language.
Parameters are passed to the valid custom-filter at-rule. Definitions of parameters in the custom-filter at-rule are overridden.

custom-filter at-rule

To address the needs on the defined goals, we came up with a new custom-filter at-rule. The custom-filter at-rule defines a shader program with the following required properties:

	format: IDENT
	parameters: <params>#

And the following properties that must be supported for the recommended shading language:

	vertex: <URL>
	fragment: <URL>
	mesh: <integer>{0,2} <box>? [ detached | attached ]?
	mix: <compositing> && <blending>

* IDENT is a unique identifier for a specific shading language. The recommended identifier for the recommended shading language is "glsl". Future versions can add a version number. UAs can decide to support other shading languages with other identifiers.
* <URL> is a reference to the shader file.
* <box>, detached, attached see definition in the current working draft[2].

The UA should take the value of 'format' into account to identify if the shader language is supported. If the author does not specify this property, the UA is recommended to interpret the shader as GLSL shader.
Other shading languages may require additional properties like 'geometry' for a geometry shader. This specification explicitly allows the extension of the custom-filter function by new properties, as the shading language requires. The property set must not be extended, if the format is specified as "glsl". A future version of this specification may define further identifiers and properties.

UAs must not accept 'format' identifier if the associated shading language is not supported.

If the parsing of a custom-filter at-rule fails, the parsing of the referenced shader files fail, or the format identifier is not accepted by the UA, this rule is treated as invalid. The custom function must proceed with the next custom-filter at-rule in the custom-filter at-rule list. Shader files of invalid custom-filter at-rule are not downloaded.

Properties in the custom-filter at-rule are not animatable.

Animation of custom function

To avoid repetition of values, parameters can be set in the custom-filter at-rule. If a parameter does not need to be animated, authors should define the parameter in the custom-filter at-rule. Otherwise the parameter should be specified in the custom function.


The custom-filter at-rule defines a bunch of parameters. These parameters don't need to be specified in the custom function, which limits the repetition of these parameters, a huge benefit on CSS Animations keyframe at-rule definitions.

	@custom-filter "my-filter" {
		format: "glsl";
		mix: normal source-in;
		parameters: ctm scale(1), array array(1, 1, 2, 3, 5), var 4, matA mat2(1, 0, 0, 1), matB mat2(1, 0, 0, 1), matC mat2(2, 0, 0, 2), matD mat2(3, 0, 0, 3), matE mat2(4, 0, 0, 4);
		mesh: 3 3 content-mask detached;

		vertex: url(shader-glsl.vs);
		fragment: url(shader-glsl.fs);

	img {
		filter: custom("my-filter");
		animation: "filter-animation" 3s linear;

	@keyframe "filter-animation" {
		0% {
			filter: custom("my-filter", ctm translate(0px, 0px), amplitude 0);
		100% {
			filter: custom("my-filter", ctm translate(100px, 100px), amplitude 3.14);

The keyframe at-rule definition just sets parameters that are animated. CSS Transitions look similar:

	img {
		filter: custom("my-filter", amplitude 0);
		transition: filter 3s linear;

	img:hover {
		filter: custom("my-filter", ctm translate(100px, 100px), amplitude 3.14);

We would like to discuss this proposal with the working groups as well as the web community. We are very open for suggestions and improvements.


[1] http://lists.w3.org/Archives/Public/public-fx/2012JulSep/0074.html
[2] http://www.w3.org/TR/2012/WD-filter-effects-20121025/
[3] http://www.w3.org/TR/2012/WD-filter-effects-20121025/#FilterFunction
Received on Thursday, 15 November 2012 22:05:25 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:49:43 UTC