# Class: texture

Bitmaps that store color information.
There is two kind of textures: loaded from file and created in memory. Filebased textures are 'load'ed while pure memory textures are created with 'new'.When a texturename looks like 'USER_TEX(myname)' then luxinia will check if a loaded texture was registered as usertex with 'myname' or if a user created texture with that name exists.

## Hierarchy

    o-+ resource
      o-+ texture

## Interfaces:

- hashid
- matsurface

## Methods:

### Method overview:

- arraydecal
- arrayset
- clamp
- combine2d
- combinecube
- convfilterboxdata
- convfiltergaussdata
- datapointer
- defaultpath
- deletedata
- deletevid
- dimension
- filter
- getdata
- getrestype
- lightmapscale
- load2d
- load2dalpha
- load2ddata
- load2dlum
- load3d
- load3dalpha
- load3dlum
- loadcube
- loadcubedotz
- loadcubeproj
- mipmapping
- name
- new2d
- newcube
- newfullwindow
- pack2d
- pixel2d
- registerusertex
- reload
- reloaddata
- resize
- sample2d
- savetofile
- swap
- uploaddata

arraydecal (texture, floatarray, int x,y,w,h,[float alphamul],[boolean mask r,g,b,a])
  returns: ()
  decal blends the floatarray (4 floats per pixel) on top of current imagedata rectangle, defined by x,y,w,h. Optionally you can mask off certain channels.
arrayset (texture, floatarray, int x,y,w,h,[boolean mask r,g,b,a])
  returns: ()
  sets pixels from floatarry (4 floats per pixel). Optionally you can mask off certain channels.
clamp (texture,[boolean all]/[boolean x,y,z])
  returns: ([boolean x,y,z])
  sets or gets clamping of the texture. If not set texture will repeat, default is off. By passing one boolean you will toggle all, else you can specify in detail which axis to repeat/clamp.
