KallistiOS ##version##
Copyright (C)2002,2003 Dan Potter

RELEASE NOTES for 1.3.0
-----------------------
This tree was branched from the 1.2.x tree somewhat slightly before the 1.2.1
release, so everything in that entry applies to this one as well.

Several libc standards compliance things were fixed, so stdlib.h no longer
includes assert.h for you. This will break some code that assumes that
assert() is available when stdlib.h (or kos.h) is included.

The build system (including environ.sh) has seen some overhauling. You'll
need to build a new environ.sh from a sample again. Additionally, your
Makefile may need to change. See the examples.

The sound stream system has changed to accomidate multiple streams. Please see
kernel/arch/dreamcast/include/dc/sound/* for the new info. In particular, you
will need to call snd_stream_init from your program before using any of the
libraries like OggVorbis. Also if you are a stream user, you need to alloc
and free channels, and pass a handle along with it. See the OggVorbis libs
for an example.

The dbgio functions have changed. It now implements a full debug-friendly
console system. See include/kos/dbgio.h for more info.


RELEASE NOTES for 1.2.1
-----------------------
There is a new build system for addons/ports which is quite a bit more
automated than the old way, and is arch-centric. Now to build a new addon
you downloaded, just extract it into addons/ and it will be built for
your arch if possible.

Subsequently, most everything that was in addons/ in previous versions of
KOS is now located in its own source control tree (and will be distributed
separately).

Several incorrectly placed pieces were moved from kernel/ into their own
addon (libkosutils). If you use the bspline or kos_img_* functions, you'll
need to add -lkosutils to your link line somewhere.


RELEASE NOTES for 1.2.0
-----------------------
The PVR API's performance/statistics measuring facility has changed.
Rather than try to keep backwards compatability, the new structs have
been changed so that the names are more accurate. The main change that
will be user-noticable is that "frame_count" has become "vbl_count",
counting the number of VBlanks, which is a much more useful measurement
(so you can do constant rate animations and such).


RELEASE NOTES for 1.1.9
-----------------------
The snd_sfx_* API has changed to allow for unlimited numbers of sound
effects. The main difference is that you now use sfxhnd_t instead of int
for addressing sound effects, and the invalid return value for snd_sfx_load
failure is 0/NULL/SFXHND_INVALID and not -1.

libdcutils has been removed at this point. Everything that was in it has
been moved elsewhere or just removed in general. This includes:
  - 3dutils -- moved into kernel/arch/dreamcast/math
  - bspline -- moved into kernel/misc
  - matrix -- moved into kernel/arch/dreamcast/math
  - pcx.c -- moved into addons/libpcx
  - pcx_texture.c -- ditto
  - precompiler.c -- removed
  - pvrutils.c -- redundant, removed
  - rand.c -- removed; a different randnum() is in libc now
  - sintab.h -- removed
  - tga.c -- moved into addons/libtga
  - tga_texture.c -- ditto
  - vmu.c -- merged into kernel/arch/dreacmast/hardware/vmu/vmu.c

The GBA code base should be functional again. I've sync'd in a bunch of
changed from Gil Megidish which brings everything relatively back up to
date:
  - math.h: GBA now supported, and include/newlib-libm-arm
  - lua and lwip not compiled for GBA
  - support for romdisk and initflags for GBA
  - mockups for threading/irq for now
  - pogo-keen example

The thread scheduling system has been changed up slightly, though this
shouldn't affect most users. If you call thd_schedule or thd_add_to_runnable,
then you should probably look at the notes in kernel/thread/thread.c above
thd_schedule.

The fake "thd_enabled" has been removed completely at this point. If you
had code which checked it (it used to resolve to "1") then you should
go ahead and remove those "if" statements. The closest thing at this point
would be thd_mode == THD_MODE_COOP.

A very early port to the PS2 RTE has been added to the source tree, but
will not be released as binaries (not mature enough yet). If anyone plays
with this or has fixes, I'd very much like to hear from you.

The SYSCALL macro was _very_ broken, as in "I'm surprised it works" 
magnitude of broken. This may be responsible for some of the apparent
breakage with newer compilers.


RELEASE NOTES for 1.1.8
-----------------------
There is now a new public maple API. Please see the examples for how to
use this new API. It's pretty similar to the old API except that you call
different functions to get the info, and some of the data interpretation
has changed since the last version. Specifically, controller buttons are
no longer inverted and the joystick is centered at 0 like one would expect.

If you used to use vmu_icon_init in libdcutils, it has been replaced by
vmu_set_icon. The new one will target all attached VMUs.

The sound API (higher level one with streaming and such) now has a real
allocation system for SPU RAM. This means that, like the change earlier
in TA->PVR, you can no longer just assume that SPU RAM is free to trample
on, nor can you assume that resetting the stream driver will release your
samples. You have two options here: you can use snd_sfx_unload to unload
a single sample loaded with snd_sfx_load; or you can use snd_sfx_unload_all
to unload all loaded samples at a shot. Note that unlike previous versions,
this will not touch other samples you may have allocated (or streaming
buffers) so these must be done separately. Calling snd_init() will reset
all SPU allocation.

The sound stream API has changed quite a bit internally, but the main
external change is that the "more data" callback now returns not only a
block of data, but the amount of data.

The deprecated TA API has been removed entirely. You need to convert any
remaining code to the new PVR API or KGL. You can take a look at the 
examples to see how this works, but here is a quick rundown:
   - poly_hdr_t becomes pvr_poly_hdr_t
   - ta_poly_hdr_txr becomes pvr_poly_cxt_txr
   - ta_poly_hdr_col becomes pvr_poly_cxt_col
   - pvr_poly_compile must be called to generate the actual pvr_poly_hdr_t
   - ta_commit_vertex and ta_commit_poly_hdr become pvr_prim
   - TA_VERTEX_NORMAL becomes PVR_CMD_VERTEX
   - TA_VERETX_EOL becomes PVR_CMD_VERTEX_EOL
   - TA_ARGB4444 (and others) become PVR_TXRFMT_ARGB4444 or whatnot
   - TA_NO_FILTER becomes PVR_FILTER_NONE
   - TA_BILINEAER_FILTER becomes PVR_FILTER_BILINEAR
   - TA_OPAQUE becomes PVR_LIST_OP_POLY
   - TA_TRANSLUCENT becomes PVR_LIST_TR_POLY
   - "uint32 texture" becomes "pvr_ptr_t texture"
   - ta_txr_allocate becomes pvr_mem_malloc
   - Textures must be freed with pvr_mem_free
...and so forth. Most of the API changes are cosmetic, but it's important
to pay attention and make sure you understand the shifts in paradigm where
appropriate as well (such as raw texture space to managed, allocated
texture space; commit_eol gives way to real lists; etc).

The "scene idiom" has also changed to the following:
  pvr_wait_ready();
  pvr_scene_begin();
  pvr_list_begin(PVR_LIST_OP_POLY)
    /* Do your opaque rendering */
  pvr_list_finish();
  pvr_list_begin(PVR_LIST_TR_POLY)
    /* Do your translucent rendering */
  pvr_list_finish();
  pvr_scene_finish();

Deprecated kos_init_all and kos_shutdown_all have been removed.

Deprecated compat macros like ALL_ENABLE have been removed.


RELEASE NOTES for 1.1.7
-----------------------
KOS 1.1.7 is probably one of the biggest, nastiest upgrades KOS has seen
since the 1.0.x -> 1.1.x transition. Unlike that transition =) this one
brings many fixes and helpful features. Most things will continue working
just fine, but specific issues are listed below. Please check through
this if you have problems.

Initialization has changed somewhat. Now instead of calling kos_init_all(),
you will need to use one or more of the KOS_INIT_* macros in
arch/arch.h. These include KOS_INIT_FLAGS and KOS_INIT_ROMDISK. Note that
there are new names for the flags to OR together, also. Please check
kernel/arch/dreamcast/include/arch.h for more info, and/or see the
examples.

Threading is also different now. Threading is now always enabled. Now
before you groan and moan at me, there are now two modes of threading
instead of just enable/disable: cooperative and pre-emptive. In
cooperative threading mode, the thread module is active and it is
possible to do things like thd_pass(), use condition variables
between the main program and an IRQ, etc. However, the timer is not
hooked and no pre-emption will occur. If you enable pre-emptive
mode, then this is basically like the old threads-enabled mode.

Note that kos_init_defaults() is now a compatability shim which will
correct any implicit defaults. However, if you want better control over
this situation, please change your program to use the macros. Also note
that this and other compatability shims will be removed by the next
release version (i.e., removed in CVS after the tagging).

