Функции для преобразования между массивами NumPy и объектами Surface. Этот модуль будет функциональным только тогда, когда pygame сможет использовать внешний пакет NumPy. Если NumPy не может быть импортирован, surfarray превращается в MissingModule объект.

Каждый пиксель хранится как единственное целое значение для представления красного, зеленого и синего цветов. 8-битные изображения используют значение, которое смотрит в цветовую карту. Пиксели с большей глубиной используют процесс упаковки битов для размещения трех или четырех значений в одно число.

Массивы индексируются по оси X сначала, а затем по оси Y. Массивы, которые рассматривают пиксели как единственное целое число, называются двумерными массивами. Этот модуль также может разделять значения красного, зеленого и синего цветов на отдельные индексы. Эти типы массивов называются трехмерными массивами, а последний индекс равен 0 для красного, 1 для зеленого и 2 для синего.

Пиксели двумерного массива, возвращаемого array2d() и pixels2d(), отображаются на конкретной поверхности. Используйте pygame.Surface.unmap_rgb() для преобразования в цвет и pygame.Surface.map_rgb() для получения специфичного для поверхности пиксельного значения цвета. Целочисленные пиксельные значения могут использоваться напрямую только между поверхностями с совпадающими макетами пикселей (см. pygame.Surface).

Все функции, которые ссылаются на «массив», скопируют информацию о поверхности в новый массив numpy. Все функции, которые ссылаются на «пиксели», будут напрямую ссылаться на пиксели с поверхности, и любые изменения, произведенные в массиве, внесут изменения на поверхности. Поскольку эти последние функции совместно используют память с поверхностью, эта функция будет заблокирована в течение всего времени существования массива.

pygame.surfarray.array2d()

Копирование пикселей в двумерный массив

array2d(Surface) -> array

Копирование mapped (сырых) пикселей с поверхности в двумерный массив. Глубина бита поверхности будет контролировать размер целочисленных значений и будет работать с любым типом формата пикселей.

Эта функция временно заблокирует поверхность при копировании пикселей (см. метод pygame.Surface.lock() - заблокировать память поверхности для доступа к пикселям).

pygame.surfarray.pixels2d()

Ссылка на пиксели в двумерный массив

pixels2d(Surface) -> array

Создание нового двумерного массива, который напрямую ссылается на пиксельные значения на поверхности. Любые изменения в массиве повлияют на пиксели на поверхности. Это быстрая операция, так как данные не копируются.

Пиксели с поверхности с 24-битным форматом не могут быть сохранены, но все другие глубины бита поверхности могут.

Эта ссылающаяся поверхность останется заблокированной на всё время существования массива, так как созданный этой функцией массив совместно использует память с поверхностью. См. метод pygame.Surface.lock() - заблокировать память поверхности для доступа к пикселям.

pygame.surfarray.array3d()

Копирование пикселей в трехмерный массив

array3d(Surface) -> array

Копирование пикселей с поверхности в трехмерный массив. Глубина бита поверхности будет контролировать размер целочисленных значений и будет работать с любым типом формата пикселей.

Эта функция временно заблокирует поверхность при копировании пикселей (см. метод pygame.Surface.lock() - заблокировать память поверхности для доступа к пикселям).

pygame.surfarray.pixels3d()

Ссылка на пиксели в трехмерный массив

pixels3d(Surface) -> array

Создание нового трехмерного массива, который напрямую ссылается на пиксельные значения на поверхности. Любые изменения в массиве повлияют на пиксели на поверхности. Это быстрая операция, так как данные не копируются.

Это будет работать только с поверхностями, имеющими 24-битный или 32-битный формат. Форматы с меньшей глубиной пикселей не могут быть сохранены.

Эта ссылающаяся поверхность останется заблокированной на всё время существования массива, так как созданный этой функцией массив совместно использует память с поверхностью. См. метод pygame.Surface.lock() - заблокировать память поверхности для доступа к пикселям.

pygame.surfarray.array_alpha()

Копирование альфа-каналов пикселей в двумерный массив

array_alpha(Surface) -> array

Копирование значений альфа-канала пикселей (степени прозрачности) с поверхности в двумерный массив. Это будет работать с любым типом формата поверхности. Поверхности без пиксельного альфа-канала вернут массив со всеми непрозрачными значениями.

Эта функция временно заблокирует поверхность при копировании пикселей (см. метод pygame.Surface.lock() - заблокировать память поверхности для доступа к пикселям).

pygame.surfarray.pixels_alpha()

Ссылка на альфа-каналы пикселей в двумерный массив

pixels_alpha(Surface) -> array

Создание нового двумерного массива, который напрямую ссылается на значения альфа-канала (степени прозрачности) на поверхности. Любые изменения в массиве повлияют на пиксели на поверхности. Это быстрая операция, так как данные не копируются.

Это может работать только с 32-битными поверхностями с альфа-каналом на пиксель.

Эта ссылающаяся поверхность останется заблокированной на всё время существования массива, так как созданный этой функцией массив совместно использует память с поверхностью. См. метод pygame.Surface.lock() - заблокировать память поверхности для доступа к пикселям.

pygame.surfarray.array_red()

Копирование красных пикселей в двумерный массив

array_red(Surface) -> array

Копирование значений красного канала пикселей с поверхности в двумерный массив. Это будет работать с любым типом формата поверхности.

Эта функция временно заблокирует поверхность при копировании пикселей (см. метод pygame.Surface.lock() - заблокировать память поверхности для доступа к пикселям).

Новое в pygame 2.0.2.

pygame.surfarray.pixels_red()

Ссылка на красные пиксели в двумерный массив.

