Rename wxBitmap::CreateWithLogicalSize() to CreateWithDIPSize()

The new name, recently introduced in 94716fd801 (Add
wxBitmap::CreateWithLogicalSize(), 2022-01-22), was perhaps more clear,
but also misleading and confusing because the postcondition

	CreateWithLogicalSize(size, 2).GetLogicalSize() == size

was not satisfied under MSW, so rename it once again, and hopefully
finally, because the new name is consistent with GetDIPSize() returning
the same size.

Also try to improve the documentation a bit more.

docs/doxygen/overviews/high_dpi.md

@@ -172,10 +172,10 @@ use "Logical", "Physical" or "DIP" in their names, the only exceptions are:
 
 - Size passed to wxBitmap constructors taking one, as well as the size returned
   by wxBitmap::GetWidth() and wxBitmap::GetHeight() is in physical pixels. You
-  can use wxBitmap::CreateWithLogicalSize() and wxBitmap::GetLogicalWidth(),
+  can use wxBitmap::CreateWithDIPSize() and wxBitmap::GetDIPSize() or
-  wxBitmap::GetLogicalHeight() and wxBitmap::GetLogicalSize() to use or get the
+  wxBitmap::GetLogicalSize() to use or get the size in DPI-independent or
-  size in logical pixels which must be used in any computations involving the
+  logical pixels (notably, the latter must be used in any computations
-  sizes expressed in logical units.
+  involving the sizes expressed in logical units).
 - Similarly, the size returned by wxBitmapBundle::GetPreferredBitmapSizeFor()
   is in physical pixels, but wxBitmapBundle::GetPreferredLogicalSizeFor() can
   be used to retrieve the same value in logical units.

include/wx/bitmap.h

@@ -178,13 +178,13 @@ public:
     virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH) = 0;
     virtual bool Create(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH) = 0;
 
-    bool CreateWithLogicalSize(const wxSize& sz,
+    bool CreateWithDIPSize(const wxSize& sz,
-                               double scale,
+                           double scale,
-                               int depth = wxBITMAP_SCREEN_DEPTH)
+                           int depth = wxBITMAP_SCREEN_DEPTH)
         { return DoCreate(sz, scale, depth); }
-    bool CreateWithLogicalSize(int width, int height,
+    bool CreateWithDIPSize(int width, int height,
-                               double scale,
+                           double scale,
-                               int depth = wxBITMAP_SCREEN_DEPTH)
+                           int depth = wxBITMAP_SCREEN_DEPTH)
         { return DoCreate(wxSize(width, height), scale, depth); }
 
     virtual int GetHeight() const = 0;
@@ -211,10 +211,10 @@ public:
     double GetLogicalHeight() const;
     wxSize GetLogicalSize() const;
 
-    // Old synonyms for CreateWithLogicalSize() and GetLogicalXXX() functions,
+    // Old synonyms for CreateWithDIPSize() and GetLogicalXXX() functions,
     // prefer the new names in the new code.
     bool CreateScaled(int w, int h, int d, double logicalScale)
-        { return CreateWithLogicalSize(w, h, logicalScale, d); }
+        { return CreateWithDIPSize(w, h, logicalScale, d); }
     double GetScaledWidth() const { return GetLogicalWidth(); }
     double GetScaledHeight() const { return GetLogicalHeight(); }
     wxSize GetScaledSize() const { return GetLogicalSize(); }

include/wx/msw/bitmap.h

@@ -159,13 +159,13 @@ public:
     virtual bool Create(int width, int height, const wxDC& dc);
     virtual bool Create(const void* data, wxBitmapType type, int width, int height, int depth = 1);
 
