Helm.Graphics2D

Contains all the types and functions for composing and rendering 2D graphics.

Types

data Collage e

Represents a collection of forms, which in turn are rendereable shapes and lines. In Helm, the collage is the main structure representing 2D graphics and is passed directly to the engine to be rendered by your view function. It's best to think of a collage as a fancy version of a game screen, with the difference being that the collage itself knows nothing about the window state. It only knows what will be rendered to the screen (which in this case, is a series of forms) and the order in which they will be rendered.

Constructors

Collage

Fields

collageDims :: Maybe (V2 Double)

The optional dimensions of the collage. It will be clipped to these dims.

collageForms :: [Form e]

The collection of forms under the collage.

collageCenter :: Maybe (V2 Double)

The optional center of the collage.

data Form e

Represents something that can be rendered to the screen ( contained under a collage). There are many different types of forms, which can be composed below but are generally represented by the FormStyle type.

A form might be an image, or a rectangle, or a circle, or even a collection of forms (which in turn can be those same things).

Constructors

Form

Fields

formTheta :: Double

The rotation of the form (in radians).

formScale :: Double

The scale factor of the form.

formPos :: V2 Double

The position of the form. This will be rendered relative to the collage origin.

formAlpha :: Double

The alpha channel of the form.

formStyle :: FormStyle e

The style of form.

data FormStyle e

Represents the styles of forms available. The form style holds data specific to a variation of form, and the Form is instead a general version of this with positioning information, rotation, scale, etc.

Constructors

PathForm LineStyle Path

A form composed of a path

ShapeForm (ShapeStyle e) Shape

A form composed of a shape.

TextForm Text

A form composed of a piece of text, including string and style info.

ImageForm (Image e) (V2 Double) (V2 Double) Bool

A form composed of an image

GroupForm Transform [Form e]

A form composed of a group of forms, with a transformation.

CollageForm (Collage e)

A form composed of a collage (which in turn is a collection of forms).

data FillStyle e

Represents the style of shape filling available.

Constructors

Solid Color

The shape will be filled with a solid color.

Texture (Image e)

The shape will be filled with a texture (a.k.a. image).

Gradient Gradient

The shape will be filled with a gradient (which can be linear or radial).

data LineCap

Represents the shape of the ends of a line.

Constructors

FlatCap

RoundCap

PaddedCap

Instances

Eq LineCap

Ord LineCap

Read LineCap

Show LineCap

data LineJoin

Represents the shape of the joints between line segments.

Constructors

SmoothJoin

SharpJoin Double

ClippedJoin

Instances

Eq LineJoin

Ord LineJoin

Read LineJoin

Show LineJoin

data LineStyle

Represents the style used for drawing lines. It's best to use defaultLine and then only change the fields you need to.

Constructors

LineStyle

Fields

lineColor :: Color

lineWidth :: Double

lineCap :: LineCap

lineJoin :: LineJoin

lineDashing :: [Double]

lineDashOffset :: Double

Instances

Eq LineStyle

Show LineStyle

data Path

Represents a series of 2D points which will be drawn in sequence. Like a Shape, a path on its own holds no styling information.

Constructors

Path [V2 Double]

Instances

Eq Path

Ord Path

Read Path

Show Path

data Shape

Represents a collection of points that when drawn in order will result in a closed polygon. They have no style information - rather, you compose shapes into a form with fill or line style and that affects their appearance.

Note that realistically, a shape could be represented as a path only. However, we add extra variants here as drawing backends usually provide optimized forms of drawing circles (and perhaps rectangles, although that is less likely) hence it's better to fall to those if our shape is circular.

Constructors

PolygonShape Path

RectangleShape (V2 Double)

ArcShape (V2 Double) Double Double Double (V2 Double)

Instances

Eq Shape

Ord Shape

Read Shape

Show Shape

data ShapeStyle e

Represents the style used for drawing a shape.

Constructors

OutlinedShape LineStyle

Stroke/outline the shape, with a specific line style.

FilledShape (FillStyle e)

Fill the shape, with a specific fill style.

data Transform

Represents a transformation matrix that can be used to transform forms. This is more useful than just using the composing methods in the graphics API, as it can perform skewing and other complex transformation techniques.

Constructors

Transform (M33 Double)

Instances

Eq Transform

Num Transform

Ord Transform

Read Transform

Show Transform

data Text

Represents a graphical piece of text, containing a UTF-8 string and any relevant style fields.

Constructors

Text

Fields

textString :: String

textColor :: Color

textTypeface :: String

textHeight :: Double

textWeight :: FontWeight

textStyle :: FontStyle

Instances

Eq Text

Show Text

Collages

collage :: [Form e] -> Collage e

Create a collage from a list of forms. By default, the collage will not be clipped and will not be centered. The origin point of the contained forms will be the top-left of the collage (which in the case of rendering a collage to the screen, is coincidently the top-left of the game window). See center and clip.

clip

Arguments

:: V2 Double

The dimensions to clip the collage with.

-> Collage e

The source collage.

-> Collage e

