1 /* 2 Copyright (C) 2017-2021, Dirk Krause 3 SPDX-License-Identifier: BSD-3-Clause 4 */ 5 6 /* 7 WARNING: This file was generated by the dkct program (see 8 http://dktools.sourceforge.net/ for details). 9 Changes you make here will be lost if dkct is run again! 10 You should modify the original source and run dkct on it. 11 Original source: dk4bif.ctr 12 */ 13 14 #ifndef DK4BIF_H_INCLUDED 15 /** Avoid multiple inclusions. */ 16 #define DK4BIF_H_INCLUDED 1 17 18 19 /** @file dk4bif.h Bitmap image files. 20 */ 21 22 #ifndef DK4CONF_H_INCLUDED 23 #if DK4_BUILDING_DKTOOLS4 24 #include "dk4conf.h" 25 #else 26 #include <dktools-4/dk4conf.h> 27 #endif 28 #endif 29 30 #ifndef DK4BIFTY_H_INCLUDED 31 #if DK4_BUILDING_DKTOOLS4 32 #include <libdk4bif/dk4bifty.h> 33 #else 34 #include <dktools-4/dk4bifty.h> 35 #endif 36 #endif 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 43 /** Find bitmap image file type for file name. 44 @param fn File name to check. 45 @return Non-negative dk4_bif_type_t value on success, 46 -1 on error (NULL file name or file name suffix does not indicate 47 a graphics type the function can handle). 48 */ 49 50 int 51 dk4bif_type_for_suffix( 52 dkChar const *fn 53 ); 54 55 56 /** Open bitmap image file. 57 @param fn File name containing the bitmap image. 58 @param hdronly Flag: Read header only. 59 @param pcsctx Color space conversion context, may be NULL. 60 @param erp Error report, may be NULL. 61 @return Valid pointer to bitmap image file on success, NULL on error. 62 63 Error codes: 64 - DK4_E_INVALID_ARGUMENTS<br> 65 if fn is NULL, 66 - DK4_E_NOT_FOUND<br> 67 if the file name does not contain a suffix or the suffix does 68 not indicate a bitmap image file type the function can handle, 69 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 70 if a memory allocation failed, 71 - DK4_E_SYNTAX<br> 72 if the file contents is incorrect (not matching the specified file 73 type), 74 - DK4_E_READ_FAILED<br> 75 if the function failed to read from file fn. 76 */ 77 78 dk4_bif_t * 79 dk4bif_open( 80 dkChar const *fn, 81 int hdronly, 82 dk4_cs_conv_ctx_t const *pcsctx, 83 dk4_er_t *erp 84 ); 85 86 87 /** Open bitmap image file. 88 @param fn File name containing the bitmap image. 89 @param ty Image file type (PNG, JPEG or TIFF). 90 @param honly Flag: Read header information only. 91 @param pcsctx Color space conversion context, may be NULL. 92 @param erp Error report, may be NULL. 93 @return Valid pointer to bitmap image file on success, NULL on error. 94 95 Error codes: 96 - DK4_E_INVALID_ARGUMENTS<br> 97 if fn is NULL or an unknown bitmap type is requested, 98 - DK4_E_READ_FAILED<br> 99 if the function failed to read from file fn, 100 - DK4_E_NOT_SUPPORTED<br> 101 if the operation is not supported (i.e. compiled without a 102 required library). 103 */ 104 105 dk4_bif_t * 106 dk4bif_open_type( 107 dkChar const *fn, 108 int ty, 109 int honly, 110 dk4_cs_conv_ctx_t const *pcsctx, 111 dk4_er_t *erp 112 ); 113 114 115 /** Open bitmap image file. 116 @param fipo File, opened for binary reading. 117 @param fn File name containing the bitmap image. 118 @param ty Image file type (PNG, JPEG or TIFF). 119 @param honly Flag: Read image header only. 120 @param pcsctx Color space conversion context, may be NULL. 121 @param erp Error report, may be NULL. 122 @return Valid pointer to bitmap image file on success, NULL on error. 123 124 Error codes: 125 - DK4_E_INVALID_ARGUMENTS<br> 126 if fipo or fn is NULL, 127 - DK4_E_NOT_SUPPORTED<br> 128 if the operation is not supported (i.e. compiled without a 129 required library). 130 */ 131 132 dk4_bif_t * 133 dk4bif_open_file( 134 FILE *fipo, 135 dkChar const *fn, 136 int ty, 137 int honly, 138 dk4_cs_conv_ctx_t const *pcsctx, 139 dk4_er_t *erp 140 ); 141 142 143 /** Close bitmap image file and release resources. 144 @param bif Bitmap image file to close. 145 */ 146 147 void 148 dk4bif_close( 149 dk4_bif_t *bif 150 ); 151 152 153 /** Find number of frames in bitmap image file. 154 @param bif Bitmap image file to query. 155 @return Positive value on success, 0 on error. 156 */ 157 158 size_t 159 dk4bif_get_number_of_frames( 160 dk4_bif_t const *bif 161 ); 162 163 164 /** Set current frame in a bitmap image file. 165 @param bif Bitmap image file. 166 @param fno Index of new current frame (0 for first frame). 167 @return 1 on success, 0 on error (out of range). 168 */ 169 170 int 171 dk4bif_set_current_frame( 172 dk4_bif_t *bif, 173 size_t fno 174 ); 175 176 177 /** Retrieve low level bit depth of current frame bitmap image file. 178 @param bif Bitmap image file 179 @return Positive value on success, 0 on error. 180 */ 181 182 dk4_px_bit_depth_t 183 dk4bif_get_original_bit_depth( 184 dk4_bif_t const *bif 185 ); 186 187 188 /** Retrieve color space of current frame returned from low-level library. 189 @param bif Bitmap image file. 190 @return Non-negative dk4_bif_cs_t value on success, -1 on error. 191 */ 192 193 int 194 dk4bif_get_color_space( 195 dk4_bif_t const *bif 196 ); 197 198 199 /** Retrieve color space of current frame contained in the file. 200 @param bif Bitmap image file. 201 @return Non-negative dk4_bif_cs_t value on success, -1 on error. 202 */ 203 204 int 205 dk4bif_get_file_color_space( 206 dk4_bif_t const *bif 207 ); 208 209 210 /** Set required output bit depth for pixel data to retrieve for 211 all frames. 212 @param bif Bitmap image file. 213 @param bd Required output bit depth. 214 @return 1 on success, 0 on error. 215 */ 216 217 int 218 dk4bif_set_output_bit_depth( 219 dk4_bif_t *bif, 220 dk4_px_bit_depth_t bd 221 ); 222 223 224 /** Set default background or enforced background for bitmap image file 225 for all frames. 226 @param bif Bitmap image file. 227 @param bg Array containing background values. 228 @param szbg Size of bg array (number of elements). 229 @param bd Bit depth used in the bg array. 230 @param force Flag: Enforce this background. Without this flag the 231 background information from here is used only if no 232 background information was found in the file. 233 @return 1 on success, 0 on error. 234 */ 235 236 int 237 dk4bif_set_background( 238 dk4_bif_t *bif, 239 dk4_px_t const *bg, 240 size_t szbg, 241 dk4_px_bit_depth_t bd, 242 int force 243 ); 244 245 246 /** Get image type. 247 @param bif Bitmap image file. 248 @return Non-negative image type on success, negative value on error. 249 */ 250 251 int 252 dk4bif_get_image_type( 253 dk4_bif_t const *bif 254 ); 255 256 257 /** Retrieve data for one pixel in the required output bit depth 258 and color space. 259 @param dptr Address of destination array, must be large enough. 260 @param szdptr Size of dptr array (number of elements). 261 @param bif Bitmap image file. 262 @param rowno Row number (0 for top row). 263 @param colno Column number (0 for left column). 264 @param cs Required color space. 265 @return 1 on success, 0 on error. 266 */ 267 268 int 269 dk4bif_get_pixel( 270 dk4_px_t *dptr, 271 size_t szdptr, 272 dk4_bif_t const *bif, 273 dk4_bif_dim_t rowno, 274 dk4_bif_dim_t colno, 275 int cs 276 ); 277 278 279 /** Get the current frames x resolution in dpi. 280 @param bif Bitmap image file. 281 @return Positive number on success, negative value on error or if 282 not found. 283 */ 284 285 double 286 dk4bif_get_xres( 287 dk4_bif_t const *bif 288 ); 289 290 291 /** Get the current frames y resolution in dpi. 292 @param bif Bitmap image file. 293 @return Positive number on success, negative value on error or if 294 not found. 295 */ 296 297 double 298 dk4bif_get_yres( 299 dk4_bif_t const *bif 300 ); 301 302 303 /** Set resolution explicitly. 304 @param bif Bitmap image file. 305 @param xres X resolution, must be positive. 306 @param yres Y resolution, must be positive. 307 @param erp Error report, may be NULL. 308 @return 1 on success, 0 on error 309 */ 310 311 int 312 dk4bif_set_res( 313 dk4_bif_t *bif, 314 double xres, 315 double yres, 316 dk4_er_t *erp 317 ); 318 319 /** Get current frame width. 320 @param bif Bitmap image file. 321 @return Positive number on success, negative value on error. 322 */ 323 324 dk4_bif_dim_t 325 dk4bif_get_width( 326 dk4_bif_t const *bif 327 ); 328 329 330 /** Get current frame height. 331 @param bif Bitmap image file. 332 @return Positive number on success, negative value on error. 333 */ 334 335 dk4_bif_dim_t 336 dk4bif_get_height( 337 dk4_bif_t const *bif 338 ); 339 340 341 /** Get color space conversion context for bitmap image. 342 @param bif Bitmap image file. 343 @return Valid pointer on success, NULL on error. 344 */ 345 346 const 347 dk4_cs_conv_ctx_t * 348 dk4bif_get_cs_conv_ctx( 349 dk4_bif_t const *bif 350 ); 351 352 353 /** Set color space conversion context for bitmap image. 354 @param bif Bitmap image file. 355 @param pctx Color space conversion context to use. 356 */ 357 358 void 359 dk4bif_set_cs_conv_ctx( 360 dk4_bif_t *bif, 361 dk4_cs_conv_ctx_t const *pctx 362 ); 363 364 365 /** Close a bitmap image frame, release ressources. 366 @param frptr Frame to close. 367 @param imgtype Bitmap image file type. 368 */ 369 370 void 371 dk4bif_frame_close( 372 dk4_bif_frame_t *frptr, 373 int imgtype 374 ); 375 376 377 #ifdef __cplusplus 378 } 379 #endif 380 381 /* vim: set ai sw=4 ts=4 : */ 382 383 #endif 384