Images

The most commonly used displayable is Image, which loads a file fromdisk and displays it. Since Image is so commonly used, when a stringgiving a filename is used in a context that expects a displayable, anImage is automatically created. The only time it's necessary to useImage directly is when you want to create an image with styleproperties.

Image(filename,*,optimize_bounds=True,oversample=1,dpi=96,mipmap=None,**properties)

Loads an image from a file.filename is astring giving the name of the file.

filename

This should be an image filename, including the extension.

optimize_bounds

If true, only the portion of the image thatinside the bounding box of non-transparent pixels is loaded intoGPU memory. (The only reason to set this to False is when using animage as input to a shader.)

oversample

If this is greater than 1, the image is considered to be oversampled,with more pixels than its logical size would imply. For example, ifan image file is 2048x2048 and oversample is 2, then the image willbe treated as a 1024x1024 image for the purpose of layout.

dpi

The DPI of an SVG image. This defaults to 96, but that can beincreased to render the SVG larger, and decreased to renderit smaller.

mipmap

If this is "auto", then mipmaps are generated for the image only if the game is scaled down to less than75% of its default size. If this is True, mipmaps are always generated. If this is False, mipmaps are nevergenerated. If this is None, then the default is taken from config.mipmap.

# 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)

There are four image file formats we recommend you use:

• AVIF

• WEBP

• PNG

• JPG

And one vector image file format we recommend:

• SVG

Non-animated GIF and BMP files are also supported, but should not beused in modern games.

Loading an Image from a file on disk and decoding it so it can bedrawn to the screen takes a long amount of time. While measured in thetenths or hundreds of seconds, the duration of the loading process islong enough that it can prevent an acceptable framerate, and becomeannoying to the user.

Since an Image is of a fixed size, and doesn't change in response toinput, game state, or the size of the area available to it, an Imagecan be loaded before it is needed and placed into an area of memoryknown 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 spacein the cache is needed for other images, Ren'Py will remove imagesthat are no longer being used.

By default, Ren'Py will predictively cache up to 8 screens worth ofimage data. (If your screen is 800x600, then a screen's worth of datais one 800x600 image, two 400x600 images, and so on.) This can bechanged with theconfig.image_cache_size configurationvariable.

Although the precise amount is dependent on implementation details andthere is significant overhead, as a rule of thumb, each pixel in theimage cache consumes 4 bytes of main memory and 4 bytes of videomemory.

SVG Images

Ren'Py supports many SVG 1.0 images, using the NanoSVG library.Some unsupported features include:

• Text elements are ignored. If the text is converted into a path, it willbe rendered.

• Embedded bitmaps are ignored.

• Scripts are ignored.

• Animations are ignored.

A list of features NanoSVG supports may be foundhere.

It's recommended to convert everything in an SVG image that will notrender properly into paths.

Ren'Py will render SVG images as if the virtual screen was 96dpi.If the window is enlarged or shrunk, the SVG image will be scaledup or down, respectively, andoversampling willbe used to ensure the image is rendered at the correct virtualsize.

This ensures the SVG will be rendered sharp if it is not scaled.

Image-Like Displayables

We call these displayables image-like because they take up arectangular area of the screen, and do not react to input. Thesediffer from normal images by varying their size to fill an area(Frame, Tile, and Solid), or by allowing the user to specify theirsize (Composite, Crop, Null). They are not image manipulators.

Image-like displayables takePosition Style Properties.

classAlphaMask(child,mask,invert=False,**properties)

This displayable takes its colors fromchild, and its alpha channelfrom the multiplication of the alpha channels ofchild andmask.The result is a displayable that has the same colors aschild, istransparent where eitherchild ormask is transparent, and isopaque wherechild andmask are both opaque.

Thechild andmask parameters may be arbitrary displayables. Thesize of the AlphaMask is the size ofchild. Theinvert parametercan be used to invert the mask's alpha channel.

Note that this takes different arguments fromim.AlphaMask(),which uses the mask's red channel.

classBorders(left,top,right,bottom,pad_left=0,pad_top=0,pad_right=0,pad_bottom=0)

This object provides border size and tiling information to aFrame().It can also provide padding information that can be supplied to thepadding style property of a window or frame.

left,top,right,bottom

These provide the size of the insets used by a frame, and are addedto the padding on each side. They should be 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 ornegative. (For example, ifleft is 5 andpad_left is -3, the finalpadding is 2.)

The padding information is supplied via a field:

padding

This is a four-element tuple containing the padding on each of thefour sides.

Composite(size,*args,**properties)

This creates a new displayable ofsize, by compositing otherdisplayables.size is a (width, height) tuple.

The remaining positional arguments are used to place images insidethe Composite. The remaining positional arguments should comein groups of two, with the first member of each group an (x, y)tuple, and the second member of a group is a displayable thatis composited at that position.

Displayables are composited from back to front.

imageeileencomposite=Composite((300,600),(0,0),"body.png",(0,0),"clothes.png",(50,50),"expression.png")

Crop(rect,child,**properties)

This creates a displayable by croppingchild torect, whererect is an (x, y, width, height) tuple.

