WebP Container API 문서

WebP 이미지의 RIFF 컨테이너 조작

Mux API

색상 프로필, 메타데이터, 애니메이션, 분할 이미지와 같은 기능이 포함된 WebP 컨테이너 이미지를 조작할 수 있습니다.

코드 예시

이미지 데이터, 색상 프로필, XMP 메타데이터로 MUX 만들기

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 객체의 수명

열거형

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

주/부/버전 각각에 8비트를 사용하여 16진수로 패키징된 Mux 라이브러리의 버전 번호를 반환합니다. 예를 들어 v2.5.7은 0x020507입니다.

int WebPGetMuxVersion(void);

WebPMuxNew()

빈 Mux 객체를 만듭니다.

WebPMux* WebPMuxNew(void);
반환 값
새로 생성된 빈 Mux 객체를 가리키는 포인터입니다.

WebPMuxDelete()

Mux 객체를 삭제합니다.

void WebPMuxDelete(WebPMux* mux);
매개변수
mux -- (in/out) 삭제할 객체

Mux 생성

WebPMuxCreate()

WebP RIFF 형식에 지정된 원시 데이터에서 Mux 객체를 만듭니다.

WebPMux* WebPMuxCreate(const WebPData* bitstream, int copy_data);
매개변수

bitstream -- WebP RIFF 형식의 비트스트림 데이터(내)

copy_data -- (in) 값 1은 지정된 데이터가 mux에 복사됨을 나타내고 0은 데이터가 mux 객체에 복사되지 않음을 나타냅니다.

반환 값

성공 시 지정된 데이터에서 생성된 Mux 객체를 가리키는 포인터입니다.

NULL -- 잘못된 데이터나 메모리 오류가 발생한 경우.

이미지가 아닌 덩어리

WebPMuxSetChunk()

ID가 fourcc이고 데이터가 chunk_data인 청크를 Mux 객체에 추가합니다. ID가 동일한 기존 청크는 삭제됩니다.

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 -- (in) 지정된 청크의 4cc가 포함된 문자 배열입니다. 예: 'ICCP', 'XMP ', 'EXIF' 등

chunk_data -- 추가할 청크 데이터

copy_data -- (in) 값 1은 지정된 데이터가 mux에 복사됨을 나타내고 0은 데이터가 mux 객체에 복사되지 않음을 나타냅니다.

반환 값

WEBP_MUX_INVALID_ARGUMENT -- mux, fourcc 또는 chunk_data가 NULL이거나fourcc가 이미지 청크에 해당하는 경우입니다.

WEBP_MUX_MEMORY_ERROR: 메모리 할당 오류 시

WEBP_MUX_OK: 성공 시

WebPMuxGetChunk()

Mux 객체에서 ID가 fourcc인 청크 데이터의 참조를 가져옵니다. 호출자는 반환된 데이터를 해제하면 안 됩니다.

WebPMuxError WebPMuxGetChunk(const WebPMux* mux,
                             const char fourcc[4],
                             WebPData* chunk_data);
매개변수

mux - 청크 데이터를 가져올 (내부) 객체

fourcc -- (in) 청크의 4cc가 포함된 문자 배열입니다. 예: 'ICCP', 'XMP ', 'EXIF' 등

chunk_data -- (출력) 청크 데이터를 반환함

반환 값

WEBP_MUX_INVALID_ARGUMENT -- mux, fourcc 또는 chunk_data가 NULL이거나fourcc가 이미지 청크에 해당하는 경우입니다.

WEBP_MUX_NOT_FOUND - mux에 지정된 ID가 있는 청크가 포함되지 않은 경우

WEBP_MUX_OK: 성공 시

WebPMuxDeleteChunk()

지정된 fourcc를 사용하여 Mux 객체에서 청크를 삭제합니다.

WebPMuxError WebPMuxDeleteChunk(WebPMux* mux, const char fourcc[4]);
매개변수

mux - 청크를 삭제할 (in/out) 객체

fourcc -- (in) 청크의 4cc가 포함된 문자 배열입니다. 예: 'ICCP', 'XMP ', 'EXIF' 등

반환 값

WEBP_MUX_INVALID_ARGUMENT -- mux 또는fourcc가 NULL이거나 Forcc가 이미지 청크에 해당하는 경우

WEBP_MUX_NOT_FOUND -- mux에 지정된 Forcc가 있는 청크가 포함되지 않은 경우

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 -- (in)은 원시 VP8/VP8L 비트스트림 또는 단일 이미지 WebP 파일 (애니메이션 및 조각화되지 않은 파일)일 수 있습니다.

