OpenGLContext 2.2.0a3__tar.gz → 3.0.0a1__tar.gz

openglcontext-3.0.0a1/MANIFEST.in

@@ -0,0 +1,44 @@
+include MANIFEST.in
+include license.txt
+include README.md
+
+recursive-include tests *.jpg *.bmp *.png *.wrl *.jpeg
+exclude tests/axis.wrl
+exclude tests/flower.wrl
+exclude tests/test.jpg
+exclude tests/wrls/logo_installer.bmp
+exclude tests/wrls/pyopenglchapel.wrl
+include tests/*.py
+include tests/*.vert
+include tests/resources/*.txt
+
+recursive-include docs *.css *.png *.gif
+include docs/*.html
+include docs/images/*
+include docs/style/*
+include OpenGLContext/resources/*.txt
+include OpenGLContext/loaders/*
+exclude docs/tutorials/*.xhtml
+exclude docs/tutorials/*.png
+exclude tests/test-results/*.png
+exclude tests/test-results/*.html
+
+# AI-workflow / internal planning docs are not user-facing; keep them out of the
+# published sdist.
+exclude CLAUDE.md
+prune plans
+
+global-exclude *CVS*
+global-exclude *Cvs*
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude *.pdb
+global-exclude *.db
+global-exclude *.max
+global-exclude *.gz
+global-exclude *.bat
+global-exclude *.profile
+global-exclude *.directory
+global-exclude *.cvsignore
+global-exclude *.ttf
+

openglcontext-3.0.0a1/OpenGLContext/__init__.py

@@ -0,0 +1,151 @@
+'''Rendering contexts for various GUI libraries, scene graph
+geometry objects, and PyOpenGL testing code
+
+The OpenGLContext project provides a simplified environment
+for writing OpenGL code with PyOpenGL.  This simplified
+environment abstracts the GUI library interfaces for a
+large number of GUI libraries to allow the easy creation of
+cross platform and cross-GUI-OpenGL programs.
+
+The project also provides simplified geometry display
+primitives to allow new developers to concentrate on the
+particular task in which they are interested rather than
+forcing them to re-implement basic geometry display
+mechanisms.
+
+Taking advantage of this simplified environment, we have
+provided a number of testing modules.  These testing
+modules should operate under any of the fully functional
+GUI contexts (note that there are unfinished contexts).
+'''
+
+__version__ = "3.0.0a1"
+__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' )
+InteractiveContext( 'pygame', 'OpenGLContext.pygameinteractivecontext.PygameInteractiveContext' )
+InteractiveContext( 'wx', 'OpenGLContext.wxinteractivecontext.wxInteractiveContext' )
+InteractiveContext( 'glut', 'OpenGLContext.glutinteractivecontext.GLUTInteractiveContext' )
+InteractiveContext( 'glfw', 'OpenGLContext.glfwinteractivecontext.GLFWInteractiveContext' )
+VRMLContext( 'pygame', 'OpenGLContext.pygamevrmlcontext.VRMLContext' )
+VRMLContext( 'wx', 'OpenGLContext.wxvrmlcontext.VRMLContext' )
+VRMLContext( 'glut', 'OpenGLContext.glutvrmlcontext.VRMLContext' )
+VRMLContext( 'glfw', 'OpenGLContext.glfwvrmlcontext.VRMLContext' )
+
+try:
+    import OpenGLContext_qt
+except ImportError as err:
+    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', 'vrml.vrml97.basenodes.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( '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.0a1/OpenGLContext/atlas.py

@@ -0,0 +1,300 @@
+"""Texture atlas implementation"""
+import math, weakref, logging
+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, height, yoffset ):
+        """Sets up the strip to receive images"""
+        self.atlas = atlas
+        self.height = height 
+        self.width = 0
+        self.yoffset = yoffset
+        self.maps = []
+    def start_coord( self, x ):
+        """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 map in self.maps:
+            referenced = map()
+            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, start=None ):
+        """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)
+        map = Map( self.atlas, offset, (x,y), image )
+        self.maps.append( weakref.ref( map, self._remover( offset )) )
+        self.atlas.need_updates.append( weakref.ref(map) )
+        return map
+    def _remover( self, offset ):
+        def remover( *args ):
+            self.onRemove( )
+        return remover 
+    def onRemove( self, *args, **named ):
+        """Remove map by offset (normally a weakref-release callback)"""
+        update = False
+        for mapRef in self.maps:
+            referenced = mapRef()
+            if referenced is None:
+                try:
+                    self.maps.remove( mapRef )
+                except ValueError as err:
+                    pass 
+                update = True 
+
+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.
+    """
+    _local = None
+    _size = None
+    def __init__( self, components=4, dataType='B', max_size=4096 ):
+        self.components = components
+        self.dataType = dataType
+        self.strips = []
+        self.max_size = max_size
+        self.need_updates = []
+        self.texture = None
+        log.info( 
+            'Allocating a %s-component texture atlas of size %sx%s',
+            components,
+            max_size,max_size,
+        )
+    
+    def add( self, image ):
+        """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,max_y, x,y ):
+        """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 ):
+        if self._size is None:
+            x = y = self.max_size
+            self._size = (x,y,self.components)
+        return self._size
+    
+    def render( self ):
+        """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 
+            )
+        self.texture()
+        needs = self.need_updates[:]
+        del self.need_updates[:len(needs)]
+        for need in needs:
+            need = need()
+            if need is not None:
+                need.update( self.texture )
+        return self.texture
+    def cached( self, mode ):
+        """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 ):
+        """Create a debugging image texture for this texture atlas 
+        """
+        from OpenGLContext.scenegraph.imagetexture import ImageTexture,Image
+        from OpenGLContext.texture import NumpyAdapter
+        from vrml import protofunctions
+        format = NumpyAdapter.shapeToMode( self.components )
+        instance = ImageTexture(
+            image = Image.new(format, (1,1), '#ffff00'),
+        )
+        holder = 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 = None
+    _coords = None
+    _uploaded = False
+    def __init__( self, atlas, offset, size, image ):
+        self.atlas = atlas 
+        self.offset = offset 
+        self.size = size
+        self.image = image
+        self.components = self.atlas.components
+    def matrix( self ):
+        """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
+            tx,ty,d = self.atlas.size()
+            tx,ty = float(tx),float(ty)
+            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 ):
+        """Return our bottom-left and top-right coordinate pairs"""
+        if self._coords is None:
+            tx,ty,d = self.atlas.size()
+            tx,ty = float(tx),float(ty)
+            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 ):
+        """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, texture ):
+        """Update texture with (new) data in self.image
+        
+        This just calls texture.update with our metadata
+        in order to do the actual copy of the data-pointer.
+        """
+        texture.update( 
+            self.offset, self.size, 
+            texture.pilAsString( self.image),
+        )
+        self._uploaded = True
+    @property 
+    def texture( self ):
+        """Retrieve our texture"""
+        return self.atlas.cached( None )
+    def __call__( self ):
+        """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=4096, max_child_size=128 ):
+        self.components = {}
+        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 ):
+        """Convert PIL format to component count"""
+        return self.FORMAT_MAPPING[ format ][0]
+    def add( self, image ):
+        """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 as err:
+                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 ):
+        """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( (glGetIntegerv(GL_MAX_TEXTURE_SIZE), self._MAX_MAX_SIZE) )
+        return self.max_size

openglcontext-3.0.0a1/OpenGLContext/audio/__init__.py

@@ -0,0 +1,32 @@
+"""Giving an OpenGLContext context an ear.
+
+The sound itself is :mod:`omi_audio`: the ``KHR_audio_emitter`` data model,
+every gain curve, the clip cache, the numpy mixer, the device seam and the
+engine that ties them together.  None of that knows what a scenegraph is, and
+none of it belongs here.
+
+What is here is the two seams between that engine and a context:
+
+=========================  ====================================================
+:mod:`~.scene`             One engine per context, opened on the first frame
+                           that has something audible in it, and driven once a
+                           frame from the camera and the render pass's
+                           ``Auditory`` node paths.
+:mod:`~.settings`          :class:`~.settings.AudioSettings`, the player's own
+                           switch, volume and voice budget, declared as a node
+                           on the :class:`~OpenGLContext.contextdefinition.ContextDefinition`
+                           so it validates, serialises and generates its own
+                           settings page like every other field group.
+=========================  ====================================================
+
+The nodes that put a sound *in* a scene are
+:mod:`OpenGLContext.scenegraph.audio` -- ``AudioEmitter``, ``AudioSource`` and
+VRML97's ``Sound`` -- and the glTF loader reads ``KHR_audio_emitter`` blocks
+into them through :mod:`OpenGLContext.loaders.gltf.scene`.
+
+Sound is **optional and never fatal**.  ``miniaudio`` may be absent and a device
+may fail to open; both end in one warning and a silent run, so a machine with no
+sound card is simply a machine with no sound.
+
+See ``docs/audio.html`` for the data-flow diagrams and a worked example.
+"""

openglcontext-3.0.0a1/OpenGLContext/audio/scene.py

@@ -0,0 +1,130 @@
+"""Giving a context an ear, and driving the scene's sounds once a frame.
+
+This is the whole of the seam between the render loop and :mod:`omi_audio`.  The
+render pass already collects every :class:`~vrml.vrml97.nodetypes.Auditory` node
+path and already knows where the camera is; :func:`update` turns those two facts
+into sound.
+
+**Silence costs nothing.**  A context gets no engine, and therefore opens no
+device and starts no audio thread, until a frame is drawn with something audible
+in it.  A scene with no sounds -- which is most test scenes and every existing
+OpenGLContext demo -- is untouched by any of this.
+
+The engine hangs off the context rather than being a global, because two windows
+are two listeners, and it is held weakly so closing a window does not leak a
+device.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import weakref
+from typing import Any, Dict, Optional, Sequence
+
+from omi_audio.device import open_device
+from omi_audio.engine import AudioEngine
+
+from OpenGLContext.audio.settings import settings_for
+from OpenGLContext.scenegraph.audio import stop_scene_audio, update_scene_audio
+
+log = logging.getLogger(__name__)
+
+#: Engines by context.  Weak, so a closed window's device goes with it; keyed by
+#: the context itself rather than stored on it so a context class needs to know
+#: nothing about audio to have some.
+_engines: "weakref.WeakKeyDictionary[Any, AudioEngine]" = weakref.WeakKeyDictionary()
+
+
+def existing_engine(context: Any) -> Optional[AudioEngine]:
+    """The engine ``context`` already has, or None.  Never makes one."""
+    return _engines.get(context)
+
+
+def enabled(context: Any) -> bool:
+    """Whether this context's settings allow sound at all."""
+    return bool(settings_for(context).enabled)
+
+
+def engine_for(context: Any) -> Optional[AudioEngine]:
+    """The engine for ``context``, opened on first ask.
+
+    Returns None where the context's definition has audio switched off, which is
+    the one case a caller has to handle -- and handling it is doing nothing.
+    """
+    if not enabled(context):
+        return None
+    engine = _engines.get(context)
+    if engine is None:
+        settings = settings_for(context)
+        engine = AudioEngine(device=open_device(), voices=int(settings.voices))
+        engine.volume = settings.volume
+        _engines[context] = engine
+    return engine
+
+
+def close(context: Any) -> None:
+    """Release ``context``'s engine and its device.  Safe if it had none."""
+    engine = _engines.pop(context, None)
+    if engine is not None:
+        engine.close()
+
+
+def update(context: Any, paths: Sequence[Any], now: Optional[float] = None) -> int:
+    """Keep ``context``'s sounds in step with its camera, for one frame.
+
+    ``paths`` are the render pass's collected ``Auditory`` node paths.  An empty
+    sequence returns immediately **without opening a device**, which is what
+    makes sound free for a scene that has none.
+
+    ``now`` is absolute seconds, because VRML97's ``startTime`` and ``stopTime``
+    are absolute; it is taken from the wall clock when not given.
+
+    Returns how many nodes were driven, for a debug overlay.
+    """
+    if not paths or not enabled(context):
+        return 0
+    engine = engine_for(context)
+    if engine is None:
+        return 0
+    # The *player's* volume, read every frame: the settings screen writes the
+    # field, and a volume slider that only takes effect on the next launch is a
+    # volume slider nobody uses.  The application's own `master_gain` is left
+    # alone -- writing over it here would make an application's mix level last
+    # exactly one frame.
+    engine.volume = settings_for(context).volume
+    platform = _view_platform(context)
+    if platform is not None:
+        engine.listen(platform)
+    return update_scene_audio(engine, paths,
+                              time.time() if now is None else now)
+
+
+def stop(context: Any, paths: Sequence[Any]) -> None:
+    """Silence every sound in a scene that is going away."""
+    stop_scene_audio(paths)
+    engine = _engines.get(context)
+    if engine is not None:
+        engine.stop_all()
+
+
+def _view_platform(context: Any) -> Any:
+    """The context's camera, however it exposes one."""
+    getter = getattr(context, 'getViewPlatform', None)
+    if getter is not None:
+        return getter()
+    return getattr(context, 'platform', None)
+
+
+def describe(context: Any) -> Dict[str, Any]:
+    """What this context's audio is doing, for a debug overlay."""
+    engine = _engines.get(context)
+    if engine is None:
+        return {'audio': 'off' if not enabled(context) else 'idle'}
+    return {
+        'audio': 'silent' if engine.silent else '%d Hz' % (engine.sample_rate,),
+        'voices': engine.active_voices,
+        'volume': round(engine.volume, 2),
+        'mix': round(engine.master_gain, 2),
+        'muffle': round(engine.muffle, 2),
+    }