Player & Canvas

This section describes the classes that provide a framework for rendering. The Player class is an interface to the avg renderer. The Canvas class and its descendant OffscreenCanvas provide areas to draw on.

class libavg.avg.Canvas

Bases: libavg.avg.ExportedObject

A Canvas is a tree of nodes. It is the place where a scenegraph is displayed. In a libavg session, there is one main canvas that corresponds to the screen (which is of class Canvas) and zero or more canvases that are rendered offscreen (which are of class OffscreenCanvas).

getElementByID(id) → Node

Returns the element in the canvas’s tree that has the id given.

screenshot() → Bitmap

Returns the image the canvas has last rendered as Bitmap. For the main canvas, this is a real screenshot. For offscreen canvases, this is the image rendered offscreen.

getRootNode() → CanvasNode

Returns the root of the scenegraph. For the main canvas, this is an AVGNode. For an offscreen canvas, this is a CanvasNode.

class libavg.avg.OffscreenCanvas

Bases: libavg.avg.Canvas

An OffscreenCanvas is a Canvas that is rendered to a texture. It can be referenced in the href attribute of an image node. See https://www.libavg.de/wiki/ProgrammersGuide/OffscreenRendering for an in-depth explanation of using offscreen rendering. Offscreen canvases are created by calling Player.createCanvas(), Player.loadCanvasFile() or Player.loadCanvasString().

autorender

Turns autorendering on or off. Default is True.

handleevents

True if events that arrive at an image node that is displaying this canvas are routed to the offscreen canvas. Events arrive at the correct node inside the canvas, so a click on a node will trigger an appropriate CURSOR_DOWN event. event.pos is also adjusted to be relative to the canvas root. There is a limitation, however: Events received through contacts can’t have this adjustment done. This means that gestures such as drag - which use contacts internally - won’t work correctly if scaling or rotation is involved. Read-only.

mipmap

True if mipmaps are generated and used for the canvas. This is used instead of RasterNode.mipmap for images that render the canvas. Read-only.

multisamplesamples

Number of samples per pixel to use for multisampling. Setting this to 1 disables multisampling. Read-only.

size

Size of the rendering area (and the CanvasNode) in pixels. Read-only.

getID() → string

Returns the id of the canvas. This is the same as calling canvas.getRootNode().getID().

getNumDependentCanvases()

Returns the number of canvases that reference this canvas. Used mainly for unit tests.

registerCameraNode()

render()

Forces an immediate redraw of the offscreen canvas. This makes sure that following calls to screenshot() get a current version of the canvas and is usually used in combination with autorender=False.

unregisterCameraNode()

classmethod isMultisampleSupported() → bool

True if the machine’s OpenGL implementation supports offscreen multisampling.

class libavg.avg.Player

Bases: libavg.avg.Publisher

The class used to load and play avg files and the main interface to the avg renderer. Player is a singleton. There is only one instance, accessed by avg.player.

Messages:

To get these messages, call Publisher.subscribe().

KEY_DOWN(keyEvent)

Called whenever a key is pressed.

KEY_UP(keyEvent)

Called whenever a key is released.

ON_FRAME()

Called each frame.

imageCache

The global ImageCache that keeps images in CPU and GPU memory.

pluginPath

A list of directories where the player searches for plugins when loadPlugin() is called. The separator between path entries is a semicolon (‘;’) under Windows and a colon (‘:’) under Mac and Linux.

volume

Total audio playback volume. 0 is silence, 1 passes media file volume through unchanged. Values higher than 1 can be used to amplify playback. A limiter prevents distortion when the volume is set too high.

addInputDevice(inputDevice)

Registers an InputDevice with the system.

areFullShadersSupported() → bool

Returns True if the current OpenGL configuration has full shader support. Platforms without full shader support (this includes OpenGL ES) disable several FXNode types. Calling this when playback is not running is an error.

assumePixelsPerMM(ppmm)

Tells the system to assume a resolution for the physical screen, overriding operating system information. The parameter is the number of pixels per millimeter as a float. This function affects the values returned by getPhysicalScreenDimensions() and getPixelsPerMM(). It is useful for situations in which the OS cannot know the resolution (e.g. projectors) and when the automatic functions return wrong values (which happens, unfortunately, because of operating system deficiencies).

callFromThread(pyfunc)

Executes pyfunc in the main thread of execution, in the next event handling phase. This method is the only libavg method that is thread-safe and can be called from secondary threads of execution. pyfunc can be any python callable, including any libavg methods.

clearInterval(id) → bool

Stops a timeout, an interval or an onFrameHandler from being called. Returns True if there was an interval with the given id, False if not.

Parameters:id (int) – An id returned by setInterval(), setTimeout() or setOnFrameHandler().

createCanvas(*params) → OffscreenCanvas

Creates an empty offscreen canvas. Parameters are given under OffscreenCanvas.

createMainCanvas(*params) → Canvas

Creates an empty canvas with a render window and an AVGNode as root node. Parameters are given under AVGNode.

createNode(xml) → Node

Creates a new Node. This node can be used as parameter to DivNode.appendChild() and DivNode.insertChild(). This method will create any type of node, including <div> nodes with children.

