VPYrender 0.1.0__py3-none-any.whl

display_driver.py

@@ -0,0 +1,305 @@
+"""Software triangle renderer and built-in scene meshes."""
+
+from __future__ import annotations
+
+from array import array
+from dataclasses import dataclass
+from math import floor, inf, sqrt
+from typing import TypeAlias
+
+from mathengine import Mat4, identity, multiply, scale, translation
+
+RGB: TypeAlias = tuple[float, float, float]
+ProjectedVertex: TypeAlias = tuple[float, float, float, float, float, float]
+ProjectedTriangle: TypeAlias = tuple[ProjectedVertex, ProjectedVertex, ProjectedVertex, float]
+SHADERS = ("Vertex", "Flat", "Toon", "Wireframe", "Depth")
+BACKGROUND = (12, 17, 24)
+
+
+@dataclass(frozen=True, slots=True)
+class Mesh:
+	"""Indexed mesh with interleaved XYZ position and RGB color attributes."""
+
+	vertices: tuple[float, ...]
+	indices: tuple[int, ...]
+
+	def __post_init__(self) -> None:
+		if not self.vertices or len(self.vertices) % 6:
+			raise ValueError("vertices must contain interleaved XYZ/RGB values")
+		if not self.indices or len(self.indices) % 3:
+			raise ValueError("indices must contain one or more triangles")
+		vertex_count = len(self.vertices) // 6
+		if min(self.indices) < 0 or max(self.indices) >= vertex_count:
+			raise ValueError("mesh index is outside the vertex array")
+
+
+def cube_mesh() -> Mesh:
+	vertices = (
+		-1, -1, -1, 1.00, 0.26, 0.19,
+		 1, -1, -1, 1.00, 0.68, 0.20,
+		 1,  1, -1, 0.38, 0.82, 0.34,
+		-1,  1, -1, 0.15, 0.72, 0.67,
+		-1, -1,  1, 0.20, 0.52, 0.92,
+		 1, -1,  1, 0.46, 0.34, 0.88,
+		 1,  1,  1, 0.92, 0.34, 0.67,
+		-1,  1,  1, 0.95, 0.72, 0.32,
+	)
+	indices = (
+		0, 2, 1, 0, 3, 2,
+		4, 5, 6, 4, 6, 7,
+		0, 1, 5, 0, 5, 4,
+		3, 7, 6, 3, 6, 2,
+		0, 4, 7, 0, 7, 3,
+		1, 2, 6, 1, 6, 5,
+	)
+	return Mesh(vertices, indices)
+
+
+@dataclass(frozen=True, slots=True)
+class SceneObject:
+	mesh: Mesh
+	model: Mat4
+
+
+@dataclass(frozen=True, slots=True)
+class Scene:
+	objects: tuple[SceneObject, ...]
+
+	@property
+	def cube_count(self) -> int:
+		return len(self.objects) - 1
+
+
+def make_scene(extra_cubes: int = 0) -> Scene:
+	if extra_cubes < 0:
+		raise ValueError("extra_cubes cannot be negative")
+	ground = Mesh((
+		-9, -1.2, -9, 0.16, 0.21, 0.24,
+		 9, -1.2, -9, 0.16, 0.21, 0.24,
+		 9, -1.2,  9, 0.22, 0.28, 0.29,
+		-9, -1.2,  9, 0.22, 0.28, 0.29,
+	), (0, 2, 1, 0, 3, 2))
+	objects = [SceneObject(ground, identity())]
+	cube = cube_mesh()
+	for row in range(3):
+		for column in range(3):
+			x = (column - 1) * 2.2
+			z = (row - 1) * 2.2
+			model = multiply(translation(x, -0.68, z), scale(0.48, 0.48, 0.48))
+			objects.append(SceneObject(cube, model))
+	for index in range(extra_cubes):
+		column = index % 5
+		row = index // 5
+		x = (column - 2) * 1.15
+		z = 3.5 + row * 1.2
+		model = multiply(translation(x, -0.68, z), scale(0.35, 0.35, 0.35))
+		objects.append(SceneObject(cube, model))
+	return Scene(tuple(objects))
+
+
+class Renderer:
+	"""CPU depth-buffer renderer; completed scan bands stay in the RGB buffer."""
+
+	def __init__(self, size: tuple[int, int]) -> None:
+		self.width, self.height = size
+		if self.width < 1 or self.height < 1:
+			raise ValueError("render target dimensions must be positive")
+		self.pixels = bytearray(self.width * self.height * 3)
+		self.depth = array("f", [inf]) * (self.width * self.height)
+		self._cached_scene: Scene | None = None
+		self._cached_mvp: Mat4 | None = None
+		self._triangles: tuple[ProjectedTriangle, ...] = ()
+		self._smoke_points: tuple[tuple[float, float, float, float], ...] = ()
+
+	def _project_point(self, mvp: Mat4, point: tuple[float, float, float], radius: float) -> tuple[float, float, float, float] | None:
+		x, y, z = point
+		clip_x = mvp[0] * x + mvp[4] * y + mvp[8] * z + mvp[12]
+		clip_y = mvp[1] * x + mvp[5] * y + mvp[9] * z + mvp[13]
+		clip_z = mvp[2] * x + mvp[6] * y + mvp[10] * z + mvp[14]
+		clip_w = mvp[3] * x + mvp[7] * y + mvp[11] * z + mvp[15]
+		if clip_w <= 0.05:
+			return None
+		return (
+			(clip_x / clip_w * 0.5 + 0.5) * self.width,
+			(0.5 - clip_y / clip_w * 0.5) * self.height,
+			clip_z / clip_w,
+			radius * self.height / (2.0 * clip_w),
+		)
+
+	def _project_scene(self, scene: Scene, mvp: Mat4) -> None:
+		if scene is self._cached_scene and mvp == self._cached_mvp:
+			return
+		triangles: list[ProjectedTriangle] = []
+		light = (-0.35, 0.82, 0.45)
+		light_length = sqrt(sum(component * component for component in light))
+		light = tuple(component / light_length for component in light)
+		for scene_object in scene.objects:
+			transform = multiply(mvp, scene_object.model)
+			mesh = scene_object.mesh
+			projected: list[ProjectedVertex | None] = []
+			for offset in range(0, len(mesh.vertices), 6):
+				x, y, z, red, green, blue = mesh.vertices[offset:offset + 6]
+				clip_x = transform[0] * x + transform[4] * y + transform[8] * z + transform[12]
+				clip_y = transform[1] * x + transform[5] * y + transform[9] * z + transform[13]
+				clip_z = transform[2] * x + transform[6] * y + transform[10] * z + transform[14]
+				clip_w = transform[3] * x + transform[7] * y + transform[11] * z + transform[15]
+				if clip_w <= 0.05:
+					projected.append(None)
+					continue
+				reciprocal_w = 1.0 / clip_w
+				screen_x = (clip_x * reciprocal_w * 0.5 + 0.5) * self.width
+				screen_y = (0.5 - clip_y * reciprocal_w * 0.5) * self.height
+				projected.append((screen_x, screen_y, clip_z * reciprocal_w, red, green, blue))
+			for offset in range(0, len(mesh.indices), 3):
+				indices = mesh.indices[offset:offset + 3]
+				first, second, third = (projected[index] for index in indices)
+				if first is None or second is None or third is None:
+					continue
+				points = [mesh.vertices[index * 6:index * 6 + 3] for index in indices]
+				edge_a = tuple(points[1][axis] - points[0][axis] for axis in range(3))
+				edge_b = tuple(points[2][axis] - points[0][axis] for axis in range(3))
+				normal = (
+					edge_a[1] * edge_b[2] - edge_a[2] * edge_b[1],
+					edge_a[2] * edge_b[0] - edge_a[0] * edge_b[2],
+					edge_a[0] * edge_b[1] - edge_a[1] * edge_b[0],
+				)
+				normal_length = sqrt(sum(component * component for component in normal)) or 1.0
+				brightness = 0.22 + 0.78 * abs(sum(normal[axis] * light[axis] for axis in range(3)) / normal_length)
+				triangles.append((first, second, third, brightness))
+		self._triangles = tuple(triangles)
+		self._cached_scene = scene
+		self._cached_mvp = mvp
+		self._smoke_points = tuple(
+			point for point in (
+				self._project_point(mvp, (-2.8, 0.15, -1.6), 0.55),
+				self._project_point(mvp, (-2.35, 0.48, -1.65), 0.72),
+				self._project_point(mvp, (-1.85, 0.25, -1.7), 0.62),
+				self._project_point(mvp, (-2.3, 0.78, -1.65), 0.46),
+			) if point is not None
+		)
+
+	def _clear_band(self, top: int, bottom: int) -> None:
+		background = bytes(BACKGROUND) * self.width
+		depth_row = array("f", [inf]) * self.width
+		for y in range(top, bottom):
+			pixel_start = y * self.width * 3
+			self.pixels[pixel_start:pixel_start + self.width * 3] = background
+			depth_start = y * self.width
+			self.depth[depth_start:depth_start + self.width] = depth_row
+
+	def _draw_triangle(self, triangle: ProjectedTriangle, top: int, bottom: int, shader: str) -> None:
+		first, second, third, brightness = triangle
+		ax, ay, az, ar, ag, ab = first
+		bx, by, bz, br, bg, bb = second
+		cx, cy, cz, cr, cg, cb = third
+		area = (by - cy) * (ax - cx) + (cx - bx) * (ay - cy)
+		if abs(area) < 0.0001:
+			return
+		left = max(0, int(min(ax, bx, cx)))
+		right = min(self.width - 1, int(max(ax, bx, cx)))
+		upper = max(top, 0, int(min(ay, by, cy)))
+		lower = min(bottom - 1, self.height - 1, int(max(ay, by, cy)))
+		if left > right or upper > lower:
+			return
+		for y in range(upper, lower + 1):
+			py = y + 0.5
+			for x in range(left, right + 1):
+				px = x + 0.5
+				weight_a = ((by - cy) * (px - cx) + (cx - bx) * (py - cy)) / area
+				weight_b = ((cy - ay) * (px - cx) + (ax - cx) * (py - cy)) / area
+				weight_c = 1.0 - weight_a - weight_b
+				if min(weight_a, weight_b, weight_c) < 0.0:
+					continue
+				if shader == "Wireframe" and min(weight_a, weight_b, weight_c) > 0.035:
+					continue
+				depth = (weight_a * az + weight_b * bz + weight_c * cz + 1.0) * 0.5
+				pixel_index = y * self.width + x
+				if depth >= self.depth[pixel_index]:
+					continue
+				self.depth[pixel_index] = depth
+				if shader == "Depth":
+					red = green = blue = int(max(0.0, min(1.0, 1.0 - depth)) * 255)
+				else:
+					if shader == "Flat":
+						red, green, blue = (ar + br + cr) / 3, (ag + bg + cg) / 3, (ab + bb + cb) / 3
+					else:
+						red = weight_a * ar + weight_b * br + weight_c * cr
+						green = weight_a * ag + weight_b * bg + weight_c * cg
+						blue = weight_a * ab + weight_b * bb + weight_c * cb
+						if shader == "Toon":
+							brightness = max(0.28, floor(brightness * 4) / 4)
+					red *= brightness
+					green *= brightness
+					blue *= brightness
+					red, green, blue = (int(max(0.0, min(1.0, value)) * 255) for value in (red, green, blue))
+				pixel_offset = pixel_index * 3
+				self.pixels[pixel_offset:pixel_offset + 3] = bytes((red, green, blue))
+
+	def _draw_smoke(self, top: int, bottom: int) -> None:
+		for center_x, center_y, ndc_depth, radius in self._smoke_points:
+			left = max(0, int(center_x - radius))
+			right = min(self.width - 1, int(center_x + radius))
+			upper = max(top, 0, int(center_y - radius))
+			lower = min(bottom - 1, self.height - 1, int(center_y + radius))
+			if radius < 1 or left > right or upper > lower:
+				continue
+			depth = (ndc_depth + 1.0) * 0.5
+			for y in range(upper, lower + 1):
+				for x in range(left, right + 1):
+					dx = (x + 0.5 - center_x) / radius
+					dy = (y + 0.5 - center_y) / radius
+					distance = dx * dx + dy * dy
+					if distance >= 1.0:
+						continue
+					pixel_index = y * self.width + x
+					if depth > self.depth[pixel_index] + 0.015:
+						continue
+					pixel_offset = pixel_index * 3
+					alpha = (1.0 - distance) * 0.28
+					for channel in range(3):
+						old = self.pixels[pixel_offset + channel]
+						self.pixels[pixel_offset + channel] = int(old * (1.0 - alpha) + 185 * alpha)
+
+	def render_band(
+		self,
+		scene: Scene,
+		mvp: Mat4,
+		top: int,
+		band_height: int,
+		shader: str = "Vertex",
+		smoke: bool = False,
+	) -> tuple[int, int]:
+		if shader not in SHADERS:
+			raise ValueError(f"Unknown software shader: {shader}")
+		if band_height < 1:
+			raise ValueError("band_height must be positive")
+		start = max(0, top)
+		end = min(self.height, top + band_height)
+		if start >= end:
+			return start, start
+		self._project_scene(scene, mvp)
+		self._clear_band(start, end)
+		for triangle in self._triangles:
+			self._draw_triangle(triangle, start, end, shader)
+		if smoke:
+			self._draw_smoke(start, end)
+		return start, end
+
+	def render_all(self, scene: Scene, mvp: Mat4, shader: str = "Vertex", smoke: bool = False) -> bytearray:
+		self.render_band(scene, mvp, 0, self.height, shader, smoke)
+		return self.pixels
+
+
+def write_ppm(path: str, pixels: bytes, width: int, height: int) -> None:
+	"""Write tightly packed RGB pixels as a portable PPM image."""
+	expected_size = width * height * 3
+	if len(pixels) != expected_size:
+		raise ValueError(f"expected {expected_size} pixel bytes, got {len(pixels)}")
+	row_size = width * 3
+	flipped = b"".join(
+		pixels[row * row_size:(row + 1) * row_size]
+		for row in range(height - 1, -1, -1)
+	)
+	with open(path, "wb") as image:
+		image.write(f"P6\n{width} {height}\n255\n".encode("ascii"))
+		image.write(flipped)

