Re: [PATCH 1/9] ui/gtk: Document scale and coordinate handling

[Weifeng Liu <weifeng.liu.z@gmail.com>]

Hi Gerd,

On Mon, 2025-05-12 at 13:46 +0200, Gerd Hoffmann wrote:
> On Sun, May 11, 2025 at 03:33:11PM +0800, Weifeng Liu wrote:
> > The existence of multiple scaling factors forces us to deal with
> > various
> > coordinate systems and this would be confusing. It would be
> > beneficial
> > to define the concepts clearly and use consistent representation
> > for
> > variables in different coordinates.
> > 
> > Signed-off-by: Weifeng Liu <weifeng.liu.z@gmail.com>
> > ---
> >  ui/gtk.c | 65
> > ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 65 insertions(+)
> > 
> > diff --git a/ui/gtk.c b/ui/gtk.c
> > index 982037b2c0..9f3171abc5 100644
> > --- a/ui/gtk.c
> > +++ b/ui/gtk.c
> > @@ -800,6 +800,71 @@ void
> > gd_update_monitor_refresh_rate(VirtualConsole *vc, GtkWidget
> > *widget)
> >  #endif
> >  }
> >  
> > +/**
> > + * DOC: Coordinate handling.
> > + *
> > + * We are coping with sizes and positions in various coordinates
> > and the
> > + * handling of these coordinates is somewhat confusing. It would
> > benefit us
> > + * all if we define these coordinates explicitly and clearly.
> > Besides, it's
> > + * also helpful to follow the same naming convention for variables
> > + * representing values in different coordinates.
> > + *
> > + * I. Definitions
> > + *
> > + * - (guest) buffer coordinate: this is the coordinates that the
> > guest will
> > + *   see. The x/y offsets and width/height specified in commands
> > sent by
> > + *   guest is basically in buffer coordinate.
> > + *
> > + * - (host) pixel coordinate: this is the coordinate in pixel
> > level on the
> > + *   host destop. A window/widget of width 300 in pixel coordinate
> > means it
> > + *   occupies 300 pixels horizontally.
> > + *
> > + * - (host) logical window coordinate: the existence of global
> > scaling
> > + *   factor in desktop level makes this kind of coordinate play a
> > role. It
> > + *   always holds that (logical window size) * (global scale
> > factor) =
> > + *   (pixel size).
> > + *
> > + * - global scale factor: this is specified in desktop level and
> > is
> > + *   typically invariant during the life cycle of the process.
> > Users with
> > + *   high-DPI monitors might set this scale, for example, to 2, in
> > order to
> > + *   make the UI look larger.
> > + *
> > + * - zooming scale: this can be freely controlled by the QEMU user
> > to zoom
> > + *   in/out the guest content.
> > + *
> > + * II. Representation
> > + *
> > + * We'd like to use consistent representation for variables in
> > different
> > + * coordinates:
> > + * - buffer coordinate: prefix fb
> > + * - pixel coordinate: prefix p
> > + * - logical window coordinate: prefix w
> > + *
> > + * For scales:
> > + * - global scale factor: prefix gs
> > + * - zooming scale: prefix scale/s
> > + *
> > + * Example: fbw, pw, ww for width in different coordinates
> > + *
> > + * III. Equation
> > + *
> > + * - fbw * gs * scale_x = pw
> 
> Well.  That is one possible approach (and this is what qemu is doing
> today, for historical reasons, because most code dates back to pre
> high-dpi days).
> 
> A possible alternative would be to go for fbw * scale_x = pw, i.e.
> let
> the guest run in pixel coordinates instead of window coordinates. 
> The
> guest would do the high-dpi scaling then.  That requires setting
> physical display width and height in ui_info, so the guest can figure
> what the display resolution is and go into high-dpi mode if needed.
> 

Thanks for your suggestion. Sounds like code could be simplified and be
much easier to understand in this way. I will investigate it on top of
this change.

Best regards,
Weifeng

> We probably also need a non-high-dpi compatibility mode for old
> guests.
> That mode would start with "zooming scale = global scale" instead of
> "zooming scale = 1", and the dpi calculation would have to consider
> that too.
> 
> (maybe best done on top of this nice cleanup).
> 
> take care,
>   Gerd