From d9c3826b21cc4b1af8e04c950f5f3d7ae1da4df8 Mon Sep 17 00:00:00 2001
From: Jordan Halase <jordan@halase.me>
Date: Sat, 26 Oct 2019 15:13:43 -0500
Subject: Add comments for Pugl

---
 Makefile |  1 +
 main.c   | 42 ++++++++++++++++++++++++++++++++++--------
 2 files changed, 35 insertions(+), 8 deletions(-)

diff --git a/Makefile b/Makefile
index e7e4d85..c2d96e6 100644
--- a/Makefile
+++ b/Makefile
@@ -6,6 +6,7 @@ GLSLC=glslc
 CFLAGS=-I$(VULKAN_SDK)/include $(FEATURE) $(DEBUG) $(WARN)
 LDFLAGS=-L$(VULKAN_SDK)/lib -lvulkan
 
+# XXX: Pugl branch location
 CFLAGS+=-I../pugl
 LDFLAGS+=-L../pugl/build -lpugl_x11
 
diff --git a/main.c b/main.c
index 9f5f10a..56e790c 100644
--- a/main.c
+++ b/main.c
@@ -187,6 +187,7 @@ static VkPhysicalDeviceProperties deviceProperties;
 
 static VmaAllocator vmaAllocator;
 
+//SDL_Window *win;
 PuglWorld *world;
 PuglView *view;
 static VkDevice device;
@@ -544,6 +545,7 @@ static void freeCommandBuffers()
 	}
 }
 
+// Kludge over SDL_Vulkan_GetDrawableSize()
 void getFrame(PuglView *view, int *width, int *height)
 {
 	const PuglRect rect = puglGetFrame(view);
@@ -941,6 +943,14 @@ void initVulkan()
 #else
 #include "pugl/detail/x11.h"
 	// HACK: Vulkan needs access to this
+	// Eventually, Pugl should wrap the call to XXX, where XXX is one of:
+	// * vkCreateXlibSurfaceKHR()
+	// * vkCreateWin32SurfaceKHR()
+	// * vkCreateMacOSSurfaceMVK() (using MoltenVK compatibility over Metal)
+	// * possibly (?) others in the future
+	// However, it should do it differently than how SDL does it, because SDL loads the Vulkan Loader
+	// using hidden global state, which goes against Pugl's embedded model.
+	// This could be negotiated at a later time.
 	const VkXlibSurfaceCreateInfoKHR createInfo = {
 		.sType = VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR,
 		.dpy = ((struct PuglWorldImpl*)world)->impl->display,
@@ -1605,6 +1615,11 @@ void teardownScene()
 	destroyUniformBuffer();
 }
 
+// This may look like it's drawing, but it's not.
+// This is pre-recording drawing commands into a buffer
+// that can be submitted to the GPU over and over again.
+// Of course, this could instead happen inside of `onDisplay`
+// if drawing commands vary per-frame.
 void recordCommandBuffers()
 {
 	VkClearValue clearValues[3] = {{
@@ -1663,18 +1678,23 @@ void recordCommandBuffers()
 	}
 }
 
+// TODO:  Vulkan swapchains can be created by "realloc"-ing an existing swapchain.
+//        However, data connected to the old swapchain must not be deleted until
+//        they are no longer in-flight, so we accumulate garbage.
+//        The easy solution is to simply wait for device idle and then delete then recreate everything,
+//        but user interfaces expect the ability to drag-resize quickly and without graphical glitches or stuttering.
 // FIXME: Memory leak
 void recreateSwapchain()
 {
 	oldRawSwapchain = rawSwapchain;
-	destroyGraphicsPipeline();
+	//destroyGraphicsPipeline();
 
 	// endVulkan();
-	destroySwapchainFramebuffers();
-	destroyRenderPass();
-	if (msaaEnabled) destroyMultisampleImage();
-	destroyDepthImage();
-	destroySwapchainImageViews();
+	//destroySwapchainFramebuffers();
+	//destroyRenderPass();
+	//if (msaaEnabled) destroyMultisampleImage();
+	//destroyDepthImage();
+	//destroySwapchainImageViews();
 	//destroySwapchain();
 
 	// beginVulkan();
@@ -1691,10 +1711,12 @@ void recreateSwapchain()
 	recordCommandBuffers();
 }
 
+/** BEGIN APPLICATION SECTION *****************************************************************************************/
+
 float angle = 0.0f;
 uint32_t syncIndex;
 float location[4][4];
-void *data;
+void *data;	// Persistent memory map to GPU uniform buffer
 uint32_t imageIndex;
 
 PuglStatus onResize(PuglView *view)
@@ -1703,6 +1725,8 @@ PuglStatus onResize(PuglView *view)
 	//SDL_Vulkan_GetDrawableSize(win, &width, &height);
 	//int width, height;
 	//getFrame(view, &width, &height);
+
+	/* Apparently Vulkan already knows the new size internally and doesn't need it passed */
 	recreateSwapchain();
 	/* Adjust aspect ratio */
 	load_perspective(
@@ -1712,6 +1736,8 @@ PuglStatus onResize(PuglView *view)
 			);
 }
 
+// Draws one frame to an image acquired from the swapchain	(vkAcquireNextImageKHR, vkQueueSubmitKHR)
+// and then gives it to the presentation engine for displaying	(vkQueuePresentKHR)
 PuglStatus onDisplay(PuglView *view)
 {
 	float rotation[4][4];
@@ -1899,7 +1925,7 @@ int main(int argc, char **argv)
 		puglPollEvents(world, -1);
 		puglDispatchEvents(world);
 	}
-quit:
+
 	cleanup();
 	//SDL_Quit();
 	return 0;
-- 
cgit v1.2.1