document EDID

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

2 files changed, 84 insertions, 7 deletions

diff --git a/info/blueshift.texinfo b/info/blueshift.texinfo
index dc6fd16..68707ef 100644
--- a/info/blueshift.texinfo
+++ b/info/blueshift.texinfo
@@ -953,13 +953,13 @@ to a monitor.
 
 @item widthmm
 The physical width of the monitor, measured
-in millimetres. @code{None} if unknown or if
-not connected.
+in millimetres. @code{None} if unknown, not
+defined or if not connected.
 
 @item heightmm
 The physical height of the monitor, measured
-in millimetres. @code{None} if unknown or if
-not connected.
+in millimetres. @code{None} if unknown, not
+defined or if not connected.
 
 @item crtc
 The CRT controller index. @code{None} if not
@@ -976,6 +976,14 @@ is used it is probably found because it is needed
 for plug and play support of the monitor.
 @end table
 
+The width and height are unknown if the monitor
+does not specify them in the EDID if using DRM.
+They are not defined the output is a projector.
+If using RandR this values are probably not
+correct, but the EDID can be parsed, which is
+want is done by DRM. The EDID can only specify
+whole centrimeters up to 255 cm.
+
 @code{Screens} and @code{Screen} provide a set
 of functions for finding the output, and traversal
 the CRTC and screen, a monitor is connected to:
@@ -1013,6 +1021,52 @@ These functions returns a list of matching
 @code{Output}:s. The list is empty if non are
 found.
 
+Using the class @code{EDID} it is possible to
+parse the extended display identification data
+of an output. @code{EDID} as a constructor that
+takes one argument: the EDID as stored by
+@code{Output} in its variable @code{edid}.
+This class can only parse EDID structure revision
+1.3, which is way all monitors produced 2000 or
+later should use. If the supplied EDID does
+not meet this requirement an exception will be
+raised by the constructor.
+
+An instance of @code{EDID} currently have
+the following variables:
+
+@table @code
+@item widthmm
+The physical width of the monitor, measured
+in millimetres. @code{None} if not, e.g. a
+projector. This value is between 10 mm and 2550
+mm inclusively and is always zero modulo 10 mm.
+
+@item heightmm
+The physical height of the monitor, measured
+in millimetres. @code{None} if not, e.g. a
+projector. This value is @code{None} exactly
+when the value of @code{widthmm} is @code{None}.
+This value is between 10 mm and 2550 mm
+inclusively and is always zero modulo 10 mm.
+
+@item gamma
+The monitor's estimated gamma characteristics,
+@code{None} if not specified. The range of this
+value is 1,00 to 3,55 inclusively, with a
+precision of 0,01.
+
+@item gamma_correction
+The value correlates exactly with @code{gamma},
+and is @code{None} if and only if @code{gamma}
+is @code{None}. More precisely, it is the value
+of @code{gamma} divided by gamma calibrated
+monitors should have: 2,2. This value can be
+used for gamma correction if you do not have
+more exact values to use.
+@end table
+
+
 
 @node Backlight
 @section Backlight
diff --git a/src/monitor.py b/src/monitor.py
index 2a9e2a8..499d7d0 100644
--- a/src/monitor.py
+++ b/src/monitor.py
@@ -473,8 +473,8 @@ class Output:
     
     @variable  name:str        The name of the output
     @variable  connected:bool  Whether the outout is known to be connected
-    @variable  widthmm:int?    The physical width of the monitor, measured in millimetres, `None` if unknown or not connected
-    @variable  heigthmm:int?   The physical height of the monitor, measured in millimetres, `None` if unknown or not connected
+    @variable  widthmm:int?    The physical width of the monitor, measured in millimetres, `None` if unknown, not defined or not connected
+    @variable  heigthmm:int?   The physical height of the monitor, measured in millimetres, `None` if unknown, not defined or not connected
     @variable  crtc:int?       The CRTC index, `None` if not connected
     @variable  screen:int?     The screen index, `None` if none
     @variable  edid:str?       Extended display identification data, `None` if none
@@ -498,28 +498,51 @@ class Output:
         return '[Name: %s, Connected: %s, Width: %s, Height: %s, CRTC: %s, Screen: %s, EDID: %s]' % rc
 
 
-class EDID: # TODO demo and document this
+class EDID: # TODO demo this
+    '''
+    Data structure for parsed EDID:s
+    
+    @var  widthmm:int?             The physical width of the monitor, measured in millimetres, `None` if not defined
+    @var  heightmm:int?            The physical height of the monitor, measured in millimetres, `None` if not defined or not connected
+    @var  gamma:float?             The monitor's estimated gamma characteristics, `None` if not specified
+    @var  gamma_correction:float?  Gamma correction to use unless you know more exact values, calculated from `gamma`
+    '''
     def __init__(self, edid):
+        '''
+        Constructor, parses an EDID
+        
+        @param      edid:str    The edid to parse, in hexadecimal representation
+        @exception  :Exception  Raised when the EDID is not of a support format
+        '''
+        # Check the length of the EDID
         if not len(edid) == 256:
             raise Exception('EDID version not support, length mismatch')
+        # Check the EDID:s magic number
         if not edid[:16].upper() == '00FFFFFFFFFFFF00':
             raise Exception('EDID version not support, magic number mismatch')
+        # Convert to raw byte representation
         edid = [int(edid[i * 2 : i * 2 + 2], 16) for i in range(128)]
+        # Check EDID structure version and revision
         if not edid[18] == 1:
             raise Exception('EDID version not support, version mismatch, only 1.3 supported')
         if not edid[19] == 3:
             raise Exception('EDID version not support, revision mismatch, only 1.3 supported')
+        # Get the maximum displayable image dimension
         self.widthmm = edid[21] * 10
         self.heightmm = edid[22] * 10
         if (self.widthmm == 0) or (self.heightmm == 0):
+            # If either is zero, it is undefined, e.g. a projector
             self.widthmm = None
             self.heightmm = None
+        # Get the gamma characteristics
         if (edid[23] == 255):
+            # Not specified if FFh
             self.gamma = None
             self.gamma_correction = None
         else:
             self.gamma = (edid[23] + 100) / 100
             self.gamma_correction = self.gamma / 2.2
+        # Check the EDID checksum
         if not sum(edid) % 256 == 0:
             raise Exception('Incorrect EDID checksum')