(make_texture -- Turn an image into a texture)

Functions
bool OIIO_API	ImageBufAlgo::make_texture (MakeTextureMode mode, const ImageBuf &input, string_view outputfilename, const ImageSpec &config, std::ostream *outstream=nullptr)
	Version of make_texture that starts with an ImageBuf. More...
bool OIIO_API	ImageBufAlgo::make_texture (MakeTextureMode mode, string_view filename, string_view outputfilename, const ImageSpec &config, std::ostream *outstream=nullptr)
bool OIIO_API	ImageBufAlgo::make_texture (MakeTextureMode mode, const std::vector< std::string > &filenames, string_view outputfilename, const ImageSpec &config, std::ostream *outstream=nullptr)

Detailed Description

The make_texture() function turns an image into a tiled, MIP-mapped, texture file and write it to disk (outputfilename).

The return value is true for success, false if an error occurred. If there was an error, any error message will be retrievable via the global OIIO::geterror() call (since there is no destination ImageBuf in which to store it).

Named fields in config:

• format : Data format of the texture file (default: UNKNOWN = same format as the input)
• tile_width/tile_height/tile_depth : Preferred tile size (default: 64x64x1)

Metadata in config.extra_attribs

• compression (string) : Default: "zip"
• fovcot (float) : Default: aspect ratio of the image resolution.
• planarconfig (string) : Default: "separate"
• worldtocamera (matrix) : World-to-camera matrix of the view.
• worldtoscreen (matrix) : World-to-screen space matrix of the view.
• worldtoNDC (matrix) : World-to-NDC space matrix of the view.
• wrapmodes (string) : Default: "black,black"
• maketx:verbose (int) : How much detail should go to outstream (0).
• maketx:runstats (int) : If nonzero, print run stats to outstream (0).
• maketx:resize (int) : If nonzero, resize to power of 2. (0)
• maketx:nomipmap (int) : If nonzero, only output the top MIP level (0).
• maketx:updatemode (int) : If nonzero, write new output only if the output file doesn't already exist, or is older than the input file, or was created with different command-line arguments. (0)
• maketx:constant_color_detect (int) : If nonzero, detect images that are entirely one color, and change them to be low resolution (default: 0).
• maketx:monochrome_detect (int) : If nonzero, change RGB images which have R==G==B everywhere to single-channel grayscale (default: 0).
• maketx:opaque_detect (int) : If nonzero, drop the alpha channel if alpha is 1.0 in all pixels (default: 0).
• maketx:compute_average (int) : If nonzero, compute and store the average color of the texture (default: 1).
• maketx:unpremult (int) : If nonzero, unpremultiply color by alpha before color conversion, then multiply by alpha after color conversion (default: 0).
• maketx:incolorspace, maketx:outcolorspace (string) : These two together will apply a color conversion (with OpenColorIO, if compiled). Default: ""
• maketx:colorconfig (string) : Specifies a custom OpenColorIO color config file. Default: ""
• maketx:checknan (int) : If nonzero, will consider it an error if the input image has any NaN pixels. (0)
• maketx:fixnan (string) : If set to "black" or "box3", will attempt to repair any NaN pixels found in the input image (default: "none").
• maketx:set_full_to_pixels (int) : If nonzero, doctors the full/display window of the texture to be identical to the pixel/data window and reset the origin to 0,0 (default: 0).
• maketx:filtername (string) : If set, will specify the name of a high-quality filter to use when resampling for MIPmap levels. Default: "", use bilinear resampling.
• maketx:highlightcomp (int) : If nonzero, performs highlight compensation – range compression and expansion around the resize, plus clamping negative pixel values to zero. This reduces ringing when using filters with negative lobes on HDR images.
• maketx:sharpen (float) : If nonzero, sharpens details when creating MIPmap levels. The amount is the contrast metric. The default is 0, meaning no sharpening.
• maketx:nchannels (int) : If nonzero, will specify how many channels the output texture should have, padding with 0 values or dropping channels, if it doesn't the number of channels in the input. (default: 0, meaning keep all input channels)
• maketx:channelnames (string) : If set, overrides the channel names of the output image (comma-separated).
• maketx:fileformatname (string) : If set, will specify the output file format. (default: "", meaning infer the format from the output filename)
• maketx:prman_metadata (int) : If set, output some metadata that PRMan will need for its textures. (0)
• maketx:oiio_options (int) : (Deprecated; all are handled by default)
• maketx:prman_options (int) : If nonzero, override a whole bunch of settings as needed to make textures that are compatible with PRMan. (0)
• maketx:mipimages (string) : Semicolon-separated list of alternate images to be used for individual MIPmap levels, rather than simply downsizing. (default: "")
• maketx:full_command_line (string) : The command or program used to generate this call, will be embedded in the metadata. (default: "")
• maketx:ignore_unassoc (int) : If nonzero, will disbelieve any evidence that the input image is unassociated alpha. (0)
• maketx:read_local_MB (int) : If nonzero, will read the full input file locally if it is smaller than this threshold. Zero causes the system to make a good guess at a reasonable threshold (e.g. 1 GB). (0)
• maketx:forcefloat (int) : Forces a conversion through float data for the sake of ImageBuf math. (1)
• maketx:hash (int) : Compute the sha1 hash of the file in parallel. (1)
• maketx:allow_pixel_shift (int) : Allow up to a half pixel shift per mipmap level. The fastest path may result in a slight shift in the image, accumulated for each mip level with an odd resolution. (0)
• maketx:bumpformat (string) : For the MakeTxBumpWithSlopes mode, chooses whether to assume the map is a height map ("height"), a normal map ("normal"), or automatically determine it from the number of channels ("auto", the default).
• maketx:uvslopes_scale (float) : If nonzero, when used in MakeTxBumpWithSlopes mode, this computes derivatives for the bumpslopes data in UV space rather than in texel space, and divides them by this scale factor. The default is 0, disabling the feature. If you use this feature, a suggested value is 256.
• maketx:cdf (int) : If nonzero, will write a Gaussian CDF and Inverse Gaussian CDF as per-channel metadata in the texture, which can be used by shaders to implement Histogram-Preserving Blending. This is only useful when the texture being created is written to an image format that supports arbitrary metadata (e.g. OpenEXR). (See Burley, "On Histogram-Preserving Blending for Randomized Texture Tiling," JCGT 8(4), 2019, and Heitz/Neyret, "High-Performance By-Example Noise using a Histogram-Preserving Blending Operator," ACM SIGGRAPH / Eurographics Symposium on High-Performance Graphics 2018.) (default: 0)
• maketx:cdfsigma (float) : When maketx:cdf is active, determines the CDF sigma (default: 1.0/6).
• maketx:cdfbits (int) : When maketx:cdf is active, determines the number of bits to use for the size of the CDF table. (default: 8, meaning 256 bins)

