# 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 'create'. Loading defaults to mipmap true and keepdata false.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:

- matsurface

## Methods:

### Method overview:

- clamp
- combine2d
- combinecube
- create1darray
- create2d
- create2darray
- create2drect
- create3d
- createbuffer
- createcube
- createfullwindow
- datapointer
- defaultpath
- deletedata
- deletevid
- dimension
- downloadbuf
- downloaddata
- filter
- formattype
- getrestype
- getscalartype
- lightmapscale
- load
- load3d
- load3dalpha
- load3dlum
- loadalpha
- loadcube
- loadcubealpha
- loadcubedotz
- loadcubelum
- loadcubeproj
- loaddata
- loadlum
- loadrect
- mipmapping
- mountscalararray
- name
- pack2d
- pixel
- pixelbyte
- registerusertex
- reload
- reloaddata
- resize
- sample
- savetofile
- settexbuffer
- swap
- uploadbuf
- uploaddata

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
create1darray (string name, int width, int height,textype, [boolean keepdata], [boolean nofilter],[boolean mipmap],[texdatatype])
  returns: (texture)
  creates a new empty texture in memory. Width must be power of two, height <= capability.texarraylayers. Resizing will not change type.
create2d (string name, int width, int height,textype, [boolean keepdata], [boolean nofilter],[boolean mipmap],[texdatatype])
  returns: (texture)
  creates a new empty texture in memory. Width and height must be power of two (unless capability for rectangle textures). texdatatype is uchar (Unsigned Byte) by default. Automatically registered as USER_TEX. No compression supported. Mipmapping will only work when keepdata + reloaddata is used, or when hardware mipmapping exists. If height is 1 it will be a 1D texture and stay like that (ie. resizing will not change this).
create2darray (string name, int width, int height, int depth, textype, [boolean keepdata], [boolean nofilter],[boolean mipmap],[texdatatype])
  returns: (texture)
  creates a new empty texture in memory. Width and height must be power of two (unless np2 supported), depth <= capability.texarraylayers. Automatically registered as USER_TEX. Same creation, compression and mipmap rules as for create2d
create2drect (string name, int width, int height,textype, [boolean keepdata], [boolean nofilter],[texdatatype])
  returns: (texture)
  creates a new empty rectangle texture in memory. Width and height can be arbitrary. texdatatype is uchar (Unsigned Byte) by default. Automatically registered as USER_TEX. No compression supported.
create3d (string name, int width, int height, int depth, textype, [boolean keepdata], [boolean nofilter],[boolean mipmap],[texdatatype])
  returns: (texture)
  creates a new empty texture in memory. Sizes must be power of two (unless np2 supported). Automatically registered as USER_TEX. Same creation, compression and mipmap rules as for new2d
createbuffer (string name, textype, texdatatype)
  returns: (texture)
  creates a texture that allows binding a vidbuffer as texture. The vidbuffer must be specified with setvidbuffer command. Only alpha,lumalpha,intensity and rgba are allowed as textypes.
createcube (string name, int size, textype, [boolean keepdata], [boolean nofilter],[boolean mipmap],[texdatatype])
  returns: (texture)
  creates a new empty texture in memory. Size must be power of two. Automatically registered as USER_TEX. Same creation, compression and mipmap rules as for create2d
createfullwindow (string name,[textype],[nofilter],[texdatatype])
  returns: (texture)
  creates a new empty windowsized texture. Should only be used within materials or as rendertargets, else you might need to set texture matrices manually (needed if capability for rectangle textures exists). Automatically registered as USER_TEX. No mipmapping nor compression supported. By default nofilter is true and textype is rgba (internally whatever is closest to window is used). The speciality about windowsized textures is that if you change window resolution they are automatically resized.
datapointer (texture)
  returns: (pointer start, end, s3darray)
  if the texture has imagedata availabe, 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 and removes keepdata flag. You can no 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,components)
  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!
downloadbuf (texture,vidbuffer, [int offset])
  returns: (boolean success)
  similar to downloaddata but stored into the vidbuffer. Offset (bytes) must be positive and within size of vidbuffer.
downloaddata (texture,[scalararray])
  returns: (boolean success)
  if texture was not loaded with keepdata, we can retrieve imagedata this way. Also allows updating local data from vidmem if keepdata was set on init, but texture content has changed. Note that without keepdata set, you must refetch data everytime major visual changes occur (fullscreen/res toggle). Optionally downloads uncompressed 1st mipmap into given scalararray
filter (texture,[boolean both]/[boolean min,mag])
  returns: ([boolean min,mag])
  returns or sets if texture filtering is used for minfication or/and magnification.
