From 1fffab8cf216d81e83e5d12101b8cbc9fc8ef0f3 Mon Sep 17 00:00:00 2001 From: Max Hilbrunner Date: Tue, 11 Oct 2022 10:14:37 +0200 Subject: [PATCH] Formatting, syntax and URL fixes --- about/docs_changelog.rst | 11 --- about/list_of_features.rst | 2 +- development/cpp/object_class.rst | 2 +- .../navigation_using_navigationmeshes.rst | 88 +++++++++---------- .../scripting/gdscript/gdscript_basics.rst | 1 + tutorials/shaders/compute_shaders.rst | 32 +++---- 6 files changed, 63 insertions(+), 73 deletions(-) diff --git a/about/docs_changelog.rst b/about/docs_changelog.rst index a63b900fa..1f08a478d 100644 --- a/about/docs_changelog.rst +++ b/about/docs_changelog.rst @@ -110,11 +110,6 @@ Scripting - :ref:`doc_what_is_gdnative` - :ref:`doc_gdscript_warning_system` (split from :ref:`doc_gdscript_static_typing`) -VR -^^ - -- :ref:`doc_developing_for_oculus_quest` - User Interface (UI) ^^^^^^^^^^^^^^^^^^^ @@ -170,12 +165,6 @@ Networking - :ref:`doc_webrtc` -VR -^^ - -- :ref:`doc_vr_starter_tutorial_part_one` -- :ref:`doc_vr_starter_tutorial_part_two` - Plugins ^^^^^^^ diff --git a/about/list_of_features.rst b/about/list_of_features.rst index 386433d24..e8feede55 100644 --- a/about/list_of_features.rst +++ b/about/list_of_features.rst @@ -652,7 +652,7 @@ File formats - Text-based formats are human-readable and more friendly to version control. - Binary formats are faster to save/load for large scenes/resources. -- Read and write text or binary files using :ref:`class_File`. +- Read and write text or binary files using :ref:`class_FileAccess`. - Can optionally be compressed or encrypted. diff --git a/development/cpp/object_class.rst b/development/cpp/object_class.rst index 8e78662cd..4016fe9d8 100644 --- a/development/cpp/object_class.rst +++ b/development/cpp/object_class.rst @@ -247,7 +247,7 @@ More information can be found on the :ref:`doc_godot_notifications` page. References ---------- -:ref:`Reference ` inherits from Object and holds a +:ref:`Reference ` inherits from Object and holds a reference count. It is the base for reference counted object types. Declaring them must be done using Ref<> template. For example: diff --git a/tutorials/navigation/navigation_using_navigationmeshes.rst b/tutorials/navigation/navigation_using_navigationmeshes.rst index 692135c2e..9a4f5e051 100644 --- a/tutorials/navigation/navigation_using_navigationmeshes.rst +++ b/tutorials/navigation/navigation_using_navigationmeshes.rst @@ -3,8 +3,8 @@ Using NavigationMeshes ====================== -2D and 3D version of the navigation mesh are available as -:ref:`NavigationPolygon` and +2D and 3D version of the navigation mesh are available as +:ref:`NavigationPolygon` and :ref:`NavigationMesh` respectively. .. _doc_navigation_navmesh_baking: @@ -12,7 +12,7 @@ Using NavigationMeshes Creating 2D NavigationMeshes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Navigation meshes in the 2D editor are created with the help of the NavigationPolygon draw tools +Navigation meshes in the 2D editor are created with the help of the NavigationPolygon draw tools that appear in the top bar of the editor when a NavigationRegion2D is selected. .. image:: img/nav_polydrawtool.png @@ -32,16 +32,16 @@ Outlines, as the name would suggest, cannot intersect each other or have any ove .. image:: img/nav_polyoutlinefail.png Outline layouts like seen in this picture will fail the convex partitioning required by the navigation mesh generation. -In this layout cases the outline tool cannot be used. Use the :ref:`Geometry2D` class for +In this layout cases the outline tool cannot be used. Use the :ref:`Geometry2D` class for polygon merge or intersect operations to create a valid merged mesh for navigation. .. note:: - The NavigationServer does not connect navigation mesh islands from the same NavigationMesh resource. + The NavigationServer does not connect navigation mesh islands from the same NavigationMesh resource. Do not create multiple disconnected islands in the same NavigationRegion2D and NavPoly resource if they should be later connected. For 2D no similar navigation mesh baking with geometry parsing exists like in 3D. -The Geometry2D class functions for offset, merge, intersect and clip can be used +The Geometry2D class functions for offset, merge, intersect and clip can be used to shrink or enlarge existing NavigationPolygons to different actor sizes. Creating 3D NavigationMeshes @@ -49,18 +49,18 @@ Creating 3D NavigationMeshes .. image:: img/baked_navmesh.png -Navigation meshes in the 3D editor are created with the help of the -:ref:`NavigationMeshGenerator` singleton +Navigation meshes in the 3D editor are created with the help of the +:ref:`NavigationMeshGenerator` singleton and the NavigationMesh bake settings that appear in the editor inspector. NavigationMesh baking is the process of creating a simplified mesh used for pathfinding out of (complex) 3D level geometry. -For this process Godot parses scene geometry and hands the raw mesh or collision data to the +For this process Godot parses scene geometry and hands the raw mesh or collision data to the third-party ReCast library for processing and creation of the final navigationmesh. -The resulting NavigationMesh is an approximation of the source geometry surfaces -for both performance and technical reasons. Do not expect the NavigationMesh -to perfectly follow the original surfaces. Especially navigation polygons placed -over ramps will not keep an equal distance to the ground surface. To align an +The resulting NavigationMesh is an approximation of the source geometry surfaces +for both performance and technical reasons. Do not expect the NavigationMesh +to perfectly follow the original surfaces. Especially navigation polygons placed +over ramps will not keep an equal distance to the ground surface. To align an actor perfectly with the ground use other means like physics. .. warning:: @@ -76,22 +76,22 @@ If the navmesh resource is already prepared, the region can be updated with the .. tabs:: .. code-tab:: gdscript GDScript - + extends NavigationRegion3D - + func update_navmesh(): - + # use bake and update function of region var on_thread : bool = true bake_navigation_mesh(on_thread) - + # or use the NavigationMeshGenerator Singleton var navigationmesh : NavigationMesh = navmesh NavigationMeshGenerator.bake(navigationmesh, self) # remove old resource first to trigger a full update navmesh = null navmesh = navigationmesh - + # or use NavigationServer API to update region with prepared navmesh var region_rid : RID = get_region_rid() NavigationServer3D.region_set_navmesh(region_rid, navmesh) @@ -104,15 +104,15 @@ If the navmesh resource is already prepared, the region can be updated with the .. warning:: - Property values on a NavigationMesh resource like ``cell_size`` need - to match the actual mesh data stored inside in order to merge + Property values on a NavigationMesh resource like ``cell_size`` need + to match the actual mesh data stored inside in order to merge different navigation meshes without issues. NavigationRegion2D and Navigation3D both use meshes to mark traversable areas, only the tools to create them are different. For 2D NavigationPolygon resources are used to draw outline points in the editor. From these outline points the NavigationServer2D creates a mesh to upload navigation data to the NavigationServer. -For 3D NavigationMesh resources are used. Instead of providing draw tools the 3D variant +For 3D NavigationMesh resources are used. Instead of providing draw tools the 3D variant provides an extensive amount of parameters to bake a navigation mesh directly from 3D source geometry. .. note:: @@ -122,40 +122,40 @@ provides an extensive amount of parameters to bake a navigation mesh directly fr 2D Navmesh from CollisionPolygons ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following script parses all child nodes of a NavigationRegion2D for CollisionPolygons -and bakes their shape into the NavigationPolygon. As the NavigationPolygon creates the +The following script parses all child nodes of a NavigationRegion2D for CollisionPolygons +and bakes their shape into the NavigationPolygon. As the NavigationPolygon creates the navigationmesh from outline data the shapes cannot overlap. .. tabs:: .. code-tab:: gdscript GDScript extends NavigationRegion2D - + var navigationpolygon : NavigationPolygon = get_navigation_polygon() - + func _ready(): - + parse_2d_collisionshapes(self) - + navigationpolygon.make_polygons_from_outlines() set_navigation_polygon(navigationpolygon) - + func parse_2d_collisionshapes(root_node : Node2D): - + for node in root_node.get_children(): - + if node.get_child_count() > 0: parse_2d_collisionshapes(node) - + if node is CollisionPolygon2D: - + var new_collision_outline : PackedVector2Array = PackedVector2Array() var collisionpolygon_transform : Transform2D = node.get_global_transform() var collisionpolygon : CollisionPolygon2D = node.get_polygon() - + for vertex in collisionpolygon: new_collision_outline.append(collisionpolygon_transform.xform(vertex)) - + navigationpolygon.add_outline(new_collision_outline) Procedual 2D Navmesh @@ -167,7 +167,7 @@ The following script creates a new 2D navigation region and fills it with proced .. code-tab:: gdscript GDScript extends Node2D - + var new_2d_region_rid : RID = NavigationServer2D.region_create() var default_2d_map_rid : RID = get_world_2d().get_navigation_map() @@ -182,7 +182,7 @@ The following script creates a new 2D navigation region and fills it with proced ]) new_navpoly.add_outline(new_outline) new_navpoly.make_polygons_from_outlines() - + NavigationServer2D.region_set_navpoly(new_2d_region_rid, new_navpoly) Procedual 3D Navmesh @@ -194,17 +194,17 @@ The following script creates a new 3D navigation region and fills it with proced .. code-tab:: gdscript GDScript extends Node3D - + var new_3d_region_rid : RID = NavigationServer3D.region_create() - + var default_3d_map_rid : RID = get_world_3d().get_navigation_map() NavigationServer3D.region_set_map(new_3d_region_rid, default_3d_map_rid) - + var new_navmesh : NavigationMesh = NavigationMesh.new() var new_plane_mesh : PlaneMesh = PlaneMesh.new() new_plane_mesh.size = Vector2(10.0, 10.0) new_navmesh.create_from_mesh(new_plane_mesh) - + NavigationServer3D.region_set_navmesh(new_3d_region_rid, new_navmesh) Navmesh for 3D GridMaps @@ -216,10 +216,10 @@ The following script creates a new 3D navmesh from the mesh of a GridMap item, c .. code-tab:: gdscript GDScript extends GridMap - + # enable navmesh for grid items set_bake_navigation(true) - + # get mesh from grid item, bake and set a new navmesh for the library var gridmap_item_list : PackedInt32Array = mesh_library.get_item_list() for item in gridmap_item_list: @@ -228,10 +228,10 @@ The following script creates a new 3D navmesh from the mesh of a GridMap item, c navmesh.create_from_mesh(item_mesh) mesh_library.set_item_navmesh(item, item_mesh) mesh_library.set_item_navmesh_transform(item, Transform3D()) - + # clear the cells clear() - + # add procedual cells using the first item var _position : Vector3i = Vector3i(global_transform.origin) var _item : int = 0 diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst index 9af2c2a6c..5b3bee857 100644 --- a/tutorials/scripting/gdscript/gdscript_basics.rst +++ b/tutorials/scripting/gdscript/gdscript_basics.rst @@ -1161,6 +1161,7 @@ be manipulated by calling methods on the loop variable. for node in node_array: node.add_to_group("Cool_Group") # This has an effect + match ^^^^^ diff --git a/tutorials/shaders/compute_shaders.rst b/tutorials/shaders/compute_shaders.rst index cc566db77..415ecc82e 100644 --- a/tutorials/shaders/compute_shaders.rst +++ b/tutorials/shaders/compute_shaders.rst @@ -39,7 +39,7 @@ Let's take a look at this compute shader code: #[compute] #version 450 - // Invocations in the (x, y, z) dimension + // Invocations in the (x, y, z) dimension layout(local_size_x = 2, local_size_y = 1, local_size_z = 1) in; // A binding to the buffer we create in our script @@ -85,7 +85,7 @@ After that we can load the newly created shader file "compute_example.glsl" and var shader_file := load("res://compute_example.glsl") var shader_spirv: RDShaderSPIRV = shader_file.get_spirv() var shader := rd.shader_create_from_spirv(shader_spirv) - + .. code-tab:: csharp // Load GLSL shader @@ -110,18 +110,18 @@ So let's initialize an array of doubles and create a storage buffer: # Prepare our data. We use doubles in the shader, so we need 64 bit. var input := PackedFloat64Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) var input_bytes := input.to_byte_array() - + # Create a storage buffer that can hold our double values. # Each double has 8 byte (64 bit) so 10 x 8 = 80 bytes var buffer := rd.storage_buffer_create(input_bytes.size(), input_bytes) - + .. code-tab:: csharp // Prepare our data. We use doubles in the shader, so we need 64 bit. var input = new double[] { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; var inputBytes = new byte[input.Length * sizeof(double)]; Buffer.BlockCopy(input, 0, inputBytes, 0, inputBytes.Length); - + // Create a storage buffer that can hold our double values. // Each double has 8 byte (64 bit) so 10 x 8 = 80 bytes var buffer = rd.StorageBufferCreate((uint)inputBytes.Length, inputBytes); @@ -138,9 +138,9 @@ To do that we will need to create a uniform (like in normal shaders) and assign uniform.binding = 0 # this needs to match the "binding" in our shader file uniform.add_id(buffer) var uniform_set := rd.uniform_set_create([uniform], shader, 0) # the last parameter (the 0) needs to match the "set" in our shader file - + .. code-tab:: csharp - + // Create a uniform to assign the buffer to the rendering device var uniform = new RDUniform { @@ -156,7 +156,7 @@ Defining a compute pipeline The next step is to create a set of instructions our GPU can execute. We need a pipeline and a compute list for that. -The steps we need to do to compute our result are: +The steps we need to do to compute our result are: 1. Create a new pipeline. 2. Begin a list of instructions for our GPU to execute. @@ -175,9 +175,9 @@ The steps we need to do to compute our result are: rd.compute_list_bind_uniform_set(compute_list, uniform_set, 0) rd.compute_list_dispatch(compute_list, 5, 1, 1) rd.compute_list_end() - + .. code-tab:: csharp - + // Create a compute pipeline var pipeline = rd.ComputePipelineCreate(shader); var computeList = rd.ComputeListBegin(); @@ -205,19 +205,19 @@ To execute our compute shader we just need to submit the pipeline to the GPU and # Submit to GPU and wait for sync rd.submit() rd.sync() - + .. code-tab:: csharp - + // Submit to GPU and wait for sync rd.Submit(); rd.Sync(); -Ideally, you would not synchronize the RenderingDevice right away as it will cause the CPU to wait for the GPU to finish working. In our example we synchronize right away because we want our data available for reading right away. In general, you will want to wait at least a few frames before synchronizing so that the GPU is able to run in parellel with the CPU. +Ideally, you would not synchronize the RenderingDevice right away as it will cause the CPU to wait for the GPU to finish working. In our example we synchronize right away because we want our data available for reading right away. In general, you will want to wait at least a few frames before synchronizing so that the GPU is able to run in parellel with the CPU. Congratulations you created and executed a compute shader. But wait, where are the results now? Retrieving results ------------------ +------------------ You may remember from the beginning of this tutorial that compute shaders don't have inputs and outputs, they simply change memory. This means we can retrieve the data from our buffer we created at the start of this tutorial. The shader read from our array and stored the data in the same array again so our results are already there. @@ -231,7 +231,7 @@ Let's retrieve the data and print the results to our console. var output := output_bytes.to_float64_array() print("Input: ", input) print("Output: ", output) - + .. code-tab:: csharp // Read back the data from the buffers @@ -244,4 +244,4 @@ Let's retrieve the data and print the results to our console. Conclusion ---------- -Working with compute shaders is a little cumbersome to start, but once you have the basics working in your program you can scale up the complexity of your shader without making many changes to your script. +Working with compute shaders is a little cumbersome to start, but once you have the basics working in your program you can scale up the complexity of your shader without making many changes to your script.