Surface

Objeto de pygame para representar imágenes.

pygame.Surface( (width, height), flags=0, depth=0, masks=None): return Surface
pygame.Surface( (width, height), flags=0, Surface): return Surface

Un objeto Surface de pygame se utiliza para representar cualquier imagen. La superficie tiene un formato de pixel y resolución fija. Las superficies con pixeles de 8 bits usan una paleta de 256 colores.

Invoque pygame.Surface() para crear un nuevo objeto image. La superficie será completamente negra. El único argumento requerido es el tamaño. La superficie se creará con el formato que mejor coincida con la pantalla actual si no se especifican los argumentos adicionales.

El formato de pixel se puede controlar especificando la profundidad de colores o una superficie existente. El argumento flags es una combinación de características adiciones para la superficie. Puede utilizar cualquier combinación de estas:

• HWSURFACE: Genera la imagen en la memoria de video.
• SRCALPHA: El formato de pixel incluirá transparencias por pixel.

Ambas opciones son solo una solicitud, tal vez no sea posible para todos los modos de video.

Los usuarios avanzados pueden combinar un conjunto de opciones con un valor depth. El argumento masks es un conjunto de 4 números enteros que especifica cuales bits representan a cada color en el pixel. Las superficies normales no requieren el argumento mask.

Las superficies pueden tener varios atributos adicionales como planos alpha, colores clave o recortes. Estas funciones afectan principalmente a la forma en que se imprime la superficie sobre otra. Las rutinas blit intentarán usar aceleración de hardware cuando sea posible, en caso contrario usarán métodos de impresión por software muy optimizados.

Existen tres tipos de transparencia en pygame: colores clave, transparencia de superficie, y transparencia de pixel. La transparencia de superficie se puede combinar con colores clave, pero las imágenes con transparencia de pixel no puede usar los otros modos. La transparencia por color clave hace transparente un solo color. No se imprimirán los pixeles que coincidan con el color clave. La transparencia de superficie es un valor individual que cambia la transparencia de la imagen completa. Una transparencia de superficie de 255 será opaca mientras que un valor de 0 será completamente transparente.

La transparencia de pixel es diferente porque se almacena el valor de transparencia de cada pixel. Esto permite crear efectos de transparencia mas precisos, pero es algo mas lento. La transparencia de pixel no se puede mezclar con los otros tipos de transparencia.

Existe soporte para acceder a los pixels de la superficie. El acceso pixels en superficies de hardware es lento y no se recomienda. Estos métodos son adecuados para acceso simple, pero serán considerablemente lentos cuando realice mucho trabajo de pixels con ellos. Si planea realizar mucho trabajo a nivel de pixels se recomienda usar el módulo pygame.surfarray que puede tratar a las superficies como vectores de varias dimensiones (y es bastante rápido).

Cualquier función que acceda directamente a los datos de pixels de la superficie necesitarán que la superficie esté bloqueada. Estas funciones pueden bloquear (block()) o desbloquear (unlock()) las superficies por ellas mismas si ayuda, pero, si habrá una sobrecarga muy grande de múltiples bloqueos o desbloqueos si se llama a esta función muchas veces. Es mejor bloquear manualmente la superficie antes de llamar a las funciones muchas veces, y luego desbloquear la superficie cuando se halla finalizado. Todas las funciones que necesitan bloquear la superficie lo indican en la documentación. Recuerde dejar la superficie bloqueada solo mientras sea necesario.

Los pixels de la superficie se almacenan internamente como un número individual que tiene todos los colores agrupados. Use las funciones Surface.map_rgb() y Surface.unmap_rgb() para convertir entre valores individuales (rojo, verde y azul) en colores agrupados para la superficie.

Las superficies también pueden ser una referencia a una sección de otra superficie. Se generan con el método Surface.subsurface(). Cualquier cambio en alguna de las dos superficie que verá reflejado en ambas.

