gewel.draw.Drawable

class gewel.draw.Drawable(z: Union[float, Tvf, PyTvf] = 0.0, alpha: Union[float, Tvf, PyTvf] = 1.0)[source]

Bases: gewel._timekeeper.TimekeeperMixin

This is the abstract base class for all drawables.

Drawables typically have two distinct phases in their lifecycle, scripting and rendering. Scripting sets up the object and all the actions it will take during a scene. It is like writing the script for the animation. Rendering animates the scene, producing a final video of the scene. It is like filming a scene after the script has been written.

For more details on the lifecycle of a Drawable, please refer to The Drawable Lifecycle.

Parameters

z (Union[float, Tvf, PyTvf]) – Depth of the object. When a Scene is rendered, the Drawable objects in the scene are rendered in ascending z order. So if two objects in the scene overlap, the one with the larger z will appear to be on top when the scene is rendered. If the z value are equal, the rendering order is undefined. So if there are two objects that are likely to overlap, it is recommended they be given different z values to ensure consistent rendering.
alpha (Union[float, Tvf, PyTvf]) –
The transparency/opacity of the object. It should be in the range [0.0, 1.0]. 0.0 means fully transparent, so when the drawn nothing appears. 1.0 is fully opaque, so nothing drawn at a lower z will show through. If in between 0.0 and 1.0, the object is partially transparent so objects with lower z will be partially visible through it. The closer to 0.0 the value is, the more transparent it will be.

Note that Color objects have their own alpha attribute. So if the color of a drawable is set to a transparent or semi-transparent color, then other objects may show through it even if the alpha of the object itself is set to 1.0.

Methods

`draw`	This method renders the drawable into pixels.
`fade_to`	Fade the object from it's current alpha to a new value.
`ramp_attr_to`	Change the value of an attribute of the object from the value it has at the current next-action time to a new value by ramping it linearly between the old and new values over the course of a given duration.
`rotated`	Return a version of the drawable that is rotated.
`rotated_degrees`	Return a version of the drawable that is rotated.
`scaled`	Construct and return a new drawable that is scaled in the x and y directions.
`set_time`	Set the next-action time.
`transformed`	Construct and return a new drawable that is transformed by the translation matrix specified by the parameters.
`translated`	Construct and return a new drawable that is translated by a relative amount in the x and y directions.
`wait`	Wait for a specified amount of time.
`wait_for`	Wait for another object to finish whatever action it is currently doing.
`wait_until`	Update the next-action time so that it is at least the given time.

Attributes

`alpha`	Transparency/opacity.
`time`	The next-action time.
`z`	z depth of the object.

alpha: Union[float, Tvf, PyTvf] = 1.0: Transparency/opacity. A value of 0.0 means completely

abstract draw(ctx: cairocffi.context.Context, t: float) → None[source]

This method renders the drawable into pixels. Drawable objects typically have time-varying behavior. For example, the x and y location of the object in a scene may be time-varying floats (see the Tvf class for details). It is the responsibility of the draw() method to render the correct pixels for time passed in.

Note that this method is very rarely called directly by user code. Instead, it is called by utility classes that render a Scene containing a Drawable objects. Examples include gewel.record.Mp4Recorder, which renders a scene to an MP4 file, or gewel.player.Player that creates an interactive preview of a Scene or the gewel.draw.Scene.__repr__() method that render a scene into an IPython notebook widget.

Parameters

ctx – The context in which to render. This is an object with low-level drawing primitives that the draw() method relies on to render at the pixel level.
t – The time at which to render. That is, we should render the object as it is intended to appear at this time in the scene. Exactly what that is is typically controlled by properties of the object that are Tvf objects.

fade_to(alpha: Union[float, Tvf, PyTvf], duration: float, update_time: bool = True)[source]

Fade the object from it’s current alpha to a new value. Alpha values range from 0.0, which means completely transparent, to 1.0, which means completely opaque. Most newly constructed Drawable classes that support alpha default to a value of 1.0.

See Using fade_to() for sample usage.

Parameters

alpha – The new alpha value. Should be between 0.0 and 1.0, inclusive. Values outside this range produce undefined behavior that may change in future versions.
duration – The amount of time, in seconds, the fade from the current alpha to the new alpha should take.
update_time – Should the object’s time be updated. Normally this is True. Making it False does not change the time, so that other updates can be made on the same object at the same time it is fading. For example, move_to() can be called to make the object move as it fades.

Returns

Return type

None

ramp_attr_to(name: str, to: float, duration: float, update_time: bool = True) → None

