![[Images/tutorial.gif]](Images/tutorial.gif)
Introduction
Table of Contents - Index
Next: Introduction to Khoros Programming
![[bar]](Images/rule.gif)
Welcome to the Khoros Programming Tutorials. These pages aims to teach basic Khoros programming by examples, including step-by-step instructions, complete code and way too comments on the code.
I am developing these tutorials in my free time - anyone who ever tried to get a doctor's degree knows that free time is almost none. Please bear with me while these pages are still under construction.
This tutorial is divided in two parts: Programming with Khoros which will focus on the developing of kroutines, libraries and xvroutines from scratch, including all steps necessary with
craftsman ,
composer and
guise up to the source code (included in the pages). The second part is called Code Snippets and will contain only commented parts of code for specific Khoros programming tasks.
Additionally, there is an Index with links to all functions, constants and other Khoros-related commands in these pages.
If you're new in this Khoros programming stuff, I'd suggest you to start at
Introduction to Khoros Programming
- it will introduce some concepts about Khoros Programming and the components that are necessary for a program. After that, the
Program 1 - A simple kroutine to convert from a specific (simple) format to KDF
will show the basic steps in practice, from the design of the user interface to adding functionality to the code.
In the example programs that will appear here, the following conventions are used:
Proportional
is used for code and file's names. Bold face is used whenever I think you should pay more attention :-)
Inside the code,
Red
is used for comments that I will write on the code to make it easier to read, but are not C/C++ comments, meaning that if you copy the programs as they are they will generate compiler errors at these comments.
Blue
will be used for everything that the programmer should write - the color is different to differentiate what the programmer is writing from what
ghostwriter did.
Here's a simple list of stuff you'll need to develop, compile and run programs for Khoros:
- A working Khoros installation. This means that you'll probably have a compatible C compiler, tools, libraries, man pages, anything ready to use.
You should also have a valid .khoros_env file: it is usually in your root directory and it is called from the end of your .cshrc or similar file. This file contains information that is necessary for Khoros toolbox programming, such as your name, e-mail and preferred text editor. If you don't have such a file you should ask the person who installed Khoros at your site for it.
- Disk space - this shouldn't be a problem too if you already have Khoros installed (at least for the examples in this toolbox which will use just some disk space).
- Basic knowledge about Khoros, Unix and C language - I will try to answer all questions about these tutorials, but you shouldn't try to program for Khoros if you don't know some basic C, how to run programs under Unix and how to make simple tasks in Khoros, like create simple workspaces in Cantata, etc.
A little list of thinks that will come in handy:
- The Khoros Manuals. If you still have the 2.0.2 manuals, they can help too. Unfortunately these aren't available in FTP sites anymore, and now are sold by Khoral Inc. for the version 2.1. I'd suggest you to buy these manuals if you're serious about programming for Khoros. Anyway the man pages can help, and some snooping on the code could make things clearer.
- Knowledge about the
Polymorphic Data Model
and Polymorphic Data Services
- needed for the programs. You can get more information about the PDS in Khoral's Polymorphic Data Services page.
- C programming books and references.
- Coffee :-)
![[bar2]](Images/rule2.gif)
You can use this tutorial with older versions of Khoros, specifically
Khoros 2.0.2 and
Khoros 2.1 , but I strongly advise you to upgrade to
Khoros 2.2 (check the Khoral Home page for license and downloading information)
. The main differences you will notice in the older versions are:
- User interfaces are different, and not all options that are shown in the tutorial will be available in older versions.
- Parts of the code generated with
ghostwriter (called from
composer ) will be different, but since they will be written automatically, you don't need to worry about them.
Khoros 2.2 was released in July, 97 with some significant changes that will reflect in this tutorial.
This tutorial's first three programs (
Program 1 - A simple kroutine to convert from a specific (simple) format to KDF
,
Program 2 - A kroutine to process color images
and
Program 3 - A program which processes an image plane by plane
) were created with Khoros 2.1, so some differences will appear if they are recreated by the user using Khoros 2.2:
Some dialog windows for programs are changed, and have more options. The pages for the first three tutorials use the programs from version 2.1, and some differences can be noted, specially in
Composer .
The code generated by
ghostwriter is different from versions 2.1 to 2.2, but since they should be generated automatically there should be no problem for this tutoorial's users. There aren't any changes in the APIs used in this tutorial.
A new feature in version 2.2 is the automatic toolbox dependency setting - if you want to use library calls from other toolbox in the programs in your toolbox, just call
craftsman and select your toolbox.
![[Images/craftsman-toolboxselected.gif]](Images/craftsman-toolboxselected.gif)
Craftsman with a toolbox selected
Go to the menu Toolbox Operations and select Toolbox Attributes. There are several buttons on the left side of the window, select the Dependencies, the following window will appear:
![[Images/craftsman-toolboxattributes.gif]](Images/craftsman-toolboxattributes.gif)
Toolbox attributes, Dependencies pane.
Just select the toolboxes you want to make your toolbox dependent on by clicking on the Add New Dependency list and clicking the button Add Selected Dependency. The toolbox will be added to the list on the right side and Craftsman will recreate the necessary files.
![[Images/craftsman-toolboxattributes2.gif]](Images/craftsman-toolboxattributes2.gif)
Toolbox attributes, Dependencies pane after adding a dependency.
I'm writing these pages to help some new users of Khoros to include their own programs into the system. When I started learning that stuff it was quite difficult but with help of the mailing list users and the Khoral people I figured some stuff out (and still have lots to learn).
It is possible that the pages here contain some incorrect information (and probably lots of incorrect English usage). If you spot any, please be kind and send-me mail (see bottom of page).
Traditional disclaimer: There is no guarantee that the programs and code shown in these pages will solve particular problems. I cannot be hold responsible for any problems that occur while using the code shown here, or for that matter, any other problems that you may have :-)
All other standard disclaimers apply, I don't speak for them, I'm just a satisfied costumer, etc.
I'll be glad to answer questions about these pages and basic questions about Khoros programming, but before e-mailing me, please keep in mind that I cannot guarantee that I will answer all questions soon - maybe you'll have better luck e-mailing the Khoros Mailing List. The list will also be a better choice for questions about Khoros in general. Also, if you send your question to the mailing list there are more chances that other people can give relevant information and other people can benefit from the answers too - that's what a mailing list is for.
I also reserve the right to forward any question/answer about Khoros that I think that could be better answered by the mailing list users to the mailing list. I will do it when I think it is appropriate by the reasons stated above: other people can answer the questions better and other people can benefit from the answers.
If your question is about C or Unix, there are better forums for these questions. Please refer to the relevant Usenet newsgroups.
All source code included in these pages is extensively commented. If you have a question, please check the code and comments before asking me.
List of sections added to this document since the last release:
List of sections modified in this document since the last release:
Table of Contents - Index
Next: Introduction to Khoros Programming
These pages copyright ©
Rafael Santos (e-mail valid until March 1998). Please let me know if this tutorial is useful for you, I need to justify the time I used to develop it. Comments, requests and bug reports are also welcome, but please see the section
Before you e-mail me...
Khoros copyright © Khoral Research, Inc. (KRI) - run klicense for more information.
Khoral Research Inc. is not responsible for or is supervising these pages.
The latest version of this document can be found at
Ejima Lab Khoros Pages at Kyushu Institute of Technology, Japan (until March 1998).
Mirrors for this tutorial can be found at Universidade do Vale do Paraíba, Brasil and PUC/RS, Brasil.
Generated with StructHTML, 14:18 August 30, 1997