include/drawinglayer/primitive2d/BufferedDecompositionPrimitive2D.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 <drawinglayer/drawinglayerdllapi.h>
  23 #include <drawinglayer/primitive2d/Primitive2DContainer.hxx>
  24 #include <drawinglayer/primitive2d/baseprimitive2d.hxx>
  25 #include <salhelper/timer.hxx>
  26
  27 namespace drawinglayer::geometry
  28 {
  29 class ViewInformation2D;
  30 }
  31
  32 namespace drawinglayer::primitive2d
  33 {
  34 /** BufferedDecompositionPrimitive2D class
  35
  36     Baseclass for all C++ implementations of css::graphic::XPrimitive2D
  37     which want to buffer the decomposition result
  38
  39     Buffering the decomposition is the most-used buffering and is thus used my most
  40     primitive implementations which support a decomposition as base class.
  41
  42     The buffering is done by holding the last decomposition in the local parameter
  43     maBuffered2DDecomposition. The default implementation of get2DDecomposition checks
  44     if maBuffered2DDecomposition is empty. If yes, it uses create2DDecomposition
  45     to create the content. In all cases, maBuffered2DDecomposition is returned.
  46
  47     For view-dependent primitives derived from Primitive2DBufferDecomposition more needs
  48     to be done when the decomposition depends on parts of the parameter ViewInformation2D.
  49     This defines a standard method for processing these:
  50
  51     Implement a view-dependent get2DDecomposition doing the following steps:
  52     (a) Locally extract needed parameters from ViewInformation2D to new, local parameters
  53         (this may be a complete local copy of ViewInformation2D)
  54     (b) If a buffered decomposition exists, check if one of the new local parameters
  55         differs from the corresponding locally remembered (as member) ones. If yes,
  56         clear maBuffered2DDecomposition
  57     (d) call baseclass::get2DDecomposition which will use create2DDecomposition
  58         to fill maBuffered2DDecomposition if it's empty
  59     (e) copy the new local parameters to the corresponding locally remembered ones
  60         to identify if a new decomposition is needed at the next call
  61     (f) return maBuffered2DDecomposition
  62  */
  63 class DRAWINGLAYERCORE_DLLPUBLIC BufferedDecompositionPrimitive2D : public BasePrimitive2D
  64 {
  65 private:
  66     // exclusive helper for Primitive2DFlusher
  67     friend void flushBufferedDecomposition(BufferedDecompositionPrimitive2D&);
  68
  69     /// a sequence used for buffering the last create2DDecomposition() result
  70     Primitive2DReference maBuffered2DDecomposition;
  71
  72     /// offer callback mechanism to flush buffered content timer-based
  73     ::rtl::Reference<::salhelper::Timer> maCallbackTimer;
  74     mutable std::mutex maCallbackLock;
  75     sal_uInt16 maCallbackSeconds;
  76
  77 protected:
  78     /** access methods to maBuffered2DDecomposition. The usage of this methods may allow
  79         later thread-safe stuff to be added if needed. Only to be used by getDecomposition()
  80         implementations for buffering the last decomposition.
  81      */
  82     const Primitive2DReference& getBuffered2DDecomposition() const;
  83     void setBuffered2DDecomposition(Primitive2DReference rNew);
  84
  85     /** method which is to be used to implement the local decomposition of a 2D primitive. */
  86     virtual Primitive2DReference
  87     create2DDecomposition(const geometry::ViewInformation2D& rViewInformation) const = 0;
  88
  89     // when changing from null (which is inactive) to a count of seconds, the
  90     // callback mechanism to flush buffered content timer-based will be activated.
  91     // it is protected since the idea is that this gets called in the constructor
  92     // of derived classes.
  93     void setCallbackSeconds(sal_uInt16 nNew) { maCallbackSeconds = nNew; }
  94
  95 public:
  96     // constructor/destructor
  97     BufferedDecompositionPrimitive2D();
  98     virtual ~BufferedDecompositionPrimitive2D();
  99
 100     /** The getDecomposition default implementation will on demand use create2DDecomposition() if
 101         maBuffered2DDecomposition is empty. It will set maBuffered2DDecomposition to this obtained decomposition
 102         to buffer it. If the decomposition is also ViewInformation2D-dependent, this method needs to be
 103         overridden and the ViewInformation2D for the last decomposition need to be remembered, too, and
 104         be used in the next call to decide if the buffered decomposition may be reused or not.
 105      */
 106     virtual void
 107     get2DDecomposition(Primitive2DDecompositionVisitor& rVisitor,
 108                        const geometry::ViewInformation2D& rViewInformation) const override;
 109 };
 110
 111 } // end of namespace drawinglayer::primitive2d
 112
 113 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */