v1.0.0

[wantehchang]

No description provided.

[wantehchang]

@joedrago @y-guyon Please review.

@jzern @maryla-uc @vigneshvg @vrabaud @tongyuantongyu FYI.

[wantehchang]

I wrote this pull request by following the instructions at https://github.com/AOMediaCodec/libavif/wiki/Release-Checklist.

I reviewed the commits in the range v0.11.1...HEAD. I may have missed a small number that should be mentioned in the changelog.

We probably should also call out 1.0.0 implies the API will be more stable from now on.

[tongyuantongyu]

We probably should also call out 1.0.0 implies the API will be more stable from now on.

Do we also want to provide a stable 1.0.0 ABI? (I believe for C, library users expect it) If so, we should also reserve some padding to the structs annotated with "Version 1.0.0 ends here" now, so that adding fields later won't break the ABI.

[wantehchang]

Yes, we also want to provide a stable 1.0.0 ABI. The three structs annotated with "Version 1.0.0 ends here" must be allocated by calling their Create() function, so we will be able to extend those three structs without breaking the ABI. I will add comments before those three structs.

[tongyuantongyu]

Ah, I forgot that these are not allocated by user. But then avifRGBImage would be in trouble, since this struct is allocated by user.

[wantehchang]

Yuan: That's correct. Vignesh, Yannis, and I reviewed the current members of the avifRGBImage struct and concluded they are adequate. So we didn't add any reserved fields (padding) to avifRGBImage. Since you are also familiar with this struct, could you take a look? Thanks.

[tongyuantongyu]

I take a look at the history of avifRGBImage, and there are some fields that were added due to external move or need: alphaPremultiplied is for premultiplied alpha, isFloat is for half float support, and maxThreads is for threaded conversion.

I feel that if we were at 2020, it's hard to predict that we will end up having these now, so I'd prefer adding a few padding, just in case new need arises in the future.

[wantehchang]

Yuan: Thank you for taking a look. Note that some of the potential new features of RGB-YUV conversion, such as honoring the chroma sample position, can be supported by using the color space information in the avifImage struct. Also, the avifRGBImage struct actually has several bytes of unneeded space:

typedef struct avifRGBImage
{
    uint32_t width;
    uint32_t height;
    uint32_t depth;
    avifRGBFormat format;
    avifChromaUpsampling chromaUpsampling;
    avifChromaDownsampling chromaDownsampling;
    avifBool avoidLibYUV;
    avifBool ignoreAlpha;
    avifBool alphaPremultiplied;
    avifBool isFloat;
    int maxThreads;
    uint8_t * pixels;
    uint32_t rowBytes;
} avifRGBImage;

For example, it uses an int (avifBool) to represent a boolean. So if we require the struct be initialized by avifRGBImageSetDefaults() or memset() before use, then we have the option of repurposing some of the bytes or bits for a new member. I wrote a pull request to document this initialization requirement:
#1520

[tongyuantongyu]

we have the option of repurposing some of the bytes or bits for a new member

This is still somethat a breaking API change. We definitely won't change typedef int avifBool, so we have to change the type of some field from avifBool to a smaller integer type. Say some user faithfully assigning that field with a variable of avifBool type, and the compiler failed to constant folding that variable therefore doesn't know that it can only be 0 or 1, this will cause a C4244 for MSVC or -Wconversion for GCC/Clang. If the user is also doing the same -Werror thing like libavif, then the previously working code is now broken.

[vigneshvg]

lgtm.

i will also create an android release an upload it to maven central once this PR is merged.