1// Copyright 2015 Google Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15////////////////////////////////////////////////////////////////////////////////
16//
17// The purpose of the preview-image-extractor (piex) is to find and extract the
18// largest JPEG compressed preview image contained in a RAW file.
19//
20// Even for unsupported RAW files we want to provide high quality images using a
21// dedicated, small and portable library. That is possible by taking the preview
22// image contained in all RAW files.
23//
24// Typically a preview image is stored as JPEG compressed, full size (or at
25// least half size) image in a RAW file.
26//
27// A typical client code snippet:
28//
29// // In C++
30// PreviewImageData image_data;
31// unique_ptr<StreamInterface> data_stream(new DataStream(file));
32// Error err = GetPreviewImageData(data_stream.get(), &image_data));
33// if (err == Error::kFail) {
34// // The input data seems to be broken.
35// return;
36// } else if (err == Error::kUnsupported) {
37// // The input data is not supported.
38// return;
39// }
40//
41// // Uncompress the JPEG as usual, e.g. on Android with the BitmapFactory:
42// // In Java
43// Bitmap bitmap = BitmapFactory.decodeByteArray(
44// file.at(image_data.preview_offset), image_data.preview_length);
45
46#ifndef PIEX_PIEX_H_
47#define PIEX_PIEX_H_
48
49#include <string>
50#include <vector>
51
52#include "src/piex_types.h"
53
54namespace piex {
55
56// Returns the maximum number of bytes IsRaw() will read from the stream.
57size_t BytesRequiredForIsRaw();
58
59// Returns true if 'data' contains a RAW file format, even if it is not
60// supported by Piex, false otherwise. Reads at most BytesRequiredForIsRaw()
61// from the stream.
62bool IsRaw(StreamInterface* data);
63
64// Gets the largest JPEG compressed preview image data. On success
65// 'preview_image_data' contains image metadata, the unverified length and the
66// offset to a JPEG compressed image from the beginning of the file.
67//
68// Returns 'kFail' when something with the data is wrong.
69// Returns 'kUnsupported' if file format is not supported.
70//
71// One could check the "preview_image_data->preview_length != 0" for the
72// existance of a preview image.
73Error GetPreviewImageData(StreamInterface* data,
74 PreviewImageData* preview_image_data);
75
76// Returns true if the full width and height and the mosaic pattern dimension of
77// a DNG image could be obtained. False otherwise.
78bool GetDngInformation(StreamInterface* data, std::uint32_t* width,
79 std::uint32_t* height,
80 std::vector<std::uint32_t>* cfa_pattern_dim);
81
82// Returns true if Exif orientation for the image can be obtained. False
83// otherwise.
84bool GetOrientation(StreamInterface* data, std::uint32_t* orientation);
85
86// Returns a vector of upper case file extensions, which are used as a first
87// step to quickly guess a supported file format.
88std::vector<std::string> SupportedExtensions();
89
90} // namespace piex
91
92#endif // PIEX_PIEX_H_
93