Go to most recent revision | Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
4758 | right-hear | 1 | /* |
2 | * @(#)jawt.h 1.10 03/12/19 |
||
3 | * |
||
4 | * Copyright 2004 Sun Microsystems, Inc. All rights reserved. |
||
5 | * SUN 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 |
||
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_ */ |