Update TRANSPARENT keywords

[geographika]

As noted in the thread at https://lists.osgeo.org/pipermail/mapserver-dev/2023-October/017023.html - the SCALEBAR and LEGEND TRANSPARENT keywords are still required to create transparent scalebars and legends on non-transparent maps.

[mateusmedeiros]

Sorry if I'm coming across as bothersome!

I'm trying to understand why I had the behaviour I described in the thread in the first place. I don't know the codebase too well and there's no amount of reading I can do in a single day that will match your familiarity with it, but in my case from the behaviour of the mapfile it seemed that by default the SCALEBAR transparency was basically inherited from the OUTPUTFORMAT instead of actually being OFF by default (which is what the new comment in the docs describe).

From the looks I've took at the code (and there's a fair share of possible wrong assumptions in my interpretation), going from initMap and initScalebar, it seems that the actual default value of the TRANSPARENT option in the scalebar is MS_NOOVERRIDE.

From there, inside msDrawScalebar we have the following:

https://github.com/MapServer/MapServer/blob/24d36f842c243f96eba88ff896db1bf34d8a687a/src/mapscale.c#L240-L248

  msApplyOutputFormat(&format, map->outputformat, map->scalebar.transparent);

  if (map->scalebar.transparent == MS_OFF) {
    if (!MS_VALID_COLOR(map->scalebar.imagecolor))
      MS_INIT_COLOR(map->scalebar.imagecolor, 255, 255, 255, 255);
  }
  image = msImageCreate(map->scalebar.width, sy, format, map->web.imagepath,
                        map->web.imageurl, map->resolution, map->defresolution,
                        &map->scalebar.imagecolor);

I'm assuming format's transparent is what will actually be used since msImageCreate doesn't receive any parameter taken from map->scalebar.transparent directly nor the whole of map->scalebar.

Inside msApplyOutputFormat we have this to check if there is a need to override values in map->outputformat (*format) according to map->scalebar.transparent (transparent):

https://github.com/MapServer/MapServer/blob/24d36f842c243f96eba88ff896db1bf34d8a687a/src/mapoutput.c#L667-L668

  if (transparent != MS_NOOVERRIDE && !format->transparent != !transparent)
    change_needed = MS_TRUE;

So if transparent here equals MS_NOOVERRIDE, it will consider there's no change needed and will end up basically just applying map->outputformat into format directly.

As you can see, lots of potentially wrong assumptions on my part (like the default value being the same that is set in initMap > initScalebar and msImageCreate simply using format to determine if it should draw the scalebar with or without transparency), so sorry if I'm talking a whole bunch of junk!

[geographika]

@mateusmedeiros - the Default is off is from the original docs which probably hadn't been updated for several years as it was marked as deprecated. Is the following more accurate to what you've experienced?

By default, a scalebar will inherit the same transparency setting as the map :ref:OUTPUTFORMAT. However, this flag can be used to override this setting, allowing, for example, a transparent scalebar to be embedded in a non-transparent map.

[mateusmedeiros]

@mateusmedeiros - the Default is off is from the original docs which probably hadn't been updated for several years as it was marked as deprecated. Is the following more accurate to what you've experienced?

By default, a scalebar will inherit the same transparency setting as the map :ref:OUTPUTFORMAT. However, this flag can be used to override this setting, allowing, for example, a transparent scalebar to be embedded in a non-transparent map.

Perfect. 👌 It matches both the behaviour I got and what I interpreted from the glance I gave in the source code. Thanks!

[jmckenna]

thanks @geographika