Updated tutorial to latest task graph

Ipotrick · Ipotrick · commit b3e253a2fbc6 · 2025-10-29T23:34:18.000+01:00
diff --git a/src/content/docs/tutorial/02 Drawing a triangle/06 Buffers.md b/src/content/docs/tutorial/02 Drawing a triangle/06 Buffers.md
@@ -4,7 +4,7 @@ description: Buffers
 slug: "tutorial/drawing-a-triangle/buffers"
 ---
 
-## Description
+## General
 
 When uploading data to the GPU, OpenGL used target-specific buffer targets (Vertex Object/Array Buffers, etc.). Daxa uses bindless buffers instead. This means a buffer isn't bound to one target only. One buffer can be used in all of these different bind targets and there is therefore only one buffer 'type'.
 
@@ -18,3 +18,29 @@ auto buffer_id = device.create_buffer({
     .name = "my vertex data",
 });
 ```
+
+## Uploading to Buffers
+
+To upload to a buffer in daxa, you query the buffers host pointer. Not all buffers have a host pointer, make sure to set either `MemoryFlagBits::HOST_ACCESS_SEQUENTIAL_WRITE` or `MemoryFlagBits::HOST_ACCESS_RANDOM` as `.allocate_info` when creating the buffer:
+
+```cpp
+auto buffer_id = device.create_buffer({
+    .size = sizeof(MyVertex) * 3,
+    .allocate_info = MemoryFlagBits::HOST_ACCESS_SEQUENTIAL_WRITE,
+    .name = "my vertex data",
+});
+```
+
+* Use `MemoryFlagBits::HOST_ACCESS_SEQUENTIAL_WRITE` for buffers that require fast reads on the gpu and host writes. This type is suboptimal for host readback. Its typically in device vram.
+* Use `MemoryFlagBits::HOST_ACCESS_RANDOM` for buffers that do not need fast access on the gpu but random cpu write and read access. This type is optimal for readback. Its typically in host ram.
+
+Uploading any data itself is then done via direct writes or a memcpy like so:
+
+```cpp
+std::array<MyVertex, 3> * vert_buf_ptr = device.buffer_host_address_as<std::array<MyVertex, 3>>(buffer_id).value();
+*vert_buf_ptr = std::array{
+    MyVertex{.position = {-0.5f, +0.5f, 0.0f}, .color = {1.0f, 0.0f, 0.0f}},
+    MyVertex{.position = {+0.5f, +0.5f, 0.0f}, .color = {0.0f, 1.0f, 0.0f}},
+    MyVertex{.position = {+0.0f, -0.5f, 0.0f}, .color = {0.0f, 0.0f, 1.0f}},
+};~
+```
diff --git a/src/content/docs/tutorial/02 Drawing a triangle/07 Task graph.md b/src/content/docs/tutorial/02 Drawing a triangle/07 Task graph.md
@@ -8,7 +8,7 @@ slug: "tutorial/drawing-a-triangle/task-graph"
 
 While not entirely necessary, we're going to use TaskGraph, which allows us to compile a list of GPU tasks and their dependencies into a synchronized set of commands. This simplifies your code by making different tasks completely self-contained, while also generating the most optimal synchronization for the tasks you describe. To use TaskGraph, as its also an optional feature, add the include path `<daxa/utils/task_graph.hpp>` at the top of our main file.
 
-## Creating a vertex uploading task
+## Creating a Rendering task
 
 Before we can use a task graph, we first need to create actual tasks that can be executed. The first task we are going to create will upload vertex data to the GPU.
 
@@ -17,105 +17,65 @@ Each task struct must consist of a child struct 'Uses' that will store all share
 For our task, this base task structure will look like this:
 
 ```cpp
