Thread: [cgkit-commits] SF.net SVN: cgkit: [213] cgkit/trunk/doc
Brought to you by:
mbaas
From: <mb...@us...> - 2007-05-09 12:06:45
|
Revision: 213 http://svn.sourceforge.net/cgkit/?rev=213&view=rev Author: mbaas Date: 2007-05-09 05:05:56 -0700 (Wed, 09 May 2007) Log Message: ----------- Updated the email address Modified Paths: -------------- cgkit/trunk/doc/tex/cgkit.tex cgkit/trunk/doc/tutorials/animation/animation.txt cgkit/trunk/doc/tutorials/baking/baking.txt cgkit/trunk/doc/tutorials/code_examples/demo1.txt cgkit/trunk/doc/tutorials/code_examples/demo2.txt cgkit/trunk/doc/tutorials/code_examples/demo3.txt cgkit/trunk/doc/tutorials/code_examples/shownormals.txt cgkit/trunk/doc/tutorials/code_examples/spacedevicedemo.txt cgkit/trunk/doc/tutorials/custom_vars/custom_vars.txt cgkit/trunk/doc/tutorials/first_steps/first_steps.txt cgkit/trunk/doc/tutorials/grow_utility/grow_utility.txt cgkit/trunk/doc/tutorials/materials/materials.txt cgkit/trunk/doc/tutorials/renderman/renderman.txt Modified: cgkit/trunk/doc/tex/cgkit.tex =================================================================== --- cgkit/trunk/doc/tex/cgkit.tex 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tex/cgkit.tex 2007-05-09 12:05:56 UTC (rev 213) @@ -8,7 +8,7 @@ \author{Matthias Baas} \authoraddress{ - Email: \email{ba...@ir...} + Email: \email{mb...@us...} } %\date{May 20, 2004} % XXX update before final release! Modified: cgkit/trunk/doc/tutorials/animation/animation.txt =================================================================== --- cgkit/trunk/doc/tutorials/animation/animation.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/animation/animation.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ cgkit tutorial: Animation ========================= -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2004/11/16 .. contents:: Modified: cgkit/trunk/doc/tutorials/baking/baking.txt =================================================================== --- cgkit/trunk/doc/tutorials/baking/baking.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/baking/baking.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ cgkit tutorial: Baking texture maps =================================== -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2005/06/18 .. contents:: Modified: cgkit/trunk/doc/tutorials/code_examples/demo1.txt =================================================================== --- cgkit/trunk/doc/tutorials/code_examples/demo1.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/code_examples/demo1.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ A minimal scene =============== -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2004/12/20 This is a minimal example of a scene with one camera, two point lights Modified: cgkit/trunk/doc/tutorials/code_examples/demo2.txt =================================================================== --- cgkit/trunk/doc/tutorials/code_examples/demo2.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/code_examples/demo2.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ Sharing material definitions ============================ -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2004/12/20 Here is another almost minimal scene where a material is defined Modified: cgkit/trunk/doc/tutorials/code_examples/demo3.txt =================================================================== --- cgkit/trunk/doc/tutorials/code_examples/demo3.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/code_examples/demo3.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ Creating a hierarchy and using expressions ========================================== -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2004/12/20 This script creates a hierarchy of objects so that moving the parent Modified: cgkit/trunk/doc/tutorials/code_examples/shownormals.txt =================================================================== --- cgkit/trunk/doc/tutorials/code_examples/shownormals.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/code_examples/shownormals.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ Visualizing vertex positions and normals ======================================== -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2004/12/20 This code example shows the following things: Modified: cgkit/trunk/doc/tutorials/code_examples/spacedevicedemo.txt =================================================================== --- cgkit/trunk/doc/tutorials/code_examples/spacedevicedemo.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/code_examples/spacedevicedemo.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ How to use the spacedevice module ================================= -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2005/08/29 This demo demonstrates the usage of the ``SpaceDevice`` object in the Modified: cgkit/trunk/doc/tutorials/custom_vars/custom_vars.txt =================================================================== --- cgkit/trunk/doc/tutorials/custom_vars/custom_vars.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/custom_vars/custom_vars.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ cgkit tutorial: Custom attributes & primitive variables ======================================================= -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2004/12/07 .. contents:: Modified: cgkit/trunk/doc/tutorials/first_steps/first_steps.txt =================================================================== --- cgkit/trunk/doc/tutorials/first_steps/first_steps.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/first_steps/first_steps.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ cgkit tutorial: First steps =========================== -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2004/11/16 .. contents:: Modified: cgkit/trunk/doc/tutorials/grow_utility/grow_utility.txt =================================================================== --- cgkit/trunk/doc/tutorials/grow_utility/grow_utility.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/grow_utility/grow_utility.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ cgkit tutorial: Using the grow utility ====================================== -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2006/10/11 .. contents:: Modified: cgkit/trunk/doc/tutorials/materials/materials.txt =================================================================== --- cgkit/trunk/doc/tutorials/materials/materials.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/materials/materials.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ cgkit tutorial: Materials ========================= -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2005/04/17 .. contents:: Modified: cgkit/trunk/doc/tutorials/renderman/renderman.txt =================================================================== --- cgkit/trunk/doc/tutorials/renderman/renderman.txt 2007-01-12 11:09:46 UTC (rev 212) +++ cgkit/trunk/doc/tutorials/renderman/renderman.txt 2007-05-09 12:05:56 UTC (rev 213) @@ -1,7 +1,7 @@ cgkit tutorial: Rendering with RenderMan ======================================== -:Author: Matthias Baas (ba...@ir...) +:Author: Matthias Baas (mb...@us...) :Date: 2004/11/24 .. contents:: This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mb...@us...> - 2008-02-24 11:33:04
|
Revision: 238 http://cgkit.svn.sourceforge.net/cgkit/?rev=238&view=rev Author: mbaas Date: 2008-02-24 03:31:59 -0800 (Sun, 24 Feb 2008) Log Message: ----------- Documentation updates Modified Paths: -------------- cgkit/trunk/doc/tex/cgkit.tex cgkit/trunk/doc/tex/hammersley.tex cgkit/trunk/doc/tex/mayaascii.tex cgkit/trunk/doc/tex/ri.tex Added Paths: ----------- cgkit/trunk/doc/pics/koch.jpg cgkit/trunk/doc/tex/cri.tex cgkit/trunk/doc/tex/mayabinary.tex Added: cgkit/trunk/doc/pics/koch.jpg =================================================================== (Binary files differ) Property changes on: cgkit/trunk/doc/pics/koch.jpg ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: cgkit/trunk/doc/tex/cgkit.tex =================================================================== --- cgkit/trunk/doc/tex/cgkit.tex 2008-02-23 19:37:04 UTC (rev 237) +++ cgkit/trunk/doc/tex/cgkit.tex 2008-02-24 11:31:59 UTC (rev 238) @@ -15,7 +15,7 @@ \date{\today} %--------------------------------------------------------- % Version information -\release{2.0.0alpha7} +\release{2.0.0alpha8} \setreleaseinfo{} \setshortversion{2.0} %--------------------------------------------------------- @@ -92,6 +92,7 @@ \input{cgkitinfo.tex} \input{cgtypes.tex} \input{ri.tex} +\input{cri.tex} \input{riutil.tex} \input{noise.tex} \input{sl.tex} @@ -106,6 +107,7 @@ \input{bvh.tex} \input{objmtl.tex} \input{mayaascii.tex} +\input{mayabinary.tex} \input{lwob.tex} \input{hammersley.tex} \input{stitch.tex} Added: cgkit/trunk/doc/tex/cri.tex =================================================================== --- cgkit/trunk/doc/tex/cri.tex (rev 0) +++ cgkit/trunk/doc/tex/cri.tex 2008-02-24 11:31:59 UTC (rev 238) @@ -0,0 +1,183 @@ +\section{\module{cri} --- + RenderMan binding for direct access to a renderer} + +\declaremodule{extension}{cgkit.cri} +\modulesynopsis{RenderMan binding for direct access to a renderer} + +The \module{cri} module is an alternative version of the \refmodule[cgkit.ri]{ri} module +that uses the Python \module{ctypes} module to interface a renderer directly. +The \module{ctypes} module is a foreign function library that is part of the +standard Python libraries since Python 2.5\footnote{Python 2.5 is embedded in +Maya 2008 and Houdini 9, whereas Maya 8.5 still uses Python 2.4.}. +With previous versions of Python, the module has to be installed separately. The module can be used in combination with any renderer +that implements the RenderMan API in a shared library. Using this module instead of +the \module{ri} module has a number of advantages: + +\begin{itemize} +\item You can mix Python code and C/C++ code and +issue RenderMan commands from any language into the same stream. +\item You can feed the renderer directly without having to create an +intermediate RIB. This also means you can use Python functions for +procedurals, filter functions or error handlers. +\item Even when generating RIB using this module is usually faster as the +actual RIB export is done by C/C++ code. The code is considerably faster if +you are using ctypes arrays or numpy arrays in your parameter lists. In this +case, no data conversion is required. +\end{itemize} + +The disadvantage of using this module is that it depends on an external +dynamic library that must implement the actual functionality. This means if you +have not installed a renderer that ships with such a library you cannot use the +module. + +Before any RenderMan function can be used, a library has to be loaded using +the \function{loadRI()} function. The returned module-like object can then be +used just like the \refmodule[cgkit.ri]{ri} module. + +% loadRI +\begin{funcdesc}{loadRI}{libName} +Load a RenderMan library and return a module-like handle to it. +\var{libName} is the name of a shared library that implements the RenderMan +interface. The name can either be an absolute file name or just the +name of the library (without suffix or "lib" prefix) in which case the +function tries to find the library file itself. The return value is +an object that can be used like a module, i.e. it contains all RenderMan +functions, constants, etc. +If \var{libName} is \code{None} or the empty string, the return value is +just a reference to the \module{ri} module. + +\begin{verbatim} +import cgkit.cri + +ri = cgkit.cri.loadRI("3delight") + +ri.RiBegin(ri.RI_NULL) +ri.RiWorldBegin() +ri.RiSurface("plastic") +ri.RiSphere(1,-1,1,360) +ri.RiWorldEnd() +ri.RiEnd() +\end{verbatim} + +The RenderMan function names can either be used with or without the +"Ri" prefix. So the following is equivalent to the above: + +\begin{verbatim} +ri.Begin(ri.RI_NULL) +ri.WorldBegin() +ri.Surface("plastic") +ri.Sphere(1,-1,1,360) +ri.WorldEnd() +ri.End() +\end{verbatim} + +The following table lists the library names for some renderers that are known to +work with this module: + +\begin{tableii}{l|c}{textrm}{Renderer}{Library Name} +\lineii{3Delight}{\code{3delight}} +\lineii{Aqsis}{\code{aqsislib} / \code{ri2rib}} +\lineii{Pixie}{\code{ri}} +\end{tableii} + +PRMan (up to v13.5) only ships with a static library which is why it cannot be +used with this module. + +\end{funcdesc} + +% importRINames +\begin{funcdesc}{importRINames}{ri, ns} +Import the RenderMan names into the given namespace. +\var{ri} is the module-like object that was returned by \function{loadRI()} +and \var{ns} is a dictionary containing a module namespace (such as +\function{globals()}) that will receive the "imported" symbols. Only +the names with the "Ri" prefix will be available. Example: + +\begin{verbatim} +ri = cgkit.cri.loadRI("3delight") +cgkit.cri.importRINames(ri, globals()) + +RiBegin(RI_NULL) +RiWorldBegin() +RiSurface("plastic") +RiSphere(1,-1,1,360) +RiWorldEnd() +RiEnd() +\end{verbatim} +\end{funcdesc} + +\subsection{Example} + +The following example renders three Koch curves that form sort of a ``snowflake'' +shape. Each curve is created by a procedural which just uses a regular Python +function as subdivide function. No RIB is generated by this example.\\ +It is possible to create the same image using the generic \module{ri} module, +but the procedural would have to be written as a separate Python script that is +invoked using the ``RunProgram'' procedural. The code would actually be longer +because you would have to encode/decode the parameters of the procedural as +strings whereas this example directly passes vector objects around. + +\begin{verbatim} +# Render a Koch snowflake as procedurals + +import cgkit.cri +from cgkit.cgtypes import * + +def bound(A, E): + """Compute the bounding box of one segment.""" + eps = 0.03 + dv = E-A + n = vec3(-dv.y, dv.x, 0) + C = 0.5*(A+E) + 0.2887*n + xx = [A.x, C.x, E.x] + yy = [A.y, C.y, E.y] + bound = [min(xx)-eps, max(xx)+eps, min(yy)-eps, max(yy)+eps, -0.001, 0.001] + return bound + +def subdiv(data, detail): + """Subdivide function.""" + A,E = data + dv = E-A + if dv.length()<0.005: + RiCurves(RI_LINEAR, [2], RI_NONPERIODIC, P=[A,E], constantwidth=0.003) + else: + t = 1.0/3 + B = (1.0-t)*A + t*E + D = (1.0-t)*E + t*A + n = vec3(-dv.y, dv.x, 0) + C = 0.5*(A+E) + 0.2887*n + RiProcedural((A,B), bound(A,B), subdiv) + RiProcedural((B,C), bound(B,C), subdiv) + RiProcedural((C,D), bound(C,D), subdiv) + RiProcedural((D,E), bound(D,E), subdiv) + +# Load the RenderMan API. +# Replace the library name with whatever renderer you want to use. +ri = cgkit.cri.loadRI("3delight") +cgkit.cri.importRINames(ri, globals()) + +RiBegin(RI_NULL) +RiFormat(1024,768,1) +RiDisplay("koch.tif", RI_FRAMEBUFFER, RI_RGB) +RiPixelSamples(3,3) +RiProjection(RI_ORTHOGRAPHIC) +RiScale(vec3(0.8)) +RiTranslate(0,0.55,5) +RiWorldBegin() +RiSurface("constant") +RiColor((1,1,1)) +RiPatch(RI_BILINEAR, P=[-2,2,1, 2,2,1, -2,-2,1, 2,-2,1]) +RiColor((0,0,0)) +RiProcedural((vec3(-1,0,0),vec3(1,0,0)), [-2,2, -2,2, -0.01,0.01], subdiv) +RiProcedural((vec3(0,-1.732,0),vec3(-1,0,0)), [-2,2, -2,2, -0.01,0.01], subdiv) +RiProcedural((vec3(1,0,0), vec3(0,-1.732,0)), [-2,2, -2,2, -0.01,0.01], subdiv) +RiWorldEnd() +RiEnd() +\end{verbatim} + +Running the above example produces this image: + +\begin{center} +\includegraphics[width=12cm]{pics/koch} +\end{center} + Modified: cgkit/trunk/doc/tex/hammersley.tex =================================================================== --- cgkit/trunk/doc/tex/hammersley.tex 2008-02-23 19:37:04 UTC (rev 237) +++ cgkit/trunk/doc/tex/hammersley.tex 2008-02-24 11:31:59 UTC (rev 238) @@ -18,7 +18,7 @@ Tien-Tsin Wong, Wai-Shing Luk, Pheng-Ann Heng\\ {\em Sampling with Hammersley and Halton points}\\ Journal of Graphics Tools, Vol. 2, No. 2, 1997, pp. 9-24\\ -\url{http://www.acm.org/jgt/papers/WongLukHeng97/}\\ +\url{http://jgt.akpeters.com/papers/WongLukHeng97/}\\ \url{http://www.cse.cuhk.edu.hk/~ttwong/papers/udpoint/udpoints.html} % planeHammersley Modified: cgkit/trunk/doc/tex/mayaascii.tex =================================================================== --- cgkit/trunk/doc/tex/mayaascii.tex 2008-02-23 19:37:04 UTC (rev 237) +++ cgkit/trunk/doc/tex/mayaascii.tex 2008-02-24 11:31:59 UTC (rev 238) @@ -42,7 +42,7 @@ method that has to execute the command. These callback methods have to be implemented in a derived class. -There are 11 MEL commands that can appear in a Maya ASCII +There are 12 MEL commands that can appear in a Maya ASCII file\footnote{Actually, there could appear any MEL command, but at least Maya will only export files containing the above commands.}: @@ -58,6 +58,7 @@ \item {\tt disconnectAttr} \item {\tt parent} \item {\tt select} +\item {\tt lockNode} \end{itemize} Each command has a number of arguments and can also take options. The @@ -83,6 +84,11 @@ messages. \end{memberdesc} +\begin{methoddesc}{abort}{} +Aborts reading the current file. +This method can be called in handler methods to abort reading the file. +\end{methoddesc} + \begin{methoddesc}{read}{f} Read the content of a file. \var{f} is either a file like object that can be used to read the content of the file or the name of a file. @@ -152,6 +158,11 @@ containing the node names. \end{methoddesc} +\begin{methoddesc}{onLockNode}{objects, opts} +Lock/unlock a node. \var{objects} is a list of strings containing the node +names (the list may be empty). +\end{methoddesc} + %---------------------------------------------------------------- \subsection{DefaultMAReader class} Added: cgkit/trunk/doc/tex/mayabinary.tex =================================================================== --- cgkit/trunk/doc/tex/mayabinary.tex (rev 0) +++ cgkit/trunk/doc/tex/mayabinary.tex 2008-02-24 11:31:59 UTC (rev 238) @@ -0,0 +1,113 @@ +\section{\module{mayabinary} --- + Reading Maya Binary files} + +\declaremodule{extension}{cgkit.mayabinary} +\modulesynopsis{Reading Maya Binary files} + +This module contains the \class{MBReader} class which can be used as a +base class for reading Maya Binary (*.mb) files. The class parses the +structure of the file and invokes a callback method for every chunk found +in the file. The actual decoding of the chunk data has to be done in a +derived class. +%---------------------------------------------------------------- +\subsection{MBReader class} + +The \class{MBReader} class reads Maya Binary files and calls +appropriate methods which have to be implemented in a derived class. +A Maya Binary file is composed of chunks that contain the actual data. +There can be data chunks that contain the actual data and group chunks +that contain the data chunks. + +\begin{classdesc}{MBReader}{} + Creates an instance of the reader. +\end{classdesc} + +\begin{memberdesc}{filename} +The file name (if it could be obtained). This may be used for generating +warning or error messages. +\end{memberdesc} + +\begin{methoddesc}{read}{file} +Read the content of a file. \var{file} is either a file like object that +can be used to read the content of the file or the name of a file. +\end{methoddesc} + +\begin{methoddesc}{abort}{} +Aborts reading the current file. +This method can be called in handler methods to abort reading the file. +\end{methoddesc} + +\begin{methoddesc}{onBeginGroup}{chunk} +Callback that is called whenever a new group tag begins. +\var{chunk} is a GroupChunk object (see section \ref{groupchunkclass}) +containing information about the group chunk. +\end{methoddesc} + +\begin{methoddesc}{onEndGroup}{chunk} +Callback that is called whenever a group goes out of scope. +\var{chunk} is a GroupChunk object (see section \ref{groupchunkclass}) +containing information about the group chunk (it is the same instance that was passed to \method{onBeginGroup()}). +\end{methoddesc} + +\begin{methoddesc}{onDataChunk}{chunk} +Callback that is called for each data chunk. +\var{chunk} is a Chunk object (see section \ref{chunkclass}) that contains +information about the chunk and that can be used to read the actual chunk data. +\end{methoddesc} + +%---------------------------------------------------------------- +\subsection{Chunk class} +\label{chunkclass} + +A \class{Chunk} object is passed to the callback methods of the +\class{MBReader} class. It contains information about the current +chunk and it can be used to read the actual chunk data. +A \class{Chunk} object has the following attributes and methods: + +\begin{memberdesc}{tag} +This is a string containing four characters that represent the chunk +name. +\end{memberdesc} + +\begin{memberdesc}{size} +The size in bytes of the data part of the chunk. +\end{memberdesc} + +\begin{memberdesc}{pos} +The absolute position of the data part within the input file. +\end{memberdesc} + +\begin{memberdesc}{depth} +The depth of the chunk (i.e. how deep it is nested). The root +has a depth of 0. +\end{memberdesc} + +\begin{memberdesc}{parent} +The GroupChunk object of the parent chunk. In the case of the root group +chunk this attribute is \code{None}. +\end{memberdesc} + + +\begin{methoddesc}{chunkPath}{} +Return a string containing the full path to this chunk. +The result is a concatenation of all chunk names that lead to this chunk. +\end{methoddesc} + +\begin{methoddesc}{read}{bytes=-1} +Read the specified number of bytes from the chunk. +If bytes is -1 the entire chunk data is read. The return value is a +string containing the binary data. +\end{methoddesc} + +%---------------------------------------------------------------- +\subsection{GroupChunk class} +\label{groupchunkclass} + +The \class{GroupChunk} class is derived from the \class{Chunk} class (see +section \ref{chunkclass}), so it has the same attributes and methods. In addition +it defines one more attribute: + +\begin{memberdesc}{type} +This is a string containing four characters that represent the group type. +\end{memberdesc} + Modified: cgkit/trunk/doc/tex/ri.tex =================================================================== --- cgkit/trunk/doc/tex/ri.tex 2008-02-23 19:37:04 UTC (rev 237) +++ cgkit/trunk/doc/tex/ri.tex 2008-02-24 11:31:59 UTC (rev 238) @@ -1,21 +1,21 @@ \section{\module{ri} --- - RenderMan binding} + Generic RenderMan binding to produce RIB} \declaremodule{extension}{cgkit.ri} -\modulesynopsis{RenderMan binding} +\modulesynopsis{Generic RenderMan binding to produce RIB} The RenderMan\textsuperscript{\textregistered} interface is an API that is used to communicate a 3D scene description (which includes 3D geometry, light sources, a camera description, etc) to a renderer which will produce a 2D image of that scene. The API itself is -independent of a particular renderer and can be used for a whole bunch -of renderers, where each could use entirely different rendering -algorithms. There are some excellent renderers freely available, such +independent of a particular renderer and can be used for any renderer +that adheres to the RenderMan standard. +There are some excellent renderers freely available, such as \ulink{3Delight}{http://www.3delight.com/} or the Open Source renderer -\ulink{Aqsis}{http://www.aqsis.com/} or +\ulink{Aqsis}{http://aqsis.sourceforge.net/} or \ulink{Pixie}{http://pixie.sourceforge.net/}. On the commercial side, the most popular renderers are Pixar's -\ulink{Photorealistic RenderMan}{http://www.pixar.com/} (PRMan), +\ulink{Photorealistic RenderMan}{http://renderman.pixar.com/} (PRMan), \ulink{RenderDotC}{http://www.dotcsw.com/} and \ulink{AIR}{http://www.sitexgraphics.com/}. The RenderMan interface was @@ -29,6 +29,10 @@ newer features such as string handles for light sources or object instances. +There is another RenderMan module called \refmodule[cgkit.cri]{cri} that +interfaces a renderer directly. Almost everything that is said in this section +applies to the \module{cri} module as well. + \subsection{Using the API} It is safe to import the module using @@ -71,6 +75,11 @@ The program is launched and the RIB stream is piped into it. \end{itemize} +Note: When using the \module{cri} module you first have to load a library +and invoke the functions on the returned handle (see the section on the +\refmodule[cgkit.cri]{cri} module for more information about that). The +interpretation of the argument to \function{RiBegin()} is then dependent on the +renderer you are using. %----------- \subsection{Online documentation} @@ -119,10 +128,12 @@ {\bf Types} -In this binding typing is not as strict as in the C API. The type names -RtBoolean, RtInt, RtFloat, etc. don't exist in this API, you just use -the corresponding Python types (for booleans the module defines the -constants \code{RI_TRUE} and \code{RI_FALSE}). +In this binding typing is not as strict as in the C API. For compatibility +reasons, the RenderMan types (RtBoolean, RtInt, RtFloat, etc.) do exist +but they are just aliases to the corresponding built-in Python types and +you never have to use them explicitly. +In the ctypes-based \module{cri} module, the types refer to the respective +ctypes types and you may want to use them occasionally to construct arrays. Wherever the API expects vector types (RtPoint, RtMatrix, RtBound, RtBasis) you can use any value that can be interpreted as a sequence @@ -187,6 +198,7 @@ \end{verbatim} This is useful if you generate the parameter list on the fly in your program. + \end{itemize} {\bf Arrays} @@ -228,17 +240,32 @@ RiTrimCurve() \end{verbatim} +When using the \module{cri} module it is particularly advantageous to pass +arrays as ctypes arrays or numpy arrays. In this case, no data conversion is +required which makes the function call considerably faster (particularly for +large amounts of data). + +\begin{verbatim} +# Creating a ctypes array of floats +points = (12*RtFloat)(0,1,0, 0,1,1, 0,0,1, 0,0,0) + +# Creating a numpy array of floats +points = numpy.array([0,1,0, 0,1,1, 0,0,1, 0,0,0], dtype=numpy.float32) +\end{verbatim} + {\bf User defined functions} -Some RenderMan functions allow to take user defined functions as input -which will be used during rendering. Since this implementation only -outputs RIB streams it is not possible to use your own functions in -these cases, instead you always have to use one of the predefined -functions. +Some RenderMan functions may take user defined functions as input +which will be used during rendering. When using the \module{cri} module to +link to an actual RenderMan library you can use Python functions in +addition to the standard functions. However, in the case of the +generic (\module{ri}) module, you can only use the predefined +standard functions. {\em Filter functions} -It is not possible to use your own filter functions, you have to use +It is not possible to use your own filter functions in combination +with the \module{ri} module, you have to use one of the predefined filters: \begin{itemize} @@ -290,10 +317,11 @@ {\bf Empty stubs} -All the functions do what they are supposed to do (well, hopefully ;) -except for the function RiTransformPoints(). This function is defined -but it does nothing, it is only an empty stub (since the module only -outputs RIB and does not maintain transformation matrices). +In the \module{ri} module, the function RiTransformPoints() always +returns None and never transforms points (as the module just outputs +RIB and does not maintain transformations matrices). +In the \module{cri} module, on the other hand, the function is available +and can be used to transform points. %----------- \subsection{Implementation specific options} This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |