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 
29 package com.jogamp.nativewindow;
30 
31 import 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  */
41 public 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 */
setGraphicsConfiguration(AbstractGraphicsConfiguration cfg)77     public void setGraphicsConfiguration(AbstractGraphicsConfiguration cfg);
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      */
getUpstreamSurface()90     public NativeSurface getUpstreamSurface();
91 
92     /** Returns the {@link UpstreamSurfaceHook} if {@link #setUpstreamSurfaceHook(UpstreamSurfaceHook) set}, otherwise <code>null</code>. */
getUpstreamSurfaceHook()93     public UpstreamSurfaceHook getUpstreamSurfaceHook();
94 
95     /**
96      * Overrides the {@link UpstreamSurfaceHook}.
97      */
setUpstreamSurfaceHook(UpstreamSurfaceHook hook)98     public void setUpstreamSurfaceHook(UpstreamSurfaceHook hook);
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      */
enableUpstreamSurfaceHookLifecycle(boolean enable)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      */
createNotify()113     public void createNotify();
114 
115     /**
116      * {@link UpstreamSurfaceHook#destroy(ProxySurface)} is being issued and all proxy surface/window handles shall be cleared.
117      */
destroyNotify()118     public void destroyNotify();
119 
getUpstreamOptionBits(StringBuilder sink)120     public StringBuilder getUpstreamOptionBits(StringBuilder sink);
getUpstreamOptionBits()121     public int getUpstreamOptionBits();
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>.*/
containsUpstreamOptionBits(int v)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>.*/
addUpstreamOptionBits(int v)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>*/
clearUpstreamOptionBits(int v)130     public void clearUpstreamOptionBits(int v);
131 
toString(StringBuilder sink)132     public StringBuilder toString(StringBuilder sink);
133     @Override
toString()134     public String toString();
135 }
136