IMG_CODER_STATUS Feature For En/De-coders

include/SDL3_image/SDL_image.h

@@ -2403,6 +2403,18 @@ extern SDL_DECLSPEC IMG_Animation * SDLCALL IMG_LoadGIFAnimation_IO(SDL_IOStream
  */
 extern SDL_DECLSPEC IMG_Animation * SDLCALL IMG_LoadWEBPAnimation_IO(SDL_IOStream *src);
 
+/**
+* An enum representing the status of the encoder and decoder.
+*/
+typedef enum IMG_CoderStatus
+{
+	IMG_CODER_STATUS_OK, 	    /**< En/De-coded the frame successfully. */
+	IMG_CODER_STATUS_FAILED,    /**< En/De-coding the frame failed. Call SDL_GetError for more information. */
+	IMG_CODER_STATUS_MAX, 	    /**< En/De-coding reached maximum frames. For Decoding, this means no more frames available. */
+
+    IMG_CODER_STATUS_INVALID,   /**< Invalid coder status that does not represent a decoder or encoder status. */
+} IMG_CoderStatus;
+
 /**
  * An object representing the encoder context.
  */
@@ -2519,7 +2531,21 @@ extern SDL_DECLSPEC IMG_AnimationEncoder * SDLCALL IMG_CreateAnimationEncoderWit
  * \sa IMG_CreateAnimationEncoderWithProperties
  * \sa IMG_CloseAnimationEncoder
  */
-extern SDL_DECLSPEC bool SDLCALL IMG_AddAnimationEncoderFrame(IMG_AnimationEncoder *encoder, SDL_Surface *surface, Uint64 duration);
+extern SDL_DECLSPEC bool SDLCALL IMG_AddAnimationEncoderFrame(IMG_AnimationEncoder *encoder, SDL_Surface *surface, Uint64 delay);
+
+
+/**
+* Get the encoder status indicating the current state of the encoder.
+*
+* \param encoder the encoder to get the status of.
+* \returns the status of the underlying encoder, or IMG_CODER_STATUS_INVALID if the given
+*          encoder is invalid.
+*
+* \since This function is available since SDL_image 3.4.0.
+*
+* \sa IMG_AddAnimationEncoderFrame
+*/
+extern SDL_DECLSPEC IMG_CoderStatus SDLCALL IMG_GetAnimationEncoderStatus(IMG_AnimationEncoder *encoder);
 
 /**
  * Close an animation encoder, finishing any encoding.
@@ -2688,6 +2714,19 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL IMG_GetAnimationDecoderProperties(I
  */
 extern SDL_DECLSPEC bool SDLCALL IMG_GetAnimationDecoderFrame(IMG_AnimationDecoder *decoder, SDL_Surface **frame, Uint64 *duration);
 
+/**
+* Get the decoder status indicating the current state of the decoder.
+*
+* \param decoder the decoder to get the status of.
+* \returns the status of the underlying decoder, or IMG_CODER_STATUS_INVALID if the given
+*          decoder is invalid.
+*
+* \since This function is available since SDL_image 3.4.0.
+*
+* \sa IMG_GetAnimationDecoderFrame
+*/
+extern SDL_DECLSPEC IMG_CoderStatus SDLCALL IMG_GetAnimationDecoderStatus(IMG_AnimationDecoder *decoder);
+
 /**
  * Reset an animation decoder.
  *

src/IMG_anim_decoder.c

@@ -193,14 +193,21 @@ bool IMG_GetAnimationDecoderFrame(IMG_AnimationDecoder *decoder, SDL_Surface **f
     if (!duration) {
         duration = &temp_duration;
     }
-
+    
     SDL_ClearError();
+    // Reset the status before trying to get the next frame.
+    decoder->status = IMG_CODER_STATUS_OK;
 
     bool result = decoder->GetNextFrame(decoder, frame, duration);
     if (temp_frame) {
         SDL_DestroySurface(temp_frame);
     }
 
+    // If the underlying decoder only uses the SDL_SetError function, we can update our status accordingly as well.
+    if (decoder->status == IMG_CODER_STATUS_OK && SDL_GetError()[0] != '\0') {
+        decoder->status = IMG_CODER_STATUS_FAILED;
+    }
+
     if (result) {
         decoder->accumulated_pts += *duration;
     } else {
@@ -242,12 +249,22 @@ bool IMG_ResetAnimationDecoder(IMG_AnimationDecoder *decoder)
 
 Uint64 IMG_CalculateDuration(IMG_AnimationDecoder* decoder, int delay_num, int delay_den)
 {
-    if (delay_den < 1)
+    if (delay_den < 1) {
         delay_den = 100;
+    }
 
     return (Uint64)SDL_round(((double)delay_num / delay_den) * ((double)decoder->timebase_denominator / (double)decoder->timebase_numerator));
 }
 
+IMG_CoderStatus IMG_GetAnimationDecoderStatus(IMG_AnimationDecoder* decoder)
+{
+    if (!decoder) {
+        return IMG_CODER_STATUS_INVALID;
+    }
+
+    return decoder->status;
+}
+
 IMG_Animation *IMG_DecodeAsAnimation(SDL_IOStream *src, const char *format, int maxFrames)
 {
     IMG_AnimationDecoder *decoder = IMG_CreateAnimationDecoder_IO(src, false, format);

src/IMG_anim_decoder.h

@@ -23,6 +23,8 @@ typedef struct IMG_AnimationDecoderContext IMG_AnimationDecoderContext;
 
 struct IMG_AnimationDecoder
 {
+    IMG_CoderStatus status;
+
     SDL_PropertiesID props;
     SDL_IOStream *src;
     Sint64 start;

src/IMG_anim_encoder.c

@@ -172,8 +172,16 @@ bool IMG_AddAnimationEncoderFrame(IMG_AnimationEncoder *encoder, SDL_Surface *su
         return SDL_InvalidParamError("surface");
     }
 
+    // Reset the status before trying to add a frame.
+    encoder->status = IMG_CODER_STATUS_OK;
+
     bool result = encoder->AddFrame(encoder, surface, duration);
 
+    // If the underlying encoder only uses the SDL_SetError function, we can update our status accordingly as well.
+    if (encoder->status == IMG_CODER_STATUS_OK && SDL_GetError()[0] != '\0') {
+        encoder->status = IMG_CODER_STATUS_FAILED;
+    }
+
     encoder->accumulated_pts += duration;
     encoder->last_delay = duration;
 
@@ -203,3 +211,12 @@ Uint64 IMG_GetCurrentTimestamp(IMG_AnimationEncoder* encoder, Uint64 duration, i
 {
     return (Uint64)SDL_round(((double)encoder->accumulated_pts + (double)duration) * factor * encoder->timebase_numerator / encoder->timebase_denominator);
 }
+
+IMG_CoderStatus IMG_GetAnimationEncoderStatus(IMG_AnimationEncoder* encoder)
+{
+    if (!encoder) {
+        return IMG_CODER_STATUS_INVALID;
+    }
+
+    return encoder->status;
+}

src/IMG_anim_encoder.h

@@ -23,6 +23,8 @@ typedef struct IMG_AnimationEncoderContext IMG_AnimationEncoderContext;
 
 struct IMG_AnimationEncoder
 {
+    IMG_CoderStatus status;
+
     SDL_IOStream *dst;
     Sint64 start;
     bool closeio;

src/IMG_avif.c

@@ -890,13 +890,15 @@ static bool IMG_AnimationDecoderGetNextFrame_Internal(IMG_AnimationDecoder *deco
     avifResult result;
 
     if (ctx->total_frames - ctx->current_frame < 1) {
+        decoder->status = IMG_CODER_STATUS_MAX;
         return false;
     }
 
     result = lib.avifDecoderNextImage(ctx->decoder);
     if (result != AVIF_RESULT_OK) {
         if (result == AVIF_RESULT_NO_IMAGES_REMAINING) {
             // This shouldn't happen here, but handle it gracefully
+            decoder->status = IMG_CODER_STATUS_MAX;
             return false;
         }
 

src/IMG_gif.c

@@ -757,6 +757,7 @@ static bool IMG_AnimationDecoderGetNextFrame_Internal(IMG_AnimationDecoder *deco
     int framesLoaded = 0;
 
     if (ctx->got_eof) {
+        decoder->status = IMG_CODER_STATUS_MAX;
         return false;
     }
 

src/IMG_libpng.c

@@ -1147,6 +1147,7 @@ static bool IMG_AnimationDecoderGetNextFrame_Internal(IMG_AnimationDecoder *deco
     }
 
     if (ctx->actl.num_frames - ctx->current_frame_index < 1) {
+        decoder->status = IMG_CODER_STATUS_MAX;
         return false;
     }
 

src/IMG_webp.c

@@ -441,15 +441,18 @@ static bool IMG_AnimationDecoderGetNextFrame_Internal(IMG_AnimationDecoder *deco
         }
     } else {
         if (!lib.WebPDemuxNextFrame(&decoder->ctx->iter)) {
+            decoder->status = IMG_CODER_STATUS_MAX;
             return false;
         }
     }
 
     int totalFrames = decoder->ctx->iter.num_frames;
     int availableFrames = totalFrames - (decoder->ctx->iter.frame_num - 1);
 
-    if (availableFrames < 1)
+    if (availableFrames < 1) {
+        decoder->status = IMG_CODER_STATUS_MAX;
         return false;
+    }
 
     SDL_Surface *canvas = decoder->ctx->canvas;
     uint32_t bgcolor = decoder->ctx->bgcolor;