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*/ 174