[Freeciv-Dev] (PR#10466) ftwl: docu (fwd)

["Per I. Mathisen" <per@xxxxxxxxxxx>]

<URL: http://rt.freeciv.org/Ticket/Display.html?id=10466 >

This patch adds some much needed documentation to the backend part of
ftwl, and removes some dead code. I couldn't figure out what exactly
MASK_UNKNOWN is and does, hence the name. Input appreciated, even though
I'm putting this in right now.

  - Per

Index: utility/ftwl/be_common_24.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/utility/ftwl/be_common_24.c,v
retrieving revision 1.4
diff -u -r1.4 be_common_24.c
--- utility/ftwl/be_common_24.c 7 Oct 2004 14:37:46 -0000       1.4
+++ utility/ftwl/be_common_24.c 7 Oct 2004 15:15:30 -0000
@@ -43,7 +43,7 @@
 }
 
 /*************************************************************************
-  ...
+  Set a pixel in a given buffer (dest) to a given color (color).
 *************************************************************************/
 static void set_color(be_color color, unsigned char *dest)
 {
@@ -53,7 +53,7 @@
 }
 
 /*************************************************************************
-  ...
+  Transform drawing type to blitting mask.
 *************************************************************************/
 static unsigned char get_mask(enum be_draw_type draw_type)
 {
@@ -68,13 +68,9 @@
 }
 
 /*************************************************************************
- Will copy all pixels which have a mask != 0 from src to dest.
- mask is src.
-
-  Two versions of image_blit_masked will follow. The first is the
-  vanilla one. The other is a testbed for optimizations.
+  Will copy all pixels which have a mask != MASK_UNKNOWN from src to dest.
+  mask is src.
 *************************************************************************/
-#if 1
 static void image_blit_masked(const struct ct_size *size,
                              const struct image *src,
                              const struct ct_point *src_pos,
@@ -97,7 +93,7 @@
     IMAGE_CHECK(dest, dest_pos->x, dest_y);
 
     for (x = 0; x < width; x++) {
-      if (psrc[3] != 0) {
+      if (psrc[3] != MASK_UNKNOWN) {
        memcpy(pdest, psrc, 4);
       }
       psrc += 4;
@@ -105,135 +101,11 @@
     }
   }
 }
