# $Id: RELEASENOTES,v 1.22 2008/11/24 16:55:17 wes Exp $
# Version: $Name: v180-alpha-02 $
# $Revision: 1.22 $


November 24, 2008 (1.8.0-alpha)
----------------------------

Both OpenRM and RM Scene Graph


RM Scene Graph only



--------------------------------------
New Features and API Changes in v1.8.0
--------------------------------------

1. RMaux Button Callback API Changes
- rmauxSetButtonDownFunc changed to rmauxSetButtonDownCallbackFunc
- rmauxSetButtonMotionFunc changed to rmauxSetButtonMotionCallbackFunc
- rmauxSetButtonUpFunc changed to rmauxSetButtonUpCallbackFunc
- all three have a new input parm void *usrData
- call button callbacks have new parm list: pipe *, node *, usrData *, xb, yb

2. RMaux Idle callback API changes
- rmauxSetIdleFunc now rmauxSetIdleCallbackFunc. New API 
has: RMpipe *, RMnode *, void *usrData, int pointerX, int pointerY.
RMdemo dyntmap.c exercises passing an int * through the void *usrData
parm in the idle callback func parm.

3. RMaux Keypress callback API changes.
rmauxSetKeyFunc now rmauxSetKeypressCallbackFunc. New API has:
RMpipe *, RMnode *, void *usrData, char key, KeySym code.
RMdemo psTest1 exercises passing a filename through the void *usrData 
to the keypress callback.

4. RMaux Init callback API changes
rmauxSetInitFunc now rmauxSetInitCallbackFunc. The user callback function
is now provided an RMpipe *, RMnode * and a void *usrData.

5. RMaux render function callback API changes
rmauxSetRenderFunc now rmauxSetRenderCallbackFunc. The user callback
is now provide a RMpipe *, RMnode *, and void *usrData. Also, this callback
must now return an integer: a zero means terminate the event loop, a 
one means continue event loop processing.

6. Added rmPipeGetWindowHeight() and rmPipeGetWindowWidth() calls.

7. rmSubtreeDelete now takes an additional RMenum/bool argument. When
set to RM_TRUE, the root node passed to rmSubtreeDelete will be deleted
along with all its children. When set to RM_FALSE, only the children
will be deleted.

8. Support for really large data. Uses size_t for mallocs in assigning
primitive blobs (vertices, normals, colors, etc.), making it possible to have
>32bits of stuff in a blob. The rmPrimitiveSet*() family of routines,
as well as internal support routines, now take size_t's rather than
ints as parameters for specifying the number of things (vertices, etc.)

9. Support for Mingw (Thanks to David K). There is a new mingw32-dynamic
build target in $RM/make.cfg. 

10. Scene Graph synchronization. Added a family of algorithms to permit
multithreaded scene graph updates. At present (9/2008), only node and
primitive client data updates are supported. Also at present (9/2008),
there is little documentation for this new capability, and no RMdemo
programs (the new capability was developed for a HPC vis project as
a research prototype). All existing RM/OpenRM programs will function
just fine w/no API changes, etc. Future releases will contain better
documentation and demo program(s) that exercise/demonstrate this
functionality.

11. Added rmNodeRemoveIthChild() call.

12. RMnode children management: no longer uses a realloc each time you
add a child node. Instead, the RMnode uses the RMarray to hold children
pointers. Reallocs still happen, but less frequently as the RMarray uses
a chunking realloc strategy. The chunk size is set via a compile-time
constant.  Additionally, rmSubTreeDelete was optimized for
better performance. A benchmark shows the following performance
improvement:
Action			Old (ms)	New (ms)
Add 20000 nodes		16.34		15.31
Delete 20000 nodes	3769.10		10.92

RMV updates:
1. Added new version of isocontouring routine 
rmvK3MarchingCubesVertsNormals. This one will return the triangle 
verts/normals as well as generating an RMnode containing the isosurface.

New RMDEMOs:
- psTest1.
- cbUsrDataTest.c -- to exercise passing user data via the RMaux callback
functions.
- addChildTest.c -- benchmark for measuring performance of scene graph
topology updates (rmNodeAddChild, rmSubTreeDelete).

New Gordo application:
- stereoModes
- isoTest


Bugs Fixed in 1.8.0-alpha
-------------------------

1. (RM only) Postscript output bug. RMpipe-level background clears not 
showing up in PS output. Previous code looked only at node-level fbclears.

2. rmPrintSceneGraph reporting bogus linestyle values.

3. in make.cfg, fixed some of the GLINC lines that needed a space
between the closing quotation mark and the backslash.

4. RMarray routines -- changed int counts in parm lists with size_t's
to support >2GB array elements.

5. rmNodeSetUnlitColor now changes both DIFFUSE and AMBIENT terms.
Formerly, it set just DIFFUSE with glMaterialfv. The result of the
change is that the appearance of objects will be the same if using
per-vertex color or per-object color. The per-vertex color uses
glColorMaterial where both ambient/diffuse color material is set.

6. Added code in rmxtext.c to try and XOpenDisplay(getenv($DISPLAY)) when
the app hasn't set the X display in the RMpipe. An open X display is
needed when preparing bitmap fonts for display on X-based systems.
This will save some initialization steps for some applications.

