# $Id: RELEASENOTES,v 1.20 2005/09/12 04:13:45 wes Exp $
# Version: $Name: OpenRM-1-6-0-2-RC2 $
# $Revision: 1.20 $


September 11, 2005 (1.6.0-2)
----------------------------

Maintenance release - lots of small documentation updates to ensure
consistency between the 1.6.0 Programming Guide and the inline documentation.

Bugs Fixed:
1. Constant-rate rendering on Windows. The previously identified bug whose
symptoms were a regular "hiccup" in frame delivery rate has been located
and repaired.



July 24, 2005 (1.6.0)
-----------------------------

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

1. Added support for multitexturing.
- Prims supported: RM_QUADS, RM_QUADMESH, RM_TRIANGLES, RM_TRIANGLE_STRIP,
	RM_INDEXED_TRIANGLES (more will be added in future releases).
- New API routines support assigning multitexture coordinates to
	RMprimitives: rmPrimitiveSetMultiTexcoord[1D, 2D, 3D].
- New API routines support assigning multiple textures to an RMnode:
	rmNodeSetSceneMultiTexture. There is also a corresponding get routine.
- New API routine so applications can query multitexturing capabilities
	of the OpenGL implementation: rmPipeGetNumMultitextureUnits() tells
	how many texturing units are supported.
- New rmdemo program that exercises multitexturing: multiTexture2D.


2. Added support for hardware-accelerated 3D texturing (volume rendering) 
on Windows.

3. Added support for 1D Textures. Tested with RM_LINES and RM_LINE_STRIP
primitives.  Use rmPrimitiveSetTexcoord1D to assign data. New RMdemo
program "strands" exercises 1D texturing.

4. Added support for normals on line segment primitives. New RMdemo program
strands exercises normals/lighting on RM_LINES and RM_LINE_STRIP
primitives.

5. Added support for textured points. The pntcld RMdemo updated to
exercise the new capability. Try running with these command line
arguments: pntcld -n 10000 -p 4 -tc

6. Added support for application-defined texture objects. These may
come from 3rd party modeling tools, like Cal3d. Create the rmTexture
as normal, but instead of assigning RMimage texel data, assign the
3rd party texture ID using rmTextureSetTextureID, then assign the 
RMtexture as a scene parameter to an RMnode as usual. The get routine
is rmTextureGetTextureID. A new RMdemo program appTexturedPrims
exercises this feature.

7. Added support for application-defined display lists. These may come
from 3rd party modeling tools like Cal3d. To use them, create an
RMprimitive of type RM_APP_DISPLAYLIST. Instead of assigning vertex,
normal, etc. data, just assign the 3rd party display list using
the new routine rmPrimitiveSetAppDisplayList. A new RMdemo program
appTexturedPrims exercises this feature.

8. Added ability to specify background clears at the RMpipe level.
The old way of doing background clears - at the RMnode level - is still
in the code base. If you only clear the framebuffer once per frame, 
then you'll want to migrate to use the RMpipe-level clears. OTOH,
if you do multiple clears per frame, like if you use inset viewports,
then you'll still need to use the RMnode-level clears for your 
viewports. Several new RMpipe-level routines support this capability,
and they parallel the previous RMnode level routines:
rmNodeSetSceneBackgroundColor, rmPipeSetSceneBackgroundImage,
rmPipeSetSceneDepthImage, rmPipeSetSceneDepthValue (and the
corresponding get routines).

9. Updated RM_QUADS primitive to accommodate per-face colors, normals, etc.
When optional data items (colors, normals) are specified per-vertex,
then we use vertex arrays. Otherwise, we use a slower path through
OpenGL.

10. Deprecated and removed from API: rmPipeGetCurrent, rmPipeInit.

11. rmPrintSceneGraph() updates:
  - Added more detailed output from rmPrintSceneGraph for RMprims -
  output now includes counts of colors/normals in addition to
  count of number of verts. 
  - Fog scene parameters are displayed, if present.
  - Update to include proper titling for all current RMprimitives.

12. Added new build targets (thanks to Tim Rightnour):  netbsd, netbsd-debug, 
netbsd-pkgsrc arch-specific stuff in make.cfg, and same build targets in 
Makefile.

13. Added new RMpipe species to use with rmPipeNew: RM_PIPE_NOPLATFORM.
The "no platform" target skips assigning several platform-specific
internal callbacks (create context, swapbuffers function). Applications
that use 3rd party tools for creating and managing the OpenGL
context (e.g., the Fast Light Toolkit, gtkglarea, etc.) will want to
use the new RM_PIPE_NOPLATFORM species as initialization code can
be streamlined. See the OpenRM "Gordo" project for example code
(Gordo is a bunch of example applications that show how to combined
FLTK and OpenRM).