-#else
-#define DUFFS_LOOP8(pixel_copy_increment, width)                       \
-{ int n = (width+7)/8;                                                 \
-       switch (width & 7) {                                            \
-       case 0: do {    pixel_copy_increment;                           \
-       case 7:         pixel_copy_increment;                           \
-       case 6:         pixel_copy_increment;                           \
-       case 5:         pixel_copy_increment;                           \
-       case 4:         pixel_copy_increment;                           \
-       case 3:         pixel_copy_increment;                           \
-       case 2:         pixel_copy_increment;                           \
-       case 1:         pixel_copy_increment;                           \
-               } while ( --n > 0 );                                    \
-       }                                                               \
-}
-/* 4-times unrolled loop */
-#define DUFFS_LOOP4(pixel_copy_increment, width)                       \
-{ int n = (width+3)/4;                                                 \
-       switch (width & 3) {                                            \
-       case 0: do {    pixel_copy_increment;                           \
-       case 3:         pixel_copy_increment;                           \
-       case 2:         pixel_copy_increment;                           \
-       case 1:         pixel_copy_increment;                           \
-               } while ( --n > 0 );                                    \
-       }                                                               \
-}
-#define rdtscll(val) __asm__ __volatile__ ("rdtsc" : "=A" (val))
-#define PREFETCH(x) __asm__ __volatile__ ("prefetchnta %0": : "m"(*(char 
*)(x)))
-static void image_blit_masked(const struct ct_size *size,
-                             const struct image *src,
-                             const struct ct_point *src_pos,
-                             struct image *dest,
-                             const struct ct_point *dest_pos)
-{
-  int y;
-  int width = size->width;
-  unsigned long long start, end;
-  static unsigned long long total_clocks = 0, total_pixels = 0;
-  static int total_blits = 0;//, total_solid = 0;
-
-  rdtscll(start);
-
-  for (y = 0; y < size->height; y++) {
-    int src_y = y + src_pos->y;
-    unsigned char *psrc = IMAGE_GET_ADDRESS(src, src_pos->x, src_y);
-
-    int dest_y = y + dest_pos->y;
-    unsigned char *pdest = IMAGE_GET_ADDRESS(dest, dest_pos->x, dest_y);
-
-    /*
-    PREFETCH(psrc);
-    PREFETCH(psrc + 16);
-    PREFETCH(psrc + 32);
-    PREFETCH(psrc + 64);
-    */
-
-#if 1
-    {
-       int x;
-
-    for (x = 0; x < width; x++) {
-      switch (0) {
-      case 0:
-       if (psrc[3] != 0) {
-         memcpy(pdest, psrc, 4);
-       }
-       break;
-
-      case 1:
-       {
-         unsigned int t = *((unsigned int *) psrc);
-         unsigned int *tp = (unsigned int *) pdest;
-
-         if ((t & 0xff000000) != 0) {
-           *tp = t;
-         }
-       }
-       break;
-
-      case 2:
-       {
-         unsigned int t = *((unsigned int *) psrc);
-         unsigned int *tp = (unsigned int *) pdest;
-         unsigned int s = *tp;
-
-         if ((t & 0xff000000) != 0) {
-           s = t;
-         }
-         *tp = s;
-       }
-       break;
-      }
-
-      psrc += 4;
-      pdest += 4;
-    }
-    }
-#else
-    DUFFS_LOOP4( {
-               if (psrc[3] != 0) {
-                   memcpy(pdest, psrc, 4);
-               }
-               psrc += 4; 
-               pdest += 4;
-    }
-                , width);
-#endif
-  }
-  rdtscll(end);
-  total_clocks += (end - start);
-  total_pixels += (size->width * size->height);
-  total_blits++;
-  if((total_blits%1000)==0) {
-      printf("%f clocks per pixel\n",(float)total_clocks/total_pixels);
-  }
-
-  /*if (trans == 0) {
-    total_solid++;
-  }
-  */
-  /* printf("%f solid blits\n",(float)total_solid/total_blits); */
-  /* printf("%d transparent pixel vs %d\n",trans,non_trans); */
-}
-#endif
 
 /*************************************************************************
   Will copy all pixels which have a mask == MASK_ALPHA from src to
   dest with transparency.  Will copy all pixels which have a mask 
-  == MASK_OPAQUE from src to dest.
+  == MASK_OPAQUE from src to dest without transparency.
 *************************************************************************/
 static void image_blit_masked_trans(const struct ct_size *size,
                                    const struct image *src,
@@ -254,7 +126,7 @@
 
       IMAGE_CHECK(src, src_x, src_y);
 
-      if (mask_value != 0) {
+      if (mask_value != MASK_UNKNOWN) {
        int dest_x = x + dest_pos->x;
        int dest_y = y + dest_pos->y;
 
@@ -286,7 +158,9 @@
 }
 
 /*************************************************************************
-  ...
+  Make one image inherit the blitting mask of another.
+
+  ( Why isn't this function here? It does not seem to be necessary. )
 *************************************************************************/
 static void update_masks(const struct ct_size *size,
                         const struct image *src,
@@ -347,22 +221,13 @@
   real_dest_pos.x += dx;
   real_dest_pos.y += dy;
 
-  /*
-    printf("  after clip:\n");
-    printf("    size=(%dx%d)\n", real_size.width, real_size.height);
-    printf("     src=(%d,%d) (%dx%d)\n", real_src_pos.x, real_src_pos.y,
-          src->width, src->height);
-    printf("    dest=(%d,%d) (%dx%d)\n", real_dest_pos.x, real_dest_pos.y,
-          dest->width, dest->height);
-  */
-
   *size=real_size;
   *src_pos=real_src_pos;
   *dest_pos=real_dest_pos;
 }
 
 /*************************************************************************
-  Changes the mask in dest for all !=0 src masks.
+  Changes the mask in dest for all != MASK_UNKNOWN src masks.
 *************************************************************************/
 static void set_mask_masked(const struct ct_size *size,
                            const struct image *src,
@@ -387,7 +252,7 @@
     IMAGE_CHECK(dest, real_dest_pos.x, y + real_dest_pos.y);
 
     for (x = 0; x < real_size.width; x++) {
-      if (psrc[3] != 0) {
+      if (psrc[3] != MASK_UNKNOWN) {
        pdest[3] = mask;
       }
       psrc+=4;
@@ -397,7 +262,8 @@
 }
 
 /*************************************************************************
-  ...
+  Blit one image onto another, using transparency value given on all
+  pixels that have alpha mask set.
 *************************************************************************/
 static void image_copy(struct image *dest,
                       struct image *src,
@@ -419,7 +285,8 @@
 }
 
 /*************************************************************************
-  dest_pos and src_pos can be NULL
+  Blit one osda onto another, using transparency value given on all 
+  pixels that have alpha mask set. dest_pos and src_pos can be NULL.
 *************************************************************************/
 void be_copy_osda_to_osda(struct osda *dest,
                          struct osda *src,
@@ -448,7 +315,7 @@
 }
 
 /*************************************************************************
-  ...
+  See be_draw_bitmap() below.
 *************************************************************************/
 static void draw_mono_bitmap(struct image *image,
                             enum be_draw_type draw_type,
@@ -479,7 +346,7 @@
 }
 
 /*************************************************************************
-  ...
+  See be_draw_bitmap() below.
 *************************************************************************/
 static void draw_alpha_bitmap(struct image *image,
                              enum be_draw_type draw_type,
@@ -517,7 +384,8 @@
 }
 
 /*************************************************************************
-  ...
+  Draw the given bitmap (ie a 1bpp pixmap) on the given osda in the given
+  color and at the givne position, using the given drawing type.
 *************************************************************************/
 void be_draw_bitmap(struct osda *target, enum be_draw_type draw_type,
                    be_color color,
@@ -535,7 +403,7 @@
 }
 
 /*************************************************************************
-  ...
+  Allocate and initialize an osda (off-screen drawing area).
 *************************************************************************/
 struct osda *be_create_osda(int width, int height)
 {
@@ -551,7 +419,7 @@
 }
 
 /*************************************************************************
-  ...
+  Free an allocated osda.
 *************************************************************************/
 void be_free_osda(struct osda *osda)
 {
@@ -564,7 +432,8 @@
 }
 
 /*************************************************************************
-  ...
+  Set the alpha mask of pixels in a given region of an image.  The alpha
+  mask can be MASK_UNKNOWN, MASK_ALPHA or MASK_OPAQUE.
 *************************************************************************/
 void image_set_mask(const struct image *image, const struct ct_rect *rect,
                    unsigned char mask)
@@ -580,12 +449,14 @@
 }
 
 /*************************************************************************
-  ...
+  Make all pixels in the given rectangle on the given osda to be drawn
+  transparently if an image we draw on this osda contains MASK_ALPHA
+  pixels in this region.
 *************************************************************************/
 void be_set_transparent(struct osda *osda, const struct ct_rect *rect)
 {
-  image_set_mask(osda->image, rect, 0);
-  osda->has_transparent_pixels = TRUE;
+  image_set_mask(osda->image, rect, MASK_UNKNOWN);
+  osda->has_transparent_pixels = TRUE; /* probably */
 }
 
 
@@ -593,7 +464,7 @@
 
 
 /*************************************************************************
-  ...
+  Draw an empty rectangle in given osda with given drawing type.
 *************************************************************************/
 void be_draw_rectangle(struct osda *target, enum be_draw_type draw_type,
                       const struct ct_rect *spec,
@@ -619,7 +490,7 @@
 }
 
 /*************************************************************************
-  ...
+  Draw a vertical line (only).
 *************************************************************************/
 static void draw_vline(struct image *image, unsigned char *src,
                       int x, int y0, int y1, int line_width, bool dashed)
@@ -642,7 +513,7 @@
 }
 
 /*************************************************************************
-  ...
+  Draw a horisontal line (only).
 *************************************************************************/
 static void draw_hline(struct image *image, unsigned char *src,
                       int y, int x0, int x1, int line_width, bool dashed)
@@ -665,7 +536,7 @@
 }
 
 /*************************************************************************
-  ...
+  Draw any line.
 *************************************************************************/
 static void draw_line(struct image *image, unsigned char *src,
                      int x1, int y1, int x2, int y2, int line_width,
@@ -715,7 +586,7 @@
 }
 
 /*************************************************************************
-  ...
+  Draw a line in given osda with given drawing type.
 *************************************************************************/
 void be_draw_line(struct osda *target, enum be_draw_type draw_type,
                  const struct ct_point *start,
@@ -754,7 +625,7 @@
 }
 
 /*************************************************************************
-  ...
+  Fill a square region in given osda with given colour and drawing type.
 *************************************************************************/
 void be_draw_region(struct osda *target, enum be_draw_type draw_type,
                    const struct ct_rect *region, be_color color)
@@ -788,7 +659,7 @@
 }
 
 /*************************************************************************
-  ...
+  Return TRUE iff pixel in given osda is transparent or out of bounds.
 *************************************************************************/
 bool be_is_transparent_pixel(struct osda *osda, const struct ct_point *pos)
 {
@@ -834,39 +705,32 @@
 }
 
 /*************************************************************************
-  ...
+  Write an image buffer to file.
 *************************************************************************/
 void be_write_osda_to_file(struct osda *osda, const char *filename)
 {
   FILE *file;
+  unsigned char *line_buffer = malloc(3 * osda->image->width), *pout;
+  int x, y;
 
   file = fopen(filename, "w");
 
-  fprintf(file, "P6\n");
-  fprintf(file, "%d %d\n", osda->image->width, osda->image->height);
-  fprintf(file, "255\n");
-
-  {
-    unsigned char *line_buffer = malloc(3 * osda->image->width), *pout;
-    int x, y;
-
-    for (y = 0; y < osda->image->height; y++) {
-      pout = line_buffer;
-
-      for (x = 0; x < osda->image->width; x++) {
-       IMAGE_CHECK(osda->image, x, y);
-       memcpy(pout, IMAGE_GET_ADDRESS(osda->image, x, y), 3);
-       pout += 3;
-      }
-      fwrite(line_buffer, 3 * osda->image->width, 1, file);
+  for (y = 0; y < osda->image->height; y++) {
+    pout = line_buffer;
+
+    for (x = 0; x < osda->image->width; x++) {
+      MAGE_CHECK(osda->image, x, y);
+      memcpy(pout, IMAGE_GET_ADDRESS(osda->image, x, y), 3);
+      pout += 3;
     }
-    free(line_buffer);
+    fwrite(line_buffer, 3 * osda->image->width, 1, file);
   }
+  free(line_buffer);
   fclose(file);
 }
 
 /*************************************************************************
-  ...
+  Copy image buffer src to dest without doing any alpha-blending.
 *************************************************************************/
 void image_copy_full(struct image *src, struct image *dest,
                     struct ct_rect *region)
@@ -887,7 +751,7 @@
 }
 
 /*************************************************************************
-  ...
+  Allocate and initialize an image struct.
 *************************************************************************/
 struct image *image_create(int width, int height)
 {
@@ -906,7 +770,7 @@
 }
 
 /*************************************************************************
-  ...
+  Free an image struct.
 *************************************************************************/
 void image_destroy(struct image *image)
 {
@@ -915,7 +779,7 @@
 }
 
 /*************************************************************************
-  ...
+  Put size of osda into size.
 *************************************************************************/
 void be_osda_get_size(struct ct_size *size, const struct osda *osda)
 {
Index: utility/ftwl/be_common_24.h
===================================================================
RCS file: /home/freeciv/CVS/freeciv/utility/ftwl/be_common_24.h,v
retrieving revision 1.1
diff -u -r1.1 be_common_24.h
--- utility/ftwl/be_common_24.h 22 Jul 2004 20:00:55 -0000      1.1
+++ utility/ftwl/be_common_24.h 7 Oct 2004 15:15:30 -0000
@@ -24,6 +24,10 @@
   struct ct_rect full_rect;
 };
 
+/* I have no idea what MASK_UNKNOWN is, but it should
+ * be defined by name instead of throwing the number zero
+ * around all the time. - Per */
+#define MASK_UNKNOWN 0x00
 #define MASK_ALPHA  0x01
 #define MASK_OPAQUE 0x02
 
Index: utility/ftwl/be_common_24_sprite.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/utility/ftwl/be_common_24_sprite.c,v
retrieving revision 1.1
diff -u -r1.1 be_common_24_sprite.c
--- utility/ftwl/be_common_24_sprite.c  22 Jul 2004 20:00:55 -0000      1.1
+++ utility/ftwl/be_common_24_sprite.c  7 Oct 2004 15:15:31 -0000
@@ -43,7 +43,6 @@
 /*************************************************************************
   ...
 *************************************************************************/
-
 void be_free_sprite(struct Sprite *sprite)
 {
   free(sprite);
@@ -60,7 +59,8 @@
 
   ct_clip_rect(&region, &source->image->full_rect);
 
-  image_set_mask(result->image, &result->image->full_rect, 0);
+  /* why do we do this?? */
+  image_set_mask(result->image, &result->image->full_rect, MASK_UNKNOWN);
 
   image_copy_full(source->image, result->image, &region);
 
Index: utility/ftwl/be_x11_ximage.c
===================================================================
RCS file: /home/freeciv/CVS/freeciv/utility/ftwl/be_x11_ximage.c,v
retrieving revision 1.1
diff -u -r1.1 be_x11_ximage.c
--- utility/ftwl/be_x11_ximage.c        22 Jul 2004 20:00:55 -0000      1.1
+++ utility/ftwl/be_x11_ximage.c        7 Oct 2004 15:15:31 -0000
@@ -47,7 +47,7 @@
 static GC gc_plain;
 
 /*************************************************************************
-  ...
+  Initialize video mode and window.
 *************************************************************************/
 void be_init(const struct ct_size *screen_size, bool fullscreen)
 {