pixels_red (Surface) -> array

Создание нового двумерного массива, который напрямую ссылается на значения красного канала на поверхности. Любые изменения в массиве повлияют на пиксели на поверхности. Это быстрая операция, так как данные не копируются.

Это может работать только с 24-битными или 32-битными поверхностями.

Эта ссылающаяся поверхность останется заблокированной на всё время существования массива, так как созданный этой функцией массив совместно использует память с поверхностью. См. метод pygame.Surface.lock() - заблокировать память поверхности для доступа к пикселям.

pygame.surfarray.array_green()

Копирование зелёных пикселей в двумерный массив

array_green(Surface) -> array

Копирование значений зелёного канала пикселей с поверхности в двумерный массив. Это будет работать с любым типом формата поверхности.

Эта функция временно заблокирует поверхность при копировании пикселей (см. метод pygame.Surface.lock() - заблокировать память поверхности для доступа к пикселям).

Новое в pygame 2.0.2.

pygame.surfarray.pixels_green()

Ссылка на зелёные пиксели в двумерный массив.

pixels_green (Surface) -> array

Создание нового двумерного массива, который напрямую ссылается на значения зелёного канала на поверхности. Любые изменения в массиве повлияют на пиксели на поверхности. Это быстрая операция, так как данные не копируются.

Это может работать только с 24-битными или 32-битными поверхностями.

Эта ссылающаяся поверхность останется заблокированной на всё время существования массива, так как созданный этой функцией массив совместно использует память с поверхностью. См. метод pygame.Surface.lock() - заблокировать память поверхности для доступа к пикселям.

pygame.surfarray.array_blue()

Копирование синих пикселей в двумерный массив

array_blue(Surface) -> array

Копирует значения синего канала пикселей из поверхности в двумерный массив. Это будет работать для любого типа формата поверхности.

Эта функция временно заблокирует поверхность во время копирования пикселей (см. pygame.Surface.lock() - блокировка памяти поверхности для доступа к пикселям).

Новая функция в pygame 2.0.2.

pygame.surfarray.pixels_blue()

Ссылка на синие пиксели в двумерный массив.

pixels_blue (Surface) -> array

Создает новый двумерный массив, который напрямую ссылается на значения синего канала в поверхности. Любые изменения в массиве повлияют на пиксели на поверхности. Это быстрая операция, так как данные не копируются.

Это может работать только с поверхностями 24-битного или 32-битного формата.

Поверхность, на которую ссылается массив, останется заблокированной на все время существования массива, так как созданный массивом массив разделяет память с поверхностью. См. pygame.Surface.lock() - блокировка памяти поверхности для доступа к пикселям.

pygame.surfarray.array_colorkey()

Копирование значений цветного ключа в двумерный массив

array_colorkey(Surface) -> array

Создает новый массив со значением прозрачности цветного ключа каждого пикселя. Если пиксель совпадает с цветным ключом, он будет полностью прозрачным; в противном случае он будет полностью непрозрачным.

Это будет работать с любым типом формата поверхности. Если у изображения нет цветного ключа, будет возвращен плотный непрозрачный массив.

Эта функция временно заблокирует поверхность при копировании пикселей.

pygame.surfarray.make_surface()

Копирование массива в новую поверхность

make_surface(array) -> Surface

Создает новую поверхность, которая максимально соответствует данным и формату массива. Массив может быть двумерным или трехмерным с целочисленными значениями любого размера. Функция make_surface использует интерфейс структуры массива для получения свойств массива, поэтому она не ограничивается только массивами NumPy. См. pygame.pixelcopy.

Новая функция в pygame 1.9.2: Поддержка интерфейса структуры массива.

pygame.surfarray.blit_array()

Прямое копирование значений массива

blit_array(Surface, array) -> None

Прямое копирование значений из массива в поверхность. Это быстрее, чем преобразование массива в поверхность и выполнение blit. Массив должен иметь те же размеры, что и поверхность, и полностью заменит все значения пикселей. Допускаются только целочисленные, символьные и массивы записей.

Эта функция временно заблокирует поверхность при копировании новых значений.

pygame.surfarray.map_array()

Преобразование трехмерного массива в двумерный

map_array(Surface, array3d) -> array2d

Преобразует трехмерный массив в двумерный. Для преобразования будет использован заданный формат поверхности. Поддерживаются форматы поверхностей палитры для массивов NumPy.

pygame.surfarray.use_arraytype()

Установка используемого типа массива для массивов поверхностей

use_arraytype (arraytype) -> None

УСТАРЕВШАЯ функция: Использует указанный тип массива для функций модуля. Единственный поддерживаемый тип массива — 'numpy'. Другие значения приведут к ошибке ValueError. Использование этой функции вызовет DeprecationWarning.

pygame.surfarray.get_arraytype()

Получение текущего активного типа массива

get_arraytype () -> str

УСТАРЕВШАЯ функция: Возвращает текущий активный тип массива. Это будет значение из кортежа get_arraytypes() и указывает, какой тип модуля массива используется для создания массива. Использование этой функции вызовет DeprecationWarning.

Новая функция в pygame 1.8.

pygame.surfarray.get_arraytypes()

Получение типов массивов, которые в данный момент поддерживаются

get_arraytypes () -> tuple

УСТАРЕВШАЯ функция: Проверяет доступные типы систем массивов и возвращает их как кортеж строк. Значения кортежа можно напрямую использовать в методе pygame.surfarray.use_arraytype() (). Если подходящая система массивов не найдена, будет возвращено None. Использование этой функции вызовет DeprecationWarning.

Новая функция в pygame 1.8.