[GRASS-dev] Display library documentation?

[Glynn Clements]

Moritz Lennert wrote:

> Glynn, as you are the one who significantly rewrote the display library, 
> do you have any documentation or notes stored somewhere ?

No. And I'm not familiar with the parts related to symbols; I haven't
touched that (beyond keeping it in sync with other changes to the
display library).

So far as coordinates go, for drawing geographic data, the usual
procedure is to call D_setup() and use cartographic coordinates
directly. For other data (e.g. legends), D_setup2() sets a
user-defined coordinate system while D_setup_unity() allows screen
coordinates to be used directly.

The library deals with 3 coordinate systems:

U (user) coordinates are used by most D_* functions which take
coordinates (the exceptions being the functions which convert
coordinates from other coordinate systems).

A (array) coordinates correspond to the region grid, and are used
implicitly for drawing raster data.

D (display) coordinates are screen pixel coordinates. The display
library converts U and A coordinates to D coordinates, which are
passed to driver functions (COM_*).

The low-level functions for setting coordinate systems and performing
conversions are in cnversions.c. Higher-level convenience functions
for setting coordinate systems are in setup.c.

D_setup() sets the U coordinate system to cartographic coordinates so
that the current region fits exactly inside the current display frame
while maintaining aspect the ratio.

D_setup2() sets the U coordinate system to a user-defined coordinate
system so that the specified rectangle fits exactly inside the current
display frame while optionally maintaining the aspect ratio.

D_setup_unity() sets the U coordinate system to match the D coordinate
system. This exists mainly to simplify the transition for existing
code.

-- 
Glynn Clements <glynn at gclements.plus.com>