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