מסמכי תיעוד של WebP Container API

טיפול בקונטיינרים מסוג RIFF לתמונות WebP.

ממשק API של Mux

הרשאה לביצוע מניפולציה של תמונות קונטיינרים של WebP, שכוללות תכונות כמו צבע פרופיל, מטא-נתונים, אנימציה ותמונות מקוטעות.

דוגמאות לקוד

יצירת MUX עם נתוני תמונה, פרופיל צבע ומטא-נתונים של XMP

int copy_data = 0;
WebPMux* mux = WebPMuxNew();
// ... (Prepare image data).
WebPMuxSetImage(mux, &image, copy_data);
// ... (Prepare ICCP color profile data).
WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data);
// ... (Prepare XMP metadata).
WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data);
// Get data from mux in WebP RIFF format.
WebPMuxAssemble(mux, &output_data);
WebPMuxDelete(mux);
// ... (Consume output_data; e.g. write output_data.bytes to file).
WebPDataClear(&output_data);

אחזור של נתוני פרופיל תמונה וצבע מקובץ WebP

int copy_data = 0;
// ... (Read data from file).
WebPMux* mux = WebPMuxCreate(&data, copy_data);
WebPMuxGetFrame(mux, 1, &image);
// ... (Consume image; e.g. call WebPDecode() to decode the data).
WebPMuxGetChunk(mux, "ICCP", &icc_profile);
// ... (Consume icc_data).
WebPMuxDelete(mux);
free(data);

חייו של אובייקט Mux

טיפוסים בני מנייה (enum)

// Error codes
typedef enum WebPMuxError {
  WEBP_MUX_OK                 =  1,
  WEBP_MUX_NOT_FOUND          =  0,
  WEBP_MUX_INVALID_ARGUMENT   = -1,
  WEBP_MUX_BAD_DATA           = -2,
  WEBP_MUX_MEMORY_ERROR       = -3,
  WEBP_MUX_NOT_ENOUGH_DATA    = -4
} WebPMuxError;

// IDs for different types of chunks.
typedef enum WebPChunkId {
  WEBP_CHUNK_VP8X,     // VP8X
  WEBP_CHUNK_ICCP,     // ICCP
  WEBP_CHUNK_ANIM,     // ANIM
  WEBP_CHUNK_ANMF,     // ANMF
  WEBP_CHUNK_ALPHA,    // ALPH
  WEBP_CHUNK_IMAGE,    // VP8/VP8L
  WEBP_CHUNK_EXIF,     // EXIF
  WEBP_CHUNK_XMP,      // XMP
  WEBP_CHUNK_UNKNOWN,  // Other chunks.
  WEBP_CHUNK_NIL
} WebPChunkId;

WebPGetMuxVersion()

מחזירה את מספר הגרסה של ספריית mux, ארוזה בהקסדצימלית באמצעות 8 סיביות לכל גרסה ראשית/משנית/גרסה. לדוגמה: גרסה 2.5.7 היא 0x020507.

int WebPGetMuxVersion(void);

WebPMuxNew()

יצירת אובייקט mux ריק.

WebPMux* WebPMuxNew(void);
החזרות
סמן לאובייקט ה-mux הריק שנוצר.

WebPMuxDelete()

מוחקת את אובייקט ה-mux.

void WebPMuxDelete(WebPMux* mux);
פרמטרים
mux – אובייקט (in/out) המיועד למחיקה

יצירת מוקפים

WebPMuxCreate()

יצירת אובייקט mux מנתונים גולמיים שניתנו בפורמט WebP RIFF.

WebPMux* WebPMuxCreate(const WebPData* bitstream, int copy_data);
פרמטרים

bitstream – (ב) נתוני ה-bitstream בפורמט WebP RIFF

copy_data -- (ב) ערך 1 מציין שהנתונים הנתונים יועתקו לשרידי הקוד והערך 0 מציין שהנתונים לא יועתקו לאובייקט mux.

החזרות

סמן לאובייקט Mux שנוצר מנתונים נתונים – לגבי הצלחה.

NULL – במקרה של שגיאת נתונים או שגיאת זיכרון.

מקטעי נתונים שאינם של תמונות

WebPMuxSetChunk()

הפונקציה מוסיפה מקטע עם המזהה fourcc והנתונים chunk_data באובייקט ה-mux. כלשהו מקטעים קיימים בעלי אותו מזהה יוסרו.

WebPMuxError WebPMuxSetChunk(WebPMux* mux,
                             const char fourcc[4],
                             const WebPData* chunk_data,
                             int copy_data);

הערה: באמצעות ממשקי API של מקטעי נתונים יש לנהל רק מקטעים שאינם קשורים לתמונה. (מקטעים שקשורים לתמונה הם: 'ANMF', 'FRGM', 'VP8', 'VP8L' ו-'ALPH'). כדי להוסיף, קבלה ומחיקה של תמונות, משתמשים ב-WebPMuxSetImage() WebPMuxPushFrame(), WebPMuxGetFrame() ו WebPMuxDeleteFrame().

פרמטרים

mux – אובייקט (in/out) שאליו צריך להוסיף את המקטע

fourcc – (ב) מערך תווים שמכיל את ה-4cc של הערך הנתון chunk; לדוגמה "ICCP", "XMP", "EXIF" וכו'

