Module ggez::graphics

The graphics module performs the actual drawing of images, text, and other objects with the Drawable trait. It also handles basic loading of images and text.

This module also manages graphics state, coordinate systems, etc. The default coordinate system has the origin in the upper-left corner of the screen, with Y increasing downwards.

This library differs significantly in performance characteristics from the LÖVE library that it is based on. Many operations that are batched by default in love (e.g. drawing primitives like rectangles or circles) are not batched in ggez, so render loops with a large number of draw calls can be very slow. The primary solution to efficiently rendering a large number of primitives is a SpriteBatch, which can be orders of magnitude more efficient than individual draw calls.

Re-exports

pub use mint;

Modules

spritebatch

A SpriteBatch is a way to efficiently draw a large number of copies of the same image, or part of the same image. It's useful for implementing tiled maps, spritesheets, particles, and other such things.

Structs

CanvasGeneric	A generic canvas independent of graphics backend. This type should never need to be used directly; use graphics::Canvas instead.
Color	A RGBA color in the sRGB color space represented as f32's in the range [0.0-1.0]
DrawParam	A struct containing all the necessary info for drawing a Drawable.
EmptyConst	A type for empty shader data for shaders that do not require any additional data to be sent to the GPU
FillOptions	Parameters for the fill tessellator.
Font	A handle referring to a loaded Truetype font.
FontCache	The font cache of the engine.
GlBackendSpec	A backend specification for OpenGL. This is different from Backend because this needs to be its own struct to implement traits upon, and because there may need to be a layer of translation between what the user asks for in the config, and what the graphics backend code actually gets from the driver.
Globals	Internal structure containing global shader state.
GlyphBrush	Object allowing glyph drawing, containing cache state. Manages glyph positioning cacheing, glyph draw caching & efficient GPU texture cache updating.
ImageGeneric	Generic in-GPU-memory image data available to be drawn on the screen. You probably just want to look at the Image type.
InstanceProperties	Internal structure containing values that are different for each drawable object. This is the per-object data that gets fed into the shaders.
Mesh	2D polygon mesh.
MeshBatch	Mesh that will be rendered with hardware instancing. Use this when you have a lot of similar geometry which does not move around often.
MeshBuilder	A builder for creating Meshes.
MeshIdx	An index of a particular instance in a MeshBatch
PxScale	Pixel scale.
Rect	A simple 2D rectangle.
ShaderGeneric	A ShaderGeneric reprensents a handle user-defined shader that can be used with a ggez graphics context that is generic over gfx::Resources
ShaderLock	A lock for RAII shader regions. The shader automatically gets cleared once the lock goes out of scope, restoring the previous shader (if any).
StrokeOptions	Parameters for the tessellator.
Text	Drawable text object. Essentially a list of TextFragment's and some cached size information.
TextFragment	A piece of text with optional color, font and font scale information. Drawing text generally involves one or more of these. These options take precedence over any similar field/argument. Implements From for char, &str, String and (String, Font, PxScale).
Vertex	Structure containing fundamental vertex data.

Enums

Align	Describes horizontal alignment preference for positioning & bounds.
BlendMode	An enum for specifying default and custom blend modes
DrawMode	Specifies whether a mesh should be drawn filled or as an outline.
FillRule	The fill rule defines how to determine what is inside and what is outside of the shape.
FilterMode	Specifies what blending method to use when scaling up/down images.
ImageFormat	The supported formats for saving an image.
LineCap	Line cap as defined by the SVG specification.
LineJoin	Line join as defined by the SVG specification.
Transform	A struct that represents where to put a Drawable.
WrapMode	Specifies how to wrap textures.

Constants

BLACK	Black
BLUE	Blue
CYAN	Cyan
DEFAULT_FONT_SCALE	Default size for fonts.
GREEN	Green
MAGENTA	Magenta
RED	Red
WHITE	White
YELLOW	Yellow

Traits

