OS X needs a screen saver configuration it recognizes, so the first step of creating a screen saver is creating the OS X interface. In this case, the interface is an Objective-C object extending the ScreenSaverView class. The name of my ScreenSaverView child is ScreenSaverChild. (It is an easy name to remember, anyway.)

The following source is for the Objective-C ScreenSaverChild interface:

#import <ScreenSaver/ScreenSaver.h>
#include "SSWrapper.h"
@interface ScreenSaverChild : ScreenSaverView
{
}
- (void) drawRectangleX: (CGFloat) x
                      y: (CGFloat) y
                  width: (CGFloat) width
                 height: (CGFloat) height;
- (void) setColorRed: (CGFloat) red
               green: (CGFloat) green
                blue: (CGFloat) blue
               alpha: (CGFloat) alpha;
@end

As you can see from the ScreenSaverChild @interface, I expose methods allowing the drawing of rectangles and the setting of colors. Both the drawRectangleX:y:width:height: method and the setColorRed:green:blue:alpha: method are used by callbacks from the Java code.

The following source is for the Objective-C ScreenSaverChild implementation. This example is very similar to the base_screen_saverView class in the first example. The main difference is that the logic from the drawScreen method in base_screen_saverView is now in the Java WeaveSS class.

#import "ScreenSaverChild.h"

@implementation ScreenSaverChild
- (id)initWithFrame:(NSRect)frame isPreview:(BOOL)isPreview
{
   self = [super initWithFrame:frame isPreview:isPreview];
   if (self) {
      [self setAnimationTimeInterval:1/30.0];

}
   return self;
}
- (void)startAnimation
{
   [super startAnimation];

   NSSize screenSize = [self bounds].size;
   int x1 = screenSize.width;
   int y1 = screenSize.height;

   setScreenSaver(self, x1, y1);
   startJVM();

}
- (void)stopAnimation
{
   [super stopAnimation];

   stopJVM();
}
- (void)drawRect:(NSRect)rect
{
   [super drawRect:rect];
}
- (void)animateOneFrame
{
   animateFrameRequest();
}
- (BOOL)hasConfigureSheet
{
   return NO;
}
- (NSWindow*)configureSheet
{
   return nil;
}
- (void) drawRectangleX: (CGFloat) x
                      y: (CGFloat) y
                  width: (CGFloat) width
                 height: (CGFloat) height
{
   NSRect rectToDraw;
   rectToDraw = NSMakeRect (x, y, width, height);
   [NSBezierPath fillRect: rectToDraw];

}
- (void) setColorRed: (CGFloat) red

green: (CGFloat) green
                blue: (CGFloat) blue
               alpha: (CGFloat) alpha;
{
   NSColor *colorToSet;
   colorToSet = [NSColor colorWithCalibratedRed: red
                                          green: green
                                           blue: blue
                                          alpha: alpha];
   [colorToSet set];

}
@end

The next step in the process of creating a Java screen saver is creating a JVM. Also, you need to hook up the Java and Objective-C methods. I divided this task into two files named SSWrapper.m and SSWrapper.h. The SSWrapper.m file is a little complex, so I break up the source with annotations explaining the code.

The following source is for the SSWrapper.h header file. The SSWrapper.h file contains all the #includes and #imports for the SSWrapper.m file. The SSWrapper header does not contain an interface definition because I did not define SSWrapper as an Objective-C class. Nothing prevents you from making SSWrapper into a class in your Java screen savers. Above all else, clarity in the code is most important. Make your decision based on code maintainability.

#import <Cocoa/Cocoa.h>
#include <jni.h>
#include <stdio.h>
#include <unistd.h>
#import "ScreenSaverChild.h"

I used #include instead of #import for jni.h, stdio.h, and unistd.h, because they are all written to handle multiple includes. However, #import works in these cases too. Using #include is just a stylistic choice here.

The following source is for the SSWrapper.m file. The SSWrapper.m file is extremely important to the process of creating a Java screen saver. SSWrapper.m obtains the JVM reference and the jmethodIDs, and it registers the names and function implementations of Java's native callbacks.

#include "SSWrapper.h"
// shutdown flag
jboolean shutdown_requested = JNI_FALSE;

// reused JNI variables
JavaVM *jvm;

jmethodID midAnimate;// an ID not a reference!
jclass javaWrapperClass;// a global, not local, reference
// Screen Saver variables
ScreenSaverChild *myScreenSaver;
jint ssWidth;
jint ssHeight;

void setScreenSaver(ScreenSaverChild *ss, int w, int h)
{
   myScreenSaver = ss;
   ssWidth = w;
   ssHeight = h;
}

