document

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

2 files changed, 49 insertions, 0 deletions

diff --git a/src/blueshift_randr.pyx b/src/blueshift_randr.pyx
index a4e80bc..7e8a1a9 100644
--- a/src/blueshift_randr.pyx
+++ b/src/blueshift_randr.pyx
@@ -61,8 +61,19 @@ Resource freeing stage of colour curve control
 
 
 cdef unsigned short int* r_c
+'''
+Storage space for the red colour curve in C native data structure
+'''
+
 cdef unsigned short int* g_c
+'''
+Storage space for the green colour curve in C native data structure
+'''
+
 cdef unsigned short int* b_c
+'''
+Storage space for the blue colour curve in C native data structure
+'''
 
 
 
@@ -75,14 +86,18 @@ def randr_open(int use_screen, display):
     @return  :int            Zero on success
     '''
     global r_c, g_c, b_c
+    # Get the display to use
     cdef char* display_ = NULL
     if display is not None:
         display_ = display
+    # Allocate the storage space for the C native colour curves
     r_c = <unsigned short int*>malloc(256 * 2)
     g_c = <unsigned short int*>malloc(256 * 2)
     b_c = <unsigned short int*>malloc(256 * 2)
+    # Check for out-of-memory error
     if (r_c is NULL) or (g_c is NULL) or (b_c is NULL):
         raise MemoryError()
+    # Start using RandR for the screen and display
     return blueshift_randr_open(use_screen, display_)
 
 
@@ -94,16 +109,20 @@ def randr_read(int use_crtc):
     @return  :(r:list<int>, g:list<int>, b:list<int>)  The current red, green and blue colour curves
     '''
     cdef unsigned short int* got
+    # Read the current curves
     got = blueshift_randr_read(use_crtc)
     if got is NULL:
         raise Exception()
+    # Convert to Python integer lists
     r, g, b, i = [], [], [], 0
     for c in (r, g, b):
+        # while extracting the sizes of the curves
         s = got[i]
         i += 1
         for j in range(s):
             c.append(got[i + j])
         i += s
+    # Free the native curves
     free(got)
     return (r, g, b)
 
@@ -118,10 +137,12 @@ def randr_apply(unsigned long long use_crtcs, r_curve, g_curve, b_curve):
     @param   b_curve:list<unsigned short int>  The blue colour curve
     @return                                    Zero on success
     '''
+    # Convert curves to 16-bit C integers
     for i in range(256):
         r_c[i] = r_curve[i] & 0xFFFF
         g_c[i] = g_curve[i] & 0xFFFF
         b_c[i] = b_curve[i] & 0xFFFF
+    # Apply curves
     return blueshift_randr_apply(use_crtcs, r_c, g_c, b_c)
 
 
@@ -129,8 +150,10 @@ def randr_close():
     '''
     Resource freeing stage of colour curve control
     '''
+    # Free the storage space for the colour curves
     free(r_c)
     free(g_c)
     free(b_c)
+    # Close free all resources in the native code
     blueshift_randr_close()
 
diff --git a/src/blueshift_vidmode.pyx b/src/blueshift_vidmode.pyx
index 606310e..a4be816 100644
--- a/src/blueshift_vidmode.pyx
+++ b/src/blueshift_vidmode.pyx
@@ -64,11 +64,26 @@ Resource freeing stage of colour curve control
 
 
 cdef int vidmode_gamma_size
+'''
+The size of the curves
+'''
 vidmode_gamma_size = 0
 
+
 cdef unsigned short int* r_c
+'''
+Storage space for the red colour curve in C native data structure
+'''
+
 cdef unsigned short int* g_c
+'''
+Storage space for the green colour curve in C native data structure
+'''
+
 cdef unsigned short int* b_c
+'''
+Storage space for the blue colour curve in C native data structure
+'''
 
 
 
@@ -81,15 +96,20 @@ def vidmode_open(int use_screen, display):
     @return  :bool           Whether call was successful
     '''
     global vidmode_gamma_size, r_c, g_c, b_c
+    # Get the display to use
     cdef char* display_ = NULL
     if display is not None:
         display_ = display
+    # Allocate the storage space for the C native colour curves
     r_c = <unsigned short int*>malloc(256 * 2)
     g_c = <unsigned short int*>malloc(256 * 2)
     b_c = <unsigned short int*>malloc(256 * 2)
+    # Check for out-of-memory error
     if (r_c is NULL) or (g_c is NULL) or (b_c is NULL):
         raise MemoryError()
+    # Start using VidMode for the screen and display
     vidmode_gamma_size = blueshift_vidmode_open(use_screen, display_)
+    # Successful only if we got an even usable size for the curves
     return vidmode_gamma_size > 1
 
 
@@ -100,8 +120,10 @@ def vidmode_read(int use_crtc):
     @param   use_crtc                                  The CRTC to use
     @return  :(r:list<int>, g:list<int>, b:list<int>)  The current red, green and blue colour curves
     '''
+    # Read the current curves
     if not blueshift_vidmode_read(use_crtc, r_c, g_c, b_c) == 0:
         raise Exception()
+    # Convert to Python integer lists
     r, g, b = [], [], []
     for i in range(vidmode_gamma_size):
         r.append(r_c[i])
@@ -120,10 +142,12 @@ def vidmode_apply(unsigned long long use_crtcs, r_curve, g_curve, b_curve):
     @param   b_curve:list<unsigned short int>  The blue colour curve
     @return                                    Zero on success
     '''
+    # Convert curves to 16-bit C integers
     for i in range(256):
         r_c[i] = r_curve[i] & 0xFFFF
         g_c[i] = g_curve[i] & 0xFFFF
         b_c[i] = b_curve[i] & 0xFFFF
+    # Apply curves
     return blueshift_vidmode_apply(use_crtcs, r_c, g_c, b_c)
 
 
@@ -131,8 +155,10 @@ def vidmode_close():
     '''
     Resource freeing stage of colour curve control
     '''
+    # Free the storage space for the colour curves
     free(r_c)
     free(g_c)
     free(b_c)
+    # Close free all resources in the native code
     blueshift_vidmode_close()