1 /*! \file 2 * \brief Scene file handling. 3 * \details Functions and structs for reading, writing and modifying OMF:2097 scene (BK) files. 4 * \copyright MIT license. 5 * \date 2013-2014 6 * \author Andrew Thompson 7 * \author Tuomas Virtanen 8 */ 9 10 #ifndef _SD_BK_H 11 #define _SD_BK_H 12 13 #include <stdint.h> 14 #include "shadowdive/palette.h" 15 #include "shadowdive/bkanim.h" 16 #include "shadowdive/vga_image.h" 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 #define MAX_BK_ANIMS 50 ///< Amount of animations in the BK file. This is fixed! 23 #define MAX_BK_PALETTES 8 ///< Maximum amount of palettes allowed in BK file. 24 25 /*! \brief BK file information 26 * 27 * Contains information about an OMF:2097 scene. Eg. arenas, menus, intro, etc. 28 */ 29 typedef struct { 30 uint32_t file_id; ///< File ID 31 uint8_t unknown_a; ///< Unknown value 32 uint8_t palette_count; ///< Number of palettes in the BK file 33 34 sd_bk_anim *anims[MAX_BK_ANIMS]; ///< All animations contained by the BK file 35 sd_vga_image *background; ///< Background image. If NULL, a black background will be used. 36 sd_palette *palettes[MAX_BK_PALETTES]; ///< All palettes in the BK file. 37 38 char soundtable[30]; ///< All sounds used by the animations in this BK file. 39 } sd_bk_file; 40 41 /*! \brief Initialize BK file structure 42 * 43 * Initializes the BK file structure with empty values. 44 * 45 * \retval SD_INVALID_INPUT BK struct pointer was NULL 46 * \retval SD_SUCCESS Success. 47 * 48 * \param bk Allocated BK struct pointer. 49 */ 50 int sd_bk_create(sd_bk_file *bk); 51 52 /*! \brief Copy BK structure 53 * 54 * Copies the contents of an BK file structure. _ALL_ internals will be copied. 55 * The copied structure must be freed using sd_bk_free(). 56 * 57 * Destination buffer does not need to be cleared. Source buffer must be a valid 58 * BK file structure, or problems are likely to appear. 59 * 60 * \retval SD_OUT_OF_MEMORY Memory ran out. The destination struct should be considered invalid and freed. 61 * \retval SD_INVALID_INPUT Either of the input pointers was NULL. 62 * \retval SD_SUCCESS Success. 63 * 64 * \param dst Destination BK struct pointer. 65 * \param src Source BK struct pointer. 66 */ 67 int sd_bk_copy(sd_bk_file *dst, const sd_bk_file *src); 68 69 /*! \brief Set background image 70 * 71 * Sets the background image of the BK file. If this is not used to a 72 * new file, a black background will be used. 73 * 74 * Image data will be copied. Make sure to free your local copy yourself. 75 * 76 * A NULL value for image data means that background will be removed. 77 * 78 * \retval SD_OUT_OF_MEMORY Memory ran out. Background was not set. 79 * \retval SD_INVALID_INPUT BK struct was NULL. 80 * \retval SD_SUCCESS Success. 81 * 82 * \param bk BK struct pointer. 83 * \param img VGA image data struct. 84 */ 85 int sd_bk_set_background(sd_bk_file *bk, const sd_vga_image *img); 86 87 /*! \brief Get background image 88 * 89 * Returns a pointer to the background image data. 90 * 91 * \retval NULL Background does not exist 92 * \retval sd_vga_image* Background image. 93 * 94 * \param bk BK struct pointer. 95 */ 96 sd_vga_image* sd_bk_get_background(const sd_bk_file *bk); 97 98 /*! \brief Set bk animation 99 * 100 * Sets a BK animation in BK file structure. Index must be between 0 and 49 (inclusive); 101 * All other index values will result in error. 102 * 103 * BK animation data will be copied. Make sure to free your local copy yourself. 104 * Old data at index will be freed automatically. 105 * 106 * Animation input value of NULL will mean that data at index will be freed! 107 * 108 * \retval SD_OUT_OF_MEMORY Memory ran out. This struct should now be considered invalid and freed. 109 * \retval SD_INVALID_INPUT index value was invalid or bk struct was NULL. 110 * \retval SD_SUCCESS Success. 111 * 112 * \param bk BK struct pointer. 113 * \param index Animation index. Must be 0 <= index <= 49 114 * \param anim Animation pointer. NULL here means that index will be cleared. 115 */ 116 int sd_bk_set_anim(sd_bk_file *bk, int index, const sd_bk_anim *anim); 117 118 /*! \brief Get BK animation 119 * 120 * Returns a pointer to a bk animation data at given index. Index must be between 121 * 0 and 49 (inclusive); any other value will return NULL. 122 * 123 * \retval NULL No BK animation at index, or index is otherwise invalid. 124 * \retval sd_bk_anim* Success. 125 * 126 * \param bk BK struct pointer. 127 * \param index Animation index. Must be 0 <= index <= 49 128 */ 129 sd_bk_anim* sd_bk_get_anim(const sd_bk_file *bk, int index); 130 131 /*! \brief Set palette 132 * 133 * Sets a palette to index in BK file structure. You can only replace already set 134 * palettes by using this function, so index must be between 0 and palette_count. 135 * For adding new palettes, please see sd_bk_push_palette(). 136 * 137 * Palette data will be copied. Make sure to free your local copy yourself. 138 * Old data in index will be freed automatically. 139 * 140 * \retval SD_OUT_OF_MEMORY Memory ran out. Palette data was not copied. 141 * \retval SD_INVALID_INPUT Index was invalid or some input pointer was NULL. 142 * \retval SD_SUCCESS Success. 143 * 144 * \param bk BK struct pointer. 145 * \param index Palette index. 146 * \param palette A Valid sd_palette object pointer. 147 */ 148 int sd_bk_set_palette(sd_bk_file *bk, int index, const sd_palette *palette); 149 150 /*! \brief Push palette 151 * 152 * Pushes a palette to the end of the palette list. If list is full, 153 * error value SD_INVALID_INPUT will be returned. 154 * 155 * Palette data will be copied. Make sure to free your local copy yourself. 156 * 157 * \retval SD_OUT_OF_MEMORY Memory ran out. Palette data was not copied. 158 * \retval SD_INVALID_INPUT Palette list is already full. 159 * \retval SD_SUCCESS Success. 160 * 161 * \param bk BK struct pointer. 162 * \param palette A Valid sd_palette object pointer. 163 */ 164 int sd_bk_push_palette(sd_bk_file *bk, const sd_palette *palette); 165 166 /*! \brief Pop palette 167 * 168 * Pops a palette from the end of the palette list. If palette list is already empty, 169 * error will be returned and nothing will happen. 170 * 171 * Popped palette data will be freed automatically. 172 * 173 * \retval SD_INVALID_INPUT There was nothing to pop. 174 * \retval SD_SUCCESS Success. 175 * 176 * \param bk BK struct pointer. 177 */ 178 int sd_bk_pop_palette(sd_bk_file *bk); 179 180 /*! \brief Get palette 181 * 182 * Returns a pointer to a palette at index from BK file structure. Index must contain 183 * a valid palette. If it doesn't, NULL will be returned. Only values between 0 and 7 (inclusive) 184 * are valid palette indices. 185 * 186 * \retval NULL Index is wrong or no palette exists at index. 187 * \retval sd_palette* Success. 188 * 189 * \param bk BK struct pointer. 190 * \param index Palette index. Must be 0 <= index <= 7 191 */ 192 sd_palette* sd_bk_get_palette(const sd_bk_file *bk, int index); 193 194 /*! \brief Load .BK file 195 * 196 * Loads the given BK file to memory. The structure must be initialized with sd_bk_create() 197 * before using this function. Loading to a previously loaded or filled sd_bk_file structure 198 * will result in old data and pointers getting lost. This is very likely to cause a memory leak. 199 * 200 * \retval SD_FILE_OPEN_ERROR File could not be opened. 201 * \retval SD_FILE_PARSE_ERROR File does not contain valid data or has syntax problems. 202 * \retval SD_OUT_OF_MEMORY Memory ran out. This struct should now be considered invalid and freed. 203 * \retval SD_SUCCESS Success. 204 * 205 * \param bk BK struct pointer. 206 * \param filename Name of the BK file to load from. 207 */ 208 int sd_bk_load(sd_bk_file *bk, const char *filename); 209 210 /*! \brief Save .BK file 211 * 212 * Saves the given BK file from memory to a file on disk. The structure must be at 213 * least initialized by using sd_bk_create() before running this. 214 * 215 * \retval SD_FILE_OPEN_ERROR File could not be opened for writing. 216 * \retval SD_SUCCESS Success. 217 * 218 * \param bk BK struct pointer. 219 * \param filename Name of the BK file to save into. 220 */ 221 int sd_bk_save(const sd_bk_file *bk, const char* filename); 222 223 /*! \brief Free BK file structure 224 * 225 * Frees up all memory reserved by the BK structure. 226 * All contents will be freed, all pointers to contents will be invalid. 227 * 228 * \param bk BK file struct pointer. 229 */ 230 void sd_bk_free(sd_bk_file *bk); 231 232 #ifdef __cplusplus 233 } 234 #endif 235 236 #endif // _SD_BK_H 237