7. RMstate initialization is "standardized" across different frame
rendering code so that default values/behavior are consistent.

8. changes to rm/rmerror.c/private_rmW32Error() to replace errno with 
my_errno due to compilation problems under MinGW


Known Bugs
----------

(Many of these are leftover from 1.6.0-2)

1. It is possible to overflow texture memory by using a texture that
doesn't fit into memory. This condition will silently produce an error.
The tfly.c demo has some sample code showing how to work around this
problem from the application's perspective.

2. There is no graceful way to release OpenGL texture resources. Texture
resources are properly released only in a limited set of circumstances.

3. Constant-rate rendering issues with nvidia drivers on some platforms.
We have seen problems with constant rate rendering on these platforms:
- Windows+nVidia drivers.
- Linux SuSE+nVidia drivers.

4. Bitmap primitives need their raster position updated a la the sprite
primitives to be properly clipped with positioned off the left or bottom
side of the display window.

ToDo - 1.8.0 (between alpha and final)
--------------------------------------

1. Renderfunc callback. Issue: the docs say that the return value
from the render callback will cause rmauxEventLoop to continue 
(when the rval >= 1) or stop (rval <= 0).

The X11 rmauxEventLoop seems to honor this convention, though 
there are render function invocations inside button action 
handlers -- the render callback can return a zero, but the button action 
handler will return a 1 even if the enclosed render callback returns a 
zero.

Need to overhaul the Win32 event loop code to do a better job of
dealing with loop termination conditions. The code that is there is
is old and crufty.

2. Win32. 1.8.0 has *not* been compiled/tested on Win32 systems.

3. make docs produces some odd results.

4. pick buffer isn't big enough to accommodate the fact that nodes/prims
may appear in up to three rendering passes.


ToDo - Longer Term
------------------

- Add code to check the maximum texture size for each of 1D, 2D and
3D textures, and at texture download time, detect and report if an 
application texture would exceed those size limits. An early version of
such code was added to the RMdemo app tfly.c.

- Add means to better manage texture memory, including garbage collection.

- cleanse API for easier error detection. E.g., rmVismapGetAlpha returns
a float value even if there's an error. It would be better to unify the
return values from routines so that all return RM_CHILL on success or
RM_WHACKED on failure.

- change or augment API on loader functions to use a fd rather than a 
filename (thanks to D. Bunzli for the excellent suggestion)

- Fix problem where window resize in tfly doesn't propogate new window
dims to the static fly struct inside rmauxFlyUI. One approach is to create
a new rmauxFlyResize function that fixes the camera and the cached
window geometry dims.

- GLUT+RM demonstration programs and chapter in the RM Programming Guide.

- Implement transformations to the multitexture matrix stack.
- Update RMstate to reflect state of multitexturing.

- Cg/GLSL. This should be quite straightforward now that OpenRM knows about
OpenGL extensions.

- Adjust default timer under windows to be something faster than 20ms
so that idle callbacks happen more quickly.

- Add support for multitexturing to more primitives. Current list
in 1.6.0 is RM_QUADMESH, RM_QUADS, RM_TRIANGLES, RM_TRIANGLE_STRIP.

- Some primitives use the new private_rmSetGLTexCoordFunc to assign
the correct (1d, 2d or 3d) glTexcoord function. Primitives
known to work with 1D texturing: RM_LINES, RM_LINE_STRIP.

Primitives that should work:
RM_POINTS, RM_TRIANGLES_DISJOINT, RM_TRIANGLE_STRIP, RM_TRIANGLE_FAN,
RM_QUAD_STRIP, RM_POLYS, RM_QUADMESH, RM_INDEXED_TFAN,
RM_INDEXED_QUADS, RM_INDEXED_TRIANGLES, RM_INDEXED_QUAD_STRIP,
RM_INDEXED_TRIANGLE_STRIP, RM_QUADS

Primitives that probably won't work:
none known to not work.

Primitives that don't and probably won't support texturing: RM_SPHERES,
RM_CONES, RM_CYLINDERS, RM_MARKERS2D, RM_BOX3D, RM_BOX3D_WIRE,
RM_CIRCLE2D, RM_BOX2D, RM_ELLIPSE2D, RM_SPRITE, RM_BITMAP, RM_TEXT,
RM_INDEXED_TEXT.

- Need to add to RM_QUAD_STRIP code to detect and do something with
per-face data. Right now, it just assumes per-vertex everything.

- Quadrics primitives that have texture coordinates (suggestion from
T. Rightnour). 

- Fix RM_INDEXED_BITMAP (currently empty)

- Hardware accelerated offscreen formats (pbuffers).

- OSmesa RMpipe target for truly device independent offscreen rendering.

- RMdemo vis3d/vis2d: compute "shrink factor" for glyph-based vis tools
to be based upon the input grid spacing. Presently, values are hard-coded
to produce visually pleasing results when the "default data sets" are
used.

- VisualC/.net workspaces for openrm-demo, openrm-gordo.
- .net workspace for openrm-devel.
- Standalone implementation of threading and semaphore routines for Windows
(to produce a more flexible development environment outside of pthreads-win32).

--EOF--
