Developer World
Spresense SDK Library v3.2.0-ebc0364
rfb.h
1/****************************************************************************
2 * include/nuttx/video/rfb.h
3 *
4 * Licensed to the Apache Software Foundation (ASF) under one or more
5 * contributor license agreements. See the NOTICE file distributed with
6 * this work for additional information regarding copyright ownership. The
7 * ASF licenses this file to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance with the
9 * License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
16 * License for the specific language governing permissions and limitations
17 * under the License.
18 *
19 ****************************************************************************/
20
21#ifndef __INCLUDE_NUTTX_VIDEO_RFB_H
22#define __INCLUDE_NUTTX_VIDEO_RFB_H
23
24/****************************************************************************
25 * Included Files
26 ****************************************************************************/
27
28#include <nuttx/config.h>
29
30/****************************************************************************
31 * RFB Protocol
32 ****************************************************************************/
33
34/* 6.1 Hand shaking Messages ************************************************/
35
36/* 6.1.1 ProtocolVersion
37 *
38 * "Handshaking begins by the server sending the client a ProtocolVersion
39 * message. This lets the client know which is the highest RFB protocol
40 * version number supported by the server. The client then replies with a
41 * similar message giving the version number of the protocol which should
42 * actually be used (which may be different to that quoted by the server).
43 * A client should never request a protocol version higher than that
44 * offered by the server. It is intended that both clients and servers may
45 * provide some level of backwards compatibility by this mechanism.
46 *
47 * "The only published protocol versions at this time are 3.3, 3.7, 3.8
48 * (version 3.5 was wrongly reported by some clients, but this should be
49 * interpreted by all servers as 3.3). Addition of a new encoding or
50 * pseudo-encoding type does not require a change in protocol version,
51 * since a server can simply ignore encodings it does not understand.
52 *
53 * "The ProtocolVersion message consists of 12 bytes interpreted as a string
54 * of ASCII characters in the format "RFB xxx.yyy\n" where xxx and yyy are
55 * the major and minor version numbers, padded with zeros."
56 */
57
58#define RFB_PROTOCOL_VERSION_FMT "RFB %03d.%03d\n"
59#define RFB_PROTOCOL_VERSION_3p3 "RFB 003.003\n"
60#define RFB_PROTOCOL_VERSION_3p7 "RFB 003.007\n"
61#define RFB_PROTOCOL_VERSION_3p8 "RFB 003.008\n"
62
64{
65 uint8_t version[12]; /* U8 Version string */
66};
67
68/* 6.1.2 Security
69 *
70 * "Once the protocol version has been decided, the server and client must
71 * agree on the type of security to be used on the connection.
72 */
73
74#define RFB_SECTYPE_INVALID 0 /* Invalid */
75#define RFB_SECTYPE_NONE 1 /* None */
76#define RFB_SECTYPE_VNC 2 /* VNC Authentication */
77#define RFB_SECTYPE_RA2 5 /* RA2 */
78#define RFB_SECTYPE_RA2NE 6 /* RA2ne */
79#define RFB_SECTYPE_TIGHT 16 /* Tight */
80#define RFB_SECTYPE_ULTRA 17 /* Ultra */
81#define RFB_SECTYPE_TLS 18 /* TLS */
82#define RFB_SECTYPE_VENCRYPT 19 /* VeNCrypt */
83#define RFB_SECTYPE_GTK 20 /* GTK-VNC SASL */
84#define RFB_SECTYPE_MD5 21 /* MD5 hash authentication */
85#define RFB_SECTYPE_COLINDEAN 22 /* Colin Dean xvp */
86
87/* "Version 3.7 onwards The server lists the security types which it
88 * supports:"
89 */
90
92{
93 uint8_t ntypes; /* U8 Number of security types supported */
94 uint8_t type[1]; /* U8 Security types supported. Actual
95 * size if ntypes. */
96};
97
98#define SIZEOF_RFB_SUPPORTED_SECTYPES_S(n) \
99 (sizeof(struct rfb_supported_sectypes_s) + (n) - 1)
100
101/* "If the server listed at least one valid security type supported by the
102 * client, the client sends back a single byte indicating which security
103 * type is to be used on the connection:"
104 */
105
107{
108 uint8_t type; /* U8 The selected security type */
109};
110
111/* "If number-of-security-types is zero, then for some reason the connection
112 * failed (e.g. the server cannot support the desired protocol version).
113 * This is followed by a string describing the reason (where a string is
114 * specified as a length followed by that many ASCII characters):
115 */
116
118{
119 uint8_t len[4]; /* U32 Reason length */
120 uint8_t str[1]; /* U8 Reason string. Actual length is len. */
121};
122
123#define SIZEOF_RFB_SECTYPE_CONNFAIL_S(n) \
124 (sizeof(struct rfb_sectype_connfail_s) + (n) - 1)
125
126/* "Version 3.3 The server decides the security type and sends a single
127 * word:"
128 */
129
131{
132 uint8_t type[4]; /* U32 Security type */
133};
134
135/* "Once the security-type has been decided, data specific to that security-
136 * type follows (see section 6.2 for details). At the end of the security
137 * handshaking phase, the protocol normally continues with the
138 * SecurityResult message. Note that after the security handshaking phase,
139 * it is possible that further protocol data is over an encrypted or
140 * otherwise altered channel."
141 */
142
143/* 6.1.3 SecurityResult
144 *
145 * The server sends a word to inform the client whether the security
146 * handshaking was successful.
147 */
148
149#define RFB_SECTYPE_SUCCESS 0
150#define RFB_SECTYPE_FAIL 1
151
153{
154 uint8_t result[4]; /* U32 Security type result */
155};
156
157/* "If successful, the protocol passes to the initialization phase (section
158 * 6.3)."
159 *
160 * "Version 3.8 onwards If unsuccessful, the server sends a string
161 * describing the reason for the failure, and then closes the connection:
162 */
163
165{
166 uint8_t len[4]; /* U32 Reason length */
167 uint8_t str[1]; /* U8 Reason string. Actual length is len. */
168};
169
170#define SIZEOF_RFB_SECTYPE_FAIL_S(n) \
171 (sizeof(struct rfb_sectype_fail_s) + (n) - 1)
172
173/* "Version 3.3 and 3.7 If unsuccessful, the server closes the connection." */
174
175/* 6.2 Security Types *******************************************************/
176
177/* 6.2.1 None
178 *
179 * "No authentication is needed and protocol data is to be sent unencrypted.
180 *
181 * "Version 3.8 onwards The protocol continues with the SecurityResult
182 * message."
183 *
184 * "Version 3.3 and 3.7 The protocol passes to the initialization phase
185 * (section 6.3)."
186 *
187 * 6.2.2 VNC Authentication
188 *
189 * "VNC authentication is to be used and protocol data is to be sent
190 * unencrypted. The server sends a random 16-byte challenge:
191 */
192
194{
195 uint8_t challenge[16]; /* U8 Random challenge */
196};
197
198/* "The client encrypts the challenge with DES, using a password supplied by
199 * the user as the key, and sends the resulting 16-byte response:
200 */
201
203{
204 uint8_t response[16]; /* U8 Encrypted response */
205};
206
207/* The protocol continues with the SecurityResult message. */
208
209/* 6.3 Initialisation Messages **********************************************/
210
211/* 6.3.1 ClientInit
212 *
213 * "Once the client and server are sure that they’re happy to talk to one
214 * another using the agreed security type, the protocol passes to the
215 * initialization phase. The client sends a ClientInit message followed by
216 * the server sending a ServerInit message.
217 *
218 * "Shared-flag is non-zero (true) if the server should try to share the
219 * desktop by leaving other clients connected, zero (false) if it should
220 * give exclusive access to this client by disconnecting all other clients."
221 */
222
223#define RFB_FLAG_SHARED 0
224#define RFB_FLAG_EXCLUSIVE 1
225
227{
228 uint8_t shared; /* U8 Shared flag */
229};
230
231/* 6.3.2 ServerInit
232 *
233 * "After receiving the ClientInit message, the server sends a ServerInit
234 * message. This tells the client the width and height of the server’s
235 * framebuffer, its pixel format and the name associated with the desktop:
236 */
237
239{
240 uint8_t bpp; /* U8 bits-per-pixel */
241 uint8_t depth; /* U8 depth */
242 uint8_t bigendian; /* U8 big-endian-flag */
243 uint8_t truecolor; /* U8 true-colour-flag */
244 uint8_t rmax[2]; /* U16 red-max */
245 uint8_t gmax[2]; /* U16 green-max */
246 uint8_t bmax[2]; /* U16 blue-max */
247 uint8_t rshift; /* U8 red-shift */
248 uint8_t gshift; /* U8 green-shift */
249 uint8_t bshift; /* U8 blue-shift */
250 uint8_t padding[3];
251};
252
254{
255 uint8_t width[2]; /* U16 Framebuffer width */
256 uint8_t height[2]; /* U16 Framebuffer height */
257 struct rfb_pixelfmt_s format; /* Pixel format */
258 uint8_t namelen[4]; /* U32 Name length */
259 uint8_t name[1]; /* U8 Name (actual size if namelen) */
260};
261
262#define SIZEOF_RFB_SERVERINIT_S(n) \
263 (sizeof(struct rfb_serverinit_s) + (n) - 1)
264
265/* "Server-pixel-format specifies the server’s natural pixel format. This
266 * pixel format will be used unless the client requests a different format
267 * using the SetPixelFormat message (section 6.4.1).
268 *
269 * "Bits-per-pixel is the number of bits used for each pixel value on the
270 * wire. This must be greater than or equal to the depth which is the number
271 * of useful bits in the pixel value. Currently bits-per-pixel must be 8,
272 * 16 or 32—less than 8-bit pixels are not yet supported. Big-endian-flag
273 * is non-zero (true) if multi-byte pixels are interpreted as big endian.
274 * Of course this is meaningless for 8 bits-per-pixel.
275 *
276 * "If true-colour-flag is non-zero (true) then the last six items specify
277 * how to extract the red, green and blue intensities from the pixel value.
278 * Red-max is the maximum red value (= 2n − 1 where n is the number of
279 * bits used for red). Note this value is always in big endian order.
280 * Red-shift is the number of shifts needed to get the red value in a pixel
281 * to the least significant bit. Green-max, green-shift and blue-max,
282 * blue-shift are similar for green and blue. For example, to find the red
283 * value (between 0 and red-max) from a given pixel, do the following:
284 *
285 * - "Swap the pixel value according to big-endian-flag (e.g. if
286 * big-endian-flag is zero (false) and host byte order is big endian,
287 * then swap).
288 * - "Shift right by red-shift.
289 * - "AND with red-max (in host byte order).
290 *
291 * "If true-colour-flag is zero (false) then the server uses pixel values
292 * which are not directly composed from the red, green and blue intensities,
293 * but which serve as indices into a colour map. Entries in the colour map
294 * are set by the server using the SetColourMapEntries message (section
295 * 6.5.2)."
296 */
297
298/* 6.4 Client to Server Messages ********************************************/
299
300/* "The client to server message types defined in this document are: */
301
302#define RFB_SETPIXELFMT_MSG 0 /* SetPixelFormat */
303#define RFB_SETENCODINGS_MSG 2 /* SetEncodings */
304#define RFB_FBUPDATEREQ_MSG 3 /* FramebufferUpdateRequest */
305#define RFB_KEYEVENT_MSG 4 /* KeyEvent */
306#define RFB_POINTEREVENT_MSG 5 /* PointerEvent */
307#define RFB_CLIENTCUTTEXT_MSG 6 /* ClientCutText */
308
309/* 6.4.1 SetPixelFormat
310 *
311 * "Sets the format in which pixel values should be sent in FramebufferUpdate
312 * messages. If the client does not send a SetPixelFormat message then the
313 * server sends pixel values in its natural format as specified in the
314 * ServerInit message (section 6.3.2).
315 *
316 * "If true-colour-flag is zero (false) then this indicates that a "colour
317 * map" is to be used. The server can set any of the entries in the colour
318 * map using the SetColourMapEntries message (section 6.5.2). Immediately
319 * after the client has sent this message the colour map is empty, even if
320 * entries had previously been set by the server.
321 */
322
324{
325 uint8_t msgtype; /* U8 Message type */
326 uint8_t padding[3];
327 struct rfb_pixelfmt_s format; /* Pixel format */
328};
329
330/* 6.4.2 SetEncodings
331 *
332 * "Sets the encoding types in which pixel data can be sent by the server.
333 * The order of the encoding types given in this message is a hint by the
334 * client as to its preference (the first encoding specified being most
335 * preferred). The server may or may not choose to make use of this hint.
336 * Pixel data may always be sent in raw encoding even if not specified
337 * explicitly here.
338 *
339 * "In addition to genuine encodings, a client can request 'pseudo-
340 * encodings' to declare to the server that it supports certain extensions
341 * to the protocol. A server which does not support the extension will
342 * simply ignore the pseudo-encoding. Note that this means the client must
343 * assume that the server does not support the extension until it gets
344 * some extension-specific confirmation from the server.
345 *
346 * "See section 6.6 for a description of each encoding and section 6.7 for
347 * the meaning of pseudo-encodings."
348 */
349
351{
352 uint8_t msgtype; /* U8 Message type */
353 uint8_t padding;
354 uint8_t nencodings[2]; /* U16 Number of encodings */
355 uint8_t encodings[4]; /* S32 Encoding type, size = 4*nencodings */
356};
357
358#define SIZEOF_RFB_SETENCODINGS_S(n) \
359 (sizeof(struct rfb_setencodings_s) + ((n) == 0 ? -4 : ((n) - 1) << 2))
360
361/* 6.4.3 FramebufferUpdateRequest
362 *
363 * "Notifies the server that the client is interested in the area of the
364 * framebuffer specified by x-position, y-position, width and height. The
365 * server usually responds to a FramebufferUpdateRequest by sending a
366 * FramebufferUpdate. Note however that a single FramebufferUpdate may be
367 * sent in reply to several FramebufferUpdateRequests.
368 *
369 * "The server assumes that the client keeps a copy of all parts of the
370 * framebuffer in which it is interested. This means that normally the
371 * server only needs to send incremental updates to the client.
372 *
373 * "However, if for some reason the client has lost the contents of a
374 * particular area which it needs, then the client sends a
375 * FramebufferUpdateRequest with incremental set to zero (false). This
376 * requests that the server send the entire contents of the specified area
377 * as soon as possible. The area will not be updated using the CopyRect
378 * encoding.
379 *
380 * "If the client has not lost any contents of the area in which it is
381 * interested, then it sends a FramebufferUpdateRequest with incremental
382 * set to non-zero (true). If and when there are changes to the specified
383 * area of the framebuffer, the server will send a FramebufferUpdate. Note
384 * that there may be an indefinite period between the
385 * FramebufferUpdateRequest and the FramebufferUpdate.
386 *
387 * "In the case of a fast client, the client may want to regulate the rate
388 * at which it sends incremental FramebufferUpdateRequests to avoid hogging
389 * the network."
390 */
391
393{
394 uint8_t msgtype; /* U8 Message type */
395 uint8_t incremental; /* U8 Incremental */
396 uint8_t xpos[2]; /* U16 X-position */
397 uint8_t ypos[2]; /* U16 Y-position */
398 uint8_t width[2]; /* U16 Width */
399 uint8_t height[2]; /* U16 Height */
400};
401
402/* 6.4.4 KeyEvent
403 *
404 * "A key press or release. Down-flag is non-zero (true) if the key is now
405 * pressed, zero (false) if it is now released. The key itself is specified
406 * using the 'keysym' values defined by the X Window System.
407 */
408
410{
411 uint8_t msgtype; /* U8 Message type */
412 uint8_t down; /* U8 Down flag */
413 uint8_t padding[2];
414 uint8_t key[4]; /* U16 Key */
415};
416
417/* "The interpretation of keysyms is a complex area. In order to be as
418 * widely interoperable as possible the following guidelines should be
419 * used:
420 *
421 * - "The 'shift state' (i.e. whether either of the Shift keysyms are down)
422 * should only be used as a hint when interpreting a keysym. For
423 * example, on a US keyboard the ’#’ character is shifted, but on a
424 * UK keyboard it is not. A server with a US keyboard receiving a
425 * ’#’ character from a client with a UK keyboard will not have been
426 * sentany shift presses.
427 * In this case, it is likely that the server will internally need to
428 * 'fake' a shift press on its local system, in order to get a ’#’
429 * character and not, for example, a ’3’.
430 * - "The difference between upper and lower case keysyms is significant.
431 * This is unlike some of the keyboard processing in the X Window
432 * System which treats them as the same. For example, a server receiving
433 * an uppercase ’A’ keysym without any shift presses should
434 * interpret it as an uppercase ’A’.
435 * Again this may involve an internal ’fake’ shift press.
436 * - "Servers should ignore 'lock' keysyms such as CapsLock and NumLock
437 * where possible. Instead they should interpret each character-based
438 * keysym according to its case.
439 * - "Unlike Shift, the state of modifier keys such as Control and Alt
440 * should be taken as modifying the interpretation of other keysyms.
441 * Note that there are no keysyms for ASCII control characters such
442 * as ctrl-a - these should be generated by viewers sending a Control
443 * press followed by an ’a’ press.
444 * - "On a viewer where modifiers like Control and Alt can also be used to
445 * generate character-based keysyms, the viewer may need to send extra
446 * 'release' events in order that the keysym is interpreted correctly.
447 * For example, on a German PC keyboard, ctrl-alt-q generates the "@"
448 * character. In this case, the viewer needs to send 'fake' release
449 * events for Control and Alt in order that the ’@’ character is
450 * interpreted correctly (ctrl-alt-@is likely to mean something
451 * completely different to the server).
452 * - "There is no universal standard for 'backward tab' in the X Window
453 * System. On some systems shift+tab gives the keysym 'ISO Left Tab',
454 * on others it gives a private 'BackTab' keysym and on others it gives
455 * 'Tab' and applications tell from the shift state that it means
456 * backward-tab rather than forward-tab. In the RFB protocol the latter
457 * approach is preferred. Viewers should generate a shifted Tab rather
458 * than ISO Left Tab. However, to be backwards-compatible with existing
459 * viewers, servers should also recognise ISO Left Tab as meaning a
460 * shifted Tab."
461 */
462
463/* 6.4.5 PointerEvent
464 *
465 * "Indicates either pointer movement or a pointer button press or release.
466 * The pointer is now at (x-position, y-position), and the current state of
467 * buttons 1 to 8 are represented by bits 0 to 7 of button-mask
468 * respectively, 0 meaning up, 1 meaning down (pressed).
469 *
470 * "On a conventional mouse, buttons 1, 2 and 3 correspond to the left,
471 * middle and right buttons on the mouse. On a wheel mouse, each step of
472 * the wheel upwards is represented by a press and release of button 4, and
473 * each step downwards is represented by a press and release of button 5."
474 */
475
477{
478 uint8_t msgtype; /* U8 Message type */
479 uint8_t buttons; /* U8 Button mask */
480 uint8_t xpos[2]; /* U16 X-position */
481 uint8_t ypos[2]; /* U16 Y-position */
482};
483
484/* 6.4.6 ClientCutText
485 *
486 * "The client has new ISO 8859-1 (Latin-1) text in its cut buffer. Ends of
487 * lines are represented by the linefeed / newline character (value 10)
488 * alone. No carriage-return (value 13) is needed. There is currently no
489 * way to transfer text outside the Latin-1 character set.
490 */
491
493{
494 uint8_t msgtype; /* U8 Message type */
495 uint8_t padding[3];
496 uint8_t length[4]; /* U32 Length */
497 uint8_t text[1]; /* U8 Text, actual length is Length */
498};
499
500#define SIZEOF_RFB_CLIENTCUTTEXT_S(n) \
501 (sizeof(struct rfb_clientcuttext_s) + (n) - 1)
502
503/* 6.5 Server to Client Messages ********************************************/
504
505/* "The server to client message types defined in this document are:" */
506
507#define RFB_FBUPDATE_MSG 0 /* FramebufferUpdate */
508#define RFB_SETCOLORMAP_MSG 1 /* SetColourMapEntries */
509#define RFB_BELL_MSG 2 /* Bell */
510#define RFB_SERVERCUTTEXT_MSG 3 /* ServerCutText */
511
512/* 6.5.1 FramebufferUpdate
513 *
514 * "A framebuffer update consists of a sequence of rectangles of pixel data
515 * which the client should put into its framebuffer. It is sent in response
516 * to a FramebufferUpdateRequest from the client. Note that there may be an
517 * indefinite period between the FramebufferUpdateRequest and the
518 * FramebufferUpdate."
519 */
520
522{
523 uint8_t xpos[2]; /* U16 X position */
524 uint8_t ypos[2]; /* U16 Y position */
525 uint8_t width[2]; /* U16 Width */
526 uint8_t height[2]; /* U16 Height */
527 uint8_t encoding[4]; /* S32 Encoding type */
528 uint8_t data[1]; /* Pixel data, actual size varies */
529};
530
531#define SIZEOF_RFB_RECTANGE_S(d) \
532 (sizeof(struct rfb_rectangle_s) + (d) - 1)
533
535{
536 uint8_t msgtype; /* U8 Message type */
537 uint8_t padding;
538 uint8_t nrect[2]; /* U16 Number of rectangles */
539 struct rfb_rectangle_s rect[1]; /* Actual number is nrect */
540};
541
542#define SIZEOF_RFB_FRAMEBUFFERUPDATE_S(r) \
543 (sizeof(struct rfb_framebufferupdate_s) + (r) - sizeof(struct rfb_rectangle_s))
544
545/* 6.5.2 SetColourMapEntries
546 *
547 * "When the pixel format uses a 'colour map', this message tells the client
548 * that the specified pixel values should be mapped to the given RGB
549 * intensities."
550 */
551
553{
554 uint8_t r[2]; /* U16 red */
555 uint8_t g[2]; /* U16 green */
556 uint8_t b[2]; /* U16 blue */
557};
558
559#define RFB_RGB_SIZE(n) \
560 ((n) * sizeof(struct rfb_rgb_s))
561
563{
564 uint8_t msgtype; /* U8 Message type */
565 uint8_t padding;
566 uint8_t first[2]; /* U16 First colour */
567 uint8_t ncolors[2]; /* U16 Number of colours */
568 struct rfb_rgb_s color[1]; /* Colors, actual number is ncolors */
569};
570
571#define SIZEOF_RFB_SETCOLOURMAPENTRIES_S(n,r) \
572 (sizeof(struct rfb_setcolourmapentries_s) + RFB_RGB_SIZE((n) - 1))
573
574/* 6.5.3 Bell
575 *
576 * "Ring a bell on the client if it has one.
577 */
578
580{
581 uint8_t msgtype; /* U8 Message type */
582};
583
584/* 6.5.4 ServerCutText
585 *
586 * "The server has new ISO 8859-1 (Latin-1) text in its cut buffer. Ends of
587 * lines are represented by the linefeed / newline character (value 10)
588 * alone. No carriage-return (value 13) is needed. There is currently no
589 * way to transfer text outside the Latin-1 character set.
590 */
591
593{
594 uint8_t msgtype; /* U8 Message type */
595 uint8_t padding[3];
596 uint8_t length[4]; /* U32 Length */
597 uint8_t text[1]; /* U8 Text, actual length is Length */
598};
599
600#define SIZEOF_RFB_SERVERCUTTEXT_S(n) \
601 (sizeof(struct rfb_servercuttext_s) + (n) - 1)
602
603/* 6.6 Encodings ************************************************************/
604
605/* The encodings defined in this document are: */
606
607#define RFB_ENCODING_RAW 0 /* Raw */
608#define RFB_ENCODING_COPYRECT 1 /* CopyRect */
609#define RFB_ENCODING_RRE 2 /* RRE */
610#define RFB_ENCODING_HEXTILE 5 /* Hextile */
611#define RFB_ENCODING_ZRLE 16 /* ZRLE */
612#define RFB_ENCODING_CURSOR -239 /* Cursor pseudo-encoding */
613#define RFB_ENCODING_DESKTOP -223 /* DesktopSize pseudo-encoding */
614
615/* 6.6.1 Raw encoding
616 *
617 * "The simplest encoding type is raw pixel data. In this case the data
618 * consists of width x height pixel values (where width and height are the
619 * width and height of the rectangle). The values simply represent each
620 * pixel in left-to-right scanline order. All RFB clients must be able to
621 * cope with pixel data in this raw encoding, and RFB servers should only
622 * produce raw encoding unless the client specifically asks for some other
623 * encoding type.
624 */
625
626/* 6.6.2 CopyRect encoding
627 *
628 * "The CopyRect (copy rectangle) encoding is a very simple and efficient
629 * encoding which can be used when the client already has the same pixel
630 * data elsewhere in its framebuffer. The encoding on the wire simply
631 * consists of an X,Y coordinate. This gives a position in the framebuffer
632 * from which the client can copy the rectangle of pixel data. This can be
633 * used in a variety of situations, the most obvious of which are when the
634 * user moves a window across the screen, and when the contents of a window
635 * are scrolled. A less obvious use is for optimising drawing of text or
636 * other repeating patterns. An intelligent server may be able to send a
637 * pattern explicitly only once, and knowing the previous position of the
638 * pattern in the framebuffer, send subsequent occurrences of the same
639 * pattern using the CopyRect encoding."
640 */
641
643{
644 uint8_t xpos[2]; /* U16 Source x position */
645 uint8_t ypos[2]; /* U16 Source y position */
646};
647
648/* 6.6.3 RRE encoding
649 *
650 * "RRE stands for rise-and-run-length encoding and as its name implies, it
651 * is essentially a two-dimensional analogue of run-length encoding.
652 * RRE-encoded rectangles arrive at the client in a form which can be
653 * rendered immediately and efficiently by the simplest of graphics
654 * engines. RRE is not appropriate for complex desktops, but can be
655 * useful in some situations.
656 *
657 * "The basic idea behind RRE is the partitioning of a rectangle of pixel
658 * data into rectangular subregions (subrectangles) each of which consists
659 * of pixels of a single value and the union of which comprises the
660 * original rectangular region. The near-optimal partition of a given
661 * rectangle into such subrectangles is relatively easy to compute.
662 *
663 * "The encoding consists of a background pixel value, Vb (typically the
664 * most prevalent pixel value in the rectangle) and a count N, followed
665 * by a list of N subrectangles, each of which consists of a tuple
666 * < v, x, y, w, h > where v (6= Vb) is the pixel value, (x, y) are the
667 * coordinates of the subrectangle relative to the top-left corner of the
668 * rectangle, and (w, h) are the width and height of the subrectangle. The
669 * client can render the original rectangle by drawing a filled rectangle
670 * of the background pixel value and then drawing a filled rectangle
671 * corresponding to each subrectangle. On the wire, the data begins with
672 * the header:"
673 */
674
676{
677 uint8_t nsubrects[4]; /* U32 Number of sub-rectangle */
678 uint8_t pixel; /* U8 Background pixel */
679};
680
682{
683 uint8_t nsubrects[4]; /* U32 Number of sub-rectangle */
684 uint8_t pixel[2]; /* U16 Background pixel */
685};
686
688{
689 uint8_t nsubrects[4]; /* U32 Number of sub-rectangle */
690 uint8_t pixel[4]; /* U32 Background pixel */
691};
692
693/* "This is followed by number-of-subrectangles instances of the following
694 * structure:"
695 */
696
698{
699 uint8_t pixel; /* U8 sub-rect pixel value */
700 uint8_t xpos[2]; /* U16 X position */
701 uint8_t ypos[2]; /* U16 Y position */
702 uint8_t width[2]; /* U16 Width */
703 uint8_t height[2]; /* U16 Height */
704};
705
707{
708 uint8_t pixel[2]; /* U16 sub-rect pixel value */
709 uint8_t xpos[2]; /* U16 X position */
710 uint8_t ypos[2]; /* U16 Y position */
711 uint8_t width[2]; /* U16 Width */
712 uint8_t height[2]; /* U16 Height */
713};
714
716{
717 uint8_t pixel[4]; /* U32 sub-rect pixel value */
718 uint8_t xpos[2]; /* U16 X position */
719 uint8_t ypos[2]; /* U16 Y position */
720 uint8_t width[2]; /* U16 Width */
721 uint8_t height[2]; /* U16 Height */
722};
723
724/* 6.6.4 Hextile encoding
725 *
726 * "Hextile is a variation on the RRE idea. Rectangles are split up into
727 * 16x16 tiles, allowing the dimensions of the subrectangles to be
728 * specified in 4 bits each, 16 bits in total. The rectangle is split
729 * into tiles starting at the top left going in left-to-right, top-to-
730 * bottom order. The encoded contents of the tiles simply follow one another
731 * in the predetermined order. If the width of the whole rectangle is not
732 * an exact multiple of 16 then the width of the last tile in each row will
733 * be correspondingly smaller. Similarly if the height of the whole
734 * rectangle is not an exact multiple of 16 then the height of each tile in
735 * the final row will also be smaller.
736 *
737 * "Each tile is either encoded as raw pixel data, or as a variation on RRE.
738 * Each tile has a background pixel value, as before. The background pixel
739 * value does not need to be explicitly specified for a given tile if it is
740 * the same as the background of the previous tile. However the background
741 * pixel value may not be carried over if the previous tile was Raw. If all
742 * of the subrectangles of a tile have the same pixel value, this can be
743 * specified once as a foreground pixel value for the whole tile. As with
744 * the background, the foreground pixel value can be left unspecified,
745 * meaning it is carried over from the previous tile. The foreground pixel
746 * value may not be carried over if the previous tile had the Raw or
747 * SubrectsColoured bits set. It may, however, be carried over from a
748 * previous tile with the AnySubrects bit clear, as long as that tile
749 * itself carried over a valid foreground from its previous tile.
750 *
751 * "So the data consists of each tile encoded in order. Each tile begins
752 * with a subencoding type byte, which is a mask made up of a number of
753 * bits:"
754 */
755
756#define RFB_SUBENCODING_RAW 1 /* Raw */
757#define RFB_SUBENCODING_BACK 2 /* BackgroundSpecified*/
758#define RFB_SUBENCODING_FORE 4 /* ForegroundSpecified*/
759#define RFB_SUBENCODING_ANY 8 /* AnySubrects*/
760#define RFB_SUBENCODING_COLORED 16 /* SubrectsColoured*/
761
762/* "If the Raw bit is set then the other bits are irrelevant; width x height
763 * pixel values follow (where width and height are the width and height of
764 * the tile). Otherwise the other bits in the mask are as follows:
765 *
766 * "BackgroundSpecified - if set, a pixel value follows which specifies the
767 * background colour for this tile:"
768 */
769
771{
772 uint8_t pixel; /* U8 Background pixel value */
773};
774
776{
777 uint8_t pixel[2]; /* U16 Background pixel value */
778};
779
781{
782 uint8_t pixel[4]; /* U32 Background pixel value */
783};
784
785/* "The first non-raw tile in a rectangle must have this bit set. If this
786 * bit isn’t set then the background is the same as the last tile.
787 *
788 * "ForegroundSpecified - if set, a pixel value follows which specifies the
789 * foreground colour to be used for all subrectangles in this tile:"
790 */
791
793{
794 uint8_t pixel; /* U8 Foreground pixel value */
795};
796
798{
799 uint8_t pixel[2]; /* U16 Foreground pixel value */
800};
801
803{
804 uint8_t pixel[4]; /* U32 Foreground pixel value */
805};
806
807/* "If this bit is set then the SubrectsColoured bit must be zero.
808 *
809 * "AnySubrects - if set, a single byte follows giving the number of
810 * subrectangles following:"
811 */
812
814{
815 uint8_t nsubrects; /* U8 Number of sub-rectangles */
816};
817
818/* "If not set, there are no subrectangles (i.e. the whole tile is just
819 * solid background colour).
820 *
821 * "SubrectsColoured - if set then each subrectangle is preceded by a pixel
822 * value giving the colour of that subrectangle, so a subrectangle is:"
823 */
824
826{
827 uint8_t pixel; /* U8 Sub-rect pixel value */
828 uint8_t xy; /* U8 X and y position */
829 uint8_t wh; /* U8 Width and height */
830};
831
833{
834 uint8_t pixel[2]; /* U16 Sub-rect pixel value */
835 uint8_t xy; /* U8 X and y position */
836 uint8_t wh; /* U8 Width and height */
837};
838
840{
841 uint8_t pixel[4]; /* U32 Sub-rect pixel value */
842 uint8_t xy; /* U8 X and y position */
843 uint8_t wh; /* U8 Width and height */
844};
845
846/* "If not set, all subrectangles are the same colour, the foreground
847 * colour; if the ForegroundSpecified bit wasn’t set then the foreground
848 * is the same as the last tile. A subrectangle is:"
849 */
850
852{
853 uint8_t xy; /* U8 X and y position */
854 uint8_t wh; /* U8 Width and height */
855};
856
857/* "The position and size of each subrectangle is specified in two bytes,
858 * x-and-y-position and width-and-height. The most-significant four bits of
859 * x-and-y-position specify the X position, the least-significant specify
860 * the Y position. The most-significant four bits of width-and-height
861 * specify the width minus one, the least-significant specify the height
862 * minus one."
863 */
864
865/* 6.6.5 ZRLE encoding
866 *
867 * "ZRLE stands for Zlib1 Run-Length Encoding, and combines zlib
868 * compression, tiling, palettisation and run-length encoding. On the wire,
869 * the rectangle begins with a 4-byte length field, and is followed by that
870 * many bytes of zlib-compressed data. A single zlib 'stream' object is
871 * used for a given RFB protocol connection, so that ZRLE rectangles must
872 * be encoded and decoded strictly in order."
873 */
874
876{
877 uint8_t length[4]; /* U32 Length */
878 uint8_t data[1]; /* U8 zlibData, actual size is length */
879};
880
881#define SIZEOF_RFB_SRLE_S(n,r) \
882 (sizeof(struct rfb_srle_s) + (n) - 1)
883
884/* "The zlibData when uncompressed represents tiles of 64x64 pixels in
885 * left-to-right, top-to-bottom order, similar to hextile. If the width of
886 * the rectangle is not an exact multiple of 64 then the width of the last
887 * tile in each row is smaller, and if the height of the rectangle is not
888 * an exact multiple of 64 then the height of each tile in the final row
889 * is smaller.
890 *
891 * "ZRLE makes use of a new type CPIXEL (compressed pixel). This is the same
892 * as a PIXEL for the agreed pixel format, except where true-colour-flag is
893 * non-zero, bitsper-pixel is 32, depth is 24 or less and all of the bits
894 * making up the red, green and blue intensities fit in either the least
895 * significant 3 bytes or the most significant 3 bytes. In this case a
896 * CPIXEL is only 3 bytes long, and contains the least significant or the
897 * most significant 3 bytes as appropriate. bytesPerCPixel is the number of
898 * bytes in a CPIXEL.
899 *
900 * "Each tile begins with a subencoding type byte. The top bit of this byte
901 * is set if the tile has been run-length encoded, clear otherwise. The
902 * bottom seven bits indicate the size of the palette used - zero means no
903 * palette, one means that the tile is of a single colour, 2 to 127
904 * indicate a palette of that size. The possible values of subencoding are:"
905 */
906
907#define RFB_SUBENCODING_RAW 0 /* Raw pixel data */
908#define RFB_SUBENCODING_SOLID 1 /* A solid tile of a single color */
909#define RFB_SUBENCODING_PACKED1 2 /* Packed palette types */
910#define RFB_SUBENCODING_PACKED2 3
911#define RFB_SUBENCODING_PACKED3 4
912#define RFB_SUBENCODING_PACKED4 5
913#define RFB_SUBENCODING_PACKED5 6
914#define RFB_SUBENCODING_PACKED6 7
915#define RFB_SUBENCODING_PACKED7 8
916#define RFB_SUBENCODING_PACKED8 9
917#define RFB_SUBENCODING_PACKED9 10
918#define RFB_SUBENCODING_PACKED10 11
919#define RFB_SUBENCODING_PACKED11 12
920#define RFB_SUBENCODING_PACKED12 13
921#define RFB_SUBENCODING_PACKED13 14
922#define RFB_SUBENCODING_PACKED14 15
923#define RFB_SUBENCODING_PACKED15 16
924#define RFB_SUBENCODING_RLE 128 /* Plain RLE */
925#define RFB_SUBENCODING_PALRLE 129 /* Palette RLE */
926
927/* "Raw pixel data. width x height pixel values follow (where width and
928 * height are the width and height of the tile):"
929 */
930
932{
933 uint8_t pixels[1]; /* Actual size is w*h */
934};
935
936#define SIZEOF_RFB_RAWPIXEL8_S(n,r) \
937 (sizeof(struct rfb_rawpixel8_s) + (n) - 1)
938
940{
941 uint8_t pixels[2]; /* Actual size is 2*w*h */
942};
943
944#define SIZEOF_RFB_RAWPIXEL16_S(n,r) \
945 (sizeof(struct rfb_rawpixel16_s) + (((n) - 1) << 1))
946
948{
949 uint8_t pixels[4]; /* Actual size is 4*w*h */
950};
951
952#define SIZEOF_RFB_RAWPIXEL32_S(n,r) \
953 (sizeof(struct rfb_rawpixel32_s) + (((n) - 1) << 2))
954
955/* "A solid tile consisting of a single colour. The pixel value follows:" */
956
958{
959 uint8_t pixels; /* Pixel value */
960};
961
963{
964 uint8_t pixels[2]; /* Pixel value */
965};
966
968{
969 uint8_t pixels[4]; /* Pixel value */
970};
971
972/* "Packed palette types. Followed by the palette, consisting of
973 * paletteSize(= subencoding) pixel values. Then the packed pixels follow,
974 * each pixel represented as a bit field yielding an index into the palette
975 * (0 meaning the first palette entry). For paletteSize 2, a 1-bit field is
976 * used, for paletteSize 3 or 4 a 2-bit field is used and for paletteSize
977 * from 5 to 16 a 4-bit field is used. The bit fields are packed into bytes,
978 * the most significant bits representing the leftmost pixel (i.e. big
979 * endian). For tiles not a multiple of 8, 4 or 2 pixels wide (as
980 * appropriate), padding bits are used to align each row to an exact number
981 * of bytes."
982 *
983 * REVISIT: Difficult to represent since it is a variable length array of
984 * RGB pixels follow by the variable length array of packed pixels.
985 */
986
987/* "Plain RLE. Consists of a number of runs, repeated until the tile is
988 * done. Runs may continue from the end of one row to the beginning of the
989 * next. Each run is a represented by a single pixel value followed by the
990 * length of the run. The length is represented as one or more bytes. The
991 * length is calculated as one more than the sum of all the bytes
992 * representing the length. Any byte value other than 255 indicates the
993 * final byte. So for example length 1 is represented as [0], 255 as [254],
994 * 256 as [255,0], 257 as [255,1], 510 as [255,254], 511 as [255,255,0] and
995 * so on."
996 *
997 * REVISIT: Difficult to represent. Consists of (1) a color value, (2)
998 * a variable length array of data, followed by (3) the run length.
999 */
1000
1001/* "Palette RLE. Followed by the palette, consisting of paletteSize =
1002 * (subencoding − 128) pixel values:"
1003 */
1004
1006{
1007 uint8_t palette[1]; /* Actual size is palleteSize */
1008};
1009
1011{
1012 uint8_t palette[2]; /* Actual size is 2*palleteSize */
1013};
1014
1016{
1017 uint8_t palette[4]; /* Actual size is 4*palleteSize */
1018};
1019
1020/* Then as with plain RLE, consists of a number of runs, repeated until the
1021 * tile is done. A run of length one is represented simply by a palette
1022 * index:
1023 */
1024
1026{
1027 uint8_t index; /* U8 Palette Index */
1028};
1029
1030/* A run of length more than one is represented by a palette index with the
1031 * top bit set, followed by the length of the run as for plain RLE."
1032 *
1033 * REVISIT: See comment with similar plain RLE representation.
1034 */
1035
1036/* 6.7 Pseudo-Encodings *****************************************************/
1037
1038/* 6.7.1 Cursor pseudo-encoding
1039 *
1040 * "A client which requests the Cursor pseudo-encoding is declaring that it
1041 * is capable of drawing a mouse cursor locally. This can significantly
1042 * improve perceived performance over slow links. The server sets the
1043 * cursor shape by sending a pseudo-rectangle with the Cursor pseudo-
1044 * encoding as part of an update. The pseudo-rectangle’s x-position and
1045 * y-position indicate the hotspot of the cursor, and width and height
1046 * indicate the width and height of the cursor in pixels. The data consists
1047 * of width x height pixel values followed by a bitmask. The bitmask
1048 * consists of left-to-right, top-to-bottom scanlines, where each scanline
1049 * is padded to a whole number of bytes floor((width + 7)/8). Within each
1050 * byte the most significant bit represents the leftmost pixel, with a
1051 * 1-bit meaning the corresponding pixel in the cursor is valid."
1052 *
1053 * REVISIT: Also difficult to represent: A variable length pixel array
1054 * followed by a variable length bit mask.
1055 */
1056
1057/* 6.7.2 DesktopSize pseudo-encoding
1058 *
1059 * "A client which requests the DesktopSize pseudo-encoding is declaring
1060 * that it is capable of coping with a change in the framebuffer width
1061 * and/or height. The server changes the desktop size by sending a
1062 * pseudo-rectangle with the DesktopSize pseudo-encoding as the last
1063 * rectangle in an update. The pseudo-rectangle’s x-position and
1064 * y-position are ignored, and width and height indicate the new width and
1065 * height of the framebuffer. There is no further data associated with the
1066 * pseudo-rectangle.
1067 */
1068
1069/* Data Access Helpers ******************************************************/
1070
1071/* All multiple byte integers (other than pixel values themselves) are in
1072 * big endian order (most significant byte first). The following do not
1073 * depend on the endianness of the target nor that they depend on any data
1074 * alignment.
1075 */
1076
1077/* void rfb_putbe16(FAR uint8_t *dest, uint16_t value) */
1078
1079#define rfb_putbe16(d,v) \
1080 do \
1081 { \
1082 register FAR uint8_t *__d = (FAR uint8_t *)(d); \
1083 *__d++ = ((uint16_t)(v) >> 8); \
1084 *__d = ((uint16_t)(v) & 0xff); \
1085 } \
1086 while (0)
1087
1088/* uin16_t rfb_getbe16(FAR const uint8_t *src) */
1089
1090#define rfb_getbe16(s) \
1091 (((uint16_t)((s)[0]) << 8) | \
1092 (uint16_t)((s)[1]))
1093
1094/* void rfb_putbe32(FAR uint8_t *dest, uint32_t value) */
1095
1096#define rfb_putbe32(d,v) \
1097 do \
1098 { \
1099 register FAR uint8_t *__d = (FAR uint8_t *)(d); \
1100 *__d++ = ((uint32_t)(v) >> 24); \
1101 *__d++ = ((uint32_t)(v) >> 16) & 0xff; \
1102 *__d++ = ((uint32_t)(v) >> 8) & 0xff; \
1103 *__d = ((uint32_t)(v) & 0xff); \
1104 } \
1105 while (0)
1106
1107/* uint32_t rfb_getbe32(FAR const uint8_t *src) */
1108
1109#define rfb_getbe32(s) \
1110 (((uint32_t)((s)[0]) << 24) | \
1111 ((uint32_t)((s)[1]) << 16) | \
1112 ((uint32_t)((s)[2]) << 8) | \
1113 (uint32_t)((s)[3]))
1114
1115/* There are also cases where the client may request pixel data in its
1116 * little-endian format.
1117 */
1118
1119/* void rfb_putle16(FAR uint8_t *dest, uint16_t value) */
1120
1121#define rfb_putle16(d,v) \
1122 do \
1123 { \
1124 register FAR uint8_t *__d = (FAR uint8_t *)(d); \
1125 *__d++ = ((uint16_t)(v) & 0xff); \
1126 *__d = ((uint16_t)(v) >> 8); \
1127 } \
1128 while (0)
1129
1130/* uin16_t rfb_getle16(FAR const uint8_t *src) */
1131
1132#define rfb_getle16(s) \
1133 (((uint16_t)((s)[1]) << 8) | \
1134 (uint16_t)((s)[0]))
1135
1136/* void rfb_putle32(FAR uint8_t *dest, uint32_t value) */
1137
1138#define rfb_putle32(d,v) \
1139 do \
1140 { \
1141 register FAR uint8_t *__d = (FAR uint8_t *)(d); \
1142 *__d++ = ((uint32_t)(v) & 0xff); \
1143 *__d++ = ((uint32_t)(v) >> 8) & 0xff; \
1144 *__d++ = ((uint32_t)(v) >> 16) & 0xff; \
1145 *__d = ((uint32_t)(v) >> 24); \
1146 } \
1147 while (0)
1148
1149/* uint32_t rfb_getle32(FAR const uint8_t *src) */
1150
1151#define rfb_getle32(s) \
1152 (((uint32_t)((s)[3]) << 24) | \
1153 ((uint32_t)((s)[2]) << 16) | \
1154 ((uint32_t)((s)[1]) << 8) | \
1155 (uint32_t)((s)[0]))
1156
1157/****************************************************************************
1158 * Public Function Prototypes
1159 ****************************************************************************/
1160
1161#ifdef __cplusplus
1162#define EXTERN extern "C"
1163extern "C"
1164{
1165#else
1166#define EXTERN extern
1167#endif
1168
1169#undef EXTERN
1170#ifdef __cplusplus
1171}
1172#endif
1173
1174#endif /* __INCLUDE_NUTTX_VIDEO_RFB_H */
Definition: rfb.h:776
Definition: rfb.h:781
Definition: rfb.h:771
Definition: rfb.h:580
Definition: rfb.h:194
Definition: rfb.h:493
Definition: rfb.h:227
Definition: rfb.h:643
Definition: rfb.h:393
Definition: rfb.h:798
Definition: rfb.h:803
Definition: rfb.h:793
Definition: rfb.h:535
Definition: rfb.h:410
Definition: rfb.h:814
Definition: rfb.h:1011
Definition: rfb.h:1016
Definition: rfb.h:1006
Definition: rfb.h:1026
Definition: rfb.h:239
Definition: rfb.h:477
Definition: rfb.h:64
Definition: rfb.h:940
Definition: rfb.h:948
Definition: rfb.h:932
Definition: rfb.h:522
Definition: rfb.h:203
Definition: rfb.h:553
Definition: rfb.h:682
Definition: rfb.h:688
Definition: rfb.h:676
Definition: rfb.h:707
Definition: rfb.h:716
Definition: rfb.h:698
Definition: rfb.h:118
Definition: rfb.h:165
Definition: rfb.h:153
Definition: rfb.h:131
Definition: rfb.h:107
Definition: rfb.h:593
Definition: rfb.h:254
Definition: rfb.h:563
Definition: rfb.h:351
Definition: rfb.h:324
Definition: rfb.h:963
Definition: rfb.h:968
Definition: rfb.h:958
Definition: rfb.h:876
Definition: rfb.h:852
Definition: rfb.h:833
Definition: rfb.h:840
Definition: rfb.h:826
Definition: rfb.h:92