qimageiohandler.cpp

Absolute File Name:

/home/qt/qt5_coco/qt5/qtbase/src/gui/image/qimageiohandler.cpp

Source code

Switch to Preprocessed file

Line Source Count

1 /**************************************************************************** -

2 ** -

4 ** Contact: http://www.qt.io/licensing/ -

5 ** -

6 ** This file is part of the QtGui module of the Qt Toolkit. -

7 ** -

8 ** $QT_BEGIN_LICENSE:LGPL21$ -

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 The Qt Company. For licensing terms -

14 ** and conditions see http://www.qt.io/terms-conditions. For further -

15 ** information use the contact form at http://www.qt.io/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 or version 3 as published by the Free -

20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and -

21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the -

22 ** following information to ensure the GNU Lesser General Public License -

23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -

24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -

25 ** -

26 ** As a special exception, The Qt Company gives you certain additional -

27 ** rights. These rights are described in The Qt Company LGPL Exception -

28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -

29 ** -

30 ** $QT_END_LICENSE$ -

31 ** -

32 ****************************************************************************/ -

33 -

34 /*! -

35 \class QImageIOHandler -

36 \brief The QImageIOHandler class defines the common image I/O -

37 interface for all image formats in Qt. -

38 \reentrant -

39 \inmodule QtGui -

40 -

41 Qt uses QImageIOHandler for reading and writing images through -

42 QImageReader and QImageWriter. You can also derive from this class -

43 to write your own image format handler using Qt's plugin mechanism. -

44 -

45 Call setDevice() to assign a device to the handler, and -

46 setFormat() to assign a format to it. One QImageIOHandler may -

47 support more than one image format. canRead() returns \c true if an -

48 image can be read from the device, and read() and write() return -

49 true if reading or writing an image was completed successfully. -

50 -

51 QImageIOHandler also has support for animations formats, through -

52 the functions loopCount(), imageCount(), nextImageDelay() and -

53 currentImageNumber(). -

54 -

55 In order to determine what options an image handler supports, Qt -

56 will call supportsOption() and setOption(). Make sure to -

57 reimplement these functions if you can provide support for any of -

58 the options in the ImageOption enum. -

59 -

60 To write your own image handler, you must at least reimplement -

61 canRead() and read(). Then create a QImageIOPlugin that -

62 can create the handler. Finally, install your plugin, and -

63 QImageReader and QImageWriter will then automatically load the -

64 plugin, and start using it. -

65 -

66 \sa QImageIOPlugin, QImageReader, QImageWriter -

67 */ -

68 -

