OpenGLContext 3.0.0a2__tar.gz → 3.0.0a4__tar.gz

openglcontext-3.0.0a4/OpenGLContext/__init__.py

@@ -0,0 +1,183 @@
+'''A 3D engine on PyOpenGL: scenes, a renderer, and a window to put it in
+
+OpenGLContext renders 3D scenes with PyOpenGL, in a window belonging to
+whichever GUI toolkit the application already uses.  GLFW, GLUT, Pygame,
+Tkinter, wxPython and Qt/PySide are all supported; GLFW is the one to reach
+for with the core profile, and Tkinter the one that needs nothing installed.
+A context can own the whole window or sit as one canvas inside a larger
+application.
+
+    from OpenGLContext.viewer import ViewerContext, ViewerOptions
+
+    class MyViewer(ViewerContext):
+        options = ViewerOptions(source='model.glb')
+
+    MyViewer.ContextMainLoop()
+
+What it holds:
+
+    scenegraph   VRML97-style nodes, plus the metallic/roughness material
+                 and mesh the glTF loader produces
+    loaders      glTF 2.0/GLB, VRML97, Wavefront OBJ and streamed 3D Tiles
+    passes       The core-profile and compatibility render passes, physically
+                 based rendering, image-based lighting, shadows, instancing
+    move         Walking, flying, swimming and mouse-look, with collision
+    physics      Rigid bodies, colliders, gravity zones and triggers
+    audio        Sound placed in the scene and heard from where you stand
+    ui           Panels, widgets and a settings screen over the live frame
+    viewer       The embeddable viewer that `oglc-view` is a command line for
+
+It is also the primary suite of test cases PyOpenGL is verified against.
+
+Documentation is under `docs/`, indexed by `docs/documentation.html`.
+'''
+
+__version__ = "3.0.0a4"
+__author__ = "Michael Colin Fletcher"
+__license__ = "BSD-Style, see license.txt for details and exceptions"
+
+from OpenGLContext.plugins import Context,InteractiveContext,VRMLContext,Loader,Node,Adapter
+
+Context( 'pygame', 'OpenGLContext.pygamecontext.PygameContext' )
+Context( 'wx', 'OpenGLContext.wxcontext.wxContext' )
+Context( 'glut', 'OpenGLContext.glutcontext.GLUTContext' )
+Context( 'glfw', 'OpenGLContext.glfwcontext.GLFWContext' )
+Context( 'tk', 'OpenGLContext.tkcontext.TkContext' )
+# Offscreen: no window, no display server.  One class fills the interactive slot
+# too, because a context nothing can click on has no separate interactive form.
+# One per platform -- EGL on Linux, WGL pbuffers on Windows -- and both are
+# registered everywhere, since which one a machine can actually create is a
+# question its answer already gives.
+Context( 'egl', 'OpenGLContext.eglcontext.EGLContext' )
+Context( 'wgl', 'OpenGLContext.wglcontext.WGLContext' )
+InteractiveContext( 'pygame', 'OpenGLContext.pygameinteractivecontext.PygameInteractiveContext' )
+InteractiveContext( 'wx', 'OpenGLContext.wxinteractivecontext.wxInteractiveContext' )
+InteractiveContext( 'glut', 'OpenGLContext.glutinteractivecontext.GLUTInteractiveContext' )
+InteractiveContext( 'glfw', 'OpenGLContext.glfwinteractivecontext.GLFWInteractiveContext' )
+InteractiveContext( 'tk', 'OpenGLContext.tkinteractivecontext.TkInteractiveContext' )
+InteractiveContext( 'egl', 'OpenGLContext.eglcontext.EGLContext' )
+InteractiveContext( 'wgl', 'OpenGLContext.wglcontext.WGLContext' )
+VRMLContext( 'pygame', 'OpenGLContext.pygamevrmlcontext.VRMLContext' )
+VRMLContext( 'wx', 'OpenGLContext.wxvrmlcontext.VRMLContext' )
+VRMLContext( 'glut', 'OpenGLContext.glutvrmlcontext.VRMLContext' )
+VRMLContext( 'glfw', 'OpenGLContext.glfwvrmlcontext.VRMLContext' )
+VRMLContext( 'tk', 'OpenGLContext.tkvrmlcontext.VRMLContext' )
+VRMLContext( 'egl', 'OpenGLContext.eglvrmlcontext.VRMLContext' )
+VRMLContext( 'wgl', 'OpenGLContext.wglvrmlcontext.VRMLContext' )
+
+# Imported for its side effect: the package registers the Qt backend with the
+# registries above as it loads.  Absent unless the separate OpenGLContext-qt
+# distribution is installed, which is the whole of what makes qt selectable.
+try:
+    import OpenGLContext_qt      # noqa: F401
+except ImportError:
+    pass
+
+Loader( 'vrml97', 'OpenGLContext.loaders.vrml97.defaultHandler', ['.wrl','.wrz','.vrml','model/vrml','x-world/x-vrml','.wrl.gz'] )
+Loader( 'obj', 'OpenGLContext.loaders.obj.defaultHandler', ['.obj'] )
+
+# What `oglc-view` can open, keyed by file suffix and content type. One viewer
+# serves every format; the adapter is chosen from the source itself.
+Adapter( 'gltf', 'OpenGLContext.viewer.adapters.gltf.GLTFAdapter', ['.gltf','.glb','model/gltf+json','model/gltf-binary'] )
+Adapter( 'vrml97', 'OpenGLContext.viewer.adapters.vrml.VRMLAdapter', ['.wrl','.wrz','.vrml','.wrl.gz','model/vrml','x-world/x-vrml'] )
+Adapter( 'obj', 'OpenGLContext.viewer.adapters.obj.OBJAdapter', ['.obj','.obj.gz','model/obj'] )
+# A tileset is any .json, so the registry only claims the conventional name; a
+# document under another name is recognised by its content (adapters._sniff).
+Adapter( 'tiles3d', 'OpenGLContext.viewer.adapters.tiles.TilesAdapter', ['tileset.json'] )
+
+Node( 'Anchor', 'vrml.vrml97.basenodes.Anchor' )
+Node( 'Appearance', 'OpenGLContext.scenegraph.appearance.Appearance' )
+Node( 'AudioEmitter', 'OpenGLContext.scenegraph.audio.AudioEmitter' )
+Node( 'AudioSource', 'OpenGLContext.scenegraph.audio.AudioSource' )
+Node( 'AudioClip', 'vrml.vrml97.basenodes.AudioClip' )
+Node( 'Background', 'OpenGLContext.scenegraph.background.Background' )
+Node( 'Billboard', 'OpenGLContext.scenegraph.billboard.Billboard' )
+Node( 'Box', 'OpenGLContext.scenegraph.box.Box' )
+Node( 'Collision', 'OpenGLContext.scenegraph.collision.Collision' )
+Node( 'Color', 'vrml.vrml97.basenodes.Color' )
+Node( 'ColorInterpolator', 'OpenGLContext.scenegraph.interpolators.ColorInterpolator' )
+Node( 'Cone', 'OpenGLContext.scenegraph.quadrics.Cone' )
+Node( 'Coordinate', 'OpenGLContext.scenegraph.coordinate.Coordinate' )
+Node( 'CoordinateInterpolator', 'OpenGLContext.scenegraph.interpolators.CoordinateInterpolator' )
+Node( 'Cylinder', 'OpenGLContext.scenegraph.quadrics.Cylinder' )
+Node( 'CylinderSensor', 'vrml.vrml97.basenodes.CylinderSensor' )
+Node( 'DirectionalLight', 'OpenGLContext.scenegraph.light.DirectionalLight' )
+Node( 'ElevationGrid', 'vrml.vrml97.basenodes.ElevationGrid' )
+Node( 'Extrusion', 'OpenGLContext.scenegraph.extrusions.Extrusion' )
+Node( 'Fog', 'OpenGLContext.scenegraph.fog.Fog' )
+Node( 'FontStyle', 'OpenGLContext.scenegraph.text.fontstyle3d.FontStyle' )
+Node( 'Gear', 'OpenGLContext.scenegraph.gear.Gear' )
+Node( 'Group', 'OpenGLContext.scenegraph.group.Group' )
+Node( 'ImageTexture', 'OpenGLContext.scenegraph.imagetexture.ImageTexture' )
+Node( 'IndexedFaceSet', 'OpenGLContext.scenegraph.indexedfaceset.IndexedFaceSet' )
+Node( 'IndexedLineSet', 'OpenGLContext.scenegraph.indexedlineset.IndexedLineSet' )
+Node( 'Inline', 'OpenGLContext.scenegraph.inline.Inline' )
+Node( 'LOD', 'OpenGLContext.scenegraph.lod.LOD' )
+Node( 'Material', 'OpenGLContext.scenegraph.material.Material' )
+Node( 'MouseOver', 'OpenGLContext.scenegraph.mouseover.MouseOver' )
+Node( 'MovieTexture', 'vrml.vrml97.basenodes.MovieTexture' )
+Node( 'NavigationInfo', 'vrml.vrml97.basenodes.NavigationInfo' )
+Node( 'Normal', 'vrml.vrml97.basenodes.Normal' )
+Node( 'NormalInterpolator', 'vrml.vrml97.basenodes.NormalInterpolator' )
+Node( 'OrientationInterpolator', 'OpenGLContext.scenegraph.interpolators.OrientationInterpolator' )
+Node( 'PixelTexture', 'OpenGLContext.scenegraph.imagetexture.PixelTexture' )
+Node( 'PlaneSensor', 'vrml.vrml97.basenodes.PlaneSensor' )
+Node( 'PolyCone', 'OpenGLContext.scenegraph.extrusions.PolyCone' )
+Node( 'PolyCylinder', 'OpenGLContext.scenegraph.extrusions.PolyCylinder' )
+Node( 'PointLight', 'OpenGLContext.scenegraph.light.PointLight' )
+Node( 'ParticleEmitter', 'OpenGLContext.scenegraph.particles.ParticleEmitter' )
+Node( 'PointSet', 'OpenGLContext.scenegraph.pointset.PointSet' )
+Node( 'PositionInterpolator', 'OpenGLContext.scenegraph.interpolators.PositionInterpolator' )
+Node( 'ProximitySensor', 'vrml.vrml97.basenodes.ProximitySensor' )
+Node( 'ScalarInterpolator', 'OpenGLContext.scenegraph.interpolators.ScalarInterpolator' )
+Node( 'Shape', 'OpenGLContext.scenegraph.shape.Shape' )
+Node( 'Sound', 'OpenGLContext.scenegraph.audio.Sound' )
+Node( 'Sphere', 'OpenGLContext.scenegraph.quadrics.Sphere' )
+Node( 'SphereSensor', 'vrml.vrml97.basenodes.SphereSensor' )
+Node( 'SpotLight', 'OpenGLContext.scenegraph.light.SpotLight' )
+Node( 'Switch', 'OpenGLContext.scenegraph.switch.Switch' )
+Node( 'Teapot', 'OpenGLContext.scenegraph.teapot.Teapot' )
+Node( 'Text', 'OpenGLContext.scenegraph.text.text.Text' )
+Node( 'TextureCoordinate', 'vrml.vrml97.basenodes.TextureCoordinate' )
+Node( 'TextureTransform', 'OpenGLContext.scenegraph.texturetransform.TextureTransform' )
+Node( 'TimeSensor', 'OpenGLContext.scenegraph.timesensor.TimeSensor' )
+Node( 'TouchSensor', 'vrml.vrml97.basenodes.TouchSensor' )
+Node( 'Transform', 'OpenGLContext.scenegraph.transform.Transform' )
+Node( 'Viewpoint', 'OpenGLContext.scenegraph.viewpoint.Viewpoint' )
+Node( 'VisibilitySensor', 'vrml.vrml97.basenodes.VisibilitySensor' )
+Node( 'WorldInfo', 'vrml.vrml97.basenodes.WorldInfo' )
+Node( 'sceneGraph', 'OpenGLContext.scenegraph.scenegraph.SceneGraph' )
+Node( 'IndexedPolygons', 'OpenGLContext.scenegraph.indexedpolygons.IndexedPolygons' )
+Node( 'FontStyle3D', 'OpenGLContext.scenegraph.text.fontstyle3d.FontStyle3D' )
+Node( 'SimpleBackground', 'OpenGLContext.scenegraph.simplebackground.SimpleBackground' )
+Node( 'CubeBackground', 'OpenGLContext.scenegraph.cubebackground.CubeBackground' )
+Node( 'SphereBackground', 'OpenGLContext.scenegraph.spherebackground.SphereBackground' )
+Node( 'MMImageTexture', 'OpenGLContext.scenegraph.imagetexture.MMImageTexture' )
+Node( 'Contour2D', 'OpenGLContext.scenegraph.nurbs.Contour2D' )
+Node( 'NurbsCurve', 'OpenGLContext.scenegraph.nurbs.NurbsCurve' )
+Node( 'NurbsCurve2D', 'OpenGLContext.scenegraph.nurbs.NurbsCurve2D' )
+Node( 'NurbsDomainDistanceSample', 'OpenGLContext.scenegraph.nurbs.NurbsDomainDistanceSample' )
+Node( 'NurbsSurface', 'OpenGLContext.scenegraph.nurbs.NurbsSurface' )
+Node( 'NurbsToleranceSample', 'OpenGLContext.scenegraph.nurbs.NurbsToleranceSample' )
+Node( 'Polyline2D', 'OpenGLContext.scenegraph.nurbs.Polyline2D' )
+Node( 'TrimmedSurface', 'OpenGLContext.scenegraph.nurbs.TrimmedSurface' )
+
+for suffix in ('1f','2f','3f','4f','m2','m3','m4','m2x3','m3x2','m2x4','m4x2','m3x4','m4x3'):
+    Node( 'FloatUniform'+suffix,'OpenGLContext.scenegraph.shaders.FloatUniform'+suffix )
+for suffix in ('1i','2i','3i','4i'):
+    Node( 'IntUniform'+suffix,'OpenGLContext.scenegraph.shaders.IntUniform'+suffix )
+Node( 'TextureUniform','OpenGLContext.scenegraph.shaders.TextureUniform' )
+Node( 'TextureBufferUniform','OpenGLContext.scenegraph.shaders.TextureBufferUniform' )
+Node( 'GLSLShader','OpenGLContext.scenegraph.shaders.GLSLShader' )
+Node( 'GLSLObject','OpenGLContext.scenegraph.shaders.GLSLObject' )
+Node( 'GLSLImport','OpenGLContext.scenegraph.shaders.GLSLImport' )
+
+Node( 'ShaderAttribute','OpenGLContext.scenegraph.shaders.ShaderAttribute' )
+Node( 'ShaderBuffer','OpenGLContext.scenegraph.shaders.ShaderBuffer' )
+Node( 'ShaderIndexBuffer','OpenGLContext.scenegraph.shaders.ShaderIndexBuffer' )
+Node( 'ShaderSlice','OpenGLContext.scenegraph.shaders.ShaderSlice' )
+Node( 'ShaderGeometry','OpenGLContext.scenegraph.shaders.ShaderGeometry' )
+
+Node( 'Shader','OpenGLContext.scenegraph.shaders.Shader' )
+Node( 'ROUTE','vrml.route.ROUTE' )
+Node( 'IS','vrml.route.IS' )

