In case someone has already started looking at implementing this, here's another update.
Changed: - Official numbers allocated. - Some minor clarifications for when both DesktopSize and ExtendedDesktopSize are used, for replies to SetDesktopSize and for the flags. - Require that the ExtendedDesktopSize is sent without any data updates. - Clarify DesktopSize behaviour based on a survey of the major VNC implementations. New version: [2.1 Screen Model] In its simplest form, the RFB protocol uses a single, rectangular framebuffer. All updates are contained within this buffer and may not extend outside of it. A client with basic functionality simply presents this buffer to the user, padding or cropping it as necessary to fit the user's display. More advanced RFB clients and servers have the ability to extend this model and add multiple screens. The purpose being to create a server-side representation of the client's physical layout. Applications can use this information to properly position themselves with regard to screen borders. In the multiple-screen model, there is still just a single framebuffer and framebuffer updates are unaffected by the screen layout. This assures compatibility between basic clients and advanced servers. Screens are added to this model and act like viewports into the framebuffer. A basic client acts as if there is a single screen covering the entire framebuffer. The server may support up to 255 screens, which must be contained fully within the current framebuffer. Multiple screens may overlap partially or completely. The client must keep track of the contents of the entire framebuffer, not just the areas currently covered by a screen. Similarly, the server is free to use encodings that rely on contents currently not visible inside any screen. For example it may issue a CopyRect rectangle from any part of the framebuffer. The client can request changes to the framebuffer size and screen layout. The server is free to approve or deny these requests at will, but must always inform the client of the result. See the SetDesktopSize message for details. If the framebuffer size changes, for whatever reason, then all data in it is invalidated and considered undefined. The server must not use any encoding that relies on the previous framebuffer contents and the client should request a full update. Note that this means that changing only the screen layout does not affect the framebuffer contents. The client must therefore keep track of the current framebuffer dimensions and compare it with the one received in the ExtendedDesktopSize rectangle. Only when they differ may it discard the framebuffer contents. [6.4 Client to server messages] 6.4.6 SetDesktopSize Requests a change of desktop size. This message is an extension and may only be sent if the client has previously received an ExtendedDesktopSize rectangle. The server must send an ExtendedDesktopSize rectangle for every SetDesktopSize message received. Several rectangles may be sent in a single FramebufferUpdate message, but the rectangles must not be merged or reordered in any way. Note that rectangles sent for other reasons may be interleaved with the ones generated as a result of SetDesktopSize messages. Upon a successful request the server must send an ExtendedDesktopSize rectangle to the requesting client with the exact same information the client provided in the corresponding SetDesktopSize message. The x-position must be set to 1, indicating a client initiated event, and the y-position must be set to 0, indicating success. The server must also send an ExtendedDesktopSize rectangle to all other connected clients, but with the x-position set to 2, indicating a change initiated by another client. If the server can not or will not satisfy the request, it must send an ExtendedDesktopSize rectangle to the requesting client with the x-position set to 1 and the y-position set to the relevant error code. All remaining fields are undefined, although the basic structure must still be followed. The server must not send an ExtendedDesktopSize rectangle to any other connected clients. All ExtendedDesktopSize rectangles that are sent as a result of a SetDesktopSize message should be sent as soon as possible. --------------------------------------------------------------- No. of bytes Type [Value] Description --------------------------------------------------------------- 1 U8 251 message-type 1 padding 2 U16 width 2 U16 height 1 U8 number-of-screens 1 padding number-of-screens * 8 SCREEN array of screens --------------------------------------------------------------- The width and height indicates the framebuffer size requested. This structure is followed by number-of-screens SCREEN structures, which is defined in section 6.7.3: ----------------------------------------- No. of bytes Type Description ----------------------------------------- 4 U32 id 2 U16 x-position 2 U16 y-position 2 U16 width 2 U16 height 4 U32 flags ----------------------------------------- The id field must be preserved upon modification as it determines the difference between a moved screen and a newly created one. The client should make every effort to preserve the fields it does not wish to modify, including any unknown flags bits. [6.7 Pseudo-encodings] 6.7.2 DesktopSize pseudo-encoding A client which requests the DesktopSize pseudo-encoding is declaring that it is capable of coping with a change in the framebuffer width and/or height. The server changes the desktop size by sending a pseudo-rectangle with the DesktopSize pseudo-encoding. This rectangle must not be followed by any changes to the framebuffer data. The server should also avoid sending any changes to the framebuffer before this rectangle as the client will discard the framebuffer contents as this rectangle is processed. Clients must however be prepared to deal with this scenario as there already exist servers that send the DesktopSize together with framebuffer data updates. The pseudo-rectangle's x-position and y-position are ignored, and width and height indicate the new width and height of the framebuffer. There is no further data associated with the pseudo-rectangle. The principle of one framebuffer update being a transition from one valid state to another does not hold for updates with the DesktopSize pseudo-rectangle. Clients should try to handle this gracefully, e.g. by showing a black framebuffer or delay the screen update until a proper update of the framebuffer contents has been received. Note that some early implementations require the DesktopSize rectangle to be the very last rectangle in an update. Servers should make every effort to support these. Some clients send a FramebufferUpdateRequest with incremental set to zero when they receive a DesktopSize pseudo-rectangle. Therefore the server must not send such a rectangle when it receives a FramebufferUpdateRequest with incremental set to zero as doing so would make the system go into an infinite loop. 6.7.3 ExtendedDesktopSize pseudo-encoding A client which requests the ExtendedDesktopSize pseudo-encoding is declaring that it is capable of coping with a change in the framebuffer width, height, and/or screen configuration. This encoding is used in conjunction with the SetDesktopSize message. If a server supports the ExtendedDesktopSize encoding, it must also have basic support for the SetDesktopSize message although it may deny all requests to change the screen layout. The ExtendedDesktopSize pseudo-encoding is designed to replace the simpler DesktopSize one. Servers and clients should support both for maximum compatibility, but a server must always send at least the extended version to a client asking for both. If both encodings are used, the framebuffer size specified must be identical. The server must send a ExtendedDesktopSize rectangle in response to a FramebufferUpdateRequest with incremental set to zero, assuming the client has requested the ExtendedDesktopSize pseudo encoding using the SetEncodings message. This requirement is needed so that the client has a reliable way of fetching the initial screen configuration, and to determine if the server supports the SetDesktopSize message. The server must also send a ExtendedDesktopSize rectangle in response to a SetDesktopSize message, indicating the result. For a full description of server behaviour as a result of the SetDesktopSize message, see 6.4.X. Rectangles sent as a result of a SetDesktopSize message must be sent as soon as possible. Rectangles sent for other reasons may be subjected to delays imposed by the server. An update containing an ExtendedDesktopSize rectangle must not contain any changes to the framebuffer data, neither before nor after the ExtendedDesktopSize rectangle. The pseudo-rectangle's x-position indicates the reason for the change: 0 - The screen layout was changed via non-RFB means on the server. For example the server may have provided means for server-side applications to manipulate the screen layout. This code is also used when the client sends a non-incremental FrameBufferUpdateRequest to learn the server's current state. 1 - The client receiving this message requested a change of the screen layout. The change may or may not have happened depending on server policy or available resources. The status code in the y-position field must be used to determine which. 2 - Another client requested a change of the screen layout and the server approved it. A rectangle with this code is never sent if the server denied the request. More reasons may be added in the future. Clients should treat an unknown value as a server-side change (i.e. as if the x-position was set to zero). The pseudo-rectangle's y-position indicates the status code for a change requested by a client: 0 = No error 1 = Resize is administratively prohibited 2 = Out of resources 3 = Invalid screen layout This field shall be set to zero by the server and ignored by clients when not defined. Other error codes may be added in the future and clients must treat them as an unknown failure. The width and height indicates the new width and height of the framebuffer. The encoding data is defined as: ------------------------------------------------- No. of bytes Type Description ------------------------------------------------- 1 U8 number-of-screens 3 padding number-of-screens * 8 SCREEN array of screens ------------------------------------------------- The number-of-screens field indicates the number of active screens and allows for multi head configurations. It also indicates how many SCREEN structures that follows. These are defined as: ----------------------------------------- No. of bytes Type Description ----------------------------------------- 4 U32 id 2 U16 x-position 2 U16 y-position 2 U16 width 2 U16 height 4 U32 flags ----------------------------------------- The id field contains an arbitrary value that the server and client can use to map RFB screens to physical screens. The value must be unique in the current set of screens and must be preserved for the lifetime of that RFB screen. New ids are assigned by whichever side creates the screen. An id may be reused if there has been a subsequent update without it. The flags field is currently unused. Clients and servers must ignore, but preserve, any bits it does not understand. For new screens, those bits must be set to zero. Note that a simple client which does not support multi head does not need to parse the list of screens and can simply display the entire framebuffer. -- Pierre Ossman OpenSource-based Thin Client Technology System Developer Telephone: +46-13-21 46 00 Cendio AB Web: http://www.cendio.com
signature.asc
Description: PGP signature
------------------------------------------------------------------------------ Stay on top of everything new and different, both inside and around Java (TM) technology - register by April 22, and save $200 on the JavaOne (SM) conference, June 2-5, 2009, San Francisco. 300 plus technical and hands-on sessions. Register today. Use priority code J9JMT32. http://p.sf.net/sfu/p
_______________________________________________ Tigervnc-devel mailing list Tigervnc-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/tigervnc-devel
