Displayable link

displayable は、ユーザーに表示されるオブジェクトです。Ren'Py の displayable には多くの用途があります。

  • image ステートメントを使って画像名に代入する。

  • screen 言語の add ステートメントを使って screen に追加する。

  • 設定変数に代入する。

  • スタイルプロパティーに代入する。

displayable を受け取る Ren'Py の関数や変数には、次の指定できます。 :

  • 後述の関数のいずれかを呼び出して作成された Displayable 型のオブジェクト。

  • : を含む文字列。滅多に使用されませんが、 displayable prefixes 節を参照してください。

  • ドット . を含む文字列。このような文字列は Image() によってファイル名として解釈されます。

  • カラー カラーは "#rgb", "#rgba", "#rrggbb", または "#rrggbbaa" の形式の 16 進数の文字列または、 Color クラス、 (r, g, b, a) のそれぞれが 0 から 255 までの整数のタプルで指定されます。カラーは Solid() に渡されます。

  • 画像名 上記以外の文字列は image ステートメントや image directory で定義された画像への参照として解釈されます。

  • リスト リストが指定されると、各要素は後述するように拡張され、ファイル名や画像名にマッチするか確認されます。マッチすれば拡張は止まり、マッチしたものが上述のように処理されます。

文字列には "eileen [mood]" や "eileen_[outfit]_[mood].png" のように1 つ以上の角括弧があるかもしれません。そのような文字列が指定されると、dynamic image が作成されます。dynamic image には各インタラクション(say または menu ステートメントなど)の開始時に処理される データの置換 があります。結果の文字列は上記のルールに基いて処理されます。

"[prefix_]" を含む文字列は、現在の displayable に対応する各スタイル接頭辞に置き換えられます。

画像 link

最もよく使われる displayable は Image です。これはディスクからファイルを読み込んで表示します。Image はよく使われるため、 displayable を期待する文脈にファイル名の文字列が使われると、その Image が自動的に作成されます。 Image を直接使う必要があるのは、スタイルプロパティーから画像を作成したいときだけです。

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

ファイルから画像をロードします。 filename はファイル名の文字列です。

filename

これは拡張子も含む画像ファイル名です。

optimize_bounds

True なら、画像のうち矩形領域内部の不透明なピクセルの部分のみが GPU メモリーにロードされます(これを False にするのは画像を shader への入力に使用するときのみです)。

oversample

この値が1より大きい場合、画像はオーバーサンプリングされ、論理的なサイズより多くのピクセルが使用されているとみなされます。例えば、2048x2048の画像ファイルに対してオーバーサンプルが2であれば、レイアウト上1024x1024の画像として扱われます。

dpi

SVG画像のDPIです。これはデフォルトでは96ですが、増やしてより大きな、減らしてより小さなSVG画像を描画できます。

mipmap

これが "auto" なら、ゲームがデフォルトサイズの 75% 未満に縮小された場合にのみ、画像のミップマップが生成されます。これが True なら、ミップマップは常に生成されます。これが False の場合、ミップマップは生成されません。 None の場合、デフォルトでは config.mipmap から所得します。

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

4つの画像ファイルフォーマットの使用を推奨します。 :

  • AVIF

  • WEBP

  • PNG

  • JPG

1つのベクター画像ファイルフォーマットの使用を推奨します。 :

  • SVG

ノンアニメーション Gif, Bmp ファイルもサポートしますが、近代的なゲームでは使用しないべきです。

画像をディスク上のファイルからロードし、それを画面に描画できるようにデコードするのには時間がかかります。数10 から数 100 分の1秒ほどになるので、ロード処理の所要時間は許容できるフレームレートに収まらず、ユーザーをいらいらさせます。

画像のサイズは一定で、また画像は入力やゲームの状態、利用できる空間の大きさに応じては変わりません。ですから必要になる前に画像を読み込み、画像キャッシュと呼ばれるメモリ空間に配置できます。画像をキャッシュにデコードしておけば、画面に素早く描画できます。

