104. opengl.drawable — OpenGL rendering objects for the new OpenGL2 engine.

104.1. Classes defined in module opengl.drawable

class opengl.drawable.Drawable(parent, **kargs)

Base class for objects that can be rendered by the OpenGL engine.

This is the basic drawable object in the pyFormex OpenGL rendering engine. It collects all the data that are needed to properly described any object to be rendered by the OpenGL shader programs. It has a multitude of optional attributes allowing it to describe many very different objects and rendering situations.

This class is however not intended to be directly used to construct an object for rendering. The Actor class and its multiple subclasses should be used for that purpose. The Actor classes provide an easier and more logical interface, and more powerful at the same time, since they can be compound: one Actor can hold multiple Drawables.

The elementary objects that can be directly drawn by the shader programs are more simple, yet very diverse. The Drawable class collects all the data that are needed by the OpenGL engine to do a proper rendering of the object. It this represents a single, versatile interface of the Actor classes with the GPU shader programs.

The versatility comes from the Attributes base class, with an unlimited set of attributes. Any undefined attribute just returns None. Some of the most important attributes are described hereafter:

• rendertype: int: the type of rendering process that will be applied by the rendering engine to the Drawable:

  0: A full 3D Actor. The Drawable will be rendered in full 3D with

  all active capabilities, such as camera rotation, projection, rendermode, lighting. The full object undergoes the camera transformations, and thus will appear as a 3D object in space. The object’s vertices are defined in 3D world coordinates. Used in: Actor.

  1: A 2D object (often a text or an image) inserted at a 3D position.

  The 2D object always keeps its orientation towards the camera. When the camera changes, the object can change its position on the viewport, but the oject itself looks the same. This can be used to add annotations to (parts of) a 3D object. The object is defined in viewport coordinates, the insertion points are in 3D world coordinates. Used in: textext.Text.

  2: A 2D object inserted at a 2D position. Both object and position

  are defined in viewport coordinates. The object will take a fixed position on the viewport. This can be use to add decorations to the viewport (like color legends and background images). Used in: decors.ColorLegend.

  3: Like 2, but with special purpose. These Drawables are not part of

  the user scene, but used for system purposes (like setting the background color, or adding an elastic rectangle during mouse picking). Used in: Canvas.createBackground().

  -1: Like 1, but with different insertion points for the multiple items

  in the object. Used to place a list of marks at a list of points. Used in: textext.Text.

  -2: A 3D object inserted at a 2D position. The 3D object will rotate

  when the camera changes directions, but it will always be located on the same position of the viewport. This is normally used to display a helper object showing the global axis directions. Used in: decors.Triade.

The initialization of a Drawable takes a single parameter: parent, which is the Actor that created the Drawable. All other parameters should be keyword arguments, and are stored as attributes in the Drawable.

Methods:

• prepare…: creates sanitized and derived attributes/data. Its action depends on current canvas settings: mode, transparent, avgnormals

• render: push values to shader and render the object: depends on canvas and renderer.

• pick: fake render to be used during pick operations

• str: format the full data set of the Drawable

prepareColor()

Prepare the colors for the shader.

changeVertexColor(color)

Change the vertex color buffer of the object.

This is experimental!!! Just make sure that the passed data have the correct shape!

prepareTexture()

Prepare texture and texture coords

prepareIndex()

Create an index buffer to draw subelements

This is always used for nplex > 3, but also to draw the edges for nplex=3.

render(renderer)

Render the geometry of this object

renderpick(renderer)

Render for picking

class opengl.drawable.BaseActor(**kargs)

Base class for all drawn objects (Actors) in pyFormex.

This defines the interface for all drawn objects, but does not implement any drawn objects. Drawable objects should be instantiated from the derived classes. Currently, we have the following derived classes:

Actor: a 3-D object positioned and oriented in the 3D scene. Defined

in actors.py.

Mark: an object positioned in 3D scene but not undergoing the camera

axis rotations and translations. It will always appear the same to the viewer, but will move over the screen according to its 3D position. Defined in marks.py.

Decor: an object drawn in 2D viewport coordinates. It will unchangeably

stick on the viewport until removed. Defined in decors.py.

The BaseActor class is just an Attributes dict storing all the rendering parameters, and providing defaults from the current canvas drawoptions for the essential parameters that are not specified.

Additional parameters can be set at init time or later using the update method. The specified parameters are sanitized before being stored.

Arguments processed by the base class:

• marksize: force to float and also copied as pointsize

setLineWidth(linewidth)

Set the linewidth of the Drawable.

setLineStipple(linestipple)

Set the linewidth of the Drawable.

setColor(color=None, colormap=None, ncolors=1)

Set the (single) color of the BaseActor.

setTexture(texture)

Set the texture data of the Drawable.

class opengl.drawable.Actor(obj, **kargs)

Proposal for drawn objects

