commit ad07b53fc0d8d910c502ce21b25c8c5bb0a5623a
Author: Peter Rosin <p...@lysator.liu.se>
Date: Wed Jun 17 10:45:35 2009 +0200
Update Tight Encoding description to match guidelines.
Signed-off-by: Peter Rosin <p...@lysator.liu.se>
diff --git a/rfbproto.rst b/rfbproto.rst
index 90545a3..0fcfe2e 100644
--- a/rfbproto.rst
+++ b/rfbproto.rst
@@ -1951,7 +1951,11 @@ the `Raw Encoding`_.
Tight Encoding
--------------
-Tight encoding provides efficient compression for pixel data.
+Tight encoding provides efficient compression for pixel data. To
+reduce implementation complexity, the width of any Tight-encoded
+rectangle cannot exceed 2048 pixels. If a wider rectangle is desired,
+it must be split into several rectangles and each one should be encoded
+separately.
The first byte of each Tight-encoded rectangle is a
*compression-control* byte:
@@ -1962,23 +1966,23 @@ No. of bytes Type Description
1 ``U8`` *compression-control*
=============== =================== ===================================
-The least significant four bits of *compression-control* byte inform
-the client which zlib compression streams should be reset before
+The least significant four bits of the *compression-control* byte
+inform the client which zlib compression streams should be reset before
decoding the rectangle. Each bit is independent and corresponds to a
separate zlib stream that should be reset:
================== ====================================================
Bit Description
================== ====================================================
-0 if 1: reset stream 0
-1 if 1: reset stream 1
-2 if 1: reset stream 2
-3 if 1: reset stream 3
+0 Reset stream 0
+1 Reset stream 1
+2 Reset stream 2
+3 Reset stream 3
================== ====================================================
One of three possible compression methods are supported in the Tight
encoding. These are **BasicCompression**, **FillCompression** and
-**JpegCompression**. If the bit 7 (the most significant bit) of
+**JpegCompression**. If the bit 7 (the most significant bit) of the
*compression-control* byte is 0, then the compression type is
**BasicCompression**. In that case, bits 7-4 (the most significant four
bits) of *compression-control* should be interpreted as follows:
@@ -1986,12 +1990,12 @@ bits) of *compression-control* should be interpreted as
follows:
=============== =================== ===================================
Bits Binary value Description
=============== =================== ===================================
-5-4 00 *UseStream0*
-.. 01 *UseStream1*
-.. 10 *UseStream2*
-.. 11 *UseStream3*
+5-4 00 Use stream 0
+.. 01 Use stream 1
+.. 10 Use stream 2
+.. 11 Use stream 3
6 0 ---
-.. 1 *ReadFilterId*
+.. 1 *read-filter-id*
7 0 **BasicCompression**
=============== =================== ===================================
@@ -2004,33 +2008,42 @@ Bits Binary value Description
=============== =================== ===================================
7-4 1000 **FillCompression**
.. 1001 **JpegCompression**
-.. any other invalid
+.. any other Invalid
=============== =================== ===================================
Note: **JpegCompression** may only be used when *bits-per-pixel* is
-either 16 or 32.
+either 16 or 32 and the client has advertized a quality level using the
+`JPEG Quality Level Pseudo-encoding`_.
+
+The Tight encoding makes use of a new type ``TPIXEL`` (Tight pixel).
+This is the same as a ``PIXEL`` for the agreed pixel format, except
+where *true-colour-flag* is non-zero, *bits-per-pixel* is 32, *depth*
+is 24 and all of the bits making up the red, green and blue intensities
+are exactly 8 bits wide. In this case a ``TPIXEL`` is only 3 bytes
+long, where the first byte is the red component, the second byte is the
+green component, and the third byte is the blue component of the pixel
+color value.
The data following the *compression-control* byte depends on the
compression method.
**FillCompression**
- If the compression type is "fill", then the only pixel value
- follows, in client pixel format (see [NOTE1]_). This value applies
- to all pixels of the rectangle.
+ If the compression type is **FillCompression**, then the only pixel
+ value follows, in ``TPIXEL`` format. This value applies to all
+ pixels of the rectangle.
**JpegCompression**
- If the compression type is "jpeg", the following data stream looks
- like this:
+ If the compression type is **JpegCompression**, the following data
+ stream looks like this:
- =============== =================== ===============================
- No. of bytes Type Description
- =============== =================== ===============================
- 1-3 *length* in compact
- representation
- *length* ``U8`` array *jpegData*
- =============== =================== ===============================
+ =============== ================ ==================================
+ No. of bytes Type Description
+ =============== ================ ==================================
+ 1-3 *length* in compact representation
+ *length* ``U8`` array *jpeg-data*
+ =============== ================ ==================================
*length* is compactly represented in one, two or three bytes,
according to the following scheme:
@@ -2049,98 +2062,99 @@ compression method.
example, decimal value 10000 should be represented as two bytes:
binary 10010000 01001110, or hexadecimal 90 4E.
+ The *jpeg-data* is a JFIF stream.
+
**BasicCompression**
- If the compression type is "basic" and bit 6 of the compression
- control byte was set to 1, then the next (second) byte specifies
- *filter-id* which tells the decoder what filter type was used by
- the encoder to pre-process pixel data before the compression. The
- *filter-id* byte can be one of the following:
+ If the compression type is **BasicCompression** and bit 6 (the
+ *read-filter-id* bit) of the *compression-control* byte was set to
+ 1, then the next (second) byte specifies *filter-id* which tells
+ the decoder what filter type was used by the encoder to pre-process
+ pixel data before the compression. The *filter-id* byte can be one
+ of the following:
=============== ========= ======== ================================
No. of bytes Type [Value] Description
=============== ========= ======== ================================
1 ``U8`` *filter-id*
- .. 0 **no filter** ("copy" filter)
- .. 1 **palette filter**
- .. 2 **gradient filter**
+ .. 0 **CopyFilter** (no filter)
+ .. 1 **PaletteFilter**
+ .. 2 **GradientFilter**
=============== ========= ======== ================================
- If bit 6 of the compression control byte is set to 0 (no
- *filter-id* byte), or if the *filter-id* is 0, then raw pixel
- values in the client format (see [NOTE1]_) will be compressed. See
- below details on the compression.
-
- The **gradient filter** pre-processes pixel data with a simple
- algorithm which converts each color component to a difference
- between a "predicted" intensity and the actual intensity. Such a
- technique does not affect uncompressed data size, but helps to
- compress photo-like images better. Pseudo-code for converting
- intensities to differences is the following:
-
- ::
-
- P[i,j] := V[i-1,j] + V[i,j-1] - V[i-1,j-1];
- if (P[i,j] < 0) then P[i,j] := 0;
- if (P[i,j] > MAX) then P[i,j] := MAX;
- D[i,j] := V[i,j] - P[i,j];
-
- Here V[i,j] is the intensity of a color component for a pixel at
- coordinates (i,j). MAX is the maximum value of intensity for a
- color component.
-
- The **palette filter** converts true-color pixel data to indexed
- colors and a palette which can consist of 2..256 colors. If the
- number of colors is 2, then each pixel is encoded in 1 bit,
- otherwise 8 bits is used to encode one pixel. 1-bit encoding is
- performed such way that the most significant bits correspond to the
- leftmost pixels, and each raw of pixels is aligned to the byte
- boundary. When "palette" filter is used, the palette is sent before
- the pixel data. The palette begins with an unsigned byte which
- value is the number of colors in the palette minus 1 (i.e. 1 means
- 2 colors, 255 means 256 colors in the palette). Then follows the
- palette itself which consist of pixel values in client pixel format
- (see [NOTE1]_).
-
- The pixel data is compressed using the zlib library. But if the
- data size after applying the filter but before the compression is
- less then 12, then the data is sent as is, uncompressed. Four
- separate zlib streams (0..3) can be used and the decoder should
- read the actual stream id from the compression control byte (see
- [NOTE2]_).
+ If bit 6 of the *compression-control* byte is set to 0 (no
+ *filter-id* byte), then the **CopyFilter** is used.
+
+ **CopyFilter**
+
+ When the **CopyFilter** is active, raw pixel values in
+ ``TPIXEL`` format will be compressed. See below for details on
+ the compression.
+
+ **PaletteFilter**
+
+ The **PaletteFilter** converts true-color pixel data to indexed
+ colors and a palette which can consist of 2..256 colors. If the
+ number of colors is 2, then each pixel is encoded in 1 bit,
+ otherwise 8 bits are used to encode one pixel. 1-bit encoding
+ is performed such way that the most significant bits correspond
+ to the leftmost pixels, and each row of pixels is aligned to
+ the byte boundary. When the **PaletteFilter** is used, the
+ palette is sent before the pixel data. The palette begins with
+ an unsigned byte which value is the number of colors in the
+ palette minus 1 (i.e. 1 means 2 colors, 255 means 256 colors in
+ the palette). Then follows the palette itself which consist of
+ pixel values in ``TPIXEL`` format.
+
+ **GradientFilter**
+
+ The **GradientFilter** pre-processes pixel data with a simple
+ algorithm which converts each color component to a difference
+ between a "predicted" intensity and the actual intensity. Such
+ a technique does not affect uncompressed data size, but helps
+ to compress photo-like images better. Pseudo-code for
+ converting intensities to differences follows::
+
+ P[i,j] := V[i-1,j] + V[i,j-1] - V[i-1,j-1];
+ if (P[i,j] < 0) then P[i,j] := 0;
+ if (P[i,j] > MAX) then P[i,j] := MAX;
+ D[i,j] := V[i,j] - P[i,j];
+
+ Here ``V[i,j]`` is the intensity of a color component for a
+ pixel at coordinates ``(i,j)``. For pixels outside the current
+ rectangle, ``V[i,j]`` is assumed to be zero (which is relevant
+ for ``P[i,0]`` and ``P[0,j]``). MAX is the maximum intensity
+ value for a color component.
+
+ Note: The **GradientFilter** may only be used when
+ *bits-per-pixel* is either 16 or 32.
+
+ After the pixel data has been filtered with one of the above three
+ filters, it is compressed using the zlib library. But if the data
+ size after applying the filter but before the compression is less
+ then 12, then the data is sent as is, uncompressed. Four separate
+ zlib streams (0..3) can be used and the decoder should read the
+ actual stream id from the *compression-control* byte (see
+ [NOTE1]_).
If the compression is not used, then the pixel data is sent as is,
otherwise the data stream looks like this:
- =============== =================== ===============================
- No. of bytes Type Description
- =============== =================== ===============================
- 1-3 *length* in compact
- representation
- *length* ``U8`` array *zlibData*
- =============== =================== ===============================
+ =============== ================ ==================================
+ No. of bytes Type Description
+ =============== ================ ==================================
+ 1-3 *length* in compact representation
+ *length* ``U8`` array *zlibData*
+ =============== ================ ==================================
*length* is compactly represented in one, two or three bytes, just
like in the **JpegCompression** method (see above).
-.. [NOTE1] If the color depth is 24, and all three color components
- are 8-bit wide, then one pixel in Tight encoding is always
- represented by three bytes, where the first byte is red component,
- the second byte is green component, and the third byte is blue
- component of the pixel color value. This applies to colors in
- palettes as well.
-
-.. [NOTE2] The decoder must reset compression streams' states before
- decoding the rectangle, if some of bits 0,1,2,3 in the compression
- control byte are set to 1. Note that the decoder must reset zlib
- streams even if the compression type is "fill" or "jpeg".
-
-.. [NOTE3] The "gradient" filter and "jpeg" compression may be used
- only when bits-per-pixel value is either 16 or 32, not 8.
-
-.. [NOTE4] The width of any Tight-encoded rectangle cannot exceed
- 2048 pixels. If a rectangle is wider, it must be split into several
- rectangles and each one should be encoded separately.
+.. [NOTE1] The decoder must reset the zlib streams before decoding the
+ rectangle, if some of the bits 0, 1, 2 and 3 in the
+ *compression-control* byte are set to 1. Note that the decoder must
+ reset the indicated zlib streams even if the compression type is
+ **FillCompression** or **JpegCompression**.
zlibhex Encoding
----------------
------------------------------------------------------------------------------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensing option that enables unlimited
royalty-free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
_______________________________________________
tigervnc-rfbproto mailing list
tigervnc-rfbproto@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/tigervnc-rfbproto
