Clarify Interpretation of DMXValue

[Firionus]

Is your feature request related to a problem? Please describe. The DMXValue type is defined with "ByteMirroring", which I can't understand and the example is not particularly helpful in understanding it.

Details

The DMXValue type is currently defined as:

Value Type	Format	Description
DMXValue	Uint/n for ByteMirroring values Uint/ns for ByteShifting values	Special type to define DMX value where n is the byte count. The byte count can be individually specified without depending on the resolution of the DMX Channel. By default byte mirroring is used for the conversion. So 255/1 in a 16 bit channel will result in 65535. You can use the byte shifting operator to use byte shifting for the conversion. So 255/1s in a 16 bit channel will result in 65280.

I intuitively grasped what "Byte Shifting" meant, as it is a standard operation in lots of programming languages.

However, "Byte Mirroring" is not a typical operation and a quick Google search does not yield any useful information.

I think it is clear that for converting from higher byte numbers to lower byte numbers bit shifting is used in both cases. E.g., 2949/2 converts to 11/1, even though 2949/256 = 11.52 and should actually be rounded to 12. It's also clear that when you use bit shifting to upconvert, you just fill with zeros from the right.

However, how to use Byte Mirroring for converting from lower byte numbers to higher byte numbers? The standard only gives the example of 255/1 converting to 65535/2. However, I can think of many algorithms that get this specific example right. For example, consider the DMXValue 43707/2 (which is AABB in hex) converted to 10 bytes:

• Mirror in the sense that the bytes are mirrored every time we extend the byte number: AABB BBAA AABB BBAA AABB
• Mirror in the sense we append the mirrored version as often as needed: AABB BBAA BBAA BBAA BBAA
• Mirror in the sense that the individual bits are mirrored every time we extend the byte number: AABB DD55 AABB DD55 AABB DD55
• Mirror in these sense that the bits inside each byte are mirrored every time, but the bytes are periodic: AABB 55DD AABB 55DD AABB
• Mirror in the sense that the bits inside each byte are mirrored once and then appended: AABB 55DD 55DD 55DD 55DD
• Just append the last byte: AABB BBBB BBBB BBBB BBBB
• Append the mirrored last byte: AABB DDDD DDDD DDDD DDDD
• Just byte shift while filling with ones: AABB FFFF FFFF FFFF FFFF

and so on ... Of course, all of the above algorithms result in FF being converted to FFFF, hence why the example in the standard isn't very helpful.

After reverse engineering the behavior of the Builder (and grandMA3 onPC), I'm pretty sure the proper behavior is to periodically repeat the original number when upconverting, i.e. AABB converts to AABB AA (3 bytes), AABB AABB (4 bytes) or AABB AABB AABB AABB AABB (10 bytes). This is an elegant method for conversion, but has to be documented. What seems peculiar is that there is nothing "mirroring" about the algorithm, so I think we should drop that name.

Describe the solution you'd like

Change the Description to:

--

Special type to define DMX value where n is the byte count. The byte count can be individually specified without depending on the resolution of the DMX Channel.
To convert a DMX value to a lower byte count, byte shifting to the right is used. Example: 43707/2 (0xaabb) will result in 170 (0xaa) for a 1-byte channel.
To convert a DMX value to a higher byte count, by default periodic conversion is used. The bytes are shifted left while periodically filling with the original bytes from the right until the target byte count is reached. Example: 43707/2 (0xaabb) will result in 11189162 (0xaabbaa) for a 3-byte channel, 2864425659 (0xaabbaabb) for a 4-byte channel and 733292968874 (0xaabbaabbaa) for a 5-byte channel. 255/1 (0xff) will result in 65535 (0xffff) for a 2-byte channel, so periodic conversion covers the whole range.
When an "s" is appended to the DMX value, conversion to a higher byte count must be performed with the byte shifting operator. The bytes are shifted left while filling with zeros from the right. Example: 255/1 (0xff) will result in 65280 (0xff00) for a 2-byte channel, so byte shifting does not cover the whole range.

--

Main changes:

• change name from "Byte Mirorring" to "periodic conversion"
• try to explain periodic conversion and byte shifting
• provide examples with a different number (0xaabb) to show how the periodic conversion works and provide useful test cases for developers
• add hex notations to examples, as this makes bit shift operations more clear
• annotate the given examples with "covers the whole range" or "does not cover the whole range" to make clear why periodic conversion is the default

Describe alternatives you've considered

I think clarifying the standard is not a bad thing in any case. Of course, I'm excited to hear your alternative suggestions to clarify the text and any other comments (Maybe I got the intended algorithm wrong? Maybe there's a better description for it or you can tell me why it's called "byte mirroring"?).

Additional context

I gave an example with a 5-byte channel. Is that allowed in GDTF? Cause the definition of DMXValue says "Uint" which means 32-bit in some languages...

[moritzstaffel]

This is also something we should talk about

[moritzstaffel]

change name from "Byte Mirorring" to "periodic conversion" try to explain periodic conversion and byte shifting provide examples with a different number (0xaabb) to show how the periodic conversion works and provide useful >test cases for developers add hex notations to examples, as this makes bit shift operations more clear annotate the given examples with "covers the whole range" or "does not cover the whole range" to make clear why >periodic conversion is the default

We are not sure about the name changing, but we want to define this more. @bbudzon is proposing to do this in Appendix, like the UUIDs