drawinglayer/README.md

   1 # Drawing API
   2
   3 Drawing API that can specify what to draw via a kind of display list.
   4
   5 Example of the DrawingLayer use is eg. in `svx/source/xoutdev/xtabhtch.cxx:121`.
   6 A stripped down version with extended comments:
   7
   8      // Create a hatch primitive (here a rectangle that will be filled with
   9      // the appropriate hatching, but has no border).
  10      // This will not draw it yet; it's so far only constructed to add it to a
  11      // display list later.
  12      const drawinglayer::primitive2d::Primitive2DReference aHatchPrimitive(
  13          new drawinglayer::primitive2d::PolyPolygonHatchPrimitive2D(...));
  14
  15      // Create a rectangle around the hatch, to give it a border.
  16      const drawinglayer::primitive2d::Primitive2DReference aBlackRectanglePrimitive(
  17          new drawinglayer::primitive2d::PolygonHairlinePrimitive2D(...));
  18
  19      // Here we want to render to a virtual device (to later obtain the bitmap
  20      // out of that), so prepare it.
  21      VirtualDevice aVirtualDevice;
  22
  23      // Create processor and draw primitives, to get it ready for rendering.
  24      std::unique_ptr<drawinglayer::processor2d::BaseProcessor2D> pProcessor2D(
  25          drawinglayer::processor2d::createPixelProcessor2DFromOutputDevice(...));
  26
  27      // Fill-in the display list.
  28      drawinglayer::primitive2d::Primitive2DSequence aSequence(2);
  29
  30      aSequence[0] = aHatchPrimitive;
  31      aSequence[1] = aBlackRectanglePrimitive;
  32
  33      // Render it to the virtual device.
  34      pProcessor2D->process(aSequence);
  35      pProcessor2D.reset();
  36
  37      // Obtain the bitmap that was rendered from the virtual device, to re-use
  38      // it in the widget.
  39      aRetval = aVirtualDevice.GetBitmap(Point(0, 0), aVirtualDevice.GetOutputSizePixel());
  40
  41 ## DrawingLayer Glossary
  42
  43 Primitives - classes that represent what should be drawn.  It holds the data
  44 what to draw, but does not contain any kind of the rendering.  Some of the
  45 primitives are 'Basic primitives', that are primitives that cannot be
  46 decomposed.  The rest of the primitives can be decomposed to the basic
  47 primitives.
  48
  49 Decomposition - a way how to break down the more complicated primitives into
  50 the basic primitives, and represent them via them; this logically makes the
  51 plain `Primitive2DSequence` display list a hierarchy.
  52 Eg. `PolygonMarkerPrimitive2D` can be decomposed to 2 hairlines
  53 `PolyPolygonHairlinePrimitive2D`'s, each with different color.
  54
  55 Processor - a class that goes through the hierarchy of the Primitives, and
  56 renders it some way.  Various processors, like `VclPixelProcessor2D` (renders to
  57 the screen), `VclMetafileProcessor2D` (renders to the VCL metafile, eg. for
  58 printing), etc.
  59
  60 ## How to Implement a New Primitive ("Something New to Draw")
  61
  62 * Create an ancestor of `BasePrimitive2D`
  63   (or of its ancestor if it fits the purpose better)
  64
  65   * Assign it an ID [in `drawinglayer_primitivetypes2d.hxx`]
  66
  67   * Implement its decomposition
  68     [`virtual Primitive2DSequence create2DDecomposition(...)`]
  69
  70 * Extend the (various) processor(s)
  71   If you need more than relying on just the decomposition
  72
  73 ## Where is DrawingLayer Used
  74
  75 * `SdrObject`(s) (rectangles, Circles, predefined shapes etc.)
  76
  77 * Selections
  78
  79 * Various smaller cases to 'just draw something'
  80
  81   * Draw to a virtual device, and use the resulting bitmap (like the example
  82     above)
  83
  84 * Custom widgets (like the Header / Footer indicator button)
  85
  86 ## Dumping DrawingLayer Primitives as XML
  87
  88 For debugging purposes, it is possible to dump the drawinglayer primitives as
  89 an xml file. The drawinglayer xml dump can show possible problems with the
  90 rendering.
  91
  92 For example, in `emfio/qa/cppunit/emf/EmfImportTest.cxx`, one can write:
  93
  94     Primitive2DSequence aSequence = parseEmf(u"emfio/qa/cppunit/wmf/data/stockobject.emf");
  95     drawinglayer::Primitive2dXmlDump dumper;
  96     Primitive2DContainer aContainer(aSequence);
  97     dumper.dump(aContainer, "/tmp/drawyinglayer.xml");
  98
  99 Then, after invoking `make CppunitTest_emfio_emf`, `/tmp/drawyinglayer.xml` will
 100 be the dump of the drawinglayer primitives used to draw the emf file in
 101 LibreOffice. The top level tag will be <primitive2D>.