webrender/

resource_cache.rs

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

use api::{BlobImageRequest, ImageDescriptorFlags, ImageFormat, RasterizedBlobImage};
use api::{DebugFlags, FontInstanceKey, FontKey, FontTemplate, GlyphIndex};
use api::{ExternalImageData, ExternalImageType, ExternalImageId, BlobImageResult};
use api::{DirtyRect, GlyphDimensions, IdNamespace, DEFAULT_TILE_SIZE};
use api::{ColorF, ImageData, ImageDescriptor, ImageKey, ImageRendering, TileSize};
use api::{BlobImageHandler, BlobImageKey, VoidPtrToSizeFn};
use api::units::*;
use euclid::size2;
use crate::render_target::RenderTargetKind;
use crate::render_task::{RenderTaskLocation, StaticRenderTaskSurface};
use crate::{render_api::{ClearCache, AddFont, ResourceUpdate, MemoryReport}, util::WeakTable};
use crate::prim_store::image::AdjustedImageSource;
use crate::image_tiling::{compute_tile_size, compute_tile_range};
#[cfg(feature = "capture")]
use crate::capture::ExternalCaptureImage;
#[cfg(feature = "replay")]
use crate::capture::PlainExternalImage;
#[cfg(any(feature = "replay", feature = "png", feature="capture"))]
use crate::capture::CaptureConfig;
use crate::composite::{NativeSurfaceId, NativeSurfaceOperation, NativeTileId, NativeSurfaceOperationDetails};
use crate::device::TextureFilter;
use crate::glyph_cache::{GlyphCache, CachedGlyphInfo};
use crate::glyph_cache::GlyphCacheEntry;
use glyph_rasterizer::{GLYPH_FLASHING, FontInstance, GlyphFormat, GlyphKey, GlyphRasterizer, GlyphRasterJob};
use glyph_rasterizer::{SharedFontResources, BaseFontInstance};
use crate::gpu_types::UvRectKind;
use crate::internal_types::{
    CacheTextureId, FastHashMap, FastHashSet, TextureSource, ResourceUpdateList,
    FrameId, FrameStamp,
};
use crate::profiler::{self, TransactionProfile, bytes_to_mb};
use crate::render_task_graph::{RenderTaskId, RenderTaskGraphBuilder};
use crate::render_task_cache::{RenderTaskCache, RenderTaskCacheKey, RenderTaskParent};
use crate::render_task_cache::{RenderTaskCacheEntry, RenderTaskCacheEntryHandle};
use crate::renderer::{GpuBufferAddress, GpuBufferBuilder, GpuBufferBuilderF, GpuBufferHandle};
use crate::surface::SurfaceBuilder;
use euclid::point2;
use smallvec::SmallVec;
use std::collections::hash_map::Entry::{self, Occupied, Vacant};
use std::collections::hash_map::{Iter, IterMut};
use std::collections::VecDeque;
use std::{cmp, mem};
use std::fmt::Debug;
use std::hash::Hash;
use std::os::raw::c_void;
#[cfg(any(feature = "capture", feature = "replay"))]
use std::path::PathBuf;
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::u32;
use crate::texture_cache::{TextureCache, TextureCacheHandle, Eviction, TargetShader};
use crate::picture_textures::PictureTextures;
use peek_poke::PeekPoke;

// Counter for generating unique native surface ids
static NEXT_NATIVE_SURFACE_ID: AtomicUsize = AtomicUsize::new(0);

#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
pub struct GlyphFetchResult {
    pub index_in_text_run: i32,
    pub uv_rect_address: GpuBufferAddress,
    pub offset: DevicePoint,
    pub size: DeviceIntSize,
    pub scale: f32,
    pub subpx_offset_x: u8,
    pub subpx_offset_y: u8,
    pub is_packed_glyph: bool,
}

// These coordinates are always in texels.
// They are converted to normalized ST
// values in the vertex shader. The reason
// for this is that the texture may change
// dimensions (e.g. the pages in a texture
// atlas can grow). When this happens, by
// storing the coordinates as texel values
// we don't need to go through and update
// various CPU-side structures.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
pub struct CacheItem {
    pub texture_id: TextureSource,
    pub uv_rect_handle: GpuBufferHandle,
    pub uv_rect: DeviceIntRect,
    pub user_data: [f32; 4],
}

impl CacheItem {
    pub fn invalid() -> Self {
        CacheItem {
            texture_id: TextureSource::Invalid,
            uv_rect_handle: GpuBufferHandle::INVALID,
            uv_rect: DeviceIntRect::zero(),
            user_data: [0.0; 4],
        }
    }

    pub fn is_valid(&self) -> bool {
        self.texture_id != TextureSource::Invalid
    }
}

/// Represents the backing store of an image in the cache.
/// This storage can take several forms.
#[derive(Clone, Debug)]
pub enum CachedImageData {
    /// A simple series of bytes, provided by the embedding and owned by WebRender.
    /// The format is stored out-of-band, currently in ImageDescriptor.
    Raw(Arc<Vec<u8>>),
    /// An series of commands that can be rasterized into an image via an
    /// embedding-provided callback.
    ///
    /// The commands are stored elsewhere and this variant is used as a placeholder.
    Blob,
    /// A stacking context for which a snapshot has been requested.
    ///
    /// The snapshot is grabbed from GPU-side rasterized pixels so there is no
    /// CPU-side data to store here.
    Snapshot,
    /// An image owned by the embedding, and referenced by WebRender. This may
    /// take the form of a texture or a heap-allocated buffer.
    External(ExternalImageData),
}

impl From<ImageData> for CachedImageData {
    fn from(img_data: ImageData) -> Self {
        match img_data {
            ImageData::Raw(data) => CachedImageData::Raw(data),
            ImageData::External(data) => CachedImageData::External(data),
        }
    }
}

impl CachedImageData {
    /// Returns true if this represents a blob.
    #[inline]
    pub fn is_blob(&self) -> bool {
        match *self {
            CachedImageData::Blob => true,
            _ => false,
        }
    }

    #[inline]
    pub fn is_snapshot(&self) -> bool {
        match *self {
            CachedImageData::Snapshot => true,
            _ => false,
        }
    }

    /// Returns true if this variant of CachedImageData should go through the texture
    /// cache.
    #[inline]
    pub fn uses_texture_cache(&self) -> bool {
        match *self {
            CachedImageData::External(ref ext_data) => match ext_data.image_type {
                ExternalImageType::TextureHandle(_) => false,
                ExternalImageType::Buffer => true,
            },
            CachedImageData::Blob => true,
            CachedImageData::Raw(_) => true,
            CachedImageData::Snapshot => true,
        }
    }
}

#[derive(Debug)]
#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
pub struct ImageProperties {
    pub descriptor: ImageDescriptor,
    pub external_image: Option<ExternalImageData>,
    pub tiling: Option<TileSize>,
    // Potentially a subset of the image's total rectangle. This rectangle is what
    // we map to the (layout space) display item bounds.
    pub visible_rect: DeviceIntRect,
    pub adjustment: AdjustedImageSource,
}

#[derive(Debug, Copy, Clone, PartialEq)]
enum State {
    Idle,
    AddResources,
    QueryResources,
}

/// Post scene building state.
type RasterizedBlob = FastHashMap<TileOffset, RasterizedBlobImage>;

#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
#[derive(Debug, Copy, Clone, PartialEq, PeekPoke, Default)]
pub struct ImageGeneration(pub u32);

impl ImageGeneration {
    pub const INVALID: ImageGeneration = ImageGeneration(u32::MAX);
}

struct ImageResource {
    data: CachedImageData,
    descriptor: ImageDescriptor,
    tiling: Option<TileSize>,
    /// This is used to express images that are virtually very large
    /// but with only a visible sub-set that is valid at a given time.
    visible_rect: DeviceIntRect,
    adjustment: AdjustedImageSource,
    generation: ImageGeneration,
}

#[derive(Default)]
struct ImageTemplates {
    images: FastHashMap<ImageKey, ImageResource>,
}

impl ImageTemplates {
    fn insert(&mut self, key: ImageKey, resource: ImageResource) {
        self.images.insert(key, resource);
    }

    fn remove(&mut self, key: ImageKey) -> Option<ImageResource> {
        self.images.remove(&key)
    }

    fn get(&self, key: ImageKey) -> Option<&ImageResource> {
        self.images.get(&key)
    }

    fn get_mut(&mut self, key: ImageKey) -> Option<&mut ImageResource> {
        self.images.get_mut(&key)
    }
}

#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
struct CachedImageInfo {
    texture_cache_handle: TextureCacheHandle,
    dirty_rect: ImageDirtyRect,
    manual_eviction: bool,
}

impl CachedImageInfo {
    fn mark_unused(&mut self, texture_cache: &mut TextureCache) {
        texture_cache.evict_handle(&self.texture_cache_handle);
        self.manual_eviction = false;
    }
}

#[cfg(debug_assertions)]
impl Drop for CachedImageInfo {
    fn drop(&mut self) {
        debug_assert!(!self.manual_eviction, "Manual eviction requires cleanup");
    }
}

#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
pub struct ResourceClassCache<K: Hash + Eq, V, U: Default> {
    resources: FastHashMap<K, V>,
    pub user_data: U,
}

impl<K, V, U> ResourceClassCache<K, V, U>
where
    K: Clone + Hash + Eq + Debug,
    U: Default,
{
    pub fn new() -> Self {
        ResourceClassCache {
            resources: FastHashMap::default(),
            user_data: Default::default(),
        }
    }

    pub fn get(&self, key: &K) -> &V {
        self.resources.get(key)
            .expect("Didn't find a cached resource with that ID!")
    }

    pub fn try_get(&self, key: &K) -> Option<&V> {
        self.resources.get(key)
    }

    pub fn insert(&mut self, key: K, value: V) {
        self.resources.insert(key, value);
    }

    pub fn remove(&mut self, key: &K) -> Option<V> {
        self.resources.remove(key)
    }

    pub fn get_mut(&mut self, key: &K) -> &mut V {
        self.resources.get_mut(key)
            .expect("Didn't find a cached resource with that ID!")
    }

    pub fn try_get_mut(&mut self, key: &K) -> Option<&mut V> {
        self.resources.get_mut(key)
    }

    pub fn entry(&mut self, key: K) -> Entry<K, V> {
        self.resources.entry(key)
    }

    pub fn iter(&self) -> Iter<K, V> {
        self.resources.iter()
    }

    pub fn iter_mut(&mut self) -> IterMut<K, V> {
        self.resources.iter_mut()
    }

    pub fn is_empty(&mut self) -> bool {
        self.resources.is_empty()
    }

    pub fn clear(&mut self) {
        self.resources.clear();
    }

    pub fn retain<F>(&mut self, f: F)
    where
        F: FnMut(&K, &mut V) -> bool,
    {
        self.resources.retain(f);
    }
}

#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
struct CachedImageKey {
    pub rendering: ImageRendering,
    pub tile: Option<TileOffset>,
}

