committing requested changes in stages.

gpx1000 · gpx1000 · commit 4b4a24349a0f · 2025-08-15T13:22:04.000-07:00
diff --git a/en/Building_a_Simple_Engine/Mobile_Development/01_introduction.adoc b/en/Building_a_Simple_Engine/Mobile_Development/01_introduction.adoc
@@ -1,13 +1,6 @@
-::pp: {plus}{plus}
+:pp: {plus}{plus}
 
 = Mobile Development: Introduction
-:doctype: book
-:sectnums:
-:sectnumlevels: 4
-:toc: left
-:icons: font
-:source-highlighter: highlightjs
-:source-language: c++
 
 == Introduction to Mobile Development
 
@@ -17,23 +10,21 @@ Mobile development presents unique challenges and opportunities for Vulkan appli
 
 === What We'll Cover
 
-In this chapter, we'll explore:
+This chapter will guide you through the complex landscape of mobile Vulkan development, where desktop assumptions often don't apply. We'll start by examining the platform-specific requirements of Android and iOS, which present unique challenges in setup, lifecycle management, and input handling. Mobile applications face constraints that desktop applications rarely encounter—sudden interruptions, battery concerns, and varying hardware capabilities all require careful consideration in your engine design.
 
-* *Platform Considerations for Android and iOS*: We'll discuss the specific requirements and constraints of developing Vulkan applications for Android and iOS, including platform-specific setup, lifecycle management, and input handling.
+Performance optimization takes on critical importance in mobile environments where every watt of power consumption and every millisecond of frame time affects user experience. We'll explore essential techniques like power-of-two texture usage and efficient texture formats, along with mobile-specific optimizations that can mean the difference between smooth performance and user frustration.
 
-* *Performance Optimizations for Mobile*: We'll explore techniques for optimizing your engine for mobile hardware, focusing on power-of-two textures, efficient texture formats, and other mobile-specific optimizations.
+Understanding the fundamental architectural differences between mobile and desktop GPUs becomes essential for effective optimization. We'll compare Tile-Based Rendering (TBR) and Immediate Mode Rendering (IMR) approaches, helping you understand why techniques that work well on desktop might perform poorly on mobile, and how to design rendering strategies that leverage mobile GPU strengths.
 
-* *Rendering Approaches*: We'll compare Tile-Based Rendering (TBR) and Immediate Mode Rendering (IMR), understanding their implications for mobile GPU architectures.
-
-* *Vulkan Extensions for Mobile*: We'll explore extensions like VK_KHR_dynamic_rendering_local_read, VK_KHR_dynamic_rendering, and VK_EXT_shader_tile_image that can significantly improve performance on mobile devices.
+Finally, we'll explore the Vulkan extensions specifically designed for mobile platforms. Extensions like VK_KHR_dynamic_rendering_local_read, VK_KHR_dynamic_rendering, and VK_EXT_shader_tile_image unlock performance opportunities that can dramatically improve your application's efficiency on mobile hardware, transforming acceptable performance into exceptional user experiences.
 
 === Prerequisites
 
-Before diving into this chapter, you should be familiar with:
+This chapter represents the culmination of everything we've built throughout the previous chapters, as mobile development requires deep integration with all engine systems. You'll need solid mastery of Vulkan fundamentals and the engine architecture we've developed, since mobile optimization often requires fine-tuning at every level—from resource management and rendering pipelines to memory allocation and synchronization.
+
+Modern C++ expertise becomes particularly valuable in mobile development, where performance constraints demand efficient code and careful resource management. C++17 and C++20 features like constexpr, structured bindings, and concepts help create mobile-optimized code that performs well under strict power and thermal limitations.
 
-* The basics of Vulkan and our engine architecture from previous chapters
-* Modern C++ concepts, particularly those introduced in C++17 and C++20
-* Basic understanding of mobile development concepts
+Understanding basic mobile development concepts will provide crucial context for the platform-specific decisions we'll make. Mobile applications operate under constraints that desktop applications rarely face—app lifecycle events, varying screen densities, touch input paradigms, and the need to preserve battery life all influence how we design and implement our Vulkan engine for mobile platforms.
 
 Let's begin by exploring the platform considerations for Android and iOS.
 
diff --git a/en/Building_a_Simple_Engine/Mobile_Development/02_platform_considerations.adoc b/en/Building_a_Simple_Engine/Mobile_Development/02_platform_considerations.adoc
@@ -1,13 +1,6 @@
-::pp: {plus}{plus}
+:pp: {plus}{plus}
 
 = Mobile Development: Platform Considerations
-:doctype: book
-:sectnums:
-:sectnumlevels: 4
-:toc: left
-:icons: font
-:source-highlighter: highlightjs
-:source-language: c++
 
 == Platform Considerations for Android and iOS
 
diff --git a/en/Building_a_Simple_Engine/Mobile_Development/03_performance_optimizations.adoc b/en/Building_a_Simple_Engine/Mobile_Development/03_performance_optimizations.adoc
@@ -1,20 +1,24 @@
-::pp: {plus}{plus}
+:pp: {plus}{plus}
 
 = Mobile Development: Performance Optimizations
-:doctype: book
-:sectnums:
-:sectnumlevels: 4
-:toc: left
-:icons: font
-:source-highlighter: highlightjs
-:source-language: c++
 
 == Performance Optimizations for Mobile
 
 Mobile devices have significantly different hardware constraints compared to desktop systems. In this section, we'll explore key performance optimizations that are essential for achieving good performance on mobile platforms.
 
 === Texture Optimizations
 