Ren'Py は、将来使われる画像を予想し、実際に使われる前にロードしようとします。キャッシュの空間を他の画像に使う必要ができたとき、Ren'Py は使われなくなった画像を消去します。

デフォルトでは、Ren'Py は前もって最大画像データ 8 画面分だけキャッシュします(画面が 800x600 なら、その画面は 800x600 の画像 1 枚、400x600 の画像 2 枚、などのデータに相当します)。 これは config.image_cache_size 設定変数で変更できます。

経験上、画像キャッシュはピクセルあたりメインメモリ 4 バイトとビデオメモリ 4 バイトを消費します。ただし、正確な量は実装によって、または無視できないオーバーヘッドがあるかどうかによって異なります。

SVG 画像 link

Ren'Py は NanoSVG ライブラリーを使用して、多くの SVG 1.0 画像をサポートします。いくつか未サポートの機能が含まれます。 :

  • テキスト要素は無視されます。テキストがパスに変換されていれば、描画されます。

  • 組み込みのビットマップは無視されます。

  • スクリプトは無視されます。

  • アニメーションは無視されます。

NanoSVG がサポートする機能のリストは こちらで みられます。

SVG画像の描画されないプロパティーのすべてはパスに変換を推奨します。

Ren'Py は SVG 画像を仮想スクリーンが 96dpi であるかのようにレンダリングします。ウィンドウが拡大または縮小された場合、SVG 画像はそれぞれ拡大または縮小され、 oversampling を使用して正しい仮想サイズでの画像レンダリングを保証します。

これはスケーリングされなければ SVG がシャープに描画されるようにします。

イメージライク displayable link

これらの displayable は長方形の領域であり、入力に反応しないことからイメージライクであると呼びます。これらは普通の画像と異なり、領域を満たすように大きさを変えたり (Frame, Tile, および Solid)、ユーザーが大きさを指定できたり (Composite, LiveCrop, Null) します。画像マニピュレータではありません。

イメージライク displayable は 位置スタイルプロパティー を取ります。

class AlphaMask(child, mask, invert=False, **properties) link

この displayable は child から色を取り出し、そのアルファチャンネルは child と mask のアルファチャンネルを乗算したものになります。結果として child と同じ色で、 child か mask どちらかで透明な部分が透明になり、 child と mask 両方で不透明な部分が不透明になります。

child と mask パラメーターは任意の displayable にできます。 AlphaMask のサイズは child のサイズになります。 invert パラメーターを使用してマスクのアルファチャンネルを反転できます。

mask のred チャンネルを使用する im.AlphaMask() とは別の引数をとることに注意してください。

class Borders(left, top, right, bottom, pad_left=0, pad_top=0, pad_right=0, pad_bottom=0) link

このオブジェクトは境界のサイズとタイリングの情報を Frame() に与えます。これはウィンドウやフレームの padding スタイルプロパティーに指定されるパッディング情報も渡せます。

left, top, right, bottom

これらはフレームに使用される挿入図のサイズを提供し、各サイズが各側面のパッディングに加えられます。これらは 0 または 正の整数であるべきです。

pad_left, pad_top, pad_right, pad_bottom

これらは各側面のパディングに加えられ、 正または負です ( 例えば、 left が 5, pad_left が -3 なら、最終的なパディングは 2 です )。

パッディング情報はフィールドとして渡します。

padding link

これは 4 要素のタプルで、各4つの側面のパディングを含みます。

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

これは他の displayable を合成して size の新しい displayable を作成します。 size は (width, height) のタプルです。

残りの位置引数は Composite 内に画像を配置するために使用されます。残りの位置引数は各グループの第一要素が (x, y) のタプルで、第二要素がその位置に合成される displayable の 2 つからなります。

Displayable は後ろから前へ合成されます。

image eileen composite = Composite(
    (300, 600),
    (0, 0), "body.png",
    (0, 0), "clothes.png",
    (50, 50), "expression.png")
Crop(rect, child, **properties) link

child を rect に刈りこんで displayable を作成します。ここで rect は (x, y, width, height) タプルです。

image eileen cropped = Crop((0, 0, 300, 300), "eileen happy")
class DynamicImage(name) link

