Hi!
I snarfed the TRLE description from the Internet draft.
I then changed the ZRLE description to also match the
Internet draft (TRLE is really very similar to ZRLE)
Three patches to make it easier to review, commit in one
go if you feel like it.
I have taken care to keep our local changes to the ZRLE
description.
Cheers,
Peter
commit 6ddabeffa4b5d865c8d570082c9c3368d64201e7
Author: Peter Rosin <p...@lysator.liu.se>
Date: Thu Oct 8 19:23:02 2009 +0200
Adapt TRLE description from the Internet draft.
Signed-off-by: Peter Rosin <p...@lysator.liu.se>
diff --git a/rfbproto.rst b/rfbproto.rst
index 33b035f..515224f 100644
--- a/rfbproto.rst
+++ b/rfbproto.rst
@@ -1696,6 +1696,7 @@ Number Name
6 `zlib Encoding`_
7 `Tight Encoding`_
8 `zlibhex Encoding`_
+15 `TRLE Encoding`_
16 `ZRLE Encoding`_
-23 to -32 `JPEG Quality Level Pseudo-encoding`_
-223 `DesktopSize Pseudo-encoding`_
@@ -1713,7 +1714,6 @@ Other registered encodings are:
=========================== ===========================================
Number Name
=========================== ===========================================
-15 TRLE
17 Hitachi ZYWRLE
-1 to -22 Tight options
-33 to -222 Tight options
@@ -2228,6 +2228,161 @@ subencoding.
If neither the **ZlibRaw** nor the **Zlib** bit is set, the
subrectangle follows the rules described in the `Hextile Encoding`_.
+TRLE Encoding
+-------------
+
+TRLE stands for Tiled Run-Length Encoding, and combines tiling,
+palettisation and run-length encoding. The rectangle is divided into
+tiles of 16x16 pixels in left-to-right, top-to-bottom order, similar to
+hextile. If the width of the rectangle is not an exact multiple of 16
+then the width of the last tile in each row is smaller, and if the
+height of the rectangle is not an exact multiple of 16 then the height
+of each tile in the final row is smaller.
+
+TRLE makes use of a new type ``CPIXEL`` (compressed pixel). This is the
+same as a ``PIXEL`` for the agreed pixel format, except as a special
+case, it uses a more compact format if *true-colour-flag* is non-zero,
+*bits-per-pixel* is 32, *depth* is 24 or less and all of the bits
+making up the red, green and blue intensities fit in either the least
+significant 3 bytes or the most significant 3 bytes. In this case, a
+``CPIXEL`` is only 3 bytes long, and contains the least significant or
+the most significant 3 bytes as appropriate. *bytesPerCPixel* is the
+number of bytes in a ``CPIXEL``.
+
+Note that for the corner case where *bits-per-pixel* is 32 and *depth*
+is 16 or less (this is a corner case, since the client is **much**
+better off using 16 or even 8 *bits-per-pixels*) a ``CPIXEL`` is still
+3 bytes long. By convention, the three least significant bytes are used
+when both the three least and the three most significant bytes would
+cover the used bits.
+
+Each tile begins with a subencoding type byte. The top bit of this
+byte is set if the tile has been run-length encoded, clear otherwise.
+The bottom seven bits indicate the size of the palette used: zero means
+no palette, one means that the tile is of a single color, and 2 to 127
+indicate a palette of that size. The special values 129 and 127
+indicate that the palette is to be reused from the previous tile, with
+and without RLE respectively.
+
+Note: in this discussion, the div(a,b) function means the result of
+dividing a/b truncated to an integer.
+
+The possible values of subencoding are:
+
+0
+ Raw pixel data. *width* * *height* pixel values follow (where width
+ and height are the width and height of the tile):
+
+ ====================================== ================ ===========
+ No. of bytes Type Description
+ ====================================== ================ ===========
+ *width* * *height* * *bytesPerCPixel* ``CPIXEL`` array *pixels*
+ ====================================== ================ ===========
+
+1
+ A solid tile consisting of a single colour. The pixel value
+ follows:
+
+ ========================== ============= ==========================
+ No. of bytes Type Description
+ ========================== ============= ==========================
+ *bytesPerCPixel* ``CPIXEL`` *pixelValue*
+ ========================== ============= ==========================
+
+2 to 16
+ Packed palette types. The *paletteSize* is the value of the
+ *subencoding*, which is followed by the palette, consisting of
+ *paletteSize* pixel values. The packed pixels follow, with each
+ pixel represented as a bit field yielding a 0-based index into the
+ palette. For *paletteSize* 2, a 1-bit field is used, for
+ *paletteSize* 3 or 4 a 2-bit field is used, and for *paletteSize*
+ from 5 to 16 a 4-bit field is used. The bit fields are packed into
+ bytes, with the most significant bits representing the leftmost
+ pixel (i.e. big endian). For tiles not a multiple of 8, 4 or 2
+ pixels wide (as appropriate), padding bits are used to align each
+ row to an exact number of bytes.
+
+ ================================= ================== ==============
+ No. of bytes Type Description
+ ================================= ================== ==============
+ *paletteSize* * *bytesPerCPixel* ``CPIXEL`` array *palette*
+ *m* ``U8`` array *packedPixels*
+ ================================= ================== ==============
+
+ where *m* is the number of bytes representing the packed pixels.
+ For *paletteSize* of 2 this is div(*width* + 7, 8) * *height*, for
+ *paletteSize* of 3 or 4 this is div(*width* + 3, 4) * *height*, for
+ *paletteSize* of 5 to 16 this is div(*width* + 1, 2) * *height*.
+
+17 to 126
+ Unused. (Packed palettes of these sizes would offer no advantage
+ over palette RLE).
+
+127
+ Packed palette with the palette reused from the previous tile. The
+ subencoding byte is followed by the packed pixels as described
+ above for packed palette types.
+
+128
+ Plain RLE. Consists of a number of runs, repeated until the tile is
+ done. Runs may continue from the end of one row to the beginning of
+ the next. Each run is a represented by a single pixel value
+ followed by the length of the run. The length is represented as one
+ or more bytes. The length is calculated as one more than the sum of
+ all the bytes representing the length. Any byte value other than
+ 255 indicates the final byte. So for example length 1 is
+ represented as [0], 255 as [254], 256 as [255,0], 257 as [255,1],
+ 510 as [255,254], 511 as [255,255,0] and so on.
+
+ =================== =============== ======= =======================
+ No. of bytes Type [Value] Description
+ =================== =============== ======= =======================
+ *bytesPerCPixel* ``CPIXEL`` *pixelValue*
+ *r* ``U8`` array 255
+ 1 ``U8`` (*runLength* - 1) % 255
+ =================== =============== ======= =======================
+
+ Where *r* is div(*runLength* - 1, 255).
+
+129
+ Palette RLE with the palette reused from the previous tile.
+ Followed by a number of runs, repeated until the tile is done, as
+ described below for 130 to 255.
+
+130 to 255
+ Palette RLE. Followed by the palette, consisting of
+ *paletteSize* = (*subencoding* - 128) pixel values:
+
+ ================================= ================== ==============
+ No. of bytes Type Description
+ ================================= ================== ==============
+ *paletteSize* * *bytesPerCPixel* ``CPIXEL`` array *palette*
+ ================================= ================== ==============
+
+ Following the palette is, as with plain RLE, of a number of runs,
+ repeated until the tile is done. A run of length one is
+ represented simply by a palette index:
+
+ ================================= ================== ==============
+ No. of bytes Type Description
+ ================================= ================== ==============
+ 1 ``U8`` *paletteIndex*
+ ================================= ================== ==============
+
+ A run of length more than one is represented by a palette index
+ with the top bit set, followed by the length of the run as for
+ plain RLE.
+
+ =================== =============== ======= =======================
+ No. of bytes Type [Value] Description
+ =================== =============== ======= =======================
+ 1 ``U8`` *paletteIndex* + 128
+ *r* ``U8`` array 255
+ 1 ``U8`` (*runLength* - 1) % 255
+ =================== =============== ======= =======================
+
+ Where *r* is div(*runLength* - 1, 255).
+
ZRLE Encoding
-------------
commit 3f3b531127b9b75aed262eb25c8404b13471cd53
Author: Peter Rosin <p...@lysator.liu.se>
Date: Thu Oct 8 19:24:00 2009 +0200
Reuse TRLE in the description of ZRLE.
Signed-off-by: Peter Rosin <p...@lysator.liu.se>
diff --git a/rfbproto.rst b/rfbproto.rst
index 515224f..1e3963f 100644
--- a/rfbproto.rst
+++ b/rfbproto.rst
@@ -2409,134 +2409,9 @@ tile in each row is smaller, and if the height of the
rectangle is not
an exact multiple of 64 then the height of each tile in the final row
is smaller.
-ZRLE makes use of a new type ``CPIXEL`` (compressed 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
-or less and all of the bits making up the red, green and blue
-intensities fit in either the least significant 3 bytes or the most
-significant 3 bytes. In this case a ``CPIXEL`` is only 3 bytes long,
-and contains the least significant or the most significant 3 bytes as
-appropriate. *bytesPerCPixel* is the number of bytes in a ``CPIXEL``.
-
-Note that for the corner case where *bits-per-pixel* is 32 and *depth*
-is 16 or less (this is a corner case, since the client is **much**
-better off using 16 or even 8 *bits-per-pixels*) a ``CPIXEL`` is still
-3 bytes long. By convention, the three least significant bytes are used
-when both the three least and the three most significant bytes would
-cover the used bits.
-
-Each tile begins with a *subencoding* type byte. The top bit of this
-byte is set if the tile has been run-length encoded, clear otherwise.
-The bottom seven bits indicate the size of the palette used: zero means
-no palette, one means that the tile is of a single colour, 2 to 127
-indicate a palette of that size. The possible values of *subencoding*
-are:
-
-0
- Raw pixel data. *width* * *height* pixel values follow (where width
- and height are the width and height of the tile):
-
- ====================================== ================ ===========
- No. of bytes Type Description
- ====================================== ================ ===========
- *width* * *height* * *bytesPerCPixel* ``CPIXEL`` array *pixels*
- ====================================== ================ ===========
-
-1
- A solid tile consisting of a single colour. The pixel value
- follows:
-
- ========================== ============= ==========================
- No. of bytes Type Description
- ========================== ============= ==========================
- *bytesPerCPixel* ``CPIXEL`` *pixelValue*
- ========================== ============= ==========================
-
-2 to 16
- Packed palette types. Followed by the palette, consisting of
- *paletteSize* (=*subencoding*) pixel values. Then the packed pixels
- follow, each pixel represented as a bit field yielding an index
- into the palette (0 meaning the first palette entry). For
- *paletteSize* 2, a 1-bit field is used, for *paletteSize* 3 or 4 a
- 2-bit field is used and for *paletteSize* from 5 to 16 a 4-bit
- field is used. The bit fields are packed into bytes, the most
- significant bits representing the leftmost pixel (i.e. big endian).
- For tiles not a multiple of 8, 4 or 2 pixels wide (as appropriate),
- padding bits are used to align each row to an exact number of bytes.
-
- ================================= ================== ==============
- No. of bytes Type Description
- ================================= ================== ==============
- *paletteSize* * *bytesPerCPixel* ``CPIXEL`` array *palette*
- *m* ``U8`` array *packedPixels*
- ================================= ================== ==============
-
- where *m* is the number of bytes representing the packed pixels.
- For *paletteSize* of 2 this is floor((*width* + 7) / 8) * *height*,
- for *paletteSize* of 3 or 4 this is
- floor((*width* + 3) / 4) * *height*, for *paletteSize* of 5 to 16
- this is floor((*width* + 1) / 2) * *height*.
-
-17 to 127
- Unused (no advantage over palette RLE).
-
-128
- Plain RLE. Consists of a number of runs, repeated until the tile is
- done. Runs may continue from the end of one row to the beginning of
- the next. Each run is a represented by a single pixel value
- followed by the length of the run. The length is represented as one
- or more bytes. The length is calculated as one more than the sum of
- all the bytes representing the length. Any byte value other than
- 255 indicates the final byte. So for example length 1 is
- represented as [0], 255 as [254], 256 as [255,0], 257 as [255,1],
- 510 as [255,254], 511 as [255,255,0] and so on.
-
- =================== =============== ======= =======================
- No. of bytes Type [Value] Description
- =================== =============== ======= =======================
- *bytesPerCPixel* ``CPIXEL`` *pixelValue*
- *r* ``U8`` array 255
- 1 ``U8`` (*runLength* - 1) % 255
- =================== =============== ======= =======================
-
- Where *r* is floor((*runLength* - 1) / 255).
-
-129
- Unused.
-
-130 to 255
- Palette RLE. Followed by the palette, consisting of
- *paletteSize* = (*subencoding* - 128) pixel values:
-
- ================================= ================== ==============
- No. of bytes Type Description
- ================================= ================== ==============
- *paletteSize* * *bytesPerCPixel* ``CPIXEL`` array *palette*
- ================================= ================== ==============
-
- Then as with plain RLE, consists of a number of runs, repeated
- until the tile is done. A run of length one is represented simply
- by a palette index:
-
- ================================= ================== ==============
- No. of bytes Type Description
- ================================= ================== ==============
- 1 ``U8`` *paletteIndex*
- ================================= ================== ==============
-
- A run of length more than one is represented by a palette index
- with the top bit set, followed by the length of the run as for
- plain RLE.
-
- =================== =============== ======= =======================
- No. of bytes Type [Value] Description
- =================== =============== ======= =======================
- 1 ``U8`` *paletteIndex* + 128
- *r* ``U8`` array 255
- 1 ``U8`` (*runLength* - 1) % 255
- =================== =============== ======= =======================
-
- Where *r* is floor((*runLength* - 1) / 255).
+The tiles are encoded in exactly the same way as TRLE, except that
+*subencoding* may not take the values 127 or 129, i.e. palettes cannot
+be reused between tiles.
Pseudo-encodings
++++++++++++++++
commit 121efcea46b22b497efc08fa158012c23edbb8f0
Author: Peter Rosin <p...@lysator.liu.se>
Date: Thu Oct 8 19:24:33 2009 +0200
Use wording of ZRLE description from the Internet draft.
Signed-off-by: Peter Rosin <p...@lysator.liu.se>
diff --git a/rfbproto.rst b/rfbproto.rst
index 1e3963f..bfa2034 100644
--- a/rfbproto.rst
+++ b/rfbproto.rst
@@ -2386,12 +2386,12 @@ The possible values of subencoding are:
ZRLE Encoding
-------------
-ZRLE stands for Zlib [#]_ Run-Length Encoding, and combines zlib
-compression, tiling, palettisation and run-length encoding. On the
-wire, the rectangle begins with a 4-byte length field, and is followed
-by that many bytes of zlib-compressed data. A single zlib "stream"
-object is used for a given RFB protocol connection, so that ZRLE
-rectangles must be encoded and decoded strictly in order.
+ZRLE stands for Zlib [#]_ Run-Length Encoding, and combines an encoding
+similar to TRLE with zlib compression. On the wire, the message
+consists of zlib-compressed data which continues until the end of the
+message. A single zlib "stream" object is used for a given RFB protocol
+connection, so that ZRLE rectangles must be encoded and decoded
+strictly in order.
.. [#] see http://www.gzip.org/zlib/
@@ -2402,17 +2402,24 @@ No. of bytes Type Description
*length* ``U8`` array *zlibData*
=============== =================== ===================================
-The *zlibData* when uncompressed represents tiles of 64x64 pixels in
-left-to-right, top-to-bottom order, similar to hextile. If the width of
-the rectangle is not an exact multiple of 64 then the width of the last
-tile in each row is smaller, and if the height of the rectangle is not
-an exact multiple of 64 then the height of each tile in the final row
-is smaller.
+The *zlibData* when uncompressed represents tiles in left-to-right,
+top-to-bottom order, similar to TRLE, but with a tile size of 64x64
+pixels. If the width of the rectangle is not an exact multiple of 64
+then the width of the last tile in each row is smaller, and if the
+height of the rectangle is not an exact multiple of 64 then the height
+of each tile in the final row is smaller.
The tiles are encoded in exactly the same way as TRLE, except that
*subencoding* may not take the values 127 or 129, i.e. palettes cannot
be reused between tiles.
+The server flushes the zlib stream to a byte boundary at the end of
+each ZRLE encoded rectangle. It need not flush the stream between tiles
+within a rectangle. Since the zlibData for a single rectangle can
+potentially be quite large, clients can incrementally decode and
+interpret the zlibData but must not assume that encoded tile data is
+byte aligned.
+
Pseudo-encodings
++++++++++++++++
------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
tigervnc-rfbproto mailing list
tigervnc-rfbproto@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/tigervnc-rfbproto