69 /*! \enum QImageIOHandler::ImageOption -

70 -

71 This enum describes the different options supported by -

72 QImageIOHandler. Some options are used to query an image for -

73 properties, and others are used to toggle the way in which an -

74 image should be written. -

75 -

76 \value Size The original size of an image. A handler that supports -

77 this option is expected to read the size of the image from the -

78 image metadata, and return this size from option() as a QSize. -

79 -

80 \value ClipRect The clip rect, or ROI (Region Of Interest). A -

81 handler that supports this option is expected to only read the -

82 provided QRect area from the original image in read(), before any -

83 other transformation is applied. -

84 -

85 \value ScaledSize The scaled size of the image. A handler that -

86 supports this option is expected to scale the image to the -

87 provided size (a QSize), after applying any clip rect -

88 transformation (ClipRect). If the handler does not support this -

89 option, QImageReader will perform the scaling after the image has -

90 been read. -

91 -

92 \value ScaledClipRect The scaled clip rect (or ROI, Region Of -

93 Interest) of the image. A handler that supports this option is -

94 expected to apply the provided clip rect (a QRect), after applying -

95 any scaling (ScaleSize) or regular clipping (ClipRect). If the -

96 handler does not support this option, QImageReader will apply the -

97 scaled clip rect after the image has been read. -

98 -

99 \value Description The image description. Some image formats, -

100 such as GIF and PNG, allow embedding of text -

101 or comments into the image data (e.g., for storing copyright -

102 information). It's common that the text is stored in key-value -

103 pairs, but some formats store all text in one continuous block. -

104 QImageIOHandler returns the text as one -

105 QString, where keys and values are separated by a ':', and -

106 keys-value pairs are separated by two newlines (\\n\\n). For example, -

107 "Title: Sunset\\n\\nAuthor: Jim Smith\\nSarah Jones\\n\\n". Formats that -

108 store text in a single block can use "Description" as the key. -

109 -

110 \value CompressionRatio The compression ratio of the image data. A -

111 handler that supports this option is expected to set its -

112 compression rate depending on the value of this option (an int) -

113 when writing. -

114 -

115 \value Gamma The gamma level of the image. A handler that supports -

116 this option is expected to set the image gamma level depending on -

117 the value of this option (a float) when writing. -

118 -

119 \value Quality The quality level of the image. A handler that -

120 supports this option is expected to set the image quality level -

121 depending on the value of this option (an int) when writing. -

122 -

123 \value Name The name of the image. A handler that supports this -

124 option is expected to read the name from the image metadata and -

125 return this as a QString, or when writing an image it is expected -

126 to store the name in the image metadata. -

127 -

128 \value SubType The subtype of the image. A handler that supports -

129 this option can use the subtype value to help when reading and -

130 writing images. For example, a PPM handler may have a subtype -

131 value of "ppm" or "ppmraw". -

132 -

133 \value IncrementalReading A handler that supports this option is -

134 expected to read the image in several passes, as if it was an -

135 animation. QImageReader will treat the image as an animation. -

136 -

137 \value Endianness The endianness of the image. Certain image -

138 formats can be stored as BigEndian or LittleEndian. A handler that -

139 supports Endianness uses the value of this option to determine how -

140 the image should be stored. -

141 -

142 \value Animation Image formats that support animation return -

143 true for this value in supportsOption(); otherwise, false is returned. -

144 -

145 \value BackgroundColor Certain image formats allow the -

146 background color to be specified. A handler that supports -

147 BackgroundColor initializes the background color to this option -

148 (a QColor) when reading an image. -

149 -

150 \value ImageFormat The image's data format returned by the handler. -

151 This can be any of the formats listed in QImage::Format. -

152 -

153 \value SupportedSubTypes Image formats that support different saving -

154 variants should return a list of supported variant names -

155 (QList<QByteArray>) in this option. -

156 -

157 \value OptimizedWrite. A handler which supports this option -

158 is expected to turn on optimization flags when writing. -

159 -

160 \value ProgressiveScanWrite. A handler which supports -

161 this option is expected to write the image as a progressive scan image. -

162 -

163 \value ImageTransformation. A handler which supports this option can read -

164 the transformation metadata of an image. A handler that supports this option -

165 should not apply the transformation itself. -

166 -

167 \value TransformedByDefault. A handler that reports support for this feature -

168 will have image transformation metadata applied by default on read. -

169 */ -

170 -

171 /*! \enum QImageIOHandler::Transformation -

172 \since 5.5 -

173 -

174 This enum describes the different transformations or orientations -

175 supported by some image formats, usually through EXIF. -

176 -

177 \value TransformationNone No transformation should be applied. -

178 -

179 \value TransformationMirror Mirror the image horizontally. -

180 -

181 \value TransformationFlip Mirror the image vertically. -

182 -

183 \value TransformationRotate180 Rotate the image 180 degrees. -

184 This is the same as mirroring it both horizontally and vertically. -

185 -

186 \value TransformationRotate90 Rotate the image 90 degrees. -

187 -

188 \value TransformationMirrorAndRotate90 Mirror the image horizontally -

189 and then rotate it 90 degrees. -

190 -

191 \value TransformationFlipAndRotate90 Mirror the image vertically -

192 and then rotate it 90 degrees. -

193 -

194 \value TransformationRotate270 Rotate the image 270 degrees. -

195 This is the same as mirroring it both horizontally, vertically and -

196 then rotating it 90 degrees. -

197 -

198 \sa QImageReader::transformation(), QImageReader::setAutoTransform(), QImageWriter::setTransformation() -

199 */ -

200 -