Cada superficie contiene un área de recorte. Por defecto el área de recorte cubre la superficie entera. Si esta área de modifica, todas las operaciones de dibujado solo afectarán un área mas pequeña.

Dibuja una imagen sobre otra.

Surface.blit(source, dest, area=None, special_flags = 0): return Rect

Dibuja una superficie source sobre otra. La impresión se puede posicionar usando el argumento dest. dest puede ser un par de coordenadas representando la esquina superior izquierda o bien un rectángulo, cuya esquina superior izquierda representará la posición destino de impresión. El tamaño de rectángulo destino no afectará la impresión.

Se puede pasar un rectángulo opcional como argumento area. Este representa una porción mas pequeña de la superficie source a imprimir.

La opción special_flags puede tomar los siguientes valores:

• BLEND_ADD
• BLEND_SUB
• BLEND_MULT
• BLEND_MIN
• BLEND_MAX
• 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

Note, tal vez se agreguen mas opciones de impresión en el futuro.

El rectángulo retornado representa el área de los pixels afectados, excluyendo cualquier pixel fuera de la superficie destino o el área de recorte.

Se ignorarán los pixels alpha cuand se imprima sobre una superficie de 8 bits.

La opción special_flags es nueva en pygame 1.8.

Cambia el formato de pixel de una imagen.

Surface.convert(Surface): return Surface
Surface.convert(depth, flags=0): return Surface
Surface.convert(masks, flags=0): return Surface
Surface.convert(): return Surface

Genera una nueva copia de la superficie con un formato de pixel modificado. El nuevo formato de pixel se puede determinar a partir de otra superficie existente. Otra posibilidad es especificar los argumentos depth, flags y mask, de manera similar a pygame.Surface()

La superficie nueva tendrá el mismo formato de pixel de la pantalla si no envía ningún argumento. Este formato será el mas rápido de imprimir. Es una buena idea convertir todas las superficies antes de imprimirlas varias veces.

La superficie convertida podría no tener pixels alpha, dado que serán eliminados si la superficie original los tenía. Vea la función Surface.convert_alpha() para crear o preservar superficies con canal alpha.

Surface.convert_alpha(Surface): return Surface
Surface.convert_alpha(): return Surface

Genera una nueva copia de la superficie con el formato de pixel deseado. La superficie nueva tendrá un formato adecuado para imprimirse mas rápidamente el formato indicado con canal alpha. Si no se especifica el argumento surface, la nueva superficie se optimizará para el formato de pantalla actual.

A diferencia del método Surface.convert(), el formato de pixel para la imagen nueva podría no ser exactamente el mismo que se pide, aunque se optimizará para imprimirse sobre la superficie destino.

Genera una nueva copia de la superficie.

Surface.copy(): return Surface

Hace una copia duplicada de un superficie. La superficie nueva tendrá el mismo formato de pixel, paletas de colores y configuración de transparencia que la original.

Pinta una superficie con un color solido.

Surface.fill(color, rect=None, special_flags=0): return Rect

Pinta la superficie con un color solido. Se pintará la superficie entera si no se especifica el argumento rect. El argumento rect limitará la modificación al área especificada. La operación de pintado también se limitará por el área de recorte de la superficie.

El argumento color puede ser una secuencia RGB, RGBA o un índice de una paleta de colores. Si usa el formato RGB se ignorará el componente alpha (una parte de RGBA) a menos que la superficie use transparencia por pixel (atributo SRCALPHA).

A partir de pygame 1.8.0 puede usar las siguientes opciones adicionales:

• BLEND_ADD
• BLEND_SUB
• BLEND_MULT
• BLEND_MIN
• BLEND_MAX

Y a partir de pygame 1.8.1 se suman:

• 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

Esta función retornará el área afectada de la superficie.

Define el color clave de transparencia.

Surface.set_colorkey(Color, flags=0): return None
Surface.set_colorkey(None): return None

