1 /*! \file 2 * \brief Animation handling. 3 * \details Functions and structs for reading, writing and modifying OMF:2097 animation structures. 4 * \copyright MIT license. 5 * \date 2013-2014 6 * \author Andrew Thompson 7 * \author Tuomas Virtanen 8 */ 9 10 #ifndef _SD_ANIMATION_H 11 #define _SD_ANIMATION_H 12 13 #include <stdint.h> 14 #include "shadowdive/sprite.h" 15 #include "shadowdive/colcoord.h" 16 #ifdef SD_USE_INTERNAL 17 #include "shadowdive/internal/reader.h" 18 #include "shadowdive/internal/writer.h" 19 #endif 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 #define SD_ANIMATION_STRING_MAX 1024 ///< Maximum animation string size 26 #define SD_EXTRA_STRING_MAX 512 ///< Maximum extra string size 27 28 #define SD_SPRITE_COUNT_MAX 255 ///< Maximum amount of sprites allowed (technical limitation) 29 #define SD_COLCOORD_COUNT_MAX 256 ///< Maximum amount of collision coordinates allowed \todo find out the real maximum 30 #define SD_EXTRASTR_COUNT_MAX 10 ///< Maximum amount of extra strings. 31 32 /*! \brief Generic animation container 33 * 34 * When starting animation playback, it should be positioned to the location pointed to by the 35 * start_x, start_y variables. Note that sprites may also have their own position offsets. 36 * 37 * Animation always has some amount of sprites and an animation string. 38 * The string is used as a scripting language to tell the animation on how to go about it's business. 39 * Animation string may change the animation position, playback speed, etc. etc. 40 * 41 * If the animation can collide with other objects, it may have an amount of collision coordinates. 42 * A single sprite may have multiple collision coordinates assigned to it. 43 */ 44 typedef struct { 45 // Header 46 int16_t start_x; ///< Animation start position, X-axis 47 int16_t start_y; ///< Animation start position, Y-axis 48 int32_t null; ///< Probably filler data 49 uint16_t coord_count; ///< Number of collision coordinates in animation frames 50 uint8_t sprite_count; ///< Number of sprites in animation 51 uint8_t extra_string_count; ///< Number of extra strings in animation 52 53 // Sprites and their collision coordinates 54 sd_coord coord_table[SD_COLCOORD_COUNT_MAX]; ///< Collision coordinates 55 sd_sprite *sprites[SD_SPRITE_COUNT_MAX]; ///< Sprites 56 57 // String header & Extra strings 58 char anim_string[SD_ANIMATION_STRING_MAX]; ///< Animation string 59 char extra_strings[SD_EXTRASTR_COUNT_MAX][SD_EXTRA_STRING_MAX]; ///< Extra strings 60 } sd_animation; 61 62 /*! \brief Initialize animation structure 63 * 64 * Initializes the animation structure with empty values. 65 * 66 * \retval SD_INVALID_INPUT Animation struct pointer was NULL 67 * \retval SD_SUCCESS Success. 68 * 69 * \param animation Allocated animation struct pointer. 70 */ 71 int sd_animation_create(sd_animation* animation); 72 73 /*! \brief Copy animation structure 74 * 75 * Copies the contents of an animation structure. _ALL_ internals will be copied. 76 * The copied structure must be freed using sd_animation_free(). 77 * 78 * Destination buffer does not need to be cleared. Source buffer must be a valid 79 * animation structure, or problems are likely to appear. 80 * 81 * \retval SD_OUT_OF_MEMORY Memory ran out. Destination struct should now be considered invalid and freed. 82 * \retval SD_INVALID_INPUT Either input value was NULL. 83 * \retval SD_SUCCESS Success. 84 * 85 * \param dst Destination animation struct pointer. 86 * \param src Source animation struct pointer. 87 */ 88 int sd_animation_copy(sd_animation *dst, const sd_animation *src); 89 90 /*! \brief Free animation structure 91 * 92 * Frees up all memory reserved by the animation structure. 93 * All contents will be freed, all pointers to contents will be invalid. 94 * 95 * \param animation Animation struct to modify. 96 */ 97 void sd_animation_free(sd_animation *animation); 98 99 /*! \brief Get coordinate count 100 * 101 * Returns the collision coordinate count in the animation. 102 * 103 * \param animation Animation struct to modify. 104 * \return Coordinate element count 105 */ 106 int sd_animation_get_coord_count(sd_animation *animation); 107 108 /*! \brief Sets coordinate at index 109 * 110 * Sets the coordinate at given index. It is only possible to overwrite values that 111 * are already in the animation. Adding new values should be done by using sd_animation_push_coord(). 112 * 113 * \retval SD_INVALID_INPUT Invalid coordinate index 114 * \retval SD_SUCCESS Success. 115 * 116 * \param animation Animation struct to modify 117 * \param num Coordinate index 118 * \param coord Coordinate information. 119 */ 120 int sd_animation_set_coord(sd_animation *animation, int num, const sd_coord coord); 121 122 /*! \brief Pushes coordinate to the end of coordinate list. 123 * 124 * Pushes a coordinate to the end of the coordinate list. 125 * Coord_count variable will be raised by 1. 126 * 127 * \retval SD_INVALID_INPUT Coordinate list is already full 128 * \retval SD_SUCCESS Success. 129 * 130 * \param animation Animation struct to modify 131 * \param coord Coordinate information. 132 */ 133 int sd_animation_push_coord(sd_animation *animation, const sd_coord coord); 134 135 /*! \brief Pops a coordinate from the end of the coordinate list. 136 * 137 * Pops a coordinate off the end of the coordinate list. 138 * Coord_count variable will be decreased by 1. 139 * 140 * \retval SD_INVALID_INPUT Coordinate list is already empty 141 * \retval SD_SUCCESS Success. 142 * 143 * \param animation Animation struct to modify 144 */ 145 int sd_animation_pop_coord(sd_animation *animation); 146 147 /*! \brief Gets a coordinate pointer at index 148 * 149 * Returns a pointer to the coordinate data at given index. 150 * 151 * \retval NULL There is no coordinate at the given index 152 * \retval sd_coord* Success 153 * 154 * \param animation Animation struct to modify 155 * \param num Coordinate index 156 */ 157 sd_coord* sd_animation_get_coord(sd_animation *animation, int num); 158 159 /*! \brief Sets the animation string 160 * 161 * Sets the animation string for the given animation. String will be copied. 162 * Maximum string length is 1024 bytes. 163 * 164 * \retval SD_INVALID_INPUT Given string was too big. 165 * \retval SD_SUCCESS Success. 166 * 167 * \param animation Animation struct to modify 168 * \param str New animation string 169 */ 170 int sd_animation_set_anim_string(sd_animation *animation, const char *str); 171 172 /*! \brief Get extra string count 173 * 174 * Returns the extra string count in the animation. 175 * 176 * \param animation Animation struct to modify. 177 * \return Extra string count 178 */ 179 int sd_animation_get_extra_string_count(sd_animation *animation); 180 181 /*! \brief Sets extra string at index 182 * 183 * Sets the extra string at given index. It is only possible to overwrite values that 184 * are already in the animation. Adding new values should be done by using 185 * sd_animation_push_extra_string(). 186 * 187 * Maximum extra string length is 512 bytes. 188 * 189 * \retval SD_INVALID_INPUT Invalid extra string index or string too long. 190 * \retval SD_SUCCESS Success. 191 * 192 * \param animation Animation struct to modify 193 * \param num String index 194 * \param str Extra string. This will be copied. 195 */ 196 int sd_animation_set_extra_string(sd_animation *animation, int num, const char *str); 197 198 /*! \brief Pushes extra string to the end of string list. 199 * 200 * Pushes am extra string to the end of the extra string list. 201 * Extra_string_count variable will be increased by 1. 202 * 203 * \retval SD_INVALID_INPUT Extra string list is full or string too long. 204 * \retval SD_SUCCESS Success. 205 * 206 * \param animation Animation struct to modify 207 * \param str Extra string. This will be copied. 208 */ 209 int sd_animation_push_extra_string(sd_animation *animation, const char *str); 210 211 /*! \brief Pops an extra string off from the end of the extra string list. 212 * 213 * Pops a extra string off the end of the extra string list. 214 * Extra_string_count variable will be decreased by 1. 215 * 216 * \retval SD_INVALID_INPUT Extra string list is already empty. 217 * \retval SD_SUCCESS Success. 218 * 219 * \param animation Animation struct to modify 220 */ 221 int sd_animation_pop_extra_string(sd_animation *animation); 222 223 /*! \brief Get extra string at given index 224 * 225 * Returns the extra string at given index. 226 * 227 * \retval NULL There is no extra string at given index. 228 * \retval char* Pointer to the extra string at given index. 229 * 230 * \param animation Animation struct to modify. 231 * \param num Extra string index 232 */ 233 char* sd_animation_get_extra_string(sd_animation *animation, int num); 234 235 /*! \brief Get extra string count 236 * 237 * Returns the extra string count in the animation. 238 * 239 * \param animation Animation struct to modify. 240 * \return Extra string count 241 */ 242 int sd_animation_get_sprite_count(sd_animation *animation); 243 244 /*! \brief Sets sprite at index 245 * 246 * Sets the sprite at given index. It is only possible to overwrite values that 247 * are already in the animation. Adding new values should be done by using 248 * sd_animation_push_sprite(). 249 * 250 * Any old data at given index will be automatically freed. 251 * 252 * \retval SD_INVALID_INPUT Invalid sprite index or sprite was NULL. 253 * \retval SD_OUT_OF_MEMORY Memory ran out. Data at the given index will be NULL. 254 * \retval SD_SUCCESS Success. 255 * 256 * \param animation Animation struct to modify 257 * \param num Sprite index 258 * \param sprite Sprite data. This will be copied. 259 */ 260 int sd_animation_set_sprite(sd_animation *animation, int num, const sd_sprite *sprite); 261 262 /*! \brief Pushes a sprite to the end of the sprite list. 263 * 264 * Pushes a sprite to the end of the sprite list. 265 * Sprite_count variable will be increased by 1. 266 * 267 * \retval SD_INVALID_INPUT Coordinate list is already full 268 * \retval SD_OUT_OF_MEMORY Memory ran out. Animation will not be affected. 269 * \retval SD_SUCCESS Success. 270 * 271 * \param animation Animation struct to modify 272 * \param sprite Sprite information. This will be copied. 273 */ 274 int sd_animation_push_sprite(sd_animation *animation, const sd_sprite *sprite); 275 276 /*! \brief Pops a sprite off from the end of the sprite list. 277 * 278 * Pops a sprite off the end of the sprite list. 279 * Sprite_count variable will be decreased by 1. 280 * Popped data will be automatically freed. 281 * 282 * \retval SD_INVALID_INPUT Sprite list is already empty 283 * \retval SD_SUCCESS Success. 284 * 285 * \param animation Animation struct to modify 286 */ 287 int sd_animation_pop_sprite(sd_animation *animation); 288 289 /*! \brief Get sprite at given index 290 * 291 * Returns a pointer to the sprite data at given index. 292 * 293 * \retval NULL There was no sprite at given index 294 * \retval sd_sprite* Success. 295 * 296 * \param animation Animation struct to modify. 297 * \param num Sprite index 298 */ 299 sd_sprite* sd_animation_get_sprite(sd_animation *animation, int num); 300 301 #ifdef SD_USE_INTERNAL 302 int sd_animation_load(sd_reader *reader, sd_animation *animation); 303 int sd_animation_save(sd_writer *writer, const sd_animation *animation); 304 #endif 305 306 #ifdef __cplusplus 307 } 308 #endif 309 310 #endif // _SD_ANIMATION_H 311