surfarray

Módulo de pygame para acceder a los pixels de una superficie usando una matriz como interfaz.

Funciones para convertir datos de pixel entre matrices y superficies de pygame. Este módulo solo funcionará cuando pygame puede tener acceso a los paquetes externos Numpy o Numeric.

Cada pixel se almacena como un único valor entero para representar los colores rojo, verde y azul. Las imágenes de 8 bits usan un valor de referencia a una paleta de colores. Los pixels que pueden representar mas colores usan un proceso de empaquetamiento de bits para agrupar tres o cuatro valores en un único número.

La matriz se organiza primero por su eje X y luego su eje Y. Las Matrices que tratan a los pixels como números empaquetados se definen como Matrices de dos dimensiones. Este módulo también puede separar las componentes de color en mas dimensiones; estos tipos de matrices se definen como matrices de tres dimensiones, donde el último indice indica con 0 el componente rojo, con 1 el componente verde y con 2 el azul.

Los sistemas de matriz que se utilizan son:

• numeric
• numpy

Por defecto se utilizará Numeric, siempre y cuando esté instalado. En otro caso se usará numpy si está instalado. Se lanzará la excepción ImportError si ninguno de los dos paquetes está instalado.

El sistema que se utilizará se puede cambiar en tiempo de ejecución usando el método use_arraytype(), que necesita como argumento el sistema de matriz a utilizar.

Nota: numpy y Numeric no son completamente compatibles. Algunas manipulaciones de vectores pueden funcionar en un sistema, pero tener un comportamiento diferente o incluso no funcionar en otro.

Además, a diferencia de Numeric, numpy puede usar enteros sin signo de 16 bits. Las imágenes con datos de 16 bits se tratarán como números sin signo. En cambio, Numeric siempre utilizará enteros con signo para la representación, es importante tener esto en mente, ya que usted puede estar utilizando funciones del módulo y sorprenderse por los valores.

El soporte para numpy es nuevo en pygame 1.8

Copia los pixels en una matriz de dos dimensiones.

pygame.surfarray.array2d(Surface): return array

Copia los pixels desde una superficie a una matriz de dos dimensiones. La profundidad de colores de la superficie controlará el tamaño de los valores enteros, y funcionará para cualquier tipo de formato de pixel.

Esta función bloqueará temporalmente la superficie (vea la función Surface.lock para mas detalles).

Genera una referencia a los pixels en una matriz de dos dimensiones.

pygame.surfarray.pixels2d(Surface): return array

Genera una nueva matriz de dos dimensiones que referencia directamente a los valores de pixels en una superficie. Cualquier cambio en la matriz afectará a los pixels de la superficie. Esta es una operación rápida ya que no se duplican los datos.

No se pueden crear matrices de referencia para superficies de 24 bits, pero si de cualquier otro tipo de superficies.

La superficie a la que se hace referencia permanecerá bloqueada mientras dure la vida del objeto matriz (vea el método Surface.lock para mas detalles).

Copia los pixels en una matriz de tres dimensiones.

pygame.surfarray.array3d(Surface): return array

Copia los pixels desde una superficie a una matriz de tres dimensiones. La profundidad de colores de la superficie controlará el tamaño de los valores enteros, y funcionará para cualquier tipo de formato de pixel.

Esta función bloqueará temporalmente la superficie (vea la función Surface.lock para mas detalles).

Genera una referencia a los pixels en una matriz de tres dimensiones.

pygame.surfarray.pixels3d(Surface): return array

Genera una nueva matriz de tres dimensiones que referencia directamente a los valores de pixels en una superficie. Cualquier cambio en la matriz afectará a los pixels de la superficie. Esta es una operación rápida ya que no se duplican los datos.

Esta operación solo funciona en superficies que tienen formatos de 24 o 32 bits. No se puede crear referencias a formatos de pixel mas bajos.

