doc/filter-image-responsive.html - incubator-pagespeed-website - Git at Google

 <!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->

 <html>
   <head>
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>Responsive Images</title>
     <link rel="stylesheet" href="doc.css">
   </head>
   <body>
 <!--#include virtual="_header.html" -->


   <div id=content>
 <h1>Responsive Images</h1>
 <p class="note"><strong>Note: New filter as of 1.10.33.0</strong></p>

 <h2>Configuration</h2>
 <p>
   The 'Responsive Images' filter requires the 'Resize Images' filter;
   these filters are enabled by specifying:
 </p>
 <dl>
   <dt>Apache:<dd><pre class="prettyprint"
      >ModPagespeedEnableFilters responsive_images,resize_images</pre>
   <dt>Nginx:<dd><pre class="prettyprint"
      >pagespeed EnableFilters responsive_images,resize_images;</pre>
 </dl>
 <p>
   in the configuration file. An additional zoom feature can be enabled by
   specifying:
 </p>
 <dl>
   <dt>Apache:<dd><pre class="prettyprint"
      >ModPagespeedEnableFilters responsive_images_zoom</pre>
   <dt>Nginx:<dd><pre class="prettyprint"
      >pagespeed EnableFilters responsive_images_zoom;</pre>
 </dl>
 <p id="pagespeed_no_transform">
   The 'Responsive Images' filter won't optimize an image if it has
   the <code>data-pagespeed-no-transform</code>
   or <code>pagespeed_no_transform</code> attribute. Usage:
 </p>
 <pre class="prettyprint">
   &lt;img src="example.png" data-pagespeed-no-transform&gt;
 </pre>

 <h2>Description</h2>
 <p>
   This filter makes images responsive by adding <code>srcset</code> attributes
   which provide multiple versions for different pixel density screens.
 </p>
 <p>
   If <code>responsive_images_zoom</code> is enabled, it also extends the
   default srcset functionality by loading higher resolution images when the
   user zooms in.
 </p>
 <p>
   In order to take advantage of this filter, the original image must
   explicitly specify <code>height</code> and <code>width</code> attributes
   and src must be a high enough resolution image (at least 2x larger than
   these height and width values).
 </p>

 <h2>Example</h2>
 <p>
   For example, if the original HTML looks like this:
 </p>
 <pre class="prettyprint">
 &lt;img src="foo.png" width="100" height="100"&gt;
 </pre>
 <p>
   and <code>foo.png</code> is 1000x1000, then PageSpeed will rewrite it into:
 </p>
 <pre class="prettyprint">
 &lt;img src="100x100xfoo.png.pagespeed.ic.HASH1.png" width="100" height="100"
      srcset="150x150xfoo.png.pagespeed.ic.HASH2.png 1.5x,200x200xfoo.png.pagespeed.ic.HASH3.png 2x,300x300xfoo.png.pagespeed.ic.HASH4.png 3x, foo.png 10x"&gt;
 </pre>
 <p>
   Which will load the normal 100x100 image on standard displays,
   higher-resolution 150x150, 200x200 or 300x300 image on 1.5x, 2x, or 3x
   displays, or the full original 1000x1000 image when users zoom in enough.
 </p>
 <p>
   If <code>foo.png</code> is 200x200, no 3x or higher version will be added to
   srcset.
   If <code>foo.png</code> is only 100x100, no srcset will be added at all.
 </p>

 <h3>Online Example</h3>
 <p>
   You can see the filter in action at <a href="https://www.modpagespeed.com/examples/responsive_images.html?PageSpeed=on&amp;PageSpeedFilters=responsive_images,responsive_images_zoom,rewrite_images,inline_images,resize_images,insert_image_dimensions"><code>www.modpagespeed.com</code></a>.
 </p>

 <h2>Limitations</h2>
 <ul>
   <li>Before 1.12.34.1, PageSpeed would not optimize images referenced in
     existing <code>srcset</code> attributes.</li>
   <li>Images must have explicit <code>height</code> and <code>width</code>
     attributes and src must refer to a higher resolution image.</li>
   <li>PageSpeed does not mix inline images with <code>srcset</code>s. If the
     largest size image is inlinable, we just inline that. Otherwise we do not
     inline any of the images and use a <code>srcset</code> instead.</li>
   <li>The Responsive Images filter is not compatible with the
     <a href="filter-local-storage-cache">Local Storage Cache filter</a>.
     Images modified by the Responsive Images filter will not be stored in
     Local Storage.</li>
   <li>PageSpeed's default memory limits keep it from processing images larger
     than 8 million pixels (8MP).  If you have images larger than this, it won't
     be able to resize them to generate the lower resolution versions.  See
     <a href="reference-image-optimize#ImageResolutionLimitBytes"
     >ImageResolutionLimitBytes</a> for more details on increasing this limit or
     resizing source images to be under the limit.</li>
 </ul>

 <h2>Risks</h2>
 <p>
   This filter will increase cache usage by 4x for all images which have
   explicit <code>width</code> and <code>height</code> attributes.
   (This is true even if the original image is only 1x.) If this pushes
   your cache over the <a href=system#file_cache><code>FileCacheSize</code></a>,
   then you may experience cache churn which makes PageSpeed much less effective.
 </p>
 <p>
   This filter has the same risks inherent in the 'Resize Images' filter.
   See <a href="filter-image-optimize#Risks">Optimize Images - Risks</a>
   for more information.
 </p>
 <p>
   This filter adds a <code>srcset</code> attribute to images. This will break
   any JavaScript which changes images by modifying their <code>src</code>
   attribute. On high-density displays, modifying the <code>src</code> attribute
   will not actually change the image. As a work-around, you can add a
   <a href="#pagespeed_no_transform"><code>data-pagespeed-no-transform</code></a>
   attribute to any <code>&lt;img&gt;</code> tag to prevent PageSpeed from adding
   a <code>srcset</code>.
 </p>
 <p>
   If using <code>responsive_images_zoom</code>, the JavaScript used to
   implement that feature may conflict with other JS on the page.
 </p>

 </div>
   <!--#include virtual="_footer.html" -->
   </body>
 </html>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<html>
	<head>
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Responsive Images</title>
	<link rel="stylesheet" href="doc.css">
	</head>
	<body>
	<!--#include virtual="_header.html" -->


	<div id=content>
	<h1>Responsive Images</h1>
	<p class="note"><strong>Note: New filter as of 1.10.33.0</strong></p>

	<h2>Configuration</h2>
	<p>
	The 'Responsive Images' filter requires the 'Resize Images' filter;
	these filters are enabled by specifying:
	</p>
	<dl>
	<dt>Apache:<dd><pre class="prettyprint"
	>ModPagespeedEnableFilters responsive_images,resize_images</pre>
	<dt>Nginx:<dd><pre class="prettyprint"
	>pagespeed EnableFilters responsive_images,resize_images;</pre>
	</dl>
	<p>
	in the configuration file. An additional zoom feature can be enabled by
	specifying:
	</p>
	<dl>
	<dt>Apache:<dd><pre class="prettyprint"
	>ModPagespeedEnableFilters responsive_images_zoom</pre>
	<dt>Nginx:<dd><pre class="prettyprint"
	>pagespeed EnableFilters responsive_images_zoom;</pre>
	</dl>
	<p id="pagespeed_no_transform">
	The 'Responsive Images' filter won't optimize an image if it has
	the <code>data-pagespeed-no-transform</code>
	or <code>pagespeed_no_transform</code> attribute. Usage:
	</p>
	<pre class="prettyprint">
	<img src="example.png" data-pagespeed-no-transform>
	</pre>

	<h2>Description</h2>
	<p>
	This filter makes images responsive by adding <code>srcset</code> attributes
	which provide multiple versions for different pixel density screens.
	</p>
	<p>
	If <code>responsive_images_zoom</code> is enabled, it also extends the
	default srcset functionality by loading higher resolution images when the
	user zooms in.
	</p>
	<p>
	In order to take advantage of this filter, the original image must
	explicitly specify <code>height</code> and <code>width</code> attributes
	and src must be a high enough resolution image (at least 2x larger than
	these height and width values).
	</p>

	<h2>Example</h2>
	<p>
	For example, if the original HTML looks like this:
	</p>
	<pre class="prettyprint">
	<img src="foo.png" width="100" height="100">
	</pre>
	<p>
	and <code>foo.png</code> is 1000x1000, then PageSpeed will rewrite it into:
	</p>
	<pre class="prettyprint">
	<img src="100x100xfoo.png.pagespeed.ic.HASH1.png" width="100" height="100"
	srcset="150x150xfoo.png.pagespeed.ic.HASH2.png 1.5x,200x200xfoo.png.pagespeed.ic.HASH3.png 2x,300x300xfoo.png.pagespeed.ic.HASH4.png 3x, foo.png 10x">
	</pre>
	<p>
	Which will load the normal 100x100 image on standard displays,
	higher-resolution 150x150, 200x200 or 300x300 image on 1.5x, 2x, or 3x
	displays, or the full original 1000x1000 image when users zoom in enough.
	</p>
	<p>
	If <code>foo.png</code> is 200x200, no 3x or higher version will be added to
	srcset.
	If <code>foo.png</code> is only 100x100, no srcset will be added at all.
	</p>

	<h3>Online Example</h3>
	<p>
	You can see the filter in action at <a href="https://www.modpagespeed.com/examples/responsive_images.html?PageSpeed=on&PageSpeedFilters=responsive_images,responsive_images_zoom,rewrite_images,inline_images,resize_images,insert_image_dimensions"><code>www.modpagespeed.com</code></a>.
	</p>

	<h2>Limitations</h2>
	<ul>
	<li>Before 1.12.34.1, PageSpeed would not optimize images referenced in
	existing <code>srcset</code> attributes.</li>
	<li>Images must have explicit <code>height</code> and <code>width</code>
	attributes and src must refer to a higher resolution image.</li>
	<li>PageSpeed does not mix inline images with <code>srcset</code>s. If the
	largest size image is inlinable, we just inline that. Otherwise we do not
	inline any of the images and use a <code>srcset</code> instead.</li>
	<li>The Responsive Images filter is not compatible with the
	<a href="filter-local-storage-cache">Local Storage Cache filter</a>.
	Images modified by the Responsive Images filter will not be stored in
	Local Storage.</li>
	<li>PageSpeed's default memory limits keep it from processing images larger
	than 8 million pixels (8MP). If you have images larger than this, it won't
	be able to resize them to generate the lower resolution versions. See
	<a href="reference-image-optimize#ImageResolutionLimitBytes"
	>ImageResolutionLimitBytes</a> for more details on increasing this limit or
	resizing source images to be under the limit.</li>
	</ul>

	<h2>Risks</h2>
	<p>
	This filter will increase cache usage by 4x for all images which have
	explicit <code>width</code> and <code>height</code> attributes.
	(This is true even if the original image is only 1x.) If this pushes
	your cache over the <a href=system#file_cache><code>FileCacheSize</code></a>,
	then you may experience cache churn which makes PageSpeed much less effective.
	</p>
	<p>
	This filter has the same risks inherent in the 'Resize Images' filter.
	See <a href="filter-image-optimize#Risks">Optimize Images - Risks</a>
	for more information.
	</p>
	<p>
	This filter adds a <code>srcset</code> attribute to images. This will break
	any JavaScript which changes images by modifying their <code>src</code>
	attribute. On high-density displays, modifying the <code>src</code> attribute
	will not actually change the image. As a work-around, you can add a
	<a href="#pagespeed_no_transform"><code>data-pagespeed-no-transform</code></a>
	attribute to any <code><img></code> tag to prevent PageSpeed from adding
	a <code>srcset</code>.
	</p>
	<p>
	If using <code>responsive_images_zoom</code>, the JavaScript used to
	implement that feature may conflict with other JS on the page.
	</p>

	</div>
	<!--#include virtual="_footer.html" -->
	</body>
	</html>