chunk_data – (ב) נתוני המקטע להוספה

copy_data -- (ב) ערך 1 מציין שהנתונים הנתונים יועתקו לשרידי הקוד והערך 0 מציין שהנתונים לא יועתקו לאובייקט mux.

החזרות

WEBP_MUX_INVALID_ARGUMENT – אם mux, 4cc או chunk_data הוא NULL או אם השדה '4cc' תואם למקטעי תמונה.

WEBP_MUX_MEMORY_ERROR – בשגיאה בהקצאת זיכרון.

WEBP_MUX_OK – להצלחה.

WebPMuxGetChunk()

הפונקציה מקבלת הפניה לנתוני המקטע עם המזהה fourcc באובייקט ה-mux. המתקשר לא צריך לשחרר את הנתונים שהוחזרו.

WebPMuxError WebPMuxGetChunk(const WebPMux* mux,
                             const char fourcc[4],
                             WebPData* chunk_data);
פרמטרים

mux – אובייקט (ב) שממנו יש לאחזר את נתוני המקטעים.

fourcc – (ב) מערך תווים שמכיל את ה-4cc של המקטע; לדוגמה "ICCP", "XMP", "EXIF" וכו'

chunk_data – (out) החזיר נתוני מקטעים

החזרות

WEBP_MUX_INVALID_ARGUMENT – אם mux, 4cc או chunk_data הוא NULL או אם השדה '4cc' תואם למקטעי תמונה.

WEBP_MUX_NOT_FOUND – אם הריגוש לא מכיל מקטע עם הערך שצוין למזהה נתון.

WEBP_MUX_OK – להצלחה.

WebPMuxDeleteChunk()

מוחקת את המקטע עם ה-fourcc הנתון מהאובייקט mux.

WebPMuxError WebPMuxDeleteChunk(WebPMux* mux, const char fourcc[4]);
פרמטרים

mux – אובייקט (in/out) שממנו יש למחוק את המקטע

fourcc – (ב) מערך תווים שמכיל את ה-4cc של המקטע; לדוגמה "ICCP", "XMP ", "EXIF" וכו'

החזרות

WEBP_MUX_INVALID_ARGUMENT – אם mux או 4cc הוא NULL או 4cc תואם למקטע תמונה.

WEBP_MUX_NOT_FOUND – אם הריגוש לא מכיל מקטע עם הערך שצוין 4cc.

WEBP_MUX_OK – להצלחה.

תמונות

כולל נתונים על מסגרת/מקטע בודדים.

struct WebPMuxFrameInfo {
  WebPData    bitstream;  // image data: can be a raw VP8/VP8L bitstream
                          // or a single-image WebP file.
  int         x_offset;   // x-offset of the frame.
  int         y_offset;   // y-offset of the frame.
  int         duration;   // duration of the frame (in milliseconds).

  WebPChunkId id;         // frame type: should be one of WEBP_CHUNK_ANMF,
                          // WEBP_CHUNK_FRGM or WEBP_CHUNK_IMAGE
  WebPMuxAnimDispose dispose_method;  // Disposal method for the frame.
  WebPMuxAnimBlend   blend_method;    // Blend operation for the frame.
};

WebPMuxSetImage()

הגדרת התמונה (ללא אנימציה וללא מקטעים) באובייקט מרובה. הערה: כל התמונות הקיימות (כולל פריימים או מקטעים) יוסרו.

WebPMuxError WebPMuxSetImage(WebPMux* mux,
                             const WebPData* bitstream,
                             int copy_data);
פרמטרים

mux – אובייקט (in/out) שבו יש להגדיר את התמונה

bitstream – (in) יכול להיות קובץ Bitstream גולמי מסוג VP8/VP8L או WebP עם תמונה יחידה קובץ (לא מונפש ולא מקוטע)

copy_data -- (ב) ערך 1 מציין שהנתונים הנתונים יועתקו לשרידי הקוד והערך 0 מציין שהנתונים לא יועתקו לאובייקט mux.

החזרות

WEBP_MUX_INVALID_ARGUMENT – אם ה-Mux הוא NULL או ש-bitstream הוא NULL.

WEBP_MUX_MEMORY_ERROR – בשגיאה בהקצאת זיכרון.

WEBP_MUX_OK – להצלחה.

WebPMuxPushFrame()

הוספת מסגרת בסוף האובייקט מוקצית.

WebPMuxError WebPMuxPushFrame(WebPMux* mux,
                              const WebPMuxFrameInfo* frame,
                              int copy_data);

הערות:

  1. frame.id צריך להיות אחד מהערכים WEBP_CHUNK_ANMF או WEBP_CHUNK_FRGM
  2. כדי להגדיר תמונה לא מונפשת ולא מחולקת, צריך להשתמש WebPMuxSetImage() במקום זאת.
  3. סוג המסגרת שנדחפת חייב להיות זהה למסגרות ברירת המחדל.
  4. מכיוון ש-WebP תומך רק בהיסטים זוגיים, כל היסט אי-זוגי ייחתך למיקום שווה באמצעות: היסט &= ~1
פרמטרים

mux – אובייקט (in/out) שאליו תתווסף המסגרת

frame – נתוני מסגרת (in).

