docs/user/translation/BitmapStream.dox

   1 /*
   2  * Copyright 2002-2013 Haiku Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              John Scipione, jscipione@gmail.com
   7  *              Travis Smith
   8  *              Michael Wilber
   9  *
  10  * Corresponds to:
  11  *              headers/os/translation/BitmapStream.h    hrev45181
  12  *              src/kits/translation/BitmapStream.cpp    hrev45181
  13  */
  14
  15
  16 /*!
  17         \file BitmapStream.h
  18         \ingroup translation
  19         \ingroup libbe
  20         \brief BBitmapStream class definition.
  21 */
  22
  23
  24 /*!
  25         \class BBitmapStream
  26         \ingroup translation
  27         \ingroup libbe
  28         \brief Provides for the conversion of a Translation Kit bitmap object to
  29                 a BBitmap.
  30
  31         BBitmapStream is limited subclass of BPositionIO that is good at reading
  32         and writing Translation Kit bitmaps. The DetachBitmap() method
  33         is the main method of this class as it returns the contents of the
  34         Translation Kit bitmap object into a BBitmap.
  35
  36         In most cases you shouldn't have to use this class directly as
  37         BTranslationUtils contains methods to load images from files and
  38         resources.
  39 */
  40
  41
  42 /*!
  43         \fn BBitmapStream::BBitmapStream(BBitmap* bitmap)
  44         \brief Initializes this object to either use the BBitmap passed to
  45                 it as the object to read/write to or to create a BBitmap when data
  46                 is written to this object.
  47
  48         If \a bitmap is \c NULL, a new BBitmap object is created when this object
  49         is written to.
  50
  51         \param bitmap The bitmap object to read from/write to.
  52 */
  53
  54
  55 /*!
  56         \fn void BBitmapStream::~BBitmapStream()
  57         \brief Destroys the object and the BBitmap object if attached.
  58 */
  59
  60
  61 /*!
  62         \fn ssize_t BBitmapStream::ReadAt(off_t pos, void* buffer, size_t size)
  63         \brief Reads data from the stream into \a buffer at a specific position
  64                 and size.
  65
  66         The first sizeof(TranslatorBitmap) bytes are the bitmap header. The header
  67         is always written out and read in as big endian byte order.
  68
  69         \param pos The position in the stream to read from.
  70         \param buffer Where the data will be read into
  71         \param size The amount of data to be read.
  72
  73         \return The amount of data written if the result is >= 0 or an error code.
  74         \retval B_BAD_VALUE \a buffer is \c NULL or \a pos is invalid or the amount
  75                 read if the result >= 0
  76         \retval B_NO_INIT There is no bitmap stored by the stream.
  77 */
  78
  79
  80 /*!
  81         \fn ssize_t BBitmapStream::WriteAt(off_t pos, const void* data,
  82                 size_t size)
  83         \brief Writes data to the bitmap starting at a specific position and size.
  84
  85         The first sizeof(TranslatorBitmap) bytes of data must be the
  86         TranslatorBitmap header in big endian byte order or the data
  87         will not be written.
  88
  89         \param pos The position in the stream to write to \a data.
  90         \param data The data to write to the stream.
  91         \param size The size of the data to write to the stream.
  92
  93         \return The amount of data written if the result is >= 0 or an error code.
  94         \retval B_BAD_VALUE Size is bad or data is \c NULL or \a pos is invalid.
  95         \retval B_MISMATCHED_VALUES The bitmap header is bad.
  96         \retval B_ERROR Error allocating memory or setting up big endian header,
  97 */
  98
  99
 100 /*!
 101         \fn off_t BBitmapStream::Seek(off_t position, uint32 seekMode)
 102         \brief Changes the current stream position.
 103
 104         \param position The position offset.
 105         \param seekMode Decides how the position offset is used:
 106         - \c SEEK_CUR Position is added to current stream position.
 107         - \c SEEK_END Position is added to the end stream position.
 108         - \c SEEK_SET The stream position is set to position.
 109
 110         \return The new position offset if the result >= 0.
 111         \retval B_BAD_VALUE \a position was bad.
 112 */
 113
 114
 115 /*!
 116         \fn off_t BBitmapStream::Position() const
 117         \brief Gets the current stream position.
 118
 119         \returns The current stream position.
 120 */
 121
 122
 123 /*!
 124         \fn off_t BBitmapStream::Size() const
 125         \brief Gets the current stream size.
 126
 127         \returns The current stream size.
 128 */
 129
 130
 131 /*!
 132         \fn status_t BBitmapStream::SetSize(off_t size)
 133         \brief Sets the size of the data.
 134
 135         \param size The size to set the stream size to.
 136
 137         \return A status code, \c B_NO_ERROR on success or an error code.
 138         \retval B_NO_ERROR (or \c B_OK) Size is a valid value.
 139         \retval B_BAD_VALUE \a size is NOT a valid value.
 140 */
 141
 142
 143 /*!
 144         \fn status_t BBitmapStream::DetachBitmap(BBitmap** _bitmap)
 145         \brief Sets \a _bitmap to point to the internal bitmap object.
 146
 147         The bitmap is not deleted when the BBitmapStream is deleted. After the
 148         bitmap has been detached it is still used by the stream, but it is never
 149         deleted by the stream.
 150
 151         Once you have called DetachBitmap() no further operations should be
 152         performed on the BBitmapStream except to destroy the object.
 153
 154         \param _bitmap A BBitmap pointer that will be set to point to the internal
 155                 bitmap object.
 156
 157         \return A status code, \c B_OK on success or an error code.
 158         \retval B_OK The bitmap was detached.
 159         \retval B_BAD_VALUE _bitmap is \c NULL.
 160         \retval B_ERROR The internal bitmap object is \c NULL or has already been
 161                 detached.
 162 */
 163
 164
 165 /*!
 166         \fn void BBitmapStream::SwapHeader(const TranslatorBitmap* source,
 167                 TranslatorBitmap* destination)
 168         \brief Swaps the byte order of \a source, no matter the byte order, and
 169                 copies the result to \a destination.
 170
 171         \param source Data to be swapped.
 172         \param destination Where the swapped data will be copied to.
 173 */