NAME

Pop::Graphics

SYNOPSIS

given Pop::Graphics {
        .clear; # Erase back-buffer

# Draw supported objects or primitives on the back-buffer
        .draw: $sprite, ( 0, 0 ), scale => 2;
        .circle: :fill, $centre, $radius, $color;

# Or specify a render target
        .set-target: $texture;
        .rectangle: ( 10, 10), ( 20, 20 ), '#ffca4bff';
        .reset-target;

# Flip the render buffers
        .present;
    }

DESCRIPTION

Pop::Graphics is the rendering manager for Pop. It manages the creation of Pop::Texture objects (which represent images in video memory) and provides a general interface for drawing both textures or sprites as well as graphic primitives such as shapes and curves.

METHODS

new

method new (
        :$width,
        :$height,
        :$title,
        :$fullscreen,
        :$flags,
    ) returns Pop::Graphics

When called (either directly by the user or indirectly when any method is called on the class), a game window will be created with the specified dimensions and title. Additional window features can be specified with the :flags bitfield, which will be interpreted as a combination of values from the SDL_WindowFlags SDL enum. See the documentation of the accompanying Pop::SDL distribution for a possible way to use these.

If not provided, default values for these parameters will be read from the window section of the global configuration made available through Pop::Config.

The :fullscreen option is made available as a shortcut to enable fullscreen mode (using the "desktop fullscreen" mode in SDL2). When in use, the dimensions specified for the window will be interpreted as the window's logical size.

renderer

method renderer () returns SDL::Renderer

Returns a reference to the internal SDL renderer. As this is an opaque object, this will likely only be needed when making direct calls to SDL bindings.

window

method window () returns SDL::Window

Returns a reference to the internal SDL window. As this is an opaque object, this will likely only be needed when making direct calls to SDL bindings.

offset

method offset is rw () returns Pop::Point

Returns a writable Pop::Point object which will be used as the global offset for draw operations. If set, it will be added to all coordinates used by any of the drawing methods described below.

set-target

method set-target (
        Pop::Texture $texture,
    ) returns Nil

Set the specified texture as the current render target. Once this is called, all drawing operations will make changes on this texture rather than on the back-buffer.

Use reset-target to revert this.

reset-target

method reset-target () returns Nil

Reset the render target that has been modified with set-target. Calling this method is idempotent.

cursor-visibility

method cursor-visibility (
        Bool() $new-state?,
    ) returns Bool

If called with a value that can be coerced to a Bool, set the mouse cursor visibility to that value: visible if True, hidden otherwise. Returns the state of cursor visibility at the end of the call.

If no value is provided, the method will return the state of cursor visibility without changing it.

clear

multi method clear (
        Pop::Color:D() $bg,
    ) returns Nil

multi method clear (
        Int:D $r = 0,
        Int:D $g = 0,
        Int:D $b = 0,
        Int:D $a = 255,
    ) returns Nil

Clear the back-buffer with the specified colour. The colour can be specified either as a Pop::Color object, or as a set of four integers between 0 and 255 representing, in order, the red, blue, green, and alpha components.

If no colour is specified, the colour will default to fully opaque black.

present

method present () returns Nil

Render the back-buffer and flip the buffers.

destroy

multi method destroy () returns Nil

multi method destroy (
        Str $key,
    ) returns Nil

Destroy a single cached texture by key, or all cached textures if no key is provided.

draw

The draw method provides two candidates: a high-level one, which operates on the abstractions provided by Pop and should be the most convenient to use in most cases; and a low-level which operates directly on SDL objects for users who would rather sacrifice usability for performance.

High-level Candidate

multi method draw (
        Pop::Drawable:D $drawable,
        Pop::Point()    $xy,
        Pop::Point()   :$offset,
        Pop::Point()   :$scale,
        Pop::Rect()    :$clip,
        Pop::Point()   :$pivot,
        Num(Numeric)   :$angle = 0,
        Bool           :$flipxy,
        Bool           :$flipx = $flipxy,
        Bool           :$flipy = $flipxy,
    ) returns Nil

The high-level version takes two mandatory parameters: an object to draw, which must consume the Pop::Drawable role, and a coordinate in the screen to draw it in which will be coerced to a Pop::Point.

By default, the coordinate will correspond to the place where the top-left corner of the drawable object will be drawn. This can be adjusted with the :offset named parameter, which must be coerceable to a Pop::Point. If given, each component will be interpreted as a ratio along the respective axis, with 0 being the top / left end, and 1 being the bottom / right end.

In other words, to make the coordinate mean the point in the screen where the middle of the drawable object will be drawn, set the :offset to ( 0.5, 0.5 ).

A :scale parameter (also coerceable to a Pop::Point) will be used to scale the image when drawing. Setting this to eg. ( 0.5, 0.5 ) would mean that the object should be drawn at half its size. The value in each component will be applied independently to scale the horizontal and vertical axis respectively.

The :flipx and the :flipy flags can be set to independently flip an image vertically and / or horizontally. To flip both axes at once, :flipxy is also available.

A rotation angle can be specified with the :angle parameter. The pivot point for this rotation can be specified with the :pivot parameter, which will be interpreted in the same way as the value for :offset and default to being the centre of the objcet to render.

