home *** CD-ROM | disk | FTP | other *** search
/ Hackers Magazine 57 / CdHackersMagazineNr57.iso / Software / Multimedia / k3d-setup-0.7.11.0.exe / lib / site-packages / cgkit / Interfaces / irenderer.py < prev    next >
Encoding:
Python Source  |  2007-01-11  |  7.8 KB  |  202 lines
  1. # ***** BEGIN LICENSE BLOCK *****
  2. # Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3. #
  4. # The contents of this file are subject to the Mozilla Public License Version
  5. # 1.1 (the "License"); you may not use this file except in compliance with
  6. # the License. You may obtain a copy of the License at
  7. # http://www.mozilla.org/MPL/
  8. #
  9. # Software distributed under the License is distributed on an "AS IS" basis,
  10. # WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11. # for the specific language governing rights and limitations under the
  12. # License.
  13. #
  14. # The Original Code is the Python Computer Graphics Kit.
  15. #
  16. # The Initial Developer of the Original Code is Matthias Baas.
  17. # Portions created by the Initial Developer are Copyright (C) 2004
  18. # the Initial Developer. All Rights Reserved.
  19. #
  20. # Contributor(s):
  21. #
  22. # Alternatively, the contents of this file may be used under the terms of
  23. # either the GNU General Public License Version 2 or later (the "GPL"), or
  24. # the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  25. # in which case the provisions of the GPL or the LGPL are applicable instead
  26. # of those above. If you wish to allow use of your version of this file only
  27. # under the terms of either the GPL or the LGPL, and not to allow others to
  28. # use your version of this file under the terms of the MPL, indicate your
  29. # decision by deleting the provisions above and replace them with the notice
  30. # and other provisions required by the GPL or the LGPL. If you do not delete
  31. # the provisions above, a recipient may use your version of this file under
  32. # the terms of any one of the MPL, the GPL or the LGPL.
  33. #
  34. # ***** END LICENSE BLOCK *****
  35. # $Id: irenderer.py,v 1.1.1.1 2004/12/12 14:31:42 mbaas Exp $
  36.  
  37. class IRenderer:
  38.     """The basic renderer interface.
  39.     
  40.     The renderer is responsible for displaying the scene on the screen
  41.     in real time (i.e. frame rates that allow working with the scene
  42.     interactively). 
  43.     
  44.     There are actually two classes involved in rendering, the Renderer
  45.     (this class) and a RenderInstance class (IRenderInstance). The
  46.     Renderer class represents a particlar rendering algorithm or
  47.     render engine while the RenderInstance is used for rendering on
  48.     a particular widget. All RenderInstances that were spawned from
  49.     the same Renderer can share resources like display lists, textures, etc.
  50.         
  51.     Before a scene can be rendered a renderer object has to be created
  52.     that is connected to one particular scene (which is passed to the 
  53.     constructor). Then, for each view you create a RenderInstance object
  54.     by calling createRenderInstance().
  55.     On a render instance you can set various parameters like render flags, 
  56.     camera and viewport parameters via 
  57.     \link IRenderInstance::setRenderFlags setRenderFlags() \endlink, 
  58.     \link IRenderInstance::setCamera setCamera() \endlink and
  59.     \link IRenderInstance::setViewport setViewport() \endlink. Once 
  60.     everything is set up, the scene can be
  61.     rendered by calling \link IRenderInstance::paint paint() \endlink for 
  62.     every frame. A picking operation can be performed using the 
  63.     \link IRenderInstance::pick pick() \endlink method.
  64.     
  65.     Of course, an actual implementation of the interface may actually
  66.     contain more methods to activate special features supported by
  67.     this particular renderer (e.g. shadows, shaders, ...).
  68.     
  69.     There are two "flavors" of renderers, one that expects the application
  70.     to provide the rendering widget and one that creates its own window.
  71.     The interface is the same, only the semantics of some methods change
  72.     slightly. If a renderer creates its own window it has to do so in
  73.     the createRenderInstance() method and close the window again in 
  74.     \link IRenderInstance::close RenderInstance.close() \endlink. 
  75.     An embedded renderer can assume that its 
  76.     associated rendering context was previously made current by the 
  77.     application for most of the calls (as noted in the
  78.     method documentations).
  79.     
  80.     \see IRenderInstance
  81.     """
  82.         
  83.     def __init__(self, scene):
  84.         """Constructor.
  85.         
  86.         \param scene (\c IScene) The scene interface of the scene that
  87.             is to be rendered.
  88.         """
  89.         
  90.     def createRenderInstance(self):
  91.         """Open & initialize a render instance.
  92.         
  93.         The renderer will set default values for the flags, camera
  94.         and viewport.
  95.         
  96.         If the renderer is embedded this method may only be called if
  97.         the associated rendering context (OpenGL context) is made current.        
  98.  
  99.         \return Render instance object (\c RenderInstance)
  100.         """
  101.         
  102.         
  103.         
  104. class IRenderInstance:
  105.     """The render instance.
  106.     
  107.     \see IRenderer
  108.     """
  109.  
  110.     def close(self):
  111.         """Close the renderer interface.
  112.         
  113.         Frees any resources that were previously allocated.
  114.         """
  115.  
  116.     def setRenderFlags(self, flags):
  117.         """Set the flags that determine how the scene is rendered.
  118.         
  119.         The \a flags parameter is a combination of the following flags:
  120.             
  121.         - \c SOLID: Draw the scene using shaded solid faces
  122.         - \c WIREFRAME: Draw the scene using unlit wireframes (this flag can 
  123.              be combined with SOLID)
  124.         - \c SMOOTH: Use smooth shading, otherwise flat (has only an effect
  125.              when SOLID is set)
  126.         - \c TEXTURE: Use texture mapping (has only an effect when SOLID
  127.              is set)
  128.         
  129.         \param flags (\c int) Flags
  130.         """
  131.         
  132.     def getRenderFlags(self):
  133.         """Return the current render flags.
  134.         
  135.         \return Flags (\c int).
  136.         \see setRenderFlags()
  137.         """
  138.         
  139.     def setCamera(self, cam):
  140.         """Set the camera to use for viewing the scene.
  141.         
  142.         The camera interface \a cam is used to retrieve the location
  143.         and orientation of the camera (= inverse view transformation)
  144.         and the projection matrix (which determines if the camera
  145.         is an orthographic or perspective camera).
  146.         
  147.         \param cam (\c IViewCamera) Camera interface
  148.         """
  149.         
  150.     def getCamera(self):
  151.         """Return the currently active camera.
  152.         
  153.         \return Camera (\c IViewCamera)
  154.         \see setCamera()
  155.         """
  156.         
  157.     def setViewport(self, viewport):
  158.         """Set the viewport settings.
  159.         
  160.         \a viewport contains the position and size (x,y,width,height) of 
  161.         the viewing area in pixels.
  162.         
  163.         If the renderer is embedded this method may only be called if
  164.         the associated rendering context (OpenGL context) is made current.
  165.         
  166.         \param viewport (\c IViewportSettings) Viewport settings
  167.         """
  168.         
  169.     def getViewport(self):
  170.         """Return the viewport settings.
  171.         
  172.         \return Viewport settings (\c IViewportSettings).
  173.         \see setViewport()
  174.         """
  175.     
  176.     def paint(self):
  177.         """Renders the scene.
  178.         
  179.         The scene that was given to the open() call is rendered
  180.         using the current camera, viewport settings and render flags.
  181.         
  182.         If the renderer is embedded this method may only be called if
  183.         the associated rendering context (OpenGL context) is made current.
  184.         
  185.         \see setRenderFlags(), setCamera(), setViewport()
  186.         """
  187.         
  188.     def pick(self, x, y):
  189.         """Performs a picking operation and returns the picked objects.
  190.         
  191.         Performs a picking operation at pixel position (\a x, \a y)
  192.         and returns all objects that were hit in depth sorted order (nearest
  193.         first).
  194.         
  195.         If the renderer is embedded this method may only be called if
  196.         the associated rendering context (OpenGL context) is made current.
  197.                 
  198.         \param x (\c int) Pick position in pixels (X)
  199.         \param y (\c int) Pick position in pixels (Y)
  200.         """
  201.         
  202.