readme.txt
April 28, 1998

This document contains late-breaking and important
information about this Katana development
software.  Please take a moment to read it.

1. Purpose
----------

This release of development software is intended
to allow developers an early preview of the API
functionality in Katana.  The current development
system differs significantly from the final Katana
system, and the performance of this system is
below that of the final system.  In addition,
several significant bugs exist in this development
environment for which no workarounds are currently
known.

Despite these limitations, we feel that developers
can begin the title development process with this
early hardware and software.  Sega has
successfully written, compiled and tested software
with this development environment, and we believe
that it can be useful to you.

2. Other important files
------------------------

\legal.txt: Legal information and disclaimer
            associated with this development
            software.

\contents.txt: A directory of software and
               documentation included in this
               release.

\readme.txt: This file.

\install.txt: Information on installing the
              development hardware and software.
              After reading this file
              (readme.txt), most developers should
              refer to install.txt and follow the
              instructions therein.

3. Confirmed bugs, problems, behaviors, and
limited functionality
-------------------------------------------

- Source-level debugging crashes target

Applications compiled with Kamui or Ninja
interfaces occasionally crash the target
development system while single-stepping through
source code.  We suggest working around this
problem by using simple debugging output routines,
such as printf() when working with Kamui, or
OutputDebugString() when working with Ninja.

- scud demo crashes on fast host machines

The scud demo, which is in the \lib\ninja\demo
folder, may sometimes crash when run on PCs that
run at 300 MHz or higher.  This crash tends to
occur if the demo runs at a very high frame rate.

This problem may be worked around by installing
the previous versions of the Kamui drivers to run
the scud demo.  For this reason, the older Kamui
drivers are available in the folder
\lib\kamui\drv\previous.

You should not install the previous versions of
the Kamui drivers unless you experience this
problem.  Two of the newer Kamui demo programs --
QTDirect and cubes -- use functionality that does
not exist in this newer driver.  It is necessary
to use the driver at \lib\kamui\drv to run these
demos.

- Driver update process is confusing

When changing or reinstalling drivers, follow the
process in install.txt carefully to avoid mixing
components of driver versions.

- Ninja models, if not regenerated, appear as
  black objects

In the previous release of Ninja, attribute flags
from modeling export utilities were automatically
overridden by Ninja with a default, simple
blending mode.  However, in this version Ninja no
longer overrides the blending mode for Ninja
models.  Any AttrFlags settings in the Ninja
models are now exact.

However, previous versions of model converters
assumed that this override would take place, and
did not set the AttrFlags for exported models
directly.  Previous versions of the Map, Teapot,
and Torus demos exhibit this behavior.

There are two possible workarounds.  Existing
Ninja models may either be re-exported using the
new exporters, or .NJA files may be manually
edited, and each AttrFlags value therein should be
logically ORed with 0x94000000.

- Triangles in busy tiles clamp to white

Occasionally you may see individual triangles
rendered as white surfaces.  This bug tends to be
seen in cases where a large number of triangles
are embedded within a single PowerVR tile (32x16
screen pixels).

Please let us know if you have a specific case
that generates this behavior repeatably.

- Specular highlights do not work correctly in
  some Ninja demos

Two Ninja sample programs, Teapot and Motlink, do
not correctly demonstrate specular highlights
under Ninja.  (Specular highlights can be
implemented in software via the Kamui interface,
however.)

- Visual C++ projects require library path to be
  changed

Because the os\ directory was renamed to lib\ in
this release, any Visual C++ projects that refer
to any paths in the os\ directory may need to be
modified.  For example, if you link directly to
the ninja.lib and kamui.lib libraries in Visual
C++, use the Options... command on the Tools menu
and select the Directories tab.  Then, modify the
Includes and Libraries directories, respectively:

\LIB\KAMUI\INCLUDE
\LIB\NINJA\INCLUDE
\LIB\KAMUI\LIB
\LIB\NINJA\LIB

- Lightwave art converter crashes on very large
  models

If a model with more than 32,768 vertices is 
converted with the LWToNJ.exe tool, the converter
will crash.  Ninja cannot handle a single model
with more than 32,768 vertices.  Break the model
into smaller subcomponents before converting.
 
- Art tools are untested

