#
# Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
# ident	"@(#)README	9.4	07/09/10 SMI"
#

1. Release Notes for mediaLib 2.5
=================================

1.1  What's New in mediaLib 2.5

1.1.1	Libraries Tuned with SSE2 for x86

	On Solaris x86, the following libraries have been tuned using the
	SSE2 instructions:

		/usr/lib/libmlib/libmlib_sse2.so.2
		/usr/lib/libmlib/amd64/libmlib_sse2.so.2

1.1.2	Changes in mediaLib Modules

	The following are 11 new functions in mediaLib 2.5:

		mlib_ImageSetSubimageStruct()
		mlib_ImageResetSubimageStruct()
		mlib_VideoColorRGBint_to_BGRAint()
		mlib_VideoDCT8x8Quantize_S16_S16_B12()
		mlib_VideoDCT8x8Quantize_S16_S16_B12_NA()
		mlib_VideoDCT8x8Quantize_S16_U8()
		mlib_VideoDCT8x8Quantize_S16_U8_NA()
		mlib_VideoDeQuantizeIDCT8x8_S16_S16_B12()
		mlib_VideoDeQuantizeIDCT8x8_S16_S16_B12_NA()
		mlib_VideoDeQuantizeIDCT8x8_U8_S16()
		mlib_VideoDeQuantizeIDCT8x8_U8_S16_NA()

	The following 4 video functions have been renamed from

		mlib_VideoDCT8x8_S16_S16()
		mlib_VideoDCT8x8_S16_S16_NA()
		mlib_VideoIDCT8x8_S16_S16()
		mlib_VideoIDCT8x8_S16_S16_NA()
	to
		mlib_VideoDCT8x8_S16_S16_B10()
		mlib_VideoDCT8x8_S16_S16_B10_NA()
		mlib_VideoIDCT8x8_S16_S16_B12()
		mlib_VideoIDCT8x8_S16_S16_B12_NA()

	respectively, but the old names are kept as the aliases of the new
	ones for backward compatibility.

	Please see mlib_image_proto.h, mlib_video_proto.h and the "mediaLib
	Reference Manual" for the calling sequences of these functions.

1.1.3   Major Bugs/RFEs Fixed

    	6397145 mlib_VideoQuantizeInit_S16() causes SIGFPE when FP_X_INV is set
    	6401721 mlib_ImageAve[_Inp] don't have rounding
	6403330 add a new function mlib_VideoColorRGBint_to_BGRAint() for
		speeding up GNOME
	6408945 add new functions
		mlib_VideoDCT8x8Quantize_[S16_U8|S16_S16_B12][_NA]
		for better performance
    	6431261 add new functions
    		mlib_VideoDeQuantizeIDCT8x8_[U8_S16|S16_S16_B12][_NA]
    		for better performance
    	6509428 mediaLib compositing has off-by-one errors with sse2
    		architecture
	6529757 add a new function mlib_ImageSetSubimageStruct() for speeding
		up GNOME
	6591899 GtkAda's testgtk got SIGFPE in mlib_ZoomBlendEdge()

1.1.4	Changes in mediaLib Examples

	The following examples have been updated from using DGA only to
	using Xlib by default so they can display the results on both SPARC
	and x86 platforms.

		example_g1
		example_g2
		example_i5
		example_i6

1.1.5	Change in Version Number

	The version number has been changed from 2.4 to 2.5.  The distribution
	file names have been changed accordingly.

	mediaLib 2.5 is a minor release and therefore no changes have been 
	made to the mediaLib 2.4 interfaces.  In mediaLib 2.5, the shared
	objects (i.e., the shared libraries) still have an external version
	".2" in their file name extensions, for example, libmlib.so.2.  But
	they have an internal version name "SUNW_2.5" for the new symbols.
	Refer to Solaris "Linker and Libraries Guide" (Part No: 817-1984)
	for more information on Solaris library versioning.

1.1.6	Changes in Documentation

	The "mediaLib Reference Manual" (Part No: 802-7800) has been updated
	for mediaLib 2.5.

-------------------------------------------------------------------------------

1.2  System Requirements

	You must have the following items in order to use mediaLib:

		OS - Solaris 8 or later (SPARC or x86)
		C/C++ Compiler - Sun Studio, or GCC

	Note that the compiler requirement is only for developers.  Also
	note that mediaLib 2.5 was built and tested with Sun Studio 12,
	and it is recommended that it be used with Sun Studio 12 which
	is available for free from the following URL:

		http://developers.sun.com/sunstudio/index.jsp

	It is recommended that Multi-threaded mediaLib be used on
	Solaris 9 or later for better support.

	Disk space requirement for a full installation:

		For Solaris SPARC

		===========================================================
		Location	Compressed Packages	 After Installation
		-----------------------------------------------------------
		/usr			113 MB			245 MB
		/opt			122 MB			278 MB
		===========================================================

		For Solaris x86

		===========================================================
		Location	Compressed Packages	 After Installation
		-----------------------------------------------------------
		/usr			 30 MB			125 MB
		/opt			 36 MB			149 MB
		===========================================================

