GL Contexts

GL Contexts

All Jitter OpenGL rendering happens within a named context. An OpenGL context is typically created using combined with one of three objects that serve as output for rendering. These output objects are jit.window, jit.pwindow, and jit.matrix. For simplicity, the object combines and jit.window into a single object, and is recommended for most cases. The name given to the output object (most often jit.window) sets the rendering context name. Contexts that don’t have an explicit name are given an automatically generated name.

In order to draw, Jitter OpenGL objects must be associated with a valid context, either by giving the context name as an argument or implicitly (see below). The and objects will automatically draw any objects associated with them. For all objects, the first argument sets the drawto attribute. It tells the object where to draw to. The or object will drive the rendering of each frame to the output window, signaling all objects associated with their context to draw. By default, all objects that draw geometry will be set to automatically draw (@automatic 1) when signals.

Implicit Contexts

It is not necessary to specify a context name for every or video object. Instead, we can make use of implicit contexts. Implicit contexts automatically assign a name to an object’s drawto attribute. This can be handy in patches where there is only one context in use and makes it easier to copy work from one patch to another.

If an object is in the same patcher as a valid OpenGL context, the system will automatically assign the context name to the object’s drawto. Additionally, if a or video object is in a sub-patch of a patch with a valid OpenGL context, it will be assigned to that context name.

Some situations require an implicitly named context — using in a Max for Live device requires that implicitly named context or a context named using a --- (triple-dash).

GL objects added implicitly to a GL context
NOTE: Some care should be taken when using implicit contexts. Certain situations may produce unexpected results. If a patch with a GL context contains a sub-patch with another GL context (e.g. a jit.pwindow), which contains another sub-patch with objects, those sub-sub-patch objects will be associated with the first GL context they find. In this case it will be the sub-patch jit.pwindow context rather than the parent patch context. For cases like this it is better to explicitly assign the context name to your objects.

Sub-Contexts With

A sub-context is a rendering context within a rendering context. Within a top-level context, there can be many sub-contexts. Sub-contexts are created by objects. The name of a sub-context is given by’s name attribute. Any object whose drawto attribute is set to the name of a belongs to the node’s sub-context. There are no restrictions on how sub-contexts can be organized, so it’s perfectly valid to nest sub-contexts within each other by placing a within another’s sub-context.

To make organizing objects into groups simpler, a patch cord can be connected from’s middle inlet to any objects. When the connection is made, the object’s drawto will automatically be set to the node’s name such that it becomes part of the sub-context. and Implicit Contexts

As described above, with implicit contexts objects automatically attach to the first context that they encounter if they aren’t explicitly attached to a context with the drawto attribute. Since also operates as a rendering context, objects can attach to nodes implicitly.

If a and a jit.window or jit.pwindow are in the same patch, the window will take priority over the node when objects search for an implicit context. A object will only attach to a implicitly if it is the only context generating object in the patch. A common idiom is to put a object in a subpatch with other objects, forcing them to implicitly attach to the node.

3 ways GL objects can be added to sub-contexts

Grouping Objects Into "Scenes"

Using, objects can be grouped into "scenes". If an object belongs to a node’s sub-context, the node controls how and when the object draws. The spatial transformation attributes position, rotate, and scale on a node are applied to all of the objects in the node’s sub-context. The node itself doesn’t draw any geometry, it simply groups objects together. Common attributes applied to, will apply to every object associated with that sub-context.

The layer and enable attributes allow control of when the scene is drawn (relative to other objects in the parent context), and whether the scene is drawn at all. If a’s enable attribute is set to 0, associated objects will not be drawn. This feature can be used to turn on and off the drawing of entire groups of objects from one point.

Controlling scene properties with

Rendering Sub-Contexts to Texture has a capture attribute that if enabled will render its sub-context to an internal texture. When capture is enabled, outputs a out its left-most outlet every time it draws itself. In this mode, and objects can be chained to the node to create post-processing effects such as blurring, glow, temporal blending, etc. has several attributes pertaining to render to texture:

  • adapt - texture dimensions should adapt to destination window dimensions
  • dim - dimensions of texture when adapt is disabled
  • type - data type of the texture
  • erase_color - background color of texture

Post processing with

As mentioned above, the object encapsulates a GL context ( and jit.window) into a single object. In most cases, using will provide the most convenient way to get started in Jitter. The object also contains an internal object, providing sub-context functionality as well. The first argument and name attribute of sets the name attribute of the internal For most purposes, the internal can be ignored and can be treated like a typical rendering context. To set the context name, use the drawto attribute. If not set explicitly, it will be automatically generated.

Any objects associated with the are included in the sub-context. This makes it very easy to render the scene to a texture or matrix. Two attributes expose this functionality - output_texture and output_matrix. Similar to, the captured scene is output from the left-most outlet when capturing is enabled. Texture output (@output_texture 1) should be used in cases where scene renders will be passed back to OpenGL objects or used in inter-application systems like Syphon or Spout.

Another option for scene output from is matrix output, enabled via the output_matrix attribute. This causes the captured texture output to be rendered into an internal jit.matrix object, via asynchronous matrix readback. When output_matrix is enabled, the matrix is sent out the left-most outlet instead of the texture. This is useful primarily for recording video captures or saving image files of the scene render.

Additional features

  • enable_cornerpin - allows cornerpin skewing of the scene via an internal
  • auto_handle - spatial transforms of scene objects via an internal
  • esc_fullscreen - an escape key handler to toggle the render window’s fullscreen mode
  • middle outlet draw bang - a bang sent out the middle outlet in sync with renderer frames, set to either pre or post render frame via the drawbang attribute
  • - an internal physics context, automatically enabled when jit.phys objects are added to the patcher

All internal objects of are addresable via the following message handlers:


The displaylink attribute enables a Mac only feature of When enabled, the Mac OS will trigger the context rendering in sync with the connected hardware display’s refresh rate (typically 60 hz). This means every time the display redraws, the context will trigger a redraw in sync with the display. There is an unexpected side-effect of displaylink rendering, where GUI updates may cause stalls in the rendering, more so than if displaylink is disabled. Therefore, users are recommended to try both modes and determine which better fits their needs.

Further Reading

See Also

Name Description
Working with OpenGL Working with OpenGL