L_Jp2FragmentJpxFile

#include "l_bitmap.h"

L_LTJP2_API L_INT EXT_FUNCTION L_Jp2FragmentJpxFile(hJp2, pInFileName, pOutFileName, pURLs, uNumOfURLs, pFragments, uNumOfFrgm)

L_HJP2 hJp2;	/* JPEG 2000 engine handle */
L_TCHAR * pInFileName;	/* input file name */
L_TCHAR * pOutFileName;	/* output file name */
pL_JP2_UUID_URL_BOX pURLs;	/* pointer to an array of UUID URL boxes */
L_UINT32 uNumOfURLs;	/* size of the URL array */
pL_JP2_FRAGMENT pFragments;	/* pointer to an array of fragment */
L_UINT32 uNumOfFrgm;	/* size of fragment array */

Fragments specified codestreams within a JPEG 2000 part 2 JPX file.

Parameter	Description
hJp2	JPEG 2000 engine handle that was created by the L_Jp2Create function.
pInFileName	Character string that contains the name of the JPEG 2000 part 2 JPX file to extract frames from it.
pOutFileName	Character string that contains the name of the fragmented JPEG 2000 part 2 JPX file.
pURLs	Array of UUID URL boxes specify the file in which the fragments are contained.
uNumOfURLs	Number of URL boxes, this value specifies the size of the pURLs.
pFragments	Pointer to an array of fragments specify for each fragment: the codestream index to be fragmented, the index of URL in which fragment is contained, and the offset of the first byte of the fragment within the URL specified.
uNumOfFrgm	Size of pFragments.

Returns

SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

Comments

If a JPX file already has fragments, the function returns: ERROR_INV_PARAMETER.

If the file is not in JPX format the function returns: ERROR_FILE_FORMAT.

You must save the specified codestreams in the URLs provided in pURLs. The codestream must be saved entirely in that URL.

Fragmentation in JPX works by specifying a table of pointers to the individual fragments. Each pointer specifies three things:

1.	The file in which the fragment is contained. Because multiple fragments across multiple codestreams may be stored in the same file, the format encapsulates all filename/URL data into a table (the Data Reference box). Each fragment specification then references an entry in the data reference table.
2.	The offset of the first byte of the fragment within the file specified. This offset is with respect to the first byte of the file (byte 0) and points directly to the first byte of codestream data for the fragment; it does not point to the start of a box containing that fragment.
3.	The length of the fragment, in bytes.

Fragmentation is an important feature of the JPX file format since it allows applications to implement such features as:

Edit an image, resaving the changed tiles to the end of the file.
Distribute the image across several disks for faster access.
Distribute the image across the internet, allowing only certain customers access to the high quality or high resolution portions of the codestream.
Reuse of the headers from within a codestream across multiple codestreams (to minimize file overhead when storing similar codestreams witin the same JPX file).

Required DLLs and Libraries

LTJP2
LFJ2K
LTIMGEFX

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Win32, x64.

See Also

Functions:	L_Jp2ExtractFramesBuffer, L_Jp2ExtractFrames, L_Jp2AppendFrames, L_Jp2AppendGMLData, L_Jp2ReadBox, L_Jp2ReadGMLData, L_Jp2ReadFrames
Topics:	Programming with JPEG 2000 Features Raster Image Functions: Working with JPEG 2000

Example

This example fragments a JPX file.

L_LTJP2TEX_API L_INT Jp2FragmentJpxFileExample(L_VOID)
{
   L_HJP2 hEngine;
   L_JP2_FILEINFO Jp2FileInfo;
   L_TCHAR pUrlString[L_MAXPATH];
   lstrcpy(pUrlString,MAKE_IMAGE_PATH(TEXT("codestream.bin")));
   L_JP2_UUID_URL_BOX pURL[1];
   L_JP2_FRAGMENT pFragment[1];

   /*Create JPEG  2000 engine handle*/
   hEngine = L_Jp2Create();

   Jp2FileInfo.uStructSize = sizeof(L_JP2_FILEINFO);
   L_Jp2GetFileInfo(hEngine, MAKE_IMAGE_PATH(TEXT("image1.jpx")),&Jp2FileInfo);
   if(Jp2FileInfo.MPEG7.uNumOfBoxes == 0)
      return 0;

   if(Jp2FileInfo.CodeStream.uNumOfBoxes < 2)
      return 0;

   if(Jp2FileInfo.DataRef.uNumOfBoxes)
      return 0;

   pURL[0].uStructSize = sizeof(L_JP2_UUID_URL_BOX);
   pURL[0].pFLAG[0] = 0;
   pURL[0].pFLAG[1] = 0;
   pURL[0].pFLAG[2] = 0;
   pURL[0].uVERS    = 0;
   pURL[0].pLOC = (L_UINT8*)pUrlString;
   pURL[0].uLOCSize = (lstrlen(pUrlString)+1)*sizeof(L_TCHAR);

   /*Fragment the second codestream*/
   pFragment[0].uStructSize = sizeof(L_JP2_FRAGMENT);
   pFragment[0].uCodeStreamIndex = 1;
   pFragment[0].uOffset = 0;
   pFragment[0].uUrlIndex = 0;

   L_Jp2FragmentJpxFile(hEngine, MAKE_IMAGE_PATH(TEXT("image1.jpx")), MAKE_IMAGE_PATH(TEXT("Test.jpx")), pURL,1,pFragment,1);

   /*Free File Info structure*/
   L_Jp2FreeFileInfo(hEngine, &Jp2FileInfo);
   /*Destroy engine handle*/
   L_Jp2Destroy(hEngine);
   return SUCCESS;
}