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