Lunatic: in shade table 'remap16' method, allow sparse table, document it.

Add shadexfog.createremap() convenience function.

git-svn-id: https://svn.eduke32.com/eduke32@4332 1a8010ca-5511-0410-912e-c29ae57300e0

polymer/eduke32/source/lunatic/doc/lunatic.txt

@@ -2192,21 +2192,34 @@ When running in EDuke32, there are additional restrictions:
   variable in the global environment that indicates whether the Lua game state
   is created for the very first time and the game is not yet running.)
 
-//////////
 ===== Shade table methods
 
 `newsht = sht:remap16(tab)`::
 
-Rearranges consecutive runs of 16 values of every shade 256-tuple of `sht` by
-the 0-based selection given by the 0-based sequence `tab`.
+Returns a new shade table with consecutive runs of 16 values of every 256-tuple
+of `sht` remapped as specified by `tab`. Specifically, `tab` must be a table
+whose keys in [0 .. 15] may be set to values in [0 .. 15]. For a shade index
+`sh` and a color index `i`, the returned shade table `newsht` then has
++
+==========
+`newsht[sh][i]` = `sht[sh][newi]`,
+==========
++
+where
++
+==========
+`newi` = `16*tab[math.floor(i/16)] + i%16` {nbsp} [gray]#// if `tab[math.floor(i/16)]` is non-*nil*# +
+`newi` = `i` {nbsp} [gray]#// otherwise#
+==========
 +
 .Example
 [source]
 ----------
-local perm16 = { [0]=0,1, 2,3, 5,4, 6,7, 8,13, 10,11, 12,9, 14,15 }
-local newsht = engine.getshadetab(0):remap16(perm16)
+-- Creates a shade table with the same remapping as pal 21 (blue -> red) and
+-- registers it under pal 22, overwriting its previous contents.
+local newsht = engine.getshadetab(0):remap16({[4]=13, [5]=8})
+engine.setshadetab(22, newsht)
 ----------
-//////////
 
 Blending table interfaces
 ^^^^^^^^^^^^^^^^^^^^^^^^^

polymer/eduke32/source/lunatic/engine.lua

@@ -49,13 +49,14 @@ local shtab_methods = {
     --  { [0]=0,1, 2,3, 5,4, 6,7, 8,13, 10,11, 12,9, 14,15 }
     -- TODO (...)
     remap16 = function(sht, idxs16)
-        if (type(idxs16) ~= "table" or idxs16[0]==nil or #idxs16 ~= 15) then
-            error("invalid argument #2: must be a [0]-table with 16 elements", 2)
+        if (type(idxs16) ~= "table") then
+            error("invalid argument #2: must be a table", 2)
         end
 
         for i=0,15 do
-            if (not (idxs16[i] >= 0 and idxs16[i] <= 15)) then
-                error("invalid reordering table: elements must be in [0 .. 15]", 2)
+            local idx = idxs16[i]
+            if (not (idx==nil or type(idx)=="number" and idx >= 0 and idx <= 15)) then
+                error("invalid reordering table: elements must be numbers in [0 .. 15], or nil", 2)
             end
         end
 
@@ -63,7 +64,7 @@ local shtab_methods = {
         for sh=0,31 do
             for i=0,15 do
                 ffi.copy(cast_u8ptr(newsht[sh]) + 16*i,
-                         cast_u8ptr(sht[sh]) + 16*idxs16[i], 16)
+                         cast_u8ptr(sht[sh]) + 16*(idxs16[i] or i), 16)
             end
         end
         return newsht

polymer/eduke32/source/lunatic/test/shadexfog.lua

@@ -22,6 +22,11 @@ local gv = gv
 
 local shadexfog = {}
 
+function shadexfog.createremap(palnum, remaptab)
+    local sht = engine.getshadetab(0)
+    engine.setshadetab(palnum, sht:remap16(remaptab))
+end
+
 -- Create 32 palookups corrensponding to different *shade levels* of a fog
 -- palookup, called a "shade-x-fog" palookup set in the following.
 --