ncca-ngl 0.1.6__tar.gz → 0.2.1__tar.gz

{ncca_ngl-0.1.6 → ncca_ngl-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ncca-ngl
-Version: 0.1.6
+Version: 0.2.1
 Summary: A Python version of the NGL graphics library.
 Author: Jon Macey
 Author-email: Jon Macey <jmacey@bournemouth.ac.uk>

{ncca_ngl-0.1.6 → ncca_ngl-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ncca-ngl"
-version = "0.1.6"
+version = "0.2.1"
 description = "A Python version of the NGL graphics library."
 authors = [{ name = "Jon Macey", email = "jmacey@bournemouth.ac.uk" }]
 requires-python = ">=3.13"

{ncca_ngl-0.1.6 → ncca_ngl-0.2.1}/src/ncca/ngl/__init__.py

@@ -25,7 +25,8 @@ from .obj import (
     ObjParseVertexError,
 )
 from .plane import Plane
-from .primitives import Primitives, Prims
+from .prim_data import PrimData, Prims
+from .primitives import Primitives
 from .pyside_event_handling_mixin import PySideEventHandlingMixin
 from .quaternion import Quaternion
 from .random import Random
@@ -103,6 +104,7 @@ all = [
     logger,
     Primitives,
     Prims,
+    PrimData,
     FirstPersonCamera,
     PySideEventHandlingMixin,
 ]

ncca_ngl-0.1.6/src/ncca/ngl/primitives.py → ncca_ngl-0.2.1/src/ncca/ngl/prim_data.py

@@ -1,21 +1,9 @@
-"""
-OpenGL primitive generation and drawing functions
-In this class we can generate a pipeline for drawing our data for the most part it will be
-x,y,z nx,ny,nz and u,v data in a flat numpy array.
-We need to create the data first which is stored in a map as part of the class, we can then call draw
-which will generate a pipeline for this object and draw into the current context.
-"""
-
 import enum
 from pathlib import Path
-from typing import Dict, Union
+from typing import Union
 
 import numpy as np
-import OpenGL.GL as gl
 
-from .log import logger
-from .simple_vao import VertexData
-from .vao_factory import VAOFactory, VAOType  # noqa
 from .vec3 import Vec3
 
 
@@ -66,61 +54,13 @@ def _circle_table(n: int) -> np.ndarray:
     return cs
 
 
-class _primitive:
-    """A private class to hold VAO data for a primitive."""
-
-    def __init__(self, prim_data: np.ndarray):
-        """
-        Initializes the primitive with the given data.
-
-        Args:
-            prim_data: A numpy array containing the vertex data (x,y,z,nx,ny,nz,u,v).
-        """
-        self.vao = VAOFactory.create_vao(VAOType.SIMPLE, gl.GL_TRIANGLES)
-        with self.vao:
-            data = VertexData(data=prim_data.data, size=prim_data.size)
-            self.vao.set_data(data)
-            vert_data_size = 8 * 4  # 4 is sizeof float and 8 is x,y,z,nx,ny,nz,uv
-            self.vao.set_vertex_attribute_pointer(0, 3, gl.GL_FLOAT, vert_data_size, 0)
-            self.vao.set_vertex_attribute_pointer(
-                1, 3, gl.GL_FLOAT, vert_data_size, Vec3.sizeof()
-            )
-            self.vao.set_vertex_attribute_pointer(
-                2, 2, gl.GL_FLOAT, vert_data_size, 2 * Vec3.sizeof()
-            )
-            self.vao.set_num_indices(prim_data.size // 8)
-
-
-class Primitives:
-    """A static class for creating and drawing primitives."""
-
-    # this is effectively a static class so we can use it to store data
-    # and generate pipelines for drawing
-    _primitives: Dict[str, _primitive] = {}
-    _loaded: bool = False
-
-    @classmethod
-    def load_default_primitives(cls) -> None:
-        """Loads the default primitives from the PrimData directory."""
-        logger.info("Loading default primitives...")
-        if not cls._loaded:
-            prim_folder = Path(__file__).parent / "PrimData"
-            prims = np.load(prim_folder / "Primitives.npz")
-            for p in prims.items():
-                prim_data = p[1]
-                prim = _primitive(prim_data)
-                cls._primitives[p[0]] = prim
-            cls._loaded = True
-
-    @classmethod
-    def create_line_grid(
-        cls, name: str, width: float, depth: float, steps: int
-    ) -> None:
+class PrimData:
+    @staticmethod
+    def line_grid(width: float, depth: float, steps: int) -> np.ndarray:
         """
         Creates a line grid primitive.
 
         Args:
-            name: The name of the primitive to create.
             width: The width of the grid.
             depth: The depth of the grid.
             steps: The number of steps in the grid.
@@ -153,19 +93,14 @@ class Primitives:
             v2 += dstep
 
         # Convert the list to a NumPy array
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
-
-    @classmethod
-    def create_triangle_plane(
-        cls, name: str, width: float, depth: float, w_p: int, d_p: int, v_n: Vec3
-    ) -> None:
+        return np.array(data, dtype=np.float32)
+
+    @staticmethod
+    def triangle_plane(width: float, depth: float, w_p: int, d_p: int, v_n: Vec3) -> np.ndarray:
         """
         Creates a triangle plane primitive.
 
         Args:
-            name: The name of the primitive.
             width: The width of the plane.
             depth: The depth of the plane.
             w_p: The number of width partitions.
@@ -191,17 +126,13 @@ class Primitives:
                 # vert 1
                 data.extend([w, 0.0, d + d_step, v_n.x, v_n.y, v_n.z, u, v + dv])
                 # vert 2
-                data.extend(
-                    [w + w_step, 0.0, d + d_step, v_n.x, v_n.y, v_n.z, u + du, v + dv]
-                )
+                data.extend([w + w_step, 0.0, d + d_step, v_n.x, v_n.y, v_n.z, u + du, v + dv])
                 # vert 3
                 data.extend([w, 0.0, d, v_n.x, v_n.y, v_n.z, u, v])
 
                 # tri 2
                 # vert 1
-                data.extend(
-                    [w + w_step, 0.0, d + d_step, v_n.x, v_n.y, v_n.z, u + du, v + dv]
-                )
+                data.extend([w + w_step, 0.0, d + d_step, v_n.x, v_n.y, v_n.z, u + du, v + dv])
                 # vert 2
                 data.extend([w + w_step, 0.0, d, v_n.x, v_n.y, v_n.z, u + du, v])
                 # vert 3
@@ -211,34 +142,14 @@ class Primitives:
             v += dv
             d += d_step
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def draw(cls, name: Union[str, Prims]) -> None:
-        """
-        Draws the specified primitive.
-
-        Args:
-            name: The name of the primitive to draw, either as a string or a Prims enum.
-        """
-        key = name.value if isinstance(name, Prims) else name
-        try:
-            prim = cls._primitives[key]
-            with prim.vao:
-                prim.vao.draw()
-        except KeyError:
-            logger.error(f"Failed to draw primitive {key}")
-            return
-
-    @classmethod
-    def create_sphere(cls, name: str, radius: float, precision: int) -> None:
+    @staticmethod
+    def sphere(radius: float, precision: int) -> np.ndarray:
         """
         Creates a sphere primitive.
 
         Args:
-            name: The name of the primitive.
             radius: The radius of the sphere.
             precision: The precision of the sphere (number of slices).
         """
@@ -310,19 +221,14 @@ class Primitives:
                 data.append([x1, y1, z1, nx1, ny1, nz1, u1, v1])
                 data.append([x3, y3, z3, nx3, ny3, nz3, u3, v3])
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def create_cone(
-        cls, name: str, base: float, height: float, slices: int, stacks: int
-    ) -> None:
+    @staticmethod
+    def cone(base: float, height: float, slices: int, stacks: int) -> np.ndarray:
         """
         Creates a cone primitive.
 
         Args:
-            name: The name of the primitive.
             base: The radius of the cone's base.
             height: The height of the cone.
             slices: The number of divisions around the cone.
@@ -429,14 +335,10 @@ class Primitives:
             r0 = r1
             r1 -= r_step
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def create_capsule(
-        cls, name: str, radius: float, height: float, precision: int
-    ) -> None:
+    @staticmethod
+    def capsule(radius: float, height: float, precision: int) -> np.ndarray:
         """
         Creates a capsule primitive.
         The capsule is aligned along the y-axis.
@@ -510,14 +412,10 @@ class Primitives:
                     nx, ny, nz = sb * c1, cb, sb * s1
                     data.extend([nx, ny + o, nz, nx, ny, nz, 0.0, 0.0])
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def create_cylinder(
-        cls, name: str, radius: float, height: float, slices: int, stacks: int
-    ) -> None:
+    @staticmethod
+    def cylinder(radius: float, height: float, slices: int, stacks: int) -> np.ndarray:
         """
         Creates a cylinder primitive.
         The cylinder is aligned along the y-axis.
@@ -568,17 +466,14 @@ class Primitives:
                 data.extend(p_tl)
                 data.extend(p_tr)
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def create_disk(cls, name: str, radius: float, slices: int) -> None:
+    @staticmethod
+    def disk(radius: float, slices: int) -> np.ndarray:
         """
         Creates a disk primitive.
 
         Args:
-            name: The name of the primitive.
             radius: The radius of the disk.
             slices: The number of slices to divide the disk into.
         """
@@ -618,24 +513,19 @@ class Primitives:
             data.extend(p2)
             data.extend(p1)
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
 
-    @classmethod
-    def create_torus(
-        cls,
-        name: str,
+    @staticmethod
+    def torus(
         minor_radius: float,
         major_radius: float,
         sides: int,
         rings: int,
-    ) -> None:
+    ) -> np.ndarray:
         """
         Creates a torus primitive.
 
         Args:
-            name: The name of the primitive.
             minor_radius: The minor radius of the torus.
             major_radius: The major radius of the torus.
             sides: The number of sides for each ring.
@@ -701,6 +591,13 @@ class Primitives:
                 data.extend(p3)
                 data.extend(p4)
 
-        data_array = np.array(data, dtype=np.float32)
-        prim = _primitive(data_array)
-        cls._primitives[name] = prim
+        return np.array(data, dtype=np.float32)
+
+    @staticmethod
+    def primitive(name: Union[str, enum]) -> np.ndarray:
+        prim_folder = Path(__file__).parent / "PrimData"
+        prims = np.load(prim_folder / "Primitives.npz")
+        try:
+            return prims[name]
+        except KeyError:
+            raise ValueError(f"Primitive '{name}' not found")

ncca_ngl-0.2.1/src/ncca/ngl/primitives.py

@@ -0,0 +1,219 @@
+"""
+OpenGL primitive generation and drawing functions
+In this class we can generate a pipeline for drawing our data for the most part it will be
+x,y,z nx,ny,nz and u,v data in a flat numpy array.
+We need to create the data first which is stored in a map as part of the class, we can then call draw
+which will generate a pipeline for this object and draw into the current context.
+"""
+
+from typing import Dict, Union
+
+import numpy as np
+import OpenGL.GL as gl
+
+from .log import logger
+from .prim_data import PrimData, Prims
+from .simple_vao import VertexData
+from .vao_factory import VAOFactory, VAOType  # noqa
+from .vec3 import Vec3
+
+
+class _primitive:
+    """A private class to hold VAO data for a primitive."""
+
+    def __init__(self, prim_data: np.ndarray):
+        """
+        Initializes the primitive with the given data.
+
+        Args:
+            prim_data: A numpy array containing the vertex data (x,y,z,nx,ny,nz,u,v).
+        """
+        self.vao = VAOFactory.create_vao(VAOType.SIMPLE, gl.GL_TRIANGLES)
+        with self.vao:
+            data = VertexData(data=prim_data.data, size=prim_data.size)
+            self.vao.set_data(data)
+            vert_data_size = 8 * 4  # 4 is sizeof float and 8 is x,y,z,nx,ny,nz,uv
+            self.vao.set_vertex_attribute_pointer(0, 3, gl.GL_FLOAT, vert_data_size, 0)
+            self.vao.set_vertex_attribute_pointer(1, 3, gl.GL_FLOAT, vert_data_size, Vec3.sizeof())
+            self.vao.set_vertex_attribute_pointer(2, 2, gl.GL_FLOAT, vert_data_size, 2 * Vec3.sizeof())
+            self.vao.set_num_indices(prim_data.size // 8)
+
+
+class Primitives:
+    """A static class for creating and drawing primitives."""
+
+    # this is effectively a static class so we can use it to store data
+    # and generate pipelines for drawing
+    _primitives: Dict[str, _primitive] = {}
+    _loaded: bool = False
+
+    @classmethod
+    def load_default_primitives(cls) -> None:
+        """Loads the default primitives from the PrimData directory."""
+        logger.info("Loading default primitives...")
+        if not cls._loaded:
+            for p in Prims:
+                prim_data = PrimData.primitive(p.value)
+                prim = _primitive(prim_data)
+                cls._primitives[p.value] = prim
+            cls._loaded = True
+
+    @classmethod
+    def create_line_grid(cls, name: str, width: float, depth: float, steps: int) -> None:
+        """
+        Creates a line grid primitive.
+
+        Args:
+            name: The name of the primitive to create.
+            width: The width of the grid.
+            depth: The depth of the grid.
+            steps: The number of steps in the grid.
+        """
+        # Convert the list to a NumPy array
+        data_array = PrimData.line_grid(width, depth, steps)
+        prim = _primitive(data_array)
+        cls._primitives[name] = prim
+
+    @classmethod
+    def create_triangle_plane(cls, name: str, width: float, depth: float, w_p: int, d_p: int, v_n: Vec3) -> None:
+        """
+        Creates a triangle plane primitive.
+
+        Args:
+            name: The name of the primitive.
+            width: The width of the plane.
+            depth: The depth of the plane.
+            w_p: The number of width partitions.
+            d_p: The number of depth partitions.
+            v_n: The normal vector for the plane.
+        """
+
+        data_array = PrimData.triangle_plane(width, depth, w_p, d_p, v_n)
+        prim = _primitive(data_array)
+        cls._primitives[name] = prim
+
+    @classmethod
+    def draw(cls, name: Union[str, Prims]) -> None:
+        """
+        Draws the specified primitive.
+
+        Args:
+            name: The name of the primitive to draw, either as a string or a Prims enum.
+        """
+        key = name.value if isinstance(name, Prims) else name
+        try:
+            prim = cls._primitives[key]
+            with prim.vao:
+                prim.vao.draw()
+        except KeyError:
+            logger.error(f"Failed to draw primitive {key}")
+            return
+
+    @classmethod
+    def create_sphere(cls, name: str, radius: float, precision: int) -> None:
+        """
+        Creates a sphere primitive.
+
+        Args:
+            name: The name of the primitive.
+            radius: The radius of the sphere.
+            precision: The precision of the sphere (number of slices).
+        """
+
+        data_array = PrimData.sphere(radius, precision)
+        prim = _primitive(data_array)
+        cls._primitives[name] = prim
+
+    @classmethod
+    def create_cone(cls, name: str, base: float, height: float, slices: int, stacks: int) -> None:
+        """
+        Creates a cone primitive.
+
+        Args:
+            name: The name of the primitive.
+            base: The radius of the cone's base.
+            height: The height of the cone.
+            slices: The number of divisions around the cone.
+            stacks: The number of divisions along the cone's height.
+        """
+        data_array = PrimData.cone(base, height, slices, stacks)
+        prim = _primitive(data_array)
+        cls._primitives[name] = prim
+
+    @classmethod
+    def create_capsule(cls, name: str, radius: float, height: float, precision: int) -> None:
+        """
+        Creates a capsule primitive.
+        The capsule is aligned along the y-axis.
+        It is composed of a cylinder and two hemispherical caps.
+        based on code from here https://code.google.com/p/rgine/source/browse/trunk/RGine/opengl/src/RGLShapes.cpp
+        and adapted
+
+        Args:
+            name: The name of the primitive.
+            radius: The radius of the capsule.
+            height: The height of the capsule.
+            precision: The precision of the capsule.
+        """
+
+        data_array = PrimData.capsule(radius, height, precision)
+        prim = _primitive(data_array)
+        cls._primitives[name] = prim
+
+    @classmethod
+    def create_cylinder(cls, name: str, radius: float, height: float, slices: int, stacks: int) -> None:
+        """
+        Creates a cylinder primitive.
+        The cylinder is aligned along the y-axis.
+        This method generates the cylinder walls, but not the top and bottom caps.
+
+        Args:
+            name: The name of the primitive.
+            radius: The radius of the cylinder.
+            height: The height of the cylinder.
+            slices: The number of slices.
+            stacks: The number of stacks.
+        """
+
+        data_array = PrimData.cylinder(radius, height, slices, stacks)
+        prim = _primitive(data_array)
+        cls._primitives[name] = prim
+
+    @classmethod
+    def create_disk(cls, name: str, radius: float, slices: int) -> None:
+        """
+        Creates a disk primitive.
+
+        Args:
+            name: The name of the primitive.
+            radius: The radius of the disk.
+            slices: The number of slices to divide the disk into.
+        """
+
+        data_array = PrimData.disk(radius, slices)
+        prim = _primitive(data_array)
+        cls._primitives[name] = prim
+
+    @classmethod
+    def create_torus(
+        cls,
+        name: str,
+        minor_radius: float,
+        major_radius: float,
+        sides: int,
+        rings: int,
+    ) -> None:
+        """
+        Creates a torus primitive.
+
+        Args:
+            name: The name of the primitive.
+            minor_radius: The minor radius of the torus.
+            major_radius: The major radius of the torus.
+            sides: The number of sides for each ring.
+            rings: The number of rings for the torus.
+        """
+
+        data_array = PrimData.torus(minor_radius, major_radius, sides, rings)
+        prim = _primitive(data_array)
+        cls._primitives[name] = prim

{ncca_ngl-0.1.6 → ncca_ngl-0.2.1}/src/ncca/ngl/util.py

@@ -3,6 +3,7 @@
 Most of these functions are based on functions found in other libraries such as GLM, NGL or GLU
 """
 
+import enum
 import math
 
 from .mat4 import Mat4
@@ -44,7 +45,32 @@ def look_at(eye, look, up):
     return result
 
 
-def perspective(fov, aspect, near, far):
+class PerspMode(enum.Enum):
+    OpenGL = "OpenGL"
+    WebGPU = "WebGPU"
+    Vulkan = "Vulkan"
+
+
+def perspective(
+    fov: float,
+    aspect: float,
+    near: float,
+    far: float,
+    mode: PerspMode = PerspMode.OpenGL,
+) -> Mat4:
+    """
+    Calculate a perspective matrix for various 3D graphics API's default mode is OpenGL but will covert for Vulkan and Web GPU if
+    required.
+
+    Args :
+        fov : float - Field of view angle in degrees.
+        aspect : float - Aspect ratio of the viewport.
+        near : float - Near clipping plane distance.
+        far : float - Far clipping plane distance.
+
+    Returns:
+        Mat4 - The perspective matrix.
+    """
     m = Mat4.zero()  # as per glm
     _range = math.tan(math.radians(fov / 2.0)) * near
     left = -_range * aspect
@@ -53,34 +79,36 @@ def perspective(fov, aspect, near, far):
     top = _range
     m.m[0][0] = (2.0 * near) / (right - left)
     m.m[1][1] = (2.0 * near) / (top - bottom)
-    m.m[2][2] = -(far + near) / (far - near)
-    m.m[2][3] = -1.0
-    m.m[3][2] = -(2.0 * far * near) / (far - near)
+    match mode:
+        case PerspMode.OpenGL:
+            m.m[2][2] = -(far + near) / (far - near)
+            m.m[2][3] = -1.0
+            m.m[3][2] = -(2.0 * far * near) / (far - near)
+
+        # This ensures the clip space Z range is [0, 1] as required by Vulkan and WebGPU.
+        case PerspMode.WebGPU | PerspMode.Vulkan:
+            m.m[2][2] = -far / (far - near)
+            m.m[2][3] = -1.0
+            m.m[3][2] = -(far * near) / (far - near)
     return m
 
 
-def ortho(left, right, bottom, top, near, far):
-    """Create an orthographic projection matrix."""
+def ortho(left, right, bottom, top, near, far, mode=PerspMode.OpenGL):
     m = Mat4.identity()
     m.m[0][0] = 2.0 / (right - left)
     m.m[1][1] = 2.0 / (top - bottom)
-    m.m[2][2] = -2.0 / (far - near)
+    match mode:
+        case PerspMode.OpenGL:
+            m.m[2][2] = -2.0 / (far - near)
+            m.m[3][2] = -(far + near) / (far - near)
+        case PerspMode.WebGPU | PerspMode.Vulkan:
+            m.m[2][2] = -1.0 / (far - near)
+            m.m[3][2] = -near / (far - near)
     m.m[3][0] = -(right + left) / (right - left)
     m.m[3][1] = -(top + bottom) / (top - bottom)
-    m.m[3][2] = -(far + near) / (far - near)
     return m
 
 
-# Mat4 result(1.0f);
-#   result.m_00= 2.0f / (_right - _left);
-#   result.m_11= 2.0f / (_top - _bottom);
-#   result.m_22= - 2.0f / (_zFar - _zNear);
-#   result.m_30= - (_right + _left) / (_right - _left);
-#   result.m_31= - (_top + _bottom) / (_top - _bottom);
-#   result.m_32= - (_zFar + _zNear) / (_zFar - _zNear);
-#   return result;
-
-
 def frustum(left, right, bottom, top, near, far):
     """Create a frustum projection matrix."""
     m = Mat4.zero()