Define el color clave para la superficie. Cuando imprima esta superficie sobre otra, cualquier pixel que tenga el mismo color que el color clave no se imprimirá. El argumento color puede ser un color RGB o un indice de una paleta de colores. Si se envía None como argumento entonces se deshabilitará el color clave.

Se ignorará el color clave si la superficie tiene un formato para usar valores alpha por pixel. La transparencia por color clave se puede mezclar con la transparencia a nivel de superficie.

Se puede definir el argumento opcional flags a pygame.RLEACCEL para obtener mejor rendimiento en pantallas que no tengan aceleración de video. Una superficie RLEACCEL puede ser mas lenta de modificar, pero se imprimirá mas rápido.

Obtiene el color clave de transparencia actual.

Surface.get_colorkey(): return RGB or None

Retorna el color clave actual de la superficie. Si la superficie no tiene color clave la función retornará None.

Define el valor de transparencia para toda la superficie.

Surface.set_alpha(value, flags=0): return None
Surface.set_alpha(None): return None

Define el valor de transparencia para la superficie. Cuando se imprima esta superficie sobre otra los pixels se dibujarán ligeramente transparentes. El valor de transparencia es un número entero de 0 a 255, 0 representa completamente transparente y 255 completamente opaco. Se deshabilitará la transparencia de la superficie si se pasa None como valor de transparencia.

Esta transparencia es diferente a la transparencia por pixel. Se ignorará este valor de transparencia si la superficie contiene pixels con transparencia. Si la superficie contiene transparencia por pixel, cuando llame a esta función con el argumento None se deshabilitará esa transparencia por pixel.

El argumento adicional flags se puede definir como pygame.RLEACCEL para obtener mayor rendimiento en pantallas que no tengan aceleración de video. Una superficie RLEACCEL será mas lenta de modificar, aunque será mas rápido imprimirla sobre otra.

Obtiene el valor de transparencia de la superficie.

Surface.get_alpha(): return int_value or None

Retorna el valor de transparencia actual para la superficie. Se retornará None si el valor de transparencia no está definido.

Bloquea la memoria de la superficie para acceder a sus pixels.

Surface.lock(): return None

Bloquea los datos de pixel de una superficie para acceder a ellos. En la superficies aceleradas, los datos de pixels podrían estar almacenados en memoria de video volátil o en formas no lineales bajo compresión. Cuando se bloquea una superficie la información de pixels se convierte en un formato accesible. El código que lee o escribe valores de pixels necesitará que la superficie se bloquee para realizar esas tareas.

Las superficies no deberían permanecer bloqueadas mas de lo necesario. Una superficie bloqueada podría no mostrarse o ser manipulada por pygame.

No todas las superficies necesitan bloquease. El método Surface.mustlock() puede determinar si la superficie requiere bloquease. De todas formas, no hay desventaja al bloquear o desbloquear una superficie que no lo necesita.

Todas las funciones de pygame bloquearán o desbloquearán automáticamente los datos de la superficie si es necesario. Si una sección de código hace varias llamas para modificar la superficie, entonces se bloqueará y desbloqueará muchas veces la superficie. Por este motivo, es mucho mas útil bloquear la superficie manualmente, luego modificarla muchas veces y luego desbloquearla manualmente.

Es seguro anidar llamas para bloquear y desbloquear. La superficie solo se desbloqueará después de soltar el último bloqueo.

Desbloquea la memoria de la superficie del acceso a pixels.

Surface.unlock(): return None

Desbloquea los datos de pixels de la superficie luego de que ha sido bloqueada. La superficie desbloqueada podrá imprimirse nuevamente por pygame. Vea la documentación de Surface.lock() para mas detalles.

Todas las funciones de pygame bloquearán o desbloquearán automáticamente los datos de la superficie si es necesario. Si una sección de código hace varias llamas para modificar la superficie, entonces se bloqueará y desbloqueará muchas veces la superficie. Por este motivo, es mucho mas útil bloquear la superficie manualmente, luego modificarla muchas veces y luego desbloquearla manualmente.

