summaryrefslogtreecommitdiff
path: root/support/dktools/dk4bif.h
blob: 8336ba59f6340ee5694cda6d54f7be2925815dc9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
/*
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