From f4cc8ce7a8712e2e840b0c120a3f86eadb665626 Mon Sep 17 00:00:00 2001 From: pommicket Date: Mon, 28 Aug 2023 11:50:57 -0400 Subject: add, sub, div, more work on the guide --- guide-src/development/index.html | 27 +++++++++ guide-src/development/js-features.html | 22 +++++++ guide-src/ex-multiply-add.png | Bin 0 -> 6404 bytes guide-src/ex-multiply-vector.png | Bin 0 -> 3176 bytes guide-src/ex-multiply.png | Bin 0 -> 3410 bytes guide-src/ex-posx.png | Bin 0 -> 2804 bytes guide-src/ex-vector.png | Bin 0 -> 2609 bytes guide-src/index.html | 69 +++++++++++++++++++++ guide-src/make.py | 108 +++++++++++++++++++++++++++++++++ guide-src/outline.txt | 7 +++ guide-src/output-multiply-add.png | Bin 0 -> 1203 bytes guide-src/output-multiply-vector.png | Bin 0 -> 1124 bytes guide-src/output-multiply.png | Bin 0 -> 1059 bytes guide-src/widget-inputs/builtins.html | 3 + guide-src/widget-inputs/constants.html | 3 + guide-src/widget-inputs/vectors.html | 3 + 16 files changed, 242 insertions(+) create mode 100644 guide-src/development/index.html create mode 100644 guide-src/development/js-features.html create mode 100644 guide-src/ex-multiply-add.png create mode 100644 guide-src/ex-multiply-vector.png create mode 100644 guide-src/ex-multiply.png create mode 100644 guide-src/ex-posx.png create mode 100644 guide-src/ex-vector.png create mode 100644 guide-src/index.html create mode 100644 guide-src/make.py create mode 100644 guide-src/outline.txt create mode 100644 guide-src/output-multiply-add.png create mode 100644 guide-src/output-multiply-vector.png create mode 100644 guide-src/output-multiply.png create mode 100644 guide-src/widget-inputs/builtins.html create mode 100644 guide-src/widget-inputs/constants.html create mode 100644 guide-src/widget-inputs/vectors.html (limited to 'guide-src') diff --git a/guide-src/development/index.html b/guide-src/development/index.html new file mode 100644 index 0000000..717ff6d --- /dev/null +++ b/guide-src/development/index.html @@ -0,0 +1,27 @@ +--- getting started + +

+note: this section is only for people who want to contribute to pugl itself. +

+ +

+after cloning the repository, +make sure you run +

npm install
+ln -s ../../pre-commit .git/hooks/

+ +this ensures that your changes are prettified & linted. +

+ +

+the main files of interest are index.html and pugl.js, which has all +the JavaScript for pugl (hopefully it doesn't become too unmanageable to have just one file). +

+ +

contributing to the guide

+the guide is automatically generated from the files in guide-src/ by guide-src/make.py +(you can also just run make to generate it), which is a simple script whose main purpose is adding +a sidebar to all of the guide pages. any PNG files are automatically copied from guide-src/ to guide/. +when you add or remove pages from the guide, you'll need to edit guide-src/outline.txt. +

diff --git a/guide-src/development/js-features.html b/guide-src/development/js-features.html new file mode 100644 index 0000000..ea8ac97 --- /dev/null +++ b/guide-src/development/js-features.html @@ -0,0 +1,22 @@ +--- modern JavaScript features + +

+pugl has no dependencies, and i'd like to keep it that way. +

+ +

+i've been pretty liberal about using modern javascript; +even though this could in theory run on IE it doesn't +(in particular it's very nice to have template literals). +that said, try to only use features that have at least as much +support as webgl2 (i.e. >94%). +

+ +

+we use webgl2 because: +

having non-constant loops in shaders is nice
there aren't that many browsers that support webgl and ES6 but not webgl2 (looking at caniuse.com, they probably + make up around 2% of browser usage)

diff --git a/guide-src/ex-multiply-add.png b/guide-src/ex-multiply-add.png new file mode 100644 index 0000000..1b826ad Binary files /dev/null and b/guide-src/ex-multiply-add.png differ diff --git a/guide-src/ex-multiply-vector.png b/guide-src/ex-multiply-vector.png new file mode 100644 index 0000000..e25ea1d Binary files /dev/null and b/guide-src/ex-multiply-vector.png differ diff --git a/guide-src/ex-multiply.png b/guide-src/ex-multiply.png new file mode 100644 index 0000000..1f3260d Binary files /dev/null and b/guide-src/ex-multiply.png differ diff --git a/guide-src/ex-posx.png b/guide-src/ex-posx.png new file mode 100644 index 0000000..52c4375 Binary files /dev/null and b/guide-src/ex-posx.png differ diff --git a/guide-src/ex-vector.png b/guide-src/ex-vector.png new file mode 100644 index 0000000..681c6fe Binary files /dev/null and b/guide-src/ex-vector.png differ diff --git a/guide-src/index.html b/guide-src/index.html new file mode 100644 index 0000000..7b5de8f --- /dev/null +++ b/guide-src/index.html @@ -0,0 +1,69 @@ +--- guide + +

your first pugl

+when you load up pugl for the first time, you should be greeted with a "Buffer" widget. +try changing its "input" value to .pos.x. +

+you should see a nice gradient like this: +here the color of each pixel is directly determined by its x coordinate. +specifically: .pos.x is −1 at the left side of the screen and +1 at the right side of the screen. +since the "Buffer" widget's title is in yellow, +the pixel values will be drawn from it. 0 (or anything below 0) is black and 1 (or anything above 1) is white, +so we see a gradient from black to white starting from the center of the screen. +

+now let's try something a little more interesting. try adding a "Multiply" widget (by searching for it or +selecting it from the "math" section). set the "a" input to .pos.x and the "b" input to +.pos.y. then click on the "Multiply" text to set it as the active widget. +

+you should now see a more interesting pattern where two of the corners of the screen are +white, and the other two corners are black:

+ +

vectors

+ +

+well, black and white is pretty boring. let's try making some colors! +one of the nice things about shaders is that they're very good at dealing with vectors. +there's a lot of mathematical theory behind vectors, but for simple shader programming all that really matters is that a vector is a list of numbers (called components), +& in shaders you basically only deal with vectors with 2 to 4 components (labelled x, y, z, w). +in graphics programming, colors are represented as vectors with 3 components, red, +green, and blue, which go from 0 to 1. +try putting 0,0.8,1 in a "Buffer" widget and making it active. +now the widget is outputting a vector with x=0, y=0.8, and z=1, so +you'll get a nice greenish blue color! +

+ +

+.pos is itself a vector, so you can just throw it into the Buffer input: +

+notice how the output is red on the right side of the screen (where the x component of .pos is high) +and green at the top of the screen (where the y component of .pos is high). +

+ +

+most widgets like Multiply work on both numbers and vectors. try multiplying together +.pos and .pos.x: +

+this multiplies each of the components of .pos by .pos.x. +so the top-left corner is red, because (−1, 1) × −1 = (1, −1), so the top-left pixel gets a red value of 1 and a green value of −1. +

+ +

multiple widgets

+ +

+you can use the output of one widget to specify the input of another widget using its name. +try creating an "Add" widget with inputs mul1,0 and 0,0,.pos.x (assuming +your Multiply widget from the last section was called "mul1"). +

+now the left side looks the same as before, but the right side (where .pos.x is 1) is bluer! +

+ +

putting everything together

+ +

TODO

diff --git a/guide-src/make.py b/guide-src/make.py new file mode 100644 index 0000000..058a63b --- /dev/null +++ b/guide-src/make.py @@ -0,0 +1,108 @@ +import os, html +from urllib.parse import quote +import shutil + +INPUT_DIR = 'guide-src' +OUTPUT_DIR = 'guide' +TITLE_PREFIX = '---' + +os.makedirs(OUTPUT_DIR, exist_ok=True) + +try: + for f in os.listdir(INPUT_DIR): + if f.endswith('.png'): + shutil.copyfile(INPUT_DIR + '/' + f, OUTPUT_DIR + '/' + f) + elif not '.' in f: + os.makedirs(OUTPUT_DIR + '/' + f, exist_ok=True) +except FileNotFoundError: + print('this script must be run from the root directory.') + quit() + +def readlines(path): + f = open(path) + l = f.readlines() + f.close() + return l + +class Section: + def __init__(self, path, name): + self.path = path + self.name = name + self.items = [] + + def __repr__(self): + return ''.join(['Section(path=', repr(self.path), ', name=', repr(self.name), ', items=', repr(self.items), ')']) + +outline = [l.strip() for l in readlines('{}/outline.txt'.format(INPUT_DIR)) if l.strip()] +sections = [] +for item in outline: + if item[0] == '/': + assert item.endswith('.html'), 'expected path ending in .html' + sections[-1].items.append(item[1:]) + else: + [path, name] = item.split(': ') + sections.append(Section(path, name)) + +sidebar_content = [ + ('', ''), + ('index.html', ''), +] + +for section in sections: + sidebar_content.append(('', ''.format(section.name))) + for item in section.items: + path = '{}/{}/{}'.format(INPUT_DIR, section.path, item) + file = open(path) + first_line = file.readline().strip() + file.close() + assert first_line.startswith(TITLE_PREFIX), 'file {} doesn\'t start with title prefix {}'.format(path, TITLE_PREFIX) + title = first_line[len(TITLE_PREFIX):].strip() + assert '"' not in path, 'path {} should not contain "'.format(path) + url = quote('{}/{}'.format(section.path, item)) + sidebar_content.append((section.path + '/' + item, ''.format(url, html.escape(title)))) + +def process_file(path): + count = path.count('/') + if count == 0: + guide_root = '' + elif count == 1: + guide_root = '../' + else: + assert False, 'whats goin on with ' + path + lines = readlines(INPUT_DIR + '/' + path) + assert lines[0].startswith(TITLE_PREFIX) + title = lines[0][len(TITLE_PREFIX):].strip() + contents = ''.join(lines[1:]) + sidebar = [] + for (p, item) in sidebar_content: + if p == path: + item = item.replace('class="', 'class="guide-sidebar-item-active ') + item = item.replace('', guide_root) + sidebar.append(item.replace('', guide_root)) + output = ''' + + + + pugl - {title} + + + + + + + +

+{contents} +

+ +'''.format(title=title, sidebar=''.join(sidebar), contents=contents, root=guide_root) + f = open(OUTPUT_DIR + '/' + path, 'w') + f.write(output) + f.close() + +process_file('index.html') +for section in sections: + for item in section.items: + process_file('{}/{}'.format(section.path, item)) diff --git a/guide-src/outline.txt b/guide-src/outline.txt new file mode 100644 index 0000000..d59b039 --- /dev/null +++ b/guide-src/outline.txt @@ -0,0 +1,7 @@ +widget-inputs: Widget inputs +/constants.html +/builtins.html +/vectors.html +development: Development +/index.html +/js-features.html diff --git a/guide-src/output-multiply-add.png b/guide-src/output-multiply-add.png new file mode 100644 index 0000000..6bcb4f6 Binary files /dev/null and b/guide-src/output-multiply-add.png differ diff --git a/guide-src/output-multiply-vector.png b/guide-src/output-multiply-vector.png new file mode 100644 index 0000000..f1c2da1 Binary files /dev/null and b/guide-src/output-multiply-vector.png differ diff --git a/guide-src/output-multiply.png b/guide-src/output-multiply.png new file mode 100644 index 0000000..3fb3fe6 Binary files /dev/null and b/guide-src/output-multiply.png differ diff --git a/guide-src/widget-inputs/builtins.html b/guide-src/widget-inputs/builtins.html new file mode 100644 index 0000000..6434921 --- /dev/null +++ b/guide-src/widget-inputs/builtins.html @@ -0,0 +1,3 @@ +--- Built-in values + +

TODO

diff --git a/guide-src/widget-inputs/constants.html b/guide-src/widget-inputs/constants.html new file mode 100644 index 0000000..a2a89ac --- /dev/null +++ b/guide-src/widget-inputs/constants.html @@ -0,0 +1,3 @@ +--- Constants + +

TODO

diff --git a/guide-src/widget-inputs/vectors.html b/guide-src/widget-inputs/vectors.html new file mode 100644 index 0000000..33bbea1 --- /dev/null +++ b/guide-src/widget-inputs/vectors.html @@ -0,0 +1,3 @@ +--- Vectors + +

TODO

-- cgit v1.2.3