Bug #1503 ยป 0032-vision.h-Update-module-documentation-comment.patch
| common/vision.h | ||
|---|---|---|
|
/* common */
|
||
|
#include "fc_types.h"
|
||
|
#include "improvement.h" /* bv_imprs */
|
||
|
/****************************************************************************
|
||
| ... | ... | |
|
A vision source has a fixed owner and tile; it changes only in range.
|
||
|
Vision range is given in radius squared; most such values will come from
|
||
|
the ruleset. All vision is circular.
|
||
|
the ruleset. All vision is circular.
|
||
|
A vision source is created using vision_new; this creates the source
|
||
|
without any sight points. Call vision_change_sight to change the sight
|
||
|
points of a vision source (generally called from city_refresh_vision
|
||
|
and unit_refresh vision; this can be called liberally to do updates after
|
||
|
an effect may have changed the source's vision range). Clear the sight
|
||
|
using vision_clear_sight before freeing it with vision_free.
|
||
|
A vision source is created using vision_new(); this creates the source
|
||
|
without any sight points. Call vision_change_sight() to change the sight
|
||
|
points of a vision source (generally called from city_refresh_vision()
|
||
|
and unit_refresh_vision(); this can be called liberally to do updates after
|
||
|
an effect may have changed the source's vision range). Clear the sight
|
||
|
using vision_clear_sight() before freeing it with vision_free().
|
||
|
vision_get_sight returns the sight points of the source. This should
|
||
|
vision_get_sight() returns the sight points of the source. This should
|
||
|
only rarely be necessary since all fogging and unfogging operations
|
||
|
are taken care of internally.
|
||
| ... | ... | |
|
discover new tiles.
|
||
|
***** IMPORTANT *****
|
||
|
To change any of the parameters given to vision_new - that is, to change
|
||
|
To change any of the parameters given to vision_new() - that is, to change
|
||
|
the vision source's position (tile) or owner - you must create a new
|
||
|
vision and then clear and free the old vision. Order is very important
|
||
|
here since you do not want to fog tiles intermediately. You must store
|
||
|
vision and then clear and free the old vision. Order is very important
|
||
|
here since you do not want to fog tiles intermediately. You must store
|
||
|
a copy of the old vision source, then create and attach and fill out the
|
||
|
sight for a new vision source, and only then may you clear and free the
|
||
|
old vision source. In most operations you'll want to stick some other
|
||
|
old vision source. In most operations you'll want to stick some other
|
||
|
code in between so that for the bulk of the operation all tiles are
|
||
|
visible. For instance to move a unit:
|
||
|
visible. For instance to move a unit:
|
||
|
old_vision = punit->server.vision;
|
||
|
punit->server.vision = vision_new(unit_owner(punit), dest_tile);
|
||
| ... | ... | |
|
vision_free(old_vision);
|
||
|
note that for all the code in the middle both the new and the old
|
||
|
vision sources are active. The same process applies when transferring
|
||
|
vision sources are active. The same process applies when transferring
|
||
|
a unit or city between players, etc.
|
||
|
****************************************************************************/
|
||