Intel IJL 简明操作.doc

第一章 准备一、需要以下的三个库1. IJL 动态链接库 (IJL15.DLL),2. IJL 引入库 (IJL15.LIB), 3. IJL 头文件 (IJL.H).二、建立IJL应用程序的步骤1. 在每一个将调用IJL函数的模块中包含头文件IJL.H2. 在项目中增加IJL15.LIB3. 编译程序。第二章 结构描述现在最多的JPEG模式是基本基线模式和扩展基线模式的连续离散余弦变换。IJL1.5完全支持这两种模式的编码及解码,一、IJL 的I/O数据结构体系1. 内存中含有一个常规的象素buffer.2. 一个标准的I/O文件包含JPEG bit stream.3. 一个内存buffer包含一个JPEG bit stream.二、支持的数据格式1、 Top-down or bottom-up pixel buffers.在Windows中, device-independent bitmaps (DIBs) 数据在内存中有两种排列方式 bottom-up and top-down。bottom-up DIB, buffer 是从最底行的最左象素开始, 接着是次底行. 而顶行的数据是在buffer 的最后。GDI 使用的Bottom-up DIB。top-down DIB的排列顺序是颠倒的. 最顶行最左侧的象素是buffer的第一个字节，而最底行的象素在buffer的最后。DirectDraw使用top-down DIBs。RGB DIBs, 图象的排列方式由 /en-us/library/ms779712.aspxBITMAPINFOHEADER结构的成员变量 biHeight 来指示。如 biHeight 是正数, 图象是bottom-up. 如果 biHeight是负数, 图象是top-down。YUV 格式的DIBs 总是top-down, biHeight 的符号被忽略。2、象素缓冲区与自定义行尾填充。3、使用普通象素缓冲之内的一个矩形。4、从一个大的JPEG 图象中指定矩形解码。5、JPEG文件交换格式(JFIF) 的编码和解码IJL 提供JFIF files 的解码，JFIF 规格版本是1.01 and 1.02。编码是JFIF version 1.01.。IJL 也支持解码嵌入式的未压缩的缩略图，使用1 or 3 bytes/pixel 适应JFIF versions 1.01 and 1.02. 压缩的缩略图未被支持。数据精度必须是每颜色通道 8-bits。三、JPEG属性和数据存贮IJL 的 “JPEG 属性” 包括全局的和图象属性的JPEG 信息。控制结构确定I/O 特性的处理选项，象二次抽样和颜色转换需求。IJL 使用 JPEG_CORE_PROPERTIES 结构存放 JPEG 属性数据。这个结构被描述为两个部分，第一部份由一组封包的共用库参数组成，另一部份由低级的嵌入的结构组成。Figure 3-2 与 附件B - Data Structure and Type Definitions).用户必须尊循以下的两个JPEG_CORE_PROPERTIES规则：1. 用户必须提供(allocate) JPEG_CORE_PROPERTIES 数据结构。2. 同样的 JPEG_CORE_PROPERTIES 数据结构可能被一连串的JPEG encodings 和/或decodings 在初始化时和清理时再生。JPEG_PROPERTIES 是低级的数据结构且它包含一个在JPEG_CORE_PROPERTIES 中每个高级数据结构的复本及一些附加字段。IJL内部使用JPEG_PROPERTIES, 而不是JPEG_CORE_PROPERTIES, 所以这个结构隔离了内部的变量。对于高级用户JPEG_PROPERTIES 数据结构可能会使用一些扩充的接口性能。例如：用户可能要自定义的Huffman 表或 量化表（quantization tables） 直接至JPEG_PROPERTIES， 而越过默认表（Chapter 7, Advanced IJL Features 有更多的信息)。JPEG_CORE_PROPERTIES and JPEG_PROPERTIES数据结构的默认值在头文件IJL.H中的注释中四、多线程支持JPEG_CORE_PROPERTIES 被设计在局部为单线程。是 “ 锁定 ” 的无参数将允许多个线程访问相同的 JPEG_CORE_PROPERTIES 结构。 但是，所有的实现细节，IJL 允许多个 JPEG_CORE_PROPERTIES 存储和代码访问由多个线程。第三章 接口详述IJL 提供标准C的函数，其模仿简单的读/写栈来建立JPEG_CORE_PROPERTIES数据结构。JPEG_CORE_PROPERTIES 的内部函数负责初始化、释放内存，及与IJL交换数据及参数。IJL函数调用失败时返回一个错误码；调用成功返回的是正的(IJL_OK, IJL_INTERRUPT_OK, IJL_ROI_OK) 成功码。了解详情参看 Appendix B - Data Structure and Type Definitions。 转换错误码至一个文本描述，使用函数 ijlErrorStr()。函数 ijlGetLibVersion() 返回IJL库的版本及其它相关信息。注意，ijlErrorStr()和ijlGetLibVersion() 函数返回的是一个指向静态变量的指针，所以应用程序不需要释放这些指针。The Intel JPEG Library Application Programming Interface/ 初始化 IJL.IJLERR ijlInit (JPEG_CORE_PROPERTIES *jcprops);/ Clean up the IJL.IJLERR ijlFree (JPEG_CORE_PROPERTIES *jcprops);/ Use the IJL to read data from a buffer or a file.IJLERR ijlRead (JPEG_CORE_PROPERTIES *jcprops, IJLIOTYPE iotype);/ Use the IJL to write data into a buffer or a file.IJLERR ijlWrite (JPEG_CORE_PROPERTIES *jcprops, IJLIOTYPE iotype);/ Return the version number of the IJL.const IJLibVersion* ijlGetLibVersion( );/ Return a pointer to a string with error description.const char* ijlErrorStr(IJLERR code);此段描述设计及执行一些IJL的共用特性，及一些例子。一、初始化在使用之前，IJL必须初始化，使用ijlInit( )完成初始化。在每一个分配JPEG_CORE_PROPERTIES 数据结构的时候，只能进行一次初始化。如果一个程序需要调用多个编、解码函数，应用程序需要在任一调用之前调用ijlInit( )更多的初始化需要在每个编、解码调用之间进行。 使用ijlFree( )释放 JPEG_CORE_PROPERTIES 且必须与初始化一一对应。二、释放用ijlFree( )释放内存及相关的系统资源。三、读数据使用ijlRead(JPEG_CORE_PROPERTIES *jcprops, IJLIOTYPE iotype)函数访问JPEG的压缩数据。第二个参数用来指定在解码期间的JPEG的数据单元（如：一个文件或一个缓存区），访问模式（mode of access）,及缩放比例。有如下两种约定：XXXX 代表访问模式1. IJL_JBUFF_XXXX (表示JPEG数据是一个缓存).2. IJL_JFILE_XXXX(表示JPEG数据是一个标准文件).读数据时，访问模式必须是： READPARAMS, READHEADER，READENTROPY, READWHOLEIMAGE,，READONEHALF， READONEQUARTER，READONEEIGHTH， READTHUMBNAIL。 IJLIOTYPE描述IJL_JXXXX_READPARAMS表示读JPEG 参数 如：高，宽，通道数量，二次抽样等。,例如如下的分析：SOI | tables/misc like APPn and DQT |SOF | tables/misc like DHT | stops at SOSNote: bit stream must start with SOI marker.IJL_JXXXX_READHEADER表示读一些特征数据，如：霍夫曼表，量化表，其它杂项。例如：SOI | tables/misc | EOI (or stops at SOF or SOS)Note: bit stream must start with SOI marker.IJL_JXXXX_READENTROPY表示读压缩图片的格式。与 READWHOLEIMAGE相同，除了位流可能包含的特征表。.For example：SOI | tables/misc | SOF tables/misc like DHT | SOS | EOINote: in this case only (READENTROPY), APP0 segments are skipped over.IJL_JXXXX_READWHOLEIMAGE表示读压缩图片数据的交换格式，如：整个的JPEG位流。例如：SOI | tables/misc like APPn and DQT |SOF tables/misc like DHT | SOS | EOIIJL_JXXXX_READONEHALF图象解码比例是(See READENTROPY).IJL_JXXXX_READONEQUARTER图象解码比例是. (See READENTROPY).IJL_JXXXX_READONEEIGHTH图象解码比例是1/8 (See READENTROPY).IJL_JXXXX_READTHUMBNAIL试图解码在数据流中嵌入的缩略图(See READPARAMS).READPARAMS 被用来确定JPEG 的高和宽，用以分配输出的缓存或显示引擎。然后，读其余的数据使用 READWHOLEIMAGE or READENTROPY。READHEADER 被用于分析压缩数据规格表，之后使用READENTROPY 来得到压缩的图象数据。READHEADER/READENTROPY 参数对是一个最优的读取JPEG解码格式的方案。When decoding a JPEG bit streamthe following markers, and their corresponding segments if applicable, are not processed by the IJL (i.e.,they are skipped over): APPn (except APP0 and APP14), DAC,DHP, DNL, EXP, JPGn, RES, SOFn (except SOF0, SOF1, and SOF2), and TEM. Any SOFn markers (except SOF0, SOF1, and SOF2) will cause the IJL_UNSUPPORTED_FRAME error.四、写数据ijlWrite(JPEG_CORE_PROPERTIES *, IJLIOTYPE iotype) 是写入数据的接口函数。第二个参数是访问方式，但不能指定图象的比例及嵌入式缩略图。1. IJL_JBUFF_XXXX (指定 JPEG 压缩数据的内存缓存区).2. IJL_JFILE_XXXX (指定 JPEG 数据的文件).写入数据时，访问方式必须是WRITEHEADER, WRITEENTROPY, or WRITEWHOLEIMAGE。详细描述见下表：IJLIOTYPE 描述IJL_JXXXX_WRITEHEADER指定数据流的压缩格式规格表。下面的标志将被写入：SOI | tables DQT and DHT | EOIIJL_JXXXX_WRITEENTROPY指定压缩图片数据。与 WRITEWHOLEIMAGE 相同，只是不包含规格表数据。下面的标志将被写入：SOI | SOF | DRI | SOS | EOIIJL_JXXXX_WRITEWHOLEIMAGE指定写入JPEG 文件交换格式（如：JPEG using JFIF).下面的标志将被写入：SOI | tables/misc APP0, DQT, DHT | SOF | DRI | SOS | EOIWRITEHEADER 通常被用于写入压缩格式规格表，它与WRITEENTROPY 一般成对使用于JPEG编码。当编码时，IJL 写入COM 标志片段，如果未指定该片段， 将写入默认的“Intel JPEG Library, ”。五、打开一个 JPEG 图片普通的解码算法：1. 分配 JPEG_CORE_PROPERTIES2. 初始化 IJL.3. 得到JPEG 图象尺寸及其它4. 设置显示参数，分配输出缓存.5. 得到JPEG数据6. 关闭IJL下面的代码使用 IJL 解码一个JPEG图象文件。请参照 Appendix B - Data Structure and Type Definitions 以得到IJL数据结构的定义，默认值，数据类型定义和错误码的详细的信息。/-/ An example using the IntelR JPEG Library:/ - Decode a JPEG image from a JFIF file to general pixel buffer./-BOOL DecodeJPGFileToGeneralBuffer( LPCSTR lpszPathName, DWORD* width, DWORD* height, DWORD* nchannels, BYTE* buffer)BOOL bres; /return ValueIJLERR jerr;DWORD x = 0; / pixels in scan lineDWORD y = 0; / number of scan linesDWORD c = 0; / number of channelsDWORD wholeimagesize;BYTE* pixel_buf = NULL;/ Allocate the IJL JPEG_CORE_PROPERTIES structure.JPEG_CORE_PROPERTIES jcprops;bres = TRUE;_try/ Initialize the IntelR JPEG Library.jerr = ijlInit(&jcprops);if(IJL_OK != jerr)bres = FALSE;_leave;/ Get information on the JPEG image(i.e., width, height, and channels).jcprops.JPGFile = const_cast(lpszPathName);jerr = ijlRead(&jcprops, IJL_JFILE_READPARAMS);if(IJL_OK != jerr)bres = FALSE;_leave;/ Set up local data.x = jcprops.JPGWidth;y = jcprops.JPGHeight;c = 3; / Decode into a 3 channel pixel buffer./ Compute size of desired pixel buffer.wholeimagesize = (x * y * c);/ Allocate memory to hold the decompressed image data.pixel_buf = new BYTE wholeimagesize;if(NULL = pixel_buf)bres = FALSE;_leave;/ Set up the info on the desired DIB properties.jcprops.DIBWidth = x;jcprops.DIBHeight = y; / Implies a bottom-up DIB.jcprops.DIBChannels = c;jcprops.DIBColor = IJL_BGR;jcprops.DIBPadBytes = 0;jcprops.DIBBytes = pixel_buf;/ 设置JPG 色彩空间 这总是有一些推策，因为JPEG是个“色盲”/（也就是说位流中没有告诉你是什么色彩空间）设置JPEG色彩空间，/ 本例中我们假定JFIF图象文件是3个通道YCbCr 色彩空间和1 个通道的Y 色彩空间.switch(jcprops.JPGChannels)case 1:jcprops.JPGColor = IJL_G;break;case 3:jcprops.JPGColor = IJL_YCBCR;break;default:/ This catches everything else, /but no color twist will be performed by the IJL.jcprops.DIBColor = (IJL_COLOR) IJL_OTHER;jcprops.JPGColor = (IJL_COLOR) IJL_OTHER;break;/ Now get the actual JPEG image data into the pixel buffer.jerr = ijlRead(&jcprops, IJL_JFILE_READWHOLEIMAGE);if(IJL_OK != jerr)bres = FALSE;_leave; / _try_finallyif(FALSE = bres)if(NULL != pixel_buf)delete pixel_buf;pixel_buf = NULL;/ Clean up the IntelR JPEG Library.ijlFree(&jcprops);*width = x;*height = y;*nchannels = c;*buffer = pixel_buf; / _finallyreturn bres; / DecodeJPGFileToGeneralBuffer()注意：这段代码是解码一个JPEG图象到一个“常规的象素缓存”因而这个缓存不是专用的。前面讲过，Chapter 3, Architecture Description, IJL 被设计为工作于普通的缓存, 需要用户自行处理缓存的分配及数据保存，IJL负责读或写缓存。缓存的地址通过IJL的JPEG_CORE_PROPERTIES 结构中DIBBytes 字段来传递。本例中用户要解码到一个Windows* DIB, 这个缓存的尺寸计算可能会是错误的，如果用户需要确保一个Windows DIB 的4字节队列的缓存，可以使用包含在 ijl.h 头文件中的 IJL_DIB_PAD_BYTES 宏，这个宏定义是：#define IJL_DIB_PAD_BYTES(width, nchannels) ( ( (width * nchannels ) + (sizeof(DWORD) - 1) ) & (sizeof(DWORD) - 1) ) - (width * nchannels) )相应的 DIBPadBytes 的值能够容易的计算：jcprops.DIBPadBytes = IJL_DIB_PAD_BYTES (width, nchannels)其中 width 是图象的象素宽度，nchannels 是通道的数量。下面的代码举例说明如何从一个图象解码到一个 Windows DIB./-/ An example using the IntelR JPEG Library:/ - Decode a JPEG image from a JFIF file to Windows DIB./-BOOL DecodeJPGFileToDIB(LPCSTR lpszPathName,BITMAPINFOHEADER* dib)BOOL bres;IJLERR jerr;DWORD width;DWORD height;DWORD nchannels;DWORD dib_line_width;DWORD dib_pad_bytes;DWORD wholeimagesize;BYTE* buffer = NULL;BITMAPINFOHEADER* bmih = NULL;/ Allocate the IJL JPEG_CORE_PROPERTIES structure.JPEG_CORE_PROPERTIES jcprops;bres = TRUE;_try/ Initialize the IntelR JPEG Library.jerr = ijlInit(&jcprops);if(IJL_OK != jerr)bres = FALSE;_leave;/ Get information on the JPEG image/ (i.e., width, height, and channels).jcprops.JPGFile = const_cast(lpszPathName);jerr = ijlRead(&jcprops,IJL_JFILE_READPARAMS);if(IJL_OK != jerr)bres = FALSE;_leave;/ Set up local data.width = jcprops.JPGWidth;height = jcprops.JPGHeight;nchannels = 3; / Decode into a 3 channel pixel buffer./ Compute DIB 填充dib_line_width = width * nchannels;dib_pad_bytes = IJL_DIB_PAD_BYTES(width,nchannels);/ Compute size of desired pixel buffer.wholeimagesize = ( dib_line_width + dib_pad_bytes ) * height;/ Allocate memory to hold the decompressed image data.buffer = new BYTE sizeof(BITMAPINFOHEADER) + wholeimagesize;if(NULL = buffer)bres = FALSE;_leave;bmih = reinterpret_cast(buffer);bmih-biSize = sizeof(BITMAPINFOHEADER);bmih-biWidth = width;bmih-biHeight = height;bmih-biPlanes = 1;bmih-biBitCount = 24;bmih-biCompression = BI_RGB;bmih-biSizeImage = 0;bmih-biXPelsPerMeter = 0;bmih-biYPelsPerMeter = 0;bmih-biClrUsed = 0;bmih-biClrImportant = 0;/ Set up the info on the desired DIB properties.jcprops.DIBWidth = width;jcprops.DIBHeight = height; / Implies a bottom-up DIB.jcprops.DIBChannels = nchannels;jcprops.DIBColor = IJL_BGR;jcprops.DIBPadBytes = dib_pad_bytes;jcprops.DIBBytes = reinterpret_cast(buffer +sizeof(BITMAPINFOHEADER);/ Set the JPG color space . this will always be/ somewhat of an educated guess at best because JPEG/ is color blind (i.e., nothing in the bit stream/ tells you what color space the data was encoded from)./ However, in this example we assume that we are/ reading JFIF files which means that 3 channel images/ are in the YCbCr color space and 1 channel images are/ in the Y color space.switch(jcprops.JPGChannels)case 1:jcprops.JPGColor = IJL_G;break;case 3:jcprops.JPGColor = IJL_YCBCR;break;default:/ This catches everything else, but no/ color twist will be performed by the IJL.jcprops.DIBColor = (IJL_COLOR)IJL_OTHER;jcprops.JPGColor = (IJL_COLOR)IJL_OTHER;break;/ Now get the actual JPEG image data into the pixel buffer.jerr = ijlRead(&jcprops,IJL_JFILE_READWHOLEIMAGE);if(IJL_OK != jerr)bres = FALSE;_leave; / _try_finallyif(FALSE = bres)if(NULL != buffer)delete buffer;buffer = NULL;/ Clean up the IntelR JPEG Library.ijlFree(&jcprops);*dib = bmih; / _finallyreturn bres; / DecodeJPGFileToDIB()六、建立JPEG图象此段代码针对普通的JPEG图象：1. 初始化 IJL.2. 设置编码参数(如果与默认值不同).3.写图象数据给IJL.4. 关闭 IJL.下面的代码段举例说明如何使用IJL从一个JFIF图象缓存编码。请参照 Appendix B - Data Structure and Type Definitions 查看更多有关数据结构等信息。/-/ An example using the IntelR JPEG Library:/ - Encode a JFIF file from Windows DIB./-BOOL EncodeJPGFileFromDIB( LPCSTR lpszPathName, BITMAPINFOHEADER* bmih)BOOL bres;IJLERR jerr;DWORD dib_pad_bytes;/ Allocate the IJL JPEG_CORE_PROPERTIES structure.JPEG_CORE_PROPERTIES jcprops;bres = TRUE;_try/ Initialize the IntelR JPEG Library.jerr = ijlInit(&jcprops);if(IJL_OK != jerr)bres = FALSE;_leave;if(bmih-biBitCount != 24)/ not supported palette imagesbres = FALSE;_leave;dib_pad_bytes = IJL_DIB_PAD_BYTES(bmih-biWidth,3);/ Set up information to write from the pixel buffer.jcprops.DIBWidth = bmih-biWidth;jcprops.DIBHeight = bmih-biHeight; / Implies a bottom-up DIB.jcprops.DIBBytes = reinterpret_cast(bmih) +sizeof(BITMAPINFOHEADER);jcprops.DIBPadBytes = dib_pad_bytes;/ Note: the following are default values and thus/ do not need to be set.jcprops.DIBChannels = 3;jcprops.DIBColor = IJL_BGR;jcprops.JPGFile = const_cast(lpszPathName);/ Specify JPEG file creation parameters.jcprops.JPGWidth = bmih-biWidth;jcprops.JPGHeight = bmih-biHeight;/ Note: the following are default values and thus/ do not need to be set.jcprops.JPGChannels = 3;jcprops.JPGColor = IJL_YCBCR;jcprops.JPGSubsampling = IJL_411; / 4:1:1 subsampling.jcprops.jquality = 75; / Select good image quality/ Write the actual JPEG image from the pixel buffer.jerr = ijlWrite(&jcprops,IJL_JFILE_WRITEWHOLEIMAGE);if(IJL_OK != jerr)bres = FALSE;_leave; / _try_finally/ Clean up the IntelR JPEG Library.ijlFree(&jcprops);return bres; / EncodeJPGFileFromDIB()七、中断编码或解码IJL 可以在编码和解码时中断，它可以被 JPEG_PROPERTIES 中定义的中断标志在任一时间中断。IJL将在完成当前的最小编码单位（MCU）时返回状态标志 IJL_INTERRUPT_OK。编解码过程也可以在原位恢复执行，只需使用ijlRead( ) 或 ijlWrite( ) 函数即可恢复。用户可以通过JPEG_PROPERTIES 中的 roi IJL_RECT 结构的left 和 top 变量计算出定位。下面的例子中，程序读一个JPEG数据中的最小片段至指定的缓存区，然后程序返回并重复这个过程，直到整个图象被解码完成。这个函数可以用做定时的中止JPEG的编解码过程。/-/ An example using the IntelR JPEG Library:/ - Interrupted decoding./-/ In this example, we are doing full scale decoding./ It could also be any of the scaled decoding modes.BOOL DecodeJPGFileInterrupted(LPCSTR lpszPathName)BOOL bres;IJLERR jerr;DWORD width;DWORD height;DWORD nchannels;DWORD wholeimagesize;BYTE* pixel_buf = NULL;/ Allocate the IJL JPEG_CORE_PROPERTIES structure.JPEG_CORE_PROPERTIES jcprops;bres = TRUE;_try/ Initialize the IntelR JPEG Library.jerr = ijlInit(&jcprops);if(IJL_OK != jerr)bres = FALSE;_leave;jcprops.JPGFile = const_cast(lpszPathName);/ Get information on the JPEG image/ (i.e., width, height, and channels).jerr = ijlRead(&jcprops, IJL_JFILE_READPARAMS);if(IJL_OK != jerr)bres = FALSE;_leave;/ Set up local data.width = jcprops.JPGWidth;height = jcprops.JPGHeight;nchannels = 3; / Decode into a 3 channel pixel buffer./ Compute size of desired pixel buffer.wholeimagesize = (width * height * nchannels);/ Allocate memory to hold the decompressed image data.pixel_buf = new BYTE wholeimagesize;if(NULL = pixel_buf)bres = FALSE;_leave;/ Set up the info on the desired DIB properties.jcprops.DIBWidth = width;jcprops.DIBHeight = height; / Implies a bottom-up DIB.jcprops.DIBChannels = nchannels;jcprops.DIBColor = IJL_BGR;jcprops.DIBPadBytes = 0;jcprops.DIBBytes = pixel_buf;/ Set the JPG color space . this will always be/ somewhat of an educated guess at best because JPEG/ is color blind (i.e., nothing in the bit stream/ tells you what color space the data was encoded from)./ However, in this example we assume that we are/ reading JFIF files which means that 3 channel images/ are in the YCbCr color space and 1 channel images are/ in the Y color space.switch(jcprops.JPGChannels