OpenCores

trunk/docs/itu-t81.pdf Property changes : Deleted: svn:mime-type ## -1 +0,0 ## -application/octet-stream \ No newline at end of property Index: trunk/docs/bmp.txt =================================================================== --- trunk/docs/bmp.txt (revision 4) +++ trunk/docs/bmp.txt (nonexistent) @@ -1,1043 +0,0 @@ -Microsoft Windows Bitmap Format - - - -Note: the constants BI_RGB, BI_RLE8, and BI_RLE4 have the values 0, 1, and 2, - respectively. - -============================================================================= -Graphics File Formats - -This topic describes the graphics-file formats used by the Microsoft Windows -operating system. Graphics files include bitmap files, icon-resource files, -and cursor-resource files. - -Bitmap-File Formats - -Windows bitmap files are stored in a device-independent bitmap (DIB) format -that allows Windows to display the bitmap on any type of display device. The -term "device independent" means that the bitmap specifies pixel color in a -form independent of the method used by a display to represent color. The -default filename extension of a Windows DIB file is .BMP. - -Bitmap-File Structures - -Each bitmap file contains a bitmap-file header, a bitmap-information header, -a color table, and an array of bytes that defines the bitmap bits. The file -has the following form: - -BITMAPFILEHEADER bmfh; -BITMAPINFOHEADER bmih; -RGBQUAD aColors[]; -BYTE aBitmapBits[]; - -The bitmap-file header contains information about the type, size, and layout -of a device-independent bitmap file. The header is defined as a -BITMAPFILEHEADER structure. - -The bitmap-information header, defined as a BITMAPINFOHEADER structure, -specifies the dimensions, compression type, and color format for the bitmap. - -The color table, defined as an array of RGBQUAD structures, contains as many -elements as there are colors in the bitmap. The color table is not present -for bitmaps with 24 color bits because each pixel is represented by 24-bit -red-green-blue (RGB) values in the actual bitmap data area. The colors in the -table should appear in order of importance. This helps a display driver -render a bitmap on a device that cannot display as many colors as there are -in the bitmap. If the DIB is in Windows version 3.0 or later format, the -driver can use the biClrImportant member of the BITMAPINFOHEADER structure to -determine which colors are important. - -The BITMAPINFO structure can be used to represent a combined -bitmap-information header and color table. The bitmap bits, immediately -following the color table, consist of an array of BYTE values representing -consecutive rows, or "scan lines," of the bitmap. Each scan line consists of -consecutive bytes representing the pixels in the scan line, in left-to-right -order. The number of bytes representing a scan line depends on the color -format and the width, in pixels, of the bitmap. If necessary, a scan line -must be zero-padded to end on a 32-bit boundary. However, segment boundaries -can appear anywhere in the bitmap. The scan lines in the bitmap are stored -from bottom up. This means that the first byte in the array represents the -pixels in the lower-left corner of the bitmap and the last byte represents -the pixels in the upper-right corner. - -The biBitCount member of the BITMAPINFOHEADER structure determines the number -of bits that define each pixel and the maximum number of colors in the -bitmap. These members can have any of the following values: - -Value Meaning - -1 Bitmap is monochrome and the color table contains two entries. Each -bit in the bitmap array represents a pixel. If the bit is clear, the pixel is -displayed with the color of the first entry in the color table. If the bit is -set, the pixel has the color of the second entry in the table. - -4 Bitmap has a maximum of 16 colors. Each pixel in the bitmap is -represented by a 4-bit index into the color table. For example, if the first -byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel -contains the color in the second table entry, and the second pixel contains -the color in the sixteenth table entry. - -8 Bitmap has a maximum of 256 colors. Each pixel in the bitmap is -represented by a 1-byte index into the color table. For example, if the first -byte in the bitmap is 0x1F, the first pixel has the color of the -thirty-second table entry. - -24 Bitmap has a maximum of 2^24 colors. The bmiColors (or bmciColors) -member is NULL, and each 3-byte sequence in the bitmap array represents the -relative intensities of red, green, and blue, respectively, for a pixel. - -The biClrUsed member of the BITMAPINFOHEADER structure specifies the number -of color indexes in the color table actually used by the bitmap. If the -biClrUsed member is set to zero, the bitmap uses the maximum number of colors -corresponding to the value of the biBitCount member. An alternative form of -bitmap file uses the BITMAPCOREINFO, BITMAPCOREHEADER, and RGBTRIPLE -structures. - -Bitmap Compression - -Windows versions 3.0 and later support run-length encoded (RLE) formats for -compressing bitmaps that use 4 bits per pixel and 8 bits per pixel. -Compression reduces the disk and memory storage required for a bitmap. - -Compression of 8-Bits-per-Pixel Bitmaps - -When the biCompression member of the BITMAPINFOHEADER structure is set to -BI_RLE8, the DIB is compressed using a run-length encoded format for a -256-color bitmap. This format uses two modes: encoded mode and absolute mode. -Both modes can occur anywhere throughout a single bitmap. - -Encoded Mode - -A unit of information in encoded mode consists of two bytes. The first byte -specifies the number of consecutive pixels to be drawn using the color index -contained in the second byte. The first byte of the pair can be set to zero -to indicate an escape that denotes the end of a line, the end of the bitmap, -or a delta. The interpretation of the escape depends on the value of the -second byte of the pair, which must be in the range 0x00 through 0x02. -Following are the meanings of the escape values that can be used in the -second byte: - -Second byte Meaning - -0 End of line. -1 End of bitmap. -2 Delta. The two bytes following the escape contain unsigned values -indicating the horizontal and vertical offsets of the next pixel from the -current position. - -Absolute Mode - -Absolute mode is signaled by the first byte in the pair being set to zero and -the second byte to a value between 0x03 and 0xFF. The second byte represents -the number of bytes that follow, each of which contains the color index of a -single pixel. Each run must be aligned on a word boundary. Following is an -example of an 8-bit RLE bitmap (the two-digit hexadecimal values in the -second column represent a color index for a single pixel): - -Compressed data Expanded data - -03 04 04 04 04 -05 06 06 06 06 06 06 -00 03 45 56 67 00 45 56 67 -02 78 78 78 -00 02 05 01 Move 5 right and 1 down -02 78 78 78 -00 00 End of line -09 1E 1E 1E 1E 1E 1E 1E 1E 1E 1E -00 01 End of RLE bitmap - -Compression of 4-Bits-per-Pixel Bitmaps - -When the biCompression member of the BITMAPINFOHEADER structure is set to -BI_RLE4, the DIB is compressed using a run-length encoded format for a -16-color bitmap. This format uses two modes: encoded mode and absolute mode. - -Encoded Mode - -A unit of information in encoded mode consists of two bytes. The first byte -of the pair contains the number of pixels to be drawn using the color indexes -in the second byte. - -The second byte contains two color indexes, one in its high-order nibble -(that is, its low-order 4 bits) and one in its low-order nibble. - -The first pixel is drawn using the color specified by the high-order nibble, -the second is drawn using the color in the low-order nibble, the third is -drawn with the color in the high-order nibble, and so on, until all the -pixels specified by the first byte have been drawn. - -The first byte of the pair can be set to zero to indicate an escape that -denotes the end of a line, the end of the bitmap, or a delta. The -interpretation of the escape depends on the value of the second byte of the -pair. In encoded mode, the second byte has a value in the range 0x00 through -0x02. The meaning of these values is the same as for a DIB with 8 bits per -pixel. - -Absolute Mode - -In absolute mode, the first byte contains zero, the second byte contains the -number of color indexes that follow, and subsequent bytes contain color -indexes in their high- and low-order nibbles, one color index for each pixel. -Each run must be aligned on a word boundary. - -Following is an example of a 4-bit RLE bitmap (the one-digit hexadecimal -values in the second column represent a color index for a single pixel): - -Compressed data Expanded data - -03 04 0 4 0 -05 06 0 6 0 6 0 -00 06 45 56 67 00 4 5 5 6 6 7 -04 78 7 8 7 8 -00 02 05 01 Move 5 right and 1 down -04 78 7 8 7 8 -00 00 End of line -09 1E 1 E 1 E 1 E 1 E 1 -00 01 End of RLE bitmap - -Bitmap Example - -The following example is a text dump of a 16-color bitmap (4 bits per pixel): - -Win3DIBFile - BitmapFileHeader - Type 19778 - Size 3118 - Reserved1 0 - Reserved2 0 - OffsetBits 118 - BitmapInfoHeader - Size 40 - Width 80 - Height 75 - Planes 1 - BitCount 4 - Compression 0 - SizeImage 3000 - - XPelsPerMeter 0 - YPelsPerMeter 0 - ColorsUsed 16 - ColorsImportant 16 - Win3ColorTable - Blue Green Red Unused -[00000000] 84 252 84 0 -[00000001] 252 252 84 0 -[00000002] 84 84 252 0 -[00000003] 252 84 252 0 -[00000004] 84 252 252 0 -[00000005] 252 252 252 0 -[00000006] 0 0 0 0 -[00000007] 168 0 0 0 -[00000008] 0 168 0 0 -[00000009] 168 168 0 0 -[0000000A] 0 0 168 0 -[0000000B] 168 0 168 0 -[0000000C] 0 168 168 0 -[0000000D] 168 168 168 0 -[0000000E] 84 84 84 0 -[0000000F] 252 84 84 0 - Image - . - . Bitmap data - . - -Icon-Resource File Format - -An icon-resource file contains image data for icons used by Windows -applications. The file consists of an icon directory identifying the number -and types of icon images in the file, plus one or more icon images. The -default filename extension for an icon-resource file is .ICO. - -Icon Directory - -Each icon-resource file starts with an icon directory. The icon directory, -defined as an ICONDIR structure, specifies the number of icons in the -resource and the dimensions and color format of each icon image. The ICONDIR -structure has the following form: - - - -typedef struct ICONDIR { - WORD idReserved; - WORD idType; - WORD idCount; - ICONDIRENTRY idEntries[1]; -} ICONHEADER; - -Following are the members in the ICONDIR structure: - -idReserved Reserved; must be zero. -idType Specifies the resource type. This member is set to 1. -idCount Specifies the number of entries in the directory. -idEntries Specifies an array of ICONDIRENTRY structures containing -information about individual icons. The idCount member specifies the number -of structures in the array. - -The ICONDIRENTRY structure specifies the dimensions and color format for an -icon. The structure has the following form: - - - -struct IconDirectoryEntry { - BYTE bWidth; - BYTE bHeight; - BYTE bColorCount; - BYTE bReserved; - WORD wPlanes; - WORD wBitCount; - DWORD dwBytesInRes; - DWORD dwImageOffset; -}; - -Following are the members in the ICONDIRENTRY structure: - -bWidth Specifies the width of the icon, in pixels. Acceptable values -are 16, 32, and 64. - -bHeight Specifies the height of the icon, in pixels. Acceptable -values are 16, 32, and 64. - -bColorCount Specifies the number of colors in the icon. Acceptable values -are 2, 8, and 16. - -bReserved Reserved; must be zero. -wPlanes Specifies the number of color planes in the icon bitmap. -wBitCount Specifies the number of bits in the icon bitmap. -dwBytesInRes Specifies the size of the resource, in bytes. -dwImageOffset Specifies the offset, in bytes, from the beginning of the -file to the icon image. - -Icon Image - -Each icon-resource file contains one icon image for each image identified in -the icon directory. An icon image consists of an icon-image header, a color -table, an XOR mask, and an AND mask. The icon image has the following form: - - - -BITMAPINFOHEADER icHeader; -RGBQUAD icColors[]; -BYTE icXOR[]; -BYTE icAND[]; - -The icon-image header, defined as a BITMAPINFOHEADER structure, specifies the -dimensions and color format of the icon bitmap. Only the biSize through -biBitCount members and the biSizeImage member are used. All other members -(such as biCompression and biClrImportant) must be set to zero. - -The color table, defined as an array of RGBQUAD structures, specifies the -colors used in the XOR mask. As with the color table in a bitmap file, the -biBitCount member in the icon-image header determines the number of elements -in the array. For more information about the color table, see Section 1.1, -"Bitmap-File Formats." - -The XOR mask, immediately following the color table, is an array of BYTE -values representing consecutive rows of a bitmap. The bitmap defines the -basic shape and color of the icon image. As with the bitmap bits in a bitmap -file, the bitmap data in an icon-resource file is organized in scan lines, -with each byte representing one or more pixels, as defined by the color -format. For more information about these bitmap bits, see Section 1.1, -"Bitmap-File Formats." - -The AND mask, immediately following the XOR mask, is an array of BYTE values, -representing a monochrome bitmap with the same width and height as the XOR -mask. The array is organized in scan lines, with each byte representing 8 -pixels. - -When Windows draws an icon, it uses the AND and XOR masks to combine the icon -image with the pixels already on the display surface. Windows first applies -the AND mask by using a bitwise AND operation; this preserves or removes -existing pixel color. Windows then applies the XOR mask by using a bitwise -XOR operation. This sets the final color for each pixel. - -The following illustration shows the XOR and AND masks that create a -monochrome icon (measuring 8 pixels by 8 pixels) in the form of an uppercase -K: - -Windows Icon Selection - -Windows detects the resolution of the current display and matches it against -the width and height specified for each version of the icon image. If Windows -determines that there is an exact match between an icon image and the current -device, it uses the matching image. Otherwise, it selects the closest match -and stretches the image to the proper size. - -If an icon-resource file contains more than one image for a particular -resolution, Windows uses the icon image that most closely matches the color -capabilities of the current display. If no image matches the device -capabilities exactly, Windows selects the image that has the greatest number -of colors without exceeding the number of display colors. If all images -exceed the color capabilities of the current display, Windows uses the icon -image with the least number of colors. - - - -Cursor-Resource File Format - -A cursor-resource file contains image data for cursors used by Windows -applications. The file consists of a cursor directory identifying the number -and types of cursor images in the file, plus one or more cursor images. The -default filename extension for a cursor-resource file is .CUR. - -Cursor Directory - -Each cursor-resource file starts with a cursor directory. The cursor -directory, defined as a CURSORDIR structure, specifies the number of cursors -in the file and the dimensions and color format of each cursor image. The -CURSORDIR structure has the following form: - - -typedef struct _CURSORDIR { - WORD cdReserved; - WORD cdType; - WORD cdCount; - CURSORDIRENTRY cdEntries[]; -} CURSORDIR; - -Following are the members in the CURSORDIR structure: - -cdReserved Reserved; must be zero. -cdType Specifies the resource type. This member must be set to 2. -cdCount Specifies the number of cursors in the file. -cdEntries Specifies an array of CURSORDIRENTRY structures containing -information about individual cursors. The cdCount member specifies the number -of structures in the array. - -A CURSORDIRENTRY structure specifies the dimensions and color format of a -cursor image. The structure has the following form: - - - -typedef struct _CURSORDIRENTRY { - BYTE bWidth; - BYTE bHeight; - BYTE bColorCount; - BYTE bReserved; - WORD wXHotspot; - WORD wYHotspot; - DWORD lBytesInRes; - DWORD dwImageOffset; -} CURSORDIRENTRY; - -Following are the members in the CURSORDIRENTRY structure: - -bWidth Specifies the width of the cursor, in pixels. -bHeight Specifies the height of the cursor, in pixels. -bColorCount Reserved; must be zero. -bReserved Reserved; must be zero. -wXHotspot Specifies the x-coordinate, in pixels, of the hot spot. -wYHotspot Specifies the y-coordinate, in pixels, of the hot spot. -lBytesInRes Specifies the size of the resource, in bytes. -dwImageOffset Specifies the offset, in bytes, from the start of the file to -the cursor image. - -Cursor Image - -Each cursor-resource file contains one cursor image for each image identified -in the cursor directory. A cursor image consists of a cursor-image header, a -color table, an XOR mask, and an AND mask. The cursor image has the following -form: - - - -BITMAPINFOHEADER crHeader; -RGBQUAD crColors[]; -BYTE crXOR[]; -BYTE crAND[]; - -The cursor hot spot is a single pixel in the cursor bitmap that Windows uses -to track the cursor. The crXHotspot and crYHotspot members specify the x- and -y-coordinates of the cursor hot spot. These coordinates are 16-bit integers. - -The cursor-image header, defined as a BITMAPINFOHEADER structure, specifies -the dimensions and color format of the cursor bitmap. Only the biSize through -biBitCount members and the biSizeImage member are used. The biHeight member -specifies the combined height of the XOR and AND masks for the cursor. This -value is twice the height of the XOR mask. The biPlanes and biBitCount -members must be 1. All other members (such as biCompression and -biClrImportant) must be set to zero. - -The color table, defined as an array of RGBQUAD structures, specifies the -colors used in the XOR mask. For a cursor image, the table contains exactly -two structures, since the biBitCount member in the cursor-image header is -always 1. - -The XOR mask, immediately following the color table, is an array of BYTE -values representing consecutive rows of a bitmap. The bitmap defines the -basic shape and color of the cursor image. As with the bitmap bits in a -bitmap file, the bitmap data in a cursor-resource file is organized in scan -lines, with each byte representing one or more pixels, as defined by the -color format. For more information about these bitmap bits, see Section 1.1, -"Bitmap-File Formats." - -The AND mask, immediately following the XOR mask, is an array of BYTE values -representing a monochrome bitmap with the same width and height as the XOR -mask. The array is organized in scan lines, with each byte representing 8 -pixels. - -When Windows draws a cursor, it uses the AND and XOR masks to combine the -cursor image with the pixels already on the display surface. Windows first -applies the AND mask by using a bitwise AND operation; this preserves or -removes existing pixel color. Window then applies the XOR mask by using a -bitwise XOR operation. This sets the final color for each pixel. - -The following illustration shows the XOR and the AND masks that create a -cursor (measuring 8 pixels by 8 pixels) in the form of an arrow: - -Following are the bit-mask values necessary to produce black, white, -inverted, and transparent results: - -Pixel result AND mask XOR mask - -Black 0 0 -White 0 1 -Transparent 1 0 -Inverted 1 1 - -Windows Cursor Selection - -If a cursor-resource file contains more than one cursor image, Windows -determines the best match for a particular display by examining the width and -height of the cursor images. - - -============================================================================== - - -BITMAPFILEHEADER (3.0) - - - -typedef struct tagBITMAPFILEHEADER { /* bmfh */ - UINT bfType; - DWORD bfSize; - UINT bfReserved1; - UINT bfReserved2; - DWORD bfOffBits; -} BITMAPFILEHEADER; - -The BITMAPFILEHEADER structure contains information about the type, size, and -layout of a device-independent bitmap (DIB) file. - -Member Description - -bfType Specifies the type of file. This member must be BM. -bfSize Specifies the size of the file, in bytes. -bfReserved1 Reserved; must be set to zero. -bfReserved2 Reserved; must be set to zero. -bfOffBits Specifies the byte offset from the BITMAPFILEHEADER structure -to the actual bitmap data in the file. - -Comments - -A BITMAPINFO or BITMAPCOREINFO structure immediately follows the -BITMAPFILEHEADER structure in the DIB file. - -See Also - -BITMAPCOREINFO, BITMAPINFO - - -============================================================================== -BITMAPINFO (3.0) - - - -typedef struct tagBITMAPINFO { /* bmi */ - BITMAPINFOHEADER bmiHeader; - RGBQUAD bmiColors[1]; -} BITMAPINFO; - -The BITMAPINFO structure fully defines the dimensions and color information -for a Windows 3.0 or later device-independent bitmap (DIB). - -Member Description - -bmiHeader Specifies a BITMAPINFOHEADER structure that contains -information about the dimensions and color format of a DIB. - -bmiColors Specifies an array of RGBQUAD structures that define the -colors in the bitmap. - -Comments - -A Windows 3.0 or later DIB consists of two distinct parts: a BITMAPINFO -structure, which describes the dimensions and colors of the bitmap, and an -array of bytes defining the pixels of the bitmap. The bits in the array are -packed together, but each scan line must be zero-padded to end on a LONG -boundary. Segment boundaries, however, can appear anywhere in the bitmap. The -origin of the bitmap is the lower-left corner. - -The biBitCount member of the BITMAPINFOHEADER structure determines the number -of bits which define each pixel and the maximum number of colors in the -bitmap. This member may be set to any of the following values: - -Value Meaning - -1 The bitmap is monochrome, and the bmciColors member must contain two -entries. Each bit in the bitmap array represents a pixel. If the bit is -clear, the pixel is displayed with the color of the first entry in the -bmciColors table. If the bit is set, the pixel has the color of the second -entry in the table. - -4 The bitmap has a maximum of 16 colors, and the bmciColors member -contains 16 entries. Each pixel in the bitmap is represented by a four-bit -index into the color table. - -For example, if the first byte in the bitmap is 0x1F, the byte represents two -pixels. The first pixel contains the color in the second table entry, and the -second pixel contains the color in the sixteenth table entry. - -8 The bitmap has a maximum of 256 colors, and the bmciColors member -contains 256 entries. In this case, each byte in the array represents a -single pixel. - -24 The bitmap has a maximum of 2^24 colors. The bmciColors member is -NULL, and each 3-byte sequence in the bitmap array represents the relative -intensities of red, green, and blue, respectively, of a pixel. - -The biClrUsed member of the BITMAPINFOHEADER structure specifies the number -of color indexes in the color table actually used by the bitmap. If the -biClrUsed member is set to zero, the bitmap uses the maximum number of colors -corresponding to the value of the biBitCount member. - -The colors in the bmiColors table should appear in order of importance. -Alternatively, for functions that use DIBs, the bmiColors member can be an -array of 16-bit unsigned integers that specify an index into the currently -realized logical palette instead of explicit RGB values. In this case, an -application using the bitmap must call DIB functions with the wUsage -parameter set to DIB_PAL_COLORS. - -Note: The bmiColors member should not contain palette indexes if the bitmap -is to be stored in a file or transferred to another application. Unless the -application uses the bitmap exclusively and under its complete control, the -bitmap color table should contain explicit RGB values. - -See Also - -BITMAPINFOHEADER, RGBQUAD - -============================================================================== -BITMAPINFOHEADER (3.0) - - - -typedef struct tagBITMAPINFOHEADER { /* bmih */ - DWORD biSize; - LONG biWidth; - LONG biHeight; - WORD biPlanes; - WORD biBitCount; - DWORD biCompression; - DWORD biSizeImage; - LONG biXPelsPerMeter; - LONG biYPelsPerMeter; - DWORD biClrUsed; - DWORD biClrImportant; -} BITMAPINFOHEADER; - -The BITMAPINFOHEADER structure contains information about the dimensions and -color format of a Windows 3.0 or later device-independent bitmap (DIB). - -Member Description - -biSize Specifies the number of bytes required by the -BITMAPINFOHEADER structure. - -biWidth Specifies the width of the bitmap, in pixels. -biHeight Specifies the height of the bitmap, in pixels. - -biPlanes Specifies the number of planes for the target device. This -member must be set to 1. - -biBitCount Specifies the number of bits per pixel. This value must be 1, -4, 8, or 24. - -biCompression Specifies the type of compression for a compressed bitmap. It -can be one of the following values: - -Value Meaning - -BI_RGB Specifies that the bitmap is not compressed. - -BI_RLE8 Specifies a run-length encoded format for bitmaps with 8 bits -per pixel. The compression format is a 2-byte format consisting of a count -byte followed by a byte containing a color index. For more information, see -the following Comments section. - -BI_RLE4 Specifies a run-length encoded format for bitmaps with 4 bits -per pixel. The compression format is a 2-byte format consisting of a count -byte followed by two word-length color indexes. For more information, see -the following Comments section. - -biSizeImage Specifies the size, in bytes, of the image. It is valid to -set this member to zero if the bitmap is in the BI_RGB format. - -biXPelsPerMeter Specifies the horizontal resolution, in pixels per meter, of -the target device for the bitmap. An application can use this value to select -a bitmap from a resource group that best matches the characteristics of the -current device. - -biYPelsPerMeter Specifies the vertical resolution, in pixels per meter, of -the target device for the bitmap. - -biClrUsed Specifies the number of color indexes in the color table -actually used by the bitmap. If this value is zero, the bitmap uses the -maximum number of colors corresponding to the value of the biBitCount member. -For more information on the maximum sizes of the color table, see the -description of the BITMAPINFO structure earlier in this topic. - -If the biClrUsed member is nonzero, it specifies the actual number of colors -that the graphics engine or device driver will access if the biBitCount -member is less than 24. If biBitCount is set to 24, biClrUsed specifies the -size of the reference color table used to optimize performance of Windows -color palettes. If the bitmap is a packed bitmap (that is, a bitmap in which -the bitmap array immediately follows the BITMAPINFO header and which is -referenced by a single pointer), the biClrUsed member must be set to zero or -to the actual size of the color table. - -biClrImportant Specifies the number of color indexes that are considered -important for displaying the bitmap. If this value is zero, all colors are -important. - -Comments - -The BITMAPINFO structure combines the BITMAPINFOHEADER structure and a color -table to provide a complete definition of the dimensions and colors of a -Windows 3.0 or later DIB. For more information about specifying a Windows 3.0 -DIB, see the description of the BITMAPINFO structure. - -An application should use the information stored in the biSize member to -locate the color table in a BITMAPINFO structure as follows: - -pColor = ((LPSTR) pBitmapInfo + (WORD) (pBitmapInfo->bmiHeader.biSize)) - -Windows supports formats for compressing bitmaps that define their colors -with 8 bits per pixel and with 4 bits per pixel. Compression reduces the disk -and memory storage required for the bitmap. The following paragraphs describe -these formats. - -BI_RLE8 - -When the biCompression member is set to BI_RLE8, the bitmap is compressed -using a run-length encoding format for an 8-bit bitmap. This format may be -compressed in either of two modes: encoded and absolute. Both modes can occur -anywhere throughout a single bitmap. - -Encoded mode consists of two bytes: the first byte specifies the number of -consecutive pixels to be drawn using the color index contained in the second -byte. In addition, the first byte of the pair can be set to zero to indicate -an escape that denotes an end of line, end of bitmap, or a delta. The -interpretation of the escape depends on the value of the second byte of the -pair. The following list shows the meaning of the second byte: - -Value Meaning - -0 End of line. -1 End of bitmap. -2 Delta. The two bytes following the escape contain unsigned values -indicating the horizontal and vertical offset of the next pixel from the -current position. - -Absolute mode is signaled by the first byte set to zero and the second byte -set to a value between 0x03 and 0xFF. In absolute mode, the second byte -represents the number of bytes that follow, each of which contains the color -index of a single pixel. When the second byte is set to 2 or less, the escape -has the same meaning as in encoded mode. In absolute mode, each run must be -aligned on a word boundary. The following example shows the hexadecimal -values of an 8-bit compressed bitmap: - - - -03 04 05 06 00 03 45 56 67 00 02 78 00 02 05 01 -02 78 00 00 09 1E 00 01 - -This bitmap would expand as follows (two-digit values represent a color index -for a single pixel): - - - -04 04 04 -06 06 06 06 06 -45 56 67 -78 78 -move current position 5 right and 1 down -78 78 -end of line -1E 1E 1E 1E 1E 1E 1E 1E 1E -end of RLE bitmap - -BI_RLE4 - -When the biCompression member is set to BI_RLE4, the bitmap is compressed -using a run-length encoding (RLE) format for a 4-bit bitmap, which also uses -encoded and absolute modes. In encoded mode, the first byte of the pair -contains the number of pixels to be drawn using the color indexes in the -second byte. The second byte contains two color indexes, one in its -high-order nibble (that is, its low-order four bits) and one in its low-order -nibble. The first of the pixels is drawn using the color specified by the -high-order nibble, the second is drawn using the color in the low-order -nibble, the third is drawn with the color in the high-order nibble, and so -on, until all the pixels specified by the first byte have been drawn. In -absolute mode, the first byte contains zero, the second byte contains the -number of color indexes that follow, and subsequent bytes contain color -indexes in their high- and low-order nibbles, one color index for each pixel. -In absolute mode, each run must be aligned on a word boundary. The -end-of-line, end-of-bitmap, and delta escapes also apply to BI_RLE4. - -The following example shows the hexadecimal values of a 4-bit compressed -bitmap: - - - -03 04 05 06 00 06 45 56 67 00 04 78 00 02 05 01 -04 78 00 00 09 1E 00 01 - -This bitmap would expand as follows (single-digit values represent a color -index for a single pixel): - - - -0 4 0 -0 6 0 6 0 -4 5 5 6 6 7 -7 8 7 8 -move current position 5 right and 1 down -7 8 7 8 -end of line -1 E 1 E 1 E 1 E 1 -end of RLE bitmap - -See Also - -BITMAPINFO - -============================================================================== -RGBQUAD (3.0) - - - -typedef struct tagRGBQUAD { /* rgbq */ - BYTE rgbBlue; - BYTE rgbGreen; - BYTE rgbRed; - BYTE rgbReserved; -} RGBQUAD; - -The RGBQUAD structure describes a color consisting of relative intensities of -red, green, and blue. The bmiColors member of the BITMAPINFO structure -consists of an array of RGBQUAD structures. - -Member Description - -rgbBlue Specifies the intensity of blue in the color. -rgbGreen Specifies the intensity of green in the color. -rgbRed Specifies the intensity of red in the color. -rgbReserved Not used; must be set to zero. - -See Also - -BITMAPINFO - -============================================================================== -RGB (2.x) - -COLORREF RGB(cRed, cGreen, cBlue) - -BYTE cRed; /* red component of color */ -BYTE cGreen; /* green component of color */ -BYTE cBlue; /* blue component of color */ - - -The RGB macro selects an RGB color based on the parameters supplied and the -color capabilities of the output device. - -Parameter Description - -cRed Specifies the intensity of the red color field. -cGreen Specifies the intensity of the green color field. -cBlue Specifies the intensity of the blue color field. - -Returns - -The return value specifies the resultant RGB color. - -Comments - -The intensity for each argument can range from 0 through 255. If all three -intensities are specified as zero, the result is black. If all three -intensities are specified as 255, the result is white. - -Comments - -The RGB macro is defined in WINDOWS.H as follows: - - - -#define RGB(r,g,b) ((COLORREF)(((BYTE)(r)|((WORD)(g)<<8))| \ - (((DWORD)(BYTE)(b))<<16))) - -See Also - -GetBValue, GetGValue, GetRValue, PALETTEINDEX, PALETTERGB - -============================================================================== -BITMAPCOREINFO (3.0) - - - -typedef struct tagBITMAPCOREINFO { /* bmci */ - BITMAPCOREHEADER bmciHeader; - RGBTRIPLE bmciColors[1]; -} BITMAPCOREINFO; - -The BITMAPCOREINFO structure fully defines the dimensions and color -information for a device-independent bitmap (DIB). Windows applications -should use the BITMAPINFO structure instead of BITMAPCOREINFO whenever -possible. - -Member Description - -bmciHeader Specifies a BITMAPCOREHEADER structure that contains -information about the dimensions and color format of a DIB. - -bmciColors Specifies an array of RGBTRIPLE structures that define the -colors in the bitmap. - -Comments - -The BITMAPCOREINFO structure describes the dimensions and colors of a bitmap. -It is followed immediately in memory by an array of bytes which define the -pixels of the bitmap. The bits in the array are packed together, but each -scan line must be zero-padded to end on a LONG boundary. Segment boundaries, -however, can appear anywhere in the bitmap. The origin of the bitmap is the -lower-left corner. - -The bcBitCount member of the BITMAPCOREHEADER structure determines the number -of bits that define each pixel and the maximum number of colors in the -bitmap. This member may be set to any of the following values: - -Value Meaning - -1 The bitmap is monochrome, and the bmciColors member must contain two -entries. Each bit in the bitmap array represents a pixel. If the bit is -clear, the pixel is displayed with the color of the first entry in the -bmciColors table. If the bit is set, the pixel has the color of the second -entry in the table. - -4 The bitmap has a maximum of 16 colors, and the bmciColors member -contains 16 entries. Each pixel in the bitmap is represented by a four-bit -index into the color table. - -For example, if the first byte in the bitmap is 0x1F, the byte represents two -pixels. The first pixel contains the color in the second table entry, and the -second pixel contains the color in the sixteenth table entry. - -8 The bitmap has a maximum of 256 colors, and the bmciColors member -contains 256 entries. In this case, each byte in the array represents a -single pixel. - -24 The bitmap has a maximum of 2^24 colors. The bmciColors member is -NULL, and each 3-byte sequence in the bitmap array represents the relative -intensities of red, green, and blue, respectively, of a pixel. - -The colors in the bmciColors table should appear in order of importance. -Alternatively, for functions that use DIBs, the bmciColors member can be an -array of 16-bit unsigned integers that specify an index into the currently -realized logical palette instead of explicit RGB values. In this case, an -application using the bitmap must call DIB functions with the wUsage -parameter set to DIB_PAL_COLORS. - -Note: The bmciColors member should not contain palette indexes if the -bitmap is to be stored in a file or transferred to another application. -Unless the application uses the bitmap exclusively and under its complete -control, the bitmap color table should contain explicit RGB values. - -See Also - -BITMAPINFO, BITMAPCOREHEADER, RGBTRIPLE - - -============================================================================== -BITMAPCOREHEADER (3.0) - - - -typedef struct tagBITMAPCOREHEADER { /* bmch */ - DWORD bcSize; - short bcWidth; - short bcHeight; - WORD bcPlanes; - WORD bcBitCount; -} BITMAPCOREHEADER; - -The BITMAPCOREHEADER structure contains information about the dimensions and -color format of a device-independent bitmap (DIB). Windows applications -should use the BITMAPINFOHEADER structure instead of BITMAPCOREHEADER -whenever possible. - -Member Description - -bcSize Specifies the number of bytes required by the -BITMAPCOREHEADER structure. - -bcWidth Specifies the width of the bitmap, in pixels. -bcHeight Specifies the height of the bitmap, in pixels. - -bcPlanes Specifies the number of planes for the target device. This -member must be set to 1. - -bcBitCount Specifies the number of bits per pixel. This value must be 1, -4, 8, or 24. - -Comments - -The BITMAPCOREINFO structure combines the BITMAPCOREHEADER structure and a -color table to provide a complete definition of the dimensions and colors of -a DIB. See the description of the BITMAPCOREINFO structure for more -information about specifying a DIB. - -An application should use the information stored in the bcSize member to -locate the color table in a BITMAPCOREINFO structure with a method such as -the following: - - - -lpColor = ((LPSTR) pBitmapCoreInfo + (UINT) (pBitmapCoreInfo->bcSize)) - -See Also - -BITMAPCOREINFO, BITMAPINFOHEADER, BITMAPINFOHEADER - -============================================================================= -RGBTRIPLE (3.0) - - - -typedef struct tagRGBTRIPLE { /* rgbt */ - BYTE rgbtBlue; - BYTE rgbtGreen; - BYTE rgbtRed; -} RGBTRIPLE; - -The RGBTRIPLE structure describes a color consisting of relative intensities -of red, green, and blue. The bmciColors member of the BITMAPCOREINFO -structure consists of an array of RGBTRIPLE structures. Windows applications -should use the BITMAPINFO structure instead of BITMAPCOREINFO whenever -possible. The BITMAPINFO structure uses an RGBQUAD structure instead of the -RGBTRIPLE structure. - -Member Description - -rgbtBlue Specifies the intensity of blue in the color. -rgbtGreen Specifies the intensity of green in the color. -rgbtRed Specifies the intensity of red in the color. - -See Also - -BITMAPCOREINFO, BITMAPINFO, RGBQUAD - -============================================================================== - Index: trunk/docs/lgpl.txt =================================================================== --- trunk/docs/lgpl.txt (revision 4) +++ trunk/docs/lgpl.txt (nonexistent) @@ -1,504 +0,0 @@ - GNU LESSER GENERAL PUBLIC LICENSE - Version 2.1, February 1999 - - Copyright (C) 1991, 1999 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - -[This is the first released version of the Lesser GPL. It also counts - as the successor of the GNU Library Public License, version 2, hence - the version number 2.1.] - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -Licenses are intended to guarantee your freedom to share and change -free software--to make sure the software is free for all its users. - - This license, the Lesser General Public License, applies to some -specially designated software packages--typically libraries--of the -Free Software Foundation and other authors who decide to use it. You -can use it too, but we suggest you first think carefully about whether -this license or the ordinary General Public License is the better -strategy to use in any particular case, based on the explanations below. - - When we speak of free software, we are referring to freedom of use, -not price. Our General Public Licenses are designed to make sure that -you have the freedom to distribute copies of free software (and charge -for this service if you wish); that you receive source code or can get -it if you want it; that you can change the software and use pieces of -it in new free programs; and that you are informed that you can do -these things. - - To protect your rights, we need to make restrictions that forbid -distributors to deny you these rights or to ask you to surrender these -rights. These restrictions translate to certain responsibilities for -you if you distribute copies of the library or if you modify it. - - For example, if you distribute copies of the library, whether gratis -or for a fee, you must give the recipients all the rights that we gave -you. You must make sure that they, too, receive or can get the source -code. If you link other code with the library, you must provide -complete object files to the recipients, so that they can relink them -with the library after making changes to the library and recompiling -it. And you must show them these terms so they know their rights. - - We protect your rights with a two-step method: (1) we copyright the -library, and (2) we offer you this license, which gives you legal -permission to copy, distribute and/or modify the library. - - To protect each distributor, we want to make it very clear that -there is no warranty for the free library. Also, if the library is -modified by someone else and passed on, the recipients should know -that what they have is not the original version, so that the original -author's reputation will not be affected by problems that might be -introduced by others. - - Finally, software patents pose a constant threat to the existence of -any free program. We wish to make sure that a company cannot -effectively restrict the users of a free program by obtaining a -restrictive license from a patent holder. Therefore, we insist that -any patent license obtained for a version of the library must be -consistent with the full freedom of use specified in this license. - - Most GNU software, including some libraries, is covered by the -ordinary GNU General Public License. This license, the GNU Lesser -General Public License, applies to certain designated libraries, and -is quite different from the ordinary General Public License. We use -this license for certain libraries in order to permit linking those -libraries into non-free programs. - - When a program is linked with a library, whether statically or using -a shared library, the combination of the two is legally speaking a -combined work, a derivative of the original library. The ordinary -General Public License therefore permits such linking only if the -entire combination fits its criteria of freedom. The Lesser General -Public License permits more lax criteria for linking other code with -the library. - - We call this license the "Lesser" General Public License because it -does Less to protect the user's freedom than the ordinary General -Public License. It also provides other free software developers Less -of an advantage over competing non-free programs. These disadvantages -are the reason we use the ordinary General Public License for many -libraries. However, the Lesser license provides advantages in certain -special circumstances. - - For example, on rare occasions, there may be a special need to -encourage the widest possible use of a certain library, so that it becomes -a de-facto standard. To achieve this, non-free programs must be -allowed to use the library. A more frequent case is that a free -library does the same job as widely used non-free libraries. In this -case, there is little to gain by limiting the free library to free -software only, so we use the Lesser General Public License. - - In other cases, permission to use a particular library in non-free -programs enables a greater number of people to use a large body of -free software. For example, permission to use the GNU C Library in -non-free programs enables many more people to use the whole GNU -operating system, as well as its variant, the GNU/Linux operating -system. - - Although the Lesser General Public License is Less protective of the -users' freedom, it does ensure that the user of a program that is -linked with the Library has the freedom and the wherewithal to run -that program using a modified version of the Library. - - The precise terms and conditions for copying, distribution and -modification follow. Pay close attention to the difference between a -"work based on the library" and a "work that uses the library". The -former contains code derived from the library, whereas the latter must -be combined with the library in order to run. - - GNU LESSER GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License Agreement applies to any software library or other -program which contains a notice placed by the copyright holder or -other authorized party saying it may be distributed under the terms of -this Lesser General Public License (also called "this License"). -Each licensee is addressed as "you". - - A "library" means a collection of software functions and/or data -prepared so as to be conveniently linked with application programs -(which use some of those functions and data) to form executables. - - The "Library", below, refers to any such software library or work -which has been distributed under these terms. A "work based on the -Library" means either the Library or any derivative work under -copyright law: that is to say, a work containing the Library or a -portion of it, either verbatim or with modifications and/or translated -straightforwardly into another language. (Hereinafter, translation is -included without limitation in the term "modification".) - - "Source code" for a work means the preferred form of the work for -making modifications to it. For a library, complete source code means -all the source code for all modules it contains, plus any associated -interface definition files, plus the scripts used to control compilation -and installation of the library. - - Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running a program using the Library is not restricted, and output from -such a program is covered only if its contents constitute a work based -on the Library (independent of the use of the Library in a tool for -writing it). Whether that is true depends on what the Library does -and what the program that uses the Library does. - - 1. You may copy and distribute verbatim copies of the Library's -complete source code as you receive it, in any medium, provided that -you conspicuously and appropriately publish on each copy an -appropriate copyright notice and disclaimer of warranty; keep intact -all the notices that refer to this License and to the absence of any -warranty; and distribute a copy of this License along with the -Library. - - You may charge a fee for the physical act of transferring a copy, -and you may at your option offer warranty protection in exchange for a -fee. - - 2. You may modify your copy or copies of the Library or any portion -of it, thus forming a work based on the Library, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) The modified work must itself be a software library. - - b) You must cause the files modified to carry prominent notices - stating that you changed the files and the date of any change. - - c) You must cause the whole of the work to be licensed at no - charge to all third parties under the terms of this License. - - d) If a facility in the modified Library refers to a function or a - table of data to be supplied by an application program that uses - the facility, other than as an argument passed when the facility - is invoked, then you must make a good faith effort to ensure that, - in the event an application does not supply such function or - table, the facility still operates, and performs whatever part of - its purpose remains meaningful. - - (For example, a function in a library to compute square roots has - a purpose that is entirely well-defined independent of the - application. Therefore, Subsection 2d requires that any - application-supplied function or table used by this function must - be optional: if the application does not supply it, the square - root function must still compute square roots.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Library, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Library, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote -it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Library. - -In addition, mere aggregation of another work not based on the Library -with the Library (or with a work based on the Library) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may opt to apply the terms of the ordinary GNU General Public -License instead of this License to a given copy of the Library. To do -this, you must alter all the notices that refer to this License, so -that they refer to the ordinary GNU General Public License, version 2, -instead of to this License. (If a newer version than version 2 of the -ordinary GNU General Public License has appeared, then you can specify -that version instead if you wish.) Do not make any other change in -these notices. - - Once this change is made in a given copy, it is irreversible for -that copy, so the ordinary GNU General Public License applies to all -subsequent copies and derivative works made from that copy. - - This option is useful when you wish to copy part of the code of -the Library into a program that is not a library. - - 4. You may copy and distribute the Library (or a portion or -derivative of it, under Section 2) in object code or executable form -under the terms of Sections 1 and 2 above provided that you accompany -it with the complete corresponding machine-readable source code, which -must be distributed under the terms of Sections 1 and 2 above on a -medium customarily used for software interchange. - - If distribution of object code is made by offering access to copy -from a designated place, then offering equivalent access to copy the -source code from the same place satisfies the requirement to -distribute the source code, even though third parties are not -compelled to copy the source along with the object code. - - 5. A program that contains no derivative of any portion of the -Library, but is designed to work with the Library by being compiled or -linked with it, is called a "work that uses the Library". Such a -work, in isolation, is not a derivative work of the Library, and -therefore falls outside the scope of this License. - - However, linking a "work that uses the Library" with the Library -creates an executable that is a derivative of the Library (because it -contains portions of the Library), rather than a "work that uses the -library". The executable is therefore covered by this License. -Section 6 states terms for distribution of such executables. - - When a "work that uses the Library" uses material from a header file -that is part of the Library, the object code for the work may be a -derivative work of the Library even though the source code is not. -Whether this is true is especially significant if the work can be -linked without the Library, or if the work is itself a library. The -threshold for this to be true is not precisely defined by law. - - If such an object file uses only numerical parameters, data -structure layouts and accessors, and small macros and small inline -functions (ten lines or less in length), then the use of the object -file is unrestricted, regardless of whether it is legally a derivative -work. (Executables containing this object code plus portions of the -Library will still fall under Section 6.) - - Otherwise, if the work is a derivative of the Library, you may -distribute the object code for the work under the terms of Section 6. -Any executables containing that work also fall under Section 6, -whether or not they are linked directly with the Library itself. - - 6. As an exception to the Sections above, you may also combine or -link a "work that uses the Library" with the Library to produce a -work containing portions of the Library, and distribute that work -under terms of your choice, provided that the terms permit -modification of the work for the customer's own use and reverse -engineering for debugging such modifications. - - You must give prominent notice with each copy of the work that the -Library is used in it and that the Library and its use are covered by -this License. You must supply a copy of this License. If the work -during execution displays copyright notices, you must include the -copyright notice for the Library among them, as well as a reference -directing the user to the copy of this License. Also, you must do one -of these things: - - a) Accompany the work with the complete corresponding - machine-readable source code for the Library including whatever - changes were used in the work (which must be distributed under - Sections 1 and 2 above); and, if the work is an executable linked - with the Library, with the complete machine-readable "work that - uses the Library", as object code and/or source code, so that the - user can modify the Library and then relink to produce a modified - executable containing the modified Library. (It is understood - that the user who changes the contents of definitions files in the - Library will not necessarily be able to recompile the application - to use the modified definitions.) - - b) Use a suitable shared library mechanism for linking with the - Library. A suitable mechanism is one that (1) uses at run time a - copy of the library already present on the user's computer system, - rather than copying library functions into the executable, and (2) - will operate properly with a modified version of the library, if - the user installs one, as long as the modified version is - interface-compatible with the version that the work was made with. - - c) Accompany the work with a written offer, valid for at - least three years, to give the same user the materials - specified in Subsection 6a, above, for a charge no more - than the cost of performing this distribution. - - d) If distribution of the work is made by offering access to copy - from a designated place, offer equivalent access to copy the above - specified materials from the same place. - - e) Verify that the user has already received a copy of these - materials or that you have already sent this user a copy. - - For an executable, the required form of the "work that uses the -Library" must include any data and utility programs needed for -reproducing the executable from it. However, as a special exception, -the materials to be distributed need not include anything that is -normally distributed (in either source or binary form) with the major -components (compiler, kernel, and so on) of the operating system on -which the executable runs, unless that component itself accompanies -the executable. - - It may happen that this requirement contradicts the license -restrictions of other proprietary libraries that do not normally -accompany the operating system. Such a contradiction means you cannot -use both them and the Library together in an executable that you -distribute. - - 7. You may place library facilities that are a work based on the -Library side-by-side in a single library together with other library -facilities not covered by this License, and distribute such a combined -library, provided that the separate distribution of the work based on -the Library and of the other library facilities is otherwise -permitted, and provided that you do these two things: - - a) Accompany the combined library with a copy of the same work - based on the Library, uncombined with any other library - facilities. This must be distributed under the terms of the - Sections above. - - b) Give prominent notice with the combined library of the fact - that part of it is a work based on the Library, and explaining - where to find the accompanying uncombined form of the same work. - - 8. You may not copy, modify, sublicense, link with, or distribute -the Library except as expressly provided under this License. Any -attempt otherwise to copy, modify, sublicense, link with, or -distribute the Library is void, and will automatically terminate your -rights under this License. However, parties who have received copies, -or rights, from you under this License will not have their licenses -terminated so long as such parties remain in full compliance. - - 9. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Library or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Library (or any work based on the -Library), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Library or works based on it. - - 10. Each time you redistribute the Library (or any work based on the -Library), the recipient automatically receives a license from the -original licensor to copy, distribute, link with or modify the Library -subject to these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties with -this License. - - 11. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Library at all. For example, if a patent -license would not permit royalty-free redistribution of the Library by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Library. - -If any portion of this section is held invalid or unenforceable under any -particular circumstance, the balance of the section is intended to apply, -and the section as a whole is intended to apply in other circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 12. If the distribution and/or use of the Library is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Library under this License may add -an explicit geographical distribution limitation excluding those countries, -so that distribution is permitted only in or among countries not thus -excluded. In such case, this License incorporates the limitation as if -written in the body of this License. - - 13. The Free Software Foundation may publish revised and/or new -versions of the Lesser General Public License from time to time. -Such new versions will be similar in spirit to the present version, -but may differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Library -specifies a version number of this License which applies to it and -"any later version", you have the option of following the terms and -conditions either of that version or of any later version published by -the Free Software Foundation. If the Library does not specify a -license version number, you may choose any version ever published by -the Free Software Foundation. - - 14. If you wish to incorporate parts of the Library into other free -programs whose distribution conditions are incompatible with these, -write to the author to ask for permission. For software which is -copyrighted by the Free Software Foundation, write to the Free -Software Foundation; we sometimes make exceptions for this. Our -decision will be guided by the two goals of preserving the free status -of all derivatives of our free software and of promoting the sharing -and reuse of software generally. - - NO WARRANTY - - 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO -WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. -EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR -OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY -KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE -LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME -THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - - 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN -WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY -AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU -FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR -CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE -LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING -RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A -FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF -SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH -DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Libraries - - If you develop a new library, and you want it to be of the greatest -possible use to the public, we recommend making it free software that -everyone can redistribute and change. You can do so by permitting -redistribution under these terms (or, alternatively, under the terms of the -ordinary General Public License). - - To apply these terms, attach the following notices to the library. It is -safest to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least the -"copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - -Also add information on how to contact you by electronic and paper mail. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the library, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the - library `Frob' (a library for tweaking knobs) written by James Random Hacker. - - , 1 April 1990 - Ty Coon, President of Vice - -That's all there is to it! - - Index: trunk/docs/jfif3.pdf =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream Index: trunk/docs/jfif3.pdf =================================================================== --- trunk/docs/jfif3.pdf (revision 4) +++ trunk/docs/jfif3.pdf (nonexistent)

