Displayable link

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

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

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

  • 設定変数に代入する。

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

displayable を受け取る Ren'Py の関数や変数には、以下の 5 つを与えられます :

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

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

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

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

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

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

画像 link

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

Image(filename, **properties) link

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

filename は適切な拡張子の JPEG または PNG ファイルでなくてはなりません。

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

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

  • Webp
  • Png
  • Jpg

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

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

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

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

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

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

イメージライク displayable link

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

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

AlphaMask(child, mask, **properties) link

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

childmask 引数は任意の displayable です。 AlphaMask のサイズは childmask 両方を重ね合せたサイズになります。

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

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つの側面のパディングを含みます。

DynamicImage(name) link

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

Flatten(child, **properties) link

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

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

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

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

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

_images/frame_example.png

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

image

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

left

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

top

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

right

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

bottom

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

tile

True なら、画像の一部をリサイズするのにスケーリングではなくタイリングが使われます。

# 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

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

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

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

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

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

image eileen cropped = LiveCrop((0, 0, 300, 300), "eileen happy")
LiveTile(child, style='tile', **properties) link

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

image bg tile = LiveTile("bg.png")
Null(width=0, height=0, **properties) link

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

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

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

image white = Solid("#fff")

Text Displayables link

Text Displayables 参照。

動的 displayable link

動的 displayable は、ゲームの状態に基づいて子 displayable を表示します。このレイアウトは自身が返す子 displayable のプロパティーで制御されるので、これらはプロパティーを取りません。

ConditionSwitch(*args, **kwargs) link

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

  • Python 式を含む文字列

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

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

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

インタラクションが起こったとき、Python 関数に基づいて子を変える 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, **kwargs) link

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

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

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

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

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

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

displayable への変換の適用 link

At 関数は、1 つの displayable と 1 つ以上の 変換 とから、displayable を作成します。

At(d, *args) link

与えられた displayable dargs のそれぞれの変換を適用します。変換は左から右へ順に適用され、最後になされる変換は最も右側の引数です。

transform birds_transform:
     xpos -200
     linear 10 xpos 800
     pause 20
     repeat

image birds = At("birds.png", birds_transform)

レイアウトボックスとグリッド 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))

グリッドはその子を画面上のグリッドに表示します。これは ref:position-style-propertiesspacing スタイルプロパティーを受け取ります。

効果 link

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

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

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

alpha

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

画像マニピュレータ link

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.

画像マニピュレータは、キャッシュに画像データを保存するだけです。よって、結果は一定の大きさになり、事前に知ることができ、ゲームの状態や入力によっては変化しません。一般に、画像マニピュレータは画像や別の画像マニピュレータしか取れません。

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

多くの画像マニピュレータは、他の displayable と同じ機能を提供します。これらのほとんどは、他の画像マニピュレータへの入力として渡せるので、ゲームメーカーはキャッシュメモリの使用かレンダリング時になされる動作を選べます。また、歴史的な事故によって存在するものもあります。これらの画像マニピュレータのほとんどと等価なものが後で作られています。

im.AlphaMask(base, mask, **properties) link

basemask 2 つの画像マニピュレータを引数として取る画像マニピュレータです。 base のアルファチャンネルを mask の赤いチャンネルで置き換えます。

これは一枚目の jpeg を色データに、二枚目をアルファデータにといった具合に、二枚目の画像のアルファチャンネルを適用するのに使います。2 枚の jpeg の方が 1 枚の png ファイルよりも容量が小さいことがあります。

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

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

この画像マニピュレータは、複数の画像を合成して一つの画像にします。

size は (width, height) タプルで、合成された画像のサイズを与えます。

その他の位置引数は、二つ一組で解釈されます。セットの一番目の引数は (x, y) タプルで、二番目は画像マニピュレータです。画像マニピュレータによって生産された画像は、タプルで与えられた位置に合成されます。

image girl clothed happy = im.Composite(
    (300, 600),
    (0, 0), "girl_body.png",
    (0, 0), "girl_clothes.png",
    (100, 100), "girl_happy.png"
    )
im.Crop(im, rect) link

画像マニピュレータ im から (x, y, width, height) タプル rect を刈りこむ画像マニピュレータです。

image logo crop = im.Crop("logo.png", (0, 0, 100, 307))
im.Data(data, filename, **properties) link

This image manipulator loads an image from binary data.

data
A string of bytes, giving the compressed image data in a standard file format.
filename
A "filename" associated with the image. This is used to provide a hint to Ren'Py about the format of data. (It's not actually loaded from disk.)
im.FactorScale(im, width, height=None, bilinear=True, **properties) link

別の画像マニピュレータ im の大きさを調整し、幅を width 倍、高さを height 倍にする画像マニピュレータです。 height を省略すると、デフォルトで width になります。

bilinear が True なら、大きさの調整に双線形補間が使われます。そうでなければ、近隣補間が使われます。

image logo doubled = im.FactorScale("logo.png", 1.5)
im.Flip(im, horizontal=False, vertical=False, **properties) link

im (画像マニピュレータ) を水平または垂直に裏返す画像マニピュレータです。 vertical および horizontal で画像が裏返される方向を制御します。

image eileen flip = im.Flip("eileen_happy.png", vertical=True)
im.Grayscale(im, **properties) link

画像マニピュレータ im の彩度をなくした版を作成する画像マニピュレータです。

im.Scale(im, width, height, bilinear=True, **properties) link

im (画像マニピュレータ) の大きさを widthheight に調整する画像マニピュレータです。

bilinear が True なら、大きさの調整に双線形補間が使われます。そうでなければ、近隣補間が使われます。