gui.py

@@ -0,0 +1,131 @@
+"""Optional pygame window and sidebar controls for the software renderer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from display_driver import Renderer, SHADERS, make_scene
+from main import view_projection
+
+
+def run(config: dict[str, Any]) -> None:
+	try:
+		import pygame
+	except ImportError as error:
+		raise RuntimeError("GUI support requires pygame-ce; install with: pip install '.[gui]'") from error
+
+	pygame.init()
+	width, height = config["width"], config["height"]
+	sidebar_width = 292
+	screen = pygame.display.set_mode((width + sidebar_width, height))
+	pygame.display.set_caption(config["title"])
+	renderer = Renderer((width, height))
+	frame = pygame.image.frombuffer(renderer.pixels, (width, height), "RGB")
+	scene = make_scene()
+	mvp = view_projection(width, height)
+	clock = pygame.time.Clock()
+	font = pygame.font.SysFont("consolas", 16)
+	small_font = pygame.font.SysFont("consolas", 13)
+	show_scan_bar = True
+	scan_speed = 300.0
+	scan_top = 0
+	scene_dirty = True
+	smoke = False
+	extra_cubes = 0
+	shader_index = 0
+	shader_menu_open = False
+	dragging_speed = False
+	running = True
+
+	def reset_scan() -> None:
+		nonlocal scan_top, scene_dirty
+		scan_top = 0
+		scene_dirty = True
+
+	def text(label: str, position: tuple[int, int], color: tuple[int, int, int] = (215, 224, 231), small: bool = False) -> None:
+		image = (small_font if small else font).render(label, True, color)
+		screen.blit(image, position)
+
+	def button(label: str, rectangle: Any, active: bool = False) -> None:
+		background = (51, 91, 88) if active else (39, 48, 58)
+		pygame.draw.rect(screen, background, rectangle, border_radius=4)
+		pygame.draw.rect(screen, (70, 87, 97), rectangle, 1, border_radius=4)
+		text(label, (rectangle.x + 10, rectangle.y + 8), (235, 241, 242))
+
+	try:
+		while running:
+			delta = min(clock.tick(60) / 1000.0, 0.05)
+			for event in pygame.event.get():
+				if event.type == pygame.QUIT:
+					running = False
+				elif event.type == pygame.KEYDOWN and event.key == pygame.K_ESCAPE:
+					running = False
+				elif event.type == pygame.MOUSEBUTTONUP and event.button == 1:
+					dragging_speed = False
+				elif event.type == pygame.MOUSEBUTTONDOWN and event.button == 1:
+					mouse_x, mouse_y = event.pos
+					if dragging_speed:
+						dragging_speed = False
+					if 18 <= mouse_x <= 274 and 78 <= mouse_y <= 114:
+						show_scan_bar = not show_scan_bar
+					elif 18 <= mouse_x <= 274 and 184 <= mouse_y <= 220:
+						smoke = not smoke
+						reset_scan()
+					elif 24 <= mouse_x <= 268 and 148 <= mouse_y <= 174:
+						dragging_speed = True
+						scan_speed = 30 + (mouse_x - 24) / 244 * 1170
+					elif 18 <= mouse_x <= 274 and 252 <= mouse_y <= 288:
+						shader_menu_open = not shader_menu_open
+					elif shader_menu_open and 18 <= mouse_x <= 274 and 292 <= mouse_y < 292 + 30 * len(SHADERS):
+						shader_index = (mouse_y - 292) // 30
+						shader_menu_open = False
+						reset_scan()
+					elif 18 <= mouse_x <= 274 and 448 <= mouse_y <= 484:
+						extra_cubes += 1
+						scene = make_scene(extra_cubes)
+						reset_scan()
+					elif 18 <= mouse_x <= 274 and 494 <= mouse_y <= 530:
+						extra_cubes = 0
+						scene = make_scene()
+						reset_scan()
+				elif event.type == pygame.MOUSEMOTION and dragging_speed:
+					mouse_x = max(24, min(268, event.pos[0]))
+					scan_speed = 30 + (mouse_x - 24) / 244 * 1170
+
+			if scene_dirty:
+				band_height = max(1, int(scan_speed * max(delta, 1 / 60)))
+				renderer.render_band(scene, mvp, scan_top, band_height, SHADERS[shader_index], smoke)
+				scan_top += band_height
+				if scan_top >= height:
+					scan_top = height
+					scene_dirty = False
+
+			screen.blit(frame, (sidebar_width, 0))
+			pygame.draw.rect(screen, (24, 30, 38), (0, 0, sidebar_width, height))
+			pygame.draw.line(screen, (59, 72, 80), (sidebar_width - 1, 0), (sidebar_width - 1, height), 1)
+			text("SOFTWARE RENDERER", (20, 20), (225, 160, 104))
+			text(f"SCENE  {scene.cube_count} CUBES", (20, 49), small=True)
+			button(f"Show scan bar   {'ON' if show_scan_bar else 'OFF'}", pygame.Rect(18, 78, 256, 36), show_scan_bar)
+			text(f"SCAN SPEED   {int(scan_speed)} px/s", (20, 125), small=True)
+			pygame.draw.line(screen, (65, 78, 87), (24, 161), (268, 161), 4)
+			slider_x = int(24 + (scan_speed - 30) / 1170 * 244)
+			pygame.draw.line(screen, (222, 137, 81), (24, 161), (slider_x, 161), 4)
+			pygame.draw.circle(screen, (240, 182, 128), (slider_x, 161), 7)
+			button(f"Smoke   {'ON' if smoke else 'OFF'}", pygame.Rect(18, 184, 256, 36), smoke)
+			text("SOFTWARE SHADER", (20, 230), small=True)
+			button(f"{SHADERS[shader_index]}   v", pygame.Rect(18, 252, 256, 36))
+			if shader_menu_open:
+				for index, name in enumerate(SHADERS):
+					button(name, pygame.Rect(18, 292 + index * 30, 256, 28), index == shader_index)
+			button("+   Add cube", pygame.Rect(18, 448, 256, 36))
+			button("Reset scene", pygame.Rect(18, 494, 256, 36))
+			status = f"SCAN {min(100, int(scan_top / height * 100)):3d}%" if scene_dirty else "SCENE UP TO DATE"
+			text(status, (sidebar_width + 16, 14), (228, 184, 142), small=True)
+			text(f"{clock.get_fps():.0f} FPS", (sidebar_width + 16, 34), (213, 221, 228), small=True)
+			if show_scan_bar and scene_dirty:
+				scan_y = min(height - 1, scan_top)
+				pygame.draw.line(screen, (235, 145, 88), (sidebar_width, scan_y), (sidebar_width + width, scan_y), 2)
+			pygame.display.flip()
+	finally:
+		del frame
+		pygame.quit()

main.py

@@ -0,0 +1,105 @@
+"""Command-line entry point for the lightweight software renderer."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from time import perf_counter
+from typing import Any
+
+from display_driver import Renderer, make_scene, write_ppm
+from mathengine import look_at, multiply, perspective
+
+DEFAULT_CONFIG: dict[str, Any] = {
+	"gui": False,
+	"width": 960,
+	"height": 540,
+	"title": "PYrendering",
+	"frame_output": "frame.ppm",
+}
+
+
+def default_config_path() -> Path:
+	if getattr(sys, "frozen", False):
+		return Path(sys.executable).resolve().parent / "config.json"
+	return Path.cwd() / "config.json"
+
+
+def load_config(path: Path) -> dict[str, Any]:
+	if not path.exists():
+		return DEFAULT_CONFIG.copy()
+	try:
+		config = json.loads(path.read_text(encoding="utf-8"))
+	except json.JSONDecodeError as error:
+		raise ValueError(f"Invalid JSON in {path}: {error}") from error
+	if not isinstance(config, dict):
+		raise ValueError("config.json must contain a JSON object")
+	merged = DEFAULT_CONFIG | config
+	if type(merged["gui"]) is not bool:
+		raise ValueError("config.gui must be true or false")
+	for key in ("width", "height"):
+		if type(merged[key]) is not int or merged[key] < 1:
+			raise ValueError(f"config.{key} must be a positive integer")
+	if not isinstance(merged["title"], str) or not isinstance(merged["frame_output"], str):
+		raise ValueError("config.title and config.frame_output must be strings")
+	return merged
+
+
+def view_projection(width: int, height: int) -> tuple[float, ...]:
+	projection = perspective(1.0, width / height, 0.1, 100.0)
+	view = look_at((6.5, 5.2, 8.5), (0.0, -0.2, 0.0))
+	return multiply(projection, view)
+
+
+def render_frame(config: dict[str, Any], output: Path) -> None:
+	renderer = Renderer((config["width"], config["height"]))
+	pixels = renderer.render_all(make_scene(), view_projection(config["width"], config["height"]))
+	write_ppm(str(output), pixels, config["width"], config["height"])
+	print(f"Rendered {config['width']}x{config['height']} frame to {output}")
+
+
+def run_benchmark(config: dict[str, Any], frames: int = 10000) -> float:
+	if frames < 1:
+		raise ValueError("frames must be positive")
+	width = min(config["width"], 320)
+	height = min(config["height"], 180)
+	renderer = Renderer((width, height))
+	scene = make_scene()
+	mvp = view_projection(width, height)
+	band_height = max(1, height // 60)
+	started = perf_counter()
+	for index in range(frames):
+		top = (index * band_height) % height
+		renderer.render_band(scene, mvp, top, min(band_height, height - top))
+	elapsed = perf_counter() - started
+	bands_per_second = frames / elapsed
+	print(f"CPU software scan benchmark: {bands_per_second:,.0f} bands/s ({width}x{height}, {band_height} rows/band)")
+	return bands_per_second
+
+
+def main() -> None:
+	parser = argparse.ArgumentParser(description="Minimal software 3D renderer")
+	parser.add_argument("--config", type=Path, default=default_config_path())
+	parser.add_argument("--benchmark", action="store_true", help="benchmark software scan throughput")
+	parser.add_argument("--frames", type=int, default=10000, help="benchmark frame count")
+	parser.add_argument("--output", type=Path, help="headless output image path")
+	arguments = parser.parse_args()
+	try:
+		config = load_config(arguments.config)
+		if arguments.benchmark:
+			run_benchmark(config, arguments.frames)
+		elif config["gui"]:
+			from gui import run
+
+			run(config)
+		else:
+			output = arguments.output or Path(config["frame_output"])
+			render_frame(config, output)
+	except (ImportError, RuntimeError) as error:
+		raise SystemExit(f"Renderer startup failed: {error}") from error
+
+
+if __name__ == "__main__":
+	main()

mathengine.py

@@ -0,0 +1,116 @@
+"""Small column-major 3D math helpers for the renderer."""
+
+from __future__ import annotations
+
+from math import cos, sin, tan
+from typing import TypeAlias
+
+Vec3: TypeAlias = tuple[float, float, float]
+Mat4: TypeAlias = tuple[float, ...]
+
+
+def _normalize(vector: Vec3) -> Vec3:
+	length = sum(component * component for component in vector) ** 0.5
+	if length == 0.0:
+		raise ValueError("Cannot normalize a zero-length vector")
+	return tuple(component / length for component in vector)  # type: ignore[return-value]
+
+
+def _subtract(left: Vec3, right: Vec3) -> Vec3:
+	return (left[0] - right[0], left[1] - right[1], left[2] - right[2])
+
+
+def _cross(left: Vec3, right: Vec3) -> Vec3:
+	return (
+		left[1] * right[2] - left[2] * right[1],
+		left[2] * right[0] - left[0] * right[2],
+		left[0] * right[1] - left[1] * right[0],
+	)
+
+
+def _dot(left: Vec3, right: Vec3) -> float:
+	return sum(a * b for a, b in zip(left, right))
+
+
+def identity() -> Mat4:
+	return (
+		1.0, 0.0, 0.0, 0.0,
+		0.0, 1.0, 0.0, 0.0,
+		0.0, 0.0, 1.0, 0.0,
+		0.0, 0.0, 0.0, 1.0,
+	)
+
+
+def multiply(left: Mat4, right: Mat4) -> Mat4:
+	if len(left) != 16 or len(right) != 16:
+		raise ValueError("Matrix multiplication requires two 4x4 matrices")
+	return tuple(
+		sum(left[index * 4 + row] * right[column * 4 + index] for index in range(4))
+		for column in range(4)
+		for row in range(4)
+	)
+
+
+def perspective(field_of_view: float, aspect: float, near: float, far: float) -> Mat4:
+	if not 0.0 < field_of_view < 3.141592653589793:
+		raise ValueError("field_of_view must be between 0 and pi radians")
+	if aspect <= 0.0 or near <= 0.0 or far <= near:
+		raise ValueError("Expected aspect > 0 and 0 < near < far")
+	scale = 1.0 / tan(field_of_view / 2.0)
+	depth = near - far
+	return (
+		scale / aspect, 0.0, 0.0, 0.0,
+		0.0, scale, 0.0, 0.0,
+		0.0, 0.0, (far + near) / depth, -1.0,
+		0.0, 0.0, (2.0 * far * near) / depth, 0.0,
+	)
+
+
+def look_at(eye: Vec3, target: Vec3, up: Vec3 = (0.0, 1.0, 0.0)) -> Mat4:
+	forward = _normalize(_subtract(target, eye))
+	side = _normalize(_cross(forward, up))
+	camera_up = _cross(side, forward)
+	return (
+		side[0], camera_up[0], -forward[0], 0.0,
+		side[1], camera_up[1], -forward[1], 0.0,
+		side[2], camera_up[2], -forward[2], 0.0,
+		-_dot(side, eye), -_dot(camera_up, eye), _dot(forward, eye), 1.0,
+	)
+
+
+def rotation_x(angle: float) -> Mat4:
+	cosine, sine = cos(angle), sin(angle)
+	return (
+		1.0, 0.0, 0.0, 0.0,
+		0.0, cosine, sine, 0.0,
+		0.0, -sine, cosine, 0.0,
+		0.0, 0.0, 0.0, 1.0,
+	)
+
+
+def rotation_y(angle: float) -> Mat4:
+	cosine, sine = cos(angle), sin(angle)
+	return (
+		cosine, 0.0, -sine, 0.0,
+		0.0, 1.0, 0.0, 0.0,
+		sine, 0.0, cosine, 0.0,
+		0.0, 0.0, 0.0, 1.0,
+	)
+
+
+def translation(x: float, y: float, z: float) -> Mat4:
+	return (
+		1.0, 0.0, 0.0, 0.0,
+		0.0, 1.0, 0.0, 0.0,
+		0.0, 0.0, 1.0, 0.0,
+		x, y, z, 1.0,
+	)
+
+
+def scale(x: float, y: float, z: float) -> Mat4:
+	return (
+		x, 0.0, 0.0, 0.0,
+		0.0, y, 0.0, 0.0,
+		0.0, 0.0, z, 0.0,
+		0.0, 0.0, 0.0, 1.0,
+	)

vpyrender-0.1.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: VPYrender
+Version: 0.1.0
+Summary: A lightweight from-scratch software 3D renderer with optional desktop GUI
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: gui
+Requires-Dist: pygame-ce>=2.5; extra == "gui"
+Provides-Extra: build
+Requires-Dist: build>=1.2; extra == "build"
+Requires-Dist: pyinstaller>=6.0; extra == "build"
+
+# PYrendering
+
+A from-scratch, pure-Python software 3D renderer. It transforms and rasterizes triangles into a retained CPU framebuffer with a depth buffer; pygame-ce is used only for the optional desktop window and controls. No OpenGL, ModernGL, or GPU is required.
+
+## Run
+
+Install the optional GUI and run `python main.py`:
+
+```powershell
+python -m pip install -e ".[gui]"
+vpyrender
+```
+
+Set `"gui": true` in `config.json` to load the window and sidebar. Set it to `false` for a headless render to `frame.ppm`, or override the output with `--output`. The GUI includes scan visibility and speed, smoke, software-shader selection, add-cube, and reset-scene controls. Scene changes are rasterized a horizontal band at a time; already-rendered bands remain untouched until the next scan reaches them. Press Escape to close the window.
+
+The command-line entry point also supports a CPU scan-band throughput check:
+
+```powershell
+python main.py --benchmark --frames 10000
+```
+
+The benchmark reports CPU scan-band throughput, not displayed FPS. This is a Python software renderer, so performance depends on CPU, resolution, and scene complexity; 4,000 FPS is not a realistic general-purpose guarantee.
+
+## Debug scripts
+
+Run the scripts from the project root:
+
+```powershell
+python test_scripts/mathtest.py
+python test_scripts/meshtest.py
+python test_scripts/configtest.py
+python test_scripts/renderer_smoke_test.py
+python test_scripts/benchmark.py --frames 10000
+```
+
+The math, mesh, and renderer tests need only Python. Install the `gui` extra to run the interactive window. The CPU renderer runs on Raspberry Pi without an OpenGL driver; pygame-ce may require the platform's SDL development/runtime packages when installed from source.
+
+## Install on Linux / Raspberry Pi
+
+After publishing to PyPI, install the dependency-free renderer with `python -m pip install VPYrender`; use `python -m pip install "VPYrender[gui]"` to include the optional window. From a local checkout, use `python -m pip install .` or `python -m pip install ".[gui]"`. The installed command is `vpyrender`. To build a wheel, install the build extra and run:
+
+```sh
+python -m pip install '.[build]'
+python -m build --wheel
+python -m pip install dist/vpyrender-0.1.0-py3-none-any.whl
+```
+
+The wheel is platform-independent and the headless renderer uses only the Python standard library.
+
+## Build a Windows executable
+
+From PowerShell:
+
+```powershell
+python -m pip install ".[gui,build]"
+python -m PyInstaller --noconfirm --onefile --name pyrendering --exclude-module OpenGL --exclude-module cv2 --exclude-module numpy main.py
+Copy-Item config.json dist\config.json
+```
+
+The executable reads `config.json` beside itself. GUI builds bundle pygame-ce; headless-only builds can omit `--collect-all pygame` and install without the `gui` extra.

vpyrender-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+display_driver.py,sha256=54D1LbPfCoKCeZxv-spM9kUrQfajdycnHZttzlHibLg,11558
+gui.py,sha256=l6dAgYp2n2Gg4bLPJjzNZ22l1QGWQz56duMqH7h2jRo,5506
+main.py,sha256=F_W7nlvWU4c-i6yJ5ssng2Gqgym8Uytp6RoUHUKRHJk,3775
+mathengine.py,sha256=TqMPjjAoeyj0C5MS0Z1qwvDaA-Ph2QLmbgvfK-Y3atg,3077
+vpyrender-0.1.0.dist-info/METADATA,sha256=tYknNTbhhkBxhmDxTqUah5T10Y4ou9Tn30YPX90MQCI,3267
+vpyrender-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+vpyrender-0.1.0.dist-info/entry_points.txt,sha256=digr_-cZjVCh564fhfiQqWwTseIfZwnrr440iC4Q1rE,40
+vpyrender-0.1.0.dist-info/top_level.txt,sha256=g28heu3d3RP10Pf0Qx6eFvpTO6Amxdsf_pVFWv-H2Rw,35
+vpyrender-0.1.0.dist-info/RECORD,,

vpyrender-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vpyrender-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vpyrender = main:main

vpyrender-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,4 @@
+display_driver
+gui
+main
+mathengine