doc

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

2 files changed, 93 insertions, 10 deletions

diff --git a/src/lib/fake-quartz-cg.c b/src/lib/fake-quartz-cg.c
index f599dbb..dbd06c7 100644
--- a/src/lib/fake-quartz-cg.c
+++ b/src/lib/fake-quartz-cg.c
@@ -34,15 +34,17 @@
 
 
 #ifndef HAVE_LIBGAMMA_METHOD_X_RANDR
+/* Use dummy translation. */
+
 
 CGError CGGetOnlineDisplayList(uint32_t max_size,
 			       CGDirectDisplayID* restrict displays_out, uint32_t* restrict count_out)
 {
+  /* Pretend that we have 2 CRTC:s */
   uint32_t i;
   for (i = 0; (i < max_size) && (i < 2); i++)
     displays_out[i] = (CGDirectDisplayID)i;
   *count_out = i;
-  
   return kCGErrorSuccess;
 }
 
@@ -55,12 +57,12 @@ CGError CGSetDisplayTransferByTable(CGDirectDisplayID display, uint32_t gamma_si
   (void) green;
   (void) blue;
   
+  /* We pretend that our gamma ramps are of size 256. */
   if (gamma_size != 256)
     {
       fprintf(stderr, "Gamma size should be 256.\n");
       abort();
     }
-  
   return kCGErrorSuccess;
 }
 