copy_data -- (ב) ערך 1 מציין שהנתונים הנתונים יועתקו לשרידי הקוד והערך 0 מציין שהנתונים לא יועתקו לאובייקט mux.

החזרות

WEBP_MUX_INVALID_ARGUMENT – אם הריגוש או המסגרת הם NULL או אם תוכן הערך של frame לא תקין.

WEBP_MUX_MEMORY_ERROR – בשגיאה בהקצאת זיכרון.

WEBP_MUX_OK – להצלחה.

WEBP_MUX_MEMORY_ERROR – בשגיאה בהקצאת זיכרון.

WebPMuxGetFrame()

הפונקציה מקבלת את המסגרת ה-nth מהאובייקט mux. התוכן של frame->bitstream הוא הוקצה באמצעות Malloc(), ולא נמצא בבעלות האובייקט mux. זה חייב להיות ניתנה על ידי המתקשר/ת באמצעות חיוג אל WebPDataClear(). Nth=0 יש משמעות מיוחדת – מיקום אחרון.

WebPMuxError WebPMuxGetFrame(const WebPMux* mux,
                             uint32_t nth,
                             WebPMuxFrameInfo* frame);
פרמטרים

mux – אובייקט (ב) שממנו המידע יאוחזר

nth – אינדקס (in) של המסגרת באובייקט mux

frame – נתונים (מחוץ) של המסגרת שהוחזרה

החזרות

WEBP_MUX_INVALID_ARGUMENT -- if mux or frame is NULL.

WEBP_MUX_NOT_FOUND – אם יש פחות מ-n פריימים ב-mox לאובייקט.

WEBP_MUX_BAD_DATA – אם מקטע של מסגרת nth ב-Mux לא חוקי.

WEBP_MUX_OK – להצלחה.

WebPMuxDeleteFrame()

מחיקת מסגרת מהאובייקט mux. ל-nth=0 יש משמעות מיוחדת המיקום.

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);
פרמטרים

mux – אובייקט (in/out) שממנו יש למחוק מסגרת

nth -- (ב) המיקום שממנו המסגרת תימחק

החזרות

WEBP_MUX_INVALID_ARGUMENT -- if mux is NULL.

WEBP_MUX_NOT_FOUND – אם יש פחות מ-n פריימים ב-mex לפני המחיקה.

WEBP_MUX_OK – להצלחה.

Animation

פרמטרים של אנימציה

struct WebPMuxAnimParams {
  uint32_t bgcolor;  // Background color of the canvas stored (in MSB order) as:
                     // Bits 00 to 07: Alpha.
                     // Bits 08 to 15: Red.
                     // Bits 16 to 23: Green.
                     // Bits 24 to 31: Blue.
  int loop_count;    // Number of times to repeat the animation [0 = infinite].
};

WebPMuxSetAnimationParams()

מגדירה את הפרמטרים של האנימציה באובייקט mux. כל מקטעי ANIM קיימים יוסרו.

WebPMuxError WebPMuxSetAnimationParams(WebPMux* mux,
                                       const WebPMuxAnimParams* params);
פרמטרים

mux – אובייקט (in/out) שבו יש להגדיר/להוסיף מקטע ANIM

params -- (ב) פרמטרים של אנימציה.

החזרות

WEBP_MUX_INVALID_ARGUMENT – אם המוקס או הפרמטרים הם NULL.

WEBP_MUX_MEMORY_ERROR – בשגיאה בהקצאת זיכרון.

WEBP_MUX_OK – להצלחה.

WebPMuxGetAnimationParams()

הפונקציה מקבלת את הפרמטרים של האנימציה מהאובייקט mux.

WebPMuxError WebPMuxGetAnimationParams(const WebPMux* mux,
                                       WebPMuxAnimParams* params);
פרמטרים

mux – אובייקט (ב) שממנו יש לאחזר את הפרמטרים של האנימציה

params -- פרמטרים של אנימציה (out) שחולצו ממקטע ANIM

החזרות

WEBP_MUX_INVALID_ARGUMENT – אם המוקס או הפרמטרים הם NULL.

WEBP_MUX_NOT_FOUND – אם מקטע ANIM לא קיים באובייקט mux.

WEBP_MUX_OK – להצלחה.

שונות. כלים לתחזוקת המחשב

WebPMuxGetCanvasSize()

הפונקציה מקבלת את גודל הקנבס מהאובייקט mux.

WebPMuxError WebPMuxGetCanvasSize(const WebPMux* mux,
                                  int* width,
                                  int* height);

הערה: השיטה הזו מבוססת על ההנחה שמקטע VP8X, אם קיים, עדכני. כלומר, האובייקט המורכב לא השתנה מאז הקריאה האחרונה WebPMuxAssemble() או WebPMuxCreate().

פרמטרים

mux – (ב) אובייקט שממנו יש לאחזר את גודל הקנבס.

width – רוחב אזור העריכה (חוץ)

height – גובה קנבס (out)

החזרות

WEBP_MUX_INVALID_ARGUMENT -- if mux, width or height is NULL.

WEBP_MUX_BAD_DATA – אם גודל הקנבס או המקטעים VP8X/VP8/VP8L לא תקין.

WEBP_MUX_OK – להצלחה.

WebPMuxGetFeatures()