The clipped collage.

Clip a collage by provided dimensions. Note that by default, a collage will not be clipped and anything beyond the window dimensions will still technically be rendered (although obviously it will not appear on the game screen). By composing a collage with this function, when the collage is rendered its contents will be clipped by these dimensions. Not only will this generally speed up performance, it can be used for certain cases where you don't want the forms in the collage to spill over to other collages near it (but that's a very rare use-case).

Something to note, that this is absolutely not an ensurance that your 2D graphics will be rendered quickly if you're doing a lot of graphics work. The clip merely prevents things being drawn outside the dimensions, which in most cases will indeed speed up the performance, but it is down to the engine implementation for how much this actually helps.

In that sense, it's up to the library user to make sure they're not rendering huge amounts of forms that aren't even in the screen's bounds.

center

Arguments

:: V2 Double

The position to center the collage at.

-> Collage e

The source collage.

-> Collage e

The centered collage.

Center a collage around a fixed point. This is useful to implement 2D game cameras - usually, you have the center of the screen at the position of the game camera (which in a 2D platformer, is usually your game character). Note that this will center the forms themselves, i.e. their original point will change from being the top left of the collage to

toForm :: Collage e -> Form e

Create a form from a collage. This might seem a little strange (as a collage is generally what you provide to the engine to render the 2D graphics) but by allowing this functionality, you can compose collages from other collages.

Styles & Forms

defaultLine :: LineStyle

Create the default line style. By default, the line is black with a width of 1, flat caps and regular sharp joints.

solid :: Color -> LineStyle

Create a solid line style with a color.

dashed :: Color -> LineStyle

Create a dashed line style with a color.

dotted :: Color -> LineStyle

Create a dotted line style with a color.

filled :: Color -> Shape -> Form e

Fill a shape with a color.

textured :: Image e -> Shape -> Form e

Fill a shape with a texture. The texture should be an image loaded by the engine.

gradient :: Gradient -> Shape -> Form e

Fill a shape with a gradient (either linear or radial).

outlined :: LineStyle -> Shape -> Form e

Create a form from a shape by outlining it with a specific line style.

traced :: LineStyle -> Path -> Form e

Create a form from a path by tracing it with a specific line style.

image :: V2 Double -> Image e -> Form e

Create a form from an image. If the image dimensions are not the same as provided, then it will stretch/shrink to fit.

fittedImage :: V2 Double -> Image e -> Form e

Create a form from an image with a 2D vector describing its dimensions. If the image dimensions are not the same as given, then it will only use the relevant pixels (i.e. cut out the given dimensions instead of scaling). If the given dimensions are bigger than the actual image, than irrelevant pixels are ignored.

croppedImage :: V2 Double -> V2 Double -> Image e -> Form e

Create a form from an image by cropping it with a certain position, width, height and image file path. This can be used to divide a single image up into smaller ones ( for example, drawing a single sprite from a sprite sheet).

blank :: Form e

Create an empty form, useful for having forms rendered only at some state.

alpha :: Double -> Form e -> Form e

Change the alpha value of a form (i.e. its transparency). By default, forms will have an alpha value of 1, in other words, they are fully opaque. Alternatively, a value of 0 will mean the form is completely hidden.

text :: Text -> Form e

Create a form from a Text structure, which in turn contains all of the text values and styling. This allows you to render a the text graphically (and in turn it's a regular old form, so it can be translated, rotated, etc.).

Grouping

group :: [Form e] -> Form e

Group a list of forms into one. They will be drawn in their sequential order within the list.

groupTransform :: Transform -> [Form e] -> Form e

Group a list of forms into one, while also applying a matrix transformation.

Transforming

rotate :: Double -> Form e -> Form e

Rotate a form by a given angle (in radians). Like move and scale, the rotation is relative.

scale :: Double -> Form e -> Form e

Scale a form by a scalar factor. Scaling by 2 will double the size of the form, and scaling by 0.5 will half the size. Note that like move, the scale function is relative - i.e. if you scaled by 0.5 and then scaled by 0.5 a gain, the final scale would be 0.25 or a quarter of the form's initial scale.

move :: V2 Double -> Form e -> Form e

Move a form by a given 2D vector. The movement is relative, i.e. the translation vector provided will be added to the form's current position.

Paths

path :: [V2 Double] -> Path

Create a path from a sequence of points (represented as 2D vectors).

Shapes

polygon :: Path -> Shape

Create an arbitary-sided polygon from a path. The points provided should refer to each corner of the -gon, however the points do not need to loop around (i.e. the final point will automatically connect to the first point).

rect :: V2 Double -> Shape

Create a rectangular shape from a 2D vector, with x and y representing width and height, respectively.

square :: Double -> Shape

Create a square shape with a side length.

oval :: Double -> Double -> Shape

Create an oval shape with a width and height.

circle :: Double -> Shape

Create a circle shape with a radius.

ngon :: Int -> Double -> Shape

Create a generic n-sided polygon (e.g. octagon, pentagon, etc) with a side count and radius.