neraulgraphics 0.4.0__tar.gz

neraulgraphics-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,141 @@
+name: release
+
+# Pushing a tag vX.Y.Z builds the source archive and wheels, then publishes them as the
+# GitHub Release for that tag, and to PyPI if that has been switched on (see RELEASING.md).
+# Running it by hand (Actions > release > Run workflow) builds the same files without
+# publishing anything, as a dry run.
+#
+# Wheels: Linux x86_64 carries the CUDA backend (and uses the CPU on a machine with no GPU);
+# macOS, Windows and Linux aarch64 are CPU-only.
+#
+# See RELEASING.md for the steps around it.
+
+on:
+  push:
+    tags: ["v*.*.*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # Refuses to release unless the tag, CMakeLists.txt and CHANGELOG.md agree.
+  check-version:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - id: version
+        run: |
+          version=$(sed -nE 's/^project\(neraulgraphics VERSION ([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' CMakeLists.txt)
+          if [ -z "$version" ]; then
+            echo "::error::no version found in CMakeLists.txt"
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+          if [ "$GITHUB_REF_TYPE" = "tag" ] && [ "$GITHUB_REF_NAME" != "v$version" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match version $version in CMakeLists.txt"
+            exit 1
+          fi
+          if ! grep -q "^## \[$version\]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no '## [$version]' section"
+            exit 1
+          fi
+          echo "version $version"
+
+  sdist:
+    needs: check-version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - run: pipx run build --sdist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  # Settings live in [tool.cibuildwheel] in pyproject.toml, shared with local builds.
+  # Linux x86_64, with the CUDA backend.
+  wheels:
+    needs: check-version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pypa/cibuildwheel@v4.3.5
+        with:
+          output-dir: wheelhouse
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-linux-cuda
+          path: wheelhouse/*.whl
+
+  # Everything without CUDA: the build finds no CUDA compiler and builds the CPU backend only.
+  wheels-cpu:
+    needs: check-version
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { name: macos-arm64, os: macos-latest }
+          - { name: windows-amd64, os: windows-latest }
+          - { name: linux-aarch64, os: ubuntu-24.04-arm, archs: aarch64 }
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pypa/cibuildwheel@v4.3.5
+        env:
+          CIBW_ARCHS_LINUX: ${{ matrix.archs }}
+        with:
+          output-dir: wheelhouse
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.name }}
+          path: wheelhouse/*.whl
+
+  publish:
+    if: github.ref_type == 'tag'
+    needs: [check-version, sdist, wheels, wheels-cpu]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.check-version.outputs.version }}
+        run: |
+          # The release notes are this version's section of CHANGELOG.md.
+          awk -v v="$VERSION" '
+            $0 ~ "^## \\[" v "\\]" { found = 1; next }
+            found && /^## \[/ { exit }
+            found { print }
+          ' CHANGELOG.md > notes.md
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "neraulgraphics $VERSION" \
+            --notes-file notes.md
+
+  # PyPI, by trusted publishing: no token is stored here. It does nothing until the repository
+  # variable PUBLISH_TO_PYPI is set to true, after the one-time setup on pypi.org in RELEASING.md.
+  pypi:
+    if: github.ref_type == 'tag' && vars.PUBLISH_TO_PYPI == 'true'
+    needs: [check-version, sdist, wheels, wheels-cpu, publish]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

neraulgraphics-0.4.0/.gitignore

@@ -0,0 +1,34 @@
+# Allowlist: ignore everything in this subproject by default...
+*
+
+# ...but keep descending into directories, so the rules below can reach inside
+# them. Without this, git never looks inside src/ and the !/src/** below can
+# never match.
+!*/
+
+# ...and un-ignore only what defines the project.
+!/.gitignore
+!/LICENSE
+!/CMakeLists.txt
+!/Makefile
+!/src/**
+!/include/**
+!/cmake/**
+!/python/**
+!/tests/**
+!/examples/**
+!/.github/**
+!/pyproject.toml
+!/README.md
+!/CHANGELOG.md
+!/RELEASING.md
+!/docs/**
+
+# Build trees: re-ignored as whole directories so git doesn't walk them at all.
+/build/
+/cmake-build-*/
+/dist/
+/wheelhouse/
+/.idea/
+__pycache__/
+*.egg-info/

neraulgraphics-0.4.0/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+Each release has a section here. The release workflow refuses to publish a version
+without one, and uses the section as the release notes.
+
+Versions follow [semantic versioning](https://semver.org). Before 1.0, a minor
+version (0.x.0) may change the API.
+
+## [0.4.0]
+
+Newton and MuJoCo adapters, model loading, textures, and a CPU backend so it runs on any machine.
+
+### Added
+- A CPU backend. The renderer runs on every core of the machine when there is no NVIDIA GPU,
+  drawing the same picture as the GPU (the two run the same rendering code). `Renderer` takes
+  `device="auto" | "cuda" | "cpu"` (C++: `Device`), `Renderer.device` says which was chosen, and
+  `cuda_available()` says whether a GPU is usable. `NERAULGRAPHICS_DEVICE=cpu` overrides `auto`;
+  `NERAULGRAPHICS_THREADS` sets the CPU thread count. A machine with no GPU used to raise
+  `CudaError`; it now falls back to the CPU.
+- CUDA is optional at build time (`-DNERAULGRAPHICS_CUDA=AUTO|ON|OFF`; AUTO uses it if a CUDA
+  compiler is found). Without it the library needs only a C++17 compiler and depends on no CUDA
+  library or driver.
+- Wheels for macOS (Apple Silicon), Windows and Linux aarch64, CPU-only, alongside the Linux x86_64
+  CUDA wheels. The release workflow can publish to PyPI by trusted publishing, once enabled.
+- `docs/portability.md`: what runs where, and how other GPUs could be supported.
+- `neraulgraphics.newton.NewtonRenderer` and `neraulgraphics.mujoco.MuJoCoRenderer`:
+  render a Newton or MuJoCo simulation. Shapes become mesh instances once; each
+  `render(state)` only moves them. Sphere, box, capsule, cylinder, cone, ellipsoid,
+  plane and mesh shapes, with colours from the model.
+- `neraulgraphics.shapes`: capsule, cylinder, cone, plane and sphere generators, and the
+  pose math (`pose_matrices`, `compose_poses`) the adapters use.
+- `examples/` with Newton, MuJoCo and model-viewing scripts, and `mujoco` and `images` extras.
+- Smooth shading and textures. `Mesh` takes optional per-vertex `normals` and `uvs`; a new
+  `Texture` (RGBA8, sRGB, bilinear filtered, repeating) can be put on an `Instance` with its
+  `texture` index, and multiplies into the material's diffuse colour. `Renderer` takes `textures`.
+- `neraulgraphics.load`, `load_gltf` and `load_obj`: glTF 2.0 (`.gltf` and `.glb`) and
+  Wavefront OBJ with materials, colour textures, vertex normals and node transforms, returning a
+  `LoadedScene` whose `.renderer()` frames the model and lights it.
+- `Renderer.ambient` (C++: `set_ambient`): light reaching every surface regardless of the lights,
+  so faces turned from every light are not black. Defaults to 0; the adapters and loaders
+  default to 0.2.
+- Simulator planes draw as a checkerboard ground.
+
+### Changed
+- `make_camera` computes in double precision on the CPU, so a camera is identical on both backends.
+- Python wheel tests now render for real on build machines, on the CPU backend.
+
+### Known limits
+- Textures are not mip-mapped, so distant fine patterns grain until samples accumulate.
+- The CPU backend is roughly 40 to 100 times slower than a recent GPU (at 1280x720 a 16-core CPU takes 17 to 41 ms for 138k-triangle models).
+- glTF: no animation or skinning (bind pose is drawn), normal maps, transparency or Draco.
+
+## [0.3.0]
+
+Triangle meshes and dynamic scenes.
+
+### Added
+- Apache-2.0 license.
+- Triangle meshes. `Mesh` is geometry, built into a BVH once; `Instance` places a
+  mesh with its own `Transform` and `Material`. The number of instances is not
+  capped, unlike spheres. Pass them to `Renderer(..., meshes, instances)`.
+- `Renderer::set_instance_transforms()` (Python: an `(N, 3, 4)` array or a list of
+  `Transform`) moves instances without touching the meshes. The tree over
+  instances is refitted in place and rebuilt only when it has loosened too far.
+- `make_transform` (position, `(x, y, z, w)` quaternion, scale), `make_box` and
+  `make_icosphere`, in C++ and Python.
+- `make raytracer` builds the viewer and links it as `./raytracer`; `make run`
+  and `make test` do the obvious. The viewer takes `--instances N` to spawn
+  spinning shapes.
+
+### Known limits
+- Triangles are shaded flat, with no vertex normals or textures.
+- Updating instances runs on the CPU: about 9 ms for 10,000 and 90 ms for 100,000.
+- Ray-triangle tests are not watertight along an exact shared edge.
+
+## [0.2.0]
+
+The renderer is now a package you can call from Python or C++.
+
+### Added
+- Python package: `pip install`, then `import neraulgraphics`. `Renderer.render()`
+  returns a `(height, width, 3)` uint8 numpy array. Vectors are plain tuples,
+  lists or numpy arrays. Bad input raises `ValueError`; CUDA failures raise
+  `neraulgraphics.CudaError`. Type stubs included.
+- Linux wheels for Python 3.10 and later that need only the NVIDIA driver, not
+  the CUDA toolkit, built for every GPU generation from Turing to Blackwell.
+- `neraulgraphics/version.h`, generated from the version in `CMakeLists.txt`.
+- C++ tests, run with `ctest`.
+
+### Changed
+- Renamed everything to `neraulgraphics`: `find_package(neraulgraphics)`, the
+  `neraulgraphics::core` target, `#include <neraulgraphics/renderer.h>` and
+  `namespace neraulgraphics`. The viewer is now `neraulgraphics-viewer`.
+- The public headers no longer include any CUDA header. Vectors are
+  `neraulgraphics::Vec3`, and `make_camera` is computed inside the library, so
+  cameras no longer depend on the caller's floating point flags.
+- The `Renderer` floor argument is optional; the default is no floor.
+
+## [0.1.0]
+
+- The renderer as a library: a `gpu::Renderer` class that owns its device
+  memory, reports errors as exceptions, and rejects bad input before it reaches
+  the GPU.
+- CMake install and `find_package(raytracer)` support.

neraulgraphics-0.4.0/CMakeLists.txt

@@ -0,0 +1,214 @@
+cmake_minimum_required(VERSION 3.28)
+
+# Must precede project(): with no build type CMake adds no -O flag and GCC defaults to -O0.
+# Only when built on its own; a project that pulls this one in keeps its own build type.
+if (CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR AND NOT CMAKE_BUILD_TYPE
+        AND NOT CMAKE_CONFIGURATION_TYPES)
+    set(CMAKE_BUILD_TYPE Release CACHE STRING "Build Type" FORCE)
+endif()
+
+# 120 = compute capability 12.0 (RTX 50-series). "native" works on CUDA 12.6+.
+# A default only: set before project(), which would otherwise cache its own (75
+# with CUDA 13), so -DCMAKE_CUDA_ARCHITECTURES=... on the command line still wins.
+# A build directory configured before this file existed may hold that 75; reset
+# its cache once (CLion: Tools > CMake > Reset Cache and Reload Project).
+# A pip install from source defaults to "native", the GPU of the machine building it.
+if (NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+    if (DEFINED SKBUILD)
+        set(CMAKE_CUDA_ARCHITECTURES native CACHE STRING "CUDA architectures to compile for")
+    else()
+        set(CMAKE_CUDA_ARCHITECTURES 120 CACHE STRING "CUDA architectures to compile for")
+    endif()
+endif()
+
+# The one place the version is written. version.h, the find_package version file,
+# the Python package metadata and neraulgraphics.__version__ all read it from here.
+project(neraulgraphics VERSION 0.4.0 LANGUAGES CXX)
+
+# CUDA is optional. Without it the library still builds and renders, on the CPU, with nothing but a
+# C++17 compiler. AUTO uses CUDA when a CUDA compiler is found; ON requires it; OFF skips it.
+set(NERAULGRAPHICS_CUDA AUTO CACHE STRING "Build the CUDA (NVIDIA GPU) backend: AUTO, ON or OFF")
+set_property(CACHE NERAULGRAPHICS_CUDA PROPERTY STRINGS AUTO ON OFF)
+set(NERAULGRAPHICS_WITH_CUDA OFF)
+if (NERAULGRAPHICS_CUDA STREQUAL "ON")
+    enable_language(CUDA)
+    set(NERAULGRAPHICS_WITH_CUDA ON)
+elseif (NERAULGRAPHICS_CUDA STREQUAL "AUTO")
+    include(CheckLanguage)
+    check_language(CUDA)
+    if (CMAKE_CUDA_COMPILER)
+        enable_language(CUDA)
+        set(NERAULGRAPHICS_WITH_CUDA ON)
+    endif()
+endif()
+message(STATUS "neraulgraphics: CUDA backend ${NERAULGRAPHICS_WITH_CUDA}; the CPU backend is always built")
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CUDA_STANDARD 17)
+set(CMAKE_CUDA_STANDARD_REQUIRED ON)
+
+# On by default only when this is the top-level project, so a project that uses
+# the library through add_subdirectory or FetchContent never needs SDL2.
+option(NERAULGRAPHICS_BUILD_VIEWER "Build the interactive SDL2 viewer" ${PROJECT_IS_TOP_LEVEL})
+option(NERAULGRAPHICS_BUILD_TESTS "Build the C++ tests (run with ctest)" ${PROJECT_IS_TOP_LEVEL})
+option(NERAULGRAPHICS_INSTALL "Generate install rules and the find_package config" ${PROJECT_IS_TOP_LEVEL})
+option(NERAULGRAPHICS_BUILD_PYTHON "Build the Python module (pip install . sets this)" OFF)
+
+# Shared links libcudart.so, which the machine running the program must have.
+# Static bakes the runtime in and needs only the NVIDIA driver, which is what lets
+# a Python wheel run on a machine without the CUDA toolkit.
+set(NERAULGRAPHICS_CUDA_RUNTIME Shared CACHE STRING "How to link the CUDA runtime: Shared or Static")
+set_property(CACHE NERAULGRAPHICS_CUDA_RUNTIME PROPERTY STRINGS Shared Static)
+
+find_package(Threads REQUIRED)
+if (NERAULGRAPHICS_WITH_CUDA)
+    find_package(CUDAToolkit REQUIRED)
+endif()
+
+# ---------------------------------------------------------------- library --
+
+# The renderer on its own: no window, no SDL. Consumers link neraulgraphics::core.
+add_library(neraulgraphics_core STATIC
+    src/renderer.cpp
+    src/cpu_backend.cpp
+    src/instances.cpp
+    src/bvh.cpp
+    src/mesh.cpp
+    src/mesh_build.cpp)
+if (NERAULGRAPHICS_WITH_CUDA)
+    target_sources(neraulgraphics_core PRIVATE src/cuda_backend.cu)
+else()
+    target_sources(neraulgraphics_core PRIVATE src/cuda_backend_stub.cpp)
+endif()
+add_library(neraulgraphics::core ALIAS neraulgraphics_core)
+
+configure_file(cmake/version.h.in ${CMAKE_CURRENT_BINARY_DIR}/include/neraulgraphics/version.h
+    @ONLY)
+
+# The public headers. BASE_DIRS makes these the include path, both here and once
+# installed, so every consumer writes #include <neraulgraphics/renderer.h>.
+# Everything in src/ (the BVH, the rendering core, the backends) stays private to the library.
+target_sources(neraulgraphics_core PUBLIC
+    FILE_SET HEADERS
+    BASE_DIRS include ${CMAKE_CURRENT_BINARY_DIR}/include
+    FILES
+        include/neraulgraphics/mesh.h
+        include/neraulgraphics/renderer.h
+        include/neraulgraphics/scene.h
+        ${CMAKE_CURRENT_BINARY_DIR}/include/neraulgraphics/version.h)
+
+target_include_directories(neraulgraphics_core PRIVATE src)
+
+# PRIVATE: the public headers need nothing from CUDA or threads. A static library still
+# carries them to whoever links it, as link-only dependencies.
+target_link_libraries(neraulgraphics_core PRIVATE Threads::Threads)
+if (NERAULGRAPHICS_WITH_CUDA)
+    if (NERAULGRAPHICS_CUDA_RUNTIME STREQUAL "Static")
+        target_link_libraries(neraulgraphics_core PRIVATE CUDA::cudart_static)
+    else()
+        target_link_libraries(neraulgraphics_core PRIVATE CUDA::cudart)
+    endif()
+endif()
+target_compile_features(neraulgraphics_core PUBLIC cxx_std_17)
+
+# Position-independent so the library can be linked into a shared object, such as
+# the Python extension module.
+set_target_properties(neraulgraphics_core PROPERTIES
+    POSITION_INDEPENDENT_CODE ON
+    EXPORT_NAME core)
+
+target_compile_options(neraulgraphics_core PRIVATE
+    $<$<AND:$<CONFIG:Release>,$<COMPILE_LANGUAGE:CUDA>>:-use_fast_math>
+    # Prints registers per thread and spill counts; a nonzero stack frame means
+    # something fell out to local memory.
+    $<$<COMPILE_LANGUAGE:CUDA>:-Xptxas=-v>)
+
+# ----------------------------------------------------------------- viewer --
+
+if (NERAULGRAPHICS_BUILD_VIEWER)
+    find_package(SDL2 REQUIRED)
+
+    # Links the library exactly the way an outside project would.
+    add_executable(neraulgraphics-viewer src/main.cpp)
+    target_link_libraries(neraulgraphics-viewer PRIVATE neraulgraphics::core SDL2::SDL2)
+
+    # The COMPILE_LANGUAGE guard is required: nvcc rejects -march=native and -ffast-math.
+    # -ffast-math lets the compiler assume NaN never occurs, which is why the
+    # renderer's input checks live in render_gpu.cu, not in anything built here.
+    target_compile_options(neraulgraphics-viewer PRIVATE
+        $<$<AND:$<CONFIG:Release>,$<COMPILE_LANGUAGE:CXX>>:-march=native -ffast-math>)
+endif()
+
+# ------------------------------------------------------------------ tests --
+
+if (NERAULGRAPHICS_BUILD_TESTS)
+    enable_testing()
+    # Plain C++ built with -ffast-math, like the viewer: the checks must survive it.
+    add_executable(neraulgraphics-tests tests/test_renderer.cpp)
+    target_link_libraries(neraulgraphics-tests PRIVATE neraulgraphics::core)
+    # The BVH builder is library-private, but its tests want it directly.
+    target_include_directories(neraulgraphics-tests PRIVATE src)
+    target_compile_options(neraulgraphics-tests PRIVATE
+        $<$<AND:$<CONFIG:Release>,$<COMPILE_LANGUAGE:CXX>>:-ffast-math>)
+    add_test(NAME renderer COMMAND neraulgraphics-tests)
+endif()
+
+# ----------------------------------------------------------------- python --
+
+if (NERAULGRAPHICS_BUILD_PYTHON)
+    find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module
+        OPTIONAL_COMPONENTS Development.SABIModule)
+    execute_process(COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+        OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT)
+    find_package(nanobind CONFIG REQUIRED)
+
+    # STABLE_ABI: on Python 3.12+ one build serves every later version too.
+    nanobind_add_module(_core STABLE_ABI NB_STATIC python/bindings.cpp)
+    # __version__ comes from the generated version.h, like everything else.
+    target_link_libraries(_core PRIVATE neraulgraphics::core)
+    install(TARGETS _core LIBRARY DESTINATION neraulgraphics)
+
+    # Type stubs, so editors can autocomplete and type-check against the module.
+    nanobind_add_stub(_core_stub
+        MODULE _core
+        OUTPUT _core.pyi
+        PYTHON_PATH $<TARGET_FILE_DIR:_core>
+        DEPENDS _core)
+    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/_core.pyi DESTINATION neraulgraphics)
+endif()
+
+# ---------------------------------------------------------------- install --
+
+if (NERAULGRAPHICS_INSTALL)
+    include(GNUInstallDirs)
+    include(CMakePackageConfigHelpers)
+
+    set(NERAULGRAPHICS_CMAKE_DIR ${CMAKE_INSTALL_LIBDIR}/cmake/neraulgraphics)
+
+    install(TARGETS neraulgraphics_core
+        EXPORT neraulgraphicsTargets
+        FILE_SET HEADERS)
+
+    # Writes the imported target neraulgraphics::core that find_package hands back.
+    install(EXPORT neraulgraphicsTargets
+        NAMESPACE neraulgraphics::
+        DESTINATION ${NERAULGRAPHICS_CMAKE_DIR})
+
+    configure_package_config_file(cmake/neraulgraphicsConfig.cmake.in
+        ${CMAKE_CURRENT_BINARY_DIR}/neraulgraphicsConfig.cmake
+        INSTALL_DESTINATION ${NERAULGRAPHICS_CMAKE_DIR})
+
+    # Before 1.0 a minor version may change the API, so only the same minor matches.
+    write_basic_package_version_file(${CMAKE_CURRENT_BINARY_DIR}/neraulgraphicsConfigVersion.cmake
+        COMPATIBILITY SameMinorVersion)
+
+    install(FILES
+            ${CMAKE_CURRENT_BINARY_DIR}/neraulgraphicsConfig.cmake
+            ${CMAKE_CURRENT_BINARY_DIR}/neraulgraphicsConfigVersion.cmake
+        DESTINATION ${NERAULGRAPHICS_CMAKE_DIR})
+
+    if (NERAULGRAPHICS_BUILD_VIEWER)
+        install(TARGETS neraulgraphics-viewer RUNTIME)
+    endif()
+endif()