הפונקציה מקבלת את דגלי הפיצ'רים מהאובייקט mux.

WebPMuxError WebPMuxGetFeatures(const WebPMux* mux, uint32_t* flags);

הערה: השיטה הזו מבוססת על ההנחה שמקטע VP8X, אם קיים, עדכני. כלומר, האובייקט המורכב לא השתנה מאז הקריאה האחרונה WebPMuxAssemble() או WebPMuxCreate().

פרמטרים

mux – אובייקט (in) שממנו התכונות מאוחזרות

flags -- (בחוץ) הדגלים שמציינים אילו תכונות קיימות לאובייקט. הערך יהיה OR של ערכי דגל שונים. טיפוסים בני מנייה (enum) WebPFeatureFlags יכול לשמש לבדיקת ערכי דגלים נפרדים.

החזרות

WEBP_MUX_INVALID_ARGUMENT -- if mux or flags is NULL.

WEBP_MUX_BAD_DATA – אם גודל הקנבס או המקטעים VP8X/VP8/VP8L לא תקין.

WEBP_MUX_OK – להצלחה.

WebPMuxNumChunks()

הפונקציה מקבלת את מספר המקטעים עם ערך התג הנתון באובייקט mux.

WebPMuxError WebPMuxNumChunks(const WebPMux* mux,
                              WebPChunkId id,
                              int* num_elements);
פרמטרים

mux – אובייקט (ב) שממנו המידע יאוחזר

id – מזהה מקטע (in) שמציין את סוג המקטע

num_elements – מספר המקטעים (חסר) עם מזהה המקטע הנתון

החזרות

WEBP_MUX_INVALID_ARGUMENT -- if mux, or num_elements is NULL.

WEBP_MUX_OK – להצלחה.

WebPMuxAssemble()

המערכת משלבת את כל המקטעים בפורמט WebP RIFF ומחזירה את הנתונים ב-assembled_data. הפונקציה הזו גם מאמתת את האובייקט mux.

WebPMuxError WebPMuxAssemble(WebPMux* mux, WebPData* assembled_data);

הערה: המערכת תתעלם מהתוכן של assembled_data והוא יוחלף. כמו כן, התוכן של assembled_data מוקצה באמצעות Malloc(), ולא בבעלות האובייקט mux. המתקשר חייב להקצות אותו בהתקשרות WebPDataClear()

פרמטרים

mux – אובייקט (in/out) שצריך להרכיב את המקטעים שלו

assembled_data – נתוני WebP מורכבים (out)

החזרות

WEBP_MUX_BAD_DATA – אם האובייקט ה-Mlux לא תקין.

WEBP_MUX_INVALID_ARGUMENT -- if mux or assembled_data is NULL.

WEBP_MUX_MEMORY_ERROR – בשגיאה בהקצאת זיכרון.

WEBP_MUX_OK – להצלחה.

ממשק API של WebPAnimEncoder

ה-API הזה מאפשר לקודד (כנראה) תמונות WebP מונפשות.

דוגמה לקוד

WebPAnimEncoderOptions enc_options;
WebPAnimEncoderOptionsInit(&enc_options);
// Tune 'enc_options' as needed.
WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options);
while(<there are more frames>) {
  WebPConfig config;
  WebPConfigInit(&config);
  // Tune 'config' as needed.
  WebPAnimEncoderAdd(enc, frame, timestamp_ms, &config);
}
WebPAnimEncoderAdd(enc, NULL, timestamp_ms, NULL);
WebPAnimEncoderAssemble(enc, webp_data);
WebPAnimEncoderDelete(enc);
// Write the 'webp_data' to a file, or re-mux it further.

typedef struct WebPAnimEncoder WebPAnimEncoder;  // Main opaque object.

אפשרויות גלובליות

struct WebPAnimEncoderOptions {
  WebPMuxAnimParams anim_params;  // Animation parameters.
  int minimize_size;    // If true, minimize the output size (slow). Implicitly
                        // disables key-frame insertion.
  int kmin;
  int kmax;             // Minimum and maximum distance between consecutive key
                        // frames in the output. The library may insert some key
                        // frames as needed to satisfy this criteria.
                        // Note that these conditions should hold: kmax > kmin
                        // and kmin >= kmax / 2 + 1. Also, if kmax <= 0, then
                        // key-frame insertion is disabled; and if kmax == 1,
                        // then all frames will be key-frames (kmin value does
                        // not matter for these special cases).
  int allow_mixed;      // If true, use mixed compression mode; may choose
                        // either lossy and lossless for each frame.
  int verbose;          // If true, print info and warning messages to stderr.
};

WebPAnimEncoderOptionsInit()

צריך לקרוא תמיד, כדי לאתחל WebPAnimEncoderOptions חדש לפני ביצוע השינוי. הפונקציה מחזירה את הערך False במקרה של חוסר התאמה בין הגרסאות. WebPAnimEncoderOptionsInit() חייב להצליח לפני השימוש enc_options.

פרמטרים
enc_options – אפשרויות (in/out) שמשמשות לקידוד אנימציה
החזרות
נכון להצלחה.
int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderNew()

יצירה והפעלה של אובייקט WebPAnimEncoder.

פרמטרים

width/height -- (ב) רוחב וגובה האנימציה.