copy_data -- (in) 값 1은 지정된 데이터가 mux에 복사됨을 나타내고 0은 데이터가 mux 객체에 복사되지 않음을 나타냅니다.

반환 값

WEBP_MUX_INVALID_ARGUMENT: mux가 NULL이거나 비트스트림이 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는 짝수 오프셋만 지원하므로 모든 홀수 오프셋은 offset &= ~1을 사용하여 짝수 위치에 맞춰집니다.
매개변수

mux - 프레임을 추가할 (in/out) 객체

frame -- (인) 프레임 데이터입니다.

copy_data -- (in) 값 1은 지정된 데이터가 mux에 복사됨을 나타내고 0은 데이터가 mux 객체에 복사되지 않음을 나타냅니다.

반환 값

WEBP_MUX_INVALID_ARGUMENT - mux 또는 프레임이 NULL이거나 frame 콘텐츠가 잘못된 경우

WEBP_MUX_MEMORY_ERROR: 메모리 할당 오류 시

WEBP_MUX_OK: 성공 시

WEBP_MUX_MEMORY_ERROR: 메모리 할당 오류 시

WebPMuxGetFrame()

Mux 객체에서 n번째 프레임을 가져옵니다. frame->bitstream의 콘텐츠는 malloc()을 사용하여 할당되며 mux 객체가 소유하지 않습니다. WebPDataClear()를 호출하여 호출자에 의해 할당 취소되어야 합니다(MUST). nth=0은 마지막 위치라는 특별한 의미가 있습니다.

WebPMuxError WebPMuxGetFrame(const WebPMux* mux,
                             uint32_t nth,
                             WebPMuxFrameInfo* frame);
매개변수

mux - 정보를 가져올 (in) 객체

nth -- (in) Mux 객체의 프레임에 대한 색인

frame -- 반환된 프레임의 (외부) 데이터

반환 값

WEBP_MUX_INVALID_ARGUMENT: mux 또는 프레임이 NULL인 경우

WEBP_MUX_NOT_FOUND: 다중 객체의 프레임이 n번째 미만인 경우

WEBP_MUX_BAD_DATA: Mux의 n번째 프레임 청크가 유효하지 않은 경우.

WEBP_MUX_OK: 성공 시

WebPMuxDeleteFrame()

Mux 객체에서 프레임을 삭제합니다. nth=0은 마지막 위치라는 특수한 의미를 가집니다.

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);
매개변수

mux - 프레임을 삭제할 (in/out) 객체

nth -- (in) 프레임을 삭제할 위치

반환 값

WEBP_MUX_INVALID_ARGUMENT: mux가 NULL인 경우

WEBP_MUX_NOT_FOUND -- 삭제 전 다중 객체에 프레임이 n번째 미만인 경우.

WEBP_MUX_OK: 성공 시

애니메이션

애니메이션 매개변수

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 -- ANIM 청크가 설정/추가되는 (in/out) 객체

params -- 애니메이션 매개변수입니다.

반환 값

WEBP_MUX_INVALID_ARGUMENT: mux 또는 params가 NULL인 경우

WEBP_MUX_MEMORY_ERROR: 메모리 할당 오류 시

WEBP_MUX_OK: 성공 시

WebPMuxGetAnimationParams()

Mux 객체에서 애니메이션 매개변수를 가져옵니다.

WebPMuxError WebPMuxGetAnimationParams(const WebPMux* mux,
                                       WebPMuxAnimParams* params);
매개변수

mux - 애니메이션 매개변수를 가져올 (in) 객체입니다.

params -- ANIM 청크에서 추출된 (out) 애니메이션 매개변수

반환 값

WEBP_MUX_INVALID_ARGUMENT: mux 또는 params가 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 객체가 수정되지 않았습니다.

매개변수

mux - 캔버스 크기를 가져올 (in) 객체

너비 -- (바깥쪽) 캔버스 너비

height -- (외부) 캔버스 높이

반환 값

WEBP_MUX_INVALID_ARGUMENT: mux, 너비 또는 높이가 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 객체가 수정되지 않았습니다.

매개변수

mux - 특성을 가져올 (in) 객체입니다.

flags -- (out) Mux 객체에 있는 기능을 지정하는 플래그입니다. 다양한 플래그 값의 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 - 정보를 가져올 (in) 객체

id -- 청크 유형을 지정하는 청크 ID(in)

num_elements -- 지정된 청크 ID가 있는 (외부) 청크 개수

반환 값

WEBP_MUX_INVALID_ARGUMENT: mux 또는 num_elements가 NULL인 경우

WEBP_MUX_OK: 성공 시

WebPMuxAssemble()

