Labelling: (Mostly) structs documentation and cleanup

[leo.git] / labeller.h

diff --git a/labeller.h b/labeller.h
index 4c0aacc4722a3cd48ed17f0d3ad236cb4f3f638d..3bd13e5f1e7204e2ac52fd9932d6a3b0d887c6b2 100644 (file)
--- a/labeller.h
+++ b/labeller.h
@@ -3,6 +3,17 @@
 
 #include "lab-utils.h"
 
+/*
+* Requests for point refer directly to point symbols that should be placed.
+* Line and area requests are in fact requests for labels (either symbols or
+* textual labels) of such objects.
+* Area requests are taken quite as-is,
+* line requests are broken into section and segment requests -- each line
+* is broken into sections of maximal length and each section is made of segments
+* which correspond to OSM ways.
+* For each line, exactly one segment of each section is labelled in the output.
+*/
+
 enum request_type
 {
   REQUEST_INVALID,
@@ -17,56 +28,50 @@ struct variant
 {
   int width;
   int height;
-  int offset_x;
-  int offset_y;
-  bool *bitmap;
+  int offset_x;                // Desired offset of top-left corner with respect to
+  int offset_y;                // actual coordinates of corresponding object
+  bool *bitmap;                // Mask having 1s where the variant is not blank; used for overlap check
 };
 
 struct request
 {
   enum request_type type;
-  int ind;
-  struct variant *variants;
+  int ind;                     // Index used whenever request indexing is needed
+  struct variant *variants;    // Growing array of all variants usable for this request
 };
 
 struct request_point
 {
   struct request request;
   struct symbol *sym;
-  z_index_t zindex;
+  z_index_t zindex;            // Needed when planning symbol
   double x;
   double y;
-  double offset_x;
-  double offset_y;
-  int num_variants;
 };
 
 struct request_segment
 {
   struct request request;
-  struct request_line *rl;
-  double x1;
+  struct symbol *label;
+  double x1;                   // Start and end of segment
   double y1;
   double x2;
   double y2;
-  double slope;
-  struct symbol *label;
-  z_index_t zindex;
+  double slope;                        // Used to calculate label rotation
+  z_index_t zindex;            // Needed when planning symbol
 };
 
 struct request_section
 {
   struct request request;
-  int num_segments;
-  struct request_segment *segments;
+  struct request_segment *segments;    // Growing array
 };
 
 struct request_line
 {
   struct request request;
   struct symbol *line;
-  int num_variants;
-  struct request_section *sections;
+  struct request_section *sections;    // Growing array
 };
 
 struct request_area
@@ -75,15 +80,18 @@ struct request_area
   struct osm_multipolygon *o;
   struct symbol *label;
   z_index_t zindex;
-  double cx, cy;
+  double cx, cy;               // Area center (coordinates average), used as reference coordinates
 };
 
+// Buffer for lines (osm_ways) added via labeller_notify_line,
+// used to make graph and join lines which should be labelled as one object
 struct buffer_line
 {
   struct sym_line *line;
-  z_index_t zindex;
 };
 
+// Buffer for line labes,
+// used to label graph -- join logical lines with their labels
 struct buffer_linelabel
 {
   struct osm_way *way;
@@ -94,14 +102,14 @@ struct buffer_linelabel
 struct placement
 {
   struct request *request;
-  double x;
+  struct individual *individual;// FIXME: Is it needed?
+  double x;                    // Coordinates of variant top-left corner placement
   double y;
-  int variant_used;
-  int ind;
-  bool processed;
+  int variant_used;            // Variant chosen for request in this placement
+  int ind;                     // Index used whenever placement indexing is needed
+  bool processed;              // FIXME: Is it needed?
   // FIXME: Replace with clist?
   struct map_placement *map_links;
-  struct individual *individual;
 };
 
 struct map_placement
@@ -121,13 +129,6 @@ struct map_part
   int ind;
 };
 
-struct individual
-{
-  struct placement *placements;
-  struct map_part **map;
-  int penalty;
-};
-
 void labeller_conf(void);
 void labeller_init(void);
 void labeller_cleanup(void);