Crate processing

Expand description

§processing-rs

processing-rs is a crate that is designed to make graphics programming as easy in Rust as it is in the popular Processing environment, without sacrificing performance or easy access to other parts of your system. It achieves this by essentially being a convienence layer built on top of glium and glutin/glfw (either can be chosen depending on your preference). It mostly mimics Processing, but diverges in a few areas to either accomodate Rust’s and glium’s safety features or to incorporate some ideas from libCinder and openFrameworks. For instance, there are now setup and draw loops in processing-rs. This is intended to enable a more flexible and modular workflow for graphics. In addition, since processing-rs is essentialy a thin wrapper, you can use glium, glutin, and raw OpenGL calls as you see fit. They should usually blend nicely with the processing-rs calls and allow for more opportunities to create fun and interesting displays.

Typical usage follows a common pattern:

1. Open a screen with processing::Screen::new(). This will return a 
   Screen struct, which is the central struct for coordinating draw calls,
   managing shaders, and maintaining render state.

2. Pre-define a few shapes. This allows caching shape data on the CPU and GPU,
   giving some marginal speed boosts and allowing the possibility to store
   shapes in collections, such as Vectors. All shapes (Rect, Ellipse, etc.) in
   this crate implement the Shape trait, which defines a common interface for
   entities that can be drawn to a screen in a meaningful way.

3. Draw the shapes to the screen with screen.draw(). This is also where you will
   want to use commands like screen.fill() and screen.stroke() to change the
   colors of objects.

4. For any pattern drawn, you will also need to flip the framebuffers, so that
   the pattern is synchronized with your monitor. This is achieved by
   screen.reveal().

5. Use commands like screen.key_press() to get input from users, if needed.

6. Have fun! :-)

Basically, all commands follow the same call conventions as those from Processing, so you can also use the Processing reference as additional documentation and for some basic examples of what you can do.

Additionally, processing-rs has a number of features that are intended to make it useful for psychological research, including color vision, material perception, motion, etc. For example, it tries to enable a 10-bit framebuffer if possible, for increased color fidelity, which is important in most color vision research. Besides this, it also aims to make sure that frame draws are as precisely synchronized with the monitor refresh as possible. This works better with glutin than with glfw, and on Mac, a few Objective-C functions are called to give the program elevated status for resources and to disable AppNap and such things while the program is running (code taken from the helpful PsychToolbox). In addition, when the crate is built on a Mac, it will also compile a C library (called libpri, short for “priority library”) that asks the operating system for some additional priorities. The crate will automatically call the library throguh the C FFI at screen initialization. It shouldn’t interfere with normal operation of the operating system, so you can probably just accept the default behaviour. With all of this, combined with a change to a setting on Mac that allows one to quit Finder, one can achieve slightly better synchronization than PsychToolbox on Mac, satisfying Psychtoolbox’s requirements for good frame synchronization. However, this has only been tested on a Mac laptop with 10.13.3 and an Intel graphics card.

Re-exports§

pub use constants::Key;
pub use constants::MouseButton;
pub use image::load_image;

Modules§

backend: The backend module allows one to link between glium and the OpenGL context..
buffer: A buffer is a memory location accessible to the video card.
color
constants
debug
draw_parameters: Describes miscellaneous parameters to be used when drawing.
environment
errors
framebuffer: Framebuffers allow you to customize the color, depth and stencil buffers you will draw on.
framebuffers
image
index: In order to draw, you need to provide a way for the video card to know how to link primitives together.
input
pixel_buffer: DEPRECATED. Moved to the texture module.
program: Items related to creating an OpenGL program.
rendering
screen
shaders
shapes
texture: A texture is an image loaded in video memory, which can be sampled in your shaders.
textures
transform
uniforms: A uniform is a global variable in your program. In order to draw something, you will need to give glium the values of all your uniforms. Objects that implement the Uniform trait are here to do that.
vertex: Contains everything related to vertex sources.

Macros§

