From b4caef492fdcc9924383e954a9c51c50f39fe99f Mon Sep 17 00:00:00 2001 From: Marko Lindqvist Date: Mon, 10 Nov 2025 05:14:54 +0200 Subject: [PATCH 32/32] vision.h: Update module documentation comment See RM #1503 Signed-off-by: Marko Lindqvist --- common/vision.h | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/common/vision.h b/common/vision.h index fa7d8bea34..cb636b0978 100644 --- a/common/vision.h +++ b/common/vision.h @@ -19,7 +19,6 @@ extern "C" { /* common */ #include "fc_types.h" - #include "improvement.h" /* bv_imprs */ /**************************************************************************** @@ -27,16 +26,16 @@ extern "C" { 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. @@ -46,15 +45,15 @@ extern "C" { 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); @@ -67,7 +66,7 @@ extern "C" { 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. ****************************************************************************/ -- 2.51.0