8000 Re-add image() function, trimmed to the basic functionality. Mark as… · w3c/csswg-drafts@b3534cc · GitHub
Skip to content

Commit b3534cc

Browse files
tabatkinstabatkins
committed
Re-add image() function, trimmed to the basic functionality. Mark as at-risk.
1 parent c016c79 commit b3534cc

2 files changed

Lines changed: 158 additions & 15 deletions

File tree

‎css3-images/Overview.html‎

Lines changed: 97 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,8 @@ <h2 class="no-num no-toc" id=status> Status of this document</h2>
127127
<p>The following features are at risk:
128128

129129
<ol>
130+
<li>The <a href="#image-notation">image() function</a>
131+
130132
<li>The <a href="#element-reference">element() function</a>
131133

132134
<li>The "none" and "scale-down" values for &lsquo;<a
@@ -158,7 +160,11 @@ <h2 class="no-num no-toc" id=contents> Table of contents</h2>
158160
Image Slices: the &lsquo;<code class=css>url()</code>&rsquo;
159161
notation</a>
160162

161-
<li><a href="#element-reference"><span class=secno>4.2. </span> Using
163+
<li><a href="#image-notation"><span class=secno>4.2. </span> Image
164+
Fallbacks: the &lsquo;<code class=css>image()</code>&rsquo;
165+
notation</a>
166+
167+
<li><a href="#element-reference"><span class=secno>4.3. </span> Using
162168
Elements as Images: the &lsquo;<code class=css>element()</code>&rsquo;
163169
notation</a>
164170
</ul>
@@ -367,7 +373,7 @@ <h3 id=url><span class=secno>4.1. </span> Image References and Image
367373
Slices: the &lsquo;<code class=css>url()</code>&rsquo; notation</h3>
368374

369375
<p>The simplest way to indicate an image is to reference an image file by
370-
URI. This is done with the <a
376+
URL. This is done with the <a
371377
href="http://www.w3.org/TR/CSS21/syndata.html#uri">&lsquo;<code
372378
class=css>url()</code>&rsquo; notation</a>, defined in <a href="#CSS21"
373379
rel=biblioentry>[CSS21]<!--{{!CSS21}}--></a>.
@@ -402,12 +408,97 @@ <h3 id=url><span class=secno>4.1. </span> Image References and Image
402408
<p class=note>Note that a legacy UA that doesn't understand the media
403409
fragments notation will ignore the fragment and simply display the
404410
entirety of an image specified with &lsquo;<code
405-
class=css>url</code>&rsquo;. A future level of this module is intended to
406-
introduce an alternate image-referencing function that is guaranteed to
407-
support image fragments.</p>
411+
class=css>url</code>&rsquo;. However, since URLs with media fragment
412+
identifiers can also be used in the &lsquo;<code
413+
class=css>image()</code>&rsquo; notation defined below, authors can take
414+
advantage of CSS's forward-compatible parsing rules to provide a fallback
415+
when using an image fragment URL:
416+
417+
<div class=example>
418+
<p>In the example below, the &lsquo;<code class=css>image()</code>&rsquo;
419+
notation is used together with the media fragment syntax, so that UAs
420+
that don't support media fragments fail to parse the second declaration
421+
and use the first.</p>
422+
423+
<pre>
424+
<!-- -->background-image: url('swirl.png'); /* old UAs */
425+
<!-- -->background-image: image('sprites.png#xywh=10,30,60,20'); /* new UAs */</pre>
426+
</div>
427+
<!-- ====================================================================== -->
428+
429+
<h3 id=image-notation><span class=secno>4.2. </span> Image Fallbacks: the
430+
&lsquo;<code class=css>image()</code>&rsquo; notation</h3>
431+
432+
<p>The &lsquo;<code class=css>image()</code>&rsquo; function allows an
433+
author to specify an image with fallback images to be used if the original
434+
image can't be decoded or is a type that the browser doesn't recognize.
435+
Additionally, the author can specify a color as an ultimate fallback to be
436+
used when none of the images can be.
437+
438+
<p>So that authors can take advantage of CSS's forwards-compatible parsing
439+
rules to provide a fallback for image slices, implementations that support
440+
the &lsquo;<code class=css>image()</code>&rsquo; notation <em>must</em>
441+
support the <code>xywh=#,#,#,#</code> form of media fragment identifiers
442+
for images. <a href="#MEDIA-FRAGS"
443+
rel=biblioentry>[MEDIA-FRAGS]<!--{{!MEDIA-FRAGS}}--></a>
444+
445+
<p>The &lsquo;<code class=css>image()</code>&rsquo; notation is defined as:
446+
447+
448+
<pre class=prod><dfn id=ltimage-list>&lt;image-list></dfn> =
449+
image( [ &lt;string> , ]* [ &lt;string> | &lt;color> ] )</pre>
450+
451+
<p>Each <code>&lt;string></code> must be a URL.
452+
453+
<p>Multiple arguments can be given separated by commas, in which case the
454+
function represents the first &lt;string> representing an image that the
455+
browser can successfully load and display. The final argument can specify
456+
a &lt;color> to serve as an ultimate fallback; this can be used, e.g. for
457+
&lsquo;<code class=property>background-image</code>&rsquo;, to ensure
458+
adequate contrast if none of the preceding &lt;image-decl>s can be used.
459+
If the final argument is a &lt;color>, it represents a solid-color image
460+
of the given color with no <a href="#intrinsic-dimensions"><i>intrinsic
461+
dimensions</i></a>.
462+
463+
<div class=example>
464+
<p>The rule below would tell the UA to load &lsquo;<code
465+
class=css>wavy.svg</code>&rsquo; if it can; failing that to load
466+
&lsquo;<code class=css>wavy.png</code>&rsquo;; failing that to display
467+
&lsquo;<code class=css>wavy.gif</code>&rsquo;; and finally, if none of
468+
the images can be loaded and displayed, to use the color &lsquo;<code
469+
class=css>rgba(0,0,255,0.5)</code>&rsquo; to create a dimensionless
470+
background image. For example, the browser might not understand how to
471+
render SVG images, the PNG may be malformed, and the GIF might not exist
472+
on the server and return an HTML 404 error page instead of an image.</p>
473+
474+
<pre>background-image: image("wavy.svg", 'wavy.png' , "wavy.gif", rgba(0,0,255,0.5));</pre>
475+
476+
<p>The &lsquo;<code class=property>background-size</code>&rsquo; property
477+
specifies that dimensionless images by default stretch to cover the
478+
entire background positioning area <a href="#CSS3BG"
479+
rel=biblioentry>[CSS3BG]<!--{{CSS3BG}}--></a>, so if none of the
480+
specified images can be displayed the background will be painted
481+
semi-transparent blue. As with any image, this fallback will be painted
482+
over the &lsquo;<code class=property>background-color</code>&rsquo; (if
483+
any).</p>
484+
</div>
485+
486+
<div class=example>
487+
<p>At times, one may need a solid-color image for a property or function
488+
that does not accept the &lt;color> type directly. The &lsquo;<code
489+
class=css>image()</code>&rsquo; function can be used for this: by
490+
specifying <em>only</em> a color without any URLs, the function
491+
immediately falls back to representing a solid-color image of the chosen
492+
color.
493+
494+
<pre>background-image: image(rgba(0,0,255,.5)), url("bg-image.png");</pre>
495+
496+
<p>In the above, the background is the image "bg-image.png", overlaid with
497+
partially-transparent blue.
498+
</div>
408499
<!-- ====================================================================== -->
409500