The build process has changed slightly. The main change is that libc is
in its own tree, and thus has its own include path. If you are using the
KOS Makefile templates, then you should use $(KOS_LIBS) at the end of your
link line (use this in place of -lkallisti -lgcc). You must also add
-I$(KOS_BASE)/libc/include to your CC line if you're using your own
custom Makefiles.

A couple of things have changed in the environ file, though nothing
drastic. Your existing environ should still work, but I recommend at
least adding the KOS_STRIP variable, as well as adding the
-fno-optimize-sibling-calls parameter to KOS_CFLAGS if you haven't built
a fixed GCC 3.0.3.

Libc has been split out of 'kernel' and into its own tree. This is what
triggered the build process change. In the future this will make it very
easy to replace libc with another libc (such as Newlib). Note that libc
is ported to KOS, not the other way around. This is why the libc objects
are still combined into libkallisti.a (easier linking until we have the
installation mode available...)

Libm from Newlib has been integrated into the source tree so that you
no longer have to pull in a seperate Newlib binary. This also ensures that
it's compiled with the same compiler flags as the rest of KOS.

The new "PVR" API has completely replaced the old "TA" API. For the near
future, code based on the "TA" API will continue working, through an
adaptation layer. The one thing which really can't be emulated properly
with the adaptation layer is custom memory management (i.e., allocating
your own textures starting at texture address 0). "PVR" texture pointers
are now real SH-4 pointers, so you must allocate them through the 3D
subsystem or you'll get garbage for textures.

The streaming and basic sound effects portions of the MP3 and OGG libraries
has been split out and placed into the kernel now, as an architecture
independent interface. The DC implementation uses a generic AICA driver
which has been improved upon greatly since the last version. This has three
implications for anyone using sound stuff:

1) If you used sfx_* functions, you must now use snd_sfx_*
2) It is now possible to use basic sound effects without loading the MP3
   or OGG libraries
3) You no longer need to include stream.drv in a romdisk; it's built into
   the library itself now

The entire maple system has been replaced. Most things will still work
as before, but one of the most notable changes is that you will no longer
need to pause between polls on the maple bus. This is all handled
automatically in the background. Enumeration is done by using the
maple_enum_* functions (see dc/maple.h) and the way to access the
keyboard matrix and shift states is different also (see dc/maple/keyboard.h).
VMU saving should be considered somewhat "beta" as is the hotswap
capability. We're still working on finding and fixing issues there,
especially with third-party peripherals.

One consequence of this change which you should pay attention to for your
own programs is that maple_first_controller() and friends might conceivably
fail at one point during your program, yet succeed later. So you'll want
to poll for the devices you want before each condition check rather than
when the program starts. For the most part, the examples have been
updated to do this.

KGL has become a lot more OpenGL(tm) compliant. This means, for example,
that the usage of radians has been deprecated in favor of degrees, 
images are expected to be loaded inverted, etc. If you program which
previously worked under KGL is having some issues, you should probably
check to see what changed there. Paul has helpfully created a KGL manual
as well, if you are looking for docs.

Image loaders now use the kos_img_t system so that they can be platform
independent and still pass around the data in a convienent format. This
also makes it easier to flip the data when loading it into the PVR RAM
for KGL usage. The loaders for PCX and TGA have additionally been split
out into their own libraries (libpcx, libtga). So you will need to
use -ltga or -lpcx for these in your link line.

Finally, if you do not have a working G++ compiler for your target, then
please comment out the line in environ for KOS_CCPLUS. This will disable
building any C++ targets. Conversely, if you have a working G++, make sure
you have a KOS_CCPLUS line so that all of the libraries and examples will
get built.


KOS Version Id: $Id: RELNOTES,v 1.20 2003/05/23 03:08:00 bardtx Exp $

