pygame.surfarray.array2d - ピクセルデータをコピーし、二次配列形式に変換します。

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

pygame.surfarray.array3d - ピクセルデータをコピーし、三次配列形式に変換します。

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

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

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

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

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

pygame.surfarray.blit_array - 配列形式の画像データを直接コピー描写します。

pygame.surfarray.map_array - 三次配列形式のデータを二次配列形式にマッピングします。

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

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

pygame.surfarray.get_arraytypes - 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(Surface): return array


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

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




Copy pixels into a 2d array. pygame.surfarray.array2d(Surface): return array Copy the pixels from a Surface into a 2D array. The bit depth of the surface will control the size of the integer values, and will work for any type of pixel format. This function will temporarily lock the Surface as pixels are copied (see the Surface.lock - lock the Surface memory for pixel access method).

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


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

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

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




Reference pixels into a 2d array pygame.surfarray.pixels2d(Surface): return array Create a new 2D array that directly references the pixel values in a Surface. Any changes to the array will affect the pixels in the Surface. This is a fast operation since no data is copied. Pixels from a 24-bit Surface cannot be referenced, but all other Surface bit depths can. The Surface this references will remain locked for the lifetime of the array (see the Surface.lock - lock the Surface memory for pixel access method).

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


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

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




Copy pixels into a 3d array pygame.surfarray.array3d(Surface): return array Copy the pixels from a Surface into a 3D array. The bit depth of the surface will control the size of the integer values, and will work for any type of pixel format. This function will temporarily lock the Surface as pixels are copied (see the Surface.lock - lock the Surface memory for pixel access method).

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


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

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

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




Reference pixels into a 3d array pygame.surfarray.pixels3d(Surface): return array Create a new 3D array that directly references the pixel values in a Surface. Any changes to the array will affect the pixels in the Surface. This is a fast operation since no data is copied. This will only work on Surfaces that have 24-bit or 32-bit formats. Lower pixel formats cannot be referenced. The Surface this references will remain locked for the lifetime of the array (see the Surface.lock - lock the Surface memory for pixel access method).

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


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

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




Copy pixel alphas into a 2d array pygame.surfarray.array_alpha(Surface): return array Copy the pixel alpha values (degree of transparency) from a Surface into a 2D array. This will work for any type of Surface format. Surfaces without a pixel alpha will return an array with all opaque values. This function will temporarily lock the Surface as pixels are copied (see the Surface.lock - lock the Surface memory for pixel access method).

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


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

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

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




Reference pixel alphas into a 2d array pygame.surfarray.pixels_alpha(Surface): return array Create a new 2D array that directly references the alpha values (degree of transparency) in a Surface. Any changes to the array will affect the pixels in the Surface. This is a fast operation since no data is copied. This can only work on 32-bit Surfaces with a per-pixel alpha value. The Surface this array references will remain locked for the lifetime of the array.

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


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

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

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




Copy the colorkey values into a 2d array pygame.surfarray.array_colorkey(Surface): return array Create a new array with the colorkey transparency value from each pixel. If the pixel matches the colorkey it will be fully tranparent; otherwise it will be fully opaque. This will work on any type of Surface format. If the image has no colorkey a solid opaque array will be returned. This function will temporarily lock the Surface as pixels are copied.

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


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




Copy an array to a new surface pygame.surfarray.make_surface(array): return Surface Create a new Surface that best resembles the data and format on the array. The array can be 2D or 3D with any sized integer values.

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


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

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




Blit directly from a array values pygame.surfarray.blit_array(Surface, array): return None Directly copy values from an array into a Surface. This is faster than converting the array into a Surface and blitting. The array must be the same dimensions as the Surface and will completely replace all pixel values. Only integer, ascii character and record arrays are accepted. This function will temporarily lock the Surface as the new values are copied.

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


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




Map a 3d array into a 2d array pygame.surfarray.map_array(Surface, array3d): return array2d Convert a 3D array into a 2D array. This will use the given Surface format to control the conversion. Palette surface formats are not supported.

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


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

  numeric
  numpy

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

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




Sets the array system to be used for surface arrays pygame.surfarray.use_arraytype (arraytype): return None Uses the requested array type for the module functions. Currently supported array types are: numeric numpy If the requested type is not available, a ValueError will be raised. New in pygame 1.8.

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


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

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




Gets the currently active array type. pygame.surfarray.get_arraytype (): return str Returns the currently active array type. This will be a value of the get_arraytypes() tuple and indicates which type of array module is used for the array creation. New in pygame 1.8

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


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

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




Gets the array system types currently supported. pygame.surfarray.get_arraytypes (): return tuple Checks, which array systems are available and returns them as a tuple of strings. The values of the tuple can be used directly in the pygame.surfarray.use_arraytype () method. If no supported array system could be found, None will be returned. New in pygame 1.8.