Es seguro anidar llamas para bloquear y desbloquear. La superficie solo se desbloqueará después de soltar el último bloqueo.

Verifica si la superficie necesita bloquearse.

Surface.mustlock(): return bool

Retorna True si la superficie se debe bloquear para acceder a sus datos de pixel. Usualmente las superficies de software pura no necesitan bloquease. Este método no se usa con frecuencia, dado que es seguro y mas rápido directamente bloquear todas las superficies como sea necesario.

Todas las funciones de pygame bloquearán o desbloquearán automáticamente los datos de la superficie si es necesario. Si una sección de código hace varias llamas para modificar la superficie, entonces se bloqueará y desbloqueará muchas veces la superficie. Por este motivo, es mucho mas útil bloquear la superficie manualmente, luego modificarla muchas veces y luego desbloquearla manualmente.

Consulta si la superficie está bloqueada.

Surface.get_locked(): return bool

Retorna True cuando la superficie está bloqueada. Esta función no se fija o preocupa sobre cuantas veces se ha bloqueado la superficie.

Obtiene los bloqueos de la superficie.

Surface.get_locks(): return tuple

Retorna los bloqueos existentes para la superficie.

Obtiene el valor de color de un pixel

Surface.get_at( (x, y) ): return Color

Retorna el valor de color RGBA en la posición indicada. Si la superficie no tiene transparencia por pixel, entonces el valor alpha del color será siempre 255 (completamente opaco). Se lanzará una excepción IndexError si la posición del pixel está fuera del área de la superficie.

Obtener y definir los pixels de a uno a la vez es una tarea generalmente lenta para ser utilizada en un juego o una situación de tiempo real.

Esta función bloqueará y desbloqueará la superficie temporalmente como sea necesario.

Define el valor de color para un pixel.

Surface.set_at( (x, y), Color): return None

Define el valor de color RGBA o entero (si utiliza paleta) de un pixel. Si la superficie no tiene transparencia por pixel, entonces el valor alpha se ignorará. No tendrá ningún efecto definir pixels fuera del área total o el área de recorte de la superficie.

Obtener y definir los pixels de a uno a la vez es una tarea generalmente lenta para ser utilizada en un juego o una situación de tiempo real.

Esta función bloqueará y desbloqueará la superficie temporalmente como sea necesario.

Obtiene la paleta de colores para una superficie de 8 bits.

Surface.get_palette(): return [RGB, RGB, RGB, ...]

Retorna una lista de a lo máximo 256 elementos de color que representan los colores utilizados en una superficie de 8bits. La lista que se retorna es una copia de la paleta, y los cambios que se realicen en esta copia no tendrán efecto sobre la superficie.

Obtiene el color de una entrada de la paleta de colores.

Surface.get_palette_at(index): return RGB

Retorna los valores rojo, verde y azul de un elemento de la paleta de colores de la superficie. El argumento index debería ser un valor entre 0 y 255.

Define la paleta de colores para una superficie de 8 bits.

Surface.set_palette([RGB, RGB, RGB, ...]): return None

Define la paleta completa para una superficie de 8 bits. Esta función reemplazará los colores de la paleta existente. Se puede enviar una paleta parcial, de modo que solo se reemplazarán los primeros elementos de la misma.

Esta función no hace nada sobre una superficie con mas de 8 bits por pixel.

Define el color para un solo elemento en una paleta de colores.

Surface.set_at(index, RGB): return None

Define el valor de un color en la paleta de una superficie. El valor del argumento index debería estar ente 0 y 255.

Esta función no hace nada sobre una superficie con mas de 8 bits por pixel.

Convierte un color en un formato empaquetado.

Surface.map_rgb(Color): return mapped_int

