JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
Overlay.java
Go to the documentation of this file.
1/*
2 * Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are
6 * met:
7 *
8 * - Redistribution of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 *
11 * - Redistribution in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 *
15 * Neither the name of Sun Microsystems, Inc. or the names of
16 * contributors may be used to endorse or promote products derived from
17 * this software without specific prior written permission.
18 *
19 * This software is provided "AS IS," without a warranty of any kind. ALL
20 * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
21 * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
22 * PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
23 * MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR
24 * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
25 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR
26 * ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR
27 * DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
28 * DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
29 * ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF
30 * SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
31 *
32 * You acknowledge that this software is not designed or intended for use
33 * in the design, construction, operation or maintenance of any nuclear
34 * facility.
35 *
36 * Sun gratefully acknowledges that this software was originally authored
37 * and developed by Kenneth Bradley Russell and Christopher John Kline.
38 */
39
40package com.jogamp.opengl.util.awt;
41
42import java.awt.Graphics2D;
43
44import com.jogamp.opengl.*;
45
46/** Provides a Java 2D overlay on top of an arbitrary GLDrawable,
47 making it easier to do things like draw text and images on top of
48 an OpenGL scene while still maintaining reasonably good
49 efficiency. */
50
51public class Overlay {
52 private final GLDrawable drawable;
53 private TextureRenderer renderer;
54 private boolean contentsLost;
55
56 /** Creates a new Java 2D overlay on top of the specified
57 GLDrawable. */
58 public Overlay(final GLDrawable drawable) {
59 this.drawable = drawable;
60 }
61
62 /** Creates a {@link java.awt.Graphics2D Graphics2D} instance for
63 rendering into the overlay. The returned object should be
64 disposed of using the normal {@link java.awt.Graphics#dispose()
65 Graphics.dispose()} method once it is no longer being used.
66
67 @return a new {@link java.awt.Graphics2D Graphics2D} object for
68 rendering into the backing store of this renderer
69 */
70 public Graphics2D createGraphics() {
71 // Validate the size of the renderer against the current size of
72 // the drawable
73 validateRenderer();
74 return renderer.createGraphics();
75 }
76
77 /** Indicates whether the Java 2D contents of the overlay were lost
78 since the last time {@link #createGraphics} was called. This
79 method should be called immediately after calling {@link
80 #createGraphics} to see whether the entire contents of the
81 overlay need to be redrawn or just the region the application is
82 interested in updating.
83
84 @return whether the contents of the overlay were lost since the
85 last render
86 */
87 public boolean contentsLost() {
88 return contentsLost;
89 }
90
91 /** Marks the given region of the overlay as dirty. This region, and
92 any previously set dirty regions, will be automatically
93 synchronized with the underlying Texture during the next {@link
94 #draw draw} or {@link #drawAll drawAll} operation, at which
95 point the dirty region will be cleared. It is not necessary for
96 an OpenGL context to be current when this method is called.
97
98 @param x the x coordinate (in Java 2D coordinates -- relative to
99 upper left) of the region to update
100 @param y the y coordinate (in Java 2D coordinates -- relative to
101 upper left) of the region to update
102 @param width the width of the region to update
103 @param height the height of the region to update
104
105 @throws GLException If an OpenGL context is not current when this method is called */
106 public void markDirty(final int x, final int y, final int width, final int height) {
107 renderer.markDirty(x, y, width, height);
108 }
109
110 /** Draws the entire contents of the overlay on top of the OpenGL
111 drawable. This is a convenience method which encapsulates all
112 portions of the rendering process; if this method is used,
113 {@link #beginRendering}, {@link #endRendering}, etc. should not
114 be used. This method should be called while the OpenGL context
115 for the drawable is current, and after your OpenGL scene has
116 been rendered.
117
118 @throws GLException If an OpenGL context is not current when this method is called
119 */
120 public void drawAll() throws GLException {
122 draw(0, 0, drawable.getSurfaceWidth(), drawable.getSurfaceHeight());
123 endRendering();
124 }
125
126 /** Begins the OpenGL rendering process for the overlay. This is
127 separated out so advanced applications can render independent
128 pieces of the overlay to different portions of the drawable.
129
130 @throws GLException If an OpenGL context is not current when this method is called
131 */
132 public void beginRendering() throws GLException {
133 renderer.beginOrthoRendering(drawable.getSurfaceWidth(), drawable.getSurfaceHeight());
134 }
135
136 /** Ends the OpenGL rendering process for the overlay. This is
137 separated out so advanced applications can render independent
138 pieces of the overlay to different portions of the drawable.
139
140 @throws GLException If an OpenGL context is not current when this method is called
141 */
142 public void endRendering() throws GLException {
143 renderer.endOrthoRendering();
144 }
145
146 /** Draws the specified sub-rectangle of the overlay on top of the
147 OpenGL drawable. {@link #beginRendering} and {@link
148 #endRendering} must be used in conjunction with this method to
149 achieve proper rendering results. This method should be called
150 while the OpenGL context for the drawable is current, and after
151 your OpenGL scene has been rendered.
152
153 @param x the lower-left x coordinate (relative to the lower left
154 of the overlay) of the rectangle to draw
155 @param y the lower-left y coordinate (relative to the lower left
156 of the overlay) of the rectangle to draw
157 @param width the width of the rectangle to draw
158 @param height the height of the rectangle to draw
159
160 @throws GLException If an OpenGL context is not current when this method is called
161 */
162 public void draw(final int x, final int y, final int width, final int height) throws GLException {
163 draw(x, y, x, y, width, height);
164 }
165
166 /** Draws the specified sub-rectangle of the overlay at the
167 specified x and y coordinate on top of the OpenGL drawable.
168 {@link #beginRendering} and {@link #endRendering} must be used
169 in conjunction with this method to achieve proper rendering
170 results. This method should be called while the OpenGL context
171 for the drawable is current, and after your OpenGL scene has
172 been rendered.
173
174 @param screenx the on-screen x coordinate at which to draw the rectangle
175 @param screeny the on-screen y coordinate (relative to lower left) at
176 which to draw the rectangle
177 @param overlayx the x coordinate of the pixel in the overlay of
178 the lower left portion of the rectangle to draw
179 @param overlayy the y coordinate of the pixel in the overlay
180 (relative to lower left) of the lower left portion of the
181 rectangle to draw
182 @param width the width of the rectangle to draw
183 @param height the height of the rectangle to draw
184
185 @throws GLException If an OpenGL context is not current when this method is called
186 */
187 public void draw(final int screenx, final int screeny,
188 final int overlayx, final int overlayy,
189 final int width, final int height) throws GLException {
190 renderer.drawOrthoRect(screenx, screeny,
191 overlayx, overlayy,
192 width, height);
193 }
194
195 //----------------------------------------------------------------------
196 // Internals only below this point
197 //
198
199 private void validateRenderer() {
200 if (renderer == null) {
201 renderer = new TextureRenderer(drawable.getSurfaceWidth(),
202 drawable.getSurfaceHeight(),
203 true);
204 contentsLost = true;
205 } else if (renderer.getWidth() != drawable.getSurfaceWidth() ||
206 renderer.getHeight() != drawable.getSurfaceHeight()) {
207 renderer.setSize(drawable.getSurfaceWidth(), drawable.getSurfaceHeight());
208 contentsLost = true;
209 } else {
210 contentsLost = false;
211 }
212 }
213}
A generic exception for OpenGL errors used throughout the binding as a substitute for RuntimeExceptio...
Provides a Java 2D overlay on top of an arbitrary GLDrawable, making it easier to do things like draw...
Definition: Overlay.java:51
void draw(final int screenx, final int screeny, final int overlayx, final int overlayy, final int width, final int height)
Draws the specified sub-rectangle of the overlay at the specified x and y coordinate on top of the Op...
Definition: Overlay.java:187
Graphics2D createGraphics()
Creates a Graphics2D instance for rendering into the overlay.
Definition: Overlay.java:70
void markDirty(final int x, final int y, final int width, final int height)
Marks the given region of the overlay as dirty.
Definition: Overlay.java:106
void beginRendering()
Begins the OpenGL rendering process for the overlay.
Definition: Overlay.java:132
void endRendering()
Ends the OpenGL rendering process for the overlay.
Definition: Overlay.java:142
void drawAll()
Draws the entire contents of the overlay on top of the OpenGL drawable.
Definition: Overlay.java:120
Overlay(final GLDrawable drawable)
Creates a new Java 2D overlay on top of the specified GLDrawable.
Definition: Overlay.java:58
void draw(final int x, final int y, final int width, final int height)
Draws the specified sub-rectangle of the overlay on top of the OpenGL drawable.
Definition: Overlay.java:162
boolean contentsLost()
Indicates whether the Java 2D contents of the overlay were lost since the last time createGraphics wa...
Definition: Overlay.java:87
Provides the ability to render into an OpenGL Texture using the Java 2D APIs.
int getHeight()
Returns the height of the backing store of this renderer.
void setSize(final int width, final int height)
Sets the size of the backing store of this renderer.
void drawOrthoRect(final int screenx, final int screeny)
Draws an orthographically projected rectangle containing all of the underlying texture to the specifi...
void markDirty(final int x, final int y, final int width, final int height)
Marks the given region of the TextureRenderer as dirty.
int getWidth()
Returns the width of the backing store of this renderer.
Graphics2D createGraphics()
Creates a Graphics2D instance for rendering to the backing store of this renderer.
void beginOrthoRendering(final int width, final int height)
Convenience method which assists in rendering portions of the OpenGL texture to the screen,...
void endOrthoRendering()
Convenience method which assists in rendering portions of the OpenGL texture to the screen,...
An abstraction for an OpenGL rendering target.
Definition: GLDrawable.java:51
int getSurfaceWidth()
Returns the width of this GLDrawable's surface client area in pixel units.
int getSurfaceHeight()
Returns the height of this GLDrawable's surface client area in pixel units.