201 /*! -

202 \class QImageIOPlugin -

203 \inmodule QtGui -

204 \brief The QImageIOPlugin class defines an interface for writing -

205 an image format plugin. -

206 \reentrant -

207 -

208 \ingroup plugins -

209 -

210 QImageIOPlugin is a factory for creating QImageIOHandler objects, -

211 which are used internally by QImageReader and QImageWriter to add -

212 support for different image formats to Qt. -

213 -

214 Writing an image I/O plugin is achieved by subclassing this -

215 base class, reimplementing the pure virtual functions capabilities() -

216 and create(), and exporting the class with the -

217 Q_PLUGIN_METADATA() macro. See \l{How to Create Qt Plugins} for details. -

218 -

219 An image format plugin can support three capabilities: reading (\l -

220 CanRead), writing (\l CanWrite) and \e incremental reading (\l -

221 CanReadIncremental). Reimplement capabilities() in you subclass to -

222 expose the capabilities of your image format. -

223 -

224 create() should create an instance of your QImageIOHandler -

225 subclass, with the provided device and format properly set, and -

226 return this handler. -

227 -

228 The json metadata file for the plugin needs to contain information -

229 about the image formats the plugins supports, together with the -

230 corresponding MIME types (one for each format). For a jpeg plugin, this -

231 could, for example, look as follows: -

232 -

233 \code -

234 { -

235 "Keys": [ "jpg", "jpeg" ], -

236 "MimeTypes": [ "image/jpeg", "image/jpeg" ] -

237 } -

238 \endcode -

239 -

240 Different plugins can support different capabilities. For example, -

241 you may have one plugin that supports reading the GIF format, and -

242 another that supports writing. Qt will select the correct plugin -

243 for the job, depending on the return value of capabilities(). If -

244 several plugins support the same capability, Qt will select one -

245 arbitrarily. -

246 -

247 \sa QImageIOHandler, {How to Create Qt Plugins} -

248 */ -

249 -

250 /*! -

251 \enum QImageIOPlugin::Capability -

252 -

253 This enum describes the capabilities of a QImageIOPlugin. -

254 -

255 \value CanRead The plugin can read images. -

256 \value CanWrite The plugin can write images. -

257 \value CanReadIncremental The plugin can read images incrementally. -

258 */ -

259 -

260 #include "qimageiohandler.h" -

261 -

262 #include <qbytearray.h> -

263 #include <qimage.h> -

264 #include <qvariant.h> -

265 -

266 QT_BEGIN_NAMESPACE -

267 -

268 class QIODevice; -

269 -

270 class QImageIOHandlerPrivate -

271 { -

272 Q_DECLARE_PUBLIC(QImageIOHandler) -

273 public: -

274 QImageIOHandlerPrivate(QImageIOHandler *q); -

275 virtual ~QImageIOHandlerPrivate(); -

276 -

277 QIODevice *device; -

278 mutable QByteArray format; -

279 -

280 QImageIOHandler *q_ptr; -

281 }; -

282 -

283 QImageIOHandlerPrivate::QImageIOHandlerPrivate(QImageIOHandler *q) -

284 { -

285 device = 0; -

286 q_ptr = q; -

287

}

never executed: end of block

288 -

289 QImageIOHandlerPrivate::~QImageIOHandlerPrivate() -

290 { -

291 } -

292 -

293 /*! -

294 Constructs a QImageIOHandler object. -

295 */ -

296 QImageIOHandler::QImageIOHandler() -

297 : d_ptr(new QImageIOHandlerPrivate(this)) -

298 { -

299

}

never executed: end of block

300 -

301 /*! \internal -

302 -

303 Constructs a QImageIOHandler object, using the private member \a -

304 dd. -

305 */ -

306 QImageIOHandler::QImageIOHandler(QImageIOHandlerPrivate &dd) -

307 : d_ptr(&dd) -

308 { -

309

}

never executed: end of block

310 -

311 /*! -

312 Destructs the QImageIOHandler object. -

313 */ -

314 QImageIOHandler::~QImageIOHandler() -

315 { -

316 } -

317 -

318 /*! -

319 Sets the device of the QImageIOHandler to \a device. The image -

320 handler will use this device when reading and writing images. -

321 -

322 The device can only be set once and must be set before calling -

323 canRead(), read(), write(), etc. If you need to read multiple -

324 files, construct multiple instances of the appropriate -

325 QImageIOHandler subclass. -

326 -

327 \sa device() -

328 */ -

329 void QImageIOHandler::setDevice(QIODevice *device) -

330 { -

331 Q_D(QImageIOHandler); -

332 d->device = device; -

333

}

never executed: end of block

334 -

335 /*! -

336 Returns the device currently assigned to the QImageIOHandler. If -

337 not device has been assigned, 0 is returned. -

338 */ -

339 QIODevice *QImageIOHandler::device() const -

340 { -

341 Q_D(const QImageIOHandler); -

342

return d->device;

never executed: return d->device;

343 } -

344 -

345 /*! -

346 Sets the format of the QImageIOHandler to \a format. The format is -

347 most useful for handlers that support multiple image formats. -

348 -

349 \sa format() -

350 */ -

351 void QImageIOHandler::setFormat(const QByteArray &format) -