+To keep the workflow concrete and digestible, think of texture optimization in three steps:
+
+1) Step 1: Ensure power‑of‑two (POT) dimensions (resize if needed)
+2) Step 2: Pick a hardware‑compressed format supported by the device (ASTC → ETC2 → BC → fallback)
+3) Step 3: Upload/update the Vulkan image and clean up staging resources
+
+[NOTE]
+====
+We focus on mobile‑specific decisions here. For general Vulkan image creation, staging uploads, and descriptor setup, refer back to earlier chapters in the engine series—link:../Engine_Architecture/04_resource_management.adoc[Resource Management], link:../Engine_Architecture/05_rendering_pipeline.adoc[Rendering Pipeline]—or the Vulkan Guide (https://docs.vulkan.org/guide/latest/).
+====
+
 Textures are often the largest consumers of memory in a graphics application. Optimizing them is crucial for mobile performance.
 
 ==== Power-of-Two Textures
diff --git a/en/Building_a_Simple_Engine/Mobile_Development/04_rendering_approaches.adoc b/en/Building_a_Simple_Engine/Mobile_Development/04_rendering_approaches.adoc
@@ -1,13 +1,6 @@
-::pp: {plus}{plus}
+:pp: {plus}{plus}
 
 = Mobile Development: Rendering Approaches
-:doctype: book
-:sectnums:
-:sectnumlevels: 4
-:toc: left
-:icons: font
-:source-highlighter: highlightjs
-:source-language: c++
 
 == Rendering Approaches for Mobile GPUs
 
diff --git a/en/Building_a_Simple_Engine/Mobile_Development/05_vulkan_extensions.adoc b/en/Building_a_Simple_Engine/Mobile_Development/05_vulkan_extensions.adoc
@@ -1,13 +1,6 @@
-::pp: {plus}{plus}
+:pp: {plus}{plus}
 
 = Mobile Development: Vulkan Extensions
-:doctype: book
-:sectnums:
-:sectnumlevels: 4
-:toc: left
-:icons: font
-:source-highlighter: highlightjs
-:source-language: c++
 
 == Vulkan Extensions for Mobile
 
@@ -25,9 +18,13 @@ The `VK_KHR_dynamic_rendering` extension (now part of Vulkan 1.3 core) allows yo
 2. *Enables More Flexible Rendering*: Makes it easier to implement techniques that don't fit well into the traditional render pass model.
 3. *Reduces API Overhead*: Fewer objects to create and manage means less CPU overhead.
 
-==== Implementation
+==== Implementation (Step-by-step)
+
+Let's break the setup into a few small, focused steps.
+
+===== Enable the extension and load entry points
 
-Here's how to use dynamic rendering:
+We first enable the device extension and, if you're not on Vulkan 1.3 core, load the function pointers.
 
 [source,cpp]
 ----
@@ -44,8 +41,16 @@ PFN_vkCmdBeginRenderingKHR vkCmdBeginRenderingKHR =
 PFN_vkCmdEndRenderingKHR vkCmdEndRenderingKHR =
     reinterpret_cast<PFN_vkCmdEndRenderingKHR>(
         vkGetDeviceProcAddr(device, "vkCmdEndRenderingKHR"));
+----
+
+This prepares your device to use dynamic rendering and gives access to the commands needed to begin/end a rendering scope without a traditional render pass.
+
+===== Describe attachments for this rendering scope
 
-// Begin rendering
+We define the color and depth attachments and package them into a VkRenderingInfoKHR. Think of this as an inline, one-off description of what would normally be baked into render pass/framebuffer objects.
+
+[source,cpp]
+----
 VkRenderingAttachmentInfoKHR color_attachment{};
 color_attachment.sType = VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO_KHR;
 color_attachment.imageView = color_image_view;
@@ -69,7 +74,16 @@ rendering_info.layerCount = 1;
 rendering_info.colorAttachmentCount = 1;
 rendering_info.pColorAttachments = &color_attachment;
 rendering_info.pDepthAttachment = &depth_attachment;
+----
+
+Each frame (or subpass-equivalent), you can tweak these descriptors directly (e.g., swapchain views after resize), avoiding pipeline-wide re-creation.
 
+===== Begin rendering, draw, end rendering
+
+With the attachments described, we open the rendering scope, record draws, then close the scope.
+
+[source,cpp]
+----
 vkCmdBeginRenderingKHR(command_buffer, &rendering_info);
 
 // Record drawing commands
@@ -80,7 +94,11 @@ vkCmdDraw(command_buffer, vertex_count, 1, 0, 0);
 vkCmdEndRenderingKHR(command_buffer);
 ----
 
-When using C++ bindings:
+The begin/end pair replaces vkCmdBeginRenderPass/vkCmdEndRenderPass while providing more flexibility for modern rendering flows.
+
+===== C++ bindings (vulkan.hpp) variant
+
+If you're using vulkan.hpp (vk::), the structure population is more ergonomic but follows the same steps.
 
 [source,cpp]
 ----
@@ -104,7 +122,12 @@ rendering_info.setRenderArea(render_area);
 rendering_info.setLayerCount(1);
 rendering_info.setColorAttachments(color_attachment);
 rendering_info.setPDepthAttachment(&depth_attachment);
+----
+
+Once the description is assembled, begin the rendering scope, submit draws, and end the scope.
 
+[source,cpp]
+----
 command_buffer.beginRenderingKHR(rendering_info);
 
 // Record drawing commands
diff --git a/en/Building_a_Simple_Engine/Mobile_Development/06_conclusion.adoc b/en/Building_a_Simple_Engine/Mobile_Development/06_conclusion.adoc
@@ -1,13 +1,6 @@
-::pp: {plus}{plus}
+:pp: {plus}{plus}
 
 = Mobile Development: Conclusion
-:doctype: book
-:sectnums:
-:sectnumlevels: 4
-:toc: left
-:icons: font
-:source-highlighter: highlightjs
-:source-language: c++
 
 == Conclusion
 
diff --git a/en/Building_a_Simple_Engine/Mobile_Development/index.adoc b/en/Building_a_Simple_Engine/Mobile_Development/index.adoc
@@ -1,13 +1,7 @@
-::pp: {plus}{plus}
+:pp: {plus}{plus}
 
 = Mobile Development
-:doctype: book
-:sectnums:
-:sectnumlevels: 4
-:toc: left
-:icons: font
-:source-highlighter: highlightjs
-:source-language: c++
+
 
 This chapter covers the essential aspects of adapting your Vulkan engine for mobile platforms, focusing on Android and iOS development, performance optimizations, rendering approaches, and mobile-specific Vulkan extensions.
 
