pixie/README.md

336 lines
7.4 KiB
Markdown
Raw Normal View History

2021-02-25 16:39:23 +00:00
<img src="docs/banner.png">
2020-11-21 05:09:52 +00:00
# Pixie - A full-featured 2D graphics library for Nim
2020-11-20 02:41:32 +00:00
2020-11-27 21:51:40 +00:00
Pixie is a 2D graphics library similar to [Cairo](https://www.cairographics.org/) and [Skia](https://skia.org) written (almost) entirely in Nim.
2020-11-20 17:13:53 +00:00
2021-02-26 00:40:27 +00:00
This library is being actively developed and we'd be happy for you to use it.
2020-11-21 05:09:52 +00:00
2021-02-14 04:14:16 +00:00
`nimble install pixie`
2021-06-03 04:58:39 +00:00
![Github Actions](https://github.com/treeform/pixie/workflows/Github%20Actions/badge.svg)
2021-02-14 04:14:16 +00:00
Features:
2021-05-11 21:47:09 +00:00
* Typesetting and rasterizing text, including styled rich text via spans.
2021-02-26 00:40:27 +00:00
* Drawing paths, shapes and curves with even-odd and non-zero windings.
* Pixel-perfect AA quality.
* Supported file formats are PNG, BMP, JPG, SVG + more in development.
2021-02-14 04:14:16 +00:00
* Strokes with joins and caps.
* Shadows, glows and blurs.
* Complex masking: Subtract, Intersect, Exclude.
* Complex blends: Darken, Multiply, Color Dodge, Hue, Luminosity... etc.
2021-05-11 22:36:14 +00:00
* Many operations are SIMD accelerated.
2021-02-25 16:39:23 +00:00
2021-02-26 00:40:27 +00:00
### Documentation
2021-05-13 05:04:59 +00:00
API reference: https://nimdocs.com/treeform/pixie/pixie.html
2021-02-25 16:39:23 +00:00
2021-05-11 21:47:09 +00:00
### Image file formats
2021-02-25 16:39:23 +00:00
Format | Read | Write |
------------- | ------------- | ------------- |
PNG | ✅ | ✅ |
JPEG | ✅ | |
2021-02-26 00:40:27 +00:00
BMP | ✅ | ✅ |
2021-03-01 16:53:15 +00:00
GIF | ✅ | |
2021-02-25 16:39:23 +00:00
SVG | ✅ | |
2021-05-11 22:34:56 +00:00
### Font file formats
Format | Read
------------- | -------------
TTF | ✅
OTF | ✅
SVG | ✅
2021-02-26 00:40:27 +00:00
### Joins and caps
2021-02-25 16:39:23 +00:00
2021-02-26 00:40:27 +00:00
Supported Caps:
2021-02-25 16:39:23 +00:00
* Butt
* Round
* Square
2021-02-26 00:40:27 +00:00
Supported Joins:
* Miter (with miter angle limit)
2021-02-25 16:39:23 +00:00
* Bevel
* Round
2021-02-26 00:40:27 +00:00
### Blending & masking
2021-02-25 16:39:23 +00:00
Supported Blend Modes:
* Normal
* Darken
* Multiply
* ColorBurn
* Lighten
* Screen
* Color Dodge
* Overlay
* Soft Light
* Hard Light
* Difference
* Exclusion
* Hue
* Saturation
* Color
* Luminosity
Supported Mask Modes:
* Mask
* Overwrite
* Subtract Mask
* Intersect Mask
* Exclude Mask
### SVG style paths:
Format | Supported | Description |
------------- | ------------- | --------------------- |
2021-05-24 17:51:17 +00:00
M m | ✅ | move to |
L l | ✅ | line to |
h h | ✅ | horizontal line to |
V v | ✅ | vertical line to |
C c S s | ✅ | cublic to |
Q q T t | ✅ | quadratic to |
A a | ✅ | arc to |
2021-02-25 16:39:23 +00:00
z | ✅ | close path |
### Realtime Examples
Here are some examples of using Pixie for realtime rendering with some popular windowing libraries:
* [examples/realtime_glfw.nim](examples/realtime_glfw.nim)
* [examples/realtime_glut.nim](examples/realtime_glut.nim)
* [examples/realtime_sdl.nim](examples/realtime_sdl.nim)
* [examples/realtime_win32.nim](examples/realtime_win32.nim)
2021-02-14 04:14:16 +00:00
2020-11-21 05:09:52 +00:00
## Testing
`nimble test`
2020-12-01 17:49:41 +00:00
## Examples
2021-05-11 21:35:44 +00:00
### Text
[examples/text.nim](examples/text.nim)
```nim
var font = readFont("tests/fonts/Roboto-Regular_1.ttf")
font.size = 20
let text = "Typesetting is the arrangement and composition of text in graphic design and publishing in both digital and traditional medias."
image.fillText(font.typeset(text, bounds = vec2(180, 180)), vec2(10, 10))
```
![example output](examples/text.png)
### Text spans
[examples/text_spans.nim](examples/text_spans.nim)
```nim
let font = readFont("tests/fonts/Ubuntu-Regular_1.ttf")
2021-05-11 21:59:53 +00:00
proc style(font: Font, size: float32, color: ColorRGBA): Font =
result = font
result.size = size
result.paint.color = color
2021-05-11 21:35:44 +00:00
let spans = @[
2021-05-11 21:59:53 +00:00
newSpan("verb [with object] ", font.style(12, rgba(200, 200, 200, 255))),
newSpan("strallow\n", font.style(36, rgba(0, 0, 0, 255))),
newSpan("\nstral·low\n", font.style(13, rgba(0, 127, 244, 255))),
2021-05-11 22:46:48 +00:00
newSpan("\n1. free (something) from restrictive restrictions \"the regulations are intended to strallow changes in public policy\" ",
font.style(14, rgba(80, 80, 80, 255)))
2021-05-11 21:35:44 +00:00
]
image.fillText(typeset(spans, bounds = vec2(180, 180)), vec2(10, 10))
```
![example output](examples/text_spans.png)
2021-02-14 04:45:27 +00:00
### Square
[examples/square.nim](examples/square.nim)
2020-12-04 16:32:03 +00:00
```nim
let ctx = newContext(image)
ctx.fillStyle = rgba(255, 0, 0, 255)
2021-02-18 19:55:26 +00:00
let
pos = vec2(50, 50)
wh = vec2(100, 100)
2021-01-29 20:17:24 +00:00
ctx.fillRect(rect(pos, wh))
2020-12-04 16:32:03 +00:00
```
2021-02-14 04:45:27 +00:00
![example output](examples/square.png)
2020-12-04 16:32:03 +00:00
2021-02-18 18:14:55 +00:00
### Line
[examples/line.nim](examples/line.nim)
```nim
let ctx = newContext(image)
ctx.strokeStyle = "#FF5C00"
ctx.lineWidth = 10
2021-02-18 19:55:26 +00:00
let
start = vec2(25, 25)
stop = vec2(175, 175)
ctx.strokeSegment(segment(start, stop))
2021-02-18 18:14:55 +00:00
```
![example output](examples/line.png)
2021-02-18 22:30:47 +00:00
### Rounded rectangle
[examples/rounded_rectangle.nim](examples/rounded_rectangle.nim)
```nim
let ctx = newContext(image)
ctx.fillStyle = rgba(0, 255, 0, 255)
2021-02-18 22:30:47 +00:00
let
pos = vec2(50, 50)
wh = vec2(100, 100)
r = 25.0
ctx.fillRoundedRect(rect(pos, wh), r)
2021-02-18 22:30:47 +00:00
```
![example output](examples/rounded_rectangle.png)
2021-02-14 04:45:27 +00:00
### Heart
[examples/heart.nim](examples/heart.nim)
```nim
image.fillPath(
"""
M 20 60
A 40 40 90 0 1 100 60
A 40 40 90 0 1 180 60
Q 180 120 100 180
Q 20 120 20 60
z
""",
parseHtmlColor("#FC427B").rgba
)
```
![example output](examples/heart.png)
2021-02-25 16:51:09 +00:00
### Masking
[examples/masking.nim](examples/masking.nim)
```nim
let ctx = newContext(lines)
ctx.strokeStyle = "#F8D1DD"
ctx.lineWidth = 30
ctx.strokeSegment(segment(vec2(25, 25), vec2(175, 175)))
ctx.strokeSegment(segment(vec2(25, 175), vec2(175, 25)))
2021-02-25 16:51:09 +00:00
mask.fillPath(
"""
M 20 60
A 40 40 90 0 1 100 60
A 40 40 90 0 1 180 60
Q 180 120 100 180
Q 20 120 20 60
z
"""
)
lines.draw(mask)
image.draw(lines)
```
![example output](examples/masking.png)
2021-02-25 16:57:49 +00:00
### Gradient
[examples/gradient.nim](examples/gradient.nim)
```nim
2021-02-25 18:05:46 +00:00
let paint = Paint(
kind: pkGradientRadial,
gradientHandlePositions: @[
vec2(100, 100),
vec2(200, 100),
vec2(100, 200)
],
gradientStops: @[
2021-02-26 01:05:29 +00:00
ColorStop(color: rgba(255, 0, 0, 255), position: 0),
ColorStop(color: rgba(255, 0, 0, 40), position: 1.0),
2021-02-25 18:05:46 +00:00
]
)
2021-02-25 16:57:49 +00:00
image.fillPath(
"""
M 20 60
A 40 40 90 0 1 100 60
A 40 40 90 0 1 180 60
Q 180 120 100 180
Q 20 120 20 60
z
""",
2021-02-25 18:05:46 +00:00
paint
2021-02-25 16:57:49 +00:00
)
```
![example output](examples/gradient.png)
### Image tiled
[examples/image_tiled.nim](examples/image_tiled.nim)
```nim
var path: Path
path.polygon(
vec2(100, 100),
70,
sides = 8
)
image.fillPath(
path,
Paint(
2021-02-25 18:05:46 +00:00
kind: pkImageTiled,
2021-02-25 16:57:49 +00:00
image: readImage("tests/images/png/baboon.png"),
2021-02-25 18:05:46 +00:00
imageMat: scale(vec2(0.08, 0.08))
2021-02-25 16:57:49 +00:00
)
)
```
![example output](examples/image_tiled.png)
2021-02-14 04:45:27 +00:00
### Shadow
[examples/shadow.nim](examples/shadow.nim)
2020-12-01 17:49:41 +00:00
```nim
2021-02-18 22:40:35 +00:00
let polygonImage = newImage(200, 200)
let ctx = newContext(polygonImage)
ctx.fillStyle = rgba(255, 255, 255, 255)
ctx.fillPolygon(
2021-02-18 22:40:35 +00:00
vec2(100, 100),
70,
sides = 8
2021-02-18 22:40:35 +00:00
)
2021-02-14 04:45:27 +00:00
2021-02-19 18:04:27 +00:00
let shadow = polygonImage.shadow(
2021-02-14 04:45:27 +00:00
offset = vec2(2, 2),
spread = 2,
blur = 10,
color = rgba(0, 0, 0, 200)
2021-02-19 18:04:27 +00:00
)
image.draw(shadow)
2021-02-18 22:40:35 +00:00
image.draw(polygonImage)
2020-12-01 17:49:41 +00:00
```
2021-02-14 04:45:27 +00:00
![example output](examples/shadow.png)
### Blur
[examples/blur.nim](examples/blur.nim)
```nim
let mask = newMask(200, 200)
2021-02-19 18:04:27 +00:00
mask.fillPolygon(vec2(100, 100), 70, sides = 6)
2021-02-14 04:45:27 +00:00
blur.blur(20)
blur.draw(mask, blendMode = bmMask)
image.draw(trees)
image.draw(blur)
```
![example output](examples/blur.png)
2020-12-04 17:41:28 +00:00
### Tiger
[examples/tiger.nim](examples/tiger.nim)
```nim
2021-01-29 20:17:24 +00:00
let tiger = readImage("examples/data/tiger.svg")
image.draw(
tiger,
translate(vec2(100, 100)) *
scale(vec2(0.2, 0.2)) *
translate(vec2(-450, -450))
)
```
![example output](examples/tiger.png)