summaryrefslogtreecommitdiffstatshomepage
path: root/src/lib/util
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2022-02-20 18:44:19 +1100
committer Vas Crabb <vas@vastheman.com>2022-02-20 18:44:19 +1100
commit02d29b771ab76f0d45ccd7d04be7a9680d8a2148 (patch)
treed9ece0ee60ae6031fe438aa9ea9bedc40c5b1dd5 /src/lib/util
parent98b88900c6df94eb37e30f1af6a4aacb833cdd68 (diff)
Miscellaneous cleanup:
* emu/machine.cpp: Organised #included headers by module. * formats/jvc_dsk.cpp: Don't hide diagnostics behind compile-time switch. * util/ioprocsfilter.h: Added doxygen comments so one doesn't need to read the source to work semantics.
Diffstat (limited to 'src/lib/util')
-rw-r--r--src/lib/util/ioprocs.cpp4
-rw-r--r--src/lib/util/ioprocsfilter.h240
2 files changed, 242 insertions, 2 deletions
diff --git a/src/lib/util/ioprocs.cpp b/src/lib/util/ioprocs.cpp
index 0dcea206571..059d537427e 100644
--- a/src/lib/util/ioprocs.cpp
+++ b/src/lib/util/ioprocs.cpp
@@ -2,9 +2,9 @@
// copyright-holders:Vas Crabb
/***************************************************************************
- ioprocs.h
+ ioprocs.cpp
- I/O interfaces
+ I/O interface implementations for RAM, C standard I/O and OSD files
***************************************************************************/
diff --git a/src/lib/util/ioprocsfilter.h b/src/lib/util/ioprocsfilter.h
index 825fcefc680..fbe24ab46e9 100644
--- a/src/lib/util/ioprocsfilter.h
+++ b/src/lib/util/ioprocsfilter.h
@@ -19,25 +19,265 @@
namespace util {
+/// \addtogroup ioprocs
+/// \{
+
+/// \brief Create a read stream filter that fills unused buffer space
+///
+/// Creates a sequential read stream filter that fills unused buffer
+/// space with a specified byte value. If a read operation does not
+/// produce enough data to fill the supplied buffer, the remaining space
+/// in the buffer is filled with the specified filler byte value. Takes
+/// ownership of the underlying input stream.
+/// \param [in] stream Underlying stream to read from.
+/// \param [in] filler Byte value to fill unused buffer space.
+/// \return A pointer to a sequential read stream, or nullptr on error.
+/// \sa read_stream
std::unique_ptr<read_stream> read_stream_fill(std::unique_ptr<read_stream> &&stream, std::uint8_t filler) noexcept;
+
+/// \brief Create a random access input filter that fills unused buffer
+/// space
+///
+/// Creates a random access input filter that fills unused buffer space
+/// with a specified byte value. If a read operation does not produce
+/// enough data to fill the supplied buffer, the remaining space in the
+/// buffer is filled with the specified filler byte value. Takes
+/// ownership of the underlying input sequence.
+/// \param [in] stream Underlying input sequence to read from.
+/// \param [in] filler Byte value to fill unused buffer space.
+/// \return A pointer to a random access input sequence, or nullptr on
+/// error.
+/// \sa random_read
std::unique_ptr<random_read> random_read_fill(std::unique_ptr<random_read> &&stream, std::uint8_t filler) noexcept;
+
+/// \brief Create a read stream filter that fills unused buffer space
+///
+/// Creates a sequential read stream filter that fills unused buffer
+/// space with a specified byte value. If a read operation does not
+/// produce enough data to fill the supplied buffer, the remaining space
+/// in the buffer is filled with the specified filler byte value. Does
+/// not take ownership of the underlying input stream.
+/// \param [in] stream Underlying stream to read from.
+/// \param [in] filler Byte value to fill unused buffer space.
+/// \return A pointer to a sequential read stream, or nullptr on error.
+/// \sa read_stream
std::unique_ptr<read_stream> read_stream_fill(read_stream &stream, std::uint8_t filler) noexcept;
+
+/// \brief Create a random access input filter that fills unused buffer
+/// space
+///
+/// Creates a random access input filter that fills unused buffer space
+/// with a specified byte value. If a read operation does not produce
+/// enough data to fill the supplied buffer, the remaining space in the
+/// buffer is filled with the specified filler byte value. Does not
+/// take ownership of the underlying input sequence.
+/// \param [in] stream Underlying input sequence to read from.
+/// \param [in] filler Byte value to fill unused buffer space.
+/// \return A pointer to a random access input sequence, or nullptr on
+/// error.
+/// \sa random_read
std::unique_ptr<random_read> random_read_fill(random_read &stream, std::uint8_t filler) noexcept;
+
+/// \brief Create a random access output filter that fills unwritten
+/// space
+///
+/// Creates a random access output filter that fills unwritten space
+/// with a specified byte value. If a write operation starts beyond the
+/// end of the output, the space between the end of the output and the
+/// start of the written data is filled with the specified filler byte
+/// value. Takes ownership of the underlying output sequence.
+/// \param [in] stream Underlying output sequence to write to.
+/// \param [in] filler Byte value to fill unwritten space.
+/// \return A pointer to a random access output sequence, or nullptr on
+/// error.
+/// \sa random_write
std::unique_ptr<random_write> random_write_fill(std::unique_ptr<random_write> &&stream, std::uint8_t filler) noexcept;
+
+/// \brief Create a random access output filter that fills unwritten
+/// space
+///
+/// Creates a random access output filter that fills unwritten space
+/// with a specified byte value. If a write operation starts beyond the
+/// end of the output, the space between the end of the output and the
+/// start of the written data is filled with the specified filler byte
+/// value. Does not take ownership of the underlying output sequence.
+/// \param [in] stream Underlying output sequence to write to.
+/// \param [in] filler Byte value to fill unwritten space.
+/// \return A pointer to a random access output sequence, or nullptr on
+/// error.
+/// \sa random_write
std::unique_ptr<random_write> random_write_fill(random_write &stream, std::uint8_t filler) noexcept;
+
+/// \brief Create a random access I/O filter that fills unused space
+///
+/// Creates a random access I/O sequence that fills unused read buffer
+/// space and unwritten space with a specified byte value. If a read
+/// operation does not produce enough data to fill the supplied buffer,
+/// the remaining space in the buffer is filled with the specified
+/// filler byte value. If a write operation starts beyond the end of
+/// the output, the space between the end of the output and the start of
+/// the written data is filled with the specified filler byte value.
+/// Takes ownership of the underlying I/O sequence.
+/// \param [in] stream Underlying I/O sequence to read from and write
+/// to.
+/// \param [in] filler Byte value to fill unused read buffer space and
+/// unwritten space.
+/// \return A pointer to a random access I/O sequence, or nullptr on
+/// error.
+/// \sa random_read_write
std::unique_ptr<random_read_write> random_read_write_fill(std::unique_ptr<random_read_write> &&stream, std::uint8_t filler) noexcept;
+
+/// \brief Create a random access I/O filter that fills unused space
+///
+/// Creates a random access I/O sequence that fills unused read buffer
+/// space and unwritten space with a specified byte value. If a read
+/// operation does not produce enough data to fill the supplied buffer,
+/// the remaining space in the buffer is filled with the specified
+/// filler byte value. If a write operation starts beyond the end of
+/// the output, the space between the end of the output and the start of
+/// the written data is filled with the specified filler byte value.
+/// Does not take ownership of the underlying I/O sequence.
+/// \param [in] stream Underlying I/O sequence to read from and write
+/// to.
+/// \param [in] filler Byte value to fill unused read buffer space and
+/// unwritten space.
+/// \return A pointer to a random access I/O sequence, or nullptr on
+/// error.
+/// \sa random_read_write
std::unique_ptr<random_read_write> random_read_write_fill(random_read_write &stream, std::uint8_t filler) noexcept;
+
+/// \brief Create an input stream filter that decompresses
+/// zlib-compressed data
+///
+/// Creates a read stream that decompresses zlib-compressed (deflated)
+/// data read from the underlying input stream. A read operation will
+/// always stop on reaching an end-of-stream marker in the compressed
+/// data. A subsequent read operation will expect to find the beginning
+/// of another block of compressed data. May read past the end of the
+/// compressed data in the underlying input stream. Takes ownership of
+/// the underlying input stream.
+/// \param [in] stream Underlying input stream to read from.
+/// \param [in] read_chunk Size of buffer for reading compressed data in
+/// bytes.
+/// \return A pointer to an input stream, or nullptr on error.
+/// \sa read_stream
std::unique_ptr<read_stream> zlib_read(std::unique_ptr<read_stream> &&stream, std::size_t read_chunk) noexcept;
+
+/// \brief Create an input stream filter that decompresses
+/// zlib-compressed data
+///
+/// Creates a read stream that decompresses zlib-compressed (deflated)
+/// data read from the underlying input sequence. A read operation will
+/// always stop on reaching an end-of-stream marker in the compressed
+/// data. A subsequent read operation will expect to find the beginning
+/// of another block of compressed data. If a read operation reads past
+/// an end-of-stream marker in the compressed data, it will seek back so
+/// the position for the next read from the underlying input sequence
+/// immediately follows the end-of-stream marker. Takes ownership of
+/// the underlying input sequence.
+/// \param [in] stream Underlying input sequence to read from. Must
+/// support seeking relative to the current position.
+/// \param [in] read_chunk Size of buffer for reading compressed data in
+/// bytes.
+/// \return A pointer to an input stream, or nullptr on error.
+/// \sa read_stream random_read
std::unique_ptr<read_stream> zlib_read(std::unique_ptr<random_read> &&stream, std::size_t read_chunk) noexcept;
+
+/// \brief Create an input stream filter that decompresses
+/// zlib-compressed data
+///
+/// Creates a read stream that decompresses zlib-compressed (deflated)
+/// data read from the underlying input stream. A read operation will
+/// always stop on reaching an end-of-stream marker in the compressed
+/// data. A subsequent read operation will expect to find the beginning
+/// of another block of compressed data. May read past the end of the
+/// compressed data in the underlying input stream. Does not take
+/// ownership of the underlying input stream.
+/// \param [in] stream Underlying input stream to read from.
+/// \param [in] read_chunk Size of buffer for reading compressed data in
+/// bytes.
+/// \return A pointer to an input stream, or nullptr on error.
+/// \sa read_stream
std::unique_ptr<read_stream> zlib_read(read_stream &stream, std::size_t read_chunk) noexcept;
+
+/// \brief Create an input stream filter that decompresses
+/// zlib-compressed data
+///
+/// Creates a read stream that decompresses zlib-compressed (deflated)
+/// data read from the underlying input sequence. A read operation will
+/// always stop on reaching an end-of-stream marker in the compressed
+/// data. A subsequent read operation will expect to find the beginning
+/// of another block of compressed data. If a read operation reads past
+/// an end-of-stream marker in the compressed data, it will seek back so
+/// the position for the next read from the underlying input sequence
+/// immediately follows the end-of-stream marker. Does not take
+/// ownership of the underlying input sequence.
+/// \param [in] stream Underlying input sequence to read from. Must
+/// support seeking relative to the current position.
+/// \param [in] read_chunk Size of buffer for reading compressed data in
+/// bytes.
+/// \return A pointer to an input stream, or nullptr on error.
+/// \sa read_stream random_read
std::unique_ptr<read_stream> zlib_read(random_read &stream, std::size_t read_chunk) noexcept;
+
+/// \brief Create an output stream filter that writes zlib-compressed
+/// data
+///
+/// Creates an output stream that compresses data using the zlib deflate
+/// algorithm and writes it to the underlying output stream. Calling
+/// the \c finalize member function compresses any buffered input,
+/// produces an end-of-stream maker, and writes any buffered compressed
+/// data to the underlying output stream. A subsequent write operation
+/// will start a new compressed block. Calling the \c flush member
+/// function writes any buffered compressed data to the underlying
+/// output stream and calls the \c flush member function of the
+/// underlying output stream; it does not ensure all buffered input data
+/// is compressed or force the end of a compressed block. Takes
+/// ownership of the underlying output stream.
+/// \param [in] stream Underlying output stream for writing compressed
+/// data.
+/// \param [in] level Compression level. Use 0 for no compression, 1
+/// for fastest compression, 9 for maximum compression, or -1 for the
+/// default compression level as defined by the zlib library. Larger
+/// values between 1 and 9 provide higher compression at the expense
+/// of speed.
+/// \param [in] buffer_size Size of buffer for compressed data in bytes.
+/// \return A pointer to an output stream, or nullptr on error.
+/// \sa write_stream
std::unique_ptr<write_stream> zlib_write(std::unique_ptr<write_stream> &&stream, int level, std::size_t buffer_size) noexcept;
+
+/// \brief Create an output stream filter that writes zlib-compressed
+/// data
+///
+/// Creates an output stream that compresses data using the zlib deflate
+/// algorithm and writes it to the underlying output stream. Calling
+/// the \c finalize member function compresses any buffered input,
+/// produces an end-of-stream maker, and writes any buffered compressed
+/// data to the underlying output stream. A subsequent write operation
+/// will start a new compressed block. Calling the \c flush member
+/// function writes any buffered compressed data to the underlying
+/// output stream and calls the \c flush member function of the
+/// underlying output stream; it does not ensure all buffered input data
+/// is compressed or force the end of a compressed block. Does not take
+/// ownership of the underlying output stream.
+/// \param [in] stream Underlying output stream for writing compressed
+/// data.
+/// \param [in] level Compression level. Use 0 for no compression, 1
+/// for fastest compression, 9 for maximum compression, or -1 for the
+/// default compression level as defined by the zlib library. Larger
+/// values between 1 and 9 provide higher compression at the expense
+/// of speed.
+/// \param [in] buffer_size Size of buffer for compressed data in bytes.
+/// \return A pointer to an output stream, or nullptr on error.
+/// \sa write_stream
std::unique_ptr<write_stream> zlib_write(write_stream &stream, int level, std::size_t buffer_size) noexcept;
+/// \}
+
} // namespace util
#endif // MAME_LIB_UTIL_IOPROCSFILTER_H