Crate piston_window

The official Piston window wrapper for the Piston game engine

Notice! If this is your first time visiting Piston, start here.

The purpose of this library is to provide an easy-to-use, simple-to-get-started and convenient-for-applications API for Piston.

Sets up:

• Gfx with an OpenGL back-end.
• gfx_graphics for 2D rendering.
• glutin_window as default window back-end, but this can be swapped (see below).

Example

extern crate piston_window;

use piston_window::*;

fn main() {
    let mut window: PistonWindow =
        WindowSettings::new("Hello World!", [512; 2])
            .build().unwrap();
    while let Some(e) = window.next() {
        window.draw_2d(&e, |c, g| {
            clear([0.5, 0.5, 0.5, 1.0], g);
            rectangle([1.0, 0.0, 0.0, 1.0], // red
                      [0.0, 0.0, 100.0, 100.0], // rectangle
                      c.transform, g);
        });
    }
}

The draw_2d function calls the closure on render events. There is no need to filter events manually, and there is no overhead.

Swap to another window back-end

Change the generic parameter to the window back-end you want to use.

extern crate piston_window;
extern crate sdl2_window;

use piston_window::*;
use sdl2_window::Sdl2Window;


let window: PistonWindow<Sdl2Window> =
    WindowSettings::new("title", [512; 2])
        .build().unwrap();

sRGB

The impl of BuildFromWindowSettings in this library turns on WindowSettings::srgb, because it is required by gfx_graphics.

Most images such as those found on the internet uses sRGB, that has a non-linear gamma corrected space. When rendering 3D, make sure textures and colors are in linear gamma space. Alternative is to use Srgb8 and Srgba8 formats for textures.

For more information about sRGB, see https://github.com/PistonDevelopers/piston/issues/1014

Library dependencies

This library is meant to be used in applications only. It is not meant to be depended on by generic libraries. Instead, libraries should depend on the lower abstractions, such as the Piston core.

Re-exports

pub extern crate texture;

Modules

character	A text character
circle_arc	Draw an arc
color	Helper methods for colors
context	Transformation context
controller	Back-end agnostic controller events.
deform	Least square deforming of a 2D grid.
draw_state	Graphics draw state.
ellipse	Draw ellipse
generic_event	Trait for generic events
glyph_cache	Implementations of the CharacterCache trait.
grid	A flat grid with square cells.
image	Draw an image
keyboard	Back-end agnostic keyboard keys.
line	Draw Line
math	Various methods for computing with vectors.
modular_index	Helper functions for computing modular index safely.
mouse	Back-end agnostic mouse buttons.
polygon	Draw polygon
radians	Reexport radians helper trait from vecmath
rectangle	Draw rectangle
text	Draw text
triangulation	Methods for converting shapes into triangles.
types	Contains type aliases used in this library

Structs

AfterRenderArgs	After render arguments.
ButtonArgs	Button arguments
CloseArgs	Close arguments.
EventId	Used to identify events arguments provided by traits.
EventSettings	Stores event loop settings.
Events	An event loop iterator
IdleArgs	Idle arguments, such as expected idle time in seconds.
NoWindow	A window without user interface, often used in server event loops.
PistonWindow	Contains everything required for controlling window, graphics, event loop.
Position	Structure to store the window position.
RenderArgs	Render arguments
Size	Structure to store the window size.
Texture	Represents a texture.
TextureSettings	Texture creation parameters.
TouchArgs	Touch arguments
UpdateArgs	Update arguments, such as delta time in seconds
Viewport	Stores viewport information.
WindowSettings	Settings structure for window behavior.

Enums

Button	Models different kinds of buttons.
ButtonState	Stores button state.
Event	Models all events.
FileDrag	Models dragging and dropping files.
Filter	Sampling filter
Flip	Flip settings.
HatState
Input	Models input events.
Loop	Models loop events.
Motion	Models different kinds of motion.
OpenGL
Touch	Stores the touch state.

Constants

BACK_END_MAX_VERTEX_COUNT	Any triangulation method called on the back-end never exceeds this number of vertices. This can be used to initialize buffers that fit the chunk size.
DEFAULT_MAX_FPS	The default maximum frames per second.
DEFAULT_UPS	The default updates per second.
DEFAULT_UPS_RESET	The default delayed updates reset.

Traits

AdvancedWindow	Trait representing a window with the most features that are still generic.
AfterRenderEvent	After rendering and buffers are swapped.
BuildFromWindowSettings	Constructs a window from a WindowSettings object.
ButtonEvent	Changed button state.
CloseEvent	Window is closing.
Colored	Implemented by contexts that contains color.
CursorEvent	When window gets or loses cursor
EventLoop	Methods implemented for changing event loop settings.
FocusEvent	When window gets or loses focus
Graphics	Implemented by all graphics back-ends.
IdleEvent	When background tasks should be performed
ImageSize	Implemented by all images to be used with generic algorithms.
OpenGLWindow	Trait for OpenGL specific operations on a window.
PressEvent	The press of a button
Rectangled	Should be implemented by contexts that have rectangle information.
ReleaseEvent	The release of a button
RenderEvent	When the next frame should be rendered
ResizeEvent	When the window is resized
SourceRectangled	Should be implemented by contexts that have source rectangle information.
TextEvent	When receiving text from user, such as typing a character
TouchEvent	When a touch is started, moved, ended or cancelled.
Transformed	Implemented by contexts that can transform.
UpdateEvent	When the application state should be updated
Window	Trait representing the minimum requirements for defining a window.

Functions

circle_arc	Draws arc
clear	Clears the screen.
ellipse	Draws ellipse.
image	Draws image.
line	Draws line.
polygon	Draws polygon.
rectangle	Draws rectangle.
text	Draws text.

Type Definitions

G2d	2D graphics.
G2dTexture	Texture type compatible with G2d.
GfxEncoder	Actual gfx::Stream implementation carried by the window.
GfxFactory	Actual factory used by Gfx backend.
Glyphs	Glyph cache.
ProcAddress	The type of an OpenGL function address.