TableOfContents

Surface

pygame里的Surface是用来表示图像的对象。Surface有一定的大小和像素格式。如果是8bit像素格式的Surface，它还会用一个调色板映射到24比特颜色。

调用pygame.Surface可以创建表示图像的新对象。Surface会整个全是黑的。唯一需要指定的参数是大小。如果不指定其他参数，Surface的像素格式会与display Surface的像素格式尽量一致。

像素格式可以通过指定像素深度或者已有的Surface来控制。flag标志位参数是其他一些Surface选项的集合，你可以指定如下的标志

• HWSURFACE, 在视频内存中创建图像
• SRCALPHA, 像素格式中会包含一个alpha通道

这些参数都仅仅是一个请求，在实际中可能并不能实现。

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 acceleratio

• when possible, otherwise 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.

Each 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.

1. Surface.blit

• draw one image onto another Surface.blit(source, dest, area=None, special_flags = 0): return Rect 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 BLEND_ADD, BLEND_SUB, BLEND_MULT, BLEND_MIN, BLEND_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.

2. Surface.convert

• change the pixel format of an image Surface.convert(Surface): return Surface Surface.convert(depth, flags=0): return Surface Surface.convert(masks, flags=0): return Surface Surface.convert(): return Surface 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.

3. Surface.copy

• create a new copy of a Surface Surface.copy(): return 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.

4. Surface.fill

• fill Surface with a solid color Surface.fill(color, rect=None): return 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 an RGB sequence or a mapped color index. This will return the affected Surface area.

5. Surface.set_colorkey

• Set the transparent colorkey Surface.set_colorkey(Color, flags=0): return None Surface.set_colorkey(None): return None 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.

6. Surface.get_at

• get the color value at a single pixel Surface.get_at((x, y)): return Color

  Return 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. This function will temporarily lock and unlock the Surface as needed.

7. Surface.set_at

• set the color value for a single pixel Surface.set_at((x, y), Color): return None 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.

8. Surface.set_clip

• set the current clipping area of the Surface Surface.set_clip(rect): return None Surface.set_clip(None): return None 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.

9. Surface.get_clip

• get the current clipping are of the Surface Surface.get_clip(): return Rect 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.

10. Surface.get_size

• get the dimensions of the Surface Surface.get_size(): return (width, height) Return the width and height of the Surface in pixels.

11. Surface.get_width

• get the width of the Surface Surface.get_width(): return width Return the width of the Surface in pixels.

12. Surface.get_height

• get the height of the Surface Surface.get_height(): return height Return the height of the Surface in pixels.

pygame.image

image模块包含读取和保存图片的函数，也包括把Surfaces变成其它包可以使用的格式的函数。

注意，没有Image类。图片是作为Surface对象读入的。Surface类允许画线、设置像素、捕捉区域等操作。

image模块是pygame必须的一个模块，但是对于扩展部分的文件格式的支持是可选的。默认情况下，它只支持不压缩的BMP图像。当编译成完整的图像格式支持后，pygame.image.load函数可以支持如下类型：

• JPG
• PNG
• GIF (non animated)
• BMP
• PCX
• TGA (uncompressed)
• TIF
• LBM (and PBM)
• PBM (and PGM, PPM)
• XPM

保存图像只支持有限的格式。你可以保存为下列格式：

• BMP
• TGA
• PNG
• JPEG

存为PNG, JPEG格式在pygame 1.8中支持。

1. pygame.image.load

从文件中读取一个图像。

pygame.image.load(filename): return Surface

pygame.image.load(fileobj, namehint=""): return Surface

从文件中读取一个图片。你可以传过去一个文件名，或者一个Python的文件对象。

pygame会自动确定文件的类型（比如GIF或者BMP），并创建一个新的Surface对象。某些情况下，需要知道文件的扩展名（比如GIF图像文件以.gif扩展名命名）。如果传递一个文件对象，你可能要把原来的文件名作为namehint参数传过去。

返回的Surface对象包含和文件中相同的颜色格式、透明色和alpha透明。你常常要调用Surface.convert函数来创建一个拷贝，使得图像在屏幕上画得更快。

对于alpha透明，比如.png图像，在读入后使用convert_alpha()方法来保留每个像素透明信息。

pygame并不是支持所有的图像格式。但是至少它支持不压缩的BMP格式。如果pygame.image.get_extended返回True，则你可以使用大部分的图像格式（包括png、jpg和gif）。

