ECW JPEG 2000 SDK Source Distribution
Version 3.3 Release
Date : 8th February 2006
Build.txt
----------------------


ABOUT

Welcome to the ECW JPEG 2000 SDK source code distribution.  This package enables you to port the SDK to alternate platforms if desired, and/or make custom modifications.  We encourage (but not require) you to submit changes back to ER Mapper to be included in the main distribution.

WHAT'S NEW IN VERSION 3.3

Numerous bug fixes and enhancements, including:

FIXES
*	functional ECWP on platforms other than Windows
*	a fix to lossless JPEG 2000 compression
*	change to headers to allow overloading new and delete on Windows
*	correct calculation of compression throughput
*	large file support issues fixed
*	fix to UNICODE support making it orthogonal to the use of UNICODE #define in client code
*	fixes to the platform-dependent code for MacOS X
*	fix to a bug where scanline reading was not reset between views in some situations
*	fix to a bug where RGB reads were corrupt when reading bands one by one
*	fix to ensure EOC (end of codestream) markers always written to JPEG 2000 output
*	fix to ensure consistency of view information when reading in tiled mode
*	fix to a bug where progressive (refresh callback) read mode was broken for tiled views
*	missing documentation items restored

ENHANCEMENTS
*	no more restrictions on the distribution of "Server Software" under the GPL-style Public Use License Agreement
*	optional and runtime configurable auto-scaling of low bitdepth JPEG 2000 data to fit the output buffer data range
*	unrestricted view sizes for views obtained via ECWP in blocking read mode
*	runtime configurable maximum size for views set in progressive read mode
*	automated support for single bit opacity bands providing a null cell mechanism
*	functional static library builds for NCSEcw, NCSUtil, and NCScnet and for all SDK code as a single linkable object
*	a new build structure called "libecwj2" providing single-library shared and static builds
*	libecwj2 makefiles for gcc/g++ on Solaris, Linux and Mac OS X
*	inclusion of the sample code that formerly shipped with the binary distribution, together with makefiles for the libecwj2 shared and static libraries

LICENSE

This distribution is covered by the ECW SDK license agreement.  See license.txt for details of the 3 alternate licenses available to use this distribution under.  NEW: the restriction on distribution of "Server Software" has been entirely removed from the GPL-style Public Use License Agreement as of this beta release.

REQUIREMENTS

The default configuration of the ECW JPEG 2000 SDK requires the following 3rd party libraries:

Little CMS - A small integrated ICC profile engine.  This should be placed in Source/C/NCSEcw/lcms.  You can remove this dependency by removing NCSJPC_USE_LCMS from the project settings and lcms112.lib from the link line, however this will disable all ICC profile handling (including restricted ICC profiles).  LittleCMS is available from www.littlecms.com.

TinyXML - A small XML parser.  This should be placed in Source/C/tinyxml.  You can remove this dependency by removing NCSJPC_USE_TINYXML from the project settings, however this will disable the GML Geolocation XML box support.  TinyXML is available from www.sourceforge.net/projects/tinyxml.

IJG libjpeg - The Independent JPEG Group's JPEG library.  This should be pleace in Source/C/libjpeg.  This is required to build the NCSRenderer object, which supports writing out JPEG files.  The IJG libjpeg is available from www.ijg.org.

All 3 libraries are (currently) redistributable in commercial applications at no charge, providing their respective distribution requirements are met.  For your convenience versions of these are included in this distribution, subject to their respective licensing conditions, to enable you to quickly build the SDK with minimal effort.

PROJECTS

The ECW JPEG 2000 SDK is split into 3 basic parts:

- NCSUtil: NCS portability utility library, including routines for memory allocation, threading, mutex etc.
- NCSCnet: NCS client networking library.  Use NCScnet2 under win32 which utilises wininet or winhttp, NCScnet3 on MacOS/Unix uses raw sockets.
- NCSEcw: NCS Wavelet C/C++ compression/decompression library.

The small NCSEcwC library now contains the C API compression routines which in this version wrap calls to the C++ API.

THE LIBECWJ2 BUILD STRUCTURE