openglcontext-3.0.0a4/OpenGLContext/__pyinstaller/__init__.py

@@ -0,0 +1,18 @@
+"""PyInstaller hooks for OpenGLContext
+
+PyInstaller finds these through the ``pyinstaller40`` entry point declared in
+``pyproject.toml``: it calls :func:`get_hook_dirs` and reads every
+``hook-*.py`` in the directory returned. An application freezing itself needs
+to do nothing to switch them on, and nothing here is imported when the engine
+is merely used.
+
+What an application does choose is in :mod:`OpenGLContext.packaging`.
+"""
+
+import os
+from typing import List
+
+
+def get_hook_dirs() -> List[str]:
+    """Directories PyInstaller should read hooks from"""
+    return [os.path.dirname(__file__)]

openglcontext-3.0.0a4/OpenGLContext/__pyinstaller/hook-OpenGLContext.py

@@ -0,0 +1,54 @@
+"""What a frozen application needs from the engine beyond its import statements
+
+Three sets of things the engine reaches by name rather than by importing:
+
+* the plug-in registries (:mod:`OpenGLContext.plugins`) -- the windowing
+  backends, the format loaders, the viewer's adapters and every scenegraph node,
+  each declared as a string and imported when a scene asks for it,
+* the generated resource and font-atlas modules, loaded by name from a
+  ``res://`` URL and from the size a piece of text is drawn at, and
+* the files the engine opens by path: the GLSL sources the render passes are
+  built from, and the environment maps a default background is lit by.
+
+Each is reported from the source the running engine uses, so a node or a shader
+added to the engine reaches a frozen application without an edit here.
+
+The whole registry is reported, PyOpenGL's own entries included: an application
+built on the engine imports both, and naming a module twice costs nothing.
+Modules for a toolkit that is not installed are reported too and end up as
+missing-import notes in the build log rather than as failures -- the backend
+reports itself unavailable at run time, which is what a bundle wants. To leave
+an unwanted toolkit out altogether, pass
+:func:`OpenGLContext.packaging.unused_backend_modules` to ``excludes``.
+"""
+
+from typing import List
+
+from PyInstaller import isolated
+from PyInstaller.utils.hooks import collect_data_files, collect_submodules
+
+
+@isolated.decorate
+def _plugin_modules() -> List[str]:
+    """Modules the plug-in registries would import, the engine's own included"""
+    import OpenGLContext  # noqa: F401 -- imported for its registrations
+    from OpenGL import plugins
+
+    modules: List[str] = plugins.registered_modules()
+    return modules
+
+
+hiddenimports = (
+    _plugin_modules()
+    # `res://` URLs and the text renderer name these modules at run time; they
+    # are generated Python holding the bytes of an icon, a shader or a font
+    # atlas, so they travel as code rather than as data files.
+    + collect_submodules('OpenGLContext.resources')
+    + collect_submodules('OpenGLContext.scenegraph.text.fonts')
+)
+
+# The shaders, the environment maps and the atlas images beside their generated
+# modules: everything in the package that is not Python. It is under half a
+# megabyte all together, so it is collected wholesale rather than by a list of
+# patterns that would go stale as passes are added.
+datas = collect_data_files('OpenGLContext')

