Coverage Report

Created: 2026-11-20 06:19

next uncovered line (L), next uncovered region (R), next uncovered branch (B)
/src/ogre/OgreMain/include/OgreGpuProgramParams.h
Line
Count
Source
1
/*
2
  -----------------------------------------------------------------------------
3
  This source file is part of OGRE
4
  (Object-oriented Graphics Rendering Engine)
5
  For the latest info, see http://www.ogre3d.org
6
7
Copyright (c) 2000-2014 Torus Knot Software Ltd
8
9
  Permission is hereby granted, free of charge, to any person obtaining a copy
10
  of this software and associated documentation files (the "Software"), to deal
11
  in the Software without restriction, including without limitation the rights
12
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13
  copies of the Software, and to permit persons to whom the Software is
14
  furnished to do so, subject to the following conditions:
15
16
  The above copyright notice and this permission notice shall be included in
17
  all copies or substantial portions of the Software.
18
19
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25
  THE SOFTWARE.
26
  -----------------------------------------------------------------------------
27
*/
28
#ifndef __GpuProgramParams_H_
29
#define __GpuProgramParams_H_
30
31
#include <limits>
32
33
// Precompiler options
34
#include "OgrePrerequisites.h"
35
#include "OgreSharedPtr.h"
36
#include "OgreSerializer.h"
37
#include "OgreAny.h"
38
#include "Threading/OgreThreadHeaders.h"
39
#include "OgreHeaderPrefix.h"
40
41
namespace Ogre {
42
    struct TransformBaseReal;
43
    template <typename T> class ConstMapIterator;
44
45
    /** \addtogroup Core
46
     *  @{
47
     */
48
    /** \addtogroup Materials
49
     *  @{
50
     */
51
52
    enum BaseConstantType
53
    {
54
        BCT_FLOAT = 0,
55
        BCT_INT = 0x10,
56
        BCT_DOUBLE = 0x20,
57
        BCT_UINT = 0x30,
58
        BCT_BOOL = 0x40,
59
        BCT_SAMPLER = 0x50,
60
        BCT_SPECIALIZATION = 0x60, //!< shader specialisation constant
61
        BCT_UNKNOWN = 0x70
62
    };
63
64
    /** Enumeration of the types of constant we may encounter in programs.
65
        @note Low-level programs, by definition, will always use either
66
        float4 or int4 constant types since that is the fundamental underlying
67
        type in assembler.
68
    */
69
    enum GpuConstantType
70
    {
71
        GCT_FLOAT1 = BCT_FLOAT + 1,
72
        GCT_FLOAT2 = BCT_FLOAT + 2,
73
        GCT_FLOAT3 = BCT_FLOAT + 3,
74
        GCT_FLOAT4 = BCT_FLOAT + 4,
75
        GCT_SAMPLER1D = BCT_SAMPLER + 1,
76
        GCT_SAMPLER2D = BCT_SAMPLER + 2,
77
        GCT_SAMPLER3D = BCT_SAMPLER + 3,
78
        GCT_SAMPLERCUBE = BCT_SAMPLER + 4,
79
        GCT_SAMPLER1DSHADOW = BCT_SAMPLER + 6,
80
        GCT_SAMPLER2DSHADOW = BCT_SAMPLER + 7,
81
        GCT_SAMPLER2DARRAY = BCT_SAMPLER + 8,
82
        GCT_SAMPLER_EXTERNAL_OES = BCT_SAMPLER + 9,
83
        GCT_SAMPLER2DARRAYSHADOW = BCT_SAMPLER + 10,
84
        GCT_SAMPLERCUBESHADOW = BCT_SAMPLER + 11,
85
        GCT_MATRIX_2X2 = BCT_FLOAT + 5,
86
        GCT_MATRIX_2X3 = BCT_FLOAT + 6,
87
        GCT_MATRIX_2X4 = BCT_FLOAT + 7,
88
        GCT_MATRIX_3X2 = BCT_FLOAT + 8,
89
        GCT_MATRIX_3X3 = BCT_FLOAT + 9,
90
        GCT_MATRIX_3X4 = BCT_FLOAT + 10,
91
        GCT_MATRIX_4X2 = BCT_FLOAT + 11,
92
        GCT_MATRIX_4X3 = BCT_FLOAT + 12,
93
        GCT_MATRIX_4X4 = BCT_FLOAT + 13,
94
        GCT_INT1 = BCT_INT + 1,
95
        GCT_INT2 = BCT_INT + 2,
96
        GCT_INT3 = BCT_INT + 3,
97
        GCT_INT4 = BCT_INT + 4,
98
        GCT_SPECIALIZATION = BCT_SPECIALIZATION,
99
        GCT_DOUBLE1 = BCT_DOUBLE + 1,
100
        GCT_DOUBLE2 = BCT_DOUBLE + 2,
101
        GCT_DOUBLE3 = BCT_DOUBLE + 3,
102
        GCT_DOUBLE4 = BCT_DOUBLE + 4,
103
        GCT_MATRIX_DOUBLE_2X2 = BCT_DOUBLE + 5,
104
        GCT_MATRIX_DOUBLE_2X3 = BCT_DOUBLE + 6,
105
        GCT_MATRIX_DOUBLE_2X4 = BCT_DOUBLE + 7,
106
        GCT_MATRIX_DOUBLE_3X2 = BCT_DOUBLE + 8,
107
        GCT_MATRIX_DOUBLE_3X3 = BCT_DOUBLE + 9,
108
        GCT_MATRIX_DOUBLE_3X4 = BCT_DOUBLE + 10,
109
        GCT_MATRIX_DOUBLE_4X2 = BCT_DOUBLE + 11,
110
        GCT_MATRIX_DOUBLE_4X3 = BCT_DOUBLE + 12,
111
        GCT_MATRIX_DOUBLE_4X4 = BCT_DOUBLE + 13,
112
        GCT_UINT1 = BCT_UINT + 1,
113
        GCT_UINT2 = BCT_UINT + 2,
114
        GCT_UINT3 = BCT_UINT + 3,
115
        GCT_UINT4 = BCT_UINT + 4,
116
        GCT_BOOL1 = BCT_BOOL + 1,
117
        GCT_BOOL2 = BCT_BOOL + 2,
118
        GCT_BOOL3 = BCT_BOOL + 3,
119
        GCT_BOOL4 = BCT_BOOL + 4,
120
        GCT_UNKNOWN = BCT_UNKNOWN
121
    };
122
123
    /** The variability of a GPU parameter, as derived from auto-params targeting it.
124
        These values must be powers of two since they are used in masks.
125
    */
126
    enum GpuParamVariability : uint16
127
    {
128
        /// No variation except by manual setting - the default
129
        GPV_GLOBAL = 1,
130
        /// Varies per object (based on an auto param usually), but not per light setup
131
        GPV_PER_OBJECT = 2,
132
        /// Varies with light setup
133
        GPV_LIGHTS = 4,
134
        /// Varies with pass iteration number
135
        GPV_PASS_ITERATION_NUMBER = 8,
136
137
138
        /// Full mask (16-bit)
139
        GPV_ALL = 0xFFFF
140
    };
141
142
    /** Information about predefined program constants.
143
        @note Only available for high-level programs but is referenced generically
144
        by GpuProgramParameters.
145
    */
146
    struct _OgreExport GpuConstantDefinition
147
    {
148
        /// Physical byte offset in buffer
149
        size_t physicalIndex;
150
        /// Logical index - used to communicate this constant to the rendersystem
151
        size_t logicalIndex;
152
        /** Number of typed slots per element
153
            (some programs pack each array element to float4, some do not) */
154
        uint32 elementSize;
155
        /// Length of array
156
        uint32 arraySize;
157
        /// Data type
158
        GpuConstantType constType;
159
        /// How this parameter varies (bitwise combination of GpuProgramVariability)
160
        mutable uint16 variability;
161
162
        //TODO Should offset be added to list?
163
        // For instance, for GLSL atomic counters:
164
        // layout(binding = 1, offset = 10) atomic_uint atom_counter;
165
        // Binding goes in logicalIndex, but where does offset go?
166
        //size_t offset;
167
168
0
        bool isFloat() const { return isFloat(constType); }
169
0
        static bool isFloat(GpuConstantType c) { return getBaseType(c) == BCT_FLOAT; }
170
171
0
        bool isDouble() const { return isDouble(constType); }
172
0
        static bool isDouble(GpuConstantType c) { return getBaseType(c) == BCT_DOUBLE; }
173
174
0
        bool isInt() const { return isInt(constType); }
175
0
        static bool isInt(GpuConstantType c) { return getBaseType(c) == BCT_INT; }
176
177
0
        bool isUnsignedInt() const { return isUnsignedInt(constType); }
178
0
        static bool isUnsignedInt(GpuConstantType c) { return getBaseType(c) == BCT_UINT; }
179
180
0
        bool isBool() const { return isBool(constType); }
181
0
        static bool isBool(GpuConstantType c) { return getBaseType(c) == BCT_BOOL; }
182
183
0
        bool isSampler() const { return isSampler(constType); }
184
0
        static bool isSampler(GpuConstantType c) { return getBaseType(c) == BCT_SAMPLER; }
185
186
0
        bool isSpecialization() const { return isSpecialization(constType); }
187
0
        static bool isSpecialization(GpuConstantType c) { return getBaseType(c) == BCT_SPECIALIZATION; }
188
189
        static BaseConstantType getBaseType(GpuConstantType ctype)
190
0
        {
191
0
            return BaseConstantType(ctype / 0x10 * 0x10);
192
0
        }
193
194
        /** Get the number of elements of a given type, including whether to pad the
195
            elements into multiples of 4 (e.g. SM1 and D3D does, GLSL doesn't)
196
        */
197
        static uint32 getElementSize(GpuConstantType ctype, bool padToMultiplesOf4)
198
0
        {
199
0
            if (padToMultiplesOf4)
200
0
            {
201
0
                switch(ctype)
202
0
                {
203
0
                case GCT_FLOAT1:
204
0
                case GCT_INT1:
205
0
                case GCT_UINT1:
206
0
                case GCT_BOOL1:
207
0
                case GCT_SAMPLER1D:
208
0
                case GCT_SAMPLER2D:
209
0
                case GCT_SAMPLER2DARRAY:
210
0
                case GCT_SAMPLER3D:
211
0
                case GCT_SAMPLERCUBE:
212
0
                case GCT_SAMPLER1DSHADOW:
213
0
                case GCT_SAMPLER2DSHADOW:
214
0
                case GCT_FLOAT2:
215
0
                case GCT_INT2:
216
0
                case GCT_UINT2:
217
0
                case GCT_BOOL2:
218
0
                case GCT_FLOAT3:
219
0
                case GCT_INT3:
220
0
                case GCT_UINT3:
221
0
                case GCT_BOOL3:
222
0
                case GCT_FLOAT4:
223
0
                case GCT_INT4:
224
0
                case GCT_UINT4:
225
0
                case GCT_BOOL4:
226
0
                    return 4;
227
0
                case GCT_MATRIX_2X2:
228
0
                case GCT_MATRIX_2X3:
229
0
                case GCT_MATRIX_2X4:
230
0
                case GCT_DOUBLE1:
231
0
                case GCT_DOUBLE2:
232
0
                case GCT_DOUBLE3:
233
0
                case GCT_DOUBLE4:
234
0
                    return 8; // 2 float4s
235
0
                case GCT_MATRIX_3X2:
236
0
                case GCT_MATRIX_3X3:
237
0
                case GCT_MATRIX_3X4:
238
0
                    return 12; // 3 float4s
239
0
                case GCT_MATRIX_4X2:
240
0
                case GCT_MATRIX_4X3:
241
0
                case GCT_MATRIX_4X4:
242
0
                case GCT_MATRIX_DOUBLE_2X2:
243
0
                case GCT_MATRIX_DOUBLE_2X3:
244
0
                case GCT_MATRIX_DOUBLE_2X4:
245
0
                    return 16; // 4 float4s
246
0
                case GCT_MATRIX_DOUBLE_3X2:
247
0
                case GCT_MATRIX_DOUBLE_3X3:
248
0
                case GCT_MATRIX_DOUBLE_3X4:
249
0
                    return 24;
250
0
                case GCT_MATRIX_DOUBLE_4X2:
251
0
                case GCT_MATRIX_DOUBLE_4X3:
252
0
                case GCT_MATRIX_DOUBLE_4X4:
253
0
                    return 32;
254
0
                default:
255
0
                    return 4;
256
0
                };
257
0
            }
258
0
            else
259
0
            {
260
0
                switch(ctype)
261
0
                {
262
0
                case GCT_SAMPLER1D:
263
0
                case GCT_SAMPLER2D:
264
0
                case GCT_SAMPLER2DARRAY:
265
0
                case GCT_SAMPLER3D:
266
0
                case GCT_SAMPLERCUBE:
267
0
                case GCT_SAMPLER1DSHADOW:
268
0
                case GCT_SAMPLER2DSHADOW:
269
0
                    return 1;
270
0
                case GCT_MATRIX_2X2:
271
0
                case GCT_MATRIX_DOUBLE_2X2:
272
0
                    return 4;
273
0
                case GCT_MATRIX_2X3:
274
0
                case GCT_MATRIX_3X2:
275
0
                case GCT_MATRIX_DOUBLE_2X3:
276
0
                case GCT_MATRIX_DOUBLE_3X2:
277
0
                    return 6;
278
0
                case GCT_MATRIX_2X4:
279
0
                case GCT_MATRIX_4X2:
280
0
                case GCT_MATRIX_DOUBLE_2X4:
281
0
                case GCT_MATRIX_DOUBLE_4X2:
282
0
                    return 8;
283
0
                case GCT_MATRIX_3X3:
284
0
                case GCT_MATRIX_DOUBLE_3X3:
285
0
                    return 9;
286
0
                case GCT_MATRIX_3X4:
287
0
                case GCT_MATRIX_4X3:
288
0
                case GCT_MATRIX_DOUBLE_3X4:
289
0
                case GCT_MATRIX_DOUBLE_4X3:
290
0
                    return 12;
291
0
                case GCT_MATRIX_4X4:
292
0
                case GCT_MATRIX_DOUBLE_4X4:
293
0
                    return 16;
294
0
                default:
295
0
                    return ctype % 0x10;
296
0
                };
297
0
298
0
            }
299
0
        }
300
301
    GpuConstantDefinition()
302
        : physicalIndex((std::numeric_limits<size_t>::max)())
303
            , logicalIndex(0)
304
            , elementSize(0)
305
            , arraySize(1)
306
            , constType(GCT_UNKNOWN)
307
0
            , variability(GPV_GLOBAL) {}
308
    };
309
    typedef std::map<String, GpuConstantDefinition> GpuConstantDefinitionMap;
310
    typedef ConstMapIterator<GpuConstantDefinitionMap> GpuConstantDefinitionIterator;
311
312
    /// Struct collecting together the information for named constants.
313
    struct _OgreExport GpuNamedConstants : public GpuParamsAlloc
314
    {
315
        /// Total size of the buffer required
316
        size_t bufferSize;
317
        /// Number of register type params (samplers)
318
        size_t registerCount;
319
        /// Map of parameter names to GpuConstantDefinition
320
        GpuConstantDefinitionMap map;
321
322
        GpuNamedConstants();
323
        ~GpuNamedConstants();
324
325
        /** Saves constant definitions to a file
326
         * compatible with @ref GpuProgram::setManualNamedConstantsFile.
327
         */
328
        void save(const String& filename) const;
329
        /** Loads constant definitions from a stream
330
         * compatible with @ref GpuProgram::setManualNamedConstantsFile.
331
         */
332
        void load(DataStreamPtr& stream);
333
334
        size_t calculateSize(void) const;
335
    };
336
337
    /// Simple class for loading / saving GpuNamedConstants
338
    class _OgreExport GpuNamedConstantsSerializer : public Serializer
339
    {
340
    public:
341
        GpuNamedConstantsSerializer();
342
        virtual ~GpuNamedConstantsSerializer();
343
        void exportNamedConstants(const GpuNamedConstants* pConsts, const String& filename,
344
                                  Endian endianMode = ENDIAN_NATIVE);
345
        void exportNamedConstants(const GpuNamedConstants* pConsts, DataStreamPtr stream,
346
                                  Endian endianMode = ENDIAN_NATIVE);
347
        void importNamedConstants(DataStreamPtr& stream, GpuNamedConstants* pDest);
348
    };
349
350
    /** Structure recording the use of a physical buffer by a logical parameter
351
        index. Only used for low-level programs.
352
    */
353
    struct _OgreExport GpuLogicalIndexUse
354
    {
355
        /// Physical buffer index
356
        size_t physicalIndex;
357
        /// Current physical size allocation
358
        size_t currentSize;
359
        /// How the contents of this slot vary
360
        mutable uint16 variability;
361
        /// Data type
362
        BaseConstantType baseType;
363
364
    GpuLogicalIndexUse()
365
0
        : physicalIndex(99999), currentSize(0), variability(GPV_GLOBAL), baseType(BCT_UNKNOWN) {}
366
    GpuLogicalIndexUse(size_t bufIdx, size_t curSz, uint16 v, BaseConstantType t)
367
0
        : physicalIndex(bufIdx), currentSize(curSz), variability(v), baseType(t) {}
368
    };
369
    typedef std::map<size_t, GpuLogicalIndexUse> GpuLogicalIndexUseMap;
370
    /// Container struct to allow params to safely & update shared list of logical buffer assignments
371
    struct _OgreExport GpuLogicalBufferStruct : public GpuParamsAlloc
372
    {
373
        OGRE_MUTEX(mutex);
374
375
        /// Map from logical index to physical buffer location
376
        GpuLogicalIndexUseMap map;
377
        /// Shortcut to know the buffer size needs
378
        size_t bufferSize;
379
        GpuLogicalBufferStruct();
380
        ~GpuLogicalBufferStruct();
381
    };
382
383
    /** Definition of container that holds the current constants.
384
        @note Not necessarily in direct index order to constant indexes, logical
385
        to physical index map is derived from GpuProgram
386
    */
387
    typedef std::vector<uchar> ConstantList;
388
389
    class GpuProgramParameters;
390
391
    /** This class records the usage of a set of shared parameters in a concrete
392
        set of GpuProgramParameters.
393
    */
394
    class _OgreExport GpuSharedParametersUsage : public GpuParamsAlloc
395
    {
396
    private:
397
        GpuSharedParametersPtr mSharedParams;
398
        // Not a shared pointer since this is also parent
399
        GpuProgramParameters* mParams;
400
        // list of physical mappings that we are going to bring in
401
        struct CopyDataEntry
402
        {
403
            const GpuConstantDefinition* srcDefinition;
404
            const GpuConstantDefinition* dstDefinition;
405
        };
406
        typedef std::vector<CopyDataEntry> CopyDataList;
407
408
        CopyDataList mCopyDataList;
409
410
        /// Version of shared params we based the copydata on
411
        uint32 mCopyDataVersion;
412
413
        void initCopyData();
414
415
416
    public:
417
        /// Construct usage
418
        GpuSharedParametersUsage(GpuSharedParametersPtr sharedParams,
419
                                 GpuProgramParameters* params);
420
421
        /** Update the target parameters by copying the data from the shared
422
            parameters.
423
            @note This method  may not actually be called if the RenderSystem
424
            supports using shared parameters directly in their own shared buffer; in
425
            which case the values should not be copied out of the shared area
426
            into the individual parameter set, but bound separately.
427
        */
428
        void _copySharedParamsToTargetParams() const;
429
430
        /// Get the name of the shared parameter set
431
        const String& getName() const;
432
433
0
        GpuSharedParametersPtr getSharedParams() const { return mSharedParams; }
434
0
        GpuProgramParameters* getTargetParams() const { return mParams; }
435
    };
436
437
    /** Collects together the program parameters used for a GpuProgram.
438
439
        Gpu program state includes constant parameters used by the program, and
440
        bindings to render system state which is propagated into the constants
441
        by the engine automatically if requested.
442
        @par
443
        GpuProgramParameters objects should be created through the GpuProgram and
444
        may be shared between multiple Pass instances. For this reason they
445
        are managed using a shared pointer, which will ensure they are automatically
446
        deleted when no Pass is using them anymore.
447
        @par
448
        High-level programs use named parameters (uniforms), low-level programs
449
        use indexed constants. This class supports both, but you can tell whether
450
        named constants are supported by calling hasNamedParameters(). There are
451
        references in the documentation below to 'logical' and 'physical' indexes;
452
        logical indexes are the indexes used by low-level programs and represent
453
        indexes into an array of float4's, some of which may be settable, some of
454
        which may be predefined constants in the program. We only store those
455
        constants which have actually been set, therefore our buffer could have
456
        gaps if we used the logical indexes in our own buffers. So instead we map
457
        these logical indexes to physical indexes in our buffer. When using
458
        high-level programs, logical indexes don't necessarily exist, although they
459
        might if the high-level program has a direct, exposed mapping from parameter
460
        names to logical indexes. In addition, high-level languages may or may not pack
461
        arrays of elements that are smaller than float4 (e.g. float2/vec2) contiguously.
462
        This kind of information is held in the ConstantDefinition structure which
463
        is only populated for high-level programs. You don't have to worry about
464
        any of this unless you intend to read parameters back from this structure
465
        rather than just setting them.
466
    */
467
    class _OgreExport GpuProgramParameters : public GpuParamsAlloc
468
    {
469
    public:
470
        /** Defines the types of automatically updated values that may be bound to GpuProgram
471
            parameters, or used to modify parameters on a per-object basis.
472
473
            For use in @ref Program-Parameter-Specification, drop the `ACT_` prefix. 
474
            E.g. `ACT_WORLD_MATRIX` becomes `world_matrix`.
475
        */
476
        enum AutoConstantType
477
        {
478
            /// The current world matrix
479
            ACT_WORLD_MATRIX,
480
            /// The current world matrix, inverted
481
            ACT_INVERSE_WORLD_MATRIX,
482
            /** Provides transpose of world matrix.
483
            */
484
            ACT_TRANSPOSE_WORLD_MATRIX,
485
            /// The current world matrix, inverted & transposed
486
            ACT_INVERSE_TRANSPOSE_WORLD_MATRIX,
487
488
            /// An array of bone matrices, each represented as only a 3x4 matrix (3 rows of
489
            /// 4columns) usually for doing hardware skinning.
490
            /// You should make enough entries available in your vertex program for the number of
491
            /// bones in use, i.e. an array of numBones*3 float4’s.
492
            ACT_BONE_MATRIX_ARRAY_3x4,
493
            ACT_WORLD_MATRIX_ARRAY_3x4 = ACT_BONE_MATRIX_ARRAY_3x4,
494
            /// The current array of bone matrices, used for blending
495
            ACT_BONE_MATRIX_ARRAY,
496
            ACT_WORLD_MATRIX_ARRAY = ACT_BONE_MATRIX_ARRAY,
497
            /// The current array of bone matrices transformed to an array of dual quaternions,
498
            /// represented as a 2x4 matrix
499
            ACT_BONE_DUALQUATERNION_ARRAY_2x4,
500
            ACT_WORLD_DUALQUATERNION_ARRAY_2x4 = ACT_BONE_DUALQUATERNION_ARRAY_2x4,
501
            /// The scale and shear components of the current array of bone matrices
502
            ACT_BONE_SCALE_SHEAR_MATRIX_ARRAY_3x4,
503
            ACT_WORLD_SCALE_SHEAR_MATRIX_ARRAY_3x4 = ACT_BONE_SCALE_SHEAR_MATRIX_ARRAY_3x4,
504
505
            /// The current view matrix
506
            ACT_VIEW_MATRIX,
507
            /// The current view matrix, inverted
508
            ACT_INVERSE_VIEW_MATRIX,
509
            /** Provides transpose of view matrix.
510
            */
511
            ACT_TRANSPOSE_VIEW_MATRIX,
512
            /** Provides inverse transpose of view matrix.
513
            */
514
            ACT_INVERSE_TRANSPOSE_VIEW_MATRIX,
515
516
            /// The current projection matrix
517
            ACT_PROJECTION_MATRIX,
518
            /** Provides inverse of projection matrix.
519
            */
520
            ACT_INVERSE_PROJECTION_MATRIX,
521
            /** Provides transpose of projection matrix.
522
            */
523
            ACT_TRANSPOSE_PROJECTION_MATRIX,
524
            /** Provides inverse transpose of projection matrix.
525
            */
526
            ACT_INVERSE_TRANSPOSE_PROJECTION_MATRIX,
527
528
            /// The current view & projection matrices concatenated
529
            ACT_VIEWPROJ_MATRIX,
530
            /** Provides inverse of concatenated view and projection matrices.
531
            */
532
            ACT_INVERSE_VIEWPROJ_MATRIX,
533
            /** Provides transpose of concatenated view and projection matrices.
534
            */
535
            ACT_TRANSPOSE_VIEWPROJ_MATRIX,
536
            /** Provides inverse transpose of concatenated view and projection matrices.
537
            */
538
            ACT_INVERSE_TRANSPOSE_VIEWPROJ_MATRIX,
539
540
            /// The current world & view matrices concatenated
541
            ACT_WORLDVIEW_MATRIX,
542
            /// The current world & view matrices concatenated, then inverted
543
            ACT_INVERSE_WORLDVIEW_MATRIX,
544
            /** Provides transpose of concatenated world and view matrices.
545
            */
546
            ACT_TRANSPOSE_WORLDVIEW_MATRIX,
547
            /// The current world & view matrices concatenated, then inverted & transposed
548
            ACT_INVERSE_TRANSPOSE_WORLDVIEW_MATRIX,
549
            /** Provides inverse transpose of the upper 3x3 of the worldview matrix.
550
                Equivalent to @c gl_NormalMatrix.
551
            */
552
            ACT_NORMAL_MATRIX,
553
554
            /// The current world, view & projection matrices concatenated
555
            ACT_WORLDVIEWPROJ_MATRIX,
556
            /** Provides inverse of concatenated world, view and projection matrices.
557
            */
558
            ACT_INVERSE_WORLDVIEWPROJ_MATRIX,
559
            /** Provides transpose of concatenated world, view and projection matrices.
560
            */
561
            ACT_TRANSPOSE_WORLDVIEWPROJ_MATRIX,
562
            /** Provides inverse transpose of concatenated world, view and projection
563
                matrices.
564
            */
565
            ACT_INVERSE_TRANSPOSE_WORLDVIEWPROJ_MATRIX,
566
            /// For layered rendering: The current world, view & projection matrices concatenated
567
            ACT_WORLDVIEWPROJ_MATRIX_ARRAY,
568
569
            // render target related values
570
            /** -1 if requires texture flipping, +1 otherwise. It's useful when you bypassed
571
                projection matrix transform, still able use this value to adjust transformed y
572
               position.
573
            */
574
            ACT_RENDER_TARGET_FLIPPING,
575
576
            /** -1 if the winding has been inverted, +1 otherwise.
577
             * e.g. for reflections
578
             */
579
            ACT_VERTEX_WINDING,
580
581
            /// Fog colour
582
            ACT_FOG_COLOUR,
583
            /// Fog params: `(density, linear start, linear end, 1/(end-start))`
584
            ACT_FOG_PARAMS,
585
586
            /// Surface ambient colour, as set in Pass::setAmbient
587
            ACT_SURFACE_AMBIENT_COLOUR,
588
            /// Surface diffuse colour, as set in Pass::setDiffuse
589
            ACT_SURFACE_DIFFUSE_COLOUR,
590
            /// Surface specular colour, as set in Pass::setSpecular
591
            ACT_SURFACE_SPECULAR_COLOUR,
592
            /// Surface emissive colour, as set in Pass::setSelfIllumination
593
            ACT_SURFACE_EMISSIVE_COLOUR,
594
            /// Surface shininess, as set in Pass::setShininess
595
            ACT_SURFACE_SHININESS,
596
            /// Surface alpha rejection value, not as set in @ref Pass::setAlphaRejectValue, but a
597
            /// floating number between 0.0f and 1.0f instead (255.0f /
598
            /// @ref Pass::getAlphaRejectValue())
599
            ACT_SURFACE_ALPHA_REJECTION_VALUE,
600
601
            /// The number of active light sources
602
            ACT_LIGHT_COUNT,
603
604
            /// The ambient light colour set in the scene
605
            ACT_AMBIENT_LIGHT_COLOUR,
606
607
            /// Light diffuse colour (index determined by setAutoConstant call).
608
            /// this requires an index in the ’extra_params’ field, and relates to the ’nth’ closest
609
            /// light which could affect this object
610
            /// (i.e. 0 refers to the closest light - note that directional lights are always first
611
            /// in the list and always present).
612
            /// NB if there are no lights this close, then the parameter will be set to black.
613
            ACT_LIGHT_DIFFUSE_COLOUR,
614
            /// Light specular colour (index determined by setAutoConstant call)
615
            ACT_LIGHT_SPECULAR_COLOUR,
616
            /** Light attenuation parameters.
617
             * Packed as `(range, constant, linear, quadric)`.
618
             * For area lights this contains the height half-vector `(x, y, z, 0)` of the light in viewspace.
619
             */
620
            ACT_LIGHT_ATTENUATION,
621
            /** Spotlight parameters.
622
                Packed as `(innerFactor, outerFactor, falloff, spotType)`
623
                innerFactor and outerFactor are cos(angle/2)
624
                The spotType parameter is 0.0f for non-spotlights, 1.0f for spotlights and 2.0f for
625
                area spotlights.
626
                For area lights this contains the width half-vector `(x, y, z, 2)` of the light in viewspace.
627
                Also for non-spotlights the inner and outer factors are 1 and 0 respectively
628
            */
629
            ACT_SPOTLIGHT_PARAMS,
630
            /** A light position in world space (index determined by setAutoConstant call).
631
             This requires an index in the ’extra_params’ field, and relates to the ’nth’ closest
632
             light which could affect this object (i.e. 0 refers to the closest light).
633
             NB if there are no lights this close, then the parameter will be set to all zeroes.
634
             Note that this property will work with all kinds of lights, even directional lights,
635
             since the parameter is set as a 4D vector.
636
             Point lights will be `(pos.x, pos.y, pos.z, 1.0f)` whilst directional lights will be
637
             `(-dir.x, -dir.y, -dir.z, 0.0f)`.
638
             Operations like dot products will work consistently on both.
639
             */
640
            ACT_LIGHT_POSITION,
641
            /// A light position in object space (index determined by setAutoConstant call)
642
            ACT_LIGHT_POSITION_OBJECT_SPACE,
643
            /// A light position in view space (index determined by setAutoConstant call)
644
            ACT_LIGHT_POSITION_VIEW_SPACE,
645
            /// A light direction in world space (index determined by setAutoConstant call)
646
            /// @deprecated this property only works on directional lights, and we recommend that
647
            /// you use light_position instead since that returns a generic 4D vector.
648
            ACT_LIGHT_DIRECTION,
649
            /// A light direction in object space (index determined by setAutoConstant call)
650
            ACT_LIGHT_DIRECTION_OBJECT_SPACE,
651
            /// A light direction in view space (index determined by setAutoConstant call)
652
            ACT_LIGHT_DIRECTION_VIEW_SPACE,
653
            /** The distance of the light from the center of the object
654
                a useful approximation as an alternative to per-vertex distance
655
                calculations.
656
            */
657
            ACT_LIGHT_DISTANCE_OBJECT_SPACE,
658
            /** Light power level, a single scalar as set in Light::setPowerScale  (index determined
659
               by setAutoConstant call) */
660
            ACT_LIGHT_POWER_SCALE,
661
            /// Light diffuse colour pre-scaled by Light::setPowerScale (index determined by
662
            /// setAutoConstant call)
663
            ACT_LIGHT_DIFFUSE_COLOUR_POWER_SCALED,
664
            /// Light specular colour pre-scaled by Light::setPowerScale (index determined by
665
            /// setAutoConstant call)
666
            ACT_LIGHT_SPECULAR_COLOUR_POWER_SCALED,
667
            /// Array of light diffuse colours (count set by extra param)
668
            ACT_LIGHT_DIFFUSE_COLOUR_ARRAY,
669
            /// Array of light specular colours (count set by extra param)
670
            ACT_LIGHT_SPECULAR_COLOUR_ARRAY,
671
            /// Array of light diffuse colours scaled by light power (count set by extra param)
672
            ACT_LIGHT_DIFFUSE_COLOUR_POWER_SCALED_ARRAY,
673
            /// Array of light specular colours scaled by light power (count set by extra param)
674
            ACT_LIGHT_SPECULAR_COLOUR_POWER_SCALED_ARRAY,
675
            /// Array of light attenuation parameters.
676
            /// @copydetails #ACT_LIGHT_ATTENUATION (count set by extra param)
677
            ACT_LIGHT_ATTENUATION_ARRAY,
678
            /// Array of light positions in world space (count set by extra param)
679
            ACT_LIGHT_POSITION_ARRAY,
680
            /// Array of light positions in object space (count set by extra param)
681
            ACT_LIGHT_POSITION_OBJECT_SPACE_ARRAY,
682
            /// Array of light positions in view space (count set by extra param)
683
            ACT_LIGHT_POSITION_VIEW_SPACE_ARRAY,
684
            /// Array of light directions in world space (count set by extra param)
685
            ACT_LIGHT_DIRECTION_ARRAY,
686
            /// Array of light directions in object space (count set by extra param)
687
            ACT_LIGHT_DIRECTION_OBJECT_SPACE_ARRAY,
688
            /// Array of light directions in view space (count set by extra param)
689
            ACT_LIGHT_DIRECTION_VIEW_SPACE_ARRAY,
690
            /** Array of distances of the lights from the center of the object
691
                a useful approximation as an alternative to per-vertex distance
692
                calculations. (count set by extra param)
693
            */
694
            ACT_LIGHT_DISTANCE_OBJECT_SPACE_ARRAY,
695
            /** Array of light power levels, a single scalar as set in Light::setPowerScale
696
                (count set by extra param)
697
            */
698
            ACT_LIGHT_POWER_SCALE_ARRAY,
699
            /** Spotlight parameters array
700
             * @copydetails #ACT_SPOTLIGHT_PARAMS
701
             * (count set by extra param)
702
             */
703
            ACT_SPOTLIGHT_PARAMS_ARRAY,
704
705
            /** The derived ambient light colour, with 'r', 'g', 'b' components filled with
706
                product of surface ambient colour and ambient light colour, respectively,
707
                and 'a' component filled with surface diffuse alpha component.
708
            */
709
            ACT_DERIVED_AMBIENT_LIGHT_COLOUR,
710
            /** The derived scene colour, with 'r', 'g' and 'b' components filled with sum
711
                of derived ambient light colour and surface emissive colour, respectively,
712
                and 'a' component filled with surface diffuse alpha component.
713
            */
714
            ACT_DERIVED_SCENE_COLOUR,
715
716
            /** The derived light diffuse colour (index determined by setAutoConstant call),
717
                with 'r', 'g' and 'b' components filled with product of surface diffuse colour,
718
                light power scale and light diffuse colour, respectively, and 'a' component filled
719
               with surface
720
                diffuse alpha component.
721
            */
722
            ACT_DERIVED_LIGHT_DIFFUSE_COLOUR,
723
            /** The derived light specular colour (index determined by setAutoConstant call),
724
                with 'r', 'g' and 'b' components filled with product of surface specular colour
725
                and light specular colour, respectively, and 'a' component filled with surface
726
                specular alpha component.
727
            */
728
            ACT_DERIVED_LIGHT_SPECULAR_COLOUR,
729
730
            /// Array of derived light diffuse colours (count set by extra param)
731
            ACT_DERIVED_LIGHT_DIFFUSE_COLOUR_ARRAY,
732
            /// Array of derived light specular colours (count set by extra param)
733
            ACT_DERIVED_LIGHT_SPECULAR_COLOUR_ARRAY,
734
            /** The absolute light number of a local light index. Each pass may have
735
                a number of lights passed to it, and each of these lights will have
736
                an index in the overall light list, which will differ from the local
737
                light index due to factors like setStartLight and setIteratePerLight.
738
                This binding provides the global light index for a local index.
739
            */
740
            ACT_LIGHT_NUMBER,
741
            /// Returns (int) 1 if the  given light casts shadows, 0 otherwise (index set in extra
742
            /// param)
743
            ACT_LIGHT_CASTS_SHADOWS,
744
            /// Returns (int) 1 if the  given light casts shadows, 0 otherwise (index set in extra
745
            /// param)
746
            ACT_LIGHT_CASTS_SHADOWS_ARRAY,
747
748
            /** The distance a shadow volume should be extruded when using
749
                finite extrusion programs.
750
            */
751
            ACT_SHADOW_EXTRUSION_DISTANCE,
752
            /// The current camera's position in world space
753
            ACT_CAMERA_POSITION,
754
            /// The current camera's position in object space
755
            ACT_CAMERA_POSITION_OBJECT_SPACE,
756
            /// The current camera's position in world space even when camera relative rendering is enabled
757
            ACT_CAMERA_RELATIVE_POSITION,
758
759
            /** The view/projection matrix of the assigned texture projection frustum.
760
             Applicable to vertex programs which have been specified as the ’shadow receiver’ vertex
761
             program alternative, or where a texture unit is marked as content_type shadow; this
762
             provides details of the view/projection matrix for the current shadow projector. The
763
             optional ’extra_params’ entry specifies which light the projector refers to (for the
764
             case of content_type shadow where more than one shadow texture may be present in a
765
             single pass), where 0 is the default and refers to the first light referenced in this
766
             pass.
767
             */
768
            ACT_TEXTURE_VIEWPROJ_MATRIX,
769
            /// Array of view/projection matrices of the first n texture projection frustums
770
            ACT_TEXTURE_VIEWPROJ_MATRIX_ARRAY,
771
            /** The view/projection matrix of the assigned texture projection frustum,
772
                combined with the current world matrix
773
            */
774
            ACT_TEXTURE_WORLDVIEWPROJ_MATRIX,
775
            /// Array of world/view/projection matrices of the first n texture projection frustums
776
            ACT_TEXTURE_WORLDVIEWPROJ_MATRIX_ARRAY,
777
            /// The view/projection matrix of a given spotlight
778
            ACT_SPOTLIGHT_VIEWPROJ_MATRIX,
779
            /// Array of view/projection matrix of a given spotlight
780
            ACT_SPOTLIGHT_VIEWPROJ_MATRIX_ARRAY,
781
            /** The view/projection matrix of a given spotlight projection frustum,
782
                combined with the current world matrix
783
            */
784
            ACT_SPOTLIGHT_WORLDVIEWPROJ_MATRIX,
785
            /** An array of the view/projection matrix of a given spotlight projection frustum,
786
                combined with the current world matrix
787
            */
788
            ACT_SPOTLIGHT_WORLDVIEWPROJ_MATRIX_ARRAY,
789
            /** A custom parameter which will come from the renderable, using 'data' as the
790
             identifier
791
792
             This allows you to map a custom parameter on an individual Renderable (see
793
             Renderable::setCustomParameter) to a parameter on a GPU program. It requires that you
794
             complete the ’extra_params’ field with the index that was used in the
795
             Renderable::setCustomParameter call, and this will ensure that whenever this Renderable
796
             is used, it will have it’s custom parameter mapped in. It’s very important that this
797
             parameter has been defined on all Renderables that are assigned the material that
798
             contains this automatic mapping, otherwise the process will fail.
799
             */
800
            ACT_CUSTOM,
801
            /** provides current elapsed time
802
             */
803
            ACT_TIME,
804
            /** Single float value, which repeats itself based on given as
805
                parameter "cycle time".
806
            */
807
            ACT_TIME_0_X,
808
            /// Cosine of "Time0_X".
809
            ACT_COSTIME_0_X,
810
            /// Sine of "Time0_X".
811
            ACT_SINTIME_0_X,
812
            /// Tangent of "Time0_X".
813
            ACT_TANTIME_0_X,
814
            /** Vector of "Time0_X", "SinTime0_X", "CosTime0_X",
815
                "TanTime0_X".
816
            */
817
            ACT_TIME_0_X_PACKED,
818
            /** Single float value, which represents scaled time value [0..1],
819
                which repeats itself based on given as parameter "cycle time".
820
            */
821
            ACT_TIME_0_1,
822
            /// Cosine of "Time0_1".
823
            ACT_COSTIME_0_1,
824
            /// Sine of "Time0_1".
825
            ACT_SINTIME_0_1,
826
            /// Tangent of "Time0_1".
827
            ACT_TANTIME_0_1,
828
            /** Vector of "Time0_1", "SinTime0_1", "CosTime0_1",
829
                "TanTime0_1".
830
            */
831
            ACT_TIME_0_1_PACKED,
832
            /** Single float value, which represents scaled time value [0..2*Pi],
833
                which repeats itself based on given as parameter "cycle time".
834
            */
835
            ACT_TIME_0_2PI,
836
            /// Cosine of "Time0_2PI".
837
            ACT_COSTIME_0_2PI,
838
            /// Sine of "Time0_2PI".
839
            ACT_SINTIME_0_2PI,
840
            /// Tangent of "Time0_2PI".
841
            ACT_TANTIME_0_2PI,
842
            /** Vector of "Time0_2PI", "SinTime0_2PI", "CosTime0_2PI",
843
                "TanTime0_2PI".
844
            */
845
            ACT_TIME_0_2PI_PACKED,
846
            /// provides the scaled frame time, returned as a floating point value.
847
            ACT_FRAME_TIME,
848
            /// provides the calculated frames per second, returned as a floating point value.
849
            ACT_FPS,
850
            // viewport-related values
851
            /** Current viewport width (in pixels) as floating point value.
852
            */
853
            ACT_VIEWPORT_WIDTH,
854
            /** Current viewport height (in pixels) as floating point value.
855
            */
856
            ACT_VIEWPORT_HEIGHT,
857
            /** This variable represents `1/ViewportWidth`.
858
            */
859
            ACT_INVERSE_VIEWPORT_WIDTH,
860
            /** This variable represents `1/ViewportHeight`.
861
            */
862
            ACT_INVERSE_VIEWPORT_HEIGHT,
863
            /** Viewport dimensions.
864
            Packed as `(ViewportWidth, ViewportHeight, 1/ViewportWidth, 1/ViewportHeight)`
865
            */
866
            ACT_VIEWPORT_SIZE,
867
868
            // view parameters
869
            /** This variable provides the view direction vector (world space).
870
            */
871
            ACT_VIEW_DIRECTION,
872
            /** This variable provides the view side vector (world space).
873
            */
874
            ACT_VIEW_SIDE_VECTOR,
875
            /** This variable provides the view up vector (world space).
876
            */
877
            ACT_VIEW_UP_VECTOR,
878
            /** This variable provides the field of view as a floating point value.
879
            */
880
            ACT_FOV,
881
            /** This variable provides the near clip distance as a floating point value.
882
            */
883
            ACT_NEAR_CLIP_DISTANCE,
884
            /** This variable provides the far clip distance as a floating point value.
885
            */
886
            ACT_FAR_CLIP_DISTANCE,
887
888
            /** provides the pass index number within the technique
889
                of the active material.
890
            */
891
            ACT_PASS_NUMBER,
892
893
            /** provides the current iteration number of the pass. The iteration
894
                number is the number of times the current render operation has
895
                been drawn for the active pass.
896
            */
897
            ACT_PASS_ITERATION_NUMBER,
898
899
            /** Provides a parametric animation value [0..1], only available
900
                where the renderable specifically implements it.
901
902
               For morph animation, sets the parametric value
903
               (0..1) representing the distance between the first position keyframe (bound to
904
               positions) and the second position keyframe (bound to the first free texture
905
               coordinate) so that the vertex program can interpolate between them. For pose
906
               animation, indicates a group of up to 4 parametric weight values applying to a
907
               sequence of up to 4 poses (each one bound to x, y, z and w of the constant), one for
908
               each pose. The original positions are held in the usual position buffer, and the
909
               offsets to take those positions to the pose where weight == 1.0 are in the first ’n’
910
               free texture coordinates; ’n’ being determined by the value passed to
911
               includes_pose_animation. If more than 4 simultaneous poses are required, then you’ll
912
               need more than 1 shader constant to hold the parametric values, in which case you
913
               should use this binding more than once, referencing a different constant entry; the
914
               second one will contain the parametrics for poses 5-8, the third for poses 9-12, and
915
               so on.
916
            */
917
            ACT_ANIMATION_PARAMETRIC,
918
919
            /** Provides the texel offsets required by this rendersystem to map
920
                texels to pixels. Packed as
921
                `(absoluteHorizontalOffset, absoluteVerticalOffset, horizontalOffset / viewportWidth, verticalOffset / viewportHeight)`
922
            */
923
            ACT_TEXEL_OFFSETS,
924
925
            /** Provides information about the depth range of the scene as viewed
926
                from the current camera.
927
                Passed as `(minDepth, maxDepth, depthRange, 1 / depthRange)`
928
            */
929
            ACT_SCENE_DEPTH_RANGE,
930
931
            /** Provides information about the depth range of the scene as viewed
932
                from a given shadow camera. Requires an index parameter which maps
933
                to a light index relative to the current light list.
934
                Passed as `(minDepth, maxDepth, depthRange, 1 / depthRange)`
935
            */
936
            ACT_SHADOW_SCENE_DEPTH_RANGE,
937
938
            /** Provides an array of information about the depth range of the scene as viewed
939
                from a given shadow camera. Requires an index parameter which maps
940
                to a light index relative to the current light list.
941
                Passed as `(minDepth, maxDepth, depthRange, 1 / depthRange)`
942
            */
943
            ACT_SHADOW_SCENE_DEPTH_RANGE_ARRAY,
944
945
            /** Provides the fixed shadow colour as configured via SceneManager::setShadowColour;
946
                useful for integrated modulative shadows.
947
            */
948
            ACT_SHADOW_COLOUR,
949
            /** Provides texture size of the texture unit (index determined by setAutoConstant
950
                call). Packed as `(width, height, depth, numMipMaps)`
951
            */
952
            ACT_TEXTURE_SIZE,
953
            /** Provides inverse texture size of the texture unit (index determined by
954
               setAutoConstant
955
                call). Packed as `(1 / width, 1 / height, 1 / depth, 1 / numMipMaps)`
956
            */
957
            ACT_INVERSE_TEXTURE_SIZE,
958
            /** Provides packed texture size of the texture unit (index determined by
959
               setAutoConstant
960
                call). Packed as `(width, height, 1 / width, 1 / height)`
961
            */
962
            ACT_PACKED_TEXTURE_SIZE,
963
964
            /** Provides the current transform matrix of the texture unit (index determined by
965
               setAutoConstant
966
                call), as seen by the fixed-function pipeline.
967
968
                This requires an index in the ’extra_params’ field, and relates to the ’nth’ texture
969
               unit of the pass in question.
970
                NB if the given index exceeds the number of texture units available for this pass,
971
               then the parameter will be set to Matrix4::IDENTITY.
972
            */
973
            ACT_TEXTURE_MATRIX,
974
975
            /** Provides the position of the LOD camera in world space, allowing you
976
                to perform separate LOD calculations in shaders independent of the rendering
977
                camera. If there is no separate LOD camera then this is the real camera
978
                position. See Camera::setLodCamera.
979
            */
980
            ACT_LOD_CAMERA_POSITION,
981
            /** Provides the position of the LOD camera in object space, allowing you
982
                to perform separate LOD calculations in shaders independent of the rendering
983
                camera. If there is no separate LOD camera then this is the real camera
984
                position. See Camera::setLodCamera.
985
            */
986
            ACT_LOD_CAMERA_POSITION_OBJECT_SPACE,
987
            /** Binds custom per-light constants to the shaders. */
988
            ACT_LIGHT_CUSTOM,
989
            /// Point attenuation params.
990
            /// Packed as `(size, constant, linear, quadratic)`
991
            ACT_POINT_PARAMS,
992
            /// the LOD index as selected by the active LodStrategy
993
            ACT_MATERIAL_LOD_INDEX,
994
            /// Clustered (froxel) lighting grid size parameters
995
            /// packed as `(countX, countY, yFix, tileSizePx)`
996
            ACT_FROXEL_TILE_PARAMS,
997
            /// Clustered (froxel) lighting depth parameters
998
            /// packed as `(scaleZ, biasZ, linZ, sliceCount)`
999
            ACT_FROXEL_DEPTH_PARAMS,
1000
            /// (offset << 8) | count, into froxel record buffer: uint32 x 4096
1001
            ACT_FROXEL_GRID,
1002
            /// Light indices: uint8 packed as uint32 x 4096
1003
            ACT_FROXEL_RECORDS
1004
        };
1005
1006
        /** Defines the type of the extra data item used by the auto constant.
1007
1008
         */
1009
        enum ACDataType {
1010
            /// no data is required
1011
            ACDT_NONE,
1012
            /// the auto constant requires data of type int
1013
            ACDT_INT,
1014
            /// the auto constant requires data of type float
1015
            ACDT_REAL
1016
        };
1017
1018
        /** Defines the base element type of the auto constant
1019
         */
1020
        enum ElementType {
1021
            ET_INT = BCT_INT,
1022
            // float
1023
            ET_REAL = BCT_FLOAT
1024
        };
1025
1026
        /** Structure defining an auto constant that's available for use in
1027
            a parameters object.
1028
        */
1029
        struct AutoConstantDefinition
1030
        {
1031
            AutoConstantType acType;
1032
            String name;
1033
            size_t elementCount;
1034
            /// @deprecated do not use
1035
            OGRE_DEPRECATED ElementType elementType;
1036
            /// The type of any extra data
1037
            ACDataType dataType;
1038
1039
        AutoConstantDefinition(AutoConstantType _acType, const String& _name,
1040
                               size_t _elementCount, ElementType _elementType,
1041
                               ACDataType _dataType)
1042
        :acType(_acType), name(_name), elementCount(_elementCount),
1043
                elementType(_elementType), dataType(_dataType)
1044
0
            {
1045
0
1046
0
            }
1047
        };
1048
1049
        /** Structure recording the use of an automatic parameter. */
1050
        class AutoConstantEntry
1051
        {
1052
        public:
1053
            /// The target (physical) constant index
1054
            size_t physicalIndex;
1055
            /// The type of parameter
1056
            AutoConstantType paramType;
1057
            /// Additional information to go with the parameter
1058
            union{
1059
                uint32 data;
1060
                float fData;
1061
            };
1062
            /// The variability of this parameter (see GpuParamVariability)
1063
            uint16 variability;
1064
            /** The number of elements per individual entry in this constant
1065
                Used in case people used packed elements smaller than 4 (e.g. GLSL)
1066
                and bind an auto which is 4-element packed to it */
1067
            uint8 elementCount;
1068
1069
        AutoConstantEntry(AutoConstantType theType, size_t theIndex, uint32 theData,
1070
                          uint16 theVariability, uint8 theElemCount = 4)
1071
            : physicalIndex(theIndex), paramType(theType),
1072
0
                data(theData), variability(theVariability), elementCount(theElemCount) {}
1073
1074
        AutoConstantEntry(AutoConstantType theType, size_t theIndex, float theData,
1075
                          uint16 theVariability, uint8 theElemCount = 4)
1076
            : physicalIndex(theIndex), paramType(theType),
1077
0
                fData(theData), variability(theVariability), elementCount(theElemCount) {}
1078
1079
        };
1080
        // Auto parameter storage
1081
        typedef std::vector<AutoConstantEntry> AutoConstantList;
1082
1083
        typedef std::vector<GpuSharedParametersUsage> GpuSharedParamUsageList;
1084
    private:
1085
        static AutoConstantDefinition AutoConstantDictionary[];
1086
1087
        /// Packed list of constants (physical indexing)
1088
        ConstantList mConstants;
1089
1090
        /// Sampler handles (logical indexing)
1091
        std::vector<int> mRegisters;
1092
1093
        /** Logical index to physical index map - for low-level programs
1094
            or high-level programs which pass params this way. */
1095
        GpuLogicalBufferStructPtr mLogicalToPhysical;
1096
1097
        /** Gets the physical buffer index associated with a logical int constant index.
1098
         */
1099
        GpuLogicalIndexUse* getConstantLogicalIndexUse(size_t logicalIndex, size_t requestedSize,
1100
                                                       uint16 variability, BaseConstantType type);
1101
1102
        /// Mapping from parameter names to def - high-level programs are expected to populate this
1103
        GpuNamedConstantsPtr mNamedConstants;
1104
        /// List of automatically updated parameters
1105
        AutoConstantList mAutoConstants;
1106
        /// The combined variability masks of all parameters
1107
        uint16 mCombinedVariability;
1108
        /// Do we need to transpose matrices?
1109
        bool mTransposeMatrices;
1110
        /// flag to indicate if names not found will be ignored
1111
        bool mIgnoreMissingParams;
1112
        /// physical index for active pass iteration parameter real constant entry;
1113
        size_t mActivePassIterationIndex;
1114
1115
        bool mUseLinearColours;
1116
1117
        /// Return the variability for an auto constant
1118
        static uint16 deriveVariability(AutoConstantType act);
1119
1120
        void copySharedParamSetUsage(const GpuSharedParamUsageList& srcList);
1121
1122
        GpuSharedParamUsageList mSharedParamSets;
1123
1124
        template <typename T> void _setNamedConstant(const String& name, const T* val, size_t count);
1125
1126
    public:
1127
        GpuProgramParameters();
1128
        ~GpuProgramParameters();
1129
1130
        /// Copy constructor
1131
        GpuProgramParameters(const GpuProgramParameters& oth);
1132
        /// Operator = overload
1133
        GpuProgramParameters& operator=(const GpuProgramParameters& oth);
1134
1135
        /** Internal method for providing a link to a name->definition map for parameters. */
1136
        void _setNamedConstants(const GpuNamedConstantsPtr& constantmap);
1137
1138
        /** Internal method for providing a link to a logical index->physical index map for
1139
         * parameters. */
1140
        void _setLogicalIndexes(const GpuLogicalBufferStructPtr& indexMap);
1141
1142
        /// Does this parameter set include named parameters?
1143
0
        bool hasNamedParameters() const { return mNamedConstants.get() != 0; }
1144
        /** Does this parameter set include logically indexed parameters?
1145
            @note Not mutually exclusive with hasNamedParameters since some high-level
1146
            programs still use logical indexes to set the parameters on the
1147
            rendersystem.
1148
        */
1149
0
        bool hasLogicalIndexedParameters() const { return mLogicalToPhysical.get() != 0; }
1150
1151
        /// Convert colour parameters from gamma to linear space when setting them.
1152
        /// This is useful when you have your materials defined in gamma space but your
1153
        /// rendering is in linear space.
1154
0
        void setUseLinearColours(bool enable) { mUseLinearColours = enable; }
1155
1156
        /// @name Set constant by logical index
1157
        /// @{
1158
        /** Sets a 4-element floating-point parameter to the program.
1159
            @param index The logical constant index at which to place the parameter
1160
            (each constant is a 4D float)
1161
            @param vec The value to set
1162
        */
1163
        void setConstant(size_t index, const Vector4& vec);
1164
        /** Sets a single floating-point parameter to the program.
1165
            @note This is actually equivalent to calling
1166
            setConstant(index Vector4(val, 0, 0, 0)) since all constants are 4D.
1167
            @param index The logical constant index at which to place the parameter (each constant is
1168
            a 4D float)
1169
            @param val The value to set
1170
        */
1171
        void setConstant(size_t index, Real val);
1172
        /** Sets a 4-element floating-point parameter to the program via Vector3.
1173
            @param index The logical constant index at which to place the parameter (each constant is
1174
            a 4D float).
1175
            Note that since you're passing a Vector3, the last element of the 4-element
1176
            value will be set to 1 (a homogeneous vector)
1177
            @param vec The value to set
1178
        */
1179
        void setConstant(size_t index, const Vector3& vec);
1180
        /** Sets a 4-element floating-point parameter to the program via Vector2.
1181
            @param index The logical constant index at which to place the parameter (each constant is
1182
            a 4D float).
1183
            Note that since you're passing a Vector2, the last 2 elements of the 4-element
1184
            value will be set to 1 (a homogeneous vector)
1185
            @param vec The value to set
1186
        */
1187
        void setConstant(size_t index, const Vector2& vec);
1188
        /** Sets a Matrix4 parameter to the program.
1189
            @param index The logical constant index at which to place the parameter (each constant is
1190
            a 4D float).
1191
            NB since a Matrix4 is 16 floats long, this parameter will take up 4 indexes.
1192
            @param m The value to set
1193
        */
1194
        void setConstant(size_t index, const Matrix4& m);
1195
        /** Sets a list of Matrix4 parameters to the program.
1196
            @param index The logical constant index at which to start placing the parameter (each constant is
1197
            a 4D float).
1198
            NB since a Matrix4 is 16 floats long, so each entry will take up 4 indexes.
1199
            @param m Pointer to an array of matrices to set
1200
            @param numEntries Number of Matrix4 entries
1201
        */
1202
        void setConstant(size_t index, const Matrix4* m, size_t numEntries);
1203
        /** Sets a ColourValue parameter to the program.
1204
            @param index The logical constant index at which to place the parameter (each constant is
1205
            a 4D float)
1206
            @param colour The value to set
1207
        */
1208
        void setConstant(size_t index, const ColourValue& colour);
1209
        /** Sets a multiple value constant floating-point parameter to the program.
1210
            @param index The logical constant index at which to start placing parameters (each constant is
1211
            a 4D float)
1212
            @param val Pointer to the values to write, must contain 4*count floats
1213
            @param count The number of groups of 4 floats to write
1214
        */
1215
        void setConstant(size_t index, const float *val, size_t count);
1216
        /** Sets a multiple value constant floating-point parameter to the program.
1217
            @param index The logical constant index at which to start placing parameters (each constant is
1218
            a 4D float)
1219
            @param val Pointer to the values to write, must contain 4*count floats
1220
            @param count The number of groups of 4 floats to write
1221
        */
1222
        void setConstant(size_t index, const double *val, size_t count);
1223
        /** Sets a multiple value constant integer parameter to the program.
1224
1225
            Different types of GPU programs support different types of constant parameters.
1226
            For example, it's relatively common to find that vertex programs only support
1227
            floating point constants, and that fragment programs only support integer (fixed point)
1228
            parameters. This can vary depending on the program version supported by the
1229
            graphics card being used. You should consult the documentation for the type of
1230
            low level program you are using, or alternatively use the methods
1231
            provided on RenderSystemCapabilities to determine the options.
1232
            @param index The logical constant index at which to place the parameter (each constant is
1233
            a 4D integer)
1234
            @param val Pointer to the values to write, must contain 4*count ints
1235
            @param count The number of groups of 4 ints to write
1236
        */
1237
        void setConstant(size_t index, const int *val, size_t count);
1238
        /** Sets a multiple value constant unsigned integer parameter to the program.
1239
1240
            Different types of GPU programs support different types of constant parameters.
1241
            For example, it's relatively common to find that vertex programs only support
1242
            floating point constants, and that fragment programs only support integer (fixed point)
1243
            parameters. This can vary depending on the program version supported by the
1244
            graphics card being used. You should consult the documentation for the type of
1245
            low level program you are using, or alternatively use the methods
1246
            provided on RenderSystemCapabilities to determine the options.
1247
            @param index The logical constant index at which to place the parameter (each constant is
1248
            a 4D integer)
1249
            @param val Pointer to the values to write, must contain 4*count ints
1250
            @param count The number of groups of 4 ints to write
1251
        */
1252
        void setConstant(size_t index, const uint *val, size_t count);
1253
        /// @}
1254
1255
        /** @name Set constant by physical index
1256
            You can use these methods if you have already derived the physical
1257
            constant buffer location, for a slight speed improvement over using
1258
            the named / logical index versions.
1259
        */
1260
        /// @{
1261
        /** Write a series of values into the underlying
1262
            constant buffer at the given physical index.
1263
            @param physicalIndex The buffer position to start writing
1264
            @param val Pointer to a list of values to write
1265
            @param count The number of floats to write
1266
        */
1267
        template<typename T>
1268
        void _writeRawConstants(size_t physicalIndex, const T* val, size_t count)
1269
        {
1270
            assert(physicalIndex + sizeof(T) * count <= mConstants.size());
1271
            memcpy(&mConstants[physicalIndex], val, sizeof(T) * count);
1272
        }
1273
        /// @overload
1274
        void _writeRawConstants(size_t physicalIndex, const double* val, size_t count);
1275
        /// write values into register storage
1276
        void _writeRegisters(size_t index, const int* val, size_t count);
1277
        /** Write a Vector parameter to the program directly to
1278
            the underlying constants buffer.
1279
            @param physicalIndex The physical buffer index at which to place the parameter
1280
            @param vec The value to set
1281
            @param count The number of floats to write; if for example
1282
            the uniform constant 'slot' is smaller than a Vector4
1283
        */
1284
        template <int dims, typename T>
1285
        void _writeRawConstant(size_t physicalIndex, const Vector<dims, T>& vec, size_t count = dims)
1286
        {
1287
            _writeRawConstants(physicalIndex, vec.ptr(), std::min(count, (size_t)dims));
1288
        }
1289
        /** Write a single parameter to the program.
1290
            @param physicalIndex The physical buffer index at which to place the parameter
1291
            @param val The value to set
1292
        */
1293
        template<typename T>
1294
        void _writeRawConstant(size_t physicalIndex, T val)
1295
        {
1296
            _writeRawConstants(physicalIndex, &val, 1);
1297
        }
1298
        /** Write a Matrix4 parameter to the program.
1299
            @param physicalIndex The physical buffer index at which to place the parameter
1300
            @param m The value to set
1301
            @param elementCount actual element count used with shader
1302
        */
1303
        void _writeRawConstant(size_t physicalIndex, const Matrix4& m, size_t elementCount);
1304
        /// @overload
1305
        void _writeRawConstant(size_t physicalIndex, const Matrix3& m, size_t elementCount);
1306
        /** Write a list of Matrix4 parameters to the program.
1307
            @param physicalIndex The physical buffer index at which to place the parameter
1308
            @param m The value to set
1309
            @param numEntries Number of Matrix4 entries
1310
        */
1311
        void _writeRawConstant(size_t physicalIndex, const TransformBaseReal* m, size_t numEntries);
1312
        /** Write a ColourValue parameter to the program.
1313
            @param physicalIndex The physical buffer index at which to place the parameter
1314
            @param colour The value to set
1315
            @param count The number of floats to write; if for example
1316
            the uniform constant 'slot' is smaller than a Vector4
1317
        */
1318
        void _writeRawConstant(size_t physicalIndex, const ColourValue& colour,
1319
                               size_t count = 4);
1320
        /// @}
1321
1322
        /** Read a series of floating point values from the underlying float
1323
            constant buffer at the given physical index.
1324
            @param physicalIndex The buffer position to start reading
1325
            @param count The number of floats to read
1326
            @param dest Pointer to a buffer to receive the values
1327
        */
1328
        void _readRawConstants(size_t physicalIndex, size_t count, float* dest);
1329
        /** Read a series of integer values from the underlying integer
1330
            constant buffer at the given physical index.
1331
            @param physicalIndex The buffer position to start reading
1332
            @param count The number of ints to read
1333
            @param dest Pointer to a buffer to receive the values
1334
        */
1335
        void _readRawConstants(size_t physicalIndex, size_t count, int* dest);
1336
1337
        /// @deprecated use getConstantDefinitions()
1338
        OGRE_DEPRECATED GpuConstantDefinitionIterator getConstantDefinitionIterator(void) const;
1339
1340
        /** Get a specific GpuConstantDefinition for a named parameter.
1341
            @note
1342
            Only available if this parameters object has named parameters.
1343
        */
1344
        const GpuConstantDefinition& getConstantDefinition(const String& name) const;
1345
1346
        /** Get the full list of GpuConstantDefinition instances.
1347
            @note
1348
            Only available if this parameters object has named parameters.
1349
        */
1350
        const GpuNamedConstants& getConstantDefinitions() const;
1351
1352
        /** Get the current list of mappings from low-level logical param indexes
1353
            to physical buffer locations in the float buffer.
1354
            @note
1355
            Only applicable to low-level programs.
1356
        */
1357
0
        const GpuLogicalBufferStructPtr& getLogicalBufferStruct() const { return mLogicalToPhysical; }
1358
1359
        /** Retrieves the logical index relating to a physical index in the
1360
            buffer, for programs which support that (low-level programs and
1361
            high-level programs which use logical parameter indexes).
1362
            @return std::numeric_limits<size_t>::max() if not found
1363
        */
1364
        size_t getLogicalIndexForPhysicalIndex(size_t physicalIndex);
1365
        /// Get a reference to the list of constants
1366
0
        const ConstantList& getConstantList() const { return mConstants; }
1367
        /// Get a pointer to the 'nth' item in the float buffer
1368
0
        float* getFloatPointer(size_t pos) { return (float*)&mConstants[pos]; }
1369
        /// Get a pointer to the 'nth' item in the float buffer
1370
0
        const float* getFloatPointer(size_t pos) const { return (const float*)&mConstants[pos]; }
1371
        /// Get a pointer to the 'nth' item in the double buffer
1372
0
        double* getDoublePointer(size_t pos) { return (double*)&mConstants[pos]; }
1373
        /// Get a pointer to the 'nth' item in the double buffer
1374
0
        const double* getDoublePointer(size_t pos) const { return (const double*)&mConstants[pos]; }
1375
        /// Get a pointer to the 'nth' item in the int buffer
1376
0
        int* getIntPointer(size_t pos) { return (int*)&mConstants[pos]; }
1377
        /// Get a pointer to the 'nth' item in the int buffer
1378
0
        const int* getIntPointer(size_t pos) const { return (const int*)&mConstants[pos]; }
1379
        /// Get a pointer to the 'nth' item in the uint buffer
1380
0
        uint* getUnsignedIntPointer(size_t pos) { return (uint*)&mConstants[pos]; }
1381
        /// Get a pointer to the 'nth' item in the uint buffer
1382
0
        const uint* getUnsignedIntPointer(size_t pos) const { return (const uint*)&mConstants[pos]; }
1383
1384
        /// get a pointer to register storage
1385
0
        int* getRegPointer(size_t pos) { return &mRegisters[pos]; }
1386
        /// @overload
1387
0
        const int* getRegPointer(size_t pos) const { return &mRegisters[pos]; }
1388
1389
        /// @name Automatically derived constants
1390
        /// @{
1391
1392
        /// Get a reference to the list of auto constant bindings
1393
0
        const AutoConstantList& getAutoConstantList() const { return mAutoConstants; }
1394
1395
        /** Sets up a constant which will automatically be updated by the system.
1396
1397
            Vertex and fragment programs often need parameters which are to do with the
1398
            current render state, or particular values which may very well change over time,
1399
            and often between objects which are being rendered. This feature allows you
1400
            to set up a certain number of predefined parameter mappings that are kept up to
1401
            date for you.
1402
            @param index The location in the constant list to place this updated constant every time
1403
            it is changed. Note that because of the nature of the types, we know how big the
1404
            parameter details will be so you don't need to set that like you do for manual constants.
1405
            @param acType The type of automatic constant to set
1406
            @param extraInfo If the constant type needs more information (like a light index or array size) put it here.
1407
        */
1408
        void setAutoConstant(size_t index, AutoConstantType acType, uint32 extraInfo = 0);
1409
        /// @overload
1410
        void setAutoConstantReal(size_t index, AutoConstantType acType, float rData);
1411
        /// @overload
1412
        void setAutoConstant(size_t index, AutoConstantType acType, uint16 extraInfo1, uint16 extraInfo2)
1413
0
        {
1414
0
            setAutoConstant(index, acType, (uint32)extraInfo1 | ((uint32)extraInfo2) << 16);
1415
0
        }
1416
1417
        /** As setAutoConstant, but sets up the auto constant directly against a
1418
            physical buffer index.
1419
        */
1420
        void _setRawAutoConstant(size_t physicalIndex, AutoConstantType acType, uint32 extraInfo,
1421
                                 uint16 variability, uint8 elementSize = 4);
1422
        /** As setAutoConstantReal, but sets up the auto constant directly against a
1423
            physical buffer index.
1424
        */
1425
        void _setRawAutoConstantReal(size_t physicalIndex, AutoConstantType acType, float rData,
1426
                                     uint16 variability, uint8 elementSize = 4);
1427
1428
1429
        /** Unbind an auto constant so that the constant is manually controlled again. */
1430
        void clearAutoConstant(size_t index);
1431
1432
        /// @deprecated use ACT_TIME directly
1433
        OGRE_DEPRECATED void setConstantFromTime(size_t index, Real factor)
1434
0
        {
1435
0
            setAutoConstantReal(index, ACT_TIME, factor);
1436
0
        }
1437
1438
        /** Clears all the existing automatic constants. */
1439
        void clearAutoConstants(void);
1440
1441
        /** Gets the automatic constant bindings currently in place. */
1442
0
        const AutoConstantList& getAutoConstants() const {
1443
0
            return mAutoConstants;
1444
0
        }
1445
1446
        /// Gets the number of int constants that have been set
1447
0
        size_t getAutoConstantCount(void) const { return mAutoConstants.size(); }
1448
        /** Gets a specific Auto Constant entry if index is in valid range
1449
            otherwise returns a NULL
1450
            @param index which entry is to be retrieved
1451
        */
1452
        AutoConstantEntry* getAutoConstantEntry(const size_t index);
1453
        /** Returns true if this instance has any automatic constants. */
1454
0
        bool hasAutoConstants(void) const { return !(mAutoConstants.empty()); }
1455
        /** Finds an auto constant that's affecting a given logical parameter
1456
            index for floating-point values.
1457
            @note Only applicable for low-level programs.
1458
        */
1459
        const AutoConstantEntry* findFloatAutoConstantEntry(size_t logicalIndex);
1460
        /** Finds an auto constant that's affecting a given named parameter index.
1461
            @note Only applicable to high-level programs.
1462
        */
1463
        const AutoConstantEntry* findAutoConstantEntry(const String& paramName) const;
1464
        /** Finds an auto constant that's affecting a given physical position in
1465
            the floating-point buffer
1466
        */
1467
        const AutoConstantEntry* _findRawAutoConstantEntryFloat(size_t physicalIndex) const;
1468
        /** Sets up a constant which will automatically be updated by the system.
1469
1470
            Vertex and fragment programs often need parameters which are to do with the
1471
            current render state, or particular values which may very well change over time,
1472
            and often between objects which are being rendered. This feature allows you
1473
            to set up a certain number of predefined parameter mappings that are kept up to
1474
            date for you.
1475
            @note
1476
            This named option will only work if you are using a parameters object created
1477
            from a high-level program (HighLevelGpuProgram).
1478
            @param name The name of the parameter
1479
            @param acType The type of automatic constant to set
1480
            @param extraInfo If the constant type needs more information (like a light index) put it here.
1481
        */
1482
        void setNamedAutoConstant(const String& name, AutoConstantType acType, uint32 extraInfo = 0);
1483
        /// @overload
1484
        void setNamedAutoConstantReal(const String& name, AutoConstantType acType, Real rData);
1485
        /// @overload
1486
        void setNamedAutoConstant(const String& name, AutoConstantType acType, uint16 extraInfo1, uint16 extraInfo2)
1487
0
        {
1488
0
            setNamedAutoConstant(name, acType, (uint32)extraInfo1 | ((uint32)extraInfo2) << 16);
1489
0
        }
1490
1491
        /// @deprecated use ACT_TIME directly
1492
        void setNamedConstantFromTime(const String& name, Real factor)
1493
0
        {
1494
0
            setNamedAutoConstantReal(name, ACT_TIME, factor);
1495
0
        }
1496
1497
        /** Unbind an auto constant so that the constant is manually controlled again. */
1498
        void clearNamedAutoConstant(const String& name);
1499
        /// @}
1500
1501
        /** Update automatic parameters.
1502
            @param source The source of the parameters
1503
            @param variabilityMask A mask of GpuParamVariability which identifies which autos will need updating
1504
        */
1505
        void _updateAutoParams(const AutoParamDataSource* source, uint16 variabilityMask);
1506
1507
        /** Tells the program whether to ignore missing parameters or not.
1508
         */
1509
0
        void setIgnoreMissingParams(bool state) { mIgnoreMissingParams = state; }
1510
1511
        /// @name Set constant by name
1512
        /// @{
1513
        /** Sets a single value constant parameter to the program.
1514
1515
            Different types of GPU programs support different types of constant parameters.
1516
            For example, it's relatively common to find that vertex programs only support
1517
            floating point constants, and that fragment programs only support integer (fixed point)
1518
            parameters. This can vary depending on the program version supported by the
1519
            graphics card being used. You should consult the documentation for the type of
1520
            low level program you are using, or alternatively use the methods
1521
            provided on RenderSystemCapabilities to determine the options.
1522
1523
            Another possible limitation is that some systems only allow constants to be set
1524
            on certain boundaries, e.g. in sets of 4 values for example. Again, see
1525
            RenderSystemCapabilities for full details.
1526
            @note
1527
            This named option will only work if you are using a parameters object created
1528
            from a high-level program (HighLevelGpuProgram).
1529
            @param name The name of the parameter
1530
            @param val The value to set
1531
        */
1532
        void setNamedConstant(const String& name, float val);
1533
        /// @overload
1534
        void setNamedConstant(const String& name, int val);
1535
        /// @overload
1536
        void setNamedConstant(const String& name, uint val);
1537
        /// @overload
1538
        void setNamedConstant(const String& name, const Vector4& val);
1539
        /// @overload
1540
        void setNamedConstant(const String& name, const Vector3& val);
1541
        /// @overload
1542
        void setNamedConstant(const String& name, const Vector2& val);
1543
        /// @overload
1544
        void setNamedConstant(const String& name, const Matrix4& val);
1545
        /// @overload
1546
        void setNamedConstant(const String& name, const ColourValue& colour);
1547
        /** Sets a list of Matrix4 parameters to the program.
1548
            @param name The name of the parameter; this must be the first index of an array,
1549
            for examples 'matrices[0]'
1550
            NB since a Matrix4 is 16 floats long, so each entry will take up 4 indexes.
1551
            @param m Pointer to an array of matrices to set
1552
            @param numEntries Number of Matrix4 entries
1553
        */
1554
        void setNamedConstant(const String& name, const Matrix4* m, size_t numEntries);
1555
        /** Sets a multiple value constant parameter to the program.
1556
1557
            Some systems only allow constants to be set on certain boundaries,
1558
            e.g. in sets of 4 values for example. The 'multiple' parameter allows
1559
            you to control that although you should only change it if you know
1560
            your chosen language supports that (at the time of writing, only
1561
            GLSL allows constants which are not a multiple of 4).
1562
            @note
1563
            This named option will only work if you are using a parameters object created
1564
            from a high-level program (HighLevelGpuProgram).
1565
            @param name The name of the parameter
1566
            @param val Pointer to the values to write
1567
            @param count The number of 'multiples' of floats to write
1568
            @param multiple The number of raw entries in each element to write,
1569
            the default is 4 so count = 1 would write 4 floats.
1570
        */
1571
        void setNamedConstant(const String& name, const float *val, size_t count,
1572
                              size_t multiple = 4);
1573
        /// @overload
1574
        void setNamedConstant(const String& name, const double *val, size_t count,
1575
                              size_t multiple = 4);
1576
        /// @overload
1577
        void setNamedConstant(const String& name, const int *val, size_t count,
1578
                              size_t multiple = 4);
1579
        /// @overload
1580
        void setNamedConstant(const String& name, const uint *val, size_t count,
1581
                              size_t multiple = 4);
1582
        /// @}
1583
        /** Find a constant definition for a named parameter.
1584
1585
            This method returns null if the named parameter did not exist, unlike
1586
            getConstantDefinition which is more strict; unless you set the
1587
            last parameter to true.
1588
            @param name The name to look up
1589
            @param throwExceptionIfMissing If set to true, failure to find an entry
1590
            will throw an exception.
1591
        */
1592
        const GpuConstantDefinition* _findNamedConstantDefinition(
1593
            const String& name, bool throwExceptionIfMissing = false) const;
1594
        /** Gets the physical buffer index associated with a logical float constant index.
1595
            @note Only applicable to low-level programs.
1596
            @param logicalIndex The logical parameter index
1597
            @param requestedSize The requested size - pass 0 to ignore missing entries
1598
            and return std::numeric_limits<size_t>::max()
1599
            @param variability
1600
            @param type
1601
        */
1602
        size_t _getConstantPhysicalIndex(size_t logicalIndex, size_t requestedSize, uint16 variability, BaseConstantType type);
1603
        /** Sets whether or not we need to transpose the matrices passed in from the rest of OGRE.
1604
1605
            D3D uses transposed matrices compared to GL and OGRE; this is not important when you
1606
            use programs which are written to process row-major matrices, such as those generated
1607
            by Cg, but if you use a program written to D3D's matrix layout you will need to enable
1608
            this flag.
1609
        */
1610
0
        void setTransposeMatrices(bool val) { mTransposeMatrices = val; }
1611
        /// Gets whether or not matrices are to be transposed when set
1612
0
        bool getTransposeMatrices(void) const { return mTransposeMatrices; }
1613
1614
        /** Copies the values of all constants (including auto constants) from another
1615
            GpuProgramParameters object.
1616
            @note This copes the internal storage of the paarameters object and therefore
1617
            can only be used for parameters objects created from the same GpuProgram.
1618
            To merge parameters that match from different programs, use copyMatchingNamedConstantsFrom.
1619
        */
1620
        void copyConstantsFrom(const GpuProgramParameters& source);
1621
1622
        /** Copies the values of all matching named constants (including auto constants) from
1623
            another GpuProgramParameters object.
1624
1625
            This method iterates over the named constants in another parameters object
1626
            and copies across the values where they match. This method is safe to
1627
            use when the 2 parameters objects came from different programs, but only
1628
            works for named parameters.
1629
        */
1630
        void copyMatchingNamedConstantsFrom(const GpuProgramParameters& source);
1631
1632
        /** gets the auto constant definition associated with name if found else returns NULL
1633
            @param name The name of the auto constant
1634
        */
1635
        static const AutoConstantDefinition* getAutoConstantDefinition(const String& name);
1636
        /** gets the auto constant definition by auto constant type.
1637
            @param type The auto constant type
1638
        */
1639
        static const AutoConstantDefinition* getAutoConstantDefinition(AutoConstantType type);
1640
        /** Returns the number of auto constant definitions
1641
         */
1642
        static size_t getNumAutoConstantDefinitions(void);
1643
1644
1645
        /** increments the multipass number entry by 1 if it exists
1646
         */
1647
        void incPassIterationNumber(void);
1648
        /// @deprecated query by GPV_PASS_ITERATION_NUMBER instead
1649
        OGRE_DEPRECATED bool hasPassIterationNumber() const
1650
0
        { return mActivePassIterationIndex != (std::numeric_limits<size_t>::max)(); }
1651
        /// @deprecated query by GPV_PASS_ITERATION_NUMBER instead
1652
        OGRE_DEPRECATED size_t getPassIterationNumberIndex() const
1653
0
        { return mActivePassIterationIndex; }
1654
1655
        /// @name Shared Parameters
1656
        /// @{
1657
        /** Use a set of shared parameters in this parameters object.
1658
1659
            Allows you to use a set of shared parameters to automatically update
1660
            this parameter set.
1661
        */
1662
        void addSharedParameters(GpuSharedParametersPtr sharedParams);
1663
1664
        /** Use a set of shared parameters in this parameters object.
1665
1666
            Allows you to use a set of shared parameters to automatically update
1667
            this parameter set.
1668
            @param sharedParamsName The name of a shared parameter set as defined in
1669
            GpuProgramManager
1670
        */
1671
        void addSharedParameters(const String& sharedParamsName);
1672
1673
        /** Returns whether this parameter set is using the named shared parameter set. */
1674
        bool isUsingSharedParameters(const String& sharedParamsName) const;
1675
1676
        /** Stop using the named shared parameter set. */
1677
        void removeSharedParameters(const String& sharedParamsName);
1678
1679
        /** Stop using all shared parameter sets. */
1680
        void removeAllSharedParameters();
1681
1682
        /** Get the list of shared parameter sets. */
1683
        const GpuSharedParamUsageList& getSharedParameters() const;
1684
1685
        /** Update the parameters by copying the data from the shared
1686
            parameters.
1687
            @note This method  may not actually be called if the RenderSystem
1688
            supports using shared parameters directly in their own shared buffer; in
1689
            which case the values should not be copied out of the shared area
1690
            into the individual parameter set, but bound separately.
1691
        */
1692
        void _copySharedParams();
1693
1694
        /** Update the HardwareBuffer based backing of referenced shared parameters
1695
         *
1696
         * falls back to _copySharedParams() if a shared parameter is not hardware backed
1697
         */
1698
        void _updateSharedParams();
1699
        /// @}
1700
1701
        size_t calculateSize(void) const;
1702
    };
1703
1704
    /** A group of manually updated parameters that are shared between many parameter sets.
1705
1706
        Sometimes you want to set some common parameters across many otherwise
1707
        different parameter sets, and keep them all in sync together. This class
1708
        allows you to define a set of parameters that you can share across many
1709
        parameter sets and have the parameters that match automatically be pulled
1710
        from the shared set, rather than you having to set them on all the parameter
1711
        sets individually.
1712
        @par
1713
        Parameters in a shared set are matched up with instances in a GpuProgramParameters
1714
        structure by matching names. It is up to you to define the named parameters
1715
        that a shared set contains, and ensuring the definition matches.
1716
        @note
1717
        Shared parameter sets can be named, and looked up using the GpuProgramManager.
1718
    */
1719
    class _OgreExport GpuSharedParameters : public GpuParamsAlloc
1720
    {
1721
        /// Name of the shared parameter set.
1722
        String mName;
1723
1724
        /// Shared parameter definitions and related data.
1725
        GpuNamedConstants mNamedConstants;
1726
1727
        /// List of constant values.
1728
        ConstantList mConstants;
1729
1730
        /// Optional rendersystem backed storage
1731
        HardwareBufferPtr mHardwareBuffer;
1732
1733
        /// Version number of the definitions in this buffer.
1734
        uint32 mVersion;
1735
1736
    /// Accumulated offset used to calculate uniform location.
1737
    size_t mOffset;
1738
1739
        struct AutoConstantEntry
1740
        {
1741
            size_t physicalIndex;
1742
            GpuProgramParameters::AutoConstantType acType;
1743
            size_t arraySize;
1744
            uint32 elementCount;
1745
            uint32 hash;
1746
        };
1747
        std::vector<AutoConstantEntry> mAutoConstants;
1748
1749
        bool mDirty;
1750
        bool mUseLinearColours;
1751
1752
        template <typename T> void _setNamedConstant(const String& name, const T* val, uint32 count);
1753
1754
        void _updateAutoParam(AutoConstantEntry& entry, const char* data, uint32 size);
1755
    public:
1756
        GpuSharedParameters(const String& name);
1757
1758
        /// Get the name of this shared parameter set.
1759
0
        const String& getName() { return mName; }
1760
1761
        /// Convert colour parameters from gamma to linear space when setting them.
1762
        /// This is useful when you have your materials defined in gamma space but your
1763
        /// rendering is in linear space.
1764
0
        void setUseLinearColours(bool enable) { mUseLinearColours = enable; }
1765
1766
        /** Add a new constant definition to this shared set of parameters.
1767
1768
            Unlike GpuProgramParameters, where the parameter list is defined by the
1769
            program being compiled, this shared parameter set is defined by the
1770
            user. Only parameters which have been predefined here may be later
1771
            updated.
1772
        */
1773
        void addConstantDefinition(const String& name, GpuConstantType constType, uint32 arraySize = 1);
1774
1775
        /** Make a constant definition auto updated from AutoConstantType */
1776
        void setAutoConstant(const String& name, GpuProgramParameters::AutoConstantType acType);
1777
1778
        void _updateAutoParams(const AutoParamDataSource* source);
1779
1780
        /// @deprecated removing a constant requires a full rebuild due to changed alignments
1781
        OGRE_DEPRECATED void removeConstantDefinition(const String& name);
1782
1783
        /** Remove a constant definition from this shared set of parameters.
1784
         */
1785
        void removeAllConstantDefinitions();
1786
1787
        /** Get the version number of this shared parameter set, can be used to identify when
1788
            changes have occurred.
1789
        */
1790
0
        uint32 getVersion() const { return mVersion; }
1791
1792
        /** Calculate the expected size of the shared parameter buffer based
1793
            on constant definition data types.
1794
        */
1795
        size_t calculateSize(void) const;
1796
1797
        /** True if this parameter set is dirty (values have been modified,
1798
            but the render system has not updated them yet).
1799
        */
1800
0
        bool isDirty() const { return mDirty; }
1801
1802
        /** Mark the shared set as being clean (values successfully updated
1803
            by the render system).
1804
1805
            You do not need to call this yourself. The set is marked as clean
1806
            whenever the render system updates dirty shared parameters.
1807
        */
1808
        void _markClean();
1809
1810
        /** Mark the shared set as being dirty (values modified and not yet
1811
            updated in render system).
1812
1813
            You do not need to call this yourself. The set is marked as
1814
            dirty whenever setNamedConstant or (non const) getFloatPointer
1815
            et al are called.
1816
        */
1817
        void _markDirty();
1818
1819
        /// @deprecated use getConstantDefinitions()
1820
        OGRE_DEPRECATED GpuConstantDefinitionIterator getConstantDefinitionIterator(void) const;
1821
1822
        /** Get a specific GpuConstantDefinition for a named parameter.
1823
         */
1824
        const GpuConstantDefinition& getConstantDefinition(const String& name) const;
1825
1826
        /** Get the full list of GpuConstantDefinition instances.
1827
         */
1828
        const GpuNamedConstants& getConstantDefinitions() const;
1829
1830
        /// Get the constant definitions ordered by their physical index.
1831
        std::vector<std::pair<String, GpuConstantDefinition>> getConstantDefinitionsSorted() const;
1832
1833
        /** @copydoc GpuProgramParameters::setNamedConstant(const String&, Real) */
1834
        template <typename T> void setNamedConstant(const String& name, T val)
1835
        {
1836
            setNamedConstant(name, &val, 1);
1837
        }
1838
        /// @overload
1839
        template <int dims, typename T>
1840
        void setNamedConstant(const String& name, const Vector<dims, T>& vec)
1841
        {
1842
            setNamedConstant(name, vec.ptr(), dims);
1843
        }
1844
        /** @copydoc GpuProgramParameters::setNamedConstant(const String& name, const Matrix4& m) */
1845
        void setNamedConstant(const String& name, const Matrix4& m);
1846
        /** @copydoc GpuProgramParameters::setNamedConstant(const String& name, const Matrix4* m, size_t numEntries) */
1847
        void setNamedConstant(const String& name, const Matrix4* m, uint32 numEntries);
1848
        void setNamedConstant(const String& name, const float *val, uint32 count);
1849
        void setNamedConstant(const String& name, const double *val, uint32 count);
1850
        /** @copydoc GpuProgramParameters::setNamedConstant(const String& name, const ColourValue& colour) */
1851
        void setNamedConstant(const String& name, const ColourValue& colour);
1852
        void setNamedConstant(const String& name, const int *val, uint32 count);
1853
        void setNamedConstant(const String& name, const uint *val, uint32 count);
1854
        /// Get a pointer to the 'nth' item in the float buffer
1855
0
        float* getFloatPointer(size_t pos) { _markDirty(); return (float*)&mConstants[pos]; }
1856
        /// Get a pointer to the 'nth' item in the float buffer
1857
0
        const float* getFloatPointer(size_t pos) const { return (const float*)&mConstants[pos]; }
1858
        /// Get a pointer to the 'nth' item in the double buffer
1859
0
        double* getDoublePointer(size_t pos) { _markDirty(); return (double*)&mConstants[pos]; }
1860
        /// Get a pointer to the 'nth' item in the double buffer
1861
0
        const double* getDoublePointer(size_t pos) const { return (const double*)&mConstants[pos]; }
1862
        /// Get a pointer to the 'nth' item in the int buffer
1863
0
        int* getIntPointer(size_t pos) { _markDirty(); return (int*)&mConstants[pos]; }
1864
        /// Get a pointer to the 'nth' item in the int buffer
1865
0
        const int* getIntPointer(size_t pos) const { return (const int*)&mConstants[pos]; }
1866
        /// Get a pointer to the 'nth' item in the uint buffer
1867
0
        uint* getUnsignedIntPointer(size_t pos) { _markDirty(); return (uint*)&mConstants[pos]; }
1868
        /// Get a pointer to the 'nth' item in the uint buffer
1869
0
        const uint* getUnsignedIntPointer(size_t pos) const { return (const uint*)&mConstants[pos]; }
1870
        /// Get a reference to the list of constants
1871
0
        const ConstantList& getConstantList() const { return mConstants; }
1872
        /** Internal method that the RenderSystem might use to store optional data. */
1873
0
        void _setHardwareBuffer(const HardwareBufferPtr& data) { mHardwareBuffer = data; }
1874
        /** Internal method that the RenderSystem might use to store optional data. */
1875
0
        const HardwareBufferPtr& _getHardwareBuffer() const { return mHardwareBuffer; }
1876
        /// upload parameter data to GPU memory. Must have a HardwareBuffer
1877
        void _upload() const;
1878
        /// download data from GPU memory. Must have a writable HardwareBuffer
1879
        void download();
1880
    };
1881
1882
    /** @} */
1883
    /** @} */
1884
}
1885
1886
#include "OgreHeaderSuffix.h"
1887
1888
#endif