Tighten levelImages layout

[lexaknyazev]

levelImages structure is:

for each array_element in numberOfArrayElements 
   for each face in numberOfFaces 
       for each z_slice in pixelDepth 
           for each row or row_of_blocks in pixelHeight 
               for each pixel or block_of_pixels in pixelWidth
                   Byte data[format-specific-number-of-bytes] 
               end
           end
       end
   end
end

Since format-specific-number-of-bytes may be unknown, an additional restriction is needed: bytesOfUncompressedLevelImages % (numberOfArrayElements * numberOfFaces) == 0

Also z_slice should be changed to something like z_slice or rows_of_blocks to accommodate compressed 3D formats.

[MarkCallow]

I agree with these suggested changes. Please submit a PR for the z_slice change. For the other, what do you think of adding a new section Validity or something like that where we can gather this and issue #11 and other similar things?

[MarkCallow]

pixel{Depth,Height,Width} also need to be replaced with something that represents those values for uncompressed textures and the number of texel blocks for compressed textures. I suggest a postscript to the levelImages structure to give the definitions.

for each array_element in numberOfArrayElements 
   for each face in numberOfFaces 
       for each z_slice_of_blocks in num_blocks_z
           for each row_of_blocks in num_blocks_y
               for each block in num_blocks_x
                   Byte data[format-specific-number-of-bytes] 
               end
           end
       end
   end
end

where numblocks{zyx} is

[stem] +++ ceil(pixel{Depth,Height,Width} / texelblock{depth,height,width}) +++

and texelblock{depth,height,width} are 1 for uncompressed formats and the block size in that dimension for block compressed formats as given in that format's section of the Khronos Data Formats specification. A block is a single pixel for uncompressed formats and texelblock{depth,width,height} pixels for block compressed formats.

This needs a :stem: in the attributes in the doc header to enable AsciiMathML processing. My attempt at mixing sh shortcuts with AsciiMathML will likely not work. It may be necessary to write separate equations for each item.

[MarkCallow]

@lexaknyazev what do you think of the idea of adding a Validity section in which we gather all the conditions that must be satisfied for a file to be considered valid?

[lexaknyazev]

That seems to be more of a document design choice. We could put each restriction next to corresponding field description, or group all of them into a separate section. Given that KTX2 spec is quite compact, I don't see much difference.

[MarkCallow]

@lexaknyazev, let's not bother with a new section then. Please file a PR using adding the additional restriction where you see fit and using something like my updated comment above for the z_slice fix. Feel free to improve on what I've written.