JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
ScalableSurface.java
Go to the documentation of this file.
1/**
2 * Copyright 2014-2023 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28
29package com.jogamp.nativewindow;
30
31/**
32 * Adding mutable surface pixel scale property to implementing class, usually to a {@link NativeSurface} implementation,
33 * see {@link #setSurfaceScale(float[])}.
34 */
35public interface ScalableSurface {
36 /** Setting surface-pixel-scale of {@value}, results in same pixel- and window-units. */
37 public static final float IDENTITY_PIXELSCALE = 1f;
38 /** Setting surface-pixel-scale of {@value}, results in maximum platform dependent pixel-scale, i.e. pixel-units >> window-units where available. */
39 public static final float AUTOMAX_PIXELSCALE = 0f;
40
41 /**
42 * Returns true if {@link #setSurfaceScale(float[])} is supported, otherwise false.
43 * <p>
44 * For pure downstream scalable surfaces like AWT widgets,
45 * setting the picel scale is not supported since the pixel scale is set by the underlying toolkit.
46 * </p>
47 */
48 public boolean canSetSurfaceScale();
49
50 /**
51 * Request a pixel scale in x- and y-direction for the associated {@link NativeSurface},
52 * where {@code size_in_pixel_units = pixel_scale * size_in_window_units}.
53 * <p>
54 * Default pixel scale request for both directions is {@link #AUTOMAX_PIXELSCALE}.
55 * </p>
56 * <p>
57 * If {@link #canSetSurfaceScale()} returns false, requested pixel scale is {@link #AUTOMAX_PIXELSCALE},
58 * immutable and method returns false.
59 * </p>
60 * <p>
61 * In case platform only supports uniform pixel scale, i.e. one scale for both directions,
62 * either {@link #AUTOMAX_PIXELSCALE} or the maximum requested pixel scale component is used.
63 * </p>
64 * <p>
65 * The <i>requested</i> pixel scale will be validated against platform limits before native scale-setup,
66 * i.e. clipped to {@link #IDENTITY_PIXELSCALE} if not supported or clipped to the platform maximum.
67 * It can be queried via {@link #getRequestedSurfaceScale(float[])}.
68 * </p>
69 * <p>
70 * The actual <i>realized</i> pixel scale values of the {@link NativeSurface}
71 * can be queried via {@link #getCurrentSurfaceScale(float[])} or
72 * computed via <code>surface.{@link NativeSurface#convertToPixelUnits(int[]) convertToPixelUnits}(new int[] { 1, 1 })</code>
73 * </p>
74 * @param pixelScale <i>requested</i> surface pixel scale float[2] values for x- and y-direction.
75 * @return {@code true} if the {@link #getCurrentSurfaceScale(float[]) current pixel scale} has changed, otherwise {@code false}.
76 * @see #getRequestedSurfaceScale(float[])
77 * @see #canSetSurfaceScale()
78 */
79 public boolean setSurfaceScale(final float[] pixelScale);
80
81 /**
82 * Returns the {@link #setSurfaceScale(float[]) requested} pixel scale of the associated {@link NativeSurface}.
83 * <p>
84 * If {@link #canSetSurfaceScale()} returns false, requested pixel scale is {@link #AUTOMAX_PIXELSCALE} and immutable.
85 * </p>
86 *
87 * @param result float[2] storage for the result
88 * @return the passed storage containing the current pixelScale for chaining
89 * @see #setSurfaceScale(float[])
90 * @see #canSetSurfaceScale()
91 */
92 public float[] getRequestedSurfaceScale(final float[] result);
93
94 /**
95 * Returns the current pixel scale of the associated {@link NativeSurface}.
96 *
97 * @param result float[2] storage for the result
98 * @return the passed storage containing the current pixelScale for chaining
99 */
100 public float[] getCurrentSurfaceScale(final float[] result);
101
102 /**
103 * Returns the minimum pixel scale of the associated {@link NativeSurface}.
104 * @param result float[2] storage for the result
105 * @return the passed storage containing the minimum pixelScale for chaining
106 */
107 public float[] getMinimumSurfaceScale(final float[] result);
108
109 /**
110 * Returns the maximum pixel scale of the associated {@link NativeSurface}.
111 * <p>
112 * The maximum pixel scale maybe used to determine the proper <i>dpi</i>
113 * value of the monitor displaying this {@link NativeSurface}.
114 * <pre>
115 * surfacePpMM = monitorPpMM * currentSurfaceScale / nativeSurfaceScale,
116 * with PpMM == pixel per millimeter
117 * </pre>
118 * </p>
119 *
120 * @param result float[2] storage for the result
121 * @return the passed storage containing the maximum pixelScale for chaining
122 */
123 public float[] getMaximumSurfaceScale(final float[] result);
124}
125
Adding mutable surface pixel scale property to implementing class, usually to a NativeSurface impleme...
boolean canSetSurfaceScale()
Returns true if setSurfaceScale(float[]) is supported, otherwise false.
static final float IDENTITY_PIXELSCALE
Setting surface-pixel-scale of {@value}, results in same pixel- and window-units.
boolean setSurfaceScale(final float[] pixelScale)
Request a pixel scale in x- and y-direction for the associated NativeSurface, where size_in_pixel_uni...
float[] getMaximumSurfaceScale(final float[] result)
Returns the maximum pixel scale of the associated NativeSurface.
static final float AUTOMAX_PIXELSCALE
Setting surface-pixel-scale of {@value}, results in maximum platform dependent pixel-scale,...
float[] getCurrentSurfaceScale(final float[] result)
Returns the current pixel scale of the associated NativeSurface.
float[] getMinimumSurfaceScale(final float[] result)
Returns the minimum pixel scale of the associated NativeSurface.
float[] getRequestedSurfaceScale(final float[] result)
Returns the requested pixel scale of the associated NativeSurface.