On Thu, 23 Apr 2009 14:25:52 +0200 Pierre Ossman <oss...@cendio.se> wrote:
> On Wed, 22 Apr 2009 16:34:51 +0200 > Pierre Ossman <oss...@cendio.se> wrote: > > > - Clarify DesktopSize behaviour based on a survey of the major VNC > > implementations. > > Thinking more about this, I now believe that the RealVNC > implementation of DesktopSize is broken and incompatible with the > earlier implementations like tight, as well as gtk-vnc. > A new version reflecting the stricter requirements needed to be compatible with those clients: [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. The update containing the pseudo- rectangle must not contain any rectangles that change the framebuffer data. 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. Also note that some servers send framebuffer data changes before the DesktopSize pseudo-rectangle. A client that wishes to be compatible with these servers must either retain the framebuffer contents as the dimensions change, or make sure that the next FrameBufferUpdateRequest has incremental set to zero. As some clients send a FramebufferUpdateRequest with incremental set to zero, because of the issue above, the server must not send a new DesktopSize pseudo-rectangle in the following update. 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. A consequence of this is that a client must not respond to a ExtendedDesktopSize rectangle by sending a FramebufferUpdateRequest with incremental set to zero. Doing so would make the system go into an infinite loop. 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 a ExtendedDesktopSize rectangle, where the result is that the framebuffer size will change and the data be discarded, must not contain any rectangles that modify the framebuffer data. A ExtendedDesktopSize rectangle where only the screen configuration is modified can however freely be combined with rectangles that modify the framebuffer data. 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
