1/****************************************************************************
2**
3** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
4** Contact: http://www.qt-project.org/legal
5**
6** This file is part of the QtGui module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Digia. For licensing terms and
14** conditions see http://qt.digia.com/licensing. For further information
15** use the contact form at http://qt.digia.com/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 2.1 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 2.1 requirements
23** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24**
25** In addition, as a special exception, Digia gives you certain additional
26** rights. These rights are described in the Digia Qt LGPL Exception
27** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28**
29** GNU General Public License Usage
30** Alternatively, this file may be used under the terms of the GNU
31** General Public License version 3.0 as published by the Free Software
32** Foundation and appearing in the file LICENSE.GPL included in the
33** packaging of this file. Please review the following information to
34** ensure the GNU General Public License version 3.0 requirements will be
35** met: http://www.gnu.org/copyleft/gpl.html.
36**
37**
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42#include "qbitmap.h"
43#include "qpixmapdata_p.h"
44#include "qimage.h"
45#include "qvariant.h"
46#include <qpainter.h>
47#include <private/qgraphicssystem_p.h>
48#include <private/qapplication_p.h>
49
50QT_BEGIN_NAMESPACE
51
52/*!
53 \class QBitmap
54 \brief The QBitmap class provides monochrome (1-bit depth) pixmaps.
55
56 \ingroup painting
57 \ingroup shared
58
59 The QBitmap class is a monochrome off-screen paint device used
60 mainly for creating custom QCursor and QBrush objects,
61 constructing QRegion objects, and for setting masks for pixmaps
62 and widgets.
63
64 QBitmap is a QPixmap subclass ensuring a depth of 1, except for
65 null objects which have a depth of 0. If a pixmap with a depth
66 greater than 1 is assigned to a bitmap, the bitmap will be
67 dithered automatically.
68
69 Use the QColor objects Qt::color0 and Qt::color1 when drawing on a
70 QBitmap object (or a QPixmap object with depth 1).
71
72 Painting with Qt::color0 sets the bitmap bits to 0, and painting
73 with Qt::color1 sets the bits to 1. For a bitmap, 0-bits indicate
74 background (or transparent pixels) and 1-bits indicate foreground
75 (or opaque pixels). Use the clear() function to set all the bits
76 to Qt::color0. Note that using the Qt::black and Qt::white colors
77 make no sense because the QColor::pixel() value is not necessarily
78 0 for black and 1 for white.
79
80 The QBitmap class provides the transformed() function returning a
81 transformed copy of the bitmap; use the QTransform argument to
82 translate, scale, shear, and rotate the bitmap. In addition,
83 QBitmap provides the static fromData() function which returns a
84 bitmap constructed from the given \c uchar data, and the static
85 fromImage() function returning a converted copy of a QImage
86 object.
87
88 Just like the QPixmap class, QBitmap is optimized by the use of
89 implicit data sharing. For more information, see the \l {Implicit
90 Data Sharing} documentation.
91
92 \sa QPixmap, QImage, QImageReader, QImageWriter
93*/
94
95/*! \typedef QBitmap::DataPtr
96 \internal
97 */
98
99/*!
100 Constructs a null bitmap.
101
102 \sa QPixmap::isNull()
103*/
104QBitmap::QBitmap()
105 : QPixmap(QSize(0, 0), QPixmapData::BitmapType)
106{
107}
108
109/*!
110 \fn QBitmap::QBitmap(int width, int height)
111
112 Constructs a bitmap with the given \a width and \a height. The pixels
113 inside are uninitialized.
114
115 \sa clear()
116*/
117
118QBitmap::QBitmap(int w, int h)
119 : QPixmap(QSize(w, h), QPixmapData::BitmapType)
120{
121}
122
123/*!
124 Constructs a bitmap with the given \a size. The pixels in the
125 bitmap are uninitialized.
126
127 \sa clear()
128*/
129
130QBitmap::QBitmap(const QSize &size)
131 : QPixmap(size, QPixmapData::BitmapType)
132{
133}
134
135/*!
136 \fn QBitmap::clear()
137
138 Clears the bitmap, setting all its bits to Qt::color0.
139*/
140
141/*!
142 Constructs a bitmap that is a copy of the given \a pixmap.
143
144 If the pixmap has a depth greater than 1, the resulting bitmap
145 will be dithered automatically.
146
147 \sa QPixmap::depth(), fromImage(), fromData()
148*/
149
150QBitmap::QBitmap(const QPixmap &pixmap)
151{
152 QBitmap::operator=(pixmap);
153}
154
155/*!
156 \fn QBitmap::QBitmap(const QImage &image)
157
158 Constructs a bitmap that is a copy of the given \a image.
159
160 Use the static fromImage() function instead.
161*/
162
163/*!
164 Constructs a bitmap from the file specified by the given \a
165 fileName. If the file does not exist, or has an unknown format,
166 the bitmap becomes a null bitmap.
167
168 The \a fileName and \a format parameters are passed on to the
169 QPixmap::load() function. If the file format uses more than 1 bit
170 per pixel, the resulting bitmap will be dithered automatically.
171
172 \sa QPixmap::isNull(), QImageReader::imageFormat()
173*/
174
175QBitmap::QBitmap(const QString& fileName, const char *format)
176 : QPixmap(QSize(0, 0), QPixmapData::BitmapType)
177{
178 load(fileName, format, Qt::MonoOnly);
179}
180
181/*!
182 \overload
183
184 Assigns the given \a pixmap to this bitmap and returns a reference
185 to this bitmap.
186
187 If the pixmap has a depth greater than 1, the resulting bitmap
188 will be dithered automatically.
189
190 \sa QPixmap::depth()
191 */
192
193QBitmap &QBitmap::operator=(const QPixmap &pixmap)
194{
195 if (pixmap.isNull()) { // a null pixmap
196 QBitmap bm(0, 0);
197 QBitmap::operator=(bm);
198 } else if (pixmap.depth() == 1) { // 1-bit pixmap
199 QPixmap::operator=(pixmap); // shallow assignment
200 } else { // n-bit depth pixmap
201 QImage image;
202 image = pixmap.toImage(); // convert pixmap to image
203 *this = fromImage(image); // will dither image
204 }
205 return *this;
206}
207
208
209#ifdef QT3_SUPPORT
210QBitmap::QBitmap(int w, int h, const uchar *bits, bool isXbitmap)
211{
212 *this = fromData(QSize(w, h), bits, isXbitmap ? QImage::Format_MonoLSB : QImage::Format_Mono);
213}
214
215
216QBitmap::QBitmap(const QSize &size, const uchar *bits, bool isXbitmap)
217{
218 *this = fromData(size, bits, isXbitmap ? QImage::Format_MonoLSB : QImage::Format_Mono);
219}
220#endif
221
222/*!
223 Destroys the bitmap.
224*/
225QBitmap::~QBitmap()
226{
227}
228
229/*!
230 \fn void QBitmap::swap(QBitmap &other)
231 \since 4.8
232
233 Swaps bitmap \a other with this bitmap. This operation is very
234 fast and never fails.
235*/
236
237/*!
238 Returns the bitmap as a QVariant.
239*/
240QBitmap::operator QVariant() const
241{
242 return QVariant(QVariant::Bitmap, this);
243}
244
245/*!
246 \fn QBitmap &QBitmap::operator=(const QImage &image)
247 \overload
248
249 Converts the given \a image to a bitmap, and assigns the result to
250 this bitmap. Returns a reference to the bitmap.
251
252 Use the static fromImage() function instead.
253*/
254
255/*!
256 Returns a copy of the given \a image converted to a bitmap using
257 the specified image conversion \a flags.
258
259 \sa fromData()
260*/
261QBitmap QBitmap::fromImage(const QImage &image, Qt::ImageConversionFlags flags)
262{
263 if (image.isNull())
264 return QBitmap();
265
266 QImage img = image.convertToFormat(QImage::Format_MonoLSB, flags);
267
268 // make sure image.color(0) == Qt::color0 (white)
269 // and image.color(1) == Qt::color1 (black)
270 const QRgb c0 = QColor(Qt::black).rgb();
271 const QRgb c1 = QColor(Qt::white).rgb();
272 if (img.color(0) == c0 && img.color(1) == c1) {
273 img.invertPixels();
274 img.setColor(0, c1);
275 img.setColor(1, c0);
276 }
277
278 QGraphicsSystem* gs = QApplicationPrivate::graphicsSystem();
279 QScopedPointer<QPixmapData> data(gs ? gs->createPixmapData(QPixmapData::BitmapType)
280 : QGraphicsSystem::createDefaultPixmapData(QPixmapData::BitmapType));
281
282 data->fromImage(img, flags | Qt::MonoOnly);
283 return QPixmap(data.take());
284}
285
286/*!
287 Constructs a bitmap with the given \a size, and sets the contents to
288 the \a bits supplied.
289
290 The bitmap data has to be byte aligned and provided in in the bit
291 order specified by \a monoFormat. The mono format must be either
292 QImage::Format_Mono or QImage::Format_MonoLSB. Use
293 QImage::Format_Mono to specify data on the XBM format.
294
295 \sa fromImage()
296
297*/
298QBitmap QBitmap::fromData(const QSize &size, const uchar *bits, QImage::Format monoFormat)
299{
300 Q_ASSERT(monoFormat == QImage::Format_Mono || monoFormat == QImage::Format_MonoLSB);
301
302 QImage image(size, monoFormat);
303 image.setColor(0, QColor(Qt::color0).rgb());
304 image.setColor(1, QColor(Qt::color1).rgb());
305
306 // Need to memcpy each line separatly since QImage is 32bit aligned and
307 // this data is only byte aligned...
308 int bytesPerLine = (size.width() + 7) / 8;
309 for (int y = 0; y < size.height(); ++y)
310 memcpy(image.scanLine(y), bits + bytesPerLine * y, bytesPerLine);
311 return QBitmap::fromImage(image);
312}
313
314/*!
315 Returns a copy of this bitmap, transformed according to the given
316 \a matrix.
317
318 \sa QPixmap::transformed()
319 */
320QBitmap QBitmap::transformed(const QTransform &matrix) const
321{
322 QBitmap bm = QPixmap::transformed(matrix);
323 return bm;
324}
325
326/*!
327 \overload
328 \obsolete
329
330 This convenience function converts the \a matrix to a QTransform
331 and calls the overloaded function.
332*/
333QBitmap QBitmap::transformed(const QMatrix &matrix) const
334{
335 return transformed(QTransform(matrix));
336}
337
338#ifdef QT3_SUPPORT
339/*!
340 \fn QBitmap QBitmap::xForm(const QMatrix &matrix) const
341
342 Returns a copy of this bitmap, transformed according to the given
343 \a matrix.
344
345 Use transformed() instead.
346*/
347
348/*!
349 \fn QBitmap::QBitmap(const QSize &size, bool clear)
350
351 Constructs a bitmap with the given \a size. If \a clear is true,
352 the bits are initialized to Qt::color0.
353
354 Use the corresponding QBitmap() constructor instead, and then call
355 the clear() function if the \a clear parameter is true.
356*/
357
358/*!
359 \fn QBitmap::QBitmap(int width, int height, bool clear)
360
361 Constructs a bitmap with the given \a width and \a height. If \a
362 clear is true, the bits are initialized to Qt::color0.
363
364 Use the corresponding QBitmap() constructor instead, and then call
365 the clear() function if the \a clear parameter is true.
366*/
367
368/*!
369 \fn QBitmap::QBitmap(int width, int height, const uchar *bits, bool isXbitmap)
370
371 Constructs a bitmap with the given \a width and \a height, and
372 sets the contents to the \a bits supplied. The \a isXbitmap flag
373 should be true if \a bits was generated by the X11 bitmap
374 program.
375
376 Use the static fromData() function instead. If \a isXbitmap is
377 true, use the default bit order(QImage_FormatMonoLSB) otherwise
378 use QImage::Format_Mono.
379
380 \omit
381 The X bitmap bit order is little endian. The QImage
382 documentation discusses bit order of monochrome images. Opposed to
383 QImage, the data has to be byte aligned.
384
385 Example (creates an arrow bitmap):
386 \snippet doc/src/snippets/code/src_gui_image_qbitmap.cpp 0
387 \endomit
388*/
389
390
391/*!
392 \fn QBitmap::QBitmap(const QSize &size, const uchar *bits, bool isXbitmap)
393
394 \overload
395
396 Constructs a bitmap with the given \a size, and sets the contents
397 to the \a bits supplied. The \a isXbitmap flag should be true if
398 \a bits was generated by the X11 bitmap program.
399
400 \omit
401 The X bitmap bit order is little endian. The QImage documentation
402 discusses bit order of monochrome images.
403 \endomit
404
405 Use the static fromData() function instead. If \a isXbitmap is
406 true, use the default bit order(QImage_FormatMonoLSB) otherwise
407 use QImage::Format_Mono.
408*/
409#endif
410
411QT_END_NAMESPACE
412