scene — 2次元のゲームとアニメーション
scene モジュールはハードウェアアクセラレータを使用した2次元グラフィックスとアニメーションを簡単に作成する方法を提供します。特にゲーム用に最適です。
- あらまし
- 古典的レンダリング・ループ
- ui モジュールとの統合
- ゲームコントローラー
- Node クラス
- シーン
- ノード
- スプライトノード
- エフェクトノード
- ラベルノード
- シェイプノード
- その他のクラス
- アクション
- シェーダー
- テクスチャ
- タッチ
- Geometry Types
- Vector2
- Point
- Size
- Rect
- 関数
- 定数
あらまし
イントロダクション
scene を使用したスクリプトを描く際には、まず Scene の子クラスを生成する必要があります。この子クラスは、接触イベントなどに反応するコンテンツの描画に用います。子クラスを生成し、run() 関数に渡せば、実際のスクリーン上への scene の表示を行うことができます。Scene クラスには、その挙動をカスタマイズできるような様々なメソッドがあります。例えば、 Scene.setup() を呼ぶことによって、スクリーン上での表示の属性を設定できます:
from scene import * class MyScene (Scene): def setup(self): self.background_color = 'green' run(MyScene())
上記の最小限の例は、Scene.setup() メソッドで画面の背景色を緑に設定するシンプルなものです。
実際に画面上にコンテンツを加える際には、普通、Node オブジェクトを生成します。異なる種類のコンテンツには Node の異なる種類の子クラスが対応します。例えば、画像には SpriteNode 、テキストには LabelNode というように。Scene もまた Node の子クラスであり、ノードは他のノードを部品として取り込むことができます。(ツリーとか「scene graph」と呼ばれる構造になります。)ノードの一部品として他のノード取り込めることによって、複数のオブジェクトを一つの要素として一括して動かしたり回転させたりすることが可能になります。全てのノードは位置、角度、寸法、そしてα(透過度)の属性を持っています。これらの属性によりノードと、子ノードがどのように描画されるかが決まります。デフォルトの位置は画面の左下隅を表す(0,0)になっています。
次の例では、setup() メソッドが、画面中央に宇宙船を表示する設定となるように拡張されています:
from scene import * class MyScene (Scene): def setup(self): self.background_color = 'midnightblue' self.ship = SpriteNode('spc:PlayerShip1Orange') self.ship.position = self.size / 2 self.add_child(self.ship) run(MyScene())
ここでいくつか注釈を:
- SpriteNode の初期化に際して渡されている文字列(上記の「spc:PlayerShip1Orange」)は、システム組込み画像の名称です。 システム組込み画像は、Pythonista のエディター画面のソフトウェアキーボードの右上端にある「+」ボタンを使えば確認することができます。(訳注 外付けキーボードを使っている場合には画面右下端に「+」が表示されます)
- 利便性を考慮し、scene モジュールのサイズや位置に関するオブジェクトは、標準的な引数を使用するようにしています。(setup() を呼び出す前に自動的に設定される) scene のサイズは、単純に2で割るとスクリーンの中心になるようになっています。サイズと画面上の点は相互に換算できるように、サイズは位置の属性として機能するような構成にしています。2つの数字からなるシンプルなタプルも使用可能です。
- デフォルトでは、SpriteNode の位置属性は中央を指定するようになっています。状況によっては、代わりにスプライトの四隅の一つを基準にした方が便利な場合があります。anchor_point 属性を変更することで、四隅の一つを基準にするよう設定可能です。
画面へのタッチと簡単なアニメーション
先程の例を画面へのタッチに反応するよう今一度拡張してみましょう。それには、Scene の touch_began() メソッドを上書きするだけで十分です。
from scene import * class MyScene (Scene): def setup(self): self.background_color = 'midnightblue' self.ship = SpriteNode('spc:PlayerShip1Orange') self.ship.position = self.size / 2 self.add_child(self.ship) def touch_began(self, touch): x, y = touch.location move_action = Action.move_to(x, y, 0.7, TIMING_SINODIAL) self.ship.run_action(move_action) run(MyScene())
この最後の例では Action クラスを使用しています。Action は Node の属性、今回は位置属性ですが、簡単に変更して Node を動かすことができます。タイミングモードの( TIMING_SNODAIL)で開始値と終了値の間の補完の仕方を指定します。この引数を省略した場合には、デフォルトの直線補完(ぎこちない動きになります)になります。ノードを回転させたり、大きさや透過度(アルファ)を変えたり、親ノードから消し去るものまで多くの Action メソッドがあります。Action.group() や Action.sequence() を使って複数のアクションを組み合わせたり、Action.repeat() を使って繰り返して動きを作り出すこともできます。
touch_began() と同様、touch_moved() や touch_ended() という、タッチの開始や終了を調べるメソッドもあります。
高度なアニメーションと動きのコントロール
Actions により scene 上のコンテンツに、簡単に使えて高機能なAPI(アプリケーション・プログラミング・インターフェイス)で動きを付けることができますが、Scene の update() メソッドで重ね書きすることによって、フレームベースの動きの変化をつけることも可能です。次の例では、この手法により、gravity() 関数を用いて、デバイスの指示に応じて宇宙船を動かします。デフォルトでは、update() メソッドは1秒間に60回呼び出されるため、Actions を用いるよりも、船の位置は直接的に動きます。
from scene import * import sound class MyScene (Scene): def setup(self): self.background_color = 'midnightblue' self.ship = SpriteNode('spc:PlayerShip1Orange') self.ship.position = self.size / 2 self.add_child(self.ship) def update(self): x, y, z = gravity() pos = self.ship.position pos += (x * 15, y * 15) # Don't allow the ship to move beyond the screen bounds: pos.x = max(0, min(self.size.w, pos.x)) pos.y = max(0, min(self.size.h, pos.y)) self.ship.position = pos def touch_began(self, touch): laser = SpriteNode('spc:LaserBlue9', position=self.ship.position, z_position=-1, parent=self) laser.run_action(Action.sequence(Action.move_by(0, 1000), Action.remove())) sound.play_effect('arcade:Laser_1') run(MyScene(), PORTRAIT)
ここで使っている gravity() 関数はデバイスの向きを決める簡単なメソッドです。より緻密なコントロールをするに、代わりに motion モジュールを使うこともできます。motion でコントロールするゲームの場合、画面の縦←→横の自動切替を無視する事ができ、run()関数に引数を追加することにより画面を縦方向に固定することもできます。
ひとつおまけに、スクリーンにタッチすると宇宙船からレーザーが撃たれるようにしました。レーザーのスプライト要素を初期設定する際に設定している z_position は、描画する順番を決める属性です。ここでは、宇宙船の先頭からレーザーが表示されないよう、-1に設定しています。画面にレーザーを書き加えたあと、2つの動作を繰り返し実行します。1つはレーザーを1000ポイント分上へ動かし、特別な方法を使って削除します。(本当の意味でのアニメーションではありませんが、アニメーションの流れの一部として使用できる方法です。)
以上は、ごく基礎的な「あらまし」です。scene モジュールを活用すれば、もっと多くのことができます。この pythonista3 に付属の Examples フォルダーには、より進んだテクニックを学ぶのに使える完成したゲームをいくつか納めてあります。
図形
scene の座標系では、左下隅を原点(0,0)としています。
「あらまし」では、scene モジュールには、2次元の図形を便利に扱うためのクラス、まずはRect、Point、Sizeがあることに簡単に触れました。点とサイズは基本的に同一の数字の組合せですが、違う意味合いで使います。
これらの幾何学的なオブジェクトは、多くの Node 属性、例えばNode.position、SpriteNode.size、Node.frame などに使用します。これらの属性に新規の値を設定する時には、Point や Size オブジェクトをわざわざ明示した形で宣言する必要はありません。タプルやリストのような2つの数字の組合せでも同じ役割を果たします。
これらの全てのクラスは、一連のものと見なされるので、例えば、point[0]を使って Point の x 座標の値にアクセスすることができます。(一般的には、point.x を使うより便利です。)
Vector2、Point、Size については、利便性を考えて、数学の演算子をサポートしています:
- ベクトルとスカラー値(すなわち、数字のことです)の掛け算については、ベクトルの各要素にそれぞれ数字を掛けます。割り算についても同様です。例えば、Size(100,200)*0.5 は、Size(50,100)になります。
- ベクトル同士の掛け算は、成分ごとに乗算を行います。例えば、Point(100,100)*(2,3) は Point(200、300)になります。
- ベクトル同士の足し算も同様です。例えば、Point(100,100) + (20,50) は Point(120,150) になります。
弾が当たったかどうかを調べるためには、点(Point) が 引数として渡した四角形(Rect)の中に入っているかどうかで判定できます。一つの四角形が他の四角形の中に入り込んでいるかどうかの判定には、 Rect.intersects() メソッドを使えます。(もしくは、厳密に四角形の中に入り込んでいるかを知りたい場合には、Rect.intersection()を使います。)
色
Node の色に関する属性、例えば SpriteNode.color や Scene.background_color は様々な方法で設定できます。
- HTML(ハイパー・テキスト・マークアップ・ランゲージ:ウェブページを書くのに使われる言語) で使われる、16進の色を示す文字列。例えば、'#ff0000' で「赤」を示す。
- CSS(カスケーディング・スタイル・シート:ウェブページのスタイルを指定する言語) での色名称。例えば、'green', 'blue', 'magenta' など。
- 赤、緑、青、そしてアルファ(不透明度)を表す0.0〜1.0の値の組合せを示す3ないし4つの数字のタプル。アルファの値はデフォルトで1.0で、完全に透けない状況を表します。
- グレイスケールの値(0.0=黒、1.0=白)を表す0.0〜1.0の単独の数値。
どの方法で色属性を指定しても、システム上は常に4つの数字のタプル(赤、緑、青、アルファ)に変換されて処理します。
古典的レンダリング・ループ
上記のようなnodeによる画像処理に加えて、scene モジュールは、古いバージョンの pythonista のインターフェイスである「古典的レンダリング・ループ」もサポートしています。多くの場合、node による画像処理の方が処理速度がかなり速くなるのですが、「古典的レンダリング・ループ」は、Processing のような、同様のプログラミング環境に慣れた方にとっては、理解がしやすいかも知れません。
このモードを使うには、Scene の子クラスを生成する必要があります。node を追加する代わりに、シンプルに draw() メソッドをオーバーライドする方法もあります。このメソッドはフレーム毎に(すなわち1秒間に60回)呼び出され、全てのフレームでコンテンツを「塗る」、モジュールレベルの塗り潰し機能を使うことができます。画面にこの方法で描かれた画像や線画は、フレーム毎に書き直され、残り続けることはありません。draw(メソッド)を呼び出す毎に、基本的に何も描かれていない画面に改めて書き始めることになります。
古典的な OpenGL(汎用グラフィクスライブラリー)と同様に、実際の drawing 関数を呼び出す前に、塗り潰しや座標変換のようなプログラム全体に使用する条件を設定します。以下の例は回転する四角形を描くスクリプトです:
from scene import * class MyScene (Scene): def draw(self): background('gray') colors = ['red', 'green', 'blue', 'yellow'] # 画面中心に移動する: translate(self.size.w/2, self.size.h/2) for color in colors: # 塗り潰し色を設定する(この設定は以降の drawing コマンドに適用されます) fill(color) # 座標変換マトリクスに回転を設定する(この操作は前回設定に加えた回転になり、回転量が蓄積されます) rotate(-20) # 注:引数の座標値は、直前の「座標変換」コマンドに応じた、画面中心からの相対的な値になります rect(-50, -50, 100, 100) run(MyScene())
古いバージョンの pythonista を使ったことのある方なら、Node や Action とコンセプト的には似通った、Layre や Animation クラスにも親しみを覚えるかも知れません。これらのクラスは下位互換性のために使用可能にしていますが、Node や Action API を代わりに使うことを強くお勧めします。なぜなら、処理速度が圧倒的に改善されているためです。
注 このモードで描画に使える関数は、scene_drawing モジュールで定義されています。これらの関数を使う必要がなければ、scene_drawing を import する必要はありません。
ui モジュールとの統合
scene を実行するのに一番簡単な方法は、フルスクリーンで表示する run() 関数を使用することです。この方法では、ゲーム以外の画面を作る時には特に、都合が悪いことがあります。より柔軟に画面を構成するために、SceneView を明示的に生成することもできます。SceneView に表現したい画面に応じた scene 属性を設定し、ui モジュールを使い、生成した view ヒエラルキーに加えます。
この方法は伝統的な UI エレメント(例えば、テキスト・フィールド)をゲームに付け加える際にも使えます。この目的のためには、SceneView を生成する必要はありません。シンプルに自動的に生成された view を、Scene の view 属性を適用して(もちろん、既に scene が生成されている場合のみ適用可能です)使うことができます。
ui モジュールは、図形やテキストなどのベクターイメージをテクスチャとして使いたい場合の画像処理にも便利に使用できます。 このためには、 ui.Image でテクスチャを初期化、一般的には ui.ImageContext を使って生成します。ShapeNode とLabelNode クラスはコンテンツの画像処理にこの方法を使っています。
ゲームコントローラー
scene モジュールは、Nimbus SteelSeries gamepad のような、MFi(Made For iPhone/iPad/iPod:アップルデバイスへの接続規格) ゲームコントローラーによるゲームコントロールをサポートしています。
ゲームに対する外部コントローラーからの入力をサポートするのは極めて簡単です。基本的に Scene の子クラスである Scene.controller_changed() メソッドをコントローラーで発生するイベント(例えば、ボタンが押された、とか、ボタンから手が離された)に反応するように重ね書きするだけです。メソッドには2つのパラメーターがあります。コントローラーの変更される要素(例えば'button_a')を示す文字列としての「key」と、コントローラーの要素の「現在値」です。「現在値」の型は、コントローラーの要素の型によって決まります。基本的なボタンについては論理型、感圧式のトリガーは0.0〜1.0の間の浮動小数点型、dpads(十字キー) や ジョイスティックは−1.0〜1.0の間の値をもつxとyで構成される Point オブジェクトになります。
Scene.update() メソッドやその他の方法でコントローラーの現在の状態を調べると、より便利な場合があります。このためには、モジュールレベルの get_controllers() 関数を使うことができます。この関数は、接続されているコントローラーのボタンや十字キー、ジョイスティックなどの現在の状態を示す辞書型のリストを返します。
Node クラス
シーン
class scene.Scene
scene は Node オブジェクトを構成するノード群の大本のノードです。これらのノードは、画面上で scene を動かしたり、描画したりするコンテンツを作るのに使います。scene をフルスクリーンで表示するためには一般的に、モジュールレベルの run() 関数を呼び出します。他の UI コンテンツと共に scene を表示する場合には、SceneView を明示的に生成することもできます。
scene は、以下の順番で、新しいフレームのコンテンツの作成処理を行います:
- scene の update() メソッドを呼び出す。
- scene の子クラスの処理を実行する。
- scene の did_evaluate_actions() メソッドを呼び出す。
- scene の全てのノードを描画し、新しいコンテンツを表示するため、画面のアップデート処理をする。
画面にタッチした時の処理(touch_began(),touch_moved(),touch_ended()の重ね書きによって)やその他のゲームのコンテンツに反応させるため、少なくとも1つは、Scene の子クラスを生成するのが一般的です。
Scene は EffectNode の子クラスであり、フルスクリーンの後処理的な効果として、カスタマイズした Shader を使うことが可能です。しかしながら、標準の EffectNode と異なり、scene の effect_enabled 属性をデフォルトでは False に設定されています。
Scene.setup()
画像をスクリーン上に表示する直前に一度だけ呼び出します。画像の表示準備に使用します。この時点ではすでに画像のサイズや境界の属性は設定済みであり、これらによってコンテンツのレイアウトを規定できます。
Scene.touch_began(touch)
このメソッドは scene の表示されている画面へのタッチが始まった時に呼び出されます。一般的に、直接的に呼び出すのではなく、Scene の子クラスの一部として実行します。
touch オブジェクトの位置属性を調べる事で、scene の座標系の中のタッチした位置を知ることができます。同時に複数の場所がタッチされた場合にも、touch_id 属性を使えば、それぞれの場所の区別をつけることができます。
Scene.touch_moved(node, touch)
このメソッドは、scene の画面に触った指などが動いた際に呼び出されます。一般的に、直接的に呼び出すのではなく、Scene の子クラスの一部として実行します。
touch オブジェクトの位置属性を調べる事で、scene の座標系の中のタッチした位置を知ることができます。同時に複数の場所がタッチされた場合にも、touch_id 属性を使えば、それぞれの場所の区別をつけることができます。
Scene.touch_ended(node, touch)
このメソッドは、scene の画面に触った指などが画面から離れた際に呼び出されます。一般的に、直接的に呼び出すのではなく、Scene の子クラスの一部として実行します。
touch オブジェクトの位置属性を調べる事で、scene の座標系の中のタッチした位置を知ることができます。同時に複数の場所がタッチされた場合にも、touch_id 属性を使えば、それぞれの場所の区別をつけることができます。
Scene.did_change_size()
このメソッドは、scene のサイズが変更された場合、通常は、画面が回転した場合に呼び出されます。一般的には、コンテンツを再配置するためにこのメソッドを重ね書きします。このメソッドが呼び出された際には、scene のサイズ属性は既に新しいサイズの数値になっています。
Scene.did_evaluate_actions()
このメソッドは、子ノードのアクションの処理が終了した scene の後に呼び出されます。
Scene.update()
scene のアクションに前もって実行する必要がある scene 特有の更新を行います。
このメソッドは直接呼び出さないで下さい;scene が表示され、停止されていない限り、1フレームに1回呼び出されます。デフォルトでは、このメソッドは何もしません。scene の子クラスが、このメソッドを重ね書きし、scene に必要な更新を実行します。
Scene.pause()
scene が実行されている間にホームボタンが押された場合に自動的に呼び出されます。このメソッドに重ね書きし、例えば、保持すべき状況のセーブをするようにできます。デフォルトでは、何も処理を行いません。
Scene.resume()
ホームボタンが押されて scene がバックグラウンドに送られて中断した際に自動的に呼び出されます。デフォルトでは、何も処理を行いません。
Scene.stop()
「X(バツ)」ボタンが押されて scene が停止した際に自動的に呼び出されます。現在の状態をセーブするためにこのメソッドを書き換えることができます。デフォルトでは、何も処理を行いません。
Scene.present_modal_scene(other_scene)
他の scene を(他の scene を隠すような形で)最前列に表示します。画面に上書きする形でメニューを表示するのに便利です。scene が表示されている間は、全てのタッチ操作を受け付けます。
Scene.dismiss_modal_scene()
Scene.present_modal_scene() を使って決められた形で表示された scene を閉じます。
Scene.controller_changed(key, value)
このメソッドは接続中のゲームコントローラーの状況が変化した際に自動的に呼び出されます。例えば、ボタンが押された場合/離された場合、またはジョイスティックや十字キーの方向が変化した場合など。
引数 key は変化を確認したいコントローラーの要素(例えば、'button_a', 'dpad', 'thumbstick_left'など)を指定する文字列です。引数 value はその要素の現在の値です。value の型はコントローラーの要素の型によって変わります。十字キーやジョイスティックのような方向を入力する要素の場合、value は Point オブジェクトになります。その他の要素の場合、浮動小数点型(感圧式のエレメントのとき)または論理型になります。
Scene の属性
scene.bounds
原点(0,0)を持つ、画面の描画領域のサイズの長方形です。
Scene.dt
update() を最後に呼び出してから経過した秒数です。カスタマイズしたアニメーションの進捗の計算に使用可能です。
Scene.size
画面の描画領域のサイズです。
Scene.t
scene がスタートしてから経過した秒数です。カスタマイズしたアニメーションの進捗の計算に使用可能です。
Scene.touches
現在アクティブな全てのタッチの辞書型のリストです。Touch オブジェクトの touch_id 属性に対応しています。
Scene.background_color
scene の背景色です。
デフォルトではダークグレーです。
Scene.size
ポイント単位(1ポイントは約0.35mm)で示した scene のサイズです。(読取専用)scene の表示サイズに対応しています。
Scene.view
View は現在表示されている scene を表します。scene が表示されていない場合には、None となります。(読取専用)
Scene.presented_scene
Scene.present_modal_scene() を使用して現在表示中の scene を表します。(表示している scene がない場合はNone)
Scene.presenting_scene
Scene.present_modal_scene() を使用して表示した scene によって、さらに派生して表示された scene があれば、それを表します。(訳注 使用事例も探して検証してみたのですが、この訳が妥当かどうか不明です。)
ノード
class scene.Node([position=(0, 0), z_position=0.0, scale=1.0, x_scale=1.0, y_scale=1.0, alpha=1.0, speed=1.0, parent=None])
Node クラスは scene の基礎的な構成要素です。基本的な Node クラスは、それ自体では何も描画しません。その主な役割は子クラスが使用する基礎的な挙動を指定することです。ノード群は全体をカスタマイズするために他のノードを構成要素にすることもできます。実際のコンテンツの描画のためには、一般的にノードの子クラスを使用します:
- SpriteNode – 画像をスプライト(背景画面とは独立に位置を変えられる区画)上に描くノード
- LabelNode – 文字列を表示するのに特化したスプライトノード
- ShapeNode – ベジェ曲線に基づいた線画を表示するの特化したスプライトノード(例 円や角の丸い長方形)
- EffectNode – カスタマイズしたシェーダー(特殊効果を与える仕組み)を使用して子ノードに効果を適用するノード
ノード群は、view と subview の関係と同様に、ノードの樹型の階層構造の形で構成されています。ごく一般的には、ノードの樹型は、Scene ノードが幹となり、その他のコンテンツのノードが枝となる形になっています。この場合の scene ノードは各ノードの処理を繰り返します。そして、ノードの樹型の中に含まれるコンテンツを画面に表示します。
全ての樹型構造の中にあるノードは、その子ノードに対して座標系を渡します。子ノードが樹型構造に付け加えられた後で、親ノードの座標系の中に子ノードの位置が設定されます。ノードの座標系は、x_scale, y_scale, rotation 属性を変える事で縮尺を変えたり、回転させたりすることができます。ノードの座標系の縮尺が変更されたり回転されたりすると、この変形はノード自体のコンテンツと子や孫のノードのコンテンツにも適用されます。
Node クラスは、それ自身では描画を行いません。しかし、多くの子クラスが画像コンテンツを描画するため、Node クラスは画像に関するコンセプトであると解釈されます:
フレームの属性は、ノードの画像コンテンツを表示する長方形を示します。この長方形は scale や rotation 属性に応じて変形します。フレームは、ノードクラスがコンテンツを表示すると空ではなくなります。それぞれのノードの子クラスはそれぞれ異なるコンテンツのサイズを持っています。いくつかの子クラスでは、スプライトノードのクラスのように、ノードのコンテンツのサイズが明示的に宣言されます。その他の子クラスでは、コンテンツサイズは他のオブジェクト属性を使って隠された形で、計算によって求められます。例えば、ラベルノードオブジェクトでは、ラベルに表示するテキストと、フォント属性によって決定されます。
ノードの bbox はノードのフレームと全ての子ノードのフレームを包含した最も大きい長方形です。
アルファ(不透過度)属性のようなそのたの属性は、ノードや子ノードの描画に影響を与えます。
樹型構造の中の全てのノードは Action オブジェクトを実行し、ノードの属性を変化させることがあります。例えば、新しい座標へのスムーズな移動など。
Node.add_child(node)
受け手の持つ子ノードのリストの最後にノードを追加します。
Node.remove_from_parent()
親ノードからノードを削除します。
Node.remove_action(key)
引数 key で指定した特定のアクションを終了させ、ノードから削除します。key はNode.run_action() メソッドに渡された任意の文字列です。
Node.remove_all_actions()
全てのアクションを終了させ、ノードから削除します。
ノードからアクションを削除すると、そのアクションが実行する残りのアニメーションはスキップされます。ただし、それ以前の変化は取り消されません。
Node.render_to_texture([crop_rect])
このノードと子ノードのスナップショットとして表面に描画したTexture オブジェクト を生成します。
Node.point_to_scene(point)
引数 point で指定した点を、このノードの座標系から、ノードを含む scene の座標系に変換します。ノードが scene の一部でなかった場合、ValueError が生じます。
Node.point_from_scene(point)
引数 point で指定した点を、このノードの scene の座標系から、このノードのローカルな座標系に変換します。ノードが scene の一部でなかった場合、ValueError が生じます。
Node.run_action(action[, key])
ノードで実行されるアクションのリストに、アクションを追加します。
もし同じ key (任意の文字列)を使用するアクションが既に実行されている場合には、新しいアクションが追加される前に削除されます。
Node Attributes
Node.bbox
ノードと全ての子ノードのコンテンツを含む長方形を親の座標系で算出します。
Node.alpha
ノードのコンテンツに不透明度(アルファ)を適用します。
Node クラスは描画はしませんが、その子クラス群の多くは描画をします。ノードや子ノードが描画する際に、それぞれのピクセル(画素)のアルファ値にはノードのアルファ属性が掛け算され、その値は0.0〜1.0の範囲に固定されています。この補正されたアルファ値は画素をフレームバッファーに溶け込ませるのに使われます。コンテンツを描画する子クラスについては、親のフレームバッファーに画素を溶け込ませるアルファ値によって、ブレンド処理が規定されます。
Node.frame
ノードのコンテンツを含む、親の座標系の長方形です。子ノードについては無視します。(読取専用)
Node.children
このノードの子ノードのリストです。このリストを修正しても、効果がないことにご注意下さい。代わりに、Node.add_child() や Node.remove_from_parent() を使用します。
Node.parent
このノードの親ノードです。(読取専用)
Node.paused
ノードや子孫ノードのアクションが処理中かどうかを判別する論理値です。
Node.position
親ノードの座標系の中でのノードの位置(x,y)です。
Node.scene
ノードを含むシーンノードです。(読取専用)
ノードがシーンに埋め込まれていない場合には、値は None になります。
Node.speed
ノードや子孫ノードにより実行される全てのアクションに適用される速度調整値です。
Node.x_scale
ノードと子孫ノードの幅に掛け算する縮尺の値です。
X 方向スケール値は、ノードと全ての子孫ノードの幅に影響を与えます。スケール値はどのようにノードのフレームの計算を行うか、どのように描画されるか、そして他の同様の指標に影響します。デフォルト値は1.0です。
Node.y_scale
ノードと子孫ノードの高さに掛け算する縮尺の値です。
Y 方向スケール値は、ノードと全ての子孫ノードの高さに影響を与えます。スケール値はどのようにノードのフレームの計算を行うか、どのように描画されるか、そして他の同様の指標に影響します。デフォルト値は1.0です。
Node.z_position
ノードの z 方向の位置により、兄弟ノード同士の描画される順番が決まります。デフォルト値は0.0です。より大きな値のノードが、小さい値のノードの手前に描かれます。
Node.rotation
ノードの Z 軸回りの回転を示します。(角度の単位はラジアンです)
デフォルト値は0.0で、「回転しない」ことを表します。プラスの値は、反時計周りの回転を示します。座標系が回転された場合、ノードと子孫ノードに影響が及びます。
スプライトノード
class scene.SpriteNode([texture, position=(0, 0), z_position=0.0, scale=1.0, x_scale=1.0, y_scale=1.0, alpha=1.0, speed=1.0, parent=None, size=None, color='white', blend_mode=0])
スプライトノードは、画像イメージや色のついた正方形、色を混ぜた画像イメージなどを描画するノードです。カスタマイズしたシェーダーによりオリジナルの描画上の効果を作り出すこともできます。
スプライトノードを初期化する際には、テクスチャオブジェクトやシステム組込の画像の名称、画像ファイル(文字列)によりテクスチャを指定できます。
SpriteNode の属性
SpriteNode.anchor_point
ノードの位置に対応するスプライトの位置を指定します。
ユニットの座標系の空間の中でこの属性の値を指定します。デフォルト値は(0.5,0.5)です。この値の場合、その位置がスプライトの中央であることを示します。
SpriteNode.blend_mode
ブレンドモードは、スプライトを親のフレームバッファに書き込む際に使用されます。
この属性に設定可能な値は、後述する「ブレンドモード」のリストの通りです。デフォルト値は BLEND_NORMAL です。
SpriteNode.color
スプライトの色です。
テクスチャ属性が設定されている場合には、画像は指定した色で薄く着色されます。テクスチャ属性が None の場合には、色は、色付きの長方形を描画する際に使用されます。
SpriteNode.shader
ストライプがカスタマイズしたシェーダーを使用して描画されるかどうかを決める属性です。
デフォルト値は None で、スプライトの描画を普通に行うことを意味します。この属性にシェーダーが設定されている場合には、スプライトの描画にカスタマイズされたシェーダーが用いられます。
SpriteNode.size
スプライトの縦と横のサイズで、単位はポイント(約0.35mm)です。テクスチャ属性を設定している場合には、サイズは自動的にテクスチャの寸法に設定されます。
SpriteNode.texture
テクスチャは、スプライトの描画に使用されます。
値が None の場合、スプライトは色属性を使用して色付きの長方形として描画されます。その他の場合には、スプライトの描画にテクスチャが使用されます。
エフェクトノード
class scene.EffectNode([position=(0, 0), z_position=0.0, scale=1.0, x_scale=1.0, y_scale=1.0, alpha=1.0, speed=1.0, parent=None])
エフェクトノードオブジェクトは、後処理のエフェクトに適用することができます。
新しいフレームは、常にエフェクトノードを使用して描画されます。エフェクトノードは、以下のステップのように動作します:
- エフェクトノードは、その子ノードをプライベートのフレームバッファに描画します。
- プライベートのフレームバッファのコンテンツを、標準のブレンドモードの一つを使って、スプライトノードと同様に、親のフレームバッファに合成します。より進んだ後処理のエフェクトをかけるため、カスタマイズしたシェーダーを使うことも可能です。
エフェクトノードの属性
EffectNode.crop_rect
エフェクトノードの座標系の長方形で、エフェクトノードの子ノードにどれだけの範囲の描画をするかを指定します。
デフォルトでは、エフェクトノードにより、子ノードの、これまでに描画されてきたフレーム上の長方形群のサイズと位置が自動的にきめられます。ところが、いくつかのケース、特に頻繁に子ノードのサイズが変更される場合や、子ノードのいくつかが画面上からはずれる場合には、この方法では効率が悪くなることがあります。
EffectNode.blend_mode
ブレンドモードは、親ノードのフレームバッファにフィルターをかけた画像を描画する際に使用されます。
この属性に設定可能な値は、後述する「ブレンドモード」のリストの通りです。デフォルト値は BLEND_NORMAL です。
EffectNode.effects_enabled
False に設定すると、エフェクトノードは一般のノードと同様に描画されます。(シェーダー、ブレンドモード、長方形群は無視されます。)デフォルトの値は True です。
EffectNode.shader
エフェクトノードを親ノードのフレームバッファに反映する際に呼び出される、カスタマイズされたシェーダーです。
デフォルト値は None で、デフォルトのブレンドが実行されます。シェーダーを指定すると、画像を親ノードのフレームバッファにブレンドする際に、そのシェーダーを適用します。
ラベルノード
class scene.LabelNode(text, font=('Helvetica', 20), *args, **kwargs)
ラベルノードは指定されたフォントを用いて、画像に文字列を描画し、自動的にテクスチャを生成することに特化した、スプライトノードの子クラスです。LabelNode.text や LabelNode.font 属性を設定すると、テクスチャは自動的にアップデートされます。
デフォルトでは、テキストはノードの中央に配置されます。この位置については、Node.anchor_point 属性を調整することで、変更可能です。
ラベルノードの属性
LabelNode.text
ラベルに描画する文字列です。
LabelNode.font
ラベルに用いられるフォントです。フォント名称とフォントサイズ(ポイント単位)の2要素タプルです。
シェイプノード
class scene.ShapeNode(path=None, fill_color='white', stroke_color='clear', shadow=None, *args, **kwargs)
シェイプノードは、ui.Path(ベクターシェイプ) を描画することに特化したスプライトノードの子クラスです。
シェイプは塗り潰し色と輪郭線の色をカスタマイズでき、オプションで影を描画することができます。
シェイプノードの属性
ShapeNode.path
描画しようとするシェイプを示す ui.Path オブジェクトです。ui.Path.line_width 属性により、描画されるシェイプの線の幅を指定します。
ShapeNode.fill_color
シェイプを塗り潰す際の色です。
ShapeNode.stroke_color
シェイプの輪郭線の色です。
ShapeNode.shadow
色、x 方向オフセット、y 方向オフセット、半径の4要素タプルで、影の付け方を指定します。None に設定すると、影は描画されません。
その他のクラスOther Classes
シーンビュー
class scene.SceneView
シーンビューは ui.View の子クラスで、シーンのコンテンツを描画したり、描画のループを実行したりします。
一般的には、シーンビューを明確に生成することはありません。run() 関数を呼び出すと、シーンビューは自動的に実行されます。この方法でシーンを実行した後でビューの属性を修正する場合、この Scene.view 属性を使って、ビューにアクセスすることができます。
デバッグのために、SceneView は画面最下端の「ステータスライン」に例外的に標準的な画面出力をするようになっています。そのため、シーンが画面全体をカバーしている場合でも、スクリプト開発中に print 文を使うことができます。
シーンビューの属性
SceneView.scene
現在ビューの中に表示されているシーンです。この属性を設定しない場合、ビューは空になります。
SceneView.paused
これを True に設定すると、描画ループは一時停止になります。
SceneView.frame_interval
デフォルトでは、frame_interval は1になっており、描画ループは1秒間に60回更新されます。より大きい値に設定すると、更新頻度が下がります。例えば、2に設定すると1秒間に30フレームの更新となります。明示的にシーンビューを生成しない場合には、run() 関数への引数としてこの値を渡すこともできます。
SceneView.anti_alias
これを True に設定すると、4倍の頻度でのサンプリングができるようになります。この時、(往々にして重要なことに)デバイスの能力を喰ってしまうので、デフォルトでは False に設定されています。
SceneView.shows_fps
True に設定すると、デバッグのために、現在のフレームレートを画面上に表示します。
シェーダー
class scene.Shader(shader_src)
シェーダーオブジェクトは、シェイプノードオブジェクトやエフェクトノードオブジェクトの描画時の動作をカスタマイズするのに使用可能な、OpenGL(CGライブラリー)のフラグメントシェーダーを示します。
シェーダーのプログラミングは難しい内容であり、完全な紹介はこの文書の目的を超えてしまいますが、基本的な考え方は極めてシンプルです。本質的には、フラグメントシェーダーは直接的にGPU上で実行される、全ての画素に色の値を設定する関数/プログラムです。シェーダーはC言語によく似たGLシェーディング言語で書かれています。
スプライトノードのデフォルトのシェーダーは基本的に、関連したテクスチャに対応する色を見つけるための、テクスチャの同等の入力(これは自動的に設定されます)のためだけに使用します。シンプルなシェーダーは、結果として生じる色の値を調整(例えば、カラーからグレースケールへの変換)したり、モーフィング効果にテクスチャを調和させたりします。
シェーダーには2種類の入力方法があります:バリイングとユニフォームです。本質的に、バリイングが補間などをするのに対して、ユニフォームでは全ての画素/フラグメントに同一の値を与えます。バリイングの例としては、全ての画素が明確に異なる、テクスチャの座標があります。ユニフォームの例としては、スプライトのサイズや現在時刻があります。
バリイングやユニフォームの組合せは、スプライトノードやエフェクトノードをカスタマイズしたシェーダーで描画する際に自動的に設定されます:
- uniform float u_time – シーンのアニメーションループの現在のタイムスタンプです。
- uniform vec2 u_sprite_size – スプライトのポイント単位のサイズです。
- uniform float u_scale – スクリーンのスケールファクターです。(retinaディスプレイの場合は通常2.0です。)u_sprite_size を実際のスクリーンの画素に変換する際に使用できます。
- uniform sampler2D u_texture – スプライトのテクスチャです。(エフェクトノードについては、このテクスチャは子ノードでの描画を含みます。)
- uniform vec4 u_tint_color – スプライトのプレマルチプライド(事前乗算)する色です。 (SpriteNode.color 属性に対応しています。)
- uniform vec4 u_fill_color – スプライトがテクスチャを持っていない場合、この属性が u_tint_color の代わりに使用されます。
- varying vec2 v_tex_coord – 現在のテクスチャ(UV)の座標です。
これらのユニフォームやバリイングが自動的に設定された場合でも、使用する場合にはシェーダーの中で宣言をする必要があります。
Shader.ser_uniform() メソッドを使用してカスタマイズしたユニフォームを宣言し設定することもできます。カスタマイズしたユニフォームはテクスチャ(sampler2D)、浮動小数点、2/3/4要素のベクトル(vec2/vec3/vec4)のいずれかです。
以下の例は、Pythonista のアイコンに興味深い「リップル」効果を与えるものです。同時に、ユニフォームを設定することで、シェーダーの挙動をどのようにアレンジできるかも示しています。このケースでは、リップル効果の中心は画面にタッチする場所に応じて変わります。:
from scene import * ripple_shader = ''' precision highp float; varying vec2 v_tex_coord; // これらの uniforms は自動的に設定されます: uniform sampler2D u_texture; uniform float u_time; uniform vec2 u_sprite_size; // この uniform は画面へのタッチに応じて設定されます。: uniform vec2 u_offset; void main(void) { vec2 p = -1.0 + 2.0 * v_tex_coord + (u_offset / u_sprite_size * 2.0); float len = length(p); vec2 uv = v_tex_coord + (p/len) * 1.5 * cos(len*50.0 - u_time*10.0) * 0.03; gl_FragColor = texture2D(u_texture,uv); } ''' class MyScene (Scene): def setup(self): self.sprite = SpriteNode('test:Pythonista', parent=self) self.sprite.shader = Shader(ripple_shader) self.did_change_size() def did_change_size(self): # Center the image: self.sprite.position = self.size/2 def touch_began(self, touch): self.set_ripple_center(touch) def touch_moved(self, touch): self.set_ripple_center(touch) def set_ripple_center(self, touch): # Center the ripple effect on the touch location by setting the `u_offset` shader uniform: dx, dy = self.sprite.position - touch.location self.sprite.shader.set_uniform('u_offset', (dx, dy)) run(MyScene())
Shader.get_uniform(name)
引数 name で指定したユニフォームの現在の値を返します。ユニフォームの型は、float, vec2, vec3, vec4 のいずれかでなければなりません。(すなわち、sampler/texture ユニフォームはこのメソッドの対象外です)無効なユニフォームの名称の場合には、None を返します。
Shader.set_uniform(name, value)
引数 name で指定したユニフォームに新しい値を設定します。値には、float型 か int型のシングルのユニフォームか、vec2, vec3, vec4型のベクトルのユニフォーム、またはsampler2D のテクスチャオブジェクトのユニフォームのいずれかを指定します。他の型のユニフォームには対応していません。
アクション
class scene.Action
アクションオブジェクトは、通常ノードの属性を変更して時間の経過とともに画面を変化させます。Node.run_action() メソッドを使用してノードに付け加えることが可能です。
異なるタイプのアクション(異なるノードの属性へのアクション)は、異なるクラスのメソッドを使用して生成します。例えば、Action.move_to() や Action.rotate_by() などです。
一度ノードにアクションが追加されると、それ以上の変更はできませんが、 Node.remove_action() や Node.remove_all_actions() を使って削除することはできます。(この時、アニメーションは停止します。
アクションの中には、他のアクションの挙動を変更するものがあります:
Action.sequence() は複数の子供のアクションを持っています。一連のシーケンスの中のアクションは、その前に実行されるアクションが終了した後に開始されます。
Action.group() も複数の子供のアクションを持っています。グループとして保存された全てのアクションは、全てが同時に実行開始されます。グループ全体は、全てのアクションが終了してから終了となります。Action.sequence() との組合せによりとても便利に使うことができます。
Action.repeat() アクションは一つの子アクションを持ちます。子アクションが終了した後、再び実行します。
シーケンス、グループ、リピートの3つのアクションは入れ子構造にすることができます。このアクション同士を組み合わせる機能を用いることによって、ノードに洗練された挙動を加えることができます。
デフォルトでは、アニメーションのアクションの継続時間は0.5秒になっています。
classmethod Action.call(func[, duration])
関数として(またはその他の呼び出し可能なオブジェクトとして)呼び出せるカスタマイズしたアクションを生成します。
引数 duration を省略した場合、関数は1回呼び出され、他の引数を用いることはできません。
引数 duration を使用した場合、アクションが実行され、進行中の(0.0から1.0の間の)ノードが関数に渡されます。この時、以下のスクリプトを使用することになります:
def custom_action(node, progress): pass # ここにノードに対する処理を記述…
classmethod Action.fade_by(alpha[, duration, timing_mode])
ノードのアルファ値(不透明さの指標)を相対的な値で調整するアクションを生成します。
このアクションを実行すると、Node.alpha 属性が新しい値へと連続的に変更されます。
classmethod Action.fade_to(alpha[, duration, timing_mode])
ノードのアルファ値(不透明さの指標)を新しい値に変化させるアクションを生成します。
このアクションを実行すると、Node.alpha 属性は新しい値に変更されます。
classmethod Action.group(actions...)
並行してグループのアクションを動作させるアクションを生成します。
アクションを実行すると、グループのアクションの全てが即座に開始され、並行に動作します。グループのアクションの動作時間はグループの中の最も長い時間実行されるものの動作時間と同じになります。グループの中に短い時間で終了するアクションがある場合には、グループの他のアクションが完了するまでアイドリングすることになります。この事は、一群のアクションを繰り返すようなアクションの繰り返しを設定する際に重要です。
このメソッド を、呼び出す際に、一連のアクションを単体の引数、または例えばリスト型のような一つの連なりを示す引数を渡す事ができます。
classmethod Action.move_by(dx, dy[, duration, timing_mode])
ノードを現在の位置から相対的位置に移動するアクションを生成します。
classmethod Action.move_to(x, y[, duration, timing_mode])
ノードを現在の位置から新しい位置へ移動するアクションを生成します。
classmethod Action.repeat(action, repeat_count)
引数 action を引数 repeat_count の回数だけ繰り返すアクションを生成します。引数 repeat_count が負の値の場合には、引数 action で指定されたアクションを無限に繰り返します。(もしくは明示的に削除されるまで繰り返します。)
classmethod Action.repeat_forever(action)
引数 action で指定されたアクションを際限なく繰り返すアクションを生成します。
classmethod Action.rotate_by(radians[, duration, timing_mode])
引数 radians で指定した相対的な角度だけノードを回転するアクションを生成します。
classmethod Action.rotate_to(radians[, duration, timing_mode])
ノードを引数 radians で指定した絶対的な角度(時計回り)に回転させるアクションを生成します。
classmethod Action.scale_by(scale[, duration, timing_mode])
ノードの x, y 方向の尺度を相対的な値で変更するアクションを生成します。
classmethod Action.scale_to(scale[, duration, timing_mode])
ノードの x, y 方向の尺度を変更するアクションを生成します。
classmethod Action.scale_x_to(scale[, duration, timing_mode])
ノードの x 方向の尺度を変更するアクションを生成します。
classmethod Action.scale_y_to(scale[, duration, timing_mode])
ノードの y 方向の尺度を変更するアクションを生成します。
classmethod Action.set_uniform(name, value[, duration, timing_mode])
引数で指定されたシェーダーユニフォームを新しい値へと変化させていくアクションを生成します。このアクションは、スプライトノードとエフェクトノードのオブジェクトに限定されることにご注意ください。引数 value は浮動小数点のユニフォームとしての単体の数字か、vec2, vec3, vec4 のユニフォームとしての2〜4の数字のセットである必要があります。
classmethod Action.sequence(actions...)
連続的に実行されるアクション群を実行するアクションを生成します。
アクションが実行される際には、一連のアクション群の最初のアクションが開始され、完了するまで実行されます。それに続くアクションは一連のアクションの全てが実行されるまで、同じ形で実行されます。一連のアクションの所要時間は、個々のアクションの所要時間の合計になります。
一連のアクションについては、独立した引数またはリスト形式の様な1連なりの引数としてメソッドに渡す事ができます。
classmethod Action.wait(wait_duration)
引数 wait_duration で指定した時間が経過するまでアイドリングするアクションを生成します。
このアクションを実行すると、指定した時間待機し、そして終了します。通常は、アクション中の二つの異なるアクションの間に時間的間隔をあけるために使用されます。
Action の属性
Action.duration
アクションの継続時間(秒単位)です。アクションの種類(例えば、グループやシーケンス)によっては、duration は無視されます。なお、アクションをノードに追加した後に duration やその他の属性を変更しても効果はないことに注意が必要です。
Action.timing_mode
アクションを実行する際に使用されるタイミングモードです。
この属性に設定可能な値のリストはタイミングモードの項を参照して下さい。デフォルトの値は TIMING_LINEAR です。
アクションの種類(例えば、グループやシーケンス)によっては、タイミングモードは無視されます。なお、アクションをノードに追加した後に timing_mode やその他の属性を変更しても効果はないことに注意が必要です。
テクスチャ
class scene.Texture(image)
テクスチャーオブジェクトはスプライトノードのオブジェクトが、そのコンテンツを描画する際に使用されます。テクスチャはGPUのメモリーに読み込まれた画像です。テクスチャは、システムに組込まれたイメージ(文字列)の名前や、ui.Image のオブジェクトを使って初期化することができます。
Texture.subtexture(rect)
既に存在しているテクスチャ上の長方形の領域から、新しいテクスチャを生成します。返されるテクスチャオブジェクトは、同じテクスチャデータを元のテクスチャオブジェクトと共有します。すなわち、メモリー上に保管されるテクスチャデータは一つだけだという事です。
引数 rect には、ユニット座標の一部、例えば(0, 0, 0.5, 0.5)を記述します。この場合、元のテクスチャの左下部分からテクスチャを生成することになります。
このメソッドはスプライトシートやテクスチャアトラス(複数の画像を一枚の画像にまとめたもの)に使用できます。
Texture.filtering_mode
フィルタリングモードはテクスチャの拡大縮小する際に使用されます。後述するテクスチャフィルタリングモードの定数リストの値を取ることができます。(デフォルト値は FILTERING_LINEAR です。)
Texture.size
テクスチャの画素単位のサイズです。画面の拡大縮小の要素は考慮しないことに注意が必要です。
タッチ
class scene.Touch(x, y, prev_x, prev_y, touch_id)
このクラスのインスタンスは、Scene.touch_began(), Scene.touch_moved() および Scene.touch_ended() メソッドに渡されます。シーンオブジェクトにもタッチ属性があります。(touch_id をタッチオブジェクトに対応させるディクショナリー型です。)
Touch.location
タッチしている現在の場所をポイントオブジェクトとして示します。
Touch.prev_location
動く前のタッチしていた場所をポイントオブジェクトとして示します。
幾何学的な型
Vector2
class scene.Vector2(x, y)
Vector2 クラスは Point と Size の基礎となるクラスです。
Vector(および点、サイズ)については、加算(+)、減算(ー)、乗算(*)、除算(/)の処理ができます。加算と減算は2つのベクトルが対象です。乗算と除算はベクトルまたはスカラー値(数字)にも適用できます。
システムに組込まれている abs() 関数にベクトルを渡すと、ベクトルの長さが返されます。この方法は、特に減算と組合せることにより威力を発揮し、例えば abs(p2 - p1) のような形で2点間の距離を簡単に算出することができます。
演算子として使うことで、ある点が長方形の中にあるかどうかの判定に使うことができます。
多くの場合、Vector2 は2要素のタプルと同様の挙動をします。例えば、x 成分について添字表記(v[0])を使ってアクセスすることができます。Vector はイテレーションや引数のアンパック等にも対応しています。
Vector2 の点やサイズのオブジェクトをscene モジュールの属性として使用する場合には、4つの数値(例えばリストやタプル)の連なりとして与えることもできます。
点
class scene.Point(x, y)
Vector2 のサブクラスで、点を表すのに使用します。このクラスは追加のメソッドや属性を持たせることはできません。
サイズ
class scene.Size(w, h)
Vector2 のサブクラスで、サイズを表すのに使用します。Vector2 と比べると、x, y 成分に Size.w(width) や Size.h(height) を使用してアクセスできる点だけが異なります。
長方形
class scene.Rect(x, y, w, h)
Rect クラスは箱の境界を示したり、例えば、Node.frame 属性の様な他の長方形の値として使用されます。長方形は (x, y, w[idth], h[eight]) という形で、基準点(x, y) は長方形の左下を原点として表現されます。
多くの場合、Rect は4要素のタプルと同様の振る舞いをします。例えば、x 成分について添字表記(r[0])を使ってアクセスすることができます。長方形はイテレーションや引数のアンパック等にも対応しています。
Rect オブジェクトをscene モジュールの属性として使用する場合には、4つの数値(例えばリストやタプル)の連なりとして与えることもできます。
Rect.x
長方形の左下隅の x 座標です。
Rect.y
長方形の左下隅の y 座標です。
Rect.w
Rect.width
長方形の幅です。
Rect.h
Rect.height
長方形の高さです。
Rect.origin
Point(rect.x, rect.y) と等価です。
Rect.size
Size(rect.w, rect.h) と等価です。
Rect.min_x
min(rect.x, rect.x + rect.w) と等価です。(長方形の左端の x 座標です。)
Rect.max_x
max(rect.x, rect.x + rect.w) と等価です。(長方形の右端の x 座標です。)
Rect.min_y
min(rect.y, rect.y + rect.h) と等価です。(長方形の下端の y 座標です。)
Rect.max_y
max(rect.y, rect.y + rect.h) と等価です。(長方形の上端の y 座標です。)
Rect.center([p])
引数なしで呼び出した場合には、長方形の中心を返します。引数に Point を渡した場合、長方形の x と y の値が調整され、長方形の新しい中心が p になります。
Rect.contains_point(p)
引数 p で与えた点が長方形の領域内の場合には True を、その他の場合には False を返します。
Rect.contains_rect(other_rect)
引数 other_rect で与えた長方形がこの長方形の領域に完全に入っている場合には True を、その他の場合には False を返します。
Rect.intersects(other_rect)
この長方形が他の長方形と交わっている場合には True を、その他の場合には False を返します。
Rect.intersection(other_rect)
この長方形と他の長方形が交差する部分の長方形を返します。
Rect.union(other_rect)
2つの長方形を含む最小の長方形を返します。
Rect.translate(x, y)
Rect(r.x + x, r.y + y, r.w, r.h)と等価です。
Rect.inset(top, left[, bottom, right])
引数で与えた境界に合わせて変形した長方形を返します。bottom/right はオプションで、デフォルトでは top/left と同じ値になります。
関数
scene.gravity()
現在の重力ベクトル(x, y, z) を返します。いずれの座標も 0.0 から 1.0 の間の値となります。特にモーションコントロールゲームで、デバイスの現在の向きを判定するのに使われます。
scene.get_screen_size()
スクリーンのサイズを Size オブジェクトとしてポイント単位の値で返します。値はデバイスの方向に依存することに注意が必要です。x, y のどの方向が小さいか(縦表示か横表示か)を調べるには、min(get_screen_size()) を使用することができます。
scene.get_screen_scale()
現在のデバイスの画面の縮尺を返します。retina ディスプレイでは通常、2.0または3.0で、ratina ディスプレイ以外の場合には1.0です。
scene.get_image_path(name)
システム組込みの画像名称に対応するファイルの絶対パスを返します。
scene.run(scene, orientation=DEFAULT_ORIENTATION, frame_interval=1, anti_alias=False, show_fps=False, multi_touch=True)
引数 scene で与えられた Scene オブジェクトを実行します。デフォルトでは、scene は現在のデバイスの向きで実行されます。引数 orientation を PORTRAIT(縦画面) または LANDSCAPE(横画面) に設定することで画面の縦横を指定し、自動回転機能を止めることができます。重要な点ですが、iOS 10 以降の iPad では、この orientation パラメーターによる指定は無効となります。画面分割と並行処理ができるアプリでは、技術的に画面の縦横を固定できないようになっているためです。
デフォルトでは、scene の update() メソッドは1秒間に60回呼び出されます。引数 frame_interval を2に設定すると一秒間に30回、3に設定すると一秒間に20回という具合に時間当たりの呼び出し頻度を変更できます。
scene.get_controllers()
接続中の全てのMFiゲームコントローラーの現在の状態をディクショナリ型のリストとして返します。(ゲームコントローラーの項についても参照下さい)
定数
Orientations
以下の定数は、run() 関数の方向のパラメーターとして使われます。
scene.DEFAULT_ORIENTATION
現在のデバイスの方向で、オートローテーションに従って、シーンを開始します。
scene.PORTRAIT
強制的に縦画面にします。
scene.LANDSCAPE
強制的に横画面にします。
ブレンドモード
scene.BLEND_NORMAL
元の画像と目的の色を、元の画像のアルファ値(不透明度)を乗じてブレンドします。
scene.BLEND_ADD
元の画像と目的の色を、加算してブレンドします。
scene.BLEND_MULTIPLY
元の画像の色に目的の色を乗じてブレンドします。
テクスチャのフィルターモード
以下の定数は Texture.filtering_mode 属性に使用されます。
scene.FILTERING_LINEAR
直線的に変化するよう補間します。デフォルトのフィルターモードです。
scene.FILTERING_NEAREST
最も近い点の色を用いて補間します。低解像度のアートワークを拡大する際に境界がシャープになるため、ピクセルアートに用いるモードとしてお勧めです。
タイミングモード
以下の定数は、アクションオブジェクトの補間関数を設定するための timing_mode 属性に使用可能です。
scene.TIMING_LINEAR
シンプルな直線補間です。(デフォルト値)
scene.TIMING_EASE_IN
イースイン(ゆっくり動き出して加速していく)補間です。
scene.TIMING_EASE_IN_2
2次のイースイン補間です。
scene.TIMING_EASE_OUT
イースアウト(早く動いて、ゆっくりと止まる)補間です。
scene.TIMING_EASE_OUT_2
2次のイースアウト補間です。
scene.TIMING_EASE_IN_OUT
イースイン・イースアウト補間です。
scene.TIMING_SINODIAL
TIMING_EASE_IN_OUTに似た、しかし幾分ゆったりした部分を減らした補間です。
scene.TIMING_ELASTIC_IN
アニメーションの最初の部分に「ラバーバンド」効果を与えます。
scene.TIMING_ELASTIC_OUT
アニメーションの最後の部分に「ラバーバンド」効果を与えます。
scene.TIMING_ELASTIC_IN_OUT
アニメーションの最初と最後の部分に「ラバーバンド」効果を与えます。
scene.TIMING_BOUNCE_IN
アニメーションの最初の部分に「バウンド」効果を与えます。
scene.TIMING_BOUNCE_OUT
アニメーションの最後の部分に「バウンド」効果を与えます。
scene.TIMING_BOUNCE_IN_OUT
アニメーションの最初と最後の部分に「バウンド」効果を与えます。
scene.TIMING_EASE_BACK_IN
アニメーションの最初の部分に「行き過ぎて戻る」効果を与えます。
scene.TIMING_EASE_BACK_OUT
アニメーションの最後の部分に「行き過ぎて戻る」効果を与えます。
scene.TIMING_EASE_BACK_IN_OUT
アニメーションの最初と最初の部分に「行き過ぎて戻る」効果を与えます。