The jvm variable is literally the variable that holds a reference to the JVM. The midAnimate jmethodID holds an ID to the Java method for animating the screen saver. The javaWrapperClass reference holds a global reference to the OSXScreenSaverWrapper class. The setScreenSaver() function stores a reference to the ScreenSaverChild instance, along with the width and height of the screen.

// Java "native" callbacks from JNI
// header file

//Class:     com.genedavis.OSXScreenSaverWrapper
//Method:    void setColor(double,double,double,double)
JNIEXPORT void
JNICALL OSXScreenSaverWrapper_setColor
(JNIEnv * env, jclass jc, jdouble red, jdouble green, jdouble
blue, jdouble alpha)
{
   [myScreenSaver setColorRed: red
             green: green
              blue: blue
             alpha: alpha];

}
//Class:     com.genedavis.OSXScreenSaverWrapper
//Method:    void drawRectangle (double,double,double,double)
JNIEXPORT void JNICALL OSXScreenSaverWrapper_drawRectangle
(JNIEnv * env, jclass jc, jdouble x, jdouble y, jdouble width,
   jdouble height)
{
   [myScreenSaver drawRectangleX: x
                               y: y
                           width: width
                          height: height];
}

The SSWrapper file creates two native implementations for Java callbacks:

OSXScreenSaverWrapper_setColor
OSXScreenSaverWrapper_drawRectangle

Looking at the names of both functions, it is obvious that javah did not create these method names. The function names are far too simple to be javah-generated. Both methods are registered native methods set up by this function:

registerOSXScreenSaverWrapperNatives

Conveniently, that is the next function in the code.

JNIEXPORT void registerOSXScreenSaverWrapperNatives
(JNIEnv * env, jclass jc)
{
   // fill with Java's native names,
   // followed by javp style signature
   // and the C version of the method
   // names
   JNINativeMethod natives[] =
   {
      {
         "setColor",
         " (DDDD)V",
         &OSXScreenSaverWrapper_setColor
      },

      {
         "drawRectangle",
         " (DDDD)V",
         &OSXScreenSaverWrapper_drawRectangle
      }
   };

   // adding the methods from the C
   // side instead of the Java side
   (*env)->RegisterNatives(env, jc, natives, 2);
}

The registerOSXScreenSaverWrapperNatives function creates a JNINativeMethod array containing the two native methods defined by the Java OSXScreenSaverWrapper class. The two methods are then registered by the RegisterNatives() function. These two function implementations are statically linked instead of dynamically linked.

