webrender/
lib.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5/*!
6A GPU based renderer for the web.
7
8It serves as an experimental render backend for [Servo](https://servo.org/),
9but it can also be used as such in a standalone application.
10
11# External dependencies
12WebRender currently depends on [FreeType](https://www.freetype.org/)
13
14# Api Structure
15The main entry point to WebRender is the [`crate::Renderer`].
16
17By calling [`Renderer::new(...)`](crate::Renderer::new) you get a [`Renderer`], as well as
18a [`RenderApiSender`](api::RenderApiSender). Your [`Renderer`] is responsible to render the
19previously processed frames onto the screen.
20
21By calling [`yourRenderApiSender.create_api()`](api::RenderApiSender::create_api), you'll
22get a [`RenderApi`](api::RenderApi) instance, which is responsible for managing resources
23and documents. A worker thread is used internally to untie the workload from the application
24thread and therefore be able to make better use of multicore systems.
25
26## Frame
27
28What is referred to as a `frame`, is the current geometry on the screen.
29A new Frame is created by calling [`set_display_list()`](api::Transaction::set_display_list)
30on the [`RenderApi`](api::RenderApi). When the geometry is processed, the application will be
31informed via a [`RenderNotifier`](api::RenderNotifier), a callback which you pass to
32[`Renderer::new`].
33More information about [stacking contexts][stacking_contexts].
34
35[`set_display_list()`](api::Transaction::set_display_list) also needs to be supplied with
36[`BuiltDisplayList`](api::BuiltDisplayList)s. These are obtained by finalizing a
37[`DisplayListBuilder`](api::DisplayListBuilder). These are used to draw your geometry. But it
38doesn't only contain trivial geometry, it can also store another
39[`StackingContext`](api::StackingContext), as they're nestable.
40
41[stacking_contexts]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context
42*/
43
44#![allow(clippy::unreadable_literal, clippy::new_without_default, clippy::too_many_arguments)]
45
46
47// Cribbed from the |matches| crate, for simplicity.
48macro_rules! matches {
49    ($expression:expr, $($pattern:tt)+) => {
50        match $expression {
51            $($pattern)+ => true,
52            _ => false
53        }
54    }
55}
56
57#[macro_use]
58extern crate bitflags;
59#[macro_use]
60extern crate lazy_static;
61#[macro_use]
62extern crate log;
63#[macro_use]
64extern crate malloc_size_of_derive;
65#[cfg(any(feature = "serde"))]
66#[macro_use]
67extern crate serde;
68#[macro_use]
69extern crate tracy_rs;
70#[macro_use]
71extern crate derive_more;
72extern crate malloc_size_of;
73extern crate svg_fmt;
74
75#[macro_use]
76mod profiler;
77mod telemetry;
78
79mod batch;
80mod border;
81mod box_shadow;
82#[cfg(any(feature = "capture", feature = "replay"))]
83mod capture;
84mod clip;
85mod space;
86mod spatial_tree;
87mod command_buffer;
88mod composite;
89mod compositor;
90mod debug_colors;
91mod debug_font_data;
92mod debug_item;
93mod device;
94mod ellipse;
95mod filterdata;
96mod frame_builder;
97mod freelist;
98mod glyph_cache;
99mod gpu_cache;
100mod gpu_types;
101mod hit_test;
102mod internal_types;
103mod lru_cache;
104mod pattern;
105mod picture;
106mod picture_graph;
107mod prepare;
108mod prim_store;
109mod print_tree;
110mod quad;
111mod render_backend;
112mod render_target;
113mod render_task_graph;
114mod render_task_cache;
115mod render_task;
116mod renderer;
117mod resource_cache;
118mod scene;
119mod scene_builder_thread;
120mod scene_building;
121mod screen_capture;
122mod segment;
123mod spatial_node;
124mod surface;
125mod texture_pack;
126mod texture_cache;
127mod tile_cache;
128mod util;
129mod visibility;
130mod api_resources;
131mod image_tiling;
132mod image_source;
133mod rectangle_occlusion;
134mod picture_textures;
135mod frame_allocator;
136mod bump_allocator;
137
138///
139pub mod intern;
140///
141pub mod render_api;
142
143pub mod shader_source {
144    include!(concat!(env!("OUT_DIR"), "/shaders.rs"));
145}
146
147extern crate bincode;
148extern crate byteorder;
149pub extern crate euclid;
150extern crate fxhash;
151extern crate gleam;
152extern crate num_traits;
153extern crate plane_split;
154extern crate rayon;
155#[cfg(feature = "ron")]
156extern crate ron;
157#[macro_use]
158extern crate smallvec;
159#[cfg(all(feature = "capture", feature = "png"))]
160extern crate png;
161#[cfg(test)]
162extern crate rand;
163
164pub extern crate api;
165extern crate webrender_build;
166
167#[doc(hidden)]
168pub use crate::composite::{LayerCompositor, CompositorInputConfig, CompositorSurfaceUsage, ClipRadius};
169pub use crate::composite::{CompositorConfig, Compositor, CompositorCapabilities, CompositorSurfaceTransform};
170pub use crate::composite::{NativeSurfaceId, NativeTileId, NativeSurfaceInfo, PartialPresentCompositor};
171pub use crate::composite::{MappableCompositor, MappedTileInfo, SWGLCompositeSurfaceInfo, WindowVisibility, WindowProperties};
172pub use crate::device::{UploadMethod, VertexUsageHint, get_gl_target, get_unoptimized_shader_source};
173pub use crate::device::{ProgramBinary, ProgramCache, ProgramCacheObserver, FormatDesc, ShaderError};
174pub use crate::device::Device;
175pub use crate::profiler::{ProfilerHooks, set_profiler_hooks};
176pub use crate::renderer::{
177    CpuProfile, DebugFlags, GpuProfile, GraphicsApi,
178    GraphicsApiInfo, PendingShadersToPrecache, PipelineInfo, Renderer, RendererError, RenderResults,
179    RendererStats, Shaders, SharedShaders, ShaderPrecacheFlags,
180    MAX_VERTEX_TEXTURE_WIDTH,
181};
182pub use crate::renderer::init::{WebRenderOptions, create_webrender_instance, AsyncPropertySampler, SceneBuilderHooks, RenderBackendHooks, ONE_TIME_USAGE_HINT};
183pub use crate::hit_test::SharedHitTester;
184pub use crate::internal_types::FastHashMap;
185pub use crate::screen_capture::{AsyncScreenshotHandle, RecordedFrameHandle};
186pub use crate::texture_cache::TextureCacheConfig;
187pub use api as webrender_api;
188pub use webrender_build::shader::{ProgramSourceDigest, ShaderKind};
189pub use crate::picture::{TileDescriptor, TileId, InvalidationReason};
190pub use crate::picture::{PrimitiveCompareResult, CompareHelperResult};
191pub use crate::picture::{TileNode, TileNodeKind, TileOffset};
192pub use crate::intern::ItemUid;
193pub use crate::render_api::*;
194pub use crate::tile_cache::{PictureCacheDebugInfo, DirtyTileDebugInfo, TileDebugInfo, SliceDebugInfo};
195pub use crate::util::FastTransform;
196pub use glyph_rasterizer;
197pub use bump_allocator::ChunkPool;
198
199#[cfg(feature = "sw_compositor")]
200pub use crate::compositor::sw_compositor;