The Java AWT Native Interface (JAWT) comprises a small set of native +(eg C language-based) APIs that provide a standard supported way +for interaction between Java API windows and surfaces, and +platform native API windows and surfaces. +Non-Java libraries may then render to a Java owned window. +
+Note: in this document the terms "Java AWT Native Interface", +"AWT Native Interface" and "JAWT" are interchangeable and +refer to this same specification. +
+The fundamental obstacle to native rendering without JAWT is that +is that the rendering code cannot identify where to draw. +The native code needs access to information about a Java +drawing surface (such as a handle to the underlying native ID of a +Canvas), but cannot get it.
+Without that information (ie without JAWT) an application could +use native rendering only by creating its own top-level window +not shared at all with Java. This is unacceptable for most uses. +Except for usage via JAWT, this is considered to be entirely +internal to the Java platform implementation: private, unsupported +and undocumented. ++JAWT should be supported in all headful implementations +where technically possible although this is not enforced by the JCK. +There is a platform-specific and a platform +independent portion to the API, to account for the differing +data structures and requirements of each platform. +This document specifies the platform independent portions and +also documents the platform dependent portions for the Oracle JDK +supported desktop operating environments. +For AWT the term platform is less tied to the underlying operating +system than it is to the desktop windowing environment. +
+Reasons for using the AWT Native Interface include +
+Drawbacks include +
+An example illustrating how easy it is to use the AWT Native Interface +is presented and discussed later in this document.
+ +JAWT usage depends on JNI
+The definition of Java Standard Edition includes JNI, the Java +Native Interface. Many Java developers will never need to use it, +but the interface is the only standard supported way for a Java +language program to interact directly with +application code that has been compiled to the native machine +instructions for the host processor architecture. +JNI is used where ever there is a need for mixed languages. +These are by no means limited to cases like AWT. For example, you +could use JNI to integrate with native code that communicates with +a peripheral device, such as a scanner, connected to a system via a +USB port.
+So JNI is general enough to be used to access almost any +sort of native library. +The rest of this document assumes a familiarity with how +to use JNI. + +
How to use JAWT
+In this section we describe the most common usage of the AWT +Native Interface — overriding the paint method to +direct drawing operations to a native rendering library which then +queries the Java VM to determine the information it needs in order +to render. Note, however, that any native code may use the AWT +Native Interface to learn about a target drawing surface, not just +code in a paint method.
+The first step in hooking up a native rendering library to a +Java Canvas is to define a new class that extends +Canvas and overrides the paint method. The Java +system routes all drawing operations for a Canvas object +through the paint method, as it does for all other GUI +objects. Canvas is a good candidate for the rendering surface as +it does not have any content as a Button would.
+The new paint method, to be implemented in the native +rendering library, must be declared as public native void +, and the native library itself is loaded at runtime by including a +call to System.loadLibrary( "myRenderingLib")in +the static block of the class. The myRenderingLib +name is used for the native shared library; for Linux or the Solaris +operating environment, the actual name for the library file on disk +is libmyRenderingLib.so .
+Here is a simple example of such a class:
+
+import java.awt.*;
+import java.awt.event.*;
+
+public class MyCanvas extends Canvas {
+ static {
+ System.loadLibrary("myRenderingLib");
+ }
+ public native void paint(Graphics g);
+
+ public static void main(String[] args) {
+ Frame f = new Frame();
+ f.setBounds(0, 0, 500, 110);
+ f.add(new MyCanvas());
+ f.addWindowListener( new WindowAdapter() {
+ public void windowClosing(WindowEvent ev) {
+ System.exit(0);
+ }
+ } );
+ f.show();
+ }
+}
+
+
+Note that this class has a main method that can be used +to run this code as an application for testing purposes.
+The next step is to run the javah tool on the +MyCanvas class file above to generate a C/C++ header file +that describes the interface to the native paint method +that Java expects to be used. javah is a standard tool +included with the JDK. NB: javac -h outputdir may also be used.
+ +The final step and the most interesting one is to +write the native rendering method, with an interface that conforms +to the header file that javah generated, and build it as a +standard shared library (called myRenderingLib in the +above example) by linking it, against the appropriate JDK provided +$JDK_HOME/lib/$JAWT_LIB library for the target platform. +Where JAWT_LIB has the base name "jawt" and follows platform +shared object naming rules. i.e.: +
Here is sample source code for a native paint method +designed for use in a X11-based drawing environment (Linux +or Solaris) and a Java VM where the AWT Native Interface is present:
+
+#include "MyCanvas.h"
+#include "jawt_md.h"
+
+/*
+ * Class: MyCanvas
+ * Method: paint
+ * Signature: (Ljava/awt/Graphics;)V
+ */
+JNIEXPORT void JNICALL Java_MyCanvas_paint
+(JNIEnv* env, jobject canvas, jobject graphics)
+{
+ JAWT awt;
+ JAWT_DrawingSurface* ds;
+ JAWT_DrawingSurfaceInfo* dsi;
+ JAWT_X11DrawingSurfaceInfo* dsi_x11;
+ jboolean result;
+ jint lock;
+ GC gc;
+
+ short i;
+ char *testString = "^^^ rendered from native code ^^^";
+
+ /* Get the AWT */
+ awt.version = JAWT_VERSION_9;
+ if (JAWT_GetAWT(env, &awt) == JNI_FALSE) {
+ printf("AWT Not found\n");
+ return;
+ }
+
+ /* Get the drawing surface */
+ ds = awt.GetDrawingSurface(env, canvas);
+ if (ds == NULL) {
+ printf("NULL drawing surface\n");
+ return;
+ }
+
+ /* Lock the drawing surface */
+ lock = ds->Lock(ds);
+ if((lock & JAWT_LOCK_ERROR) != 0) {
+ printf("Error locking surface\n");
+ awt.FreeDrawingSurface(ds);
+ return;
+ }
+
+ /* Get the drawing surface info */
+ dsi = ds->GetDrawingSurfaceInfo(ds);
+ if (dsi == NULL) {
+ printf("Error getting surface info\n");
+ ds->Unlock(ds);
+ awt.FreeDrawingSurface(ds);
+ return;
+ }
+
+ /* Get the platform-specific drawing info */
+ dsi_x11 = (JAWT_X11DrawingSurfaceInfo*)dsi->platformInfo;
+
+
+ /* Now paint */
+ gc = XCreateGC(dsi_x11->display, dsi_x11->drawable, 0, 0);
+ XSetBackground(dsi_x11->display, gc, 0);
+ for (i=0; i<36;i++)
+ {
+ XSetForeground(dsi_x11->display, gc, 10*i);
+ XFillRectangle(dsi_x11->display, dsi_x11->drawable, gc,
+ 10*i, 5, 90, 90);
+ }
+ XSetForeground(dsi_x11->display, gc, 155);
+ XDrawImageString(dsi_x11->display, dsi_x11->drawable, gc,
+ 100, 110, testString, strlen(testString));
+ XFreeGC(dsi_x11->display, gc);
+
+
+ /* Free the drawing surface info */
+ ds->FreeDrawingSurfaceInfo(dsi);
+
+ /* Unlock the drawing surface */
+ ds->Unlock(ds);
+
+ /* Free the drawing surface */
+ awt.FreeDrawingSurface(ds);
+}
+
+The key data structure here is JAWT , which is defined +in jawt.h (included by jawt_md.h) ; it provides +access to all the information the native code needs to get the job +done. The first part of the native method is boilerplate: it +populates the JAWT structure, gets a +JAWT_DrawingSurface structure, locks the surface (only one +drawing engine at a time, please!), then gets a +JAWT_DrawingSurfaceInfo structure that contains a pointer +(in the platformInfo field) to the necessary +platform-specific drawing information. It also includes the +bounding rectangle of the drawing surface and the current clipping +region.
+The structure of the information pointed to by +platformInfo is defined in a machine-dependent header file +called jawt_md.h. For X11 drawing, it includes +information about the X11 display and X11 drawable associated with +MyCanvas. After the drawing operations are completed, +there is more boilerplate code as JAWT_DrawingSurfaceInfo +is freed and JAWT_DrawingSurface is unlocked and +freed.
+The corresponding code for the GDI API on the Microsoft Windows platform would +be structured similarly, but would include the version of +jawt_md.h for Microsoft Windows and the structure located +in the platformInfo field of drawing surface info would be +cast as a JAWT_Win32DrawingSurfaceInfo* . And, of course, +the actual drawing operations would need to be changed to those +appropriate for the Microsoft Windows platform. +The same also for MacOS. +
+Summary
+The ability to draw directly into a Java Canvas from a +native code library is extremely useful for developers planning to +migrate a legacy software system to Java, especially one that +includes a high-performance rendering engine. It makes it much +easier to migrate in stages, leaving performance-sensitive +rendering code alone, while other less-sensitive portions of code +are converted to Java. The result can be a modern Java-centric +application, providing the benefit of portability and development +efficiency, but one that does not sacrifice an investment in +performance of a key piece of native code.
+References
+The definitive reference to the Java Native Interface is The +Java Native Interface: Programmer's Guide and Specification by +Sheng Liang. This book was published in June +1999 by Addison-Wesley. The ISBN is 0-201-32577-2.
+Appendix
+Header Files for jawt.h and jawt_md.h
+ +jawt.h
+
+#ifndef _JAVASOFT_JAWT_H_
+#define _JAVASOFT_JAWT_H_
+
+#include "jni.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * AWT native interface.
+ *
+ * The AWT native interface allows a native C or C++ application a means
+ * by which to access native structures in AWT. This is to facilitate moving
+ * legacy C and C++ applications to Java and to target the needs of the
+ * developers who need to do their own native rendering to canvases
+ * for performance or other reasons.
+ *
+ * Conversely it also provides mechanisms for an application which already
+ * has a native window to provide that to AWT for AWT rendering.
+ *
+ * Since every platform may be different in its native data structures
+ * and APIs for windowing systems the application must necessarily
+ * provided per-platform source and compile and deliver per-platform
+ * native code to use this API.
+ *
+ * These interfaces are not part of the Java SE specification and
+ * a VM is not required to implement this API. However it is strongly
+ * recommended that all implementations which support headful AWT
+ * also support these interfaces.
+ *
+ */
+
+/*
+ * AWT Native Drawing Surface (JAWT_DrawingSurface).
+ *
+ * For each platform, there is a native drawing surface structure. This
+ * platform-specific structure can be found in jawt_md.h. It is recommended
+ * that additional platforms follow the same model. It is also recommended
+ * that VMs on all platforms support the existing structures in jawt_md.h.
+ *
+ *******************
+ * EXAMPLE OF USAGE:
+ *******************
+ *
+ * On Microsoft Windows, a programmer wishes to access the HWND of a canvas
+ * to perform native rendering into it. The programmer has declared the
+ * paint() method for their canvas subclass to be native:
+ *
+ *
+ * MyCanvas.java:
+ *
+ * import java.awt.*;
+ *
+ * public class MyCanvas extends Canvas {
+ *
+ * static {
+ * System.loadLibrary("mylib");
+ * }
+ *
+ * public native void paint(Graphics g);
+ * }
+ *
+ *
+ * myfile.c:
+ *
+ * #include "jawt_md.h"
+ * #include <assert.h>
+ *
+ * JNIEXPORT void JNICALL
+ * Java_MyCanvas_paint(JNIEnv* env, jobject canvas, jobject graphics)
+ * {
+ * JAWT awt;
+ * JAWT_DrawingSurface* ds;
+ * JAWT_DrawingSurfaceInfo* dsi;
+ * JAWT_Win32DrawingSurfaceInfo* dsi_win;
+ * jboolean result;
+ * jint lock;
+ *
+ * // Get the AWT. Request version 9 to access features in that release.
+ * awt.version = JAWT_VERSION_9;
+ * result = JAWT_GetAWT(env, &awt);
+ * assert(result != JNI_FALSE);
+ *
+ * // Get the drawing surface
+ * ds = awt.GetDrawingSurface(env, canvas);
+ * assert(ds != NULL);
+ *
+ * // Lock the drawing surface
+ * lock = ds->Lock(ds);
+ * assert((lock & JAWT_LOCK_ERROR) == 0);
+ *
+ * // Get the drawing surface info
+ * dsi = ds->GetDrawingSurfaceInfo(ds);
+ *
+ * // Get the platform-specific drawing info
+ * dsi_win = (JAWT_Win32DrawingSurfaceInfo*)dsi->platformInfo;
+ *
+ * //////////////////////////////
+ * // !!! DO PAINTING HERE !!! //
+ * //////////////////////////////
+ *
+ * // Free the drawing surface info
+ * ds->FreeDrawingSurfaceInfo(dsi);
+ *
+ * // Unlock the drawing surface
+ * ds->Unlock(ds);
+ *
+ * // Free the drawing surface
+ * awt.FreeDrawingSurface(ds);
+ * }
+ *
+ */
+
+/*
+ * JAWT_Rectangle
+ * Structure for a native rectangle.
+ */
+typedef struct jawt_Rectangle {
+ jint x;
+ jint y;
+ jint width;
+ jint height;
+} JAWT_Rectangle;
+
+struct jawt_DrawingSurface;
+
+/*
+ * JAWT_DrawingSurfaceInfo
+ * Structure for containing the underlying drawing information of a component.
+ */
+typedef struct jawt_DrawingSurfaceInfo {
+ /*
+ * Pointer to the platform-specific information. This can be safely
+ * cast to a JAWT_Win32DrawingSurfaceInfo on Microsoft Windows or a
+ * JAWT_X11DrawingSurfaceInfo on Linux and Solaris. On MacOS this is a
+ * pointer to a NSObject that conforms to the JAWT_SurfaceLayers protocol.
+ * See jawt_md.h for details.
+ */
+ void* platformInfo;
+ /* Cached pointer to the underlying drawing surface */
+ struct jawt_DrawingSurface* ds;
+ /* Bounding rectangle of the drawing surface */
+ JAWT_Rectangle bounds;
+ /* Number of rectangles in the clip */
+ jint clipSize;
+ /* Clip rectangle array */
+ JAWT_Rectangle* clip;
+} JAWT_DrawingSurfaceInfo;
+
+#define JAWT_LOCK_ERROR 0x00000001
+#define JAWT_LOCK_CLIP_CHANGED 0x00000002
+#define JAWT_LOCK_BOUNDS_CHANGED 0x00000004
+#define JAWT_LOCK_SURFACE_CHANGED 0x00000008
+
+/*
+ * JAWT_DrawingSurface
+ * Structure for containing the underlying drawing information of a component.
+ * All operations on a JAWT_DrawingSurface MUST be performed from the same
+ * thread as the call to GetDrawingSurface.
+ */
+typedef struct jawt_DrawingSurface {
+ /* Cached reference to the Java environment of the calling thread.
+ * If Lock(), Unlock(), GetDrawingSurfaceInfo() or
+ * FreeDrawingSurfaceInfo() are called from a different thread,
+ * this data member should be set before calling those functions.
+ */
+ JNIEnv* env;
+ /* Cached reference to the target object */
+ jobject target;
+ /*
+ * Lock the surface of the target component for native rendering.
+ * When finished drawing, the surface must be unlocked with
+ * Unlock(). This function returns a bitmask with one or more of the
+ * following values:
+ *
+ * JAWT_LOCK_ERROR - When an error has occurred and the surface could not
+ * be locked.
+ *
+ * JAWT_LOCK_CLIP_CHANGED - When the clip region has changed.
+ *
+ * JAWT_LOCK_BOUNDS_CHANGED - When the bounds of the surface have changed.
+ *
+ * JAWT_LOCK_SURFACE_CHANGED - When the surface itself has changed
+ */
+ jint (JNICALL *Lock)
+ (struct jawt_DrawingSurface* ds);
+ /*
+ * Get the drawing surface info.
+ * The value returned may be cached, but the values may change if
+ * additional calls to Lock() or Unlock() are made.
+ * Lock() must be called before this can return a valid value.
+ * Returns NULL if an error has occurred.
+ * When finished with the returned value, FreeDrawingSurfaceInfo must be
+ * called.
+ */
+ JAWT_DrawingSurfaceInfo* (JNICALL *GetDrawingSurfaceInfo)
+ (struct jawt_DrawingSurface* ds);
+ /*
+ * Free the drawing surface info.
+ */
+ void (JNICALL *FreeDrawingSurfaceInfo)
+ (JAWT_DrawingSurfaceInfo* dsi);
+ /*
+ * Unlock the drawing surface of the target component for native rendering.
+ */
+ void (JNICALL *Unlock)
+ (struct jawt_DrawingSurface* ds);
+} JAWT_DrawingSurface;
+
+/*
+ * JAWT
+ * Structure for containing native AWT functions.
+ */
+typedef struct jawt {
+ /*
+ * Version of this structure. This must always be set before
+ * calling JAWT_GetAWT(). It affects the functions returned.
+ * Must be one of the known pre-defined versions.
+ */
+ jint version;
+ /*
+ * Return a drawing surface from a target jobject. This value
+ * may be cached.
+ * Returns NULL if an error has occurred.
+ * Target must be a java.awt.Component (should be a Canvas
+ * or Window for native rendering).
+ * FreeDrawingSurface() must be called when finished with the
+ * returned JAWT_DrawingSurface.
+ */
+ JAWT_DrawingSurface* (JNICALL *GetDrawingSurface)
+ (JNIEnv* env, jobject target);
+ /*
+ * Free the drawing surface allocated in GetDrawingSurface.
+ */
+ void (JNICALL *FreeDrawingSurface)
+ (JAWT_DrawingSurface* ds);
+ /*
+ * Since 1.4
+ * Locks the entire AWT for synchronization purposes
+ */
+ void (JNICALL *Lock)(JNIEnv* env);
+ /*
+ * Since 1.4
+ * Unlocks the entire AWT for synchronization purposes
+ */
+ void (JNICALL *Unlock)(JNIEnv* env);
+ /*
+ * Since 1.4
+ * Returns a reference to a java.awt.Component from a native
+ * platform handle. On Windows, this corresponds to an HWND;
+ * on Solaris and Linux, this is a Drawable. For other platforms,
+ * see the appropriate machine-dependent header file for a description.
+ * The reference returned by this function is a local
+ * reference that is only valid in this environment.
+ * This function returns a NULL reference if no component could be
+ * found with matching platform information.
+ */
+ jobject (JNICALL *GetComponent)(JNIEnv* env, void* platformInfo);
+
+ /**
+ * Since 9
+ * Creates a java.awt.Frame placed in a native container. Container is
+ * referenced by the native platform handle. For example on Windows this
+ * corresponds to an HWND. For other platforms, see the appropriate
+ * machine-dependent header file for a description. The reference returned
+ * by this function is a local reference that is only valid in this
+ * environment. This function returns a NULL reference if no frame could be
+ * created with matching platform information.
+ */
+ jobject (JNICALL *CreateEmbeddedFrame) (JNIEnv *env, void* platformInfo);
+
+ /**
+ * Since 9
+ * Moves and resizes the embedded frame. The new location of the top-left
+ * corner is specified by x and y parameters relative to the native parent
+ * component. The new size is specified by width and height.
+ *
+ * The embedded frame should be created by CreateEmbeddedFrame() method, or
+ * this function will not have any effect.
+ *
+ * java.awt.Component.setLocation() and java.awt.Component.setBounds() for
+ * EmbeddedFrame really don't move it within the native parent. These
+ * methods always locate the embedded frame at (0, 0) for backward
+ * compatibility. To allow moving embedded frames this method was
+ * introduced, and it works just the same way as setLocation() and
+ * setBounds() for usual, non-embedded components.
+ *
+ * Using usual get/setLocation() and get/setBounds() together with this new
+ * method is not recommended.
+ */
+ void (JNICALL *SetBounds) (JNIEnv *env, jobject embeddedFrame,
+ jint x, jint y, jint w, jint h);
+ /**
+ * Since 9
+ * Synthesize a native message to activate or deactivate an EmbeddedFrame
+ * window depending on the value of parameter doActivate, if "true"
+ * activates the window; otherwise, deactivates the window.
+ *
+ * The embedded frame should be created by CreateEmbeddedFrame() method, or
+ * this function will not have any effect.
+ */
+ void (JNICALL *SynthesizeWindowActivation) (JNIEnv *env,
+ jobject embeddedFrame, jboolean doActivate);
+} JAWT;
+
+/*
+ * Get the AWT native structure. This function returns JNI_FALSE if
+ * an error occurs.
+ */
+_JNI_IMPORT_OR_EXPORT_
+jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt);
+
+/*
+ * Specify one of these constants as the JAWT.version
+ * Specifying an earlier version will limit the available functions to
+ * those provided in that earlier version of JAWT.
+ * See the "Since" note on each API. Methods with no "Since"
+ * may be presumed to be present in JAWT_VERSION_1_3.
+ */
+#define JAWT_VERSION_1_3 0x00010003
+#define JAWT_VERSION_1_4 0x00010004
+#define JAWT_VERSION_1_7 0x00010007
+#define JAWT_VERSION_9 0x00090000
+
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* !_JAVASOFT_JAWT_H_ */
+
+
+jawt_md.h (Linux/Solaris/X11 operating environment version)
+
+#ifndef _JAVASOFT_JAWT_MD_H_
+#define _JAVASOFT_JAWT_MD_H_
+
+#include <X11/Xlib.h>
+#include <X11/Xutil.h>
+#include <X11/Intrinsic.h>
+#include "jawt.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * X11-specific declarations for AWT native interface.
+ * See notes in jawt.h for an example of use.
+ */
+typedef struct jawt_X11DrawingSurfaceInfo {
+ Drawable drawable;
+ Display* display;
+ VisualID visualID;
+ Colormap colormapID;
+ int depth;
+} JAWT_X11DrawingSurfaceInfo;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* !_JAVASOFT_JAWT_MD_H_ */
+
+jawt_md.h (Microsoft Windows version)
+
+#ifndef _JAVASOFT_JAWT_MD_H_
+#define _JAVASOFT_JAWT_MD_H_
+
+#include <windows.h>
+#include "jawt.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Microsoft Windows specific declarations for AWT native interface.
+ * See notes in jawt.h for an example of use.
+ */
+typedef struct jawt_Win32DrawingSurfaceInfo {
+ /* Native window, DDB, or DIB handle */
+ union {
+ HWND hwnd;
+ HBITMAP hbitmap;
+ void* pbits;
+ };
+ /*
+ * This HDC should always be used instead of the HDC returned from
+ * BeginPaint() or any calls to GetDC().
+ */
+ HDC hdc;
+ HPALETTE hpalette;
+} JAWT_Win32DrawingSurfaceInfo;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* !_JAVASOFT_JAWT_MD_H_ */
+
+jawt_md.h (MacOS version)
++#ifndef _JAVASOFT_JAWT_MD_H_ +#define _JAVASOFT_JAWT_MD_H_ + +#include "jawt.h" + +#ifdef __OBJC__ +#import+ + + --- old/src/java.desktop/share/classes/java/awt/package-info.java 2017-04-26 11:33:47.871600819 -0700 +++ new/src/java.desktop/share/classes/java/awt/package-info.java 2017-04-26 11:33:47.663600819 -0700 @@ -54,6 +54,8 @@ * * * @since 1.0 --- old/src/java.desktop/share/native/include/jawt.h 2017-04-26 11:33:48.315600817 -0700 +++ new/src/java.desktop/share/native/include/jawt.h 2017-04-26 11:33:48.139600818 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -38,18 +38,22 @@ * The AWT native interface allows a native C or C++ application a means * by which to access native structures in AWT. This is to facilitate moving * legacy C and C++ applications to Java and to target the needs of the - * community who, at present, wish to do their own native rendering to canvases - * for performance reasons. Standard extensions such as Java3D also require a - * means to access the underlying native data structures of AWT. - * - * There may be future extensions to this API depending on demand. - * - * A VM does not have to implement this API in order to pass the JCK. - * It is recommended, however, that this API is implemented on VMs that support - * standard extensions, such as Java3D. + * developers who need to do their own native rendering to canvases + * for performance or other reasons. + * + * Conversely it also provides mechanisms for an application which already + * has a native window to provide that to AWT for AWT rendering. + * + * Since every platform may be different in its native data structures + * and APIs for windowing systems the application must necessarily + * provided per-platform source and compile and deliver per-platform + * native code to use this API. + * + * These interfaces are not part of the Java SE specification and + * a VM is not required to implement this API. However it is strongly + * recommended that all implementations which support headful AWT + * also support these interfaces. * - * Since this is a native API, any program which uses it cannot be considered - * 100% pure java. */ /* @@ -58,7 +62,7 @@ * For each platform, there is a native drawing surface structure. This * platform-specific structure can be found in jawt_md.h. It is recommended * that additional platforms follow the same model. It is also recommended - * that VMs on Win32 and Solaris support the existing structures in jawt_md.h. + * that VMs on all platforms support the existing structures in jawt_md.h. * ******************* * EXAMPLE OF USAGE: @@ -98,8 +102,8 @@ * jboolean result; * jint lock; * - * // Get the AWT - * awt.version = JAWT_VERSION_1_3; + * // Get the AWT. Request version 9 to access features in that release. + * awt.version = JAWT_VERSION_9; * result = JAWT_GetAWT(env, &awt); * assert(result != JNI_FALSE); * @@ -154,7 +158,7 @@ /* * Pointer to the platform-specific information. This can be safely * cast to a JAWT_Win32DrawingSurfaceInfo on Windows or a - * JAWT_X11DrawingSurfaceInfo on Solaris. On Mac OS X this is a + * JAWT_X11DrawingSurfaceInfo on Linux and Solaris. On Mac OS X this is a * pointer to a NSObject that conforms to the JAWT_SurfaceLayers * protocol. See jawt_md.h for details. */ @@ -237,7 +241,8 @@ typedef struct jawt { /* * Version of this structure. This must always be set before - * calling JAWT_GetAWT() + * calling JAWT_GetAWT(). It affects the functions returned. + * Must be one of the known pre-defined versions. */ jint version; /* @@ -332,6 +337,13 @@ _JNI_IMPORT_OR_EXPORT_ jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt); +/* + * Specify one of these constants as the JAWT.version + * Specifying an earlier version will limit the available functions to + * those provided in that earlier version of JAWT. + * See the "Since" note on each API. Methods with no "Since" + * may be presumed to be present in JAWT_VERSION_1_3. + */ #define JAWT_VERSION_1_3 0x00010003 #define JAWT_VERSION_1_4 0x00010004 #define JAWT_VERSION_1_7 0x00010007 --- old/src/java.desktop/macosx/native/include/jawt_md.h 2017-04-26 11:33:48.691600816 -0700 +++ new/src/java.desktop/macosx/native/include/jawt_md.h 2017-04-26 11:33:48.547600816 -0700 @@ -37,7 +37,7 @@ #endif /* - * Mac OS X specific declarations for AWT native interface. + * MacOS specific declarations for AWT native interface. * See notes in jawt.h for an example of use. */+#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/* + * MacOS specific declarations for AWT native interface. + * See notes in jawt.h for an example of use. + */ + +/* + * When calling JAWT_GetAWT with a JAWT version less than 1.7, you must pass this + * flag or you will not be able to get a valid drawing surface and JAWT_GetAWT will + * return false. This is to maintain compatibility with applications that used the + * interface with Java 6 which had multiple rendering models. This flag is not necessary + * when JAWT version 1.7 or greater is used as this is the only supported rendering mode. + * + * Example: + * JAWT awt; + * awt.version = JAWT_VERSION_1_4 | JAWT_MACOSX_USE_CALAYER; + * jboolean success = JAWT_GetAWT(env, &awt); + */ +#define JAWT_MACOSX_USE_CALAYER 0x80000000 + +/* + * When the native Cocoa toolkit is in use, the pointer stored in + * JAWT_DrawingSurfaceInfo->platformInfo points to a NSObject that conforms to the + * JAWT_SurfaceLayers protocol. Setting the layer property of this object will cause the + * specified layer to be overlaid on the Components rectangle. If the window the + * Component belongs to has a CALayer attached to it, this layer will be accessible via + * the windowLayer property. + */ +#ifdef __OBJC__ +@protocol JAWT_SurfaceLayers +@property (readwrite, retain) CALayer *layer; +@property (readonly) CALayer *windowLayer; +@end +#endif + +#ifdef __cplusplus +} +#endif + +#endif /* !_JAVASOFT_JAWT_MD_H_ */ +