The ECW JPEG 2000 SDK is supplied with two build structures.  The first, newer system is the "libecwj2" project that allows you to build a single static or shared library object.  The intent of the new build system is to simplify building and linking for user applications that will rarely, if ever, wish to use the library functionality separately.

The older system that previous users of the ECW JPEG 2000 SDK will already be familiar with is the three part NCSEcw, NCScnet, and NCSUtil build.  Build files for these projects are still supplied with the SDK and you are welcome to continue using them - in this beta version you may find that in some cases they are more stable than the libraries built under the new system.

There are also some circumstances where (for example) the network services library functionality may not be required and you may want to keep your binary sizes to a minimum.  If you have existing projects that link against NCSEcw, NCScnet and NCSUtil we encourage you to try out the libecwj2 build.

The following notes about compilation are divided into three sections - notes that are common to both build structures, notes for libecwj2, and notes for the old system.


COMPILING: GENERAL NOTES

You should have an up to date compiler and development environment installed on your build machine.  In the case of Windows builds either Visual Studio 6.0 (with Service Packs 1-5) or Visual Studio .NET 2003 are supported, and it is suggested you obtain the latest version of the Microsoft Platform SDK which will ensure you are able to build the hardware optimised SDK code.

In the case of Linux/Solaris/Mac OS X, we suggest a standard installation of gcc/g++ 3.4 or higher, and GNU Make be used to compile.  You may also have success with earlier versions of gcc or other compilers, although minor modifications to the source may be required.

COMPILING: NOTES FOR LIBECWJ2

The single-library libecwj2 build system uses build files created using Trolltech's make configuration tool, Qmake (which is shipped with Qt).  Generated build files for Linux, Solaris, Mac OS X and Windows are included, as well as the master configuration files libecwj2.pro and examples.pro which are used in conjunction with Qmake to generate new build files.  If you have access to Qmake, which is available free from Trolltech as part of Qt, you can modify these files as an excellent starting point for generating build files for other operating systems, compilers and hardware.

The ECW JPEG 2000 SDK ships with the NT batch files QmakeMakes.bat and QmakeExampleMakes.bat that generate the libecwj2 and example projects for Win32, Linux, Solaris and Mac OS X.  A script is used to eliminate Qmake-dependent material from the makefiles so that you can use them without needing Qt or Qmake installed.  If you regenerate the build files or create new ones using the .pro Qmake files, you may need to make minor manual edits to remove Qmake dependencies for distribution.

* WINDOWS

To build the single static libecwj2S.lib library from the source follow these instructions:

-	Open your Microsoft IDE of choice (either Visual Studio 6.0 or .NET 2003)
-	Open the libecwj2 project file from $INSTALL/Source/NCSBuildQmake
	(either libecwj2-win32-static.dsp or libecwj2_win32_net_static.vcproj - a default workspace is created)
-	Choose either the release or debug configurations
-	Using .NET 2003: Change the startup project to NCSEcwC_SDK
-	Using Visual Studio 6.0: Change the build configuration to NCSEcwC_SDK
-	Build all
-	Once the build is complete the libecwj2S.lib library has been created in the $INSTALL/lib directory

To build the single shared libecwj2.dll library follow the steps above with the project files libecwj2-win32-shared.dsp and libecwj2_win32_net_shared.vcproj.  These projects generate the libecwj2.lib import library in $INSTALL/lib and the libecwj2.dll DLL in $INSTALL/bin.

If you experience problems building the SDK, it is suggested you build against the latest Microsoft Platform SDK (specifying the Platform SDK include and lib directories at the top of your global include and linker search paths) to minimize any compatibility or linking problems.

To build the examples on Windows, open and build the project .dsp or .vcproj files in each example's directory after building the libecwj2 projects.  The examples are identified as linking statically or dynamically against libecwj2 in their filenames.  You will need to specify the release or debug configuration of each example depending on which configuration of the libecwj2 projects has been built.

NOTE: due to a limitation in qmake it may be necessary to specify /SUBSYSTEM:CONSOLE instead of /SUBSYSTEM:WINDOWS in the .NET 2003 sample projects in order for them to build correctly (some of the examples can report an unresolved symbol _WinMain16 in other cases).  This can be done using the IDE's Project|Properties|Linker|Command Line dialog.
	
