Warning, /graphics/kphotoalbum/dev/documentation/thumbnail-storage.md is written in an unsupported language. File is not indexed.
0001 <!-- 0002 SPDX-FileCopyrightText: 2020 Johannes Zarl-Zierl <johannes@zarl-zierl.at> 0003 SPDX-FileCopyrightText: 2022 Johannes Zarl-Zierl <johannes@zarl-zierl.at> 0004 0005 SPDX-License-Identifier: CC-BY-SA-4.0 0006 --> 0007 0008 # Thumbnail storage file formats 0009 0010 Thumbnails are stored in packed form in `.thumbnails` in the image root folder. Thumbnails can be recreated from the image files. The packed format is much more efficient in terms of I/O than storing the thumbnails as individual image files in the filesystem. 0011 0012 The thumbnails themselves are stored in JPEG format, packed into 32 MB container files named `thumb-<n>`, with n starting from 0 and incrementing as needed. The size of the JPEG images is determined by the user's configuration choice. The choice of 32 MB is arbitrary, but it combines good I/O efficiency (many thumbnails per file and the ability to stream thumbnails efficiently) with backup efficiency (not modifying very large files constantly). There is no header, delimiter, or descriptor for the thumbnails in the container files; they require the thumbnailindex described below to be of use. 0013 0014 Additionally, an index file named `thumbnailindex` contains an index allowing KPhotoAlbum to quickly locate the thumbnail for any given file. The thumbnailindex file is stored in binary form as implemented by QDataStream, as depicted below. The thumbnailindex cannot be regenerated from the thumbnail containers. 0015 0016 ## Version 4 0017 0018 Since KPhotoAlbum 4.3. 0019 0020 ### thumbnailindex 0021 0022 The index file contains some header information as described below, followed by the actual cache entries. 0023 String data is UTF-8 encoded, data is stored as big-endian. 0024 0025 ```` 0026 using FileIndex = int32; 0027 using ByteOffset = int32; 0028 using ByteSize = int32; 0029 0030 struct CacheLine { 0031 int32 string_length; 0032 char filename_relative[string_length]; 0033 FileIndex file_index; /* Index for thumbnail file. Name: "thumb-%d" */ 0034 ByteOffset offset_bytes; /* Offset in thumbnail file. */ 0035 ByteSize size_bytes; /* Thumbnail data size in bytes. */ 0036 } 0037 0038 struct Cache { 0039 int32 FILE_VERSION; /* assert(FILE_VERSION == 4); */ 0040 FileIndex CURRENT_FILE; /* Highest index for thumbnail file. */ 0041 ByteOffset CURRENT_OFFSET; /* Offset for the next thumbnail in the thumbnail file. */ 0042 ByteSize CACHE_SIZE; /* Number of files/thumbnails in the cache. */ 0043 CacheLine CACHE_ENTRIES[CACHE_SIZE]; 0044 } 0045 ```` 0046 0047 ### Thumbnail files 0048 0049 Raw data files containing thumbnail data in JPEG format. 0050 File size is limited by KPhotoAlbum to at most 32MB. 0051 0052 The files are names "thumb-%d" where "%d" corresponds to the thumbnail index used in the `thumbnailindex` file. 0053 0054 0055 ## Version 5 0056 0057 Since KPhotoAlbum 4.7. 0058 The thumbnail dimensions are now stored in the `thumbnailindex` to prevent inconsistencies. 0059 0060 ## thumbnailindex 0061 0062 ```` 0063 using FileIndex = int32; 0064 using ByteOffset = int32; 0065 using ByteSize = int32; 0066 0067 struct CacheLine { 0068 int32 string_length; 0069 char filename_relative[string_length]; 0070 FileIndex file_index; /* Index for thumbnail file. Name: "thumb-%d" */ 0071 ByteOffset offset_bytes; /* Offset in thumbnail file. */ 0072 ByteSize size_bytes; /* Thumbnail data size in bytes. */ 0073 } 0074 0075 struct Cache { 0076 int32 FILE_VERSION; /* assert(FILE_VERSION == 5); */ 0077 int32 THUMBNAIL_DIMENSIONS; /* Size of the longer edge of a thumbnail in pixels. */ 0078 FileIndex CURRENT_FILE; /* Highest index for thumbnail file. */ 0079 ByteOffset CURRENT_OFFSET; /* Offset for the next thumbnail in the thumbnail file. */ 0080 ByteSize CACHE_SIZE; /* Number of files/thumbnails in the cache. */ 0081 CacheLine CACHE_ENTRIES[CACHE_SIZE]; 0082 } 0083 ```` 0084 0085 ## Thumbnail files 0086 0087 Unchanged to previous version.