slideshow/source/engine/slide/layer.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: layer.hxx,v $
  10  * $Revision: 1.3 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef INCLUDED_SLIDESHOW_LAYER_HXX
  32 #define INCLUDED_SLIDESHOW_LAYER_HXX
  33
  34 #include <basegfx/range/b2dmultirange.hxx>
  35 #include <cppcanvas/spritecanvas.hxx>
  36
  37 #include "view.hxx"
  38 #include "animatableshape.hxx"
  39
  40 #include <boost/shared_ptr.hpp>
  41 #include <boost/weak_ptr.hpp>
  42 #include <boost/noncopyable.hpp>
  43 #include <boost/enable_shared_from_this.hpp>
  44
  45 #include <vector>
  46
  47
  48 namespace slideshow
  49 {
  50     namespace internal
  51     {
  52         class LayerEndUpdate;
  53
  54         /* Definition of Layer class */
  55
  56         /** This class represents one layer of output on a Slide.
  57
  58             Layers group shapes for a certain depth region of a slide.
  59
  60             Since slides have a notion of depth, i.e. shapes on it
  61             have a certain order in which they lie upon each other,
  62             this layering must be modeled. A prime example for this
  63             necessity are animations of shapes lying behind other
  64             shapes. Then, everything behind the animated shape will be
  65             in a background layer, the shape itself will be in an
  66             animation layer, and everything before it will be in a
  67             foreground layer (these layers are most preferrably
  68             modeled as XSprite objects internally).
  69
  70             @attention All methods of this class are only supposed to
  71             be called from the LayerManager. Normally, it shouldn't be
  72             possible to get hold of an instance of this class at all.
  73          */
  74         class Layer : public boost::enable_shared_from_this<Layer>,
  75                       private boost::noncopyable
  76         {
  77         public:
  78             typedef boost::shared_ptr<LayerEndUpdate> EndUpdater;
  79
  80             /** Create background layer
  81
  82                 This method will create a layer without a ViewLayer,
  83                 i.e. one that displays directly on the background.
  84
  85                 @param rMaxLayerBounds
  86                 Maximal bounds of this layer, in user
  87                 coordinates. This layer will never be larger or extend
  88                 outside these bounds.
  89              */
  90             static ::boost::shared_ptr< Layer > createBackgroundLayer( const basegfx::B2DRange& rMaxLayerBounds );
  91
  92             /** Create non-background layer
  93
  94                 This method will create a layer in front of the
  95                 background, to contain shapes that should appear in
  96                 front of animated objects.
  97
  98                 @param rMaxLayerBounds
  99                 Maximal bounds of this layer, in user
 100                 coordinates. This layer will never be larger or extend
 101                 outside these bounds.
 102              */
 103             static ::boost::shared_ptr< Layer > createLayer( const basegfx::B2DRange& rMaxLayerBounds );
 104
 105
 106             /////////////////////////////////////////////////////////////////////
 107
 108
 109             /** Predicate, whether this layer is the special
 110                 background layer
 111
 112                 This method is mostly useful for checking invariants.
 113              */
 114             bool isBackgroundLayer() const { return mbBackgroundLayer; }
 115
 116             /** Add a view to this layer.
 117
 118                 If the view is already added, this method does not add
 119                 it a second time, just returning the existing ViewLayer.
 120
 121                 @param rNewView
 122                 New view to add to this layer.
 123
 124                 @return the newly generated ViewLayer for this View
 125              */
 126             ViewLayerSharedPtr addView( const ViewSharedPtr& rNewView );
 127
 128             /** Remove a view
 129
 130                 This method removes the view from this Layer and all
 131                 shapes included herein.
 132
 133                 @return the ViewLayer of the removed Layer, if
 134                 any. Otherwise, NULL is returned.
 135              */
 136             ViewLayerSharedPtr removeView( const ViewSharedPtr& rView );
 137
 138             /** Notify that given ViewLayer has changed
 139
 140                 @param rChangedView
 141                 This view's layer will get resized. Afterwards, a
 142                 complete repaint might be necessary.
 143              */
 144             void viewChanged( const ViewSharedPtr& rChangedView );
 145
 146             /** Notify that all ViewLayer have changed
 147
 148                 This resizes all view layers. Afterwards, a complete
 149                 repaint might be necessary.
 150              */
 151             void viewsChanged();
 152
 153             /** Init shape with this layer's views
 154
 155                 @param rShape
 156                 The shape, that will subsequently display on this
 157                 layer's views
 158              */
 159             void setShapeViews( ShapeSharedPtr const& rShape ) const;
 160
 161
 162             /////////////////////////////////////////////////////////////////////
 163
 164
 165             /** Change layer priority range.
 166
 167                 The layer priority affects the position of the layer
 168                 in the z direction (i.e. before/behind which other
 169                 layers this one appears). The higher the prio, the
 170                 further on top of the layer stack this one appears.
 171
 172                 @param rPrioRange
 173                 The priority range of differing layers must not
 174                 intersect
 175              */
 176             void setPriority( const ::basegfx::B1DRange& rPrioRange );
 177
 178             /** Add an area that needs update
 179
 180                 @param rUpdateRange
 181                 Area on this layer that needs update
 182              */
 183             void addUpdateRange( ::basegfx::B2DRange const& rUpdateRange );
 184
 185             /** Whether any update ranges have been added
 186
 187                 @return true, if any non-empty addUpdateRange() calls
 188                 have been made since the last render()/update() call.
 189              */
 190             bool isUpdatePending() const { return !maUpdateAreas.isEmpty(); }
 191
 192             /** Update layer bound rect from shape bounds
 193              */
 194             void updateBounds( ShapeSharedPtr const& rShape );
 195
 196             /** Commit collected layer bounds to ViewLayer
 197
 198                 Call this method when you're done adding new shapes to
 199                 the layer.
 200
 201                 @return true, if layer needed a resize (which
 202                 invalidates its content - you have to repaint all
 203                 contained shapes!)
 204              */
 205             bool commitBounds();
 206
 207             /** Clear all registered update ranges
 208
 209                 This method clears all update ranges that are
 210                 registered at this layer.
 211              */
 212             void clearUpdateRanges();
 213
 214             /** Clear whole layer content
 215
 216                 This method clears the whole layer content. As a
 217                 byproduct, all update ranges are cleared as well. It
 218                 makes no sense to maintain them any further, since
 219                 they only serve for partial updates.
 220              */
 221             void clearContent();
 222
 223             /** Init layer update.
 224
 225                 This method initializes a full layer update of the
 226                 update area. When the last copy of the returned
 227                 EndUpdater is destroyed, the Layer leaves update mode
 228                 again.
 229
 230                 @return a update end RAII object.
 231             */
 232             EndUpdater beginUpdate();
 233
 234             /** Finish layer update
 235
 236                 Resets clipping and transformation to normal values
 237              */
 238             void endUpdate();
 239
 240             /** Check whether given shape is inside current update area.
 241
 242                 @return true, if the given shape is at least partially
 243                 inside the current update area.
 244             */
 245             bool isInsideUpdateArea( ShapeSharedPtr const& rShape ) const;
 246
 247         private:
 248             enum Dummy{ BackgroundLayer };
 249
 250             /** Create background layer
 251
 252                 This constructor will create a layer without a
 253                 ViewLayer, i.e. one that displays directly on the
 254                 background.
 255
 256                 @param rMaxLayerBounds
 257                 Maximal bounds of this layer, in user
 258                 coordinates. This layer will never be larger or extend
 259                 outside these bounds.
 260
 261                 @param eFlag
 262                 Dummy parameter, to disambiguate from normal layer
 263                 constructor
 264              */
 265             Layer( const basegfx::B2DRange& rMaxLayerBounds,
 266                    Dummy                    eFlag );
 267
 268             /** Create non-background layer
 269
 270                 This constructor will create a layer in front of the
 271                 background, to contain shapes that should appear in
 272                 front of animated objects.
 273
 274                 @param rMaxLayerBounds
 275                 Maximal bounds of this layer, in user
 276                 coordinates. This layer will never be larger or extend
 277                 outside these bounds.
 278              */
 279             explicit Layer( const basegfx::B2DRange& rMaxLayerBounds );
 280
 281             struct ViewEntry
 282             {
 283                 ViewEntry( const ViewSharedPtr&      rView,
 284                            const ViewLayerSharedPtr& rViewLayer ) :
 285                     mpView( rView ),
 286                     mpViewLayer( rViewLayer )
 287                 {}
 288
 289                 ViewSharedPtr      mpView;
 290                 ViewLayerSharedPtr mpViewLayer;
 291
 292                 // for generic algo access (which needs actual functions)
 293                 const ViewSharedPtr&      getView() const { return mpView; }
 294                 const ViewLayerSharedPtr& getViewLayer() const { return mpViewLayer; }
 295             };
 296
 297             typedef ::std::vector< ViewEntry > ViewEntryVector;
 298
 299             ViewEntryVector            maViewEntries;
 300             basegfx::B2DMultiRange     maUpdateAreas;
 301             basegfx::B2DRange          maBounds;
 302             basegfx::B2DRange          maNewBounds;
 303             const basegfx::B2DRange    maMaxBounds;       // maBounds is clipped against this
 304             bool                       mbBoundsDirty;     // true, if view layers need resize
 305             bool                       mbBackgroundLayer; // true, if this
 306                                                           // layer is the
 307                                                           // special
 308                                                           // background layer
 309             bool                       mbClipSet; // true, if beginUpdate set a clip
 310         };
 311
 312         typedef ::boost::shared_ptr< Layer >    LayerSharedPtr;
 313         typedef ::boost::weak_ptr< Layer >      LayerWeakPtr;
 314         typedef ::std::vector< LayerSharedPtr > LayerVector;
 315
 316     }
 317 }
 318
 319 #endif /* INCLUDED_SLIDESHOW_LAYER_HXX */