graphic—image-based graphic

class Graphic(img, pos=(0, 0), layer=0, pool=conf.DEFAULT_RESOURCE_POOL, res_mgr=conf.GAME.resources)

Bases: engine.util.Owned

Something that can be drawn to the screen.

Parameters:

• img – surface or filename (under conf.IMG_DIR) to load. If a surface, it should be already converted for blitting.
• pos – initial (x, y) position. The existence of a default is because you might use align() immediately on adding to a GraphicsManager.
• layer – the layer to draw in, lower being closer to the ‘front’. This can actually be any hashable object except None, as long as all layers used in the same GraphicsManager can be ordered with respect to each other.
• pool – ResourceManager resource pool name to cache any loaded images in.
• res_mgr – ResourceManager instance to use to load any images.

Many properties of a graphic, such as pos and size, can be changed in two main ways: by setting the attribute directly, or by calling the corresponding method. The former is more natural, and is useful for sched.Scheduler.interp(), while the latter all return the graphic, and so can be chained together.

Position and size can also be retrieved and altered using list indexing, like with Pygame rects. Altering size in any way applies the resize() transformation.

resize(), crop(), flip(), opacify() and rotate() correspond to builtin transforms (see transform()).

is_view = False

fn = None

Filename of the loaded image, or None if a surface was given.

last_rect = None

rect at the time of the last draw.

transforms = None

A list of transformations applied to the graphic. Always contains the builtin transforms as strings (though they do nothing by default); other transforms are added through transform(), and are functions.

opaque = None

Whether the graphic is completely opaque; do not change.

blit_flags = None

When blitting the surface, this is passed as the special_flags argument.

visible = None

Whether currently (supposed to be) visible on-screen.

was_visible = None

Whether this graphic was visible at the time of the last draw; do not change.

orig_sfc

The surface before any transforms.

When setting this, the surface should be already converted for blitting.

surface

The (possibly transformed) surface that will be used for drawing.

Accessing this will cause all queued transformations to be applied.

rect

pygame.Rect giving the on-screen area covered.

May be set directly, but not altered in-place.

This is actually the rect before rotation, which is probably what you want, really. To get the real rect, use postrot_rect.

x

x co-ordinate of the top-left corner of rect.

y

y co-ordinate of the top-left corner of rect.

pos

(x , y ).

w

Width of rect; uses resize().

h

Height of rect; uses resize().

size

(w , h ).

scale_x

Scaling ratio of the graphic on the x-axis; uses rescale().

scale_y

Scaling ratio of the graphic on the y-axis; uses rescale().

scale

(scale_x , scale_y ).

Can be set to a single number to scale by in both dimensions.

cropped_rect

The rect currently cropped to.

flipped_x

Whether flipped on the x-axis.

flipped_y

Whether flipped on the x-axis.

flipped

(flipped_x , flipped_y ).

Can be set to a single value to apply to both dimensions.

tint_colour

Tinted colour of the graphic, as taken by engine.util.normalise_colour().

opacity

Opacity of the graphic, from 0 (transparent) to 255.

angle

Current rotation angle, anti-clockwise in radians.

Also see rot_anchor.

postrot_rect

pygame.Rect giving the on-screen area covered after rotation.

anchor

The point within rect to fix in place when size changes.

This is a position as taken by engine.util.pos_in_rect() (where the rect argument will be rect). Defaults to (0, 0).

rot_anchor

Like anchor, used for rotation.

Defaults to 'center'.

scale_fn

Function to use for scaling.

Defaults to pygame.transform.smoothscale (and should have the same signature as this default).

rotate_fn

Function to use for rotating.

Uses pygame.transform.rotozoom by default. Takes the surface and angle (as passed to rotate()) and returns the new rotated surface.

rotate_threshold

Only rotate when the angle changes by this much.

Defaults to 2 * pi / 500.

owner

The thing that ‘owns’ this graphic.

This is usually a GraphicsManager instance, or None, but may be any other object. If this object has 'add', 'rm' or 'orig_size' attributes, these must be implemented like in GraphicsManager.

This property may be changed directly.

layer

As taken by the constructor.

move_to([x][, y]) → self

Move to the given position.

Omitted arguments are unchanged.

move_by(dx = 0, dy = 0) → self

Move by the given number of pixels.

align(alignment = 0, pad = 0, offset = 0, within = self.owner.orig_sfc.get_rect()) → self

Position this graphic within a rect.

All arguments are as taken by engine.util.align_rect().

last_transform_args(transform_fn)

Return the last (tuple of) arguments passed to the given transform.

This is all arguments passed to the transform when it was last applied/queued. Takes a transform function as taken by transform(). If it has not been applied/queued yet, the return value is None (builtin transformations are always applied).

sfc_before_transform(transform_fn)

Return the value of surface before the given transform.

Takes a transform function as taken by transform(), or an index in transforms. If it has not been applied/queued yet, the return value is None (builtin transformations are always applied). Calling this causes all queued transformations to be applied.

sz_before_transform(transform_fn)

Return the value of size before the given transform.

Takes a transform function as taken by transform(). If it has not been applied/queued yet, the return value is None (builtin transformations are always applied). Unlike sfc_before_transform(), calling this does not apply queued transformations.

transform(transform_fn, *args[, position][, before][, after]) → self

Apply a transformation to the graphic.

Parameters:

