As you may or may not know, George Wright has been working on adding dynamic framebuffer resize to VNC. As part of this we've put together a suggestion on how the protocol should be extended to support this.
Now this suggestion is rather complex. The reason is that we want to avoid having to make another extension mechanism in the future, so we've crammed in support for multi-head at the same time. Our initial implementation will not support this properly, but we'd like to have a future proof protocol from day one. This suggestion is meant to be added to the rfbproto spec, so the heading numbers indicate where these things should show up in that document. Comment away! [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 in any way. 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 other fields must indicate the current state of the server. 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 Description ------------------------------------------------- 1 U8 7 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 ----------------------------------------- 2 U16 x-position 2 U16 y-position 2 U16 width 2 U16 height 4 U32 flags ----------------------------------------- The client should make every effort to preserve the fields it does not modify, including any unknown flags bits. [6.7 Pseudo-encodings] 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 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 requests the ExtendedDesktopSize pseudo encoding using SetEncodings. 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. The pseudo-rectangle's x-position indicates the reason for the change: 0 - The screen layout was changed via outside means on the server. For example the server may have provided means for server-side applications to manipulate the screen layout. 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 handle unknown values gracefully. The width and height indicates the new width and height of the framebuffer. The encoding data is defined as: ------------------------------------------------- No. of bytes Type Description ------------------------------------------------- 2 U16 x-min 2 U16 y-min 2 U16 x-max 2 U16 y-max 1 U8 number-of-screens 3 padding number-of-screens * 8 SCREEN array of screens ------------------------------------------------- The x-min, y-min, x-max, and y-max indicates server imposed limits of the framebuffer. The client can use this information to indicate to the user when resizing (using SetDesktopSize) is possible. 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 ----------------------------------------- 2 U16 x-position 2 U16 y-position 2 U16 width 2 U16 height 4 U32 flags ----------------------------------------- The flags field is currently unused. Clients and servers must ignore any bits it does not understand. 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
------------------------------------------------------------------------------
_______________________________________________ Tigervnc-devel mailing list Tigervnc-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/tigervnc-devel
