Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WebGL mode documentation improvements #6167

Merged
merged 19 commits into from
Jun 20, 2023
+19 −2
Merged

WebGL mode documentation improvements #6167

Changes from 1 commit
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
1d6068d
add basic feature list and links as a summary for webgl mode docs
wong-justin May 29, 2023
9d96c21
Merge remote-tracking branch 'upstream/main' into webgl-inline-docs
wong-justin Jun 4, 2023
17936c8
use markdown bold instead of html bold
wong-justin Jun 4, 2023
a2ef21d
intro sentences more descriptive + simplified
wong-justin Jun 4, 2023
29a700d
format list items as: topic, then sentence(s) with links
wong-justin Jun 4, 2023
84985f3
ending references seem nicer as a sentence instead of 2 list items
wong-justin Jun 4, 2023
f1a00c6
add line() WEBGL example
wong-justin Jun 5, 2023
021c565
label z-params as WEBGL mode
wong-justin Jun 5, 2023
004ac1d
remove unused documentation
wong-justin Jun 5, 2023
f4b3a9c
Revert "remove unused documentation"
wong-justin Jun 5, 2023
eed99e6
add comment about documentation not being generated
wong-justin Jun 5, 2023
9dbe1c2
add webgl example using detail param for arc()
wong-justin Jun 5, 2023
346e0a4
Merge remote-tracking branch 'upstream/main' into webgl-inline-docs
wong-justin Jun 9, 2023
30d6fd4
style line() 3d example as xyz gizmo
wong-justin Jun 9, 2023
2fafba9
add shape detail to webgl feature list
wong-justin Jun 12, 2023
699c922
Revert "style line() 3d example as xyz gizmo"
wong-justin Jun 20, 2023
04f8763
Revert "add webgl example using detail param for arc()"
wong-justin Jun 20, 2023
994d18f
Revert "label z-params as WEBGL mode"
wong-justin Jun 20, 2023
57f3a96
Revert "add line() WEBGL example"
wong-justin Jun 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions src/core/constants.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,18 @@ export const VERSION =
*/
export const P2D = 'p2d';
/**
* One of the two render modes in p5.js: P2D (default renderer) and WEBGL
* Enables 3D render by introducing the third dimension: Z
* One of the two render modes in p5.js, most known for 3D rendering.
*
* Some differences and new features to expect compared to the default render mode <a href="/#/p5/P2D">P2D</a>:
* - The <strong>coordinate system</strong> is centered and uses an optional z-dimension
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, just a heads up, for now bullet lists in our docs render just as newlines in the reference. I don't think we have an issue to track this yet so I made an issue for it here: #6170

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok once this is merged #6177 you'll get bullets next to your list items!

* - <strong>Textures</strong>, <strong>materials</strong>, and <strong>lighting</strong> can be applied to shapes
* - You can control the <strong>camera</strong> that views the scene
* - <strong>Text</strong> is drawn differently
* - You can use <strong>shaders</strong>
Copy link
Contributor Author

@wong-justin wong-justin May 29, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking about adding links to each of the bold features, like <a href="https://github.com/processing/p5.js/wiki/Getting-started-with-WebGL-in-p5#text"><strong>Text</strong></a> is drawn differently. Not sure if function docs should be linked, or p5js tutorial sections, or other content, or if they should even have links in the first place.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Linking sounds good to me, for what it's worth!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it is helpful to link out to more info for each of those topics and I appreciate this as a brief list of differences. I think that replacing the bold text with links though might not be very clear, I wonder if things can be reworded in a way that lets you describe where the information can be found. Something like:

The coordinate system is centered and uses an optional z-dimension, which you can read more about in the <a href="">"Getting Started With WebGL"</a> tutorial in the Learn page.

Additionally, it would help to include a little more text for "Text is drawn differently" and "You can use shaders". For text, the reference page for text() describes some of the issues, maybe you can rephrase it into something like:

Text in WebGL requires opentype/truetype fonts loaded in your [preload()](https://p5js.org/reference/#/p5/preload) function using the [loadFont()](https://p5js.org/reference/#/p5/loadFont) method. More information about using text in this mode can be found in the [wiki](https://github.com/processing/p5.js/wiki/Getting-started-with-WebGL-in-p5#text).

And it might be helpful to briefly define shader, as some users might not be familiar:

WebGL mode makes it possible to use shaders, which are programs that can be used for creating a variety of effects and graphics that take advantage of hardware acceleration.

*
* To learn more about WEBGL mode, see:
* - <a href="https://github.com/processing/p5.js/wiki/Getting-started-with-WebGL-in-p5">Getting started with WebGL in p5</a>, a wiki page on the p5.js github
* - <a href="https://p5js.org/learn/#:~:text=Getting%20Started%20in%20WebGL">Getting Started in WebGL</a>, a series of tutorials in the p5.js "Learn" reference section
* @property {String} WEBGL
* @final
*/
Expand Down