1 /*
   2  * Copyright (c) 1999, 2016, 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.
  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     /**
 283      * Since 9
 284      * Creates a java.awt.Frame placed in a native container. Container is
 285      * referenced by the native platform handle. For example on Windows this
 286      * corresponds to an HWND. For other platforms, see the appropriate
 287      * machine-dependent header file for a description. The reference returned
 288      * by this function is a local reference that is only valid in this
 289      * environment. This function returns a NULL reference if no frame could be
 290      * creates with matching platform information.
 291      */
 292     jobject (JNICALL *CreateEmbeddedFrame) (JNIEnv *env, void* platformInfo);
 293 
 294     /**
 295      * Since 9
 296      * Moves and resize the embedded frame. The new location of the top-left
 297      * corner is specified by x and y parameters relative to the native parent
 298      * component. The new size is specified by width and height.
 299      *
 300      * The embedded frame should be created by CreateEmbeddedFrame() method, or
 301      * this function will not have any effect.
 302      *
 303      * setLocation() and setBounds() for EmbeddedFrame really don't move it
 304      * within the native parent. These methods always put embedded frame to
 305      * (0, 0) for backward compatibility. To allow moving embedded frames
 306      * this method was introduced, and it work just the same way as
 307      * setLocation() and setBounds() for usual, non-embedded components.
 308      *
 309      * Using usual get/setLocation() and get/setBounds() together with this new
 310      * method is not recommended.
 311      */
 312     void (JNICALL *SetBounds) (JNIEnv *env, jobject embeddedFrame,
 313             jint x, jint y, jint w, jint h);
 314     /**
 315      * Since 9
 316      * Synthesize native message to activate or deactivate EmbeddedFrame window
 317      * depending on the value of parameter doActivate, if "true" activates the
 318      * window; otherwise, deactivates the window.
 319      *
 320      * The embedded frame should be created by CreateEmbeddedFrame() method, or
 321      * this function will not have any effect.
 322      */
 323     void (JNICALL *SynthesizeWindowActivation) (JNIEnv *env,
 324             jobject embeddedFrame, jboolean doActivate);
 325 } JAWT;
 326 
 327 /*
 328  * Get the AWT native structure.  This function returns JNI_FALSE if
 329  * an error occurs.
 330  */
 331 _JNI_IMPORT_OR_EXPORT_
 332 jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt);
 333 
 334 #define JAWT_VERSION_1_3 0x00010003
 335 #define JAWT_VERSION_1_4 0x00010004
 336 #define JAWT_VERSION_1_7 0x00010007
 337 #define JAWT_VERSION_9 0x00010009
 338 
 339 #ifdef __cplusplus
 340 } /* extern "C" */
 341 #endif
 342 
 343 #endif /* !_JAVASOFT_JAWT_H_ */