enc_options -- (ב) אפשרויות קידוד; ניתן להעביר NULL כדי לבחור ערכי ברירת מחדל סבירים.

החזרות

מצביע לאובייקט WebPAnimEncoder שנוצר, או ל-NULL במקרה של שגיאת זיכרון.

WebPAnimEncoder* WebPAnimEncoderNew(
    int width, int height, const WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderAdd()

לבצע אופטימיזציה של המסגרת הנתונה ל-WebP, לקודד אותה ולהוסיף אותה אובייקט WebPAnimEncoder.

הקריאה האחרונה ל-WebPAnimEncoderAdd צריכה להיות עם frame = NULL, מציין שלא צריך להוסיף עוד מסגרות. השיחה הזו משמשת גם קביעת משך הזמן של הפריים האחרון.

פרמטרים

enc – אובייקט (in/out) שאליו תתווסף המסגרת.

frame -- נתוני מסגרת (in/out) בפורמט ARGB או YUV(A). אם הוא נמצא בפורמט YUV(A), הוא יומר ל-ARGB, מה שמוביל להפסד קטן.

timestamp_ms – (in) חותמת זמן של הפריים הזה באלפיות השנייה. משך/אורך של פריים יחושב כ"חותמת זמן של המסגרת הבאה - חותמת זמן של "המסגרת הזו". לכן, חותמות הזמן צריכות להיות בסדר לא יורד.

config -- (ב) אפשרויות קידוד; ניתן להעביר NULL כדי לבחור ברירות המחדל.

החזרות

במקרה של שגיאה, מחזירה FALSE ו-frame->error_code מוגדר כראוי. אחרת, הפונקציה מחזירה את הערך True.

int WebPAnimEncoderAdd(
    WebPAnimEncoder* enc, struct WebPPicture* frame, int timestamp_ms,
    const struct WebPConfig* config);

WebPAnimEncoderAssemble()

להרכיב את כל הפריימים שנוספו עד עכשיו ל-bitstream של WebP. השיחה צריכה להיות לפניה קריאה ל-WebPAnimEncoderAdd עם frame = NULL; אם לא, משך הפריים האחרון יהיה משוער באופן פנימי.

פרמטרים

enc – אובייקט (in/out) שממנו צריך להרכיב את הפריימים.

webp_data – זרם ביט של WebP שנוצר (out)

החזרות

נכון לגבי הצלחה.

int WebPAnimEncoderAssemble(WebPAnimEncoder* enc, WebPData* webp_data);

WebPAnimEncoderGetError()

קבלת מחרוזת שגיאה שתואמת לקריאה האחרונה באמצעות enc. המחרוזת המוחזרת נמצאת בבעלות של enc והיא תקפה רק עד הקריאה הבאה אל WebPAnimEncoderAdd() או WebPAnimEncoderAssemble() או WebPAnimEncoderDelete().

פרמטרים
enc – אובייקט (in/out) שממנו יש לאחזר את מחרוזת השגיאה.
החזרות
NULL if enc is NULL. אחרת, מחזירה את מחרוזת השגיאה אם הייתה שגיאה בקריאה ל-enc, או מחרוזת ריקה אם הקריאה האחרונה הייתה להצלחה.
const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

WebPAnimEncoderDelete()

מוחקת את האובייקט WebPAnimEncoder.

פרמטרים
enc -- (in/out) אובייקט למחיקה
void WebPAnimEncoderDelete(WebPAnimEncoder* enc);

API של Demux

מאפשר חילוץ של נתוני תמונה ונתוני פורמט מורחבים מקובצי WebP.

דוגמאות לקוד

פענוח נתוני WebP כדי לחלץ את כל המסגרות, פרופיל ICC ומטא-נתונים של EXIF/XMP

WebPDemuxer* demux = WebPDemux(&webp_data);

uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH);
uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT);
// ... (Get information about the features present in the WebP file).
uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS);

// ... (Iterate over all frames).
WebPIterator iter;
if (WebPDemuxGetFrame(demux, 1, &iter)) {
  do {
    // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(),
    // ... and get other frame properties like width, height, offsets etc.
    // ... see 'struct WebPIterator' below for more info).
  } while (WebPDemuxNextFrame(&iter));
  WebPDemuxReleaseIterator(&iter);
}

// ... (Extract metadata).
WebPChunkIterator chunk_iter;
if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter);
// ... (Consume the ICC profile in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter);
// ... (Consume the EXIF metadata in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter);
// ... (Consume the XMP metadata in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
WebPDemuxDelete(demux);

חייו של אובייקט הדמיה

טיפוסים בני מנייה (enum)

typedef enum WebPDemuxState {
  WEBP_DEMUX_PARSE_ERROR    = -1,  // An error occurred while parsing.
  WEBP_DEMUX_PARSING_HEADER =  0,  // Not enough data to parse full header.
  WEBP_DEMUX_PARSED_HEADER  =  1,  // Header parsing complete,
                                   // data may be available.
  WEBP_DEMUX_DONE           =  2   // Entire file has been parsed.
} WebPDemuxState;

WebPGetDemuxVersion()

פונקציה זו מחזירה את מספר הגרסה של ספריית demux, ארוזה בהקסדצימלית באמצעות 8 סיביות לכל גרסה ראשית/משנית/גרסה. לדוגמה, גרסה 2.5.7 היא 0x020507.