By default, the image to draw will be clipped using the result of calling the .clip method on the Pop::Drawable object. This can be overriden for convenience by setting the :clip parameter to a value that can be coerced to a Pop::Rect object.

Low-level candidate

multi method draw (
        SDL::Texture:D  $texture,
        SDL::Rect:D     $source,
        SDL::Rect:D     $dest,
        Numeric        :$angle = 0,
        SDL::Point     :$pivot,
        Int            :$flip,
    ) returns Nil

The low-level version accepts SDL representations, and forwards them to SDL_RenderCopyEx if any rotation or flipping is involved, or to SDL_RenderCopy otherwise. Please refer to the SDL documentation for further details.

point

method point (
        Pop::Point:D() $xy,
        Pop::Color:D() $color,
    ) returns Nil

Draw a point of the given colour at the specified coordinate on the current render target.

line

method line (
        Pop::Point:D() $start,
        Pop::Point:D() $end,
        Pop::Color:D() $color,
        Bool      :aa(:$anti-alias),
        Int           :$width,
    ) returns Nil

Draw a line of the given colour between the coordinates specified on the current render target. The :width parameter can be used to draw thick lines. If :anti-alias or the :aa shortcut is used, the line will be anti-aliased.

Line thickness will be ignored is anti-aliasing is used.

rectangle

multi method rectangle (
        Pop::Rect:D    $rectangle,
        Pop::Color:D() $color,
        Bool          :$fill,
        Int           :$border-radius,
    ) returns Nil

multi method rectangle (
        Pop::Point:D() $top-left,
        Pop::Point:D() $bottom-right,
        Pop::Color:D() $color,
        Bool          :$fill,
        Int           :$border-radius,
    ) returns Nil

Draw a rectangle of the given colour on the current render target. If called with a Pop::Rect object, the position and dimensions of that object will be used. Alternatively, it an be called with two arguments that can coerce to Pop::Point which will be interpreted as the rectangle's top-left and bottom-right corner (note that the second parameter is not the rectangle's width and height).

If :fill is set, the specified colour will be used to fill the area inside the rectangle. The :border-radius can be used to specify the radius in pixels to be used when drawing rounded corners. These two options are compatible.

circle

method circle (
        Pop::Point:D() $centre,
        Int:D()        $radius,
        Pop::Color:D() $color,
        Bool      :aa(:$anti-alias),
        Bool          :$fill,
    ) returns Nil

Draw a circle of the given colour on the current render target. The value in the $radius parameter will be interpreted in pixels.

If :fill is set, the specified colour will be used to fill the area inside the circle. If :anti-alias or the :aa shortcut is used, the edge of the circle will be anti-aliased.

Anti-aliasing will be ignored if :fill is set.

arc

multi method arc (
        Pop::Point:D() $centre,
        Int:D()        $radius,
        Int:D()        $start,
        Int:D()        $end,
        Pop::Color:D() $color,
        Bool          :$pie,
        Bool          :$fill,
    ) returns Nil

Draw an arc (a partial circle) of the given colour on the current render target. The value in the $radius parameter will be interpreted in pixels. The :start and <:end> parameters can be used to set the start and end of the arc in degrees, with 0 pointing downwards.

If :pie is set, the start and end points of the arc will each separately be connected to the centre coordinate with a line. If the :fill parameter is also set, the area inside this shape will be filled with the specified colour.

The :fill parameter is ignored unless :pie is set.

ellipse

method ellipse (
        Pop::Point:D() $centre,
        Pop::Point:D() $radii,
        Pop::Color:D() $color,
        Bool      :aa(:$anti-alias),
        Bool          :$fill,
    ) returns Nil

Draw an ellipse of the given colour on the current render target. The second parameter will be coerced to a Pop::Point, with its components representing the horizontal and vertical radius respectively.

If :fill is set, the specified colour will be used to fill the area inside the ellipse. If :anti-alias or the :aa shortcut is used, the edge of the ellipse will be anti-aliased.

Anti-aliasing will be ignored if :fill is set.

polygon

method polygon (
                       @points,
        Pop::Color:D() $color,
        Bool      :aa(:$anti-alias),
        Bool          :$fill,
    ) returns Nil

Draw a polygon of the given colour on the current render target. The first parameter will be a list of vertices, each of which must independently be coercible to a Pop::Point.

If :fill is set, the specified colour will be used to fill the area inside the polygon. If :anti-alias or the :aa shortcut is used, the edge of the polygon will be anti-aliased.

Anti-aliasing will be ignored if :fill is set.

bezier

method bezier (
                       @points,
        Pop::Color:D() $color,
        Int           :$steps where * >= 2 = 2,
    ) returns Nil

Draw a bezier curve of the given colour on the current render target. The first parameter will be a list of control points, each of which must independently be coercible to a Pop::Point.

The value of the :steps parameter determines the number of steps to use for interpolation. This number cannot be less than two, and will default to this value as well.

string

multi method string (
        Str:D()        $string,
        Pop::Point:D() $xy,
        Pop::Color:D() $color,
    ) returns Nil

Print a string with the given colour at the specified coordinate. The string will be printed with an internal 8x8 pixel font. The coordinate will set the position of the top-left corner of the string.

COPYRIGHT AND LICENSE

Copyright 2021 José Joaquín Atria

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.