Parameters:xml – xml string conforming to the avg dtd that specifies the node to create.

createNode(type, args) → Node

Creates a new Node. This node can be used as parameter to DivNode.appendChild() and DivNode.insertChild(). This method will only create one node at a time.

Parameters:

• type (string) – Type string of the node to create (For example, image and words are valid type strings).
• args (dict) – a dictionary specifying attributes of the node.

deleteCanvas(id)

Removes the canvas given by id from the player’s internal list of canvases. It is an error to delete a canvas that is still referenced by an image node.

enableGLErrorChecks(enable)

Enables or disables checking for errors after each OpenGL call. By default, this is False, since it hurts performance in some setups. It is enabled by the tests. You do not need this method unless you are looking for errors inside libavg.

enableMouse(enable)

Enables or disable mouse event handling.

getCanvas(id) → OffscreenCanvas

Returns the offscreen canvas with the id given.

getCurrentEvent() → Event

Must be called inside an event handler and returns the event that’s being processed. Throws an exception if called outside an event handler.

getEffectiveFramerate() → float

Returns the framerate that the player is actually achieving. The value returned is not averaged and reflects only the current frame.

getElementByID(id) → Node

Returns an element in the main avg tree.

Parameters:id – id attribute of the node to return.

getEventHook() → pyfunc

Returns the last event hook set using setEventHook().

getFrameDuration() → float

Returns the number of milliseconds that have elapsed since the last frame (i.e. the last display update).

getFramerate() → float

Returns the current target framerate in frames per second. To get the actual framerate that the player is currently achieving, call getEffectiveFramerate().

getFrameTime() → int

Returns the number of milliseconds that have elapsed since playback has started. Honors FakeFPS. The time returned stays constant for an entire frame; it is the time of the last display update.

getKeyModifierState() → KeyModifier

Returns the current modifier keys pressed, or’ed together. For a list of possible values, see KeyEvent.modifiers.

getMainCanvas() → Canvas

Returns the main canvas. This is the canvas loaded using loadFile() or loadString() and displayed on screen.

getMouseState() → MouseEvent

Returns the last mouse event generated.

getPhysicalScreenDimensions() → Point2D

Returns the size of the primary screen in millimeters.

getPixelsPerMM() → float

Returns the number of dots per millimeter of the primary display. Assumes square pixels.

getRootNode() → Node

Returns the outermost element in the main avg tree.

getScreenResolution() → Point2D

Returns the size in pixels of the current screen.

getTestHelper()

getVideoMemInstalled() → int

Returns the amount of dedicated video memory installed in the system in bytes (which might be zero in case of shared-memory graphics cards). Only available when using NVidia drivers.

getVideoMemUsed() → int

Returns the amount of dedicated video memory used in bytes. This is the total amount used by all programs. Only available when using NVidia drivers.

getMemoryUsage() → int

Returns the amount of memory used by the application in bytes. More precisely, this function returns the resident set size of the process in bytes. This does not include shared libraries or memory paged out to disk.

getVideoRefreshRate() → float

Returns the current hardware video refresh rate in number of refreshes per second.

isCursorShown()

Returns True if the mouse cursor is visible.

isFullscreen()

Returns True if the player is running in fullscreen mode.

isPlaying() → bool

Returns True if play() is currently executing, False if not.

keepWindowOpen()

Tells the player to keep the playback window open after play() has returned. This makes it possible to reuse the window with another scene and play() call. It is used by the tests to keep flickering to a minimum and increase speed.

loadCanvasFile(filename) → OffscreenCanvas

Loads the canvas file specified in filename and adds it to the registered offscreen canvases.

loadCanvasString(avgString) → OffscreenCanvas

Parses avgString, loads the nodes it contains and adds the hierarchy to the registered offscreen canvases.

Parameters:avgString (string) – An xml string containing an avg node hierarchy.

loadFile(filename) → Canvas

Loads the avg file specified in filename. Returns the canvas loaded. The canvas is the main canvas displayed onscreen.

loadPlugin(name)

Load a Plugin.

Parameters:name (string) – filename of the plugin without directory and file extension.

loadString(avgString) → Canvas

Parses avgString and loads the nodes it contains. Returns the canvas loaded. The canvas is the main canvas displayed onscreen.

Parameters:avgString (string) – An xml string containing an avg node hierarchy.

play()

Opens a playback window or screen and starts playback. play returns when playback has ended.

screenshot() → Bitmap

Returns the contents of the current screen as a bitmap.

setEventHook(pyfunc)

Set a callable which will receive all events before the standard event handlers receive them. If this callable returns True, the event is not propagated to the standard event handlers.

Generally, setEventHook() should be used as a last resort. In most cases, standard event handlers are a lot cleaner. Also, setting several event hooks is not supported by libavg. To get around this limitation, you can use getEventHook() to chain event hook functions.

Note that event.node is not set in the callback, since the system hasn’t determined the node to send the event to at that point.

setFakeFPS(fps)

Sets a fixed number of virtual frames per second that are used as clock source for video playback, animations and other time-based actions. If a value of -1 is given as parameter, the real clock is used. setFakeFPS() can be used to get reproducible results for recordings or automated tests. Setting FakeFPS has the side-effect of disabling audio.