#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
pub struct ImageRequest {
    pub key: ImageKey,
    pub rendering: ImageRendering,
    pub tile: Option<TileOffset>,
}

impl ImageRequest {
    pub fn with_tile(&self, offset: TileOffset) -> Self {
        ImageRequest {
            key: self.key,
            rendering: self.rendering,
            tile: Some(offset),
        }
    }

    pub fn is_untiled_auto(&self) -> bool {
        self.tile.is_none() && self.rendering == ImageRendering::Auto
    }
}

impl Into<BlobImageRequest> for ImageRequest {
    fn into(self) -> BlobImageRequest {
        BlobImageRequest {
            key: BlobImageKey(self.key),
            tile: self.tile.unwrap(),
        }
    }
}

impl Into<CachedImageKey> for ImageRequest {
    fn into(self) -> CachedImageKey {
        CachedImageKey {
            rendering: self.rendering,
            tile: self.tile,
        }
    }
}

#[derive(Debug)]
#[cfg_attr(feature = "capture", derive(Clone, Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
pub enum ImageCacheError {
    OverLimitSize,
}

#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
enum ImageResult {
    UntiledAuto(CachedImageInfo),
    Multi(ResourceClassCache<CachedImageKey, CachedImageInfo, ()>),
    Err(ImageCacheError),
}

impl ImageResult {
    /// Releases any texture cache entries held alive by this ImageResult.
    fn drop_from_cache(&mut self, texture_cache: &mut TextureCache) {
        match *self {
            ImageResult::UntiledAuto(ref mut entry) => {
                entry.mark_unused(texture_cache);
            },
            ImageResult::Multi(ref mut entries) => {
                for entry in entries.resources.values_mut() {
                    entry.mark_unused(texture_cache);
                }
            },
            ImageResult::Err(_) => {},
        }
    }
}

type ImageCache = ResourceClassCache<ImageKey, ImageResult, ()>;

struct Resources {
    fonts: SharedFontResources,
    image_templates: ImageTemplates,
    // We keep a set of Weak references to the fonts so that we're able to include them in memory
    // reports even if only the OS is holding on to the Vec<u8>. PtrWeakHashSet will periodically
    // drop any references that have gone dead.
    weak_fonts: WeakTable
}

// We only use this to report glyph dimensions to the user of the API, so using
// the font instance key should be enough. If we start using it to cache dimensions
// for internal font instances we should change the hash key accordingly.
pub type GlyphDimensionsCache = FastHashMap<(FontInstanceKey, GlyphIndex), Option<GlyphDimensions>>;

/// Internal information about allocated render targets in the pool
struct RenderTarget {
    size: DeviceIntSize,
    format: ImageFormat,
    texture_id: CacheTextureId,
    /// If true, this is currently leant out, and not available to other passes
    is_active: bool,
    last_frame_used: FrameId,
}

impl RenderTarget {
    fn size_in_bytes(&self) -> usize {
        let bpp = self.format.bytes_per_pixel() as usize;
        (self.size.width * self.size.height) as usize * bpp
    }

    /// Returns true if this texture was used within `threshold` frames of
    /// the current frame.
    pub fn used_recently(&self, current_frame_id: FrameId, threshold: u64) -> bool {
        self.last_frame_used + threshold >= current_frame_id
    }
}

/// High-level container for resources managed by the `RenderBackend`.
///
/// This includes a variety of things, including images, fonts, and glyphs,
/// which may be stored as memory buffers, GPU textures, or handles to resources
/// managed by the OS or other parts of WebRender.
pub struct ResourceCache {
    cached_glyphs: GlyphCache,
    cached_images: ImageCache,
    cached_render_tasks: RenderTaskCache,

    resources: Resources,
    state: State,
    current_frame_id: FrameId,

    #[cfg(feature = "capture")]
    /// Used for capture sequences. If the resource cache is updated, then we
    /// mark it as dirty. When the next frame is captured in the sequence, we
    /// dump the state of the resource cache.
    capture_dirty: bool,

    pub texture_cache: TextureCache,
    pub picture_textures: PictureTextures,

    /// TODO(gw): We should expire (parts of) this cache semi-regularly!
    cached_glyph_dimensions: GlyphDimensionsCache,
    glyph_rasterizer: GlyphRasterizer,

    /// The set of images that aren't present or valid in the texture cache,
    /// and need to be rasterized and/or uploaded this frame. This includes
    /// both blobs and regular images.
    pending_image_requests: FastHashSet<ImageRequest>,

    rasterized_blob_images: FastHashMap<BlobImageKey, RasterizedBlob>,

    /// A log of the last three frames worth of deleted image keys kept
    /// for debugging purposes.
    deleted_blob_keys: VecDeque<Vec<BlobImageKey>>,

    /// We keep one around to be able to call clear_namespace
    /// after the api object is deleted. For most purposes the
    /// api object's blob handler should be used instead.
    blob_image_handler: Option<Box<dyn BlobImageHandler>>,

    /// A list of queued compositor surface updates to apply next frame.
    pending_native_surface_updates: Vec<NativeSurfaceOperation>,

    image_templates_memory: usize,
    font_templates_memory: usize,

    /// A pool of render targets for use by the render task graph
    render_target_pool: Vec<RenderTarget>,

    /// An empty (1x1 transparent) image used when a stacking context snapshot
    /// is missing.
    ///
    /// For now it acts as a catch-all solution for cases where WebRender fails
    /// to produce a texture cache item for a snapshotted tacking context.
    /// These cases include:
    /// - Empty stacking contexts.
    /// - Stacking contexts that are more aggressively culled out than they
    ///   should, for example when they are in a perspective transform that
    ///   cannot be projected to screen space.
    /// - Likely other cases we have not found yet.
    /// Over time it would be better to handle each of these cases explicitly
    /// and make it a hard error to fail to snapshot a stacking context.
    fallback_handle: TextureCacheHandle,
    debug_fallback_panic: bool,
    debug_fallback_pink: bool,
}

impl ResourceCache {
    pub fn new(
        texture_cache: TextureCache,
        picture_textures: PictureTextures,
        glyph_rasterizer: GlyphRasterizer,
        cached_glyphs: GlyphCache,
        fonts: SharedFontResources,
        blob_image_handler: Option<Box<dyn BlobImageHandler>>,
    ) -> Self {
        ResourceCache {
            cached_glyphs,
            cached_images: ResourceClassCache::new(),
            cached_render_tasks: RenderTaskCache::new(),
            resources: Resources {
                fonts,
                image_templates: ImageTemplates::default(),
                weak_fonts: WeakTable::new(),
            },
            cached_glyph_dimensions: FastHashMap::default(),
            texture_cache,
            picture_textures,
            state: State::Idle,
            current_frame_id: FrameId::INVALID,
            pending_image_requests: FastHashSet::default(),
            glyph_rasterizer,
            rasterized_blob_images: FastHashMap::default(),
            // We want to keep three frames worth of delete blob keys
            deleted_blob_keys: vec![Vec::new(), Vec::new(), Vec::new()].into(),
            blob_image_handler,
            pending_native_surface_updates: Vec::new(),
            #[cfg(feature = "capture")]
            capture_dirty: true,
            image_templates_memory: 0,
            font_templates_memory: 0,
            render_target_pool: Vec::new(),
            fallback_handle: TextureCacheHandle::invalid(),
            debug_fallback_panic: false,
            debug_fallback_pink: false,
        }
    }

    /// Construct a resource cache for use in unit tests.
    #[cfg(test)]
    pub fn new_for_testing() -> Self {
        use rayon::ThreadPoolBuilder;

        let texture_cache = TextureCache::new_for_testing(
            4096,
            ImageFormat::RGBA8,
        );
        let workers = Arc::new(ThreadPoolBuilder::new().build().unwrap());
        let glyph_rasterizer = GlyphRasterizer::new(workers, None, true);
        let cached_glyphs = GlyphCache::new();
        let fonts = SharedFontResources::new(IdNamespace(0));
        let picture_textures = PictureTextures::new(
            crate::tile_cache::TILE_SIZE_DEFAULT,
            TextureFilter::Nearest,
        );

        ResourceCache::new(
            texture_cache,
            picture_textures,
            glyph_rasterizer,
            cached_glyphs,
            fonts,
            None,
        )
    }

    pub fn max_texture_size(&self) -> i32 {
        self.texture_cache.max_texture_size()
    }

    /// Maximum texture size before we consider it preferrable to break the texture
    /// into tiles.
    pub fn tiling_threshold(&self) -> i32 {
        self.texture_cache.tiling_threshold()
    }

    pub fn enable_multithreading(&mut self, enable: bool) {
        self.glyph_rasterizer.enable_multithreading(enable);
    }

    fn should_tile(limit: i32, descriptor: &ImageDescriptor, data: &CachedImageData) -> bool {
        let size_check = descriptor.size.width > limit || descriptor.size.height > limit;
        match *data {
            CachedImageData::Raw(_) | CachedImageData::Blob => size_check,
            CachedImageData::External(info) => {
                // External handles already represent existing textures so it does
                // not make sense to tile them into smaller ones.
                info.image_type == ExternalImageType::Buffer && size_check
            }
            CachedImageData::Snapshot => false,
        }
    }

    /// Request an optionally cacheable render task.
    ///
    /// If the render task cache key is None, the render task is
    /// not cached.
    /// Otherwise, if the item is already cached, the texture cache
    /// handle will be returned. Otherwise, the user supplied
    /// closure will be invoked to generate the render task
    /// chain that is required to draw this task.
    ///
    /// This function takes care of adding the render task as a
    /// dependency to its parent task or surface.
    pub fn request_render_task(
        &mut self,
        key: Option<RenderTaskCacheKey>,
        is_opaque: bool,
        parent: RenderTaskParent,
        gpu_buffer_builder: &mut GpuBufferBuilderF,
        rg_builder: &mut RenderTaskGraphBuilder,
        surface_builder: &mut SurfaceBuilder,
        f: &mut dyn FnMut(&mut RenderTaskGraphBuilder, &mut GpuBufferBuilderF) -> RenderTaskId,
    ) -> RenderTaskId {
        self.cached_render_tasks.request_render_task(
            key.clone(),
            &mut self.texture_cache,
            is_opaque,
            parent,
            gpu_buffer_builder,
            rg_builder,
            surface_builder,
            f
        )
    }

