~ubuntu-branches/ubuntu/breezy/gimp/breezy : revision 1

1

<?xml version="1.0" encoding="UTF-8" ?>

2

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

3

"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

4

5

6

7

<refentrytitle>GimpMatrix</refentrytitle>

8

9

<refmiscinfo>LIBGIMPMATH Library</refmiscinfo>

10

</refmeta>

11

12

13

<refname>GimpMatrix</refname><refpurpose>Utilities to set up and manipulate 3x3 transformation matrices.</refpurpose>

14

</refnamediv>

15

16

<refsynopsisdiv><title>Synopsis</title>

17

18

19

20

21

22

struct <link linkend="GimpMatrix2">GimpMatrix2</link>;

23

struct <link linkend="GimpMatrix3">GimpMatrix3</link>;

24

struct <link linkend="GimpMatrix4">GimpMatrix4</link>;

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

</synopsis>

65

</refsynopsisdiv>

66

67

68

69

70

71

72

73

74

75

76

<title>Description</title>

77

<para>

78

When doing image manipulation you will often need 3x3 transformation

79

matrices that define translation, rotation, scaling, shearing and

80

arbitrary perspective transformations using a 3x3 matrix. Here you'll

81

find a set of utility functions to set up those matrices and to perform

82

basic matrix manipulations and tests.

83

</para>

84

</refsect1>

85

86

87

<title>Details</title>

88

89

<title><anchor id="GimpMatrix2"/>struct GimpMatrix2</title>

90

<indexterm><primary>GimpMatrix2</primary></indexterm><programlisting>struct GimpMatrix2 {

91

92

gdouble coeff[2][2];

93

};

94

</programlisting>

95

<para>

96

A two by two matrix.

97

</para></refsect2>

98

99

<title><anchor id="GimpMatrix3"/>struct GimpMatrix3</title>

100

<indexterm><primary>GimpMatrix3</primary></indexterm><programlisting>struct GimpMatrix3 {

101

102

gdouble coeff[3][3];

103

};

104

</programlisting>

105

<para>

106

A three by three matrix.

107

</para></refsect2>

108

109

<title><anchor id="GimpMatrix4"/>struct GimpMatrix4</title>

110

<indexterm><primary>GimpMatrix4</primary></indexterm><programlisting>struct GimpMatrix4 {

111

112

gdouble coeff[4][4];

113

};

114

</programlisting>

115

<para>

116

A four by four matrix.

117

</para></refsect2>

118

119

<title><anchor id="gimp-matrix2-identity"/>gimp_matrix2_identity ()</title>

120

<indexterm><primary>gimp_matrix2_identity</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix2_identity (<link linkend="GimpMatrix2">GimpMatrix2</link> *matrix);</programlisting>

121

<para>

122

Sets the matrix to the identity matrix.</para>

123

<para>

124

125

</para><variablelist role="params">

126

<varlistentry><term><parameter>matrix</parameter> :</term>

127

<listitem><simpara> A matrix.

128

</simpara></listitem></varlistentry>

129

</variablelist></refsect2>

130

131

<title><anchor id="gimp-matrix2-mult"/>gimp_matrix2_mult ()</title>

132

