From 3b31caf52cec07634319ce7ee1c41e2306f8adc9 Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sat, 16 Nov 2024 21:59:58 +0000 Subject: [PATCH 01/18] migrate doccomments in common.swift --- Sources/JPEG/common.swift | 142 +++++++++++------------------- Sources/JPEG/docs.docc/General.md | 13 +++ 2 files changed, 65 insertions(+), 90 deletions(-) create mode 100644 Sources/JPEG/docs.docc/General.md diff --git a/Sources/JPEG/common.swift b/Sources/JPEG/common.swift index fe2f6bbd..ff91369d 100644 --- a/Sources/JPEG/common.swift +++ b/Sources/JPEG/common.swift @@ -2,12 +2,7 @@ License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/. */ -/// enum General -/// A namespace for general functionality. -/// # [Range types](general-range-types) -/// # [Integer storage](general-storage-types) -/// # [See also](top-level-namespaces) -/// ## (1:top-level-namespaces) +/// A namespace for general functionality. public enum General { @@ -15,54 +10,43 @@ enum General extension General { - /// struct General.Storage - /// where I:Swift.FixedWidthInteger & Swift.BinaryInteger - /// @propertyWrapper - /// A property wrapper providing an immutable [`Swift.Int`] interface backed - /// by a different integer type. - /// # [See also](general-storage-types) - /// ## (general-storage-types) + /// A property wrapper providing an immutable [`Swift.Int`] interface backed + /// by a different integer type. @propertyWrapper public struct Storage where I:FixedWidthInteger & BinaryInteger { private var storage:I - /// init General.Storage.init(wrappedValue:) - /// Creates an instance of this property wrapper, with the given value - /// truncated to the width of the storage type [`I`]. - /// - wrappedValue : Swift.Int + /// Creates an instance of this property wrapper, with the given value + /// truncated to the width of the storage type [`I`]. + /// + /// - Parameter wrappedValue: /// The value to wrap. public init(wrappedValue:Int) { self.storage = .init(truncatingIfNeeded: wrappedValue) } - /// var General.Storage.wrappedValue : Swift.Int { get } - /// The value wrapped by this property wrapper, expanded to an [`Swift.Int`]. + /// The value wrapped by this property wrapper, expanded to an [`Swift.Int`]. public var wrappedValue:Int { .init(self.storage) } } - /// struct General.Storage2 - /// where I:Swift.FixedWidthInteger & Swift.BinaryInteger - /// @propertyWrapper - /// A property wrapper providing an immutable `(`[`Swift.Int`]`, `[`Swift.Int`]`)` - /// interface backed by a different integer type. - /// # [See also](general-storage-types) - /// ## (general-storage-types) + /// A property wrapper providing an immutable `(`[`Swift.Int`]`, `[`Swift.Int`]`)` + /// interface backed by a different integer type. @propertyWrapper public struct Storage2 where I:FixedWidthInteger & BinaryInteger { private var storage:(x:I, y:I) - /// init General.Storage2.init(wrappedValue:) - /// Creates an instance of this property wrapper, with the given values - /// truncated to the width of the storage type [`I`]. - /// - wrappedValue : (x:Swift.Int, y:Swift.Int) + /// Creates an instance of this property wrapper, with the given values + /// truncated to the width of the storage type [`I`]. + /// + /// - Parameter wrappedValue: /// The values to wrap. public init(wrappedValue:(x:Int, y:Int)) @@ -73,40 +57,33 @@ extension General .init(truncatingIfNeeded: wrappedValue.y) ) } - /// var General.Storage2.wrappedValue : Swift.Int { get } - /// The values wrapped by this property wrapper, expanded to an - /// `(`[`Swift.Int`]`, `[`Swift.Int`]`)` tuple. + /// The values wrapped by this property wrapper, expanded to an + /// `(`[`Swift.Int`]`, `[`Swift.Int`]`)` tuple. public var wrappedValue:(x:Int, y:Int) { (.init(self.storage.x), .init(self.storage.y)) } } - /// struct General.MutableStorage - /// where I:Swift.FixedWidthInteger & Swift.BinaryInteger - /// @propertyWrapper - /// A property wrapper providing a mutable [`Swift.Int`] interface backed - /// by a different integer type. - /// # [See also](general-storage-types) - /// ## (general-storage-types) + /// A property wrapper providing a mutable [`Swift.Int`] interface backed + /// by a different integer type. @propertyWrapper public struct MutableStorage where I:FixedWidthInteger & BinaryInteger { private var storage:I - /// init General.MutableStorage.init(wrappedValue:) - /// Creates an instance of this property wrapper, with the given value - /// truncated to the width of the storage type [`I`]. - /// - wrappedValue : Swift.Int + /// Creates an instance of this property wrapper, with the given value + /// truncated to the width of the storage type [`I`]. + /// + /// - Parameter wrappedValue: /// The value to wrap. public init(wrappedValue:Int) { self.storage = .init(truncatingIfNeeded: wrappedValue) } - /// var General.MutableStorage.wrappedValue : Swift.Int { get set } - /// The value wrapped by this property wrapper, expanded to an [`Swift.Int`]. + /// The value wrapped by this property wrapper, expanded to an [`Swift.Int`]. public var wrappedValue:Int { @@ -305,11 +282,7 @@ extension General.Heap:ExpressibleByArrayLiteral // 2d iterators extension General { - /// struct General.Range2 - /// where Bound:Swift.Comparable - /// : Swift.Sequence where Bound:Swift.Strideable, Bound.Stride:Swift.SignedInteger - /// A two-dimensional open range. - /// ## (general-range-types) + /// A two-dimensional open range. public struct Range2 where Bound:Comparable { @@ -335,16 +308,10 @@ func ..< (lhs:(x:Bound, y:Bound), rhs:(x:Bound, y:Bound)) -> General.Rang extension General.Range2:Sequence where Bound:Strideable, Bound.Stride:SignedInteger { - /// typealias General.Range2.Element = (x:Bound, y:Bound) - /// ?: Swift.Sequence where Bound:Swift.Strideable, Bound.Stride:Swift.SignedInteger public typealias Element = (x:Bound, y:Bound) - /// struct General.Range2.Iterator - /// ?: Swift.Sequence where Bound:Swift.Strideable, Bound.Stride:Swift.SignedInteger - /// : Swift.IteratorProtocol - /// A two-dimensional range iterator. - /// ## (general-range-types) + /// A two-dimensional range iterator. public struct Iterator { @@ -353,16 +320,12 @@ extension General.Range2:Sequence where Bound:Strideable, Bound.Stride:SignedInt let bound:(x:(Bound, Bound), y:Bound) } - /// func General.Range2.makeIterator() - /// ?: Swift.Sequence where Bound:Swift.Strideable, Bound.Stride:Swift.SignedInteger - /// Creates an iterator for this range instance. + /// Creates an iterator for this range instance. /// - /// This iterator will traverse the range space in row-major order. For - /// example, if the bounds are `(x: 0, y: 0)` and `(x: 2, y: 2)`, the iterator - /// will yield the elements `(x: 0, y: 0)`, `(x: 1, y: 0)`, `(x: 0, y: 1)`, - /// and `(x: 1, y: 1)`, in that order. - /// - -> : Iterator - /// An iterator. + /// This iterator will traverse the range space in row-major order. For + /// example, if the bounds are `(x: 0, y: 0)` and `(x: 2, y: 2)`, the iterator + /// will yield the elements `(x: 0, y: 0)`, `(x: 1, y: 0)`, `(x: 0, y: 1)`, + /// and `(x: 1, y: 1)`, in that order. public func makeIterator() -> Iterator { @@ -372,10 +335,9 @@ extension General.Range2:Sequence where Bound:Strideable, Bound.Stride:SignedInt } extension General.Range2.Iterator:IteratorProtocol { - /// mutating func General.Range2.Iterator.next() - /// ?: Swift.IteratorProtocol - /// Advances to the next element and returns it, or `nil` if no next element exists. - /// - -> : (x:Bound, y:Bound)? + /// Advances to the next element and returns it, or `nil` if no next element exists. + /// + /// - Returns: /// The next element in the two-dimensional range sequence, if it exists, /// otherwise `nil`. If advancing the `x` index would cause it to reach its /// upper bound, this iterator will advance to the next `y` index and reset @@ -412,12 +374,12 @@ extension General.Range2.Iterator:IteratorProtocol // raw buffer utilities extension ArraySlice where Element == UInt8 { - // Loads this array slice as a misaligned big-endian integer value, - // and casts it to a desired format. - // - Parameters: - // - bigEndian: The size and type to interpret this array slice as. - // - type: The type to cast the read integer value to. - // - Returns: The read integer value, cast to `U`. + /// Loads this array slice as a misaligned big-endian integer value, + /// and casts it to a desired format. + /// - Parameters: + /// - bigEndian: The size and type to interpret this array slice as. + /// - type: The type to cast the read integer value to. + /// - Returns: The read integer value, cast to `U`. func load(bigEndian:T.Type, as type:U.Type) -> U where T:FixedWidthInteger, U:BinaryInteger { @@ -447,13 +409,13 @@ extension ArraySlice where Element == UInt8 } extension Array where Element == UInt8 { - // Loads a misaligned big-endian integer value from the given byte offset - // and casts it to a desired format. - // - Parameters: - // - bigEndian: The size and type to interpret the data to load as. - // - type: The type to cast the read integer value to. - // - byte: The byte offset to load the big-endian integer from. - // - Returns: The read integer value, cast to `U`. + /// Loads a misaligned big-endian integer value from the given byte offset + /// and casts it to a desired format. + /// - Parameters: + /// - bigEndian: The size and type to interpret the data to load as. + /// - type: The type to cast the read integer value to. + /// - byte: The byte offset to load the big-endian integer from. + /// - Returns: The read integer value, cast to `U`. func load(bigEndian:T.Type, as type:U.Type, at byte:Int) -> U where T:FixedWidthInteger, U:BinaryInteger { @@ -463,12 +425,12 @@ extension Array where Element == UInt8 extension Array where Element == UInt8 { - // Decomposes the given integer value into its constituent bytes, in big-endian order. - // - Parameters: - // - value: The integer value to decompose. - // - type: The big-endian format `T` to store the given `value` as. The given - // `value` is truncated to fit in a `T`. - // - Returns: An array containing the bytes of the given `value`, in big-endian order. + /// Decomposes the given integer value into its constituent bytes, in big-endian order. + /// - Parameters: + /// - value: The integer value to decompose. + /// - type: The big-endian format `T` to store the given `value` as. The given + /// `value` is truncated to fit in a `T`. + /// - Returns: An array containing the bytes of the given `value`, in big-endian order. static func store(_ value:U, asBigEndian type:T.Type) -> [UInt8] where U:BinaryInteger, T:FixedWidthInteger diff --git a/Sources/JPEG/docs.docc/General.md b/Sources/JPEG/docs.docc/General.md new file mode 100644 index 00000000..6b856f31 --- /dev/null +++ b/Sources/JPEG/docs.docc/General.md @@ -0,0 +1,13 @@ +# ``General`` + +## Topics + +### Range types + +- ``General.Range2`` + +### Integer storage + +- ``General.Storage`` +- ``General.Storage2`` +- ``General.MutableStorage`` From 7aa66308427034ced37eeab1318ce88ef81bdca5 Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sat, 16 Nov 2024 22:01:42 +0000 Subject: [PATCH 02/18] debug.swift --- Sources/JPEG/debug.swift | 7 ------- 1 file changed, 7 deletions(-) diff --git a/Sources/JPEG/debug.swift b/Sources/JPEG/debug.swift index fbec7dbd..016fd243 100644 --- a/Sources/JPEG/debug.swift +++ b/Sources/JPEG/debug.swift @@ -2,12 +2,8 @@ License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/. */ -// literal forms extension JPEG.Component.Key:ExpressibleByIntegerLiteral { - /// init JPEG.Component.Key.init(integerLiteral:) - /// ?: Swift.ExpressibleByIntegerLiteral - /// - integerLiteral : Swift.UInt8 public init(integerLiteral:UInt8) { @@ -16,9 +12,6 @@ extension JPEG.Component.Key:ExpressibleByIntegerLiteral } extension JPEG.Table.Quantization.Key:ExpressibleByIntegerLiteral { - /// init JPEG.Table.Quantization.Key.init(integerLiteral:) - /// ?: Swift.ExpressibleByIntegerLiteral - /// - integerLiteral : Swift.Int public init(integerLiteral:Int) { From 0c1262c4bea8f90da5ea1109f7dba36ef60477dc Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sat, 16 Nov 2024 22:58:33 +0000 Subject: [PATCH 03/18] partially migrate doccomments in decode.swift --- Sources/JPEG/decode.swift | 995 ++++++++---------- Sources/JPEG/docs.docc/JPEG.Data.Planar.md | 39 + .../JPEG/docs.docc/JPEG.Data.Rectangular.md | 37 + Sources/JPEG/docs.docc/JPEG.Data.Spectral.md | 47 + Sources/JPEG/docs.docc/JPEG.md | 95 ++ Sources/JPEG/encode.swift | 18 - Sources/JPEG/error.swift | 20 - Sources/JPEG/jpeg.swift | 51 - Sources/JPEG/metadata.swift | 4 - Sources/JPEGSystem/os.swift | 12 - 10 files changed, 636 insertions(+), 682 deletions(-) create mode 100644 Sources/JPEG/docs.docc/JPEG.Data.Planar.md create mode 100644 Sources/JPEG/docs.docc/JPEG.Data.Rectangular.md create mode 100644 Sources/JPEG/docs.docc/JPEG.Data.Spectral.md create mode 100644 Sources/JPEG/docs.docc/JPEG.md diff --git a/Sources/JPEG/decode.swift b/Sources/JPEG/decode.swift index 2f141af9..8faa2993 100644 --- a/Sources/JPEG/decode.swift +++ b/Sources/JPEG/decode.swift @@ -4,30 +4,26 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/. */ // binary utilities -/// protocol JPEG.Bytestream.Source -/// A source bytestream. +/// A source bytestream. /// -/// To implement a custom data source type, conform it to this protocol by -/// implementing [`(Source).read(count:)`]. It can -/// then be used with the library’s core decompression interfaces. -/// # [See also](file-io-protocols) -/// ## (1:file-io-protocols) -/// ## (1:lexing-and-formatting) +/// To implement a custom data source type, conform it to this protocol by +/// implementing [`(Source).read(count:)`]. It can +/// then be used with the library’s core decompression interfaces. public protocol _JPEGBytestreamSource { - /// mutating func JPEG.Bytestream.Source.read(count:) - /// required - /// Attempts to read and return the given number of bytes from this stream. + /// Attempts to read and return the given number of bytes from this stream. /// - /// A successful call to this function should affect the bytestream state - /// such that subsequent calls should pick up where the last call left off. + /// A successful call to this function should affect the bytestream state + /// such that subsequent calls should pick up where the last call left off. /// - /// The rest of the library interprets a `nil` return value from this function - /// as indicating end-of-stream. - /// - count : Swift.Int + /// The rest of the library interprets a `nil` return value from this function + /// as indicating end-of-stream. + /// + /// - Parameter count: /// The number of bytes to read. - /// - -> : [Swift.UInt8]? + /// + /// - Returns: /// The `count` bytes read, or `nil` if the read attempt failed. This /// method should return `nil` even if any number of bytes less than `count` /// were successfully read. @@ -36,11 +32,7 @@ protocol _JPEGBytestreamSource } extension JPEG { - /// enum JPEG.Bytestream - /// A namespace for bytestream utilities. - /// # [File IO](file-io-protocols) - /// ## (0:file-io-protocols) - /// ## (0:lexing-and-formatting) + /// A namespace for bytestream utilities. public enum Bytestream { @@ -88,18 +80,17 @@ extension JPEG.Bytestream.Source return data } } - /// mutating func JPEG.Bytestream.Source.segment() - /// throws - /// Lexes a single marker segment from this bytestream, assuming there - /// is no entropy-coded data prefixed to it. + /// Lexes a single marker segment from this bytestream, assuming there + /// is no entropy-coded data prefixed to it. /// - /// Calling this function is roughly equivalent to calling [`segment(prefix:)`] - /// with the `prefix` parameter set to `false`, except that the empty - /// prefix array is omitted from the return value. + /// Calling this function is roughly equivalent to calling [`segment(prefix:)`] + /// with the `prefix` parameter set to `false`, except that the empty + /// prefix array is omitted from the return value. /// - /// This function can throw a [`(JPEG).LexingError`] if it encounters an - /// unexpected end-of-stream. - /// - -> : (JPEG.Marker, [Swift.UInt8]) + /// This function can throw a [`(JPEG).LexingError`] if it encounters an + /// unexpected end-of-stream. + /// + /// - Returns: /// A tuple containing the marker segment type and the marker segment data. /// The data array does *not* include the marker segment length field /// from the segment header. @@ -108,19 +99,19 @@ extension JPEG.Bytestream.Source { try self.segment(prefix: false).1 } - /// mutating func JPEG.Bytestream.Source.segment(prefix:) - /// throws - /// Optionally lexes a single entropy-coded segment followed by a single marker - /// segment from this bytestream. + /// Optionally lexes a single entropy-coded segment followed by a single marker + /// segment from this bytestream. /// - /// This function can throw a [`(JPEG).LexingError`] if it encounters an - /// unexpected end-of-stream. - /// - prefix : Swift.Bool + /// This function can throw a [`(JPEG).LexingError`] if it encounters an + /// unexpected end-of-stream. + /// + /// - Parameter prefix: /// Whether this function should expect an entropy-coded segment prefixed /// to the marker segment. If this parameter is set to `false`, and this /// function encounters a prefixed entropy-coded segment, it will throw /// a [`(JPEG).LexingError`]. - /// - -> : ([Swift.UInt8], (JPEG.Marker, [Swift.UInt8])) + /// + /// - Returns: /// A tuple containing the entropy-coded segment, marker segment type, /// and the marker segment data, in that order. If `prefix` was false, /// the entropy-coded segment data array will be empty. @@ -192,23 +183,16 @@ extension JPEG.Bytestream.Source // parsing -/// protocol JPEG.Bitstream.AnySymbol -/// : Swift.Hashable -/// Functionality common to all bitstream symbols. -/// # [Symbol types](entropy-coding-symbols) -/// ## (3:entropy-coding-symbols) -/// ## (4:entropy-coding) +/// Functionality common to all bitstream symbols. public protocol _JPEGBitstreamAnySymbol:Hashable { - /// init JPEG.Bitstream.AnySymbol.init(_:) - /// required - /// Creates a symbol instance. - /// - _ : Swift.UInt8 - /// The byte value of this symbol. - init(_:UInt8) - /// var JPEG.Bitstream.AnySymbol.value:Swift.UInt8 { get } + /// Creates a symbol instance. + /// + /// - Parameter value: /// The byte value of this symbol. + init(_ value:UInt8) + /// The byte value of this symbol. var value:UInt8 { get @@ -218,32 +202,19 @@ extension JPEG.Bitstream { public typealias AnySymbol = _JPEGBitstreamAnySymbol - /// enum JPEG.Bitstream.Symbol - /// A namespace for bitstream symbol types. - /// # [Symbol types](entropy-coding-symbols) - /// ## (0:entropy-coding-symbols) - /// ## (1:entropy-coding) + /// A namespace for bitstream symbol types. public enum Symbol { - /// enum JPEG.Bitstream.Symbol.DC - /// : JPEG.Bitstream.AnySymbol - /// A DC symbol. - /// # [See also](entropy-coding-symbols) - /// ## (1:entropy-coding-symbols) - /// ## (2:entropy-coding) + /// A DC symbol. public struct DC:AnySymbol { - /// let JPEG.Bitstream.Symbol.DC.value:Swift.UInt8 - /// ?: JPEG.Bitstream.AnySymbol - /// The raw byte value of this symbol. + /// The raw byte value of this symbol. public let value:UInt8 - /// init JPEG.Bitstream.Symbol.DC.init(_:) - /// ?: JPEG.Bitstream.AnySymbol - /// Creates a DC symbol instance. - /// - value : Swift.UInt8 + /// Creates a DC symbol instance. + /// - Parameter value: /// The raw byte value of this symbol. public init(_ value:UInt8) @@ -251,24 +222,16 @@ extension JPEG.Bitstream self.value = value } } - /// enum JPEG.Bitstream.Symbol.AC - /// : JPEG.Bitstream.AnySymbol - /// An AC symbol. - /// # [See also](entropy-coding-symbols) - /// ## (2:entropy-coding-symbols) - /// ## (3:entropy-coding) + /// An AC symbol. public struct AC:AnySymbol { - /// let JPEG.Bitstream.Symbol.AC.value:Swift.UInt8 - /// ?: JPEG.Bitstream.AnySymbol - /// The raw byte value of this symbol. + /// The raw byte value of this symbol. public let value:UInt8 - /// init JPEG.Bitstream.Symbol.AC.init(_:) - /// ?: JPEG.Bitstream.AnySymbol - /// Creates an AC symbol instance. - /// - value : Swift.UInt8 + /// Creates an AC symbol instance. + /// + /// - Parameter value: /// The raw byte value of this symbol. public init(_ value:UInt8) @@ -380,26 +343,27 @@ extension JPEG.Table.Huffman self.init(symbols, target: target) } - /// init JPEG.Table.Huffman.init?(_:target:) - /// Creates a huffman tree from the given leaf nodes. - /// - /// This initializer determines the shape of the tree from the shape of - /// the leaf array input. It has no knowledge of symbol frequencies or - /// priority. To build an *optimal* huffman tree, use the [`init(frequencies:target:)`] - /// initializer. - /// - /// This initializer will return `nil` if the sizes of the given leaf arrays do not - /// describe a [full binary tree](https://en.wikipedia.org/wiki/Binary_tree#full). - /// (The last level is allowed to be incomplete.) - /// For example, the leaf counts (3,\ 0,\ 0,\ …\ ) are invalid because - /// no binary tree can have three leaf nodes in its first level. - /// - symbols : [[Symbol]] + /// Creates a huffman tree from the given leaf nodes. + /// + /// This initializer determines the shape of the tree from the shape of + /// the leaf array input. It has no knowledge of symbol frequencies or + /// priority. To build an *optimal* huffman tree, use the [`init(frequencies:target:)`] + /// initializer. + /// + /// This initializer will return `nil` if the sizes of the given leaf arrays do not + /// describe a [full binary tree](https://en.wikipedia.org/wiki/Binary_tree#full). + /// (The last level is allowed to be incomplete.) + /// For example, the leaf counts (3,\ 0,\ 0,\ …\ ) are invalid because + /// no binary tree can have three leaf nodes in its first level. + /// + /// - Parameter symbols: /// The leaf nodes in each level of the tree. The tree root is always /// assumed to be internal, so the 0th sub-array of this array should /// contain the leaves in the first level of the tree. This array must /// contain 16 sub-arrays, even if the deeper levels of the tree are /// empty, or this initializer will suffer a precondition failure. - /// - target : Selector + /// + /// - Parameter target: /// The table selector this huffman table is meant to be stored at. public init?(_ symbols:[[Symbol]], target:Selector) @@ -439,16 +403,18 @@ extension JPEG.Table.Quantization self.init(precision: .uint16, values: uint16, target: target) } } - /// init JPEG.Table.Quantization.init(precision:values:target:) - /// Creates a quantization table from the given quantum values. - /// - precision : Precision + /// Creates a quantization table from the given quantum values. + /// + /// - Parameter precision: /// The bit width of the integer type to encode the quanta as. - /// - values : [Swift.UInt16] + /// + /// - Parameter values: /// The quantum values, in zigzag order. This array must have exactly 64 /// elements. If the `precision` is [`(Precision).uint8`], all of the values /// must be within the range of a [`Swift.UInt8`]. Passing an invalid /// array will result in a precondition failure. - /// - target : Selector + /// + /// - Parameter target: /// The table selector this quantization table is meant to be stored at. public init(precision:Precision, values:[UInt16], target:Selector) @@ -462,15 +428,15 @@ extension JPEG.Table.Quantization } extension JPEG.Table { - /// static func JPEG.Table.parse(huffman:) - /// throws - /// Parses a [`(Marker).huffman`] segment into huffman tables. + /// Parses a [`(Marker).huffman`] segment into huffman tables. + /// + /// If the given data does not parse to valid huffman tables, this function + /// will throw a [`(JPEG).ParsingError`]. /// - /// If the given data does not parse to valid huffman tables, this function - /// will throw a [`(JPEG).ParsingError`]. - /// - data : [Swift.UInt8] + /// - Parameter data: /// The segment data to parse. - /// - -> : (dc:[HuffmanDC], ac:[HuffmanAC]) + /// + /// - Returns: /// The parsed DC and AC huffman tables. public static func parse(huffman data:[UInt8]) throws -> (dc:[HuffmanDC], ac:[HuffmanAC]) @@ -555,15 +521,15 @@ extension JPEG.Table return tables } - /// static func JPEG.Table.parse(quantization:) - /// throws - /// Parses a [`(Marker).quantization`] segment into huffman tables. + /// Parses a [`(Marker).quantization`] segment into huffman tables. /// - /// If the given data does not parse to valid quantization tables, this function - /// will throw a [`(JPEG).ParsingError`]. - /// - data : [Swift.UInt8] + /// If the given data does not parse to valid quantization tables, this function + /// will throw a [`(JPEG).ParsingError`]. + /// + /// - Parameter data: /// The segment data to parse. - /// - -> : [Quantization] + /// + /// - Returns: /// The parsed quantization tables. public static func parse(quantization data:[UInt8]) throws -> [Quantization] @@ -618,15 +584,15 @@ extension JPEG.Table // frame/scan header parsing extension JPEG.Header.HeightRedefinition { - /// static func JPEG.Header.HeightRedefinition.parse(_:) - /// throws - /// Parses a [`(Marker).height`] segment into a height redefinition. + /// Parses a [`(Marker).height`] segment into a height redefinition. + /// + /// If the given data does not parse to a valid height redefinition, + /// this function will throw a [`(JPEG).ParsingError`]. /// - /// If the given data does not parse to a valid height redefinition, - /// this function will throw a [`(JPEG).ParsingError`]. - /// - data : [Swift.UInt8] + /// - Parameter data: /// The segment data to parse. - /// - -> : Self + /// + /// - Returns: /// The parsed height redefinition. public static func parse(_ data:[UInt8]) throws -> Self @@ -642,15 +608,15 @@ extension JPEG.Header.HeightRedefinition } extension JPEG.Header.RestartInterval { - /// static func JPEG.Header.RestartInterval.parse(_:) - /// throws - /// Parses an [`(Marker).interval`] segment into a restart interval definition. + /// Parses an [`(Marker).interval`] segment into a restart interval definition. /// - /// If the given data does not parse to a valid restart interval definition, - /// this function will throw a [`(JPEG).ParsingError`]. - /// - data : [Swift.UInt8] + /// If the given data does not parse to a valid restart interval definition, + /// this function will throw a [`(JPEG).ParsingError`]. + /// + /// - Parameter data: /// The segment data to parse. - /// - -> : Self + /// + /// - Returns: /// The parsed restart definition. public static func parse(_ data:[UInt8]) throws -> Self @@ -667,35 +633,38 @@ extension JPEG.Header.RestartInterval } extension JPEG.Header.Frame { - /// static func JPEG.Header.Frame.validate(process:precision:size:components:) - /// throws - /// Creates a frame header after validating the given field values. + /// Creates a frame header after validating the given field values. + /// + /// If the given parameters are not consistent with one another, and the + /// [JPEG standard](https://www.w3.org/Graphics/JPEG/itu-t81.pdf), this + /// function will throw a [`(JPEG).ParsingError`], unless otherwise noted. /// - /// If the given parameters are not consistent with one another, and the - /// [JPEG standard](https://www.w3.org/Graphics/JPEG/itu-t81.pdf), this - /// function will throw a [`(JPEG).ParsingError`], unless otherwise noted. - /// - process : JPEG.Process + /// - Parameter process: /// The coding process used by the image. - /// - precision : Swift.Int + /// + /// - Parameter precision: /// The bit depth of the image. If the `process` is [`(JPEG.Process).baseline`], /// this parameter must be 8. If the `process` is [`(JPEG.Process).extended(coding:differential:)`] /// or [`(JPEG.Process).progressive(coding:differential:)`], this parameter /// must be either 8 or 12. If the process is [`(JPEG.Process).lossless(coding:differential:)`], /// this parameter must be within the interval `2 ... 16`. - /// - size : (x:Swift.Int, y:Swift.Int) + /// + /// - Parameter size: /// The size of the image, in pixels. Passing a negative height will result /// in a precondition failure. Passing a negative or zero width will result /// in a [`(JPEG).ParsingError`]. This constructor treats the two failure /// conditions differently because the latter one is the only one that can /// occur when parsing a frame header from input data. - /// - components: [JPEG.Component.Key: JPEG.Component] + /// + /// - Parameter components: /// The components in the image. This dictionary must have at least one /// element. If the `process` is [`(JPEG.Process).progressive(coding:differential:)`], /// it can have no more than four elements. The sampling factors of each /// component must be within the interval `1 ... 4` in both directions. /// if the `process` is [`(JPEG.Process).baseline`], the components can /// only use the quantization table selectors `\.0` and `\.1`. - /// - -> : Self + /// + /// - Returns: /// A frame header. public static func validate(process:JPEG.Process, precision:Int, size:(x:Int, y:Int), @@ -767,19 +736,20 @@ extension JPEG.Header.Frame return .init(process: process, precision: precision, size: size, components: components) } - /// static func JPEG.Header.Frame.parse(_:process:) - /// throws - /// Parses a [`(Marker).frame(_:)`] segment into a frame header. + /// Parses a [`(Marker).frame(_:)`] segment into a frame header. /// - /// If the given data does not parse to a valid frame header, - /// this function will throw a [`(JPEG).ParsingError`]. This function - /// invokes [`validate(process:precision:size:components:)`], so any errors - /// it can throw can also be thrown by this function. - /// - data : [Swift.UInt8] + /// If the given data does not parse to a valid frame header, + /// this function will throw a [`(JPEG).ParsingError`]. This function + /// invokes [`validate(process:precision:size:components:)`], so any errors + /// it can throw can also be thrown by this function. + /// + /// - Parameter data: /// The segment data to parse. - /// - process : JPEG.Process + /// + /// - Parameter process: /// The coding process used by the image. - /// - -> : Self + /// + /// - Returns: /// The parsed frame header. public static func parse(_ data:[UInt8], process:JPEG.Process) throws -> Self @@ -838,34 +808,37 @@ extension JPEG.Header.Frame } extension JPEG.Header.Scan { - /// static func JPEG.Header.Scan.validate(process:band:bits:components:) - /// throws - /// Creates a scan header after validating the given field values. + /// Creates a scan header after validating the given field values. + /// + /// If the given parameters are not consistent with one another, and the + /// [JPEG standard](https://www.w3.org/Graphics/JPEG/itu-t81.pdf), this + /// function will throw a [`(JPEG).ParsingError`]. /// - /// If the given parameters are not consistent with one another, and the - /// [JPEG standard](https://www.w3.org/Graphics/JPEG/itu-t81.pdf), this - /// function will throw a [`(JPEG).ParsingError`]. - /// - process : JPEG.Process + /// - Parameter process: /// The coding process used by the image. - /// - band : Swift.Range + /// + /// - Parameter band: /// The frequency band encoded by the scan, in zigzag order. It must be /// within the interval of 0 to 64. If the `process` is /// [`(Process).progressive(coding:differential:)`], this parameter must /// either be `0 ..< 1`, or some range within the interval `1 ..< 64`. /// Otherwise, this parameter must be set to `0 ..< 64`. - /// - bits : Swift.Range + /// + /// - Parameter bits: /// The bit range encoded by the scan, where bit zero is the least significant /// bit. The upper range bound must be either infinity ([`Swift.Int`max`]) /// or one greater than the lower bound. If the `process` is not /// [`(Process).progressive(coding:differential:)`], this value must /// be set to `0 ..< .max`. - /// - components: [JPEG.Scan.Component] + /// + /// - Parameter components: /// The color components in the scan, in the order in which their /// data units are interleaved. If the scan is an AC progressive scan, /// this array must have exactly one element. Otherwise, it must have /// between one and four elements. If the `process` is [`(Process).baseline`], /// the components can only use the huffman table selectors `\.0` and `\.1`. - /// - -> : Self + /// + /// - Returns: /// A scan header. public static func validate(process:JPEG.Process, @@ -929,19 +902,20 @@ extension JPEG.Header.Scan return .init(band: band, bits: bits, components: components) } - /// static func JPEG.Header.Scan.parse(_:process:) - /// throws - /// Parses a [`(Marker).scan`] segment into a scan header. + /// Parses a [`(Marker).scan`] segment into a scan header. + /// + /// If the given data does not parse to a valid scan header, + /// this function will throw a [`(JPEG).ParsingError`]. This function + /// invokes [`validate(process:band:bits:components:)`], so any errors + /// it can throw can also be thrown by this function. /// - /// If the given data does not parse to a valid scan header, - /// this function will throw a [`(JPEG).ParsingError`]. This function - /// invokes [`validate(process:band:bits:components:)`], so any errors - /// it can throw can also be thrown by this function. - /// - data : [Swift.UInt8] + /// - Parameter data: /// The segment data to parse. - /// - process : JPEG.Process + /// + /// - Parameter process: /// The coding process used by the image. - /// - -> : Self + /// + /// - Returns: /// The parsed scan header. public static func parse(_ data:[UInt8], process:JPEG.Process) throws -> Self @@ -1273,24 +1247,24 @@ extension JPEG.Table.Huffman.Decoder } extension JPEG.Table.Quantization { - /// static func JPEG.Table.Quantization.z(k:h:) - /// @inlinable - /// Converts a coefficient grid index to a zigzag index. + /// Converts a coefficient grid index to a zigzag index. /// - /// It is easier to convert grid indices (*k*,\ *h*) to zigzag indices (*z*) - /// than the other way around, so most library APIs store coefficient-related - /// information natively in zigzag order. + /// It is easier to convert grid indices (*k*,\ *h*) to zigzag indices (*z*) + /// than the other way around, so most library APIs store coefficient-related + /// information natively in zigzag order. /// - /// The JPEG format only uses the grid domain `0 ..< 8`\ ×\ `0 ..< 8`, which - /// maps to the zigzag range `0 ..< 64`. However, this function works for - /// any non-negative input coordinate. - /// - x : Swift.Int + /// The JPEG format only uses the grid domain `0 ..< 8`\ ×\ `0 ..< 8`, which + /// maps to the zigzag range `0 ..< 64`. However, this function works for + /// any non-negative input coordinate. + /// + /// - Parameter x: /// The horizontal frequency index. - /// - y : Swift.Int + /// + /// - Parameter y: /// The vertical frequency index. - /// - ->: Swift.Int + /// + /// - Returns: /// The corresponding zigzag index. - /// # [See also](quantization-table-subscripts) @inlinable public static func z(k x:Int, h y:Int) -> Int @@ -1304,20 +1278,19 @@ extension JPEG.Table.Quantization return a + b * t - q * x - (q ^ 1) * y - 1 } - /// subscript JPEG.Table.Quantization[k:h:] { get set } - /// @inlinable - /// Accesses the quantum value at the given grid index. + /// Accesses the quantum value at the given grid index. /// - /// Using this subscript is equivalent to using [`[z:]`] with the output - /// of [`z(k:h:)`]. - /// - k : Swift.Int + /// Using this subscript is equivalent to using [`[z:]`] with the output + /// of [`z(k:h:)`]. + /// + /// - Parameter k: /// The horizontal frequency index. This value must be in the range `0 ..< 8`. - /// - h : Swift.Int + /// + /// - Parameter k /// The vertical frequency index. This value must be in the range `0 ..< 8`. - /// - -> : Swift.UInt16 + /// + /// - Returns: /// The quantum value. - /// # [See also](quantization-table-subscripts) - /// ## (quantization-table-subscripts) @inlinable public subscript(k k:Int, h h:Int) -> UInt16 @@ -1331,14 +1304,13 @@ extension JPEG.Table.Quantization self[z: Self.z(k: k, h: h)] = value } } - /// subscript JPEG.Table.Quantization[z:] { get set } - /// Accesses the quantum value at the given zigzag index. - /// - z : Swift.Int + /// Accesses the quantum value at the given zigzag index. + /// + /// - Parameter z: /// The zigzag index. This value must be in the range `0 ..< 64`. - /// - -> : Swift.UInt16 + /// + /// - Returns: /// The quantum value. - /// # [See also](quantization-table-subscripts) - /// ## (quantization-table-subscripts) public subscript(z z:Int) -> UInt16 { @@ -1356,10 +1328,7 @@ extension JPEG.Table.Quantization // intermediate forms extension JPEG { - /// enum JPEG.Data - /// A namespace for image representation types. - /// # [Image representations](image-data-types) - /// ## (image-data-types-and-namespace) + /// A namespace for image representation types. public enum Data { @@ -1374,38 +1343,24 @@ extension JPEG.Data partial:Int = size % stride != 0 ? 1 : 0 return complete + partial } - /// struct JPEG.Data.Spectral - /// where Format:JPEG.Format - /// : Swift.RandomAccessCollection - /// A planar image represented in the frequency domain. - /// - /// A spectral image stores its data in blocks called *data units*. Each - /// block is a square 8×8 matrix of frequency coefficients. The data units - /// themselves have the same spatial arrangement they do in the spatial domain. - /// - /// A spectral image always stores a whole number of data units in both - /// dimensions, even if the image dimensions in pixels are not multiples of 8. - /// Because each component in an image has its own sampling factors, the - /// image planes may not have the same size. - /// - /// The spectral representation is a lossless representation. JPEG - /// images that have been decoded to this representation can be re-encoded - /// without loss of information or compression. - /// # [Creating an image](spectral-create-image) - /// # [Saving an image](spectral-save-image) - /// # [Querying an image](spectral-query-image) - /// # [Editing an image](spectral-edit-image) - /// # [Changing representations](spectral-change-representation) - /// # [Accessing planes](spectral-accessing-planes) - /// # [See also](image-data-types) - /// ## (image-data-types) - /// ## (image-data-types-and-namespace) + /// A planar image represented in the frequency domain. + /// + /// A spectral image stores its data in blocks called *data units*. Each + /// block is a square 8×8 matrix of frequency coefficients. The data units + /// themselves have the same spatial arrangement they do in the spatial domain. + /// + /// A spectral image always stores a whole number of data units in both + /// dimensions, even if the image dimensions in pixels are not multiples of 8. + /// Because each component in an image has its own sampling factors, the + /// image planes may not have the same size. + /// + /// The spectral representation is a lossless representation. JPEG + /// images that have been decoded to this representation can be re-encoded + /// without loss of information or compression. public struct Spectral where Format:JPEG.Format { - /// struct JPEG.Data.Spectral.Quanta - /// : Swift.RandomAccessCollection - /// A container for the quantization tables used by a spectral image. + /// A container for the quantization tables used by a spectral image. public struct Quanta { @@ -1413,24 +1368,20 @@ extension JPEG.Data var quanta:[JPEG.Table.Quantization], q:[JPEG.Table.Quantization.Key: Int] } - /// struct JPEG.Data.Spectral.Plane - /// A plane of an image in the frequency domain, containing one color channel. + /// A plane of an image in the frequency domain, containing one color channel. public struct Plane { - /// var JPEG.Data.Spectral.Plane.units : (x:Swift.Int, y:Swift.Int) { get } - /// The number of data units in this plane in the horizontal and - /// vertical directions. + /// The number of data units in this plane in the horizontal and + /// vertical directions. public internal(set) var units:(x:Int, y:Int) - /// var JPEG.Data.Spectral.Plane.factor : (x:Swift.Int, y:Swift.Int) { get } - /// @ : General.Storage2 - /// The sampling factors of the color component this plane stores. + /// The sampling factors of the color component this plane stores. /// - /// This property is backed by two [`Swift.Int16`]s to circumvent compiler - /// size limits for the `read` and `modify` accessors that the image - /// planes are subscriptable through. + /// This property is backed by two [`Swift.Int16`]s to circumvent compiler + /// size limits for the `read` and `modify` accessors that the image + /// planes are subscriptable through. @General.Storage2 public var factor:(x:Int, y:Int) @@ -1440,23 +1391,26 @@ extension JPEG.Data private var buffer:[Int16] - /// subscript JPEG.Data.Spectral.Plane[x:y:z:] { get set } - /// Accesses the frequency coefficient at the specified zigzag index - /// in the specified data unit. + /// Accesses the frequency coefficient at the specified zigzag index + /// in the specified data unit. + /// + /// The `x` and `y` indices of this subscript have no index bounds. + /// Out-of-bounds reads will return 0; out-of-bounds writes will + /// have no effect. The `z` index still has to be within the + /// correct range. /// - /// The `x` and `y` indices of this subscript have no index bounds. - /// Out-of-bounds reads will return 0; out-of-bounds writes will - /// have no effect. The `z` index still has to be within the - /// correct range. - /// - x : Swift.Int + /// - Parameter x: /// The horizontal index of the data unit to access. - /// - y : Swift.Int + /// + /// - Parameter y: /// The vertical index of the data unit to access. Index 0 /// corresponds to the visual top of the image. - /// - z : Swift.Int + /// + /// - Parameter z: /// The zigzag index of the coefficient to access. This index must /// be in the range `0 ..< 64`. - /// - ->: Swift.Int16 + /// + /// - Returns: /// The frequency coefficient. public subscript(x x:Int, y y:Int, z z:Int) -> Int16 @@ -1485,110 +1439,83 @@ extension JPEG.Data } } } - /// var JPEG.Data.Spectral.size : (x:Swift.Int, y:Swift.Int) { get } - /// The size of this image, in pixels. + /// The size of this image, in pixels. /// - /// In general, this size is not the same as the size of the image planes. - /// # [See also](spectral-query-image) - /// ## (0:spectral-query-image) + /// In general, this size is not the same as the size of the image planes. public private(set) - var size:(x:Int, y:Int), - /// var JPEG.Data.Spectral.blocks : (x:Swift.Int, y:Swift.Int) { get } - /// The number of minimum-coded units in this image, in the horizontal - /// and vertical directions. + var size:(x:Int, y:Int) + /// The number of minimum-coded units in this image, in the horizontal + /// and vertical directions. /// - /// The size of the minimum-coded unit, in 8×8 blocks of pixels, - /// is given by [`layout``(Layout).scale`]. - /// # [See also](spectral-query-image) - /// ## (1:spectral-query-image) - blocks:(x:Int, y:Int) - /// var JPEG.Data.Spectral.layout : JPEG.Layout { get } - /// The layout of this image. - /// # [See also](spectral-query-image) - /// ## (2:spectral-query-image) + /// The size of the minimum-coded unit, in 8×8 blocks of pixels, + /// is given by [`layout``(Layout).scale`]. + public private(set) + var blocks:(x:Int, y:Int) + /// The layout of this image. public private(set) var layout:JPEG.Layout - /// var JPEG.Data.Spectral.metadata : [JPEG.Metadata] - /// The metadata records in this image. - /// # [See also](spectral-query-image) - /// ## (4:spectral-query-image) + /// The metadata records in this image. public var metadata:[JPEG.Metadata] - /// var JPEG.Data.Spectral.quanta : Quanta { get } - /// The quantization tables used by this image. - /// # [See also](spectral-query-image) - /// ## (3:spectral-query-image) + /// The quantization tables used by this image. public private(set) var quanta:Quanta private var planes:[Plane] } - /// struct JPEG.Data.Planar - /// where Format:JPEG.Format - /// A planar image represented in the spatial domain. - /// - /// A planar image stores its data in blocks called *data units*. Each - /// block is an 8×8-pixel square. A planar image always stores a whole - /// number of data units in both dimensions, even if the image dimensions - /// in pixels are not multiples of 8. Because each component in an image - /// has its own sampling factors, the image planes may not have the same size. - /// - /// A planar image is the result of applying an *inverse discrete cosine - /// transformation* to a spectral image. It can be converted back into a spectral - /// image (with some floating point error) with a *forward discrete cosine - /// transformation*. - /// # [Creating an image](planar-create-image) - /// # [Saving an image](planar-save-image) - /// # [Querying an image](planar-query-image) - /// # [Changing representations](planar-change-representation) - /// # [Accessing planes](planar-accessing-planes) - /// # [See also](image-data-types) - /// ## (image-data-types) - /// ## (image-data-types-and-namespace) + /// A planar image represented in the spatial domain. + /// + /// A planar image stores its data in blocks called *data units*. Each + /// block is an 8×8-pixel square. A planar image always stores a whole + /// number of data units in both dimensions, even if the image dimensions + /// in pixels are not multiples of 8. Because each component in an image + /// has its own sampling factors, the image planes may not have the same size. + /// + /// A planar image is the result of applying an *inverse discrete cosine + /// transformation* to a spectral image. It can be converted back into a spectral + /// image (with some floating point error) with a *forward discrete cosine + /// transformation*. public struct Planar where Format:JPEG.Format { - /// struct JPEG.Data.Planar.Plane - /// A plane of an image in the spatial domain, containing one color channel. + /// A plane of an image in the spatial domain, containing one color channel. public struct Plane { - /// let JPEG.Data.Planar.Plane.units : (x:Swift.Int, y:Swift.Int) - /// The number of data units in this plane in the horizontal and - /// vertical directions. + /// The number of data units in this plane in the horizontal and + /// vertical directions. public let units:(x:Int, y:Int) - /// var JPEG.Data.Planar.Plane.size : (x:Swift.Int, y:Swift.Int) { get } - /// The size of this plane, in pixels. It is equivalent to multiplying - /// [`units`] by 8. + /// The size of this plane, in pixels. It is equivalent to multiplying + /// [`units`] by 8. public var size:(x:Int, y:Int) { (8 * self.units.x, 8 * self.units.y) } - /// var JPEG.Data.Planar.Plane.factor : (x:Swift.Int, y:Swift.Int) { get } - /// @ : General.Storage2 - /// The sampling factors of the color component this plane stores. + /// The sampling factors of the color component this plane stores. /// - /// This property is backed by two [`Swift.Int32`]s to circumvent compiler - /// size limits for the `read` and `modify` accessors that the image - /// planes are subscriptable through. + /// This property is backed by two [`Swift.Int32`]s to circumvent compiler + /// size limits for the `read` and `modify` accessors that the image + /// planes are subscriptable through. @General.Storage2 public var factor:(x:Int, y:Int) private var buffer:[UInt16] - /// subscript JPEG.Data.Planar.Plane[x:y:] { get set } - /// Accesses the sample at the specified pixel location. - /// - x : Swift.Int + /// Accesses the sample at the specified pixel location. + /// + /// - Parameter x: /// The horizontal pixel index of the sample to access. - /// - y : Swift.Int + /// + /// - Parameter y: /// The vertical pixel index of the sample to access. Index 0 /// corresponds to the visual top of the image. - /// - ->: Swift.UInt16 + /// + /// - Returns: /// The sample. public subscript(x x:Int, y y:Int) -> UInt16 @@ -1603,25 +1530,17 @@ extension JPEG.Data } } } - /// let JPEG.Data.Planar.size : (x:Swift.Int, y:Swift.Int) - /// The size of this image, in pixels. + /// The size of this image, in pixels. /// - /// In general, this size is not the same as the size of the image planes. - /// # [See also](planar-query-image) - /// ## (planar-query-image) + /// In general, this size is not the same as the size of the image planes. public let size:(x:Int, y:Int) - /// let JPEG.Data.Planar.layout : JPEG.Layout - /// The layout of this image. - /// # [See also](planar-query-image) - /// ## (planar-query-image) + /// The layout of this image. + public + let layout:JPEG.Layout + /// The metadata records in this image. public - let layout:JPEG.Layout, - /// let JPEG.Data.Planar.metadata : [JPEG.Metadata] - /// The metadata records in this image. - /// # [See also](planar-query-image) - /// ## (planar-query-image) - metadata:[JPEG.Metadata] + let metadata:[JPEG.Metadata] private var planes:[Plane] @@ -1637,77 +1556,58 @@ extension JPEG.Data self.planes = planes } } - /// struct JPEG.Data.Rectangular - /// where Format:JPEG.Format - /// A rectangular image. - /// - /// A rectangular image resamples all planes at the same sampling level, - /// giving a rectangular array of interleaved samples. - /// - /// It can be unpacked to various color targets to get a pixel color array. - /// # [Creating an image](rectangular-create-image) - /// # [Saving an image](rectangular-save-image) - /// # [Querying an image](rectangular-query-image) - /// # [Changing representations](rectangular-change-representation) - /// # [Accessing samples](rectangular-accessing-samples) - /// # [See also](image-data-types) - /// ## (image-data-types) - /// ## (image-data-types-and-namespace) + /// A rectangular image. + /// + /// A rectangular image resamples all planes at the same sampling level, + /// giving a rectangular array of interleaved samples. + /// + /// It can be unpacked to various color targets to get a pixel color array. public struct Rectangular where Format:JPEG.Format { - /// let JPEG.Data.Rectangular.size : (x:Swift.Int, y:Swift.Int) - /// The size of this image, in pixels. - /// # [See also](rectangular-query-image) - /// ## (rectangular-query-image) + /// The size of this image, in pixels. public - let size:(x:Int, y:Int), - /// let JPEG.Data.Rectangular.layout : JPEG.Layout - /// The layout of this image. - /// # [See also](rectangular-query-image) - /// ## (rectangular-query-image) - layout:JPEG.Layout, - /// let JPEG.Data.Rectangular.metadata : [JPEG.Metadata] - /// The metadata records in this image. - /// # [See also](rectangular-query-image) - /// ## (rectangular-query-image) - metadata:[JPEG.Metadata] + let size:(x:Int, y:Int) + /// The layout of this image. + public + let layout:JPEG.Layout + /// The metadata records in this image. + public + let metadata:[JPEG.Metadata] var values:[UInt16] - /// let JPEG.Data.Rectangular.stride : JPEG.Layout - /// The stride of the interleaved samples in this image. + /// The stride of the interleaved samples in this image. /// - /// This value is analogous to the plane `count` of a planar or spectral image. - /// For example, the rectangular representation of a planar YCbCr image - /// with 3 planes would have a stride of 3. - /// # [See also](rectangular-accessing-samples) - /// ## (1:rectangular-accessing-samples) + /// This value is analogous to the plane `count` of a planar or spectral image. + /// For example, the rectangular representation of a planar YCbCr image + /// with 3 planes would have a stride of 3. public var stride:Int { self.layout.recognized.count } - /// init JPEG.Data.Rectangular.init(size:layout:metadata:values:) - /// Creates a rectangular image with the given image parameters and - /// interleaved samples. + /// Creates a rectangular image with the given image parameters and + /// interleaved samples. /// - /// Passing an invalid `size`, or an array of the wrong `count` will - /// result in a precondition failure. - /// - size : (x:Swift.Int, y:Swift.Int) + /// Passing an invalid `size`, or an array of the wrong `count` will + /// result in a precondition failure. + /// + /// - Parameter size: /// The size of the image, in pixels. Both dimensions must be positive. - /// - layout : JPEG.Layout + /// + /// - Parameter layout: /// The layout of the image. - /// - metadata : [JPEG.Metadata] + /// + /// - Parameter metadata: /// The metadata records in the image. - /// - values : [Swift.UInt16] + /// + /// - Parameter values: /// An array of interleaved samples, in row major order, and without /// padding. The array must have exactly /// [`layout``(Layout).recognized`count`]\ ×\ [`size`x`]\ ×\ [`size`y`] samples. /// Each [`Swift.UInt16`] is one sample. The samples should not be /// normalized, so an image with a [`layout``(Layout).format``(Format).precision`] of /// 8 should only have samples in the range `0 ... 255`. - /// # [See also](rectangular-create-image) - /// ## (0:rectangular-create-image) public init(size:(x:Int, y:Int), layout:JPEG.Layout, @@ -1749,15 +1649,15 @@ extension JPEG.Data.Spectral.Quanta self.quanta.removeAll() self.q.removeAll() } - /// func JPEG.Data.Spectral.Quanta.mapValues(_:) - /// rethrows - /// Returns a dictionary of the quantization tables in this container with - /// the quantum values of each table transformed by the given closure. - /// - transform : ([Swift.UInt16]) throws -> [Swift.UInt16] + /// Returns a dictionary of the quantization tables in this container with + /// the quantum values of each table transformed by the given closure. + /// + /// - Parameter transform: /// A closure that transforms a value. This closure accepts a 64-element /// zigzag-indexed array of the quantum values in each table as its parameter, /// and returns a transformed value of the same or of a different type. - /// - -> : [JPEG.Table.Quantization.Key: R] + /// + /// - Returns: /// A dictionary containing the keys and transformed quanta of the /// quantization tables in this container. public @@ -1773,37 +1673,33 @@ extension JPEG.Data.Spectral.Quanta // RAC conformance for planar types extension JPEG.Data.Spectral.Quanta:RandomAccessCollection { - /// var JPEG.Data.Spectral.Quanta.startIndex:Swift.Int { get } - /// ?: Swift.RandomAccessCollection - /// The index of the first quantization table in this container. + /// The index of the first quantization table in this container. /// - /// The default (all-zeroes) quantization table is not part of the - /// [`Swift.RandomAccessCollection`]. This index is 1 greater than the - /// index of the default quanta. + /// The default (all-zeroes) quantization table is not part of the + /// [`Swift.RandomAccessCollection`]. This index is 1 greater than the + /// index of the default quanta. public var startIndex:Int { // don’t include the default quanta self.quanta.startIndex + 1 } - /// var JPEG.Data.Spectral.Quanta.endIndex:Swift.Int { get } - /// ?: Swift.RandomAccessCollection - /// The index one greater than the index of the last quantization table - /// in this container. + /// The index one greater than the index of the last quantization table + /// in this container. public var endIndex:Int { self.quanta.endIndex } - /// subscript JPEG.Data.Spectral.Quanta[_:] { get set } - /// ?: Swift.RandomAccessCollection - /// Accesses the quantization table at the given index. + /// Accesses the quantization table at the given index. + /// + /// The getter and setter of this subscript yield the quantization table + /// using `read` and `modify`. /// - /// The getter and setter of this subscript yield the quantization table - /// using `read` and `modify`. - /// - q : Swift.Int + /// - Parameter q: /// The index of the quantization table to access. - /// - -> : JPEG.Table.Quantization + /// + /// - Returns: /// The quantization table. public subscript(q:Int) -> JPEG.Table.Quantization @@ -1817,16 +1713,17 @@ extension JPEG.Data.Spectral.Quanta:RandomAccessCollection yield &self.quanta[q] } } - /// func JPEG.Data.Spectral.Quanta.index(forKey:) - /// Returns the index of the table with the given key. + /// Returns the index of the table with the given key. + /// + /// An instance of this type which is part of a [`Spectral`] + /// instance will always contain all quanta keys used by its [`(Spectral).layout`], + /// including keys used only by non-recognized components. /// - /// An instance of this type which is part of a [`Spectral`] - /// instance will always contain all quanta keys used by its [`(Spectral).layout`], - /// including keys used only by non-recognized components. - /// - qi : JPEG.Table.Quantization.Key + /// - Parameter qi: /// The quanta key. Passing a key that does not exist in this container /// will result in a precondition failure. - /// - -> : Swift.Int + /// + /// - Returns: /// The integer index. This index can be used with the [`[_:]`] subscript. public func index(forKey qi:JPEG.Table.Quantization.Key) -> Int @@ -1846,44 +1743,34 @@ extension JPEG.Data.Spectral.Quanta:RandomAccessCollection } extension JPEG.Data.Spectral:RandomAccessCollection { - /// var JPEG.Data.Spectral.startIndex:Swift.Int { get } - /// ?: Swift.RandomAccessCollection - /// The index of the first plane in this image. + /// The index of the first plane in this image. /// - /// This index is always 0. - /// # [See also](spectral-accessing-planes) - /// ## (1:spectral-accessing-planes) + /// This index is always 0. public var startIndex:Int { self.planes.startIndex } - /// var JPEG.Data.Spectral.endIndex:Swift.Int { get } - /// ?: Swift.RandomAccessCollection - /// The index one greater than the index of the last plane in this image. - /// - /// This index is always the number of recognized components in the image’s - /// [`layout``(JPEG.Layout).format`]. - /// # [See also](spectral-accessing-planes) - /// ## (2:spectral-accessing-planes) + /// The index one greater than the index of the last plane in this image. + /// + /// This index is always the number of recognized components in the image’s + /// [`layout``(JPEG.Layout).format`]. public var endIndex:Int { self.planes.endIndex } - /// subscript JPEG.Data.Spectral[_:] { get set } - /// ?: Swift.RandomAccessCollection - /// Accesses the plane at the given index. + /// Accesses the plane at the given index. /// - /// The getter and setter of this subscript yield the plane - /// using `read` and `modify`. - /// - p : Swift.Int + /// The getter and setter of this subscript yield the plane + /// using `read` and `modify`. + /// + /// - Parameter p: /// The index of the plane to access. This index must be within the index /// bounds of this [`Swift.RandomAccessCollection`]. - /// - -> : Plane + /// + /// - Returns: /// The plane. - /// # [See also](spectral-accessing-planes) - /// ## (0:spectral-accessing-planes) public subscript(p:Int) -> Plane { @@ -1896,17 +1783,16 @@ extension JPEG.Data.Spectral:RandomAccessCollection yield &self.planes[p] } } - /// func JPEG.Data.Spectral.index(forKey:) - /// Returns the index of the plane storing the color channel represented - /// by the given component key, or `nil` if the component key is a - /// non-recognized component. - /// - ci : JPEG.Component.Key + /// Returns the index of the plane storing the color channel represented + /// by the given component key, or `nil` if the component key is a + /// non-recognized component. + /// + /// - Parameter ci: /// The component key. - /// - -> : Swift.Int? + /// + /// - Returns: /// The integer index of the plane, or `nil`. If not `nil`, this index /// can be used with the [`[_:]`] subscript. - /// # [See also](spectral-accessing-planes) - /// ## (3:spectral-accessing-planes) public func index(forKey ci:JPEG.Component.Key) -> Int? { @@ -1915,44 +1801,34 @@ extension JPEG.Data.Spectral:RandomAccessCollection } extension JPEG.Data.Planar:RandomAccessCollection { - /// var JPEG.Data.Planar.startIndex:Swift.Int { get } - /// ?: Swift.RandomAccessCollection - /// The index of the first plane in this image. + /// The index of the first plane in this image. /// - /// This index is always 0. - /// # [See also](planar-accessing-planes) - /// ## (1:planar-accessing-planes) + /// This index is always 0. public var startIndex:Int { self.planes.startIndex } - /// var JPEG.Data.Planar.endIndex:Swift.Int { get } - /// ?: Swift.RandomAccessCollection - /// The index one greater than the index of the last plane in this image. - /// - /// This index is always the number of recognized components in the image’s - /// [`layout``(JPEG.Layout).format`]. - /// # [See also](planar-accessing-planes) - /// ## (2:planar-accessing-planes) + /// The index one greater than the index of the last plane in this image. + /// + /// This index is always the number of recognized components in the image’s + /// [`layout``(JPEG.Layout).format`]. public var endIndex:Int { self.planes.endIndex } - /// subscript JPEG.Data.Planar[_:] { get set } - /// ?: Swift.RandomAccessCollection - /// Accesses the plane at the given index. + /// Accesses the plane at the given index. /// - /// The getter and setter of this subscript yield the plane - /// using `read` and `modify`. - /// - p : Swift.Int + /// The getter and setter of this subscript yield the plane + /// using `read` and `modify`. + /// + /// - Parameter p: /// The index of the plane to access. This index must be within the index /// bounds of this [`Swift.RandomAccessCollection`]. - /// - -> : Plane + /// + /// - Returns: /// The plane. - /// # [See also](planar-accessing-planes) - /// ## (0:planar-accessing-planes) public subscript(p:Int) -> Plane { @@ -1965,17 +1841,16 @@ extension JPEG.Data.Planar:RandomAccessCollection yield &self.planes[p] } } - /// func JPEG.Data.Planar.index(forKey:) - /// Returns the index of the plane storing the color channel represented - /// by the given component key, or `nil` if the component key is a - /// non-recognized component. - /// - ci : JPEG.Component.Key + /// Returns the index of the plane storing the color channel represented + /// by the given component key, or `nil` if the component key is a + /// non-recognized component. + /// + /// - Parameter ci: /// The component key. - /// - -> : Swift.Int? + /// + /// - Returns: /// The integer index of the plane, or `nil`. If not `nil`, this index /// can be used with the [`[_:]`] subscript. - /// # [See also](planar-accessing-planes) - /// ## (3:planar-accessing-planes) public func index(forKey ci:JPEG.Component.Key) -> Int? { @@ -1984,20 +1859,21 @@ extension JPEG.Data.Planar:RandomAccessCollection } extension JPEG.Data.Rectangular { - /// subscript JPEG.Data.Rectangular[x:y:p:] { get set } - /// Accesses the sample at the specified pixel location and offset. - /// - x : Swift.Int + /// Accesses the sample at the specified pixel location and offset. + /// + /// - Parameter x: /// The horizontal pixel index of the sample to access. - /// - y : Swift.Int + /// + /// - Parameter y: /// The vertical pixel index of the sample to access. Index 0 /// corresponds to the visual top of the image. - /// - p : Swift.Int + /// + /// - Parameter p: /// The interleaved offset of the sample. This offset is analogous to the /// plane index in the planar image representations. - /// - ->: Swift.UInt16 + /// + /// - Returns: /// The sample. - /// # [See also](rectangular-accessing-samples) - /// ## (0:rectangular-accessing-samples) public subscript(x x:Int, y y:Int, p:Int) -> UInt16 { @@ -2010,17 +1886,16 @@ extension JPEG.Data.Rectangular self.values[p + self.stride * (x + self.size.x * y)] = value } } - /// func JPEG.Data.Rectangular.offset(forKey:) - /// Returns the interleaved offset of the color channel represented - /// by the given component key, or `nil` if the component key is a - /// non-recognized component. - /// - ci : JPEG.Component.Key + /// Returns the interleaved offset of the color channel represented + /// by the given component key, or `nil` if the component key is a + /// non-recognized component. + /// + /// - Parameter ci: /// The component key. - /// - -> : Swift.Int? + /// + /// - Returns: /// The interleaved offset of the channel, or `nil`. If not `nil`, this offset /// can be used as the `p` parameter to the [`[x:y:p:]`] subscript. - /// # [See also](rectangular-accessing-samples) - /// ## (2:rectangular-accessing-samples) public func offset(forKey ci:JPEG.Component.Key) -> Int? { @@ -2030,11 +1905,10 @@ extension JPEG.Data.Rectangular // `indices` property for plane types extension JPEG.Data.Spectral.Plane { - /// var JPEG.Data.Spectral.Plane.indices : General.Range2 { get } - /// A two-dimensional index range encompassing the data units in this plane. + /// A two-dimensional index range encompassing the data units in this plane. /// - /// This index range is a [`Swift.Sequence`] which can be used to iterate - /// through its index space in row-major order. + /// This index range is a [`Swift.Sequence`] which can be used to iterate + /// through its index space in row-major order. public var indices:General.Range2 { @@ -2043,11 +1917,10 @@ extension JPEG.Data.Spectral.Plane } extension JPEG.Data.Planar.Plane { - /// var JPEG.Data.Planar.Plane.indices : General.Range2 { get } - /// A two-dimensional index range encompassing the data units in this plane. + /// A two-dimensional index range encompassing the data units in this plane. /// - /// This index range is a [`Swift.Sequence`] which can be used to iterate - /// through its index space in row-major order. + /// This index range is a [`Swift.Sequence`] which can be used to iterate + /// through its index space in row-major order. public var indices:General.Range2 { @@ -2061,20 +1934,19 @@ extension JPEG.Data.Spectral // cannot have both of them named `with(ci:_)` since this leads to ambiguity // at the call site - /// func JPEG.Data.Spectral.read(ci:_:) - /// rethrows - /// Calls the given closure on the plane and associated quantization table - /// for the given component key. - /// - ci : JPEG.Component.Key + /// Calls the given closure on the plane and associated quantization table + /// for the given component key. + /// + /// - Parameter ci: /// The component key of the plane to access. This component must be a /// recognized component, or this function will suffer a precondition failure. - /// - body : (Plane, JPEG.Table.Quantization) throws -> R + /// + /// - Parameter body: /// The closure to apply to the plane and associated quantization table. /// Its return value is the return value of the surrounding function. - /// - -> : R + /// + /// - Returns: /// The return value of the given closure. - /// # [See also](spectral-accessing-planes) - /// ## (4:spectral-accessing-planes) public func read(ci:JPEG.Component.Key, _ body:(Plane, JPEG.Table.Quantization) throws -> R) @@ -2087,25 +1959,24 @@ extension JPEG.Data.Spectral } return try body(self[p], self.quanta[self[p].q]) } - /// mutating func JPEG.Data.Spectral.with(ci:_:) - /// rethrows - /// Calls the given closure on the plane and associated quantization table - /// for the given component key. - /// - /// The closure passed to this method can mutate the plane in this image - /// specified by the component key. The associated quantization table is still - /// immutable, because editing it would also affect all other planes referencing - /// that table. - /// - ci : JPEG.Component.Key + /// Calls the given closure on the plane and associated quantization table + /// for the given component key. + /// + /// The closure passed to this method can mutate the plane in this image + /// specified by the component key. The associated quantization table is still + /// immutable, because editing it would also affect all other planes referencing + /// that table. + /// + /// - Parameter ci: /// The component key of the plane to access. This component must be a /// recognized component, or this function will suffer a precondition failure. - /// - body : (inout Plane, JPEG.Table.Quantization) throws -> R + /// + /// - Parameter body: /// The closure to apply to the plane and associated quantization table. /// Its return value is the return value of the surrounding function. - /// - -> : R + /// + /// - Returns: /// The return value of the given closure. - /// # [See also](spectral-accessing-planes) - /// ## (5:spectral-accessing-planes) public mutating func with(ci:JPEG.Component.Key, _ body:(inout Plane, JPEG.Table.Quantization) throws -> R) @@ -2121,19 +1992,18 @@ extension JPEG.Data.Spectral } extension JPEG.Data.Planar { - /// func JPEG.Data.Planar.read(ci:_:) - /// rethrows - /// Calls the given closure on the plane for the given component key. - /// - ci : JPEG.Component.Key + /// Calls the given closure on the plane for the given component key. + /// + /// - Parameter ci: /// The component key of the plane to access. This component must be a /// recognized component, or this function will suffer a precondition failure. - /// - body : (Plane) throws -> R + /// + /// - Parameter body: /// The closure to apply to the plane. /// Its return value is the return value of the surrounding function. - /// - -> : R + /// + /// - Returns: /// The return value of the given closure. - /// # [See also](planar-accessing-planes) - /// ## (4:planar-accessing-planes) public func read(ci:JPEG.Component.Key, body:(Plane) throws -> R) @@ -2146,22 +2016,21 @@ extension JPEG.Data.Planar } return try body(self[p]) } - /// mutating func JPEG.Data.Planar.with(ci:_:) - /// rethrows - /// Calls the given closure on the plane for the given component key. + /// Calls the given closure on the plane for the given component key. + /// + /// The closure passed to this method can mutate the plane in this image + /// specified by the component key. /// - /// The closure passed to this method can mutate the plane in this image - /// specified by the component key. - /// - ci : JPEG.Component.Key + /// - Parameter ci: /// The component key of the plane to access. This component must be a /// recognized component, or this function will suffer a precondition failure. - /// - body : (inout Plane) throws -> R + /// + /// - Parameter body: /// The closure to apply to the plane. /// Its return value is the return value of the surrounding function. - /// - -> : R + /// + /// - Returns: /// The return value of the given closure. - /// # [See also](planar-accessing-planes) - /// ## (5:planar-accessing-planes) public mutating func with(ci:JPEG.Component.Key, body:(inout Plane) throws -> R) @@ -2179,11 +2048,10 @@ extension JPEG.Data.Planar // shared properties needed for initializing planar, spectral, and other layout types extension JPEG.Layout { - /// var JPEG.Layout.scale : (x:Swift.Int, y:Swift.Int) { get } - /// The size of the minimum-coded unit of the image, in data units. + /// The size of the minimum-coded unit of the image, in data units. /// - /// This value is the maximum of all the sampling [`(JPEG.Component).factor`]s - /// of the components in the image, including the non-recognized components. + /// This value is the maximum of all the sampling [`(JPEG.Component).factor`]s + /// of the components in the image, including the non-recognized components. public var scale:(x:Int, y:Int) { @@ -2414,8 +2282,6 @@ extension JPEG.Data.Spectral /// for that bit width. /// /// Passing an invalid quanta dictionary will result in a precondition failure. - /// # [See also](spectral-create-image) - /// ## (0:spectral-create-image) public init(size:(x:Int, y:Int), layout:JPEG.Layout, metadata:[JPEG.Metadata], @@ -2457,8 +2323,6 @@ extension JPEG.Data.Spectral /// The new width of this image, in pixels. This width is measured from the /// left side of the image. Passing a negative or zero value will result /// in a precondition failure. - /// # [See also](spectral-edit-image) - /// ## (spectral-edit-image) public mutating func set(width x:Int) { @@ -2485,8 +2349,6 @@ extension JPEG.Data.Spectral /// The new height of this image, in pixels. This height is measured from the /// top of the image. Passing a negative value will result /// in a precondition failure. - /// # [See also](spectral-edit-image) - /// ## (spectral-edit-image) public mutating func set(height y:Int) { @@ -2511,8 +2373,6 @@ extension JPEG.Data.Spectral /// tables created from these values will be encoded using integers with a bit width /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], /// and all the values must be in the correct range for that bit width. - /// # [See also](spectral-edit-image) - /// ## (spectral-edit-image) public mutating func set(quanta:[JPEG.Table.Quantization.Key: [UInt16]]) { @@ -2595,8 +2455,6 @@ extension JPEG.Data.Planar /// samples in the plane, in row-major order. This buffer contains /// 64\ *x*\ *y* samples, where (*x*,\ *y*) is the size of the plane, /// in data units. - /// # [See also](planar-create-image) - /// ## (0:planar-create-image) public init(size:(x:Int, y:Int), layout:JPEG.Layout, metadata:[JPEG.Metadata], initializingWith initializer: @@ -2645,8 +2503,6 @@ extension JPEG.Data.Planar /// The layout of the image. /// - metadata : [JPEG.Metadata] /// The metadata records in the image. - /// # [See also](planar-create-image) - /// ## (1:planar-create-image) public init(size:(x:Int, y:Int), layout:JPEG.Layout, metadata:[JPEG.Metadata]) { @@ -2673,8 +2529,6 @@ extension JPEG.Data.Rectangular /// The layout of the image. /// - metadata : [JPEG.Metadata] /// The metadata records in the image. - /// # [See also](rectangular-create-image) - /// ## (1:rectangular-create-image) public init(size:(x:Int, y:Int), layout:JPEG.Layout, metadata:[JPEG.Metadata]) { @@ -3567,7 +3421,6 @@ extension JPEG /// The main use case for this type is to observe the visual state of a /// partially-decoded image, for example, when performing /// [online decoding](https://github.com/kelvin13/jpeg/tree/master/examples#online-decoding). - /// ## (manual-decoding) public struct Context where Format:JPEG.Format { @@ -4155,8 +4008,6 @@ extension JPEG.Data.Spectral /// Converts this spectral image into its planar, spatial representation. /// - -> : JPEG.Data.Planar /// The output of an inverse discrete cosine transform performed on this image. - /// # [See also](spectral-change-representation) - /// ## (0:spectral-change-representation) public func idct() -> JPEG.Data.Planar { @@ -4183,8 +4034,6 @@ extension JPEG.Data.Planar /// - -> : JPEG.Data.Rectangular /// A rectangular image created by upsampling all planes in the input to /// the same sampling factor. - /// # [See also](planar-change-representation) - /// ## (0:planar-change-representation) public func interleaved(cosite cosited:Bool = false) -> JPEG.Data.Rectangular { @@ -4293,8 +4142,6 @@ extension JPEG.Data.Rectangular /// The color target. /// - ->: [Color] /// A row-major array containing pixels of the image in the specified color space. - /// # [See also](rectangular-change-representation) - /// ## (0:rectangular-change-representation) @_specialize(where Color == JPEG.YCbCr, Format == JPEG.Common) @_specialize(where Color == JPEG.RGB, Format == JPEG.Common) public @@ -4316,8 +4163,6 @@ extension JPEG.Data.Spectral /// A source bytestream. /// - -> : Self /// The decompressed image. - /// # [See also](spectral-create-image) - /// ## (1:spectral-create-image) public static func decompress(stream:inout Source) throws -> Self where Source:JPEG.Bytestream.Source @@ -4339,8 +4184,6 @@ extension JPEG.Data.Planar /// A source bytestream. /// - -> : Self /// The decompressed image. - /// # [See also](planar-create-image) - /// ## (2:planar-create-image) public static func decompress(stream:inout Source) throws -> Self where Source:JPEG.Bytestream.Source @@ -4368,8 +4211,6 @@ extension JPEG.Data.Rectangular /// The default value is `false`. /// - -> : Self /// The decompressed image. - /// # [See also](rectangular-create-image) - /// ## (3:rectangular-create-image) public static func decompress(stream:inout Source, cosite cosited:Bool = false) throws -> Self where Source:JPEG.Bytestream.Source diff --git a/Sources/JPEG/docs.docc/JPEG.Data.Planar.md b/Sources/JPEG/docs.docc/JPEG.Data.Planar.md new file mode 100644 index 00000000..d8e0a09d --- /dev/null +++ b/Sources/JPEG/docs.docc/JPEG.Data.Planar.md @@ -0,0 +1,39 @@ +# ``JPEG.Data.Planar`` + +## Topics + +### Creating an image + +- ``init(size:layout:metadata:initializingWith:)`` +- ``init(size:layout:metadata:)`` +- ``decompress(stream:)`` +- ``decompress(path:)`` + + +### Saving an image + +- ``compress(stream:quanta:)`` +- ``compress(path:quanta:)`` + + +### Querying an image + +- ``size`` +- ``layout`` +- ``metadata`` + + +### Changing representations + +- ``interleaved(cosite:)`` +- ``fdct(quanta:)`` + + +### Accessing planes + +- ``startIndex`` +- ``endIndex`` +- ``subscript(_:)`` +- ``index(forKey:)`` +- ``read(ci:_:)`` +- ``with(ci:_:)`` diff --git a/Sources/JPEG/docs.docc/JPEG.Data.Rectangular.md b/Sources/JPEG/docs.docc/JPEG.Data.Rectangular.md new file mode 100644 index 00000000..1f4557cb --- /dev/null +++ b/Sources/JPEG/docs.docc/JPEG.Data.Rectangular.md @@ -0,0 +1,37 @@ +# ``JPEG.Data.Rectangular`` + +## Topics + +### Creating an image + +- ``init(size:layout:metadata:values:)`` +- ``init(size:layout:metadata:)`` +- ``pack(size:layout:metadata:pixels:)`` +- ``decompress(stream:cosite:)`` +- ``decompress(path:cosite:)`` + + +### Saving an image + +- ``compress(stream:quanta:)`` +- ``compress(path:quanta:)`` + + +### Querying an image + +- ``size`` +- ``layout`` +- ``metadata`` + + +### Changing representations + +- ``unpack(as:)`` +- ``decomposed`` + + +### Accessing samples + +- ``stride`` +- ``subscript(x:y:p:)`` +- ``offset(forKey:)`` diff --git a/Sources/JPEG/docs.docc/JPEG.Data.Spectral.md b/Sources/JPEG/docs.docc/JPEG.Data.Spectral.md new file mode 100644 index 00000000..27efd94a --- /dev/null +++ b/Sources/JPEG/docs.docc/JPEG.Data.Spectral.md @@ -0,0 +1,47 @@ +# ``JPEG.Data.Spectral`` + +## Topics + +### Creating an image + +- ``init(size:layout:metadata:quanta:)`` +- ``decompress(stream:)`` +- ``decompress(path:)`` + + +### Saving an image + +- ``compress(stream:)`` +- ``compress(path:)`` + + +### Querying an image + +- ``size`` +- ``blocks`` +- ``layout`` +- ``metadata`` +- ``quanta`` + + +### Editing an image + +- ``set(width:)`` +- ``set(height:)`` +- ``set(quanta:)`` + + +### Changing representations + +- ``idct`` +- ``encode`` + + +### Accessing planes + +- ``startIndex`` +- ``endIndex`` +- ``subscript(_:)`` +- ``index(forKey:)`` +- ``read(ci:_:)`` +- ``with(ci:_:)`` diff --git a/Sources/JPEG/docs.docc/JPEG.md b/Sources/JPEG/docs.docc/JPEG.md new file mode 100644 index 00000000..5fcf6708 --- /dev/null +++ b/Sources/JPEG/docs.docc/JPEG.md @@ -0,0 +1,95 @@ +# ``/JPEG`` + +Decode, inspect, edit, and encode JPEG images. + + +## Topics + +### Color spaces + +- ``JPEG.Format`` +- ``JPEG.Color`` +- ``JPEG.YCbCr`` +- ``JPEG.RGB`` +- ``JPEG.Common`` + + +### Image metadata + +- ``JPEG.Metadata`` +- ``JPEG.JFIF`` +- ``JPEG.EXIF`` + + +### Image headers + +- ``JPEG.Header`` +- ``JPEG.Header.HeightRedefinition`` +- ``JPEG.Header.RestartInterval`` +- ``JPEG.Header.Frame`` +- ``JPEG.Header.Scan`` + + +### Image tables + +- ``JPEG.AnyTable`` +- ``JPEG.Table`` +- ``JPEG.Table.Huffman`` +- ``JPEG.Table.Quantization`` + + +### Entropy coding + +- ``JPEG.Bitstream.AnySymbol`` +- ``JPEG.Bitstream.Symbol`` +- ``JPEG.Bitstream.Symbol.DC`` +- ``JPEG.Bitstream.Symbol.AC`` +- ``JPEG.Bitstream`` + + +### Data IO and file structure + +- ``JPEG.Bytestream`` +- ``JPEG.Bytestream.Source`` +- ``JPEG.Bytestream.Destination`` +- ``JPEG.Process`` +- ``JPEG.Marker`` + + +### Image representations + +- ``JPEG.Data`` +- ``JPEG.Data.Spectral`` +- ``JPEG.Data.Planar`` +- ``JPEG.Data.Rectangular`` + + +### Image layout and decomposition + +- ``JPEG.Component`` +- ``JPEG.Component.Key`` +- ``JPEG.Scan`` +- ``JPEG.Scan.Component`` +- ``JPEG.Layout`` + + +### Image quality + +- ``JPEG.Table.Quantization.Key`` +- ``JPEG.CompressionLevel`` + + +### Manual decoding + +- ``JPEG.Context`` + + +### Error handling + +- ``JPEG.Error`` +- ``JPEG.LexingError`` +- ``JPEG.ParsingError`` +- ``JPEG.DecodingError`` +- ``JPEG.FormattingError`` +- ``JPEG.SerializingError`` +- ``JPEG.EncodingError`` diff --git a/Sources/JPEG/encode.swift b/Sources/JPEG/encode.swift index 1325ec22..f224de8a 100644 --- a/Sources/JPEG/encode.swift +++ b/Sources/JPEG/encode.swift @@ -255,7 +255,6 @@ extension JPEG /// This is a toy API which generates acceptable defaults for a range of /// quality settings. For finer-grained control, specify coefficient-wise /// quantum values manually. - /// ## (1:image-quality) public enum CompressionLevel { @@ -347,8 +346,6 @@ extension JPEG.Data.Planar /// and all the values must be in the correct range for that bit width. /// - -> : JPEG.Data.Spectral /// The output of a forward discrete cosine transform performed on this image. - /// # [See also](planar-change-representation) - /// ## (1:planar-change-representation) public func fdct(quanta:[JPEG.Table.Quantization.Key: [UInt16]]) -> JPEG.Data.Spectral @@ -383,8 +380,6 @@ extension JPEG.Data.Rectangular /// - -> : JPEG.Data.Planar /// A planar image created by resampling all components in the input /// according to their sampling factors in the image [`layout`]. - /// # [See also](rectangular-change-representation) - /// ## (1:rectangular-change-representation) public func decomposed() -> JPEG.Data.Planar { @@ -448,8 +443,6 @@ extension JPEG.Data.Rectangular /// padding. The array must have exactly [`size`x`]\ ×\ [`size`y`] pixels. /// - -> : Self /// A rectangular image. - /// # [See also](rectangular-create-image) - /// ## (2:rectangular-create-image) @_specialize(where Color == JPEG.YCbCr, Format == JPEG.Common) @_specialize(where Color == JPEG.RGB, Format == JPEG.Common) public static @@ -482,8 +475,6 @@ extension JPEG.Data.Spectral /// with a [`(JPEG.Header).HeightRedefinition`] header). /// - -> : JPEG.Header.Frame /// The encoded frame header. - /// # [See also](spectral-change-representation) - /// ## (1:spectral-change-representation) public func encode() -> JPEG.Header.Frame { @@ -1810,9 +1801,6 @@ extension JPEG.Header.Scan /// To implement a custom data destination type, conform it to this protocol by /// implementing [`(Destination).write(_:)`]. It can /// then be used with the library’s core compression interfaces. -/// # [See also](file-io-protocols) -/// ## (2:file-io-protocols) -/// ## (2:lexing-and-formatting) public protocol _JPEGBytestreamDestination { @@ -1919,8 +1907,6 @@ extension JPEG.Data.Spectral /// the outputted file, in the order they appear in the [`metadata`] array. /// - stream : inout Destination /// A destination bytestream. - /// # [See also](spectral-save-image) - /// ## (1:spectral-save-image) public func compress(stream:inout Destination) throws where Destination:JPEG.Bytestream.Destination @@ -2000,8 +1986,6 @@ extension JPEG.Data.Planar /// tables created from these values will be encoded using integers with a bit width /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], /// and all the values must be in the correct range for that bit width. - /// # [See also](planar-save-image) - /// ## (0:planar-save-image) public func compress(stream:inout Destination, quanta:[JPEG.Table.Quantization.Key: [UInt16]]) throws @@ -2032,8 +2016,6 @@ extension JPEG.Data.Rectangular /// tables created from these values will be encoded using integers with a bit width /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], /// and all the values must be in the correct range for that bit width. - /// # [See also](rectangular-save-image) - /// ## (0:rectangular-save-image) public func compress(stream:inout Destination, quanta:[JPEG.Table.Quantization.Key: [UInt16]]) throws diff --git a/Sources/JPEG/error.swift b/Sources/JPEG/error.swift index d140e49a..acb87834 100644 --- a/Sources/JPEG/error.swift +++ b/Sources/JPEG/error.swift @@ -5,8 +5,6 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/. */ /// protocol JPEG.Error /// : Swift.Error /// Functionality common to all library error types. -/// # [See also](error-types) -/// ## (error-handling) public protocol _JPEGError:Swift.Error { @@ -40,9 +38,6 @@ extension JPEG /// enum JPEG.LexingError /// : JPEG.Error /// A lexing error. - /// # [See also](error-types) - /// ## (error-types) - /// ## (error-handling) public enum LexingError:JPEG.Error { @@ -144,9 +139,6 @@ extension JPEG /// enum JPEG.ParsingError /// : JPEG.Error /// A parsing error. - /// # [See also](error-types) - /// ## (error-types) - /// ## (error-handling) public enum ParsingError:JPEG.Error { @@ -488,9 +480,6 @@ extension JPEG /// enum JPEG.DecodingError /// : JPEG.Error /// A decoding error. - /// # [See also](error-types) - /// ## (error-types) - /// ## (error-handling) public enum DecodingError:JPEG.Error { @@ -808,9 +797,6 @@ extension JPEG /// enum JPEG.FormattingError /// : JPEG.Error /// A formatting error. - /// # [See also](error-types) - /// ## (error-types) - /// ## (error-handling) public enum FormattingError:JPEG.Error { @@ -855,9 +841,6 @@ extension JPEG /// A serializing error. /// /// This enumeration currently has no cases. - /// # [See also](error-types) - /// ## (error-types) - /// ## (error-handling) public enum SerializingError:JPEG.Error { @@ -895,9 +878,6 @@ extension JPEG /// An encoding error. /// /// This enumeration currently has no cases. - /// # [See also](error-types) - /// ## (error-types) - /// ## (error-handling) public enum EncodingError:JPEG.Error { diff --git a/Sources/JPEG/jpeg.swift b/Sources/JPEG/jpeg.swift index 88736c6a..e5c492ce 100644 --- a/Sources/JPEG/jpeg.swift +++ b/Sources/JPEG/jpeg.swift @@ -2,21 +2,12 @@ License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/. */ -/// module JPEG -/// Decode, inspect, edit, and encode JPEG images. -/// -/// See example programs and library tutorials [here](https://github.com/kelvin13/jpeg/tree/master/examples). -/// # [Top level namespaces](top-level-namespaces) - /// protocol JPEG.Format /// A color format, determined by the bit depth and set of component keys in /// a frame header. /// /// The coding [`(JPEG).Process`] of an image may place restrictions on which /// combinations of component sets and bit precisions are valid. -/// # [See also](color-protocols) -/// ## (color-protocols) -/// ## (0:color-space-apis) public protocol _JPEGFormat { @@ -58,7 +49,6 @@ protocol _JPEGFormat /// A color target. /// # [See also](color-protocols) /// ## (color-protocols) -/// ## (0:color-space-apis) public protocol _JPEGColor { @@ -96,19 +86,6 @@ protocol _JPEGColor /// enum JPEG /// A namespace for JPEG-related functionality. -/// # [Color spaces](color-space-apis) -/// # [Image metadata](metadata-types) -/// # [Image headers](header-types-and-namespace) -/// # [Image tables](table-types-and-protocols) -/// # [Entropy coding](entropy-coding) -/// # [Image representations](image-data-types-and-namespace) -/// # [Data IO and file structure](lexing-and-formatting) -/// # [Image layout and decomposition](image-structure-and-decomposition) -/// # [Image quality](image-quality) -/// # [Manual decoding](manual-decoding) -/// # [Error handling](error-handling) -/// # [See also](top-level-namespaces) -/// ## (0:top-level-namespaces) public enum JPEG { @@ -119,8 +96,6 @@ enum JPEG /// enum JPEG.Metadata /// A metadata record. - /// # [Metadata types](metadata-types) - /// ## (metadata-types) public enum Metadata { @@ -157,7 +132,6 @@ enum JPEG /// # [Color channels](JPEG-YCbCr-color-channels) /// # [See also](builtin-color-targets) /// ## (builtin-color-targets) - /// ## (2:color-space-apis) @frozen public struct YCbCr:Hashable @@ -217,7 +191,6 @@ enum JPEG /// # [Color channels](JPEG-RGB-color-channels) /// # [See also](builtin-color-targets) /// ## (builtin-color-targets) - /// ## (2:color-space-apis) @frozen public struct RGB:Hashable @@ -286,7 +259,6 @@ extension JPEG /// # [Compatibility formats](common-nonstandard-formats) /// # [See also](color-protocols) /// ## (color-protocols) - /// ## (1:color-space-apis) public enum Common { @@ -614,7 +586,6 @@ extension JPEG /// [`(Process.Coding).huffman`] entropy coding and the `differential` flag /// set to `false`. /// # [Coding processes](coding-processes) - /// ## (4:lexing-and-formatting) public enum Process:Sendable { @@ -679,7 +650,6 @@ extension JPEG /// enum JPEG.Marker /// A marker type indicator. - /// ## (3:lexing-and-formatting) public enum Marker:Sendable { @@ -812,8 +782,6 @@ extension JPEG /// protocol JPEG.AnyTable /// Functionality common to all table types. -/// # [See also](table-types-and-protocols) -/// ## (table-types-and-protocols) public protocol _JPEGAnyTable { @@ -839,8 +807,6 @@ extension JPEG /// In general, the fields in these types can be assumed to be valid with /// respect to the other fields in the structure, but not necessarily with /// respect to the JPEG file as a whole. - /// # [Header types](header-types-and-namespace) - /// ## (0:header-types-and-namespace) public enum Header { @@ -849,7 +815,6 @@ extension JPEG /// /// This structure is the parsed form of a [`(JPEG.Marker).height`] /// marker segment. - /// ## (header-types-and-namespace) public struct HeightRedefinition { @@ -877,7 +842,6 @@ extension JPEG /// This structure is the parsed form of an [`(JPEG.Marker).interval`] /// marker segment. It can modify or clear the restart interval of an /// image. - /// ## (header-types-and-namespace) public struct RestartInterval { @@ -908,7 +872,6 @@ extension JPEG /// marker segment. In non-hierarchical mode images, it defines global /// image parameters. It contains some of the information needed to /// fully-define an image [`(JPEG).Layout`]. - /// ## (1:header-types-and-namespace) public struct Frame { @@ -942,7 +905,6 @@ extension JPEG /// create the [`JPEG.Scan`] structures elsewhere in the library API. /// # [Creating sequential scans](scan-header-creation-sequential) /// # [Creating progressive scans](scan-header-creation-progressive) - /// ## (1:header-types-and-namespace) public struct Scan { @@ -971,8 +933,6 @@ extension JPEG typealias AnyTable = _JPEGAnyTable /// enum JPEG.Table /// A namespace for table types. - /// # [Table types](table-types-and-protocols) - /// ## (0:table-types-and-protocols) public enum Table { @@ -992,8 +952,6 @@ extension JPEG /// : JPEG.AnyTable /// where Symbol:JPEG.Bitstream.AnySymbol /// A huffman table. - /// # [See also](huffman-table-types) - /// ## (1:table-types-and-protocols) public struct Huffman:AnyTable where Symbol:Bitstream.AnySymbol { @@ -1017,7 +975,6 @@ extension JPEG /// Quantization tables store 64 coefficient quanta. The quantum values /// can be accessed using either a zigzag index with the [`(Quantization).[z:]`] /// subscript, or grid indices with the [`(Quantization).[k:h:]`] subscript. - /// ## (1:table-types-and-protocols) public struct Quantization:AnyTable { @@ -1032,7 +989,6 @@ extension JPEG /// in their numerical representation are written in **boldface**. /// # [See also](key-types) /// ## (key-types) - /// ## (0:image-quality) public struct Key:Hashable, Comparable, Sendable { @@ -1079,7 +1035,6 @@ extension JPEG { /// struct JPEG.Component /// A color channel in an image. - /// ## (1:image-structure-and-decomposition) public struct Component { @@ -1102,7 +1057,6 @@ extension JPEG /// representation are written in **boldface**. /// # [See also](key-types) /// ## (key-types) - /// ## (2:image-structure-and-decomposition) public struct Key:Hashable, Comparable, Sendable { @@ -1130,13 +1084,11 @@ extension JPEG /// This type contains essentially the same information as [`(JPEG).Header.Scan`], /// but has been validated against the global image parameters and has its /// component keys pre-resolved to integer indices. - /// ## (4:image-structure-and-decomposition) public struct Scan { /// struct JPEG.Scan.Component /// A descriptor for a component encoded within a scan. - /// ## (5:image-structure-and-decomposition) public struct Component { @@ -1217,7 +1169,6 @@ extension JPEG /// # [Image modes](layout-image-format) /// # [Component membership](layout-component-membership) /// # [Image structure](layout-image-structure) - /// ## (0:image-structure-and-decomposition) public struct Layout where Format:JPEG.Format { @@ -1857,8 +1808,6 @@ extension JPEG /// struct JPEG.Bitstream /// : Swift.ExpressibleByArrayLiteral /// A padded bitstream. - /// # [Symbol types](entropy-coding-symbols) - /// ## (0:entropy-coding) public struct Bitstream { diff --git a/Sources/JPEG/metadata.swift b/Sources/JPEG/metadata.swift index 0e6959e2..b0279597 100644 --- a/Sources/JPEG/metadata.swift +++ b/Sources/JPEG/metadata.swift @@ -6,8 +6,6 @@ extension JPEG { /// struct JPEG.JFIF /// A JFIF metadata record. - /// # [See also](metadata-types) - /// ## (metadata-types) public struct JFIF { @@ -78,8 +76,6 @@ extension JPEG /// relies extensively on internal file pointers, it is easy to accidentally /// corrupt an EXIF segment. To perform more sophisticated operations, /// use a dedicated library, such as [Carpaccio](https://github.com/mz2/Carpaccio). - /// # [See also](metadata-types) - /// ## (metadata-types) public struct EXIF { diff --git a/Sources/JPEGSystem/os.swift b/Sources/JPEGSystem/os.swift index 510d643b..adc8c0c0 100644 --- a/Sources/JPEGSystem/os.swift +++ b/Sources/JPEGSystem/os.swift @@ -258,8 +258,6 @@ extension JPEG.Data.Spectral /// - -> : Self? /// The decompressed image, or `nil` if the file could not be opened at /// the given file path. - /// # [See also](spectral-create-image) - /// ## (2:spectral-create-image) public static func decompress(path:String) throws -> Self? { @@ -281,8 +279,6 @@ extension JPEG.Data.Spectral /// - -> : Swift.Void? /// A [`Swift.Void`] tuple, or `nil` if the file could not be opened at /// the given file path. - /// # [See also](spectral-save-image) - /// ## (2:spectral-save-image) public func compress(path:String) throws -> Void? { @@ -305,8 +301,6 @@ extension JPEG.Data.Planar /// - -> : Self? /// The decompressed image, or `nil` if the file could not be opened at /// the given file path. - /// # [See also](planar-create-image) - /// ## (3:planar-create-image) public static func decompress(path:String) throws -> Self? { @@ -341,8 +335,6 @@ extension JPEG.Data.Planar /// - -> : Swift.Void? /// A [`Swift.Void`] tuple, or `nil` if the file could not be opened at /// the given file path. - /// # [See also](planar-save-image) - /// ## (1:planar-save-image) public func compress(path:String, quanta:[JPEG.Table.Quantization.Key: [UInt16]]) throws -> Void? @@ -371,8 +363,6 @@ extension JPEG.Data.Rectangular /// - -> : Self? /// The decompressed image, or `nil` if the file could not be opened at /// the given file path. - /// # [See also](rectangular-create-image) - /// ## (4:rectangular-create-image) public static func decompress(path:String, cosite cosited:Bool = false) throws -> Self? { @@ -408,8 +398,6 @@ extension JPEG.Data.Rectangular /// - -> : Swift.Void? /// A [`Swift.Void`] tuple, or `nil` if the file could not be opened at /// the given file path. - /// # [See also](rectangular-save-image) - /// ## (1:rectangular-save-image) public func compress(path:String, quanta:[JPEG.Table.Quantization.Key: [UInt16]]) throws -> Void? From 8e786cd022ea81c7b93f962b6f648e0d85fe6a99 Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sat, 16 Nov 2024 23:06:07 +0000 Subject: [PATCH 04/18] migrate rest of decode.swift --- Sources/JPEG/decode.swift | 340 +++++++++++++++++++------------------- 1 file changed, 172 insertions(+), 168 deletions(-) diff --git a/Sources/JPEG/decode.swift b/Sources/JPEG/decode.swift index 8faa2993..f21949ce 100644 --- a/Sources/JPEG/decode.swift +++ b/Sources/JPEG/decode.swift @@ -2063,15 +2063,14 @@ extension JPEG.Layout ) } } - /// var JPEG.Layout.components : [JPEG.Component.Key: (factor:(x:Swift.Int, y:Swift.Int), qi:JPEG.Table.Quantization.Key)] { get } - /// A dictionary mapping all of the resident components in the image to - /// their sampling factors and quanta keys. - /// - /// This property should be equivalent to the `components` dictionary - /// that would be used to construct this instance using - /// [`init(format:process:components:scans:)`]. As long as the [`Format`] - /// type is properly implemented, this dictionary will always have at - /// least one element. + /// A dictionary mapping all of the resident components in the image to + /// their sampling factors and quanta keys. + /// + /// This property should be equivalent to the `components` dictionary + /// that would be used to construct this instance using + /// [`init(format:process:components:scans:)`]. As long as the [`Format`] + /// type is properly implemented, this dictionary will always have at + /// least one element. public var components: [ @@ -2185,30 +2184,33 @@ extension JPEG.Data.Spectral.Plane self.units.y = y } - /// subscript JPEG.Data.Spectral.Plane[x:y:k:h:] { get set } - /// @inlinable - /// Accesses the frequency coefficient at the specified grid index - /// in the specified data unit. - /// - /// The `x` and `y` indices of this subscript have no index bounds. - /// Out-of-bounds reads will return 0; out-of-bounds writes will - /// have no effect. The `k` and `h` indices still have to be within the - /// correct range. - /// - /// Using this subscript is equivalent to using [`[x:y:z:]`] with the `z` - /// index set to the output of [`Table.Quantization.z(k:h:)`]. - /// - x : Swift.Int + /// Accesses the frequency coefficient at the specified grid index + /// in the specified data unit. + /// + /// The `x` and `y` indices of this subscript have no index bounds. + /// Out-of-bounds reads will return 0; out-of-bounds writes will + /// have no effect. The `k` and `h` indices still have to be within the + /// correct range. + /// + /// Using this subscript is equivalent to using [`[x:y:z:]`] with the `z` + /// index set to the output of [`Table.Quantization.z(k:h:)`]. + /// + /// - Parameter x: /// The horizontal index of the data unit to access. - /// - y : Swift.Int + /// + /// - Parameter y: /// The vertical index of the data unit to access. Index 0 /// corresponds to the visual top of the image. - /// - k : Swift.Int + /// + /// - Parameter z: /// The horizontal frequency index of the coefficient to access. /// This value must be in the range `0 ..< 8`. - /// - h : Swift.Int + /// + /// - Parameter h: /// The vertical frequency index of the coefficient to access. /// This value must be in the range `0 ..< 8`. - /// - ->: Swift.Int16 + /// + /// - Returns: /// The frequency coefficient. @inlinable public @@ -2261,18 +2263,21 @@ extension JPEG.Data.Spectral spectral.set(height: frame.size.y) return spectral } - /// init JPEG.Data.Spectral.init(size:layout:metadata:quanta:) - /// Creates a blank spectral image with the given image parameters and quanta. + /// Creates a blank spectral image with the given image parameters and quanta. /// - /// This initializer will initialize all frequency coefficients in the image to zero. - /// - size : (x:Swift.Int, y:Swift.Int) + /// This initializer will initialize all frequency coefficients in the image to zero. + /// + /// - Parameter size: /// The size of the image, in pixels. Passing a negative or zero width, or /// a negative height, will result in a precondition failure. - /// - layout : JPEG.Layout + /// + /// - Parameter layout: /// The layout of the image. - /// - metadata : [JPEG.Metadata] + /// + /// - Parameter metadata: /// The metadata records in the image. - /// - quanta : [JPEG.Table.Quantization.Key: [Swift.UInt16]] + /// + /// - Parameter quanta: /// The quantum values for each quanta key used by the given `layout`, /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization @@ -2281,7 +2286,7 @@ extension JPEG.Data.Spectral /// of the given layout, and all the values must be in the correct range /// for that bit width. /// - /// Passing an invalid quanta dictionary will result in a precondition failure. + /// Passing an invalid quanta dictionary will result in a precondition failure. public init(size:(x:Int, y:Int), layout:JPEG.Layout, metadata:[JPEG.Metadata], @@ -2313,13 +2318,13 @@ extension JPEG.Data.Spectral self.blocks = (0, 0) } - /// mutating func JPEG.Data.Spectral.set(width:) - /// Sets the width of this image, in pixels. + /// Sets the width of this image, in pixels. + /// + /// Existing data in this image will either be preserved, or cropped. + /// Any additional data units created by this function will have all coefficients + /// initialized to zero. /// - /// Existing data in this image will either be preserved, or cropped. - /// Any additional data units created by this function will have all coefficients - /// initialized to zero. - /// - x : Swift.Int + /// - Parameter x: /// The new width of this image, in pixels. This width is measured from the /// left side of the image. Passing a negative or zero value will result /// in a precondition failure. @@ -2339,13 +2344,13 @@ extension JPEG.Data.Spectral self[p].set(width: u) } } - /// mutating func JPEG.Data.Spectral.set(height:) - /// Sets the height of this image, in pixels. + /// Sets the height of this image, in pixels. + /// + /// Existing data in this image will either be preserved, or cropped. + /// Any additional data units created by this function will have all coefficients + /// initialized to zero. /// - /// Existing data in this image will either be preserved, or cropped. - /// Any additional data units created by this function will have all coefficients - /// initialized to zero. - /// - y : Swift.Int + /// - Parameter y: /// The new height of this image, in pixels. This height is measured from the /// top of the image. Passing a negative value will result /// in a precondition failure. @@ -2362,11 +2367,11 @@ extension JPEG.Data.Spectral self[p].set(height: u) } } - /// mutating func JPEG.Data.Spectral.set(quanta:) - /// Replaces the quantization tables in this image. + /// Replaces the quantization tables in this image. /// - /// This function will invalidate all existing quantization table indices. - /// - quanta : [JPEG.Table.Quantization.Key: [Swift.UInt16]] + /// This function will invalidate all existing quantization table indices. + /// + /// - Parameter quanta: /// The quantum values for each quanta key used by this image’s [`layout`], /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization @@ -2429,17 +2434,19 @@ extension JPEG.Data.Spectral } extension JPEG.Data.Planar { - /// init JPEG.Data.Planar.init(size:layout:metadata:initializingWith:) - /// rethrows - /// Creates a planar image with the given image parameters and generator. - /// - size : (x:Swift.Int, y:Swift.Int) + /// Creates a planar image with the given image parameters and generator. + /// + /// - Parameter size: /// The size of the image, in pixels. Both dimensions must be positive, /// or this initializer will suffer a precondition failure. - /// - layout : JPEG.Layout + /// + /// - Parameter layout: /// The layout of the image. - /// - metadata : [JPEG.Metadata] + /// + /// - Parameter metadata: /// The metadata records in the image. - /// - initializer : (Swift.Int, (x:Swift.Int, y:Swift.Int), (x:Swift.Int, y:Swift.Int), Swift.UnsafeMutableBufferPointer) throws -> () + /// + /// - Parameter initializer: /// A closure called by this function to initialize the contents of each /// plane in this image. /// @@ -2489,19 +2496,21 @@ extension JPEG.Data.Planar return .init(plane, units: units, factor: factor) } } - /// init JPEG.Data.Planar.init(size:layout:metadata:) - /// Creates a planar image with the given image parameters, initializing - /// all image samples to a neutral color. - /// - /// This initializer will initialize all samples in all planes to the - /// midpoint of this image’s sample range. The midpoint is equal to - /// 2^*w*\ –\ 1^, where *w*\ =\ [`layout``(Layout).format``(JPEG.Format).precision`]. - /// - size : (x:Swift.Int, y:Swift.Int) + /// Creates a planar image with the given image parameters, initializing + /// all image samples to a neutral color. + /// + /// This initializer will initialize all samples in all planes to the + /// midpoint of this image’s sample range. The midpoint is equal to + /// 2^*w*\ –\ 1^, where *w*\ =\ [`layout``(Layout).format``(JPEG.Format).precision`]. + /// + /// - Parameter size: /// The size of the image, in pixels. Both dimensions must be positive, /// or this initializer will suffer a precondition failure. - /// - layout : JPEG.Layout + /// + /// - Parameter layout: /// The layout of the image. - /// - metadata : [JPEG.Metadata] + /// + /// - Parameter metadata: /// The metadata records in the image. public init(size:(x:Int, y:Int), layout:JPEG.Layout, metadata:[JPEG.Metadata]) @@ -2515,19 +2524,21 @@ extension JPEG.Data.Planar } extension JPEG.Data.Rectangular { - /// init JPEG.Data.Rectangular.init(size:layout:metadata:) - /// Creates a rectangular image with the given image parameters, initializing - /// all image samples to a neutral color. - /// - /// This initializer will initialize all samples to the - /// midpoint of this image’s sample range. The midpoint is equal to - /// 2^*w*\ –\ 1^, where *w*\ =\ [`layout``(Layout).format``(JPEG.Format).precision`]. - /// - size : (x:Swift.Int, y:Swift.Int) + /// Creates a rectangular image with the given image parameters, initializing + /// all image samples to a neutral color. + /// + /// This initializer will initialize all samples to the + /// midpoint of this image’s sample range. The midpoint is equal to + /// 2^*w*\ –\ 1^, where *w*\ =\ [`layout``(Layout).format``(JPEG.Format).precision`]. + /// + /// - Parameter size: /// The size of the image, in pixels. Both dimensions must be positive, /// or this initializer will suffer a precondition failure. - /// - layout : JPEG.Layout + /// + /// - Parameter layout: /// The layout of the image. - /// - metadata : [JPEG.Metadata] + /// + /// - Parameter metadata: /// The metadata records in the image. public init(size:(x:Int, y:Int), layout:JPEG.Layout, metadata:[JPEG.Metadata]) @@ -3414,13 +3425,11 @@ extension JPEG.Data.Spectral extension JPEG { - /// struct JPEG.Context - /// where Format:JPEG.Format - /// A contextual state manager used for manual decoding. + /// A contextual state manager used for manual decoding. /// - /// The main use case for this type is to observe the visual state of a - /// partially-decoded image, for example, when performing - /// [online decoding](https://github.com/kelvin13/jpeg/tree/master/examples#online-decoding). + /// The main use case for this type is to observe the visual state of a + /// partially-decoded image, for example, when performing + /// [online decoding](https://github.com/kelvin13/jpeg/tree/master/examples#online-decoding). public struct Context where Format:JPEG.Format { @@ -3435,8 +3444,7 @@ extension JPEG private var interval:Int? - /// var JPEG.Context.spectral : JPEG.Data.Spectral { get } - /// The spectral image, as currently decoded. + /// The spectral image, as currently decoded. public private(set) var spectral:Data.Spectral private @@ -3448,10 +3456,9 @@ extension JPEG } extension JPEG.Context { - /// init JPEG.Context.init(frame:) - /// throws - /// Initializes the decoder context from the given frame header. - /// - frame : JPEG.Header.Frame + /// Initializes the decoder context from the given frame header. + /// + /// - Parameter frame: /// The frame header of the image. This frame header is used to allocate /// a [`(Data).Spectral`] image. public @@ -3468,57 +3475,56 @@ extension JPEG.Context ) self.interval = nil } - /// mutating func JPEG.Context.push(height:) - /// Updates the decoder state with the given height redefinition. + /// Updates the decoder state with the given height redefinition. /// - /// This method calls [`(Data.Spectral).set(height:)`] on the stored image. - /// - height : JPEG.Header.HeightRedefinition + /// This method calls [`(Data.Spectral).set(height:)`] on the stored image. + /// + /// - Parameter height: /// The height redefinition. public mutating func push(height:JPEG.Header.HeightRedefinition) { self.spectral.set(height: height.height) } - /// mutating func JPEG.Context.push(interval:) - /// Updates the decoder state with the given restart interval definition. - /// - interval : JPEG.Header.RestartInterval + /// Updates the decoder state with the given restart interval definition. + /// + /// - Parameter interval: /// The restart interval definition. public mutating func push(interval:JPEG.Header.RestartInterval) { self.interval = interval.interval } - /// mutating func JPEG.Context.push(dc:) - /// Updates the decoder state with the given DC huffman table. + /// Updates the decoder state with the given DC huffman table. /// - /// This method binds the table to its target [`(Table.HuffmanDC).Selector`] - /// within this instance. - /// - table : JPEG.Table.HuffmanDC + /// This method binds the table to its target [`(Table.HuffmanDC).Selector`] + /// within this instance. + /// + /// - Parameter table: /// The DC huffman table. public mutating func push(dc table:JPEG.Table.HuffmanDC) { self.tables.dc[keyPath: table.target] = table } - /// mutating func JPEG.Context.push(ac:) - /// Updates the decoder state with the given AC huffman table. + /// Updates the decoder state with the given AC huffman table. + /// + /// This method binds the table to its target [`(Table.HuffmanAC).Selector`] + /// within this instance. /// - /// This method binds the table to its target [`(Table.HuffmanAC).Selector`] - /// within this instance. - /// - table : JPEG.Table.HuffmanAC + /// - Parameter table: /// The AC huffman table. public mutating func push(ac table:JPEG.Table.HuffmanAC) { self.tables.ac[keyPath: table.target] = table } - /// mutating func JPEG.Context.push(quanta:) - /// throws - /// Updates the decoder state with the given quantization table. + /// Updates the decoder state with the given quantization table. /// - /// This method binds the table to its target [`(Table.Quantization).Selector`] - /// within this instance. - /// - table : JPEG.Table.Quantization + /// This method binds the table to its target [`(Table.Quantization).Selector`] + /// within this instance. + /// + /// - Parameter table: /// The quantization table. public mutating func push(quanta table:JPEG.Table.Quantization) throws @@ -3530,31 +3536,32 @@ extension JPEG.Context self.counter += 1 self.tables.quanta[keyPath: table.target] = (q, qi) } - /// mutating func JPEG.Context.push(metadata:) - /// Updates the decoder state with the given metadata record. + /// Updates the decoder state with the given metadata record. + /// + /// This method adds the metadata record to the [`(Data.Spectral).metadata`] + /// array in the stored image. /// - /// This method adds the metadata record to the [`(Data.Spectral).metadata`] - /// array in the stored image. - /// - metadata : JPEG.Metadata + /// - Parameter metadata: /// The metadata record. public mutating func push(metadata:JPEG.Metadata) { self.spectral.metadata.append(metadata) } - /// mutating func JPEG.Context.push(scan:ecss:extend:) - /// throws - /// Updates the decoder state with the given scan header, and decodes the - /// given entropy-coded segment. - /// - /// This type tracks the scan progression of the stored image, and will - /// validate the newly pushed `scan` header against the stored progressive state. - /// - scan : JPEG.Header.Scan + /// Updates the decoder state with the given scan header, and decodes the + /// given entropy-coded segment. + /// + /// This type tracks the scan progression of the stored image, and will + /// validate the newly pushed `scan` header against the stored progressive state. + /// + /// - Parameter scan: /// The scan header associated with the given entropy-coded segment. - /// - ecss : [[Swift.UInt8]] + /// + /// - Parameter ecss: /// The entropy-coded segment. Each sub-array is one restart interval of /// segment. - /// - extend: Swift.Bool + /// + /// - Parameter extend: /// Specifies whether or not the decoder is allowed to dynamically extend /// the height of the image if the entropy-coded segment contains more /// rows of image data than implied by the frame header [`(Header.Frame).size`]. @@ -4004,9 +4011,9 @@ extension JPEG.Data.Planar.Plane extension JPEG.Data.Spectral { - /// func JPEG.Data.Spectral.idct() - /// Converts this spectral image into its planar, spatial representation. - /// - -> : JPEG.Data.Planar + /// Converts this spectral image into its planar, spatial representation. + /// + /// - Returns: /// The output of an inverse discrete cosine transform performed on this image. public func idct() -> JPEG.Data.Planar @@ -4024,14 +4031,15 @@ extension JPEG.Data.Spectral } extension JPEG.Data.Planar { - /// func JPEG.Data.Planar.interleaved(cosite:) - /// Converts this planar image into its rectangular representation. - /// - cosited : Swift.Bool + /// Converts this planar image into its rectangular representation. + /// + /// - Parameter cosited: /// The upsampling method to use. Setting this parameter to `true` co-sites /// the samples; setting it to `false` centers them instead. /// /// The default value is `false`. - /// - -> : JPEG.Data.Rectangular + /// + /// - Returns: /// A rectangular image created by upsampling all planes in the input to /// the same sampling factor. public @@ -4133,14 +4141,12 @@ extension JPEG.Data.Planar } extension JPEG.Data.Rectangular { - /// func JPEG.Data.Rectangular.unpack(as:) - /// where Color:JPEG.Color, Color.Format == Format - /// @ specialized where Color == JPEG.YCbCr - /// @ specialized where Color == JPEG.RGB - /// Unpacks the data in this image into pixels of the given color target. - /// - _ : Color.Type + /// Unpacks the data in this image into pixels of the given color target. + /// + /// - Parameter _: /// The color target. - /// - ->: [Color] + /// + /// - Returns: /// A row-major array containing pixels of the image in the specified color space. @_specialize(where Color == JPEG.YCbCr, Format == JPEG.Common) @_specialize(where Color == JPEG.RGB, Format == JPEG.Common) @@ -4155,13 +4161,12 @@ extension JPEG.Data.Rectangular // staged APIs extension JPEG.Data.Spectral { - /// static func JPEG.Data.Spectral.decompress(stream:) - /// throws - /// where Source:JPEG.Bytestream.Source - /// Decompresses a spectral image from the given data source. - /// - stream : inout Source + /// Decompresses a spectral image from the given data source. + /// + /// - Parameter stream: /// A source bytestream. - /// - -> : Self + /// + /// - Returns: /// The decompressed image. public static func decompress(stream:inout Source) throws -> Self @@ -4172,17 +4177,16 @@ extension JPEG.Data.Spectral } extension JPEG.Data.Planar { - /// static func JPEG.Data.Planar.decompress(stream:) - /// throws - /// where Source:JPEG.Bytestream.Source - /// Decompresses a planar image from the given data source. - /// - /// This function is a convenience function which calls [`Spectral.decompress(stream:)`] - /// to obtain a spectral image, and then calls [`(Spectral).idct()`] on the - /// output to return a planar image. - /// - stream : inout Source + /// Decompresses a planar image from the given data source. + /// + /// This function is a convenience function which calls [`Spectral.decompress(stream:)`] + /// to obtain a spectral image, and then calls [`(Spectral).idct()`] on the + /// output to return a planar image. + /// + /// - Parameter stream: /// A source bytestream. - /// - -> : Self + /// + /// - Returns: /// The decompressed image. public static func decompress(stream:inout Source) throws -> Self @@ -4194,22 +4198,22 @@ extension JPEG.Data.Planar } extension JPEG.Data.Rectangular { - /// static func JPEG.Data.Rectangular.decompress(stream:cosite:) - /// throws - /// where Source:JPEG.Bytestream.Source - /// Decompresses a rectangular image from the given data source. - /// - /// This function is a convenience function which calls [`Planar.decompress(stream:)`] - /// to obtain a planar image, and then calls [`(Planar).interleaved(cosite:)`] - /// on the output to return a rectangular image. - /// - stream : inout Source + /// Decompresses a rectangular image from the given data source. + /// + /// This function is a convenience function which calls [`Planar.decompress(stream:)`] + /// to obtain a planar image, and then calls [`(Planar).interleaved(cosite:)`] + /// on the output to return a rectangular image. + /// + /// - Parameter stream: /// A source bytestream. - /// - cosited : Swift.Bool + /// + /// - Parameter cosited: /// The upsampling method to use. Setting this parameter to `true` co-sites /// the samples; setting it to `false` centers them instead. /// /// The default value is `false`. - /// - -> : Self + /// + /// - Returns: /// The decompressed image. public static func decompress(stream:inout Source, cosite cosited:Bool = false) throws -> Self From 8a03871007e391ef2b2d15dfe3052b7bf7b142b1 Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sat, 16 Nov 2024 23:13:16 +0000 Subject: [PATCH 05/18] migrate doccomments in encode.swift --- Sources/JPEG/encode.swift | 294 +++++++++++++++++++------------------- 1 file changed, 145 insertions(+), 149 deletions(-) diff --git a/Sources/JPEG/encode.swift b/Sources/JPEG/encode.swift index f224de8a..6abf878c 100644 --- a/Sources/JPEG/encode.swift +++ b/Sources/JPEG/encode.swift @@ -249,25 +249,24 @@ extension JPEG.Data.Spectral.Plane } extension JPEG { - /// enum JPEG.CompressionLevel - /// A basic image quality parameter. + /// A basic image quality parameter. /// - /// This is a toy API which generates acceptable defaults for a range of - /// quality settings. For finer-grained control, specify coefficient-wise - /// quantum values manually. + /// This is a toy API which generates acceptable defaults for a range of + /// quality settings. For finer-grained control, specify coefficient-wise + /// quantum values manually. public enum CompressionLevel { - /// case JPEG.CompressionLevel.luminance(_:) - /// A quality level for a luminance component. - /// - _ : Swift.Double + /// A quality level for a luminance component. + /// + /// - Parameter _: /// The quality parameter. A value of `0.0` represents the highest /// possible image quality. A value of `1.0` represents a “medium” /// compression level. This value can be greater than `1.0`. case luminance(Double) - /// case JPEG.CompressionLevel.chrominance(_:) - /// A quality level for a chrominance component. - /// - _ : Swift.Double + /// A quality level for a chrominance component. + /// + /// - Parameter _: /// The quality parameter. A value of `0.0` represents the highest /// possible image quality. A value of `1.0` represents a “medium” /// compression level. This value can be greater than `1.0`. @@ -278,9 +277,8 @@ extension JPEG.CompressionLevel { // taken from the T-81 recommendations - /// var JPEG.CompressionLevel.quanta : [Swift.UInt16] { get } - /// A 64-component array containing quantum values determined by this - /// quality parameter, in zigzag order. + /// A 64-component array containing quantum values determined by this + /// quality parameter, in zigzag order. public var quanta:[UInt16] { @@ -333,18 +331,19 @@ extension JPEG.CompressionLevel } extension JPEG.Data.Planar { - /// func JPEG.Data.Planar.fdct(quanta:) - /// Converts this planar image into its spectral representation. + /// Converts this planar image into its spectral representation. /// - /// This method is the inverse of [`Spectral.idct()`] - /// - quanta: [JPEG.Table.Quantization.Key: [Swift.UInt16]] + /// This method is the inverse of [`Spectral.idct()`] + /// + /// - Parameter quanta: /// The quantum values for each quanta key used by this image’s [`layout`], /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], /// and all the values must be in the correct range for that bit width. - /// - -> : JPEG.Data.Spectral + /// + /// - Returns: /// The output of a forward discrete cosine transform performed on this image. public func fdct(quanta:[JPEG.Table.Quantization.Key: [UInt16]]) @@ -368,16 +367,16 @@ extension JPEG.Data.Planar } extension JPEG.Data.Rectangular { - /// func JPEG.Data.Rectangular.decomposed() - /// Converts this rectangular image into its planar representation. + /// Converts this rectangular image into its planar representation. /// - /// This method uses a basic box-filter to perform downsampling. A box-filter - /// is a relatively poor low-pass filter, so it may be worthwhile to - /// perform component resampling manually and construct a planar image - /// directly using [`(Planar).init(size:layout:metadata:initializingWith:)`]. + /// This method uses a basic box-filter to perform downsampling. A box-filter + /// is a relatively poor low-pass filter, so it may be worthwhile to + /// perform component resampling manually and construct a planar image + /// directly using [`(Planar).init(size:layout:metadata:initializingWith:)`]. /// - /// This method is the inverse of [`Planar.interleaved(cosite:)`]. - /// - -> : JPEG.Data.Planar + /// This method is the inverse of [`Planar.interleaved(cosite:)`]. + /// + /// - Returns: /// A planar image created by resampling all components in the input /// according to their sampling factors in the image [`layout`]. public @@ -421,27 +420,28 @@ extension JPEG.Data.Rectangular } extension JPEG.Data.Rectangular { - /// static func JPEG.Data.Rectangular.pack(size:layout:metadata:pixels:) - /// where Color:JPEG.Color, Color.Format == Format - /// @ specialized where Color == JPEG.YCbCr - /// @ specialized where Color == JPEG.RGB - /// Packs the given row-major pixels into rectangular image data and creates - /// a rectangular image with the given image parameters and layout. + /// Packs the given row-major pixels into rectangular image data and creates + /// a rectangular image with the given image parameters and layout. + /// + /// Passing an invalid `size`, or a pixel array of the wrong `count` will + /// result in a precondition failure. /// - /// Passing an invalid `size`, or a pixel array of the wrong `count` will - /// result in a precondition failure. + /// This function is the inverse of [`unpack(as:)`]. /// - /// This function is the inverse of [`unpack(as:)`]. - /// - size : (x:Swift.Int, y:Swift.Int) + /// - Parameter size: /// The size of the image, in pixels. Both dimensions must be positive. - /// - layout : JPEG.Layout + /// + /// - Parameter layout: /// The layout of the image. - /// - metadata : [JPEG.Metadata] + /// + /// - Parameter metadata: /// The metadata records in the image. - /// - pixels : [Swift.UInt16] + /// + /// - Parameter pixels: /// An array of pixels, in row major order, and without /// padding. The array must have exactly [`size`x`]\ ×\ [`size`y`] pixels. - /// - -> : Self + /// + /// - Returns: /// A rectangular image. @_specialize(where Color == JPEG.YCbCr, Format == JPEG.Common) @_specialize(where Color == JPEG.RGB, Format == JPEG.Common) @@ -467,13 +467,13 @@ extension JPEG.Data.Spectral // this property is not to be used within the library, it is used for encoding // to obtain a valid frame header from a `Spectral` struct - /// func JPEG.Data.Spectral.encode() - /// Creates a frame header for this image. + /// Creates a frame header for this image. /// - /// The encoded frame header contains only the recognized components in - /// this image. It encodes the image height eagerly (as opposed to lazily, - /// with a [`(JPEG.Header).HeightRedefinition`] header). - /// - -> : JPEG.Header.Frame + /// The encoded frame header contains only the recognized components in + /// this image. It encodes the image height eagerly (as opposed to lazily, + /// with a [`(JPEG.Header).HeightRedefinition`] header). + /// + /// - Returns: /// The encoded frame header. public func encode() -> JPEG.Header.Frame @@ -501,13 +501,12 @@ extension JPEG.Layout // note: all components referenced by the scan headers in `self.scans` // must be recognized components. - /// var JPEG.Layout.scans : [JPEG.Header.Scan] { get } - /// The scan decomposition of this image layout, filtered to include only - /// recognized components. + /// The scan decomposition of this image layout, filtered to include only + /// recognized components. /// - /// This property is derived from the this layout’s [`definitions`]. - /// Scans containing only non-recognized components are omitted from this - /// array. + /// This property is derived from the this layout’s [`definitions`]. + /// Scans containing only non-recognized components are omitted from this + /// array. public var scans:[JPEG.Header.Scan] { @@ -671,14 +670,15 @@ extension JPEG.Table.Huffman } // `frequencies` must always contain 256 entries - /// init JPEG.Table.Huffman.init(frequencies:target:) - /// Creates a huffman table containing a near-optimal huffman tree from - /// the given symbol frequencies and table selector. + + /// Creates a huffman table containing a near-optimal huffman tree from + /// the given symbol frequencies and table selector. /// - /// This initializer uses the standard huffman tree construction algorithm - /// to determine optimal codeword assignments. These assignments are modified - /// slightly to fit codeword length constraints imposed by the JPEG specification. - /// - frequencies : [Swift.Int] + /// This initializer uses the standard huffman tree construction algorithm + /// to determine optimal codeword assignments. These assignments are modified + /// slightly to fit codeword length constraints imposed by the JPEG specification. + /// + /// - Parameter frequencies: /// An array of symbol frequencies. This array must contain exactly 256 /// elements, corresponding to the 256 possible 8-bit symbols. The *i*th /// array element specifies the frequency of the symbol with the @@ -686,7 +686,8 @@ extension JPEG.Table.Huffman /// /// At least one symbol must have a non-zero frequency. Passing an invalid /// frequency array will result in a precondition failure. - /// - target : Selector + /// + /// - Parameter target: /// The selector target for the created huffman table. public init(frequencies:[Int], target:Selector) @@ -1663,20 +1664,21 @@ extension JPEG.Table.Quantization } extension JPEG.Table { - /// func JPEG.Table.serialize(_:_:) - /// Serializes the given huffman tables as segment data. + /// Serializes the given huffman tables as segment data. /// - /// The DC tables appear before the AC tables in the serialized - /// segment. + /// The DC tables appear before the AC tables in the serialized segment. /// - /// This method is the inverse of [`parse(huffman:)`]. - /// - _ : [HuffmanDC] + /// This method is the inverse of [`parse(huffman:)`]. + /// + /// - Parameter dc: /// The DC huffman tables to serialize. The tables will appear in the /// serialized segment in the same order they appear in this array. - /// - _ : [HuffmanAC] + /// + /// - Parameter ac: /// The AC huffman tables to serialize. The tables will appear in the /// serialized segment in the same order they appear in this array. - /// - -> : [Swift.UInt8] + /// + /// - Returns: /// A marker segment body. This array does not include the marker type /// indicator, or the marker segment length field. public static @@ -1696,14 +1698,15 @@ extension JPEG.Table return bytes } - /// func JPEG.Table.serialize(_:) - /// Serializes the given quantization tables as segment data. + /// Serializes the given quantization tables as segment data. /// - /// This method is the inverse of [`parse(quantization:)`]. - /// - _ : [Quantization] + /// This method is the inverse of [`parse(quantization:)`]. + /// + /// - Parameter tables: /// The quantization tables to serialize. The tables will appear in the /// serialized segment in the same order they appear in this array. - /// - -> : [Swift.UInt8] + /// + /// - Returns: /// A marker segment body. This array does not include the marker type /// indicator, or the marker segment length field. public static @@ -1732,11 +1735,11 @@ extension JPEG.Table extension JPEG.Header.Frame { - /// func JPEG.Header.Frame.serialized() - /// Serializes this frame header as segment data. + /// Serializes this frame header as segment data. /// - /// This method is the inverse of [`parse(_:process:)`]. - /// - -> : [Swift.UInt8] + /// This method is the inverse of [`parse(_:process:)`]. + /// + /// - Returns: /// A marker segment body. This array does not include the marker type /// indicator, or the marker segment length field. public @@ -1761,11 +1764,11 @@ extension JPEG.Header.Frame } extension JPEG.Header.Scan { - /// func JPEG.Header.Scan.serialized() - /// Serializes this scan header as segment data. + /// Serializes this scan header as segment data. + /// + /// This method is the inverse of [`parse(_:process:)`]. /// - /// This method is the inverse of [`parse(_:process:)`]. - /// - -> : [Swift.UInt8] + /// - Returns: /// A marker segment body. This array does not include the marker type /// indicator, or the marker segment length field. public @@ -1795,27 +1798,26 @@ extension JPEG.Header.Scan // formatters (opposite of lexers) -/// protocol JPEG.Bytestream.Destination -/// A destination bytestream. +/// A destination bytestream. /// -/// To implement a custom data destination type, conform it to this protocol by -/// implementing [`(Destination).write(_:)`]. It can -/// then be used with the library’s core compression interfaces. +/// To implement a custom data destination type, conform it to this protocol by +/// implementing [`(Destination).write(_:)`]. It can +/// then be used with the library’s core compression interfaces. public protocol _JPEGBytestreamDestination { - /// mutating func JPEG.Bytestream.Destination.write(_:) - /// required - /// Attempts to write the given bytes to this stream. + /// Attempts to write the given bytes to this stream. /// - /// A successful call to this function should affect the bytestream state - /// such that subsequent calls should pick up where the last call left off. + /// A successful call to this function should affect the bytestream state + /// such that subsequent calls should pick up where the last call left off. /// - /// The rest of the library interprets a `nil` return value from this function - /// as indicating a write failure. - /// - bytes : [Swift.UInt8] + /// The rest of the library interprets a `nil` return value from this function + /// as indicating a write failure. + /// + /// - Parameter bytes: /// The bytes to write. - /// - -> : Swift.Void? + /// + /// - Returns: /// A [`Swift.Void`] tuple, or `nil` if the write attempt failed. This /// method should return `nil` even if any number of bytes less than /// `bytes.count` were successfully written. @@ -1829,16 +1831,15 @@ extension JPEG.Bytestream } extension JPEG.Bytestream.Destination { - /// mutating func JPEG.Bytestream.Destination.format(marker:) - /// throws - /// Formats a single marker into this bytestream. + /// Formats a single marker into this bytestream. /// - /// This function is meant to be used with markers without segment bodies, - /// such as [`(Marker).start`], [`(Marker).end`], and [`(Marker).restart(_:)`]. + /// This function is meant to be used with markers without segment bodies, + /// such as [`(Marker).start`], [`(Marker).end`], and [`(Marker).restart(_:)`]. /// - /// This function can throw a [`FormattingError`] if it fails to write - /// to the bytestream. - /// - marker : JPEG.Marker + /// This function can throw a [`FormattingError`] if it fails to write + /// to the bytestream. + /// + /// - Parameter marker: /// The type indicator of the marker to format. public mutating func format(marker:JPEG.Marker) throws @@ -1849,19 +1850,19 @@ extension JPEG.Bytestream.Destination throw JPEG.FormattingError.invalidDestination } } - /// mutating func JPEG.Bytestream.Destination.format(marker:tail:) - /// throws - /// Formats a single marker segment into this bytestream. + /// Formats a single marker segment into this bytestream. + /// + /// This function will output a segment length field, even if no marker data + /// is provided, and so should *not* be used with markers without segment + /// bodies, such as [`(Marker).start`], [`(Marker).end`], and [`(Marker).restart(_:)`]. /// - /// This function will output a segment length field, even if no marker data - /// is provided, and so should *not* be used with markers without segment - /// bodies, such as [`(Marker).start`], [`(Marker).end`], and [`(Marker).restart(_:)`]. + /// This function can throw a [`FormattingError`] if it fails to write + /// to the bytestream. /// - /// This function can throw a [`FormattingError`] if it fails to write - /// to the bytestream. - /// - marker : JPEG.Marker + /// - Parameter marker: /// The type indicator of the marker to format. - /// - tail : [Swift.UInt8] + /// + /// - Parameter tail: /// The marker segment body. This array should not include the marker type /// indicator, or the marker segment length field. public mutating @@ -1876,13 +1877,12 @@ extension JPEG.Bytestream.Destination throw JPEG.FormattingError.invalidDestination } } - /// mutating func JPEG.Bytestream.Destination.format(prefix:) - /// throws - /// Formats the given entropy-coded data into this bytestream. + /// Formats the given entropy-coded data into this bytestream. + /// + /// This function is essentially a wrapper around [`write(_:)`] which converts + /// `nil` return values to a thrown [`FormattingError`]. /// - /// This function is essentially a wrapper around [`write(_:)`] which converts - /// `nil` return values to a thrown [`FormattingError`]. - /// - prefix : JPEG.Marker + /// - Parameter prefix: /// The data to write to the bytestream. public mutating func format(prefix:[UInt8]) throws @@ -1898,14 +1898,12 @@ extension JPEG.Bytestream.Destination // staged APIs extension JPEG.Data.Spectral { - /// func JPEG.Data.Spectral.compress(stream:) - /// throws - /// where Destination:JPEG.Bytestream.Destination - /// Compresses a spectral image to the given data destination. + /// Compresses a spectral image to the given data destination. /// - /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. - /// - stream : inout Destination + /// All metadata records in this image will be emitted at the beginning of + /// the outputted file, in the order they appear in the [`metadata`] array. + /// + /// - Parameter stream: /// A destination bytestream. public func compress(stream:inout Destination) throws @@ -1966,20 +1964,19 @@ extension JPEG.Data.Spectral } extension JPEG.Data.Planar { - /// func JPEG.Data.Planar.compress(stream:quanta:) - /// throws - /// where Destination:JPEG.Bytestream.Destination - /// Compresses a planar image to the given data destination. + /// Compresses a planar image to the given data destination. + /// + /// All metadata records in this image will be emitted at the beginning of + /// the outputted file, in the order they appear in the [`metadata`] array. /// - /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. + /// This function is a convenience function which calls [`fdct(quanta:)`] + /// to obtain a spectral image, and then calls [`(Spectral).compress(stream:)`] + /// on the output. /// - /// This function is a convenience function which calls [`fdct(quanta:)`] - /// to obtain a spectral image, and then calls [`(Spectral).compress(stream:)`] - /// on the output. - /// - stream : inout Destination + /// - Parameter stream: /// A destination bytestream. - /// - quanta: [JPEG.Table.Quantization.Key: [Swift.UInt16]] + /// + /// - Parameter quanta: /// The quantum values for each quanta key used by this image’s [`layout`], /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization @@ -1996,20 +1993,19 @@ extension JPEG.Data.Planar } extension JPEG.Data.Rectangular { - /// func JPEG.Data.Rectangular.compress(stream:quanta:) - /// throws - /// where Destination:JPEG.Bytestream.Destination - /// Compresses a rectangular image to the given data destination. + /// Compresses a rectangular image to the given data destination. + /// + /// All metadata records in this image will be emitted at the beginning of + /// the outputted file, in the order they appear in the [`metadata`] array. /// - /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. + /// This function is a convenience function which calls [`decomposed()`] + /// to obtain a planar image, and then calls [`(Planar).compress(stream:quanta:)`] + /// on the output. /// - /// This function is a convenience function which calls [`decomposed()`] - /// to obtain a planar image, and then calls [`(Planar).compress(stream:quanta:)`] - /// on the output. - /// - stream : inout Destination + /// - Parameter stream: /// A destination bytestream. - /// - quanta: [JPEG.Table.Quantization.Key: [Swift.UInt16]] + /// + /// - Parameter quanta: /// The quantum values for each quanta key used by this image’s [`layout`], /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization From 0160b8bd85d7a79f72247be95e261f076c7e1635 Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sat, 16 Nov 2024 23:24:39 +0000 Subject: [PATCH 06/18] error.swift --- Sources/JPEG/error.swift | 584 ++++++++++++++++++--------------------- 1 file changed, 268 insertions(+), 316 deletions(-) diff --git a/Sources/JPEG/error.swift b/Sources/JPEG/error.swift index acb87834..c8ddd3b4 100644 --- a/Sources/JPEG/error.swift +++ b/Sources/JPEG/error.swift @@ -2,30 +2,22 @@ License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/. */ -/// protocol JPEG.Error -/// : Swift.Error -/// Functionality common to all library error types. +/// Functionality common to all library error types. public protocol _JPEGError:Swift.Error { - /// static var JPEG.Error.namespace : Swift.String { get } - /// required - /// The human-readable namespace for errors of this type. + /// The human-readable namespace for errors of this type. static var namespace:String { get } - /// var JPEG.Error.message : Swift.String { get } - /// required - /// A basic description of this error instance. + /// A basic description of this error instance. var message:String { get } - /// var JPEG.Error.details : Swift.String? { get } - /// required - /// A detailed description of this error instance, if available. + /// A detailed description of this error instance, if available. var details:String? { get @@ -35,59 +27,50 @@ extension JPEG { public typealias Error = _JPEGError - /// enum JPEG.LexingError - /// : JPEG.Error - /// A lexing error. + /// A lexing error. public enum LexingError:JPEG.Error { - /// case JPEG.LexingError.truncatedMarkerSegmentType - /// The lexer encountered end-of-stream while lexing a marker - /// segment type indicator. + /// The lexer encountered end-of-stream while lexing a marker + /// segment type indicator. case truncatedMarkerSegmentType - /// case JPEG.LexingError.truncatedMarkerSegmentHeader - /// The lexer encountered end-of-stream while lexing a marker - /// segment length field. + /// The lexer encountered end-of-stream while lexing a marker + /// segment length field. case truncatedMarkerSegmentHeader - /// case JPEG.LexingError.truncatedMarkerSegmentBody(expected:) - /// The lexer encountered end-of-stream while lexing a marker - /// segment body. - /// - expected:Swift.Int + /// The lexer encountered end-of-stream while lexing a marker + /// segment body. + /// + /// - Parameter expected: /// The number of bytes the lexer was expecting to read. case truncatedMarkerSegmentBody(expected:Int) - /// case JPEG.LexingError.truncatedEntropyCodedSegment - /// The lexer encountered end-of-stream while lexing an entropy-coded - /// segment, usually because it was expecting a subsequent marker segment. + /// The lexer encountered end-of-stream while lexing an entropy-coded + /// segment, usually because it was expecting a subsequent marker segment. case truncatedEntropyCodedSegment - /// case JPEG.LexingError.invalidMarkerSegmentLength(_:) - /// The lexer read a marker segment length field, but the value did - /// not make sense. - /// - _ :Swift.Int + /// The lexer read a marker segment length field, but the value did + /// not make sense. + /// + /// - Parameter _: /// The value that the lexer read from the marker segment length field. case invalidMarkerSegmentLength(Int) - /// case JPEG.LexingError.invalidMarkerSegmentPrefix(_:) - /// The lexer encountered a prefixed entropy-coded segment where it - /// was expecting none. - /// - _ :Swift.UInt8 + /// The lexer encountered a prefixed entropy-coded segment where it + /// was expecting none. + /// + /// - Parameter _: /// The first invalid byte encountered by the lexer. case invalidMarkerSegmentPrefix(UInt8) - /// case JPEG.LexingError.invalidMarkerSegmentType(_:) - /// The lexer encountered a marker segment with a reserved type indicator - /// code. - /// - _ :Swift.UInt8 + /// The lexer encountered a marker segment with a reserved type indicator + /// code. + /// + /// - Parameter _: /// The invalid type indicator code encountered by the lexer. case invalidMarkerSegmentType(UInt8) - /// static var JPEG.LexingError.namespace : Swift.String { get } - /// ?: JPEG.Error - /// Returns the string `"lexing error"`. + /// Returns the string `"lexing error"`. public static var namespace:String { "lexing error" } - /// var JPEG.LexingError.message : Swift.String { get } - /// ?: JPEG.Error - /// Returns a basic description of this lexing error. + /// Returns a basic description of this lexing error. public var message:String { @@ -110,9 +93,7 @@ extension JPEG return "invalid marker segment type code" } } - /// var JPEG.LexingError.details : Swift.String? { get } - /// ?: JPEG.Error - /// Returns a detailed description of this lexing error, if available. + /// Returns a detailed description of this lexing error, if available. public var details:String? { @@ -136,169 +117,179 @@ extension JPEG } } } - /// enum JPEG.ParsingError - /// : JPEG.Error - /// A parsing error. + /// A parsing error. public enum ParsingError:JPEG.Error { - /// case JPEG.ParsingError.truncatedMarkerSegmentBody(_:_:expected:) - /// A marker segment contained less than the expected amount of data. - /// - _ : JPEG.Marker + /// A marker segment contained less than the expected amount of data. + /// + /// - Parameter type: /// The marker segment type. - /// - _ : Swift.Int + /// + /// - Parameter size: /// The size of the marker segment, in bytes. - /// - expected : Swift.ClosedRange + /// + /// - Parameter expected: /// The range of marker segment sizes that was expected, in bytes. case truncatedMarkerSegmentBody(Marker, Int, expected:ClosedRange) - /// case JPEG.ParsingError.extraneousMarkerSegmentData(_:_:expected:) - /// A marker segment contained more than the expected amount of data. - /// - _ : JPEG.Marker + /// A marker segment contained more than the expected amount of data. + /// + /// - Parameter type: /// The marker segment type. - /// - _ : Swift.Int + /// + /// - Parameter size: /// The size of the marker segment, in bytes. - /// - expected : Swift.Int + /// + /// - Parameter expected: /// The amount of data that was expected, in bytes. case extraneousMarkerSegmentData(Marker, Int, expected:Int) - /// case JPEG.ParsingError.invalidJFIFSignature(_:) - /// A JFIF segment had an invalid signature. - /// - _ : [Swift.UInt8] + /// A JFIF segment had an invalid signature. + /// + /// - Parameter _: /// The signature read from the segment. case invalidJFIFSignature([UInt8]) - /// case JPEG.ParsingError.invalidJFIFVersionCode(_:) - /// A JFIF segment had an invalid version code. - /// - _ : (major:Swift.UInt8, minor:Swift.UInt8) + /// A JFIF segment had an invalid version code. + /// + /// - Parameter _: /// The version code read from the segment. case invalidJFIFVersionCode((major:UInt8, minor:UInt8)) - /// case JPEG.ParsingError.invalidJFIFDensityUnitCode(_:) - /// A JFIF segment had an invalid density unit code. - /// - _ : Swift.UInt8 + /// A JFIF segment had an invalid density unit code. + /// + /// - Parameter _: /// The density unit code read from the segment. case invalidJFIFDensityUnitCode(UInt8) - /// case JPEG.ParsingError.invalidEXIFSignature(_:) - /// An EXIF segment had an invalid signature. - /// - _ : [Swift.UInt8] + /// An EXIF segment had an invalid signature. + /// + /// - Parameter _: /// The signature read from the segment. case invalidEXIFSignature([UInt8]) - /// case JPEG.ParsingError.invalidEXIFEndiannessCode(_:) - /// An EXIF segment had an invalid endianness specifier. - /// - _ : (Swift.UInt8, Swift.UInt8, Swift.UInt8, Swift.UInt8) + /// An EXIF segment had an invalid endianness specifier. + /// + /// - Parameter _: /// The endianness specifier read from the segment. case invalidEXIFEndiannessCode((UInt8, UInt8, UInt8, UInt8)) - /// case JPEG.ParsingError.invalidFrameWidth(_:) - /// A frame header segment had a negative or zero width field. - /// - _ : Swift.Int + /// A frame header segment had a negative or zero width field. + /// + /// - Parameter _: /// The value of the width field read from the segment. case invalidFrameWidth(Int) - /// case JPEG.ParsingError.invalidFramePrecision(_:_:) - /// A frame header segment had an invalid precision field. - /// - _ : Swift.Int + /// A frame header segment had an invalid precision field. + /// + /// - Parameter value: /// The value of the precision field read from the segment. - /// - _ : JPEG.Process + /// + /// - Parameter process: /// The coding process specified by the frame header. case invalidFramePrecision(Int, Process) - /// case JPEG.ParsingError.invalidFrameComponentCount(_:_:) - /// A frame header segment had an invalid number of components. - /// - _ : Swift.Int + /// A frame header segment had an invalid number of components. + /// + /// - Parameter value: /// The number of components in the segment. - /// - _ : JPEG.Process + /// + /// - Parameter process: /// The coding process specified by the frame header. case invalidFrameComponentCount(Int, Process) - /// case JPEG.ParsingError.invalidFrameQuantizationSelectorCode(_:) - /// A component in a frame header segment had an invalid quantization - /// table selector code. - /// - _ : Swift.UInt8 + /// A component in a frame header segment had an invalid quantization + /// table selector code. + /// + /// - Parameter _: /// The selector code read from the segment. case invalidFrameQuantizationSelectorCode(UInt8) - /// case JPEG.ParsingError.invalidFrameQuantizationSelector(_:_:) - /// A component in a frame header segment used a quantization table - /// selector which is well-formed but unavailable given the frame header coding process. - /// - _ : JPEG.Table.Quantization.Selector + /// A component in a frame header segment used a quantization table + /// selector which is well-formed but unavailable given the frame header coding process. + /// + /// - Parameter value: /// The quantization table selector. - /// - _ : JPEG.Process + /// + /// - Parameter process: /// The coding process specified by the frame header. case invalidFrameQuantizationSelector(JPEG.Table.Quantization.Selector, Process) - /// case JPEG.ParsingError.invalidFrameComponentSamplingFactor(_:_:) - /// A component in a frame header had an invalid sampling factor. + /// A component in a frame header had an invalid sampling factor. /// - /// Sampling factors must be within the range `1 ... 4`. - /// - _ : (x:Swift.Int, y:Swift.Int) + /// Sampling factors must be within the range `1 ... 4`. + /// + /// - Parameter value: /// The sampling factor of the component. - /// - _ : JPEG.Component.Key + /// + /// - Parameter key: /// The component key. case invalidFrameComponentSamplingFactor((x:Int, y:Int), Component.Key) - /// case JPEG.ParsingError.duplicateFrameComponentIndex(_:) - /// The same component key occurred more than once in the same frame header. - /// - _ : JPEG.Component.Key + /// The same component key occurred more than once in the same frame header. + /// + /// - Parameter _: /// The duplicated component key. case duplicateFrameComponentIndex(Component.Key) - /// case JPEG.ParsingError.invalidScanHuffmanSelectorCode(_:) - /// A component in a frame header segment had an invalid quantization - /// table selector code. - /// - _ : Swift.UInt8 + /// A component in a frame header segment had an invalid quantization + /// table selector code. + /// + /// - Parameter _: /// The selector code read from the segment. case invalidScanHuffmanSelectorCode(UInt8) - /// case JPEG.ParsingError.invalidScanHuffmanDCSelector(_:_:) - /// A component in a frame header segment used a DC huffman table - /// selector which is well-formed but unavailable given the frame header coding process. - /// - _ : JPEG.Table.HuffmanDC.Selector + /// A component in a frame header segment used a DC huffman table + /// selector which is well-formed but unavailable given the frame header coding process. + /// + /// - Parameter value: /// The huffman table selector. - /// - _ : JPEG.Process + /// + /// - Parameter process: /// The coding process specified by the frame header. case invalidScanHuffmanDCSelector(JPEG.Table.HuffmanDC.Selector, Process) - /// case JPEG.ParsingError.invalidScanHuffmanACSelector(_:_:) - /// A component in a frame header segment used an AC huffman table - /// selector which is well-formed but unavailable given the frame header coding process. - /// - _ : JPEG.Table.HuffmanAC.Selector + /// A component in a frame header segment used an AC huffman table + /// selector which is well-formed but unavailable given the frame header coding process. + /// + /// - Parameter value: /// The huffman table selector. - /// - _ : JPEG.Process + /// + /// - Parameter process: /// The coding process specified by the frame header. case invalidScanHuffmanACSelector(JPEG.Table.HuffmanAC.Selector, Process) - /// case JPEG.ParsingError.invalidScanComponentCount(_:_:) - /// A scan header had more that the maximum allowed number of components - /// given the image coding process. - /// - _ : Swift.Int + /// A scan header had more that the maximum allowed number of components + /// given the image coding process. + /// + /// - Parameter value: /// The number of components in the scan header. - /// - _ : JPEG.Process + /// + /// - Parameter process: /// The coding process used by the image. case invalidScanComponentCount(Int, Process) - /// case JPEG.ParsingError.invalidScanProgressiveSubset(band:bits:_:) - /// A scan header specified an invalid progressive frequency band - /// or bit range given the image coding process. - /// - band : (Swift.Int, Swift.Int) + /// A scan header specified an invalid progressive frequency band + /// or bit range given the image coding process. + /// + /// - Parameter band: /// The lower and upper bounds of the frequency band read from the scan header. - /// - bits : (Swift.Int, Swift.Int) + /// + /// - Parameter bits: /// The lower and upper bounds of the bit range read from the scan header. - /// - _ : JPEG.Process + /// + /// - Parameter process: /// The coding process used by the image. case invalidScanProgressiveSubset(band:(Int, Int), bits:(Int, Int), Process) - /// case JPEG.ParsingError.invalidHuffmanTargetCode(_:) - /// A huffman table definition had an invalid huffman table - /// selector code. - /// - _ : Swift.UInt8 + /// A huffman table definition had an invalid huffman table + /// selector code. + /// + /// - Parameter _: /// The selector code read from the segment. case invalidHuffmanTargetCode(UInt8) - /// case JPEG.ParsingError.invalidHuffmanTypeCode(_:) - /// A huffman table definition had an invalid type indicator code. - /// - _ : Swift.UInt8 + /// A huffman table definition had an invalid type indicator code. + /// + /// - Parameter _: /// The type indicator code read from the segment. case invalidHuffmanTypeCode(UInt8) - /// case JPEG.ParsingError.invalidHuffmanTable - /// A huffman table definition did not define a valid binary tree. + /// A huffman table definition did not define a valid binary tree. case invalidHuffmanTable - /// case JPEG.ParsingError.invalidQuantizationTargetCode(_:) - /// A quantization table definition had an invalid quantization table - /// selector code. - /// - _ : Swift.UInt8 + /// A quantization table definition had an invalid quantization table + /// selector code. + /// + /// - Parameter _: /// The selector code read from the segment. case invalidQuantizationTargetCode(UInt8) - /// case JPEG.ParsingError.invalidQuantizationPrecisionCode(_:) - /// A quantization table definition had an invalid precision indicator code. - /// - _ : Swift.UInt8 + /// A quantization table definition had an invalid precision indicator code. + /// + /// - Parameter _: /// The precision indicator code read from the segment. case invalidQuantizationPrecisionCode(UInt8) @@ -319,17 +310,13 @@ extension JPEG return .extraneousMarkerSegmentData(marker, count, expected: expected) } } - /// static var JPEG.ParsingError.namespace: Swift.String { get } - /// ?: JPEG.Error - /// Returns the string `"parsing error"`. + /// Returns the string `"parsing error"`. public static var namespace:String { "parsing error" } - /// var JPEG.ParsingError.message : Swift.String { get } - /// ?: JPEG.Error - /// Returns a basic description of this parsing error. + /// Returns a basic description of this parsing error. public var message:String { @@ -391,9 +378,7 @@ extension JPEG return "invalid quantization table precision specifier" } } - /// var JPEG.ParsingError.details : Swift.String? { get } - /// ?: JPEG.Error - /// Returns a detailed description of this parsing error, if available. + /// Returns a detailed description of this parsing error, if available. public var details:String? { @@ -477,195 +462,189 @@ extension JPEG } } } - /// enum JPEG.DecodingError - /// : JPEG.Error - /// A decoding error. + /// A decoding error. public enum DecodingError:JPEG.Error { - /// case JPEG.DecodingError.truncatedEntropyCodedSegment - /// An entropy-coded segment contained less than the expected amount of data. + /// An entropy-coded segment contained less than the expected amount of data. case truncatedEntropyCodedSegment - /// case JPEG.DecodingError.invalidRestartPhase(_:expected:) - /// A restart marker appeared out-of-phase. + /// A restart marker appeared out-of-phase. + /// + /// Restart markers should cycle from 0 to 7, in that order. /// - /// Restart markers should cycle from 0 to 7, in that order. - /// - _ : Swift.Int + /// - Parameter _: /// The phase read from the restart marker. - /// - expected : Swift.Int + /// + /// - Parameter expected: /// The expected phase, which is one greater than the phase of the /// last-encountered restart marker (modulo 8), or 0 if this is the /// first restart marker in the entropy-coded segment. case invalidRestartPhase(Int, expected:Int) - /// case JPEG.DecodingError.missingRestartIntervalSegment - /// A restart marker appeared, but no restart interval was ever defined, - /// or restart markers were disabled. + /// A restart marker appeared, but no restart interval was ever defined, + /// or restart markers were disabled. case missingRestartIntervalSegment - /// case JPEG.DecodingError.invalidSpectralSelectionProgression(_:_:) - /// The first scan for a component encoded a frequency band that - /// did not include the DC coefficient. - /// - _ : Swift.Range + /// The first scan for a component encoded a frequency band that + /// did not include the DC coefficient. + /// + /// - Parameter value: /// The frequency band encoded by the scan. - /// - _ : JPEG.Component.Key + /// + /// - Parameter key: /// The component key of the invalidated color channel. case invalidSpectralSelectionProgression(Range, Component.Key) - /// case JPEG.DecodingError.invalidSuccessiveApproximationProgression(_:_:z:_:) - /// A scan did not follow the correct successive approximation sequence - /// for at least one frequency coefficient. - /// - /// Successive approximation must refine bits starting from the most-significant - /// and going towards the least-significant, only the initial scan - /// for each coefficient can encode more than one bit at a time. - /// - _ : Swift.Range + /// A scan did not follow the correct successive approximation sequence + /// for at least one frequency coefficient. + /// + /// Successive approximation must refine bits starting from the most-significant + /// and going towards the least-significant, only the initial scan + /// for each coefficient can encode more than one bit at a time. + /// + /// - Parameter bits: /// The bit range encoded by the scan. - /// - _ : Swift.Int + /// + /// - Parameter bit: /// The index of the least-significant bit encoded so far for the coefficient `z`. - /// - z : Swift.Int + /// + /// - Parameter z: /// The zigzag index of the coefficient. - /// - _ : JPEG.Component.Key + /// + /// - Parameter key: /// The component key of the invalidated color channel. case invalidSuccessiveApproximationProgression(Range, Int, z:Int, Component.Key) - /// case JPEG.DecodingError.invalidCompositeValue(_:expected:) - /// The decoder decoded an out-of-range composite value. + /// The decoder decoded an out-of-range composite value. /// - /// This error occurs when a refining AC scan encodes any composite - /// value that is not –1, 0, or +1, because refining scans can only - /// refine one bit at a time. - /// - _ : Swift.Int16 + /// This error occurs when a refining AC scan encodes any composite + /// value that is not –1, 0, or +1, because refining scans can only + /// refine one bit at a time. + /// + /// - Parameter _: /// The decoded composite value. - /// - expected : Swift.ClosedRange + /// + /// - Parameter expected: /// The expected range for the composite value. case invalidCompositeValue(Int16, expected:ClosedRange) - /// case JPEG.DecodingError.invalidCompositeBlockRun(_:expected:) - /// The decoder decoded an out-of-range end-of-band/end-of-block run count. + /// The decoder decoded an out-of-range end-of-band/end-of-block run count. /// - /// This error occurs when a sequential scan tries to encode an end-of-band - /// run, which is a progressive coding process concept only. Sequential - /// scans can only end-of-block runs of length 1. - /// - _ : Swift.Int16 + /// This error occurs when a sequential scan tries to encode an end-of-band + /// run, which is a progressive coding process concept only. Sequential + /// scans can only end-of-block runs of length 1. + /// + /// - Parameter _: /// The decoded end-of-band/end-of-block run count. - /// - expected : Swift.ClosedRange + /// + /// - Parameter expected: /// The expected range for the end-of-band/end-of-block run count. case invalidCompositeBlockRun(Int, expected:ClosedRange) - /// case JPEG.DecodingError.undefinedScanComponentReference(_:_:) - /// A scan encoded a component with a key that was not one of the - /// resident components declared in the frame header. - /// - _ : JPEG.Component.Key + /// A scan encoded a component with a key that was not one of the + /// resident components declared in the frame header. + /// + /// - Parameter _: /// The undefined component key. - /// - _ : Swift.Set + /// + /// - Parameter keys: /// The set of defined resident component keys. case undefinedScanComponentReference(Component.Key, Set) - /// case JPEG.DecodingError.invalidScanSamplingVolume(_:) - /// An interleaved scan had a total component sampling volume greater - /// than 10. + /// An interleaved scan had a total component sampling volume greater + /// than 10. /// - /// The total sampling volume is the sum of the products of the sampling - /// factors of each component encoded by the scan. - /// - _ : Swift.Int + /// The total sampling volume is the sum of the products of the sampling + /// factors of each component encoded by the scan. + /// + /// - Parameter _: /// The total sampling volume of the scan components. case invalidScanSamplingVolume(Int) - /// case JPEG.DecodingError.undefinedScanHuffmanDCReference(_:) - /// A DC huffman table selector in a scan referenced a table - /// slot with no bound table. - /// - _ : JPEG.Table.HuffmanDC.Selector + /// A DC huffman table selector in a scan referenced a table + /// slot with no bound table. + /// + /// - Parameter _: /// The table selector. case undefinedScanHuffmanDCReference(Table.HuffmanDC.Selector) - /// case JPEG.DecodingError.undefinedScanHuffmanACReference(_:) - /// An AC huffman table selector in a scan referenced a table - /// slot with no bound table. - /// - _ : JPEG.Table.HuffmanAC.Selector + /// An AC huffman table selector in a scan referenced a table + /// slot with no bound table. + /// + /// - Parameter _: /// The table selector. case undefinedScanHuffmanACReference(Table.HuffmanAC.Selector) - /// case JPEG.DecodingError.undefinedScanQuantizationReference(_:) - /// A quantization table selector in the first scan for a particular - /// component referenced a table slot with no bound table. - /// - _ : JPEG.Table.Quantization.Selector + /// A quantization table selector in the first scan for a particular + /// component referenced a table slot with no bound table. + /// + /// - Parameter _: /// The table selector. case undefinedScanQuantizationReference(Table.Quantization.Selector) - /// case JPEG.DecodingError.invalidScanQuantizationPrecision(_:) - /// A quantization table had the wrong precision mode for the image - /// color format. + /// A quantization table had the wrong precision mode for the image + /// color format. /// - /// Only images with a bit depth greater than 8 should use a 16-bit - /// quantization table. - /// - _ : JPEG.Table.Quantization.Precision + /// Only images with a bit depth greater than 8 should use a 16-bit + /// quantization table. + /// + /// - Parameter _: /// The precision mode of the quantization table. case invalidScanQuantizationPrecision(Table.Quantization.Precision) - /// case JPEG.DecodingError.missingStartOfImage(_:) - /// The first marker segment in the image was not a start-of-image marker. - /// - _ : JPEG.Marker + /// The first marker segment in the image was not a start-of-image marker. + /// + /// - Parameter _: /// The type indicator of the first encountered marker segment. case missingStartOfImage(Marker) - /// case JPEG.DecodingError.duplicateStartOfImage - /// The decoder encountered more than one start-of-image marker. + /// The decoder encountered more than one start-of-image marker. case duplicateStartOfImage - /// case JPEG.DecodingError.duplicateFrameHeaderSegment - /// The decoder encountered more than one frame header segment. + /// The decoder encountered more than one frame header segment. /// - /// JPEG files using the hierarchical coding process can encode more - /// than one frame header. However, this coding process is not currently - /// supported. + /// JPEG files using the hierarchical coding process can encode more + /// than one frame header. However, this coding process is not currently + /// supported. case duplicateFrameHeaderSegment - /// case JPEG.DecodingError.prematureScanHeaderSegment - /// The decoder encountered a scan header segment before a frame header - /// segment. + /// The decoder encountered a scan header segment before a frame header + /// segment. case prematureScanHeaderSegment - /// case JPEG.DecodingError.missingHeightRedefinitionSegment - /// The decoder did not encounter the height redefinition segment that - /// must follow the first scan of an image with a declared height of 0. + /// The decoder did not encounter the height redefinition segment that + /// must follow the first scan of an image with a declared height of 0. case missingHeightRedefinitionSegment - /// case JPEG.DecodingError.prematureHeightRedefinitionSegment - /// The decoder encountered a height redefinition segment before the - /// first image scan. + /// The decoder encountered a height redefinition segment before the + /// first image scan. case prematureHeightRedefinitionSegment - /// case JPEG.DecodingError.unexpectedHeightRedefinitionSegment - /// The decoder encountered a height redefinition segment after, but - /// not immediately after the first image scan. + /// The decoder encountered a height redefinition segment after, but + /// not immediately after the first image scan. case unexpectedHeightRedefinitionSegment - /// case JPEG.DecodingError.unexpectedRestart - /// The decoder encountered a restart marker outside of an entropy-coded - /// segment. + /// The decoder encountered a restart marker outside of an entropy-coded + /// segment. case unexpectedRestart - /// case JPEG.DecodingError.prematureEndOfImage - /// The decoder encountered an end-of-image marker before encountering - /// a frame header segment. + /// The decoder encountered an end-of-image marker before encountering + /// a frame header segment. case prematureEndOfImage - /// case JPEG.DecodingError.unsupportedFrameCodingProcess(_:) - /// The image coding process was anything other than - /// [`(Process).baseline`], or [`(Process).extended(coding:differential:)`] - /// and [`(Process).progressive(coding:differential:)`] with [`(Process.Coding).huffman`] - /// coding and `differential` set to `false`. - /// - _ : JPEG.Process + /// The image coding process was anything other than + /// [`(Process).baseline`], or [`(Process).extended(coding:differential:)`] + /// and [`(Process).progressive(coding:differential:)`] with [`(Process.Coding).huffman`] + /// coding and `differential` set to `false`. + /// + /// - Parameter _: /// The coding process used by the image. case unsupportedFrameCodingProcess(Process) - /// case JPEG.DecodingError.unrecognizedColorFormat(_:_:_:) - /// A [`(Format).recognize(_:precision:)`] implementation failed to - /// recognize the component set and bit precision in a frame header. - /// - _ : Swift.Set + /// A [`(Format).recognize(_:precision:)`] implementation failed to + /// recognize the component set and bit precision in a frame header. + /// + /// - Parameter components: /// The set of resident component keys read from the frame header. - /// - _ : Swift.Int + /// + /// - Parameter precision: /// The bit precision read from the frame header. - /// - _ : Swift.Any.Type + /// + /// - Parameter format: /// The [`Format`] type that tried to detect the color format. case unrecognizedColorFormat(Set, Int, Any.Type) - /// static var JPEG.DecodingError.namespace: Swift.String { get } - /// ?: JPEG.Error - /// Returns the string `"decoding error"`. + /// Returns the string `"decoding error"`. public static var namespace:String { "decoding error" } - /// var JPEG.DecodingError.message : Swift.String { get } - /// ?: JPEG.Error - /// Returns a basic description of this decoding error. + /// Returns a basic description of this decoding error. public var message:String { @@ -727,9 +706,7 @@ extension JPEG return "unrecognized color format" } } - /// var JPEG.DecodingError.details : Swift.String? { get } - /// ?: JPEG.Error - /// Returns a detailed description of this decoding error, if available. + /// Returns a detailed description of this decoding error, if available. public var details:String? { @@ -794,26 +771,19 @@ extension JPEG extension JPEG { - /// enum JPEG.FormattingError - /// : JPEG.Error - /// A formatting error. + /// A formatting error. public enum FormattingError:JPEG.Error { - /// case JPEG.FormattingError.invalidDestination - /// The formatter could not write data to its destination stream. + /// The formatter could not write data to its destination stream. case invalidDestination - /// static var JPEG.FormattingError.namespace: Swift.String { get } - /// ?: JPEG.Error - /// Returns the string `"formatting error"`. + /// Returns the string `"formatting error"`. public static var namespace:String { "formatting error" } - /// var JPEG.FormattingError.message : Swift.String { get } - /// ?: JPEG.Error - /// Returns a basic description of this formatting error. + /// Returns a basic description of this formatting error. public var message:String { @@ -823,9 +793,7 @@ extension JPEG return "failed to write to destination" } } - /// var JPEG.FormattingError.details : Swift.String? { get } - /// ?: JPEG.Error - /// Returns a detailed description of this formatting error, if available. + /// Returns a detailed description of this formatting error, if available. public var details:String? { @@ -836,25 +804,19 @@ extension JPEG } } } - /// enum JPEG.SerializingError - /// : JPEG.Error - /// A serializing error. + /// A serializing error. /// - /// This enumeration currently has no cases. + /// This enumeration currently has no cases. public enum SerializingError:JPEG.Error { - /// static var JPEG.SerializingError.namespace: Swift.String { get } - /// ?: JPEG.Error - /// Returns the string `"serializing error"`. + /// Returns the string `"serializing error"`. public static var namespace:String { "serializing error" } - /// var JPEG.SerializingError.message : Swift.String { get } - /// ?: JPEG.Error - /// Returns a basic description of this serializing error. + /// Returns a basic description of this serializing error. public var message:String { @@ -862,9 +824,7 @@ extension JPEG { } } - /// var JPEG.SerializingError.details : Swift.String? { get } - /// ?: JPEG.Error - /// Returns a detailed description of this serializing error, if available. + /// Returns a detailed description of this serializing error, if available. public var details:String? { @@ -873,25 +833,19 @@ extension JPEG } } } - /// enum JPEG.EncodingError - /// : JPEG.Error - /// An encoding error. + /// An encoding error. /// - /// This enumeration currently has no cases. + /// This enumeration currently has no cases. public enum EncodingError:JPEG.Error { - /// static var JPEG.EncodingError.namespace : Swift.String { get } - /// ?: JPEG.Error - /// Returns the string `"encoding error"`. + /// Returns the string `"encoding error"`. public static var namespace:String { "encoding error" } - /// var JPEG.EncodingError.message : Swift.String { get } - /// ?: JPEG.Error - /// Returns a basic description of this encoding error. + /// Returns a basic description of this encoding error. public var message:String { @@ -899,9 +853,7 @@ extension JPEG { } } - /// var JPEG.EncodingError.details : Swift.String? { get } - /// ?: JPEG.Error - /// Returns a detailed description of this encoding error, if available. + /// Returns a detailed description of this encoding error, if available. public var details:String? { From c2de31ef02f23132bcf15720e36faf8ddede8666 Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sat, 16 Nov 2024 23:45:17 +0000 Subject: [PATCH 07/18] jpeg.swift --- Sources/JPEG/docs.docc/JPEG.Layout.md | 25 + Sources/JPEG/jpeg.swift | 1152 +++++++++++-------------- 2 files changed, 521 insertions(+), 656 deletions(-) create mode 100644 Sources/JPEG/docs.docc/JPEG.Layout.md diff --git a/Sources/JPEG/docs.docc/JPEG.Layout.md b/Sources/JPEG/docs.docc/JPEG.Layout.md new file mode 100644 index 00000000..74902bec --- /dev/null +++ b/Sources/JPEG/docs.docc/JPEG.Layout.md @@ -0,0 +1,25 @@ +# ``JPEG.Layout`` + +## Topics + +### Creating a layout + +- ``init(format:process:components:scans:)`` + + +### Image modes + +- ``format`` +- ``process`` + + +### Component membership + +- ``residents`` +- ``recognized`` + + +### Image structure + +- ``planes`` +- ``definitions`` diff --git a/Sources/JPEG/jpeg.swift b/Sources/JPEG/jpeg.swift index e5c492ce..f3e09563 100644 --- a/Sources/JPEG/jpeg.swift +++ b/Sources/JPEG/jpeg.swift @@ -2,90 +2,80 @@ License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/. */ -/// protocol JPEG.Format -/// A color format, determined by the bit depth and set of component keys in -/// a frame header. +/// A color format, determined by the bit depth and set of component keys in +/// a frame header. /// -/// The coding [`(JPEG).Process`] of an image may place restrictions on which -/// combinations of component sets and bit precisions are valid. +/// The coding [`(JPEG).Process`] of an image may place restrictions on which +/// combinations of component sets and bit precisions are valid. public protocol _JPEGFormat { - /// static func JPEG.Format.recognize(_:precision:) - /// required - /// Detects this color format, given a set of component keys and a bit depth. + /// Detects this color format, given a set of component keys and a bit depth. /// - /// - components : Swift.Set + /// - Parameter components: /// The set of given component keys. - /// - precision : Swift.Int + /// + /// - Parameter precision: /// The given bit depth. - /// - -> : Self? + /// + /// - Returns: /// A color format instance. static func recognize(_ components:Set, precision:Int) -> Self? - /// var JPEG.Format.components : [JPEG.Component.Key] {get} - /// required - /// The set of component keys for this color format. + /// The set of component keys for this color format. /// - /// The ordering is used to determine plane index assignments when initializing - /// an image layout. This property should never be empty. It is allowed - /// for this array to contain fewer components than were detected by the - /// [`(Format).recognize(_:precision:)`] constructor. + /// The ordering is used to determine plane index assignments when initializing + /// an image layout. This property should never be empty. It is allowed + /// for this array to contain fewer components than were detected by the + /// [`(Format).recognize(_:precision:)`] constructor. var components:[JPEG.Component.Key] { get } - /// var JPEG.Format.precision : Swift.Int {get} - /// required - /// The bit depth of each component in this color format. + /// The bit depth of each component in this color format. var precision:Int { get } } -/// protocol JPEG.Color -/// A color target. -/// # [See also](color-protocols) -/// ## (color-protocols) +/// A color target. public protocol _JPEGColor { - /// associatedtype JPEG.Color.Format : JPEG.Format - /// The color format associated with this color target. An image using - /// any color format of this type will support rendering to this color target. + /// The color format associated with this color target. An image using + /// any color format of this type will support rendering to this color target. associatedtype Format:JPEG.Format - /// static func JPEG.Color.unpack(_:of:) - /// required - /// Converts the given interleaved samples into an array of structured pixels. + /// Converts the given interleaved samples into an array of structured pixels. /// - /// - interleaved : [Swift.UInt16] + /// - Parameter interleaved: /// A flat array of interleaved component samples. - /// - format : Format + /// + /// - Parameter format: /// The color format of the interleaved input. - /// - -> : [Self] + /// + /// - Returns: /// An array of pixels of this color target type. static func unpack(_ interleaved:[UInt16], of format:Format) -> [Self] - /// static func JPEG.Color.pack(_:as:) - /// required - /// Converts the given array of structured pixels into an array of interleaved samples. + /// Converts the given array of structured pixels into an array of interleaved samples. /// - /// - pixels : [Self] + /// - Parameter pixels: /// An array of pixels of this color target type. - /// - format : Format + /// + /// - Parameter format: /// The color format of the interleaved output. - /// - -> : [Swift.UInt16] + /// + /// - Returns: /// A flat array of interleaved component samples. static func pack(_ pixels:[Self], as format:Format) -> [UInt16] } -/// enum JPEG -/// A namespace for JPEG-related functionality. +/// A namespace for JPEG-related functionality. public enum JPEG { @@ -94,69 +84,57 @@ enum JPEG public typealias Color = _JPEGColor - /// enum JPEG.Metadata - /// A metadata record. + /// A metadata record. public enum Metadata { - /// case JPEG.Metadata.jfif(_:) - /// A JFIF metadata record. - /// - _ : JPEG.JFIF + /// A JFIF metadata record. case jfif(JFIF) - /// case JPEG.Metadata.exif(_:) - /// An EXIF metadata record. - /// - _ : JPEG.EXIF + /// An EXIF metadata record. case exif(EXIF) - /// case JPEG.Metadata.application(_:data:) - /// An unparsed application data segment. - /// - _ : Swift.Int + /// An unparsed application data segment. + /// + /// - Parameter type: /// The type code of this application segment. - /// - data : Swift.Array + /// + /// - Parameter data: /// The raw data of this application segment. case application(Int, data:[UInt8]) - /// case JPEG.Metadata.comment(data:) - /// A comment segment. - /// - data : Swift.Array + /// A comment segment. + /// + /// - Parameter data: /// The raw contents of this comment segment. Often, but not always, /// this data is UTF-8-encoded text. case comment(data:[UInt8]) } - /// struct JPEG.YCbCr - /// : Swift.Hashable - /// : JPEG.Color - /// @ frozen - /// An 8-bit YCbCr color. + /// An 8-bit YCbCr color. /// - /// This type is a color target for the built-in [`JPEG.Common`] color format. - /// # [Color channels](JPEG-YCbCr-color-channels) - /// # [See also](builtin-color-targets) - /// ## (builtin-color-targets) + /// This type is a color target for the built-in [`JPEG.Common`] color format. + /// + /// ## Color channels + /// - ``y`` + /// - ``cb`` + /// - ``cr`` @frozen public struct YCbCr:Hashable { - /// var JPEG.YCbCr.y : Swift.UInt8 - /// The luminance component of this color. - /// ## (0:JPEG-YCbCr-color-channels) + /// The luminance component of this color. public var y:UInt8 - /// var JPEG.YCbCr.cb : Swift.UInt8 - /// The blue component of this color. - /// ## (1:JPEG-YCbCr-color-channels) + /// The blue component of this color. public var cb:UInt8 - /// var JPEG.YCbCr.cr : Swift.UInt8 - /// The red component of this color. - /// ## (2:JPEG-YCbCr-color-channels) + /// The red component of this color. public var cr:UInt8 - /// init JPEG.YCbCr.init(y:) - /// Initializes this color to the given luminance level. + /// Initializes this color to the given luminance level. + /// + /// The Cb and Cr channels will be initialized to 128. /// - /// The Cb and Cr channels will be initialized to 128. - /// - y : Swift.UInt8 + /// - Parameter y: /// The given luminance level. public init(y:UInt8) @@ -164,14 +142,15 @@ enum JPEG self.init(y: y, cb: 128, cr: 128) } - /// init JPEG.YCbCr.init(y:cb:cr:) - /// Initializes this color to the given YCbCr triplet. + /// Initializes this color to the given YCbCr triplet. /// - /// - y : Swift.UInt8 + /// - Parameter y: /// The given luminance component. - /// - cb: Swift.UInt8 + /// + /// - Parameter cb: /// The given blue component. - /// - cr: Swift.UInt8 + /// + /// - Parameter cr: /// The given red component. public init(y:UInt8, cb:UInt8, cr:UInt8) @@ -181,41 +160,32 @@ enum JPEG self.cr = cr } } - /// struct JPEG.RGB - /// : Swift.Hashable - /// : JPEG.Color - /// @ frozen - /// An 8-bit RGB color. - /// - /// This type is a color target for the built-in [`JPEG.Common`] color format. - /// # [Color channels](JPEG-RGB-color-channels) - /// # [See also](builtin-color-targets) - /// ## (builtin-color-targets) + /// An 8-bit RGB color. + /// + /// This type is a color target for the built-in [`JPEG.Common`] color format. + /// + /// ## Color channels + /// - ``r`` + /// - ``g`` + /// - ``b`` @frozen public struct RGB:Hashable { - /// var JPEG.RGB.r : Swift.UInt8 - /// The red component of this color. - /// ## (JPEG-RGB-color-channels) + /// The red component of this color. public var r:UInt8 - /// var JPEG.RGB.g : Swift.UInt8 - /// The green component of this color. - /// ## (JPEG-RGB-color-channels) + /// The green component of this color. public var g:UInt8 - /// var JPEG.RGB.b : Swift.UInt8 - /// The blue component of this color. - /// ## (JPEG-RGB-color-channels) + /// The blue component of this color. public var b:UInt8 - /// init JPEG.RGB.init(_:) - /// Creates an opaque grayscale color with all color components set - /// to the given value sample. + /// Creates an opaque grayscale color with all color components set + /// to the given value sample. /// - /// - value : Swift.UInt8 + /// - Parameter value: /// The value to initialize all color components to. public init(_ value:UInt8) @@ -223,14 +193,15 @@ enum JPEG self.init(value, value, value) } - /// init JPEG.RGB.init(_:_:_:) - /// Creates an opaque color with the given color samples. + /// Creates an opaque color with the given color samples. /// - /// - red : Swift.UInt8 + /// - Parameter red: /// The value to initialize the red component to. - /// - green : Swift.UInt8 + /// + /// - Parameter green: /// The value to initialize the green component to. - /// - blue : Swift.UInt8 + /// + /// - Parameter blue: /// The value to initialize the blue component to. public init(_ red:UInt8, _ green:UInt8, _ blue:UInt8) @@ -245,68 +216,54 @@ enum JPEG // pixel accessors extension JPEG { - /// enum JPEG.Common - /// : JPEG.Format - /// A built-in color format which covers the JFIF/EXIF subset of the - /// [JPEG standard](https://www.w3.org/Graphics/JPEG/itu-t81.pdf). - /// - /// This color format is able to recognize conforming JFIF and EXIF images, - /// which use the component key assignments *Y*\ =\ **1**, *Cb*\ =\ **2**, *Cr*\ =\ **3**. - /// To provide compatibility with older, faulty JPEG codecs, it is also - /// able to recognize non-standard component schemes as long as - /// they have the correct arity and form a contiguously increasing sequence. - /// # [Standardized formats](common-standard-formats) - /// # [Compatibility formats](common-nonstandard-formats) - /// # [See also](color-protocols) - /// ## (color-protocols) + /// A built-in color format which covers the JFIF/EXIF subset of the + /// [JPEG standard](https://www.w3.org/Graphics/JPEG/itu-t81.pdf). + /// + /// This color format is able to recognize conforming JFIF and EXIF images, + /// which use the component key assignments *Y*\ =\ **1**, *Cb*\ =\ **2**, *Cr*\ =\ **3**. + /// To provide compatibility with older, faulty JPEG codecs, it is also + /// able to recognize non-standard component schemes as long as + /// they have the correct arity and form a contiguously increasing sequence. public enum Common { - /// case JPEG.Common.y8 - /// The standard JFIF 8-bit grayscale format. + /// The standard JFIF 8-bit grayscale format. /// - /// This color format uses the component key assignment *Y*\ =\ **1**. - /// Note that images using this format are compliant JFIF images, but - /// are *not* compliant EXIF images. - /// # [See also](common-standard-formats) - /// ## (common-standard-formats) + /// This color format uses the component key assignment *Y*\ =\ **1**. + /// Note that images using this format are compliant JFIF images, but + /// are *not* compliant EXIF images. case y8 - /// case JPEG.Common.ycc8 - /// The standard JFIF/EXIF 8-bit YCbCr format. + /// The standard JFIF/EXIF 8-bit YCbCr format. /// - /// This color format uses the component key assignments *Y*\ =\ **1**, - /// *Cb*\ =\ **2**, *Cr*\ =\ **3**. - /// # [See also](common-standard-formats) - /// ## (common-standard-formats) + /// This color format uses the component key assignments *Y*\ =\ **1**, + /// *Cb*\ =\ **2**, *Cr*\ =\ **3**. case ycc8 - /// case JPEG.Common.nonconforming1x8(_:) - /// A non-standard 8-bit grayscale format. + /// A non-standard 8-bit grayscale format. + /// + /// This color format can use any component key assignment of arity 1. + /// Note that images using this format are valid JPEG images, but are + /// not compliant JFIF or EXIF images, and some viewers may not support them. /// - /// This color format can use any component key assignment of arity 1. - /// Note that images using this format are valid JPEG images, but are - /// not compliant JFIF or EXIF images, and some viewers may not support them. - /// - _ : JPEG.Component.Key + /// - Parameter _: /// The component key interpreted as the luminance component. - /// # [See also](common-nonstandard-formats) - /// ## (common-nonstandard-formats) case nonconforming1x8(JPEG.Component.Key) - /// case JPEG.Common.nonconforming3x8(_:_:_:) - /// A non-standard 8-bit YCbCr format. + /// A non-standard 8-bit YCbCr format. /// - /// This color format can use any contiguously increasing sequence of - /// component key assignments of arity 3. For example, it can use the - /// assignments *Y*\ =\ **0**, *Cb*\ =\ **1**, *Cr*\ =\ **2**, or the assignments - /// *Y*\ =\ **2**, *Cb*\ =\ **3**, *Cr*\ =\ **4**. - /// Note that images using this format are valid JPEG images, but are - /// not compliant JFIF or EXIF images, and some viewers may not support them. - /// - _ : JPEG.Component.Key + /// This color format can use any contiguously increasing sequence of + /// component key assignments of arity 3. For example, it can use the + /// assignments *Y*\ =\ **0**, *Cb*\ =\ **1**, *Cr*\ =\ **2**, or the assignments + /// *Y*\ =\ **2**, *Cb*\ =\ **3**, *Cr*\ =\ **4**. + /// Note that images using this format are valid JPEG images, but are + /// not compliant JFIF or EXIF images, and some viewers may not support them. + /// + /// - Parameter y: /// The component key interpreted as the luminance component. - /// - _ : JPEG.Component.Key + /// + /// - Parameter cb: /// The component key interpreted as the blue component. - /// - _ : JPEG.Component.Key + /// + /// - Parameter cr: /// The component key interpreted as the red component. - /// # [See also](common-nonstandard-formats) - /// ## (common-nonstandard-formats) case nonconforming3x8(JPEG.Component.Key, JPEG.Component.Key, JPEG.Component.Key) } } @@ -325,19 +282,18 @@ extension JPEG.Common:JPEG.Format upperBound: .init(repeating: .init(T.max)))) } - /// static func JPEG.Common.recognize(_:precision:) - /// ?: JPEG.Format - /// Detects this color format, given a set of component keys and a bit depth. + /// Detects this color format, given a set of component keys and a bit depth. + /// + /// If this constructor detects a [`(Common).nonconforming3x8(_:_:_:)`] + /// color format, it will populate the associated values with the keys in + /// ascending order. /// - /// If this constructor detects a [`(Common).nonconforming3x8(_:_:_:)`] - /// color format, it will populate the associated values with the keys in - /// ascending order. - /// - components : Swift.Set + /// - Parameter components: /// Must be a numerically-contiguous set with one or three elements, or /// this constructor will return `nil`. - /// - precision : Swift.Int + /// + /// - Parameter precision: /// Must be 8, or this constructor will return `nil`. - /// - -> : Self? public static func recognize(_ components:Set, precision:Int) -> Self? { @@ -367,13 +323,11 @@ extension JPEG.Common:JPEG.Format return nil } } - /// var JPEG.Common.components : [JPEG.Component.Key] {get} - /// ?: JPEG.Format - /// The set of component keys for this color format. + /// The set of component keys for this color format. /// - /// If this instance is a [`(Common).nonconforming3x8(_:_:_:)`] color format, - /// the array contains the component keys in the order they appear - /// in the instance’s associated values. + /// If this instance is a [`(Common).nonconforming3x8(_:_:_:)`] color format, + /// the array contains the component keys in the order they appear + /// in the instance’s associated values. public var components:[JPEG.Component.Key] { @@ -389,11 +343,9 @@ extension JPEG.Common:JPEG.Format return [c0, c1, c2] } } - /// var JPEG.Common.precision : Swift.Int {get} - /// ?: JPEG.Format - /// The bit depth of each component in this color format. + /// The bit depth of each component in this color format. /// - /// This value is always 8. + /// This value is always 8. public var precision:Int { @@ -402,13 +354,12 @@ extension JPEG.Common:JPEG.Format } extension JPEG.YCbCr { - /// var JPEG.YCbCr.rgb : JPEG.RGB - /// This color represented in the RGB color space. + /// This color represented in the RGB color space. /// - /// This property applies the YCbCr-to-RGB conversion formula defined in - /// the [JFIF standard](https://www.w3.org/Graphics/JPEG/jfif3.pdf). Some - /// YCbCr colors are not representable in the RGB color space; such colors - /// will be clipped to the acceptable range. + /// This property applies the YCbCr-to-RGB conversion formula defined in + /// the [JFIF standard](https://www.w3.org/Graphics/JPEG/jfif3.pdf). Some + /// YCbCr colors are not representable in the RGB color space; such colors + /// will be clipped to the acceptable range. public var rgb:JPEG.RGB { @@ -426,11 +377,10 @@ extension JPEG.YCbCr } extension JPEG.RGB { - /// var JPEG.RGB.ycc : JPEG.YCbCr - /// This color represented in the YCbCr color space. + /// This color represented in the YCbCr color space. /// - /// This property applies the RGB-to-YCbCr conversion formula defined in - /// the [JFIF standard](https://www.w3.org/Graphics/JPEG/jfif3.pdf). + /// This property applies the RGB-to-YCbCr conversion formula defined in + /// the [JFIF standard](https://www.w3.org/Graphics/JPEG/jfif3.pdf). public var ycc:JPEG.YCbCr { @@ -452,14 +402,15 @@ extension JPEG.RGB extension JPEG.YCbCr:JPEG.Color { - /// static func JPEG.YCbCr.unpack(_:of:) - /// ?: JPEG.Color - /// Converts the given interleaved samples into an array of YCbCr pixels. - /// - interleaved : [Swift.UInt16] + /// Converts the given interleaved samples into an array of YCbCr pixels. + /// + /// - Parameter interleaved: /// A flat array of interleaved component samples. - /// - format : JPEG.Common + /// + /// - Parameter format: /// The color format of the interleaved input. - /// - -> : [Self] + /// + /// - Returns: /// An array of YCbCr pixels. public static func unpack(_ interleaved:[UInt16], of format:JPEG.Common) -> [Self] @@ -484,15 +435,15 @@ extension JPEG.YCbCr:JPEG.Color } } } - /// static func JPEG.YCbCr.pack(_:as:) - /// ?: JPEG.Color - /// Converts the given array of YCbCr pixels into an array of interleaved samples. + /// Converts the given array of YCbCr pixels into an array of interleaved samples. /// - /// - pixels : [Self] + /// - Parameter pixels: /// An array of YCbCr pixels. - /// - format : JPEG.Common + /// + /// - Parameter format: /// The color format of the interleaved output. - /// - -> : [Swift.UInt16] + /// + /// - Returns: /// A flat array of interleaved component samples. public static func pack(_ pixels:[Self], as format:JPEG.Common) -> [UInt16] @@ -510,14 +461,15 @@ extension JPEG.YCbCr:JPEG.Color extension JPEG.RGB:JPEG.Color { - /// static func JPEG.RGB.unpack(_:of:) - /// ?: JPEG.Color - /// Converts the given interleaved samples into an array of RGB pixels. - /// - interleaved : [Swift.UInt16] + /// Converts the given interleaved samples into an array of RGB pixels. + /// + /// - Parameter interleaved: /// A flat array of interleaved component samples. - /// - format : JPEG.Common + /// + /// - Parameter format: /// The color format of the interleaved input. - /// - -> : [Self] + /// + /// - Returns: /// An array of RGB pixels. public static func unpack(_ interleaved:[UInt16], of format:JPEG.Common) -> [Self] @@ -542,15 +494,15 @@ extension JPEG.RGB:JPEG.Color } } } - /// static func JPEG.RGB.pack(_:as:) - /// ?: JPEG.Color - /// Converts the given array of RGB pixels into an array of interleaved samples. + /// Converts the given array of RGB pixels into an array of interleaved samples. /// - /// - pixels : [Self] + /// - Parameter pixels: /// An array of RGB pixels. - /// - format : JPEG.Common + /// + /// - Parameter format: /// The color format of the interleaved output. - /// - -> : [Swift.UInt16] + /// + /// - Returns: /// A flat array of interleaved component samples. public static func pack(_ pixels:[Self], as format:JPEG.Common) -> [UInt16] @@ -574,132 +526,113 @@ extension JPEG.RGB:JPEG.Color // compound types extension JPEG { - /// enum JPEG.Process - /// A coding process. - /// - /// The [JPEG standard](https://www.w3.org/Graphics/JPEG/itu-t81.pdf) - /// specifies several subformats of the JPEG format known as *coding processes*. - /// The library can recognize images using any coding process, but - /// only supports encoding and decoding images using the [`(Process).baseline`], - /// [`(Process).extended(coding:differential:)`], or - /// [`(Process).progressive(coding:differential:)`] processes with - /// [`(Process.Coding).huffman`] entropy coding and the `differential` flag - /// set to `false`. - /// # [Coding processes](coding-processes) + /// A coding process. + /// + /// The [JPEG standard](https://www.w3.org/Graphics/JPEG/itu-t81.pdf) + /// specifies several subformats of the JPEG format known as *coding processes*. + /// The library can recognize images using any coding process, but + /// only supports encoding and decoding images using the [`(Process).baseline`], + /// [`(Process).extended(coding:differential:)`], or + /// [`(Process).progressive(coding:differential:)`] processes with + /// [`(Process.Coding).huffman`] entropy coding and the `differential` flag + /// set to `false`. public enum Process:Sendable { - /// enum JPEG.Process.Coding - /// An entropy coding method. + /// An entropy coding method. public enum Coding:Sendable { - /// case JPEG.Process.Coding.huffman - /// Huffman entropy coding. + /// Huffman entropy coding. case huffman - /// case JPEG.Process.Coding.arithmetic - /// Arithmetic entropy coding. + /// Arithmetic entropy coding. case arithmetic } - /// case JPEG.Process.baseline - /// The baseline coding process. + /// The baseline coding process. /// - /// This is a sequential coding process. It allows up to two simultaneously - /// referenced tables of each type. It can only be used with color formats - /// with a bit [`(JPEG.Format).precision`] of 8. - /// ## (coding-processes) + /// This is a sequential coding process. It allows up to two simultaneously + /// referenced tables of each type. It can only be used with color formats + /// with a bit [`(JPEG.Format).precision`] of 8. case baseline - /// case JPEG.Process.extended(coding:differential:) - /// The extended coding process. + /// The extended coding process. + /// + /// This is a sequential coding process. It allows up to four simultaneously + /// referenced tables of each type. It can only be used with color formats + /// with a bit [`(JPEG.Format).precision`] of 8 or 12. /// - /// This is a sequential coding process. It allows up to four simultaneously - /// referenced tables of each type. It can only be used with color formats - /// with a bit [`(JPEG.Format).precision`] of 8 or 12. - /// - coding : Coding + /// - Parameter coding: /// The entropy coding used by this coding process. - /// - differential : Swift.Bool + /// + /// - Parameter differential: /// Indicates whether the image frame using this coding process is a /// differential frame under the hierarchical mode of operations. - /// ## (coding-processes) case extended(coding:Coding, differential:Bool) - /// case JPEG.Process.progressive(coding:differential:) - /// The progressive coding process. + /// The progressive coding process. + /// + /// This is a progressive coding process. It allows up to four simultaneously + /// referenced tables of each type. It can only be used with color formats + /// with a bit [`(JPEG.Format).precision`] of 8 or 12, and no more than + /// four components. /// - /// This is a progressive coding process. It allows up to four simultaneously - /// referenced tables of each type. It can only be used with color formats - /// with a bit [`(JPEG.Format).precision`] of 8 or 12, and no more than - /// four components. - /// - coding : Coding + /// - Parameter coding: /// The entropy coding used by this coding process. - /// - differential : Swift.Bool + /// + /// - Parameter differential: /// Indicates whether the image frame using this coding process is a /// differential frame under the hierarchical mode of operations. - /// ## (coding-processes) case progressive(coding:Coding, differential:Bool) - /// case JPEG.Process.lossless(coding:differential:) - /// The lossless coding process. - /// - coding : Coding + /// The lossless coding process. + /// + /// - Parameter coding: /// The entropy coding used by this coding process. - /// - differential : Swift.Bool + /// + /// - Parameter differential: /// Indicates whether the image frame using this coding process is a /// differential frame under the hierarchical mode of operations. - /// ## (coding-processes) case lossless(coding:Coding, differential:Bool) } - /// enum JPEG.Marker - /// A marker type indicator. + /// A marker type indicator. public enum Marker:Sendable { - /// case JPEG.Marker.start - /// A start-of-image (SOI) marker. + /// A start-of-image (SOI) marker. case start - /// case JPEG.Marker.end - /// An end-of-image (EOI) marker. + /// An end-of-image (EOI) marker. case end - /// case JPEG.Marker.quantization - /// A quantization table definition (DQT) segment. + /// A quantization table definition (DQT) segment. case quantization - /// case JPEG.Marker.huffman - /// A huffman table definition (DHT) segment. + /// A huffman table definition (DHT) segment. case huffman - /// case JPEG.Marker.application(_:) - /// An application data (APP~*n*~) segment. - /// - _ : Swift.Int + /// An application data (APP~*n*~) segment. + /// + /// - Parameter _: /// The application segment type code. This value can be from 0 to 15. case application(Int) - /// case JPEG.Marker.restart(_:) - /// A restart (RST~*m*~) marker. - /// - _ : Swift.Int + /// A restart (RST~*m*~) marker. + /// + /// - Parameter _: /// The restart phase. It cycles through the values 0 through 7. case restart(Int) - /// case JPEG.Marker.height - /// A height redefinition (DNL) segment. + /// A height redefinition (DNL) segment. case height - /// case JPEG.Marker.interval - /// A restart interval definition (DRI) segment. + /// A restart interval definition (DRI) segment. case interval - /// case JPEG.Marker.comment - /// A comment (COM) segment. + /// A comment (COM) segment. case comment - /// case JPEG.Marker.frame(_:) - /// A frame header (SOF\*) segment. - /// - _ : JPEG.Process + /// A frame header (SOF\*) segment. + /// + /// - Parameter _: /// The coding process used by the image frame. case frame(Process) - /// case JPEG.Marker.scan - /// A scan header (SOS) segment. + /// A scan header (SOS) segment. case scan - /// case JPEG.Marker.arithmeticCodingCondition case arithmeticCodingCondition - /// case JPEG.Marker.hierarchical case hierarchical - /// case JPEG.Marker.expandReferenceComponents case expandReferenceComponents init?(code:UInt8) @@ -780,53 +713,45 @@ extension JPEG } } -/// protocol JPEG.AnyTable -/// Functionality common to all table types. +/// Functionality common to all table types. public protocol _JPEGAnyTable { - /// associatedtype JPEG.AnyTable.Delegate - /// required - /// A type representing a table instance while it is bound to a table slot. + /// A type representing a table instance while it is bound to a table slot. associatedtype Delegate - /// typealias JPEG.AnyTable.Slots = (Delegate?, Delegate?, Delegate?, Delegate?) - /// Four table slots. + /// Four table slots. /// - /// JPEG images are always limited to four table slots for each table type. - /// Some coding processes may limit further the number of available table slots. + /// JPEG images are always limited to four table slots for each table type. + /// Some coding processes may limit further the number of available table slots. typealias Slots = (Delegate?, Delegate?, Delegate?, Delegate?) - /// typealias JPEG.AnyTable.Selector = Swift.WritableKeyPath - /// A table selector. + /// A table selector. typealias Selector = WritableKeyPath } extension JPEG { - /// enum JPEG.Header - /// A namespace for header types. + /// A namespace for header types. /// - /// In general, the fields in these types can be assumed to be valid with - /// respect to the other fields in the structure, but not necessarily with - /// respect to the JPEG file as a whole. + /// In general, the fields in these types can be assumed to be valid with + /// respect to the other fields in the structure, but not necessarily with + /// respect to the JPEG file as a whole. public enum Header { - /// struct JPEG.Header.HeightRedefinition - /// A height redefinition header. + /// A height redefinition header. /// - /// This structure is the parsed form of a [`(JPEG.Marker).height`] - /// marker segment. + /// This structure is the parsed form of a [`(JPEG.Marker).height`] + /// marker segment. public struct HeightRedefinition { - /// let JPEG.Header.HeightRedefinition.height : Swift.Int - /// The visible image height, in pixels. + /// The visible image height, in pixels. /// - /// This value is always positive. + /// This value is always positive. public let height:Int - /// init JPEG.Header.HeightRedefinition.init(height:) - /// Creates a height redefinition header. - /// - height : Swift.Int + /// Creates a height redefinition header. + /// + /// - Parameter height: /// The visible image height, in pixels. Passing a negative value /// will result in a precondition failure. public @@ -836,25 +761,23 @@ extension JPEG self.height = height } } - /// struct JPEG.Header.RestartInterval - /// A restart interval definition header. + /// A restart interval definition header. /// - /// This structure is the parsed form of an [`(JPEG.Marker).interval`] - /// marker segment. It can modify or clear the restart interval of an - /// image. + /// This structure is the parsed form of an [`(JPEG.Marker).interval`] + /// marker segment. It can modify or clear the restart interval of an + /// image. public struct RestartInterval { - /// let JPEG.Header.RestartInterval.interval : Swift.Int? - /// The restart interval, in minimum-coded units, or `nil` if the - /// header is meant to disable restart markers. + /// The restart interval, in minimum-coded units, or `nil` if the + /// header is meant to disable restart markers. /// - /// This value is always positive or `nil`. + /// This value is always positive or `nil`. public let interval:Int? - /// init JPEG.Header.RestartInterval.init(interval:) - /// Creates a restart interval definition header. - /// - interval : Swift.Int? + /// Creates a restart interval definition header. + /// + /// - Parameter interval: /// The restart interval, in minimum-coded units, or `nil` to /// disable restart markers. Passing a negative or zero value /// will result in a precondition failure. @@ -865,98 +788,79 @@ extension JPEG self.interval = interval } } - /// struct JPEG.Header.Frame - /// A frame header. + /// A frame header. /// - /// This structure is the parsed form of a [`(JPEG.Marker).frame(_:)`] - /// marker segment. In non-hierarchical mode images, it defines global - /// image parameters. It contains some of the information needed to - /// fully-define an image [`(JPEG).Layout`]. + /// This structure is the parsed form of a [`(JPEG.Marker).frame(_:)`] + /// marker segment. In non-hierarchical mode images, it defines global + /// image parameters. It contains some of the information needed to + /// fully-define an image [`(JPEG).Layout`]. public struct Frame { - /// let JPEG.Header.Frame.process : JPEG.Process - /// The coding process used by the image. + /// The coding process used by the image. + public + let process:Process + /// The bit precision of this image. public - let process:Process, - /// let JPEG.Header.Frame.precision : Swift.Int - /// The bit precision of this image. - precision:Int, - /// let JPEG.Header.Frame.size : (x:Swift.Int, y:Swift.Int) - /// The visible size of this image, in pixels. + let precision:Int + /// The visible size of this image, in pixels. /// - /// The width is always positive. The height can be either positive - /// or zero, if the height is to be defined later by a - /// [`(JPEG.Header).HeightRedefinition`] header. - size:(x:Int, y:Int) - /// let JPEG.Header.Frame.components: [JPEG.Component.Key: JPEG.Component] - /// The components in this image. + /// The width is always positive. The height can be either positive + /// or zero, if the height is to be defined later by a + /// [`(JPEG.Header).HeightRedefinition`] header. + public + let size:(x:Int, y:Int) + /// The components in this image. /// - /// This dictionary will always have at least one element. + /// This dictionary will always have at least one element. public let components:[Component.Key: Component] } - /// struct JPEG.Header.Scan - /// A scan header. + /// A scan header. /// - /// This structure is the parsed form of a [`(JPEG.Marker).scan`] - /// marker segment. It defines scan-level image parameters. The library - /// validates these structures against the global image parameters to - /// create the [`JPEG.Scan`] structures elsewhere in the library API. - /// # [Creating sequential scans](scan-header-creation-sequential) - /// # [Creating progressive scans](scan-header-creation-progressive) + /// This structure is the parsed form of a [`(JPEG.Marker).scan`] + /// marker segment. It defines scan-level image parameters. The library + /// validates these structures against the global image parameters to + /// create the [`JPEG.Scan`] structures elsewhere in the library API. public struct Scan { - /// let JPEG.Header.Scan.band : Swift.Range - /// The frequency band encoded by this scan. + /// The frequency band encoded by this scan. /// - /// This property specifies a range of zigzag-indexed frequency coefficients. - /// It is always within the interval of 0 to 64. + /// This property specifies a range of zigzag-indexed frequency coefficients. + /// It is always within the interval of 0 to 64. public - let band:Range, - /// let JPEG.Header.Scan.bits : Swift.Range - /// The bit range encoded by this scan. + let band:Range + /// The bit range encoded by this scan. /// - /// This range is always non-negative. - bits:Range, - /// let JPEG.Header.Scan.components : [JPEG.Scan.Component] - /// The color components in this scan, in the order in which their - /// data units are interleaved. + /// This range is always non-negative. + public + let bits:Range + /// The color components in this scan, in the order in which their + /// data units are interleaved. /// - /// This array always contains at least one element. - components:[JPEG.Scan.Component] + /// This array always contains at least one element. + public + let components:[JPEG.Scan.Component] } } public typealias AnyTable = _JPEGAnyTable - /// enum JPEG.Table - /// A namespace for table types. + /// A namespace for table types. public enum Table { - /// typealias JPEG.Table.HuffmanDC = Huffman - /// A DC huffman table. - /// # [See also](huffman-table-types) - /// ## (huffman-table-types) + /// A DC huffman table. public typealias HuffmanDC = Huffman - /// typealias JPEG.Table.HuffmanAC = Huffman - /// An AC huffman table. - /// # [See also](huffman-table-types) - /// ## (huffman-table-types) + /// An AC huffman table. public typealias HuffmanAC = Huffman - /// struct JPEG.Table.Huffman - /// : JPEG.AnyTable - /// where Symbol:JPEG.Bitstream.AnySymbol - /// A huffman table. + /// A huffman table. public struct Huffman:AnyTable where Symbol:Bitstream.AnySymbol { - /// typealias JPEG.Table.Huffman.Delegate = Self - /// ?: JPEG.AnyTable public typealias Delegate = Self @@ -968,27 +872,19 @@ extension JPEG // constructor for the huffman Decoder type can just read it from here let size:(n:Int, z:Int) } - /// struct JPEG.Table.Quantization - /// : JPEG.AnyTable - /// A quantization table. + /// A quantization table. /// - /// Quantization tables store 64 coefficient quanta. The quantum values - /// can be accessed using either a zigzag index with the [`(Quantization).[z:]`] - /// subscript, or grid indices with the [`(Quantization).[k:h:]`] subscript. + /// Quantization tables store 64 coefficient quanta. The quantum values + /// can be accessed using either a zigzag index with the [`(Quantization).[z:]`] + /// subscript, or grid indices with the [`(Quantization).[k:h:]`] subscript. public struct Quantization:AnyTable { - /// struct JPEG.Table.Quantization.Key - /// : Swift.Hashable - /// : Swift.Comparable - /// : Swift.ExpressibleByIntegerLiteral - /// A unique identifier assigned to each quantization table in an image. + /// A unique identifier assigned to each quantization table in an image. /// - /// Quanta keys are numeric values ranging from [`Swift.Int`min`] - /// to [`Swift.Int`max`]. In these reference pages, quanta keys - /// in their numerical representation are written in **boldface**. - /// # [See also](key-types) - /// ## (key-types) + /// Quanta keys are numeric values ranging from [`Swift.Int`min`] + /// to [`Swift.Int`max`]. In these reference pages, quanta keys + /// in their numerical representation are written in **boldface**. public struct Key:Hashable, Comparable, Sendable { @@ -1006,20 +902,15 @@ extension JPEG } } - /// typealias JPEG.Table.Quantization.Delegate = (q:Swift.Int, qi:JPEG.Table.Quantization.Key) - /// ?: JPEG.AnyTable public typealias Delegate = (q:Int, qi:Table.Quantization.Key) - /// enum JPEG.Table.Quantization.Precision - /// The integer width of the quantum values in this quantization table. + /// The integer width of the quantum values in this quantization table. public enum Precision:Sendable { - /// case JPEG.Table.Quantization.Precision.uint8 - /// The quantum values are encoded as 8-bit unsigned integers. + /// The quantum values are encoded as 8-bit unsigned integers. case uint8 - /// case JPEG.Table.Quantization.Precision.uint16 - /// The quantum values are encoded as big endian 16-bit unsigned integers. + /// The quantum values are encoded as big endian 16-bit unsigned integers. case uint16 } @@ -1033,30 +924,21 @@ extension JPEG // layout extension JPEG { - /// struct JPEG.Component - /// A color channel in an image. + /// A color channel in an image. public struct Component { - /// let JPEG.Component.factor : (x:Swift.Int, y:Swift.Int) - /// The horizontal and vertical sampling factors for this component. + /// The horizontal and vertical sampling factors for this component. public let factor:(x:Int, y:Int) - /// let JPEG.Component.selector : JPEG.Table.Quantization.Selector - /// The table selector of the quantization table associated with this component. + /// The table selector of the quantization table associated with this component. public let selector:Table.Quantization.Selector - /// struct JPEG.Component.Key - /// : Swift.Hashable - /// : Swift.Comparable - /// : Swift.ExpressibleByIntegerLiteral - /// A unique identifier assigned to each color component in an image. + /// A unique identifier assigned to each color component in an image. /// - /// Component keys are numeric values ranging from 0 to 255. In - /// these reference pages, component keys in their numerical - /// representation are written in **boldface**. - /// # [See also](key-types) - /// ## (key-types) + /// Component keys are numeric values ranging from 0 to 255. In + /// these reference pages, component keys in their numerical + /// representation are written in **boldface**. public struct Key:Hashable, Comparable, Sendable { @@ -1075,69 +957,64 @@ extension JPEG } } - /// struct JPEG.Scan - /// An image scan. + /// An image scan. /// - /// Depending on the coding process used by the image, a scan may encode - /// a select frequency band, range of bits, and subset of color components. + /// Depending on the coding process used by the image, a scan may encode + /// a select frequency band, range of bits, and subset of color components. /// - /// This type contains essentially the same information as [`(JPEG).Header.Scan`], - /// but has been validated against the global image parameters and has its - /// component keys pre-resolved to integer indices. + /// This type contains essentially the same information as [`(JPEG).Header.Scan`], + /// but has been validated against the global image parameters and has its + /// component keys pre-resolved to integer indices. public struct Scan { - /// struct JPEG.Scan.Component - /// A descriptor for a component encoded within a scan. + /// A descriptor for a component encoded within a scan. public struct Component { - /// let JPEG.Scan.Component.ci : JPEG.Component.Key - /// The key specifying the image component referenced by this descriptor. + /// The key specifying the image component referenced by this descriptor. public let ci:JPEG.Component.Key - /// let JPEG.Scan.Component.selector : (dc:JPEG.Table.HuffmanDC.Selector, ac:JPEG.Table.HuffmanAC.Selector) - /// The table selectors for the huffman tables associated with this - /// component in the context of this scan. + /// The table selectors for the huffman tables associated with this + /// component in the context of this scan. /// - /// An image component may use different huffman - /// tables in different scans. (In contrast, quantization - /// table assignments are global to the file.) The DC table is - /// used to encode or decode coefficient zero; the AC table is used - /// for all other frequency coefficients. Depending on the band - /// and bit range encoded by the image scan, one or both of the - /// huffman table selectors may be unused, and therefore may not - /// need to reference valid tables. + /// An image component may use different huffman + /// tables in different scans. (In contrast, quantization + /// table assignments are global to the file.) The DC table is + /// used to encode or decode coefficient zero; the AC table is used + /// for all other frequency coefficients. Depending on the band + /// and bit range encoded by the image scan, one or both of the + /// huffman table selectors may be unused, and therefore may not + /// need to reference valid tables. public let selector:(dc:Table.HuffmanDC.Selector, ac:Table.HuffmanAC.Selector) } - /// let JPEG.Scan.band : Swift.Range - /// The frequency band encoded by this scan. + /// The frequency band encoded by this scan. /// - /// This property specifies a range of zigzag-indexed frequency coefficients. - /// It is always within the interval of 0 to 64. If the image coding - /// process is not [`(Process).progressive(coding:differential:)`], - /// this value will be `0 ..< 64`. + /// This property specifies a range of zigzag-indexed frequency coefficients. + /// It is always within the interval of 0 to 64. If the image coding + /// process is not [`(Process).progressive(coding:differential:)`], + /// this value will be `0 ..< 64`. public - let band:Range, - /// let JPEG.Scan.bits : Swift.Range - /// The bit range encoded by this scan. + let band:Range + /// The bit range encoded by this scan. /// - /// This property specifies a range of bit indices, where bit zero is - /// the least significant bit. The upper range bound is always either - /// infinity ([`Swift.Int`max`]) or one greater than the lower bound. - /// If the image coding process is not [`(Process).progressive(coding:differential:)`], - /// this value will be `0 ..< .max`. - bits:Range, - /// let JPEG.Scan.components : [(c:Swift.Int, component:Component)] - /// The color components in this scan, in the order in which their - /// data units are interleaved. + /// This property specifies a range of bit indices, where bit zero is + /// the least significant bit. The upper range bound is always either + /// infinity ([`Swift.Int`max`]) or one greater than the lower bound. + /// If the image coding process is not [`(Process).progressive(coding:differential:)`], + /// this value will be `0 ..< .max`. + public + let bits:Range + /// The color components in this scan, in the order in which their + /// data units are interleaved. /// - /// The component descriptors are paired with resolved component indices - /// which are equivalent to the index of the image plane storing that - /// color channel. This array will always have at least one element. - components:[(c:Int, component:Component)] + /// The component descriptors are paired with resolved component indices + /// which are equivalent to the index of the image plane storing that + /// color channel. This array will always have at least one element. + public + let components:[(c:Int, component:Component)] // restrict access for synthesized init fileprivate init(band:Range, bits:Range, components:[(c:Int, component:Component)]) @@ -1148,85 +1025,65 @@ extension JPEG } } - /// struct JPEG.Layout - /// where Format:JPEG.Format - /// A specification of the components, coding process, table assignments, - /// and scan progression of an image. - /// - /// This structure records both the *recognized components* and - /// the *resident components* in an image. We draw this distinction because - /// the [`(Layout).planes`] property is allowed to include definitions for components - /// that are not part of [`(Layout).format``(Format).components`]. - /// Such components will not recieve a plane in the [`(JPEG).Data`] types, - /// but will be ignored by the scan decoder without errors. - /// - /// Non-recognized components can only occur in images decoded from JPEG files, - /// and only when using a custom [`(JPEG).Format`] type, as the built-in - /// [`JPEG.Common`] color format will never accept any component declaration - /// in a frame header that it does not also recognize. When encoding images to JPEG - /// files, all declared resident components must also be recognized components. - /// # [Creating a layout](layout-creation) - /// # [Image modes](layout-image-format) - /// # [Component membership](layout-component-membership) - /// # [Image structure](layout-image-structure) + /// A specification of the components, coding process, table assignments, + /// and scan progression of an image. + /// + /// This structure records both the *recognized components* and + /// the *resident components* in an image. We draw this distinction because + /// the [`(Layout).planes`] property is allowed to include definitions for components + /// that are not part of [`(Layout).format``(Format).components`]. + /// Such components will not recieve a plane in the [`(JPEG).Data`] types, + /// but will be ignored by the scan decoder without errors. + /// + /// Non-recognized components can only occur in images decoded from JPEG files, + /// and only when using a custom [`(JPEG).Format`] type, as the built-in + /// [`JPEG.Common`] color format will never accept any component declaration + /// in a frame header that it does not also recognize. When encoding images to JPEG + /// files, all declared resident components must also be recognized components. public struct Layout where Format:JPEG.Format { - /// let JPEG.Layout.format : Format - /// The color format of the image. - /// ## (layout-image-format) + /// The color format of the image. public let format:Format - /// let JPEG.Layout.process : JPEG.Process - /// The coding process used by the image. - /// ## (layout-image-format) + /// The coding process used by the image. public let process:Process - /// let JPEG.Layout.residents : [JPEG.Component.Key: Swift.Int] - /// The set of color components declared (or to-be-declared) in the - /// image frame header. + /// The set of color components declared (or to-be-declared) in the + /// image frame header. /// - /// The dictionary values are indices to be used with the [`planes`] property - /// on this type. - /// # [See also](layout-component-membership) - /// ## (layout-component-membership) + /// The dictionary values are indices to be used with the [`planes`] property + /// on this type. public let residents:[Component.Key: Int] - /// var JPEG.Layout.recognized : [JPEG.Component.Key] { get } - /// The set of color components in the color format of this image. - /// This set is always a subset of the resident components in the image. - /// # [See also](layout-component-membership) - /// ## (layout-component-membership) + /// The set of color components in the color format of this image. + /// This set is always a subset of the resident components in the image. public var recognized:[Component.Key] { self.format.components } - /// var JPEG.Layout.planes : [(component:JPEG.Component, qi:JPEG.Table.Quantization.Key)] { get } - /// The descriptor array for the planes in the image. + /// The descriptor array for the planes in the image. /// - /// Each descriptor consists of a [`JPEG.Component`] instance and a - /// quantization table key. On layout initialization, the library will - /// automatically assign table keys to table selectors. + /// Each descriptor consists of a [`JPEG.Component`] instance and a + /// quantization table key. On layout initialization, the library will + /// automatically assign table keys to table selectors. /// - /// The ordering of the first *k* array elements follows the order that - /// the component keys appear in the [`recognized`] property, where - /// *k* is the number of components in the image. Any - /// non-recognized resident components will occur at the end of this - /// array, can can be indexed using the values of the [`residents`] - /// dictionary. - /// ## (layout-image-structure) + /// The ordering of the first *k* array elements follows the order that + /// the component keys appear in the [`recognized`] property, where + /// *k* is the number of components in the image. Any + /// non-recognized resident components will occur at the end of this + /// array, can can be indexed using the values of the [`residents`] + /// dictionary. public internal(set) var planes:[(component:Component, qi:Table.Quantization.Key)] - /// var JPEG.Layout.definitions : [(quanta:[JPEG.Table.Quantization.Key], scans:[JPEG.Scan])] { get } - /// The sequence of scan and table definitions in the image file. + /// The sequence of scan and table definitions in the image file. /// - /// The definitions in this property are given as alternating runs - /// of quantization tables and image scans. (Image layouts do not specify - /// huffman table definitions, as the library encodes them on a per-scan - /// basis.) - /// ## (layout-image-structure) + /// The definitions in this property are given as alternating runs + /// of quantization tables and image scans. (Image layouts do not specify + /// huffman table definitions, as the library encodes them on a per-scan + /// basis.) public private(set) var definitions:[(quanta:[Table.Quantization.Key], scans:[Scan])] } @@ -1288,43 +1145,45 @@ extension JPEG.Layout ($0, -1) }) } - /// init JPEG.Layout.init(format:process:components:scans:) - /// Creates an image layout given image parameters and a scan decomposition. - /// - /// If the image coding process is a sequential process, the given scan headers - /// should be constructed using the [`(JPEG.Header.Scan).sequential(...:)`] - /// constructor. If the coding process is progressive, the scan headers - /// should be constructed with the [`(JPEG.Header.Scan).progressive(...:bits:)`], - /// [`(JPEG.Header.Scan).progressive(...:bit:)`], - /// [`(JPEG.Header.Scan).progressive(_:band:bits:)`], or - /// [`(JPEG.Header.Scan).progressive(_:band:bit:)`] constructors. - /// - /// This initializer will validate the scan progression and attempt to - /// generate a sequence of table definitions to implement the - /// quantization table relationships specified by the `components` parameter. - /// It will suffer a precondition failure if the scan progression is invalid, or - /// if it is impossible to implement the specified table relationships with - /// the number of table selectors available for the given coding process. - /// - /// This initializer will normalize all scan headers passed to the `scans` - /// argument. It will strip non-recognized components from the headers, - /// and rearrange their component descriptors in ascending numeric order. - /// It will also validate the scan headers against the `process` argument - /// with [`(Header.Scan).validate(process:band:bits:components:)`]. - /// Passing invalid scan headers will result in a precondition failure. - /// See the [advanced encoding](https://github.com/kelvin13/jpeg/tree/master/examples#advanced-encoding) - /// library tutorial to learn more about the validation rules. - /// - format : Format + /// Creates an image layout given image parameters and a scan decomposition. + /// + /// If the image coding process is a sequential process, the given scan headers + /// should be constructed using the [`(JPEG.Header.Scan).sequential(...:)`] + /// constructor. If the coding process is progressive, the scan headers + /// should be constructed with the [`(JPEG.Header.Scan).progressive(...:bits:)`], + /// [`(JPEG.Header.Scan).progressive(...:bit:)`], + /// [`(JPEG.Header.Scan).progressive(_:band:bits:)`], or + /// [`(JPEG.Header.Scan).progressive(_:band:bit:)`] constructors. + /// + /// This initializer will validate the scan progression and attempt to + /// generate a sequence of table definitions to implement the + /// quantization table relationships specified by the `components` parameter. + /// It will suffer a precondition failure if the scan progression is invalid, or + /// if it is impossible to implement the specified table relationships with + /// the number of table selectors available for the given coding process. + /// + /// This initializer will normalize all scan headers passed to the `scans` + /// argument. It will strip non-recognized components from the headers, + /// and rearrange their component descriptors in ascending numeric order. + /// It will also validate the scan headers against the `process` argument + /// with [`(Header.Scan).validate(process:band:bits:components:)`]. + /// Passing invalid scan headers will result in a precondition failure. + /// See the [advanced encoding](https://github.com/kelvin13/jpeg/tree/master/examples#advanced-encoding) + /// library tutorial to learn more about the validation rules. + /// + /// - Parameter format: /// The color format of the image. - /// - process : JPEG.Process + /// + /// - Parameter process: /// The coding process used by the image. - /// - components: [JPEG.Component.Key: (factor:(x:Swift.Int, y:Swift.Int), qi:JPEG.Table.Quantization.Key)] + /// + /// - Parameter components: /// The sampling factors and quantization table key for each component in the image. /// This dictionary must contain an entry for every component in the /// given color `format`. - /// - scans : [JPEG.Header.Scan] + /// + /// - Parameter scans: /// The scan progression of the image. - /// ## (layout-creation) public init(format:Format, process:JPEG.Process, @@ -1595,23 +1454,22 @@ extension JPEG.Header.Scan // using these apis, but this is also possible with the validating constructor, // by simply passing a fake value for `process` - /// static func JPEG.Header.Scan.sequential(_:) - /// Creates a sequential scan descriptor. + /// Creates a sequential scan descriptor. + /// + /// This constructor bypasses normal scan header validation checks. It is + /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] + /// with the `band` argument set to `0 ..< 64` and the `bits` argument set + /// to `0 ..< .max`. /// - /// This constructor bypasses normal scan header validation checks. It is - /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] - /// with the `band` argument set to `0 ..< 64` and the `bits` argument set - /// to `0 ..< .max`. - /// - components:[(ci:JPEG.Component.Key, dc:JPEG.Table.HuffmanDC.Selector, ac:JPEG.Table.HuffmanAC.Selector)] + /// - Parameter components: /// The components encoded by this scan, and associated DC and AC huffman /// table selectors. For each type of huffman table, components with the /// same table selector will share the same huffman table. Huffman tables /// will not persist in between different scans. Passing an empty array /// will result in a precondition failure. - /// - -> :Self + /// + /// - Returns: /// An unvalidated sequential scan header. - /// # [See also](scan-header-creation-sequential) - /// ## (scan-header-creation-sequential) public static func sequential(_ components: [( @@ -1624,14 +1482,9 @@ extension JPEG.Header.Scan return .init(band: 0 ..< 64, bits: 0 ..< .max, components: components.map{ .init(ci: $0.ci, selector: ($0.dc, $0.ac))}) } - /// static func JPEG.Header.Scan.sequential(...:) - /// Creates a sequential scan descriptor. - /// - /// This function is variadic sugar for [`(Scan).sequential(_:)`]. - /// - components:(ci:JPEG.Component.Key, dc:JPEG.Table.HuffmanDC.Selector, ac:JPEG.Table.HuffmanAC.Selector) - /// - -> :Self - /// # [See also](scan-header-creation-sequential) - /// ## (scan-header-creation-sequential) + /// Creates a sequential scan descriptor. + /// + /// This function is variadic sugar for [`(Scan).sequential(_:)`]. public static func sequential(_ components: ( @@ -1642,28 +1495,28 @@ extension JPEG.Header.Scan { .sequential(components) } - /// static func JPEG.Header.Scan.progressive(_:bits:) - /// Creates a progressive initial DC scan descriptor. + /// Creates a progressive initial DC scan descriptor. + /// + /// This constructor bypasses normal scan header validation checks. It is + /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] + /// with the `band` argument set to `0 ..< 1`. /// - /// This constructor bypasses normal scan header validation checks. It is - /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] - /// with the `band` argument set to `0 ..< 1`. + /// Initial DC scans only use DC huffman tables, so no AC table selectors + /// need to be specified. /// - /// Initial DC scans only use DC huffman tables, so no AC table selectors - /// need to be specified. - /// - components:[(ci:JPEG.Component.Key, dc:JPEG.Table.HuffmanDC.Selector)] + /// - Parameter components: /// The components encoded by this scan, and associated DC huffman /// table selectors. Components with the same table selector will share /// the same huffman table. Huffman tables will not persist in between /// different scans. Passing an empty array will result in a precondition failure. - /// - bits :Swift.PartialRangeFrom + /// + /// - Parameter bits: /// The range of DC bits encoded by this scan. Setting this argument to /// `0...` disables spectral selection. Passing a range with a negative /// lower bound will result in a precondition failure. - /// - -> :Self + /// + /// - Returns: /// An unvalidated initial DC scan header. - /// # [See also](scan-header-creation-progressive) - /// ## (scan-header-creation-progressive) public static func progressive(_ components:[(ci:JPEG.Component.Key, dc:JPEG.Table.HuffmanDC.Selector)], @@ -1674,15 +1527,9 @@ extension JPEG.Header.Scan return .init(band: 0 ..< 1, bits: bits.lowerBound ..< .max, components: components.map{ .init(ci: $0.ci, selector: ($0.dc, \.0))}) } - /// static func JPEG.Header.Scan.progressive(...:bits:) - /// Creates a progressive initial DC scan descriptor. - /// - /// This function is variadic sugar for [`(Scan).progressive(_:bits:)`]. - /// - components:(ci:JPEG.Component.Key, dc:JPEG.Table.HuffmanDC.Selector) - /// - bits :Swift.PartialRangeFrom - /// - -> :Self - /// # [See also](scan-header-creation-progressive) - /// ## (scan-header-creation-progressive) + /// Creates a progressive initial DC scan descriptor. + /// + /// This function is variadic sugar for [`(Scan).progressive(_:bits:)`]. public static func progressive(_ components:(ci:JPEG.Component.Key, dc:JPEG.Table.HuffmanDC.Selector)..., @@ -1690,26 +1537,26 @@ extension JPEG.Header.Scan { .progressive(components, bits: bits) } - /// static func JPEG.Header.Scan.progressive(_:bit:) - /// Creates a progressive refining DC scan descriptor. + /// Creates a progressive refining DC scan descriptor. + /// + /// This constructor bypasses normal scan header validation checks. It is + /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] + /// with the `band` argument set to `0 ..< 1` and the `bits` argument set + /// to `bit ..< bit + 1`. /// - /// This constructor bypasses normal scan header validation checks. It is - /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] - /// with the `band` argument set to `0 ..< 1` and the `bits` argument set - /// to `bit ..< bit + 1`. + /// Refining DC scans do not use entropy-coding, so no huffman table selectors + /// need to be specified. /// - /// Refining DC scans do not use entropy-coding, so no huffman table selectors - /// need to be specified. - /// - components:[JPEG.Component.Key] + /// - Parameter components: /// The components encoded by this scan. Passing an empty array will /// result in a precondition failure. - /// - bit :Swift.Int + /// + /// - Parameter bit: /// The index of the bit refined by this scan. Passing a negative index /// will result in a precondition failure. - /// - -> :Self + /// + /// - Returns: /// An unvalidated refining DC scan header. - /// # [See also](scan-header-creation-progressive) - /// ## (scan-header-creation-progressive) public static func progressive(_ components:[JPEG.Component.Key], @@ -1720,15 +1567,9 @@ extension JPEG.Header.Scan return .init(band: 0 ..< 1, bits: bit ..< bit + 1, components: components.map{ .init(ci: $0, selector: (\.0, \.0))}) } - /// static func JPEG.Header.Scan.progressive(...:bit:) - /// Creates a progressive refining DC scan descriptor. - /// - /// This function is variadic sugar for [`(Scan).progressive(_:bit:)`]. - /// - components:JPEG.Component.Key - /// - bit :Swift.Int - /// - -> :Self - /// # [See also](scan-header-creation-progressive) - /// ## (scan-header-creation-progressive) + /// Creates a progressive refining DC scan descriptor. + /// + /// This function is variadic sugar for [`(Scan).progressive(_:bit:)`]. public static func progressive(_ components:JPEG.Component.Key..., @@ -1736,29 +1577,30 @@ extension JPEG.Header.Scan { .progressive(components, bit: bit) } - /// static func JPEG.Header.Scan.progressive(_:band:bits:) - /// Creates a progressive initial AC scan descriptor. + /// Creates a progressive initial AC scan descriptor. /// - /// This constructor bypasses normal scan header validation checks. It is - /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`]. + /// This constructor bypasses normal scan header validation checks. It is + /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`]. /// - /// AC scans only use AC huffman tables, so no DC table selectors - /// need to be specified. - /// - component :(ci:JPEG.Component.Key, ac:JPEG.Table.HuffmanAC.Selector) + /// AC scans only use AC huffman tables, so no DC table selectors + /// need to be specified. + /// + /// - Parameter component: /// The component encoded by this scan, and its associated AC huffman /// table selector. Huffman tables will not persist in between /// different scans. - /// - band :Swift.Range + /// + /// - Parameter band: /// The frequency band encoded by this scan, in zigzag indices. This range /// will be clamped to the interval `1 ..< 64`. - /// - bits :Swift.PartialRangeFrom + /// + /// - Parameter bits: /// The range of AC bits encoded by this scan. Setting this argument to /// `0...` disables spectral selection. Passing a range with a negative /// lower bound will result in a precondition failure. - /// - -> :Self + /// + /// - Returns: /// An unvalidated initial AC scan header. - /// # [See also](scan-header-creation-progressive) - /// ## (scan-header-creation-progressive) public static func progressive(_ component:(ci:JPEG.Component.Key, ac:JPEG.Table.HuffmanAC.Selector), @@ -1768,29 +1610,30 @@ extension JPEG.Header.Scan return .init(band: band.clamped(to: 1 ..< 64), bits: bits.lowerBound ..< .max, components: [.init(ci: component.ci, selector: (\.0, component.ac))]) } - /// static func JPEG.Header.Scan.progressive(_:band:bit:) - /// Creates a progressive refining AC scan descriptor. + /// Creates a progressive refining AC scan descriptor. + /// + /// This constructor bypasses normal scan header validation checks. It is + /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] + /// with the `bits` argument set to `bit ..< bit + 1`. /// - /// This constructor bypasses normal scan header validation checks. It is - /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] - /// with the `bits` argument set to `bit ..< bit + 1`. + /// AC scans only use AC huffman tables, so no DC table selectors + /// need to be specified. /// - /// AC scans only use AC huffman tables, so no DC table selectors - /// need to be specified. - /// - component :(ci:JPEG.Component.Key, ac:JPEG.Table.HuffmanAC.Selector) + /// - Parameter component: /// The component encoded by this scan, and its associated AC huffman /// table selector. Huffman tables will not persist in between /// different scans. - /// - band :Swift.Range + /// + /// - Parameter band: /// The frequency band encoded by this scan, in zigzag indices. This range /// will be clamped to the interval `1 ..< 64`. - /// - bit :Swift.Int + /// + /// - Parameter bit: /// The index of the bit refined by this scan. Passing a negative index /// will result in a precondition failure. - /// - -> :Self + /// + /// - Returns: /// An unvalidated refining AC scan header. - /// # [See also](scan-header-creation-progressive) - /// ## (scan-header-creation-progressive) public static func progressive(_ component:(ci:JPEG.Component.Key, ac:JPEG.Table.HuffmanAC.Selector), @@ -1805,9 +1648,7 @@ extension JPEG.Header.Scan // bitstream extension JPEG { - /// struct JPEG.Bitstream - /// : Swift.ExpressibleByArrayLiteral - /// A padded bitstream. + /// A padded bitstream. public struct Bitstream { @@ -1958,14 +1799,13 @@ extension JPEG.Bitstream } extension JPEG.Bitstream:ExpressibleByArrayLiteral { - /// init JPEG.Bitstream.init(arrayLiteral...:) - /// ?: Swift.ExpressibleByArrayLiteral - /// Creates a bitstream from the given array literal. - /// - /// This type stores the bitstream in 16-bit atoms. If the array literal - /// does not contain an even number of bytes, the last atom is padded - /// with 1-bits. - /// - arrayLiteral : Swift.UInt8 + /// Creates a bitstream from the given array literal. + /// + /// This type stores the bitstream in 16-bit atoms. If the array literal + /// does not contain an even number of bytes, the last atom is padded + /// with 1-bits. + /// + /// - Parameter arrayLiteral: /// The raw bytes making up the bitstream. The more significant bits in /// each byte come first in the bitstream. If the bitstream does not /// correspond to a whole number of bytes, the least significant bits From a89e2d2e297628a8e02086f854c1fcc8ded343bc Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sat, 16 Nov 2024 23:51:37 +0000 Subject: [PATCH 08/18] metadata.swift --- Sources/JPEG/metadata.swift | 341 +++++++++++++++++------------------- 1 file changed, 158 insertions(+), 183 deletions(-) diff --git a/Sources/JPEG/metadata.swift b/Sources/JPEG/metadata.swift index b0279597..8c29f7a9 100644 --- a/Sources/JPEG/metadata.swift +++ b/Sources/JPEG/metadata.swift @@ -4,59 +4,53 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/. */ extension JPEG { - /// struct JPEG.JFIF - /// A JFIF metadata record. + /// A JFIF metadata record. public struct JFIF { - /// enum JPEG.JFIF.Unit - /// A unit of measurement. + /// A unit of measurement. public enum Unit { - /// case JPEG.JFIF.Unit.inches - /// The unit is inches. + /// The unit is inches. case inches - /// case JPEG.JFIF.Unit.centimeters - /// The unit is centimeters. + /// The unit is centimeters. case centimeters } - /// enum JPEG.JFIF.Version - /// A version of the [JFIF standard](https://www.w3.org/Graphics/JPEG/jfif3.pdf). + /// A version of the [JFIF standard](https://www.w3.org/Graphics/JPEG/jfif3.pdf). public enum Version { - /// case JPEG.JFIF.Version.v1_0 - /// JFIF version 1.0. + /// JFIF version 1.0. + case v1_0 - /// case JPEG.JFIF.Version.v1_1 - /// JFIF version 1.1. + /// JFIF version 1.1. + case v1_1 - /// case JPEG.JFIF.Version.v1_2 - /// JFIF version 1.2. - case v1_0, v1_1, v1_2 + /// JFIF version 1.2. + case v1_2 } - /// let JPEG.JFIF.version : Version - /// The JFIF version of this metadata record. + /// The JFIF version of this metadata record. public - let version:Version, - /// let JPEG.JFIF.density : (x:Swift.Int, y:Swift.Int, unit:Unit?) - /// The sampling density of the image. + let version:Version + /// The sampling density of the image. /// - /// The `x` and `y` fields specify the number of physical samples along - /// each dimension per `unit` length. For example, the value - /// `(x: 72, y: 72, unit: `[`Unit.inches`]`)` indicates a density of 72\ dpi. - /// If the `unit` field is `nil`, the units are unknown. - density:(x:Int, y:Int, unit:Unit?) + /// The `x` and `y` fields specify the number of physical samples along + /// each dimension per `unit` length. For example, the value + /// `(x: 72, y: 72, unit: `[`Unit.inches`]`)` indicates a density of 72\ dpi. + /// If the `unit` field is `nil`, the units are unknown. + public + let density:(x:Int, y:Int, unit:Unit?) // initializer has to live here due to compiler issue - /// init JPEG.JFIF.init(version:density:) - /// Creates a metadata record. - /// - version : Version + /// Creates a metadata record. + /// + /// - Parameter version: /// The JFIF version of the metadata record. - /// - density : (x:Swift.Int, y:Swift.Int, unit:Unit?) + /// + /// - Parameter density: /// The sampling density of the image. public init(version:Version, density:(x:Int, y:Int, unit:Unit?)) @@ -65,134 +59,106 @@ extension JPEG self.density = density } } - /// struct JPEG.EXIF - /// An EXIF metadata record. + /// An EXIF metadata record. /// - /// This type will index the root, *EXIF* (tag 34665), and *GPS* (tag 34853) - /// field groups, if they are present and well-linked in the record. + /// This type will index the root, *EXIF* (tag 34665), and *GPS* (tag 34853) + /// field groups, if they are present and well-linked in the record. /// - /// This framework only supports basic field retrieval from EXIF data. - /// It does not support constructing or editing EXIF records. Because this metadata format - /// relies extensively on internal file pointers, it is easy to accidentally - /// corrupt an EXIF segment. To perform more sophisticated operations, - /// use a dedicated library, such as [Carpaccio](https://github.com/mz2/Carpaccio). + /// This framework only supports basic field retrieval from EXIF data. + /// It does not support constructing or editing EXIF records. Because this metadata format + /// relies extensively on internal file pointers, it is easy to accidentally + /// corrupt an EXIF segment. To perform more sophisticated operations, + /// use a dedicated library, such as [Carpaccio](https://github.com/mz2/Carpaccio). public struct EXIF { - /// enum JPEG.EXIF.Endianness - /// An endianness mode. + /// An endianness mode. public enum Endianness { - /// case JPEG.EXIF.Endianness.bigEndian - /// Multibyte integers are stored most-significant-byte first. + /// Multibyte integers are stored most-significant-byte first. /// - /// For historical reasons, the [EXIF standard](https://www.exif.org/Exif2-2.PDF) - /// refers to this mode as *motorola byte order*. + /// For historical reasons, the [EXIF standard](https://www.exif.org/Exif2-2.PDF) + /// refers to this mode as *motorola byte order*. case bigEndian - /// case JPEG.EXIF.Endianness.littleEndian - /// Multibyte integers are stored least-significant-byte first. + /// Multibyte integers are stored least-significant-byte first. /// - /// For historical reasons, the [EXIF standard](https://www.exif.org/Exif2-2.PDF) - /// refers to this mode as *intel byte order*. + /// For historical reasons, the [EXIF standard](https://www.exif.org/Exif2-2.PDF) + /// refers to this mode as *intel byte order*. case littleEndian } - /// enum JPEG.EXIF.FieldType - /// A variant field type. - /// # [Field types](exif-field-types) + /// A variant field type. public enum FieldType { - /// case JPEG.EXIF.FieldType.ascii - /// A [`Swift.Unicode.ASCII.CodeUnit`] field. - /// ## (exif-field-types) + /// A [`Swift.Unicode.ASCII.CodeUnit`] field. case ascii - /// case JPEG.EXIF.FieldType.uint8 - /// A [`Swift.UInt8`] field. + /// A [`Swift.UInt8`] field. /// - /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) - /// refers to this variant type as a *byte*. - /// ## (exif-field-types) + /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) + /// refers to this variant type as a *byte*. case uint8 - /// case JPEG.EXIF.FieldType.uint16 - /// A [`Swift.UInt16`] field. + /// A [`Swift.UInt16`] field. /// - /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) - /// refers to this variant type as a *short*. - /// ## (exif-field-types) + /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) + /// refers to this variant type as a *short*. case uint16 - /// case JPEG.EXIF.FieldType.uint32 - /// A [`Swift.UInt32`] field. + /// A [`Swift.UInt32`] field. /// - /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) - /// refers to this variant type as a *long*. - /// ## (exif-field-types) + /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) + /// refers to this variant type as a *long*. case uint32 - /// case JPEG.EXIF.FieldType.int32 - /// An [`Swift.Int32`] field. + /// An [`Swift.Int32`] field. /// - /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) - /// refers to this variant type as a *slong*. - /// ## (exif-field-types) + /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) + /// refers to this variant type as a *slong*. case int32 - /// case JPEG.EXIF.FieldType.urational - /// An unsigned fraction field, represented as two [`Swift.UInt32`]s. + /// An unsigned fraction field, represented as two [`Swift.UInt32`]s. /// - /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) - /// refers to this variant type as a *rational*. - /// ## (exif-field-types) + /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) + /// refers to this variant type as a *rational*. case urational - /// case JPEG.EXIF.FieldType.rational - /// A signed fraction field, represented as two [`Swift.Int32`]s. + /// A signed fraction field, represented as two [`Swift.Int32`]s. /// - /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) - /// refers to this variant type as a *srational*. - /// ## (exif-field-types) + /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) + /// refers to this variant type as a *srational*. case rational - /// case JPEG.EXIF.FieldType.raw - /// A raw byte. + /// A raw byte. /// - /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) - /// refers to this variant type as an *undefined*. - /// ## (exif-field-types) + /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) + /// refers to this variant type as an *undefined*. case raw - /// case JPEG.EXIF.FieldType.other(code:) - /// A field of unknown type. - /// - code : Swift.UInt16 + /// A field of unknown type. + /// + /// - Parameter code: /// The type indicator code. - /// ## (exif-field-types) case other(code:UInt16) } - /// struct JPEG.EXIF.Box - /// An abstracted field value. + /// An abstracted field value. /// - /// Depending on the size of the field data, the field value may either - /// be stored inline within this instance, or be stored indirectly - /// elsewhere in the mantle of this metadata segment. + /// Depending on the size of the field data, the field value may either + /// be stored inline within this instance, or be stored indirectly + /// elsewhere in the mantle of this metadata segment. public struct Box { - /// let JPEG.EXIF.Box.contents : (Swift.UInt8, Swift.UInt8, Swift.UInt8, Swift.UInt8) - /// The contents of this field box. + /// The contents of this field box. /// - /// Depending on the field, the four bytes that make up this property - /// may encode the field value directly, or encode a 32-bit internal - /// file address pointing to the field value. - /// # [See also](exif-box-as-offset) + /// Depending on the field, the four bytes that make up this property + /// may encode the field value directly, or encode a 32-bit internal + /// file address pointing to the field value. public - let contents:(UInt8, UInt8, UInt8, UInt8), - /// let JPEG.EXIF.Box.endianness : JPEG.EXIF.Endianness - /// The byte order of the contents of this field box. + let contents:(UInt8, UInt8, UInt8, UInt8) + /// The byte order of the contents of this field box. /// - /// This is always the same as the byte order of the entire metadata record. - endianness:Endianness + /// This is always the same as the byte order of the entire metadata record. + public + let endianness:Endianness - /// var JPEG.EXIF.Box.asOffset : Swift.Int { get } - /// The contents of this field box, interpreted as a 32-bit internal - /// file pointer, and extended to the width of an [`Swift.Int`]. - /// ## (exif-box-as-offset) + /// The contents of this field box, interpreted as a 32-bit internal + /// file pointer, and extended to the width of an [`Swift.Int`]. public var asOffset:Int { @@ -210,19 +176,23 @@ extension JPEG .init(contents.3) } } - /// init JPEG.EXIF.Box.init(_:_:_:_:endianness:) - /// Creates a field box instance. - /// - b0 : Swift.UInt8 + /// Creates a field box instance. + /// + /// - Parameter b0: /// The zeroth content byte. Depending on the `endianness`, this /// is either the most- or least-significant byte. - /// - b1 : Swift.UInt8 + /// + /// - Parameter b1: /// The first content byte. - /// - b2 : Swift.UInt8 + /// + /// - Parameter b2: /// The second content byte. - /// - b3 : Swift.UInt8 + /// + /// - Parameter b3: /// The third content byte. Depending on the `endianness`, this /// is either the least- or most-significant byte. - /// - endianness : JPEG.EXIF.Endianness + /// + /// - Parameter endianness: /// The byte order of the content bytes. public init(_ b0:UInt8, _ b1:UInt8, _ b2:UInt8, _ b3:UInt8, endianness:Endianness) @@ -232,26 +202,24 @@ extension JPEG } } - /// let JPEG.EXIF.endianness : JPEG.EXIF.Endianness - /// The byte order of this metadata record. + /// The byte order of this metadata record. public let endianness:Endianness - /// var JPEG.EXIF.tags : [Swift.UInt16: Swift.Int] { get } - /// The index of tags and fields defined in this metadata record. + /// The index of tags and fields defined in this metadata record. /// - /// The tag codes are listed in the [EXIF standard](https://www.exif.org/Exif2-2.PDF). - /// The dictionary values are internal file pointers that can be - /// dereferenced manually from the [`storage`]; alternatively, the - /// [`[tag:]`] subscript can perform both the lookup and the dereferencing - /// in one step. + /// The tag codes are listed in the [EXIF standard](https://www.exif.org/Exif2-2.PDF). + /// The dictionary values are internal file pointers that can be + /// dereferenced manually from the [`storage`]; alternatively, the + /// [`[tag:]`] subscript can perform both the lookup and the dereferencing + /// in one step. public private(set) - var tags:[UInt16: Int], - /// var JPEG.EXIF.storage : [Swift.UInt8] { get } - /// The raw contents of this metadata record. + var tags:[UInt16: Int] + /// The raw contents of this metadata record. /// - /// A file pointer with a value of 0 points to the beginning of this - /// array. - storage:[UInt8] + /// A file pointer with a value of 0 points to the beginning of this + /// array. + public private(set) + var storage:[UInt8] } } @@ -296,17 +264,17 @@ extension JPEG.JFIF { static let signature:[UInt8] = [0x4a, 0x46, 0x49, 0x46, 0x00] - /// static func JPEG.JFIF.parse(_:) - /// throws - /// Parses a JFIF segment into a metadata record. + /// Parses a JFIF segment into a metadata record. /// - /// If the given data does not parse to a valid metadata record, - /// this function will throw a [`(JPEG).ParsingError`]. + /// If the given data does not parse to a valid metadata record, + /// this function will throw a [`(JPEG).ParsingError`]. /// - /// This parser ignores embedded thumbnails. - /// - data : [Swift.UInt8] + /// This parser ignores embedded thumbnails. + /// + /// - Parameter data: /// The segment data to parse. - /// - -> : Self + /// + /// - Returns: /// The parsed metadata record. public static func parse(_ data:[UInt8]) throws -> Self @@ -378,11 +346,11 @@ extension JPEG.JFIF.Unit } extension JPEG.JFIF { - /// func JPEG.JFIF.serialized() - /// Serializes this metadata record as segment data. + /// Serializes this metadata record as segment data. + /// + /// This method is the inverse of [`parse(_:)`]. /// - /// This method is the inverse of [`parse(_:)`]. - /// - -> : [Swift.UInt8] + /// - Returns: /// A marker segment body. This array does not include the marker type /// indicator, or the marker segment length field. public @@ -434,19 +402,19 @@ extension JPEG.EXIF { static let signature:[UInt8] = [0x45, 0x78, 0x69, 0x66, 0x00, 0x00] - /// static func JPEG.EXIF.parse(_:) - /// throws - /// Parses an EXIF segment into a metadata record. + /// Parses an EXIF segment into a metadata record. /// - /// If the given data does not parse to a valid metadata record, - /// this function will throw a [`(JPEG).ParsingError`]. + /// If the given data does not parse to a valid metadata record, + /// this function will throw a [`(JPEG).ParsingError`]. /// - /// This constructor will attempt to index the root, *EXIF* (tag 34665), - /// and *GPS* (tag 34853) field groups, if they are present and well-linked - /// in the segment data. This parser ignores embedded thumbnails. - /// - data : [Swift.UInt8] + /// This constructor will attempt to index the root, *EXIF* (tag 34665), + /// and *GPS* (tag 34853) field groups, if they are present and well-linked + /// in the segment data. This parser ignores embedded thumbnails. + /// + /// - Parameter data: /// The segment data to parse. - /// - -> : Self + /// + /// - Returns: /// The parsed metadata record. public static func parse(_ data:[UInt8]) throws -> Self @@ -520,15 +488,16 @@ extension JPEG.EXIF self.tags[self[offset, as: UInt16.self]] = offset } } - /// subscript JPEG.EXIF[tag:] { get } - /// Returns the field descriptor and boxed value for the given tag, - /// if it exists in this metadata record. - /// - tag : Swift.UInt16 + /// Returns the field descriptor and boxed value for the given tag, + /// if it exists in this metadata record. + /// + /// - Parameter tag: /// A tag code. The various EXIF tag codes are listed in the /// [EXIF standard](https://www.exif.org/Exif2-2.PDF). The [`tags`] /// dictionary contains an index of the known, defined tags in this metadata /// record. - /// - -> : (type:FieldType, count:Swift.Int, box:Box)? + /// + /// - Returns: /// The field descriptor and boxed value, if it exists, otherwise `nil`. public subscript(tag tag:UInt16) -> (type:FieldType, count:Int, box:Box)? @@ -550,28 +519,32 @@ extension JPEG.EXIF endianness: self.endianness) return (type, count, box) } - /// subscript JPEG.EXIF[_:as:] { get } - /// Loads the [`(FieldType).uint8`] value at the given address. - /// - offset: Swift.Int + /// Loads the [`(FieldType).uint8`] value at the given address. + /// + /// - Parameter offset: /// The address of the value to access. This pointer must be within the /// index range of [`storage`]. - /// - _ : Swift.UInt8.Type + /// + /// - Parameter _: /// This parameter must be set to [`Swift.UInt8`self`]. - /// - -> : Swift.UInt8 + /// + /// - Returns: /// The [`(FieldType).uint8`] value. public subscript(offset:Int, as _:UInt8.Type) -> UInt8 { self.storage[offset] } - /// subscript JPEG.EXIF[_:as:] { get } - /// Loads the [`(FieldType).uint16`] value at the given address. - /// - offset: Swift.Int + /// Loads the [`(FieldType).uint16`] value at the given address. + /// + /// - Parameter offset: /// The address of the value to access. This pointer, and the address after /// it must be within the index range of [`storage`]. - /// - _ : Swift.UInt16.Type + /// + /// - Parameter _: /// This parameter must be set to [`Swift.UInt16`self`]. - /// - -> : Swift.UInt16 + /// + /// - Returns: /// The [`(FieldType).uint16`] value, loaded according to the [`endianness`] /// of this metadata record. public @@ -587,14 +560,16 @@ extension JPEG.EXIF .init(self[offset + 1, as: UInt8.self]) } } - /// subscript JPEG.EXIF[_:as:] { get } - /// Loads the [`(FieldType).uint32`] value at the given address. - /// - offset: Swift.Int + /// Loads the [`(FieldType).uint32`] value at the given address. + /// + /// - Parameter offset: /// The address of the value to access. This pointer, and the next three /// addresses after it must be within the index range of [`storage`]. - /// - _ : Swift.UInt32.Type + /// + /// - Parameter _: /// This parameter must be set to [`Swift.UInt32`self`]. - /// - -> : Swift.UInt32 + /// + /// - Returns: /// The [`(FieldType).uint32`] value, loaded according to the [`endianness`] /// of this metadata record. public @@ -631,11 +606,11 @@ extension JPEG.EXIF.Endianness } extension JPEG.EXIF { - /// func JPEG.EXIF.serialized() - /// Serializes this metadata record as segment data. + /// Serializes this metadata record as segment data. + /// + /// This method is the inverse of [`parse(_:)`]. /// - /// This method is the inverse of [`parse(_:)`]. - /// - -> : [Swift.UInt8] + /// - Returns: /// A marker segment body. This array does not include the marker type /// indicator, or the marker segment length field. public From 9676ef112c89b30878f76ecc0ad30d1182d6bec3 Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sat, 16 Nov 2024 23:55:08 +0000 Subject: [PATCH 09/18] os.swift --- Sources/JPEGSystem/os.swift | 214 +++++++++++++++++------------------- 1 file changed, 103 insertions(+), 111 deletions(-) diff --git a/Sources/JPEGSystem/os.swift b/Sources/JPEGSystem/os.swift index adc8c0c0..35bf8b6b 100644 --- a/Sources/JPEGSystem/os.swift +++ b/Sources/JPEGSystem/os.swift @@ -14,29 +14,20 @@ import JPEG #if os(macOS) || os(Linux) -/// enum System -/// A namespace for platform-dependent functionality. +/// A namespace for platform-dependent functionality. /// -/// These APIs are only available on MacOS and Linux. However, the rest of the -/// framework is pure Swift and should support all Swift platforms. -/// # [File IO](system-file-io) -/// # [See also](top-level-namespaces) -/// ## (2:top-level-namespaces) +/// These APIs are only available on MacOS and Linux. However, the rest of the +/// framework is pure Swift and should support all Swift platforms. public enum System { - /// enum System.File - /// A namespace for file IO functionality. - /// ## (system-file-io) + /// A namespace for file IO functionality. public enum File { typealias Descriptor = UnsafeMutablePointer - /// struct System.File.Source - /// : JPEG.Bytestream.Source - /// A type for reading data from files on disk. - /// ## (system-file-io) + /// A type for reading data from files on disk. public struct Source { @@ -44,10 +35,7 @@ enum System let descriptor:Descriptor } - /// struct System.File.Destination - /// : JPEG.Bytestream.Destination - /// A type for writing data to files on disk. - /// ## (system-file-io) + /// A type for writing data to files on disk. public struct Destination { @@ -58,14 +46,14 @@ enum System } extension System.File.Source { - /// static func System.File.Source.open(path:_:) - /// rethrows - /// Calls a closure with an interface for reading from the specified file. + /// Calls a closure with an interface for reading from the specified file. /// - /// This method automatically closes the file when its closure argument returns. - /// - path : Swift.String + /// This method automatically closes the file when its closure argument returns. + /// + /// - Parameter path: /// The path to the file to open. - /// - body : (inout Self) throws -> R + /// + /// - Parameter body: /// A closure with a [`Source`] parameter from which data in /// the specified file can be read. This interface is only valid /// for the duration of the method’s execution. The closure is @@ -73,7 +61,8 @@ extension System.File.Source /// opened, otherwise this method will return `nil`. If `body` has a /// return value and the specified file could be opened, this method /// returns the return value of the closure. - /// - -> : R? + /// + /// - Returns: /// The return value of the closure argument, or `nil` if the specified /// file could not be opened. public static @@ -95,15 +84,15 @@ extension System.File.Source return try body(&file) } - /// func System.File.Source.read(count:) - /// ?: JPEG.Bytestream.Source - /// Reads the specified number of bytes from this file interface. + /// Reads the specified number of bytes from this file interface. + /// + /// This method only returns an array if the exact number of bytes + /// specified could be read. This method advances the file pointer. /// - /// This method only returns an array if the exact number of bytes - /// specified could be read. This method advances the file pointer. - /// - capacity : Swift.Int + /// - Parameter capacity: /// The number of bytes to read. - /// - -> : [Swift.UInt8]? + /// + /// - Returns: /// An array containing the read data, or `nil` if the specified /// number of bytes could not be read. public @@ -125,11 +114,10 @@ extension System.File.Source return buffer } - /// var System.File.Source.count : Swift.Int? { get } - /// The size of the file, in bytes, or `nil` if the file is not a regular - /// file or a link to a file. + /// The size of the file, in bytes, or `nil` if the file is not a regular + /// file or a link to a file. /// - /// This property queries the file size using `stat`. + /// This property queries the file size using `stat`. public var count:Int? { @@ -168,14 +156,14 @@ extension System.File.Source } extension System.File.Destination { - /// static func System.File.Destination.open(path:_:) - /// rethrows - /// Calls a closure with an interface for writing to the specified file. + /// Calls a closure with an interface for writing to the specified file. + /// + /// This method automatically closes the file when its closure argument returns. /// - /// This method automatically closes the file when its closure argument returns. - /// - path : Swift.String + /// - Parameter path: /// The path to the file to open. - /// - body : (inout Self) throws -> R + /// + /// - Parameter body: /// A closure with a [`Destination`] parameter representing /// the specified file to which data can be written to. This /// interface is only valid for the duration of the method’s @@ -183,7 +171,8 @@ extension System.File.Destination /// be successfully opened, otherwise this method will return `nil`. /// If `body` has a return value and the specified file could be opened, /// this method returns the return value of the closure. - /// - -> : R? + /// + /// - Returns: /// The return value of the closure argument, or `nil` if the specified /// file could not be opened. public static @@ -205,15 +194,15 @@ extension System.File.Destination return try body(&file) } - /// func System.File.Destination.write(_:) - /// ?: JPEG.Bytestream.Destination - /// Write the bytes in the given array to this file interface. + /// Write the bytes in the given array to this file interface. + /// + /// This method only returns `()` if the entire array argument could + /// be written. This method advances the file pointer. /// - /// This method only returns `()` if the entire array argument could - /// be written. This method advances the file pointer. - /// - buffer : [Swift.UInt8] + /// - Parameter buffer: /// The data to write. - /// - -> : Swift.Void? + /// + /// - Returns: /// A [`Swift.Void`] tuple if the entire array argument could be written, /// or `nil` otherwise. public @@ -245,17 +234,17 @@ extension System.File.Destination:JPEG.Bytestream.Destination // file-based encoding and decoding apis extension JPEG.Data.Spectral { - /// static func JPEG.Data.Spectral.decompress(path:) - /// throws - /// Decompresses a spectral image from the given file path. + /// Decompresses a spectral image from the given file path. /// - /// Calling this function is equivalent to calling [`System.File.Source.open(path:_:)`] - /// with the closure parameter set to [`Self``decompress(stream:)`]. + /// Calling this function is equivalent to calling [`System.File.Source.open(path:_:)`] + /// with the closure parameter set to [`Self``decompress(stream:)`]. /// - /// This function is only available on MacOS and Linux platforms. - /// - path : Swift.String + /// This function is only available on MacOS and Linux platforms. + /// + /// - Parameter path: /// A file path. - /// - -> : Self? + /// + /// - Returns: /// The decompressed image, or `nil` if the file could not be opened at /// the given file path. public static @@ -263,20 +252,20 @@ extension JPEG.Data.Spectral { return try System.File.Source.open(path: path, Self.decompress(stream:)) } - /// func JPEG.Data.Spectral.compress(path:) - /// throws - /// Compresses a spectral image to the given file path. + /// Compresses a spectral image to the given file path. + /// + /// All metadata records in this image will be emitted at the beginning of + /// the outputted file, in the order they appear in the [`metadata`] array. /// - /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. + /// Calling this function is equivalent to calling [`System.File.Destination.open(path:_:)`] + /// with the closure parameter set to [`Self``compress(stream:)`]. /// - /// Calling this function is equivalent to calling [`System.File.Destination.open(path:_:)`] - /// with the closure parameter set to [`Self``compress(stream:)`]. + /// This function is only available on MacOS and Linux platforms. /// - /// This function is only available on MacOS and Linux platforms. - /// - path : Swift.String + /// - Parameter path: /// A file path. - /// - -> : Swift.Void? + /// + /// - Returns: /// A [`Swift.Void`] tuple, or `nil` if the file could not be opened at /// the given file path. public @@ -287,18 +276,18 @@ extension JPEG.Data.Spectral } extension JPEG.Data.Planar { - /// static func JPEG.Data.Planar.decompress(path:) - /// throws - /// Decompresses a planar image from the given file path. + /// Decompresses a planar image from the given file path. + /// + /// This function is a convenience function which calls [`Spectral.decompress(path:)`] + /// to obtain a spectral image, and then calls [`(Spectral).idct()`] on the + /// output to return a planar image. /// - /// This function is a convenience function which calls [`Spectral.decompress(path:)`] - /// to obtain a spectral image, and then calls [`(Spectral).idct()`] on the - /// output to return a planar image. + /// This function is only available on MacOS and Linux platforms. /// - /// This function is only available on MacOS and Linux platforms. - /// - path : Swift.String + /// - Parameter path: /// A file path. - /// - -> : Self? + /// + /// - Returns: /// The decompressed image, or `nil` if the file could not be opened at /// the given file path. public static @@ -311,28 +300,29 @@ extension JPEG.Data.Planar } return spectral.idct() } - /// func JPEG.Data.Planar.compress(path:quanta:) - /// throws - /// Compresses a planar image to the given file path. + /// Compresses a planar image to the given file path. /// - /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. + /// All metadata records in this image will be emitted at the beginning of + /// the outputted file, in the order they appear in the [`metadata`] array. /// - /// This function is a convenience function which calls [`fdct(quanta:)`] - /// to obtain a spectral image, and then calls [`(Spectral).compress(path:)`] - /// on the output. + /// This function is a convenience function which calls [`fdct(quanta:)`] + /// to obtain a spectral image, and then calls [`(Spectral).compress(path:)`] + /// on the output. /// - /// This function is only available on MacOS and Linux platforms. - /// - path : Swift.String + /// This function is only available on MacOS and Linux platforms. + /// + /// - Parameter path: /// A file path. - /// - quanta: [JPEG.Table.Quantization.Key: [Swift.UInt16]] + /// + /// - Parameter quanta: /// The quantum values for each quanta key used by this image’s [`layout`], /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], /// and all the values must be in the correct range for that bit width. - /// - -> : Swift.Void? + /// + /// - Returns: /// A [`Swift.Void`] tuple, or `nil` if the file could not be opened at /// the given file path. public @@ -344,23 +334,24 @@ extension JPEG.Data.Planar } extension JPEG.Data.Rectangular { - /// static func JPEG.Data.Rectangular.decompress(path:cosite:) - /// throws - /// Decompresses a rectangular image from the given file path. + /// Decompresses a rectangular image from the given file path. /// - /// This function is a convenience function which calls [`Planar.decompress(path:)`] - /// to obtain a planar image, and then calls [`(Planar).interleaved(cosite:)`] - /// on the output to return a rectangular image. + /// This function is a convenience function which calls [`Planar.decompress(path:)`] + /// to obtain a planar image, and then calls [`(Planar).interleaved(cosite:)`] + /// on the output to return a rectangular image. /// - /// This function is only available on MacOS and Linux platforms. - /// - path : Swift.String + /// This function is only available on MacOS and Linux platforms. + /// + /// - Parameter path: /// A file path. - /// - cosited : Swift.Bool + /// + /// - Parameter cosited: /// The upsampling method to use. Setting this parameter to `true` co-sites /// the samples; setting it to `false` centers them instead. /// /// The default value is `false`. - /// - -> : Self? + /// + /// - Returns: /// The decompressed image, or `nil` if the file could not be opened at /// the given file path. public static @@ -374,28 +365,29 @@ extension JPEG.Data.Rectangular return planar.interleaved(cosite: cosited) } - /// func JPEG.Data.Rectangular.compress(path:quanta:) - /// throws - /// Compresses a rectangular image to the given file path. + /// Compresses a rectangular image to the given file path. /// - /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. + /// All metadata records in this image will be emitted at the beginning of + /// the outputted file, in the order they appear in the [`metadata`] array. /// - /// This function is a convenience function which calls [`decomposed()`] - /// to obtain a planar image, and then calls [`(Planar).compress(path:quanta:)`] - /// on the output. + /// This function is a convenience function which calls [`decomposed()`] + /// to obtain a planar image, and then calls [`(Planar).compress(path:quanta:)`] + /// on the output. /// - /// This function is only available on MacOS and Linux platforms. - /// - path : Swift.String + /// This function is only available on MacOS and Linux platforms. + /// + /// - Parameter path: /// A file path. - /// - quanta: [JPEG.Table.Quantization.Key: [Swift.UInt16]] + /// + /// - Parameter quanta: /// The quantum values for each quanta key used by this image’s [`layout`], /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], /// and all the values must be in the correct range for that bit width. - /// - -> : Swift.Void? + /// + /// - Returns: /// A [`Swift.Void`] tuple, or `nil` if the file could not be opened at /// the given file path. public From 1ecf82f6c8c8145a4e7b6b21fdd577c327fd208c Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sun, 17 Nov 2024 00:00:05 +0000 Subject: [PATCH 10/18] reformat scoped codelinks --- Sources/JPEG/decode.swift | 84 ++++++++++++++++++------------------- Sources/JPEG/encode.swift | 16 +++---- Sources/JPEG/error.swift | 6 +-- Sources/JPEG/jpeg.swift | 74 ++++++++++++++++---------------- Sources/JPEG/metadata.swift | 16 +++---- Sources/JPEGSystem/os.swift | 8 ++-- 6 files changed, 102 insertions(+), 102 deletions(-) diff --git a/Sources/JPEG/decode.swift b/Sources/JPEG/decode.swift index f21949ce..9ed92853 100644 --- a/Sources/JPEG/decode.swift +++ b/Sources/JPEG/decode.swift @@ -7,7 +7,7 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/. */ /// A source bytestream. /// /// To implement a custom data source type, conform it to this protocol by -/// implementing [`(Source).read(count:)`]. It can +/// implementing ``Source/read(count:)``. It can /// then be used with the library’s core decompression interfaces. public protocol _JPEGBytestreamSource @@ -87,7 +87,7 @@ extension JPEG.Bytestream.Source /// with the `prefix` parameter set to `false`, except that the empty /// prefix array is omitted from the return value. /// - /// This function can throw a [`(JPEG).LexingError`] if it encounters an + /// This function can throw a ``JPEG/LexingError`` if it encounters an /// unexpected end-of-stream. /// /// - Returns: @@ -102,14 +102,14 @@ extension JPEG.Bytestream.Source /// Optionally lexes a single entropy-coded segment followed by a single marker /// segment from this bytestream. /// - /// This function can throw a [`(JPEG).LexingError`] if it encounters an + /// This function can throw a ``JPEG/LexingError`` if it encounters an /// unexpected end-of-stream. /// /// - Parameter prefix: /// Whether this function should expect an entropy-coded segment prefixed /// to the marker segment. If this parameter is set to `false`, and this /// function encounters a prefixed entropy-coded segment, it will throw - /// a [`(JPEG).LexingError`]. + /// a ``JPEG/LexingError``. /// /// - Returns: /// A tuple containing the entropy-coded segment, marker segment type, @@ -410,7 +410,7 @@ extension JPEG.Table.Quantization /// /// - Parameter values: /// The quantum values, in zigzag order. This array must have exactly 64 - /// elements. If the `precision` is [`(Precision).uint8`], all of the values + /// elements. If the `precision` is ``Precision/uint8``, all of the values /// must be within the range of a [`Swift.UInt8`]. Passing an invalid /// array will result in a precondition failure. /// @@ -428,10 +428,10 @@ extension JPEG.Table.Quantization } extension JPEG.Table { - /// Parses a [`(Marker).huffman`] segment into huffman tables. + /// Parses a ``Marker/huffman`` segment into huffman tables. /// /// If the given data does not parse to valid huffman tables, this function - /// will throw a [`(JPEG).ParsingError`]. + /// will throw a ``JPEG/ParsingError``. /// /// - Parameter data: /// The segment data to parse. @@ -521,10 +521,10 @@ extension JPEG.Table return tables } - /// Parses a [`(Marker).quantization`] segment into huffman tables. + /// Parses a ``Marker/quantization`` segment into huffman tables. /// /// If the given data does not parse to valid quantization tables, this function - /// will throw a [`(JPEG).ParsingError`]. + /// will throw a ``JPEG/ParsingError``. /// /// - Parameter data: /// The segment data to parse. @@ -584,10 +584,10 @@ extension JPEG.Table // frame/scan header parsing extension JPEG.Header.HeightRedefinition { - /// Parses a [`(Marker).height`] segment into a height redefinition. + /// Parses a ``Marker/height`` segment into a height redefinition. /// /// If the given data does not parse to a valid height redefinition, - /// this function will throw a [`(JPEG).ParsingError`]. + /// this function will throw a ``JPEG/ParsingError``. /// /// - Parameter data: /// The segment data to parse. @@ -608,10 +608,10 @@ extension JPEG.Header.HeightRedefinition } extension JPEG.Header.RestartInterval { - /// Parses an [`(Marker).interval`] segment into a restart interval definition. + /// Parses an ``Marker/interval`` segment into a restart interval definition. /// /// If the given data does not parse to a valid restart interval definition, - /// this function will throw a [`(JPEG).ParsingError`]. + /// this function will throw a ``JPEG/ParsingError``. /// /// - Parameter data: /// The segment data to parse. @@ -637,31 +637,31 @@ extension JPEG.Header.Frame /// /// If the given parameters are not consistent with one another, and the /// [JPEG standard](https://www.w3.org/Graphics/JPEG/itu-t81.pdf), this - /// function will throw a [`(JPEG).ParsingError`], unless otherwise noted. + /// function will throw a ``JPEG/ParsingError``, unless otherwise noted. /// /// - Parameter process: /// The coding process used by the image. /// /// - Parameter precision: - /// The bit depth of the image. If the `process` is [`(JPEG.Process).baseline`], - /// this parameter must be 8. If the `process` is [`(JPEG.Process).extended(coding:differential:)`] - /// or [`(JPEG.Process).progressive(coding:differential:)`], this parameter - /// must be either 8 or 12. If the process is [`(JPEG.Process).lossless(coding:differential:)`], + /// The bit depth of the image. If the `process` is ``JPEG.Process/baseline``, + /// this parameter must be 8. If the `process` is ``JPEG.Process/extended(coding:differential:)`` + /// or ``JPEG.Process/progressive(coding:differential:)``, this parameter + /// must be either 8 or 12. If the process is ``JPEG.Process/lossless(coding:differential:)``, /// this parameter must be within the interval `2 ... 16`. /// /// - Parameter size: /// The size of the image, in pixels. Passing a negative height will result /// in a precondition failure. Passing a negative or zero width will result - /// in a [`(JPEG).ParsingError`]. This constructor treats the two failure + /// in a ``JPEG/ParsingError``. This constructor treats the two failure /// conditions differently because the latter one is the only one that can /// occur when parsing a frame header from input data. /// /// - Parameter components: /// The components in the image. This dictionary must have at least one - /// element. If the `process` is [`(JPEG.Process).progressive(coding:differential:)`], + /// element. If the `process` is ``JPEG.Process/progressive(coding:differential:)``, /// it can have no more than four elements. The sampling factors of each /// component must be within the interval `1 ... 4` in both directions. - /// if the `process` is [`(JPEG.Process).baseline`], the components can + /// if the `process` is ``JPEG.Process/baseline``, the components can /// only use the quantization table selectors `\.0` and `\.1`. /// /// - Returns: @@ -736,10 +736,10 @@ extension JPEG.Header.Frame return .init(process: process, precision: precision, size: size, components: components) } - /// Parses a [`(Marker).frame(_:)`] segment into a frame header. + /// Parses a ``Marker/frame(_:)`` segment into a frame header. /// /// If the given data does not parse to a valid frame header, - /// this function will throw a [`(JPEG).ParsingError`]. This function + /// this function will throw a ``JPEG/ParsingError``. This function /// invokes [`validate(process:precision:size:components:)`], so any errors /// it can throw can also be thrown by this function. /// @@ -812,7 +812,7 @@ extension JPEG.Header.Scan /// /// If the given parameters are not consistent with one another, and the /// [JPEG standard](https://www.w3.org/Graphics/JPEG/itu-t81.pdf), this - /// function will throw a [`(JPEG).ParsingError`]. + /// function will throw a ``JPEG/ParsingError``. /// /// - Parameter process: /// The coding process used by the image. @@ -820,7 +820,7 @@ extension JPEG.Header.Scan /// - Parameter band: /// The frequency band encoded by the scan, in zigzag order. It must be /// within the interval of 0 to 64. If the `process` is - /// [`(Process).progressive(coding:differential:)`], this parameter must + /// ``Process/progressive(coding:differential:)``, this parameter must /// either be `0 ..< 1`, or some range within the interval `1 ..< 64`. /// Otherwise, this parameter must be set to `0 ..< 64`. /// @@ -828,14 +828,14 @@ extension JPEG.Header.Scan /// The bit range encoded by the scan, where bit zero is the least significant /// bit. The upper range bound must be either infinity ([`Swift.Int`max`]) /// or one greater than the lower bound. If the `process` is not - /// [`(Process).progressive(coding:differential:)`], this value must + /// ``Process/progressive(coding:differential:)``, this value must /// be set to `0 ..< .max`. /// /// - Parameter components: /// The color components in the scan, in the order in which their /// data units are interleaved. If the scan is an AC progressive scan, /// this array must have exactly one element. Otherwise, it must have - /// between one and four elements. If the `process` is [`(Process).baseline`], + /// between one and four elements. If the `process` is ``Process/baseline``, /// the components can only use the huffman table selectors `\.0` and `\.1`. /// /// - Returns: @@ -902,10 +902,10 @@ extension JPEG.Header.Scan return .init(band: band, bits: bits, components: components) } - /// Parses a [`(Marker).scan`] segment into a scan header. + /// Parses a ``Marker/scan`` segment into a scan header. /// /// If the given data does not parse to a valid scan header, - /// this function will throw a [`(JPEG).ParsingError`]. This function + /// this function will throw a ``JPEG/ParsingError``. This function /// invokes [`validate(process:band:bits:components:)`], so any errors /// it can throw can also be thrown by this function. /// @@ -1716,7 +1716,7 @@ extension JPEG.Data.Spectral.Quanta:RandomAccessCollection /// Returns the index of the table with the given key. /// /// An instance of this type which is part of a [`Spectral`] - /// instance will always contain all quanta keys used by its [`(Spectral).layout`], + /// instance will always contain all quanta keys used by its ``Spectral/layout``, /// including keys used only by non-recognized components. /// /// - Parameter qi: @@ -2050,7 +2050,7 @@ extension JPEG.Layout { /// The size of the minimum-coded unit of the image, in data units. /// - /// This value is the maximum of all the sampling [`(JPEG.Component).factor`]s + /// This value is the maximum of all the sampling ``JPEG.Component/factor``s /// of the components in the image, including the non-recognized components. public var scale:(x:Int, y:Int) @@ -2282,7 +2282,7 @@ extension JPEG.Data.Spectral /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width - /// determined by the [`(JPEG.Format).precision`] of the color [`(Layout).format`] + /// determined by the ``JPEG.Format/precision`` of the color ``Layout/format`` /// of the given layout, and all the values must be in the correct range /// for that bit width. /// @@ -3460,7 +3460,7 @@ extension JPEG.Context /// /// - Parameter frame: /// The frame header of the image. This frame header is used to allocate - /// a [`(Data).Spectral`] image. + /// a ``Data/Spectral`` image. public init(frame:JPEG.Header.Frame) throws { @@ -3477,7 +3477,7 @@ extension JPEG.Context } /// Updates the decoder state with the given height redefinition. /// - /// This method calls [`(Data.Spectral).set(height:)`] on the stored image. + /// This method calls ``Data.Spectral/set(height:)`` on the stored image. /// /// - Parameter height: /// The height redefinition. @@ -3497,7 +3497,7 @@ extension JPEG.Context } /// Updates the decoder state with the given DC huffman table. /// - /// This method binds the table to its target [`(Table.HuffmanDC).Selector`] + /// This method binds the table to its target ``Table.HuffmanDC/Selector`` /// within this instance. /// /// - Parameter table: @@ -3509,7 +3509,7 @@ extension JPEG.Context } /// Updates the decoder state with the given AC huffman table. /// - /// This method binds the table to its target [`(Table.HuffmanAC).Selector`] + /// This method binds the table to its target ``Table.HuffmanAC/Selector`` /// within this instance. /// /// - Parameter table: @@ -3521,7 +3521,7 @@ extension JPEG.Context } /// Updates the decoder state with the given quantization table. /// - /// This method binds the table to its target [`(Table.Quantization).Selector`] + /// This method binds the table to its target ``Table.Quantization/Selector`` /// within this instance. /// /// - Parameter table: @@ -3538,7 +3538,7 @@ extension JPEG.Context } /// Updates the decoder state with the given metadata record. /// - /// This method adds the metadata record to the [`(Data.Spectral).metadata`] + /// This method adds the metadata record to the ``Data.Spectral/metadata`` /// array in the stored image. /// /// - Parameter metadata: @@ -3564,10 +3564,10 @@ extension JPEG.Context /// - Parameter extend: /// Specifies whether or not the decoder is allowed to dynamically extend /// the height of the image if the entropy-coded segment contains more - /// rows of image data than implied by the frame header [`(Header.Frame).size`]. + /// rows of image data than implied by the frame header ``Header.Frame/size``. /// /// This argument should be set to `true` for the first scan in the file, - /// to accommodate a possible [`(Header).HeightRedefinition`], and `false` + /// to accommodate a possible ``Header/HeightRedefinition``, and `false` /// for all other scans. public mutating func push(scan:JPEG.Header.Scan, ecss:[[UInt8]], extend:Bool) throws @@ -4180,7 +4180,7 @@ extension JPEG.Data.Planar /// Decompresses a planar image from the given data source. /// /// This function is a convenience function which calls [`Spectral.decompress(stream:)`] - /// to obtain a spectral image, and then calls [`(Spectral).idct()`] on the + /// to obtain a spectral image, and then calls ``Spectral/idct()`` on the /// output to return a planar image. /// /// - Parameter stream: @@ -4201,7 +4201,7 @@ extension JPEG.Data.Rectangular /// Decompresses a rectangular image from the given data source. /// /// This function is a convenience function which calls [`Planar.decompress(stream:)`] - /// to obtain a planar image, and then calls [`(Planar).interleaved(cosite:)`] + /// to obtain a planar image, and then calls ``Planar/interleaved(cosite:)`` /// on the output to return a rectangular image. /// /// - Parameter stream: diff --git a/Sources/JPEG/encode.swift b/Sources/JPEG/encode.swift index 6abf878c..1cb28e8b 100644 --- a/Sources/JPEG/encode.swift +++ b/Sources/JPEG/encode.swift @@ -372,7 +372,7 @@ extension JPEG.Data.Rectangular /// This method uses a basic box-filter to perform downsampling. A box-filter /// is a relatively poor low-pass filter, so it may be worthwhile to /// perform component resampling manually and construct a planar image - /// directly using [`(Planar).init(size:layout:metadata:initializingWith:)`]. + /// directly using ``Planar/init(size:layout:metadata:initializingWith:)``. /// /// This method is the inverse of [`Planar.interleaved(cosite:)`]. /// @@ -471,7 +471,7 @@ extension JPEG.Data.Spectral /// /// The encoded frame header contains only the recognized components in /// this image. It encodes the image height eagerly (as opposed to lazily, - /// with a [`(JPEG.Header).HeightRedefinition`] header). + /// with a ``JPEG.Header/HeightRedefinition`` header). /// /// - Returns: /// The encoded frame header. @@ -682,7 +682,7 @@ extension JPEG.Table.Huffman /// An array of symbol frequencies. This array must contain exactly 256 /// elements, corresponding to the 256 possible 8-bit symbols. The *i*th /// array element specifies the frequency of the symbol with the - /// [`(Bitstream.AnySymbol).value`] *i*. + /// ``Bitstream.AnySymbol/value`` *i*. /// /// At least one symbol must have a non-zero frequency. Passing an invalid /// frequency array will result in a precondition failure. @@ -1801,7 +1801,7 @@ extension JPEG.Header.Scan /// A destination bytestream. /// /// To implement a custom data destination type, conform it to this protocol by -/// implementing [`(Destination).write(_:)`]. It can +/// implementing ``Destination/write(_:)``. It can /// then be used with the library’s core compression interfaces. public protocol _JPEGBytestreamDestination @@ -1834,7 +1834,7 @@ extension JPEG.Bytestream.Destination /// Formats a single marker into this bytestream. /// /// This function is meant to be used with markers without segment bodies, - /// such as [`(Marker).start`], [`(Marker).end`], and [`(Marker).restart(_:)`]. + /// such as ``Marker/start``, ``Marker/end``, and ``Marker/restart(_:)``. /// /// This function can throw a [`FormattingError`] if it fails to write /// to the bytestream. @@ -1854,7 +1854,7 @@ extension JPEG.Bytestream.Destination /// /// This function will output a segment length field, even if no marker data /// is provided, and so should *not* be used with markers without segment - /// bodies, such as [`(Marker).start`], [`(Marker).end`], and [`(Marker).restart(_:)`]. + /// bodies, such as ``Marker/start``, ``Marker/end``, and ``Marker/restart(_:)``. /// /// This function can throw a [`FormattingError`] if it fails to write /// to the bytestream. @@ -1970,7 +1970,7 @@ extension JPEG.Data.Planar /// the outputted file, in the order they appear in the [`metadata`] array. /// /// This function is a convenience function which calls [`fdct(quanta:)`] - /// to obtain a spectral image, and then calls [`(Spectral).compress(stream:)`] + /// to obtain a spectral image, and then calls ``Spectral/compress(stream:)`` /// on the output. /// /// - Parameter stream: @@ -1999,7 +1999,7 @@ extension JPEG.Data.Rectangular /// the outputted file, in the order they appear in the [`metadata`] array. /// /// This function is a convenience function which calls [`decomposed()`] - /// to obtain a planar image, and then calls [`(Planar).compress(stream:quanta:)`] + /// to obtain a planar image, and then calls ``Planar/compress(stream:quanta:)`` /// on the output. /// /// - Parameter stream: diff --git a/Sources/JPEG/error.swift b/Sources/JPEG/error.swift index c8ddd3b4..537cea10 100644 --- a/Sources/JPEG/error.swift +++ b/Sources/JPEG/error.swift @@ -618,14 +618,14 @@ extension JPEG case prematureEndOfImage /// The image coding process was anything other than - /// [`(Process).baseline`], or [`(Process).extended(coding:differential:)`] - /// and [`(Process).progressive(coding:differential:)`] with [`(Process.Coding).huffman`] + /// ``Process/baseline``, or ``Process/extended(coding:differential:)`` + /// and ``Process/progressive(coding:differential:)`` with ``Process.Coding/huffman`` /// coding and `differential` set to `false`. /// /// - Parameter _: /// The coding process used by the image. case unsupportedFrameCodingProcess(Process) - /// A [`(Format).recognize(_:precision:)`] implementation failed to + /// A ``Format/recognize(_:precision:)`` implementation failed to /// recognize the component set and bit precision in a frame header. /// /// - Parameter components: diff --git a/Sources/JPEG/jpeg.swift b/Sources/JPEG/jpeg.swift index f3e09563..642bbbea 100644 --- a/Sources/JPEG/jpeg.swift +++ b/Sources/JPEG/jpeg.swift @@ -5,7 +5,7 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/. */ /// A color format, determined by the bit depth and set of component keys in /// a frame header. /// -/// The coding [`(JPEG).Process`] of an image may place restrictions on which +/// The coding ``JPEG/Process`` of an image may place restrictions on which /// combinations of component sets and bit precisions are valid. public protocol _JPEGFormat @@ -28,7 +28,7 @@ protocol _JPEGFormat /// The ordering is used to determine plane index assignments when initializing /// an image layout. This property should never be empty. It is allowed /// for this array to contain fewer components than were detected by the - /// [`(Format).recognize(_:precision:)`] constructor. + /// ``Format/recognize(_:precision:)`` constructor. var components:[JPEG.Component.Key] { get @@ -284,7 +284,7 @@ extension JPEG.Common:JPEG.Format /// Detects this color format, given a set of component keys and a bit depth. /// - /// If this constructor detects a [`(Common).nonconforming3x8(_:_:_:)`] + /// If this constructor detects a ``Common/nonconforming3x8(_:_:_:)`` /// color format, it will populate the associated values with the keys in /// ascending order. /// @@ -325,7 +325,7 @@ extension JPEG.Common:JPEG.Format } /// The set of component keys for this color format. /// - /// If this instance is a [`(Common).nonconforming3x8(_:_:_:)`] color format, + /// If this instance is a ``Common/nonconforming3x8(_:_:_:)`` color format, /// the array contains the component keys in the order they appear /// in the instance’s associated values. public @@ -531,10 +531,10 @@ extension JPEG /// The [JPEG standard](https://www.w3.org/Graphics/JPEG/itu-t81.pdf) /// specifies several subformats of the JPEG format known as *coding processes*. /// The library can recognize images using any coding process, but - /// only supports encoding and decoding images using the [`(Process).baseline`], - /// [`(Process).extended(coding:differential:)`], or - /// [`(Process).progressive(coding:differential:)`] processes with - /// [`(Process.Coding).huffman`] entropy coding and the `differential` flag + /// only supports encoding and decoding images using the ``Process/baseline``, + /// ``Process/extended(coding:differential:)``, or + /// ``Process/progressive(coding:differential:)`` processes with + /// ``Process.Coding/huffman`` entropy coding and the `differential` flag /// set to `false`. public enum Process:Sendable @@ -553,13 +553,13 @@ extension JPEG /// /// This is a sequential coding process. It allows up to two simultaneously /// referenced tables of each type. It can only be used with color formats - /// with a bit [`(JPEG.Format).precision`] of 8. + /// with a bit ``JPEG.Format/precision`` of 8. case baseline /// The extended coding process. /// /// This is a sequential coding process. It allows up to four simultaneously /// referenced tables of each type. It can only be used with color formats - /// with a bit [`(JPEG.Format).precision`] of 8 or 12. + /// with a bit ``JPEG.Format/precision`` of 8 or 12. /// /// - Parameter coding: /// The entropy coding used by this coding process. @@ -572,7 +572,7 @@ extension JPEG /// /// This is a progressive coding process. It allows up to four simultaneously /// referenced tables of each type. It can only be used with color formats - /// with a bit [`(JPEG.Format).precision`] of 8 or 12, and no more than + /// with a bit ``JPEG.Format/precision`` of 8 or 12, and no more than /// four components. /// /// - Parameter coding: @@ -739,7 +739,7 @@ extension JPEG { /// A height redefinition header. /// - /// This structure is the parsed form of a [`(JPEG.Marker).height`] + /// This structure is the parsed form of a ``JPEG.Marker/height`` /// marker segment. public struct HeightRedefinition @@ -763,7 +763,7 @@ extension JPEG } /// A restart interval definition header. /// - /// This structure is the parsed form of an [`(JPEG.Marker).interval`] + /// This structure is the parsed form of an ``JPEG.Marker/interval`` /// marker segment. It can modify or clear the restart interval of an /// image. public @@ -790,10 +790,10 @@ extension JPEG } /// A frame header. /// - /// This structure is the parsed form of a [`(JPEG.Marker).frame(_:)`] + /// This structure is the parsed form of a ``JPEG.Marker/frame(_:)`` /// marker segment. In non-hierarchical mode images, it defines global /// image parameters. It contains some of the information needed to - /// fully-define an image [`(JPEG).Layout`]. + /// fully-define an image ``JPEG/Layout``. public struct Frame { @@ -807,7 +807,7 @@ extension JPEG /// /// The width is always positive. The height can be either positive /// or zero, if the height is to be defined later by a - /// [`(JPEG.Header).HeightRedefinition`] header. + /// ``JPEG.Header/HeightRedefinition`` header. public let size:(x:Int, y:Int) /// The components in this image. @@ -818,7 +818,7 @@ extension JPEG } /// A scan header. /// - /// This structure is the parsed form of a [`(JPEG.Marker).scan`] + /// This structure is the parsed form of a ``JPEG.Marker/scan`` /// marker segment. It defines scan-level image parameters. The library /// validates these structures against the global image parameters to /// create the [`JPEG.Scan`] structures elsewhere in the library API. @@ -962,7 +962,7 @@ extension JPEG /// Depending on the coding process used by the image, a scan may encode /// a select frequency band, range of bits, and subset of color components. /// - /// This type contains essentially the same information as [`(JPEG).Header.Scan`], + /// This type contains essentially the same information as ``JPEG/Header.Scan``, /// but has been validated against the global image parameters and has its /// component keys pre-resolved to integer indices. public @@ -994,7 +994,7 @@ extension JPEG /// /// This property specifies a range of zigzag-indexed frequency coefficients. /// It is always within the interval of 0 to 64. If the image coding - /// process is not [`(Process).progressive(coding:differential:)`], + /// process is not ``Process/progressive(coding:differential:)``, /// this value will be `0 ..< 64`. public let band:Range @@ -1003,7 +1003,7 @@ extension JPEG /// This property specifies a range of bit indices, where bit zero is /// the least significant bit. The upper range bound is always either /// infinity ([`Swift.Int`max`]) or one greater than the lower bound. - /// If the image coding process is not [`(Process).progressive(coding:differential:)`], + /// If the image coding process is not ``Process/progressive(coding:differential:)``, /// this value will be `0 ..< .max`. public let bits:Range @@ -1030,13 +1030,13 @@ extension JPEG /// /// This structure records both the *recognized components* and /// the *resident components* in an image. We draw this distinction because - /// the [`(Layout).planes`] property is allowed to include definitions for components + /// the ``Layout/planes`` property is allowed to include definitions for components /// that are not part of [`(Layout).format``(Format).components`]. - /// Such components will not recieve a plane in the [`(JPEG).Data`] types, + /// Such components will not recieve a plane in the ``JPEG/Data`` types, /// but will be ignored by the scan decoder without errors. /// /// Non-recognized components can only occur in images decoded from JPEG files, - /// and only when using a custom [`(JPEG).Format`] type, as the built-in + /// and only when using a custom ``JPEG/Format`` type, as the built-in /// [`JPEG.Common`] color format will never accept any component declaration /// in a frame header that it does not also recognize. When encoding images to JPEG /// files, all declared resident components must also be recognized components. @@ -1148,12 +1148,12 @@ extension JPEG.Layout /// Creates an image layout given image parameters and a scan decomposition. /// /// If the image coding process is a sequential process, the given scan headers - /// should be constructed using the [`(JPEG.Header.Scan).sequential(...:)`] + /// should be constructed using the ``JPEG.Header.Scan/sequential(...:)`` /// constructor. If the coding process is progressive, the scan headers - /// should be constructed with the [`(JPEG.Header.Scan).progressive(...:bits:)`], - /// [`(JPEG.Header.Scan).progressive(...:bit:)`], - /// [`(JPEG.Header.Scan).progressive(_:band:bits:)`], or - /// [`(JPEG.Header.Scan).progressive(_:band:bit:)`] constructors. + /// should be constructed with the ``JPEG.Header.Scan/progressive(...:bits:)``, + /// ``JPEG.Header.Scan/progressive(...:bit:)``, + /// ``JPEG.Header.Scan/progressive(_:band:bits:)``, or + /// ``JPEG.Header.Scan/progressive(_:band:bit:)`` constructors. /// /// This initializer will validate the scan progression and attempt to /// generate a sequence of table definitions to implement the @@ -1166,7 +1166,7 @@ extension JPEG.Layout /// argument. It will strip non-recognized components from the headers, /// and rearrange their component descriptors in ascending numeric order. /// It will also validate the scan headers against the `process` argument - /// with [`(Header.Scan).validate(process:band:bits:components:)`]. + /// with ``Header.Scan/validate(process:band:bits:components:)``. /// Passing invalid scan headers will result in a precondition failure. /// See the [advanced encoding](https://github.com/kelvin13/jpeg/tree/master/examples#advanced-encoding) /// library tutorial to learn more about the validation rules. @@ -1457,7 +1457,7 @@ extension JPEG.Header.Scan /// Creates a sequential scan descriptor. /// /// This constructor bypasses normal scan header validation checks. It is - /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] + /// otherwise equivalent to calling ``Header.Scan/validate(process:band:bits:components:)`` /// with the `band` argument set to `0 ..< 64` and the `bits` argument set /// to `0 ..< .max`. /// @@ -1484,7 +1484,7 @@ extension JPEG.Header.Scan } /// Creates a sequential scan descriptor. /// - /// This function is variadic sugar for [`(Scan).sequential(_:)`]. + /// This function is variadic sugar for ``Scan/sequential(_:)``. public static func sequential(_ components: ( @@ -1498,7 +1498,7 @@ extension JPEG.Header.Scan /// Creates a progressive initial DC scan descriptor. /// /// This constructor bypasses normal scan header validation checks. It is - /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] + /// otherwise equivalent to calling ``Header.Scan/validate(process:band:bits:components:)`` /// with the `band` argument set to `0 ..< 1`. /// /// Initial DC scans only use DC huffman tables, so no AC table selectors @@ -1529,7 +1529,7 @@ extension JPEG.Header.Scan } /// Creates a progressive initial DC scan descriptor. /// - /// This function is variadic sugar for [`(Scan).progressive(_:bits:)`]. + /// This function is variadic sugar for ``Scan/progressive(_:bits:)``. public static func progressive(_ components:(ci:JPEG.Component.Key, dc:JPEG.Table.HuffmanDC.Selector)..., @@ -1540,7 +1540,7 @@ extension JPEG.Header.Scan /// Creates a progressive refining DC scan descriptor. /// /// This constructor bypasses normal scan header validation checks. It is - /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] + /// otherwise equivalent to calling ``Header.Scan/validate(process:band:bits:components:)`` /// with the `band` argument set to `0 ..< 1` and the `bits` argument set /// to `bit ..< bit + 1`. /// @@ -1569,7 +1569,7 @@ extension JPEG.Header.Scan } /// Creates a progressive refining DC scan descriptor. /// - /// This function is variadic sugar for [`(Scan).progressive(_:bit:)`]. + /// This function is variadic sugar for ``Scan/progressive(_:bit:)``. public static func progressive(_ components:JPEG.Component.Key..., @@ -1580,7 +1580,7 @@ extension JPEG.Header.Scan /// Creates a progressive initial AC scan descriptor. /// /// This constructor bypasses normal scan header validation checks. It is - /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`]. + /// otherwise equivalent to calling ``Header.Scan/validate(process:band:bits:components:)``. /// /// AC scans only use AC huffman tables, so no DC table selectors /// need to be specified. @@ -1613,7 +1613,7 @@ extension JPEG.Header.Scan /// Creates a progressive refining AC scan descriptor. /// /// This constructor bypasses normal scan header validation checks. It is - /// otherwise equivalent to calling [`(Header.Scan).validate(process:band:bits:components:)`] + /// otherwise equivalent to calling ``Header.Scan/validate(process:band:bits:components:)`` /// with the `bits` argument set to `bit ..< bit + 1`. /// /// AC scans only use AC huffman tables, so no DC table selectors diff --git a/Sources/JPEG/metadata.swift b/Sources/JPEG/metadata.swift index 8c29f7a9..2ebedccc 100644 --- a/Sources/JPEG/metadata.swift +++ b/Sources/JPEG/metadata.swift @@ -267,7 +267,7 @@ extension JPEG.JFIF /// Parses a JFIF segment into a metadata record. /// /// If the given data does not parse to a valid metadata record, - /// this function will throw a [`(JPEG).ParsingError`]. + /// this function will throw a ``JPEG/ParsingError``. /// /// This parser ignores embedded thumbnails. /// @@ -405,7 +405,7 @@ extension JPEG.EXIF /// Parses an EXIF segment into a metadata record. /// /// If the given data does not parse to a valid metadata record, - /// this function will throw a [`(JPEG).ParsingError`]. + /// this function will throw a ``JPEG/ParsingError``. /// /// This constructor will attempt to index the root, *EXIF* (tag 34665), /// and *GPS* (tag 34853) field groups, if they are present and well-linked @@ -519,7 +519,7 @@ extension JPEG.EXIF endianness: self.endianness) return (type, count, box) } - /// Loads the [`(FieldType).uint8`] value at the given address. + /// Loads the ``FieldType/uint8`` value at the given address. /// /// - Parameter offset: /// The address of the value to access. This pointer must be within the @@ -529,13 +529,13 @@ extension JPEG.EXIF /// This parameter must be set to [`Swift.UInt8`self`]. /// /// - Returns: - /// The [`(FieldType).uint8`] value. + /// The ``FieldType/uint8`` value. public subscript(offset:Int, as _:UInt8.Type) -> UInt8 { self.storage[offset] } - /// Loads the [`(FieldType).uint16`] value at the given address. + /// Loads the ``FieldType/uint16`` value at the given address. /// /// - Parameter offset: /// The address of the value to access. This pointer, and the address after @@ -545,7 +545,7 @@ extension JPEG.EXIF /// This parameter must be set to [`Swift.UInt16`self`]. /// /// - Returns: - /// The [`(FieldType).uint16`] value, loaded according to the [`endianness`] + /// The ``FieldType/uint16`` value, loaded according to the [`endianness`] /// of this metadata record. public subscript(offset:Int, as _:UInt16.Type) -> UInt16 @@ -560,7 +560,7 @@ extension JPEG.EXIF .init(self[offset + 1, as: UInt8.self]) } } - /// Loads the [`(FieldType).uint32`] value at the given address. + /// Loads the ``FieldType/uint32`` value at the given address. /// /// - Parameter offset: /// The address of the value to access. This pointer, and the next three @@ -570,7 +570,7 @@ extension JPEG.EXIF /// This parameter must be set to [`Swift.UInt32`self`]. /// /// - Returns: - /// The [`(FieldType).uint32`] value, loaded according to the [`endianness`] + /// The ``FieldType/uint32`` value, loaded according to the [`endianness`] /// of this metadata record. public subscript(offset:Int, as _:UInt32.Type) -> UInt32 diff --git a/Sources/JPEGSystem/os.swift b/Sources/JPEGSystem/os.swift index 35bf8b6b..2f292675 100644 --- a/Sources/JPEGSystem/os.swift +++ b/Sources/JPEGSystem/os.swift @@ -279,7 +279,7 @@ extension JPEG.Data.Planar /// Decompresses a planar image from the given file path. /// /// This function is a convenience function which calls [`Spectral.decompress(path:)`] - /// to obtain a spectral image, and then calls [`(Spectral).idct()`] on the + /// to obtain a spectral image, and then calls ``Spectral/idct()`` on the /// output to return a planar image. /// /// This function is only available on MacOS and Linux platforms. @@ -306,7 +306,7 @@ extension JPEG.Data.Planar /// the outputted file, in the order they appear in the [`metadata`] array. /// /// This function is a convenience function which calls [`fdct(quanta:)`] - /// to obtain a spectral image, and then calls [`(Spectral).compress(path:)`] + /// to obtain a spectral image, and then calls ``Spectral/compress(path:)`` /// on the output. /// /// This function is only available on MacOS and Linux platforms. @@ -337,7 +337,7 @@ extension JPEG.Data.Rectangular /// Decompresses a rectangular image from the given file path. /// /// This function is a convenience function which calls [`Planar.decompress(path:)`] - /// to obtain a planar image, and then calls [`(Planar).interleaved(cosite:)`] + /// to obtain a planar image, and then calls ``Planar/interleaved(cosite:)`` /// on the output to return a rectangular image. /// /// This function is only available on MacOS and Linux platforms. @@ -371,7 +371,7 @@ extension JPEG.Data.Rectangular /// the outputted file, in the order they appear in the [`metadata`] array. /// /// This function is a convenience function which calls [`decomposed()`] - /// to obtain a planar image, and then calls [`(Planar).compress(path:quanta:)`] + /// to obtain a planar image, and then calls ``Planar/compress(path:quanta:)`` /// on the output. /// /// This function is only available on MacOS and Linux platforms. From 345375cf825ac7d95e07e5dedf8211431973775e Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sun, 17 Nov 2024 00:00:43 +0000 Subject: [PATCH 11/18] migrate stdlib codelinks --- Sources/JPEG/common.swift | 12 ++++++------ Sources/JPEG/decode.swift | 18 +++++++++--------- Sources/JPEG/encode.swift | 2 +- Sources/JPEG/metadata.swift | 16 ++++++++-------- Sources/JPEGSystem/os.swift | 8 ++++---- 5 files changed, 28 insertions(+), 28 deletions(-) diff --git a/Sources/JPEG/common.swift b/Sources/JPEG/common.swift index ff91369d..9a173576 100644 --- a/Sources/JPEG/common.swift +++ b/Sources/JPEG/common.swift @@ -10,7 +10,7 @@ enum General extension General { - /// A property wrapper providing an immutable [`Swift.Int`] interface backed + /// A property wrapper providing an immutable ``Int`` interface backed /// by a different integer type. @propertyWrapper public @@ -28,14 +28,14 @@ extension General { self.storage = .init(truncatingIfNeeded: wrappedValue) } - /// The value wrapped by this property wrapper, expanded to an [`Swift.Int`]. + /// The value wrapped by this property wrapper, expanded to an ``Int``. public var wrappedValue:Int { .init(self.storage) } } - /// A property wrapper providing an immutable `(`[`Swift.Int`]`, `[`Swift.Int`]`)` + /// A property wrapper providing an immutable `(```Int```, ```Int```)` /// interface backed by a different integer type. @propertyWrapper public @@ -58,14 +58,14 @@ extension General ) } /// The values wrapped by this property wrapper, expanded to an - /// `(`[`Swift.Int`]`, `[`Swift.Int`]`)` tuple. + /// `(```Int```, ```Int```)` tuple. public var wrappedValue:(x:Int, y:Int) { (.init(self.storage.x), .init(self.storage.y)) } } - /// A property wrapper providing a mutable [`Swift.Int`] interface backed + /// A property wrapper providing a mutable ``Int`` interface backed /// by a different integer type. @propertyWrapper public @@ -83,7 +83,7 @@ extension General { self.storage = .init(truncatingIfNeeded: wrappedValue) } - /// The value wrapped by this property wrapper, expanded to an [`Swift.Int`]. + /// The value wrapped by this property wrapper, expanded to an ``Int``. public var wrappedValue:Int { diff --git a/Sources/JPEG/decode.swift b/Sources/JPEG/decode.swift index 9ed92853..a62b3fe1 100644 --- a/Sources/JPEG/decode.swift +++ b/Sources/JPEG/decode.swift @@ -411,7 +411,7 @@ extension JPEG.Table.Quantization /// - Parameter values: /// The quantum values, in zigzag order. This array must have exactly 64 /// elements. If the `precision` is ``Precision/uint8``, all of the values - /// must be within the range of a [`Swift.UInt8`]. Passing an invalid + /// must be within the range of a ``UInt8``. Passing an invalid /// array will result in a precondition failure. /// /// - Parameter target: @@ -1379,7 +1379,7 @@ extension JPEG.Data /// The sampling factors of the color component this plane stores. /// - /// This property is backed by two [`Swift.Int16`]s to circumvent compiler + /// This property is backed by two ``Int16``s to circumvent compiler /// size limits for the `read` and `modify` accessors that the image /// planes are subscriptable through. @General.Storage2 @@ -1497,7 +1497,7 @@ extension JPEG.Data /// The sampling factors of the color component this plane stores. /// - /// This property is backed by two [`Swift.Int32`]s to circumvent compiler + /// This property is backed by two ``Int32``s to circumvent compiler /// size limits for the `read` and `modify` accessors that the image /// planes are subscriptable through. @General.Storage2 @@ -1605,7 +1605,7 @@ extension JPEG.Data /// An array of interleaved samples, in row major order, and without /// padding. The array must have exactly /// [`layout``(Layout).recognized`count`]\ ×\ [`size`x`]\ ×\ [`size`y`] samples. - /// Each [`Swift.UInt16`] is one sample. The samples should not be + /// Each ``UInt16`` is one sample. The samples should not be /// normalized, so an image with a [`layout``(Layout).format``(Format).precision`] of /// 8 should only have samples in the range `0 ... 255`. public @@ -1676,7 +1676,7 @@ extension JPEG.Data.Spectral.Quanta:RandomAccessCollection /// The index of the first quantization table in this container. /// /// The default (all-zeroes) quantization table is not part of the - /// [`Swift.RandomAccessCollection`]. This index is 1 greater than the + /// ``RandomAccessCollection``. This index is 1 greater than the /// index of the default quanta. public var startIndex:Int @@ -1767,7 +1767,7 @@ extension JPEG.Data.Spectral:RandomAccessCollection /// /// - Parameter p: /// The index of the plane to access. This index must be within the index - /// bounds of this [`Swift.RandomAccessCollection`]. + /// bounds of this ``RandomAccessCollection``. /// /// - Returns: /// The plane. @@ -1825,7 +1825,7 @@ extension JPEG.Data.Planar:RandomAccessCollection /// /// - Parameter p: /// The index of the plane to access. This index must be within the index - /// bounds of this [`Swift.RandomAccessCollection`]. + /// bounds of this ``RandomAccessCollection``. /// /// - Returns: /// The plane. @@ -1907,7 +1907,7 @@ extension JPEG.Data.Spectral.Plane { /// A two-dimensional index range encompassing the data units in this plane. /// - /// This index range is a [`Swift.Sequence`] which can be used to iterate + /// This index range is a ``Sequence`` which can be used to iterate /// through its index space in row-major order. public var indices:General.Range2 @@ -1919,7 +1919,7 @@ extension JPEG.Data.Planar.Plane { /// A two-dimensional index range encompassing the data units in this plane. /// - /// This index range is a [`Swift.Sequence`] which can be used to iterate + /// This index range is a ``Sequence`` which can be used to iterate /// through its index space in row-major order. public var indices:General.Range2 diff --git a/Sources/JPEG/encode.swift b/Sources/JPEG/encode.swift index 1cb28e8b..a4b440b5 100644 --- a/Sources/JPEG/encode.swift +++ b/Sources/JPEG/encode.swift @@ -1818,7 +1818,7 @@ protocol _JPEGBytestreamDestination /// The bytes to write. /// /// - Returns: - /// A [`Swift.Void`] tuple, or `nil` if the write attempt failed. This + /// A ``Void`` tuple, or `nil` if the write attempt failed. This /// method should return `nil` even if any number of bytes less than /// `bytes.count` were successfully written. mutating diff --git a/Sources/JPEG/metadata.swift b/Sources/JPEG/metadata.swift index 2ebedccc..8b6bad3b 100644 --- a/Sources/JPEG/metadata.swift +++ b/Sources/JPEG/metadata.swift @@ -92,34 +92,34 @@ extension JPEG public enum FieldType { - /// A [`Swift.Unicode.ASCII.CodeUnit`] field. + /// A ``Unicode.ASCII.CodeUnit`` field. case ascii - /// A [`Swift.UInt8`] field. + /// A ``UInt8`` field. /// /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) /// refers to this variant type as a *byte*. case uint8 - /// A [`Swift.UInt16`] field. + /// A ``UInt16`` field. /// /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) /// refers to this variant type as a *short*. case uint16 - /// A [`Swift.UInt32`] field. + /// A ``UInt32`` field. /// /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) /// refers to this variant type as a *long*. case uint32 - /// An [`Swift.Int32`] field. + /// An ``Int32`` field. /// /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) /// refers to this variant type as a *slong*. case int32 - /// An unsigned fraction field, represented as two [`Swift.UInt32`]s. + /// An unsigned fraction field, represented as two ``UInt32``s. /// /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) /// refers to this variant type as a *rational*. case urational - /// A signed fraction field, represented as two [`Swift.Int32`]s. + /// A signed fraction field, represented as two ``Int32``s. /// /// The [EXIF standard](https://www.exif.org/Exif2-2.PDF) /// refers to this variant type as a *srational*. @@ -158,7 +158,7 @@ extension JPEG let endianness:Endianness /// The contents of this field box, interpreted as a 32-bit internal - /// file pointer, and extended to the width of an [`Swift.Int`]. + /// file pointer, and extended to the width of an ``Int``. public var asOffset:Int { diff --git a/Sources/JPEGSystem/os.swift b/Sources/JPEGSystem/os.swift index 2f292675..3204c98a 100644 --- a/Sources/JPEGSystem/os.swift +++ b/Sources/JPEGSystem/os.swift @@ -203,7 +203,7 @@ extension System.File.Destination /// The data to write. /// /// - Returns: - /// A [`Swift.Void`] tuple if the entire array argument could be written, + /// A ``Void`` tuple if the entire array argument could be written, /// or `nil` otherwise. public func write(_ buffer:[UInt8]) -> Void? @@ -266,7 +266,7 @@ extension JPEG.Data.Spectral /// A file path. /// /// - Returns: - /// A [`Swift.Void`] tuple, or `nil` if the file could not be opened at + /// A ``Void`` tuple, or `nil` if the file could not be opened at /// the given file path. public func compress(path:String) throws -> Void? @@ -323,7 +323,7 @@ extension JPEG.Data.Planar /// and all the values must be in the correct range for that bit width. /// /// - Returns: - /// A [`Swift.Void`] tuple, or `nil` if the file could not be opened at + /// A ``Void`` tuple, or `nil` if the file could not be opened at /// the given file path. public func compress(path:String, quanta:[JPEG.Table.Quantization.Key: [UInt16]]) throws @@ -388,7 +388,7 @@ extension JPEG.Data.Rectangular /// and all the values must be in the correct range for that bit width. /// /// - Returns: - /// A [`Swift.Void`] tuple, or `nil` if the file could not be opened at + /// A ``Void`` tuple, or `nil` if the file could not be opened at /// the given file path. public func compress(path:String, quanta:[JPEG.Table.Quantization.Key: [UInt16]]) throws From 69fe81407531556d162105fa80d4cfbb3876acb2 Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sun, 17 Nov 2024 00:01:27 +0000 Subject: [PATCH 12/18] migrate simple codelinks --- Sources/JPEG/common.swift | 6 +++--- Sources/JPEG/decode.swift | 26 +++++++++++------------ Sources/JPEG/encode.swift | 42 ++++++++++++++++++------------------- Sources/JPEG/error.swift | 2 +- Sources/JPEG/jpeg.swift | 16 +++++++------- Sources/JPEG/metadata.swift | 20 +++++++++--------- Sources/JPEGSystem/os.swift | 26 +++++++++++------------ 7 files changed, 69 insertions(+), 69 deletions(-) diff --git a/Sources/JPEG/common.swift b/Sources/JPEG/common.swift index 9a173576..443c527a 100644 --- a/Sources/JPEG/common.swift +++ b/Sources/JPEG/common.swift @@ -19,7 +19,7 @@ extension General private var storage:I /// Creates an instance of this property wrapper, with the given value - /// truncated to the width of the storage type [`I`]. + /// truncated to the width of the storage type ``I``. /// /// - Parameter wrappedValue: /// The value to wrap. @@ -44,7 +44,7 @@ extension General private var storage:(x:I, y:I) /// Creates an instance of this property wrapper, with the given values - /// truncated to the width of the storage type [`I`]. + /// truncated to the width of the storage type ``I``. /// /// - Parameter wrappedValue: /// The values to wrap. @@ -74,7 +74,7 @@ extension General private var storage:I /// Creates an instance of this property wrapper, with the given value - /// truncated to the width of the storage type [`I`]. + /// truncated to the width of the storage type ``I``. /// /// - Parameter wrappedValue: /// The value to wrap. diff --git a/Sources/JPEG/decode.swift b/Sources/JPEG/decode.swift index a62b3fe1..96fb0ccc 100644 --- a/Sources/JPEG/decode.swift +++ b/Sources/JPEG/decode.swift @@ -83,7 +83,7 @@ extension JPEG.Bytestream.Source /// Lexes a single marker segment from this bytestream, assuming there /// is no entropy-coded data prefixed to it. /// - /// Calling this function is roughly equivalent to calling [`segment(prefix:)`] + /// Calling this function is roughly equivalent to calling ``segment(prefix:)`` /// with the `prefix` parameter set to `false`, except that the empty /// prefix array is omitted from the return value. /// @@ -347,7 +347,7 @@ extension JPEG.Table.Huffman /// /// This initializer determines the shape of the tree from the shape of /// the leaf array input. It has no knowledge of symbol frequencies or - /// priority. To build an *optimal* huffman tree, use the [`init(frequencies:target:)`] + /// priority. To build an *optimal* huffman tree, use the ``init(frequencies:target:)`` /// initializer. /// /// This initializer will return `nil` if the sizes of the given leaf arrays do not @@ -740,7 +740,7 @@ extension JPEG.Header.Frame /// /// If the given data does not parse to a valid frame header, /// this function will throw a ``JPEG/ParsingError``. This function - /// invokes [`validate(process:precision:size:components:)`], so any errors + /// invokes ``validate(process:precision:size:components:)``, so any errors /// it can throw can also be thrown by this function. /// /// - Parameter data: @@ -906,7 +906,7 @@ extension JPEG.Header.Scan /// /// If the given data does not parse to a valid scan header, /// this function will throw a ``JPEG/ParsingError``. This function - /// invokes [`validate(process:band:bits:components:)`], so any errors + /// invokes ``validate(process:band:bits:components:)``, so any errors /// it can throw can also be thrown by this function. /// /// - Parameter data: @@ -1281,7 +1281,7 @@ extension JPEG.Table.Quantization /// Accesses the quantum value at the given grid index. /// /// Using this subscript is equivalent to using [`[z:]`] with the output - /// of [`z(k:h:)`]. + /// of ``z(k:h:)``. /// /// - Parameter k: /// The horizontal frequency index. This value must be in the range `0 ..< 8`. @@ -1488,7 +1488,7 @@ extension JPEG.Data public let units:(x:Int, y:Int) /// The size of this plane, in pixels. It is equivalent to multiplying - /// [`units`] by 8. + /// ``units`` by 8. public var size:(x:Int, y:Int) { @@ -1630,7 +1630,7 @@ extension JPEG.Data.Spectral.Quanta init(default:JPEG.Table.Quantization) { // generate the ‘default’ quantization table at `qi = -1`, `q = 0` - self.quanta = [`default`] + self.quanta = ``default`` self.q = [-1: 0] } @@ -1715,7 +1715,7 @@ extension JPEG.Data.Spectral.Quanta:RandomAccessCollection } /// Returns the index of the table with the given key. /// - /// An instance of this type which is part of a [`Spectral`] + /// An instance of this type which is part of a ``Spectral`` /// instance will always contain all quanta keys used by its ``Spectral/layout``, /// including keys used only by non-recognized components. /// @@ -2068,7 +2068,7 @@ extension JPEG.Layout /// /// This property should be equivalent to the `components` dictionary /// that would be used to construct this instance using - /// [`init(format:process:components:scans:)`]. As long as the [`Format`] + /// ``init(format:process:components:scans:)``. As long as the ``Format`` /// type is properly implemented, this dictionary will always have at /// least one element. public @@ -2193,7 +2193,7 @@ extension JPEG.Data.Spectral.Plane /// correct range. /// /// Using this subscript is equivalent to using [`[x:y:z:]`] with the `z` - /// index set to the output of [`Table.Quantization.z(k:h:)`]. + /// index set to the output of ``Table.Quantization.z(k:h:)``. /// /// - Parameter x: /// The horizontal index of the data unit to access. @@ -2372,7 +2372,7 @@ extension JPEG.Data.Spectral /// This function will invalidate all existing quantization table indices. /// /// - Parameter quanta: - /// The quantum values for each quanta key used by this image’s [`layout`], + /// The quantum values for each quanta key used by this image’s ``layout``, /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width @@ -4179,7 +4179,7 @@ extension JPEG.Data.Planar { /// Decompresses a planar image from the given data source. /// - /// This function is a convenience function which calls [`Spectral.decompress(stream:)`] + /// This function is a convenience function which calls ``Spectral.decompress(stream:)`` /// to obtain a spectral image, and then calls ``Spectral/idct()`` on the /// output to return a planar image. /// @@ -4200,7 +4200,7 @@ extension JPEG.Data.Rectangular { /// Decompresses a rectangular image from the given data source. /// - /// This function is a convenience function which calls [`Planar.decompress(stream:)`] + /// This function is a convenience function which calls ``Planar.decompress(stream:)`` /// to obtain a planar image, and then calls ``Planar/interleaved(cosite:)`` /// on the output to return a rectangular image. /// diff --git a/Sources/JPEG/encode.swift b/Sources/JPEG/encode.swift index a4b440b5..1f0e85ea 100644 --- a/Sources/JPEG/encode.swift +++ b/Sources/JPEG/encode.swift @@ -333,10 +333,10 @@ extension JPEG.Data.Planar { /// Converts this planar image into its spectral representation. /// - /// This method is the inverse of [`Spectral.idct()`] + /// This method is the inverse of ``Spectral.idct()`` /// /// - Parameter quanta: - /// The quantum values for each quanta key used by this image’s [`layout`], + /// The quantum values for each quanta key used by this image’s ``layout``, /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width @@ -374,11 +374,11 @@ extension JPEG.Data.Rectangular /// perform component resampling manually and construct a planar image /// directly using ``Planar/init(size:layout:metadata:initializingWith:)``. /// - /// This method is the inverse of [`Planar.interleaved(cosite:)`]. + /// This method is the inverse of ``Planar.interleaved(cosite:)``. /// /// - Returns: /// A planar image created by resampling all components in the input - /// according to their sampling factors in the image [`layout`]. + /// according to their sampling factors in the image ``layout``. public func decomposed() -> JPEG.Data.Planar { @@ -426,7 +426,7 @@ extension JPEG.Data.Rectangular /// Passing an invalid `size`, or a pixel array of the wrong `count` will /// result in a precondition failure. /// - /// This function is the inverse of [`unpack(as:)`]. + /// This function is the inverse of ``unpack(as:)``. /// /// - Parameter size: /// The size of the image, in pixels. Both dimensions must be positive. @@ -504,7 +504,7 @@ extension JPEG.Layout /// The scan decomposition of this image layout, filtered to include only /// recognized components. /// - /// This property is derived from the this layout’s [`definitions`]. + /// This property is derived from the this layout’s ``definitions``. /// Scans containing only non-recognized components are omitted from this /// array. public @@ -1668,7 +1668,7 @@ extension JPEG.Table /// /// The DC tables appear before the AC tables in the serialized segment. /// - /// This method is the inverse of [`parse(huffman:)`]. + /// This method is the inverse of ``parse(huffman:)``. /// /// - Parameter dc: /// The DC huffman tables to serialize. The tables will appear in the @@ -1700,7 +1700,7 @@ extension JPEG.Table } /// Serializes the given quantization tables as segment data. /// - /// This method is the inverse of [`parse(quantization:)`]. + /// This method is the inverse of ``parse(quantization:)``. /// /// - Parameter tables: /// The quantization tables to serialize. The tables will appear in the @@ -1737,7 +1737,7 @@ extension JPEG.Header.Frame { /// Serializes this frame header as segment data. /// - /// This method is the inverse of [`parse(_:process:)`]. + /// This method is the inverse of ``parse(_:process:)``. /// /// - Returns: /// A marker segment body. This array does not include the marker type @@ -1766,7 +1766,7 @@ extension JPEG.Header.Scan { /// Serializes this scan header as segment data. /// - /// This method is the inverse of [`parse(_:process:)`]. + /// This method is the inverse of ``parse(_:process:)``. /// /// - Returns: /// A marker segment body. This array does not include the marker type @@ -1836,7 +1836,7 @@ extension JPEG.Bytestream.Destination /// This function is meant to be used with markers without segment bodies, /// such as ``Marker/start``, ``Marker/end``, and ``Marker/restart(_:)``. /// - /// This function can throw a [`FormattingError`] if it fails to write + /// This function can throw a ``FormattingError`` if it fails to write /// to the bytestream. /// /// - Parameter marker: @@ -1856,7 +1856,7 @@ extension JPEG.Bytestream.Destination /// is provided, and so should *not* be used with markers without segment /// bodies, such as ``Marker/start``, ``Marker/end``, and ``Marker/restart(_:)``. /// - /// This function can throw a [`FormattingError`] if it fails to write + /// This function can throw a ``FormattingError`` if it fails to write /// to the bytestream. /// /// - Parameter marker: @@ -1879,8 +1879,8 @@ extension JPEG.Bytestream.Destination } /// Formats the given entropy-coded data into this bytestream. /// - /// This function is essentially a wrapper around [`write(_:)`] which converts - /// `nil` return values to a thrown [`FormattingError`]. + /// This function is essentially a wrapper around ``write(_:)`` which converts + /// `nil` return values to a thrown ``FormattingError``. /// /// - Parameter prefix: /// The data to write to the bytestream. @@ -1901,7 +1901,7 @@ extension JPEG.Data.Spectral /// Compresses a spectral image to the given data destination. /// /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. + /// the outputted file, in the order they appear in the ``metadata`` array. /// /// - Parameter stream: /// A destination bytestream. @@ -1967,9 +1967,9 @@ extension JPEG.Data.Planar /// Compresses a planar image to the given data destination. /// /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. + /// the outputted file, in the order they appear in the ``metadata`` array. /// - /// This function is a convenience function which calls [`fdct(quanta:)`] + /// This function is a convenience function which calls ``fdct(quanta:)`` /// to obtain a spectral image, and then calls ``Spectral/compress(stream:)`` /// on the output. /// @@ -1977,7 +1977,7 @@ extension JPEG.Data.Planar /// A destination bytestream. /// /// - Parameter quanta: - /// The quantum values for each quanta key used by this image’s [`layout`], + /// The quantum values for each quanta key used by this image’s ``layout``, /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width @@ -1996,9 +1996,9 @@ extension JPEG.Data.Rectangular /// Compresses a rectangular image to the given data destination. /// /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. + /// the outputted file, in the order they appear in the ``metadata`` array. /// - /// This function is a convenience function which calls [`decomposed()`] + /// This function is a convenience function which calls ``decomposed()`` /// to obtain a planar image, and then calls ``Planar/compress(stream:quanta:)`` /// on the output. /// @@ -2006,7 +2006,7 @@ extension JPEG.Data.Rectangular /// A destination bytestream. /// /// - Parameter quanta: - /// The quantum values for each quanta key used by this image’s [`layout`], + /// The quantum values for each quanta key used by this image’s ``layout``, /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width diff --git a/Sources/JPEG/error.swift b/Sources/JPEG/error.swift index 537cea10..907883cc 100644 --- a/Sources/JPEG/error.swift +++ b/Sources/JPEG/error.swift @@ -635,7 +635,7 @@ extension JPEG /// The bit precision read from the frame header. /// /// - Parameter format: - /// The [`Format`] type that tried to detect the color format. + /// The ``Format`` type that tried to detect the color format. case unrecognizedColorFormat(Set, Int, Any.Type) /// Returns the string `"decoding error"`. diff --git a/Sources/JPEG/jpeg.swift b/Sources/JPEG/jpeg.swift index 642bbbea..207eba7b 100644 --- a/Sources/JPEG/jpeg.swift +++ b/Sources/JPEG/jpeg.swift @@ -110,7 +110,7 @@ enum JPEG /// An 8-bit YCbCr color. /// - /// This type is a color target for the built-in [`JPEG.Common`] color format. + /// This type is a color target for the built-in ``JPEG.Common`` color format. /// /// ## Color channels /// - ``y`` @@ -162,7 +162,7 @@ enum JPEG } /// An 8-bit RGB color. /// - /// This type is a color target for the built-in [`JPEG.Common`] color format. + /// This type is a color target for the built-in ``JPEG.Common`` color format. /// /// ## Color channels /// - ``r`` @@ -821,7 +821,7 @@ extension JPEG /// This structure is the parsed form of a ``JPEG.Marker/scan`` /// marker segment. It defines scan-level image parameters. The library /// validates these structures against the global image parameters to - /// create the [`JPEG.Scan`] structures elsewhere in the library API. + /// create the ``JPEG.Scan`` structures elsewhere in the library API. public struct Scan { @@ -1037,7 +1037,7 @@ extension JPEG /// /// Non-recognized components can only occur in images decoded from JPEG files, /// and only when using a custom ``JPEG/Format`` type, as the built-in - /// [`JPEG.Common`] color format will never accept any component declaration + /// ``JPEG.Common`` color format will never accept any component declaration /// in a frame header that it does not also recognize. When encoding images to JPEG /// files, all declared resident components must also be recognized components. public @@ -1053,7 +1053,7 @@ extension JPEG /// The set of color components declared (or to-be-declared) in the /// image frame header. /// - /// The dictionary values are indices to be used with the [`planes`] property + /// The dictionary values are indices to be used with the ``planes`` property /// on this type. public let residents:[Component.Key: Int] @@ -1066,15 +1066,15 @@ extension JPEG } /// The descriptor array for the planes in the image. /// - /// Each descriptor consists of a [`JPEG.Component`] instance and a + /// Each descriptor consists of a ``JPEG.Component`` instance and a /// quantization table key. On layout initialization, the library will /// automatically assign table keys to table selectors. /// /// The ordering of the first *k* array elements follows the order that - /// the component keys appear in the [`recognized`] property, where + /// the component keys appear in the ``recognized`` property, where /// *k* is the number of components in the image. Any /// non-recognized resident components will occur at the end of this - /// array, can can be indexed using the values of the [`residents`] + /// array, can can be indexed using the values of the ``residents`` /// dictionary. public internal(set) var planes:[(component:Component, qi:Table.Quantization.Key)] diff --git a/Sources/JPEG/metadata.swift b/Sources/JPEG/metadata.swift index 8b6bad3b..a640b435 100644 --- a/Sources/JPEG/metadata.swift +++ b/Sources/JPEG/metadata.swift @@ -38,7 +38,7 @@ extension JPEG /// /// The `x` and `y` fields specify the number of physical samples along /// each dimension per `unit` length. For example, the value - /// `(x: 72, y: 72, unit: `[`Unit.inches`]`)` indicates a density of 72\ dpi. + /// `(x: 72, y: 72, unit: ```Unit.inches```)` indicates a density of 72\ dpi. /// If the `unit` field is `nil`, the units are unknown. public let density:(x:Int, y:Int, unit:Unit?) @@ -209,7 +209,7 @@ extension JPEG /// /// The tag codes are listed in the [EXIF standard](https://www.exif.org/Exif2-2.PDF). /// The dictionary values are internal file pointers that can be - /// dereferenced manually from the [`storage`]; alternatively, the + /// dereferenced manually from the ``storage``; alternatively, the /// [`[tag:]`] subscript can perform both the lookup and the dereferencing /// in one step. public private(set) @@ -348,7 +348,7 @@ extension JPEG.JFIF { /// Serializes this metadata record as segment data. /// - /// This method is the inverse of [`parse(_:)`]. + /// This method is the inverse of ``parse(_:)``. /// /// - Returns: /// A marker segment body. This array does not include the marker type @@ -493,7 +493,7 @@ extension JPEG.EXIF /// /// - Parameter tag: /// A tag code. The various EXIF tag codes are listed in the - /// [EXIF standard](https://www.exif.org/Exif2-2.PDF). The [`tags`] + /// [EXIF standard](https://www.exif.org/Exif2-2.PDF). The ``tags`` /// dictionary contains an index of the known, defined tags in this metadata /// record. /// @@ -523,7 +523,7 @@ extension JPEG.EXIF /// /// - Parameter offset: /// The address of the value to access. This pointer must be within the - /// index range of [`storage`]. + /// index range of ``storage``. /// /// - Parameter _: /// This parameter must be set to [`Swift.UInt8`self`]. @@ -539,13 +539,13 @@ extension JPEG.EXIF /// /// - Parameter offset: /// The address of the value to access. This pointer, and the address after - /// it must be within the index range of [`storage`]. + /// it must be within the index range of ``storage``. /// /// - Parameter _: /// This parameter must be set to [`Swift.UInt16`self`]. /// /// - Returns: - /// The ``FieldType/uint16`` value, loaded according to the [`endianness`] + /// The ``FieldType/uint16`` value, loaded according to the ``endianness`` /// of this metadata record. public subscript(offset:Int, as _:UInt16.Type) -> UInt16 @@ -564,13 +564,13 @@ extension JPEG.EXIF /// /// - Parameter offset: /// The address of the value to access. This pointer, and the next three - /// addresses after it must be within the index range of [`storage`]. + /// addresses after it must be within the index range of ``storage``. /// /// - Parameter _: /// This parameter must be set to [`Swift.UInt32`self`]. /// /// - Returns: - /// The ``FieldType/uint32`` value, loaded according to the [`endianness`] + /// The ``FieldType/uint32`` value, loaded according to the ``endianness`` /// of this metadata record. public subscript(offset:Int, as _:UInt32.Type) -> UInt32 @@ -608,7 +608,7 @@ extension JPEG.EXIF { /// Serializes this metadata record as segment data. /// - /// This method is the inverse of [`parse(_:)`]. + /// This method is the inverse of ``parse(_:)``. /// /// - Returns: /// A marker segment body. This array does not include the marker type diff --git a/Sources/JPEGSystem/os.swift b/Sources/JPEGSystem/os.swift index 3204c98a..5b0ab059 100644 --- a/Sources/JPEGSystem/os.swift +++ b/Sources/JPEGSystem/os.swift @@ -54,7 +54,7 @@ extension System.File.Source /// The path to the file to open. /// /// - Parameter body: - /// A closure with a [`Source`] parameter from which data in + /// A closure with a ``Source`` parameter from which data in /// the specified file can be read. This interface is only valid /// for the duration of the method’s execution. The closure is /// only executed if the specified file could be successfully @@ -164,7 +164,7 @@ extension System.File.Destination /// The path to the file to open. /// /// - Parameter body: - /// A closure with a [`Destination`] parameter representing + /// A closure with a ``Destination`` parameter representing /// the specified file to which data can be written to. This /// interface is only valid for the duration of the method’s /// execution. The closure is only executed if the specified file could @@ -236,7 +236,7 @@ extension JPEG.Data.Spectral { /// Decompresses a spectral image from the given file path. /// - /// Calling this function is equivalent to calling [`System.File.Source.open(path:_:)`] + /// Calling this function is equivalent to calling ``System.File.Source.open(path:_:)`` /// with the closure parameter set to [`Self``decompress(stream:)`]. /// /// This function is only available on MacOS and Linux platforms. @@ -255,9 +255,9 @@ extension JPEG.Data.Spectral /// Compresses a spectral image to the given file path. /// /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. + /// the outputted file, in the order they appear in the ``metadata`` array. /// - /// Calling this function is equivalent to calling [`System.File.Destination.open(path:_:)`] + /// Calling this function is equivalent to calling ``System.File.Destination.open(path:_:)`` /// with the closure parameter set to [`Self``compress(stream:)`]. /// /// This function is only available on MacOS and Linux platforms. @@ -278,7 +278,7 @@ extension JPEG.Data.Planar { /// Decompresses a planar image from the given file path. /// - /// This function is a convenience function which calls [`Spectral.decompress(path:)`] + /// This function is a convenience function which calls ``Spectral.decompress(path:)`` /// to obtain a spectral image, and then calls ``Spectral/idct()`` on the /// output to return a planar image. /// @@ -303,9 +303,9 @@ extension JPEG.Data.Planar /// Compresses a planar image to the given file path. /// /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. + /// the outputted file, in the order they appear in the ``metadata`` array. /// - /// This function is a convenience function which calls [`fdct(quanta:)`] + /// This function is a convenience function which calls ``fdct(quanta:)`` /// to obtain a spectral image, and then calls ``Spectral/compress(path:)`` /// on the output. /// @@ -315,7 +315,7 @@ extension JPEG.Data.Planar /// A file path. /// /// - Parameter quanta: - /// The quantum values for each quanta key used by this image’s [`layout`], + /// The quantum values for each quanta key used by this image’s ``layout``, /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width @@ -336,7 +336,7 @@ extension JPEG.Data.Rectangular { /// Decompresses a rectangular image from the given file path. /// - /// This function is a convenience function which calls [`Planar.decompress(path:)`] + /// This function is a convenience function which calls ``Planar.decompress(path:)`` /// to obtain a planar image, and then calls ``Planar/interleaved(cosite:)`` /// on the output to return a rectangular image. /// @@ -368,9 +368,9 @@ extension JPEG.Data.Rectangular /// Compresses a rectangular image to the given file path. /// /// All metadata records in this image will be emitted at the beginning of - /// the outputted file, in the order they appear in the [`metadata`] array. + /// the outputted file, in the order they appear in the ``metadata`` array. /// - /// This function is a convenience function which calls [`decomposed()`] + /// This function is a convenience function which calls ``decomposed()`` /// to obtain a planar image, and then calls ``Planar/compress(path:quanta:)`` /// on the output. /// @@ -380,7 +380,7 @@ extension JPEG.Data.Rectangular /// A file path. /// /// - Parameter quanta: - /// The quantum values for each quanta key used by this image’s [`layout`], + /// The quantum values for each quanta key used by this image’s ``layout``, /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width From 37f79872aa3dd33bfe061d738904b892049b23c7 Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sun, 17 Nov 2024 00:03:14 +0000 Subject: [PATCH 13/18] reformat subscript codelinks --- Sources/JPEG/decode.swift | 12 ++++++------ Sources/JPEG/metadata.swift | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Sources/JPEG/decode.swift b/Sources/JPEG/decode.swift index 96fb0ccc..7be0d5fa 100644 --- a/Sources/JPEG/decode.swift +++ b/Sources/JPEG/decode.swift @@ -1280,7 +1280,7 @@ extension JPEG.Table.Quantization /// Accesses the quantum value at the given grid index. /// - /// Using this subscript is equivalent to using [`[z:]`] with the output + /// Using this subscript is equivalent to using ``subscript(z:)`` with the output /// of ``z(k:h:)``. /// /// - Parameter k: @@ -1724,7 +1724,7 @@ extension JPEG.Data.Spectral.Quanta:RandomAccessCollection /// will result in a precondition failure. /// /// - Returns: - /// The integer index. This index can be used with the [`[_:]`] subscript. + /// The integer index. This index can be used with the ``subscript(_:)`` subscript. public func index(forKey qi:JPEG.Table.Quantization.Key) -> Int { @@ -1792,7 +1792,7 @@ extension JPEG.Data.Spectral:RandomAccessCollection /// /// - Returns: /// The integer index of the plane, or `nil`. If not `nil`, this index - /// can be used with the [`[_:]`] subscript. + /// can be used with the ``subscript(_:)`` subscript. public func index(forKey ci:JPEG.Component.Key) -> Int? { @@ -1850,7 +1850,7 @@ extension JPEG.Data.Planar:RandomAccessCollection /// /// - Returns: /// The integer index of the plane, or `nil`. If not `nil`, this index - /// can be used with the [`[_:]`] subscript. + /// can be used with the ``subscript(_:)`` subscript. public func index(forKey ci:JPEG.Component.Key) -> Int? { @@ -1895,7 +1895,7 @@ extension JPEG.Data.Rectangular /// /// - Returns: /// The interleaved offset of the channel, or `nil`. If not `nil`, this offset - /// can be used as the `p` parameter to the [`[x:y:p:]`] subscript. + /// can be used as the `p` parameter to the ``subscript(x:y:p:)`` subscript. public func offset(forKey ci:JPEG.Component.Key) -> Int? { @@ -2192,7 +2192,7 @@ extension JPEG.Data.Spectral.Plane /// have no effect. The `k` and `h` indices still have to be within the /// correct range. /// - /// Using this subscript is equivalent to using [`[x:y:z:]`] with the `z` + /// Using this subscript is equivalent to using ``subscript(x:y:z:)`` with the `z` /// index set to the output of ``Table.Quantization.z(k:h:)``. /// /// - Parameter x: diff --git a/Sources/JPEG/metadata.swift b/Sources/JPEG/metadata.swift index a640b435..066469c0 100644 --- a/Sources/JPEG/metadata.swift +++ b/Sources/JPEG/metadata.swift @@ -210,7 +210,7 @@ extension JPEG /// The tag codes are listed in the [EXIF standard](https://www.exif.org/Exif2-2.PDF). /// The dictionary values are internal file pointers that can be /// dereferenced manually from the ``storage``; alternatively, the - /// [`[tag:]`] subscript can perform both the lookup and the dereferencing + /// ``subscript(tag:)`` subscript can perform both the lookup and the dereferencing /// in one step. public private(set) var tags:[UInt16: Int] From bbf4b0568d15b827fe1d76192c68858b89079bea Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sun, 17 Nov 2024 00:04:24 +0000 Subject: [PATCH 14/18] revert unwanted substitution --- Sources/JPEG/decode.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/JPEG/decode.swift b/Sources/JPEG/decode.swift index 7be0d5fa..468f396e 100644 --- a/Sources/JPEG/decode.swift +++ b/Sources/JPEG/decode.swift @@ -1630,7 +1630,7 @@ extension JPEG.Data.Spectral.Quanta init(default:JPEG.Table.Quantization) { // generate the ‘default’ quantization table at `qi = -1`, `q = 0` - self.quanta = ``default`` + self.quanta = [`default`] self.q = [-1: 0] } From e8b441b4bf7a617db0d296d3b5684f6e82c63497 Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sun, 17 Nov 2024 00:13:38 +0000 Subject: [PATCH 15/18] reformat or downgrade the Entrapta keypath codelinks --- Sources/JPEG/decode.swift | 18 +++++++++--------- Sources/JPEG/encode.swift | 8 ++++---- Sources/JPEG/jpeg.swift | 12 ++++++------ Sources/JPEG/metadata.swift | 6 +++--- Sources/JPEGSystem/os.swift | 8 ++++---- 5 files changed, 26 insertions(+), 26 deletions(-) diff --git a/Sources/JPEG/decode.swift b/Sources/JPEG/decode.swift index 468f396e..953bbbfb 100644 --- a/Sources/JPEG/decode.swift +++ b/Sources/JPEG/decode.swift @@ -826,7 +826,7 @@ extension JPEG.Header.Scan /// /// - Parameter bits: /// The bit range encoded by the scan, where bit zero is the least significant - /// bit. The upper range bound must be either infinity ([`Swift.Int`max`]) + /// bit. The upper range bound must be either infinity (``Int.max``) /// or one greater than the lower bound. If the `process` is not /// ``Process/progressive(coding:differential:)``, this value must /// be set to `0 ..< .max`. @@ -1448,7 +1448,7 @@ extension JPEG.Data /// and vertical directions. /// /// The size of the minimum-coded unit, in 8×8 blocks of pixels, - /// is given by [`layout``(Layout).scale`]. + /// is given by ``layout`` → ``Layout/scale``. public private(set) var blocks:(x:Int, y:Int) /// The layout of this image. @@ -1604,9 +1604,9 @@ extension JPEG.Data /// - Parameter values: /// An array of interleaved samples, in row major order, and without /// padding. The array must have exactly - /// [`layout``(Layout).recognized`count`]\ ×\ [`size`x`]\ ×\ [`size`y`] samples. + /// `layout.recognized.count`\ ×\ `x`\ ×\ `y` samples. /// Each ``UInt16`` is one sample. The samples should not be - /// normalized, so an image with a [`layout``(Layout).format``(Format).precision`] of + /// normalized, so an image with a `layout.format.precision` of /// 8 should only have samples in the range `0 ... 255`. public init(size:(x:Int, y:Int), @@ -1754,7 +1754,7 @@ extension JPEG.Data.Spectral:RandomAccessCollection /// The index one greater than the index of the last plane in this image. /// /// This index is always the number of recognized components in the image’s - /// [`layout``(JPEG.Layout).format`]. + /// `layout.format`. public var endIndex:Int { @@ -1812,7 +1812,7 @@ extension JPEG.Data.Planar:RandomAccessCollection /// The index one greater than the index of the last plane in this image. /// /// This index is always the number of recognized components in the image’s - /// [`layout``(JPEG.Layout).format`]. + /// `layout.format`. public var endIndex:Int { @@ -2376,7 +2376,7 @@ extension JPEG.Data.Spectral /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width - /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], + /// determined by this image’s `layout.format.precision`, /// and all the values must be in the correct range for that bit width. public mutating func set(quanta:[JPEG.Table.Quantization.Key: [UInt16]]) @@ -2501,7 +2501,7 @@ extension JPEG.Data.Planar /// /// This initializer will initialize all samples in all planes to the /// midpoint of this image’s sample range. The midpoint is equal to - /// 2^*w*\ –\ 1^, where *w*\ =\ [`layout``(Layout).format``(JPEG.Format).precision`]. + /// 2^*w*\ –\ 1^, where *w*\ =\ `layout.format.precision`. /// /// - Parameter size: /// The size of the image, in pixels. Both dimensions must be positive, @@ -2529,7 +2529,7 @@ extension JPEG.Data.Rectangular /// /// This initializer will initialize all samples to the /// midpoint of this image’s sample range. The midpoint is equal to - /// 2^*w*\ –\ 1^, where *w*\ =\ [`layout``(Layout).format``(JPEG.Format).precision`]. + /// 2^*w*\ –\ 1^, where *w*\ =\ `layout.format.precision`. /// /// - Parameter size: /// The size of the image, in pixels. Both dimensions must be positive, diff --git a/Sources/JPEG/encode.swift b/Sources/JPEG/encode.swift index 1f0e85ea..e4a6a8ff 100644 --- a/Sources/JPEG/encode.swift +++ b/Sources/JPEG/encode.swift @@ -340,7 +340,7 @@ extension JPEG.Data.Planar /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width - /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], + /// determined by this image’s `layout.format.precision`, /// and all the values must be in the correct range for that bit width. /// /// - Returns: @@ -439,7 +439,7 @@ extension JPEG.Data.Rectangular /// /// - Parameter pixels: /// An array of pixels, in row major order, and without - /// padding. The array must have exactly [`size`x`]\ ×\ [`size`y`] pixels. + /// padding. The array must have exactly `x`\ ×\ `y` pixels. /// /// - Returns: /// A rectangular image. @@ -1981,7 +1981,7 @@ extension JPEG.Data.Planar /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width - /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], + /// determined by this image’s `layout.format.precision`, /// and all the values must be in the correct range for that bit width. public func compress(stream:inout Destination, @@ -2010,7 +2010,7 @@ extension JPEG.Data.Rectangular /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width - /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], + /// determined by this image’s `layout.format.precision`, /// and all the values must be in the correct range for that bit width. public func compress(stream:inout Destination, diff --git a/Sources/JPEG/jpeg.swift b/Sources/JPEG/jpeg.swift index 207eba7b..b2458d9c 100644 --- a/Sources/JPEG/jpeg.swift +++ b/Sources/JPEG/jpeg.swift @@ -875,15 +875,15 @@ extension JPEG /// A quantization table. /// /// Quantization tables store 64 coefficient quanta. The quantum values - /// can be accessed using either a zigzag index with the [`(Quantization).[z:]`] - /// subscript, or grid indices with the [`(Quantization).[k:h:]`] subscript. + /// can be accessed using either a zigzag index with the ``Quantization/subscript(z:)`` + /// subscript, or grid indices with the ``Quantization/subscript(k:h:)`` subscript. public struct Quantization:AnyTable { /// A unique identifier assigned to each quantization table in an image. /// - /// Quanta keys are numeric values ranging from [`Swift.Int`min`] - /// to [`Swift.Int`max`]. In these reference pages, quanta keys + /// Quanta keys are numeric values ranging from ``Int.min`` + /// to ``Int.max``. In these reference pages, quanta keys /// in their numerical representation are written in **boldface**. public struct Key:Hashable, Comparable, Sendable @@ -1002,7 +1002,7 @@ extension JPEG /// /// This property specifies a range of bit indices, where bit zero is /// the least significant bit. The upper range bound is always either - /// infinity ([`Swift.Int`max`]) or one greater than the lower bound. + /// infinity ``Int.max`` or one greater than the lower bound. /// If the image coding process is not ``Process/progressive(coding:differential:)``, /// this value will be `0 ..< .max`. public @@ -1031,7 +1031,7 @@ extension JPEG /// This structure records both the *recognized components* and /// the *resident components* in an image. We draw this distinction because /// the ``Layout/planes`` property is allowed to include definitions for components - /// that are not part of [`(Layout).format``(Format).components`]. + /// that are not part of `format.components`. /// Such components will not recieve a plane in the ``JPEG/Data`` types, /// but will be ignored by the scan decoder without errors. /// diff --git a/Sources/JPEG/metadata.swift b/Sources/JPEG/metadata.swift index 066469c0..36c98977 100644 --- a/Sources/JPEG/metadata.swift +++ b/Sources/JPEG/metadata.swift @@ -526,7 +526,7 @@ extension JPEG.EXIF /// index range of ``storage``. /// /// - Parameter _: - /// This parameter must be set to [`Swift.UInt8`self`]. + /// This parameter must be set to `UInt8.self`. /// /// - Returns: /// The ``FieldType/uint8`` value. @@ -542,7 +542,7 @@ extension JPEG.EXIF /// it must be within the index range of ``storage``. /// /// - Parameter _: - /// This parameter must be set to [`Swift.UInt16`self`]. + /// This parameter must be set to `UInt16.self`. /// /// - Returns: /// The ``FieldType/uint16`` value, loaded according to the ``endianness`` @@ -567,7 +567,7 @@ extension JPEG.EXIF /// addresses after it must be within the index range of ``storage``. /// /// - Parameter _: - /// This parameter must be set to [`Swift.UInt32`self`]. + /// This parameter must be set to `UInt32.self`. /// /// - Returns: /// The ``FieldType/uint32`` value, loaded according to the ``endianness`` diff --git a/Sources/JPEGSystem/os.swift b/Sources/JPEGSystem/os.swift index 5b0ab059..bcd61a22 100644 --- a/Sources/JPEGSystem/os.swift +++ b/Sources/JPEGSystem/os.swift @@ -237,7 +237,7 @@ extension JPEG.Data.Spectral /// Decompresses a spectral image from the given file path. /// /// Calling this function is equivalent to calling ``System.File.Source.open(path:_:)`` - /// with the closure parameter set to [`Self``decompress(stream:)`]. + /// with the closure parameter set to ``decompress(stream:)``. /// /// This function is only available on MacOS and Linux platforms. /// @@ -258,7 +258,7 @@ extension JPEG.Data.Spectral /// the outputted file, in the order they appear in the ``metadata`` array. /// /// Calling this function is equivalent to calling ``System.File.Destination.open(path:_:)`` - /// with the closure parameter set to [`Self``compress(stream:)`]. + /// with the closure parameter set to ``compress(stream:)``. /// /// This function is only available on MacOS and Linux platforms. /// @@ -319,7 +319,7 @@ extension JPEG.Data.Planar /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width - /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], + /// determined by this image’s `layout.format.precision`, /// and all the values must be in the correct range for that bit width. /// /// - Returns: @@ -384,7 +384,7 @@ extension JPEG.Data.Rectangular /// including quanta keys used only by non-recognized components. Each /// array of quantum values must have exactly 64 elements. The quantization /// tables created from these values will be encoded using integers with a bit width - /// determined by this image’s [`layout``(Layout).format``(JPEG.Format).precision`], + /// determined by this image’s `layout.format.precision`, /// and all the values must be in the correct range for that bit width. /// /// - Returns: From 34535fc4213d8fad1eb1b36a95226cb58b28e87e Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sun, 17 Nov 2024 00:19:11 +0000 Subject: [PATCH 16/18] use true nested protocols --- Sources/JPEG/decode.swift | 83 +++++++++---------- Sources/JPEG/encode.swift | 52 ++++++------ Sources/JPEG/error.swift | 43 +++++----- Sources/JPEG/jpeg.swift | 170 ++++++++++++++++++-------------------- 4 files changed, 168 insertions(+), 180 deletions(-) diff --git a/Sources/JPEG/decode.swift b/Sources/JPEG/decode.swift index 953bbbfb..afa0eed8 100644 --- a/Sources/JPEG/decode.swift +++ b/Sources/JPEG/decode.swift @@ -4,40 +4,38 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/. */ // binary utilities -/// A source bytestream. -/// -/// To implement a custom data source type, conform it to this protocol by -/// implementing ``Source/read(count:)``. It can -/// then be used with the library’s core decompression interfaces. -public -protocol _JPEGBytestreamSource -{ - /// Attempts to read and return the given number of bytes from this stream. - /// - /// A successful call to this function should affect the bytestream state - /// such that subsequent calls should pick up where the last call left off. - /// - /// The rest of the library interprets a `nil` return value from this function - /// as indicating end-of-stream. - /// - /// - Parameter count: - /// The number of bytes to read. - /// - /// - Returns: - /// The `count` bytes read, or `nil` if the read attempt failed. This - /// method should return `nil` even if any number of bytes less than `count` - /// were successfully read. - mutating - func read(count:Int) -> [UInt8]? -} extension JPEG { /// A namespace for bytestream utilities. public enum Bytestream { + /// A source bytestream. + /// + /// To implement a custom data source type, conform it to this protocol by + /// implementing ``Source/read(count:)``. It can + /// then be used with the library’s core decompression interfaces. public - typealias Source = _JPEGBytestreamSource + protocol Source + { + /// Attempts to read and return the given number of bytes from this stream. + /// + /// A successful call to this function should affect the bytestream state + /// such that subsequent calls should pick up where the last call left off. + /// + /// The rest of the library interprets a `nil` return value from this function + /// as indicating end-of-stream. + /// + /// - Parameter count: + /// The number of bytes to read. + /// + /// - Returns: + /// The `count` bytes read, or `nil` if the read attempt failed. This + /// method should return `nil` even if any number of bytes less than `count` + /// were successfully read. + mutating + func read(count:Int) -> [UInt8]? + } } } @@ -183,25 +181,24 @@ extension JPEG.Bytestream.Source // parsing -/// Functionality common to all bitstream symbols. -public -protocol _JPEGBitstreamAnySymbol:Hashable -{ - /// Creates a symbol instance. - /// - /// - Parameter value: - /// The byte value of this symbol. - init(_ value:UInt8) - /// The byte value of this symbol. - var value:UInt8 - { - get - } -} extension JPEG.Bitstream { + /// Functionality common to all bitstream symbols. public - typealias AnySymbol = _JPEGBitstreamAnySymbol + protocol AnySymbol:Hashable + { + /// Creates a symbol instance. + /// + /// - Parameter value: + /// The byte value of this symbol. + init(_ value:UInt8) + /// The byte value of this symbol. + var value:UInt8 + { + get + } + } + /// A namespace for bitstream symbol types. public enum Symbol diff --git a/Sources/JPEG/encode.swift b/Sources/JPEG/encode.swift index e4a6a8ff..fd395cc1 100644 --- a/Sources/JPEG/encode.swift +++ b/Sources/JPEG/encode.swift @@ -1798,36 +1798,34 @@ extension JPEG.Header.Scan // formatters (opposite of lexers) -/// A destination bytestream. -/// -/// To implement a custom data destination type, conform it to this protocol by -/// implementing ``Destination/write(_:)``. It can -/// then be used with the library’s core compression interfaces. -public -protocol _JPEGBytestreamDestination -{ - /// Attempts to write the given bytes to this stream. - /// - /// A successful call to this function should affect the bytestream state - /// such that subsequent calls should pick up where the last call left off. - /// - /// The rest of the library interprets a `nil` return value from this function - /// as indicating a write failure. - /// - /// - Parameter bytes: - /// The bytes to write. - /// - /// - Returns: - /// A ``Void`` tuple, or `nil` if the write attempt failed. This - /// method should return `nil` even if any number of bytes less than - /// `bytes.count` were successfully written. - mutating - func write(_ bytes:[UInt8]) -> Void? -} extension JPEG.Bytestream { + /// A destination bytestream. + /// + /// To implement a custom data destination type, conform it to this protocol by + /// implementing ``Destination/write(_:)``. It can + /// then be used with the library’s core compression interfaces. public - typealias Destination = _JPEGBytestreamDestination + protocol Destination + { + /// Attempts to write the given bytes to this stream. + /// + /// A successful call to this function should affect the bytestream state + /// such that subsequent calls should pick up where the last call left off. + /// + /// The rest of the library interprets a `nil` return value from this function + /// as indicating a write failure. + /// + /// - Parameter bytes: + /// The bytes to write. + /// + /// - Returns: + /// A ``Void`` tuple, or `nil` if the write attempt failed. This + /// method should return `nil` even if any number of bytes less than + /// `bytes.count` were successfully written. + mutating + func write(_ bytes:[UInt8]) -> Void? + } } extension JPEG.Bytestream.Destination { diff --git a/Sources/JPEG/error.swift b/Sources/JPEG/error.swift index 907883cc..8005aa5b 100644 --- a/Sources/JPEG/error.swift +++ b/Sources/JPEG/error.swift @@ -2,31 +2,30 @@ License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/. */ -/// Functionality common to all library error types. -public -protocol _JPEGError:Swift.Error -{ - /// The human-readable namespace for errors of this type. - static - var namespace:String - { - get - } - /// A basic description of this error instance. - var message:String - { - get - } - /// A detailed description of this error instance, if available. - var details:String? - { - get - } -} extension JPEG { + /// Functionality common to all library error types. public - typealias Error = _JPEGError + protocol Error:Swift.Error + { + /// The human-readable namespace for errors of this type. + static + var namespace:String + { + get + } + /// A basic description of this error instance. + var message:String + { + get + } + /// A detailed description of this error instance, if available. + var details:String? + { + get + } + } + /// A lexing error. public enum LexingError:JPEG.Error diff --git a/Sources/JPEG/jpeg.swift b/Sources/JPEG/jpeg.swift index b2458d9c..b453184e 100644 --- a/Sources/JPEG/jpeg.swift +++ b/Sources/JPEG/jpeg.swift @@ -2,87 +2,82 @@ License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/. */ -/// A color format, determined by the bit depth and set of component keys in -/// a frame header. -/// -/// The coding ``JPEG/Process`` of an image may place restrictions on which -/// combinations of component sets and bit precisions are valid. +/// A namespace for JPEG-related functionality. public -protocol _JPEGFormat +enum JPEG { - /// Detects this color format, given a set of component keys and a bit depth. - /// - /// - Parameter components: - /// The set of given component keys. - /// - /// - Parameter precision: - /// The given bit depth. - /// - /// - Returns: - /// A color format instance. - static - func recognize(_ components:Set, precision:Int) -> Self? - - /// The set of component keys for this color format. + /// A color format, determined by the bit depth and set of component keys in + /// a frame header. /// - /// The ordering is used to determine plane index assignments when initializing - /// an image layout. This property should never be empty. It is allowed - /// for this array to contain fewer components than were detected by the - /// ``Format/recognize(_:precision:)`` constructor. - var components:[JPEG.Component.Key] + /// The coding ``JPEG/Process`` of an image may place restrictions on which + /// combinations of component sets and bit precisions are valid. + public + protocol Format { - get - } + /// Detects this color format, given a set of component keys and a bit depth. + /// + /// - Parameter components: + /// The set of given component keys. + /// + /// - Parameter precision: + /// The given bit depth. + /// + /// - Returns: + /// A color format instance. + static + func recognize(_ components:Set, precision:Int) -> Self? - /// The bit depth of each component in this color format. - var precision:Int - { - get - } -} -/// A color target. -public -protocol _JPEGColor -{ - /// The color format associated with this color target. An image using - /// any color format of this type will support rendering to this color target. - associatedtype Format:JPEG.Format + /// The set of component keys for this color format. + /// + /// The ordering is used to determine plane index assignments when initializing + /// an image layout. This property should never be empty. It is allowed + /// for this array to contain fewer components than were detected by the + /// ``Format/recognize(_:precision:)`` constructor. + var components:[JPEG.Component.Key] + { + get + } - /// Converts the given interleaved samples into an array of structured pixels. - /// - /// - Parameter interleaved: - /// A flat array of interleaved component samples. - /// - /// - Parameter format: - /// The color format of the interleaved input. - /// - /// - Returns: - /// An array of pixels of this color target type. - static - func unpack(_ interleaved:[UInt16], of format:Format) -> [Self] + /// The bit depth of each component in this color format. + var precision:Int + { + get + } + } + /// A color target. + public + protocol Color + { + /// The color format associated with this color target. An image using + /// any color format of this type will support rendering to this color target. + associatedtype Format:JPEG.Format - /// Converts the given array of structured pixels into an array of interleaved samples. - /// - /// - Parameter pixels: - /// An array of pixels of this color target type. - /// - /// - Parameter format: - /// The color format of the interleaved output. - /// - /// - Returns: - /// A flat array of interleaved component samples. - static - func pack(_ pixels:[Self], as format:Format) -> [UInt16] -} + /// Converts the given interleaved samples into an array of structured pixels. + /// + /// - Parameter interleaved: + /// A flat array of interleaved component samples. + /// + /// - Parameter format: + /// The color format of the interleaved input. + /// + /// - Returns: + /// An array of pixels of this color target type. + static + func unpack(_ interleaved:[UInt16], of format:Format) -> [Self] -/// A namespace for JPEG-related functionality. -public -enum JPEG -{ - public - typealias Format = _JPEGFormat - public - typealias Color = _JPEGColor + /// Converts the given array of structured pixels into an array of interleaved samples. + /// + /// - Parameter pixels: + /// An array of pixels of this color target type. + /// + /// - Parameter format: + /// The color format of the interleaved output. + /// + /// - Returns: + /// A flat array of interleaved component samples. + static + func pack(_ pixels:[Self], as format:Format) -> [UInt16] + } /// A metadata record. public @@ -713,20 +708,6 @@ extension JPEG } } -/// Functionality common to all table types. -public -protocol _JPEGAnyTable -{ - /// A type representing a table instance while it is bound to a table slot. - associatedtype Delegate - /// Four table slots. - /// - /// JPEG images are always limited to four table slots for each table type. - /// Some coding processes may limit further the number of available table slots. - typealias Slots = (Delegate?, Delegate?, Delegate?, Delegate?) - /// A table selector. - typealias Selector = WritableKeyPath -} extension JPEG { /// A namespace for header types. @@ -845,8 +826,21 @@ extension JPEG } } + /// Functionality common to all table types. public - typealias AnyTable = _JPEGAnyTable + protocol AnyTable + { + /// A type representing a table instance while it is bound to a table slot. + associatedtype Delegate + /// Four table slots. + /// + /// JPEG images are always limited to four table slots for each table type. + /// Some coding processes may limit further the number of available table slots. + typealias Slots = (Delegate?, Delegate?, Delegate?, Delegate?) + /// A table selector. + typealias Selector = WritableKeyPath + } + /// A namespace for table types. public enum Table From b53adce4365aec804f0df89d86888202e41f0d19 Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sun, 17 Nov 2024 00:29:26 +0000 Subject: [PATCH 17/18] update or demote broken codelinks --- Sources/JPEG/common.swift | 6 +++--- Sources/JPEG/decode.swift | 12 ++++++------ Sources/JPEG/docs.docc/JPEG.Data.Rectangular.md | 2 +- Sources/JPEG/jpeg.swift | 12 ++++++------ 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/Sources/JPEG/common.swift b/Sources/JPEG/common.swift index 443c527a..0fd6c1c4 100644 --- a/Sources/JPEG/common.swift +++ b/Sources/JPEG/common.swift @@ -19,7 +19,7 @@ extension General private var storage:I /// Creates an instance of this property wrapper, with the given value - /// truncated to the width of the storage type ``I``. + /// truncated to the width of the storage type `I`. /// /// - Parameter wrappedValue: /// The value to wrap. @@ -44,7 +44,7 @@ extension General private var storage:(x:I, y:I) /// Creates an instance of this property wrapper, with the given values - /// truncated to the width of the storage type ``I``. + /// truncated to the width of the storage type `I`. /// /// - Parameter wrappedValue: /// The values to wrap. @@ -74,7 +74,7 @@ extension General private var storage:I /// Creates an instance of this property wrapper, with the given value - /// truncated to the width of the storage type ``I``. + /// truncated to the width of the storage type `I`. /// /// - Parameter wrappedValue: /// The value to wrap. diff --git a/Sources/JPEG/decode.swift b/Sources/JPEG/decode.swift index afa0eed8..2f33c2ec 100644 --- a/Sources/JPEG/decode.swift +++ b/Sources/JPEG/decode.swift @@ -1892,7 +1892,7 @@ extension JPEG.Data.Rectangular /// /// - Returns: /// The interleaved offset of the channel, or `nil`. If not `nil`, this offset - /// can be used as the `p` parameter to the ``subscript(x:y:p:)`` subscript. + /// can be used as the `p` parameter to the ``subscript(x:y:_:)`` subscript. public func offset(forKey ci:JPEG.Component.Key) -> Int? { @@ -2003,7 +2003,7 @@ extension JPEG.Data.Planar /// The return value of the given closure. public func read(ci:JPEG.Component.Key, - body:(Plane) throws -> R) + _ body:(Plane) throws -> R) rethrows -> R { guard let p:Int = self.index(forKey: ci) @@ -2030,7 +2030,7 @@ extension JPEG.Data.Planar /// The return value of the given closure. public mutating func with(ci:JPEG.Component.Key, - body:(inout Plane) throws -> R) + _ body:(inout Plane) throws -> R) rethrows -> R { guard let p:Int = self.index(forKey: ci) @@ -3494,7 +3494,7 @@ extension JPEG.Context } /// Updates the decoder state with the given DC huffman table. /// - /// This method binds the table to its target ``Table.HuffmanDC/Selector`` + /// This method binds the table to its target ``JPEG.AnyTable/Selector`` /// within this instance. /// /// - Parameter table: @@ -3506,7 +3506,7 @@ extension JPEG.Context } /// Updates the decoder state with the given AC huffman table. /// - /// This method binds the table to its target ``Table.HuffmanAC/Selector`` + /// This method binds the table to its target ``JPEG.AnyTable/Selector`` /// within this instance. /// /// - Parameter table: @@ -3518,7 +3518,7 @@ extension JPEG.Context } /// Updates the decoder state with the given quantization table. /// - /// This method binds the table to its target ``Table.Quantization/Selector`` + /// This method binds the table to its target ``JPEG.AnyTable/Selector`` /// within this instance. /// /// - Parameter table: diff --git a/Sources/JPEG/docs.docc/JPEG.Data.Rectangular.md b/Sources/JPEG/docs.docc/JPEG.Data.Rectangular.md index 1f4557cb..e2a4b513 100644 --- a/Sources/JPEG/docs.docc/JPEG.Data.Rectangular.md +++ b/Sources/JPEG/docs.docc/JPEG.Data.Rectangular.md @@ -33,5 +33,5 @@ ### Accessing samples - ``stride`` -- ``subscript(x:y:p:)`` +- ``subscript(x:y:_:)`` - ``offset(forKey:)`` diff --git a/Sources/JPEG/jpeg.swift b/Sources/JPEG/jpeg.swift index b453184e..acd872dd 100644 --- a/Sources/JPEG/jpeg.swift +++ b/Sources/JPEG/jpeg.swift @@ -1142,10 +1142,10 @@ extension JPEG.Layout /// Creates an image layout given image parameters and a scan decomposition. /// /// If the image coding process is a sequential process, the given scan headers - /// should be constructed using the ``JPEG.Header.Scan/sequential(...:)`` + /// should be constructed using the ``JPEG.Header.Scan/sequential(_:) [8EG0R]`` /// constructor. If the coding process is progressive, the scan headers - /// should be constructed with the ``JPEG.Header.Scan/progressive(...:bits:)``, - /// ``JPEG.Header.Scan/progressive(...:bit:)``, + /// should be constructed with the ``JPEG.Header.Scan/progressive(_:bits:) [4VRKH]``, + /// ``JPEG.Header.Scan/progressive(_:bit:) [6Z2C2]``, /// ``JPEG.Header.Scan/progressive(_:band:bits:)``, or /// ``JPEG.Header.Scan/progressive(_:band:bit:)`` constructors. /// @@ -1478,7 +1478,7 @@ extension JPEG.Header.Scan } /// Creates a sequential scan descriptor. /// - /// This function is variadic sugar for ``Scan/sequential(_:)``. + /// This function is variadic sugar for ``Scan/sequential(_:) [4K2XD]``. public static func sequential(_ components: ( @@ -1523,7 +1523,7 @@ extension JPEG.Header.Scan } /// Creates a progressive initial DC scan descriptor. /// - /// This function is variadic sugar for ``Scan/progressive(_:bits:)``. + /// This function is variadic sugar for ``Scan/progressive(_:bits:) [4NV9J]``. public static func progressive(_ components:(ci:JPEG.Component.Key, dc:JPEG.Table.HuffmanDC.Selector)..., @@ -1563,7 +1563,7 @@ extension JPEG.Header.Scan } /// Creates a progressive refining DC scan descriptor. /// - /// This function is variadic sugar for ``Scan/progressive(_:bit:)``. + /// This function is variadic sugar for ``Scan/progressive(_:bit:) [404AZ]``. public static func progressive(_ components:JPEG.Component.Key..., From a7abb16b3450f4942b35a1feb51b2c00648d303c Mon Sep 17 00:00:00 2001 From: Dianna Ma Date: Sun, 17 Nov 2024 00:30:44 +0000 Subject: [PATCH 18/18] add doc validation to the CI pipeline --- .github/workflows/Documentation.yml | 48 +++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 .github/workflows/Documentation.yml diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml new file mode 100644 index 00000000..43ee1e0d --- /dev/null +++ b/.github/workflows/Documentation.yml @@ -0,0 +1,48 @@ +name: documentation + +on: + push: + branches: [ master ] + pull_request: + branches: [ master ] + +jobs: + linux: + runs-on: ubuntu-24.04 + name: Ubuntu 24.04 + + steps: + - name: Install Swift + uses: tayloraswift/swift-install-action@master + with: + swift-prefix: "swift-6.0.2-release/ubuntu2404/swift-6.0.2-RELEASE" + swift-id: "swift-6.0.2-RELEASE-ubuntu24.04" + + - name: Install Unidoc + uses: tayloraswift/swift-unidoc-action@master + + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Validate documentation + run: | + unidoc compile \ + --swift-toolchain $SWIFT_INSTALLATION \ + --ci fail-on-errors \ + --project-path . + + macos: + runs-on: macos-15 + name: macOS + steps: + - name: Install Unidoc + uses: tayloraswift/swift-unidoc-action@master + + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Validate documentation + run: | + unidoc compile \ + --ci fail-on-errors \ + --project-path .