    pub fn render_as_image(
        &mut self,
        image_key: ImageKey,
        size: DeviceIntSize,
        rg_builder: &mut RenderTaskGraphBuilder,
        gpu_buffer_builder: &mut GpuBufferBuilderF,
        is_opaque: bool,
        adjustment: &AdjustedImageSource,
        f: &mut dyn FnMut(&mut RenderTaskGraphBuilder, &mut GpuBufferBuilderF) -> RenderTaskId,
    ) -> RenderTaskId {

        let task_id = f(rg_builder, gpu_buffer_builder);

        let render_task = rg_builder.get_task_mut(task_id);

        // Note: We are defaulting to `ImageRendering::Auto` and only support
        // this mode here, because the desired rendering mode is known later
        // when an image display item will read the produced snapshot. In theory,
        // multiple image items with different rendering modes could refer to
        // the snapshot's image key, or they could first appear in a later frame
        // So delaying snapshotting logic until the we know about the rendering
        // mode would, in addition to adding complexity, only work in certain
        // cases.
        // If supporting more rendering modes is important for snapshots, we could
        // consider specifying it in the stacking context's snapshot params so
        // that we have the information early enough.
        // Here and in other parts of the code, this restriction manifests itself
        // in the expectation that we are dealing with `ImageResult::UntiledAuto`
        // which implicitly specifies the rendering mode.

        // Make sure to update the existing image info and texture cache handle
        // instead of overwriting them if they already exist for this key.
        let image_result = self.cached_images.entry(image_key).or_insert_with(|| {
            ImageResult::UntiledAuto(CachedImageInfo {
                texture_cache_handle: TextureCacheHandle::invalid(),
                dirty_rect: ImageDirtyRect::All,
                manual_eviction: true,
            })
        });

        let ImageResult::UntiledAuto(ref mut info) = *image_result else {
            unreachable!("Expected untiled image with auto filter for snapshot");
        };

        let flags = if is_opaque {
            ImageDescriptorFlags::IS_OPAQUE
        } else {
            ImageDescriptorFlags::empty()
        };

        let descriptor = ImageDescriptor::new(
            size.width,
            size.height,
            self.texture_cache.shared_color_expected_format(),
            flags,
        );

        // TODO(bug 1975123) We currently do not have a way to ensure that an
        // atlas texture used as a destination for the snapshot will not be
        // also used as an input by a primitive of the snapshot.
        // We can't both read and write the same texture in a draw call
        // so we work around it by preventing the snapshot from being placed
        // in a texture atlas.
        let force_standalone_texture = true;

        // Allocate space in the texture cache, but don't supply
        // and CPU-side data to be uploaded.
        let user_data = [0.0; 4];
        self.texture_cache.update(
            &mut info.texture_cache_handle,
            descriptor,
            TextureFilter::Linear,
            None,
            user_data,
            DirtyRect::All,
            gpu_buffer_builder,
            None,
            render_task.uv_rect_kind(),
            Eviction::Manual,
            TargetShader::Default,
            force_standalone_texture,
        );

        // Get the allocation details in the texture cache, and store
        // this in the render task. The renderer will draw this task
        // into the appropriate rect of the texture cache on this frame.
        let (texture_id, uv_rect, _, _, _) =
            self.texture_cache.get_cache_location(&info.texture_cache_handle);

        render_task.location = RenderTaskLocation::Static {
            surface: StaticRenderTaskSurface::TextureCache {
                texture: texture_id,
                target_kind: RenderTargetKind::Color,
            },
            rect: uv_rect.to_i32(),
        };

        self.resources.image_templates
            .get_mut(image_key)
            .unwrap()
            .adjustment = *adjustment;

        task_id
    }

    pub fn post_scene_building_update(
        &mut self,
        updates: Vec<ResourceUpdate>,
        profile: &mut TransactionProfile,
    ) {
        // TODO, there is potential for optimization here, by processing updates in
        // bulk rather than one by one (for example by sorting allocations by size or
        // in a way that reduces fragmentation in the atlas).
        #[cfg(feature = "capture")]
        match updates.is_empty() {
            false => self.capture_dirty = true,
            _ => {},
        }

        for update in updates {
            match update {
                ResourceUpdate::AddImage(img) => {
                    if let ImageData::Raw(ref bytes) = img.data {
                        self.image_templates_memory += bytes.len();
                        profile.set(profiler::IMAGE_TEMPLATES_MEM, bytes_to_mb(self.image_templates_memory));
                    }
                    self.add_image_template(
                        img.key,
                        img.descriptor,
                        img.data.into(),
                        &img.descriptor.size.into(),
                        img.tiling,
                    );
                    profile.set(profiler::IMAGE_TEMPLATES, self.resources.image_templates.images.len());
                }
                ResourceUpdate::UpdateImage(img) => {
                    self.update_image_template(img.key, img.descriptor, img.data.into(), &img.dirty_rect);
                }
                ResourceUpdate::AddBlobImage(img) => {
                    self.add_image_template(
                        img.key.as_image(),
                        img.descriptor,
                        CachedImageData::Blob,
                        &img.visible_rect,
                        Some(img.tile_size),
                    );
                }
                ResourceUpdate::UpdateBlobImage(img) => {
                    self.update_image_template(
                        img.key.as_image(),
                        img.descriptor,
                        CachedImageData::Blob,
                        &to_image_dirty_rect(
                            &img.dirty_rect
                        ),
                    );
                    self.discard_tiles_outside_visible_area(img.key, &img.visible_rect); // TODO: remove?
                    self.set_image_visible_rect(img.key.as_image(), &img.visible_rect);
                }
                ResourceUpdate::DeleteImage(img) => {
                    self.delete_image_template(img);
                    profile.set(profiler::IMAGE_TEMPLATES, self.resources.image_templates.images.len());
                    profile.set(profiler::IMAGE_TEMPLATES_MEM, bytes_to_mb(self.image_templates_memory));
                }
                ResourceUpdate::DeleteBlobImage(img) => {
                    self.delete_image_template(img.as_image());
                }
                ResourceUpdate::AddSnapshotImage(img) => {
                    let format = self.texture_cache.shared_color_expected_format();
                    self.add_image_template(
                        img.key.as_image(),
                        ImageDescriptor {
                            format,
                            // We'll know about the size when creating the render task.
                            size: DeviceIntSize::zero(),
                            stride: None,
                            offset: 0,
                            flags: ImageDescriptorFlags::empty(),
                        },
                        CachedImageData::Snapshot,
                        &DeviceIntRect::zero(),
                        None,
                    );
                }
                ResourceUpdate::DeleteSnapshotImage(img) => {
                    self.delete_image_template(img.as_image());
                }
                ResourceUpdate::DeleteFont(font) => {
                    if let Some(shared_key) = self.resources.fonts.font_keys.delete_key(&font) {
                        self.delete_font_template(shared_key);
                        if let Some(ref mut handler) = &mut self.blob_image_handler {
                            handler.delete_font(shared_key);
                        }
                        profile.set(profiler::FONT_TEMPLATES, self.resources.fonts.templates.len());
                        profile.set(profiler::FONT_TEMPLATES_MEM, bytes_to_mb(self.font_templates_memory));
                    }
                }
                ResourceUpdate::DeleteFontInstance(font) => {
                    if let Some(shared_key) = self.resources.fonts.instance_keys.delete_key(&font) {
                        self.delete_font_instance(shared_key);
                    }
                    if let Some(ref mut handler) = &mut self.blob_image_handler {
                        handler.delete_font_instance(font);
                    }
                }
                ResourceUpdate::SetBlobImageVisibleArea(key, area) => {
                    self.discard_tiles_outside_visible_area(key, &area);
                    self.set_image_visible_rect(key.as_image(), &area);
                }
                ResourceUpdate::AddFont(font) => {
                    // The shared key was already added in ApiResources, but the first time it is
                    // seen on the backend we still need to do some extra initialization here.
                    let (key, template) = match font {
                        AddFont::Raw(key, bytes, index) => {
                            (key, FontTemplate::Raw(bytes, index))
                        }
                        AddFont::Native(key, native_font_handle) => {
                            (key, FontTemplate::Native(native_font_handle))
                        }
                    };
                    let shared_key = self.resources.fonts.font_keys.map_key(&key);
                    if !self.glyph_rasterizer.has_font(shared_key) {
                        self.add_font_template(shared_key, template);
                        profile.set(profiler::FONT_TEMPLATES, self.resources.fonts.templates.len());
                        profile.set(profiler::FONT_TEMPLATES_MEM, bytes_to_mb(self.font_templates_memory));
                    }
                }
                ResourceUpdate::AddFontInstance(..) => {
                    // Already added in ApiResources.
                }
            }
        }
    }

    pub fn add_rasterized_blob_images(
        &mut self,
        images: Vec<(BlobImageRequest, BlobImageResult)>,
        profile: &mut TransactionProfile,
    ) {
        for (request, result) in images {
            let data = match result {
                Ok(data) => data,
                Err(..) => {
                    warn!("Failed to rasterize a blob image");
                    continue;
                }
            };

            profile.add(profiler::RASTERIZED_BLOBS_PX, data.rasterized_rect.area());

            // First make sure we have an entry for this key (using a placeholder
            // if need be).
            let tiles = self.rasterized_blob_images.entry(request.key).or_insert_with(
                || { RasterizedBlob::default() }
            );

            tiles.insert(request.tile, data);

            match self.cached_images.try_get_mut(&request.key.as_image()) {
                Some(&mut ImageResult::Multi(ref mut entries)) => {
                    let cached_key = CachedImageKey {
                        rendering: ImageRendering::Auto, // TODO(nical)
                        tile: Some(request.tile),
                    };
                    if let Some(entry) = entries.try_get_mut(&cached_key) {
                        entry.dirty_rect = DirtyRect::All;
                    }
                }
                _ => {}
            }
        }
    }

    pub fn add_font_template(&mut self, font_key: FontKey, template: FontTemplate) {
        // Push the new font to the font renderer, and also store
        // it locally for glyph metric requests.
        if let FontTemplate::Raw(ref data, _) = template {
            self.resources.weak_fonts.insert(Arc::downgrade(data));
            self.font_templates_memory += data.len();
        }
        self.glyph_rasterizer.add_font(font_key, template.clone());
        self.resources.fonts.templates.add_font(font_key, template);
    }

    pub fn delete_font_template(&mut self, font_key: FontKey) {
        self.glyph_rasterizer.delete_font(font_key);
        if let Some(FontTemplate::Raw(data, _)) = self.resources.fonts.templates.delete_font(&font_key) {
            self.font_templates_memory -= data.len();
        }
        self.cached_glyphs.delete_fonts(&[font_key]);
    }

    pub fn delete_font_instance(&mut self, instance_key: FontInstanceKey) {
        self.resources.fonts.instances.delete_font_instance(instance_key);
    }

    pub fn get_font_instance(&self, instance_key: FontInstanceKey) -> Option<Arc<BaseFontInstance>> {
        self.resources.fonts.instances.get_font_instance(instance_key)
    }

    pub fn get_fonts(&self) -> SharedFontResources {
        self.resources.fonts.clone()
    }

