Changeset 20889
- Timestamp:
- 11/02/07 21:07:33 (1 year ago)
- Files:
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
juggler/trunk/modules/vrjuggler/doc/getting.started.guide/getting.started.guide.xml
r20882 r20889 774 774 successfully.</para> 775 775 776 <para>On <productname 777 class="registered">Windows</productname>, the Juggler DLLs 778 (<filename>vpr-2_2.dll</filename>, 779 <filename>jccl-1_4.dll</filename>, 780 <filename>vrj-3_0.dll</filename>, etc.) determine on their 781 own where they are installed when they are attached to the 782 application process. As such, the <productname 783 class="registered">Windows</productname> DLLs will 784 automatically set the environment variable(s) that they need 785 to function properly. If an environment variable is already 786 set, then its setting will <emphasis>not</emphasis> be 787 changed by the DLL when it is attached to the application 776 <para>With the release of VR Juggler 2.2.1, it should not be 777 necessary to set <envar>VJ_BASE_DIR</envar> on any platform 778 in order to <emphasis>execute</emphasis> applications. 779 Compiling applications, however, may require the use of 780 <envar>VJ_BASE_DIR</envar>. This varies from application to 781 application.</para> 782 783 <para>The reduced need for <envar>VJ_BASE_DIR</envar> is 784 possible because the Juggler shared libraries determine on 785 their own where they are installed when they are attached to 786 the application process. As such, they will automatically 787 set the environment variable(s) that they need to function 788 properly. If an environment variable is already set, then 789 its setting will <emphasis>not</emphasis> be changed by the 790 shared library when it is attached to the application 788 791 process.</para> 789 792 … … 910 913 911 914 <varlistentry> 915 <term>VJ_DRAW_THREAD_AFFINITY</term> 916 917 <listitem> 918 <para>VR Juggler 3.0 introduced the ability for Linux and 919 IRIX users to direct processor affinity for render threads 920 created by all Draw Managers. The default way of doing this 921 is to create a multi-pipe/multi-threaded configuration and 922 then set the environment variable 923 <envar>VJ_DRAW_THREAD_AFFINITY</envar> to be a 924 space-separated list of integers identifying the processors 925 in the machine. The optimal setting for this environment 926 variable is likely to vary with hardware and with 927 applications. If more render threads are created than there 928 are processors available, the OpenGL Draw Manager starts 929 over at the beginning of the processor ID list.</para> 930 931 <tip> 932 <para>With a multi-processor, multi-core computer, it 933 will generally be best to separate rener threads by 934 processor first and by core second. For example, on a 935 dual processor, dual core machine, a setting of <quote>0 936 2 1 3</quote> is likely to give good results. In this 937 case, render thread 0 will be assigned to processor 0, 938 render thread 1 to processor 2, and so on.</para> 939 </tip> 940 941 <note> 942 <para>It is possible to use a value less than zero for a 943 processor ID when setting this environment variable. 944 Doing so will disable processor affinity for that 945 particular rendering thread.</para> 946 </note> 947 948 <para>Be aware that the use of this environment variable is 949 optional and that application programmers are free to define 950 their own render thread affinity algorithm that may not use 951 this environment variable at all. For more details on how to 952 do this, refer to the VR Juggler <emphasis>Programmer's 953 Guide</emphasis>.</para> 954 </listitem> 955 </varlistentry> 956 957 <varlistentry> 912 958 <term>VJ_CFG_PATH</term> 913 959 juggler/trunk/modules/vrjuggler/doc/programmer.guide/programmer.guide.xml
r20739 r20889 11294 11294 important, interesting, and worthwhile topics nonetheless.</para> 11295 11295 11296 <section> 11297 <title>Customizing Render Thread Processor Affinity</title> 11298 11299 <para>VR Juggler 2.2.1 introduced the feature of adjustable render 11300 thread processor affinity for Linux and IRIX users of the OpenGL 11301 Draw Manager<footnote> 11302 <para>In VR Juggler 3.0, this capability is available to all 11303 Draw Managers, but only the OpenGL Draw Manager takes 11304 advantage. The Direct3D Draw Manager is not currently 11305 multi-threaded.</para> 11306 </footnote>. The default mechanism for defining processor 11307 affinity is based on an environment variable and the use of a 11308 simple round-robin scheme for the case of having more graphics 11309 pipes than processors. More tailored uses of render thread 11310 processor affinity can be achieved by giving the OpenGL Draw 11311 Manager a custom affinity assignment algorithm. That will be the 11312 topic of this section.</para> 11313 11314 <para>The OpenGL Draw Manager class 11315 <classname>vrj::opengl::DrawManager</classname> has a method named 11316 <methodname>setCpuAffinityStrategy()</methodname> that takes as 11317 its argument a callable object. This is encapsulated using a 11318 Boost.Function object of type <type>boost::function<int (const 11319 unsigned int)></type>, which in English is a function that 11320 takes a single constant unsigned integer (the pipe identifier) and 11321 returns a signed integer (the processor identifier). Anything that 11322 can be encapsulated by a Boost.Function object can be used. That 11323 includes a pointer to a C function, a pointer to a static C++ 11324 class member function, a value returned by 11325 <function>boost::bind()</function>, or an instance of a class that 11326 overloads <methodname>operator()</methodname>. This usage 11327 implements the Strategy Pattern where functionality is plugged in 11328 at run time. The default behavior is to use an instance of 11329 <classname>vrj::CpuAffinityFromEnv</classname>, assigned in the 11330 <classname>vrj::opengl::DrawManager</classname> 11331 constructor.</para> 11332 11333 <para>The job of this callable object is to map the pipe 11334 identifier to the processor to which affinity will be assigned for 11335 the render thread of the pipe. The processor identifier is a 11336 signed integer so that a negative value can be used to indicate 11337 that no affinity should be assigned for the render thread of the 11338 pipe. The exact means by which it accomplishes this can vary, and 11339 that is the power of the Strategy Pattern in this context.</para> 11340 11341 <para>To provide a customized processor affinity assignment 11342 algorithm, 11343 <methodname>vrj::opengl::DrawManager::setCpuAffinityStrategy()</methodname> 11344 must be invoked at the correct time. The OpenGL Draw Manager uses 11345 whatever affinity assignment algorithm it has as soon as it 11346 determines that <classname>vrj::opengl::Pipe</classname> objects 11347 need to be created. This is done as part of the VR Juggler 11348 run-time reconfiguration process. Therefore, to guarantee that all 11349 pipes use the customized algorithm, 11350 <methodname>vrj::opengl::DrawManager::setCpuAffinityStrategy()</methodname> 11351 must be called before calling 11352 <methodname>vrj::Kernel::start()</methodname>, the method that 11353 starts the VR Juggler kernel control loop. Since the kernel 11354 control loop is normally started in the application 11355 <function>main()</function> function, the most likely place for a 11356 call to 11357 <methodname>vrj::opengl::DrawManager::setCpuAffinityStrategy()</methodname> 11358 is also in <function>main()</function>. Of course, this can vary 11359 depending on how VR Juggler is being used, so the most important 11360 thing to understand is that it must happen 11361 <emphasis>before</emphasis> 11362 <methodname>vrj::Kernel::start()</methodname> is called.</para> 11363 </section> 11364 11296 11365 <section id="section.custom.delegate"> 11297 11366 <title>Making a Custom <classname>NSApplication</classname>
