Proposal: Add MutateAsync() support.

[icanhasjonas]

While Mutate() is great the way it is, there's already internal support for Async Visitors in ImageSharp.

Adding MutateAsync() would allow the inner mutate loop to load external resources one by one, instead of loading all up front before the mutate, therefore limiting resource usage a ton.

I would add this feature my self, externally, but Configuration.ImageOperationsProvider is marked internal, so I feel there is a resonable case for adding MutateAsync() without adding too much new surface for maintenance.

I have a proposal PR ready at (https://github.com/SixLabors/ImageSharp/pull/2464/files)

[antonfirsov]

would allow the inner mutate loop to load external resources one by one, instead of loading all up front before the mutate

Can you please provide a code example that demonstrates this? (How does upfront loading look like vs how would it look like with MutateAsync().)

[icanhasjonas]

Sure, two quick examples, with and without async mutate()

Example of non async Mutate() where all external assets/layers in this case, are loaded up front and disposed after the Mutate() is complete.

		var layerImages = new List<Image>(); 
		using var resultImage = new Image<Abgr32>(1024, 1024, new Abgr32());
		try {
			foreach( var model in assetLayers ) {
				await using var stream = await _httpClient.GetStreamAsync(model.ImageUrl;);
				layerImages.Add(await Image.LoadAsync(stream));
			}

			resultImage.Mutate(x => {
				var graphicsOptions = new GraphicsOptions {
					AlphaCompositionMode = PixelAlphaCompositionMode.SrcOver,
				};

				foreach( var layer in layerImages ) {
					// MARK: Here would be a great spot to load each asset at a time,
					//     and merge it with the resultImage, then dispose of the asset
					x.DrawImage(layer, new Point(0, 0), graphicsOptions);
				}
			});
		}
		finally {
			// We obviously need to dispose all images after use
			foreach( var x in layerImages ) {
				x.Dispose();
			}
		}

Same example, but with proposed MutateAsync()

		using var resultImage = new Image<Abgr32>(1024, 1024, new Abgr32());
		await resultImage.MutateAsync( async x => {
			var graphicsOptions = new GraphicsOptions {
				AlphaCompositionMode = PixelAlphaCompositionMode.SrcOver,
			};
			foreach( var model in assetLayers ) {
				await using var stream = await _httpClient.GetStreamAsync(assetModel.ImageUrl;);
				using var layer = await Image.LoadAsync(stream);
				x.DrawImage(layer, new Point(0, 0), graphicsOptions);
			}
		});

[tocsoft]

could you not just use this pattern instead? just call Mutate(..) multiple times.

using var resultImage = new Image<Abgr32>(1024, 1024, new Abgr32());
var graphicsOptions = new GraphicsOptions {
    AlphaCompositionMode = PixelAlphaCompositionMode.SrcOver,
};
foreach( var model in assetLayers ) {
    await using var stream = await _httpClient.GetStreamAsync(assetModel.ImageUrl);
    using var layer = await Image.LoadAsync(stream);
    resultImage.Mutate(x => x.DrawImage(layer, new Point(0, 0), graphicsOptions))
}

[icanhasjonas]

(As an alternative, I propose Configuration.ImageOperationsProvider, IImageProcessingContextFactory and IInternalImageProcessingContext<TPixel> be made public. That way any async shenanigans can be user implemented 🥳 at the risk of braking public interfaces in future plans, ofc)

[icanhasjonas]

could you not just use this pattern instead? just call Mutate(..) multiple times.

I guess that works actually.