410-
<h3 id=element-reference><span class=secno>4.2. </span> Using Elements as
501+
<h3 id=element-reference><span class=secno>4.3. </span> Using Elements as
411502
Images: the &lsquo;<code class=css>element()</code>&rsquo; notation</h3>
412503

413504
<p>The &lsquo;<code class=css>element()</code>&rsquo; function allows an

‎css3-images/Overview.src.html‎

Lines changed: 61 additions & 9 deletions
< 55C0 td data-grid-cell-id="diff-4a48af6d07b0bb3ada4b8daf320d545d50715abf2ee12118112d4d94e04ff872-212-212-1" data-selected="false" role="gridcell" style="background-color:var(--diffBlob-deletionNum-bgColor, var(--diffBlob-deletion-bgColor-num));text-align:center" tabindex="-1" valign="top" class="focusable-grid-cell diff-line-number position-relative left-side"> 8096
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,8 @@ <h2 class="no-num no-toc" id="status">
6868
<p>The following features are at risk:</p>
6969

7070
<ol>
71+
<li>The <a href="#image-notation">image() function</a></li>
72+
7173
<li>The <a href="#element-reference">element() function</a></li>
7274

7375
<li>The "none" and "scale-down" values for 'object-fit'</li>
@@ -208,10 +210,7 @@ <h2 id="image">
208210
<h3 id="url">
209211
Image References and Image Slices: the ''url()'' notation</h3>
210212

211-
<p>The simplest way to indicate an image is to reference an image file
212-
by URI. This is done with the
213-
<a href="http://www.w3.org/TR/CSS21/syndata.html#uri">''url()'' notation</a>,
214-
defined in [[!CSS21]].
213+
<p>The simplest way to indicate an image is to reference an image file by URL. This is done with the <a href="http://www.w3.org/TR/CSS21/syndata.html#uri">''url()'' notation</a>, defined in [[!CSS21]].
215214

216215
<div class="example">
217216
<p>In the example below, a background image is specified with ''url()''
@@ -220,10 +219,7 @@ <h3 id="url">
220219
<pre>background-image: url(wavy.png);</pre>
221220
</div>
222221

