Every window in pyglet has its own OpenGL context. Each context has its own OpenGL state, including the matrix stacks and current flags. However, contexts can optionally share their objects with one or more other contexts. Shareable objects include:
There are two reasons for sharing objects. The first is to allow objects to be stored on the video card only once, even if used by more than one window. For example, you could have one window showing the actual game, with other "debug" windows showing the various objects as they are manipulated. Or, a set of widget textures required for a GUI could be shared between all the windows in an application.
The second reason is to avoid having to recreate the objects when a context needs to be recreated. For example, if the user wishes to turn on multisampling, it is necessary to recreate the context. Rather than destroy the old one and lose all the objects already created, you can
pyglet defines an ObjectSpace: a representation of a collection of objects used by one or more contexts. Each context has a single object space, accessible via its object_space attribute.
By default, all contexts share the same object space as long as at least one context using it is "alive". If all the contexts sharing an object space are lost or destroyed, the object space will be destroyed also. This is why it is necessary to follow the steps outlined above for retaining objects when a context is recreated.
pyglet creates a hidden "shadow" context as soon as pyglet.gl is imported. By default, all windows will share object space with this shadow context, so the above steps are generally not needed. The shadow context also allows objects such as textures to be loaded before a window is created.
When you create a Context, you tell pyglet which other context it will obtain an object space from. By default (when using the Window constructor to create the context) the most recently created context will be used. You can specify another context, or specify no context (to create a new object space) in the Context constructor.
It can be useful to keep track of which object space an object was created in. For example, when you load a font, pyglet caches the textures used and reuses them; but only if the font is being loaded on the same object space. The easiest way to do this is to set your own attributes on the ObjectSpace object.
In the following example, an attribute is set on the object space indicating that game objects have been loaded. This way, if the context is recreated, you can check for this attribute to determine if you need to load them again:
context = pyglet.gl.get_current_context() object_space = context.object_space object_space.my_game_objects_loaded = True
Avoid using attribute names on ObjectSpace that begin with "pyglet", they may conflict with an internal module.