Crate radiant_rs [−] [src]
Rust sprite rendering engine with a friendly API, wait-free send+sync drawing targets 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 --release --example demo_blobs
to run demo_blobs.rs
Basic rendering
- Create a display with
Display::builder()
. This represents the window/screen. - Create a renderer with
Renderer::new()
. It is used to draw to rendertargets like the display. - Grab a context from the renderer using the
context()
method. It is required for resource loading. - Load sprites or fonts using e.g.
Font::from_file()
orSprite::from_file()
. - Create as many drawing layers as you need using
Layer::new()
. - Draw to the layer using the
Font::write()
orSprite::draw()
methods. - Prepare a new frame and clear it using
Display::clear_frame()
. (If you don't want to clear, useDisplay::prepare_frame()
instead.) - Draw the contents of your layers to the display using
Renderer::draw_layer()
. - Make the frame visible via
Display::swap_frame()
. - 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, 1); }); //... maybe draw here with only effect 1? ... }); //... or here without any postprocessor? ... });
Drawing from multiple threads
- Wrap fonts, sprites, and layers or scenes in
Arc
s. - Clone the
Arc
s for each thread that needs their contents. The rendercontext can be cloned directly. - Move the clones into the thread.
- 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).
- Perform steps 7-10 from the above list in the thread that created the
Renderer
; both it andDisplay
do not implementSend
.
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. These are normal glsl shaders. To simplify access to the default
sampler (which might be a sampler2DArray or sampler2D, depending on what is drawn) a tiny wrapper is injected into the
source. The wrapper provides sheet*()
functions similar to glsl's texture*()
functions.
This only applies to the default sampler. It is possible to add custom uniforms, including samplers, to your shader
that would be sampled using the texture*()
functions.
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.
To access the default sampler, the following wrappers are provided:
vec2 sheetSize()
Retrieves the dimensions of the texture.vec4 sheet(in vec2 texture_coords)
Retrieves texels from the texture.vec4 sheetComponent(in vec2 texture_coords, in uint component)
Samples a specific sprite component instead of the default one set byRenderer::draw_layer()
.vec4 sheetOffset(in vec2 texture_coords, in ivec2 offset)
Like textureOffset().
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 |
math |
Mostly optional math structs. |
postprocessors |
A set of predefined postprocessors for use with |
support |
Support structures returned by various methods. Usually not required to be created manually. |
utils |
Optional utility features. These may eventually be moved into the example code or a separate library. |
Structs
BlendMode |
A blendmode for use with |
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. |
Font |
A font used for writing on a |
Input |
Basic keyboard and mouse support. |
Layer |
A drawing surface for text and sprites that implements send+sync and is wait-free for drawing operations. |
Monitor |
An individual monitor, returned from |
Point2 |
A 2-dimensional point. |
Program |
A shader program and its uniforms. |
Rect |
A rectangle. |
RenderContext |
A thread-safe render-context. |
Renderer |
A renderer is used to render |
Sprite |
A sprite used for drawing on a |
Texture |
A texture to draw or draw to. |
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
AsRenderTarget |
A target for rendering. |
AsUniform |
A value usable as a uniform. |
Postprocessor |
A custom postprocessor. |
Type Definitions
Result |
Radiant result. |