combine2d (stringstack,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  combines all 2d textures to a single row, ideally number of textures should be power of 2, max 64 textures
combinecube (stringstack,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  combines all 2d textures to a single cubemap, 6 textures are required
convfilterboxdata (texture,int kernelsize,[boolean wrap])
  returns: ()
  runs convolution boxcar filter on the imagedata. wrap defaults to true
convfiltergaussdata (texture,int kernelsize,[boolean wrap])
  returns: ()
  runs convolution gauss filter on the imagedata. wrap defaults to true
datapointer (texture)
  returns: (int start, int end)
  if the texture was loaded with keepdata you can access the memory directly in other lua dlls. Be aware that you must make sure to not corrupt memory, make sure you are always smaller than the 'end' pointer.
defaultpath ([string])
  returns: ([string])
  returns or sets the default resource path. Luxinia will search in those when resources are not found.
deletedata (texture)
  returns: ()
  deletes the imagedata in system memory. you can now longer change or sample it.
deletevid (texture)
  returns: ()
  unloads the texture from video memory, can result into errors when you free a still in use texture.
dimension (texture)
  returns: (int width,height,depth,bpp,origwidth,origheight)
  will return infos about the texture. It returns the size in memory and the original size. If system.detail() is <2, the loaded textures are resized at half of their size! If you do any calculations on the image depending on its size, you have to take this into account!
filter (texture,[boolean both]/[boolean min,mag])
  returns: ([boolean min,mag])
  returns or sets if texture filtering is used for minfication or/and magnification.
getdata (texture)
  returns: ()
  if texture was not loaded with keepdata, we can retrieve imagedata this way and set keepdata
getrestype ()
  returns: (int restype)
  returns the resource type as int value, useful for resdata or reschunk functions
lightmapscale (texture,[float])
  returns: ([float])
  returns or sets how much the output is scaled, when this texture is used as lightmap outside of shaders (or when lightmapscale is used in shader stage)
load2d (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a 2d color texture (autoconverted to 1D if height is 1), if nothing is specified we will use mipmapping
load2dalpha (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a 2d alpha texture (autoconverted to 1D if height is 1), if nothing is specified we will use mipmapping
load2ddata (string file)
  returns: (Texture tex)
  loads a texture, but it will not be renderable. (autosets keepdata)
load2dlum (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a 2d luminance texture (autoconverted to 1D if height is 1), if nothing is specified we will use mipmapping
load3d (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a 3d color texture (autoconverted to 1D if height is 1), if nothing is specified we will use mipmapping (only works with .dds)
load3dalpha (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a 3d alpha texture (autoconverted to 1D if height is 1), if nothing is specified we will use mipmapping (only works with .dds)
load3dlum (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a 3d luminance texture (autoconverted to 1D if height is 1), if nothing is specified we will use mipmapping (only works with .dds)
loadcube (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a cubemap texture, if nothing is specified we will use mipmapping. (only works with .dds)
loadcubedotz (string file,[boolean mipmap])
  returns: (Texture tex)
  loads a special cubemap texture, generated from a single 1d image to create a vector.dot.+Z cubemap, cube.size is half of width. -1 is left and +1 is right. if nothing is specified we will use mipmapping.
loadcubeproj (string file,[boolean mipmap])
  returns: (Texture tex)
  loads a special cubemap texture, generated from a single 2d image to fix backprojection problems, if nothing is specified we will use mipmapping.
mipmapping (texture,[boolean])
  returns: ([boolean])
  turn on/off mipmapping for the texture. Only works when texture was created with mipmap support.
name (texture tex)
  returns: (string)
  returns name of texture
new2d (string name, int width, int height,int type 0-6, boolean keepdata, [boolean nofilter],[boolean mipmap])
  returns: (texture)
  creates a new empty texture in memory. Width and height must be power of two (unless capability for rectangle textures exists). Types are 0 = RGB, 1 = RGBA, 2 = Alpha, 3 = Luminance, 4 = Depth, 5 = BGR, 6 = BGRA. Automatically registered as USER_TEX. No compression supported. Mipmapping will only work when keepdata + reloaddata is used, or when hardware mipmapping exists.
newcube (string name, int size, int type 0-1, boolean keepdata, [boolean nofilter],[boolean mipmap])
  returns: (texture)
  creates a new empty texture in memory. Size must be power of two. Types are 0 = RGB, 1 = RGBA. Automatically registered as USER_TEX. Same compression and mipmap rules as for new2d
newfullwindow (string name)
  returns: (texture)
  creates a new empty windowsized texture in memory. Should only be used within materials or as rendertargets, else you might need to set texture matrices manually. Automatically registered as USER_TEX. No mipmapping nor compression supported
pack2d (string filenameR, string filenameG, string filenameB,[string filenameA],[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  combines all 2d textures to a single image where each image file becomes one color channel. 3 or 4 filenames required.
pixel2d (texture,int x,y,[float r,g,b,a])
  returns: ([float r,g,b,a])
  same as sample but works with discrete coordinates and can set pixels. Writing to texture is not visible until uploaddata or reloaddata was called. (if internal format is BGR or BGRA values must be manually reordered)
registerusertex (texture,string username)
  returns: ()
  registers the texture as USER_TEX. If anyone access a texture with the name 'USER_TEX(username)' this texture will be used. The name will be unavailable once texture was deleted.
reload
  () : (texture,[string filename,boolean keepoldsize] - reloads the texture with original (or new filename) with same specifications as on first load. The internal filename remains to be the original filename. Optionally the texture can be forced to the current texturesize.
reloaddata (texture)
  returns: ()
  deletes old image in videomemory, and uploads a new one with the current imagedata. this is slower than uploaddata but supports all textures.
resize (texture,int width, int height)
  returns: ()
  resizing textures. previous data is lost.
sample2d (texture,float u,v,[boolean clamp])
  returns: ([float r,g,b,a])
  gets color from data texture, does clamped,bilinear filtering. texture must have keepdata flag set or be of data2d type. (if internal format is BGR or BGRA values must be manually reordered)
savetofile (texture,string filename,[int quality],[int cubeside])
  returns: ()
  saves texture to file. quality must be within 1 and 100 and is used for .jpg (default is 85). cubeside can be 0-5 for cubemap textures (default 0)
swap (texture,texture)
  returns: ()
  swaps both texture contents, all images who already referenced one of either, now uses the other data. Names stay as they were.
uploaddata (texture,[int x,y,z,w,h,d],[int side])
  returns: ()
  will upload the current data to video memory. only works on user-created textures with keepdata flag. x,y,z are the starting points, w,h,d the dimension of the updated area. Side is for cubemaps (0-5). All numbers passed must be positive

## Inherited Methods:

### From resource

condition, getresname, getresshortname