=========
TKE_Image
=========

Opcode
======

.. csv-table::

	"ASCII", "i"
	"Hexadecimal", "69"
	"Decimal", "105"

Operands
========

| Point position, Byte format, 
| [Byte name_length], [(name_length)x Byte name],
| Long width, Long height, Byte compression, Variable data, 
| [Byte alpha_format, [Long alpha_rle_length],  
| (alpha_rle_length)x Byte alpha_data],
| [2 x Float size, 2 x Byte size_units] 

.. raw:: html

	<table BORDER =1 WIDTH="530">
	  <tr> 
		<td WIDTH="131" HEIGHT="21">position</td>
		<td WIDTH="390" HEIGHT="21">reference point for the image</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">format</td>
		<td WIDTH="390" HEIGHT="21">type of image data and options</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">name_length</td>
		<td WIDTH="390" HEIGHT="21">length of name string, present if Image_Is_Named 
		  bit set in format</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">name</td>
		<td WIDTH="390" HEIGHT="21">name associated with image, present if Image_Is_Named 
		  bit set in format</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">width</td>
		<td WIDTH="390" HEIGHT="21">number of pixel columns in image</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">height</td>
		<td WIDTH="390" HEIGHT="21">number of pixel rows in image</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">compression</td>
		<td WIDTH="390" HEIGHT="21">type of data compression used on image data</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">data</td>
		<td WIDTH="390" HEIGHT="21">image contents</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">alpha_format</td>
		<td WIDTH="390" HEIGHT="21">format of separate alpha</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">alpha_rle_length</td>
		<td WIDTH="390" HEIGHT="21">length of alpha data (if alpha_format is 1), 
		  otherwise assumed 1</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">alpha_data</td>
		<td WIDTH="390" HEIGHT="21">alpha data</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">size</td>
		<td WIDTH="390" HEIGHT="21">explicit image sizing</td>
	  </tr>
	  <tr> 
		<td WIDTH="131" HEIGHT="21">size_units</td>
		<td WIDTH="390" HEIGHT="21">manner of interpretting size</td>
	  </tr>
	</table>
	
	
Notes
=====

An image is inserted into the currently open segment.

Image data is arranged per-pixel, starting at the upper-left and moving right, then moving down to successive rows. The amount of data per pixel is shown in the following table. Pixels in mapped images are indices into the appropriate color map. The order of bytes in non-mapped formats is as shown.

RGBA and BGRA images with jpeg compression requested are separated into an RGB image which is compressed normally, and an alpha image which is processed separately. If the alpha value is constant, such as an image that is completely opaque, the alpha format indicator is zero, and the constant alpha value is a single Byte following. Otherwise, the format indicator is 1 to indicate RLE, and is followed by a Long to indicate the length of the rle compressed data which follows (the same as if the alpha data were a Mapped 8 image).


Format value (lower nibble of the format byte)
----------------------------------------------

.. raw:: html

	<table BORDER =1 WIDTH="350">
	  <TR> 
		<TD height=21 width=50>Format</TD>
		<TD height=21 width=190>Description</TD>
		<TD height=21 width=120>Bytes per pixel</TD>
	  </TR>
	  <tr> 
		<td WIDTH="50" HEIGHT="21">0</td>
		<td WIDTH="190" HEIGHT="21">Mapped 8</td>
		<td WIDTH="120" HEIGHT="21">1</td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21">1</td>
		<td WIDTH="190" HEIGHT="21">Mapped 16</td>
		<td WIDTH="120" HEIGHT="21">2</td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21">2</td>
		<td WIDTH="190" HEIGHT="21">RGB</td>
		<td WIDTH="120" HEIGHT="21">3</td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21">3</td>
		<td WIDTH="190" HEIGHT="21">RGBA</td>
		<td WIDTH="120" HEIGHT="21">4</td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21">4</td>
		<td WIDTH="190" HEIGHT="21">BGRA</td>
		<td WIDTH="120" HEIGHT="21">4</td>
	  </tr>
	</table>


Option values (higher nibble of the format byte)
------------------------------------------------