dynamic image はテキスト置換により新しい displayable の文字列を生成するテキストを持つ displayable です。そのような置換は各インタラクションの開始時に処理されます。

class Flatten(child, drawable_resolution=True, **properties) link

これは複数のテクスチャで構成された child を一つのテクスチャに貼り付けます。

alpha transform プロパティーのような特定の処理は displayable を構成するすべてのテクスチャに適用され、スクリーン上でテクスチャが重なり合っていると誤った結果になる可能性があります。貼り付けは複数のテクスチャから一つのテクスチャを作成し、この問題を防ぎます。

貼り付けは比較的重い処理なので絶対的に必要なときのみ使用するべきです。

drawable_resolution

デフォルトでは True であり、通常は正しい選択ですが、スケーリングされたときに、テクスチャーにノイズが発生する可能性があります。 False に設定すると、ノイズが変わり、場合によってはより好ましいものになる可能性があります。

class Frame(image, left=0, top=0, right=None, bottom=None, *, tile=False, **properties) link

境界の幅と高さを保ちながら、利用できる領域を満たすようにリサイズする displayable です。ウィンドウやボタンの背景によく使われます。

_images/frame_example.png

フレームを使用し、画像サイズを2倍にリサイズ。 link

image

Frame によって大きさを変えられる画像マニピュレータです。

left

左側面の境界サイズです。これは Borders() オブジェクトでもよく、その場合オブジェクトは他のパラメーターの位置にも使用されます。

top

上側の境界のサイズです。

right

右側の境界のサイズです。None なら、デフォルトでは left です。

bottom

下側の境界のサイズです。None なら、デフォルトでは top です。

tile

True なら、拡大でなくタイル張りによって画像領域をリサイズします。文字列 "integer" に設定されると、各方向に最も近い整数個のタイルが使用されます。必要な領域に一致するようすべてのタイルが拡大縮小されます。

# Resize the background of the text window if it's too small.
init python:
    style.window.background = Frame("frame.png", 10, 10)
class Null(width=0, height=0, **properties) link

画面上に空のボックスを作成する displayable です。このボックスの大きさは width と height で制御できます。これは、displayable が子を要求しているが適切な子が無いときや、ボックス内の空間を埋めるのに使えます。

image logo spaced = HBox("logo.png", Null(width=100), "logo.png")
class Solid(color, **properties) link

割り当てられた領域を color で満たす displayable です。

image white = Solid("#fff")
class Tile(child, style='tile', **properties) link

この displayable に割り当てられた領域まで child をタイル張りします。

image bg tile = Tile("bg.png")

Text Displayables link

Text Displayables 参照。

動的 displayable link

動的 Displayable はゲームの状態に合わせて子 Displayable を表示します。

これらの動的 displayable は常にその現在の状態を表示します。このため、動的 displayable はトランジションに参加せず(ないしは正しく参加しません)、トランジション前後の両方の状態で同様に表示されます。

動的 displayable はめったに変更しないものや (キャラクターカスタマイズのように) この方法で定義された画像が画面上にないときの使用を想定しています。キャラクターの表情のように頻繁に変わる物は想定していません。

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

これは、Python 条件式に基づいて表示するものを変える displayable です。位置引数は、次を二つ一組にまとめて指定しなければなりません:

  • Python 式を含む文字列

  • 条件式が True の時に使う displayable

最初に True になった条件式の displayable が表示され、少なくとも一つの条件式が True にならなければなりません。

ここで使用する条件は外部から可視である副作用をもつべきではありません。

predict_all

True なら、起こりうるすべての displayable がその表示時に予測されます。　False なら、現在の条件でのみ予測されます。None なら config.conditionswitch_predict_all が使用されます。

image jill = ConditionSwitch(
    "jill_beers > 4", "jill_drunk.png",
    "True", "jill_sober.png")
class DynamicDisplayable(function, *args, **kwargs) link

Pythonの関数に基づき、インタラクションの過程でその子を変更できる displayable です。そのレイアウトは関数が返す子 displayable のプロパティによって制御されるため、どんなプロパティも取りません。

