3.2.5.1.1.1 Processing Primary Drawing Orders

  • Article

All primary drawing orders MUST conform to the structure and rules defined in section 2.2.2.2.1.1.2.

To efficiently decode and process a primary drawing order, the client MUST use a Primary Drawing Order History (section 3.2.1.1) store. This store holds three pieces of information:

  • Last primary order type processed

  • Current bounding rectangle

  • Per-order record of the last value received for each field

These stored records allow the client to correctly decode a received primary drawing order, as only fields that have new values are required to be included in orders sent by the server. If a field is unchanged from the value that it had when the order type was last sent, it SHOULD NOT be included in the order. The fields that are present in the order MUST be indicated by the fieldFlags field.

If all of the Coord-type fields (see section 2.2.2.2.1.1.1.1) in an order can be represented as a signed delta in the range -127 to 128 from the previous field value, all of these fields SHOULD contain delta-coordinates (see sections 2.2.2.2.1.1.1.1 and 2.2.2.2.1.1.1.2). The presence of delta-coordinates MUST be indicated by the TS_DELTA_COORDINATES (0x10) flag in the primary drawing header.

The basic process to decode a primary drawing order begins with reading the controlFlags header byte (this is common to all drawing classes) to determine the order class. If order is a primary drawing order, the following sequence of steps SHOULD be used to decode the order:

  1. The control flags extract the following information:

    • Whether or not the order type is specified

    • The fields that are present in the primary order field data

    • Whether or not any components of the bounding rectangle are present

    • Whether or not delta-coordinates are used in the primary order Coord-type fields

  2. If support for the primary drawing order was not specified in the Order Capability Set (see [MS-RDPBCGR] section 2.2.7.1.3), the client SHOULD ignore the order, and processing SHOULD cease.

  3. Determine whether or not all of the data required to decode and process the order has been received in the Orders Update (section 2.2.2.1) structure or the Fast-Path Orders Update (section 2.2.2.2) structure. If the packet does not contain enough data, processing SHOULD cease, and the order update SHOULD be ignored.

  4. Read the order data, and validate the fields to make sure all the field data is consistent with the order specification (for example, the maximum number of fields and maximum order size MUST conform to the order specification). If any of the field data for a given order is inconsistent or refers to non-existent or invalid items (such as a non-existent cache entry or invalid brush format), processing of the order SHOULD terminate, and it SHOULD also be ignored.

Once the order has been decoded, and all of the information necessary to process it has been collected, the data MUST be handed off to a graphics rendering module so that the images from the remote system can be displayed locally on the client system. The client MUST also update the records in the Primary Drawing Order History (section 3.3.1.2) to ensure that future orders can be decoded correctly.