-------------------------------------------------------------------------------

1.3  mediaLib Components

	mediaLib 2.5 is comprised of eight packages on the Solaris SPARC
	platform or the Solaris x86 platform, including the following six
	platform-specific packages for Solaris SPARC or Solaris x86:

		SUNWmlib       mediaLib - Shared Libraries
		SUNWmliba      mediaLib - Archive Libraries
		SUNWmlibe      mediaLib - Examples
		SUNWmlibh      mediaLib - Headers
		SUNWmlibl      mediaLib - Library Links
		SUNWmlibt      mediaLib - Multi-threaded Libraries

	and the following two common packages for both Solaris SPARC and
	Solaris x86:

		SUNWmlibd      mediaLib - Documentation
		SUNWmlibk      mediaLib - Header and Example Links

-------------------------------------------------------------------------------

1.4  mediaLib Distributions

	There are three types of distributions for mediaLib:

		mediaLib on the Web
		mediaLib bundled with Solaris Express
		mediaLib bundled with Solaris 10

	Currently, the mediaLib released on the Web is version 2.5.  The
	ones bundled with Solaris Express and Solaris 10 are version 2.4,
	but they will be updated to mediaLib 2.5 later on.

1.4.1	mediaLib Packages

	The mediaLib packages can be categorized as follows:

		===========================================================
	        Platform	Package  	In Solaris	 On the Web
		-----------------------------------------------------------
		common		SUNWmlibd			 yes
				SUNWmlibk	bundled		 yes
		-----------------------------------------------------------
		i386		SUNWmlib	bundled		 yes
				SUNWmliba			 yes
				SUNWmlibe	bundled		 yes
				SUNWmlibh	bundled		 yes
				SUNWmlibl	bundled		 yes
				SUNWmlibt	bundled		 yes
		-----------------------------------------------------------
		sparc		SUNWmlib	bundled		 yes
				SUNWmliba			 yes
				SUNWmlibe	bundled		 yes
				SUNWmlibh	bundled		 yes
				SUNWmlibl	bundled		 yes
				SUNWmlibt	bundled		 yes
		===========================================================

1.4.2	mediaLib on the Web

	The following 14 compressed tar files correspond to the 14 packages
	listed in Section 1.4.1, mediaLib Packages, and are provided for
	downloading.  Users can download and install just the packages they
	need.  Use gunzip to decompress.

	common.SUNWmlibd.2.5.tar.gz	- SUNWmlibd (for both SPARC and x86)
	common.SUNWmlibk.2.5.tar.gz	- SUNWmlibk (for both SPARC and x86)
	i386.SUNWmlib.2.5.tar.gz	- SUNWmlib  (for Solaris x86)
	i386.SUNWmliba.2.5.tar.gz	- SUNWmliba (for Solaris x86)
	i386.SUNWmlibe.2.5.tar.gz	- SUNWmlibe (for Solaris x86)
	i386.SUNWmlibh.2.5.tar.gz	- SUNWmlibh (for Solaris x86)
	i386.SUNWmlibl.2.5.tar.gz	- SUNWmlibl (for Solaris x86)
	i386.SUNWmlibt.2.5.tar.gz	- SUNWmlibt (for Solaris x86)
	sparc.SUNWmlib.2.5.tar.gz	- SUNWmlib  (for Solaris SPARC)
	sparc.SUNWmliba.2.5.tar.gz	- SUNWmliba (for Solaris SPARC)
	sparc.SUNWmlibe.2.5.tar.gz	- SUNWmlibe (for Solaris SPARC)
	sparc.SUNWmlibh.2.5.tar.gz	- SUNWmlibh (for Solaris SPARC)
	sparc.SUNWmlibl.2.5.tar.gz	- SUNWmlibl (for Solaris SPARC)
	sparc.SUNWmlibt.2.5.tar.gz	- SUNWmlibt (for Solaris SPARC)

-------------------------------------------------------------------------------

1.5  mediaLib File Structure

	Each package of mediaLib consists of part of the structure shown below.
	The packages can be installed independently.  The actual files which
	show up on your system depend on which packages you have installed.

	After a full installation of mediaLib 2.5, the files are organized as
	follows:

1.5.1	On Solaris SPARC

