document

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

1 files changed, 26 insertions, 0 deletions

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()