imageeileencropped=Crop((0,0,300,300),"eileen happy")

classDynamicImage(name)

A DynamicImage is a displayable that has text interpolation performedon it to yield a string giving a new displayable. Such interpolation isperformed at the start of each interaction.

classFlatten(child,drawable_resolution=True,**properties)

This flattenschild, which may be made up of multiple textures, intoa single texture.

Certain operations, like the alpha transform property, apply to everytexture making up a displayable, which can yield incorrect resultswhen the textures overlap on screen. Flatten creates a single texturefrom multiple textures, which can prevent this problem.

Flatten is a relatively expensive operation, and so should only be usedwhen absolutely required.

drawable_resolution

Defaults to true, which is usually the right choice, but may causethe resulting texture, when scaled, to have different artifacts thanthe textures that make it up. Setting this to False will change theartifacts, which may be more pleasing in some cases.

classFrame(image,left=0,top=0,right=None,bottom=None,*,tile=False,**properties)

A displayable that resizes an image to fill the available area,while preserving the width and height of its borders. It is oftenused as the background of a window or button.

image

An image manipulator that will be resized by this frame.

left

The size of the border on the left side. This can also be aBorders() object, in which case that object is used in placeof the other parameters.

top

The size of the border on the top.

right

The size of the border on the right side. If None, defaultstoleft.

bottom

The side of the border on the bottom. If None, defaults totop.

tile

If set to True, tiling is used to resize sections of the image,rather than scaling. If set to the string "integer", the nearestinteger number of tiles will be used in each direction. That set offull tiles will then be scaled up or down to fit the required area.

# Resize the background of the text window if it's too small.initpython:style.window.background=Frame("frame.png",10,10)

classNull(width=0,height=0,**properties)

A displayable that creates an empty box on the screen. The sizeof the box is controlled bywidth andheight. This can be usedwhen a displayable requires a child, but no child is suitable, oras a spacer inside a box.

imagelogospaced=HBox("logo.png",Null(width=100),"logo.png")

classSolid(color,**properties)

A displayable that fills the area its assigned withcolor.

imagewhite=Solid("#fff")

classTile(child,style='tile',**properties)

Tileschild until it fills the area allocated to this displayable.

imagebgtile=Tile("bg.png")

Text Displayables

SeeText Displayables.

Dynamic Displayables

Dynamic displayables display a child displayable based on the state ofthe game.

Note that these dynamic displayables always display their current state.Because of this, a dynamic displayable will not participate in atransition. (Or more precisely, it will display the same thing in both theold and new states of the transition.)

By design, dynamic displayables are intended to be used for things thatchange rarely and when an image defined this way is off screen (Such asa character customization system). It is not designed for things thatchange frequently, such as character emotions.

ConditionSwitch(*args,predict_all=None,**properties)

This is a displayable that changes what it is showing based onPython conditions. The positional arguments should be given ingroups of two, where each group consists of:

• A string containing a Python condition.

• A displayable to use if the condition is true.

The first true condition has its displayable shown, at leastone condition should always be true.

The conditions uses here should not have externally-visible side-effects.

predict_all

If True, all of the possible displayables will be predicted whenthe displayable is shown. If False, only the current condition ispredicted. If None,config.conditionswitch_predict_all isused.

imagejill=ConditionSwitch("jill_beers > 4","jill_drunk.png","True","jill_sober.png")

classDynamicDisplayable(function,*args,**kwargs)

A displayable that can change its child based on a Pythonfunction, over the course of an interaction. It does nottake any properties, as its layout is controlled by theproperties of the child displayable it returns.

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 maximum amount of time to wait before calling thefunction again, or None to not require the function be called againbefore 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 evaluatesto a displayable. In that case, function is run once per interaction.

# Shows a countdown from 5 to 0, updating it every tenth of# a second until the time expires.initpython:defshow_countdown(st,at):ifst>5.0:returnText("0.0"),Noneelse:d=Text("{:.1f}".format(5.0-st))returnd,0.1imagecountdown=DynamicDisplayable(show_countdown)

ShowingSwitch(*args,predict_all=None,**properties)

This is a displayable that changes what it is showing based on theimages are showing on the screen. The positional argument shouldbe given in groups of two, where each group consists of:

• A string giving an image name, or None to indicate the default.

• A displayable to use if the condition is true.

A default image should be specified.

predict_all

If True, all of the possible displayables will be predicted whenthe displayable is shown. If False, only the current condition ispredicted. If None,config.conditionswitch_predict_all isused.

One use of ShowingSwitch is to have images change depending onthe current emotion of a character. For example:

imageemotion_indicator=ShowingSwitch("eileen concerned","emotion_indicator concerned","eileen vhappy","emotion_indicator vhappy",None,"emotion_indicator happy")

Layer Displayables

Layer displayables display the contents of a layer based on the state of thegame. They are intended for use withconfig.detached_layers.

Note that similar to dynamic displayables, the layers shown within alwaysdisplay their current state. Because of this, the contents of a layerdisplayable will not participate in a transition, unless that transition istargeted at the layer being displayed.