image logo scale = im.Scale("logo.png", 100, 150)
im.Sepia(im, **properties) link

画像マニピュレータ im のセピアトーン版を作成する画像マニピュレータです。

im.Tile(im, size=None, **properties) link

画像マニピュレータ imsize になるまでタイル張りする画像マニピュレータです。

size

None を指定するか、(width, height) タプルでを指定します。None であれば、デフォルトで (config.screen_width, config.screen_height) になります。

im.MatrixColor link

im.MatrixColor 画像マニピュレータは、画像の色の変換を行列で指定する画像マニピュレータです。使われる行列は im.matrix オブジェクトです。im.matrix オブジェクトは 5x5 行列をオブジェクトにエンコードし、行列操作をサポートし、一連の関数によって返されます。im.matrix オブジェクトを掛け合わせて、両方の演算を行う一つのオブジェクトを得られます。例えば、このコードは

image city blue = im.MatrixColor(
    "city.jpg",
    im.matrix.desaturate() * im.matrix.tint(0.9, 0.9, 1.0))

まず画像の彩度をなくし、それから青く染めます。中間の画像が必要ないときは、im.MatrixColors を二度使うよりも行列を掛け合わせましょう。そのほうが時間上も画像キャッシュ領域上も遥かに効率的です。

im.MatrixColor(im, matrix, **properties) link

matrix を使って画像マニピュレータ im を線形に変換する画像マニピュレータです。

Matrix は、20 または 25 要素のリスト、タプル、または im.matrix() にしてください。オブジェクトに 25 要素あれば、20 番目よりあとは無視されます。

ソースカラーの 4 つの構成要素が R, G, B, および A でそれぞれの範囲が 0.0 から 1.0、変換された後の色の 4 つの構成要素が R', G', B', および A' で同じ範囲、そして行列の要素が以下のように名付けられるとすると

[ a, b, c, d, e,
  f, g, h, i, j,
  k, l, m, n, o,
  p, q, r, s, t ]

変換先の色は以下の公式で計算されます

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

変換先の色の構成要素は範囲 [0.0, 1.0] に固定されます。

im.matrix() link

matrix から im.matrix オブジェクトを構成します。im.matrix オブジェクトがサポートする演算は、行列乗算、スカラー乗算、要素ごとの加算、要素ごとの減算です。これらの演算は、標準の数学演算子 (それぞれ *, *, +, および -) を使って呼び出されます。二つの im.matrix オブジェクトを乗じると行列乗算が行われ、そうでなければスカラー乗算が使われます。

matrix は 20 または 25 要素のリストまたはタプルです。これが 20 要素なら、乗算をしやすいように (0, 0, 0, 0, 1) が付け足され、5x5 の行列になります。

im.matrix.brightness(b) link

画像の輝度を変える im.matrix を返します。

b

画像の輝度を変化させる量です。これは -1 から 1 でなければならず、-1 は可能な中で最も暗い画像で、1 は最も明るい画像です。

im.matrix.colorize(black_color, white_color) link

白黒の画像に着色する im.matrix を返します。 black_color および white_color は Ren'Py スタイルの色で、文字列か (0-255) の明度値のタプルかで指定できます。

# This makes black colors red, and white colors blue.
image logo colored = im.MatrixColor(
    "bwlogo.png",
    im.matrix.colorize("#f00", "#00f"))
im.matrix.contrast(c) link

画像のコントラストを変化させる im.matrix を返します。 c は 0.0 より大きく、0.0 から 1.0 の値はコントラストを下げ、1.0 より大きい値はコントラストを上げます。

im.matrix.desaturate() link

画像の彩度を無くす (グレースケールにする) im.matrix を返します。これは、im.matrix.saturation(0) を呼び出すのと等価です。

im.matrix.hue(h) link

高度を変えずに色相を h 度循環させる im.matrix を返します。

im.matrix.identity() link

色やアルファ値を変えない恒等行列を返します。

im.matrix.invert() link

アルファ値を変えずに赤、緑、青のチャンネルを反転させる im.matrix を返します。

im.matrix.opacity(o) link

画像の不透明度を変更する im.matrix を返します。 o は 0.0 で完全に透明、1.0 で完全に不透明になります。

im.matrix.saturation(level, desat=(0.2126, 0.7152, 0.0722)) link

画像の彩度を変える im.matrix を返します。アルファチャンネルはそのままです。

level

変更後の画像の彩度です。1.0 はそのままの画像で、0.0 はグレースケールです。

desat

これは 3 要素のタプルで、赤、緑、青チャンネルが完全に彩度を無くされた 3 つのチャンネルにどれだけ置かれるかを制御します。デフォルトは、NTSC テレビジョンシグナルの輝度チャンネルに使われる定数に基づきます。人間の目は緑に一番敏感なので、緑チャンネルは他の 2 つのチャンネルよりも多く残されます。

im.matrix.tint(r, g, b) link

画像のアルファチャンネルはそのままで色合いをつける im.matrix を返します。 r,`g`, および b は 0 から 1 の数で、与えられたチャンネルのうちの最終的な画像に置かれる割合を制御します。(例えば、 r が .5 で、赤チャンネルの値が 100 なら、変換された後の色の赤値は 50 になります。)

プレースホルダ link

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

# 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

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

base

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

'bg'

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

'boy'

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

'girl'

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

None

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

そうでなければウェブサービスにアクセスしてキャラクター名から性別を推測し、それを使用します。 (サービスにアクセス出来ないと 'girl' プレイスフォルダーが使用されます。)

ウェブサービスには config.developer が True のときのみアクセスされます。

full

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

flip

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