WebP RIFF 형식으로 모든 청크를 조합하고 assembled_data로 반환합니다. 이 함수는 Mux 객체의 유효성을 검사합니다.

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

참고: compiled_data의 콘텐츠는 무시되고 덮어씁니다. 또한 assembled_data의 콘텐츠는 malloc()을 통해 할당되며 assembled_data 객체가 소유하지 않습니다. WebPDataClear()를 호출하여 호출자에 의해 할당 해제되어야 합니다(MUST).

매개변수

mux -- 청크를 조합할 (in/out) 객체입니다.

assembled_data -- (외부) 조합된 WebP 데이터

반환 값

WEBP_MUX_BAD_DATA: Mux 객체가 잘못된 경우

WEBP_MUX_INVALID_ARGUMENT: mux 또는 assertd_data가 NULL인 경우

WEBP_MUX_MEMORY_ERROR: 메모리 할당 오류 시

WEBP_MUX_OK: 성공 시

WebPAnimEncoder API

이 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 -- (in) 캔버스 애니메이션의 너비 및 높이입니다.

enc_options -- 인코딩 옵션(in)으로, 적절한 기본값을 선택하기 위해 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 -- 이 프레임의 (in) 타임스탬프(밀리초)입니다. 프레임의 지속 시간은 '다음 프레임의 타임스탬프 - 이 프레임의 타임스탬프'로 계산됩니다. 따라서 타임스탬프는 내림차순이어야 합니다.

config -- 인코딩 옵션(in)으로, 적절한 기본값을 선택하기 위해 NULL을 전달할 수 있습니다.

반환 값

오류가 발생하면 false가 반환되고 frame->error_code이 적절하게 설정됩니다. 그렇지 않으면 true를 반환합니다.

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

WebPAnimEncoderAssemble()

지금까지 추가된 모든 프레임을 WebP 비트스트림에 조합합니다. 이 호출 전에 frame = NULL로 WebPAnimEncoderAdd를 호출해야 합니다. 그러지 않으면 마지막 프레임의 지속 시간이 내부적으로 추정됩니다.

매개변수

enc -- 프레임이 조합될 (in/out) 객체입니다.

webp_data -- (출력) 생성된 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 -- (in/out) 객체를 삭제할 예정입니다.
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 객체의 수명

열거형

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

주/부/버전 각각에 8비트를 사용하여 16진수로 패키징된 demux 라이브러리의 버전 번호를 반환합니다. 예를 들어 v2.5.7은 0x020507입니다.

int WebPGetDemuxVersion(void);

WebPDemux()

data에서 제공된 전체 WebP 파일을 파싱합니다.

WebPDemuxer WebPDemux(const WebPData* data);

파싱이 성공하면 WebPDemuxer 객체를 반환하고 그렇지 않으면 NULL을 반환합니다.

WebPDemuxPartial()

data에서 제공한 불완전할 수 있는 WebP 파일을 파싱합니다. state가 NULL이 아니면 demuxer의 상태를 나타내도록 설정됩니다.

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에서 feature 값을 가져옵니다.

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

dmux에서 frame_number 프레임을 검색합니다.

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

iter->fragment는 이 함수에서 반환될 때 첫 번째 프래그먼트를 가리킵니다. WebPDemuxSelectFragment()를 사용하여 개별 프래그먼트를 추출할 수 있습니다. frame_number를 0으로 설정하면 이미지의 마지막 프레임이 반환됩니다.

dmux가 NULL이거나 프레임 frame_number가 없으면 false를 반환합니다. 반복기 사용이 완료되면 WebPDemuxReleaseIterator()를 호출합니다.

참고: dmux는 iter의 전체 기간 동안 지속되어야 합니다.

WebPDemuxNextFrame(), WebPDemuxPrevFrame()

다음 (iter->frame_num + 1) 또는 이전 (iter->frame_num - 1) 프레임을 가리키도록 iter->fragment를 설정합니다. 이러한 함수는 반복되지 않습니다.

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

성공 시 true를 반환하고 그렇지 않으면 false를 반환합니다.

WebPDemuxSelectFragment()

프래그먼트 번호 fragment_num을 반영하도록 iter->fragment를 설정합니다.

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

프래그먼트 fragment_num이 있으면 true를 반환하고 그렇지 않으면 false를 반환합니다.

WebPDemuxReleaseIterator()

iter와 연결된 모든 메모리를 해제합니다.

void WebPDemuxReleaseIterator(WebPIterator* iter);

동일한 반복에서 WebPDemuxGetChunk()를 후속 호출하기 전에 호출해야 합니다. 또한 WebPDemuxDelete()로 연결된 WebPDemuxer를 폐기하기 전에 호출해야 합니다.

