מסמכי תיעוד של 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

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

// 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 – אובייקט (בתוך/מחוץ) למחיקה

יצירה של Mux

WebPMuxCreate()

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

WebPMux* WebPMuxCreate(const WebPData* bitstream, int copy_data);

פרמטרים

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

copy_data – (ב) ערך 1 מציין שהנתונים הנתונים יועתקו ל-mux והערך 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 של הקטע הנתון. למשל, "ICCP", "XMP", "EXIF" וכו'.

chunk_data -- (ב) נתוני המקטע שיש להוסיף

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

החזרות

WEBP_MUX_INVALID_ARGUMENT – אם ה-mux, ארבעהcc או chunk_data הם NULL או אם fourcc תואם לקבוצת תמונות.

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 -- (מ) החזירו נתוני מקטעים

החזרות

WEBP_MUX_INVALID_ARGUMENT – אם ה-mux, ארבעהcc או chunk_data הם NULL או אם fourcc תואם לקבוצת תמונות.

WEBP_MUX_NOT_FOUND – אם ה-mux לא מכיל גוש עם המזהה הנתון.

WEBP_MUX_OK -- בהצלחה.

WebPMuxDeleteChunk()

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

WebPMuxError WebPMuxDeleteChunk(WebPMux* mux, const char fourcc[4]);

פרמטרים

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

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

החזרות

WEBP_MUX_INVALID_ARGUMENT – אם השדה mux או ארבעהcc הוא NULL, או אם הערך '4cc' תואם לקבוצת תמונות.

WEBP_MUX_NOT_FOUND – אם ה-mux לא מכיל גוש עם הרביעית הנתונה.

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()

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

WebPMuxError WebPMuxSetImage(WebPMux* mux,
                             const WebPData* bitstream,
                             int copy_data);

פרמטרים

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

bitstream -- (ב) יכול להיות זרם ביט גולמי VP8/VP8L או קובץ WebP עם תמונה יחידה (לא מונפש וללא פיצולים)

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

החזרות

WEBP_MUX_INVALID_ARGUMENT -- אם ה-mux הוא NULL או אם ה-bitstream הוא NULL.

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

WEBP_MUX_OK -- בהצלחה.

WebPMuxPushFrame()

מוסיף מסגרת בסוף אובייקט ה-mux.

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

הערות:

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

פרמטרים

mux -- האובייקט (בתוך/מחוץ) שאליו יש להוסיף את המסגרת

frame -- (בתוך) נתוני המסגרת.

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

החזרות

WEBP_MUX_INVALID_ARGUMENT -- אם ה-mux או המסגרת הם NULL או אם התוכן של המסגרת לא חוקי.

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

WEBP_MUX_OK -- בהצלחה.

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

WebPMuxGetFrame()

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

WebPMuxError WebPMuxGetFrame(const WebPMux* mux,
                             uint32_t nth,
                             WebPMuxFrameInfo* frame);

פרמטרים

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

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

frame -- נתוני (out) של המסגרת שהוחזרה

החזרות

WEBP_MUX_INVALID_ARGUMENT -- אם mux או מסגרת הם NULL.

WEBP_MUX_NOT_FOUND -- אם יש פחות מ-n פריימים באובייקט ה-mux.

WEBP_MUX_BAD_DATA -- אם המקטע של מסגרת ה-n ב-mux לא חוקי.

WEBP_MUX_OK -- בהצלחה.

WebPMuxDeleteFrame()

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

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);

פרמטרים

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

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

החזרות

WEBP_MUX_INVALID_ARGUMENT -- אם mux הוא NULL.

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

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 -- אם ה-mux או הפרמטרים הוא NULL.

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

WEBP_MUX_OK -- בהצלחה.

WebPMuxGetAnimationParams()

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

WebPMuxError WebPMuxGetAnimationParams(const WebPMux* mux,
                                       WebPMuxAnimParams* params);

פרמטרים

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

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

החזרות

WEBP_MUX_INVALID_ARGUMENT -- אם ה-mux או הפרמטרים הוא NULL.

WEBP_MUX_NOT_FOUND -- אם מקטע ANIM לא נמצא באובייקט mux.

WEBP_MUX_OK -- בהצלחה.

שירותים שונים

WebPMuxGetCanvasSize()

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

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

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

פרמטרים

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

width -- רוחב הקנבס (לא)