你应该使用os.path.join来保证兼容性。比如asurf = pygame.image.load(os.path.join('data', 'bla.png'))

2. pygame.image.save

把图像保存到文件中

pygame.image.save(Surface, filename): return None

这个函数可以把Surface保存为BMP、TGA、PNG或者JPEG图像文件。如果文件扩展名不认识，默认保存为TGA格式。TGA和BMP格式都是非压缩的文件。

保存为PNG、JPEG格式在pygame1.8种支持。

3. pygame.image.tostring

把图像转换为字符串。

pygame.image.tostring(Surface, format, flipped=False): return string

创建一个字符串，这个字符串可以在其它包中用fromstring方法转换回图像。某些Python图像包希望使用自底向上的图像格式（比如PyOpenGL）。如果你给flipped传送True，则字符串中表示的图像会上下翻转。

format参数可以是以下这些值。注意并不是只有8位的Surface才能使用P格式。其它的格式也能被所有Surface使用。同时也要注意，其它的图像包支持比pygame更多的图像格式。

• P, 8bit palettized Surfaces
• RGB, 24bit image
• RGBX, 32bit image with unused space
• RGBA, 32bit image with an alpha channel
• ARGB, 32bit image with alpha channel first

4. pygame.image.fromstring

从字符串创建一个新的Surface。

pygame.image.fromstring(string, size, format, flipped=False): return Surface

这个函数和pygame.image.tostring有类似的参数。size参数包括一对数字用来指定图像的高度和宽度。一旦新的Surface创建后，你就可以释放你的字符串了。

根据图像的大小和格式计算出来的大小必须和传过来的字符串大小一样。 否则，会导致一个异常。

参看pygame.image.frombuffer方法来更快的创建一个图像的方法。

draw

Draw several simple shapes to a Surface. These functions will work for rendering to any format of Surface. Rendering to hardware Surfaces will be slower than regular software Surfaces.

Most of the functions take a width argument to represent the size of stroke around the edge of the shape. If a width of 0 is passed the function will actually solid fill the entire shape.

All the drawing functions respect the clip area for the Surface, and will be constrained to that area. The functions return a rectangle representing the bounding area of changed pixels.

Most of the arguments accept a color argument that is an RGB triplet. These can also accept an RGBA quadruplet. The alpha value will be written directly into the Surface if it contains pixel alphas, but the draw function will not draw transparently. The color argument can also be an integer pixel value that is already mapped to the Surface's pixel format.

These functions must temporarily lock the Surface they are operating on. Many sequential drawing calls can be sped up by locking and unlocking the Surface object around the draw calls.

1. pygame.draw.rect

• draw a rectangle shape pygame.draw.rect(Surface, color, Rect, width=0): return Rect Draws a rectangular shape on the Surface. The given Rect is the area of the rectangle. The width argument is the thickness to draw the outer edge. If width is zero then the rectangle will be filled. Keep in mind the Surface.fill - fill Surface with a solid color method works just as well for drawing filled rectangles. In fact the Surface.fill - fill Surface with a solid color can be hardware accelerated on some platforms with both software and hardware display modes.

2. pygame.draw.polygon

• draw a shape with any number of sides pygame.draw.polygon(Surface, color, pointlist, width=0): return Rect Draws a polygonal shape on the Surface. The pointlist argument is the vertices of the polygon. The width argument is the thickness to draw the outer edge. If width is zero then the polygon will be filled. For aapolygon, use aalines with the 'closed' parameter.

3. pygame.draw.circle

• draw a circle around a point pygame.draw.circle(Surface, color, pos, radius, width=0): return Rect Draws a circular shape on the Surface. The pos argument is the center of the circle, and radius is the size. The width argument is the thickness to draw the outer edge. If width is zero then the circle will be filled.

4. pygame.draw.ellipse

• draw a round shape inside a rectangle pygame.draw.ellipse(Surface, color, Rect, width=0): return Rect Draws an elliptical shape on the Surface. The given rectangle is the area that the circle will fill. The width argument is the thickness to draw the outer edge. If width is zero then the ellipse will be filled.

5. pygame.draw.arc

• draw a partial section of an ellipse pygame.draw.arc(Surface, color, Rect, start_angle, stop_angle, width=1): return Rect Draws an elliptical arc on the Surface. The rect argument is the area that the ellipse will fill. The two angle arguments are the initial and final angle in radians, with the zero on the right. The width argument is the thickness to draw the outer edge.

6. pygame.draw.line