int WebPGetDemuxVersion(void);

WebPDemux()

ניתוח של קובץ ה-WebP המלא שמסופק על ידי data.

WebPDemuxer WebPDemux(const WebPData* data);

מחזירה אובייקט WebPDemuxer בניתוח מוצלח, NULL, אחרת.

WebPDemuxPartial()

ניתוח של קובץ ה-WebP שעשוי להיות חלקי, שניתן על ידי data. אם state הוא שהוא לא NULL, הוא יוגדר כדי לציין את סטטוס הדמוקזר.

WebPDemuxer WebPDemuxPartial(const WebPData* data, WebPDemuxState* state);

הפונקציה מחזירה NULL במקרה של שגיאה או אם אין מספיק נתונים כדי להתחיל בניתוח. ואובייקט WebPDemuxer בניתוח מוצלח.

חשוב לשים לב: WebPDemuxer שומר מצביעים פנימיים על מקטע זיכרון נתונים. אם המיקום הם תנודתיים, יש למחוק את אובייקט הדמוקזר (על ידי קריאה WebPDemuxDelete()) וגם WebPDemuxPartial() התקשר שוב לגבי הנתונים החדשים. הדבר בדרך כלל פעולה לא יקרה.

WebPDemuxDelete()

הסרת זיכרון שמשויך ל-dmux.

void WebPDemuxDelete(WebPDemuxer* dmux);

חילוץ נתונים/מידע

typedef enum WebPFormatFeature {
  WEBP_FF_FORMAT_FLAGS,      // bit-wise combination of WebPFeatureFlags
                             // corresponding to the 'VP8X' chunk (if present).
  WEBP_FF_CANVAS_WIDTH,
  WEBP_FF_CANVAS_HEIGHT,
  WEBP_FF_LOOP_COUNT,        // only relevant for animated file
  WEBP_FF_BACKGROUND_COLOR,  // idem.
  WEBP_FF_FRAME_COUNT        // Number of frames present in the demux object.
                             // In case of a partial demux, this is the number
                             // of frames seen so far, with the last frame
                             // possibly being partial.
} WebPFormatFeature;

WebPDemuxGetI()

אפשר לקבל את הערך של התכונה מה-dmux.

uint32_t WebPDemuxGetI(const WebPDemuxer* dmux, WebPFormatFeature feature);

הערה: הערכים תקפים רק אם השתמשתם ב-WebPDemux() או הוחזרה מדינה > WebPDemuxPartial() WEBP_DEMUX_PARSING_HEADER.

איטרציה של פריימים

struct WebPIterator {
  int frame_num;
  int num_frames;          // equivalent to WEBP_FF_FRAME_COUNT.
  int fragment_num;
  int num_fragments;
  int x_offset, y_offset;  // offset relative to the canvas.
  int width, height;       // dimensions of this frame or fragment.
  int duration;            // display duration in milliseconds.
  WebPMuxAnimDispose dispose_method;  // dispose method for the frame.
  int complete;   // true if 'fragment' contains a full frame. partial images
                  // may still be decoded with the WebP incremental decoder.
  WebPData fragment;  // The frame or fragment given by 'frame_num' and
                      // 'fragment_num'.
  int has_alpha;      // True if the frame or fragment contains transparency.
  WebPMuxAnimBlend blend_method;  // Blend operation for the frame.
};

WebPDemuxGetFrame()

שולפת מסגרת frame_number מ-dmux.

int WebPDemuxGetFrame(const WebPDemuxer* dmux,
                      int frame_number,
                      WebPIterator* iter);

iter-&gt;fragment מצביע על המקטע הראשון בהחזר מהפונקציה הזו. אפשר לחלץ מקטעים בודדים באמצעות WebPDemuxSelectFragment() ההגדרה frame_number שווה ל-0 יחזיר את הפריים האחרון של התמונה.

הפונקציה מחזירה את הערך False אם dmux הוא NULL או אם אין מסגרת dmux. קוראים לפונקציה WebPDemuxReleaseIterator() כשמשתמשים ב האיטרטור הושלם.

הערה: dmux חייב להישאר בכל משך החיים של iter.

WebPDemuxNextFrame(), WebPDemuxPrevFrame()

מגדיר את iter-&gt;fragment כדי להצביע על הבא (iter-&gt;fragment + 1) או המסגרת הקודמת (iter-&gt;frame_num - 1) . הפונקציות האלה לא מופיעות בלולאה.

int WebPDemuxNextFrame(WebPIterator* iter);
int WebPDemuxPrevFrame(WebPIterator* iter);

הפונקציה מחזירה את הערך True אחרי הצלחה, ומחזירה את הערך False אם לא.

WebPDemuxSelectFragment()

מגדיר את iter-&gt;fragment כדי לשקף את מספר המקטע iter-&gt;fragment.

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

הפונקציה מחזירה את הערך True אם המקטע fragment_num קיים. אחרת, הערך false.

WebPDemuxReleaseIterator()

משחררים כל זיכרון המשויך ל-iter.

void WebPDemuxReleaseIterator(WebPIterator* iter);

