/*********************************************************************************************
 *                                                                                           *
 *                                                                                           *
 *   Copyright 1989-2018 by AutoDesSys, Inc.                                                 *
 *                                                                                           *
 *   This software and its associated documentation contains proprietary,                    *
 *   confidential, and trade secret information of AutoDesSys Inc. and may not be            *
 *   disclosed, copied in any form, or used for any purpose except as specifically           *
 *   permitted in writing by AutoDesSys, Inc.                                                *
 *                                                                                           *
 *   AutoDesSys, Inc. grants permission to use the software to those who purchase            *
 *   a license.  Such a usage will be made according to the terms and conditions             *
 *   specified in the license agreement to which a licensee agrees before installing         *
 *   and commencing usage of the software.  The license agreement can be found               *
 *   on the envelop that contains the software CD.                                           *
 *                                                                                           *
 *   AutoDesSys, Inc. also grants permission to licensees to develop extensions to           *
 *   the software, which can be in the form of scripts or plugins.  The permission           *
 *   includes calling the API and call back functions provided by AutoDesSys, Inc.           *
 *   and accessing information relevant to these functions and the general workings          *
 *   of form.Z, but only up to the point to which AutoDesSys, Inc. has chosen to             *
 *   expose, through its form.Z SDK Manual.  All extensions developed by third               *
 *   parties will include a copy of this copyright note in an easily accessible place or     *
 *   a clear instruction to read this original note by AutoDesSys, Inc.                      *
 *                                                                                           *
 *   All the software distributed under a license, either for the purpose of using it or     *
 *   for the purpose of developing extensions, is distributed AS IS, WITHOUT                 *
 *   WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, AND                                    *
 *   AutoDesSys, Inc. HEREBY DISCLAIMS ALL SUCH WARRANTIES,                                  *
 *   INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF                                         *
 *   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.                                    *
 *                                                                                           *
 *   formZ, RenderZone, and RadioZity are registered trademarks of AutoDesSys, Inc.          *
 *                                                                                           *
 *   form.Z SDK, Version 8.6.3, Dec 03, 2018                                                 *
 *                                                                                           *
 *                                                                                           *
 *********************************************************************************************/


#ifndef __FZ_TMAP_API_H
#define __FZ_TMAP_API_H 1