• draw a straight line segment pygame.draw.line(Surface, color, start_pos, end_pos, width=1): return Rect Draw a straight line segment on a Surface. There are no endcaps, the ends are squared off for thick lines.

7. pygame.draw.lines

• draw multiple contiguous line segments pygame.draw.lines(Surface, color, closed, pointlist, width=1): return Rect Draw a sequence of lines on a Surface. The pointlist argument is a series of points that are connected by a line. If the closed argument is true an additional line segment is drawn between the first and last points. This does not draw any endcaps or miter joints. Lines with sharp corners and wide line widths can have improper looking corners.

8. pygame.draw.aaline

• draw fine antialiased lines pygame.draw.aaline(Surface, color, startpos, endpos, blend=1): return Rect Draws an anti-aliased line on a surface. This will respect the clipping rectangle. A bounding box of the affected area is returned returned as a rectangle. If blend is true, the shades will be be blended with existing pixel shades instead of overwriting them. This function accepts floating point values for the end points.

9. pygame.draw.aalines

• pygame.draw.aalines(Surface, color, closed, pointlist, blend=1): return Rect Draws a sequence on a surface. You must pass at least two points in the sequence of points. The closed argument is a simple boolean and if true, a line will be draw between the first and last points. The boolean blend argument set to true will blend the shades with existing shades instead of overwriting them. This function accepts floating point values for the end points.

font

The font module allows for rendering TrueType fonts into a new Surface object. This module is optional and requires SDL_ttf as a dependency. You should test that pygame.font is available and initialized before attempting to use the module.

Most of the work done with fonts are done by using the actual Font objects. The module by itself only has routines to initialize the module and create Font objects with pygame.font.Font - create a new Font object from a file.

You can load fonts from the system by using the pygame.font.SysFont - create a Font object from the system fonts function. There are a few other functions to help lookup the system fonts.

Pygame comes with a builtin default font. This can always be accessed by passing None as the font name.

1. pygame.font.init

• initialize the font module pygame.font.init(): return None This method is called automatically by pygame.init - initialize all imported pygame modules. It initializes the font module. The module must be initialized before any other functions will work. It is safe to call this function more than once.

2. pygame.font.quit

• uninitialize the font module pygame.font.quit(): return None Manually uninitialize SDL_ttf's font system. This is called automatically by pygame.quit - uninitialize all pygame modules. It is safe to call this function even if font is currently not initialized.

3. pygame.font.get_init

• true if the font module is initialized pygame.font.get_init(): return bool Test if the font module is initialized or not.

4. pygame.font.get_default_font

• get the filename of the default font pygame.font.get_default_font(): return string Return the filename of the system font. This is not the full path to the file. This file can usually be found in the same directory as the font module, but it can also be bundled in separate archives.

5. pygame.font.get_fonts

• get all available fonts pygame.font.get_fonts(): return list of strings Returns a list of all the fonts available on the system. The names of the fonts will be set to lowercase with all spaces and punctuation removed. This works on most systems, but some will return an empty list if they cannot find fonts.

6. pygame.font.match_font

• find a specific font on the system pygame.font.match_font(name, bold=False, italic=False): return path Returns the full path to a font file on the system. If bold or italic are set to true, this will attempt to find the correct family of font. The font name can actually be a comma separated list of font names to try. If none of the given names are found, None is returned. Example:
  • print pygame.font.match_font('bitstreamverasans') # output is: /usr/share/fonts/truetype/ttf-bitstream-vera/Vera.ttf # (but only if you have Vera on your system)

7. pygame.font.SysFont

• create a Font object from the system fonts

  pygame.font.SysFont(name, size, bold=False, italic=False): return Font Return a new Font object that is loaded from the system fonts. The font will match the requested bold and italic flags. If a suitable system font is not found this will fallback on loading the default pygame font. The font name can be a comma separated list of font names to look for.

8. pygame.font.Font