• transform_fn – a function to apply a transform, or a string for a builtin transform such as 'resize' (see class documentation).
• args – passed to the transformation function as positional arguments, after compulsory arguments.
• position – the index in transforms to insert this transform at. If not given, the transform is appended to the end if new (not in transforms already), else left where it is.
• before – if position is not given, this gives the transform function (as in transforms) to insert this transform before. If before is not in transforms, the transform is put at the end.
• after – if position and before are not given, insert after this transform function, or at the end if it doesn’t exist.

Builtin transforms should not be moved after rotation ('rotate'); behaviour in this case is undefined.

Calls transform_fn(src, dest, dirty, last_args, *args) to apply the transformation, where:

• src is the surface before this transformation was last applied (or the current surface if it never has been).
• dest is the surface last produced by this transformation, or None if the transform is new.
• last_args is the args passed to this method when this transformation was last applied, as a tuple (or None if it never has been).
• args is as passed to this method.
• dirty defines what has changed in src since the last time this transform was applied—True if the whole surface has changed, or a list of rects, or False if nothing has changed. This allows for partial transformations by altering dest, if given.

transform_fn should return (sfc, dirty), where:

• sfc is the resulting pygame Surface.
• dirty is a corresponding definition of changed areas in the resulting surface - everything that changed since ‘last time’, which is the result after the last time the transform was performed, or the result before the transform is performed, if it hasn’t been performed before.

src should never be altered, but may be returned as sfc if the transform does nothing. Possible modes of operation are:

• full transform: return (new_sfc, True).
• partial transform: return (dest, new_dirty) (new_dirty might also be False here).
• do nothing: return (src, dirty).

If creating and returning a new surface, it should already be converted for blitting.

retransform(transform_fn) → self

Reapply the given transformation (if already applied).

Parameters:transform_fn – a transformation function as taken by transform().

untransform(transform_fn) → self

Remove an applied transformation.

Parameters:transform_fn – a transformation function as taken by transform().

size_changed(size)

Tell the graphic that the original size has changed.

Parameters:size – the new original size to use.

‘Original’ means before any transforms. This method is for use by subclasses, to call when orig_sfc will change, but will not be set until render() is called to avoid unnecessary computations. The new position is determined by anchor.

reload()

Reload from disk if possible.

If successful, all transformations are reapplied afterwards, if any.

resize([w][, h]) → self

Resize the graphic.

Parameters:

• w – the new width.
• h – the new height.

No scaling occurs in omitted dimensions. Also see anchor.

rescale(w=1, h=1) → self

A convenience wrapper around resize() to scale by a ratio.

Parameters:

• w – the new width; ratio of the width before scaling.
• h – the new height; ratio of the height before scaling.

resize_both(w=False, h=False) → self

Resize with constant aspect ratio.

Parameters:

• w – the new width; pass only one of w and h.
• h – the new height.

rescale_both(scale=1) → self

A convenience wrapper around rescale() to scale the same on both axes.

Parameters:scale – ratio to scale both width and height by.

crop(rect) → self

Crop the surface to the given rect.

rect need not be contained in the current surface rect.

flip(x = False, y = False) → self

Flip the graphic over either axis.

Parameters:

• x – whether to flip over the x-axis.
• y – whether to flip over the y-axis.

tint(colour) → self

Set tint colour, as taken by engine.util.normalise_colour().

This doesn’t actually add any colour; it just alters the amount of colour in each channel.

opacify(opacity) → self

Set opacity, from 0 (transparent) to 255.

(Sorry about the name—fade would be nice, but conflicts with GraphicsManager.fade().)

rotate(angle) → self

Rotate the graphic.

Parameters:angle – the angle in radians to rotate to, anti-clockwise from the original graphic.

Also see rot_anchor.

snapshot(copy=True)

Return a copy of this graphic.

The copy is shallow, which means the new graphic will not transform as this one does, but will be an exact copy of the current state.

Parameters:copy – whether to copy the final surface of this graphic/initial surface of the returned graphic. Since under some circumstances, this graphic can modify its final surface, this is often necessary. However, if you do not plan to modify this graphic further and will not alter the inital surface (orig_sfc) of the returned graphic, you maybe safely pass False for reduced CPU and memory usage.

view()

Return a ‘view’ to this graphic.

This is a wrapper around the graphic that allows assigning a different position and visibility (visible, layer, etc.) without affecting the original graphic (or any other wrappers). It is a subclass of this graphic’s class.

Changes to the image represented by either the wrapper or the original graphic affect both instances. This includes both transformations and changes to the original surface.

This may not be used on subclasses that define a child property.

dirty(*rects)

Mark some or all of the graphic as changed.

This is to be used when you alter the original surface (orig_sfc)—do not alter any other (transformed) surfaces. Takes any number of rects to flag as dirty. If none are given, the whole of the graphic is flagged.

render()

Update the final surface.

This propagates changes from queued transformations and changes to the original surface.

cb(cb, *evts) → self

Register a callback for a number of events.

Parameters:

• cb – callback function; it is called with the event name followed by event-specific arguments. If this callback was already registered, the previous set of events specified is overridden.
• evts – event names to register the callback for; if none are given, it is called for all event types.

Event types:

draw

The content of surface changed without the surface itself changing.

Arguments: surface.

draw orig

The content of orig_sfc changed without the surface itself changing.

Arguments: surface.

change

surface changed to a different surface.

Arguments: old surface, new surface.

change orig

orig_sfc changed to a different surface.

Arguments: old surface, new surface.

resize

surface changed to a different surface with a different size.

Arguments: old size, new size (both (width, height)).

resize orig

orig_sfc changed to a different surface with a different size.

Arguments: old size, new size (both (width, height)).

rm_cbs(*cbs) → self

Remove any number of callbacks registered with events.

Missing items are ignored.