openglcontext-3.0.0a4/OpenGLContext/__pyinstaller/hook-glfw.py

@@ -0,0 +1,17 @@
+"""The GLFW shared library, which its bindings open by path
+
+``glfw`` is the backend the engine recommends for the core profile, and the
+one an application on this stack normally freezes. Its bindings load the
+library with ``ctypes`` from a path they work out at run time -- including,
+already, the paths a frozen application has -- so all that is missing is the
+file itself, which no import statement mentions.
+
+The Linux wheels carry a build for X11 and one for Wayland and choose between
+them from the session type, so both travel: which one a machine wants is not
+known when the bundle is built. PyInstaller ships no hook for ``glfw``, so
+this one lives with the engine that asks for it.
+"""
+
+from PyInstaller.utils.hooks import collect_dynamic_libs
+
+binaries = collect_dynamic_libs('glfw')

openglcontext-3.0.0a4/OpenGLContext/atlas.py

@@ -0,0 +1,302 @@
+"""Texture atlas implementation"""
+import math
+import weakref
+import logging
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from OpenGL.GL import *
+from OpenGLContext.arrays import zeros, array, dot, ArrayType
+from OpenGLContext import texture
+from vrml.vrml97 import transformmatrix
+
+log = logging.getLogger( __name__ )
+
+class _Strip( object ):
+    """Strip within the atlas which takes particular set of images"""
+    def __init__( self, atlas: 'Atlas', height: int, yoffset: int ) -> None:
+        """Sets up the strip to receive images"""
+        self.atlas = atlas
+        self.height = height 
+        self.width = 0
+        self.yoffset = yoffset
+        self.maps: List['weakref.ref[Map]'] = []
+    def start_coord( self, x: int ) -> int:
+        """Do we have an empty space sufficient to fit image of width x?
+        
+        return starting coordinate or -1 if not enough space...
+        """
+        last = 0
+        for mapRef in self.maps:
+            referenced = mapRef()
+            if referenced is not None:
+                if referenced.offset[0]-last >= x:
+                    return last
+                else:
+                    last = referenced.offset[0]+referenced.size[0]
+        if self.atlas.max_size-last >= x:
+            return last 
+        return -1
+    def add( self, image: Any, start: Optional[int] = None ) -> 'Map':
+        """Add the given PIL image to our atlas' image"""
+        x,y = image.size
+        if start is None:
+            start = self.start_coord( x )
+        offset = (start,self.yoffset)
+        result = Map( self.atlas, offset, (x,y), image )
+        self.maps.append( weakref.ref( result, self.onRemove ) )
+        self.atlas.need_updates.append( weakref.ref(result) )
+        return result
+    def onRemove( self, *args: Any, **named: Any ) -> None:
+        """Drop the maps that have been released (a weakref-release callback)
+
+        Rebuilt rather than removed from in place: a released map is found by
+        scanning, and removing during that scan skips the entry after it.
+        """
+        self.maps[:] = [ ref for ref in self.maps if ref() is not None ]
+
+class AtlasError( Exception ):
+    """Raised when we can't/shouldn't append to this atlas"""
+
+class Atlas( object ):
+    """Collection of textures packed into a single texture
+    
+    Texture atlases allow the rendering engine to reduce the 
+    number of state-changes which occur during the rendering 
+    process.  They pack a large number of small textures into 
+    a single large texture, producing offset/scale matrices to 
+    use for modifying texture coordinates to map from the
+    original to the packed coordinates.
+    """
+    _size: Optional[Tuple[int, int, int]] = None
+    def __init__( self, components: int = 4, dataType: str = 'B',
+                  max_size: int = 4096 ) -> None:
+        self.components = components
+        self.dataType = dataType
+        self.strips: List[_Strip] = []
+        self.max_size = max_size
+        self.need_updates: List['weakref.ref[Map]'] = []
+        self.texture: Optional[texture.Texture] = None
+        log.info( 
+            'Allocating a %s-component texture atlas of size %sx%s',
+            components,
+            max_size,max_size,
+        )
+    
+    def add( self, image: Any ) -> 'Map':
+        """Insert a PIL image of values as a sub-texture
+        
+        Has to find a place within the atlas to insert the 
+        sub-texture and then return the offset/scale factors...
+        """
+        max_x = max_y = self.max_size
+        x,y = image.size 
+        strip,start = self.choose_strip( max_x, max_y, x, y )
+        return strip.add( image, start=start )
+    def choose_strip( self, max_x: int, max_y: int,
+                      x: int, y: int ) -> Tuple['_Strip', int]:
+        """Find the strip to which we should be added"""
+        candidates = [ 
+            s 
+            for s in self.strips 
+            if (
+                s.height >= y
+            ) 
+        ]
+        for strip in candidates:
+            if strip.height == y:
+                start = strip.start_coord( x )
+                if start > -1:
+                    return strip, start
+        for strip in candidates:
+            strip_mag = math.floor(math.log( strip.height, 2 ))
+            img_mag = math.floor(math.log( y, 2 ))
+            if strip_mag == img_mag:
+                start = strip.start_coord( x )
+                if start > -1:
+                    return strip, start
+        if self.strips:
+            last = self.strips[-1]
+            current_height = last.yoffset + last.height 
+        else:
+            current_height = 0
+        if current_height + y > max_y:
+            raise AtlasError( """Insufficient space to store in this atlas""" )
+        strip = _Strip( self, height=y, yoffset= current_height )
+        self.strips.append( strip )
+        start = strip.start_coord( x )
+        return strip, start
+    
+    def size( self ) -> Tuple[int, int, int]:
+        """The atlas texture's width, height and component count"""
+        if self._size is None:
+            x = y = self.max_size
+            self._size = (x,y,self.components)
+        return self._size
+    
+    def render( self ) -> texture.Texture:
+        """Render this texture to the context"""
+        if self.texture is None:
+            format = [0, GL_LUMINANCE, GL_LUMINANCE_ALPHA, GL_RGB, GL_RGBA ][self.components]
+            self.texture = texture.Texture(format=format)
+            x,y,d = self.size()
+            self.texture.store( 
+                d,
+                format,
+                x,y,
+                None 
+            )
+        # Bound rather than enabled: the sub-image uploads below need the
+        # binding, and the fixed-function texture unit does not exist in core.
+        self.texture.bind()
+        needs = self.need_updates[:]
+        del self.need_updates[:len(needs)]
+        for reference in needs:
+            need = reference()
+            if need is not None:
+                need.update( self.texture )
+        return self.texture
+    def cached( self, mode: Any ) -> texture.Texture:
+        """Get cached version of this texture
+        
+        Note: currently we do *not* properly use mode-level caching
+        for the texture object
+        """
+        return self.render()
+    def debugImageTexture( self, mode: Any ) -> Any:
+        """Create a debugging image texture for this texture atlas 
+        """
+        from OpenGLContext.scenegraph.imagetexture import ImageTexture,Image
+        from OpenGLContext.texture import NumpyAdapter
+        format = NumpyAdapter.shapeToMode( self.components )
+        instance = ImageTexture(
+            image = Image.new(format, (1,1)),
+        )
+        mode.cache.holder(instance, self.texture)
+        return instance
+
+class Map( object ):
+    """Object representing a sub-texture within a texture atlas
+    
+    A Map object is a dependent version of an OpenGLContext.texture.Texture
+    object, i.e. it tries to offer the same API, but with support for 
+    Atlas-based maps instead of stand-alone ones.
+    """
+    _matrix: Any = None
+    _coords: Any = None
+    _uploaded = False
+    def __init__( self, atlas: 'Atlas', offset: Tuple[int, int],
+                  size: Tuple[int, int], image: Any ) -> None:
+        self.atlas = atlas 
+        self.offset = offset 
+        self.size = size
+        self.image = image
+        self.components = self.atlas.components
+    def matrix( self ) -> Any:
+        """Calculate a 4x4 transform matrix for texcoords
+        
+        To manipulate texture coordinates with this matrix 
+        they need to be in homogenous coordinates, i.e. a 
+        "regular" 2d coordinate of (x,y) becomes (x,y,0.0,1.0)
+        so that it can pick up the translations.
+        
+        dot( coord, matrix ) produces the transformed 
+        coordinate for processing.
+        
+        returns 4x4 translation matrix
+        """
+        if self._matrix is None:
+            # translate by self.offset/atlas.size
+            # scale by self.size/atlas.size
+            width,height,_depth = self.atlas.size()
+            tx,ty = float(width),float(height)
+            x,y = self.offset
+            sx,sy = self.size 
+            self._matrix = transformmatrix.transformMatrix (
+                translation = (x/tx,y/ty,0),
+                scale = (sx/tx,sy/ty,1),
+            )
+        return self._matrix
+    def coords( self ) -> Any:
+        """Return our bottom-left and top-right coordinate pairs"""
+        if self._coords is None:
+            width,height,_depth = self.atlas.size()
+            tx,ty = float(width),float(height)
+            x,y = self.offset
+            sx,sy = self.size 
+            self._coords = array( ((x/tx,y/ty),((x+sx)/tx,(y+sy)/ty)), 'f')
+        return self._coords
+    
+    def replace( self, image: Any ) -> None:
+        """Replace our current image with given (PIL) image"""
+        self._uploaded = False 
+        self.image = image 
+        self.atlas.need_updates.append( weakref.ref(self) )
+    def update( self, target: Any ) -> None:
+        """Update the atlas texture with (new) data in self.image
+        
+        This just calls the texture's update with our metadata
+        in order to do the actual copy of the data-pointer.
+        """
+        target.update( 
+            self.offset, self.size, 
+            target.pilAsString( self.image),
+        )
+        self._uploaded = True
+    @property 
+    def texture( self ) -> Any:
+        """Retrieve our texture"""
+        return self.atlas.cached( None )
+    def __call__( self ) -> None:
+        """Enable/call our texture"""
+        self.atlas.render()
+        # should also load our texture-transform matrix.
+        glMatrixMode( GL_TEXTURE )
+        glLoadMatrixd( self.matrix() )
+        glMatrixMode( GL_MODELVIEW )
+
+class AtlasManager( object ):
+    """Collection of atlases within the renderer"""
+    def __init__( self, max_size: Optional[int] = 4096,
+                  max_child_size: int = 128 ) -> None:
+        self.components: Dict[int, List[Atlas]] = {}
+        self.max_size = max_size
+        self.max_child_size = max_child_size
+    FORMAT_MAPPING = {
+        'L':(1,GL_LUMINANCE), 
+        'LA':(2,GL_LUMINANCE_ALPHA),
+        'RGB':(3,GL_RGB),
+        'RGBA':(4,GL_RGBA),
+    }
+    def formatToComponents( self, format: str ) -> int:
+        """Convert PIL format to component count"""
+        return self.FORMAT_MAPPING[ format ][0]
+    def add( self, image: Any ) -> 'Map':
+        """Add the given image to the texture atlas"""
+        if isinstance( image, ArrayType ):
+            image = texture.NumpyAdapter( image )
+        x,y = image.size
+        if x > self.max_child_size:
+            raise AtlasError( """X size (%s) > %s"""%( x,self.max_child_size ) )
+        if y > self.max_child_size:
+            raise AtlasError( """Y size (%s) > %s"""%( y,self.max_child_size ) )
+        d = self.formatToComponents( image.mode )
+        atlases = self.components.setdefault( d, [])
+        for atlas in atlases:
+            try:
+                return atlas.add( image )
+            except AtlasError:
+                pass 
+        atlas = Atlas( d, max_size=self.max_size or self.calculate_max_size() )
+        atlases.append( atlas )
+        return atlas.add( image )
+    _MAX_MAX_SIZE = 4096
+    def calculate_max_size( self ) -> int:
+        """Calculate the maximum size of a texture
+        
+        Note that this might, for instance, assume a
+        single-component texture or some similarly inappropriate
+        value...
+        """
+        self.max_size = min( int(glGetIntegerv(GL_MAX_TEXTURE_SIZE)),
+                             self._MAX_MAX_SIZE )
+        return self.max_size