    pub fn add_image_template(
        &mut self,
        image_key: ImageKey,
        descriptor: ImageDescriptor,
        data: CachedImageData,
        visible_rect: &DeviceIntRect,
        mut tiling: Option<TileSize>,
    ) {
        if let Some(ref mut tile_size) = tiling {
            // Sanitize the value since it can be set by a pref.
            *tile_size = (*tile_size).max(16).min(2048);
        }

        if tiling.is_none() && Self::should_tile(self.tiling_threshold(), &descriptor, &data) {
            // We aren't going to be able to upload a texture this big, so tile it, even
            // if tiling was not requested.
            tiling = Some(DEFAULT_TILE_SIZE);
        }

        let resource = ImageResource {
            descriptor,
            data,
            tiling,
            visible_rect: *visible_rect,
            adjustment: AdjustedImageSource::new(),
            generation: ImageGeneration(0),
        };

        self.resources.image_templates.insert(image_key, resource);
    }

    pub fn update_image_template(
        &mut self,
        image_key: ImageKey,
        descriptor: ImageDescriptor,
        data: CachedImageData,
        dirty_rect: &ImageDirtyRect,
    ) {
        let tiling_threshold = self.tiling_threshold();
        let image = match self.resources.image_templates.get_mut(image_key) {
            Some(res) => res,
            None => panic!("Attempt to update non-existent image"),
        };

        let mut tiling = image.tiling;
        if tiling.is_none() && Self::should_tile(tiling_threshold, &descriptor, &data) {
            tiling = Some(DEFAULT_TILE_SIZE);
        }

        // Each cache entry stores its own copy of the image's dirty rect. This allows them to be
        // updated independently.
        match self.cached_images.try_get_mut(&image_key) {
            Some(&mut ImageResult::UntiledAuto(ref mut entry)) => {
                entry.dirty_rect = entry.dirty_rect.union(dirty_rect);
            }
            Some(&mut ImageResult::Multi(ref mut entries)) => {
                for (key, entry) in entries.iter_mut() {
                    // We want the dirty rect relative to the tile and not the whole image.
                    let local_dirty_rect = match (tiling, key.tile) {
                        (Some(tile_size), Some(tile)) => {
                            dirty_rect.map(|mut rect|{
                                let tile_offset = DeviceIntPoint::new(
                                    tile.x as i32,
                                    tile.y as i32,
                                ) * tile_size as i32;
                                rect = rect.translate(-tile_offset.to_vector());

                                let tile_rect = compute_tile_size(
                                    &descriptor.size.into(),
                                    tile_size,
                                    tile,
                                ).into();

                                rect.intersection(&tile_rect).unwrap_or_else(DeviceIntRect::zero)
                            })
                        }
                        (None, Some(..)) => DirtyRect::All,
                        _ => *dirty_rect,
                    };
                    entry.dirty_rect = entry.dirty_rect.union(&local_dirty_rect);
                }
            }
            _ => {}
        }

        if image.descriptor.format != descriptor.format {
            // could be a stronger warning/error?
            trace!("Format change {:?} -> {:?}", image.descriptor.format, descriptor.format);
        }
        *image = ImageResource {
            descriptor,
            data,
            tiling,
            visible_rect: descriptor.size.into(),
            adjustment: AdjustedImageSource::new(),
            generation: ImageGeneration(image.generation.0 + 1),
        };
    }

    pub fn increment_image_generation(&mut self, key: ImageKey) {
        if let Some(image) = self.resources.image_templates.get_mut(key) {
            image.generation.0 += 1;
        }
    }

    pub fn delete_image_template(&mut self, image_key: ImageKey) {
        // Remove the template.
        let value = self.resources.image_templates.remove(image_key);

        // Release the corresponding texture cache entry, if any.
        if let Some(mut cached) = self.cached_images.remove(&image_key) {
            cached.drop_from_cache(&mut self.texture_cache);
        }

        match value {
            Some(image) => if image.data.is_blob() {
                if let CachedImageData::Raw(data) = image.data {
                    self.image_templates_memory -= data.len();
                }

                let blob_key = BlobImageKey(image_key);
                self.deleted_blob_keys.back_mut().unwrap().push(blob_key);
                self.rasterized_blob_images.remove(&blob_key);
            },
            None => {
                warn!("Delete the non-exist key");
                debug!("key={:?}", image_key);
            }
        }
    }

    /// Return the current generation of an image template
    pub fn get_image_generation(&self, key: ImageKey) -> ImageGeneration {
        self.resources
            .image_templates
            .get(key)
            .map_or(ImageGeneration::INVALID, |template| template.generation)
    }

    /// Requests an image to ensure that it will be in the texture cache this frame.
    ///
    /// returns the size in device pixel of the image or tile.
    pub fn request_image(
        &mut self,
        mut request: ImageRequest,
        gpu_buffer: &mut GpuBufferBuilderF,
    ) -> DeviceIntSize {
        debug_assert_eq!(self.state, State::AddResources);

        let template = match self.resources.image_templates.get(request.key) {
            Some(template) => template,
            None => {
                warn!("ERROR: Trying to render deleted / non-existent key");
                debug!("key={:?}", request.key);
                return DeviceIntSize::zero();
            }
        };

        let size = match request.tile {
            Some(tile) => compute_tile_size(&template.visible_rect, template.tiling.unwrap(), tile),
            None => template.descriptor.size,
        };

        // Images that don't use the texture cache can early out.
        if !template.data.uses_texture_cache() {
            return size;
        }

        if template.data.is_snapshot() {
            // We only Support `Auto` for snapshots. This is because we have
            // to make the decision about the filtering mode earlier when
            // producing the snapshot.
            // See the comment at the top of `render_as_image`.
            request.rendering = ImageRendering::Auto;
        }

        let side_size =
            template.tiling.map_or(cmp::max(template.descriptor.size.width, template.descriptor.size.height),
                                   |tile_size| tile_size as i32);
        if side_size > self.texture_cache.max_texture_size() {
            // The image or tiling size is too big for hardware texture size.
            warn!("Dropping image, image:(w:{},h:{}, tile:{}) is too big for hardware!",
                  template.descriptor.size.width, template.descriptor.size.height, template.tiling.unwrap_or(0));
            self.cached_images.insert(request.key, ImageResult::Err(ImageCacheError::OverLimitSize));
            return DeviceIntSize::zero();
        }

        let storage = match self.cached_images.entry(request.key) {
            Occupied(e) => {
                // We might have an existing untiled entry, and need to insert
                // a second entry. In such cases we need to move the old entry
                // out first, replacing it with a dummy entry, and then creating
                // the tiled/multi-entry variant.
                let entry = e.into_mut();
                if !request.is_untiled_auto() {
                    let untiled_entry = match entry {
                        &mut ImageResult::UntiledAuto(ref mut entry) => {
                            Some(mem::replace(entry, CachedImageInfo {
                                texture_cache_handle: TextureCacheHandle::invalid(),
                                dirty_rect: DirtyRect::All,
                                manual_eviction: false,
                            }))
                        }
                        _ => None
                    };

                    if let Some(untiled_entry) = untiled_entry {
                        let mut entries = ResourceClassCache::new();
                        let untiled_key = CachedImageKey {
                            rendering: ImageRendering::Auto,
                            tile: None,
                        };
                        entries.insert(untiled_key, untiled_entry);
                        *entry = ImageResult::Multi(entries);
                    }
                }
                entry
            }
            Vacant(entry) => {
                entry.insert(if request.is_untiled_auto() {
                    ImageResult::UntiledAuto(CachedImageInfo {
                        texture_cache_handle: TextureCacheHandle::invalid(),
                        dirty_rect: DirtyRect::All,
                        manual_eviction: false,
                    })
                } else {
                    ImageResult::Multi(ResourceClassCache::new())
                })
            }
        };

        // If this image exists in the texture cache, *and* the dirty rect
        // in the cache is empty, then it is valid to use as-is.
        let entry = match *storage {
            ImageResult::UntiledAuto(ref mut entry) => entry,
            ImageResult::Multi(ref mut entries) => {
                entries.entry(request.into())
                    .or_insert(CachedImageInfo {
                        texture_cache_handle: TextureCacheHandle::invalid(),
                        dirty_rect: DirtyRect::All,
                        manual_eviction: false,
                    })
            },
            ImageResult::Err(_) => panic!("Errors should already have been handled"),
        };

        let needs_upload = self.texture_cache.request(&entry.texture_cache_handle, gpu_buffer);

        if !needs_upload && entry.dirty_rect.is_empty() {
            return size;
        }

        if !self.pending_image_requests.insert(request) {
            return size;
        }

        if template.data.is_blob() {
            let request: BlobImageRequest = request.into();
            let missing = match self.rasterized_blob_images.get(&request.key) {
                Some(tiles) => !tiles.contains_key(&request.tile),
                _ => true,
            };

            assert!(!missing);
        }

        size
    }

    fn discard_tiles_outside_visible_area(
        &mut self,
        key: BlobImageKey,
        area: &DeviceIntRect
    ) {
        let tile_size = match self.resources.image_templates.get(key.as_image()) {
            Some(template) => template.tiling.unwrap(),
            None => {
                //debug!("Missing image template (key={:?})!", key);
                return;
            }
        };

        let tiles = match self.rasterized_blob_images.get_mut(&key) {
            Some(tiles) => tiles,
            _ => { return; }
        };

        let tile_range = compute_tile_range(
            &area,
            tile_size,
        );

        tiles.retain(|tile, _| { tile_range.contains(*tile) });

        let texture_cache = &mut self.texture_cache;
        match self.cached_images.try_get_mut(&key.as_image()) {
            Some(&mut ImageResult::Multi(ref mut entries)) => {
                entries.retain(|key, entry| {
                    if key.tile.is_none() || tile_range.contains(key.tile.unwrap()) {
                        return true;
                    }
                    entry.mark_unused(texture_cache);
                    return false;
                });
            }
            _ => {}
        }
    }

    fn set_image_visible_rect(&mut self, key: ImageKey, rect: &DeviceIntRect) {
        if let Some(image) = self.resources.image_templates.get_mut(key) {
            image.visible_rect = *rect;
            image.descriptor.size = rect.size();
        }
    }

    pub fn request_glyphs(
        &mut self,
        mut font: FontInstance,
        glyph_keys: &[GlyphKey],
        gpu_buffer: &mut GpuBufferBuilderF,
    ) {
        debug_assert_eq!(self.state, State::AddResources);

        self.glyph_rasterizer.prepare_font(&mut font);
        let glyph_key_cache = self.cached_glyphs.insert_glyph_key_cache_for_font(&font);
        let texture_cache = &mut self.texture_cache;
        self.glyph_rasterizer.request_glyphs(
            font,
            glyph_keys,
            |key| {
                let cache_key = key.cache_key();
                if let Some(entry) = glyph_key_cache.try_get(&cache_key) {
                    match entry {
                        GlyphCacheEntry::Cached(ref glyph) => {
                            if !texture_cache.request(&glyph.texture_cache_handle, gpu_buffer) {
                                return false;
                            }
                            // This case gets hit when we already rasterized the glyph, but the
                            // glyph has been evicted from the texture cache. Just force it to
                            // pending so it gets rematerialized.
                        }
                        // Otherwise, skip the entry if it is blank or pending.
                        GlyphCacheEntry::Blank | GlyphCacheEntry::Pending => return false,
                    }
                };

                glyph_key_cache.add_glyph(cache_key, GlyphCacheEntry::Pending);

                true
            }
        );
    }

