{"id":17144143,"url":"https://github.com/szabolcsdombi/zengl","last_synced_at":"2025-04-07T23:09:37.175Z","repository":{"id":38417844,"uuid":"420309094","full_name":"szabolcsdombi/zengl","owner":"szabolcsdombi","description":"OpenGL Rendering Pipelines for Python","archived":false,"fork":false,"pushed_at":"2025-01-27T17:36:23.000Z","size":1622,"stargazers_count":187,"open_issues_count":1,"forks_count":11,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-31T22:21:28.430Z","etag":null,"topics":["opengl","python3","rendering"],"latest_commit_sha":null,"homepage":"https://zengl.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/szabolcsdombi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-23T04:03:02.000Z","updated_at":"2025-02-27T10:06:35.000Z","dependencies_parsed_at":"2024-02-02T21:26:59.000Z","dependency_job_id":"f3eeea0e-e673-4058-a53a-e3bc8188bcf2","html_url":"https://github.com/szabolcsdombi/zengl","commit_stats":{"total_commits":1053,"total_committers":11,"mean_commits":95.72727272727273,"dds":0.2602089268755935,"last_synced_commit":"d39e012a6b50fbdb5ab9fe5ac894ccdaf486b56f"},"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szabolcsdombi%2Fzengl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szabolcsdombi%2Fzengl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szabolcsdombi%2Fzengl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szabolcsdombi%2Fzengl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/szabolcsdombi","download_url":"https://codeload.github.com/szabolcsdombi/zengl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247744335,"owners_count":20988783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["opengl","python3","rendering"],"created_at":"2024-10-14T20:43:12.012Z","updated_at":"2025-04-07T23:09:37.151Z","avatar_url":"https://github.com/szabolcsdombi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![ZenGL](https://repository-images.githubusercontent.com/420309094/f7c17e13-4d5b-4a38-8b52-ab2dfdacd5a0)](#zengl)\n\n```\npip install zengl\n```\n\n- [Documentation](https://zengl.readthedocs.io/)\n- [zengl on Github](https://github.com/szabolcsdombi/zengl/)\n- [zengl on PyPI](https://pypi.org/project/zengl/)\n- [Discord](https://discord.gg/nM34Uv7x)\n\n# ZenGL\n\nZenGL is a low level graphics library. Works on all platforms including the browser.\n\n## Description\n\n- **Context** is the root object to access OpenGL\n- **Image** is an OpenGL Texture or Renderbuffer\n- **Buffer** is an OpenGL Buffer\n- **Pipeline** is an OpenGL Program + Vertex Array + Framebuffer + _complete state for rendering_\n\n```py\nctx = zengl.context()\ntexture = ctx.image(size, 'rgba8unorm', pixels)\nrenderbuffer = ctx.image(size, 'rgba8unorm', samples=4)\nvertex_buffer = ctx.buffer(vertices)\npipeline = ctx.pipeline(...)\n```\n\nThe complete OpenGL state is encapsulated by the **Pipeline**.\n\nRendering with multiple pipelines guarantees proper state with minimal changes and api calls.\n\n```py\nbackground.render()\nscene.render()\nparticles.render()\nbloom.render()\n```\n\n**Pipelines** render to framebuffers, **Images** can be blit to the screen.\n\n```py\n# init time\npipeline = ctx.pipeline(\n    framebuffer=[image, depth],\n)\n```\n\n```py\n# per frame\nimage.clear()\ndepth.clear()\npipeline.render()\nimage.blit()\n```\n\nPrograms are simple, easy, and cached. Unique shader sources are only compiled once.\n\n```py\npipeline = ctx.pipeline(\n    vertex_shader='''\n        #version 330 core\n\n        void main() {\n            gl_Position = ...\n        }\n    ''',\n    fragment_shader='''\n        #version 330 core\n\n        out vec4 frag_color;\n\n        void main() {\n            frag_color = ...\n        }\n    ''',\n)\n```\n\nVertex Arrays are simple.\n\n```py\n# simple\npipeline = ctx.pipeline(\n    vertex_buffers=zengl.bind(vertex_buffer, '3f 3f 2f', 0, 1, 2),\n    vertex_count=vertex_buffer.size // zengl.calcsize('3f 3f 2f'),\n)\n```\n\n```py\n# indexed\npipeline = ctx.pipeline(\n    vertex_buffers=zengl.bind(vertex_buffer, '3f 3f 2f', 0, 1, 2),\n    index_buffer=index_buffer,\n    vertex_count=index_buffer.size // 4,\n)\n```\n\n```py\n# instanced\npipeline = ctx.pipeline(\n    vertex_buffers=[\n        *zengl.bind(vertex_buffer, '3f 3f 2f', 0, 1, 2),\n        *zengl.bind(instance_buffer, '3f 4f /i', 3, 4),\n    ],\n    vertex_count=vertex_buffer.size // zengl.calcsize('3f 3f 2f'),\n    instance_count=1000,\n)\n```\n\nUniform Buffer, Texture, and Sampler binding is easy.\n\n```py\n# uniform buffers\npipeline = ctx.pipeline(\n    layout=[\n        {\n            'name': 'Common',\n            'binding': 0,\n        },\n    ],\n    resources=[\n        {\n            'type': 'uniform_buffer',\n            'binding': 0,\n            'buffer': uniform_buffer,\n        },\n    ],\n)\n```\n\n```py\n# textures\npipeline = ctx.pipeline(\n    layout=[\n        {\n            'name': 'Texture',\n            'binding': 0,\n        },\n    ],\n    resources=[\n        {\n            'type': 'sampler',\n            'binding': 0,\n            'image': texture,\n            'wrap_x': 'clamp_to_edge',\n            'wrap_y': 'clamp_to_edge',\n            'min_filter': 'nearest',\n            'mag_filter': 'nearest',\n        },\n    ],\n)\n```\n\nPostprocessing and Compute can be implemented as rendering a fullscreen quad.\n\n```py\npipeline = ctx.pipeline(\n    vertex_shader='''\n        #version 330 core\n\n        vec2 vertices[3] = vec2[](\n            vec2(-1.0, -1.0),\n            vec2(3.0, -1.0),\n            vec2(-1.0, 3.0)\n        );\n\n        void main() {\n            gl_Position = vec4(vertices[gl_VertexID], 0.0, 1.0);\n        }\n    ''',\n    fragment_shader='''\n        #version 330 core\n\n        out vec4 frag_color;\n\n        void main() {\n            frag_color = ...\n        }\n    ''',\n    topology='triangles',\n    vertex_count=3,\n)\n```\n\n```py\nparticle_system = ctx.pipeline(\n    vertex_shader=...,\n    fragment_shader='''\n        #version 330 core\n\n        uniform sampler2D Position;\n        uniform sampler2D Velocity;\n        uniform vec3 Acceleration;\n\n        layout (location = 0) out vec3 OutputPosition;\n        layout (location = 1) out vec3 OutputVelocity;\n\n        void main() {\n            ivec2 at = ivec2(gl_FragCoord.xy);\n            vec3 position = texelFetch(Position, at, 0).xyz;\n            vec3 velocity = texelFetch(Velocity, at, 0).xyz;\n            OutputPosition = position + velocity;\n            OutputVelocity = velocity + Acceleration;\n        }\n    ''',\n)\n```\n\nZenGL intentionally does not support:\n\n- Transform Feedback\n- Geometry Shaders\n- Tesselation\n- Compute Shaders\n- 3D Textures\n- Storage Buffers\n\nMost of the above can be implemented in a more hardware friendly way using the existing ZenGL API.\nInteroperability with other modules is also possible. Using such may reduce the application's portablity.\nIt is even possible to use direct OpenGL calls together with ZenGL, however this is likely not necessary.\n\nIt is common to render directly to the screen with OpenGL.\nWith ZenGL, the right way is to render to a framebuffer and blit the final image to the screen.\nThis allows fine-grained control of the framebuffer format, guaranteed multisampling settings, correct depth/stencil precison.\nIt is also possible to render directly to the screen, however this feature is designed to be used for the postprocessing step.\n\nThis design allows ZenGL to support:\n\n- Rendering without a window\n- Rendering to multiple windows\n- Rendering to HDR monitors\n- Refreshing the screen without re-rendering the scene\n- Apply post-processing without changing how the scene is rendered\n- Making reusable shaders and components\n- Taking screenshots or exporting a video\n\nThe [default framebuffer](https://www.khronos.org/opengl/wiki/Default_Framebuffer) in OpenGL is highly dependent on how the Window is created.\nIt is often necessary to configure the Window to provide the proper depth precision, stencil buffer, multisampling and double buffering.\nOften the \"best pixel format\" lacks all of these features on purpose. ZenGL aims to allow choosing these pixel formats and ensures the user specifies the rendering requirements.\nIt is even possible to render low-resolution images and upscale them for high-resolution monitors.\nTearing can be easily prevented by decoupling the scene rendering from the screen updates.\n\nZenGL was designed for Prototyping\n\nIt is tempting to start a project with Vulkan, however even getting a simple scene rendered requires tremendous work and advanced tooling to compile shaders ahead of time. ZenGL provides self-contained Pipelines which can be easily ported to Vulkan.\nZenGL code is verbose and easy to read.\n\nZenGL support multiple design patters\n\nMany libraries enfore certain design patterns.\nZenGL avoids this by providing cached pipeline creation, pipeline templating and lean resourece and framebuffer definition.\nIt is supported to create pipelines on the fly or template them for certain use-cases.\n\n\u003e TODO: examples for such patters\n\nZenGL emerged from an experimental version of [ModernGL](https://github.com/moderngl/moderngl).\nTo keep ModernGL backward compatible, ZenGL was re-designed from the ground-up to support a strict subset of OpenGL.\nOn the other hand, ModernGL supports a wide variety of OpenGL versions and extensions.\n\n## Disambiguation\n\n- ZenGL is a drop-in replacement for pure OpenGL code\n- Using ZenGL requires some OpenGL knowledge\n- ZenGL Images are OpenGL [Texture Objects](https://www.khronos.org/opengl/wiki/Texture) or [Renderbuffer Objects](https://www.khronos.org/opengl/wiki/Renderbuffer_Object)\n- ZenGL Buffers are OpenGL [Buffer Objects](https://www.khronos.org/opengl/wiki/Buffer_Object)\n- ZenGL Pipelines contain an OpenGL [Vertex Array Object](https://www.khronos.org/opengl/wiki/Vertex_Specification#Vertex_Array_Object), a [Program Object](https://www.khronos.org/opengl/wiki/GLSL_Object#Program_objects), and a [Framebuffer Object](https://www.khronos.org/opengl/wiki/Framebuffer)\n- ZenGL Pipelines may also contain OpenGL [Sampler Objects](https://www.khronos.org/opengl/wiki/Sampler_Object)\n- Creating ZenGL Pipelines does not necessarily compile the shader from source\n- The ZenGL Shader Cache exists independently from the Pipeline objects\n- A Framebuffer is always represented by a Python list of ZenGL Images\n- There is no `Pipeline.clear()` method, individual images must be cleared independently\n- GLSL Uniform Blocks and sampler2D objects are bound in the Pipeline layout\n- Textures and Uniform Buffers are bound in the Pipeline resources\n\n## [Examples](./examples/)\n\n[![bezier_curves](https://user-images.githubusercontent.com/11232402/235417415-f04815bf-3380-45fa-9804-f9f36016f46c.png)](#native-examples)\n[![deferred_rendering](https://user-images.githubusercontent.com/11232402/235417431-4dd870ea-1804-4b00-bfd2-49e3ca72e2b1.png)](#native-examples)\n[![envmap](https://user-images.githubusercontent.com/11232402/235417438-0cc02333-dd92-47e4-b874-ff1b6dca2086.png)](#native-examples)\n[![fractal](https://user-images.githubusercontent.com/11232402/235417445-73efbe67-21ea-4aae-a1ff-6aa4002bf58d.png)](#native-examples)\n[![grass](https://user-images.githubusercontent.com/11232402/235417450-3ff0b82d-e097-40cd-947a-58803e464cd3.png)](#native-examples)\n[![normal_mapping](https://user-images.githubusercontent.com/11232402/235417454-1d8e4bfb-02ad-42a2-87ba-ce39f47de14d.png)](#native-examples)\n[![rigged_objects](https://user-images.githubusercontent.com/11232402/235417459-79483b7f-6581-4788-a662-ef81087334b6.png)](#native-examples)\n[![wireframe](https://user-images.githubusercontent.com/11232402/235417465-f3f54a9b-624b-4fa1-88b6-f725ac468e78.png)](#native-examples)\n\n### Simple Pipeline Definition\n\n```py\npipeline = ctx.pipeline(\n    # program definition\n    vertex_shader='...',\n    fragment_shader='...',\n    layout=[\n        {\n            'name': 'Uniforms',\n            'binding': 0,\n        },\n        {\n            'name': 'Texture',\n            'binding': 0,\n        },\n    ],\n\n    # descriptor sets\n    resources=[\n        {\n            'type': 'uniform_buffer',\n            'binding': 0,\n            'buffer': uniform_buffer,\n        },\n        {\n            'type': 'sampler',\n            'binding': 0,\n            'image': texture,\n        },\n    ],\n\n    # uniforms\n    uniforms={\n        'color': [0.0, 0.5, 1.0],\n        'iterations': 10,\n    },\n\n    # program definition global state\n    depth={\n        'func': 'less',\n        'write': False,\n    },\n    stencil={\n        'front': {\n            'fail_op': 'replace',\n            'pass_op': 'replace',\n            'depth_fail_op': 'replace',\n            'compare_op': 'always',\n            'compare_mask': 1,\n            'write_mask': 1,\n            'reference': 1,\n        },\n        'back': ...,\n        # or\n        'both': ...,\n    },\n    blend={\n        'enable': True,\n        'src_color': 'src_alpha',\n        'dst_color': 'one_minus_src_alpha',\n    },\n    cull_face='back',\n    topology='triangles',\n\n    # framebuffer\n    framebuffer=[color1, color2, ..., depth],\n    viewport=(x, y, width, height),\n\n    # vertex array\n    vertex_buffers=[\n        *zengl.bind(vertex_buffer, '3f 3f', 0, 1), # bound vertex attributes\n        *zengl.bind(None, '2f', 2), # unused vertex attribute\n    ],\n    index_buffer=index_buffer, # or None\n    short_index=False, # 2 or 4 byte intex\n    vertex_count=...,\n    instance_count=1,\n    first_vertex=0,\n\n    # override includes\n    includes={\n        'common': '...',\n    },\n)\n\n# some members are actually mutable and calls no OpenGL functions\npipeline.viewport = ...\npipeline.vertex_count = ...\npipeline.uniforms['iterations'][:] = struct.pack('i', 50) # writable memoryview\n\n# rendering\npipeline.render() # no parameters for hot code\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszabolcsdombi%2Fzengl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fszabolcsdombi%2Fzengl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszabolcsdombi%2Fzengl/lists"}