ピクセルデータを、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から新たにサポートされました。
Functions to convert pixel data between pygame Surfaces and arrays. This module will only be functional when pygame can use the external Numpy or Numeric packages.
Every pixel is stored as a single integer value to represent the red, green, and blue colors. The 8bit images use a value that looks into a colormap. Pixels with higher depth use a bit packing process to place three or four values into a single number.
The arrays are indexed by the X axis first, followed by the Y axis. Arrays that treat the pixels as a single integer are referred to as 2D arrays. This module can also separate the red, green, and blue color values into separate indices. These types of arrays are referred to as 3D arrays, and the last index is 0 for red, 1 for green, and 2 for blue.
Supported array systems are
numpy numeric
The default will be numpy, if installed. Otherwise, Numeric will be set as default if installed. If neither numpy nor Numeric are installed, the module will raise an ImportError.
The array type to use can be changed at runtime using the use_arraytype () method, which requires one of the above types as string.
Note: numpy and Numeric are not completely compatible. Certain array manipulations, which work for one type, might behave differently or even completely break for the other.
Additionally, in contrast to Numeric numpy does use unsigned 16-bit integers. Images with 16-bit data will be treated as unsigned integers. Numeric instead uses signed integers for the representation, which is important to keep in mind, if you use the module's functions and wonder about the values.
The support of numpy is new in pygame 1.8.
Surfaceオブジェクト上のピクセルデータをコピーし、二次配列形式に変換します。Surfaceオブジェクトのビット深度によって配列に格納される整数値の大きさが変わります。この命令はSurfaceのビット深度に関係なく実行することができます。
ピクセルをコピーするので、この命令を実行するとSurfaceオブジェクトが一時的にロックされます (ロックの詳細についてはSurface.lock命令を参照してください)。
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).
Surfaceオブジェクト上のピクセル情報を参照する二次配列形式のデータを、新規に作成します。配列データを編集すると、Surfaceオブジェクト上のピクセルにもその結果が反映されます。この命令ではピクセルデータのコピーが行われないので、高速な処理が行われます。
24bit以上のSurfaceのピクセルデータにこの機能は使えませんが、それ以外のビット深度であれば問題なく使用できます。
参照された状態のSurfaceオブジェクトは、配列データが削除されるまでロックされた状態となります(ロックの詳細についてはSurface.lock命令を参照してください)。
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).
Surfaceオブジェクト上のピクセルデータをコピーし、三次配列形式に変換します。Surfaceオブジェクトのビット深度によって配列に格納される整数値の大きさが変わります。この命令はSurfaceのビット深度に関係なく実行することができます。
ピクセルをコピーするので、この命令を実行するとSurfaceオブジェクトが一時的にロックされます (ロックの詳細についてはSurface.lock命令を参照してください)。
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).
Surfaceオブジェクト上のピクセル情報を参照する三次配列形式のデータを、新規に作成します。配列データを編集すると、Surfaceオブジェクト上のピクセルにもその結果が反映されます。この命令ではピクセルデータのコピーが行われないので、高速な処理が行われます。
この命令は24bitか32bitのSurfaceオブジェクトでのみ実行できます。24bit未満のピクセル形式では実行できません。
参照された状態のSurfaceオブジェクトは、配列データが削除されるまでロックされた状態となります(ロックの詳細についてはSurface.lock命令を参照してください)。
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).
Surfaceオブジェクト上のピクセルのアルファ値（透明度）をコピーし、二次配列形式に変換します。この命令はSurfaceのビット深度に関係なく実行することができます。ピクセルにアルファ値が設定されていないSurfaceオブジェクトの場合、 全ての位置に不透明値が格納された二次配列を戻り値として返します。
ピクセルをコピーするので、この命令を実行するとSurfaceオブジェクトが一時的にロックされます (ロックの詳細についてはSurface.lock命令を参照してください)。
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).
Surfaceオブジェクト上のピクセルのアルファ値（透明度）を参照する二次配列形式のデータを、新規に作成します。配列データを編集すると、Surfaceオブジェクト上のピクセルにもその結果が反映されます。この命令ではピクセルデータのコピーが行われないので、高速な処理が行われます。
この命令は、ピクセル単位のアルファ値を持つ32bitのSurfaceオブジェクトでのみ実行できます。
参照された状態のSurfaceオブジェクトは、配列データが削除されるまでロックされた状態となります。
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.
全ピクセルから透過色を取得し、二次配列形式のデータとして新規に作成します。ピクセルが透過色と同じ色の場合、そのピクセル透明な状態となります。；透明色ではない場合は、色がしっかりと描写されます。
この命令はSurfaceのビット深度に関係なく実行することができます。画像に透過色が設定されていない場合、全ての位置に不透明を表す値が入った配列が戻り値として帰ります。
ピクセルをコピーするので、この命令を実行するとSurfaceオブジェクトが一時的にロックされます。
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オブジェクトを新規に作成します。任意の値の整数を保持した二次配列、もしくは三次配列を引数として設定できます。
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.
配列形式の画像データを、Surfaceオブジェクトへ直接コピーします。この命令は、配列形式のデータをSurfaceオブジェクトへ変換した上でコピー描写するよりも高速に動作します。配列のサイズはSurfaceオブジェクトのサイズと同じでなければならず、この処理によってSurfaceオブジェクト上の全てのピクセル情報は完全に書き換えられます。ASCIIコードで記載された数字が格納された配列のみを、引数として使用できます。
ピクセルをコピーするので、この命令を実行するとSurfaceオブジェクトが一時的にロックされます。
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.
三次配列形式のデータを二次配列形式に変換します。変換処理では、引数として設定したSurfaceオブジェクトのフォーマットが使用されます。カラーパレットを持つsurfaceのフォーマットには対応していません。
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.
この命令で設定したものが、surfarrayモジュールの各命令で使われる配列形式となります。現在は下記の配列形式に対応しています：
numeric numpy
対応していない配列形式を設定した場合、ValueErrorのエラーが発生します。
この命令はpygameのバージョン1.8で新たに実装されました。
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.
現在設定されている配列形式名を戻り値として返します。ここで取得できる値は、get_arraytypes()命令で取得できるタプル型の値にも含まれています。タプル型の中で、配列を作成するのに使用される既定の配列モジュールの方が取得されます。
この命令はpygameのバージョン1.8で新たに実装されました。
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.surfarray.use_arraytype()命令の引数としてそのまま使用できます。対応している配列形式が見つからない場合、None値が戻り値として返されます。
この命令はpygameのバージョン1.8で新たに実装されました。
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.