assert_no_gl_error: Calls the assert_no_error method on a glium::Display instance with file and line number information.
create_uniforms: This macro rolls your custom uniforms for your custom shader into the uniform format expected by glium. It makes things more convienent, because it will add the current MVP transformation matrix that is shared across all shaders for consistent rendering to the screen. If your shader will be rendering 2-dimensional or 3-dimensional shapes to the screen, you will probably want to make use of this matrix, which will be available as uniform mat4 MVP in your custom shader.
implement_buffer_content: Implements the glium::buffer::Content trait for the given type.
implement_uniform_block: Implements the glium::uniforms::UniformBlock trait for the given type.
implement_vertex: Implements the glium::vertex::Vertex trait for the given type.
program: Builds a program depending on the GLSL version supported by the backend.
uniform: Returns an implementation-defined type which implements the Uniform trait.

Structs§

Blend: Blend effect that the GPU will use for blending.
BlitTarget: Area of a surface in pixels. Similar to a Rect except that dimensions can be negative.
DFBFDVertex
Depth: Represents the depth parameters of a draw command.
Display: A GL context combined with a facade for drawing upon.
DrawParameters: Represents the parameters to use when drawing.
FBtexs
Frame: Implementation of Surface, targeting the default framebuffer.
GLmatStruct
HeadlessRenderer: A headless glutin context.
IncompatibleOpenGl: Returned during Context creation if the OpenGL implementation is too old.
IndexBuffer: A list of indices loaded in the graphics card’s memory.
LinearSyncFence: Prototype for a SyncFence.
Program: A combination of shaders linked together.
Rect: Area of a surface in pixels.
Screen: This is essentially the central struct of processing-rs. It not only contains the the display window returned by glutin, but it also has a number of elements that maintain the render state and that manage a framebuffer for increased color fidelity. Its internal elements are mostly private and an instance of a Screen struct should be interacted with through the public functions provided in other modules, such as the shapes, environment, or textures modules.
SyncFence: Provides a way to wait for a server-side operation to be finished.
Texture2d: A two-dimensional texture containing floating-point data.
Version: Describes a version.
VertexBuffer: A list of vertices loaded in the graphics card’s memory.

Enums§

Api: Describes an OpenGL-related API.
BackfaceCullingMode: Describes how triangles should be filtered before the fragment processing. Backface culling is purely an optimization. If you don’t know what this does, just use CullingDisabled.
BlendingFunction: Function that the GPU will use for blending.
DepthTest: The function that the GPU will use to determine whether to write over an existing pixel on the target.
DrawError: Error that can happen while drawing.
Handle: Handle to a shader or a program.
LinearBlendingFactor: Indicates which value to multiply each component with.
PolygonMode: Defines how the device should render polygons.
Profile: Describes the OpenGL context profile.
ProgramCreationError: Error that can be triggered when creating a Program.
RawUniformValue: A raw value of a uniform. “Raw” means that it’s passed directly with glUniform. Textures for example are just passed as integers.
Smooth: Specifies a hint for the smoothing.
StencilOperation: Specificies which operation the GPU will do depending on the result of the stencil test.
StencilTest: Specifies which comparison the GPU will do to determine whether a sample passes the stencil test. The general equation is (ref & mask) CMP (stencil & mask), where ref is the reference value (stencil_reference_value_clockwise or stencil_reference_value_counter_clockwise), CMP is the comparison chosen, and stencil is the current value in the stencil buffer.
SwapBuffersError: Error that can happen when swapping buffers.

Traits§

CapabilitiesSource: Trait for objects that describe the capabilities of an OpenGL backend.
GlObject: Trait for objects that are OpenGL objects.
Surface: Object that can be drawn upon.
Vertex: Trait for structures that represent a vertex.

Functions§

get_supported_glsl_version: Given an API version, this function returns the GLSL version that the implementation is required to support.

Type Aliases§

VertexFormat: Describes the layout of each vertex in a vertex buffer.

Crate processingCopy item path