1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gstreamer.Segment; 26 27 private import glib.ConstructionException; 28 private import gobject.ObjectG; 29 private import gstreamerc.gstreamer; 30 public import gstreamerc.gstreamertypes; 31 32 33 /** 34 * This helper structure holds the relevant values for tracking the region of 35 * interest in a media file, called a segment. 36 * 37 * The structure can be used for two purposes: 38 * <itemizedlist> 39 * <listitem><para>performing seeks (handling seek events)</para></listitem> 40 * <listitem><para>tracking playback regions (handling newsegment events)</para></listitem> 41 * </itemizedlist> 42 * 43 * The segment is usually configured by the application with a seek event which 44 * is propagated upstream and eventually handled by an element that performs the seek. 45 * 46 * The configured segment is then propagated back downstream with a newsegment event. 47 * This information is then used to clip media to the segment boundaries. 48 * 49 * A segment structure is initialized with gst_segment_init(), which takes a #GstFormat 50 * that will be used as the format of the segment values. The segment will be configured 51 * with a start value of 0 and a stop/duration of -1, which is undefined. The default 52 * rate and applied_rate is 1.0. 53 * 54 * The public duration field contains the duration of the segment. When using 55 * the segment for seeking, the start and time members should normally be left 56 * to their default 0 value. The stop position is left to -1 unless explicitly 57 * configured to a different value after a seek event. 58 * 59 * The current position in the segment should be set by changing the position 60 * member in the structure. 61 * 62 * For elements that perform seeks, the current segment should be updated with the 63 * gst_segment_do_seek() and the values from the seek event. This method will update 64 * all the segment fields. The position field will contain the new playback position. 65 * If the start_type was different from GST_SEEK_TYPE_NONE, playback continues from 66 * the position position, possibly with updated flags or rate. 67 * 68 * For elements that want to use #GstSegment to track the playback region, 69 * update the segment fields with the information from the newsegment event. 70 * The gst_segment_clip() method can be used to check and clip 71 * the media data to the segment boundaries. 72 * 73 * For elements that want to synchronize to the pipeline clock, gst_segment_to_running_time() 74 * can be used to convert a timestamp to a value that can be used to synchronize 75 * to the clock. This function takes into account the base as well as 76 * any rate or applied_rate conversions. 77 * 78 * For elements that need to perform operations on media data in stream_time, 79 * gst_segment_to_stream_time() can be used to convert a timestamp and the segment 80 * info to stream time (which is always between 0 and the duration of the stream). 81 */ 82 public class Segment 83 { 84 /** the main Gtk struct */ 85 protected GstSegment* gstSegment; 86 87 /** Get the main Gtk struct */ 88 public GstSegment* getSegmentStruct() 89 { 90 return gstSegment; 91 } 92 93 /** the main Gtk struct as a void* */ 94 protected void* getStruct() 95 { 96 return cast(void*)gstSegment; 97 } 98 99 /** 100 * Sets our main struct and passes it to the parent class. 101 */ 102 public this (GstSegment* gstSegment) 103 { 104 this.gstSegment = gstSegment; 105 } 106 107 108 /** */ 109 public static GType getType() 110 { 111 return gst_segment_get_type(); 112 } 113 114 /** 115 * Allocate a new #GstSegment structure and initialize it using 116 * gst_segment_init(). 117 * 118 * Free-function: gst_segment_free 119 * 120 * Return: a new #GstSegment, free with gst_segment_free(). 121 * 122 * Throws: ConstructionException GTK+ fails to create the object. 123 */ 124 public this() 125 { 126 auto p = gst_segment_new(); 127 128 if(p is null) 129 { 130 throw new ConstructionException("null returned by new"); 131 } 132 133 this(cast(GstSegment*) p); 134 } 135 136 /** 137 * Clip the given @start and @stop values to the segment boundaries given 138 * in @segment. @start and @stop are compared and clipped to @segment 139 * start and stop values. 140 * 141 * If the function returns %FALSE, @start and @stop are known to fall 142 * outside of @segment and @clip_start and @clip_stop are not updated. 143 * 144 * When the function returns %TRUE, @clip_start and @clip_stop will be 145 * updated. If @clip_start or @clip_stop are different from @start or @stop 146 * respectively, the region fell partially in the segment. 147 * 148 * Note that when @stop is -1, @clip_stop will be set to the end of the 149 * segment. Depending on the use case, this may or may not be what you want. 150 * 151 * Params: 152 * format = the format of the segment. 153 * start = the start position in the segment 154 * stop = the stop position in the segment 155 * clipStart = the clipped start position in the segment 156 * clipStop = the clipped stop position in the segment 157 * 158 * Return: %TRUE if the given @start and @stop times fall partially or 159 * completely in @segment, %FALSE if the values are completely outside 160 * of the segment. 161 */ 162 public bool clip(GstFormat format, ulong start, ulong stop, out ulong clipStart, out ulong clipStop) 163 { 164 return gst_segment_clip(gstSegment, format, start, stop, &clipStart, &clipStop) != 0; 165 } 166 167 /** 168 * Create a copy of given @segment. 169 * 170 * Free-function: gst_segment_free 171 * 172 * Return: a new #GstSegment, free with gst_segment_free(). 173 */ 174 public Segment copy() 175 { 176 auto p = gst_segment_copy(gstSegment); 177 178 if(p is null) 179 { 180 return null; 181 } 182 183 return ObjectG.getDObject!(Segment)(cast(GstSegment*) p); 184 } 185 186 /** 187 * Copy the contents of @src into @dest. 188 * 189 * Params: 190 * dest = a #GstSegment 191 */ 192 public void copyInto(Segment dest) 193 { 194 gst_segment_copy_into(gstSegment, (dest is null) ? null : dest.getSegmentStruct()); 195 } 196 197 /** 198 * Update the segment structure with the field values of a seek event (see 199 * gst_event_new_seek()). 200 * 201 * After calling this method, the segment field position and time will 202 * contain the requested new position in the segment. The new requested 203 * position in the segment depends on @rate and @start_type and @stop_type. 204 * 205 * For positive @rate, the new position in the segment is the new @segment 206 * start field when it was updated with a @start_type different from 207 * #GST_SEEK_TYPE_NONE. If no update was performed on @segment start position 208 * (#GST_SEEK_TYPE_NONE), @start is ignored and @segment position is 209 * unmodified. 210 * 211 * For negative @rate, the new position in the segment is the new @segment 212 * stop field when it was updated with a @stop_type different from 213 * #GST_SEEK_TYPE_NONE. If no stop was previously configured in the segment, the 214 * duration of the segment will be used to update the stop position. 215 * If no update was performed on @segment stop position (#GST_SEEK_TYPE_NONE), 216 * @stop is ignored and @segment position is unmodified. 217 * 218 * The applied rate of the segment will be set to 1.0 by default. 219 * If the caller can apply a rate change, it should update @segment 220 * rate and applied_rate after calling this function. 221 * 222 * @update will be set to %TRUE if a seek should be performed to the segment 223 * position field. This field can be %FALSE if, for example, only the @rate 224 * has been changed but not the playback position. 225 * 226 * Params: 227 * rate = the rate of the segment. 228 * format = the format of the segment. 229 * flags = the segment flags for the segment 230 * startType = the seek method 231 * start = the seek start value 232 * stopType = the seek method 233 * stop = the seek stop value 234 * update = boolean holding whether position was updated. 235 * 236 * Return: %TRUE if the seek could be performed. 237 */ 238 public bool doSeek(double rate, GstFormat format, GstSeekFlags flags, GstSeekType startType, ulong start, GstSeekType stopType, ulong stop, ref bool update) 239 { 240 int outupdate = (update ? 1 : 0); 241 242 auto p = gst_segment_do_seek(gstSegment, rate, format, flags, startType, start, stopType, stop, &outupdate) != 0; 243 244 update = (outupdate == 1); 245 246 return p; 247 } 248 249 /** 250 * Free the allocated segment @segment. 251 */ 252 public void free() 253 { 254 gst_segment_free(gstSegment); 255 } 256 257 /** 258 * The start/position fields are set to 0 and the stop/duration 259 * fields are set to -1 (unknown). The default rate of 1.0 and no 260 * flags are set. 261 * 262 * Initialize @segment to its default values. 263 * 264 * Params: 265 * format = the format of the segment. 266 */ 267 public void init(GstFormat format) 268 { 269 gst_segment_init(gstSegment, format); 270 } 271 272 /** 273 * Checks for two segments being equal. Equality here is defined 274 * as perfect equality, including floating point values. 275 * 276 * Params: 277 * s1 = a #GstSegment structure. 278 * 279 * Return: %TRUE if the segments are equal, %FALSE otherwise. 280 * 281 * Since: 1.6 282 */ 283 public bool isEqual(Segment s1) 284 { 285 return gst_segment_is_equal(gstSegment, (s1 is null) ? null : s1.getSegmentStruct()) != 0; 286 } 287 288 /** 289 * Adjust the values in @segment so that @offset is applied to all 290 * future running-time calculations. 291 * 292 * Params: 293 * format = the format of the segment. 294 * offset = the offset to apply in the segment 295 * 296 * Return: %TRUE if the segment could be updated successfully. If %FALSE is 297 * returned, @offset is not in @segment. 298 * 299 * Since: 1.2.3 300 */ 301 public bool offsetRunningTime(GstFormat format, long offset) 302 { 303 return gst_segment_offset_running_time(gstSegment, format, offset) != 0; 304 } 305 306 /** 307 * Adjust the start/stop and base values of @segment such that the next valid 308 * buffer will be one with @running_time. 309 * 310 * Params: 311 * format = the format of the segment. 312 * runningTime = the running_time in the segment 313 * 314 * Return: %TRUE if the segment could be updated successfully. If %FALSE is 315 * returned, @running_time is -1 or not in @segment. 316 */ 317 public bool setRunningTime(GstFormat format, ulong runningTime) 318 { 319 return gst_segment_set_running_time(gstSegment, format, runningTime) != 0; 320 } 321 322 /** 323 * Convert @running_time into a position in the segment so that 324 * gst_segment_to_running_time() with that position returns @running_time. 325 * 326 * Params: 327 * format = the format of the segment. 328 * runningTime = the running_time in the segment 329 * 330 * Return: the position in the segment for @running_time. This function returns 331 * -1 when @running_time is -1 or when it is not inside @segment. 332 */ 333 public ulong toPosition(GstFormat format, ulong runningTime) 334 { 335 return gst_segment_to_position(gstSegment, format, runningTime); 336 } 337 338 /** 339 * Translate @position to the total running time using the currently configured 340 * segment. Position is a value between @segment start and stop time. 341 * 342 * This function is typically used by elements that need to synchronize to the 343 * global clock in a pipeline. The running time is a constantly increasing value 344 * starting from 0. When gst_segment_init() is called, this value will reset to 345 * 0. 346 * 347 * This function returns -1 if the position is outside of @segment start and stop. 348 * 349 * Params: 350 * format = the format of the segment. 351 * position = the position in the segment 352 * 353 * Return: the position as the total running time or -1 when an invalid position 354 * was given. 355 */ 356 public ulong toRunningTime(GstFormat format, ulong position) 357 { 358 return gst_segment_to_running_time(gstSegment, format, position); 359 } 360 361 /** 362 * Translate @position to the total running time using the currently configured 363 * segment. Compared to gst_segment_to_running_time() this function can return 364 * negative running-time. 365 * 366 * This function is typically used by elements that need to synchronize buffers 367 * against the clock or eachother. 368 * 369 * @position can be any value and the result of this function for values outside 370 * of the segment is extrapolated. 371 * 372 * When 1 is returned, @position resulted in a positive running-time returned 373 * in @running_time. 374 * 375 * When this function returns -1, the returned @running_time should be negated 376 * to get the real negative running time. 377 * 378 * Params: 379 * format = the format of the segment. 380 * position = the position in the segment 381 * runningTime = result running-time 382 * 383 * Return: a 1 or -1 on success, 0 on failure. 384 * 385 * Since: 1.6 386 */ 387 public int toRunningTimeFull(GstFormat format, ulong position, ulong* runningTime) 388 { 389 return gst_segment_to_running_time_full(gstSegment, format, position, runningTime); 390 } 391 392 /** 393 * Translate @position to stream time using the currently configured 394 * segment. The @position value must be between @segment start and 395 * stop value. 396 * 397 * This function is typically used by elements that need to operate on 398 * the stream time of the buffers it receives, such as effect plugins. 399 * In those use cases, @position is typically the buffer timestamp or 400 * clock time that one wants to convert to the stream time. 401 * The stream time is always between 0 and the total duration of the 402 * media stream. 403 * 404 * Params: 405 * format = the format of the segment. 406 * position = the position in the segment 407 * 408 * Return: the position in stream_time or -1 when an invalid position 409 * was given. 410 */ 411 public ulong toStreamTime(GstFormat format, ulong position) 412 { 413 return gst_segment_to_stream_time(gstSegment, format, position); 414 } 415 }