function

次の引数を渡して呼び出される関数です :

  • その displayable が表示されている時間

  • 同じタグの displayable が表示されている時間。

  • DynamicDisplayable に渡された任意の位置引数とキーワード引数。

これは (d, redraw) タプルを返すべきです。ここで :

  • d は表示する displayable です。

  • redraw は、関数を再び呼び出すまでの最大待ち時間です。None にすると、次のインタラクションが始まるまでもうこの関数は呼び出されません。

function は、インタラクションが始まるごとに呼び出されます

特別に、 function は評価が displayable である Python 文字列にもできます。その場合、関数はインタラクションごとに一度実行されます。

# Shows a countdown from 5 to 0, updating it every tenth of
# a second until the time expires.
init python:

    def show_countdown(st, at):
        if st > 5.0:
            return Text("0.0"), None
        else:
            d = Text("{:.1f}".format(5.0 - st))
            return d, 0.1

image countdown = DynamicDisplayable(show_countdown)
ShowingSwitch(*args, predict_all=None, **properties) link

これは、画面に表示されている画像に基づいて表示する画像を変える displayable です。位置引数は、次を二つ一組にまとめて指定しなければなりません :

  • 画像名の文字列。または、デフォルトを表す None

  • 条件式が True の時に使う displayable

デフォルトの画像は指定されなければなりません。

predict_all

True なら、起こりうるすべての displayable がその表示時に予測されます。　False なら、現在の条件でのみ予測されます。None なら config.conditionswitch_predict_all が使用されます。

ShowingSwitch の使い方の一つは、キャラクターの現在の表情に応じて画像を変えることです。例

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

Layer Displayable link

Layer Displayable はゲームの状態に基づきあるレイヤーの中身を表示します。 config.detached_layers との併用を想定しています。

Dynamic Displayableと同様に、表示されるレイヤーは常に現在の状態を表示することに注意してください。このため、ある Layer Displayable の内容は、表示されている Layer を対象としたトランジションでない限り、トランジションに参加しません。

class Layer(layer, *, clipping=True, **properties) link

これによりあるレイヤーを他のレイヤーに Displayable として表示できます。 detached レイヤーとの併用が想定されています。

レイヤーのそのレイヤー自体への表示は出来ません。

layer

表示するレイヤー

clipping

False なら、そのレイヤーの内容はその領域を超えた部分がカットされずにはみ出る可能性があります。

config.layer_clipping にそのレイヤーがあればこのオプションは無視され、その設定で指定されたようにクリッピングが行われるます。

# A new detached layer to hold the contents of a broadcast.
define config.detached_layers += [ "broadcast" ]

# A layer displayable to represent a TV and watch the broadcast layer.
image tv = Window(Layer("broadcast"), background='#000', padding=(10, 10), style="default")

image living_room = Placeholder('bg', text='living_room')
image studio = Solid('7c7')
image eileen = Placeholder('girl')

label example:
    pause

    # Set up the broadcast scene.
    scene studio onlayer broadcast
    with None

    # Begin a new scene in the living room.
    scene living_room

    # Show the TV in the lower right corner of ths screen.
    show tv:
      align (.75, .75) zoom .3

    # Show Eileen in the broadcast.
    show eileen onlayer broadcast

    # Dissolve into the living room, as Eileen enters the TV from the right.
    with {'master': dissolve, 'broadcast': moveinright}
    pause

レイアウトボックスとグリッド link

レイアウトボックスは、その子 displayable を画面にレイアウトする displayable です。子 displayable を、水平や垂直に並べたり、一定の配置法でレイアウトしたりできます。

ボックス displayable は、任意の数の位置引数とキーワードを取ります。位置引数はボックスに子として加えられる displayable となります。キーワード引数はボックスに適用されるスタイルプロパティーです。

ボックスは 位置スタイルプロパティー と ボックススタイルプロパティー を取ります。

Fixed(*args, **properties) link

画面を満たすボックスです。このメンバは奥から手前に並べられ、この位置は位置プロパティーで制御されます。

HBox(*args, **properties) link