    pub fn pending_updates(&mut self) -> ResourceUpdateList {
        ResourceUpdateList {
            texture_updates: self.texture_cache.pending_updates(),
            native_surface_updates: mem::replace(&mut self.pending_native_surface_updates, Vec::new()),
        }
    }

    pub fn fetch_glyphs<F>(
        &self,
        mut font: FontInstance,
        glyph_keys: &[GlyphKey],
        gpu_buffer: &GpuBufferBuilderF,
        fetch_buffer: &mut Vec<GlyphFetchResult>,
        mut f: F,
    ) where
        F: FnMut(TextureSource, GlyphFormat, &[GlyphFetchResult]),
    {
        debug_assert_eq!(self.state, State::QueryResources);

        self.glyph_rasterizer.prepare_font(&mut font);
        let glyph_key_cache = self.cached_glyphs.get_glyph_key_cache_for_font(&font);

        let mut current_texture_id = TextureSource::Invalid;
        let mut current_glyph_format = GlyphFormat::Subpixel;
        debug_assert!(fetch_buffer.is_empty());

        for (loop_index, key) in glyph_keys.iter().enumerate() {
            let cache_key = key.cache_key();
            let (cache_item, glyph_format, is_packed_glyph) = match *glyph_key_cache.get(&cache_key) {
                GlyphCacheEntry::Cached(ref glyph) => {
                    (self.texture_cache.get(&glyph.texture_cache_handle), glyph.format, glyph.is_packed_glyph)
                }
                GlyphCacheEntry::Blank | GlyphCacheEntry::Pending => continue,
            };
            if current_texture_id != cache_item.texture_id ||
                current_glyph_format != glyph_format {
                if !fetch_buffer.is_empty() {
                    f(current_texture_id, current_glyph_format, fetch_buffer);
                    fetch_buffer.clear();
                }
                current_texture_id = cache_item.texture_id;
                current_glyph_format = glyph_format;
            }
            let (subpx_offset_x, subpx_offset_y) = key.subpixel_offset();
            fetch_buffer.push(GlyphFetchResult {
                index_in_text_run: loop_index as i32,
                uv_rect_address: gpu_buffer.resolve_handle(cache_item.uv_rect_handle),
                offset: DevicePoint::new(cache_item.user_data[0], cache_item.user_data[1]),
                size: cache_item.uv_rect.size(),
                scale: cache_item.user_data[2],
                subpx_offset_x: subpx_offset_x as u8,
                subpx_offset_y: subpx_offset_y as u8,
                is_packed_glyph,
            });
        }

        if !fetch_buffer.is_empty() {
            f(current_texture_id, current_glyph_format, fetch_buffer);
            fetch_buffer.clear();
        }
    }

    pub fn map_font_key(&self, key: FontKey) -> FontKey {
        self.resources.fonts.font_keys.map_key(&key)
    }

    pub fn map_font_instance_key(&self, key: FontInstanceKey) -> FontInstanceKey {
        self.resources.fonts.instance_keys.map_key(&key)
    }

    pub fn get_glyph_dimensions(
        &mut self,
        font: &FontInstance,
        glyph_index: GlyphIndex,
    ) -> Option<GlyphDimensions> {
        match self.cached_glyph_dimensions.entry((font.instance_key, glyph_index)) {
            Occupied(entry) => *entry.get(),
            Vacant(entry) => *entry.insert(
                self.glyph_rasterizer
                    .get_glyph_dimensions(font, glyph_index),
            ),
        }
    }

    pub fn get_glyph_index(&mut self, font_key: FontKey, ch: char) -> Option<u32> {
        self.glyph_rasterizer.get_glyph_index(font_key, ch)
    }

    #[inline]
    pub fn get_cached_image(&self, request: ImageRequest) -> Result<CacheItem, ()> {
        debug_assert_eq!(self.state, State::QueryResources);
        let image_info = self.get_image_info(request)?;

        if let Ok(item) = self.get_texture_cache_item(&image_info.texture_cache_handle) {
            // Common path.
            return Ok(item);
        }

        if self.resources.image_templates
            .get(request.key)
            .map_or(false, |img| img.data.is_snapshot()) {
            if self.debug_fallback_panic {
                panic!("Missing snapshot image");
            }
            return self.get_texture_cache_item(&self.fallback_handle);
        }

        panic!("Requested image missing from the texture cache");
    }

    pub fn get_cached_render_task(
        &self,
        handle: &RenderTaskCacheEntryHandle,
    ) -> &RenderTaskCacheEntry {
        self.cached_render_tasks.get_cache_entry(handle)
    }

    #[inline]
    fn get_image_info(&self, request: ImageRequest) -> Result<&CachedImageInfo, ()> {
        // TODO(Jerry): add a debug option to visualize the corresponding area for
        // the Err() case of CacheItem.
        match *self.cached_images.get(&request.key) {
            ImageResult::UntiledAuto(ref image_info) => Ok(image_info),
            ImageResult::Multi(ref entries) => Ok(entries.get(&request.into())),
            ImageResult::Err(_) => Err(()),
        }
    }

    #[inline]
    pub fn get_texture_cache_item(&self, handle: &TextureCacheHandle) -> Result<CacheItem, ()> {
        if let Some(item) = self.texture_cache.try_get(handle) {
            return Ok(item);
        }

        Err(())
    }

    pub fn get_image_properties(&self, image_key: ImageKey) -> Option<ImageProperties> {
        let image_template = &self.resources.image_templates.get(image_key);

        image_template.map(|image_template| {
            let external_image = match image_template.data {
                CachedImageData::External(ext_image) => match ext_image.image_type {
                    ExternalImageType::TextureHandle(_) => Some(ext_image),
                    // external buffer uses resource_cache.
                    ExternalImageType::Buffer => None,
                },
                // raw and blob image are all using resource_cache.
                CachedImageData::Raw(..)
                | CachedImageData::Blob
                | CachedImageData::Snapshot
                 => None,
            };

            ImageProperties {
                descriptor: image_template.descriptor,
                external_image,
                tiling: image_template.tiling,
                visible_rect: image_template.visible_rect,
                adjustment: image_template.adjustment,
            }
        })
    }

    pub fn begin_frame(&mut self, stamp: FrameStamp, profile: &mut TransactionProfile) {
        profile_scope!("begin_frame");
        debug_assert_eq!(self.state, State::Idle);
        self.state = State::AddResources;
        self.texture_cache.begin_frame(stamp, profile);
        self.picture_textures.begin_frame(stamp, &mut self.texture_cache.pending_updates);

        self.cached_glyphs.begin_frame(
            stamp,
            &mut self.texture_cache,
            &mut self.glyph_rasterizer,
        );
        self.cached_render_tasks.begin_frame(&mut self.texture_cache);
        self.current_frame_id = stamp.frame_id();

        // Pop the old frame and push a new one.
        // Recycle the allocation if any.
        let mut v = self.deleted_blob_keys.pop_front().unwrap_or_else(Vec::new);
        v.clear();
        self.deleted_blob_keys.push_back(v);

        self.texture_cache.run_compaction();
    }

    pub fn block_until_all_resources_added(
        &mut self,
        gpu_buffer: &mut GpuBufferBuilder,
        profile: &mut TransactionProfile,
    ) {
        profile_scope!("block_until_all_resources_added");

        debug_assert_eq!(self.state, State::AddResources);
        self.state = State::QueryResources;

        let cached_glyphs = &mut self.cached_glyphs;
        let texture_cache = &mut self.texture_cache;

        self.glyph_rasterizer.resolve_glyphs(
            |job, can_use_r8_format| {
                let GlyphRasterJob { font, key, result } = job;
                let cache_key = key.cache_key();
                let glyph_key_cache = cached_glyphs.get_glyph_key_cache_for_font_mut(&*font);
                let glyph_info = match result {
                    Err(_) => GlyphCacheEntry::Blank,
                    Ok(ref glyph) if glyph.width == 0 || glyph.height == 0 => {
                        GlyphCacheEntry::Blank
                    }
                    Ok(glyph) => {
                        let mut texture_cache_handle = TextureCacheHandle::invalid();
                        texture_cache.request(&texture_cache_handle, &mut gpu_buffer.f32);
                        texture_cache.update(
                            &mut texture_cache_handle,
                            ImageDescriptor {
                                size: size2(glyph.width, glyph.height),
                                stride: None,
                                format: glyph.format.image_format(can_use_r8_format),
                                flags: ImageDescriptorFlags::empty(),
                                offset: 0,
                            },
                            TextureFilter::Linear,
                            Some(CachedImageData::Raw(Arc::new(glyph.bytes))),
                            [glyph.left, -glyph.top, glyph.scale, 0.0],
                            DirtyRect::All,
                            &mut gpu_buffer.f32,
                            Some(glyph_key_cache.eviction_notice()),
                            UvRectKind::Rect,
                            Eviction::Auto,
                            TargetShader::Text,
                            false,
                        );
                        GlyphCacheEntry::Cached(CachedGlyphInfo {
                            texture_cache_handle,
                            format: glyph.format,
                            is_packed_glyph: glyph.is_packed_glyph,
                        })
                    }
                };
                glyph_key_cache.insert(cache_key, glyph_info);
            },
            profile,
        );

        // Apply any updates of new / updated images (incl. blobs) to the texture cache.
        self.update_texture_cache(gpu_buffer);
    }

