[][src]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 love 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.

The pipe module is auto-generated by gfx_defines!.

Modules

pipe
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 probably never 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.

FontId

Id for a font

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 specifies in the config, and what the graphics backend init code actually gets.

Globals

Internal structure containing global shader state.

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.

MeshBuilder

A builder for creating Meshes.

Rect

A simple 2D rectangle.

Scale

Defines the size of a rendered face of a font, in pixels, horizontally and vertically. A vertical scale of y pixels means that the distance betwen the ascent and descent lines (see VMetrics) of the face will be y pixels. If x and y are equal the scaling is uniform. Non-uniform scaling by a factor f in the horizontal direction is achieved by setting x equal to f times y.

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 metrics 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. Can be implicitly constructed from String, (String, Color), and (String, FontId, Scale).

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 shape 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.

WrapMode

Specifies how texture coordinates outside the range [0, 1] are handled.

Constants

BLACK

Black

DEFAULT_FONT_SCALE

Default size for fonts.

WHITE

White

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

apply_transformations

Calculates the new total transformation (Model-View-Projection) matrix based on the matrices at the top of the transform and view matrix stacks and sends it to the graphics card.

clear

Clear the screen to the background color.

clear_shader

Clears the the current shader for the Context, restoring the default shader.

default_filter

Get the default filter mode for new images.

depth_view

Returns the gfx-rs depth target object for ggez's rendering context.

device

Returns the gfx-rs Device object for ggez's rendering context.

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.

encoder

Returns the gfx-rs Encoder object for ggez's rendering context.

factory

Returns the gfx-rs Factory object for ggez's rendering 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. Returns all the relevant objects at once; getting them one by one is awkward 'cause it tends to create double-borrows on the Context object.

hidpi_factor

Returns the hidpi pixel scaling factor that ggez is currently using. If WindowSetup::allow_highdpi is true this is equal to os_hidpi_factor(), otherwise it is 1.0.

mul_projection

Premultiplies the given transformation matrix with the current projection matrix

mul_transform

Premultiplies the given transform with the current model transform.

origin

Sets the current model transform to the origin transform (no transformation)

os_hidpi_factor

Returns the hidpi pixel scaling factor that the operating system says that ggez should be using.

pop_transform

Pops the transform matrix off the top of the transform (model) matrix stack of the Context.

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

push_transform

Pushes a homogeneous transform matrix to the top of the transform (model) matrix stack of the Context. If no matrix is given, then pushes a copy of the current transform matrix to the top of the stack.

queue_text

Queues the Text to be drawn by draw_queued(). relative_dest is relative to the DrawParam::dest passed to draw_queued()./ Note, any Text drawn via graphics::draw() will also draw the queue.

queue_text_raw

Exposes gfx_glyph's GlyphBrush::queue() and GlyphBrush::queue_custom_layout(), in case ggez' API is insufficient.

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 }

screen_render_target

Returns the gfx-rs color target object for ggez's rendering context.

screenshot

Take a screenshot by outputting the current render surface (screen or selected canvas) to a PNG file.

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_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.

set_resizable

Sets whether or not the window is resizable.

set_resolution

Sets the window size/resolution to the specified width and height.

set_screen_coordinates

Sets the bounds of the screen viewport.

set_shader

Set the current shader for the Context to render with

set_transform

Sets the current model transformation to the given homogeneous transformation matrix.

set_window_icon

Sets the window icon.

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. TODO: Rename, since get_drawable_size is usually what we actually want. Maybe get_entire_size or get_window_border_size?

transform

Gets a copy of the context's current transform matrix

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.

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