トップへ戻る Cdrom || Color || Cursors || Display || Draw || Event || Examples || Font || Gfxdraw || Image || Joystick || Key || Locals || Mask || Mixer || Mouse || Movie || Music || Overlay || Pixelarray || Pygame || Rect || Scrap || Sndarray || Sprite || Surface || Surfarray || Tests || Time || Transform
pygame.surfarray
    配列を使用して、surfaceオブジェクトのピクセルデータを直接編集するpygameモジュールです。

    ピクセルデータを、Surfacesオブジェクト形式と配列形式との間で相互変換する命令です。このモジュールは、numpyかNumericどちらかの拡張パッケージをインストールしている場合にのみ使用できます。

    全てのピクセルは、赤・緑・青を表す整数値を保持しています。8bitの深度を持つ画像では use a value that looks into a colormap.8bit以上の深度を持つ画像では、use a bit packing process to place three or four values into a single number.

    配列表記では最初の添え字がX軸、次の添え字がY軸を表します。各ピクセルの色情報を一つの整数で表す配列を、二次配列を呼びます。このモジュールでは、別の配列軸を用意して赤・緑・青といったピクセルの色情報を分けて保持することもできます。それらの配列を三次配列と呼び、最後尾の添え字が[0]の位置に赤の色情報、[1]の場合は緑の色情報、[2]の場合は青の色情報を保持しています。

    下記の配列形式をサポートしています。

      numpy
      numeric
    

    numpyモジュールがインストールされていた場合、それが既定の配列として使用されます。numpyモジュールがインストールされておらず、Numericモジュールがインストールされていた場合は、そちらが既定の配列として使用されます。

    use_arraytype()命令で上記numpyとnumericのどちらかを設定することで、使用する配列の種類を状況に応じて変更することができます。

    補足: numpy形式のデータとNumeric形式のデータは完全に互換性があるわけはありません。一方の形式では正常に動作した配列操作が、もう一方の形式では異なる動作をしたりデータを壊してしまったりすることさえあります。

    さらに言うと、numpy形式ではNumeric形式と違って符号なしの16bit整数を使用することができます。そのため16bitデータの音声を扱う場合、サンプルデータの種類によっては符号なし整数として扱われます。一方で Numeric形式は、常に符号付整数で値を表します。このpygame.sndarrayの命令を使用して取得された値がおかしいと思ったときは、それぞれの配列形式の違いを思い出してください。

    numpy形式はpygameのバージョン1.8から新たにサポートされました。



    pygame.surfarray.array2d
      ピクセルデータをコピーし、二次配列形式に変換します。
      pygame.surfarray.array2d(Surface): return array

      Surfaceオブジェクト上のピクセルデータをコピーし、二次配列形式に変換します。Surfaceオブジェクトのビット深度によって配列に格納される整数値の大きさが変わります。この命令はSurfaceのビット深度に関係なく実行することができます。

      ピクセルをコピーするので、この命令を実行するとSurfaceオブジェクトが一時的にロックされます (ロックの詳細についてはSurface.lock命令を参照してください)。



    pygame.surfarray.pixels2d
      二次配列形式のデータを通して、ピクセルデータを操作します。
      pygame.surfarray.pixels2d(Surface): return array

      Surfaceオブジェクト上のピクセル情報を参照する二次配列形式のデータを、新規に作成します。配列データを編集すると、Surfaceオブジェクト上のピクセルにもその結果が反映されます。この命令ではピクセルデータのコピーが行われないので、高速な処理が行われます。

      24bit以上のSurfaceのピクセルデータにこの機能は使えませんが、それ以外のビット深度であれば問題なく使用できます。

      参照された状態のSurfaceオブジェクトは、配列データが削除されるまでロックされた状態となります(ロックの詳細についてはSurface.lock命令を参照してください)。



    pygame.surfarray.array3d
      ピクセルデータをコピーし、三次配列形式に変換します。
      pygame.surfarray.array3d(Surface): return array

      Surfaceオブジェクト上のピクセルデータをコピーし、三次配列形式に変換します。Surfaceオブジェクトのビット深度によって配列に格納される整数値の大きさが変わります。この命令はSurfaceのビット深度に関係なく実行することができます。

      ピクセルをコピーするので、この命令を実行するとSurfaceオブジェクトが一時的にロックされます (ロックの詳細についてはSurface.lock命令を参照してください)。



    pygame.surfarray.pixels3d
      三次配列形式のデータを通して、ピクセルデータを操作します。
      pygame.surfarray.pixels3d(Surface): return array

      Surfaceオブジェクト上のピクセル情報を参照する三次配列形式のデータを、新規に作成します。配列データを編集すると、Surfaceオブジェクト上のピクセルにもその結果が反映されます。この命令ではピクセルデータのコピーが行われないので、高速な処理が行われます。

      この命令は24bitか32bitのSurfaceオブジェクトでのみ実行できます。24bit未満のピクセル形式では実行できません。

      参照された状態のSurfaceオブジェクトは、配列データが削除されるまでロックされた状態となります(ロックの詳細についてはSurface.lock命令を参照してください)。



    pygame.surfarray.array_alpha
      ピクセルのアルファ値をコピーし、二次配列形式に変換します。
      pygame.surfarray.array_alpha(Surface): return array

      Surfaceオブジェクト上のピクセルのアルファ値(透明度)をコピーし、二次配列形式に変換します。この命令はSurfaceのビット深度に関係なく実行することができます。ピクセルにアルファ値が設定されていないSurfaceオブジェクトの場合、 全ての位置に不透明値が格納された二次配列を戻り値として返します。

      ピクセルをコピーするので、この命令を実行するとSurfaceオブジェクトが一時的にロックされます (ロックの詳細についてはSurface.lock命令を参照してください)。



    pygame.surfarray.pixels_alpha
      二次配列形式のデータを通して、ピクセルのアルファ値を操作します。
      pygame.surfarray.pixels_alpha(Surface): return array

      Surfaceオブジェクト上のピクセルのアルファ値(透明度)を参照する二次配列形式のデータを、新規に作成します。配列データを編集すると、Surfaceオブジェクト上のピクセルにもその結果が反映されます。この命令ではピクセルデータのコピーが行われないので、高速な処理が行われます。

      この命令は、ピクセル単位のアルファ値を持つ32bitのSurfaceオブジェクトでのみ実行できます。

      参照された状態のSurfaceオブジェクトは、配列データが削除されるまでロックされた状態となります。



    pygame.surfarray.array_colorkey
      ピクセルの透過色情報をコピーし、二次配列形式に変換します。
      pygame.surfarray.array_colorkey(Surface): return array

      全ピクセルから透過色を取得し、二次配列形式のデータとして新規に作成します。ピクセルが透過色と同じ色の場合、そのピクセル透明な状態となります。;透明色ではない場合は、色がしっかりと描写されます。

      この命令はSurfaceのビット深度に関係なく実行することができます。画像に透過色が設定されていない場合、全ての位置に不透明を表す値が入った配列が戻り値として帰ります。

      ピクセルをコピーするので、この命令を実行するとSurfaceオブジェクトが一時的にロックされます。



    pygame.surfarray.make_surface
      配列形式のデータをコピーし、Surfaceオブジェクトに変換します。
      pygame.surfarray.make_surface(array): return Surface

      配列が記録しているデータやフォーマットに最も適した状態のSurfaceオブジェクトを新規に作成します。任意の値の整数を保持した二次配列、もしくは三次配列を引数として設定できます。



    pygame.surfarray.blit_array
      配列形式の画像データを直接コピー描写します。
      pygame.surfarray.blit_array(Surface, array): return None

      配列形式の画像データを、Surfaceオブジェクトへ直接コピーします。この命令は、配列形式のデータをSurfaceオブジェクトへ変換した上でコピー描写するよりも高速に動作します。配列のサイズはSurfaceオブジェクトのサイズと同じでなければならず、この処理によってSurfaceオブジェクト上の全てのピクセル情報は完全に書き換えられます。ASCIIコードで記載された数字が格納された配列のみを、引数として使用できます。

      ピクセルをコピーするので、この命令を実行するとSurfaceオブジェクトが一時的にロックされます。



    pygame.surfarray.map_array
      三次配列形式のデータを二次配列形式にマッピングします。
      pygame.surfarray.map_array(Surface, array3d): return array2d

      三次配列形式のデータを二次配列形式に変換します。変換処理では、引数として設定したSurfaceオブジェクトのフォーマットが使用されます。カラーパレットを持つsurfaceのフォーマットには対応していません。



    pygame.surfarray.use_arraytype
      配列型のsurfaceオブジェクトで使われる配列形式を設定します。
      pygame.surfarray.use_arraytype (arraytype): return None

      この命令で設定したものが、surfarrayモジュールの各命令で使われる配列形式となります。現在は下記の配列形式に対応しています:

        numeric
        numpy
      

      対応していない配列形式を設定した場合、ValueErrorのエラーが発生します。

      この命令はpygameのバージョン1.8で新たに実装されました。



    pygame.surfarray.get_arraytype
      現在設定されている既定の配列形式を取得します。
      pygame.surfarray.get_arraytype (): return str

      現在設定されている配列形式名を戻り値として返します。ここで取得できる値は、get_arraytypes()命令で取得できるタプル型の値にも含まれています。タプル型の中で、配列を作成するのに使用される既定の配列モジュールの方が取得されます。

      この命令はpygameのバージョン1.8で新たに実装されました。



    pygame.surfarray.get_arraytypes
      pygameが、現時点で対応している配列形式を取得します。
      pygame.surfarray.get_arraytypes (): return tuple

      どの配列形式が使用できるかを調べ、使用できるものをタプル型の文字列の戻り値として返します。取得されたタプル型の各値は、pygame.surfarray.use_arraytype()命令の引数としてそのまま使用できます。対応している配列形式が見つからない場合、None値が戻り値として返されます。

      この命令はpygameのバージョン1.8で新たに実装されました。



トップへ戻る Cdrom || Color || Cursors || Display || Draw || Event || Examples || Font || Gfxdraw || Image || Joystick || Key || Locals || Mask || Mixer || Mouse || Movie || Music || Overlay || Pixelarray || Pygame || Rect || Scrap || Sndarray || Sprite || Surface || Surfarray || Tests || Time || Transform