.. raw:: html

	<table border="1" width="350">
	  <tr> 
		<td height="21" width="50"> Bit</td>
		<td height="21" width="300"> Description</td>
	  </tr>
	  <tr> 
		<td height="21" width="50"> 0x10</td>
		<td height="21" width="190"> size and size_units is specified</td>
	  </tr>
	  <tr> 
		<td height="21" width="50"> 0x20</td>
		<td height="21" width="190"> implicit texture for this image is local 
		  to the owner</td>
	  </tr>
	  <tr> 
		<td height="21" width="50"> 0x80</td>
		<td height="21" width="190"> Image_Is_Named (and an implicit texture)</td>
	  </tr>
	</table>


Compression formats
-------------------

.. raw:: html

	<table BORDER =1 WIDTH="530">
	  <TR> 
		<TD height=21 width=50>Compression</TD>
		<TD height=21 width=400>Description</TD>
	  </TR>
	  <tr> 
		<td WIDTH="50" HEIGHT="21">0</td>
		<td WIDTH="190" HEIGHT="21"><STRONG>None</STRONG> - Data is simply 
		   <STRONG>(</STRONG><EM>width</EM>&nbsp;<STRONG>x</STRONG>&nbsp;<EM>height</EM>&nbsp;<STRONG>x</STRONG>&nbsp; 
			<EM>{bytes per pixel}</EM><STRONG>)x&nbsp;Byte</STRONG> data </td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21">1</td>
		<td WIDTH="190" HEIGHT="21"><STRONG>RLE</STRONG> (Mapped 8 format only) 
		  - Data is 
		   <STRONG>Long</STRONG> rle_length, <STRONG>[(</STRONG><EM>rle_length</EM><STRONG>)x&nbsp;Byte</STRONG>&nbsp;rle_data
		   where <em>rle_data</em> is a series of [count,run] pairs.<br>
			if the count byte is positive, the run is a series of <em>count</em> 
			bytes used directly. if the count byte is negative, the run is a single 
			byte to be repeated ABS(<em>count</em>)+3 times. </td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21">2</td>
		<td WIDTH="190" HEIGHT="21"><STRONG>JPEG</STRONG> - Data is 
		   <STRONG>Long</STRONG> jpeg_length, <STRONG>[(</STRONG><EM>jpeg_length</EM><STRONG>)x&nbsp;Byte</STRONG>&nbsp;jpeg_data
		   where <em>jpeg_data</em>represents an RGB image </td>
	  </tr>
	  <tr> 
		<td WIDTH="50" HEIGHT="21">99</td>
		<td WIDTH="190" HEIGHT="21"><STRONG>External reference</STRONG> - Data 
		  is 
		   <STRONG>Word</STRONG> ref_length, <STRONG>[(</STRONG><EM>ref_length</EM><STRONG>)x&nbsp;Byte</STRONG>&nbsp;reference
		   where <em>reference</em> is a reference to external image data (filename, 
			URL, etc.) </td>
	  </tr>
	</table>


Size units options
------------------

.. raw:: html

	<table BORDER =1 WIDTH="500">
	  <TR> 
		<TD height=21 width=50>0</TD>
		<TD height=21 width=390>Object space size</TD>
	  </TR>
	  <tr> 
		<td WIDTH=50 HEIGHT=21>1</td>
		<td WIDTH=390 HEIGHT=21>Screen space size</td>
	  </tr>
	  <tr> 
		<td WIDTH=50 HEIGHT=21>2</td>
		<td WIDTH=390 HEIGHT=21>Window space size</td>
	  </tr>
	  <tr> 
		<td WIDTH=50 HEIGHT=21>3</td>
		<td WIDTH=390 HEIGHT=21>Points</td>
	  </tr>
	  <tr> 
		<td WIDTH=50 HEIGHT=21>4</td>
		<td WIDTH=390 HEIGHT=21>Pixels</td>
	  </tr>
	  <tr> 
		<td WIDTH=50 HEIGHT=21>6</td>
		<td WIDTH=390 HEIGHT=21>size is a scale factor on original size</td>
	  </tr>
	  <tr> 
		<td WIDTH=50 HEIGHT=21>7</td>
		<td WIDTH=390 HEIGHT=21>World space size</td>
	  </tr>
	</table>

Image size was added in 10.01.

JPEG Compression of RGBA and BGRA images via separate alpha handling was dded in 13.40. 