ボックスで、このメンバは左から右へ並べられます。

VBox(*args, **properties) link

ボックスで、このメンバは上から下へ並べられます。

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

グリッドはその子を画面上のグリッドに表示します。これは 位置スタイルプロパティー と spacing スタイルプロパティーを受け取ります。

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

グリッドに displayable を配置します。最初の 2 つの位置引数はグリッドの縦と横の列の数です。この後にはグリッドを満す columns * rows 個の displayable の位置引数が続かなければなりません。

効果 link

これらの displayable は、特定の視覚効果を作成するのに使われます。

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

このトランジションは、ある displayable から別の displayable へのトランジションに control displayable ( ほとんどはATL transform を並べたものです )を使います。その transform が評価され、 transform が不透明な領域は new displayable が使われ、 transform が透明な領域は old displayable が使われます。

alpha

True であれば、画像は背後のものと合成されます。デフォルトの False であれば、画像は不透明で背後のものを上書きします。

画像マニピュレータ link

Image manipulators は、他の画像や画像マニピュレーターだけに transform や操作を適用するレガシーな種類の Displayable であり、他の種類の Displayable には作用しません。

画像マニピュレータは displayable が使える所ならどこででも使えますが、その逆はできません。Image() は画像マニピュレータの一種なので、Image は画像マニピュレータが要求されたときはいつでも使えます。

それらの使用はレガシーなものです。かつてドキュメントに記されていた多くの画像マニピュレータは本質的に問題があるため、すでに使用されていません。 im.Data() を除いて多くの場合で Transform() displayable はそれらの問題を解決しつつ同様な機能を提供します。

画像マニピュレータのリストは 画像マニピュレータ を参照してください。

プレースホルダ link

プレースホルダ displayable を使用して適切な背景やキャラクターを表示します。開発者モードで未定義の画像が使用されるとプレースホルダが自動的に使用されます。プレースホルダ displayable はデフォルトが適切でないときには手動でも使用出来ます。

# By default, the girl placeholder will be used.
image sue = Placeholder("boy")

label start:
    show sue angry
    "Sue" "How do you do? Now you gonna die!"
class Placeholder(base=None, full=False, flip=None, text=None, **properties) link

この displayable を使用して プレースホルダキャラクターや背景を表示出来ます。

base

表示される画像の種類です。これは次の内のひとつであるべきです。 :

'bg'

背景プレースホルダを表示するために、現在は画面を灰色で埋め、スクリーン上部に画像の名前を表示します。

'boy'

肩に画像の名前をいれて男性プレースホルダを表示します。

'girl'

肩に画像の名前をいれて女性プレースホルダを表示します。

None

画像名が "bg" や "cg", "event", で始まるか、 'bg' を使用していたら、自動的に使用する画像タイプを判断します。

それ以外では girl プレースホルダを使用します。

full

True なら全身画像が使用されます。そうでなければ 3/4 画像が使用されます。

flip

True なら画像は水平に反転します。

text

指定された場合、これ以外のテキストはプレースホルダーに表示されません。そうでなければテキストはそれを表示するために使用された show の指示を反映します。

Displayable Prefixes link

Displayable 接頭辞は開発者に独自の displayable の定義を可能にし、 Ren'Py で displayable が使用可能などこででも使用できます。接頭辞のある displayable はコロンを含む文字列です。接頭辞はコロンの左側で、その右側にあるものが引数となります。 config.displayable_prefix 変数は接頭辞を関数に対応させます。その関数は引数を受け取り、 displayable または None を返します。

例えば、オリジナルの二倍の大きさの画像を返す big 接頭辞を作成します。

init -10 python:
    def embiggen(s):
        return Transform(s, zoom=2)

    config.displayable_prefix["big"] = embiggen

init -10 によって接頭辞は使用するどの画像よりも前に定義され、その接頭辞を使用して画像の定義ができます

image eileen big = "big:eileen happy"

また、 displayable が要求されるどこにでも使用できます。

その他参照 link

画像の表示 : これらすべての Displayable を画面に表示させるための基本的な方法です。