Crate radiant_rs

Thread-safe Rust sprite rendering engine with a friendly API and custom shader support.

To view the reference, scroll down or collapse this block using the [-] to the left.

This is work-in-progress. Parts of the API are incomplete and will likely still change somewhat.

Examples

The examples folder contains multiple small examples. They can be run via cargo run --example <example name>, e.g.

cargo run --example demo_blobs to run demo_blobs.rs

Basic rendering

1. Create a display with Display::new(). This represents the window/screen.
2. Create a renderer with Renderer::new(). It is used to draw to rendertargets like the display.
3. Grab a context from the renderer using the context() method. It is required for resource loading.
4. Load sprites or fonts using e.g. Font::from_file() or Sprite::from_file().
5. Create as many drawing layers as you need using Layer::new().
6. Draw to the layer using the Font::write() or Sprite::draw() methods.
7. Prepare a new frame and clear it using Display::clear_frame(). (If you don't want to clear, use Display::prepare_frame() instead.)
8. Draw the contents of your layers to the display using Renderer::draw_layer().
9. Make the frame visible via Display::swap_frame().
10. Consider clearing the layer and goto 6. Or maybe simply change some layer properties and redraw it starting a step 7.

Draw to texture/postprocess

Postprocessors are custom effects that may be as simple as a single shader program or combine multiple shaders and textures into a single output.

The renderer has a method Renderer::render_to() that accepts a texture and a closure. Anything drawn within the closure will be rendered to the texture.

Likewise, use Renderer::postprocess() to render using a postprocessor.

These methods can be combined/nested as shown here:

renderer.render_to(&surface, || {
    renderer.postprocess(&effect1, &effect1_arguments, || {
        renderer.postprocess(&effect2, &effect2_arguments, || {
            //...
            renderer.draw_layer(&layer);
        });
        //... maybe draw here with only effect 1? ...
    });
    //... or here without any postprocessor? ...
});

Drawing from multiple threads

1. Wrap fonts, sprites, and layers or scenes in Arcs.
2. Clone the Arcs for each thread that needs their contents. The rendercontext can be cloned directly.
3. Move the clones into the thread.
4. Draw onto your layers, load sprites etc. from any thread(s). Layers are non-blocking for drawing operations, blocking for other manipulations (e.g. matrix modification).
5. Perform steps 7-10 from the above list in the thread that created the Renderer; both it and Display do not implement Send.

Sprite-sheets

Currently sprite-sheets are required to be sheets of one or more either horizontally or vertically aligned sprite frames. Each frame can have multiple components aligned orthogonally to the frames. Components could be the sprite's color image, a light or distortion map for the shader etc.

Filenames are required to express the sprite format, e.g. battery_lightmapped_128x128x15x2 would be 15 frames of a 128x128 sprite using two components. This is a scaled version of how it could look. The Color component is in the top row, a lightmap component in the bottom row:

Custom shaders

Radiant supports the use of custom fragment shaders. When you create a program, a tiny wrapper is injected into the source to make it compatible with the different internal shader programs used by the library. Instead of texture() you would then use sheet() to retrieve data from the current texture, etc. (This is required as the texture might come from a sampler or sampler array.) It is possible to add custom uniforms, including textures, to your shader. The postprocessing example uses a shader that takes 5 samplers and combines them.

Available default inputs:

• uniform mat4 u_view The view matrix if applicable, otherwise the identity.
• uniform mat4 u_model The model matrix if applicable, otherwise the identity.
• in vec2 v_tex_coords Texture coordinates.
• in vec4 v_color Color multiplier. For layers this is sprite color * layer color.

Wrappers:

• vec2 sheetSize() Retrieves the dimensions of the texture. Replaces textureSize().
• vec4 sheet(in vec2 texture_coords) Retrieves texels from the texture. Replaces texture()
• !todo add other texture*.

Example: (This is the default shader used by radiant.)

#version 140

in vec2 v_tex_coords;
in vec4 v_color;

out vec4 f_color;

void main() {
    f_color = sheet(v_tex_coords) * v_color;
}

Modules

blendmodes	A set of predefined blendmodes for use with Layer::set_blendmode().
postprocessors	A set of predefined postprocessors for use with Renderer::postprocess().
scene	[ Deprecated ] Optional scene abstraction.
utils	Optional utility features. These may eventually be moved into the example code or a separate library.

Structs

Angle	An Angle between -PI and PI.
BlendMode	A blendmode for use with Layer::set_blendmode(). See blendmodes for a list of predefined modes.
Color	A color value consisting of four floating point values for the color channels red, green, blue and alpha.
Display	A target to render to, e.g. a window or full screen.
DisplayInfo	A struct describing a Display to be created.
Font	A font used for writing on a Layer.
FontInfo	A struct used to filter the result of Font::query_specific() or to describe a Font to be created from a system font via Font::from_info().
Input	Basic keyboard and mouse support.
InputDownIterator	An iterator over all keys all buttons currently pressed.
InputIterator	An iterator over all keys and buttons.
InputUpIterator	An iterator over all keys all buttons currently not pressed.
Layer	A non-blocking, thread-safe drawing surface.
Mat4	A 4x4 matrix.
Monitor	An individual monitor, returned from Display::monitors().
Program	A shader program and its uniforms.
Rect	A rectangle.
RenderContext	A thread-safe render-context.
Renderer	A renderer is used to render Layers or Scenes to the Display.
Sprite	A sprite used for drawing on a Layer.
Texture	A texture to draw or draw to.
TextureInfo	A struct used to describe a Texture to be created via Texture::from_info().
Vec2	A 2-dimensional vector.
Vec3	A 3-dimensional vector.

Enums

Error	Radiant errors.
InputId	Input key and mousebutton ids
InputState	The current state of a key or mousebutton.
RenderTarget	An enum of render target type instances.
TextureFilter	Texture minify- or magnify filtering function.
TextureFormat	Internal texture format. Note that the shader will always see a floating point representation. U[n]* will have their minimum value mapped to 0.0 and their maximum to 1.0.
TextureWrap	Texture wrapping function.
Uniform	A uniform value.

Traits

AsUniform	A value usable as a uniform.
Postprocessor	A custom postprocessor.
VecType	Trait for values that can be converted to a vector.

Type Definitions

Point2	A 2-dimensional point.
Point3	A 3-dimensional point.
Result	Radiant result.