14. Streamlined condition checks inside rmPipeMakeCurrent. 
Added more stringent checking inside rmPipeMakeCurrent (the X11 code)
so that you must have all of (1) a valid display, (2) a valid window and
(3) a valid context assigned to the RMpipe before glXMakeCurrent
will be called. 

15. RMaux updates. Modified rmauxArcBall, rmauxDolly, rmauxTranslate 
to perform more thorough error checking upon entry.

16. New RMnode flags for the pick traversal. Use rmNodeSetPickEnable()
to schedule a node for processing during a pick traversal (rmFramePick,
rmFramePickList). Use rmNodeGetPickEnable to obtain the pick traversal
mask value. By default, RMnodes are created with the pick traversal
mask enabled. This mask is processed only during the pick traversal.

17. New MSVC workspace. New "visualc" directory contains a Microsoft 
Visual C++ workspace that can be used to build debug and/or release 
versions of openrm-devel. Corresponding with this addition, we also included 
source for the JPEG library for the benefit of Windows users and developers.

18. Removed linestyle and linewidth enumerators from the rmvI3VectorCodes
routine. It generates surface triangles only, so linewidth/style enumerators
were not needed.

19. Removed the deprecated routines rmvLOD1MeshReducer() and
rmvLOD2MeshReducer from the API.

20. Added rmSetEnum/rmGetEnum to set/get defaults. In 1.6.0, the two
valid set/get targets are RM_DEFAULT_NODE_PICK_TRAVERSAL_MASK and
RM_DEFAULT_NODE_TRAVERSAL_MASK. These flags may be used to alter the
default traversal mask values assigned to RMnodes by rmNodeNew.

21. fogtest and tfly demonstration programs:
  - Now use reasonably detailed quadmesh primitives to result in better
	visual fidelity: formerly, large and skinny triangles produced odd
	lighting effects in some view positions.

22. Tfly demo program:
  - Now has some experimental code showing how to use OpenGL texture
	proxies to check if a given texture will fit into memory. If the
	texture doesn't fit, make repeated calls to rmImageResize to shrink
	the image until it does fit. This code will be migrated into the
	RM code base in 1.6.1, and support 1D, 2D and 3D textures.
  - Added key handler in tfly: press "w" to toggle wireframe display, and
	'f' to return to filled-polygon display mode.

New RMDEMOs:
- appTexturedPrims - exercise 3rd party display lists and texture IDs.
- autoTmap - exercise OpenGL automatic texture coordinate generation
	with OpenRM spheres.
- extensions - obtain and display extensions supported by OpenGL.
- multiTexture2D - exercises multitexturing on several different types
  of RMprimitives.
- strands - exercises 1d texturing and lit, shaded line segments.
- vrend & vslicer now operational on windows!
- pntcld updated to do textured points.

Bugs Fixed in v1.6.0
--------------------

1. Many small OpenGL state tracking problems repaired. 
   - Lighting state tracking. Problems with RMstateCache not having its 
lightingActive attribute updated to reflect changes from lights off to 
lights on.  Fixed by adding some update code to process_scene_lights().
   - Consolidated opcode to capture both local state push/pop and OpenGL
attrib stack push/pop. This move helps streamline state tracking and
makes it possible to better track OpenGL state.

2. Repaired several memory leaks.
   - Modified rmPipeClose to zero out variables that are freed during
a pipe close operation (contextCache, displayLists). That way, you
can call rmPipeClose more than once on an RMpipe and not get an error.
This bug was turned up by an application that first called rmPipeClose
followed by rmPipeDelete, which is a valid sequence.

3. Fixed buglet present in several RMprimitives whereby prims with 0 verts 
would  cause their draw code to return early, resulting in an incomplete
OpenGL display list. In turn, that produced a domino effect of errors
that was visible as a corrupted OpenGL state.

4. Sprite primitives raster position: updated code that repositions the 
OpenGL rasterposition when the sprite vertex lies to the left or bottom of 
the display window so that it is properly clipped. Tested in both 3D 
(fogtest.c demo) and 2D (trans2d.c demo).

5. Sprite primitives justification. The sprite primitive draw code will now
take into account any justification set using rmTextPropsSetAttribs +
rmNodeSetSceneTextProps.

6. In rmDefaultLighting, changed default setting of localview to RM_TRUE.
Produces more accurate specular reflections at a slight performance cost.

7. RMstate computations. Updated RMstate to include the viewport matrix that
is accessible to application callbacks in the RM_RENDER traversal.
Internal code reorganization to consolidate viewport matrix computation
into a single routine that is accessed from several places.

8. Updated rmNodeSceneGetFog to return RM_WHACKED when no RMfog is present.


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

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.

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 in 1.6.1:
--------------

The next version will be 1.6.0 due to some expected small but noticeable
changes to the API.

- 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.

- The callbacks attached to RMpipes should include an RMpipe * as part
of the callback parameter list.

- RMaux callbacks should provide an RMnode * to the callback routine.

- 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. 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_STTRIP.

- 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--
