Thread: [cgkit-commits] SF.net SVN: cgkit:[273] cgkit/trunk/cgkit
Brought to you by:
mbaas
From: <mb...@us...> - 2009-02-05 23:31:04
|
Revision: 273 http://cgkit.svn.sourceforge.net/cgkit/?rev=273&view=rev Author: mbaas Date: 2009-02-05 23:31:00 +0000 (Thu, 05 Feb 2009) Log Message: ----------- Updated doc strings. Modified Paths: -------------- cgkit/trunk/cgkit/_cri.py cgkit/trunk/cgkit/cri.py Modified: cgkit/trunk/cgkit/_cri.py =================================================================== --- cgkit/trunk/cgkit/_cri.py 2009-01-26 19:16:12 UTC (rev 272) +++ cgkit/trunk/cgkit/_cri.py 2009-02-05 23:31:00 UTC (rev 273) @@ -41,6 +41,19 @@ # ------------------------------------------------------------- # $Id: ri.py,v 1.4 2006/02/14 19:29:39 mbaas Exp $ +"""This is the "lower-level" _cri module which is used by the cri module. + +This module provides the function loadRI() which loads a shared RenderMan +library and prepares the returned library handle, so that all RenderMan +constants, tokens and functions are properly defined. + +The ri library returned by loadRI() has to be used like a C library and +can crash the application if not used properly (like forgetting to terminate +parameter lists with RI_NULL). This is why this low-level ri library is not +passed back to the user but instead the cri module provides another wrapper +layer that allows the library to be used just like the pure Python ri module. +""" + import os.path from ctypes import * import rmanlibutil @@ -95,8 +108,11 @@ def _createRiTypes(ri): """Create the RenderMan types. - The types are added as attributes to the ri object. All names + ri must be the open ctypes library handle. + The RenderMan types are added as attributes to the ri object. All names begin with "Rt" (RtInt, RtFloat, ...). + + This is a helper function for loadRI(). """ # Base types that are not composed of other RenderMan types... @@ -134,7 +150,12 @@ def _createRiConstants(ri): """Create the RenderMan constants. - The types must already be available on ri. + Add the RenderMan constants to the ri object which must be an open + ctypes library handle. + The types must already be available on ri (i.e. _createRiTypes() must + already have been called). + + This is a helper function for loadRI(). """ ri.RI_NULL = None @@ -162,10 +183,15 @@ def _createRiTokens(ri): """Create the RenderMan tokens. - The constants are added as attributes to the ri object. All names - begin with "RI_". + The RenderMan constants are added as attributes to the ri object which + must be an open ctypes library handle. All names begin with "RI_". + + This is a helper function for loadRI(). """ + # All the following constants will be added to the ri object. + # The items are (Token Name, Default). If a token does not exist in the + # library, the default value is used. tokens = [("RI_A", "a"), ("RI_ABORT", "abort"), ("RI_AMBIENTLIGHT", "ambientlight"), @@ -285,6 +311,12 @@ def _createRiFunctions(ri): + """Declare the RenderMan functions. + + ri must be an open ctypes library handle. + + This is a helper function for loadRI(). + """ # "Import" the types (so that we can write RtInt instead of ri.RtInt)... for name in dir(ri): if name.startswith("Rt"): Modified: cgkit/trunk/cgkit/cri.py =================================================================== --- cgkit/trunk/cgkit/cri.py 2009-01-26 19:16:12 UTC (rev 272) +++ cgkit/trunk/cgkit/cri.py 2009-02-05 23:31:00 UTC (rev 273) @@ -41,6 +41,9 @@ # ------------------------------------------------------------- # $Id: ri.py,v 1.4 2006/02/14 19:29:39 mbaas Exp $ +"""High level cri module that can be used pretty much like the cgkit.ri module. +""" + import types, re import ri from cgtypes import vec3 @@ -156,7 +159,7 @@ def __init__(self, rimod): """Constructor. - rimod is the unterlying ctypes library handle as returned by _cri.loadRI(). + rimod is the underlying ctypes library handle as returned by _cri.loadRI(). """ self._ri = rimod @@ -203,7 +206,6 @@ self._numpyTypes[self._ri.RtInt] = numpy.int_ - def _getRiLastError(self): return self._ri.RiLastError This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mb...@us...> - 2009-08-15 09:31:16
|
Revision: 334 http://cgkit.svn.sourceforge.net/cgkit/?rev=334&view=rev Author: mbaas Date: 2009-08-15 09:31:07 +0000 (Sat, 15 Aug 2009) Log Message: ----------- Changed doc strings to use rst markup so that they can be used for the Sphinx documentation. Modified Paths: -------------- cgkit/trunk/cgkit/glslangparams.py cgkit/trunk/cgkit/glslangtokenize.py cgkit/trunk/cgkit/pointcloud.py cgkit/trunk/cgkit/ri.py cgkit/trunk/cgkit/sloargs.py cgkit/trunk/cgkit/slparams.py cgkit/trunk/cgkit/sltokenize.py Modified: cgkit/trunk/cgkit/glslangparams.py =================================================================== --- cgkit/trunk/cgkit/glslangparams.py 2009-08-08 12:58:38 UTC (rev 333) +++ cgkit/trunk/cgkit/glslangparams.py 2009-08-15 09:31:07 UTC (rev 334) @@ -327,38 +327,38 @@ def glslangparams(shader=None, cpp=None, cpperrstream=sys.stderr): """Extracts the shader parameters from an OpenGL 2 shader source file. - The argument shader is either the name of the shader source file + The argument *shader* is either the name of the shader source file or a file-like object that provides the shader sources. - cpp determines how the shader source is preprocessed. It + *cpp* determines how the shader source is preprocessed. It can either be a string containing the name of an external - preprocessor tool (such as 'cpp') that must take the file name as + preprocessor tool (such as ``cpp``) that must take the file name as parameter and dump the preprocessed output to stdout or it can be - a callable that takes shader and cpperrstream as input and returns + a callable that takes *shader* and *cpperrstream* as input and returns the preprocessed sources as a string. If the external - preprocessor does not produce any data a PreprocessorNotFound + preprocessor does not produce any data a :exc:`PreprocessorNotFound` exception is thrown. The error stream of the preprocessor is written to the object - that is specified by cpperrstream which must have a write() - method. If cpperrstream is None, the error stream is ignored. + that is specified by *cpperrstream* which must have a :meth:`write()` + method. If *cpperrstream* is ``None``, the error stream is ignored. - If cpp is None a simple internal preprocessor based on the - simplecpp module is used. + If *cpp* is ``None`` a simple internal preprocessor based on the + :mod:`simplecpp` module is used. - The function returns three lists (uniform, attribute, varying) + The function returns three lists (*uniform*, *attribute*, *varying*) that contain the variables with the corresponding qualifier. - A uniform variable is a 5-tuple (type, identifier, arraysize, - structname, struct). arraysize is a string containing the + A uniform variable is a 5-tuple (*type*, *identifier*, *arraysize*, + *structname*, *struct*). *arraysize* is a string containing the expression for the length of the array (i.e. the value between - the square brackets). If the variable is no array, arraysize is None. - When the variable is a struct, type has the value 'struct'. In this - case, the struct is given in struct (which is itself a list of + the square brackets). If the variable is no array, *arraysize* is ``None``. + When the variable is a struct, *type* has the value ``'struct'``. In this + case, the struct is given in *struct* (which is itself a list of variables as 5-tuples). If the struct has a name, this name is - given in structname, otherwise structname is None. + given in *structname*, otherwise *structname* is ``None``. - An attribute variable is a 2-tuple (type, identifier) and a - varying variable is a 3-tuple (type, identifier, arraysize) where - arraysize is defined as in the uniform case. + An attribute variable is a 2-tuple (*type*, *identifier*) and a + varying variable is a 3-tuple (*type*, *identifier*, *arraysize*) where + *arraysize* is defined as in the uniform case. """ # Run the preprocessor on the input file... Modified: cgkit/trunk/cgkit/glslangtokenize.py =================================================================== --- cgkit/trunk/cgkit/glslangtokenize.py 2009-08-08 12:58:38 UTC (rev 333) +++ cgkit/trunk/cgkit/glslangtokenize.py 2009-08-15 09:31:07 UTC (rev 334) @@ -52,21 +52,35 @@ def tokenize(readline, tokeater): """Reads a Shading Language input stream and creates tokens. - The first parameter, readline, must be a callable object which - provides the same interface as the readline() method of built-in + The first parameter, *readline*, must be a callable object which + provides the same interface as the :meth:`readline()` method of built-in file objects. Each call to the function should return one line of input as a string. - The second parameter, tokeneater, must also be a callable object. + The second parameter, *tokeater*, must also be a callable object. It is called with six parameters: the token type, the token - string, a tuple (srow, scol) specifying the row and column where - the token begins in the source, a tuple (erow, ecol) giving the + string, a tuple (*srow*, *scol*) specifying the row and column where + the token begins in the source, a tuple (*erow*, *ecol*) giving the ending position of the token, the line on which the token was found and the filename of the current file. - By default the filename argument is an empty string. It will only + The token type can be one of + + * ``WHITESPACE``: This is a series of blanks and/or tabs. + * ``NAME``: A valid identifier name or keyword. + * ``NUMBER``: An integer or float. + * ``STRING``: A string enclosed in ``'"'``. + * ``NEWLINE``: A newline character. + * ``OPERATOR``: An operator such as ``'+', '-', '!', '==', '!='``, etc. + * ``CHARACTER``: A single character that doesn't fit anything else. + * ``TYPE``: A language type (``void``, ``bool``, ``float``, ``int``, ``vec2``, + ``vec3``, ``vec4``, etc.) + * ``QUALIFIER``: A type qualifier (``const``, ``attribute``, ``uniform``, + ``varying``, ``in``, ``out``, ``inout``) + + By default, the filename argument is an empty string. It will only be the actual filename if you provide a preprocessed file stream - as input (so you should first run cpp on any shader). The + as input (so you should first run ``cpp`` on any shader). The tokenizer actually expects preprocessed data as it doesn't handle comments. """ Modified: cgkit/trunk/cgkit/pointcloud.py =================================================================== --- cgkit/trunk/cgkit/pointcloud.py 2009-08-08 12:58:38 UTC (rev 333) +++ cgkit/trunk/cgkit/pointcloud.py 2009-08-15 09:31:07 UTC (rev 334) @@ -606,16 +606,19 @@ def open(fileName, mode="r", libName=None, **kwargs): """Open a point cloud file for reading or writing. - fileName is the name of the point cloud file. mode is either "r" - for reading a file or "w" for writing a new point cloud file. - libName is the library name that implements the point cloud API. - When mode is "w", the following additional keyword arguments must + *fileName* is the name of the point cloud file. *mode* is either ``"r"`` + for reading a file or ``"w"`` for writing a new point cloud file. + *libName* is the library name that implements the point cloud API. + When mode is ``"w"``, the following additional keyword arguments must be present: - - vars: A list of tuples (type, name) that defines what additional variables to write - - world2eye: The world2eye matrix - - world2ndc: The world2ndc matrix - - format: A tuple (xres, yres, aspect) + - ``vars``: A list of tuples (*type*, *name*) that defines what additional variables to write + - ``world2eye``: The world2eye matrix + - ``world2ndc``: The world2ndc matrix + - ``format``: A tuple (*xres*, *yres*, *aspect*) + + Depending on the mode, the function either returns a :class:`PtcReader` or + :class:`PtcWriter` object. """ if mode=="r": return PtcReader(fileName, libName, **kwargs) Modified: cgkit/trunk/cgkit/ri.py =================================================================== --- cgkit/trunk/cgkit/ri.py 2009-08-08 12:58:38 UTC (rev 333) +++ cgkit/trunk/cgkit/ri.py 2009-08-15 09:31:07 UTC (rev 334) @@ -48,7 +48,7 @@ Interface specification. However, it also supports some newer features such as string handles for light sources or object instances. -It is safe to import the module using +It is safe to import the module using:: from cgkit.ri import * @@ -57,7 +57,7 @@ naming conflict. After importing the module this way you can use the functions just as -you are used to from the C API (well, almost). +you are used to from the C API:: from cgkit.ri import * Modified: cgkit/trunk/cgkit/sloargs.py =================================================================== --- cgkit/trunk/cgkit/sloargs.py 2009-08-08 12:58:38 UTC (rev 333) +++ cgkit/trunk/cgkit/sloargs.py 2009-08-15 09:31:07 UTC (rev 334) @@ -518,10 +518,10 @@ _sloLibNames = {} def registerSloArgs(sloSuffix, sloArgsCls): - """Register a SloArgs class for a particular renderer. + """Register a :class:`SloArgs` class for a particular renderer. - sloSuffix is the suffix (without dot) that is used for the compiled - shaders of this renderer. sloArgsCls is the SloArgs class that + *sloSuffix* is the suffix (without dot) that is used for the compiled + shaders of this renderer. *sloArgsCls* is the :class:`SloArgs` class that can read compiled shaders for this renderer. """ global _sloArgsClasses @@ -532,9 +532,15 @@ def getSloLib(sloSuffix): """Return the library name that manages a particular type of compiled shaders. - sloSuffix is the suffix of the compiled shaders. + *sloSuffix* is the suffix of the compiled shader. The return value is the library name that is used to read the parameters from compiled shaders of the given suffix. + + When called before a shader was parsed, the return value is the + library name that will be used when the library is loaded. This value can be + set by calling :func:`setSloLib()`. When the function is called after a + shader was already parsed, the return value is the absolute path to the + actual library that is used to read parameters. """ global _sloArgsClasses, _sloArgsInstances @@ -549,10 +555,10 @@ def setSloLib(sloSuffix, libName): """Set the library name that should be used for reading shader parameters. - Shaders with the given suffix (case-insensitive) will be handled by - the given library. This function has no effect if a shader of the given + Shaders with the suffix *sloSuffix* (case-insensitive) will be handled by + the library *libName*. This function has no effect if a shader of the given suffix has already been read. You must call this function at the beginning - of your application when slparams() hasn't been called yet. + of your application when :func:`slparams()` hasn't been called yet. """ global _sloLibNames @@ -561,7 +567,7 @@ def slparams(shader): """Read shader parameters. - See slparams.slparams() for more details. + See :func:`slparams.slparams()<cgkit.slparams.slparams>` for more details. """ global _sloArgsClasses, _sloArgsInstances, _sloLibNames Modified: cgkit/trunk/cgkit/slparams.py =================================================================== --- cgkit/trunk/cgkit/slparams.py 2009-08-08 12:58:38 UTC (rev 333) +++ cgkit/trunk/cgkit/slparams.py 2009-08-15 09:31:07 UTC (rev 334) @@ -228,59 +228,89 @@ def slparams(slfile=None, cpp=None, cpperrstream=sys.stderr, slname=None, includedirs=None, defines=None): """Extracts the shader parameters from a RenderMan Shader file. - The argument slfile is either the name of a compiled shader, the name of - the shader source file (*.sl) or a file-like object that provides the - shader sources. cpp determines how the shader source is preprocessed. + The argument *slfile* is either the name of a compiled shader, the name of + the shader source file (``*.sl``) or a file-like object that provides the + shader sources. + + *cpp* determines how the shader source is preprocessed. It can either be a string containing the name of an external - preprocessor tool (such as 'cpp') that must take the file name as + preprocessor tool (such as ``cpp``) that must take the file name as parameter and dump the preprocessed output to stdout or it can be - a callable that takes slfile and cpperrstream as input and returns + a callable that takes *slfile* and *cpperrstream* as input and returns the preprocessed sources as a string. If the external - preprocessor does not produce any data a PreprocessorNotFound + preprocessor does not produce any data a :exc:`PreprocessorNotFound` exception is thrown. The error stream of the preprocessor is written to the object - that's specified by cpperrstream which must have a write() - method. If cpperrstream is None, the error stream is ignored. + specified by *cpperrstream* which must have a :meth:`write()` + method. If *cpperrstream* is ``None``, the error stream is ignored. - If cpp is None a simple internal preprocessor based on the - simplecpp module is used. - The slname argument is an alias for slfile, it's only available + If *cpp* is ``None`` a simple internal preprocessor based on the + :mod:`simplecpp` module is used. + The *slname* argument is an alias for *slfile*, it is only available for backwards compatibility. - includedirs is a list of strings that contain directories where to - look for include files. defines is a list of tuples (name, value) + *includedirs* is a list of strings that contain directories where to + look for include files. *defines* is a list of tuples (*name*, *value*) that specify the predefined symbols to use. The function returns a list of shader info objects. These objects have - 4 attributes: + four attributes: - - type: The type of the shader (surface, displacement, etc.) - - name: The name of the shader - - params: The shader parameters (see below) - - meta: The shader meta data. How exactly meta data is specified depends - on the renderer you are using. + - ``type``: The type of the shader (surface, displacement, etc.) + - ``name``: The name of the shader + - ``params``: The shader parameters (see below) + - ``meta``: The shader meta data. How exactly meta data is specified depends + on the renderer you are using. The parameters are given as a list of shader parameter objects describing each parameter. A shader parameter object has the following attributes: - - outputSpec: The output specifier (either "output" or an empty string) - - storage: The storage class ("uniform" or "varying") - - type: The parameter type - - size: The array length or None if the parameter is not an array - - name: The name of the parameter - - space: The space in which a point-like type was defined - - default: The "raw" default value. If the input was a shader source file, + - ``outputSpec``: The output specifier (either ``"output"`` or an empty string) + - ``storage``: The storage class (``"uniform"`` or ``"varying"``) + - ``type``: The parameter type + - ``size``: The array length or ``None`` if the parameter is not an array + - ``name``: The name of the parameter + - ``space``: The space in which a point-like type was defined + - ``default``: The "raw" default value. If the input was a shader source file, this will always be a string containing an expression. If the input was a compiled shader this will already be an appropriate Python value. - You should never use this value directly, but always use convertdefault() + You should never use this value directly, but always use :func:`convertdefault()` to obtain a value which can be further processed. This way, your code will work for both, compiled shaders and shader source files. For backwards compatibility, the shader info object behaves like a - 3-tuple (type, name, params). The meta data can only be accessed via name - though. The shader parameter objects can also be used like 7-tuples + 3-tuple (*type*, *name*, *params*). The meta data can only be accessed via + name though. The shader parameter objects can also be used like 7-tuples containing the above data (in the order given above). + + Example (output slightly reformatted for better readability):: + + >>> from cgkit import slparams + >>> shaders = lparams.slparams("plastic.sl") + >>> print shaders + [('surface', 'plastic', + [('', 'uniform', 'float', None, 'Ka', None, '1'), + ('', 'uniform', 'float', None, 'Kd', None, '0.5'), + ('', 'uniform', 'float', None, 'Ks', None, '0.5'), + ('', 'uniform', 'float', None, 'roughness', None, '0.1'), + ('', 'uniform', 'color', None, 'specularcolor', 'rgb', '1')])] + >>> shaders[0].type + 'surface' + >>> shaders[0].name + 'plastic' + >>> for param in shaders[0].params: print param.name + ... + Ka + Kd + Ks + roughness + specularcolor + >>> shaders[0].meta + {} + + The parser used inside this function was generated using the parser generator + `Yapps <http://theory.stanford.edu/~amitp/Yapps/>`_ by Amit Patel. """ if slname is not None: @@ -433,22 +463,33 @@ def convertdefault(paramtuple): """Converts the default value of a shader parameter into a Python type. - paramtuple must be a 7-tuple (or parameter object) as returned by slparams(). + *paramtuple* must be a 7-tuple (or parameter object) as returned by + :func:`slparams()`. The function returns a Python object that corresponds to the default value of the parameter. If the default value can't be converted - then None is returned. Only the functions that are present in the - sl module are evaluated. If a default value calls a user defined - function then None is returned. + then ``None`` is returned. Only the functions that are present in the + :mod:`sl<cgkit.sl>` module are evaluated. If a default value calls a user defined + function then ``None`` is returned. The SL types will be converted into the following Python types: - - float -> float - - string -> string - - color -> vec3 - - point -> vec3 - - vector -> vec3 - - normal -> vec3 - - matrix -> mat4 + +------------+-------------+ + | SL type | Python type | + +============+=============+ + | ``float`` | ``float`` | + +------------+-------------+ + | ``string`` | ``string`` | + +------------+-------------+ + | ``color`` | ``vec3`` | + +------------+-------------+ + | ``point`` | ``vec3`` | + +------------+-------------+ + | ``vector`` | ``vec3`` | + +------------+-------------+ + | ``normal`` | ``vec3`` | + +------------+-------------+ + | ``matrix`` | ``mat4`` | + +------------+-------------+ Arrays will be converted into lists of the corresponding type. """ Modified: cgkit/trunk/cgkit/sltokenize.py =================================================================== --- cgkit/trunk/cgkit/sltokenize.py 2009-08-08 12:58:38 UTC (rev 333) +++ cgkit/trunk/cgkit/sltokenize.py 2009-08-15 09:31:07 UTC (rev 334) @@ -51,21 +51,32 @@ def tokenize(readline, tokeater): """Reads a Shading Language input stream and creates tokens. - The first parameter, readline, must be a callable object which - provides the same interface as the readline() method of built-in + The first parameter, *readline*, must be a callable object which + provides the same interface as the :meth:`readline()` method of built-in file objects. Each call to the function should return one line of input as a string. - The second parameter, tokeneater, must also be a callable object. + The second parameter, *tokeater*, must also be a callable object. It is called with six parameters: the token type, the token - string, a tuple (srow, scol) specifying the row and column where - the token begins in the source, a tuple (erow, ecol) giving the + string, a tuple (*srow*, *scol*) specifying the row and column where + the token begins in the source, a tuple (*erow*, *ecol*) giving the ending position of the token, the line on which the token was found and the filename of the current file. - By default the filename argument is an empty string. It will only + The token type can be one of: + + * ``WHITESPACE``: This is a series of blanks and/or tabs + * ``NAME``: A valid identifier name or keyword + * ``NUMBER``: An integer or float + * ``STRING``: A string enclosed in ``'"'``. + * ``NEWLINE``: A newline character. + * ``OPERATOR``: An operator such as ``'+', '-', '!', '==', '!='``, etc. + * ``CHARACTER``: A single character that doesn't fit anything else. + * ``TYPE``: A Shading Language type (float, point, vector, normal, matrix, color) + + By default, the filename argument is an empty string. It will only be the actual filename if you provide a preprocessed file stream - as input (so you should first run cpp on any shader). The + as input (so you should first run ``cpp`` on any shader). The tokenizer actually expects preprocessed data as it doesn't handle comments. """ This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |