JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
ProxySurface.java
Go to the documentation of this file.
1/**
2 * Copyright 2012 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
31import jogamp.nativewindow.Debug;
32
33/**
34 * Provides a mutable {@link NativeSurface}, i.e. {@link MutableSurface}, while allowing an
35 * {@link UpstreamSurfaceHook} to influence the lifecycle and information.
36 *
37 * @see UpstreamSurfaceHook
38 * @see MutableSurface
39 * @see NativeSurface
40 */
41public interface ProxySurface extends MutableSurface {
42 public static final boolean DEBUG = Debug.debug("ProxySurface");
43
44 /**
45 * Implementation specific bit-value stating this {@link ProxySurface} owns the upstream's surface handle
46 * @see #addUpstreamOptionBits(int)
47 * @see #clearUpstreamOptionBits(int)
48 * @see #getUpstreamOptionBits()
49 */
50 public static final int OPT_PROXY_OWNS_UPSTREAM_SURFACE = 1 << 6;
51
52 /**
53 * Implementation specific bit-value stating this {@link ProxySurface} owns the upstream's {@link AbstractGraphicsDevice}.
54 * @see #addUpstreamOptionBits(int)
55 * @see #clearUpstreamOptionBits(int)
56 * @see #getUpstreamOptionBits()
57 */
58 public static final int OPT_PROXY_OWNS_UPSTREAM_DEVICE = 1 << 7;
59
60 /**
61 * Implementation specific bitvalue stating the upstream's {@link NativeSurface} is an invisible window, i.e. maybe incomplete.
62 * @see #addUpstreamOptionBits(int)
63 * @see #clearUpstreamOptionBits(int)
64 * @see #getUpstreamOptionBits()
65 */
66 public static final int OPT_UPSTREAM_WINDOW_INVISIBLE = 1 << 8;
67
68 /**
69 * Implementation specific bitvalue stating the upstream's {@link NativeSurface}'s zero handle is valid.
70 * @see #addUpstreamOptionBits(int)
71 * @see #clearUpstreamOptionBits(int)
72 * @see #getUpstreamOptionBits()
73 */
74 public static final int OPT_UPSTREAM_SURFACELESS = 1 << 9;
75
76 /** Allow redefining the AbstractGraphicsConfiguration */
78
79 /**
80 * Returns the optional upstream {@link NativeSurface} if used by implementation, otherwise <code>null</code>.
81 * <p>
82 * The upstream {@link NativeSurface} is retrieved via {@link #getUpstreamSurfaceHook() the UpstreamSurfaceHook},
83 * i.e. {@link UpstreamSurfaceHook#getUpstreamSurface()}.
84 * </p>
85 * <p>
86 * One example is the JOGL EGLWrappedSurface, which might be backed up by a
87 * native platform NativeSurface (X11, WGL, CGL, ..).
88 * </p>
89 */
91
92 /** Returns the {@link UpstreamSurfaceHook} if {@link #setUpstreamSurfaceHook(UpstreamSurfaceHook) set}, otherwise <code>null</code>. */
94
95 /**
96 * Overrides the {@link UpstreamSurfaceHook}.
97 */
99
100 /**
101 * Enables or disables the {@link UpstreamSurfaceHook} lifecycle functions
102 * {@link UpstreamSurfaceHook#create(ProxySurface)} and {@link UpstreamSurfaceHook#destroy(ProxySurface)}.
103 * <p>
104 * Use this for small code blocks where the native resources shall not change,
105 * i.e. resizing a derived (OpenGL) drawable.
106 * </p>
107 */
108 public void enableUpstreamSurfaceHookLifecycle(boolean enable);
109
110 /**
111 * {@link UpstreamSurfaceHook#create(ProxySurface)} is being issued and the proxy surface/window handles shall be set.
112 */
113 public void createNotify();
114
115 /**
116 * {@link UpstreamSurfaceHook#destroy(ProxySurface)} is being issued and all proxy surface/window handles shall be cleared.
117 */
118 public void destroyNotify();
119
120 public StringBuilder getUpstreamOptionBits(StringBuilder sink);
122
123 /** Returns <code>true</code> if the give bit-mask <code>v</code> is set in this instance upstream-option-bits, otherwise <code>false</code>.*/
124 public boolean containsUpstreamOptionBits(int v);
125
126 /** Add the given bit-mask to this instance upstream-option-bits using bit-or w/ <code>v</code>.*/
127 public void addUpstreamOptionBits(int v);
128
129 /** Clear the given bit-mask from this instance upstream-option-bits using bit-and w/ <code>~v</code>*/
130 public void clearUpstreamOptionBits(int v);
131
132 public StringBuilder toString(StringBuilder sink);
133 @Override
134 public String toString();
135}
A marker interface describing a graphics configuration, visual, or pixel format in a toolkit-independ...
Provides a NativeSurface with a mutable surfaceHandle via setSurfaceHandle(long).
Provides low-level information required for hardware-accelerated rendering using a surface in a platf...
Provides a mutable NativeSurface, i.e.
NativeSurface getUpstreamSurface()
Returns the optional upstream NativeSurface if used by implementation, otherwise null.
static final int OPT_PROXY_OWNS_UPSTREAM_SURFACE
Implementation specific bit-value stating this ProxySurface owns the upstream's surface handle.
void addUpstreamOptionBits(int v)
Add the given bit-mask to this instance upstream-option-bits using bit-or w/ v.
void clearUpstreamOptionBits(int v)
Clear the given bit-mask from this instance upstream-option-bits using bit-and w/ ~v
boolean containsUpstreamOptionBits(int v)
Returns true if the give bit-mask v is set in this instance upstream-option-bits, otherwise false.
StringBuilder toString(StringBuilder sink)
static final int OPT_UPSTREAM_SURFACELESS
Implementation specific bitvalue stating the upstream's NativeSurface's zero handle is valid.
void destroyNotify()
UpstreamSurfaceHook#destroy(ProxySurface) is being issued and all proxy surface/window handles shall ...
StringBuilder getUpstreamOptionBits(StringBuilder sink)
UpstreamSurfaceHook getUpstreamSurfaceHook()
Returns the UpstreamSurfaceHook if set, otherwise null.
void setGraphicsConfiguration(AbstractGraphicsConfiguration cfg)
Allow redefining the AbstractGraphicsConfiguration.
void enableUpstreamSurfaceHookLifecycle(boolean enable)
Enables or disables the UpstreamSurfaceHook lifecycle functions UpstreamSurfaceHook#create(ProxySurfa...
static final int OPT_PROXY_OWNS_UPSTREAM_DEVICE
Implementation specific bit-value stating this ProxySurface owns the upstream's AbstractGraphicsDevic...
static final int OPT_UPSTREAM_WINDOW_INVISIBLE
Implementation specific bitvalue stating the upstream's NativeSurface is an invisible window,...
void setUpstreamSurfaceHook(UpstreamSurfaceHook hook)
Overrides the UpstreamSurfaceHook.
void createNotify()
UpstreamSurfaceHook#create(ProxySurface) is being issued and the proxy surface/window handles shall b...
Interface allowing upstream caller to pass lifecycle actions and size info to a ProxySurface instance...