-void upload_vertex_data_task(daxa::TaskGraph & tg, daxa::TaskBufferView vertices)
-{
-    tg.add_task({
-        .attachments = {
-            daxa::inl_attachment(daxa::TaskBufferAccess::TRANSFER_WRITE, vertices),
-        },
-        .task = [=](daxa::TaskInterface ti)
-        {
-            // [...]
-        },
+daxa::Task task = daxa::RasterTask("draw task")
+    // adds an attachment:
+    // * stage = color_attachment, 
+    // * access = reads_writes,
+    // * view_type = REGULAR_2D,
+    // * task_image_view =  render_target
+    .color_attachments.reads_writes(daxa::ImageViewType::REGULAR_2D, render_target) 
+    .executes([=](daxa::TaskInterface ti){
+        // this callback is executed later when executing the graph after completing recording.
+        ....
     });
-}
-```
-
-In the `task` callback function, for the sake of brevity, we will create the data we will upload. In this sample, we will use the standard triangle vertices.
-
-```cpp
-auto data = std::array{
-    MyVertex{.position = {-0.5f, +0.5f, 0.0f}, .color = {1.0f, 0.0f, 0.0f}},
-    MyVertex{.position = {+0.5f, +0.5f, 0.0f}, .color = {0.0f, 1.0f, 0.0f}},
-    MyVertex{.position = {+0.0f, -0.5f, 0.0f}, .color = {0.0f, 0.0f, 1.0f}},
-};
-```
-
-To send the data to the GPU, we can create a staging buffer, which has host access, so that we can then issue a command to copy from this buffer to the dedicated GPU memory.
-
-```cpp
-auto staging_buffer_id = ti.device.create_buffer({
-    .size = sizeof(data),
-    .allocate_info = daxa::MemoryFlagBits::HOST_ACCESS_RANDOM,
-    .name = "my staging buffer",
-});
-```
-
-We can also ask the command recorder to destroy this temporary buffer since we don't care about it living, but we DO need it to survive through its usage on the GPU (which won't happen until after these commands are submitted), so we tell the command recorder to destroy it in a deferred fashion.
-
-```cpp
-ti.recorder.destroy_buffer_deferred(staging_buffer_id);
-```
-
-We then get the memory-mapped pointer of the staging buffer, and write the data directly to it.
-
-```cpp
-auto * buffer_ptr = ti.device.buffer_host_address_as<std::array<MyVertex, 3>>(staging_buffer_id).value();
-*buffer_ptr = data;
-ti.recorder.copy_buffer_to_buffer({
-    .src_buffer = staging_buffer_id,
-    .dst_buffer = ti.get(vertices).ids[0],
-    .size = sizeof(data),
-});
+tg.add_task(task);
 ```
 
-## Creating a Rendering task
+For the drawing, we need the following within the execute callback.
 
-We will again create a simple task:
+Within the task callback we have access to the device, a fast transient allocator, a cmd recorder and accessor functions for data around attachments:
 
 ```cpp
-void draw_vertices_task(daxa::TaskGraph & tg, std::shared_ptr<daxa::RasterPipeline> pipeline, daxa::TaskBufferView vertices, daxa::TaskImageView render_target)
+void draw_swapchain_task_callback(daxa::TaskInterface ti, daxa::RasterPipeline * pipeline, daxa::TaskImageView color_target, daxa::BufferId vertex_buffer)
 {
-    tg.add_task({
-        .attachments = {
-            daxa::inl_attachment(daxa::TaskBufferAccess::VERTEX_SHADER_READ, vertices),
-            daxa::inl_attachment(daxa::TaskImageAccess::COLOR_ATTACHMENT, daxa::ImageViewType::REGULAR_2D, render_target),
-        },
-        .task = [=](daxa::TaskInterface ti)
-        {
-            // [...]
+    // The task interface provides a way to get the attachment info:
+    auto image_info = ti.info(color_target).value();
+    auto image_id = ti.id(color_target);
+    auto image_view_id = ti.view(color_target);
+    auto image_layout = ti.layout(color_target);
+
+    // When starting a render pass via a rasterization pipeline, daxa "eats" a generic command recorder
+    // and turns it into a RenderCommandRecorder.
+    // Only the RenderCommandRecorder can record raster commands.
+    // The RenderCommandRecorder can only record commands that are valid within a render pass.
+    // This way daxa ensures typesafety for command recording.
+    daxa::RenderCommandRecorder render_recorder = std::move(ti.recorder).begin_renderpass({
+        .color_attachments = std::array{
+            daxa::RenderAttachmentInfo{
+                .image_view = ti.view(color_target),
+                .load_op = daxa::AttachmentLoadOp::CLEAR,
+                .clear_value = std::array<daxa::f32, 4>{0.1f, 0.0f, 0.5f, 1.0f},
+            },
         },
-        .name = "draw vertices",
+        .render_area = {.width = image_info.size.x, .height = image_info.size.y},
     });
-}
-```
-
-We first need to get the screen width and height in the callback function. We can do this by getting the target image dimensions.
-
-```cpp
-auto const size = ti.device.info(ti.get(render_target).ids[0]).value().size;
-```
-
-Next, we need to record an actual renderpass. The values are pretty self-explanatory if you have used OpenGL before. This contains the actual rendering logic.
-
-```cpp
-daxa::RenderCommandRecorder render_recorder = std::move(ti.recorder).begin_renderpass({
-    .color_attachments = std::array{
-        daxa::RenderAttachmentInfo{
-            .image_view = ti.get(render_target).view_ids[0],
-            .load_op = daxa::AttachmentLoadOp::CLEAR,
-            .clear_value = std::array<daxa::f32, 4>{0.1f, 0.0f, 0.5f, 1.0f},
-        },
-    },
-    .render_area = {.width = size.x, .height = size.y},
-});
+    // Here, we'll bind the pipeline to be used in the draw call below
+    render_recorder.set_pipeline(*pipeline);
+
+    // Very importantly, task graph packs up our attachment shader data into a byte blob.
+    // We need to pass this blob to our shader somehow.
+    // The typical way to do this is to assign the blob to the push constant.
+    render_recorder.push_constant(MyPushConstant{
+        .vertices = ti.device.device_address(vertex_buffer).value(),
+    });
+    // and issue the draw call with the desired number of vertices.
+    render_recorder.draw({.vertex_count = 3});
 
-render_recorder.set_pipeline(*pipeline);
-render_recorder.push_constant(MyPushConstant{
-    .my_vertex_ptr = ti.device.device_address(ti.get(vertices).ids[0]).value(),
-});
-render_recorder.draw({.vertex_count = 3});
-ti.recorder = std::move(render_recorder).end_renderpass();
+    // VERY IMPORTANT! A renderpass must be ended after finishing!
+    // The ending of a render pass returns back the original command recorder.
+    // Assign it back to the task interfaces command recorder.
+    ti.recorder = std::move(render_recorder).end_renderpass();
+};
 ```
 
 ## Creating a Rendering TaskGraph
@@ -128,16 +88,7 @@ Back in our main method, the first we'll make is the swap chain image task resou
 auto task_swapchain_image = daxa::TaskImage{{.swapchain_image = true, .name = "swapchain image"}};
 ```
 
-We will also create a buffer task resource, for our MyVertex buffer buffer_id. We do something a little special here, which is that we set the initial access of the buffer to be vertex shader read, and that's because we'll create a task list that will upload the buffer.
-
-```cpp
-auto task_vertex_buffer = daxa::TaskBuffer({
-    .initial_buffers = {.buffers = std::span{&buffer_id, 1}},
-    .name = "task vertex buffer",
-});
-```
-
-Next, we need to create the actual task graph itself:
+We need to create the actual task graph itself:
 
 ```cpp
 auto loop_task_graph = daxa::TaskGraph({
@@ -149,15 +100,22 @@ auto loop_task_graph = daxa::TaskGraph({
 
 We need to explicitly declare all uses of persistent task resources because manually marking used resources makes it possible to detect errors in your graph recording.
 
+The vertex buffer is read only after initialization, therefor it needs no runtime sync, it should be ignored by the taskgraph and get no attachment in tasks. It should be passed directly via the push constants.
+
 ```cpp
-loop_task_graph.use_persistent_buffer(task_vertex_buffer);
 loop_task_graph.use_persistent_image(task_swapchain_image);
 ```
 
 Since we need the task graph to do something, we add the task that draws to the screen:
 
-```cpp
-draw_vertices_task(loop_task_graph, pipeline, task_vertex_buffer, task_swapchain_image);
+```cpp    
+auto draw_swapchain_task =
+    daxa::RasterTask("draw triangle")
+        .color_attachment.reads_writes(daxa::ImageViewType::REGULAR_2D, task_swapchain_image.view())
+        .executes(draw_swapchain_task_callback, pipeline.get(), buffer_id);
+
+// Insert the task into the graph:
+loop_task_graph.add_task(draw_swapchain_task);
 ```
 
 Once we have added all the tasks we want, we have to tell the task graph we are done.
