Crate screen_13

An easy-to-use 2D/3D rendering engine in the spirit of QBasic.

This crate provides image rendering types and functions. It is intended to be integrated into other libraries and programs which require very high performance graphics code, but which do not want to know anything about the underlying graphics hardware or programming interfaces.

Before starting you should be familar with these topics:

• The Rust Programming Language (beginner level)
• Common file formats (.gltf, .png, etc..)
• Pixel formats such as 24bpp RGB (optional)
• Vertex formats such as [POSITION, TEXCOORD0] (optional)
• Some notion about what a GPU might be

With almost striking exception, which appear in "NOTE:" sections only, no further graphics API-specific concepts need to be introduced in order to master Screen 13 and implement exceptionally fast graphics code.

TL;DR: Screen 13 adds state-of-the-art Vulkan/Metal/DirectX/GL to your code, easily.

Usage

First, add this to your Cargo.toml:

[dependencies]
screen_13 = "0.1"

Next, for a console program:

/// Creates a 128x128 pixel jpeg file as `output.jpg`.
fn main() {
    let gpu = screen_13::Gpu::offscreen();
    let render = gpu.render((128u32, 128u32));
    render.clear().record();
    render.encode().record("output.jpg");
}

Or, for a windowed program:

use screen_13::prelude_all::*;

/// Paints a magenta window at 60 glorious frames per second.
fn main() {
    let engine = Engine::default();
    engine.run(Box::new(FooProgram))
}

struct FooProgram;

impl Screen for FooProgram {
    fn render(&self, gpu: &Gpu, dims: Extent) -> Render {
        let frame = gpu.render(dims);
        frame.clear().with_value(MAGENTA).record();
        frame
    }

    fn update(self: Box<Self>, gpu: &Gpu, dims: &Input) -> DynScreen {
        // Never exits
        self
    }
}

Screen 13 Concepts

Screen 13 offers libraries and applications two general modes of operation, both of which focus on the Gpu type:

• Gpu::offscreen(): For headless rendering, such as from a console program
• The Screen trait: Provides a fullscreen graphics mode or paints a window

NOTE: Resources loaded or read from a Gpu created in headless or screen modes cannot be used with other instances, including of the same mode. This is a limitation only because the code to share the resources properly has not be started yet.

Screen 13 PAK Format

Although data may be loaded at runtime, the highest performance can be achieved by pre-baking data at design-time and simply reading it at runtime.

It is recommended to use the .pak file format, which includes optional 10:1-typical compression, whenever possible. See the main README for more on this philosphy and the module level documentation for more details on how to use this system with existing files and assets.

Modules

camera	Contains digital representations of traditional film cameras.
color	Contains color types and functions.
fx	Contains pre-made implementations of Screen 13 traits.
gpu	Contains the heart and soul of Screen 13.
input	Window-based inputs captured during event loop processing.
math	Mathmatics types and functions, mostly based on glam-rs.
pak	Note about keys: When baking assets using the .toml format you will not need to use the .toml extension in order to load and use the assets at runtime. For instance, when trying to read a model packed at models/thing.toml you might: gpu.read_model("models/thing")
prelude	Things, particularly traits, which are used in almost every single Screen 13 program.
prelude_all	Like prelude, but contains all public exports.

Structs

Engine	Pumps an operating system event loop in order to refresh a Gpu-created image at the refresh rate of the monitor. Requires a DynScreen instance to render.
Program	Program is the required information to start an event loop, and therefore an Engine.

Traits

Screen

A window-painting and user input handling type.

Functions

root	Gets the filesystem root for a given program name and author. The returned path is a good place to store program configuration and data on a per-user basis.

Type Definitions

DynScreen

Helpful alias of Box<dyn Screen>; can be used to hold an instance of any Screen.