223-
<p>A portion of an image may be referenced (clipped out and used as a
224-
standalone image) by use of
225-
<a href="http://www.w3.org/TR/media-frags/#naming-space">media fragment identifiers</a>.
226-
[[!MEDIA-FRAGS]]
222+
<p>A portion of an image may be referenced (clipped out and used as a standalone image) by use of <a href="http://www.w3.org/TR/media-frags/#naming-space">media fragment identifiers</a>. [[!MEDIA-FRAGS]]
227223

228224
<div class="example">
229225
<p>For example, given the following image* and CSS:</p>
@@ -240,7 +236,63 @@ <h3 id="url">
240236
<p><small>* SVG-in-&lt;img> support required. Click the picture to view the SVG directly.</small></p>
241237
</div>
242238

243-
<p class="note">Note that a legacy UA that doesn't understand the media fragments notation will ignore the fragment and simply display the entirety of an image specified with ''url''. A future level of this module is intended to introduce an alternate image-referencing function that is guaranteed to support image fragments.</p>
239+
<p class="note">Note that a legacy UA that doesn't understand the media
240+
fragments notation will ignore the fragment and simply display the
241+
entirety of an image specified with ''url''. However, since URLs with
242+
media fragment identifiers can also be used in the ''image()'' notation
243+
defined below, authors can take advantage of CSS's forward-compatible
244+
parsing rules to provide a fallback when using an image fragment URL:</p>
245+
246+
<div class="example">
247+
<p>In the example below, the ''image()'' notation is used together with
248+
the media fragment syntax, so that UAs that don't support media fragments
249+
fail to parse the second declaration and use the first.</p>
250+
251+
<pre>
252+
<!-- -->background-image: url('swirl.png'); /* old UAs */
253+
<!-- -->background-image: image('sprites.png#xywh=10,30,60,20'); /* new UAs */</pre>
254+
</div>
255+
256+
<!-- ====================================================================== -->
257+
258+
<h3 id="image-notation">
259+
Image Fallbacks: the ''image()'' notation</h3>
260+
261+
<p>The ''image()'' function allows an author to specify an image with fallback images to be used if the original image can't be decoded or is a type that the browser doesn't recognize. Additionally, the author can specify a color as an ultimate fallback to be used when none of the images can be.</p>
262+
263+
<p>So that authors can take advantage of CSS's forwards-compatible parsing
264+
rules to provide a fallback for image slices, implementations that support
265+
the ''image()'' notation <em>must</em> support the <code>xywh=#,#,#,#</code>
266+
form of media fragment identifiers for images. [[!MEDIA-FRAGS]]
267+
268+
<p>The ''image()'' notation is defined as:
269+
270+
<pre class='prod'><dfn>&lt;image-list></dfn> =
271+
image( [ &lt;string> , ]* [ &lt;string> | &lt;color> ] )</pre>
272+
273+
<p>Each <code>&lt;string></code> must be a URL.</p>
274+
275+
<p>Multiple arguments can be given separated by commas, in which case the function represents the first &lt;string> representing an image that the browser can successfully load and display. The final argument can specify a &lt;color> to serve as an ultimate fallback; this can be used, e.g. for 'background-image', to ensure adequate contrast if none of the preceding &lt;image-decl>s can be used. If the final argument is a &lt;color>, it represents a solid-color image of the given color with no <i>intrinsic dimensions</i>.
276+
277+
<div class="example">
278+
<p>The rule below would tell the UA to load ''wavy.svg'' if it can; failing that to load ''wavy.png''; failing that to display ''wavy.gif''; and finally, if none of the images can be loaded and displayed, to use the color ''rgba(0,0,255,0.5)'' to create a dimensionless background image. For example, the browser might not understand how to render SVG images, the PNG may be malformed, and the GIF might not exist on the server and return an HTML 404 error page instead of an image.</p>
279+
280+
<pre>background-image: image("wavy.svg", 'wavy.png' , "wavy.gif", rgba(0,0,255,0.5));</pre>
281+
282+
<p>The 'background-size' property specifies that dimensionless images
283+
by default stretch to cover the entire background positioning area
284+
[[CSS3BG]], so if none of the specified images can be displayed
285+
the background will be painted semi-transparent blue. As with any image,
286+
this fallback will be painted over the 'background-color' (if any).</p>
287+
</div>
288+
289+
<div class='example'>
290+
<p>At times, one may need a solid-color image for a property or function that does not accept the &lt;color> type directly. The ''image()'' function can be used for this: by specifying <em>only</em> a color without any URLs, the function immediately falls back to representing a solid-color image of the chosen color.
291+
292+
<pre>background-image: image(rgba(0,0,255,.5)), url("bg-image.png");</pre>
293+
294+
<p>In the above, the background is the image "bg-image.png", overlaid with partially-transparent blue.
295+
</div>
244296

245297
<!-- ====================================================================== -->
246298

0 commit comments

Comments
 (0)