[haiku-commits] haiku: hrev45182 - docs/user/translation src/kits/translation docs/user
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Sat, 19 Jan 2013 21:05:43 +0100 (CET)
hrev45182 adds 2 changesets to branch 'master'
old head: 6a4b222bc9666e27518ce30b0fcaf75818fdd580
new head: 3528f5bb69184d6b3da7201c51c56068fe907f04
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=3528f5b+%5E6a4b222
----------------------------------------------------------------------------
278bcb5: Remove docs from BitmapStream.cpp
3528f5b: Add BBitmapStream docs and translation kit stub
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
4 files changed, 192 insertions(+), 67 deletions(-)
docs/user/Doxyfile | 2 +
docs/user/book.dox | 7 ++
docs/user/translation/BitmapStream.dox | 170 +++++++++++++++++++++++++++++
src/kits/translation/BitmapStream.cpp | 80 +++-----------
############################################################################
Commit: 278bcb57e76d634a01c8d1e594fd1167375c07c8
URL: http://cgit.haiku-os.org/haiku/commit/?id=278bcb5
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Sat Jan 19 20:04:34 2013 UTC
Remove docs from BitmapStream.cpp
----------------------------------------------------------------------------
diff --git a/src/kits/translation/BitmapStream.cpp
b/src/kits/translation/BitmapStream.cpp
index db2572f..9bc9634 100644
--- a/src/kits/translation/BitmapStream.cpp
+++ b/src/kits/translation/BitmapStream.cpp
@@ -18,13 +18,9 @@
#include <Debug.h>
-/*! 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.
-
- \param bitmap the bitmap used to read from/write to, if it is NULL, a
- bitmap is created when this object is written to.
-*/
+// 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.
BBitmapStream::BBitmapStream(BBitmap* bitmap)
{
fBitmap = bitmap;
@@ -65,16 +61,7 @@ BBitmapStream::~BBitmapStream()
}
-/*! Reads data from the stream at a specific position and for a
- specific amount. 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 buffer, where the
data
- will be read into size, the amount of data to read
- \return B_ERROR if there is no bitmap stored by the stream, B_BAD_VALUE
if
- buffer is NULL or pos is invalid or the amount read if the
result >= 0
-*/
+// Reads data from the stream at a specific position and size.
ssize_t
BBitmapStream::ReadAt(off_t pos, void* buffer, size_t size)
{
@@ -104,19 +91,7 @@ BBitmapStream::ReadAt(off_t pos, void* buffer, size_t size)
}
-/*! Writes data to the bitmap from data, starting at position pos
- of size, size. The first sizeof(TranslatorBitmap) bytes
- of data must be the TranslatorBitmap header in the Big
- Endian byte order, otherwise, the data will fail to be
- successfully written.
-
- \param pos, the position in the stream to write to data, the data to
write
- to the stream size, the size of the data to write to the stream
- \return B_BAD_VALUE if size is bad or data is NULL or pos is invalid,
- B_MISMATCHED_VALUES if the bitmap header is bad,
- B_ERROR if error allocating memory or setting up big endian
header,
- or the amount written if the result is >= 0
-*/
+// Writes data to the bitmap starting at a specific position and size.
ssize_t
BBitmapStream::WriteAt(off_t pos, const void* data, size_t size)
{
@@ -198,16 +173,7 @@ BBitmapStream::WriteAt(off_t pos, const void* data, size_t
size)
}
-/*! Changes the current stream position.
-
- \param position the position offset
- \param seekMode decides how the position offset is used:
- SEEK_CUR, position is added to current stream position
- SEEK_END, position is added to the end stream position
- SEEK_SET, the stream position is set to position
- \return B_BAD_VALUE if the position is bad or the new position value if
the
- result >= 0
-*/
+// Changes the current stream position.
off_t
BBitmapStream::Seek(off_t position, uint32 seekMode)
{
@@ -226,8 +192,7 @@ BBitmapStream::Seek(off_t position, uint32 seekMode)
}
-/*! Returns the current stream position
-*/
+// Returns the current stream position
off_t
BBitmapStream::Position() const
{
@@ -236,8 +201,7 @@ BBitmapStream::Position() const
-/*! Returns the curren stream size
-*/
+// Returns the current stream size
off_t
BBitmapStream::Size() const
{
@@ -245,13 +209,8 @@ BBitmapStream::Size() const
}
-/*! Sets the size of the data, but I'm not sure if this function has any
real
- purpose.
-
- \param size the size to set the stream size to.
- \return B_BAD_VALUE, if size is a bad value, B_NO_ERROR, if size is a
- valid value
-*/
+// Sets the size of the data.
+// I'm not sure if this method has any real purpose.
status_t
BBitmapStream::SetSize(off_t size)
{
@@ -272,16 +231,7 @@ BBitmapStream::SetSize(off_t size)
}
-/*! Returns the internal bitmap through outBitmap so the user
- can do whatever they want to it. It means that when the
- BBitmapStream is deleted, the bitmap is not deleted. After
- the bitmap has been detached, it is still used by the stream,
- but it is never deleted by the stream.
-
- \param _bitmap where the bitmap is detached to
- \return B_BAD_VALUE, if outBitmap is NULL, B_ERROR, if the bitmap is
NULL or
- has already been detached, B_OK, if the bitmap was successfully
detached
-*/
+// Sets _bitmap to point to the internal bitmap object.
status_t
BBitmapStream::DetachBitmap(BBitmap** _bitmap)
{
@@ -297,12 +247,8 @@ BBitmapStream::DetachBitmap(BBitmap** _bitmap)
}
-/*! Swaps the byte order of source, no matter what the
- byte order, and copies the result to destination
-
- \param source data to be swapped
- \param destination where the swapped data will be copied to
-*/
+// Swaps the byte order of source, no matter the byte order, and
+// copies the result to destination.
void
BBitmapStream::SwapHeader(const TranslatorBitmap* source,
TranslatorBitmap* destination)
############################################################################
Revision: hrev45182
Commit: 3528f5bb69184d6b3da7201c51c56068fe907f04
URL: http://cgit.haiku-os.org/haiku/commit/?id=3528f5b
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Sat Jan 19 20:05:11 2013 UTC
Add BBitmapStream docs and translation kit stub
----------------------------------------------------------------------------
diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile
index b7791ed..43e0c1f 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 d057d81..8d7db45 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 0000000..26eaa93
--- /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 <jscipione@xxxxxxxxx>
+ * 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.
+*/
Other related posts:
- » [haiku-commits] haiku: hrev45182 - docs/user/translation src/kits/translation docs/user - jscipione
