Confirm
166
edits
Changes
→Learning Moz2D: Introducing the API
== Learning Moz2D: Introducing the API ==
Following is an overview of the main pieces of the API. For the details including the most recent changes, please refer to [http://mxr.mozilla.org/mozilla-central/source/gfx/2d/2D.h].
The two main components of the Moz2D API are:
* Source surfaces, and
* Draw targets.
=== Source surfaces ===
Source surfaces represent a ''read-only graphics buffer''. There are actually two categories of source surfaces as follows:
<p style="text-align:center">
[[Image:Source-surface-hierarchy.png|DataSourceSurface inherits from SourceSurface]]
</p>
Both SourceSurface and DataSourceSurface are abstract interfaces that are implemented by the various backends.
A '''SourceSurface''' is an ''opaque representation of a buffer'', a ''handle''. That means you ''can’t'' access its pixel data directly.
So what ''can'' you do?
* Use it in various drawing operations on a DrawTarget. For example,
** Draw it, or just part of it (DrawSurface)
** Use it as a mask when drawing a pattern (MaskSurface)
** Use it as a pattern will filling a rectangle (FillRect after wrapping the SourceSurface in a SourcePattern)
* You can also get a DataSourceSurface from it which ''does'' let you access its data.
A '''DataSourceSurface''' is a subclass of a SourceSurface that provides direct access to pixel data.
It is possible to get the DataSourceSurface corresponding to a SourceSurface using the <code>SourceSurface::GetDataSurface</code> method.
Where do SourceSurfaces come from?
* DrawTarget::Snapshot() – SourceSurface corresponding to the current contents of a draw target.
* DrawTarget::CreateSourceSurfaceFromData() – SourceSurface for an existing memory buffer (suitable for using with the draw target it is called on).
* DrawTarget::CreateSourceSurfaceFromNativeSurface() – SourceSurface for an existing buffer of some… ?
* DrawTarget::OptimizeSourceSurface() – Converts an existing SourceSurface into one that can be readily used with the given DrawTarget.
* SourceSurface::GetDataSurface() – Gets a DataSourceSurface corresponding to an existing SourceSurface.
* Factory::CreateDataSourceSurface() – Creates an new memory buffer to be used as a DataSourceSurface.
* Factory::CreateWrappingDataSourceSurface() – Creates a DataSourceSurface to wrap an existing buffer.
{ Diagram showing relationship between concrete implementations and these interfaces using Direct2D as an example }
=== Draw targets ===
