{"id":13811563,"url":"https://github.com/pure-data/externals-howto","last_synced_at":"2026-03-17T23:34:56.332Z","repository":{"id":15551158,"uuid":"78365714","full_name":"pure-data/externals-howto","owner":"pure-data","description":"How-To write externals for Pd","archived":false,"fork":false,"pushed_at":"2023-12-05T07:26:35.000Z","size":297,"stargazers_count":215,"open_issues_count":3,"forks_count":23,"subscribers_count":13,"default_branch":"master","last_synced_at":"2026-01-02T04:29:03.211Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TeX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pure-data.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-01-08T19:32:15.000Z","updated_at":"2025-12-11T20:43:23.000Z","dependencies_parsed_at":"2023-12-05T08:37:53.686Z","dependency_job_id":null,"html_url":"https://github.com/pure-data/externals-howto","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pure-data/externals-howto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pure-data%2Fexternals-howto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pure-data%2Fexternals-howto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pure-data%2Fexternals-howto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pure-data%2Fexternals-howto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pure-data","download_url":"https://codeload.github.com/pure-data/externals-howto/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pure-data%2Fexternals-howto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30635190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T22:38:22.569Z","status":"ssl_error","status_checked_at":"2026-03-17T22:38:11.804Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T04:00:23.463Z","updated_at":"2026-03-17T23:34:56.310Z","avatar_url":"https://github.com/pure-data.png","language":"TeX","funding_links":[],"categories":["Pure Data external development \u0026 scripting","TeX"],"sub_categories":[],"readme":"#####################################\nHOWTO write an External for Pure Data\n#####################################\n\nPure Data (aka Pd) is a graphical real-time computer-music system that follows the tradition of IRCAM's ISPW-Max.\n\nAlthough plenty of functions are built into Pd, it is sometimes a pain or simply impossible to create a patch with a certain functionality out of the given primitives and combinations of these.\n\nTherefore, Pd can be extended with self made primitives (“objects”) that are written in higher-level programming-languages, like C/C++, Python, lua,...\n\nThis document aims to explain how to write such primitives in C, the popular programming language that was used to implement Pd.\n\n.. |kbd| raw:: html\n\n   \u003ckbd\u003e\n\n.. |nkbd| raw:: html\n\n   \u003c/kbd\u003e\n\nTable of Contents\n*****************\n\n.. contents::\n\ndefinitions and prerequisites\n*****************************\n\nPd refers to the graphical real-time computer music environment\n*Pure Data* by Miller S. Puckette.\n\nTo fully understand this document, it is necessary to be acquainted with Pd and to have a general understanding of programming techniques especially in C.\n\nTo write externals yourself, a C compiler that supports the ANSI C standard,\nlike the *GNU C compiler* (gcc) on Linux systems or\n*Visual C++* on Windows platforms, will be necessary.\n\nclasses, instances, objects\n===========================\n\nPd is written in the C programming language.\nDue to its graphical nature, Pd is an *object-oriented* system.\nUnfortunately, C does not support the use of classes very well.\nThus the resulting source code is not as elegant as C++ code would be, for instance.\n\nIn this document, the expression *class* refers to the realisation of a concept combining data and manipulators on this data.\n\nConcrete *instances of a class* are called *objects*.\n\ninternals, externals and libraries\n==================================\n\nTo avoid confusion of ideas, the expressions *internal*, *external* and *library* should be explained here.\n\nInternal\n--------\n\nAn *internal* is a class that is built into Pd.\nPlenty of primitives, such as “+”, “pack” or “sig” are *internals*.\n\nExternal\n--------\n\nAn *external* is a class that is not built into Pd but is loaded at runtime.\nOnce loaded into Pd’s memory, *externals* cannot be distinguished from *internals* any more.\n\nLibrary\n-------\n\nA *library* is a collection of *externals* that are compiled into a\nsingle binary file.\n\n*Library* files must follow a system-dependent naming convention:\n\n+-----------------+-------------------------+----------------------+\n|Operating System | CPU-architecture        | filename             |\n+=================+=========================+======================+\n| Linux           | *unspecified*           | ``my_lib.pd_linux``  |\n|                 | (any architecture)      |                      |\n+-----------------+-------------------------+----------------------+\n| Linux           | i386 (Intel/AMD 32bit)  | ``my_lib.l_i386``    |\n+-----------------+-------------------------+----------------------+\n| Linux           | amd64 (Intel/AMD 64bit) | ``my_lib.l_amd64``   |\n+-----------------+-------------------------+----------------------+\n| Linux           | arm (e.g. RaspberryPi)  | ``my_lib.l_arm``     |\n+-----------------+-------------------------+----------------------+\n| Linux           | arm64                   | ``my_lib.l_arm64``   |\n+-----------------+-------------------------+----------------------+\n| macOS           | *unspecified*           | ``my_lib.pd_darwin`` |\n|                 | (any architecture)      |                      |\n+-----------------+-------------------------+----------------------+\n| macOS           | fat (multiple archs)    | ``my_lib.d_fat``     |\n+-----------------+-------------------------+----------------------+\n| macOS           | PowerPC                 | ``my_lib.d_ppc``     |\n+-----------------+-------------------------+----------------------+\n| macOS           | i386 (Intel 32bit)      | ``my_lib.d_i386``    |\n+-----------------+-------------------------+----------------------+\n| macOS           | amd64 (Intel 64bit)     | ``my_lib.d_amd64``   |\n+-----------------+-------------------------+----------------------+\n| macOS           | arm64 (Apple Silicon)   | ``my_lib.d_arm64``   |\n+-----------------+-------------------------+----------------------+\n| Windows         | *unspecified*           | ``my_lib.dll``       |\n|                 | (any architecture)      |                      |\n+-----------------+-------------------------+----------------------+\n| Windows         | i386 (Intel/AMD 32bit)  | ``my_lib.m_i386``    |\n+-----------------+-------------------------+----------------------+\n| Windows         | amd64 (Intel/AMD 64bit) | ``my_lib.m_amd64``   |\n+-----------------+-------------------------+----------------------+\n\n\nThe simplest form of a *library* includes exactly one *external* bearing the same name as the *library*.\n\nUnlike *externals*, *libraries* can be imported by Pd with special operations.\nAfter a *library* has been imported, all included *externals* have been loaded into memory and are available as objects.\n\nPd supports a few ways to import *libraries*:\n\n-  via the command-line option “-lib my\\_lib”\n\n-  by creating a “declare -lib my\\_lib” object\n\n-  by creating a “my\\_lib” object\n\nThe first method loads a *library* when Pd is started.\nThis method is preferably used for *libraries* that contain several *externals*.\n\nThe other method should be used for *libraries* that contain exactly one\n*external* bearing the same name. Pd checks first, whether a class named\n“my\\_lib” is already loaded. If this is not the case [#]_, all paths are\nsearched for a file called “my\\_lib.pd\\_linux” [#]_. If such file is\nfound, all included *externals* are loaded into memory by calling a\n``my_lib_setup()`` function. After loading, a “my\\_lib” class is (again)\nlooked for as a (newly loaded) *external*. If so, an instance of this\nclass is created, else the instantiation fails and an error is printed.\nAnyhow, all *external* classes declared in the *library* are loaded by\nnow.\n\n.. [#] If a class “my\\_lib” is already existent, an object “my\\_lib” will be instantiated and the procedure is done. Thus, no *library* has been loaded. Therefore no *library* that is named like an already used class name like, say, “abs”, can be loaded.\n\n.. [#] or other system-dependent filename extensions (s.a.)\n\n\nWriting externals\n*****************\n\nmy first external: helloworld\n=============================\n\nUsually the first attempt at learning a programming language is\na “hello world” application.\n\nIn our case, we will create an object class that prints the line\n“Hello world !!” to the standard error every time it is triggered with a\n“bang” message.\n\nthe interface to Pd\n-------------------\n\nTo write a Pd external, a well-defined interface is needed. This is\nprovided by the header file “m\\_pd.h”.\n\n::\n\n    #include \"m_pd.h\"\n\na class and its data space\n--------------------------\n\nFirst a new class must be prepared and the data space for this class\nmust be defined.\n\n::\n\n    static t_class *helloworld_class;\n\n    typedef struct _helloworld {\n      t_object  x_obj;\n    } t_helloworld;\n\n``helloworld_class`` is going to be a pointer to the new class.\n\nStructure ``t_helloworld`` (of type ``struct _helloworld``) is the data\nspace of the class.\n\nAn absolutely necessary element of the data space is a variable of\ntype ``t_object``, which is used to store internal object properties\nlike the graphical presentation of the object or data about inlets and\noutlets.\n\n``t_object`` must be the first entry in the structure!\n\nBecause a simple “hello world” application needs no variables,\nthe structure is empty apart from the ``t_object``.\n\nmethod space\n------------\n\nIn addition to the data space, a class needs a set of manipulators\n(methods) to manipulate the data with.\n\nIf a message is sent to an instance of our class, a method is called.\nThese methods are the interfaces to Pd's message system.\nOn principle, they have no return argument and are therefore of type\n``void``.\n\n::\n\n    void helloworld_bang(t_helloworld *x)\n    {\n      post(\"Hello world !!\");\n    }\n\nThis method takes an argument of type ``t_helloworld``, which would\nenable us to manipulate the data space.\n\nBut since we only want to output “Hello world !!” (and, by the way, our data\nspace is quite sparse), we simply ignore the argument.\n\nThe ``post(char *c,...)`` function sends a string to the standard error.\nA carriage return is added automatically. Apart from this, the\n``post`` function works like the C ``printf()`` function.\n\ngeneration of a new class\n-------------------------\n\nTo generate a new class, information on the data space and the method\nspace of this class must be passed to Pd when a library is loaded.\n\nOn loading a new library named “my\\_lib”, Pd tries to call a “my\\_lib\\_setup()”\nfunction. This function (or functions called by it) declares\nthe new classes and their properties. It is only called once, when the\nlibrary is loaded. If the function call fails (e.g., because no function\nof the specified name is present) no external of the library will be\nloaded.\n\n::\n\n    void helloworld_setup(void)\n    {\n      helloworld_class = class_new(gensym(\"helloworld\"),\n            (t_newmethod)helloworld_new,\n            0, sizeof(t_helloworld),\n            CLASS_DEFAULT, 0);\n\n      class_addbang(helloworld_class, helloworld_bang);\n    }\n\nclass\\_new\n^^^^^^^^^^\n\nFunction ``class_new`` creates a new class and returns a pointer to\nthis prototype.\n\nThe first argument is the symbolic name of the class.\n\nThe next two arguments define the constructor and destructor of the class.\n\nWhenever a class object is created in a Pd patch,\nclass constructor ``(t_newmethod)helloworld_new`` instantiates the object\nand initialises the data space.\n\nWhenever an object is destroyed (either by closing the containing patch or by deleting the object from the patch)\nthe destructor frees the dynamically reserved memory.\nThe allocated memory for the static data space is automatically reserved and freed.\n\nTherefore we need not provide a destructor in this example, the\nargument is set to “0”.\n\nTo enable Pd to reserve and free enough memory for the static data\nspace, the size of the data structure must be passed as the fourth\nargument.\n\nThe fifth argument has influence on the graphical representation of the\nclass objects. The default value is ``CLASS_DEFAULT`` or simply “0”.\n\nThe remaining arguments define the arguments of an object and its type.\n\nUp to six numeric and symbolic object arguments can be defined via\n``A_DEFFLOAT`` and ``A_DEFSYMBOL``. If more arguments are to be passed\nto the object, or if the order of atom types should be more flexible,\n``A_GIMME`` can be used for passing an arbitrary list of atoms.\n\nThe list of object arguments is terminated by “0”. In this example we\nhave no object arguments at all for the class.\n\nclass\\_addbang\n^^^^^^^^^^^^^^\n\nWe still need to add a method space to the class.\n\n``class_addbang`` adds a method for a “bang” message to the class that\nis defined in the first argument. The added method is defined in the\nsecond argument.\n\nconstructor: instantiation of an object\n---------------------------------------\n\nEach time, an object is created in a Pd patch, the constructor that is\ndefined with the ``class_new`` function, generates a new instance of the\nclass.\n\nThe constructor must be of type ``void *``.\n\n::\n\n    void *helloworld_new(void)\n    {\n      t_helloworld *x = (t_helloworld *)pd_new(helloworld_class);\n\n      return (void *)x;\n    }\n\nThe arguments of the constructor method depend on the object arguments\ndefined with ``class_new``.\n\n+--------------------------+-------------------------------------------+\n| ``class_new`` argument   | constructor argument                      |\n+==========================+===========================================+\n| ``A_DEFFLOAT``           | ``t_floatarg f``                          |\n+--------------------------+-------------------------------------------+\n| ``A_DEFSYMBOL``          | ``t_symbol *s``                           |\n+--------------------------+-------------------------------------------+\n| ``A_GIMME``              | ``t_symbol *s, int argc, t_atom *argv``   |\n+--------------------------+-------------------------------------------+\n\nBecause there are no object arguments for our “hello world” class,\nthe constructor has none too.\n\nFunction ``pd_new`` reserves memory for the data space, initialises\nthe variables that are internal to the object and returns a pointer to\nthe data space.\n\nThe type cast to the data space is necessary.\n\nNormally, the constructor would initialise the object variables.\nHowever, since we have none, this is not necessary.\n\nThe constructor must return a pointer to the instantiated data space.\nIf it returns ``NULL``, Pd think the object did not create.\n\nthe code: helloworld\n--------------------\n\n::\n\n    #include \"m_pd.h\"\n\n    static t_class *helloworld_class;\n\n    typedef struct _helloworld {\n      t_object  x_obj;\n    } t_helloworld;\n\n    void helloworld_bang(t_helloworld *x)\n    {\n      post(\"Hello world !!\");\n    }\n\n    void *helloworld_new(void)\n    {\n      t_helloworld *x = (t_helloworld *)pd_new(helloworld_class);\n\n      return (void *)x;\n    }\n\n    void helloworld_setup(void) {\n      helloworld_class = class_new(gensym(\"helloworld\"),\n            (t_newmethod)helloworld_new,\n            0, sizeof(t_helloworld),\n            CLASS_DEFAULT, 0);\n      class_addbang(helloworld_class, helloworld_bang);\n    }\n\na simple external: counter\n==========================\n\nNow we want to realize a simple counter as an external.\nA “bang” trigger outputs the counter value on the outlet\nand afterwards increases the counter value by 1.\n\nThis class is similar to the previous one, but the data space is\nextended by variable “counter” and the result is written as a message\nto an outlet instead of a string to the standard error.\n\nobject variables\n----------------\n\nOf course, a counter needs a state variable to store the actual\ncounter value.\n\nState variables that belong to class instances belong to the data space.\n\n::\n\n    typedef struct _counter {\n      t_object  x_obj;\n      int i_count;\n    } t_counter;\n\nInteger variable ``i_count`` stores the counter value.\n\nobject arguments\n----------------\n\nIt is quite useful for a counter, if an initial value can be defined by\nthe user. Therefore this initial value should be passed to the object at\ncreation time.\n\n::\n\n    void counter_setup(void) {\n      counter_class = class_new(gensym(\"counter\"),\n            (t_newmethod)counter_new,\n            0, sizeof(t_counter),\n            CLASS_DEFAULT,\n            A_DEFFLOAT, 0);\n\n      class_addbang(counter_class, counter_bang);\n    }\n\nSo we have an additional argument in function ``class_new``:\n``A_DEFFLOAT`` tells Pd that the object needs one argument of the type\n``t_floatarg``.\nIf no argument is passed, this will default to “0”.\n\nconstructor\n-----------\n\nThe constructor has some new tasks.\nOn the one hand, a variable value must be initialised,\non the other hand, an outlet for the object has to be created.\n\n::\n\n    void *counter_new(t_floatarg f)\n    {\n      t_counter *x = (t_counter *)pd_new(counter_class);\n\n      x-\u003ei_count=f;\n      outlet_new(\u0026x-\u003ex_obj, \u0026s_float);\n\n      return (void *)x;\n    }\n\nThe constructor method has one argument of type ``t_floatarg`` as\ndeclared in the setup function by ``class_new``. This argument is used to\ninitialise the counter.\n\nA new outlet is created with function ``outlet_new``. The first\nargument is a pointer to the internals of the object the new outlet is\ncreated for.\n\nThe second argument is a symbolic description of the outlet type. Since\nour counter should output numeric values it is of type “float”.\n\n``outlet_new`` returns a pointer to the new outlet and saves this very\npointer in the ``t_object`` variable ``x_obj.ob_outlet``. If only one\noutlet is used, the pointer need not additionally be stored in the data\nspace. If more than one outlets are used, the pointers must be stored\nin the data space, because the ``t_object`` variable can only hold one\noutlet pointer.\n\nthe counter method\n------------------\n\nWhen triggered, the counter's value should be sent to the outlet and\nafterwards be incremented by 1.\n\n::\n\n    void counter_bang(t_counter *x)\n    {\n      t_float f=x-\u003ei_count;\n      x-\u003ei_count++;\n      outlet_float(x-\u003ex_obj.ob_outlet, f);\n    }\n\nFunction ``outlet_float`` sends a floating point value (second argument)\nto the outlet specified by the first argument.\n\nWe first store the counter in a floating point buffer.\nAfterwards the counter is incremented and not before that the buffer variable\nis sent to the outlet.\n\nWhat appears to be unnecessary at first glance, makes sense after\nfurther inspection: the buffer variable has been declared as a\n``t_float``, since ``outlet_float`` expects a floating point value and a\ntypecast is inevitable.\n\nIf the counter value was sent to the outlet before being incremented,\nthis could result in unwanted (though well defined) behaviour: if the\ncounter outlet directly triggered its own inlet, the counter method\nwould be called although the counter value was not yet incremented.\nNormally this is not what we want.\n\nThe same (correct) result could of course be obtained with a single\nline, but this would obscure the *reentrant* problem.\n\nthe code: counter\n-----------------\n\n::\n\n    #include \"m_pd.h\"\n\n    static t_class *counter_class;\n\n    typedef struct _counter {\n      t_object  x_obj;\n      int i_count;\n    } t_counter;\n\n    void counter_bang(t_counter *x)\n    {\n      t_float f=x-\u003ei_count;\n      x-\u003ei_count++;\n      outlet_float(x-\u003ex_obj.ob_outlet, f);\n    }\n\n    void *counter_new(t_floatarg f)\n    {\n      t_counter *x = (t_counter *)pd_new(counter_class);\n\n      x-\u003ei_count=f;\n      outlet_new(\u0026x-\u003ex_obj, \u0026s_float);\n\n      return (void *)x;\n    }\n\n    void counter_setup(void) {\n      counter_class = class_new(gensym(\"counter\"),\n            (t_newmethod)counter_new,\n            0, sizeof(t_counter),\n            CLASS_DEFAULT,\n            A_DEFFLOAT, 0);\n\n      class_addbang(counter_class, counter_bang);\n    }\n\na complex external: counter\n===========================\n\nThe simple counter of the previous chapter can easily be extended to\nmore complexity. It might be quite useful to be able to reset the\ncounter to an initial value, to set upper and lower boundaries and to\ncontrol the step width. Each overrun should send a “bang” message to a\nsecond outlet and reset the counter to the initial value.\n\nextended data space\n-------------------\n\n::\n\n    typedef struct _counter {\n      t_object  x_obj;\n      int i_count;\n      t_float step;\n      int i_down, i_up;\n      t_outlet *f_out, *b_out;\n    } t_counter;\n\nThe data space has been extended to hold variables for step width and upper and lower boundaries.\nFurthermore pointers for two outlets have been added.\n\nextension of the class\n----------------------\n\nThe new class objects should have methods for different messages,\nlike “set” and “reset”.\nTherefore the method space must be extended too.\n\n::\n\n      counter_class = class_new(gensym(\"counter\"),\n            (t_newmethod)counter_new,\n            0, sizeof(t_counter),\n            CLASS_DEFAULT, \n            A_GIMME, 0);\n\nClass generator ``class_new`` has been extended by the argument ``A_GIMME``.\nThis enables a dynamic number of arguments to be passed at object instantiation.\n\n::\n\n      class_addmethod(counter_class,\n            (t_method)counter_reset,\n            gensym(\"reset\"), 0);\n\n``class_addmethod`` adds a method for an arbitrary selector to a class.\n\nThe first argument is the class the method (second argument) will be added to.\n\nThe third argument is the symbolic selector that should be associated with the method.\n\nThe remaining “0”-terminated arguments describe the list of atoms that follows the selector.\n\n::\n\n      class_addmethod(counter_class,\n            (t_method)counter_set, gensym(\"set\"),\n            A_DEFFLOAT, 0);\n      class_addmethod(counter_class,\n            (t_method)counter_bound, gensym(\"bound\"),\n            A_DEFFLOAT, A_DEFFLOAT, 0);\n\nA method for “set” followed by a numerical value is added, as well as a method for the selector “bound” followed by two numerical values.\n\n::\n\n      class_sethelpsymbol(counter_class, gensym(\"help-counter\"));\n\nIf a Pd object is right-clicked, a help patch describing the\nobject's class can be opened.\nBy default, this patch is located in directory “\\ *doc/5.reference/*\\ ”\nand is named like the symbolic class name.\n\nAn alternative help patch can be defined using function ``class_sethelpsymbol``.\n\nconstruction of in- and outlets\n-------------------------------\n\nWhen creating the object, several arguments should be passed by the user.\n\n::\n\n    void *counter_new(t_symbol *s, int argc, t_atom *argv)\n\nBecause of the declaration of arguments in function ``class_new``\nwith ``A_GIMME``, the constructor has the following arguments:\n\n+--------------------+------------------------------------------------+\n| ``t_symbol *s``    | the symbolic name used for object creation     |\n+--------------------+------------------------------------------------+\n| ``int argc``       | the number of arguments passed to the object   |\n+--------------------+------------------------------------------------+\n| ``t_atom *argv``   | a pointer to a list of argc atoms              |\n+--------------------+------------------------------------------------+\n\n::\n\n      t_float f1=0, f2=0;\n\n      x-\u003estep=1;\n      switch(argc){\n      default:\n      case 3:\n        x-\u003estep=atom_getfloat(argv+2);\n      case 2:\n        f2=atom_getfloat(argv+1);\n      case 1:\n        f1=atom_getfloat(argv);\n        break;\n      case 0:\n        break;\n      }\n      if (argc\u003c2)f2=f1;\n      x-\u003ei_down = (f1\u003cf2)?f1:f2;\n      x-\u003ei_up   = (f1\u003ef2)?f1:f2;\n\n      x-\u003ei_count=x-\u003ei_down;\n\nIf three arguments are passed, these should be the *lower boundary*, the *upper boundary* and the *step width*.\n\nIf only two arguments are passed, the step width defaults to “1”.\nIf only one argument is passed, this should be the *initial value* of the\ncounter with step width of “1”.\n\n::\n\n      inlet_new(\u0026x-\u003ex_obj, \u0026x-\u003ex_obj.ob_pd,\n            gensym(\"list\"), gensym(\"bound\"));\n\nFunction ``inlet_new`` creates a new “active” inlet.\n“Active” means, that a class method is called each time a message is sent\nto an “active” inlet.\n\nDue to the software architecture, the first inlet is always “active”.\n\nThe first two arguments of the ``inlet_new`` function are pointers to\nthe internals of the object and to the graphical presentation of the\nobject.\n\nThe symbolic selector that is specified by the third argument is to be substituted by another symbolic selector (fourth argument) for this inlet.\n\nBecause of this substitution of selectors, a message on a certain right inlet can be treated as a message with a certain selector on the leftmost inlet.\n\nThis means:\n\n-  The substituting selector must be declared by ``class_addmethod``\n   in the setup function.\n\n-  It is possible to simulate a certain right inlet, by sending a message with this inlet’s selector to the leftmost inlet.\n\n-  It is not possible to add methods for more than one selector to a right inlet.\n   Particularly, it is not possible to add a universal method for arbitrary selectors to a right inlet.\n\n::\n\n      floatinlet_new(\u0026x-\u003ex_obj, \u0026x-\u003estep);\n\n``floatinlet_new`` generates a new “passive” inlet for numerical values.\n“Passive” inlets allow parts of the data space memory to be written\ndirectly from outside. Therefore it is not possible to check for illegal\ninputs.\n\nThe first argument is a pointer to the internal infrastructure of the\nobject. The second argument is the address in the data space memory,\nwhere other objects can write too.\n\n“Passive” inlets can be created for pointers, symbolic or numerical (floating point [#]_ ) values.\n\n\n::\n\n      x-\u003ef_out = outlet_new(\u0026x-\u003ex_obj, \u0026s_float);\n      x-\u003eb_out = outlet_new(\u0026x-\u003ex_obj, \u0026s_bang);\n\nThe pointers returned by ``outlet_new`` must be saved in the\nclass data space to be used later by the outlet functions.\n\nThe order of the generation of inlets and outlets is important, since it corresponds to the order of inlets and outlets in the graphical representation of the object.\n\n.. [#] That’s why the step width of the classdata space is declared as t\\_float.\n\nextended method space\n---------------------\n\nThe method for the “bang” message must fulfill the more complex tasks.\n\n::\n\n    void counter_bang(t_counter *x)\n    {\n      t_float f=x-\u003ei_count;\n      int step = x-\u003estep;\n      x-\u003ei_count+=step;\n      if (x-\u003ei_down-x-\u003ei_up) {\n        if ((step\u003e0) \u0026\u0026 (x-\u003ei_count \u003e x-\u003ei_up)) {\n          x-\u003ei_count = x-\u003ei_down;\n          outlet_bang(x-\u003eb_out);\n        } else if (x-\u003ei_count \u003c x-\u003ei_down) {\n          x-\u003ei_count = x-\u003ei_up;\n          outlet_bang(x-\u003eb_out);\n        }\n      }\n      outlet_float(x-\u003ef_out, f);\n    }\n\nEach outlet is identified by the ``outlet_...`` functions via the\npointer to this outlets.\n\nThe remaining methods still need to be implemented:\n\n::\n\n    void counter_reset(t_counter *x)\n    {\n      x-\u003ei_count = x-\u003ei_down;\n    }\n\n    void counter_set(t_counter *x, t_floatarg f)\n    {\n      x-\u003ei_count = f;\n    }\n\n    void counter_bound(t_counter *x, t_floatarg f1, t_floatarg f2)\n    {\n      x-\u003ei_down = (f1\u003cf2)?f1:f2;\n      x-\u003ei_up   = (f1\u003ef2)?f1:f2;\n    }\n\nthe code: counter\n-----------------\n\n::\n\n    #include \"m_pd.h\"\n\n    static t_class *counter_class;\n\n    typedef struct _counter {\n      t_object  x_obj;\n      int i_count;\n      t_float step;\n      int i_down, i_up;\n      t_outlet *f_out, *b_out;\n    } t_counter;\n\n    void counter_bang(t_counter *x)\n    {\n      t_float f=x-\u003ei_count;\n      int step = x-\u003estep;\n      x-\u003ei_count+=step;\n\n      if (x-\u003ei_down-x-\u003ei_up) {\n        if ((step\u003e0) \u0026\u0026 (x-\u003ei_count \u003e x-\u003ei_up)) {\n          x-\u003ei_count = x-\u003ei_down;\n          outlet_bang(x-\u003eb_out);\n        } else if (x-\u003ei_count \u003c x-\u003ei_down) {\n          x-\u003ei_count = x-\u003ei_up;\n          outlet_bang(x-\u003eb_out);\n        }\n      }\n\n      outlet_float(x-\u003ef_out, f);\n    }\n\n    void counter_reset(t_counter *x)\n    {\n      x-\u003ei_count = x-\u003ei_down;\n    }\n\n    void counter_set(t_counter *x, t_floatarg f)\n    {\n      x-\u003ei_count = f;\n    }\n\n    void counter_bound(t_counter *x, t_floatarg f1, t_floatarg f2)\n    {\n      x-\u003ei_down = (f1\u003cf2)?f1:f2;\n      x-\u003ei_up   = (f1\u003ef2)?f1:f2;\n    }\n\n    void *counter_new(t_symbol *s, int argc, t_atom *argv)\n    {\n      t_counter *x = (t_counter *)pd_new(counter_class);\n      t_float f1=0, f2=0;\n\n      x-\u003estep=1;\n      switch(argc){\n      default:\n      case 3:\n        x-\u003estep=atom_getfloat(argv+2);\n      case 2:\n        f2=atom_getfloat(argv+1);\n      case 1:\n        f1=atom_getfloat(argv);\n        break;\n      case 0:\n        break;\n      }\n      if (argc\u003c2)f2=f1;\n\n      x-\u003ei_down = (f1\u003cf2)?f1:f2;\n      x-\u003ei_up   = (f1\u003ef2)?f1:f2;\n\n      x-\u003ei_count=x-\u003ei_down;\n\n      inlet_new(\u0026x-\u003ex_obj, \u0026x-\u003ex_obj.ob_pd,\n            gensym(\"list\"), gensym(\"bound\"));\n      floatinlet_new(\u0026x-\u003ex_obj, \u0026x-\u003estep);\n\n      x-\u003ef_out = outlet_new(\u0026x-\u003ex_obj, \u0026s_float);\n      x-\u003eb_out = outlet_new(\u0026x-\u003ex_obj, \u0026s_bang);\n\n      return (void *)x;\n    }\n\n    void counter_setup(void) {\n      counter_class = class_new(gensym(\"counter\"),\n            (t_newmethod)counter_new,\n            0, sizeof(t_counter),\n            CLASS_DEFAULT, \n            A_GIMME, 0);\n\n      class_addbang  (counter_class, counter_bang);\n      class_addmethod(counter_class,\n            (t_method)counter_reset, gensym(\"reset\"), 0);\n      class_addmethod(counter_class, \n            (t_method)counter_set, gensym(\"set\"),\n            A_DEFFLOAT, 0);\n      class_addmethod(counter_class,\n            (t_method)counter_bound, gensym(\"bound\"),\n            A_DEFFLOAT, A_DEFFLOAT, 0);\n\n      class_sethelpsymbol(counter_class, gensym(\"help-counter\"));\n    }\n\na signal-external: xfade~\n=========================\n\nSignal classes are normal Pd classes, that offer additional\nmethods for signals.\n\nAll methods and concepts that can be realized with normal object classes can therefore be realized with signal classes too.\n\nPer agreement, the symbolic names of signal classes end with a tilde .\n\nThe class “xfade” shall demonstrate, how signal classes are written.\n\nA signal on the left inlet is crossfaded with a signal on the second inlet.\nThe mixing factor between 0 and 1 is defined via a ``t_float``-message\nto the third inlet.\n\nvariables of a signal class\n---------------------------\n\nSince a signal class is only an extended normal class,\nthere are no principal differences between the data spaces.\n\n::\n\n    typedef struct _xfade_tilde {\n      t_object x_obj;\n\n      t_float x_pan;\n      t_float f;\n\n      t_inlet *x_in2;\n      t_inlet *x_in3;\n\n      t_outlet*x_out;\n\n    } t_xfade_tilde;\n\nOnly one variable ``x_pan`` for the *mixing factor* of the crossfade function\nis needed.\n\nThe other variable, ``f``, is needed whenever a signal inlet is needed too.\nIf no signal but only a float message is present at a signal inlet,\nthis variable is used to automatically convert the float to signal.\n\nFinally, we have members ``x_in2``, ``x_in3`` and ``x_out``,\nwhich are needed to store handles to the various extra inlets (resp. outlets)\nof the object.\n\nsignal classes\n--------------\n\n::\n\n    void xfade_tilde_setup(void) {\n      xfade_tilde_class = class_new(gensym(\"xfade~\"),\n            (t_newmethod)xfade_tilde_new,\n            (t_method)xfade_tilde_free,\n            sizeof(t_xfade_tilde),\n            CLASS_DEFAULT, \n            A_DEFFLOAT, 0);\n\n      class_addmethod(xfade_tilde_class,\n            (t_method)xfade_tilde_dsp, gensym(\"dsp\"), A_CANT, 0);\n      CLASS_MAINSIGNALIN(xfade_tilde_class, t_xfade_tilde, f);\n    }\n\nSomething has changed with the ``class_new`` function:\nthe third argument specifies a “free method” (aka *destructor*),\nwhich is called whenever an instance of the object is to be deleted\n(just like the “new method” is called whenever an instance is to be created).\nIn the prior examples this was set to ``0`` (meaning: we don’t care),\nbut in this example we want to clean up some resources when we don’t\nneed them any more.\n\nMore interestingly, a method for signal processing must be provided\nby each signal class.\n\nWhenever Pd’s audio engine is started, a message with the selector “dsp”\nis sent to each object.\nEach class that has a method for the “dsp” message is recognised\nas a signal class.\n*Always* mark the arguments following the “dsp” selector as ``A_CANT``,\nas this will make it impossible to manually send an *illegal* ``dsp``\nmessage to the object, triggering a crash.\n\nSignal classes that want to provide signal inlets\nmust declare this via the ``CLASS_MAINSIGNALIN`` macro.\nThis enables signals at the first (default) inlet.\nIf more than one signal inlet is needed,\nthey must be created explicitly in the constructor method.\n\nInlets that are declared as signal inlets\ncannot provide methods for ``t_float`` messages any longer.\n\nThe first argument of the macro is a pointer to the signal class.\nThe second argument is the type of the class’ data space.\n\nThe last argument is a dummy variable out of the data space\nthat is needed to replace nonexisting signal at the (first)\nsignal inlet with ``t_float``-messages.\n\nconstruction of signal inlets and outlets\n-----------------------------------------\n\n::\n\n    void *xfade_tilde_new(t_floatarg f)\n    {\n      t_xfade_tilde *x = (t_xfade_tilde *)pd_new(xfade_tilde_class);\n\n      x-\u003ex_pan = f;\n\n      x-\u003ex_in2 = inlet_new(\u0026x-\u003ex_obj, \u0026x-\u003ex_obj.ob_pd, \u0026s_signal, \u0026s_signal);\n      x-\u003ex_in3 = floatinlet_new (\u0026x-\u003ex_obj, \u0026x-\u003ex_pan);\n\n      x-\u003ex_out = outlet_new(\u0026x-\u003ex_obj, \u0026s_signal);\n\n      return (void *)x;\n    }\n\nAdditional signal inlets are added like other inlets, using\nfunction ``inlet_new``. The last two arguments are references to the\n“signal” symbolic selector in the lookup table.\n\nSignal outlets are also created like normal (message) outlets, by\nsetting the outlet selector to “signal”.\n\nThe newly created inlets/outlets are “user-allocated” data. Pd will keep\ntrack of all the resources it automatically creates (like the default\ninlet), and will eventually free these resources once they are no longer\nneeded. However, if we request “extra” resources (like the additional\ninlets/outlets in this example; or - more commonly - memory that is\nallocated via ``malloc`` or similar), we ourselves must make sure\nthat these resources are freed when no longer needed. If we fail to do\nso, we will invariably cause a dreaded *memory leak*.\n\nTherefore, we store the “handles” to the newly created inlets/outlets as\nreturned by the ``..._new`` functions for later use.\n\nDSP methods\n-----------\n\nWhenever Pd’s audio engine is turned on, all signal objects declare\ntheir perform routines that are to be added to the DSP tree.\n\nThe “dsp” method has two arguments, the pointer to the class data space,\nand a pointer to an array of signals. The signal array consists of the\ninput signals (from left to right) and then the output signals (from\nleft to right).\n\n::\n\n    void xfade_tilde_dsp(t_xfade_tilde *x, t_signal **sp)\n    {\n      dsp_add(xfade_tilde_perform, 5, x,\n              sp[0]-\u003es_vec, sp[1]-\u003es_vec, sp[2]-\u003es_vec, sp[0]-\u003es_n);\n    }\n\n``dsp_add`` adds a *perform* function (as declared in the first argument)\nto the DSP tree.\n\nThe second argument is the number of the following pointers to diverse variables.\nWhich pointers to which variables are passed is not limited.\n\nHere, sp[0] is the first input signal, sp[1] represents the second\ninput signal and sp[2] points to the output signal.\n\nStructure ``t_signal`` contains a pointer to its signal vector\n``().s_vec`` (an array of samples of type ``t_sample``), and the length\nof this signal vector ``().s_n``.\n\nSince all the signal vectors in a patch (not including its subpatches) are\nof the same length, it is sufficient to get the length of one of these\nvectors.\n\nSince an object doesn't know its *perform* function's signal vector\nlength until the \"dsp\" method, this would be the place to allocate\ntemporary buffers to store intermediate dsp computations.\nSee: *getbytes*.\n\nperform function\n----------------\n\nThe perform function is the DSP heart of each signal class.\n\nA pointer to an array of pointers (really: pointer sized integers)\nis passed to it.\nThis array contains the pointers that were passed via ``dsp_add``,\nwhich must be cast back to their real type.\n\nThe perform function must return an address,\nthat is just behind the stored pointers of the function.\nThis means that the return argument equals the argument of the perform function\nplus the number of pointer variables (as declared as the second argument of\n``dsp_add``) plus one.\n\n::\n\n    t_int *xfade_tilde_perform(t_int *w)\n    {\n      t_xfade_tilde *x = (t_xfade_tilde *)(w[1]);\n      t_sample    *in1 =      (t_sample *)(w[2]);\n      t_sample    *in2 =      (t_sample *)(w[3]);\n      t_sample    *out =      (t_sample *)(w[4]);\n      int            n =             (int)(w[5]);\n\n      t_sample pan = (x-\u003ex_pan\u003c0)?0.0:(x-\u003ex_pan\u003e1)?1.0:x-\u003ex_pan;\n\n      while (n--) *out++ = (*in1++)*(1-pan)+(*in2++)*pan;\n\n      return (w+6);\n    }\n\nEach sample of the signal vectors is read and manipulated in the\n``while`` loop.\n\nOptimisation of the DSP tree tries to avoid unnecessary copy operations.\nTherefore it is possible, that in and out signals are located at the\nsame address in the memory. In this case, the programmer must be\ncareful not to write into the out signal before having read the\nin signal to avoid overwriting data that is not yet saved.\n\ndestructor\n----------\n\n::\n\n    void xfade_tilde_free(t_xfade_tilde *x)\n    {\n      inlet_free(x-\u003ex_in2);\n      inlet_free(x-\u003ex_in3);\n      outlet_free(x-\u003ex_out);\n    }\n\nIf our object has some dynamically allocated resources\n(usually this is dynamically allocated memory),\nwe must free them manually in the “free method” (aka: destructor).\n\nIn the example above, we do so by calling ``inlet_free`` (resp. ``outlet_free``) on the handles to our additional iolets.\n\n*NOTE*: we do not really need to free inlets and outlet, as Pd will\nautomatically free them for us (unless we are doing higher-order magic,\nlike displaying one object's iolet as another object's. but let's not get\ninto that for now...)\n\nthe code: xfade~\n----------------\n\n::\n\n    #include \"m_pd.h\"\n\n    static t_class *xfade_tilde_class;\n\n    typedef struct _xfade_tilde {\n      t_object x_obj;\n      t_float x_pan;\n      t_float f;\n\n      t_inlet *x_in2;\n      t_inlet *x_in3;\n      t_outlet*x_out;\n    } t_xfade_tilde;\n\n    t_int *xfade_tilde_perform(t_int *w)\n    {\n      t_xfade_tilde *x = (t_xfade_tilde *)(w[1]);\n      t_sample    *in1 =      (t_sample *)(w[2]);\n      t_sample    *in2 =      (t_sample *)(w[3]);\n      t_sample    *out =      (t_sample *)(w[4]);\n      int            n =             (int)(w[5]);\n      t_sample pan = (x-\u003ex_pan\u003c0)?0.0:(x-\u003ex_pan\u003e1)?1.0:x-\u003ex_pan;\n\n      while (n--) *out++ = (*in1++)*(1-pan)+(*in2++)*pan;\n\n      return (w+6);\n    }\n\n    void xfade_tilde_dsp(t_xfade_tilde *x, t_signal **sp)\n    {\n      dsp_add(xfade_tilde_perform, 5, x,\n              sp[0]-\u003es_vec, sp[1]-\u003es_vec, sp[2]-\u003es_vec, sp[0]-\u003es_n);\n    }\n\n    void xfade_tilde_free(t_xfade_tilde *x)\n    {\n      inlet_free(x-\u003ex_in2);\n      inlet_free(x-\u003ex_in3);\n      outlet_free(x-\u003ex_out);\n    }\n\n    void *xfade_tilde_new(t_floatarg f)\n    {\n      t_xfade_tilde *x = (t_xfade_tilde *)pd_new(xfade_tilde_class);\n\n      x-\u003ex_pan = f;\n      \n      x-\u003ex_in2=inlet_new(\u0026x-\u003ex_obj, \u0026x-\u003ex_obj.ob_pd, \u0026s_signal, \u0026s_signal);\n      x-\u003ex_in3=floatinlet_new (\u0026x-\u003ex_obj, \u0026x-\u003ex_pan);\n      x-\u003ex_out=outlet_new(\u0026x-\u003ex_obj, \u0026s_signal);\n\n      return (void *)x;\n    }\n\n    void xfade_tilde_setup(void) {\n      xfade_tilde_class = class_new(gensym(\"xfade~\"),\n            (t_newmethod)xfade_tilde_new,\n            (t_method)xfade_tilde_free,\n            sizeof(t_xfade_tilde),\n            CLASS_DEFAULT, \n            A_DEFFLOAT, 0);\n\n      class_addmethod(xfade_tilde_class,\n            (t_method)xfade_tilde_dsp, gensym(\"dsp\"), A_CANT, 0);\n      CLASS_MAINSIGNALIN(xfade_tilde_class, t_xfade_tilde, f);\n    }\n\nPd’s message system\n*******************\n\nNon-audio data is distributed via a message system. Each message\nconsists of a “selector” and a list of atoms.\n\natoms\n=====\n\nThere are three kinds of atoms:\n\n-  *A\\_FLOAT*: a numerical value (floating point)\n\n-  *A\\_SYMBOL*: a symbolic value (string)\n\n-  *A\\_POINTER*: a pointer\n\nNumerical values are always floating point values (``t_float``), even if\nthey could be displayed as integer values.\n\nEach symbol is stored in a lookup table for performance reasons.\nFunction ``gensym`` looks up a string in the lookup table and returns the\naddress of the symbol. If the string is not yet to be found in the\ntable, a new symbol is added.\n\nAtoms of type *A\\_POINTER* are not very important (for simple externals).\n\nThe type of an atom ``a`` is stored in structure element ``a.a_type``.\n\nselectors\n=========\n\nThe selector is a symbol that defines the type of a message.\nThere are five predefined selectors:\n\n-  “bang” labels a trigger event.\n   A “bang” message consists only of the selector and contains no lists of atoms.\n\n-  “float” labels a numerical value.\n   The list of a “float” message contains one single atom of type *A\\_FLOAT*.\n\n-  “symbol” labels a symbolic value.\n   The list of a “symbol” message contains one single atom of type *A\\_SYMBOL*.\n\n-  “pointer” labels a pointer value.\n   The list of a “pointer” message contains one single atom of type *A\\_POINTER*.\n\n-  “list” labels a list of one or more atoms of arbitrary type.\n\nSince the symbols for these selectors are used quite often,\ntheir address in the lookup table can be queried directly,\nwithout having to use ``gensym``:\n\n+--------------+-------------------------+------------------+\n| selector     | lookup function call    | lookup address   |\n+==============+=========================+==================+\n| bang         | ``gensym(\"bang\")``      | ``\u0026s_bang``      |\n+--------------+-------------------------+------------------+\n| float        | ``gensym(\"float\")``     | ``\u0026s_float``     |\n+--------------+-------------------------+------------------+\n| symbol       | ``gensym(\"symbol\")``    | ``\u0026s_symbol``    |\n+--------------+-------------------------+------------------+\n| pointer      | ``gensym(\"pointer\")``   | ``\u0026s_pointer``   |\n+--------------+-------------------------+------------------+\n| list         | ``gensym(\"list\")``      | ``\u0026s_list``      |\n+--------------+-------------------------+------------------+\n| — (signal)   | ``gensym(\"signal\")``    | ``\u0026s_signal``    |\n+--------------+-------------------------+------------------+\n\nOther selectors can be used as well.\nThe receiving class must provide a method for a specific selector\nor for “anything”, which is any arbitrary selector.\n\nMessages that have no explicit selector and start with a numerical value,\nare recognised automatically either as “float” message (only one atom)\nor as “list” message (several atoms).\n\nFor example, messages “\\ ``12.429``\\ ” and “\\ ``float 12.429``\\ ” are identical.\nLikewise, the messages “\\ ``list 1 for you``\\ ” is identical to “\\ ``1 for you``\\ ”.\n\n\nAPI reference\n*************\n\n\nPd types\n========\n\nSince Pd is used on several platforms, many ordinary types of variables,\nlike ``float``, are redefined.\nTo write portable code, it is advisable to use types provided by Pd.\n\nApart from this there are many predefined types, which should make the life of the programmer simpler.\n\nGenerally, Pd types start with ``t_``.\n\n+-------------------+------------------------------------------+\n| Pd type           | description                              |\n+===================+==========================================+\n| ``t_atom``        | atom                                     |\n+-------------------+------------------------------------------+\n| ``t_float``       | floating point value                     |\n+-------------------+------------------------------------------+\n| ``t_symbol``      | symbol                                   |\n+-------------------+------------------------------------------+\n| ``t_gpointer``    | pointer (to graphical objects)           |\n+-------------------+------------------------------------------+\n| ``t_int``         | pointer-sized integer value              |\n|                   | (do **not** use this for integers)       |\n+-------------------+------------------------------------------+\n| ``t_signal``      | structure of a signal                    |\n+-------------------+------------------------------------------+\n| ``t_sample``      | audio signal value (floating point)      |\n+-------------------+------------------------------------------+\n| ``t_outlet``      | outlet of an object                      |\n+-------------------+------------------------------------------+\n| ``t_inlet``       | inlet of an object                       |\n+-------------------+------------------------------------------+\n| ``t_object``      | object internals                         |\n+-------------------+------------------------------------------+\n| ``t_class``       | a Pd class                               |\n+-------------------+------------------------------------------+\n| ``t_method``      | class method                             |\n+-------------------+------------------------------------------+\n| ``t_newmethod``   | pointer to a constructor (new function)  |\n+-------------------+------------------------------------------+\n\nPd functions\n============\n\nfunctions: atoms\n----------------\n\nSETFLOAT\n^^^^^^^^\n\n::\n\n    SETFLOAT(atom, f)\n\nThis macro sets the type of ``atom`` to ``A_FLOAT``\nand stores numerical value ``f`` in this atom.\n\nSETSYMBOL\n^^^^^^^^^\n\n::\n\n    SETSYMBOL(atom, s)\n\nThis macro sets the type of ``atom`` to ``A_SYMBOL``\nand stores symbolic pointer ``s`` in this atom.\n\nSETPOINTER\n^^^^^^^^^^\n\n::\n\n    SETPOINTER(atom, pt)\n\nThis macro sets the type of ``atom`` to ``A_POINTER``\nand stores pointer ``pt`` in this atom.\n\natom\\_getfloat\n^^^^^^^^^^^^^^\n\n::\n\n    t_float atom_getfloat(t_atom *a);\n\nIf the type of atom ``a`` is ``A_FLOAT``,\nthe numerical value of this atom, else “0.0”, is returned.\n\natom\\_getfloatarg\n^^^^^^^^^^^^^^^^^\n\n::\n\n    t_float atom_getfloatarg(int which, int argc, t_atom *argv)\n\nIf the type of atom at position ``which``\n– found in the ``argv`` atom list with the length ``argc`` –\nis ``A_FLOAT``, the numerical value of this atom, else “0.0”, is returned.\n\natom\\_getint\n^^^^^^^^^^^^\n\n::\n\n    t_int atom_getint(t_atom *a);\n\nIf the type of atom ``a`` is ``A_FLOAT``,\nits numerical value is returned as an integer, else “0” is returned.\n\natom\\_getsymbol\n^^^^^^^^^^^^^^^\n\n::\n\n    t_symbol atom_getsymbol(t_atom *a);\n\nIf the type of atom ``a`` is ``A_SYMBOL``,\na pointer to this symbol is returned, else a null pointer “0” is returned.\n\natom\\_gensym\n^^^^^^^^^^^^\n\n::\n\n    t_symbol *atom_gensym(t_atom *a);\n\nIf the type of atom ``a`` is ``A_SYMBOL``,\na pointer to this symbol is returned.\n\nAtoms of a different type, are “reasonably” converted into a string.\nThis string is inserted into the symbol table (if required).\nA pointer to this symbol is returned.\n\natom\\_string\n^^^^^^^^^^^^\n\n::\n\n    void atom_string(t_atom *a, char *buf, unsigned int bufsize);\n\nConverts atom ``a`` into C string ``buf``.\nThe memory to this char buffer needs to be reserved manually\nand its length must be declared in ``bufsize``.\n\ngensym\n^^^^^^\n\n::\n\n    t_symbol *gensym(char *s);\n\nChecks whether C string ``*s`` is already present in the symbol table.\nIf no entry exists, it is created.\nA pointer to the symbol is returned.\n\nfunctions: classes\n------------------\n\nclass\\_new\n^^^^^^^^^^\n\n::\n\n    t_class *class_new(t_symbol *name,\n            t_newmethod newmethod, t_method freemethod,\n            size_t size, int flags,\n            t_atomtype arg1, ...);\n\nGenerates a class with the symbolic name ``name``.\n``newmethod`` is the constructor that creates an instance of the class\nand returns a pointer to this instance.\n\nIf memory is reserved dynamically,\nthis memory must be freed by the destructor method ``freemethod``\n(without any return argument), when the object is destroyed.\n\n``size`` is the static size of the class data space that is returned by\n``sizeof(t_mydata)``.\n\n``flags`` define the presentation of the graphical object. A (more or\nless arbitrary) combination of the following values is possible:\n\n\n+---------------------+------------------------------------+\n| flag                | description                        |\n+=====================+====================================+\n| ``CLASS_DEFAULT``   | a normal object with one inlet     |\n+---------------------+------------------------------------+\n| ``CLASS_PD``        | *object*                           |\n|                     | *(without graphical presentation)* |\n+---------------------+------------------------------------+\n| ``CLASS_GOBJ``      | *pure graphical object*            |\n|                     | *(like arrays, graphs,...)*        |\n+---------------------+------------------------------------+\n| ``CLASS_PATCHABLE`` | *a normal object (with one inlet)* |\n+---------------------+------------------------------------+\n| ``CLASS_NOINLET``   | the default inlet is suppressed    |\n+---------------------+------------------------------------+\n\nFlags whose description is printed in *italic*\nare of small importance for writing externals.\n\nThe remaining arguments ``arg1,...`` define the types of\nobject arguments passed at the creation of a class object. A maximum of\nsix type-checked arguments can be passed to an object. The list of\nargument types is terminated by “0”.\n\nPossible argument types are:\n\n+-------------------+-------------------------------------------------+\n| ``A_DEFFLOAT``    | a numerical value                               |\n+-------------------+-------------------------------------------------+\n| ``A_DEFSYMBOL``   | a symbolic value                                |\n+-------------------+-------------------------------------------------+\n| ``A_GIMME``       | a list of atoms of arbitrary length and types   |\n+-------------------+-------------------------------------------------+\n\nIf more than six arguments are to be passed,\n``A_GIMME`` must be used and a manual type check must be made.\n\nclass\\_addmethod\n^^^^^^^^^^^^^^^^\n\n::\n\n    void class_addmethod(t_class *c, t_method fn, t_symbol *sel,\n        t_atomtype arg1, ...);\n\nAdds method ``fn`` for selector ``sel`` to class ``c``.\n\nThe remaining arguments ``arg1,...`` define the types of the list of atoms that follow the selector.\nA maximum of six type-checked arguments can be passed.\nIf more than six arguments are to be passed, ``A_GIMME`` must be used and a manual type check must be made.\n\nThe list of arguments is terminated by “0”.\n\nPossible types of arguments are:\n\n+-------------------+--------------------------------------------------+\n| ``A_DEFFLOAT``    | a numerical value (default to '0')               |\n+-------------------+--------------------------------------------------+\n| ``A_FLOAT``       | an obligatory numerical value (no default value) |\n+-------------------+--------------------------------------------------+\n| ``A_DEFSYMBOL``   | a symbolic value (default to '')                 |\n+-------------------+--------------------------------------------------+\n| ``A_SYMBOL``      | an obligatory symbol value                       |\n+-------------------+--------------------------------------------------+\n| ``A_POINTER``     | a pointer                                        |\n+-------------------+--------------------------------------------------+\n| ``A_GIMME``       | a list of atoms of arbitrary length and types    |\n+-------------------+--------------------------------------------------+\n| ``A_CANT``        | no possible atoms (used for internal messages    |\n|                   | which would crash Pd when called by the user     |\n+-------------------+--------------------------------------------------+\n\nclass\\_addbang\n^^^^^^^^^^^^^^\n\n::\n\n    void class_addbang(t_class *c, t_method fn);\n\nAdds method ``fn`` for “bang”-messages to class ``c``.\n\nThe argument of the “bang” method is a pointer to the class data space:\n\n``void my_bang_method(t_mydata *x);``\n\nclass\\_addfloat\n^^^^^^^^^^^^^^^\n\n::\n\n    void class_addfloat(t_class *c, t_method fn);\n\nAdds method ``fn`` for “float” messages to class ``c``.\n\nThe arguments of the “float” method are a pointer to the class data space\nand a floating point argument:\n\n``void my_float_method(t_mydata *x, t_floatarg f);``\n\nclass\\_addsymbol\n^^^^^^^^^^^^^^^^\n\n::\n\n    void class_addsymbol(t_class *c, t_method fn);\n\nAdds method ``fn`` for “symbol” messages to class ``c``.\n\nThe arguments of the “symbol” method are a pointer to the class data space\nand a pointer to the passed symbol:\n\n``void my_symbol_method(t_mydata *x, t_symbol *s);``\n\nclass\\_addpointer\n^^^^^^^^^^^^^^^^^\n\n::\n\n    void class_addpointer(t_class *c, t_method fn);\n\nAdds method ``fn`` for “pointer” messages to class ``c``.\n\nThe arguments of the “pointer” method are a pointer to the class data space\nand a pointer to a pointer:\n\n``void my_pointer_method(t_mydata *x, t_gpointer *pt);``\n\nclass\\_addlist\n^^^^^^^^^^^^^^\n\n::\n\n    void class_addlist(t_class *c, t_method fn);\n\nAdds method ``fn`` for “list” messages to class ``c``.\n\nThe arguments of the “list” method are\n– apart from a pointer to the class data space –\na pointer to the selector symbol (always ``\u0026s_list``),\nthe number of atoms and a pointer to the list of atoms:\n\n``void my_list_method(t_mydata *x,``\n\n``t_symbol *s, int argc, t_atom *argv);``\n\nclass\\_addanything\n^^^^^^^^^^^^^^^^^^\n\n::\n\n    void class_addanything(t_class *c, t_method fn);\n\nAdds method ``fn`` for an arbitrary message to class ``c``.\n\nThe arguments of the anything method are\n– apart from a pointer to the class data space –\na pointer to the selector symbol,\nthe number of atoms and a pointer to the list of atoms:\n\n``void my_any_method(t_mydata *x,``\n\n``t_symbol *s, int argc, t_atom *argv);``\n\nclass\\_addcreator\n^^^^^^^^^^^^^^^^^\n\n::\n\n     void class_addcreator(t_newmethod newmethod, t_symbol *s, \n        t_atomtype type1, ...);\n\nAdds creator symbol ``s``, alternative to the symbolic class name, to\nconstructor ``newmethod``. Thus, objects can be created either by\ntheir “real” class name or an alias name (e.g. an abbreviation, like the\ninternal “float” resp. “f”).\n\nThe “0”-terminated list of types corresponds to that of ``class_new``.\n\nclass\\_sethelpsymbol\n^^^^^^^^^^^^^^^^^^^^\n\n::\n\n    void class_sethelpsymbol(t_class *c, t_symbol *s);\n\nIf a Pd object is right-clicked, a help patch for the corresponding\nobject class can be opened.\nBy default, this is a patch with the symbolic class name\nin the directory “\\ *doc/5.reference/*\\ ”.\n\nThe name of the help patch for the class pointed to by ``c`` is\nchanged to symbol ``s``.\n\nTherefore, several similar classes can share a single help patch.\n\nThe path is relative to the default help directory *doc/5.reference/*.\n\npd\\_new\n^^^^^^^\n\n::\n\n    t_pd *pd_new(t_class *cls);\n\nGenerates a new instance of class ``cls``\nand returns a pointer to this instance.\n\nfunctions: inlets and outlets\n-----------------------------\n\nAll functions for inlets and outlets need a reference to the\nobject internals of the class instance.\nWhen instantiating a new object,\nthe necessary data space variable of the ``t_object`` type is\ninitialised. This variable must be passed as the ``owner`` object to\nthe various inlet and outlet functions.\n\ninlet\\_new\n^^^^^^^^^^\n\n::\n\n    t_inlet *inlet_new(t_object *owner, t_pd *dest,\n          t_symbol *s1, t_symbol *s2);\n\nGenerates an additional “active” inlet for the object pointed at by ``owner``.\nGenerally, ``dest`` points at “\\ ``owner.ob_pd``\\ ”.\n\nSelector ``s1`` at the new inlet is substituted by selector ``s2``.\n\nIf a message with selector ``s1`` appears at the new inlet,\nthe class method for selector ``s2`` is called.\n\nThis means:\n\n-  The substituting selector must be declared by ``class_addmethod``\n   in the setup function.\n\n-  It is possible to simulate a certain right inlet, by sending a message with this inlet’s selector to the leftmost inlet.\n\n   Using an empty symbol (``gensym(\"\")``) as selector makes it impossible to address a right inlet via the leftmost one.\n\n-  It is not possible to add methods for more than one selector to a\n   right inlet. Particularly, it is not possible to add a universal\n   method for arbitrary selectors to a right inlet.\n\nfloatinlet\\_new\n^^^^^^^^^^^^^^^\n\n::\n\n    t_inlet *floatinlet_new(t_object *owner, t_float *fp);\n\nGenerates a new “passive” inlet for the object pointed at by ``owner``.\nThis inlet enables numerical values to be written directly\ninto the memory location pointed at by ``fp``,\nwithout calling a dedicated method.\n\nsymbolinlet\\_new\n^^^^^^^^^^^^^^^^\n\n::\n\n    t_inlet *symbolinlet_new(t_object *owner, t_symbol **sp);\n\nGenerates a new “passive” inlet for the object pointed at by ``owner``.\nThis inlet enables symbolic values to be written directly\ninto the memory  location pointed at by ``*sp``,\nwithout calling a dedicated method.\n\npointerinlet\\_new\n^^^^^^^^^^^^^^^^^\n\n::\n\n    t_inlet *pointerinlet_new(t_object *owner, t_gpointer *gp);\n\nGenerates a new “passive” inlet for the object pointed at by ``owner``.\nThis inlet enables pointer to be written directly into the\nmemory location pointed at by ``gp``,\nwithout calling a dedicated method.\n\noutlet\\_new\n^^^^^^^^^^^\n\n::\n\n    t_outlet *outlet_new(t_object *owner, t_symbol *s);\n\nGenerates a new outlet for the object pointed at by ``owner``.\nSymbol ``s`` indicates the type of the outlet.\n\n+-------------+-------------------+---------------------+\n| symbol      | symbol address    | outlet type         |\n+=============+===================+=====================+\n| “bang”      | ``\u0026s_bang``       | message (bang)      |\n+-------------+-------------------+---------------------+\n| “float”     | ``\u0026s_float``      | message (float)     |\n+-------------+-------------------+---------------------+\n| “symbol”    | ``\u0026s_symbol``     | message (symbol)    |\n+-------------+-------------------+---------------------+\n| “pointer”   | ``\u0026s_gpointer``   | message (pointer)   |\n+-------------+-------------------+---------------------+\n| “list”      | ``\u0026s_list``       | message (list)      |\n+-------------+-------------------+---------------------+\n| —           | 0                 | message             |\n+-------------+-------------------+---------------------+\n| “signal”    | ``\u0026s_signal``     | signal              |\n+-------------+-------------------+---------------------+\n\nThere are no real differences between outlets of the various message types.\nAt any rate, it makes code more easily readable, if the use of outlet is shown at creation time.\nFor outlets for any-type messages, a null pointer is used.\nSignal outlet must be declared with ``\u0026s_signal``.\n\nVariables of type ``t_object`` provide pointers to one outlet.\nWhenever a new outlet is generated, its address is stored in object\nvariable ``(*owner).ob_outlet``.\n\nIf more than one message outlet is needed, the outlet pointers\nreturned by ``outlet_new`` must be stored manually in the data space\nso you can later address the given outlet.\n\noutlet\\_bang\n^^^^^^^^^^^^\n\n::\n\n    void outlet_bang(t_outlet *x);\n\nOutputs a “bang”-message at the outlet specified by ``x``.\n\noutlet\\_float\n^^^^^^^^^^^^^\n\n::\n\n    void outlet_float(t_outlet *x, t_float f);\n\nOutputs a “float”-message with numeric value ``f``\nat the outlet specified by ``x``.\n\noutlet\\_symbol\n^^^^^^^^^^^^^^\n\n::\n\n    void outlet_symbol(t_outlet *x, t_symbol *s);\n\nOutputs a “symbol”-message with symbolic value ``s``\nat the outlet specified by ``x``.\n\noutlet\\_pointer\n^^^^^^^^^^^^^^^\n\n::\n\n    void outlet_pointer(t_outlet *x, t_gpointer *gp);\n\nOutputs a “pointer” message with pointer ``gp``\nat the outlet specified by ``x``.\n\noutlet\\_list\n^^^^^^^^^^^^\n\n::\n\n    void outlet_list(t_outlet *x,\n                     t_symbol *s, int argc, t_atom *argv);\n\nOutputs a “list” message at the outlet specified by ``x``.\nThe list contains ``argc`` atoms.\n``argv`` points to the first element of the atom list.\n\nIndependent of symbol ``s``, selector “list” will precede the list.\n\nTo make the code more readable, ``s`` should point to the symbol list (either via ``gensym(\"list\")`` or via ``\u0026s_list``).\n\noutlet\\_anything\n^^^^^^^^^^^^^^^^\n\n::\n\n    void outlet_anything(t_outlet *x,\n                         t_symbol *s, int argc, t_atom *argv);\n\nOutputs a message at the outlet specified by ``x``.\n\nThe message selector is specified with ``s``.\nIt is followed by ``argc`` atoms.\n``argv`` points to the first element of the atom list.\n\nfunctions: DSP\n--------------\n\nIf a class is to provide methods for digital signal processing,\na method for selector “dsp” (followed by no atoms) must be added to the class.\n\nWhenever Pd’s audio engine is started, all the objects providing a\n“dsp” method are identified as instances of signal classes.\n\nDSP method\n^^^^^^^^^^\n\n::\n\n    void my_dsp_method(t_mydata *x, t_signal **sp)\n\nIn the “dsp” method, a method for signal processing is added to the\nDSP tree by function ``dsp_add``.\n\nApart from the data space ``x`` of the object, an array of signals is\npassed. The signals in the array are arranged from left to right,\nfirst the inlets, then the outlets.\n\nIn case there are both two in and out signals, this means:\n\n+-----------+--------------------+\n| pointer   | to signal          |\n+===========+====================+\n| sp[0]     | left in signal     |\n+-----------+--------------------+\n| sp[1]     | right in signal    |\n+-----------+--------------------+\n| sp[2]     | left out signal    |\n+-----------+--------------------+\n| sp[3]     | right out signal   |\n+-----------+--------------------+\n\nThe signal structure contains apart from other things:\n\n+---------------------+--------------------------------+\n| structure element   | description                    |\n+=====================+================================+\n| ``s_n``             | length of the signal vector    |\n+---------------------+--------------------------------+\n| ``s_vec``           | pointer to the signal vector   |\n+---------------------+--------------------------------+\n\nThe signal vector is an array of samples of type ``t_sample``.\n\nperform function\n^^^^^^^^^^^^^^^^\n\n::\n\n    t_int *my_perform_routine(t_int *w)\n\nA pointer ``w`` to an array (of pointer-sized integers) is passed to the\nperform function that is inserted into the DSP tree by ``class_add``.\n\nIn this array, the pointers passed via ``dsp_add`` are stored.\nThese pointers must be cast back to their original type.\n\n**N.B.**: The first pointer is stored at ``w[1]`` !!!\n(``w[0]`` stores the address of the perform-routine itself; while used internally by the DSP-graph, there's typically no use for this value in perform-routine itself.)\n\nThe perform function must return a pointer, that points\ndirectly behind the memory, where the object’s pointers are stored. This\nmeans that the return argument equals function argument ``w``, plus\nthe number of used pointers (as defined in the second argument of\n``dsp_add``) plus one.\n\n\nCLASS\\_MAINSIGNALIN\n^^^^^^^^^^^^^^^^^^^\n\n::\n\n    CLASS_MAINSIGNALIN(\u003cclass_name\u003e, \u003cclass_data\u003e, \u003cf\u003e);\n\nMacro ``CLASS_MAINSIGNALIN`` declares that the objectclass' first inlet\nwill accept a signal.\n\nThe first macro argument is a pointer to the signal class.\nThe second argument is the type of the class data space.\nThe third argument is a (dummy) floating point variable of the data space,\nthat is needed to automatically convert “float” messages into signals\nif no signal is present at the signal inlet.\n\nNo “float” methods can be used for signal inlets created this way.\n\ndsp\\_add\n^^^^^^^^\n\n::\n\n    void dsp_add(t_perfroutine f, int n, ...);\n\nAdds perform function ``f`` to the DSP tree.\nThe perform function is called at each DSP cycle.\n\nSecond argument ``n`` defines the number of the following\npointer arguments.\n\nWhich pointers to which data are passed is not limited. Generally,\npointers to the data space of the object and to the signal vectors are\nreasonable. The length of the signal vectors should also be passed to\nmanipulate signals effectively.\n\ndsp\\_addv\n^^^^^^^^^\n\n::\n\n    void dsp_addv(t_perfroutine f, int n, t_int *vec);\n\nAdds perform function ``f`` to the DSP tree.\nThe perform function is called at each DSP cycle.\n\nSecond argument ``n`` defines the number of arguments passed in\nthird argument ``vec``.\n\nThird argument ``vec`` holds the pointers to the data to be passed\nto perform function ``f``.\n\nThis method performs the same operation as *dsp\\_add* but is more\nflexible, because its array can be manipulated at run-time based on\nattributes of the object.\nThis is how you would create an object with a variable amount of inputs\nand/or outputs.\n\nsys\\_getsr\n^^^^^^^^^^\n\n::\n\n    float sys_getsr(void);\n\nReturns the sample rate of the system.\n\nsys\\_getblksize\n^^^^^^^^^^^^^^^\n\n::\n\n    int sys_getblksize(void);\n\nReturns the system's top level dsp block size.\n\n*Note*: this isn't necessarily the same as the length of the\nsignal vector that a signal object is expected to execute on.\nA switch~ or block~ object might change that.\nAn object's \"dsp\" method has access to the signal vectors\nand the *s\\_n* entry of any of the t\\_signal's passed in\ngive the length of the signal vector the dsp *perform* function will execute on.\n\nfunctions: memory\n-----------------\n\ngetbytes\n^^^^^^^^\n\n::\n\n    void *getbytes(size_t nbytes);\n\nReserves ``nbytes`` bytes and returns a pointer to the allocated memory.\n\ncopybytes\n^^^^^^^^^\n\n::\n\n    void *copybytes(void *src, size_t nbytes);\n\nCopies ``nbytes`` bytes from ``*src`` into a newly allocated memory block.\nThe address of this memory block is returned.\n\nfreebytes\n^^^^^^^^^\n\n::\n\n    void freebytes(void *x, size_t nbytes);\n\nFrees ``nbytes`` bytes at address ``*x``.\n\nfunctions: output\n-----------------\n\npost\n^^^^\n\n::\n\n    void post(const char *fmt, ...);\n\nWrites a C string to the Pd console.\n\nverbose\n^^^^^^^\n\n::\n\n   void verbose(int level, const char *fmt, ...);\n\nWrites a C-string as a verbose message to the Pd-console.\nIf ``level==0``, the message is only printed if Pd was started in *verbose* mode (``-v`` startup flag).\nIf ``level==1``, the message is only printed if Pd was started in *more verbose* mode (``-v -v`` startup flags), and so on.\n\n\npd_error\n^^^^^^^^\n\n::\n\n    void pd_error(void object*, const char *fmt, ...);\n\nWrites a C string as an error message to the Pd console.\nThe error message is associated with the object that emitted it,\nso you can |kbd| Control |nkbd| -click the error message to highlight the object\n(or find it via the Pd menu *Find-\u003eFind last error*)\n\nThe ``object`` must point to your object instance (or be ``NULL``).\n\nlogpost\n^^^^^^^\n\n::\n\n    void logpost(void object*, const int level, const char *fmt, ...);\n\nWrites a C-string as an message to the Pd-console at a given verbosity.\nThe message is associated with the object that emitted it, so you can |kbd| Control |nkbd| -Click the error message to highlight the object.\n\nThe ``object`` must point to your object instance (or be ``NULL``).\n\nThe verbosity ``level`` can have the following values:\n\n+-------+---------------+\n| level | severity      |\n+=======+===============+\n| 0     | fatal         |\n+-------+---------------+\n| 1     | error         |\n+-------+---------------+\n| 2     | normal        |\n+-------+---------------+\n| 3     | verbose       |\n+-------+---------------+\n| 4     | more verbose  |\n+-------+---------------+\n\n.. raw:: html\n\n   \u003cs\u003e\n\nerror\n^^^^^\n\nPrevious versions of Pd had an ``error`` function to emit errors,\nbut this has been removed as it clashed with the function of the same name\nin many libc implementations.\n\nUse ``pd_error()`` instead (possibly with a ``NULL`` object)\n\n.. raw:: html\n\n   \u003c/s\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpure-data%2Fexternals-howto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpure-data%2Fexternals-howto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpure-data%2Fexternals-howto/lists"}