path: root/libavutil/murmur3.h (plain)
blob: 6a1694c08df29f83569245da7f691da643f4dde1

1	/*
2	* Copyright (C) 2013 Reimar Döffinger <Reimar.Doeffinger@gmx.de>
3	*
4	* This file is part of FFmpeg.
5	*
6	* FFmpeg is free software; you can redistribute it and/or
7	* modify it under the terms of the GNU Lesser General Public
8	* License as published by the Free Software Foundation; either
9	* version 2.1 of the License, or (at your option) any later version.
10	*
11	* FFmpeg is distributed in the hope that it will be useful,
12	* but WITHOUT ANY WARRANTY; without even the implied warranty of
13	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14	* Lesser General Public License for more details.
15	*
16	* You should have received a copy of the GNU Lesser General Public
17	* License along with FFmpeg; if not, write to the Free Software
18	* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19	*/
20
21	/**
22	* @file
23	* @ingroup lavu_murmur3
24	* Public header for MurmurHash3 hash function implementation.
25	*/
26
27	#ifndef AVUTIL_MURMUR3_H
28	#define AVUTIL_MURMUR3_H
29
30	#include <stdint.h>
31
32	/**
33	* @defgroup lavu_murmur3 Murmur3
34	* @ingroup lavu_hash
35	* MurmurHash3 hash function implementation.
36	*
37	* MurmurHash3 is a non-cryptographic hash function, of which three
38	* incompatible versions were created by its inventor Austin Appleby:
39	*
40	* - 32-bit output
41	* - 128-bit output for 32-bit platforms
42	* - 128-bit output for 64-bit platforms
43	*
44	* FFmpeg only implements the last variant: 128-bit output designed for 64-bit
45	* platforms. Even though the hash function was designed for 64-bit platforms,
46	* the function in reality works on 32-bit systems too, only with reduced
47	* performance.
48	*
49	* @anchor lavu_murmur3_seedinfo
50	* By design, MurmurHash3 requires a seed to operate. In response to this,
51	* libavutil provides two functions for hash initiation, one that requires a
52	* seed (av_murmur3_init_seeded()) and one that uses a fixed arbitrary integer
53	* as the seed, and therefore does not (av_murmur3_init()).
54	*
55	* To make hashes comparable, you should provide the same seed for all calls to
56	* this hash function -- if you are supplying one yourself, that is.
57	*
58	* @{
59	*/
60
61	/**
62	* Allocate an AVMurMur3 hash context.
63	*
64	* @return Uninitialized hash context or `NULL` in case of error
65	*/
66	struct AVMurMur3 *av_murmur3_alloc(void);
67
68	/**
69	* Initialize or reinitialize an AVMurMur3 hash context with a seed.
70	*
71	* @param[out] c Hash context
72	* @param[in] seed Random seed
73	*
74	* @see av_murmur3_init()
75	* @see @ref lavu_murmur3_seedinfo "Detailed description" on a discussion of
76	* seeds for MurmurHash3.
77	*/
78	void av_murmur3_init_seeded(struct AVMurMur3 *c, uint64_t seed);
79
80	/**
81	* Initialize or reinitialize an AVMurMur3 hash context.
82	*
83	* Equivalent to av_murmur3_init_seeded() with a built-in seed.
84	*
85	* @param[out] c Hash context
86	*
87	* @see av_murmur3_init_seeded()
88	* @see @ref lavu_murmur3_seedinfo "Detailed description" on a discussion of
89	* seeds for MurmurHash3.
90	*/
91	void av_murmur3_init(struct AVMurMur3 *c);
92
93	/**
94	* Update hash context with new data.
95	*
96	* @param[out] c Hash context
97	* @param[in] src Input data to update hash with
98	* @param[in] len Number of bytes to read from `src`
99	*/
100	void av_murmur3_update(struct AVMurMur3 *c, const uint8_t *src, int len);
101
102	/**
103	* Finish hashing and output digest value.
104	*
105	* @param[in,out] c Hash context
106	* @param[out] dst Buffer where output digest value is stored
107	*/
108	void av_murmur3_final(struct AVMurMur3 *c, uint8_t dst[16]);
109
110	/**
111	* @}
112	*/
113
114	#endif /* AVUTIL_MURMUR3_H */
115