Added wxUSE_DC_CACHEING and associated code to wxMSW

Added EnableCache, CacheEnabled to wxDCBase
Added mask source args to DoBlit, Blit
Added cache testing code to dragimag sample
Added wxSystemOptions, regenerated makefiles


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@10962 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/category.tex

@@ -543,7 +543,8 @@ using any of them in the new programs:
 \twocolitem{\helpref{wxTimer}{wxtimer}}{Timer class}
 \twocolitem{\helpref{wxStopWatch}{wxstopwatch}}{Stop watch class}
 \twocolitem{\helpref{wxMimeTypesManager}{wxmimetypesmanager}}{MIME-types manager class}
-\twocolitem{\helpref{wxSystemSettings}{wxsystemsettings}}{System settings class}
+\twocolitem{\helpref{wxSystemSettings}{wxsystemsettings}}{System settings class for obtaining various global parameters}
+\twocolitem{\helpref{wxSystemOptions}{wxsystemoptions}}{System options class for run-time configuration}
 \twocolitem{\helpref{wxAcceleratorTable}{wxacceleratortable}}{Accelerator table}
 \twocolitem{\helpref{wxAutomationObject}{wxautomationobject}}{OLE automation class}
 \twocolitem{\helpref{wxFontMapper}{wxfontmapper}}{Font mapping, finding suitable font for given encoding}

docs/latex/wx/classes.tex

@@ -283,6 +283,7 @@
 \input propslv.tex
 \input tokenizr.tex
 \input sysclevt.tex
+\input sysopt.tex
 \input settings.tex
 \input tab.tex
 \input tabctrl.tex

docs/latex/wx/dc.tex

@@ -61,11 +61,11 @@ released for each drawing operation.
 
 \func{bool}{Blit}{\param{wxCoord}{ xdest}, \param{wxCoord}{ ydest}, \param{wxCoord}{ width}, \param{wxCoord}{ height},
   \param{wxDC* }{source}, \param{wxCoord}{ xsrc}, \param{wxCoord}{ ysrc}, \param{int}{ logicalFunc = wxCOPY},
-  \param{bool }{useMask = FALSE}}
+  \param{bool }{useMask = FALSE}, \param{wxCoord}{ xsrcMask = -1}, \param{wxCoord}{ ysrcMask = -1}}
 
 Copy from a source DC to this DC, specifying the destination
-coordinates, size of area to copy, source DC, source coordinates, and
-logical function.
+coordinates, size of area to copy, source DC, source coordinates,
+logical function, whether to use a bitmap mask, and mask source position.
 
 \wxheading{Parameters}
 
@@ -86,7 +86,7 @@ logical function.
 \docparam{logicalFunc}{Logical function to use: see \helpref{wxDC::SetLogicalFunction}{wxdcsetlogicalfunction}.}
 
 \docparam{useMask}{If TRUE, Blit does a transparent blit using the mask that is associated with the bitmap
-selected into the source device context. The Windows implementation does the following:
+selected into the source device context. The Windows implementation does the following if MaskBlt cannot be used:
 
 \begin{enumerate}
 \item Creates a temporary bitmap and copies the destination area into it.
@@ -103,8 +103,21 @@ and the background colour set to WHITE.
 
 This sequence of operations ensures that the source's transparent area need not be black,
 and logical functions are supported.
+
+{\bf Note:} on Windows, blitting with masks can be speeded up considerably by using 
+\helpref{DC cacheing}{wxdcenablecache}. You can also influence whether MaskBlt
+or the explicit mask blitting code above is used, by using \helpref{wxSystemOptions}{wxsystemoptions} and
+setting the {\bf no-maskblt} option to 1.
+
 }
 
+\docparam{xsrcMask}{Source x position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and ysrc
+will be assumed for the mask source position. Currently only implemented on Windows.}
+
+\docparam{ysrcMask}{Source y position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and ysrc
+will be assumed for the mask source position. Currently only implemented on Windows.}
+
+
 \wxheading{Remarks}
 
 There is partial support for Blit in wxPostScriptDC, under X.
@@ -115,6 +128,22 @@ See \helpref{wxMemoryDC}{wxmemorydc} for typical usage.
 
 \helpref{wxMemoryDC}{wxmemorydc}, \helpref{wxBitmap}{wxbitmap}, \helpref{wxMask}{wxmask}
 
+\membersection{wxDC::CacheEnabled}\label{wxdccacheenabled}
+
+\func{static bool}{CacheEnabled}{\void}
+
+On supported platforms (currently only Windows), returns TRUE
+if the DC cache is enabled. The DC cache
+can speed up the \helpref{Blit}{wxdcblit} operation when
+drawing a large number of masked bitmaps.
+
+If using the cache functions in your code, please test for the
+wxUSE\_DC\_CACHEING preprocessor symbol for portability.
+
+\wxheading{See also}
+
+\helpref{wxDC::EnableCache}{wxdcenablecache}, \helpref{wxDC::ClearCache}
+
 \membersection{wxDC::CalcBoundingBox}\label{wxdccalcboundingbox}
 
 \func{void}{CalcBoundingBox}{\param{wxCoord }{x}, \param{wxCoord }{y}}
@@ -133,6 +162,24 @@ Adds the specified point to the bounding box which can be retrieved with
 
 Clears the device context using the current background brush.
 