@@ -72,14 +74,17 @@ CGError CGGetDisplayTransferByTable(CGDirectDisplayID display, uint32_t gamma_si
   long i;
   (void) display;
   
+  /* We pretend that our gamma ramps are of size 256. */
   if (gamma_size != 256)
     {
       fprintf(stderr, "Gamma size should be 256.\n");
       abort();
     }
   
+  /* We pretend that our gamma ramps are of size 256. */
   *gamma_size_out = 256;
   
+  /* Pretend that our gamma ramps are identity mappings. */
   for (i = 0; i < 256; i++)
     red[i] = green[i] = blue[i] = (CGGammaValue)i / 255;
   
@@ -93,6 +98,7 @@ void CGDisplayRestoreColorSyncSettings(void)
 
 uint32_t CGDisplayGammaTableCapacity(CGDirectDisplayID display)
 {
+  /* We pretend that our gamma ramps are of size 256. */
   (void) display;
   return 256;
 }
@@ -104,23 +110,47 @@ void close_fake_quartz(void)
 
 
 #else
+/* Use translation to X RandR. */
+
 
 #include <xcb/xcb.h>
 #include <xcb/randr.h>
 
 
 
+/**
+ * Connection to the X RandR display.
+ */
 static xcb_connection_t* restrict connection = NULL;
+
+/**
+ * Resouces for the screen.
+ * We only have one screen, again this is a very sloppy compatibility layer.
+ */
 static xcb_randr_get_screen_resources_current_reply_t* restrict res_reply = NULL;
+
+/**
+ * The number of available CRTC:s.
+ */
 static uint32_t crtc_count = 0;
+
+/**
+ * List of X RandR CRTC:s.
+ */
 static xcb_randr_crtc_t* restrict crtcs = NULL;
+
+/**
+ * The original gamma ramps, used to emulate gamma ramp restoration to system settings.
+ */
 static uint16_t* restrict original_ramps = NULL;
 
 
 
+/* xcb violates the rule to never return struct:s. */
 # pragma GCC diagnostic push
 # pragma GCC diagnostic ignored "-Waggregate-return"
 
+
 CGError CGGetOnlineDisplayList(uint32_t max_size,
 			       CGDirectDisplayID* restrict displays_out, uint32_t* restrict count_out)
 {
@@ -278,8 +308,12 @@ void CGDisplayRestoreColorSyncSettings(void)
   xcb_void_cookie_t gamma_cookie;
   uint32_t i;
   
+  /* Restore the gamma ramps on each monitor to
+     the ramps that we used when we started. */
   for (i = 0; i < crtc_count; i++)
     {
+      /* We assume that our gamma ramps are of the size
+	 256 (this is a sloppy compatibility layer.) */
       gamma_cookie = xcb_randr_set_crtc_gamma_checked(connection, crtcs[i], 256,
 						      original_ramps + (0 + 3 * i) * 256,
 						      original_ramps + (1 + 3 * i) * 256,
@@ -292,10 +326,13 @@ void CGDisplayRestoreColorSyncSettings(void)
 
 uint32_t CGDisplayGammaTableCapacity(CGDirectDisplayID display)
 {
+  /* We assume that our gamma ramps are of the size
+     256 (this is a sloppy compatibility layer.) */
   (void) display;
   return 256;
 }
 
+
 # pragma GCC diagnostic pop
 
 
diff --git a/src/lib/fake-w32-gdi.c b/src/lib/fake-w32-gdi.c
index 541b3c8..ba72dce 100644
--- a/src/lib/fake-w32-gdi.c
+++ b/src/lib/fake-w32-gdi.c
@@ -34,10 +34,13 @@
 
 
 #ifndef HAVE_LIBGAMMA_METHOD_X_RANDR
+/* Use dummy translation. */
+
 
 /* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx */
 HDC GetDC(HWND hWnd)
 {
+  /* Just a non-NULL value. */
   (void) hWnd;
   return (HDC*)16;
 }
@@ -45,6 +48,7 @@ HDC GetDC(HWND hWnd)
 /* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx */
 int ReleaseDC(HWND hWnd, HDC hDC)
 {
+  /* Always successful. */
   (void) hWnd;
   (void) hDC;
   return 1;
@@ -54,6 +58,7 @@ int ReleaseDC(HWND hWnd, HDC hDC)
 /* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx */
 int GetDeviceCaps(HDC hDC, int nIndex)
 {
+  /* We have gamma ramps if the user asks for colour management capabilities. */
   (void) hDC;
   return CM_GAMMA_RAMP + nIndex - COLORMGMTCAPS;
 }
@@ -61,6 +66,7 @@ int GetDeviceCaps(HDC hDC, int nIndex)
 /* http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx */
 BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 {
+  /* Always successful. */
   (void) hDC;
   (void) lpRamp;
   return TRUE;
@@ -69,6 +75,7 @@ BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 /* http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx */
 BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 {
+  /* Always successful. */
   (void) hDC;
   (void) lpRamp;
   return TRUE;
@@ -79,12 +86,11 @@ BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice,
 	     void* restrict lpszOutput, void* restrict lpInitData)
 {
+  /* `NULL` if not asking for a CRTC, otherwise a non-NULL value. */
   (void) lpszOutput;
   (void) lpInitData;
   (void) lpszDevice;
-  if (strcmp(lpszDriver, "DISPLAY"))
-    return NULL;
-  return (HDC*)16;
+  return strcmp(lpszDriver, "DISPLAY") ? NULL : (HDC*)16;
 }
 
 
@@ -93,46 +99,78 @@ BOOL EnumDisplayDevices(LPCTSTR lpDevice, restrict DWORD iDevNum,
 			PDISPLAY_DEVICE restrict lpDisplayDevice, DWORD dwFlags)
 {
   (void) dwFlags;
+  /* Check correctness of `lpDevice`. */
   if (lpDevice != NULL)
     {
       fprintf(stderr, "lpDevice (argument 1) for EnumDisplayDevices should be NULL\n");
       abort();
       return FALSE;
     }
+  /* Pretend that we have two CRTC:s. */
   if (iDevNum >= 2)
     return FALSE;
+  /* Check correctness of `lpDisplayDevice`. */
   if (lpDisplayDevice->cb != sizeof(DISPLAY_DEVICE))
     {
-      fprintf(stderr,
-	      "lpDisplayDevice->cb for EnumDisplayDevices is not sizeof(DISPLAY_DEVICE)\n");
+      fprintf(stderr, "lpDisplayDevice->cb for EnumDisplayDevices is not sizeof(DISPLAY_DEVICE)\n");
       abort();
       return FALSE;
     }
+  /* Store an arbitrary name for the monitor. */
   strcmp(lpDisplayDevice->DeviceName, "some monitor");
+  /* The connector is always enabled. */
   lpDisplayDevice->StateFlags = DISPLAY_DEVICE_ACTIVE;
   return TRUE;
 }
 
+
 #else
+/* Use translation to X RandR. */
 
 
 #include <xcb/xcb.h>
 #include <xcb/randr.h>
 
 
+/**
+ * The gamma ramp size that devices will
+ * always have in Windows GDI.
+ */
 #define GAMMA_RAMP_SIZE  256
 
 
+/**
+ * Connection to the X RandR display.
+ */
 static xcb_connection_t* restrict connection = NULL;
-static size_t dc_count = 0;
+
+/**
+ * Resouces for the screen.
+ * We only have one screen, again this is a very sloppy compatibility layer.
+ */
+static xcb_randr_get_screen_resources_current_reply_t* restrict res_reply = NULL;
+
+/**
+ * The number of available CRTC:s, -1 if not known yet.
+ */
 static ssize_t crtc_count = -1;
+
+/**
+ * List of X RandR CRTC:s.
+ */
 static xcb_randr_crtc_t* restrict crtcs = NULL;
-static xcb_randr_get_screen_resources_current_reply_t* restrict res_reply = NULL;
+
+/**
+ * The number of opened CRTC:s.
+ */
+static size_t dc_count = 0;
+
 
 
 /* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx */
 HDC GetDC(HWND hWnd)
 {
+  /* Return the primary CRTC. */
   (void) hWnd;
   return CreateDC(TEXT("DISPLAY"), "0", NULL, NULL);
 }
@@ -141,6 +179,7 @@ HDC GetDC(HWND hWnd)
 /* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx */
 int ReleaseDC(HWND hWnd, HDC hDC)
 {
+  /* Disconnect from the RandR display when all monitors have been closed. */
   (void) hWnd;
   (void) hDC;
   dc_count--;
@@ -159,17 +198,22 @@ int ReleaseDC(HWND hWnd, HDC hDC)
 /* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx */
 int GetDeviceCaps(HDC hDC, int nIndex)
 {
+  /* We have gamma ramps if the user asks for colour management capabilities. */
   (void) hDC;
   return CM_GAMMA_RAMP + nIndex - COLORMGMTCAPS;
 }
 
 
+/* xcb violates the rule to never return struct:s. */
 # pragma GCC diagnostic push
 # pragma GCC diagnostic ignored "-Waggregate-return"
 
+
 /* http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx */
 BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 {
+  /* We assume that our gamma ramps are of the same size
+     as used by Windows GDI (we are so sloppy.) */
   xcb_void_cookie_t gamma_cookie =
     xcb_randr_set_crtc_gamma_checked(connection, *(xcb_randr_crtc_t*)hDC, GAMMA_RAMP_SIZE,
 				     ((uint16_t*)lpRamp) + 0 * GAMMA_RAMP_SIZE,
@@ -187,15 +231,16 @@ BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
   xcb_randr_get_crtc_gamma_reply_t* restrict gamma_reply;
   xcb_generic_error_t* error;
   
+  /* Read current gamma ramps. */
   gamma_cookie = xcb_randr_get_crtc_gamma(connection, *(xcb_randr_crtc_t*)hDC);
   gamma_reply = xcb_randr_get_crtc_gamma_reply(connection, gamma_cookie, &error);
-  
   if (error)
     return FALSE;
   
 #define DEST_RAMP(I)  (((uint16_t*)lpRamp) + (I) * GAMMA_RAMP_SIZE)
 #define SRC_RAMP(C)  (xcb_randr_get_crtc_gamma_##C(gamma_reply))
   
+  /* Copy the ramps into the output parameter. (coalesced) */
   memcpy(DEST_RAMP(0), SRC_RAMP(red),   GAMMA_RAMP_SIZE * sizeof(uint16_t));
   memcpy(DEST_RAMP(1), SRC_RAMP(green), GAMMA_RAMP_SIZE * sizeof(uint16_t));
   memcpy(DEST_RAMP(2), SRC_RAMP(blue),  GAMMA_RAMP_SIZE * sizeof(uint16_t));
@@ -256,6 +301,7 @@ HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice,
   return crtcs + crtc_index;
 }
 
+
 # pragma GCC diagnostic pop