    fn update_texture_cache(&mut self, gpu_buffer: &mut GpuBufferBuilder) {
        profile_scope!("update_texture_cache");

        if self.fallback_handle == TextureCacheHandle::invalid() {
            let fallback_color = if self.debug_fallback_pink {
                vec![255, 0, 255, 255]
            } else {
                vec![0, 0, 0, 0]
            };
            self.texture_cache.update(
                &mut self.fallback_handle,
                ImageDescriptor {
                    size: size2(1, 1),
                    stride: None,
                    format: ImageFormat::BGRA8,
                    flags: ImageDescriptorFlags::empty(),
                    offset: 0,
                },
                TextureFilter::Linear,
                Some(CachedImageData::Raw(Arc::new(fallback_color))),
                [0.0; 4],
                DirtyRect::All,
                &mut gpu_buffer.f32,
                None,
                UvRectKind::Rect,
                Eviction::Manual,
                TargetShader::Default,
                false,
            );
        }

        for request in self.pending_image_requests.drain() {
            let image_template = self.resources.image_templates.get_mut(request.key).unwrap();
            debug_assert!(image_template.data.uses_texture_cache());

            let mut updates: SmallVec<[(CachedImageData, Option<DeviceIntRect>); 1]> = SmallVec::new();

            match image_template.data {
                CachedImageData::Snapshot => {
                    // The update is done in ResourceCache::render_as_image.
                }
                CachedImageData::Raw(..)
                | CachedImageData::External(..) => {
                    // Safe to clone here since the Raw image data is an
                    // Arc, and the external image data is small.
                    updates.push((image_template.data.clone(), None));
                }
                CachedImageData::Blob => {
                    let blob_image = self.rasterized_blob_images.get_mut(&BlobImageKey(request.key)).unwrap();
                    let img = &blob_image[&request.tile.unwrap()];
                    updates.push((
                        CachedImageData::Raw(Arc::clone(&img.data)),
                        Some(img.rasterized_rect)
                    ));
                }
            };

            for (image_data, blob_rasterized_rect) in updates {
                let entry = match *self.cached_images.get_mut(&request.key) {
                    ImageResult::UntiledAuto(ref mut entry) => entry,
                    ImageResult::Multi(ref mut entries) => entries.get_mut(&request.into()),
                    ImageResult::Err(_) => panic!("Update requested for invalid entry")
                };

                let mut descriptor = image_template.descriptor.clone();
                let mut dirty_rect = entry.dirty_rect.replace_with_empty();

                if let Some(tile) = request.tile {
                    let tile_size = image_template.tiling.unwrap();
                    let clipped_tile_size = compute_tile_size(&image_template.visible_rect, tile_size, tile);
                    // The tiled image could be stored on the CPU as one large image or be
                    // already broken up into tiles. This affects the way we compute the stride
                    // and offset.
                    let tiled_on_cpu = image_template.data.is_blob();
                    if !tiled_on_cpu {
                        // we don't expect to have partial tiles at the top and left of non-blob
                        // images.
                        debug_assert_eq!(image_template.visible_rect.min, point2(0, 0));
                        let bpp = descriptor.format.bytes_per_pixel();
                        let stride = descriptor.compute_stride();
                        descriptor.stride = Some(stride);
                        descriptor.offset +=
                            tile.y as i32 * tile_size as i32 * stride +
                            tile.x as i32 * tile_size as i32 * bpp;
                    }

                    descriptor.size = clipped_tile_size;
                }

                // If we are uploading the dirty region of a blob image we might have several
                // rects to upload so we use each of these rasterized rects rather than the
                // overall dirty rect of the image.
                if let Some(rect) = blob_rasterized_rect {
                    dirty_rect = DirtyRect::Partial(rect);
                }

                let filter = match request.rendering {
                    ImageRendering::Pixelated => {
                        TextureFilter::Nearest
                    }
                    ImageRendering::Auto | ImageRendering::CrispEdges => {
                        // If the texture uses linear filtering, enable mipmaps and
                        // trilinear filtering, for better image quality. We only
                        // support this for now on textures that are not placed
                        // into the shared cache. This accounts for any image
                        // that is > 512 in either dimension, so it should cover
                        // the most important use cases. We may want to support
                        // mip-maps on shared cache items in the future.
                        if descriptor.allow_mipmaps() &&
                           descriptor.size.width > 512 &&
                           descriptor.size.height > 512 &&
                           !self.texture_cache.is_allowed_in_shared_cache(
                            TextureFilter::Linear,
                            &descriptor,
                        ) {
                            TextureFilter::Trilinear
                        } else {
                            TextureFilter::Linear
                        }
                    }
                };

                let eviction = match &image_template.data {
                    CachedImageData::Blob | CachedImageData::Snapshot => {
                        entry.manual_eviction = true;
                        Eviction::Manual
                    }
                    _ => {
                        Eviction::Auto
                    }
                };

                //Note: at this point, the dirty rectangle is local to the descriptor space
                self.texture_cache.update(
                    &mut entry.texture_cache_handle,
                    descriptor,
                    filter,
                    Some(image_data),
                    [0.0; 4],
                    dirty_rect,
                    &mut gpu_buffer.f32,
                    None,
                    UvRectKind::Rect,
                    eviction,
                    TargetShader::Default,
                    false,
                );
            }
        }
    }

    pub fn create_compositor_backdrop_surface(
        &mut self,
        color: ColorF
    ) -> NativeSurfaceId {
        let id = NativeSurfaceId(NEXT_NATIVE_SURFACE_ID.fetch_add(1, Ordering::Relaxed) as u64);

        self.pending_native_surface_updates.push(
            NativeSurfaceOperation {
                details: NativeSurfaceOperationDetails::CreateBackdropSurface {
                    id,
                    color,
                },
            }
        );

        id
    }

    /// Queue up allocation of a new OS native compositor surface with the
    /// specified tile size.
    pub fn create_compositor_surface(
        &mut self,
        virtual_offset: DeviceIntPoint,
        tile_size: DeviceIntSize,
        is_opaque: bool,
    ) -> NativeSurfaceId {
        let id = NativeSurfaceId(NEXT_NATIVE_SURFACE_ID.fetch_add(1, Ordering::Relaxed) as u64);

        self.pending_native_surface_updates.push(
            NativeSurfaceOperation {
                details: NativeSurfaceOperationDetails::CreateSurface {
                    id,
                    virtual_offset,
                    tile_size,
                    is_opaque,
                },
            }
        );

        id
    }

    pub fn create_compositor_external_surface(
        &mut self,
        is_opaque: bool,
    ) -> NativeSurfaceId {
        let id = NativeSurfaceId(NEXT_NATIVE_SURFACE_ID.fetch_add(1, Ordering::Relaxed) as u64);

        self.pending_native_surface_updates.push(
            NativeSurfaceOperation {
                details: NativeSurfaceOperationDetails::CreateExternalSurface {
                    id,
                    is_opaque,
                },
            }
        );

        id
    }

    /// Queue up destruction of an existing native OS surface. This is used when
    /// a picture cache surface is dropped or resized.
    pub fn destroy_compositor_surface(
        &mut self,
        id: NativeSurfaceId,
    ) {
        self.pending_native_surface_updates.push(
            NativeSurfaceOperation {
                details: NativeSurfaceOperationDetails::DestroySurface {
                    id,
                }
            }
        );
    }

    /// Queue construction of a native compositor tile on a given surface.
    pub fn create_compositor_tile(
        &mut self,
        id: NativeTileId,
    ) {
        self.pending_native_surface_updates.push(
            NativeSurfaceOperation {
                details: NativeSurfaceOperationDetails::CreateTile {
                    id,
                },
            }
        );
    }

    /// Queue destruction of a native compositor tile.
    pub fn destroy_compositor_tile(
        &mut self,
        id: NativeTileId,
    ) {
        self.pending_native_surface_updates.push(
            NativeSurfaceOperation {
                details: NativeSurfaceOperationDetails::DestroyTile {
                    id,
                },
            }
        );
    }

    pub fn attach_compositor_external_image(
        &mut self,
        id: NativeSurfaceId,
        external_image: ExternalImageId,
    ) {
        self.pending_native_surface_updates.push(
            NativeSurfaceOperation {
                details: NativeSurfaceOperationDetails::AttachExternalImage {
                    id,
                    external_image,
                },
            }
        );
    }


    pub fn end_frame(&mut self, profile: &mut TransactionProfile) {
        debug_assert_eq!(self.state, State::QueryResources);
        profile_scope!("end_frame");
        self.state = State::Idle;

        // GC the render target pool, if it's currently > 64 MB in size.
        //
        // We use a simple scheme whereby we drop any texture that hasn't been used
        // in the last 60 frames, until we are below the size threshold. This should
        // generally prevent any sustained build-up of unused textures, unless we don't
        // generate frames for a long period. This can happen when the window is
        // minimized, and we probably want to flush all the WebRender caches in that case [1].
        // There is also a second "red line" memory threshold which prevents
        // memory exhaustion if many render targets are allocated within a small
        // number of frames. For now this is set at 320 MB (10x the normal memory threshold).
        //
        // [1] https://bugzilla.mozilla.org/show_bug.cgi?id=1494099
        self.gc_render_targets(
            64 * 1024 * 1024,
            32 * 1024 * 1024 * 10,
            60,
        );

        self.texture_cache.end_frame(profile);
        self.picture_textures.gc(
            &mut self.texture_cache.pending_updates,
        );

        self.picture_textures.update_profile(profile);
    }

    pub fn set_debug_flags(&mut self, flags: DebugFlags) {
        GLYPH_FLASHING.store(flags.contains(DebugFlags::GLYPH_FLASHING), std::sync::atomic::Ordering::Relaxed);
        self.texture_cache.set_debug_flags(flags);
        self.picture_textures.set_debug_flags(flags);
        self.debug_fallback_panic = flags.contains(DebugFlags::MISSING_SNAPSHOT_PANIC);
        let fallback_pink = flags.contains(DebugFlags::MISSING_SNAPSHOT_PINK);

        if fallback_pink != self.debug_fallback_pink && self.fallback_handle != TextureCacheHandle::invalid() {
            self.texture_cache.evict_handle(&self.fallback_handle);
        }
        self.debug_fallback_pink = fallback_pink;
    }

    pub fn clear(&mut self, what: ClearCache) {
        if what.contains(ClearCache::IMAGES) {
            for (_key, mut cached) in self.cached_images.resources.drain() {
                cached.drop_from_cache(&mut self.texture_cache);
            }
        }
        if what.contains(ClearCache::GLYPHS) {
            self.cached_glyphs.clear();
        }
        if what.contains(ClearCache::GLYPH_DIMENSIONS) {
            self.cached_glyph_dimensions.clear();
        }
        if what.contains(ClearCache::RENDER_TASKS) {
            self.cached_render_tasks.clear();
        }
        if what.contains(ClearCache::TEXTURE_CACHE) {
            self.texture_cache.clear_all();
            self.picture_textures.clear(&mut self.texture_cache.pending_updates);
        }
        if what.contains(ClearCache::RENDER_TARGETS) {
            self.clear_render_target_pool();
        }
    }

    pub fn clear_namespace(&mut self, namespace: IdNamespace) {
        self.clear_images(|k| k.0 == namespace);

        // First clear out any non-shared resources associated with the namespace.
        self.resources.fonts.instances.clear_namespace(namespace);
        let deleted_keys = self.resources.fonts.templates.clear_namespace(namespace);
        self.glyph_rasterizer.delete_fonts(&deleted_keys);
        self.cached_glyphs.clear_namespace(namespace);
        if let Some(handler) = &mut self.blob_image_handler {
            handler.clear_namespace(namespace);
        }

        // Check for any shared instance keys that were remapped from the namespace.
        let shared_instance_keys = self.resources.fonts.instance_keys.clear_namespace(namespace);
        if !shared_instance_keys.is_empty() {
            self.resources.fonts.instances.delete_font_instances(&shared_instance_keys);
            self.cached_glyphs.delete_font_instances(&shared_instance_keys, &mut self.glyph_rasterizer);
            // Blob font instances are not shared across namespaces, so there is no
            // need to call the handler for them individually.
        }

        // Finally check for any shared font keys that were remapped from the namespace.
        let shared_keys = self.resources.fonts.font_keys.clear_namespace(namespace);
        if !shared_keys.is_empty() {
            self.glyph_rasterizer.delete_fonts(&shared_keys);
            self.resources.fonts.templates.delete_fonts(&shared_keys);
            self.cached_glyphs.delete_fonts(&shared_keys);
            if let Some(handler) = &mut self.blob_image_handler {
                for &key in &shared_keys {
                    handler.delete_font(key);
                }
            }
        }
    }

