Skip to content

MLR123: OpenGL-only mesh added to a scene under a Cairo-target profile

qual reports MLR123 when a curated OpenGL-only mesh mobject (Object3D / Mesh from manim.renderer.shader, or the OpenGLSurface family from manim.mobject.opengl) is definitely added to a scene — a direct self.add(...), a play auto-add, or an introducer setup-add — while an active render profile targets the Cairo renderer.

  • Default severity: error
  • Minimum confidence: high
  • Implementation phase: 4
  • Fix: none (suggests an OpenGL profile, renderer = "opengl")

Verified against Manim 0.20 (clean base 4d25c031): Scene.add diverts Object3D instances into Scene.meshes only under RendererType.OPENGL (scene.py Scene.add). Under Cairo the object lands in Scene.mobjects, and because none of these classes is a Cairo Mobject, the first captured frame raises TypeError in Camera.type_or_raise (camera/camera.py — the display_funcs table matches VMobject / PMobject / AbstractImageMobject / Mobject, none of which an OpenGLMobject- or Object3D-rooted class is).

The knowledge profile curates the contract as a positive renderer-requirement fact (renderer.opengl_only_mesh on the entries). It deliberately does not set cairo: false: construction itself is renderer-independent, so the generic call-site rule MLR107 stays silent and the scene-membership rule owns the display-time failure.

The DESIGN §7.2 row also covers "renderer-unknown" profiles: a render profile that does not set a renderer resolves to Manim's default (the Cairo renderer), so it is part of the same gate. The diagnostic's applicable_profiles lists only the Cairo-target profiles (DESIGN §15.8); a run whose active profiles all target OpenGL is silent.

Silence is kept for: Cairo-capable 3D mobjects (Surface, ThreeDVMobject — ordinary VMobjects), Unknown kinds, branch-dependent (Maybe) adds, mixed mesh/Mobject inheritance (the Cairo camera's isinstance dispatch finds the Mobject arm and does not crash), and meshes that are constructed but never added. A project subclass whose resolved base chain reaches a curated mesh fires like the mesh itself.

Note: the curated classes are not star-exported from manim in 0.20, and from manim.opengl import ... re-exports are not modeled — only imports from the defining modules (manim.mobject.opengl.opengl_surface, manim.renderer.shader, ...) resolve to the curated facts.

Wrong (with a Cairo-target profile active):

from manim.mobject.opengl.opengl_surface import OpenGLSurface

class MeshScene(Scene):
    def construct(self):
        surface = OpenGLSurface(lambda u, v: (u, v, 0))
        self.add(surface)  # TypeError at the first rendered frame

Right: declare an OpenGL profile for this scene, or use the Cairo-capable Surface:

[[tool.qual.profile]]
name = "opengl"
renderer = "opengl"