La superficie a la que se hace referencia permanecerá bloqueada mientras dure la vida del objeto matriz (vea el método Surface.lock para mas detalles).

Copia los valores alphas a una matriz de dos dimensiones.

pygame.surfarray.array_alpha(Surface): return array

Copia los valores alpha de los pixel (el grado de transparencia) desde una superficie a una matriz de dos dimensiones. Esta operación funcionará para cualquier formato de superficie. Las superficies que no tienen valores alpha retornarán una matriz con todos los valores opacos.

Esta función bloqueará temporalmente la superficie (vea la función Surface.lock para mas detalles).

Genera una referencia a los pixels alpha en una matriz de dos dimensiones.

pygame.surfarray.pixels_alpha(Surface): return array

Genera una nueva matriz de dos dimensiones que referencia directamente a los valores alpha de una superficie. Cualquier cambio en la matriz afectará a los pixels de la superficie. Esta es una operación rápida ya que no se duplican los datos.

Solo puede funcionar en superficies de 32 bits con valores alpha por cada pixel.

La superficie a la que se hace referencia permanecerá bloqueada mientras dure la vida del objeto matriz (vea el método Surface.lock para mas detalles).

Copia los valores clave de una superficie en una matriz de dos dimensiones.

pygame.surfarray.array_colorkey(Surface): return array

Genera una nueva matriz con los valores de transparencia por color clave de cada pixel. El pixel será completamente transparente si coincide con el valor del color clave; en caso contrario el pixel será completamente opaco.

Esta operación funcionará sobre cualquier tupo de formato de superficie. Si la imagen no tiene color calve se retornará una matriz completamente sólida.

Esta función bloqueará temporalmente la superficie.

Convierte una matriz en una nueva superficie.

pygame.surfarray.make_surface(array): return Surface

Genera una nueva superficie que coincide con los datos y el formato en la matriz. La matriz puede ser de dos o tres dimensiones con cualquier cantidad de valores enteros.

Dibuja directamente sobre los valores de una matriz.

pygame.surfarray.blit_array(Surface, array): return None

Copia valores directamente desde una matriz sobre una superficie. Esta operación es mas rápida que convertir la matriz en una superficie y luego imprimirla. La matriz debe tener las mismas dimensiones que la superficie y la operación reemplazará complemente todos los valores de los pixels.

Esta función bloqueará temporalmente la superficie como los nuevos valores que se copian.

Convierte una matriz de tres dimensiones a una matriz de dos dimensiones.

pygame.surfarray.map_array(Surface, array3d): return array2d

Convierte una matriz de tres dimensiones en una matriz de dos dimensiones. Esta función usará el formato de la superficie dada para controlar la conversión. Los formatos de superficie basados en una paleta no están soportados.

Define el sistema de matriz que se usará para matrices de superficie.

pygame.surfarray.use_arraytype (arraytype): return None

Usa el tipo de matriz indicado para el resto de las funciones del módulo. Los tipos de matriz disponibles son:

• numeric
• numpy

Se lanzará una excepción ValueError si el tipo de matriz solicitado no está disponible.

Esta función es nueva a partir de pygame 1.8

Obtiene el tipo de matriz utilizado actualmente.

pygame.surfarray.get_arraytype (): return str

Retorna el tipo de matriz que que se utiliza actualmente. Este valor será uno de los que forman parte de la tupla que devuelve get_arraytypes() e indica que sistema de matriz que se usará para la creación de matrices.

Esta función es nueva en pygame 1.8

Obtiene los sistema de matriz actualmente soportadas.

pygame.surfarray.get_arraytypes (): return tuple

Consulta que tipo de sistemas de vector están disponibles y los retorna como una tupla de cadenas de caracteres. Los valores de la tupla se pueden usar directamente en el método pygame.surfarray.use_arraytype(). Si no hay sistema de matriz disponible se podría obtener None como retorno.

Esta función es nueva en pygame 1.8.