Skip to content

Sc21 Tutorial _ Part 1 Introduction

Jump to bottom
Volker Enderlein edited this page Jan 12, 2020 · 2 revisions

You are here: Home → Documentation → Mac information page → Sc21 → Sc21 Tutorial - Part 1 Introduction

Sc21 Tutorial - Part 1: Introduction

This tutorial is step-by-step guide to building a Cocoa application with Coin 3D rendering.

The following tutorial assumes that you have Coin and Sc21 compiled on your system, and that you are familiar with the basics of using Apple's Xcode IDE.

If you have never used Xcode and Interface Builder before, please take a look at Apple's introduction to creating Cocoa applications. If you are new to Cocoa programming and want to learn more about it, an excellent introductory book I can suggest is Aaron Hillegass' "Cocoa Programming for Mac OS X".

Create a new project.

Start Xcode and create a new project: a Cocoa application. Name it as you will; in this tutorial, we will call it sc21-tutorial-test.

Add the frameworks.

You will use Sc21 and Coin, so you have to add these two frameworks.

To do this, choose "Add to Project..." from the Project menu. (In Xcode versions < 1.5, you have to choose "Add Frameworks...") Navigate to /Library/Framework, select Inventor.framework and Sc21.framework, and click "Add". (The default settings in the dialog that comes up are fine, just accept them.)

The frameworks have now been added to your project. You might want to move them to the "Linked Frameworks" group in your project's file list, but you don't have to.

Note for Xcode 2.2 users: You will also need to modify the target settings for your project. (Project > Edit project settings > General TAB > Cross Develop using target SDK : This is by default set to "Mac OS X 10.4 (Universal)", you should change it "Current Mac OS".) - Thanks to Peter Halkmund for pointing this out.

Edit the nib file.

Open the main nib file in Interface Builder by double-clicking on the MainMenu.nib (located under Resources in the file list) file.

Verify that the Sc21 palette is installed correctly. Bring up the Palettes panel (Tools > Palettes > Show Palettes). If you do not see the Sc21 palette, you might have to add it to the toolbar (Tools > Palettes > Customize Toolbar... - then simply drag the Sc21 icon onto the toolbar).

The SC21 palette contains five elements. These are the basic model, view and controller: SCSceneGraph, SCView, and SCController; and two event handlers: SCExaminerHandler and SCCoinHandler.

Each functional SC21 application needs at least an SCView (for display), an SCController (for doing the actual rendering), and an SCSceneGraph (to specify what to render).

Drag an SCView onto the main window, and resize it to the desired size. Drag an SCController and an SCSceneGraph into the Instances frame.

Now you have to connect the outlets: To establish the connection from the view to the controller, control-click on the SCView and drag to the the controller. Choose "Connect" in the info window that pops up to set the view's controller outlet. Connect the SCController's sceneGraph outlet to the SCSceneGraph instance in the same way.

Save the Nib file and return to Project Builder. It is important that you save the nib file using key-value coding. This should be the default in current versions of Xcode, but I suggest you verify that "10.2 and later formats" is chosen in the "Save As..." dialogue:

Write the code to open files.

The only thing left now is to specify what Coin scenegraph to render. One way to do this is by loading an Inventor or VRML file, so you will now create an application controller object that will display a file open dialog when the user chooses "Open..." from the File menu, and tell the SCSceneGraph to read its data from the chosen file.

Create a new class (File - New File... - Objective-C class) called AppController.mm. Note that is important that the filename ends in .mm - not .m - so that the compiler knows that this is an Objective-C++ file.

The AppController will need one outlet that is connected to the SCSceneGraph, and one action that will be called from the "Open..." menu entry. The final AppController.h file should look like this:

#import <Cocoa/Cocoa.h>
#import <Sc21/Sc21.h>
            
@interface AppController : NSObject {
  IBOutlet SCSceneGraph * scenegraph;
}
- (IBAction)open:(id)sender;
@end

The code in AppController.mm for displaying a standard file open dialog and setting the scenegraph is fairly straightforward:

#import "AppController.h"

@implementation AppController 

- (IBAction)open:(id)sender
{
  NSOpenPanel * panel = [NSOpenPanel openPanel];
  [panel beginSheetForDirectory:nil
                           file:nil
                       types:nil
                  modalForWindow:[NSApp mainWindow]
                   modalDelegate:self
                  didEndSelector:@selector(openPanelDidEnd:returnCode:contextInfo:)
                     contextInfo:nil];
}

- (void) openPanelDidEnd:(NSOpenPanel*)panel returnCode:(int)rc contextInfo:(void *) ctx
{
  if (rc == NSOKButton) {
     [scenegraph readFromFile:[panel filename]];
     [scenegraph viewAll];
  }
}

@end

Finally, switch to Interface Builder to make the connections. In IB's MainMenu.nib project window, select the classes tab and drag the AppController.h file down into it. (Remember to save the file first.)

Right-click on AppController and select "Instantiate AppController" to instantiate the class. Make a connection from the AppController instance to the SCSceneGraph instance. Finally, connect the menu item: Right-click on the Open menu item and drag to the AppController instance. Select open: and click connect.

That's all you have to do in Interface Builder. Save MainMenu.nib and return to Xcode.

Build and run the application.

You can now build and run the application. (Choose Build and Run from the Project menu, or click the hammer icon.)

The sc21-tutorial-test application should now start. You can use File > Open to open an Inventor/VRML file - for example one of the sample models that come with Sc21.

Summary

To summarize, the steps to integrate Coin 3D rendering into a Cocoa application are:

  • Add an SCView, an SCController and an SCSceneGraph instance.
  • Connect the SCView's controller outlet and the SCController's sceneGraph outlet.
  • Load the scenegraph to be rendered, e.g. using SCSceneGraph:readFromFile.

Ready for more?

Part 2 of this tutorial shows you how to add interactivity to your scene, and teaches you the basics of the Sc21 event handling system. Take the next step...

If you have any questions, feel free to ask on the coin-discuss list (look at the mailing list for information on how to subscribe) or contact us directly at [email protected].

Clone this wiki locally