Document the public api

src/lib.rs

@@ -4,6 +4,44 @@
 
 //#![feature(mpsc_select)]
 
+//! A GPU based Webrender.
+//!
+//! It serves as an experimental render backend for [Servo](https://servo.org/),
+//! but it can also be used as such in a standalone application.
+//!
+//! # External dependencies
+//! Webrender currently depends on [FreeType](https://www.freetype.org/)
+//!
+//! # Api Structure
+//! The main entry point to webrender is the `webrender::renderer::Renderer`.
+//!
+//! By calling `Renderer::new(...)` you get a `Renderer`, as well as a `RenderApiSender`.
+//! Your `Renderer` is responsible to render the previously processed frames onto the screen.
+//!
+//! By calling `yourRenderApiSenderInstance.create_api()`, you'll get a `RenderApi` instance,
+//! which is responsible for the processing of new frames. A worker thread is used internally to
+//! untie the workload from the application thread and therefore be able
+//! to make better use of multicore systems.
+//!
+//! What is referred to as a `frame`, is the current geometry on the screen.
+//! A new Frame is created by calling [set_root_stacking_context()][newframe] on the `RenderApi`.
+//! When the geometry is processed, the application will be informed via a `RenderNotifier`,
+//! a callback which you employ with [set_render_notifier][notifier] on the `Renderer`
+//! More information about [stacking contexts][stacking_contexts].
+//!
+//! `set_root_stacking_context()` also needs to be supplied with `BuiltDisplayList`s.
+//! These are obtained by finalizing a `DisplayListBuilder`. These are used to draw your geometry.
+//! But it doesn't only contain trivial geometry, it can also store another StackingContext, as
+//! they're nestable.
+//!
+//! Remember to insert the DisplayListId into the StackingContext as well, as they'll be referenced
+//! from there. An Id for your DisplayList can be obtained by calling
+//! `yourRenderApiInstance.next_display_list_id();`
+//!
+//! [stacking_contexts]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context
+//! [newframe]: ../webrender_traits/struct.RenderApi.html#method.set_root_stacking_context
+//! [notifier]: struct.Renderer.html#method.set_render_notifier
+
 #[macro_use]
 extern crate lazy_static;
 #[macro_use]

src/renderer.rs

@@ -2,6 +2,13 @@
  * 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/. */
 
+//! The webrender API.
+//!
+//! The `webrender::renderer` module provides the interface to webrender, which
+//! is accessible through [`Renderer`][renderer]
+//!
+//! [renderer]: struct.Renderer.html
+
 use batch::{RasterBatch, VertexBufferId};
 use bit_set::BitSet;
 use debug_render::DebugRenderer;
@@ -155,6 +162,25 @@ pub struct Renderer {
 }
 
 impl Renderer {
+    /// Initializes webrender and creates a Renderer and RenderApiSender.
+    ///
+    /// # Examples
+    /// Initializes a Renderer with some reasonable values. For more information see
+    /// [RendererOptions][rendereroptions].
+    /// [rendereroptions]: struct.RendererOptions.html
+    ///
+    /// ```rust,ignore
+    /// # use webrender::renderer::Renderer;
+    /// # use std::path::PathBuf;
+    /// let opts = webrender::RendererOptions {
+    ///    device_pixel_ratio: 1.0,
+    ///    resource_path: PathBuf::from("../webrender/res"),
+    ///    enable_aa: false,
+    ///    enable_msaa: false,
+    ///    enable_profiler: false,
+    /// };
+    /// let (renderer, sender) = Renderer::new(opts);
+    /// ```
     pub fn new(options: RendererOptions) -> (Renderer, RenderApiSender) {
         let (api_tx, api_rx) = ipc::channel().unwrap();
         let (payload_tx, payload_rx) = ipc::bytes_channel().unwrap();
@@ -341,17 +367,25 @@ impl Renderer {
         self.u_direction = self.device.get_uniform_location(self.blur_program_id, "uDirection");
     }
 
+    /// Sets the new RenderNotifier.
+    ///
+    /// The RenderNotifier will be called when processing e.g. of a (scrolling) frame is done,
+    /// and therefore the screen should be updated.
     pub fn set_render_notifier(&self, notifier: Box<RenderNotifier>) {
         let mut notifier_arc = self.notifier.lock().unwrap();
         *notifier_arc = Some(notifier);
     }
 
+    /// Returns the Epoch of the current frame in a pipeline.
     pub fn current_epoch(&self, pipeline_id: PipelineId) -> Option<Epoch> {
         self.current_frame.as_ref().and_then(|frame| {
             frame.pipeline_epoch_map.get(&pipeline_id).map(|epoch| *epoch)
         })
     }
 
+    /// Processes the result queue.
+    ///
+    /// Should be called before `render()`, as texture cache updates are done here.
     pub fn update(&mut self) {
         // Pull any pending results and return the most recent.
         while let Ok(msg) = self.result_rx.try_recv() {
@@ -371,6 +405,10 @@ impl Renderer {
         }
     }
 
+    /// Renders the current frame.
+    ///
+    /// A Frame is supplied by calling [set_root_stacking_context()][newframe].
+    /// [newframe]: ../../webrender_traits/struct.RenderApi.html#method.set_root_stacking_context
     pub fn render(&mut self, framebuffer_size: Size2D<u32>) {
         let mut profile_timers = RendererProfileTimers::new();