Crate radiant_rs [−] [src]
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
- Create a display with
Display::new()
. 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); }); //... 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. 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. ReplacestextureSize()
.vec4 sheet(in vec2 texture_coords)
Retrieves texels from the texture. Replacestexture()
- !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 |
postprocessors |
A set of predefined postprocessors for use with |
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 |
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 |
Font |
A font used for writing on a |
FontInfo |
A struct used to filter the result of |
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 |
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. |
TextureInfo |
A struct used to describe a |
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. |