Change the value of an attribute of the object from the value it has at the current next-action time to a new value by ramping it linearly between the old and new values over the course of a given duration.

See Next-Action Time During Scripting for more on next-action time.

Parameters

name – Name of the attribute to update.
to – Value to change to.
duration – Time in seconds over which the value ramps from the old to the new value.
update_time – If True, update the object’s next-action time so that it is duration later than it was.

rotated(radians: Union[float, Tvf, PyTvf], z: Optional[Union[float, Tvf, PyTvf]] = None) → Drawable[source]

Return a version of the drawable that is rotated. See also rotated_degrees().

Parameters

radians – How much to rotate by, in radians.
z – The z depth of the resulting drawable. If not supplied, the z depth of self is used.

Returns

A new drawable that renders as the original but rotated.

Return type

Drawable

rotated_degrees(degrees: Union[float, Tvf, PyTvf], z: Optional[Union[float, Tvf, PyTvf]] = None) → Drawable[source]

Return a version of the drawable that is rotated. See also rotated().

Parameters

degrees – How much to rotate by, in degrees.
z – The z depth of the resulting drawable. If not supplied, the z depth of self is used.

Returns

A new drawable that renders as the original but rotated.

Return type

Drawable

scaled(sx: Union[float, Tvf, PyTvf], sy: Optional[Union[float, Tvf, PyTvf]] = None, z: Optional[Union[float, Tvf, PyTvf]] = None) → Drawable[source]

Construct and return a new drawable that is scaled in the x and y directions.

Parameters

sx – Scale in the x direction.
sy – Scale in the y direction.
z – The z depth of the resulting drawable. If not supplied, the z depth of self is used.

Returns

A new drawable that renders as the original but scaled.

Return type

Drawable

set_time(t: float)[source]

Set the next-action time.

See Next-Action Time During Scripting for more on next-action time.

Parameters: t – The new next-action time.

property time: float

The next-action time. See Next-Action Time During Scripting for more on next-action time.

Returns: The next action time.
Return type: float

transformed(xx: Union[float, Tvf, PyTvf] = 1.0, yx: Union[float, Tvf, PyTvf] = 0.0, xy: Union[float, Tvf, PyTvf] = 0.0, yy: Union[float, Tvf, PyTvf] = 1.0, x0: Union[float, Tvf, PyTvf] = 0.0, y0: Union[float, Tvf, PyTvf] = 0.0, z: Optional[Union[float, Tvf, PyTvf]] = None) → Drawable[source]

Construct and return a new drawable that is transformed by the translation matrix specified by the parameters. The default parameter values produce the identity transform.

The location of any point (x, y) in the original drawable is translated to the new point (x’, y’) where

x’ = xx * x + xy * y + x0

and

y’ = yy * y + yx * x + y0

Parameters

xx – Element of the matrix.
yx – Element of the matrix.
xy – Element of the matrix.
yy – Element of the matrix.
x0 – Translation in x
y0 – Translation in y
z – z depth of the new drawable. If None then self.z is used.

Returns

A transformed version of self.

Return type

Drawable

translated(dx: Union[float, Tvf, PyTvf], dy: Union[float, Tvf, PyTvf], z: Optional[Union[float, Tvf, PyTvf]] = None) → Drawable[source]

Construct and return a new drawable that is translated by a relative amount in the x and y directions.

Parameters

dx – How far to translate in the x direction.
dy – How far to translate in the y direction.
z – The z depth of the resulting drawable. If not supplied, the z depth of self is used.

Returns

A new drawable that renders as the original but translated.

Return type

Drawable

wait(duration: float) → None

Wait for a specified amount of time. This updates the object’s next-action time by adding a constant amount of time to it.

See Next-Action Time During Scripting for more on next-action time.

Parameters: duration – How long to wait, in seconds.

wait_for(other: Union[gewel._timekeeper.TimekeeperMixin, Iterable[gewel._timekeeper.TimekeeperMixin]]) → None

Wait for another object to finish whatever action it is currently doing. This method us used at scripting time to ensure that an object updates its next-action time so that it is no earlier than the next-action time of another object.

See Next-Action Time During Scripting for more on next-action time.

Parameters: other – The object to wait for. Or, an iterable collection of objects. If iterable, then wait for the one with the latest time.

wait_until(at_least: float) → None

Update the next-action time so that it is at least the given time. If it is already greater than that, change nothing.

See Next-Action Time During Scripting for more on next-action time.

Parameters: at_least – The minimum new next-action time.

z: Union[float, Tvf, PyTvf] = 0.0: z depth of the object. Objects in a scene are rendered