Menu
▾
▴
[Gtk2hs-commit] (main branch): gstreamer: M.S.G.Core.Buffer: add documentation, API improvements
|
From: Duncan C. <dun...@wo...> - 2007-11-10 18:17:45
|
Sat Nov 3 06:55:04 PDT 2007 Peter Gavin <pg...@gm...>
* gstreamer: M.S.G.Core.Buffer: add documentation, API improvements
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 29
+--
+-- Data-passing buffer type, supporting sub-buffers.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 33
+-- * Types
+
+ -- | Buffers are the basic unit of data transfer in GStreamer. The
+ -- 'Buffer' type provides all the state necessary to define a
+ -- region of memory as part of a stream. Sub-buffers are also
+ -- supported, allowing a smaller region of a buffer to become its
+ -- own buffer, with mechansims in place to ensure that neither
+ -- memory space goes away prematurely.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 44
- toBuffer,
+ -- Safely downcast an 'Object' to a 'Bin'.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 46
+ -- Upcast to a 'Bin'.
+ toBuffer,
+ -- See if an 'Object' is a 'Bin'.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 50
+
+-- * Buffer Operations
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 62
+ unsafeBufferGetPtrM,
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 78
- bufferDurationIsValid,
- bufferDurationIsValidM,
- bufferTimestampIsValid,
- bufferTimestampIsValidM,
- bufferOffsetIsValid,
- bufferOffsetIsValidM,
- bufferOffsetEndIsValid,
- bufferOffsetEndIsValidM,
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 87
- bufferStampM,
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 104
-
+-- | Get the flags set on this buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 110
+-- | Get the flags set on the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 115
+-- | Set flags on the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 121
+-- | Unset flags on the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 127
+-- | Get the size of the buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 141
+-- | Get the size of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 148
+-- | Make an O(n) copy of the buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 162
+-- | Make an O(n) copy of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 175
+-- | Store an O(n) copy of the provided data in the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 191
+-- | Get a raw pointer to the internal data area for the current
+-- buffer. The pointer may be used to write into the data area if
+-- desired. This function is unsafe in that the pointer should not
+-- be used once the buffer is returned.
+unsafeBufferGetPtrM :: BufferClass bufferT
+ => MiniObjectM bufferT (Ptr Word8)
+unsafeBufferGetPtrM =
+ MiniObjectM $ \buffer ->
+ liftM castPtr $
+ withMiniObject buffer $
+ {# get GstBuffer->data #} . castPtr
+
+marshalGetNum :: (BufferClass bufferT, Integral intT, Num numT)
+ => (Ptr Buffer -> IO intT)
+ -> numT
+ -> bufferT
+ -> Maybe numT
+marshalGetNum getAction invalid buffer =
+ let n = fromIntegral $ unsafePerformIO $
+ withMiniObject (toBuffer buffer) getAction
+ in if n /= invalid
+ then Just n
+ else Nothing
+
+marshalGetNumM :: (BufferClass bufferT, Integral intT, Num numT)
+ => (Ptr Buffer -> IO intT)
+ -> numT
+ -> MiniObjectM bufferT (Maybe numT)
+marshalGetNumM getAction invalid =
+ marshalBufferM $ \bufferPtr -> do
+ n <- liftM fromIntegral $ getAction bufferPtr
+ return $ if n /= invalid
+ then Just n
+ else Nothing
+
+marshalSetNumM :: (BufferClass bufferT, Integral intT, Num numT)
+ => (Ptr Buffer -> numT -> IO ())
+ -> intT
+ -> Maybe intT
+ -> MiniObjectM bufferT ()
+marshalSetNumM setAction invalid nM =
+ let n = case nM of
+ Just n' -> n'
+ Nothing -> invalid
+ in marshalBufferM $ flip setAction $ fromIntegral n
+
+-- | Get the timestamp for this buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 240
- -> ClockTime
-bufferGetTimestamp buffer =
- fromIntegral $ unsafePerformIO $
- withMiniObject buffer {# get GstBuffer->timestamp #}
+ -> Maybe ClockTime
+bufferGetTimestamp =
+ marshalGetNum {# get GstBuffer->timestamp #} clockTimeNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 244
+-- | Get the timestamp of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 246
- => MiniObjectM bufferT ClockTime
+ => MiniObjectM bufferT (Maybe ClockTime)
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 248
- liftM fromIntegral $
- marshalBufferM {# get GstBuffer->timestamp #}
+ marshalGetNumM {# get GstBuffer->timestamp #} clockTimeNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 250
+-- | Set the timestamp of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 252
- => ClockTime
+ => Maybe ClockTime
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 254
-bufferSetTimestampM timestamp =
- marshalBufferM $ flip {# set GstBuffer->timestamp #} $ fromIntegral timestamp
+bufferSetTimestampM =
+ marshalSetNumM {# set GstBuffer->timestamp #} clockTimeNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 257
+-- | Get the duration of the buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 260
- -> ClockTime
-bufferGetDuration buffer =
- fromIntegral $ unsafePerformIO $
- withMiniObject buffer {# get GstBuffer->duration #}
+ -> Maybe ClockTime
+bufferGetDuration =
+ marshalGetNum {# get GstBuffer->duration #} clockTimeNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 264
+-- | Get the duration of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 266
- => MiniObjectM bufferT ClockTime
+ => MiniObjectM bufferT (Maybe ClockTime)
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 268
- liftM fromIntegral $
- marshalBufferM {# get GstBuffer->duration #}
+ marshalGetNumM {# get GstBuffer->duration #} clockTimeNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 270
+-- | Set the duration of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 272
- => ClockTime
+ => Maybe ClockTime
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 274
-bufferSetDurationM duration =
- marshalBufferM $
- flip {# set GstBuffer->duration #} $ fromIntegral duration
+bufferSetDurationM =
+ marshalSetNumM {# set GstBuffer->duration #} clockTimeNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 277
+-- | Get the caps of the buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 286
+-- | Get the caps of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 294
+-- | Set the caps of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 296
- => Caps
+ => Maybe Caps
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 298
-bufferSetCapsM caps =
+bufferSetCapsM capsM =
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 300
- {# call buffer_set_caps #} (toBuffer buffer) caps
+ {# call buffer_set_caps #} (toBuffer buffer) $
+ case capsM of
+ Just caps -> caps
+ Nothing -> Caps nullForeignPtr
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 305
+-- | Get the offset of the buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 308
- -> Word64
-bufferGetOffset buffer =
- fromIntegral $ unsafePerformIO $
- withMiniObject buffer {# get GstBuffer->offset #}
+ -> Maybe Word64
+bufferGetOffset =
+ marshalGetNum {# get GstBuffer->offset #} bufferOffsetNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 312
+-- | Get the start offset of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 314
- => MiniObjectM bufferT Word64
+ => MiniObjectM bufferT (Maybe Word64)
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 316
- liftM fromIntegral $
- marshalBufferM {# get GstBuffer->offset #}
+ marshalGetNumM {# get GstBuffer->offset #} bufferOffsetNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 318
+-- | Set the start offset of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 320
- => Word64
+ => Maybe Word64
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 322
-bufferSetOffsetM offset =
- marshalBufferM $
- flip {# set GstBuffer->offset #} $ fromIntegral offset
+bufferSetOffsetM =
+ marshalSetNumM {# set GstBuffer->offset #} bufferOffsetNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 325
+-- | Get the end offset of the buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 328
- -> Word64
-bufferGetOffsetEnd buffer =
- fromIntegral $ unsafePerformIO $
- withMiniObject buffer {# get GstBuffer->offset_end #}
+ -> Maybe Word64
+bufferGetOffsetEnd =
+ marshalGetNum {# get GstBuffer->offset_end #} bufferOffsetNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 332
+-- | Get the end offset of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 334
- => MiniObjectM bufferT Word64
+ => MiniObjectM bufferT (Maybe Word64)
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 336
- liftM fromIntegral $
- marshalBufferM {# get GstBuffer->offset_end #}
+ marshalGetNumM {# get GstBuffer->offset_end #} bufferOffsetNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 338
+-- | Set the end offset of the current buffer.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 340
- => Word64
+ => Maybe Word64
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 342
-bufferSetOffsetEndM offsetEnd =
- marshalBufferM $
- flip {# set GstBuffer->offset_end #} $ fromIntegral offsetEnd
-
-bufferDurationIsValid :: BufferClass bufferT
- => bufferT
- -> Bool
-bufferDurationIsValid =
- (/= clockTimeNone) . bufferGetOffset
-
-bufferDurationIsValidM :: BufferClass bufferT
- => MiniObjectM bufferT Bool
-bufferDurationIsValidM =
- liftM (/= clockTimeNone) $ bufferGetDurationM
-
-bufferTimestampIsValid :: BufferClass bufferT
- => bufferT
- -> Bool
-bufferTimestampIsValid =
- (/= clockTimeNone) . bufferGetTimestamp
-
-bufferTimestampIsValidM :: BufferClass bufferT
- => MiniObjectM bufferT Bool
-bufferTimestampIsValidM =
- liftM (/= clockTimeNone) $ bufferGetTimestampM
-
-bufferOffsetIsValid :: BufferClass bufferT
- => bufferT
- -> Bool
-bufferOffsetIsValid =
- (/= bufferOffsetNone) . bufferGetOffset
-
-bufferOffsetIsValidM :: BufferClass bufferT
- => MiniObjectM bufferT Bool
-bufferOffsetIsValidM =
- liftM (/= bufferOffsetNone) $ bufferGetOffsetM
-
-bufferOffsetEndIsValid :: BufferClass bufferT
- => bufferT
- -> Bool
-bufferOffsetEndIsValid =
- (/= bufferOffsetNone) . bufferGetOffsetEnd
-
-bufferOffsetEndIsValidM :: BufferClass bufferT
- => MiniObjectM bufferT Bool
-bufferOffsetEndIsValidM =
- liftM (/= bufferOffsetNone) $ bufferGetOffsetEndM
+bufferSetOffsetEndM =
+ marshalSetNumM {# set GstBuffer->offset_end #} bufferOffsetNone
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 345
+-- | Return 'True' if the buffer marks a discontinuity in a stream, or
+-- 'False' otherwise. This typically occurs after a seek or a
+-- dropped buffer from a live or network source.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 354
+-- | Return 'True' if the current buffer marks a discontinuity in a
+-- stream, or 'False' otherwise.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 361
-bufferCreateEmpty :: MiniObjectM Buffer a
- -> IO (Buffer, a)
+-- | Create an empty buffer and mutates it according to the given
+-- action. Once this function returns, the buffer is immutable.
+bufferCreateEmpty :: MiniObjectM Buffer a -- ^ the mutating action
+ -> IO (Buffer, a) -- ^ the new buffer and the action's result
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 368
-bufferCreate :: Word
- -> MiniObjectM Buffer a
- -> IO (Buffer, a)
+-- | Create and mutate a buffer of the given size.
+bufferCreate :: Word -- ^ the size of the buffer to be created
+ -> MiniObjectM Buffer a -- ^ the mutating action
+ -> IO (Buffer, a) -- ^ the new buffer and the action's result
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 376
+-- | Create a sub-buffer from an existing buffer with the given offset
+-- and size. This sub-buffer uses the actual memory space of the
+-- parent buffer. Thus function will copy the offset and timestamp
+-- fields when the offset is 0. Otherwise, they will both be set to
+-- 'Nothing'. If the offset is 0 and the size is the total size of
+-- the parent, the duration and offset end fields are also
+-- copied. Otherwise they will be set to 'Nothing'.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 384
- => bufferT
- -> Word
- -> Word
- -> MiniObjectM Buffer a
- -> IO (Buffer, a)
+ => bufferT -- ^ the parent buffer
+ -> Word -- ^ the offset
+ -> Word -- ^ the size
+ -> IO (Maybe Buffer) -- ^ the new sub-buffer
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 389
- marshalMiniObjectModify $
- {# call buffer_create_sub #} (toBuffer parent)
- (fromIntegral offset)
- (fromIntegral size)
+ {# call buffer_create_sub #} (toBuffer parent)
+ (fromIntegral offset)
+ (fromIntegral size) >>=
+ maybePeek takeMiniObject
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 394
+-- | Return 'True' if 'bufferSpan' can be done without copying the
+-- data, or 'False' otherwise.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 405
+-- | Create a new buffer that consists of a span across the given
+-- buffers. Logically, the buffers are concatenated to make a larger
+-- buffer, and a new buffer is created at the given offset and with
+-- the given size.
+-- [_$_]
+-- If the two buffers are children of the same larger buffer, and
+-- are contiguous, no copying is necessary. You can use
+-- 'bufferIsSpanFast' to determine if copying is needed.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 414
- => bufferT1
- -> Word32
- -> bufferT2
- -> Word32
- -> Maybe Buffer
+ => bufferT1 -- ^ the first buffer
+ -> Word32 -- ^ the offset into the concatenated buffer
+ -> bufferT2 -- ^ the second buffer
+ -> Word32 -- ^ the length of the final buffer
+ -> Maybe Buffer -- ^ the spanning buffer, or 'Nothing' if
+ -- the arguments are invalid
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 428
-bufferStampM :: (BufferClass srcT, BufferClass destT)
- => srcT
- -> MiniObjectM destT ()
-bufferStampM src =
- MiniObjectM $ \dest ->
- {# call buffer_stamp #} (toBuffer dest)
- (toBuffer src)
-
+-- | Concatenate two buffers. If the buffers point to contiguous memory
+-- areas, no copying will occur.
hunk ./gstreamer/Media/Streaming/GStreamer/Core/Buffer.chs.pp 431
- => bufferT1
- -> bufferT2
- -> Buffer
+ => bufferT1 -- ^ a buffer
+ -> bufferT2 -- ^ a buffer
+ -> Buffer -- ^ the concatenation of the buffers
|