blib/lib/SDL3/Image.pm untested

filter: Statementstmt 0.0% 0 / 384 Branchbran 0.0% 0 / 16 Conditioncond 0.0% 0 / 23 MC/DCmcdc 0.0% 0 / 14 Subroutinesub 0.0% 0 / 21 Podpod 0.0% 0 / 8 totaltotal 0.0% 0 / 466 CC 8 SCAR 17.0
CC
8
Cov
0%
_affix_and_export
12.0
_enum_and_export
12.0
_image
12.0
CRAP 5.5
1 package SDL3::Image v0.0.7 {
2 use v5.40;
3 use base 'Exporter';
4 use Affix qw[:all];
5 use Alien::SDL3;
6 use SDL3 qw[:all];
7 use Carp qw[croak confess];
8 use Config qw[%Config];
9  
10 =encoding utf-8
11  
12 =head1 NAME
13  
14 SDL3::Image - Image Loading support for SDL3
15  
16 =head1 SYNOPSIS
17  
18 use v5.40;
19 use SDL3 qw[:all :main];
20 use SDL3::Image qw[:all];
21  
22 my $surface = IMG_Load('sprite.png');
23 die SDL_GetError() unless $surface;
24  
25 # Or decode straight into a texture the renderer can draw
26 my $texture = IMG_LoadTexture( $renderer, 'background.jpg' );
27  
28 =head1 DESCRIPTION
29  
30 C<SDL3::Image> binds a simple library to load images of various formats as SDL surfaces.
31  
32 It can load C<BMP>, C<GIF>, C<JPEG>, C<LBM>, C<PCX>, C<PNG>, C<PNM> (PPM/PGM/PBM), C<QOI>, C<TGA>, C<XCF>, C<XPM>, and
33 simple C<SVG> format images. It can also load C<AVIF>, C<JPEG-XL>, C<TIFF>, and C<WebP> images, depending on how the
34 underlying library was built.
35  
36 Decoded pixels are returned as an C<SDL_Surface> (see L<SDL3>) that you can blit, convert, or turn into a texture with
37 C<SDL_CreateTextureFromSurface( ... )>. When a renderer is already available, C<IMG_LoadTexture( ... )> uploads the
38 pixels straight into an C<SDL_Texture>. Every loader has an C<*_IO> variant that reads from an C<SDL_IOStream>, so
39 images can be decoded from memory, a storage container, or any other stream.
40  
41 Animated images (C<GIF>, C<WebP>, C<AVIF>, C<ANI>, ...) can be decoded frame by frame with an C<IMG_AnimationDecoder>,
42 and embedded metadata is exposed as SDL properties on the loaded surface or animation.
43  
44 There are a few examples in this distribution's C<eg/image> directory.
45  
46 =head2 Features
47  
48 Each feature listed below is a tag you may use.
49  
50 =head3 C<:all> - SDL3_image Functions
51  
52 This binds all functions, defines all types, and imports them into your package.
53  
54 See L<the SDL3_image Wiki|https://wiki.libsdl.org/SDL3_image/FrontPage> for documentation of the functions and formats
55 you will have access to with this import tag.
56  
57 =cut
58  
59 my $alien = Alien::SDL3->new;
60 my $info = $alien->alt('libsdl3_image')->package_info;
61 croak 'SDL3_image is not installed' unless $info;
62 my ($lib) = @{ $info->libfiles };
63 $ENV{PATH} = join( $Config{path_sep}, ( map { @{ $_->bindirs // [] } } $info ), $ENV{PATH} // '' );
64 our ( %EXPORT_TAGS, @EXPORT_OK );
65  
66 sub import ( $pkg, @wants ) {
67 {
68 no strict 'refs';
69 (s[^:][_]r)->() for @wants;
70 }
71 require List::Util;
72 @EXPORT_OK = sort map {@$_} values %EXPORT_TAGS;
73 $EXPORT_TAGS{all} = [@EXPORT_OK];
74 __PACKAGE__->export_to_level( 1, $pkg, @wants );
75 }
76  
77 sub _affix_and_export ( $name, $args, $ret ) {
78 my ( $n, $r ) = ref $name ? @$name : ( $name, $name );
79 confess "Failed to affix $n" unless affix( $lib, $name, $args, $ret );
80 push @{ $EXPORT_TAGS{ [ caller(1) ]->[3] =~ s/^.+?_//r } }, $n;
81 }
82  
83 sub _const_and_export ( $name, $value ) {
84 no strict 'refs';
85 *{$name} = sub () {$value};
86 push @{ $EXPORT_TAGS{ [ caller(1) ]->[3] =~ s/^.+?_//r } }, $name;
87 }
88  
89 sub _func_and_export ( $name, $sub ) {
90 no strict 'refs';
91 *{$name} = $sub;
92 push @{ $EXPORT_TAGS{ [ caller(1) ]->[3] =~ s/^.+?_//r } }, $name;
93 }
94  
95 sub _typedef_and_export ( $name, $type //= () ) {
96 no strict 'refs';
97 if ( defined $type ) {
98 typedef $name, $type;
99 }
100 else {
101 typedef $name;
102 }
103 push @{ $EXPORT_TAGS{ [ caller(1) ]->[3] =~ s/^.+?_//r } }, $name;
104 }
105  
106 sub _enum_and_export ( $name, $values ) {
107 no strict 'refs';
108 if ( defined $values ) {
109 typedef $name, Enum [@$values];
110 push @{ $EXPORT_TAGS{ [ caller(1) ]->[3] =~ s/^.+?_//r } }, $name;
111 for my $enum (@$values) {
112 push @{ $EXPORT_TAGS{ [ caller(1) ]->[3] =~ s/^.+?_//r } }, ref $enum ? $enum->[0] : $enum;
113 }
114 }
115 }
116  
117 sub _image () {
118 state $done++ && return;
119  
120 # Runtime version discovery
121 _affix_and_export IMG_Version => [], Int;
122 _func_and_export IMG_VERSIONNUM => sub ( $major, $minor, $patch ) { ( ($major) * 1000000 + ($minor) * 1000 + ($patch) ) };
123 _func_and_export IMG_VERSIONNUM_MAJOR => sub ($version) { int( ($version) / 1000000 ) };
124 _func_and_export IMG_VERSIONNUM_MINOR => sub ($version) { int( ( ($version) / 1000 ) % 1000 ) };
125 _func_and_export IMG_VERSIONNUM_MICRO => sub ($version) { int( ($version) % 1000 ) };
126 _func_and_export IMG_MAJOR_VERSION => sub () { state $i //= IMG_VERSIONNUM_MAJOR( IMG_Version() ); $i };
127 _func_and_export IMG_MINOR_VERSION => sub () { state $i //= IMG_VERSIONNUM_MINOR( IMG_Version() ); $i };
128 _func_and_export IMG_MICRO_VERSION => sub () { state $i //= IMG_VERSIONNUM_MICRO( IMG_Version() ); $i };
129 _const_and_export IMG_VERSION => IMG_VERSIONNUM( IMG_MAJOR_VERSION(), IMG_MINOR_VERSION(), IMG_MICRO_VERSION() );
130 _func_and_export IMG_VERSION_ATLEAST => sub ( $X, $Y, $Z ) { ( IMG_VERSION() >= IMG_VERSIONNUM( $X, $Y, $Z ) ); };
131  
132 # Core loading
133 _affix_and_export IMG_Load => [String], Pointer [ SDL_Surface() ];
134 _affix_and_export IMG_Load_IO => [ Pointer [ SDL_IOStream() ], Bool ], Pointer [ SDL_Surface() ];
135 _affix_and_export IMG_LoadTyped_IO => [ Pointer [ SDL_IOStream() ], Bool, String ], Pointer [ SDL_Surface() ];
136  
137 # Texture loading
138 _affix_and_export IMG_LoadTexture => [ Pointer [ SDL_Renderer() ], String ], Pointer [ SDL_Texture() ];
139 _affix_and_export IMG_LoadTexture_IO => [ Pointer [ SDL_Renderer() ], Pointer [ SDL_IOStream() ], Bool ], Pointer [ SDL_Texture() ];
140 _affix_and_export
141 IMG_LoadTextureTyped_IO => [ Pointer [ SDL_Renderer() ], Pointer [ SDL_IOStream() ], Bool, String ],
142 Pointer [ SDL_Texture() ];
143 if ( IMG_VERSION_ATLEAST( 3, 4, 0 ) ) {
144  
145 # GPU Texture loading
146 _affix_and_export
147 IMG_LoadGPUTexture => [ Pointer [ SDL_GPUDevice() ], Pointer [ SDL_GPUCopyPass() ], String, Pointer [Int], Pointer [Int] ],
148 Pointer [ SDL_GPUTexture() ];
149 _affix_and_export
150 IMG_LoadGPUTexture_IO =>
151 [ Pointer [ SDL_GPUDevice() ], Pointer [ SDL_GPUCopyPass() ], Pointer [ SDL3::SDL_IOStream() ], Bool, Pointer [Int], Pointer [Int] ],
152 Pointer [ SDL_GPUTexture() ];
153 _affix_and_export
154 IMG_LoadGPUTextureTyped_IO => [
155 Pointer [ SDL_GPUDevice() ],
156 Pointer [ SDL_GPUCopyPass() ],
157 Pointer [ SDL3::SDL_IOStream() ],
158 Bool, String,
159 Pointer [Int],
160 Pointer [Int]
161 ],
162 Pointer [ SDL_GPUTexture() ];
163 _affix_and_export IMG_GetClipboardImage => [], Pointer [ SDL3::SDL_Surface() ];
164 }
165  
166 # Format detection
167 for my $ext (qw[ANI AVIF CUR BMP GIF ICO JPG JXL LBM PCX PNG PNM QOI SVG TIF WEBP XCF XPM XV]) {
168 _affix_and_export "IMG_is$ext", [ Pointer [ SDL3::SDL_IOStream() ] ], Bool;
169  
170 #~ _affix_and_export "IMG_Load${ext}_IO", [ Pointer [ SDL3::SDL_IOStream() ] ], Pointer [ SDL3::SDL_Surface() ] unless $ext eq 'SVG';
171 }
172 _affix_and_export IMG_LoadSVG_IO => [ Pointer [ SDL3::SDL_IOStream() ] ], Pointer [ SDL_Surface() ];
173 _affix_and_export IMG_LoadSizedSVG_IO => [ Pointer [ SDL3::SDL_IOStream() ], Int, Int ], Pointer [ SDL_Surface() ];
174 _affix_and_export IMG_ReadXPMFromArray => [ Pointer [String] ], Pointer [ SDL_Surface() ];
175 _affix_and_export IMG_ReadXPMFromArrayToRGB888 => [ Pointer [String] ], Pointer [ SDL_Surface() ];
176  
177 # Saving
178 _affix_and_export IMG_Save => [ Pointer [ SDL3::SDL_Surface() ], String ], Bool;
179 _affix_and_export IMG_SaveTyped_IO => [ Pointer [ SDL3::SDL_Surface() ], Pointer [ SDL3::SDL_IOStream() ], Bool, String ], Bool;
180 _affix_and_export IMG_SaveAVIF => [ Pointer [ SDL3::SDL_Surface() ], String, Int ], Bool;
181 _affix_and_export IMG_SaveAVIF_IO => [ Pointer [ SDL3::SDL_Surface() ], Pointer [ SDL3::SDL_IOStream() ], Bool, Int ], Bool;
182 _affix_and_export IMG_SaveBMP => [ Pointer [ SDL3::SDL_Surface() ], String ], Bool;
183 _affix_and_export IMG_SaveBMP_IO => [ Pointer [ SDL3::SDL_Surface() ], Pointer [ SDL3::SDL_IOStream() ], Bool ], Bool;
184 _affix_and_export IMG_SaveCUR => [ Pointer [ SDL3::SDL_Surface() ], String ], Bool;
185 _affix_and_export IMG_SaveCUR_IO => [ Pointer [ SDL3::SDL_Surface() ], Pointer [ SDL3::SDL_IOStream() ], Bool ], Bool;
186 _affix_and_export IMG_SaveGIF => [ Pointer [ SDL3::SDL_Surface() ], String ], Bool;
187 _affix_and_export IMG_SaveGIF_IO => [ Pointer [ SDL3::SDL_Surface() ], Pointer [ SDL3::SDL_IOStream() ], Bool ], Bool;
188 _affix_and_export IMG_SaveICO => [ Pointer [ SDL3::SDL_Surface() ], String ], Bool;
189 _affix_and_export IMG_SaveICO_IO => [ Pointer [ SDL3::SDL_Surface() ], Pointer [ SDL3::SDL_IOStream() ], Bool ], Bool;
190 _affix_and_export IMG_SaveJPG => [ Pointer [ SDL3::SDL_Surface() ], String, Int ], Bool;
191 _affix_and_export IMG_SaveJPG_IO => [ Pointer [ SDL3::SDL_Surface() ], Pointer [ SDL3::SDL_IOStream() ], Bool, Int ], Bool;
192 _affix_and_export IMG_SavePNG => [ Pointer [ SDL3::SDL_Surface() ], String ], Bool;
193 _affix_and_export IMG_SavePNG_IO => [ Pointer [ SDL3::SDL_Surface() ], Pointer [ SDL3::SDL_IOStream() ], Bool ], Bool;
194 _affix_and_export IMG_SaveTGA => [ Pointer [ SDL3::SDL_Surface() ], String ], Bool;
195 _affix_and_export IMG_SaveTGA_IO => [ Pointer [ SDL3::SDL_Surface() ], Pointer [ SDL3::SDL_IOStream() ], Bool ], Bool;
196 _affix_and_export IMG_SaveWEBP => [ Pointer [ SDL3::SDL_Surface() ], String, Float ], Bool;
197 _affix_and_export IMG_SaveWEBP_IO => [ Pointer [ SDL3::SDL_Surface() ], Pointer [ SDL3::SDL_IOStream() ], Bool, Float ], Bool;
198  
199 # Animation Support
200 _typedef_and_export IMG_Animation =>
201 Struct [ w => Int, h => Int, count => Int, frames => Pointer [ Pointer [ SDL_Surface() ] ], delays => Pointer [Int] ];
202 _affix_and_export IMG_LoadAnimation => [String], Pointer [ IMG_Animation() ];
203 _affix_and_export IMG_LoadAnimation_IO => [ Pointer [ SDL_IOStream() ], Bool ], Pointer [ IMG_Animation() ];
204 _affix_and_export IMG_LoadAnimationTyped_IO => [ Pointer [ SDL_IOStream() ], Bool, String ], Pointer [ IMG_Animation() ];
205 for my $ext (qw[ANI APNG AVIF GIF WEBP]) {
206 _affix_and_export "IMG_Load${ext}Animation_IO", [ Pointer [ SDL_IOStream() ] ], Pointer [ IMG_Animation() ];
207 if ( $ext eq 'AVIF' || $ext eq 'WEBP' ) {
208 _affix_and_export "IMG_Save${ext}Animation_IO", [ Pointer [ IMG_Animation() ], Pointer [ SDL_IOStream() ], Bool, Int ], Bool;
209 }
210 else {
211 _affix_and_export "IMG_Save${ext}Animation_IO", [ Pointer [ IMG_Animation() ], Pointer [ SDL_IOStream() ], Bool ], Bool;
212 }
213 }
214 _affix_and_export IMG_SaveAnimation => [ Pointer [ IMG_Animation() ], String ], Bool;
215 _affix_and_export IMG_SaveAnimationTyped_IO => [ Pointer [ IMG_Animation() ], Pointer [ SDL_IOStream() ], Bool, String ], Bool;
216 _affix_and_export IMG_CreateAnimatedCursor => [ Pointer [ IMG_Animation() ], Int, Int ], Pointer [ SDL_Cursor() ];
217 _affix_and_export IMG_FreeAnimation => [ Pointer [ IMG_Animation() ] ], Void;
218  
219 # Encoders
220 _typedef_and_export IMG_AnimationEncoder => Void;
221 _affix_and_export IMG_CreateAnimationEncoder => [String], Pointer [ IMG_AnimationEncoder() ];
222 _affix_and_export IMG_CreateAnimationEncoder_IO => [ Pointer [ SDL_IOStream() ], Bool, String ], Pointer [ IMG_AnimationEncoder() ];
223 _affix_and_export IMG_CreateAnimationEncoderWithProperties => [ SDL_PropertiesID() ], Pointer [ IMG_AnimationEncoder() ];
224 _const_and_export IMG_PROP_ANIMATION_ENCODER_CREATE_FILENAME_STRING => 'SDL_image.animation_encoder.create.filename';
225 _const_and_export IMG_PROP_ANIMATION_ENCODER_CREATE_IOSTREAM_POINTER => 'SDL_image.animation_encoder.create.iostream';
226 _const_and_export IMG_PROP_ANIMATION_ENCODER_CREATE_IOSTREAM_AUTOCLOSE_BOOLEAN => 'SDL_image.animation_encoder.create.iostream.autoclose';
227 _const_and_export IMG_PROP_ANIMATION_ENCODER_CREATE_TYPE_STRING => 'SDL_image.animation_encoder.create.type';
228 _const_and_export IMG_PROP_ANIMATION_ENCODER_CREATE_QUALITY_NUMBER => 'SDL_image.animation_encoder.create.quality';
229 _const_and_export IMG_PROP_ANIMATION_ENCODER_CREATE_TIMEBASE_NUMERATOR_NUMBER => 'SDL_image.animation_encoder.create.timebase.numerator';
230 _const_and_export IMG_PROP_ANIMATION_ENCODER_CREATE_TIMEBASE_DENOMINATOR_NUMBER => 'SDL_image.animation_encoder.create.timebase.denominator';
231 _const_and_export IMG_PROP_ANIMATION_ENCODER_CREATE_AVIF_MAX_THREADS_NUMBER => 'SDL_image.animation_encoder.create.avif.max_threads';
232 _const_and_export IMG_PROP_ANIMATION_ENCODER_CREATE_AVIF_KEYFRAME_INTERVAL_NUMBER =>
233 'SDL_image.animation_encoder.create.avif.keyframe_interval';
234 _const_and_export IMG_PROP_ANIMATION_ENCODER_CREATE_GIF_USE_LUT_BOOLEAN => 'SDL_image.animation_encoder.create.gif.use_lut';
235 _affix_and_export IMG_AddAnimationEncoderFrame => [ Pointer [ IMG_AnimationEncoder() ], Pointer [ SDL_Surface() ], UInt64 ], Bool;
236 _affix_and_export IMG_CloseAnimationEncoder => [ Pointer [ IMG_AnimationEncoder() ] ], Bool;
237  
238 # Decoders
239 _enum_and_export IMG_AnimationDecoderStatus =>
240 [ [ IMG_DECODER_STATUS_INVALID => -1 ], qw[IMG_DECODER_STATUS_OK IMG_DECODER_STATUS_FAILED IMG_DECODER_STATUS_COMPLETE] ];
241 _typedef_and_export IMG_AnimationDecoder => Void;
242 _affix_and_export IMG_CreateAnimationDecoder => [String], Pointer [ IMG_AnimationDecoder() ];
243 _affix_and_export IMG_CreateAnimationDecoder_IO => [ Pointer [ SDL_IOStream() ], Bool, String ], Pointer [ IMG_AnimationDecoder() ];
244 _affix_and_export IMG_CreateAnimationDecoderWithProperties => [ SDL_PropertiesID() ], Pointer [ IMG_AnimationDecoder() ];
245 _const_and_export IMG_PROP_ANIMATION_DECODER_CREATE_FILENAME_STRING => 'SDL_image.animation_decoder.create.filename';
246 _const_and_export IMG_PROP_ANIMATION_DECODER_CREATE_IOSTREAM_POINTER => 'SDL_image.animation_decoder.create.iostream';
247 _const_and_export IMG_PROP_ANIMATION_DECODER_CREATE_IOSTREAM_AUTOCLOSE_BOOLEAN => 'SDL_image.animation_decoder.create.iostream.autoclose';
248 _const_and_export IMG_PROP_ANIMATION_DECODER_CREATE_TYPE_STRING => 'SDL_image.animation_decoder.create.type';
249 _const_and_export IMG_PROP_ANIMATION_DECODER_CREATE_TIMEBASE_NUMERATOR_NUMBER => 'SDL_image.animation_decoder.create.timebase.numerator';
250 _const_and_export IMG_PROP_ANIMATION_DECODER_CREATE_TIMEBASE_DENOMINATOR_NUMBER => 'SDL_image.animation_decoder.create.timebase.denominator';
251 _const_and_export IMG_PROP_ANIMATION_DECODER_CREATE_AVIF_MAX_THREADS_NUMBER => 'SDL_image.animation_decoder.create.avif.max_threads';
252 _const_and_export IMG_PROP_ANIMATION_DECODER_CREATE_AVIF_ALLOW_INCREMENTAL_BOOLEAN =>
253 'SDL_image.animation_decoder.create.avif.allow_incremental';
254 _const_and_export IMG_PROP_ANIMATION_DECODER_CREATE_AVIF_ALLOW_PROGRESSIVE_BOOLEAN =>
255 'SDL_image.animation_decoder.create.avif.allow_progressive';
256 _const_and_export IMG_PROP_ANIMATION_DECODER_CREATE_GIF_TRANSPARENT_COLOR_INDEX_NUMBER =>
257 'SDL_image.animation_encoder.create.gif.transparent_color_index';
258 _const_and_export IMG_PROP_ANIMATION_DECODER_CREATE_GIF_NUM_COLORS_NUMBER => 'SDL_image.animation_encoder.create.gif.num_colors';
259 _affix_and_export IMG_GetAnimationDecoderProperties => [ Pointer [ IMG_AnimationDecoder() ] ], SDL_PropertiesID();
260 _const_and_export IMG_PROP_METADATA_IGNORE_PROPS_BOOLEAN => 'SDL_image.metadata.ignore_props';
261 _const_and_export IMG_PROP_METADATA_DESCRIPTION_STRING => 'SDL_image.metadata.description';
262 _const_and_export IMG_PROP_METADATA_COPYRIGHT_STRING => 'SDL_image.metadata.copyright';
263 _const_and_export IMG_PROP_METADATA_TITLE_STRING => 'SDL_image.metadata.title';
264 _const_and_export IMG_PROP_METADATA_AUTHOR_STRING => 'SDL_image.metadata.author';
265 _const_and_export IMG_PROP_METADATA_CREATION_TIME_STRING => 'SDL_image.metadata.creation_time';
266 _const_and_export IMG_PROP_METADATA_FRAME_COUNT_NUMBER => 'SDL_image.metadata.frame_count';
267 _const_and_export IMG_PROP_METADATA_LOOP_COUNT_NUMBER => 'SDL_image.metadata.loop_count';
268 _affix_and_export
269 IMG_GetAnimationDecoderFrame => [ Pointer [ IMG_AnimationDecoder() ], Pointer [ Pointer [ SDL_Surface() ] ], Pointer [UInt64] ],
270 Bool;
271 _affix_and_export IMG_GetAnimationDecoderStatus => [ Pointer [ IMG_AnimationDecoder() ] ], IMG_AnimationDecoderStatus();
272 _affix_and_export IMG_ResetAnimationDecoder => [ Pointer [ IMG_AnimationDecoder() ] ], Bool;
273 _affix_and_export IMG_CloseAnimationDecoder => [ Pointer [ IMG_AnimationDecoder() ] ], Bool;
274 }
275  
276 sub _all () {
277 state $done++ && return;
278 _image();
279 }
280 }
281 1;
282  
283 =head1 See Also
284  
285 The project's repo: L<https://github.com/Perl-SDL3/>
286  
287 The SDL3_image Wiki: L<https://wiki.libsdl.org/SDL3_image/FrontPage>
288  
289 L<SDL3>
290  
291 L<Affix>
292  
293 =head1 LICENSE
294  
295 This software is Copyright (c) 2026 by Sanko Robinson.
296  
297 This is free software, licensed under:
298  
299 The Artistic License 2.0 (GPL Compatible)
300  
301 See the F<LICENSE> file for full text.
302  
303 =head1 AUTHOR
304  
305 Sanko Robinson L<https://github.com/sanko>
306  
307 =begin stopwords
308  
309  
310 =end stopwords
311  
312 =cut