352 { -

353 Q_D(QImageIOHandler); -

354 d->format = format; -

355

}

never executed: end of block

356 -

357 /*! -

358 Sets the format of the QImageIOHandler to \a format. The format is -

359 most useful for handlers that support multiple image formats. -

360 -

361 This function is declared const so that it can be called from canRead(). -

362 -

363 \sa format() -

364 */ -

365 void QImageIOHandler::setFormat(const QByteArray &format) const -

366 { -

367 Q_D(const QImageIOHandler); -

368 d->format = format; -

369

}

never executed: end of block

370 -

371 /*! -

372 Returns the format that is currently assigned to -

373 QImageIOHandler. If no format has been assigned, an empty string -

374 is returned. -

375 -

376 \sa setFormat() -

377 */ -

378 QByteArray QImageIOHandler::format() const -

379 { -

380 Q_D(const QImageIOHandler); -

381

return d->format;

never executed: return d->format;

382 } -

383 -

384 /*! -

385 \fn bool QImageIOHandler::read(QImage *image) -

386 -

387 Read an image from the device, and stores it in \a image. -

388 Returns \c true if the image is successfully read; otherwise returns -

389 false. -

390 -

391 For image formats that support incremental loading, and for animation -

392 formats, the image handler can assume that \a image points to the -

393 previous frame. -

394 -

395 \sa canRead() -

396 */ -

397 -

398 /*! -

399 \fn bool QImageIOHandler::canRead() const -

400 -

401 Returns \c true if an image can be read from the device (i.e., the -

402 image format is supported, the device can be read from and the -

403 initial header information suggests that the image can be read); -

404 otherwise returns \c false. -

405 -

406 When reimplementing canRead(), make sure that the I/O device -

407 (device()) is left in its original state (e.g., by using peek() -

408 rather than read()). -

409 -

410 \sa read(), QIODevice::peek() -

411 */ -

412 -

413 /*! -

414 \obsolete -

415 -

416 Use format() instead. -

417 */ -

418 -

419 QByteArray QImageIOHandler::name() const -

420 { -

421

return format();

never executed: return format();

422 } -

423 -

424 /*! -

425 Writes the image \a image to the assigned device. Returns \c true on -

426 success; otherwise returns \c false. -

427 -

428 The default implementation does nothing, and simply returns \c false. -

429 */ -

430 bool QImageIOHandler::write(const QImage &image) -

431 { -

432 Q_UNUSED(image); -

433

return false;

never executed: return false;

434 } -

435 -

436 /*! -

437 Sets the option \a option with the value \a value. -

438 -

439 \sa option(), ImageOption -

440 */ -

441 void QImageIOHandler::setOption(ImageOption option, const QVariant &value) -

442 { -

443 Q_UNUSED(option); -

444 Q_UNUSED(value); -

445

}

never executed: end of block

446 -

447 /*! -

448 Returns the value assigned to \a option as a QVariant. The type of -

449 the value depends on the option. For example, option(Size) returns -

450 a QSize variant. -

451 -

452 \sa setOption(), supportsOption() -

453 */ -

454 QVariant QImageIOHandler::option(ImageOption option) const -

455 { -

456 Q_UNUSED(option); -

457

return QVariant();

never executed: return QVariant();

458 } -

459 -

460 /*! -

461 Returns \c true if the QImageIOHandler supports the option \a option; -

462 otherwise returns \c false. For example, if the QImageIOHandler -

463 supports the \l Size option, supportsOption(Size) must return -

464 true. -

465 -

466 \sa setOption(), option() -

467 */ -

468 bool QImageIOHandler::supportsOption(ImageOption option) const -

469 { -

470 Q_UNUSED(option); -

471

return false;

never executed: return false;

472 } -

473 -

474 /*! -

475 For image formats that support animation, this function returns -

476 the sequence number of the current image in the animation. If -

477 this function is called before any image is read(), -1 is -

478 returned. The number of the first image in the sequence is 0. -

479 -

480 If the image format does not support animation, 0 is returned. -

481 -

482 \sa read() -

483 */ -

484 int QImageIOHandler::currentImageNumber() const -

485 { -

486

return 0;

never executed: return 0;

487 } -

488 -

489 /*! -

490 Returns the rect of the current image. If no rect is defined for the -

491 image, and empty QRect() is returned. -

492 -

493 This function is useful for animations, where only parts of the frame -

494 may be updated at a time. -

495 */ -