    /// Reports the CPU heap usage of this ResourceCache.
    ///
    /// NB: It would be much better to use the derive(MallocSizeOf) machinery
    /// here, but the Arcs complicate things. The two ways to handle that would
    /// be to either (a) Implement MallocSizeOf manually for the things that own
    /// them and manually avoid double-counting, or (b) Use the "seen this pointer
    /// yet" machinery from the proper malloc_size_of crate. We can do this if/when
    /// more accurate memory reporting on these resources becomes a priority.
    pub fn report_memory(&self, op: VoidPtrToSizeFn) -> MemoryReport {
        let mut report = MemoryReport::default();

        let mut seen_fonts = std::collections::HashSet::new();
        // Measure fonts. We only need the templates here, because the instances
        // don't have big buffers.
        for (_, font) in self.resources.fonts.templates.lock().iter() {
            if let FontTemplate::Raw(ref raw, _) = font {
                report.fonts += unsafe { op(raw.as_ptr() as *const c_void) };
                seen_fonts.insert(raw.as_ptr());
            }
        }

        for font in self.resources.weak_fonts.iter() {
            if !seen_fonts.contains(&font.as_ptr()) {
                report.weak_fonts += unsafe { op(font.as_ptr() as *const c_void) };
            }
        }

        // Measure images.
        for (_, image) in self.resources.image_templates.images.iter() {
            report.images += match image.data {
                CachedImageData::Raw(ref v) => unsafe { op(v.as_ptr() as *const c_void) },
                CachedImageData::Blob
                | CachedImageData::External(..)
                | CachedImageData::Snapshot => 0,
            }
        }

        // Mesure rasterized blobs.
        // TODO(gw): Temporarily disabled while we roll back a crash. We can re-enable
        //           these when that crash is fixed.
        /*
        for (_, image) in self.rasterized_blob_images.iter() {
            let mut accumulate = |b: &RasterizedBlobImage| {
                report.rasterized_blobs += unsafe { op(b.data.as_ptr() as *const c_void) };
            };
            match image {
                RasterizedBlob::Tiled(map) => map.values().for_each(&mut accumulate),
                RasterizedBlob::NonTiled(vec) => vec.iter().for_each(&mut accumulate),
            };
        }
        */

        report
    }

    /// Properly deletes all images matching the predicate.
    fn clear_images<F: Fn(&ImageKey) -> bool>(&mut self, f: F) {
        let keys = self.resources.image_templates.images.keys().filter(|k| f(*k))
            .cloned().collect::<SmallVec<[ImageKey; 16]>>();

        for key in keys {
            self.delete_image_template(key);
        }

        #[cfg(feature="leak_checks")]
        let check_leaks = true;
        #[cfg(not(feature="leak_checks"))]
        let check_leaks = false;

        if check_leaks {
            let blob_f = |key: &BlobImageKey| { f(&key.as_image()) };
            assert!(!self.resources.image_templates.images.keys().any(&f));
            assert!(!self.cached_images.resources.keys().any(&f));
            assert!(!self.rasterized_blob_images.keys().any(&blob_f));
        }
    }

    /// Get a render target from the pool, or allocate a new one if none are
    /// currently available that match the requested parameters.
    pub fn get_or_create_render_target_from_pool(
        &mut self,
        size: DeviceIntSize,
        format: ImageFormat,
    ) -> CacheTextureId {
        for target in &mut self.render_target_pool {
            if target.size == size &&
               target.format == format &&
               !target.is_active {
                // Found a target that's not currently in use which matches. Update
                // the last_frame_used for GC purposes.
                target.is_active = true;
                target.last_frame_used = self.current_frame_id;
                return target.texture_id;
            }
        }

        // Need to create a new render target and add it to the pool

        let texture_id = self.texture_cache.alloc_render_target(
            size,
            format,
        );

        self.render_target_pool.push(RenderTarget {
            size,
            format,
            texture_id,
            is_active: true,
            last_frame_used: self.current_frame_id,
        });

        texture_id
    }

    /// Return a render target to the pool.
    pub fn return_render_target_to_pool(
        &mut self,
        id: CacheTextureId,
    ) {
        let target = self.render_target_pool
            .iter_mut()
            .find(|t| t.texture_id == id)
            .expect("bug: invalid render target id");

        assert!(target.is_active);
        target.is_active = false;
    }

    /// Clear all current render targets (e.g. on memory pressure)
    fn clear_render_target_pool(
        &mut self,
    ) {
        for target in self.render_target_pool.drain(..) {
            debug_assert!(!target.is_active);
            self.texture_cache.free_render_target(target.texture_id);
        }
    }

    /// Garbage collect and remove old render targets from the pool that haven't
    /// been used for some time.
    fn gc_render_targets(
        &mut self,
        total_bytes_threshold: usize,
        total_bytes_red_line_threshold: usize,
        frames_threshold: u64,
    ) {
        // Get the total GPU memory size used by the current render target pool
        let mut rt_pool_size_in_bytes: usize = self.render_target_pool
            .iter()
            .map(|t| t.size_in_bytes())
            .sum();

        // If the total size of the pool is less than the threshold, don't bother
        // trying to GC any targets
        if rt_pool_size_in_bytes <= total_bytes_threshold {
            return;
        }

        // Sort the current pool by age, so that we remove oldest textures first
        self.render_target_pool.sort_by_key(|t| t.last_frame_used);

        // We can't just use retain() because `RenderTarget` requires manual cleanup.
        let mut retained_targets = SmallVec::<[RenderTarget; 8]>::new();

        for target in self.render_target_pool.drain(..) {
            assert!(!target.is_active);

            // Drop oldest textures until we are under the allowed size threshold.
            // However, if it's been used in very recently, it is always kept around,
            // which ensures we don't thrash texture allocations on pages that do
            // require a very large render target pool and are regularly changing.
            let above_red_line = rt_pool_size_in_bytes > total_bytes_red_line_threshold;
            let above_threshold = rt_pool_size_in_bytes > total_bytes_threshold;
            let used_recently = target.used_recently(self.current_frame_id, frames_threshold);
            let used_this_frame = target.last_frame_used == self.current_frame_id;

            if !used_this_frame && (above_red_line || (above_threshold && !used_recently)) {
                rt_pool_size_in_bytes -= target.size_in_bytes();
                self.texture_cache.free_render_target(target.texture_id);
            } else {
                retained_targets.push(target);
            }
        }

        self.render_target_pool.extend(retained_targets);
    }

    #[cfg(test)]
    pub fn validate_surfaces(
        &self,
        expected_surfaces: &[(i32, i32, ImageFormat)],
    ) {
        assert_eq!(expected_surfaces.len(), self.render_target_pool.len());

        for (expected, surface) in expected_surfaces.iter().zip(self.render_target_pool.iter()) {
            assert_eq!(DeviceIntSize::new(expected.0, expected.1), surface.size);
            assert_eq!(expected.2, surface.format);
        }
    }
}

impl Drop for ResourceCache {
    fn drop(&mut self) {
        self.clear_images(|_| true);
    }
}

#[cfg(any(feature = "capture", feature = "replay"))]
#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
struct PlainFontTemplate {
    data: String,
    index: u32,
}

#[cfg(any(feature = "capture", feature = "replay"))]
#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
struct PlainImageTemplate {
    data: String,
    descriptor: ImageDescriptor,
    tiling: Option<TileSize>,
    generation: ImageGeneration,
}

#[cfg(any(feature = "capture", feature = "replay"))]
#[cfg_attr(feature = "capture", derive(Serialize))]
#[cfg_attr(feature = "replay", derive(Deserialize))]
pub struct PlainResources {
    font_templates: FastHashMap<FontKey, PlainFontTemplate>,
    font_instances: Vec<BaseFontInstance>,
    image_templates: FastHashMap<ImageKey, PlainImageTemplate>,
}

#[cfg(feature = "capture")]
#[derive(Serialize)]
pub struct PlainCacheRef<'a> {
    current_frame_id: FrameId,
    glyphs: &'a GlyphCache,
    glyph_dimensions: &'a GlyphDimensionsCache,
    images: &'a ImageCache,
    render_tasks: &'a RenderTaskCache,
    textures: &'a TextureCache,
    picture_textures: &'a PictureTextures,
}

#[cfg(feature = "replay")]
#[derive(Deserialize)]
pub struct PlainCacheOwn {
    current_frame_id: FrameId,
    glyphs: GlyphCache,
    glyph_dimensions: GlyphDimensionsCache,
    images: ImageCache,
    render_tasks: RenderTaskCache,
    textures: TextureCache,
    picture_textures: PictureTextures,
}

#[cfg(feature = "replay")]
const NATIVE_FONT: &'static [u8] = include_bytes!("../res/Proggy.ttf");

// This currently only casts the unit but will soon apply an offset
fn to_image_dirty_rect(blob_dirty_rect: &BlobDirtyRect) -> ImageDirtyRect {
    match *blob_dirty_rect {
        DirtyRect::Partial(rect) => DirtyRect::Partial(rect.cast_unit()),
        DirtyRect::All => DirtyRect::All,
    }
}

