Bug 999440 - Fix styling and typos in MozSurface.md. r=nical
authorMarkus Stange <mstange@themasta.com>
Tue, 22 Apr 2014 16:25:49 +0200
changeset 198028 862dce46405cb8e68e3f98bd9ca94510181297ed
parent 198027 76d97ee6133f83ce35b86dd38f2260eb42cb102a
child 198029 94df6fc66986e23bacc2b31a030031f0f791fa74
push id3624
push userasasaki@mozilla.com
push dateMon, 09 Jun 2014 21:49:01 +0000
treeherdermozilla-beta@b1a5da15899a [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersnical
bugs999440
milestone31.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 999440 - Fix styling and typos in MozSurface.md. r=nical
gfx/doc/MozSurface.md
--- a/gfx/doc/MozSurface.md
+++ b/gfx/doc/MozSurface.md
@@ -1,13 +1,12 @@
 MozSurface {#mozsurface}
 ==========
 
-## This document is work in progress.  Some information may be missing or
-incomplete.
+**This document is work in progress.  Some information may be missing or incomplete.**
 
 ## Goals
 
 We need to be able to safely and efficiently render web content into surfaces that may be shared accross processes.
 MozSurface is a cross-process and backend-independent Surface API and not a stream API.
 
 ## Owner
 
@@ -29,20 +28,21 @@ Drawing web content into a surface and s
 * MozSurface must be a cross-backend/cross-platform abstraction that we will use on all of the supported platforms.
 * It must be possible to efficiently draw into a MozSurface using Moz2D.
 * While it should be possible to share MozSurfaces accross processes, it should not be limited to that. MozSurface should also be the preferred abstraction for use with surfaces that are not shared with the compositor process.
 
 ## TextureClient and TextureHost
 
 TextureClient and TextureHost are the closest abstractions we currently have to MozSurface.
 Inline documentation about TextureClient and TextureHost can be found in:
-* http://dxr.mozilla.org/mozilla-central/source/gfx/layers/client/TextureClient.h
-* http://dxr.mozilla.org/mozilla-central/source/gfx/layers/composite/TextureHost.h
 
-TextureClient is the client-side handle on a MozSurface, while TextureHost is the equivalent host-side representation. There can only be one TextureClient for a given TextureHost, and one TextureHost for a given TextureClient. likewise, the can only be one shared object for a given TextureClient/TextureHost pair.
+* [gfx/layers/client/TextureClient.h](http://dxr.mozilla.org/mozilla-central/source/gfx/layers/client/TextureClient.h)
+* [gfx/layers/composite/TextureHost.h](http://dxr.mozilla.org/mozilla-central/source/gfx/layers/composite/TextureHost.h)
+
+TextureClient is the client-side handle on a MozSurface, while TextureHost is the equivalent host-side representation. There can only be one TextureClient for a given TextureHost, and one TextureHost for a given TextureClient. Likewise, there can only be one shared object for a given TextureClient/TextureHost pair.
 
 A MozSurface containing data that is shared between a client process and a host process exists in the foolowing form:
 
 ```
                                  .
             Client process       .      Host process
                                  .
      ________________      ______________      ______________
@@ -51,50 +51,51 @@ A MozSurface containing data that is sha
     |________________|    |______________|    |______________|
                                  .
                                  .
                                  .
     Figure 1) A Surface as seen by the client and the host processes
 ```
 
 The above figure is a logical representation, not a class diagram.
-<SharedData> Is a placeholder for whichever platform specific surface type we are sharing. For example a Gralloc buffer on Gonk or a D3D11 texture on Windows
+`<SharedData>` is a placeholder for whichever platform specific surface type we are sharing, for example a Gralloc buffer on Gonk or a D3D11 texture on Windows.
 
 ## Locking semantics
 
 In order to access the shared surface data users of MozSurface must acquire and release a lock on the surface, specifying the open mode (read/write/read+write).
 
-bool Lock(OpenMode aMode);
-void Unlock();
+    bool Lock(OpenMode aMode);
+    void Unlock();
 
 This locking API has two purposes:
+
 * Ensure that access to the shared data is race-free.
 * Let the implemetation do whatever is necessary for the user to have access to the data. For example it can be mapping and unmapping the surface data in memory if the underlying backend requires it.
 
 The lock is expected to behave as a cross-process blocking read/write lock that is not reentrant.
 
 ## Immutable surfaces
 
-In some cases we know in advance that a surface will not be modified after it has been shared. This is for example true for video frames. In this case the surface can be arked as immutable and the underlying implementation doesn't need to hold an actual blocking lock on the shared data.
-Trying to acquire a write lock on a MoSurface that is marked as immutable and already shared must fail (return false).
+In some cases we know in advance that a surface will not be modified after it has been shared. This is for example true for video frames. In this case the surface can be marked as immutable and the underlying implementation doesn't need to hold an actual blocking lock on the shared data.
+Trying to acquire a write lock on a MozSurface that is marked as immutable and already shared must fail (return false).
 Note that it is still required to use the Lock/Unlock API to read the data, in order for the implementation to be able to properly map and unmap the memory. This is just an optimization and a safety check.
 
 ## Drawing into a surface
 
 In most cases we want to be able to paint directly into a surface through the Moz2D API.
 
 A surface lets you *borrow* a DrawTarget that is only valid between Lock and Unlock.
 
-DrawTarget* GetAsDrawTarget();
+    DrawTarget* GetAsDrawTarget();
 
-It is invalid to hold a referene to the DrawTarget after Unlock, and a different DrawTarget may be obtained during the next Lock/Unlock interval.
+It is invalid to hold a reference to the DrawTarget after Unlock, and a different DrawTarget may be obtained during the next Lock/Unlock interval.
 
 In some cases we want to use MozSurface without Drawing into it. For instance to share video frames accross processes. Some surface types may also not be accessible through a DrawTarget (for example YCbCr surfaces).
 
-bool CanExposeDrawTarget();
+    bool CanExposeDrawTarget();
 
 helps with making sure that a Surface supports exposing a Moz2D DrawTarget.
 
 ## Using a MozSurface as a source for Compositing
 
 To interface with the Compositor API, MozSurface gives access to TextureSource objects. TextureSource is the cross-backend representation of a texture that Compositor understands.
 While MozSurface handles memory management of (potentially shared) texture data, TextureSource is only an abstraction for Compositing.
 
@@ -129,16 +130,17 @@ When a TextureClient's reference count r
                                     / .   ... can't receive nor send ...
                                    /  .
     (D) Client: Receive Delete <--'   .
                                       .
     Figure 2) MozSurface deallocation handshake
 ```
 
 This handshake protocol is twofold:
+
 * It defines where and when it is possible to deallocate the shared data without races
 * It makes it impossible for asynchronous messages to race with the destruction of the MozSurface.
 
 ### Deallocating on the host side
 
 In the common case, the shared data is deallocated asynchronously on the host side. In this case the deallocation takes place at the point (C) of figure 2.
 
 ### Deallocating on the client side
@@ -158,38 +160,42 @@ The sharing state of a MozSurface can be
 * (2) Local (it isn't shared with the another thread/process)
 * (3) Shared (the state you would expect it to be most of the time)
 * (4) Invalid (when for some rare cases we needed to force the deallocation of the shared data before the destruction of the TextureClient object).
 
 Surfaces can move from state N to state N+1 and be deallocated in any of these states. It could be possible to move from Shared to Local, but we currently don't have a use case for it.
 
 The deallocation protocol above, applies to the Shared state (3).
 In the other cases:
+
 * (1) Unitilialized: There is nothing to do.
 * (2) Local: The shared data is deallocated by the client side without need for a handshake, since it is not shared with other threads.
 * (4) Invalid: There is nothing to do (deallocation has already happenned).
 
 ## Internal buffers / direct texturing
 
-Some MozSurface implementations use CPU-side shared memory to share the texture data accross processes, and require a GPU texture upload when interfacing with a TextureSource. In this case we say that the surface has an internal buffer (because it is implicitly equivalent to double buffering where the shared data is the back buffer and the gpu side texture is the front buffer). We also say that it doesn't do "direct texturing" meaning that we don't draw directly in the GPU-side texture.
-examples:
+Some MozSurface implementations use CPU-side shared memory to share the texture data accross processes, and require a GPU texture upload when interfacing with a TextureSource. In this case we say that the surface has an internal buffer (because it is implicitly equivalent to double buffering where the shared data is the back buffer and the GPU side texture is the front buffer). We also say that it doesn't do "direct texturing" meaning that we don't draw directly into the GPU-side texture.
+
+Examples:
+
  * Shmem MozSurface + OpenGL TextureSource: Has an internal buffer (no direct texturing)
  * Gralloc MozSurface + Gralloc TextureSource: No internal buffer (direct texturing)
 
 While direct texturing is usually the most efficient way, it is not always available depending on the platform and the required allocation size or format. Textures with internal buffers have less restrictions around locking since the host side will only need to read from the MozSurface once per update, meaning that we can often get away with single buffering where we would need double buffering with direct texturing.
 
 ## Alternative solutions
 
 ### Sending ownership back and forth between the client and host sides through message passing, intead of sharing.
 
 The current design of MozSurface makes the surface accessible from both sides at the same time, forcing us to do Locking and have a hand shake around deallocating the shared data, while using pure message passing and making the surface accessible only from one side at a time would avoid these complications.
 
 Using pure message passing was actually the first approach we tried when we created the first version of TextureClient and TextureHost. This strategy failed in several places, partly because of some legacy in Gecko's architecture, and partly because of some of optimizations we do to avoid copying surfaces.
 
 We need a given surface to be accessible on both the client and host for the following reasons:
+
 * Gecko can at any time require read access on the client side to a surface that is shared with the host process, for example to build a temporary layer manager and generate a screenshot. This is mostly a legacy problem.
 * We do some copy-on-write optimizations on surfaces that are shared with the compositor in order to keep invalid regions as small as possible. Out tiling implementation is an example of that.
 * Our buffer rotation code on scrollable non-tiled layers also requires a synchronization on the client side between the front and back buffers, while the front buffer is used on the host side.
 
 ## Backends
 
 We have MozSurface implementaions (classes inheriting from TextureClient/TextureHost) for OpenGL, Software, D3D9, and D3D11 backends.
 Some implemtations can be used with any backend (ex. ShmemTextureClient/Host).