חובה להתקשר לפני קריאות נוספות למספר WebPDemuxGetChunk() באותו חזרה. כמו כן, צריכות להיות נשלחה לפני השמדת WebPDemuxer המשויך עם WebPDemuxDelete().

איטרציה של מקטעים

struct WebPChunkIterator {
  // The current and total number of chunks with the fourcc given to
  // WebPDemuxGetChunk().
  int chunk_num;
  int num_chunks;
  WebPData chunk;    // The payload of the chunk.
};

WebPDemuxGetChunk()

מאחזר את המופע chunk_number של המקטע עם המזהה fourcc מ- dmux.

int WebPDemuxGetChunk(const WebPDemuxer* dmux,
                      const char fourcc[4], int chunk_number,
                      WebPChunkIterator* iter);

fourcc הוא מערך תווים שמכיל את ה-4cc של המקטע שצריך להחזיר, לדוגמה "ICCP", "XMP", "EXIF" וכו'.

אם הערך של chunk_number שווה ל-0, תוחזר המקטע האחרון בקבוצה.

הפונקציה מחזירה את הערך True אם המקטע נמצא. אחרת, הפונקציה מחזירה את הערך False. מקטע שקשור לתמונה הגישה למטענים ייעודיים (payloads) מתבצעת דרך WebPDemuxGetFrame() ופונקציות קשורות. שיחת טלפון WebPDemuxReleaseChunkIterator() בזמן השימוש באיטרטור הושלם.

הערה: ה-dmux חייב להישאר בכל משך החיים של האיטרטור.

WebPDemuxNextChunk(), WebPDemuxPrevChunk()

מגדיר את iter->chunk כדי להצביע אל הבא (iter->chunk_num + 1) או המקטע הקודם (iter->chunk_num - 1). הפונקציות האלה לא מופיעות בלולאה.

int WebPDemuxNextChunk(WebPChunkIterator* iter);
int WebPDemuxPrevChunk(WebPChunkIterator* iter);

הפונקציה מחזירה את הערך True אחרי הצלחה, ומחזירה את הערך False אם לא.

WebPDemuxReleaseChunkIterator()

משחררים כל זיכרון המשויך ל-iter.

void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);

חייבים לקרוא לפני שמשמידים את WebPDemuxer המשויך עם WebPDemuxDelete().

ממשק API של WebPAnimDecoder

ה-API הזה מאפשר לפענח (כנראה) תמונות WebP מונפשות.

דוגמה לקוד

WebPAnimDecoderOptions dec_options;
WebPAnimDecoderOptionsInit(&dec_options);
// Tune 'dec_options' as needed.
WebPAnimDecoder* dec = WebPAnimDecoderNew(webp_data, &dec_options);
WebPAnimInfo anim_info;
WebPAnimDecoderGetInfo(dec, &anim_info);
for (uint32_t i = 0; i < anim_info.loop_count; ++i) {
  while (WebPAnimDecoderHasMoreFrames(dec)) {
    uint8_t* buf;
    int timestamp;
    WebPAnimDecoderGetNext(dec, &buf, &timestamp);
    // ... (Render 'buf' based on 'timestamp').
    // ... (Do NOT free 'buf', as it is owned by 'dec').
  }
  WebPAnimDecoderReset(dec);
}
const WebPDemuxer* demuxer = WebPAnimDecoderGetDemuxer(dec);
// ... (Do something using 'demuxer'; e.g. get EXIF/XMP/ICC data).
WebPAnimDecoderDelete(dec);

typedef struct WebPAnimDecoder WebPAnimDecoder;  // Main opaque object.

אפשרויות גלובליות

struct WebPAnimDecoderOptions {
  // Output colorspace. Only the following modes are supported:
  // MODE_RGBA, MODE_BGRA, MODE_rgbA and MODE_bgrA.
  WEBP_CSP_MODE color_mode;
  int use_threads;           // If true, use multi-threaded decoding.
};

WebPAnimDecoderOptionsInit()

צריך לקרוא תמיד, כדי לאתחל WebPAnimDecoderOptions חדש לפני ביצוע השינוי. הפונקציה מחזירה את הערך False במקרה של חוסר התאמה בין הגרסאות. WebPAnimDecoderOptionsInit() חייב להצליח לפני השימוש אובייקט dec_options.

פרמטרים

dec_options -- (in/out) המשמשות לפענוח אנימציה

החזרות
נכון להצלחה
int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options);

WebPAnimDecoderNew()

יצירה והפעלה של אובייקט WebPAnimDecoder.

פרמטרים

webp_data -- (ב) WebPbitstream. הערך הזה יישאר ללא שינוי במהלך משך החיים של אובייקט הפלט WebPAnimDecoder.

dec_options -- (ב) אפשרויות פענוח. ניתן להעביר NULL לבחירה ברירות מחדל סבירות (במיוחד מצב הצבע מצב_RGBA שייבחר).

החזרות

מצביע לאובייקט WebPAnimDecoder שנוצר, או NULL, למקרה של שגיאת ניתוח, אפשרות לא חוקית או שגיאת זיכרון.

WebPAnimDecoder* WebPAnimDecoderNew(
    const WebPData* webp_data, const WebPAnimDecoderOptions* dec_options);

מידע גלובלי על האנימציה.

