Previous topic

Next topic

Search

A displayable is an object that can be shown to the user. Ren'Py
displayables can be used in many ways.

Assignment to an image name using the image statement.

Added to a screen using the screen language add statement.

Assignment to certain config variables.

Assignment to certain style properties.

When a Ren'Py function or variable expects a displayable, there are
four things that can be provided:

An object of type Displayable, created by calling one of the
functions given below.

A string with a dot (.) in it. Such a string is interpreted as
a filename by Image().

A color. A color may either be given as a hexadecimal color string in "#rgb",
"#rgba", "#rrggbb", or "#rrggbbaa" form, or an (r, g, b, a) tuple,
where each component is an integer between 0 and 255. Colors are
passed to Solid().

An image name. Any other string is interpreted as a reference to an
image defined with the image statement.

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.

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.imagelogo="logo.png"imagelogo=Image("logo.png")# Using Image allows us to specify a default position as part of# an image.imagelogoright=Image("logo.png",xalign=1.0)

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.

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.

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.

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.

A displayable that can change its child based on a Python
function, over the course of an interaction.

function

A function that is called with the arguments:

The amount of time the displayable has been shown for.

The amount of time any displayable with the same tag has been shown for.

Any positional or keyword arguments supplied to DynamicDisplayable.

and should return a (d, redraw) tuple, where:

d is a displayable to show.

redraw is the amount of time to wait before calling the
function again, or None to not call the function again
before the start of the next interaction.

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.initpython:defshow_tooltip(st,at):iftooltip:returntooltip,.1else:returnNull()imagetooltipper=DynamicDisplayable(show_tooltip)

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.

# Display two logos, to the left and right of each other.imagelogohbox=HBox("logo.png","logo.png")# Display two logos, one on top of the other.imagelogovbox=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.imagelogofixed=Fixed(Image("logo.png",xalign=0.0,yalign=0.0),Image("logo.png",xalign=1.0,yalign=1.0))

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.

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.

alpha

If true, the image is composited with what's behind it. If false,
the default, the image is opaque and overwrites what's behind it.

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
vice-versa. An 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.

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.

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:

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.

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:

Returns an im.matrix that alters the saturation of an
image. The alpha channel is untouched.

level

The amount of saturation in the resulting image. 1.0 is
the unaltered image, while 0.0 is grayscale.

desat

This is a 3-element tuple that controls how much of the
red, green, and blue channels will be placed into all
three channels of a fully desaturated image. The default
is based on the constants used for the luminance channel
of an NTSC television signal. Since the human eye is
mostly sensitive to green, more of the green channel is
kept then the other two channels.

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.imagesue=Placeholder("boy")labelstart:showsueangry"Sue""How do you do? Now you gonna die!"