impl ResourceCache {
    #[cfg(feature = "capture")]
    pub fn save_capture(
        &mut self, root: &PathBuf
    ) -> (PlainResources, Vec<ExternalCaptureImage>) {
        use std::fs;
        use std::io::Write;

        info!("saving resource cache");
        let res = &self.resources;
        let path_fonts = root.join("fonts");
        if !path_fonts.is_dir() {
            fs::create_dir(&path_fonts).unwrap();
        }
        let path_images = root.join("images");
        if !path_images.is_dir() {
            fs::create_dir(&path_images).unwrap();
        }
        let path_blobs = root.join("blobs");
        if !path_blobs.is_dir() {
            fs::create_dir(&path_blobs).unwrap();
        }
        let path_externals = root.join("externals");
        if !path_externals.is_dir() {
            fs::create_dir(&path_externals).unwrap();
        }

        info!("\tfont templates");
        let mut font_paths = FastHashMap::default();
        for template in res.fonts.templates.lock().values() {
            let data: &[u8] = match *template {
                FontTemplate::Raw(ref arc, _) => arc,
                FontTemplate::Native(_) => continue,
            };
            let font_id = res.fonts.templates.len() + 1;
            let entry = match font_paths.entry(data.as_ptr()) {
                Entry::Occupied(_) => continue,
                Entry::Vacant(e) => e,
            };
            let file_name = format!("{}.raw", font_id);
            let short_path = format!("fonts/{}", file_name);
            fs::File::create(path_fonts.join(file_name))
                .expect(&format!("Unable to create {}", short_path))
                .write_all(data)
                .unwrap();
            entry.insert(short_path);
        }

        info!("\timage templates");
        let mut image_paths = FastHashMap::default();
        let mut other_paths = FastHashMap::default();
        let mut num_blobs = 0;
        let mut external_images = Vec::new();
        for (&key, template) in res.image_templates.images.iter() {
            let desc = &template.descriptor;
            match template.data {
                CachedImageData::Raw(ref arc) => {
                    let image_id = image_paths.len() + 1;
                    let entry = match image_paths.entry(arc.as_ptr()) {
                        Entry::Occupied(_) => continue,
                        Entry::Vacant(e) => e,
                    };

                    #[cfg(feature = "png")]
                    CaptureConfig::save_png(
                        root.join(format!("images/{}.png", image_id)),
                        desc.size,
                        desc.format,
                        desc.stride,
                        &arc,
                    );
                    let file_name = format!("{}.raw", image_id);
                    let short_path = format!("images/{}", file_name);
                    fs::File::create(path_images.join(file_name))
                        .expect(&format!("Unable to create {}", short_path))
                        .write_all(&*arc)
                        .unwrap();
                    entry.insert(short_path);
                }
                CachedImageData::Blob => {
                    warn!("Tiled blob images aren't supported yet");
                    let result = RasterizedBlobImage {
                        rasterized_rect: desc.size.into(),
                        data: Arc::new(vec![0; desc.compute_total_size() as usize])
                    };

                    assert_eq!(result.rasterized_rect.size(), desc.size);
                    assert_eq!(result.data.len(), desc.compute_total_size() as usize);

                    num_blobs += 1;
                    #[cfg(feature = "png")]
                    CaptureConfig::save_png(
                        root.join(format!("blobs/{}.png", num_blobs)),
                        desc.size,
                        desc.format,
                        desc.stride,
                        &result.data,
                    );
                    let file_name = format!("{}.raw", num_blobs);
                    let short_path = format!("blobs/{}", file_name);
                    let full_path = path_blobs.clone().join(&file_name);
                    fs::File::create(full_path)
                        .expect(&format!("Unable to create {}", short_path))
                        .write_all(&result.data)
                        .unwrap();
                    other_paths.insert(key, short_path);
                }
                CachedImageData::Snapshot => {
                    let short_path = format!("snapshots/{}", external_images.len() + 1);
                    other_paths.insert(key, short_path.clone());
                }
                CachedImageData::External(ref ext) => {
                    let short_path = format!("externals/{}", external_images.len() + 1);
                    other_paths.insert(key, short_path.clone());
                    external_images.push(ExternalCaptureImage {
                        short_path,
                        descriptor: desc.clone(),
                        external: ext.clone(),
                    });
                }
            }
        }

        let mut font_templates = FastHashMap::default();
        let mut font_remap = FastHashMap::default();
        // Generate a map from duplicate font keys to their template.
        for key in res.fonts.font_keys.keys() {
            let shared_key = res.fonts.font_keys.map_key(&key);
            let template = match res.fonts.templates.get_font(&shared_key) {
                Some(template) => template,
                None => {
                    debug!("Failed serializing font template {:?}", key);
                    continue;
                }
            };
            let plain_font = match template {
                FontTemplate::Raw(arc, index) => {
                    PlainFontTemplate {
                        data: font_paths[&arc.as_ptr()].clone(),
                        index,
                    }
                }
                #[cfg(not(any(target_os = "macos", target_os = "ios")))]
                FontTemplate::Native(native) => {
                    PlainFontTemplate {
                        data: native.path.to_string_lossy().to_string(),
                        index: native.index,
                    }
                }
                #[cfg(any(target_os = "macos", target_os = "ios"))]
                FontTemplate::Native(native) => {
                    PlainFontTemplate {
                        data: native.name,
                        index: 0,
                    }
                }
            };
            font_templates.insert(key, plain_font);
            // Generate a reverse map from a shared key to a representive key.
            font_remap.insert(shared_key, key);
        }
        let mut font_instances = Vec::new();
        // Build a list of duplicate instance keys.
        for instance_key in res.fonts.instance_keys.keys() {
            let shared_key = res.fonts.instance_keys.map_key(&instance_key);
            let instance = match res.fonts.instances.get_font_instance(shared_key) {
                Some(instance) => instance,
                None => {
                    debug!("Failed serializing font instance {:?}", instance_key);
                    continue;
                }
            };
            // Target the instance towards a representive duplicate font key. The font key will be
            // de-duplicated on load to an appropriate shared key.
            font_instances.push(BaseFontInstance {
                font_key: font_remap.get(&instance.font_key).cloned().unwrap_or(instance.font_key),
                instance_key,
                ..(*instance).clone()
            });
        }
        let resources = PlainResources {
            font_templates,
            font_instances,
            image_templates: res.image_templates.images
                .iter()
                .map(|(key, template)| {
                    (*key, PlainImageTemplate {
                        data: match template.data {
                            CachedImageData::Raw(ref arc) => image_paths[&arc.as_ptr()].clone(),
                            _ => other_paths[key].clone(),
                        },
                        descriptor: template.descriptor.clone(),
                        tiling: template.tiling,
                        generation: template.generation,
                    })
                })
                .collect(),
        };

        (resources, external_images)
    }

    #[cfg(feature = "capture")]
    pub fn save_caches(&self, _root: &PathBuf) -> PlainCacheRef {
        PlainCacheRef {
            current_frame_id: self.current_frame_id,
            glyphs: &self.cached_glyphs,
            glyph_dimensions: &self.cached_glyph_dimensions,
            images: &self.cached_images,
            render_tasks: &self.cached_render_tasks,
            textures: &self.texture_cache,
            picture_textures: &self.picture_textures,
        }
    }

    #[cfg(feature = "replay")]
    pub fn load_capture(
        &mut self,
        resources: PlainResources,
        caches: Option<PlainCacheOwn>,
        config: &CaptureConfig,
    ) -> Vec<PlainExternalImage> {
        use std::{fs, path::Path};
        use crate::texture_cache::TextureCacheConfig;

        info!("loading resource cache");
        //TODO: instead of filling the local path to Arc<data> map as we process
        // each of the resource types, we could go through all of the local paths
        // and fill out the map as the first step.
        let mut raw_map = FastHashMap::<String, Arc<Vec<u8>>>::default();

        self.clear(ClearCache::all());
        self.clear_images(|_| true);

        match caches {
            Some(cached) => {
                self.current_frame_id = cached.current_frame_id;
                self.cached_glyphs = cached.glyphs;
                self.cached_glyph_dimensions = cached.glyph_dimensions;
                self.cached_images = cached.images;
                self.cached_render_tasks = cached.render_tasks;
                self.texture_cache = cached.textures;
                self.picture_textures = cached.picture_textures;
            }
            None => {
                self.current_frame_id = FrameId::INVALID;
                self.texture_cache = TextureCache::new(
                    self.texture_cache.max_texture_size(),
                    self.texture_cache.tiling_threshold(),
                    self.texture_cache.color_formats(),
                    self.texture_cache.swizzle_settings(),
                    &TextureCacheConfig::DEFAULT,
                );
                self.picture_textures = PictureTextures::new(
                    self.picture_textures.default_tile_size(),
                    self.picture_textures.filter(),
                );
            }
        }

        self.glyph_rasterizer.reset();
        let res = &mut self.resources;
        res.fonts.templates.clear();
        res.fonts.instances.clear();
        res.image_templates.images.clear();

        info!("\tfont templates...");
        let root = config.resource_root();
        let native_font_replacement = Arc::new(NATIVE_FONT.to_vec());
        for (key, plain_template) in resources.font_templates {
            let arc = match raw_map.entry(plain_template.data) {
                Entry::Occupied(e) => {
                    e.get().clone()
                }
                Entry::Vacant(e) => {
                    let file_path = if Path::new(e.key()).is_absolute() {
                        PathBuf::from(e.key())
                    } else {
                        root.join(e.key())
                    };
                    let arc = match fs::read(file_path) {
                        Ok(buffer) => Arc::new(buffer),
                        Err(err) => {
                            error!("Unable to open font template {:?}: {:?}", e.key(), err);
                            Arc::clone(&native_font_replacement)
                        }
                    };
                    e.insert(arc).clone()
                }
            };

            let template = FontTemplate::Raw(arc, plain_template.index);
            // Only add the template if this is the first time it has been seen.
            if let Some(shared_key) = res.fonts.font_keys.add_key(&key, &template) {
                self.glyph_rasterizer.add_font(shared_key, template.clone());
                res.fonts.templates.add_font(shared_key, template);
            }
        }

        info!("\tfont instances...");
        for instance in resources.font_instances {
            // Target the instance to a shared font key.
            let base = BaseFontInstance {
                font_key: res.fonts.font_keys.map_key(&instance.font_key),
                ..instance
            };
            if let Some(shared_instance) = res.fonts.instance_keys.add_key(base) {
                res.fonts.instances.add_font_instance(shared_instance);
            }
        }

        info!("\timage templates...");
        let mut external_images = Vec::new();
        for (key, template) in resources.image_templates {
            let data = if template.data.starts_with("snapshots/") {
                // TODO(nical): If a snapshot was captured in a previous frame,
                // we have to serialize/deserialize the image itself.
                CachedImageData::Snapshot
            } else {
                match config.deserialize_for_resource::<PlainExternalImage, _>(&template.data) {
                    Some(plain) => {
                        let ext_data = plain.external;
                        external_images.push(plain);
                        CachedImageData::External(ext_data)
                    }
                    None => {
                        let arc = match raw_map.entry(template.data) {
                            Entry::Occupied(e) => e.get().clone(),
                            Entry::Vacant(e) => {
                                match fs::read(root.join(e.key())) {
                                    Ok(buffer) => {
                                        e.insert(Arc::new(buffer)).clone()
                                    }
                                    Err(err) => {
                                        log::warn!("Unable to open {}: {err:?}", e.key());
                                        continue;
                                    }
                                }
                            }
                        };
                        CachedImageData::Raw(arc)
                    }
                }
            };

            res.image_templates.images.insert(key, ImageResource {
                data,
                descriptor: template.descriptor,
                tiling: template.tiling,
                visible_rect: template.descriptor.size.into(),
                adjustment: AdjustedImageSource::new(), // TODO(nical)
                generation: template.generation,
            });
        }

        external_images
    }

    #[cfg(feature = "capture")]
    pub fn save_capture_sequence(&mut self, config: &mut CaptureConfig) -> Vec<ExternalCaptureImage> {
        if self.capture_dirty {
            self.capture_dirty = false;
            config.prepare_resource();
            let (resources, deferred) = self.save_capture(&config.resource_root());
            config.serialize_for_resource(&resources, "plain-resources.ron");
            deferred
        } else {
            Vec::new()
        }
    }
}