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