doc

Signed-off-by: Mattias Andrée <maandree@operamail.com>

3 files changed, 88 insertions, 31 deletions

diff --git a/src/lib/fake-quartz-cg.c b/src/lib/fake-quartz-cg.c
index dbd06c7..1fcfaf3 100644
--- a/src/lib/fake-quartz-cg.c
+++ b/src/lib/fake-quartz-cg.c
@@ -156,6 +156,7 @@ CGError CGGetOnlineDisplayList(uint32_t max_size,
 {
   uint32_t i;
   
+  /* Connect to the display and get screen data if not already done so. */
   if (connection == NULL)
     {
       xcb_generic_error_t* error;
@@ -164,12 +165,13 @@ CGError CGGetOnlineDisplayList(uint32_t max_size,
       xcb_randr_get_crtc_gamma_cookie_t gamma_cookie;
       xcb_randr_get_crtc_gamma_reply_t* restrict gamma_reply;
       
+      /* Connect to the display. */
       connection = xcb_connect(NULL, NULL);
-      
+      /* Get the first screen. */
       iter = xcb_setup_roots_iterator(xcb_get_setup(connection));
+      /* Get the resources of the screen. */
       res_cookie = xcb_randr_get_screen_resources_current(connection, iter.data->root);
       res_reply = xcb_randr_get_screen_resources_current_reply(connection, res_cookie, &error);
-      
       if (error)
 	{
 	  fprintf(stderr, "Failed to open X connection.\n");
@@ -178,9 +180,19 @@ CGError CGGetOnlineDisplayList(uint32_t max_size,
 	  return ~kCGErrorSuccess;
 	}
       
+      /* Get the number of CRTC:s. */
       crtc_count = (uint32_t)(res_reply->num_crtcs);
+      /* Get the CRTC ID:s. */
       crtcs = xcb_randr_get_screen_resources_current_crtcs(res_reply);
       
+      /* Allocate memory where we store the
+	 gamma ramps as they looked when this
+	 adjustment method was first used.
+	 This is used to emulate the functionality
+	 of `CGDisplayRestoreColorSyncSettings`
+	 which restore the all gamma ramps on
+	 the system to the system settnigs.
+      */
       original_ramps = malloc(crtc_count * 3 * 256 * sizeof(uint16_t));
       if (original_ramps == NULL)
 	{
@@ -190,11 +202,12 @@ CGError CGGetOnlineDisplayList(uint32_t max_size,
 	  return ~kCGErrorSuccess;
 	}
       
+      /* Fill the gamma ramps we just allocated. */
       for (i = 0; i < crtc_count; i++)
 	{
+	  /* Read current gamma ramps. */
 	  gamma_cookie = xcb_randr_get_crtc_gamma(connection, crtcs[i]);
 	  gamma_reply = xcb_randr_get_crtc_gamma_reply(connection, gamma_cookie, &error);
-	  
 	  if (error)
 	    {
 	      fprintf(stderr, "Failed to read gamma ramps.\n");
@@ -203,6 +216,7 @@ CGError CGGetOnlineDisplayList(uint32_t max_size,
 	      return ~kCGErrorSuccess;
 	    }
 	  
+	  /* Copy over the gamma ramps to the memory area we have allocated. */
 #define __DEST(C)  original_ramps + (C + 3 * i) * 256
 #define __SRC(C)  xcb_randr_get_crtc_gamma_##C(gamma_reply)
 	  memcpy(__DEST(0), __SRC(red),   256 * sizeof(uint16_t));
@@ -211,13 +225,16 @@ CGError CGGetOnlineDisplayList(uint32_t max_size,
 #undef __SRC
 #undef __DEST
 	  
+	  /* Release resouces. */
 	  free(gamma_reply);
 	}
     }
   
+  /* Return CRTC ID:s. */
   for (i = 0; (i < max_size) && (i < crtc_count); i++)
     *(displays_out + i) = (CGDirectDisplayID)i;
   
+  /* Return the number of CRTC ID:s we returned. */
   *count_out = i;
   return kCGErrorSuccess;
 }
@@ -233,26 +250,33 @@ CGError CGSetDisplayTransferByTable(CGDirectDisplayID display, uint32_t gamma_si
   long i;
   int32_t v;
   
+  /* This is a sloppy compatibility layer that assumes the gamma ramp size is 256. */
   if (gamma_size != 256)
     {
       fprintf(stderr, "Gamma size should be 256.\n");
       abort();
     }
   
+  /* Translate the gamma ramps from float (CoreGraphics) to 16-bit unsigned integer (X RandR). */
   for (i = 0; i < 256; i++)
     {
+      /* Red channel. */
       v = (int32_t)(red[i] * UINT16_MAX);
       r_int[i] = (uint16_t)(v < 0 ? 0 : v > UINT16_MAX ? UINT16_MAX : v);
       
+      /* Green channel. */
       v = (int32_t)(green[i] * UINT16_MAX);
       g_int[i] = (uint16_t)(v < 0 ? 0 : v > UINT16_MAX ? UINT16_MAX : v);
       
+      /* Blue channel. */
       v = (int32_t)(blue[i] * UINT16_MAX);
       b_int[i] = (uint16_t)(v < 0 ? 0 : v > UINT16_MAX ? UINT16_MAX : v);
     }
   
+  /* Apply gamma ramps. */
   gamma_cookie = xcb_randr_set_crtc_gamma_checked(connection, crtcs[display],
 						  (uint16_t)gamma_size, r_int, g_int, b_int);
+  /* Check for errors. */
   return xcb_request_check(connection, gamma_cookie) == NULL ? kCGErrorSuccess : ~kCGErrorSuccess;
 }
 
@@ -269,27 +293,32 @@ CGError CGGetDisplayTransferByTable(CGDirectDisplayID display, uint32_t gamma_si
   uint16_t* restrict b_int;
   long i;
   
+  /* This is a sloppy compatibility layer that assumes the gamma ramp size is 256. */
   if (gamma_size != 256)
     {
       fprintf(stderr, "Gamma size should be 256.\n");
       abort();
     }
   
+  /* The gamma ramp size should be returned to the caller. */
   *gamma_size_out = 256;
   
+  /* Read current gamma ramps. */
   gamma_cookie = xcb_randr_get_crtc_gamma(connection, crtcs[display]);
   gamma_reply = xcb_randr_get_crtc_gamma_reply(connection, gamma_cookie, &error);
-  
   if (error)
     {
       fprintf(stderr, "Failed to write gamma ramps.\n");
       return ~kCGErrorSuccess;
     }
   
+  /* Get gamma ramp values. */
   r_int = xcb_randr_get_crtc_gamma_red(gamma_reply);
   g_int = xcb_randr_get_crtc_gamma_green(gamma_reply);
   b_int = xcb_randr_get_crtc_gamma_blue(gamma_reply);
   
+  /* Translate gamma ramps to float format,
+     that is what CoreGraphics uses. */
   for (i = 0; i < 256; i++)
     {
       red[i]   = (CGGammaValue)(r_int[i]) / UINT16_MAX;
diff --git a/src/lib/fake-w32-gdi.c b/src/lib/fake-w32-gdi.c
index ba72dce..b2ca79b 100644
--- a/src/lib/fake-w32-gdi.c
+++ b/src/lib/fake-w32-gdi.c
@@ -262,42 +262,58 @@ HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice,
   (void) lpszOutput;
   (void) lpInitData;
   
+  /* Check correctness of input. */
   if (strcmp(lpszDriver, "DISPLAY"))
     return NULL;
   
-  if (dc_count == 0) {
-    xcb_generic_error_t* error;
-    xcb_screen_iterator_t iter;
-    xcb_randr_get_screen_resources_current_cookie_t res_cookie;
-    
-    connection = xcb_connect(NULL, NULL);
-    
-    iter = xcb_setup_roots_iterator(xcb_get_setup(connection));
-    res_cookie = xcb_randr_get_screen_resources_current(connection, iter.data->root);
-    res_reply = xcb_randr_get_screen_resources_current_reply(connection, res_cookie, &error);
-    
-    if (error)
-      {
-	xcb_disconnect(connection);
-	crtc_count = -1;
-	return NULL;
-      }
-    
-    crtc_count = res_reply->num_crtcs;
-    crtcs = xcb_randr_get_screen_resources_current_crtcs(res_reply);
-  }
+  /* Connect to the display and get screen data if not already done so. */
+  if (dc_count == 0)
+    {
+      xcb_generic_error_t* error;
+      xcb_screen_iterator_t iter;
+      xcb_randr_get_screen_resources_current_cookie_t res_cookie;
+      
+      /* Connect to the display. */
+      connection = xcb_connect(NULL, NULL);
+      /* Get the first screen. */
+      iter = xcb_setup_roots_iterator(xcb_get_setup(connection));
+      /* Get the resources of the screen. */
+      res_cookie = xcb_randr_get_screen_resources_current(connection, iter.data->root);
+      res_reply = xcb_randr_get_screen_resources_current_reply(connection, res_cookie, &error);
+      if (error)
+	{
+	  fprintf(stderr, "Failed to open X connection.\n");
+	  xcb_disconnect(connection);
+	  crtc_count = -1;
+	  return NULL;
+	}
+      
+      /* Get the number of CRTC:s. */
+      crtc_count = res_reply->num_crtcs;
+      /* Get the CRTC ID:s. */
+      crtcs = xcb_randr_get_screen_resources_current_crtcs(res_reply);
+    }
   
+  /* Was the index too high. */
   if (crtc_index >= crtc_count)
     {
+      /* Disconnect and release resouces and
+	 mark that we do not know the number of
+	 available CRTC:s if we have not opened
+	 any monitors yet. */
       if (dc_count == 0)
 	{
 	  xcb_disconnect(connection);
+	  free(res_reply);
+	  res_reply = NULL
 	  crtc_count = -1;
 	}
       return NULL;
     }
   
+  /* We have opened a new CRTC. */
   dc_count++;
+  /* Return the ID of the CRTC. */
   return crtcs + crtc_index;
 }
 
@@ -311,29 +327,36 @@ BOOL EnumDisplayDevices(LPCTSTR restrict lpDevice, DWORD iDevNum,
 {
   size_t count = (size_t)crtc_count;
   (void) dwFlags;
+  /* Check the correctness of the input. */
   if (lpDevice != NULL)
     {
       fprintf(stderr, "lpDevice (argument 1) for EnumDisplayDevices should be NULL\n");
       abort();
       return FALSE;
     }
+  /* Do we know how many CRTC:s are available? */
   if (crtc_count < 0)
     {
+      /* If not open the first CRTC so that will be figured out. */
       if (GetDC(NULL) == NULL)
 	return FALSE;
-      dc_count = 0;
       count = (size_t)crtc_count;
+      /* Close the primary monitor that we just closed. */
       ReleaseDC(NULL, NULL);
     }
+  /* Check that the request CRTC exists. */
   if (iDevNum >= count)
     return FALSE;
+  /* Check the correctness of the input. */
   if (lpDisplayDevice->cb != sizeof(DISPLAY_DEVICE))
     {
       fprintf(stderr, "lpDisplayDevice->cb for EnumDisplayDevices is not sizeof(DISPLAY_DEVICE)\n");
       abort();
       return FALSE;
     }
+  /* Store name for the CRTC. */
   sprintf(lpDisplayDevice->DeviceName, "%i", iDevNum);
+  /* The connector that the CRTC belongs to is enabled. */
   lpDisplayDevice->StateFlags = DISPLAY_DEVICE_ACTIVE;
   return TRUE;
 }
diff --git a/src/lib/libgamma-facade.c b/src/lib/libgamma-facade.c
index 8d64514..65f0d38 100644
--- a/src/lib/libgamma-facade.c
+++ b/src/lib/libgamma-facade.c
@@ -122,12 +122,14 @@ static int libgamma_list_method_test(int method, int operation)
   
   switch (operation)
     {
-    case 0: /* Methods that the environment suggests will work, excluding fake. */
+    case 0:
+      /* Methods that the environment suggests will work, excluding fake. */
       if (caps.fake)
 	return 0;
       /* Fall through. */
       
-    case 1: /* Methods that the environment suggests will work, including fake. */
+    case 1:
+      /* Methods that the environment suggests will work, including fake. */
       if (caps.real == 0)
 	return 0;
 #ifdef HAVE_LIBGAMMA_METHOD_LINUX_DRM
@@ -142,13 +144,16 @@ static int libgamma_list_method_test(int method, int operation)
 #endif
       return caps.default_site_known;
       
-    case 2: /* All real non-fake methods. */
+    case 2:
+      /* All real non-fake methods. */
       return caps.real && (caps.fake == 0);
       
-    case 3: /* All real methods. */
+    case 3:
+      /* All real methods. */
       return caps.real;
       
-    default: /* All methods. */
+    default:
+      /* All methods. */
       return 1;
     }
 }