<meta charset="UTF-8">

<link href="style.css" rel="stylesheet" type="text/css">

<title>Спрайты - Helianthus</title>

  
Helianthus

  
Запуск и общие функции

  
Клавиатура и мышь

  
Рисование

  
Спрайты

  
Группы спрайтов

  
Камера

  
Звук

  
Все функции

Спрайты

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

Спрайты будут выводится на экран командой drawSprites, она рисует на экране сразу все спрайт. Её достаточно вызвать только один раз за кадр.

Спрайт может изображаться в виде прямоугольника выбранного вами цвета (spriteSetShapeColor), либо в виде картинки из выбранного вами файла (spriteSetAnimation). Кроме того спрайт может содержать анимацию, для этого вместо одного изображения в него можно загрузить папку с картинками — кадрами. Эти кадры могут переключаться автоматически (spritePlay) или по вашей команде (spriteSetFrame, spriteNextFrame).

Положение спрайта задаётся координатами его центра (spriteSetX, spriteSetY), и углом поворота (spriteSetRotation). Кроме того вы можете задать ширину и высоту спрайта (spriteSetWidth, spriteSetHeight)

Создать спрайт можно функцией createSprite, которая возвращает значение типа Sprite, которое по сути является адресом в памяти — указателем на описание спрайта внутри библиотеки Helianthus.

Пример:

#include <helianthus.h>

Sprite mysprite;

void init() {

    // Создать новый спрайт с центром в точке (200, 200)

    mysprite = createSprite(200, 200);

    // Загрузить файл изображения.

    spriteSetAnimation(mysprite, "picture.png"); 

}

void draw() {

    // Повернуть спрайт на 10 градусов перед рисованием.

    double r = spriteGetRotation(mysprite);

    spriteSetRotation(mysprite, r + 10);

    // Вывести все спрайты на экран.

    // Весь один спрайт, в данном случае.

    drawSprites();

}

int main() {

    worldSetInit(&init);

    worldSetDraw(&draw);

    worldRun();

    return 0;

}

Физика и обнаружение столкновений

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

Изначально физическое представление спрайта это прямоугольник соответствующий видимой форме спрайта. Но это может быть изменено, например, вы можете представить спрайт для физической модели в виде круга, при этом видимое изображение останется прежним (spriteSetCollider).

Физическое тело спрайта позволяет вам определять находится ли над спрайтом указатель мыши, см. функции mouseIsOver и mousePressedOver.

Помимо описания формы и размеров физического тела спрайта вам, скорее всего, понадобится задать и его скорость (spriteSetVelocityXY).

Для обнаружения столкновений и расчёта скоростей и позиций объектов после столкновения необходимо запустить одну из специальных функций. Они представлены в таблице ниже. Каждая из этих функций работает с двумя выбранными вами спрайтами и рассчитывает столкновения только между ними.

    Имя функции

    Первый спрайт сохраняет свою скорость?

    Второй спрайт сохраняет свою скорость?

    Описание

    spriteOverlap

    Да.

    Да.

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

    spriteCollide

    Нет.

    Нет.

    Спрайты отталкиваются друг от друга — обычное столкновение двух объектов

    spriteBounceOff

    Нет.

    Да.

    Первый спрайт отталкивается от второго, второй же продолжает своё движение так, словно ничего не было.

    spritePush

    Да.

    Нет.

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

    spriteCollideEx

    Задаётся параметрами функции.

    Задаётся параметрами функции.

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

Также указанные функции (кроме spriteOverlap) имеют параметр bounciness — это показатель энергии столкновения.

Если bounciness меньше 1, то взаимная скорость спрайтов после столкновения уменьшится, как если бы столкнулись мешки с песком.

Если больше 1, то скорости после столкновения увеличатся. Можете представить себе супер-упругий волшебный мячик, который после падения на пол подпрыгивает выше чем падал.

Параметр bounciness есть и у каждого спрайта (spriteSetBounciness). При расчёте параметры  bounciness от обоих спрайтов и параметр bounciness из функции перемножаются и получается окончательное значение bounciness для расчётов.

Таким образом запустив, например, функцию spritePush для двух ваших спрайтов вы тем самым инициируете расчёт физического взаимодействия межу ними. И кроме того вы одновременно с этим указываете какую роль в физической модели занимает ваш объект. Например для spritePush первый спрайт будет представлять из себя какую-то тяжёлую мощную платформу, сдвинуть которую второй спрайт не может — он просто отталкивается от неё сам, а платформа двигается (или стоит) как ни в чём ни бывало.

Однако работы всего лишь с двумя спрайтами мало для полноценной физической модели. В помощь вам Helianthus предлагает группы спрайтов. Поместив свои спрайты в различные группы (или в одну группу) вы можете одной командой вызвать расчёт столкновений между всеми спрайтами в группе или между спрайтами одной группы со спрайтами другой группы или между группой и одиночным спрайтом.

Также функция createEdgesGroup поможет вам создать группу спрайтов обозначающую границы экрана, чтобы ваши объекты отталкивались от краёв экрана.

Подробнее о группах и их функциях смотрите в разделе «Группы спрайтов».

Функции:

Sprite createSprite(double x, double y);

Создаёт спрайт с центром в указанной точке. См. также createSpriteEx.

Параметры:

x, y — координаты центра нового спрайта.

Sprite createSpriteEx(double x, double y, double width, double height);

Создаёт спрайт заданного размера с центром в указанной точке. См. также createSprite.

Параметры:

x, y — координаты центра нового спрайта;

width — ширина нового спрайта;

height — высота нового спрайта.

void spriteDestroy(Sprite sprite);

Удаляет спрайт. Спрайт удаляется также из всех групп в которые он был включён.

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

Важно: Скорее всего у вас в программе останется переменная в которой хранился указатель на спрайт. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на спрайт, спрайт удалён. Вы можете занести в эту переменную другой спрайт, но использовать старое значение переменной больше нельзя это приведёт у ошибкам и непредсказуемому поведению программы.

void spriteDestroyTimer(Sprite sprite, double lifetime);

Задаёт таймер для удаления спрайта через определённое время. Рекомендуется больше не обращаться в к этому спрайту из вашей программы и не хранить указатель на него. Так как неизвестно существует ли спрайт ещё или уже сработал таймер удаления. Смотрите также функцию spriteDestroy и примечание к ней.

Параметры:

lifetime — время в секундах по истечении которого спрайт должен быть удалён. Если 0 или меньше, то спрайт будет удалён немедленно. Если больше 0, то спрайт будет в один из промежутков между вызовами функции перерисовки кадра.

double spriteGetX(Sprite sprite);

double spriteGetY(Sprite sprite);

void spriteSetX(Sprite sprite, double x);

void spriteSetY(Sprite sprite, double y);

Получить (Get) либо задать (Set) координаты центра спрайта.

double spriteGetVelocityX(Sprite sprite);

double spriteGetVelocityY(Sprite sprite);

void spriteSetVelocityX(Sprite sprite, double x);

void spriteSetVelocityY(Sprite sprite, double y);

void spriteSetVelocityXY(Sprite sprite, double x, double y);

Получить (Get) либо задать (Set) координаты вектора скорости спрайта. См. также  spriteSetSpeedAndDirection.

void spriteSetSpeedAndDirection(Sprite sprite, double speed, double angle);

Задать скорость спрайта через угол направления и абсолютное значение скорости. Если вы не понимаете смысла слов «абсолютное значение», то в здесь подразумевается обычное бытовое значение смысла слова скорость. В данном случае она измеряется в пикселях в секунду.

Параметры:

speed — абсолютное значение скорости;

angle — угол направления движения в градусах. Не путайте, пожалуйста, с отображаемым поворотом спрайта (spriteSetRotation, spriteSetRotateToDirection).

double spriteGetSpeed(Sprite sprite);

Возвращает абсолютное значение скорости спрайта. См. также  spriteSetSpeedAndDirection.

double spriteGetDirection(Sprite sprite);

Возвращает направление движения в градусах. См. также spriteSetSpeedAndDirection. Не путайте, пожалуйста, с отображаемым поворотом спрайта (spriteGetRotation).

double spriteGetWidth(Sprite sprite);

void spriteSetWidth(Sprite sprite, double width);

Получить (Get) либо задать (Set) ширину спрайта.

double spriteGetHeight(Sprite sprite);

void spriteSetHeight(Sprite sprite, double height);

Получить (Get) либо задать (Set) высоту спрайта.

double spriteGetScale(Sprite sprite);

void spriteSetScale(Sprite sprite, double scale);

Получить (Get) либо задать (Set) масштабирование спрайта. Вы можете увеличить ли уменьшить весь спрайт и его физическое тело с сохранением всех пропорций. См. также  spriteGetScaledWidth,  spriteGetScaledHeight.

double spriteGetScaledWidth(Sprite sprite);

Возвращает ширину спрайта с учётом масштабирования. См. также spriteSetScale.

double spriteGetScaledHeight(Sprite sprite);

Возвращает высоту спрайта с учётом масштабирования. См. также spriteSetScale.

double spriteGetRotation(Sprite sprite);

void spriteSetRotation(Sprite sprite, double rotation);

Получить (Get) или задать (Set) поворот спрайта. Не путайте, пожалуйста, с направлением движения спрайта. См. также spriteSetSpeedAndDirection,  spriteSetRotateToDirection, spritePointTo.

double spriteGetRotationSpeed(Sprite sprite);

void spriteSetRotationSpeed(Sprite sprite, double rotationSpeed);

Получить (Get) или задать (Set) скорость вращения спрайта. Да, спрайт имеет ещё и скорость вращения. Вы можете её задать в градусах в секунду и спрайт будет вращаться сам.  См. также spriteSetRotation.

int spriteGetRotateToDirection(Sprite sprite);

void spriteSetRotateToDirection(Sprite sprite, int rotateToDirection);

Получить (Get) или задать (Set) автоматический поворот спрайта вдоль направления движения. rotateToDirection может принимать значение TRUE (число 1) или FALSE (число 0).

Когда rotateToDirection равно TRUE, спрайт будет автоматически поворачиваться в направлении своего движения (вектора скорости). См. также spriteSetSpeedAndDirection, spriteSetRotation.

int spriteGetMirrorX(Sprite sprite);

void spriteSetMirrorX(Sprite sprite, int mirrorX);

Получить (Get) или задать (Set) отражение спрайта по оси X.

Если  mirrorX больше или равно 0, то спрайт рисуется как обычно.

Если  mirrorX меньше нуля то рисуется зеркальное отражение спрайта по горизонтали.

int spriteGetMirrorY(Sprite sprite);

void spriteSetMirrorY(Sprite sprite, int mirrorY);

Получить (Get) или задать (Set) отражение спрайта по оси Y.

Если  mirrorY больше или равно 0, то спрайт рисуется как обычно.

Если  mirrorY меньше нуля то рисуется зеркальное отражение спрайта по вертикали.

double spriteGetDepth(Sprite sprite);

void spriteSetDepth(Sprite sprite, double depth);

Получить (Get) или задать (Set) показатель глубины спрайта. На переднем плане рисуются спрайты с наименьшим значением глубины, на заднем — с наибольшим. Таким образом задавая глубину спрайтов вы определяете порядок их отрисовки.

int spriteGetVisible(Sprite sprite);

void spriteSetVisible(Sprite sprite, int visible);

Получить (Get) или задать (Set) видимость спрайта.  Может принимать значение TRUE (число 1) — спрайт видно, или FALSE (число 0) — спрайт спрятан.

int spriteGetTag(Sprite sprite);

void spriteSetTag(Sprite sprite, int tag);

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

int spriteGetDebug(Sprite sprite);

void spriteSetDebug(Sprite sprite, int debug);

Получить (Get) или задать (Set) отображение отладочной информации для данного спрайта.  Может принимать значение TRUE (число 1) — включено, или FALSE (число 0) — выключено.

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

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

int spriteOverlap(Sprite a, Sprite b);

Возвращает TRUE если спрайты касаются или накладываются друг на друга. В противном случае возвращает FALSE.

int spriteCollide(Sprite a, Sprite b, double bounciness);

Определяет есть ли столкновение между двумя спрайтами и, если есть, то рассчитывает новые скорости и позиции для указанных спрайтов и возвращает TRUE. В противном случае возвращает FALSE. См. описание физической модели в разделе «Спрайты».

Параметры:

bounciess — показатель энергии столкновения.

int spriteBounceOff(Sprite sprite, Sprite other, double bounciness);

Определяет есть ли столкновение между двумя спрайтами и, если есть, то рассчитывает новую скорость и позицию для спрайта sprite (спрайт other не меняет своих параметров) и возвращает TRUE. В противном случае возвращает FALSE. См. описание физической модели в разделе «Спрайты».

Параметры:

bounciess — показатель энергии столкновения.

int spritePush(Sprite sprite, Sprite other, double bounciness);

Определяет есть ли столкновение между двумя спрайтами и, если есть, то рассчитывает новую скорость и позицию для спрайта other (спрайт sprite не меняет своих параметров) и возвращает TRUE. В противном случае возвращает FALSE. См. описание физической модели в разделе «Спрайты».

Параметры:

bounciess — показатель энергии столкновения.

int spriteCollideEx(Sprite a, Sprite b, int keepVelocityA, int keepVelocityB, double bounciness);

Определяет есть ли столкновение между двумя спрайтами и, если есть, то рассчитывает новые скорости и позиции для указанных спрайтов и возвращает TRUE. В противном случае возвращает FALSE. См. описание физической модели в разделе «Спрайты».

Параметры:

bounciess — показатель энергии столкновения;

keepVelocityA — если TRUE то спрайт a не меняет своих параметров и продолжает движение, так будто столкновения не было;

keepVelocityB — если TRUE то спрайт b не меняет своих параметров и продолжает движение, так будто столкновения не было.

double spriteGetBounciness(Sprite sprite);

void spriteSetBounciness(Sprite sprite, double bounciness);

Получить (Get) или задать (Set) показатель энергии столкновения для данного спрайта. См. описание физической модели в разделе «Спрайты».

void spriteSetCollider(Sprite sprite, Collider type, double xOffset, double yOffset, double rotationOffset);

Устанавливает параметры физического тела спрайта. Размеры тела определяются размерами самого спрайта. Для круга диаметр равен ширине спрайта.

Параметры:

type — форма COLLIDER_CIRCLE (круг) или COLLIDER_RECTANGLE (прямоугольник);

xOffset,  yOffset — смещение центра физического тела относительно центра спрайта;

rotationOffset — поворот физического тела относительно спрайта.

void spriteSetColliderCircle(Sprite sprite, double xOffset, double yOffset, double radius);

Задать физическое тела спрайта в виде круга.

Параметры:

xOffset,  yOffset — смещение центра физического тела относительно центра спрайта;

radius — радиус круга, если меньше 0, то будет использоваться половина от ширины спрайта.

void spriteSetColliderRectangle(Sprite sprite, double xOffset, double yOffset, double rotationOffset, double width, double height, double cornersRadius);

Задать физическое тела спрайта в виде прямоугольника. Прямоугольник может быть со скруглёнными углами.

Параметры:

xOffset,  yOffset — смещение центра физического тела относительно центра спрайта;

rotationOffset — поворот физического тела относительно спрайта;

width — ширина прямоугольника, если меньше 0, то будет использоваться ширина спрайта;

height — высота прямоугольника, если меньше 0, то будет использоваться высота спрайта;

cornersRadius — радиус скругления углов.

void spriteSetColliderEx(Sprite sprite, Collider type, double xOffset, double yOffset, double rotationOffset, double width, double height, double radius);

Устанавливает полный набор параметров физического тела спрайта.

Параметры:

type — форма COLLIDER_CIRCLE (круг) или COLLIDER_RECTANGLE (прямоугольник);

xOffset,  yOffset — смещение центра физического тела относительно центра спрайта;

rotationOffset — поворот физического тела относительно спрайта;

width — ширина, используется только для прямоугольника, если меньше 0, то будет использоваться ширина спрайта;

height — высота, используется только для прямоугольника, если меньше 0, то будет использоваться высота спрайта;

radius — для круга — его радиус, для прямоугольника — радиус скругления углов.

void spriteSetAnimation(Sprite sprite, const char *path);

Задать файл изображения или анимации спрайта. Поддерживаются изображения в формате PNG. Если вместо файла указана папка, то из неё загружаются все файлы PNG в алфавитном порядке — анимация спрайта.

Параметры:

path — путь к файлу PNG или к папке с фалами PNG для анимации.

void spriteSetNoAnimation(Sprite sprite);

Убрать анимацию и изображение со спрайта — спрайт будет рисоваться в виде простого прямоугольника.

void spritePlay(Sprite sprite);

Включить воспроизведение анимации для спрайта. При каждом вызове функции перерисовки окна будет переключаться кадр. Частоту перерисовки окна, а следовательно и частоту кадров для анимации спрайтов, можно задать функцией worldSetFrameRate. См. также spritePause.

void spritePause(Sprite sprite);

Остановить анимацию спрайта. См. также spritePlay.

void spriteNextFrame(Sprite sprite);

Перейти к следующему кадру анимации. Если это был последний кадр, то перейти к первому (точнее к нулевому).

void spriteSetFrame(Sprite sprite, int frame);

Перейти к кадру с заданным номером.

Параметры:

frame - номер кадра, кадры нумеруются начиная с нуля.

void spriteSetShapeColor(Sprite sprite, const char *color);

Установить цвет прямоугольника спрайта. Только для спрайтов у которых нет изображения или анимации.

Параметры:

color — текстовое наименование цвета, см. раздел «Рисование».

void spriteSetTintColor(Sprite sprite, const char *color);

Установить цвет подкрашивания спрайта. Компоненты указанного цвета умножаются на компоненты цвета изображения (или базового прямоугольника) спрайта. Таким образом вы можете немного менять цвета в спрайте, а также устанавливать общую прозрачность спрайта.

Параметры:

color — текстовое наименование цвета, см. раздел «Рисование».

void spritePointTo(Sprite sprite, double x, double y);

Повернуть спрайт по направлению к указанной точке. См. также spriteSetRotation.

Параметры:

x, y — координаты точки.

int mouseIsOver(Sprite sprite);

Функция возвращает TRUE (число 1) если указатель мыши находится над указанным спрайтом, иначе возвращает FALSE (число 0). См. также раздел «Спрайты».

int mousePressedOver(Sprite sprite);

Функция возвращает TRUE (число 1) если любая кнопка мыши нажата (и удерживается) в то время как указатель мыши находится над указанным спрайтом, иначе возвращает FALSE (число 0). См. также раздел «Спрайты».

int worldGetSpriteCount();

Возвращает количество спрайтов существующих в программе в данный момент. См. также worldGetSprite.

Sprite worldGetSprite(int i);

Возвращает спрайт по указанному номеру. См. также worldGetSpriteCount.

void drawSprites();

Вывести все спрайты на экран.