#ifdef __cplusplus
extern "C" {
#endif


/****************************************************************

	Texture Maps


	Description
		formZ texture maps. They are used by surface styles, backgounds, environment maps, 
		projector lights and other rendering related processes. The functions in this module 
		are used to extract information from a texture map and to a lesser degree, change 
		certain aspects of a texture map.
 ****************************************************************/

#include "fzpl_plugin.h"

#include "fz_api.h"
#include "fz_iost_api.h"
#include "fz_type_api.h"

/****************************************************************

	fz_tmap_ptr


	Description
		Data structure for a texture map. 
		A texture map is an image file stored on disk, in a format supported 
		by formZ, such as TIFF or Targa. The image of the texture map can be 
		loaded into memory and retrieved by a plugin and used for rendering 
		or other image based operations. The pixels of a texture map, once loaded 
		into memory through the API fz_tmap_get_pixels, are always in rgb 
		format, even if the file is black and white or cmyk. If the texture map 
		file has an alpha channel, it can be loaded separately, or together with 
		the rgb channels. Before using any of the api functions that extract information 
		from a texture map, such as the pixels, or the texture map width and height, the 
		API function fz_tmap_find_file should be called. This function makes sure that 
		the texture map file can be found on disk. if the file cannot be found, the 
		plugin may decide to ignore the texture map or use an alternative texture.

	Availability	5.0.0.0


	See Also
		fz_tmap_set_crop_rect, fz_tmap_set_floc

 ****************************************************************/
typedef struct tmap_td 				*fz_tmap_ptr;

/****************************************************************

	fz_tmap_embd_ptr


	Description
		Data structure for a texture map that may have pixels already loaded in memory. If they are, 
		pixels are saved to disk anytime the texture map is saved. The fz_tmap_embd_ptr also 
		maintains a reference to the image file where the orignal texture came from. 
		To achieve this it contains a fz_tmap_ptr structure.

	Availability	7.0.0.0


	See Also
		fz_rmtl_get_simple_parms, fz_srep_cbak_get_generic_parm, fz_srep_cbak_set_generic_parm,  
		fz_tmap_embd_same_as_tmap_org, fz_tmap_embd_set_floc, fz_tmap_embd_to_tmap_file

 ****************************************************************/
typedef struct tmap_embd_td 		*fz_tmap_embd_ptr;


/****************************************************************

	fz_tmap_channel_enum


	Description
		Defines which channels of a texture map file are requested to be 
		loaded. This enum is used in the API function fz_tmap_get_pixels.

	Members
		FZ_TMAP_CHANNEL_RGB
			Load the red, green and blue channels of the file. These channels 
			are always present, even if the texture is black and while or 
			cmyk.
		FZ_TMAP_CHANNEL_ALPHA
			Load the alpha channel of the file. This option is only valid if 
			the texture map possesses an alpha channel.
		FZ_TMAP_CHANNEL_RGB_ALPHA
			Load the red, green, blue and alpha channels of the file. This option is only valid if 
			the texture map possesses an alpha channel.

	Availability	5.0.0.0


	See Also
		fz_tmap_get_pixels

 ****************************************************************/
typedef enum fz_tmap_channel_enum
{
	FZ_TMAP_CHANNEL_RGB,
	FZ_TMAP_CHANNEL_ALPHA,
	FZ_TMAP_CHANNEL_RGB_ALPHA

} fz_tmap_channel_enum;

/****************************************************************

	fz_tmap_get_floc



	Description
		Gets the file locator (floc) of a texture map. The floc 
		argument needs to be allocated and disposed by the 
		calling code via the API functions fzrt_file_floc_init 
		and fzrt_file_floc_finit. 
		fz_tmap_find_file should be called before using this function.

	Parameters
		tmap  [Input]
			the texture map for which to get the file locator
		floc  [Result]
			the file locator

	Returns
		error codes


	Availability	5.0.0.0


	See Also
		fz_tmap_set_floc_func

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_get_floc_func) (
	fz_tmap_ptr			tmap,
	fzrt_floc_ptr		floc
	);
										
/****************************************************************

	fz_tmap_set_floc



	Description
		Sets the file locator (floc) of a texture map. The floc 
		argument needs to be allocated and disposed by the 
		calling code via the API functions fzrt_file_floc_init 
		and fzrt_file_floc_finit. This function call effectively 
		changes, which file a texture map is associated with. 
		If the floc identifies a file which is not a supported 
		image file, an error is returned. The cropping information 
		is always reset to the full texture width and height.

	Parameters
		tmap  [Input]
			the texture map for which to set the file locator
		floc  [Input]
			the file locator

	Returns
		error codes


	Availability	5.0.0.0


	See Also
		fz_tmap_get_floc_func

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_set_floc_func) (
	fz_tmap_ptr			tmap,
	fzrt_floc_ptr		floc
	);

/****************************************************************

	fz_tmap_get_crop_rect



	Description
		Gets the cropping rectangle of a texture map. This is 
		a rectangle which specifies a sub portion of the 
		texture. 
		fz_tmap_find_file should be called before using this function.

	Parameters
		tmap  [Input]
			the texture map for which to get the cropping rectangle
		rect  [Result]
			the cropping rectangle

	Returns
		error codes


	Availability	5.0.0.0


	See Also
		fz_tmap_set_crop_rect

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_get_crop_rect_func) (
	fz_tmap_ptr			tmap,
	fzrt_rect			*rect
	);
										
/****************************************************************

	fz_tmap_set_crop_rect



	Description
		Sets the cropping rectangle of a texture map. This is 
		a rectangle which specifies a sub portion of the 
		texture. if the cropping rectangle exceeds the actual 
		size of the texture, an error is returned. If NULL is 
		passed for the rect argument, the cropping rectangle of the 
		texture is set to no cropping (i.e. the full texture). 
		fz_tmap_find_file should be called before using this function.

	Parameters
		tmap  [Input]
			the texture map for which to set the cropping rectangle
		rect  [Input]
			the cropping rectangle

	Returns
		error codes


	Availability	5.0.0.0


	See Also
		fz_tmap_get_crop_rect

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_set_crop_rect_func) (
	fz_tmap_ptr			tmap,
	fzrt_rect			*rect
	);
										
/****************************************************************

	fz_tmap_get_info



	Description
		Gets basic information about the texture map : width, height and 
		whether an alpha channel is present. The width and height 
		parameters are the original (uncropped) dimensions of the 
		texture. 
		fz_tmap_find_file should be called before using this function.

	Parameters
		tmap  [Input]
			the texture map for which to get the info
		width  [Result]
			the width of the texture map in # of pixels
		height  [Result]
			the height of the texture map in # of pixels
		has_alpha  [Result]
			TRUE, if the texture map has an alpha channel, FALSE otherwise

	Returns
		error codes


	Availability	5.0.0.0


	See Also
		fz_tmap_get_pixels

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_get_info_func) (
	fz_tmap_ptr			tmap,
	fzrt_int				*width,
	fzrt_int				*height,
	fzrt_boolean		*has_alpha
	);

/****************************************************************

	fz_tmap_get_pixels



	Description
		Gets the pixels of a texture map. The channel argument indicates whether 
		the rgb, alpha or rgb and alpha channels are returned. The pixels 
		array must be allocated by the calling code to provide enough 
		space to hold the cropped image of the texture. The required 
		space can be calculated as follows : 

		nbytes = (crop_rect.right - crop_rect.left) * (crop_rect.bottom - crop_rect.top) * num_channels

		When loading the rgb channels, num_channels is 3, the alpha channel only, num_channels is 1 and 
		rgb and alpha, num_channels is 4.

		fz_tmap_find_file should be called before using this function.

	Parameters
		tmap  [Input]
			the texture map for which to get the pixels
		pixels  [Result]
			a preallocated array which receives the pixels
		channels  [Input]
			which channels of the texture map to extract

	Returns
		error codes


	Availability	5.0.0.0


	See Also
		fz_tmap_get_info

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_get_pixels_func) (
	fz_tmap_ptr				tmap,
	unsigned char			*pixels,
	fz_tmap_channel_enum	channels
	);

/****************************************************************

	fz_tmap_find_file



	Description
		Locates a texture map on file. This function should be 
		called for a given texture map before any of the other texture map related 
		functions are used. It makes sure that the texture map 
		does indeed exist in the location specified in the path 
		stored with the texture map. If it does not, this function searches in the 
		file search paths associated with the project. If it still cannot 
		be found, and the silent argument is set to FALSE, a dialog 
		is invoked to ask for the location of the texture map. If the 
		silent argument is TRUE, this step is skipped. An error is 
		returned if the texture map cannot be located after any of 
		the searches or by asking the user.

	Parameters
		windex  [Input]
			project window index
		tmap  [Input]
			the texture map to be found
		silent  [Input]
			Set to FALSE, if allowing to ask the user to locate it if it cannot be found. 
			Set to TRUE, if no dialogs are to be presented to the user.

	Returns
		error codes


	Availability	5.5.0.0


	See Also
		fz_tmap_get_info

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_find_file_func) (
	fzrt_int					windex,
	fz_tmap_ptr				tmap,
	fzrt_boolean			silent
	);
	
/****************************************************************

	fz_tmap_allocate



	Description
		Allocates and initializes a texture map structure.	The texture map 
		is set to the formZ logo default texture.

	Parameters
		zone_ptr  [Input]
			the memory zone in which the texture map's memory is allocated
		tmap  [Result]
			the new texture map

	Returns
		error codes


	Availability	7.0.0.0


	See Also
		fz_tmap_finit

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_allocate_func) (
	fzrt_zone_ptr			zone_ptr,
	fz_tmap_ptr				*tmap
	);

/****************************************************************

	fz_tmap_free



	Description
		Frees a texture map, previously allocated with fz_tmap_init. The tmap 
		pointer is deallocated and returnd as NULL.

	Parameters
		zone_ptr  [Input]
			the memory zone in which the texture map's memory was allocated
		tmap  [Input, Result]
			the texture map to be freed

	Returns
		error codes


	Availability	7.0.0.0


	See Also
		fz_tmap_finit

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_free_func) (
	fzrt_zone_ptr			zone_ptr,
	fz_tmap_ptr				*tmap
	);


/****************************************************************

	fz_tmap_embd_get_info_func



	Description
		Gets embedded texture map info

	Parameters
		tmap_embd  [Input]
			the embedded texture map for which to get the info
		width  [Result, Optional]
			the width of the texture map in # of pixels
		height  [Result, Optional]
			the height of the texture map in # of pixels
		channels  [Result, Optional]
			The type of channels : RGB, RGBA, ALPHA

	Returns
		error codes


	Availability	7.0.0.0

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_get_info_func) (
	fz_tmap_embd_ptr		tmap_embd,
	fzrt_int					*width,
	fzrt_int					*height,
	fz_tmap_channel_enum	*channels
	);

/****************************************************************

	fz_tmap_embd_get_pixels



	Description
		Gets the pixels of an embedded texture map. pixels must be allocated 
		by the calling code to width * height * num_channels. You may also 
		call fz_tmap_embd_get_mem_size to get the exact memory size needed.

	Parameters
		tmap_embd  [Input]
			the embedded texture map for which to get the pixels
		pixels  [Input]
			A preallocated array to hold the pixels

	Returns
		error codes


	Availability	7.0.0.0


	See Also
		fz_tmap_embd_get_mem_size

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_get_pixels_func) (
	fz_tmap_embd_ptr		tmap_embd,
	unsigned char			*pixels
	);

/****************************************************************

	fz_tmap_embd_get_mem_size



	Description
		Gets the size of memory (in bytes) occupied by the pixels of an 
		embeeded tmap. This function can be called to determine how much 
		memory to allcoate for the pixels when calling fz_tmap_embd_get_pixels

	Parameters
		tmap_embd  [Input]
			the embedded texture map for which to get the size
		mem_size  [Result]
			The memory size required for the pixels

	Returns
		error codes


	Availability	7.0.0.0


	See Also
		fz_tmap_embd_get_pixels

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_get_mem_size_func) (
	fz_tmap_embd_ptr		tmap_embd,
	fzrt_int					*mem_size
	);

/****************************************************************

	fz_tmap_embd_to_tmap_file



	Description
		Writes a new image file from the pixels of an embedded tmap. The file 
		name and location are specified via the floc argument. The image file 
		type is identified by ffmt_id. The tmap passed in need to be allocated 
		via fz_tmap_allocate by the calling code.

	Parameters
		windex  [Input]
			project window index
		tmap_embd  [Input]
			the embedded texture map
		floc  [Input]
			the file locator
		ffmt_id  [Input]
			the file format id

	Returns
		error codes


	Availability	7.0.0.0


	See Also
		fz_tmap_allocate

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_to_tmap_file_func) (
	fzrt_int				windex,
	fz_tmap_embd_ptr	tmap_embd,
	fzrt_floc_ptr		floc,
	fz_ffmt_ref_td		ffmt_id
	);

/****************************************************************

	fz_tmap_embd_same_as_tmap_org



	Description
		Determine whether the original source file for the embedded tmap 
		is no longer the same as the pixels in the embedded tmap 
		They are the same if : 
		The original file can be found 
		The original file has the same width and height 
		The pixels are identical

	Parameters
		windex  [Input]
			project window index
		tmap_embd  [Input]
			the embedded texture map
		are_same  [Result]
			TRUE, if the original file and the embdded pixels are the same, FALSE otherwise

	Returns
		error codes


	Availability	7.0.0.0

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_same_as_tmap_org_func) (
	fzrt_int				windex,
	fz_tmap_embd_ptr	tmap_embd,
	fzrt_boolean		*are_same
	);

/****************************************************************

	fz_tmap_embd_allocate



	Description
		Allocates and initializes an embedded texture map structure. Note, that 
		no pixles are loaded yet. This needs to be done with a subsequent call 
		to fz_tmap_embd_set_floc

	Parameters
		zone_ptr  [Input]
			the memory zone in which the texture map's memory is allocated
		tmap_embd  [Result]
			the embedded texture map

	Returns
		error codes


	Availability	7.0.0.0


	See Also
		fz_tmap_embd_set_floc

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_allocate_func) (
	fzrt_zone_ptr		zone_ptr,
	fz_tmap_embd_ptr	*tmap_embd
	);

/****************************************************************

	fz_tmap_embd_free



	Description
		Deallocates an embdedded texture map, previously allocated with fz_tmap_embd_allocate

	Parameters
		zone_ptr  [Input]
			the memory zone in which the texture map's memory is allocated
		tmap_embd  [Input, Result]
			the embedded texture map

	Returns
		error codes


	Availability	7.0.0.0


	See Also
		fz_tmap_embd_allocate

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_free_func) (
	fzrt_zone_ptr		zone_ptr,
	fz_tmap_embd_ptr	*tmap_embd
	);

/****************************************************************

	fz_tmap_embd_set_floc



	Description
		Associates an embdded texture map with a texture file and laods the 
		pixels from the file into memory. The load_alpha argument determines 
		whether the alpha channel or RGB channels of the file are loaded. If 
		load_alpha is TRUE and the file does not have an alpha channel, the 
		rgb channels are loaded instead.

	Parameters
		windex  [Input]
			project window index
		tmap_embd  [Input]
			the embedded texture map
		floc  [Input]
			the file locator, which identifies the texture file
		load_alpha  [Input]
			If set to TRUE, only the alpha channel is loaded. Otherwise RGB channels are loaded

	Returns
		error codes


	Availability	7.0.0.0


	See Also
		fz_tmap_embd_get_floc

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_set_floc_func) (
	fzrt_int				windex,
	fz_tmap_embd_ptr	tmap_embd,
	fzrt_floc_ptr		floc,
	fzrt_boolean		load_alpha
	);

/****************************************************************

	fz_tmap_embd_get_floc



	Description
		Gets the floc of the file, from which the pixels of the embedded texture 
		map were once loaded. Note, that is is not quaranteed, that this file 
		still exists. fz_tmap_embd_find_file should be called first to locate 
		the file on disk.

	Parameters
		tmap_embd  [Input]
			the embedded texture map
		floc  [Input]
			the file locator

	Returns
		error codes


	Availability	7.0.0.0


	See Also
		fz_tmap_embd_set_floc,fz_tmap_embd_find_file

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_get_floc_func) (
	fz_tmap_embd_ptr	tmap_embd,
	fzrt_floc_ptr		floc
	);

/****************************************************************

	fz_tmap_embd_find_file



	Description
		Find the image file of an embedded tmap on the disk

	Parameters
		windex  [Input]
			project window index
		tmap_embd  [Input]
			the embedded texture map
		silent  [Input]
			If FALSE, a dialog will be displayed to ask for the 
			location of the file, if it can't be found. If TRUE 
			no dialog will be p[osted.

	Returns
		error codes


	Availability	7.0.0.0

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_find_file_func) (
	fzrt_int				windex,
	fz_tmap_embd_ptr	tmap_embd,
	fzrt_boolean		silent
	);

/****************************************************************

	fz_tmap_embd_copy



	Description
		Copies one embedded tmap to another. Note, that the destiantion tmap 
		must have been previoulsy been allocated via fz_tmap_embd_allocate

	Parameters
		src_tmap  [Input]
			the source embedded texture map
		dst_tmap  [Input]
			the destination embedded texture map

	Returns
		error codes


	Availability	7.0.0.0


	See Also
		fz_tmap_embd_allocate

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_copy_func) (
	fz_tmap_embd_ptr	src_tmap,
	fz_tmap_embd_ptr	dst_tmap
	);

/****************************************************************

	fz_tmap_embd_iost



	Description
		iost for an embedded tmap. Note, that when reading, the tmap must be 
		allocated first with a call to fz_tmap_embd_allocate.

	Parameters
		iost  [Input]
			the io stream from which to read / to which to write
		dir  [Input]
			FZ_IOST_READ or FZ_IOST_WRITE
		tmap_embd  [Input]
			the embedded texture map

	Returns
		error codes


	Availability	7.0.0.0


	See Also
		fz_tmap_embd_allocate

 ****************************************************************/
typedef fzrt_error_td  (*fz_tmap_embd_iost_func) (
	fz_iost_ptr 		iost,
	fz_iost_dir_td_enum dir,
	fz_tmap_embd_ptr	tmap_embd
	);

/****************************************************************

	fz_tmap_fset


	FZ_TMAP_FSET_TYPE
		formZ Texture Map function set UUID.

	FZ_TMAP_FSET_NAME
		formZ Texture Map function set name.

	FZ_TMAP_FSET_VERSION
		formZ Texture Map function set version.

	Description
		formZ Texture Map function set

	Availability	5.0.0.0

 ****************************************************************/


#define FZ_TMAP_FSET_TYPE		"\xa4\x47\x16\xf2\x18\x0f\x4b\x79\x88\xd2\x5c\xb6\x5a\xfa\x9b\x1e"
	
#define FZ_TMAP_FSET_NAME		"formZ Texture Map functions"

#define FZ_TMAP_FSET_VERSION	FZPL_VERS_MAKE(7,0,0,0)

typedef struct fz_tmap_fset
{
	fzpl_fset_prvt_data_td				prvt_data;
	
	fz_tmap_get_floc_func				fz_tmap_get_floc;
	fz_tmap_set_floc_func				fz_tmap_set_floc;
	fz_tmap_get_crop_rect_func			fz_tmap_get_crop_rect;
	fz_tmap_set_crop_rect_func			fz_tmap_set_crop_rect;
	fz_tmap_get_info_func				fz_tmap_get_info;
	fz_tmap_get_pixels_func				fz_tmap_get_pixels;
	
	
	
	fz_tmap_find_file_func				fz_tmap_find_file;
	fz_tmap_allocate_func				fz_tmap_allocate;
	fz_tmap_free_func					fz_tmap_free;

	


	fz_tmap_embd_get_info_func			fz_tmap_embd_get_info;
	fz_tmap_embd_get_pixels_func		fz_tmap_embd_get_pixels;
	fz_tmap_embd_get_mem_size_func		fz_tmap_embd_get_mem_size;
	fz_tmap_embd_to_tmap_file_func		fz_tmap_embd_to_tmap_file;
	fz_tmap_embd_same_as_tmap_org_func  fz_tmap_embd_same_as_tmap_org;
	fz_tmap_embd_allocate_func			fz_tmap_embd_allocate;
	fz_tmap_embd_free_func				fz_tmap_embd_free;
	fz_tmap_embd_set_floc_func			fz_tmap_embd_set_floc;
	fz_tmap_embd_get_floc_func			fz_tmap_embd_get_floc;
	fz_tmap_embd_find_file_func			fz_tmap_embd_find_file;
	fz_tmap_embd_copy_func				fz_tmap_embd_copy;
	fz_tmap_embd_iost_func				fz_tmap_embd_iost;



}  fz_tmap_fset;


#ifdef __cplusplus
}
#endif

#endif