* SOLARIS, LINUX and MAC OS X

To build the single static libecwj2 library follow these instructions:

-	Open a shell
- 	Change directory to $INSTALL/Source/NCSBuildQmake
- 	Invoke
		make -f Makefile-<platform>-static 
	where <platform> is the name of your OS, e.g. "linux".
-	The target directory is $INSTALL/Source/lib/<platform>/static

To build the single shared libecwj2 library do the same things substituting "shared" for "static" where applicable.

To build the examples against libecwj2 (static or shared) use make -f with the appropriate makefile located in the example project directory (e.g. $INSTALL/examples/decompression/example1).  The examples should be configured to link against the previously built libecwj2 projects automatically.

The target directory for the example code is $INSTALL/bin.  Example binaries are named according to the convention (C|D)Example(n)[S][d], where C and D distinguish between examples of ECW and JPEG 2000 compression and decompression respectively, n is the example number, and an S indicates the binary is statically linked.  For example, DExample1S is the statically linked version of decompression example 1.  To learn more about the example programs and the SDK features that they demonstrate, look at the PDF manual that ships with the ECW JPEG 2000 SDK and the sample code itself (updates to this text will be forthcoming).

NOTE: The Mac OS X build currently has a dependency on the Carbon development libraries.

COMPILING: NOTES FOR NCSEcw, NCScnet AND NCSUtil

* WINDOWS

When building the separate libraries under Windows $INSTALL/SOURCE/include needs to be added to your environment's include path, and the $INSTALL/LIB directory needs to be added to your environments library search path.  Consult your relevant compiler/linker documentation for details.

In general, it is strongly recommended that you reduce potential build problems on Windows by installing the Microsoft Platform SDK.

* Windows Visual Studio 6

Load the NCSEcw Workspace from Source/C/NCSEcw/NCSEcw.  To build DLLs, make NCSEcwC_SDK the active project and build the appropriate configuration (Debug/Release on 32bit, Debug64/Release64 for AMD64/EM64T).  NOTE: To build the MMX/SSE optimised code you need either:

- "Microsoft Processor Pack", available for free from http://msdn.microsoft.com/vstudio/downloads/tools/ppack/download.aspx, or
- Platform SDK compiler, available for free from http://www.microsoft.com/msdownload/platformsdk/sdkupdate (latest Windows Server 2003 version required for the AMD64/EM64T 64bit compiler)

It is important to note that the Processor Pack is incompatible with Visual Studio 6.0 Service Pack 6.  To build the SDK using Visual Studio 6 and the Processor Pack with MMX/SSE optimisations enabled, you should wind back Service Pack 6 if you have it installed.

If you do not wish to utilise the MMX/SSE optimisations, remove the NCSJPC_X86_MMI and NCSJPC_X86_MMI_MMX definitions from Source/include/NCSJPCDefs.h. 

* Windows Visual Studio.NET 2003

Load the NCSEcw Solution from SOurce/C/NCSEcw/NCSEcw.  To build DLLs, make NCSEcwC_SDK the active project and build the appropriate configuration (Debug/Release on 32bit, Debug64/Release64 for AMD64/EM64T).  NOTE: To build the AMD64/EM64T configuration, you need the latest Windows Server 2003 PLatform SDK compiler, available for free from http://www.microsoft.com/msdownload/platformsdk/sdkupdate.

* Windows build: Java dependency

The ECW JPEG 2000 SDK includes some JNI material which creates a dependency on the J2SDK in the win32 build.  To remove this dependency this material has been removed from the default build files supplied with the SDK.  You can add the files ecw_jni.c and ecw_jni_config.c to the "Source Files" listing for the projects NCSEcw.dsp and NCSEcw_Static.dsp, or to NCSEcw.vcproj and NCSEcw_Static.vcproj if you are using Visual Studio .NET 2003, and add valid Java SDK include and lib paths to your global search paths to restore this material to the build.  The JNI support is not required for the majority of uses of the SDK and has not been thoroughly QA'd for this release.

* Windows build: WinHTTP dependency

