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