_______
                   ____                       /´  ____/\
  __ ______ _____ /   /\_ _ ______ _____ ____/   /_/___/\ __ _____ ______

==/ ´ __/ \ / ´ / ` , /==/ ´ / \ ==/ /´=/ ____/ /==/ /´=/ /==/ /=/ /=/ /==/ /´=/ __/\ ==/ /==/ /__/ // /==/ // /=/ /=/ // /==/ /__\/ ==// ==____/__// ==_____,´/ /==\// ==______/\ ==_\/ ==_\/\_\/ ==_____/,´ /==\_\/==_____\/ _____\,´

================================ Introduction ================================

   Note: This document is best viewed on a 80-column VGA terminal.

The retrofire project began as a shamelessly nostalgic effort to explore the state of graphics programming as it was in the mid-to-late 90s in the gamedev and demoscene circles of the era, before the proliferation of hardware 3D ac- celeration. More recently, as a result of the author's frustration when debug- ging the earlier versions, it has grown into an experiment on using the Rust type system to prevent several types of bugs common in graphics programming that might normally manifest as graphical glitches or runtime panics at best.

================================= Philosophy =================================

Keeping with the do-it-yourself mentality of the demoscene and the 90s state of software dev in general, retrofire aims to have the bare minimum number of external dependencies. The current number of required dependencies is zero.

On the other hand, retrofire also aims to utilize the bare minimum amount of unsafe code, and only if shown to have a measurable effect on performance by a profiler. The current number of unsafe lines of code in retrofire is zero.

A third aim of this project, again in the demoscene spirit, is to function on puny hardware with few or no operating system services required. To that end, all core functionality only requires alloc, and components requiring std are behind optional features or split into separate crates. Support for custom allocators is planned in order to make alloc optional as well.

================================== Features ==================================

Done:

• Software 3D rendering pipeline with a subpixel-precise rasterizer
• Trait-based interpolation of arbitrary vertex attributes
• User-definable vertex and fragment shaders, written in Rust
• Type-tagged vector and color spaces and bases
• Type-tagged affine transforms and projections
• Perspective-correct texture mapping
• Triangle mesh data structure and a library of shapes
• Fully customizable rasterization stage
• Collecting rendering performance data
• Reading and writing pnm image files
• Reading and writing Wavefront .obj files
• Cubic Bezier curves and splines
• Simple random number generation and distributions
• Frontend for wasm and minifb

In progress:

= Sprite and text primitives = Simple bitmap font support = Spherical, cube, etc UV mapping = Procedural noise generation

= Frontends for sdl2, softbuffer, ncurses

Planned:

• Material support
• Different camera types
• Basic scene graph
• Hierarchical transforms
• Cube mapping and skyboxes
• Mipmapping and mipmap generation
• More procedural generation
• Basic animation and sequencing
• Particle simulations
• Support for more file types

================================ Organization ================================

retrofire is split into several packages:

• core: math, renderer, utilities; no-std compatible
• front: frontends for writing simple graphical applications
• geom: geometric shapes, mesh builders, model loading
• demos: binaries showcasing retrofire features

================================ Dependencies ================================

The minimum supported Rust version is the current stable, at least for now.

The core package only requires alloc and has no non-optional external dependencies. However, because no_std lacks most floating-point functions, the package is not fully functional unless either the std, libm, or mm feature is enabled. Activating std additionally enables APIs that do I/O.

The front package can be used to write simple games and demos. It contains simple window abstractions, one using the minifb crate and the other running in the browser via WebAssembly.

The geom package has no external dependencies. It only requires alloc; activating the optional feature std enables APIs doing I/O.

The demos package contains sample applications using front to exhibit various features of retrofire.

================================== License ===================================

Copyright 2020-2024 Johannes Dahlström. retrofire is licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submit- ted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.