formattype (texture)
  returns: (string)
  the format in which the texture is stored as string, e.g. 1d, 2d, 3d, rect, cube, 1darray, 2darray.
getrestype ()
  returns: (int restype)
  returns the resource type as int value, useful for resdata or reschunk functions
getscalartype (texture)
  returns: (scalartype)
  the format of the local data.
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)
load (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a color 1d/2d texture (RGB or RGBA depending on file). Dimension depends on file.
  There are some special commands that you can attach to your load filename. "nocompress;filename.ext" will disable compression. 'normalize' will normalize the texture and its mipmaps. 'normal2light' will create a greyscale version of the normalmap using a fixed light direction vector. 'dxt1','dxt3' or 'dxt5' enforce specifc compression (if enabled), otherwise let driver choose compression format. If the filename contains 'lightmap' compression will be disabled, too. Note that compressed-stored textures will not work with the commands.
load3d (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a color 3d texture (RGB or RGBA depending on file). 3D textures are either .dds or a 2d image whose slices are stored vertically along image height. So that depth = height/width, height = width
load3dalpha (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a alpha 3d texture
load3dlum (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a luminance 3d texture.
loadalpha (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a alpha 1d/2d texture.
loadcube (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a color cube texture (RGB or RGBA depending on file). Cube texture are either .dds or 2d image whose sides are stored (+x,-x,+y,-y,+z,-z) vertically. So that height = width*6.
loadcubealpha (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a alpha cube texture
loadcubedotz (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a special color 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.
loadcubelum (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a luminance cube texture.
loadcubeproj (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a special color cubemap texture, generated from a single 2d image to fix backprojection problems, if nothing is specified we will use mipmapping.
loaddata (string file)
  returns: (Texture tex)
  loads a texture, but it will not be renderable. (autosets keepdata)
loadlum (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a luminance 1d/2d texture.
loadrect (string file,[boolean mipmap],[boolean keepdata])
  returns: (Texture tex)
  loads a color 2d rect texture (check capability) MipMap is ignored. Dimension depends on file.
  There are some special commands that you can attach to your load filename. "nocompress;filename.ext" will disable compression. 'normalize' will normalize the texture and its mipmaps. 'normal2light' will create a greyscale version of the normalmap using a fixed light direction vector. 'dxt1','dxt3' or 'dxt5' enforce specifc compression (if enabled), otherwise let driver choose compression format. If the filename contains 'lightmap' compression will be disabled, too. Note that compressed-stored textures will not work with the commands.
mipmapping (texture,[boolean])
  returns: ([boolean])
  turn on/off mipmapping for the texture. Only works when texture was created with mipmap support.
mountscalararray (texture, [int cubeside])
  returns: ([scalararray])
  returns a mounted array if data is available.
name (texture tex)
  returns: (string)
  returns name of texture
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.
pixel (texture,int x,y,[z],[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. Z can be 0-5 for cubemap side, and 0-depth for 3d textures. If internal format is BGR/BGRA/ABGR values must be manually reordered, LUMALPHA uses R and G channels. ALPHA/LUM use R channel.)
pixelbyte (texture,int x,y,[z],[int r,g,b,a])
  returns: ([int r,g,b,a])
  same as pixel but assumes channels as byte values (0-255).
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. If the texture was bound to an renderfbo, make sure to call renderfbo:resetattach. 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, [int depth])
  returns: ()
  resizing textures. previous data is lost. depth only for 3d textures
sample (texture,float u,v,[w],[boolean clamp])
  returns: ([float r,g,b,a])
  gets color from data texture, does clamped,bilinear filtering. More details under pixel function.
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)
settexbuffer (texture, vidbuffer)
  returns: ()
  assigns the given vidbuffer to the texture. texture must be of 'buffer' format. Internalformat as defined by texture creation is used. Passing a none vidbuffer disables binding.
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.
uploadbuf (texture,int x,y,z,w,h,d, vidbuffer,[int offset],[scalartype], [int offset], [mipmaplevel])
  returns: ()
  similar to uploaddata but reads from vidbuffer. Offset must be positive and within size range. Data by default is 4 component float32 and mipmaplevel is 0.
uploaddata (texture,[int x,y,z,w,h,d]/[int side],[staticarray/scalararray uploaddata])
  returns: ()
  will upload the current data to video memory. Only works on user-created textures with data, or if dataarray is passed. x,y,z are the starting points, w,h,d the dimension of the updated area. If arraycount does not match full texture dimension, then dataarray is assumed to be only the update rectangle. Scalararrays offsets are ignored. Side is for cubemaps (0-5), else cubemaps take Z as side. All numbers passed must be positive

## Inherited Methods:

### From resource

condition, getresname, getresshortname, resuserstring