Parameters

mode	Describes what type of texture file we are creating and may be one of: MakeTxTexture : Ordinary 2D texture. MakeTxEnvLatl : Latitude-longitude environment map MakeTxEnvLatlFromLightProbe : Latitude-longitude environment map constructed from a "light probe" image. MakeTxBumpWithSlopes : Bump/displacement map with extra slope data channels (6 channels total, containing both the height and 1st and 2nd moments of slope distributions) for bump-to-roughness conversion in shaders.
outputfilename	Name of the file in which to save the resulting texture.
config	An ImageSpec that contains all the information and special instructions for making the texture. Anything set in config (format, tile size, or named metadata) will take precedence over whatever is specified by the input file itself. Additionally, named metadata that starts with "maketx:" will not be output to the file itself, but may contain instructions controlling how the texture is created. The full list of supported configuration options is listed below.
outstream	If not nullptr, it should point to a stream (for example, &std::out, or a pointer to a local std::stringstream to capture output), which is where console output and errors will be deposited. Note that error messages will also be retrievable from OIIO::geterror().

Function Documentation

bool OIIO_API ImageBufAlgo::make_texture	(	MakeTextureMode	mode,
		const ImageBuf &	input,
		string_view	outputfilename,
		const ImageSpec &	config,
		std::ostream *	outstream = nullptr
	)

Version of make_texture that starts with an ImageBuf.

bool OIIO_API ImageBufAlgo::make_texture	(	MakeTextureMode	mode,
		string_view	filename,
		string_view	outputfilename,
		const ImageSpec &	config,
		std::ostream *	outstream = nullptr
	)

Version of make_texture that starts with a filename and reads the input from that file, rather than being given an ImageBuf directly.

bool OIIO_API ImageBufAlgo::make_texture	(	MakeTextureMode	mode,
		const std::vector< std::string > &	filenames,
		string_view	outputfilename,
		const ImageSpec &	config,
		std::ostream *	outstream = nullptr
	)

Version of make_texture that takes multiple filenames (reserved for future expansion, such as assembling several faces into a cube map).