[−][src]Crate screen_13

Screen 13 is an easy-to-use 2D/3D rendering engine in the spirit of QBasic.

Screen 13 supports DirectX 11/12, Metal, Vulkan and OpenGL (ES3, WebGL2).

This crate 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)
Pixel formats such as 24bpp RGB (optional)
Vertex formats such as [POSITION, TEXCOORD0] (optional)
Common file formats (.gltf, .png, etc..)
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.

Usage

First, add this to your Cargo.toml:

[dependencies]
screen_13 = "0.1"

Next, pick a shared reference type. We'll use std::rc::Rc:

use screen_13::prelude_rc::*;

Then, for a console program:

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

Or, for a windowed program:

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

struct Foo;

impl Screen<RcK> for Foo {
    fn render(&self, gpu: &Gpu, dims: Extent) -> Render {
        let mut frame = gpu.render(dims);
        frame.clear().with(MAGENTA).record(); // <-- 🔥
        frame
    }

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

Screen 13 Concepts

Screen 13 offers 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

Shared References

A Gpu's resources, such as bitmaps and models, use either std::sync::Arc or std::rc::Rc types to track their internal states.

Screen 13 offers the following preludes to easily specifiy the shared reference type:

Scenario	Recommended `use`	Screen 13 Types
Single-Threaded Program	`screen_13::prelude_rc::*;`	`Gpu`, `Render`, etc...
Multi-Threaded Program	`screen_13::prelude_arc::*;`	`Gpu`, `Render`, etc...
Both or Choose at Runtime	`screen_13::prelude_all::*;`	`Gpu<P>`, `Render<P>`, etc...

NOTE: The generic types require ptr::ArcK or ptr::RcK type parameters.

`.pak` File 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 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	Mathematics types and functions, mostly based on glam-rs.
pak	Types which support the `.pak` file format and general serialization functionality.
prelude	Things, particularly traits, which are used in almost every single Screen 13 program.
prelude_all	Like `prelude`, but contains all public exports.
prelude_arc	Like `prelude_all`, but specialized for `std::sync::Arc`-backed `Gpu` instances.
prelude_rc	Like `prelude_all`, but specialized for `std::rc::Rc`-backed `Gpu` instances.
ptr	Shared reference (`Arc` and `Rc`) implementation based on archery.

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.
Icon	A small picture which represents a program, to be used in different ways on each platform.
Program	Program specifies the information required 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.

Type Definitions

DynScreen	Helpful alias of `Box<dyn Screen>`; can be used to hold an instance of any `Screen`.
RenderReturn	Alias of either `Render` or `Vec<Render>`, used by `Screen::render()`.