1//! Decoding of farbfeld images
2//!
3//! farbfeld is a lossless image format which is easy to parse, pipe and compress.
4//!
5//! It has the following format:
6//!
7//! | Bytes | Description |
8//! |--------|---------------------------------------------------------|
9//! | 8 | "farbfeld" magic value |
10//! | 4 | 32-Bit BE unsigned integer (width) |
11//! | 4 | 32-Bit BE unsigned integer (height) |
12//! | [2222] | 4⋅16-Bit BE unsigned integers [RGBA] / pixel, row-major |
13//!
14//! The RGB-data should be sRGB for best interoperability and not alpha-premultiplied.
15//!
16//! # Related Links
17//! * <https://tools.suckless.org/farbfeld/> - the farbfeld specification
18
19use std::i64;
20use std::io::{self, Read, Seek, SeekFrom, Write};
21
22use crate::color::ColorType;
23use crate::error::{
24 DecodingError, ImageError, ImageResult, UnsupportedError, UnsupportedErrorKind,
25};
26use crate::image::{self, ImageDecoder, ImageDecoderRect, ImageEncoder, ImageFormat, Progress};
27
28/// farbfeld Reader
29pub struct FarbfeldReader<R: Read> {
30 width: u32,
31 height: u32,
32 inner: R,
33 /// Relative to the start of the pixel data
34 current_offset: u64,
35 cached_byte: Option<u8>,
36}
37
38impl<R: Read> FarbfeldReader<R> {
39 fn new(mut buffered_read: R) -> ImageResult<FarbfeldReader<R>> {
40 fn read_dimm<R: Read>(from: &mut R) -> ImageResult<u32> {
41 let mut buf = [0u8; 4];
42 from.read_exact(&mut buf).map_err(|err| {
43 ImageError::Decoding(DecodingError::new(ImageFormat::Farbfeld.into(), err))
44 })?;
45 Ok(u32::from_be_bytes(buf))
46 }
47
48 let mut magic = [0u8; 8];
49 buffered_read.read_exact(&mut magic).map_err(|err| {
50 ImageError::Decoding(DecodingError::new(ImageFormat::Farbfeld.into(), err))
51 })?;
52 if &magic != b"farbfeld" {
53 return Err(ImageError::Decoding(DecodingError::new(
54 ImageFormat::Farbfeld.into(),
55 format!("Invalid magic: {:02x?}", magic),
56 )));
57 }
58
59 let reader = FarbfeldReader {
60 width: read_dimm(&mut buffered_read)?,
61 height: read_dimm(&mut buffered_read)?,
62 inner: buffered_read,
63 current_offset: 0,
64 cached_byte: None,
65 };
66
67 if crate::utils::check_dimension_overflow(
68 reader.width,
69 reader.height,
70 // ColorType is always rgba16
71 ColorType::Rgba16.bytes_per_pixel(),
72 ) {
73 return Err(ImageError::Unsupported(
74 UnsupportedError::from_format_and_kind(
75 ImageFormat::Farbfeld.into(),
76 UnsupportedErrorKind::GenericFeature(format!(
77 "Image dimensions ({}x{}) are too large",
78 reader.width, reader.height
79 )),
80 ),
81 ));
82 }
83
84 Ok(reader)
85 }
86}
87
88impl<R: Read> Read for FarbfeldReader<R> {
89 fn read(&mut self, mut buf: &mut [u8]) -> io::Result<usize> {
90 let mut bytes_written = 0;
91 if let Some(byte) = self.cached_byte.take() {
92 buf[0] = byte;
93 buf = &mut buf[1..];
94 bytes_written = 1;
95 self.current_offset += 1;
96 }
97
98 if buf.len() == 1 {
99 buf[0] = cache_byte(&mut self.inner, &mut self.cached_byte)?;
100 bytes_written += 1;
101 self.current_offset += 1;
102 } else {
103 for channel_out in buf.chunks_exact_mut(2) {
104 consume_channel(&mut self.inner, channel_out)?;
105 bytes_written += 2;
106 self.current_offset += 2;
107 }
108 }
109
110 Ok(bytes_written)
111 }
112}
113
114impl<R: Read + Seek> Seek for FarbfeldReader<R> {
115 fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
116 fn parse_offset(original_offset: u64, end_offset: u64, pos: SeekFrom) -> Option<i64> {
117 match pos {
118 SeekFrom::Start(off) => i64::try_from(off)
119 .ok()?
120 .checked_sub(i64::try_from(original_offset).ok()?),
121 SeekFrom::End(off) => {
122 if off < i64::try_from(end_offset).unwrap_or(i64::MAX) {
123 None
124 } else {
125 Some(i64::try_from(end_offset.checked_sub(original_offset)?).ok()? + off)
126 }
127 }
128 SeekFrom::Current(off) => {
129 if off < i64::try_from(original_offset).unwrap_or(i64::MAX) {
130 None
131 } else {
132 Some(off)
133 }
134 }
135 }
136 }
137
138 let original_offset = self.current_offset;
139 let end_offset = self.width as u64 * self.height as u64 * 2;
140 let offset_from_current =
141 parse_offset(original_offset, end_offset, pos).ok_or_else(|| {
142 io::Error::new(
143 io::ErrorKind::InvalidInput,
144 "invalid seek to a negative or overflowing position",
145 )
146 })?;
147
148 // TODO: convert to seek_relative() once that gets stabilised
149 self.inner.seek(SeekFrom::Current(offset_from_current))?;
150 self.current_offset = if offset_from_current < 0 {
151 original_offset.checked_sub(offset_from_current.wrapping_neg() as u64)
152 } else {
153 original_offset.checked_add(offset_from_current as u64)
154 }
155 .expect("This should've been checked above");
156
157 if self.current_offset < end_offset && self.current_offset % 2 == 1 {
158 let curr = self.inner.seek(SeekFrom::Current(-1))?;
159 cache_byte(&mut self.inner, &mut self.cached_byte)?;
160 self.inner.seek(SeekFrom::Start(curr))?;
161 } else {
162 self.cached_byte = None;
163 }
164
165 Ok(original_offset)
166 }
167}
168
169fn consume_channel<R: Read>(from: &mut R, mut to: &mut [u8]) -> io::Result<()> {
170 let mut ibuf: [u8; 2] = [0u8; 2];
171 from.read_exact(&mut ibuf)?;
172 to.write_all(&u16::from_be_bytes(ibuf).to_ne_bytes())?;
173
174 Ok(())
175}
176
177fn cache_byte<R: Read>(from: &mut R, cached_byte: &mut Option<u8>) -> io::Result<u8> {
178 let mut obuf: [u8; 2] = [0u8; 2];
179 consume_channel(from, &mut obuf)?;
180 *cached_byte = Some(obuf[1]);
181 Ok(obuf[0])
182}
183
184/// farbfeld decoder
185pub struct FarbfeldDecoder<R: Read> {
186 reader: FarbfeldReader<R>,
187}
188
189impl<R: Read> FarbfeldDecoder<R> {
190 /// Creates a new decoder that decodes from the stream ```r```
191 pub fn new(buffered_read: R) -> ImageResult<FarbfeldDecoder<R>> {
192 Ok(FarbfeldDecoder {
193 reader: FarbfeldReader::new(buffered_read)?,
194 })
195 }
196}
197
198impl<'a, R: 'a + Read> ImageDecoder<'a> for FarbfeldDecoder<R> {
199 type Reader = FarbfeldReader<R>;
200
201 fn dimensions(&self) -> (u32, u32) {
202 (self.reader.width, self.reader.height)
203 }
204
205 fn color_type(&self) -> ColorType {
206 ColorType::Rgba16
207 }
208
209 fn into_reader(self) -> ImageResult<Self::Reader> {
210 Ok(self.reader)
211 }
212
213 fn scanline_bytes(&self) -> u64 {
214 2
215 }
216}
217
218impl<'a, R: 'a + Read + Seek> ImageDecoderRect<'a> for FarbfeldDecoder<R> {
219 fn read_rect_with_progress<F: Fn(Progress)>(
220 &mut self,
221 x: u32,
222 y: u32,
223 width: u32,
224 height: u32,
225 buf: &mut [u8],
226 progress_callback: F,
227 ) -> ImageResult<()> {
228 // A "scanline" (defined as "shortest non-caching read" in the doc) is just one channel in this case
229
230 let start = self.reader.stream_position()?;
231 image::load_rect(
232 x,
233 y,
234 width,
235 height,
236 buf,
237 progress_callback,
238 self,
239 |s, scanline| s.reader.seek(SeekFrom::Start(scanline * 2)).map(|_| ()),
240 |s, buf| s.reader.read_exact(buf),
241 )?;
242 self.reader.seek(SeekFrom::Start(start))?;
243 Ok(())
244 }
245}
246
247/// farbfeld encoder
248pub struct FarbfeldEncoder<W: Write> {
249 w: W,
250}
251
252impl<W: Write> FarbfeldEncoder<W> {
253 /// Create a new encoder that writes its output to ```w```. The writer should be buffered.
254 pub fn new(buffered_writer: W) -> FarbfeldEncoder<W> {
255 FarbfeldEncoder { w: buffered_writer }
256 }
257
258 /// Encodes the image `data` (native endian) that has dimensions `width` and `height`.
259 ///
260 /// # Panics
261 ///
262 /// Panics if `width * height * 8 != data.len()`.
263 #[track_caller]
264 pub fn encode(self, data: &[u8], width: u32, height: u32) -> ImageResult<()> {
265 let expected_buffer_len = (width as u64 * height as u64).saturating_mul(8);
266 assert_eq!(
267 expected_buffer_len,
268 data.len() as u64,
269 "Invalid buffer length: expected {expected_buffer_len} got {} for {width}x{height} image",
270 data.len(),
271 );
272 self.encode_impl(data, width, height)?;
273 Ok(())
274 }
275
276 fn encode_impl(mut self, data: &[u8], width: u32, height: u32) -> io::Result<()> {
277 self.w.write_all(b"farbfeld")?;
278
279 self.w.write_all(&width.to_be_bytes())?;
280 self.w.write_all(&height.to_be_bytes())?;
281
282 for channel in data.chunks_exact(2) {
283 self.w
284 .write_all(&u16::from_ne_bytes(channel.try_into().unwrap()).to_be_bytes())?;
285 }
286
287 Ok(())
288 }
289}
290
291impl<W: Write> ImageEncoder for FarbfeldEncoder<W> {
292 #[track_caller]
293 fn write_image(
294 self,
295 buf: &[u8],
296 width: u32,
297 height: u32,
298 color_type: ColorType,
299 ) -> ImageResult<()> {
300 if color_type != ColorType::Rgba16 {
301 return Err(ImageError::Unsupported(
302 UnsupportedError::from_format_and_kind(
303 format:ImageFormat::Farbfeld.into(),
304 kind:UnsupportedErrorKind::Color(color_type.into()),
305 ),
306 ));
307 }
308
309 self.encode(data:buf, width, height)
310 }
311}
312
313#[cfg(test)]
314mod tests {
315 use crate::codecs::farbfeld::FarbfeldDecoder;
316 use crate::ImageDecoderRect;
317 use byteorder::{ByteOrder, NativeEndian};
318 use std::io::{Cursor, Seek, SeekFrom};
319
320 static RECTANGLE_IN: &[u8] = b"farbfeld\
321 \x00\x00\x00\x02\x00\x00\x00\x03\
322 \xFF\x01\xFE\x02\xFD\x03\xFC\x04\xFB\x05\xFA\x06\xF9\x07\xF8\x08\
323 \xF7\x09\xF6\x0A\xF5\x0B\xF4\x0C\xF3\x0D\xF2\x0E\xF1\x0F\xF0\x10\
324 \xEF\x11\xEE\x12\xED\x13\xEC\x14\xEB\x15\xEA\x16\xE9\x17\xE8\x18";
325
326 #[test]
327 fn read_rect_1x2() {
328 static RECTANGLE_OUT: &[u16] = &[
329 0xF30D, 0xF20E, 0xF10F, 0xF010, 0xEB15, 0xEA16, 0xE917, 0xE818,
330 ];
331
332 read_rect(1, 1, 1, 2, RECTANGLE_OUT);
333 }
334
335 #[test]
336 fn read_rect_2x2() {
337 static RECTANGLE_OUT: &[u16] = &[
338 0xFF01, 0xFE02, 0xFD03, 0xFC04, 0xFB05, 0xFA06, 0xF907, 0xF808, 0xF709, 0xF60A, 0xF50B,
339 0xF40C, 0xF30D, 0xF20E, 0xF10F, 0xF010,
340 ];
341
342 read_rect(0, 0, 2, 2, RECTANGLE_OUT);
343 }
344
345 #[test]
346 fn read_rect_2x1() {
347 static RECTANGLE_OUT: &[u16] = &[
348 0xEF11, 0xEE12, 0xED13, 0xEC14, 0xEB15, 0xEA16, 0xE917, 0xE818,
349 ];
350
351 read_rect(0, 2, 2, 1, RECTANGLE_OUT);
352 }
353
354 #[test]
355 fn read_rect_2x3() {
356 static RECTANGLE_OUT: &[u16] = &[
357 0xFF01, 0xFE02, 0xFD03, 0xFC04, 0xFB05, 0xFA06, 0xF907, 0xF808, 0xF709, 0xF60A, 0xF50B,
358 0xF40C, 0xF30D, 0xF20E, 0xF10F, 0xF010, 0xEF11, 0xEE12, 0xED13, 0xEC14, 0xEB15, 0xEA16,
359 0xE917, 0xE818,
360 ];
361
362 read_rect(0, 0, 2, 3, RECTANGLE_OUT);
363 }
364
365 #[test]
366 fn read_rect_in_stream() {
367 static RECTANGLE_OUT: &[u16] = &[0xEF11, 0xEE12, 0xED13, 0xEC14];
368
369 let mut input = vec![];
370 input.extend_from_slice(b"This is a 31-byte-long prologue");
371 input.extend_from_slice(RECTANGLE_IN);
372 let mut input_cur = Cursor::new(input);
373 input_cur.seek(SeekFrom::Start(31)).unwrap();
374
375 let mut out_buf = [0u8; 64];
376 FarbfeldDecoder::new(input_cur)
377 .unwrap()
378 .read_rect(0, 2, 1, 1, &mut out_buf)
379 .unwrap();
380 let exp = degenerate_pixels(RECTANGLE_OUT);
381 assert_eq!(&out_buf[..exp.len()], &exp[..]);
382 }
383
384 #[test]
385 fn dimension_overflow() {
386 let header = b"farbfeld\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF";
387
388 assert!(FarbfeldDecoder::new(Cursor::new(header)).is_err());
389 }
390
391 fn read_rect(x: u32, y: u32, width: u32, height: u32, exp_wide: &[u16]) {
392 let mut out_buf = [0u8; 64];
393 FarbfeldDecoder::new(Cursor::new(RECTANGLE_IN))
394 .unwrap()
395 .read_rect(x, y, width, height, &mut out_buf)
396 .unwrap();
397 let exp = degenerate_pixels(exp_wide);
398 assert_eq!(&out_buf[..exp.len()], &exp[..]);
399 }
400
401 fn degenerate_pixels(exp_wide: &[u16]) -> Vec<u8> {
402 let mut exp = vec![0u8; exp_wide.len() * 2];
403 NativeEndian::write_u16_into(exp_wide, &mut exp);
404 exp
405 }
406}
407