The 3D model conversion utilities in this release
have not been tested.  This includes the
Lightwave, 3D Studio Max R2, Softimage, and Alias
conversion utilities.  Crashes have been observed
with the 3D Studio Max R2 and Lightwave
converters.

- Copying the contents of the CD sets the
  read-only attribute

Example programs in this release will not compile
if the contents of the development CD are copied
manually to a hard drive.  Windows sets the
read-only bit on files copied manually from CD
media.  If you want to install the software
manually, see install.txt for a workaround.

- Demos are unstable without Kamui driver

Some Kamui demos can run without having the Kamui
driver installed on the target system.  These
demos may crash more frequently.  Follow the
instructions in install.txt to install the most
recent Kamui driver.

- Kamui example programs require documentation and
  utilities

If you intend to do full builds of the Kamui
sample programs, make sure to install the Katana
development system utilities as well.  The Kamui
makefiles require the art conversion tools in
order to generate PowerVR textures from Windows
.BMP format bitmaps.

- No SH4, CD, or sound support

The heart of this early development hardware is
the PowerVR ARC1 graphics chip, which is the early
version of Katana's CLX1 chip.  CLX1 will be used
in the final version of Katana.  The final version
of Katana will comprise a Hitachi SH-4 CPU, a
Yamaha CD-ROM drive, and AICA sound hardware by
Yamaha.  Neither these items nor their emulation
is available in this development system.

- No encryption

Katana titles may not be encrypted, duplicated or
distributed using this version of development
software or hardware.

- woman.nja has seaming problems

The converted Alias model, woman.nja, shows some
artifacts when viewed using the NjViewer tool.

- PVRConv.exe outpath parameter does not work as
  on-line help states

The PVRConv on-line help says that a third
parameter can be used as an output file path.  In
fact, the -p option on the command line is used to
describe the output path of processed textures:

  PVRCONV.EXE -4 -p MYDIR MYPIC.BMP ALPHA.BMP

4. Changes
----------

4a. Kamui

- Kamui now supports the kmDirect series of
  function calls.  These functions allow an
  application to send data directly to the tile
  accelerator without an intermediate buffering
  step in system memory to accumulate like types
  of vertices.  The kmDirect series of functions
  include the following:

  kmSetUserClippingDirect()
  kmStartVertexStripDirect()
  kmSetVertexDirect()
  kmSetEndOfListDirect()
  kmRenderDirect()
  kmRenderTextureDirect()

- The Kamui driver now supports pixel-level
  antialiasing and dithering.  This can
  appreciably improve the quality of output of
  NTSC images.  (VGA images usually suffer
  somewhat if antialiasing is enabled.)  To enable
  antialiasing and dithering, make the following
  changes to the KAMUI.INI file, which is
  installed into your \WINDOWS directory when the
  Kamui driver is installed:

   AntiAlias=1
   Dither=1

- Several new sample programs were added into the
  \lib\kamui\samples folder.  These include Cubes,
  QTDirect, and QuikTest.  Both the Cubes and
  QTDirect samples demonstrate the new kmDirect
  functionality.

- The make process of all Kamui examples was
  modified to build PowerVR textures from .BMP
  sources as part of the make process.  In order
  to build the sample Kamui art from sources, do a
  "make clean" and then a "make".

- The internal driver architecture for Kamui
  running on the PC host has changed.  When a
  Kamui program runs, a servlet application
  (kmsrv.exe) orchestrates Kamui access to the Set
  2.1 video card and prevents two Kamui
  applications from running at the same time.

4b. Ninja

- The following functions were added to Ninja.
  These functions support object animation,
  PowerVR modifier volumes, culling modes, and
  some debugging support:

   njActionLink();
   njAlphaMode();
   njColorBlendingMode();
   njDrawMotionLink();
   njDrawShapeMotion();
   njDrawShapeMotionLink();
   njFastAction();
   njFastActionLink();
   njFastDrawMotion();
   njFastDrawMotionLink();
   njFastDrawMotionLink();
   njFastDrawShapeMotion();
   njFastDrawShapeMotionLink();
   njFrameBufferBmp();
   njGetMotionRotate();
   njGetMotionScale();
   njGetMotionTranslate();
   njIgnoreTextureAlphaMode();
   njInitShape();
   njModifierVolumeMode();
   njMotionRotateXYZ();
   njMotionRotateZXY();
   njMotionScale();
   njMotionTransform();
   njMotionTransformZXY();
   njMotionTranslate();
   njPolygonCullingMode();
   njPolygonCullingSize();
   njPrintSize(Uint16 size);
   njSetCurrentMotion();
   njSetLightAlpha();
   njSetNextMotionNode();
   njSetRenderWidth(Uint32 nWidth);
   njSetSimpleLight();
   njSimpleAction();
   njSimpleActionLink();
   njSimpleDrawModel();
   njSimpleDrawMotion();
   njSimpleDrawObject();
   njSimpleDrawShapeMotion();
   njSimpleDrawShapeMotionLink();
   njSpecularMode();
   njTextureShadingMode();

- Collision testing via bounding-box support was
  added to Ninja:

   njCollisionCheckBB();
   njCollisionCheckSS();
   njCollisionCheckCC();
   njCollisionCheckSC();
   njCollisionCheckBS();
   njCollisionCheckBC();

- The following function was added to Nindows:

   nwGetFontSize();

- The following functions have been removed from
  Ninja and are not supported in this release:

   njChromakeyEnable();
   njChromakeyDisable();
   njSetChromakeyColor();

- For more information on these new Ninja
  functions, see the on-line documentation.

- Two new Ninja sample programs, Motlink and
  Shape, have been added.

4c. Art tools

- NjViewer tool now supports loading and viewing
  Ninja animation (.NAM) files in conjunction with
  their corresponding .NJA model files.
  Previously, loading a .NAM file crashed
  NjViewer.

- A vector quantization compression tool, VQ.EXE,
  has been added.  This is a command-line tool for
  compressing textures into the PowerVR format.

- In the previous release, the PVRConv.exe utility
  shifted the alpha channel to the right by 4 to 8
  pixels for textures of type 4444.  This has been
  fixed.

- Initial support for automated strip format
  conversion has been added.  In the future, this
  will allow models exported through the Ninja
  conversion utilities to be rendered more
  efficiently.

- The koke model no longer crashes NjViewer.

- Numerous new art examples for use with NjViewer
  have been added.

- Support for 3D Studio Max for versions before R2
  has been omitted from this release.  Please
  contact us if that's a problem.

4d. Documentation

- The Adobe Acrobat Reader with Search tool,
  version 3.01, is copied to your hard drive if
  you select Documentation as an installation
  option.  It's necessary to run the installation
  program first (RS32E301.EXE) in order to view
  the online documentation in .PDF format.  This
  documentation has been extensively
  cross-indexed, and you can now search across the
  contents of all the documentation with Acrobat
  Reader.  Search indices exist at \doc\pdf\Search
  Modules.

- Kamui documentation has been updated, and a new
  incremental update to Ninja function
  documentation was added.  Documentation was also
  added for most of the 3D file format plugins and
  conversion utilities.

5. Support options
------------------

We look forward to hearing about problems or
questions that you have regarding Katana
development.  Here's how you can get help or
contact us:

- Printed and on-line documentation

Check the \doc folder for on-line versions of the
manuals.

- Electronic mail

Developers in the United States and developers
working with Sega of America should send e-mail to
dts@sega.com .  Developers in the United Kingdom
and developers working with Sega of Europe should
send e-mail to edts@soepd.sega.co.uk .

Your e-mail will be routed to the appropriate
engineer, and you can then communicate directly
with that engineer.

- DTS Web site

We maintain a private Web site at
http://www.dts.sega.com/NextGen that contains
current development software, frequently asked
questions, and message-based discussion forums.
We host regular technical chats via a Web-based
interface on a variety of Katana topics.  To be
granted access to the Web site, send e-mail from
your corporate e-mail address to dts@sega.com.
You will be voice-validated for access to the
Web site.

- Listserver

Sega provides an active electronic mail listserver
dedicated to Katana game development.  This
listserver allows you to send mail to Sega
internal and third-party Katana developers.  This
listserver operates 24 hours a day.  To join the
listserver, send e-mail from your corporate e-mail
address to elite-listserv@sega.com with the word
"subscribe" in the body of the message.  You will
be voice-validated for access to the listserver.

- Telephone

In the US, Sega of America's Developer Technical
Support department may be contacted at (650)
802-1719, 10:00 am to 6:00 pm, Monday through
Friday.  In Europe, Sega of Europe's Developer
Technical Support may be contacted at +(44) (1)
181-996-4421.










