Skip to content

Commit 404f9a4

Browse files
authored
Improve Gizmo API docs (#7620)
1 parent e378645 commit 404f9a4

File tree

3 files changed

+99
-9
lines changed

3 files changed

+99
-9
lines changed

src/extras/gizmo/rotate-gizmo.js

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,36 @@ const FACING_THRESHOLD = 0.9;
2929
const GUIDE_ANGLE_COLOR = new Color(0, 0, 0, 0.3);
3030

3131
/**
32-
* Rotation gizmo.
32+
* The RotateGizmo provides interactive 3D manipulation handles for rotating/reorienting
33+
* {@link Entity}s in a {@link Scene}. It creates a visual widget with a draggable ring for each
34+
* axis of rotation, plus a fourth ring for rotation in the camera's view plane, allowing precise
35+
* control over object orientation through direct manipulation. The gizmo's visual appearance can
36+
* be customized away from the defaults as required.
37+
*
38+
* Note that the gizmo can be driven by both mouse+keyboard and touch input.
39+
*
40+
* ```javascript
41+
* // Create a layer for rendering all gizmos
42+
* const gizmoLayer = pc.Gizmo.createLayer(app);
43+
*
44+
* // Create a rotate gizmo
45+
* const gizmo = new pc.RotateGizmo(cameraComponent, gizmoLayer);
46+
*
47+
* // Create an entity to attach the gizmo to
48+
* const entity = new pc.Entity();
49+
* entity.addComponent('render', {
50+
* type: 'box'
51+
* });
52+
* app.root.addChild(entity);
53+
*
54+
* // Attach the gizmo to the entity
55+
* gizmo.attach([entity]);
56+
* ```
57+
*
58+
* Relevant Engine API examples:
59+
*
60+
* - [Rotate Gizmo](https://playcanvas.github.io/#/gizmos/transform-rotate)
61+
* - [Editor](https://playcanvas.github.io/#/misc/editor)
3362
*
3463
* @category Gizmo
3564
*/
@@ -142,10 +171,11 @@ class RotateGizmo extends TransformGizmo {
142171
orbitRotation = false;
143172

144173
/**
145-
* Creates a new RotateGizmo object.
174+
* Creates a new RotateGizmo object. Use {@link Gizmo.createLayer} to create the layer
175+
* required to display the gizmo.
146176
*
147177
* @param {CameraComponent} camera - The camera component.
148-
* @param {Layer} layer - The render layer.
178+
* @param {Layer} layer - The layer responsible for rendering the gizmo.
149179
* @example
150180
* const gizmo = new pc.RotateGizmo(camera, layer);
151181
*/

src/extras/gizmo/scale-gizmo.js

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,36 @@ const tmpQ1 = new Quat();
2323
const GLANCE_EPSILON = 0.98;
2424

2525
/**
26-
* Scaling gizmo.
26+
* The ScaleGizmo provides interactive 3D manipulation handles for scaling/resizing
27+
* {@link Entity}s in a {@link Scene}. It creates a visual widget with box-tipped lines along the
28+
* X, Y and Z axes, planes at their intersections, and a center box, allowing precise control over
29+
* object scaling through direct manipulation. The gizmo's visual appearance can be customized
30+
* away from the defaults as required.
31+
*
32+
* Note that the gizmo can be driven by both mouse+keyboard and touch input.
33+
*
34+
* ```javascript
35+
* // Create a layer for rendering all gizmos
36+
* const gizmoLayer = pc.Gizmo.createLayer(app);
37+
*
38+
* // Create a scale gizmo
39+
* const gizmo = new pc.ScaleGizmo(cameraComponent, gizmoLayer);
40+
*
41+
* // Create an entity to attach the gizmo to
42+
* const entity = new pc.Entity();
43+
* entity.addComponent('render', {
44+
* type: 'box'
45+
* });
46+
* app.root.addChild(entity);
47+
*
48+
* // Attach the gizmo to the entity
49+
* gizmo.attach([entity]);
50+
* ```
51+
*
52+
* Relevant Engine API examples:
53+
*
54+
* - [Scale Gizmo](https://playcanvas.github.io/#/gizmos/transform-scale)
55+
* - [Editor](https://playcanvas.github.io/#/misc/editor)
2756
*
2857
* @category Gizmo
2958
*/
@@ -124,10 +153,11 @@ class ScaleGizmo extends TransformGizmo {
124153
lowerBoundScale = new Vec3(-Infinity, -Infinity, -Infinity);
125154

126155
/**
127-
* Creates a new ScaleGizmo object.
156+
* Creates a new ScaleGizmo object. Use {@link Gizmo.createLayer} to create the layer
157+
* required to display the gizmo.
128158
*
129159
* @param {CameraComponent} camera - The camera component.
130-
* @param {Layer} layer - The render layer.
160+
* @param {Layer} layer - The layer responsible for rendering the gizmo.
131161
* @example
132162
* const gizmo = new pc.ScaleGizmo(camera, layer);
133163
*/

src/extras/gizmo/translate-gizmo.js

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,36 @@ const tmpQ1 = new Quat();
2929
const GLANCE_EPSILON = 0.98;
3030

3131
/**
32-
* Translation gizmo.
32+
* The TranslateGizmo provides interactive 3D manipulation handles for translating/moving
33+
* {@link Entity}s in a {@link Scene}. It creates a visual widget with arrows along the X, Y
34+
* and Z axes, planes at their intersections, and a center sphere, allowing precise control over
35+
* object positioning through direct manipulation. The gizmo's visual appearance can be customized
36+
* away from the defaults as required.
37+
*
38+
* Note that the gizmo can be driven by both mouse+keyboard and touch input.
39+
*
40+
* ```javascript
41+
* // Create a layer for rendering all gizmos
42+
* const gizmoLayer = pc.Gizmo.createLayer(app);
43+
*
44+
* // Create a translate gizmo
45+
* const gizmo = new pc.TranslateGizmo(cameraComponent, gizmoLayer);
46+
*
47+
* // Create an entity to attach the gizmo to
48+
* const entity = new pc.Entity();
49+
* entity.addComponent('render', {
50+
* type: 'box'
51+
* });
52+
* app.root.addChild(entity);
53+
*
54+
* // Attach the gizmo to the entity
55+
* gizmo.attach([entity]);
56+
* ```
57+
*
58+
* Relevant Engine API examples:
59+
*
60+
* - [Translate Gizmo](https://playcanvas.github.io/#/gizmos/transform-translate)
61+
* - [Editor](https://playcanvas.github.io/#/misc/editor)
3362
*
3463
* @category Gizmo
3564
*/
@@ -121,10 +150,11 @@ class TranslateGizmo extends TransformGizmo {
121150
flipShapes = true;
122151

123152
/**
124-
* Creates a new TranslateGizmo object.
153+
* Creates a new TranslateGizmo object. Use {@link Gizmo.createLayer} to create the layer
154+
* required to display the gizmo.
125155
*
126156
* @param {CameraComponent} camera - The camera component.
127-
* @param {Layer} layer - The render layer.
157+
* @param {Layer} layer - The layer responsible for rendering the gizmo.
128158
* @example
129159
* const gizmo = new pc.TranslateGizmo(camera, layer);
130160
*/

0 commit comments

Comments
 (0)