About

The Cinema 4D Cinema API provides various functions to handle threads and thread related tasks.

Warning: For Maxon API threading utilities see Threads Manual.

Utility Functions

Various tasks should only be performed from the main thread. For example any GUI interaction or any change of the currently active BaseDocument must only happen from the main thread. To make sure that such code is only executed in the main thread the following functions can be used:

GeIsMainThread(): Returns true if the code is running in the context of the main thread.
GeIsMainThreadAndNoDrawThread(): Returns true if the code is running in the context of the main thread and if the main thread does not execute any viewport drawing.

// This example shows how a context less function can check
// if it is allowed to edit the active document.
 
static maxon::Result<void> SetActiveDocumentTime(const Float time)
{
  // check if the function is called
  // from within the main thread
  if (!GeIsMainThreadAndNoDrawThread())
  {
    CriticalStop();
    return maxon::IllegalStateError(MAXON_SOURCE_LOCATION);
  }
 
  BaseDocument* const doc = GetActiveDocument();
  if (doc == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  doc->SetTime(BaseTime(time));
  EventAdd();
 
  return maxon::OK;
}

GeGetCurrentThreadCount(): Returns the number of threads being used for the current (render) context.
IdentifyThread(): Returns the type of the current thread. Useful to get the current context.
- THREADTYPE::EDITORREDRAW : Editor redraw.
- THREADTYPE::RENDEREDITOR : Editor render.
- THREADTYPE::RENDEREXTERNAL : External render.
GeSleep(): Sleeps for the given time.
StopAllThreads(): Stops all running threads. Needed when an asynchronous dialog reacts to a message (e.g. mouse click) and modifies the document. Never use this in a thread itself or in a function of a NodeData based plugin.
StopDrawViewsThread(): Stops all draw view threads.
GeStopBackgroundThreads(): Stops all running threads of the given class.

Running Systems

GeCheckBackgroundThreadsRunning(): Returns true if a given background thread is running.
CheckIsRunning(): Returns true if the given task is running.
- CHECKISRUNNING::ANIMATIONRUNNING : Animation running.
- CHECKISRUNNING::VIEWDRAWING : View drawing.
- CHECKISRUNNING::EDITORRENDERING : Editor rendering.
- CHECKISRUNNING::EXTERNALRENDERING : External rendering.
- CHECKISRUNNING::PAINTERUPDATING : Painter updating.
- CHECKISRUNNING::MATERIALPREVIEWRUNNING : Material preview running.
- CHECKISRUNNING::EVENTSYSTEM : Event System.
- CHECKISRUNNING::BAKING : Baking.

Note: CheckIsRunning() does not check if the current code is running within the context of the checked task. See IdentifyThread() above.

  // This example checks if the external render thread is running.
  // If so it should stop.
 
  // check if the external renderer ("Picture Viewer") is running
  if (CheckIsRunning(CHECKISRUNNING::EXTERNALRENDERING))
  {
    GeStopBackgroundThreads(BACKGROUNDHANDLER_TYPECLASS_C4D, BACKGROUNDHANDLERFLAGS::RENDEREXTERNAL, nullptr);
  }

Get Threads

These functions are used to obtain certain threads:

GeGetCurrentThreadId(): Returns the unique ID for the current thread.
GeGetCurrentThread(): Returns the current BaseThread. This BaseThread can be passed to functions that require a BaseThread argument to check for stop conditions.
GeGetDummyThread(): Returns a dummy thread. This may be used when a BaseThread argument must be set.
GeGetEscTestThread(): Returns a thread for escape key testing. This may be used when a BaseThread argument must be set.

  // This example will execute the while loop until the "Esc" key is pressed.
 
  BaseThread* const escThread = GeGetEscTestThread();
  if (escThread == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // execute the loop until the escThread signals to stop
  while (!escThread->TestBreak())
  {
    DoSomething();
  }

Table of Contents

About

Utility Functions

Running Systems

Get Threads

Further Reading