• create a new Font object from a file pygame.font.Font(filename, size): return Font pygame.font.Font(object, size): return Font
  • Font.render - draw text on a new Surface draw text on a new Surface Font.size - determine the amount of space needed to render text determine the amount of space needed to render text Font.set_underline - control if text is rendered with an underline control if text is rendered with an underline Font.get_underline - check if text will be rendered with an underline check if text will be rendered with an underline Font.set_bold - enable fake rendering of bold text enable fake rendering of bold text Font.get_bold - check if text will be rendered bold check if text will be rendered bold Font.set_italic - enable fake rendering of italic text enable fake rendering of italic text Font.get_italic - check if the text will be rendered italic check if the text will be rendered italic Font.get_linesize - get the line space of the font text get the line space of the font text Font.get_height - get the height of the font get the height of the font Font.get_ascent - get the ascent of the font get the ascent of the font Font.get_descent - get the descent of the font get the descent of the font
  Load a new font from a given filename or a python file object. The size is the height of the font in pixels. If the filename is None the Pygame default font will be loaded. If a font cannot be loaded from the arguments given an exception will be raised. Once the font is created the size cannot be changed. Font objects are mainly used to render text into new Surface objects. The render can emulate bold or italic features, but it is better to load from a font with actual italic or bold glyphs. The rendered text can be regular strings or unicode.

8.1. Font.render

• draw text on a new Surface Font.render(text, antialias, color, background=None): return Surface This creates a new Surface with the specified text rendered on it. Pygame provides no way to directly draw text on an existing Surface: instead you must use Font.render - draw text on a new Surface to create an image (Surface) of the text, then blit this image onto another Surface. The text can only be a single line: newline characters are not rendered. The antialias argument is a boolean: if true the characters will have smooth edges. The color argument is the color of the text [e.g.: (0,0,255) for blue]. The optional background argument is a color to use for the text background. If no background is passed the area outside the text will be transparent. The Surface returned will be of the dimensions required to hold the text. (the same as those returned by Font.size()). If an empty string is passed for the text, a blank surface will be returned that is one pixel wide and the height of the font. Depending on the type of background and antialiasing used, this returns different types of Surfaces. For performance reasons, it is good to know what type of image will be used. If antialiasing is not used, the return image will always be an 8bit image with a two color palette. If the background is transparent a colorkey will be set. Antialiased images are rendered to 24-bit RGB images. If the background is transparent a pixel alpha will be included. Optimization: if you know that the final destination for the text (on the screen) will always have a solid background, and the text is antialiased, you can improve performance by specifying the background color. This will cause the resulting image to maintain transparency information by colorkey rather than (much less efficient) alpha values. If you render '\n' a unknown char will be rendered. Usually a rectangle. Instead you need to handle new lines yourself. Font rendering is not thread safe: only a single thread can render text any time.

8.2. Font.size

• determine the amount of space needed to render text Font.size(text): return (width, height) Returns the dimensions needed to render the text. This can be used to help determine the positioning needed for text before it is rendered. It can also be used for wordwrapping and other layout effects. Be aware that most fonts use kerning which adjusts the widths for specific letter pairs. For example, the width for "ae" will not always match the width for "a" + "e".

8.3. Font.set_underline

• control if text is rendered with an underline Font.set_underline(bool): return None When enabled, all rendered fonts will include an underline. The underline is always one pixel thick, regardless of font size. This can be mixed with the bold and italic modes.

8.4. Font.get_underline

• check if text will be rendered with an underline Font.get_underline(): return bool Return True when the font underline is enabled.

8.5. Font.set_bold

• enable fake rendering of bold text Font.set_bold(bool): return None Enables the bold rendering of text. This is a fake stretching of the font that doesn't look good on many font types. If possible load the font from a real bold font file. While bold, the font will have a different width than when normal. This can be mixed with the italic and underline modes.

8.6. Font.get_bold

• check if text will be rendered bold Font.get_bold(): return bool Return True when the font bold rendering mode is enabled.

8.7. Font.set_italic

• enable fake rendering of italic text Font.set_bold(bool): return None Enables fake rendering of italic text. This is a fake skewing of the font that doesn't look good on many font types. If possible load the font from a real italic font file. While italic the font will have a different width than when normal. This can be mixed with the bold and underline modes.

8.8. Font.get_italic

• check if the text will be rendered italic Font.get_italic(): return bool Return True when the font italic rendering mode is enabled.

8.9. Font.get_linesize

• get the line space of the font text Font.get_linesize(): return int Return the height in pixels for a line of text with the font. When rendering multiple lines of text this is the recommended amount of space between lines.

8.10. Font.get_height

• get the height of the font Font.get_height(): return int Return the height in pixels of the actual rendered text. This is the average size for each glyph in the font.

8.11. Font.get_ascent

• get the ascent of the font Font.get_ascent(): return int Return the height in pixels for the font ascent. The ascent is the number of pixels from the font baseline to the top of the font.

8.12. Font.get_descent

• get the descent of the font Font.get_descent(): return int Return the height in pixels for the font descent. The descent is the number of pixels from the font baseline to the bottom of the font.

The end