Java AWT Native Interface: Difference between revisions

Revision as of 20:14, 29 January 2006

Latest revision as of 13:29, 31 December 2024

(60 intermediate revisions by 49 users not shown)

Line 1:

{{Multiple issues|

The [[Java Native Interface]] enabled Developers to add platform-dependant functionality to Java Applications. It enables developers to add things like time-critical operations like mathematical calculations and 3-D Rendering. 3-D Rendering is interesting, because the native side don't know where to draw the graphics! The AWT Native Interface is designed to give developers a sort of a "canvas" for their native programs to "draw" on. In fact, the Java 3D API (Extension to the standard J2SE JDK) relies heavily on the AWT Native Interface to render 3D objects in Java! The AWT Native Interface is very similar to the JNI, and, the steps are, in fact, the same as those of the JNI. So, it is highly recommended that you read the [[Java Native Interface]] article first before continuing.

{{unreferenced|date=June 2012}}

{{original research|date=June 2012}}

{{tone|date=June 2012}}

}}

'''Java AWT Native Interface''' ('''JAWT''') is an interface for the [[Java (programming language)|Java programming language]] that enables [[Rendering (computer graphics)|rendering]] [[library (computer science)|libraries]] compiled to [[native code]] to draw directly to a Java [[Abstract Window Toolkit]] (AWT) {{Javadoc:SE|java/awt|Canvas|module=java.desktop}} [[object (computer science)|object]] drawing surface.

Note that the AWT Interface only existed since JDK 1.3 ("Kestrel")

The [[Java Native Interface]] (JNI) allows developers to add platform-dependent functionality to [[Java (programming language)|Java]] [[application software|applications]]. The JNI enables developers to add time-critical operations like [[Mathematics|mathematical]] calculations and [[3D rendering]].

==AWT Native Interface Example Walkthrough==

===1. Create the Java Side===

Type in this in a .java file named JavaSideCanvas and compile:

<pre>

import java.awt.*;

import java.awt.event.*;

Previously, native 3D rendering was challenging because the native code did not have access to the graphic context. The AWT Native Interface is designed to give developers access to an AWT <code>Canvas</code> for direct drawing with native code. In fact, the [[Java 3D]] API extension to the standard [[Java SE]] [[JDK]] relies heavily on the AWT Native Interface to render 3D objects in Java.

public class JavaSideCanvas extends Canvas {

static {

System.loadLibrary("NativeSideCanvas");

}

The AWT Native Interface is very similar to the JNI, and the steps are the same as those of the JNI. See the [[Java Native Interface]] article for an explanation of the JNI techniques employed by the AWT Native Interface. The AWT Native Interface was added to the [[Java platform]] with the [[Java Platform, Standard Edition|J2SE]] 1.3 ("Kestrel") version.

public native void paint(Graphics g);

== Native painting ==

public static void main(String[] args) {

One can paint as if it is a native application. In [[Microsoft Windows|Windows]], the JVM will pass a HWND and other window information to the native application so that the application will "know" where to draw. It could use GDI to draw a Rectangle. The window information the native side needs will be in a <code>JAWT_Win32DrawingSurfaceInfo</code> structure (depending on the [[operating system]]) which can be retrieved with this line: {{code|lang=c|1=dsi_win = (JAWT_Win32DrawingSurfaceInfo*)dsi->platformInfo;}}

Frame f = new Frame();

f.setBounds(0, 0, 500, 500);

JavaSideCanvas jsc = new JavaSideCanvas();

f.add(jsc);

f.addWindowListener(new WindowAdapter() {

public void windowClosing(WindowEvent ev) {

System.exit(0);

}

});

f.show();

}

}

</pre>

If you read the [[Java Native Interface]] article you know the native keywords and the loadLibrary() method. The paint method will be simply invoked when the JVM "repaints" the screen.

===2. Create Header File===

Create Header File as Usual (Look at [[Java Native Interface]] for help)

The Header File looks like this now:

<pre>

/* DO NOT EDIT THIS FILE - it is machine generated */

#include <jni.h>

/* Header for class JavaSideCanvas */

==References==

#ifndef _Included_JavaSideCanvas

{{reflist}}

#define _Included_JavaSideCanvas

#ifdef __cplusplus