Convierte un color RGBA en un número entero empaquetado para esta superficie. El número entero retornado no contendrá mas bits que la profundidad de color de la superficie. Estos valores empaquetados no se usan con frecuencia dentro de pygame, aunque se pueden pasar como argumento a varias funciones que soliciten una superficie y un color.

Vea la documentación del objeto Surface para obtener mas información acerca de los colores y los formatos de pixel.

Convierte el valor de un entero empaquetado en un color.

Surface.map_rgb(mapped_int): return Color

Convierte un color de formato empaquetado en un conjunto de componentes de color RGB para esta superficie. Estos valores empaquetados no se usan con frecuencia dentro de pygame, aunque se pueden pasar como argumento a varias funciones que soliciten una superficie y un color.

Vea la documentación del objeto Surface para obtener mas información acerca de los colores y los formatos de pixel.

Define el área de recorte para la superficie.

Surface.set_clip(rect): return None
Surface.set_clip(None): return None

Cada superficie tiene una área de recorte activa. Este recorte es un rectángulo que representa a los pixels que se pueden modificar en una superficie. Toda la superficie se podrá modificar si se pasa None como área de recorte.

El área de recorte está siempre limitada al área de la superficie en sí misma. Si el rectángulo de recorte es mas grande, entonces se encogerá para caber dentro de la superficie.

Obtiene el área de recorte actual de la superficie.

Surface.get_clip(): return Rect

Retorna una rectángulo que representa el área de recorte. La superficie siempre retornará un rectángulo válido que nunca estará por afuera de los bordes de la superficie. La superficie retornará el área completa de la misma si no se ha definido un área de recorte.

Genera una nueva superficie que hace referencia a su pariente.

Surface.subsurface(Rect): return Surface

Retorna una nueva superficie que comparte sus pixels con su superficie pariente. La nueva superficie se considera hija de la original. Las modificaciones a los pixels de cualquier de las dos superficies afectará a la otra. La información de la superficie como el área de recorte o los colores clave son únicos para cada superficie.

La nueva superficie heredará la paleta, colores clave y configuración de transparencia de su padre.

Es posible tener cualquier número de sub-superficies y sub-sub-superficies de una superficie. También es posible tener una sub-superficie de la pantalla principal si el modo de video no está acelerado por software.

Vea las funciones Surface.get_offset() y Subsurfaces.get_parent() para aprender mas acerca del estado de una sub-superficie.

Encuentra el padre de una sub-superficie.

Surface.get_parent(): return Surface

Retorna el padre de una sub-superficie. Si el receptor no es una sub-superficie entonces se retornará None.

Obtiene el padre de mayor nivel de una superficie.

Surface.get_abs_parent(): return Surface

Retorna el padre de una sub-superficie. Se retornará None si el receptor no es una sub-superficie.

Encuentra la posición la superficie hija dentro del la superficie padre.

Surface.get_offset(): return (x, y)

Obtiene la posición de desplazamiento de una sub-superficie dentro de la superficie padre. Retornará (0, 0) si la superficie no es una sub-superficie.

Obtiene la posición absoluta de una superficie hija en relación a su padre de mayor nivel.

Surface.get_abs_offset(): return (x, y)

Obtiene la posición desplazamiento de una superficie hija en relación a superficie padre de nivel superior. Retornará (0, 0) si la superficie no es una sub-superficie.

Obtiene las dimensiones de una superficie.

Surface.get_size(): return (width, height)

Retorna el ancho y alto de una superficie medida en pixels.

Obtiene el ancho de una superficie.

Surface.get_width(): return width

Retorna el ancho de una superficie medida en pixels.

Obtiene la altura de una superficie.

Surface.get_height(): return height

Retorna la altura de una superficies medida en pixels.

Obtiene el área rectangular de una superficie.

Surface.get_rect(*\*kwargs): return Rect

Retorna un nuevo rectángulo que cubre la superficie entera. Este rectángulo siempre comenzará en la posición (0, 0) y tendrá el ancho y alto idéntico al tamaño de la imagen.