청크 반복

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

ID가 fourcc인 청크의 chunk_number 인스턴스를 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를 반환합니다. 이미지 관련 청크 페이로드는 WebPDemuxGetFrame() 및 관련 함수를 통해 액세스됩니다. 반복기 사용이 완료되면 WebPDemuxReleaseChunkIterator()를 호출합니다.

참고: dmux는 반복기의 전체 기간 동안 지속되어야 합니다.

WebPDemuxNextChunk(), WebPDemuxPrevChunk()

다음 (iter->chunk_num + 1) 또는 이전 (iter->chunk_num - 1) 청크를 가리키도록 iter->chunk를 설정합니다. 이러한 함수는 반복되지 않습니다.

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

성공 시 true를 반환하고 그렇지 않으면 false를 반환합니다.

WebPDemuxReleaseChunkIterator()

iter와 연결된 모든 메모리를 해제합니다.

void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);

WebPDemuxDelete()로 연결된 WebPDemuxer를 폐기하기 전에 호출해야 합니다.

WebPAnimDecoder API

이 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 -- WebP 비트스트림(내)입니다. 출력 WebPAnimDecoder 객체의 전체 기간 동안 변경되지 않아야 합니다.

dec_options -- 디코딩 옵션(in)입니다. 적절한 기본값을 선택하기 위해 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 -- 정보를 가져올 디코더 인스턴스(in)입니다.

info -- 애니메이션에서 가져온 (외부) 전역 정보입니다.

반환 값

성공에 충실합니다.

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

WebPAnimDecoderGetNext()

WebPAnimDecoderNew()에 제공된 옵션에 따라 dec에서 다음 프레임을 가져옵니다. 이는 프레임 하위 직사각형뿐만 아니라 canvas_width * 4 * canvas_height 크기의 완전히 재구성된 캔버스입니다. 반환된 버퍼 buf는 다음번 WebPAnimDecoderGetNext(), WebPAnimDecoderReset() 또는 WebPAnimDecoderDelete() 호출까지만 유효합니다.

매개변수

dec -- 다음 프레임을 가져올 디코더 인스턴스(in/out)입니다.

buf -- (출력) 디코딩된 프레임.

timestamp -- 프레임의 (출력) 타임스탬프(밀리초)입니다.

반환 값

인수가 NULL이거나 파싱 또는 디코딩 오류가 있거나 더 이상 프레임이 없으면 false입니다. 그렇지 않으면 true를 반환합니다.

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

WebPAnimDecoderHasMoreFrames()

디코딩할 프레임이 더 있는지 확인합니다.

매개변수
dec: 확인할 디코더 인스턴스(in)입니다.
반환 값
dec가 NULL이 아니고 일부 프레임이 아직 디코딩되지 않은 경우 true입니다. 그렇지 않으면 False를 반환합니다.
int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

WebPAnimDecoderReset()

다음 WebPAnimDecoderGetNext() 호출 시 첫 번째 프레임에서 디코딩이 다시 시작되도록 WebPAnimDecoder 객체를 재설정합니다. 이는 dec 객체를 삭제하고 다시 생성하지 않고 모든 프레임을 여러 번 디코딩해야 할 때 (예: info.loop_count times) 유용합니다.

매개변수
dec -- 재설정할 (in/out) 디코더 인스턴스입니다.
void WebPAnimDecoderReset(WebPAnimDecoder* dec);

WebPAnimDecoderGetDemuxer()

내부 디퓨저 객체를 가져옵니다.

디믹서를 통해서만 사용할 수 있는 작업(예: XMP/EXIF/ICC 메타데이터 가져오기)을 사용하려는 경우 디믹서 객체를 가져오는 것이 유용할 수 있습니다. 반환된 디럭서 객체는 dec가 소유하며 다음 WebPAnimDecoderDelete() 호출까지만 유효합니다.

매개변수
dec: 디코더 객체를 가져올 디코더 인스턴스(in)입니다.
const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

WebPAnimDecoder 객체를 삭제합니다.

매개변수
dec: 삭제할 디코더 인스턴스(in/out)입니다.
반환 값
성공은 참입니다.
void WebPAnimDecoderDelete(WebPAnimDecoder* dec);

공통 데이터 유형

열거형

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

free()를 호출하여 webp_data 객체의 콘텐츠를 삭제합니다. 객체 자체를 할당 해제하지 않습니다.

void WebPDataClear(WebPData* webp_data);

WebPDataCopy()

dst에 필요한 저장소를 할당하고 src의 콘텐츠를 복사합니다. 성공 시 true를 반환합니다.

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