afxEffectGroup.cpp

Public Functions

ConsoleDocClass(afxEffectGroupData , "@brief A datablock that describes an Effect <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">Group.\n\n</a>" "<a href="/coding/class/classafxeffectgroupdata/">afxEffectGroupData</a> provides <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> way <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a> adding several effects <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> choreographer as <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> " "group and can be used wherever an <a href="/coding/class/classafxeffectwrapperdata/">afxEffectWrapperData</a> is used. Basically, an " "effect-group is <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> simple list of effect-wrappers. When an effect-group is added <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> " " choreographer, the end result is almost the same as adding all of the group 's " "effect-wrappers directly <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> the choreographer. The <a href="/coding/file/x86unixmain_8cpp/#x86unixmain_8cpp_1a217dbf8b442f20279ea00b898af96f52">main</a> difference is that the " "grouped effects can be turned on and off collectively and created in multiples. " "Effect-groups can also contain other effect- groups, forming <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> hierarchy of <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">effects.\n\n</a>" "A great strength of effect-groups is that they have <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1ad43c3812e6d13e0518d9f8b8f463ffcf">count</a> setting that multiplies " "the number of times the effects in the group are added <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> the owning choreographer " "and this doesn '<a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1aded116371789db1fd63c90ef00c95a3d">t</a> happen until the choreographer instance is created and launched. " "This makes <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> big difference <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a> certain kinds of effects, such as fireworks, that " "tend <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> consist of small groupings of effects that are repeated many times with " "slight variations. With groups, an effect like this has <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> very compact representation " "<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a> transmitting from server <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> clients, that only expands when actually <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">used.\n\n</a>" "Effect-groups with <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1ad43c3812e6d13e0518d9f8b8f463ffcf">count</a> greater than one are extremely useful when some of the " "effects use field substitutions. When an effect-group is expanded, it essentially runs " "through <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a>-loop from 0 <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1ad43c3812e6d13e0518d9f8b8f463ffcf">count</a>-1 and creates <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> <a href="/coding/file/tmm__on_8h/#tmm__on_8h_1a1ac41480eb2e4aadd52252ee550b630a">new</a> set of effect instances each " "time through the loop. For each <a href="/coding/file/tmm__on_8h/#tmm__on_8h_1a1ac41480eb2e4aadd52252ee550b630a">new</a> set of effects, their group-index is set <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> the " "index of this <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a>- loop, which in turn replaces the ## token used in any field " "substitutions in the child effects. In essence, the <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1a2732ab74fa0237854c2ba0f75f88a624">for</a>-loop index becomes <a href="/coding/file/pointer_8h/#pointer_8h_1aeeddce917cf130d62c370b8f216026dd">a</a> parameter " "of the child effects which can be used <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> vary the effects created in each <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">loop.\n\n</a>" " @see <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">afxEffectBaseData\n\n</a>" " @see <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">afxEffectWrapperData\n\n</a>" " @ingroup <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">afxEffects\n</a>" " @ingroup <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">AFX\n</a>" " @ingroup <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">Datablocks\n</a>" )

DefineEngineMethod(afxEffectGroupData , pushEffect , void , (afxEffectBaseData *effect) , "Adds an effect (wrapper or group) <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> an effect-<a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">group.\n\n</a>" "@ingroup AFX" )

DefineEngineMethod(afxEffectGroupData , reset , void , () , "Resets an effect-group datablock during <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">reload.\n\n</a>" "@ingroup AFX" )

IMPLEMENT_CO_DATABLOCK_V1(afxEffectGroupData )

  1
  2
  3//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~~//
  4// Arcane-FX for MIT Licensed Open Source version of Torque 3D from GarageGames
  5// Copyright (C) 2015 Faust Logic, Inc.
  6//
  7// Permission is hereby granted, free of charge, to any person obtaining a copy
  8// of this software and associated documentation files (the "Software"), to
  9// deal in the Software without restriction, including without limitation the
 10// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 11// sell copies of the Software, and to permit persons to whom the Software is
 12// furnished to do so, subject to the following conditions:
 13//
 14// The above copyright notice and this permission notice shall be included in
 15// all copies or substantial portions of the Software.
 16//
 17// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 18// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 19// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 20// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 21// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 22// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 23// IN THE SOFTWARE.
 24//
 25//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~~//
 26
 27#include "afx/arcaneFX.h"
 28
 29#include "console/engineAPI.h"
 30
 31#include "afx/afxEffectGroup.h"
 32
 33//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~~//
 34// afxEffectGroupData::egValidator
 35//
 36// When an effect is added using "addEffect", this validator intercepts the value
 37// and adds it to the dynamic effects list. 
 38//
 39void afxEffectGroupData::egValidator::validateType(SimObject* object, void* typePtr)
 40{
 41  afxEffectGroupData* eff_data = dynamic_cast<afxEffectGroupData*>(object);
 42  afxEffectBaseData** ew = (afxEffectBaseData**)(typePtr);
 43
 44  if (eff_data && ew)
 45  {
 46    eff_data->fx_list.push_back(*ew);
 47    *ew = 0;
 48  }
 49}
 50
 51//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~~//
 52//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~~//
 53// afxEffectGroupData
 54
 55IMPLEMENT_CO_DATABLOCK_V1(afxEffectGroupData);
 56
 57ConsoleDocClass( afxEffectGroupData,
 58   "@brief A datablock that describes an Effect Group.\n\n"
 59
 60   "afxEffectGroupData provides a way for adding several effects to a choreographer as a "
 61   "group and can be used wherever an afxEffectWrapperData is used. Basically, an "
 62   "effect-group is a simple list of effect-wrappers. When an effect-group is added to a "
 63   "choreographer, the end result is almost the same as adding all of the group's "
 64   "effect-wrappers directly to the choreographer. The main difference is that the "
 65   "grouped effects can be turned on and off collectively and created in multiples. "
 66   "Effect-groups can also contain other effect-groups, forming a hierarchy of effects.\n\n"
 67
 68   "A great strength of effect-groups is that they have a count setting that multiplies "
 69   "the number of times the effects in the group are added to the owning choreographer "
 70   "and this doesn't happen until the choreographer instance is created and launched. "
 71   "This makes a big difference for certain kinds of effects, such as fireworks, that "
 72   "tend to consist of small groupings of effects that are repeated many times with "
 73   "slight variations. With groups, an effect like this has a very compact representation "
 74   "for transmitting from server to clients, that only expands when actually used.\n\n"
 75
 76   "Effect-groups with a count greater than one are extremely useful when some of the "
 77   "effects use field substitutions. When an effect-group is expanded, it essentially runs "
 78   "through a for-loop from 0 to count-1 and creates a new set of effect instances each "
 79   "time through the loop. For each new set of effects, their group-index is set to the "
 80   "index of this for-loop, which in turn replaces the ## token used in any field "
 81   "substitutions in the child effects. In essence, the for-loop index becomes a parameter "
 82   "of the child effects which can be used to vary the effects created in each loop.\n\n"
 83
 84   "@see afxEffectBaseData\n\n"
 85   "@see afxEffectWrapperData\n\n"
 86
 87   "@ingroup afxEffects\n"
 88   "@ingroup AFX\n"
 89   "@ingroup Datablocks\n"
 90);
 91
 92afxEffectGroupData::afxEffectGroupData()
 93{
 94  group_enabled = true;
 95  group_count = 1;
 96  idx_offset = 0;
 97  assign_idx = false;
 98
 99  // dummy entry holds effect-wrapper pointer while a special validator
100  // grabs it and adds it to an appropriate effects list
101  dummy_fx_entry = NULL;
102
103  // marked true if datablock ids need to
104  // be converted into pointers
105  do_id_convert = false;
106}
107
108afxEffectGroupData::afxEffectGroupData(const afxEffectGroupData& other, bool temp_clone) : afxEffectBaseData(other, temp_clone)
109{
110  group_enabled = other.group_enabled;
111  group_count = other.group_count;
112  idx_offset = other.idx_offset;
113  assign_idx = other.assign_idx;
114  timing = other.timing;
115  dummy_fx_entry = other.dummy_fx_entry;
116  do_id_convert = other.do_id_convert; // --
117  fx_list = other.fx_list; // -- 
118}
119
120void afxEffectGroupData::reloadReset()
121{
122  fx_list.clear();
123}
124
125void afxEffectGroupData::pack_fx(BitStream* stream, const afxEffectList& fx, bool packed)
126{
127  stream->writeInt(fx.size(), EFFECTS_PER_PHRASE_BITS);
128  for (int i = 0; i < fx.size(); i++)
129    writeDatablockID(stream, fx[i], packed);
130}
131
132void afxEffectGroupData::unpack_fx(BitStream* stream, afxEffectList& fx)
133{
134  fx.clear();
135  S32 n_fx = stream->readInt(EFFECTS_PER_PHRASE_BITS);
136  for (int i = 0; i < n_fx; i++)
137    fx.push_back((afxEffectWrapperData*)(uintptr_t)readDatablockID(stream));
138}
139
140#define myOffset(field) Offset(field, afxEffectGroupData)
141
142void afxEffectGroupData::initPersistFields()
143{
144  addField("groupEnabled",   TypeBool,    myOffset(group_enabled),
145    "...");
146  addField("count",          TypeS32,     myOffset(group_count),
147    "...");
148  addField("indexOffset",    TypeS8,      myOffset(idx_offset),
149    "...");
150  addField("assignIndices",  TypeBool,    myOffset(assign_idx),
151    "...");
152
153  addField("delay",          TypeF32,     myOffset(timing.delay),
154    "...");
155  addField("lifetime",       TypeF32,     myOffset(timing.lifetime),
156    "...");
157  addField("fadeInTime",     TypeF32,     myOffset(timing.fade_in_time),
158    "...");
159  addField("fadeOutTime",    TypeF32,     myOffset(timing.fade_out_time),
160    "...");
161
162  // effect lists
163  // for each of these, dummy_fx_entry is set and then a validator adds it to the appropriate effects list 
164  static egValidator emptyValidator(0);
165  
166  addFieldV("addEffect",  TYPEID<afxEffectBaseData>(),  myOffset(dummy_fx_entry), &emptyValidator,
167    "...");
168
169  Parent::initPersistFields();
170
171  // disallow some field substitutions
172  disableFieldSubstitutions("addEffect");
173}
174
175void afxEffectGroupData::packData(BitStream* stream)
176{
177   Parent::packData(stream);
178
179  stream->writeFlag(group_enabled);
180  stream->write(group_count);
181  stream->write(idx_offset);
182  stream->writeFlag(assign_idx);
183  stream->write(timing.delay);
184  stream->write(timing.lifetime);
185  stream->write(timing.fade_in_time);
186  stream->write(timing.fade_out_time);
187
188  pack_fx(stream, fx_list, mPacked);
189}
190
191void afxEffectGroupData::unpackData(BitStream* stream)
192{
193  Parent::unpackData(stream);
194
195  group_enabled = stream->readFlag();
196  stream->read(&group_count);
197  stream->read(&idx_offset);
198  assign_idx = stream->readFlag();
199  stream->read(&timing.delay);
200  stream->read(&timing.lifetime);
201  stream->read(&timing.fade_in_time);
202  stream->read(&timing.fade_out_time);
203
204  do_id_convert = true;
205  unpack_fx(stream, fx_list);
206}
207
208bool afxEffectGroupData::preload(bool server, String &errorStr)
209{
210  if (!Parent::preload(server, errorStr))
211    return false;
212
213  // Resolve objects transmitted from server
214  if (!server) 
215  {
216    if (do_id_convert)
217    {
218      for (S32 i = 0; i < fx_list.size(); i++)
219      {
220        SimObjectId db_id = SimObjectId((uintptr_t)fx_list[i]);
221        if (db_id != 0)
222        {
223          // try to convert id to pointer
224          if (!Sim::findObject(db_id, fx_list[i]))
225          {
226            Con::errorf(ConsoleLogEntry::General, 
227              "afxEffectGroupData::preload() -- bad datablockId: 0x%x", 
228              db_id);
229          }
230        }
231      }
232      do_id_convert = false;
233    }
234  }
235
236  return true;
237}
238
239void afxEffectGroupData::gather_cons_defs(Vector<afxConstraintDef>& defs)
240{
241  for (S32 i = 0; i < fx_list.size(); i++)
242  {
243    if (fx_list[i])
244      fx_list[i]->gather_cons_defs(defs);
245  }
246}
247
248//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//
249
250DefineEngineMethod(afxEffectGroupData, reset, void, (),,
251                   "Resets an effect-group datablock during reload.\n\n"
252                   "@ingroup AFX")
253{
254  object->reloadReset();
255}
256
257DefineEngineMethod(afxEffectGroupData, pushEffect, void, (afxEffectBaseData* effect),,
258                   "Adds an effect (wrapper or group) to an effect-group.\n\n"
259                   "@ingroup AFX")
260{
261  if (!effect) 
262  {
263    Con::errorf("afxEffectGroupData::pushEffect() -- missing afxEffectWrapperData.");
264    return;
265  }
266  
267  object->fx_list.push_back(effect);
268}
269
270//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~~//
271
272