drawinglayer/source/processor2d/vclhelperbufferdevice.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #pragma once
  21
  22 #include <vcl/virdev.hxx>
  23
  24 // Helper class *exclusively* for VclProcessor2D. It should only
  25 // be used internally, see current four usages. It is used to
  26 // render something with mask or transparence (see MaskPrimitive2D,
  27 // UnifiedTransparencePrimitive2D and TransparencePrimitive2D) or
  28 // as tooling for preparing pixelized output in the renderer
  29 // (see PatternFillPrimitive2D) if that is faster.
  30 //
  31 // To do so, initializing this instance takes over a lot of work
  32 // from you:
  33 // - It initializes a 'Content' VDev which is buffered (since it had
  34 // shown that re-allocating all the time is slower). It checks
  35 // visibility and all usages initializing this should check for
  36 // isVisible() after construction.
  37 // - It pre-initializes the 'Content' VDev with blitting the content
  38 // of the target VDev.
  39 // - It offers to get a 'Transparence' VDev (also from the buffer) if
  40 // needed.
  41 //
  42 // If 'Transparence' is/was used, it combines as needed to paint
  43 // all buffered stuff to target VDev when calling paint().
  44 // Caution: It is designed to use *either* a fixed transparence in
  45 // the paint()-call *or* a fill TransparenceChannel using a
  46 // 'Transparence' VDev. It is *not* designed to use/combine
  47 // both - it's simply not needed for it's intended purpose/usage.
  48 //
  49 // Painting transparent works based on a simple principle: It first
  50 // blits the original content of the target VDev. Then the content
  51 // is painted on top of that, plus a Transparence/Mask prepared.
  52 // The combination always works since unchanged pixels will not
  53 // change, independent of the transparence value [0..255] it gets
  54 // mixed with. Or the other way around: Only pixels changed on the
  55 // Content *can* be changed by transparence values.
  56 //
  57 // This is 2.5 times faster than first painting to a
  58 // 'combined' VDev that supports transparency, as is used by the
  59 // presentation engine.
  60 // For the mentioned factor refer to:
  61 //   Patch to demonstrate former and now repaint differences
  62 //   https://gerrit.libreoffice.org/c/core/+/129301
  63 //   git fetch https://git.libreoffice.org/core refs/changes/01/129301/3 && git cherry-pick FETCH_HEAD
  64 //
  65 // Note: This principle only works when the target is RGB, so
  66 // useful for EditViews like for PrimitiveRenderers where this is
  67 // the case. For usage with GBA targets the starting conditions
  68 // would have to be modified to not blend against the initial color
  69 // of 'Content' (usually COL_WHITE).
  70 //
  71 // After having finished the rework of ShadowPrimitive2D,
  72 // SoftEdgePrimitive2D and GlowPrimitive2D (see commits:)
  73 //      e735ad1c57cddaf17d6ffc0cf15b5e14fa63c4ad
  74 //      707b0c328a282d993fa33b618083d20b6c521de6
  75 //      c2d1458723c66c2fd717a112f89f773226adc841
  76 // which used the impBufferDevice in such a mode combined with
  77 // mentioned 'combined' transparence VDev it is now possible
  78 // to return to this former, much faster method.
  79 //
  80 // Please do *not* hack/use this helper class, better create
  81 // a new one fitting your/the intended purpose. I do not want
  82 // to see losing performance by this getting modified again.
  83 //
  84 // Note: Using that 'combined' transparence VDev is not really
  85 // recommended, it may vanish anytime. That it works with
  86 // PrimitiveRenderers *at all* is neither designed nor tested
  87 // or recommended - it's pure coincidence.
  88 //
  89 // I hope that for the future all this will vanish by getting to
  90 // fully RGBA-capable devices - what is planned and makes sense.
  91
  92 namespace drawinglayer
  93 {
  94 class impBufferDevice
  95 {
  96     OutputDevice& mrOutDev;
  97     VclPtr<VirtualDevice> mpContent;
  98     VclPtr<VirtualDevice> mpAlpha;
  99     tools::Rectangle maDestPixel;
 100
 101 public:
 102     impBufferDevice(OutputDevice& rOutDev, const basegfx::B2DRange& rRange);
 103     ~impBufferDevice();
 104
 105     void paint(double fTrans = 0.0);
 106     bool isVisible() const { return !maDestPixel.IsEmpty(); }
 107     VirtualDevice& getContent();
 108     VirtualDevice& getTransparence();
 109 };
 110 } // end of namespace drawinglayer
 111
 112 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */