Updated docs for VoxelTool class family #683

Illauriel · 2024-08-12T23:31:54Z

I tried to fill some blanks in VoxelTool docs based on some experiments and looking at source. I might have still gotten something wrong and would appreciate feedback and suggestions on how to do things better.

PS: I was unsure how to do links from class ref to main articles, so I used relative path. bbcode_to_markdown complains about such syntax, but the link works well in vscode markdown preview. Hope it doesn't break in readthedocs ^^'

Zylann · 2024-08-13T18:31:31Z

doc/classes/VoxelTool.xml

@@ -41,39 +41,47 @@
 			<param index="0" name="begin" type="Vector3i" />
 			<param index="1" name="end" type="Vector3i" />
 			<description>
-				Operate on a rectangular cuboid section of the terrain. [code]begin[/code] and [code]end[/code] are inclusive. Choose operation and which voxel to use by setting [code]value[/code] and [code]mode[/code] before calling this function.
+				Operate on a rectangular cuboid section of the terrain. [code]begin[/code] and [code]end[/code] are inclusive. 


Actually, end is not inclusive with smooth voxels. For example if you pass (0,0,0) and (0,0,0), that's an empty box and it won't do anything. It might have been a mistake that the blocky mode was inconsistent, because generally I code everything dealing with boxes using an exclusive max point. But thats how things have been so far, it's quite old.

Ah, okay, then I'll try to reflect that in revised description.^^'

Zylann · 2024-08-13T18:32:52Z

doc/classes/VoxelTool.xml

@@ -41,39 +41,47 @@
 			<param index="0" name="begin" type="Vector3i" />
 			<param index="1" name="end" type="Vector3i" />
 			<description>
-				Operate on a rectangular cuboid section of the terrain. [code]begin[/code] and [code]end[/code] are inclusive. Choose operation and which voxel to use by setting [code]value[/code] and [code]mode[/code] before calling this function.
+				Operate on a rectangular cuboid section of the terrain. [code]begin[/code] and [code]end[/code] are inclusive. 
+				You must choose operation by setting [code]mode[/code] and set parameters relevant to the type of tool before calling this function.


That's true of every operation, so I'm not sure how relevant it is to indicate that on do_box specifically?

At first I thought of linking every do_* op to Box as the most documented one, but now I'm thinking that maybe this and the next comment can be moved to ''Using VoxelTool" section of Scripting article in the main doc. Maybe even with code examples and stuff. Does it sound reasonable?

It would be nice, but at the same time it requires putting absolute links in there, while it could also be in the description of the class. But I dont think we can link to that description somehow.

Zylann · 2024-08-13T18:36:38Z

doc/classes/VoxelTool.xml

+				Operate on a rectangular cuboid section of the terrain. [code]begin[/code] and [code]end[/code] are inclusive. 
+				You must choose operation by setting [code]mode[/code] and set parameters relevant to the type of tool before calling this function.
+				If working with blocky terrain, you can choose which voxel to use by setting [member value].
+				If working with smooth terrain, use [member sdf_scale] and [member sdf_strength] in [constant VoxelTool.MODE_ADD] or [constant VoxelTool.MODE_REMOVE]. See also [constant VoxelTool.MODE_TEXTURE_PAINT].


Once again, not sure if all this should be indicated here, because that's true of many do_* functions. In addition, sdf_scale is getting less recommended unless you know what you're doing, it was originally present to allow improving the encoding fixed-point scale, which is now automatic.

Zylann · 2024-08-13T18:38:07Z

doc/classes/VoxelTool.xml

 			</description>
 		</method>
 		<method name="do_path">
 			<return type="void" />
 			<param index="0" name="points" type="PackedVector3Array" />
 			<param index="1" name="radii" type="PackedFloat32Array" />
 			<description>
+				Performs an edit similar to `do_sphere` along a spline defined by `points`.


This is not a spline, it's a list of points connected by linear segments. They are not smoothed out. Not sure how to call that, but a spline is something different.
Also radii (radius, plural) needs to be explained, it is the width of the "tube" along each point.
Internally, this is equivalent to carving/building capsules end-to-end, where the radius of the base and the top of each capsule is taken from the radii. The original reason I started exposing that function was to do cave worms.

I see! So maybe something like

"Performs an edit along a series of tubular sections with junctions defined by points array. radii (plural of radius) array defines tube's thickness at the point with corresponding index. The main purpose of this function is efficiently carving tunnels."

This is not a spline, it's a list of points connected by linear segments. They are not smoothed out. Not sure how to call that, but a spline is something different.

Polyline is probably the best term. It may be lingo, but is used in various open APIs and in AutoCAD.

Zylann · 2024-08-13T18:44:05Z

doc/classes/VoxelTool.xml

 			</description>
 		</method>
 		<method name="get_voxel_f">
 			<return type="float" />
 			<param index="0" name="pos" type="Vector3i" />
 			<description>
+				Returns data from voxel at `pos` coordinates as float. If set to operate on [constant VoxelBuffer.CHANNEL_SDF] returns the voxel's SDF value.


Note that the channel doesn't actually matter: it will always decode voxel data the same way. But it is indeed meant to read SDF values. Also, the range of precision is not exactly like a float, it is set to quantized values when using 8-bit and 16-bit depths, which are tuned for signed distances. However when using 32-bit it does use actual floats.
This is actually something that boils down to VoxelBuffer, because that's where this encoding/decoding takes place.
Anyways, not sure if it needs all these details, "float" is ok, but it's just that not the full range of float values work here.

I tried to distill the details and got something like this:
"Returns data from voxel at pos coordinates as a float value. This method is intended to read SDF values and will be decoded as such regardless of the channel value of the tool.
Note: Return value's actual precision depends on VoxelBuffer.Depth set for the SDF channel."

Zylann · 2024-08-13T18:46:04Z

doc/classes/VoxelTool.xml

@@ -100,12 +108,14 @@
 			<return type="bool" />
 			<param index="0" name="box" type="AABB" />
 			<description>
+				Returns false if the blocks within `box` are not fully loaded. Not implemented in this class, because it only makes sense if editing with [VoxelToolTerrain] or [VoxelToolLodTerrain]


Not sure if it should say that it's not implemented in this class? Because that method won't appear in derived classes in the docs. Also it should already being known that VoxelTool itself should never be used as-is, it's only a base class acting as a common interface. The woes of OOP inheritance docs :p

Haha, yeah, I wrote this looking at base implementation without realizing it won't appear in child class docs. I'm new to this xD
If links to main docs will work, maybe it can mention "Useful to check if edited area is within bounds and in LOD0 in case of LOD terrain" and link back to the section about this in Scripting.

Zylann · 2024-08-13T20:08:34Z

doc/classes/VoxelToolLodTerrain.xml

@@ -16,6 +16,7 @@
 			<param index="1" name="transform" type="Transform3D" />
 			<param index="2" name="area_size" type="Vector3" />
 			<description>
+				Allows using a [VoxelGeneratorGraph] as a brush, which opens possibility for various advanced scenarios. See [related article](../Generators.md#using-voxelgeneratorgraph-as-a-brush).


[related has no precedent in Godot's documentation. XML files follow features supported by Godot, because this is the same file used to display API docs in the editor.
Maybe you should use the [url=https://...]text[/url] syntax?

Oof, yeah. 'related' is not intended as a keyword here, it's just "related article" x) I'll try the new syntax and see if the bbcode converter still complains at me.^^

Zylann · 2024-08-13T20:15:01Z

doc/classes/VoxelToolTerrain.xml

@@ -17,6 +17,7 @@
 			<param index="2" name="flat_direction" type="Vector3" />
 			<param index="3" name="smoothness" type="float" default="0.0" />
 			<description>
+				Operates on a hemisphe, where the "dome" part's summit is pointed in `flat_direction`. `smoothness` determines how the flat part blends with the rounded part, with higher values producing softer more rounded edge.  


Typo: "hemisphe"

flat_direction is actually supposed to point away from the flat side. If that's not the case I think it should be fixed.

Oh nö, my bad!^^'

With flat_direction I was expecting it to work as you say, but yeah, it's flipped.

//funcs.h:353 math::sdf_smooth_subtract( // math::sdf_sphere(pos, center, radius), // math::sdf_plane(pos, flat_direction, plane_d), smoothness );

Updated docs for VoxelTool class family

1298aa9

Zylann reviewed Aug 13, 2024

View reviewed changes

Zylann force-pushed the master branch 2 times, most recently from 8fdf450 to a393969 Compare October 5, 2024 04:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updated docs for VoxelTool class family #683

Updated docs for VoxelTool class family #683

Illauriel commented Aug 12, 2024 •

edited

Loading

Zylann Aug 13, 2024

Illauriel Aug 14, 2024

Zylann Aug 13, 2024

Illauriel Aug 14, 2024

Zylann Aug 14, 2024

Zylann Aug 13, 2024

Zylann Aug 13, 2024 •

edited

Loading

Illauriel Aug 15, 2024

Poikilos Aug 15, 2024 •

edited

Loading

Zylann Aug 13, 2024 •

edited

Loading

Illauriel Aug 15, 2024

Zylann Aug 13, 2024 •

edited

Loading

Illauriel Aug 15, 2024

Zylann Aug 13, 2024

Illauriel Aug 15, 2024

Zylann Aug 13, 2024

Illauriel Aug 15, 2024

Updated docs for VoxelTool class family #683

Are you sure you want to change the base?

Updated docs for VoxelTool class family #683

Conversation

Illauriel commented Aug 12, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Zylann Aug 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Poikilos Aug 15, 2024 • edited Loading

Choose a reason for hiding this comment

Zylann Aug 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Zylann Aug 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Illauriel commented Aug 12, 2024 •

edited

Loading

Zylann Aug 13, 2024 •

edited

Loading

Poikilos Aug 15, 2024 •

edited

Loading

Zylann Aug 13, 2024 •

edited

Loading

Zylann Aug 13, 2024 •

edited

Loading