extern "C" {

#endif

#undef JavaSideCanvas_FOCUS_TRAVERSABLE_UNKNOWN

#define JavaSideCanvas_FOCUS_TRAVERSABLE_UNKNOWN 0L

#undef JavaSideCanvas_FOCUS_TRAVERSABLE_DEFAULT

#define JavaSideCanvas_FOCUS_TRAVERSABLE_DEFAULT 1L

#undef JavaSideCanvas_FOCUS_TRAVERSABLE_SET

#define JavaSideCanvas_FOCUS_TRAVERSABLE_SET 2L

#undef JavaSideCanvas_TOP_ALIGNMENT

#define JavaSideCanvas_TOP_ALIGNMENT 0.0f

#undef JavaSideCanvas_CENTER_ALIGNMENT

#define JavaSideCanvas_CENTER_ALIGNMENT 0.5f

#undef JavaSideCanvas_BOTTOM_ALIGNMENT

#define JavaSideCanvas_BOTTOM_ALIGNMENT 1.0f

#undef JavaSideCanvas_LEFT_ALIGNMENT

#define JavaSideCanvas_LEFT_ALIGNMENT 0.0f

#undef JavaSideCanvas_RIGHT_ALIGNMENT

#define JavaSideCanvas_RIGHT_ALIGNMENT 1.0f

#undef JavaSideCanvas_serialVersionUID

#define JavaSideCanvas_serialVersionUID -7644114512714619750i64

#undef JavaSideCanvas_serialVersionUID

#define JavaSideCanvas_serialVersionUID -2284879212465893870i64

/*

* Class: JavaSideCanvas

* Method: paint

* Signature: (Ljava/awt/Graphics;)V

*/

JNIEXPORT void JNICALL Java_JavaSideCanvas_paint

(JNIEnv *, jobject, jobject);

== External links==

#ifdef __cplusplus

{{Portal|Computer programming}}

}

{{Wikibooks|Java Swings/AWT}}

#endif

*[https://docs.oracle.com/javase/8/docs/technotes/guides/awt/AWT_Native_Interface.html The AWT Native Interface]

#endif

*[https://www.infoworld.com/article/2077589/java-tip-86--support-native-rendering-in-jdk-1-3.html Support native rendering in JDK 1.3]

</pre>

{{Java desktop}}

===3. Implement the C++ side===

Type this in a file named NativeSideCanvas.cpp and compile into a library:

(See [[Java Native Interface]])

[[Category:Java platform|AWT Native Interface]]

Don't Forget to link this with jawt.lib and gdi32.lib (because it draws a rectangle)

Microsoft C++:

<pre>

#include "jawt_md.h"

#include <assert.h>

#include "JavaSideCanvas.h"

JNIEXPORT void JNICALL Java_JavaSideCanvas_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

awt.version = JAWT_VERSION_1_3;

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 !!! //

//////////////////////////////

//Simple paints a rectangle (GDI32)

Rectangle(dsi_win->hdc, 50, 50, 200, 200);

// Free the drawing surface info

ds->FreeDrawingSurfaceInfo(dsi);

// Unlock the drawing surface

ds->Unlock(ds);

// Free the drawing surface

awt.FreeDrawingSurface(ds);

}

</pre>

(Solaris Code and Other operating systems: look at links below)

The code above should be self-explanatory

===4. Run the Example===

Run the file as usual (See [[Java Native Interface]])

It's interesting to note that the AWT Native Interface requires the jawt.dll (or jawt.so) to run with the application, so the easiest way to to that is copying the jawt.dll (should be in the .../jre/bin of the JDK's installation path)

You should see a window with a rectangle drawn in it.

Congratulations! You have made your first AWT Native Application!

==Note about Native Painting==

As you can see, you can paint as if it is a native application. In Windows, the JVM will pass a HWND and other window information to your native application so that your application will "know" where to draw. In this example, it uses GDI to draw a Rectangle. The window information your native side need will be in a JAWT_Win32DrawingSurfaceInfo structure (Depending on Operating System) which can be retrieved with this line:

<pre>

dsi_win = (JAWT_Win32DrawingSurfaceInfo*)dsi->platformInfo;

</pre>

dsi_win has the information, look in the jni.h file for details.

==External links==

The AWT Native Interface

*http://java.sun.com/j2se/1.5.0/docs/guide/awt/1.3/AWT_Native_Interface.html

Java Native Interface (Wikipedia Article)

*http://en.wikipedia.org/wiki/Java_Native_Interface

[[Category:Java platform]]