path: root/support/dktools/dk4bif.h

/*
Copyright (C) 2017-2020, Dirk Krause
SPDX-License-Identifier: BSD-3-Clause
*/

/*
	WARNING: This file was generated by the dkct program (see
	http://dktools.sourceforge.net/ for details).
	Changes you make here will be lost if dkct is run again!
	You should modify the original source and run dkct on it.
	Original source: dk4bif.ctr
*/

#ifndef DK4BIF_H_INCLUDED
/** Avoid multiple inclusions. */
#define DK4BIF_H_INCLUDED 1


#line 7 "dk4bif.ctr"

/**	@file dk4bif.h	Bitmap image files.
*/

#ifndef	DK4CONF_H_INCLUDED
#if	DK4_BUILDING_DKTOOLS4
#include "dk4conf.h"
#else
#include <dktools-4/dk4conf.h>
#endif
#endif

#ifndef	DK4BIFTY_H_INCLUDED
#if	DK4_BUILDING_DKTOOLS4
#include "dk4bifty.h"
#else
#include <dktools-4/dk4bifty.h>
#endif
#endif

#ifdef	__cplusplus
extern "C" {
#endif


/**	Find bitmap image file type for file name.
	@param	fn	File name to check.
	@return	Non-negative dk4_bif_type_t value on success,
	-1 on error (NULL file name or file name suffix does not indicate
	a graphics type the function can handle).
*/

int
dk4bif_type_for_suffix(
	dkChar	const	*fn
);


/**	Open bitmap image file.
	@param	fn		File name containing the bitmap image.
	@param	hdronly	Flag: Read header only.
	@param	pcsctx	Color space conversion context, may be NULL.
	@param	erp		Error report, may be NULL.
	@return	Valid pointer to bitmap image file on success, NULL on error.

	Error codes:
	- DK4_E_INVALID_ARGUMENTS<br>
	  if fn is NULL,
	- DK4_E_NOT_FOUND<br>
	  if the file name does not contain a suffix or the suffix does
	  not indicate a bitmap image file type the function can handle,
	- DK4_E_MEMORY_ALLOCATION_FAILED<br>
	  if a memory allocation failed,
	- DK4_E_SYNTAX<br>
	  if the file contents is incorrect (not matching the specified file
	  type),
	- DK4_E_READ_FAILED<br>
	  if the function failed to read from file fn.
*/

dk4_bif_t *
dk4bif_open(
	dkChar	const				*fn,
	int							 hdronly,
	dk4_cs_conv_ctx_t	const	*pcsctx,
	dk4_er_t					*erp
);


/**	Open bitmap image file.
	@param	fn		File name containing the bitmap image.
	@param	ty		Image file type (PNG, JPEG or TIFF).
	@param	honly	Flag: Read header information only.
	@param	pcsctx	Color space conversion context, may be NULL.
	@param	erp		Error report, may be NULL.
	@return	Valid pointer to bitmap image file on success, NULL on error.

	Error codes:
	- DK4_E_INVALID_ARGUMENTS<br>
	  if fn is NULL or an unknown bitmap type is requested,
	- DK4_E_READ_FAILED<br>
	  if the function failed to read from file fn,
	- DK4_E_NOT_SUPPORTED<br>
	  if the operation is not supported (i.e. compiled without a
	  required library).
*/

dk4_bif_t *
dk4bif_open_type(
	dkChar	const				*fn,
	int							 ty,
	int							 honly,
	dk4_cs_conv_ctx_t	const	*pcsctx,
	dk4_er_t					*erp
);


/**	Open bitmap image file.
	@param	fipo	File, opened for binary reading.
	@param	fn		File name containing the bitmap image.
	@param	ty		Image file type (PNG, JPEG or TIFF).
	@param	honly	Flag: Read image header only.
	@param	pcsctx	Color space conversion context, may be NULL.
	@param	erp		Error report, may be NULL.
	@return	Valid pointer to bitmap image file on success, NULL on error.

	Error codes:
	- DK4_E_INVALID_ARGUMENTS<br>
	  if fipo or fn is NULL,
	- DK4_E_NOT_SUPPORTED<br>
	  if the operation is not supported (i.e. compiled without a
	  required library).
*/

dk4_bif_t *
dk4bif_open_file(
	FILE						*fipo,
	dkChar	const				*fn,
	int							 ty,
	int							 honly,
	dk4_cs_conv_ctx_t	const	*pcsctx,
	dk4_er_t					*erp
);


/**	Close bitmap image file and release resources.
	@param	bif		Bitmap image file to close.
*/

void
dk4bif_close(
	dk4_bif_t		*bif
);


/**	Find number of frames in bitmap image file.
	@param	bif		Bitmap image file to query.
	@return	Positive value on success, 0 on error.
*/

size_t
dk4bif_get_number_of_frames(
	dk4_bif_t const		*bif
);


/**	Set current frame in a bitmap image file.
	@param	bif		Bitmap image file.
	@param	fno		Index of new current frame (0 for first frame).
	@return	1 on success, 0 on error (out of range).
*/

int
dk4bif_set_current_frame(
	dk4_bif_t		*bif,
	size_t			 fno
);


/**	Retrieve low level bit depth of current frame bitmap image file.
	@param	bif		Bitmap image file
	@return	Positive value on success, 0 on error.
*/

dk4_px_bit_depth_t
dk4bif_get_original_bit_depth(
	dk4_bif_t const		*bif
);


/**	Retrieve color space of current frame returned from low-level library.
	@param	bif		Bitmap image file.
	@return	Non-negative dk4_bif_cs_t value on success, -1 on error.
*/

int
dk4bif_get_color_space(
	dk4_bif_t const		*bif
);


/**	Retrieve color space of current frame contained in the file.
	@param	bif		Bitmap image file.
	@return	Non-negative dk4_bif_cs_t value on success, -1 on error.
*/

int
dk4bif_get_file_color_space(
	dk4_bif_t const		*bif
);


/**	Set required output bit depth for pixel data to retrieve for
	all frames.
	@param	bif		Bitmap image file.
	@param	bd		Required output bit depth.
	@return	1 on success, 0 on error.
*/

int
dk4bif_set_output_bit_depth(
	dk4_bif_t			*bif,
	dk4_px_bit_depth_t	 bd
);


/**	Set default background or enforced background for bitmap image file
	for all frames.
	@param	bif		Bitmap image file.
	@param	bg		Array containing background values.
	@param	szbg	Size of bg array (number of elements).
	@param	bd		Bit depth used in the bg array.
	@param	force	Flag: Enforce this background. Without this flag the
					background information from here is used only if no
					background information was found in the file.
	@return	1 on success, 0 on error.
*/

int
dk4bif_set_background(
	dk4_bif_t					*bif,
	dk4_px_t			const	*bg,
	size_t						 szbg,
	dk4_px_bit_depth_t			 bd,
	int							 force
);


/**	Get image type.
	@param	bif	Bitmap image file.
	@return	Non-negative image type on success, negative value on error.
*/

int
dk4bif_get_image_type(
	dk4_bif_t	const	*bif
);


/**	Retrieve data for one pixel in the required output bit depth
	and color space.
	@param	dptr	Address of destination array, must be large enough.
	@param	szdptr	Size of dptr array (number of elements).
	@param	bif		Bitmap image file.
	@param	rowno	Row number (0 for top row).
	@param	colno	Column number (0 for left column).
	@param	cs		Required color space.
	@return	1 on success, 0 on error.
*/

int
dk4bif_get_pixel(
	dk4_px_t				*dptr,
	size_t					 szdptr,
	dk4_bif_t		const	*bif,
	dk4_bif_dim_t			 rowno,
	dk4_bif_dim_t			 colno,
	int						 cs
);


/**	Get the current frames x resolution in dpi.
	@param	bif	Bitmap image file.
	@return	Positive number on success, negative value on error or if
	not found.
*/

double
dk4bif_get_xres(
	dk4_bif_t const		*bif
);


/**	Get the current frames y resolution in dpi.
	@param	bif	Bitmap image file.
	@return	Positive number on success, negative value on error or if
	not found.
*/

double
dk4bif_get_yres(
	dk4_bif_t const		*bif
);


/**	Set resolution explicitly.
	@param	bif		Bitmap image file.
	@param	xres	X resolution, must be positive.
	@param	yres	Y resolution, must be positive.
	@param	erp		Error report, may be NULL.
	@return	1 on success, 0 on error
*/

int
dk4bif_set_res(
	dk4_bif_t			*bif,
	double				 xres,
	double				 yres,
	dk4_er_t			*erp
);

/**	Get current frame width.
	@param	bif	Bitmap image file.
	@return	Positive number on success, negative value on error.
*/

dk4_bif_dim_t
dk4bif_get_width(
	dk4_bif_t const		 *bif
);


/**	Get current frame height.
	@param	bif	Bitmap image file.
	@return	Positive number on success, negative value on error.
*/

dk4_bif_dim_t
dk4bif_get_height(
	dk4_bif_t const 		*bif
);


/**	Get color space conversion context for bitmap image.
	@param	bif	Bitmap image file.
	@return	Valid pointer on success, NULL on error.
*/

const
dk4_cs_conv_ctx_t *
dk4bif_get_cs_conv_ctx(
	dk4_bif_t const		*bif
);


/**	Set color space conversion context for bitmap image.
	@param	bif		Bitmap image file.
	@param	pctx	Color space conversion context to use.
*/

void
dk4bif_set_cs_conv_ctx(
	dk4_bif_t					*bif,
	dk4_cs_conv_ctx_t	const	*pctx
);


/**	Close a bitmap image frame, release ressources.
	@param	frptr	Frame to close.
	@param	imgtype	Bitmap image file type.
*/

void
dk4bif_frame_close(
	dk4_bif_frame_t	*frptr,
	int				 imgtype
);

#ifdef	__cplusplus
}
#endif

/* vim: set ai sw=4 ts=4 : */

#endif