<indexterm><primary>gimp_matrix2_mult</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix2_mult (const <link linkend="GimpMatrix2">GimpMatrix2</link> *matrix1,

133

134

<para>

135

Multiplies two matrices and puts the result into the second one.</para>

136

<para>

137

138

</para><variablelist role="params">

139

<varlistentry><term><parameter>matrix1</parameter> :</term>

140

<listitem><simpara> The first input matrix.

141

</simpara></listitem></varlistentry>

142

<varlistentry><term><parameter>matrix2</parameter> :</term>

143

<listitem><simpara> The second input matrix which will be overwritten by the result.

144

</simpara></listitem></varlistentry>

145

</variablelist></refsect2>

146

147

<title><anchor id="gimp-matrix3-identity"/>gimp_matrix3_identity ()</title>

148

<indexterm><primary>gimp_matrix3_identity</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix3_identity (<link linkend="GimpMatrix3">GimpMatrix3</link> *matrix);</programlisting>

149

<para>

150

Sets the matrix to the identity matrix.</para>

151

<para>

152

153

</para><variablelist role="params">

154

<varlistentry><term><parameter>matrix</parameter> :</term>

155

<listitem><simpara> A matrix.

156

</simpara></listitem></varlistentry>

157

</variablelist></refsect2>

158

159

<title><anchor id="gimp-matrix3-mult"/>gimp_matrix3_mult ()</title>

160

<indexterm><primary>gimp_matrix3_mult</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix3_mult (const <link linkend="GimpMatrix3">GimpMatrix3</link> *matrix1,

161

162

<para>

163

Multiplies two matrices and puts the result into the second one.</para>

164

<para>

165

166

</para><variablelist role="params">

167

<varlistentry><term><parameter>matrix1</parameter> :</term>

168

<listitem><simpara> The first input matrix.

169

</simpara></listitem></varlistentry>

170

<varlistentry><term><parameter>matrix2</parameter> :</term>

171

<listitem><simpara> The second input matrix which will be overwritten by the result.

172

</simpara></listitem></varlistentry>

173

</variablelist></refsect2>

174

175

<title><anchor id="gimp-matrix3-translate"/>gimp_matrix3_translate ()</title>

176

<indexterm><primary>gimp_matrix3_translate</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix3_translate (<link linkend="GimpMatrix3">GimpMatrix3</link> *matrix,

177

178

179

<para>

180

Translates the matrix by x and y.</para>

181

<para>

182

183

</para><variablelist role="params">

184

<varlistentry><term><parameter>matrix</parameter> :</term>

185

<listitem><simpara> The matrix that is to be translated.

186

</simpara></listitem></varlistentry>

187

188

<listitem><simpara> Translation in X direction.

189

</simpara></listitem></varlistentry>

190

191

<listitem><simpara> Translation in Y direction.

192

</simpara></listitem></varlistentry>

193

</variablelist></refsect2>

194

195

<title><anchor id="gimp-matrix3-scale"/>gimp_matrix3_scale ()</title>

196

<indexterm><primary>gimp_matrix3_scale</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix3_scale (<link linkend="GimpMatrix3">GimpMatrix3</link> *matrix,

197

198

199

<para>

200

Scales the matrix by x and y</para>

201

<para>

202

203

</para><variablelist role="params">

204

<varlistentry><term><parameter>matrix</parameter> :</term>

205

<listitem><simpara> The matrix that is to be scaled.

206

</simpara></listitem></varlistentry>

207

208

<listitem><simpara> X scale factor.

209

</simpara></listitem></varlistentry>

210

211

<listitem><simpara> Y scale factor.

212

</simpara></listitem></varlistentry>

213

</variablelist></refsect2>

214

215

<title><anchor id="gimp-matrix3-rotate"/>gimp_matrix3_rotate ()</title>

216

<indexterm><primary>gimp_matrix3_rotate</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix3_rotate (<link linkend="GimpMatrix3">GimpMatrix3</link> *matrix,

217

218

<para>

219

Rotates the matrix by theta degrees.</para>

220

<para>

221

222

</para><variablelist role="params">

223

<varlistentry><term><parameter>matrix</parameter> :</term>

224

<listitem><simpara> The matrix that is to be rotated.

225

</simpara></listitem></varlistentry>

226

<varlistentry><term><parameter>theta</parameter> :</term>

227

<listitem><simpara> The angle of rotation (in radians).

228

</simpara></listitem></varlistentry>

229

</variablelist></refsect2>

230

231

<title><anchor id="gimp-matrix3-xshear"/>gimp_matrix3_xshear ()</title>

232

<indexterm><primary>gimp_matrix3_xshear</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix3_xshear (<link linkend="GimpMatrix3">GimpMatrix3</link> *matrix,

233

234

<para>

235

Shears the matrix in the X direction.</para>

236

<para>

237

238

</para><variablelist role="params">

239

<varlistentry><term><parameter>matrix</parameter> :</term>

240

<listitem><simpara> The matrix that is to be sheared.

241

</simpara></listitem></varlistentry>

242

<varlistentry><term><parameter>amount</parameter> :</term>

243

<listitem><simpara> X shear amount.

244

</simpara></listitem></varlistentry>

245

</variablelist></refsect2>

246

247

<title><anchor id="gimp-matrix3-yshear"/>gimp_matrix3_yshear ()</title>

248

<indexterm><primary>gimp_matrix3_yshear</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix3_yshear (<link linkend="GimpMatrix3">GimpMatrix3</link> *matrix,

249

250

<para>

251

Shears the matrix in the Y direction.</para>

252

<para>

253

254

</para><variablelist role="params">

255

<varlistentry><term><parameter>matrix</parameter> :</term>

256

<listitem><simpara> The matrix that is to be sheared.

257

</simpara></listitem></varlistentry>

258

<varlistentry><term><parameter>amount</parameter> :</term>

259

<listitem><simpara> Y shear amount.

260

</simpara></listitem></varlistentry>

261

</variablelist></refsect2>

262

263

<title><anchor id="gimp-matrix3-affine"/>gimp_matrix3_affine ()</title>

264

<indexterm><primary>gimp_matrix3_affine</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix3_affine (<link linkend="GimpMatrix3">GimpMatrix3</link> *matrix,

265

266

267

268

269

270

271

<para>

272

Applies the affine transformation given by six values to <parameter>matrix</parameter>.

273

The six values form define an affine transformation matrix as

274

illustrated below:

275

</para>

276

<para>

277

( a c e )

278

( b d f )

279

( 0 0 1 )</para>

280

<para>

281

282

</para><variablelist role="params">

283

<varlistentry><term><parameter>matrix</parameter> :</term>

284

<listitem><simpara> The input matrix.

285

</simpara></listitem></varlistentry>

286

287

288

</simpara></listitem></varlistentry>

289

290

291

</simpara></listitem></varlistentry>

292

293

294

</simpara></listitem></varlistentry>

295

296

297

</simpara></listitem></varlistentry>

298

299

300

</simpara></listitem></varlistentry>

301

302

303

</simpara></listitem></varlistentry>

304

</variablelist></refsect2>

305

306

<title><anchor id="gimp-matrix3-transform-point"/>gimp_matrix3_transform_point ()</title>

307

<indexterm><primary>gimp_matrix3_transform_point</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix3_transform_point (const <link linkend="GimpMatrix3">GimpMatrix3</link> *matrix,

308

309

310

311

312

<para>

313

Transforms a point in 2D as specified by the transformation matrix.</para>

314

<para>

315

316

</para><variablelist role="params">

317

<varlistentry><term><parameter>matrix</parameter> :</term>

318

<listitem><simpara> The transformation matrix.

319

</simpara></listitem></varlistentry>

320

321

<listitem><simpara> The source X coordinate.

322

</simpara></listitem></varlistentry>

323

324

<listitem><simpara> The source Y coordinate.

325

</simpara></listitem></varlistentry>

326

327

<listitem><simpara> The transformed X coordinate.

328

</simpara></listitem></varlistentry>

329

330

<listitem><simpara> The transformed Y coordinate.

331

</simpara></listitem></varlistentry>

332

</variablelist></refsect2>

333

334

<title><anchor id="gimp-matrix3-determinant"/>gimp_matrix3_determinant ()</title>

335

<indexterm><primary>gimp_matrix3_determinant</primary></indexterm><programlisting><link linkend="gdouble">gdouble</link> gimp_matrix3_determinant (const <link linkend="GimpMatrix3">GimpMatrix3</link> *matrix);</programlisting>

336

<para>

337

Calculates the determinant of the given matrix.</para>

338

<para>

339

340

</para><variablelist role="params">

341

<varlistentry><term><parameter>matrix</parameter> :</term>

342

<listitem><simpara> The input matrix.

343

</simpara></listitem></varlistentry>

344

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The determinant.

345

</simpara></listitem></varlistentry>

346

</variablelist></refsect2>

347

348

<title><anchor id="gimp-matrix3-invert"/>gimp_matrix3_invert ()</title>

349

<indexterm><primary>gimp_matrix3_invert</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix3_invert (<link linkend="GimpMatrix3">GimpMatrix3</link> *matrix);</programlisting>

350

<para>

351

Inverts the given matrix.</para>

352

<para>

353

354

</para><variablelist role="params">

355

<varlistentry><term><parameter>matrix</parameter> :</term>

356

<listitem><simpara> The matrix that is to be inverted.

357

</simpara></listitem></varlistentry>

358

</variablelist></refsect2>

359

360

<title><anchor id="gimp-matrix3-is-diagonal"/>gimp_matrix3_is_diagonal ()</title>

361

<indexterm><primary>gimp_matrix3_is_diagonal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gimp_matrix3_is_diagonal (const <link linkend="GimpMatrix3">GimpMatrix3</link> *matrix);</programlisting>

362

<para>

363

Checks if the given matrix is diagonal.</para>

364

<para>

365

366

</para><variablelist role="params">

367

<varlistentry><term><parameter>matrix</parameter> :</term>

368

<listitem><simpara> The matrix that is to be tested.

369

</simpara></listitem></varlistentry>

370

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if the matrix is diagonal.

371

</simpara></listitem></varlistentry>

372

</variablelist></refsect2>

373

374

<title><anchor id="gimp-matrix3-is-identity"/>gimp_matrix3_is_identity ()</title>

375

<indexterm><primary>gimp_matrix3_is_identity</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gimp_matrix3_is_identity (const <link linkend="GimpMatrix3">GimpMatrix3</link> *matrix);</programlisting>

376

<para>

377

Checks if the given matrix is the identity matrix.</para>

378

<para>

379

380

</para><variablelist role="params">

381

<varlistentry><term><parameter>matrix</parameter> :</term>

382

<listitem><simpara> The matrix that is to be tested.

383

</simpara></listitem></varlistentry>

384

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if the matrix is the identity matrix.

385

</simpara></listitem></varlistentry>

386

</variablelist></refsect2>

387

388

<title><anchor id="gimp-matrix3-is-simple"/>gimp_matrix3_is_simple ()</title>

389

<indexterm><primary>gimp_matrix3_is_simple</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gimp_matrix3_is_simple (const <link linkend="GimpMatrix3">GimpMatrix3</link> *matrix);</programlisting>

390

<para>

391

Checks if we'll need to interpolate when applying this matrix as

392

a transformation.</para>

393

<para>

394

395

</para><variablelist role="params">

396

<varlistentry><term><parameter>matrix</parameter> :</term>

397

<listitem><simpara> The matrix that is to be tested.

398

</simpara></listitem></varlistentry>

399

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if all entries of the upper left 2x2 matrix are either

400

0 or 1

401

</simpara></listitem></varlistentry>

402

</variablelist></refsect2>

403

404

<title><anchor id="gimp-matrix4-to-deg"/>gimp_matrix4_to_deg ()</title>

405

<indexterm><primary>gimp_matrix4_to_deg</primary></indexterm><programlisting><link linkend="void">void</link> gimp_matrix4_to_deg (const <link linkend="GimpMatrix4">GimpMatrix4</link> *matrix,

406

407

408

409

<para>

410

</para>

411

<para>

412

413

</para><variablelist role="params">

414

<varlistentry><term><parameter>matrix</parameter> :</term>

415

416

</simpara></listitem></varlistentry>

417

418

419

</simpara></listitem></varlistentry>

420

421

422

</simpara></listitem></varlistentry>

423

424

425

</simpara></listitem></varlistentry>

426

</variablelist></refsect2>

427

428

</refsect1>

429

430

431

432

433

434

<para>

435

436

</para>

437

<para>

438

439

</para>

440

<para>

441

442

</para>

443

</refsect1>

444

445

</refentry>