simvx.core.gradient

A two-colour gradient: a fill value, not a drawing method.

canvas.rect(pos, size, fill=Gradient(top, bottom)) is how a 2D drawing surface fills a shape with a ramp instead of a flat colour. Passing the ramp as a value is what keeps the vocabulary to one entry point per primitive: there is one rect, and what it is filled with is an argument, so a caller that computes its fill (flat here, a ramp there) writes one call rather than branching between two method names.

It lives in core because all three 2D drawing surfaces have to read it and one of them (the headless DrawLog) is a core module, so the type cannot sit anywhere that core is unable to import.

The shape is deliberately small: two colours and the axis they run along, which is what a drawing surface can turn into vertex colours on its own. Anything richer (interior stops, a radial ramp, a shader) is a different mechanism and does not belong behind this name.

Module Contents

Classes

GradientDirection	The axis a :class:Gradient runs along, in the filled shape’s own space.
Gradient	A linear ramp from start to end across the shape it fills.

Functions

reject_gradient	Raise when a gradient reaches a primitive that can only paint a flat colour.
fill_corner_colours	The colour of each corner of a rectangle filled with fill.

Data

__all__

API

simvx.core.gradient.__all__

[‘Gradient’, ‘GradientDirection’, ‘fill_corner_colours’, ‘reject_gradient’]

class simvx.core.gradient.GradientDirection

Bases: enum.StrEnum

The axis a :class:Gradient runs along, in the filled shape’s own space.

Initialization

Initialize self. See help(type(self)) for accurate signature.

VERTICAL

‘vertical’

start at the top edge, end at the bottom edge.

HORIZONTAL

‘horizontal’

start at the left edge, end at the right edge.

__new__(*values)

__add__()

__contains__()

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getitem__()

__getnewargs__()

__getstate__()

__gt__()

__hash__()

__iter__()

__le__()

__len__()

__lt__()

__mod__()

__mul__()

__ne__()

__reduce__()

__reduce_ex__()

__repr__()

__rmod__()

__rmul__()

__setattr__()

__sizeof__()

__str__()

__subclasshook__()

capitalize()

casefold()

center()

count()

encode()

endswith()

expandtabs()

find()

format()

format_map()

index()

isalnum()

isalpha()

isascii()

isdecimal()

isdigit()

isidentifier()

islower()

isnumeric()

isprintable()

isspace()

istitle()

isupper()

join()

ljust()

lower()

lstrip()

partition()

removeprefix()

removesuffix()

replace()

rfind()

rindex()

rjust()

rpartition()

rsplit()

rstrip()

split()

splitlines()

startswith()

strip()

swapcase()

title()

translate()

upper()

zfill()

__deepcopy__(memo)

__copy__()

name()

value()

class simvx.core.gradient.Gradient

A linear ramp from start to end across the shape it fills.

Example::

canvas.rect((0, 0), (w, h), fill=Gradient((0.1, 0.1, 0.3), (0.6, 0.2, 0.1)))
canvas.rect((0, 0), (w, h), fill=Gradient(left, right, "horizontal"))

Both colours are ordinary drawing colours: RGB or RGBA floats in 0-1, which the surface normalises exactly as it normalises a flat fill. The direction accepts a :class:GradientDirection member or its plain string.

start: simvx.core.gradient.ColourValue

None

end: simvx.core.gradient.ColourValue

None

direction: simvx.core.gradient.GradientDirection

None

__post_init__() → None

corner_colours() → tuple[simvx.core.gradient.ColourValue, simvx.core.gradient.ColourValue, simvx.core.gradient.ColourValue, simvx.core.gradient.ColourValue]

The colour of each corner of the rectangle this fills.

In the order a drawing surface builds a quad: top-left, top-right, bottom-right, bottom-left. The one place the ramp becomes per-corner colour, so every surface puts the same colour on the same corner.

simvx.core.gradient.reject_gradient(fill, primitive: str) → None

Raise when a gradient reaches a primitive that can only paint a flat colour.

A rectangle is the one shape whose corners a two-colour ramp lands on unambiguously, so it is the one shape that takes a :class:Gradient fill. Anywhere else the argument is a mistake, and a mistake that would otherwise surface as a colour-arity error from deep inside the vertex path.

simvx.core.gradient.fill_corner_colours(fill) → tuple[simvx.core.gradient.ColourValue, simvx.core.gradient.ColourValue, simvx.core.gradient.ColourValue, simvx.core.gradient.ColourValue]

The colour of each corner of a rectangle filled with fill.

A flat colour repeats; a :class:Gradient ramps. Every drawing surface calls this and then normalises the four results, so none of them can put the ramp on a different corner from the others.