From 71fd1bcb68e5ea3f447bf739e70ad46b03fc75d4 Mon Sep 17 00:00:00 2001
From: Stefan Schippers <schippes@mazinga.lan>
Date: Thu, 19 Nov 2020 15:08:40 +0100
Subject: [PATCH] comments about color handling in source code,
 set_cairo_color() function

---
 src/draw.c  | 23 ++++++++++++++---------
 src/xinit.c | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/src/draw.c b/src/draw.c
index 32cb6757..dd6ea2d9 100644
--- a/src/draw.c
+++ b/src/draw.c
@@ -222,6 +222,19 @@ void print_image()
   draw();
 }
 
+
+void set_cairo_color(int layer) 
+{
+  cairo_set_source_rgb(cairo_ctx,
+    (double)xcolor_array[layer].red/65535.0,
+    (double)xcolor_array[layer].green/65535.0,
+    (double)xcolor_array[layer].blue/65535.0);
+  cairo_set_source_rgb(cairo_save_ctx,
+    (double)xcolor_array[layer].red/65535.0,
+    (double)xcolor_array[layer].green/65535.0,
+    (double)xcolor_array[layer].blue/65535.0);
+}
+
 #ifdef HAS_CAIRO
 /* remember to call cairo_restore(cairo_ctx) when done !! */
 int set_text_custom_font(xText *txt) /* 20171122 for correct text_bbox calculation */
@@ -341,15 +354,7 @@ void draw_string(int layer, int what, const char *str, int rot, int flip, int hc
     if(rot == 3 && flip == 1 ) { x=textx1;}
   }
 
-  cairo_set_source_rgb(cairo_ctx,
-    (double)xcolor_array[layer].red/65535.0,
-    (double)xcolor_array[layer].green/65535.0,
-    (double)xcolor_array[layer].blue/65535.0);
-  cairo_set_source_rgb(cairo_save_ctx,
-    (double)xcolor_array[layer].red/65535.0,
-    (double)xcolor_array[layer].green/65535.0,
-    (double)xcolor_array[layer].blue/65535.0);
-
+  set_cairo_color(layer);
   cairo_set_font_size (cairo_ctx, size*xctx->mooz);
   cairo_set_font_size (cairo_save_ctx, size*xctx->mooz);
   cairo_font_extents(cairo_ctx, &fext);
diff --git a/src/xinit.c b/src/xinit.c
index e9d435cf..bc032b26 100644
--- a/src/xinit.c
+++ b/src/xinit.c
@@ -700,6 +700,39 @@ void xwin_exit(void)
  init_done=0; /* 20150409 to avoid multiple calls */
 }
 
+
+/* 
+ *  color structures in xschem:
+ *  - color_array[]: 
+ *      array of color character  names ("#xxxxxx" hex) indexed by xschem layer number.
+ *      these are set from tcl 'color' list variable in init_color_array()
+ *  - color_index[]: 
+ *      array of integers, pixel values, color lookup table, indexed by xschem layer num.
+ *      this array is initialized in build_colors() by calling find_best_color()
+ *      indexes are returned from XAllocNamedColor()
+ *      these are used in XSetForeground and XSetBackground calls:
+ *        XSetForeground(display, gc, color_index[i]) 
+ *  - xcolor_array[]: 
+ *      array of 256 XColor structures:
+ *      typedef struct {
+ *        unsigned long pixel; //  pixel value 
+ *        unsigned short red, green, blue; // rgb values
+ *        char flags; // DoRed, DoGreen, DoBlue 	
+ *        char pad;
+ *      } XColor;
+ *      This array is used temporarily in find_best_color() to store all
+ *      allocated colors in case of pseudocolor visuals to find best substitute when
+ *      XAllocNamedColor fails to find the requested "color_array[i]".
+ *      When all color_index[] are populated with pixel values xcolor_array[]
+ *      is reset with the xschem layer colors in build_colors() using XLookupColor():
+ *        for(i=0;i<cadlayers;i++) {
+ *          XLookupColor(display, colormap, color_array[i], &xcolor_exact, &xcolor);
+ *          xcolor_array[i] = xcolor;
+ *        }
+ *
+ *
+ *
+ */
 int build_colors(double dim)
 {
     int i;