• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 #ifndef _JAVASOFT_JAWT_H_
27 #define _JAVASOFT_JAWT_H_
28 
29 #include "jni.h"
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /*
36  * AWT native interface (new in JDK 1.3)
37  *
38  * The AWT native interface allows a native C or C++ application a means
39  * by which to access native structures in AWT.  This is to facilitate moving
40  * legacy C and C++ applications to Java and to target the needs of the
41  * community who, at present, wish to do their own native rendering to canvases
42  * for performance reasons.  Standard extensions such as Java3D also require a
43  * means to access the underlying native data structures of AWT.
44  *
45  * There may be future extensions to this API depending on demand.
46  *
47  * A VM does not have to implement this API in order to pass the JCK.
48  * It is recommended, however, that this API is implemented on VMs that support
49  * standard extensions, such as Java3D.
50  *
51  * Since this is a native API, any program which uses it cannot be considered
52  * 100% pure java.
53  */
54 
55 /*
56  * AWT Native Drawing Surface (JAWT_DrawingSurface).
57  *
58  * For each platform, there is a native drawing surface structure.  This
59  * platform-specific structure can be found in jawt_md.h.  It is recommended
60  * that additional platforms follow the same model.  It is also recommended
61  * that VMs on Win32 and Solaris support the existing structures in jawt_md.h.
62  *
63  *******************
64  * EXAMPLE OF USAGE:
65  *******************
66  *
67  * In Win32, a programmer wishes to access the HWND of a canvas to perform
68  * native rendering into it.  The programmer has declared the paint() method
69  * for their canvas subclass to be native:
70  *
71  *
72  * MyCanvas.java:
73  *
74  * import java.awt.*;
75  *
76  * public class MyCanvas extends Canvas {
77  *
78  *     static {
79  *         System.loadLibrary("mylib");
80  *     }
81  *
82  *     public native void paint(Graphics g);
83  * }
84  *
85  *
86  * myfile.c:
87  *
88  * #include "jawt_md.h"
89  * #include <assert.h>
90  *
91  * JNIEXPORT void JNICALL
92  * Java_MyCanvas_paint(JNIEnv* env, jobject canvas, jobject graphics)
93  * {
94  *     JAWT awt;
95  *     JAWT_DrawingSurface* ds;
96  *     JAWT_DrawingSurfaceInfo* dsi;
97  *     JAWT_Win32DrawingSurfaceInfo* dsi_win;
98  *     jboolean result;
99  *     jint lock;
100  *
101  *     // Get the AWT
102  *     awt.version = JAWT_VERSION_1_3;
103  *     result = JAWT_GetAWT(env, &awt);
104  *     assert(result != JNI_FALSE);
105  *
106  *     // Get the drawing surface
107  *     ds = awt.GetDrawingSurface(env, canvas);
108  *     assert(ds != NULL);
109  *
110  *     // Lock the drawing surface
111  *     lock = ds->Lock(ds);
112  *     assert((lock & JAWT_LOCK_ERROR) == 0);
113  *
114  *     // Get the drawing surface info
115  *     dsi = ds->GetDrawingSurfaceInfo(ds);
116  *
117  *     // Get the platform-specific drawing info
118  *     dsi_win = (JAWT_Win32DrawingSurfaceInfo*)dsi->platformInfo;
119  *
120  *     //////////////////////////////
121  *     // !!! DO PAINTING HERE !!! //
122  *     //////////////////////////////
123  *
124  *     // Free the drawing surface info
125  *     ds->FreeDrawingSurfaceInfo(dsi);
126  *
127  *     // Unlock the drawing surface
128  *     ds->Unlock(ds);
129  *
130  *     // Free the drawing surface
131  *     awt.FreeDrawingSurface(ds);
132  * }
133  *
134  */
135 
136 /*
137  * JAWT_Rectangle
138  * Structure for a native rectangle.
139  */
140 typedef struct jawt_Rectangle {
141     jint x;
142     jint y;
143     jint width;
144     jint height;
145 } JAWT_Rectangle;
146 
147 struct jawt_DrawingSurface;
148 
149 /*
150  * JAWT_DrawingSurfaceInfo
151  * Structure for containing the underlying drawing information of a component.
152  */
153 typedef struct jawt_DrawingSurfaceInfo {
154     /*
155      * Pointer to the platform-specific information.  This can be safely
156      * cast to a JAWT_Win32DrawingSurfaceInfo on Windows or a
157      * JAWT_X11DrawingSurfaceInfo on Solaris. On Mac OS X this is a
158      * pointer to a NSObject that conforms to the JAWT_SurfaceLayers
159      * protocol. See jawt_md.h for details.
160      */
161     void* platformInfo;
162     /* Cached pointer to the underlying drawing surface */
163     struct jawt_DrawingSurface* ds;
164     /* Bounding rectangle of the drawing surface */
165     JAWT_Rectangle bounds;
166     /* Number of rectangles in the clip */
167     jint clipSize;
168     /* Clip rectangle array */
169     JAWT_Rectangle* clip;
170 } JAWT_DrawingSurfaceInfo;
171 
172 #define JAWT_LOCK_ERROR                 0x00000001
173 #define JAWT_LOCK_CLIP_CHANGED          0x00000002
174 #define JAWT_LOCK_BOUNDS_CHANGED        0x00000004
175 #define JAWT_LOCK_SURFACE_CHANGED       0x00000008
176 
177 /*
178  * JAWT_DrawingSurface
179  * Structure for containing the underlying drawing information of a component.
180  * All operations on a JAWT_DrawingSurface MUST be performed from the same
181  * thread as the call to GetDrawingSurface.
182  */
183 typedef struct jawt_DrawingSurface {
184     /*
185      * Cached reference to the Java environment of the calling thread.
186      * If Lock(), Unlock(), GetDrawingSurfaceInfo() or
187      * FreeDrawingSurfaceInfo() are called from a different thread,
188      * this data member should be set before calling those functions.
189      */
190     JNIEnv* env;
191     /* Cached reference to the target object */
192     jobject target;
193     /*
194      * Lock the surface of the target component for native rendering.
195      * When finished drawing, the surface must be unlocked with
196      * Unlock().  This function returns a bitmask with one or more of the
197      * following values:
198      *
199      * JAWT_LOCK_ERROR - When an error has occurred and the surface could not
200      * be locked.
201      *
202      * JAWT_LOCK_CLIP_CHANGED - When the clip region has changed.
203      *
204      * JAWT_LOCK_BOUNDS_CHANGED - When the bounds of the surface have changed.
205      *
206      * JAWT_LOCK_SURFACE_CHANGED - When the surface itself has changed
207      */
208     jint (JNICALL *Lock)
209         (struct jawt_DrawingSurface* ds);
210     /*
211      * Get the drawing surface info.
212      * The value returned may be cached, but the values may change if
213      * additional calls to Lock() or Unlock() are made.
214      * Lock() must be called before this can return a valid value.
215      * Returns NULL if an error has occurred.
216      * When finished with the returned value, FreeDrawingSurfaceInfo must be
217      * called.
218      */
219     JAWT_DrawingSurfaceInfo* (JNICALL *GetDrawingSurfaceInfo)
220         (struct jawt_DrawingSurface* ds);
221     /*
222      * Free the drawing surface info.
223      */
224     void (JNICALL *FreeDrawingSurfaceInfo)
225         (JAWT_DrawingSurfaceInfo* dsi);
226     /*
227      * Unlock the drawing surface of the target component for native rendering.
228      */
229     void (JNICALL *Unlock)
230         (struct jawt_DrawingSurface* ds);
231 } JAWT_DrawingSurface;
232 
233 /*
234  * JAWT
235  * Structure for containing native AWT functions.
236  */
237 typedef struct jawt {
238     /*
239      * Version of this structure.  This must always be set before
240      * calling JAWT_GetAWT()
241      */
242     jint version;
243     /*
244      * Return a drawing surface from a target jobject.  This value
245      * may be cached.
246      * Returns NULL if an error has occurred.
247      * Target must be a java.awt.Component (should be a Canvas
248      * or Window for native rendering).
249      * FreeDrawingSurface() must be called when finished with the
250      * returned JAWT_DrawingSurface.
251      */
252     JAWT_DrawingSurface* (JNICALL *GetDrawingSurface)
253         (JNIEnv* env, jobject target);
254     /*
255      * Free the drawing surface allocated in GetDrawingSurface.
256      */
257     void (JNICALL *FreeDrawingSurface)
258         (JAWT_DrawingSurface* ds);
259     /*
260      * Since 1.4
261      * Locks the entire AWT for synchronization purposes
262      */
263     void (JNICALL *Lock)(JNIEnv* env);
264     /*
265      * Since 1.4
266      * Unlocks the entire AWT for synchronization purposes
267      */
268     void (JNICALL *Unlock)(JNIEnv* env);
269     /*
270      * Since 1.4
271      * Returns a reference to a java.awt.Component from a native
272      * platform handle.  On Windows, this corresponds to an HWND;
273      * on Solaris and Linux, this is a Drawable.  For other platforms,
274      * see the appropriate machine-dependent header file for a description.
275      * The reference returned by this function is a local
276      * reference that is only valid in this environment.
277      * This function returns a NULL reference if no component could be
278      * found with matching platform information.
279      */
280     jobject (JNICALL *GetComponent)(JNIEnv* env, void* platformInfo);
281 
282 } JAWT;
283 
284 /*
285  * Get the AWT native structure.  This function returns JNI_FALSE if
286  * an error occurs.
287  */
288 _JNI_IMPORT_OR_EXPORT_
289 jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt);
290 
291 #define JAWT_VERSION_1_3 0x00010003
292 #define JAWT_VERSION_1_4 0x00010004
293 #define JAWT_VERSION_1_7 0x00010007
294 
295 #ifdef __cplusplus
296 } /* extern "C" */
297 #endif
298 
299 #endif /* !_JAVASOFT_JAWT_H_ */
300