diff options
Diffstat (limited to 'gfx/wr/webrender_api/src/image.rs')
| -rw-r--r-- | gfx/wr/webrender_api/src/image.rs | 580 |
1 files changed, 580 insertions, 0 deletions
diff --git a/gfx/wr/webrender_api/src/image.rs b/gfx/wr/webrender_api/src/image.rs new file mode 100644 index 0000000000..4ce73f9e46 --- /dev/null +++ b/gfx/wr/webrender_api/src/image.rs @@ -0,0 +1,580 @@ +/* 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/. */ + +#![deny(missing_docs)] + +use euclid::{size2, Box2D, num::Zero}; +use peek_poke::PeekPoke; +use std::ops::{Add, Sub}; +use std::sync::Arc; +// local imports +use crate::{IdNamespace, TileSize}; +use crate::font::{FontInstanceKey, FontInstanceData, FontKey, FontTemplate}; +use crate::units::*; + +/// The default tile size for blob images and regular images larger than +/// the maximum texture size. +pub const DEFAULT_TILE_SIZE: TileSize = 512; + +/// An opaque identifier describing an image registered with WebRender. +/// This is used as a handle to reference images, and is used as the +/// hash map key for the actual image storage in the `ResourceCache`. +#[repr(C)] +#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, MallocSizeOf, PartialEq, Serialize, PeekPoke)] +pub struct ImageKey(pub IdNamespace, pub u32); + +impl Default for ImageKey { + fn default() -> Self { + ImageKey::DUMMY + } +} + +impl ImageKey { + /// Placeholder Image key, used to represent None. + pub const DUMMY: Self = ImageKey(IdNamespace(0), 0); + + /// Mints a new ImageKey. The given ID must be unique. + pub fn new(namespace: IdNamespace, key: u32) -> Self { + ImageKey(namespace, key) + } +} + +/// An opaque identifier describing a blob image registered with WebRender. +/// This is used as a handle to reference blob images, and can be used as an +/// image in display items. +#[repr(C)] +#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] +pub struct BlobImageKey(pub ImageKey); + +impl BlobImageKey { + /// Interpret this blob image as an image for a display item. + pub fn as_image(self) -> ImageKey { + self.0 + } +} + +/// An arbitrary identifier for an external image provided by the +/// application. It must be a unique identifier for each external +/// image. +#[repr(C)] +#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash, Serialize, Deserialize)] +pub struct ExternalImageId(pub u64); + +/// The source for an external image. +pub enum ExternalImageSource<'a> { + /// A raw pixel buffer. + RawData(&'a [u8]), + /// A gl::GLuint texture handle. + NativeTexture(u32), + /// An invalid source. + Invalid, +} + +/// The data that an external client should provide about +/// an external image. For instance, if providing video frames, +/// the application could call wr.render() whenever a new +/// video frame is ready. Note that the UV coords are supplied +/// in texel-space! +pub struct ExternalImage<'a> { + /// UV coordinates for the image. + pub uv: TexelRect, + /// The source for this image's contents. + pub source: ExternalImageSource<'a>, +} + +/// The interfaces that an application can implement to support providing +/// external image buffers. +/// When the application passes an external image to WR, it should keep that +/// external image life time. People could check the epoch id in RenderNotifier +/// at the client side to make sure that the external image is not used by WR. +/// Then, do the clean up for that external image. +pub trait ExternalImageHandler { + /// Lock the external image. Then, WR could start to read the image content. + /// The WR client should not change the image content until the unlock() + /// call. + fn lock(&mut self, key: ExternalImageId, channel_index: u8) -> ExternalImage; + /// Unlock the external image. WR should not read the image content + /// after this call. + fn unlock(&mut self, key: ExternalImageId, channel_index: u8); +} + +/// Specifies the type of texture target in driver terms. +#[repr(u8)] +#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug, Serialize, Deserialize)] +pub enum ImageBufferKind { + /// Standard texture. This maps to GL_TEXTURE_2D in OpenGL. + Texture2D = 0, + /// Rectangle texture. This maps to GL_TEXTURE_RECTANGLE in OpenGL. This + /// is similar to a standard texture, with a few subtle differences + /// (no mipmaps, non-power-of-two dimensions, different coordinate space) + /// that make it useful for representing the kinds of textures we use + /// in WebRender. See https://www.khronos.org/opengl/wiki/Rectangle_Texture + /// for background on Rectangle textures. + TextureRect = 1, + /// External texture. This maps to GL_TEXTURE_EXTERNAL_OES in OpenGL, which + /// is an extension. This is used for image formats that OpenGL doesn't + /// understand, particularly YUV. See + /// https://www.khronos.org/registry/OpenGL/extensions/OES/OES_EGL_image_external.txt + TextureExternal = 2, +} + +/// Storage format identifier for externally-managed images. +#[repr(u8)] +#[derive(Debug, Copy, Clone, Eq, Hash, PartialEq, Serialize, Deserialize)] +pub enum ExternalImageType { + /// The image is texture-backed. + TextureHandle(ImageBufferKind), + /// The image is heap-allocated by the embedding. + Buffer, +} + +/// Descriptor for external image resources. See `ImageData`. +#[repr(C)] +#[derive(Debug, Copy, Clone, Eq, Hash, PartialEq, Serialize, Deserialize)] +pub struct ExternalImageData { + /// The identifier of this external image, provided by the embedding. + pub id: ExternalImageId, + /// For multi-plane images (i.e. YUV), indicates the plane of the + /// original image that this struct represents. 0 for single-plane images. + pub channel_index: u8, + /// Storage format identifier. + pub image_type: ExternalImageType, +} + +/// Specifies the format of a series of pixels, in driver terms. +#[repr(u8)] +#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] +pub enum ImageFormat { + /// One-channel, byte storage. The "red" doesn't map to the color + /// red per se, and is just the way that OpenGL has historically referred + /// to single-channel buffers. + R8 = 1, + /// One-channel, short storage + R16 = 2, + /// Four channels, byte storage. + BGRA8 = 3, + /// Four channels, float storage. + RGBAF32 = 4, + /// Two-channels, byte storage. Similar to `R8`, this just means + /// "two channels" rather than "red and green". + RG8 = 5, + /// Two-channels, short storage. Similar to `R16`, this just means + /// "two channels" rather than "red and green". + RG16 = 6, + + /// Four channels, signed integer storage. + RGBAI32 = 7, + /// Four channels, byte storage. + RGBA8 = 8, +} + +impl ImageFormat { + /// Returns the number of bytes per pixel for the given format. + pub fn bytes_per_pixel(self) -> i32 { + match self { + ImageFormat::R8 => 1, + ImageFormat::R16 => 2, + ImageFormat::BGRA8 => 4, + ImageFormat::RGBAF32 => 16, + ImageFormat::RG8 => 2, + ImageFormat::RG16 => 4, + ImageFormat::RGBAI32 => 16, + ImageFormat::RGBA8 => 4, + } + } +} + +/// Specifies the color depth of an image. Currently only used for YUV images. +#[repr(u8)] +#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, MallocSizeOf, PartialEq, Serialize, PeekPoke)] +pub enum ColorDepth { + /// 8 bits image (most common) + Color8, + /// 10 bits image + Color10, + /// 12 bits image + Color12, + /// 16 bits image + Color16, +} + +impl Default for ColorDepth { + fn default() -> Self { + ColorDepth::Color8 + } +} + +impl ColorDepth { + /// Return the numerical bit depth value for the type. + pub fn bit_depth(self) -> u32 { + match self { + ColorDepth::Color8 => 8, + ColorDepth::Color10 => 10, + ColorDepth::Color12 => 12, + ColorDepth::Color16 => 16, + } + } + /// 10 and 12 bits images are encoded using 16 bits integer, we need to + /// rescale the 10 or 12 bits value to extend to 16 bits. + pub fn rescaling_factor(self) -> f32 { + match self { + ColorDepth::Color8 => 1.0, + ColorDepth::Color10 => 64.0, + ColorDepth::Color12 => 16.0, + ColorDepth::Color16 => 1.0, + } + } +} + +bitflags! { + /// Various flags that are part of an image descriptor. + #[derive(Deserialize, Serialize)] + pub struct ImageDescriptorFlags: u32 { + /// Whether this image is opaque, or has an alpha channel. Avoiding blending + /// for opaque surfaces is an important optimization. + const IS_OPAQUE = 1; + /// Whether to allow the driver to automatically generate mipmaps. If images + /// are already downscaled appropriately, mipmap generation can be wasted + /// work, and cause performance problems on some cards/drivers. + /// + /// See https://github.com/servo/webrender/pull/2555/ + const ALLOW_MIPMAPS = 2; + } +} + +/// Metadata (but not storage) describing an image In WebRender. +#[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)] +pub struct ImageDescriptor { + /// Format of the image data. + pub format: ImageFormat, + /// Width and length of the image data, in pixels. + pub size: DeviceIntSize, + /// The number of bytes from the start of one row to the next. If non-None, + /// `compute_stride` will return this value, otherwise it returns + /// `width * bpp`. Different source of images have different alignment + /// constraints for rows, so the stride isn't always equal to width * bpp. + pub stride: Option<i32>, + /// Offset in bytes of the first pixel of this image in its backing buffer. + /// This is used for tiling, wherein WebRender extracts chunks of input images + /// in order to cache, manipulate, and render them individually. This offset + /// tells the texture upload machinery where to find the bytes to upload for + /// this tile. Non-tiled images generally set this to zero. + pub offset: i32, + /// Various bool flags related to this descriptor. + pub flags: ImageDescriptorFlags, +} + +impl ImageDescriptor { + /// Mints a new ImageDescriptor. + pub fn new( + width: i32, + height: i32, + format: ImageFormat, + flags: ImageDescriptorFlags, + ) -> Self { + ImageDescriptor { + size: size2(width, height), + format, + stride: None, + offset: 0, + flags, + } + } + + /// Returns the stride, either via an explicit stride stashed on the object + /// or by the default computation. + pub fn compute_stride(&self) -> i32 { + self.stride.unwrap_or(self.size.width * self.format.bytes_per_pixel()) + } + + /// Computes the total size of the image, in bytes. + pub fn compute_total_size(&self) -> i32 { + self.compute_stride() * self.size.height + } + + /// Computes the bounding rectangle for the image, rooted at (0, 0). + pub fn full_rect(&self) -> DeviceIntRect { + DeviceIntRect::from_origin_and_size( + DeviceIntPoint::zero(), + self.size, + ) + } + + /// Returns true if this descriptor is opaque + pub fn is_opaque(&self) -> bool { + self.flags.contains(ImageDescriptorFlags::IS_OPAQUE) + } + + /// Returns true if this descriptor allows mipmaps + pub fn allow_mipmaps(&self) -> bool { + self.flags.contains(ImageDescriptorFlags::ALLOW_MIPMAPS) + } +} + +/// Represents the backing store of an arbitrary series of pixels for display by +/// WebRender. This storage can take several forms. +#[derive(Clone, Debug, Serialize, Deserialize)] +pub enum ImageData { + /// A simple series of bytes, provided by the embedding and owned by WebRender. + /// The format is stored out-of-band, currently in ImageDescriptor. + Raw(#[serde(with = "serde_image_data_raw")] Arc<Vec<u8>>), + /// 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), +} + +mod serde_image_data_raw { + extern crate serde_bytes; + + use std::sync::Arc; + use serde::{Deserializer, Serializer}; + + pub fn serialize<S: Serializer>(bytes: &Arc<Vec<u8>>, serializer: S) -> Result<S::Ok, S::Error> { + serde_bytes::serialize(bytes.as_slice(), serializer) + } + + pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Arc<Vec<u8>>, D::Error> { + serde_bytes::deserialize(deserializer).map(Arc::new) + } +} + +impl ImageData { + /// Mints a new raw ImageData, taking ownership of the bytes. + pub fn new(bytes: Vec<u8>) -> Self { + ImageData::Raw(Arc::new(bytes)) + } + + /// Mints a new raw ImageData from Arc-ed bytes. + pub fn new_shared(bytes: Arc<Vec<u8>>) -> Self { + ImageData::Raw(bytes) + } +} + +/// The resources exposed by the resource cache available for use by the blob rasterizer. +pub trait BlobImageResources { + /// Returns the `FontTemplate` for the given key. + fn get_font_data(&self, key: FontKey) -> Option<FontTemplate>; + /// Returns the `FontInstanceData` for the given key, if found. + fn get_font_instance_data(&self, key: FontInstanceKey) -> Option<FontInstanceData>; +} + +/// A handler on the render backend that can create rasterizer objects which will +/// be sent to the scene builder thread to execute the rasterization. +/// +/// The handler is responsible for collecting resources, managing/updating blob commands +/// and creating the rasterizer objects, but isn't expected to do any rasterization itself. +pub trait BlobImageHandler: Send { + /// Creates a snapshot of the current state of blob images in the handler. + fn create_blob_rasterizer(&mut self) -> Box<dyn AsyncBlobImageRasterizer>; + + /// Creates an empty blob handler of the same type. + /// + /// This is used to allow creating new API endpoints with blob handlers installed on them. + fn create_similar(&self) -> Box<dyn BlobImageHandler>; + + /// A hook to let the blob image handler update any state related to resources that + /// are not bundled in the blob recording itself. + fn prepare_resources( + &mut self, + services: &dyn BlobImageResources, + requests: &[BlobImageParams], + ); + + /// Register a blob image. + fn add(&mut self, key: BlobImageKey, data: Arc<BlobImageData>, visible_rect: &DeviceIntRect, + tile_size: TileSize); + + /// Update an already registered blob image. + fn update(&mut self, key: BlobImageKey, data: Arc<BlobImageData>, visible_rect: &DeviceIntRect, + dirty_rect: &BlobDirtyRect); + + /// Delete an already registered blob image. + fn delete(&mut self, key: BlobImageKey); + + /// A hook to let the handler clean up any state related to a font which the resource + /// cache is about to delete. + fn delete_font(&mut self, key: FontKey); + + /// A hook to let the handler clean up any state related to a font instance which the + /// resource cache is about to delete. + fn delete_font_instance(&mut self, key: FontInstanceKey); + + /// A hook to let the handler clean up any state related a given namespace before the + /// resource cache deletes them. + fn clear_namespace(&mut self, namespace: IdNamespace); + + /// Whether to allow rendering blobs on multiple threads. + fn enable_multithreading(&mut self, enable: bool); +} + +/// A group of rasterization requests to execute synchronously on the scene builder thread. +pub trait AsyncBlobImageRasterizer : Send { + /// Rasterize the requests. + /// + /// Gecko uses te priority hint to schedule work in a way that minimizes the risk + /// of high priority work being blocked by (or enqued behind) low priority work. + fn rasterize( + &mut self, + requests: &[BlobImageParams], + low_priority: bool + ) -> Vec<(BlobImageRequest, BlobImageResult)>; +} + + +/// Input parameters for the BlobImageRasterizer. +#[derive(Copy, Clone, Debug)] +pub struct BlobImageParams { + /// A key that identifies the blob image rasterization request. + pub request: BlobImageRequest, + /// Description of the format of the blob's output image. + pub descriptor: BlobImageDescriptor, + /// An optional sub-rectangle of the image to avoid re-rasterizing + /// the entire image when only a portion is updated. + /// + /// If set to None the entire image is rasterized. + pub dirty_rect: BlobDirtyRect, +} + +/// The possible states of a Dirty rect. +/// +/// This exists because people kept getting confused with `Option<Box2D>`. +#[derive(Debug, Serialize, Deserialize)] +pub enum DirtyRect<T: Copy, U> { + /// Everything is Dirty, equivalent to Partial(image_bounds) + All, + /// Some specific amount is dirty + Partial(Box2D<T, U>) +} + +impl<T, U> DirtyRect<T, U> +where + T: Copy + Clone + + PartialOrd + PartialEq + + Add<T, Output = T> + + Sub<T, Output = T> + + Zero +{ + /// Creates an empty DirtyRect (indicating nothing is invalid) + pub fn empty() -> Self { + DirtyRect::Partial(Box2D::zero()) + } + + /// Returns whether the dirty rect is empty + pub fn is_empty(&self) -> bool { + match self { + DirtyRect::All => false, + DirtyRect::Partial(rect) => rect.is_empty(), + } + } + + /// Replaces self with the empty rect and returns the old value. + pub fn replace_with_empty(&mut self) -> Self { + ::std::mem::replace(self, DirtyRect::empty()) + } + + /// Maps over the contents of Partial. + pub fn map<F>(self, func: F) -> Self + where F: FnOnce(Box2D<T, U>) -> Box2D<T, U>, + { + use crate::DirtyRect::*; + + match self { + All => All, + Partial(rect) => Partial(func(rect)), + } + } + + /// Unions the dirty rects. + pub fn union(&self, other: &Self) -> Self { + use crate::DirtyRect::*; + + match (*self, *other) { + (All, _) | (_, All) => All, + (Partial(rect1), Partial(rect2)) => Partial(rect1.union(&rect2)), + } + } + + /// Intersects the dirty rects. + pub fn intersection(&self, other: &Self) -> Self { + use crate::DirtyRect::*; + + match (*self, *other) { + (All, rect) | (rect, All) => rect, + (Partial(rect1), Partial(rect2)) => { + Partial(rect1.intersection(&rect2).unwrap_or_else(Box2D::zero)) + } + } + } + + /// Converts the dirty rect into a subrect of the given one via intersection. + pub fn to_subrect_of(&self, rect: &Box2D<T, U>) -> Box2D<T, U> { + use crate::DirtyRect::*; + + match *self { + All => *rect, + Partial(dirty_rect) => { + dirty_rect.intersection(rect).unwrap_or_else(Box2D::zero) + } + } + } +} + +impl<T: Copy, U> Copy for DirtyRect<T, U> {} +impl<T: Copy, U> Clone for DirtyRect<T, U> { + fn clone(&self) -> Self { *self } +} + +impl<T: Copy, U> From<Box2D<T, U>> for DirtyRect<T, U> { + fn from(rect: Box2D<T, U>) -> Self { + DirtyRect::Partial(rect) + } +} + +/// Backing store for blob image command streams. +pub type BlobImageData = Vec<u8>; + +/// Result type for blob raserization. +pub type BlobImageResult = Result<RasterizedBlobImage, BlobImageError>; + +/// Metadata (but not storage) for a blob image. +#[repr(C)] +#[derive(Copy, Clone, Debug)] +pub struct BlobImageDescriptor { + /// Surface of the image or tile to render in the same coordinate space as + /// the drawing commands. + pub rect: LayoutIntRect, + /// Format for the data in the backing store. + pub format: ImageFormat, +} + +/// Representation of a rasterized blob image. This is obtained by passing +/// `BlobImageData` to the embedding via the rasterization callback. +pub struct RasterizedBlobImage { + /// The rectangle that was rasterized in device pixels, relative to the + /// image or tile. + pub rasterized_rect: DeviceIntRect, + /// Backing store. The format is stored out of band in `BlobImageDescriptor`. + pub data: Arc<Vec<u8>>, +} + +/// Error code for when blob rasterization failed. +#[derive(Clone, Debug)] +pub enum BlobImageError { + /// Out of memory. + Oom, + /// Other failure, embedding-specified. + Other(String), +} + + + +/// A key identifying blob image rasterization work requested from the blob +/// image rasterizer. +#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] +pub struct BlobImageRequest { + /// Unique handle to the image. + pub key: BlobImageKey, + /// Tiling offset in number of tiles. + pub tile: TileOffset, +} |