Skip to content

Commit 73cd65d

Browse files
committed
added new text, examples, and illustrations
1 parent 2ef1b3b commit 73cd65d

File tree

9 files changed

+374
-209
lines changed

9 files changed

+374
-209
lines changed

i18n-tracking.yml

Lines changed: 60 additions & 60 deletions
Large diffs are not rendered by default.

package-lock.json

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.
76.2 KB
Loading
35.2 KB
Loading
9.06 KB
Loading

src/data/en.yml

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -370,19 +370,18 @@ learn:
370370
getting-started-in-webgl-custom-geometry-title: Creating Custom Geometry in WebGL
371371
getting-started-in-webgl-custom-geometry: Creating custom geometry in WebGL
372372
getting-started-in-webgl-custom-geometry-p1x1: >-
373-
p5.js has a number of 3D primitives that can be used to create basic shapes, like <a class="code">box()</a> or <a class="code">sphere()</a>, but p5.js
374-
is also capable of rendering complex custom geometry, either from files that are created in other 3D software
375-
(like Blender) or from code. This tutorial will walk through how to import 3D models into p5.js, as well as how
373+
p5.js has a number of basic shapes, like <a class="code">box()</a> or <a class="code">sphere()</a>, but p5.js
374+
is also capable of rendering complex custom geometry, both from 3D model files or from code. This tutorial will walk through how to import 3D models into p5.js, as well as how
376375
to create a basic geometry from scratch.
377376
getting-started-in-webgl-custom-geometry-info1x1: >-
378-
If you are new to 3D it's recommended that you check out the
377+
If you are new to 3D check out the
379378
<a href="{{root}}/learn/getting-started-in-webgl-coords-and-transform.html">
380-
Coordinates and Transformations</a> tutorial before continuing with this tutorial.
379+
Coordinates and Transformations</a> tutorial.
381380
getting-started-in-webgl-custom-geometry-toc-title: Table of Contents
382381
getting-started-in-webgl-custom-geometry-toc1: Loading 3D Models from File
383382
getting-started-in-webgl-custom-geometry-toc2: Creating Basic Procedural Geometry
384-
getting-started-in-webgl-custom-geometry-toc3: Glossary
385-
getting-started-in-webgl-custom-geometry-toc4: Conclusion
383+
getting-started-in-webgl-custom-geometry-toc3: Conclusion
384+
getting-started-in-webgl-custom-geometry-toc4: Glossary
386385
getting-started-in-webgl-custom-geometry-heading1: Loading 3D Models from File
387386
getting-started-in-webgl-custom-geometry-p2x1: >-
388387
Custom geometry can be imported into p5.js using either OBJ or STL files. These files are usually generated in
@@ -405,10 +404,17 @@ learn:
405404
There are also methods that offer greater control of the geometry. A shape can be defined point-by-point using
406405
<a class="code" href="{{root}}/reference/#/p5/beginShape">beginShape()</a>, <a class="code"
407406
href="{{root}}/reference/#/p5/vertex">vertex()</a>, and <a class="code"
408-
href="{{root}}/reference/#/p5/endShape">endShape()</a>
407+
href="{{root}}/reference/#/p5/endShape">endShape()</a>. This following example shows how
408+
these methods can be used to construct a 3D shape mathematically.
409409
getting-started-in-webgl-custom-geometry-p6x1: >-
410-
There is also a powerful class, p5.Geometry, which p5 uses internally for <a class="code">loadModel()</a> but can also be used to
410+
There is also a powerful class, <a class="code" href="{{root}}/reference/#/p5/p5.Geometry">p5.Geometry</a>, which p5 uses internally for <a class="code">loadModel()</a> but can also be used to
411411
define custom geometry, offering tools that can be helpful in calculating faces and normals.
412+
getting-started-in-webgl-custom-geometry-p6x2: >-
413+
In 3D, a face refers to a collection of three or four points that make up a surface, giving our
414+
geometry the appearance of being solid. A normal is the direction that is perpendicular to the face, which helps p5.js calculate lighting across the surface.
415+
getting-started-in-webgl-custom-geometry-p6x3: >-
416+
In the following example, <a class="code">p5.Geometry</a> is used to plot the points for the geometry. Then, <a class="code">computeFaces()</a> is used to give the geometry
417+
a solid appearance and <a class="code">computeNormals()</a> allows our geometry to have proper lighting.
412418
getting-started-in-webgl-custom-geometry-heading3: Conclusion
413419
getting-started-in-webgl-custom-geometry-p7x1: >-
414420
Now you should be able to create custom geometry, making it possible to create

src/templates/pages/learn/getting-started-in-webgl-appearance.hbs

