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_ */ 279