496 QRect QImageIOHandler::currentImageRect() const -

497 { -

498

return QRect();

never executed: return QRect();

499 } -

500 -

501 /*! -

502 For image formats that support animation, this function returns -

503 the number of images in the animation. If the image format does -

504 not support animation, or if it is unable to determine the number -

505 of images, 0 is returned. -

506 -

507 The default implementation returns 1 if canRead() returns \c true; -

508 otherwise 0 is returned. -

509 */ -

510 int QImageIOHandler::imageCount() const -

511 { -

512

return canRead() ? 1 : 0;

never executed: return canRead() ? 1 : 0;

canRead()	Description
TRUE	never evaluated
FALSE	never evaluated

513 } -

514 -

515 /*! -

516 For image formats that support animation, this function jumps to the -

517 next image. -

518 -

519 The default implementation does nothing, and returns \c false. -

520 */ -

521 bool QImageIOHandler::jumpToNextImage() -

522 { -

523

return false;

never executed: return false;

524 } -

525 -

526 /*! -

527 For image formats that support animation, this function jumps to the image -

528 whose sequence number is \a imageNumber. The next call to read() will -

529 attempt to read this image. -

530 -

531 The default implementation does nothing, and returns \c false. -

532 */ -

533 bool QImageIOHandler::jumpToImage(int imageNumber) -

534 { -

535 Q_UNUSED(imageNumber); -

536

return false;

never executed: return false;

537 } -

538 -

539 /*! -

540 For image formats that support animation, this function returns -

541 the number of times the animation should loop. If the image format -

542 does not support animation, 0 is returned. -

543 */ -

544 int QImageIOHandler::loopCount() const -

545 { -

546

return 0;

never executed: return 0;

547 } -

548 -

549 /*! -

550 For image formats that support animation, this function returns -

551 the number of milliseconds to wait until reading the next -

552 image. If the image format does not support animation, 0 is -

553 returned. -

554 */ -

555 int QImageIOHandler::nextImageDelay() const -

556 { -

557

return 0;

never executed: return 0;

558 } -

559 -

560 #ifndef QT_NO_IMAGEFORMATPLUGIN -

561 -

562 /*! -

563 Constructs an image plugin with the given \a parent. This is -

564 invoked automatically by the moc generated code that exports the plugin. -

565 */ -

566 QImageIOPlugin::QImageIOPlugin(QObject *parent) -

567 : QObject(parent) -

568 { -

569

}

never executed: end of block

570 -

571 /*! -

572 Destroys the picture format plugin. -

573 -

574 You never have to call this explicitly. Qt destroys a plugin -

575 automatically when it is no longer used. -

576 */ -

577 QImageIOPlugin::~QImageIOPlugin() -

578 { -

579 } -

580 -

581 /*! \fn QImageIOPlugin::capabilities(QIODevice *device, const QByteArray &format) const -

582 -

583 Returns the capabilities of the plugin, based on the data in \a -

584 device and the format \a format. If \a device is \c 0, it should -

585 simply report whether the format can be read or written. Otherwise, -

586 it should attempt to determine whether the given format (or any -

587 format supported by the plugin if \a format is empty) can be read -

588 from or written to \a device. It should do this without changing -

589 the state of \a device (typically by using QIODevice::peek()). -

590 -

591 For example, if the QImageIOPlugin supports the BMP format, \a format -

592 is either empty or \c "bmp", and the data in the device starts with the -

593 characters \c "BM", this function should return \l CanRead. If \a format -

594 is \c "bmp", \a device is \c 0 and the handler supports both reading and -

595 writing, this function should return \l CanRead | \l CanWrite. -

596 -

597 Format names are always given in lower case. -

598 */ -

599 -

600 /*! -

601 \fn QImageIOHandler *QImageIOPlugin::create(QIODevice *device, const QByteArray &format) const -

602 -

603 Creates and returns a QImageIOHandler subclass, with \a device -

604 and \a format set. The \a format must come from the values listed -

605 in the \c "Keys" entry in the plugin metadata, or be empty. If it is -

606 empty, the data in \a device must have been recognized by the -

607 capabilities() method (with a likewise empty format). -

608 -

609 Format names are always given in lower case. -

610 */ -

611 -

612 #endif // QT_NO_IMAGEFORMATPLUGIN -

613 -

614 QT_END_NAMESPACE -

Source code

Switch to Preprocessed file

Generated by Squish Coco Non-Commercial 4.3.0-BETA-master-30-08-2018-4cb69e9