classLayer(layer,*,clipping=True,**properties)

This allows a layer to be shown as a displayable on another layer.Intended for use with detached layers.

Trying to display a layer on itself is not supported.

layer

The layer to display.

clipping

If False, the layer's contents may exceed its bounds, otherwiseanything exceeding the bounds will be trimmed.

An entry in config.layer_clipping will cause this option to beignored, and clipping to occur as specified by that config.

# A new detached layer to hold the contents of a broadcast.defineconfig.detached_layers+=["broadcast"]# A layer displayable to represent a TV and watch the broadcast layer.imagetv=Window(Layer("broadcast"),background='#000',padding=(10,10),style="default")imageliving_room=Placeholder('bg',text='living_room')imagestudio=Solid('7c7')imageeileen=Placeholder('girl')labelexample:pause# Set up the broadcast scene.scenestudioonlayerbroadcastwithNone# Begin a new scene in the living room.sceneliving_room# Show the TV in the lower right corner of ths screen.showtv:align(.75,.75)zoom.3# Show Eileen in the broadcast.showeileenonlayerbroadcast# Dissolve into the living room, as Eileen enters the TV from the right.with{'master':dissolve,'broadcast':moveinright}pause

Layout Boxes and Grids

Layout boxes are displayables that lay out their children on thescreen. They can lay out the children in a horizontal or verticalmanner, or lay them out using the standard positioning algorithm.

The box displayables take any number of positional and keywordarguments. Positional arguments should be displayables that areadded to the box as children. Keyword arguments are style propertiesthat are applied to the box.

Boxes takePosition Style Properties andBox Style Properties.

Fixed(*args,**properties)

A box that fills the screen. Its members are laid outfrom back to front, with their position propertiescontrolling their position.

HBox(*args,**properties)

A box that lays out its members from left to right.

VBox(*args,**properties)

A layout that lays out its members from top to bottom.

# 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))

The Grid layout displays its children in a grid on the screen. It takesPosition Style Properties and thespacing styleproperty.

Grid(cols,rows,*args,**properties)

Lays out displayables in a grid. The first two positional argumentsare the number of columns and rows in the grid. This must be followedbycolumns * rows positional arguments giving the displayables thatfill the grid.

Effects

These displayables are used to create certain visual effects.

AlphaBlend(control,old,new,alpha=False)

This transition uses acontrol displayable (almost always some sort ofanimated transform) to transition from one displayable to another. Thetransform is evaluated. Thenew displayable is used where the transformis opaque, and theold 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.

Image Manipulators

Image manipulators are an historic kind of displayables thatapply transformations or operations exclusively to other images or imagemanipulators - to the exclusion of the other kinds of displayables.

An image manipulator can be used any place a displayable can, but notvice-versa. AnImage() is a kind of image manipulator, so anImage can be used whenever an image manipulator is required.

Their use is historic. A number of image manipulators that had been documentedin a distant past should no longer be used, as they suffer from inherentproblems, and in general (except forim.Data()), theTransform()displayable provides similar functionality while fixing the problems.

For the list of image manipulators, see theimage manipulatordocumentation.

Placeholders

The Placeholder displayable is used to display background or characterimages as appropriate. Placeholders are used automatically when an undefinedimage is used in developer mode. Placeholder displayables can also be usedmanually when the defaults are inappropriate.

# By default, the girl placeholder will be used.imagesue=Placeholder("boy")labelstart:showsueangry"Sue""How do you do? Now you gonna die!"

classPlaceholder(base=None,full=False,flip=None,text=None,**properties)

This displayable can be used to display a placeholder character orbackground.

base

The type of image to display. This should be one of:

'bg'

To display a background placeholder. This currentlyfills the screen with a light-gray, and displaysthe image name at the top of the screen.

'boy'

Displays a male-identified placeholder with the imagename on his chest.

'girl'

Displays a female-identified placeholder with the imagename on her chest.

None

Attempts to automatically determine the type of imageto use. If the image name begins with "bg", "cg", or"event", uses 'bg'.

Otherwise, the 'girl' placeholder is used.

full

If true, a full-body sprite is used. Otherwise, a 3/4 spriteis used.

flip

If true, the sprite is flipped horizontally.

text

If provided, no other text than this will be displayed on theplaceholder. If not, the text will reflect the showinstruction that was used to display it.

Displayable Prefixes

Displayable prefixes make it possible for a creator to define their owndisplayables, and refer to them anywhere a displayable can be used inRen'Py. A prefixed displayable is a string with a colon in it. The prefixis to the left of the colon, and the argument is anything to the right ofit. Theconfig.displayable_prefix variable maps a prefix to a function.The function takes the argument, and either returns a displayable or None.

For example, this makes the big prefix return an image that is twice asbig as the original.

init-10python:defembiggen(s):returnTransform(s,zoom=2)config.displayable_prefix["big"]=embiggen

Theinit-10 makes sure the prefix is defined before any images that use it.The prefix can then be used to define images:

imageeileenbig="big:eileen happy"

or in any other place where a displayable is required.

See also

Displaying Images : the basics of how to make all these displayablesappear on the screen.