Lines changed: 71 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,8 @@ slug: learn/
5757
<li><a href="#camera">Camera and View</a></li>
5858
<li><a href="#lighting">Lighting</a></li>
5959
<li><a href="#materials">Materials and Textures</a></li>
60-
<li><a href="#glossary">Glossary</a></li>
6160
<li><a href="#conclusion">Conclusion</a></li>
61+
<li><a href="#glossary">Glossary</a></li>
6262
</ol>
6363
</div>
6464

@@ -73,27 +73,33 @@ slug: learn/
7373
alt="an illustration showing the difference between perspective and orthographic camera types">
7474

7575
<p>A <em>perspective camera</em> skews objects so they appear to get smaller as they get further away, vanishing
76-
at a
77-
single point in the distance. This is in contrast to an <em>orthographic camera</em>, where the geometry stays
78-
the same
79-
size as it gets further away and has no vanishing point. </p>
76+
at a single point in the distance. This is in contrast to an <em>orthographic camera</em>, where the
77+
geometry stays the same size as it gets further away and has no vanishing point. </p>
8078

81-
<p>Constantly moving and adjusting the camera in code can be tedious, especially when you are experimenting with
79+
{{!-- sketch illustrating 3D camera --}}
80+
<iframe src="{{assets}}/learn/basic3D/cameraExample.html" width="720" height="350">
81+
</iframe>
82+
83+
<p>One setting that we can change with a perspective camera is the <em>field-of-view</em>, or FOV. This is the
84+
term that is used to describe how much our camera can see, measured as an angle. In simple examples it might appear
85+
to have a zoom-like effect, but it will change way that shapes will change size in the distance.</p>
86+
87+
<p>Another important term when working with cameras in 3D is the camera <em>frustum</em>. The frustum of the camera the
88+
shape of the camera's view, a pyramid-like shape within which geometry can be displayed. The frustum includes a <em>near and far plane</em>.
89+
The near plane defines the minimum distance that geometry must be from the camera to be rendered. The far plane defines the maximum
90+
distance that the geometry can be from the camera. Each of these can be changed to affect how close and how far the camera can see. This process
91+
of selectively including geometry is sometimes referred to as 'clipping'.</p>
92+
93+
<div style="display:flex; align-items:center; justify-content: center;">
94+
<img style="width:50%;" src='{{assets}}/learn/basic3D/images/frustum_example.png'
95+
alt="an illustration showing the the camera frustum, near plane, and far plane">
96+
</div>
97+
98+
<p>Cameras can be moved by passing arguments to <a class="code">camera()</a>, but constantly moving and adjusting the camera in code can be tedious, especially when you are experimenting with
8299
ideas. p5.js has a special camera method, <a class="code"
83100
href="{{root}}/reference/#/p5/orbitControl">orbitControl()</a>, that can be used to zoom, pan,
84101
and position the camera using the mouse.</p>
85102

86-
<p>The following camera methods are available in p5.js:</p>
87-
88-
<ul>
89-
<li><a class="code" href="{{root}}/reference/#/p5/ortho">ortho(left, right, bottom, top, near, far)</a></li>
90-
<li><a class="code" href="{{root}}/reference/#/p5/perspective">perspective(fovy, aspect, near, far)</a></li>
91-
<li><a class="code" href="{{root}}/reference/#/p5/camera">camera(x, y, z, centerX, centerY, centerZ, upX, upY,
92-
upZ)</a></li>
93-
<li><a class="code" href="{{root}}/reference/#/p5/orbitControl">orbitControl(sensitivityX, sensitivityY,
94-
sensitivityZ)</a></li>
95-
</ul>
96-
97103
<p>
98104
A scene can have multiple cameras, but only one camera can be active at a time. Sketches in p5.js will default
99105
to having a single perspective camera, but that can be changed by calling either <a
@@ -111,7 +117,7 @@ function setup() {
111117
// ortho();
112118
113119
// setting initial camera position
114-
camera(400,-40, 400);
120+
camera(200,-40, 200);
115121
}
116122
117123
function draw() {
@@ -149,43 +155,39 @@ function draw() {
149155
}
150156
</script>
151157

152-
{{!-- sketch illustrating 3D camera --}}
153-
<iframe src="{{assets}}/learn/basic3D/cameraExample.html" width="720" height="350">
154-
</iframe>
158+
155159

156160
<h2 id="lighting">Lighting</h2>
157161

158162
<p>Lighting is another essential part of a 3D scene. To be able to convey shape and depth in 3D is necessary to
159163
have a light source. p5.js has a few different types of light that can be used in a sketch.</p>
160164

161-
<p>In p5 we have: </p>
162-
163165
<ul>
164-
<li><a class="code" href="{{root}}/reference/#/p5/ambientLight">ambientLight()</a>
166+
<li><h3><a class="code" href="{{root}}/reference/#/p5/ambientLight">ambientLight()</a></h3>
165167
<ul style="margin-left:15px;">
166168
<li>Ambient light makes everything display a little brighter, with no consideration for light position or
167169
direction.</li>
168170
</ul>
169171
</li>
170-
<li><a class="code" href="{{root}}/reference/#/p5/directionalLight">directionalLight()</a>
172+
<li><h3><a class="code" href="{{root}}/reference/#/p5/directionalLight">directionalLight()</a></h3>
171173
<ul style="margin-left:15px;">
172174
<li>A directional light shines from one direction, which can be especially useful for communicating depth in
173175
a scene, or when a scene needs a 'sun' light. This method accepts a color and direction.</li>
174176
</ul>
175177
</li>
176-
<li><a class="code" href="{{root}}/reference/#/p5/pointLight">pointLight()</a>
178+
<li><h3><a class="code" href="{{root}}/reference/#/p5/pointLight">pointLight()</a></h3>
177179
<ul style="margin-left:15px;">
178180
<li>A point light emits from a single point in all directions, similar to something like a lightbulb. This
179181
method accepts a color and a position for the light.</li>
180182
</ul>
181183
</li>
182-
<li><a class="code" href="{{root}}/reference/#/p5/spotLight">spotLight()</a>
184+
<li><h3><a class="code" href="{{root}}/reference/#/p5/spotLight">spotLight()</a></h3>
183185
<ul style="margin-left:15px;">
184186
<li>A spot light emits from a single point in a single direction. This light is cast in a conical shape and
185187
it's radius and concentration can be adjusted.</li>
186188
</ul>
187189
</li>
188-
<li><a class="code" href="{{root}}/reference/#/p5/noLights">noLights()</a>
190+
<li><h3><a class="code" href="{{root}}/reference/#/p5/noLights">noLights()</a></h3>
189191
<ul style="margin-left:15px;">
190192
<li>noLights() makes it so that all subsequent geometry is rendered without any lighting. This can be useful
191193
when you want flat, unshaded geometry.</li>
@@ -196,45 +198,43 @@ function draw() {
196198
<p>
197199
These lights should be used within <a class="code">draw()</a>. Up to 5 lights can be used in a scene
198200
simultaneously,
199-
allowing you to compose a scene with varied and complex lighting sources.
201+
allowing you to compose a scene with varied and complex lighting sources. In the following sketch there are a number of different lights commented out. Try uncommenting them to see how the lights can be combined.
200202
</p>
201203

202204
{{!-- lighting example --}}
203205
<script type="text/p5" data-autoplay data-p5-version="{{ version }}">
204206
function setup() {
205207
createCanvas(windowWidth, windowHeight, WEBGL);
206-
debugMode();
207-
208-
camera(200,-80, 200);
208+
camera(100,-80, 100);
209209
}
210210
211211
function draw() {
212212
background(220);
213213
214214
orbitControl()
215215
216-
// uncomment to enable / disable lights
216+
// use comments to enable / disable lights
217217
218-
// ambientLight(20);
218+
ambientLight(20);
219219
220-
// pointLight(
221-
// 255, 0, 0, // color
222-
// 40, -40,0 // position
223-
// );
220+
pointLight(
221+
255, 0, 0, // color
222+
40, -40,0 // position
223+
);
224224
225-
// directionalLight(
226-
// 0,255,0, // color
227-
// 1, 1, 0 // direction
228-
// );
225+
directionalLight(
226+
0,255,0, // color
227+
1, 1, 0 // direction
228+
);
229229
230-
// let locX = mouseX - width / 2;
231-
// let locY = mouseY - height / 2;
232-
// spotLight(
233-
// 0, 0, 255, // color
234-
// locX, locY, 100, // position
235-
// 0, 0, -1, // direction
236-
// 40 // radius of the spotlight cone
237-
// );
230+
let locX = mouseX - width / 2;
231+
let locY = mouseY - height / 2;
232+
spotLight(
233+
0, 0, 255, // color
234+
locX, locY, 100, // position
235+
0, 0, -1, // direction
236+
40 // radius of the spotlight cone
237+
);
238238
239239
// noLights();
240240
@@ -244,9 +244,9 @@ function draw() {
244244

245245
<br />
246246

247-
{{!-- sketch illustrating lighting of geometry --}}
247+
{{!-- sketch illustrating lighting of geometry
248248
<iframe src="{{assets}}/learn/basic3D/lightingExample.html" width="720" height="350">
249-
</iframe>
249+
</iframe> --}}
250250

251251
<h2 id="materials">Materials and Textures</h2>
252252
<p>3D is not all about geometry, objects can appear differently based on their material. Materials dictate how
@@ -269,30 +269,32 @@ function draw() {
269269
<script type="text/p5" data-autoplay data-p5-version="{{ version }}">
270270
function setup() {
271271
createCanvas(innerWidth, innerHeight, WEBGL);
272-
debugMode();
273272
}
274273
275274
function draw() {
276275
background(220);
277276
camera(200, -200, 200);
277+
278+
noStroke();
278279
279280
ambientLight(128)
280281
let locX = mouseX - width / 2;
281282
let locY = mouseY - height / 2;
282283
pointLight(255, 255, 255, locX, locY, 100);
283284
284-
// normalMaterial();
285+
// normal material shows the geometry normals
286+
normalMaterial();
285287
286288
// ambient materials reflect under any light
287289
ambientMaterial(255, 0, 0);
288290
289291
// emissive materials show the same color regardless of light
290-
// emissiveMaterial(0, 255, 0);
292+
emissiveMaterial(0, 255, 0);
291293
292294
// specular materials reflect the color of the light source
293295
// and can vary in 'shininess'
294-
// shininess(10)
295-
// specularMaterial(0, 0, 255);
296+
shininess(10)
297+
specularMaterial(0, 0, 255);
296298
297299
// box(50);
298300
sphere();
@@ -359,6 +361,18 @@ function draw() {
359361
<p>A projection that is <em>orthogonal</em> and unaffected by depth. It gives the appearance of being
360362
two-dimensional. </p>
361363

364+
<h3>Field-of-View</h3>
365+
<p></p>
366+
367+
<h3>Frustum</h3>
368+
<p></p>
369+
370+
<h3>Near and Far Plane</h3>
371+
<p></p>
372+
373+
<h3>Clipping</h3>
374+
<p></p>
375+
362376
</main>
363377

364378
{{> footer}}

src/templates/pages/learn/getting-started-in-webgl-custom-geometry.hbs

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,6 @@ slug: learn/
3939
<main>
4040
<script src="//toolness.github.io/p5.js-widget/p5-widget.js"></script>
4141

42-
{{!-- large title sketch --}}
43-
{{!-- <iframe src="{{assets}}/learn/basic3D/titleExample.html" width="720" height="350">
44-
</iframe> --}}
45-
4642
<h1>{{#i18n "getting-started-in-webgl-custom-geometry-title"}}{{/i18n}}</h1>
4743

4844
<p>{{#i18n "getting-started-in-webgl-custom-geometry-p1x1"}}{{/i18n}}</p>
@@ -54,8 +50,8 @@ slug: learn/
5450
<ol>
5551
<li><a href="#3dModels">{{#i18n "getting-started-in-webgl-custom-geometry-toc1"}}{{/i18n}}</a></li>
5652
<li><a href="#proceduralGeometry">{{#i18n "getting-started-in-webgl-custom-geometry-toc2"}}{{/i18n}}</a></li>
57-
<li><a href="#glossary">{{#i18n "getting-started-in-webgl-custom-geometry-toc3"}}{{/i18n}}</a></li>
58-
<li><a href="#conclusion">Conclusion</a></li>
53+
<li><a href="#conclusion">{{#i18n "getting-started-in-webgl-custom-geometry-toc3"}}{{/i18n}}</a></li>
54+
<li><a href="#glossary">{{#i18n "getting-started-in-webgl-custom-geometry-toc4"}}{{/i18n}}</a></li>
5955
</ol>
6056
</div>
6157

@@ -110,12 +106,12 @@ function draw(){
110106
// click+drag on canvas to look around the shape
111107
orbitControl();
112108
113-
fill(255,0,0,128)
109+
fill(255,0,0,128);
114110
115111
var numVertices = 100;
116-
translate(0,numVertices,0)
117-
rotateY(millis()/1000)
118-
scale(20)
112+
translate(0,numVertices,0);
113+
rotateY(millis()/1000);
114+
scale(20);
119115
beginShape();
120116
// a simple spiral shape
121117
for(let i = 0; i < numVertices; i++) {
@@ -131,6 +127,15 @@ function draw(){
131127

132128
<p>{{#i18n "getting-started-in-webgl-custom-geometry-p6x1"}}{{/i18n}}</p>
133129

130+
<div style="display: flex; align-items: center; justify-content: center;">
131+
<p>{{#i18n "getting-started-in-webgl-custom-geometry-p6x2"}}{{/i18n}}</p>
132+
133+
<img style="padding:30px; width:50%;" src='{{assets}}/learn/basic3D/images/normals_face_example.png'
134+
alt="an illustration a collection of three points, constituting a face, and an arrow extending perpendicular to it, the normal" />
135+
</div>
136+
137+
<p>{{#i18n "getting-started-in-webgl-custom-geometry-p6x3"}}{{/i18n}}</p>
138+
134139
{{!-- Example using p5.Geometry --}}
135140
<script type="text/p5" data-autoplay data-p5-version="{{ version }}">
136141
var myGeometry

0 commit comments

Comments
 (0)