__init__: store all static values: attributes, geometry, vbo’s prepare: creates sanitized and derived attributes/data render: push values to shader and render the object

__init__ is only dependent on input attributes and geometry

prepare may depend on current canvas settings:

mode, transparent, avgnormals

render depends on canvas and renderer

If the actor does not have a name, it will be given a default one.

The actor has the following attributes, initialized or computed on demand

property coords

Return the fused coordinates of the object

property elems

Return the original elems of the object

property ndim

Return the dimensionality of the object.

property b_normals

Return individual normals at all vertices of all elements

property b_avgnormals

Return averaged normals at the vertices

changeColor(color=None, colormap=None, bkcolor=None, bkcolormap=None)

Change the colors of an actor.

Changes the specified non-None values and repaints the actor accordingly. Note: you can not set a value to None using this method. Set the attribute directly and then call changeColor. For example, to remove the back color, do:

actor.bkcolor = None
actor.changeColor()

To repaint an actor with the current objects’s prop values, do:

actor.changeColor(color='prop')

prepare(canvas)

Prepare the attributes for the renderer.

This sanitizes and completes the attributes for the renderer. Since the attributes may be dependent on the rendering mode, this method is called on each mode change.

changeMode(canvas)

Modify the actor according to the specified mode

fullElems()

Return an elems index for the full coords set

subElems(nsel=None, esel=None)

Create indices for the drawable subelems

This indices always refers to the full coords (fcoords).

The esel selects the elements to be used (default all).

The nsel selects (possibly multiple) parts from each element. The selector is 2D (nsubelems, nsubplex). It is applied on all selected elements

If both esel and esel are None, returns None

property faces

Return the faces of the object as they will be drawn

Returns a dict with parameters for the Drawable

selectedFaces(esel)

Return selected faces of the object as they will be drawn

This is like faces but only containing some elements.

property edges

Return the edges of the object as they will be drawn

This returns a 2D index in a single element. All elements should have compatible node numberings.

highlighted()

Return True if the Actor is highlighted.

The highlight can be full (self.highlight=1) or partial (self._highlight is not None).

removeHighlight()

Remove the highlight for the current actor.

Remove the highlight (whether full or partial) from the actor.

setHighlight()

Add full highlighting of the actor.

This makes the whole actor being drawn in the highlight color.

addHighlightElements(sel=None)

Add a highlight for the selected elements. Default is all.

addHighlightPoints(sel=None)

Add a highlight for the selected points. Default is all.

okColor(color, colormap=None)

Compute a color usable by the shader.

The shader (currently) only supports 3*float type of colors:

• None

• single color (separate for front and back faces)

• vertex colors

setAlpha(alpha, bkalpha=None)

Set the Actors alpha value.

setTexture(texture, texcoords=None, texmode=None)

Set the texture data of the Drawable.

render(renderer)

Render the geometry of this object

renderpick(renderer)

Render the geometry of this object

inside(camera, rect=None, mode='actor', sel='any', return_depth=False)

Test whether the actor is rendered inside rect of camera.

Parameters:

• camera (Camera) – A properly initialized Camera. Usually it will be the current canvas camera (pf.canvas.camera).

• rect (tuple[int], optional) – A tuple (x,y,w,h) specifying a rectangular subregion of the camera’s viewport. (x,y) is the lower left angle, (w,h) are the width and height, all in pixels. If not provided the full camera viewport is used.

• mode (str) –

  The testing mode. Currently one of:

  • ’actor’ (default): test if the actor is (partly) inside

  • ’element’: test which elements of the actor are inside

  • ’point’: test which vertices of the actor are inside

• sel (str) – One of ‘all’ or ‘any’. This is not used with ‘point’ mode. For the other modes it specifies whether all or any of the points of the actor or element should be inside the rectangle in order to be flagged as a positive.

• return_depth (bool) – If True, also returns the z-depth of the objects that are found inside the rectangle. The z-depth is the closest distance of the object to the camera.

Returns:

• inside (bool | int array) – In ‘actor’ mode, returns True if the Actor is inside the rectangle, or False otherwise. If ‘element’ and ‘point’ mode, returns an array with the indices of the actor’s elements or points that are inside the rectangle.

• depth (float array) – The z-depth of the objects inside the rectangle. Only returned if return_depth is True.

104.2. Functions defined in module opengl.drawable

opengl.drawable.polygonFaceIndex(n)

Return a selector to get triangle fan elements from polygon

Examples

>>> polygonFaceIndex(5)
array([[0, 1, 2],
       [0, 2, 3],
       [0, 3, 4]])

opengl.drawable.polygonEdgeIndex(n)

Return a selector to get edge elements from polygon

Examples

>>> polygonEdgeIndex(5)
array([[0, 1],
       [1, 2],
       [2, 3],
       [3, 4],
       [4, 0]])