summaryrefslogtreecommitdiffstats
path: root/include/canvas
diff options
context:
space:
mode:
Diffstat (limited to 'include/canvas')
-rw-r--r--include/canvas/canvastools.hxx560
-rw-r--r--include/canvas/canvastoolsdllapi.h35
-rw-r--r--include/canvas/elapsedtime.hxx163
3 files changed, 758 insertions, 0 deletions
diff --git a/include/canvas/canvastools.hxx b/include/canvas/canvastools.hxx
new file mode 100644
index 000000000..63aea6239
--- /dev/null
+++ b/include/canvas/canvastools.hxx
@@ -0,0 +1,560 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed
+ * with this work for additional information regarding copyright
+ * ownership. The ASF licenses this file to you under the Apache
+ * License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of
+ * the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+#ifndef INCLUDED_CANVAS_CANVASTOOLS_HXX
+#define INCLUDED_CANVAS_CANVASTOOLS_HXX
+
+#include <com/sun/star/uno/Reference.hxx>
+#include <com/sun/star/uno/Sequence.hxx>
+#include <com/sun/star/uno/RuntimeException.hpp>
+#include <osl/diagnose.h>
+#include <rtl/ustring.hxx>
+#include <sal/log.hxx>
+
+#include <math.h>
+#include <string.h>
+#include <vector>
+#include <limits>
+
+#include <canvas/canvastoolsdllapi.h>
+
+namespace basegfx
+{
+ class B2DHomMatrix;
+ class B2DRange;
+ class B2IRange;
+ class B2IPoint;
+ class B2DPolyPolygon;
+}
+
+namespace com::sun::star::geometry
+{
+ struct RealSize2D;
+ struct IntegerSize2D;
+ struct AffineMatrix2D;
+ struct Matrix2D;
+}
+
+namespace com::sun::star::rendering
+{
+ struct RenderState;
+ struct ViewState;
+ struct IntegerBitmapLayout;
+ class XCanvas;
+ struct Texture;
+ class XIntegerBitmapColorSpace;
+}
+
+namespace com::sun::star::awt
+{
+ struct Rectangle;
+ class XWindow2;
+}
+
+namespace com::sun::star::beans {
+ struct PropertyValue;
+}
+
+class Color;
+class OutputDevice;
+
+namespace canvas
+{
+ namespace tools
+ {
+ /** Compute the next highest power of 2 of a 32-bit value
+
+ Code devised by Sean Anderson, in good ole HAKMEM
+ tradition.
+
+ @return 1 << (lg(x - 1) + 1)
+ */
+ inline sal_uInt32 nextPow2( sal_uInt32 x )
+ {
+ --x;
+ x |= x >> 1;
+ x |= x >> 2;
+ x |= x >> 4;
+ x |= x >> 8;
+ x |= x >> 16;
+
+ return ++x;
+ }
+
+ /**
+ *
+ * Count the number of 1-bits of a n-bit value
+ *
+ */
+
+ /** Round given floating point value down to next integer
+ */
+ inline sal_Int32 roundDown( const double& rVal )
+ {
+ return static_cast< sal_Int32 >( floor( rVal ) );
+ }
+
+ /** Round given floating point value up to next integer
+ */
+ inline sal_Int32 roundUp( const double& rVal )
+ {
+ return static_cast< sal_Int32 >( ceil( rVal ) );
+ }
+
+ /** Create a RealSize2D with both coordinate values set to +infinity
+ */
+ CANVASTOOLS_DLLPUBLIC css::geometry::RealSize2D createInfiniteSize2D();
+
+
+ // View- and RenderState utilities
+
+
+ CANVASTOOLS_DLLPUBLIC css::rendering::RenderState&
+ initRenderState( css::rendering::RenderState& renderState );
+
+ CANVASTOOLS_DLLPUBLIC css::rendering::ViewState&
+ initViewState( css::rendering::ViewState& viewState );
+
+ CANVASTOOLS_DLLPUBLIC ::basegfx::B2DHomMatrix&
+ getViewStateTransform( ::basegfx::B2DHomMatrix& transform,
+ const css::rendering::ViewState& viewState );
+
+ CANVASTOOLS_DLLPUBLIC css::rendering::ViewState&
+ setViewStateTransform( css::rendering::ViewState& viewState,
+ const ::basegfx::B2DHomMatrix& transform );
+
+ CANVASTOOLS_DLLPUBLIC ::basegfx::B2DHomMatrix&
+ getRenderStateTransform( ::basegfx::B2DHomMatrix& transform,
+ const css::rendering::RenderState& renderState );
+
+ CANVASTOOLS_DLLPUBLIC css::rendering::RenderState&
+ setRenderStateTransform( css::rendering::RenderState& renderState,
+ const ::basegfx::B2DHomMatrix& transform );
+
+ CANVASTOOLS_DLLPUBLIC css::rendering::RenderState&
+ appendToRenderState( css::rendering::RenderState& renderState,
+ const ::basegfx::B2DHomMatrix& transform );
+
+ CANVASTOOLS_DLLPUBLIC css::rendering::RenderState&
+ prependToRenderState( css::rendering::RenderState& renderState,
+ const ::basegfx::B2DHomMatrix& transform );
+
+ CANVASTOOLS_DLLPUBLIC ::basegfx::B2DHomMatrix&
+ mergeViewAndRenderTransform( ::basegfx::B2DHomMatrix& transform,
+ const css::rendering::ViewState& viewState,
+ const css::rendering::RenderState& renderState );
+
+
+ // Matrix utilities
+
+
+ CANVASTOOLS_DLLPUBLIC css::geometry::AffineMatrix2D&
+ setIdentityAffineMatrix2D( css::geometry::AffineMatrix2D& matrix );
+
+ CANVASTOOLS_DLLPUBLIC css::geometry::Matrix2D&
+ setIdentityMatrix2D( css::geometry::Matrix2D& matrix );
+
+
+ // Special utilities
+
+
+ /** Calc the bounding rectangle of a transformed rectangle.
+
+ The method applies the given transformation to the
+ specified input rectangle, and returns the bounding box of
+ the resulting output area.
+
+ @param o_Rect
+ Output rectangle
+
+ @param i_Rect
+ Input rectangle
+
+ @param i_Transformation
+ Transformation to apply to the input rectangle
+
+ @return a reference to the resulting rectangle
+ */
+ CANVASTOOLS_DLLPUBLIC ::basegfx::B2DRange& calcTransformedRectBounds( ::basegfx::B2DRange& o_Rect,
+ const ::basegfx::B2DRange& i_Rect,
+ const ::basegfx::B2DHomMatrix& i_Transformation );
+
+ /** Calc a transform that maps the upper, left corner of a
+ rectangle to the origin.
+
+ The method is a specialized version of
+ calcRectToRectTransform() (Removed now), mapping the input rectangle's
+ the upper, left corner to the origin, and leaving the size
+ untouched.
+
+ @param o_transform
+ Output parameter, to receive the resulting transformation
+ matrix.
+
+ @param i_srcRect
+ Input parameter, specifies the original source
+ rectangle. The resulting transformation will exactly map
+ the source rectangle's upper, left corner to the origin.
+
+ @param i_transformation
+ The original transformation matrix. This is changed with
+ translations (if necessary), to exactly map the source
+ rectangle to the origin.
+
+ @return a reference to the resulting transformation matrix
+
+ @see calcRectToRectTransform()
+ @see calcTransformedRectBounds()
+ */
+ CANVASTOOLS_DLLPUBLIC ::basegfx::B2DHomMatrix& calcRectToOriginTransform( ::basegfx::B2DHomMatrix& o_transform,
+ const ::basegfx::B2DRange& i_srcRect,
+ const ::basegfx::B2DHomMatrix& i_transformation );
+
+ /** Check whether a given rectangle is within another
+ transformed rectangle.
+
+ This method checks for polygonal containedness, i.e. the
+ transformed rectangle is not represented as an axis-aligned
+ rectangle anymore (like calcTransformedRectBounds()), but
+ polygonal. Thus, the insideness test is based on tight
+ bounds.
+
+ @param rContainedRect
+ This rectangle is checked, whether it is fully within the
+ transformed rTransformRect.
+
+ @param rTransformRect
+ This rectangle is transformed, and then checked whether it
+ fully contains rContainedRect.
+
+ @param rTransformation
+ This transformation is applied to rTransformRect
+ */
+ CANVASTOOLS_DLLPUBLIC bool isInside( const ::basegfx::B2DRange& rContainedRect,
+ const ::basegfx::B2DRange& rTransformRect,
+ const ::basegfx::B2DHomMatrix& rTransformation );
+
+ /** Clip a scroll to the given bound rect
+
+ @param io_rSourceArea
+ Source area to scroll. The resulting clipped source area
+ is returned therein.
+
+ @param io_rDestPoint
+ Destination point of the scroll (upper, left corner of
+ rSourceArea after the scroll). The new, resulting
+ destination point is returned therein.q
+
+ @param o_ClippedAreas
+ Vector of rectangles in the <em>destination</em> area
+ coordinate system, which are clipped away from the source
+ area, and thus need extra updates (i.e. they are not
+ correctly copy from the scroll operation, since there was
+ no information about them in the source).
+
+ @param rBounds
+ Bounds to clip against.
+
+ @return false, if the resulting scroll area is empty
+ */
+ CANVASTOOLS_DLLPUBLIC bool clipScrollArea( ::basegfx::B2IRange& io_rSourceArea,
+ ::basegfx::B2IPoint& io_rDestPoint,
+ ::std::vector< ::basegfx::B2IRange >& o_ClippedAreas,
+ const ::basegfx::B2IRange& rBounds );
+
+ /** Clip a blit between two differently surfaces.
+
+ This method clips source and dest rect for a clip between
+ two differently clipped surfaces, such that the resulting
+ blit rects are fully within both clip areas.
+
+ @param io_rSourceArea
+ Source area of the blit. Returned therein is the computed
+ clipped source area.
+
+ @param io_rDestPoint
+ Dest area of the blit. Returned therein is the computed
+ clipped dest area.
+
+ @param rSourceBounds
+ Clip bounds of the source surface
+
+ @param rDestBounds
+ Clip bounds of the dest surface
+
+ @return false, if the resulting blit is empty, i.e. fully
+ clipped away.
+ */
+ CANVASTOOLS_DLLPUBLIC ::basegfx::B2IRange spritePixelAreaFromB2DRange( const ::basegfx::B2DRange& rRange );
+
+ /** Retrieve various internal properties of the actual canvas implementation.
+
+ This method retrieves a bunch of internal, implementation-
+ and platform-dependent values from the canvas
+ implementation. Among them are for example operating
+ system window handles. The actual layout and content of
+ the returned sequence is dependent on the component
+ implementation, undocumented and subject to change.
+
+ @param i_rxCanvas
+ Input parameter, the canvas representation for which the device information
+ is to be retrieved
+
+ @param o_rxParams
+ Output parameter, the sequence of Anys that hold the device parameters. Layout is as described above
+
+ @return A reference to the resulting sequence of parameters
+ */
+ CANVASTOOLS_DLLPUBLIC css::uno::Sequence< css::uno::Any >& getDeviceInfo(
+ const css::uno::Reference< css::rendering::XCanvas >& i_rxCanvas,
+ css::uno::Sequence< css::uno::Any >& o_rxParams );
+
+ /** Return a color space for a default RGBA integer format
+
+ Use this method for dead-simple bitmap implementations,
+ that map all their formats to 8888 RGBA color.
+ */
+ CANVASTOOLS_DLLPUBLIC css::uno::Reference< css::rendering::XIntegerBitmapColorSpace> const & getStdColorSpace();
+
+ /** Return a color space for a default RGB integer format
+
+ Use this method for dead-simple bitmap implementations,
+ that map all their formats to 8888 RGB color (the last byte
+ is unused).
+ */
+ CANVASTOOLS_DLLPUBLIC css::uno::Reference< css::rendering::XIntegerBitmapColorSpace> const & getStdColorSpaceWithoutAlpha();
+
+ /** Return a memory layout for a default RGBA integer format
+
+ Use this method for dead-simple bitmap implementations,
+ that map all their formats to 8888 RGBA color.
+ */
+ CANVASTOOLS_DLLPUBLIC css::rendering::IntegerBitmapLayout getStdMemoryLayout(
+ const css::geometry::IntegerSize2D& rBitmapSize );
+
+ /// Convert standard 8888 RGBA color to vcl color
+ CANVASTOOLS_DLLPUBLIC css::uno::Sequence<sal_Int8> colorToStdIntSequence( const ::Color& rColor );
+
+ // Modelled closely after boost::numeric_cast, only that we
+ // issue some trace output here and throw a RuntimeException
+
+ /** Cast numeric value into another (numeric) data type
+
+ Apart from converting the numeric value, this template
+ also checks if any overflow, underflow, or sign
+ information is lost (if yes, it throws an
+ uno::RuntimeException.
+ */
+ template< typename Target, typename Source > inline Target numeric_cast( Source arg )
+ {
+ // typedefs abbreviating respective trait classes
+ typedef ::std::numeric_limits< Source > SourceLimits;
+ typedef ::std::numeric_limits< Target > TargetLimits;
+
+#undef min
+#undef max
+
+ if( ( arg<0 && !TargetLimits::is_signed) || // losing the sign here
+ ( SourceLimits::is_signed && arg<TargetLimits::min()) || // underflow will happen
+ ( arg>TargetLimits::max() ) ) // overflow will happen
+ {
+# if OSL_DEBUG_LEVEL > 2
+ SAL_WARN("canvas", "numeric_cast detected data loss");
+#endif
+ throw css::uno::RuntimeException(
+ "numeric_cast detected data loss",
+ nullptr );
+ }
+
+ return static_cast<Target>(arg);
+ }
+
+ CANVASTOOLS_DLLPUBLIC css::awt::Rectangle getAbsoluteWindowRect(
+ const css::awt::Rectangle& rRect,
+ const css::uno::Reference< css::awt::XWindow2 >& xWin );
+
+ /** Retrieve for small bound marks around each corner of the given rectangle
+ */
+ CANVASTOOLS_DLLPUBLIC ::basegfx::B2DPolyPolygon getBoundMarksPolyPolygon( const ::basegfx::B2DRange& rRange );
+
+ /** Calculate number of gradient "strips" to generate (takes
+ into account device resolution)
+
+ @param nColorSteps
+ Maximal integer difference between all color stops, needed
+ for smooth gradient color differences
+ */
+ CANVASTOOLS_DLLPUBLIC int calcGradientStepCount( ::basegfx::B2DHomMatrix& rTotalTransform,
+ const css::rendering::ViewState& viewState,
+ const css::rendering::RenderState& renderState,
+ const css::rendering::Texture& texture,
+ int nColorSteps );
+
+ /** A very simplistic map for ASCII strings and arbitrary value
+ types.
+
+ This class internally references a constant, static array of
+ sorted MapEntries, and performs a binary search to look up
+ values for a given query string. Note that this map is static,
+ i.e. not meant to be extended at runtime.
+
+ @tpl ValueType
+ The value type this map should store, associated with an ASCII
+ string.
+ */
+ template< typename ValueType > class ValueMap
+ {
+ public:
+ struct MapEntry
+ {
+ const char* maKey;
+ ValueType maValue;
+ };
+
+ /** Create a ValueMap for the given array of MapEntries.
+
+ @param pMap
+ Pointer to a <em>static</em> array of MapEntries. Must
+ live longer than this object! Make absolutely sure that
+ the string entries passed via pMap are ASCII-only -
+ everything else might not yield correct string
+ comparisons, and thus will result in undefined behaviour.
+
+ @param nEntries
+ Number of entries for pMap
+
+ @param bCaseSensitive
+ Whether the map query should be performed case sensitive
+ or not. When bCaseSensitive is false, all MapEntry strings
+ must be lowercase!
+ */
+ ValueMap( const MapEntry* pMap,
+ ::std::size_t nEntries,
+ bool bCaseSensitive ) :
+ mpMap( pMap ),
+ mnEntries( nEntries ),
+ mbCaseSensitive( bCaseSensitive )
+ {
+#ifdef DBG_UTIL
+ // Ensure that map entries are sorted (and all lowercase, if this
+ // map is case insensitive)
+ const OString aStr( pMap->maKey );
+ if( !mbCaseSensitive &&
+ aStr != aStr.toAsciiLowerCase() )
+ {
+ SAL_WARN("canvas", "ValueMap::ValueMap(): Key is not lowercase " << pMap->maKey);
+ }
+
+ if( mnEntries <= 1 )
+ return;
+
+ for( ::std::size_t i=0; i<mnEntries-1; ++i, ++pMap )
+ {
+ if( !mapComparator(pMap[0], pMap[1]) &&
+ mapComparator(pMap[1], pMap[0]) )
+ {
+ SAL_WARN("canvas", "ValueMap::ValueMap(): Map is not sorted, keys are wrong, "
+ << pMap[0].maKey << " and " << pMap[1].maKey);
+ OSL_FAIL( "ValueMap::ValueMap(): Map is not sorted" );
+ }
+
+ const OString aStr2( pMap[1].maKey );
+ if( !mbCaseSensitive &&
+ aStr2 != aStr2.toAsciiLowerCase() )
+ {
+ SAL_WARN("canvas", "ValueMap::ValueMap(): Key is not lowercase" << pMap[1].maKey);
+ }
+ }
+#endif
+ }
+
+ /** Lookup a value for the given query string
+
+ @param rName
+ The string to lookup. If the map was created with the case
+ insensitive flag, the lookup is performed
+ case-insensitive, otherwise, case-sensitive.
+
+ @param o_rResult
+ Output parameter, which receives the value associated with
+ the query string. If no value was found, the referenced
+ object is kept unmodified.
+
+ @return true, if a matching entry was found.
+ */
+ bool lookup( const OUString& rName,
+ ValueType& o_rResult ) const
+ {
+ // rName is required to contain only ASCII characters.
+ // TODO(Q1): Enforce this at upper layers
+ OString aKey( OUStringToOString( mbCaseSensitive ? rName : rName.toAsciiLowerCase(),
+ RTL_TEXTENCODING_ASCII_US ) );
+ MapEntry aSearchKey =
+ {
+ aKey.getStr(),
+ ValueType()
+ };
+
+ const MapEntry* pEnd = mpMap+mnEntries;
+ const MapEntry* pRes = ::std::lower_bound( mpMap,
+ pEnd,
+ aSearchKey,
+ &mapComparator );
+ if( pRes != pEnd )
+ {
+ // place to _insert before_ found - is it equal to
+ // the search key?
+ if( strcmp( pRes->maKey, aSearchKey.maKey ) == 0 )
+ {
+ // yep, correct entry found
+ o_rResult = pRes->maValue;
+ return true;
+ }
+ }
+
+ // not found
+ return false;
+ }
+
+ private:
+ static bool mapComparator( const MapEntry& rLHS,
+ const MapEntry& rRHS )
+ {
+ return strcmp( rLHS.maKey,
+ rRHS.maKey ) < 0;
+ }
+
+ const MapEntry* mpMap;
+ ::std::size_t mnEntries;
+ bool mbCaseSensitive;
+ };
+
+ CANVASTOOLS_DLLPUBLIC void clipOutDev(const css::rendering::ViewState& viewState,
+ const css::rendering::RenderState& renderState,
+ OutputDevice& rOutDev,
+ OutputDevice* p2ndOutDev=nullptr);
+
+ CANVASTOOLS_DLLPUBLIC void extractExtraFontProperties(const css::uno::Sequence<css::beans::PropertyValue>& rExtraFontProperties,
+ sal_uInt32& rEmphasisMark);
+ }
+}
+
+#endif /* INCLUDED_CANVAS_CANVASTOOLS_HXX */
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/include/canvas/canvastoolsdllapi.h b/include/canvas/canvastoolsdllapi.h
new file mode 100644
index 000000000..a3748371a
--- /dev/null
+++ b/include/canvas/canvastoolsdllapi.h
@@ -0,0 +1,35 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed
+ * with this work for additional information regarding copyright
+ * ownership. The ASF licenses this file to you under the Apache
+ * License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of
+ * the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+#ifndef INCLUDED_CANVAS_CANVASTOOLSDLLAPI_H
+#define INCLUDED_CANVAS_CANVASTOOLSDLLAPI_H
+
+#include <sal/config.h>
+#include <sal/types.h>
+
+#if defined(CANVASTOOLS_DLLIMPLEMENTATION)
+#define CANVASTOOLS_DLLPUBLIC SAL_DLLPUBLIC_EXPORT
+#else
+#define CANVASTOOLS_DLLPUBLIC SAL_DLLPUBLIC_IMPORT
+#endif
+#define CANVASTOOLS_DLLPRIVATE SAL_DLLPRIVATE
+
+#endif
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
diff --git a/include/canvas/elapsedtime.hxx b/include/canvas/elapsedtime.hxx
new file mode 100644
index 000000000..cf73af960
--- /dev/null
+++ b/include/canvas/elapsedtime.hxx
@@ -0,0 +1,163 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed
+ * with this work for additional information regarding copyright
+ * ownership. The ASF licenses this file to you under the Apache
+ * License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of
+ * the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+#ifndef INCLUDED_CANVAS_ELAPSEDTIME_HXX
+#define INCLUDED_CANVAS_ELAPSEDTIME_HXX
+
+#include <canvas/canvastoolsdllapi.h>
+#include <memory>
+
+namespace canvas::tools
+{
+ /** Calculate elapsed time.
+
+ This class provides several time-measurement and
+ -management functions. In its simplest use-case, it
+ measures the time from its creation.
+ */
+ class CANVASTOOLS_DLLPUBLIC ElapsedTime
+ {
+ public:
+ /** Create a new ElapsedTime object
+
+ The moment of construction starts the time
+ measurement. That means, a subsequent getElapsedTime()
+ call will return the time difference between object
+ creation and getElapsedTime() call.
+ */
+ ElapsedTime();
+
+ /** Creates a new ElapsedTime object based on another
+ timer.
+
+ The moment of construction starts the time
+ measurement. That means, a subsequent getElapsedTime()
+ call will return the time difference between object
+ creation and getElapsedTime() call. All time values
+ are not taken from the system's time base, but from
+ the provided timer.
+ */
+ ElapsedTime( std::shared_ptr<ElapsedTime> xTimeBase );
+
+ /** Reset the time
+
+ The instance of the reset() call starts the time
+ measurement from scratch. That means, a subsequent
+ getElapsedTime() call will return the time difference
+ between reset() and getElapsedTime() call.
+ */
+ void reset();
+
+ /** Query the elapsed time
+
+ This method returns the elapsed time in seconds
+ between either the construction of this object, or the
+ last reset() call, if any (but see the time modulation
+ methods below, for means to modify the otherwise
+ continuous flow of time).
+
+ @return the elapsed time in seconds.
+ */
+ double getElapsedTime() const;
+
+ /** Pauses the running timer.
+
+ This method stops the time, as returned by this
+ object, until continueTimer() is called. During this
+ period, getElapsedTime() will always return the same
+ time value (i.e. the instant when pauseTimer() was
+ called).
+ */
+ void pauseTimer();
+
+ /** Continues the paused timer.
+
+ This method re-enables the time flow, that is, time
+ starts running again for clients calling
+ getElapsedTime(). The (subtle) difference to the
+ holdTimer/releaseTimer() methods below is, that there
+ is no perceived time 'jump' between the pauseTimer()
+ call and the continueTimer() call, i.e. the time
+ starts over with the same value it has stopped on
+ pauseTimer().
+ */
+ void continueTimer();
+
+ /** Adjusts the timer, hold and pause times.
+
+ This method modifies the time as returned by this
+ object by the specified amount. This affects the time
+ as returned by getElapsedTime(), regardless of the
+ mode (e.g. paused, or on hold).
+
+ @param fOffset
+ This value will be added to the current time, i.e. the
+ next call to getElapsedTime() (when performed
+ immediately) will be adjusted by fOffset.
+ */
+ void adjustTimer( double fOffset );
+
+ /** Holds the current time.
+
+ This call makes the timer hold the current time
+ (e.g. getElapsedTime() will return the time when
+ holdTimer() was called), while the underlying time is
+ running on. When releaseTimer() is called, the time
+ will 'jump' to the then-current, underlying time. This
+ is equivalent to pressing the "interim time" button on
+ a stop watch, which shows this stopped time, while the
+ clock keeps running internally.
+ */
+ void holdTimer();
+
+ /** Releases a held timer.
+
+ After this call, the timer again returns the running
+ time on getElapsedTime().
+ */
+ void releaseTimer();
+
+ private:
+ static double getSystemTime();
+ double getCurrentTime() const;
+ double getElapsedTimeImpl() const; // does not set m_fLastQueriedTime
+
+ const std::shared_ptr<ElapsedTime> m_pTimeBase;
+
+ /// To validate adjustTimer() calls with bLimitToLastQueriedTime=true
+ mutable double m_fLastQueriedTime;
+
+ /// Start time, from which the difference to the time base is returned
+ double m_fStartTime;
+
+ /// Instant, when last pause or hold started, relative to m_fStartTime
+ double m_fFrozenTime;
+
+ /// True, when in pause mode
+ bool m_bInPauseMode;
+
+ /// True, when in hold mode
+ bool m_bInHoldMode;
+ };
+
+}
+
+#endif /* INCLUDED_CANVAS_ELAPSEDTIME_HXX */
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */