Рисование

Перечисленные ниже функции позволяют рисовать на экране различные фигуры и текст.

Для указания цвета используется его числовой код. Код можно записать в виде шестнадцатеричного числа, например: 0xFF0000AA — это полупрозрачный красный (также как #FF0000 в формате web/CSS3, только с добавлением двух цифр альфа-канала в конце). Однако проще всего получить код используя константы COLOR_*, например:

COLOR_WHITE — белый,
COLOR_TRANSPARENT — прозрачный,
COLOR_RED — красный,
COLOR_GREEN — зелёный,
COLOR_BLUE — синий и т. д., все наименования заглавными буквами в соответствии с именами цветов в CSS3.

Также вам помогут вычислить код цвета вспомогательные функции: colorByName, colorByRGB, colorByHSV, colorByYUV, а также их аналоги с альфа-каналом: colorWithAlpha, colorByNameA, colorByRGBA, colorByHSVA, colorByYUVA.

Вы можете также провести и обратную операцию — извлечь данные отдельных цветовых каналов из кода цвета, см. функции: colorGetRed, colorGetGreen, colorGetBlue, colorGetAlpha, colorGetHue, colorGetSaturation, colorGetValue, colorGetYLuminance, colorGetUChromanance, colorGetVChromanance.

Для рисования линий и многоугольников используются функции moveTo, lineTo, closePath, strokePath. При этом функции stroke и fill задают цвет линий и заливки. Функция strokeWidth задаёт толщину линий. Вот пример рисования красного треугольника с чёрным контуром:

fill(COLOR_RED);
stroke(COLOR_BLACK);
strokeWidth(10);
moveTo(100, 300);
lineTo(300, 300);
lineTo(50, 200);
closePath();

Также существуют отдельные функции для рисования точек (point), линий (line), прямоугольников (rect), правильных многоугольников (regularPolygon), эллипсов (ellipse) и дуг окружности (arc), смотрите описания функций ниже.

Для очистки экрана используйте функцию clear. Функция background задаёт цвет фона — функция clear закрасит все пиксели именно этим цветом. Обратите внимание, что перед рисованием очередного кадра картинка полностью затирается цветом фона. Если вам необходимо сохранять картинку, то вам либо придётся повторить все операции рисования выполненные ранее или обратиться к разделам «Буфер кадра» и «Текстуры и анимация», чтобы узнать, как можно рисовать не на экран, а в текстуру.

Для рисования текста см. раздел «Шрифты и текст».

Трансформации и прочие преобразования

Перед рисованием вы можете сместить, повернуть или растянуть выводимое изображение при помощи функций соответственно: translate, rotate и scale. Таким образом вы можете как бы изменить позицию камеры. Отменить все вышеуказанные трансформации можно вызвав функцию noTransform. Указанные функции меняют текущую матрицу OpenGL, если вы знакомы с OpenGL, то можете менять матрицы напрямую — на работу Helianthus это не повлияет.

Также вы можете ограничить область рисования задав прямоугольник отсечения — cliprect.

Также обратите внимание на функции saveState и restoreState. Они позволяют соответственно сохранить действующие в данный момент преобразование и затем вернуться к сохранённому состоянию.

Функция resetState отменяет все преобразования.

Фукнции saveState, restoreState и resetState затрагивают также выбранный шрифт (см. textFont), выбранный буфер кадра (см. target), матрицу проекции (см. projectionByVireport) и координаты области рисования (см. viewportByFramebuffer, viewportByWindow).

Взаимодействие с OpenGL

Helianthus использует библиотеку OpenGL для рисования. Вы тоже можете использовать функции OpenGL в своих программах. Helianthus спроектирована так чтобы минимально влиять на состояние OpenGL, так чтобы вы могли полноценно использовать все функции библиотеки OpenGL, если вы того захотите. Например, если вы вызвали функцию translate, то изменится только текущая матрица OpenGL, обычно, это матрица модели.

Вы можете также использовать рисование в 3D, в этом случае, если вы обратитесь к 2D функциям Helianthus — они будут выполнены в плоскости XY и координата Z будет принята равной нулю.

Функции:

unsigned int colorWithAlpha(unsigned int colorCode, double a);

Функция добавляет прозрачность (alpha) к цвету с указанным кодом. значения альфа-канала из цвета (из colorCode) умножается на заданное значение альфа (a). Возвращает код для полученного цвета.

Параметры:

colorCode — код цвета;
a — альфа-канал, степень непрозрачности от 0 до 1, где 0 — полностью прозрачный, 1 — полностью непрозрачный.

unsigned int colorByName(const char *colorName);

Функция генерирует код цвета по его текстовому наименованию в соответствии с CSS3.

Вот примеры наименований:
    "transparent" — прозрачный,
    "black" — чёрный,
    "white" — белый,
    "gray" — серый,
    "red" — красный,
    "green" — зелёный,
    "blue" — синий,
    "yellow" — жёлтый,
    "brown" — коричневый.

Также поддерживаются цвета в кодировка #RRGGBB или #RRGGBBAA:
    #000000 — чёрный;
    #ff0000 — красный;
    #0000ff — синий;
    #00ff00aa — зелёный полупрозрачный.

Параметры:

colorName — текстовое наименование цвета.

unsigned int colorByNameA(const char *colorName, double a);

Генерирует код цвета по его текстовому наименованию с применением прозрачности (alpha). См. также colorByName, colorWithAlpha. Если в текстовом наименовании уже заключён цвет с прозрачностью (alpha) то значения альфа-канала будут перемножены.

Параметры:

colorName — текстовое наименование цвета;
a — альфа-канал, степень непрозрачности от 0 до 1, где 0 — полностью прозрачный, 1 — полностью непрозрачный.

unsigned int colorByRGB(double r, double g, double b);

Генерирует код цвета по трём цветовым составляющим — красный, зелёный, синий. Генерируется полностью непрозрачный цвет (альфа-канал равен 1). См. также colorByRGBA.

Параметры:

r — красная составляющая, от 0 до 1;
g — зелёная составляющая, от 0 до 1;
b — синяя составляющая, от 0 до 1.

unsigned int colorByRGBA(double r, double g, double b, double a);

Генерирует код цвета по трём цветовым составляющим — красный, зелёный, синий — и прозрачности — альфа-канал. См. также colorByRGB, colorWithAlpha.

Параметры:

r — красная составляющая, от 0 до 1;
g — зелёная составляющая, от 0 до 1;
b — синяя составляющая, от 0 до 1;
a — альфа-канал, степень непрозрачности от 0 до 1, где 0 — полностью прозрачный, 1 — полностью непрозрачный.

unsigned int colorByHSV(double h, double s, double v);

Генерирует код цвета по трём составляющим в системе HSV — оттенок (hue), цветность (saturation), яркость (value). Генерируется полностью непрозрачный цвет (альфа-канал равен 1). См. также colorByHSVA.

Параметры:

h — оттенок (hue) в градусах на цветовом круге, обычно от 0 до 360;
s — цветность (saturation), от 0 до 1;
v — яркость, от 0 до 1.

unsigned int colorByHSVA(double h, double s, double v, double a);

Генерирует код цвета по трём составляющим в системе HSV — оттенок (hue), цветность (saturation), яркость (value) — и прозрачности (alpha). См. также colorByHSV, colorWithAlpha.

Параметры:

h — оттенок (hue) в градусах на цветовом круге, обычно от 0 до 360;
s — цветность (saturation), от 0 до 1;
v — яркость, от 0 до 1;
a — альфа-канал, степень непрозрачности от 0 до 1, где 0 — полностью прозрачный, 1 — полностью непрозрачный.

unsigned int colorByYUV(double y, double u, double v);

Генерирует код цвета по трём составляющим в системе YUV. Генерируется полностью непрозрачный цвет (альфа-канал равен 1). См. также colorByYUVA.

Параметры:

y — яркость, от 0 до 1;
u — цветоразностный компонент U, от -1 до 1;
v — цветоразностный компонент V, от -1 до 1.

unsigned int colorByYUVA(double y, double u, double v, double a);

Генерирует код цвета по трём составляющим в системе YUV и прозрачности. См. также colorByYUV, colorWithAlpha.

Параметры:

y — яркость, от 0 до 1;
u — цветоразностный компонент U, от -1 до 1;
v — цветоразностный компонент V, от -1 до 1;
a — альфа-канал, степень непрозрачности от 0 до 1, где 0 — полностью прозрачный, 1 — полностью непрозрачный.

double colorGetRed(unsigned int colorCode);

Возвращает красную составляющую цвета. См. также colorByRGBA.

double colorGetGreen(unsigned int colorCode);

Возвращает зелёную составляющую цвета. См. также colorByRGBA.

double colorGetBlue(unsigned int colorCode);

Возвращает синюю составляющую цвета. См. также colorByRGBA.

double colorGetAlpha(unsigned int colorCode);

Возвращает степень непрозрачности цвета — альфа-канал. См. также colorByRGBA.

double colorGetHue(unsigned int colorCode);

Возвращает цветовой оттенок в градусах на цветовом круге, от 0 до 360 в системе HSV. См. также colorByHSV.

double colorGetSaturation(unsigned int colorCode);

Возвращает цветность (цветовую насыщенность) для выбранного цвета в системе HSV. См. также colorByHSV.

double colorGetValue(unsigned int colorCode);

Возвращает яркость для выбранного цвета в системе HSV. См. также colorByHSV.

double colorGetYLuminance(unsigned int colorCode);

Возвращает яркость для выбранного цвета в системе YUV. См. также colorByYUV.

double colorGetUChromanance(unsigned int colorCode);

Возвращает цветоразностный компонент U для выбранного цвета в системе YUV. См. также colorByYUV.

double colorGetVChromanance(unsigned int colorCode);

Возвращает цветоразностный компонент V для выбранного цвета в системе YUV. См. также colorByYUV.

void background(unsigned int colorCode);

Установить цвет фона. Начиная со следующего все кадры будут рисоваться на выбранном фоне. Также влияет на поведение функции clear.

Параметры:

colorCode — код цвета.

void clear();

Заполняет все пиксели цветом фона. См. также background.

void fill(unsigned int colorCode);

Установить цвет заливки. После вызова этой функции все фигуры будут заполняться выбранным цветом. См. также stroke, noFill и fillTexture.

Параметры:

colorCode — код цвета.

void fillTexture(Animation animation, double x, double y, double width, diuble height, int fixed);

Установить заливку текстурой. После вызова этой функции все фигуры будут заполняться выбранной текстурой. Для заливки текстурой определяется базовый прямоугольник (по координатам x, y, width, height) в который будет смасштабировано изображение текстуры. Если текстура повторяющаяся, то её копии будут распространяться и за пределами базового прямоугольника. При помощи параметра fixed вы можете зафиксировать базовый прямоугольник текстуры в текущих координатах так, что на них в не будут влиять последующие трансформации перемещения (translate), вращения (rotate) и масштабирования (scale и zoom). См. также fill, noFill и раздел «Текстуры и анимация».

Параметры:

animation — анимированная или статическая текстура;
x, y — координаты верхнего левого угла базового прямоугольника текстуры;
width — ширина базового прямоугольника текстуры;
height — ширина базового прямоугольника текстуры;
fixed — если TRUE (1 или любое другое число кроме 0), то фиксирует прямоугольник текстуры в текущих координатах — операции трансформации на него не влияют.

void noFill();

Полностью отключить заливку фигур. После вызова этой функции все фигуры будут рисоваться без заполнения. См. также noFillColor, noFillTexture, fill, fillTexture, saveState и restoreState.

void noFillColor();

Установить прозрачный цвет заливки фигур. После вызова этой функции все фигуры будут рисоваться без заполнения. Однако, выбранная текстура будет сохранена в памяти и будет использована вновь при последующем включении непрозрачного цвета заливки. См. также noFill, fill, saveState и restoreState.

void noFillTexture();

Отключить заливку фигур текстурой. См. также noFill, fillTexture, saveState и restoreState.

void stroke(unsigned int colorCode);

Установить цвет контура. После вызова этой функции все фигуры будут рисоваться с контуром выбранного цвета. Также эта функция задаёт цвет рисования текста. См. также fill, noStroke. и раздел «Шрифты и текст».

Параметры:

colorCode — код цвета.

void strokeTexture(Animation animation, double x, double y, double width, diuble height, int fixed);

Установить заливку текстурой для контура. После вызова этой функции все фигуры будут заполняться выбранной текстурой. Для заливки текстурой определяется базовый прямоугольник (по координатам x, y, width, height) в который будет смасштабировано изображение текстуры. Если текстура повторяющаяся, то её копии будут распространяться и за пределами базового прямоугольника. При помощи параметра fixed вы можете зафиксировать базовый прямоугольник текстуры в текущих координатах так, что на них в не будут влиять последующие трансформации перемещения (translate), вращения (rotate) и масштабирования (scale и zoom). См. также stroke, noStroke и раздел «Текстуры и анимация».

Параметры:

void noStroke();

Отключить рисование контура. После вызова этой функции все фигуры будут рисоваться без прорисовки контура. См. также noStrokeColor, noStrokeTexture, stroke, strokeTexture, saveState и restoreState.

Важно: Так как текст рисуется цветом контура, эта функция полностью отключает вывод текста.

void noStrokeColor();

Установить прозрачный цвет рисования контуров. После вызова этой функции все фигуры будут рисоваться без контура. Однако, выбранная текстура будет сохранена в памяти и будет использована вновь при последующем включении непрозрачного цвета контура. См. также noStroke, stroke, strokeTexture, saveState и restoreState.

void noStrokeTexture();

Отключить текстурирование контуров фигур. См. также noStroke, strokeTexture, saveState и restoreState.

void enableAntialiasing();

Включить сглаживание (antialiasing). По-умолчанию включено. См. также disableAntialiasing, saveState и restoreState.

void disableAntialiasing();

Отключить сглаживание. См. также enableAntialiasing, saveState и restoreState.

void strokeWidth(double width);

Установить толщину линий и контуров. После вызова этой функции все линии и контуры будут рисоваться с заданной толщиной. Изначально толщина равна 1.

Параметры:

width — толщина линии.

void moveTo(double x, double y);

Начать рисование новой фигуры, и задать начальное положение пера. Перед запуском этой функции убедитесь что вы завершили рисование предыдущей фигуры функцией closePath или strokePath.

Параметры:

x, y — координаты в которые будет помещено перо.

void lineTo(double x, double y);

Наметить линию от текущих координат пера до заданной точки, а также перевести перо в указанною точку. Настоящая линия будет нарисована позже при помощи функции closePath или strokePath. См. также функцию moveTo.

Важно: если положение пера не было задано, то линия не намечается, вместо этого просто задаётся начальное положение пера.

void resetPath();

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

void closePath();

Завершить контур соединив начальную и конечную точки линией и нарисовать заполненную фигуру с контуром. Цвета заполнения и контура задаются функциями fill и stroke. См. также функции moveTo и lineTo. После вывода фигуры на экран положение пера и все намеченные линии забываются.

void strokePath();

Нарисовать ранее намеченные линии. В отличии от функции closePath, данная функция не соединяет начальную и конечную точки, а просто рисует только те линии которые были намечены. Цвет контура задаётся функцией stroke, а вот заполнение цветом не производится. После вывода намеченных линий на экран, их расположение и позиция пера забываются.

void rect(double x, double y, double width, double height);

Нарисовать прямоугольник. Цвета заполнения и контура задаются заранее функциями fill и stroke. См. также rectRounded, rectTextured.

Параметры:

x, y — координаты левого верхнего угла прямоугольника;
width — ширина прямоугольника;
height — высота прямоугольника.

void rectRounded(double x, double y, double width, double height, double radius);

Нарисовать прямоугольник со скруглёнными углами. Цвета заполнения и контура задаются заранее функциями fill и stroke. См. также rect, rectTextured.

Параметры:

x, y — координаты левого верхнего угла прямоугольника;
width — ширина прямоугольника;
height — высота прямоугольника;
radius — радиус скругления углов.

void rectTextured(Animation animation, double x, double y, double width, double height);

Нарисовать прямоугольник и заполнить его выбранной текстурой. Цвет контура задаётся заранее функцией stroke. См. также функции rect, fillTexture, strokeTexture и раздел «Текстуры и анимация».

Параметры:

animation — анимированная или статическая текстура;
x, y — координаты левого верхнего угла прямоугольника;
width — ширина прямоугольника;
height — высота прямоугольника.

void ellipse(double x, double y, double width, double height);

Нарисовать эллипс. Эллипс рисуется таким чтобы от вписался в ограничивающий прямоугольник (см. функцию rect). Следовательно для того чтобы нарисовать окружность нужно передать одинаковую ширину и высоту ограничивающего прямоугольника. Цвета заполнения и контура задаются заранее функциями fill и stroke. См. также circle.

Параметры:

x, y — координаты левого верхнего угла ограничивающего прямоугольника;
width — ширина ограничивающего прямоугольника;
height — высота ограничивающего прямоугольника.

void circle(double x, double y, double radius);

Нарисовать круг заданного радиуса с центром в указанной точке. Цвета заполнения и контура задаются заранее функциями fill и stroke. См. также ellipse.

Параметры:

x, y — координаты центра;
radius — радиус.

void arc(double x, double y, double w, double h, double start, double stop);

Нарисовать дугу эллипса заданного ограничивающим прямоугольником. Дуга задаётся значением начального и конечного угла. Цвет линии задаётся функцией stroke.

Параметры:

void arcPath(double x, double y, double w, double h, double start, double stop);

Наметить дугу эллипса заданного ограничивающим прямоугольником так как если бы она рисовалась функциями moveTo и lineTo. Дуга задаётся значением начального и конечного угла. Окончательное рисование будет выполнено после вызова функции closePath или strokePath.

Параметры:

void line(double x1, double y1, double x2, double y2);

Провести прямую линию от первой указанной точки до второй. Цвет линии задаётся функцией stroke.

Параметры:

x1, y1 — координаты первой точки;
x2, y2 — координаты второй точки.

void point(double x, double y);

Нарисовать точку в указанных координатах. Цвет задаётся функцией stroke. Диаметр точки задаётся функцией strokeWidth.

Параметры:

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

void regularPolygon(double x, double y, int sides, double radius, double angle);

Нарисовать правильный многоугольник с заданным радиусом и с центром в указанной точке. Цвета заполнения и контура задаются функциями fill и stroke.

Параметры:

x, y — координаты центра многоугольника;
sides — количество сторон;
radius — радиус многоугольника (радиус описанной окружности);
angle — угол поворота многоугольника.

void translate(double x, double y);

Задать смещение системы координат. После вызова этой функции все объекты будут рисоваться с заданным смещением. Смещение производится относительно действующей в данный момент системы координат. См. также rotate, scale и noTransform.

void rotate(double angle);

Повернуть текущую систему координат на заданный угол (angle) в градусах. См. также translate, scale и noTransform.

void zoom(double z);

Смасштабировать текущую систему координат на заданный коэффициент (z). Эквивалентно вызову scale(z, z). См. также translate, rotate, scale и noTransform.

void scale(double x, double y);

Смасштабировать (растянуть) текущую систему координат на заданные коэффициенты по осям x и y. См. также translate, rotate и noTransform.

void noTransform();

Отменяет все преобразования системы координат заданные функциями translate, rotate, scale и zoom. См. также saveState и restoreState.

void clipRect(double x, double y, double width, double height);

Задаёт прямоугольник отсечения. Все последующие операции рисования будут выполнены только внутри заданного прямоугольника. Всё что было нарисовано ранее за его пределами останется неизменным. Повторный вызов функции заменяет (а не дополняет) ранее заданную область отсечения. Если вы знакомы с OpenGL, вам будет полезно знать, что данная функция просто задаёт четыре плоскости отсечения (glClipPlane). Область отсечения применяется со всеми действующими в момент вызова функции преобразованиями системы координат, таким образом она может быть на экране не прямоугольной, а, например, иметь форму параллелограмма. См. также noClip.

void noClip();

Отменяет область отсечения заданную функцией clipRect. См. также saveState и restoreState.

void resetState();

Сбрасывает состояние инструментов рисования к их начальным значениям. Эквивалентно вызову resetStateEx(STATE_ALL). См. также saveState и restoreState.

void resetStateEx(unsigned int flags);

Сбрасывает выбранные состояния инструментов рисования к их начальным значениям. Аргумент flags определяет перечень состояний которые необходимо сбросить. Значение для него можно вычислить объединив операцией побитового «или» (вертикальная черта: |) несколько флагов из следующего списка:

STATE_FILL_COLOR	цвет заполнения, см. fill
STATE_FILL_TEXTURE	текстура заполнения, см. fillTexture
STATE_STROKE_COLOR	цвет обводки, см. stroke
STATE_STROKE_TEXTURE	текстура обводки, см. strokeTexture
STATE_STROKE_WIDTH	толщина обводки, см. strokeWidth
STATE_TEXT_ALIGN	расположение текста, см. textAlign
STATE_TEXT_SIZE	размер шрифта, см. textSize
STATE_TEXT_FONT	шрифт, см. textFont
STATE_TARGET_FRAMEBUFFER	выбранный буфер кадра, см. target
STATE_TARGET_VIEWPORT	текущая область рисования, см. viewportByFramebuffer, viewportByWindow
STATE_TARGET_PROJECTION	текущая матрица проекции, см. projectionByViewport
STATE_BACKGROUND	цвет очистки экрана (цвет фона), см. baclground
STATE_TRANSFORM	преобразования системы координат, см. translate, rotate, scale, zoom
STATE_CLIP	область отсечения, см. clipRect
STATE_ANTIALIASING	сглаживание, см. enableAntialiasing
STATE_FILL	объединение флагов STATE_FILL_*
STATE_STROKE	объединение флагов STATE_STROKE_*
STATE_TEXT	объединение флагов STATE_TEXT_*
STATE_TARGET	объединение флагов STATE_TARGET_*
STATE_ALL	объединение всех флагов

void saveState();

Запоминает состояние всех инструментов рисования для того чтобы впоследствии к ним вернуться вызвав функцию restoreState. Функция может быть вызвана несколько раз чтобы запомнить несколько состояний, при этом позже необходимо будет выполнить соответствующее количество вызовов функции restoreState. Обращение в данной функции эквивалентно вызову saveStateEx(STATE_ALL). См. также resetState.

void saveStateEx(unsigned int flags);

Запоминает выбранные состояния инструментов рисования для того чтобы впоследствии к ним вернуться вызвав функцию restoreState. Функция может быть вызвана несколько раз, при этом позже необходимо будет выполнить соответствующее количество вызовов функции restoreState. Аргумент flags определяет перечень состояний которые необходимо запомнить. Значение для него можно вычислить объединив операцией побитового «или» (вертикальная черта: |) несколько флагов из списка представленного в описании функции resetState.
См. также saveState.

void restoreState();

Восстанавливает состояния инструментов рисования ранее сохранённые функцией saveState или saveStateEx. Если функция saveState (или saveStateEx) была вызвана несколько раз, то чтобы вернуться к первоначальному состоянию нужно вызвать restoreState аналогичное количество раз. См. также resetState.

Важно: следите за тем чтобы количество сохранений (saveState или saveStateEx) всегда совпадало с количеством восстановлений (restoreState).