jack/port.h

   1 /*
   2     Copyright (C) 2001 Paul Davis
   3
   4     This program is free software; you can redistribute it and/or modify
   5     it under the terms of the GNU Lesser General Public License as published by
   6     the Free Software Foundation; either version 2.1 of the License, or
   7     (at your option) any later version.
   8
   9     This program is distributed in the hope that it will be useful,
  10     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12     GNU Lesser General Public License for more details.
  13
  14     You should have received a copy of the GNU Lesser General Public License
  15     along with this program; if not, write to the Free Software
  16     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  17
  18 */
  19
  20 #ifndef __jack_port_h__
  21 #define __jack_port_h__
  22
  23 #include <pthread.h>
  24 #include <jack/types.h>
  25 #include <jack/jslist.h>
  26 #include <jack/shm.h>
  27
  28 #define JACK_PORT_NAME_SIZE 256
  29 #define JACK_PORT_TYPE_SIZE 32
  30
  31 /* The relatively low value of this constant reflects the fact that
  32  * JACK currently only knows about *2* port types.  (May 2006)
  33  *
  34  * Further, the 4 covers:
  35  *   - a single non-negotiated audio format
  36  *   - music data (ie. MIDI)
  37  *   - video
  38  *   - one other
  39  *
  40  * which is probably enough for more than just the foreseeable future.
  41  */
  42 #define JACK_MAX_PORT_TYPES 4
  43 #define JACK_AUDIO_PORT_TYPE 0
  44 #define JACK_MIDI_PORT_TYPE 1
  45
  46 /* these should probably go somewhere else, but not in <jack/types.h> */
  47 #define JACK_CLIENT_NAME_SIZE 33
  48 typedef uint32_t jack_client_id_t;
  49
  50 /* JACK shared memory segments are limited to MAX_INT32, they can be
  51  * shared between 32-bit and 64-bit clients.
  52  */
  53 #define JACK_SHM_MAX (MAX_INT32)
  54 typedef int32_t jack_port_type_id_t;
  55
  56 #define JACK_BACKEND_ALIAS "system"
  57
  58 #ifndef POST_PACKED_STRUCTURE
  59 #ifdef __GNUC__
  60 /* POST_PACKED_STRUCTURE needs to be a macro which
  61    expands into a compiler directive. The directive must
  62    tell the compiler to arrange the preceding structure
  63    declaration so that it is packed on byte-boundaries rather
  64    than use the natural alignment of the processor and/or
  65    compiler.
  66 */
  67 #define POST_PACKED_STRUCTURE __attribute__((__packed__))
  68 #else
  69 /* Add other things here for non-gcc platforms */
  70 #endif
  71 #endif
  72
  73 /* Port type structure.
  74  *
  75  *  (1) One for each port type is part of the engine's jack_control_t
  76  *  shared memory structure.
  77  *
  78  *  (2) One for each port type is appended to the engine's
  79  *  jack_client_connect_result_t response.  The client reads them into
  80  *  its local memory, using them to attach the corresponding shared
  81  *  memory segments.
  82  */
  83 typedef struct _jack_port_type_info {
  84
  85     jack_port_type_id_t ptype_id;
  86     const char     type_name[JACK_PORT_TYPE_SIZE];
  87
  88     /* If == 1, then a buffer to handle nframes worth of data has
  89      * sizeof(jack_default_audio_sample_t) * nframes bytes.
  90      *
  91      * If > 1, the buffer allocated for input mixing will be
  92      * this value times sizeof(jack_default_audio_sample_t)
  93      * * nframes bytes in size.  For non-audio data types,
  94      * it may have a different value.
  95      *
  96      * If < 0, the value should be ignored, and buffer_size
  97      * should be used.
  98      */
  99     int32_t buffer_scale_factor;
 100
 101     /* ignored unless buffer_scale_factor is < 0. see above */
 102     jack_shmsize_t buffer_size;
 103
 104     jack_shm_registry_index_t shm_registry_index;
 105
 106     jack_shmsize_t zero_buffer_offset;
 107
 108 } POST_PACKED_STRUCTURE jack_port_type_info_t;
 109
 110 /* Allocated by the engine in shared memory. */
 111 typedef struct _jack_port_shared {
 112
 113     jack_port_type_id_t      ptype_id;  /* index into port type array */
 114     jack_shmsize_t           offset;    /* buffer offset in shm segment */
 115     jack_port_id_t           id;        /* index into engine port array */
 116     uint32_t                         flags;
 117     char                     name[JACK_CLIENT_NAME_SIZE+JACK_PORT_NAME_SIZE];
 118     char                     alias1[JACK_CLIENT_NAME_SIZE+JACK_PORT_NAME_SIZE];
 119     char                     alias2[JACK_CLIENT_NAME_SIZE+JACK_PORT_NAME_SIZE];
 120     jack_client_id_t         client_id; /* who owns me */
 121
 122     volatile jack_nframes_t  latency;
 123     volatile jack_nframes_t  total_latency;
 124     volatile uint8_t         monitor_requests;
 125
 126     char                     has_mixdown; /* port has a mixdown function */
 127     char                     in_use;
 128     char                     unused; /* legacy locked field */
 129
 130 } POST_PACKED_STRUCTURE jack_port_shared_t;
 131
 132 typedef struct _jack_port_functions {
 133
 134     /* Function to initialize port buffer. Cannot be NULL.
 135      * NOTE: This must take a buffer rather than jack_port_t as it is called
 136      * in jack_engine_place_buffers() before any port creation.
 137      * A better solution is to make jack_engine_place_buffers to be type-specific,
 138      * but this works.
 139      */
 140     void (*buffer_init)(void *buffer, size_t size, jack_nframes_t);
 141
 142     /* Function to mixdown multiple inputs to a buffer.  Can be NULL,
 143      * indicating that multiple input connections are not legal for
 144      * this data type.
 145      */
 146     void (*mixdown)(jack_port_t *, jack_nframes_t);
 147
 148 } jack_port_functions_t;
 149
 150 /**
 151  * Get port functions.
 152  * @param ptid port type id.
 153  *
 154  * @return pointer to port type functions or NULL if port type is unknown.
 155  */
 156 /*const*/ jack_port_functions_t *
 157 jack_get_port_functions(jack_port_type_id_t ptid);
 158
 159
 160 /* Allocated by the client in local memory. */
 161 struct _jack_port {
 162     void                    **client_segment_base;
 163     void                     *mix_buffer;
 164     jack_port_type_info_t    *type_info; /* shared memory type info */
 165     struct _jack_port_shared *shared;    /* corresponding shm struct */
 166     struct _jack_port        *tied;      /* locally tied source port */
 167     jack_port_functions_t    fptr;
 168     pthread_mutex_t          connection_lock;
 169     JSList                   *connections;
 170 };
 171
 172 /*  Inline would be cleaner, but it needs to be fast even in
 173  *  non-optimized code.  jack_output_port_buffer() only handles output
 174  *  ports.  jack_port_buffer() works for both input and output ports.
 175  */
 176 #define jack_port_buffer(p) \
 177   ((void *) ((p)->mix_buffer? (p)->mix_buffer: \
 178    *(p)->client_segment_base + (p)->shared->offset))
 179 #define jack_output_port_buffer(p) \
 180   ((void *) (*(p)->client_segment_base + (p)->shared->offset))
 181
 182 #endif /* __jack_port_h__ */
 183