From 3528f5bb69184d6b3da7201c51c56068fe907f04 Mon Sep 17 00:00:00 2001 From: John Scipione Date: Sat, 19 Jan 2013 15:05:11 -0500 Subject: [PATCH] Add BBitmapStream docs and translation kit stub --- docs/user/Doxyfile | 2 + docs/user/book.dox | 7 + docs/user/translation/BitmapStream.dox | 170 +++++++++++++++++++++++++ 3 files changed, 179 insertions(+) create mode 100644 docs/user/translation/BitmapStream.dox diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index b7791ede72..43e0c1f2ce 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -641,6 +641,7 @@ INPUT = . \ midi2 \ storage \ support \ + translation \ ../../headers/os/app \ ../../headers/os/drivers/fs_interface.h \ ../../headers/os/drivers/USB3.h \ @@ -652,6 +653,7 @@ INPUT = . \ ../../headers/os/midi2 \ ../../headers/os/storage \ ../../headers/os/support \ + ../../headers/os/translation \ ../../headers/posix/syslog.h \ ../../src/kits/game/GameProducer.h diff --git a/docs/user/book.dox b/docs/user/book.dox index d057d81859..8d7db458fe 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -52,6 +52,8 @@ retrieving information from disk. - The \ref support contains support classes to use in your application including resources for thread safety, IO, and serialization. + - The \ref translation provides a framework for converting data streams + between media formats. \section special_topics Special Topics @@ -543,6 +545,11 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE); - Error codes for all kits + \defgroup translation Translation Kit + \brief Provides a framework for converting data streams between media + formats. + + \defgroup libbe (libbe.so) diff --git a/docs/user/translation/BitmapStream.dox b/docs/user/translation/BitmapStream.dox new file mode 100644 index 0000000000..26eaa93414 --- /dev/null +++ b/docs/user/translation/BitmapStream.dox @@ -0,0 +1,170 @@ +/* + * Copyright 2002-2013 Haiku Inc. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * John Scipione + * Travis Smith + * Michael Wilber + * Corresponds to: + * /trunk/headers/os/translation/BitmapStream.h hrev45181 + * /trunk/src/kits/translation/BitmapStream.cpp hrev45181 + */ + + +/*! + \file BitmapStream.h + \brief BBitmapStream class definition. +*/ + + +/*! + \class BBitmapStream + \ingroup translation + \ingroup libbe + \brief Provides for the conversion of a Translation Kit bitmap object to + a BBitmap. + + BBitmapStream is limited subclass of BPositionIO that is good at reading + and writing Translation Kit bitmaps. The DetachBitmap() method + is the main method of this class as it returns the contents of the + Translation Kit bitmap object into a BBitmap. + + In most cases you shouldn't have to use this class directly as + BTranslationUtils contains methods to load images from files and + resources. +*/ + + +/*! + \fn BBitmapStream::BBitmapStream(BBitmap* bitmap) + \brief Initializes this object to either use the BBitmap passed to + it as the object to read/write to or to create a BBitmap when data + is written to this object. + + If \a bitmap is \c NULL, a new BBitmap object is created when this object + is written to. + + \param bitmap The bitmap object to read from/write to. +*/ + + +/*! + \fn void BBitmapStream::~BBitmapStream() + \brief Destroys the object and the BBitmap object if attached. +*/ + + +/*! + \fn ssize_t BBitmapStream::ReadAt(off_t pos, void* buffer, size_t size) + \brief Reads data from the stream into \a buffer at a specific position + and size. + + The first sizeof(TranslatorBitmap) bytes are the bitmap header. The header + is always written out and read in as big endian byte order. + + \param pos The position in the stream to read from. + \param buffer Where the data will be read into + \param size The amount of data to be read. + + \return The amount of data written if the result is >= 0 or an error code. + \retval B_BAD_VALUE \a buffer is \c NULL or \a pos is invalid or the amount + read if the result >= 0 + \retval B_NO_INIT There is no bitmap stored by the stream. +*/ + + +/*! + \fn ssize_t BBitmapStream::WriteAt(off_t pos, const void* data, + size_t size) + \brief Writes data to the bitmap starting at a specific position and size. + + The first sizeof(TranslatorBitmap) bytes of data must be the + TranslatorBitmap header in big endian byte order or the data + will not be written. + + \param pos The position in the stream to write to \a data. + \param data The data to write to the stream. + \param size The size of the data to write to the stream. + + \return The amount of data written if the result is >= 0 or an error code. + \retval B_BAD_VALUE Size is bad or data is \c NULL or \a pos is invalid. + \retval B_MISMATCHED_VALUES The bitmap header is bad. + \retval B_ERROR Error allocating memory or setting up big endian header, +*/ + + +/*! + \fn off_t BBitmapStream::Seek(off_t position, uint32 seekMode) + \brief Changes the current stream position. + + \param position The position offset. + \param seekMode Decides how the position offset is used: + - \c SEEK_CUR Position is added to current stream position. + - \c SEEK_END Position is added to the end stream position. + - \c SEEK_SET The stream position is set to position. + + \return The new position offset if the result >= 0. + \retval B_BAD_VALUE \a position was bad. +*/ + + +/*! + \fn off_t BBitmapStream::Position() const + \brief Gets the current stream position. + + \returns The current stream position. +*/ + + +/*! + \fn off_t BBitmapStream::Size() const + \brief Gets the current stream size. + + \returns The current stream size. +*/ + + +/*! + \fn status_t BBitmapStream::SetSize(off_t size) + \brief Sets the size of the data. + + \param size The size to set the stream size to. + + \return A status code, \c B_NO_ERROR on success or an error code. + \retval B_NO_ERROR (or \c B_OK) Size is a valid value. + \retval B_BAD_VALUE \a size is NOT a valid value. +*/ + + +/*! + \fn status_t BBitmapStream::DetachBitmap(BBitmap** _bitmap) + \brief Sets \a _bitmap to point to the internal bitmap object. + + The bitmap is not deleted when the BBitmapStream is deleted. After the + bitmap has been detached it is still used by the stream, but it is never + deleted by the stream. + + Once you have called DetachBitmap() no further operations should be + performed on the BBitmapStream except to destroy the object. + + \param _bitmap A BBitmap pointer that will be set to point to the internal + bitmap object. + + \return A status code, \c B_OK on success or an error code. + \retval B_OK The bitmap was detached. + \retval B_BAD_VALUE _bitmap is \c NULL. + \retval B_ERROR The internal bitmap object is \c NULL or has already been + detached. +*/ + + +/*! + \fn void BBitmapStream::SwapHeader(const TranslatorBitmap* source, + TranslatorBitmap* destination) + \brief Swaps the byte order of \a source, no matter the byte order, and + copies the result to \a destination. + + \param source Data to be swapped. + \param destination Where the swapped data will be copied to. +*/