The SDK's HTTP support on Windows uses Windows HTTP Services (WinHTTP).  This was formerly available (version 5.0) as a standalone SDK from Microsoft, but support has been discontinued for the standalone SDK since version 5.1, which is available as part of the Microsoft Platform SDK.  Missing WinHTTP from your system is usually flagged when you receive an error message about the compiler being unable to find the file "winhttp.h".  If this is the case it is suggested that you obtain a copy of the Platform SDK to build against.

* Windows Static libraries

When using the static libraries on windows, you need to link with the following libraries; "NCSEcws.lib NCScnets.lib NCSUtils.lib version.lib imagehlp.lib shlwapi.lib Crypt32.lib wsock32.lib".  The default static library project settings link to the "Multithreaded" static runtime.

* SOLARIS, LINUX, and MAC OS X

You can build release or debug versions of the separate NCSEcw, NCScnet, NCSUtil and NCSEcwC libraries by running the script at $INSTALL/Source/NCSNightlyBuild/NCSNightlyBuildUnix.ksh.  Before running this script, you must set the environment variable $NCSTOP to equal the main directory of your unzipped copy of the SDK source archive.  You also need to edit the value of $NCSTOP specified at the top of the script, and if you are using a shell other than ksh (for example, bash) you should edit the "shebang" line approriately.

In summary, to build the NCSEcw, NCScnet, NCSUtil and NCSEcwC libraries on Solaris, Linux or MacOSX:

- unzip the SDK source archive to a directory on your machine
- open a shell
- set the value of $NCSTOP in your environment, e.g. "export NCSTOP=~/dev/ecwsdk"
- change directory to $NCSTOP/Source/NCSNightlyBuild
- use your editor of choice to synchronise the value of $NCSTOP in the script NCSNightlyBuildUnix.kshwith your installation directory
- edit the "shebang" line of the script if necessary
- run ./NCSNightlyBuildUnix.ksh specifying an output target, e.g. "debug" or "release" as an argument

The shared libraries are built in the target directory $INSTALL/bin/<platform> where <platform> is your operating system - usually "solaris", "linux" or "macosx".

* OTHER PLATFORMS

WindowCE/PocketPC EVC3 workspace and project files are included in this distribution, however they are currently unsupported.  The makefiles can be used to build the libraries on Linux using GCC, however this is currently unsupported.


DOCUMENTATION

High-level documetation is available in the SDK.pdf file, which is also included in the binary distributions.  This PDF document contains tips and tricks, example code with discussion, and a reasonably complete API reference.  If you have not worked with the ECW JPEG 2000 SDK before, this is a good entry point to use to gain an understanding of the API and its associated development paradigms.

HTML doxygen generated documentation is available for the main objects and routines in the NCSEcw library, accessed via Source/C/NCSEcw/NCSEcw/html/index.htm.  Note that a considerable amount of low-level and design documentation is currently missing from the distribution.  This will be made available over upcoming releases as it is converted to doxygen format.


SUPPORT

The source code distribution is not officially supported.  However, we will endeavour to provide support when and where possible.  You can post queries in the SDK section of the public ER Mapper forums at forums.ermapper.com where you may receive a reply.  Commercial SDK licensees will receive support via the existing SDK support channel.


JPEG 2000 CONFORMANCE

ER Mapper makes no guarantee that libraries built from the source distribution will be compliant with the JPEG 2000 Part 1 specification.  Users are encouraged to validate the SDK against the Part 4 compliance test to ensure full compliance.  ER Mapper does provide fully compliant binary distributions for certain platforms at no charge, see the www.ermapper.com website for details.

KNOWN PROBLEMS AND LIMITATIONS

This source code distribution is (still) not in final release and has some known problems.

These include:
	-	Carbon dependency in the Mac OS X build
	-	lack of a convenient, unified method for building debug versions of the libraries
	-	improvements needed to documentation across the board

The ECW JPEG 2000 SDK is an open source project and ER Mapper welcomes and encourages feedback from developers using the source code.  If you have found a problem in the SDK, or fixed a problem, or ported the code to another operating system, we would value your feedback highly.  Contact ER Mapper Development Support with any new information or questions: email devsupport@ermapper.com, or use the beta feedback form available online at www.ermapper.com.



