Struct Screen

pub struct Screen<'a> {
    pub matrices: GLmatStruct,
    /* private fields */
}

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.

Fields

matrices: GLmatStruct

Implementations

impl<'a> Screen<'a>

pub fn new( width: u32, height: u32, fullscreen: bool, preserve_aspect_ratio: bool, vsync: bool, ) -> Result<Screen<'a>, ProcessingErr>

Create a new Screen struct with a given width and height. Also, specify if the Screen should be fullscreen, if it should preserve aspect ratio on wide monitors, and if it should be synchronize to the refresh rate of the monitor (this should always be true, except in rare circumstances when you need really high draw rates, such as when doing intense raymarching in a fragment shader).

It is necessary to call this function before everything else. It’s what gets the whole show going. Once you have a Screen, you can then create shapes, load textures, draw, check for user input, etc.

Screen setup tries to choose a number of glutin and glium defaults that will satisfy most users, especially those that want speed but still have a visually pleasing display of shapes with good color fidelity, if possible.

pub fn new_headless( width: u32, height: u32, preserve_aspect_ratio: bool, ) -> Result<Screen<'a>, ProcessingErr>

This creates a “headless” rendering screen. It’s basically the same as a screen except that you won’t see a window. This is useful when you need to quickly render some kind of image, but you don’t want to user to see all of the drawing that leads up to the final image. In other words, you could draw in the headless window, save the result, and load it as a texture to be displayed in a main display window. One circumstance where I used this was to have a GLSL fragment shader pathtrace a scene and then have the result displayed in another window. For various reasons, I couldn’t have users see the scene being progressively created, so the “headless” rendering screen effectively hid it.

This takes width and height as parameters, as well as whether or not aspect ratio should be preserved. Fullscreen makes no sense for a “headless” rendering window, and neither does frame synchronization, since it never displays anything on the monitor. Otherwise, you should also see the documentation for the main Screen struct.

pub fn reveal(&mut self) -> Result<(), ProcessingErr>

Once you have finished drawing a number of shapes to the screen, you will need to call screen.reveal() for the result to be viewable on the monitor. This is because processing-rs uses double-buffering, whereby all of the drawing happens on a separate, hidden buffer and once that is done, it is transferred to a viewable, monitor buffer. This is standard practice in graphics programming, since it makes drawing faster and reduces screen tearing.

pub fn reveal_with_events(&mut self) -> Result<Vec<Event>, ProcessingErr>

This function works exactly the same as screen.reveal(), except that it also outputs a Vector of raw glutin events, if you need that for any reason. I needed it once, so I leave it here.

pub fn end_drawing(self)

This will safely close a window and drop the Screen struct associated with it. Currently unimplemented, so for now, to close a window, you have to quit the running program.

impl<'a> Screen<'a>

pub fn load_frag_shader<U: Uniforms>( &mut self, frag_filename: &str, uniforms: U, ) -> Result<ShaderInfo<U>, ProcessingErr>

Load your custom fragment shader and the initial values of the uniforms that go with it. You will get a ShaderInfo struct in return, through which you can update the uniform values and which can be used to tell processing-rs to use your custom shader, instead of the standard ones it provides. The ShaderInfo struct that you receive should be the input to screen.shader(), which allows you to use the custom shader.

This function provides an additional convienence, in that if your shader contains a line like #include <auxiliary.frag> it will process that and load the named file into that exact location of your fragment shader. This allows you to keep things a bit more modular and managable. Please note though, it will do this no matter where you put the line, so remain aware. You probably only want to use this convienence at outermost scope, but the choice is yours.

pub fn shader<U: Uniforms>(&mut self, which_shader: &ShaderInfo<U>)

Tell processing-rs to use your custom shader instead of one of the standards it provides. This only accepts ShaderInfo structs, which are output by screen.load_frag_shader() and screen.load_shaders().

pub fn reset_shader(&mut self)

Tell processing-rs to stop using any custom shaders and to return to the default shaders.

impl<'a> Screen<'a>

pub fn background(&mut self, r: f32, g: f32, b: f32, a: f32)