BackendSpec	A trait providing methods for working with a particular backend, such as OpenGL, with associated gfx-rs types for that backend. As a user you probably don't need to touch this unless you want to write a new graphics backend for ggez. (Trust me, you don't.)
Drawable	All types that can be drawn on the screen implement the Drawable trait.
ShaderHandle	A trait that is used to create trait objects to abstract away the gfx::Structure<ConstFormat> type of the constant data for drawing

Functions

clear	Clear the screen to the background color.
clear_font_cache	Deletes all cached font data.
clear_shader	Clears the the current shader for the Context, restoring the default shader.
default_filter	Get the default filter mode for new images.
draw	Draws the given Drawable object to the screen by calling its draw() method.
draw_queued_text	Draws all of the Texts added via queue_text().
drawable_size	Returns the size of the window's underlying drawable in pixels as (width, height). Returns zeros if window doesn't exist.
font_cache	Obtains the font cache.
get_window_color_format	Returns the screen color format used by the context
gfx_objects	Returns raw gfx-rs state objects, if you want to use gfx-rs to write your own graphics pipeline then this gets you the interfaces you need to do so.
mul_projection	Premultiplies the given transformation matrix with the current projection matrix
present	Tells the graphics system to actually put everything on the screen. Call this at the end of your EventHandler's draw() method.
projection	Gets a copy of the context's raw projection matrix
queue_text	Queues the Text to be drawn by draw_queued_text(). relative_dest is relative to the DrawParam::dest passed to draw_queued(). Note, any Text drawn via graphics::draw() will also draw everything already the queue.
queue_text_raw	Exposes glyph_brush's drawing API in case ggez's text drawing is insufficient. It takes glyph_brush's VariedSection and GlyphPositioner, which give you lower- level control over how text is drawn.
renderer_info	Returns a string that tells a little about the obtained rendering mode. It is supposed to be human-readable and will change; do not try to parse information out of it!
screen_coordinates	Returns a rectangle defining the coordinate system of the screen. It will be Rect { x: left, y: top, w: width, h: height }
screenshot	Take a screenshot by outputting the current render surface (screen or selected canvas) to an Image.
set_blend_mode	Sets the blend mode of the currently active shader program
set_canvas	Set the Canvas to render to. Specifying Option::None will cause all rendering to be done directly to the screen.
set_default_filter	Sets the default filter mode used to scale images.
set_drawable_size	Sets the window size/resolution to the specified width and height.
set_fullscreen	Sets the window to fullscreen or back.
set_mode	Sets the window mode, such as the size and other properties.
set_projection	Sets the raw projection matrix to the given homogeneous transformation matrix. For an introduction to graphics matrices, a good source is this: http://ncase.me/matrix/
set_resizable	Sets whether or not the window is resizable.
set_screen_coordinates	Sets the bounds of the screen viewport.
set_shader	Set the current shader for the Context to render with
set_window_icon	Sets the window icon.
set_window_position	Sets the window position.
set_window_title	Sets the window title.
size	Returns the size of the window in pixels as (width, height), including borders, titlebar, etc. Returns zeros if the window doesn't exist.
transform_rect	Applies DrawParam to Rect.
use_shader	Use a shader until the returned lock goes out of scope
window	Returns a reference to the Glutin window. Ideally you should not need to use this because ggez would provide all the functions you need without having to dip into Glutin itself. But life isn't always ideal.
window_raw	Return raw window context

Type Definitions

Canvas	A canvas that can be rendered to instead of the screen (sometimes referred to as "render target" or "render to texture"). Set the canvas with the graphics::set_canvas() function, and then anything you draw will be drawn to the canvas instead of the screen.
Image	In-GPU-memory image data available to be drawn on the screen, using the OpenGL backend.
Shader	A Shader represents a handle to a user-defined shader that can be used with a ggez graphics context
ShaderId	An ID used by the ggez graphics context to uniquely identify a shader