modify readback API

lib/RefreshCS

@@ -1 +1 @@
-Subproject commit 7465d4d4de1a0f2c5de5a2d0b3240671e83776d1
+Subproject commit 859675dbab86e6eeda662ef9bdb0c688cce4cec3

src/Graphics/CommandBuffer.cs

@@ -1950,100 +1950,6 @@ namespace MoonWorks.Graphics
 			);
 		}
 
-		/// <summary>
-		/// Downloads data from a Texture to a TransferBuffer.
-		/// This copy occurs on the GPU timeline.
-		///
-		/// You MAY NOT assume that the data in the TransferBuffer is
-		/// fully copied until the command buffer has finished execution.
-		/// </summary>
-		public void DownloadFromTexture(
-			in TextureRegion textureRegion,
-			TransferBuffer transferBuffer,
-			in BufferImageCopy copyParams,
-			TransferOptions option
-		) {
-#if DEBUG
-			AssertNotSubmitted();
-			AssertInCopyPass("Cannot download from texture outside of copy pass!");
-			AssertBufferBoundsCheck(transferBuffer.Size, copyParams.BufferOffset, textureRegion.Size);
-#endif
-
-			Refresh.Refresh_DownloadFromTexture(
-				Device.Handle,
-				Handle,
-				textureRegion.ToRefreshTextureRegion(),
-				transferBuffer.Handle,
-				copyParams.ToRefresh(),
-				(Refresh.TransferOptions) option
-			);
-		}
-
-		/// <summary>
-		/// Downloads the contents of a Texture with no mips into a TransferBuffer.
-		/// </summary>
-		public void DownloadFromTexture(
-			Texture texture,
-			TransferBuffer transferBuffer,
-			TransferOptions option
-		) {
-			DownloadFromTexture(
-				new TextureRegion(texture),
-				transferBuffer,
-				new BufferImageCopy(0, 0, 0),
-				option
-			);
-		}
-
-		/// <summary>
-		/// Downloads data from a GpuBuffer to a TransferBuffer.
-		/// This copy occurs on the GPU timeline.
-		///
-		/// You MAY NOT assume that the data in the TransferBuffer is
-		/// fully copied until the command buffer has finished execution.
-		/// </summary>
-		public void DownloadFromBuffer(
-			GpuBuffer gpuBuffer,
-			TransferBuffer transferBuffer,
-			in BufferCopy copyParams,
-			TransferOptions option
-		) {
-#if DEBUG
-			AssertNotSubmitted();
-			AssertInCopyPass("Cannot download from texture outside of copy pass!");
-			AssertBufferBoundsCheck(transferBuffer.Size, copyParams.DstOffset, copyParams.Size);
-#endif
-
-			Refresh.Refresh_DownloadFromBuffer(
-				Device.Handle,
-				Handle,
-				gpuBuffer.Handle,
-				transferBuffer.Handle,
-				copyParams.ToRefresh(),
-				(Refresh.TransferOptions) option
-			);
-		}
-
-		/// <summary>
-		/// Downloads data from a GpuBuffer to a TransferBuffer.
-		/// This copy occurs on the GPU timeline.
-		///
-		/// You MAY NOT assume that the data in the TransferBuffer is
-		/// fully copied until the command buffer has finished execution.
-		/// </summary>
-		public void DownloadFromBuffer(
-			GpuBuffer gpuBuffer,
-			TransferBuffer transferBuffer,
-			TransferOptions option
-		) {
-			DownloadFromBuffer(
-				gpuBuffer,
-				transferBuffer,
-				new BufferCopy(0, 0, gpuBuffer.Size),
-				option
-			);
-		}
-
 		/// <summary>
 		/// Copies the contents of a TextureSlice to another TextureSlice.
 		/// The slices must have the same dimensions.

src/Graphics/GraphicsDevice.cs

@@ -467,6 +467,118 @@ namespace MoonWorks.Graphics
 			FencePool.Return(fence);
 		}
 
+		/// <summary>
+		/// ⚠️⚠️⚠️ <br/>
+		/// Downloads data from a Texture to a TransferBuffer.
+		/// This copy occurs immediately on the CPU timeline.<br/>
+		///
+		/// If you modify this texture in a command buffer and then call this function without calling
+		/// SubmitAndAcquireFence and WaitForFences first, the results will not be what you expect.<br/>
+		///
+		/// This method forces a sync point and is generally a bad thing to do.
+		/// Only use it if you have exhausted all other options.<br/>
+		///
+		/// Remember: friends don't let friends readback.<br/>
+		/// ⚠️⚠️⚠️
+		/// </summary>
+		public void DownloadFromTexture(
+			in TextureRegion textureRegion,
+			TransferBuffer transferBuffer,
+			in BufferImageCopy copyParams,
+			TransferOptions transferOption
+		) {
+			Refresh.Refresh_DownloadFromTexture(
+				Handle,
+				textureRegion.ToRefreshTextureRegion(),
+				transferBuffer.Handle,
+				copyParams.ToRefresh(),
+				(Refresh.TransferOptions) transferOption
+			);
+		}
+
+		/// <summary>
+		/// ⚠️⚠️⚠️ <br/>
+		/// Downloads all data from a 2D texture with no mips to a TransferBuffer.
+		/// This copy occurs immediately on the CPU timeline.<br/>
+		///
+		/// If you modify this texture in a command buffer and then call this function without calling
+		/// SubmitAndAcquireFence and WaitForFences first, the results will not be what you expect.<br/>
+		///
+		/// This method forces a sync point and is generally a bad thing to do.
+		/// Only use it if you have exhausted all other options.<br/>
+		///
+		/// Remember: friends don't let friends readback.<br/>
+		/// ⚠️⚠️⚠️
+		/// </summary>
+		public void DownloadFromTexture(
+			Texture texture,
+			TransferBuffer transferBuffer,
+			TransferOptions transferOption
+		) {
+			DownloadFromTexture(
+				new TextureRegion(texture),
+				transferBuffer,
+				new BufferImageCopy(0, 0, 0),
+				transferOption
+			);
+		}
+
+		/// <summary>
+		/// ⚠️⚠️⚠️ <br/>
+		/// Downloads data from a GpuBuffer to a TransferBuffer.
+		/// This copy occurs immediately on the CPU timeline.<br/>
+		///
+		/// If you modify this GpuBuffer in a command buffer and then call this function without calling
+		/// SubmitAndAcquireFence and WaitForFences first, the results will not be what you expect.<br/>
+		///
+		/// This method forces a sync point and is generally a bad thing to do.
+		/// Only use it if you have exhausted all other options.<br/>
+		///
+		/// Remember: friends don't let friends readback.<br/>
+		/// ⚠️⚠️⚠️
+		/// </summary>
+		public void DownloadFromBuffer(
+			GpuBuffer gpuBuffer,
+			TransferBuffer transferBuffer,
+			in BufferCopy copyParams,
+			TransferOptions transferOption
+		) {
+			Refresh.Refresh_DownloadFromBuffer(
+				Handle,
+				gpuBuffer.Handle,
+				transferBuffer.Handle,
+				copyParams.ToRefresh(),
+				(Refresh.TransferOptions) transferOption
+			);
+		}
+
+		/// <summary>
+		/// ⚠️⚠️⚠️ <br/>
+		/// Downloads all data in a GpuBuffer to a TransferBuffer.
+		/// This copy occurs immediately on the CPU timeline.<br/>
+		///
+		/// If you modify this GpuBuffer in a command buffer and then call this function without calling
+		/// SubmitAndAcquireFence and WaitForFences first, the results will not be what you expect.<br/>
+		///
+		/// This method forces a sync point and is generally a bad thing to do.
+		/// Only use it if you have exhausted all other options.<br/>
+		///
+		/// Remember: friends don't let friends readback.<br/>
+		/// ⚠️⚠️⚠️
+		/// </summary>
+		public void DownloadFromBuffer(
+			GpuBuffer gpuBuffer,
+			TransferBuffer transferBuffer,
+			TransferOptions option
+		) {
+			DownloadFromBuffer(
+				gpuBuffer,
+				transferBuffer,
+				new BufferCopy(0, 0, gpuBuffer.Size),
+				option
+			);
+		}
+
 		private TextureFormat GetSwapchainFormat(Window window)
 		{
 			return (TextureFormat) Refresh.Refresh_GetSwapchainFormat(Handle, window.Handle);