+\membersection{wxDC::ClearCache}\label{wxdcclearcache}
+
+\func{static void}{ClearCache}{\void}
+
+On supported platforms (currently only Windows), clears
+the contents of the DC cache (one bitmap and two Windows device contexts). The DC cache
+can speed up the \helpref{Blit}{wxdcblit} operation when
+drawing a large number of masked bitmaps. You should
+call ClearCache at the end of length DC operations if you wish to only use
+the cache transiently; you should also call it as your application exits.
+
+If using the cache functions in your code, please test for the
+wxUSE\_DC\_CACHEING preprocessor symbol for portability.
+
+\wxheading{See also}
+
+\helpref{wxDC::EnableCache}{wxdcenablecache}, \helpref{wxDC::CacheEnabled}
+
 \membersection{wxDC::CrossHair}\label{wxdccrosshair}
 
 \func{void}{CrossHair}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
@@ -370,6 +417,21 @@ text more precisely.
 but it is ignored by wxMSW. Thus, you should avoid using logical functions
 with this function in portable programs.
 
+\membersection{wxDC::EnableCache}\label{wxdcenablecache}
+
+\func{static void}{EnableCache}{\param{bool}{ enableCache}}
+
+On supported platforms (currently only Windows), enables the DC cache
+which can speed up the \helpref{Blit}{wxdcblit} operation when
+drawing a large number of masked bitmaps.
+
+If using the cache functions in your code, please test for the
+wxUSE\_DC\_CACHEING preprocessor symbol for portability.
+
+\wxheading{See also}
+
+\helpref{wxDC::CacheEnabled}{wxdccacheenabled}, \helpref{wxDC::ClearCache}
+
 \membersection{wxDC::EndDoc}\label{wxdcenddoc}
 
 \func{void}{EndDoc}{\void}

docs/latex/wx/sysopt.tex

@@ -0,0 +1,89 @@
+\section{\class{wxSystemOptions}}\label{wxsystemoptions}
+
+wxSystemOptions stores option/value pairs that wxWindows itself or
+applications can use to alter behaviour at run-time. It can be
+used to optimize behaviour that doesn't deserve a distinct API,
+but is still important to be able to configure.
+
+These options are currently recognised by wxWindows:
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf Option}}{{\bf Value}}
+\twocolitem{no-maskblt}{1 to never use WIN32's MaskBlt function, 0 to allow it to be used where possible. Default: 0.
+
+In some circumstances the MaskBlt function can be slower than using the fallback code, especially if using
+DC cacheing. By default, MaskBlt will be used where it is implemented by the operating system and driver.
+}
+\end{twocollist}
+
+The compile-time option to include or exclude this functionality
+is wxUSE\_SYSTEM\_OPTIONS.
+
+\wxheading{Derived from}
+
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/sysopt.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxSystemOptions::wxSystemOptions}
+
+\func{}{wxSystemOptions}{\void}
+
+Default constructor. You don't need to create an instance of wxSystemOptions
+since all of its functions are static.
+
+\membersection{wxSystemOptions::GetOption}\label{wxsystemoptionsgetoption}
+
+\constfunc{wxString}{GetOption}{\param{const wxString\&}{ name}}
+
+Gets an option. The function is case-insensitive to {\it name}.
+
+\wxheading{See also}
+
+\helpref{wxSystemOptions::SetOption}{wxsystemoptionssetoption},\rtfsp
+\helpref{wxSystemOptions::GetOptionInt}{wxsystemoptionsgetoptionint},\rtfsp
+\helpref{wxSystemOptions::HasOption}{wxsystemoptionshasoption}
+
+\membersection{wxSystemOptions::GetOptionInt}\label{wxsystemoptionsgetoptionint}
+
+\constfunc{int}{GetOptionInt}{\param{const wxString\&}{ name}}
+
+Gets an option as an integer. The function is case-insensitive to {\it name}.
+
+\wxheading{See also}
+
+\helpref{wxSystemOptions::SetOption}{wxsystemoptionssetoption},\rtfsp
+\helpref{wxSystemOptions::GetOption}{wxsystemoptionsgetoption},\rtfsp
+\helpref{wxSystemOptions::HasOption}{wxsystemoptionshasoption}
+
+\membersection{wxSystemOptions::HasOption}\label{wxsystemoptionshasoption}
+
+\constfunc{bool}{HasOption}{\param{const wxString\&}{ name}}
+
+Returns TRUE if the given option is present. The function is case-insensitive to {\it name}.
+
+\wxheading{See also}
+
+\helpref{wxSystemOptions::SetOption}{wxsystemoptionssetoption},\rtfsp
+\helpref{wxSystemOptions::GetOption}{wxsystemoptionsgetoption},\rtfsp
+\helpref{wxSystemOptions::GetOptionInt}{wxsystemoptionsgetoptionint}
+
+\membersection{wxSystemOptions::SetOption}\label{wxsystemoptionssetoption}
+
+\func{void}{SetOption}{\param{const wxString\&}{ name}, \param{const wxString\&}{ value}}
+
+\func{void}{SetOption}{\param{const wxString\&}{ name}, \param{int}{ value}}
+
+Sets an option. The function is case-insensitive to {\it name}.
+
+\wxheading{See also}
+
+\helpref{wxSystemOptions::GetOption}{wxsystemoptionsgetoption},\rtfsp
+\helpref{wxSystemOptions::GetOptionInt}{wxsystemoptionsgetoptionint},\rtfsp
+\helpref{wxSystemOptions::HasOption}{wxsystemoptionshasoption}
+