Add snippet for demonstrating options to programmatically create images

With the implementation of monitor-specific UI scaling on Windows, an
SWT application does not have a static zoom anymore. The zoom will be
specific for each shell and the monitor it is currently placed on. As a
consequence, when programmatically creating an image, the target zoom at
which it will be used is not known when creating the image anymore.
Instead, it will depend on the context in which the image is used later
on. There are multiple options how to achieve that such an image will
still be rendered at the according zoom in a sharp way instead of
rendering it at an arbitrary zoom and then scaling it in a blurry way.
This snippet demonstrates these different options and also a common way
for programmatic image creation that will lead to blurry results.

Author: HeikoKlare

examples/org.eclipse.swt.snippets/Snippets.md

@@ -216,6 +216,7 @@ To contribute a new snippet, [create a snippet contribution as a pull request](h
 - [draw a disabled/grayed image at various zoom levels](https://github.com/eclipse-platform/eclipse.platform.swt/tree/master/examples/org.eclipse.swt.snippets/src/org/eclipse/swt/snippets/Snippet382.java) – [(preview)](https://github.com/eclipse-platform/eclipse.platform.swt/blob/master/examples/org.eclipse.swt.snippets/previews/Snippet382.png "Preview for Snippet 382")
 - [compare algorithms for rendering disabled images](https://github.com/eclipse-platform/eclipse.platform.swt/tree/master/examples/org.eclipse.swt.snippets/src/org/eclipse/swt/snippets/Snippet384.java) – [(preview)](https://github.com/eclipse-platform/eclipse.platform.swt/blob/master/examples/org.eclipse.swt.snippets/previews/Snippet384.png "Preview for Snippet 384")
 - [draw an image with watermark using ImageGcProvider](https://github.com/eclipse-platform/eclipse.platform.swt/tree/master/examples/org.eclipse.swt.snippets/src/org/eclipse/swt/snippets/Snippet385.java) – [(preview)](https://github.com/eclipse-platform/eclipse.platform.swt/blob/master/examples/org.eclipse.swt.snippets/previews/Snippet385.png "Preview for Snippet 385")
+- [options for programmatically creating an image](https://github.com/eclipse-platform/eclipse.platform.swt/tree/master/examples/org.eclipse.swt.snippets/src/org/eclipse/swt/snippets/Snippet387.java) – [(preview)](https://github.com/eclipse-platform/eclipse.platform.swt/blob/master/examples/org.eclipse.swt.snippets/previews/Snippet387.png "Preview for Snippet 387")
 
 ### **ImageData**
 - [display an animated GIF](https://github.com/eclipse-platform/eclipse.platform.swt/tree/master/examples/org.eclipse.swt.snippets/src/org/eclipse/swt/snippets/Snippet141.java)

examples/org.eclipse.swt.snippets/previews/Snippet387.png

@@ -0,0 +1,112 @@
+/*******************************************************************************
+ * Copyright (c) 2025 Vector Informatik GmbH and others.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License 2.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+package org.eclipse.swt.snippets;
+
+import org.eclipse.swt.graphics.*;
+import org.eclipse.swt.widgets.*;
+
+/**
+ * Demonstrates different ways of programmatically creating an image with a GC
+ * <p>
+ * When creating an image programmatically, it is important to use an
+ * appropriate way of doing that when at the time of image creation it is not
+ * yet known at which zoom the image will be used. This is particularly the case
+ * when using monitor-specific scaling on Windows.
+ * <p>
+ * There are two general options how to programmatically create an image:
+ * <ul>
+ * <li>{@link ImageGcDrawer}: create an image with an {@link ImageGcDrawer};
+ * preferred way as the drawer will be called with the requested zoom when
+ * needed
+ * <li>{@link GC} on image: create an image with fixed dimensions and create a
+ * {@link GC} for the image to drawn on; this is the legacy way of drawing an
+ * image and should only be used if the whole drawing logic cannot be wrapped
+ * into an {@link ImageGcDrawer} but the {@link GC} may be passed around to
+ * collect drawing contributions from different places
+ * </ul>
+ * When using the second approach creating a {@link GC} on top of an image, it
+ * is important to not dispose the GC before using the image, as in that case
+ * the Windows implementation of an image can request its regeneration at the
+ * desired zoom from the GC. If the GC is disposed before the image is used at
+ * desired zoom, it may need to blurry-scale any existing drawing result to the
+ * requested zoom instead of sharply rendering it at that zoom.
+ * <p>
+ * This snippet demonstrates both proper usages of the above mentioned options
+ * as well as a usage that disposes the GC before consuming the image at the
+ * desired zoom, leading to a blurry result. To see such a bad result, the
+ * snippet needs to be executed on Windows and has to be moved between monitors
+ * with different monitor zooms.
+ * <p>
+ * For a list of all SWT example snippets see
+ * http://www.eclipse.org/swt/snippets/
+ * </p>
+ */
+public class Snippet387 {
+
+	private static final int PADDING = 5;
+	private static final int IMAGE_WIDTH = 270;
+	private static final int IMAGE_HEIGHT = 50;
+
+	public static void main(String[] args) {
+		activateMonitorSpecificScaling();
+
+		Display display = new Display();
+		Shell shell = new Shell(display);
+		shell.setText("Programmatic Images");
+		shell.setSize(IMAGE_WIDTH + 2 * PADDING + 20, 3 * IMAGE_HEIGHT + 4 * PADDING + 40);
+
+		Image staticImage = createStaticImage(display, "Static Image with disposed GC", true);
+		Image staticImageUndisposedGC = createStaticImage(display, "Static Image with non-disposed GC", false);
+		Image dynamicImage = createDynamicImage(display, "Dynamic Image");
+
+		shell.addPaintListener(event -> {
+			GC gc = event.gc;
+			gc.drawImage(staticImage, PADDING, PADDING);
+			gc.drawImage(staticImageUndisposedGC, PADDING, 2 * PADDING + IMAGE_HEIGHT);
+			gc.drawImage(dynamicImage, PADDING, 3 * PADDING + 2 * IMAGE_HEIGHT);
+		});
+
+		shell.open();
+		while (!shell.isDisposed()) {
+			if (!display.readAndDispatch()) {
+				display.sleep();
+			}
+		}
+		display.dispose();
+	}
+
+	private static void activateMonitorSpecificScaling() {
+		System.setProperty("swt.autoScale.updateOnRuntime", "true");
+	}
+
+	private static Image createStaticImage(Display display, String text, boolean disposeGC) {
+		Image staticImage = new Image(display, IMAGE_WIDTH, IMAGE_HEIGHT);
+		GC imageGC = new GC(staticImage);
+		try {
+			drawImageContent(imageGC, text, IMAGE_WIDTH, IMAGE_HEIGHT);
+		} finally {
+			if (disposeGC) {
+				imageGC.dispose();
+			}
+		}
+		return staticImage;
+	}
+
+	private static Image createDynamicImage(Display display, String text) {
+		return new Image(display, (gc, w, h) -> drawImageContent(gc, text, w, h), IMAGE_WIDTH, IMAGE_HEIGHT);
+	}
+
+	private static void drawImageContent(GC gc, String text, int width, int height) {
+		gc.drawRectangle(0, 0, width - 1, height - 1);
+		gc.drawText(text, PADDING, PADDING);
+	}
+
+}