Change the background color of the window. It takes four f32’s. If color mode is equal to “RGB”, then it takes one for red, one for green, one for blue, and one for alpha. If color mode is equal to “HSB”, then the arguments are reinterpreted as one for hue, one for saturation, one for brightness, and one for alpha.

pub fn color_mode(&mut self, mode: &str)

Change the color mode to “RGB” or “HSB”. This causes the arguments to fill(), stroke(), background(), and color() to be reinterpreted in the respective color system.

pub fn fill(&mut self, r: &[f32], g: &[f32], b: &[f32], a: &[f32])

Change the color used to fill in the space bounded by shapes. For example, setting fill to 1, 1, 1, 1 in “RGB” mode will cause the interior of a rectangle to be white. The arguments to fill are actually slices of f32’s. This is meant to be a convenience when you know that you want to draw many of the same kind of shape, but each with a different stroke color. Calling this function will also undo the effect of fill_off().

pub fn fill_off(&mut self)

This disables filling in of shapes, such that only their outline is drawn. It essentially acts as if the interior of a shape was transparent. Calling fill() or fill_on() will re-enable filling in of shapes.

pub fn stroke_off(&mut self)

This disables the drawing of edges of shapes, such that only their interior is drawn. It essentially acts as if the shape was one single color, with the edge sharing that color. It’s a little easier to understand with some examples (see the Processing reference). Calling stroke() or stroke_on() will re-enable the drawing of edges of shapes.

pub fn fill_on(&mut self)

This undoes the effect of fill_off(), so that the interiors of shapes are drawn again.

pub fn stroke_on(&mut self)

This undoes the effect of stroke_off(), so that the edges of shapes are drawn again.

pub fn stroke(&mut self, r: &[f32], g: &[f32], b: &[f32], a: &[f32])

Change the color used to drawn the edges of shapes. For example, setting stroke to 1, 1, 1, 1 in “RGB” mode will cause the edge of a rectangle to be white. The arguments to stroke are actually slices of f32’s. This is meant to be a convenience when you know that you want to draw many of the same kind of shape, but each with a different edge color. Calling this function will also undo the effect of stroke_off().

impl<'a> Screen<'a>

pub fn draw<S: Shape>(&mut self, shape: &S) -> Result<(), ProcessingErr>

Take a given shape and draw it onto the screen. Since the shape’s properties were precomputed and its buffers were already uploaded to the GPU, drawing many shapes should be faster than in a standard Processing environment.

pub fn draw_mould<S: Shape, U: Uniforms>( &mut self, mould: &Mould<U, S>, ) -> Result<(), ProcessingErr>

The same as screen.draw(), except now a Mould will be drawn to the screen. A Mould is just a shape that has been paired with a given shader which alters how it is typically drawn to the screen. This allows one to have a shader affect only one object instead of the whole drawing process. The concept is borrowed from libCinder.

pub fn stroke_weight(&mut self, new_weight: f32)

pub fn ellipse_mode(&mut self, mode: &str)

pub fn rect_mode(&mut self, mode: &str)

pub fn shape_mode(&mut self, mode: &str)

impl<'a> Screen<'a>

pub fn texture<P, S, C>( &mut self, img: &ImageBuffer<P, C>, ) -> Result<(Texture2d, f64, f64), ProcessingErr>

where P: Pixel<Subpixel = S> + 'static, S: Primitive + 'static + ToClientFormat + PixelValue, C: DerefMut<Target = [P::Subpixel]>,

Take an image (in particular anything that implements image::ImageBuffer, such as the image::ImageRgba returned by processing.load_image()) and upload it to the GPU as a texture for later use. In return, you will get a reference to the texture, its width in normalized screen coordinates (i.e., [0,1]), and its height in normalized screen coordinates.

pub fn empty_texture( &self, w: u32, h: u32, ) -> Result<(Texture2d, f64, f64), ProcessingErr>

Create an empty texture on the GPU. The output is the same as screen.texture(), so see that for more info. This function is useful in circumstances where you want to draw something onto a texture and use that for a later purpose, rather than load an external image. See the framebuffers module for more info.

