[Interest] QCborValue and Qt types
Thiago Macieira
thiago.macieira at intel.com
Sat Dec 1 18:21:49 CET 2018
On Saturday, 1 December 2018 03:54:35 PST Konstantin Shegunov wrote:
> Hello,
> I'm evaluating Qt's (5.12) cbor implementation for a network transmission
> protocol. I saw that few Qt types were tagged already (I imagine as a proof
> of concept/preview). Are there plans to extend these to include more types
> (e.g. QImage) or should I just stick to writing them as binary buffers?
> As a follow-up what is the suggested way to pass *custom* types to QCbor*,
> are they to be streamed through QVariant?
Yes and no. See the attached draft spec (tag numbers are outdated) for a few
types I had been thinking of and already have an implementation for. Which
also reminds me I needed to send them to the CBOR IETF group for review.
I was thinking of sticking at first to QtCore types, so QImage will not be
included. I'm not even sure how we could add support for types in other
libraries; possibly you'll need to register a serialisation and
deserialisation function like qRegisterStreamOperators does.
And also note that we'll never get actual matching to Qt types. Like in the
attached geometry proposal, there's one type for size, not one for size and
one for size-float. This is important if you look at classes that are
identical but of different generations, like QVector4D and QQuaternion, or
worse functionally identical ones like QPixmap, QBitmap and QImage. We won't
get a standard tag that distinguishes them, since that distinction is not
useful outside of Qt. I'm open to ideas on how we can address that.
--
Thiago Macieira - thiago.macieira (AT) intel.com
Software Architect - Intel Open Source Technology Center
-------------- next part --------------
========================
(Screen) geometric types
========================
This document specifies tags for geometry objects in `Concise Binary Object
Representation (CBOR)`_, mostly intended for use in manipulating objects on a
computer screen.
**Point (screen coordinate)**::
Tag: 40
Data item: array
Semantics: A point in the screen
Reference: THISDOCUMENT
Contact: development at qt-project.org
**Size**::
Tag: 41
Data item: array
Semantics: The size of an object on the screen
Reference: THISDOCUMENT
Contact: development at qt-project.org
**Rectangle**::
Tag: 42
Data item: array
Semantics: A rectangle on the screen
Reference: THISDOCUMENT
Contact: development at qt-project.org
**Line**::
Tag: 43
Data item: array
Semantics: A line between two points on the screen
Reference: THISDOCUMENT
Contact: development at qt-project.org
**Polygon**::
Tag: 263
Data item: array
Semantics:
Introduction
------------
When dealing with painting, showing or otherwise manipulating objects on a
computer screen, computer programs deal frequently with sets of coordinates
measured in pixels. This document specifies a way of tagging those
representations in CBOR.
Semantics
---------
Tag 40 can be applied to a CBOR array of size 2 or 3, containing the (x,y) or
(x,y,z) coordinates of the point in question. The contents of the array should
be either CBOR integers (major types 0 and 1) or floating point (major type 7,
additional information 25, 26 and 27).
Tag 41 can be applied to a CBOR array of size 2 or 3, containing the (width,
height) or (width, height, depth) tuples of the object in question. The
contents of the array should be either CBOR integers or floating point. Sizes
should be zero or positive. Infinite sizes are permitted, indicating unlimited
size in one direction. Negative values (except negative infinity) or NaN for
either coordinate are unspecified and should not be used.
Tag 42 can be applied to a CBOR array containing 4 or 6 elements: (x, y, width,
height) or (x, y, z, width, height, depth). The rectangle is understood to be
inclusive of the origin point at (x,y) or (x,y,z), but exclusive of the end
point at (x + width, y + height, z + depth).
Tag 259 can be applied to a CBOR array of arbitrary size, whose elements are
points, stored like described for tag 40 (the tag itself is optional).
Canonical format
----------------
The canonical format for rectangles (Tag 42) is that the size components of the
rectangle all be infinity, positive values or zero. This way, the (x,y)
coordinate of a 2D rectangle would be understood as the Top-Left coordinate in
a standard "grows down and right" orientation of pixels on the screen, or
Bottom-Left for standard graphical plots found in Mathematics.
If the rectangle's width is negative, it can be canonicalized using the
following transformation:
- x' = x + width
- width' = -width
Note how this transformation should not be applied when the width is negative
infinite, as that would result in the new x coordinate becoming negative
infinite. The resulting rectangle would not be the same as the original one.
The same process can be applied to the y-height or z-depth pairs.
Examples
--------
The following example illustrates the encoding of point with coordinates
(320,240)::
40([320, 240]) CBOR diagnostic notation
D8 28 # Tag 40
82 # Array of length 2
19 01 40 # Integer value 320
18 F0 # Integer value 240
The following alternative representation is also possible, using floating
point::
D8 28 # Tag 40
82 # Array of length 2
F9 5D 00 # Half-precision FP 320
F9 5B 80 # Half-precision FP 240
The following example illustrates the encoding of a 3D size (10, 20, 30)::
41([10, 20, 30]) CBOR diagnostic notation
D8 29 # Tag 41
83 # Array of length 3
0A # Integer value 10
14 # Integer value 20
18 1E # Integer value 30
The following example illustrates the encoding of a 2D rectangle
640x480+200+150::
42([640, 480, 200, 150]) CBOR diagnostic notation
D8 2A # Tag 42
84 # Array of length 4
19 02 80 # Integer value 640
19 01 E0 # Integer value 480
18 C8 # Integer value 200
18 96 # Integer value 150
Finally, the following example illustrates a 4-sided polygon (a square) with
vertices located at (-0.5, -0.5), (0.5, -0.5), (0.5, 0.5), (-0.5, 0.5)::
263([[-0.5, -0.5], [0.5, -0.5], [0.5, 0.5], [-0.5, 0.5]])
D9 01 07 # Tag 263
84 # Array of length 4
82 # Array of length 2
F9 B8 00 # Half-precision FP -0.5
F9 B8 00 # Half-precision FP -0.5
82 # Array of length 2
F9 38 00 # Half-precision FP 0.5
F9 B8 00 # Half-precision FP -0.5
82 # Array of length 2
F9 38 00 # Half-precision FP 0.5
F9 38 00 # Half-precision FP 0.5
82 # Array of length 2
F9 B8 00 # Half-precision FP -0.5
F9 38 00 # Half-precision FP 0.5
Definition
----------
The following is the definition of the types above, using the `CBOR Data
Definition Language (CDDL)`_ (currently in draft).
**Point**::
point = #6.40(point-2d / point-3d)
point-2d = [coord-2d]
point-3d = [coord-3d]
**Size**::
size = #6.41(size-2d / size-3d)
size-2d = [coord-2d]
size-3d = [coord-3d]
**Rectangle**::
rectangle = #6.42(rectangle-2d / rectangle-3d)
rectangle-2d = [coord-2d, coord-2d]
rectangle-3d = [coord-3d, coord-3d]
**Polygon**::
polygon = #6.263(polygon-2d / polygon-3d)
polygon-2d = [ * point-2d ]
polygon-3d = [ * point-3d ]
**Common definitions**::
coord-2d = (number, number)
coord-3d = (number, number, number)
External references
-------------------
.. Concise Binary Object Representation (CBOR): https://tools.ietf.org/html/rfc7049
.. CBOR Data Definition Language (CDDL): https://tools.ietf.org/html/draft-ietf-cbor-cddl-00
-------------- next part --------------
=========
Bit array
=========
This document specifies a tag for bit arrays in `Concise Binary Object
Representation (CBOR)`_::
Tags: 43
Data item: array
Semantics: a dense array of bits
Reference: THISDOCUMENT
Contact: development at qt-project.org
Introduction
------------
CBOR already posseses a type to transmit arrays of arbitrary bytes in Major
Type 2. This document describes tags that indicate that such a byte string is a
bit array, including the indication of how many bits are valid in the last
byte.
Semantics
---------
Tag 43 is used to mark an array as a bit array. The first element of the array
is an unsigned number with the number of bits in the array, whereas the second
is a byte string containing the actual payload. The length of the byte string
may be smaller than the number of bits specified, with the those beyond the
size implicitly zero.
Bits are encoded in the least significant bits of each byte first, as follows:
- bit 0 is the LSB of byte 0
- bit 7 is the MSB of byte 0
- bit 8 is the LSB of byte 1
- bit 15 is the MSB of byte 2
- and so forth
If the byte string is longer than the number of bits specified, those beyond
the size are ignored. If the number of bits is not a multiple of 8, the last
byte in the byte string contains the remainder bits encoded in the least
significant bits.
Canonical format
----------------
Given a bit array of size N, the corresponding byte string should be no longer
than N / 8 bytes, rounded up to the next integer. For example, if the bit array
contains 61 bits, the byte string should contain 8 bytes or less.
Examples
--------
The following encodes a bit array containing the sequence of bits::
0 1 1
1234567890123456
----------------
1001001100011000
43([16. h'c9 18')] # Extended CBOR diagnostic notation
D8 35 # Tag 43
82 # Array of length 2
10 # Integer value 16
42 # Byte string of length 2
C9 18
The following encodes a bit array containing the following sequence of bits,
which is not a multiple of 8::
0 1
123456789012
------------
10011110110
43([11, h'79 03']) # Extended CBOR diagnostic notation
D8 35 # Tag 43
82 # Array of length 2
0B # Integer value 11
42 # Byte string of length 2
79 03
The following illustrates zero-padding in a bit array of length 512, with only
the first bit set::
43([512, h'01']) # Extended CBOR diagnostic notation
D8 35 # Tag 43
82 # Array of length 2
19 02 00 # Integer value 512
41 # Byte string of length 1
01
Definition
----------
The following is the definition of the types above, using the `CBOR Data
Definition Language (CDDL)`_ (currently in draft)::
bitarray = #6.43([uint, bstr])
External references
-------------------
.. Concise Binary Object Representation (CBOR): https://tools.ietf.org/html/rfc7049
.. CBOR Data Definition Language (CDDL): https://tools.ietf.org/html/draft-ietf-cbor-cddl-00
More information about the Interest
mailing list