|author||Jan Holesovsky <firstname.lastname@example.org>||2014-09-05 10:06:58 +0200|
|committer||Jan Holesovsky <email@example.com>||2014-09-05 10:30:02 +0200|
drawinglayer: Improve the README.
Diffstat (limited to 'drawinglayer')
1 files changed, 83 insertions, 3 deletions
diff --git a/drawinglayer/README b/drawinglayer/README
index 480c5b491243..d950f29cfddb 100644
@@ -1,5 +1,85 @@
-Somewhat of a middle layer between rendering subsystems and application cores.
+Drawing API that can specify what to draw via a kind of display list.
-(What are "rendering subsystems" and "application cores"?)
+Example of the DrawingLayer use is eg. in svx/source/xoutdev/xtabhtch.cxx:121.
+A stripped down version with extended comments:
-It offers a nice and easy API to render complex shapes. (Pure "marketing".)
+ // Create a hatch primitive (here a rectangle that will be filled with
+ // the appropriate hatching, but has no border).
+ // This will not draw it yet; it's so far only constructed to add it to a
+ // display list later.
+ const drawinglayer::primitive2d::Primitive2DReference aHatchPrimitive(
+ new drawinglayer::primitive2d::PolyPolygonHatchPrimitive2D(...));
+ // Create a rectangle around the hatch, to give it a border.
+ const drawinglayer::primitive2d::Primitive2DReference aBlackRectanglePrimitive(
+ new drawinglayer::primitive2d::PolygonHairlinePrimitive2D(...));
+ // Here we want to render to a virtual device (to later obtain the bitmap
+ // out of that), so prepare it.
+ VirtualDevice aVirtualDevice;
+ // Create processor and draw primitives, to get it ready for rendering.
+ boost::scoped_ptr<drawinglayer::processor2d::BaseProcessor2D> pProcessor2D(
+ if (pProcessor2D)
+ // Fill-in the display list.
+ drawinglayer::primitive2d::Primitive2DSequence aSequence(2);
+ aSequence = aHatchPrimitive;
+ aSequence = aBlackRectanglePrimitive;
+ // Render it to the virtual device.
+ // Obtain the bitmap that was rendered from the virtual device, to re-use
+ // it in the widget.
+ aRetval = aVirtualDevice.GetBitmap(Point(0, 0), aVirtualDevice.GetOutputSizePixel());
+== DrawingLayer glossary ==
+Primitives - classes that represent what should be drawn. It holds the data
+what to draw, but does not contain any kind of the rendering. Some of the
+primitives are 'Basic primitives', that are primitives that cannot be
+decomposed. The rest of the primitives can be decomposed to the basic
+Decomposition - a way how to break down the more complicated primitives into
+the basic primitives, and represent them via them; this logically makes the
+plain Primitive2DSequence display list a hierarchy.
+Eg. PolygonMarkerPrimitive2D can be decomposed to 2 hairlines
+PolyPolygonHairlinePrimitive2D's, each with different color.
+Processor - a class that goes through the hierarchy of the Primitives, and
+renders it some way. Various processors, like VclPixelProcessor2D (renders to
+the screen), VclMetafileProcessor2D (renders to the VCL metafile, eg. for
+== How to Implement a new Primitive ("something new to draw") ==
+* Create an ancestor of BasePrimitive2D
+ (or of its ancestor if it fits the purpose better)
+ * Assign it an ID [in drawinglayer_primitivetypes2d.hxx]
+ * Implement its decomposition
+ [virtual Primitive2DSequence create2DDecomposition(...)]
+* Extend the (various) processor(s)
+ If you need more than relying on just the decomposition
+== Where is DrawingLayer used ==
+* SdrObject(s) (rectangles, Circles, predefined shapes etc.)
+* Various smaller cases to 'just draw something'
+ * Draw to a virtual device, and use the resulting bitmap (like the example
+* Custom widgets (like the Header / Footer indicator button)