pygameのSurfaceクラスは画像を表示するために使用します。Surfaceクラスは固定の解像度とピクセル形式を持ちます。8ビットピクセル形式のSurfacesはカラーパレットを使用して24bitカラーで描写されます。
pygame.Surfaceを実行すると新規に画像オブジェクトを作成します。作成されたSurfaceは全面が黒一色で初期化されます。作成時に必ず設定しなければならない引数はSurfaceのサイズだけです。 サイズ以外の引数を設定しなかった場合、 Surfaceはディスプレイに合わせた最適の形式で作成されます。
Surfaceのピクセル形式は、作成時に引数として渡されるビット深度や既存Surfaceによって決定されます。 flags引数ではSurfaceに備わっている他の機能をビットマスク方式で設定します。下記のflags値を組み合わせて設定することができます:
HWSURFACE:ハードウェア側のメモリに画像を作成します。 SRCALPHA:ピクセル単位で透明度を設定できる形式です。
上記flags引数はあくまで要求を出すだけなので、ディスプレイやピクセル形式によっては指定した設定が適用されないこともあります。
上級者であればdepth引数とmasks引数を組み合わせて設定することができます。 The masks are a set of 4 integers representing which bits in a pixel will represent each color. 普通にSurfaceを使うのであればmasks引数を設定する必要はありません。
Surfaceは他にも透明度や透過色、描写可能領域といった多くの属性を設定することができます。 これらの機能は主にSurfaceに描写されている画像を他のSurface上にコピー描写する時に影響を与えます。この画像コピー処理はハードウェアの処理機能を使用できる場合はそちら使用し、使用できない場合は非常に高速化されているソフトウェアの処理機能を使用します。
Pygameでは3種類の透過処理が用意されています: 色の透過、 Surfaceの透過、ピクセルの透過です。 色の透過処理はSurfaceの透過処理と組み合わせることができますが、ピクセル透過処理を行った画像に他の透過処理を組み合わせて使うことはできません。色の透過処理では、一つの色のみが透明になります。指定された色と同じ色のピクセルは描写されません。Surfaceの透明度は、 Surface上に描写されている画像全体の透明度を表します。Surfaceの透明度が255の場合だとSurface上の画像は完全な状態で描写され、透明度が0の時は透明状態で描写されます。
ピクセル透過の場合はピクセル一つ一つが透明度を持つため、上記二つの処理とは異なります。これは最も精密な透明効果処理ですが、同時に最も遅い透明効果処理でもあります。 ピクセル透過は色の透過やSurface透過と組み合わせて使うことができません。
Surfaceクラスにはピクセルの編集を手助けする機能があります。ハードウェア上でピクセルを編集する方法は遅いためあまりお勧めできません。get_at()命令やset_at()命令を使用することでピクセルの編集ができます。これらの処理は単純な編集を行う場合には適していますが、大量のピクセルを同時に編集する時には処理が遅くなってしまいます。 もし大量のピクセルを処理したいのなら、 pygame.surfarrayモジュールを使用するのがお勧めです。pygame.surfarrayモジュールはSurfaceを大規模な多次元配列として扱います。（とても速いです。）
ピクセル編集命令を使用してSurfaceのピクセルデータを直接編集する場合は、編集するSurfaceをlock()命令でロックする必要があります。それらの命令実行時には特に何もしなくても自動でSurfaceのロックやロック解除を行われます。しかしそうした命令が一度にたくさん実行されると、Surfaceロック・ロック解除処理が多すぎて大量のオーバーヘッド負荷がかかってしまいます。大量のピクセル編集命令を実行する前にはSurfaceを手動でロックし、処理が終わった時にロックを解除するのがよいでしょう。Surfaceのロックが必要な命令はリファレンスにその旨が書かれています。必要な時だけSurfaceをロックするよう心掛けてください。
Surfaceのピクセルは単一数値情報として内部に記録されています。その数値情報とは、ピクセルが持つ(赤の輝度,緑の輝度,青の輝度)といったRGBA形式色の情報を単一数値にエンコードしたものです。Surface.map_rgb命令とSurface.unmap_rgb命令を使えば、(赤の輝度,緑の輝度,青の輝度）形式の色情報と、Surface向けにエンコードされた単一数値の色情報を相互に変換することができます。
またSurfaceは別のSurfaceの指定した範囲を参照することができます。この参照範囲は Surface.subsurface命令で作成します。元のSurfaceと参照範囲Surfaceにおいては、一方のSurfaceを変更するともう一方のSurfaceも同じように変更されます。
全てのSurfaceは描写可能領域があります。既定では描写可能領域はSurfaceの全ての範囲です。この描写可能領域を変更すれば、特定の範囲に絞った描写処理を行うことができます。
A pygame Surface is used to represent any image. The Surface has a fixed resolution and pixel format. Surfaces with 8bit pixels use a color palette to map to 24bit color.
Call pygame.Surface - pygame object for representing images to create a new image object. The Surface will be cleared to all black. The only required arguments are the sizes. With no additional arguments, the Surface will be created in a format that best matches the display Surface.
The pixel format can be controlled by passing the bit depth or an existing Surface. The flags argument is a bitmask of additional features for the surface. You can pass any combination of these flags:
HWSURFACE, creates the image in video memory SRCALPHA, the pixel format will include a per-pixel alpha
Both flags are only a request, and may not be possible for all displays and formats.
Advance users can combine a set of bitmasks with a depth value. The masks are a set of 4 integers representing which bits in a pixel will represent each color. Normal Surfaces should not require the masks argument.
Surfaces can have many extra attributes like alpha planes, colorkeys, source rectangle clipping. These functions mainly effect how the Surface is blitted to other Surfaces. The blit routines will attempt to use hardware acceleration when possible, otherwise they will use highly optimized software blitting methods.
There are three types of transparency supported in Pygame: colorkeys, surface alphas, and pixel alphas. Surface alphas can be mixed with colorkeys, but an image with per pixel alphas cannot use the other modes. Colorkey transparency makes a single color value transparent. Any pixels matching the colorkey will not be drawn. The surface alpha value is a single value that changes the transparency for the entire image. A surface alpha of 255 is opaque, and a value of 0 is completely transparent.
Per pixel alphas are different because they store a transparency value for every pixel. This allows for the most precise transparency effects, but it also the slowest. Per pixel alphas cannot be mixed with surface alpha and colorkeys.
There is support for pixel access for the Surfaces. Pixel access on hardware surfaces is slow and not recommended. Pixels can be accessed using the get_at() and set_at() functions. These methods are fine for simple access, but will be considerably slow when doing of pixel work with them. If you plan on doing a lot of pixel level work, it is recommended to use the pygame.surfarray module, which can treat the surfaces like large multidimensional arrays (and it's quite quick).
Any functions that directly access a surface's pixel data will need that surface to be lock()'ed. These functions can lock() and unlock() the surfaces themselves without assistance. But, if a function will be called many times, there will be a lot of overhead for multiple locking and unlocking of the surface. It is best to lock the surface manually before making the function call many times, and then unlocking when you are finished. All functions that need a locked surface will say so in their docs. Remember to leave the Surface locked only while necessary.
Surface pixels are stored internally as a single number that has all the colors encoded into it. Use the Surface.map_rgb - convert a color into a mapped color value and Surface.unmap_rgb - convert a mapped integer color value into a Color to convert between individual red, green, and blue values into a packed integer for that Surface.
Surfaces can also reference sections of other Surfaces. These are created with the Surface.subsurface - create a new surface that references its parent method. Any change to either Surface will effect the other.
Surface contains a clipping area. By default the clip area covers the entire Surface. If it is changed, all drawing operations will only effect the smaller area.
Surface上にソース画像を描写します。dest引数を使用して描写位置を設定することができます。 dest値はソース画像の左上隅が置かれる(x座標,y座標)を表します。dest値の代わりに、画像を描写する四角範囲(x座標,y座標,幅,高さ)のrect値を引数として渡すこともできます。rect値として設定した画像描写範囲の大きさを、ソース画像より広く設定してしまったり逆に狭く設定してしまった場合でも、画像は正常に描写されます。
dest値に加えて、area値にも同様の四角範囲を設定することができます。このarea値は、ソース画像の中から一部分だけを切り取って描写したい時に、その切り取る描写範囲として設定します。
オプションで設定できるspecial_flags引数は、pygameのver1.8.0では BLEND_ADD, BLEND_SUB, BLEND_MULT, BLEND_MIN, BLEND_MAXが追加され、ver1.8.1では BLEND_RGBA_ADD, BLEND_RGBA_SUB, BLEND_RGBA_MULT, BLEND_RGBA_MIN, BLEND_RGBA_MAX BLEND_RGB_ADD, BLEND_RGB_SUB, BLEND_RGB_MULT, BLEND_RGB_MIN, BLEND_RGB_MAXが追加され、将来的には他にも様々なspecial_flags引数を追加する予定です。
この処理の影響を受ける範囲がrect型の戻り値として返されます。Surfaceの枠外や描写可能領域外は、戻り値の範囲から除外されます。
8bitのSurfaceに画像を描写する場合。ピクセルの透過処理は適用されません。
special_flags引数はpygameのver1.8で新規に実装されました。
透過色やblanket alphaを設定しているSurfaceでは、Surface自身にSurfaceの画像を描写する場合と、他のSurfaceにSurfaceの画像を描写する場合とでは表示される色がやや異なってきます。
Draws a source Surface onto this Surface. The draw can be positioned with the dest argument. Dest can either be pair of coordinates representing the upper left corner of the source. A Rect can also be passed as the destination and the topleft corner of the rectangle will be used as the position for the blit. The size of the destination rectangle does not effect the blit.
An optional area rectangle can be passed as well. This represents a smaller portion of the source Surface to draw.
An optional special flags is for passing in new in 1.8.0: BLEND_ADD, BLEND_SUB, BLEND_MULT, BLEND_MIN, BLEND_MAX new in 1.8.1: BLEND_RGBA_ADD, BLEND_RGBA_SUB, BLEND_RGBA_MULT, BLEND_RGBA_MIN, BLEND_RGBA_MAX BLEND_RGB_ADD, BLEND_RGB_SUB, BLEND_RGB_MULT, BLEND_RGB_MIN, BLEND_RGB_MAX With other special blitting flags perhaps added in the future.
The return rectangle is the area of the affected pixels, excluding any pixels outside the destination Surface, or outside the clipping area.
Pixel alphas will be ignored when blitting to an 8 bit Surface.
special_flags new in pygame 1.8.
For a surface with colorkey or blanket alpha, a blit to self may give slightly different colors than a non self-blit.
ピクセル形式を変更してSurfaceのコピーを新規に作成します。 既存のSurfaceを引数として設定することで、新規作成されるSurfaceのピクセル形式を決定することができます。それ以外にも、 pygame.Surfaceで新規にSurfaceを作成する時と同じように、ビット深度やflags引数、maskflags引数を使用することによってピクセル形式を設定できます。
何も引数を定しなかった場合は、SurfaceはディスプレイのSurfaceと同じピクセル形式になります。この方法を行うと、常に使用ディスプレイ環境での画像描写に最も高速化された形式となります。画像描写処理を行う前には、Surface.convert()命令でピクセル形式を最適な状態に変更するとよいでしょう。
ピクセル変換処理を行ったSurfaceは、ピクセルの透明度が0の状態です。変換前のSurfaceにピクセルの透明度が設定されていた場合、その透明度は消去されます。ピクセルの透明度を保持したままの変換や、変換時にピクセルの透明度も設定する場合は Surface.convert_alpha を参照してください。
Creates a new copy of the Surface with the pixel format changed. The new pixel format can be determined from another existing Surface. Otherwise depth, flags, and masks arguments can be used, similar to the pygame.Surface - pygame object for representing images call.
If no arguments are passed the new Surface will have the same pixel format as the display Surface. This is always the fastest format for blitting. It is a good idea to convert all Surfaces before they are blitted many times.
The converted Surface will have no pixel alphas. They will be stripped if the original had them. See Surface.convert_alpha - change the pixel format of an image including per pixel alphas for preserving or creating per-pixel alphas.
任意のピクセル透明度でSurfaceのコピーを新規に作成します。これによって作成されたSurfaceは、設定されたピクセル透明度で最も早くコピー描写ができる形式のものになります。引数に既存Surfaceを設定しなかった場合、作成されるSurfaceは現在のディスプレイ環境でのコピー描写に最適化された形式のものとなります。
Surface.convert 命令とは違い、作成された画像のピクセル形式は元画像と完全に同じものにはなりません。しかし、それは透明度を考慮したうえで高速なコピー描写用に最適化されたものとなっています。
※原文では「任意のピクセル形式でSurfaceのコピーを新規に作成します（Creates a new copy of the surface with the desired pixel format）」と書かれていますが、誤りの可能性があるので「ピクセル形式（pixel format）」を「ピクセル透明度（pixel alpha）」に読み替えています。
Creates a new copy of the surface with the desired pixel format. The new surface will be in a format suited for quick blitting to the given format with per pixel alpha. If no surface is given, the new surface will be optimized for blitting to the current display.
Unlike the Surface.convert - change the pixel format of an image method, the pixel format for the new image will not be exactly the same as the requested source, but it will be optimized for fast alpha blitting to the destination.
Surfaceのコピーを新規に作成します。これによって作成されたSurfaceでは、ピクセル形式、カラーパレット、透明度などの設定はコピー元のSurfaceと全く同じものとなります。
Makes a duplicate copy of a Surface. The new Surface will have the same pixel formats, color palettes, and transparency settings as the original.
Surfaceを一色で塗りつぶします。rect引数を設定しなかった場合はSurface全体が塗りつぶされます。rect引数を設定すると塗りつぶす部分を特定の範囲のみに制限することができます。また、この塗りつぶし処理が適用されるのは描写可能領域内に限定されます。
color引数には(赤,緑,青)形式の値、(赤,緑,青,透明度)形式の値、 (赤,緑,青,透明度)形式の値と紐付けされたカラー定数などが設定できます。(赤,緑,青,透明度)形式で設定した場合でも、Surfaceがピクセル単位の透過に対応していないと透明度は無視されてしまいます。 (Surfaceをピクセル単位の透過に対応させるにはSRCALPHAフラグで設定します)
追加で設定できるspecial_flags引数は、pygameのver 1.8.0では BLEND_ADD, BLEND_SUB, BLEND_MULT, BLEND_MIN, BLEND_MAXが追加され、ver1.8.1ではBLEND_RGBA_ADD, BLEND_RGBA_SUB, BLEND_RGBA_MULT, BLEND_RGBA_MIN, BLEND_RGBA_MAX BLEND_RGB_ADD, BLEND_RGB_SUB, BLEND_RGB_MULT, BLEND_RGB_MIN, BLEND_RGB_MAXが追加され、将来的には他にも様々なspecial_flags引数を追加する予定です。
このの処理では、塗りつぶされる範囲がrect値の戻り値として返されます。
Fill the Surface with a solid color. If no rect argument is given the entire Surface will be filled. The rect argument will limit the fill to a specific area. The fill will also be contained by the Surface clip area.
The color argument can be either a RGB sequence, a RGBA sequence or a mapped color index. If using RGBA, the Alpha (A part of RGBA) is ignored unless the surface uses per pixel alpha (Surface has the SRCALPHA flag).
An optional special_flags is for passing in new in 1.8.0: BLEND_ADD, BLEND_SUB, BLEND_MULT, BLEND_MIN, BLEND_MAX new in 1.8.1: BLEND_RGBA_ADD, BLEND_RGBA_SUB, BLEND_RGBA_MULT, BLEND_RGBA_MIN, BLEND_RGBA_MAX BLEND_RGB_ADD, BLEND_RGB_SUB, BLEND_RGB_MULT, BLEND_RGB_MIN, BLEND_RGB_MAX With other special blitting flags perhaps added in the future.
This will return the affected Surface area.
Surface上に描写された画像をdx引数で指定したピクセル分右へ、dy引数で指定したピクセル分下へ移動させます。dxとdyそれぞれマイナスの値を指定すれば、左方向への移動や上方向への移動もできます。 Surface上の画像が描写されていない範囲については、元のピクセル位置情報がそのまま保持されます。この命令で移動できるのは描写可能領域内に限定されます。dxとdyの設定で画像位置がSurfaceの範囲からはみ出してしまっても特に問題はありません。
Move the image by dx pixels right and dy pixels down. dx and dy may be negative for left and up scrolls respectively. Areas of the surface that are not overwritten retain their original pixel values. Scrolling is contained by the Surface clip area. It is safe to have dx and dy values that exceed the surface size.
Surfaceの透過色を設定します。 設定したSurfaceをコピー描写する時、ここで設定した色と同じ色のピクセルは透明になります。透明色は(赤,緑,青)形式の値や、カラー定数で設定します。None値を引数に指定すると、設定されている透過色が解除されます。
Surfaceがピクセル単位の透過に対応していないと透明色は無視されてしまいます。透明色はSurface全体の透明度と組み合わせることができます。
追加で指定できるflags引数でpygame.RLEACCELの設定を行うことができ、それほど速くないディスプレイ環境でもより良いパフォーマンスで描写処理を行うことができます。 An RLEACCEL Surfaceでは画像編集処理を行うのは遅いですが、画像のコピー処理は早くなります。
Set the current color key for the Surface. When blitting this Surface onto a destination, and pixels that have the same color as the colorkey will be transparent. The color can be an RGB color or a mapped color integer. If None is passed, the colorkey will be unset.
The colorkey will be ignored if the Surface is formatted to use per pixel alpha values. The colorkey can be mixed with the full Surface alpha value.
The optional flags argument can be set to pygame.RLEACCEL to provide better performance on non accelerated displays. An RLEACCEL Surface will be slower to modify, but quicker to blit as a source.
Surfaceの透過色を取得します。透過色が設定されていなければNone値が返されます。
Return the current colorkey value for the Surface. If the colorkey is not set then None is returned.
Surfaceの透明度を設定します。Surfaceをコピー描写する場合、各ピクセルはこの命令で設定した分だけ透明に描写されます。透明度は0から255までの数字で設定でき、0の時は完全に透明状態となり、255の時は完全に不透明状態となります。透明度の引数としてNone値を設定すると、Surfaceの透過は使用できなくなります。
この透過はピクセル単位の透過とは違うものです。 Surfaceがピクセル単位の透過を使用できる形式の場合、この命令で設定された透明度は無視されます。ですがこの命令でNone値を設定した場合は、ピクセル単位の透明度も無効となります。
追加で指定できるflags引数でpygame.RLEACCELの設定を行うことができ、それほど速くないディスプレイ環境でもより良いパフォーマンスで描写処理を行うことができます。 RLEACCELの設定されたSurfaceでは画像編集処理を行うのは遅いですが、画像コピー処理は早くなります。
Set the current alpha value for the Surface. When blitting this Surface onto a destination, the pixels will be drawn slightly transparent. The alpha value is an integer from 0 to 255, 0 is fully transparent and 255 is fully opaque. If None is passed for the alpha value, then the Surface alpha will be disabled.
This value is different than the per pixel Surface alpha. If the Surface format contains per pixel alphas, then this alpha value will be ignored. If the Surface contains per pixel alphas, setting the alpha value to None will disable the per pixel transparency.
The optional flags argument can be set to pygame.RLEACCEL to provide better performance on non accelerated displays. An RLEACCEL Surface will be slower to modify, but quicker to blit as a source.
Surfaceの透明度を取得します。透明度が設定されていなければNone値が返されます。
Return the current alpha value for the Surface. If the alpha value is not set then None is returned.
編集のためにSurfaceのピクセルデータをロックします。様々な描写処理が絶えず行われているSurface上では、ピクセルデータはすぐに消えてしまうビデオメモリーに保存されたり、すぐには判別できないような形式で保存されていたりします。 Surfaceをロックすることで、ピクセルのメモリーは通常のソフトウェアでも編集ができるようになります。ピクセルの値の読み込みや書き込みを行う処理を記述する場合はSurfaceのロックを行う必要があります。
Surfaceは必要な時以外はロックしたままにするべきではありません。Pygameではロック状態のSurfaceは表示や制御ができない場合が多いです。
全てのSurfaceでロック処理が必要なわけではありません。 The Surface.mustlock命令を使用するとそのSurfaceはロックが必要かどうかを確認することができます。ロックが必要ではないSurfaceの場合は、ロックの有無によって パフォーマンスに違いは出ません。
pygameの全ての命令では、Surfaceデータのロックやロック解除は必要な時に自動的に行われます。 Surfaceのロックとロック解除を大量に繰り返し実行するようなプログラムを記述する場合、lock命令とunlock命令の間の処理はインテンドで字下げしてブロックを分けると分かりやすいでしょう。
ロック処理とロック解除処理は、複数回実行して入れ子状態になっても問題ありません。ロック処理を複数回実行している時は、ロックした回数分ロック解除処理を行うことでSurfaceはロック解除状態になります。
Lock the pixel data of a Surface for access. On accelerated Surfaces, the pixel data may be stored in volatile video memory or nonlinear compressed forms. When a Surface is locked the pixel memory becomes available to access by regular software. Code that reads or writes pixel values will need the Surface to be locked.
Surfaces should not remain locked for more than necessary. A locked Surface can often not be displayed or managed by Pygame.
Not all Surfaces require locking. The Surface.mustlock - test if the Surface requires locking method can determine if it is actually required. There is no performance penalty for locking and unlocking a Surface that does not need it.
All pygame functions will automatically lock and unlock the Surface data as needed. If a section of code is going to make calls that will repeatedly lock and unlock the Surface many times, it can be helpful to wrap the block inside a lock and unlock pair.
It is safe to nest locking and unlocking calls. The surface will only be unlocked after the final lock is released.
ロックされているSurfaceのピクセルデータのロックを解除します。ロック解除されたSurfaceはPygameでの描写や制御ができるようになります。ロックの詳細についてはSurface.lockの項目を参照してください。
pygameの全ての命令では、Surfaceデータのロックやロック解除は必要な時に自動的に行われます。 Surfaceのロックとロック解除を大量に繰り返し実行するようなプログラムを記述する場合、lock命令とunlock命令の間の処理はインテンドで字下げしてブロックを分けると分かりやすいでしょう。
ロック処理とロック解除処理は、複数回実行して入れ子状態になっても問題ありません。ロック処理を複数回実行している時は、ロックした回数分ロック解除処理を行うことでSurfaceはロック解除状態になります。
Unlock the Surface pixel data after it has been locked. The unlocked Surface can once again be drawn and managed by Pygame. See the Surface.lock - lock the Surface memory for pixel access documentation for more details.
All pygame functions will automatically lock and unlock the Surface data as needed. If a section of code is going to make calls that will repeatedly lock and unlock the Surface many times, it can be helpful to wrap the block inside a lock and unlock pair.
It is safe to nest locking and unlocking calls. The surface will only be unlocked after the final lock is released.
このSurfaceのピクセルデータ編集時にロック処理が必要な場合は戻り値 True を返します。通常、純粋なソフトウェアSurfaceはロックを行う必要がありません。必要な時には全てのSurfaceをまとめてロックしてしまった方が安全かつ速いため、この命令を使用することはあまりないでしょう。
pygameの全ての命令では、Surfaceデータのロックやロック解除は必要な時に自動的に行われます。 Surfaceのロックとロック解除を大量に繰り返し実行するようなプログラムを記述する場合、lock命令とunlock命令の間の処理はインテンドで字下げしてブロックを分けると分かりやすいでしょう。
Returns True if the Surface is required to be locked to access pixel data. Usually pure software Surfaces do not require locking. This method is rarely needed, since it is safe and quickest to just lock all Surfaces as needed.
All pygame functions will automatically lock and unlock the Surface data as needed. If a section of code is going to make calls that will repeatedly lock and unlock the Surface many times, it can be helpful to wrap the block inside a lock and unlock pair.
Surfaceがロックされている時は戻り値 True を返します。最後に行われたのがロック処理なのかロック解除処理なのかを判別する命令のため、Surface がロックされている回数は考慮されません。
Returns True when the Surface is locked. It doesn't matter how many times the Surface is locked.
現在Surfaceに対して適用されている全てのロック情報を戻り値として返します。
Returns the currently existing locks for the Surface.
指定座標にあるピクセルの色情報をRGBA形式の戻り値として返します。Surfaceがピクセル単位の透過に対応していない場合は、透明度は常に255(不透明)となります。引数として渡したピクセルの座標がSurfaceの範囲外だった場合は、IndexErrorの例外が発生します。
一般的にゲームやリアルタイムシミュレーションでは、ピクセル一点一点のデータを取得したり設定したりするような処理は遅すぎて使い物になりません。blit命令や,fill命令、draw命令のような多くのピクセルをまとめて操作する処理を行う方がよいでしょう。もしくはsurfarrayクラスやPixelArrayクラスを使用するのもいいかもしれません。
この命令を使用すると、Surfaceは必要に応じて一時的にロックやロック解除されます。
Pygameのver1.9.0からはタプル型の値ではなくColor型の値で戻り値が返されるようになりました。もしColor型ではなくタプル型で戻り値が欲しい場合はtuple(surf.get_at((x,y)))と記述してください。どちらの処理でもあまり違いはありませんが、色をdict型の情報として使用したい場合に関係してきます。
Return a copy of the RGBA Color value at the given pixel. If the Surface has no per pixel alpha, then the alpha value will always be 255 (opaque). If the pixel position is outside the area of the Surface an IndexError exception will be raised.
Getting and setting pixels one at a time is generally too slow to be used in a game or realtime situation. It is better to use methods which operate on many pixels at a time like with the blit, fill and draw methods - or by using surfarray/PixelArray.
This function will temporarily lock and unlock the Surface as needed.
Returning a Color instead of tuple, New in pygame 1.9.0. Use tuple(surf.get_at((x,y))) if you want a tuple, and not a Color. This should only matter if you want to use the color as a key in a dict.
RGBA形式の値かカラー定数を使用して指定座標にあるピクセルの色情報を設定します。Surfaceがピクセル単位の透過に対応していない場合は、透明度については無視されます。 引数として渡したピクセルの座標がSurfaceそのもの、もしくはSurface描写可能範囲の範囲外だった場合は何も起こりません。
一般的にゲームやリアルタイムシミュレーションでは、ピクセル一点一点のデータを取得したり設定したりするような処理は遅すぎて使い物になりません。
この命令を使用すると、Surfaceは必要に応じて一時的にロックやロック解除されます。
Set the RGBA or mapped integer color value for a single pixel. If the Surface does not have per pixel alphas, the alpha value is ignored. Settting pixels outside the Surface area or outside the Surface clipping will have no effect.
Getting and setting pixels one at a time is generally too slow to be used in a game or realtime situation.
This function will temporarily lock and unlock the Surface as needed.
最大で256個で構成される色情報のリスト型値を戻り値として返します。この戻り値は8ビットのSurfaceにて使用される色を順番に並べてリスト化したものです。ここで取得するカラーパレットは元パレットのコピーのため、変更してもSurfaceに影響はありません。
pygameのver1.9.0からは、戻り値がタプル型ではなColor型となりました。
Return a list of up to 256 color elements that represent the indexed colors used in an 8bit Surface. The returned list is a copy of the palette, and changes will have no effect on the Surface.
Returning a list of Color(with length 3) instances instead of tuples, New in pygame 1.9.0
Surfaceのカラーパレット上の指定した位置にある色情報を戻り値として返します。位置は0から255の間の値を指定してください。
pygameのver1.9.0からは、戻り値がタプル型ではなColor型となりました。
Returns the red, green, and blue color values for a single index in a Surface palette. The index should be a value from 0 to 255.
Returning Color(with length 3) instance instead of a tuple, New in pygame 1.9.0
8bit Surfaceの全てのパレットを設定します。 現在設定されているカラーパレットは失われ、この命令で設定したものが新たに適用されます。256個の色情報を全て引数として渡す必要はありませんが、数が足りない場合は前から数えて順番に色情報が設定されます。
Surfaceのピクセルが8ビット以上の場合この機能は適用されません。
Set the full palette for an 8bit Surface. This will replace the colors in the existing palette. A partial palette can be passed and only the first colors in the original palette will be changed.
This function has no effect on a Surface with more than 8bits per pixel.
Surfaceのカラーパレット上の指定した位置に色情報を設定します。
Surfaceのピクセルが8ビット以上の場合この機能は適用されません。
Set the palette value for a single entry in a Surface palette. The index should be a value from 0 to 255.
This function has no effect on a Surface with more than 8bits per pixel.
(赤,緑,青,透明度)形式の色情報を、その色情報に紐づけされているカラー定数へ変換します。(赤,緑,青,透明度)形式で細かい色情報を指定しても、それがSurfaceのビット深度を超える色情報だった場合は、Surfaceの深度に合わせた最も近いカラー定数が取得されます。Pygame内部の処理でカラー定数が使われることはあまりありませんが、Surfaceや色情報の設定が必要な多くの命令ではカラー定数を引数として指定することができます。
色やピクセル形式についてのさらに詳細な情報が知りたい場合は、Surfaceクラスの項目を参照してください。
Convert an RGBA color into the mapped integer value for this Surface. The returned integer will contain no more bits than the bit depth of the Surface. Mapped color values are not often used inside Pygame, but can be passed to most functions that require a Surface and a color.
See the Surface object documentation for more information about colors and pixel formats.
カラー定数を、(赤,緑,青,透明度)形式の色情報に変換します。Pygame内部の処理でカラー定数が使われることはあまりありませんが、Surfaceや色情報の設定が必要な多くの命令ではカラー定数を引数として指定することができます。
色やピクセル形式についてのさらに詳細な情報が知りたい場合は、Surfaceクラスの項目を参照してください。
Convert an mapped integer color into the RGB color components for this Surface. Mapped color values are not often used inside Pygame, but can be passed to most functions that require a Surface and a color.
See the Surface object documentation for more information about colors and pixel formats.
全てのSurfaceには描写可能領域が存在します。描写可能領域とはSurface上にてピクセルの編集をすることができる矩形範囲のことです。引数として Noneが設定された場合はSurface全体が編集可能な範囲となります。
この描写可能領域の大きさは常にSurface自身の大きさによって制限されます。描写可能領域が大きすぎると、Surfaceの範囲内に収まるよう縮小されます。
Each Surface has an active clipping area. This is a rectangle that represents the only pixels on the Surface that can be modified. If None is passed for the rectangle the full Surface will be available for changes.
The clipping area is always restricted to the area of the Surface itself. If the clip rectangle is too large it will be shrunk to fit inside the Surface.
描写可能領域を取得します。Surfaceは常に有効な矩形範囲を返し、画像の範囲外が含まれることは決してありません。Surfaceに描写可能領域が設定されていない場合は、Surface全体の矩形範囲を戻り値として返します。
Return a rectangle of the current clipping area. The Surface will always return a valid rectangle that will never be outside the bounds of the image. If the Surface has had None set for the clipping area, the Surface will return a rectangle with the full area of the Surface.
オリジナルのSurfaceとピクセル情報を共有するSurfaceを戻り値として返します。新規に作成されたSurfaceは、オリジナルSurfaceの分身と見なされます。どちらかのSurafaceのピクセルを編集すると、その編集はもう一方のSurafaceにも影響を与えます。描写可能領域や透過色のようなSurfaceの情報は、共有されずにそれぞれが個別に情報を設定できます。
新規作成されたSurfaceは元Surfaceからカラーパレット、透過色、透過設定などの情報を引き継ぎます。
複数のsubsurfaceを作成することや、subsurfaceのsubsurfaceを作成することも可能です。display.set_mode命令でHWSURFACE引数を設定するとハードウェア側で高速描写を行う状態に設定にされますが、その設定を行っていなければsubsurfaceを画面に表示することも可能です。
subsurfaceについてさらに知りたいのなら、Surface.get_offsetや Surface.get_parent の項目を参照してください。
Returns a new Surface that shares its pixels with its new parent. The new Surface is considered a child of the original. Modifications to either Surface pixels will effect each other. Surface information like clipping area and color keys are unique to each Surface.
The new Surface will inherit the palette, color key, and alpha settings from its parent.
It is possible to have any number of subsurfaces and subsubsurfaces on the parent. It is also possible to subsurface the display Surface if the display mode is not hardware accelerated.
See the Surface.get_offset - find the position of a child subsurface inside a parent, Surface.get_parent - find the parent of a subsurface to learn more about the state of a subsurface.
subsurfaceのオリジナルSurfaceを戻り値として返します。この処理を実行したのがsubsurfaceでない場合は、None値が戻り値として返されます。
Returns the parent Surface of a subsurface. If this is not a subsurface then None will be returned.
subsurfaceの大元となるオリジナルSurfaceを戻り値として返します。この処理を実行したのがsubsurfaceでない場合、そのSurface自身が戻り値として返されます。
Returns the parent Surface of a subsurface. If this is not a subsurface then this surface will be returned.
のsubsurfaceがオリジナルSurface内のどの位置を参照しているか調べます。この処理を実行したのがsubsurfaceでない場合、(0,0)の位置情報が戻り値として返されます。
Get the offset position of a child subsurface inside of a parent. If the Surface is not a subsurface this will return (0, 0).
subsurfaceが大元となるオリジナルSurface内のどの位置を参照しているか調べます。この処理を実行したのがsubsurfaceでない場合、(0,0)の位置情報が戻り値として返されます。
Get the offset position of a child subsurface inside of its top level parent Surface. If the Surface is not a subsurface this will return (0, 0).
Surfaceのピクセル単位での幅と高さを戻り値として返します。
Return the width and height of the Surface in pixels.
Surfaceのピクセル単位での幅を戻り値として返します。
Return the width of the Surface in pixels.
Surfaceのピクセル単位での高さを戻り値として返します。
Return the height of the Surface in pixels.
Surfaceが存在する範囲全体をRect値の戻り値として返します。このRect型範囲は常に(0,0)座標を起点とし、幅と高さはそれぞれSurface全体に表示される画像と同じものとなります。
この命令ではキーワードとその値を引数として設定することができます。このキーワード値がRect型クラスの該当する値に設定されたうえで、戻り値が返ります。例えば、'get_rect(center=(100,100))'という引数を設定した場合、Surfaceの中心が(100,100)座標となった状態のRect値が取得されます。
Returns a new rectangle covering the entire surface. This rectangle will always start at 0, 0 with a width. and height the same size as the image.
You can pass keyword argument values to this function. These named values will be applied to the attributes of the Rect before it is returned. An example would be 'mysurf.get_rect(center=(100,100))' to create a rectangle for the Surface centered at a given position.
ピクセルの描写に使われるビット数を戻り値として返します。この値はピクセル描写に使用されるバイト数を正確に表せるわけではありません。例えば、15bitのSurfaceであっても2バイトが必要になります。
Returns the number of bits used to represent each pixel. This value may not exactly fill the number of bytes used per pixel. For example a 15 bit Surface still requires a full 2 bytes.
ピクセル一個あたりの使用するバイト数を戻り値として返します。
Return the number of bytes used per pixel.
現在Surfaceに設定されている機能一覧を戻り値として返します。Each feature is a bit in the flags bitmask.よく使用されるflagにはHWSURFACE、RLEACCEL、 SRCALPHA、SRCCOLORKEYなどがあります。
以下により詳細なfalg一覧を示します。 全てのflag一覧はSDL_video.hファイルから参照することが可能です。
SWSURFACE 0x00000000 # Surfaceはソフトウェア側のメモリーに記録されます。 HWSURFACE 0x00000001 # Surfaceはハードウェア側のメモリーに記録されます。 ASYNCBLIT 0x00000004 # 可能な場合には非同期でのコピー描写処理を行います
以下は pygame.display.set_mode命令で設定できます。
ANYFORMAT 0x10000000 # 全ての解像度とピクセルフォーマットを使用可能にします。
HWPALETTE 0x20000000 # Surfaceは専用のカラーパレットを持つことができます。
DOUBLEBUF 0x40000000 # ダブルバッファリングモードを使用可能にします。
FULLSCREEN 0x80000000 # Surfaceをフルスクリーンモードにします。
OPENGL 0x00000002 # OpenGLでの画像処理を使用可能にします。
OPENGLBLIT 0x0000000A # OpenGLでの画像処理を使用可能にし、コピー描写処理にて使用します。このflagは現在廃止されています。
RESIZABLE 0x00000010 # ウィンドウの大きさを変えることができるモードです。
NOFRAME 0x00000020 # ウィンドウのタイトルバーと枠がなくなります。
以下はpygameの内部処理で自動的に設定されます。 (ユーザーが設定することはできません。)
HWACCEL 0x00000100 # ハードウェア側の高速な処理でコピー描写を行います。 SRCCOLORKEY 0x00001000 # コピー元の透過色を適用してコピー描写を行います。 RLEACCELOK 0x00002000 # Private flag RLEACCEL 0x00004000 # Surfaceはランレングス形式で圧縮されます。 SRCALPHA 0x00010000 # コピー元の透過度を適用してコピー描写を行います。 PREALLOC 0x01000000 # Surfaceはあらかじめ割り当てられたメモリーを使用します。
Returns a set of current Surface features. Each feature is a bit in the flags bitmask. Typical flags are HWSURFACE, RLEACCEL, SRCALPHA, and SRCCOLORKEY.
Here is a more complete list of flags. A full list can be found in SDL_video.h
SWSURFACE 0x00000000 # Surface is in system memory HWSURFACE 0x00000001 # Surface is in video memory ASYNCBLIT 0x00000004 # Use asynchronous blits if possible
Available for pygame.display.set_mode - initialize a window or screen for display
ANYFORMAT 0x10000000 # Allow any video depth/pixel-format
HWPALETTE 0x20000000 # Surface has exclusive palette
DOUBLEBUF 0x40000000 # Set up double-buffered video mode
FULLSCREEN 0x80000000 # Surface is a full screen display
OPENGL 0x00000002 # Create an OpenGL rendering context
OPENGLBLIT 0x0000000A # Create an OpenGL rendering context
# and use it for blitting. Obsolete.
RESIZABLE 0x00000010 # This video mode may be resized
NOFRAME 0x00000020 # No window caption or edge frame
Used internally (read-only)
HWACCEL 0x00000100 # Blit uses hardware acceleration SRCCOLORKEY 0x00001000 # Blit uses a source color key RLEACCELOK 0x00002000 # Private flag RLEACCEL 0x00004000 # Surface is RLE encoded SRCALPHA 0x00010000 # Blit uses source alpha blending PREALLOC 0x01000000 # Surface uses preallocated memory
Surfaceのピクセル1行ごとのバイト数を戻り値として返します。ハードウェア側のメモリに保存されたSurfaceは、ちゃんと1行ごとにまとめられていない場合もあるので気をつけてください。また Subsurfaceは実際よりも横幅が大きくなってしまいます。
ここで取得できる値は、通常のPygame処理であれば特に使う機会はないでしょう。
Return the number of bytes separating each row in the Surface. Surfaces in video memory are not always linearly packed. Subsurfaces will also have a larger pitch than their real width.
This value is not needed for normal Pygame usage.
カラー定数を(赤,緑,青,透明度)の四つの情報に分けるために使用されるビットマスクを、戻り値として返します。
ここで取得できる値は、通常のPygame処理であれば特に使う機会はないでしょう。
Returns the bitmasks used to isolate each color in a mapped integer.
This value is not needed for normal Pygame usage.
ここで設定できる値は、通常のPygame処理であれば特に使う機会はないでしょう。この命令はpygameのver 1.8.1で新たに実装されました。
This is not needed for normal Pygame usage. New in pygame 1.8.1
タプル型の(赤,緑,青,透明度)形式色情報と整数型のカラー定数を相互に変換する際に使われるビットシフトを戻り値として返します。
ここで取得できる値は、通常のPygame処理であれば特に使う機会はないでしょう。
Returns the pixel shifts need to convert between each color and a mapped integer.
This value is not needed for normal Pygame usage.
ここで設定できる値は、通常のPygame処理であれば特に使う機会はないでしょう。この命令はpygameのver 1.8.1で新たに実装されました。
※原文では「Surface.get_shifts((r,g,b,a))」となっていますが、誤りの可能性があるため「Surface.set_shifts((r,g,b,a))」と読み替えて訳しています。
This is not needed for normal Pygame usage. New in pygame 1.8.1
カラー定数への変換時に、(赤,緑,青,透明度)形式色情報の各値から削除される最下位ビットの値を戻り値として返します。
ここで取得できる値は、通常のPygame処理であれば特に使う機会はないでしょう。
Return the least significant number of bits stripped from each color in a mapped integer.
This value is not needed for normal Pygame usage.
Surface内で、透明度が1以上の最小範囲をRect型の戻り値として返します。
この処理を行うときは、必要に応じて一時的にSurfaceのロックやロック解除が行われます。
この命令はpygameのver 1.8.1で新たに実装されました。
Returns the smallest rectangular region that contains all the pixels in the surface that have an alpha value greater than or equal to the minimum alpha value.
This function will temporarily lock and unlock the Surface as needed.
New in pygame 1.8.
Surfaceのピクセル編集用に確保されるバッファ領域を戻り値として返します。このバッファ領域は、ピクセルを直接編集したり操作するのに使用することができます。
この処理が行われる時は、必然的にSurfaceはロックされることになります。というのも、このロックが解除されたのを合図にバッファ領域内のデータが消去されるからです。
この命令はpygameのver 1.8で新たに実装されました。
Return a buffer object for the pixels of the Surface. The buffer can be used for direct pixel access and manipulation.
This method implicitly locks the Surface. The lock will be released, once the returned BufferProxy object is deleted.
New in pygame 1.8.