map_SetFlag

Set the value of a flag for a map (see flag IDs, below.)

bool CExtAPI::map_SetFlag(ZMAP hMap, long FlagID, bool FlagValue);

False if:

• hMap is not a valid map.
• FlagID is not an allowed value.
• Another error occurred (consult L3DT event log in such cases.)

True otherwise.

The following flag IDs are defined in CExtAPI_defines.h:

All flags are false by default.

MAPFLAG_READY indicates that the map is not in use by a calculation, and is ready to be displayed or saved. L3DT will set this flag after loading a map, or after a calculation has completed. Plugins should set this flag after initialising a map with map_Init and having done whatever it is that plugins do to maps (calculations, hopefully), so that the map may be saved / rendered OK.

You do not need to set MAPFLAG_SAVED. L3DT will do this when the map is saved/loaded.

You do not need to set MAPFLAG_MOSAIC. L3DT will do this when a mosaic is created or loaded.

You may set MAPFLAG_INVALID when an operation on one map has invalidated the contents of another, and you wish to force the user to re-calculate the invalidated map. For instance, a modification to the heightfield should cause the water map, salinity map, attributes map, terrain normals, light map and texture map to be invalidated, because they are all calculated (ultimately) from the heightfield. Similarly, a change to the light map should invalidate the texture map if the light map is baked-on to the texture, but not if lighting wasn't applied to the texture.

Setting MAPFLAG_INVALID is considered more polite than outright destruction of an invalidated map with map_Free, which can upset some users if they're not expecting it. MAPFLAG_INVALID will allow the user to save the invalidated map should they want to retain the data, whereas map_Free sends the bits to the great /dev/null in the sky.

However, setting MAPFLAG_INVALID will still annoy users if it is set inappropriately. As an example of this, changing the climate in a pixel of the design map should invalidate the attributes map because it depends on the climates, but it must not invalidate the heightfield or the water map, because those maps are not affected by climates. If in doubt, don't set the flag and let the user work out which maps they have to re-do.

MAPFLAG_MODIFIED is a rather important flag. When you click 'Save' in L3DT, each map will only be saved if MAPFLAG_READY is true, and either MAPFLAG_SAVED is false or MAPFLAG_MODIFIED is true. That is to say, a map will only be saved if it is ready to be saved, and if it either has not been saved before, or if it has been modified since it was last saved.

This means if you modify a map that has been saved before, your changes will only be saved if you set MAPFLAG_MODIFIED to true. For reasons of performance, MAPFLAG_MODIFIED is not automatically set by L3DT/Zeolite every time you call map_SetPixel, so the responsibility rests with you to ensure the flag is set after your calculations are completed.

You cannot combine flags with the bitwise or operator '|' in map_SetFlag/GetFlag; each flag must be handled individually. There is no good reason for this, other than I wrote this bit of the program before I really knew what I was doing with bitwise stuff. It's too late to change now, I'm afraid.