1 /******************************************************************************* 2 * Copyright 2011 See AUTHORS file. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 ******************************************************************************/ 16 17 package com.badlogic.gdx; 18 19 import com.badlogic.gdx.graphics.Cursor; 20 import com.badlogic.gdx.graphics.Cursor.SystemCursor; 21 import com.badlogic.gdx.graphics.GL20; 22 import com.badlogic.gdx.graphics.GL30; 23 import com.badlogic.gdx.graphics.Mesh; 24 import com.badlogic.gdx.graphics.Pixmap; 25 import com.badlogic.gdx.graphics.g2d.Batch; 26 import com.badlogic.gdx.graphics.g2d.BitmapFont; 27 import com.badlogic.gdx.graphics.glutils.FrameBuffer; 28 import com.badlogic.gdx.graphics.glutils.GLVersion; 29 import com.badlogic.gdx.graphics.glutils.IndexBufferObject; 30 import com.badlogic.gdx.graphics.glutils.ShaderProgram; 31 import com.badlogic.gdx.graphics.glutils.VertexArray; 32 import com.badlogic.gdx.graphics.glutils.VertexBufferObject; 33 34 /** This interface encapsulates communication with the graphics processor. Depending on the available hardware and the current 35 * {@link Application} configuration, access to {@link GL20} and {@link GL30} are provided here. 36 * <p> 37 * If supported by the backend, this interface lets you query the available display modes (graphics resolution and color depth) 38 * and change it. 39 * <p> 40 * This interface can be used to switch between continuous and non-continuous rendering (see 41 * {@link #setContinuousRendering(boolean)}), and to explicitly {@link #requestRendering()}. 42 * <p> 43 * There are many more utility classes that are not directly generated by the {@link Graphics} interfaces. See {@link VertexArray} 44 * , {@link VertexBufferObject}, {@link IndexBufferObject}, {@link Mesh}, {@link ShaderProgram} and {@link FrameBuffer}, 45 * {@link BitmapFont}, {@link Batch} and so on. All these classes are managed, meaning they don't need to be reloaded on a context 46 * loss. Explore the com.badlogic.gdx.graphics package for more classes that might come in handy. 47 * @author mzechner */ 48 public interface Graphics { 49 /** Enumeration describing different types of {@link Graphics} implementations. 50 * 51 * @author mzechner */ 52 public enum GraphicsType { 53 AndroidGL, LWJGL, WebGL, iOSGL, JGLFW, Mock, LWJGL3 54 } 55 56 /** Describe a fullscreen display mode 57 * 58 * @author mzechner */ 59 public class DisplayMode { 60 /** the width in physical pixels **/ 61 public final int width; 62 /** the height in physical pixles **/ 63 public final int height; 64 /** the refresh rate in Hertz **/ 65 public final int refreshRate; 66 /** the number of bits per pixel, may exclude alpha **/ 67 public final int bitsPerPixel; 68 DisplayMode(int width, int height, int refreshRate, int bitsPerPixel)69 protected DisplayMode (int width, int height, int refreshRate, int bitsPerPixel) { 70 this.width = width; 71 this.height = height; 72 this.refreshRate = refreshRate; 73 this.bitsPerPixel = bitsPerPixel; 74 } 75 toString()76 public String toString () { 77 return width + "x" + height + ", bpp: " + bitsPerPixel + ", hz: " + refreshRate; 78 } 79 } 80 81 /** Describes a monitor 82 * 83 * @author badlogic 84 */ 85 public class Monitor { 86 public final int virtualX; 87 public final int virtualY; 88 public final String name; 89 Monitor(int virtualX, int virtualY, String name)90 protected Monitor (int virtualX, int virtualY, String name) { 91 this.virtualX = virtualX; 92 this.virtualY = virtualY; 93 this.name = name; 94 } 95 } 96 97 /** Class describing the bits per pixel, depth buffer precision, stencil precision and number of MSAA samples. */ 98 public static class BufferFormat { 99 /* number of bits per color channel */ 100 public final int r, g, b, a; 101 /* number of bits for depth and stencil buffer */ 102 public final int depth, stencil; 103 /** number of samples for multi-sample anti-aliasing (MSAA) **/ 104 public final int samples; 105 /** whether coverage sampling anti-aliasing is used. in that case you have to clear the coverage buffer as well! */ 106 public final boolean coverageSampling; 107 BufferFormat(int r, int g, int b, int a, int depth, int stencil, int samples, boolean coverageSampling)108 public BufferFormat (int r, int g, int b, int a, int depth, int stencil, int samples, boolean coverageSampling) { 109 this.r = r; 110 this.g = g; 111 this.b = b; 112 this.a = a; 113 this.depth = depth; 114 this.stencil = stencil; 115 this.samples = samples; 116 this.coverageSampling = coverageSampling; 117 } 118 toString()119 public String toString () { 120 return "r: " + r + ", g: " + g + ", b: " + b + ", a: " + a + ", depth: " + depth + ", stencil: " + stencil 121 + ", num samples: " + samples + ", coverage sampling: " + coverageSampling; 122 } 123 } 124 125 /** Returns whether OpenGL ES 3.0 is available. If it is you can get an instance of {@link GL30} via {@link #getGL30()} to 126 * access OpenGL ES 3.0 functionality. Note that this functionality will only be available if you instructed the 127 * {@link Application} instance to use OpenGL ES 3.0! 128 * 129 * @return whether OpenGL ES 3.0 is available */ isGL30Available()130 public boolean isGL30Available (); 131 132 /** @return the {@link GL20} instance */ getGL20()133 public GL20 getGL20 (); 134 135 /** @return the {@link GL30} instance or null if not supported */ getGL30()136 public GL30 getGL30 (); 137 138 /** @return the width of the client area in logical pixels. */ getWidth()139 public int getWidth (); 140 141 /** @return the height of the client area in logical pixels */ getHeight()142 public int getHeight (); 143 144 /** @return the width of the framebuffer in physical pixels */ getBackBufferWidth()145 public int getBackBufferWidth (); 146 147 /** @return the height of the framebuffer in physical pixels */ getBackBufferHeight()148 public int getBackBufferHeight (); 149 150 /** Returns the id of the current frame. The general contract of this method is that the id is incremented only when the 151 * application is in the running state right before calling the {@link ApplicationListener#render()} method. Also, the id of 152 * the first frame is 0; the id of subsequent frames is guaranteed to take increasing values for 2<sup>63</sup>-1 rendering 153 * cycles. 154 * @return the id of the current frame */ getFrameId()155 public long getFrameId (); 156 157 /** @return the time span between the current frame and the last frame in seconds. Might be smoothed over n frames. */ getDeltaTime()158 public float getDeltaTime (); 159 160 /** @return the time span between the current frame and the last frame in seconds, without smoothing **/ getRawDeltaTime()161 public float getRawDeltaTime (); 162 163 /** @return the average number of frames per second */ getFramesPerSecond()164 public int getFramesPerSecond (); 165 166 /** @return the {@link GraphicsType} of this Graphics instance */ getType()167 public GraphicsType getType (); 168 169 /** @return the {@link GLVersion} of this Graphics instance */ getGLVersion()170 public GLVersion getGLVersion (); 171 172 /** @return the pixels per inch on the x-axis */ getPpiX()173 public float getPpiX (); 174 175 /** @return the pixels per inch on the y-axis */ getPpiY()176 public float getPpiY (); 177 178 /** @return the pixels per centimeter on the x-axis */ getPpcX()179 public float getPpcX (); 180 181 /** @return the pixels per centimeter on the y-axis. */ getPpcY()182 public float getPpcY (); 183 184 /** This is a scaling factor for the Density Independent Pixel unit, following the same conventions as 185 * android.util.DisplayMetrics#density, where one DIP is one pixel on an approximately 160 dpi screen. Thus on a 160dpi screen 186 * this density value will be 1; on a 120 dpi screen it would be .75; etc. 187 * 188 * @return the logical density of the Display. */ getDensity()189 public float getDensity (); 190 191 /** Whether the given backend supports a display mode change via calling {@link Graphics#setFullscreenMode(DisplayMode)} 192 * 193 * @return whether display mode changes are supported or not. */ supportsDisplayModeChange()194 public boolean supportsDisplayModeChange (); 195 196 /** @return the primary monitor **/ getPrimaryMonitor()197 public Monitor getPrimaryMonitor(); 198 199 /** @return the monitor the application's window is located on */ getMonitor()200 public Monitor getMonitor(); 201 202 /** @return the currently connected {@link Monitor}s */ getMonitors()203 public Monitor[] getMonitors(); 204 205 /** @return the supported fullscreen {@link DisplayMode}(s) of the monitor the window is on */ getDisplayModes()206 public DisplayMode[] getDisplayModes (); 207 208 /** @return the supported fullscreen {@link DisplayMode}s of the given {@link Monitor} */ getDisplayModes(Monitor monitor)209 public DisplayMode[] getDisplayModes(Monitor monitor); 210 211 /** @return the current {@link DisplayMode} of the monitor the window is on. */ getDisplayMode()212 public DisplayMode getDisplayMode (); 213 214 /** @return the current {@link DisplayMode} of the given {@link Monitor} */ getDisplayMode(Monitor monitor)215 public DisplayMode getDisplayMode (Monitor monitor); 216 217 /** Sets the window to full-screen mode. 218 * 219 * @param displayMode the display mode. 220 * @return whether the operation succeeded. */ setFullscreenMode(DisplayMode displayMode)221 public boolean setFullscreenMode (DisplayMode displayMode); 222 223 /** Sets the window to windowed mode. 224 * 225 * @param width the width in pixels 226 * @param height the height in pixels 227 * @return whether the operation succeeded*/ setWindowedMode(int width, int height)228 public boolean setWindowedMode (int width, int height); 229 230 /** Sets the title of the window. Ignored on Android. 231 * 232 * @param title the title. */ setTitle(String title)233 public void setTitle (String title); 234 235 /** Sets the window decoration as enabled or disabled. On Android, this will enable/disable 236 * the menu bar. 237 * 238 * Note that immediate behavior of this method may vary depending on the implementation. It 239 * may be necessary for the window to be recreated in order for the changes to take effect. 240 * Consult the documentation for the backend in use for more information. 241 * 242 * Supported on all GDX desktop backends and on Android (to disable the menu bar). 243 * 244 * @param undecorated true if the window border or status bar should be hidden. false otherwise. 245 */ setUndecorated(boolean undecorated)246 public void setUndecorated (boolean undecorated); 247 248 /** Sets whether or not the window should be resizable. Ignored on Android. 249 * 250 * Note that immediate behavior of this method may vary depending on the implementation. It 251 * may be necessary for the window to be recreated in order for the changes to take effect. 252 * Consult the documentation for the backend in use for more information. 253 * 254 * Supported on all GDX desktop backends. 255 * 256 * @param resizable 257 */ setResizable(boolean resizable)258 public void setResizable (boolean resizable); 259 260 /** Enable/Disable vsynching. This is a best-effort attempt which might not work on all platforms. 261 * 262 * @param vsync vsync enabled or not. */ setVSync(boolean vsync)263 public void setVSync (boolean vsync); 264 265 /** @return the format of the color, depth and stencil buffer in a {@link BufferFormat} instance */ getBufferFormat()266 public BufferFormat getBufferFormat (); 267 268 /** @param extension the extension name 269 * @return whether the extension is supported */ supportsExtension(String extension)270 public boolean supportsExtension (String extension); 271 272 /** Sets whether to render continuously. In case rendering is performed non-continuously, the following events will trigger a 273 * redraw: 274 * 275 * <ul> 276 * <li>A call to {@link #requestRendering()}</li> 277 * <li>Input events from the touch screen/mouse or keyboard</li> 278 * <li>A {@link Runnable} is posted to the rendering thread via {@link Application#postRunnable(Runnable)}</li> 279 * </ul> 280 * 281 * Life-cycle events will also be reported as usual, see {@link ApplicationListener}. This method can be called from any 282 * thread. 283 * 284 * @param isContinuous whether the rendering should be continuous or not. */ setContinuousRendering(boolean isContinuous)285 public void setContinuousRendering (boolean isContinuous); 286 287 /** @return whether rendering is continuous. */ isContinuousRendering()288 public boolean isContinuousRendering (); 289 290 /** Requests a new frame to be rendered if the rendering mode is non-continuous. This method can be called from any thread. */ requestRendering()291 public void requestRendering (); 292 293 /** Whether the app is fullscreen or not */ isFullscreen()294 public boolean isFullscreen (); 295 296 /** Create a new cursor represented by the {@link com.badlogic.gdx.graphics.Pixmap}. The Pixmap must be in RGBA8888 format, 297 * width & height must be powers-of-two greater than zero (not necessarily equal), and alpha transparency must be single-bit 298 * (i.e., 0x00 or 0xFF only). This function returns a Cursor object that can be set as the system cursor by calling 299 * {@link #setCursor(Cursor)} . 300 * 301 * @param pixmap the mouse cursor image as a {@link com.badlogic.gdx.graphics.Pixmap} 302 * @param xHotspot the x location of the hotspot pixel within the cursor image (origin top-left corner) 303 * @param yHotspot the y location of the hotspot pixel within the cursor image (origin top-left corner) 304 * @return a cursor object that can be used by calling {@link #setCursor(Cursor)} or null if not supported */ newCursor(Pixmap pixmap, int xHotspot, int yHotspot)305 public Cursor newCursor (Pixmap pixmap, int xHotspot, int yHotspot); 306 307 /** Only viable on the lwjgl-backend and on the gwt-backend. Browsers that support cursor:url() and support the png format (the 308 * pixmap is converted to a data-url of type image/png) should also support custom cursors. Will set the mouse cursor image to 309 * the image represented by the {@link com.badlogic.gdx.graphics.Cursor}. It is recommended to call this function in the main render thread, and maximum one time per frame. 310 * 311 * @param cursor the mouse cursor as a {@link com.badlogic.gdx.graphics.Cursor} */ setCursor(Cursor cursor)312 public void setCursor (Cursor cursor); 313 314 /** 315 * Sets one of the predefined {@link SystemCursor}s 316 */ setSystemCursor(SystemCursor systemCursor)317 public void setSystemCursor(SystemCursor systemCursor); 318 } 319