height – גובה הקנבס (מחוץ)

החזרות

WEBP_MUX_INVALID_ARGUMENT -- אם הרווח, הרוחב או הגובה הם NULL.

WEBP_MUX_BAD_DATA -- אם המקטעים VP8X/VP8/VP8L לא תקינים.

WEBP_MUX_OK -- בהצלחה.

WebPMuxGetFeatures()

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

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

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

פרמטרים

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

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

החזרות

WEBP_MUX_INVALID_ARGUMENT -- אם הערך של mux או דגלים הוא 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 -- אם הערך של mux או num_elements הוא NULL.

WEBP_MUX_OK -- בהצלחה.

WebPMuxAssemble()

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

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

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

פרמטרים

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

assembled_data -- נתוני WebP שנאספו (לא)

החזרות

WEBP_MUX_BAD_DATA -- אם אובייקט mux לא חוקי.

WEBP_MUX_INVALID_ARGUMENT -- אם הערך של mux או assembled_data הוא 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 במקרה של חוסר התאמה בין גרסאות. לפני השימוש באובייקט enc_options, צריכה להיות בעיה ב-WebPAnimEncoderOptionsInit() .

פרמטרים

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 -- נתוני פריימים (בתוך/מחוץ) בפורמט ARGB או YUV(A). אם הוא בפורמט YUV(A), הוא מומר ל-ARGB, וכתוצאה מכך הפסד קטן.

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

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 -- אובייקט (בתוך/מחוץ) שממנו יש להרכיב את המסגרות.

webp_data -- זרם ה-WebP של ה-WebP שנוצר (מחוץ).

החזרות

כל הכבוד על ההצלחה.

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 -- אובייקט (בפנים/מחוץ) למחיקה

void WebPAnimEncoderDelete(WebPAnimEncoder* enc);

Demux API

מאפשר חילוץ של נתוני תמונות ופורמטים מורחבים מקובצי 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);

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

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

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 שומרת את ההפניות הפנימיות לפלח הזיכרון נתונים. אם יש תנודתיות בנתונים האלה, צריך למחוק את אובייקט ה-demuxer (באמצעות קריאה ל-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()

מקבלים את הערך של feature מ-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->fragment מפנה למקטע הראשון בהחזרה מהפונקציה הזו. אפשר לחלץ מקטעים ספציפיים באמצעות WebPDemuxSelectFragment(). הגדרה של frame_number שווה ל-0 תחזיר את המסגרת האחרונה של התמונה.

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

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

WebPDemuxNextFrame(), WebPDemuxPrevFrame()

הפונקציה מגדירה את iter->fragment כך שיפנה למסגרת הבאה (iter->frame_num + 1) או הקודם (iter->frame_num - 1). הפונקציות האלה לא פועלות בלולאה.

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

הפונקציה מחזירה את הערך 'TRUE' על הצלחה, או 'FALSE' אם לא.

WebPDemuxSelectFragment()

iter->fragment מוגדר כך שישקף את מספר המקטע fragment_num.

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 -- (ב) Bitstream מסוג WebP. אין לשנות את הערך הזה במהלך משך החיים של אובייקט הפלט WebPAnimDecoder.

dec_options -- (ב) אפשרויות פענוח. אפשר להעביר את הערך NULL כדי לבחור ערכי ברירת מחדל סבירים (באופן ספציפי, נבחר מצב הצבע Mode_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 – מידע גלובלי שאוחזר מהאנימציה.

החזרות

כל הכבוד על ההצלחה.

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()

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

פרמטרים

דצ -- (ב) מופע של מפענח שצריך לבדוק.

החזרות

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 יכולה להיות שימושית אם רוצים להשתמש בפעולות שזמינות רק דרך demuxer, למשל כדי לקבל מטא-נתונים של XMP/EXIF/ICC. אובייקט ה-demuxer שמוחזר נמצא בבעלות dec, ותקף רק עד הקריאה הבאה אל WebPAnimDecoderDelete().

פרמטרים

dec -- (ב) מופע מפענח שממנו יש להביא את אובייקט ה-demuxer.

const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

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

פרמטרים

דצ -- מופע המפענח (בתוך/מחוץ) יימחק.

החזרות

ההצלחה מובטחת.

void WebPAnimDecoderDelete(WebPAnimDecoder* dec);

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

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

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()

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

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