From b9a84dcae5db4c7936be625373efb86903a1d0c7 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Tue, 28 Jun 2022 22:44:33 +0200
Subject: [PATCH 1/2] Improve wxMemoryDC documentation

Try to explain the difference between SelectObject() and
SelectObjectAsSource() more clearly.
---
 interface/wx/dcmemory.h | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/interface/wx/dcmemory.h b/interface/wx/dcmemory.h
index 19e3a78e4a..d7c4dfa3f9 100644
--- a/interface/wx/dcmemory.h
+++ b/interface/wx/dcmemory.h
@@ -76,13 +76,11 @@ public:
     wxMemoryDC(wxBitmap& bitmap);
 
     /**
-        Works exactly like SelectObjectAsSource() but this is the function you
-        should use when you select a bitmap because you want to modify it, e.g.
-        drawing on this DC.
+        Allow using this device context object to modify the given bitmap
+        contents.
 
-        Using SelectObjectAsSource() when modifying the bitmap may incur some
-        problems related to wxBitmap being a reference counted object (see
-        @ref overview_refcount).
+        Note that if you need to only use the existing bitmap contents instead
+        of modifying it, you should use SelectObjectAsSource() instead.
 
         Before using the updated bitmap data, make sure to select it out of
         context first either by selecting ::wxNullBitmap into the device
@@ -91,22 +89,25 @@ public:
         If the bitmap is already selected in this device context, nothing is
         done. If it is selected in another context, the function asserts and
         drawing on the bitmap won't work correctly.
-
-        @see wxDC::DrawBitmap()
     */
     void SelectObject(wxBitmap& bitmap);
 
     /**
         Selects the given bitmap into the device context, to use as the memory
-        bitmap. Selecting the bitmap into a memory DC allows you to draw into
-        the DC (and therefore the bitmap) and also to use wxDC::Blit() to copy
-        the bitmap to a window. For this purpose, you may find wxDC::DrawIcon()
-        easier to use instead.
+        bitmap.
+
+        Selecting the bitmap as source into a memory DC allows you to copy its
+        contents to another device context using wxDC::Blit(). Note that using
+        wxDC::DrawBitmap() or wxDC::DrawIcon() is a simpler way to do the same
+        thing.
+
+        @note Modifying a bitmap selected only as a source may not work
+        correctly and can notably modify the other bitmaps sharing the same
+        data due to the use of reference counting (see @ref overview_refcount).
 
         If the argument is ::wxNullBitmap (or some other uninitialised wxBitmap)
-        the current bitmap is selected out of the device context, and the
-        original bitmap restored, allowing the current bitmap to be destroyed
-        safely.
+        the current bitmap is selected out of the device context, allowing the
+        current bitmap to be destroyed safely.
     */
     void SelectObjectAsSource(const wxBitmap& bitmap);
 

From b95f2b699d99d63f68376c6e80a2e441c1ee39be Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Tue, 28 Jun 2022 22:50:24 +0200
Subject: [PATCH 2/2] Clarify that wxDC::CopyAttributes() doesn't copy scaling
 factor

Also show an example of setting the scaling factor in wxMemoryDC
documentation.
---
 interface/wx/dc.h       |  3 +++
 interface/wx/dcmemory.h | 19 +++++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/interface/wx/dc.h b/interface/wx/dc.h
index 52a9905206..09b5015897 100644
--- a/interface/wx/dc.h
+++ b/interface/wx/dc.h
@@ -1500,6 +1500,9 @@ public:
             - Background brush
             - Layout direction
 
+        Note that the scaling factor is not considered to be an attribute of
+        wxDC and is @e not copied by this function.
+
         @param dc
             A valid (i.e. its IsOk() must return @true) source device context.
      */
diff --git a/interface/wx/dcmemory.h b/interface/wx/dcmemory.h
index d7c4dfa3f9..b30bd19ee6 100644
--- a/interface/wx/dcmemory.h
+++ b/interface/wx/dcmemory.h
@@ -38,6 +38,25 @@
 
     This happens automatically when wxMemoryDC object goes out of scope.
 
+    Note that the scaling factor of the bitmap determines the scaling factor
+    used by this device context, so when using a memory device context as a
+    back buffer for a window, you should typically create the bitmap using the
+    same scale factor as used by the window, e.g.
+    @code
+    void MyWindow::OnPaint(wxPaintEvent&)
+    {
+        wxBitmap bmp;
+        bmp.CreateWithDIPSize(GetClientSize(), GetDPIScaleFactor());
+        {
+            wxMemoryDC memdc(bmp);
+            ... use memdc to draw on the bitmap ...
+        }
+
+        wxPaintDC dc(this);
+        dc.DrawBitmap(bmp, wxPoint(0, 0));
+    }
+    @endcode
+
     @library{wxcore}
     @category{dc}