Puede pasar valores clave como argumentos a esta función. Estos argumentos se aplicarán a los atributos del rectángulo antes de ser retornado. Un ejemplo podría ser mysurf.get_rect(center=(100,100)) para crear un rectángulo de la superficie con centro en la posición (100, 100).

Obtiene la profundidad de colores en bits del formato de pixel de la superficie.

Surface.get_bitsize(): return int

Retorna el número de bits utilizados para representar cada pixel. Este valor podría no coincidir exactamente con el número de bytes usados por pixel. Por ejemplo, una superficie de 15 bits requiere 2 bytes completos.

Obtiene el número de bytes utilizados por pixel de la superficie.

Surface.get_bytesize(): return int

Retorna el número de bytes utilizados por pixel.

Obtiene las opciones adicionales utilizadas por la superficie.

Surface.get_flags(): return int

Retorna el conjunto de propiedades de la superficie. Cada propiedad es un bit en la máscara de bits flags. Las propiedades habituales son HWSURFACE, RLEACCEL, SRCALPHA y SRCCOLORKEY.

Esta es una lista mas completa de propiedades. La lista completa de estas propiedades se puede encontrar en el archivo sdl_video.h.

y algunas disponibles para la función pygame.display.set_mode():

otras utilizadas internamente (de solo lectura)

Obtiene el número de bytes utilizados por cada fila de la superficie.

Surface.get_pitch(): return int

Retorna el número de bytes que separan a cada fila de pixels en una superficie. Las superficies en memoria de video no siempre se almacenan en forma lineal. Las sub-superficies también podrían tener un pitch mas grande que su verdadera longitud.

Este valor no es necesario para el uso habitual de pygame.

Obtiene la máscara de bits necesaria para convertir entre un color RGB y un color empaquetado.

Surface.get_masks(): return (R, G, B, A)

Retorna la máscara de bits que se utiliza para empaquetar cada color en un número entero.

Este valor no se necesita para el uso normal de pygame.

Define la máscara de bits necesaria para convertir entre un color RGB en un color en formato empaquetado.

Surface.set_masks( (r,g,b,a) ): return None

Esta función no se necesita para el uso habitual de pygame.

Es una función nueva a partir de pygame 1.8.1.

Obtiene los bits de intercambios necesarios para convertir un color RGB en un color en formato empaquetado.

Surface.get_shifts(): return (R, G, B, A)

Retorna los bits de intercambio de pixel necesarios para convertir el formato de cada color.

Este valor no se necesita para el uso habitual de pygame.

Define los bits de intercambios necesarios para convertir un color RGB en un color en formato empaquetado.

Surface.get_shifts( (r,g,b,a) ): return None

Esta función no se necesita para el uso habitual de pygame.

Esta función es nueva a partir de pygame 1.8.1.

Obtiene los bits significativos que se usan para convertir el formato de color.

Surface.get_losses(): return (R, G, B, A)

Retorna el número menos significativo de bits agrupados por cada color en un número entero empaquetado.

Este valor no se necesita para el uso habitual de pygame.

Obtiene el rectángulo mas pequeño que contiene información.

Surface.get_bounding_rect(min_alpha = 1): return Rect

Retorna la región rectangular mas pequeña que contiene todos los pixels en una superficie que tienen un atributo de transparencia mas grande o igual que le indicado por argumento.

Esta función bloqueará y desbloqueará temporalmente la superficie.

Esta función es nueva en pygame 1.8.

Obtiene un objeto buffer para los pixels de la superficie.

Surface.get_buffer(): return BufferProxy

Retorna un objeto buffer para los pixels de la superficie. El buffer se puede usar para acceder y manipular directamente los pixels.

Este método bloquea y desbloquea la superficie de forma implícita. El bloqueo a la superficie se anulará una vez que el objeto BufferProxy sea eliminado.

Esta función es nueva en pygame 1.8.