/usr
 |
 +--- demo -----+--- mlib ------+--- README, Makefile
 |				+--- algebra ------- *.c, *.h, Makefile.*
 |				+--- graphics ------ *.c, *.h, Makefile.*
 |				+--- image --------- *.c, *.h, Makefile.*
 |				+--- signal -------- *.c, *.h, Makefile.*
 |				+--- volume -------- *.c, *.h, Makefile.*
 |				+--- util ---------- *.c, *.h, sparc*/*.o
 |
 +--- include --+--- mlib.h
 |		+--- mlib_algebra.h
 |		+--- mlib_algebra_proto.h
 |		+--- mlib_graphics.h
 |		+--- mlib_graphics_drawset_proto.h
 |		+--- mlib_graphics_proto.h
 |		+--- mlib_image.h
 |		+--- mlib_image_blend_proto.h
 |		+--- mlib_image_get.h
 |		+--- mlib_image_proto.h
 |		+--- mlib_image_types.h
 |		+--- mlib_signal.h
 |		+--- mlib_signal_proto.h
 |		+--- mlib_signal_types.h
 |		+--- mlib_status.h
 |		+--- mlib_sys.h
 |		+--- mlib_sys_proto.h
 |		+--- mlib_types.h
 |		+--- mlib_video.h
 |		+--- mlib_video_proto.h
 |		+--- mlib_volume.h
 |		+--- mlib_volume_proto.h
 |		+--- mlib_volume_types.h
 |
 +--- lib ------+--- libmlib.so -> ./libmlib.so.2
		+--- libmlib.so.2
		+--- libmlib_mt.so -> ./libmlib_mt.so.2
		+--- libmlib_mt.so.2
		|
		+--- sparcv9 --+-- libmlib.so -> ./libmlib.so.2
		|	       +-- libmlib.so.2
		|	       +-- libmlib_mt.so -> ./libmlib_mt.so.2
		|	       +-- libmlib_mt.so.2
		|
		+--- cpu ------+-- sparcv8plus -----+- libmlib.so.2
			       |
			       +-- sparcv8plus+vis -+- libmlib.so.2
			       |
			       +-- sparcv9+vis -----+- sparcv9 -+- libmlib.so.2
			       |
			       +-- sparcv9+vis2 ----+- libmlib.so.2
						    +- sparcv9 -+- libmlib.so.2

/opt/SUNWmlib
 |
 +--- doc ------+--- README		(this file)
 |		+--- mlib_guide.pdf	(user's guide)
 |		+--- mlib_install.pdf	(release notes and installation guide)
 |		+--- mlib_qr.pdf	(quick reference manual)
 |		+--- mlib_ref.pdf	(reference manual)
 |
 +--- example -> ../../usr/demo/mlib
 |
 +--- include --+--- mlib.h -> ../../../usr/include/mlib.h
 |		+--- mlib_algebra.h -> ../../../usr/include/mlib_algebra.h
 |		+--- mlib_algebra_proto.h ->
 |		|	../../../usr/include/mlib_algebra_proto.h
 |		+--- mlib_graphics.h -> ../../../usr/include/mlib_graphics.h
 |		+--- mlib_graphics_drawset_proto.h ->
 |		|	../../../usr/include/mlib_graphics_drawset_proto.h
 |		+--- mlib_graphics_proto.h ->
 |		|	../../../usr/include/mlib_graphics_proto.h
 |		+--- mlib_image.h -> ../../../usr/include/mlib_image.h
 |		+--- mlib_image_blend_proto.h ->
 |		|	../../../usr/include/mlib_image_blend_proto.h
 |		+--- mlib_image_get.h -> ../../../usr/include/mlib_image_get.h
 |		+--- mlib_image_proto.h ->
 |		|	../../../usr/include/mlib_image_proto.h
 |		+--- mlib_image_types.h ->
 |		|	../../../usr/include/mlib_image_types.h
 |		+--- mlib_signal.h -> ../../../usr/include/mlib_signal.h
 |		+--- mlib_signal_proto.h ->
 |		|	../../../usr/include/mlib_signal_proto.h
 |		+--- mlib_signal_types.h ->
 |		|	../../../usr/include/mlib_signal_types.h
 |		+--- mlib_status.h -> ../../../usr/include/mlib_status.h
 |		+--- mlib_sys.h -> ../../../usr/include/mlib_sys.h
 |		+--- mlib_sys_proto.h ->
 |		|	../../../usr/include/mlib_sys_proto.h
 |		+--- mlib_types.h -> ../../../usr/include/mlib_types.h
 |		+--- mlib_video.h -> ../../../usr/include/mlib_video.h
 |		+--- mlib_video_proto.h ->
 |		|	../../../usr/include/mlib_video_proto.h
 |		+--- mlib_volume.h -> ../../../usr/include/mlib_volume.h
 |		+--- mlib_volume_proto.h ->
 |		|	../../../usr/include/mlib_volume_proto.h
 |		+--- mlib_volume_types.h ->
 |			../../../usr/include/mlib_volume_types.h
 |
 +--- lib ------+--- libmlib.a -> ./sparcv8plus+vis/libmlib.a
		+--- libmlib.so -> ./libmlib.so.2
		+--- libmlib.so.2 -> ../../../usr/lib/libmlib.so.2
		+--- libmlib_algebra.so -> ./libmlib_algebra.so.2
		+--- libmlib_algebra.so.2 -> ./libmlib.so.2
		+--- libmlib_graphics.so -> ./libmlib_graphics.so.2
		+--- libmlib_graphics.so.2 -> ./libmlib.so.2
		+--- libmlib_image.so -> ./libmlib_image.so.2
		+--- libmlib_image.so.2 -> ./libmlib.so.2
		+--- libmlib_signal.so -> ./libmlib_signal.so.2
		+--- libmlib_signal.so.2 -> ./libmlib.so.2
		+--- libmlib_video.so -> ./libmlib_video.so.2
		+--- libmlib_video.so.2 -> ./libmlib.so.2
		+--- libmlib_volume.so -> ./libmlib_volume.so.2
		+--- libmlib_volume.so.2 -> ./libmlib.so.2
		|
		+--- sparcv8 -----------+--- libmlib.a
		|			+--- libmlib.so -> ./libmlib.so.2
		|			+--- libmlib.so.2 ->
 		|			|      ../../../../usr/lib/libmlib.so.2
		|			+--- libmlib_algebra.so ->
 		|			|	./libmlib_algebra.so.2
		|			+--- libmlib_algebra.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_graphics.so ->
 		|			|	./libmlib_graphics.so.2
		|			+--- libmlib_graphics.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_image.so ->
 		|			|	./libmlib_image.so.2
		|			+--- libmlib_image.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_signal.so ->
 		|			|	./libmlib_signal.so.2
		|			+--- libmlib_signal.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_video.so ->
 		|			|	./libmlib_video.so.2
		|			+--- libmlib_video.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_volume.so ->
 		|			|	./libmlib_volume.so.2
		|			+--- libmlib_volume.so.2 ->
 		|				./libmlib.so.2
		|
		+--- sparcv8plus -------+--- libmlib.a
		|			+--- libmlib.so -> ./libmlib.so.2
		|			+--- libmlib.so.2 ->
 		|	../../../../usr/lib/cpu/sparcv8plus/libmlib.so.2
		|			+--- libmlib_algebra.so ->
 		|			|	./libmlib_algebra.so.2
		|			+--- libmlib_algebra.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_graphics.so ->
 		|			|	./libmlib_graphics.so.2
		|			+--- libmlib_graphics.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_image.so ->
 		|			|	./libmlib_image.so.2
		|			+--- libmlib_image.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_signal.so ->
 		|			|	./libmlib_signal.so.2
		|			+--- libmlib_signal.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_video.so ->
 		|			|	./libmlib_video.so.2
		|			+--- libmlib_video.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_volume.so ->
 		|			|	./libmlib_volume.so.2
		|			+--- libmlib_volume.so.2 ->
 		|				./libmlib.so.2
		|
		+--- sparcv8plus+vis ---+--- libmlib.a
		|			+--- libmlib.so -> ./libmlib.so.2
		|			+--- libmlib.so.2 ->
 		|	../../../../usr/lib/cpu/sparcv8plus+vis/libmlib.so.2
		|			+--- libmlib_algebra.so ->
 		|			|	./libmlib_algebra.so.2
		|			+--- libmlib_algebra.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_graphics.so ->
 		|			|	./libmlib_graphics.so.2
		|			+--- libmlib_graphics.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_image.so ->
 		|			|	./libmlib_image.so.2
		|			+--- libmlib_image.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_signal.so ->
 		|			|	./libmlib_signal.so.2
		|			+--- libmlib_signal.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_video.so ->
 		|			|	./libmlib_video.so.2
		|			+--- libmlib_video.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_volume.so ->
 		|			|	./libmlib_volume.so.2
		|			+--- libmlib_volume.so.2 ->
 		|				./libmlib.so.2
		|
		+--- sparcv8plus+vis2 --+--- libmlib.a
		|			+--- libmlib.so -> ./libmlib.so.2
		|			+--- libmlib.so.2 ->
 		|	../../../../usr/lib/cpu/sparcv9+vis2/libmlib.so.2
		|			+--- libmlib_algebra.so ->
 		|			|	./libmlib_algebra.so.2
		|			+--- libmlib_algebra.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_graphics.so ->
 		|			|	./libmlib_graphics.so.2
		|			+--- libmlib_graphics.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_image.so ->
 		|			|	./libmlib_image.so.2
		|			+--- libmlib_image.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_signal.so ->
 		|			|	./libmlib_signal.so.2
		|			+--- libmlib_signal.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_video.so ->
 		|			|	./libmlib_video.so.2
		|			+--- libmlib_video.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_volume.so ->
 		|			|	./libmlib_volume.so.2
		|			+--- libmlib_volume.so.2 ->
 		|				./libmlib.so.2
		|
		+--- sparcv9 -----------+--- libmlib.a
		|			+--- libmlib.so -> ./libmlib.so.2
		|			+--- libmlib.so.2 ->
 		|	../../../../usr/lib/sparcv9/libmlib.so.2
		|			+--- libmlib_algebra.so ->
 		|			|	./libmlib_algebra.so.2
		|			+--- libmlib_algebra.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_graphics.so ->
 		|			|	./libmlib_graphics.so.2
		|			+--- libmlib_graphics.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_image.so ->
 		|			|	./libmlib_image.so.2
		|			+--- libmlib_image.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_signal.so ->
 		|			|	./libmlib_signal.so.2
		|			+--- libmlib_signal.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_video.so ->
 		|			|	./libmlib_video.so.2
		|			+--- libmlib_video.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_volume.so ->
 		|			|	./libmlib_volume.so.2
		|			+--- libmlib_volume.so.2 ->
 		|				./libmlib.so.2
		|
		+--- sparcv9+vis -------+--- libmlib.a
		|			+--- libmlib.so -> ./libmlib.so.2
		|			+--- libmlib.so.2 ->
 		|      ../../../../usr/lib/cpu/sparcv9+vis/sparcv9/libmlib.so.2
		|			+--- libmlib_algebra.so ->
 		|			|	./libmlib_algebra.so.2
		|			+--- libmlib_algebra.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_graphics.so ->
 		|			|	./libmlib_graphics.so.2
		|			+--- libmlib_graphics.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_image.so ->
 		|			|	./libmlib_image.so.2
		|			+--- libmlib_image.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_signal.so ->
 		|			|	./libmlib_signal.so.2
		|			+--- libmlib_signal.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_video.so ->
 		|			|	./libmlib_video.so.2
		|			+--- libmlib_video.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_volume.so ->
 		|			|	./libmlib_volume.so.2
		|			+--- libmlib_volume.so.2 ->
 		|				./libmlib.so.2
		|
		+--- sparcv9+vis2 ------+--- libmlib.a
					+--- libmlib.so -> ./libmlib.so.2
					+--- libmlib.so.2 ->
 		      ../../../../usr/lib/cpu/sparcv9+vis2/sparcv9/libmlib.so.2
					+--- libmlib_algebra.so ->
 					|	./libmlib_algebra.so.2
					+--- libmlib_algebra.so.2 ->
 					|	./libmlib.so.2
					+--- libmlib_graphics.so ->
 					|	./libmlib_graphics.so.2
					+--- libmlib_graphics.so.2 ->
 					|	./libmlib.so.2
					+--- libmlib_image.so ->
 					|	./libmlib_image.so.2
					+--- libmlib_image.so.2 ->
 					|	./libmlib.so.2
					+--- libmlib_signal.so ->
 					|	./libmlib_signal.so.2
					+--- libmlib_signal.so.2 ->
 					|	./libmlib.so.2
					+--- libmlib_video.so ->
 					|	./libmlib_video.so.2
					+--- libmlib_video.so.2 ->
 					|	./libmlib.so.2
					+--- libmlib_volume.so ->
 					|	./libmlib_volume.so.2
					+--- libmlib_volume.so.2 ->
 						./libmlib.so.2

1.5.2	On Solaris x86

/usr
 |
 +--- demo -----+--- mlib ------+--- README, Makefile
 |				+--- algebra ------- *.c, *.h, Makefile.*
 |				+--- graphics ------ *.c, *.h, Makefile.*
 |				+--- image --------- *.c, *.h, Makefile.*
 |				+--- signal -------- *.c, *.h, Makefile.*
 |				+--- volume -------- *.c, *.h, Makefile.*
 |				+--- util ---------- *.c, *.h
 |
 +--- include --+--- mlib.h
 |		+--- mlib_algebra.h
 |		+--- mlib_algebra_proto.h
 |		+--- mlib_graphics.h
 |		+--- mlib_graphics_drawset_proto.h
 |		+--- mlib_graphics_proto.h
 |		+--- mlib_image.h
 |		+--- mlib_image_blend_proto.h
 |		+--- mlib_image_get.h
 |		+--- mlib_image_proto.h
 |		+--- mlib_image_types.h
 |		+--- mlib_signal.h
 |		+--- mlib_signal_proto.h
 |		+--- mlib_signal_types.h
 |		+--- mlib_status.h
 |		+--- mlib_sys.h
 |		+--- mlib_sys_proto.h
 |		+--- mlib_types.h
 |		+--- mlib_video.h
 |		+--- mlib_video_proto.h
 |		+--- mlib_volume.h
 |		+--- mlib_volume_proto.h
 |		+--- mlib_volume_types.h
 |
 +--- lib ------+--- libmlib.so -> ./libmlib.so.2
		+--- libmlib.so.2
		+--- libmlib_mt.so -> ./libmlib_mt.so.2
		+--- libmlib_mt.so.2
		|
		+--- amd64 -----+--- libmlib.so -> ./libmlib.so.2
		|		+--- libmlib.so.2
		|	        +--- libmlib_mt.so -> ./libmlib_mt.so.2
		|	        +--- libmlib_mt.so.2
		|
		+--- libmlib ---+--- libmlib_sse2.so.2
				|
				+--- amd64 ---+--- libmlib_sse2.so.2

/opt/SUNWmlib
 |
 +--- doc ------+--- README		(this file)
 |		+--- mlib_guide.pdf	(user's guide)
 |		+--- mlib_install.pdf	(release notes and installation guide)
 |		+--- mlib_qr.pdf	(quick reference manual)
 |		+--- mlib_ref.pdf	(reference manual)
 | 
 +--- example -> ../../usr/demo/mlib
 |
 +--- include --+--- mlib.h -> ../../../usr/include/mlib.h
 |		+--- mlib_algebra.h -> ../../../usr/include/mlib_algebra.h
 |		+--- mlib_algebra_proto.h ->
 |		|	../../../usr/include/mlib_algebra_proto.h
 |		+--- mlib_graphics.h -> ../../../usr/include/mlib_graphics.h
 |		+--- mlib_graphics_drawset_proto.h ->
 |		|	../../../usr/include/mlib_graphics_drawset_proto.h
 |		+--- mlib_graphics_proto.h ->
 |		|	../../../usr/include/mlib_graphics_proto.h
 |		+--- mlib_image.h -> ../../../usr/include/mlib_image.h
 |		+--- mlib_image_blend_proto.h ->
 |		|	../../../usr/include/mlib_image_blend_proto.h
 |		+--- mlib_image_get.h -> ../../../usr/include/mlib_image_get.h
 |		+--- mlib_image_proto.h ->
 |		|	../../../usr/include/mlib_image_proto.h
 |		+--- mlib_image_types.h ->
 |		|	../../../usr/include/mlib_image_types.h
 |		+--- mlib_signal.h -> ../../../usr/include/mlib_signal.h
 |		+--- mlib_signal_proto.h ->
 |		|	../../../usr/include/mlib_signal_proto.h
 |		+--- mlib_signal_types.h ->
 |		|	../../../usr/include/mlib_signal_types.h
 |		+--- mlib_status.h -> ../../../usr/include/mlib_status.h
 |		+--- mlib_sys.h -> ../../../usr/include/mlib_sys.h
 |		+--- mlib_sys_proto.h ->
 |		|	../../../usr/include/mlib_sys_proto.h
 |		+--- mlib_types.h -> ../../../usr/include/mlib_types.h
 |		+--- mlib_video.h -> ../../../usr/include/mlib_video.h
 |		+--- mlib_video_proto.h ->
 |		|	../../../usr/include/mlib_video_proto.h
 |		+--- mlib_volume.h -> ../../../usr/include/mlib_volume.h
 |		+--- mlib_volume_proto.h ->
 |		|	../../../usr/include/mlib_volume_proto.h
 |		+--- mlib_volume_types.h ->
 |			../../../usr/include/mlib_volume_types.h
 |
 +--- lib ------+--- libmlib.a -> ./i386/libmlib.a
		+--- libmlib.so -> ./libmlib.so.2
		+--- libmlib.so.2 -> ../../../usr/lib/libmlib.so.2
		+--- libmlib_algebra.so -> ./libmlib_algebra.so.2
		+--- libmlib_algebra.so.2 -> ./libmlib.so.2
		+--- libmlib_graphics.so -> ./libmlib_graphics.so.2
		+--- libmlib_graphics.so.2 -> ./libmlib.so.2
		+--- libmlib_image.so -> ./libmlib_image.so.2
		+--- libmlib_image.so.2	-> ./libmlib.so.2
		+--- libmlib_signal.so -> ./libmlib_signal.so.2
		+--- libmlib_signal.so.2 -> ./libmlib.so.2
		+--- libmlib_video.so -> ./libmlib_video.so.2
		+--- libmlib_video.so.2 -> ./libmlib.so.2
		+--- libmlib_volume.so -> ./libmlib_volume.so.2
		+--- libmlib_volume.so.2 -> ./libmlib.so.2
		|
		+--- i386 --------------+--- libmlib.a
		|			+--- libmlib.so -> ./libmlib.so.2
		|			+--- libmlib.so.2 ->
 		|			|      ../../../../usr/lib/libmlib.so.2
		|			+--- libmlib_algebra.so ->
 		|			|	./libmlib_algebra.so.2
		|			+--- libmlib_algebra.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_graphics.so ->
 		|			|	./libmlib_graphics.so.2
		|			+--- libmlib_graphics.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_image.so ->
 		|			|	./libmlib_image.so.2
		|			+--- libmlib_image.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_signal.so ->
 		|			|	./libmlib_signal.so.2
		|			+--- libmlib_signal.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_video.so ->
 		|			|	./libmlib_video.so.2
		|			+--- libmlib_video.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_volume.so ->
 		|			|	./libmlib_volume.so.2
		|			+--- libmlib_volume.so.2 ->
 		|				./libmlib.so.2
		|
		+--- amd64 -------------+--- libmlib.a
		|			+--- libmlib.so -> ./libmlib.so.2
		|			+--- libmlib.so.2 ->
 		|	../../../../usr/lib/amd64/libmlib.so.2
		|			+--- libmlib_algebra.so ->
 		|			|	./libmlib_algebra.so.2
		|			+--- libmlib_algebra.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_graphics.so ->
 		|			|	./libmlib_graphics.so.2
		|			+--- libmlib_graphics.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_image.so ->
 		|			|	./libmlib_image.so.2
		|			+--- libmlib_image.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_signal.so ->
 		|			|	./libmlib_signal.so.2
		|			+--- libmlib_signal.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_video.so ->
 		|			|	./libmlib_video.so.2
		|			+--- libmlib_video.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_volume.so ->
 		|			|	./libmlib_volume.so.2
		|			+--- libmlib_volume.so.2 ->
 		|				./libmlib.so.2
		|
		+--- sse2 --------------+--- libmlib.a
		|			+--- libmlib.so -> ./libmlib.so.2
		|			+--- libmlib.so.2 ->
 		|	../../../../usr/lib/libmlib/libmlib_sse2.so.2
		|			+--- libmlib_algebra.so ->
 		|			|	./libmlib_algebra.so.2
		|			+--- libmlib_algebra.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_graphics.so ->
 		|			|	./libmlib_graphics.so.2
		|			+--- libmlib_graphics.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_image.so ->
 		|			|	./libmlib_image.so.2
		|			+--- libmlib_image.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_signal.so ->
 		|			|	./libmlib_signal.so.2
		|			+--- libmlib_signal.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_video.so ->
 		|			|	./libmlib_video.so.2
		|			+--- libmlib_video.so.2 ->
 		|			|	./libmlib.so.2
		|			+--- libmlib_volume.so ->
 		|			|	./libmlib_volume.so.2
		|			+--- libmlib_volume.so.2 ->
 		|				./libmlib.so.2
		|
		+--- i386+sse2 -> ./sse2
		|
		+--- amd64+sse2 --------+--- libmlib.a

-------------------------------------------------------------------------------

1.6  Tips on Using mediaLib 2.5 for Better Performance

1.6.1	Use MT mediaLib on systems with multiple processors or a processor
	with multiple cores

1.6.1.1 Introduction

	Multi-threaded (MT) mediaLib is a software layer developed on top of
	mediaLib using OpenMP.  When used with a large data set on
	multi-processor systems, MT mediaLib will partition data into subsets
	and process the subsets in parallel, thus greatly improving performance
	of applications that are using mediaLib.  Because Solaris treats each
	core/strand on a CMT (chip multi-threading) CPU, such as UltraSPARC-IV
	and UltraSPARC-T1, as a separate logical processor, applications will
	also benefit from MT mediaLib even running on systems with a single
	UltraSPARC-IV or UltraSPARC-T1.

	Note that MT mediaLib has the same API as mediaLib.  There is no need
	to modify any source code to use MT mediaLib.

	A subset of functions for algebra, image processing, signal processing,
	and video processing are implemented in MT mediaLib with this release.

	MT mediaLib uses the following general scheme to determine whether to
	use multithreading and how many threads to use.

	    if (function is not capable of MT) {
		call mediaLib function in single thread
	    }
	    else if (data set is too small to benefit from MT) {
		call mediaLib function in single thread
	    }
	    else if (PARALLEL = 1) {
		call mediaLib function in single thread
	    }
	    else {
		if (PARALLEL is not set) or (PARALLEL <= 0) {
		    NTHRS = number of online processors
		}
		else if (PARALLEL > number of online processors) {
		    NTHRS = number of online processors
 		}
 		else {
		    NTHRS = PARALLEL
		}
		if (data set is too small to benefit from NTHRS threads) {
		    NTHRS = reduced according to size of data set
		}
		partition data into NTHRS subsets
		call mediaLib function from NTHRS threads to process
			each subset in separate thread
	    }

1.6.1.2 Using MT mediaLib

	There are two ways to use MT mediaLib:

	    a. pre-loading MT mediaLib during runtime
	    b. linking with MT mediaLib directly

1.6.1.2.1 Pre-Loading MT mediaLib

	You can pre-load MT mediaLib during runtime by setting the LD_PRELOAD
	environment variable, and then running your application as normal.

	    Bourne/Korn Shell:

		LD_PRELOAD=libmlib_mt.so
		export LD_PRELOAD

	    C Shell:

		setenv LD_PRELOAD libmlib_mt.so

	In this way, you can take advantage of MT mediaLib WITHOUT rebuilding
	your applications.

1.6.1.2.2 Linking with MT mediaLib

	You can also rebuild your application by linking it with MT mediaLib.

	cc [ flag ... ] file ...  -lmlib_mt -lmlib [ library ... ]

	In this way, MT mediaLib is always used whenever your application is
	started.

1.6.1.3 Parallelization Control

	The parallelization of MT mediaLib is controlled, in part, with the
	PARALLEL environment variable.  You can change its setting to adjust
	the degree of parallelization before starting your application.

	    Bourne/Korn Shell:

		PARALLEL=NTHRS
		export PARALLEL

	    C Shell:

		setenv PARALLEL NTHRS

	where NTHRS is a positive integer.

	Note that other factors also affect the degree of parallelization in
	MT mediaLib.  See the introduction section for more information.

	There are other environment variables that can be set to change OpenMP
	runtime behavior.  See section 2.3 OpenMP Environment Variables in Sun
	Studio 12: OpenMP API User's Guide in following URL for more details.

	    http://docs.sun.com/app/docs/doc/819-5270/aewcb?a=view

1.6.1.4 Recommended Patches

	It is recommended that one of the following patches or their later
	revisions be installed in order to use MT mediaLib.

	On Solaris SPARC:
	
	    117557-04  SunOS 5.8: Microtasking libraries (libmtsk) patch
	    117560-06  SunOS 5.9: Microtasking libraries (libmtsk) patch
	    120753-05  SunOS 5.10: Microtasking libraries (libmtsk) patch

	On Solaris x86:
	
	    117558-04  SunOS 5.8_x86: Microtasking libraries (libmtsk) patch
	    117559-06  SunOS 5.9_x86: Microtasking libraries (libmtsk) patch
	    120754-05  SunOS 5.10_x86: Microtasking libraries (libmtsk) patch

	They are available from the SunSolve web site.

	    http://sunsolve.sun.com/

1.6.2	Use 8-byte or 16-byte Aligned Data Buffers

	For some mediaLib functions, data buffers are required to be 8-byte
	aligned (i.e., to start from an 8-byte aligned address).  For other
	functions, there is no requirement on data buffer alignment, but they
	usually run faster in the cases with aligned data buffers.  Refer to
	"mediaLib Reference Manual" (Part No: 802-7800) for the alignment
	requirements, if any, for each mediaLib function.

	Use mlib_malloc(), which is a wrapper of memalign(3C) with an
	alignment of 16, or mlib_ImageCreate() when possible.

1.6.3	Use the filter shared libraries at /usr/lib/ to let the runtime linker
	pick the best platform-specific library

	On UltraSPARC-based systems, there are VIS and VIS2 versions of the
	libraries which have better performance than the C versions.  But
	you don't have to link your applications to the shared libraries at
	/usr/lib/cpu/ directly.  In fact, on UltraSPARC-based machines, the
	shared libraries libmlib.so.2 at /usr/lib/ and /usr/lib/spacv9/ are
	built as auxiliary filters for the platform-specific libraries
	under /usr/lib/cpu/.  You just need to link your applications to
	/usr/lib/libmlib.so, or /usr/lib/sparcv9/libmlib.so in case of 64-bit,
	and let the runtime linker pick the best library for you.  You can
	run ldd(1) on your executable to see which version of libmlib.so.2 is
	actually used.  For example, the 32-bit VIS2 version library is used
	in the following case:

		% ldd /usr/demo/mlib/image/example_i1
        	libmlib.so.2 =>  /usr/lib/libmlib.so.2
        	libc.so.1 =>     /lib/libc.so.1
        	libm.so.2 =>     /lib/libm.so.2
        	/usr/lib/cpu/sparcv9+vis2/libmlib.so.2
        	/platform/SUNW,Sun-Blade-2500/lib/libc_psr.so.1

	On AMD64-based systems, there are SSE2 versions of libraries installed
	at /usr/lib/libmlib/.   They were built as auxiliary filtees of the
	C version filter libraries.  You can link your application to a filter
	library and let the runtime linker pick up the filtee library.  For
	example:

		% ldd /usr/demo/mlib/image/example_i1_x86
        	libmlib.so.2 =>  /usr/lib/libmlib.so.2
        	libc.so.1 =>     /lib/libc.so.1
        	libm.so.2 =>     /lib/libm.so.2
        	/usr/lib/libmlib/libmlib_sse2.so.2


2. Installation Guide for mediaLib 2.5
======================================

	Note:  The following steps are for installing mediaLib packages
	manually.  Some of the mediaLib packages are bundled with Solaris 10
	FCS and later releases, which means they either are preinstalled or
	can be installed by a Solaris installer.  So if you have a system
	running Solaris 10 or later, please check the installed mediaLib
	packages as shown in step (3) before proceeding.

    (1) Download the compressed packages for mediaLib 2.5 from the Web at:

		http://www.sun.com/processors/vis/mlibfiles.html

	Assume they reside in the directory /tmp/.

    (2) Extract the files from each downloaded file. For example to extract
	files from /tmp/sparc.SUNWmlib.2.5.tar.gz, perform the following
	steps:

		% cd /tmp
		% gzip -cd sparc.SUNWmlib.2.5.tar.gz | tar -xvf -

    (3) Check if any older version of mediaLib packages are installed.

		% pkginfo | grep SUNWmlib
		% pkginfo -x SUNWmlib SUNWmlibe SUNWmlibh SUNWmlibk SUNWmlibl \
		  SUNWmlibt

    (4)	Become a superuser.

		% su
		password:
		#

    (5)	Remove the older version of mediaLib packages, if any.  For example,

		# pkgrm SUNWmlib SUNWmlibe SUNWmlibh SUNWmlibk SUNWmlibl \
		  SUNWmlibt

    (6)	Add the new packages to your system.

	You can install one or more packages that you need.  For example, to
	install the packages SUNWmlib and SUNWmlibh, enter:

		# pkgadd -d `pwd` SUNWmlib SUNWmlibh

	and follow the instructions.  By default, the packages SUNWmlib,
	SUNWmlibt, SUNWmlibh and SUNWmlibe are installed at /usr while the
	other packages are installed at /opt.  See the man page of pkgadd(1M)
	for more information if you want to install the packages in other
	places.

    (7)	Exit from superuser.

		# exit
		%