void startJVM(void)
{

NSLog( @"Called startJVM()" );


   // declaring the JVM and environment
   // variables
   JNIEnv *env;

   // setting up arguments to JVM
   JavaVMInitArgs jvm_args;

   // Always declare the newest version of
   // JNI you want to use. JNI_VERSION_1_6
   // corresponds to Java 6.
   jvm_args.version = JNI_VERSION_1_6;

   // JavaVMOptions are the properties
   // you are already familiar with
   // from the command line
   JavaVMOption options[1];

   // The Java JAR file is placed in the Resources
   // directory of the *.saver bundle. This code
   // locates the JAR file in the bundle and then sets
   // the -Djava.class.path= option so that the
   // JVM knows where to find the Java classes.
   NSString * javaOption = @"-Djava.class.path=";
   NSBundle* myBundle =
      [NSBundle bundleForClass:[myScreenSaver class]];
   NSString* myJar = [myBundle pathForResource:@"weaver_screen_saver" ofType:@"jar"];
   javaOption = [javaOption stringByAppendingString:myJar];
   options[0].optionString = (char*) [javaOption UTF8String];

   // The option array length MUST be declared.
   // Remember this is C, and array lengths
   // are not known unless your program explicitly
   // stores them.
   jvm_args.nOptions = 1;

   // setting the options
   jvm_args.options = options;
   jvm_args.ignoreUnrecognized = JNI_FALSE;

At this point, you are ready to create a JVM. However, screen savers are modules in a larger process, which implies that a JVM may already exist. Never assume you are the only one creating JVMs. Only one JVM can be created per process, so if a JVM already exists, you cannot create a second one. Also, if a JVM was created and destroyed, you are still barred from creating another JVM. If you are running in preview mode, because the user is using System Preferences to choose a screen saver, and the user clicks the Test button to test your screen saver, your test needs to grab the existing JVM from the preview screen saver instance.

In short, look for existing JVMs before creating JVMs. When finished with a JVM, remember not to destroy it unless you are certain it is not still needed. In the case of screen savers, don't destroy your JVMs.

// checking for existing JVM
 // This is a must! Multiple JVMs cannot be created
// in one process
jsize jvmCount = 0;
int foundJVM = JNI_GetCreatedJavaVMs(&jvm, 1, &jvmCount);
if (foundJVM == 0 && jvmCount > 0)
{
   // succeeded in getting an existing JVM
   // attaching this thread
   (*jvm)->AttachCurrentThread(jvm, (void**) &env, NULL);
}
else
{
   // no JVM found, ... creating the JVM
   // this thread is automatically attached
   JNI_CreateJavaVM(&jvm, (void**)&env, &jvm_args);
}

Now, you have a JVM with a reference in your jvm variable. All that remains in this function is to obtain a global reference to the OSXScreenSaverWrapper class and use the reference to obtain method IDs for the startAnimation() and the animateOneFrame() methods.

// obtaining the Java class com.genedavis.
OSXScreenSaverWrapper
jclass localJavaWrapperClass =
   (*env)->FindClass(env, "com/genedavis/
OSXScreenSaverWrapper");
javaWrapperClass = (*env)->NewWeakGlobalRef(env,
localJavaWrapperClass);// make reference permanent
// don't need reference anymore
(*env)->DeleteLocalRef(env, localJavaWrapperClass);

// registering the statically linked native methods
// for com.genedavis.OSXScreenSaverWrapper
registerOSXScreenSaverWrapperNatives(env, javaWrapperClass);

jmethodID mid =
(*env)->GetStaticMethodID(env, javaWrapperClass,
"startAnimation", " ()V");

(*env)->CallStaticVoidMethod(env, javaWrapperClass, mid);

midAnimate =
   (*env)->GetStaticMethodID(env, javaWrapperClass,
"animateOneFrame", " (IIZ)V");
}

The previous function handled starting the screen saver. This includes calling the startAnimation() method in the Java code. The code in the next two functions calls the Java methods for animating the screen saver and stopping the screen saver.

void stopJVM(void)
{

   NSLog( @"Called stopJVM()" );


   JNIEnv *env = NULL;
   jint env_error = JNI_OK;

   // Use the JVM reference to get an up-to-date
   // JNIEnv. JNIEnv variables need constant
   // updates
   env_error = (*jvm)->GetEnv(
                              jvm,
                              (void **)&env,
                              JNI_VERSION_1_6);

   jmethodID mid =
   (*env)->GetStaticMethodID(env, javaWrapperClass,
   "stopAnimation", " ()V");
   (*env)->CallStaticVoidMethod(env, javaWrapperClass, mid);
   // cleaning up the JVM. Do NOT destroy the JVM!
   (*env)->DeleteWeakGlobalRef(env, javaWrapperClass);
}
void animateFrameRequest(void)
{
   JNIEnv *env = NULL;
   jint env_error = JNI_OK;

   // Use the JVM reference to get an up-to-date
   // JNIEnv. JNIEnv variables need constant
   // updates
   env_error = (*jvm)->GetEnv(
                              jvm,
                              (void **)&env,
                              JNI_VERSION_1_6);

if ([myScreenSaver isPreview])
   {
      (*env)->CallStaticVoidMethod(env, javaWrapperClass,
   midAnimate, ssWidth, ssHeight, JNI_TRUE);
   }
   else
   {
      (*env)->CallStaticVoidMethod(env, javaWrapperClass,
   midAnimate, ssWidth, ssHeight, JNI_FALSE);
   }
}

That completes the native code and JNI necessary for the Java screen saver. When you make your own Java screen savers, you need to create additional native methods to register with the RegisterNatives() functions. Make sure you understand how the Java callbacks to the native screen saver code work, and you will do fine.

In the java_screen_saver project, the Java code is about the same length as the native code. In more complex screen savers, the Java code grows much larger than the native code. Most of your variations from this example project will exist in the Java code and the implementation of OSXScreenSaverWrapper's native methods.

All the Java communication from and to Objective-C goes through the OSXScreenSaverWrapper class. The OSXScreenSaverWrapper class acts as the wrapper for all the native code in the screen saver. The following source is for the Java OSXScreenSaverWrapper class:

package com.genedavis;
public class OSXScreenSaverWrapper
{
   private static WeaveSS weave1;
   private static WeaveSS weave2;
   private static WeaveSS weave3;

   @SuppressWarnings("unused")
   private static void startAnimation()
   {
      // creating objects that control the drawing
      weave1 = new WeaveSS();
      weave2 = new WeaveSS();
      weave3 = new WeaveSS();

}

   @SuppressWarnings("unused")
   private static void stopAnimation()
   {
      // cleaning up
      weave1 = null;
      weave2 = null;
      weave3 = null;
   }

   @SuppressWarnings("unused")
   private static void animateOneFrame(
         int width,
         int height,
         boolean isPreview)
   {
      weave1.drawScreen();
      weave2.drawScreen();
      weave3.drawScreen();

   }

   public static native void setColor(
         double red,
         double green,
         double blue,
         double alpha);

   public static native void drawRectangle(
         double x,
         double y,
         double width,
         double height);
}

The first three methods, startAnimation(), stopAnimation(), and animateOneFrame(), are called from the native code. They correspond to similarly named methods in the Objective-C ScreenSaverChild class. I set these three methods as private to discourage their use in the Java code. They are meant to be called only from the native code.

The last two methods, setColor() and drawRectangle(), are declared as native methods. These are the callbacks from Java to the native ScreenSaverChild. This example screen saver requires only two Java native methods. NSViews accept many drawing-related commands, so the potential list of useful native methods is very long. I give additional ideas related specifically to NSBezierPaths, later in this chapter.

All that's left is the code for drawing the screen saver animation. WeaveSS instances handle drawing the screen. The following source is for the Java WeaveSS class. I break up the code with explanations of what is occurring.

package com.genedavis;
public class WeaveSS {
   private double x1;
   private double y1;

   private boolean nw;
   private boolean ne;
   private boolean sw;
   private boolean se;

   private double redChoice;
   private double greenChoice;
   private double blueChoice;

   private int screenWidth;
   private int screenHeight;


   public WeaveSS()
   {
      int direction = (int)(Math.random()*4+1);
      switch ( direction )
      {
         case 1:
            nw = true;
            break;
         case 2:
            ne = true;
            break;
         case 3:
            sw = true;
            break;
         default:
            se = true;
            break;
      }

      pickColor();

      x1 = Math.random()*(screenWidth-12)+1;
      y1 = Math.random()*(screenWidth-12)+1;
   }

Each WeaveSS object represents one woven line on the screen. The WeaveSS constructor chooses a random movement direction for this instance. WeaveSS chooses a random starting color for itself by calling the pickColor() method. Finally, WeaveSS chooses a starting location for itself.

public void drawScreen()
{
      // set current color

      OSXScreenSaverWrapper.setColor(
            redChoice,
            greenChoice,
            blueChoice,
            0.5);

      // draw current position

      OSXScreenSaverWrapper.drawRectangle(
            x1,
            y1,
            10,
            10);

      // move square

      if (nw)
      {
         x1--;
         y1++;
      }
      else if (ne)
      {
         x1++;
         y1++;
      }
      else if (sw)
      {
         x1--;
         y1--;
      }
      else if (se)
      {
         x1++;
         y1--;
      }


      // bounce off walls

if (y1 < 1)
      {
         if (se)
         {
            se = false;
            ne = true;
            pickColor();
         }
         else if (sw)
         {
            sw = false;
            nw = true;
            pickColor();
         }
      }

      if (y1 > screenHeight - 11.0)
      {
         if (ne)
         {
            ne = false;
            se = true;
            pickColor();
         }
         else if (nw)
         {
            nw = false;
            sw = true;
            pickColor();
         }
      }

      if (x1 < 1)
      {
         if (sw)
         {
            sw = false;
            se = true;
            pickColor();
         }
         else if (nw)
         {
            nw = false;
            ne = true;
            pickColor();
         }
      }

if (x1 > screenWidth - 11.0)
      {
         if (se)
         {
            se = false;
            sw = true;
            pickColor();
         }
         else if (ne)
         {
            ne = false;
            nw = true;
            pickColor();
         }
      }

   }

The drawScreen() method sets the screen saver's drawing color and draws a rectangle in the current drawing location. After taking care of drawing based on the current color and location, the drawScreen() method moves the drawing location one point. The drawScreen() method finishes by determining whether the motion direction and color should change.

public void pickColor()
   {
      redChoice = Math.random();
      greenChoice = Math.random();
      blueChoice = Math.random();
   }
}

The pickColor() method randomly chooses a new color for the current WeaveSS instance. New colors are chosen when the WeaveSS object is constructed and when it reaches the edge of the screen and changes direction.

That is all the code necessary to make your own screen saver. Only one task remains. You must package screen savers on OS X in *.saver bundles. Creating custom SAVER bundles is the topic of the next couple of sections.