pub fn texture_from_data<P: PixelValue>( &self, data: Vec<Vec<P>>, ) -> Result<(Texture2d, f64, f64), ProcessingErr>

Rather than create a texture from an external image or creating an empty texture and drawing to it, you can create a texture from arbitrary data. It expects a Vec of Vec (mimicing the layout of an image) that contains anything that implements glium::texture::PixelValue.

pub fn texture_array<T: Clone + 'a + PixelValue>( &mut self, images: Vec<RawImage2d<'_, T>>, ) -> Result<Texture2dArray, ProcessingErr>

A texture array is a uniform sampler on the GPU that will place many 2-dimensional textures (i.e., pre-processed RGBA images) in one part of memory. /// For the user, this means that you can upload a movie for instance and step through the frames in your shader via an overloaded call to texture(). Please see OpenGL tutorials and documentation for more info. This function returns a glium::texture::Texture2dArray, which is accepted by the create_uniforms{} macro.

pub fn texture_wrap(&mut self, wrap: &str)

When you sample outside the boundaries of a texture, should it wrap around and repeat (“REPEAT”, the default) or should it clamp (“CLAMP”) at the edge. See the official Processing reference for more info and examples.

impl<'a> Screen<'a>

pub fn framebuffer( &self, fbtex: &'a Texture2d, ) -> Result<SimpleFrameBuffer<'_>, ProcessingErr>

Create a new framebuffer from a texture. This is necessary if you want to draw to a texture, which is useful in combination with shaders that perform some post-processing on the texture. In the case that you will also use a shader for post-processing, you will also need to use a Mould.

pub fn clear_framebuffer( &self, framebuffer: &mut SimpleFrameBuffer<'_>, r: f32, g: f32, b: f32, a: f32, )

Erase the framebuffer and set it to the given color.

pub fn draw_onto_framebuffer<S: Shape>( &self, shape: &S, framebuffer: &mut SimpleFrameBuffer<'_>, ) -> Result<(), ProcessingErr>

Draw the given shape onto the given framebuffer.

pub fn draw_mould_onto_framebuffer<S: Shape, U: Uniforms>( &self, mould: &Mould<U, S>, framebuffer: &mut SimpleFrameBuffer<'_>, ) -> Result<(), ProcessingErr>

Draw a Mould (i.e., a shape plus a custom shader) onto the given framebuffer.

impl<'a> Screen<'a>

pub fn apply_matrix( &mut self, n00: f32, n01: f32, n02: f32, n03: f32, n10: f32, n11: f32, n12: f32, n13: f32, n20: f32, n21: f32, n22: f32, n23: f32, n30: f32, n31: f32, n32: f32, n33: f32, )

Pre-multiply the current MVP transformation matrix with a matrix formed from the given values.

pub fn pop_matrix(&mut self)

Remove the current MVP transformation matrix from the stack and use the most recently used one instead.

pub fn push_matrix(&mut self)

Push the current MVP transformation matrix onto the stack, so that it can be saved for later. Useful for when you want to temporarily apply some rotation or translation to a single object and don’t want to disturb the rest of the scene.

pub fn reset_matrix(&mut self)

Remove the current MVP transfomation matrix and set it to the standard 4x4 identity matrix.

pub fn rotate(&mut self, angle: f32, x: f32, y: f32, z: f32)

Pre-multiply the current MVP transformation matrix by a rotation matrix which is derived from a rotation angle about a vector in the direction (x, y, z).

pub fn rotate_x(&mut self, angle: f32)

Apply a rotation matrix for a given angle around the x-axis to the current MVP transformation matrix.

pub fn rotate_y(&mut self, angle: f32)

Apply a rotation matrix for a given angle around the y-axis to the current MVP transformation matrix.

pub fn rotate_z(&mut self, angle: f32)

Apply a rotation matrix for a given angle around the z-axis to the current MVP transformation matrix.

pub fn scale(&mut self, x: f32, y: f32, z: f32)

Scale the scene along the x-, y-, and z-axes by applying a matrix derived from these values to the current MVP transformation matrix.

pub fn shear_x(&mut self, angle: f32)

Derive a matrix that applies shear for a given angle the scene about the x-axis and apply it to the current MVP transformation matrix.

pub fn shear_y(&mut self, angle: f32)

Derive a matrix that applies shear for a given angle the scene about the y-axis and apply it to the current MVP transformation matrix.

pub fn translate(&mut self, x: f32, y: f32, z: f32)

Derive a translation matrix from the given (x, y, z) vector and apply it to the current MVP transformation matrix.

pub fn print_matrix(&self)

Print out the current MVP transformation matrix.

impl<'a> Screen<'a>

pub fn blend_mode(&mut self, mode: &str)

Change the way colors and alpha values are mixed to produce a final color value for a pixel on the screen. Possible values are “REPLACE”, “BLEND”, “ADD”, “SUBTRACT”, “LIGHTEST”, “DARKEST”, “EXCLUSION”, “MULTIPLY”, and “SCREEN”. They all follow the same conventions as Processing, so you should check the Processing reference for more info.

impl<'a> Screen<'a>

pub fn image_mode(&mut self, mode: &str)

Not really useful in processing-rs since you will typically draw a texture to the screen by attaching it to a Rect, rather than having a separate function just for drawing an image to the screen. Should probably be removed.

pub fn no_tint(&mut self)

Stop applying tint to a drawn image.

pub fn save(&self, filename: &str) -> Result<(), ProcessingErr>

Save the current state of the screen to an image. The format will be determined by the file extension.

impl<'a> Screen<'a>

pub fn reset_cursor(&mut self) -> Result<(), ProcessingErr>

Change the cursor back to the default that is used when a new Screen is made. This is operating system dependent, but is usually an arrow.

pub fn cursor(&mut self, cursor_type: &str) -> Result<(), ProcessingErr>

Change the cursor. Possible types are “HAND”, “ARROW”, “CROSS”, “MOVE”, “TEXT”, and “WAIT”, all following the convention of Processing. These will probably be changed to enums in the future.

pub fn focused(&mut self) -> bool

Test if this screen is the currently focused screen.

pub fn frame_count(&self) -> isize

How many frames have already been revealed.

pub fn get_frame_rate(&self) -> isize

What is the current framerate of the screen.

pub fn set_frame_rate(&mut self, f_rate: isize)

Change the framerate of the screen.

pub fn height(&self) -> u32

What is the height of the screen.

pub fn no_cursor(&mut self) -> Result<(), ProcessingErr>

Disable the cursor so that it cannot be seen.

pub fn no_smooth(&mut self)

Draw shapes without antialiasing, so that individual pixels can be more readily observed.

pub fn smooth(&mut self)

Draw shapes with antialiasing for a more pleasing visual appearence.

pub fn width(&self) -> u32

What is the width of the screen.

impl<'a> Screen<'a>

pub fn key_press<I: Into<VirtualKeyCode>>(&mut self, button: I) -> bool

Check if the given key was pressed since the last call to screen.release() or screen.poll_events().

pub fn space_wait(&mut self)

Pause the program and wait for the space bar to be pressed. This is a convienence which is useful for debugging and also in psychological experiments.

pub fn mouse_press<B: Into<MouseButton>>(&mut self, button: B) -> bool

Check if the given mouse button was pressed since the last call to screen.reveal() or screen.poll_events().

pub fn mouse_release<B: Into<MouseButton>>(&mut self, button: B) -> bool

Check if the given mouse button was released since the last call to screen.reveal() or screen.poll_events().

pub fn mouse_x(&mut self) -> f64

What was the x-coordinate of the mouse at the last call to screen.reveal() or screen.poll_events().

pub fn mouse_y(&mut self) -> f64

What was the y-coordinate of the mouse at the last call to screen.reveal() or screen.poll_events().

pub fn poll_events(&mut self)

Rather than wait for screen.reveal() to be called to see if any events occurred, you can manually check for events with this function. Once it has been called, you can then check for specific events using the other functions in this