-    bool CreateWithLogicalSize(const wxSize& sz,
+    bool CreateWithDIPSize(const wxSize& sz,
-                               double scale,
+                           double scale,
-                               int depth = wxBITMAP_SCREEN_DEPTH);
+                           int depth = wxBITMAP_SCREEN_DEPTH);
-    bool CreateWithLogicalSize(int width, int height,
+    bool CreateWithDIPSize(int width, int height,
-                               double scale,
+                           double scale,
-                               int depth = wxBITMAP_SCREEN_DEPTH)
+                           int depth = wxBITMAP_SCREEN_DEPTH)
-        { return CreateWithLogicalSize(wxSize(width, height), scale, depth); }
+        { return CreateWithDIPSize(wxSize(width, height), scale, depth); }
 
     virtual bool LoadFile(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
     virtual bool SaveFile(const wxString& name, wxBitmapType type, const wxPalette *cmap = NULL) const;
@@ -191,9 +191,9 @@ public:
     void UseAlpha(bool use = true);
     void ResetAlpha() { UseAlpha(false); }
 
-    // old synonyms for CreateWithLogicalSize() and GetLogicalXXX() functions
+    // old synonyms for CreateWithDIPSize() and GetLogicalXXX() functions
     bool CreateScaled(int w, int h, int d, double logicalScale)
-        { return CreateWithLogicalSize(wxSize(w, h), logicalScale, d); }
+        { return CreateWithDIPSize(wxSize(w, h), logicalScale, d); }
     double GetScaledWidth() const { return GetLogicalWidth(); }
     double GetScaledHeight() const { return GetLogicalHeight(); }
     wxSize GetScaledSize() const { return GetLogicalSize(); }

interface/wx/bitmap.h

@@ -460,16 +460,21 @@ public:
     bool Create(int width, int height, const wxDC& dc);
 
     /**
-        Create a bitmap specifying its size in logical pixels and the scale
+        Create a bitmap specifying its size in DPI-independent pixels and the
-        factor to use.
+        scale factor to use.
 
         The physical size of the bitmap is obtained by multiplying the given
-        size in logical pixels by @a scale and rounding it to the closest
+        @a size by @a scale and rounding it to the closest integer.
-        integer.
+
+        After using this function the following postconditions are true:
+
+        - GetSize() returns @a size multiplied by @a scale
+        - GetDIPSize() returns @a size
+        - GetScaleFactor() returns @a scale
 
         @param size
-            The size of the bitmap in logical pixels. Both width and height
+            The size of the bitmap in DPI-independent pixels. Both width and
-            must be strictly positive.
+            height must be strictly positive.
         @param scale
             Scale factor used by the bitmap, see SetScaleFactor().
         @param depth
@@ -479,19 +484,19 @@ public:
 
         @since 3.1.6
      */
-    bool CreateWithLogicalSize(const wxSize& size,
+    bool CreateWithDIPSize(const wxSize& size,
-                               double scale,
+                           double scale,
-                               int depth = wxBITMAP_SCREEN_DEPTH);
+                           int depth = wxBITMAP_SCREEN_DEPTH);
 
     /// @overload
-    bool CreateWithLogicalSize(int width, int height,
+    bool CreateWithDIPSize(int width, int height,
-                               double scale,
+                           double scale,
-                               int depth = wxBITMAP_SCREEN_DEPTH);
+                           int depth = wxBITMAP_SCREEN_DEPTH);
 
     /**
         Create a bitmap with a scale factor.
 
-        This is an older synonym for CreateWithLogicalSize(), use the new
+        This is an older synonym for CreateWithDIPSize(), use the new
         function in the new code.
 
         @param width
@@ -577,7 +582,7 @@ public:
         Returns the size of bitmap in DPI-independent units.
 
         This assumes that the bitmap was created using the value of scale
-        factor corresponding to the current DPI (see CreateWithLogicalSize()
+        factor corresponding to the current DPI (see CreateWithDIPSize()
         and SetScaleFactor()) and returns its physical size divided by this
         scale factor.
 
@@ -895,7 +900,7 @@ public:
         which logical and physical pixels differ (i.e. wxOSX and wxGTK3, but
         not wxMSW).
 
-        When creating a new bitmap, CreateWithLogicalSize() can be used to
+        When creating a new bitmap, CreateWithDIPSize() can be used to
         specify the correct scale factor from the beginning.
 
         @since 3.1.6

src/common/animatecmn.cpp

@@ -148,7 +148,7 @@ void wxAnimationCtrlBase::UpdateStaticImage()
             m_bmpStaticReal.GetLogicalHeight() != sz.GetHeight())
         {
             // need to (re)create m_bmpStaticReal
-            if (!m_bmpStaticReal.CreateWithLogicalSize(sz,
+            if (!m_bmpStaticReal.CreateWithDIPSize(sz,
                                           bmpCurrent.GetScaleFactor(),
                                           bmpCurrent.GetDepth()))
             {

src/common/dcbufcmn.cpp

@@ -84,7 +84,7 @@ private:
 
         // we must always return a valid bitmap but creating a bitmap of
         // size 0 would fail, so create a 1*1 bitmap in this case
-        buffer->CreateWithLogicalSize(wxMax(w, 1), wxMax(h, 1), scale);
+        buffer->CreateWithDIPSize(wxMax(w, 1), wxMax(h, 1), scale);
 
         return buffer;
     }

src/msw/bitmap.cpp

@@ -763,7 +763,7 @@ bool wxBitmap::Create(int width, int height, const wxDC& dc)
         return false;
 }
 
-bool wxBitmap::CreateWithLogicalSize(const wxSize& size, double scale, int depth)
+bool wxBitmap::CreateWithDIPSize(const wxSize& size, double scale, int depth)
 {
     if ( !Create(size*scale, depth) )
         return false;

src/osx/cocoa/toolbar.mm

@@ -599,7 +599,7 @@ void wxToolBarTool::UpdateImages()
         // TODO CS this should use the best current representation, or optionally iterate through all
         wxSize sz = m_bmpNormal.GetDefaultSize();
         m_alternateBitmap = wxBitmap();
-        m_alternateBitmap.Create(sz.x, sz.y, -1); // TODO CS m_alternateBitmap.CreateWithLogicalSize(sz, m_bmpNormal.GetScaleFactor());
+        m_alternateBitmap.Create(sz.x, sz.y, -1); // TODO CS m_alternateBitmap.CreateWithDIPSize(sz, m_bmpNormal.GetScaleFactor());
         m_alternateBitmap.UseAlpha();
         wxMemoryDC dc;
 

src/osx/cocoa/utils.mm

@@ -559,7 +559,7 @@ wxBitmap wxWindowDCImpl::DoGetAsBitmap(const wxRect *subrect) const
 
     const wxSize bitmapSize(subrect ? subrect->GetSize() : m_window->GetSize());
     wxBitmap bitmap;
-    bitmap.CreateWithLogicalSize(bitmapSize, m_contentScaleFactor);
+    bitmap.CreateWithDIPSize(bitmapSize, m_contentScaleFactor);
 
     NSView* view = (NSView*) m_window->GetHandle();
     if ( [view isHiddenOrHasHiddenAncestor] == NO )
@@ -591,7 +591,7 @@ wxBitmap wxWindowDCImpl::DoGetAsBitmap(const wxRect *subrect) const
 
         CGRect r = CGRectMake( 0 , 0 , CGImageGetWidth(cgImageRef)  , CGImageGetHeight(cgImageRef) );
 
-        // The bitmap created by wxBitmap::CreateWithLogicalSize() above is scaled,
+        // The bitmap created by wxBitmap::CreateWithDIPSize() above is scaled,
         // so we need to adjust the coordinates for it.
         r.size.width /= m_contentScaleFactor;
         r.size.height /= m_contentScaleFactor;

src/osx/core/bitmap.cpp

@@ -961,7 +961,7 @@ wxBitmap wxBitmap::GetSubBitmap(const wxRect &rect) const
 
     wxBitmap ret;
     double scale = GetScaleFactor();
-    ret.CreateWithLogicalSize( rect.GetSize(), scale, GetDepth() );
+    ret.CreateWithDIPSize( rect.GetSize(), scale, GetDepth() );
     wxASSERT_MSG( ret.IsOk(), wxT("GetSubBitmap error") );
     if ( HasAlpha() )
         ret.UseAlpha() ;
@@ -1039,7 +1039,7 @@ bool wxBitmap::Create(int w, int h, int d)
 bool wxBitmap::Create(int w, int h, const wxDC& dc)
 {
     double factor = dc.GetContentScaleFactor();
-    return CreateWithLogicalSize(w, h, factor);
+    return CreateWithDIPSize(w, h, factor);
 }
 
 bool wxBitmap::DoCreate(const wxSize& size, double scale, int d)

src/propgrid/propgrid.cpp

@@ -4621,7 +4621,7 @@ void wxPropertyGrid::OnResize( wxSizeEvent& event )
             int w = wxMax(width, 250);
             int h = wxMax(height + dblh, 400);
             m_doubleBuffer = new wxBitmap;
-            m_doubleBuffer->CreateWithLogicalSize( w, h, scaleFactor );
+            m_doubleBuffer->CreateWithDIPSize( w, h, scaleFactor );
         }
         else
         {
@@ -4635,7 +4635,7 @@ void wxPropertyGrid::OnResize( wxSizeEvent& event )
                 if ( h < (height+dblh) ) h = height + dblh;
                 delete m_doubleBuffer;
                 m_doubleBuffer = new wxBitmap;
-                m_doubleBuffer->CreateWithLogicalSize( w, h, scaleFactor );
+                m_doubleBuffer->CreateWithDIPSize( w, h, scaleFactor );
             }
         }
     }

src/stc/PlatWX.cpp

@@ -299,7 +299,7 @@ void SurfaceImpl::InitPixMap(int width, int height, Surface *surface, WindowID w
     if (width < 1) width = 1;
     if (height < 1) height = 1;
     bitmap = new wxBitmap();
-    bitmap->CreateWithLogicalSize(width, height,(GETWIN(winid))->GetContentScaleFactor());
+    bitmap->CreateWithDIPSize(width, height,(GETWIN(winid))->GetContentScaleFactor());
     mdc->SelectObject(*bitmap);
 }
 

tests/graphics/bmpbundle.cpp

@@ -173,7 +173,7 @@ TEST_CASE("BitmapBundle::Scale", "[bmpbundle][scale]")
     // setting scale factor works correctly for bitmaps, as wxBitmapBundle does
     // this internally.
     wxBitmap bmp;
-    bmp.CreateWithLogicalSize(8, 8, 2);
+    bmp.CreateWithDIPSize(8, 8, 2);
 #ifdef wxHAS_DPI_INDEPENDENT_PIXELS
     CHECK( bmp.GetLogicalSize() == wxSize(8, 8) );
 #endif