I've been looking fairly closely at the coordinate system of VCL. I understood it fairly well, but as I have a Pro subscription of Gemini, I asked it to look at it for me to tell me how it thinks it works. Here is what is came up with:
If you’ve ever worked on a complex UI rendering engine, you know that placing a single pixel on the screen is rarely as simple as draw(x, y). A single coordinate actually exists in several different "realities" simultaneously.
In LibreOffice’s VCL (Visual Components Library), a coordinate has to travel through up to five distinct spatial dimensions to get from the mathematical purity of a document model to the physical LED pixels on your monitor.
If you get an offset wrong or apply a scaling factor out of order, your text disappears off the page, your borders render fuzzy, or your PDF exports break entirely. To fix these issues and modernize the rendering stack, we have to establish a strict, predictable pipeline.
Here is a deep dive into the five coordinate spaces of the LibreOffice VCL, and the math required to traverse them.
The 5 Coordinate Spaces
Think of these spaces as a series of nested Russian dolls. To get to the center (the document), you have to open them one by one.
1. Absolute Logic (Document Space)
This is the pure, mathematical space of the document itself.
Units: Defined by the
MapMode(e.g., 1/100th of a millimeter for high-precision printing).Origin (0,0): The absolute top-left corner of the page or document canvas.
The Variable: Represented simply as
nXornY.
2. Logic Units (Pipeline Space)
This is an intermediate staging area. The coordinate is still in logical document units, but it has been intentionally shifted.
The Shift:
mnOutOffLogic.Why it exists: This is an artificial shift applied to the document origin. It is frequently used when VCL needs to render a specific sub-section or "tile" of a document without actually changing the underlying coordinates of the objects themselves.
3. View Space (Viewport Space)
Welcome to the realm of pixels—specifically, pixels relative to the viewport (the scrollable area of the application).
The Transformation: To get here, we multiply the Logic Units by the DPI and Zoom scale (
mfMapScX / mfMapScY).The Shift:
mnMapOfsX / mnMapOfsY(The Mapping Offset).Why it exists: The origin (0,0) here is the top-left of your current scroll position. As you scroll down a Writer document, the mapping offset changes, shifting the view without altering the document.
4. Window Space (Client Space)
These are pixels relative to the GUI window frame itself.
The Shift:
mnOutOffOrigX / mnOutOffOrigY(The VCL Pixel Offset).Why it exists: The origin (0,0) is the top-left corner of the specific LibreOffice window or UI widget you are interacting with. VCL uses this offset internally to account for things like scrollbars, widget borders, or docking areas inside a window. This is the coordinate space where your mouse click events natively arrive.
5. Device Space (Physical Space)
The final destination. These are absolute pixels mapped to your physical hardware.
The Shift:
mnOutOffX / mnOutOffY(The Screen Origin).Why it exists: The origin (0,0) is the top-left corner of your physical monitor. This is the coordinate system that the underlying operating system graphics APIs (like CoreGraphics on macOS, Cairo on Linux, or GDI/DirectWrite on Windows) require to actually illuminate a pixel on your screen.
The Mathematical Pipeline
To safely traverse these spaces without causing "double-subtraction" bugs or off-by-one pixel errors, we chain the transitions together in a strict sequence.
Here is the Forward Path (converting a Document coordinate to a Physical Screen pixel):
Absolute Logic Units: Add the logical offset.
LogicUnits = nX + mnOutOffLogicXLogic Units View: Apply the zoom scale, then add the scroll offset.
View = (LogicUnits * mfMapScX) + mnMapOfsXView Window: Add the internal VCL widget offset.
Window = View + mnOutOffOrigXWindow Device: Add the physical screen position.
Device = Window + mnOutOffX
When handling a mouse click, we run this exact pipeline in reverse (The Inverse Path), carefully subtracting the offsets and dividing by the scale to figure out exactly which 1/100th of a millimeter the user clicked on.
Why Sub-Pixel Accuracy Matters
Historically, rendering engines used integer math (tools::Long) for these transitions. If a line ended up at pixel 10.7, it was truncated to 10. For basic UI elements, this was fine.
However, modern graphics rely heavily on anti-aliasing (B2D rendering) and high-fidelity vector exports (PDFs). If you truncate a coordinate too early in the pipeline, you lose the fractional data. When you eventually scale that truncated coordinate back up, that tiny fractional loss multiplies into massive visual artifacts—lines appear to "shimmer" when scrolling, or text glyphs collide with each other.
By upgrading this pipeline to handle high-precision double math at every stage (Sub-Pixel stages), LibreOffice can pass mathematically perfect coordinates to the OS-level drawing APIs, ensuring that your documents look perfectly crisp at any zoom level.
