================
TKE_PolyPolyline
================

Opcode
======

.. csv-table::

	"ASCII", "unprintable"
	"Hexadecimal", "0x10"
	"Decimal", "16"


Operands
========

Operands depend on suboptions. Operands enclosed in brackets ('<STRONG>[]</STRONG>') will not be present in all situations. See the description of the specific operands for the rules that dictate whether or not they appear.

| short suboptions, int point_count, [int primitive_count], 
| [int array lengths], variable points, [variable leftovers] 

.. raw:: html

	<table BORDER =1 WIDTH="530">
	  <TR> 
		<TD height=21 width=131>suboptions</TD>
		<TD height=21 width=390>a bit field with information about the formatting. 
		  See below for more details</TD>
	  </TR>
	  <TR> 
		<TD height=21 width=131>point_count</TD>
		<TD height=21 width=390>The total number of vertices in all of the primitives 
		  combined.</TD>
	  </TR>
	  <TR> 
		<TD height=21 width=131>lengths</TD>
		<TD height=21 width=390>An array of integers to indicate the length (number 
		  of vertices) of each primitive. Left implicit if there is only one primitive 
		  and the TKPP_ONE_PRIMITIVE_ONLY bit is set. (see the description of 
		  "suboptions").</TD>
	  </TR>
	  <TR> 
		<TD height=21 width=131>primitive_count</TD>
		<TD height=21 width=390>The number of primitives that this opcode is encoding. 
		  Under most circumstances, this is left implicit and inferred from "lengths" 
		  and "point_count"</TD>
	  </TR>
	  <TR> 
		<TD height=21 width=131>points</TD>
		<TD height=21 width=390>Point data that is either compressed or uncompressed 
		  depending on suboptions. Described in detail below. For 2d data, this 
		  operand contains only the unrestricted dimensions. </TD>
	  </TR>
	  <TR> 
		<TD height=21 width=131>leftovers</TD>
		<TD height=21 width=390>If "suboptions" contains bits which place restrictions 
		  on certain dimensions, a small number of additional floats may be required 
		  to fully specify the points array. (see the description of "suboptions").</TD>
	  </TR>
	</table>


Suboptions
----------

As mentioned above, the formatting depends on the values of "suboptions". The following two tables define the bits of those two flags, as well as the rules that use the values of those bits to determine by which format the polylines and/or lines is to be interpreted. Note that some of the values contain multiple bits, requiring if statements of the form ((subop&mask)==val), instead of (subop&val).


**Suboptions**

.. raw:: html

	<table BORDER =1 WIDTH="500">
	  <TR> 
		<TD height=21 width=50> 0x0001</TD>
		<TD height=21 width=390>TKSH_COMPRESSED_POINTS -- Points are compressed</TD>
	  </TR>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x0002</td>
		<td WIDTH="390" HEIGHT="21">TKPP_HAS_EXPLICIT_PRIMITIVE_COUNT -- the primitive 
		  count is explicitly specified. Mutually exclusive with TKPP_ONE_PRIMITIVE_ONLY</td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x0004</td>
		<td WIDTH="390" HEIGHT="21"> TKPP_ONE_PRIMITIVE_ONLY -- this polypolyline 
		  encodes only a single primitive. The "lengths" array is omitted, since 
		  it can be assumed to be the same as "point_count". Mutually exclusive 
		  with TKPP_HAS_EXPLICIT_PRIMITIVE_COUNT.</td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x0008</td>
		<td WIDTH="390" HEIGHT="21"> TKPP_GLOBAL_QUANTIZATION -- Compressed vertices 
		  inherit global bounding box instead of specifying their own.</td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"></td>
		<td WIDTH="390" HEIGHT="21"><center><i>(break in sequence)</i>.</td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x0100</td>
		<td WIDTH="390" HEIGHT="21">TKPP_ZERO_X -- all points have x == 0</td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x0200</td>
		<td WIDTH="390" HEIGHT="21">TKPP_SAME_X -- all points have the same x 
		  value. Add 1 to the "leftovers" array. </td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x0300</td>
		<td WIDTH="390" HEIGHT="21">TKPP_PER_PRIMITIVE_X -- within any given primitive, 
		  x values are the same. Add primitive_count (generally implicit) to the 
		  "leftovers" array. </td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x0400</td>
		<td WIDTH="390" HEIGHT="21">TKPP_ZERO_Y -- all points have y == 0</td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x0800</td>
		<td WIDTH="390" HEIGHT="21">TKPP_SAME_Y -- all points have the same y 
		  value. Add 1 to the "leftovers" array. </td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x0c00</td>
		<td WIDTH="390" HEIGHT="21">TKPP_PER_PRIMITIVE_Y -- within any given primitive, 
		  y values are the same. Add primitive_count (generally implicit) to the 
		  "leftovers" array. </td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x1000</td>
		<td WIDTH="390" HEIGHT="21">TKPP_ZERO_Z -- all points have z == 0</td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x2000</td>
		<td WIDTH="390" HEIGHT="21">TKPP_SAME_Z -- all points have the same z 
		  value. Add 1 to the "leftovers" array. </td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21"> 0x3000</td>
		<td WIDTH="390" HEIGHT="21">TKPP_PER_PRIMITIVE_Z -- within any given primitive, 
		  z values are the same. Add primitive_count (generally implicit) to the 
		  "leftovers" array. </td>
	  </tr>
	</table>
	
	
Notes
=====

Polylines or lines are inserted into the currently opened segment.


Points (uncompressed)
---------------------

``array of floats`` uncompressed floats to specify point data for unrestricted dimensions only. For example, fully 3d data will have the order xyzxyz...xyz, whereas 2d data with the ``TKPP_SAME_Y`` flag in suboptions might have xzxz...xzy, with the final "y" coming as the "leftovers array". 


Points (compressed)
-------------------

``byte`` compression scheme, ``array of floats`` bounding, ``byte`` bits_per_sample, ``int`` data_length,  ``variable`` array of compressed floats (see :doc:`attributes.html </general/hsf/opcodes/attributes>`) .

Points are either compressed or uncompressed vertex data. Compression status is dictated by the ``TKPP_COMPRESSED_POINTS`` bit in the suboptions. If compressed, it will consist of a compression scheme identifier, followed by data that is specific to that compression scheme. The specifics of the compressed format are identical to those of polyhedron vertex attributes, described in :doc:`attributes.html </general/hsf/opcodes/attributes>` in the "array of compressed floats" section. The bounding data will be 2 floats in length for every unrestricted dimension (thus, 2d data would have 4 floats for its bounding). 

  
Leftovers
=========

Leftovers apply to 2d data only, and are only present when the restricted dimensions are specified as "SAME" or "PER_PRIMITIVE", as opposed to "ZERO". It is always considered to be a one dimensional array, that is either compressed or uncompressed, just like the main points array -- with the exception that a leftovers array of length 1 is always left uncompressed. 
  
  
Leftovers (uncompressed)
------------------------

``array of floats`` 1d array of uncompressed floats to specify point data.


Leftovers (compressed)
----------------------

``byte`` compression scheme, **2 floats** min and max, ``int`` data_length, ``variable`` 1d array of compressed floats

"bits_per_sample" is assumed to be the same as the value for the main points array, and therefore omitted, and the array of floats is always 1d. In all other respects, however, the leftovers array is very much similar to the main points array.
