[GRASS-dev] documenting the display lib in grass7

[Glynn Clements]

Hamish wrote:

> I am trying to write some new module-level display code for grass 7 but
> am finding it a bit hard going due to lack of library documentation and
> reference modules. Basically, I don't know what's going on and am looking
> for some breadcrumbs to follow...
> 
> most D_*() functions are missing Doxygen comments saying what they do
> (e.g. D_get_src() and D_get_dst()),

D_get_src() returns the frame bounds in the source coordinate system
(used by D_* functions), while D_get_dst() returns the frame bounds in
the destination coordinate system (used by R_* commands).

The various D_setup() commands all set the destination coordinate
system to the current frame reported by R_get_window().

D_setup() sets the source coordinate system to the current region, and
adjusts the destination coordinate system to preserve the aspect
ratio.

D_setup2() sets the source coordinate system to its arguments, and if
the fit argument is non-zero, adjusts the destination coordinate
system to preserve the aspect ratio.

D_setup_unity() sets the source coordinate system to match the
destination coordinate system, so that D_* functions use the same
coordinate system as R_* functions.

Look at setup.c and cnversions.c for details.

> and lib/display/displaylib.dox has
> not been updated to give an overview of the new architecture.
> 
> d.graph seems to ignore the -m flag,

It uses it to set the coordinate system:

    if (mapcoords->answer) {
	mapunits = TRUE;
	D_setup(0);
    }
    else {
	D_setup2(0, 0, 100, 0, 0, 100);
	mapunits = FALSE;
    }

If -m is given, the source coordinate system is set to geographic
coordinates, otherwise it's percentages, with 0,0 at the bottom-left
and 100,100 at the top-right.

> and d.barscale and d.legend still
> include (int) casts when converting % of frame to eastings,northings
> which I expect are no longer needed.

Probably not.

> I don't know what d.modules to trust
> and don't want to copy/perpetuate old broken code & methods.
> 
> 
> my immediate questions are:
>  - how to make the code frame compatible? is that desired? (yes please)

Can you elaborate?

>  - how to convert x%,y% of frame to eastings and northings and back;
>     are D_a_to_b() cnversion functions still for general use?

The preferred approach is to use D_setup2() to configure the source
coordinate system such that you can pass coordinates directly to other
D_* functions.

>  - is 0%,0% considered lower left or upper left of frame? (standardized)

Whichever is preferred. The display library can handle both top > bot
(positive-Y is up) and top < bot (positive-Y is down) for source
coordinates.

>  - is the native display units pixels, percent, or map-coords?

The source coordinate system is whatever you want it to be. Unless
explicitly changed, the destination coordinate system is whatever the
driver uses (currently points for the PS driver and pixels for
everything else, with 0,0 at the top-left).

The main reason for application code to care about the destination
coordinate system is that line width and text size are currently
specified in destination coordinates (however, D_get_text_box()
returns source coordinates).

Also, if you want a unit size which doesn't change with the frame
size, one destination unit is a better choice than one source unit
(although neither is ideal).

The general idea is that application code should avoid caring (or even
knowing) about the destination coordinate system.

Ultimately, there should be a defined (and user-configurable) "unit
size" which is used to scale line widths, text, symbols, tick marks,
etc so that you don't get illegible output at high resolutions.

The leading option involves adding the ability to push/pop coordinate
systems, so you would e.g. D_move_abs() to a specific geographic
coordinate, D_push() to create a temporary coordinate system with the
origin at the current position, D_unit_scale(1.0) to use "unit" scale
(i.e. 1 unit equals one point, or one pixel, or N pixels if
oversampling), draw an icon using unit coordinates, then D_pop() to
restore the geographic coordinate system.

Text sizes and line widths would be treated as units regardless of the
active coordinate system (I'm assuming that you wouldn't want to
specify line widths in metres etc, as if they were geographic
features).

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