struct WebPAnimInfo {
  uint32_t canvas_width;
  uint32_t canvas_height;
  uint32_t loop_count;
  uint32_t bgcolor;
  uint32_t frame_count;
};

WebPAnimDecoderGetInfo()

לקבל מידע גלובלי על האנימציה.

פרמטרים

dec -- (ב) מכונת מפענח שממנה רוצים לקבל מידע.

info -- מידע גלובלי (out) שאוחזר מהאנימציה.

החזרות

נכון לגבי הצלחה.

int WebPAnimDecoderGetInfo(const WebPAnimDecoder* dec,
                           WebPAnimInfo* info);

WebPAnimDecoderGetNext()

אחזור הפריים הבא מ-dec על סמך האפשרויות שסופקו ל- WebPAnimDecoderNew(). זו תהיה קנבס משוחזר בגודל canvas_width * 4 * canvas_height, ולא רק מלבן המשנה של המסגרת. המאגר של מאגר הנתונים הזמני שהוחזר תקף רק עד השיחה הבאה אל WebPAnimDecoderGetNext(), WebPAnimDecoderReset() או WebPAnimDecoderDelete().

פרמטרים

dec -- מופע של מפענח (in/out) שממנו הפריים הבא צריך להיות אוחזרו.

buf -- (מחוץ) מסגרת מפוענחת.

timestamp -- חותמת זמן (out) של הפריים באלפיות השנייה.

החזרות

הערך יהיה False אם אחד מהארגומנטים הוא NULL, או אם יש ניתוח או או כשאין עוד פריימים. אחרת, הפונקציה מחזירה את הערך True.

int WebPAnimDecoderGetNext(WebPAnimDecoder* dec,
                           uint8_t** buf, int* timestamp);

WebPAnimDecoderHasMoreFrames()

בודקים אם נשארו עוד פריימים לפענוח.

פרמטרים
dec – (ב) מכונת המפענח שצריך לבדוק.
החזרות
True אם הערך dec הוא לא NULL וחלק מהפריימים עדיין לא מפוענחים. אחרת, מחזירה False.
int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

WebPAnimDecoderReset()

מאפס את האובייקט WebPAnimDecoder, כך שהקריאה הבאה הפענוח יופעל מחדש על ידי WebPAnimDecoderGetNext() מהפריים הראשון. האפשרות הזו שימושית כשצריך לפענח את כל הפריימים מספר פעמים (למשל, info.loop_count פעמים) בלי להרוס וליצור מחדש את המילים את האובייקט dec.

פרמטרים
dec -- (in/out) של המפענח של המפענח שצריך לאפס
void WebPAnimDecoderReset(WebPAnimDecoder* dec);

WebPAnimDecoderGetDemuxer()

לוקחים את אובייקט הדחיסה הפנימי.

אחזור אובייקט demuxer יכול להיות שימושי אם רוצים להשתמש בפעולות בלבד זמין דרך demuxer, לדוגמה כדי לקבל מטא-נתונים של XMP/EXIF/ICC. המוחזר אובייקט demuxer נמצא בבעלות של dec ותקף רק עד הקריאה הבאה ל- WebPAnimDecoderDelete().

פרמטרים
dec -- (ב) מופע של מפענח שממנו אובייקט הדמוקזר אמור להיות אוחזרו.
const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

נמחק את האובייקט WebPAnimDecoder.

פרמטרים
dec -- (in/out) של המקודד של המפענח למחיקה.
החזרות
נכון להצלחה.
void WebPAnimDecoderDelete(WebPAnimDecoder* dec);

סוגי נתונים נפוצים

טיפוסים בני מנייה (enum)

typedef enum WebPFeatureFlags {
  FRAGMENTS_FLAG  = 0x00000001,
  ANIMATION_FLAG  = 0x00000002,
  XMP_FLAG        = 0x00000004,
  EXIF_FLAG       = 0x00000008,
  ALPHA_FLAG      = 0x00000010,
  ICCP_FLAG       = 0x00000020
} WebPFeatureFlags;

// Dispose method (animation only). Indicates how the area used by the current
// frame is to be treated before rendering the next frame on the canvas.
typedef enum WebPMuxAnimDispose {
  WEBP_MUX_DISPOSE_NONE,       // Do not dispose.
  WEBP_MUX_DISPOSE_BACKGROUND  // Dispose to background color.
} WebPMuxAnimDispose;

// Blend operation (animation only). Indicates how transparent pixels of the
// current frame are blended with those of the previous canvas.
typedef enum WebPMuxAnimBlend {
  WEBP_MUX_BLEND,              // Blend.
  WEBP_MUX_NO_BLEND            // Do not blend.
} WebPMuxAnimBlend;

WebPDataInit()

אתחול התוכן של האובייקט webp_data בערכי ברירת המחדל.

void WebPDataInit(WebPData* webp_data);

WebPDataClear()

ניקוי התוכן של האובייקט webp_data באמצעות קריאה ל-free(). לא מקציבים את האובייקט עצמו.

void WebPDataClear(WebPData* webp_data);

WebPDataCopy()

ב-Google Allo מסתיים האחסון הנדרש ל-dst, ומעתיק את התוכן של src. הפונקציה מחזירה את הערך true.

int WebPDataCopy(const WebPData* src, WebPData* dst);