setFramerate(framerate)

Sets the desired framerate for playback. Turns off syncronization to the vertical blanking interval.

setGamma(red, green, blue)

Sets display gamma. This is a control for overall brightness and contrast that leaves black and white unchanged but adjusts greyscale values. 1.0 is identity, higher values give a brighter image, lower values a darker one.

setInterval(time, pyfunc) → int

Sets a python callable object that should be executed regularly. setInterval() returns an id that can be used to call clearInterval() to stop the function from being called. The callback is called at most once per frame.

Parameters:

• time (int) – Number of milliseconds between two calls.
• pyfunc – Python callable to execute.

setMousePos(pos)

Sets the position of the mouse cursor. Generates a mouse motion event.

setMultiSampleSamples(multiSampleSamples)

Sets the number of samples per pixel to compute. This costs performance and smoothes the edges of polygons. A value of 1 turns multisampling (also knowna as FSAA - Full-Screen Antialiasing) off. Good values are dependent on the graphics driver and the performance of the graphics card.

setOGLOptions(usePOW2Textures, usePixelBuffers, multiSampleSamples, shaderUsage=AUTO, useDebugContext=False)

Determines which OpenGL extensions to check for and use if possible. This method is mainly used for debugging purposes while developing libavg, but can also be used to work around buggy drivers. The values set here override those in the avgrc file. Note that with the exception of multiSampleSamples, fallbacks are always used - if a feature is specified that the system doesn’t support, a less demanding one will be used.

Must be called before play().

Parameters:

• usePOW2Textures (bool) – If True, restricts textures to power-of-two dimensions.
• usePixelBuffers (bool) – If False, disables the use of OpenGL pixel buffer objects.
• multiSampleSamples (int) – The number of samples per pixel to compute. This costs performance and smoothes the edges of polygons. A value of 1 turns multisampling (also known as FSAA - Full-Screen Antialiasing) off. Good values are dependent on the graphics driver and the performance of the graphics card.
• shaderUsage – Either avg.SHADERUSAGE_FULL, avg.SHADERUSAGE_MINIMAL or avg.SHADERUSAGE_AUTO. SHADERUSAGE_MINIMAL restricts shader usage to a subset that doesn’t use much GPU power.
• useDebugContext – Uses an OpenGL Debug Context for rendering if the graphics driver supports it. This causes more verbose error messages and warnings in the case of OpenGL errors.

setOnFrameHandler(pyfunc) → int

Sets a python callable object that should be executed once per frame. This is the same as setInterval(0, pyfunc). Returns an id that can be used to call clearInterval() to stop the function from being called.

Parameters:pyfunc – Python callable to execute.

setResolution(fullscreen, width, height, bpp)

Sets display engine parameters. Must be called before loadFile() or loadString().

Parameters:

• fullscreen (bool) – True if the avg file should be rendered fullscreen.
• width, height (int) – The window size (if fullscreen is False) or screen resolution (if fullscreen is True).
• bpp (int) – Number of bits per pixel to use. Valid values are 16 or 24.

setTimeout(time, pyfunc) → int

Sets a python callable object that should be executed after a set amount of time. The callable is executed exactly once (use setInterval() to trigger regular callbacks). setTimeout() returns an id that can be used to call clearInterval() to stop the function from being called.

Parameters:

• time (int) – Number of milliseconds before the call.
• pyfunc – Python callable to execute.

setVBlankFramerate(rate)

Sets the desired number of monitor refreshes before the next frame is displayed. The resulting framerate is determined by the monitor refresh rate divided by the rate parameter.

Parameters:rate (int) – Number of vertical blanking intervals to wait. On Mac OS X, only 1 is supported as rate.

setWindowConfig(configFileName)

Sets the window configuration for multi-window setups. Multi-window setups are supported on X11 and can span more than one X11 display (and thus, multiple GPUs). A sample config file can be found under src/test/avg_windowconfig.xml. Using this file, window positions and sizes can be set. Each window can show a separate portion of the main scene (a ‘viewport’).

setWindowFrame(hasWindowFrame)

hasWindowFrame should be set to True if a non-fullscreen player should have a window frame. If set to False, the player runs with no title bar or window frame. Must be called before play() is called.

setWindowPos(x, y)

Sets the location of the player window. Must be called before loadFile or loadString.

setWindowTitle(title)

Sets the string displayed in the title bar of the libavg window. Default is ‘libavg’.

showCursor(show)

Shows or hides the mouse cursor.

Parameters:show (bool) – True if the mouse cursor should be visible.

stop()

Stops playback and resets the video mode if necessary.

stopOnEscape(stop)

Toggles player stop upon escape keystroke. If stop is True (the default), if player will halt playback when Esc is pressed.

useGLES(gles)

Chooses whether to use OpenGL ES or desktop OpenGL for rendering. Must be called before play().

Parameters:gles (bool) – True if OpenGL ES should be used.

classmethod get() → Player

Deprecated since version 1.8: Use avg.player instead.

This method gives access to the player instance. If no player has been created yet, a player is created.