trunk/docs/jfif3.pdf Property changes : Deleted: svn:mime-type ## -1 +0,0 ## -application/octet-stream \ No newline at end of property Index: trunk/readme.txt =================================================================== --- trunk/readme.txt (revision 4) +++ trunk/readme.txt (revision 5) @@ -10,60 +10,19 @@ - Description -This project features a complete JPEG Hardware Compressor (standard Baseline DCT, JFIF header) with 2:1:1 subsampling, able to compress at a rate of up to 24 images per second (on XC2V1000-4 @ 40 MHz with resolution 352x288). +This project features a complete JPEG Hardware Compressor (standard Baseline DCT, JFIF header) with 2:1:1 subsampling, able to compress at a rate of up to 24 images per second (on XC2V1000-4 @ 40 MHz with CIF resolution: 352x288). -Image resolution is not limited. It takes an RGB input (row-wise) and outputs to a memory the compressed JPEG image. Its quality is comparable to software solutions. +IMAGE RESOLUTION IS LIMITED TO 352x288. It takes an RGB input (row-wise) and outputs to a memory the compressed JPEG image. -A testbench has been made that takes a bitmap image from your computer and writes a compressed JPEG file by simulating the code. Download the code and try it, it's easy. +A testbench has been made that takes a bitmap image from your computer and writes a compressed JPEG file by simulating the code. -The source code is VHDL and it is LGPL, so it can be used in commercial applications as long as the terms of the license are respected. - Anyone interested in the image standards used in this project, they can be downloaded from the following places: -JPEG (ITU-T81 standard): http://www.w3.org/Graphics/JPEG/itu-t81.pdf -JFIF (JPEG file headers): http://www.w3.org/Graphics/JPEG/jfif3.pdf +JPEG (ITU-T81 standard): http://www.w3.org/Graphics/JPEG/itu-t81.pdf +JFIF (JPEG file headers): http://www.w3.org/Graphics/JPEG/jfif3.pdf BMP (bitmaps for the testbench): http://netghost.narod.ru/gff/vendspec/micbmp/bmp.txt -Please note that there is another Tab in this web page named "Detailed Description" with further info on this core. +If you run into any problems downloading the files from the cvs please check that you are downloading them in binary form. For any questions my email is: +victor.lopez [(at)] ono [(dot)] com -If you run into any problems downloading the files from the cvs please check that you are downloading them in binary form. For any questions my email is: -galland@opencores.org - - -- Notes - -Some quick notes until the time I upload the full documentation: - - * This implementation is compliant with ISO standard (and ITU standard T-81), it features a compliant JPEG compressor Baseline DCT with Huffman encoding and 2x2 1x1 1x1 subsampling. The header is the widely employed JFIF. Baseline DCT JPEG with JFIF header is one of the most used image formats. - * Included with the source code is a Testbench which allows you to compress a bitmap (uncompressed 24 bit BMP) file located in the project folder (if using Active-HDL then in the design folder) just by simulating it. Its name MUST be "image.bmp". By the way, remember that a bitmap image stores the information bottom up, and JPEG is top-bottom, so you should flip (invert) the bitmap image (see the test image if you don't understand what I mean). This is only important for simulation. - * The testbench is made in such a way that it will automatically exit the simulation when it finishes. A 352x288 image takes almost 40 ms of simulation time (that will take some minutes depending on your machine). The output image will be in the same folder as "image.bmp" and its name will be "image.jpg" (it will overwrite previous outputs without warning). - * It has been simulated on Windows machines, so I can't guarantee anything on simulation over Linux though I don't think there could be any problem at all. Please update me on this. - * It has been synthesized and tested in a Xilinx Virtex-2 XC2V1000-4 running at 40 MHz (that is why it takes 40 ms, the testbench simulates a 40 MHz clock). This is one of the worst speed grades (-4), so with most other FPGAs you will get faster implementations. - * It uses at minimum 11 BlockRAMs (one of them for the DCT block), but you will need some more to store the final compressed image (whose size varies as compression depends on the image as well as in the compression level), the source code in the Downloads page includes a memory for this purpose of 51.200 bytes (buffer_img), that is 25 BlockRAMs. - * There is an easily overridable limitation on input image resolution, for a description on how to change the maximum input image size see the Notes at the beginning of the main source file "compressor.vhd". - * The only real limitation is that the input image must have width and height multiple of 16 (that is, an image 32x32 will produce a strictly compliant JPEG image file, but not a 32x24 or a 24x32 input image, although the resulting image will more likely still be viewable), this is due to the subsampling method employed. This limitation could be overriden with some extra logic (for padding as indicated in the JPEG standard). - - * Finally I would like to apologize if you find this code somewhat messy. When I programmed it, I imposed myself very strict deadlines and making it opensource was not in my mind, mainly because, if I were to do it again, I would do it in other way to get much more performance. The main problem faced with this implementation was a very scarce availability of BlockRAM in the target FPGA, so some areas that could perfectly run in parallel, speeding a lot the whole process, had to be made sequential in order to save up BlockRAMs. Anyways, this code works (it functioned as a webcam, attached to a CMOS sensor) and, though not as fast as it could be, it has a good performance. This source code is LGPL. Any questions, suggestions, comments (positive criticism) is always welcome. - - -- Functional Description - -The source code is composed of 9 VHDL files: - - * compressor_tb.vhd : Testbench file for the project. It reads an uncompressed BMP located in the project folder (not necessarily the source code folder) and outputs a JPG compressed image (the actual writing of the output file is carried out by the next file). - - * compressor.vhd : This is the main code file. Inside, there are a few concurrent instructions, declarations of the needed componentes (BlockRAMs and DCT block) and two processes which are responsible of the whole compression process. To better follow the next explanation consult the figure located after this explanation. The first process is RGB2YCbCr is in charge of converting the input signals (Red, Green and Blue, strobed by ProcessRGB signal) to the YCbCr color space and to apply a level shift as specified by the JPEG standard. The second is the process JPEG, it feeds the DCT block (DCT-2D Core in the figure) with data from the previous process (the interface between the two processes are three memories (Y, Cb and Cr Compression Buffers in the figure), one for luminance (Y) data, one for blue chrominance (Cb) and another for red chrominance (Cr)); after the DCT has processed the data (calculated the Forward 2D-DCT) it is quantized with the values stored in memory q_rom (Q ROM in the figure). As this quantization implies dividing by an integer number (remember that only divisions by power of 2 numbers and multiplications times an integer can be made really efficient in digital logic thru the use of shifts, right for division, left for multiplication), the solution was to convert the number to divide into a fraction with denominator 16384 for all the quantization values (128 for every compression level and there are three of these) so that we can multiply times an integer (left shift and some additions) and divide by a power of 2 number (right shift). For instance: to divide by 11 is the same as multiplying times 1/11, which is almost the same as multiplying times 1489/16384, which is actually equal to dividing by 11.003357. Using this apparently complicated way of handling real number operations we get the fastest implementation and no floating point, only a minimal error (you would never notice the visual difference). After quantization of all the values, Huffman encoding starts by looking up the tables stored in huff_rom (Huffman ROM in the figure) and storing in the final image buffer the compressed image (should be buffer_img but in the figure is left as a blue upwards pointing arrow). By the way, at the beginning, when a compression level is selected and the port CompressImage signals the start of a new image, the header in buffer_img (yes, there are some hundred bytes pre-stored with the fixed fields in the header) is updated with image dimensions and with the quantization tables for the selected compression (they are read from the ROM tabla_q in the figure and copied to the appropiate location in buffer_img). - - * buffer_img.vhd : CoreGen generated file with wrapper for the 25 SP BlockRAMs, Read/Write, WidthxDepth = 8 bits x 51200, where final image is stored. - - * buffer_comp.vhd : CoreGen generated file with wrapper for 5 SP BlockRAMs, Read/Write, WidthxDepth = 12 bits x 5632. Y pixels (8 bits) stored here and also, after transformation by DCT, their quantized counterparts (12 bits) are stored over them. - - * buffer_comp_chrom.vhd : CoreGen generated file with wrapper for 1 SP BlockRAM, Read/Write, WidthxDepth = 12 bits x 1408. This component is instantiated twice, one for Cb pixels, and other for Cr pixels. Cx pixels (8 bits) stored here and also, after transformation by DCT, their quantized counterparts (12 bits) are stored over them. - - * huff_rom.vhd : CoreGen generated file with wrapper for 1 SP BlockRAM, Read Only, WidthxDepth = 20 bits x 352. Huffman Code Tables stored here. - - * q_rom.vhd : CoreGen generated file with wrapper for 1 SP BlockRAM, Read Only, WidthxDepth = 13 bits x 384. Quantization Numerators stored here for multiplication and later division by 16384 as explained above. Three compression levels, two tables for each one (AC and DC), 64 elements in each one : 3x2x64=384. - - * tabla_q.vhd : CoreGen generated file with wrapper for 1 SP BlockRAM, Read Only, WidthxDepth = 8 bits x 384. Quantization Tables stored here for updating of the final JPEG file header. Three compression levels, two tables for each one (AC and DC), 64 elements in each one : 3x2x64=384. - - * dct2d.vhd : CoreGen generated file with wrapper for 2-D Discrete Cosine Transform (Forward DCT), Data Width = 8 bits Signed, Coefficients Width = 24 (Enable Symmetry), Precision Control: Round, Internal Width: 19, Result Width: 19, Performance: Clock Cycles per input=9, Transpose Memory = Block, Reset: No. (Results: Latency = 95 cycles, Row Latency = 15 cycles, Column Latency = 15 cycles). Takes as input sixty-four 8 bits signed values and outputs sixty-four 19 bits signed numbers in the frequency domain (the LSBs are decimals). \ No newline at end of file +PLEASE NOTICE THAT THIS CORE IS LICENSED AS GPL. That means you may use it only for NON-COMMERCIAL purposes.

/trunk/compressor.vhd

0,0 → 1,1913

Browse

Tools

Subversion Repositories jpeg

Compare Revisions

Rev 4 → Rev 5