Overview.bs

<pre class='metadata'>
Title: CSS Images Module Level 5
Status: ED
Work Status: Exploring
Shortname: css-images
Level: 5
Group: csswg
ED: https://drafts.csswg.org/css-images-5/
TR: https://www.w3.org/TR/css-images-5/
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Lea Verou, Invited Expert, http://lea.verou.me/about, w3cid 52258
Abstract: This module contains the features of CSS level 4 relating to the <<image>> type and replaced elements.
	It includes and extends the functionality of CSS level 2 [[CSS2]] and in the previous level of this specification [[css-images-4]].
Default Highlight: css
Ignore MDN Failure: the-image-orientation
Ignore MDN Failure: the-image-rendering
Ignore MDN Failure: the-object-fit
Ignore MDN Failure: the-object-position
Ignore MDN Failure: gradients
Ignore MDN Failure: image-values
Ignore MDN Failure: radial-gradients
Ignore MDN Failure: repeating-gradients
</pre>

Introduction {#intro}
=====================

This is a diff spec over [[!css-images-4]].

<!--
   ██ ████ ██     ██    ███     ██████   ████████ ██
  ██   ██  ███   ███   ██ ██   ██    ██  ██        ██
 ██    ██  ████ ████  ██   ██  ██        ██         ██
██     ██  ██ ███ ██ ██     ██ ██   ████ ██████      ██
 ██    ██  ██     ██ █████████ ██    ██  ██         ██
  ██   ██  ██     ██ ██     ██ ██    ██  ██        ██
   ██ ████ ██     ██ ██     ██  ██████   ████████ ██
-->

2D Image Values: the <<image>> type {#image-values}
===================================================

	...

<!--
████ ██     ██    ███     ██████   ████████   ███ ███
 ██  ███   ███   ██ ██   ██    ██  ██        ██     ██
 ██  ████ ████  ██   ██  ██        ██       ██       ██
 ██  ██ ███ ██ ██     ██ ██   ████ ██████   ██       ██
 ██  ██     ██ █████████ ██    ██  ██       ██       ██
 ██  ██     ██ ██     ██ ██    ██  ██        ██     ██
████ ██     ██ ██     ██  ██████   ████████   ███ ███
-->


Image Fallbacks and Annotations: the ''image()'' notation {#image-notation}
---------------------------------------------------------------------------

	[[css-images-4]] defines a simple form of the ''image()'' function,
	which generates a solid-color dimensionless image.
	This level introduces a number of additional functions.

	The ''image()'' function allows an author to:

	* use <a href="https://www.w3.org/TR/media-frags/">media fragments</a> to clip out a portion of an image
	* use a solid color as an image
	* fallback to a solid-color image, when the image at the specified url can't be downloaded or decoded
	* automatically respect the image orientation specified in the image's metadata

	The ''image()'' notation is defined as:

	<pre class='prod'>
		<dfn>image()</dfn> = image( <<image-tags>>? [ <<image-src>>? , <<color>>? ]! )
		<dfn>&lt;image-tags></dfn> = [ ltr | rtl ]
		<dfn>&lt;image-src></dfn> = [ <<url>> | <<string>> ]
	</pre>

	A <<string>> used in ''image()'' represents a <<url>>.
	As usual for URLs in CSS,
	relative URLs are resolved to an absolute URL
	(as described in Values &amp; Units [[!CSS-VALUES-3]])
	when a specified ''image()'' value is computed.

	If the image has an orientation specified in its metadata,
	such as EXIF,
	the UA must rotate or flip the image to correctly orient it
	as the metadata specifies.

### Image Fallbacks ### {#image-fallbacks}

	If both a URL and a <<color>> are specified in ''image()'',
	then whenever the URL represents an [=invalid image=] or [=loading image=],
	the ''image()'' function renders as if the URL were not specified at all;
	it generates a solid-color image as specified in [[#color-images]].

	If just a URL is specified (no <<color>>)
	and it represents an [=invalid image=] or [=loading image=],
	the ''image()'' function represents the same.

	<wpt>
		css-image-fallbacks-and-annotations.html
		css-image-fallbacks-and-annotations002.html
		css-image-fallbacks-and-annotations003.html
		css-image-fallbacks-and-annotations004.html
		css-image-fallbacks-and-annotations005.html
	</wpt>

	<div class='example' id='ex-fallback'>
		The fallback color can be used to ensure that text is still readable
		even when the image fails to load.
		For example, the following legacy code works fine if the image is rectangular and has no transparency:

		<pre class="lang-css">
			body      { color: black; background: white; }
			p.special { color: white; background: url("dark.png") black; }
		</pre>

		When the image doesn't load,
		the background color is still there to ensure that the white text is readable.
		However, if the image has some transparency,
		the black will be visible behind it,
		which is probably not desired.
		The ''image()'' function addresses this:

		<pre class="lang-css">
			body      { color: black; background: white; }
			p.special { color: white; background: image("dark.png", black); }
		</pre>

		Now, the black won't show at all if the image loads,
		but if for whatever reason the image fails,
		it'll pop in and prevent the white text from being set against a white background.
	</div>

<!-- Good example for the fallback() function
	<div class='example' id='ex-fallback-2'>
		For example, if a future specification defined a way to refer to a specific frame of an animated GIF with a fragment identifier,
		an author could write the following to get newer browsers to use the GIF's frame,
		and older browsers to instead download the fallback image:

		<pre class="lang-css">background-image: image("cat_meme.gif#frame=5", "lolcat.png");</pre>
	</div>
-->

### Image Fragments ### {#image-fragments}

	When a URL specified in ''image()'' represents a portion of a resource
	(e.g. by the use of <a href="https://www.w3.org/TR/media-frags/#naming-space">media fragment identifiers</a>)
	that portion is clipped out of its context and used as a standalone image.

	<div class="example" id='ex-image-fragment'>
		For example, given the following image and CSS:

		<a href="images/sprites.svg">
			<img src="images/sprites.svg" height="20" width="180" alt="[9 circles, with 0 to 8 eighths filled in]">
		</a>

		<pre class="lang-css">background-image: image('sprites.svg#xywh=40,0,20,20')</pre>

		...the background of the element will be the portion of the image that starts at (40px,0px) and is 20px wide and tall,
		which is just the circle with a quarter filled in.
	</div>

	So that authors can take advantage of CSS's forwards-compatible parsing rules to provide a fallback for image slices,
	implementations that support the ''image()'' notation
	<em>must</em> support the <code>xywh=#,#,#,#</code> form of media fragment identifiers
	for images specified via ''image()''. [[!MEDIA-FRAGS]]

	<div class='example' id='ex-image-fragment-fallback'>
		Note that image fragments can also be used with the ''url()'' notation.
		However, a legacy UA that doesn't understand the media fragments notation
		will ignore the fragment and simply display the entirety of the image.

		Since the ''image()'' notation requires UAs to support media fragments,
		authors can take advantage of CSS's forward-compatible parsing rules
		to provide a fallback when using an image fragment URL:

		<pre class="lang-css">
			background-image: url('swirl.png'); /* old UAs */
			background-image: image('sprites.png#xywh=10,30,60,20'); /* new UAs */
		</pre>
	</div>

	If a URL uses a fragment identifier syntax that the implementation does not understand,
	or does not consider valid for that type of image,
	the URL must be treated as representing an <a>invalid image</a>.

	Note: This error-handling is limited to ''image()'',
	and not in the definition of URL,
	for legacy compat reasons.


### Solid-color Images ### {#color-images}

	If the ''image()'' function is specified with only a <<color>> argument (no URL),
	it represents a solid-color image of the specified color with no [=natural dimensions=].

	<div class='example' id='ex-solid-color'>
		For example,
		one can use this as a simple way to "tint" a background image,
		by overlaying a partially-transparent color over the top of the other image:

		<pre class="lang-css">background-image: image(rgba(0, 0, 255, .5)), url("bg-image.png");</pre>

		This is equivalent to a single color stop gradient:

		<pre class="lang-css">background-image: linear-gradient(rgba(0, 0, 255, .5)), url("bg-image.png");</pre>

		'background-color' does not work for this,
		as the solid color it generates always lies <em>beneath</em> all the background images.
	</div>


### Bidi-sensitive Images ### {#bidi-images}

	Before listing any <code>&lt;image-src>s</code>,
	the author may specify a directionality for the image,
	similar to adding a <code>dir</code> attribute to an element in HTML.
	If a directional image is used on or in an element with opposite <a href="https://www.w3.org/TR/CSS21/visuren.html#propdef-direction">direction</a>,
	the image must be flipped in the inline direction
	(as if it was transformed by, e.g., <code>scaleX(-1)</code>, if the inline direction is the X axis).

	Note: Absent this declaration,
	images default to no directionality at all,
	and thus don't care about the directionality of the surrounding element.

	<div class='example' id='ex-image-directionality'>
		A list may use an arrow for a bullet that points into the content.
		If the list can contain both LTR and RTL text,
		though, the bullet may be on the left or the right,
		and an image designed to point into the text on one side will point out of the text on the other side.
		This can be fixed with code like:

		<pre class="lang-html">
			&lt;ul style="list-style-image: image(ltr 'arrow.png');">
				&lt;li dir='ltr'>My bullet is on the left!&lt;/li>
				&lt;li dir='rtl'>MY BULLET IS ON THE RIGHT!&lt;/li>
			&lt;/ul>
		</pre>

			This should render something like:

		<pre class="lang-html">
			&#8658; My bullet is on the left!
			  !THGIR EHT NO SI TELLUB YM &#8656;
		</pre>

		In LTR list items, the image will be used as-is.
		In the RTL list items, however,
		it will be flipped in the inline direction,
		so it still points into the content.
	</div>


Sizing Images and Objects in CSS {#sizing}
==========================================

<!--
 ███████          ██     ██         ████████
██     ██         ██     ██         ██     ██
██     ██         ██     ██         ██     ██
██     ██ ███████ ██     ██ ███████ ████████
██     ██          ██   ██          ██     ██
██     ██           ██ ██           ██     ██
 ███████             ███            ████████
-->

Setting The Viewbox: the 'object-view-box' property {#the-object-view-box}
--------------------------------------------------------------------------

	<pre class=propdef>
	Name: object-view-box
	Value: none | <<basic-shape-rect>>
	Initial: none
	Applies to: [=replaced elements=]
	Inherited: no
	Percentages: n/a
	Computed value: specified keyword, or computed <<basic-shape>> function
	Animation Type: as <<basic-shape>> if possible, otherwise discrete
	</pre>

	The 'object-view-box' property
	specifies a "view box" over an element,
	which allows zooming or panning over the element's contents.
	It maps to the <{svg/viewBox|&lt;svg viewBox>}> attribute in SVG. [[SVG2]]

	ISSUE: Make sure behavior is <a href="https://github.com/w3c/csswg-drafts/issues/7058#issuecomment-1057553833">properly consistent for SVG</a>.

	<dl dfn-type=value dfn-for=object-view-box>
		: <dfn>none</dfn>
		::
			The element does not have a view box.

		: <dfn><<basic-shape-rect>></dfn>
		::
			If the element does not have both a [=natural width=]
			and a [=natural height=],
			this value has no effect,
			similar to ''object-view-box/none''.

			Otherwise, specifies a view box for the element.

			First, resolve the <<basic-shape-rect>>
			against a [=<basic-shape>/reference box=] formed by the element's
			[=natural sizes=]
			to obtain the element's view box.

			For all purposes,
			the element is now treated as having [=natural sizes=]
			equal to the view box's width and height.
			If the element had a [=natural aspect ratio=],
			it's now treated as instead having the same ratio as the view box.
			Further adjustments to the size/position of the element's contents,
			such as 'object-position' or 'object-fit',
			are similarly performed on the view box instead.

			When the element is painted,
			its contents are scaled and translated
			such that the element's contents
			retain the same position and size,
			relative to the view box's final size and position,
			that they had when the view box was determined (above).

			Issue: Have not yet defined what happens if the view box is zero-area.
			It's an error case,
			so precise behavior isn't important;
			just need to see what impls want to do about it.
	</dl>

	Note: Some replaced elements might have a built-in notion of a "view box",
	such as the <{svg}> element.
	Unless otherwise specified,
	this property does not interact with such notions;
	the built-in notion has its effect as normal,
	producing a replaced element with [=natural sizes=],
	then this property applies on top of that.

	<div class=example>
		Issue: example here. Need a basic one showing off zooming in, one showing off zooming out, and one showing off interaction with object-fit to display how the parts outside the viewbox can still be painted.
	</div>

Privacy Considerations {#privacy}
=================================

No new privacy considerations have been reported on this specification.

Security Considerations {#security}
===================================

No new security considerations have been reported on this specification.