A displayable is an object that can be shown to the user. Ren'Py displayables can be used in many ways.
When a Ren'Py function or variable expects a displayable, there are five things that can be provided:
Color, or an (r, g, b, a) tuple, where each component is an integer between 0 and 255. Colors are passed to
Strings may have one or more square-bracket substitutions in them, such as "eileen [mood]" or "eileen_[outfit]_[mood].png". When such a string is given, a dynamic image is created. A dynamic image has text interpolation performed at the start of each interaction (such as say statements and menus). The resulting string is processed according to the rules above.
The most commonly used displayable is Image, which loads a file from disk and displays it. Since Image is so commonly used, when a string giving a filename is used in a context that expects a displayable, an Image is automatically created. The only time it's necessary to use Image directly is when you want to create an image with style properties.
Image(filename, **properties) link
Loads an image from a file. filename is a string giving the name of the file.
filename should be a JPEG or PNG file with an appropriate extension.
# These two lines are equivalent. image logo = "logo.png" image logo = Image("logo.png") # Using Image allows us to specify a default position as part of # an image. image logo right = Image("logo.png", xalign=1.0)
There are three image file formats we recommend you use:
Non-animated Gif and Bmp files are also supported, but should not be used in modern games.
Loading an Image from from a file on disk and decoding it so it can be drawn to the screen takes a long amount of time. While measured in the tenths or hundreds of seconds, the duration of the loading process is long enough that it can prevent an acceptable framerate, and become annoying to the user.
Since an Image is of a fixed size, and doesn't change in response to input, game state, or the size of the area available to it, an Image can be loaded before it is needed, and placed into an area of memory known as the image cache. Once an Image is decoded and in the cache, it can be quickly drawn to the screen.
Ren'Py attempts to predict the images that will be used in the future, and loads them into the image cache before they are used. When space in the cache is needed for other images, Ren'Py will remove images that are no longer being used.
By default, Ren'Py will predictively cache up to 8 screens worth of image data. (If your screen is 800x600, then a screen's worth of data is one 800x600 image, two 400x600 images, and so on.) This can be changed with the :var:config.image_cache_size configuration variable.
Although the precise amount is dependent on implementation details and there is significant overhead, as a rule of thumb, each pixel in the image cache consumes 4 bytes of main memory and 4 bytes of video memory.
We call these displayables image-like because they take up a rectangular area of the screen, and do not react to input. These differ from normal images by varying their size to fill an area (Frame, LiveTile, and Solid), or by allowing the user to specify their size (LiveComposite, LiveCrop, Null). They are not image manipulators.
Image-like displayables take Position Style Properties.
AlphaMask(child, mask, **properties) link
This displayable takes its colors from child, and its alpha channel from the multiplication of the alpha channels of child and mask. The result is a displayable that has the same colors as child, is transparent where either child or mask is transparent, and is opaque where child and mask are both opaque.
The child and mask parameters may be arbitrary displayables. The size of the AlphaMask is the size of the overlap between child and mask.
Note that this takes different arguments from
which uses the mask's color channel.
Borders(left, top, right, bottom, pad_left=0, pad_top=0, pad_right=0, pad_bottom=0) link
left top right bottom
These provide the size of the insets used by a frame, and are added to the padding on each side. They should zero or a positive integer.
pad_left pad_top pad_right pad_bottom
These are added to the padding on each side, and may be positive or negative. (For example, if left is 5 and pad_left is -3, the final padding is 2.)
The padding information is supplied via a field:
This is a four-element tuple containing the padding on each of the four sides.
A DynamicImage is a displayable that has text interpolation performed on it to yield a string giving a new displayable. Such interpolation is performed at the start of each interaction.
Flatten(child, **properties) link
This flattens child, which may be made up of multiple textures, into a single texture.
Certain operations, like the alpha transform property, apply to every texture making up a displayable, which can yield incorrect results when the textures overlap on screen. Flatten creates a single texture from multiple textures, which can prevent this problem.
Flatten is a relatively expensive operation, and so should only be used when absolutely required.
Frame(image, left=0, top=0, right=None, bottom=None, tile=False, **properties) link
A displayable that resizes an image to fill the available area, while preserving the width and height of its borders. is often used as the background of a window or button.
Borders()object, in which case that object is use in place of the other parameters.
# Resize the background of the text window if it's too small. init python: style.window.background = Frame("frame.png", 10, 10)
LiveComposite(size, *args, **properties) link
This creates a new displayable of size, by compositing other displayables. size is a (width, height) tuple.
The remaining positional arguments are used to place images inside the LiveComposite. The remaining positional arguments should come in groups of two, with the first member of each group an (x, y) tuple, and the second member of a group is a displayable that is composited at that position.
Displayables are composited from back to front.
image eileen composite = LiveComposite( (300, 600), (0, 0), "body.png", (0, 0), "clothes.png", (50, 50), "expression.png")
LiveCrop(rect, child, **properties) link
This created a displayable by cropping child to rect, where rect is an (x, y, width, height) tuple.
image eileen cropped = LiveCrop((0, 0, 300, 300), "eileen happy")
LiveTile(child, style='tile', **properties) link
Tiles child until it fills the area allocated to this displayable.
image bg tile = LiveTile("bg.png")
Null(width=0, height=0, **properties) link
A displayable that creates an empty box on the screen. The size of the box is controlled by width and height. This can be used when a displayable requires a child, but no child is suitable, or as a spacer inside a box.
image logo spaced = HBox("logo.png", Null(width=100), "logo.png")
Solid(color, **properties) link
A displayable that fills the area its assigned with color.
image white = Solid("#fff")
Dynamic displayables display a child displayable based on the state of the game. They do not take any properties, as layout is controlled by the properties of the child displayable they return.
ConditionSwitch(*args, **kwargs) link
This is a displayable that changes what it is showing based on python conditions. The positional argument should be given in groups of two, where each group consists of:
The first true condition has its displayable shown, at least one condition should always be true.
image jill = ConditionSwitch( "jill_beers > 4", "jill_drunk.png", "True", "jill_sober.png")
DynamicDisplayable(function, *args, **kwargs) link
A displayable that can change its child based on a Python function, over the course of an interaction.
A function that is called with the arguments:
and should return a (d, redraw) tuple, where:
function is called at the start of every interaction.
As a special case, function may also be a python string that evaluates to a displayable. In that case, function is run once per interaction.
# If tooltip is not empty, shows it in a text. Otherwise, # show Null. Checks every tenth of a second to see if the # tooltip has been updated. init python: def show_tooltip(st, at): if tooltip: return tooltip, .1 else: return Null(), .1 image tooltipper = DynamicDisplayable(show_tooltip)
ShowingSwitch(*args, **kwargs) link
This is a displayable that changes what it is showing based on the images are showing on the screen. The positional argument should be given in groups of two, where each group consists of:
A default image should be specified.
One use of ShowingSwitch is to have side images change depending on the current emotion of a character. For example:
define e = Character("Eileen", show_side_image=ShowingSwitch( "eileen happy", Image("eileen_happy_side.png", xalign=1.0, yalign=1.0), "eileen vhappy", Image("eileen_vhappy_side.png", xalign=1.0, yalign=1.0), None, Image("eileen_happy_default.png", xalign=1.0, yalign=1.0), ) )
The At function produces a displayable from a displayable and one or more transforms.
At(d, *args) link
Given a displayable d, applies each of the transforms in args to it. The transforms are applied in left-to-right order, so that the outermost transform is the rightmost argument.
transform birds_transform: xpos -200 linear 10 xpos 800 pause 20 repeat image birds = At("birds.png", birds_transform)
Layout boxes are displayables that lay out their children on the screen. They can lay out the children in a horizontal or vertical manner, or can lay them out using the standard positioning algorithm.
The box displayables take any number of positional and keyword arguments. Positional arguments should be displayables that are added to the box as children. Keyword arguments are style properties that are applied to the box.
Fixed(*args, **properties) link
A box that fills the screen. Its members are laid out from back to front, with their position properties controlling their position.
HBox(*args, **properties) link
A box that lays out its members from left to right.
VBox(*args, **properties) link
A layout that lays out its members from top to bottom.
# Display two logos, to the left and right of each other. image logo hbox = HBox("logo.png", "logo.png") # Display two logos, one on top of the other. image logo vbox = VBox("logo.png", "logo.png") # Display two logos. Since both default to the upper-left # corner of the screen, we need to use Image to place # those logos on the screen. image logo fixed = Fixed( Image("logo.png", xalign=0.0, yalign=0.0), Image("logo.png", xalign=1.0, yalign=1.0))
Grid(*args, **properties) link
Lays out displayables in a a grid. The first two positional arguments are the number of columns and rows in the grid. This must be followed by columns * rows positional arguments giving the displayables that fill the grid.
These displayables are used to create certain visual effects.
AlphaBlend(control, old, new, alpha=False) link
This transition uses a control displayable (almost always some sort of animated transform) to transition from one displayable to another. The transform is evaluated. The new displayable is used where the transform is opaque, and the old displayable is used when it is transparent.
An image manipulator is a displayable that takes an image or image manipulator, performs an operation to it, and stores the result of that operation in the image cache. Since image manipulators can be predicted like images, they can perform expensive operations without incuring a display-time overhead.
Image manipulators are limited to storing image data to the cache. This means that their result is of a fixed size, known in advance, and they can't change in response to game state or input. Generally, image manipulators can only take images or other image manipulators as input.
An image manipulator can be used any place a displayable can, but not
Image() is a kind of image manipulator, so an
Image can be used whenever an image manipulator is required.
Many image manipulators provide the same functionality as other displayables. Most of these exist so they can be provided as input to other image manipulators, and so the game-maker can choose between cache memory usage and work done at render-time. There's also an element of historical accident here - many of these image manipulators predate their equivalents.
AlphaMask(base, mask, **properties) link
An image manipulator that takes two image manipulators, base and mask, as arguments. It replaces the alpha channel of base with the red channel of mask.
This is used to provide an image's alpha channel in a second image, like having one jpeg for color data, and a second one for alpha. In some cases, two jpegs can be smaller than a single png file.
Note that this takes different arguments from
which uses the mask's alpha channel.
Composite(size, *args, **properties) link
This image manipulator composites multiple images together to form a single image.
The size should be a (width, height) tuple giving the size of the composed image.
The remaining positional arguments are interpreted as groups of two. The first argument in a group should be an (x, y) tuple, while the second should be an image manipulator. The image produced by the image manipulator is composited at the location given by the tuple.
image girl clothed happy = im.Composite( (300, 600), (0, 0), "girl_body.png", (0, 0), "girl_clothes.png", (100, 100), "girl_happy.png" )
Crop(im, rect) link
An image manipulator that crops rect, a (x, y, width, height) tuple, out of im, an image manipulator.
image logo crop = im.Crop("logo.png", (0, 0, 100, 307))
FactorScale(im, width, height=None, bilinear=True, **properties) link
An image manipulator that scales im (a second image manipulator) to width times its original width, and height times its original height. If height is omitted, it defaults to width.
If bilinear is true, then bilinear interpolation is used for the scaling. Otherwise, nearest neighbor interpolation is used.
image logo doubled = im.FactorScale("logo.png", 1.5)
Flip(im, horizontal=False, vertical=False, **properties) link
An image manipulator that flips im (an image manipulator) vertically or horizontally. vertical and horizontal control the directions in which the image is flipped.
image eileen flip = im.Flip("eileen_happy.png", vertical=True)
Grayscale(im, **properties) link
An image manipulator that creates a desaturated version of the image manipulator im.
Scale(im, width, height, bilinear=True, **properties) link
An image manipulator that scales im (an image manipulator) to width and height.
If bilinear is true, then bilinear interpolation is used for the scaling. Otherwise, nearest neighbor interpolation is used.
image logo scale = im.Scale("logo.png", 100, 150)
Sepia(im, **properties) link
An image manipulator that creates a sepia-toned version of the image manipulator im.
The im.MatrixColor image manipulator is an image manipulator that uses a matrix to control how the colors of an image are transformed. The matrix used can be an im.matrix object, which encodes a 5x5 matrix in an object that supports matrix multiplication, and is returned by a series of functions. im.matrix objects may be multiplied together to yield a second object that performs both operations. For example, the code:
image city blue = im.MatrixColor( "city.jpg", im.matrix.desaturate() * im.matrix.tint(0.9, 0.9, 1.0))
first desaturates the image, and then tints it blue. When the intermediate image is not needed, multiplying matrices is far more efficient, in both time and image cache space, than using two im.MatrixColors.
MatrixColor(im, matrix, **properties) link
An image operator that uses matrix to linearly transform the image manipulator im.
Matrix should be a list, tuple, or
im.matrix() that is 20
or 25 elements long. If the object has 25 elements, then elements
past the 20th are ignored.
When the four components of the source color are R, G, B, and A, which range from 0.0 to 1.0; the four components of the transformed color are R', G', B', and A', with the same range; and the elements of the matrix are named:
[ a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t ]
the transformed colors can be computed with the formula:
R' = (a * R) + (b * G) + (c * B) + (d * A) + e G' = (f * R) + (g * G) + (h * B) + (i * A) + j B' = (k * R) + (l * G) + (m * B) + (n * A) + o A' = (p * R) + (q * G) + (r * B) + (s * A) + t
The components of the transformed color are clamped to the range [0.0, 1.0].
Constructs an im.matrix object from matrix. im.matrix objects support The operations supported are matrix multiplication, scalar multiplication, element-wise addition, and element-wise subtraction. These operations are invoked using the standard mathematical operators (*, *, +, and -, respectively). If two im.matrix objects are multiplied, matrix multiplication is performed, otherwise scalar multiplication is used.
matrix is a 20 or 25 element list or tuple. If it is 20 elements long, it is padded with (0, 0, 0, 0, 1) to make a 5x5 matrix, suitable for multiplication.
Returns an im.matrix that alters the brightness of an image.
colorize(black_color, white_color) link
Returns an im.matrix that colorizes a black and white image. black_color and white_color are Ren'Py style colors, so they may be specified as strings or tuples of (0-255) color values.
# This makes black colors red, and white colors blue. image logo colored = im.MatrixColor( "bwlogo.png", im.matrix.colorize("#f00", "#00f"))
Returns an im.matrix that alters the contrast of an image. c should be greater than 0.0, with values between 0.0 and 1.0 decreasing contrast, and values greater than 1.0 increasing contrast.
Returns an im.matrix that desaturates the image (makes it grayscale). This is equivalent to calling im.matrix.saturation(0).
Returns an im.matrix that rotates the hue by h degrees, while preserving luminosity.
Returns an identity matrix, one that does not change color or alpha.
Returns an im.matrix that inverts the red, green, and blue channels of the image without changing the alpha channel.
Returns an im.matrix that alters the opacity of an image. An o of 0.0 is fully transparent, while 1.0 is fully opaque.
saturation(level, desat=(0.2126, 0.7152, 0.0722)) link
Returns an im.matrix that alters the saturation of an image. The alpha channel is untouched.
tint(r, g, b) link
Returns an im.matrix that tints an image, without changing the alpha channel. r, g, and b should be numbers between 0 and 1, and control what fraction of the given channel is placed into the final image. (For example, if r is .5, and the value of the red channel is 100, the transformed color will have a red value of 50.)
The Placeholder displayable is used to display background or character images as appropriate. Placeholders are used automatically when an undefined image is used in developer mode. Placeholder displayables can also be used manually when the defaults are inappropriate.
# By default, the girl placeholer will be used. image sue = Placeholder("boy") label start: show sue angry "Sue" "How do you do? Now you gonna die!"
Placeholder(base=None, full=False, flip=None, **properties) link
This displayable can be used to display a placeholder character or background.
The type of image to display. This should be one of:
Attempts to automatically determine the type of image to use. If the image name begins with "bg", "cg", or "event", uses 'bg'.
Otherwise, contacts a web service to guess gender from the character's name, and uses that. (The 'girl' placeholder is used when the service can't guess.)
The webservice will only be contacted when config.developer is True.