Expose and document Image.get_mipmap_count()

[bitsawer]

Adds a new method Image.get_mipmap_details() and exposes an already existing method Image.get_mipmap_count(). Also documents both. This makes it possible to efficiently manipulate raw mipmap data. It was technically possible before, but the calculations required are not trivial to do and very error prone.

[Calinou]

Sounds good to me 🙂

Documentation-wise, these methods are likely worth referencing in the create_from_image() method's description, or whichever method lets you create a new Image with a mipmaps parameter.

[bitsawer]

I added some references to these new methods to Image.generate_mipmaps() method description. That is the method which both Image.create() and Image.create_from_data() point to when talking about their use_mipmaps parameter, so I feel it is a good place to put some extra info. I also added a sentence describing the renormalize-parameter as a bonus, it might be pretty mysterious to many people otherwise.

If anyone wants to tweak the wording let me know, I can write some pretty clumsy documentation sometimes.

[akien-mga]

Implementation looks good to me, and in principle it makes sense to me to expose this information for users.
Documentation looks great.

The partial duplicate #79368 confirms that there's some demand for the mipmap count.

Neither have a proposal, so I'd like @reduz to sign off on the addition, or clarify if there are any reason he would not expose this.

[reduz]

I would like to avoid exposing further API as dictionaries, at least until the structs proposal is approved and implemented.

Alternatively you could have 3 functions:

• get_mipmap_byte_offset
• get_mipmap_byte_size
• get_mipmap_size

[bitsawer]

I agree with the API decision to avoid Dictionaries for now. Considering we will have to live with any exposed API for a long time, I didn't add individual getters like get_mipmap_byte_offset() yet. So this PR will only expose and document Image.get_mipmap_count() for now. Updated the commit message and PR title.

For future reference, adding the a struct API will probably make exposing these details in a more convenient easier in the future. Also, eventually exposing some version of Image.get_mipmap_offset_size_and_dimensions() as static method has also found some support. That way, you could precalculate these image parameters without actually having to create an Image object, which is often useful. Currently, most people use some sort of GDScript code snippet to calculate these, which works quite well for now.

[akien-mga]

Thanks!