Crate processing

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

BlitTarget	Area of a surface in pixels. Similar to a Rect except that dimensions can be negative.
DFBFDVertex
FBtexs
Frame	Implementation of Surface, targeting the default framebuffer.
GLmatStruct
IncompatibleOpenGl	Returned during Context creation if the OpenGL implementation is too old.
LinearSyncFence	Prototype for a SyncFence.
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.
Version	Describes a version.

Enums

Api	Describes an OpenGL-related API.
DrawError	Error that can happen while drawing.
Handle	Handle to a shader or a program.
Profile	Describes the OpenGL context profile.
RawUniformValue	A raw value of a uniform. "Raw" means that it's passed directly with glUniform. Textures for example are just passed as integers.
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.

Functions

get_supported_glsl_version

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